-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Whilst becoming reacquainted with the guts of libltdl in order to work on release blockers, I found myself rewriting this part of the HACKING file.
Okay to commit to HEAD? Index: ChangeLog from Gary V. Vaughan <[EMAIL PROTECTED]> * HACKING (Abstraction layers in libltdl): Rewritten somewhat for (hopefully) better clarity. Index: HACKING =================================================================== RCS file: /sources/libtool/libtool/HACKING,v retrieving revision 1.37 diff -u -u -r1.37 HACKING --- HACKING 25 Mar 2007 21:09:42 -0000 1.37 +++ HACKING 28 Mar 2007 11:53:23 -0000 @@ -287,84 +287,99 @@ * 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__private.h| + `-------------' + +* The top layer of the stack is the libltdl API proper, which includes + the relevant subsystems automatically. Clients of libltdl need only + invoke: - lt_system.h ../config.h + #include <ltdl.h> + + ,------. + |ltdl.h| + +------+ + |ltdl.c| + `------' -* 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: - - #if defined(LT_CONFIG_H) - # include LT_CONFIG_H - #else - # include <config.h> - #endif - #include "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!): + + ,------------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: + + #include <libltdl/lt__glibc.h> + + It consists of a single file: + + ,-----------. + |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: + + #if defined(LT_CONFIG_H) + # include LT_CONFIG_H + #else + # include <config.h> + #endif + #include "lt_system.h" Or if they are installed headers that must work outside the libtool source tree, simply: - #include <libltdl/lt_system.h> + #include <libltdl/lt_system.h> This layer's interface is defined by files that are usually named with a leading `lt__': - ,------------. ,-----------. ,------. ,-------. - |lt__dirent.h| |lt__alloc.h| |argz.h| |slist.h| - +------------+ +-----------+ +------+ +-------+ - |lt__dirent.c| |lt__alloc.c| |argz.c| |slist.c| - `------------' `-----------' `------' `-------' - - The exceptions here are argz.h and slist.h which are used - independently of libltdl in other projects. - -* 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: - - #include <libltdl/lt__glibc.h> - - It consists of the single file: - - lt__glibc.h - -* 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!): - - ,----------. ,-------------. - |lt_error.h| |lt_dlloader.h| - +----------+ +-------------+ - |lt_error.c| |lt_dlloader.c| - `----------' `-------------' + ,--------------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 | + `--------------^-------------^------------^--------^---------' + (argz.h and slist.h are used independently of libltdl in other projects) -* The top layer of the stack is the libltdl API proper, which includes - the subsystems automatically: - - ,------. - |ltdl.h| - +------+ - |ltdl.c| - `------' - -* 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: +* 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: - lt__private.h + ,-----------. + |../config.h| + `-----------' + + ,-----------. + |lt_system.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 - -- ())_. Email me: [EMAIL PROTECTED] ( '/ Read my blog: http://blog.azazil.net / )= ...and my book: http://sources.redhat.com/autobook `(_~)_ Join my AGLOCO Network: http://www.agloco.com/r/BBBS7912 _________________________________________________________ This patch notification generated by vcsapply version 1.0 http://savannah.gnu.org/projects/cvs-utils -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (Darwin) iD8DBQFGCleVFRMICSmD1gYRAg/fAKCiKosNbvHoUTIT/arfxQRYUk4n+QCgr8q0 3XBogEeDvvN+YUtYRcWsyeQ= =T65U -----END PGP SIGNATURE-----