HACKING

# -*-text-*-

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

If you are already familiar with builds based on the GNU Autotools, you should
be able to build and test the project using just the instructions in the
INSTALL file. Please notify the author if you run into problems (see the BUGS
file for how to report problems).

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

    automake 1.15
    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.15
    Copyright (C) 2014 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 (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.


Misc Notes
----------

You'll notice that there is a 'configure' script in the root directory of the
source tree, 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. It is desired that we be able to track differences in these files
accross releases.

Though other versions of the autotools may work, only those files generated by
the versions "officially supported" will be committed. Please do not ask the
author for help using different versions of the autotools.

Also, please omit from any submitted patches hunks from files generated by the
autotools.


Pre-configuration: The 'bootstrap' script

    $ pwd
    .../screen-wrappers
    $ ./bootstrap --force

The 'bootstrap' script is simply a wrapper around the 'autoreconf' program
provided by the GNU Autotools (Automake). The 'autoreconf' program invokes the
various GNU Autotools programs (aclocal, automake, etc) in the correct order,
and the '--force' option to out 'bootstrap' script is is simply passed through
autoreconf: it requests that autoreconf presume that all timestamps are
invalid. This has the effect of regenerating the autogenerated files with
meaningful timestamps (is is required for any 'make' based build system to
work correctly).

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' in your git working
directory. If you want to install ("for real") your newly hacked version of
the 'screen-wrappers' project, then create a distribution tarball and install
using that:

    $ make distcheck
    $ ls | grep tar
    screen-wrappers-0.2.2.tar.gz

Note: It is not acceptable to simply invoke:

    $ make dist

for a release of the 'screen-wrappers' project. 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.1, the version number specified in 'configure.ac' should be:

    0.1.1-snapshot

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

The GNU Autotools generated files should be checked into git (as noted above),
and the release should be tagged. After the 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.2-snapshot