1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
12 @node Working on LilyPond projects
13 @chapter Working on LilyPond projects
15 This section explains how to solve or avoid certain common
16 problems. If you have programming experience, many of these
17 tips may seem obvious, but it is still advisable to read
22 * Suggestions for writing LilyPond input files::
23 * When things don't work::
24 * Make and Makefiles::
28 @node Suggestions for writing LilyPond input files
29 @section Suggestions for writing LilyPond input files
31 Now you're ready to begin writing larger LilyPond input files --
32 not just the little examples in the tutorial, but whole pieces.
33 But how should you go about doing it?
35 As long as LilyPond can understand your input files and produce
36 the output that you want, it doesn't matter what your input files
37 look like. However, there are a few other things to consider when
38 writing LilyPond input files.
41 @item What if you make a mistake? The structure of a LilyPond
42 file can make certain errors easier (or harder) to find.
44 @item What if you want to share your input files with somebody
45 else? In fact, what if you want to alter your own input files in
46 a few years? Some LilyPond input files are understandable at
47 first glance; others may leave you scratching your head
50 @item What if you want to upgrade your LilyPond file for use
51 with a later version of LilyPond? The input syntax changes
52 occasionally as LilyPond improves. Most changes can be
53 done automatically with @code{convert-ly}, but some changes
54 might require manual assistance. LilyPond input files can be
55 structured in order to be easier (or harder) to update.
60 * General suggestions::
61 * Typesetting existing music::
63 * Saving typing with variables and functions::
68 @node General suggestions
69 @subsection General suggestions
71 Here are a few suggestions that can help you to avoid or fix
75 @item @strong{Include @code{\version} numbers in every file}. Note that all
76 templates contain @code{\version} information. We
77 highly recommend that you always include the @code{\version}, no matter
78 how small your file is. Speaking from personal experience, it's
79 quite frustrating to try to remember which version of LilyPond you were
80 using a few years ago. @command{convert-ly} requires you to declare
81 which version of LilyPond you used.
83 @item @strong{Include checks}: @ruser{Bar and bar number checks},
84 @ruser{Octave checks}. If you include checks every so often, then
85 if you make a mistake, you can pinpoint it quicker. How often is
86 @q{every so often}? It depends on the complexity of the music.
87 For very simple music, perhaps just once or twice. For very
88 complex music, perhaps every bar.
90 @item @strong{One bar per line of text}. If there is anything complicated,
92 itself or in the output you desire, it's often good to write only one bar
93 per line. Saving screen space by cramming eight bars per line just isn't
94 worth it if you have to @q{debug} your input files.
96 @item @strong{Comment your input files}. Use either bar numbers
98 references to musical themes (@q{second theme in violins,} @q{fourth
99 variation,} etc.). You may not need comments when you're writing the piece
100 for the first time, but if you want to go back to change something two or
101 three years later, or if you pass the source over to a friend, it will
103 challenging to determine your intentions or how your file is structured if
104 you didn't comment the file.
106 @item @strong{Indent your braces}. A lot of problems are caused by an
108 in the number of @code{@{} and @code{@}}.
110 @item @strong{Explicitly add durations} at the beginnings of sections
111 and variables. If you specify @code{c4 d e} at the beginning of a
112 phrase (instead of just @code{c d e}) you can save yourself some
113 problems if you rearrange your music later.
115 @item @strong{Separate tweaks} from music definitions. See
116 @ref{Saving typing with variables and functions}, and
122 @node Typesetting existing music
123 @subsection Typesetting existing music
125 If you are entering music from an existing score (i.e., typesetting a
126 piece of existing sheet music),
130 @item Enter the manuscript (the physical copy of the music) into
131 LilyPond one system at a time (but still only one bar per line of text),
132 and check each system when you finish it. You may use the
133 @code{showLastLength} or @code{showFirstLength} properties to speed up
134 processing -- see @ruser{Skipping corrected music}.
136 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
137 in the input file whenever the manuscript has a line break. This
138 makes it much easier to compare the LilyPond music to the original
139 music. When you are finished proofreading your score, you may
140 define @code{mBreak = @{ @}} to remove all those line breaks. This
141 will allow LilyPond to place line breaks wherever it feels are
144 @item When entering a part for a transposing instrument into a
145 variable, it is recommended that the notes are wrapped in
148 \transpose c natural-pitch @{...@}
150 (where @code{natural-pitch} is the open pitch of the instrument) so
151 that the music in the variable is effectively in C. You can transpose
152 it back again when the variable is used, if required, but you might
153 not want to (e.g., when printing a score in concert pitch,
154 converting a trombone part from treble to bass clef, etc.)
155 Mistakes in transpositions are less likely if all the music in
156 variables is at a consistent pitch.
158 Also, only ever transpose to/from C. That means that the only other
159 keys you will use are the natural pitches of the instruments - bes
160 for a B-flat trumpet, aes for an A-flat clarinet, etc.
166 @subsection Large projects
168 When working on a large project, having a clear structure to your
169 lilypond input files becomes vital.
173 @item @strong{Use a variable for each voice}, with a minimum of
174 structure inside the definition. The structure of the
175 @code{\score} section is the most likely thing to change;
176 the @code{violin} definition is extremely unlikely to change
177 in a new version of LilyPond.
180 violin = \relative c'' @{
193 @item @strong{Separate tweaks from music definitions}. This
194 point was made previously, but for large
195 projects it is absolutely vital. We might need to change
196 the definition of @code{fthenp}, but then we only need
197 to do this once, and we can still avoid touching anything
198 inside @code{violin}.
202 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
203 violin = \relative c'' @{
211 @node Saving typing with variables and functions
212 @subsection Saving typing with variables and functions
217 By this point, you've seen this kind of thing:
219 @lilypond[quote,verbatim,ragged-right]
220 hornNotes = \relative c'' { c4 b dis c }
228 You may even realize that this could be useful in minimalist music:
230 @lilypond[quote,verbatim,ragged-right]
231 fragmentA = \relative c'' { a4 a8. b16 }
232 fragmentB = \relative c'' { a8. gis16 ees4 }
233 violin = \new Staff { \fragmentA \fragmentA \fragmentB \fragmentA }
241 However, you can also use these variables (also known as
242 variables, macros, or (user-defined) command) for tweaks:
244 @lilypond[quote,verbatim,ragged-right]
245 dolce = \markup{ \italic \bold dolce }
246 padText = { \once \override TextScript #'padding = #5.0 }
247 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
248 violin = \relative c'' {
250 c4._\dolce b8 a8 g a b |
252 c4.^"hi there!" d8 e' f g d |
253 c,4.\fthenp b8 c4 c-. |
260 \layout{ragged-right=##t}
264 These variables are obviously useful for saving
265 typing. But they're worth considering even if you
266 only use them once -- they reduce complexity. Let's
267 look at the previous example without any
268 variables. It's a lot harder to read, especially
272 violin = \relative c'' @{
274 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
275 \once \override TextScript #'padding = #5.0
276 c4.^"hi there!" d8 e' f g d |
277 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
278 \hspace #0.1 \dynamic p @} b8 c4 c-. |
283 @c TODO Replace the following with a better example -td
284 @c Skylining handles this correctly without padText
286 So far we've seen static substitution -- when LilyPond
287 sees @code{\padText}, it replaces it with the stuff that
288 we've defined it to be (ie the stuff to the right of
291 LilyPond can handle non-static substitution, too (you
292 can think of these as functions).
294 @lilypond[quote,verbatim,ragged-right]
296 #(define-music-function (parser location padding) (number?)
298 \once \override TextScript #'padding = #$padding
306 c4^"piu mosso" fis a g
310 Using variables is also a good way to reduce work if the
311 LilyPond input syntax changes (see @ref{Updating old input files}). If
312 you have a single definition (such as @code{\dolce}) for all your
313 input files (see @ref{Style sheets}), then if the syntax changes, you
314 only need to update your single @code{\dolce} definition,
315 instead of making changes throughout every @code{.ly} file.
319 @subsection Style sheets
321 The output that LilyPond produces can be heavily modified; see
322 @ref{Tweaking output}, for details. But what if you have many
323 input files that you want to apply your tweaks to? Or what if you
324 simply want to separate your tweaks from the actual music? This
327 Let's look at an example. Don't worry if you don't understand
328 the parts with all the @code{#()}. This is explained in
329 @ref{Advanced tweaks with Scheme}.
331 @lilypond[quote,verbatim,ragged-right]
332 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
333 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
335 inst = #(define-music-function (parser location string) (string?)
339 'text (markup #:bold (#:box string))))
343 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
345 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
349 There are some problems with overlapping output; we'll fix those using
350 the techniques in @ref{Moving objects}. But let's also
351 do something about the @code{mpdolce} and @code{inst}
352 definitions. They produce the output we desire, but we might want
353 to use them in another piece. We could simply copy-and-paste them
354 at the top of every file, but that's an annoyance. It also leaves
355 those definitions in our input files, and I personally find all
356 the @code{#()} somewhat ugly. Let's hide them in another file:
359 %%% save this to a file called "definitions.ily"
360 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
361 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
363 inst = #(define-music-function (parser location string) (string?)
367 'text (markup #:bold (#:box string))))
370 We will refer to this file using the @code{\include} command near
371 the top of the music file. (The extension @code{.ily} is used to
372 distinguish this included file, which is not meant to be compiled
373 on its own, from the main file.)
374 Now let's modify our music (let's save this file as @file{"music.ly"}).
376 @c We have to do this awkward example/lilypond-non-verbatim
377 @c because we can't do the \include stuff in the manual.
380 \include "definitions.ily"
384 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
386 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
390 @lilypond[quote,ragged-right]
391 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
392 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
394 inst = #(define-music-function (parser location string) (string?)
398 'text (markup #:bold (#:box string))))
402 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
404 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
408 That looks better, but let's make a few changes. The glissando is hard
409 to see, so let's make it thicker and closer to the note heads. Let's
410 put the metronome marking above the clef, instead of over the first
411 note. And finally, my composition professor hates @q{C} time signatures,
412 so we'd better make that @q{4/4} instead.
414 Don't change @file{music.ly}, though. Replace our @file{definitions.ily}
419 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
420 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
422 inst = #(define-music-function (parser location string) (string?)
426 'text (markup #:bold (#:box string))))
430 \override MetronomeMark #'extra-offset = #'(-9 . 0)
431 \override MetronomeMark #'padding = #'3
434 \override TimeSignature #'style = #'numbered
437 \override Glissando #'thickness = #3
438 \override Glissando #'gap = #0.1
443 @lilypond[quote,ragged-right]
444 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
445 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
447 inst = #(define-music-function (parser location string) (string?)
451 'text (markup #:bold (#:box string))))
455 \override MetronomeMark #'extra-offset = #'(-9 . 0)
456 \override MetronomeMark #'padding = #'3
459 \override TimeSignature #'style = #'numbered
462 \override Glissando #'thickness = #3
463 \override Glissando #'gap = #0.1
469 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
471 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
475 That looks nicer! But now suppose that I want to publish this
476 piece. My composition professor doesn't like @q{C} time
477 signatures, but I'm somewhat fond of them. Let's copy the
478 current @file{definitions.ily} to @file{web-publish.ily} and
479 modify that. Since this music is aimed at producing a pdf which
480 will be displayed on the screen, we'll also increase the
481 overall size of the output.
485 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
486 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
488 inst = #(define-music-function (parser location string) (string?)
492 'text (markup #:bold (#:box string))))
494 #(set-global-staff-size 23)
497 \override MetronomeMark #'extra-offset = #'(-9 . 0)
498 \override MetronomeMark #'padding = #'3
503 \override Glissando #'thickness = #3
504 \override Glissando #'gap = #0.1
509 @lilypond[quote,ragged-right]
510 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
511 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
513 inst = #(define-music-function (parser location string) (string?)
517 'text (markup #:bold (#:box string))))
519 #(set-global-staff-size 23)
522 \override MetronomeMark #'extra-offset = #'(-9 . 0)
523 \override MetronomeMark #'padding = #'3
526 \override Glissando #'thickness = #3
527 \override Glissando #'gap = #0.1
533 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
535 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
539 Now in our music, I simply replace
540 @code{\include "definitions.ily"} with
541 @code{\include "web-publish.ily"}. Of course, we could make this
542 even more convenient. We could make a @file{definitions.ily} file which
543 contains only the definitions of @code{mpdolce} and @code{inst}, a
544 @file{web-publish.ily} file which contains only the @code{\layout}
545 section listed above, and a @file{university.ily} file which
546 contains only the tweaks to produce the output that my professor
547 prefers. The top of @file{music.ly} would then look like this:
550 \include "definitions.ily"
552 %%% Only uncomment one of these two lines!
553 \include "web-publish.ily"
554 %\include "university.ily"
557 This approach can be useful even if you are only producing
558 one set of parts. I use half a dozen different
559 @q{style sheet} files for my projects. I begin every music
560 file with @code{\include "../global.ily"}, which contains
564 \version @w{"@version{}"}
565 #(ly:set-option 'point-and-click #f)
566 \include "../init/init-defs.ly"
567 \include "../init/init-layout.ly"
568 \include "../init/init-headers.ly"
569 \include "../init/init-paper.ly"
573 @node When things don't work
574 @section When things don't work
577 * Updating old input files::
579 * Troubleshooting (taking it all apart)::
583 @node Updating old input files
584 @subsection Updating old input files
587 @cindex updating old input files
589 The LilyPond input syntax occasionally changes. As LilyPond itself
590 improves, the syntax (input language) is modified accordingly. Sometimes
591 these changes are made to make the input easier to read and write or
592 sometimes the changes are made to accommodate new features of LilyPond.
594 LilyPond comes with a file that makes this updating easier:
595 @code{convert-ly}. For details about how to run this program, see
596 @rprogram{Updating files with convert-ly}.
598 Unfortunately, @code{convert-ly} cannot handle all input changes. It
599 takes care of simple search-and-replace changes (such as @code{raggedright}
600 becoming @code{ragged-right}), but some changes are too
601 complicated. The syntax changes that @code{convert-ly} cannot handle
602 are listed in @rprogram{Updating files with convert-ly}.
604 For example, in LilyPond 2.4 and earlier, accents and non-English
605 letters were entered using LaTeX -- for example,
606 @code{No\"el} (this would print the French word for
607 @q{Christmas}). In LilyPond 2.6 and above, the special
608 @code{ë} must be entered directly into the LilyPond file as an
609 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
610 special characters into UTF-8 characters; you must manually update
611 your old LilyPond input files.
614 @subsection Common errors
616 The error conditions described below occur often, yet the cause
617 is not obvious or easily found. Once seen and understood, they
622 * Music runs off the page::
623 * An extra staff appears::
624 * Apparent error in ../ly/init.ly::
625 * Error message Unbound variable %::
628 @node Music runs off the page
629 @unnumberedsubsubsec Music runs off the page
631 Music running off the page over the right margin or appearing
632 unduly compressed is almost always due to entering an incorrect
633 duration on a note, causing the final note in a measure to extend
634 over the bar line. It is not invalid if the final note in a
635 measure does not end on the automatically entered bar line, as the
636 note is simply assumed to carry over into the next measure. But
637 if a long sequence of such carry-over measures occurs the music
638 can appear compressed or may flow off the page because automatic
639 line breaks can be inserted only at the end of complete measures,
640 i.e., where all notes end before or at the end of the measure.
642 @warning{An incorrect duration can cause line breaks to be
643 inhibited, leading to a line of highly compressed music or
644 music which flows off the page.}
646 The incorrect duration can be found easily if bar checks are used,
647 see @ruser{Bar and bar number checks}.
649 If you actually intend to have a series of such carry-over measures
650 you will need to insert an invisible bar line where you want the
651 line to break. For details, see @ruser{Bar lines}.
654 @node An extra staff appears
655 @unnumberedsubsubsec An extra staff appears
657 If contexts are not created explicitly with @code{\new} they will be
658 silently created as soon as a command is encountered which cannot
659 be applied to an existing context. In simple scores the automatic
660 creation of contexts is useful, and most of the examples in the
661 LilyPond manuals take advantage of this simplification. But
662 occasionally the silent creation of contexts can give rise to
663 unexpected new staves or scores. For example, it might be expected
664 that the following code would cause all note heads within the
665 following staff to be colored red, but in fact it results in two
666 staves with the note heads remaining the default black in the lower
669 @lilypond[quote,verbatim,relative=2]
670 \override Staff.NoteHead #'color = #red
674 This is because a @code{Staff} context does not exist when the
675 override is processed, so one is implicitly created and the override
676 is applied to it, but then the @code{\new Staff} command creates
677 another, separate, staff into which the notes are placed. The
678 correct code to color all note heads red is
680 @lilypond[quote,verbatim,relative=2]
682 \override Staff.NoteHead #'color = #red
687 As a second example, if a @code{\relative} command is placed inside
688 a @code{\repeat} command two staves result, the second offset from
689 the first, because the @code{\repeat} command generates two
690 @code{\relative} blocks, which each implicitly create @code{Staff}
691 and @code{Voice} blocks.
693 @lilypond[quote,verbatim]
694 \repeat unfold 2 \relative { c d e f }
697 The correct way is to reverse the @code{\repeat} and
698 @code{\relative} commands, like this:
700 @lilypond[quote,verbatim]
702 \repeat unfold 2 { c d e f }
707 @node Apparent error in ../ly/init.ly
708 @unnumberedsubsubsec Apparent error in @code{../ly/init.ly}
710 Various obscure error messages may appear about syntax errors in
711 @code{../ly/init.ly} if the input file is not correctly formed,
712 for example, if it does not contain correctly
713 matched braces or quote signs.
715 The most common error is a missing brace, (@code{@}}), at the end of
716 a @code{score} block. Here the solution is obvious: check the
717 @code{score} block is correctly terminated. The correct structure
718 of an input file is described in @ref{How LilyPond input files work}.
719 Using an editor which automatically highlights matching brackets and
720 braces is helpful to avoid such errors.
722 This error message can also appear if a terminating quote sign,
723 (@code{"}), is omitted. In this case an accompanying error message
724 should give a line number close to the line in error. The
725 mismatched quote will usually be on the line one or two above.
727 @node Error message Unbound variable %
728 @unnumberedsubsubsec Error message Unbound variable %
730 This error message will appear at the bottom of the console
731 output or log file together with a @qq{GUILE signalled an error ...}
732 message every time a Scheme routine is called which (invalidly)
733 contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
735 LilyPond comments begin with a percent sign, (@code{%}), and must
736 not be used within Scheme routines. Scheme comments begin with a
737 semi-colon, (@code{;}).
739 @node Troubleshooting (taking it all apart)
740 @subsection Troubleshooting (taking it all apart)
742 Sooner or later, you will write a file that LilyPond cannot
743 compile. The messages that LilyPond gives may help
744 you find the error, but in many cases you need to do some
745 investigation to determine the source of the problem.
747 The most powerful tools for this purpose are the
748 single line comment (indicated by @code{%}) and the block
749 comment (indicated by @code{%@{ ... %@}}). If you don't
750 know where a problem is, start commenting out huge portions
751 of your input file. After you comment out a section, try
752 compiling the file again. If it works, then the problem
753 must exist in the portion you just commented. If it doesn't
754 work, then keep on commenting out material until you have
755 something that works.
757 In an extreme case, you might end up with only
771 (in other words, a file without any music)
773 If that happens, don't give up. Uncomment a bit -- say,
774 the bass part -- and see if it works. If it doesn't work,
775 then comment out all of the bass music (but leave
776 @code{\bass} in the @code{\score} uncommented.
779 bass = \relative c' @{
787 Now start slowly uncommenting more and more of the
788 @code{bass} part until you find the problem line.
790 Another very useful debugging technique is constructing
791 @ref{Minimal examples}.
794 @node Minimal examples
795 @subsection Minimal examples
797 A minimal example is an example which is as small as possible. These
798 examples are much easier to understand than long examples. Minimal
799 examples are used for
803 @item Sending a help request to mailing lists
804 @item Adding an example to the @uref{http://lsr.dsi.unimi.it/,
805 LilyPond Snippet Repository}
808 To construct an example which is as small as possible, the rule is
809 quite simple: remove anything which is not necessary. When trying to
810 remove unnecessary parts of a file, it is a very good idea to comment
811 out lines instead of deleting them. That way, if you discover that you
812 actually @emph{do} need some lines, you can uncomment them, instead of
813 typing them in from scratch.
815 There are two exceptions to the @qq{as small as possible} rule:
818 @item Include the @code{\version} number.
819 @item If possible, use @code{\paper@{ ragged-right=##t @}} at the
823 The whole point of a minimal example is to make it easy to read:
826 @item Avoid using complicated notes, keys, or time signatures, unless you
827 wish to demonstrate something is about the behavior of those items.
828 @item Do not use @code{\override} commands unless that is the point of the
834 @node Make and Makefiles
835 @section Make and Makefiles
840 Pretty well all the platforms Lilypond can run on support a software
841 facility called @code{make}. This software reads a special file called a
842 @code{Makefile} that defines what files depend on what others and what
843 commands you need to give the operating system to produce one file from
844 another. For example the makefile would spell out how to produce
845 @code{ballad.pdf} and @code{ballad.midi} from @code{ballad.ly} by
848 There are times when it is a good idea to create a @code{Makefile}
849 for your project, either for your own convenience or
850 as a courtesy to others who might have access to your source files.
851 This is true for very large projects with many included files and
852 different output options (e.g. full score, parts, conductor's
853 score, piano reduction, etc.), or for projects that
854 require difficult commands to build them (such as
855 @code{lilypond-book} projects). Makefiles vary greatly in
856 complexity and flexibility, according to the needs and skills of
857 the authors. The program GNU Make comes installed on GNU/Linux
858 distributions and on MacOS X, and it is also available for Windows.
860 See the @strong{GNU Make Manual} for full details on using
861 @code{make}, as what follows here gives only a glimpse of what it
864 The commands to define rules in a makefile differ
865 according to platform; for instance the various forms of Linux and
866 MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
867 MacOS X, you need to configure the system to use the command-line
868 intepreter. Here are some example makefiles, with versions for both
869 Linux/MacOS and Windows.
871 The first example is for an orchestral work in four
872 movements with a directory structure as follows:
889 | |-- symphony-cello.ly
890 | |-- symphony-horn.ly
891 | |-- symphony-oboes.ly
892 | |-- symphony-viola.ly
893 | |-- symphony-violinOne.ly
894 | `-- symphony-violinTwo.ly
904 The @code{.ly} files in the @code{Scores} and
905 @code{Parts} directories get their notes from @code{.ily}
906 files in the @code{Notes} directory:
909 %%% top of file "symphony-cello.ly"
910 \include ../definitions.ily
911 \include ../Notes/cello.ily
914 The makefile will have targets of @code{score} (entire piece in
915 full score), @code{movements} (individual movements in full score),
916 and @code{parts} (individual parts for performers). There
917 is also a target @code{archive} that will create a tarball of
918 the source files, suitable for sharing via web or email. Here is
919 the makefile for GNU/Linux or MacOS X. It should be saved with the
920 name @code{Makefile} in the top directory of the project:
922 @warning{When a target or pattern rule is defined, the
923 subsequent lines must begin with tabs, not spaces.}
926 # the name stem of the output files
928 # determine how many processors are present
929 CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
930 # The command to run lilypond
931 LILY_CMD = lilypond -ddelete-intermediate-files \
932 -dno-point-and-click -djob-count=$(CPU_CORES)
934 # The suffixes used in this Makefile.
935 .SUFFIXES: .ly .ily .pdf .midi
937 # Input and output files are searched in the directories listed in
938 # the VPATH variable. All of them are subdirectories of the current
939 # directory (given by the GNU make variable `CURDIR').
946 # The pattern rule to create PDF and MIDI files from a LY input file.
947 # The .pdf output files are put into the `PDF' subdirectory, and the
948 # .midi files go into the `MIDI' subdirectory.
950 $(LILY_CMD) $<; \ # this line begins with a tab
951 if test -f "$*.pdf"; then \
954 if test -f "$*.midi"; then \
955 mv "$*.midi" MIDI/; \
966 # The dependencies of the movements.
967 $(piece)I.pdf: $(piece)I.ly $(notes)
968 $(piece)II.pdf: $(piece)II.ly $(notes)
969 $(piece)III.pdf: $(piece)III.ly $(notes)
970 $(piece)IV.pdf: $(piece)IV.ly $(notes)
972 # The dependencies of the full score.
973 $(piece).pdf: $(piece).ly $(notes)
975 # The dependencies of the parts.
976 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
977 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
978 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
979 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
980 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
981 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
983 # Type `make score' to generate the full score of all four
984 # movements as one file.
988 # Type `make parts' to generate all parts.
989 # Type `make foo.pdf' to generate the part for instrument `foo'.
990 # Example: `make symphony-cello.pdf'.
992 parts: $(piece)-cello.pdf \
993 $(piece)-violinOne.pdf \
994 $(piece)-violinTwo.pdf \
999 # Type `make movements' to generate files for the
1000 # four movements separately.
1002 movements: $(piece)I.pdf \
1007 all: score parts movements
1010 tar -cvvf stamitz.tar \ # this line begins with a tab
1011 --exclude=*pdf --exclude=*~ \
1012 --exclude=*midi --exclude=*.tar \
1017 There are special complications on the Windows platform. After
1018 downloading and installing GNU Make for Windows, you must set the
1019 correct path in the system's environment variables so that the
1020 DOS shell can find the Make program. To do this, right-click on
1021 "My Computer," then choose @code{Properties} and
1022 @code{Advanced}. Click @code{Environment Variables}, and then
1023 in the @code{System Variables} pane, highlight @code{Path}, click
1024 @code{edit}, and add the path to the GNU Make executable file, which
1025 will look something like this:
1028 C:\Program Files\GnuWin32\bin
1031 The makefile itself has to be altered to handle different shell
1032 commands and to deal with spaces that are present
1033 in some default system directories. The @code{archive} target
1034 is eliminated since Windows does not have the @code{tar} command,
1035 and Windows also has a different default extension for midi files.
1042 LILY_CMD = lilypond -ddelete-intermediate-files \
1043 -dno-point-and-click \
1044 -djob-count=$(NUMBER_OF_PROCESSORS)
1046 #get the 8.3 name of CURDIR (workaround for spaces in PATH)
1047 workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
1050 .SUFFIXES: .ly .ily .pdf .mid
1059 $(LILY_CMD) $< # this line begins with a tab
1060 if exist "$*.pdf" move /Y "$*.pdf" PDF/ # begin with tab
1061 if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab
1073 $(piece)I.pdf: $(piece)I.ly $(notes)
1074 $(piece)II.pdf: $(piece)II.ly $(notes)
1075 $(piece)III.pdf: $(piece)III.ly $(notes)
1076 $(piece)IV.pdf: $(piece)IV.ly $(notes)
1078 $(piece).pdf: $(piece).ly $(notes)
1080 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
1081 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
1082 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
1083 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
1084 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
1085 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
1091 parts: $(piece)-cello.pdf \
1092 $(piece)-violinOne.pdf \
1093 $(piece)-violinTwo.pdf \
1094 $(piece)-viola.pdf \
1095 $(piece)-oboes.pdf \
1099 movements: $(piece)I.pdf \
1104 all: score parts movements
1108 The next Makefile is for a @command{lilypond-book} document done in
1109 LaTeX. This project has an index, which requires that the
1110 @command{latex} command be run twice to update links. Output files are
1111 all stored in the @code{out} directory for .pdf output and in the
1112 @code{htmlout} directory for the html output.
1121 LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
1122 LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
1123 PDF=cd $(OUTDIR) && pdflatex $(FILE)
1124 HTML=cd $(WEBDIR) && latex2html $(FILE)
1125 INDEX=cd $(OUTDIR) && makeindex $(FILE)
1126 PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &
1131 $(LILYBOOK_PDF) # begin with tab
1132 $(PDF) # begin with tab
1133 $(INDEX) # begin with tab
1134 $(PDF) # begin with tab
1135 $(PREVIEW) # begin with tab
1138 $(LILYBOOK_HTML) # begin with tab
1139 $(HTML) # begin with tab
1140 cp -R $(WEBDIR)/$(FILE)/ ./ # begin with tab
1141 $(BROWSER) $(FILE)/$(FILE).html & # begin with tab
1144 cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab
1147 rm -rf $(OUTDIR) # begin with tab
1150 rm -rf $(WEBDIR) # begin with tab
1153 tar -cvvf myproject.tar \ # begin this line with tab
1155 --exclude=htmlout/* \
1156 --exclude=myproject/* \
1163 TODO: make this thing work on Windows
1165 The previous makefile does not work on Windows. An alternative
1166 for Windows users would be to create a simple batch file
1167 containing the build commands. This will not
1168 keep track of dependencies the way a makefile does, but it at
1169 least reduces the build process to a single command. Save the
1170 following code as @command{build.bat} or @command{build.cmd}.
1171 The batch file can be run at the DOS prompt or by simply
1172 double-clicking its icon.
1175 lilypond-book --output=out --pdf myproject.lytex
1181 copy out\myproject.pdf MyProject.pdf
1187 @rprogram{Setup for MacOS X},
1188 @rprogram{Command-line usage},
1189 @rprogram{LilyPond-book}