release: 1.0.1

[lilypond.git] / Documentation / README-W32.yo

article(LilyPond on W32)
        (Jan Nieuwenhuizen and Jeffrey Reed)
        () 

No, there's no reason to be concered, Lily should work in
Windows-NT(/95/98?) too.  The setup may not be easy or smooth.  This
document will help you getting started.

sect(DISCLAIMER)

If you have the Cygnus gnu-windows32 port of the GNU utils, LilyPond
will work in Windows-NT (/95/98?).

We still recommend you use Unix.  In particular, use GNU/Linux: We've
been there, and we've seen it happen several times.  It is bf(much)
easier and quicker to install RedHat Linux and LilyPond than to
obtain, compile and install all the necessary tools to compile and run
LilyPond on Windows.

``Ok, thanks for the suggestions.  I can't run Linux or I don't want
to run Unix.  What can I expect?''

itemize(
it()LilyPond development is moving quite fast, and all developers use Unix.  
    Newly added features may require some attention to get them to work.
it()LilyPond depends on a number of other packages that usually are
    available on Unix boxes, but are not installed by default on Windows.
)

subsect(INSTALL)

Like Yodl, LilyPond will now install/extract in a unix-like tree:
verb(
    usr/[local/]bin/
    usr/[local/]share/lilypond/*
)
etc.

Both Yodl and Lily run in a the unix-like Cygnus gnu-windows environment;
hopefully Cygnus will adopt the file(/usr/[local/]) tree too.

nl()
If you really don't want usr/ in your root directory, but rather scatter
your programs and packages all over your harddisk, do something like:    
verb(
    md lilypond
    cd lilypond
    unzip ../lilypond-0.1.77.exe.zip
)
and add file(lilypond/usr/bin) to your file(PATH) and 
file(lilypond/usr/share/lilypond) to your file(LILYINCLUDE).


subsect(BUILDING LILYPOND)

If you've received a binary release of LilyPond (file(.exe.zip)),
you may skip the following sections.

subsect(GOOD NEWS)

It can be done!  Occasionally, the Cygnus b19.1 cross compiler and
utilities under GNU/Linux are used to make the binary file(.exe.zip)
releases (some makefile hacking was needed to build this stuff).  Jeffrey
Reed tries to keep-up with LilyPond development, and is doing quite well.

subsect(UNPACKING)

I have heard of such tools that think they're probably much smarter than the
packager and thus decide for themselves that they don't need to unpack certain
files (e.g., empty directories such as bin/out).

To unpack the lilypond sources, you should do something like: verb( 
    tar zxf releases/lilypond-x.y.z.tar.gz
)

subsect(ABOUT UNIX)

If you're familiar with the GNU/Cygnus development package, you may skip
this.

Don't forget to set
verb(
    /start/settings/control-panel/system/environment/system-variables:
    GCC_EXEC_PREFIX=/Cygnus/b19/H-i386-cygwin32/lib/gcc-lib/
    MAKE_MODE=UNIX
)
You want to run bash, while building Lily:
verb(
    c:\bash
    bash-2.01$ 
)
The install instructions mention something like:
verb(
    configure
    make
    make install
)

Now for a small UNIX lesson:  The current working directory (cwd) is 
by default not in your PATH, like it is under DOS (for security reasons).
Check this by looking at the output of:
verb(
    echo $PATH
)
The cwd looks like code('::') or code(':.').  If it's not there, you may 
add the cwd to your path:
verb(
    PATH=$PATH:. 
)
or you must use './' when issuing a command in th cwd, try: 
verb( 
    ./configure
    make
)

sect(LILYPOND Windows-NT Support -- by Jeffrey Reed)

My point of reference comes from 15 odd years working with a variety
of tt(UNIX) platforms.  I am relatively new to Windows-NT and, even
though I am a card carrying tt(UNIX) bigot, I am excited about the
NT OS.  My goals for lilypond are to give back to the Free Software
Foundation a little of what they have given me over the years and to
contribute to the lilypond project by supporting a Windows-NT port.  I
hope that someday we can distribute and run lilypond on the NT OS in a
much more native fashion.

itemize(
it()link(Building lilypond on tt(Windows-NT))(build)
it()link(Maintaining lilypond on tt(Windows-NT))(maintain)
it()link(Running lilypond on tt(Windows-NT))(run)
)


subsect(Building lilypond on Windows-NT) label(build)
Currently as stated above lilypond is primarily a tt(UNIX) thing.
The Windows-NT port is based on the tt(UNIX) environment provided by
url(Cygnus)(http://www.cygnus.com). Therefore the first step is to
download and install the Cygnus development kit:

subsubsect(Cygnus Development Kit)
lurl(http://www.cygnus.com/misc/gnu-win32/)


Please follow the documentation Cygnus has on there web site for
downloading and installing.  The important part is that you down load
the entire development kit.  I believe it is file(cdk.exe).  The
installation will ask you where you want to install it.  I will refer
to Cygnus installation directory as file(/gnuwin32/b19).  There should be a
file(README) file that contains installation instructions.  After the
installation is complete you should have a em(Cygnus) shortcut in your
em(Program) section of your em(Start Menu).  This shortcut is your
door to the tt(UNIX) world and I will refer to the resulting window
as a file(bash) shell.

The shortcut points to file(/gnuwin32/b19/cygnus.bat).  The following
is my file(cygnus.bat) file.  

verb(
@ECHO OFF
rem default environment

rem GNU cygnus installation

SET CYGREL=B19.1
SET MAKE_MODE=unix
SET LOCAL_ROOT=d:\gnuwin32
SET LOCAL_FS=d:/gnuwin32
SET LOCAL_DIR=/gnuwin32
SET CYGROOT=%LOCAL_ROOT%\b19
SET CYGFS=%LOCAL_FS%/b19
SET GCC_EXEC_PREFIX=%CYGROOT%\H-i386-cygwin32\lib\gcc-lib\
SET TCL_LIBRARY=%CYGROOT%\share\tcl8.0\
SET GDBTK_LIBRARY=%CYGFS%/share/gdbtcl

rem This was not in the original but is needed by lots of packages
SET BISON_SIMPLE=%CYGFS%/share/bison.simple

rem I place the cygnus stuff in front of /WINNT 
SET PATH=d:\bin;%CYGROOT%\H-i386-cygwin32\bin;%PATH%
SET MANPATH=%LOCAL_ROOT%\man;%LOCAL_ROOT%\b19\man;%LOCAL_ROOT%\b19\cdk-man\man;%LOCAL_ROOT%\a2ps-4.10\man
SET INFOPATH=%LOCAL_FS%/b19/cdk-man/info;%LOCAL_FS%/b19/info;%LOCAL_DIR%/info
SET PATH=%PATH%;%LOCAL_ROOT%\bin


rem General tools not included with Cygnus Development Kit


rem CVS

SET PATH=%PATH%;%LOCAL_ROOT%\cvs-1.9.28\bin
SET INFOPATH=%INFOPATH%;%LOCAL_FS%/cvs-1.9.28/info
SET MANPATH=%MANPATH%;%LOCAL_ROOT%\cvs-1.9.28\man

rem EMACS

SET PATH=%PATH%;%LOCAL_ROOT%\emacs-19.34\bin
SET INFOPATH=%INFOPATH%;%LOCAL_FS%/emacs-19.34/info

rem VIM

SET VIM=%LOCAL_ROOT%\vim-4.6\doc
SET PATH=%PATH%;%LOCAL_ROOT%\vim-4.6

rem TeX

SET PATH=%PATH%;%LOCAL_ROOT%\texmf\miktex\bin

rem a2ps

SET PATH=%PATH%;%LOCAL_ROOT%\a2ps-4.10\bin
SET INFOPATH=%INFOPATH%;%LOCAL_FS%/a2ps-4.10/info
SET MANPATH=%MANPATH%;%LOCAL_ROOT%\a2ps-4.10\man

rem python

SET PATH=%PATH%;\Program Files\Python

rem perl

SET PATH=%PATH%;\qub

rem yodl

SET PATH=%PATH%;%LOCAL_ROOT%\yodl-1.30.0.pre10\bin
set MANPATH=%MANPATH%;%LOCAL_ROOT%\yodl-1.30.0.pre10\man

uname -sv
bash -login
)

Please look over this carefully. Be careful with the forward and
backward slash notations.  The paths specified were done for good
reasons.  Maybe someday we will all be using code(UNC).  Note the
tt(BISON) entry and the tt(PATH) ordering in particular. Also note
that the generic file(cygnus.bat) you will be looking at does not
include alot of the packages listed.  We will be installing some of
these.

There is also some discussion of how you want to em(mount) the Cygnus
development kit.  em(mount) is a tt(UNIX) term that refers to the
mechanism used to provide a disk resource to the filesystem.  Cygnus
supplies a mechinism for em(mounting) a filesystem as a tt(DOS) like
resource or a tt(UNIX) like resource.  Among other things this
attempts to deal with the text file carriage return line feed on
tt(DOS) versus the line feed on tt(UNIX) and the issue that tt(DOS)
has two file types, text and binary.  Where tt(UNIX) deals with a
single streams type.  I have used the default out of the box
configuration with no problems.  We will however later discuss
mounting a directory as a binary resource ref(binary).

The installation also suggests that you create a directory file(/bin)
and copy file(/gnuwin32/b19/H-i386-cygwin32/bin/sh.exe) to file(/bin).
The file(sh.exe) shell provided by Cygnus is a descendant of the
file(ash) shell and I have found that some of the tt(GNU) products
configure/installations work better with the file(bash) shell.  So
this is my recommendation for post installation steps.  From a
file(bash) shell:

itemize(
it()code(cd /)
it()code(mkdir bin)
it()code(cd /bin)
it()code(cp /gnuwin32/b19/H-i386-cygwin32/bin/bash.exe sh.exe)
it()code(cd /)
it()code(mkdir /tmp)
it()code(chmod a+rwx tmp)
it()code(mkdir /etc)
it()code(cd /etc)
it()code(mkpasswd -l > passwd)
it()code(mkgroup -l > group)
)

subsubsect(Ecgs Compiler, assembler, and linker)
lurl(http://www.xraylith.wisc.edu/~khan/software/gnu-win32/egcs.html)


Cygnus recommends using the ecgs compiler.  I do too.  Follow the
instructions from the above site to install ecgs compiler/linker and
the gas assembler.  We have attempted to compile lilypond with the
Cygnus default compiler/linker with poor results.  So for lilypond
anyway this step is a requirement.

I took the following steps to download and install the ecgs suite.
Keep in mind that it is better to follow the instructions from the
indicated website.

itemize(
it()download
url(egcs-1.0.2-cygb19.tar.gz)(ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/cygwin32/b19-releases/egcs-1.0.2-cygb19.tar.gz)
to /tmp
it()download
url(gas-980303-cygb19.tar.gz)(ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/cygwin32/b19-releases/gas-980303-cygb19.tar.gz)
to /tmp
it() read
url(INSTALL)(http://www.xraylith.wisc.edu/~khan/software/gnu-win32/egcs-cygb19-install.html)
)

In a bash shell
itemize(
it() cd $CYGFS/include
it() mv g++ g++-b19
it() cd $CYGFS
it() tar zxf /tmp/gas-980303-cygb19.tar.gz
it() tar zxf /tmp/egcs-1.0.2-cygb19.tar.gz
)

You now have a compiler, assembler, linker combination capable of
compiling lilypond.  

subsubsect(bf(GNU)'s Internationalization Package) 
lurl(http://www.gnu.org/order/ftp.html)

Considering the origin of the major contributors of lilypond, this is a
must.  However before we actually do a bf(GNU) build we have to
discuss some caveats of the Windows-NT OS in particular the naming of
executable files.  tt(Windows-NT) uses a .exe extension where tt(UNIX)
does not use an extension.  This causes a problem during the
installation portion of a bf(GNU) build.  The following script can be
used to help alleviate this problem.

verb(
#!/bin/sh

realinstall=/gnuwin32/b19/H-i386-cygwin32/bin/install.exe
args=''
while [ $# -ne 0 ] 
do
    case $1 in
        -*CHAR(41) args="$args $1"
            ;;

         *CHAR(41) if [ -f $1.exe ]; then
                args="$args $1.exe"
            else
                args="$args $1"
            fi
            ;;
    esac
    shift
done

$realinstall $args
)

I place this in script file(~/bin).  Having said that here is how one
might build the em(gettext) package.

itemize(
it() download the package from one of the ftp sites.
it() From a bash shell, cd ~/usr/src.
it() tar zxf gettext-0.10.tar.gz
it() cd gettext-0.10
it() ./configure --prefix=$CYGFS/H-i386-cygwin32
it() make
it() make install
)

subsubsect(bf(GNU)'s roff package) 
lurl(http://www.gnu.org/order/ftp.html)

Following the instructions for em(gettext) package to download, build,
and install the em(groff) package.

subsubsect(Python Programing Language) 
lurl(http://www.python.org)

Python is the scripting language of choice for a lilypond build.
There is a native tt(Windows-NT) self extracting binary distribution
available.  I recommend installing Python in a directory that does
bf(not) have spaces.  And then place it in the bash shell path by
editing $CYGFS/cygnus.bat.

subsubsect(Perl Programing Language) 
lurl(http://www.cpan.org)

I believe perl is used in some legacy scripts to date.  There is a
native tt(Windows-NT) self extracting binary distribution available.
I recommend installing Perl in a directory that does bf(not) have
spaces.  And then place it in the bash shell path by editing
$CYGFS/cygnus.bat.

subsubsect(Yodl Document Language) 
lurl(http://www.digicash.com/~jan/yodl/)

Yodl for documentation in Lilypond.  It is currently being updated by
Jan Nieuwenhuizen.  The development methodology of em(Yodl) as well as
em(LilyPond) relies on a the following directory structure:

label(dirstr)
verb(
$HOME/usr/src/
       |-releases/
       |-patches/
       |-test/
)

description(

dit(releases/) Downloaded and generated releases live here.  For
example file(yodl-1.30.0.pre12.tar.gz) and
file(lilypond-0.1.81.tar.gz).

dit(patches/) Downloaded and generated patches live here.  For
example file(yodl-1.30.0.pre12.diff.gz) and
file(lilypond-0.1.81.diff.gz).

dit(test/) This directory is used to generate releases and patches.

)

I strongly recommend using this file structure to build em(yodl) and
em(lilypond).
                                   
itemize(
it() download the package from
lurl(http://www.digicash.com/~jan/yodl/) to
file($HOME/usr/src/releases).
it() From a bash shell, cd file($HOME/usr/src).
it() tar zxf releases/yodl-em(<version>).tar.gz 
it() cd yodl-em(<version>)
it() ./configure --prefix=/gnuwin32/yodl-em(<version>) --srcdir=.
Since em(yodl) is under development I choose to install it in a
version rooted directory.  This allows me to test newly released
versions without losing a known working version.
it() make
it() make install
it() place it in the bash shell path by editing $CYGFS/cygnus.bat.
For example:
verb(\
rem yodl

SET PATH=%PATH%;%LOCAL_ROOT%\yodl-1.30.0.pre12\bin

)
)

subsubsubsect(Yodl build CAVEAT)

em(yodl) uses the em(stepmake) package for it's build methodology.
The build of em(stepmake) documentation will fail due to the fact
that em(yodl) is not yet installed.  This is normal and shouldn't be a
problem.

subsubsect(Lilypond) label(lilybuild)
itemize(
it() download the package from
lurl(http://www.cs.uu.nl/people/hanwen/lilypond/) to
file($HOME/usr/src/releases).
it() From a bash shell, cd file($HOME/usr/src).
it() tar zxf releases/lilypond-em(<version>).tar.gz 
it() cd lilypond-em(<version>)
it() ./configure --prefix=/gnuwin32/lilypond-em(<version>) \ nl()
        --srcdir=. \ nl()
        --enable-tex-prefix=/gnuwin32/lilypond-em(<version>)/texmf \ nl()
        --enable-tex-dir=/gnuwin32/lilypond-em(<version>)/texmf/tex \ nl()
        --enable-mf-dir=/gnuwin32/lilypond-em(<version>)/texmf/mf nl()
Since em(lilypond) is under development I choose to install it in a
version rooted directory.  This allows me to test newly released
versions without losing a known working version.
it() make
it() make install
it() place it in the bash shell path by editing $CYGFS/cygnus.bat.
For example:
verb(\
rem lilypond

SET PATH=%PATH%;%LOCAL_ROOT%\lilypond-0.1.80\bin

)
)

subsect(Maintaining lilypond on Windows-NT) label(maintain)

If you have built em(lilypond) on tt(Windows-NT) using the directory
structure described link(previously)(dirstr) and the process described
in section ref(lilybuild), then you are ready to maintain
em(lilypond).  It can not be that easy!?  Well, there is one caveat.
Currently to use the file(stepmake/bin/release.py) and
file(stepmake/bin/package-diff.py) scripts you need to obtain/build a
version of em(python) that was built with bf(Cygnus) development kit.
The process I used is as follows:

itemize(
it() obtain python source from lurl(http://www.python.org)
it() tar zxf /tmp/python-em(<version>).tar.gz 
it() cd python-em(<version>)
it() configure --prefix=/gnuwin32/python-em(<version>)
it() edit toplevel file(Makefile) code(EXE) macro so it reads code(EXE=.exe)
it() make
it() make install
it() place it in the bash shell path by editing $CYGFS/cygnus.bat.
For example:
verb(\
rem python

SET PATH=%PATH%;%LOCAL_ROOT%\python-1.5.1\bin

)
)

I choose to build em(lilypond) with the standard tt(Windows-NT)
em(python) and use the bf(Cygnus) version for using the release
scripts.  This way I can make sure the tt(Windows-NT) em(python)
version is able to build em(lilypond).  Currently there are several
issues with the release scripts.  Using code(os.link) and
code(os.system(set -x;...)) are to name a few.

To generate a new release and patch you must use the directory
structure described link(previously)(dirstr).  And follow the
instructions found in file(PATCH.txt).  Editing
file(Documentation/AUTHORS.yo), file(VERSION), and file(NEWS) is also
required.  When my edits are complete and tested I:

itemize(
it() Edit file(config.make) and change em(python) path to the
bf(Cygnus) version: code(PYTHON=/gnuwin32/Python-1.5.1/bin/python).
it() make release
)

The new release is placed in file(releases) directory and the patch is
placed in the file(patches) directory.  I email the new patch to
email(gnu-music-discuss@gnu.org).  More than one patch a day can be
generated by:

itemize(
it() cd $HOME/usr/src 
it() tar zxf releases/lilypond-em(<version>).em(<patchlevel>)
it() use your normal configure
it() make edits
it() Change file(VERSION) to increment em(<patchlevel>)
it() Change file(NEWS)
it() make release
)

subsect(Running lilypond on Windows-NT) label(run)
 
label(binary)

Jeffrey B. Reed email(daboys@bga.com)


sect(RUNNING LILYPOND -- by Dominique Cretel)

enumerate(
eit() First, I have download tha 0.1.64 version of Lilypond music software.

eit() Then I extract it in a temp directory, and I move the directory
"lilypond-0.1.64" to the root directory of my D drive.

eit() I go to the D:\Lilypond-0.1.64\tex directory to modify the
lilyponddefs.tex file (lines 75 and 84), and comment all
cmbx15 ans cmbx14, and replace them by cmbx12.

eit() build a command file like this:
Note: I use MiKTeX to process the tex file generated.

verb(
---begin ly2dvi.bat
echo off
set ver=0.1.64
set path=%path%;d:\lilypond-%ver%\bin
lilypond -I d:\lilypond-%ver%\init %1
rem *** pause

set path=c:\texmf\miktex\bin;%path%
set TEXINPUTS=%TEXINPUTS%;d:\lilypond-%ver%\tex
set MFINPUTS=%MFINPUTS%;d:\lilypond-%ver%\mf
tex %1.tex
rem *** pause

dvips %1.dvi
rem *** pause

set path=%path%;d:\gstools\gsview
gsview32 %1.ps
---end ly2dvi.bat
)

eit() execute lilypond by doing:
verb(
ly2ps silly <Enter>
)
)

Note:
nl()
You'll better have to put the SET commands lines in a separate command
file to avoid consumming each time environnment ressources.

Bye,nl()
Dominique Cretel email(dominique.cretel@cfwb.be)


sect(PROBLEMS AND ANWSWERS)

subsect(CONFIGURE AND INSTALL)
This is all to confusing.  I have:
enumerate(
eit() downloaded file(/tmp/lilypond-0.1.78.tar.gz)
eit() verb(
    cd ~/usr/src
)
eit() verb(
    tar zxf /tmp/lilypond-0.1.78.tar.gz
)
eit() verb(
    ./configure --prefix=/users/jeff/lilypond-0.1.78 \\\

        --enable-tex-prefix=/users/jeff/lilypond-0.1.78/texmf \\\

        --enable-tex-dir=/users/jeff/lilypond-0.1.78/texmf/tex \\\

        --enable-mf-dir=/users/jeff/lilypond-0.1.78/texmf/mf
)
eit() verb(
    make
)
eit() verb(
    make install
)
)

I did have a problem with lilypond.info.  And I will look into this
further.  After mending lilypond.info issue, it compiled and install
with no problems.

I have 64 Meg of physical memory and 64 Meg of swap.  Actually I need
to increase the swap space.  If a memory problem is occuring it most
likely is during the link process of lilypond.  There is a boat load
of objects to link.

Jan the mount -b stuff is confussing to me.  I have the entire system
mounted _without_ -b and only use -b on certain paths for programs
that create binary files that do not use O_BINARY open option.  By the
way the midi file open is one of these cases, I need to look into
that.  I have had no problems with this methodology.


subsect(DRIVE D:)

The windows multiroot filesystem is an utterly broken concept.  Please
do everything on one (urg) drive, C:.

verb(
> configure
> creating cache ./config.cache
> [..]
> creating config.make
> creating config.hh
> cd: lstat /d failed
)

Ok, this looks like another stupid windows problem.
You're working on 'drive D:', right?

I can think of some solutions, but i don't know if they work;
i just had to do some work in windows some time ago.  If you
have problems with this, please ask email(gnu-win32@cygnus.com).
I'll start with the simplest:
itemize(
  it() do everything on drive C:, or
  it() explicitely mount drive d:, work from there:
  verb(
      mkdir -p /mnt/d
      mount d: /mnt/d
      cd /mnt/d/lilypond-x.y.z/
  )
  it() make d:/ the root of cygnus, in cmd.exe/command.exe do:
  verb(    
      umount /
      mount d: /
  )
)


subsect(INSTALLING TOOLS)

> - First I have installed Python (for win32) "Pyth151.exe" and "Configure
nl()
> don't find it. I had to put it in the path for configure find it?
nl()

Yes, of course.  It should be possible to have different versions of tools 
installed (e.g. perl 4 and perl 5).  The best way to tell people (or tools 
like configure) which one to use is to put it in the path?
  
Another small unix lesson: Where under dos each program installs itself
into a nice directory
verb(
    c:\DosProgram\*
)
under unix, installation is handled centrally.  Executables go in
file(/usr/bin) (or file(/usr/local/bin)), and are always in your path.

subsect(VIRTUAL MEMORY)

verb(
> 4. make -C lily don't work. I get an error (see below). I get several
> object files in the ./lily/out directory (34 files: 17 *.dep, 16 *.o,
> and 1 *.hh):
>    [...]
>    include/engraver-group.hh:35: virtual memory exhausted
>    make: *** [out/bar-grav.o] Error 1
>    bash-2.01$

)

Ok, so everything works now, there's only some error with one of the
source files.  Lets see which one (and now the cc's now why they're
reading this :-)

It looks like you've run out of memory.  You should compile without
optimisation, gcc/egcs need a lot of memory for optimising.
Reconfigure without optimisation:
verb(
    configure --disable-optimise
)
or edit file(config.make):
verb(
    ## USER_CXXFLAGS = -g # -O  no optimise!
    USER_CXXFLAGS = -g
)

There are some other things to look at: how much RAM do you have
(please say something > 8Mb :-)?  Although it might be an egcs bug,
you should have a look at the size of your swap file.
For an US version of windows, you should find it here:
verb(
    /start/settings/control-panel/system/performance/virtual-memory
)
you see, amongst others, these entries:
verb(
    paging file size for selected drive:

        space-available: xx
        initial-size: xx
        maximum-size: xx

    total paging file size for all drives

        currently allocated: xx
)
Try to set:
verb(
    initial-size: 64
    maximum-size: 128
)
Make sure that:
itemize(
it() maximum-size >= 128 Mb
it() urrently-allocated + space-available >= 128 Mb
)