Re: GOP-PROP 5: build system output (final)

[Reinhold Kainhofer]

Am Montag, 8. August 2011, 02:59:31 schrieb Graham Percival:
> - will will ***NOT*** display any errors from g++.  (second point)
>   - exception: we ***MIGHT*** display some portion(s) of the
>     relevant log file(s).  The policy uses the word "might" here,
>     not "must".  There is a huge difference between those two words.
> 
> Please always remember that there is a difference between the
> make(1) program, and other programs which are called by make(1).
> 
> ... if we are still this unclear about precisely what the policy
> states,

No, the policy is clear in that regard. It's just that this is a decision I 
simply CANNOT LIVE WITH!

You know, compiler errors is the single most important information that a 
build system can give, even more important than success/failure message!
To a developer that's the information that is absolutely required from a build 
system.

Also, this policy builds on the assumption that the commands called by make 
are the most important things and all output created by them (e.g. compiler 
warnings, errors, etc.) are not that important.
This gets the priorities completely wrong: The exact command line called by 
make (usually 5-10 lines of output!) might be useful to reproduce, but only 
know what the problem is. The current proposal does NOT tell you that there is 
a problem and what the problem is. So you can't use the exact commands 
directly anyway.
On the other hand, the compiler errors are typically crafted to tell you which 
problem occurred and where, so you can easily fix the problem and run make 
again, without having to know the exact call of the gcc binary.

Below I'll make a list of possible output from a build system, with things 
that are essential to me as a developer down to things that might be an 
annoyance if printed.

Our build system will be about the only build system on earth that does not 
print compiler errors. And that makes it pretty useless as a build system.


Currently, the normal build (i.e. 'make') produces output that is acceptable 
for developing lilypond. On the other hand, I think we all agree that a docs 
build prints out so much that the output is not really usable. Plus, the error 
output for errors in lilypond-book-included snippets is broken in that it does 
not properly tell you which file exactly failed and how it failed.


For a compilation run, the following types of output are possible, sorted in 
my order of importance. Everything above the +++ separator I consider 
absolutely essential and a major annoyance to a developer if not printed by 
default. Everything below the ----- separator is also not useful and if 
printed clutters the output with unuseful information, thus making it an 
annoyance, too.

COMPILATION RUN:
When coding, all compiler errors and warnings are essential, because they need 
to be fixed (warnings usually point to serious coding errors!)

1) Compiler errors
2) Success/Failure of the build
3) Simple progress (which file is processed)
4) Compiler warnings (usually pointing to serious programming errors)
+++++++++++++++++++++++
5) directory traversal of make
6) make failures
7) Exact commands called by make
8) "normal" output (progress) by commands invoked by make
-----------------------
9) All environment variables
10) debug output by commands invoked by make (i.e. output for debugging a
    problem with the invoked commands, like a bug in gcc, not for problems in
    the files processed)

Ideally, the default make prints out 1-6 (at least 1-4). Verbose prints out 
more.


DOCUMENTATION BUILD:
Here things are a bit different, because e.g. some regtests are supposed to 
trigger warnings.

1) Success/Failure of the whole build
2) Error messages
3) Simple progress (which file is processed)
4) make failures
5) Warnings that should be fixed
6) directory traversal of make
+++++++++++++++++++++++
7) minimal progress output by commands invoked by make (e.g. lilypond-book
   printing which snippet it is processing)
8) Exact commands called by make
9) "normal" output (progress) by commands invoked by make (e.g. lilypond-book
   printing the progress for each processed snippet)
10) Warnings that are expected and should be there (e.g. in regtests)
11) All environment variables (e.g. python include pathes!) needed to call the
    commands manually
-----------------------
12) debug output by commands invoked by make (i.e. output for debugging a
    problem with the invoked commands, e.g. a bug in gcc, not for problems in
    the files processed; or all debug output of lilypond when processing
    snippets - this is only needed to find a bug in lilypond, but not useful
    to find a typo in the documentation)

Ideally, the default make prints out 1-7 or 1-9.

Cheers,
Reinhold

-- 
------------------------------------------------------------------
Reinhold Kainhofer, address@hidden, http://reinhold.kainhofer.com/
 * Financial & Actuarial Math., Vienna Univ. of Technology, Austria
 * http://www.fam.tuwien.ac.at/, DVR: 0005886
 * LilyPond, Music typesetting, http://www.lilypond.org