From: Thomas Tanner Date: Sun, 14 Mar 1999 11:18:37 +0000 (+0000) Subject: * TODO: libltdl is now documented X-Git-Tag: release-1-2f~4 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7378519a1beb8276ad1fa09fcdc78571b778d345;p=thirdparty%2Flibtool.git * TODO: libltdl is now documented * doc/libltdl.texi (linking with installed libtool libraries): fixed typo * doc/libltdl.texi (libltdl): added documentation for building libtool modules and examples how to embed libltdl * ltmain.in: don't ignore user-specified run-paths (fixed it at the right place) --- diff --git a/ChangeLog b/ChangeLog index 7b5382045..1e59bb08a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +1999-03-14 Thomas Tanner + + * TODO: libltdl is now documented + * doc/libltdl.texi (linking with installed libtool libraries): + fixed typo + * doc/libltdl.texi (libltdl): added documentation for building + libtool modules and examples how to embed libltdl + * ltmain.in: don't ignore user-specified run-paths (fixed it + at the right place) + 1999-03-14 Alexandre Oliva * ltmain.in (deplibs_check_method=none): discard -L and -R diff --git a/TODO b/TODO index ed819b6e6..e51996e81 100644 --- a/TODO +++ b/TODO @@ -20,8 +20,6 @@ so that the size of lt_preloaded_symbols can be reduced. * Documentation: -- libltdl documentation needs to be completed. - - AC_PROG_LIBTOOL, AC_ENABLE/DISABLE_SHARED/STATIC/FAST_INSTALL, AC_LIBTOOL_DLOPEN, AC_LIBLTDL_CONVENIENCE/INSTALLABLE are not documented diff --git a/doc/libtool.texi b/doc/libtool.texi index 7640a9a97..c44ede2d6 100644 --- a/doc/libtool.texi +++ b/doc/libtool.texi @@ -710,7 +710,7 @@ Thing (TM) for you: @example burger$ @kbd{libtool gcc -g -O -o test test.o /usr/local/lib/libhello.la} gcc -g -O -o @value{objdir}/test test.o -Wl,--rpath --Wl,/usr/local/lib /usr/local/lib/libhello.la -lm +-Wl,/usr/local/lib /usr/local/lib/libhello.a -lm creating test burger$ @end example @@ -2768,11 +2768,68 @@ any libltdl function other than @code{lt_dlpreopen_default} or the macro @node Modules for libltdl @section Creating modules that can be @code{dlopen}ed -You just have to link the module with libtool's @samp{-module} switch, -and link any program that is intended to dlopen the module with -@samp{-dlopen modname.la}. If the module depends on any other -libraries, make sure you specify them either when you link the module or -when you link programs that dlopen it. +Libtool modules are like normal libtool libraries with a few exceptions: + +You have to link the module with libtool's @samp{-module} switch, +and you should link any program that is intended to dlopen the module with +@samp{-dlopen modulename.la} so that libtool can dlpreopen the module +on platforms which don't support dlopening. If the module depends on any +other libraries, make sure you specify them either when you link the module +or when you link programs that dlopen it. +If you want to disable @pxref{Versioning} for a specific module +you should link it with the @samp{-avoid-version} switch. +Note that libtool modules don't need to have a "lib" prefix. +However, automake 1.4 or higher is required to build such modules. + +Usually a set of modules provide the same interface, i.e, exports the same +symbols, so that a program can dlopen them without having to know more +about their internals. +In order to avoid symbol conflicts all exported symbols must be prefixed +with "modulename_LTX_" (@samp{modulename} is the name of the module). +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 +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. + +@example +/* aliases for the exported symbols */ +#define foo foo1_LTX_foo +#define bar foo1_LTX_bar + +/* a global variable definition */ +int bar = 1; + +/* a private function */ +int _foo1_helper() @{ + return bar; +@} + +/* an exported function */ +int foo() @{ + return _foo_helper(); +@} +@end example + +@noindent +The @file{Makefile.am} contains the necessary rules to build the +module @file{foo1.la}: + +@example +... +lib_LTLIBRARIES = foo1.la + +foo1_la_SOURCES = foo1.c +foo1_la_LDFLAGS = -module +... +@end example @node Distributing libltdl @section How to distribute libltdl with your package @@ -2786,12 +2843,17 @@ convenience library or an installable libtool library. 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 +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 errors or run-time crashes. Another problem is that you cannot link the convenience library into more than one libtool library, then link a single program with these libraries, because you may get duplicate -symbols. In order to enable this flavor of libltdl, you should add the +symbols. In general you can safely use the convenience library in programs +which don't depend on other libraries that might use libltdl too. +In order to enable this flavor of libltdl, you should add the line @samp{AC_LIBLTDL_CONVENIENCE} to your @file{configure.in}, @emph{after} @samp{AM_PROG_LIBTOOL}. @@ -2805,6 +2867,13 @@ the test and determine that the libltdl embedded must be installed, regardless of the existence of another version, using the configure switch @samp{--enable-ltdl-install}. +In order to embed libltdl into your package, just add @samp{--ltdl} to +the @code{libtoolize} command line. It will copy the libltdl sources +to a subdirectory @samp{libltdl} in your package. +Both macros accept an optional argument to specify the location +of the @samp{libltdl} directory. By the default both macros assume that it +is @samp{$@{top_builddir@}/libltdl}. + Whatever macro you use, it is up to you to ensure that your @file{configure.in} will configure libltdl, using @samp{AC_CONFIG_SUBDIRS}, and that your @file{Makefile}s will start @@ -2831,8 +2900,38 @@ Avoid using the @code{-all-static} switch when linking programs with libltdl; this will not work on all plaforms, because the dlopening functions may not be available for static linking. -In order to embed libltdl into your package, just add @samp{--ltdl} to -the @code{libtoolize} command line. +The following example shows you how to embed the convenience libltdl +in your package. In order to use the installable variant just replace +AC_LIBLTDL_CONVENIENCE with AC_LIBLTDL_INSTALLABLE. We assume that +libltdl was embedded using @samp{libtoolize --ltdl}. + +configure.in: +@example +... +dnl Check for dlopen support +AC_LIBTOOL_DLOPEN +dnl Configure libtool +AM_PROG_LIBTOOL +dnl Enable building of the convenience library and set LIBLTDL accordingly +AC_LIBLTDL_CONVENIENCE +dnl Substitute LIBLTDL in the Makefiles +AC_SUBST(LIBLTDL) +dnl Configure libltdl +AC_CONFIG_SUBDIRS(libltdl) +... +@end example + +Makefile.am: +@example +... +SUBDIRS = libltdl + +myprog_LDFLAGS = -export-dynamic +# The quotes around -dlopen below fool automake into accepting it +myprog_LDADD = $(LIBLTDL) "-dlopen" self "-dlopen" libfoo.la +myprog_DEPENDENCIES = $(LIBLTDL) libfoo.la +... +@end example @node Other languages @chapter Using libtool with other languages diff --git a/ltmain.in b/ltmain.in index e7adb9bb2..c250d54fe 100644 --- a/ltmain.in +++ b/ltmain.in @@ -800,6 +800,7 @@ compiler." fi # now prepend the system-specific ones eval lib_search_path=\"$sys_lib_search_path_spec\$lib_search_path\" + eval sys_lib_dlsearch_path=\"$sys_lib_dlsearch_path_spec\" avoid_version=no dlfiles= @@ -1240,14 +1241,27 @@ compiler." esac # This is the magic to use -rpath. - case "$compile_rpath " in - *" $absdir "*) ;; - *) compile_rpath="$compile_rpath $absdir" ;; - esac - case "$finalize_rpath " in - *" $libdir "*) ;; - *) finalize_rpath="$finalize_rpath $libdir" ;; - esac + # Skip directories that are in the system default run-time + # search path, unless they have been requested with -R. + case " $sys_lib_dlsearch_path " in + *" $absdir "*) ;; + *) + case "$compile_rpath " in + *" $absdir "*) ;; + *) compile_rpath="$compile_rpath $absdir" + esac + ;; + esac + + case " $sys_lib_dlsearch_path " in + *" $libdir "*) ;; + *) + case "$finalize_rpath " in + *" $libdir "*) ;; + *) finalize_rpath="$finalize_rpath $libdir" + esac + ;; + esac lib_linked=yes case "$hardcode_action" in @@ -2174,21 +2188,9 @@ EOF fi # Now hardcode the library paths - eval sys_lib_dlsearch_path=\"$sys_lib_dlsearch_path_spec\" rpath= hardcode_libdirs= for libdir in $compile_rpath $finalize_rpath; do - # Skip directories that are in the system default run-time - # search path, unless they have been requested with -R. - case " $sys_lib_dlsearch_path " in - *" $libdir "*) - case " $xrpath " in - *" $libdir "*) ;; - *) continue ;; - esac ;; - *) ;; - esac - if test -n "$hardcode_libdir_flag_spec"; then if test -n "$hardcode_libdir_separator"; then if test -z "$hardcode_libdirs"; then @@ -2226,17 +2228,6 @@ EOF rpath= hardcode_libdirs= for libdir in $finalize_rpath; do - # Skip directories that are in the system default run-time - # search path, unless they have been requested with -R. - case " $sys_lib_dlsearch_path " in - *" $libdir "*) - case " $xrpath " in - *" $libdir "*) ;; - *) continue ;; - esac ;; - *) ;; - esac - if test -n "$hardcode_libdir_flag_spec"; then if test -n "$hardcode_libdir_separator"; then if test -z "$hardcode_libdirs"; then