Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 821 insertions, 0 deletions

diff --git a/upstream/fedora-rawhide/man1/perlwin32.1 b/upstream/fedora-rawhide/man1/perlwin32.1
new file mode 100644
index 00000000..5573435a
--- /dev/null
+++ b/upstream/fedora-rawhide/man1/perlwin32.1
@@ -0,0 +1,821 @@
+.\" -*- 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 "PERLWIN32 1"
+.TH PERLWIN32 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
+perlwin32 \- Perl under Windows
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+These are instructions for building Perl under Windows 7 and later.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Before you start, you should glance through the README file
+found in the top-level directory to which the Perl distribution
+was extracted.  Make sure you read and understand the terms under
+which this software is being distributed.
+.PP
+Also make sure you read "BUGS AND CAVEATS" below for the
+known limitations of this port.
+.PP
+The INSTALL file in the perl top-level has much information that is
+only relevant to people building Perl on Unix-like systems.  In
+particular, you can safely ignore any information that talks about
+"Configure".
+.PP
+You may also want to look at one other option for building a perl that
+will work on Windows: the README.cygwin file, which give a different
+set of rules to build a perl for Windows.  This method will probably
+enable you to build a more Unix-compatible perl, but you will also
+need to download and use various other build-time and run-time support
+software described in that file.
+.PP
+This set of instructions is meant to describe a so-called "native"
+port of Perl to the Windows platform.  This includes both 32\-bit and
+64\-bit Windows operating systems.  The resulting Perl requires no
+additional software to run (other than what came with your operating
+system).  Currently, this port is capable of using one of the
+following compilers on the Intel x86 and x86_64 architectures:
+.PP
+.Vb 4
+\&      Microsoft Visual C++    version 12.0 or later
+\&      Intel C++ Compiler      (experimental)
+\&      Gcc by mingw.org        gcc version 3.4.5\-5.3.0
+\&      Gcc by mingw\-w64.org    gcc version 4.4.3 or later
+.Ve
+.PP
+Note that the last two of these are actually competing projects both
+delivering complete gcc toolchain for MS Windows:
+.IP <https://osdn.net/projects/mingw/> 4
+.IX Item "<https://osdn.net/projects/mingw/>"
+Delivers gcc toolchain building 32\-bit executables (which can be used both 32 and 64 bit Windows platforms)
+.IP <https://mingw\-w64.org> 4
+.IX Item "<https://mingw-w64.org>"
+Delivers gcc toolchain targeting both 64\-bit Windows and 32\-bit Windows
+platforms (despite the project name "mingw\-w64" they are not only 64\-bit
+oriented). They deliver the native gcc compilers and cross-compilers
+that are also supported by perl's makefile.
+.PP
+The Microsoft Visual C++ compilers are also now being given away free. They
+are available as "Visual C++ 2013\-2022 Community Edition" and are the same
+compilers that ship with "Visual C++ 2013\-2022 Professional".
+.PP
+Visual C++ 2013 is capable of \fBtargeting\fR XP and Windows Server 2003 but the
+build host requirement is Windows 7/Windows Server 2012. For more details see
+https://docs.microsoft.com/en\-us/visualstudio/productinfo/vs2013\-compatibility\-vs
+and
+https://docs.microsoft.com/en\-us/visualstudio/productinfo/vs2013\-sysrequirements\-vs
+.PP
+The MinGW64 compiler is available at <https://mingw\-w64.org>.
+The latter is actually a cross-compiler targeting Win64. There's also a trimmed
+down compiler (no java, or gfortran) suitable for building perl available at:
+<https://strawberryperl.com/package/kmx/64_gcctoolchain/>
+.PP
+NOTE: If you're using a 32\-bit compiler to build perl on a 64\-bit Windows
+operating system, then you should set the WIN64 environment variable to "undef".
+Also, the trimmed down compiler only passes tests when USE_ITHREADS *= define
+(as opposed to undef) and when the CFG *= Debug line is commented out.
+.PP
+This port fully supports MakeMaker (the set of modules that
+is used to build extensions to perl).  Therefore, you should be
+able to build and install most extensions found in the CPAN sites.
+See "Usage Hints for Perl on Windows" below for general hints about this.
+.SS "Setting Up Perl on Windows"
+.IX Subsection "Setting Up Perl on Windows"
+.IP Make 4
+.IX Item "Make"
+You need a "make" program to build the sources.  If you are using
+Visual C++, you can use nmake supplied with Visual C++.
+You may also use gmake instead of nmake.  Builds using gcc need
+gmake. nmake is not supported for gcc builds.  Parallel building is only
+supported with gmake, not nmake.
+.IP "Command Shell" 4
+.IX Item "Command Shell"
+Use the default "cmd" shell that comes with Windows.  Some versions of the
+popular 4DOS/NT shell have incompatibilities that may cause you trouble.
+If the build fails under that shell, try building again with the cmd
+shell.
+.Sp
+Make sure the path to the build directory does not contain spaces.  The
+build usually works in this circumstance, but some tests will fail.
+.IP "Microsoft Visual C++" 4
+.IX Item "Microsoft Visual C++"
+The nmake that comes with Visual C++ will suffice for building. Visual C++
+requires that certain things be set up in the console before Visual C++ will
+successfully run. To make a console box be able to run the C compiler, you will
+need to beforehand, run \f(CW\*(C`vcvarsall.bat x86\*(C'\fR to compile for x86\-32 and for
+x86\-64 \f(CW\*(C`vcvarsall.bat amd64\*(C'\fR. On a typical install of a Microsoft C++
+compiler product, these batch files will already be in your \f(CW\*(C`PATH\*(C'\fR
+environment variable so you may just type them without an absolute path into
+your console. If you need to find the absolute path to the batch file, it is
+usually found somewhere like
+C:\eProgram Files (x86)\eMicrosoft Visual Studio 14.0\eVC.
+With some newer Microsoft C products (released after ~2004), the installer will
+put a shortcut in the start menu to launch a new console window with the
+console already set up for your target architecture (x86\-32 or x86\-64 or IA64).
+With the newer compilers, you may also use the older batch files if you choose
+so.
+.IP "Microsoft Visual C++ 2013\-2022 Community Edition" 4
+.IX Item "Microsoft Visual C++ 2013-2022 Community Edition"
+These free versions of Visual C++ 2013\-2022 Professional contain the same
+compilers and linkers that ship with the full versions, and also contain
+everything necessary to build Perl.
+.Sp
+These packages can be downloaded from <https://visualstudio.microsoft.com/>.
+.Sp
+Install Visual C++ 2013\-2022 Community, then setup your environment
+using, e.g.
+.Sp
+\&\fIC:\eProgram Files\eMicrosoft Visual Studio 12.0\eCommon7\eTools\evsvars32.bat\fR
+.Sp
+(assuming the default installation location was chosen).
+.Sp
+Perl should now build using the \fIwin32/Makefile\fR.  You will need to edit that
+file to set \f(CW\*(C`CCTYPE\*(C'\fR to one of \f(CW\*(C`MSVC120\*(C'\fR\-\f(CW\*(C`MSVC143\*(C'\fR first.
+.IP "Microsoft C++ Build Tools" 4
+.IX Item "Microsoft C++ Build Tools"
+There's also a standalone (IDE-less) version of the build tools mentioned
+above containing the MSVC compiler available for download from
+<https://visualstudio.microsoft.com/visual\-cpp\-build\-tools/>.
+.Sp
+This is also referred to as \fIBuild Tools for Visual Studio\fR.
+.IP GCC 4
+.IX Item "GCC"
+Perl can be compiled with gcc from MinGW (version 3.4.5 or later) or from
+MinGW64 (version 4.4.3 or later).  It can be downloaded here:
+.Sp
+<https://osdn.net/projects/mingw/>
+<https://www.mingw\-w64.org/>
+.Sp
+You also need gmake. Usually it comes with MinGW but its executable may have
+a different name, such as mingw32\-make.exe.
+.Sp
+Note that the MinGW build currently fails with version 6.3.0 or later.
+.Sp
+Note also that the C++ mode build currently fails with MinGW 3.4.5 and 4.7.2
+or later, and with MinGW64 64\-bit 6.3.0 or later.
+.IP "Intel C++ Compiler" 4
+.IX Item "Intel C++ Compiler"
+Experimental support for using Intel C++ Compiler has been added. Edit
+\&\fIwin32/Makefile\fR and pick the correct \f(CW\*(C`CCTYPE\*(C'\fR for the Visual C that Intel C
+was installed into. Also uncomment \f(CW\*(C`_\|_ICC\*(C'\fR to enable Intel C on Visual C support.
+To set up the build environment, from the Start Menu run
+IA\-32 Visual Studio 20_\|_ mode or Intel 64 Visual Studio 20_\|_ mode as
+appropriate. Then run \f(CW\*(C`nmake\*(C'\fR as usual in that prompt box.
+.Sp
+Only Intel C++ Compiler v12.1 has been tested. Other versions probably will
+work. Using Intel C++ Compiler instead of Visual C has the benefit of C99
+compatibility which is needed by some CPAN XS modules, while maintaining
+compatibility with Visual C object code and Visual C debugging infrastructure
+unlike GCC.
+.SS Building
+.IX Subsection "Building"
+.IP \(bu 4
+Make sure you are in the \fIwin32\fR subdirectory under the perl toplevel.
+This directory contains a \fIMakefile\fR that will work with
+versions of \f(CW\*(C`nmake\*(C'\fR that come with Visual C++, and
+a GNU make \fIGNUmakefile\fR that will work for all supported compilers.
+The defaults in the \f(CW\*(C`gmake\*(C'\fR makefile are set up to build with MinGW/gcc.
+.IP \(bu 4
+Edit the \fIGNUmakefile\fR (or \fIMakefile\fR, if you're using \fInmake\fR) and change
+the values of \fIINST_DRV\fR and \f(CW\*(C`INST_TOP\*(C'\fR. You can also enable various build
+flags. These are explained in the makefiles.
+.Sp
+Note that it is generally not a good idea to try to build a \f(CW\*(C`perl\*(C'\fR with
+\&\f(CW\*(C`INST_DRV\*(C'\fR and \f(CW\*(C`INST_TOP\*(C'\fR set to a path that already exists from a previous
+build.  In particular, this may cause problems with the
+\&\fIlib/ExtUtils/t/Embed.t\fR test, which attempts to build a test program and
+may end up building against the installed \f(CW\*(C`perl\*(C'\fR's \fIlib/CORE\fR directory
+rather than the one being tested.
+.Sp
+You will have to make sure that \f(CW\*(C`CCTYPE\*(C'\fR is set correctly and that
+\&\f(CW\*(C`CCHOME\*(C'\fR points to wherever you installed your compiler.  For GCC this
+should be the directory that contains the \fIbin\fR, \fIinclude\fR and
+\&\fIlib\fR directories.
+.Sp
+If building with the cross-compiler provided by
+mingw\-w64.org you'll need to uncomment the line that sets
+\&\f(CW\*(C`GCCCROSS\*(C'\fR in the \fIGNUmakefile\fR. Do this only if it's the cross-compiler,
+ie. only if the \fIbin\fR folder doesn't contain a \fIgcc.exe\fR. (The cross-compiler
+does not provide a \fIgcc.exe\fR, \fIg++.exe\fR, \fIar.exe\fR, etc. Instead, all of these
+executables are prefixed with \f(CW\*(C`x86_64\-w64\-mingw32\-\*(C'\fR.)
+.Sp
+The default value for \f(CW\*(C`CCHOME\*(C'\fR in the makefiles for Visual C++
+may not be correct for some versions.  Make sure the default exists
+and is valid.
+.Sp
+If you want build some core extensions statically into \f(CW\*(C`perl\*(C'\fR's DLL,
+specify them in the \f(CW\*(C`STATIC_EXT\*(C'\fR macro.
+.Sp
+Be sure to read the instructions near the top of the makefiles carefully.
+.IP \(bu 4
+Type \f(CW\*(C`gmake\*(C'\fR (or \f(CW\*(C`nmake\*(C'\fR if you are using that version of \f(CW\*(C`make\*(C'\fR).
+.Sp
+This should build everything.  Specifically, it will create \fIperl.exe\fR,
+\&\fIperl538.dll\fR at the perl toplevel, and various other extension DLL's
+under the \fIlib\eauto\fR directory.  If the build fails for any reason, make
+sure you have done the previous steps correctly.
+.Sp
+To try \f(CW\*(C`gmake\*(C'\fR's parallel mode, type \f(CW\*(C`gmake \-j2\*(C'\fR where \f(CW2\fR is the maximum number
+of parallel jobs you want to run. A number of things in the build process will
+run in parallel, but there are serialization points where you will see just 1
+CPU maxed out. This is normal.
+.Sp
+If you are advanced enough with building C code, here is a suggestion to speed
+up building \f(CW\*(C`perl\*(C'\fR, and the later \f(CW\*(C`make test\*(C'\fR. Try to keep your \f(CW\*(C`PATH\*(C'\fR environment
+variable with the least number of folders possible (remember to keep your C
+compiler's folders there). \fIC:\eWINDOWS\esystem32\fR or \fIC:\eWINNT\esystem32\fR
+depending on your OS version should be first folder in \f(CW\*(C`PATH\*(C'\fR, since \f(CW\*(C`cmd.exe\*(C'\fR
+is the most commonly launched program during the build and later testing.
+.SS "Testing Perl on Windows"
+.IX Subsection "Testing Perl on Windows"
+Type "gmake test" (or "nmake test").  This will run most
+of the tests from the testsuite (many tests will be skipped).
+.PP
+There should be no test failures.
+.PP
+If you build with Visual C++ 2013 then three tests currently may fail with
+Daylight Saving Time related problems: \fIt/io/fs.t\fR,
+\&\fIcpan/HTTP\-Tiny/t/110_mirror.t\fR and \fIlib/File/Copy.t\fR. The failures are
+caused by bugs in the CRT in VC++ 2013 which are fixed in VC++2015 and
+later, as explained by Microsoft here:
+<https://connect.microsoft.com/VisualStudio/feedback/details/811534/utime\-sometimes\-fails\-to\-set\-the\-correct\-file\-times\-in\-visual\-c\-2013>. In the meantime,
+if you need fixed \f(CW\*(C`stat\*(C'\fR and \f(CW\*(C`utime\*(C'\fR functions then have a look at the
+CPAN distribution Win32::UTCFileTime.
+.PP
+If you build with Visual C++ 2015 or later then \fIext/XS\-APItest/t/locale.t\fR
+may crash (after all its tests have passed). This is due to a regression in the
+Universal CRT introduced in the Windows 10 April 2018 Update, and will be fixed
+in the May 2019 Update, as explained here: <https://developercommunity.visualstudio.com/content/problem/519486/setlocalelc\-numeric\-iso\-latin\-16\-fails\-then\-succee.html>.
+.PP
+If you build with certain versions (e.g. 4.8.1) of gcc from mingw then
+\&\fIext/POSIX/t/time.t\fR may fail test 17 due to a known bug in those gcc builds:
+see <https://sourceforge.net/p/mingw/bugs/2152/>.
+.PP
+Some test failures may occur if you use a command shell other than the
+native "cmd.exe", or if you are building from a path that contains
+spaces.  So don't do that.
+.PP
+If you are running the tests from a emacs shell window, you may see
+failures in op/stat.t.  Run "gmake test-notty" in that case.
+.PP
+Furthermore, you should make sure that during \f(CW\*(C`make test\*(C'\fR you do not
+have any GNU tool packages in your path: some toolkits like Unixutils
+include some tools (\f(CW\*(C`type\*(C'\fR for instance) which override the Windows
+ones and makes tests fail. Remove them from your path while testing to
+avoid these errors.
+.PP
+To see the output of specific failing tests run the harness from the t
+directory:
+.PP
+.Vb 3
+\&  # assuming you\*(Aqre starting from the win32 directory
+\&  cd ..\ewin32
+\&  .\eperl harness <list of tests>
+.Ve
+.PP
+Please report any other failures as described under "BUGS AND CAVEATS".
+.SS "Installation of Perl on Windows"
+.IX Subsection "Installation of Perl on Windows"
+Type "gmake install" ("nmake install").  This will
+put the newly built perl and the libraries under whatever \f(CW\*(C`INST_TOP\*(C'\fR
+points to in the Makefile.  It will also install the pod documentation
+under \f(CW\*(C`$INST_TOP\e$INST_VER\elib\epod\*(C'\fR and HTML versions of the same
+under \f(CW\*(C`$INST_TOP\e$INST_VER\elib\epod\ehtml\*(C'\fR.
+.PP
+To use the Perl you just installed you will need to add a new entry to
+your PATH environment variable: \f(CW\*(C`$INST_TOP\ebin\*(C'\fR, e.g.
+.PP
+.Vb 1
+\&    set PATH=c:\eperl\ebin;%PATH%
+.Ve
+.PP
+If you opted to uncomment \f(CW\*(C`INST_VER\*(C'\fR and \f(CW\*(C`INST_ARCH\*(C'\fR in the makefile
+then the installation structure is a little more complicated and you will
+need to add two new PATH components instead: \f(CW\*(C`$INST_TOP\e$INST_VER\ebin\*(C'\fR and
+\&\f(CW\*(C`$INST_TOP\e$INST_VER\ebin\e$ARCHNAME\*(C'\fR, e.g.
+.PP
+.Vb 1
+\&    set PATH=c:\eperl\e5.6.0\ebin;c:\eperl\e5.6.0\ebin\eMSWin32\-x86;%PATH%
+.Ve
+.SS "Usage Hints for Perl on Windows"
+.IX Subsection "Usage Hints for Perl on Windows"
+.IP "Environment Variables" 4
+.IX Item "Environment Variables"
+The installation paths that you set during the build get compiled
+into perl, so you don't have to do anything additional to start
+using that perl (except add its location to your PATH variable).
+.Sp
+If you put extensions in unusual places, you can set PERL5LIB
+to a list of paths separated by semicolons where you want perl
+to look for libraries.  Look for descriptions of other environment
+variables you can set in perlrun.
+.Sp
+You can also control the shell that perl uses to run \fBsystem()\fR and
+backtick commands via PERL5SHELL.  See perlrun.
+.Sp
+Perl does not depend on the registry, but it can look up certain default
+values if you choose to put them there unless disabled at build time with
+USE_NO_REGISTRY.  On Perl process start Perl checks if
+\&\f(CW\*(C`HKEY_CURRENT_USER\eSoftware\ePerl\*(C'\fR and \f(CW\*(C`HKEY_LOCAL_MACHINE\eSoftware\ePerl\*(C'\fR
+exist.  If the keys exists, they will be checked for remainder of the Perl
+process's run life for certain entries.  Entries in
+\&\f(CW\*(C`HKEY_CURRENT_USER\eSoftware\ePerl\*(C'\fR override entries in
+\&\f(CW\*(C`HKEY_LOCAL_MACHINE\eSoftware\ePerl\*(C'\fR.  One or more of the following entries
+(of type REG_SZ or REG_EXPAND_SZ) may be set in the keys:
+.Sp
+.Vb 7
+\& lib\-$]        version\-specific standard library path to add to @INC
+\& lib           standard library path to add to @INC
+\& sitelib\-$]    version\-specific site library path to add to @INC
+\& sitelib       site library path to add to @INC
+\& vendorlib\-$]  version\-specific vendor library path to add to @INC
+\& vendorlib     vendor library path to add to @INC
+\& PERL*         fallback for all %ENV lookups that begin with "PERL"
+.Ve
+.Sp
+Note the \f(CW$]\fR in the above is not literal.  Substitute whatever version
+of perl you want to honor that entry, e.g. \f(CW5.6.0\fR.  Paths must be
+separated with semicolons, as usual on Windows.
+.IP "File Globbing" 4
+.IX Item "File Globbing"
+By default, perl handles file globbing using the File::Glob extension,
+which provides portable globbing.
+.Sp
+If you want perl to use globbing that emulates the quirks of DOS
+filename conventions, you might want to consider using File::DosGlob
+to override the internal \fBglob()\fR implementation.  See File::DosGlob for
+details.
+.IP "Using perl from the command line" 4
+.IX Item "Using perl from the command line"
+If you are accustomed to using perl from various command-line
+shells found in UNIX environments, you will be less than pleased
+with what Windows offers by way of a command shell.
+.Sp
+The crucial thing to understand about the Windows environment is that
+the command line you type in is processed twice before Perl sees it.
+First, your command shell (usually CMD.EXE) preprocesses the command
+line, to handle redirection, environment variable expansion, and
+location of the executable to run. Then, the perl executable splits
+the remaining command line into individual arguments, using the
+C runtime library upon which Perl was built.
+.Sp
+It is particularly important to note that neither the shell nor the C
+runtime do any wildcard expansions of command-line arguments (so
+wildcards need not be quoted).  Also, the quoting behaviours of the
+shell and the C runtime are rudimentary at best (and may, if you are
+using a non-standard shell, be inconsistent).  The only (useful) quote
+character is the double quote (").  It can be used to protect spaces
+and other special characters in arguments.
+.Sp
+The Windows documentation describes the shell parsing rules here:
+<https://docs.microsoft.com/en\-us/windows\-server/administration/windows\-commands/cmd>
+and the C runtime parsing rules here:
+<https://msdn.microsoft.com/en\-us/library/17w5ykft%28v=VS.100%29.aspx>.
+.Sp
+Here are some further observations based on experiments: The C runtime
+breaks arguments at spaces and passes them to programs in argc/argv.
+Double quotes can be used to prevent arguments with spaces in them from
+being split up.  You can put a double quote in an argument by escaping
+it with a backslash and enclosing the whole argument within double quotes.
+The backslash and the pair of double quotes surrounding the argument will
+be stripped by the C runtime.
+.Sp
+The file redirection characters "<", ">", and "|" can be quoted by
+double quotes (although there are suggestions that this may not always
+be true).  Single quotes are not treated as quotes by the shell or
+the C runtime, they don't get stripped by the shell (just to make
+this type of quoting completely useless).  The caret "^" has also
+been observed to behave as a quoting character, but this appears
+to be a shell feature, and the caret is not stripped from the command
+line, so Perl still sees it (and the C runtime phase does not treat
+the caret as a quote character).
+.Sp
+Here are some examples of usage of the "cmd" shell:
+.Sp
+This prints two doublequotes:
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aq\e"\e"\*(Aq "
+.Ve
+.Sp
+This does the same:
+.Sp
+.Vb 1
+\&    perl \-e "print \e"\e\e\e"\e\e\e"\e" "
+.Ve
+.Sp
+This prints "bar" and writes "foo" to the file "blurch":
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" > blurch
+.Ve
+.Sp
+This prints "foo" ("bar" disappears into nowhereland):
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" 2> nul
+.Ve
+.Sp
+This prints "bar" and writes "foo" into the file "blurch":
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" 1> blurch
+.Ve
+.Sp
+This pipes "foo" to the "less" pager and prints "bar" on the console:
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" | less
+.Ve
+.Sp
+This pipes "foo\enbar\en" to the less pager:
+.Sp
+.Vb 1
+\&    perl \-le "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" 2>&1 | less
+.Ve
+.Sp
+This pipes "foo" to the pager and writes "bar" in the file "blurch":
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" 2> blurch | less
+.Ve
+.Sp
+Discovering the usefulness of the "command.com" shell on Windows 9x
+is left as an exercise to the reader :)
+.Sp
+One particularly pernicious problem with the 4NT command shell for
+Windows is that it (nearly) always treats a % character as indicating
+that environment variable expansion is needed.  Under this shell, it is
+therefore important to always double any % characters which you want
+Perl to see (for example, for hash variables), even when they are
+quoted.
+.IP "Building Extensions" 4
+.IX Item "Building Extensions"
+The Comprehensive Perl Archive Network (CPAN) offers a wealth
+of extensions, some of which require a C compiler to build.
+Look in <https://www.cpan.org/> for more information on CPAN.
+.Sp
+Note that not all of the extensions available from CPAN may work
+in the Windows environment; you should check the information at
+<https://www.cpantesters.org/> before investing too much effort into
+porting modules that don't readily build.
+.Sp
+Most extensions (whether they require a C compiler or not) can
+be built, tested and installed with the standard mantra:
+.Sp
+.Vb 4
+\&    perl Makefile.PL
+\&    $MAKE
+\&    $MAKE test
+\&    $MAKE install
+.Ve
+.Sp
+where \f(CW$MAKE\fR is whatever 'make' program you have configured perl to
+use.  Use "perl \-V:make" to find out what this is.  Some extensions
+may not provide a testsuite (so "$MAKE test" may not do anything or
+fail), but most serious ones do.
+.Sp
+It is important that you use a supported 'make' program, and
+ensure Config.pm knows about it.
+.Sp
+Note that MakeMaker actually emits makefiles with different syntax
+depending on what 'make' it thinks you are using.  Therefore, it is
+important that one of the following values appears in Config.pm:
+.Sp
+.Vb 3
+\&    make=\*(Aqnmake\*(Aq        # MakeMaker emits nmake syntax
+\&    any other value     # MakeMaker emits generic make syntax
+\&                            (e.g GNU make, or Perl make)
+.Ve
+.Sp
+If the value doesn't match the 'make' program you want to use,
+edit Config.pm to fix it.
+.Sp
+If a module implements XSUBs, you will need one of the supported
+C compilers.  You must make sure you have set up the environment for
+the compiler for command-line compilation before running \f(CW\*(C`perl Makefile.PL\*(C'\fR
+or any invocation of make.
+.Sp
+If a module does not build for some reason, look carefully for
+why it failed, and report problems to the module author.  If
+it looks like the extension building support is at fault, report
+that with full details of how the build failed using the GitHub
+issue tracker at <https://github.com/Perl/perl5/issues>.
+.IP "Command-line Wildcard Expansion" 4
+.IX Item "Command-line Wildcard Expansion"
+The default command shells on DOS descendant operating systems (such
+as they are) usually do not expand wildcard arguments supplied to
+programs.  They consider it the application's job to handle that.
+This is commonly achieved by linking the application (in our case,
+perl) with startup code that the C runtime libraries usually provide.
+However, doing that results in incompatible perl versions (since the
+behavior of the argv expansion code differs depending on the
+compiler, and it is even buggy on some compilers).  Besides, it may
+be a source of frustration if you use such a perl binary with an
+alternate shell that *does* expand wildcards.
+.Sp
+Instead, the following solution works rather well. The nice things
+about it are 1) you can start using it right away; 2) it is more
+powerful, because it will do the right thing with a pattern like
+*/*/*.c; 3) you can decide whether you do/don't want to use it; and
+4) you can extend the method to add any customizations (or even
+entirely different kinds of wildcard expansion).
+.Sp
+.Vb 10
+\& C:\e> copy con c:\eperl\elib\eWild.pm
+\& # Wild.pm \- emulate shell @ARGV expansion on shells that don\*(Aqt
+\& use File::DosGlob;
+\& @ARGV = map {
+\&              my @g = File::DosGlob::glob($_) if /[*?]/;
+\&              @g ? @g : $_;
+\&            } @ARGV;
+\& 1;
+\& ^Z
+\& C:\e> set PERL5OPT=\-MWild
+\& C:\e> perl \-le "for (@ARGV) { print }" */*/perl*.c
+\& p4view/perl/perl.c
+\& p4view/perl/perlio.c
+\& p4view/perl/perly.c
+\& perl5.005/win32/perlglob.c
+\& perl5.005/win32/perllib.c
+\& perl5.005/win32/perlglob.c
+\& perl5.005/win32/perllib.c
+\& perl5.005/win32/perlglob.c
+\& perl5.005/win32/perllib.c
+.Ve
+.Sp
+Note there are two distinct steps there: 1) You'll have to create
+Wild.pm and put it in your perl lib directory. 2) You'll need to
+set the PERL5OPT environment variable.  If you want argv expansion
+to be the default, just set PERL5OPT in your default startup
+environment.
+.Sp
+If you are using the Visual C compiler, you can get the C runtime's
+command line wildcard expansion built into perl binary.  The resulting
+binary will always expand unquoted command lines, which may not be
+what you want if you use a shell that does that for you.  The expansion
+done is also somewhat less powerful than the approach suggested above.
+.IP "Notes on 64\-bit Windows" 4
+.IX Item "Notes on 64-bit Windows"
+Windows .NET Server supports the LLP64 data model on the Intel Itanium
+architecture.
+.Sp
+The LLP64 data model is different from the LP64 data model that is the
+norm on 64\-bit Unix platforms.  In the former, \f(CW\*(C`int\*(C'\fR and \f(CW\*(C`long\*(C'\fR are
+both 32\-bit data types, while pointers are 64 bits wide.  In addition,
+there is a separate 64\-bit wide integral type, \f(CW\*(C`_\|_int64\*(C'\fR.  In contrast,
+the LP64 data model that is pervasive on Unix platforms provides \f(CW\*(C`int\*(C'\fR
+as the 32\-bit type, while both the \f(CW\*(C`long\*(C'\fR type and pointers are of
+64\-bit precision.  Note that both models provide for 64\-bits of
+addressability.
+.Sp
+64\-bit Windows running on Itanium is capable of running 32\-bit x86
+binaries transparently.  This means that you could use a 32\-bit build
+of Perl on a 64\-bit system.  Given this, why would one want to build
+a 64\-bit build of Perl?  Here are some reasons why you would bother:
+.RS 4
+.IP \(bu 4
+A 64\-bit native application will run much more efficiently on
+Itanium hardware.
+.IP \(bu 4
+There is no 2GB limit on process size.
+.IP \(bu 4
+Perl automatically provides large file support when built under
+64\-bit Windows.
+.IP \(bu 4
+Embedding Perl inside a 64\-bit application.
+.RE
+.RS 4
+.RE
+.SS "Running Perl Scripts"
+.IX Subsection "Running Perl Scripts"
+Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
+indicate to the OS that it should execute the file using perl.
+Windows has no comparable means to indicate arbitrary files are
+executables.
+.PP
+Instead, all available methods to execute plain text files on
+Windows rely on the file "extension".  There are three methods
+to use this to execute perl scripts:
+.IP 1. 8
+There is a facility called "file extension associations".  This can be
+manipulated via the two commands "assoc" and "ftype" that come
+standard with Windows.  Type "ftype /?" for a complete example of how
+to set this up for perl scripts (Say what?  You thought Windows
+wasn't perl-ready? :).
+.IP 2. 8
+Since file associations don't work everywhere, and there are
+reportedly bugs with file associations where it does work, the
+old method of wrapping the perl script to make it look like a
+regular batch file to the OS, may be used.  The install process
+makes available the "pl2bat.bat" script which can be used to wrap
+perl scripts into batch files.  For example:
+.Sp
+.Vb 1
+\&        pl2bat foo.pl
+.Ve
+.Sp
+will create the file "FOO.BAT".  Note "pl2bat" strips any
+\&.pl suffix and adds a .bat suffix to the generated file.
+.Sp
+If you use the 4DOS/NT or similar command shell, note that
+"pl2bat" uses the "%*" variable in the generated batch file to
+refer to all the command line arguments, so you may need to make
+sure that construct works in batch files.  As of this writing,
+4DOS/NT users will need a "ParameterChar = *" statement in their
+4NT.INI file or will need to execute "setdos /p*" in the 4DOS/NT
+startup file to enable this to work.
+.IP 3. 8
+Using "pl2bat" has a few problems:  the file name gets changed,
+so scripts that rely on \f(CW$0\fR to find what they must do may not
+run properly; running "pl2bat" replicates the contents of the
+original script, and so this process can be maintenance intensive
+if the originals get updated often.  A different approach that
+avoids both problems is possible.
+.Sp
+A script called "runperl.bat" is available that can be copied
+to any filename (along with the .bat suffix).  For example,
+if you call it "foo.bat", it will run the file "foo" when it is
+executed.  Since you can run batch files on Windows platforms simply
+by typing the name (without the extension), this effectively
+runs the file "foo", when you type either "foo" or "foo.bat".
+With this method, "foo.bat" can even be in a different location
+than the file "foo", as long as "foo" is available somewhere on
+the PATH.  If your scripts are on a filesystem that allows symbolic
+links, you can even avoid copying "runperl.bat".
+.Sp
+Here's a diversion:  copy "runperl.bat" to "runperl", and type
+"runperl".  Explain the observed behavior, or lack thereof. :)
+Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
+.SS "Miscellaneous Things"
+.IX Subsection "Miscellaneous Things"
+A full set of HTML documentation is installed, so you should be
+able to use it if you have a web browser installed on your
+system.
+.PP
+\&\f(CW\*(C`perldoc\*(C'\fR is also a useful tool for browsing information contained
+in the documentation, especially in conjunction with a pager
+like \f(CW\*(C`less\*(C'\fR (recent versions of which have Windows support).  You may
+have to set the PAGER environment variable to use a specific pager.
+"perldoc \-f foo" will print information about the perl operator
+"foo".
+.PP
+One common mistake when using this port with a GUI library like \f(CW\*(C`Tk\*(C'\fR
+is assuming that Perl's normal behavior of opening a command-line
+window will go away.  This isn't the case.  If you want to start a copy
+of \f(CW\*(C`perl\*(C'\fR without opening a command-line window, use the \f(CW\*(C`wperl\*(C'\fR
+executable built during the installation process.  Usage is exactly
+the same as normal \f(CW\*(C`perl\*(C'\fR on Windows, except that options like \f(CW\*(C`\-h\*(C'\fR
+don't work (since they need a command-line window to print to).
+.PP
+If you find bugs in perl, you can report them to
+<https://github.com/Perl/perl5/issues>.
+.SH "BUGS AND CAVEATS"
+.IX Header "BUGS AND CAVEATS"
+Norton AntiVirus interferes with the build process, particularly if
+set to "AutoProtect, All Files, when Opened". Unlike large applications
+the perl build process opens and modifies a lot of files. Having the
+AntiVirus scan each and every one slows build the process significantly.
+Worse, with PERLIO=stdio the build process fails with peculiar messages
+as the virus checker interacts badly with miniperl.exe writing configure
+files (it seems to either catch file part written and treat it as suspicious,
+or virus checker may have it "locked" in a way which inhibits miniperl
+updating it). The build does complete with
+.PP
+.Vb 1
+\&   set PERLIO=perlio
+.Ve
+.PP
+but that may be just luck. Other AntiVirus software may have similar issues.
+.PP
+A git GUI shell extension for Windows such as TortoiseGit will cause the build
+and later \f(CW\*(C`make test\*(C'\fR to run much slower since every file is checked for its
+git status as soon as it is created and/or modified. TortoiseGit doesn't cause
+any test failures or build problems unlike the antivirus software described
+above, but it does cause similar slowness. It is suggested to use Task Manager
+to look for background processes which use high CPU amounts during the building
+process.
+.PP
+Some of the built-in functions do not act exactly as documented in
+perlfunc, and a few are not implemented at all.  To avoid
+surprises, particularly if you have had prior exposure to Perl
+in other operating environments or if you intend to write code
+that will be portable to other environments, see perlport
+for a reasonably definitive list of these differences.
+.PP
+Not all extensions available from CPAN may build or work properly
+in the Windows environment.  See "Building Extensions".
+.PP
+Most \f(CWsocket()\fR related calls are supported, but they may not
+behave as on Unix platforms.  See perlport for the full list.
+.PP
+Signal handling may not behave as on Unix platforms (where it
+doesn't exactly "behave", either :).  For instance, calling \f(CWdie()\fR
+or \f(CWexit()\fR from signal handlers will cause an exception, since most
+implementations of \f(CWsignal()\fR on Windows are severely crippled.
+Thus, signals may work only for simple things like setting a flag
+variable in the handler.  Using signals under this port should
+currently be considered unsupported.
+.PP
+Please report detailed descriptions of any problems and solutions that
+you may find at <<https://github.com/Perl/perl5/issues>>,
+along with the output produced by \f(CW\*(C`perl \-V\*(C'\fR.
+.SH ACKNOWLEDGEMENTS
+.IX Header "ACKNOWLEDGEMENTS"
+The use of a camel with the topic of Perl is a trademark
+of O'Reilly and Associates, Inc. Used with permission.
+.SH AUTHORS
+.IX Header "AUTHORS"
+.IP "Gary Ng <71564.1743@CompuServe.COM>" 4
+.IX Item "Gary Ng <71564.1743@CompuServe.COM>"
+.PD 0
+.IP "Gurusamy Sarathy <gsar@activestate.com>" 4
+.IX Item "Gurusamy Sarathy <gsar@activestate.com>"
+.IP "Nick Ing-Simmons <nick@ing\-simmons.net>" 4
+.IX Item "Nick Ing-Simmons <nick@ing-simmons.net>"
+.IP "Jan Dubois <jand@activestate.com>" 4
+.IX Item "Jan Dubois <jand@activestate.com>"
+.IP "Steve Hay <steve.m.hay@googlemail.com>" 4
+.IX Item "Steve Hay <steve.m.hay@googlemail.com>"
+.PD
+.PP
+This document is maintained by Jan Dubois.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perl
+.SH HISTORY
+.IX Header "HISTORY"
+This port was originally contributed by Gary Ng around 5.003_24,
+and borrowed from the Hip Communications port that was available
+at the time.  Various people have made numerous and sundry hacks
+since then.
+.PP
+GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
+.PP
+Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
+.PP
+Support for \fBfork()\fR emulation was added in 5.6 (ActiveState Tool Corp).
+.PP
+Win9x support was added in 5.6 (Benjamin Stuhl).
+.PP
+Support for 64\-bit Windows added in 5.8 (ActiveState Corp).
+.PP
+Last updated: 06 October 2021