xahaud/Builds/VisualStudio2017/README.md

# 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

| Component | Minimum Recommended Version |
|-----------|-----------------------|
| [Visual Studio 2017](README.md#install-visual-studio-2017)| 15.5.4 |
| [Git for Windows](README.md#install-git-for-windows)| 2.16.1 |
| [OpenSSL Library](README.md#install-openssl) | 1.0.2n |
| [Boost library](README.md#build-boost) | 1.70.0 |
| [CMake for Windows](README.md#optional-install-cmake-for-windows)* | 3.12 |

\* Only needed if not using the integrated CMake in VS 2017 and prefer generating dedicated project/solution files.

## 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 initial free-trial
period.

### 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.

### Install OpenSSL

[Download OpenSSL.](http://slproweb.com/products/Win32OpenSSL.html) There will
four `Win64` bit variants available, you want the non-light `v1.0` line. As of
this writing, you **should** select

* Win64 OpenSSL v1.0.2n. 

and should **not** select

* Win64 OpenSSL v1.0.2n light
* Win64 OpenSSL v1.1.0g
* Win64 OpenSSL v1.1.0g 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

Boost 1.70 or later is required.

After [downloading boost](http://www.boost.org/users/download/) and unpacking it
to `c:\lib`. As of this writing, the most recent version of boost is 1.70.0,
which will unpack into a directory named `boost_1_70_0`. We recommended either
renaming this directory to `boost`, or creating a junction link `mklink /J boost
boost_1_70_0`, so that you can more easily switch between versions.

Next, open **Developer Command Prompt** and type the following commands

```powershell
cd C:\lib\boost
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.

## Clone the rippled repository

If you are familiar with cloning github repositories, just follow your normal
process and clone `git@github.com: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 git@github.com: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](/Builds/VisualStudio2017/CMakeSettings-example.json). 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.exe
```
or
```
.\build\x64-Debug\Debug\rippled.exe
```
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 the cmake executable folder in 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_70_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.

The executable will be in 
```
.\build\cmake\Release\rippled.exe
```
or
```
.\build\cmake\Debug\rippled.exe
```
These paths are relative to your cloned git repository.

# Unity/No-Unity Builds

The rippled build system defaults to using [unity source files](http://onqtam.com/programming/2018-07-07-unity-builds/)
to improve build times. In some cases it might be desirable to disable the unity build and compile
individual translation units. Here is how you can switch to a "no-unity" build configuration:

## Visual Studio Integrated CMake
 
Edit your `CmakeSettings.json` (described above) by adding `-Dunity=OFF` to the `cmakeCommandArgs` entry 
for each build configuration.

## Standalone CMake Builds

When running cmake to generate the Visual Studio project files, add `-Dunity=OFF` to the 
command line options passed to cmake.

**Note:** you will need to re-run the cmake configuration step anytime you want to switch between unity/no-unity builds.

# 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.