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 MB |
20 | (PPC), and more. For a full list see the |
21 | L<Synology FAQ|http://forum.synology.com/wiki/index.php/What_kind_of_CPU_does_my_NAS_have>. | |
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 |
7351909a | 26 | the installed perl ranges from 5.8.6 on DSM-4.3 to 5.18.4 on DSM-6.0.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 | |
5f9bdaf6 | 30 | they provide Perl version 5.18.4. |
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 | |
45 | L<BusyBox|http://en.wikipedia.org/wiki/BusyBox>. | |
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 | ||
62 | http://www.cphub.net | |
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 | |
141 | supported architectures are armv5, armv7, mipsel, x86_32 and x86_64. | |
142 | ||
143 | Entware-ng comes with a precompiled 5.22.1 (June 2016) that allowes | |
144 | building shared XS code. Note that this installation does B<not> use | |
145 | a site_perl folder. | |
146 | ||
58534900 MB |
147 | =head2 Compiling Perl 5 |
148 | ||
149 | When the build environment has been set up, building and testing Perl | |
150 | is straightforward. The only thing you need to do is download the | |
151 | sources as usual, and add a file Policy.sh as follows: | |
152 | ||
153 | # Administrivia. | |
154 | perladmin="your.email@goes.here" | |
155 | ||
156 | # Install Perl in a tree in /opt/perl instead of /opt/bin. | |
157 | prefix=/opt/perl | |
158 | ||
159 | # Select the compiler. Note that there is no 'cc' alias or link. | |
160 | cc=gcc | |
161 | ||
162 | # Build flags. | |
163 | ccflags="-DDEBUGGING" | |
164 | ||
165 | # Library and include paths. | |
166 | libpth="/lib" | |
167 | locincpth="/opt/include" | |
168 | loclibpth="/lib" | |
169 | ||
170 | You may want to create the destination directory and give it the right | |
171 | permissions before installing, thus eliminating the need to build Perl | |
172 | as a super user. | |
173 | ||
174 | In the directory where you unpacked the sources, issue the familiar | |
175 | commands: | |
176 | ||
177 | ./Configure -des | |
178 | make | |
179 | make test | |
180 | make install | |
181 | ||
182 | =head2 Known problems | |
183 | ||
184 | =head3 Configure | |
185 | ||
186 | No known problems yet | |
187 | ||
188 | =head3 Build | |
189 | ||
190 | =over 4 | |
191 | ||
192 | =item Error message "No error definitions found". | |
193 | ||
194 | This error is generated when it is not possible to find the local | |
195 | definitions for error codes, due to the uncommon structure of the | |
196 | Synology file system. | |
197 | ||
198 | This error was fixed in the Perl development git for version 5.19, | |
199 | commit 7a8f1212e5482613c8a5b0402528e3105b26ff24. | |
200 | ||
201 | =back | |
202 | ||
203 | =head3 Failing tests | |
204 | ||
205 | =over 4 | |
206 | ||
a95b3d6a | 207 | =item F<ext/DynaLoader/t/DynaLoader.t> |
58534900 MB |
208 | |
209 | One subtest fails due to the uncommon structure of the Synology file | |
a95b3d6a | 210 | system. The file F</lib/glibc.so> is missing. |
58534900 | 211 | |
a95b3d6a | 212 | B<WARNING:> Do not symlink F</lib/glibc.so.6> to F</lib/glibc.so> or |
58534900 MB |
213 | some system components will start to fail. |
214 | ||
215 | =back | |
216 | ||
217 | =head2 Smoke testing Perl 5 | |
218 | ||
219 | If building completes successfully, you can set up smoke testing as | |
220 | described in the Test::Smoke documentation. | |
221 | ||
222 | For smoke testing you need a running Perl. You can either install the | |
223 | Synology supplied package for Perl 5.8.6, or build and install your | |
224 | own, much more recent version. | |
225 | ||
226 | Note that I could not run successful smokes when initiated by the | |
227 | Synology Task Scheduler. I resorted to initiating the smokes via a | |
228 | cron job run on another system, using ssh: | |
229 | ||
230 | ssh nas1 wrk/Test-Smoke/smoke/smokecurrent.sh | |
231 | ||
232 | =head3 Local patches | |
233 | ||
234 | When local patches are applied with smoke testing, the test driver | |
235 | will automatically request regeneration of certain tables after the | |
236 | patches are applied. The Synology supplied Perl 5.8.6 (at least on the | |
237 | DS413) B<is NOT capable> of generating these tables. It will generate | |
238 | opcodes with bogus values, causing the build to fail. | |
239 | ||
240 | You can prevent regeneration by adding the setting | |
241 | ||
242 | 'flags' => 0, | |
243 | ||
244 | to the smoke config, or by adding another patch that inserts | |
245 | ||
246 | exit 0 if $] == 5.008006; | |
247 | ||
248 | in the beginning of the C<regen.pl> program. | |
249 | ||
250 | =head2 Adding libraries | |
251 | ||
252 | The above procedure describes a basic environment and hence results in | |
253 | a basic Perl. If you want to add additional libraries to Perl, you may | |
254 | need some extra settings. | |
255 | ||
256 | For example, the basic Perl does not have any of the DB libraries (db, | |
257 | dbm, ndbm, gdsm). You can add these using iPKGui, however, you need to | |
258 | set environment variable LD_LIBRARY_PATH to the appropriate value: | |
259 | ||
260 | LD_LIBRARY_PATH=/lib:/opt/lib | |
261 | export LD_LIBRARY_PATH | |
262 | ||
263 | This setting needs to be in effect while Perl is built, but also when | |
264 | the programs are run. | |
265 | ||
266 | =head1 REVISION | |
267 | ||
7351909a | 268 | June 2016, for Synology DSM 5.1.5022 and DSM 6.0.1-7393. |
58534900 MB |
269 | |
270 | =head1 AUTHOR | |
271 | ||
272 | Johan Vromans <jvromans@squirrel.nl> | |
58534900 MB |
273 | H. Merijn Brand <h.m.brand@xs4all.nl> |
274 | ||
275 | =cut |