File: make.info,  Node: Loaded Object API,  Next: Loaded Object Example,  Prev: Remaking Loaded Objects,  Up: Loading Objects

12.2.3 Loaded Object Interface
------------------------------

     Warning: For this feature to be useful your extensions will need to
     invoke various functions internal to GNU 'make'.  The programming
     interfaces provided in this release should not be considered
     stable: functions may be added, removed, or change calling
     signatures or implementations in future versions of GNU 'make'.

   To be useful, loaded objects must be able to interact with GNU
'make'.  This interaction includes both interfaces the loaded object
provides to makefiles and also interfaces 'make' provides to the loaded
object to manipulate 'make''s operation.

   The interface between loaded objects and 'make' is defined by the
'gnumake.h' C header file.  All loaded objects written in C should
include this header file.  Any loaded object not written in C will need
to implement the interface defined in this header file.

   Typically, a loaded object will register one or more new GNU 'make'
functions using the 'gmk_add_function' routine from within its setup
function.  The implementations of these 'make' functions may make use of
the 'gmk_expand' and 'gmk_eval' routines to perform their tasks, then
optionally return a string as the result of the function expansion.

Loaded Object Licensing
.......................

Every dynamic extension should define the global symbol
'plugin_is_GPL_compatible' to assert that it has been licensed under a
GPL-compatible license.  If this symbol does not exist, 'make' emits a
fatal error and exits when it tries to load your extension.

   The declared type of the symbol should be 'int'.  It does not need to
be in any allocated section, though.  The code merely asserts that the
symbol exists in the global scope.  Something like this is enough:

     int plugin_is_GPL_compatible;

Data Structures
...............

'gmk_floc'
     This structure represents a filename/location pair.  It is provided
     when defining items, so GNU 'make' can inform the user later where
     the definition occurred if necessary.

Registering Functions
.....................

There is currently one way for makefiles to invoke operations provided
by the loaded object: through the 'make' function call interface.  A
loaded object can register one or more new functions which may then be
invoked from within the makefile in the same way as any other function.

   Use 'gmk_add_function' to create a new 'make' function.  Its
arguments are as follows:

'name'
     The function name.  This is what the makefile should use to invoke
     the function.  The name must be between 1 and 255 characters long
     and it may only contain alphanumeric, period ('.'), dash ('-'), and
     underscore ('_') characters.  It may not begin with a period.

'func_ptr'
     A pointer to a function that 'make' will invoke when it expands the
     function in a makefile.  This function must be defined by the
     loaded object.

'min_args'
     The minimum number of arguments the function will accept.  Must be
     between 0 and 255.  GNU 'make' will check this and fail before
     invoking 'func_ptr' if the function was invoked with too few
     arguments.

'max_args'
     The maximum number of arguments the function will accept.  Must be
     between 0 and 255.  GNU 'make' will check this and fail before
     invoking 'func_ptr' if the function was invoked with too many
     arguments.  If the value is 0, then any number of arguments is
     accepted.  If the value is greater than 0, then it must be greater
     than or equal to 'min_args'.

'flags'
     Flags that specify how this function will operate; the desired
     flags should be OR'd together.  If the 'GMK_FUNC_NOEXPAND' flag is
     given then the function arguments will not be expanded before the
     function is called; otherwise they will be expanded first.

Registered Function Interface
.............................

A function registered with 'make' must match the 'gmk_func_ptr' type.
It will be invoked with three parameters: 'name' (the name of the
function), 'argc' (the number of arguments to the function), and 'argv'
(an array of pointers to arguments to the function).  The last pointer
(that is, 'argv[argc]') will be null ('0').

   The return value of the function is the result of expanding the
function.  If the function expands to nothing the return value may be
null.  Otherwise, it must be a pointer to a string created with
'gmk_alloc'.  Once the function returns, 'make' owns this string and
will free it when appropriate; it cannot be accessed by the loaded
object.

GNU 'make' Facilities
.....................

There are some facilities exported by GNU 'make' for use by loaded
objects.  Typically these would be run from within the setup function
and/or the functions registered via 'gmk_add_function', to retrieve or
modify the data 'make' works with.

'gmk_expand'
     This function takes a string and expands it using 'make' expansion
     rules.  The result of the expansion is returned in a nil-terminated
     string buffer.  The caller is responsible for calling 'gmk_free'
     with a pointer to the returned buffer when done.

'gmk_eval'
     This function takes a buffer and evaluates it as a segment of
     makefile syntax.  This function can be used to define new
     variables, new rules, etc.  It is equivalent to using the 'eval'
     'make' function.

   Note that there is a difference between 'gmk_eval' and calling
'gmk_expand' with a string using the 'eval' function: in the latter case
the string will be expanded _twice_; once by 'gmk_expand' and then again
by the 'eval' function.  Using 'gmk_eval' the buffer is only expanded
once, at most (as it's read by the 'make' parser).

Memory Management
.................

Some systems allow for different memory management schemes.  Thus you
should never pass memory that you've allocated directly to any 'make'
function, nor should you attempt to directly free any memory returned to
you by any 'make' function.  Instead, use the 'gmk_alloc' and 'gmk_free'
functions.

   In particular, the string returned to 'make' by a function registered
using 'gmk_add_function' _must_ be allocated using 'gmk_alloc', and the
string returned from the 'make' 'gmk_expand' function _must_ be freed
(when no longer needed) using 'gmk_free'.

'gmk_alloc'
     Return a pointer to a newly-allocated buffer.  This function will
     always return a valid pointer; if not enough memory is available
     'make' will exit.  'gmk_alloc' does not initialize allocated
     memory.

'gmk_free'
     Free a buffer returned to you by 'make'.  Once the 'gmk_free'
     function returns the string will no longer be valid.  If NULL is
     passed to 'gmk_free', no operation is performed.