chiark
/
gitweb
/
~ian
/
subdirmk.git
/ blobdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
|
commitdiff
|
tree
raw
|
inline
| side by side
Drop Perdir.sd.mk from explicit MAKEFILE_TEMPLATES
[subdirmk.git]
/
subdirmk
/
README
diff --git
a/subdirmk/README
b/subdirmk/README
index d43c04b2c0c56922c11d300e272c66370f1f8004..cc309f6ae1ec796febb92b7b4fad8083f2d9669d 100644
(file)
--- a/
subdirmk/README
+++ b/
subdirmk/README
@@
-5,7
+5,7
@@
Introduction
------------
Peter Miller's 1997 essay _Recursive Make Considered Harmful_
------------
Peter Miller's 1997 essay _Recursive Make Considered Harmful_
-persuasively argues that it is better to arran
n
ge to have a single
+persuasively argues that it is better to arrange to have a single
make invocation with the project's complete dependency tree, rather
than the currently conventional `$(MAKE) -C subdirectory' approach.
make invocation with the project's complete dependency tree, rather
than the currently conventional `$(MAKE) -C subdirectory' approach.
@@
-14,7
+14,7
@@
style is not very ergonomic. The main difficulties are:
- constantly having to write out long file and directory names
- the lack of a per-directory make variable namespace means
long make variables (or namespace clashes)
- constantly having to write out long file and directory names
- the lack of a per-directory make variable namespace means
long make variables (or namespace clashes)
- - it is difficult to arrange that one can cd to a subdirectory
+ - it is difficult to arrange that one can cd to a subdirectory
and say `make all' and have something reasonable happen
(to wit, build an appropriate subset)
and say `make all' and have something reasonable happen
(to wit, build an appropriate subset)
@@
-42,9
+42,9
@@
The Subdir.sd.mk's are filtered, fed through autoconf in the usual way
(for @..@-substitutions) and included by one autogenerated toplevel
makefile.
(for @..@-substitutions) and included by one autogenerated toplevel
makefile.
-So all of the input is combined and passed to one make invocation.
(A
-corollary is that there is no enforcement of the namespacing:
-discipline is required to prefix relevant variable names with &, etc.
+So all of the input is combined and passed to one make invocation.
+
(A
corollary is that there is no enforcement of the namespacing:
+discipline is required to prefix relevant variable names with &, etc.
)
Each subdirectory is also provided with an autogenerated `Makefile'
which exists purely to capture ordinary make invocations and arrange
Each subdirectory is also provided with an autogenerated `Makefile'
which exists purely to capture ordinary make invocations and arrange
@@
-67,7
+67,7
@@
Each subdirectory has its own `all' target. For example a
subdirectory `src' has a target `src/all'. The rules for these are
automatically generated from the settings of the per-directory
&TARGETS variables. &TARGETS is magic in this way. (In
subdirectory `src' has a target `src/all'. The rules for these are
automatically generated from the settings of the per-directory
&TARGETS variables. &TARGETS is magic in this way. (In
-src/Subdir.sd.mk, &TARGES of course refers to a make variable called
+src/Subdir.sd.mk, &TARGE
T
S of course refers to a make variable called
src_TARGETS.)
The `all' target in a parent directory is taken to imply the `all'
src_TARGETS.)
The `all' target in a parent directory is taken to imply the `all'
@@
-77,8
+77,9
@@
just type `make' in the toplevel, you are asking for `&all'
(<subdir>/all) for every directory in the project.
In a parallel build, the rules for all these various subdirectory
(<subdir>/all) for every directory in the project.
In a parallel build, the rules for all these various subdirectory
-targets may be in run in parallel: there is only one `make'
-invocation at a time.
+targets may be in run in parallel: there is only one `make' invocation
+at a time. There is no sequencing between subdirectories, only been
+individual targets (as specified according to their dependencies).
You can define other per-directory recursive targets too: simply
mention (usually, by setting) the variable &TARGETS_zonk, or whatever.
You can define other per-directory recursive targets too: simply
mention (usually, by setting) the variable &TARGETS_zonk, or whatever.
@@
-109,6
+110,10
@@
If want to set global variables, such as CC, that should only be done
once. You can put them in your top-level Subdir.sd.mk, or a separate
file you `include' and declare using SUBDIRMK_MAKEFILES.
once. You can put them in your top-level Subdir.sd.mk, or a separate
file you `include' and declare using SUBDIRMK_MAKEFILES.
+If you need different settings of variables like CC for different
+subdirectories, you should probably do that with target-specific
+variable settings. See the info node `(make) Target-specific'.
+
Subdirectory templates `.sd.mk' vs plain autoconf templates `.mk.in'
--------------------------------------------------------------------
Subdirectory templates `.sd.mk' vs plain autoconf templates `.mk.in'
--------------------------------------------------------------------
@@
-151,8
+156,8
@@
we describe the expansion at the top level, which is often a special
case (in general in variable names we call that TOP rather than the
empty string).
case (in general in variable names we call that TOP rather than the
empty string).
-&CAPS => sub_dir_CAPS or TOP_CAPS
-&lc => sub/dir/lc or lc
+&CAPS => sub_dir_CAPS or TOP_CAPS
+&lc => sub/dir/lc or lc
Here CAPS is any ASCII letter A-Z and lc is a-z.
The assumption is that filenames are usually lowercase and
variables usually uppercase. Otherwise, use another syntax:
Here CAPS is any ASCII letter A-Z and lc is a-z.
The assumption is that filenames are usually lowercase and
variables usually uppercase. Otherwise, use another syntax:
@@
-174,7
+179,7
@@
empty string).
Introduced by & followed by lwsp (space or tab).
Each lwsp-separated non-ws word is prefixed by &/ &^/ &~/
respectively. No other & escapes are recognised.
Introduced by & followed by lwsp (space or tab).
Each lwsp-separated non-ws word is prefixed by &/ &^/ &~/
respectively. No other & escapes are recognised.
- This processing continues until
a
& preceded by lwsp,
+ This processing continues until & preceded by lwsp,
or until EOL (the end of the line), or \ then EOL.
&:<directive> <args>....
or until EOL (the end of the line), or \ then EOL.
&:<directive> <args>....
@@
-183,14
+188,18
@@
empty string).
&:include filename filename should usually be foo.sd.mk
&:-include filename tolerate nonexistent file
&:include filename filename should usually be foo.sd.mk
&:-include filename tolerate nonexistent file
+ filenames are relative to $(top_srcdir)
&!<lwsp> disables & until EOL (and then disappears)
&!<lwsp> disables & until EOL (and then disappears)
+&# delete everything to end of line
+ (useful if the RHS contains unrecognise & constructions)
+
&!STUFF
changes the escape sequence from & to literally STUFF
STUFF may be any series of of non-whitespace characters,
&!STUFF
changes the escape sequence from & to literally STUFF
STUFF may be any series of of non-whitespace characters,
- and is terminated by EOL or lwsp. STUFF and the lwsp
-
is
discarded.
+ and is terminated by EOL or lwsp.
&!
STUFF and the lwsp
+
are
discarded.
After this, write STUFF instead of &, everywhere.
The effect is global and lasts until the next setting.
After this, write STUFF instead of &, everywhere.
The effect is global and lasts until the next setting.
@@
-198,14
+207,13
@@
empty string).
it back before using &:include.
Notably
it back before using &:include.
Notably
- STUFFSTUFF => STUFF
+ STUFFSTUFF => STUFF
STUFF
\STUFF => STUFF
STUFF!& set escape back to &
&TARGETS_things
\STUFF => STUFF
STUFF!& set escape back to &
&TARGETS_things
- Handled specially. If mentioned, declares that
- this subdirectory ought to have a target `things'.
- (`all' if not specified). The rule will be
+ Handled specially. If mentioned, declares that this
+ subdir ought to have a target `things'. The rule will be
&/things:: $(&TARGETS_things)
You may extend it by adding more :: rules for the target,
&/things:: $(&TARGETS_things)
You may extend it by adding more :: rules for the target,
@@
-213,13
+221,14
@@
empty string).
&TARGETS_check += & test-passed.stamp
It is important to mention &TARGETS_things at least once in
&TARGETS_check += & test-passed.stamp
It is important to mention &TARGETS_things at least once in
- the context of each applicable directory, because
it arranges
- that the *parent* will also have a `things' target which
- recursively implies this directory's `things'.
+ the context of each applicable directory, because
doing so
+ arranges that the *parent* will also have a `things' target
+
which
recursively implies this directory's `things'.
Must be spelled exactly &TARGETS_things. &_TARGETS_things,
Must be spelled exactly &TARGETS_things. &_TARGETS_things,
- for example, does not work. But mentioning it in a #-comment
- *does* work because the & filter does not care about comments.
+ for example, is not magic. But mentioning &TARGETS_things in
+ a #-comment *does* work because the & filter does not care
+ about comments.
`all' is extra special: every directory has an `all'
target, which corresponds to &TARGETS.
`all' is extra special: every directory has an `all'
target, which corresponds to &TARGETS.