boinc/doc/build_system.php

<?
require_once("docutil.php");
page_head("BOINC: Build system");
echo "

    <h2>Details of BOINC's new automake/autoconf build system</h2>
    <p>
      The BOINC build system uses
      <a href=http://www.gnu.org/software/autoconf/>autoconf</a> 2.57 and <a
      href=http://www.gnu.org/software/automake/automake.html>automake</a>
      1.7.
    </p>

    <p>
      Much of these instructions are generic to automake but are provided here
      for convenience.
    </p>

    <h3>Notes</h3>
    <ul>
      <li><b>Maintainer mode</b>
        <p>
          The BOINC automake files use the <i>maintainer-mode</i> setting
          which by default disables automatic maintainer dependencies. If you
          modify makefiles or <code>configure.ac</code> you should enable them
          by adding the <code>--enable-maintainer-mode</code> option
          to <code>configure</code>:
          <pre>
            ./configure --enable-maintainer-mode
          </pre>

          You should modify only the <code>Makefile.am</code> files, which
          generate the <code>Makefile.in</code> files (and
          the <code>configure</code> script produced by autoconf will generate
          the <code>Makefile</code>s from those). If you don't have automake
          (or not a new enough version), the build system will warn you and
          continue without regenerating <code>Makefile.in</code>. (When
          checking out from CVS or extracting from a source distribution,
          sometimes <code>make</code> will think that
          the <code>makefile.in</code> files need to be regenerated because
          they aren't newer than the <code>Makefile.am</code> files.)
        </p>
      <li><b>Layout</b>
        <p>
          The top-level <code>Makefile.am</code> contains the
          <code>SUBDIRS=</code> line which sets up directory recursion, and
          the rules for creating source distributions.
        </p>
        <p>
          Each subdirectory's <code>Makefile.am</code> contains the rules for
          making the binaries and libraries in that directory and any extra
          files to distribute.
        </p>
        <p>
          Usually you will want to run <code>make</code> from the toplevel
          (the directory containing the file <code>configure</code>), but
          sometimes it is useful to run <code>make</code> and <code>make
            check</code> in certain subdirectories.
        </p>
      </li>
      <li><b>Dependencies</b>
        <p>
          Automake takes care of all dependency issues.
          Calling <code>make</code> will automagically regenerate the
          dependencies themselves as necessary.  This includes source
          dependencies (on header files) as well as Makefile dependencies
          (<code>Makefile</code> depends on <code>Makefile.in</code> which
          depends on <code>Makefile.am</code>).
        </p>
      </li>
      <li><b>Expanding</b>
        <p>
          If you create a new directory with another <code>Makefile.am</code>,
          you should <b>A)</b> make sure the directory is referenced by
          a <code>SUBDIRS=</code> line from its
          parent <code>Makefile.am</code> and <b>B)</b> add it to the
          AC_CONFIG_FILES directive in <code>configure.ac</code>.
        </p>
      </li>
    </ul>

    <h3>Tasks</h3>
    <ul>
      <li><b>Compiling</b>
        <p>
          To compile, use the usual
          <pre>
            ./configure
            make
          </pre>
        </p>
        <p>
          Example using multiple build directories under a single source
          directory (assuming the same directory is mounted
          on <code>milkyway</code> and <code>shaggy</code>):
          <pre>
            milkyway$ mkdir build
            milkyway$ mkdir build/solaris2.7
            milkyway$ cd build/solaris2.7
            milkyway$ ../../configure
            milkyway$ make

            milkyway$ mkdir build/solaris2.7-gcc3
            milkyway$ cd build/solaris2.7-gcc3
            milkyway$ ../../configure CC=/opt/misc/gcc-3.0.4/bin/gcc CXX=/opt/misc/gcc-3.0.4/bin/g++
            milkyway$ make

            shaggy$ mkdir build/linux
            shaggy$ cd build/linux
            shaggy$ ../../configure
            shaggy$ make
          </pre>
        </p>
      </li>
      <li><b>Testing</b>
        <p>
          To test the code:
          <pre>
            make check
          </pre> This runs the python tests in the <code>test/</code>
          directory; requires Python2.2, MySQLdb.  Old PHP-based tests in
          <code>test/</code>are also available to be run individually.
        </p>
      </li>
      <li><b>Version number</b>
        <p>
          The version number is set in the line
          <pre>
            AC_INIT(BOINC, 1.03)
          </pre>
          in <code>configure.ac</code>.  If you change this, run
          <code>make</code> and it will rebuild any files necessary to
          propagate the version number into source files and scripts (if
          maintainer-mode is on).  This is the only location the version
          number is set (in unix); all other uses of it come from here (no
          environment variables used).
        </p>
      </li>
      <li><b>Archiving</b>
        <p>
          To make source distributions:
          <pre>
            make dist
          </pre>
        </p>

        <p>
          This will make <code>.tar.gz</code>, <code>.tar.bz2</code>,
          and <code>.zip</code> files.  You can also make only the individual
          ones using the make
          targets <code>dist-bzip2</code>, <code>dist-gzip</code>, <code>dist-zip</code>.
          The source distributions contain everything necessary to build and
          run the server, and also remake distributions.
        </p>

        <p>
          (There used to be a separate client distribution requiring
           complicated rules for picking subdirectories to compile and
           distribute, but it has been obsoleted because few people will
           download the distribution to build only the client.)
        </p>

        <p>
          There is also a very handy target:
          <pre>
            make distcheck
          </pre>
          In a temporary directory, <code>make</code> will extract the
          distribution tarball, <code>make all</code>, <code>make
          check</code>, <code>make install</code> (to another temporary
          directory). This simulates what the developer end-user can do with
          the tarball.
        </p>
      </li>
      <li><b>Cleaning</b>
        <p>
          To clean out built object files:
          <pre>
            make clean
          </pre>
          To clean out built object files and generated files such
          as <code>Makefile.in</code>:
          <pre>
            make distclean
          </pre>
        </p>
      </li>
    </ul>
";
page_tail();
?>