From d856d2f6aa0b835143c29402454464f1535753a4 Mon Sep 17 00:00:00 2001 From: Elliot Lee Date: Fri, 21 Apr 2023 10:48:41 -0700 Subject: [PATCH 1/5] Update BUILD.md - make it easier to find environment.md Make the instructions a bit easier to follow. Users on different platforms can look for their platform name to find relevant information. --- BUILD.md | 77 +++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 29 deletions(-) diff --git a/BUILD.md b/BUILD.md index cafde96b6a6..35c715cc11d 100644 --- a/BUILD.md +++ b/BUILD.md @@ -21,7 +21,7 @@ git checkout develop ``` -## Platforms +## Compilers rippled is written in the C++20 dialect and includes the `` header. The [minimum compiler versions][2] that can compile this dialect are given @@ -34,33 +34,42 @@ below: | Apple Clang | 13.1.6 | MSVC | 19.23 -We do not recommend Windows for rippled production use at this time. -As of January 2023, the Ubuntu platform has received the highest level of +## Prerequisites + +See [System Requirements](https://xrpl.org/system-requirements.html). + +rippled generally requires: +- git +- Python +- Conan +- CMake +- a C++ compiler + +### Linux + +The Ubuntu operating system has received the highest level of quality assurance, testing, and support. -Additionally, 32-bit Windows development is not supported. -Visual Studio 2022 is not yet supported. -This is because rippled is not compatible with [Boost][] versions 1.78 or 1.79, -but Conan cannot build Boost versions released earlier than them with VS 2022. -We expect that rippled will be compatible with Boost 1.80, which should be -released in August 2022. -Until then, we advise Windows developers to use Visual Studio 2019. +Here are [sample instructions for setting up a C++ development environment on Linux](./docs/build/environment.md#linux). -[Boost]: https://www.boost.org/ +### Mac +Many rippled engineers use macOS for development. -## Prerequisites +Here are [sample instructions for setting up a C++ development environment on macOS](./docs/build/environment.md#macos). + +### Windows + +Windows is not recommended for production use at this time. -> **Warning** -> These instructions assume you have a C++ development environment ready -> with Git, Python, Conan, CMake, and a C++ compiler. -> For help setting one up on Linux, macOS, or Windows, -> please see [our guide](./docs/build/environment.md). -> -> These instructions further assume a basic familiarity with Conan and CMake. -> If you are unfamiliar with Conan, -> then please read our [crash course](./docs/build/conan.md) -> or the official [Getting Started][3] walkthrough. +- Additionally, 32-bit Windows development is not supported. +- Visual Studio 2022 is not yet supported. + - rippled generally requires [Boost][] 1.77, which Conan cannot build with VS 2022. + - Until rippled is updated for compatibility with later versions of Boost, Windows developers may need to use Visual Studio 2019. + +[Boost]: https://www.boost.org/ + +## Conan profile To build this package, you will need Python (>= 3.7), [Conan][] (>= 1.55, < 2), and [CMake][] (>= 3.16). @@ -68,6 +77,12 @@ To build this package, you will need Python (>= 3.7), [Conan]: https://conan.io/downloads.html [CMake]: https://cmake.org/download/ +After you have a [C++ development environment](./docs/build/environment.md) ready with Git, Python, Conan, CMake, and a C++ compiler, you may need to set up your Conan profile. + +These instructions assume a basic familiarity with Conan and CMake. + +If you are unfamiliar with Conan, then please read [this crash course](./docs/build/conan.md) or the official [Getting Started][3] walkthrough. + You'll need at least one Conan profile: ``` @@ -80,7 +95,7 @@ You'll need to compile in the C++20 dialect: conan profile update settings.compiler.cppstd=20 default ``` -Linux developers will commonly have a default Conan [profile][] that compiles +**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`), then you will need to choose the `libstdc++11` ABI: @@ -89,7 +104,7 @@ then you will need to choose the `libstdc++11` ABI: conan profile update settings.compiler.libcxx=libstdc++11 default ``` -We find it necessary to use the x64 native build tools on Windows. +**Windows** developers may need to use the x64 native build tools. 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. @@ -100,16 +115,18 @@ architecture: conan profile update settings.arch=x86_64 default ``` -If you have multiple compilers installed on your platform, +**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. -This setting will set the correct variables (`CMAKE__COMPILER`) in the -generated CMake toolchain file: - +Update the `conf.tools.build:compiler_executables` setting in order to set the correct variables (`CMAKE__COMPILER`) in the +generated CMake toolchain file. +For example, on Ubuntu 20, you may have gcc at `/usr/bin/gcc` and g++ at `/usr/bin/g++`; if that is the case, you can select those compilers with: ``` -conan profile update 'conf.tools.build:compiler_executables={"c": "", "cpp": ""}' default +conan profile update 'conf.tools.build:compiler_executables={"c": "/usr/bin/gcc", "cpp": "/usr/bin/g++"}' default ``` +Replace `/usr/bin/gcc` and `/usr/bin/g++` with paths to the desired compilers. + It should choose the compiler for dependencies as well, but not all of them have a Conan recipe that respects this setting (yet). For the rest, you can set these environment variables: @@ -119,6 +136,8 @@ conan profile update env.CC= default conan profile update env.CXX= default ``` +Replace `` with paths to the desired compilers. + Export our [Conan recipe for Snappy](./external/snappy). It does not explicitly link the C++ standard library, which allows you to statically link it with GCC, if you want. From 27750c9e5f17b930546aa22386fe1552ed654d29 Mon Sep 17 00:00:00 2001 From: Elliot Lee Date: Fri, 21 Apr 2023 16:50:49 -0700 Subject: [PATCH 2/5] Update BUILD.md --- BUILD.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/BUILD.md b/BUILD.md index 35c715cc11d..e51a0afb0e6 100644 --- a/BUILD.md +++ b/BUILD.md @@ -38,12 +38,7 @@ below: See [System Requirements](https://xrpl.org/system-requirements.html). -rippled generally requires: -- git -- Python -- Conan -- CMake -- a C++ compiler +rippled generally requires git, Python, Conan, CMake, and a C++ compiler. Some guidance on setting up such a [C++ development environment can be found here](./docs/build/environment.md). ### Linux From 244622b40df7ba6b455e83dccaff37b5ff3ea63b Mon Sep 17 00:00:00 2001 From: Elliot Lee Date: Tue, 25 Apr 2023 14:29:03 -0700 Subject: [PATCH 3/5] Update BUILD.md --- BUILD.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BUILD.md b/BUILD.md index e51a0afb0e6..757e5509121 100644 --- a/BUILD.md +++ b/BUILD.md @@ -38,7 +38,7 @@ below: See [System Requirements](https://xrpl.org/system-requirements.html). -rippled generally requires git, Python, Conan, CMake, and a C++ compiler. Some guidance on setting up such a [C++ development environment can be found here](./docs/build/environment.md). +Building rippled generally requires git, Python, Conan, CMake, and a C++ compiler. Some guidance on setting up such a [C++ development environment can be found here](./docs/build/environment.md). ### Linux From c8f17324f6b4aa5d8e2d8f7994fb7b76a7d4bf49 Mon Sep 17 00:00:00 2001 From: Elliot Lee Date: Wed, 26 Apr 2023 08:12:36 -0700 Subject: [PATCH 4/5] Title section "Multiple compilers" --- BUILD.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/BUILD.md b/BUILD.md index 757e5509121..1bff86eaea5 100644 --- a/BUILD.md +++ b/BUILD.md @@ -110,9 +110,13 @@ architecture: conan profile update settings.arch=x86_64 default ``` -**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. +### Multiple compilers + +When `/usr/bin/g++` exists on a platform, it is the default cpp compiler. This +default works for some users. + +However, if this compiler cannot build rippled or its dependencies, then you can +install another compiler and set Conan and CMake to use it. Update the `conf.tools.build:compiler_executables` setting in order to set the correct variables (`CMAKE__COMPILER`) in the generated CMake toolchain file. For example, on Ubuntu 20, you may have gcc at `/usr/bin/gcc` and g++ at `/usr/bin/g++`; if that is the case, you can select those compilers with: From deb142b18ac89586dde95f93bc6ddbab277c6f00 Mon Sep 17 00:00:00 2001 From: Elliot Lee Date: Wed, 28 Jun 2023 10:39:08 -0700 Subject: [PATCH 5/5] Add WARNING per https://github.com/XRPLF/rippled/pull/4507/files#r1178031746 --- BUILD.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/BUILD.md b/BUILD.md index 7fb799249a2..8866eeb4555 100644 --- a/BUILD.md +++ b/BUILD.md @@ -1,7 +1,7 @@ -> These instructions assume you have a C++ development environment ready -> with Git, Python, Conan, CMake, and a C++ compiler. For help setting one up -> on Linux, macOS, or Windows, see [our guide](./docs/build/environment.md). -> +| :warning: **WARNING** :warning: +|---| +| These instructions assume you have a C++ development environment ready with Git, Python, Conan, CMake, and a C++ compiler. For help setting one up on Linux, macOS, or Windows, [see this guide](./docs/build/environment.md). | + > These instructions also assume a basic familiarity with Conan and CMake. > If you are unfamiliar with Conan, > you can read our [crash course](./docs/build/conan.md)