@samp{-lm}, the library libhello.la depended upon. Nice, huh?
Since libtool created a wrapper script, you should use libtool to
-install it and debug it too. However, since the program does not depend
+install it and debug it too. However, since the program does not depend
on any uninstalled libtool library, it is probably usable even without
-the wrapper script. Libtool could probably be made smarter to avoid the
+the wrapper script. Libtool could probably be made smarter to avoid the
creation of the wrapper script in this case, but this is left as an
exercise for the reader.
But libtool libraries are more than just collections of object files:
they can also carry library dependency information, which old archives
-do not. If you want to create a libtool static convenience library, you
+do not. If you want to create a libtool static convenience library, you
can omit the @samp{-rpath} flag and use @samp{-static} to indicate that
you're only interested in a static library. When you link a program
with such a library, libtool will actually link all object files and
(@pxref{Dlopened modules}).
@item -export-symbols @var{symfile}
-Tells the linker to export only the symbols listed in @var{symfile}.
-The symbol file should end in @samp{.sym} and must contain the name of one
+Tells the linker to export only the symbols listed in @var{symfile}.
+The symbol file should end in @samp{.sym} and must contain the name of one
symbol per line. This option has no effect on some platforms.
By default all symbols are exported.
executable.
@item -module
-Creates a library that can be dlopened (@pxref{Dlopened modules}).
+Creates a library that can be dlopened (@pxref{Dlopened modules}).
This option doesn't work for programs.
Module names don't need to be prefixed with 'lib'.
-In order to prevent name clashes, however, 'libname' and 'name'
+In order to prevent name clashes, however, 'libname' and 'name'
must not be used at the same time in your package.
@item -no-fast-install
comma-separated @var{pkgs} list, and every other package with
@samp{--disable-shared}. The @samp{--enable-static=@var{pkgs}} flag
behaves similarly, but it uses @samp{--enable-static} and
-@samp{--disable-static}. The same applies to the
+@samp{--disable-static}. The same applies to the
@samp{--enable-fast-install=@var{pkgs}} flag, which uses
@samp{--enable-fast-install} and @samp{--disable-fast-install}.
The package name @samp{default} matches any packages which have not set
their name in the @code{PACKAGE} environment variable.
-This macro also sets the shell variable @var{LIBTOOL_DEPS}, that you can
+This macro also sets the shell variable @var{LIBTOOL_DEPS}, that you can
use to automatically update the libtool script if it becomes
out-of-date. In order to do that, add to your @file{configure.in}:
@end defmac
The tests in @code{AC_PROG_LIBTOOL} also recognize the following
-environment variables:
+environment variables:
@defvar CC
The C compiler that will be used by the generated @code{libtool}. If
@end defvar
@defvar DLLTOOL
-Program to use rather than checking for @code{dlltool}. Only meaningful
+Program to use rather than checking for @code{dlltool}. Only meaningful
for Cygwin/MS-Windows.
@end defvar
@defvar OBJDUMP
-Program to use rather than checking for @code{objdump}. Only meaningful
+Program to use rather than checking for @code{objdump}. Only meaningful
for Cygwin/MS-Windows.
@end defvar
@emph{after} @samp{AC_PROG_LIBTOOL}), libtool will assume no dlopening
mechanism is available, and will try to simulate it.
-This chapter discusses how you as a dlopen application developer might
+This chapter discusses how you as a dlopen application developer might
use libtool to generate dlopen-accessible modules.
@menu
in order to be dynamically resolved with the @code{dlsym} (or
equivalent) function.
-Libtool provides the @samp{-export-dynamic} and @samp{-module}
-link flags (@pxref{Link mode}), which do this declaration.
-You need to use these flags if you are linking an application program that
+Libtool provides the @samp{-export-dynamic} and @samp{-module}
+link flags (@pxref{Link mode}), which do this declaration.
+You need to use these flags if you are linking an application program that
dlopens other modules or a libtool library that will also be dlopened.
For example, if we wanted to build a shared library, @file{libhello},
generic pointer to the appropriate object, such as @code{&fprintf}.
@end deftypefn
-@deftypevar {const lt_dlsymlist *}lt_preloaded_symbols
+@deftypevar {const lt_dlsymlist *} lt_preloaded_symbols
An array of @var{lt_symbol} structures, representing all the preloaded
-symbols linked into the program. For each @samp{-dlpreloaded} file
-there is an element with the @var{name} of the file and a @var{address}
+symbols linked into the program. For each @samp{-dlpreloaded} file
+there is an element with the @var{name} of the file and a @var{address}
of @code{0}, followed by all symbols exported from this file.
For the executable itself the special name @@PROGRAM@@ is used.
The last element has a @var{name} and @var{address} of @code{0}.
@cindex names of dynamic modules
@cindex dynamic modules, names
-After a library has been linked with @samp{-module}, it can be dlopened.
+After a library has been linked with @samp{-module}, it can be dlopened.
Unfortunately, because of the variation in library names,
your package needs to determine the correct file to dlopen.
@item
Dlopen functions are generally only available on shared library
platforms. If you want your package to be portable to static platforms,
-you have to use either libltdl (@pxref{Using libltdl}) or develop your
+you have to use either libltdl (@pxref{Using libltdl}) or develop your
own alternatives to dlopening dynamic code.
Most reasonable solutions involve writing wrapper functions for the
@code{dlopen} family, which do package-specific tricks when dlopening
@end deftp
@deftp {Type} lt_dlhandle
-@code{lt_dlhandle} is a module "handle".
+@code{lt_dlhandle} is a module "handle".
Every lt_dlopened module has a handle associated with it.
@end deftp
@deftypefun int lt_dlexit (void)
Shut down libltdl and close all modules.
-This function will only then shut down libltdl when it was called as
+This function will only then shut down libltdl when it was called as
many times as @code{lt_dlinit} has been successfully called.
Return 0 on success, otherwise the number of errors.
@end deftypefun
@deftypefun lt_dlhandle lt_dlopen (const char *@var{filename})
Open the module with the file name @var{filename} and return a
handle for it. @code{lt_dlopen} is able to open libtool dynamic
-modules, preloaded static modules, the program itself and
-native dynamic libraries.
+modules, preloaded static modules, the program itself and
+native dynamic libraries.
Unresolved symbols in the module are resolved using its dependency
libraries (not implemented yet) and previously dlopened modules. If the
executable using this module was linked with the @code{-export-dynamic}
flag, then the global symbols in the executable will also be used to
resolve references in the module.
-
+
If @var{filename} is @code{NULL} and the program was linked with
@code{-export-dynamic} or @code{-dlopen self}, @code{lt_dlopen} will
return a handle for the program itself, which can be used to access its
If libltdl cannot find the library and the file name @var{filename} does
not have a directory component it will additionally search in the
following search paths for the module (in the order as follows):
-
+
@enumerate 1
@item user-defined search path:
This search path can be set by the program using the
functions @code{lt_dlsetsearchpath} and @code{lt_dladdsearchdir}.
-
+
@item libltdl's search path:
This search path is the value of the environment variable
@var{LTDL_LIBRARY_PATH}.
-
+
@item system library search path:
-The system dependent library search path
+The system dependent library search path
(e.g. on Linux it is @var{LD_LIBRARY_PATH}).
@end enumerate
Each search path must be a colon-separated list of absolute directories,
for example, @code{"/usr/lib/mypkg:/lib/foo"}.
-
+
If the same module is loaded several times, the same handle is returned.
If @code{lt_dlopen} fails for any reason, it returns @code{NULL}.
@end deftypefun
@enumerate 1
@item the libtool archive extension @samp{.la}
-@item the extension used for native dynamic libraries on the host platform,
+@item the extension used for native dynamic libraries on the host platform,
e.g., @samp{.so}, @samp{.sl}, etc.
@end enumerate
-This lookup strategy was designed to allow programs that don't
-have knowledge about native dynamic libraries naming conventions
+This lookup strategy was designed to allow programs that don't
+have knowledge about native dynamic libraries naming conventions
to be able to @code{dlopen} such libraries as well as libtool modules
transparently.
@end deftypefun
then the module is unloaded.
Return 0 on success.
@end deftypefun
-
+
@deftypefun lt_ptr lt_dlsym (lt_dlhandle @var{handle}, const char *@var{name})
-Return the address in the module @var{handle}, where the symbol given
+Return the address in the module @var{handle}, where the symbol given
by the null-terminated string @var{name} is loaded.
If the symbol cannot be found, @code{NULL} is returned.
@end deftypefun
-
+
@deftypefun {const char *}lt_dlerror (void)
-Return a human readable string describing the most
+Return a human readable string describing the most
recent error that occurred from any of libltdl's functions.
Return @code{NULL} if no errors have occurred since initialization
or since it was last called.
@end deftypefun
-
+
@deftypefun int lt_dlpreload (const lt_dlsymlist *@var{preloaded})
Register the list of preloaded modules @var{preloaded}.
If @var{preloaded} is @code{NULL}, then all previously registered
@defmac LTDL_SET_PRELOADED_SYMBOLS()
Set the default list of preloaded symbols.
-Should be used in your program to initialize libltdl's
+Should be used in your program to initialize libltdl's
list of preloaded modules.
@example
@end defmac
@deftypefun int lt_dladdsearchdir (const char *@var{search_dir})
-Add the search directory @var{search_dir} to the user-defined library
+Add the search directory @var{search_dir} to the user-defined library
search path. Return 0 on success.
@end deftypefun
@deftypefun {const lt_dlinfo *}lt_dlgetinfo (lt_dlhandle @var{handle})
Return a pointer to a struct that contains some information about
the module @var{handle}. The contents of the struct must not be modified.
-Return @code{NULL} on failure.
+Return @code{NULL} on failure.
@end deftypefun
@deftypefun int lt_dlforeach (int (*@var{func})(lt_dlhandle @var{handle}, lt_ptr @var{data}), lt_ptr @var{data})
Otherwise 0 is returned.
@end deftypefun
-@deftypevar {lt_ptr (*) (size_t @var{size})} lt_dlmalloc
-@deftypevarx {void (*) (lt_ptr @var{ptr})} lt_dlfree
+@deftypevar {lt_ptr (*) (size_t @var{size})} lt_dlmalloc
+@deftypevarx {void (*) (lt_ptr @var{ptr})} lt_dlfree
These variables are set to @code{malloc} and @code{free}, by default,
but you can set them to any other functions that provides equivalent
functionality. However, you must not modify their values after calling
Internal symbols must be named in such a way that they won't conflict
with other modules, for example, by prefixing them with "_modulename_".
Although some platforms support having the same symbols defined more than
-once it is generally not portable and it makes it impossible to dlpreopen
-such modules. libltdl will automatically cut the prefix off to get
+once it is generally not portable and it makes it impossible to dlpreopen
+such modules. libltdl will automatically cut the prefix off to get
the real name of the symbol. Additionally, it supports modules which
don't use a prefix so that you can also dlopen non-libtool modules.
@file{foo1.c} gives an example of a portable libtool module.
-Exported symbols are prefixed with "foo1_LTX_", internal symbols
-with "_foo1_". Aliases are defined at the beginning so that the code
-is more readable.
+Exported symbols are prefixed with "foo1_LTX_", internal symbols
+with "_foo1_". Aliases are defined at the beginning so that the code
+is more readable.
@example
/* aliases for the exported symbols */
@end example
@noindent
-The @file{Makefile.am} contains the necessary rules to build the
+The @file{Makefile.am} contains the necessary rules to build the
module @file{foo1.la}:
@example
@section How to distribute libltdl with your package
Even though libltdl is installed together with libtool, you may wish to
-include libltdl in the distribution of your package, for the convenience
+include libltdl in the distribution of your package, for the convenience
of users of your package that don't have libtool or libltdl installed.
In this case, you must decide whether to manually add the @code{ltdl}
objects to your package, or else which flavor of libltdl you want to use:
One advantage of the convenience library is that it is not installed, so
the fact that you use libltdl will not be apparent to the user, and it
will not overwrite a pre-installed version of libltdl a user might have.
-On the other hand, if you want to upgrade libltdl for any reason
-(e.g. a bugfix) you'll have to recompile your package instead of just
+On the other hand, if you want to upgrade libltdl for any reason
+(e.g. a bugfix) you'll have to recompile your package instead of just
replacing an installed version of libltdl.
However, if your programs or libraries are linked with other libraries
that use such a pre-installed version of libltdl, you may get linker
Sometimes libltdl's many ways of gaining access to modules are not
sufficient for the purposes of a project. You can write your own
loader, and register it with libltdl so that @code{lt_dlopen} will be
-able to use it.
+able to use it.
Writing a loader involves writing at least three functions which can be
called by @code{lt_dlopen}, @code{lt_dlsym} and @code{lt_dlclose}.
The loader for @code{lt_dlopen}ing of preloaded static modules.
@end table
-The prefix "dl" is reserved for loaders supplied with future versions of
+The prefix "dl" is reserved for loaders supplied with future versions of
libltdl, so you should not use that for your own loader names.
@noindent
@deftypefn {Type} int lt_module_close (@w{lt_dlloader_data @var{loader_data},} @w{lt_module @var{module}})
The type of the unloader function for a user defined module loader.
-Implementatation of such a function should attempt to release
+Implementatation of such a function should attempt to release
any resources tied up by the @var{module} module, and then unload it
from memory. If the function fails for some reason, set the error
message with @code{lt_dlseterror} and return non-zero.
@end deftypefn
-@deftypefn {Type} lt_ptr lt_find_sym (@w{lt_user_data @var{loader_data},} @w{lt_module @var{module},} @w{const char *@var{symbol}})
+@deftypefn {Type} lt_ptr lt_find_sym (@w{lt_user_data @var{loader_data},} @w{lt_module @var{module},} @w{const char *@var{symbol}})
The type of the symbol lookup function for a user defined module loader.
Implementation of such a function should return the address of the named
@var{symbol} in the module @var{module}, or else set the error message
@deftypefun int lt_dlloader_remove (@w{const char *@var{loader_name}})
Remove the loader identified by the unique name, @var{loader_name}.
Before this can succeed, all modules opened by the named loader must
-have been closed. Returns 0 for success, otherwise an error message can
+have been closed. Returns 0 for success, otherwise an error message can
be obtained from @code{lt_dlerror}.
@example
@item assign.test
@pindex assign.test
-Checks whether we don't put break or continue on the same
+Checks whether we don't put break or continue on the same
line as an assignment in the libtool script.
@item link.test
worthwhile to send e-mail to @value{MAILLIST}, to make sure that you are
not duplicating existing work.
-If you find that any porting documentation is missing, please complain!
+If you find that any porting documentation is missing, please complain!
Complaints with patches and improvements to the documentation, or to
libtool itself, are more than welcome.
argument to @samp{$file_magic_cmd} in order to verify whether the
regular expression matches its output, and warn the user otherwise.
-@item test_compile
+@item test_compile
@vindex test_compile
just checks whether it is possible to link a program out of a list of
libraries, and checks which of those are listed in the output of
(@url{http://www.sun.com/service/online/free.html}) and documentation
server (@url{http://docs.sun.com/}).
-@item
-Compaq's Tru64 UNIX online documentation is at
+@item
+Compaq's Tru64 UNIX online documentation is at
(@url{http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html})
-with C++ documentation at
-(@url{http://tru64unix.compaq.com/cplus/docs/index.htm}).
+with C++ documentation at
+(@url{http://tru64unix.compaq.com/cplus/docs/index.htm}).
-@item
-Hewlett-Packard has online documentation at
-(@url{http://docs.hp.com/index.html}).
+@item
+Hewlett-Packard has online documentation at
+(@url{http://docs.hp.com/index.html}).
-@item
-IBM has online documentation at
-(@url{http://www.rs6000.ibm.com/resource/aix_resource/Pubs/}).
+@item
+IBM has online documentation at
+(@url{http://www.rs6000.ibm.com/resource/aix_resource/Pubs/}).
@end itemize
@node Compilers
Since version 1.4, the @code{libtool} script is generated by
@code{configure} (@pxref{Configuring}). In earlier versions,
@code{configure} achieved this by calling a helper script called
-@file{ltconfig}. From libtool version 0.7 to 1.0, this script
+@file{ltconfig}. From libtool version 0.7 to 1.0, this script
simply set shell variables, then sourced the libtool backend,
@code{ltmain.sh}. @code{ltconfig} from libtool version 1.1 through 1.3
inlined the contents of @code{ltmain.sh} into the generated
@end defvar
@defvar compiler_c_o
-Whether the compiler supports the @code{-c} and @code{-o} options
+Whether the compiler supports the @code{-c} and @code{-o} options
simultaneously. Set to @samp{yes} or @samp{no}.
@end defvar
@defvar compiler_o_lo
-Whether the compiler supports compiling directly to a ".lo" file,
+Whether the compiler supports compiling directly to a ".lo" file,
i.e whether object files do not have to have the suffix ".o".
Set to @samp{yes} or @samp{no}.
@end defvar
@defvar need_lib_prefix
Whether libtool should automatically prefix module names with 'lib'.
-Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which
+Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which
means the same as @samp{yes}, but documents that we are not really sure
about it.
@samp{yes} means that it is possible both to @code{dlopen} and to
@defvar need_version
Whether versioning is required for libraries, i.e. whether the
dynamic linker requires a version suffix for all libraries.
-Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which
+Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which
means the same as @samp{yes}, but documents that we are not really sure
about it.
@end defvar
@defvar need_locks
-Whether files must be locked to prevent conflicts when compiling
+Whether files must be locked to prevent conflicts when compiling
simultaneously. Set to @samp{yes} or @samp{no}.
@end defvar
@defvar version_type
The library version numbering type. One of @samp{libtool},
@samp{freebsd-aout}, @samp{freebsd-elf}, @samp{irix}, @samp{linux},
-@samp{osf}, @samp{sunos}, @samp{windows}, or @samp{none}.
+@samp{osf}, @samp{sunos}, @samp{windows}, or @samp{none}.
@end defvar
@defvar whole_archive_flag_spec
projects / thirdparty / libtool.git / commitdiff
