\input texinfo @c -*-texinfo-*-
@setfilename INSTALL.info
@settitle INSTALL

@node Top, , , (dir)
@top


@unnumberedsec Name
    

INSTALL - installing StepMake

@unnumberedsec Description
    

This page documents installation and usage of StepMake

@unnumberedsec Abstract
    

StepMake is a drop-in package that takes care of generic Makefile and
packaging/distribution issues.  It enables you to write only the simplest of
Makefile snippets, while providing a series powerful make targets.  Features
include speed, wildcarding, out/ dir build, stateless Makefiles and package
clustering.  It includes some handy scripts for making (package-)diffs and
patches, making binary distributions etc.

To use StepMake with your package, you do something remotely like:
@example 

    tar xzf releases/stepmake-0.1.23
    cd package-x.x.x/		       # package to be StepMake-ised
    ./../stepmake-0.1.23/bin/stepmakeise.sh
 
@end example 

You'll have to customize at least the files:
@example 

    ./VERSION .
    ./configure.in 
 
@end example 

to your package's needs.  You might want to take a look at:
@example 

    ./make/Toplevel.make.in
    ./config.hh.in
    ./config.make.in
 
@end example 

Also, you should put a Makefile in every subdirectory of your
package.  These makefiles generally are quite simple, e.g. this 
is a the makefile for an include directory of LilyPond:
@example 

    # lily/include/Makefile

    depth = ../..
    include $(depth)/make/Stepmake.make
 
@end example 

it will identify all @code{.h, .hh, ...} files and take care of distributing 
them.

There's a @file{make/Template.make} that you can use as an example.
See also the Makefiles in the LilyPond or Yodl package.

Once included in your package, StepMake (or in fact, any 
StepMake-ised package) behaves as a normal subdirectory;
make commands such as 'make dist' recurse into the stepmake tree
(For a list of available targets, type @code{make help} after
configuring).
Stepmake (and any changes made) will be distributed with the main
pacakage.  However, StepMake doesn't lose its independency, change
to the stepmake directory, and it'll behave as a main package.
You shouldn't version directory names of subpackages, otherwise
you'll see that package twice in each patch when you upgrade.

@unnumberedsec Prerequisites
    

To use StepMake with a package you need:

@itemize @bullet
@item A GNU system: StepMake is known to work on these GNU systems: Linux
    (PPC, intel), FreeBSD, AIX, NeXTStep, IRIX, Digital Unix and Solaris.
    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 GNU make 
@item GNU autoconf
@end itemize

@unnumberedsec Recommended
    

Although not strictly necessary, these are recommended to have.

@itemize @bullet
@item Python
@item Yodl.  All documentation will be in Yodl. (1.22.jcn3)
@item GNU find
@end itemize

@unnumberedsec Internals
    

Over time, we put a lot of effort in the configure, make, distribute
system (CMDS) for LilyPond.  Some months ago, we realised it was not
standard GNU --- we require GNU make for building, and Python for extra
scripting.  In an effort to be more GNU, we tried automake, but after two
weeks we realised the costs were too high for us and we reverted to our
own system (see @file{automake.urgh}).  Not long after that i was confronted
with two other packages that lacked a decent CMDS.  I realised that Lily's
would be perfect, it's modular and easy.  The only problem was to make a
clean cut between generic and Lily specific stuff.  The result was
StepMake: a bunch of generic makefiles, found in:
@example 

    stepmake/stepmake/*.make
 
@end example 

eneric helper scripts:
@example 

    stepmake/bin/*.sh
    stepmake/bin/*.py
 
@end example 

and modular configure functions:
@example 

    stepmake/configure.in
    stepmake/aclocal.m4
    stepmake/config.hh.in
    stepmake/config.make.in
 
@end example 

Of course, every package has its own configure- and make peculiarities.
The best way to create the configure scripts is to copy them from
stepmake@footnote{Actually, stepmake/bin/stepmakeise.sh will do
that for you.} into you package's toplevel directory.  For most
packages, you'll only have to comment in/out some functions in
@file{configure.in}.

Package specific makefiles go in:
@example 

    make/Targets.make
    make/Rulese.make
    make/Substitute.make
 
@end example 

and are included by the generic StepMake makefiles.

@unnumberedsec Maintaining
    

If you want to make and manage (binary) distributions, create and apply
patches, you'll need some framework that's outside of the package's
sourcetree.
For a number of simple  maintenance tasks, StepMake will therefore assume
the following directory structure:

Check and update the layout with the command:
@example 

    ./stepmake/bin/stepdirs.sh
 
@end example 

@unnumberedsec See also
    

@code{../PATCHES.txt}

@unnumberedsec Configuring
    

Stepmake comes with a number of precooked configure functions for
general needs, such as AC_STEPMAKE_COMPILE for simple C development
and AC_STEPMAKE_CXX for C++.

See configure.in and comment in/out the functions that your package
needs.  For specific needs, you can write your own autoconf code,
see @code{info autoconf}.

@example 

    doos/                        # gnu/windows32 build and binary releases
    harmonia -> harmonia-x.y.z 
    harmonia-x.y.z/
    lilypond -> lilypond-x.y.z   # symlink to development directory
    lilypond-x.y.z/              # current development
    patches/ 		         # patches between different releases
    RedHat/BUILD                 # RedHat build and binary releases
    RedHat/RPMS
    RedHat/SPECS
    releases/                    # .tar.gz releases
    test/                        # tarballs and diffs from current version
    yodl -> yodl-1.30.17
    yodl-1.30.17
 
@end example 

with prefix @file{$HOME/usr/src}
and (for building rpms only) in @file{$HOME/.rpmrc}:
@example 

    topdir: /home/fred/usr/src/RedHat
 
@end example 


@unnumberedsec Authors

@itemize @bullet
@item @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, 
    @uref{http://www.cs.uu.nl/people/hanwen}
    @* 
    Main author.

@item @email{janneke@@gnu.org, Jan Nieuwenhuizen},
    @uref{http://www.xs4all.nl/~jantien}
    @* 
    Main author.
@item @email{daboys@@austin.rr.com, Jeffrey B. Reed},
    Windows-nt fixes.
@end itemize


@bye
