NEWS

Stu versions are of the form X.Y.Z, where X is the major version, Y is
the minor version and Z the patch level.  For each new patch level, no
new syntax features are added.  When the minor version is incremented,
features are added, which are documented in this file.  This file also
documents important changes in patch level updates, which are mostly
changes in terminology, changes in the installation procedure, or
changes in invocation.

When the major version is increased, backward-incompatible changes are
made, which are documented in the file 'doc/MIGRATION', and summarized here.

------------------------------------------------------------------------

2024-09-25  Version 2.7.100

* 'stu --help' and 'stu --version' now do the same as 'stu -h' and 'stu -V'.

2024-09-06  Version 2.7.89

* Switched to C++17 (from C++14).

2024-09-01  Version 2.7.87

* Introduced "make check".  Works like "make test", but omits strict warnings and
  code-cleanliness tests.  This makes "make check" work with non-GCC compilers such as
  clang++.

2024-08-05  Version 2.7.84

* The flag -C was added.  It can be used inside dynamic dependencies (like [-C
  filename]) to denote that "filename" will be parsed in full Stu syntax.  This
  is the default behavior and thus -C and can always be omitted.

2023-06-30  Version 2.7.70

* The option -I outputs all targets that can be rebuilt.  Useful for
  ".gitignore" and similar.
* Traces are now called backtraces.
* Stu can now output traces.  This is only possible in debug mode (NDEBUG not
  set).  See src/trace.hh.

2023-04-02  Version 2.7.16

* We switched from Autotools to a custom Makefile.

2020-10-30  Version 2.7

* Backslashes are now allowed outside of quotes and act as the escape character:
  * In front of newline, the newline is ignored
  * At end of file:  An error
  * Before any other character:  Represents the character as part of a unquoted
    filename.

2020-04-13  Version 2.6.4

* Switched to C++14 (from C++11).

2020-03-18  Version 2.6

* Canonicalization is implemented.  This means that Stu will now
  canonicalize all names of files and transient before further
  processing.  For instance, 'data' and './data' will refer to the same
  file.  This takes into account uses of '/' and '.'.  Symlinks and '..'
  are not resolved by canonicalization.  The exact semantics are described in
  the manpage.

2018-02-28  Version 2.5.59

* We clarified what happens when multiple environment variables that Stu
  sets have identical names:
  (1) Two parameter cannot have the same name; they would be interpreted
  as the same parameter.
  (2) Two variable dependencies may have the same name.  This is
  allowed, and it is unspecified which gets used.
  (3) If a variable dependency and a parameter have the same name, the
  variable overrides the parameter.

2018-02-15  Version 2.5.53

* The parsing of arguments on the command line was made consistent with
  the new features introduced in Version 2.5.  As before, the
  characters @[] are recognized, and now also the '-' character for
  flags.  Empty arguments now result in logical error (exit status 2)
  rather than fatal errors (exit status 4).

2017-08-11  Version 2.5

* Concatenation is supported
* The handling of dynamic dependencies was rewritten to allow
  concatenation.  The semantics of existing functionality was not
  changed, except in certain undocumented corner cases.  These include
  transients whose rules contain a command or file targets.  These acted
  transitively previously, but do not now.  Only transient rules without
  command and without file targets act transitively now.  This applies
  to transients used in dynamic dependencies, transients used to import
  variable dependencies, as well as transients used to carry over flags
  to child targets.
* Arguments to -j cannot be in octal anymore.  In previous versions, the
  -j option accepted numbers in octal when they started with a zero.
  This behavior was accidental, and has been removed.
* When a file read using the -f option or a file included using %include
  does not exist, Stu now returns an exit code of 1 (build error),
  rather than 2 (logical error) as done previously.

2016-09-13  Version 2.4.19

* The rules governing what is written on stdout where reworked:  There
  is now only the -s option (silent).  The options -Q and -w were
  removed.

2016-09-11  Version 2.4.17

* "Verbose mode" is now called "debug mode", and the option was changed
  from -v to -d.

2016-09-03  Version 2.4.7

* The -B option is renamed to -i, because it is mainly an interactive
  mode, even if only very rudimentary.

2016-08-31  Version 2.4.2

