QPID-4640: Fixed up some of the documentation from the autotools deprecation

- The new INSTALL-AUTOMAKE was incorrectly based on the new INSTALL not the old one
- The cmake build instructions didn't use a separate build directory which is the
  recommended configuration (both by cmake and qpid)

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

3 files changed, 105 insertions, 42 deletions

diff --git a/qpid/cpp/INSTALL b/qpid/cpp/INSTALL
index 47af4a3b3e..e83411d34d 100644
--- a/qpid/cpp/INSTALL
+++ b/qpid/cpp/INSTALL
@@ -14,8 +14,7 @@ Table of Contents
 
 3. Building from a Source Distribution
 4. Building a Repository Working Copy
-5. Portability
-6. Tests
+5. Tests
 
 
 1. Introduction
@@ -125,7 +124,7 @@ 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:
+ To build and install the dependency packages:
 
  1. Unzip and untar them and cd to the untared directory.
  2. do:
@@ -135,7 +134,7 @@ It is recommended that you create a directory to install them to, for example,
 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.
@@ -152,6 +151,13 @@ manually installed to non-standard locations. For example:
 
  # export PATH=~/qpid-tools/bin:$PATH
 
+Ensure that pkg-config is set up correctly. This is especially important
+if you have built the dependencies from source, as they may not be installed
+in the default system location. 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:
 
@@ -162,7 +168,9 @@ For example:
 ======================================
 In the distribution directory, build and install with:
 
- # cmake .         # Note "." for the current directory
+ # mkdir BLD       # This is just a suggested name for the build directory
+ # cd BLD
+ # cmake ..        # ".." is the path to the distribution directory
  # make all
  # make install
 
@@ -176,9 +184,14 @@ 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 -DCMAKE_CXX_FLAGS=-g .. && make )   # Note ".." for parent dir
- # (cd .build-dbg; cmake -DCMAKE_CXX_FLAGS=-O3 .. && make)
+ # mkdir BLD-dbg BLD-opt
+ # (cd BLD-dbg; cmake -DCMAKE_BUILD_TYPE=Debug .. && make )
+ # (cd BLD-opt; cmake -DCMAKE_BUILD_TYPE=Release .. && make)
+
+Note that there are 4 different predefined cmake build types:
+Debug, Release, MinSizeRel, DebWithRelInfo: They each correspond to a different
+set of build flags for respectively debug; release; minimum size release; release
+with debug information.
 
 
 4. Building a Repository Working Copy
@@ -192,16 +205,7 @@ 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
+5. Tests
 ========
 See src/tests/README.txt for details.
 
diff --git a/qpid/cpp/INSTALL-AUTOTOOLS b/qpid/cpp/INSTALL-AUTOTOOLS
index 20461cb609..8a35d7bedc 100644
--- a/qpid/cpp/INSTALL-AUTOTOOLS
+++ b/qpid/cpp/INSTALL-AUTOTOOLS
@@ -24,12 +24,13 @@ Table of Contents
    2.2. How to Install
       2.2.1. Using Package Management Tools
       2.2.2. From Source
+	  2.2.2.1. boost
+      2.2.2.2. autotools
    2.3. Important Environment Variable Settings
 
 3. Building from a Source Distribution
 4. Building a Repository Working Copy
-5. Portability
-6. Tests
+5. Tests
 
 
 1. Introduction
@@ -81,9 +82,11 @@ 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)
@@ -114,7 +117,7 @@ e2fsprogs-devel package.
 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
+ # yum install boost-devel libuuid-devel pkgconfig gcc-c++ make autoconf automake ruby libtool help2man doxygen graphviz
 
 For SASL and SSL, include
  # yum install cyrus-sasl-devel nss-devel nspr-devel
@@ -147,8 +150,8 @@ It is recommended that you create a directory to install them to, for example,
 
 The exception is boost.
 
-boost
-========
+2.2.2.1. 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.
@@ -157,6 +160,39 @@ boost
   # bjam toolset=gcc variant=release threading=single link=shared \
     --layout=system --prefix=~/qpid-tools install
 
+2.2.2.2. 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
 ============================================
@@ -165,6 +201,11 @@ 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:
 
@@ -177,48 +218,64 @@ In the distribution directory
 
 Build and install with:
 
- # mkdir build
- # cd build
- # cmake ..
+ # ./configure --prefix=<install_location>
  # make all
  # make install
 
 To build and test everything:
 
  # make
- # make test
+ # make check
 
 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-dbg; cmake cmake -DCMAKE_CXX_FLAGS=-g .. && make )
- # (cd .build-dbg; cmake cmake -DCMAKE_CXX_FLAGS=-O3 .. && make)
+ # (cd .build-opt ../configure --prefix=/tmp/x && make && make check)
+ # (cd .build-dbg ../configure CXXFLAGS=-g --prefix=/tmp/x \
+    && make && make check)
 
 
 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).
+To build a fresh checkout:
 
+Cd to qpid/cpp subdirectory. Before running make on a fresh checkout do:
 
-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.
+ # ./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).
 
-These wrappers are mainly inline by-value classes so they impose no
-run-time penalty compared do direct system calls.
 
-6. Tests
+5. Tests
 ========
 See src/tests/README.txt for details.
 
diff --git a/qpid/cpp/README.txt b/qpid/cpp/README.txt
index 425e382a23..9e11474bb7 100644
--- a/qpid/cpp/README.txt
+++ b/qpid/cpp/README.txt
@@ -37,7 +37,9 @@ For documentation, go to:
 
 In C++ distributions:
 
-   cmake .        # Generates code and makefiles
+   mkdir BLD      # The recommended way to use cmake is in a separate build directory
+   cd BLD
+   cmake ..       # Generates code and makefiles
    make test      # Runs tests
    make install   # Installs the client and daemon