INSTALL.txt

   1 INSTALL - compiling and installing GNU LilyPond
   2 ***********************************************
   3
   4
   5 1 Compilation
   6   1.1 Overview of compiling
   7   1.2 Requirements
   8     1.2.1 Requirements for running LilyPond
   9     1.2.2 Requirements for compiling LilyPond
  10       Fedora
  11       Linux Mint
  12       OpenSUSE
  13       Ubuntu
  14       Other
  15     1.2.3 Requirements for building documentation
  16   1.3 Getting the source code
  17   1.4 Configuring ‘make’
  18     1.4.1 Running ‘./autogen.sh’
  19     1.4.2 Running ‘../configure’
  20       Configuration options
  21       Checking build dependencies
  22       Configuring target directories
  23   1.5 Compiling LilyPond
  24     1.5.1 Using ‘make’
  25     1.5.2 Saving time with the ‘-j’ option
  26     1.5.3 Compiling for multiple platforms
  27     1.5.4 Useful ‘make’ variables
  28   1.6 Post-compilation options
  29     1.6.1 Installing LilyPond from a local build
  30     1.6.2 Generating documentation
  31       Documentation editor’s edit/compile cycle
  32       Building documentation
  33       Building a single document
  34       Saving time with ‘CPU_COUNT’
  35       AJAX search
  36       Installing documentation
  37       Building documentation without compiling
  38     1.6.3 Testing LilyPond binary
  39   1.7 Problems
  40     Compiling on MacOS X
  41     Solaris
  42     FreeBSD
  43     International fonts
  44     Using lilypond python libraries
  45   1.8 Concurrent stable and development versions
  46   1.9 Build system
  47 1 Compilation
  48 *************
  49
  50 1.1 Overview of compiling
  51 =========================
  52
  53 Compiling LilyPond from source is an involved process, and is only
  54 recommended for developers and packagers.  Typical program users are
  55 instead encouraged to obtain the program from a package manager (on
  56 Unix) or by downloading a precompiled binary configured for a specific
  57 operating system.  Pre-compiled binaries are available on the *note
  58 (lilypond-web)Download:: page.
  59
  60    Compiling LilyPond from source is necessary if you want to build,
  61 install, or test your own version of the program.
  62
  63    A successful compile can also be used to generate and install the
  64 documentation, incorporating any changes you may have made.  However, a
  65 successful compile is not a requirement for generating the
  66 documentation.  The documentation can be built using a Git repository in
  67 conjunction with a locally installed copy of the program.  For more
  68 information, see *note Building documentation without compiling::.
  69
  70    Attempts to compile LilyPond natively on Windows have been
  71 unsuccessful, though a workaround is available (see *note
  72 (lilypond-contributor)LilyDev::).
  73
  74 1.2 Requirements
  75 ================
  76
  77 1.2.1 Requirements for running LilyPond
  78 ---------------------------------------
  79
  80 This section contains the list of separate software packages that are
  81 required to run LilyPond.
  82
  83    • DejaVu fonts (http://www.dejavu-fonts.org/) These are normally
  84      installed by default.
  85
  86    • FontConfig (http://www.fontconfig.org/) Use version 2.4.0 or newer.
  87
  88    • Freetype (http://www.freetype.org/) Use version 2.1.10 or newer.
  89
  90    • Ghostscript (http://www.ghostscript.com) Use version 8.60 or newer.
  91
  92    • Guile (http://www.gnu.org/software/guile/guile.html) Use version
  93      1.8.8.  Version 2.x of Guile is not currently supported.
  94
  95    • Pango (http://www.pango.org/) User version 1.12 or newer.
  96
  97    • Python (http://www.python.org) Use version 2.4 or newer.
  98
  99    • International fonts.  For example:
 100
 101      Fedora:
 102
 103           fonts-arabic
 104           fonts-hebrew
 105           fonts-ja
 106           fonts-xorg-truetype
 107           taipeifonts
 108           ttfonts-ja
 109           ttfonts-zh_CN
 110
 111      Debian based distributions:
 112
 113           emacs-intl-fonts
 114           fonts-ipafont-gothic
 115           fonts-ipafont-mincho
 116           xfonts-bolkhov-75dpi
 117           xfonts-cronyx-75dpi
 118           xfonts-cronyx-100dpi
 119           xfonts-intl-.*
 120
 121      These are normally installed by default and are required only to
 122      create music with international text or lyrics.
 123
 124 1.2.2 Requirements for compiling LilyPond
 125 -----------------------------------------
 126
 127 This section contains instructions on how to quickly and easily get all
 128 the software packages required to build LilyPond.
 129
 130    Most of the more popular Linux distributions only require a few
 131 simple commands to download all the software needed.  For others, there
 132 is an explicit list of all the individual packages (as well as where to
 133 get them from) for those that are not already included in your
 134 distributions’ own repositories.
 135
 136 Fedora
 137 ......
 138
 139 The following instructions were tested on ‘Fedora’ versions 22 & 23 and
 140 will download all the software required to both compile LilyPond and
 141 build the documentation.
 142
 143    • Download and install all the LilyPond build-dependencies
 144      (approximately 700MB);
 145
 146           sudo dnf builddep lilypond --nogpgcheck
 147
 148    • Download and install additional ‘build’ tools required for
 149      compiling;
 150
 151           sudo dnf install autoconf gcc-c++
 152
 153    • Download ‘texi2html 1.82’ directly from:
 154      <http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz>;
 155
 156      ‘texi2html’ is only required if you intend to compile LilyPond’s
 157      own documentation (e.g.  to help with any document writing).  The
 158      version available in the Fedora repositories is too new and will
 159      not work.  Extract the files into an appropriate location and then
 160      run the commands;
 161
 162           ./configure
 163           make
 164           sudo make install
 165
 166      This should install ‘texi2html 1.82’ into ‘/usr/local/bin’, which
 167      will normally take priority over ‘/usr/bin’ where the later,
 168      pre-installed versions gets put.  Now verify that your operating
 169      system is able to see the correct version of ‘texi2html’.
 170
 171           texi2html --version
 172
 173    • Although not ‘required’ to compile LilyPond, if you intend to
 174      contribute to LilyPond (codebase or help improve the documentation)
 175      then it is recommended that you also need to install ‘git’.
 176
 177           sudo dnf install git
 178
 179      Also see *note (lilypond-contributor)Starting with Git::.
 180
 181    • To use the ‘lily-git.tcl’ GUI;
 182
 183           sudo dnf install tk
 184
 185      See *note (lilypond-contributor)lily-git::.
 186
 187           Note: By default, when building LilyPond’s documentation,
 188           ‘pdfTeX’ is be used.  However ligatures (fi, fl, ff etc.)  may
 189           not be printed in the PDF output.  In this case XeTeX can be
 190           used instead.  Download and install the ‘texlive-xetex’
 191           package.
 192
 193                sudo dnf install texlive-xetex
 194
 195           The scripts used to build the LilyPond documentation will use
 196           ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
 197           it is available.  No additional configuration is required.
 198
 199 Linux Mint
 200 ..........
 201
 202 The following instructions were tested on ‘Linux Mint 17.1’ and ‘LMDE -
 203 Betsy’ and will download all the software required to both compile
 204 LilyPond and build the documentation..
 205
 206    • Enable the _sources_ repository;
 207
 208        1. Using the _Software Sources_ GUI (located under
 209           _Administration_).
 210
 211        2. Select _Official Repositories_.
 212
 213        3. Check the _Enable source code repositories_ box under the
 214           _Source Code_ section.
 215
 216        4. Click the _Update the cache_ button and when it has completed,
 217           close the _Software Sources_ GUI.
 218
 219    • Download and install all the LilyPond build-dependencies
 220      (approximately 200MB);
 221
 222           sudo apt-get build-dep lilypond
 223
 224    • Download and install additional ‘build’ tools required for
 225      compiling;
 226
 227           sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
 228
 229    • Although not ‘required’ to compile LilyPond, if you intend to
 230      contribute to LilyPond (codebase or help improve the documentation)
 231      then it is recommended that you also need to install ‘git’.
 232
 233           sudo apt-get install git
 234
 235      Also see *note (lilypond-contributor)Starting with Git::.
 236
 237    • To use the ‘lily-git.tcl’ GUI;
 238
 239           sudo apt-get install tk
 240
 241      Also see *note (lilypond-contributor)lily-git::.
 242
 243           Note: By default, when building LilyPond’s documentation,
 244           ‘pdfTeX’ is be used.  However ligatures (fi, fl, ff etc.)  may
 245           not be printed in the PDF output.  In this case XeTeX can be
 246           used instead.  Download and install the ‘texlive-xetex’
 247           package.
 248
 249                sudo apt-get install texlive-xetex
 250
 251           The scripts used to build the LilyPond documentation will use
 252           ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
 253           it is available.  No additional configuration is required.
 254
 255 OpenSUSE
 256 ........
 257
 258 The following instructions were tested on ‘OpenSUSE 13.2’ and will
 259 download all the software required to both compile LilyPond and build
 260 the documentation.
 261
 262    • Add the _sources_ repository;
 263
 264           sudo zypper addrepo -f \
 265           "http://download.opensuse.org/source/distribution/13.2/repo/oss/" sources
 266
 267    • Download and install all the LilyPond build-dependencies
 268      (approximately 680MB);
 269
 270           sudo zypper source-install lilypond
 271
 272    • Download and install additional ‘build’ tools required for
 273      compiling;
 274
 275           sudo zypper install make
 276
 277    • Although not ‘required’ to compile LilyPond, if you intend to
 278      contribute to LilyPond (codebase or help improve the documentation)
 279      then it is recommended that you also need to install ‘git’.
 280
 281           sudo zypper install git
 282
 283      Also see *note (lilypond-contributor)Starting with Git::.
 284
 285    • To use the ‘lily-git.tcl’ GUI;
 286
 287           sudo zypper install tk
 288
 289      Also see *note (lilypond-contributor)lily-git::.
 290
 291           Note: By default, when building LilyPond’s documentation,
 292           ‘pdfTeX’ is be used.  However ligatures (fi, fl, ff etc.)  may
 293           not be printed in the PDF output.  In this case XeTeX can be
 294           used instead.  Download and install the ‘texlive-xetex’
 295           package.
 296
 297                sudo zypper install texlive-xetex
 298
 299           The scripts used to build the LilyPond documentation will use
 300           ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
 301           it is available.  No additional configuration is required.
 302
 303 Ubuntu
 304 ......
 305
 306 The following commands were tested on Ubuntu versions ‘14.04 LTS’,
 307 ‘14.10’ and ‘15.04’ and will download all the software required to both
 308 compile LilyPond and build the documentation.
 309
 310    • Download and install all the LilyPond build-dependencies
 311      (approximately 200MB);
 312
 313           sudo apt-get build-dep lilypond
 314
 315    • Download and install additional ‘build’ tools required for
 316      compiling;
 317
 318           sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
 319
 320    • Although not ‘required’ to compile LilyPond, if you intend to
 321      contribute to LilyPond (codebase or help improve the documentation)
 322      then it is recommended that you also need to install ‘git’.
 323
 324           sudo apt-get install git
 325
 326      Also see *note (lilypond-contributor)Starting with Git::.
 327
 328    • To use the ‘lily-git.tcl’ GUI;
 329
 330           sudo apt-get install tk
 331
 332      Also see *note (lilypond-contributor)lily-git::.
 333
 334           Note: By default, when building LilyPond’s documentation,
 335           ‘pdfTeX’ is be used.  However ligatures (fi, fl, ff etc.)  may
 336           not be printed in the PDF output.  In this case XeTeX can be
 337           used instead.  Download and install the ‘texlive-xetex’
 338           package.
 339
 340                sudo apt-get install texlive-xetex
 341
 342           The scripts used to build the LilyPond documentation will use
 343           ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
 344           it is available.  No additional configuration is required.
 345
 346 Other
 347 .....
 348
 349 The following individual software packages are required just to compile
 350 LilyPond.
 351
 352    • GNU Autoconf (http://www.gnu.org/software/autoconf)
 353
 354    • GNU Bison (http://www.gnu.org/software/bison/)
 355
 356      Use version ‘2.0’ or newer.
 357
 358    • GNU Compiler Collection (http://gcc.gnu.org/)
 359
 360      Use version ‘3.4’ or newer (‘4.x’ recommended).
 361
 362    • Flex (http://flex.sourceforge.net/)
 363
 364    • FontForge (http://fontforge.sf.net/)
 365
 366      Use version ‘20060125’ or newer (we recommend using at least
 367      ‘20100501’); it must also be compiled with the ‘--enable-double’
 368      switch, else this can lead to inaccurate intersection calculations
 369      which end up with poorly-rendered glyphs in the output.
 370
 371    • GNU gettext (http://www.gnu.org/software/gettext/gettext.html)
 372
 373      Use version ‘0.17’ or newer.
 374
 375    • GNU Make (http://www.gnu.org/software/make/)
 376
 377      Use version ‘3.78’ or newer.
 378
 379    • MetaFont (http://metafont.tutorial.free.fr/)
 380
 381      The ‘mf-nowin’, ‘mf’, ‘mfw’ or ‘mfont’ binaries are usually
 382      packaged along with TeX (http://www.latex-project.org/ftp.html).
 383
 384    • MetaPost (http://cm.bell-labs.com/who/hobby/MetaPost.html)
 385
 386      The ‘mpost’ binary is also usually packaged with TeX
 387      (http://www.latex-project.org/ftp.html).
 388
 389    • Perl (http://www.perl.org/)
 390
 391    • Texinfo (http://www.gnu.org/software/texinfo/)
 392
 393      Use version ‘4.11’ or newer.
 394
 395    • Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)
 396
 397      Use version ‘1.33’ or newer.
 398
 399    • Cyrillic fonts (https://www.ctan.org/pkg/cyrillic?lang=en)
 400
 401      Often packaged in repositories as ‘texlive-lang-cyrillic’.
 402
 403    • TeX Gyre ‘OTF’ font packages.  As of LilyPond version ‘2.19.26’,
 404      the previous default serif, san serif and monospace fonts now use
 405      Tex Gyre’s _Schola_, _Heros_ and _Cursor_ fonts respectively.  Also
 406      See *note (lilypond-notation)Fonts::.
 407
 408      Some distributions do not always provide ‘OTF’ font files in the
 409      Tex Gyre packages from their repositories.  Use the command
 410      ‘fc-list | grep texgyre’ to list the fonts available to your system
 411      and check that the appropriate ‘*.otf’ files are reported.  If they
 412      are not then download and manually extract the ‘OTF’ files to
 413      either your local ‘~/.fonts/’ directory or use the ‘configure’
 414      command and the ‘--with-texgyre-dir=/path_to_otf_files/’ option.
 415
 416      The following font families are required:
 417
 418      Schola (http://www.gust.org.pl/projects/e-foundry/tex-gyre/schola),
 419      Heros (http://www.gust.org.pl/projects/e-foundry/tex-gyre/heros)
 420      and Cursor
 421      (http://www.gust.org.pl/projects/e-foundry/tex-gyre/cursor).
 422
 423 1.2.3 Requirements for building documentation
 424 ---------------------------------------------
 425
 426 The entire set of documentation for the most current build of LilyPond
 427 is available online at
 428 <http://lilypond.org/doc/v2.19/Documentation/web/development>, but you
 429 can also build them locally from the source code.  This process requires
 430 some additional tools and packages.
 431
 432           Note: If the instructions for one of the previously listed
 433           Linux in the previous section (*note
 434           (lilypond-contributor)Requirements for compiling LilyPond::)
 435           have been used, then the following can be ignored as the
 436           software should already be installed.
 437
 438    • Everything listed in *note Requirements for compiling LilyPond::
 439
 440    • ImageMagick (http://www.imagemagick.org/)
 441
 442    • Netpbm (http://netpbm.sourceforge.net/)
 443
 444    • gzip (http://gzip.org/)
 445
 446    • rsync (http://rsync.samba.org/)
 447
 448    • Texi2HTML (http://www.nongnu.org/texi2html/)
 449
 450      Use version ‘1.82’.  Later versions will not work.
 451
 452      Download ‘texi2html 1.82’ directly from:
 453      <http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz>;
 454
 455      Extract the files into an appropriate location and then run the
 456      commands;
 457
 458           ./configure
 459           make
 460           sudo make install
 461
 462      Now verify that your operating system is able to see the correct
 463      version of ‘texi2html’.
 464
 465           texi2html --version
 466
 467    • Fonts required to build the documentation in addition to those
 468      required to run LilyPond:
 469
 470           gsfonts
 471           fonts-linuxlibertine
 472           fonts-liberation
 473           fonts-dejavu
 474           fonts-freefont-otf
 475           ttf-bitstream-vera
 476           texlive-fonts-recommended
 477           ttf-xfree86-nonfree
 478
 479           Note: By default, when building LilyPond’s documentation,
 480           ‘pdfTeX’ is be used.  However ligatures (fi, fl, ff etc.)  may
 481           not be printed in the PDF output.  In this case XeTeX can be
 482           used instead.  Download and install the ‘texlive-xetex’
 483           package.  The scripts used to build the LilyPond documentation
 484           will use ‘XeTex’ instead of ‘pdfTex’ to generate the PDF
 485           documents if it is available.  No additional configuration is
 486           required.
 487
 488 1.3 Getting the source code
 489 ===========================
 490
 491 Downloading the Git repository
 492 ------------------------------
 493
 494 In general, developers compile LilyPond from within a local Git
 495 repository.  Setting up a local Git repository is explained in *note
 496 (lilypond-contributor)Starting with Git::.
 497
 498 Downloading a source tarball
 499 ----------------------------
 500
 501 Packagers are encouraged to use source tarballs for compiling.
 502
 503    The tarball for the latest stable release is available on the *note
 504 (lilypond-web)Source:: page.
 505
 506 The latest source code snapshot
 507 (http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot) is also
 508 available as a tarball from the GNU Savannah Git server.
 509
 510 All tagged releases (including legacy stable versions and the most
 511 recent development release) are available here:
 512
 513      <http://download.linuxaudio.org/lilypond/source/>
 514
 515    Download the tarball to your ‘~/src/’ directory, or some other
 516 appropriate place.
 517
 518           Note: Be careful where you unpack the tarball!  Any
 519           subdirectories of the current folder named ‘lilypond/’ or
 520           ‘lilypond-X.Y.Z/’ (where X.Y.Z is the release number) will be
 521           overwritten if there is a name clash with the tarball.
 522
 523    Unpack the tarball with this command:
 524
 525      tar -xzf lilypond-X.Y.Z.tar.gz
 526
 527    This creates a subdirectory within the current directory called
 528 ‘lilypond-X.Y.Z/’.  Once unpacked, the source files occupy about 40 MB
 529 of disk space.
 530
 531    Windows users wanting to look at the source code may have to download
 532 and install the free-software 7zip archiver (http://www.7-zip.org) to
 533 extract the tarball.
 534
 535 1.4 Configuring ‘make’
 536 ======================
 537
 538 1.4.1 Running ‘./autogen.sh’
 539 ----------------------------
 540
 541 After you unpack the tarball (or download the Git repository), the
 542 contents of your top source directory should be similar to the current
 543 source tree listed at
 544 <http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree>.
 545
 546    Next, you need to create the generated files; enter the following
 547 command from your top source directory:
 548
 549      ./autogen.sh --noconfigure
 550
 551    This will generate a number of files and directories to aid
 552 configuration, such as ‘configure’, ‘README.txt’, etc.
 553
 554    Next, create the build directory with:
 555
 556      mkdir build/
 557      cd build/
 558
 559    We heavily recommend building lilypond inside a separate directory
 560 with this method.
 561
 562 1.4.2 Running ‘../configure’
 563 ----------------------------
 564
 565 Configuration options
 566 .....................
 567
 568           Note: make sure that you are in the ‘build/’ subdirectory of
 569           your source tree.
 570
 571    The ‘../configure’ command (generated by ‘./autogen.sh’) provides
 572 many options for configuring ‘make’.  To see them all, run:
 573
 574      ../configure --help
 575
 576 Checking build dependencies
 577 ...........................
 578
 579           Note: make sure that you are in the ‘build/’ subdirectory of
 580           your source tree.
 581
 582    When ‘../configure’ is run without any arguments, it will check to
 583 make sure your system has everything required for compilation:
 584
 585      ../configure
 586
 587    If any build dependency is missing, ‘../configure’ will return with:
 588
 589      ERROR: Please install required programs:  FOO
 590
 591    The following message is issued if you are missing programs that are
 592 only needed for building the documentation:
 593
 594      WARNING: Please consider installing optional programs:  BAR
 595
 596    If you intend to build the documentation locally, you will need to
 597 install or update these programs accordingly.
 598
 599           Note: ‘../configure’ may fail to issue warnings for certain
 600           documentation build requirements that are not met.  If you
 601           experience problems when building the documentation, you may
 602           need to do a manual check of *note Requirements for building
 603           documentation::.
 604
 605 Configuring target directories
 606 ..............................
 607
 608           Note: make sure that you are in the ‘build/’ subdirectory of
 609           your source tree.
 610
 611    If you intend to use your local build to install a local copy of the
 612 program, you will probably want to configure the installation directory.
 613 Here are the relevant lines taken from the output of
 614 ‘../configure --help’:
 615
 616      By default, ‘‘make install’’ will install all the files in
 617      ‘/usr/local/bin’, ‘/usr/local/lib’ etc.  You can specify an
 618      installation prefix other than ‘/usr/local’ using ‘‘--prefix’’, for
 619      instance ‘‘--prefix=$HOME’’.
 620
 621    A typical installation prefix is ‘$HOME/usr’:
 622
 623      ../configure --prefix=$HOME/usr
 624
 625    Note that if you plan to install a local build on a system where you
 626 do not have root privileges, you will need to do something like this
 627 anyway—‘make install’ will only succeed if the installation prefix
 628 points to a directory where you have write permission (such as your home
 629 directory).  The installation directory will be automatically created if
 630 necessary.
 631
 632    The location of the ‘lilypond’ command installed by this process will
 633 be ‘PREFIX/bin/lilypond’; you may want to add ‘PREFIX/bin/’ to your
 634 ‘$PATH’ if it is not already included.
 635
 636    It is also possible to specify separate installation directories for
 637 different types of program files.  See the full output of
 638 ‘../configure --help’ for more information.
 639
 640    If you encounter any problems, please see *note Problems::.
 641
 642 1.5 Compiling LilyPond
 643 ======================
 644
 645 1.5.1 Using ‘make’
 646 ------------------
 647
 648           Note: make sure that you are in the ‘build/’ subdirectory of
 649           your source tree.
 650
 651    LilyPond is compiled with the ‘make’ command.  Assuming ‘make’ is
 652 configured properly, you can simply run:
 653
 654      make
 655
 656    ‘make’ is short for ‘make all’.  To view a list of ‘make’ targets,
 657 run:
 658
 659      make help
 660
 661    TODO: Describe what ‘make’ actually does.
 662
 663
 664 See also
 665 ........
 666
 667    *note Generating documentation:: provides more info on the ‘make’
 668 targets used to build the LilyPond documentation.
 669
 670 1.5.2 Saving time with the ‘-j’ option
 671 --------------------------------------
 672
 673 If your system has multiple CPUs, you can speed up compilation by adding
 674 ‘-jX’ to the ‘make’ command, where ‘X’ is one more than the number of
 675 cores you have.  For example, a typical Core2Duo machine would use:
 676
 677      make -j3
 678
 679    If you get errors using the ‘-j’ option, and ‘make’ succeeds without
 680 it, try lowering the ‘X’ value.
 681
 682    Because multiple jobs run in parallel when ‘-j’ is used, it can be
 683 difficult to determine the source of an error when one occurs.  In that
 684 case, running ‘make’ without the ‘-j’ is advised.
 685
 686 1.5.3 Compiling for multiple platforms
 687 --------------------------------------
 688
 689 If you want to build multiple versions of LilyPond with different
 690 configuration settings, you can use the ‘--enable-config=CONF’ option of
 691 ‘configure’.  You should use ‘make conf=CONF’ to generate the output in
 692 ‘out-CONF’.  For example, suppose you want to build with and without
 693 profiling, then use the following for the normal build
 694
 695      ./configure --prefix=$HOME/usr/ --enable-checking
 696      make
 697
 698    and for the profiling version, specify a different configuration
 699
 700      ./configure --prefix=$HOME/usr/ --enable-profiling \
 701        --enable-config=prof --disable-checking
 702      make conf=prof
 703
 704    If you wish to install a copy of the build with profiling, don’t
 705 forget to use ‘conf=CONF’ when issuing ‘make install’:
 706
 707      make conf=prof install
 708
 709
 710 See also
 711 ........
 712
 713    *note Installing LilyPond from a local build::
 714
 715 1.5.4 Useful ‘make’ variables
 716 -----------------------------
 717
 718 If a less verbose build output if desired, the variable ‘QUIET_BUILD’
 719 may be set to ‘1’ on ‘make’ command line, or in ‘local.make’ at top of
 720 the build tree.
 721
 722 1.6 Post-compilation options
 723 ============================
 724
 725 1.6.1 Installing LilyPond from a local build
 726 --------------------------------------------
 727
 728 If you configured ‘make’ to install your local build in a directory
 729 where you normally have write permission (such as your home directory),
 730 and you have compiled LilyPond by running ‘make’, you can install the
 731 program in your target directory by running:
 732
 733      make install
 734
 735    If instead, your installation directory is not one that you can
 736 normally write to (such as the default ‘/usr/local/’, which typically is
 737 only writeable by the superuser), you will need to temporarily become
 738 the superuser when running ‘make install’:
 739
 740      sudo make install
 741
 742 or...
 743
 744      su -c 'make install'
 745
 746    If you don’t have superuser privileges, then you need to configure
 747 the installation directory to one that you can write to, and then
 748 re-install.  See *note Configuring target directories::.
 749
 750 1.6.2 Generating documentation
 751 ------------------------------
 752
 753 Documentation editor’s edit/compile cycle
 754 .........................................
 755
 756    • Initial documentation build:
 757
 758           make [-jX]
 759           make [-jX CPU_COUNT=X] doc          _## can take an hour or more_
 760           make [-jX CPU_COUNT=X] doc-stage-1  _## to build only PDF documentation_
 761
 762    • Edit/compile cycle:
 763
 764           _## edit source files, then..._
 765
 766           make [-jX]                  _## needed if editing outside_
 767                                       _##   Documentation/, but useful anyway_
 768                                       _##   for finding Texinfo errors._
 769           make [-jX CPU_COUNT=X] doc  _## usually faster than initial build._
 770
 771    • Reset:
 772
 773      It is generally possible to remove the compiled documentation from
 774      your system with ‘make doc-clean’, but this method is not 100%
 775      guaranteed.  Instead, if you want to be sure you have a clean
 776      system, we recommend that you delete your ‘build/’ directory, and
 777      begin compiling from scratch.  Since the documentation compile
 778      takes much longer than the non-documentation compile, this does not
 779      increase the overall time by a great deal.
 780
 781 Building documentation
 782 ......................
 783
 784 After a successful compile (using ‘make’), the documentation can be
 785 built by issuing:
 786
 787      make doc
 788
 789    or, to build only the PDF documentation and not the HTML,
 790
 791      make doc-stage-1
 792
 793           Note: The first time you run ‘make doc’, the process can
 794           easily take an hour or more with not much output on the
 795           command line.
 796
 797    After this initial build, ‘make doc’ only makes changes to the
 798 documentation where needed, so it may only take a minute or two to test
 799 changes if the documentation is already built.
 800
 801    If ‘make doc’ succeeds, the HTML documentation tree is available in
 802 ‘out-www/offline-root/’, and can be browsed locally.  Various portions
 803 of the documentation can be found by looking in ‘out/’ and ‘out-www’
 804 subdirectories in other places in the source tree, but these are only
 805 _portions_ of the docs.  Please do not complain about anything which is
 806 broken in those places; the only complete set of documentation is in
 807 ‘out-www/offline-root/’ from the top of the source tree.
 808
 809    ‘make doc’ sends the output from most of the compilation to logfiles.
 810 If the build fails for any reason, it should prompt you with the name of
 811 a logfile which will provide information to help you work out why the
 812 build failed.  These logfiles are not deleted with ‘make doc-clean’.  To
 813 remove all the logfiles generated by the compilation process, use:
 814
 815      make log-clean
 816
 817    ‘make doc’ compiles the documents for all languages.  To save some
 818 compile time, the English language documents can be compiled on their
 819 own with:
 820
 821      make LANGS='' doc
 822
 823 Similarly, it is possible to compile a subset of the translated
 824 documentation by specifying their language codes on the command line.
 825 For example, the French and German translations are compiled with:
 826
 827      make LANGS='de fr' doc
 828
 829 Note that this will also compile the English version.
 830
 831    Compilation of documentation in Info format with images can be done
 832 separately by issuing:
 833
 834      make info
 835
 836 An issue when switching branches between master and translation is the
 837 appearance/disappearance of translated versions of some manuals.  If you
 838 see such a warning from make:
 839
 840      No rule to make target `X', needed by `Y'
 841
 842 Your best bet is to delete the file Y.dep and to try again.
 843
 844 Building a single document
 845 ..........................
 846
 847 It’s possible to build a single document.  For example, to rebuild only
 848 ‘contributor.pdf’, do the following:
 849
 850      cd build/
 851      cd Documentation/
 852      touch ../../Documentation/contributor.texi
 853      make out=www out-www/contributor.pdf
 854
 855    If you are only working on a single document, test-building it in
 856 this way can give substantial time savings - recreating
 857 ‘contributor.pdf’, for example, takes a matter of seconds.
 858
 859 Saving time with ‘CPU_COUNT’
 860 ............................
 861
 862 The most time consuming task for building the documentation is running
 863 LilyPond to build images of music, and there cannot be several
 864 simultaneously running ‘lilypond-book’ instances, so the ‘-j’ ‘make’
 865 option does not significantly speed up the build process.  To help speed
 866 it up, the makefile variable ‘CPU_COUNT’ may be set in ‘local.make’ or
 867 on the command line to the number of ‘.ly’ files that LilyPond should
 868 process simultaneously, e.g.  on a bi-processor or dual core machine:
 869
 870      make -j3 CPU_COUNT=3 doc
 871
 872 The recommended value of ‘CPU_COUNT’ is one plus the number of cores or
 873 processors, but it is advisable to set it to a smaller value unless your
 874 system has enough RAM to run that many simultaneous LilyPond instances.
 875 Also, values for the ‘-j’ option that pose problems with ‘make’ are less
 876 likely to pose problems with ‘make doc’ (this applies to both ‘-j’ and
 877 ‘CPU_COUNT’).  For example, with a quad-core processor, it is possible
 878 for ‘make -j5 CPU_COUNT=5 doc’ to work consistently even if ‘make -j5’
 879 rarely succeeds.
 880
 881 AJAX search
 882 ...........
 883
 884 To build the documentation with interactive searching, use:
 885
 886      make doc AJAX_SEARCH=1
 887
 888    This requires PHP, and you must view the docs via a http connection
 889 (you cannot view them on your local filesystem).
 890
 891           Note: Due to potential security or load issues, this option is
 892           not enabled in the official documentation builds.  Enable at
 893           your own risk.
 894
 895 Installing documentation
 896 ........................
 897
 898 The HTML, PDF and if available Info files can be installed into the
 899 standard documentation path by issuing
 900
 901      make install-doc
 902
 903 This also installs Info documentation with images if the installation
 904 prefix is properly set; otherwise, instructions to complete proper
 905 installation of Info documentation are printed on standard output.
 906
 907    To install the Info documentation separately, run:
 908
 909      make install-info
 910
 911 Note that to get the images in Info documentation, ‘install-doc’ target
 912 creates symbolic links to HTML and PDF installed documentation tree in
 913 ‘PREFIX/share/info’, in order to save disk space, whereas ‘install-info’
 914 copies images in ‘PREFIX/share/info’ subdirectories.
 915
 916    It is possible to build a documentation tree in
 917 ‘out-www/online-root/’, with special processing, so it can be used on a
 918 website with content negotiation for automatic language selection; this
 919 can be achieved by issuing
 920
 921      make WEB_TARGETS=online doc
 922
 923 and both ‘offline’ and ‘online’ targets can be generated by issuing
 924
 925      make WEB_TARGETS="offline online" doc
 926
 927    Several targets are available to clean the documentation build and
 928 help with maintaining documentation; an overview of these targets is
 929 available with
 930
 931      make help
 932
 933 from every directory in the build tree.  Most targets for documentation
 934 maintenance are available from ‘Documentation/’; for more information,
 935 see *note (lilypond-contributor)Documentation work::.
 936
 937    The makefile variable ‘QUIET_BUILD’ may be set to ‘1’ for a less
 938 verbose build output, just like for building the programs.
 939
 940 Building documentation without compiling
 941 ........................................
 942
 943 The documentation can be built locally without compiling LilyPond
 944 binary, if LilyPond is already installed on your system.
 945
 946    From a fresh Git checkout, do
 947
 948      ./autogen.sh   # ignore any warning messages
 949      cp GNUmakefile.in GNUmakefile
 950      make -C scripts && make -C python
 951      nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
 952
 953    Please note that this may break sometimes – for example, if a new
 954 feature is added with a test file in input/regression, even the latest
 955 development release of LilyPond will fail to build the docs.
 956
 957    You may build the manual without building all the ‘input/*’ stuff
 958 (i.e.  mostly regression tests): change directory, for example to
 959 ‘Documentation/’, issue ‘make doc’, which will build documentation in a
 960 subdirectory ‘out-www’ from the source files in current directory.  In
 961 this case, if you also want to browse the documentation in its
 962 post-processed form, change back to top directory and issue
 963
 964      make out=www WWW-post
 965
 966
 967 Known issues and warnings
 968 .........................
 969
 970 You may also need to create a script for ‘pngtopnm’ and ‘pnmtopng’.  On
 971 GNU/Linux, I use this:
 972
 973 export LD_LIBRARY_PATH=/usr/lib
 974 exec /usr/bin/pngtopnm "$@"
 975
 976    On MacOS X with fink, I use this:
 977
 978 export DYLD_LIBRARY_PATH=/sw/lib
 979 exec /sw/bin/pngtopnm "$@"
 980
 981    On MacOS X with macports, you should use this:
 982
 983 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
 984 exec /opt/local/bin/pngtopnm "$@"
 985
 986 1.6.3 Testing LilyPond binary
 987 -----------------------------
 988
 989 LilyPond comes with an extensive suite that exercises the entire
 990 program.  This suite can be used to test that the binary has been built
 991 correctly.
 992
 993    The test suite can be executed with:
 994
 995 make test
 996
 997    If the test suite completes successfully, the LilyPond binary has
 998 been verified.
 999
1000    More information on the regression test suite is found at *note
1001 (lilypond-contributor)Regression tests::.
1002
1003 1.7 Problems
1004 ============
1005
1006 For help and questions use <lilypond-user@gnu.org>.  Send bug reports to
1007 <bug-lilypond@gnu.org>.
1008
1009    Bugs that are not fault of LilyPond are documented here.
1010
1011 Compiling on MacOS X
1012 --------------------
1013
1014 Here are special instructions for compiling under MacOS X. These
1015 instructions assume that dependencies are installed using MacPorts.
1016 (http://www.macports.org/) The instructions have been tested using OS X
1017 10.5 (Leopard).
1018
1019    First, install the relevant dependencies using MacPorts.
1020
1021    Next, add the following to your relevant shell initialization files.
1022 This is ‘~/.profile’ by default.  You should create this file if it does
1023 not exist.
1024
1025      export PATH=/opt/local/bin:/opt/local/sbin:$PATH
1026      export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
1027
1028    Now you must edit the generated ‘config.make’ file.  Change
1029
1030      FLEXLEXER_FILE = /usr/include/FlexLexer.h
1031
1032 to:
1033
1034      FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
1035
1036    At this point, you should verify that you have the appropriate fonts
1037 installed with your ghostscript installation.  Check ‘ls
1038 /opt/local/share/ghostscript/fonts’ for: ’c0590*’ files (.pfb, .pfb and
1039 .afm).  If you don’t have them, run the following commands to grab them
1040 from the ghostscript SVN server and install them in the appropriate
1041 location:
1042
1043      svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
1044      sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
1045      rm -rf urw-fonts-1.07pre44
1046
1047    Now run the ‘./configure’ script.  To avoid complications with
1048 automatic font detection, add
1049
1050      --with-fonts-dir=/opt/local/share/ghostscript/fonts
1051
1052 Solaris
1053 -------
1054
1055 Solaris7, ./configure
1056
1057    ‘./configure’ needs a POSIX compliant shell.  On Solaris7, ‘/bin/sh’
1058 is not yet POSIX compliant, but ‘/bin/ksh’ or bash is.  Run configure
1059 like
1060
1061      CONFIG_SHELL=/bin/ksh ksh -c ./configure
1062
1063 or
1064
1065      CONFIG_SHELL=/bin/bash bash -c ./configure
1066
1067 FreeBSD
1068 -------
1069
1070 To use system fonts, dejaview must be installed.  With the default port,
1071 the fonts are installed in ‘usr/X11R6/lib/X11/fonts/dejavu’.
1072
1073    Open the file ‘$LILYPONDBASE/usr/etc/fonts/local.conf’ and add the
1074 following line just after the ‘<fontconfig>’ line.  (Adjust as necessary
1075 for your hierarchy.)
1076
1077      <dir>/usr/X11R6/lib/X11/fonts</dir>
1078
1079 International fonts
1080 -------------------
1081
1082 On Mac OS X, all fonts are installed by default.  However, finding all
1083 system fonts requires a bit of configuration; see this post
1084 (http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
1085 on the ‘lilypond-user’ mailing list.
1086
1087    On Linux, international fonts are installed by different means on
1088 every distribution.  We cannot list the exact commands or packages that
1089 are necessary, as each distribution is different, and the exact package
1090 names within each distribution changes.  Here are some hints, though:
1091
1092 Red Hat Fedora
1093
1094     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
1095          ttfonts-zh_CN fonts-ja fonts-hebrew
1096
1097 Debian GNU/Linux
1098
1099    apt-get install emacs-intl-fonts xfonts-intl-.* \
1100         fonts-ipafont-gothic  fonts-ipafont-mincho \
1101         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
1102
1103 Using lilypond python libraries
1104 -------------------------------
1105
1106 If you want to use lilypond’s python libraries (either running certain
1107 build scripts manually, or using them in other programs), set
1108 ‘PYTHONPATH’ to ‘python/out’ in your build directory, or
1109 ‘.../usr/lib/lilypond/current/python’ in the installation directory
1110 structure.
1111
1112 1.8 Concurrent stable and development versions
1113 ==============================================
1114
1115 It can be useful to have both the stable and the development versions of
1116 LilyPond available at once.  One way to do this on GNU/Linux is to
1117 install the stable version using the precompiled binary, and run the
1118 development version from the source tree.  After running ‘make all’ from
1119 the top directory of the LilyPond source files, there will be a binary
1120 called ‘lilypond’ in the ‘out’ directory:
1121
1122      <PATH TO>/lilypond/out/bin/lilypond
1123
1124    This binary can be run without actually doing the ‘make install’
1125 command.  The advantage to this is that you can have all of the latest
1126 changes available after pulling from git and running ‘make all’, without
1127 having to uninstall the old version and reinstall the new.
1128
1129    So, to use the stable version, install it as usual and use the normal
1130 commands:
1131
1132      lilypond foobar.ly
1133
1134    To use the development version, create a link to the binary in the
1135 source tree by saving the following line in a file somewhere in your
1136 ‘$PATH’:
1137
1138      exec <PATH TO>/lilypond/out/bin/lilypond "$@"
1139
1140    Save it as ‘Lilypond’ (with a capital L to distinguish it from the
1141 stable ‘lilypond’), and make it executable:
1142
1143      chmod +x Lilypond
1144
1145    Then you can invoke the development version this way:
1146
1147      Lilypond foobar.ly
1148
1149    TODO: ADD
1150
1151    - other compilation tricks for developers
1152
1153 1.9 Build system
1154 ================
1155
1156 We currently use make and stepmake, which is complicated and only used
1157 by us.  Hopefully this will change in the future.
1158
1159 Version-specific texinfo macros
1160 -------------------------------
1161
1162    • made with ‘scripts/build/create-version-itexi.py’ and
1163      ‘scripts/build/create-weblinks-itexi.py’
1164
1165    • used extensively in the ‘WEBSITE_ONLY_BUILD’ version of the website
1166      (made with ‘website.make’, used on lilypond.org)
1167
1168    • not (?)  used in the main docs?
1169
1170    • the numbers in VERSION file: MINOR_VERSION should be 1 more than
1171      the last release, VERSION_DEVEL should be the last *online*
1172      release.  Yes, VERSION_DEVEL is less than VERSION.
1173