X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fincluded%2Fcompile.itexi;h=c3aa45de1cffeaaae70ba9c589b04c9e68eec87c;hb=5f2e79bd78f7c350167e61e38123d7a7db7ce362;hp=498bbfd33875d0984011b5ec268743491f43e7c2;hpb=b3f0fb668fac39d49a3aeb61b689a362d21d0605;p=lilypond.git diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi index 498bbfd338..c3aa45de1c 100644 --- a/Documentation/included/compile.itexi +++ b/Documentation/included/compile.itexi @@ -7,7 +7,6 @@ @c @n ode Compiling from source @c @s ection Compiling from source - @menu * Overview of compiling:: * Requirements:: @@ -17,7 +16,6 @@ * Post-compilation options:: * Problems:: * Concurrent stable and development versions:: -* Using a Virtual Machine to Compile LilyPond:: * Build system:: @end menu @@ -44,8 +42,8 @@ program. For more information, see @ref{Building documentation without compiling}. Attempts to compile LilyPond natively on Windows have been -unsuccessful, though a workaround is available (see @ref{Using a -Virtual Machine to Compile LilyPond}). +unsuccessful, though a workaround is available (see +@rcontrib{Lilydev}). @node Requirements @@ -141,7 +139,9 @@ python@var{version}-dev @item @uref{http://flex.sourceforge.net/, Flex} @item @uref{http://fontforge.sf.net/, FontForge} (20060125 or -newer) +newer; 20100501 or newer is recommended; must be compiled +with @option{--enable-double}. Failure to do so can lead to +poor intersection calculations and poorly-rendered glyphs.) @item @uref{http://www.gnu.org/software/bison/, GNU Bison} @@ -284,7 +284,7 @@ download and install the free-software @menu * Running ./autogen.sh:: -* Running ./configure:: +* Running ../configure:: @end menu @@ -300,50 +300,65 @@ Next, you need to create the generated files; enter the following command from your top source directory: @example -./autogen.sh +./autogen.sh --noconfigure @end example -This will: - -@enumerate -@item generate a number of files and directories to aid +This will generate a number of files and directories to aid configuration, such as @file{configure}, @file{README.txt}, etc. -@item automatically run the @command{./configure} command. -@end enumerate +Next, create the build directory with: +@example +mkdir build/ +cd build/ +@end example + +We heavily recommend building lilypond inside a separate directory +with this method. + + +@node Running ../configure +@subsection Running @command{../configure} -@node Running ./configure -@subsection Running @command{./configure} @menu * Configuration options:: * Checking build dependencies:: * Configuring target directories:: -* Making an out-of-tree build:: @end menu @node Configuration options @unnumberedsubsubsec Configuration options -The @command{./configure} command (generated by +@warning{make sure that you are in the @file{build/} subdirectory +of your source tree.} + +The @command{../configure} command (generated by @command{./autogen.sh}) provides many options for configuring @command{make}. To see them all, run: @example -./configure --help +../configure --help @end example @node Checking build dependencies @unnumberedsubsubsec Checking build dependencies -When @command{./configure} is run without any arguments, it will +@warning{make sure that you are in the @file{build/} subdirectory +of your source tree.} + +When @command{../configure} is run without any arguments, it will check to make sure your system has everything required for -compilation. This is done automatically when -@command{./autogen.sh} is run. If any build dependency is -missing, @command{./configure} will return with: +compilation: + +@example +../configure +@end example + +If any build dependency is missing, @command{../configure} will +return with: @example ERROR: Please install required programs: @var{foo} @@ -359,7 +374,7 @@ WARNING: Please consider installing optional programs: @var{bar} If you intend to build the documentation locally, you will need to install or update these programs accordingly. -@warning{@command{./configure} may fail to issue warnings for +@warning{@command{../configure} may fail to issue warnings for certain documentation build requirements that are not met. If you experience problems when building the documentation, you may need to do a manual check of @ref{Requirements for building @@ -369,22 +384,25 @@ documentation}.} @node Configuring target directories @unnumberedsubsubsec Configuring target directories +@warning{make sure that you are in the @file{build/} subdirectory +of your source tree.} + If you intend to use your local build to install a local copy of the program, you will probably want to configure the installation directory. Here are the relevant lines taken from the output of -@command{./configure@tie{}--help}: +@command{../configure@tie{}--help}: @quotation By default, `@command{make@tie{}install}' will install all the files in @file{/usr/local/bin}, @file{/usr/local/lib} etc. You can specify an installation prefix other than @file{/usr/local} -using `@code{--prefix}', for instance `@code{--prefix=$HOME}'. +using `@option{--prefix}', for instance `@option{--prefix=$HOME}'. @end quotation A typical installation prefix is @file{$HOME/usr}: @example -./configure --prefix=$HOME/usr +../configure --prefix=$HOME/usr @end example Note that if you plan to install a local build on a system where @@ -401,28 +419,11 @@ already included. It is also possible to specify separate installation directories for different types of program files. See the full output of -@command{./configure@tie{}--help} for more information. +@command{../configure@tie{}--help} for more information. If you encounter any problems, please see @ref{Problems}. -@node Making an out-of-tree build -@unnumberedsubsubsec Making an out-of-tree build - -It is possible to compile LilyPond in a build tree different from -the source tree, using the @option{--srcdir} option of -@command{configure}. Note that in some cases you may need to -remove the output of a previous @command{configure} command by -running @command{make@tie{}distclean} in the main source directory -before configuring the out-of-tree build: - -@example -make distclean -mkdir lily-build && cd lily-build -@var{sourcedir}/configure --srcdir=@var{sourcedir} -@end example - - @node Compiling LilyPond @section Compiling LilyPond @@ -438,6 +439,9 @@ mkdir lily-build && cd lily-build @node Using make @subsection Using @command{make} +@warning{make sure that you are in the @file{build/} subdirectory +of your source tree.} + LilyPond is compiled with the @command{make} command. Assuming @command{make} is configured properly, you can simply run: @@ -479,9 +483,9 @@ that case, running @samp{make} without the @option{-j} is advised. If you want to build multiple versions of LilyPond with different configuration settings, you can use the -@code{--enable-config=@var{CONF}} option of @command{configure}. -You should use @code{make@tie{}conf=@var{CONF}} to generate the -output in @file{out-@var{CONF}}. For example, suppose you want to +@option{--enable-config=@var{conf}} option of @command{configure}. +You should use @code{make@tie{}conf=@var{conf}} to generate the +output in @file{out-@var{conf}}. For example, suppose you want to build with and without profiling, then use the following for the normal build @@ -572,6 +576,7 @@ re-install. See @ref{Configuring target directories}. @menu * Documentation editor's edit/compile cycle:: * Building documentation:: +* Building a single document:: * Saving time with CPU_COUNT:: * AJAX search:: * Installing documentation:: @@ -600,16 +605,20 @@ Edit/compile cycle: make [-j@var{X}] @emph{## needed if editing outside} @emph{## Documentation/, but useful anyway} @emph{## for finding Texinfo errors.} -touch Documentation/*te?? @emph{## bug workaround} make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## usually faster than initial build.} @end example @item Reset: -@example -make doc-clean @emph{## use only as a last resort.} -@end example +In some cases, it is possible to clean the compiled documentation +with @samp{make@tie{}doc-clean}, but this method is not guaranteed +to fix everything. Instead, we recommend that you delete your +@file{build/} directory, and begin compiling from scratch. Since +the documentation compile takes much longer than the +non-documentation compile, this does not increase the overall time +by a great deal. + @end itemize @node Building documentation @@ -637,6 +646,25 @@ the docs. Please do not complain about anything which is broken in those places; the only complete set of documentation is in @file{out-www/offline-root/} from the top of the source tree. +@code{make doc} compiles the documents for all languages. To save +some compile time, the English language documents can be compiled +on their own with: + +@example +make LANGS='' doc +@end example + +@noindent 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: + +@example +make LANGS='de fr' doc +@end example + +@noindent Note that this will also compile the English version. + Compilation of documentation in Info format with images can be done separately by issuing: @@ -687,6 +715,33 @@ However, this will rebuild all of the manuals indiscriminately---it is more efficient to @command{touch} only the affected files. +@noindent +Another typical issue when switching branches between master and +lilypond/translation is the appearance/disappearance of translated +versions of some manuals. If you see such a warning from make: + +@example +No rule to make target `X', needed by `Y' +@end example + +@noindent +Your best bet is to delete the file Y.dep and to try again. + +@node Building a single document +@unnumberedsubsubsec Building a single document +It's possible to build a single document. For example, to rebuild +only @file{contributor.pdf}, do the following: + +@example +cd build/ +cd Documentation/ +touch ../../Documentation/contributor.texi +make out=www out-www/contributor.pdf +@end example + +If you are only working on a single document, test-building it in +this way can give substantial time savings - recreating +@file{contributor.pdf}, for example, takes a matter of seconds. @node Saving time with CPU_COUNT @unnumberedsubsubsec Saving time with @code{CPU_COUNT} @@ -916,7 +971,7 @@ export PATH=/opt/local/bin:/opt/local/sbin:$PATH export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH @end example -Now you must edit the generated @code{config.make} file. Change +Now you must edit the generated @file{config.make} file. Change @example FLEXLEXER_FILE = /usr/include/FlexLexer.h @@ -1076,119 +1131,6 @@ TODO: ADD - other compilation tricks for developers -@node Using a Virtual Machine to Compile LilyPond -@section Using a Virtual Machine to Compile LilyPond - - -TODO: rewrite for lily-git.tcl !!! do before GOP! -gp - -Since it is not possible to compile Lilypond on Windows, some -developers may find it useful to install a GNU/Linux virtual -machine. A disk image with a special remix of @strong{Ubuntu} -has been created for this purpose. It has all of the Lilypond -build dependencies in place, so that once installed, it is -ready to compile both Lilypond and the Documentation. -The @code{lilybuntu} remix is available for download here: - -@example -@uref{http://@/files.lilynet.net/@/lilybuntu.iso} -@end example - -We do not necessarily recommend any one virtualization tool, -however the @code{lilybuntu} remix is known to work well on -@uref{http://www.virtualbox.org/wiki/Downloads, Sun VirtualBox}, -which is a free download. Consult your virtualization software's -documentation for instructions on setting up the software and -for general instructions on installing a virtual machine. - -Steps to setting up @code{lilybuntu} in a virtual machine: - -@enumerate -@item Download the @code{lilybuntu} disk image. - -@item Install @code{lilybuntu}. You will use the @code{.iso} -file as the boot disk. It should not be necessary to burn it -to a DVD, but consult the documentation for your virtualization -software for specific instructions. If possible, use at least 500 -MB of RAM (1GB would be better!) for the virtual machine, and use -a dynamically expanding virtual hard drive. -A virtual hard drive with 6 GB will be enough to compile LilyPond, -but if you intend to build the docs and run the regression tests -the virtual hard drive should be at least 10 GB. -The Ubuntu installation should be straightforward, although in the -partitioning stage do not be afraid to select @qq{use entire disk,} -since this is only your @strong{virtual disk} and not your -machine's actual hard drive. - -@item After installation is complete, restart the virtual -machine. If you are using @strong{VirtualBox}, you may wish -to install the @qq{Guest Additions}, which while not essential for -compiling @code{Lilypond} will allow you to use the virtual machine -in full screen, Seamless mode (also known as Unity mode on other -virtualization platforms) and allow you to share clipboards between -the physical and virtual machine. From the @code{Devices} menu select -@code{Install Guest Additions...}, the @code{VBOXADDITIONS} CDROM device -will appear on the desktop. Open a @strong{terminal} session. -(@code{Applications > Accessories > Terminal}) and @code{cd} to the -top level of the CDROM. Run the @code{autorun.sh} script as superuser -(@code{sudo ./autorun.sh }), a console window will open while the -@qq{Guest Additions} are being installed. Once the script has -been finished, reboot your Virtual Machine to complete the installation -of the @qq{Guest Additions}. - -@item Open a @strong{terminal} session. -(@code{Applications > Accessories > Terminal}) - -@item Open @strong{Firefox} (there's an icon for it on the -panel at the top of the screen) and go to the online Lilypond -@uref{http://lilypond.org/doc/latest/Documentation/contributor/, -Contributor's Guide}. - -@item To retrieve the Lilypond source code from @code{git}, -copy-and-paste each command from the CG @qq{Main source code} -section into the terminal (paste into the terminal with keystroke -@code{CTRL+SHIFT+V}). - -@item Prepare to build Lilypond by running the configuration script. -Type - -@example -./autogen.sh -@end example - -When it is finished you should be presented -with the three most common @code{make} options: - -@example -Type: - make all to build LilyPond - make install to install LilyPond - make help to see all possible targets - -Edit local.make for local Makefile overrides. -@end example - -@item First type @code{make all} to build Lilypond. This will take -a while. - -@item When Lilypond is finished building, build the documentation -by typing - -@example -make doc -@end example - -Depending on your system specs it could take from 30-60 minutes -to finish. - -@end enumerate - -At this point everything has been compiled. -You may install Lilypond using @code{make install}, or you may wish -to set up your system with concurrent stable and development -versions as described in the previous section. - - @node Build system @section Build system @@ -1207,7 +1149,7 @@ made with @command{scripts/build/create-version-itexi.py} and@* @item used extensively in the @code{WEBSITE_ONLY_BUILD} version of the -website (made with website.make, used on lilypond.org) +website (made with @file{website.make}, used on lilypond.org) @item not (?) used in the main docs?