1N/Apackage ExtUtils::Liblist;
1N/A
1N/Ause vars qw($VERSION);
1N/A$VERSION = '1.01';
1N/A
1N/Ause File::Spec;
1N/Arequire ExtUtils::Liblist::Kid;
1N/A@ISA = qw(ExtUtils::Liblist::Kid File::Spec);
1N/A
1N/A# Backwards compatibility with old interface.
1N/Asub ext {
1N/A goto &ExtUtils::Liblist::Kid::ext;
1N/A}
1N/A
1N/Asub lsdir {
1N/A shift;
1N/A my $rex = qr/$_[1]/;
1N/A opendir DIR, $_[0];
1N/A my @out = grep /$rex/, readdir DIR;
1N/A closedir DIR;
1N/A return @out;
1N/A}
1N/A
1N/A__END__
1N/A
1N/A=head1 NAME
1N/A
1N/AExtUtils::Liblist - determine libraries to use and how to use them
1N/A
1N/A=head1 SYNOPSIS
1N/A
1N/A require ExtUtils::Liblist;
1N/A
1N/A $MM->ext($potential_libs, $verbose, $need_names);
1N/A
1N/A # Usually you can get away with:
1N/A ExtUtils::Liblist->ext($potential_libs, $verbose, $need_names)
1N/A
1N/A=head1 DESCRIPTION
1N/A
1N/AThis utility takes a list of libraries in the form C<-llib1 -llib2
1N/A-llib3> and returns lines suitable for inclusion in an extension
1N/AMakefile. Extra library paths may be included with the form
1N/AC<-L/another/path> this will affect the searches for all subsequent
1N/Alibraries.
1N/A
1N/AIt returns an array of four or five scalar values: EXTRALIBS,
1N/ABSLOADLIBS, LDLOADLIBS, LD_RUN_PATH, and, optionally, a reference to
1N/Athe array of the filenames of actual libraries. Some of these don't
1N/Amean anything unless on Unix. See the details about those platform
1N/Aspecifics below. The list of the filenames is returned only if
1N/A$need_names argument is true.
1N/A
1N/ADependent libraries can be linked in one of three ways:
1N/A
1N/A=over 2
1N/A
1N/A=item * For static extensions
1N/A
1N/Aby the ld command when the perl binary is linked with the extension
1N/Alibrary. See EXTRALIBS below.
1N/A
1N/A=item * For dynamic extensions at build/link time
1N/A
1N/Aby the ld command when the shared object is built/linked. See
1N/ALDLOADLIBS below.
1N/A
1N/A=item * For dynamic extensions at load time
1N/A
1N/Aby the DynaLoader when the shared object is loaded. See BSLOADLIBS
1N/Abelow.
1N/A
1N/A=back
1N/A
1N/A=head2 EXTRALIBS
1N/A
1N/AList of libraries that need to be linked with when linking a perl
1N/Abinary which includes this extension. Only those libraries that
1N/Aactually exist are included. These are written to a file and used
1N/Awhen linking perl.
1N/A
1N/A=head2 LDLOADLIBS and LD_RUN_PATH
1N/A
1N/AList of those libraries which can or must be linked into the shared
1N/Alibrary when created using ld. These may be static or dynamic
1N/Alibraries. LD_RUN_PATH is a colon separated list of the directories
1N/Ain LDLOADLIBS. It is passed as an environment variable to the process
1N/Athat links the shared library.
1N/A
1N/A=head2 BSLOADLIBS
1N/A
1N/AList of those libraries that are needed but can be linked in
1N/Adynamically at run time on this platform. SunOS/Solaris does not need
1N/Athis because ld records the information (from LDLOADLIBS) into the
1N/Aobject file. This list is used to create a .bs (bootstrap) file.
1N/A
1N/A=head1 PORTABILITY
1N/A
1N/AThis module deals with a lot of system dependencies and has quite a
1N/Afew architecture specific C<if>s in the code.
1N/A
1N/A=head2 VMS implementation
1N/A
1N/AThe version of ext() which is executed under VMS differs from the
1N/AUnix-OS/2 version in several respects:
1N/A
1N/A=over 2
1N/A
1N/A=item *
1N/A
1N/AInput library and path specifications are accepted with or without the
1N/AC<-l> and C<-L> prefixes used by Unix linkers. If neither prefix is
1N/Apresent, a token is considered a directory to search if it is in fact
1N/Aa directory, and a library to search for otherwise. Authors who wish
1N/Atheir extensions to be portable to Unix or OS/2 should use the Unix
1N/Aprefixes, since the Unix-OS/2 version of ext() requires them.
1N/A
1N/A=item *
1N/A
1N/AWherever possible, shareable images are preferred to object libraries,
1N/Aand object libraries to plain object files. In accordance with VMS
1N/Anaming conventions, ext() looks for files named I<lib>shr and I<lib>rtl;
1N/Ait also looks for I<lib>lib and libI<lib> to accommodate Unix conventions
1N/Aused in some ported software.
1N/A
1N/A=item *
1N/A
1N/AFor each library that is found, an appropriate directive for a linker options
1N/Afile is generated. The return values are space-separated strings of
1N/Athese directives, rather than elements used on the linker command line.
1N/A
1N/A=item *
1N/A
1N/ALDLOADLIBS contains both the libraries found based on C<$potential_libs> and
1N/Athe CRTLs, if any, specified in Config.pm. EXTRALIBS contains just those
1N/Alibraries found based on C<$potential_libs>. BSLOADLIBS and LD_RUN_PATH
1N/Aare always empty.
1N/A
1N/A=back
1N/A
1N/AIn addition, an attempt is made to recognize several common Unix library
1N/Anames, and filter them out or convert them to their VMS equivalents, as
1N/Aappropriate.
1N/A
1N/AIn general, the VMS version of ext() should properly handle input from
1N/Aextensions originally designed for a Unix or VMS environment. If you
1N/Aencounter problems, or discover cases where the search could be improved,
1N/Aplease let us know.
1N/A
1N/A=head2 Win32 implementation
1N/A
1N/AThe version of ext() which is executed under Win32 differs from the
1N/AUnix-OS/2 version in several respects:
1N/A
1N/A=over 2
1N/A
1N/A=item *
1N/A
1N/AIf C<$potential_libs> is empty, the return value will be empty.
1N/AOtherwise, the libraries specified by C<$Config{perllibs}> (see Config.pm)
1N/Awill be appended to the list of C<$potential_libs>. The libraries
1N/Awill be searched for in the directories specified in C<$potential_libs>,
1N/AC<$Config{libpth}>, and in C<$Config{installarchlib}/CORE>.
1N/AFor each library that is found, a space-separated list of fully qualified
1N/Alibrary pathnames is generated.
1N/A
1N/A=item *
1N/A
1N/AInput library and path specifications are accepted with or without the
1N/AC<-l> and C<-L> prefixes used by Unix linkers.
1N/A
1N/AAn entry of the form C<-La:\foo> specifies the C<a:\foo> directory to look
1N/Afor the libraries that follow.
1N/A
1N/AAn entry of the form C<-lfoo> specifies the library C<foo>, which may be
1N/Aspelled differently depending on what kind of compiler you are using. If
1N/Ayou are using GCC, it gets translated to C<libfoo.a>, but for other win32
1N/Acompilers, it becomes C<foo.lib>. If no files are found by those translated
1N/Anames, one more attempt is made to find them using either C<foo.a> or
1N/AC<libfoo.lib>, depending on whether GCC or some other win32 compiler is
1N/Abeing used, respectively.
1N/A
1N/AIf neither the C<-L> or C<-l> prefix is present in an entry, the entry is
1N/Aconsidered a directory to search if it is in fact a directory, and a
1N/Alibrary to search for otherwise. The C<$Config{lib_ext}> suffix will
1N/Abe appended to any entries that are not directories and don't already have
1N/Athe suffix.
1N/A
1N/ANote that the C<-L> and C<-l> prefixes are B<not required>, but authors
1N/Awho wish their extensions to be portable to Unix or OS/2 should use the
1N/Aprefixes, since the Unix-OS/2 version of ext() requires them.
1N/A
1N/A=item *
1N/A
1N/AEntries cannot be plain object files, as many Win32 compilers will
1N/Anot handle object files in the place of libraries.
1N/A
1N/A=item *
1N/A
1N/AEntries in C<$potential_libs> beginning with a colon and followed by
1N/Aalphanumeric characters are treated as flags. Unknown flags will be ignored.
1N/A
1N/AAn entry that matches C</:nodefault/i> disables the appending of default
1N/Alibraries found in C<$Config{perllibs}> (this should be only needed very rarely).
1N/A
1N/AAn entry that matches C</:nosearch/i> disables all searching for
1N/Athe libraries specified after it. Translation of C<-Lfoo> and
1N/AC<-lfoo> still happens as appropriate (depending on compiler being used,
1N/Aas reflected by C<$Config{cc}>), but the entries are not verified to be
1N/Avalid files or directories.
1N/A
1N/AAn entry that matches C</:search/i> reenables searching for
1N/Athe libraries specified after it. You can put it at the end to
1N/Aenable searching for default libraries specified by C<$Config{perllibs}>.
1N/A
1N/A=item *
1N/A
1N/AThe libraries specified may be a mixture of static libraries and
1N/Aimport libraries (to link with DLLs). Since both kinds are used
1N/Apretty transparently on the Win32 platform, we do not attempt to
1N/Adistinguish between them.
1N/A
1N/A=item *
1N/A
1N/ALDLOADLIBS and EXTRALIBS are always identical under Win32, and BSLOADLIBS
1N/Aand LD_RUN_PATH are always empty (this may change in future).
1N/A
1N/A=item *
1N/A
1N/AYou must make sure that any paths and path components are properly
1N/Asurrounded with double-quotes if they contain spaces. For example,
1N/AC<$potential_libs> could be (literally):
1N/A
1N/A "-Lc:\Program Files\vc\lib" msvcrt.lib "la test\foo bar.lib"
1N/A
1N/ANote how the first and last entries are protected by quotes in order
1N/Ato protect the spaces.
1N/A
1N/A=item *
1N/A
1N/ASince this module is most often used only indirectly from extension
1N/AC<Makefile.PL> files, here is an example C<Makefile.PL> entry to add
1N/Aa library to the build process for an extension:
1N/A
1N/A LIBS => ['-lgl']
1N/A
1N/AWhen using GCC, that entry specifies that MakeMaker should first look
1N/Afor C<libgl.a> (followed by C<gl.a>) in all the locations specified by
1N/AC<$Config{libpth}>.
1N/A
1N/AWhen using a compiler other than GCC, the above entry will search for
1N/AC<gl.lib> (followed by C<libgl.lib>).
1N/A
1N/AIf the library happens to be in a location not in C<$Config{libpth}>,
1N/Ayou need:
1N/A
1N/A LIBS => ['-Lc:\gllibs -lgl']
1N/A
1N/AHere is a less often used example:
1N/A
1N/A LIBS => ['-lgl', ':nosearch -Ld:\mesalibs -lmesa -luser32']
1N/A
1N/AThis specifies a search for library C<gl> as before. If that search
1N/Afails to find the library, it looks at the next item in the list. The
1N/AC<:nosearch> flag will prevent searching for the libraries that follow,
1N/Aso it simply returns the value as C<-Ld:\mesalibs -lmesa -luser32>,
1N/Asince GCC can use that value as is with its linker.
1N/A
1N/AWhen using the Visual C compiler, the second item is returned as
1N/AC<-libpath:d:\mesalibs mesa.lib user32.lib>.
1N/A
1N/AWhen using the Borland compiler, the second item is returned as
1N/AC<-Ld:\mesalibs mesa.lib user32.lib>, and MakeMaker takes care of
1N/Amoving the C<-Ld:\mesalibs> to the correct place in the linker
1N/Acommand line.
1N/A
1N/A=back
1N/A
1N/A
1N/A=head1 SEE ALSO
1N/A
1N/AL<ExtUtils::MakeMaker>
1N/A
1N/A=cut
1N/A