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