stepmake/INSTALL.txt

   1
   2 NAME
   3
   4 INSTALL - installing StepMake
   5
   6 DESCRIPTION
   7
   8 This page documents installation and usage of StepMake
   9
  10 ABSTRACT
  11
  12 StepMake is a drop-in package that takes care of generic Makefile and
  13 packaging/distribution issues.  It enables you to write only the simplest of
  14 Makefile snippets, while providing a series powerful make targets.  Features
  15 include speed, wildcarding, out/ dir build, stateless Makefiles and package
  16 clustering.  It includes some handy scripts for making (package-)diffs and
  17 patches, making binary distributions etc.
  18
  19 To use StepMake with your package, you do something remotely like:
  20
  21     tar xzf releases/stepmake-0.1.23
  22     cd package-x.x.x/                  # package to be StepMake-ised
  23     ./../stepmake-0.1.23/bin/stepmakeise.sh
  24
  25 You'll have to customize at least the files:
  26
  27     ./VERSION .
  28     ./configure.in
  29
  30 to your package's needs.  You might want to take a look at:
  31
  32     ./make/Toplevel.make.in
  33     ./config.hh.in
  34     ./config.make.in
  35
  36 Also, you should put a Makefile in every subdirectory of your
  37 package.  These makefiles generally are quite simple, e.g. this
  38 is a the makefile for an include directory of LilyPond:
  39
  40     # lily/include/Makefile
  41
  42     depth = ../..
  43     include $(depth)/make/Stepmake.make
  44
  45 it will identify all .h, .hh, ... files and take care of distributing
  46 them.
  47
  48 There's a make/Template.make that you can use as an example.
  49 See also the Makefiles in the LilyPond or Yodl package.
  50
  51 Once included in your package, StepMake (or in fact, any
  52 StepMake-ised package) behaves as a normal subdirectory;
  53 make commands such as 'make dist' recurse into the stepmake tree
  54 (For a list of available targets, type make help after
  55 configuring).
  56 Stepmake (and any changes made) will be distributed with the main
  57 pacakage.  However, StepMake doesn't lose its independency, change
  58 to the stepmake directory, and it'll behave as a main package.
  59 You shouldn't version directory names of subpackages, otherwise
  60 you'll see that package twice in each patch when you upgrade.
  61
  62 PREREQUISITES
  63
  64 To use StepMake with a package you need:
  65
  66 o A GNU system: StepMake is known to work on these GNU systems: Linux
  67     (PPC, intel), FreeBSD, AIX, NeXTStep, IRIX, Digital Unix and Solaris.
  68     If you have the Cygnus WINDOWS32 port of the GNU utils, it will even
  69     work in Windows NT/95, but we don't promise to support it.
  70 o GNU make
  71 o GNU autoconf
  72
  73 RECOMMENDED
  74
  75 Although not strictly necessary, these are recommended to have.
  76
  77 o Python
  78 o Yodl.  All documentation will be in Yodl. (1.22.jcn3)
  79 o GNU find
  80
  81 INTERNALS
  82
  83 Over time, we put a lot of effort in the configure, make, distribute
  84 system (CMDS) for LilyPond.  Some months ago, we realised it was not
  85 standard GNU --- we require GNU make for building, and Python for extra
  86 scripting.  In an effort to be more GNU, we tried automake, but after two
  87 weeks we realised the costs were too high for us and we reverted to our
  88 own system (see automake.urgh).  Not long after that i was confronted
  89 with two other packages that lacked a decent CMDS.  I realised that Lily's
  90 would be perfect, it's modular and easy.  The only problem was to make a
  91 clean cut between generic and Lily specific stuff.  The result was
  92 StepMake: a bunch of generic makefiles, found in:
  93
  94     stepmake/stepmake/*.make
  95
  96 eneric helper scripts:
  97
  98     stepmake/bin/*.sh
  99     stepmake/bin/*.py
 100
 101 and modular configure functions:
 102
 103     stepmake/configure.in
 104     stepmake/aclocal.m4
 105     stepmake/config.hh.in
 106     stepmake/config.make.in
 107
 108 Of course, every package has its own configure- and make peculiarities.
 109 The best way to create the configure scripts is to copy them from
 110 stepmake (Actually, stepmake/bin/stepmakeise.sh will do
 111 that for you.) into you package's toplevel directory.  For most
 112 packages, you'll only have to comment in/out some functions in
 113 configure.in.
 114
 115 Package specific makefiles go in:
 116
 117     make/Targets.make
 118     make/Rulese.make
 119     make/Substitute.make
 120
 121 and are included by the generic StepMake makefiles.
 122
 123 MAINTAINING
 124
 125 If you want to make and manage (binary) distributions, create and apply
 126 patches, you'll need some framework that's outside of the package's
 127 sourcetree.
 128 For a number of simple  maintenance tasks, StepMake will therefore assume
 129 the following directory structure:
 130
 131     doos/                        # gnu/windows32 build and binary releases
 132     harmonia -> harmonia-x.y.z
 133     harmonia-x.y.z/
 134     lilypond -> lilypond-x.y.z   # symlink to development directory
 135     lilypond-x.y.z/              # current development
 136     patches/                     # patches between different releases
 137     RedHat/BUILD                 # RedHat build and binary releases
 138     RedHat/RPMS
 139     RedHat/SPECS
 140     releases/                    # .tar.gz releases
 141     test/                        # tarballs and diffs from current version
 142     yodl -> yodl-1.30.17
 143     yodl-1.30.17
 144
 145 with prefix $HOME/usr/src
 146 and (for building rpms only) in $HOME/.rpmrc:
 147
 148     topdir: /home/fred/usr/src/RedHat
 149
 150 Check and update the layout with the command:
 151
 152     ./stepmake/bin/stepdirs.sh
 153
 154 SEE ALSO
 155
 156 ../PATCHES.txt
 157
 158 CONFIGURING
 159
 160 Stepmake comes with a number of precooked configure functions for
 161 general needs, such as AC_STEPMAKE_COMPILE for simple C development
 162 and AC_STEPMAKE_CXX for C++.
 163
 164 See configure.in and comment in/out the functions that your package
 165 needs.  For specific needs, you can write your own autoconf code,
 166 see info autoconf.
 167
 168 AUTHORS
 169
 170 Jan Nieuwenhuizen <janneke@gnu.org>
 171
 172 Han-Wen Nienhuys <hanwen@cs.uu.nl>
 173
 174 Have fun!