diff options
Diffstat (limited to 'upstream/fedora-rawhide/man1/perlsynology.1')
| -rw-r--r-- | upstream/fedora-rawhide/man1/perlsynology.1 | 373 |
1 files changed, 373 insertions, 0 deletions
diff --git a/upstream/fedora-rawhide/man1/perlsynology.1 b/upstream/fedora-rawhide/man1/perlsynology.1 new file mode 100644 index 00000000..e42f8852 --- /dev/null +++ b/upstream/fedora-rawhide/man1/perlsynology.1 @@ -0,0 +1,373 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLSYNOLOGY 1" +.TH PERLSYNOLOGY 1 2024-01-25 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlsynology \- Perl 5 on Synology DSM systems +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Synology manufactures a vast number of Network Attached Storage (NAS) +devices that are very popular in large organisations as well as small +businesses and homes. +.PP +The NAS systems are equipped with Synology Disk Storage Manager (DSM), +which is a trimmed-down Linux system enhanced with several tools for +managing the NAS. There are several flavours of hardware: Marvell +Armada (ARMv5tel, ARMv7l), Intel Atom (i686, x86_64), Freescale QorIQ +(PPC), and more. For a full list see the +Synology FAQ <https://kb.synology.com/en-global/DSM/tutorial/What_kind_of_CPU_does_my_NAS_have>. +.PP +Since it is based on Linux, the NAS can run many popular Linux +software packages, including Perl. In fact, Synology provides a +ready-to-install package for Perl, depending on the version of DSM +the installed perl ranges from 5.8.6 on DSM\-4.3 to 5.28.1 on DSM\-7.1. +.PP +There is an active user community that provides many software packages +for the Synology DSM systems; at the time of writing this document +they provide Perl version 5.28.1. +.PP +This document describes various features of Synology DSM operating +system that will affect how Perl 5 (hereafter just Perl) is +configured, compiled and/or runs. It has been compiled and verified by +Johan Vromans for the Synology DS413 (QorIQ), with feedback from +H.Merijn Brand (DS213: ARMv5tel, RS815: Intel Atom x64, and DS218+: +Celeron J3355). +.SS "Setting up the build environment" +.IX Subsection "Setting up the build environment" +\fIDSM 7\fR +.IX Subsection "DSM 7" +.PP +For a comfortable development environment, Entware is currently the only +viable solution. Just follow the detailed instructions on +Install Entware on Synology NAS <https://github.com/Entware/Entware/wiki/Install-on-Synology-NAS>. +supported architectures are armv5, armv7, mipsel, wl500g, x86_32, and x86_64. +Check here <https://pkg.entware.net/binaries/> for supported platforms. +.PP +That github link also shows what environments should be supported. +.PP +It was tested on DSM\-7.1 by H.Merijn Brand on a DS218+ and a DS220+ (both +Intel x64). +.PP +Entware comes with a precompiled 5.26.1 (Jan 2018) that allowes +building shared XS code. Note that this installation does \fBnot\fR use +a site_perl folder. The available \f(CW\*(C`cpan\*(C'\fR works. If all required +development packages are installed too, also for XS. +.PP +Installing perl from the Community package center: +.IP \(bu 4 +Using your favourite browser open the DSM management page and start +the Package Center. +.IP \(bu 4 +In Settings, add the following Package Sources: +.Sp +.Vb 2 +\& Name: Community +\& Location: https://synopackage.com/repository/spk/All +.Ve +.IP \(bu 4 +Still in Settings, in Channel Update, select Beta Channel. +.PP +To complete the development environment, install make and gcc +.PP +.Vb 1 +\& ds220# opkg install make gcc +.Ve +.PP +Then, optionally, make sure you use the more recent bash and gawk. +.PP +.Vb 4 +\& ds220# opkg install bash gawk +\& ds220# cd /usr/bin +\& ds220# mv bash bash.syno +\& ds220# ln \-s /opt/bin/bash . +.Ve +.PP +In order to have Configure find the required libraries +.PP +.Vb 8 +\& ds220# cd /opt/lib +\& ds220# ln \-s libcrypt.so.? libcrypt.so +\& ds220# ln \-s libdl.so.? libdl.so +\& ds220# ln \-s libgdbm.so.? libgdbm.so +\& ds220# ln \-s libgdbm_compat.so.? libgdbm_compat.so +\& ds220# ln \-s libm.so.? libm.so +\& ds220# ln \-s libpthread.so.? libpthread.so +\& ds220# ln \-s libutil.so.? libutil.so +.Ve +.PP +\fIDSM 6\fR +.IX Subsection "DSM 6" +.PP +Using iPkg has been deprecated on DSM 6, but an alternative is available +for DSM 6: entware/opkg. For instructions on how to use that, please read +Install Entware-ng on Synology NAS <https://github.com/Entware-ng/Entware-ng/wiki/Install-on-Synology-NAS> +.PP +That sadly does not (yet) work on QorIQ. At the moment of writing, the +supported architectures are armv5, armv7, mipsel, wl500g, x86_32, and x86_64. +Check here <https://pkg.entware.net/binaries/> for supported platforms. +.PP +Entware-ng comes with a precompiled 5.24.1 (June 2017) that allowes +building shared XS code. Note that this installation does \fBnot\fR use +a site_perl folder. The available \f(CW\*(C`cpan\*(C'\fR works. If all required +development packages are installed too, also for XS. +.PP +\fIDSM 5\fR +.IX Subsection "DSM 5" +.PP +As DSM is a trimmed-down Linux system, it lacks many of the tools and +libraries commonly found on Linux. The basic tools like sh, cp, rm, +etc. are implemented using +BusyBox <https://en.wikipedia.org/wiki/BusyBox>. +.IP \(bu 4 +Using your favourite browser open the DSM management page and start +the Package Center. +.IP \(bu 4 +If you want to smoke test Perl, install \f(CW\*(C`Perl\*(C'\fR. +.IP \(bu 4 +In Settings, add the following Package Sources: +.Sp +.Vb 2 +\& https://www.cphub.net +\& http://packages.quadrat4.de +.Ve +.Sp +As these two are both discontinued, it is unlikely you will be able +to set up a build environment on DSM 5. +.IP \(bu 4 +Still in Settings, in Channel Update, select Beta Channel. +.IP \(bu 4 +Press Refresh. In the left panel the item "Community" will appear. +Click it. Select "Bootstrap Installer Beta" and install it. +.IP \(bu 4 +Likewise, install "iPKGui Beta". +.Sp +The application window should now show an icon for iPKGui. +.IP \(bu 4 +Start iPKGui. Install the packages \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`gcc\*(C'\fR and \f(CW\*(C`coreutils\*(C'\fR. +.Sp +If you want to smoke test Perl, install \f(CW\*(C`patch\*(C'\fR. +.PP +The next step is to add some symlinks to system libraries. For +example, the development software expect a library \f(CW\*(C`libm.so\*(C'\fR that +normally is a symlink to \f(CW\*(C`libm.so.6\*(C'\fR. Synology only provides the +latter and not the symlink. +.PP +Here the actual architecture of the Synology system matters. You have +to find out where the gcc libraries have been installed. Look in /opt +for a directory similar to arm-none-linux-gnueab or +powerpc-linux-gnuspe. In the instructions below I'll use +powerpc-linux-gnuspe as an example. +.IP \(bu 4 +On the DSM management page start the Control Panel. +.IP \(bu 4 +Click Terminal, and enable SSH service. +.IP \(bu 4 +Close Terminal and the Control Panel. +.IP \(bu 4 +Open a shell on the Synology using ssh and become root. +.IP \(bu 4 +Execute the following commands: +.Sp +.Vb 7 +\& cd /lib +\& ln \-s libm.so.6 libm.so +\& ln \-s libcrypt.so.1 libcrypt.so +\& ln \-s libdl.so.2 libdl.so +\& cd /opt/powerpc\-linux\-gnuspe/lib (or +\& /opt/arm\-none\-linux\-gnueabi/lib) +\& ln \-s /lib/libdl.so.2 libdl.so +.Ve +.PP +\&\fBWARNING:\fR When you perform a system software upgrade, these links +will disappear and need to be re-established. +.SS "Compiling Perl 5" +.IX Subsection "Compiling Perl 5" +When the build environment has been set up, building and testing Perl +is straightforward. The only thing you need to do is download the +sources as usual, and add a file Policy.sh as follows: +.PP +.Vb 2 +\& # Administrivia. +\& perladmin="your.email@goes.here" +\& +\& # Install Perl in a tree in /opt/perl instead of /opt/bin. +\& prefix=/opt/perl +\& +\& # Select the compiler. Note that there is no \*(Aqcc\*(Aq alias or link +\& # on older DSM versions +\& cc=gcc +\& awk=/opt/bin/gawk +\& +\& # Build flags. Optional +\& ccflags="\-DDEBUGGING" +\& +\& # Library and include paths. +\& locincpth="/opt/include" +\& loclibpth="/opt/lib /usr/local/lib /usr/lib" +\& libpth="/opt/lib /usr/local/lib /usr/lib" +.Ve +.PP +You may want to create the destination directory and give it the right +permissions before installing, thus eliminating the need to build Perl +as a super user. +.PP +In the directory where you unpacked the sources, issue the familiar +commands: +.PP +.Vb 4 +\& $ bash ./Configure \-Dusedevel \-Duseshrplib \-Duse64bitall \-des +\& $ make \-j2 +\& $ env TEST_JOBS=2 make test_harness +\& $ make install +.Ve +.SS "Known problems" +.IX Subsection "Known problems" +\fIConfigure\fR +.IX Subsection "Configure" +.PP +The GNU C\-compiler might spit out unexpected stuff under \-v, which +causes the analysis of cppsymbols to fail because of unmatched quotes. +.PP +You'll note if config.sh fails with a syntax error. +.PP +\fIBuild\fR +.IX Subsection "Build" +.IP "Error message ""No error definitions found""." 4 +.IX Item "Error message ""No error definitions found""." +This error is generated when it is not possible to find the local +definitions for error codes, due to the uncommon structure of the +Synology file system. +.Sp +This error was fixed in the Perl development git for version 5.19, +commit 7a8f1212e5482613c8a5b0402528e3105b26ff24. +.PP +\fIFailing tests\fR +.IX Subsection "Failing tests" +.IP \fIext/DynaLoader/t/DynaLoader.t\fR 4 +.IX Item "ext/DynaLoader/t/DynaLoader.t" +One subtest fails due to the uncommon structure of the Synology file +system. The file \fI/lib/glibc.so\fR is missing. +.Sp +\&\fBWARNING:\fR Do not symlink \fI/lib/glibc.so.6\fR to \fI/lib/glibc.so\fR or +some system components will start to fail. +.SS "Smoke testing Perl" +.IX Subsection "Smoke testing Perl" +If building completes successfully, you can set up smoke testing as +described in the Test::Smoke documentation. +.PP +For smoke testing you need a running Perl. You can either install the +Synology supplied package for Perl 5.8.6, or build and install your +own, much more recent version. +.PP +Note that I could not run successful smokes when initiated by the +Synology Task Scheduler. I resorted to initiating the smokes via a +cron job run on another system, using ssh: +.PP +.Vb 1 +\& ssh nas1 wrk/Test\-Smoke/smoke/smokecurrent.sh +.Ve +.PP +\fILocal patches\fR +.IX Subsection "Local patches" +.PP +When local patches are applied with smoke testing, the test driver +will automatically request regeneration of certain tables after the +patches are applied. The Synology supplied Perl 5.8.6 (at least on the +DS413) \fBis NOT capable\fR of generating these tables. It will generate +opcodes with bogus values, causing the build to fail. +.PP +You can prevent regeneration by adding the setting +.PP +.Vb 1 +\& \*(Aqflags\*(Aq => 0, +.Ve +.PP +to the smoke config, or by adding another patch that inserts +.PP +.Vb 1 +\& exit 0 if $] == 5.008006; +.Ve +.PP +in the beginning of the \f(CW\*(C`regen.pl\*(C'\fR program. +.SS "Adding libraries" +.IX Subsection "Adding libraries" +The above procedure describes a basic environment and hence results in +a basic Perl. If you want to add additional libraries to Perl, you may +need some extra settings. +.PP +For example, the basic Perl does not have any of the DB libraries (db, +dbm, ndbm, gdsm). You can add these using iPKGui, however, you need to +set environment variable LD_LIBRARY_PATH to the appropriate value: +.PP +.Vb 2 +\& LD_LIBRARY_PATH=/lib:/opt/lib +\& export LD_LIBRARY_PATH +.Ve +.PP +This setting needs to be in effect while Perl is built, but also when +the programs are run. +.SH REVISION +.IX Header "REVISION" +July 2022, for DSM 5.1.5022 and DSM 6.1\-15101\-4, and DSM\-7.1\-42661\-3. +.SH AUTHOR +.IX Header "AUTHOR" +Johan Vromans <jvromans@squirrel.nl> +H. Merijn Brand <cpan@tux.freedom.nl> |