Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 373 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man1/perlsynology.1 b/upstream/debian-unstable/man1/perlsynology.1
new file mode 100644
index 00000000..c47df4b6
--- /dev/null
+++ b/upstream/debian-unstable/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-12 "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>