stepmake/Documentation/topdocs/INSTALL.yo

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