+ make doc
+
+ or, to build only the PDF documentation and not the HTML,
+
+ make doc-stage-1
+
+ Note: The first time you run ‘make doc’, the process can
+ easily take an hour or more with not much output on the
+ command line.
+
+ After this initial build, ‘make doc’ only makes changes to the
+documentation where needed, so it may only take a minute or two to test
+changes if the documentation is already built.
+
+ If ‘make doc’ succeeds, the HTML documentation tree is available in
+‘out-www/offline-root/’, and can be browsed locally. Various portions
+of the documentation can be found by looking in ‘out/’ and ‘out-www’
+subdirectories in other places in the source tree, but these are only
+_portions_ of the docs. Please do not complain about anything which is
+broken in those places; the only complete set of documentation is in
+‘out-www/offline-root/’ from the top of the source tree.
+
+ ‘make doc’ sends the output from most of the compilation to logfiles.
+If the build fails for any reason, it should prompt you with the name of
+a logfile which will provide information to help you work out why the
+build failed. These logfiles are not deleted with ‘make doc-clean’. To
+remove all the logfiles generated by the compilation process, use:
+
+ make log-clean
+
+ ‘make doc’ compiles the documents for all languages. To save some
+compile time, the English language documents can be compiled on their
+own with:
+
+ make LANGS='' doc
+
+Similarly, it is possible to compile a subset of the translated
+documentation by specifying their language codes on the command line.
+For example, the French and German translations are compiled with:
+
+ make LANGS='de fr' doc
+
+Note that this will also compile the English version.
+
+ Compilation of documentation in Info format with images can be done
+separately by issuing:
+
+ make info
+
+An issue when switching branches between master and translation is the
+appearance/disappearance of translated versions of some manuals. If you
+see such a warning from make:
+
+ No rule to make target `X', needed by `Y'
+
+Your best bet is to delete the file Y.dep and to try again.
+
+Building a single document
+..........................
+
+It’s possible to build a single document. For example, to rebuild only
+‘contributor.pdf’, do the following:
+
+ cd build/
+ cd Documentation/
+ touch ../../Documentation/contributor.texi
+ make out=www out-www/contributor.pdf
+
+ If you are only working on a single document, test-building it in
+this way can give substantial time savings - recreating
+‘contributor.pdf’, for example, takes a matter of seconds.
+
+Saving time with ‘CPU_COUNT’
+............................
+
+The most time consuming task for building the documentation is running
+LilyPond to build images of music, and there cannot be several
+simultaneously running ‘lilypond-book’ instances, so the ‘-j’ ‘make’
+option does not significantly speed up the build process. To help speed
+it up, the makefile variable ‘CPU_COUNT’ may be set in ‘local.make’ or
+on the command line to the number of ‘.ly’ files that LilyPond should
+process simultaneously, e.g. on a bi-processor or dual core machine:
+
+ make -j3 CPU_COUNT=3 doc
+
+The recommended value of ‘CPU_COUNT’ is one plus the number of cores or
+processors, but it is advisable to set it to a smaller value unless your
+system has enough RAM to run that many simultaneous LilyPond instances.
+Also, values for the ‘-j’ option that pose problems with ‘make’ are less
+likely to pose problems with ‘make doc’ (this applies to both ‘-j’ and
+‘CPU_COUNT’). For example, with a quad-core processor, it is possible
+for ‘make -j5 CPU_COUNT=5 doc’ to work consistently even if ‘make -j5’
+rarely succeeds.
+
+AJAX search
+...........
+
+To build the documentation with interactive searching, use:
+
+ make doc AJAX_SEARCH=1
+
+ This requires PHP, and you must view the docs via a http connection
+(you cannot view them on your local filesystem).
+
+ Note: Due to potential security or load issues, this option is
+ not enabled in the official documentation builds. Enable at
+ your own risk.
+
+Installing documentation
+........................
+
+The HTML, PDF and if available Info files can be installed into the
+standard documentation path by issuing
+
+ make install-doc
+
+This also installs Info documentation with images if the installation
+prefix is properly set; otherwise, instructions to complete proper
+installation of Info documentation are printed on standard output.
+
+ To install the Info documentation separately, run:
+
+ make install-info
+
+Note that to get the images in Info documentation, ‘install-doc’ target
+creates symbolic links to HTML and PDF installed documentation tree in
+‘PREFIX/share/info’, in order to save disk space, whereas ‘install-info’
+copies images in ‘PREFIX/share/info’ subdirectories.
+
+ It is possible to build a documentation tree in
+‘out-www/online-root/’, with special processing, so it can be used on a
+website with content negotiation for automatic language selection; this
+can be achieved by issuing
+
+ make WEB_TARGETS=online doc
+
+and both ‘offline’ and ‘online’ targets can be generated by issuing
+
+ make WEB_TARGETS="offline online" doc
+
+ Several targets are available to clean the documentation build and
+help with maintaining documentation; an overview of these targets is
+available with
+
+ make help
+
+from every directory in the build tree. Most targets for documentation
+maintenance are available from ‘Documentation/’; for more information,
+see *note (lilypond-contributor)Documentation work::.
+
+ The makefile variable ‘QUIET_BUILD’ may be set to ‘1’ for a less
+verbose build output, just like for building the programs.
+
+Building documentation without compiling
+........................................
+
+The documentation can be built locally without compiling LilyPond
+binary, if LilyPond is already installed on your system.
+
+ From a fresh Git checkout, do
+
+ ./autogen.sh # ignore any warning messages
+ cp GNUmakefile.in GNUmakefile
+ make -C scripts && make -C python
+ nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
+
+ Please note that this may break sometimes – for example, if a new
+feature is added with a test file in input/regression, even the latest
+development release of LilyPond will fail to build the docs.
+
+ You may build the manual without building all the ‘input/*’ stuff
+(i.e. mostly regression tests): change directory, for example to
+‘Documentation/’, issue ‘make doc’, which will build documentation in a
+subdirectory ‘out-www’ from the source files in current directory. In
+this case, if you also want to browse the documentation in its
+post-processed form, change back to top directory and issue
+
+ make out=www WWW-post
+
+
+Known issues and warnings
+.........................
+
+You may also need to create a script for ‘pngtopnm’ and ‘pnmtopng’. On
+GNU/Linux, I use this:
+
+export LD_LIBRARY_PATH=/usr/lib
+exec /usr/bin/pngtopnm "$@"
+
+ On MacOS X with fink, I use this:
+
+export DYLD_LIBRARY_PATH=/sw/lib
+exec /sw/bin/pngtopnm "$@"
+
+ On MacOS X with macports, you should use this:
+
+export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
+exec /opt/local/bin/pngtopnm "$@"
+
+1.6.3 Testing LilyPond binary
+-----------------------------
+
+LilyPond comes with an extensive suite that exercises the entire
+program. This suite can be used to test that the binary has been built
+correctly.
+
+ The test suite can be executed with:
+
+make test
+
+ If the test suite completes successfully, the LilyPond binary has
+been verified.
+
+ More information on the regression test suite is found at *note
+(lilypond-contributor)Regression tests::.
+
+1.7 Problems
+============
+
+For help and questions use <lilypond-user@gnu.org>. Send bug reports to
+<bug-lilypond@gnu.org>.
+
+ Bugs that are not fault of LilyPond are documented here.
+
+Compiling on MacOS X
+--------------------
+
+Here are special instructions for compiling under MacOS X. These
+instructions assume that dependencies are installed using MacPorts.
+(http://www.macports.org/) The instructions have been tested using OS X
+10.5 (Leopard).
+
+ First, install the relevant dependencies using MacPorts.
+
+ Next, add the following to your relevant shell initialization files.
+This is ‘~/.profile’ by default. You should create this file if it does
+not exist.
+
+ export PATH=/opt/local/bin:/opt/local/sbin:$PATH
+ export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
+
+ Now you must edit the generated ‘config.make’ file. Change
+
+ FLEXLEXER_FILE = /usr/include/FlexLexer.h
+
+to:
+
+ FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
+
+ At this point, you should verify that you have the appropriate fonts
+installed with your ghostscript installation. Check ‘ls
+/opt/local/share/ghostscript/fonts’ for: ’c0590*’ files (.pfb, .pfb and
+.afm). If you don’t have them, run the following commands to grab them
+from the ghostscript SVN server and install them in the appropriate
+location:
+
+ svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
+ sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
+ rm -rf urw-fonts-1.07pre44
+
+ Now run the ‘./configure’ script. To avoid complications with
+automatic font detection, add
+
+ --with-fonts-dir=/opt/local/share/ghostscript/fonts
+
+Solaris
+-------
+
+Solaris7, ./configure
+
+ ‘./configure’ needs a POSIX compliant shell. On Solaris7, ‘/bin/sh’
+is not yet POSIX compliant, but ‘/bin/ksh’ or bash is. Run configure
+like
+
+ CONFIG_SHELL=/bin/ksh ksh -c ./configure
+
+or
+
+ CONFIG_SHELL=/bin/bash bash -c ./configure
+
+FreeBSD
+-------
+
+To use system fonts, dejaview must be installed. With the default port,
+the fonts are installed in ‘usr/X11R6/lib/X11/fonts/dejavu’.
+
+ Open the file ‘$LILYPONDBASE/usr/etc/fonts/local.conf’ and add the
+following line just after the ‘<fontconfig>’ line. (Adjust as necessary
+for your hierarchy.)
+
+ <dir>/usr/X11R6/lib/X11/fonts</dir>
+
+International fonts
+-------------------
+
+On Mac OS X, all fonts are installed by default. However, finding all
+system fonts requires a bit of configuration; see this post
+(http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
+on the ‘lilypond-user’ mailing list.
+
+ On Linux, international fonts are installed by different means on
+every distribution. We cannot list the exact commands or packages that
+are necessary, as each distribution is different, and the exact package
+names within each distribution changes. Here are some hints, though:
+
+Red Hat Fedora
+
+ taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
+ ttfonts-zh_CN fonts-ja fonts-hebrew
+
+Debian GNU/Linux
+
+ apt-get install emacs-intl-fonts xfonts-intl-.* \
+ fonts-ipafont-gothic fonts-ipafont-mincho \
+ xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
+
+Using lilypond python libraries
+-------------------------------
+
+If you want to use lilypond’s python libraries (either running certain
+build scripts manually, or using them in other programs), set
+‘PYTHONPATH’ to ‘python/out’ in your build directory, or
+‘.../usr/lib/lilypond/current/python’ in the installation directory
+structure.
+
+1.8 Concurrent stable and development versions
+==============================================
+
+It can be useful to have both the stable and the development versions of
+LilyPond available at once. One way to do this on GNU/Linux is to
+install the stable version using the precompiled binary, and run the
+development version from the source tree. After running ‘make all’ from
+the top directory of the LilyPond source files, there will be a binary
+called ‘lilypond’ in the ‘out’ directory:
+
+ <PATH TO>/lilypond/out/bin/lilypond
+
+ This binary can be run without actually doing the ‘make install’
+command. The advantage to this is that you can have all of the latest
+changes available after pulling from git and running ‘make all’, without
+having to uninstall the old version and reinstall the new.
+
+ So, to use the stable version, install it as usual and use the normal
+commands:
+
+ lilypond foobar.ly
+
+ To use the development version, create a link to the binary in the
+source tree by saving the following line in a file somewhere in your
+‘$PATH’:
+
+ exec <PATH TO>/lilypond/out/bin/lilypond "$@"
+
+ Save it as ‘Lilypond’ (with a capital L to distinguish it from the
+stable ‘lilypond’), and make it executable:
+
+ chmod +x Lilypond
+
+ Then you can invoke the development version this way:
+
+ Lilypond foobar.ly
+
+ TODO: ADD
+
+ - other compilation tricks for developers
+
+1.9 Build system
+================