www.delorie.com/gnu/docs/libtool/libtool_52.html   search  
 
Buy GNU books!


Libtool

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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(10), 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
...


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003