Introduce CDEPS_CFLAGS so without cdeps.sd.mk you don't get .*.d

[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 arrannge 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, &TARGETS 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      =>      STUFFSTUFF

                \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.