updating build instructions

5 files changed, 79 insertions, 257 deletions

diff --git a/cpp/BuildInstructions.md b/cpp/BuildInstructions.md
index 0ee0efc70de..fd0c58397ee 100644
--- a/cpp/BuildInstructions.md
+++ b/cpp/BuildInstructions.md
@@ -1,6 +1,5 @@
 # Building Ice for C++
 
-- [Building Ice for C++ on AIX.](BuildInstructionsAIX.md)
-- [Building Ice for C++ on Linux.](BuildInstructionsLinux.md)
-- [Building Ice for C++ on Linux.](BuildInstructionsOSX.md)
-- [Building Ice for C++ on Windows.](BuildInstructionsWindows.md)
\ No newline at end of file
+- [Building Ice for C++ on Linux](BuildInstructionsLinux.md)
+- [Building Ice for C++ on macOS](BuildInstructionsMacOS.md)
+- [Building Ice for C++ on Windows](BuildInstructionsWindows.md)
diff --git a/cpp/BuildInstructionsAIX.md b/cpp/BuildInstructionsAIX.md
deleted file mode 100644
index 59dcb261e14..00000000000
--- a/cpp/BuildInstructionsAIX.md
+++ /dev/null
@@ -1,164 +0,0 @@
-# Building Ice for C++ on AIX
-
-This document provides step-by-step instructions for building Ice for C++
-from sources on AIX.
-
-## Unsupported Platform
-
-AIX is currently an unsupported platform. Only minimal testing was performed
-on AIX, and there is no guarantee future releases of Ice will build or run
-on this platform.
-
-## Recommended Operating System and C++ Compiler
-
- - AIX 6.1, AIX 7.1
- - IBM XL C/C++ 12.1 with latest Fix Pack
- - 32 bit or 64 bit
-
-## Build Pre-Requisites
-
-Before building Ice, you need to install or build a number of third-party
-packages that Ice depends on, and install some build tools.
-
-### Third-Party Packages
-
-Ice depends on several open-source packages: bzip2 1.0, expat 2.x, LMDB 0.9.x, 
-mcpp 2.7.2 (+patches) and OpenSSL.
-
-OpenSSL is a system package on AIX. RPM packages for bzip2 and expat are
-available in the [AIX Toolbox for Linux Applications][1]. You can install
-them as follows:
-
-```
-# As root
-rpm -i ftp://public.dhe.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/bzip2/bzip2-1.0.5-3.aix5.3.ppc.rpm
-rpm -i ftp://public.dhe.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/expat/expat-2.0.1-2.aix5.3.ppc.rpm
-rpm -i ftp://public.dhe.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/expat/expat-devel-2.0.1-2.aix5.3.ppc.rpm
-
-```
-
-LMDB and mcpp must be built from sources, as described below. 
-
-### Build Tools
-
-You need GNU make (gmake) to build Ice:
-```
-# As root
-rpm -i ftp://public.dhe.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/make/make-4.1-2.aix6.1.ppc.rpm
-```
-
-The preferred way to retrieve the Ice and mcpp source distributions is with
-git. A RPM for git is available from [bullfreeware.com][2].
-
-### Building mcpp from Sources
-
-If building 64-bit binaries, set `OBJECT_MODE` to 64:
-```
-export OBJECT_MODE=64
-```
-Otherwise, leave `OBJECT_MODE` unset.
-
-Then clone the zeroc-ice/mcpp repository and build with gmake:
-```
-git clone https://github.com/zeroc-ice/mcpp.git
-cd mcpp
-gmake
-```
-
-This build creates a static library, `lib/libmcpp.a`. `libmcpp.a` is used
-only when building Ice from sources, and does not need to be installed.
-
-### Building LMDB from Sources
-
-TBD
-
-## Building Ice
-
-### Clone zeroc-ice/ice
-
-```
-git clone https://github.com/zeroc-ice/ice.git
-cd ice
-```
-
-### Configure
-
-Edit `config/Make.rules` to establish your build configuration. The comments
-in the file provide more information.
-
-Make sure to set `LMDB_HOME` to your LMDB installation directory and 
-`MCPP_HOME` to your mcpp build directory (for example `$(HOME)/builds/mcpp`).
-
-### Build
-
-Use the gmake `-j` option to speed up the build:
-
-```
-cd cpp
-gmake -j8
-```
-
-This builds the Ice core libraries, services, and tests.
-
-### Build configurations and platforms
-
-The C++ source tree supports multiple build configurations and platforms. To
-see the supported configurations and platforms:
-
-    gmake print V=supported-configs
-    gmake print V=supported-platforms
-
-To build all the supported configurations and platforms:
-
-    gmake CONFIGS=all PLATFORMS=all
-
-### C++11 mapping
-
-The C++ source tree supports two different language mappings (C++98 and C++11),
-the default build uses the C++98 mapping. The C++11 mapping is a new mapping
-that uses the new language features.
-
-To build the new C++11 mapping, use build configurations which are prefixed with
-`cpp11`, for example:
-
-    gmake CONFIGS=cpp11-shared
-
-### Install
-
-Simply run `gmake install`. This will install Ice in the directory specified by
-the `<prefix>` variable in `config/Make.rules`.
-
-By default, all Ice binaries embed the library path `prefix/lib:/usr/lib`.
-
-After installation, make sure that the `prefix/bin` directory is in your `PATH`.
-
-### Run the Test Suite (Optional)
-
-Python is required to run the test suite. You can install Python as follows:
-```
-# As root
-rpm -i ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/python/python-2.7.10-1.aix6.1.ppc.rpm
-rpm -i ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/python/python-tools-2.7.10-1.aix6.1.ppc.rpm
-rpm -i ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/python/python-devel-2.7.10-1.aix6.1.ppc.rpm
-```
-
-Additionally, the Glacier2 tests require the Python module `passlib`, available
-from the Python Package Index:
-```
-# As root
-wget https://bootstrap.pypa.io/get-pip.py
-python get-pip.py
-export PATH=/opt/freeware/bin:$PATH
-pip install passlib
-```
-
-Then run the test suite with:
-```
-python allTests.py
-```
-
-If everything worked out, you should see lots of `ok` messages. In case of a
-failure, the tests abort with `failed`.
-
-[1]: http://www-03.ibm.com/systems/power/software/aix/linux
-[2]: http://www.bullfreeware.com
diff --git a/cpp/BuildInstructionsLinux.md b/cpp/BuildInstructionsLinux.md
index 36b5e658737..2a656abda77 100644
--- a/cpp/BuildInstructionsLinux.md
+++ b/cpp/BuildInstructionsLinux.md
@@ -53,14 +53,15 @@ that do not include them. You can install these packages as shown below:
 
 ## Building Ice
 
