README: Fix documentation errors relating to &{ etc.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

syntax: Support &: literal (for make `grouped' multiple targets)

Very recent versions of GNU make support this syntax:

  foo bar biz &: baz boz
        echo $^ > foo
        echo $^ > bar
        echo $^ > biz

(See (make)Multiple Targets, subheading `Rules with Grouped Targets')

This use of & is nonoverlapping with everything we care about, so we
can just pass it straight through.  Passing through &: means we pass
through &:: too.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Add subheading `Directives'

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Syntax: Incompatible change: &$( does not do daft { thing

It is silly for &$( to expand to ${.  That requires the input to
contain non-matched kinds of brackets.

The shell compatibility is not needed.  In a shell rune, you can write
&\$thing since the { } are not normally needed there at all.  If they
are then now &\${thing} is necessary.  It would be possible to steal
"&${" (or allow only "&$(") but that seems less good.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Syntax: Provide convenience syntax &( for $(eval

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/filter/extract-doctests: Use $withspcs more

This does away with a special case and will allow general use of
spaces in before and after expansions.

No change with current input.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/filter/extract-doctests: Improve an error message

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/filter/extract-doctests: Recognise directives first

We are going to expand the rules for => expansions and they would
match directives too, but we don't want them to.

No functional change with existing input.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Syntax: Incompatible change: Use &{ not &${ for macros

This will be more orthogonal with $( which will come in a moment.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Adjust indent of &${..$..} expansion

No change to the meaning.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests: Provide make-release script

Not really `tests' but I don't want to add a whole new directory just
for this.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests: Provide advance-tested script

Useful for our own testing.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Legal: Update tests/filter/ inputs and outputs

We judiciously use # vs. &# for the legal comment so that each
expected output file contains one notice.

The following files, which are wholly constructed by running
generate and reviewing the diffs, do not have a legal notice:
  tests/filter/main.mk.expected
  tests/filter/stderr.expected
  tests/filter/sub/Dir.mk.expected
This is OK I think.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Legal: Add copyright, licence and warranty notice to many files

The .sd.mk and .expected files in tests/filter/ are more complicated.
We'll do those in a moment.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Legal: Add NO WARRANTY everywhere

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Avoid $err_file undefined warning during startup

If, for example, one of the input files implied by the command line
arguments is missing, err is called with $err_file not yet set.

Handle this case.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Mention suppressions when warning re VAR vs &VAR

When we are actually printing the warning, report all the locations,
including the suppressed ones.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Syntax: Support &:local+global !...

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/filter: Test &:local+global & vs non-&

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Syntax: Rescope effect of &:local+global

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

subdirmk: Fix a Subdir left over in README

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Syntax: Expand &$( and &$NN to use ${ } rather than $( )

And now document the use of $&+ for recipes.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

doctests: Allow parenthetical comments as an expansion RHS

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Swap order of &$( and &$NN

We are going to add a note to &$( which applies to &$NN too, and this
makes it nicer.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Syntax: Use ${top_srcdir} rather than $(top_srcdir)

Again, this makes it possible to use in $-doubled shell runes as well
as in make syntax.  (Assuming you have made top_srcdir be a shell
variable as well as a make variable.)

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Syntax: expand &$... to ${....} rather than $(....)

This makes it possible to use in $-doubled shell runes as well as in
make syntax.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warnings: Introduce new `broken-var-ref' warning

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/filter: Print all the diffs, not just the first

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Refer to example/

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Move the "how to use" up

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Add another layer of structure

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Move the Warnings section up into what is going to be spec

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: deinent the macro explaation

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Further miscellaneous fixes and clarifications

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Document that local+global is not 100% accurate

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: More syntax further up

This is primary.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warning reporting: Report each warning only once

In particular, Prefix and Suffix, or conventional &:include's can
generate a lot of repeated warnings.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warning reporting: Provide &:local+global directive

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warning reporting: Add a test of the warning suppression system

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warning reporting: Warning suppression system

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

test/filter; Cause some warnings, to check they appear

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warnings: Sort occurrences properly in local+global warnings

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warnings: Warn for confusing single-char $ expansions

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warnings: Track variable references in &-expansions

For &-escapes which match the whole variable name, we can conveniently
track variable expansions as part of the processing.  (We don't change
any of the matching regexps.)

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warnings: Track basic $-references

We must always stop at $'s in the input now.

Having stopped at $, we normally just output it and carry on.  Ie, we
only stop so we can do some inspection: as before, we do this variable
tracking as inspection before processing, rather entangled with
processing.

We can deal reasonably properly with ${ } and $( ).

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warnings: Track settings of variables

Where the variable tracking does not involve &-escapes, or only
involves &-escapes which work like a prefix so the processor does not
have the whole variable name, we do this separately from processing.

This is simpler because we can look ahead more.  It also avoids
disturbing the processing logic (which needs to be precisely accurate,
unlike this variable tracking).

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warnings: Infrastructure for tracking and warning about variables

We are going to track when we see FOO or &FOO.  If we see both, we
issue a warning, as that might mean the programmer forgot a &.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Warnings: generate: Basic `wrn' function

This is sufficient to add warnning calls to the code.  We'll soup it
up later.  No callers yet.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/filter/check: Capture generate's stderr

We are going to cause `generate' to emit warnings, which we want to
check are working.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

test/filter: Test &${ ... } rather better

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Fix &${ } end condition

It is quite wrong to use $ddbl, which might be adjusted by &$- &$+.
We must maintain a separate counter.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Fix { } in &${ to actually output the { }

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/filter: Rename `doctest' -> `doctests' everywhere

This is more uniform.  A lot of churn, though.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Move &:changequote further down

This is a bit of a minority interest.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Explain a wrinkle in &:include filename semantics

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: use oraw in a few more places

This gets rid of some open-coded `print O'.

No functional change.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Miscellaneous fixes and clarifications

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Document restriction on $-doubling and lack of -quadrupling

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: Move `Tables of file reference syntaxes' down

This is more of an appendix or addendum.  It should come after the
complete description of the substitution syntax.

Pure motion.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Big incompatible change: Rename `Subdir' to `Dir'

We want completion to be easy, and we have Suffix now.  `Dir' is as
good as `Subdir' I think (and a bit shorter).

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Error handling: Fix messages resulting from bad directive arguments

"Unknown directive" is not necessarily accurate; another possibility
is that the directive is known but didn't match the parsing regexp
because of problems with the arguments.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Nested scope: Change `Eval' to `eval'

This is the nesting kind name.  But it also appears in error messages
where it ought not to be capitalised.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Nested scope: Change `Macro' to `macro'

This is the nesting kind name.  But it also appears in error messages
where it ought not to be capitalised.

We'll change `Eval' in a moment.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Error handling: Trim the `bad escape' message.e

Do not print the whole line, only the next 5 chars (say) - and, also,
not any newlines.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Error handling: Better reporting of nest-related errors

Track `$what' which is a kind of example for the error message.
Use it in error messages.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Error handling: Often say `subdirmk' rather than `$0'

The latter is generally a path (`.../generate') and may be confusing.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Error handling: Replace or update many calls to `die'

To conform to new approach.

The `ending wrong kind of nest' error will be dealt with in a moment.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Error handling: Provide err and ddbl_only, and an internal spec

No callers of these yet.  The spec is honoured in the breach.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Make @nest always be nonempty

No outward functional change, but makes the error handling
etc. slightly simpler.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Do not tolerate unclosed nested scopes at EOF

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Macro assistance part 2 - syntax for $(eval $(call...))

This can be used to call a macro defined with &:macro.  In combination
these provide a more reasonable macro facility than make's.

Specifically:

* Document the new facility.
* Motivate it in the README.
* Provide the new @nest kind for &${  }, which uses $ddbl as
  a counter to count { and }.
* Implement the {}-counting and nesting end in the main parsing
  loop.  (We must now search for things besides $esc.)
* In extract-doctest, provide a slightly adhoc special case for
  understanding ${eval ...} as an expansion text in the README.
  And do not attempt to test &${ } when already $-doubling.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Macro assistance part 1 - macro directive

Define the &:macro directive, which is a dollar-doubled version of
make's own `define'.

We must introuce a new concept of `nesting', for when "the content of
the construct is $-doubled" in the words of the README.  The
implementation is in the main process_input_mk function: it is a
multi-line scope of some kind with an ad-hoc ending condition, and its
own dollar-doubling setting.

We will also want a convenient syntax for $(eval $(call...)), which
we're going to introduce in a moment.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

doctests: Rename `desc' etc. in extract-doctest from `rubric'

This isn't a rubric, it is a description of a particular test entry.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

doctests: Improve entry description filter

This makes the decriptive text more aposite in some situations.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Dollar doubling feature

This makes it easier to write certain rules commands, and macros
involving eval.  Further enhancements will follow, but for now:

* Document the new facility, including the &-escapes to turn it on and
  off, its effect, and the three within-doubling don't-double escapes.

* Implementation.  Specifically:
   - Rename od to oud (`undoubled').
   - Provide od which does double things if $ddbl (a global) is set.
   - Implement the escapes, and add some error checks.
   - Change `od' to `oud' in `&\$', so that that always produces an
     undoubled $.

* Enhance extract-doctest:
   - Set $e->{DD} to say if it's in `while dollar doubling'.
   - Filter out such entries from the `normal' test - they are not
     legal outside dollar-doubling.
   - Add a dollar-doubling test which includes versions of all
     the normal tests as well as the dollar-doubling ones, and
     which dollar-doubles the outputs when appropriate.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/filter/.gitignore: Ignore all .tmp

Rather than trying to list them all.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Introduce oraw

Replace all other calls to `o' with `oraw'.  This ensures we
have no stray calls.

It elminates an anomaly, namely that calls outside process_input_mk
would rely on the $buffering_output variable which is set only there.

No functional change.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Introduce od

Replace every call to `o' in process_input_mk (the main filtering
routine) with a call to `od', which is going to be the dollar-doubled
output variant when we add the dollar doubling feature.

For now it just does the same as `o'.

No functional change.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

example: Introduce a Final.sd.mk and test it

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/filter: Test Final.sd.mk

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Interface: Read Final.sd.mk

Tests will come in a moment, although we already see the new output
file mentioned in main.mk.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

README: fix TARGETS text for new tidier semantics

In
  Syntax: Refine &TARGETS_things, mostly to avoid # wrinkle
we updated the spec for &TARGETS_things in the list of expansions,
but not in the discussion of per-directory recursive targets.

Fix that.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

Interface: Rename Perdir to Suffix; provide Prefix

We want to be able to specify something that appears at the top of
every per-directory segment, principally to provide
for-every-directory variable settings.

A more sophisticated scheme akin to m4 diversions would be possible in
principle, but it would make organising the output files (which must
be processed by autoconf) really awkward - let alone the depenency
management for regenerating the makefiles.

So instead, simply provide a Prefix too.  Additionally, soon we are
going to introduce a Final.sd.mk which is processed right at the end.

I think this new scheme will be sufficient in principle to do anything
that might be needed.  Sadly it will continue to require that
&:include's are done in the right order.

"Suffix" and "Subdir" tab-complete really badly.  In a forthcoming
commit we will rename Subdir.sd.mk to Dir.sd.mk.

Incompatible change.  We must update the tests right away.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Make many dir vars globals

This makes the code a bit more fragile but a lot less repetitious.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Fix an erroneous comment

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

generate: Drop comment about input files

This is all documented in README now.
And it's about to become out of date.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/check: Dynamic parallism choice

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/check: Show parallel make rune we run

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests: Run in parallel

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/example: Reset times of (copied) source files too

This eliminates a problem with our test case: if the build takes less
than 1s the files were probably copied more recently than the 1s ago,
resulting in too much rebuilding (and possibly missing
failed-to-rebuild bugs).

We can now change the timestamp for the build tree to something
earlier.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/example: Build in a copy

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/build-common: Copy subdirmk, rather than symlinking

This is more like it will be in someone's project.  Also it prevents
us from accidentally touching anything in the source tree.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/intree: Make copy and break out from tests/example

We introduce make_copy, which makes a copy of tests/example
suitable for testing.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

build tests: Break out build-common

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

regen.mk.in: Clarify documentation about realclean

It's not sensible to `make [the provided] realclean:: into a recursive
target' in that sense since the one we provide is effective, and
present, only in the toplevel.  What we mean is that you can make your
own realclean target and regen.mk's will fit in nicely.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

regen.mk.in: Document CONFIG_STATUS_OUTPUTS

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

test/example/check: Reset times for regen tests

In principle, on a filesystem with poor time resolution, the updates
to the input files might have the same timestamp as the output files.
Things would then not be regenerated.

Work around this by resetting all timestamps in the build tree to
1s ago.  This should ensure that exactly the one file whose edit we
are simulating seems, to make, to have been changed.

There is a remaining possible problem: if our last actual change to
the subdirmk source tree is less than 1s ago, this might rebuild too
much.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

test/example/check: Make sections appear in stderr output

This makes the output easier to navigate.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/example/check: Better handling of makefile updates

Rather than checking just for presence of a string in a templated
output file, also have the input file define a target which we try to
run.  This checks that make actually reread the file.

Also add ||false to the grep lines, which makes the stderr output
more obviously contain a failure when the test fails.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

tests/example: Include non-.sd.mk files in SUBDIRMK_MAKEFILES

subdirmk.ac provides @_SUBDIRMK_MAKEFILES@ which is a list of the
*.mk makefiles (corresponding to *.mk.in makefiles) passed to
SUBDIRMK_MAKEFILES.  These need to be included in the
identically-named make variable for regen.mk to rerun config.status
when the .in files are edited.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>