libtool-patches
[Top][All Lists]
Advanced

[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-----




reply via email to

[Prev in Thread] Current Thread [Next in Thread]