make: Loaded Object API
1
1 12.2.3 Loaded Object Interface
1 ------------------------------
1
1 Warning: For this feature to be useful your extensions will need to
1 invoke various functions internal to GNU 'make'. The programming
1 interfaces provided in this release should not be considered
1 stable: functions may be added, removed, or change calling
1 signatures or implementations in future versions of GNU 'make'.
1
1 To be useful, loaded objects must be able to interact with GNU
1 'make'. This interaction includes both interfaces the loaded object
1 provides to makefiles and also interfaces 'make' provides to the loaded
1 object to manipulate 'make''s operation.
1
1 The interface between loaded objects and 'make' is defined by the
1 'gnumake.h' C header file. All loaded objects written in C should
1 include this header file. Any loaded object not written in C will need
1 to implement the interface defined in this header file.
1
1 Typically, a loaded object will register one or more new GNU 'make'
1 functions using the 'gmk_add_function' routine from within its setup
1 function. The implementations of these 'make' functions may make use of
1 the 'gmk_expand' and 'gmk_eval' routines to perform their tasks, then
1 optionally return a string as the result of the function expansion.
1
1 Loaded Object Licensing
1 .......................
1
1 Every dynamic extension should define the global symbol
1 'plugin_is_GPL_compatible' to assert that it has been licensed under a
1 GPL-compatible license. If this symbol does not exist, 'make' emits a
1 fatal error and exits when it tries to load your extension.
1
1 The declared type of the symbol should be 'int'. It does not need to
1 be in any allocated section, though. The code merely asserts that the
1 symbol exists in the global scope. Something like this is enough:
1
1 int plugin_is_GPL_compatible;
1
1 Data Structures
1 ...............
1
1 'gmk_floc'
1 This structure represents a filename/location pair. It is provided
1 when defining items, so GNU 'make' can inform the user later where
1 the definition occurred if necessary.
1
1 Registering Functions
1 .....................
1
1 There is currently one way for makefiles to invoke operations provided
1 by the loaded object: through the 'make' function call interface. A
1 loaded object can register one or more new functions which may then be
1 invoked from within the makefile in the same way as any other function.
1
1 Use 'gmk_add_function' to create a new 'make' function. Its
1 arguments are as follows:
1
1 'name'
1 The function name. This is what the makefile should use to invoke
1 the function. The name must be between 1 and 255 characters long
1 and it may only contain alphanumeric, period ('.'), dash ('-'), and
1 underscore ('_') characters. It may not begin with a period.
1
1 'func_ptr'
1 A pointer to a function that 'make' will invoke when it expands the
1 function in a makefile. This function must be defined by the
1 loaded object.
1
1 'min_args'
1 The minimum number of arguments the function will accept. Must be
1 between 0 and 255. GNU 'make' will check this and fail before
1 invoking 'func_ptr' if the function was invoked with too few
1 arguments.
1
1 'max_args'
1 The maximum number of arguments the function will accept. Must be
1 between 0 and 255. GNU 'make' will check this and fail before
1 invoking 'func_ptr' if the function was invoked with too few
1 arguments. If the value is 0, then any number of arguments is
1 accepted. If the value is greater than 0, then it must be greater
1 than or equal to 'min_args'.
1
1 'flags'
1 Flags that specify how this function will operate; the desired
1 flags should be OR'd together. If the 'GMK_FUNC_NOEXPAND' flag is
1 given then the function arguments will not be expanded before the
1 function is called; otherwise they will be expanded first.
1
1 Registered Function Interface
1 .............................
1
1 A function registered with 'make' must match the 'gmk_func_ptr' type.
1 It will be invoked with three parameters: 'name' (the name of the
1 function), 'argc' (the number of arguments to the function), and 'argv'
1 (an array of pointers to arguments to the function). The last pointer
1 (that is, 'argv[argc]') will be null ('0').
1
1 The return value of the function is the result of expanding the
1 function. If the function expands to nothing the return value may be
1 null. Otherwise, it must be a pointer to a string created with
1 'gmk_alloc'. Once the function returns, 'make' owns this string and
1 will free it when appropriate; it cannot be accessed by the loaded
1 object.
1
1 GNU 'make' Facilities
1 .....................
1
1 There are some facilities exported by GNU 'make' for use by loaded
1 objects. Typically these would be run from within the setup function
1 and/or the functions registered via 'gmk_add_function', to retrieve or
1 modify the data 'make' works with.
1
1 'gmk_expand'
1 This function takes a string and expands it using 'make' expansion
1 rules. The result of the expansion is returned in a nil-terminated
1 string buffer. The caller is responsible for calling 'gmk_free'
1 with a pointer to the returned buffer when done.
1
1 'gmk_eval'
1 This function takes a buffer and evaluates it as a segment of
1 makefile syntax. This function can be used to define new
1 variables, new rules, etc. It is equivalent to using the 'eval'
1 'make' function.
1
1 Note that there is a difference between 'gmk_eval' and calling
1 'gmk_expand' with a string using the 'eval' function: in the latter case
1 the string will be expanded _twice_; once by 'gmk_expand' and then again
1 by the 'eval' function. Using 'gmk_eval' the buffer is only expanded
1 once, at most (as it's read by the 'make' parser).
1
1 Memory Management
1 .................
1
1 Some systems allow for different memory management schemes. Thus you
1 should never pass memory that you've allocated directly to any 'make'
1 function, nor should you attempt to directly free any memory returned to
1 you by any 'make' function. Instead, use the 'gmk_alloc' and 'gmk_free'
1 functions.
1
1 In particular, the string returned to 'make' by a function registered
1 using 'gmk_add_function' _must_ be allocated using 'gmk_alloc', and the
1 string returned from the 'make' 'gmk_expand' function _must_ be freed
1 (when no longer needed) using 'gmk_free'.
1
1 'gmk_alloc'
1 Return a pointer to a newly-allocated buffer. This function will
1 always return a valid pointer; if not enough memory is available
1 'make' will exit.
1
1 'gmk_free'
1 Free a buffer returned to you by 'make'. Once the 'gmk_free'
1 function returns the string will no longer be valid.
1