QPID-4640: Deprecate autotools build system.

This patch does the following:

- Update INSTALL and README files to refer to the cmake build.
- configure script prints a deprecation notice.

The autotools instructions are still available in INSTALL-AUTOTOOLS,
which also has a deprecation notice.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1457098 13f79535-47bb-0310-9956-ffa450edef68

5 files changed, 273 insertions, 161 deletions

diff --git a/qpid/cpp/INSTALL b/qpid/cpp/INSTALL
index 770a16f72f..47af4a3b3e 100644
--- a/qpid/cpp/INSTALL
+++ b/qpid/cpp/INSTALL
@@ -10,16 +10,12 @@ Table of Contents
    2.2. How to Install
       2.2.1. Using Package Management Tools
       2.2.2. From Source
-	 b. boost
-         c. autotools
    2.3. Important Environment Variable Settings
 
 3. Building from a Source Distribution
 4. Building a Repository Working Copy
 5. Portability
 6. Tests
-7. Doxygen
-8. Troubleshooting
 
 
 1. Introduction
@@ -38,8 +34,7 @@ This also explains how to install the required prerequisites for Qpid/C++.
 We prefer to avoid spending time accommodating older versions of these
 packages, so please make sure that you have the latest stable versions.
 Known version numbers for a succesfull build are given in brackets, take
-these as a recommended minimum version. Older unix versions, for example,
-Redhat Linux 3, will almost certainly require some packages to be upgraded.
+these as a recommended minimum version.
 
 
 2.1. What to Install
@@ -72,11 +67,9 @@ Qpid has been built using the GNU C++ compiler:
 If you want to build directly from the SVN repository you will need
 all of the above plus:
 
+ * Cmake      <http://www.cmake.org/>                   (2.6.4)
  * GNU make   <http://www.gnu.org/software/make/>      	(3.8.0)
- * autoconf   <http://www.gnu.org/software/autoconf/>  	(2.61)
- * automake   <http://www.gnu.org/software/automake/>  	(1.9.6)
  * help2man   <http://www.gnu.org/software/help2man/>  	(1.36.4)
- * libtool    <http://www.gnu.org/software/libtool/>   	(1.5.22)
  * doxygen    <ftp://ftp.stack.nl/pub/users/dimitri/>  	(1.5.1)
  * graphviz   <http://www.graphviz.org/>               	(2.12)
  * ruby 1.8   <http://www.ruby-lang.org>               	(1.8.4)
@@ -92,6 +85,7 @@ the following must also be installed:
  * swig       <http://www.swig.org>                     (1.3.35)
 
 UUID problems:
+
 In some earlier Linux releases (such as Fedora 11), the uuid/uuid.h
 file is located in the e2fsprogs-devel package instead of
 libuuid-devel. If you are using an older Linux release and run into a
@@ -107,7 +101,7 @@ e2fsprogs-devel package.
 On linux most packages can be installed using your distribution's
 package management tool. For example on Fedora:
 
- # yum install boost-devel libuuid-devel pkgconfig gcc-c++ make autoconf automake ruby libtool help2man doxygen graphviz
+ # yum install cmake boost-devel libuuid-devel pkgconfig gcc-c++ make ruby help2man doxygen graphviz
 
 For SASL and SSL, include
  # yum install cyrus-sasl-devel nss-devel nspr-devel
@@ -150,39 +144,6 @@ boost
   # bjam toolset=gcc variant=release threading=single link=shared \
     --layout=system --prefix=~/qpid-tools install
 
-c. autotools
-============
-If you don't have sufficiently up-to-date autotools you can get the
-latest by running the script qpid-autotools-install.
-
-1. Decide where you would like to install the tools. It should be in a
-   local directory so that you do not need root privileges. (Suggest
-   $HOME/qpid-tools.) Create an empty directory.
-2. Modify your environment variable PATH to ensure that the bin directory
-   within this directory comes first in the PATH string:
-   PATH=$HOME/qpid-tools/bin:$PATH
-3. Set PKG_CONFIG_PATH=$HOME/qpid-tools/lib/pkgconfig:/usr/lib/pkgconfig
-   (or if it already exists, make sure that the above path to your
-   qpid-tools directory is first).
-4. Run the install utility from the cpp directory:
-   ./qpid-autotools-install --prefix=$HOME/qpid-tools --skip-check
-   (Note that --prefix will only accept an absolute path, so don't use
-   ~/qpid-tools.) The utility will download, compile and install the
-   required tools into the qpid-tools directory (this may take a little
-   time). Watch for any notices about paths at the end of the install -
-   this means that your environment is not correct - see steps 2 and 3
-   above.
-   NOTE: If you omit the --skip-check option, the check of the build
-   can add up to an hour to what is normally a few minutes of install
-   time.
-5. Perform a check: from the command-line run "which automake" and
-   ensure that it finds the automake in your qpid-tools directory. If not,
-   check that the build completed normally and your environment.
-6. (Optional) If having the build artifacts lying around bothers you, delete
-   the (hidden) build directory cpp/.build-auto-tools.
-
-To see help, run ./qpid-autotools-install --help.
-
 
 2.3. Important Environment Variable Settings
 ============================================
