Improves the documentation.

git-svn-id: http://googlemock.googlecode.com/svn/trunk@42 8415998a-534a-0410-bf83-d39667b30386

2 files changed, 103 insertions, 49 deletions

diff --git a/README b/README
index 47d10ed..f51c9ba 100644
--- a/README
+++ b/README
@@ -31,7 +31,7 @@ OFTC (irc.oftc.net) #gtest available. Please join us!
 
 Please note that code under scripts/generator/ is from the cppclean
 project (http://code.google.com/p/cppclean/) and under the Apache
-License.
+License, which is different from Google Mock's license.
 
 Requirements
 ------------
@@ -89,11 +89,11 @@ much more active and have the latest features, but the latter provides much
 more stability and predictability. Choose whichever fits your needs best, and
 proceed with the following Subversion commands:
 
-  $ svn checkout http://googlemock.googlecode.com/svn/trunk/ gmock-svn
+  svn checkout http://googlemock.googlecode.com/svn/trunk/ gmock-svn
 
 or for a release version X.Y.*'s branch:
 
-  $ svn checkout http://googlemock.googlecode.com/svn/branches/release-X.Y/ \
+  svn checkout http://googlemock.googlecode.com/svn/branches/release-X.Y/ \
     gmock-X.Y-svn
 
 Next you will need to prepare the GNU Autotools build system, if you
@@ -101,27 +101,28 @@ are using Linux or Mac OS X. Enter the target directory of the
 checkout command you used ('gmock-svn' or 'gmock-X.Y-svn' above) and
 proceed with the following command:
 
-  $ autoreconf -fvi
+  autoreconf -fvi
 
-Once you have completed this step, you are ready to build the library.
-Note that you should need to complete this step only once.  The sub-
-sequent `make' invocations will automatically re-generate the bits of
-the build system that need to be changed.
+Once you have completed this step, you are ready to build the library. Note
+that you should only need to complete this step once. The subsequent `make'
+invocations will automatically re-generate the bits of the build system that
+need to be changed.
 
 If your system uses older versions of the autotools, the above command will
-fail.  You may need to explicitly specify a version to use.  For instance, if
-you have both GNU Automake 1.4 and 1.9 installed and `automake' would invoke
-the 1.4, use instead:
+fail. You may need to explicitly specify a version to use. For instance, if you
+have both GNU Automake 1.4 and 1.9 installed and `automake' would invoke the
+1.4, use instead:
 
-  $ AUTOMAKE=automake-1.9 ACLOCAL=aclocal-1.9 autoreconf -fvi
+  AUTOMAKE=automake-1.9 ACLOCAL=aclocal-1.9 autoreconf -fvi
 
 Make sure you're using the same version of automake and aclocal.
 
 ### Source Package: ###
 Google Mock is also released in source packages which can be downloaded from
 its Google Code download page[1]. Several different archive formats are
-provided, but the only difference is the tools used to manipulate them, and the
-size of the resulting file. Download whichever you are most comfortable with.
+provided, but the only difference is the tools needed to extract their
+contents, and the size of the resulting file. Download whichever you are most
+comfortable with.
 
   [1] Google Mock Downloads: http://code.google.com/p/googlemock/downloads/list
 
@@ -129,9 +130,9 @@ Once downloaded expand the archive using whichever tools you prefer for that
 type. This will always result in a new directory with the name "gmock-X.Y.Z"
 which contains all of the source code. Here are some examples in Linux:
 
-  $ tar -xvzf gmock-X.Y.Z.tar.gz
-  $ tar -xvjf gmock-X.Y.Z.tar.bz2
-  $ unzip gmock-X.Y.Z.zip
+  tar -xvzf gmock-X.Y.Z.tar.gz
+  tar -xvjf gmock-X.Y.Z.tar.bz2
+  unzip gmock-X.Y.Z.zip
 
 Building the Source
 -------------------
@@ -148,35 +149,83 @@ either approach by simply substituting the shell variable SRCDIR with "." for
 building inside the source directory, and the relative path to the source
 directory otherwise.
 
-  $ ${SRCDIR}/configure  # Standard GNU configure script, --help for more info
-  $ make  # Standard makefile following GNU conventions
-  $ make check  # Builds and runs all tests - all should pass
+  ${SRCDIR}/configure  # Standard GNU configure script, --help for more info
+
+The default behavior of the configure script with respect to locating and using
+Google Test is to first search for a 'gtest-config' in the system path, and
+lacking this, build an internal copy of Google Test. You may optionally specify
+a custom Google Test you wish to build Google Mock against, provided it is
+a new enough version.
+
+  # Configure against an installation in '/opt' with '/opt/bin/gtest-config'.
+  ${SRCDIR}/configure --with-gtest=/opt
+
+This can also be used to specify a Google Test which hasn't yet been installed.
+However, it must have been configured and built as described in the Google Test
+README before you configure Google Mock. To enable this feature, simply pass
+the directory where you configured and built Google Test (which is not
+necessarily its source directory) to Google Mock's configure script.
+
+  # Configure against a build of Google Test in an arbitrary directory.
+  ${SRCDIR}/configure --with-gtest=../../my_gtest_build
+
+Finally, if you have a version of Google Test installed but for some reason
+wish to forcibly prevent it from being used, we provide a special option.
+Typically this is not needed as we fall back to the internal Google Test
+packaged with Google Mock if an installed version is either unavailable or too
+old to build Google Mock. When using the internally packaged Google Test, the
+user does *not* need to configure or build it, that is automatically handled by
+Google Mock's build system.
+
+  # Force the use of the internally packaged Google Test, despite
+  # 'gtest-config' being in your PATH.
+  ${SRCDIR}/configure --disable-external-gtest
+
+Once you have successfully configured Google Mock, the build steps are standard
+for GNU-style OSS packages.
+
+  make  # Standard makefile following GNU conventions
+  make check  # Builds and runs all tests - all should pass
 
 Other programs will only be able to use Google Mock's functionality if you
 install it in a location which they can access, in Linux this is typically
 under '/usr/local'. The following command will install all of the Google Mock
 libraries, public headers, and utilities necessary for other programs and
-libraries to leverage it:
+libraries to leverage it. Note that if Google Mock was unable to find an
+external Google Test to build against, it will also install the internally
+packaged Google Test in order to allow the installed Google Mock to function
+properly. This Google Test install will be fully functional, and if installed
+will also be uninstalled by uninstalling Google Mock.
+
+  sudo make install  # Not necessary, but allows use by other programs
 
-  $ sudo make install  # Not necessary, but allows use by other programs
+Should you need to remove Google Mock from your system after having installed
+it, run the following command, and it will back out its changes.  However, note
+carefully that you must run this command on the *same* Google Mock build that
+you ran the install from, or the results are not predictable.  If you install
+Google Mock on your system, and are working from a VCS checkout, make sure you
+run this *before* updating your checkout of the source in order to uninstall
+the same version which you installed.
 
-TODO(chandlerc@google.com): This section needs to be expanded when the
-'gmock-config' script is finished and Autoconf macro's are provided (or not
-provided) in order to properly reflect the process for other programs to
-locate, include, and link against Google Mock.
+  sudo make uninstall  # Must be run against the exact same build as "install"
 
