11.2 Creating modules that can be dlopened ¶

Libtool modules are created like normal libtool libraries with a few exceptions:

You have to link the module with libtool’s -module switch, and you should link any program that is intended to dlopen the module with -dlopen modulename.la where possible, so that libtool can dlpreopen the module on platforms that do not 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 versioning (see Library interface versions) for a specific module you should link it with the -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_" (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 that do not use a prefix so that you can also dlopen non-libtool modules.

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.

/* 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 _foo1_helper();
}

The Makefile.am contains the necessary rules to build the module foo1.la:

...
lib_LTLIBRARIES = foo1.la

foo1_la_SOURCES = foo1.c
foo1_la_LDFLAGS = -module
...