X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=INSTALL.txt;h=2a431f3a5c0a8c6d9eb00db2c5f15db14fcb0160;hb=96e411c64146df6dc1b2aa5c5667bb9b8d7176d2;hp=a8bf785b37f406008f2ba985716a528cb62253e0;hpb=42ab6ff971c06253b34f96ed122836ab88d09cc0;p=lilypond.git diff --git a/INSTALL.txt b/INSTALL.txt index a8bf785b37..2a431f3a5c 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -1,322 +1,415 @@ - INSTALL - compiling and installing GNU LilyPond - HWN & JCN +INSTALL - compiling and installing GNU LilyPond +*********************************************** -Contents +Abstract +======== - 1: ABSTRACT -2: PREREQUISITES -3: RUNNING -4: RECOMMENDED -5: WEBSITE -6: CONFIGURING and COMPILING -7: CONFIGURING FOR MULTIPLE PLATFORMS -8: INSTALLING -9: REDHAT LINUX -10: DEBIAN GNU/LINUX -11: WINDOWS NT/95 -12: AUTHORS + 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. -1: ABSTRACT +Obtaining +========= -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. + You can get the latest version of LilyPond at +ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/ +(ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/). -2: PREREQUISITES + _If you upgrade by patching do remember to rerun autoconf after +applying the patch_. -For compilation you need: + 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/'. -o A GNU system: GNU LilyPond is known to run on these GNU - systems: Linux (PPC, intel), FreeBSD, AIX, NeXTStep, - IRIX, Digital Unix and Solaris. + 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 -o Lots of disk space: LilyPond takes between 50 and 100 - mb to compile if you use debugging information. If you - are short on disk-space run configure with --disable- - debugging. +Prerequisites +============= - Although we recommend to use Unix, LilyPond is known to - run on Windows NT/95/98 as well. See Section 11. + For compilation you need: -o EGCS 1.1 or newer. + * A GNU system: GNU LilyPond is known to run on these GNU systems: + Linux (PPC, intel), FreeBSD, AIX, NeXTStep, IRIX, Digital Unix + and Solaris. -o Python 1.5 (Strictly speaking, you shouldn't need - Python for compiling and installing, but you'll need it - to regenerate the font tables, e.g.). + * 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'. -o GUILE 1.3 (no, GUILE 1.2 won't work), check out - http://www.gnu.org/software/guile/guile.html. + * Although we recommend to use Unix, LilyPond is known to run on + Windows NT/95/98 as well. See Section Windows NT/95,es. -3: RUNNING + * EGCS 1.1 or newer. Check out `ftp://ftp.gnu.org/pub/gcc/'. -GNU LilyPond does use a lot of resources. For operation you -need the following: + * Python 1.5, Check out `ftp://ftp.python.org' or + `ftp://ftp.cwi.nl/pub/python'. -o TeX + * GUILE 1.3.4, check out + http://www.gnu.org/software/guile/guile.html + (http://www.gnu.org/software/guile/guile.html). -o A PostScript printer and/or viewer (such as - Ghostscript) is strongly recommended. Xdvi will show - all embedded PostScript too if you have Ghostscript - installed. + * GNU make. Check out ftp://ftp.gnu.org/make/ + (ftp://ftp.gnu.org/make/). -o GUILE 1.3 (no, GUILE 1.2 won't work), check out - http://www.gnu.org/programs/guile.html + * Flex (version 2.5.4 or newer). Check out ftp://ftp.gnu.org/flex/ + (ftp://ftp.gnu.org/flex/). -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: + * Bison (version 1.25 or newer). Check out ftp://ftp.gnu.org/bison/ + (ftp://ftp.gnu.org/bison/). - export MFINPUTS="/usr/local/share/lilypond/mf:" - export TEXINPUTS="/usr/local/share/lilypond/tex:" + * Texinfo. Check out ftp://ftp.gnu.org/pub/texinfo/ + (ftp://ftp.gnu.org/pub/texinfo/). Most documentation is in + texinfo. -The empty path component represents and MetaFont's default -search paths. Scripts with the proper paths for the bourne -and C-shell respectively are generated in build- -scripts/out/lilypond-profile and buildscripts/out/lilypond- -login during compilation. + * 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) -4: RECOMMENDED + * 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. -Although not strictly necessary, these are recommended to -have. -o GNU make. Check out ftp://ftp.gnu.org or any mirror of - this site. +Running +======= -o Flex (version 2.5.4 or newer). Check out - ftp://ftp.gnu.org or any mirror of this site. + GNU LilyPond does use a lot of resources. For operation you need the +following software -o Bison (version 1.25 or newer). Check out - ftp://ftp.gnu.org or any mirror of this site. + * TeX -o GUILE 1.3 (no, GUILE 1.2 won't work), check out - http://www.gnu.org/programs/guile.html + * A PostScript printer and/or viewer (such as Ghostscript) is + strongly recommended. Xdvi will show all embedded PostScript + too if you have Ghostscript installed. -o Python (version 1.5 or newer). Check out - ftp://ftp.python.org or ftp://ftp.cwi.nl/pub/python. + * GUILE 1.3.4, check out http://www.gnu.org/software/guile/ + (http://www.gnu.org/programs/guile.html) -o Yodl. All documentation will be in Yodl. (1.30.17) - ftp://ftp.lilypond.org/pub/yodl - http://www.cs.uu.nl/~hanwen/yodl + 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:" -o Texinfo. (version 3.12 or newer) + 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. -o GNU find Check out ftp://ftp.gnu.org or any mirror of - this site. + LilyPond is a hiddeously big, slow and bloated program. A fast CPU +and plenty of RAM is recommended for comfortable use. -o The geometry package for LaTeX is needed to use ly2dvi. - Available at ftp://ftp.ctan.org/tex- - archive/macros/latex/contrib/supported/geometry or at - mirror site ftp://ftp.dante.de +Website +======= -o A fast computer: a full page of music typically takes 1 - minute on my 486/133, using the --enable-checking com- - pile. + The website is the most convenient form to use for reading the +documentation on-line documentation. It is made by entering -5: WEBSITE + make website + This does require a fully functioning -If you want to auto-generate Lily's website, you'll need -some additional conversion tools. + If you want to auto-generate Lily's website, you'll need some +additional conversion tools. -o xpmtoppm (from the Portable Bitmap Utilities) (For Red- - Hat Linux users: it is included within the package - libgr-progs). + * 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) -o Bib2html http://pertsserver.cs.uiuc.edu/~hull/bib2html. - Which, in turn depends on man2html for proper installa- - tion. man2html can be had from http://askdon- - ald.ask.uni-karlsruhe.de/hppd/hpux/Network- - ing/WWW/Man2html-1.05. + * 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 - TeTeX users should not forget to rerun texhash. + 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. -Building the website requires pnmtopng. The version of pnm- -topng that is distributed with RedHat 5.1 contains a bug -(pnmtopng is dynamically linked to the wrong version of -libpng). Recompile it from source, and make sure that the -pnmtopng binary is linked statically to the libpng that is -included in libgr. + tar xzf libgr-2.0.13.tar.gz + make + cd png + rm libpng.so* + make pnmtopng - 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 this utility, but you will not see + our hypertextified bibliography. -You can then install the new pnmtopng into /usr/local/bin/ + * Doc++ (optional) to read the source code. -6: CONFIGURING and COMPILING -to install GNU LilyPond, simply type: +Configuring and compiling +========================= - gunzip -c lilypond-x.y.z | tar xf - - cd lilypond-x.y.z - configure # fill in your standard prefix with --prefix - make - make install + to install GNU LilyPond, simply type: -This will install a number of files, something close to: + gunzip -c lilypond-x.y.z | tar xf - + cd lilypond-x.y.z + ./configure # fill in your standard prefix with --prefix + make + make install - /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 + This will install a number of files, something close to: -The above assumes that you are root and have the GNU devel- -opment tools, and your make is GNU make. If this is not the -case, you can adjust your environment variables to your + /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 -taste: + 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: - export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR" - configure -CPPFLAGS are the preprocessor flags. + export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR" + ./configure -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 + `CPPFLAGS' are the preprocessor flags. - configure --prefix=$HOME/usr + 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 -In this case, you will have to set up MFINPUTS, and TEXIN- -PUTS accordingly. -Since GNU LilyPond currently is beta, you are advised to -also use + ./configure --prefix=$HOME/usr - --enable-debugging - --enable-checking + In this case, you will have to set up MFINPUTS, and TEXINPUTS +accordingly. -Options to configure include: + Since GNU LilyPond currently is beta, you are advised to also use ---enable-printing - Enable debugging print routines (lilypond -D option) ---enable-optimise - Set maximum optimisation: compile with -O2. This can - be unreliable on some compiler/platform combinations - (eg, DEC Alpha and PPC) + --enable-debugging + --enable-checking ---enable-profiling + Options to configure include: + +``--enable-printing'' + Enable debugging print routines (lilypond `-D' option) + +``--enable-optimise'' + Set maximum optimisation: compile with `-O2'. This can be + unreliable on some compiler/platform combinations (eg, DEC Alpha + and PPC) + +``--enable-profiling'' Compile with support for profiling. ---enable-config - Output to a different configuration file. Needed for - multi-platform builds +``--enable-config'' + Output to a different configuration file. Needed for + multi-platform builds + + All options are documented in the `configure' help The option +`--enable-optimise' is recommended for Real Life usage. -All options are documented in the configure help The option ---enable-optimise is recommended for Real Life usage. + If you do -If you do - make all + make all -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). + 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). -7: CONFIGURING FOR MULTIPLE PLATFORMS +Configuring for multiple platforms +================================== -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 profil- -ing. Then I'd use the following for the normal build, + 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, - configure --prefix=~ --disable-optimise --enable-checking + + ./configure --prefix=~ --disable-optimise --enable-checking make make install -and for the profiling version, I specify a different config- -uration. + and for the profiling version, I specify a different configuration. + - configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking + ./configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking make config=optprof make config=optprof install -8: INSTALLING +Installing +========== + + if you have done a successful `make', then a simple + + + make install + + should do the trick. + + 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'. + +Redhat linux +============ + + RedHat Linux users can compile an RPM. A spec file is in +`make/out/lilypond.spec', it is distributed along with the sources. + + You can make the rpm by issuing + + rpm -tb lilypond-x.y.z.tar.gz + rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z + + 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/). + + For compilation on a RedHat system you need these packages, in +addition to the those needed for running: + * glibc-devel + + * libstdc++-devel + + * guile-devel + + * flex + + * bison + + * texinfo + +Debian GNU/linux +================ + + A Debian package is also available; contact Anthony Fok +. The build scripts are in the subdirectory `debian/'. + +Windows NT/95 +============= + + 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 . + + 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. -If you have done a successful make, then a simple +LinuxPPC Bugs: +************** - make install + * 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/' -should do the trick. + * egcs-1.0.2 (LinuxPPC R4): all compiling with `-O2' is suspect, in + particular guile-1.3, and Lily herself will break. -If you are doing an upgrade, please remember to remove obso- -lete .pk and .tfm files of the fonts. A script has been -provided to do the work for you, see bin/clean-fonts.sh. +Linux-i386 +********** -CAVEATS + * SuSE6.2 and similar platforms (glibc 2.1, libstdc++ 2.9.0) -o The -O2 option triggers bugs on various platforms - (PowerPC, Alpha). If you experience problems, you - should first try turning off this. + Lily will crash during parsing (which suggests a C++ library + incompatibility). Precise cause, precise platform description or + solution are not known. -EXAMPLE + Note that this only happens on some computers with the said + platform. -This is what I type in my xterm: + * libg++ 2.7 - lilypond someinput.ly - tex someinput.tex - xdvi someinput& + LilyPond occasionally crashes while parsing the initialisation + files. This is a very obscure bug, and usually entering the + commandline differently "fixes" it. -This is what the output looks like over here: + lilypond input.ly - GNU LilyPond 0.0.78 #4/FlowerLib 1.1.24 #0 - Parsing ... [/home/hw/share/lilypond/init// - <..etc..> - init//performer.ly]]][input/kortjakje.ly] - Creating elements ...[8][16][24][25] - Preprocessing elements... - Calculating column positions ... [14][25] - Postprocessing elements... - TeX output to someinput.tex ... - Creating MIDI elements ...MIDI output to someinput.midi ... + and + lilypond -I. ./input.ly + makes a difference - hw:~/musix/spacer$ xdvi someinput& - [1] 855 + Typical stacktrace: + SIGSEGV + __libc_malloc (bytes=16384) + ?? () + yyFlexLexer::yy_create_buffer () + Includable_lexer::new_input (this=0x8209a00, s={strh_ = { -Check out the input files, some of them have comments Please -refer to the man page for more information. + This behaviour has been observed with machines that have old libg++ + versions (LinuxPPC feb '98, RedHat 4.x). -9: REDHAT LINUX +Solaris: +******** -RedHat Linux users can compile an RPM. A spec file is in -make/out/lilypond.spec, it is distributed along with the -sources. + * Sparc64/Solaris 2.6, GNU make-3.77 -You can make the rpm by issuing + GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or + newer. - rpm -tb lilypond-x.y.z.tar.gz - rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z + * Sparc64/Solaris 2.6, ld -10: DEBIAN GNU/LINUX + Not yet resolved. -A Debian package is also available; contact Anthony Fok -foka@debian.org. The build scripts are in the subdirectory -debian/. +AIX +*** -11: WINDOWS NT/95 + * AIX 4.3 ld -Separate instructions on building for W32 are avaible in the -file README-W32.yo. + The following is from the gcc install/SPECIFIC file. + 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. -12: AUTHORS + 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. -Han-Wen Nienhuys + add -Wl,-bbigtoc to USER_LDFLAGS, ie: + LDFLAGS='-Wl,-bbigtoc' ./configure -Jan Nieuwenhuizen -Have fun!