stepmake/INSTALL.texi

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