source: trunk/doc/build-system @ 11692

Revision 11692, 10.1 KB checked in by danw, 26 years ago (diff)
Update bootstrapping info... synctree uses autoconf now, and third/cns has been replaced with third/krb5. I didn't touch the aklog instructions, since the truth is more complicated than it implies (It needs to find the krb libraries) and I wasn't sure the best way to do it.
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 /var/tmp/PACKGAGE-NAME
31        cd /var/tmp/PACKAGE-NAME
32        synctree -s $src/PATH-TO-PACKAGE -d . -a $src/.rconf
33        sh $src/packs/build/ prepare
34        sh $src/packs/build/ all
36"do" accepts the following options:
38        -s SRCDIR       Specifies the source hierarchy, if not default
39        -d DESTDIR      Specifies the install hierarchy, if not /srvd
41The default location for SRCDIR is the source locker you attached
42(/mit/source, /mit/source-8.1, etc.).  "do" recognizes supports the
43following build operations:
45        prepare         Set up the source tree for building
46        clean           Clean any files generated by the "all" operation
47        all             Create automatically generated files
48        check           Perform automated tests, if any
49        install         Install in /srvd (or dir given by -d option)
51Building the tree
54To build the entire tree by hand, you run packs/build/ from
55the source directory.  Building the tree has the following
56requirements right now:
58        * The system passwd file must have "pop" and "discuss" users.
59          Athena machines should typically have these lines in them
60          already, but you may have to add them on non-Athena systems.
62        * The source tree must be findable in the default location
63          (/mit/source for the current sources), or you must tell
64 where to find the source tree using the -s option.
66        * You must have a link farm of the source tree generated by
67          synctree.  The default location is /build; you can specify
68          an alternative location with the -b option.
70        * You must have write access to a destination tree, and be
71          able to chown files and make setuid root files in that tree.
72          The default location is /srvd; you can specify an
73          alternative location with the -d option.
75        * On Solaris, you need system:authuser access to the Athena
76          cell in order to build third/gcc (since it is bootstrapped
77          with the sunsoft compiler).
79Therefore, if you have a machine newly installed with the vendor
80operating system and AFS, and you want to build the Athena source tree
81for the first time, you have to do a little work beforehand:
83        * Make a temporary directory to put binaries in:
85                mkdir /var/tmp/bin
86                set path = ($path /var/tmp/bin)
88        * You need a functioning synctree.  The sources are in
89          athena/etc/synctree; because they are not world-readable,
90          you may need to copy the sources somewhere temporary from
91          another workstation in order to get them onto the machine
92          you're building on.  Once you have a copy of the sources,
93          building them is relatively easy:
95                set src = /afs/
96                ./configure
97                make
98                cp synctree /var/tmp/bin
99                rehash
101        * You need a functioning kinit.  In the worst case, you may
102          need to do a partial build of third/krb5.
104                cd /var/tmp; mkdir krb5; cd krb5
105                synctree -s $src/third/krb5 -d . -a $src/.rconf
106                make -f Makefile.athena prepare
107                make -f Makefile.athena all
109          The build will eventually bomb out because parts of it
110          depend on Hesiod and libal. This is OK.
112                cp src/clients/kinit/kinit /var/tmp/bin
113                cp $src/packs/config/krb5.conf /etc
114                mkdir /etc/athena
115                cp $src/packs/config/krb.conf /etc/athena
116                cp $src/packs/config/krb.realms /etc/athena
118        * For Solaris, you need a functioning aklog.
120                cd /var/tmp; mkdir aklog; cd aklog
121                synctree -s $src/athena/bin/aklog -d . -a $src/.rconf
122                imake -I$src/packs/build/config -DUseInstalled
123                make # or "make AFSDIR=/wherever" if AFS libs not in /usr/afsws
124                cp aklog /var/tmp/bin
126        * For a few packages (third/perl and some things under packs),
127          /os must point to an image of the operating system.  A
128          symlink from /os to / will usually service if a pristine
129          operating system image is unavailable.
131With these tools, you should be able to set up the build environment
132as documented above.
134Generic build system guidelines
137Here are some desirable properties of a build system for programs or
138libraries, regardless of how it is implemented:
140        * It should use feature tests, not platform tests.
142        * Once the appropriate configuration steps (e.g. running
143          configure or imake) have been done, "make all" should
144          generate all automatically generated files without ever
145          modifying any source files.  (For example, "make all" should
146          not try to regenerate configure from, and a
147          build system should not wait until "make install" time to
148          generate a file which is going to be installed.)
150        * "make install" should install all files appropriate for the
151          target directories without modifying any files in the build
152          tree.  In particular, it should not depend on the "all"
153          target.
155          "make install" should use the install command to install
156          files, not cp or tar or shell redirection.  To install
157          multiple files in the same way, use a single install command
158          rather than a for loop.
160        * "make clean" should clean all files generated by "make all."
161          "make distclean" should also delete files generated by the
162          configuration steps.
164        * "make check" should run self-tests.  It should not assume
165          that the program has been installed, but it should assume
166          that the program has been built.  It should not modify the
167          build tree in any way; in particular, it should not depend
168          on the "all" target.  If there are no self-tests, "make
169          check" should not generate an error.
171        * In a multi-directory source tree, it should be possible to
172          change to a subdirectory of the build tree and run any of
173          the aforementioned make targets with the same results as
174          having descended into that directory from above.  It is okay
175          to assume that previous parts of the build tree have been
176          built, but it is not okay to rely on make command-line
177          parameters passed in from the parent directory.
179Using Autoconf
182For packages in the "athena" hierarchy, we use autoconf.  Autoconf is
183not perfect, but it's the only reasonable package out there for doing
184feature tests as opposed to platform tests.  See the Autoconf info
185pages (available in the default emacs info menu) for information about
186using Autoconf in general.
188When we build the program for the Athena environment, we will use a file (already written; you don't need to write it or point
190to it) which does the following:
192        * Sets the shell variable "athena" to "true".
194        * Sets the appropriate compiler (using the CC environment
195          variable) as well as other compilation tools (yacc, lex) for
196          the platform in question.
198        * Sets the appropriate X include path and library path for use
199          with AC_PATH_X.
201        * Sets the appropriate with_* variables for finding Motif, AFS
202          libraries, Kerberos 4, Kerberos 5, com_err, and ss.  If your
203          package uses any of those libraries, copy the aclocal.m4
204          file from packs/build and use the macros contained within.
206        * Sets prefix to /usr/athena, datadir to '${prefix}/lib',
207          sbindir to '${prefix}/etc', and sysconfdir to '/etc/athena'.
208          You do not need to take these into account in;
209          just put in your
211                prefix=@prefix@
212                exec_prefix=@exec_prefix@
213                datadir=@datadir@
214                sbindir=@sbindir@
215                sysconfdir=@sysconfdir@
217        * Sets shell variables lbindir and lsbindir to /bin/athena and
218          /etc/athena respectively.  If your build system needs to
219          install files in /bin/athena or /etc/athena when built for
220          the Athena environment, use the following in your
222                test -z "$lbindir" && lbindir='${bindir}'
223                test -z "$lsbindir" && lsbindir='${sbindir}'
224                AC_SUBST(lbindir)
225                AC_SUBST(lsbindir)
227          And then in your
229                prefix=@prefix@
230                exec_prefix=@exec_prefix@
231                bindir=@bindir@
232                sbindir=@sbindir@
233                lbindir=@lbindir@
234                lsbindir=@lsbindir@
236The build environment will ensure that the following things are true:
238        * The environment variable ATHENA_SYS is set to the current
239          platform's desired ATHENA_SYS value (e.g. "sun4m_54").
241        * The environment variable HOSTTYPE is set to the current
242          platform name (e.g. "sun").
244        * The environment variable CONFIG_SITE points to the Athena
245 file.
247Using a straight Makefile
250For packages in the "packs" hierarchy, and in some parts of the
251"third" hierarchy where we construct the build system by hand, we use
252a straight Makefile, since feature tests are not necessary for the
253packs hierarchy.
255The build system will ensure that the same environment variables are
256set as for using Autoconf.  In addition, the make variable CC will be
257set to the appropriate compiler for the current platform when the
258"all" target is invoked.  You should be sparing in your use of C
259source code in packages using a straight Makefile, but for small,
260portable C programs it's okay.
262The subdirectories "platform/$HOSTTYPE" or "arch/$ATHENA_SYS" should
263be used for platform or system-dependent components of a package using
264a straight Makefile.
266Start each Makefile with "# $Id: $" and "SHELL=/bin/sh".  The latter
267is to work around a bug in the Irix make where it runs commands under
268${SHELL} rather than /bin/sh.  Also necessary for Irix is using
269"-mkdir -p" instead of "mkdir -p", since mkdir -p under Irix gives an
270error when the directory already exists (in violation of IEEE 1003.2).
Note: See TracBrowser for help on using the repository browser.