modules/README

   1 This directory contains all bundled modules for GNU m4.
   2
   3 Dynamic modules are only available if the host operating system provides
   4 one (or more!) of libltdl's required APIs.
   5
   6 Implementation details are in ../m4/module.c
   7
   8 A module is a compiled shared object, i.e., modules are written in C and
   9 then compiled.  The compiled file can then be loaded into a running m4
  10 process by calling m4 with the module name listed on the command line,
  11 or by calling the builtin "include". This gives GNU m4 potential access
  12 to any system feature with a C interface.
  13
  14 Modules are searched for in M4PATH, if set, else in a module directory
  15 defined at configure time, $prefix/lib/m4/ by default.  Extra directories
  16 can also be added to the search patch by specifying them on the command
  17 line with the `-I' or `-B' options.
  18
  19 A module extends GNU m4 by defining new builtins, It can define builtins
  20 with the same names as existing builtins, which will shadow the existing
  21 builtins, making them temporarily unavailable.  A module cannot redefine
  22 internal functions of GNU m4, such as the input parser or argument handling
  23 (yet!).
  24
  25 Each module should include the installed header file,
  26 `$prefix/include/m4module.h'.  This will define all the necessary macros,
  27 type declarations and function prototypes required to implement a module.
  28
  29 The module system uses libtool's libltdl for dynamic module loading, and
  30 that in turn requires that any non-static symbols in the module to be
  31 be in their own namespace to avoid namespace clashes with symbols
  32 exported from other modules (which may be loaded too!).  This is usually
  33 done by `#define'ing these symbols to libltdl's naming scheme at the top
  34 of the file.  The scheme is to prefix each symbol with the module name,
  35 followed by `_LTX_' and then the original symbol name.  For example,
  36 to export "m4_macro_table" in a source file which will become part of
  37 a module, "mymod", we would add the following to the top of the source file:
  38 `#define m4_macro_table mymod_LTX_m4_macro_table'.  See the included modules
  39 for more examples.
  40
  41 Each module *must* define one or more entry points from the following:
  42 "m4_builtin_table", "m4_macro_table" and "m4_init_module".  The symbol
  43 "m4_builtin_table" is a pointer to a table of "m4_builtin" (defined in
  44 m4module.h), listing each new builtin that it implements.  The symbol
  45 "m4_macro_table", is a pointer to a table of "m4_macro", listing each
  46 text macro initialised by the module.  These tables end with an
  47 entry where name == NULL.
  48
  49 If a module defines the symbol "m4_init_module", it is supposed to be a
  50 function with a prototype of "void m4_init_module (struct obstack *obs)",
  51 and it will be called as soon as the module is loaded.  Any non-finished
  52 object left on the obstack will be the expansion of the call of the
  53 builtin "include".  The obstack pointer might be NULL (in the future).
  54
  55 If a module defines the symbol "m4_finish_module", it is supposed to be
  56 a function with a prototype of "void m4_finish_module (void)", and it
  57 will be called just before the module is unloaded or GNU m4 exits.  This
  58 will allow a module to clean up before exit.  There is no way of
  59 communicating information to the user, as GNU m4 exits immediately
  60 afterwards.
  61
  62 No other symbols will be used by GNU m4.  All other symbols within the
  63 module are private and should be declared `static' so that they will not
  64 be accessible to GNU m4 or to other modules.
  65
  66 Modules are allowed to call external functions already defined within
  67 the GNU m4module library.  These have prototypes in m4module.h.
  68
  69 Loading and unloading of modules, and symbol namespace resolution
  70 strategies are illustrated by shadow.c and shadow.m4.
  71
  72 To try the demos, compile with `make' and run them with the commands as:
  73
  74     tests/m4 doc/examples/time.m4
  75
  76 or in the case of time2.m4
  77
  78     tests/m4 -I tests time -I doc/examples time2.m4
  79
  80 ========================================================================
  81
  82 Copyright (C) 2000-2001, 2006, 2010, 2013-2014 Free Software Foundation,
  83 Inc.
  84
  85 Permission is granted to copy, distribute and/or modify this document
  86 under the terms of the GNU Free Documentation License, Version 1.3 or
  87 any later version published by the Free Software Foundation; with no
  88 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  89 Texts.  A copy of the license is included in the ``GNU Free
  90 Documentation License'' file as part of this distribution.