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|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
  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.18.4 on DSM-6.0.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.18.4.
  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 and RS815, Intel Atom x64).
  37
  38 =head2 Setting up the build environment
  39
  40 =head3 DSM 5
  41
  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
 125   cd /opt/powerpc-linux-gnuspe/lib  (or
 126                                     /opt/arm-none-linux-gnueabi/lib)
 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
 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
 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
 207 =item F<ext/DynaLoader/t/DynaLoader.t>
 208
 209 One subtest fails due to the uncommon structure of the Synology file
 210 system. The file F</lib/glibc.so> is missing.
 211
 212 B<WARNING:> Do not symlink F</lib/glibc.so.6> to F</lib/glibc.so> or
 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
 268 June 2016, for Synology DSM 5.1.5022 and DSM 6.0.1-7393.
 269
 270 =head1 AUTHOR
 271
 272 Johan Vromans <jvromans@squirrel.nl>
 273 H. Merijn Brand <h.m.brand@xs4all.nl>
 274
 275 =cut