13.24 guile-tools make-module-catalog

See Finding Guile Modules, for discussion.

Usage: make-module-catalog [OPTIONS] [DIR ...]

Create a module catalog (named ".module-catalog") in each directory DIR.
A module catalog is an alist with module names (list of symbols) for the
key and CATALOG-INFO, described below, for the value.  OPTIONS are zero
or more of the following (defaults in square braces):

 -f, --force        -- ignore current catalog entries
 -v, --verbose      -- describe each file scanned
 -x, --exclude NAME -- do not scan NAME, which may be either a filename
                       or a directory name (also excludes children);
                       this option may be given multiple times
 -X, --xregexp RX   -- do not scan files or directories that match
                       regular expression RX (may include path sep char);
                       this option may be given multiple times
 -d, --dot-ext EXTS -- like -X "[.]foo$" for every foo in comma-sep EXTS;
                       this option may be given multiple times
 -o, --output STEM  -- write to DIR/STEM [".module-catalog"]
 -b, --bufsize NUM  -- use NUM bytes for the scan buffer [256]
 -t, --trim PREFIX  -- delete PREFIX from each filename

Note that STEM may not include a directory component.  Also, the minimum
buffer size is 128; a specified NUM less than that is silently adjusted.

Each catalog entry has the form:

  (MODULE-NAME [LOAD-TYPE EXTRA-INFO...] . FILENAME)

MODULE-NAME is a list of symbols, such as: (scripts slurp).  If LOAD-TYPE
and EXTRA-INFO... are omitted, the module is taken to be loadable as plain
text (human-readable) Scheme code with a `define-module' form starting in
column 0.  Otherwise, LOAD-TYPE is a symbol and EXTRA-INFO... is other
information useful in loading a module.  Here is a list of possible values
for LOAD-TYPE:

  scm_init_module -- module is a shared object library following the
                     "scm_init_MODULE_NAME_module" convention outlined
                     in the Guile manual; EXTRA-INFO is a string naming
                     the C init function followed by a (possibly empty)
                     list of upstream module names

FILENAME is a string, the absolute path to the file that provides the
interface to the module.  (This file may also provide the definitions, or
implementation, of the module, although that is not required.)

There are two special catalog entries whose keys are not module names:

  **exclude**  -- list of subdirectories excluded from this catalog,
                  as specified by the `--exclude' command-line option

  **catfmtv**  -- vector, the first element of which is the version of
                  the catalog format (at this time: 1); and remaining
                  elements catfmtv-specific info (for version 1: none)

The asterisks (*) are part of the symbol name.

Collisions within a single catalog are flagged and resolved if possible in
favor of the most recent existing FILENAME.  If not possible, signal error.

Normally, FILENAME is written out in full.  This can be problematic for
installations that use a $(DESTDIR)$(foodir) style prefix, because the
desired effective directory is solely $(foodir), without $(DESTDIR).  You
can use `--trim $(DESTDIR)' in this case, to omit the $(DESTDIR) prefix.


Acknowledgements: The idea and style of the module catalog are directly
                  inspired by SLIB's slibcat.  Thanks, Aubrey Jaffer!


TODO: Factor bounded-space grep into its own module.
      Make scanner extensible.
      Make collision resolution extensible.