GOP-PROP 5: build system output

[Graham Percival]

http://lilypond.org/~graham/gop/gop_5.html

(proposal written by Phil Holmes.  I have a few qualms, which I
will send when I have a bit more time)


** Proposal summary

Let’s decide what we want to see when we do:
        
  make
  make doc


** Rationale

Before any of the current work on reducing output from make, the
result of a "make doc" was over 500,000 lines of text. Finding
errors or warnings in that volume of output is always going to be
hard. The prime reason for the output being so verbose is that all
the processes that run as a result of the call to make echo their
output to the screen, often in verbose mode. Lilypond itself
produces around 370,000 lines of output as a result of
lilypond-book building all the snippets.

Much of this output can be redirected to logfiles and so the
impossible-to-read clutter on the screen is cut out and could be
referred to later. However, there is a danger in this approach,
that vital error messages can also be lost, thus preventing the
cause of the failure of a make being found. We therefore need to
be exceptionally careful to move cautiously, include plenty of
tests, and give time for people to experiment/find problems in
each stage before proceeding to the next stage.

A variable, QUIET_BUILD, can be set and this will reduce the
clutter but not eliminate it. (see
http://lilypond.org/doc/v2.15/Documentation/contributor/useful-make-variables
) This variable currently does things like adding a -q flag to the
TEXI2PDF call ("quiet") and getting rid of the –verbose flag in
some calls to LilyPond. However, it could be used more widely, as
proposed below.


** Proposal

    * We do not change the output of make, make doc, or any of the
      other make commands - this is the default.
    * We use the variable QUIET_BUILD to signal to the make system
      that we want the minimum of progress output visible on the
      terminal, with all other output going to logfiles
    * Wherever possible, the logfiles should be put in the
      ‘build/logfiles’ directory - which will have to be created
      as part of configure
    * Wherever possible, stderr output should go to *.err.log and
      stdout output to *.log
    * Running (for example) make -s QUIET_BUILD=1 doc should give
      the occasional progress message to indicate where it has
      reached in the build process, but a such a rate that it’s
      easy to read and a volume that allows the user to see the
      top of the output in terminal
    * Ideally, running (for example) make -s QUIET_BUILD=1 on a
      build that fails should make it easy to see the file causing
      the build to fail. 


** Implementation notes

none yet 


Cheers,
- Graham