@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
+<a name="download-source">
+@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
+
projects / lilypond.git / blobdiff