Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 270 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/perlsource.1 b/upstream/mageia-cauldron/man1/perlsource.1
new file mode 100644
index 00000000..53509dcf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlsource.1
@@ -0,0 +1,270 @@
+.\" -*- 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 "PERLSOURCE 1"
+.TH PERLSOURCE 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
+perlsource \- A guide to the Perl source tree
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes the layout of the Perl source tree. If you're
+hacking on the Perl core, this will help you find what you're looking
+for.
+.SH "FINDING YOUR WAY AROUND"
+.IX Header "FINDING YOUR WAY AROUND"
+The Perl source tree is big. Here's some of the thing you'll find in
+it:
+.SS "C code"
+.IX Subsection "C code"
+The C source code and header files mostly live in the root of the
+source tree. There are a few platform-specific directories which
+contain C code. In addition, some of the modules shipped with Perl
+include C or XS code.
+.PP
+See perlinterp for more details on the files that make up the Perl
+interpreter, as well as details on how it works.
+.SS "Core modules"
+.IX Subsection "Core modules"
+Modules shipped as part of the Perl core live in four subdirectories.
+Two of these directories contain modules that live in the core, and two
+contain modules that can also be released separately on CPAN. Modules
+which can be released on cpan are known as "dual-life" modules.
+.IP \(bu 4
+\&\fIlib/\fR
+.Sp
+This directory contains pure-Perl modules which are only released as
+part of the core. This directory contains \fIall\fR of the modules and
+their tests, unlike other core modules.
+.IP \(bu 4
+\&\fIext/\fR
+.Sp
+Like \fIlib/\fR, this directory contains modules which are only released
+as part of the core.  Unlike \fIlib/\fR, however, a module under \fIext/\fR
+generally has a CPAN-style directory\- and file-layout and its own
+\&\fIMakefile.PL\fR.  There is no expectation that a module under \fIext/\fR
+will work with earlier versions of Perl 5.  Hence, such a module may
+take full advantage of syntactical and other improvements in Perl 5
+blead.
+.IP \(bu 4
+\&\fIdist/\fR
+.Sp
+This directory is for dual-life modules where the blead source is
+canonical. Note that some modules in this directory may not yet have
+been released separately on CPAN.  Modules under \fIdist/\fR should make
+an effort to work with earlier versions of Perl 5.
+.IP \(bu 4
+\&\fIcpan/\fR
+.Sp
+This directory contains dual-life modules where the CPAN module is
+canonical. Do not patch these modules directly! Changes to these
+modules should be submitted to the maintainer of the CPAN module. Once
+those changes are applied and released, the new version of the module
+will be incorporated into the core.
+.PP
+For some dual-life modules, it has not yet been determined if the CPAN
+version or the blead source is canonical. Until that is done, those
+modules should be in \fIcpan/\fR.
+.SS Tests
+.IX Subsection "Tests"
+The Perl core has an extensive test suite. If you add new tests (or new
+modules with tests), you may need to update the \fIt/TEST\fR file so that
+the tests are run.
+.IP \(bu 4
+Module tests
+.Sp
+Tests for core modules in the \fIlib/\fR directory are right next to the
+module itself. For example, we have \fIlib/strict.pm\fR and
+\&\fIlib/strict.t\fR.
+.Sp
+Tests for modules in \fIext/\fR and the dual-life modules are in \fIt/\fR
+subdirectories for each module, like a standard CPAN distribution.
+.IP \(bu 4
+\&\fIt/base/\fR
+.Sp
+Tests for the absolute basic functionality of Perl. This includes
+\&\f(CW\*(C`if\*(C'\fR, basic file reads and writes, simple regexes, etc. These are run
+first in the test suite and if any of them fail, something is \fIreally\fR
+broken.
+.IP \(bu 4
+\&\fIt/cmd/\fR
+.Sp
+Tests for basic control structures, \f(CW\*(C`if\*(C'\fR/\f(CW\*(C`else\*(C'\fR, \f(CW\*(C`while\*(C'\fR, subroutines,
+etc.
+.IP \(bu 4
+\&\fIt/comp/\fR
+.Sp
+Tests for basic issues of how Perl parses and compiles itself.
+.IP \(bu 4
+\&\fIt/io/\fR
+.Sp
+Tests for built-in IO functions, including command line arguments.
+.IP \(bu 4
+\&\fIt/mro/\fR
+.Sp
+Tests for perl's method resolution order implementations (see mro).
+.IP \(bu 4
+\&\fIt/op/\fR
+.Sp
+Tests for perl's built in functions that don't fit into any of the
+other directories.
+.IP \(bu 4
+\&\fIt/opbasic/\fR
+.Sp
+Tests for perl's built in functions which, like those in \fIt/op/\fR, do
+not fit into any of the other directories, but which, in addition,
+cannot use \fIt/test.pl\fR,as that program depends on functionality which
+the test file itself is testing.
+.IP \(bu 4
+\&\fIt/re/\fR
+.Sp
+Tests for regex related functions or behaviour. (These used to live in
+t/op).
+.IP \(bu 4
+\&\fIt/run/\fR
+.Sp
+Tests for features of how perl actually runs, including exit codes and
+handling of PERL* environment variables.
+.IP \(bu 4
+\&\fIt/uni/\fR
+.Sp
+Tests for the core support of Unicode.
+.IP \(bu 4
+\&\fIt/win32/\fR
+.Sp
+Windows-specific tests.
+.IP \(bu 4
+\&\fIt/porting/\fR
+.Sp
+Tests the state of the source tree for various common errors. For
+example, it tests that everyone who is listed in the git log has a
+corresponding entry in the \fIAUTHORS\fR file.
+.IP \(bu 4
+\&\fIt/lib/\fR
+.Sp
+The old home for the module tests, you shouldn't put anything new in
+here. There are still some bits and pieces hanging around in here that
+need to be moved. Perhaps you could move them?  Thanks!
+.SS Documentation
+.IX Subsection "Documentation"
+All of the core documentation intended for end users lives in \fIpod/\fR.
+Individual modules in \fIlib/\fR, \fIext/\fR, \fIdist/\fR, and \fIcpan/\fR usually
+have their own documentation, either in the \fIModule.pm\fR file or an
+accompanying \fIModule.pod\fR file.
+.PP
+Finally, documentation intended for core Perl developers lives in the
+\&\fIPorting/\fR directory.
+.SS "Hacking tools and documentation"
+.IX Subsection "Hacking tools and documentation"
+The \fIPorting\fR directory contains a grab bag of code and documentation
+intended to help porters work on Perl. Some of the highlights include:
+.IP \(bu 4
+\&\fIcheck*\fR
+.Sp
+These are scripts which will check the source things like ANSI C
+violations, POD encoding issues, etc.
+.IP \(bu 4
+\&\fIMaintainers\fR, \fIMaintainers.pl\fR, and \fIMaintainers.pm\fR
+.Sp
+These files contain information on who maintains which modules. Run
+\&\f(CW\*(C`perl Porting/Maintainers \-M Module::Name\*(C'\fR to find out more
+information about a dual-life module.
+.IP \(bu 4
+\&\fIpodtidy\fR
+.Sp
+Tidies a pod file. It's a good idea to run this on a pod file you've
+patched.
+.SS "Build system"
+.IX Subsection "Build system"
+The Perl build system on *nix\-like systems starts with the \fIConfigure\fR
+script in the root directory.
+.PP
+Platform-specific pieces of the build system also live in
+platform-specific directories like \fIwin32/\fR, \fIvms/\fR, etc.
+Windows and VMS have their own Configure-like scripts, in their
+respective directories.
+.PP
+The \fIConfigure\fR script (or a platform-specific similar script) is
+ultimately responsible for generating a \fIMakefile\fR from \fIMakefile.SH\fR.
+.PP
+The build system that Perl uses is called metaconfig. This system is
+maintained separately from the Perl core, and knows about the
+platform-specific Configure-like scripts, as well as \fIConfigure\fR
+itself.
+.PP
+The metaconfig system has its own git repository. Please see its README
+file in <https://github.com/Perl/metaconfig> for more details.
+.PP
+The \fICross\fR directory contains various files related to
+cross-compiling Perl. See \fICross/README\fR for more details.
+.SS \fIAUTHORS\fP
+.IX Subsection "AUTHORS"
+This file lists everyone who's contributed to Perl. If you submit a
+patch, you should add your name to this file as part of the patch.
+.SS \fIMANIFEST\fP
+.IX Subsection "MANIFEST"
+The \fIMANIFEST\fR file in the root of the source tree contains a list of
+every file in the Perl core, as well as a brief description of each
+file.
+.PP
+You can get an overview of all the files with this command:
+.PP
+.Vb 1
+\&  % perl \-lne \*(Aqprint if /^[^\e/]+\e.[ch]\es+/\*(Aq MANIFEST
+.Ve