
Apache C++ Standard Library - stdcxx

Introduction
============

This experimental branch of the 4.2.0 release adds support for the GNU
"Autotools" suite consisting primarily of GNU Autoconf, Automake, and
Libtool.   It preserves the layout and structure of the 4.2.0 release.
This new infrastructure is intended to be distributed as an alternative
to the existing Makefile-based infrastructure in the 4.3.0 release.

First, a word of warning.  The current version is incomplete and quite
likely broken.  Hack at your own risk.

To "bootstrap" the resulting distribution, run the following commands
in the top-level source directory:

	$ libtoolize -c
	$ aclocal -I etc/config/macros
	$ autoheader
	$ automake -ac
	$ autoconf

To hack on files in this branch, generate a config.h header file using
the old (existing) configuration method.  Rename the header (such as
config.old.h using the name specified in configure.ac) then generate
another config.h header file using the new configure script.  Include
the old, renamed config header in the new config.h header (also done
already in configure.ac).  Migrate the old config tests (found in
etc/config/src) to Autoconf (m4)  macros (found in etc/config/macros).
After completing each new Autoconf macro, remove the correspoding
define(s) from the old config header.  Rinse and repeat as necessary.

You can test maintenance/distribution changes really easy by running
'make distcheck'.  If the last lines of output look like the following,
then you can safely check in your changes.

	==============================================
	stdcxx-4.3.0 archives ready for distribution: 
	stdcxx-4.3.0.tar.gz
	stdcxx-4.3.0.tar.bz2
	stdcxx-4.3.0.zip
	==============================================

Lastly, there are plenty of specific changes needed in individual files
as indicated by a "TODO:" prefix.


ChangeLog (4.3 Release Plans)
=============================

The following list describes the differences between the files and
directories found in the 4.2.0 distribution and this branch.

Existing Distribution Files
---------------------------

* ChangeLog,
README:

No changes required in new infrastructure.  Automatically packaged and
distributed.

* NOTICE.txt,
configure.bat,
generate.bat:

No changes required to these files but they are not automatically
distributed.  Add them to the EXTRA_DIST variable found in Makefile.am
so that they get packaged in the distribution.

* GNUmakefile:

The file name of this makefile (or its current location in the top-level
source directory) may need to change (e.g. GNUmakefile.top) because GNU
Make looks for this filename before files named "Makefile".  This might
not be a problem for the 4.3 release since the existing infrastructure
is the default but it will likely cause confusion for users who use the
new configure script then type "make" and get a totally unexpected.
output.

* LICENSE.txt:

No changes required to this file but it is not automatically distributed.
Add it to the EXTRA_DIST variable found in Makefile.am so that it gets
packaged in the distribution.

* bin/xbuildgen:

Not really a distribution file, only used for internal testing.  Ignore
it and the subdirectory containing it.

* etc,
doc:

No changes required to files in these subdirectories but they are not
automatically distributed.  Add the subdirectories to the EXTRA_DIST
variable found in Makefile.am so that they get packaged in the
distribution.  (The makefiles generated by Autotools are smart enough
to recursively package the subdirectories and all files within them.)

All other distribution files require no further changes and are
automatically packaged in the distribution by implicit reference in the
associated Automake files.

New Distribution Files
----------------------

The remaining file and directories listed hereafter are specific to the
new infrastructure.

* AUTHORS:

This is a file conventionally found in GNU and other open source
distributions and is automatically packaged in the distribution.  It
should contain at least a list of the STDCXX committers and probably
special thanks to any other major contributors to the project.

(Unless the NOTICE.txt file is mandated by Apache distribution policies,
it can be integrated into the AUTHORS file and then removed from
Subversion.)

* NEWS,
TODO (this file):

Other text files conventionally found in GNU and other open source
distributions that get packaged automatically in the distribution.
Once this experimental branch becomes reasonably stable enough to merge
into the main development baseline, the NEWS file is replaced with
release notes prior to actual distribution.  The TODO file contains a
summary of features and enhancements planned for future releases.

* COPYING:

The conventional filename for including a copy of the GPL.  It is
automatically packaged as part of the distribution by Automake's
makefiles.

Since this branch utilizes quite a bit of code (and includes some GNU
config macros) that was developed with the GPL, it is quite likely that
BOTH license files will need to be included in the distribution.

* configure.ac:

The GNU Autoconf input file.  This is the primary input file used by GNU
Autoconf to generate the configure script.

* Makefile.am:

Input file used by GNU Automake to generate Makefile.in templates.  The
top-level Makefile.am file NEED TO FINISH THIS

This file also contains rules for updating the `maintainer-clean` target.
In addition to files cleaned by the `distclean' target, this target will
clean all files generated by maintenance tools.

* etc/config/aux:

This subdirectory, as specified by the AC_CONFIG_AUX_DIR macro in the
configure.ac file, contains support files required in the new
infrastructure.

* etc/config/macros:

This subdirectory, specified by the AC_CONFIG_MACRO_DIR in configure.ac,
contains the M4 configuration macros used primarily by the GNU Autoconf
tools.  

All other files found in the new infrastructure are either copied from
Autotools or generated by some other means and automatically packaged,
if necessary, in the distribution.


ChangeLog (Proposed 5.0 Release Plans)
======================================

Some of the subdirectories in the 4.2 release use abbreviated names
(e.g. doc, etc, src, util) while others don't (e.g. examples, tests).
For installation directories, the conventional Unix names make sense but
they aren't required for a source distribution.  So for the 5.0 release,
a more consistent naming convention is used for the subdirectories.

* GNUmakefile:

Moved to "config/GNUmakefile" so that GNU Make with find the Makefile
generated by GNU Automake by default.  If users still want to use the
old infrastructure, they'll need to specify the "-f config/GNUmakefile"
option for GNU Make.

* etc/config:

Moved to the top-level "config" subdirectory.

* etc/nls:

Moved to top-level "locale" or "nls" subdirectory.  The "etc"
subdirectory is no longer needed.

* src:

Renamed to "source".

* util:

Renamed to "tools".

* examples,
include,
tests:

No change.