+&: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
+------------------------------------
+
+&$+ Starts dollar-doubling
+&$- Stops dollar-doubling
+ Both are idempotent and local to the file or context.
+
+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.
+
+&:macro NAME => define NAME
+STUFF $ THINGS .. STUFF $$ THINGS
+&:endm .. endef
+ NAME is processed for &
+
+&${..$..} => ${eval ${call ..$$..}}
+ (matches { } pairs to find the end)
+ 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 &${...}.
+
+While dollar-doubling:
+- - - - - - - - - - -
+
+$ => $$ including $'s produced by other
+ &-expansions not mentioned here
+
+&\$ => $
+&$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
+get $-quadrupling.)
+
+
+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.)
+
~ian / subdirmk.git / blobdiff