Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 250 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/perlamiga.1 b/upstream/mageia-cauldron/man1/perlamiga.1
new file mode 100644
index 00000000..a5bd7f07
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlamiga.1
@@ -0,0 +1,250 @@
+.\" -*- 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 "PERLAMIGA 1"
+.TH PERLAMIGA 1 2023-11-28 "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
+perlamiga \- Perl under AmigaOS 4.1
+.SH NOTE
+.IX Header "NOTE"
+This is a port of Perl 5.22.1, it is a fresh port and not in any way
+compatible with my previous ports of Perl 5.8 and 5.16.3. This means
+you will need to reinstall / rebuild any third party modules you have
+installed.
+.PP
+newlib.library version 53.28 or greater is required.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+Once perl is installed you can read this document in the following way
+.PP
+.Vb 1
+\&        sh \-c "perldoc perlamiga"
+.Ve
+.PP
+or you may read \fIas is\fR: either as \fIREADME.amiga\fR, or \fIpod/perlamiga.pod\fR.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS "Prerequisites for running Perl 5.22.1 under AmigaOS 4.1"
+.IX Subsection "Prerequisites for running Perl 5.22.1 under AmigaOS 4.1"
+.IP "\fBAmigaOS 4.1 update 6 with all updates applied as of 9th October 2013\fR" 6
+.IX Item "AmigaOS 4.1 update 6 with all updates applied as of 9th October 2013"
+The most important of which is:
+.IP "\fBnewlib.library version 53.28 or greater\fR" 6
+.IX Item "newlib.library version 53.28 or greater"
+.PD 0
+.IP "\fBAmigaOS SDK\fR" 6
+.IX Item "AmigaOS SDK"
+.PD
+Perl installs into the SDK directory structure and expects many of the
+build tools present in the SDK to be available. So for the best results
+install the SDK first.
+.IP \fBabc-shell\fR 6
+.IX Item "abc-shell"
+If you do not have the SDK installed you must at least have abc-shell
+installed or some other suitable sh port. This is required to run
+external commands and should be available as 'sh' in your path.
+.SS "Starting Perl programs under AmigaOS 4.1"
+.IX Subsection "Starting Perl programs under AmigaOS 4.1"
+Perl may be run from the AmigaOS shell but for best results should be
+run under abc-shell.  (abc-shell handles file globbing, pattern
+expansion, and sets up environment variables in the UN*Xy way that
+Perl expects.)
+.PP
+For example:
+.PP
+.Vb 3
+\&        New Shell process 10
+\&        10.AmigaOS4:> sh
+\&        /AmigaOS4>perl path:to/myprog arg1 arrg2 arg3
+.Ve
+.PP
+Abc-shell can also launch programs via the #! syntax at the start of
+the program file, it's best use the form #!SDK:Local/C/perl so that
+the AmigaOS shell may also find perl in the same way. AmigaOS requires
+the script bit to be set for this to work
+.PP
+.Vb 2
+\&        10.AmigaOS4:> sh
+\&        /AmigaOS4>myprog arg1 arrg2 arg3
+.Ve
+.SS "Limitations of Perl under AmigaOS 4.1"
+.IX Subsection "Limitations of Perl under AmigaOS 4.1"
+.IP "\fBNested Piped programs can crash when run from older abc-shells\fR" 6
+.IX Item "Nested Piped programs can crash when run from older abc-shells"
+abc-shell version 53.2 has a bug that can cause crashes in the
+subprocesses used to run piped programs, if a later version is
+available you should install it instead.
+.IP "\fBIncorrect or unexpected command line unescaping\fR" 6
+.IX Item "Incorrect or unexpected command line unescaping"
+newlib.library 53.30 and earlier incorrectly unescape slashed escape
+sequences e.g. \e" \en \et etc requiring unusual extra escaping.
+.IP "\fBStarting subprocesses via open has limitations\fR" 6
+.IX Item "Starting subprocesses via open has limitations"
+.Vb 1
+\&        open FH, "command |"
+.Ve
+.Sp
+Subprocesses started with open use a minimal \fBpopen()\fR routine and
+therefore they do not return pids usable with waitpid etc.
+.IP "If you find any other limitations or bugs then let me know." 6
+.IX Item "If you find any other limitations or bugs then let me know."
+Please report bugs in this version of perl to andy@broad.ology.org.uk
+in the first instance.
+.SH INSTALLATION
+.IX Header "INSTALLATION"
+This guide assumes you have obtained a prebuilt archive from os4depot.net.
+.PP
+Unpack the main archive to a temporary location (RAM: is fine).
+.PP
+Execute the provided install script from shell or via its icon.
+.PP
+You \fBmust not\fR attempt to install by hand.
+.PP
+Once installed you may delete the temporary archive.
+.PP
+This approach will preserve links in the installation without creating
+duplicate binaries.
+.PP
+If you have the earlier ports perl 5.16 or 5.8 installed you may like
+to rename your perl executable to perl516 or perl58 or something
+similar before the installation of 5.22.1, this will allow you to use
+both versions at the same time.
+.SH "Amiga Specific Modules"
+.IX Header "Amiga Specific Modules"
+.SS Amiga::ARexx
+.IX Subsection "Amiga::ARexx"
+The Amiga::ARexx module allows you to easily create a perl based ARexx
+host or to send ARexx commands to other programs.
+.PP
+Try \f(CW\*(C`perldoc Amiga::ARexx\*(C'\fR for more info.
+.SS Amiga::Exec
+.IX Subsection "Amiga::Exec"
+The Amiga::Exec module introduces support for \fBWait()\fR.
+.PP
+Try \f(CW\*(C`perldoc Amiga::Exec\*(C'\fR for more info.
+.SH BUILDING
+.IX Header "BUILDING"
+To build perl under AmigaOS from the patched sources you will need to
+have a recent version of the SDK. Version 53.29 is recommended,
+earlier versions will probably work too.
+.PP
+With the help of Jarkko Hietaniemi the Configure system has been tweaked to
+run under abc-shell so the recommend build process is as follows.
+.PP
+.Vb 3
+\&        stack 2000000
+\&        sh Configure \-de
+\&        gmake
+.Ve
+.PP
+This will build the default setup that installs under SDK:local/newlib/lib/
+.SH CHANGES
+.IX Header "CHANGES"
+.IP "\fBAugust 2015\fR" 6
+.IX Item "August 2015"
+.RS 6
+.PD 0
+.IP "Port to Perl 5.22" 2
+.IX Item "Port to Perl 5.22"
+.IP "Add handling of NIL: to \fBafstat()\fR" 2
+.IX Item "Add handling of NIL: to afstat()"
+.IP "Fix inheritance of environment variables by subprocesses." 2
+.IX Item "Fix inheritance of environment variables by subprocesses."
+.IP "Fix exec, and exit in ""forked"" subprocesses." 2
+.IX Item "Fix exec, and exit in ""forked"" subprocesses."
+.IP "Fix issue with newlib's unlink, which could cause infinite loops." 2
+.IX Item "Fix issue with newlib's unlink, which could cause infinite loops."
+.IP "Add \fBflock()\fR emulation using IDOS\->LockRecord thanks to Tony Cook for the suggestion." 2
+.IX Item "Add flock() emulation using IDOS->LockRecord thanks to Tony Cook for the suggestion."
+.IP "Fix issue where kill was using the wrong kind of process ID" 2
+.IX Item "Fix issue where kill was using the wrong kind of process ID"
+.RE
+.RS 6
+.RE
+.IP "\fB27th November 2013\fR" 6
+.IX Item "27th November 2013"
+.RS 6
+.IP "Create new installation system based on installperl links and Amiga protection bits now set correctly." 2
+.IX Item "Create new installation system based on installperl links and Amiga protection bits now set correctly."
+.IP "Pod now defaults to text." 2
+.IX Item "Pod now defaults to text."
+.IP "File::Spec should now recognise an Amiga style absolute path as well as an Unix style one. Relative paths must always be Unix style." 2
+.IX Item "File::Spec should now recognise an Amiga style absolute path as well as an Unix style one. Relative paths must always be Unix style."
+.RE
+.RS 6
+.RE
+.IP "\fB20th November 2013\fR" 6
+.IX Item "20th November 2013"
+.RS 6
+.IP "Configured to use SDK:Local/C/perl to start standard scripts" 2
+.IX Item "Configured to use SDK:Local/C/perl to start standard scripts"
+.IP "Added Amiga::Exec module with support for \fBWait()\fR and AmigaOS signal numbers." 2
+.IX Item "Added Amiga::Exec module with support for Wait() and AmigaOS signal numbers."
+.RE
+.RS 6
+.RE
+.IP "\fB10th October 13\fR" 6
+.IX Item "10th October 13"
+.PD
+First release of port to 5.16.3.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+You like this port?  See <http://www.broad.ology.org.uk/amiga/>
+for how you can help.