[9154] | 1 | This document explains how to build packages from the Athena source |
---|
| 2 | tree, and then describes guidelines for designing the build system for |
---|
| 3 | code we maintain in the Athena source tree. A discussion of building |
---|
| 4 | packages we get from third parties is in the file "third-party" in |
---|
| 5 | this directory. |
---|
[8769] | 6 | |
---|
[9154] | 7 | This file contains the following sections: |
---|
[8769] | 8 | |
---|
[9991] | 9 | Building packages from the source tree |
---|
[10293] | 10 | Building the tree |
---|
[9154] | 11 | Generic build system guidelines |
---|
| 12 | Using Autoconf |
---|
| 13 | Using a straight Makefile |
---|
| 14 | |
---|
| 15 | Building packages from the source tree |
---|
| 16 | -------------------------------------- |
---|
| 17 | |
---|
[9992] | 18 | To build a package from the Athena source tree, you should generally |
---|
| 19 | first attach the source tree that you want. You can either attach a |
---|
| 20 | locker like "source-8.0" or "source-8.1" to get the sources for a |
---|
| 21 | particular release, or you can attach "source" to get the current |
---|
[10293] | 22 | development sources. Releases prior to 8.1 will not build using the |
---|
| 23 | procedure below. Note that you can only build whole packages, not |
---|
| 24 | arbitrary subdirectories; package names are listed in |
---|
| 25 | packs/build/packages. |
---|
[9154] | 26 | |
---|
[10293] | 27 | After attaching the correct locker, you can build a package by doing: |
---|
[9992] | 28 | |
---|
[10293] | 29 | set src = /mit/source # or /mit/source-8.1, etc. |
---|
[18936] | 30 | cp -r /mit/source/PACKAGE /tmp/PACKAGE |
---|
[17299] | 31 | cd /tmp/PACKAGE |
---|
[14489] | 32 | sh $src/packs/build/do.sh dist |
---|
[9992] | 33 | sh $src/packs/build/do.sh prepare |
---|
| 34 | sh $src/packs/build/do.sh all |
---|
[9154] | 35 | |
---|
[17299] | 36 | If you are building the current sources (or sources from a release |
---|
| 37 | other than the one running on the Athena machine you're doing the |
---|
| 38 | build from), they might depend on aspects of the Athena release which |
---|
| 39 | aren't true of the machine you're using. If this is true, then you |
---|
| 40 | may have to construct a build root and build large parts of the |
---|
| 41 | release. See the next section on "Build the tree" if that is true. |
---|
[13738] | 42 | |
---|
[17299] | 43 | "do" accepts the following options: |
---|
[13738] | 44 | |
---|
[10293] | 45 | -s SRCDIR Specifies the source hierarchy, if not default |
---|
[17299] | 46 | -d DESTDIR Specifies the install hierarchy, if not /.srvd |
---|
[13470] | 47 | -n Show what build steps would be done, but don't |
---|
[13737] | 48 | do them |
---|
[17299] | 49 | -p Don't change the path (used by rhlinux SRPMs) |
---|
[9992] | 50 | |
---|
[10293] | 51 | The default location for SRCDIR is the source locker you attached |
---|
[13622] | 52 | (/mit/source, /mit/source-8.1, etc.). "do" supports the following |
---|
| 53 | build operations: |
---|
[9154] | 54 | |
---|
[14489] | 55 | dist Copy in or create any materials necessary to |
---|
| 56 | make source tree suitable for distribution |
---|
[9372] | 57 | prepare Set up the source tree for building |
---|
[9154] | 58 | clean Clean any files generated by the "all" operation |
---|
| 59 | all Create automatically generated files |
---|
| 60 | check Perform automated tests, if any |
---|
[13622] | 61 | install Install in DESTDIR specified by -d (or default) |
---|
[9154] | 62 | |
---|
[10293] | 63 | Building the tree |
---|
| 64 | ----------------- |
---|
| 65 | |
---|
[17299] | 66 | To build the entire tree, you must create a build root area on a |
---|
| 67 | machine to run a chrooted build inside. This is slow and somewhat |
---|
| 68 | disruptive of the machine (if you set up AFS to be accessible from the |
---|
| 69 | root area), so it helps to have a machine set aside for the purpose. |
---|
[10293] | 70 | |
---|
[17299] | 71 | To create a build root area, run |
---|
[13472] | 72 | |
---|
[17299] | 73 | sh /mit/source/packs/build/makeroot.sh PATH [RELEASE] |
---|
[13472] | 74 | |
---|
[17299] | 75 | where PATH is the place you want the build root to be in and the |
---|
| 76 | optional RELEASE argument specifies which release you want the build |
---|
| 77 | to be for (if none is given, the script assumes you want to be |
---|
| 78 | building /mit/source). |
---|
| 79 | |
---|
| 80 | To make AFS accessible in the build root, you must turn AFSADJUST off |
---|
| 81 | in /etc/athena/rc.conf, modify /usr/vice/etc/cacheinfo to mount AFS in |
---|
| 82 | PATH/afs, reboot, and then remove /afs and make it a symlink to |
---|
| 83 | PATH/afs. |
---|
| 84 | |
---|
| 85 | If you do not want to make AFS accessible in the build root, you will |
---|
| 86 | have to make a copy of the source tree in the build root; for Solaris, |
---|
| 87 | you will also have to make a copy of the sunsoft locker. There may be |
---|
| 88 | other dependencies on AFS as well. |
---|
| 89 | |
---|
| 90 | After you have set up a build root, run: |
---|
| 91 | |
---|
| 92 | chroot PATH /bin/sh /mit/source/packs/build/build.sh |
---|
| 93 | |
---|
| 94 | By default, the builds will be done in PATH/build and the installs |
---|
| 95 | done into PATH/.srvd. "build" takes the following options: |
---|
| 96 | |
---|
[13472] | 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 |
---|
[17299] | 102 | -l Log build output to a file in BUILDDIR/logs |
---|
[13472] | 103 | |
---|
[17299] | 104 | On Linux, we use a different build script which builds RPMs instead of |
---|
| 105 | doing a traditional build. To use it, run: |
---|
[13472] | 106 | |
---|
[17299] | 107 | chroot PATH /bin/sh /mit/source/packs/build/rpm/build-all |
---|
| 108 | |
---|
| 109 | By default, the builds will be done in /build/BUILD and the resulting |
---|
| 110 | RPMs will wind up in /build/SRPMS and /build/RPMS. "build-all" takes |
---|
| 111 | the same options as "build" except that there is no -b option; the -d |
---|
| 112 | option specifies the path for both the build and destination area. |
---|
| 113 | |
---|
[15564] | 114 | Building the whole tree has the following requirements right now: |
---|
[13472] | 115 | |
---|
[10941] | 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 | |
---|
[13472] | 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. |
---|
[10293] | 123 | |
---|
| 124 | * On Solaris, you need system:authuser access to the Athena |
---|
[17299] | 125 | cell in order to use the compiler from the sunsoft locker. |
---|
[10293] | 126 | |
---|
[9154] | 127 | Generic build system guidelines |
---|
| 128 | ------------------------------- |
---|
| 129 | |
---|
| 130 | Here are some desirable properties of a build system for programs or |
---|
| 131 | libraries, regardless of how it is implemented: |
---|
| 132 | |
---|
[8769] | 133 | * It should use feature tests, not platform tests. |
---|
| 134 | |
---|
| 135 | * Once the appropriate configuration steps (e.g. running |
---|
[8936] | 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.) |
---|
[8769] | 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 |
---|
[9296] | 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. |
---|
[8769] | 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 | |
---|
[8936] | 172 | Using Autoconf |
---|
| 173 | -------------- |
---|
| 174 | |
---|
| 175 | For packages in the "athena" hierarchy, we use autoconf. Autoconf is |
---|
| 176 | not perfect, but it's the only reasonable package out there for doing |
---|
| 177 | feature tests as opposed to platform tests. See the Autoconf info |
---|
| 178 | pages (available in the default emacs info menu) for information about |
---|
| 179 | using Autoconf in general. |
---|
| 180 | |
---|
[8769] | 181 | When we build the program for the Athena environment, we will use a |
---|
| 182 | config.site file (already written; you don't need to write it or point |
---|
| 183 | to 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 | |
---|
[10408] | 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. |
---|
[8769] | 198 | |
---|
[9318] | 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: |
---|
[9051] | 203 | |
---|
| 204 | prefix=@prefix@ |
---|
[9108] | 205 | exec_prefix=@exec_prefix@ |
---|
[9051] | 206 | datadir=@datadir@ |
---|
| 207 | sbindir=@sbindir@ |
---|
[9318] | 208 | sysconfdir=@sysconfdir@ |
---|
[9051] | 209 | |
---|
[9318] | 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 | |
---|
[9296] | 215 | test -z "$lbindir" && lbindir='${bindir}' |
---|
| 216 | test -z "$lsbindir" && lsbindir='${sbindir}' |
---|
[8769] | 217 | AC_SUBST(lbindir) |
---|
| 218 | AC_SUBST(lsbindir) |
---|
| 219 | |
---|
[9051] | 220 | And then in your Makefile.in: |
---|
| 221 | |
---|
| 222 | prefix=@prefix@ |
---|
[9108] | 223 | exec_prefix=@exec_prefix@ |
---|
| 224 | bindir=@bindir@ |
---|
| 225 | sbindir=@sbindir@ |
---|
[9051] | 226 | lbindir=@lbindir@ |
---|
| 227 | lsbindir=@lsbindir@ |
---|
| 228 | |
---|
[8769] | 229 | The build environment will ensure that the following things are true: |
---|
| 230 | |
---|
| 231 | * The environment variable ATHENA_SYS is set to the current |
---|
[8785] | 232 | platform's desired ATHENA_SYS value (e.g. "sun4m_54"). |
---|
[8769] | 233 | |
---|
[8785] | 234 | * The environment variable HOSTTYPE is set to the current |
---|
| 235 | platform name (e.g. "sun"). |
---|
| 236 | |
---|
[8769] | 237 | * The environment variable CONFIG_SITE points to the Athena |
---|
| 238 | config.site file. |
---|
[8936] | 239 | |
---|
| 240 | Using a straight Makefile |
---|
| 241 | ------------------------- |
---|
| 242 | |
---|
| 243 | For packages in the "packs" hierarchy, and in some parts of the |
---|
| 244 | "third" hierarchy where we construct the build system by hand, we use |
---|
| 245 | a straight Makefile, since feature tests are not necessary for the |
---|
| 246 | packs hierarchy. |
---|
| 247 | |
---|
| 248 | The build system will ensure that the same environment variables are |
---|
[9154] | 249 | set as for using Autoconf. In addition, the make variable CC will be |
---|
| 250 | set to the appropriate compiler for the current platform when the |
---|
| 251 | "all" target is invoked. You should be sparing in your use of C |
---|
| 252 | source code in packages using a straight Makefile, but for small, |
---|
| 253 | portable C programs it's okay. |
---|
[8936] | 254 | |
---|
| 255 | The subdirectories "platform/$HOSTTYPE" or "arch/$ATHENA_SYS" should |
---|
| 256 | be used for platform or system-dependent components of a package using |
---|
| 257 | a straight Makefile. |
---|
| 258 | |
---|
[9052] | 259 | Start each Makefile with "# $Id: $" and "SHELL=/bin/sh". The latter |
---|
[8936] | 260 | is to work around a bug in the Irix make where it runs commands under |
---|
[12276] | 261 | ${SHELL} rather than /bin/sh. |
---|