HACKING

# -*-text-*-

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

This file contains the following sections:

    * Building from a Source Tarball
    * Building from Git

Building from a Source Tarball
==============================

If you simply want to build the 'ads-clock' 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.

FIXME: document where to get a source distribution tarball

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

    $ cd /usr/local/src
    .../src$ wget -nd http://some.host.example.com/some/path/ads-clock-0.1.0.tar.gz
    .../src$ ls | grep ads-clock
    ads-clock-0.1.0.tar.gz
    .../src$
    .../src$ gzip -dc ads-clock-0.1.0.gz | tar xf -
    .../src$ cd ads-clock-0.1.0
    .../src/ads-clock-0.1.0$ ./configure --prefix=/path/to/whatever
    .../src/ads-clock-0.1.0$ make
    .../src/ads-clock-0.1.0$ make check
    .../src/ads-clock-0.1.0$ make install



Building from Git
=================

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

    automake 1.14.1
    autoconf 2.69

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

    $ automake --version
    automake (GNU automake) 1.14.1
    Copyright (C) 2013 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>.


    $ autoconf --version
    autoconf (GNU Autoconf) 2.69
    Copyright (C) 2012 Free Software Foundation, Inc.
    License GPLv3+/Autoconf: GNU GPL version 3 or later
    <http://gnu.org/licenses/gpl.html>, <http://gnu.org/licenses/exceptions.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.


Check the ads-clock source out of git from the project's public GitHub
repository:

    $ git clone https://github.com/salewski/ads-clock.git
    $ cd ads-clock

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 cloning the git repository.

Upon a fresh clone, you should be able to just run 'configure'. However, if
you find that your working directory somehow has timestamps out of sync, then
you can force a regeneration of all of the GNU Autotools-generated files.

Pre-configuration: The 'bootstrap' script

    $ pwd
    .../ads-clock
    $ ./bootstrap

The 'bootstrap' script is a thin wrapper around the 'autoreconf' program
(supplied by Autoconf), which itself 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 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 'ads-clock' project, then create a distribution tarball and install using
that:

    $ make distcheck
    $ ls | grep ads-clock
    ads-clock-0.1.0.tar.gz

Note: It is not acceptable to simply invoke:

    $ make dist

for a release of the 'ads-clock'. If the build does not pass the 'distcheck'
verifications, the package is considered 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 'boostrap' 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 0.1.2, the version number specified in 'configure.ac' should be:

    0.1.2-snapshot

This eliminates the possibility of producing artifacts labeled just '0.1.2'
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.

    0.1.2

The GNU Autotools generated files should be checked into git, 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.

    0.1.3-snapshot