source: trunk/doc/build-system @ 17299

Revision 17299, 10.1 KB checked in by ghudson, 22 years ago (diff)
Update for new build methodology.
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        cp -r /mit/souce/PACKAGE /tmp/PACKAGE
31        cd /tmp/PACKAGE
32        sh $src/packs/build/do.sh dist
33        sh $src/packs/build/do.sh prepare
34        sh $src/packs/build/do.sh all
35
36If you are building the current sources (or sources from a release
37other than the one running on the Athena machine you're doing the
38build from), they might depend on aspects of the Athena release which
39aren't true of the machine you're using.  If this is true, then you
40may have to construct a build root and build large parts of the
41release.  See the next section on "Build the tree" if that is true.
42
43"do" accepts the following options:
44
45        -s SRCDIR       Specifies the source hierarchy, if not default
46        -d DESTDIR      Specifies the install hierarchy, if not /.srvd
47        -n              Show what build steps would be done, but don't
48                        do them
49        -p              Don't change the path (used by rhlinux SRPMs)
50
51The default location for SRCDIR is the source locker you attached
52(/mit/source, /mit/source-8.1, etc.).  "do" supports the following
53build operations:
54
55        dist            Copy in or create any materials necessary to
56                        make source tree suitable for distribution
57        prepare         Set up the source tree for building
58        clean           Clean any files generated by the "all" operation
59        all             Create automatically generated files
60        check           Perform automated tests, if any
61        install         Install in DESTDIR specified by -d (or default)
62
63Building the tree
64-----------------
65
66To build the entire tree, you must create a build root area on a
67machine to run a chrooted build inside.  This is slow and somewhat
68disruptive of the machine (if you set up AFS to be accessible from the
69root area), so it helps to have a machine set aside for the purpose.
70
71To create a build root area, run
72
73        sh /mit/source/packs/build/makeroot.sh PATH [RELEASE]
74
75where PATH is the place you want the build root to be in and the
76optional RELEASE argument specifies which release you want the build
77to be for (if none is given, the script assumes you want to be
78building /mit/source).
79
80To make AFS accessible in the build root, you must turn AFSADJUST off
81in /etc/athena/rc.conf, modify /usr/vice/etc/cacheinfo to mount AFS in
82PATH/afs, reboot, and then remove /afs and make it a symlink to
83PATH/afs.
84
85If you do not want to make AFS accessible in the build root, you will
86have to make a copy of the source tree in the build root; for Solaris,
87you will also have to make a copy of the sunsoft locker.  There may be
88other dependencies on AFS as well.
89
90After you have set up a build root, run:
91
92        chroot PATH /bin/sh /mit/source/packs/build/build.sh
93
94By default, the builds will be done in PATH/build and the installs
95done into PATH/.srvd.  "build" takes the following options:
96
97        -s SRCDIR       Specifies the source hierarchy, if not default
98        -b BUILDDIR     Specifies the build hierarchy, if not /build
99        -d DESTDIR      Specifies the install hierarchy, if not /.srvd
100        -k              Keep going if a package fails to build
101        -n              Only display a list of packages to be built
102        -l              Log build output to a file in BUILDDIR/logs
103
104On Linux, we use a different build script which builds RPMs instead of
105doing a traditional build.  To use it, run:
106
107        chroot PATH /bin/sh /mit/source/packs/build/rpm/build-all
108
109By default, the builds will be done in /build/BUILD and the resulting
110RPMs will wind up in /build/SRPMS and /build/RPMS.  "build-all" takes
111the same options as "build" except that there is no -b option; the -d
112option specifies the path for both the build and destination area.
113
114Building the whole tree has the following requirements right now:
115
116        * The system passwd file must have "pop" and "discuss" users.
117          Athena machines should typically have these lines in them
118          already, but you may have to add them on non-Athena systems.
119
120        * You must have write access to the destination hierarchy, and
121          be able to chown files and make setuid root files in that
122          tree.
123
124        * On Solaris, you need system:authuser access to the Athena
125          cell in order to use the compiler from the sunsoft locker.
126
127Generic build system guidelines
128-------------------------------
129
130Here are some desirable properties of a build system for programs or
131libraries, regardless of how it is implemented:
132
133        * It should use feature tests, not platform tests.
134
135        * Once the appropriate configuration steps (e.g. running
136          configure or imake) have been done, "make all" should
137          generate all automatically generated files without ever
138          modifying any source files.  (For example, "make all" should
139          not try to regenerate configure from configure.in, and a
140          build system should not wait until "make install" time to
141          generate a file which is going to be installed.)
142
143        * "make install" should install all files appropriate for the
144          target directories without modifying any files in the build
145          tree.  In particular, it should not depend on the "all"
146          target.
147
148          "make install" should use the install command to install
149          files, not cp or tar or shell redirection.  To install
150          multiple files in the same way, use a single install command
151          rather than a for loop.
152
153        * "make clean" should clean all files generated by "make all."
154          "make distclean" should also delete files generated by the
155          configuration steps.
156
157        * "make check" should run self-tests.  It should not assume
158          that the program has been installed, but it should assume
159          that the program has been built.  It should not modify the
160          build tree in any way; in particular, it should not depend
161          on the "all" target.  If there are no self-tests, "make
162          check" should not generate an error.
163
164        * In a multi-directory source tree, it should be possible to
165          change to a subdirectory of the build tree and run any of
166          the aforementioned make targets with the same results as
167          having descended into that directory from above.  It is okay
168          to assume that previous parts of the build tree have been
169          built, but it is not okay to rely on make command-line
170          parameters passed in from the parent directory.
171
172Using Autoconf
173--------------
174
175For packages in the "athena" hierarchy, we use autoconf.  Autoconf is
176not perfect, but it's the only reasonable package out there for doing
177feature tests as opposed to platform tests.  See the Autoconf info
178pages (available in the default emacs info menu) for information about
179using Autoconf in general.
180
181When we build the program for the Athena environment, we will use a
182config.site file (already written; you don't need to write it or point
183to it) which does the following:
184
185        * Sets the shell variable "athena" to "true".
186
187        * Sets the appropriate compiler (using the CC environment
188          variable) as well as other compilation tools (yacc, lex) for
189          the platform in question.
190
191        * Sets the appropriate X include path and library path for use
192          with AC_PATH_X.
193
194        * Sets the appropriate with_* variables for finding Motif, AFS
195          libraries, Kerberos 4, Kerberos 5, com_err, and ss.  If your
196          package uses any of those libraries, copy the aclocal.m4
197          file from packs/build and use the macros contained within.
198
199        * Sets prefix to /usr/athena, datadir to '${prefix}/lib',
200          sbindir to '${prefix}/etc', and sysconfdir to '/etc/athena'.
201          You do not need to take these into account in configure.in;
202          just put in your Makefile.in:
203
204                prefix=@prefix@
205                exec_prefix=@exec_prefix@
206                datadir=@datadir@
207                sbindir=@sbindir@
208                sysconfdir=@sysconfdir@
209
210        * Sets shell variables lbindir and lsbindir to /bin/athena and
211          /etc/athena respectively.  If your build system needs to
212          install files in /bin/athena or /etc/athena when built for
213          the Athena environment, use the following in your configure.in:
214
215                test -z "$lbindir" && lbindir='${bindir}'
216                test -z "$lsbindir" && lsbindir='${sbindir}'
217                AC_SUBST(lbindir)
218                AC_SUBST(lsbindir)
219
220          And then in your Makefile.in:
221
222                prefix=@prefix@
223                exec_prefix=@exec_prefix@
224                bindir=@bindir@
225                sbindir=@sbindir@
226                lbindir=@lbindir@
227                lsbindir=@lsbindir@
228
229The build environment will ensure that the following things are true:
230
231        * The environment variable ATHENA_SYS is set to the current
232          platform's desired ATHENA_SYS value (e.g. "sun4m_54").
233
234        * The environment variable HOSTTYPE is set to the current
235          platform name (e.g. "sun").
236
237        * The environment variable CONFIG_SITE points to the Athena
238          config.site file.
239
240Using a straight Makefile
241-------------------------
242
243For packages in the "packs" hierarchy, and in some parts of the
244"third" hierarchy where we construct the build system by hand, we use
245a straight Makefile, since feature tests are not necessary for the
246packs hierarchy.
247
248The build system will ensure that the same environment variables are
249set as for using Autoconf.  In addition, the make variable CC will be
250set to the appropriate compiler for the current platform when the
251"all" target is invoked.  You should be sparing in your use of C
252source code in packages using a straight Makefile, but for small,
253portable C programs it's okay.
254
255The subdirectories "platform/$HOSTTYPE" or "arch/$ATHENA_SYS" should
256be used for platform or system-dependent components of a package using
257a straight Makefile.
258
259Start each Makefile with "# $Id: $" and "SHELL=/bin/sh".  The latter
260is to work around a bug in the Irix make where it runs commands under
261${SHELL} rather than /bin/sh.
Note: See TracBrowser for help on using the repository browser.