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