* The libltdl API uses a layered approach to differentiate internal and
external interfaces, among other things. To keep the abstraction
consistent, files in a given layer may only use APIs from files in the
- lower layers. The exception to this is lt__glibc.h which serves a
- dual purpose, as explained later.
+ lower layers. The ASCII art boxes below represent this stack, from
+ top to bottom...
-* At the bottom of the stack we have the system abstraction layer,
- which tries to smooth over the cracks where there are differences
- between host systems and compilers. config.h is generated at
- configure time and is not installed; lt_system.h is an installed
- file and cannot use macros from config.h:
+* But first, outside of the stack, there is a convenience header that
+ defines the internal interfaces (as evidenced by the `lt__' prefix to
+ the filename!) shared between implementation files in the stack, that
+ are however not exported to libltdl clients:
- lt_system.h ../config.h
+ ,-------------.
+ |lt__private.h|
+ `-------------'
-* Next up is the libc abstraction layer, which provides a uniform api
- to various system libc interfaces that differ between hosts supported
- by libtool. Typically, the files that implement this layer begin:
+* The top layer of the stack is the libltdl API proper, which includes
+ the relevant subsystems automatically. Clients of libltdl need only
+ invoke:
- #if defined(LT_CONFIG_H)
- # include LT_CONFIG_H
- #else
- # include <config.h>
- #endif
- #include "lt_system.h"
+ #include <ltdl.h>
- Or if they are installed headers that must work outside the libtool
- source tree, simply:
+ ,------.
+ |ltdl.h|
+ +------+
+ |ltdl.c|
+ `------'
- #include <libltdl/lt_system.h>
+* The next layer is comprised of the subsystems of the exported libltdl
+ API, which are implemented by files that are named with a leading `lt_'
+ (single underscore!):
- This layer's interface is defined by files that are usually named with
- a leading `lt__':
+ ,------------v---------------.
+ | lt_error.h | lt_dlloader.h |
+ +------------+---------------+
+ | lt_error.c | lt_dlloader.c |
+ `------------^---------------'
+
+* The next file is used both by the headers that implement it (in which
+ case its function is to avoid namespace clashes when linking with the
+ GNU C library proper) and is included by code that wants to program
+ against a glibc-like interface, in which case it serves to pull in all
+ the glibc-like functionality used by libltdl with a simple:
- ,------------. ,-----------. ,------. ,-------.
- |lt__dirent.h| |lt__alloc.h| |argz.h| |slist.h|
- +------------+ +-----------+ +------+ +-------+
- |lt__dirent.c| |lt__alloc.c| |argz.c| |slist.c|
- `------------' `-----------' `------' `-------'
+ #include <libltdl/lt__glibc.h>
- The exceptions here are argz.h and slist.h which are used
- independently of libltdl in other projects.
+ It consists of a single file:
-* There is also a sub-layer that can be used either by the headers that
- implement it, in which case its function is to avoid namespace clashes
- when linked with the GNU C library; Or it can be included by code that
- wants to program against a glibc like interface, where it also serves
- the function of pulling in all the glibc-like functionality used by
- libltdl from a single:
+ ,-----------.
+ |lt__glibc.h|
+ `-----------'
- #include <libltdl/lt__glibc.h>
+* Next to last is the libc abstraction layer, which provides a uniform
+ API to various system libc interfaces that differ between hosts
+ supported by libtool. Typically, the files that implement this layer
+ begin:
- It consists of the single file:
+ #if defined(LT_CONFIG_H)
+ # include LT_CONFIG_H
+ #else
+ # include <config.h>
+ #endif
+ #include "lt_system.h"
- lt__glibc.h
+ Or if they are installed headers that must work outside the libtool
+ source tree, simply:
-* The next layer are the subsystems of the exported libltdl API, which
- are defined by files that are named with a leading `lt_' (no double
- underscore!):
+ #include <libltdl/lt_system.h>
- ,----------. ,-------------.
- |lt_error.h| |lt_dlloader.h|
- +----------+ +-------------+
- |lt_error.c| |lt_dlloader.c|
- `----------' `-------------'
+ This layer's interface is defined by files that are usually named with
+ a leading `lt__':
+ ,--------------v-------------v------------v--------v---------.
+ | lt__dirent.h | lt__alloc.h | lt__strl.h | argz.h | slist.h |
+ +--------------+-------------+------------+--------+---------+
+ | lt__dirent.c | lt__alloc.c | lt__strl.c | argz.c | slist.c |
+ `--------------^-------------^------------^--------^---------'
-* The top layer of the stack is the libltdl API proper, which includes
- the subsystems automatically:
+ (argz.h and slist.h are used independently of libltdl in other projects)
- ,------.
- |ltdl.h|
- +------+
- |ltdl.c|
- `------'
+* At the bottom of the stack we have the system abstraction layer,
+ which tries to smooth over the cracks where there are differences
+ between host systems and compilers. config.h is generated at
+ configure time and is not installed; lt_system.h is an installed
+ file and cannot use macros from config.h:
+
+ ,-----------.
+ |../config.h|
+ `-----------'
-* And finally, there is an additional internal only layer (as evidenced
- by the `lt__' prefix to the filename!) that defines additional
- internal interfaces that are not exported to libltdl clients, but are
- shared between internal files:
+ ,-----------.
+ |lt_system.h|
+ `-----------'
- lt__private.h
+* Tacked on the side of this stack, attached via the lt_dlloader.h
+ definitions are the various implementation modules for run-time module
+ loading: preopen.c, dlopen.c etc.
10. Licensing Rules
projects / thirdparty / libtool.git / commitdiff
