DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

(libtool14.info.gz) Distributing libltdl

Info Catalog (libtool14.info.gz) Module loaders for libltdl (libtool14.info.gz) Using libltdl
 
 10.6 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.
 
Info Catalog (libtool14.info.gz) Module loaders for libltdl (libtool14.info.gz) Using libltdl
automatically generated byinfo2html