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