From dcfe6a10a3de0dbbc2caefe388f726f694ab0d56 Mon Sep 17 00:00:00 2001 From: justinr1234 Date: Thu, 19 Jan 2023 17:01:11 -0600 Subject: [PATCH 1/3] docs: Update Windows build instructions --- .gitignore | 2 ++ BUILD.md | 68 +++++++++++++++----------------------- Builds/windows/install.ps1 | 15 +++++++++ cfg/rippled-example.cfg | 2 +- 4 files changed, 45 insertions(+), 42 deletions(-) create mode 100644 Builds/windows/install.ps1 diff --git a/.gitignore b/.gitignore index 5c8b2443700..93ccf913ca9 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ bin/boostbook_catalog.xml bin/config.log bin/project-cache.jam +.build # Ignore vim swap files. *.swp @@ -102,6 +103,7 @@ Builds/VisualStudio2015/*.sdf *.pdb .vs/ CMakeSettings.json +CMakeUserPresets.json compile_commands.json .clangd packages diff --git a/BUILD.md b/BUILD.md index 7bb2d4d8ebb..34375575880 100644 --- a/BUILD.md +++ b/BUILD.md @@ -170,16 +170,12 @@ Until then, we advise Windows developers to use Visual Studio 2019. ## Prerequisites -To build this package, you will need Python (>= 3.7), -[Conan][] (>= 1.55), and [CMake][] (>= 3.16). - > **Warning** -> The commands in this document are not meant to be blindly copied and pasted. +> The commands in this document are guidelines which cannot always be successfully copy and pasted. > This document is written for multiple audiences, > meaning that your particular circumstances may require some commands and not > others. -> You should never run any commands without understanding what they do -> and why you are running them. +> It is recommended to fully understand what the following commands do before running them. > > These instructions assume a basic familiarity with Conan and CMake. > If you are unfamiliar with Conan, @@ -187,15 +183,30 @@ To build this package, you will need Python (>= 3.7), > at the beginning of this document, > or the official [Getting Started][3] walkthrough. +### All Platforms + +To build this package, you will need [Python][] (>= 3.7), +[Conan][] (>= 1.52), and [CMake][] (>= 3.16). +If you are unfamiliar with Conan, +there is a crash course at the end of this document. + [Conan]: https://conan.io/downloads.html [CMake]: https://cmake.org/download/ +[Python]: https://www.python.org/downloads/ + +If you've never used Conan before, use autodetect to setup a default profile: + +``` +conan profile new default --detect +``` You'll need to compile in the C++20 dialect: ``` -conan profile update settings.compiler.cppstd=20 default +conan profile update settings.cppstd=20 default ``` +### Linux Linux developers will commonly have a default Conan [profile][] that compiles with GCC and links with libstdc++. If you are linking with libstdc++ (see profile setting `compiler.libcxx`), @@ -205,6 +216,12 @@ then you will need to choose the `libstdc++11` ABI: conan profile update settings.compiler.libcxx=libstdc++11 default ``` +### Windows + +[Visual Studio 2019]: https://visualstudio.microsoft.com/vs/older-downloads/ + +It is recommended to utilize PowerShell in administrator mode to run commands. See an [example script](./Builds/windows/install.ps1) that utilizes the [chocolately](https://chocolatey.org/) package manager. + We find it necessary to use the x64 native build tools on Windows. An easy way to do that is to run the shortcut "x64 Native Tools Command Prompt" for the version of Visual Studio that you have installed. @@ -216,6 +233,8 @@ architecture: conan profile update settings.arch=x86_64 default ``` +### A note about multiple compilers + If you have multiple compilers installed on your platform, then you'll need to make sure that Conan and CMake select the one you want to use. @@ -235,40 +254,7 @@ conan profile update env.CC= default conan profile update env.CXX= default ``` - -## How to build and test - -Let's start with a couple of examples of common workflows. -The first is for a single-configuration generator (e.g. Unix Makefiles) on -Linux or MacOS: - -``` -conan export external/rocksdb -mkdir .build -cd .build -conan install .. --output-folder . --build missing --settings build_type=Release -cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release .. -cmake --build . -./rippled --unittest -``` - -The second is for a multi-configuration generator (e.g. Visual Studio) on -Windows: - -``` -conan export external/rocksdb -mkdir .build -cd .build -conan install .. --output-folder . --build missing --settings build_type=Release --settings compiler.runtime=MT -conan install .. --output-folder . --build missing --settings build_type=Debug --settings compiler.runtime=MTd -cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake .. -cmake --build . --config Release -cmake --build . --config Debug -./Release/rippled --unittest -./Debug/rippled --unittest -``` - -Now to explain the individual steps in each example: +## Explanation of build steps 1. Export our [Conan recipe for RocksDB](./external/rocksdb). diff --git a/Builds/windows/install.ps1 b/Builds/windows/install.ps1 new file mode 100644 index 00000000000..dbf17265661 --- /dev/null +++ b/Builds/windows/install.ps1 @@ -0,0 +1,15 @@ +## To run these commands as a script, execution policy must be relaxed: +#set-executionpolicy remotesigned +## If running in admin powershell simply run: +Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) +choco install -y python3 +choco install -y git conan +choco install -y cmake.install --installargs '"ADD_CMAKE_TO_PATH=System"' + +## These workloads depend on and will install visualstudiobuildtools +choco install -y visualstudio2022-workload-vctools visualstudio2019-workload-vctools +## and for the IDEs *Be prepared to wait!* +choco install -y visualstudio2019community +choco install -y visualstudio2019-workload-nativedesktop +choco install -y visualstudio2022community +choco install -y visualstudio2022-workload-nativedesktop \ No newline at end of file diff --git a/cfg/rippled-example.cfg b/cfg/rippled-example.cfg index fda1671e416..e92131f813c 100644 --- a/cfg/rippled-example.cfg +++ b/cfg/rippled-example.cfg @@ -1617,7 +1617,7 @@ admin = 127.0.0.1 protocol = http [port_peer] -port = 51235 +port = 2459 ip = 0.0.0.0 # alternatively, to accept connections on IPv4 + IPv6, use: #ip = :: From b21bbe2c8ad50a296138ebef67d29aee08b3e1ee Mon Sep 17 00:00:00 2001 From: Long Le Date: Fri, 20 Jan 2023 19:01:25 +0100 Subject: [PATCH 2/3] Update build instructions for Visual Studio 2019 --- Builds/VisualStudio2019/README.md | 64 +++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/Builds/VisualStudio2019/README.md b/Builds/VisualStudio2019/README.md index e369eac6775..67d7b46a89e 100644 --- a/Builds/VisualStudio2019/README.md +++ b/Builds/VisualStudio2019/README.md @@ -6,6 +6,12 @@ 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. +While there are several options for building `rippled` on Windows, we recommend using +[Chocolatey, Conan, CMake and Visual Studio](README.md#build-using-chocolatey-conan-cmake-and-visual-studio-recommended). +If using this option, you can skip the section [Install Software](README.md#install-software) +because Conan automatically installs all dependencies for `rippled`. + + ## Prerequisites To clone the source code repository, create branches for inspection or @@ -233,6 +239,64 @@ or ``` These paths are relative to your cloned git repository. +# Build using Chocolatey, Conan, CMake and Visual Studio (Recommended) + +Open a PowerShell as Administrator and execute a +[setup script](https://gist.github.com/ximinez/1678229f97831c602a9a42a1ea03c9c4). +Alternatively, [install Chocolatey](https://chocolatey.org/install) and run the following commands +in a PowerShell as Administrator: + +```powershell +choco install -y git conan +choco install -y cmake.install --installargs '"ADD_CMAKE_TO_PATH=System"' +choco install -y visualstudio2019-workload-vctools +choco install -y visualstudio2019community +choco install -y visualstudio2019-workload-nativedesktop + +``` + + +If you do not have a Conan profile already, create a default profile: + +```powershell +conan profile new default --detect +``` + +Set Conan options to compile in the C++20 dialect and for the x64 architecture: + +```powershell +conan profile update settings.compiler.cppstd=20 default +conan profile update settings.arch=x86_64 default +``` + +Clone the `rippled` repository: +```powershell +git clone git@github.com:XRPLF/rippled.git +cd rippled +``` + +Run the following commands to create a release build: +```powershell +conan export external/rocksdb +mkdir .build +cd .build +conan install .. --output-folder . --build missing --settings build_type=Release --settings compiler.runtime=MT +cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake .. +cmake --build . --config Release +./Release/rippled --unittest +``` + +Alternatively, run the following commands to create a debug build: +```powershell +conan export external/rocksdb +mkdir .build +cd .build +conan install .. --output-folder . --build missing --settings build_type=Debug --settings compiler.runtime=MTd +cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake .. +cmake --build . --config Debug +./Debug/rippled --unittest +``` + # Unity/No-Unity Builds The rippled build system defaults to using From edeff7ef67bcf6ccc3bae2251654b09135aa505d Mon Sep 17 00:00:00 2001 From: Long Le Date: Wed, 15 Feb 2023 17:17:58 +0100 Subject: [PATCH 3/3] Address review --- BUILD.md | 41 ++++++++++++++++++++++++++++--- Builds/VisualStudio2019/README.md | 15 ++++++----- 2 files changed, 46 insertions(+), 10 deletions(-) diff --git a/BUILD.md b/BUILD.md index 34375575880..faf76021b0b 100644 --- a/BUILD.md +++ b/BUILD.md @@ -171,7 +171,7 @@ Until then, we advise Windows developers to use Visual Studio 2019. ## Prerequisites > **Warning** -> The commands in this document are guidelines which cannot always be successfully copy and pasted. +> The commands in this document are examples which cannot always be successfully copy-and-pasted. > This document is written for multiple audiences, > meaning that your particular circumstances may require some commands and not > others. @@ -186,9 +186,9 @@ Until then, we advise Windows developers to use Visual Studio 2019. ### All Platforms To build this package, you will need [Python][] (>= 3.7), -[Conan][] (>= 1.52), and [CMake][] (>= 3.16). +[Conan][] (>= 1.58), and [CMake][] (>= 3.16). If you are unfamiliar with Conan, -there is a crash course at the end of this document. +there is a crash course at the beginning of this document. [Conan]: https://conan.io/downloads.html [CMake]: https://cmake.org/download/ @@ -203,7 +203,7 @@ conan profile new default --detect You'll need to compile in the C++20 dialect: ``` -conan profile update settings.cppstd=20 default +conan profile update settings.compiler.cppstd=20 default ``` ### Linux @@ -254,6 +254,39 @@ conan profile update env.CC= default conan profile update env.CXX= default ``` + +## How to build and test + +Let's start with a couple of examples of common workflows. +The first is for a single-configuration generator (e.g. Unix Makefiles) on +Linux or MacOS: + +``` +conan export external/rocksdb +mkdir .build +cd .build +conan install .. --output-folder . --build missing --settings build_type=Release +cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release .. +cmake --build . +./rippled --unittest +``` + +The second is for a multi-configuration generator (e.g. Visual Studio) on +Windows: + +``` +conan export external/rocksdb +mkdir .build +cd .build +conan install .. --output-folder . --build missing --settings build_type=Release --settings compiler.runtime=MT +conan install .. --output-folder . --build missing --settings build_type=Debug --settings compiler.runtime=MTd +cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake .. +cmake --build . --config Release +cmake --build . --config Debug +./Release/rippled --unittest +./Debug/rippled --unittest +``` + ## Explanation of build steps 1. Export our [Conan recipe for RocksDB](./external/rocksdb). diff --git a/Builds/VisualStudio2019/README.md b/Builds/VisualStudio2019/README.md index 67d7b46a89e..2699f39a55d 100644 --- a/Builds/VisualStudio2019/README.md +++ b/Builds/VisualStudio2019/README.md @@ -6,10 +6,12 @@ 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. -While there are several options for building `rippled` on Windows, we recommend using -[Chocolatey, Conan, CMake and Visual Studio](README.md#build-using-chocolatey-conan-cmake-and-visual-studio-recommended). -If using this option, you can skip the section [Install Software](README.md#install-software) -because Conan automatically installs all dependencies for `rippled`. +While there are several options for building `rippled` on Windows, we recommend +using [Chocolatey, Conan, CMake and Visual +Studio](README.md#build-using-chocolatey-conan-cmake-and-visual-studio). +If using this option, you can skip the section [Install +Software](README.md#install-software) because Conan automatically installs all +dependencies for `rippled`. ## Prerequisites @@ -26,7 +28,8 @@ need these software components | [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 2019 and prefer generating dedicated project/solution files. +\* Only needed if not using the integrated CMake in VS 2019 and prefer +generating dedicated project/solution files. ## Install Software @@ -239,7 +242,7 @@ or ``` These paths are relative to your cloned git repository. -# Build using Chocolatey, Conan, CMake and Visual Studio (Recommended) +# Build using Chocolatey, Conan, CMake and Visual Studio Open a PowerShell as Administrator and execute a [setup script](https://gist.github.com/ximinez/1678229f97831c602a9a42a1ea03c9c4).