lib/ExtUtils/Liblist.pm

package ExtUtils::Liblist;

use vars qw($VERSION);
$VERSION = '1.01';

use File::Spec;
require ExtUtils::Liblist::Kid;
@ISA = qw(ExtUtils::Liblist::Kid File::Spec);

# Backwards compatibility with old interface.
sub ext {
    goto &ExtUtils::Liblist::Kid::ext;
}

sub lsdir {
  shift;
  my $rex = qr/$_[1]/;
  opendir DIR, $_[0];
  my @out = grep /$rex/, readdir DIR;
  closedir DIR;
  return @out;
}

__END__

=head1 NAME

ExtUtils::Liblist - determine libraries to use and how to use them

=head1 SYNOPSIS

  require ExtUtils::Liblist;

  $MM->ext($potential_libs, $verbose, $need_names);

  # Usually you can get away with:
  ExtUtils::Liblist->ext($potential_libs, $verbose, $need_names)

=head1 DESCRIPTION

This utility takes a list of libraries in the form C<-llib1 -llib2
-llib3> and returns lines suitable for inclusion in an extension
Makefile.  Extra library paths may be included with the form
C<-L/another/path> this will affect the searches for all subsequent
libraries.

It returns an array of four or five scalar values: EXTRALIBS,
BSLOADLIBS, LDLOADLIBS, LD_RUN_PATH, and, optionally, a reference to
the array of the filenames of actual libraries.  Some of these don't
mean anything unless on Unix.  See the details about those platform
specifics below.  The list of the filenames is returned only if
$need_names argument is true.

Dependent libraries can be linked in one of three ways:

=over 2

=item * For static extensions

by the ld command when the perl binary is linked with the extension
library. See EXTRALIBS below.

=item * For dynamic extensions at build/link time

by the ld command when the shared object is built/linked. See
LDLOADLIBS below.

=item * For dynamic extensions at load time

by the DynaLoader when the shared object is loaded. See BSLOADLIBS
below.

=back

=head2 EXTRALIBS

List of libraries that need to be linked with when linking a perl
binary which includes this extension. Only those libraries that
actually exist are included.  These are written to a file and used
when linking perl.

=head2 LDLOADLIBS and LD_RUN_PATH

List of those libraries which can or must be linked into the shared
library when created using ld. These may be static or dynamic
libraries.  LD_RUN_PATH is a colon separated list of the directories
in LDLOADLIBS. It is passed as an environment variable to the process
that links the shared library.

=head2 BSLOADLIBS

List of those libraries that are needed but can be linked in
dynamically at run time on this platform.  SunOS/Solaris does not need
this because ld records the information (from LDLOADLIBS) into the
object file.  This list is used to create a .bs (bootstrap) file.

=head1 PORTABILITY

This module deals with a lot of system dependencies and has quite a
few architecture specific C<if>s in the code.

=head2 VMS implementation

The version of ext() which is executed under VMS differs from the
Unix-OS/2 version in several respects:

=over 2

=item *

Input library and path specifications are accepted with or without the
C<-l> and C<-L> prefixes used by Unix linkers.  If neither prefix is
present, a token is considered a directory to search if it is in fact
a directory, and a library to search for otherwise.  Authors who wish
their extensions to be portable to Unix or OS/2 should use the Unix
prefixes, since the Unix-OS/2 version of ext() requires them.

=item *

Wherever possible, shareable images are preferred to object libraries,
and object libraries to plain object files.  In accordance with VMS
naming conventions, ext() looks for files named I<lib>shr and I<lib>rtl;
it also looks for I<lib>lib and libI<lib> to accommodate Unix conventions
used in some ported software.

=item *

For each library that is found, an appropriate directive for a linker options
file is generated.  The return values are space-separated strings of
these directives, rather than elements used on the linker command line.

=item *

