make flat heavier.

[lilypond.git] / Documentation / windows / installing.texi

\input texinfo @c -*-texinfo-*-
@setfilename installing.info
@settitle LilyPond on Windows

@html
<!--- @@WEB-TITLE@@=Windows Installation --->
@end html

@node Top
@top

@chapter WINDOWS - Installing GNU LilyPond on Windows

This document explains how to install the binary release for windows
on a Microsoft Windows 95, 98, ME, NT, 2000 or XP machine.  Please
follow the instructions carefully.  If it doesn't work for you, please
send a bugreport, following the guidelines in the section on
bugreports below.

@section QuickInstall

Click @uref{http://cygwin.com/setup.exe, Install Lily now}, run the
installer (@file{setup.exe}), and in the Package View dialogue, select
LilyPond, found in the Publishing section.

If you have any problems, please read the rest of this page.

@section Windows binary setup 

The binary LilyPond setup for Windows is in fact a
@uref{http://cygwin.com, Cygwin} installation, including the LilyPond
package for Cygwin.

If you run Windows NT, 2000 or XP, please become administrator first;
installing as an ordinary user does not seem to work on certain
Windows-NT variants.  Download and run
@uref{http://cygwin.com/setup.exe, setup.exe}.  You will be asked some
questions.  If you are unsure just click "Next".  Do not change the
default install directory @file{c:/cygwin}.  Do not change the default
text type @samp{UNIX}, i.e., do not use @samp{DOS} mounts.

In the Package View dialogue window, click on the Publishing section
to view the available publishing software for Cygwin.  Make sure that
LilyPond is selected.  If this is a new or first installation, click
on @emph{Skip} to select.

This installs LilyPond, and Cygwin, GUILE, Python, teTeX (MikTeX is not
supported).  If you already have some of that software under
@file{c:/cygwin}, then don't worry: nothing will be installed twice.

@subsection Additional software

If you install the Cygwin's XFree86 X11 window system, tetex-x11 and
ghostscript-x11 packages too, you can view the @code{dvi} output doing
@code{xdvi test.dvi}.

LilyPond needs a PostScript/PDF viewer to be really useful.  At this
time (Sun Aug 11 2002), such software is not available in Cygwin, so
you must use native Windows software instead.

@table @samp
@item Ghostview.

You can use GSView-2.6.  This old package has two advantages.  It has
gsview and ghostscript bundeled, and it doesn't popup @emph{Register
Now|Cancel} windows all the time.

Install
@uref{ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/aladdin/gs550/gsv27550.exe,GSView-2.7}
(GhostView for Windows), or visit
@uref{ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/ghostgum,ftp://mirror.cs.wisc.edu/}.

@c check/update versions
If you need to view PDFs, or want to create PDFs using GSView, you can
install the newer versions GSView-3.6 and GhostScript-6.50.  You get
annoying @emph{Register Now|Cancel} popups, though.

Install
@uref{ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/ghostgum/gsv36w32.exe,GSview-3.6}
and
@uref{ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/AFPL/gs650/gs650w32.exe,
GhostScript-6.50}, or visit the @uref{http://www.cs.wisc.edu/~ghost/,
Ghostview and GSview site}.
@end table

Note: @uref{ftp://ftp.cs.wisc.edu/pub/ghost/README,ftp.cs.wisc.edu}
has moved the ghostscript/ghostview distribution to a
@uref{ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/,rather unreliable
server}.

@section Testing LilyPond

Open a LilyPond shell (To open a a lilypond shell, click the "GNU
LilyPond" or "Cygwin" icon), and type


@example
lilypond --help
@end example


You should see something similar to


@example
GNU LilyPond 1.6.0
Usage: lilypond [OPTION]... FILE...

Typeset music and or play MIDI from FILE

LilyPond is a music typesetter.  It produces beautiful sheet music
using a high level description file as input.  LilyPond is part of 
the GNU Project.

Options:
  -h,--help             this help
[..]
@end example


Then, prepare a file called @file{foo.ly}, by issuing

@example
notepad foo.ly
@end example

Enter the following into the file

@example

\score @{ \notes @{ c4 ( ) c4 @} @}

@end example

Close the editor and save the file.  Then run the following command.

@example
ly2dvi -p foo
@end example

At the end, it should say

@example
DVI output to `foo.dvi'...
PS output to `foo.ps'...
PDF output to `foo.pdf'...
@end example

If you install the Cygwin's XFree86 X11 window system, tetex-x11 and
ghostscript-x11 packages too, you can view the @code{dvi} output
@c copied from tutorial, where xdvi command has been explained above
@c doing @code{xdvi test.dvi}.
doing:

@example
startx
xdvi test.dvi
@end example

If you have installed a PostScript/PDF viewer,
such as @code{GSView} from @uref{http://www.cs.wisc.edu/~ghost},
viewing the PS file can be done with:

@example
gsview32 foo.ps
@end example


If this works, then you can head to the
@uref{../../user/out-www/lilypond/Tutorial.html,Tutorial}
@c Hmm, this only works for 1.6.5-1 installs.
@c Cygwin does not have a proper html documentation index such as dwww
@c Should add for debian and red hat packages too.
(@uref{file:///c/cygwin/usr/doc/lilypond-1.6.5-1/html/Documentation/user/out-www/Tutorial.html,
local copy})
to start using LilyPond.

@section Removing LilyPond

Start @file{setup.exe}, click Next, select "Install from Local
Directory".  Then click next until you reach "Select packages to
install".  Click "View".  Now, for every package, click on the recycle
icon until it says "Uninstall".  Then, click Next.

(If you find this too tedious, you can also simply remove
@file{c:/cygwin}. This also removes the @file{/home/} directories under
cygwin (i.e. @file{C:\CYGWIN\HOME}, so make sure that you bring
important files in safety first.)

@section Troubleshooting

For problems and solutions see
@uref{http://lilypond.org/wiki?TroubleshootingWindows,Troubleshooting
Windows}

If you have a problem running LilyPond, you should first make sure
that you are running the latest version.  Chances are, that your
problem was already reported and fixed in a newer release.  Click
@uref{http://cygwin.com/setup.exe, Update Lily now} to check if
new software is available.

If you subscribe to the @uref{http://cygwin.com/ml/cygwin-announce/,
cygwin-announce (archives)} mailing list, see
@uref{http://sources.redhat.com/cygwin/lists.html, Cygwin mailing
lists}, bottom of page.  You'll be notified of new and updated
software for Cygwin, including LilyPond.

Chances are, that a problem you experience has been noted by others.
Cygwin specific problems will be reported to the
@uref{http://cygwin.com/ml/cygwin, cygwin-user (archives)} mailing
list (@uref{http://sources.redhat.com/cygwin/lists.html, Cygwin mailing
lists}, bottom of page).

LilyPond specific problems, also concering Cygwin/Windows, are
reported and discussed on the
@uref{http://mail.gnu.org/pipermail/lilypond-user, lilypond-user
(archives)} mailing list.

@subsection Setup.exe does not run at all

Make sure that you run @uref{http://cygwin.com/setup.exe, this latest
setup.exe}.
This will also work if  you were using a setup.exe you donwloaded
before from lilypond.org before.

If you're sure that you have the very latest version, and it doesn't
work, and the @uref{http://cygwin.com/ml/cygwin, cygwin-user archives}
do not mention the problem, write to @email{cygwin@@cygwin.com}.
Setup is under heavy development, so you may have been unlucky and
have dowloaded a buggy version.

@subsection ly2dvi:error: filename should not contain spaces

@quotation
@emph{I don't seem to be able to either change this "default" or to point
Lilypond to another directory which does not have the space.}

@example
ly2dvi:error: filename should not contain spaces: `/usr/bin/Ralph Whedon/foo'
@end example

@emph{Any ideas what I should do?}
@end quotation
Best is to create a new home directory.  Start the Cygwin or LilyPond
shell, and do:

@example
HOME=/home/ralph
mkdir -p $HOME
cd
@end example

To go there automatically, each time you log in, edit the file

@example
/etc/passwd   # windows name: c:\cygwin\etc\passwd
@end example


using vim or wordpad, and change the `/usr/bin/Ralph Whedon/' to
`/home/ralph'.

@subsection What's this Bash/Cygwin shell?

The bash shell is a basic UNIX-like console that we use for the
Windows release.  Using such an intercompatible shell makes it easier
to maintain the Windows release reasonably, notably because it works
the same as the normal UNIX setup.  Keep in mind that none of the
developers are using Windows.

Also it is possible to build LilyPond from source with a complete
Cygwin install, see @uref{compiling.html,Compiling LilyPond on Windows}.

Bash is not very different from the MS-DOS shell, you'll just have to
(re-)learn a few commands needed to browse through your hard-drive.
Here are some commands you'll definitely be needing.

To change folders, the usual @code{cd}


@example
cd ../..    # If you type this at startup, you should be in the root
            # directory.  Better do:
cd /            
@end example


You'll notice that file names in Bash are written with the slash (/),
and not the backslash (\) bar as in MS-DOS and Windows.


@example
C:\Win98\Bureau\  ---> /cygdrive/c/Win98/Bureau
@end example

The equivalent of the MS-DOS dir command is ls -l :

@example
ls -l       #You'll get the listing of the current folder.
@end example

To copy a file, use the cp command:

@example
cp srcfile destfile
@end example

For more information, see the
@uref{http://www.linuxdoc.org/HOWTO/DOS-Win-to-Linux-HOWTO.html,DOS/Windows
to Linux HOWTO}.



@subsection Requirements and DLLs

TeTeX and LilyPond depend on a number of library packages, but as it
seems, they sometimes do not get selected automagically.

@itemize @samp
@item teTeX
  requires: ash cygwin ed grep jpeg libkpathsea3 libncurses6 libpng12 tiff
  sed termcap zlib
  
@item LilyPond
  requires: bash libguile12 libiconv2 libintl2 libkpathsea3 python
  tetex-bin, tetex-tiny or tetex-base
@end itemize

@multitable @columnfractions .40 .40
@item DLL              @tab Package
@item cygguile-12.dll  @tab libguile12
@item cygintl-2.dll    @tab libintl2
@item cygiconv-2.dll   @tab libiconv2
@item cygltdl-3.dll    @tab libltdl3
@item cygpcre.dll      @tab pcre
@item cygpng12.dll     @tab libpng12
@item cygtiff3.dll     @tab tiff
@end multitable

Also, the more general info on missing DLLs may be helpful:
@example
    @uref{http://cygwin.com/faq/faq_4.html#SEC32}
    @uref{http://cygwin.com/ml/cygwin/2002-01/msg01619.html}
@end example

@subsection Why don't you fix this?

Well, we've tried several times, but we can't reproduce the problem
('It works for me').  If you're experiencing DLL problems, you're much
invited to help us find the bug and fix it.  You can install the
binutils package, and use objdump to find which executable depends on
the missing dll.

@example
objdump -x <path to download dir>/setup.exe | grep -i dll
objdump -x /usr/bin/awk.exe | grep -i dll
objdump -x /usr/bin/python.exe | grep -i dll
@end example

Of course, you should check what version of the offending package you
have installed (see @file{/var/log/setup.log} and
@file{/var/log/setup.log.full)}.

@subsection Check your TeX installation

Start a LilyPond shell and run

@example
latex sample2e
@end example

This should print a few lines of information and produce a file
@file{sample2e.dvi}. Then run

@example
dvips sample2e
@end example


which produces a sample2e.ps, which you can view using @code{gsview32}.

When this works correctly, you could resume your attempts with
LilyPond.


@subsection Bugreports

So you have checked by running @uref{http://cygwin.com/setup.exe,
Update Lily now} that you run the latest version, and
@uref{http://lilypond.org/wiki?TroubleshootingWindows,Troubleshooting
Windows} nor @uref{http://cygwin.com/ml/cygwin, cygwin-user
(archives)} or @uref{http://mail.gnu.org/pipermail/lilypond-user,
lilypond-user (archives)} mentions your problem.  It looks like you
found a bug.

We can only help you with a problem if you give a full, detailed
bugreport. A bugreport includes

@itemize @bullet
@item A @emph{precise} description of the problem.  
@item A full description of your platform (machine type, operating
system)
@item All version numbers of relevant software you run.
      The best way to this is to run
      
      @example
      sh -x /usr/bin/bug-lilypond-cygwin >& bug.txt
      @end example
      
      and include the file @file{bug.txt}.  (If you are running
      lilypond 1.5.73 or earlier, download
      @uref{http://lilypond.org/cygwin/bug-lilypond-cygwin,
      bug-lilypond-cygwin here}.
@end itemize

If you have trouble using bug-lilypond-cygwin, you must gather this
information by hand.  Specifically, we want to see the output of the
following commands:
@itemize @bullet
@item Version info

@example
  python -V
  lilypond --version
  ly2dvi --version
@end example

@item If ly2dvi fails, then please run it as follows and include the
  output in the 

@example
  ly2dvi --verbose MY-FILE
@end example

@end itemize

The file @file{bug.txt} should contain information on your system
(check that).  Send your problem together with @file{bug.txt} to
@email{lilypond-user@@gnu.org}.

Be sure to turn off HTML email.  It is very annoying.  For reasons
unknown to man, most Windows email clients have that turned on by
default.

If you are using Microsoft Outlook (Express), you can send normal
plain text messages by clicking through the menus
Tools/Options/Send/Mail Sending Format/Plain Text, with options:

@example
Set Message format as MIME, set "Encode text using:" to None.  Set
Automatically wrap text at 70, and > is used to indent original text.
@end example

Easy instructions for various email clients can be found at
@uref{http://helpdesk.rootsweb.com/listadmins/plaintext.html,
helpdesk.rootsweb.com}.