modules/README - m4 - Git at Google

 This directory contains all bundled modules for GNU m4.

 Note that as of this writing, an unreleased version of libtool from the
 CVS trunk is required to be able to compile the example modules, since they
 in turn depend on the uninstalled libm4.la library.  I think that third
 party modules will not have this requirement since they will be linking
 against the installed library.  In any case, once libtool-2.0 is
 released this will become a non-issue.  The bottom line is that you
 shouldn't libtoolize this distribution unless you know what you are doing!

 Dynamic modules are only available if the host operating system provides
 one (or more!) of libltdl's required APIs.

 Implementation details are in ../m4/module.c

 A module is a compiled shared object, i.e., modules are written in C and
 then compiled.  The compiled file can then be loaded into a running m4
 process by calling m4 with the `-m' or `--load-module' options on the
 command line, or by calling the builtin "load" (itself implemented by the
 module `load').  This will give GNU m4 potential access to any system
 feature with a C interface.

 Modules are searched for in M4MODPATH, if set, else in a module directory
 defined at configure time, default $prefix/libexec/m4.  Extra directories
 can also be added to the search patch by specifying them on the command
 line with the `-M' or `--module-directory' options.

 A module extends GNU m4 by defining new builtins, It can define builtins
 with the same names as existing builtins, which will shadow the existing
 builtins, making them temporarily unavailable.  A module cannot redefine
 internal functions of GNU m4, such as the input parser or argument handling
 (yet!).

 Each module should include the installed header file,
 `$prefix/include/m4module.h'.  This will define all the necessary macros,
 type declarations and function prototypes required to implement a module.

 The module system uses libtool's libltdl for dynamic module loading, and
 that in turn requires that any non-static symbols in the module to be
 be in their own namespace to avoid namespace clashes with symbols
 exported from other modules (which may be loaded too!).  This is usually
 done by `#define'ing these symbols to libltdl's naming scheme at the top
 of the file.  The scheme is to prefix each symbol with the module name,
 followed by `_LTX_' and then the original symbol name.  For example,
 to export "m4_macro_table" in a source file which will become part of
 a module, "mymod", we would add the following to the top of the source file:
 `#define m4_macro_table mymod_LTX_m4_macro_table'.  See the included modules
 for more examples.

 Each module *must* define one or more entry points from the following:
 "m4_builtin_table", "m4_macro_table" and "m4_init_module".  The symbol
 "m4_builtin_table" is a pointer to a table of "m4_builtin" (defined in
 m4module.h), listing each new builtin that it implements.  The symbol
 "m4_macro_table", is a pointer to a table of "m4_macro", listing each
 text macro initialised by the module.  These tables end with an
 entry where name == NULL.

 If a module defines the symbol "m4_init_module", it is supposed to be a
 function with a prototype of "void m4_init_module (struct obstack *obs)",
 and it will be called as soon as the module is loaded.  Any non-finished
 object left on the obstack will be the expansion of the call of the
 builtin "load".  The obstack pointer might be NULL (in the future).

 If a module defines the symbol "m4_finish_module", it is supposed to be
 a function with a prototype of "void m4_finish_module (void)", and it
 will be called just before the module is unloaded or GNU m4 exits.  This
 will allow a module to clean up before exit.  There is no way of
 communicating information to the user, as GNU m4 exits immediately
 afterwards.

 No other symbols will be used by GNU m4.  All other symbols within the
 module are private and should be declared `static' so that they will not
 be accessible to GNU m4 or to other modules.

 Modules are allowed to call external functions already defined within
 the GNU m4module library.  These have prototypes in m4module.h.

 Loading and unloading of modules, and symbol namespace resolution
 strategies are illustrated by shadow.c and shadow.m4.

 To try the demos, compile with `make' and run them with the commands as:

    M4MODPATH=`pwd` ../src/m4 time.m4

 or

   ../src/m4 -M `pwd` shadow.m4

 or in the case of time2.m4

   ../src/m4 -M `pwd` -m time time2.m4

 ========================================================================

 Copyright (C) 2000, 2001, 2006 Free Software Foundation, Inc.

 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no
 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 Texts.  A copy of the license is included in the ``GNU Free
 Documentation License'' file as part of this distribution.
	This directory contains all bundled modules for GNU m4.

	Note that as of this writing, an unreleased version of libtool from the
	CVS trunk is required to be able to compile the example modules, since they
	in turn depend on the uninstalled libm4.la library. I think that third
	party modules will not have this requirement since they will be linking
	against the installed library. In any case, once libtool-2.0 is
	released this will become a non-issue. The bottom line is that you
	shouldn't libtoolize this distribution unless you know what you are doing!

	Dynamic modules are only available if the host operating system provides
	one (or more!) of libltdl's required APIs.

	Implementation details are in ../m4/module.c

	A module is a compiled shared object, i.e., modules are written in C and
	then compiled. The compiled file can then be loaded into a running m4
	process by calling m4 with the `-m' or `--load-module' options on the
	command line, or by calling the builtin "load" (itself implemented by the
	module `load'). This will give GNU m4 potential access to any system
	feature with a C interface.

	Modules are searched for in M4MODPATH, if set, else in a module directory
	defined at configure time, default $prefix/libexec/m4. Extra directories
	can also be added to the search patch by specifying them on the command
	line with the `-M' or `--module-directory' options.

	A module extends GNU m4 by defining new builtins, It can define builtins
	with the same names as existing builtins, which will shadow the existing
	builtins, making them temporarily unavailable. A module cannot redefine
	internal functions of GNU m4, such as the input parser or argument handling
	(yet!).

	Each module should include the installed header file,
	`$prefix/include/m4module.h'. This will define all the necessary macros,
	type declarations and function prototypes required to implement a module.

	The module system uses libtool's libltdl for dynamic module loading, and
	that in turn requires that any non-static symbols in the module to be
	be in their own namespace to avoid namespace clashes with symbols
	exported from other modules (which may be loaded too!). This is usually
	done by `#define'ing these symbols to libltdl's naming scheme at the top
	of the file. The scheme is to prefix each symbol with the module name,
	followed by `_LTX_' and then the original symbol name. For example,
	to export "m4_macro_table" in a source file which will become part of
	a module, "mymod", we would add the following to the top of the source file:
	`#define m4_macro_table mymod_LTX_m4_macro_table'. See the included modules
	for more examples.

	Each module must define one or more entry points from the following:
	"m4_builtin_table", "m4_macro_table" and "m4_init_module". The symbol
	"m4_builtin_table" is a pointer to a table of "m4_builtin" (defined in
	m4module.h), listing each new builtin that it implements. The symbol
	"m4_macro_table", is a pointer to a table of "m4_macro", listing each
	text macro initialised by the module. These tables end with an
	entry where name == NULL.

	If a module defines the symbol "m4_init_module", it is supposed to be a
	function with a prototype of "void m4_init_module (struct obstack *obs)",
	and it will be called as soon as the module is loaded. Any non-finished
	object left on the obstack will be the expansion of the call of the
	builtin "load". The obstack pointer might be NULL (in the future).

	If a module defines the symbol "m4_finish_module", it is supposed to be
	a function with a prototype of "void m4_finish_module (void)", and it
	will be called just before the module is unloaded or GNU m4 exits. This
	will allow a module to clean up before exit. There is no way of
	communicating information to the user, as GNU m4 exits immediately
	afterwards.

	No other symbols will be used by GNU m4. All other symbols within the
	module are private and should be declared `static' so that they will not
	be accessible to GNU m4 or to other modules.

	Modules are allowed to call external functions already defined within
	the GNU m4module library. These have prototypes in m4module.h.

	Loading and unloading of modules, and symbol namespace resolution
	strategies are illustrated by shadow.c and shadow.m4.

	To try the demos, compile with `make' and run them with the commands as:

	M4MODPATH=`pwd` ../src/m4 time.m4

	or

	../src/m4 -M `pwd` shadow.m4

	or in the case of time2.m4

	../src/m4 -M `pwd` -m time time2.m4

	========================================================================

	Copyright (C) 2000, 2001, 2006 Free Software Foundation, Inc.

	Permission is granted to copy, distribute and/or modify this document
	under the terms of the GNU Free Documentation License, Version 1.2 or
	any later version published by the Free Software Foundation; with no
	Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
	Texts. A copy of the license is included in the ``GNU Free
	Documentation License'' file as part of this distribution.