Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 299 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/ExtUtils::CBuilder.3perl b/upstream/debian-unstable/man3/ExtUtils::CBuilder.3perl
new file mode 100644
index 00000000..f279ecd0
--- /dev/null
+++ b/upstream/debian-unstable/man3/ExtUtils::CBuilder.3perl
@@ -0,0 +1,299 @@
+.\" -*- 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 "ExtUtils::CBuilder 3perl"
+.TH ExtUtils::CBuilder 3perl 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
+ExtUtils::CBuilder \- Compile and link C code for Perl modules
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&  use ExtUtils::CBuilder;
+\&
+\&  my $b = ExtUtils::CBuilder\->new(%options);
+\&  $obj_file = $b\->compile(source => \*(AqMyModule.c\*(Aq);
+\&  $lib_file = $b\->link(objects => $obj_file);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This module can build the C portions of Perl modules by invoking the
+appropriate compilers and linkers in a cross-platform manner.  It was
+motivated by the \f(CW\*(C`Module::Build\*(C'\fR project, but may be useful for other
+purposes as well.  However, it is \fInot\fR intended as a general
+cross-platform interface to all your C building needs.  That would
+have been a much more ambitious goal!
+.SH METHODS
+.IX Header "METHODS"
+.IP new 4
+.IX Item "new"
+Returns a new \f(CW\*(C`ExtUtils::CBuilder\*(C'\fR object.  A \f(CW\*(C`config\*(C'\fR parameter
+lets you override \f(CW\*(C`Config.pm\*(C'\fR settings for all operations performed
+by the object, as in the following example:
+.Sp
+.Vb 3
+\&  # Use a different compiler than Config.pm says
+\&  my $b = ExtUtils::CBuilder\->new( config =>
+\&                                   { ld => \*(Aqgcc\*(Aq } );
+.Ve
+.Sp
+A \f(CW\*(C`quiet\*(C'\fR parameter tells \f(CW\*(C`CBuilder\*(C'\fR to not print its \f(CWsystem()\fR
+commands before executing them:
+.Sp
+.Vb 2
+\&  # Be quieter than normal
+\&  my $b = ExtUtils::CBuilder\->new( quiet => 1 );
+.Ve
+.IP have_compiler 4
+.IX Item "have_compiler"
+Returns true if the current system has a working C compiler and
+linker, false otherwise.  To determine this, we actually compile and
+link a sample C library.  The sample will be compiled in the system
+tempdir or, if that fails for some reason, in the current directory.
+.IP have_cplusplus 4
+.IX Item "have_cplusplus"
+Just like have_compiler but for C++ instead of C.
+.IP compile 4
+.IX Item "compile"
+Compiles a C source file and produces an object file.  The name of the
+object file is returned.  The source file is specified in a \f(CW\*(C`source\*(C'\fR
+parameter, which is required; the other parameters listed below are
+optional.
+.RS 4
+.ie n .IP """object_file""" 4
+.el .IP \f(CWobject_file\fR 4
+.IX Item "object_file"
+Specifies the name of the output file to create.  Otherwise the
+\&\f(CWobject_file()\fR method will be consulted, passing it the name of the
+\&\f(CW\*(C`source\*(C'\fR file.
+.ie n .IP """include_dirs""" 4
+.el .IP \f(CWinclude_dirs\fR 4
+.IX Item "include_dirs"
+Specifies any additional directories in which to search for header
+files.  May be given as a string indicating a single directory, or as
+a list reference indicating multiple directories.
+.ie n .IP """extra_compiler_flags""" 4
+.el .IP \f(CWextra_compiler_flags\fR 4
+.IX Item "extra_compiler_flags"
+Specifies any additional arguments to pass to the compiler.  Should be
+given as a list reference containing the arguments individually, or if
+this is not possible, as a string containing all the arguments
+together.
+.ie n .IP """C++""" 4
+.el .IP \f(CWC++\fR 4
+.IX Item "C++"
+Specifies that the source file is a C++ source file and sets appropriate
+compiler flags
+.RE
+.RS 4
+.Sp
+The operation of this method is also affected by the
+\&\f(CW\*(C`archlibexp\*(C'\fR, \f(CW\*(C`cccdlflags\*(C'\fR, \f(CW\*(C`ccflags\*(C'\fR, \f(CW\*(C`optimize\*(C'\fR, and \f(CW\*(C`cc\*(C'\fR
+entries in \f(CW\*(C`Config.pm\*(C'\fR.
+.RE
+.IP link 4
+.IX Item "link"
+Invokes the linker to produce a library file from object files.  In
+scalar context, the name of the library file is returned.  In list
+context, the library file and any temporary files created are
+returned.  A required \f(CW\*(C`objects\*(C'\fR parameter contains the name of the
+object files to process, either in a string (for one object file) or
+list reference (for one or more files).  The following parameters are
+optional:
+.RS 4
+.IP lib_file 4
+.IX Item "lib_file"
+Specifies the name of the output library file to create.  Otherwise
+the \f(CWlib_file()\fR method will be consulted, passing it the name of
+the first entry in \f(CW\*(C`objects\*(C'\fR.
+.IP module_name 4
+.IX Item "module_name"
+Specifies the name of the Perl module that will be created by linking.
+On platforms that need to do prelinking (Win32, OS/2, etc.) this is a
+required parameter.
+.IP extra_linker_flags 4
+.IX Item "extra_linker_flags"
+Any additional flags you wish to pass to the linker.
+.RE
+.RS 4
+.Sp
+On platforms where \f(CWneed_prelink()\fR returns true, \f(CWprelink()\fR
+will be called automatically.
+.Sp
+The operation of this method is also affected by the \f(CW\*(C`lddlflags\*(C'\fR,
+\&\f(CW\*(C`shrpenv\*(C'\fR, and \f(CW\*(C`ld\*(C'\fR entries in \f(CW\*(C`Config.pm\*(C'\fR.
+.RE
+.IP link_executable 4
+.IX Item "link_executable"
+Invokes the linker to produce an executable file from object files.  In
+scalar context, the name of the executable file is returned.  In list
+context, the executable file and any temporary files created are
+returned.  A required \f(CW\*(C`objects\*(C'\fR parameter contains the name of the
+object files to process, either in a string (for one object file) or
+list reference (for one or more files).  The optional parameters are
+the same as \f(CW\*(C`link\*(C'\fR with exception for
+.RS 4
+.IP exe_file 4
+.IX Item "exe_file"
+Specifies the name of the output executable file to create.  Otherwise
+the \f(CWexe_file()\fR method will be consulted, passing it the name of the
+first entry in \f(CW\*(C`objects\*(C'\fR.
+.RE
+.RS 4
+.RE
+.IP object_file 4
+.IX Item "object_file"
+.Vb 1
+\& my $object_file = $b\->object_file($source_file);
+.Ve
+.Sp
+Converts the name of a C source file to the most natural name of an
+output object file to create from it.  For instance, on Unix the
+source file \fIfoo.c\fR would result in the object file \fIfoo.o\fR.
+.IP lib_file 4
+.IX Item "lib_file"
+.Vb 1
+\& my $lib_file = $b\->lib_file($object_file);
+.Ve
+.Sp
+Converts the name of an object file to the most natural name of a
+output library file to create from it.  For instance, on Mac OS X the
+object file \fIfoo.o\fR would result in the library file \fIfoo.bundle\fR.
+.IP exe_file 4
+.IX Item "exe_file"
+.Vb 1
+\& my $exe_file = $b\->exe_file($object_file);
+.Ve
+.Sp
+Converts the name of an object file to the most natural name of an
+executable file to create from it.  For instance, on Mac OS X the
+object file \fIfoo.o\fR would result in the executable file \fIfoo\fR, and
+on Windows it would result in \fIfoo.exe\fR.
+.IP prelink 4
+.IX Item "prelink"
+On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary
+to perform some actions before invoking the linker.  The
+\&\f(CW\*(C`ExtUtils::Mksymlists\*(C'\fR module does this, writing files used by the
+linker during the creation of shared libraries for dynamic extensions.
+The names of any files written will be returned as a list.
+.Sp
+Several parameters correspond to \f(CWExtUtils::Mksymlists::Mksymlists()\fR
+options, as follows:
+.Sp
+.Vb 10
+\&    Mksymlists()   prelink()          type
+\&   \-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    NAME        |  dl_name          | string (required)
+\&    DLBASE      |  dl_base          | string
+\&    FILE        |  dl_file          | string
+\&    DL_VARS     |  dl_vars          | array reference
+\&    DL_FUNCS    |  dl_funcs         | hash reference
+\&    FUNCLIST    |  dl_func_list     | array reference
+\&    IMPORTS     |  dl_imports       | hash reference
+\&    VERSION     |  dl_version       | string
+.Ve
+.Sp
+Please see the documentation for \f(CW\*(C`ExtUtils::Mksymlists\*(C'\fR for the
+details of what these parameters do.
+.IP need_prelink 4
+.IX Item "need_prelink"
+Returns true on platforms where \f(CWprelink()\fR should be called
+during linking, and false otherwise.
+.IP extra_link_args_after_prelink 4
+.IX Item "extra_link_args_after_prelink"
+Returns list of extra arguments to give to the link command; the arguments
+are the same as for \fBprelink()\fR, with addition of array reference to the
+results of \fBprelink()\fR; this reference is indexed by key \f(CW\*(C`prelink_res\*(C'\fR.
+.SH "TO DO"
+.IX Header "TO DO"
+Currently this has only been tested on Unix and doesn't contain any of
+the Windows-specific code from the \f(CW\*(C`Module::Build\*(C'\fR project.  I'll do
+that next.
+.SH HISTORY
+.IX Header "HISTORY"
+This module is an outgrowth of the \f(CW\*(C`Module::Build\*(C'\fR project, to which
+there have been many contributors.  Notably, Randy W. Sims submitted
+lots of code to support 3 compilers on Windows and helped with various
+other platform-specific issues.  Ilya Zakharevich has contributed
+fixes for OS/2; John E. Malmberg and Peter Prymmer have done likewise
+for VMS.
+.SH SUPPORT
+.IX Header "SUPPORT"
+ExtUtils::CBuilder is maintained as part of the Perl 5 core.  Please
+submit any bug reports via the \fIperlbug\fR tool included with Perl 5.
+Bug reports will be included in the Perl 5 ticket system at
+<https://rt.perl.org>.
+.PP
+The Perl 5 source code is available at <https://perl5.git.perl.org/perl.git>
+and ExtUtils-CBuilder may be found in the \fIdist/ExtUtils\-CBuilder\fR directory
+of the repository.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Ken Williams, kwilliams@cpan.org
+.PP
+Additional contributions by The Perl 5 Porters.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (c) 2003\-2005 Ken Williams.  All rights reserved.
+.PP
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBperl\fR\|(1), \fBModule::Build\fR\|(3)