From 0ef9b234c5f94e7d99dc10e04a24898486e272c8 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 8 Dec 2019 18:30:10 +0000 Subject: [PATCH] README: v2: Draft - Use / for variable names too. Use &. for just the name Not implemented yet. Signed-off-by: Ian Jackson --- README | 52 +++++++++++++++++++++++++--------------------------- 1 file changed, 25 insertions(+), 27 deletions(-) diff --git a/README b/README index 6dd1a05..91b62d4 100644 --- a/README +++ b/README @@ -197,9 +197,8 @@ abs_src.) Substitution syntax ------------------- -In general & expands to the subdirectory name when used for a -filename, and to the subdirectory name with / replaced with _ for -variable names. +In general & expands to the subdirectory name. (`/' is legal in make +variable names.) Note that & is processed *even in makefile comments*. The substitutor does not understand make syntax, or shell syntax, at all. However, @@ -209,36 +208,37 @@ are common in makefiles. In the notation below, we suppose that the substitution is being in done in a subdirectory sub/dir of the source tree. In the RH column 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. (Even in variable names: top level's start `./'.) -&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: - -&_ => sub_dir_ or TOP_ -&=_ => sub_dir or TOP +&alpha => sub/dir/alpha or ./alpha + Here alpha is any ASCII letter A-Za-z. + The assumption is that filenames and variables usually + start with a letter. Otherwise, use another syntax: &/ => sub/dir/ or nothing -&=/ => sub/dir or . +&. => sub/dir or . + (This implies that `&./' works much like `&/'. &./ is + suitable for variable name construction in a way &/ is not.) -&^lc => $(top_srcdir)/sub/dir/lc +&^alpha => $(top_srcdir)/sub/dir/alpha &^/ => $(top_srcdir)/sub/dir/ +&^. => $(top_srcdir)/sub/dir -&~lc => $(top_srcdir)/lc +&~alpha => $(top_srcdir)/alpha &~/ => $(top_srcdir)/ +&~. => $(top_srcdir) In general: - = return subdir without delimiter (not allowed with `^' `~') ^ pathname of this subdirectory in source tree ~ pathname of top level of source tree - / terminates the escape (needed if next is not lwsp or space) + / terminates the escape (needed if next is not lwsp, alpha or `.') + . terminates the escape, gives subdir without / lwsp starts multi-word processing (see below) -So pathname syntax is a subset of: - '&' [ '^' | '~' ] [ lc | '/' ] +&_ => ERROR (for compat with v1) + +So pathname and variable syntax is a subset of: + '&' [ '^' | '~' ] [ alpha... | '/' | '.' ] && => && for convenience in shell runes &@ => & general escaping mechanism @@ -247,11 +247,12 @@ So pathname syntax is a subset of: &$VARIABLE $(sub/dir/VARIABLE) VARIABLE is ASCII starting with a letter and matching \w+ -& thing thing... & +& thing thing... & +&/ thing thing... & &^ thing thing... & &~ thing thing... & Convenience syntax for prefixing multiple filenames. - Introduced by & followed by lwsp where lc could go. + Introduced by &... followed by lwsp where alpha could go. Each lwsp-separated non-ws word is prefixed by &/ etc. etc. respectively. No other & escapes are recognised. This processing continues until & preceded by lwsp, @@ -314,7 +315,7 @@ So pathname syntax is a subset of: 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, is not magic. To make the target exist without providing any prerequisites for it, write a line containing just `&TARGETS_things +='. @@ -356,13 +357,10 @@ 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 +`.', 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. - Incorporating this into your project ------------------------------------ -- 2.30.2