HACKING

%# -*-text-*-

The 'bedrock' project is built using the GNU Autotools (Automake,
Autoconf, etc.)

This file contains the following sections:

    * Building from a Source Tarball
    * Building from local git repository

Building from a Source Tarball
==============================

If you simply want to build the 'bedrock' project (as opposed to hacking on
the codebase), the easiest thing to do is obtain a source distribution tarball
of the version of the project you wish to build.

You can download a current snapshot of the source tree from GitHub.

  https://github.com/rlauer6/openbedrock.git

If all you really want to do is hack on Bedrock and don't feel up to
the challenge of joining the Bedrock development community, download
the zip file and hack on it.

  https://github.com/rlauer6/openbedrock/archive/master.zip

This relieves you of having access to specific versions of the GNU
Autotools, etc.

    $ cd /usr/local/src
    $ wget -O openbedrock.zip -nd https://github.com/rlauer6/openbedrock/archive/master.zip
    $ unzip openbedrock.zip
    $ cd openbedrock-master
    $ ./configure 
    $ make
    $ sudo install


Building from a  local git repository
=====================================

All developers working on the 'bedrock' project need to be using the same
versions of the Autotools programs in the toolchain. Currently (as of
2013-12), those versions are:

    automake 1.11.1
    autoconf 2.63

You can determine the versions in your PATH by invoking the respective
tools with the '--version' option:

    $ autoconf --version
    autoconf (GNU Autoconf) 2.63
    Copyright (C) 2008 Free Software Foundation, Inc.
    License GPLv2+: GNU GPL version 2 or later
    <http://gnu.org/licenses/old-licenses/gpl-2.0.html>
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
    
    Written by David J. MacKenzie and Akim Demaille.

    $ automake --vesion
    automake (GNU automake) 1.11.1
    Copyright (C) 2009 Free Software Foundation, Inc.
    License GPLv2+: GNU GPL version 2 or later
    <http://gnu.org/licenses/gpl-2.0.html>
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
    
    Written by Tom Tromey <tromey@redhat.com>
           and Alexandre Duret-Lutz <adl@gnu.org>.

Clone the project from GitHub:

    $ git clone https://github.com/rlauer6/openbedrock.git openbedrock
    $ cd openbedrock

You'll notice that there is a 'configure' script in the root directory, as
well as 'Makefile.in' files scattered throughout the tree. These files are all
generated by the GNU Autotools, and are checked into git to allow (in the
future) developers to configure the project upon git checkout.

Upon a fresh checkout, you should be able to just run 'configure'. However, if
you have an already checked-out source tree that you run some variation of
'git pull' on, then simply rerunning 'configure' will not work because CVS
will have modified the timestamps of updated files to have the current time.

In order to allow developers to configure the project directly after a
git pull (without requiring access to the GNU Autotools), we need a script to
touch(1) various files in the correct order (that is, in the same order that
the GNU Autotools generated them in the first place). As of 2013-12-08, such a
script does not exist for the 'bedrock' project, so developers must have the
correct versions of the GNU Autotools available.

Pre-configuration: The 'bootstrap' script

    $ pwd
    ../openbedrock
    $ ./bootstrap

The 'bootstrap' script simply invokes the GNU Autotools in the correct order
in such a way that it assumes all timestamps are invalid. This has the effect
of regenerating the autogenerated files with meaningful timestamps. After
doing a 'git pull', if the 'bootstrap' script is not run prior to running
'configure', you'll get strange, broken behavior from the 'configure' process
due to the timestamp issue mentioned above.

After you've run the 'bootstrap' script, you are ready to configure the
project for your host:

    $ ./configure --prefix=/path/to/wherever
    $ make
    $ make check

You probably do not want to run 'make install' from your git working
directory. If you want to install ("for real") your newly hacked version of
the 'bedrock' project, then create a distribution tarball and install using
that:

    $ make distcheck
    $ ls | grep openbedrock
    bedrock-2.3.4.tar.gz

Note: It is not acceptable to simply invoke:

    $ make dist

for a release of the 'bedrock' package. If the build does not pass the 'distcheck'
verifications, the package is broken.

For new releases, the version of the project must be changed in the
'configure.ac' file, and the 'bootstrap' script re-run to regenerate the GNU
Autotools generated files (such as the 'configure' program and all
'Makefile.in' files).

After a release is made, the version number should be incremented with the
constant '-snapshot' appended to it. Again, the 'bootstrap' script should be
re-run to regenerate the GNU Autotools generated files.

For example, during the development of the code that will be released as
version 2.3.5, the version number specified in 'configure.ac' should be:

    2.3.5-snapshot

This eliminates the possibility of producing artifacts labeled just '2.3.5'
which are not the final release.

When it comes time to do the release, the version number in 'configure.ac'
should be changed to remove the '-snapshot' suffix, and the 'bootstrap'
script rerun.

    2.3.5

The GNU Autotools generated files should be checked into the git
repository, and the release should be tagged. After the final release
is tagged, the version number in 'configure.ac' should be bumped up
for the next development cycle, and the 'bootstrap' script re-run.

    2.3.6-snapshot