README.synology

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