X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=subdirmk.git;a=blobdiff_plain;f=README;h=4493a0da2f146b5bf9121f09aa780ee9b3ee5cfa;hp=6705b14b8b8ec77bacfd664f2862f588439a6196;hb=b0bdaa30dd60890b5494fab1f3e7f5d70a8ceb8e;hpb=51c56a8542758518adbd0e4739d526d423d4a006 diff --git a/README b/README index 6705b14..4493a0d 100644 --- a/README +++ b/README @@ -88,13 +88,13 @@ empty string). &= => 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 @@ -114,7 +114,7 @@ So pathname syntax is a subset of: &\$ => $ 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... & @@ -174,10 +174,11 @@ So pathname syntax is a subset of: 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 @@ -205,6 +206,10 @@ Dollar doubling and macro assistance &$- 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. @@ -214,7 +219,7 @@ STUFF $ THINGS .. STUFF $$ THINGS &: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) @@ -233,8 +238,8 @@ $ => $$ including $'s produced by other &-expansions not mentioned here &\$ => $ -&$NN => $(NN) where N are digits -&$( => $( +&$( => ${ (expands to { } so it is useable for shell too) +&$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 @@ -334,7 +339,12 @@ suppressed with the &:warn directive. The warning tags are: 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 @@ -346,6 +356,69 @@ suppressed with the &:warn directive. The warning tags are: Guides, hints, and further explanations ======================================= +Incorporating this into your project +------------------------------------ + +Use `git-subtree' to merge the subdirmk/ directory. You may find it +useful to symlink the DEVELOPER-CERTIFICATE file (git can store +symlinks as symlinks - just `git add' the link). And you probably +want to mention the situation in your top-level COPYING and HACKING. + +Symlink autogen.sh into your project toplevel. + +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. 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 + +Write a Suffix.sd.mk in the toplevel, if you want. It should probably +have: + + &:include subdirmk/cdeps.sd.mk + &:include subdirmk/clean.sd.mk + + +Hints +----- + +You can convert your project incrementally. Start with the top-level +Makefile.in and rename it to Dir.sd.mk, and add the appropriate +stuff to configure.ac, and fix everything up. Leave the existing +$(MAKE) -C for your existing subdirectories alone. Then you can +convert individual subdirectories, or classes of subdirectories, at +your leisure. (You must be /sure/ that each recursive (non-subdirmk) +subdirectory will be entered only once at a time, but your existing +recursive make descent system should already do that or you already +have concurrency bugs.) + +Aside from this, be very wary of any invocation of $(MAKE) anywhere. +This is a frequent source of concurrency bugs in recursive make build +systems. When combined with nonrecursive make it's all in the same +directory and there is nothing stopping the different invocations +ending up trying to make the same targets at the same time. That +causes hideous racy lossage. There are ways to get this to work +reliably but it is advanced stuff. + +If you make syntax errors, or certain kinds of other errors, in your +makefiles, you may find that just `make' is broken now and cannot get +far enough to regenerate a working set of makefiles. If this happens +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 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 +will clear up the problem. + + Global definitions ------------------ @@ -440,66 +513,6 @@ 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. -Incorporating this into your project ------------------------------------- - -Use `git-subtree' to merge the subdirmk/ directory. You may find it -useful to symlink the DEVELOPER-CERTIFICATE file (git can store -symlinks as symlinks - just `git add' the link). And you probably -want to mention the situation in your top-level COPYING and HACKING. - -Symlink autogen.sh into your project toplevel. - -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: - - include subdirmk/usual.mk - include subdirmk/regen.mk - -Write a Suffix.sd.mk in the toplevel, if you want. It should probably -have: - - &:include subdirmk/cdeps.sd.mk - &:include subdirmk/clean.sd.mk - -Hints ------ - -You can convert your project incrementally. Start with the top-level -Makefile.in and rename it to Dir.sd.mk, and add the appropriate -stuff to configure.ac, and fix everything up. Leave the existing -$(MAKE) -C for your existing subdirectories alone. Then you can -convert individual subdirectories, or classes of subdirectories, at -your leisure. (You must be /sure/ that each recursive (non-subdirmk) -subdirectory will be entered only once at a time, but your existing -recursive make descent system should already do that or you already -have concurrency bugs.) - -Aside from this, be very wary of any invocation of $(MAKE) anywhere. -This is a frequent source of concurrency bugs in recursive make build -systems. When combined with nonrecursive make it's all in the same -directory and there is nothing stopping the different invocations -ending up trying to make the same targets at the same time. That -causes hideous racy lossage. There are ways to get this to work -reliably but it is advanced stuff. - -If you make syntax errors, or certain kinds of other errors, in your -makefiles, you may find that just `make' is broken now and cannot get -far enough to regenerate a working set of makefiles. If this happens -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 -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 -will clear up the problem. - Legal information =================