Documentation/windows/installing.texi

   1 \input texinfo @c -*-texinfo-*-
   2 @setfilename installing.info
   3 @settitle LilyPond on Windows
   4
   5 @html
   6 <!--- @@WEB-TITLE@@=Windows Installation --->
   7 @end html
   8
   9 @node Top
  10 @top
  11
  12 @chapter WINDOWS - Installing GNU LilyPond on Windows
  13
  14 This document explains how to install the binary release for windows
  15 on a Microsoft Windows 95, 98, ME, NT, 2000 or XP machine.  Please
  16 follow the instructions carefully.  If it doesn't work for you, please
  17 send a bugreport, following the guidelines in the section on
  18 bugreports below.
  19
  20 @section QuickInstall
  21
  22 Click @uref{http://cygwin.com/setup.exe, Install Lily now}, run the
  23 installer (@file{setup.exe}), and in the Package View dialogue, select
  24 LilyPond, found in the Publishing section.
  25
  26 If you have any problems, please read the rest of this page.
  27
  28 @section Windows binary setup
  29
  30 The binary LilyPond setup for Windows is in fact a
  31 @uref{http://cygwin.com, Cygwin} installation, including the LilyPond
  32 package for Cygwin.
  33
  34 If you run Windows NT, 2000 or XP, please become administrator first
  35 (currently, installing as an ordinary user will not work).  Download
  36 and run @uref{http://cygwin.com/setup.exe, setup.exe}.  You will be
  37 asked some questions.  If you are unsure just click "Next".  Do not
  38 change the default install directory @file{c:/cygwin}.
  39
  40 In the Package View dialogue window, click on the Publishing section
  41 to view the available publishing software for Cygwin.  Make sure that
  42 LilyPond is selected.  If this is a new or first installation, click
  43 on @emph{Skip} to select.
  44
  45 This installs LilyPond, and Cygwin, GUILE, Python, teTeX (MikTeX is not
  46 supported).  If you already have some of that software under
  47 @file{c:/cygwin}, then don't worry: nothing will be installed twice.
  48
  49 @subsection Additional software
  50
  51 If you install the Cygwin's XFree86 X11 window system, tetex-x11 and
  52 ghostscript-x11 packages too, you can view the @code{dvi} output doing
  53 @code{xdvi test.dvi}.
  54
  55 LilyPond needs a PostScript/PDF viewer to be really useful.  At this
  56 time (Sun Aug 11 2002), such software is not available in Cygwin, so
  57 you must use native Windows software instead.
  58
  59 @table @samp
  60 @item Ghostview.
  61
  62 You can use GSView-2.6.  This old package has two advantages.  It has
  63 gsview and ghostscript bundeled, and it doesn't popup @emph{Register
  64 Now|Cancel} windows all the time.
  65
  66 Install
  67 @uref{ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/aladdin/gs550/gsv27550.exe,GSView-2.7}
  68 (GhostView for Windows), or visit
  69 @uref{ftp://ftp.cs.wisc.edu/ghost/ghostgum,ftp.cs.wisc.edu}.
  70
  71 @c check/update versions
  72 You can also use the newer versions GSView-3.6 and GhostScript-6.50,
  73 which can also display PDFs.  You get annoying @emph{Register
  74 Now|Cancel} popups, though.
  75
  76 Install
  77 @uref{ftp://ftp.cs.wisc.edu/ghost/ghostgum/gsv36w32.exe,GSview-3.6}
  78 and
  79 @uref{ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/AFPL/gs650/gs650w32.exe,
  80 GhostScript-6.50}, or visit the @uref{http://www.cs.wisc.edu/~ghost/,
  81 Ghostview and GSview site}.
  82 @end table
  83
  84 @section Testing LilyPond
  85
  86 Open a LilyPond shell (To open a a lilypond shell, click the "GNU
  87 LilyPond" or "Cygwin" icon), and type
  88
  89 @quotation
  90 @example
  91 lilypond --help
  92 @end example
  93 @end quotation
  94
  95 You should see something similar to
  96
  97 @quotation
  98 @example
  99 GNU LilyPond 1.6.0
 100 Usage: lilypond [OPTION]... FILE...
 101
 102 Typeset music and or play MIDI from FILE
 103
 104 LilyPond is a music typesetter.  It produces beautiful sheet music
 105 using a high level description file as input.  LilyPond is part of
 106 the GNU Project.
 107
 108 Options:
 109   -h,--help             this help
 110 [..]
 111 @end example
 112 @end quotation
 113
 114 Then, prepare a file called @file{foo.ly}, by issuing
 115 @quotation
 116 @example
 117 notepad foo.ly
 118 @end example
 119 @end quotation
 120 Enter the following into the file
 121 @quotation
 122 @example
 123
 124 \score @{ \notes @{ c4 ( ) c4 @} @}
 125
 126 @end example
 127 @end quotation
 128 Close the editor and save the file.  Then run the following command.
 129 @quotation
 130 @example
 131 ly2dvi -p foo
 132 @end example
 133 @end quotation
 134 At the end, it should say
 135 @quotation
 136 @example
 137 DVI output to `foo.dvi'...
 138 PS output to `foo.ps'...
 139 PDF output to `foo.pdf'...
 140 @end example
 141 @end quotation
 142 If you install the Cygwin's XFree86 X11 window system, tetex-x11 and
 143 ghostscript-x11 packages too, you can view the @code{dvi} output doing
 144 @code{xdvi test.dvi}.  If you have installed a PostScript/PDF viewer,
 145 such as @code{GSView} from @uref{http://www.cs.wisc.edu/~ghost},
 146 viewing the PS file can be done with:
 147 @quotation
 148 @example
 149 gsview32 foo.ps
 150 @end example
 151 @end quotation
 152
 153 If this works, then you can head to the
 154 @uref{../../user/out-www/lilypond/Tutorial.html,Tutorial}
 155 @ignore
 156 Hmm, this only works for 1.5.73-1 installs.
 157 Cygwin does not yet have an html documentation index, such as dwww.
 158 (@uref{file:///c/cygwin/usr/doc/lilypond-1.5.73-1/html/Documentation/user/out-www/Tutorial.html,
 159 local copy})
 160 @end ignore
 161 to start using LilyPond.
 162
 163 @section Removing LilyPond
 164
 165 Start @file{setup.exe}, click Next, select "Install from Local
 166 Directory".  Then click next until you reach "Select packages to
 167 install".  Click "View".  Now, for every package, click on the recycle
 168 icon until it says "Uninstall".  Then, click Next.
 169
 170 (If you find this too tedious, you can also simply remove
 171 @file{c:/cygwin}. This also removes the @file{/home/} directories under
 172 cygwin (i.e. @file{C:\CYGWIN\HOME}, so make sure that you bring
 173 important files in safety first.)
 174
 175 @section Troubleshooting
 176
 177 For problems and solutions see
 178 @uref{http://lilypond.org/wiki?TroubleshootingWindows,Troubleshooting
 179 Windows}
 180
 181 If you have a problem running LilyPond, you should first make sure
 182 that you are running the latest version.  Chances are, that your
 183 problem was already reported and fixed in a newer release.  Click
 184 @uref{http://cygwin.com/setup.exe, Update Lily now} to check if
 185 new software is available.
 186
 187 If you subscribe to the @uref{http://cygwin.com/ml/cygwin-announce/,
 188 cygwin-announce (archives)} mailing list, see
 189 @uref{http://sources.redhat.com/cygwin/lists.html, Cygwin mailing
 190 lists}, bottom of page.  You'll be notified of new and updated
 191 software for Cygwin, including LilyPond.
 192
 193 Chances are, that a problem you experience has been noted by others.
 194 Cygwin specific problems will be reported to the
 195 @uref{http://cygwin.com/ml/cygwin, cygwin-user (archives)} mailing
 196 list (@uref{http://sources.redhat.com/cygwin/lists.html, Cygwin mailing
 197 lists}, bottom of page).
 198
 199 LilyPond specific problems, also concering Cygwin/Windows, are
 200 reported and discussed on the
 201 @uref{http://mail.gnu.org/pipermail/lilypond-user, lilypond-user
 202 (archives)} mailing list.
 203
 204 @subsection Setup.exe does not run at all
 205
 206 Make sure that you run @uref{http://cygwin.com/setup.exe, this latest
 207 setup.exe}.
 208 This will also work if  you were using a setup.exe you donwloaded
 209 before from lilypond.org before.
 210
 211 If you're sure that you have the very latest version, and it doesn't
 212 work, and the @uref{http://cygwin.com/ml/cygwin, cygwin-user archives}
 213 do not mention the problem, write to @email{cygwin@@cygwin.com}.
 214 Setup is under heavy development, so you may have been unlucky and
 215 have dowloaded a buggy version.
 216
 217 @subsection ly2dvi:error: filename should not contain spaces
 218
 219 @quotation
 220 @emph{I don't seem to be able to either change this "default" or to point
 221 Lilypond to another directory which does not have the space.}
 222 @quotation
 223 @example
 224 ly2dvi:error: filename should not contain spaces: `/usr/bin/Ralph Whedon/foo'
 225 @end example
 226 @end quotation
 227 @emph{Any ideas what I should do?}
 228 @end quotation
 229 Best is to create a new home directory.  Start the Cygwin or LilyPond
 230 shell, and do:
 231 @quotation
 232 @example
 233 HOME=/home/ralph
 234 mkdir -p $HOME
 235 cd
 236 @end example
 237 @end quotation
 238 To go there automatically, each time you log in, edit the file
 239 @quotation
 240 @example
 241 /etc/passwd   # windows name: c:\cygwin\etc\passwd
 242 @end example
 243 @end quotation
 244
 245 using vim or wordpad, and change the `/usr/bin/Ralph Whedon/' to
 246 `/home/ralph'.
 247
 248 @subsection What's this Bash/Cygwin shell?
 249
 250 The bash shell is a basic UNIX-like console that we use for the
 251 Windows release.  Using such an intercompatible shell makes it easier
 252 to maintain the Windows release reasonably, notably because it works
 253 the same as the normal UNIX setup.  Keep in mind that none of the
 254 developers are using Windows.
 255
 256 Also it is possible to build LilyPond from source with a complete
 257 Cygwin install, see @uref{compiling.html,Compiling LilyPond on Windows}.
 258
 259 Bash is not very different from the MS-DOS shell, you'll just have to
 260 (re-)learn a few commands needed to browse through your hard-drive.
 261 Here are some commands you'll definitely be needing.
 262
 263 To change folders, the usual @code{cd}
 264
 265 @quotation
 266 @example
 267 cd ../..    # If you type this at startup, you should be in the root
 268             # directory.  Better do:
 269 cd /
 270 @end example
 271 @end quotation
 272
 273 You'll notice that file names in Bash are written with the slash (/),
 274 and not the backslash (\) bar as in MS-DOS and Windows.
 275
 276 @quotation
 277 @example
 278 C:\Win98\Bureau\  ---> /cygdrive/c/Win98/Bureau
 279 @end example
 280 @end quotation
 281 The equivalent of the MS-DOS dir command is ls -l :
 282 @quotation
 283 @example
 284 ls -l       #You'll get the listing of the current folder.
 285 @end example
 286 @end quotation
 287 To copy a file, use the cp command:
 288 @quotation
 289 @example
 290 cp srcfile destfile
 291 @end example
 292 @end quotation
 293 For more information, see the
 294 @uref{http://www.linuxdoc.org/HOWTO/DOS-Win-to-Linux-HOWTO.html,DOS/Windows
 295 to Linux HOWTO}.
 296
 297
 298
 299 @subsection Requirements and DLLs
 300
 301 TeTeX and LilyPond depend on a number of library packages, but as it
 302 seems, they sometimes do not get selected automagically.
 303
 304 @itemize @samp
 305 @item teTeX
 306   requires: ash cygwin ed grep jpeg libkpathsea3 libncurses6 libpng12 tiff
 307   sed termcap zlib
 308
 309 @item LilyPond
 310   requires: bash libguile14 libiconv2 libintl2 libkpathsea3 python
 311   tetex-bin, tetex-tiny or tetex-base
 312 @end itemize
 313
 314 @multitable @columnfractions .40 .40
 315 @item DLL              @tab Package
 316 @item cygguile-14.dll  @tab libguile14
 317 @item cygintl-2.dll    @tab libintl2
 318 @item cygiconv-2.dll   @tab libiconv2
 319 @item cygltdl-3.dll    @tab libltdl3
 320 @item cygpcre.dll      @tab pcre
 321 @item cygpng12.dll     @tab libpng12
 322 @item cygtiff3.dll     @tab tiff
 323 @end multitable
 324
 325 Also, the more general info on missing DLLs may be helpful:
 326 @example
 327     @uref{http://cygwin.com/faq/faq_4.html#SEC32}
 328     @uref{http://cygwin.com/ml/cygwin/2002-01/msg01619.html}
 329 @end example
 330
 331 @subsection Why don't you fix this?
 332
 333 Well, we've tried several times, but we can't reproduce the problem
 334 ('It works for me').  If you're experiencing DLL problems, you're much
 335 invited to help us find the bug and fix it.  You can install the
 336 binutils package, and use objdump to find which executable depends on
 337 the missing dll.
 338 @quotation
 339 @example
 340 objdump -x <path to download dir>/setup.exe | grep -i dll
 341 objdump -x /usr/bin/awk.exe | grep -i dll
 342 objdump -x /usr/bin/python.exe | grep -i dll
 343 @end example
 344 @end quotation
 345 Of course, you should check what version of the offending package you
 346 have installed (see @file{/var/log/setup.log} and
 347 @file{/var/log/setup.log.full)}.
 348
 349 @subsection Check your TeX installation
 350
 351 Start a LilyPond shell and run
 352 @quotation
 353 @example
 354 latex sample2e
 355 @end example
 356 @end quotation
 357 This should print a few lines of information and produce a file
 358 @file{sample2e.dvi}. Then run
 359 @quotation
 360 @example
 361 dvips sample2e
 362 @end example
 363 @end quotation
 364
 365 which produces a sample2e.ps, which you can view using @code{gsview32}.
 366
 367 When this works correctly, you could resume your attempts with
 368 LilyPond.
 369
 370
 371 @subsection Bugreports
 372
 373 So you have checked by running @uref{http://cygwin.com/setup.exe,
 374 Update Lily now} that you run the latest version, and
 375 @uref{http://lilypond.org/wiki?TroubleshootingWindows,Troubleshooting
 376 Windows} nor @uref{http://cygwin.com/ml/cygwin, cygwin-user
 377 (archives)} or @uref{http://mail.gnu.org/pipermail/lilypond-user,
 378 lilypond-user (archives)} mentions your problem.  It looks like you
 379 found a bug.
 380
 381 We can only help you with a problem if you give a full, detailed
 382 bugreport. A bugreport includes
 383
 384 @itemize @bullet
 385 @item A @emph{precise} description of the problem.
 386 @item A full description of your platform (machine type, operating
 387 system)
 388 @item All version numbers of relevant software you run.
 389       The best way to this is to run
 390       @quotation
 391       @example
 392       sh -x /usr/bin/bug-lilypond-cygwin >& bug.txt
 393       @end example
 394       @end quotation
 395       and include the file @file{bug.txt}.  (If you are running
 396       lilypond 1.5.73 or earlier, download
 397       @uref{http://lilypond.org/cygwin/bug-lilypond-cygwin,
 398       bug-lilypond-cygwin here}.
 399 @end itemize
 400
 401 If you have trouble using bug-lilypond-cygwin, you must gather this
 402 information by hand.  Specifically, we want to see the output of the
 403 following commands:
 404 @itemize @bullet
 405 @item Version info
 406 @quotation
 407 @example
 408   python -V
 409   lilypond --version
 410   ly2dvi --version
 411 @end example
 412 @end quotation
 413 @item If ly2dvi fails, then please run it as follows and include the
 414   output in the
 415 @quotation
 416 @example
 417   ly2dvi --verbose MY-FILE
 418 @end example
 419 @end quotation
 420 @end itemize
 421
 422 The file @file{bug.txt} should contain information on your system
 423 (check that).  Send your problem together with @file{bug.txt} to
 424 @email{lilypond-user@@gnu.org}.
 425
 426 Be sure to turn off HTML email.  It is very annoying.  For reasons
 427 unknown to man, most Windows email clients have that turned on by
 428 default.
 429
 430 If you are using Microsoft Outlook (Express), you can send normal
 431 plain text messages by clicking through the menus
 432 Tools/Options/Send/Mail Sending Format/Plain Text, with options:
 433 @quotation
 434 @example
 435 Set Message format as MIME, set "Encode text using:" to None.  Set
 436 Automatically wrap text at 70, and > is used to indent original text.
 437 @end example
 438 @end quotation
 439 Easy instructions for various email clients can be found at
 440 @uref{http://helpdesk.rootsweb.com/listadmins/plaintext.html,
 441 helpdesk.rootsweb.com}.
 442