+From the top-level source directory, edit `config/Make.rules` to establish your
+build configuration. The comments in the file provide more information. Pay
+particular attention to the variables that define the locations of the third-party
+libraries.
+
 In a command window, change to the `cpp` subdirectory:
 
     $ cd cpp
 
-Edit `config/Make.rules` to establish your build configuration. The comments in
-the file provide more information. Pay particular attention to the variables
-that define the locations of the third-party libraries.
-
 Now you're ready to build Ice:
 
     $ make
@@ -81,11 +82,11 @@ To build all the supported configurations and platforms:
 
 ### C++11 mapping
 
-The C++ source tree supports two different language mappings (C++98 and C++11),
-the default build uses the C++98 mapping. The C++11 mapping is a new mapping
-that uses the new language features.
+The C++ source tree supports two different language mappings (C++98 and C++11).
+The default build uses the C++98 mapping. The C++11 mapping is a new mapping
+that uses new language features.
 
-To build the new C++11 mapping, use build configurations which are prefixed with
+To build the C++11 mapping, use build configurations that are prefixed with
 `cpp11`, for example:
 
     make CONFIGS=cpp11-shared
@@ -93,12 +94,12 @@ To build the new C++11 mapping, use build configurations which are prefixed with
 ## Installing a C++ Source Build
 
 Simply run `make install`. This will install Ice in the directory specified by
-the `<prefix>` variable in `config/Make.rules`.
+the `<prefix>` variable in `../config/Make.rules`.
 
 After installation, make sure that the `<prefix>/bin` directory is in your `PATH`.
 
 If you choose to not embed a `runpath` into executables at build time (see your
-build settings in `config/Make.rules`) or did not create a symbolic link from
+build settings in `../config/Make.rules`) or did not create a symbolic link from
 the `runpath` directory to the installation directory, you also need to add the
 library directory to your `LD_LIBRARY_PATH`.
 
