Debian Codegraph @

upstream/mageia-cauldron/man1/perlsynology.1

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