X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=INSTALL.txt;h=f08529a3b756476c949d6f6d8da23daa9c783814;hb=469b0c1660e8481379eb5a5c032feb3600e1c530;hp=378400dc449ef12e2db9fb6ddb23dfb99c39bf72;hpb=01d6763cea8e4890874001a2f756ba2162e4262f;p=lilypond.git diff --git a/INSTALL.txt b/INSTALL.txt index 378400dc44..f08529a3b7 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -3,16 +3,6 @@ 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 handy when you have to compile LilyPond -more often. - Obtaining ========= @@ -20,377 +10,345 @@ Obtaining ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/ (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/). - _If you upgrade by patching do remember to rerun autoconf after -applying the patch_. + There are three options for downloading sources. - 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 don't have any version, then you can download the entire + `.tar.gz' file. - 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 an unpacked source tree of a previous version, you + may use the diffs . -Prerequisites -============= + _If you upgrade by patching do remember to rerun autoconf after + applying the patch_. + + * 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. - For compilation you need: + 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 - * A GNU system: GNU LilyPond is known to run on these GNU systems: - Linux (PPC, intel), FreeBSD, AIX, NeXTStep, IRIX, Digital Unix - and Solaris. +Build requirements +================== - * 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'. + 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 the LilyPond on Windows page +(http://appel.lilypond.org/lilypond/gnu-windows/). - * Although we recommend to use Unix, LilyPond is known to run on - Windows NT/95/98 as well. See Section Windows NT/95,es. + You need the following packages to compile Lilypond. - * EGCS 1.1 or newer. Check out `ftp://ftp.gnu.org/gnu/gcc/'. + * 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/). - * Python 1.5, Check out `ftp://ftp.python.org' or - `ftp://ftp.cwi.nl/pub/python'. + * Python 1.5, Check out the python website (http://www.python.org). - * GUILE 1.3.4 or newer, check out - http://www.gnu.org/software/guile/guile.html + * 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. - * GNU Make. Check out ftp://ftp.gnu.org/gnu/make/ + * GNU Make. Check out the GNU make FTP directory (ftp://ftp.gnu.org/gnu/make/). - * Flex (version 2.5.4 or newer). Check out - ftp://ftp.gnu.org/gnu/flex/ (ftp://ftp.gnu.org/gnu/flex/). + * Flex (version 2.5.4a or newer). Check out the Flex webpage + (http://www.gnu.org/software/flex/). + + * Bison (version 1.25 or newer). Check out the bison webpage + (http://www.gnu.org/software/bison/) - * Bison (version 1.25 or newer). Check out - ftp://ftp.gnu.org/gnu/bison/ (ftp://ftp.gnu.org/gnu/bison/). + * TeX. + + TeX is used as an output backend. - * TeX. 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. + Also, TeX's libkpathsea is used to find the fonts (.mf, .afm, + .tfm). 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. - * Texinfo (version 4.0 or newer). Check out - ftp://ftp.gnu.org/gnu/texinfo/ (ftp://ftp.gnu.org/gnu/texinfo/). - Most documentation is in texinfo. + * 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/). - * 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) + * 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. * MetaPost, needed for generating PostScript fonts. Please note that - tetex-0.4pl8 (included with Redhat 5.x) does not include + tetex-0.4pl8 (included with Red Hat 5.x) does not include `mfplain.mp', which is needed for producing the scalable font files. - If you do not want to use PostScript output, edit `mf/GNUmakefile'. + 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. + usually included with your installation of TeX. You may need to + install a tetex-devel or tetex-dev package too. + + In the very unlikely case that kpathsea is not available for your + platform (ie, you're not running GNU/Linux, Windows, or any recent + UNIX), you can compile LilyPond without kpathsea support. In that + case, you'll probably have to indicate where TeX's tfm files live. + Invoke configure something like: + ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols -Running -======= + +Running requirements +==================== GNU LilyPond does use a lot of resources. For operation you need the following software * TeX. - * A PostScript printer and/or viewer (such as Ghostscript) is - strongly recommended. Xdvi will show all embedded PostScript - too if you have Ghostscript installed. + * Xdvi and ghostscript - * GUILE 1.3.4, check out http://www.gnu.org/software/guile/ - (http://www.gnu.org/programs/guile.html) + * GUILE 1.3.4, or newer. Check out the GUILE webpage + (http://www.gnu.org/software/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. 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:" - - 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. +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. - LilyPond is a hiddeously big, slow and bloated program. A fast CPU -and plenty of RAM is recommended for comfortable use. + LilyPond is a big and slow program. A fast CPU and plenty of RAM is +recommended for comfortable use. -Website -======= +Website requirements +==================== - The website is the most convenient form to use for reading the -documentation on-line documentation. It is made by entering + 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 - make htmldoc - This does require a functioning LilyPond. The binary doesn't have -to be installed. + make web-doc - If you want to auto-generate Lily's website, you'll need some -additional conversion tools. + Building the website requires some additional tools: - * 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 + * 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) - * 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). - Which, in turn depends on man2html for proper installation. - man2html can be had from + * pnmtopng. The original is at in the pnmtopng FTP site + (ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.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 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. + The website will build without bib converter utility, but you will + not see our hypertextified bibliography. - * DOC++ (http://www.zib.de/Visual/software/doc++/index.html) A - documentation system for C++ sources, which is used for the - LilyPond sources. Configuring and compiling ========================= - to install GNU LilyPond, simply type: - + to install GNU LilyPond, type: gunzip -c lilypond-x.y.z | tar xf - cd lilypond-x.y.z - ./configure # fill in your standard prefix with --prefix + ./configure # run with --help to see appropriate options make make install + sh buildscripts/clean-fonts.sh - This will install a number of files, something close to: + 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'. - /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 + If you are not root, you should choose a `--prefix' argument that +points into your home directory, eg. - 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: + ./configure --prefix=$HOME/usr + 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. - export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR" - ./configure +Configuring for multiple platforms +================================== - `CPPFLAGS' are the preprocessor flags. + 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, - 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 + ./configure --prefix=~ --enable-checking + make + make install + and for the profiling version, I specify a different configuration. - ./configure --prefix=$HOME/usr - In this case, you will have to set up MFINPUTS, and TEXINPUTS -accordingly. + ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking + make conf=prof + make conf=prof install - Since GNU LilyPond currently is beta, you are advised to also use +Emacs mode +========== + 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. - --enable-debugging - --enable-checking + 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))) - Options to configure include: + If you have the latest LilyPond-1.3.x Debian package, LilyPond-mode +is automatically loaded, so you need not modify your `~/.emacs' file. -``--enable-printing'' - Enable debugging print routines (lilypond `-D' option) +Red Hat Linux +============= -``--enable-optimise'' - Set maximum optimisation: compile with `-O2'. This can be - unreliable on some compiler/platform combinations (eg, DEC Alpha - and PPC) + Red Hat 7.0 i386 RPMS are available from +`ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/RedHat/'. -``--enable-profiling'' - Compile with support for profiling. + 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-config'' - Output to a different configuration file. Needed for - multi-platform builds + rpm -tb lilypond-x.y.z.tar.gz + rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z - All options are documented in the `configure' help The option -`--enable-optimise' is recommended for Real Life usage. + For running on a Red Hat system you need these packages: guile, +tetex, tetex-dvips, libstdc++, python, ghostscript. - If you do + 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. +SuSE +==== - make all + [TODO: document this] - 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). + Install `tetex', `te_mpost', `te_kpath'. -Configuring for multiple platforms -================================== +Mandrake +======== - 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, + [TODO] +Debian GNU/Linux +================ - ./configure --prefix=~ --disable-optimise --enable-checking - make - make install + A Debian package is also available. You may install it easily by +using apt-get as root: - and for the profiling version, I specify a different configuration. + apt-get install lilypond1.3 + Alternatively, visit - ./configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking - make config=optprof - make config=optprof install + * http://packages.debian.org/lilypond + (http://packages.debian.org/lilypond) -Installing -========== + * 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; - if you have done a successful `make', then a simple + * 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. + You may contact Anthony Fok for more information. - make install + The build scripts are in the subdirectory `debian/'; you can make +the .deb by doing, for example: - should do the trick. + $ 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 + $ - 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'. + For compilation on a Debian GNU/Linux system you need these packages, +in addition to the those needed for running: -Redhat linux -============ + * g++, cpp, libc6-dev, libstdc++-dev - RedHat Linux users can compile an RPM. A spec file is in -`make/out/lilypond.spec', it is distributed along with the sources. + * libguile-dev - You can make the rpm by issuing + * make, m4, flex, bison - rpm -tb lilypond-x.y.z.tar.gz - rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z + * gettext - 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/). + * groff, texinfo, bibtex2html (not in 2.2r2) - For compilation on a RedHat system you need these packages, in -addition to the those needed for running: - * glibc-devel + * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev - * libstdc++-devel + * dpkg-dev, debhelper, fakeroot - * guile-devel + * gs, netpbm, pnmtopng - * flex + 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. - * bison + For Debian 2.2 (or 2.2r2, 2.2r3): - * texinfo + 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 -Debian GNU/linux -================ + For Debian in development ("unstable", the future 2.3 or 3.0): - A Debian package is also available; see -http://packages.debian.org/lilypond -(http://packages.debian.org/lilypond) or contact Anthony Fok - for more information. The build scripts are in the -subdirectory `debian/'. + 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 -Windows NT/95 -============= + 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: - Separate instructions on building for W32 are available; See the -files in `Documentation/ntweb/', included with the sources. + dpkg --purge lilypond lilypond1.3 Problems ======== For help and questions use and . Please consult the faq before mailing -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. +your problems. If you find bugs, please send bug reports to +. - * libg++ 2.7 + Bugs that are not fault of LilyPond are documented here. - LilyPond occasionally crashes while parsing the initialisation - files. This is a very obscure bug, and usually entering the - commandline differently "fixes" it. +NetBSD +****** - lilypond input.ly + * The flex precompiled in NetBSD-1.4.2 is broken. Download + flex-2.5.4a, build, install. - and - lilypond -I. ./input.ly - makes a difference + * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1 + release)) does not include `/usr/pkg' paths. Configure using: - Typical stacktrace: - SIGSEGV - __libc_malloc (bytes=16384) - ?? () - yyFlexLexer::yy_create_buffer () - Includable_lexer::new_input (this=0x8209a00, s={strh_ = { + CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure - This behaviour has been observed with machines that have old libg++ - versions (LinuxPPC feb '98, RedHat 4.x). Solaris: ******** @@ -413,7 +371,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.