new nALFS Hackers Guide

Kevin P. Fleming kpfleming at
Tue Oct 21 11:07:37 PDT 2003

Random stuff, in no particular order, do with them as you will... 
(headers in asterisks)

**CVS usage**

The CVS repository copy of nALFS does not include an executable 
configure script nor a Makefile. This is by design, as there is a 
script to create them, which ensures that the Makefile content will 
always be up to date with the source tree contents and not require 
manual editing.

nALFS has been configured to use the GNU autotools suite for its build 
process. The build system was created using autoconf-2.57, 
automake-1.7.7 and libtool-1.5. If you use older versions than those, 
you may experience warnings and/or outright failures (automake-1.6 is 
known to be unable to handle the nALFS

When you checkout the nALFS source tree, you will need to execute:

sh ./bootstrap

in the nALFS directory itself. This should result output similar to 
the following:

$ sh ./bootstrap
You should update your `aclocal.m4' by running aclocal.
Putting files in AC_CONFIG_AUX_DIR, `gnubuild'. installing `gnubuild/install-sh' installing `gnubuild/mkinstalldirs' installing `gnubuild/missing' installing `gnubuild/compile' installing `gnubuild/depcomp'
patching file
Hunk #1 succeeded at 160 with fuzz 2 (offset -78 lines).
Hunk #2 succeeded at 269 with fuzz 1.
Hunk #3 succeeded at 4483 (offset -1172 lines).

This output comes from the autoreconf tool, which is part of autoconf, 
that automatically runs libtoolize, autoheader, aclocal and other 
parts of the autotools suite. The warning about "update your 
'aclocal.m4'" can be ignored, as aclocal is already executed later by 
autoreconf. The patch offset and/or fuzz messages about are 
caused by the bootstrap script applying a patch created against 
libtool-1.5; if your libtool version is different, the patch should 
still work correctly, but you may see messages like this from the 
patch command. In the worst case, the patch fails to apply, the nALFS 
build will still be functional, but libtool will generate more output 
messages than necessary.

Once bootstrap has been run, you can execute "./configure" like any 
other GNU autoconf-based package to configure nALFS for your system.

**Editing source files**

The nALFS build system, because it uses automake, has full dependency 
tracking on all files used to build the binaries. This will reduce 
your rebuilding time as you edit header files and source files, as the 
make system will know exactly what must be rebuilt.

In addition, if you are going to make changes to, you 
should add the "--enable-maintainer-mode" parameter to the configure 
command. With this done, each time you edit, the Makefile 
will automatically re-run configure to make your changes take effect. 
Be warned, though, that if you manually edit, you must 
modify the bootstrap script to incorporate your changes, because is not stored in the CVS repository.

**Making a distribution tarball**

When you are ready to produce a tarball for distribution, there are a 
few steps to follow:

1) Edit, and modify the line starting with AC_INIT 
(should be the first line) to reflect the version number that you want 
the distribution to be given. Commit this change to the CVS 
repository, and create a CVS tag to match the version number.
2) Run a normal ./configure process for your system.
3) Run "make dist". This will produce both a .tar.gz and a .tar.bz2 
file in the current directory containing everything that should be 
needed to build nALFS on an end-user's system. Note that this tarball 
will be created using the autoconf, automake and libtool versions _on 
your development system_, so please make sure they are current 
releases before creating a tarball for public consumption.
4) Run "make distcheck". If your system requires any special 
parameters to be given to configure for it to complete (like 
"--with-libxml2", for example), then you can use 'make 
DISTCHECK_CONFIGURE_FLAGS="..." distcheck' to supply those parameters. 
The distcheck process will actually unpack the tarball into a 
temporary directory, and run a complete 
configure/make/install/uninstall process on it to ensure that no build 
errors occur. This step should be considered to be mandatory before 
releasing your tarball to the general public.

More information about the alfs-discuss mailing list