Commit | Line | Data |
---|---|---|
58534900 MB |
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 |