Update Visual Studio build instructions

Builds/VisualStudio2017/README.md

@@ -0,0 +1,260 @@
+# Visual Studio 2017 Build Instructions
+
+## Important
+
+We do not recommend Windows for rippled production use at this time. Currently,
+the Ubuntu platform has received the highest level of quality assurance,
+testing, and support. Additionally, 32-bit Windows versions are not supported.
+
+## Prerequisites
+
+To clone the source code repository, create branches for inspection or
+modification, build rippled under Visual Studio, and run the unit tests you will
+need these software components:
+
+* [Visual Studio 2017](README.md#install-visual-studio-2017)
+* [Git for Windows](README.md#install-git-for-windows)
+* [Google Protocol Buffers
+  Compiler](README.md#install-google-protocol-buffers-compiler)
+* [OpenSSL Library](README.md#install-openssl)
+* [Boost library](README.md#build-boost)
+* (Optional) [Cmake for Windows](README.md#optional-install-cmake-for-windows) -
+  Only needed if not using the integrated CMake in VS 2017.
+
+## Install Software
+
+### Install Visual Studio 2017
+
+If not already installed on your system, download your choice of installer from
+the [Visual Studio 2017
+Download](https://www.visualstudio.com/downloads/download-visual-studio-vs)
+page, run the installer, and follow the directions. **You may need to choose the
+`Desktop development with C++` workload to install all necessary C++ features.**
+
+Any version of Visual Studio 2017 may be used to build rippled. The **Visual
+Studio 2017 Community** edition is available free of charge (see [the product
+page](https://www.visualstudio.com/products/visual-studio-community-vs) for
+licensing details), while paid editions may be used for an free initial trial
+period.
+
+As of this writing, the latest version of Visual Studio 2017 for Windows is
+15.5.4.
+
+### Install Git for Windows
+
+Git is a distributed revision control system. The Windows version also provides
+the bash shell and many Windows versions of Unix commands. While there are other
+varieties of Git (such as TortoiseGit, which has a native Windows interface and
+integrates with the Explorer shell), we recommend installing [Git for
+Windows](https://git-scm.com/) since it provides a Unix-like command line
+environment useful for running shell scripts. Use of the bash shell under
+Windows is mandatory for running the unit tests.
+
+As of this writing, the latest version of Git for Windows is 2.16.1.
+
+### Install Google Protocol Buffers Compiler
+
+Building rippled requires **protoc.exe** version 2.5.1 or later. At your option
+you may build it yourself from the sources in the [Google Protocol
+Buffers](https://github.com/google/protobuf) repository, or you may download a
+[protoc.exe](https://ripple.github.io/Downloads/protoc/2.5.1/protoc.exe)
+([alternate
+link](https://github.com/ripple/Downloads/raw/gh-pages/protoc/2.5.1/protoc.exe))
+precompiled Windows executable from the [Ripple
+Organization](https://github.com/ripple).
+
+Either way, once you have the required version of **protoc.exe**, copy it into a
+standard location that is in your command line `%PATH%`.
+
+* **NOTE:** If you use an older version of the compiler, the build will fail
+  with errors related to a mismatch of the version of protocol buffer headers
+  versus the compiler. Likewise, if you use version 3 or newer, the build will
+  fail.
+
+### Install OpenSSL
+
+[Download OpenSSL.](http://slproweb.com/products/Win32OpenSSL.html) There will
+be four variants available:
+
+1. 64-bit. Use this if you are running 64-bit windows. As of this writing, the
+   link is called: "Win64 OpenSSL v1.0.2n".
+2. 64-bit light - Don't use this. It is missing files needed to build rippled.
+   As of this writing, the link is called: "Win64 OpenSSL v1.0.2n Light"
+
+Run the installer, and choose an appropriate location for your OpenSSL
+installation. In this guide we use `C:\lib\OpenSSL-Win64` as the destination
+location.
+
+You may be informed on running the installer that "Visual C++ 2008
+Redistributables" must first be installed first. If so, download it from the
+[same page](http://slproweb.com/products/Win32OpenSSL.html), again making sure
+to get the correct 32-/64-bit variant.
+
+* NOTE: Since rippled links statically to OpenSSL, it does not matter where the
+  OpenSSL .DLL files are placed, or what version they are. rippled does not use
+  or require any external .DLL files to run other than the standard operating
+  system ones.
+
+### Build Boost
+
+After [downloading boost](http://www.boost.org/users/download/) and unpacking it
+to `c:\lib\`, open a **Developer Command Prompt** for Visual Studio, change to
+the directory containing boost, then bootstrap the build tools:
+
+(As of this writing, the most recent version of boost is 1.66.0, which will
+unpack into a directory named `boost_1_66_0`. For higher versions of boost,
+adjust the directories provided in these examples as appropriate.)
+
+```powershell
+cd C:\lib\boost_1_66_0
+bootstrap
+```
+
+The rippled application is linked statically to the standard runtimes and
+external dependencies on Windows, to ensure that the behavior of the executable
+is not affected by changes in outside files. Therefore, it is necessary to build
+the required boost static libraries using this command:
+
+```powershell
+bjam -j<Num Parallel> --toolset=msvc-14.1 address-model=64 architecture=x86 link=static threading=multi runtime-link=shared,static stage
+```
+
+where you should replace `<Num Parallel>` with the number of parallel
+invocations to use build, e.g. `bjam -j4 ...` would use up to 4 concurrent build
+shell commands for the build.
+
+Building the boost libraries may take considerable time. When the build process
+is completed, take note of both the reported compiler include paths and linker
+library paths as they will be required later.
+
+### (Optional) Install CMake for Windows
+
+[CMake](http://cmake.org) is a cross platform build system generator. Visual
+Studio 2017 includes an integrated version of CMake that avoids having to
+manually run CMake, but it is undergoing continuous improvement. Users that
+prefer to use standard Visual Studio project and solution files need to install
+a dedicated version of Cmake to generate them.  The latest version can be found
+at the [CMake download site](https://cmake.org/download/). It is recommended you
+select the install option to add CMake to your path.
+
+As of this writing, the latest version of CMake for windows is 3.10.2.
+
+## Clone the rippled repository
+
+If you are familiar with cloning github repositories, just follow your normal
+process and clone `[email protected]:ripple/rippled.git`. Otherwise follow this
+section for instructions.
+
+1. If you don't have a github account, sign up for one at
+   [github.com](https://github.com/).
+2. Make sure you have Github ssh keys. For help see
+   [generating-ssh-keys](https://help.github.com/articles/generating-ssh-keys).
+
+Open the "Git Bash" shell that was installed with "Git for Windows" in the step
+above. Navigate to the directory where you want to clone rippled (git bash uses
+`/c` for windows's `C:` and forward slash where windows uses backslash, so
+`C:\Users\joe\projs` would be `/c/Users/joe/projs` in git bash). Now clone the
+repository and optionally switch to the *master* branch. Type the following at
+the bash prompt:
+
+```powershell
+git clone [email protected]:ripple/rippled.git
+cd rippled
+```
+If you receive an error about not having the "correct access rights" make sure
+you have Github ssh keys, as described above.
+
+For a stable release, choose the `master` branch or one of the tagged releases
+listed on [rippled's GitHub page](https://github.com/ripple/rippled/releases). 
+
+```
+git checkout master
+```
+
+To test the latest release candidate, choose the `release` branch.
+
+```
+git checkout release
+```
+
+If you are doing development work and want the latest set of untested features,
+you can consider using the `develop` branch instead.
+
+```
+git checkout develop
+```
+
+# Build using Visual Studio integrated CMake
+
+In Visual Studio 2017, Microsoft added [integrated IDE support for
+cmake](https://blogs.msdn.microsoft.com/vcblog/2016/10/05/cmake-support-in-visual-studio/).
+To begin, simply:
+
+1. Launch Visual Studio and choose **File | Open | Folder**, navigating to the
+   cloned rippled folder.
+2. Right-click on `CMakeLists.txt` in the **Solution Explorer - Folder View** to
+   generate a `CMakeSettings.json` file. A sample settings file is provided
+   here. Customize the settings for `BOOST_ROOT`, `OPENSSL_ROOT` to match the
+   install paths if they differ from those in the file.
+4. Select either the `x64-Release` or `x64-Debug` configuration from the
+   **Project Setings** drop-down. This should invoke the built-in CMake project
+   generator. If not, you can right-click on the `CMakeLists.txt` file and
+   choose **Cache | Generate Cache**.
+5. Select either the `rippled.exe` (unity) or `rippled_classic.exe` (non-unity)
+   option in the **Select Startup Item** drop-down. This will be the target
+   built when you press F7. Alternatively, you can choose a target to build from
+   the top-level **CMake | Build** menu. Note that at this time, there are other
+   targets listed that come from third party visual studio files embedded in the
+   rippled repo, e.g. `datagen.vcxproj`. Please ignore them.
+
+For details on configuring debugging sessions or further customization of CMake,
+please refer to the [CMake tools for VS
+documentation](https://docs.microsoft.com/en-us/cpp/ide/cmake-tools-for-visual-cpp).
+
+If using the provided `CMakeSettings.json` file, the executable will be in
+```
+.\build\x64-Release\Release\rippled(_classic).exe
+```
+or
+```
+.\build\x64-Debug\Debug\rippled.exe(_classic).exe
+```
+where these paths are relative to your cloned git repository.
+
+# Build using stand-alone CMake
+
+This requires having installed [Cmake for
+Windows](README.md#optional-install-cmake-for-windows). We do not recommend
+mixing this method with the integrated CMake method for the same repository
+clone. Assuming you included to add the cmake executable folder to your path,
+execute the following commands within your `rippled` cloned repository:
+
+```
+mkdir build\cmake
+cd build\cmake
+cmake ..\.. -G"Visual Studio 15 2017 Win64" -DBOOST_ROOT="C:\lib\boost_1_66_0" -DOPENSSL_ROOT="C:\lib\OpenSSL-Win64"
+```
+Now launch Visual Studio 2017 and select **File | Open | Project/Solution**.
+Navigate to the `build\cmake` folder created above and select the `rippled.sln`
+file. You can then choose whether to build the `Debug` or `Release` solution
+configuration. Within the **Solution Explorer**, selected either the `rippled`
+(unity build) project or the `rippled_classic` (non-unity) project, and
+right-click to build.
+
+The executable will be in 
+```
+.\build\cmake\Release\rippled(_classic).exe
+```
+ or
+````
+.\build\cmake\Debug\rippled.exe(_classic)
+````
+where these paths are relative to your cloned git repository.
+
+# Unit Test (Recommended)
+
+`rippled` builds a set of unit tests into the server executable. To run these
+unit tests after building, pass the `--unittest` option to the compiled
+`rippled` executable. The executable will exit with summary info after running
+the unit tests.
+