LDLOADLIBS contains both the libraries found based on C<$potential_libs> and
the CRTLs, if any, specified in Config.pm.  EXTRALIBS contains just those
libraries found based on C<$potential_libs>.  BSLOADLIBS and LD_RUN_PATH
are always empty.

=back

In addition, an attempt is made to recognize several common Unix library
names, and filter them out or convert them to their VMS equivalents, as
appropriate.

In general, the VMS version of ext() should properly handle input from
extensions originally designed for a Unix or VMS environment.  If you
encounter problems, or discover cases where the search could be improved,
please let us know.

=head2 Win32 implementation

The version of ext() which is executed under Win32 differs from the
Unix-OS/2 version in several respects:

=over 2

=item *

If C<$potential_libs> is empty, the return value will be empty.
Otherwise, the libraries specified by C<$Config{perllibs}> (see Config.pm)
will be appended to the list of C<$potential_libs>.  The libraries
will be searched for in the directories specified in C<$potential_libs>,
C<$Config{libpth}>, and in C<$Config{installarchlib}/CORE>.
For each library that is found,  a space-separated list of fully qualified
library pathnames is generated.

=item *

Input library and path specifications are accepted with or without the
C<-l> and C<-L> prefixes used by Unix linkers.

An entry of the form C<-La:\foo> specifies the C<a:\foo> directory to look
for the libraries that follow.

An entry of the form C<-lfoo> specifies the library C<foo>, which may be
spelled differently depending on what kind of compiler you are using.  If
you are using GCC, it gets translated to C<libfoo.a>, but for other win32
compilers, it becomes C<foo.lib>.  If no files are found by those translated
names, one more attempt is made to find them using either C<foo.a> or
C<libfoo.lib>, depending on whether GCC or some other win32 compiler is
being used, respectively.

If neither the C<-L> or C<-l> prefix is present in an entry, the entry is
considered a directory to search if it is in fact a directory, and a
library to search for otherwise.  The C<$Config{lib_ext}> suffix will
be appended to any entries that are not directories and don't already have
the suffix.

Note that the C<-L> and C<-l> prefixes are B<not required>, but authors
who wish their extensions to be portable to Unix or OS/2 should use the
prefixes, since the Unix-OS/2 version of ext() requires them.

=item *

Entries cannot be plain object files, as many Win32 compilers will
not handle object files in the place of libraries.

=item *

Entries in C<$potential_libs> beginning with a colon and followed by
alphanumeric characters are treated as flags.  Unknown flags will be ignored.

An entry that matches C</:nodefault/i> disables the appending of default
libraries found in C<$Config{perllibs}> (this should be only needed very rarely).

An entry that matches C</:nosearch/i> disables all searching for
the libraries specified after it.  Translation of C<-Lfoo> and
C<-lfoo> still happens as appropriate (depending on compiler being used,
as reflected by C<$Config{cc}>), but the entries are not verified to be
valid files or directories.

An entry that matches C</:search/i> reenables searching for
the libraries specified after it.  You can put it at the end to
enable searching for default libraries specified by C<$Config{perllibs}>.

=item *

The libraries specified may be a mixture of static libraries and
import libraries (to link with DLLs).  Since both kinds are used
pretty transparently on the Win32 platform, we do not attempt to
distinguish between them.

=item *

LDLOADLIBS and EXTRALIBS are always identical under Win32, and BSLOADLIBS
and LD_RUN_PATH are always empty (this may change in future).

=item *

You must make sure that any paths and path components are properly
surrounded with double-quotes if they contain spaces. For example,
C<$potential_libs> could be (literally):

        "-Lc:\Program Files\vc\lib" msvcrt.lib "la test\foo bar.lib"

Note how the first and last entries are protected by quotes in order
to protect the spaces.

=item *

Since this module is most often used only indirectly from extension
C<Makefile.PL> files, here is an example C<Makefile.PL> entry to add
a library to the build process for an extension:

        LIBS => ['-lgl']

