chiark / gitweb /
README: Move the Warnings section up into what is going to be spec
[subdirmk.git] / README
diff --git a/README b/README
index e5e937f..50bd4d3 100644 (file)
--- a/README
+++ b/README
@@ -55,109 +55,6 @@ for something suitable to happen.
 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
 -------------------
 
@@ -269,6 +166,19 @@ So pathname syntax is a subset of:
        `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,
@@ -306,16 +216,15 @@ STUFF $ THINGS    ..      STUFF $$ THINGS
 
 &${..$..} =>   ${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:
 - - - - - - - - - - -
@@ -332,6 +241,143 @@ or places where this might imply $-quadrupling.  (There is no way to
 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
 ---------------------------------
 
@@ -373,6 +419,7 @@ In more detail, with all the various options laid out:
 (This assumes you have appropriate make variables src, PWD and
 abs_src.)
 
+
 Subdirectory and variable naming
 --------------------------------