X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=INSTALL.txt;h=2a431f3a5c0a8c6d9eb00db2c5f15db14fcb0160;hb=7ad8b6d5db629f678cfc5c65bda27ea5ca9824dc;hp=97f4d4d3593a786d17891dd1c8adaadc5caff4f2;hpb=4eb6f42fc6ca20d65c788a73eb78dfcc22ea0453;p=lilypond.git diff --git a/INSTALL.txt b/INSTALL.txt index 97f4d4d359..2a431f3a5c 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -3,6 +3,16 @@ INSTALL - compiling and installing GNU LilyPond *********************************************** +Abstract +======== + + 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 +`buildscripts/set-lily.sh' script. It sets some environment variables +and symlinks, which comes in handly when you have to compile LilyPond +more often. + Obtaining ========= @@ -10,321 +20,363 @@ Obtaining ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/ (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/). - There are three options for downloading sources. - - * if you don't have any version, then you can download the entire - `.tar.gz' file. + _If you upgrade by patching do remember to rerun autoconf after +applying the patch_. - * if you have an unpacked source tree of a previous version, you - may use the diffs . + If you do not want to download the entire archive for each version, +the safest method for upgrading is to use `xdelta', see +`ftp://ftp.xcf.berkeley.edu/pub/xdelta/'. - _If you upgrade by patching do remember to rerun autoconf after - applying the patch_. + The following command produces `lilypond-1.1.55.tar.gz' from +`lilypond-1.1.54' identical (up to compression dates) to the .55 on the +FTP site. + xdelta patch lilypond-1.1.54-1.1.55.xd lilypond-1.1.54.tar.gz - * if you have the `.tar.gz' file of a previous release, you can use - xdelta (ftp://ftp.xcf.berkeley.edu/pub/xdelta/). This is much - safer than using normal diffs, and is the recommended way. - - The following command produces `lilypond-1.3.122.tar.gz' from - `lilypond-1.3.121' identical (up to compression dates) to the .122 - on the FTP site. - xdelta patch lilypond-1.3.121-1.3.122.xd lilypond-1.3.121.tar.gz - -Build requirements -================== +Prerequisites +============= - This document describes how to build LilyPond on Unix platforms. It -is also known to run and compile on Windows NT/95/98 as well. More -information on this topic can be found at Jan's windows page -(http://appel.lilypond.org/lilypond/gnu-windows/). + For compilation you need: - You need the following packages to compile Lilypond. + * A GNU system: GNU LilyPond is known to run on these GNU systems: + Linux (PPC, intel), FreeBSD, AIX, NeXTStep, IRIX, Digital Unix + and Solaris. - * A reasonably new C++ compiler: EGCS 1.1, GCC 2.95.2 or newer. - Check out the gcc site (ftp://ftp.gnu.org/gnu/gcc/). + * 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 `--disable-debugging'. - * Python 1.5, Check out the python website (http://www.python.org). + * Although we recommend to use Unix, LilyPond is known to run on + Windows NT/95/98 as well. See Section Windows NT/95,es. - * GUILE 1.3.4 or newer, check out the GUILE webpage - (http://www.gnu.org/software/guile/guile.html). Version 1.4 is - recommended for better performance. + * EGCS 1.1 or newer. Check out `ftp://ftp.gnu.org/pub/gcc/'. - * GNU Make. Check out the GNU make FTP directory - (ftp://ftp.gnu.org/gnu/make/). + * Python 1.5, Check out `ftp://ftp.python.org' or + `ftp://ftp.cwi.nl/pub/python'. - * Flex (version 2.5.4a or newer). Check out the Flex webpage - (http://www.gnu.org/software/flex/). + * GUILE 1.3.4, check out + http://www.gnu.org/software/guile/guile.html + (http://www.gnu.org/software/guile/guile.html). - * Bison (version 1.25 or newer). Check out the bison webpage - (http://www.gnu.org/software/bison/) + * GNU make. Check out ftp://ftp.gnu.org/make/ + (ftp://ftp.gnu.org/make/). - * TeX. + * Flex (version 2.5.4 or newer). Check out ftp://ftp.gnu.org/flex/ + (ftp://ftp.gnu.org/flex/). - If you want LilyPond to use kpathsea support (recommended), make - sure you have tetex 1.0 or newer (1.0.6 is known to work). You - may need to install a tetex-devel or tetex-dev package too. + * Bison (version 1.25 or newer). Check out ftp://ftp.gnu.org/bison/ + (ftp://ftp.gnu.org/bison/). - * Texinfo (version 4.0 or newer). The documentation of lily is - written in texinfo. Check out the texinfo FTP directory - (ftp://ftp.gnu.org/gnu/texinfo/). + * Texinfo. Check out ftp://ftp.gnu.org/pub/texinfo/ + (ftp://ftp.gnu.org/pub/texinfo/). Most documentation is in + texinfo. - * The geometry package for LaTeX is needed to use ly2dvi. It is - available at the FTP directory for `geometry' - (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry). - This package is normally included with the TeX distribution. + * The geometry package for LaTeX is needed to use ly2dvi. Available + at + 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 ftp://ftp.dante.de (ftp://ftp.dante.de) - * MetaPost, needed for generating PostScript fonts. Please note that - tetex-0.4pl8 (included with Red Hat 5.x) does not include - `mfplain.mp', which is needed for producing the scalable font + * MetaPost, if you want to use direct PostScript output. Please note + that tetex-0.4pl8 (included with Redhat 5.x) does not include + `mfplain.mp', which is needed for producing the scaleable font files. - If you don't have MetaPost and don't want to use PostScript - output, then edit `mf/GNUmakefile', removing the line saying - `PFA_FILES='. - * kpathsea, a library for searching (TeX) files. `kpathsea' is - usually included with your installation of TeX. - - -Running requirements -==================== +Running +======= GNU LilyPond does use a lot of resources. For operation you need the following software - * TeX. + * TeX - * Xdvi and ghostscript + * A PostScript printer and/or viewer (such as Ghostscript) is + strongly recommended. Xdvi will show all embedded PostScript + too if you have Ghostscript installed. - * GUILE 1.3.4, or newer. Check out the GUILE webpage - (http://www.gnu.org/software/guile.html) + * GUILE 1.3.4, check out http://www.gnu.org/software/guile/ + (http://www.gnu.org/programs/guile.html) 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. Appropriate -Csh and bourne sh scripts are left in -`buildscripts/out/lilypond-profile' and -`buildscripts/out/lilypond-login' after compilation. +environment variables in the start-up scripts of your shell. An +example is given here for the Bourne shell: + export MFINPUTS="/usr/local/share/lilypond/mf:" + export TEXINPUTS="/usr/local/share/lilypond/tex:/usr/local/share/lilypond/ps:" - LilyPond is a big and slow program. A fast CPU and plenty of RAM is -recommended for comfortable use. + 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 `buildscripts/out/lilypond-profile' and +`buildscripts/out/lilypond-login' during compilation. -Website requirements -==================== + LilyPond is a hiddeously big, slow and bloated program. A fast CPU +and plenty of RAM is recommended for comfortable use. - The documentation comes in the form of a website. You can view this -website on the internet, but you can also build it locally. This process -requires a successful compile of lilypond. The website is built by -issuing +Website +======= - make web-doc + The website is the most convenient form to use for reading the +documentation on-line documentation. It is made by entering - Building the website requires some additional tools: + make website + This does require a fully functioning - * xpmtoppm (from the netpbm package: the Portable Bitmap Utilities). - The original is at the netpbm FTP site - (ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz) + If you want to auto-generate Lily's website, you'll need some +additional conversion tools. - * pnmtopng. The original is at in the pnmtopng FTP site - (ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz). + * xpmtoppm (from the Portable Bitmap Utilities) (For RedHat Linux + users: it is included within the package libgr-progs). + the original is at + ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz + (ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz) - * Bibtex2html (http://www.lri.fr/~filliatr/ftp/bibtex2html/), or - Bib2html (http://www.uni-koblenz.de/ag-ki/ftp/bib2html/). - Bibtex2html is available in debian, while bib2html is in some rpm - based distributions. Bib2html, in turn depends on man2html for - proper installation. man2html can be had from + * pnmtopng, which is also in libgr-progs for RedHat. The original is + at + 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 `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. + + tar xzf libgr-2.0.13.tar.gz + make + cd png + rm libpng.so* + make pnmtopng + + You can then install the new pnmtopng into `/usr/local/bin/' + + * Bib2html 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 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 bib converter utility, but you will - not see our hypertextified bibliography. + The website will build without this utility, but you will not see + our hypertextified bibliography. + + * Doc++ (optional) to read the source code. Configuring and compiling ========================= - to install GNU LilyPond, type: + to install GNU LilyPond, simply type: + gunzip -c lilypond-x.y.z | tar xf - cd lilypond-x.y.z - ./configure # run with --help to see appropriate options + ./configure # fill in your standard prefix with --prefix make make install - sh buildscripts/clean-fonts.sh - If you are doing an upgrade, you should remove all `feta' `.pk' and -`.tfm' files. A script has been provided to do the work for you, see -`buildscripts/clean-fonts.sh'. + This will install a number of files, something close to: - If you are not root, you should choose a `--prefix' argument that -points into your home directory, eg. + /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 - ./configure --prefix=$HOME/usr + 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: - In this case, you have to insert the contents of -`buildscripts/out/lilypond-login' or -`buildscripts/out/lilypond-profile' into your start up scripts by hand. -Configuring for multiple platforms -================================== + export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR" + ./configure - If you want to build multiple versions of LilyPond with different -configuration settings, you can use the `--enable-config=CONF' option -of configure. You should use `make conf=CONF' to generate the output -in `out-CONF'. Example: suppose I want to build with and without -profiling. Then I'd use the following for the normal build, + `CPPFLAGS' are the preprocessor flags. - ./configure --prefix=~ --enable-checking - make - make install + The configure script is Cygnus configure, and it will accept +`--help'. If you are not root, you will probably have to make it with a +different `--prefix' option. Our favourite location is - and for the profiling version, I specify a different configuration. + ./configure --prefix=$HOME/usr - ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking - make conf=prof - make conf=prof install + In this case, you will have to set up MFINPUTS, and TEXINPUTS +accordingly. -Emacs mode -========== + Since GNU LilyPond currently is beta, you are advised to also use - An emacs mode for LilyPond is included with the source archive as -`lilypond-mode.el' and `lilypond-font-lock.el'. If you have an RPM, it -is in `/usr/share/doc/lilypond-X/'. You have to install it yourself. - Add this to your ~/.emacs or ~/.emacs.el: - (load-library "lilypond-mode.el") - (setq auto-mode-alist - (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist)) - (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock))) + --enable-debugging + --enable-checking - If you have the latest LilyPond-1.3.x Debian package, LilyPond-mode -is automatically loaded, so you need not modify your `~/.emacs' file. + Options to configure include: -Red Hat Linux -============= +``--enable-printing'' + Enable debugging print routines (lilypond `-D' option) - Red Hat 7.0 i386 RPMS are available from -`ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/RedHat/'. +``--enable-optimise'' + Set maximum optimisation: compile with `-O2'. This can be + unreliable on some compiler/platform combinations (eg, DEC Alpha + and PPC) - You can also compile them yourself. A spec file is in -`make/out/lilypond.spec'. This file is distributed along with the -sources. You can make the rpm by issuing +``--enable-profiling'' + Compile with support for profiling. - rpm -tb lilypond-x.y.z.tar.gz - rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z +``--enable-config'' + Output to a different configuration file. Needed for + multi-platform builds - For running on a Red Hat system you need these packages: guile, -tetex, tetex-dvips, libstdc++, python, ghostscript. + All options are documented in the `configure' help The option +`--enable-optimise' is recommended for Real Life usage. - For compilation on a Red Hat system you need these packages, in -addition to the those needed for running: glibc-devel, gcc-c++, -libstdc++-devel, guile-devel, flex, bison, texinfo, tetex-devel, groff, -libgr-progs. + If you do -SuSE -==== - [TODO: document this] + make all - Install `tetex', `te_mpost', `te_kpath'. + everything will be compiled, but nothing will be installed. The +resulting binaries can be found in the subdirectories `out/' (which +contain all files generated during compilation). -Mandrake -======== +Configuring for multiple platforms +================================== - [TODO] + If you want to compile LilyPond with different configuration +settings, then, you can use the `--enable-config' option. Example: +suppose I want to build with and without profiling. Then I'd use the +following for the normal build, -Debian GNU/Linux -================ - A Debian package is also available. You may install it easily by -using apt-get as root: + ./configure --prefix=~ --disable-optimise --enable-checking + make + make install - apt-get install lilypond1.3 + and for the profiling version, I specify a different configuration. - Alternatively, visit - * http://packages.debian.org/lilypond - (http://packages.debian.org/lilypond) + ./configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking + make config=optprof + make config=optprof install - * http://ftp.debian.org/debian/pool/main/l/lilypond1.3/ - (http://ftp.debian.org/debian/pool/main/l/lilypond1.3/) for latest - package uploaded to Debian unstable; +Installing +========== - * http://people.debian.org/~foka/lilypond/ - (http://people.debian.org/~foka/lilypond/) for latest - semi-unofficial build of LilyPond 1.3.121 for Debian 2.2r2 - (potato) users. The official stable Debian 2.2r2 is stuck with - the old LilyPond-1.3.24. + if you have done a successful `make', then a simple - You may contact Anthony Fok for more information. - The build scripts are in the subdirectory `debian/'; you can make -the .deb by doing, for example: + make install - $ su - root - # dpkg --purge lilypond lilypond1.3 - # exit - $ tar xzf lilypond-1.3.122.tar.gz - $ cd lilypond-1.3.122 - $ dch -p -v 1.3.122-0.local.1 "Local build." - $ debuild - $ su - root - # dpkg -i ../lilypond1.3_1.3.122*.deb - # exit - $ + should do the trick. - For compilation on a Debian GNU/Linux system you need these packages, -in addition to the those needed for running: + If you are doing an upgrade, please remember to remove obsolete +`.pk' and `.tfm' files of the fonts. A script has been provided to do +the work for you, see `bin/clean-fonts.sh'. - * g++, cpp, libc6-dev, libstdc++-dev +Redhat linux +============ - * libguile-dev + RedHat Linux users can compile an RPM. A spec file is in +`make/out/lilypond.spec', it is distributed along with the sources. - * make, m4, flex, bison + You can make the rpm by issuing - * gettext + rpm -tb lilypond-x.y.z.tar.gz + rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z - * groff, texinfo, bibtex2html (not in 2.2r2) + Precompiled i386 RedHat RPMS are available from +ftp://freshmeat.net/pub/rpms/lilypond/ +(ftp://freshmeat.net/pub/rpms/lilypond/) and +http://linux.umbc.edu/software/lilypond/rpms/ +(http://linux.umbc.edu/software/lilypond/rpms/). - * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev + For compilation on a RedHat system you need these packages, in +addition to the those needed for running: + * glibc-devel - * dpkg-dev, debhelper, fakeroot + * libstdc++-devel - * gs, netpbm, pnmtopng + * guile-devel - Most of these are listed on the Build-Depends line in the -debian/control file. To ensure the creation of the lilypond deb is -trouble-free, we recommend that you first install the following packages -before starting dpkg-buildpackage by running apt-get as root. + * flex - For Debian 2.2 (or 2.2r2, 2.2r3): + * bison - apt-get install task-debian-devel task-c++-dev \ - python-base libguile6-dev tetex-bin tetex-dev \ - tetex-extra flex bison texinfo groff gs \ - netpbm pnmtopng m4 gettext + * texinfo - For Debian in development ("unstable", the future 2.3 or 3.0): +Debian GNU/linux +================ - apt-get install task-debian-devel task-c++-dev \ - python-base libguile9-dev tetex-bin libkpathsea-dev \ - tetex-extra flex bison texinfo bibtex2html groff gs \ - netpbm pnmtopng m4 gettext + A Debian package is also available; contact Anthony Fok +. The build scripts are in the subdirectory `debian/'. - And, just so that old fonts from previous versions of LilyPond won't -interfere with your build, you may want to do this before the build too: +Windows NT/95 +============= - dpkg --purge lilypond lilypond1.3 + Separate instructions on building for W32 are available; See the +files in `Documentation/ntweb/', included with the sources. Problems ======== For help and questions use and . Please consult the faq before mailing -your problems. If you find bugs, please send bug reports to -. +your problems. + + If you find bugs, please send bug reports to . + + Known bugs that are LilyPond's fault are listed in `TODO', or +demonstrated in `input/bugs/'. + + Known bugs that are not LilyPond's fault are documented here. + +LinuxPPC Bugs: +************** + + * 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, + `ftp://dev.linuxppc.org/users/fsirl/R5/RPMS/ppc/' + + * egcs-1.0.2 (LinuxPPC R4): all compiling with `-O2' is suspect, in + particular guile-1.3, and Lily herself will break. + +Linux-i386 +********** + + * SuSE6.2 and similar platforms (glibc 2.1, libstdc++ 2.9.0) + + 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. + + * 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. + + lilypond input.ly + + and + lilypond -I. ./input.ly + makes a difference + + Typical stacktrace: + SIGSEGV + __libc_malloc (bytes=16384) + ?? () + yyFlexLexer::yy_create_buffer () + Includable_lexer::new_input (this=0x8209a00, s={strh_ = { - Bugs that are not fault of LilyPond are documented here. + This behaviour has been observed with machines that have old libg++ + versions (LinuxPPC feb '98, RedHat 4.x). Solaris: ******** @@ -347,7 +399,7 @@ AIX 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 + 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.