@@ -191,11 +152,6 @@ manually installed to non-standard locations. For example:
 
  # export PATH=~/qpid-tools/bin:$PATH
 
-Ensure that pkg-config is set up correctly. For example:
-
- # export PKG_CONFIG_PATH=~/qpid-tools/lib/pkgconfig:/usr/local/pkgconfig
- # export PKG_CONFIG=~/qpid-tools/bin/pkg-config
-
 Ensure that the boost libraries are made available on the gcc library path.
 For example:
 
@@ -204,65 +160,36 @@ For example:
 
 3. Building from a Source Distribution
 ======================================
-In the distribution directory
-
-Build and install with:
+In the distribution directory, build and install with:
 
- # ./configure --prefix=<install_location>
+ # cmake .         # Note "." for the current directory
  # make all
  # make install
 
 To build and test everything:
 
  # make
- # make check
+ # make test
 
 This builds in the source tree. You can have multiple builds in the
 same working copy with different configuration. For example you can do
 the following to build twice, once for debug, the other with
 optimization:
 
- # make distclean
  # mkdir .build-dbg .build-opt
- # (cd .build-opt ../configure --prefix=/tmp/x && make && make check)
- # (cd .build-dbg ../configure CXXFLAGS=-g --prefix=/tmp/x \
-    && make && make check)
+ # (cd .build-dbg; cmake -DCMAKE_CXX_FLAGS=-g .. && make )   # Note ".." for parent dir
+ # (cd .build-dbg; cmake -DCMAKE_CXX_FLAGS=-O3 .. && make)
 
 
 4. Building a Repository Working Copy
 =====================================
+
 To get the source code from the subversion repository (trunk) do:
 
  # svn checkout http://svn.apache.org/repos/asf/qpid/trunk/qpid/.
 
-To build a fresh checkout:
-
-Cd to qpid/cpp subdirectory. Before running make on a fresh checkout do:
-
- # ./bootstrap
-
-This generates config, makefiles and the like - check the script for
-details. You only need to do this once, "make" will keep everything up
-to date thereafter (including re-generating configuration & Makefiles
-if the automake templates change etc.)
-
-If you are developing code yourself, or if you want to help
-us keep the code as tight and robust as possible, consider enabling
-the use of valgrind. If you configure like this:
-
- # ./configure --enable-valgrind
-
-That will arrange (assuming you have valgrind installed) for "make check"
-to run tests via valgrind.  That makes the tests run more slowly, but
-helps detect certain types of bugs, as well as memory leaks.  If you run
-"make check" and valgrind detects a leak that is not listed as being
-"ignorable-for-now", the test script in question will fail.  However,
-recording whether a leak is ignorable is not easy, when the stack
-signature, libraries, compiler, O/S, architecture, etc., may all vary,
-so if you see a new leak, try to figure out if it's one you can fix
-before adding it to the list.
-
-Now follow instruction for building from a source distribution in step (3).
+To build, cd to qpid/cpp subdirectory and then follow instruction for building
+from a source distribution in step (3).
 
 
 5. Portability
@@ -274,37 +201,7 @@ code.
 These wrappers are mainly inline by-value classes so they impose no
 run-time penalty compared do direct system calls.
 
-Initially we will have a full linux implementation and a portable
-implementation sufficient for the client using the APR portability
-library. The implementations may change in future but the interface
-for qpid code outside the qpid/sys namespace should remain stable.
-
-
 6. Tests
 ========
 See src/tests/README.txt for details.
 
