14.6.4.9 GOP-PROP 9 - behavior of make doc
If there are build problems, then it should be easier to find out why it’s failing. This will be achieved with log files, as well as possibly including scripts which automatically display portions of those log files for a failing build.
We will also add targets for building a specific manual (for quick+easy checking of doc work), as well as for building all documentation in a specific language (either English or a translated language).
When you run make doc,
-
All output will be saved to various log files, with the exception
of output directly from
make(1).Note that
make(1)refers to a specific executable file on unix computers, and is not a general term for the build system. -
By default, no other output will be displayed on the console, with
one exception: if a build fails, we might display some portion(s)
of log file(s) which give useful clues about the reason for the
failure.
The user may optionally request additional output to be printed; this is controlled with the
VERBOSE=xflag. In such cases, all output will still be written to log files; the console output is strictly additional to the log files. -
Logfiles from calling lilypond (as part of lilypond-book) will go in
the relevant
‘$LILYPOND_BUILD_DIR/out/lybook-db/12/lily-123456.log’ file. All
other logfiles will go in the ‘$LILYPOND_BUILD_DIR/logfiles/’
directory.
A single
make docwill therefore result in hundreds of log files. Log files produced from individual lilypond runs are not under our control; apart from that, I anticipate having one or two dozen log files. As long as it is clear which log file is associated with which operation(s), I think this is entirely appropriate. The precise implementation will be discussed for specific patches as they appear. -
Both stderr and stdout will be saved in
*.log. The order of lines from these streams should be preserved. -
There will be no additional “progress messages” during the
build process. If you run
make --silent, a non-failing build should print absolutely nothing to the screen. - Assuming that the loglevels patch is accepted, lilypond (inside lilypond-book) will be run with –loglevel=WARN. http://codereview.appspot.com/4822055/
- Ideally, a failing build should provide hints about the reason why it failed, or at least hints about which log file(s) to examine.
If this proposal is accepted, none of these policies will be assumed to apply to any other aspect of the build system. Policies for any other aspect of the build system will be discussed in separate proposals.
Don’t cause more build problems
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.
This will be done by starting from individual lilypond calls within lilypond-book, and slowly moving to “larger” targets of the build system – after the individual lilypond calls are are producing the appropriate amount of output and this is saved in the right place and we can automatically isolate parts of a failing build, we will work on lilypond-book in general, and only then will we look at the build system itself.
Implementation notes
There is an existing make variable QUIET_BUILD, which alter the amount of output being displayed (http://lilypond.org/doc/v2.15/Documentation/contributor/useful-make-variables ). We are not planning on keeping this make variable.
The standard way for GNU packages to give more output is with a
V=x option. Presumably this is done by increasing
x? If we support this option, we should still write log
files; we would simply print more of the info in those log files
to screen.
The command tee may be useful to write to a file and
display to stdout (in the case of VERBOSE).
Discussions
https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00378.html https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00703.html |