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