* Job control:  Jobs are now always put into the background, except when
  the -B function is used.  The -B function must now be used when Stu
  command should read from their standard input.

2016-08-31  Version 2.4

* Copy rules can now use the -o flag to denote optional copy rules:

A = -o B;

The semantics are:
- When B is not present:
   - Fail when A is not present
   - Succeed when A is present
- When B is present, apply the usual rules

This is particularly useful when working in projects where a certain file
can be updated from a source only for some developers:  The file can be
distributed for the project, and an optional copy rule can be used such
that for developers who have the source file, it will be updated when
necessary, and for developers who don't have the source file, the copy
delivered with the project can always be used.

2016-08-31  Version 2.3.10

* The environment variable $STU_OPTIONS can now be used to pass options
  to Stu.  All non-option charaters are ignored, i.e., you can include
  spaces an preceded all options with a dash, but it doesn't matter.
  This works only for options for which it makes sense to set them
  globally:  "EQswxyYz".  Options passed on the command line take
  precedence over options passed in $STU_OPTIONS.

2016-08-30  Version 2.3.6

* Stu now starts all commands with their standard input redirected from
  /dev/null, except for command whose rule has an input redirection.
  This behavior, along with the usage of a separate process group for
  each job, can be disabled with the '-B' option.  Thus, jobs will now
  systematically get a STDIN of size zero instead of (erratically)
  getting Stu's STDIN.  If jobs should be able to read Stu's STDIN, then
  '-B' has to be used.  For technical reasons, this cannot be used in
  conjunction with process groups, and as a result, it may happen that
  indirect child processes (i.e., grandchild processes) may not be
  terminated correctly by Stu when -B is used.

2016-08-29  Version 2.3

* A flag and an option '-0' is now available for \0-separated dynamic
  dependencies, that work analogously to '-n' for newline-separated
  dependency.  Thus, this is now possible (using the nonportable find
  -print0 as an example):

@all [ -0 FILES ];
>FILES { find ... -print0 }

A corresponding command-line option '-0' also exists now.

2016-08-27  Version 2.2.2

* There is now a command-line option '-n' to pass the name of a file
  that contains newline-separated names of files to be built.  This is
  in analogy with the '-n' flag.  Example:

$ find ... >FILES
$ stu -n FILES

The same can be achieved by

$ stu -C '[ -n FILES]'

but the -n option avoids quoting and escaping problems in case the
filename contains brackets, spaces, etc.

2016-08-26  Version 2.2

* Dynamic dependencies can now be declared to be newline-separated list
  of filenames by using the '-n' flag.  For instance:

A: [ -n B ] { ... }
>B { find ... }

In this example, the file 'B' is generate by a 'find' command that
outputs on filename per line.  Stu will then interpret each file
contained in 'B' as a dependency of 'A'.

2016-08-26  Version 2.1.4

* There is now a new option '-Y' to turn on color output
  unconditionally.

2016-08-25  Version 2.1

See 'doc/MIGRATION'.

* "Timestamp-ignoring dependencies" are now called "persistent dependencies".
* Quoting rules were changed.
* Unquoted names cannot begin with -, + or ~ anymore.
* Whitespace is now mandatory in certain environments.
* The "print database" option is now -P instead of -p.
* The flags !, ? and & have been replaced by -p, -o and -t.
* The options -o and -p now denote optional and persistent dependencies.
* Command line argument are now parsed differently.

2016-07-29  Version 1.15.80:

* "Existence-only" dependencies are renamed to "timestamp-ignoring"
  dependencies.  The syntax is not changed.

2016-05-18  Version 1.15:

* Arguments to Stu outside of options are now parsed in a simplified
  syntax in which only the characters '!?&@[]' retain their special
  meaning.  To pass dependencies in full Stu syntax, the option -C can
  be used, as in previous versions.

2016-05-15  Version 1.14:

* Rules with multiple targets are possible, as in

