X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Ftopdocs%2FINSTALL.texi;h=c663700030c51fedcf11dd5d11a0abc715f42e80;hb=7653e2f45f427ecb67ad8231bd5e24afb8d204e4;hp=ebe9ad88b261ede683d3dd547c1b582702809504;hpb=8492f482fe743bce99865bcefbd015bcad43d6cf;p=lilypond.git diff --git a/Documentation/topdocs/INSTALL.texi b/Documentation/topdocs/INSTALL.texi index ebe9ad88b2..c663700030 100644 --- a/Documentation/topdocs/INSTALL.texi +++ b/Documentation/topdocs/INSTALL.texi @@ -2,484 +2,318 @@ @setfilename INSTALL.info @settitle INSTALL - compiling and installing GNU LilyPond -@node Top, , , (dir) -@top +@documentencoding utf-8 +@documentlanguage en -@chapter INSTALL - compiling and installing GNU LilyPond +@node Top +@top +@contents -@section Abstract +@chapter Compiling and installing on Unix -This document explains what you need to install LilyPond, and what you -should do. If you are going to compile and install LilyPond often, -e.g. when doing development, you might want to check out the -@file{buildscripts/set-lily.sh} script. It sets some environment -variables and symlinks, which comes in handly when you have to compile -LilyPond more often. -@section Obtaining +@html + +@end html -You can get the latest version of LilyPond at -@uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/,ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/}. Refer to the links -document for mirror sites. +@section Downloading -@emph{If you upgrade by patching do remember to rerun autoconf after -applying the patch}. +Even numbered minor versions are `stable' (2.6, 2.8, etc), while odd +version are development releases (2.7, 2.9, etc). Building LilyPond +is an involved process. If possible +@uref{http://lilypond.org/install,download a precompiled binary} for +your platform. -If you do not want to download the entire archive for each version, the -safest method for upgrading is to use @file{xdelta}, see -@uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/} +@subsection Source code -The following command produces @file{lilypond-1.1.55.tar.gz} from -@file{lilypond-1.1.54} identical (up to compression dates) to the .55 on -the FTP site. +Download source +@itemize @bullet +@item tarballs from +@uref{http://lilypond.org/download/} by HTTP. +@item tarballs from +@uref{http://download.linuxaudio.org/lilypond/} by HTTP. +@item +GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org} @example - xdelta patch lilypond-1.1.54-1.1.55.xd lilypond-1.1.54.tar.gz +git clone git://git.sv.gnu.org/lilypond.git @end example -@section Prerequisites - -For compilation you need: - -@itemize @bullet -@item A GNU system: GNU LilyPond is known to run on these GNU systems: Linux - (PPC, intel), FreeBSD, AIX, NeXTStep, IRIX, Digital Unix and -Solaris. - -@item Lots of disk space: LilyPond takes between 30 and 100 mb to -compile if you use debugging information. If you are short on -disk-space run configure with @code{--disable-debugging}. - -@item -Although we recommend to use Unix, LilyPond is known to run on Windows -NT/95/98 as well. See Section Windows NT/95,es. - -@item EGCS 1.1 or newer. Check out @uref{ftp://ftp.gnu.org/pub/gcc/}. - -@item Python 1.5, -Check out -@uref{ftp://ftp.python.org} or @uref{ftp://ftp.cwi.nl/pub/python}. - -@item GUILE 1.3, check out @uref{http://www.gnu.org/software/guile/guile.html,http://www.gnu.org/software/guile/guile.html}. - -@item GNU make. -Check out @uref{ftp://ftp.gnu.org/make/,ftp://ftp.gnu.org/make/}. - -@item Flex (version 2.5.4 or newer). -Check out @uref{ftp://ftp.gnu.org/flex/,ftp://ftp.gnu.org/flex/}. - -@item Bison (version 1.25 or newer). -Check out @uref{ftp://ftp.gnu.org/bison/,ftp://ftp.gnu.org/bison/}. - -@item Texinfo. Check out @uref{ftp://ftp.gnu.org/pub/texinfo/,ftp://ftp.gnu.org/pub/texinfo/}. -Most documentation is in texinfo. - -@item The geometry package for LaTeX is needed to use ly2dvi. -Available at -@uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry} -or at mirror site @uref{ftp://ftp.dante.de,ftp://ftp.dante.de} - -@item MetaPost, if you want to use direct PostScript output. Please -note that tetex-0.4pl8 (included with Redhat 5.x) does not include -@file{mfplain.mp}, which is needed for producing the scaleable font files. - -@end itemize - -@section Running - -GNU LilyPond does use a lot of resources. For operation you need the -following software - -@itemize @bullet -@item TeX -@item A PostScript printer and/or viewer (such as Ghostscript) is strongly - recommended. Xdvi will show all embedded PostScript too if you have - Ghostscript installed. -@item GUILE 1.3, check out @uref{http://www.gnu.org/programs/guile.html,http://www.gnu.org/programs/guile.html} -@end itemize - -For running LilyPond successfully you have to help TeX and MetaFont -find various files. The recommended way of doing so is adjusting the -environment variables in the start-up scripts of your shell. An -example is given here for the Bourne shell: -@example -export MFINPUTS="/usr/local/share/lilypond/mf:" -export TEXINPUTS="/usr/local/share/lilypond/tex:/usr/local/share/lilypond/ps:" - -@end example - -The empty path component -represents TeX and MetaFont's default search paths. Scripts with -the proper paths for the bourne and C-shell respectively are generated in -@file{buildscripts/out/lilypond-profile} and -@file{buildscripts/out/lilypond-login} during compilation. - -LilyPond is a hiddeously big, slow and bloated program. A fast CPU -and plenty of RAM is recommended for comfortable use. - -@section Website - -The website is the most convenient form to use for reading the -documentation on-line documentation. It is made by entering @example - - make website - -@end example -This does require a fully functioning - -If you want to auto-generate Lily's website, you'll need some additional -conversion tools. - -@itemize @bullet -@item xpmtoppm (from the Portable Bitmap Utilities) (For RedHat Linux - users: it is included within the package libgr-progs). - the original is at -@uref{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz,ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz} - -@item pnmtopng, which is also in libgr-progs for RedHat. The original is -at -@uref{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz,ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz}.i - -The version of @file{pnmtopng} that is distributed with RedHat 5.1 and -5.2 contains a bug: pnmtopng is dynamically linked to the wrong -version of libpng, which results in cropped images. Recompile it from -source, and make sure that the pnmtopng binary is linked statically to -the libpng that is included in libgr. RedHat 6.0 does not have this -problem. - -@example - tar xzf libgr-2.0.13.tar.gz - make - cd png - rm libpng.so* - make pnmtopng - -@end example - -You can then install the new pnmtopng into @file{/usr/local/bin/} - -@item Bib2html @uref{http://pertsserver.cs.uiuc.edu/~hull/bib2html.,http://pertsserver.cs.uiuc.edu/~hull/bib2html.} - Which, in turn depends on man2html for proper installation. -man2html can be had from @uref{http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05,http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05}. - -The website will build without this utility, but you will not see our -hypertextified bibliography. - -@item Doc++ (optional) to read the source code. - +The repository does not contain generated files. To create +@file{configure}, run +@example +./autogen.sh +@end example @end itemize -@section configuring and compiling - -to install GNU LilyPond, simply type: -@example - - gunzip -c lilypond-x.y.z | tar xf - - cd lilypond-x.y.z - ./configure # fill in your standard prefix with --prefix - make - make install - -@end example - -This will install a number of files, something close to: - -@example - /usr/local/man/man1/mi2mu.1 - /usr/local/man/man1/convert-mudela.1 - /usr/local/man/man1/mudela-book.1 - /usr/local/man/man1/lilypond.1 - /usr/local/bin/lilypond - /usr/local/bin/mi2mu - /usr/local/bin/convert-mudela - /usr/local/bin/mudela-book - /usr/local/bin/abc2ly - /usr/local/share/lilypond/* - /usr/local/share/locale/@{it,nl@}/LC_MESSAGES/lilypond.mo -@end example - +For information on packaging, see @uref{http://lilypond.org/devel}. -The above assumes that you are root and have the GNU development -tools, and your make is GNU make. If this is not the case, you can -adjust your environment variables to your taste: +@subsection Precompiled binary packages -@example +Check out @uref{http://lilypond.org/web/install/} for up to date +information on binary packages for your platform. - export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR" - ./configure - -@end example -@code{CPPFLAGS} are the preprocessor flags. +@section Requirements -The configure script is Cygnus configure, and it will accept -@code{--help}. If you are not root, you will probably have to make it -with a different @code{--prefix} option. Our favourite location is +@subsection Compilation -@example +In addition to the packages needed for running Lilypond (see below), +you need the following extra packages for building. - ./configure --prefix=$HOME/usr - -@end example +When installing a binary package FOO, you may need to install the +FOO-devel, libFOO-dev or FOO-dev package too. -In this case, you will have to set up MFINPUTS, and TEXINPUTS accordingly. +@itemize -Since GNU LilyPond currently is beta, you are advised to also use +@item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer. -@example +@item New Century Schoolbook fonts, as PFB files. These are shipped +with X11 and Ghostscript, and are named @file{c059033l.pfb} +@file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb} - --enable-debugging - --enable-checking - -@end example +@item @uref{http://www.xs4all.nl/~hanwen/mftrace/,mftrace} (1.1.19 or +newer), -Options to configure include: +You will need to install some additional packages to get mftrace to +work. -@table @samp -@item @code{--enable-printing} - Enable debugging print routines (lilypond @code{-D} option) -@item @code{--enable-optimise} - Set maximum optimisation: compile with @code{-O2}. This can be -unreliable on some compiler/platform combinations (eg, DEC Alpha and PPC) -@item @code{--enable-profiling} - Compile with support for profiling. -@item @code{--enable-config} - Output to a different configuration file. Needed for multi-platform - builds -@end table +@item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} +(version 1.6.7 or newer). If you are installing binary packages, you +may need to install guile-devel or guile-dev or libguile-dev too. -All options are documented in the @file{configure} help -The option @code{--enable-optimise} is recommended for Real Life usage. +@item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.8 or newer). -If you do - -@example - - make all - -@end example - -everything will be compiled, but nothing will be installed. The -resulting binaries can be found in the subdirectories @file{out/} (which -contain all files generated during compilation). - -@section configuring for multiple platforms - -If you want to compile LilyPond with different configuration settings, -then, you can use the @code{--enable-config} option. Example: suppose I -want to build with and without profiling. Then I'd use the -following for the normal build, - -@example - - ./configure --prefix=~ --disable-optimise --enable-checking - make - make install - -@end example - -and for the profiling version, I specify a different configuration. +@item +@uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or +newer). -@example +@item @uref{http://www.python.org,Python} (version 2.3 or newer) - ./configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking - make config=optprof - make config=optprof install - -@end example +@item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer). +@item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}. -@section Installing +@item @uref{http://www.gnu.org/software/flex/,Flex} -if you have done a successful @code{make}, then a simple +@item @uref{http://www.perl.org/,Perl} -@example +@item @uref{http://www.gnu.org/software/flex/,GNU Bison} - make install - -@end example +@item All packages required for running, including development packages with +header files and libraries. -should do the trick. +@end itemize -If you are doing an upgrade, please remember to remove obsolete -@file{.pk} and @file{.tfm} files of the fonts. A script has been -provided to do the work for you, see @file{bin/clean-fonts.sh}. +@subsection Running requirements +Running LilyPond requires proper installation of the following +software -@section Redhat linux +@itemize @bullet -RedHat Linux users can compile an RPM. A spec file is in -@file{make/out/lilypond.spec}, it is distributed along with the -sources. +@item @uref{http://www.freetype.org/,Freetype} (version 2). +@item @uref{http://www.freetype.org/,FontConfig} (version 2.2). +@item @uref{http://www.pango.org/,Pango} (version 1.12 or newer). +@item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} +(version 1.8.0 or newer). +@item @uref{http://www.python.org,Python} (version 2.4 or newer). +@item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or +newer. 8.50 recommended) +@end itemize -You can make the rpm by issuing -@example +@subsection Building documentation - rpm -tb lilypond-x.y.z.tar.gz - rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z - -@end example +You can view the documentation online at +@uref{http://lilypond.org/doc/}, but you can also build it locally. +This process requires a successful compile of lilypond. The +documentation is built by issuing +@quotation +@example +make web +@end example +@end quotation -Precompiled i386 RedHat RPMS are available from -@uref{ftp://freshmeat.net/pub/rpms/lilypond/,ftp://freshmeat.net/pub/rpms/lilypond/} and -@uref{http://linux.umbc.edu/software/lilypond/rpms/,http://linux.umbc.edu/software/lilypond/rpms/}. +Building the website requires some additional tools and packages -For compilation on a RedHat system you need these packages, -in addition to the those needed for running: @itemize @bullet -@item glibc-devel -@item libstdc++-devel -@item guile-devel -@item flex -@item bison -@item texinfo +@item The @uref{http://netpbm.sourceforge.net/,netpbm utilities} +@item ImageMagick +@item International fonts (see input/regression/utf-8.ly for hints +about which font packages are necessary for your platform) +@item Ghostscript, 8.50 with the patch from +@uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154} +and the patch from +@uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}. @end itemize -@section Debian GNU/linux - -A Debian package is also available; contact Anthony Fok -@email{foka@@debian.org}. The build scripts are in the subdirectory -@file{debian/}. - -@section Windows NT/95 - -Separate instructions on building for W32 are available; See file -README-W32, included with the sources. - -@c I detest the use of euphemisms, esp. for BUGS -@section Bugs and Problems - -For help and questions use @email{help-gnu-music@@gnu.org} and -@email{gnu-music-discuss@@gnu.org}. Please consult the faq before -mailing your problems. +The HTML files can be installed into the standard documentation path +by issuing -If you find bugs, please send bug reports to -@email{bug-gnu-music@@gnu.org}. +@quotation +@example +make out=www web-install +@end example +@end quotation -Known bugs that are LilyPond's fault are listed in @file{TODO}, or -demonstrated in @file{input/bugs/}. -Known bugs that are not LilyPond's fault are documented here. +@section Building LilyPond -@unnumbered All platforms -@table @bullet -@item GUILE 1.3.2 -Guile 1.3.2 is buggy in several respects. Do not use it for LilyPond. -@end table +To install GNU LilyPond, type +@quotation +@example +gunzip -c lilypond-x.y.z | tar xf - +cd lilypond-x.y.z +./configure # run with --help for applicable options +make +make install +@end example +@end quotation -@unnumbered LinuxPPC Bugs: +If you are not root, you should choose a @code{--prefix} argument that +points into your home directory, e.g. +@quotation +@example +./configure --prefix=$HOME/usr +@end example +@end quotation -@table @bullet -@item R5, egcs-1.1.2-12c -Egcs-1.1.2-12c (stock LinuxPPC R5) has a serious bug, upgrade to -fixed in egcs-1.1.2-12f or gcc-2.95-0a, @uref{ftp://dev.linuxppc.org/users/fsirl/R5/RPMS/ppc/} -@item R4, egcs-1.0.2 -All compiling with @code{-O2} is suspect, in particular guile-1.3, and -Lily herself will break. -@end table +@subsection Configuring for multiple platforms +If you want to build multiple versions of LilyPond with different +configuration settings, you can use the @code{--enable-config=CONF} +option of configure. You should use @samp{make conf=CONF} to generate +the output in @file{out-CONF}. Example: Suppose you want to build +with and without profiling, then use the following for the normal +build +@quotation +@example +./configure --prefix=$HOME/usr/ --enable-checking +make +make install +@end example +@end quotation -@unnumbered Linux-i386 +and for the profiling version, specify a different configuration -@table @bullet -@item SuSE6.2 and similar platforms (glibc 2.1, libstdc++ 2.9.0) +@quotation +@example +./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking +make conf=prof +make conf=prof install +@end example +@end quotation -Lily will crash during parsing (which suggests a C++ library -incompatibility). Precise cause, precise platform description or -solution are not known. -Note that this only happens on some computers with the said platform. +@section Emacs mode -@item GUILE -A binary RPM of Guile 1.3 has been distributed from the LilyPond ftp -site. This binary was made in RedHat 5.x, and it will fail if this -RPM is used with RedHat 6.x. +An Emacs mode for entering music and running LilyPond is contained in +the source archive in the @file{elisp} directory. Do @command{make +install} to install it to @var{elispdir}. The file @file{lilypond-init.el} +should be placed to @var{load-path}@file{/site-start.d/} or appended +to your @file{~/.emacs} or @file{~/.emacs.el}. +As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to +your @var{load-path} by appending the following line (as modified) to your +@file{~/.emacs} +@c any reason we do not advise: (push "~/site-lisp" load-path) +@quotation +@example +(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path)) +@end example +@end quotation -@item libg++ 2.7 -LilyPond occasionally crashes while parsing the initialisation files. -This is a very obscure bug, and usually entering the commandline -differently "fixes" it. +@section Vim mode -@example - lilypond input.ly -@end example +A Vim mode for entering music and running LilyPond is contained in the +source archive in @code{$VIM} directory. -and +The LilyPond file type is detected if the file @file{~/.vim/filetype.vim} @c +has the following content +@quotation @example - lilypond -I. ./input.ly +if exists("did_load_filetypes") + finish +endif +augroup filetypedetect + au! BufNewFile,BufRead *.ly setf lilypond +augroup END @end example -makes a difference +@end quotation + +Please include this path by appending the following line to your +@file{~/.vimrc} -Typical stacktrace: +@quotation @example - SIGSEGV - __libc_malloc (bytes=16384) - ?? () - yyFlexLexer::yy_create_buffer () - Includable_lexer::new_input (this=0x8209a00, s=@{strh_ = @{ +set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/ @end example +@end quotation -This behaviour has been observed with machines that have old libg++ -versions (LinuxPPC feb '98, RedHat 4.x). -@end table +@noindent +where $@{LILYPOND_VERISON@} is your lilypond version. If Lilypond was not +installed in @file{/usr/local/}, then change this path accordingly. +@section Problems +For help and questions use @email{lilypond-user@@gnu.org}. Send bug +reports to @email{bug-lilypond@@gnu.org}. -@unnumbered Solaris: +Bugs that are not fault of LilyPond are documented here. -@table @bullet -@item Sparc64/Solaris 2.6, GNU make-3.77 +@subsection Bison 1.875 -GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer. +There is a bug in bison-1.875: compilation fails with "parse error +before `goto'" in line 4922 due to a bug in bison. To fix, please +recompile bison 1.875 with the following fix + +@quotation +@example +$ cd lily; make out/parser.cc +$ vi +4919 out/parser.cc +# append a semicolon to the line containing "__attribute__ ((__unused__)) +# save +$ make +@end example +@end quotation -@item Sparc64/Solaris 2.6, ld +@unnumberedsubsec MacOS X -Not yet resolved. -@end table +For Fink, use the following command to compile. +@verbatim +export GUILE=guile-1.6 +export GUILE_CONFIG=guile-1.6-config +export PKG_CONFIG_PATH=/sw/lib/freetype219/lib/pkgconfig/:/sw/lib/fontconfig2/lib/pkgconfig/ +./configure +@end verbatim -@unnumbered AIX +@unnumberedsubsec Solaris -@table @bullet -@item AIX 4.3 ld +@itemize @bullet +@item Solaris7, ./configure -The following is from the gcc install/SPECIFIC file. +@file{./configure} needs a POSIX compliant shell. On Solaris7, +@file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash +is. Run configure like @quotation - Some versions of the AIX binder (linker) can fail with a relocation - overflow severe error when the -bbigtoc option is used to link - GCC-produced object files into an executable that overflows the TOC. A - fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND - -BBIGTOC) is available from IBM Customer Support and from its - 27service.boulder.ibm.com website as PTF U455193. - - Binutils does not support AIX 4.3 (at least through release 2.9). GNU - as and GNU ld will not work properly and one should not configure GCC - to use those GNU utilities. Use the native AIX tools which do - interoperate with GCC. +@example + CONFIG_SHELL=/bin/ksh ksh -c ./configure +@end example @end quotation - -add -Wl,-bbigtoc to USER_LDFLAGS, ie: +or +@quotation @example - LDFLAGS='-Wl,-bbigtoc' ./configure + CONFIG_SHELL=/bin/bash bash -c ./configure @end example +@end quotation -@end table - - -@section Authors - -@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys} - -@email{janneke@@gnu.org, Jan Nieuwenhuizen} - -In case of problems, please use the mailing list for help. - -Have fun! +@end itemize @bye +