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