File: INSTALL.txt

package info (click to toggle)
lilypond 2.19.83-1~exp1
  • links: PTS, VCS
  • area: main
  • in suites: experimental
  • size: 76,396 kB
  • sloc: cpp: 79,385; ansic: 75,071; lisp: 59,263; xml: 31,196; python: 22,406; sh: 8,159; yacc: 3,872; perl: 3,507; asm: 1,587; lex: 1,408; makefile: 1,048; tcl: 457; awk: 199; php: 53; csh: 50
file content (1173 lines) | stat: -rw-r--r-- 40,641 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
INSTALL - compiling and installing GNU LilyPond
***********************************************


1 Compilation
  1.1 Overview of compiling
  1.2 Requirements
    1.2.1 Requirements for running LilyPond
    1.2.2 Requirements for compiling LilyPond
      Fedora
      Linux Mint
      OpenSUSE
      Ubuntu
      Other
    1.2.3 Requirements for building documentation
  1.3 Getting the source code
  1.4 Configuring ‘make’
    1.4.1 Running ‘./autogen.sh’
    1.4.2 Running ‘../configure’
      Configuration options
      Checking build dependencies
      Configuring target directories
  1.5 Compiling LilyPond
    1.5.1 Using ‘make’
    1.5.2 Saving time with the ‘-j’ option
    1.5.3 Compiling for multiple platforms
    1.5.4 Useful ‘make’ variables
  1.6 Post-compilation options
    1.6.1 Installing LilyPond from a local build
    1.6.2 Generating documentation
      Documentation editor’s edit/compile cycle
      Building documentation
      Building a single document
      Saving time with ‘CPU_COUNT’
      AJAX search
      Installing documentation
      Building documentation without compiling
    1.6.3 Testing LilyPond binary
  1.7 Problems
    Compiling on MacOS X
    Solaris
    FreeBSD
    International fonts
    Using lilypond python libraries
  1.8 Concurrent stable and development versions
  1.9 Build system
1 Compilation
*************

1.1 Overview of compiling
=========================

Compiling LilyPond from source is an involved process, and is only
recommended for developers and packagers.  Typical program users are
instead encouraged to obtain the program from a package manager (on
Unix) or by downloading a precompiled binary configured for a specific
operating system.  Pre-compiled binaries are available on the *note
(lilypond-web)Download:: page.

   Compiling LilyPond from source is necessary if you want to build,
install, or test your own version of the program.

   A successful compile can also be used to generate and install the
documentation, incorporating any changes you may have made.  However, a
successful compile is not a requirement for generating the
documentation.  The documentation can be built using a Git repository in
conjunction with a locally installed copy of the program.  For more
information, see *note Building documentation without compiling::.

   Attempts to compile LilyPond natively on Windows have been
unsuccessful, though a workaround is available (see *note
(lilypond-contributor)LilyDev::).

1.2 Requirements
================

1.2.1 Requirements for running LilyPond
---------------------------------------

