[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
FYI: 327-gary-clarify-libltdl-api-docs
From: |
Gary V. Vaughan |
Subject: |
FYI: 327-gary-clarify-libltdl-api-docs |
Date: |
Wed, 28 Mar 2007 17:52:30 +0100 (BST) |
User-agent: |
mailnotify/0.7 |
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Applied to HEAD.
Index: ChangeLog
from Gary V. Vaughan <address@hidden>
* 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 16:52:04 -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: address@hidden
( '/ 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)
iD8DBQFGCp1NFRMICSmD1gYRAkJwAKCAue76AvhnYGZ7OQJuZTyxrzp+5ACeJYMt
YsV0z1dRcGnOL0Y+Gf+Exbo=
=AlB+
-----END PGP SIGNATURE-----
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- FYI: 327-gary-clarify-libltdl-api-docs,
Gary V. Vaughan <=