diff options
Diffstat (limited to 'doc/make.texi')
| -rw-r--r-- | doc/make.texi | 593 |
1 files changed, 377 insertions, 216 deletions
diff --git a/doc/make.texi b/doc/make.texi index 67f45c6..3a16dd3 100644 --- a/doc/make.texi +++ b/doc/make.texi @@ -100,6 +100,7 @@ Cover art by Etienne Suvasa. * Implicit Rules:: Use implicit rules to treat many files alike, based on their file names. * Archives:: How @code{make} can update library archives. +* Extending make:: Using extensions to @code{make}. * Features:: Features GNU @code{make} has over other @code{make}s. * Missing:: What GNU @code{make} lacks from other @code{make}s. * Makefile Conventions:: Conventions for writing makefiles for @@ -277,13 +278,7 @@ Functions for Transforming Text * Flavor Function:: Find out the flavor of a variable. * Make Control Functions:: Functions that control how make runs. * Shell Function:: Substitute the output of a shell command. -* Guile Function:: Call the GNU Guile embedded scripting language. - -The @code{guile} Function - -* Guile Types:: Converting Guile types to @code{make} strings. -* Guile Interface:: Invoking @code{make} functions from Guile. -* Guile Example:: Example using Guile in @code{make}. +* Guile Function:: Use GNU Guile embedded scripting language. How to Run @code{make} @@ -339,6 +334,21 @@ Implicit Rule for Archive Member Targets * Archive Symbols:: How to update archive symbol directories. +Extending GNU @code{make} + +* Guile Integration:: Using Guile as an embedded scripting language. +* Loading Objects:: Loading dynamic objects as extensions. + +GNU Guile Integration + +* Guile Types:: Converting Guile types to @code{make} strings. +* Guile Interface:: Invoking @code{make} functions from Guile. +* Guile Example:: Example using Guile in @code{make}. + +Loading Dynamic Objects + +* load Directive:: Loading dynamic objects as extensions. + @end detailmenu @end menu @@ -6280,7 +6290,11 @@ Supports the @code{undefine} directive. @xref{Undefine Directive}. @item guile Has GNU Guile available as an embedded extension language. -@xref{Guile Function}. +@xref{Guile Integration, ,GNU Guile Integration}. + +@item load +Supports dynamically loadable objects for creating custom extensions. +@xref{Loading Objects, ,Loading Dynamic Objects}. @end table @@ -6422,12 +6436,12 @@ endif or: @example -@var{conditional-directive} +@var{conditional-directive-one} @var{text-if-one-is-true} -else @var{conditional-directive} -@var{text-if-true} +else @var{conditional-directive-two} +@var{text-if-two-is-true} else -@var{text-if-false} +@var{text-if-one-and-two-are-false} endif @end example @@ -6631,7 +6645,7 @@ be substituted. * Flavor Function:: Find out the flavor of a variable. * Make Control Functions:: Functions that control how make runs. * Shell Function:: Substitute the output of a shell command. -* Guile Function:: Call the GNU Guile embedded scripting language. +* Guile Function:: Use GNU Guile embedded scripting language. @end menu @node Syntax of Functions, Text Functions, Functions, Functions @@ -7896,208 +7910,17 @@ exists).@refill @findex guile @cindex Guile -GNU make may be built with support for GNU Guile as an embedded -extension language. You can check the @code{.FEATURES} variable for -the word @samp{guile} to determine if your version of GNU make -provides this capability. - -GNU Guile implements the Scheme language. A review of GNU Guile and -the Scheme language and its features is beyond the scope of this -manual: see the documentation for GNU Guile and Scheme. - -If GNU Guile is available as an extension language, there will be one -new @code{make} function available: @code{guile}. The @code{guile} -function takes one argument which is first expanded by @code{make} in -the normal fashion, then passed to the GNU Guile evaluator. The -result of the evaluator is converted into a string and used as the -expansion of the @code{guile} function in the makefile. - -Similarly, there are Guile procedures exposed by @code{make} for use -in Guile scripts. - -@menu -* Guile Types:: Converting Guile types to @code{make} strings. -* Guile Interface:: Invoking @code{make} functions from Guile. -* Guile Example:: Example using Guile in @code{make}. -@end menu - -@node Guile Types, Guile Interface, Guile Function, Guile Function -@subsection Conversion of Guile Types -@cindex convert guile types -@cindex guile, conversion of types -@cindex types, conversion of - -There is only one ``data type'' in @code{make}: a string. GNU Guile, -on the other hand, provides a rich variety of different data types. -An important aspect of the interface between @code{make} and GNU Guile -is the conversion of Guile data types into @code{make} strings. - -This conversion is relevant in two places: when a makefile invokes the -@code{guile} function to evaluate a Guile expression, the result of -that evaluation must be converted into a make string so it can be -further evaluated by @code{make}. And secondly, when a Guile script -invokes one of the procedures exported by @code{make} the argument -provided to the procedure must be converted into a string. - -The conversion of Guile types into @code{make} strings is as below: - -@table @code -@item #f -False is converted into the empty string: in @code{make} conditionals -the empty string is considered false. - -@item #t -True is converted to the string @samp{#t}: in @code{make} conditionals -any non-empty string is considered true. - -@item symbol -@item number -A symbol or number is converted into the string representation of that -symbol or number. - -@item character -A printable character is converted to the same character. - -@item string -A string containing only printable characters is converted to the same -string. - -@item list -A list is converted recursively according to the above rules. This -implies that any structured list will be flattened (that is, a result -of @samp{'(a b (c d) e)} will be converted to the @code{make} string -@samp{a b c d e}). - -@item other -Any other Guile type results in an error. In future versions of -@code{make}, other Guile types may be converted. - -@end table - -The translation of @samp{#f} (to the empty string) and @samp{#t} (to -the non-empty string @samp{#t}) is designed to allow you to use Guile -boolean results directly as @code{make} boolean conditions. For -example: - -@example -$(if $(guile (access? "myfile" R_OK)),$(info myfile exists)) -@end example - -As a consequence of these conversion rules you must consider the -result of your Guile script, as that result will be converted into a -string and parsed by @code{make}. If there is no natural result for -the script (that is, the script exists solely for its side-effects), -you should add @samp{#f} as the final expression in order to avoid -syntax errors in your makefile. - -@node Guile Interface, Guile Example, Guile Types, Guile Function -@subsection Interfaces from Guile to @code{make} -@cindex make interface to guile -@cindex make procedures in guile - -In addition to the @code{guile} function available in makefiles, -@code{make} exposes some procedures for use in your Guile scripts. At -startup @code{make} creates a new Guile module, @code{gnu make}, and -exports these procedures as public interfaces from that module: - -@table @code -@item 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 -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. - -@end table - -@node Guile Example, , Guile Interface, Guile Function -@subsection Example Using Guile in @code{make} -@cindex Guile example -@cindex example using Guile - -Here is a very simple example using GNU Guile to manage writing to a -file. These Guile procedures simply open a file, allow writing to the -file (one string per line), and close the file. Note that because we -cannot store complex values such as Guile ports in @code{make} -variables, we'll keep the port as a global variable in the Guile -interpreter. - -You can create Guile functions easily using @code{define}/@code{endef} -to create a Guile script, then use the @code{guile} function to -internalize it: - -@example -@group -define GUILEIO -;; A simple Guile IO library for GNU make - -(define MKPORT #f) - -(define (mkopen name mode) - (set! MKPORT (open-file name mode)) - #f) - -(define (mkwrite s) - (display s MKPORT) - (newline MKPORT) - #f) - -(define (mkclose) - (close-port MKPORT) - #f) - -#f -endef - -# Internalize the Guile IO functions -$(guile $(GUILEIO)) -@end group -@end example - -If you have a significant amount of Guile support code, you might -consider keeping it in a different file (e.g., @file{guileio.scm}) and -then loading it in your makefile using the @code{guile} function: - -@example -$(guile (load "guileio.scm")) -@end example - -An advantage to this method is that when editing @file{guileio.scm}, -your editor will understand that this file contains Scheme syntax -rather than makefile syntax. - -Now you can use these Guile functions to create files. Suppose you -need to operate on a very large list, which cannot fit on the command -line, but the utility you're using accepts the list as input as well: - -@example -@group -prog: $(PREREQS) - @@$(guile (mkopen "tmp.out" "w")) \ - $(foreach X,$^,$(guile (mkwrite "$(X)"))) \ - $(guile (mkclose)) - $(LINK) < tmp.out -@end group -@end example - -A more comprehensive suite of file manipulation procedures is possible -of course. You could, for example, maintain multiple output files at -the same time by choosing a symbol for each one and using it as the -key to a hash table, where the value is a port, then returning the -symbol to be stored in a @code{make} variable. +If GNU @code{make} is built with support for GNU Guile as an embedded +extension language then the @code{guile} function will be available. +The @code{guile} function takes one argument which is first expanded +by @code{make} in the normal fashion, then passed to the GNU Guile +evaluator. The result of the evaluator is converted into a string and +used as the expansion of the @code{guile} function in the makefile. +See @ref{Guile Integration, ,GNU Guile Integration} for details on +writing extensions to @code{make} in Guile. +You can determine whether GNU Guile support is available by checking +the @code{.FEATURES} variable for the word @var{guile}. @node Running, Implicit Rules, Functions, Top @chapter How to Run @code{make} @@ -10476,7 +10299,7 @@ When the recipe of a pattern rule is executed for @var{t}, the automatic variables are set corresponding to the target and prerequisites. @xref{Automatic Variables}. -@node Archives, Features, Implicit Rules, Top +@node Archives, Extending make, Implicit Rules, Top @chapter Using @code{make} to Update Archive Files @cindex archive @@ -10703,7 +10526,345 @@ in the normal way (@pxref{Suffix Rules}). Thus a double-suffix rule @w{@samp{.@var{x}.a}} produces two pattern rules: @samp{@w{(%.o):} @w{%.@var{x}}} and @samp{@w{%.a}: @w{%.@var{x}}}.@refill -@node Features, Missing, Archives, Top +@node Extending make, Features, Archives, Top +@chapter Extending GNU @code{make} +@cindex make extensions + +GNU @code{make} provides many advanced capabilities, including many +useful functions. However, it does not contain a complete programming +language and so it has limitations. Sometimes these limitations can be +overcome through use of the @code{shell} function to invoke a separate +program, although this can be inefficient. + +In cases where the built-in capabilities of GNU @code{make} are +insufficient to your requirements there are two options for extending +@code{make}. On systems where it's provided, you can utilize GNU +Guile as an embedded scripting language (@pxref{Guile Integration, +,GNU Guile Integration}). On systems which support dynamically +loadable objects, you can write your own extension in any language +(which can be compiled into such an object) and load it to provide +extended capabilities (@pxref{load Directive, ,The @code{load} Directive}). + +@menu +* Guile Integration:: Using Guile as an embedded scripting language. +* Loading Objects:: Loading dynamic objects as extensions. +@end menu + +@node Guile Integration, Loading Objects, Extending make, Extending make +@section GNU Guile Integration +@cindex Guile +@cindex extensions, Guile + +GNU @code{make} may be built with support for GNU Guile as an embedded +extension language. Guile implements the Scheme language. A review +of GNU Guile and the Scheme language and its features is beyond the +scope of this manual: see the documentation for GNU Guile and Scheme. + +You can determine if @code{make} contains support for Guile by +examining the @code{.FEATURES} variable; it will contain the word +@var{guile} if Guile support is available. + +The Guile integration provides one new @code{make} function: @code{guile}. +The @code{guile} function takes one argument which is first expanded +by @code{make} in the normal fashion, then passed to the GNU Guile +evaluator. The result of the evaluator is converted into a string and +used as the expansion of the @code{guile} function in the makefile. + +In addition, GNU @code{make} exposes Guile procedures for use in Guile +scripts. + +@menu +* Guile Types:: Converting Guile types to @code{make} strings. +* Guile Interface:: Invoking @code{make} functions from Guile. +* Guile Example:: Example using Guile in @code{make}. +@end menu + +@node Guile Types, Guile Interface, Guile Integration, Guile Integration +@subsection Conversion of Guile Types +@cindex convert guile types +@cindex guile, conversion of types +@cindex types, conversion of + +There is only one ``data type'' in @code{make}: a string. GNU Guile, +on the other hand, provides a rich variety of different data types. +An important aspect of the interface between @code{make} and GNU Guile +is the conversion of Guile data types into @code{make} strings. + +This conversion is relevant in two places: when a makefile invokes the +@code{guile} function to evaluate a Guile expression, the result of +that evaluation must be converted into a make string so it can be +further evaluated by @code{make}. And secondly, when a Guile script +invokes one of the procedures exported by @code{make} the argument +provided to the procedure must be converted into a string. + +The conversion of Guile types into @code{make} strings is as below: + +@table @code +@item #f +False is converted into the empty string: in @code{make} conditionals +the empty string is considered false. + +@item #t +True is converted to the string @samp{#t}: in @code{make} conditionals +any non-empty string is considered true. + +@item symbol +@item number +A symbol or number is converted into the string representation of that +symbol or number. + +@item character +A printable character is converted to the same character. + +@item string +A string containing only printable characters is converted to the same +string. + +@item list +A list is converted recursively according to the above rules. This +implies that any structured list will be flattened (that is, a result +of @samp{'(a b (c d) e)} will be converted to the @code{make} string +@samp{a b c d e}). + +@item other +Any other Guile type results in an error. In future versions of +@code{make}, other Guile types may be converted. + +@end table + +The translation of @samp{#f} (to the empty string) and @samp{#t} (to +the non-empty string @samp{#t}) is designed to allow you to use Guile +boolean results directly as @code{make} boolean conditions. For +example: + +@example +$(if $(guile (access? "myfile" R_OK)),$(info myfile exists)) +@end example + +As a consequence of these conversion rules you must consider the +result of your Guile script, as that result will be converted into a +string and parsed by @code{make}. If there is no natural result for +the script (that is, the script exists solely for its side-effects), +you should add @samp{#f} as the final expression in order to avoid +syntax errors in your makefile. + +@node Guile Interface, Guile Example, Guile Types, Guile Integration +@subsection Interfaces from Guile to @code{make} +@cindex make interface to guile +@cindex make procedures in guile + +In addition to the @code{guile} function available in makefiles, +@code{make} exposes some procedures for use in your Guile scripts. At +startup @code{make} creates a new Guile module, @code{gnu make}, and +exports these procedures as public interfaces from that module: + +@table @code +@item 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 +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. + +@end table + +@node Guile Example, , Guile Interface, Guile Integration +@subsection Example Using Guile in @code{make} +@cindex Guile example +@cindex example using Guile + +Here is a very simple example using GNU Guile to manage writing to a +file. These Guile procedures simply open a file, allow writing to the +file (one string per line), and close the file. Note that because we +cannot store complex values such as Guile ports in @code{make} +variables, we'll keep the port as a global variable in the Guile +interpreter. + +You can create Guile functions easily using @code{define}/@code{endef} +to create a Guile script, then use the @code{guile} function to +internalize it: + +@example +@group +define GUILEIO +;; A simple Guile IO library for GNU make + +(define MKPORT #f) + +(define (mkopen name mode) + (set! MKPORT (open-file name mode)) + #f) + +(define (mkwrite s) + (display s MKPORT) + (newline MKPORT) + #f) + +(define (mkclose) + (close-port MKPORT) + #f) + +#f +endef + +# Internalize the Guile IO functions +$(guile $(GUILEIO)) +@end group +@end example + +If you have a significant amount of Guile support code, you might +consider keeping it in a different file (e.g., @file{guileio.scm}) and +then loading it in your makefile using the @code{guile} function: + +@example +$(guile (load "guileio.scm")) +@end example + +An advantage to this method is that when editing @file{guileio.scm}, +your editor will understand that this file contains Scheme syntax +rather than makefile syntax. + +Now you can use these Guile functions to create files. Suppose you +need to operate on a very large list, which cannot fit on the command +line, but the utility you're using accepts the list as input as well: + +@example +@group +prog: $(PREREQS) + @@$(guile (mkopen "tmp.out" "w")) \ + $(foreach X,$^,$(guile (mkwrite "$(X)"))) \ + $(guile (mkclose)) + $(LINK) < tmp.out +@end group +@end example + +A more comprehensive suite of file manipulation procedures is possible +of course. You could, for example, maintain multiple output files at +the same time by choosing a symbol for each one and using it as the +key to a hash table, where the value is a port, then returning the +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 extensions, loading + +@cartouche +@quotation Warning +The @code{load} directive and extension capability is considered a +``technology preview'' in this release of GNU make. We encourage you +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 + +Many operating systems provide a facility for dynamically loading +compiled objects. If your system provides this facility, GNU +@code{make} can make use of it to load dynamic objects at runtime, +providing new capabilities which may then be invoked by your makefile. + +The @code{load} directive is used to load a dynamic object. Once the +object is loaded, a ``setup'' function will be invoked to allow the +object to initialize itself and register new facilities with GNU +@code{make}. Typically a dynamic object would create new functions, +for example, and the ``setup'' function would register them with GNU +@code{make}'s function handling system. + +@menu +* load Directive:: Loading dynamic objects as extensions. +@end menu + +@node load Directive, , Loading Objects, Loading Objects +@subsection The @code{load} Directive +@cindex load directive +@cindex extensions, load directive + +Objects are loaded into GNU @code{make} by placing the @code{load} +directive into your makefile. The syntax of the @code{load} directive +is as follows: + +@findex load +@example +load @var{object-file} @dots{} +@end example + +or: + +@example +load @var{object-file}(@var{symbol-name}) @dots{} +@end example + +In the first form, the file @var{object-file} is dynamically loaded by +GNU @code{make}. On failure, @code{make} will print a message and +exit. If the load succeeds @code{make} will invoke an initializing +function whose 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}, then this symbol will be invoked. + +In the second form, the function @var{symbol-name} will be invoked. + +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 +same directive. + +For example: + +@example +load ../mk_funcs.so +@end example + +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}. + +On the other hand: + +@example +load ../mk_funcs.so(init_mk_func) +@end example + +will load the dynamic object @file{../mk_funcs.so}. After the object +is loaded, @code{make} will invoke the function @code{init_mk_func}. + +Regardless of how many times an object file appears in a @code{load} +directive, it will only be loaded (and it's setup function will only +be invoked) once. + +@vindex .LOADED +After an object has been successfully loaded, its file name is +appended to the @code{.LOADED} variable. + +@findex -load +If you would prefer that failure to load a dynamic object not be +reported as an error, you can use the @code{-load} directive instead +of @code{load}. GNU @code{make} will not fail and no message will be +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 Features, Missing, Extending make, Top @chapter Features of GNU @code{make} @cindex features of GNU @code{make} @cindex portability |