@setfilename INSTALL.info
@settitle INSTALL - compiling and installing GNU LilyPond
-@node Top, , , (dir)
-@top
-
-@chapter INSTALL - compiling and installing GNU LilyPond
-
-
-@section Abstract
-
-TODO: document xdeltas
-
-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
-
-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.
-
-@emph{If you upgrade by patching do remember to rerun autoconf after
-applying the patch}.
-
-@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}.
-
-Although we recommend to use Unix, LilyPond is known to run on Windows
-NT/95/98 as well. See Section Windows NT/95,es.
+@documentencoding utf-8
+@documentlanguage en
-@item EGCS 1.1 or newer. Check out @uref{ ftp://ftp.gnu.org/pub/gcc/, ftp://ftp.gnu.org/pub/gcc/}
-
-@item Python 1.5,
-Check out
-@uref{ftp://ftp.python.org,ftp://ftp.python.org} or @uref{ftp://ftp.cwi.nl/pub/python,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
+@node Top
+@top
-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
+@contents
-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.
+@chapter Compiling and installing on Unix
-LilyPond is a hiddeously big, slow and bloated program. A fast CPU
-and plenty of RAM is recommended for comfortable use.
-@section Website
+@html
+<a name="download-source">
+@end html
-The website is the most convenient form to use for reading the
-documentation on-line documentation. It is made by entering @example
+@section Downloading
- make website
-
-@end example
-This does require a fully functioning
+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 want to auto-generate Lily's website, you'll need some additional
-conversion tools.
+@subsection Source code
+Download source
@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.
-
+@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
+git clone git://git.sv.gnu.org/lilypond.git
+@end example
+
+The repository does not contain generated files. To create
+@file{configure}, run
+@example
+./autogen.sh
+@end example
@end itemize
-You also have to install @file{buildscripts/out/ps-to-gifs} in a
-directory that is in the path.
-
-@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/share/lilypond/*
- /usr/local/share/locale/@{it,nl@}/LC_MESSAGES/lilypond.mo
-
-@end example
-
-
-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:
-
-@example
-
- export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
- ./configure
-
-@end example
-
-@code{CPPFLAGS} are the preprocessor flags.
-
-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
-
-@example
+For information on packaging, see @uref{http://lilypond.org/devel}.
- ./configure --prefix=$HOME/usr
-
-@end example
+@subsection Precompiled binary packages
-In this case, you will have to set up MFINPUTS, and TEXINPUTS accordingly.
+Check out @uref{http://lilypond.org/web/install/} for up to date
+information on binary packages for your platform.
-Since GNU LilyPond currently is beta, you are advised to also use
-@example
+@section Requirements
- --enable-debugging
- --enable-checking
-
-@end example
+@subsection Compilation
-Options to configure include:
+In addition to the packages needed for running Lilypond (see below),
+you need the following extra packages for building.
-@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
+When installing a binary package FOO, you may need to install the
+FOO-devel, libFOO-dev or FOO-dev package too.
-All options are documented in the @file{configure} help
-The option @code{--enable-optimise} is recommended for Real Life usage.
+@itemize
-If you do
+@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}
- make all
-
-@end example
+@item @uref{http://www.xs4all.nl/~hanwen/mftrace/,mftrace} (1.1.19 or
+newer),
-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).
+You will need to install some additional packages to get mftrace to
+work.
-@section configuring for multiple platforms
+@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.
-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,
+@item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.8 or newer).
-@example
+@item
+@uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or
+newer).
- ./configure --prefix=~ --disable-optimise --enable-checking
- make
- make install
-
-@end example
+@item @uref{http://www.python.org,Python} (version 2.3 or newer)
-and for the profiling version, I specify a different configuration.
+@item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
-@example
+@item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
- ./configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking
- make config=optprof
- make config=optprof install
-
-@end example
+@item @uref{http://www.gnu.org/software/flex/,Flex}
+@item @uref{http://www.perl.org/,Perl}
-@section Installing
+@item @uref{http://www.gnu.org/software/flex/,GNU Bison}
-if you have done a successful @code{make}, then a simple
+@item All packages required for running, including development packages with
+header files and libraries.
-@example
-
- make install
-
-@end example
-
-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
-@unnumberedsec CAVEATS
-
+Running LilyPond requires proper installation of the following
+software
@itemize @bullet
-@item The -O2 option triggers bugs on various platforms (PowerPC, Alpha).
- If you experience problems, you should first try turning off
- this.
-@item On PPC you need at least EGCS-1.1.2f.
-@end itemize
-@section Redhat linux
-
-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/}.
+The HTML files can be installed into the standard documentation path
+by issuing
+
+@quotation
+@example
+make out=www web-install
+@end example
+@end quotation
+
+
+@section Building LilyPond
+
+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
+
+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
+
+
+@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
+
+and for the profiling version, specify a different configuration
+
+@quotation
+@example
+./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
+make conf=prof
+make conf=prof install
+@end example
+@end quotation
+
+
+@section Emacs mode
+
+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
+
+
+@section Vim mode
+
+A Vim mode for entering music and running LilyPond is contained in the
+source archive in @code{$VIM} directory.
+
+The LilyPond file type is detected if the file @file{~/.vim/filetype.vim} @c
+has the following content
+@quotation
+@example
+if exists("did_load_filetypes")
+ finish
+endif
+augroup filetypedetect
+ au! BufNewFile,BufRead *.ly setf lilypond
+augroup END
+@end example
+@end quotation
+
+Please include this path by appending the following line to your
+@file{~/.vimrc}
+
+@quotation
+@example
+set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
+@end example
+@end quotation
+
+@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}.
+
+Bugs that are not fault of LilyPond are documented here.
+
+@subsection Bison 1.875
+
+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
-@section Windows NT/95
-Separate instructions on building for W32 are available; See file
-README-W32, included with the sources.
+@unnumberedsubsec MacOS X
+
+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
-@section Bugs
+@unnumberedsubsec Solaris
-Send bug reports to bug-gnu-music@@gnu.org. For help and questions use
-help-gnu-music@@gnu.org and gnu-music-discuss@@gnu.org. Please consult
-the faq before mailing your problems.
-
-@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.
+@itemize @bullet
+@item Solaris7, ./configure
+
+@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
+@example
+ CONFIG_SHELL=/bin/ksh ksh -c ./configure
+@end example
+@end quotation
+or
+@quotation
+@example
+ CONFIG_SHELL=/bin/bash bash -c ./configure
+@end example
+@end quotation
-Have fun!
+@end itemize
@bye
+
projects / lilypond.git / blobdiff