-Finally, should you need to remove Google Mock from your system after having
-installed it, run the following command, and it will back out its changes.
-However, note carefully that you must run this command on the *same* Google
-Mock build that you ran the install from, or the results are not predictable.
-If you install Google Mock on your system, and are working from a VCS checkout,
-make sure you run this *before* updating your checkout of the source in order
-to uninstall the same version which you installed.
+Your project can build against Google Mock and Google Test simply by leveraging
+the 'gmock-config' script. This script can be invoked directly out of the
+'scripts' subdirectory of the build tree, and it will be installed in the
+binary directory specified during the 'configure'. Here are some examples of
+its use, see 'gmock-config --help' for more detailed information.
 
-  $ sudo make uninstall  # Must be run against the exact same build as "install"
+  gmock-config --min-version=1.0 || echo "Insufficient Google Mock version."
 
-TODO(chandlerc@google.com): Fixes the above instructions to match the
-actual implementation.
+  g++ $(gmock-config --cppflags --cxxflags) -o foo.o -c foo.cpp
+  g++ $(gmock-config --ldflags --libs) -o foo foo.o
+
+  # When using a built but not installed Google Mock:
+  g++ $(../../my_gmock_build/scripts/gmock-config ...) ...
+
+Note that when building your project against Google Mock, you are building
+against Google Test as well. There is no need to configure Google Test
+separately.
 
 ### Windows ###
 The msvc/ directory contains VC++ 2005 projects for building Google Mock and
