1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
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::
25 * Make and Makefiles::
29 @node Suggestions for writing LilyPond input files
30 @section Suggestions for writing LilyPond input files
32 Now you're ready to begin writing larger LilyPond input files --
33 not just the little examples in the tutorial, but whole pieces.
34 But how should you go about doing it?
36 As long as LilyPond can understand your input files and produce
37 the output that you want, it doesn't matter what your input files
38 look like. However, there are a few other things to consider when
39 writing LilyPond input files.
42 @item What if you make a mistake? The structure of a LilyPond
43 file can make certain errors easier (or harder) to find.
45 @item What if you want to share your input files with somebody
46 else? In fact, what if you want to alter your own input files in
47 a few years? Some LilyPond input files are understandable at
48 first glance; others may leave you scratching your head
51 @item What if you want to upgrade your LilyPond file for use
52 with a later version of LilyPond? The input syntax changes
53 occasionally as LilyPond improves. Most changes can be
54 done automatically with @code{convert-ly}, but some changes
55 might require manual assistance. LilyPond input files can be
56 structured in order to be easier (or harder) to update.
61 * General suggestions::
62 * Typesetting existing music::
64 * Saving typing with variables and functions::
69 @node General suggestions
70 @subsection General suggestions
72 Here are a few suggestions that can help you to avoid or fix
76 @item @strong{Include @code{\version} numbers in every file}. Note that all
77 templates contain @code{\version} information. We
78 highly recommend that you always include the @code{\version}, no matter
79 how small your file is. Speaking from personal experience, it's
80 quite frustrating to try to remember which version of LilyPond you were
81 using a few years ago. @command{convert-ly} requires you to declare
82 which version of LilyPond you used.
84 @item @strong{Include checks}: @ruser{Bar and bar number checks},
85 @ruser{Octave checks}. If you include checks every so often, then
86 if you make a mistake, you can pinpoint it quicker. How often is
87 @q{every so often}? It depends on the complexity of the music.
88 For very simple music, perhaps just once or twice. For very
89 complex music, perhaps every bar.
91 @item @strong{One bar per line of text}. If there is anything complicated,
93 itself or in the output you desire, it's often good to write only one bar
94 per line. Saving screen space by cramming eight bars per line just isn't
95 worth it if you have to @q{debug} your input files.
97 @item @strong{Comment your input files}. Use either bar numbers
99 references to musical themes (@q{second theme in violins,} @q{fourth
100 variation,} etc.). You may not need comments when you're writing the piece
101 for the first time, but if you want to go back to change something two or
102 three years later, or if you pass the source over to a friend, it will
104 challenging to determine your intentions or how your file is structured if
105 you didn't comment the file.
107 @item @strong{Indent your braces}. A lot of problems are caused by an
109 in the number of @code{@{} and @code{@}}.
111 @item @strong{Explicitly add durations} at the beginnings of sections
112 and variables. If you specify @code{c4 d e} at the beginning of a
113 phrase (instead of just @code{c d e}) you can save yourself some
114 problems if you rearrange your music later.
116 @item @strong{Separate tweaks} from music definitions. See
117 @ref{Saving typing with variables and functions}, and
123 @node Typesetting existing music
124 @subsection Typesetting existing music
126 If you are entering music from an existing score (i.e., typesetting a
127 piece of existing sheet music),
131 @item Enter the manuscript (the physical copy of the music) into
132 LilyPond one system at a time (but still only one bar per line of text),
133 and check each system when you finish it. You may use the
134 @code{showLastLength} or @code{showFirstLength} properties to speed up
135 processing -- see @ruser{Skipping corrected music}.
137 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
138 in the input file whenever the manuscript has a line break. This
139 makes it much easier to compare the LilyPond music to the original
140 music. When you are finished proofreading your score, you may
141 define @code{mBreak = @{ @}} to remove all those line breaks. This
142 will allow LilyPond to place line breaks wherever it feels are
145 @item When entering a part for a transposing instrument into a
146 variable, it is recommended that the notes are wrapped in
149 \transpose c natural-pitch @{...@}
151 (where @code{natural-pitch} is the open pitch of the instrument) so
152 that the music in the variable is effectively in C. You can transpose
153 it back again when the variable is used, if required, but you might
154 not want to (e.g., when printing a score in concert pitch,
155 converting a trombone part from treble to bass clef, etc.)
156 Mistakes in transpositions are less likely if all the music in
157 variables is at a consistent pitch.
159 Also, only ever transpose to/from C. That means that the only other
160 keys you will use are the natural pitches of the instruments - bes
161 for a B-flat trumpet, aes for an A-flat clarinet, etc.
167 @subsection Large projects
169 When working on a large project, having a clear structure to your
170 lilypond input files becomes vital.
174 @item @strong{Use a variable for each voice}, with a minimum of
175 structure inside the definition. The structure of the
176 @code{\score} section is the most likely thing to change;
177 the @code{violin} definition is extremely unlikely to change
178 in a new version of LilyPond.
181 violin = \relative c'' @{
194 @item @strong{Separate tweaks from music definitions}. This
195 point was made previously, but for large
196 projects it is absolutely vital. We might need to change
197 the definition of @code{fthenp}, but then we only need
198 to do this once, and we can still avoid touching anything
199 inside @code{violin}.
203 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
204 violin = \relative c'' @{
212 @node Saving typing with variables and functions
213 @subsection Saving typing with variables and functions
218 By this point, you've seen this kind of thing:
220 @lilypond[quote,verbatim,ragged-right]
221 hornNotes = \relative c'' { c4 b dis c }
229 You may even realize that this could be useful in minimalist music:
231 @lilypond[quote,verbatim,ragged-right]
232 fragmentA = \relative c'' { a4 a8. b16 }
233 fragmentB = \relative c'' { a8. gis16 ees4 }
234 violin = \new Staff { \fragmentA \fragmentA \fragmentB \fragmentA }
242 However, you can also use these variables (also known as
243 variables, macros, or (user-defined) command) for tweaks:
245 @lilypond[quote,verbatim,ragged-right]
246 dolce = \markup{ \italic \bold dolce }
247 padText = { \once \override TextScript #'padding = #5.0 }
248 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
249 violin = \relative c'' {
251 c4._\dolce b8 a8 g a b |
253 c4.^"hi there!" d8 e' f g d |
254 c,4.\fthenp b8 c4 c-. |
261 \layout{ragged-right=##t}
265 These variables are obviously useful for saving
266 typing. But they're worth considering even if you
267 only use them once -- they reduce complexity. Let's
268 look at the previous example without any
269 variables. It's a lot harder to read, especially
273 violin = \relative c'' @{
275 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
276 \once \override TextScript #'padding = #5.0
277 c4.^"hi there!" d8 e' f g d |
278 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
279 \hspace #0.1 \dynamic p @} b8 c4 c-. |
284 @c TODO Replace the following with a better example -td
285 @c Skylining handles this correctly without padText
287 So far we've seen static substitution -- when LilyPond
288 sees @code{\padText}, it replaces it with the stuff that
289 we've defined it to be (ie the stuff to the right of
292 LilyPond can handle non-static substitution, too (you
293 can think of these as functions).
295 @lilypond[quote,verbatim,ragged-right]
297 #(define-music-function (parser location padding) (number?)
299 \once \override TextScript #'padding = #$padding
307 c4^"piu mosso" fis a g
311 Using variables is also a good way to reduce work if the
312 LilyPond input syntax changes (see @ref{Updating old input files}). If
313 you have a single definition (such as @code{\dolce}) for all your
314 input files (see @ref{Style sheets}), then if the syntax changes, you
315 only need to update your single @code{\dolce} definition,
316 instead of making changes throughout every @code{.ly} file.
320 @subsection Style sheets
322 The output that LilyPond produces can be heavily modified; see
323 @ref{Tweaking output}, for details. But what if you have many
324 input files that you want to apply your tweaks to? Or what if you
325 simply want to separate your tweaks from the actual music? This
328 Let's look at an example. Don't worry if you don't understand
329 the parts with all the @code{#()}. This is explained in
330 @ref{Advanced tweaks with Scheme}.
332 @lilypond[quote,verbatim,ragged-right]
333 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
334 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
336 inst = #(define-music-function (parser location string) (string?)
340 'text (markup #:bold (#:box string))))
344 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
346 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
350 There are some problems with overlapping output; we'll fix those using
351 the techniques in @ref{Moving objects}. But let's also
352 do something about the @code{mpdolce} and @code{inst}
353 definitions. They produce the output we desire, but we might want
354 to use them in another piece. We could simply copy-and-paste them
355 at the top of every file, but that's an annoyance. It also leaves
356 those definitions in our input files, and I personally find all
357 the @code{#()} somewhat ugly. Let's hide them in another file:
360 %%% save this to a file called "definitions.ily"
361 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
362 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
364 inst = #(define-music-function (parser location string) (string?)
368 'text (markup #:bold (#:box string))))
371 We will refer to this file using the @code{\include} command near
372 the top of the music file. (The extension @code{.ily} is used to
373 distinguish this included file, which is not meant to be compiled
374 on its own, from the main file.)
375 Now let's modify our music (let's save this file as @file{"music.ly"}).
377 @c We have to do this awkward example/lilypond-non-verbatim
378 @c because we can't do the \include stuff in the manual.
381 \include "definitions.ily"
385 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
387 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
391 @lilypond[quote,ragged-right]
392 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
393 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
395 inst = #(define-music-function (parser location string) (string?)
399 'text (markup #:bold (#:box string))))
403 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
405 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
409 That looks better, but let's make a few changes. The glissando is hard
410 to see, so let's make it thicker and closer to the note heads. Let's
411 put the metronome marking above the clef, instead of over the first
412 note. And finally, my composition professor hates @q{C} time signatures,
413 so we'd better make that @q{4/4} instead.
415 Don't change @file{music.ly}, though. Replace our @file{definitions.ily}
420 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
421 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
423 inst = #(define-music-function (parser location string) (string?)
427 'text (markup #:bold (#:box string))))
431 \override MetronomeMark #'extra-offset = #'(-9 . 0)
432 \override MetronomeMark #'padding = #'3
435 \override TimeSignature #'style = #'numbered
438 \override Glissando #'thickness = #3
439 \override Glissando #'gap = #0.1
444 @lilypond[quote,ragged-right]
445 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
446 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
448 inst = #(define-music-function (parser location string) (string?)
452 'text (markup #:bold (#:box string))))
456 \override MetronomeMark #'extra-offset = #'(-9 . 0)
457 \override MetronomeMark #'padding = #'3
460 \override TimeSignature #'style = #'numbered
463 \override Glissando #'thickness = #3
464 \override Glissando #'gap = #0.1
470 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
472 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
476 That looks nicer! But now suppose that I want to publish this
477 piece. My composition professor doesn't like @q{C} time
478 signatures, but I'm somewhat fond of them. Let's copy the
479 current @file{definitions.ily} to @file{web-publish.ily} and
480 modify that. Since this music is aimed at producing a pdf which
481 will be displayed on the screen, we'll also increase the
482 overall size of the output.
486 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
487 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
489 inst = #(define-music-function (parser location string) (string?)
493 'text (markup #:bold (#:box string))))
495 #(set-global-staff-size 23)
498 \override MetronomeMark #'extra-offset = #'(-9 . 0)
499 \override MetronomeMark #'padding = #'3
504 \override Glissando #'thickness = #3
505 \override Glissando #'gap = #0.1
510 @lilypond[quote,ragged-right]
511 mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
512 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
514 inst = #(define-music-function (parser location string) (string?)
518 'text (markup #:bold (#:box string))))
520 #(set-global-staff-size 23)
523 \override MetronomeMark #'extra-offset = #'(-9 . 0)
524 \override MetronomeMark #'padding = #'3
527 \override Glissando #'thickness = #3
528 \override Glissando #'gap = #0.1
534 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
536 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
540 Now in our music, I simply replace
541 @code{\include "definitions.ily"} with
542 @code{\include "web-publish.ily"}. Of course, we could make this
543 even more convenient. We could make a @file{definitions.ily} file which
544 contains only the definitions of @code{mpdolce} and @code{inst}, a
545 @file{web-publish.ily} file which contains only the @code{\layout}
546 section listed above, and a @file{university.ily} file which
547 contains only the tweaks to produce the output that my professor
548 prefers. The top of @file{music.ly} would then look like this:
551 \include "definitions.ily"
553 %%% Only uncomment one of these two lines!
554 \include "web-publish.ily"
555 %\include "university.ily"
558 This approach can be useful even if you are only producing
559 one set of parts. I use half a dozen different
560 @q{style sheet} files for my projects. I begin every music
561 file with @code{\include "../global.ily"}, which contains
565 \version @w{"@version{}"}
566 #(ly:set-option 'point-and-click #f)
567 \include "../init/init-defs.ly"
568 \include "../init/init-layout.ly"
569 \include "../init/init-headers.ly"
570 \include "../init/init-paper.ly"
574 @node When things don't work
575 @section When things don't work
578 * Updating old input files::
580 * Troubleshooting (taking it all apart)::
584 @node Updating old input files
585 @subsection Updating old input files
588 @cindex updating old input files
590 The LilyPond input syntax occasionally changes. As LilyPond itself
591 improves, the syntax (input language) is modified accordingly. Sometimes
592 these changes are made to make the input easier to read and write or
593 sometimes the changes are made to accommodate new features of LilyPond.
595 LilyPond comes with a file that makes this updating easier:
596 @code{convert-ly}. For details about how to run this program, see
597 @rprogram{Updating files with convert-ly}.
599 Unfortunately, @code{convert-ly} cannot handle all input changes. It
600 takes care of simple search-and-replace changes (such as @code{raggedright}
601 becoming @code{ragged-right}), but some changes are too
602 complicated. The syntax changes that @code{convert-ly} cannot handle
603 are listed in @rprogram{Updating files with convert-ly}.
605 For example, in LilyPond 2.4 and earlier, accents and non-English
606 letters were entered using LaTeX -- for example,
607 @code{No\"el} (this would print the French word for
608 @q{Christmas}). In LilyPond 2.6 and above, the special
609 @code{ë} must be entered directly into the LilyPond file as an
610 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
611 special characters into UTF-8 characters; you must manually update
612 your old LilyPond input files.
615 @subsection Common errors
617 The error conditions described below occur often, yet the cause
618 is not obvious or easily found. Once seen and understood, they
623 * Music runs off the page::
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}.
653 @node Apparent error in ../ly/init.ly
654 @unnumberedsubsubsec Apparent error in @code{../ly/init.ly}
656 Various obscure error messages may appear about syntax errors in
657 @code{../ly/init.ly} if the input file is not correctly formed,
658 for example, if it does not contain correctly
659 matched braces or quote signs.
661 The most common error is a missing brace, (@code{@}}), at the end of
662 a @code{score} block. Here the solution is obvious: check the
663 @code{score} block is correctly terminated. The correct structure
664 of an input file is described in @ref{How LilyPond input files work}.
665 Using an editor which automatically highlights matching brackets and
666 braces is helpful to avoid such errors.
668 This error message can also appear if a terminating quote sign,
669 (@code{"}), is omitted. In this case an accompanying error message
670 should give a line number close to the line in error. The
671 mismatched quote will usually be on the line one or two above.
673 @node Error message Unbound variable %
674 @unnumberedsubsubsec Error message Unbound variable %
676 This error message will appear at the bottom of the console
677 output or log file together with a @qq{GUILE signalled an error ...}
678 message every time a Scheme routine is called which (invalidly)
679 contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
681 LilyPond comments begin with a percent sign, (@code{%}), and must
682 not be used within Scheme routines. Scheme comments begin with a
683 semi-colon, (@code{;}).
685 @node Troubleshooting (taking it all apart)
686 @subsection Troubleshooting (taking it all apart)
688 Sooner or later, you will write a file that LilyPond cannot
689 compile. The messages that LilyPond gives may help
690 you find the error, but in many cases you need to do some
691 investigation to determine the source of the problem.
693 The most powerful tools for this purpose are the
694 single line comment (indicated by @code{%}) and the block
695 comment (indicated by @code{%@{ ... %@}}). If you don't
696 know where a problem is, start commenting out huge portions
697 of your input file. After you comment out a section, try
698 compiling the file again. If it works, then the problem
699 must exist in the portion you just commented. If it doesn't
700 work, then keep on commenting out material until you have
701 something that works.
703 In an extreme case, you might end up with only
717 (in other words, a file without any music)
719 If that happens, don't give up. Uncomment a bit -- say,
720 the bass part -- and see if it works. If it doesn't work,
721 then comment out all of the bass music (but leave
722 @code{\bass} in the @code{\score} uncommented.
725 bass = \relative c' @{
733 Now start slowly uncommenting more and more of the
734 @code{bass} part until you find the problem line.
736 Another very useful debugging technique is constructing
737 @ref{Minimal examples}.
740 @node Minimal examples
741 @subsection Minimal examples
743 A minimal example is an example which is as small as possible. These
744 examples are much easier to understand than long examples. Minimal
745 examples are used for
749 @item Sending a help request to mailing lists
750 @item Adding an example to the @uref{http://lsr.dsi.unimi.it/,
751 LilyPond Snippet Repository}
754 To construct an example which is as small as possible, the rule is
755 quite simple: remove anything which is not necessary. When trying to
756 remove unnecessary parts of a file, it is a very good idea to comment
757 out lines instead of deleting them. That way, if you discover that you
758 actually @emph{do} need some lines, you can uncomment them, instead of
759 typing them in from scratch.
761 There are two exceptions to the @qq{as small as possible} rule:
764 @item Include the @code{\version} number.
765 @item If possible, use @code{\paper@{ ragged-right=##t @}} at the
769 The whole point of a minimal example is to make it easy to read:
772 @item Avoid using complicated notes, keys, or time signatures, unless you
773 wish to demonstrate something is about the behavior of those items.
774 @item Do not use @code{\override} commands unless that is the point of the
780 @node Scores and parts
781 @section Scores and parts
783 TODO: this is really old stuff from the really old tutorial.
784 Rewrite, fix, etc. Or maybe delete entirely. -gp
785 Include section on tags -td
786 and then move to section 5. Working ... -td
788 In orchestral music, all notes are printed twice. Once in a part for
789 the musicians, and once in a full score for the conductor. Variables can
790 be used to avoid double work. The music is entered once, and stored in
791 a variable. The contents of that variable is then used to generate
792 both the part and the full score.
794 It is convenient to define the notes in a special file. For example,
795 suppose that the file @file{horn-music.ly} contains the following part
796 of a horn/@/bassoon duo
799 hornNotes = \relative c @{
806 Then, an individual part is made by putting the following in a file
809 \include "horn-music.ly"
811 instrument = "Horn in F"
815 \transpose f c' \hornNotes
822 \include "horn-music.ly"
826 substitutes the contents of @file{horn-music.ly} at this position in
827 the file, so @code{hornNotes} is defined afterwards. The command
828 @code{\transpose f@tie{}c'} indicates that the argument, being
829 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
830 @code{f} is denoted by notated @code{c'}, which corresponds with the
831 tuning of a normal French Horn in@tie{}F. The transposition can be seen
832 in the following output
834 @lilypond[quote,ragged-right]
835 \transpose f c' \relative c {
841 In ensemble pieces, one of the voices often does not play for many
842 measures. This is denoted by a special rest, the multi-measure
843 rest. It is entered with a capital @code{R} followed by a duration
844 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
845 etc.). By multiplying the
846 duration, longer rests can be constructed. For example, this rest
847 takes 3@tie{}measures in 2/4 time
853 When printing the part, multi-rests
854 must be condensed. This is done by setting a run-time variable
857 \set Score.skipBars = ##t
861 This command sets the property @code{skipBars} in the
862 @code{Score} context to true (@code{##t}). Prepending the rest and
863 this option to the music above, leads to the following result
865 @lilypond[quote,ragged-right]
866 \transpose f c' \relative c {
868 \set Score.skipBars = ##t
875 The score is made by combining all of the music together. Assuming
876 that the other voice is in @code{bassoonNotes} in the file
877 @file{bassoon-music.ly}, a score is made with
880 \include "bassoon-music.ly"
881 \include "horn-music.ly"
884 \new Staff \hornNotes
885 \new Staff \bassoonNotes
892 @lilypond[quote,ragged-right]
900 r4 d,8 f | gis4 c | b bes |
901 a8 e f4 | g d | gis f
908 @node Make and Makefiles
909 @section Make and Makefiles
914 Pretty well all the platforms Lilypond can run on support a software
915 facility called @code{make}. This software reads a special file called a
916 @code{Makefile} that defines what files depend on what others and what
917 commands you need to give the operating system to produce one file from
918 another. For example the makefile would spell out how to produce
919 @code{ballad.pdf} and @code{ballad.midi} from @code{ballad.ly} by
922 There are times when it is a good idea to create a @code{Makefile}
923 for your project, either for your own convenience or
924 as a courtesy to others who might have access to your source files.
925 This is true for very large projects with many included files and
926 different output options (e.g. full score, parts, conductor's
927 score, piano reduction, etc.), or for projects that
928 require difficult commands to build them (such as
929 @code{lilypond-book} projects). Makefiles vary greatly in
930 complexity and flexibility, according to the needs and skills of
931 the authors. The program GNU Make comes installed on GNU/Linux
932 distributions and on MacOS X, and it is also available for Windows.
934 See the @strong{GNU Make Manual} for full details on using
935 @code{make}, as what follows here gives only a glimpse of what it
938 The commands to define rules in a makefile differ
939 according to platform; for instance the various forms of Linux and
940 MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
941 MacOS X, you need to configure the system to use the command-line
942 intepreter. Here are some example makefiles, with versions for both
943 Linux/MacOS and Windows.
945 The first example is for an orchestral work in four
946 movements with a directory structure as follows:
963 | |-- symphony-cello.ly
964 | |-- symphony-horn.ly
965 | |-- symphony-oboes.ly
966 | |-- symphony-viola.ly
967 | |-- symphony-violinOne.ly
968 | `-- symphony-violinTwo.ly
978 The @code{.ly} files in the @code{Scores} and
979 @code{Parts} directories get their notes from @code{.ily}
980 files in the @code{Notes} directory:
983 %%% top of file "symphony-cello.ly"
984 \include ../definitions.ily
985 \include ../Notes/cello.ily
988 The makefile will have targets of @code{score} (entire piece in
989 full score), @code{movements} (individual movements in full score),
990 and @code{parts} (individual parts for performers). There
991 is also a target @code{archive} that will create a tarball of
992 the source files, suitable for sharing via web or email. Here is
993 the makefile for GNU/Linux or MacOS X. It should be saved with the
994 name @code{Makefile} in the top directory of the project:
996 @warning{When a target or pattern rule is defined, the
997 subsequent lines must begin with tabs, not spaces.}
1000 # the name stem of the output files
1002 # determine how many processors are present
1003 CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
1004 # The command to run lilypond
1005 LILY_CMD = lilypond -ddelete-intermediate-files \
1006 -dno-point-and-click -djob-count=$(CPU_CORES)
1008 # The suffixes used in this Makefile.
1009 .SUFFIXES: .ly .ily .pdf .midi
1011 # Input and output files are searched in the directories listed in
1012 # the VPATH variable. All of them are subdirectories of the current
1013 # directory (given by the GNU make variable `CURDIR').
1020 # The pattern rule to create PDF and MIDI files from a LY input file.
1021 # The .pdf output files are put into the `PDF' subdirectory, and the
1022 # .midi files go into the `MIDI' subdirectory.
1024 $(LILY_CMD) $<; \ # this line begins with a tab
1025 if test -f "$*.pdf"; then \
1028 if test -f "$*.midi"; then \
1029 mv "$*.midi" MIDI/; \
1040 # The dependencies of the movements.
1041 $(piece)I.pdf: $(piece)I.ly $(notes)
1042 $(piece)II.pdf: $(piece)II.ly $(notes)
1043 $(piece)III.pdf: $(piece)III.ly $(notes)
1044 $(piece)IV.pdf: $(piece)IV.ly $(notes)
1046 # The dependencies of the full score.
1047 $(piece).pdf: $(piece).ly $(notes)
1049 # The dependencies of the parts.
1050 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
1051 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
1052 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
1053 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
1054 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
1055 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
1057 # Type `make score' to generate the full score of all four
1058 # movements as one file.
1062 # Type `make parts' to generate all parts.
1063 # Type `make foo.pdf' to generate the part for instrument `foo'.
1064 # Example: `make symphony-cello.pdf'.
1066 parts: $(piece)-cello.pdf \
1067 $(piece)-violinOne.pdf \
1068 $(piece)-violinTwo.pdf \
1069 $(piece)-viola.pdf \
1070 $(piece)-oboes.pdf \
1073 # Type `make movements' to generate files for the
1074 # four movements separately.
1076 movements: $(piece)I.pdf \
1081 all: score parts movements
1084 tar -cvvf stamitz.tar \ # this line begins with a tab
1085 --exclude=*pdf --exclude=*~ \
1086 --exclude=*midi --exclude=*.tar \
1091 There are special complications on the Windows platform. After
1092 downloading and installing GNU Make for Windows, you must set the
1093 correct path in the system's environment variables so that the
1094 DOS shell can find the Make program. To do this, right-click on
1095 "My Computer," then choose @code{Properties} and
1096 @code{Advanced}. Click @code{Environment Variables}, and then
1097 in the @code{System Variables} pane, highlight @code{Path}, click
1098 @code{edit}, and add the path to the GNU Make executable file, which
1099 will look something like this:
1102 C:\Program Files\GnuWin32\bin
1105 The makefile itself has to be altered to handle different shell
1106 commands and to deal with spaces that are present
1107 in some default system directories. The @code{archive} target
1108 is eliminated since Windows does not have the @code{tar} command,
1109 and Windows also has a different default extension for midi files.
1116 LILY_CMD = lilypond -ddelete-intermediate-files \
1117 -dno-point-and-click \
1118 -djob-count=$(NUMBER_OF_PROCESSORS)
1120 #get the 8.3 name of CURDIR (workaround for spaces in PATH)
1121 workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
1124 .SUFFIXES: .ly .ily .pdf .mid
1133 $(LILY_CMD) $< # this line begins with a tab
1134 if exist "$*.pdf" move /Y "$*.pdf" PDF/ # begin with tab
1135 if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab
1147 $(piece)I.pdf: $(piece)I.ly $(notes)
1148 $(piece)II.pdf: $(piece)II.ly $(notes)
1149 $(piece)III.pdf: $(piece)III.ly $(notes)
1150 $(piece)IV.pdf: $(piece)IV.ly $(notes)
1152 $(piece).pdf: $(piece).ly $(notes)
1154 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
1155 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
1156 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
1157 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
1158 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
1159 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
1165 parts: $(piece)-cello.pdf \
1166 $(piece)-violinOne.pdf \
1167 $(piece)-violinTwo.pdf \
1168 $(piece)-viola.pdf \
1169 $(piece)-oboes.pdf \
1173 movements: $(piece)I.pdf \
1178 all: score parts movements
1182 The next Makefile is for a @command{lilypond-book} document done in
1183 LaTeX. This project has an index, which requires that the
1184 @command{latex} command be run twice to update links. Output files are
1185 all stored in the @code{out} directory for .pdf output and in the
1186 @code{htmlout} directory for the html output.
1195 LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
1196 LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
1197 PDF=cd $(OUTDIR) && pdflatex $(FILE)
1198 HTML=cd $(WEBDIR) && latex2html $(FILE)
1199 INDEX=cd $(OUTDIR) && makeindex $(FILE)
1200 PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &
1205 $(LILYBOOK_PDF) # begin with tab
1206 $(PDF) # begin with tab
1207 $(INDEX) # begin with tab
1208 $(PDF) # begin with tab
1209 $(PREVIEW) # begin with tab
1212 $(LILYBOOK_HTML) # begin with tab
1213 $(HTML) # begin with tab
1214 cp -R $(WEBDIR)/$(FILE)/ ./ # begin with tab
1215 $(BROWSER) $(FILE)/$(FILE).html & # begin with tab
1218 cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab
1221 rm -rf $(OUTDIR) # begin with tab
1224 rm -rf $(WEBDIR) # begin with tab
1227 tar -cvvf myproject.tar \ # begin this line with tab
1229 --exclude=htmlout/* \
1230 --exclude=myproject/* \
1237 TODO: make this thing work on Windows
1239 The previous makefile does not work on Windows. An alternative
1240 for Windows users would be to create a simple batch file
1241 containing the build commands. This will not
1242 keep track of dependencies the way a makefile does, but it at
1243 least reduces the build process to a single command. Save the
1244 following code as @command{build.bat} or @command{build.cmd}.
1245 The batch file can be run at the DOS prompt or by simply
1246 double-clicking its icon.
1249 lilypond-book --output=out --pdf myproject.lytex
1255 copy out\myproject.pdf MyProject.pdf
1261 @rprogram{Setup for MacOS X},
1262 @rprogram{Command-line usage},
1263 @rprogram{LilyPond-book}