INSTALL.txt

   1 INSTALL - compiling and installing GNU LilyPond
   2 ***********************************************
   3
   4 Table of Contents
   5 *****************
   6
   7 INSTALL - compiling and installing GNU LilyPond
   8   Overview of compiling
   9   Requirements
  10     Requirements for running LilyPond
  11     Requirements for compiling LilyPond
  12     Requirements for building documentation
  13   Getting the source code
  14   Configuring `make'
  15     Running `./autogen.sh'
  16     Running `../configure'
  17       Configuration options
  18       Checking build dependencies
  19       Configuring target directories
  20   Compiling LilyPond
  21     Using `make'
  22     Saving time with the `-j' option
  23     Compiling for multiple platforms
  24     Useful `make' variables
  25   Post-compilation options
  26     Installing LilyPond from a local build
  27     Generating documentation
  28       Documentation editor's edit/compile cycle
  29       Building documentation
  30       Building a single document
  31       Saving time with `CPU_COUNT'
  32       AJAX search
  33       Installing documentation
  34       Building documentation without compiling
  35     Testing LilyPond binary
  36   Problems
  37       Bison 1.875
  38       Compiling on MacOS X
  39       Solaris
  40       FreeBSD
  41       International fonts
  42       Using lilypond python libraries
  43   Concurrent stable and development versions
  44   Build system
  45
  46
  47 Overview of compiling
  48 =====================
  49
  50 Compiling LilyPond from source is an involved process, and is only
  51 recommended for developers and packagers.  Typical program users are
  52 instead encouraged to obtain the program from a package manager (on
  53 Unix) or by downloading a precompiled binary configured for a specific
  54 operating system.  Pre-compiled binaries are available on the *note
  55 Download: (lilypond-web)Download. page.
  56
  57    Compiling LilyPond from source is necessary if you want to build,
  58 install, or test your own version of the program.
  59
  60    A successful compile can also be used to generate and install the
  61 documentation, incorporating any changes you may have made.  However, a
  62 successful compile is not a requirement for generating the
  63 documentation.  The documentation can be built using a Git repository
  64 in conjunction with a locally installed copy of the program.  For more
  65 information, see *note Building documentation without compiling::.
  66
  67    Attempts to compile LilyPond natively on Windows have been
  68 unsuccessful, though a workaround is available (see *note LilyDev:
  69 (lilypond-contributor)LilyDev.).
  70
  71 Requirements
  72 ============
  73
  74 Requirements for running LilyPond
  75 ---------------------------------
  76
  77 Running LilyPond requires proper installation of the following software:
  78
  79    * DejaVu fonts (http://www.dejavu-fonts.org/) (normally installed by
  80      default)
  81
  82    * FontConfig (http://www.fontconfig.org/) (2.4.0 or newer)
  83
  84    * Freetype (http://www.freetype.org/) (2.1.10 or newer)
  85
  86    * Ghostscript (http://www.ghostscript.com) (8.60 or newer)
  87
  88    * Guile (http://www.gnu.org/software/guile/guile.html) (1.8.2 or
  89      newer)
  90
  91    * Pango (http://www.pango.org/) (1.12 or newer)
  92
  93    * Python (http://www.python.org) (2.4 or newer)
  94
  95    International fonts are required to create music with international
  96 text or lyrics.
  97
  98 Requirements for compiling LilyPond
  99 -----------------------------------
 100
 101 Below is a full list of packages needed to build LilyPond.  However,
 102 for most common distributions there is an easy way of installing most
 103 all build dependencies in one go:
 104
 105 Distribution                         Command
 106 --------------------------------------------------------------------------
 107 Debian, Ubuntu                       `sudo apt-get build-dep lilypond'
 108 Fedora, RHEL                         `sudo yum-builddep lilypond'
 109 openSUSE, SLED                       `sudo zypper --build-deps-only
 110                                      source-install lilypond'
 111
 112    * Everything listed in *note Requirements for running LilyPond::
 113
 114    * Development packages for the above items (which should include
 115      header files and libraries).
 116
 117      Red Hat Fedora:
 118
 119           guile-devel-VERSION
 120           fontconfig-devel-VERSION
 121           freetype-devel-VERSION
 122           pango-devel-VERSION
 123           python-devel-VERSION
 124
 125      Debian GNU/Linux:
 126
 127           guile-VERSION-dev
 128           libfontconfig1-dev
 129           libfreetype6-dev
 130           libpango1.0-dev
 131           pythonVERSION-dev
 132
 133    * Flex (http://flex.sourceforge.net/)
 134
 135    * FontForge (http://fontforge.sf.net/) (20060125 or newer; 20100501
 136      or newer is recommended; must be compiled with `--enable-double'.
 137      Failure to do so can lead to poor intersection calculations and
 138      poorly-rendered glyphs.)
 139
 140    * GNU Bison (http://www.gnu.org/software/bison/)
 141
 142    * GNU Compiler Collection (http://gcc.gnu.org/) (3.4 or newer, 4.X
 143      recommended)
 144
 145    * GNU gettext (http://www.gnu.org/software/gettext/gettext.html)
 146      (0.17 or newer)
 147
 148    * GNU Make (http://www.gnu.org/software/make/) (3.78 or newer)
 149
 150    * MetaFont (http://metafont.tutorial.free.fr/) (mf-nowin, mf, mfw or
 151      mfont binaries), usually packaged with TeX
 152      (http://www.latex-project.org/ftp.html).
 153
 154    * MetaPost (http://cm.bell-labs.com/who/hobby/MetaPost.html) (mpost
 155      binary), usually packaged with TeX
 156      (http://www.latex-project.org/ftp.html).
 157
 158    * Perl (http://www.perl.org/)
 159
 160    * Texinfo (http://www.gnu.org/software/texinfo/) (4.11 or newer)
 161
 162    * Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)
 163      (1.33 or newer recommended)
 164
 165 Requirements for building documentation
 166 ---------------------------------------
 167
 168 You can view the documentation online at
 169 `http://www.lilypond.org/doc/', but you can also build it locally.
 170 This process requires some additional tools and packages:
 171
 172    * Everything listed in *note Requirements for compiling LilyPond::
 173
 174    * ImageMagick (http://www.imagemagick.org/)
 175
 176    * Netpbm (http://netpbm.sourceforge.net/)
 177
 178    * gzip (http://gzip.org/)
 179
 180    * rsync (http://rsync.samba.org/)
 181
 182    * Texi2HTML (http://www.nongnu.org/texi2html/) (1.82)
 183
 184    * International fonts
 185
 186      Red Hat Fedora:
 187
 188           fonts-arabic
 189           fonts-hebrew
 190           fonts-ja
 191           fonts-xorg-truetype
 192           taipeifonts
 193           ttfonts-ja
 194           ttfonts-zh_CN
 195
 196      Debian GNU/Linux:
 197
 198           emacs-intl-fonts
 199           ttf-kochi-gothic
 200           ttf-kochi-mincho
 201           xfonts-bolkhov-75dpi
 202           xfonts-cronyx-75dpi
 203           xfonts-cronyx-100dpi
 204           xfonts-intl-.*
 205
 206 Getting the source code
 207 =======================
 208
 209 Downloading the Git repository
 210 ------------------------------
 211
 212 In general, developers compile LilyPond from within a local Git
 213 repository.  Setting up a local Git repository is explained in *note
 214 Starting with Git: (lilypond-contributor)Starting with Git.
 215
 216 Downloading a source tarball
 217 ----------------------------
 218
 219 Packagers are encouraged to use source tarballs for compiling.
 220
 221    The tarball for the latest stable release is available on the *note
 222 Source: (lilypond-web)Source. page.
 223
 224 The latest source code snapshot
 225 (http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot) is also
 226 available as a tarball from the GNU Savannah Git server.
 227
 228 All tagged releases (including legacy stable versions and the most
 229 recent development release) are available here:
 230
 231      `http://download.linuxaudio.org/lilypond/source/'
 232
 233    Download the tarball to your `~/src/' directory, or some other
 234 appropriate place.
 235
 236           Note: Be careful where you unpack the tarball!  Any
 237           subdirectories of the current folder named `lilypond/' or
 238           `lilypond-X.Y.Z/' (where X.Y.Z is the release number) will be
 239           overwritten if there is a name clash with the tarball.
 240
 241    Unpack the tarball with this command:
 242
 243      tar -xzf lilypond-X.Y.Z.tar.gz
 244
 245    This creates a subdirectory within the current directory called
 246 `lilypond-X.Y.Z/'.  Once unpacked, the source files occupy about 40 MB
 247 of disk space.
 248
 249    Windows users wanting to look at the source code may have to
 250 download and install the free-software 7zip archiver
 251 (http://www.7-zip.org) to extract the tarball.
 252
 253 Configuring `make'
 254 ==================
 255
 256 Running `./autogen.sh'
 257 ----------------------
 258
 259 After you unpack the tarball (or download the Git repository), the
 260 contents of your top source directory should be similar to the current
 261 source tree listed at
 262 `http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree'.
 263
 264    Next, you need to create the generated files; enter the following
 265 command from your top source directory:
 266
 267      ./autogen.sh --noconfigure
 268
 269    This will generate a number of files and directories to aid
 270 configuration, such as `configure', `README.txt', etc.
 271
 272    Next, create the build directory with:
 273
 274      mkdir build/
 275      cd build/
 276
 277    We heavily recommend building lilypond inside a separate directory
 278 with this method.
 279
 280 Running `../configure'
 281 ----------------------
 282
 283 Configuration options
 284 .....................
 285
 286           Note: make sure that you are in the `build/' subdirectory of
 287           your source tree.
 288
 289 The `../configure' command (generated by `./autogen.sh') provides many
 290 options for configuring `make'.  To see them all, run:
 291
 292      ../configure --help
 293
 294 Checking build dependencies
 295 ...........................
 296
 297           Note: make sure that you are in the `build/' subdirectory of
 298           your source tree.
 299
 300 When `../configure' is run without any arguments, it will check to make
 301 sure your system has everything required for compilation:
 302
 303      ../configure
 304
 305    If any build dependency is missing, `../configure' will return with:
 306
 307      ERROR: Please install required programs:  FOO
 308
 309    The following message is issued if you are missing programs that are
 310 only needed for building the documentation:
 311
 312      WARNING: Please consider installing optional programs:  BAR
 313
 314    If you intend to build the documentation locally, you will need to
 315 install or update these programs accordingly.
 316
 317           Note: `../configure' may fail to issue warnings for certain
 318           documentation build requirements that are not met.  If you
 319           experience problems when building the documentation, you may
 320           need to do a manual check of *note Requirements for building
 321           documentation::.
 322
 323 Configuring target directories
 324 ..............................
 325
 326           Note: make sure that you are in the `build/' subdirectory of
 327           your source tree.
 328
 329 If you intend to use your local build to install a local copy of the
 330 program, you will probably want to configure the installation
 331 directory.  Here are the relevant lines taken from the output of
 332 `../configure --help':
 333
 334      By default, ``make install'' will install all the files in
 335      `/usr/local/bin', `/usr/local/lib' etc.  You can specify an
 336      installation prefix other than `/usr/local' using ``--prefix'',
 337      for instance ``--prefix=$HOME''.
 338
 339    A typical installation prefix is `$HOME/usr':
 340
 341      ../configure --prefix=$HOME/usr
 342
 343    Note that if you plan to install a local build on a system where you
 344 do not have root privileges, you will need to do something like this
 345 anyway--`make install' will only succeed if the installation prefix
 346 points to a directory where you have write permission (such as your
 347 home directory).  The installation directory will be automatically
 348 created if necessary.
 349
 350    The location of the `lilypond' command installed by this process
 351 will be `PREFIX/bin/lilypond'; you may want to add `PREFIX/bin/' to
 352 your `$PATH' if it is not already included.
 353
 354    It is also possible to specify separate installation directories for
 355 different types of program files.  See the full output of
 356 `../configure --help' for more information.
 357
 358    If you encounter any problems, please see *note Problems::.
 359
 360 Compiling LilyPond
 361 ==================
 362
 363 Using `make'
 364 ------------
 365
 366           Note: make sure that you are in the `build/' subdirectory of
 367           your source tree.
 368
 369 LilyPond is compiled with the `make' command.  Assuming `make' is
 370 configured properly, you can simply run:
 371
 372      make
 373
 374    `make' is short for `make all'.  To view a list of `make' targets,
 375 run:
 376
 377      make help
 378
 379    TODO: Describe what `make' actually does.
 380
 381
 382
 383 See also
 384 ........
 385
 386
 387
 388    *note Generating documentation:: provides more info on the `make'
 389 targets used to build the LilyPond documentation.
 390
 391 Saving time with the `-j' option
 392 --------------------------------
 393
 394 If your system has multiple CPUs, you can speed up compilation by
 395 adding `-jX' to the `make' command, where `X' is one more than the
 396 number of cores you have.  For example, a typical Core2Duo machine
 397 would use:
 398
 399      make -j3
 400
 401    If you get errors using the `-j' option, and `make' succeeds without
 402 it, try lowering the `X' value.
 403
 404    Because multiple jobs run in parallel when `-j' is used, it can be
 405 difficult to determine the source of an error when one occurs.  In that
 406 case, running `make' without the `-j' is advised.
 407
 408 Compiling for multiple platforms
 409 --------------------------------
 410
 411 If you want to build multiple versions of LilyPond with different
 412 configuration settings, you can use the `--enable-config=CONF' option
 413 of `configure'.  You should use `make conf=CONF' to generate the output
 414 in `out-CONF'.  For example, suppose you want to build with and without
 415 profiling, then use the following for the normal build
 416
 417      ./configure --prefix=$HOME/usr/ --enable-checking
 418      make
 419
 420    and for the profiling version, specify a different configuration
 421
 422      ./configure --prefix=$HOME/usr/ --enable-profiling \
 423        --enable-config=prof --disable-checking
 424      make conf=prof
 425
 426    If you wish to install a copy of the build with profiling, don't
 427 forget to use `conf=CONF' when issuing `make install':
 428
 429      make conf=prof install
 430
 431
 432 See also
 433 ........
 434
 435
 436
 437    *note Installing LilyPond from a local build::
 438
 439 Useful `make' variables
 440 -----------------------
 441
 442 If a less verbose build output if desired, the variable `QUIET_BUILD'
 443 may be set to `1' on `make' command line, or in `local.make' at top of
 444 the build tree.
 445
 446 Post-compilation options
 447 ========================
 448
 449 Installing LilyPond from a local build
 450 --------------------------------------
 451
 452 If you configured `make' to install your local build in a directory
 453 where you normally have write permission (such as your home directory),
 454 and you have compiled LilyPond by running `make', you can install the
 455 program in your target directory by running:
 456
 457      make install
 458
 459    If instead, your installation directory is not one that you can
 460 normally write to (such as the default `/usr/local/', which typically
 461 is only writeable by the superuser), you will need to temporarily
 462 become the superuser when running `make install':
 463
 464      sudo make install
 465
 466 or...
 467
 468      su -c 'make install'
 469
 470    If you don't have superuser privileges, then you need to configure
 471 the installation directory to one that you can write to, and then
 472 re-install.  See *note Configuring target directories::.
 473
 474 Generating documentation
 475 ------------------------
 476
 477 Documentation editor's edit/compile cycle
 478 .........................................
 479
 480    * Initial documentation build:
 481
 482           make [-jX]
 483           make [-jX CPU_COUNT=X] doc          _## can take an hour or more_
 484           make [-jX CPU_COUNT=X] doc-stage-1  _## to build only PDF documentation_
 485
 486    * Edit/compile cycle:
 487
 488           _## edit source files, then..._
 489
 490           make [-jX]                  _## needed if editing outside_
 491                                       _##   Documentation/, but useful anyway_
 492                                       _##   for finding Texinfo errors._
 493           make [-jX CPU_COUNT=X] doc  _## usually faster than initial build._
 494
 495    * Reset:
 496
 497      It is generally possible to remove the compiled documentation from
 498      your system with `make doc-clean', but this method is not 100%
 499      guaranteed.  Instead, if you want to be sure you have a clean
 500      system, we recommend that you delete your `build/' directory, and
 501      begin compiling from scratch.  Since the documentation compile
 502      takes much longer than the non-documentation compile, this does
 503      not increase the overall time by a great deal.
 504
 505
 506 Building documentation
 507 ......................
 508
 509 After a successful compile (using `make'), the documentation can be
 510 built by issuing:
 511
 512      make doc
 513
 514    or, to build only the PDF documentation and not the HTML,
 515
 516      make doc-stage-1
 517
 518           Note: The first time you run `make doc', the process can
 519           easily take an hour or more with not much output on the
 520           command line.
 521
 522    After this initial build, `make doc' only makes changes to the
 523 documentation where needed, so it may only take a minute or two to test
 524 changes if the documentation is already built.
 525
 526    If `make doc' succeeds, the HTML documentation tree is available in
 527 `out-www/offline-root/', and can be browsed locally.  Various portions
 528 of the documentation can be found by looking in `out/' and `out-www'
 529 subdirectories in other places in the source tree, but these are only
 530 _portions_ of the docs.  Please do not complain about anything which is
 531 broken in those places; the only complete set of documentation is in
 532 `out-www/offline-root/' from the top of the source tree.
 533
 534    `make doc' sends the output from most of the compilation to
 535 logfiles.  If the build fails for any reason, it should prompt you with
 536 the name of a logfile which will provide information to help you work
 537 out why the build failed.  These logfiles are not deleted with
 538 `make doc-clean'.  To remove all the logfiles generated by the
 539 compilation process, use:
 540
 541      make log-clean
 542
 543    `make doc' compiles the documents for all languages.  To save some
 544 compile time, the English language documents can be compiled on their
 545 own with:
 546
 547      make LANGS='' doc
 548
 549 Similarly, it is possible to compile a subset of the translated
 550 documentation by specifying their language codes on the command line.
 551 For example, the French and German translations are compiled with:
 552
 553      make LANGS='de fr' doc
 554
 555 Note that this will also compile the English version.
 556
 557    Compilation of documentation in Info format with images can be done
 558 separately by issuing:
 559
 560      make info
 561
 562 An issue when switching branches between master and translation is the
 563 appearance/disappearance of translated versions of some manuals.  If
 564 you see such a warning from make:
 565
 566      No rule to make target `X', needed by `Y'
 567
 568 Your best bet is to delete the file Y.dep and to try again.
 569
 570 Building a single document
 571 ..........................
 572
 573 It's possible to build a single document.  For example, to rebuild only
 574 `contributor.pdf', do the following:
 575
 576      cd build/
 577      cd Documentation/
 578      touch ../../Documentation/contributor.texi
 579      make out=www out-www/contributor.pdf
 580
 581    If you are only working on a single document, test-building it in
 582 this way can give substantial time savings - recreating
 583 `contributor.pdf', for example, takes a matter of seconds.
 584
 585 Saving time with `CPU_COUNT'
 586 ............................
 587
 588 The most time consuming task for building the documentation is running
 589 LilyPond to build images of music, and there cannot be several
 590 simultaneously running `lilypond-book' instances, so the `-j' `make'
 591 option does not significantly speed up the build process.  To help
 592 speed it up, the makefile variable `CPU_COUNT' may be set in
 593 `local.make' or on the command line to the number of `.ly' files that
 594 LilyPond should process simultaneously, e.g. on a bi-processor or dual
 595 core machine:
 596
 597      make -j3 CPU_COUNT=3 doc
 598
 599 The recommended value of `CPU_COUNT' is one plus the number of cores or
 600 processors, but it is advisable to set it to a smaller value unless
 601 your system has enough RAM to run that many simultaneous LilyPond
 602 instances.  Also, values for the `-j' option that pose problems with
 603 `make' are less likely to pose problems with `make doc' (this applies
 604 to both `-j' and `CPU_COUNT').  For example, with a quad-core processor,
 605 it is possible for `make -j5 CPU_COUNT=5 doc' to work consistently even
 606 if `make -j5' rarely succeeds.
 607
 608 AJAX search
 609 ...........
 610
 611 To build the documentation with interactive searching, use:
 612
 613      make doc AJAX_SEARCH=1
 614
 615    This requires PHP, and you must view the docs via a http connection
 616 (you cannot view them on your local filesystem).
 617
 618           Note: Due to potential security or load issues, this option is
 619           not enabled in the official documentation builds.  Enable at
 620           your own risk.
 621
 622 Installing documentation
 623 ........................
 624
 625 The HTML, PDF and if available Info files can be installed into the
 626 standard documentation path by issuing
 627
 628      make install-doc
 629
 630 This also installs Info documentation with images if the installation
 631 prefix is properly set; otherwise, instructions to complete proper
 632 installation of Info documentation are printed on standard output.
 633
 634    To install the Info documentation separately, run:
 635
 636      make install-info
 637
 638 Note that to get the images in Info documentation, `install-doc' target
 639 creates symbolic links to HTML and PDF installed documentation tree in
 640 `PREFIX/share/info', in order to save disk space, whereas
 641 `install-info' copies images in `PREFIX/share/info' subdirectories.
 642
 643    It is possible to build a documentation tree in
 644 `out-www/online-root/', with special processing, so it can be used on a
 645 website with content negotiation for automatic language selection; this
 646 can be achieved by issuing
 647
 648      make WEB_TARGETS=online doc
 649
 650 and both `offline' and `online' targets can be generated by issuing
 651
 652      make WEB_TARGETS="offline online" doc
 653
 654    Several targets are available to clean the documentation build and
 655 help with maintaining documentation; an overview of these targets is
 656 available with
 657
 658      make help
 659
 660 from every directory in the build tree.  Most targets for documentation
 661 maintenance are available from `Documentation/'; for more information,
 662 see *note Documentation work: (lilypond-contributor)Documentation work.
 663
 664    The makefile variable `QUIET_BUILD' may be set to `1' for a less
 665 verbose build output, just like for building the programs.
 666
 667 Building documentation without compiling
 668 ........................................
 669
 670 The documentation can be built locally without compiling LilyPond
 671 binary, if LilyPond is already installed on your system.
 672
 673    From a fresh Git checkout, do
 674
 675      ./autogen.sh   # ignore any warning messages
 676      cp GNUmakefile.in GNUmakefile
 677      make -C scripts && make -C python
 678      nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
 679
 680    Please note that this may break sometimes - for example, if a new
 681 feature is added with a test file in input/regression, even the latest
 682 development release of LilyPond will fail to build the docs.
 683
 684    You may build the manual without building all the `input/*' stuff
 685 (i.e. mostly regression tests): change directory, for example to
 686 `Documentation/', issue `make doc', which will build documentation in a
 687 subdirectory `out-www' from the source files in current directory.  In
 688 this case, if you also want to browse the documentation in its
 689 post-processed form, change back to top directory and issue
 690
 691      make out=www WWW-post
 692
 693
 694 Known issues and warnings
 695 .........................
 696
 697 You may also need to create a script for `pngtopnm' and `pnmtopng'.  On
 698 GNU/Linux, I use this:
 699
 700 export LD_LIBRARY_PATH=/usr/lib
 701 exec /usr/bin/pngtopnm "$@"
 702
 703    On MacOS X with fink, I use this:
 704
 705 export DYLD_LIBRARY_PATH=/sw/lib
 706 exec /sw/bin/pngtopnm "$@"
 707
 708    On MacOS X with macports, you should use this:
 709
 710 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
 711 exec /opt/local/bin/pngtopnm "$@"
 712
 713 Testing LilyPond binary
 714 -----------------------
 715
 716 LilyPond comes with an extensive suite that exercises the entire
 717 program.  This suite can be used to test that the binary has been built
 718 correctly.
 719
 720    The test suite can be executed with:
 721
 722 make test
 723
 724    If the test suite completes successfully, the LilyPond binary has
 725 been verified.
 726
 727    More information on the regression test suite is found at *note
 728 Regression tests: (lilypond-contributor)Regression tests.
 729
 730 Problems
 731 ========
 732
 733 For help and questions use <lilypond-user@gnu.org>.  Send bug reports
 734 to <bug-lilypond@gnu.org>.
 735
 736    Bugs that are not fault of LilyPond are documented here.
 737
 738 Bison 1.875
 739 ...........
 740
 741 There is a bug in bison-1.875: compilation fails with "parse error
 742 before `goto'" in line 4922 due to a bug in bison.  To fix, please
 743 recompile bison 1.875 with the following fix
 744
 745      $ cd lily; make out/parser.cc
 746      $ vi +4919 out/parser.cc
 747      # append a semicolon to the line containing "__attribute__ ((__unused__))
 748      # save
 749      $ make
 750
 751 Compiling on MacOS X
 752 ....................
 753
 754 Here are special instructions for compiling under MacOS X.  These
 755 instructions assume that dependencies are installed using MacPorts.
 756 (http://www.macports.org/) The instructions have been tested using OS X
 757 10.5 (Leopard).
 758
 759    First, install the relevant dependencies using MacPorts.
 760
 761    Next, add the following to your relevant shell initialization files.
 762 This is `~/.profile' by default.  You should create this file if it
 763 does not exist.
 764
 765      export PATH=/opt/local/bin:/opt/local/sbin:$PATH
 766      export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
 767
 768    Now you must edit the generated `config.make' file.  Change
 769
 770      FLEXLEXER_FILE = /usr/include/FlexLexer.h
 771
 772 to:
 773
 774      FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
 775
 776    At this point, you should verify that you have the appropriate fonts
 777 installed with your ghostscript installation.  Check `ls
 778 /opt/local/share/ghostscript/fonts' for: 'c0590*' files (.pfb, .pfb and
 779 .afm).  If you don't have them, run the following commands to grab them
 780 from the ghostscript SVN server and install them in the appropriate
 781 location:
 782
 783      svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
 784      sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
 785      rm -rf urw-fonts-1.07pre44
 786
 787    Now run the `./configure' script.  To avoid complications with
 788 automatic font detection, add
 789
 790      --with-ncsb-dir=/opt/local/share/ghostscript/fonts
 791
 792 Solaris
 793 .......
 794
 795 Solaris7, ./configure
 796
 797    `./configure' needs a POSIX compliant shell.  On Solaris7, `/bin/sh'
 798 is not yet POSIX compliant, but `/bin/ksh' or bash is.  Run configure
 799 like
 800
 801      CONFIG_SHELL=/bin/ksh ksh -c ./configure
 802
 803 or
 804
 805      CONFIG_SHELL=/bin/bash bash -c ./configure
 806
 807 FreeBSD
 808 .......
 809
 810 To use system fonts, dejaview must be installed.  With the default
 811 port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.
 812
 813    Open the file `$LILYPONDBASE/usr/etc/fonts/local.conf' and add the
 814 following line just after the `<fontconfig>' line.  (Adjust as necessary
 815 for your hierarchy.)
 816
 817      <dir>/usr/X11R6/lib/X11/fonts</dir>
 818
 819 International fonts
 820 ...................
 821
 822 On Mac OS X, all fonts are installed by default.  However, finding all
 823 system fonts requires a bit of configuration; see this post
 824 (http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
 825 on the `lilypond-user' mailing list.
 826
 827    On Linux, international fonts are installed by different means on
 828 every distribution.  We cannot list the exact commands or packages that
 829 are necessary, as each distribution is different, and the exact package
 830 names within each distribution changes.  Here are some hints, though:
 831
 832 Red Hat Fedora
 833
 834     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 835          ttfonts-zh_CN fonts-ja fonts-hebrew
 836
 837 Debian GNU/Linux
 838
 839    apt-get install emacs-intl-fonts xfonts-intl-.* \
 840         ttf-kochi-gothic ttf-kochi-mincho \
 841         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 842
 843 Using lilypond python libraries
 844 ...............................
 845
 846 If you want to use lilypond's python libraries (either running certain
 847 build scripts manually, or using them in other programs), set
 848 `PYTHONPATH' to `python/out' in your build directory, or
 849 `.../usr/lib/lilypond/current/python' in the installation directory
 850 structure.
 851
 852 Concurrent stable and development versions
 853 ==========================================
 854
 855 It can be useful to have both the stable and the development versions
 856 of Lilypond available at once.  One way to do this on GNU/Linux is to
 857 install the stable version using the precompiled binary, and run the
 858 development version from the source tree.  After running `make all'
 859 from the top directory of the Lilypond source files, there will be a
 860 binary called `lilypond' in the `out' directory:
 861
 862      <PATH TO>/lilypond/out/bin/lilypond
 863
 864    This binary can be run without actually doing the `make install'
 865 command.  The advantage to this is that you can have all of the latest
 866 changes available after pulling from git and running `make all',
 867 without having to uninstall the old version and reinstall the new.
 868
 869    So, to use the stable version, install it as usual and use the
 870 normal commands:
 871
 872      lilypond foobar.ly
 873
 874    To use the development version, create a link to the binary in the
 875 source tree by saving the following line in a file somewhere in your
 876 `$PATH':
 877
 878      exec <PATH TO>/lilypond/out/bin/lilypond "$@"
 879
 880    Save it as `Lilypond' (with a capital L to distinguish it from the
 881 stable `lilypond'), and make it executable:
 882
 883      chmod +x Lilypond
 884
 885    Then you can invoke the development version this way:
 886
 887      Lilypond foobar.ly
 888
 889    TODO: ADD
 890
 891    - other compilation tricks for developers
 892
 893 Build system
 894 ============
 895
 896 We currently use make and stepmake, which is complicated and only used
 897 by us.  Hopefully this will change in the future.
 898
 899 Version-specific texinfo macros
 900 ...............................
 901
 902    * made with `scripts/build/create-version-itexi.py' and
 903      `scripts/build/create-weblinks-itexi.py'
 904
 905    * used extensively in the `WEBSITE_ONLY_BUILD' version of the
 906      website (made with `website.make', used on lilypond.org)
 907
 908    * not (?) used in the main docs?
 909
 910    * the numbers in VERSION file: MINOR_VERSION should be 1 more than
 911      the last release, VERSION_DEVEL should be the last *online*
 912      release.  Yes, VERSION_DEVEL is less than VERSION.
 913
 914