| 1 | If you read this file _as_is_, just ignore the funny characters you see. |
| 2 | It is written in the POD format (see pod/perlpod.pod) which is specially |
| 3 | designed to be readable as is. But if you have been into Perl you |
| 4 | probably already know this. |
| 5 | |
| 6 | =head1 NAME |
| 7 | |
| 8 | perlsynology - Perl 5 on Synology DSM systems |
| 9 | |
| 10 | =head1 DESCRIPTION |
| 11 | |
| 12 | Synology manufactures a vast number of Network Attached Storage (NAS) |
| 13 | devices that are very popular in large organisations as well as small |
| 14 | businesses and homes. |
| 15 | |
| 16 | The NAS systems are equipped with Synology Disk Storage Manager (DSM), |
| 17 | which is a trimmed-down Linux system enhanced with several tools for |
| 18 | managing the NAS. There are several flavours of hardware: Marvell |
| 19 | Armada (ARMv5te, ARMv7l), Intel Atom (i686, x86_64), Freescale QorIQ |
| 20 | (PPC), and more. For a full list see the |
| 21 | L<Synology FAQ|http://forum.synology.com/wiki/index.php/What_kind_of_CPU_does_my_NAS_have>. |
| 22 | |
| 23 | Since it is based on Linux, the NAS can run many popular Linux |
| 24 | software packages, including Perl. In fact, Synology provides a |
| 25 | ready-to-install package for Perl, albeit version 5.8.6 which should |
| 26 | be considered very old. |
| 27 | |
| 28 | There is an active user community that provides many software packages |
| 29 | for the Synology DSM systems; at the time of writing this document |
| 30 | they provide Perl version 5.8.8. |
| 31 | |
| 32 | This document describes various features of Synology DSM operating |
| 33 | system that will affect how Perl 5 (hereafter just Perl) is |
| 34 | configured, compiled and/or runs. It has been compiled and verified by |
| 35 | Johan Vromans for the Synology DS413 (QorIQ), with feedback from |
| 36 | H.Merijn Brand (DS213, ARMv5te). |
| 37 | |
| 38 | =head2 Setting up the build environment |
| 39 | |
| 40 | As DSM is a trimmed-down Linux system, it lacks many of the tools and |
| 41 | libraries commonly found on Linux. The basic tools like sh, cp, rm, |
| 42 | etc. are implemented using |
| 43 | L<BusyBox|http://en.wikipedia.org/wiki/BusyBox>. |
| 44 | |
| 45 | =over 4 |
| 46 | |
| 47 | =item * |
| 48 | |
| 49 | Using your favourite browser open the DSM management page and start |
| 50 | the Package Center. |
| 51 | |
| 52 | =item * |
| 53 | |
| 54 | If you want to smoke test Perl, install C<Perl>. |
| 55 | |
| 56 | =item * |
| 57 | |
| 58 | In Settings, add the following Package Sources: |
| 59 | |
| 60 | http://www.cphub.net |
| 61 | http://packages.quadrat4.de |
| 62 | |
| 63 | =item * |
| 64 | |
| 65 | Still in Settings, in Channel Update, select Beta Channel. |
| 66 | |
| 67 | =item * |
| 68 | |
| 69 | Press Refresh. In the left panel the item "Community" will appear. |
| 70 | Click it. Select "Bootstrap Installer Beta" and install it. |
| 71 | |
| 72 | =item * |
| 73 | |
| 74 | Likewise, install "iPKGui Beta". |
| 75 | |
| 76 | The application window should now show an icon for iPKGui. |
| 77 | |
| 78 | =item * |
| 79 | |
| 80 | Start iPKGui. Install the packages C<make>, C<gcc> and C<coreutils>. |
| 81 | |
| 82 | If you want to smoke test Perl, install C<patch>. |
| 83 | |
| 84 | =back |
| 85 | |
| 86 | The next step is to add some symlinks to system libraries. For |
| 87 | example, the development software expect a library C<libm.so> that |
| 88 | normally is a symlink to C<libm.so.6>. Synology only provides the |
| 89 | latter and not the symlink. |
| 90 | |
| 91 | Here the actual architecture of the Synology system matters. You have |
| 92 | to find out where the gcc libraries have been installed. Look in /opt |
| 93 | for a directory similar to arm-none-linux-gnueab or |
| 94 | powerpc-linux-gnuspe. In the instructions below I'll use |
| 95 | powerpc-linux-gnuspe as an example. |
| 96 | |
| 97 | =over 4 |
| 98 | |
| 99 | =item * |
| 100 | |
| 101 | On the DSM management page start the Control Panel. |
| 102 | |
| 103 | =item * |
| 104 | |
| 105 | Click Terminal, and enable SSH service. |
| 106 | |
| 107 | =item * |
| 108 | |
| 109 | Close Terminal and the Control Panel. |
| 110 | |
| 111 | =item * |
| 112 | |
| 113 | Open a shell on the Synology using ssh and become root. |
| 114 | |
| 115 | =item * |
| 116 | |
| 117 | Execute the following commands: |
| 118 | |
| 119 | cd /lib |
| 120 | ln -s libm.so.6 libm.so |
| 121 | ln -s libcrypt.so.1 libcrypt.so |
| 122 | ln -s libdl.so.2 libdl.so |
| 123 | cd /opt/powerpc-linux-gnuspe/lib |
| 124 | ln -s /lib/libdl.so.2 libdl.so |
| 125 | |
| 126 | =back |
| 127 | |
| 128 | B<WARNING:> When you perform a system software upgrade, these links |
| 129 | will disappear and need to be re-established. |
| 130 | |
| 131 | =head2 Compiling Perl 5 |
| 132 | |
| 133 | When the build environment has been set up, building and testing Perl |
| 134 | is straightforward. The only thing you need to do is download the |
| 135 | sources as usual, and add a file Policy.sh as follows: |
| 136 | |
| 137 | # Administrivia. |
| 138 | perladmin="your.email@goes.here" |
| 139 | |
| 140 | # Install Perl in a tree in /opt/perl instead of /opt/bin. |
| 141 | prefix=/opt/perl |
| 142 | |
| 143 | # Select the compiler. Note that there is no 'cc' alias or link. |
| 144 | cc=gcc |
| 145 | |
| 146 | # Build flags. |
| 147 | ccflags="-DDEBUGGING" |
| 148 | |
| 149 | # Library and include paths. |
| 150 | libpth="/lib" |
| 151 | locincpth="/opt/include" |
| 152 | loclibpth="/lib" |
| 153 | |
| 154 | You may want to create the destination directory and give it the right |
| 155 | permissions before installing, thus eliminating the need to build Perl |
| 156 | as a super user. |
| 157 | |
| 158 | In the directory where you unpacked the sources, issue the familiar |
| 159 | commands: |
| 160 | |
| 161 | ./Configure -des |
| 162 | make |
| 163 | make test |
| 164 | make install |
| 165 | |
| 166 | =head2 Known problems |
| 167 | |
| 168 | =head3 Configure |
| 169 | |
| 170 | No known problems yet |
| 171 | |
| 172 | =head3 Build |
| 173 | |
| 174 | =over 4 |
| 175 | |
| 176 | =item Error message "No error definitions found". |
| 177 | |
| 178 | This error is generated when it is not possible to find the local |
| 179 | definitions for error codes, due to the uncommon structure of the |
| 180 | Synology file system. |
| 181 | |
| 182 | This error was fixed in the Perl development git for version 5.19, |
| 183 | commit 7a8f1212e5482613c8a5b0402528e3105b26ff24. |
| 184 | |
| 185 | =back |
| 186 | |
| 187 | =head3 Failing tests |
| 188 | |
| 189 | =over 4 |
| 190 | |
| 191 | =item C<ext/DynaLoader/t/DynaLoader.t> |
| 192 | |
| 193 | One subtest fails due to the uncommon structure of the Synology file |
| 194 | system. The file C</lib/glibc.so> is missing. |
| 195 | |
| 196 | B<WARNING:> Do not symlink C</lib/glibc.so.6> to C</lib/glibc.so> or |
| 197 | some system components will start to fail. |
| 198 | |
| 199 | =back |
| 200 | |
| 201 | =head2 Smoke testing Perl 5 |
| 202 | |
| 203 | If building completes successfully, you can set up smoke testing as |
| 204 | described in the Test::Smoke documentation. |
| 205 | |
| 206 | For smoke testing you need a running Perl. You can either install the |
| 207 | Synology supplied package for Perl 5.8.6, or build and install your |
| 208 | own, much more recent version. |
| 209 | |
| 210 | Note that I could not run successful smokes when initiated by the |
| 211 | Synology Task Scheduler. I resorted to initiating the smokes via a |
| 212 | cron job run on another system, using ssh: |
| 213 | |
| 214 | ssh nas1 wrk/Test-Smoke/smoke/smokecurrent.sh |
| 215 | |
| 216 | =head3 Local patches |
| 217 | |
| 218 | When local patches are applied with smoke testing, the test driver |
| 219 | will automatically request regeneration of certain tables after the |
| 220 | patches are applied. The Synology supplied Perl 5.8.6 (at least on the |
| 221 | DS413) B<is NOT capable> of generating these tables. It will generate |
| 222 | opcodes with bogus values, causing the build to fail. |
| 223 | |
| 224 | You can prevent regeneration by adding the setting |
| 225 | |
| 226 | 'flags' => 0, |
| 227 | |
| 228 | to the smoke config, or by adding another patch that inserts |
| 229 | |
| 230 | exit 0 if $] == 5.008006; |
| 231 | |
| 232 | in the beginning of the C<regen.pl> program. |
| 233 | |
| 234 | =head2 Adding libraries |
| 235 | |
| 236 | The above procedure describes a basic environment and hence results in |
| 237 | a basic Perl. If you want to add additional libraries to Perl, you may |
| 238 | need some extra settings. |
| 239 | |
| 240 | For example, the basic Perl does not have any of the DB libraries (db, |
| 241 | dbm, ndbm, gdsm). You can add these using iPKGui, however, you need to |
| 242 | set environment variable LD_LIBRARY_PATH to the appropriate value: |
| 243 | |
| 244 | LD_LIBRARY_PATH=/lib:/opt/lib |
| 245 | export LD_LIBRARY_PATH |
| 246 | |
| 247 | This setting needs to be in effect while Perl is built, but also when |
| 248 | the programs are run. |
| 249 | |
| 250 | =head1 REVISION |
| 251 | |
| 252 | November 2013, for Synology DSM 4.3.3810. |
| 253 | |
| 254 | =head1 AUTHOR |
| 255 | |
| 256 | Johan Vromans <jvromans@squirrel.nl> |
| 257 | |
| 258 | =head1 THANKS |
| 259 | |
| 260 | H. Merijn Brand <h.m.brand@xs4all.nl> |
| 261 | |
| 262 | =cut |