A B C: X Y { # Build A B C }

This would previously have been written as

A: X Y { # Build A B C }
B: A;
C: A;

with the difference that using the new form, Stu will rebuild 'B' and
'C' when any of these has been removed.

* In the error message for cyclic dependencies, Stu doesn't show anymore
  how each target was instantiated if it was dynamic, in consistence
  with other error messages
* In the error message for cyclic dependencies, Stu now also shows the
  trace from the cycle to the top-level target
* "Phony targets" were renamed to "transient targets"
* The default compilation mode is now -O2 instead of -O3

The old form is still valid.

2016-05-01  Version 1.13:

* Dynamic phonies are now allowed.  The following is an example:

A :  [@x] { cp C A }
@x : B;
B = {C}
C = {correct}

This will create a file 'A' containing the text 'correct'.

2016-04-26  Version 1.12:

* Copy rules:

A = B;

This will copy the file 'B' to 'A'.  This can be used with '!' and '&',
but not with '?':

A = !B;
A = &B;
A = directory/;

If the source ends in a slash, then it is interpreted as a directory and
it is searched for a file with the same name as the basename of the
target.

2016-04-17  Version 1.11:

* Variable dependencies can use explicit names:

A : $[X = B] { ... use $X here ... }

This will use the content of the file 'B' and make it available as the
content of the variable $X within the command for target 'A'.

2016-04-17  Version 1.10:

* Content can be assigned to files using the following syntax:

A = { CONTENT ... }

This works only with file targets without dependencies, and without
output redirection.

2016-03-26  Version 1.9:

* The algorithm for trivial dependencies (marked with '&') has been
  rewritten, fixing bugs in the previous version, in particular in
  relation to trivial dependencies included indirectly via phonies and
  dynamic dependencies.
* Flags of variable dependencies can now also be specified outside the
  brackets.  For instance, '!$[X]' is now fully equivalent to '$[!X]'.
  Previously, '!$[X]' was an error.  This is true for all three flags,
  '!', '?', and '&'.

2016-01-24  Version 1.8:

* Variable dependencies can now be enclosed in parentheses, as in
  '($[A])'.  This was not allowed before.

2015-11-22  Version 1.7:

* A new flag '&', marks trivial dependencies.  '&' is used as a prefix,
  like '!' and '?'.  Trivial dependencies will never cause a target to
  be rebuilt, but if the target is rebuilt anyway, then they act like
  normal dependencies. They are intended for configuration files
  containing e.g. flags and paths.

2015-10-22  Version 1.6:

* Both the -f option and the %include directive now allow directories as
  parameters, and will read the file 'main.stu' within them.

2015-10-19  Version 1.5:

* The syntax now allows parentheses (only for grouping, no other
  semantics).  The can contain any number of other dependencies.
  Example:

      (A [B] [(C)])

  is equivalent to

      A [B] [C]

* Brackets can contain multiple expressions, e.g. [A B C].  This is
  equivalent to [A] [B] [C].
* The attributes '?' and '!' can be used as prefix operators at any
  level inside and outside brackets, with differing semantics.  For
  instance, the three following line have different meaning:
    [?A]   # The dependency 'A' is optional
    ?[A]   # The dependencies read from 'A' are optional
    ?[?A]  # Combination of the two
* Much code related to dynamic dependencies was rewritten, in particular
  related to options '?' and '!' as well as multiply dynamic
  dependencies.  As a result, many bugs related to these features were
  fixed.

2015-06-10  Version 1.4

* Parentheses are supported and may contain multiple filenames.
  Brackets may contain multiple filenames.  Existence-only dependencies
  are transitive through phonies and parentheses.

2015-06-05  Version 1.3

* Optional dependencies are supported, and use the prefix '?'.  Their
  semantics is:  If the dependency does not exist, it is never created.
  If it already exists, it is processed normally (i.e., regenerated when
  it has to.)

2015-09-29  Version 1.2

* Input redirection is possible using the '<' operator, which must be
  put in front of a file dependency which is then used as standard input
  for the command.  This cannot be used for phony dependencies, for
  variable dependencies or for dynamic dependencies (neither before them
  or within them).  When combined with '!', the redirection operator
  comes second, i.e., '!<A'.  This can be combined with the output
  operator '>' to write commands that consist only of a single call to a
  filter such as sed, tr or awk.

2015-05-29  Version 1.1

* Output commands directly into the target file using the '>'
  operator, to be used in front of the target filename.  Only for file
  rules, not for phonies.