README.synology

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