| 1 | This document describes guidelines for designing the build system for |
|---|
| 2 | a program or library in the Athena source tree (code we maintain, not |
|---|
| 3 | code we get from thrid parties). |
|---|
| 4 | |
|---|
| 5 | First, here are some desirable properties of a build system for |
|---|
| 6 | programs or libraries. |
|---|
| 7 | |
|---|
| 8 | * It should use feature tests, not platform tests. |
|---|
| 9 | |
|---|
| 10 | * Once the appropriate configuration steps (e.g. running |
|---|
| 11 | configure) have been done, "make all" should generate all |
|---|
| 12 | automatically generated files without ever modifying any |
|---|
| 13 | source files. (For example, "make all" should not try to |
|---|
| 14 | regenerate configure from configure.in, and a build system |
|---|
| 15 | should not wait until "make install" time to generate a file |
|---|
| 16 | which is going to be installed.) |
|---|
| 17 | |
|---|
| 18 | * "make install" should install all files appropriate for the |
|---|
| 19 | target directories without modifying any files in the build |
|---|
| 20 | tree. In particular, it should not depend on the "all" |
|---|
| 21 | target. |
|---|
| 22 | |
|---|
| 23 | "make install" should use the install command to install |
|---|
| 24 | files, not cp or tar or shell redirection. It should avoid |
|---|
| 25 | using for loops to install multiple files unless there is |
|---|
| 26 | some preexisting reason to store that list of files as a |
|---|
| 27 | variable. It should not generate the files it is installing. |
|---|
| 28 | |
|---|
| 29 | * "make clean" should clean all files generated by "make all." |
|---|
| 30 | "make distclean" should also delete files generated by the |
|---|
| 31 | configuration steps. |
|---|
| 32 | |
|---|
| 33 | * "make check" should run self-tests. It should not assume |
|---|
| 34 | that the program has been installed, but it should assume |
|---|
| 35 | that the program has been built. It should not modify the |
|---|
| 36 | build tree in any way; in particular, it should not depend |
|---|
| 37 | on the "all" target. If there are no self-tests, "make |
|---|
| 38 | check" should not generate an error. |
|---|
| 39 | |
|---|
| 40 | * In a multi-directory source tree, it should be possible to |
|---|
| 41 | change to a subdirectory of the build tree and run any of |
|---|
| 42 | the aforementioned make targets with the same results as |
|---|
| 43 | having descended into that directory from above. It is okay |
|---|
| 44 | to assume that previous parts of the build tree have been |
|---|
| 45 | built, but it is not okay to rely on make command-line |
|---|
| 46 | parameters passed in from the parent directory. |
|---|
| 47 | |
|---|
| 48 | Your build system should use Autoconf. Autoconf is not perfect, but |
|---|
| 49 | it's the only reasonable package out there for doing feature tests as |
|---|
| 50 | opposed to platform tests. See the Autoconf info pages (available in |
|---|
| 51 | the default emacs info menu) for information about using Autoconf in |
|---|
| 52 | general. |
|---|
| 53 | |
|---|
| 54 | When we build the program for the Athena environment, we will use a |
|---|
| 55 | config.site file (already written; you don't need to write it or point |
|---|
| 56 | to it) which does the following: |
|---|
| 57 | |
|---|
| 58 | * Sets the shell variable "athena" to "true". |
|---|
| 59 | |
|---|
| 60 | * Sets the appropriate compiler (using the CC environment |
|---|
| 61 | variable) as well as other compilation tools (yacc, lex) for |
|---|
| 62 | the platform in question. |
|---|
| 63 | |
|---|
| 64 | * Sets the appropriate X include path and library path for use |
|---|
| 65 | with AC_PATH_X. |
|---|
| 66 | |
|---|
| 67 | * Sets the appropriate value of with_motif for use with |
|---|
| 68 | AC_WITH_MOTIF, which should be used as follows if you need |
|---|
| 69 | to use the Motif library: |
|---|
| 70 | |
|---|
| 71 | # Near the beginning. |
|---|
| 72 | AC_ARG_WITH(motif, |
|---|
| 73 | [ --with-motif=PREFIX Compile with Motif], |
|---|
| 74 | [motif="$withval"], [motif=no]) |
|---|
| 75 | |
|---|
| 76 | # Where you do checks for header files. |
|---|
| 77 | AC_PATH_XTRA |
|---|
| 78 | |
|---|
| 79 | # Where you do checks for libraries. |
|---|
| 80 | if test "$motif" != "no"; then |
|---|
| 81 | if test "$motif" != "yes"; then |
|---|
| 82 | CPPFLAGS="${CPPFLAGS} -I$motif/include" |
|---|
| 83 | LDFLAGS="$LDFLAGS -L$motif/lib" |
|---|
| 84 | fi |
|---|
| 85 | AC_CHECK_LIB(Xm, XmString, [LIBS="-lXm $LIBS"], |
|---|
| 86 | [AC_ERROR(Motif library not found)]) |
|---|
| 87 | AC_DEFINE(WITH_MOTIF) |
|---|
| 88 | fi |
|---|
| 89 | |
|---|
| 90 | * Sets the prefix to /usr/athena. |
|---|
| 91 | |
|---|
| 92 | * Sets shell variables lbindir and lsbindir to /bin/athena and |
|---|
| 93 | /etc/athena respectively. If your build system needs to |
|---|
| 94 | install files in /bin/athena or /etc/athena when built for |
|---|
| 95 | the Athena environment, use the following in your |
|---|
| 96 | configure.in: |
|---|
| 97 | |
|---|
| 98 | lbindir=${lbindir-'$(exec_prefix)/bin'} |
|---|
| 99 | lsbindir=${lsbindir-'$(exec_prefix)/sbin'} |
|---|
| 100 | AC_SUBST(lbindir) |
|---|
| 101 | AC_SUBST(lsbindir) |
|---|
| 102 | |
|---|
| 103 | The build environment will ensure that the following things are true: |
|---|
| 104 | |
|---|
| 105 | * The environment variable ATHENA_SYS is set to the current |
|---|
| 106 | platform's desired value. |
|---|
| 107 | |
|---|
| 108 | * The environment variable CONFIG_SITE points to the Athena |
|---|
| 109 | config.site file. |
|---|
