From 5058a94ee717d96285da20423324af3478df175d Mon Sep 17 00:00:00 2001 From: Paul Smith Date: Mon, 25 Feb 2013 01:38:36 -0500 Subject: Expand the loadable object support. Provide a simple API for loaded objects to interact with GNU make. I still won't guarantee that this API won't change but it's much closer to something that's supported and provides easy-to-use interfaces with a public header file. --- doc/make.texi | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 129 insertions(+), 19 deletions(-) (limited to 'doc') diff --git a/doc/make.texi b/doc/make.texi index f5ca116..2fe7aa6 100644 --- a/doc/make.texi +++ b/doc/make.texi @@ -348,6 +348,7 @@ Loading Dynamic Objects * load Directive:: Loading dynamic objects as extensions. * Remaking Loaded Objects:: How loaded objects get remade. +* Loaded Object API:: Programmatic interface for loaded objects. @end detailmenu @end menu @@ -10658,23 +10659,24 @@ exports these procedures as public interfaces from that module: @table @code @item gmk-expand +@findex gmk-expand This procedure takes a single argument which is converted into a string. The string is expanded by @code{make} using normal @code{make} expansion rules. The result of the expansion is converted into a Guile string and provided as the result of the procedure. @item gmk-eval +@findex gmk-eval This procedure takes a single argument which is converted into a string. The string is evaluated by @code{make} as if it were a makefile. This is the same capability available via the @code{eval} function (@pxref{Eval Function}). The result of the @code{gmk-eval} procedure is always the empty string. -@item gmk-var -This procedure takes a single argument which is converted into a -string. The string is assumed to be the name of a @code{make} -variable, which is then expanded. The expansion is converted into a -string and provided as the result of the procedure. +Note that @code{gmk-eval} is not quite the same as using +@code{gmk-expand} with the @code{eval} function: in the latter case +the evaluated string will be expanded @emph{twice}; first by +@code{gmk-expand}, then again by the @code{eval} function. @end table @@ -10756,8 +10758,8 @@ symbol to be stored in a @code{make} variable. @node Loading Objects, , Guile Integration, Extending make @section Loading Dynamic Objects -@cindex loading objects -@cindex objects, loading +@cindex loaded objects +@cindex objects, loaded @cindex extensions, loading @cartouche @@ -10767,12 +10769,6 @@ The @code{load} directive and extension capability is considered a to experiment with this feature and we appreciate any feedback on it. However we cannot guarantee to maintain backward-compatibility in the next release. - -In particular, for this feature to be useful your extensions will need -to invoke various functions internal to GNU @code{make}. In this -release there is no stable programming interface defined for -@code{make}: any internal function may change or even disappear in -future releases. @end quotation @end cartouche @@ -10791,6 +10787,7 @@ for example, and the ``setup'' function would register them with GNU @menu * load Directive:: Loading dynamic objects as extensions. * Remaking Loaded Objects:: How loaded objects get remade. +* Loaded Object API:: Programmatic interface for loaded objects. @end menu @node load Directive, Remaking Loaded Objects, Loading Objects, Loading Objects @@ -10829,7 +10826,7 @@ If no @var{symbol-name} is provided, the initializing function name is created by taking the base file name of @var{object-file}, up to the first character which is not a valid symbol name character (alphanumerics and underscores are valid symbol name characters). To -this prefix will be appended the suffix @code{_gmake_setup}. +this prefix will be appended the suffix @code{_gmk_setup}. More than one object file may be loaded with a single @code{load} directive, and both forms of @code{load} arguments may be used in the @@ -10848,7 +10845,7 @@ load ../mk_funcs.so will load the dynamic object @file{../mk_funcs.so}. After the object is loaded, @code{make} will invoke the function (assumed to be defined -by the shared object) @code{mk_funcs_gmake_setup}. +by the shared object) @code{mk_funcs_gmk_setup}. On the other hand: @@ -10875,11 +10872,11 @@ generated if an object fails to load. The failed object is not added to the @code{.LOADED} variable, which can then be consulted to determine if the load was successful. -@node Remaking Loaded Objects, , load Directive, Loading Objects +@node Remaking Loaded Objects, Loaded Object API, load Directive, Loading Objects @subsection How Loaded Objects Are Remade -@cindex updating load objects -@cindex remaking load objects -@cindex load objects, remaking of +@cindex updating loaded objects +@cindex remaking loaded objects +@cindex loaded objects, remaking of Loaded objects undergo the same re-make procedure as makefiles (@pxref{Remaking Makefiles, ,How Makefiles Are Remade}). If any @@ -10891,6 +10888,119 @@ support this.@refill It's up to the makefile author to provide the rules needed for rebuilding the loaded object. +@node Loaded Object API, , Remaking Loaded Objects, Loading Objects +@subsection Loaded Object Interface +@cindex loaded object API +@cindex interface for loaded objects + +@cartouche +@quotation Warning +For this feature to be useful your extensions will need to invoke +various functions internal to GNU @code{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 @code{make}. +@end quotation +@end cartouche + +To be useful, loaded objects must be able to interact with GNU +@code{make}. This interaction includes both interfaces the loaded +object provides to makefiles and also interfaces the loaded object can +use to manipulate @code{make}'s operation. + +The interface between loaded objects and @code{make} is defined by the +@file{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 +@code{make} functions using the @code{gmk_add_function} routine from +within its setup function. The implementations of these @code{make} +functions may make use of the @code{gmk_expand} and @code{gmk_eval} +routines to perform their tasks. + +@subsubheading Data Structures + +@table @code +@item gmk_floc +This structure represents a filename/location pair. It is provided +when defining items, so GNU @code{make} can inform the user later +where the definition occurred if necessary. +@end table + +@subsubheading Registering Functions + +There is currently one way for makefiles to invoke operations provided +by the loaded object: through the @code{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 @code{gmk_add_function} to create a new @code{make} function. Its +arguments are as follows: + +@table @code +@item 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. + +@item func_ptr +A pointer to a function that @code{make} will invoke when it expands +the function in a makefile. This function must be defined by the +loaded object. GNU @code{make} will call it with three arguments: +@code{name} (the same name as above), @code{argc} (the number of +arguments to the function), and @code{argv} (the list of arguments to +the function). The last argument (that is, @code{argv[argc]} will be +null (@code{0}). + +@item min_args +The minimum number of arguments the function will accept. Must be +between 0 and 255. GNU @code{make} will check this and fail before +invoking @code{func_ptr} if the function was invoked with too few +arguments. + +@item max_args +The maximum number of arguments the function will accept. Must be +between 0 and 255. GNU @code{make} will check this and fail before +invoking @code{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 @code{min_args}. + +@item expand_args +If this value is 0, then @code{make} will not expand the arguments to +the function before passing them to @code{func_ptr}. If the value is +non-0, then the arguments will be expanded first. +@end table + +@subsubheading GNU @code{make} Facilities + +There are some facilities exported by GNU @code{make} for use by +loaded objects. Typically these would be run from within the +setup function and/or the functions registered via +@code{gmk_add_function}, to retrieve or modify the data @code{make} +works with. + +@table @code +@item gmk_expand +This function takes a string and expands it using @code{make} +expansion rules. The result of the expansion is returned in a string +that has been allocated using @code{malloc}. The caller is +responsible for calling @code{free} on the string when done. + +@item 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 @code{eval} @code{make} function. + +Note that there is a difference between @code{gmk_eval} and calling +@code{gmk_expand} with a string using the @code{eval} function: in +the latter case the string will be expanded @emph{twice}; once by +@code{gmk_expand} and then again by the @code{eval} function. Using +@code{gmk_eval} the buffer is only expanded once, at most (as it's +read by the @code{make} parser). +@end table + @node Features, Missing, Extending make, Top @chapter Features of GNU @code{make} @cindex features of GNU @code{make} -- cgit v1.2.3