X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=subdirmk.git;a=blobdiff_plain;f=README;h=a44fb492b47301ea3bbbef8c102c645c5e4c9f8c;hp=e5e937fc7b1927561953a1992dd32d3285da87cc;hb=02276fc4ac88fc9cd85625c749ffe4305a8a69f8;hpb=05c6af41adb9be0c0f7a7595bba06b4341c3feae diff --git a/README b/README index e5e937f..a44fb49 100644 --- 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' -(/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,61 +241,110 @@ or places where this might imply $-quadrupling. (There is no way to get $-quadrupling.) -Tables of file reference syntaxes ---------------------------------- +Invocation, "recursive" per-directory targets +--------------------------------------------- -In a nonrecursive makefile supporting out of tree builds there are -three separate important distinctions between different file -locations: +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. - (i) In the build tree, or in the source tree ? +But `foo' can also be a conventional target like `all'. - (ii) In (or relative to) the subdirectory to which this Dir.sd.mk - relates, or relative to the project's top level ? +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.) - (iii) Absolute or relative pathname ? Usually relative pathnames - suffice. Where an absolute pathname is needed, it can be built - out of &/ and an appropriate make variable such as $(PWD). +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' +(/all) for every directory in the project. -Path construction &-expansions are built from the following: +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). - Relative paths in... - build source - - This directory & &^ - Top level . &~ +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). -In more detail, with all the various options laid out: +Prefix.sd.mk, Suffix.sd.mk, Final.sd.mk, inclusion +-------------------------------------------------- - Recommended Relative paths in... Absolute paths in... - for build source build source - - This lc &file &^file $(PWD)/&file $(abs_src)/&file - directory any &/file &^/file $(PWD)/&/file $(abs_src)/&/file - several & f g h &^ f g h $(addprefix...) - - Top lc file &~file - level any file &~/file $(PWD)/file $(abs_src)/file - .mk.in file $(src)/file $(PWD)/file $(abs_src)/file - several f g h &~ f g h $(addprefix...) +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 assumes you have appropriate make variables src, PWD and -abs_src.) +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. -Subdirectory and variable naming --------------------------------- +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 simple variable decoration scheme does not enforce a strict -namespace distinction between parts of variable names which come from -subdirectory names, and parts that mean something else. +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. -So it is a good idea to be a bit careful with your directory naming. -`TOP', names that contain `_', and names that are similar to parts of -make variables (whether conventional ones, or ones used in your -project) are best avoided. +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)). -If you name your variables in ALL CAPS and your subdirectories in -lower case with `-' rather than `_', there will be no confusion. +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.) + + +Guides, hints, and further explanations +======================================= Incorporating this into your project ------------------------------------ @@ -403,8 +361,9 @@ In your configure.ac, say m4_include([subdirmk/subdirmk.ac]) SUBDIRMK_SUBDIRS([...list of subdirectories in relative syntax...]) -Write a Dir.sd.mk in each directory. The toplevel one should -probably contain: +Write a Dir.sd.mk in each directory. See the substitution syntax +reference, above, and the example/ directory here. The toplevel +Dir.sd.mk should probably contain: include subdirmk/usual.mk include subdirmk/regen.mk @@ -415,6 +374,7 @@ have: &:include subdirmk/cdeps.sd.mk &:include subdirmk/clean.sd.mk + Hints ----- @@ -449,8 +409,103 @@ clean' (or `make realclean') these dependencies are suppressed, which will clear up the problem. +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 +--------------------------------- + +In a nonrecursive makefile supporting out of tree builds there are +three separate important distinctions between different file +locations: + + (i) In the build tree, or in the source tree ? + + (ii) In (or relative to) the subdirectory to which this Dir.sd.mk + relates, or relative to the project's top level ? + + (iii) Absolute or relative pathname ? Usually relative pathnames + suffice. Where an absolute pathname is needed, it can be built + out of &/ and an appropriate make variable such as $(PWD). + +Path construction &-expansions are built from the following: + + Relative paths in... + build source + + This directory & &^ + Top level . &~ + +In more detail, with all the various options laid out: + + Recommended Relative paths in... Absolute paths in... + for build source build source + + This lc &file &^file $(PWD)/&file $(abs_src)/&file + directory any &/file &^/file $(PWD)/&/file $(abs_src)/&/file + several & f g h &^ f g h $(addprefix...) + + Top lc file &~file + level any file &~/file $(PWD)/file $(abs_src)/file + .mk.in file $(src)/file $(PWD)/file $(abs_src)/file + several f g h &~ f g h $(addprefix...) + +(This assumes you have appropriate make variables src, PWD and +abs_src.) + + +Subdirectory and variable naming +-------------------------------- + +The simple variable decoration scheme does not enforce a strict +namespace distinction between parts of variable names which come from +subdirectory names, and parts that mean something else. + +So it is a good idea to be a bit careful with your directory naming. +`TOP', names that contain `_', and names that are similar to parts of +make variables (whether conventional ones, or ones used in your +project) are best avoided. + +If you name your variables in ALL CAPS and your subdirectories in +lower case with `-' rather than `_', there will be no confusion. + + Legal information ------------------ +================= subdirmk is Copyright 2019 Mark Wooding