@@ -116,8 +117,8 @@ When compiling Ice programs, you must pass the location of the `<prefix>/include
 directory to the compiler with the `-I` option, and the location of the library
 directory with the `-L` option. 
 
-If building a C++11 program, you must define `ICE_CPP11_MAPPING` macro during
-compilation with the `-D` option (`g++ -DICE_CPP11_MAPING`) and add
+If building a C++11 program, you must define the `ICE_CPP11_MAPPING` macro during
+compilation with the `-D` option (`g++ -DICE_CPP11_MAPPING`) and add
 the `++11` suffix to the library name when linking (such as `-lIce++11`).
 
 ## Running the Test Suite
@@ -135,7 +136,7 @@ This command is equivalent to:
 
     $ python allTests.py
     
-For C++11 mapping it also include the`--c++11` argument:
+For the C++11 mapping it also includes the `--c++11` argument:
 
     $ python allTests.py --c++11
 
diff --git a/cpp/BuildInstructionsMacOS.md b/cpp/BuildInstructionsMacOS.md
index ebecf058b12..c1f236a8fef 100644
--- a/cpp/BuildInstructionsMacOS.md
+++ b/cpp/BuildInstructionsMacOS.md
@@ -29,14 +29,15 @@ You can install LMDB and mcpp using [Homebrew][7]:
 
 ## Building Ice
 
+From the top-level source directory, edit `config/Make.rules` to establish your
+build configuration. The comments in the file provide more information. Pay
+particular attention to the variables that define the locations of the third-party
+libraries.
+
 In a command window, change to the `cpp` subdirectory:
 
     cd cpp
 
-Edit `config/Make.rules` to establish your build configuration. The comments in
-the file provide more information. Pay particular attention to the variables
-that define the locations of the third-party libraries.
-
 Now you're ready to build Ice:
 
     make
@@ -57,18 +58,18 @@ To build all the supported configurations and platforms:
 
 ### C++11 mapping
 
-The C++ source tree supports two different language mappings (C++98 and C++11),
-the default build uses the C++98 mapping. The C++11 mapping is a new mapping
-that uses the new language features.
+The C++ source tree supports two different language mappings (C++98 and C++11).
+The default build uses the C++98 mapping. The C++11 mapping is a new mapping
+that uses new language features.
 
-To build the new C++11 mapping, use build configurations which are prefixed with
+To build the C++11 mapping, use build configurations that are prefixed with
 `cpp11`, for example:
 
     make CONFIGS=cpp11-shared
 
 ### Ice Xcode SDK
 
-The build system supports building Xcode SDKs for Ice. These SDKs allow to
+The build system supports building Xcode SDKs for Ice. These SDKs allow you to
 easily develop Ice applications with Xcode. To build Xcode SDKs, use the
 `xcodesdk` configurations:
 
@@ -80,13 +81,13 @@ The Xcode SDKs are built into `ice/IceSDK`.
 ## Installing a C++ Source Build
 
 Simply run `make install`. This will install Ice in the directory specified by
-the `prefix` variable in `config/Make.rules`.
+the `prefix` variable in `../config/Make.rules`.
 
 After installation, make sure that the `<prefix>/bin` directory is in your
 `PATH`.
 
 If you choose to not embed a `runpath` into executables at build time (see your
-build settings in `config/Make.rules`) or did not create a symbolic link from
+build settings in `../config/Make.rules`) or did not create a symbolic link from
 the `runpath` directory to the installation directory, you also need to add the
 library directory to your `DYLD_LIBRARY_PATH`.
 
@@ -96,7 +97,7 @@ location of the library directory with the `-L` option.
 
 If building a C++11 program, you must define the `ICE_CPP11_MAPPING` macro
 during compilation with the `-D` option (for example `clang++
--DICE_CPP11_MAPING`) and add the `++11` suffix to the library name when linking
+-DICE_CPP11_MAPPING`) and add the `++11` suffix to the library name when linking
 (such as `-lIce++11`).
 
 The Ice Xcode SDKs are installed in `<prefix>/lib/IceSDK`.
@@ -116,14 +117,14 @@ This command is equivalent to:
 
     python allTests.py
 
-For C++11 mapping it also include the`--c++11` argument:
+For the C++11 mapping it also includes the `--c++11` argument:
 
     $ python allTests.py --c++11
 
 If everything worked out, you should see lots of `ok` messages. In case of a
 failure, the tests abort with `failed`.
 