-
-7. Doxygen
-==========
-Doxygen generates documentation in several formats from source code
-using special comments. You can use javadoc style comments if you know
-javadoc, if you don't or want to know the fully story on doxygen
-markup see http://www.stack.nl/~dimitri/doxygen/
-
-Even even if the code is completely uncommented, doxygen generates
-UML-esque dependency diagrams that are ''extremely'' useful in navigating
-around the code, especially for newcomers.
-
-To try it out "make doxygen" then open doxygen/html/index.html.
-
-
-8. Troubleshooting
-==================
-When building, get the following on configure
-  configure: error: Package requirements (apr-1 >= 1.2.2) were not met:
-
-  No package 'apr-1' found
-
-The following has not been set
-  export PKG_CONFIG_PATH=$HOME/qpid-tools/lib/pkgconfig:/usr/lib/pkgconfig
diff --git a/qpid/cpp/INSTALL-AUTOTOOLS b/qpid/cpp/INSTALL-AUTOTOOLS
new file mode 100644
index 0000000000..20461cb609
--- /dev/null
+++ b/qpid/cpp/INSTALL-AUTOTOOLS
@@ -0,0 +1,224 @@
+
+
+   ============================== DEPRECATED ==============================
+
+   This file describes how to use the autotools build system to build Qpid.
+   The autotools build system is *deprecated* and will be removed in a
+   future release. Use the cmake build system instead as described in the
+   INSTALL file.
+
+   You can continue using the autoconf build system until you switch to
+   cmake. Run configure with --enable-deprecated=yes to enable it.
+
+   ========================================================================
+
+		Installing Qpid/C++
+		===================
+
+Table of Contents
+=================
+1. Introduction
+
+2. Prerequisites
+   2.1. What to Install
+   2.2. How to Install
+      2.2.1. Using Package Management Tools
+      2.2.2. From Source
+   2.3. Important Environment Variable Settings
+
+3. Building from a Source Distribution
+4. Building a Repository Working Copy
+5. Portability
+6. Tests
+
+
+1. Introduction
+===============
+Note that the daemon and client API can be installed separately.
+
+This document describes how to build the Qpid/C++ broker and client, either
+from a checkout of the source or from a source distribution, on Linux/UNIX.
+Please see INSTALL-WINDOWS for information on building on Windows.
+
+This also explains how to install the required prerequisites for Qpid/C++.
+
+
+2. Prerequisites
+================
+We prefer to avoid spending time accommodating older versions of these
+packages, so please make sure that you have the latest stable versions.
+Known version numbers for a succesfull build are given in brackets, take
+these as a recommended minimum version.
+
+
+2.1. What to Install
+====================
+The following libraries and header files must be installed to build
+a source distribution:
+ * boost      <http://www.boost.org>                    (1.35)(*)
+ * libuuid    <http://kernel.org/~kzak/util-linux/>     (2.19)
+ * pkgconfig  <http://pkgconfig.freedesktop.org/wiki/>  (0.21)
+
+(*) earlier versions of boost e.g. 1.33 also work and there is a patch
+to get 1.32 working in the svn tree though that is only recommended as
+a last resort.
+
+Optional XML exchange requires:
+ * xqilla  <http://xqilla.sourceforge.net/HomePage>     (2.0.0)
+ * xerces-c <http://xerces.apache.org/xerces-c/>        (2.7.0)
+
+Optional SSL support requires:
+* nss <http://www.mozilla.org/projects/security/pki/nss/>
+* nspr <http://www.mozilla.org/projects/nspr/>
+
+Optional binding support for ruby requires:
+* ruby and ruby devel <http://www.ruby-lang.org/en/>
+* swig <http://www.swig.org/>
+
+Qpid has been built using the GNU C++ compiler:
+ * gcc     <http://gcc.gnu.org/>            		(3.4.6)
+
+If you want to build directly from the SVN repository you will need
+all of the above plus:
+
+ * Cmake      <http://www.cmake.org/>                   (2.6.4)
+ * GNU make   <http://www.gnu.org/software/make/>      	(3.8.0)
+ * help2man   <http://www.gnu.org/software/help2man/>  	(1.36.4)
+ * doxygen    <ftp://ftp.stack.nl/pub/users/dimitri/>  	(1.5.1)
+ * graphviz   <http://www.graphviz.org/>               	(2.12)
+ * ruby 1.8   <http://www.ruby-lang.org>               	(1.8.4)
+
+
+NOTE: make sure to install the related '-devel' packages also!
+
+To build the QMF (Qpid Management Framework) bindings for Ruby and Python,
+the following must also be installed:
+
+ * ruby-devel
+ * python-devel
+ * swig       <http://www.swig.org>                     (1.3.35)
+
+UUID problems:
+In some earlier Linux releases (such as Fedora 11), the uuid/uuid.h
+file is located in the e2fsprogs-devel package instead of
+libuuid-devel. If you are using an older Linux release and run into a
+problem during configure in which uuid.h cannot be found, install the
+e2fsprogs-devel package.
+
+2.2. How to Install
+===================
+
+2.2.1. Using Package Management Tools
+=====================================
+
+On linux most packages can be installed using your distribution's
+package management tool. For example on Fedora:
+
+ # yum install cmake boost-devel libuuid-devel pkgconfig gcc-c++ make ruby help2man doxygen graphviz
+
+For SASL and SSL, include
+ # yum install cyrus-sasl-devel nss-devel nspr-devel
+
+For the XML Exchange, include:
+
+ # yum install xqilla-devel xerces-c-devel
+
+Optional ruby binding support include:
+ # yum install ruby ruby-devel swig
+
+Optional legacystore store module.
+# yum install libdb-cxx-devel libaio-devel
+
+Follow the manual installation instruction below for any packages not
+available through your distributions packaging tool.
+
+2.2.2. From Source
+==================
+Required dependencies can be installed and built from source distributions.
+It is recommended that you create a directory to install them to, for example,
+~/qpid-tools.
+
+ To build and install the dependency pakcages:
+
+ 1. Unzip and untar them and cd to the untared directory.
+ 2. do:
+  # ./configure --prefix=~/qpid-tools
+  # make install
+
+The exception is boost.
+
+boost
+========
+ 1. Unpack boost-jam.
+ 2. Add bjam in the unpacked directory to your path.
+ 3. Unpack boost and cd to the boost untarred directory.
+ 4. do:
+
+  # bjam toolset=gcc variant=release threading=single link=shared \
+    --layout=system --prefix=~/qpid-tools install
+
+
+2.3. Important Environment Variable Settings
+============================================
+Ensure that all the build tools are available on your path, when they are
+manually installed to non-standard locations. For example:
+
+ # export PATH=~/qpid-tools/bin:$PATH
+
+Ensure that the boost libraries are made available on the gcc library path.
+For example:
+
+ # export CXXFLAGS=-I~/qpid-tools/include/boost-1_33_1
+
+
+3. Building from a Source Distribution
+======================================
+In the distribution directory
+
+Build and install with:
+
+ # mkdir build
+ # cd build
+ # cmake ..
+ # make all
+ # make install
+
+To build and test everything:
+
+ # make
+ # make test
+
+This builds in the source tree. You can have multiple builds in the
+same working copy with different configuration. For example you can do
+the following to build twice, once for debug, the other with
+optimization:
+
+ # mkdir .build-dbg .build-opt
+ # (cd .build-dbg; cmake cmake -DCMAKE_CXX_FLAGS=-g .. && make )
+ # (cd .build-dbg; cmake cmake -DCMAKE_CXX_FLAGS=-O3 .. && make)
+
+
+4. Building a Repository Working Copy
+=====================================
+
+To get the source code from the subversion repository (trunk) do:
+
+ # svn checkout http://svn.apache.org/repos/asf/qpid/trunk/qpid/.
+
+To build, cd to qpid/cpp subdirectory and then follow instruction for building
+from a source distribution in step (3).
+
+
+5. Portability
+==============
+All system calls are abstracted by classes under lib/common/sys. This
+provides an object-oriented C++ API and contains platform-specific
+code.
+
+These wrappers are mainly inline by-value classes so they impose no
+run-time penalty compared do direct system calls.
+
+6. Tests
+========
+See src/tests/README.txt for details.
+
diff --git a/qpid/cpp/README.txt b/qpid/cpp/README.txt
index f200802342..425e382a23 100644
--- a/qpid/cpp/README.txt
+++ b/qpid/cpp/README.txt
@@ -13,9 +13,6 @@ Table of Contents
 Qpid/C++ is a C++ implementation of the AMQP protcol described at
 http://amqp.org/
 
