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