Proposed Changes to the Usage 5.5 Make and Makefiles

[Fr. Samuel Springuel]

I’d like to propose some changes to the Usage Manual, specifically Section 5.5 
Make and Makefiles.

1) In the first part where the top of the ly files is described, the example 
code (for symphony-cello.ly) should have quotation marks around the names of 
the files in the `\include` statements.  As best I can understand, these 
quotation marks are required by the syntax of the `\include` statement 
(http://lilypond.org/doc/v2.20/Documentation/notation/including-lilypond-files).
  Thus:

%%% top of file "symphony-cello.ly"
\include ../symphonyDefs.ily
\include ../Notes/cello.ily

Should become:

%%% top of file "symphony-cello.ly"
\include "../symphonyDefs.ily"
\include "../Notes/cello.ily"

2) The model Makefile for *nix OSes has several things about it which I think 
make it less than ideal as an example.  In particular:
        a) the definition of CPU_CORES is not portable to macOS as 
/proc/cpuinfo is not present in macOS.  Further, make never passes more than 
one target to LilyPond at a time and so there is no benefit to using the 
-djob-count flag (as best I can tell).  I therefore think that this variable 
and flag should be removed.
        b) The recipe for creating (and moving) the pdf and midi files is 
overly complicated by the tests to see if the files exist.  Further, these 
tests are only needed because it has been written as a 1-logical-line script 
which means that the shell has control over the continuation of the recipe 
rather than make.  If the recipe is written as 3 logical lines, then make will 
automatically halt the recipe if the creation of the pdf and midi files by 
LilyPond fails.
        c) The archive target refers to a directory outside of the example 
hierarchy.  I propose eliminating it.
        d) The Makefile doesn’t check to see if the PDF and MIDI directories 
exist when executing the recipe to create pdf and midi files.  These should be 
added as order-only prerequisites and rules to create these directories should 
they be missing added.
        e) The comment describing the target names for the parts is 
contradictory.  It first says that `make foo.pdf` is the appropriate target for 
instrument foo (which would be `make cello.pdf` for the cello), and then gives 
the example of `make symphony-cello.pdf`.  It is the latter which is correct, 
not the former and so the general description should be fixed.
        f) No .DEFAULT_GOAL is specified, so make falls back on picking the 
first target.  I propose making the .DEFAULT_GOAL explicitly score so that 
those less familiar with make aren’t surprised by a new default goal as they 
modify the file to their own use case.
        g) symphonyDefs.ily is not mentioned as a prerequisite to any of the 
targets.

Attached is my proposed revision to the sample Makefile which deals with all of 
the above issues.

3) Some of the above changes would also apply to the sample Makefile for 
Windows, but I don’t have a system to test them on to figure out exactly which 
ones.

✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝
Fr. Samuel, OSB
(R. Padraic Springuel)
St. Anselm’s Abbey
4501 South Dakota Ave, NE
Washington, DC, 20017
202-269-2300
(c) 202-853-7036

PAX ☧ ΧΡΙΣΤΟΣ

Makefile
Description: Binary data