@@ -192,11 +241,11 @@ one.
 
 For example, if you unpacked boost v1.36.0 into C:\boost:
 To configure Boost as a system library.
- * Assuming you are using the Visual Studio 2008 IDE, select Tools |
+ * Assuming you are using the Visual Studio 2005 IDE, select Tools |
    Options | Projects And Solutions | VC++ Directories.
  * In the "Show directories for" drop-down select Include Files.  Add
- * C:\boost\boost_1_36_0\boost\tr1\tr1 and C:\boost\boost_1_36_0
-   to the list of directories.
+   C:\boost\v_1_36_0\boost\tr1\tr1 and C:\boost\v_1_36_0 to the list of
+   directories.
 
 To configure your project to point to that version of Boost, replace
 the value of the BoostDir user macro with C:\boost\boost_1_36_0 in the
@@ -209,9 +258,14 @@ to point to the new location.
 After configuring Boost, just open msvc/gmock.sln and build the library and
 tests. If you want to create your own project to use with Google Mock, you'll
 have to configure it to use the gmock_config propety sheet. For that:
- * Open the Property Manager window (View/Other Windows/Property Manager)
+ * Open the Property Manager window (View | Other Windows | Property Manager)
  * Right-click on your project and select "Add Existing Property Sheet..."
  * Navigate to gmock_config.vsprops and select it.
+ * In Project Properties | Configuration Properties | General | Additional
+   Include Directories, type <path to Google Mock>/include.
+
+TODO(wan@google.com): update the .vsprops and .vcproj files such that the
+last step is unnecessary.
 
 ### Using GNU Make ###
 The make/ directory contains a Makefile that you can use to build
@@ -223,9 +277,9 @@ use it as a starting point for your own Makefile.
 If the default settings are correct for your environment, the
 following commands should succeed:
 
-  $ cd ${SRCDIR}/make
-  $ make
-  $ ./gmock_test
+  cd ${SRCDIR}/make
+  make
+  ./gmock_test
 
 If you see errors, try to tweak the contents of make/Makefile to make
 them go away.  There are instructions in make/Makefile on how to do
@@ -239,13 +293,13 @@ the Google Test source tree) and src/gmock-all.cc into a library and
 link your tests with it.  Assuming a Linux-like system and gcc,
 something like the following will do:
 
-  $ cd ${SRCDIR}
-  $ g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \
+  cd ${SRCDIR}
+  g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \
     -c {GTEST_SRCDIR}/src/gtest-all.cc
-  $ g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \
+  g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \
     -c src/gmock-all.cc
-  $ ar -rv libgmock.a gtest-all.o gmock-all.o
-  $ g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \
+  ar -rv libgmock.a gtest-all.o gmock-all.o
+  g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \
     path/to/your_test.cc libgmock.a -o your_test
 
 On Windows, you'll also need to add the include path for the boost
diff --git a/scripts/gmock-config.in b/scripts/gmock-config.in
index 540faff..016ad61 100755
--- a/scripts/gmock-config.in
+++ b/scripts/gmock-config.in
@@ -34,7 +34,7 @@ Compiler flag queries output the union of the sets of flags when combined.
   g++ $(gmock-config --ldflags --libs) -o foo foo.o
 
   # When using a built but not installed Google Mock:
-  g++ $(../../my_gmock_build/scripts/gtest-config ...) ...
+  g++ $(../../my_gmock_build/scripts/gmock-config ...) ...
 
   # When using an installed Google Mock, but with installation overrides:
   export GMOCK_PREFIX="/opt"