From 125316f2a69edb095264e0e093a295c872afd2ff Mon Sep 17 00:00:00 2001 From: Brad Chase Date: Thu, 25 Jan 2018 12:08:36 -0500 Subject: [PATCH] Update Visual Studio build instructions --- Builds/CMake/CMakeFuncs.cmake | 19 +- .../CMakeSettings-example.json | 45 +++ Builds/VisualStudio2017/README.md | 263 ++++++++++++++++++ 3 files changed, 324 insertions(+), 3 deletions(-) create mode 100644 Builds/VisualStudio2017/CMakeSettings-example.json create mode 100644 Builds/VisualStudio2017/README.md diff --git a/Builds/CMake/CMakeFuncs.cmake b/Builds/CMake/CMakeFuncs.cmake index 37cbef16a..2dd0a3590 100644 --- a/Builds/CMake/CMakeFuncs.cmake +++ b/Builds/CMake/CMakeFuncs.cmake @@ -357,12 +357,21 @@ macro(use_boost) if(NOT Boost_FOUND) message(WARNING "Boost directory found, but not all components. May not be able to build.") endif() + + if(MSVC14) + # VS2017 with boost <= 1.66.0 requires a flag to suppress warnings + if(NOT Boost_VERSION VERSION_GREATER 106600) + add_definitions(-DBOOST_CONFIG_SUPPRESS_OUTDATED_MESSAGE) + endif() + endif() + if (is_xcode) include_directories(BEFORE ${Boost_INCLUDE_DIRS}) append_flags(CMAKE_CXX_FLAGS --system-header-prefix="boost/") else() include_directories(SYSTEM ${Boost_INCLUDE_DIRS}) endif() + link_directories(${Boost_LIBRARY_DIRS}) else() message(FATAL_ERROR "Boost not found") @@ -388,9 +397,13 @@ macro(use_openssl openssl_min) endif() if (WIN32) - if (DEFINED ENV{OPENSSL_ROOT}) - include_directories($ENV{OPENSSL_ROOT}/include) - link_directories($ENV{OPENSSL_ROOT}/lib) + if ((NOT DEFINED OPENSSL_ROOT) AND (DEFINED ENV{OPENSSL_ROOT})) + set(OPENSSL_ROOT $ENV{OPENSSL_ROOT}) + endif() + file(TO_CMAKE_PATH "${OPENSSL_ROOT}" OPENSSL_ROOT) + if (DEFINED OPENSSL_ROOT) + include_directories(${OPENSSL_ROOT}/include) + link_directories(${OPENSSL_ROOT}/lib) endif() else() if (static) diff --git a/Builds/VisualStudio2017/CMakeSettings-example.json b/Builds/VisualStudio2017/CMakeSettings-example.json new file mode 100644 index 000000000..b2889ddf5 --- /dev/null +++ b/Builds/VisualStudio2017/CMakeSettings-example.json @@ -0,0 +1,45 @@ +{ + // See https://go.microsoft.com//fwlink//?linkid=834763 for more information about this file. + "configurations": [ + { + "name": "x64-Debug", + "generator": "Visual Studio 15 2017 Win64", + "configurationType": "Debug", + "inheritEnvironments": [ "msvc_x64_x64" ], + "buildRoot": "${thisFileDir}\\build\\${name}", + "cmakeCommandArgs": "", + "buildCommandArgs": "-v:minimal", + "ctestCommandArgs": "", + "variables": [ + { + "name": "BOOST_ROOT", + "value": "C:\\lib\\boost" + }, + { + "name": "OPENSSL_ROOT", + "value": "C:\\lib\\OpenSSL-Win64" + } + ] + }, + { + "name": "x64-Release", + "generator": "Visual Studio 15 2017 Win64", + "configurationType": "Release", + "inheritEnvironments": [ "msvc_x64_x64" ], + "buildRoot": "${thisFileDir}\\build\\${name}", + "cmakeCommandArgs": "", + "buildCommandArgs": "-v:minimal", + "ctestCommandArgs": "", + "variables": [ + { + "name": "BOOST_ROOT", + "value": "C:\\lib\\boost" + }, + { + "name": "OPENSSL_ROOT", + "value": "C:\\lib\\OpenSSL-Win64" + } + ] + } + ] +} diff --git a/Builds/VisualStudio2017/README.md b/Builds/VisualStudio2017/README.md new file mode 100644 index 000000000..38c320363 --- /dev/null +++ b/Builds/VisualStudio2017/README.md @@ -0,0 +1,263 @@ +# 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| +| [Google Protocol Buffers Compiler](README.md#install-google-protocol-buffers-compiler) | 2.5.1| +| [OpenSSL Library](README.md#install-openssl) | 1.0.2n | +| [Boost library](README.md#build-boost) | 1.66.0 | +| [CMake for Windows](README.md#optional-install-cmake-for-windows)* | 3.10.2 | + +\* 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 Google Protocol Buffers Compiler + +Building rippled requires **protoc.exe** version 2. Version 3 is not currently +supported.. 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 +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 + +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.66.0, +which will unpack into a directory named `boost_1_66_0`. We recommended either +renaming this directory to `boost`, or creating a junction link `mklink /J boost +boost_1_66_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 --toolset=msvc-14.1 address-model=64 architecture=x86 link=static threading=multi runtime-link=shared,static stage +``` + +where you should replace `` 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 `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(_classic).exe +``` +or +``` +.\build\x64-Debug\Debug\rippled(_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 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_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(_classic).exe +```` +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. +