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.
8 perlsynology - Perl 5 on Synology DSM systems
12 Synology manufactures a vast number of Network Attached Storage (NAS)
13 devices that are very popular in large organisations as well as small
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 (ARMv5tel, ARMv7l), Intel Atom (i686, x86_64), Freescale QorIQ
20 (PPC), and more. For a full list see the
21 L<Synology FAQ|https://forum.synology.com/wiki/index.php/What_kind_of_CPU_does_my_NAS_have>.
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, depending on the version of DSM
26 the installed perl ranges from 5.8.6 on DSM-4.3 to 5.24.0 on DSM-6.1.
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.24.1.
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, ARMv5tel and RS815, Intel Atom x64).
38 =head2 Setting up the build environment
42 As DSM is a trimmed-down Linux system, it lacks many of the tools and
43 libraries commonly found on Linux. The basic tools like sh, cp, rm,
44 etc. are implemented using
45 L<BusyBox|https://en.wikipedia.org/wiki/BusyBox>.
51 Using your favourite browser open the DSM management page and start
56 If you want to smoke test Perl, install C<Perl>.
60 In Settings, add the following Package Sources:
63 http://packages.quadrat4.de
67 Still in Settings, in Channel Update, select Beta Channel.
71 Press Refresh. In the left panel the item "Community" will appear.
72 Click it. Select "Bootstrap Installer Beta" and install it.
76 Likewise, install "iPKGui Beta".
78 The application window should now show an icon for iPKGui.
82 Start iPKGui. Install the packages C<make>, C<gcc> and C<coreutils>.
84 If you want to smoke test Perl, install C<patch>.
88 The next step is to add some symlinks to system libraries. For
89 example, the development software expect a library C<libm.so> that
90 normally is a symlink to C<libm.so.6>. Synology only provides the
91 latter and not the symlink.
93 Here the actual architecture of the Synology system matters. You have
94 to find out where the gcc libraries have been installed. Look in /opt
95 for a directory similar to arm-none-linux-gnueab or
96 powerpc-linux-gnuspe. In the instructions below I'll use
97 powerpc-linux-gnuspe as an example.
103 On the DSM management page start the Control Panel.
107 Click Terminal, and enable SSH service.
111 Close Terminal and the Control Panel.
115 Open a shell on the Synology using ssh and become root.
119 Execute the following commands:
122 ln -s libm.so.6 libm.so
123 ln -s libcrypt.so.1 libcrypt.so
124 ln -s libdl.so.2 libdl.so
125 cd /opt/powerpc-linux-gnuspe/lib (or
126 /opt/arm-none-linux-gnueabi/lib)
127 ln -s /lib/libdl.so.2 libdl.so
131 B<WARNING:> When you perform a system software upgrade, these links
132 will disappear and need to be re-established.
136 Using iPkg has been deprecated on DSM 6, but an alternative is available
137 for DSM 6: entware/opkg. For instructions on how to use that, please read
138 L<Install Entware-ng on Synology NAS|https://github.com/Entware-ng/Entware-ng/wiki/Install-on-Synology-NAS>
140 That sadly does not (yet) work on QorIQ. At the moment of writing, the
141 supported architectures are armv5, armv7, mipsel, wl500g, x86_32, and x86_64.
142 Check L<here|https://pkg.entware.net/binaries/> for supported platforms.
144 Entware-ng comes with a precompiled 5.24.1 (June 2017) that allowes
145 building shared XS code. Note that this installation does B<not> use
146 a site_perl folder. The available C<cpan> works. If all required
147 development packages are installed too, also for XS.
149 =head2 Compiling Perl 5
151 When the build environment has been set up, building and testing Perl
152 is straightforward. The only thing you need to do is download the
153 sources as usual, and add a file Policy.sh as follows:
156 perladmin="your.email@goes.here"
158 # Install Perl in a tree in /opt/perl instead of /opt/bin.
161 # Select the compiler. Note that there is no 'cc' alias or link.
165 ccflags="-DDEBUGGING"
167 # Library and include paths.
169 locincpth="/opt/include"
172 You may want to create the destination directory and give it the right
173 permissions before installing, thus eliminating the need to build Perl
176 In the directory where you unpacked the sources, issue the familiar
184 =head2 Known problems
188 No known problems yet
194 =item Error message "No error definitions found".
196 This error is generated when it is not possible to find the local
197 definitions for error codes, due to the uncommon structure of the
198 Synology file system.
200 This error was fixed in the Perl development git for version 5.19,
201 commit 7a8f1212e5482613c8a5b0402528e3105b26ff24.
209 =item F<ext/DynaLoader/t/DynaLoader.t>
211 One subtest fails due to the uncommon structure of the Synology file
212 system. The file F</lib/glibc.so> is missing.
214 B<WARNING:> Do not symlink F</lib/glibc.so.6> to F</lib/glibc.so> or
215 some system components will start to fail.
219 =head2 Smoke testing Perl 5
221 If building completes successfully, you can set up smoke testing as
222 described in the Test::Smoke documentation.
224 For smoke testing you need a running Perl. You can either install the
225 Synology supplied package for Perl 5.8.6, or build and install your
226 own, much more recent version.
228 Note that I could not run successful smokes when initiated by the
229 Synology Task Scheduler. I resorted to initiating the smokes via a
230 cron job run on another system, using ssh:
232 ssh nas1 wrk/Test-Smoke/smoke/smokecurrent.sh
236 When local patches are applied with smoke testing, the test driver
237 will automatically request regeneration of certain tables after the
238 patches are applied. The Synology supplied Perl 5.8.6 (at least on the
239 DS413) B<is NOT capable> of generating these tables. It will generate
240 opcodes with bogus values, causing the build to fail.
242 You can prevent regeneration by adding the setting
246 to the smoke config, or by adding another patch that inserts
248 exit 0 if $] == 5.008006;
250 in the beginning of the C<regen.pl> program.
252 =head2 Adding libraries
254 The above procedure describes a basic environment and hence results in
255 a basic Perl. If you want to add additional libraries to Perl, you may
256 need some extra settings.
258 For example, the basic Perl does not have any of the DB libraries (db,
259 dbm, ndbm, gdsm). You can add these using iPKGui, however, you need to
260 set environment variable LD_LIBRARY_PATH to the appropriate value:
262 LD_LIBRARY_PATH=/lib:/opt/lib
263 export LD_LIBRARY_PATH
265 This setting needs to be in effect while Perl is built, but also when
266 the programs are run.
270 June 2017, for Synology DSM 5.1.5022 and DSM 6.1-15101-4.
274 Johan Vromans <jvromans@squirrel.nl>
275 H. Merijn Brand <h.m.brand@xs4all.nl>