Where there are dependencies between subdirectories, each Dir.sd.mk
can simply refer to files in other subdirectories directly.
-Invocation, "recursive" per-directory targets
----------------------------------------------
-
-Arrangements are made so that when you run `make foo' in a
-subdirectory, it is like running the whole toplevel makefile, from the
-toplevel, as `make subdir/foo'. If `subdir/foo' is a file that might
-be built, that builds it.
-
-But `foo' can also be a conventional target like `all'.
-
-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
-src/Dir.sd.mk, &TARGETS of course refers to a make variable called
-src_TARGETS.)
-
-The `all' target in a parent directory is taken to imply the `all'
-targets in all of its subdirectories, recursively. And in the
-autogenerated stub Makefiles, `all' is the default target. So if you
-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
-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: set the
-variable &TARGETS_zonk, or whatever (being sure to write &TARGETS_zonk
-at the start of a line). This will create a src/zonk target (for
-appropriate value of src/). Unlike `all', these other targets only
-exist in areas of the project where at least something mentions them.
-So for example, if &TARGETS_zonk is set in src but not lib, `make
-zonk' in lib will fail. If you want to make a target exist
-everywhere, += it with nothing in Prefix.sd.mk or Suffix.sd.mk (see
-below).
-
-Prefix.sd.mk, Suffix.sd.mk, Final.sd.mk, inclusion
---------------------------------------------------
-
-The files Prefix.sd.mk and Suffix.sd.mk in the toplevel of the source
-are automatically processed before and after each individual
-directory's Dir.sd.mk, and the &-substituted contents therefore
-appear once for each subdirectory.
-
-This lets you do per-directory boilerplate. Some useful boilerplate
-is already provided in subdirmk, for you to reference like this:
- &:include subdirmk/cdeps.sd.mk
- &:include subdirmk/clean.sd.mk
-For example you could put that in Suffix.sd.mk.
-
-The top-level Dir.sd.mk is the first makefile included after the
-autogenerated `main.mk' which merely has some basic settings and
-includes. So if you want to get in early and set global variables,
-put them near the top of Dir.sd.mk.
-
-The file Final.sd.mk in the toplevel directory is processed and
-included after all the other files.
-
-subdirmk's filter script itself sets (only) these variables:
- top_srcdir
- abs_top_srcdir
- SUBDIRMK_MAKEFILES
- MAKEFILE_TEMPLATES
-You are likely to want to define $(PWD), and shorter names for
-top_srdir and abs_top_srcdir (we suggest $(src) and $(abs_src)).
-
-Global definitions
-------------------
-
-If want to set global variables, such as CC, that should only be done
-once. You can put them in your top-level Dir.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'.
-
-Directory templates `.sd.mk' vs plain autoconf templates `.mk.in'
---------------------------------------------------------------------
-
-There are two kinds of template files.
-
- Filename .sd.mk .mk.in
-
- Processed by &-substitution, autoconf only
- then autoconf
-
- Instantiated Usu. once per subdir Once only
-
- Need to be mentioned No, but Dir.sd.mk All not in subdirmk/
- in configure.ac? via SUBDIRMK_SUBDIRS via SUBDIRMK_MAKEFILES
-
- How to include `&:include foo.sd.mk' `include foo.mk'
- in all relevant .sd.mk in only one
- (but not needed for Dir.sd.mk
- Prefix, Suffix, Final)
-
-If you `include subdirmk/regen.mk', dependency management and
-automatic regeneration for all of this template substitution, and for
-config.status etc. is done for you.
-
Substitution syntax
-------------------
&:include filename filename should usually be [&]foo.sd.mk
&:-include filename tolerate nonexistent file
- filenames are relative to $(top_srcdir)
- RHS is &-expanded
+ RHS is &-expanded but filenames are relative to the top
+ srcdir. This implies that unqualified names are like &~/
+ whereas &/ is like &^/. &^ and &~ do not work here because
+ they expand to constructions involving literally
+ `$(top_srcdir)', but the RHS is not make-expanded.
&!<lwsp> disables & until EOL (and then disappears)
&# delete everything to end of line
(useful if the RHS contains unrecognised & constructions)
-&:changequote NEWQUOTE
- changes the escape sequence from & to literally NEWQUOTE
- NEWQUOTE may be any series of of non-whitespace characters,
- and is terminated by EOL or lwsp. The whole line is
- discarded.
-
- After this, write NEWQUOTE instead of &, everywhere.
- The effect is unscoped and lasts until the next setting,
- or until the end of the current directory's Suffix.sd.mk.
- It takes effect on &:include'd files too, so maybe set
- it back before using &:include.
-
- Notably
- NEWQUOTENEWQUOTE => NEWQUOTENEWQUOTE
- NEWQUOTE\NEWQUOTE => NEWQUOTE
- NEWQUOTE\$ => $
- NEWQUOTE:changequote & set escape back to &
-
&TARGETS_things
Handled specially. If mentioned at the start of a line
(possibly following whitespace), declares that this
`all' is extra special: every directory has an `all'
target, which corresponds to &TARGETS.
+&:warn [!]WARNTAG ...
+ Suppress (with !) or re-enable (without !) warnings tagged
+ WARNTAG (see section `Warnings', below). The suppression list
+ is reset at the start of processing in each subdirectory.
+ Warnings that appear at the end of processing are controlled
+ 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.
+
+&:changequote NEWQUOTE
+ changes the escape sequence from & to literally NEWQUOTE
+ NEWQUOTE may be any series of of non-whitespace characters,
+ and is terminated by EOL or lwsp. The whole line is
+ discarded.
+
+ After this, write NEWQUOTE instead of &, everywhere.
+ The effect is unscoped and lasts until the next setting,
+ or until the end of the current directory's Suffix.sd.mk.
+ It takes effect on &:include'd files too, so maybe set
+ it back before using &:include.
+
+ Notably
+ NEWQUOTENEWQUOTE => NEWQUOTENEWQUOTE
+ NEWQUOTE\NEWQUOTE => NEWQUOTE
+ NEWQUOTE\$ => $
+ NEWQUOTE:changequote & set escape back to &
+
Dollar doubling and macro assistance
------------------------------------
&${..$..} => ${eval ${call ..$$..}}
(matches { } pairs to find the end)
- content is $-doubled (unless it contains $- to turn that off)
+ content is $-doubled (unless it contains &$- to turn that off)
- 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 )' 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 &${...}.
+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 )'
+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 &${...}.
While dollar-doubling:
- - - - - - - - - - -
get $-quadrupling.)
+Invocation, "recursive" per-directory targets
+---------------------------------------------
+
+Arrangements are made so that when you run `make foo' in a
+subdirectory, it is like running the whole toplevel makefile, from the
+toplevel, as `make subdir/foo'. If `subdir/foo' is a file that might
+be built, that builds it.
+
+But `foo' can also be a conventional target like `all'.
+
+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
+src/Dir.sd.mk, &TARGETS of course refers to a make variable called
+src_TARGETS.)
+
+The `all' target in a parent directory is taken to imply the `all'
+targets in all of its subdirectories, recursively. And in the
+autogenerated stub Makefiles, `all' is the default target. So if you
+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
+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: set the
+variable &TARGETS_zonk, or whatever (being sure to write &TARGETS_zonk
+at the start of a line). This will create a src/zonk target (for
+appropriate value of src/). Unlike `all', these other targets only
+exist in areas of the project where at least something mentions them.
+So for example, if &TARGETS_zonk is set in src but not lib, `make
+zonk' in lib will fail. If you want to make a target exist
+everywhere, += it with nothing in Prefix.sd.mk or Suffix.sd.mk (see
+below).
+
+Prefix.sd.mk, Suffix.sd.mk, Final.sd.mk, inclusion
+--------------------------------------------------
+
+The files Prefix.sd.mk and Suffix.sd.mk in the toplevel of the source
+are automatically processed before and after each individual
+directory's Dir.sd.mk, and the &-substituted contents therefore
+appear once for each subdirectory.
+
+This lets you do per-directory boilerplate. Some useful boilerplate
+is already provided in subdirmk, for you to reference like this:
+ &:include subdirmk/cdeps.sd.mk
+ &:include subdirmk/clean.sd.mk
+For example you could put that in Suffix.sd.mk.
+
+The top-level Dir.sd.mk is the first makefile included after the
+autogenerated `main.mk' which merely has some basic settings and
+includes. So if you want to get in early and set global variables,
+put them near the top of Dir.sd.mk.
+
+The file Final.sd.mk in the toplevel directory is processed and
+the result included after all the other files. Its subdirmk
+filtering context inherits warning suppressions from the toplevel's
+Dir.sd.mk etc., but not anything else.
+
+subdirmk's filter script itself sets (only) these variables:
+ top_srcdir
+ abs_top_srcdir
+ SUBDIRMK_MAKEFILES
+ MAKEFILE_TEMPLATES
+You are likely to want to define $(PWD), and shorter names for
+top_srdir and abs_top_srcdir (we suggest $(src) and $(abs_src)).
+
+Warnings
+--------
+
+subdirmk's `generate' program, which does the acual &-substitution,
+can produce some warnings about your .sd.mk files. These can be
+suppressed with the &:warn directive. The warning tags are:
+
+ local+global
+ The same VARNAME was used both with and without an & prefix.
+ This can be confusing. Also, if you avoid this then you will
+ get a warning iff you accidentally leave off a needed &.
+ The generation of this warning depends on scanning your
+ makefile for things that look like variable references, which
+ subdirmk does not do completely perfectly. Exciting make
+ syntax may evade this warning, or require suppressions.
+ (You can suppress this warning for a particular VARNAME with
+ the &:local+global directive.)
+
+ single-char-var
+ A variable expansion like $FBAR. make's expansion rules
+ 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).
+
+ unknown-warning
+ &:warn was used to try to enable a warning that this version
+ of subdirmk does not understand. (Note that an attempt to
+ *dis*able an unknown warning is only reported if some other
+ warning was issued which might have been disabled.)
+
+Global definitions
+------------------
+
+If want to set global variables, such as CC, that should only be done
+once. You can put them in your top-level Dir.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'.
+
+Directory templates `.sd.mk' vs plain autoconf templates `.mk.in'
+--------------------------------------------------------------------
+
+There are two kinds of template files.
+
+ Filename .sd.mk .mk.in
+
+ Processed by &-substitution, autoconf only
+ then autoconf
+
+ Instantiated Usu. once per subdir Once only
+
+ Need to be mentioned No, but Dir.sd.mk All not in subdirmk/
+ in configure.ac? via SUBDIRMK_SUBDIRS via SUBDIRMK_MAKEFILES
+
+ How to include `&:include foo.sd.mk' `include foo.mk'
+ in all relevant .sd.mk in only one
+ (but not needed for Dir.sd.mk
+ Prefix, Suffix, Final)
+
+If you `include subdirmk/regen.mk', dependency management and
+automatic regeneration for all of this template substitution, and for
+config.status etc. is done for you.
+
+
Tables of file reference syntaxes
---------------------------------
(This assumes you have appropriate make variables src, PWD and
abs_src.)
+
Subdirectory and variable naming
--------------------------------
~ian / subdirmk.git / blobdiff