modules/README - m4 - Git at Google


            
            This directory contains all bundled modules for GNU m4.


            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 module name listed on the command line,

            
            or by calling the builtin "include". This gives GNU m4 potential access

            
            to any system feature with a C interface.


            Modules are searched for in M4PATH, if set, else in a module directory

            
            defined at configure time, $prefix/lib/m4/ by default.  Extra directories

            
            can also be added to the search patch by specifying them on the command

            
            line with the `-I' or `-B' 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 "include".  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:


                tests/m4 doc/examples/time.m4


            or in the case of time2.m4


                tests/m4 -I tests time -I doc/examples time2.m4


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


            Copyright (C) 2000-2001, 2006, 2010, 2013-2014 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.3 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.

	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 module name listed on the command line,
	or by calling the builtin "include". This gives GNU m4 potential access
	to any system feature with a C interface.

	Modules are searched for in M4PATH, if set, else in a module directory
	defined at configure time, $prefix/lib/m4/ by default. Extra directories
	can also be added to the search patch by specifying them on the command
	line with the `-I' or `-B' 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 "include". 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:

	tests/m4 doc/examples/time.m4

	or in the case of time2.m4

	tests/m4 -I tests time -I doc/examples time2.m4

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

	Copyright (C) 2000-2001, 2006, 2010, 2013-2014 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.3 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.