]> git.donarmstrong.com Git - lilypond.git/blob - INSTALL.txt
release: 1.4.0
[lilypond.git] / INSTALL.txt
1
2
3 Table of Contents
4 *****************
5
6
7
8
9 INSTALL - compiling and installing GNU LilyPond
10   Downloading
11     source code
12     Binaries
13     Upgrading
14   Requirements
15     Compilation
16     Running requirements
17     Website requirements
18   Building  LilyPond
19     Configuring for multiple platforms
20   Emacs mode
21   Compiling for distributions
22     Red Hat Linux
23     LinuxPPC
24     SuSE
25     Slackware
26     Mandrake
27     Debian GNU/Linux
28   Problems
29     NetBSD
30     Solaris:
31     AIX
32
33
34 INSTALL - compiling and installing GNU LilyPond
35 ***********************************************
36
37    This document describes how to build LilyPond on Unix platforms.  It
38 is also known to run and compile on Windows NT/95/98 as well.  More
39 information on this topic can be found at the LilyPond on Windows page
40 (ftp://ftp.lilypond.org/pub/LilyPond/gnu-windows/).
41
42 Downloading
43 ===========
44
45    Even numbered versions are `stable'. The webpages for the stable
46 version (1.2) reside on the GNU servers
47 (http://www.gnu.org/software/lilypond). Big enhancements go into the
48 latest odd numbered version (1.3), whose webpages are on the lilypond
49 site (http://www.lilypond.org/).
50
51 source code
52 -----------
53
54    If you want to compile LilyPond from source, download here:
55    * Download development releases from
56      `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/' by FTP and
57      `http://ftp.cs.uu.nl/pub/GNU/LilyPond/', by HTTP.
58
59    * `ftp://sca.uwaterloo.ca/pub/' by FTP (Canadian mirror)
60
61    * at `lilypond.org' `ftp://ftp.lilypond.org/pub/LilyPond/' by FTP and
62      `http://www.lilypond.org/ftp/' by HTTP.
63
64 Binaries
65 --------
66
67    Binaries are available, but are not updated for every version
68 released.
69    * RedHat i386
70      (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/)
71
72    * LinuxPPC (ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc)
73
74    * Debian GNU/Linux Stable
75      (ftp://ftp.debian.org/debian/pool/main/l/lilypond)
76
77    * Debian GNU/Linux Unstable
78      (ftp://ftp.debian.org/debian/pool/main/l/lilypond1.3)
79
80    * Windows Stable (http://home.austin.rr.com/jbr/jeff/lilypond/)
81      Windows Testing (http://www.lilypond.org/gnu-windows)
82
83
84 Upgrading
85 ---------
86
87    There are two  options for upgrading sources.
88
89    * if you have an unpacked source tree of a previous version, you may
90      the patches.
91
92      _If you upgrade by patching do remember to rerun autoconf after
93      applying the patch_.
94
95    * if you have the `.tar.gz' file of a previous release, you can use
96      xdelta (ftp://ftp.xcf.berkeley.edu/pub/xdelta/).   This is much
97      safer than using patches, and is the recommended way.
98
99      The following command produces `lilypond-1.3.122.tar.gz' from
100      `lilypond-1.3.121' identical (up to compression dates) to the .122
101      on the FTP site.
102             xdelta patch lilypond-1.3.121-1.3.122.xd lilypond-1.3.121.tar.gz
103
104 Requirements
105 ============
106
107 Compilation
108 -----------
109
110    You need the following packages to compile Lilypond.
111
112    * A reasonably new C++ compiler:  EGCS 1.1, GCC 2.95.2 or newer.
113      Check out the gcc site (ftp://ftp.gnu.org/gnu/gcc/).
114
115    * Python 1.5, Check out the python website (http://www.python.org).
116
117    * GUILE 1.3.4 or newer,  check out the GUILE webpage
118      (http://www.gnu.org/software/guile/guile.html).  Version 1.4 is
119      recommended for better performance.
120
121    * GNU Make.  Check out the GNU make FTP directory
122      (ftp://ftp.gnu.org/gnu/make/).
123
124    * Flex (version 2.5.4a or newer).  Check out the Flex webpage
125      (http://www.gnu.org/software/flex/).
126
127    * Bison (version 1.25 or newer).  Check out the bison webpage
128      (http://www.gnu.org/software/bison/)
129
130    * TeX.
131
132      TeX is used as an output backend.
133
134      Also, TeX's libkpathsea is used to find the fonts (.mf, .afm,
135      .tfm).  Make sure you have tetex 1.0 or newer (1.0.6 is known to
136      work).  You may need to install a tetex-devel or tetex-dev package
137      too.
138
139    * Texinfo (version 4.0 or newer).  The documentation of lily is
140      written in texinfo.  Check out the texinfo FTP directory
141      (ftp://ftp.gnu.org/gnu/texinfo/).
142
143    * The geometry package for LaTeX is needed to use ly2dvi.  It is
144      available at the FTP directory for `geometry'
145      (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry).
146      This package is normally included with the TeX distribution.
147
148    * MetaPost, needed for generating PostScript fonts. Please note that
149      tetex-0.4pl8 (included with Red Hat 5.x) does not include
150      `mfplain.mp', which is needed for producing the scalable font
151      files.
152
153      If you don't have MetaPost and don't want to use PostScript
154      output, then edit `mf/GNUmakefile', removing the line saying
155      `PFA_FILES='.
156
157    * kpathsea, a library for searching (TeX) files.  `kpathsea' is
158      usually included with your installation of TeX.  You may need to
159      install a tetex-devel or tetex-dev package too.
160
161      In the very unlikely case that kpathsea is not available for your
162      platform (ie, you're not running GNU/Linux, Windows, or any recent
163      UNIX), you can compile LilyPond without kpathsea support.  In that
164      case, you'll probably have to indicate where TeX's tfm files live.
165      Invoke configure something like:
166
167           ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
168
169
170 Running requirements
171 --------------------
172
173    GNU LilyPond does use a lot of resources. For operation you need the
174 following software
175
176    * TeX.
177
178    * Xdvi and ghostscript
179
180    * GUILE 1.3.4, or newer.  Check out the GUILE webpage
181      (http://www.gnu.org/software/guile.html)
182
183    For running LilyPond successfully you have to help TeX and MetaFont
184 find various files.  The recommended way of doing so is adjusting the
185 environment variables in the start-up scripts of your shell. Appropriate
186 Csh and bourne sh scripts are left in
187 `buildscripts/out/lilypond-profile' and
188 `buildscripts/out/lilypond-login' after compilation.
189
190    LilyPond is a big and slow program.  A fast CPU and plenty of RAM is
191 recommended for comfortable use.
192
193 Website requirements
194 --------------------
195
196    The documentation comes in the form of a website. You can view this
197 website on the internet, but you can also build it locally. This process
198 requires a successful compile of lilypond. The website is built by
199 issuing
200
201        make web-doc
202
203    Building the website requires some additional tools:
204
205    * xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
206      The original is at the netpbm FTP site
207      (ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz)
208
209    * pnmtopng. The original is at in the pnmtopng FTP site
210      (ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz).
211
212    * Bibtex2html (http://www.lri.fr/~filliatr/ftp/bibtex2html/), or
213      Bib2html (http://www.uni-koblenz.de/ag-ki/ftp/bib2html/).
214      Bibtex2html is available in debian, while bib2html is in some rpm
215      based distributions.  Bib2html, in turn depends on man2html for
216      proper installation.  man2html can be had from
217      http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05
218      (http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05).
219
220      The website will build without bib converter utility, but you will
221      not see our hypertextified bibliography.
222
223    * texinfo (a development release) The documentation will build with
224      texinfo-4.0, but if you want split html pages, you're best off
225      using the lates pretest version from texinfo-4.0b
226      (ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz) or
227      texinfo-4.0b (ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz)
228
229 Building  LilyPond
230 ==================
231
232    to install GNU LilyPond, type:
233         gunzip -c lilypond-x.y.z | tar xf -
234         cd lilypond-x.y.z
235         ./configure             # run with --help to see appropriate options
236         make
237         make install
238              sh buildscripts/clean-fonts.sh
239
240    If you are doing an upgrade, you should remove all `feta' `.pk' and
241 `.tfm' files.  A script has been provided to do the work for you, see
242 `buildscripts/clean-fonts.sh'.
243
244    If you are not root, you should choose a `--prefix' argument that
245 points into your home directory, eg.
246
247         ./configure --prefix=$HOME/usr
248
249    In this case, you have to insert the contents of
250 `buildscripts/out/lilypond-login' or
251 `buildscripts/out/lilypond-profile' into your start up scripts by hand.
252
253 Configuring for multiple platforms
254 ----------------------------------
255
256    If you want to build multiple versions of LilyPond with different
257 configuration settings, you can use the `--enable-config=CONF' option
258 of configure.  You should use `make conf=CONF' to generate the output
259 in `out-CONF'.  Example: suppose I want to build with and without
260 profiling.  Then I'd use the following for the normal build,
261
262            ./configure --prefix=~ --enable-checking
263            make
264            make install
265
266    and for the profiling version, I specify a different configuration.
267
268
269            ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
270            make conf=prof
271            make conf=prof install
272
273 Emacs mode
274 ==========
275
276    An emacs mode for LilyPond is included with the source archive as
277 `lilypond-mode.el' and `lilypond-font-lock.el'.  If you have an RPM, it
278 is in `/usr/share/doc/lilypond-X/'.  You have to install it yourself.
279
280    Add this to your `~/.emacs' or `~/.emacs.el':
281          (load-library "lilypond-mode.el")
282          (setq auto-mode-alist
283            (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
284          (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
285
286    If you have the latest LilyPond-1.3.x Debian package, LilyPond-mode
287 is automatically loaded, so you need not modify your `~/.emacs' file.
288
289 Compiling for distributions
290 ===========================
291
292 Red Hat Linux
293 -------------
294
295    Red Hat 7.0 i386 RPMS are available from
296 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
297
298    You can also compile them yourself.  A spec file is in
299 `make/out/redhat.spec'. This file is distributed along with the
300 sources.  You can make the rpm by issuing
301
302              tar xfz lilypond-x.y.z.tar.gz
303         rpm -bb lilypond-x.y.z/make/out/redhat.spec
304         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
305
306    For running on a Red Hat system you need these packages: guile,
307 tetex, tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
308
309    For compilation on a Red Hat system you need these packages, in
310 addition to the those needed for running: glibc-devel, gcc-c++,
311 libstdc++-devel, guile-devel, flex, bison, texinfo, tetex-devel, groff,
312 libgr-progs.
313
314    Warning
315
316    There appears to be a problem with the Xdvi shipped with RedHat 7.1.
317 Symptoms: Xdvi responds very sluggishly or hangs while viewing lilypond
318 output. The cause for this problem is unknown; you are advised to
319 recompile Xdvi from source.
320
321 LinuxPPC
322 --------
323
324    Some LinuxPPC RPMS should available from
325 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
326
327    A LinuxPPC RPM can be made using the `redhat.spec' file.
328
329 SuSE
330 ----
331
332    Some SUSE RPMS should available from
333 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
334
335    You can also compile a RPM for SUSE yourself.  A spec file is in
336 `make/out/suse.spec', see the instructions for building the RedHat RPM.
337
338    You must have the following packages: guile tcsh tetex te_latex
339 te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
340 libnetpb gs_serv gs_lib gs_fonts guile
341
342 Slackware
343 ---------
344
345    No precompiled packages for Slackware are available.
346
347    Problems have been reported with Slackware 7.0; apparently, it ships
348 with a faulty compiler. Do not compile LilyPond with -O2 on this
349 platform.
350
351 Mandrake
352 --------
353
354    Some binaries are available at rpmfind.net. Refer to
355 `ftp://ftp.rpmfind.net/linux/Mandrake-devel/cooker/contrib/RPMS/'.
356
357 Debian GNU/Linux
358 ----------------
359
360    A Debian package is also available.  You may install it easily by
361 using apt-get as root:
362
363         apt-get install lilypond1.3
364
365    Debian's tex installation is a bit short on memory, you may want to
366 increase it like this:
367      --- /etc/texmf/texmf.cnf.dpkg      Sun Jan 28 14:12:14 2001
368      +++ /etc/texmf/texmf.cnf   Fri Apr 27 11:09:35 2001
369      @ -384,8 +384,8 @
370       main_memory.context = 1500000
371       main_memory.mpost = 1000000
372       main_memory = 263000 % words of inimemory available; also applies to inimf&mp
373      -extra_mem_top = 0    % extra high memory for chars, tokens, etc.
374      -extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
375      +extra_mem_top = 100000    % extra high memory for chars, tokens, etc.
376      +extra_mem_bot = 100000    % extra low memory for boxes, glue, breakpoints, etc.
377      
378       obj_tab_size.context = 256000
379
380    Alternatively, visit
381
382    * http://packages.debian.org/lilypond
383      (http://packages.debian.org/lilypond)
384
385    * http://ftp.debian.org/debian/pool/main/l/lilypond1.3/
386      (http://ftp.debian.org/debian/pool/main/l/lilypond1.3/) for latest
387      package uploaded to Debian unstable;
388
389    * http://people.debian.org/~foka/lilypond/
390      (http://people.debian.org/~foka/lilypond/) for latest
391      semi-unofficial build of LilyPond 1.3.121 for Debian 2.2r2
392      (potato) users.  The official stable Debian 2.2r2 is stuck with
393      the old LilyPond-1.3.24.
394
395    You may contact Anthony Fok <foka@debian.org> for more information.
396
397    The build scripts are in the subdirectory `debian/'; you can make
398 the .deb by doing, for example:
399
400         $ su - root
401         # dpkg --purge lilypond lilypond1.3
402         # exit
403         $ tar xzf lilypond-1.3.122.tar.gz
404         $ cd lilypond-1.3.122
405         $ dch -p -v 1.3.122-0.local.1 "Local build."
406         $ debuild
407         $ su - root
408         # dpkg -i ../lilypond1.3_1.3.122*.deb
409         # exit
410         $
411
412    For compilation on a Debian GNU/Linux system you need these packages,
413 in addition to the those needed for running:
414
415    * g++, cpp, libc6-dev, libstdc++<your-libstdc++-version-here>-dev
416
417    * libguile<your-libguile-version-here>-dev
418
419    * make, m4, flex, bison
420
421    * gettext
422
423    * groff, texinfo, bibtex2html (not in 2.2r2)
424
425    * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
426
427    * dpkg-dev, debhelper, fakeroot
428
429    * gs, netpbm, pnmtopng
430
431    Most of these are listed on the Build-Depends line in the
432 debian/control file.  To ensure the creation of the lilypond deb is
433 trouble-free, we recommend that you first install the following packages
434 before starting dpkg-buildpackage by running apt-get as root.
435
436    For Debian 2.2 (or 2.2r2, 2.2r3):
437
438         apt-get install task-debian-devel task-c++-dev \
439                 python-base libguile6-dev tetex-bin tetex-dev \
440                 tetex-extra flex bison texinfo groff gs \
441                 netpbm pnmtopng m4 gettext
442
443    For Debian in development ("unstable", the future 2.3 or 3.0):
444
445         apt-get install task-debian-devel task-c++-dev \
446                 python-base libguile9-dev tetex-bin libkpathsea-dev \
447                 tetex-extra flex bison texinfo bibtex2html groff gs \
448                 netpbm pnmtopng m4 gettext
449
450    And, just so that old fonts from previous versions of LilyPond won't
451 interfere with your build, you may want to do this before the build too:
452
453         dpkg --purge lilypond lilypond1.3
454
455 Problems
456 ========
457
458    For help and questions use <help-gnu-music@gnu.org> and
459 <gnu-music-discuss@gnu.org>.  Please consult the faq before mailing
460 your problems.  If you find bugs, please send bug reports to
461 <bug-gnu-music@gnu.org>.
462
463    Bugs that are not fault of LilyPond are documented here.
464
465 NetBSD
466 ------
467
468    * The flex precompiled in NetBSD-1.4.2 is broken.  Download
469      flex-2.5.4a, build, install.
470
471    * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
472      release)) does not include `/usr/pkg' paths.  Configure using:
473
474           CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
475
476
477 Solaris:
478 --------
479
480    * Sparc64/Solaris 2.6, GNU make-3.77
481
482      GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
483      newer.
484
485    * Sparc64/Solaris 2.6, ld
486
487      Not yet resolved.
488
489 AIX
490 ---
491
492    * AIX 4.3 ld
493
494      The following is from the gcc install/SPECIFIC file.
495              Some versions of the AIX binder (linker) can fail with a
496           relocation    overflow severe error when the -bbigtoc option
497           is used to link    GCC-produced object files into an
498           executable that overflows the TOC.     A fix for APAR IX75823
499           (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
500           available from IBM Customer Support and from its
501           27service.boulder.ibm.com website as PTF U455193.
502
503           Binutils does not support AIX 4.3 (at least through release
504           2.9). GNU    as and GNU ld will not work properly and one
505           should not configure GCC    to use those GNU utilities. Use
506           the native AIX tools which do    interoperate with GCC.
507
508      add -Wl,-bbigtoc to USER_LDFLAGS, ie:
509               LDFLAGS='-Wl,-bbigtoc' ./configure
510
511