12.2.3 Loaded Object Interface

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 few 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_free

Free a buffer returned to you by make. Once the gmk_free function returns the string will no longer be valid.

This document was generated on October 10, 2013 using texi2html 5.0.