When using GCC, that entry specifies that MakeMaker should first look
for C<libgl.a> (followed by C<gl.a>) in all the locations specified by
C<$Config{libpth}>.

When using a compiler other than GCC, the above entry will search for
C<gl.lib> (followed by C<libgl.lib>).

If the library happens to be in a location not in C<$Config{libpth}>,
you need:

        LIBS => ['-Lc:\gllibs -lgl']

Here is a less often used example:

        LIBS => ['-lgl', ':nosearch -Ld:\mesalibs -lmesa -luser32']

This specifies a search for library C<gl> as before.  If that search
fails to find the library, it looks at the next item in the list. The
C<:nosearch> flag will prevent searching for the libraries that follow,
so it simply returns the value as C<-Ld:\mesalibs -lmesa -luser32>,
since GCC can use that value as is with its linker.

When using the Visual C compiler, the second item is returned as
C<-libpath:d:\mesalibs mesa.lib user32.lib>.

When using the Borland compiler, the second item is returned as
C<-Ld:\mesalibs mesa.lib user32.lib>, and MakeMaker takes care of
moving the C<-Ld:\mesalibs> to the correct place in the linker
command line.

=back


=head1 SEE ALSO

L<ExtUtils::MakeMaker>

=cut

Revision:	1.1
Committed:	Thu Jun 30 14:27:10 2005 UTC (21 years, 4 months ago) by root
Branch:	MAIN
CVS Tags:	PERL-5-8-7, HEAD
Branch point for:	PERL
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	package ExtUtils::Liblist;
2
3			use vars qw($VERSION);
4			$VERSION = '1.01';
5
6			use File::Spec;
7			require ExtUtils::Liblist::Kid;
8			@ISA = qw(ExtUtils::Liblist::Kid File::Spec);
9
10			# Backwards compatibility with old interface.
11			sub ext {
12			goto &ExtUtils::Liblist::Kid::ext;
13			}
14
15			sub lsdir {
16			shift;
17			my $rex = qr/$_[1]/;
18			opendir DIR, $_[0];
19			my @out = grep /$rex/, readdir DIR;
20			closedir DIR;
21			return @out;
22			}
23
24			__END__
25
26			=head1 NAME
27
28			ExtUtils::Liblist - determine libraries to use and how to use them
29
30			=head1 SYNOPSIS
31
32			require ExtUtils::Liblist;
33
34			$MM->ext($potential_libs, $verbose, $need_names);
35
36			# Usually you can get away with:
37			ExtUtils::Liblist->ext($potential_libs, $verbose, $need_names)
38
39			=head1 DESCRIPTION
40
41			This utility takes a list of libraries in the form C<-llib1 -llib2
42			-llib3> and returns lines suitable for inclusion in an extension
43			Makefile. Extra library paths may be included with the form
44			C<-L/another/path> this will affect the searches for all subsequent
45			libraries.
46
47			It returns an array of four or five scalar values: EXTRALIBS,
48			BSLOADLIBS, LDLOADLIBS, LD_RUN_PATH, and, optionally, a reference to
49			the array of the filenames of actual libraries. Some of these don't
50			mean anything unless on Unix. See the details about those platform
51			specifics below. The list of the filenames is returned only if
52			$need_names argument is true.
53
54			Dependent libraries can be linked in one of three ways:
55
56			=over 2
57
58			=item * For static extensions
59
60			by the ld command when the perl binary is linked with the extension
61			library. See EXTRALIBS below.
62
63			=item * For dynamic extensions at build/link time
64
65			by the ld command when the shared object is built/linked. See
66			LDLOADLIBS below.
67
68			=item * For dynamic extensions at load time
69
70			by the DynaLoader when the shared object is loaded. See BSLOADLIBS
71			below.
72
73			=back
74
75			=head2 EXTRALIBS
76
77			List of libraries that need to be linked with when linking a perl
78			binary which includes this extension. Only those libraries that
79			actually exist are included. These are written to a file and used
80			when linking perl.
81
82			=head2 LDLOADLIBS and LD_RUN_PATH
83
84			List of those libraries which can or must be linked into the shared
85			library when created using ld. These may be static or dynamic
86			libraries. LD_RUN_PATH is a colon separated list of the directories
87			in LDLOADLIBS. It is passed as an environment variable to the process
88			that links the shared library.
89
90			=head2 BSLOADLIBS
91
92			List of those libraries that are needed but can be linked in
93			dynamically at run time on this platform. SunOS/Solaris does not need
94			this because ld records the information (from LDLOADLIBS) into the
95			object file. This list is used to create a .bs (bootstrap) file.
96
97			=head1 PORTABILITY
98
99			This module deals with a lot of system dependencies and has quite a
100			few architecture specific C<if>s in the code.
101
102			=head2 VMS implementation
103
104			The version of ext() which is executed under VMS differs from the
105			Unix-OS/2 version in several respects:
106
107			=over 2
108
109			=item *
110
111			Input library and path specifications are accepted with or without the
112			C<-l> and C<-L> prefixes used by Unix linkers. If neither prefix is
113			present, a token is considered a directory to search if it is in fact
114			a directory, and a library to search for otherwise. Authors who wish
115			their extensions to be portable to Unix or OS/2 should use the Unix
116			prefixes, since the Unix-OS/2 version of ext() requires them.
117
118			=item *
119
120			Wherever possible, shareable images are preferred to object libraries,
121			and object libraries to plain object files. In accordance with VMS
122			naming conventions, ext() looks for files named I<lib>shr and I<lib>rtl;
123			it also looks for I<lib>lib and libI<lib> to accommodate Unix conventions
124			used in some ported software.
125
126			=item *
127
128			For each library that is found, an appropriate directive for a linker options
129			file is generated. The return values are space-separated strings of
130			these directives, rather than elements used on the linker command line.
131
132			=item *
133
134			LDLOADLIBS contains both the libraries found based on C<$potential_libs> and
135			the CRTLs, if any, specified in Config.pm. EXTRALIBS contains just those
136			libraries found based on C<$potential_libs>. BSLOADLIBS and LD_RUN_PATH
137			are always empty.
138
139			=back
140
141			In addition, an attempt is made to recognize several common Unix library
142			names, and filter them out or convert them to their VMS equivalents, as
143			appropriate.
144
145			In general, the VMS version of ext() should properly handle input from
146			extensions originally designed for a Unix or VMS environment. If you
147			encounter problems, or discover cases where the search could be improved,
148			please let us know.
149
150			=head2 Win32 implementation
151
152			The version of ext() which is executed under Win32 differs from the
153			Unix-OS/2 version in several respects:
154
155			=over 2
156
157			=item *
158
159			If C<$potential_libs> is empty, the return value will be empty.
160			Otherwise, the libraries specified by C<$Config{perllibs}> (see Config.pm)
161			will be appended to the list of C<$potential_libs>. The libraries
162			will be searched for in the directories specified in C<$potential_libs>,
163			C<$Config{libpth}>, and in C<$Config{installarchlib}/CORE>.
164			For each library that is found, a space-separated list of fully qualified
165			library pathnames is generated.
166
167			=item *
168
169			Input library and path specifications are accepted with or without the
170			C<-l> and C<-L> prefixes used by Unix linkers.
171
172			An entry of the form C<-La:\foo> specifies the C<a:\foo> directory to look
173			for the libraries that follow.
174
175			An entry of the form C<-lfoo> specifies the library C<foo>, which may be
176			spelled differently depending on what kind of compiler you are using. If
177			you are using GCC, it gets translated to C<libfoo.a>, but for other win32
178			compilers, it becomes C<foo.lib>. If no files are found by those translated
179			names, one more attempt is made to find them using either C<foo.a> or
180			C<libfoo.lib>, depending on whether GCC or some other win32 compiler is
181			being used, respectively.
182
183			If neither the C<-L> or C<-l> prefix is present in an entry, the entry is
184			considered a directory to search if it is in fact a directory, and a
185			library to search for otherwise. The C<$Config{lib_ext}> suffix will
186			be appended to any entries that are not directories and don't already have
187			the suffix.
188
189			Note that the C<-L> and C<-l> prefixes are B<not required>, but authors
190			who wish their extensions to be portable to Unix or OS/2 should use the
191			prefixes, since the Unix-OS/2 version of ext() requires them.
192
193			=item *
194
195			Entries cannot be plain object files, as many Win32 compilers will
196			not handle object files in the place of libraries.
197
198			=item *
199
200			Entries in C<$potential_libs> beginning with a colon and followed by
201			alphanumeric characters are treated as flags. Unknown flags will be ignored.
202
203			An entry that matches C</:nodefault/i> disables the appending of default
204			libraries found in C<$Config{perllibs}> (this should be only needed very rarely).
205
206			An entry that matches C</:nosearch/i> disables all searching for
207			the libraries specified after it. Translation of C<-Lfoo> and
208			C<-lfoo> still happens as appropriate (depending on compiler being used,
209			as reflected by C<$Config{cc}>), but the entries are not verified to be
210			valid files or directories.
211
212			An entry that matches C</:search/i> reenables searching for
213			the libraries specified after it. You can put it at the end to
214			enable searching for default libraries specified by C<$Config{perllibs}>.
215
216			=item *
217
218			The libraries specified may be a mixture of static libraries and
219			import libraries (to link with DLLs). Since both kinds are used
220			pretty transparently on the Win32 platform, we do not attempt to
221			distinguish between them.
222
223			=item *
224
225			LDLOADLIBS and EXTRALIBS are always identical under Win32, and BSLOADLIBS
226			and LD_RUN_PATH are always empty (this may change in future).
227
228			=item *
229
230			You must make sure that any paths and path components are properly
231			surrounded with double-quotes if they contain spaces. For example,
232			C<$potential_libs> could be (literally):
233
234			"-Lc:\Program Files\vc\lib" msvcrt.lib "la test\foo bar.lib"
235
236			Note how the first and last entries are protected by quotes in order
237			to protect the spaces.
238
239			=item *
240
241			Since this module is most often used only indirectly from extension
242			C<Makefile.PL> files, here is an example C<Makefile.PL> entry to add
243			a library to the build process for an extension:
244
245			LIBS => ['-lgl']
246
247			When using GCC, that entry specifies that MakeMaker should first look
248			for C<libgl.a> (followed by C<gl.a>) in all the locations specified by
249			C<$Config{libpth}>.
250
251			When using a compiler other than GCC, the above entry will search for
252			C<gl.lib> (followed by C<libgl.lib>).
253
254			If the library happens to be in a location not in C<$Config{libpth}>,
255			you need:
256
257			LIBS => ['-Lc:\gllibs -lgl']
258
259			Here is a less often used example:
260
261			LIBS => ['-lgl', ':nosearch -Ld:\mesalibs -lmesa -luser32']
262
263			This specifies a search for library C<gl> as before. If that search
264			fails to find the library, it looks at the next item in the list. The
265			C<:nosearch> flag will prevent searching for the libraries that follow,
266			so it simply returns the value as C<-Ld:\mesalibs -lmesa -luser32>,
267			since GCC can use that value as is with its linker.
268
269			When using the Visual C compiler, the second item is returned as
270			C<-libpath:d:\mesalibs mesa.lib user32.lib>.
271
272			When using the Borland compiler, the second item is returned as
273			C<-Ld:\mesalibs mesa.lib user32.lib>, and MakeMaker takes care of
274			moving the C<-Ld:\mesalibs> to the correct place in the linker
275			command line.
276
277			=back
278
279
280			=head1 SEE ALSO
281
282			L<ExtUtils::MakeMaker>
283
284			=cut
285