-[1]: https://doc.zeroc.com/display/Ice37/Using+the+OS+X+Binary+Distribution
+[1]: https://doc.zeroc.com/display/Ice37/Using+the+macOS+Binary+Distribution
 [2]: https://doc.zeroc.com/display/Ice37/Supported+Platforms+for+Ice+3.7.0
 [3]: http://bzip.org
 [4]: http://expat.sourceforge.net
diff --git a/cpp/BuildInstructionsWindows.md b/cpp/BuildInstructionsWindows.md
index 4172f8e2a77..3729a555508 100644
--- a/cpp/BuildInstructionsWindows.md
+++ b/cpp/BuildInstructionsWindows.md
@@ -1,6 +1,6 @@
 # Building Ice for C++ on Windows
 
-This file describes how to build Ice for C++ from sources on Windows, and how
+This file describes how to build Ice for C++ from sources on Windows and how
 to test the resulting build.
 
 ZeroC provides [Ice binary distributions][1] for various platforms and compilers,
@@ -27,9 +27,9 @@ Ice has dependencies on a number of third-party libraries:
  - [mcpp][6] 2.7.2 (with patches)
 
 You do not need to build these packages yourself, as ZeroC supplies
-[NuGet][7] packages for all these third party dependencies.
+[NuGet][7] packages for all of these third-party dependencies.
 
-The Ice build system for Windows downloads and installs the NuGet command line
+The Ice build system for Windows downloads and installs the NuGet command-line
 executable and these NuGet packages when you build Ice for C++. The third-party
 packages are installed in the ``ice/cpp/msbuild/packages`` folder.
 
@@ -45,51 +45,47 @@ Using the first Command Prompt produces `Win32` binaries by default, while
 the second Command Promt produces `x64` binaries by default.
 
 In the Command Prompt, change to the `cpp` subdirectory:
-```
+
     cd cpp
-```
 
 Now you're ready to build Ice:
-```
-    Msbuild msbuild\ice.proj
-```
+
+    msbuild msbuild\ice.proj
 
 This builds the Ice for C++ SDK and the Ice for C++ test suite, with 
 Release binaries for the default platform.
 
-Set the Msbuild `Configuration` property to `Debug` to build debug binaries
+Set the MSBuild `Configuration` property to `Debug` to build debug binaries
 instead:
-```
-     MSbuild msbuild\ice.proj /p:Configuration=Debug
-```
+
+     msbuild msbuild\ice.proj /p:Configuration=Debug
 
 The `Configuration` property may be set to `Debug` or `Release`.
 
-Set the Msbuild `Platform` property to `Win32` or `x64` to build binaries
+Set the MSBuild `Platform` property to `Win32` or `x64` to build binaries
 for a specific platform, for example:
-```
-    MSbuild msbuild\ice.proj /p:Configuration=Debug /p:Platform=x64
-```
+
+    msbuild msbuild\ice.proj /p:Configuration=Debug /p:Platform=x64
 
 You can also skip the build of the test suite with the `BuildDist` target:
-```
-    MSbuild msbuild\ice.proj /t:BuildDist /p:Platform=x64
-```
+
+    msbuild msbuild\ice.proj /t:BuildDist /p:Platform=x64
 
 If you want to build all supported platforms and configurations at once, use:
-```
-    MSbuild msbuild\ice.proj /p:BuildAllConfigurations=yes
-```
+
+    msbuild msbuild\ice.proj /p:BuildAllConfigurations=yes
 
 You can also sign the Ice binaries with Authenticode, by setting the following
 environment variables:
  - SIGN_CERTIFICATE to your Authenticode certificate
  - SIGN_PASSWORD to the certificate password
- 
-You can also build the test suite against the NuGet packages with:
-```
-    MSbuild msbuild\ice.proj /p:ICE_BIN_DIST=all
-```
+
+If you want to run the test suite without building the entire source base, use this
+command:
+
+    msbuild msbuild\ice.proj /p:ICE_BIN_DIST=all
+
+The build will automatically install ZeroC's official Ice binary NuGet packages if necessary.
 
 ## Building Ice for UWP
 
@@ -97,39 +93,33 @@ The steps are the same as for Building Ice for C++ above, except you must also u
 `UWP` target.
 
 To build Ice for UWP:
-```
-    Msbuild msbuild\ice.proj /t:UWPBuild
-```
+
+    msbuild msbuild\ice.proj /t:UWPBuild
 
 To skip the building of the test suite:
