Name
====

INSTALL - installing StepMake

Description
===========

This page documents installation and usage of StepMake

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:

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

You'll have to customize at least the files:

         ./VERSION .
         ./configure.in

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

         ./make/Toplevel.make.in
         ./config.hh.in
         ./config.make.in

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:

         # lily/include/Makefile

         depth = ../..
         include $(depth)/make/Stepmake.make

it will identify all .h, .hh, ... files and take care of distributing them.

There's a 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 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.

Prerequisites
=============

To use StepMake with a package you need:

  * 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.

  * GNU make

  * GNU autoconf

Recommended
===========

Although not strictly necessary, these are recommended to have.

  * Python

  * Yodl.  All documentation will be in Yodl. (1.22.jcn3)

  * GNU find

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 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:

         stepmake/stepmake/*.make

eneric helper scripts:

         stepmake/bin/*.sh
         stepmake/bin/*.py

and modular configure functions:

         stepmake/configure.in
         stepmake/aclocal.m4
         stepmake/config.hh.in
         stepmake/config.make.in

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 (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 configure.in.

Package specific makefiles go in:

         make/Targets.make
         make/Rulese.make
         make/Substitute.make

and are included by the generic StepMake makefiles.

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:

         ./stepmake/bin/stepdirs.sh

See also
========

../PATCHES.txt

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 info autoconf.

         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

with prefix $HOME/usr/src and (for building rpms only) in $HOME/.rpmrc:

         topdir: /home/fred/usr/src/RedHat

Authors
=======

  * Han-Wen Nienhuys, http://www.cs.uu.nl/people/hanwen Main author.

  * Jan Nieuwenhuizen, http://www.xs4all.nl/~jantien Main author.

  * Jeffrey B. Reed, Windows-nt fixes.