-This release of Qpid/C++ implements the AMQP 0-10. 
-It will not inter-operate with AMQP 0-8/0-9 implementations.
-
 For additional software or information on the Qpid project go to:
 
    http://qpid.apache.org
@@ -40,15 +37,9 @@ For documentation, go to:
 
 In C++ distributions:
 
-   ./configure && make - compiles all sources
-
-   make check - runs tests
-
-   make install - installs the client and daemon
-
-In some distributions, no ./configure file is provided. To create the
-./configure file, you must have autotools installed. Run ./bootstrap
-from the qpid/cpp directory, then follow the above instructions.
+   cmake .        # Generates code and makefiles
+   make test      # Runs tests
+   make install   # Installs the client and daemon
 
 The INSTALL notes contain more detailed information on compiling and
 installing this software.
diff --git a/qpid/cpp/configure.ac b/qpid/cpp/configure.ac
index e876dd66af..1523af81af 100644
--- a/qpid/cpp/configure.ac
+++ b/qpid/cpp/configure.ac
@@ -33,6 +33,7 @@ AC_LANG([C++])
 # doesn't exist)
 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],[])],[],[AC_MSG_ERROR([No C++ compiler found])])
 
+
 # Check for optional use of help2man
 AC_CHECK_PROG([HELP2MAN], [help2man], [help2man])
 AC_ARG_WITH([help2man],
@@ -550,3 +551,19 @@ AC_CONFIG_FILES([
   ])
 AC_OUTPUT
 
+cat <<EOF
+
+
+   ============================== DEPRECATED ==============================
+
+   The autotools build system is deprecated, use the cmake build system
+   instead as described in the INSTALL file.
+
+   You can continue to use the autotools system for now, but it will be
+   removed in a future release. If you encounter any problems with the
+   cmake system send email to dev@qpid.apache.org.
+
+   ========================================================================
+
+
+EOF
diff --git a/qpid/cpp/src/tests/README.txt b/qpid/cpp/src/tests/README.txt
index 0f4edee493..8eaa5bbd25 100644
--- a/qpid/cpp/src/tests/README.txt
+++ b/qpid/cpp/src/tests/README.txt
@@ -1,54 +1,37 @@
 = Running Qpid C++ tests =
 
-General philosophy is that "make check" run all tests by default, but
+General philosophy is that "make test" run all tests by default, but
 developers can run tests selectively as explained below.
 
-== Valgrind ==
-
-By default we run tests under valgrind to detect memory errors if valgrind
-is present. ./configure --disable-valgrind will disable it.
-
-Default valgrind options are specified in .valgrindrc-default, which a
-checked-in file. The actual options used are in .valgrindrc which is a
-local file. Normally it is a copy of valgrindrc-default but you can
-modify at will.
-
-Supressed errors are listed in .valgrind.supp. If you want to change
-suppressions for local testing, just modify .valgrindrc to point to a
-different file. Do NOT add suppressions to .valgrindrc.supp unless
-they are known problems outside of Qpid that can't reasonably be
-worked around in Qpid.
-
-
 == Unit Tests ==
-Unit tests use the boost test framework, and are compiled to rogram
- unit_test
-There are several options to control how test results are displayed,
-see
- http://www.boost.org/doc/libs/1_35_0/libs/test/doc/components/utf/parameters/index.html
 
-NOTE: some unit tests are written as CppUnit plug-ins, we are moving away
-from CppUnit so new tests should use the boost framework.
+Unit tests use the boost test framework, and are compiled to the programd
+unit_test
 
-CppUnit tests are run by the script run-unit-tests.
+There are several options to control how test results are displayed, see
+ http://www.boost.org/doc/libs/1_35_0/libs/test/doc/components/utf/parameters/index.html
 
 == System Tests ==
 
-System tests are self contained AMQP client executables or scripts.
-They are listed in the TESTS make variable, which can be over-ridden.
-
-The ./start_broker "test" launches the broker, ./stop_broker" stops it.
-Tests in between assume the broker is running.
+System tests are executables or scripts. You can run executable tests directly
+as well as via "make test" or "ctest".  Some tests require environment settings
+which are set by src/tests/test_env.sh on Unix or by src/tests/test_env.ps1 on
+Windows.
 
 ./python_tests: runs ../python/run_tests. This is the main set of
-system testss for the broker.
+system tests for the broker.
 
 Other C++ client test executables and scripts under client/test are
 system tests for the client.
 
-By setting TESTS in a make command you can run a different subset of tests
-against an already-running broker.
+== Running selected tests ==
 
+The make target "make test" simply runs the command "ctest".  Running ctest
+directly gives you additional options, e.g.
 
+  ctest -R <regexp> -VV
 
+This runs tests with names matching the regular expression <regexp> and will
+print the full output of the tests rather than just listing which tests pass or
+fail.