-```
-    MSbuild msbuild\ice.proj /t:UWPBuildDist
-```
+
+    msbuild msbuild\ice.proj /t:UWPBuildDist
 
 To build all configurations:
-```
-    MSbuild msbuild\ice.proj /t:UWPBuildDist /p:BuildAllConfigurations=yes
-```
 
-To build the test suite against the NuGet packages:
-```
-    MSbuild msbuild\ice.proj /t:UWPBuild /p:ICE_BIN_DIST=all
-```
+    msbuild msbuild\ice.proj /t:UWPBuildDist /p:BuildAllConfigurations=yes
+
+To run the test suite without building the entire source base:
+
+    msbuild msbuild\ice.proj /t:UWPBuild /p:ICE_BIN_DIST=all
 
 ## NuGet packages
 
 You can create a NuGet package with the following command:
-```
-    MSbuild msbuild\ice.proj /t:NuGetPack /p:BuildAllConfigurations=yes
-```
+
+    msbuild msbuild\ice.proj /t:NuGetPack /p:BuildAllConfigurations=yes
 
 This creates `zeroc.ice.v120\zeroc.ice.v120.nupkg`, `zeroc.ice.v140\zeroc.ice.v140.nupkg`
-or `zeroc.ice.v141\zeroc.ice.v141.nupkg` depending of the compiler you are using.
+or `zeroc.ice.v141\zeroc.ice.v141.nupkg` depending on the compiler you are using.
 
 To create UWP NuGet packages, use the `UWPNuGetPack` target instead:
-```
-    MSbuild msbuild\ice.proj /t:UWPNuGetPack /p:BuildAllConfigurations=yes
-```
+
+    msbuild msbuild\ice.proj /t:UWPNuGetPack /p:BuildAllConfigurations=yes
 
 This creates `zeroc.ice.uwp\zeroc.ice.uwp.nupkg`, `zeroc.ice.uwp.x64\zeroc.ice.uwp.x64.nupkg` 
 and `zeroc.ice.uwp.x86\zeroc.ice.uwp.x86.nupkg`.
@@ -138,19 +128,16 @@ and `zeroc.ice.uwp.x86\zeroc.ice.uwp.x86.nupkg`.
 
 Python is required to run the test suite. Additionally, the Glacier2 tests
 require the Python module `passlib`, which you can install with the command:
-```
+
     pip install passlib
-```
 
 After a successful source build, you can run the tests as follows:
-```
+
     python allTests.py
-```
 
-For C++11 mapping you need to use the `Cpp11-Debug` or `Cpp11-Release` configuration:
-```
-    python allTests.py --config Cpp11-Debug
-```
+For the C++11 mapping you need to use the `Cpp11-Debug` or `Cpp11-Release` configuration:
+
+    $ python allTests.py --config Cpp11-Debug
 
 If everything worked out, you should see lots of `ok` messages. In case of a
 failure, the tests abort with `failed`.
@@ -158,14 +145,13 @@ failure, the tests abort with `failed`.
 ## Running the Universal Windows Platform Test Suite
 
 In Visual Studio 2015, open the solution file:
-```
+
     cpp\msbuild\ice.testuwp.sln
-```
 
 Now select the configuration that matches the settings that you used to build
 Ice for UWP.
 
-To run the UWP Test suite application you can deploy the application using "Deploy
+To run the UWP Test suite application, you can deploy the application using "Deploy
 Solution" in the "Build" menu. Once deployed, you can start the application from
 the Start Menu by clicking the "Ice Test Suite" icon.
 
@@ -173,17 +159,16 @@ In the test suite application, selecting "uwp" for the Server field allows you
 to run tests with TCP and WS protocols supported by the UWP server side.
 
 You can also use C++, C# or Java servers to run the tests, which allows you to
-use  additional SSL and WSS protocols.
+use additional SSL and WSS protocols.
 
 To use servers from C++, C# or Java language mappings, you need to build the
 tests for the desired language mapping.
 
 The test controller server is implemented in Java. Refer to the build
-instructions in java subdirectory for information on building the test
+instructions in the java subdirectory for information on building the test
 controller. Use the following command to start the test controller:
-```
+
     python scripts/TestController.py
-```
 
 In the "Ice Test Suite" Windows Store application, select the Server language
 mapping and Protocol you want to use.