From: Gary V. Vaughan Date: Wed, 28 Mar 2007 16:52:26 +0000 (+0000) Subject: * HACKING (Abstraction layers in libltdl): Rewritten somewhat X-Git-Tag: release-2-1b~145 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d5cbbc4c5e1749a6e831b6ba9527da480b21e407;p=thirdparty%2Flibtool.git * HACKING (Abstraction layers in libltdl): Rewritten somewhat for (hopefully) better clarity. --- diff --git a/ChangeLog b/ChangeLog index 3cb24e084..bd0ae9692 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2007-03-28 Gary V. Vaughan + + * HACKING (Abstraction layers in libltdl): Rewritten somewhat + for (hopefully) better clarity. + 2007-03-26 Gary V. Vaughan The stamp-vcl file rules caused non-gnu make programs to rerun diff --git a/HACKING b/HACKING index c775d95d0..d57d94085 100644 --- a/HACKING +++ b/HACKING @@ -287,84 +287,99 @@ yyyy-mm-dd Name of Author (tiny change) * 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 - #endif - #include "lt_system.h" + #include - Or if they are installed headers that must work outside the libtool - source tree, simply: + ,------. + |ltdl.h| + +------+ + |ltdl.c| + `------' - #include +* 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 - 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 +* 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 + #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 - ,----------. ,-------------. - |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