This section contains the list of separate software packages that are
required to run LilyPond.

   • DejaVu fonts (http://www.dejavu-fonts.org/) These are normally
     installed by default.

   • FontConfig (http://www.fontconfig.org/) Use version 2.4.0 or newer.

   • Freetype (http://www.freetype.org/) Use version 2.1.10 or newer.

   • Ghostscript (http://www.ghostscript.com) Use version 8.60 or newer.

   • Guile (http://www.gnu.org/software/guile/guile.html) Use version
     1.8.8.  Version 2.x of Guile is not currently supported.

   • Pango (http://www.pango.org/) User version 1.12 or newer.

   • Python (http://www.python.org) Use version 2.4 or newer.

   • International fonts.  For example:

     Fedora:

          fonts-arabic
          fonts-hebrew
          fonts-ja
          fonts-xorg-truetype
          taipeifonts
          ttfonts-ja
          ttfonts-zh_CN

     Debian based distributions:

          emacs-intl-fonts
          fonts-ipafont-gothic
          fonts-ipafont-mincho
          xfonts-bolkhov-75dpi
          xfonts-cronyx-75dpi
          xfonts-cronyx-100dpi
          xfonts-intl-.*

     These are normally installed by default and are required only to
     create music with international text or lyrics.

1.2.2 Requirements for compiling LilyPond
-----------------------------------------

This section contains instructions on how to quickly and easily get all
the software packages required to build LilyPond.

   Most of the more popular Linux distributions only require a few
simple commands to download all the software needed.  For others, there
is an explicit list of all the individual packages (as well as where to
get them from) for those that are not already included in your
distributions’ own repositories.

Fedora
......

The following instructions were tested on ‘Fedora’ versions 22 & 23 and
will download all the software required to both compile LilyPond and
build the documentation.

   • Download and install all the LilyPond build-dependencies
     (approximately 700MB);

          sudo dnf builddep lilypond --nogpgcheck

   • Download and install additional ‘build’ tools required for
     compiling;

          sudo dnf install autoconf gcc-c++

   • Download ‘texi2html 1.82’ directly from:
     <http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz>;

     ‘texi2html’ is only required if you intend to compile LilyPond’s
     own documentation (e.g.  to help with any document writing).  The
     version available in the Fedora repositories is too new and will
     not work.  Extract the files into an appropriate location and then
     run the commands;

          ./configure
          make
          sudo make install

     This should install ‘texi2html 1.82’ into ‘/usr/local/bin’, which
     will normally take priority over ‘/usr/bin’ where the later,
     pre-installed versions gets put.  Now verify that your operating
     system is able to see the correct version of ‘texi2html’.

          texi2html --version

   • Although not ‘required’ to compile LilyPond, if you intend to
     contribute to LilyPond (codebase or help improve the documentation)
     then it is recommended that you also need to install ‘git’.

          sudo dnf install git

     Also see *note (lilypond-contributor)Starting with Git::.

   • To use the ‘lily-git.tcl’ GUI;

          sudo dnf install tk

     See *note (lilypond-contributor)lily-git::.

          Note: By default, when building LilyPond’s documentation,
          ‘pdfTeX’ is be used.  However ligatures (fi, fl, ff etc.)  may
          not be printed in the PDF output.  In this case XeTeX can be
          used instead.  Download and install the ‘texlive-xetex’
          package.

               sudo dnf install texlive-xetex

          The scripts used to build the LilyPond documentation will use
          ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
          it is available.  No additional configuration is required.

Linux Mint
..........

The following instructions were tested on ‘Linux Mint 17.1’ and ‘LMDE -
Betsy’ and will download all the software required to both compile
LilyPond and build the documentation..

   • Enable the _sources_ repository;

       1. Using the _Software Sources_ GUI (located under
          _Administration_).

       2. Select _Official Repositories_.

       3. Check the _Enable source code repositories_ box under the
          _Source Code_ section.

       4. Click the _Update the cache_ button and when it has completed,
          close the _Software Sources_ GUI.

   • Download and install all the LilyPond build-dependencies
     (approximately 200MB);

          sudo apt-get build-dep lilypond

   • Download and install additional ‘build’ tools required for
     compiling;

          sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic

   • Although not ‘required’ to compile LilyPond, if you intend to
     contribute to LilyPond (codebase or help improve the documentation)
     then it is recommended that you also need to install ‘git’.

          sudo apt-get install git

     Also see *note (lilypond-contributor)Starting with Git::.

   • To use the ‘lily-git.tcl’ GUI;

          sudo apt-get install tk

     Also see *note (lilypond-contributor)lily-git::.

          Note: By default, when building LilyPond’s documentation,
          ‘pdfTeX’ is be used.  However ligatures (fi, fl, ff etc.)  may
          not be printed in the PDF output.  In this case XeTeX can be
          used instead.  Download and install the ‘texlive-xetex’
          package.

               sudo apt-get install texlive-xetex

          The scripts used to build the LilyPond documentation will use
          ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
          it is available.  No additional configuration is required.

OpenSUSE
........

The following instructions were tested on ‘OpenSUSE 13.2’ and will
download all the software required to both compile LilyPond and build
the documentation.

   • Add the _sources_ repository;

          sudo zypper addrepo -f \
          "http://download.opensuse.org/source/distribution/13.2/repo/oss/" sources

   • Download and install all the LilyPond build-dependencies
     (approximately 680MB);

          sudo zypper source-install lilypond

   • Download and install additional ‘build’ tools required for
     compiling;

          sudo zypper install make

   • Although not ‘required’ to compile LilyPond, if you intend to
     contribute to LilyPond (codebase or help improve the documentation)
     then it is recommended that you also need to install ‘git’.

          sudo zypper install git

     Also see *note (lilypond-contributor)Starting with Git::.

   • To use the ‘lily-git.tcl’ GUI;

          sudo zypper install tk

     Also see *note (lilypond-contributor)lily-git::.

          Note: By default, when building LilyPond’s documentation,
          ‘pdfTeX’ is be used.  However ligatures (fi, fl, ff etc.)  may
          not be printed in the PDF output.  In this case XeTeX can be
          used instead.  Download and install the ‘texlive-xetex’
          package.

               sudo zypper install texlive-xetex

          The scripts used to build the LilyPond documentation will use
          ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
          it is available.  No additional configuration is required.

Ubuntu
......

The following commands were tested on Ubuntu versions ‘14.04 LTS’,
‘14.10’ and ‘15.04’ and will download all the software required to both
compile LilyPond and build the documentation.

   • Download and install all the LilyPond build-dependencies
     (approximately 200MB);

          sudo apt-get build-dep lilypond

   • Download and install additional ‘build’ tools required for
     compiling;

          sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic

   • Although not ‘required’ to compile LilyPond, if you intend to
     contribute to LilyPond (codebase or help improve the documentation)
     then it is recommended that you also need to install ‘git’.

          sudo apt-get install git

     Also see *note (lilypond-contributor)Starting with Git::.

   • To use the ‘lily-git.tcl’ GUI;

          sudo apt-get install tk

     Also see *note (lilypond-contributor)lily-git::.

          Note: By default, when building LilyPond’s documentation,
          ‘pdfTeX’ is be used.  However ligatures (fi, fl, ff etc.)  may
          not be printed in the PDF output.  In this case XeTeX can be
          used instead.  Download and install the ‘texlive-xetex’
          package.

               sudo apt-get install texlive-xetex

          The scripts used to build the LilyPond documentation will use
          ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
          it is available.  No additional configuration is required.

Other
.....

The following individual software packages are required just to compile
LilyPond.

   • GNU Autoconf (http://www.gnu.org/software/autoconf)

   • GNU Bison (http://www.gnu.org/software/bison/)

     Use version ‘2.0’ or newer.

   • GNU Compiler Collection (http://gcc.gnu.org/)

     Use version ‘3.4’ or newer (‘4.x’ recommended).

   • Flex (http://flex.sourceforge.net/)

   • FontForge (http://fontforge.sf.net/)

     Use version ‘20060125’ or newer (we recommend using at least
     ‘20100501’); it must also be compiled with the ‘--enable-double’
     switch, else this can lead to inaccurate intersection calculations
     which end up with poorly-rendered glyphs in the output.

   • GNU gettext (http://www.gnu.org/software/gettext/gettext.html)

     Use version ‘0.17’ or newer.

   • GNU Make (http://www.gnu.org/software/make/)

     Use version ‘3.78’ or newer.

   • MetaFont (http://metafont.tutorial.free.fr/)

     The ‘mf-nowin’, ‘mf’, ‘mfw’ or ‘mfont’ binaries are usually
     packaged along with TeX (http://www.latex-project.org/ftp.html).

   • MetaPost (http://cm.bell-labs.com/who/hobby/MetaPost.html)

     The ‘mpost’ binary is also usually packaged with TeX
     (http://www.latex-project.org/ftp.html).

   • Perl (http://www.perl.org/)

   • Texinfo (http://www.gnu.org/software/texinfo/)

     Use version ‘4.11’ or newer.

   • Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)

     Use version ‘1.33’ or newer.

   • Cyrillic fonts (https://www.ctan.org/pkg/cyrillic?lang=en)

     Often packaged in repositories as ‘texlive-lang-cyrillic’.

   • TeX Gyre ‘OTF’ font packages.  As of LilyPond version ‘2.19.26’,
     the previous default serif, san serif and monospace fonts now use
     Tex Gyre’s _Schola_, _Heros_ and _Cursor_ fonts respectively.  Also
     See *note (lilypond-notation)Fonts::.

     Some distributions do not always provide ‘OTF’ font files in the
     Tex Gyre packages from their repositories.  Use the command
     ‘fc-list | grep texgyre’ to list the fonts available to your system
     and check that the appropriate ‘*.otf’ files are reported.  If they
     are not then download and manually extract the ‘OTF’ files to
     either your local ‘~/.fonts/’ directory or use the ‘configure’
     command and the ‘--with-texgyre-dir=/path_to_otf_files/’ option.

     The following font families are required:

     Schola (http://www.gust.org.pl/projects/e-foundry/tex-gyre/schola),
     Heros (http://www.gust.org.pl/projects/e-foundry/tex-gyre/heros)
     and Cursor
     (http://www.gust.org.pl/projects/e-foundry/tex-gyre/cursor).

1.2.3 Requirements for building documentation
---------------------------------------------

The entire set of documentation for the most current build of LilyPond
is available online at
<http://lilypond.org/doc/v2.19/Documentation/web/development>, but you
can also build them locally from the source code.  This process requires
some additional tools and packages.

          Note: If the instructions for one of the previously listed
          Linux in the previous section (*note
          (lilypond-contributor)Requirements for compiling LilyPond::)
          have been used, then the following can be ignored as the
          software should already be installed.

   • Everything listed in *note Requirements for compiling LilyPond::

   • ImageMagick (http://www.imagemagick.org/)

   • Netpbm (http://netpbm.sourceforge.net/)

   • gzip (http://gzip.org/)

   • rsync (http://rsync.samba.org/)

   • Texi2HTML (http://www.nongnu.org/texi2html/)

     Use version ‘1.82’.  Later versions will not work.

     Download ‘texi2html 1.82’ directly from:
     <http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz>;

     Extract the files into an appropriate location and then run the
     commands;

          ./configure
          make
          sudo make install

     Now verify that your operating system is able to see the correct
     version of ‘texi2html’.

          texi2html --version

   • Fonts required to build the documentation in addition to those
     required to run LilyPond:

          gsfonts
          fonts-linuxlibertine
          fonts-liberation
          fonts-dejavu
          fonts-freefont-otf
          ttf-bitstream-vera
          texlive-fonts-recommended
          ttf-xfree86-nonfree

          Note: By default, when building LilyPond’s documentation,
          ‘pdfTeX’ is be used.  However ligatures (fi, fl, ff etc.)  may
          not be printed in the PDF output.  In this case XeTeX can be
          used instead.  Download and install the ‘texlive-xetex’
          package.  The scripts used to build the LilyPond documentation
          will use ‘XeTex’ instead of ‘pdfTex’ to generate the PDF
          documents if it is available.  No additional configuration is
          required.

1.3 Getting the source code
===========================

Downloading the Git repository
------------------------------

In general, developers compile LilyPond from within a local Git
repository.  Setting up a local Git repository is explained in *note
(lilypond-contributor)Starting with Git::.

Downloading a source tarball
----------------------------

Packagers are encouraged to use source tarballs for compiling.

   The tarball for the latest stable release is available on the *note
(lilypond-web)Source:: page.

The latest source code snapshot
(http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot) is also
available as a tarball from the GNU Savannah Git server.

All tagged releases (including legacy stable versions and the most
recent development release) are available here:

     <http://lilypond.org/download/source/>

   Download the tarball to your ‘~/src/’ directory, or some other
appropriate place.

          Note: Be careful where you unpack the tarball!  Any
          subdirectories of the current folder named ‘lilypond/’ or
          ‘lilypond-X.Y.Z/’ (where X.Y.Z is the release number) will be
          overwritten if there is a name clash with the tarball.

   Unpack the tarball with this command:

     tar -xzf lilypond-X.Y.Z.tar.gz

   This creates a subdirectory within the current directory called
‘lilypond-X.Y.Z/’.  Once unpacked, the source files occupy about 40 MB
of disk space.

   Windows users wanting to look at the source code may have to download
and install the free-software 7zip archiver (http://www.7-zip.org) to
extract the tarball.

1.4 Configuring ‘make’
======================

1.4.1 Running ‘./autogen.sh’
----------------------------

After you unpack the tarball (or download the Git repository), the
contents of your top source directory should be similar to the current
source tree listed at
<http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree>.

   Next, you need to create the generated files; enter the following
command from your top source directory:

     ./autogen.sh --noconfigure

   This will generate a number of files and directories to aid
configuration, such as ‘configure’, ‘README.txt’, etc.

   Next, create the build directory with:

     mkdir build/
     cd build/

   We heavily recommend building lilypond inside a separate directory
with this method.

1.4.2 Running ‘../configure’
----------------------------

Configuration options
.....................

          Note: make sure that you are in the ‘build/’ subdirectory of
          your source tree.

   The ‘../configure’ command (generated by ‘./autogen.sh’) provides
many options for configuring ‘make’.  To see them all, run:

     ../configure --help

Checking build dependencies
...........................

          Note: make sure that you are in the ‘build/’ subdirectory of
          your source tree.

   When ‘../configure’ is run without any arguments, it will check to
make sure your system has everything required for compilation:

     ../configure

   If any build dependency is missing, ‘../configure’ will return with:

     ERROR: Please install required programs:  FOO

   The following message is issued if you are missing programs that are
only needed for building the documentation:

     WARNING: Please consider installing optional programs:  BAR

   If you intend to build the documentation locally, you will need to
install or update these programs accordingly.

          Note: ‘../configure’ may fail to issue warnings for certain
          documentation build requirements that are not met.  If you
          experience problems when building the documentation, you may
          need to do a manual check of *note Requirements for building
          documentation::.

Configuring target directories
..............................

          Note: make sure that you are in the ‘build/’ subdirectory of
          your source tree.

   If you intend to use your local build to install a local copy of the
program, you will probably want to configure the installation directory.
Here are the relevant lines taken from the output of
‘../configure --help’:

     By default, ‘‘make install’’ will install all the files in
     ‘/usr/local/bin’, ‘/usr/local/lib’ etc.  You can specify an
     installation prefix other than ‘/usr/local’ using ‘‘--prefix’’, for
     instance ‘‘--prefix=$HOME’’.

   A typical installation prefix is ‘$HOME/usr’:

     ../configure --prefix=$HOME/usr

   Note that if you plan to install a local build on a system where you
do not have root privileges, you will need to do something like this
anyway—‘make install’ will only succeed if the installation prefix
points to a directory where you have write permission (such as your home
directory).  The installation directory will be automatically created if
necessary.

   The location of the ‘lilypond’ command installed by this process will
be ‘PREFIX/bin/lilypond’; you may want to add ‘PREFIX/bin/’ to your
‘$PATH’ if it is not already included.

   It is also possible to specify separate installation directories for
different types of program files.  See the full output of
‘../configure --help’ for more information.

   If you encounter any problems, please see *note Problems::.

1.5 Compiling LilyPond
======================

1.5.1 Using ‘make’
------------------

          Note: make sure that you are in the ‘build/’ subdirectory of
          your source tree.

   LilyPond is compiled with the ‘make’ command.  Assuming ‘make’ is
configured properly, you can simply run:

     make

   ‘make’ is short for ‘make all’.  To view a list of ‘make’ targets,
run:

     make help

   TODO: Describe what ‘make’ actually does.


See also
........

   *note Generating documentation:: provides more info on the ‘make’
targets used to build the LilyPond documentation.

1.5.2 Saving time with the ‘-j’ option
--------------------------------------

If your system has multiple CPUs, you can speed up compilation by adding
‘-jX’ to the ‘make’ command, where ‘X’ is one more than the number of
cores you have.  For example, a typical Core2Duo machine would use:

     make -j3

   If you get errors using the ‘-j’ option, and ‘make’ succeeds without
it, try lowering the ‘X’ value.

   Because multiple jobs run in parallel when ‘-j’ is used, it can be
difficult to determine the source of an error when one occurs.  In that
case, running ‘make’ without the ‘-j’ is advised.

1.5.3 Compiling for multiple platforms
--------------------------------------

If you want to build multiple versions of LilyPond with different
configuration settings, you can use the ‘--enable-config=CONF’ option of
‘configure’.  You should use ‘make conf=CONF’ to generate the output in
‘out-CONF’.  For example, suppose you want to build with and without
profiling, then use the following for the normal build

     ./configure --prefix=$HOME/usr/ --enable-checking
     make

   and for the profiling version, specify a different configuration

     ./configure --prefix=$HOME/usr/ --enable-profiling \
       --enable-config=prof --disable-checking
     make conf=prof

   If you wish to install a copy of the build with profiling, don’t
forget to use ‘conf=CONF’ when issuing ‘make install’:

     make conf=prof install


See also
........

   *note Installing LilyPond from a local build::

1.5.4 Useful ‘make’ variables
-----------------------------

If a less verbose build output if desired, the variable ‘QUIET_BUILD’
may be set to ‘1’ on ‘make’ command line, or in ‘local.make’ at top of
the build tree.

1.6 Post-compilation options
============================

1.6.1 Installing LilyPond from a local build
--------------------------------------------

If you configured ‘make’ to install your local build in a directory
where you normally have write permission (such as your home directory),
and you have compiled LilyPond by running ‘make’, you can install the
program in your target directory by running:

     make install

   If instead, your installation directory is not one that you can
normally write to (such as the default ‘/usr/local/’, which typically is
only writeable by the superuser), you will need to temporarily become
the superuser when running ‘make install’:

     sudo make install

or...

     su -c 'make install'

   If you don’t have superuser privileges, then you need to configure
the installation directory to one that you can write to, and then
re-install.  See *note Configuring target directories::.

1.6.2 Generating documentation
------------------------------

Documentation editor’s edit/compile cycle
.........................................

   • Initial documentation build:

          make [-jX]
          make [-jX CPU_COUNT=X] doc          _## can take an hour or more_
          make [-jX CPU_COUNT=X] doc-stage-1  _## to build only PDF documentation_

   • Edit/compile cycle:

          _## edit source files, then..._

          make [-jX]                  _## needed if editing outside_
                                      _##   Documentation/, but useful anyway_
                                      _##   for finding Texinfo errors._
          make [-jX CPU_COUNT=X] doc  _## usually faster than initial build._

   • Reset:

     It is generally possible to remove the compiled documentation from
     your system with ‘make doc-clean’, but this method is not 100%
     guaranteed.  Instead, if you want to be sure you have a clean
     system, we recommend that you delete your ‘build/’ directory, and
     begin compiling from scratch.  Since the documentation compile
     takes much longer than the non-documentation compile, this does not
     increase the overall time by a great deal.

Building documentation
......................

After a successful compile (using ‘make’), the documentation can be
built by issuing:

     make doc

   or, to build only the PDF documentation and not the HTML,

     make doc-stage-1

          Note: The first time you run ‘make doc’, the process can
          easily take an hour or more with not much output on the
          command line.

   After this initial build, ‘make doc’ only makes changes to the
documentation where needed, so it may only take a minute or two to test
changes if the documentation is already built.

   If ‘make doc’ succeeds, the HTML documentation tree is available in
‘out-www/offline-root/’, and can be browsed locally.  Various portions
of the documentation can be found by looking in ‘out/’ and ‘out-www’
subdirectories in other places in the source tree, but these are only
_portions_ of the docs.  Please do not complain about anything which is
broken in those places; the only complete set of documentation is in
‘out-www/offline-root/’ from the top of the source tree.

   ‘make doc’ sends the output from most of the compilation to logfiles.
If the build fails for any reason, it should prompt you with the name of
a logfile which will provide information to help you work out why the
build failed.  These logfiles are not deleted with ‘make doc-clean’.  To
remove all the logfiles generated by the compilation process, use:

     make log-clean

   ‘make doc’ compiles the documents for all languages.  To save some
compile time, the English language documents can be compiled on their
own with:

     make LANGS='' doc

Similarly, it is possible to compile a subset of the translated
documentation by specifying their language codes on the command line.
For example, the French and German translations are compiled with:

     make LANGS='de fr' doc

Note that this will also compile the English version.

   Compilation of documentation in Info format with images can be done
separately by issuing:

     make info

An issue when switching branches between master and translation is the
appearance/disappearance of translated versions of some manuals.  If you
see such a warning from make:

     No rule to make target `X', needed by `Y'

Your best bet is to delete the file Y.dep and to try again.

Building a single document
..........................

It’s possible to build a single document.  For example, to rebuild only
‘contributor.pdf’, do the following:

     cd build/
     cd Documentation/
     touch ../../Documentation/contributor.texi
     make out=www out-www/contributor.pdf

   If you are only working on a single document, test-building it in
this way can give substantial time savings - recreating
‘contributor.pdf’, for example, takes a matter of seconds.

Saving time with ‘CPU_COUNT’
............................

The most time consuming task for building the documentation is running
LilyPond to build images of music, and there cannot be several
simultaneously running ‘lilypond-book’ instances, so the ‘-j’ ‘make’
option does not significantly speed up the build process.  To help speed
it up, the makefile variable ‘CPU_COUNT’ may be set in ‘local.make’ or
on the command line to the number of ‘.ly’ files that LilyPond should
process simultaneously, e.g.  on a bi-processor or dual core machine:

     make -j3 CPU_COUNT=3 doc

The recommended value of ‘CPU_COUNT’ is one plus the number of cores or
processors, but it is advisable to set it to a smaller value unless your
system has enough RAM to run that many simultaneous LilyPond instances.
Also, values for the ‘-j’ option that pose problems with ‘make’ are less
likely to pose problems with ‘make doc’ (this applies to both ‘-j’ and
‘CPU_COUNT’).  For example, with a quad-core processor, it is possible
for ‘make -j5 CPU_COUNT=5 doc’ to work consistently even if ‘make -j5’
rarely succeeds.

AJAX search
...........

To build the documentation with interactive searching, use:

     make doc AJAX_SEARCH=1

   This requires PHP, and you must view the docs via a http connection
(you cannot view them on your local filesystem).

          Note: Due to potential security or load issues, this option is
          not enabled in the official documentation builds.  Enable at
          your own risk.

Installing documentation
........................

The HTML, PDF and if available Info files can be installed into the
standard documentation path by issuing

     make install-doc

This also installs Info documentation with images if the installation
prefix is properly set; otherwise, instructions to complete proper
installation of Info documentation are printed on standard output.

   To install the Info documentation separately, run:

     make install-info

Note that to get the images in Info documentation, ‘install-doc’ target
creates symbolic links to HTML and PDF installed documentation tree in
‘PREFIX/share/info’, in order to save disk space, whereas ‘install-info’
copies images in ‘PREFIX/share/info’ subdirectories.

   It is possible to build a documentation tree in
‘out-www/online-root/’, with special processing, so it can be used on a
website with content negotiation for automatic language selection; this
can be achieved by issuing

     make WEB_TARGETS=online doc

and both ‘offline’ and ‘online’ targets can be generated by issuing

     make WEB_TARGETS="offline online" doc

   Several targets are available to clean the documentation build and
help with maintaining documentation; an overview of these targets is
available with

     make help

from every directory in the build tree.  Most targets for documentation
maintenance are available from ‘Documentation/’; for more information,
see *note (lilypond-contributor)Documentation work::.

   The makefile variable ‘QUIET_BUILD’ may be set to ‘1’ for a less
verbose build output, just like for building the programs.

Building documentation without compiling
........................................

The documentation can be built locally without compiling LilyPond
binary, if LilyPond is already installed on your system.

   From a fresh Git checkout, do

     ./autogen.sh   # ignore any warning messages
     cp GNUmakefile.in GNUmakefile
     make -C scripts && make -C python
     nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc

   Please note that this may break sometimes – for example, if a new
feature is added with a test file in input/regression, even the latest
development release of LilyPond will fail to build the docs.

   You may build the manual without building all the ‘input/*’ stuff
(i.e.  mostly regression tests): change directory, for example to
‘Documentation/’, issue ‘make doc’, which will build documentation in a
subdirectory ‘out-www’ from the source files in current directory.  In
this case, if you also want to browse the documentation in its
post-processed form, change back to top directory and issue

     make out=www WWW-post


Known issues and warnings
.........................

You may also need to create a script for ‘pngtopnm’ and ‘pnmtopng’.  On
GNU/Linux, I use this:

export LD_LIBRARY_PATH=/usr/lib
exec /usr/bin/pngtopnm "$@"

   On MacOS X with fink, I use this:

export DYLD_LIBRARY_PATH=/sw/lib
exec /sw/bin/pngtopnm "$@"

   On MacOS X with macports, you should use this:

export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
exec /opt/local/bin/pngtopnm "$@"

1.6.3 Testing LilyPond binary
-----------------------------

LilyPond comes with an extensive suite that exercises the entire
program.  This suite can be used to test that the binary has been built
correctly.

   The test suite can be executed with:

make test

   If the test suite completes successfully, the LilyPond binary has
been verified.

   More information on the regression test suite is found at *note
(lilypond-contributor)Regression tests::.

1.7 Problems
============

For help and questions use <lilypond-user@gnu.org>.  Send bug reports to
<bug-lilypond@gnu.org>.

   Bugs that are not fault of LilyPond are documented here.

Compiling on MacOS X
--------------------

Here are special instructions for compiling under MacOS X. These
instructions assume that dependencies are installed using MacPorts.
(http://www.macports.org/) The instructions have been tested using OS X
10.5 (Leopard).

   First, install the relevant dependencies using MacPorts.

   Next, add the following to your relevant shell initialization files.
This is ‘~/.profile’ by default.  You should create this file if it does
not exist.

     export PATH=/opt/local/bin:/opt/local/sbin:$PATH
     export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH

   Now you must edit the generated ‘config.make’ file.  Change

     FLEXLEXER_FILE = /usr/include/FlexLexer.h

to:

     FLEXLEXER_FILE = /opt/local/include/FlexLexer.h

   At this point, you should verify that you have the appropriate fonts
installed with your ghostscript installation.  Check ‘ls
/opt/local/share/ghostscript/fonts’ for: ’c0590*’ files (.pfb, .pfb and
.afm).  If you don’t have them, run the following commands to grab them
from the ghostscript SVN server and install them in the appropriate
location:

     svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
     sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
     rm -rf urw-fonts-1.07pre44

   Now run the ‘./configure’ script.  To avoid complications with
automatic font detection, add

     --with-fonts-dir=/opt/local/share/ghostscript/fonts

Solaris
-------

Solaris7, ./configure

   ‘./configure’ needs a POSIX compliant shell.  On Solaris7, ‘/bin/sh’
is not yet POSIX compliant, but ‘/bin/ksh’ or bash is.  Run configure
like

     CONFIG_SHELL=/bin/ksh ksh -c ./configure

or

     CONFIG_SHELL=/bin/bash bash -c ./configure

FreeBSD
-------

To use system fonts, dejaview must be installed.  With the default port,
the fonts are installed in ‘usr/X11R6/lib/X11/fonts/dejavu’.

   Open the file ‘$LILYPONDBASE/usr/etc/fonts/local.conf’ and add the
following line just after the ‘<fontconfig>’ line.  (Adjust as necessary
for your hierarchy.)

     <dir>/usr/X11R6/lib/X11/fonts</dir>

International fonts
-------------------

On Mac OS X, all fonts are installed by default.  However, finding all
system fonts requires a bit of configuration; see this post
(http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
on the ‘lilypond-user’ mailing list.

   On Linux, international fonts are installed by different means on
every distribution.  We cannot list the exact commands or packages that
are necessary, as each distribution is different, and the exact package
names within each distribution changes.  Here are some hints, though:

Red Hat Fedora

    taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
         ttfonts-zh_CN fonts-ja fonts-hebrew

Debian GNU/Linux

   apt-get install emacs-intl-fonts xfonts-intl-.* \
        fonts-ipafont-gothic  fonts-ipafont-mincho \
        xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi

Using lilypond python libraries
-------------------------------

If you want to use lilypond’s python libraries (either running certain
build scripts manually, or using them in other programs), set
‘PYTHONPATH’ to ‘python/out’ in your build directory, or
‘.../usr/lib/lilypond/current/python’ in the installation directory
structure.

1.8 Concurrent stable and development versions
==============================================

It can be useful to have both the stable and the development versions of
LilyPond available at once.  One way to do this on GNU/Linux is to
install the stable version using the precompiled binary, and run the
development version from the source tree.  After running ‘make all’ from
the top directory of the LilyPond source files, there will be a binary
called ‘lilypond’ in the ‘out’ directory:

     <PATH TO>/lilypond/out/bin/lilypond

   This binary can be run without actually doing the ‘make install’
command.  The advantage to this is that you can have all of the latest
changes available after pulling from git and running ‘make all’, without
having to uninstall the old version and reinstall the new.

   So, to use the stable version, install it as usual and use the normal
commands:

     lilypond foobar.ly

   To use the development version, create a link to the binary in the
source tree by saving the following line in a file somewhere in your
‘$PATH’:

     exec <PATH TO>/lilypond/out/bin/lilypond "$@"

   Save it as ‘Lilypond’ (with a capital L to distinguish it from the
stable ‘lilypond’), and make it executable:

     chmod +x Lilypond

   Then you can invoke the development version this way:

     Lilypond foobar.ly

   TODO: ADD

   - other compilation tricks for developers

1.9 Build system
================

We currently use make and stepmake, which is complicated and only used
by us.  Hopefully this will change in the future.

Version-specific texinfo macros
-------------------------------

   • made with ‘scripts/build/create-version-itexi.py’ and
     ‘scripts/build/create-weblinks-itexi.py’

   • used extensively in the ‘WEBSITE_ONLY_BUILD’ version of the website
     (made with ‘website.make’, used on lilypond.org)

   • not (?)  used in the main docs?

   • the numbers in VERSION file: MINOR_VERSION should be 1 more than
     the last release, VERSION_DEVEL should be the last *online*
     release.  Yes, VERSION_DEVEL is less than VERSION.