=head1 NAME
-INSTALL - installing LilyPond
+INSTALL - installing GNU LilyPond
=head1 DESCRIPTION
-This page documents installation and compilation of LilyPond
+This page documents installation and compilation of GNU LilyPond
-=head1 IMPORTANT
+=head1 ABSTRACT
-if you have downloaded a
+You do something which looks remotely like
- *.pre*
+ configure
+ make
+ make install
-version, then this is version is I<not> meant for producing nice
-output, but to keep your patchsets up to date. It might not even compile.
+The detailed instructions follow here.
=head1 PREREQUISITES
=over 5
=item *
-Unix. LilyPond is known to run on Linux, AIX, Digital Unix and
-Solaris
-If you have the Cygnus WIN32 port of the GNU utils, it will
-even work in Lose NT/95, but don't promise to support it.
+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 *
-GNU C++ v2.7 or better, with libg++ installed. Version 2.7.2
-or better recommended. I almost positive that it will not compile with
-AT&T CC.
+If you have the Cygnus WINDOWS32 port of the GNU utils, it will even
+work in Windows NT/95, but we don't promise to support it.
=item *
-Bash. Most scripts will continue to work with a stock sh, but they
-will generate (harmless) syntax errors
+
+GNU C++ v2.7 or better, with libg++ installed. If you use gcc 2.8 or
+egcs then you should install a matching libg++ (ie. 2.8) version.
=item *
+
GNU make.
=item *
+
Flex (2.5.1 or better).
=item *
-Bison.
+
+Bison. (Version 1.25 or better)
=back
-=head1 RECOMMENDED
+=head1 RUNNING
+
+GNU LilyPond does use a lot of resources. For operation you need the following:
+
=over 5
=item *
-Perl. Some (mostly unimportant scripts) use Perl for trivial
-operations. The documentation was created with the perl's Plain Old
-Documentation.
+
+TeX
=item *
-(GNU) find
+
+A PostScript printer and/or viewer (such as Ghostscript) is strongly
+recommended. Xdvi will show all embedded PostScript too if you have
+Ghostscript installed.
=back
+=head1 RECOMMENDED
+
+Although not strictly necessary, these are recommended to have.
+
+=over 5
+
+=item *
+
+Perl-5. Most documentation was created with the perl's Plain Old
+Documentation. (I use 5.003)
+
+=item *
+
+Python. Although perl is nice, python is better. We will shift
+towards python for build scripts
+
+=item *
+
+GNU find
+
+=item *
+
+A fast computer (a full page of music typically takes 1 minute on my
+486/133, using the B<--enable-checking> compile. It's lot slower than
+most MusiXTeX preprocessors)
+
+=back
+
=head1 CONFIGURING and COMPILING
-to install LilyPond, simply type:
+to install GNU LilyPond, simply type:
configure
make install
This will install the following files:
+ /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/lib/libflower.{so,a}
/usr/local/bin/lilypond
/usr/local/bin/mi2mu
/usr/local/share/lilypond/*
/usr/lib/texmf/texmf/tex/lilypond/*
The TeX include directory is detected dynamically, but it can be
-adjusted with B<--enable-texprefix>. 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:
+adjusted with B<--enable-tex-prefix> and B<--enable-tex-dir>. 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:
- CXXFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR" configure
+ export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
+ configure
+
+C<CPPFLAGS> are the preprocessor flags.
the configure script is Cygnus configure, and it will accept
B<--help>. If you are not root, you will probably have to make it with
configure --prefix=/home/me_myself_and_I/
-Since LilyPond currently is beta, You are advised to also use
+In this case, you will have to set MFINPUTS, and TEXINPUTS accordingly.
+
+If you want to install GNU LilyPond in F</usr/local>, and your TeX has
+no default hooks for local stuff (mine is broken too), you can do:
- --enable-debug
+ configure --prefix=/usr/local --enable-tex-prefix=/usr/lib/texmf
+
+Since GNU LilyPond currently is beta, you are advised to also use
+
+ --enable-debugging
--enable-checking
other options include:
- --enable-printing
- --enable-optimise
- --enable-profiling
+=over 4
+
+=item B<--enable-shared>
+
+Make a shared library (gnu/linux, solaris (?) only )
+
+=item B<--enable-printing>
+
+Enable debugging print routines (lilypond B<-d> option)
+
+=item B<--enable-optimise>
+
+Set maximum optimisation: compile with B<-O2>
+
+=item B<--enable-profiling>
+
+Compile with support for profiling
+
+=item B<--enable-tex-prefix>
+
+Set the directory where TeX and Metafont live
+=item B<--enable-tex-dir>
+
+Set then directory TeX input is in (detected as a subdir of tex-prefix)
+
+=item B<--enable-mf-dir>
+
+Set the directory mf input is in (idem)
+
+=item B<--enable-out-dir>
+
+Set the directory for machine generated output.
+
+=back
+
+All options are documented in the F<configure> help
The option B<--enable-optimise> is recommended for Real Life usage.
If you do
make all
everything will be compiled, but nothing will be installed. The
-resulting binaries can be found in the subdirectory
-F<bin/>.
+resulting binaries can be found in the subdirectories F<out/> (which
+contain all files generated during compilation).
+
+=head2 Building for multiple hosts
+
+LilyPond does not follow the GNU standards when it comes to
+configuring and making Makefiles. In LilyPond, F<make> generates
+I<all> output in output directories (called F<out/>, by default). You
+can have multiple compiles from the same source-tree, by overriding
+the setting for the output directory.
+
+Example: on my system, I do debugging and lots compiling. For this I
+use the configuration as follows:
+
+ configure --prefix=~ --enable-debugging --enable-printing --enable-checking
+ make all
+
+and I want to do profiling. For that I use
+
+ configure --prefix=~ --enable-debugging --disable-printing\
+ --disable-checking --enable-profiling --enable-optimise\
+ --enable-out-dir=out-profile
+
+ make OUTDIR_NAME=out-profile all
+
+These two commands build two entirely separate versions of
+LilyPond. In Real Life, you would probably also want to have two
+different prefixes. On my machine this is no problem; I never do
+C<make install>. My prefix dirs are linked back to my source
+directory.
-=head1 RUNNING
-LilyPond does use a lot of resources. For operation you need the following:
+=head1 INSTALLING
+If you have done a successful C<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, see F<bin/clean-fonts.sh>.
+
+=head1 CAVEATS
=over 5
=item *
-A fast computer (a full page of music typically takes 1 minute
-on my 486/66, using the B<--enable-checking> compile. It's lot slower
-than most MusiXTeX preprocessors)
-=item *
-TeX
+The -O2 option to gcc triggers a gcc bug on DEC Alpha in dstream.cc. You
+should turn off this flag for this file.
=item *
-The MusixTeX fonts. (I use those found in MusixTeX
-T.59)
+
+Perl5.003 and Perl5.004 use different syntax for pod2html.
=back
+=head1 EXAMPLE
+
+This is what I type in my xterm:
+
+ lilypond someinput.ly
+ tex someinput.tex
+ xdvi someinput&
+
+This is what the output looks like over here:
+
+ 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 ...
+
+
+ hw:~/musix/spacer$ xdvi someinput&
+ [1] 855
+
+Check out the input files, some of them have comments
Please refer to the man page for more information.
=head1 REDHAT LINUX
RedHat Linux users should be able to get a RPM. A spec file is in
-F<make/lilypond.spec>.
+F<make/out/lilypond.spec>. You should be able to create an rpm as a
+normal user. Be sure you have a F<~/.rpmrc>, and edit the RPM-dir in
+F<Variables.make>. (If you create the RPM as a normal user the
+permissions will not be set correctly, unfortunately)
-=head1 WINDOZE
+=head1 DEBIAN GNU/LINUX
-Windows NT:
+A Debian package is also available; contact Anthony Fok
+<foka@debian.org>. The build scripts are in the subdirectory debian/
-you need the cygnus win32 gnu port development stuff; have a look
-at http://www.cygnus.com/gnu-win32.
-to make LilyPond under, brr, aargh, well, simply type:
+=head1 WINDOWS NT/95
+
+So, you're stuck with Windows, eh? Well, don't worry, you just
+need (to get) Cygnus' windows32 port of gnu development stuff;
+have a look at http://www.cygnus.com/gnu-win32.
+
+To make GNU LilyPond under, brr, aargh, shudder... windows32, well,
+simply type:
bash configure
- make win32
+ make
+
+B<Note> If you rely on broken DOS/Windows tools such as pkzip/WinZIP
+to unpack the distribution, make sure the B<entire> source tree
+is unpacked correctly, in particular the empty out directories
+(F<flower/out>, F<lib/out> et. al.)
+
+=head1 MUSIXTEX
+
+Previous versions (before 0.1.39) used fonts from the TeX macro
+package "MusixTeX". You can still use these, but they are not
+supported. Since LilyPond's Feta font is much prettier, you'd be
+seriously misguided if you used them, but anyway, here are the
+installation instructions for those deprecated fonts.
+
+
+[obsolete] I use the MusixTeX fonts those found in MusixTeX
+T.73. Beware, the clef symbol seems to have changed its position in
+some versions, (notably Egler's, a.k.a. OpusTeX). The MusixTeX fonts
+are included in MusixTeX (T73 or better), which can be had from any
+CTAN site, e.g. at
+
+=over 4
+
+=item ftp://ftp.shsu.edu/tex-archive/macros/musixtex/taupin
+
+=item ftp://ftp.tex.ac.uk/tex-archive/macros/musixtex/taupin
+
+=item ftp://ftp.dante.de/tex-archive/macros/musixtex/taupin
+
+=back
+
+You only need the contents of the F<mf/> subdirectory of the
+package. The primary site of the Taupin version is
+ftp://hprib.lps.u-psud.fr/pub/music_zips/musixtex.zip
+
+Install the musixtex fonts in a directory which TeX and MF knows (if
+you are root, look for a directory which contains the directories with
+AMS and CM source (*.mf) files. Create a subdir lilypond or musixtex
+and copy the fonts into that). Do not forget to rehash TeX (if
+applicable)
+
+Example: my fonts are in F</usr/local/lib/texfonts/musixtex/>, and I
+have a symlink pointing to that in
+F</usr/lib/texmf/texmf/fonts/source/public/>. After I copied the
+files, I ran "texhash"
-=head1 PLATFORMS
+Andreas Egler's version of MusixTeX, now called OpusTeX, will also
+work. Andreas moved some characters around in the fonts, so you have
+to edit the definitions in F<tex/eglerdefs.tex>.
-LilyPond (pl 0.0.39) is known to compile on the following platforms:
- * linux 2.0.28, g++ 2.7.2[.1]
- * aix 4.1, g++ 2.7.2
- * windows-nt 4.0, cygnus gnu-win32 beta17.1 (~=g++ 2.7.2)
- * linux 2.0.28 X to doze, gcc-go32 (~=g++ 2.7.2) [exec. untested]
=head1 AUTHORS
- Han-Wen Nienhuys <hanwen@stack.nl>
+Han-Wen Nienhuys <hanwen@stack.nl>
- Jan Nieuwenhuizen <jan@digicash.com>
+Jan Nieuwenhuizen <jan@digicash.com>
Have fun!