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