source: trunk/doc/build-system @ 11692

Revision 11692, 10.1 KB checked in by danw, 27 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.
Line 
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.
6
7This file contains the following sections:
8
9        Building packages from the source tree
10        Building the tree
11        Generic build system guidelines
12        Using Autoconf
13        Using a straight Makefile
14
15Building packages from the source tree
16--------------------------------------
17
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
25packs/build/packages.
26
27After attaching the correct locker, you can build a package by doing:
28
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/do.sh prepare
34        sh $src/packs/build/do.sh all
35
36"do" accepts the following options:
37
38        -s SRCDIR       Specifies the source hierarchy, if not default
39        -d DESTDIR      Specifies the install hierarchy, if not /srvd
40
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:
44
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)
50
51Building the tree
52-----------------
53
54To build the entire tree by hand, you run packs/build/build.sh from
55the source directory.  Building the tree has the following
56requirements right now:
57
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.
61
62        * The source tree must be findable in the default location
63          (/mit/source for the current sources), or you must tell
64          build.sh where to find the source tree using the -s option.
65
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.
69
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.
74
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).
78
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:
82
83        * Make a temporary directory to put binaries in:
84
85                mkdir /var/tmp/bin
86                set path = ($path /var/tmp/bin)
87
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:
94
95                set src = /afs/dev.mit.edu/source/src-current
96                ./configure
97                make
98                cp synctree /var/tmp/bin
99                rehash
100
101        * You need a functioning kinit.  In the worst case, you may
102          need to do a partial build of third/krb5.
103
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
108
109          The build will eventually bomb out because parts of it
110          depend on Hesiod and libal. This is OK.
111
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
117
118        * For Solaris, you need a functioning aklog.
119
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
125
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.
130
131With these tools, you should be able to set up the build environment
132as documented above.
133
134Generic build system guidelines
135-------------------------------
136
137Here are some desirable properties of a build system for programs or
138libraries, regardless of how it is implemented:
139
140        * It should use feature tests, not platform tests.
141
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 configure.in, and a
147          build system should not wait until "make install" time to
148          generate a file which is going to be installed.)
149
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.
154
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.
159
160        * "make clean" should clean all files generated by "make all."
161          "make distclean" should also delete files generated by the
162          configuration steps.
163
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.
170
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.
178
179Using Autoconf
180--------------
181
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.
187
188When we build the program for the Athena environment, we will use a
189config.site file (already written; you don't need to write it or point
190to it) which does the following:
191
192        * Sets the shell variable "athena" to "true".
193
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.
197
198        * Sets the appropriate X include path and library path for use
199          with AC_PATH_X.
200
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.
205
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 configure.in;
209          just put in your Makefile.in:
210
211                prefix=@prefix@
212                exec_prefix=@exec_prefix@
213                datadir=@datadir@
214                sbindir=@sbindir@
215                sysconfdir=@sysconfdir@
216
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 configure.in:
221
222                test -z "$lbindir" && lbindir='${bindir}'
223                test -z "$lsbindir" && lsbindir='${sbindir}'
224                AC_SUBST(lbindir)
225                AC_SUBST(lsbindir)
226
227          And then in your Makefile.in:
228
229                prefix=@prefix@
230                exec_prefix=@exec_prefix@
231                bindir=@bindir@
232                sbindir=@sbindir@
233                lbindir=@lbindir@
234                lsbindir=@lsbindir@
235
236The build environment will ensure that the following things are true:
237
238        * The environment variable ATHENA_SYS is set to the current
239          platform's desired ATHENA_SYS value (e.g. "sun4m_54").
240
241        * The environment variable HOSTTYPE is set to the current
242          platform name (e.g. "sun").
243
244        * The environment variable CONFIG_SITE points to the Athena
245          config.site file.
246
247Using a straight Makefile
248-------------------------
249
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.
254
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.
261
262The subdirectories "platform/$HOSTTYPE" or "arch/$ATHENA_SYS" should
263be used for platform or system-dependent components of a package using
264a straight Makefile.
265
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.