GNU Info

Info Node: (libtool.info)Distributing libltdl

(libtool.info)Distributing libltdl


Prev: Module loaders for libltdl Up: Using libltdl
Enter node , (file) or (file)node

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 of users of your package that don't have libtool or libltdl
installed.  In this case, you must decide whether to manually add the
`ltdl' objects to your package, or else which flavor of libltdl you
want to use: a convenience library or an installable libtool library.

   The most simplistic way to add `libltdl' to your package is to copy
the source files, `ltdl.c' and `ltdl.h', to a source directory withing
your package and to build and link them along with the rest of your
sources.  To help you do this, the m4 macros for autoconf are available
in `ltdl.m4'.  You must ensure that they are available in `aclocal.m4'
before you run autoconf - by appending the contents of `ltdl.m4' to
`acinclude.m4', if you are using automake, or to `aclocal.m4' if you
are not.  Having made the macros available, you must add a call to the
`AC_LIB_LTDL' macro to your package's `configure.in' to perform the
configure time checks required to build `ltdl.o' correctly.  This
method has problems if you then try to link the package binaries with
an installed libltdl, or a library which depends on libltdl: you may
have problems with duplicate symbol definitions.

   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 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 `AC_LIBLTDL_CONVENIENCE' to your `configure.in', _before_
`AC_PROG_LIBTOOL'.

   In order to select the installable version of libltdl, you should
add a call of the macro `AC_LIBLTDL_INSTALLABLE' to your `configure.in'
_before_ `AC_PROG_LIBTOOL'.  This macro will check whether libltdl is
already installed and, if not, request the libltdl embedded in your
package to be built and installed.  Note, however, that no version
checking is performed.  The user may override the test and determine
that the libltdl embedded must be installed, regardless of the
existence of another version, using the configure switch
`--enable-ltdl-install'.

   In order to embed libltdl into your package, just add `--ltdl' to
the `libtoolize' command line. It will copy the libltdl sources to a
subdirectory `libltdl' in your package.  Both macros accept an optional
argument to specify the location of the `libltdl' directory. By the
default both macros assume that it is `${top_srcdir}/libltdl'.

   Whatever macro you use, it is up to you to ensure that your
`configure.in' will configure libltdl, using `AC_CONFIG_SUBDIRS', and
that your `Makefile's will start sub-makes within libltdl's directory,
using automake's SUBDIRS, for example.  Both macros define the shell
variables LIBLTDL, to the link flag that you should use to link with
libltdl, and LTDLINCL, to the preprocessor flag that you should use to
compile with programs that include `ltdl.h'.  It is up to you to use
`AC_SUBST' to ensure that this variable will be available in
`Makefile's, or add them to variables that are `AC_SUBST'ed by default,
such as LIBS and CPPFLAGS.

   If you're using the convenience libltdl, LIBLTDL will be the
pathname for the convenience version of libltdl and LTDLINCL will be
`-I' followed by the directory that contains libltdl, both starting
with `${top_builddir}/' or `${top_srcdir}/', respectively.

   If you request an installed version of libltdl and one is found(1),
LIBLTDL will be set to `-lltdl' and LTDLINCL will be empty (which is
just a blind assumption that `ltdl.h' is somewhere in the include path
if libltdl is in the library path).  If an installable version of
libltdl must be built, its pathname, starting with `${top_builddir}/',
will be stored in LIBLTDL, and LTDLINCL will be set just like in the
case of convenience library.

   So, when you want to link a program with libltdl, be it a
convenience, installed or installable library, just compile with
`$(LTDLINCL)' and link it with `$(LIBLTDL)', using libtool.

   You should probably also add `AC_LIBTOOL_DLOPEN' to your
`configure.in' _before_ `AC_PROG_LIBTOOL', otherwise libtool will
assume no dlopening mechanism is supported, and revert to dlpreopening,
which is probably not what you want.

   Avoid using the `-static' or `-all-static' switches when linking
programs with libltdl.  This will not work on all platforms, because
the dlopening functions may not be available for static linking.

   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 `libtoolize --ltdl'.

   configure.in:
     ...
     dnl Enable building of the convenience library
     dnl and set LIBLTDL accordingly
     AC_LIBLTDL_CONVENIENCE
     dnl Substitute LTDLINCL and LIBLTDL in the Makefiles
     AC_SUBST(LTDLINCL)
     AC_SUBST(LIBLTDL)
     dnl Check for dlopen support
     AC_LIBTOOL_DLOPEN
     dnl Configure libtool
     AC_PROG_LIBTOOL
     dnl Configure libltdl
     AC_CONFIG_SUBDIRS(libltdl)
     ...

   Makefile.am:
     ...
     SUBDIRS = libltdl
     
     INCLUDES = $(LTDLINCL)
     
     myprog_LDFLAGS = -export-dynamic
     # The quotes around -dlopen below fool automake <= 1.4 into accepting it
     myprog_LDADD = $(LIBLTDL) "-dlopen" self "-dlopen" foo1.la
     myprog_DEPENDENCIES = $(LIBLTDL) foo1.la
     ...

   ---------- Footnotes ----------

   (1) Even if libltdl is installed, `AC_LIBLTDL_INSTALLABLE' may fail
to detect it, if libltdl depends on symbols provided by libraries other
than the C library.  In this case, it will needlessly build and install
libltdl.


automatically generated by info2www version 1.2.2.9