Debian Codegraph @

upstream/debian-unstable/man1/perlsynology.1

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