source: trunk/doc/build-system @ 17298

Revision 17298, 10.7 KB checked in by ghudson, 22 years ago (diff)
Suggest /tmp instead of /var/tmp, just to make the examples shorter. Which is best to use is a matter of preference.
1This document explains how to build packages from the Athena source
2tree, and then describes guidelines for designing the build system for
3code we maintain in the Athena source tree.  A discussion of building
4packages we get from third parties is in the file "third-party" in
5this directory.
7This file contains the following sections:
9        Building packages from the source tree
10        Building the tree
11        Generic build system guidelines
12        Using Autoconf
13        Using a straight Makefile
15Building packages from the source tree
18To build a package from the Athena source tree, you should generally
19first attach the source tree that you want.  You can either attach a
20locker like "source-8.0" or "source-8.1" to get the sources for a
21particular release, or you can attach "source" to get the current
22development sources.  Releases prior to 8.1 will not build using the
23procedure below.  Note that you can only build whole packages, not
24arbitrary subdirectories; package names are listed in
27After attaching the correct locker, you can build a package by doing:
29        set src = /mit/source           # or /mit/source-8.1, etc.
30        mkdir /tmp/PACKAGE-NAME
31        cd /tmp/PACKAGE-NAME
32        synctree -s $src/PATH-TO-PACKAGE -d . -a $src/.rconf
33        sh $src/packs/build/ dist
34        sh $src/packs/build/ prepare
35        sh $src/packs/build/ all
37If you are building the from the current sources (that is, $src is
38/mit/source), the package may have dependencies on changes which have
39been made since the last release.  In this case, use the "-c" flag to to make the build use a recent build for tools and libraries.
41The last three commands are then:
43        sh $src/packs/build/ -c dist
44        sh $src/packs/build/ -c prepare
45        sh $src/packs/build/ -c all
47"do" accepts the following options (-c and -t are mutually exclusive):
49        -s SRCDIR       Specifies the source hierarchy, if not default
50        -d DESTDIR      Specifies the install hierarchy, if not
51                        /afs/$ATHENA_SYS/srvd-current
52        -t TOOLDIR      Specifies the tool hierarchy
53        -c              Sets the tool hierarchy to the install
54                        hierarchy
55        -n              Show what build steps would be done, but don't
56                        do them
58The default location for SRCDIR is the source locker you attached
59(/mit/source, /mit/source-8.1, etc.).  "do" supports the following
60build operations:
62        dist            Copy in or create any materials necessary to
63                        make source tree suitable for distribution
64        prepare         Set up the source tree for building
65        clean           Clean any files generated by the "all" operation
66        all             Create automatically generated files
67        check           Perform automated tests, if any
68        install         Install in DESTDIR specified by -d (or default)
70Building the tree
73To build the entire tree by hand, attach an appropriate source locker
74and do something like the following:
76        set src = /mit/source
77        mkdir /tmp/build
78        cd /tmp/build
79        synctree -s $src -d .
80        sh $src/packs/build/ -b `pwd` -d /tmp/inst
82"build" accepts the following options:
84        -s SRCDIR       Specifies the source hierarchy, if not default
85        -b BUILDDIR     Specifies the build hierarchy, if not /build
86        -d DESTDIR      Specifies the install hierarchy, if not /.srvd
87        -t TARGET       Build a single target and its dependencies
88        -k              Keep going if a package fails to build
89        -n              Only display a list of packages to be built
90        -l              Log build output to a file.
92As with "do", the default location for SRCDIR is the source locker you
95Building the whole tree has the following requirements right now:
97        * The system passwd file must have "pop" and "discuss" users.
98          Athena machines should typically have these lines in them
99          already, but you may have to add them on non-Athena systems.
101        * You must have write access to the destination hierarchy, and
102          be able to chown files and make setuid root files in that
103          tree.
105        * On Solaris, you need system:authuser access to the Athena
106          cell in order to build third/gcc (since it is bootstrapped
107          with the sunsoft compiler).
109Therefore, if you have a machine newly installed with the vendor
110operating system and AFS, and you want to build the Athena source tree
111for the first time, you have to do a little work beforehand:
113        * Make a temporary directory to put binaries in:
115                mkdir /tmp/bin
116                set path = ($path /tmp/bin)
118        * You need a functioning synctree.  The sources are in
119          athena/etc/synctree; because they are not world-readable,
120          you may need to copy the sources somewhere temporary from
121          another workstation in order to get them onto the machine
122          you're building on.  Once you have a copy of the sources,
123          building them is relatively easy:
125                set src = /afs/
126                ./configure
127                make
128                cp synctree /tmp/bin
129                rehash
131        * You need a functioning kinit.  In the worst case, you may
132          need to do a partial build of third/krb5.
134                cd /tmp; mkdir krb5; cd krb5
135                synctree -s $src/third/krb5 -d . -a $src/.rconf
136                make -f Makefile.athena prepare
137                make -f Makefile.athena all
139                cp src/clients/kinit/kinit /tmp/bin
140                cp $src/packs/config/krb5.conf /etc
141                mkdir /etc/athena
142                cp $src/packs/config/krb.conf /etc/athena
143                cp $src/packs/config/krb.realms /etc/athena
145        * For Solaris, you need a functioning aklog.
147                cd /tmp; mkdir aklog; cd aklog
148                synctree -s $src/athena/bin/aklog -d . -a $src/.rconf
149                ./configure --with-afs=/usr/afsws # or wherever
150                make
151                cp aklog /tmp/bin
153        * For a few packages (third/perl and some things under packs),
154          /os must point to an image of the operating system.  A
155          symlink from /os to / will usually service if a pristine
156          operating system image is unavailable.
158With these tools, you should be able to set up the build environment
159as documented above.
161Generic build system guidelines
164Here are some desirable properties of a build system for programs or
165libraries, regardless of how it is implemented:
167        * It should use feature tests, not platform tests.
169        * Once the appropriate configuration steps (e.g. running
170          configure or imake) have been done, "make all" should
171          generate all automatically generated files without ever
172          modifying any source files.  (For example, "make all" should
173          not try to regenerate configure from, and a
174          build system should not wait until "make install" time to
175          generate a file which is going to be installed.)
177        * "make install" should install all files appropriate for the
178          target directories without modifying any files in the build
179          tree.  In particular, it should not depend on the "all"
180          target.
182          "make install" should use the install command to install
183          files, not cp or tar or shell redirection.  To install
184          multiple files in the same way, use a single install command
185          rather than a for loop.
187        * "make clean" should clean all files generated by "make all."
188          "make distclean" should also delete files generated by the
189          configuration steps.
191        * "make check" should run self-tests.  It should not assume
192          that the program has been installed, but it should assume
193          that the program has been built.  It should not modify the
194          build tree in any way; in particular, it should not depend
195          on the "all" target.  If there are no self-tests, "make
196          check" should not generate an error.
198        * In a multi-directory source tree, it should be possible to
199          change to a subdirectory of the build tree and run any of
200          the aforementioned make targets with the same results as
201          having descended into that directory from above.  It is okay
202          to assume that previous parts of the build tree have been
203          built, but it is not okay to rely on make command-line
204          parameters passed in from the parent directory.
206Using Autoconf
209For packages in the "athena" hierarchy, we use autoconf.  Autoconf is
210not perfect, but it's the only reasonable package out there for doing
211feature tests as opposed to platform tests.  See the Autoconf info
212pages (available in the default emacs info menu) for information about
213using Autoconf in general.
215When we build the program for the Athena environment, we will use a file (already written; you don't need to write it or point
217to it) which does the following:
219        * Sets the shell variable "athena" to "true".
221        * Sets the appropriate compiler (using the CC environment
222          variable) as well as other compilation tools (yacc, lex) for
223          the platform in question.
225        * Sets the appropriate X include path and library path for use
226          with AC_PATH_X.
228        * Sets the appropriate with_* variables for finding Motif, AFS
229          libraries, Kerberos 4, Kerberos 5, com_err, and ss.  If your
230          package uses any of those libraries, copy the aclocal.m4
231          file from packs/build and use the macros contained within.
233        * Sets prefix to /usr/athena, datadir to '${prefix}/lib',
234          sbindir to '${prefix}/etc', and sysconfdir to '/etc/athena'.
235          You do not need to take these into account in;
236          just put in your
238                prefix=@prefix@
239                exec_prefix=@exec_prefix@
240                datadir=@datadir@
241                sbindir=@sbindir@
242                sysconfdir=@sysconfdir@
244        * Sets shell variables lbindir and lsbindir to /bin/athena and
245          /etc/athena respectively.  If your build system needs to
246          install files in /bin/athena or /etc/athena when built for
247          the Athena environment, use the following in your
249                test -z "$lbindir" && lbindir='${bindir}'
250                test -z "$lsbindir" && lsbindir='${sbindir}'
251                AC_SUBST(lbindir)
252                AC_SUBST(lsbindir)
254          And then in your
256                prefix=@prefix@
257                exec_prefix=@exec_prefix@
258                bindir=@bindir@
259                sbindir=@sbindir@
260                lbindir=@lbindir@
261                lsbindir=@lsbindir@
263The build environment will ensure that the following things are true:
265        * The environment variable ATHENA_SYS is set to the current
266          platform's desired ATHENA_SYS value (e.g. "sun4m_54").
268        * The environment variable HOSTTYPE is set to the current
269          platform name (e.g. "sun").
271        * The environment variable CONFIG_SITE points to the Athena
272 file.
274Using a straight Makefile
277For packages in the "packs" hierarchy, and in some parts of the
278"third" hierarchy where we construct the build system by hand, we use
279a straight Makefile, since feature tests are not necessary for the
280packs hierarchy.
282The build system will ensure that the same environment variables are
283set as for using Autoconf.  In addition, the make variable CC will be
284set to the appropriate compiler for the current platform when the
285"all" target is invoked.  You should be sparing in your use of C
286source code in packages using a straight Makefile, but for small,
287portable C programs it's okay.
289The subdirectories "platform/$HOSTTYPE" or "arch/$ATHENA_SYS" should
290be used for platform or system-dependent components of a package using
291a straight Makefile.
293Start each Makefile with "# $Id: $" and "SHELL=/bin/sh".  The latter
294is to work around a bug in the Irix make where it runs commands under
295${SHELL} rather than /bin/sh.
Note: See TracBrowser for help on using the repository browser.