&= => sub_dir or TOP
-&^lc => $(top_srcdir)/sub/dir/lc
-&^/ => $(top_srcdir)/sub/dir/
-&^. => $(top_srcdir)/sub/dir
+&^lc => ${top_srcdir}/sub/dir/lc
+&^/ => ${top_srcdir}/sub/dir/
+&^. => ${top_srcdir}/sub/dir
-&~lc => $(top_srcdir)/lc
-&~/ => $(top_srcdir)/
-&~. => $(top_srcdir)
+&~lc => ${top_srcdir}/lc
+&~/ => ${top_srcdir}/
+&~. => ${top_srcdir}
In general:
^ pathname of this subdirectory in source tree
&\$ => $ provided for $-doubling regimes
&\NEWLINE eats the newline and vanishes
-&$VARIABLE => $(sub_dir_VARIABLE) or $(TOP_VARIABLE)
+&$VARIABLE => ${sub_dir_VARIABLE} or ${TOP_VARIABLE}
VARIABLE is ASCII starting with a letter and matching \w+
& thing thing... &
&:<directive> <args>....
recognised at start of line only (possibly after lwsp)
+&: => &:
+ for make multiple targets syntax
+ recognised anywhere *except* start of line
+
&:include filename filename should usually be [&]foo.sd.mk
&:-include filename tolerate nonexistent file
RHS is &-expanded but filenames are relative to the top
`all' is extra special: every directory has an `all'
target, which corresponds to &TARGETS.
+Directives
+- - - - -
+
&:warn [!]WARNTAG ...
Suppress (with !) or re-enable (without !) warnings tagged
WARNTAG (see section `Warnings', below). The suppression list
by the final warning state after processing all the toplevel
input files (including Final.sd.mk).
-&:local+global [&]VARIABLE ...
- Suppresses the warning about seeing both VARIABLE and
- &VARIABLE. Any & specified in the RHS is redundant: this
- always affects both versions identically.
+&:local+global [!][&]VARIABLE ...
+ Suppresses any warnings relating to forthcoming mentions
+ to VARIABLE or &VARIABLE, as applicable. Scope ends at
+ the end of the current directory's Suffix.sd.mk.
+ Prefixing with ! removes [&]VARIABLE from the suppresion list.
&:changequote NEWQUOTE
changes the escape sequence from & to literally NEWQUOTE
&$- Stops dollar-doubling
Both are idempotent and local to the file or context.
+This is useful both for make macrology involving $(eval ...), and
+possibly for helping write complicated recipes involving shell
+variables, inline Perl code, etc.
+
Sometimes we will show $'s being doubled inside another construct.
This means the content of the construct is $-doubled: $-doubling is
locally enabled, and restored afterwards.
&:endm .. endef
NAME is processed for &
-&${..$..} => ${eval ${call ..$$..}}
+&{..$..} => ${eval ${call ..$$..}}
(matches { } pairs to find the end)
content is $-doubled (unless it contains &$- to turn that off)
+ contrast &(...), see "Convenience syntax for call", below.
-Together &:macro and &${...} provide a more reasonable macro facility
+Together &:macro and &{...} provide a more reasonable macro facility
than raw make. They solve the problem that make expansions cannot
-directly generate multiple rules, variable, etc.; instead, `$(eval )'
+directly generate multiple rules, variables, etc.; instead, `$(eval )'
must be used, but that re-expands the argument, meaning that all the
literal text must be $-doubled. This applies to the macro text and to
the arguments. Also `$(eval $(call ...))' is an unfortunate syntax.
-Hence &:macro and &${...}.
+Hence &:macro and &{...}.
While dollar-doubling:
- - - - - - - - - - -
&-expansions not mentioned here
&\$ => $
-&$NN => $(NN) where N are digits
&$( => $(
+&$NN => ${NN} where N are digits
A few contexts do not support $-doubling, such as directive arguments
or places where this might imply $-quadrupling. (There is no way to
get $-quadrupling.)
+Convenience syntax for call
+- - - - - - - - - - - - - -
+
+&(thing => $(call thing
+&( thing => $(call thing
+ and specially:
+&(&lc => $(call sub_dir_lc or $(call TOP_lc
+&( &lc => $(call sub_dir_lc or $(call TOP_lc
+ even though lc would normally be thought a filename
+
+Unlike &{...}, this does not involve any dollar-doubling.
+
+Use this when the expansion is going to be a piece of text to be used
+as part of a rule, filename, etc. When the expansion is top-level
+make text (eg, rules), use &:macro and &{...}.
+
Invocation, "recursive" per-directory targets
---------------------------------------------
interpret this as $(F)BAR. It's normally better to write
it this way, at least if the variable expansion is followed
by more letters. Note that &$FOO works differently to
- raw make: it expands to $(sub_dir_FOO).
+ raw make: it expands to ${sub_dir_FOO}.
+
+ broken-var-ref
+ An attempt at variable expansion looking like $&...
+ You probably expected this to mean $(TOP_F)BAR but it
+ expands to $TOP_FBAR which make thinks means $(T)OP_FBAR.
unknown-warning
&:warn was used to try to enable a warning that this version
just rerun ./config.status by hand.
If you go back and forth between different versions of your code you
-can sometimes find that `make' complains that one of your Subdir.sd.mk
+can sometimes find that `make' complains that one of your Dir.sd.mk
files is missing: typically, if iot was used and therefore a
dependency in some other version of your code. If you run `make
clean' (or `make realclean') these dependencies are suppressed, which
=================
subdirmk is
+ Copyright 2019-2020 Ian Jackson
Copyright 2019 Mark Wooding
- Copyright 2019 Ian Jackson
subdirmk and its example is free software; you can redistribute it
and/or modify it under the terms of the GNU Library General Public