ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2025-11-04 19:25:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update BUILD.md for Conan 2 (#5478)

Browse Source 
This change updates BUILD.md for Conan 2, add fixes/workarounds for Apple Clang 17, Clang 20 and CMake 4. This also removes (from BUILD.md only) workarounds for compiler versions which we no longer support e.g. Clang 15 and adds compilation flag -Wno-deprecated-declarations to enable building with Clang 20 on Linux.
This commit is contained in:
Bronek Kozicki
2025-08-06 11:18:41 +01:00
committed by GitHub
parent 4eae037fee
commit dbeb841b5a
2 changed files with 303 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

400
BUILD.md
View File

@@ -3,29 +3,29 @@
| 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 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. > These instructions also assume a basic familiarity with Conan and CMake.
> If you are unfamiliar with Conan, > If you are unfamiliar with Conan, you can read our
> you can read our [crash course](./docs/build/conan.md) > [crash course](./docs/build/conan.md) or the official [Getting Started][3]
> or the official [Getting Started][3] walkthrough. > walkthrough.
## Branches ## Branches
For a stable release, choose the `master` branch or one of the [tagged For a stable release, choose the `master` branch or one of the [tagged
releases](https://github.com/ripple/rippled/releases). releases](https://github.com/ripple/rippled/releases).
``` ```bash
git checkout master git checkout master
``` ```
For the latest release candidate, choose the `release` branch. For the latest release candidate, choose the `release` branch.
``` ```bash
git checkout release git checkout release
``` ```
For the latest set of untested features, or to contribute, choose the `develop` For the latest set of untested features, or to contribute, choose the `develop`
branch. branch.
``` ```bash
git checkout develop git checkout develop
``` ```
@@ -33,151 +33,282 @@ git checkout develop
See [System Requirements](https://xrpl.org/system-requirements.html). See [System Requirements](https://xrpl.org/system-requirements.html).
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). 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).
- [Python 3.7](https://www.python.org/downloads/) - [Python 3.11](https://www.python.org/downloads/), or higher
- [Conan 1.60](https://conan.io/downloads.html)[^1] - [Conan 2.17](https://conan.io/downloads.html)[^1], or higher
- [CMake 3.16](https://cmake.org/download/) - [CMake 3.22](https://cmake.org/download/)[^2], or higher
[^1]: It is possible to build with Conan 2.x, [^1]: It is possible to build with Conan 1.60+, but the instructions are
but the instructions are significantly different, significantly different, which is why we are not recommending it.
which is why we are not recommending it yet.
Notably, the `conan profile update` command is removed in 2.x. [^2]: CMake 4 is not yet supported by all dependencies required by this project.
Profiles must be edited by hand. If you are affected by this issue, follow [conan workaround for cmake
4](#workaround-for-cmake-4)
`rippled` is written in the C++20 dialect and includes the `<concepts>` header. `rippled` is written in the C++20 dialect and includes the `<concepts>` header.
The [minimum compiler versions][2] required are: The [minimum compiler versions][2] required are:
| Compiler | Version | | Compiler | Version |
|-------------|---------| |-------------|-----|
| GCC | 11 | | GCC | 12 |
| Clang | 13 | | Clang | 16 |
| Apple Clang | 13.1.6 | | Apple Clang | 16 |
| MSVC | 19.23 | | MSVC | 19.44[^3] |
### Linux ### Linux
The Ubuntu operating system has received the highest level of The Ubuntu Linux distribution has received the highest level of quality
quality assurance, testing, and support. assurance, testing, and support. We also support Red Hat and use Debian
internally.
Here are [sample instructions for setting up a C++ development environment on Linux](./docs/build/environment.md#linux). Here are [sample instructions for setting up a C++ development environment on
Linux](./docs/build/environment.md#linux).
### Mac ### Mac
Many rippled engineers use macOS for development. Many rippled engineers use macOS for development.
Here are [sample instructions for setting up a C++ development environment on macOS](./docs/build/environment.md#macos). Here are [sample instructions for setting up a C++ development environment on
macOS](./docs/build/environment.md#macos).
### Windows ### Windows
Windows is not recommended for production use at this time. Windows is used by some engineers for development only.
- Additionally, 32-bit Windows development is not supported. [^3]: Windows is not recommended for production use.
[Boost]: https://www.boost.org/
## Steps ## Steps
### Set Up Conan ### Set Up Conan
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. 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. 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.
If you are unfamiliar with Conan, then please read [this crash course](./docs/build/conan.md) or the official [Getting Started][3] walkthrough. #### Default profile
We recommend that you import the provided `conan/profiles/default` profile:
You'll need at least one Conan profile: ```bash
conan config install conan/profiles/ -tf $(conan config home)/profiles/
```
conan profile new default --detect
```
Update the compiler settings:
```
conan profile update settings.compiler.cppstd=20 default
```
Configure Conan (1.x only) to use recipe revisions:
```
conan config set general.revisions_enabled=1
```
**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:
```
conan profile update settings.compiler.libcxx=libstdc++11 default
```
Ensure inter-operability between `boost::string_view` and `std::string_view` types:
```
conan profile update 'conf.tools.build:cxxflags+=["-DBOOST_BEAST_USE_STD_STRING_VIEW"]' default
conan profile update 'env.CXXFLAGS="-DBOOST_BEAST_USE_STD_STRING_VIEW"' default
``` ```
If you have other flags in the `conf.tools.build` or `env.CXXFLAGS` sections, make sure to retain the existing flags and append the new ones. You can check them with: You can check your Conan profile by running:
```
conan profile show default ```bash
conan profile show
``` ```
#### Custom profile
**Windows** developers may need to use the x64 native build tools. If the default profile does not work for you and you do not yet have a Conan
An easy way to do that is to run the shortcut "x64 Native Tools Command profile, you can create one by running:
Prompt" for the version of Visual Studio that you have installed.
Windows developers must also build `rippled` and its dependencies for the x64 ```bash
architecture: conan profile detect
```
conan profile update settings.arch=x86_64 default
```
### 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_<LANG>_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": "/usr/bin/gcc", "cpp": "/usr/bin/g++"}' default
``` ```
Replace `/usr/bin/gcc` and `/usr/bin/g++` with paths to the desired compilers. You may need to make changes to the profile to suit your environment. You can
refer to the provided `conan/profiles/default` profile for inspiration, and you
may also need to apply the required [tweaks](#conan-profile-tweaks) to this
default profile.
It should choose the compiler for dependencies as well, ### Patched recipes
but not all of them have a Conan recipe that respects this setting (yet).
For the rest, you can set these environment variables.
Replace `<path>` with paths to the desired compilers:
- `conan profile update env.CC=<path> default` The recipes in Conan Center occasionally need to be patched for compatibility
- `conan profile update env.CXX=<path> default` with the latest version of `rippled`. We maintain a fork of the Conan Center
[here](https://github.com/XRPLF/conan-center-index/) containing the patches.
Export our [Conan recipe for Snappy](./external/snappy). To ensure our patched recipes are used, you must add our Conan remote at a
It does not explicitly link the C++ standard library, higher index than the default Conan Center remote, so it is consulted first. You
which allows you to statically link it with GCC, if you want. can do this by running:
``` ```bash
# Conan 2.x conan remote add --index 0 xrplf "https://conan.ripplex.io"
conan export --version 1.1.10 external/snappy ```
Alternatively, you can use the `conan export` command to add the patched recipes
that are also (for the time being) located in the `external/` directory to your
local Conan cache:
```bash
conan export --version 1.1.10 external/snappy
conan export --version 4.0.3 external/soci
```
### Conan profile tweaks
#### Missing compiler version
If you see an error similar to the following after running `conan profile show`:
```bash
ERROR: Invalid setting '17' is not a valid 'settings.compiler.version' value.
Possible values are ['5.0', '5.1', '6.0', '6.1', '7.0', '7.3', '8.0', '8.1',
'9.0', '9.1', '10.0', '11.0', '12.0', '13', '13.0', '13.1', '14', '14.0', '15',
'15.0', '16', '16.0']
Read "http://docs.conan.io/2/knowledge/faq.html#error-invalid-setting"
```
you need to amend the list of compiler versions in
`$(conan config home)/settings.yml`, by appending the required version number(s)
to the `version` array specific for your compiler. For example:
```yaml
apple-clang:
version: ["5.0", "5.1", "6.0", "6.1", "7.0", "7.3", "8.0", "8.1", "9.0",
"9.1", "10.0", "11.0", "12.0", "13", "13.0", "13.1", "14",
"14.0", "15", "15.0", "16", "16.0", "17", "17.0"]
```
#### Multiple compilers
If you have multiple compilers installed, make sure to select the one to use in
your default Conan configuration **before** running `conan profile detect`, by
setting the `CC` and `CXX` environment variables.
For example, if you are running MacOS and have [homebrew
LLVM@18](https://formulae.brew.sh/formula/llvm@18), and want to use it as a
compiler in the new Conan profile:
```bash
export CC=$(brew --prefix llvm@18)/bin/clang
export CXX=$(brew --prefix llvm@18)/bin/clang++
conan profile detect
``` ```
Export our [Conan recipe for SOCI](./external/soci). You should also explicitly set the path to the compiler in the profile file,
It patches their CMake to correctly import its dependencies. which helps to avoid errors when `CC` and/or `CXX` are set and disagree with the
selected Conan profile. For example:
``` ```text
# Conan 2.x [conf]
conan export --version 4.0.3 external/soci tools.build:compiler_executables={'c':'/usr/bin/gcc','cpp':'/usr/bin/g++'}
``` ```
#### Multiple profiles
You can manage multiple Conan profiles in the directory
`$(conan config home)/profiles`, for example renaming `default` to a different
name and then creating a new `default` profile for a different compiler.
#### Select language
The default profile created by Conan will typically select different C++ dialect
than C++20 used by this project. You should set `20` in the profile line
starting with `compiler.cppstd=`. For example:
```bash
sed -i.bak -e 's|^compiler\.cppstd=.*$|compiler.cppstd=20|' $(conan config home)/profiles/default
```
#### Select standard library in 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`), then you will need to choose the
`libstdc++11` ABI:
```bash
sed -i.bak -e 's|^compiler\.libcxx=.*$|compiler.libcxx=libstdc++11|' $(conan config home)/profiles/default
```
#### Select architecture and runtime in 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.
Windows developers must also build `rippled` and its dependencies for the x64
architecture:
```bash
sed -i.bak -e 's|^arch=.*$|arch=x86_64|' $(conan config home)/profiles/default
```
**Windows** developers also must select static runtime:
```bash
sed -i.bak -e 's|^compiler\.runtime=.*$|compiler.runtime=static|' $(conan config home)/profiles/default
```
#### Workaround for CMake 4
If your system CMake is version 4 rather than 3, you may have to configure Conan
profile to use CMake version 3 for dependencies, by adding the following two
lines to your profile:
```text
[tool_requires]
!cmake/*: cmake/[>=3 <4]
```
This will force Conan to download and use a locally cached CMake 3 version, and
is needed because some of the dependencies used by this project do not support
CMake 4.
#### Clang workaround for grpc
If your compiler is clang, version 19 or later, or apple-clang, version 17 or
later, you may encounter a compilation error while building the `grpc`
dependency:
```text
In file included from .../lib/promise/try_seq.h:26:
.../lib/promise/detail/basic_seq.h:499:38: error: a template argument list is expected after a name prefixed by the template keyword [-Wmissing-template-arg-list-after-template-kw]
499 | Traits::template CallSeqFactory(f_, *cur_, std::move(arg)));
| ^
```
The workaround for this error is to add two lines to profile:
```text
[conf]
tools.build:cxxflags=['-Wno-missing-template-arg-list-after-template-kw']
```
#### Workaround for gcc 12
If your compiler is gcc, version 12, and you have enabled `werr` option, you may
encounter a compilation error such as:
```text
/usr/include/c++/12/bits/char_traits.h:435:56: error: 'void* __builtin_memcpy(void*, const void*, long unsigned int)' accessing 9223372036854775810 or more bytes at offsets [2, 9223372036854775807] and 1 may overlap up to 9223372036854775813 bytes at offset -3 [-Werror=restrict]
435 | return static_cast<char_type*>(__builtin_memcpy(__s1, __s2, __n));
| ~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~
cc1plus: all warnings being treated as errors
```
The workaround for this error is to add two lines to your profile:
```text
[conf]
tools.build:cxxflags=['-Wno-restrict']
```
#### Workaround for clang 16
If your compiler is clang, version 16, you may encounter compilation error such
as:
```text
In file included from .../boost/beast/websocket/stream.hpp:2857:
.../boost/beast/websocket/impl/read.hpp:695:17: error: call to 'async_teardown' is ambiguous
async_teardown(impl.role, impl.stream(),
^~~~~~~~~~~~~~
```
The workaround for this error is to add two lines to your profile:
```text
[conf]
tools.build:cxxflags=['-DBOOST_ASIO_DISABLE_CONCEPTS']
```
### Build and Test ### Build and Test
@@ -245,7 +376,6 @@ It patches their CMake to correctly import its dependencies.
cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release -Dxrpld=ON -Dtests=ON .. cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release -Dxrpld=ON -Dtests=ON ..
``` ```
Multi-config generators: Multi-config generators:
``` ```
@@ -257,13 +387,13 @@ It patches their CMake to correctly import its dependencies.
5. Build `rippled`. 5. Build `rippled`.
For a single-configuration generator, it will build whatever configuration For a single-configuration generator, it will build whatever configuration
you passed for `CMAKE_BUILD_TYPE`. For a multi-configuration generator, you passed for `CMAKE_BUILD_TYPE`. For a multi-configuration generator, you
you must pass the option `--config` to select the build configuration. must pass the option `--config` to select the build configuration.
Single-config generators: Single-config generators:
``` ```
cmake --build . -j $(nproc) cmake --build .
``` ```
Multi-config generators: Multi-config generators:
@@ -278,18 +408,22 @@ It patches their CMake to correctly import its dependencies.
Single-config generators: Single-config generators:
``` ```
./rippled --unittest ./rippled --unittest --unittest-jobs N
``` ```
Multi-config generators: Multi-config generators:
``` ```
./Release/rippled --unittest ./Release/rippled --unittest --unittest-jobs N
./Debug/rippled --unittest ./Debug/rippled --unittest --unittest-jobs N
``` ```
The location of `rippled` in your build directory depends on your CMake Replace the `--unittest-jobs` parameter N with the desired unit tests
generator. Pass `--help` to see the rest of the command line options. concurrency. Recommended setting is half of the number of available CPU
cores.
The location of `rippled` binary in your build directory depends on your
CMake generator. Pass `--help` to see the rest of the command line options.
## Coverage report ## Coverage report
@@ -347,7 +481,7 @@ cmake --build . --target coverage
After the `coverage` target is completed, the generated coverage report will be After the `coverage` target is completed, the generated coverage report will be
stored inside the build directory, as either of: stored inside the build directory, as either of:
- file named `coverage.`_extension_ , with a suitable extension for the report format, or - file named `coverage.`_extension_, with a suitable extension for the report format, or
- directory named `coverage`, with the `index.html` and other files inside, for the `html-details` or `html-nested` report formats. - directory named `coverage`, with the `index.html` and other files inside, for the `html-details` or `html-nested` report formats.
@@ -355,12 +489,14 @@ stored inside the build directory, as either of:
| Option | Default Value | Description | | Option | Default Value | Description |
| --- | ---| ---| | --- | ---| ---|
| `assert` | OFF | Enable assertions. | `assert` | OFF | Enable assertions. |
| `coverage` | OFF | Prepare the coverage report. | | `coverage` | OFF | Prepare the coverage report. |
| `san` | N/A | Enable a sanitizer with Clang. Choices are `thread` and `address`. | | `san` | N/A | Enable a sanitizer with Clang. Choices are `thread` and `address`. |
| `tests` | OFF | Build tests. | | `tests` | OFF | Build tests. |
| `unity` | ON | Configure a unity build. | | `unity` | OFF | Configure a unity build. |
| `xrpld` | OFF | Build the xrpld (`rippled`) application, and not just the libxrpl library. | | `xrpld` | OFF | Build the xrpld (`rippled`) application, and not just the libxrpl library. |
| `werr` | OFF | Treat compilation warnings as errors |
| `wextra` | OFF | Enable additional compilation warnings |
[Unity builds][5] may be faster for the first build [Unity builds][5] may be faster for the first build
(at the cost of much more memory) since they concatenate sources into fewer (at the cost of much more memory) since they concatenate sources into fewer
@@ -375,12 +511,28 @@ and can be helpful for detecting `#include` omissions.
After any updates or changes to dependencies, you may need to do the following: After any updates or changes to dependencies, you may need to do the following:
1. Remove your build directory. 1. Remove your build directory.
2. Remove the Conan cache: `conan remove "*" -c` 2. Remove individual libraries from the Conan cache, e.g.
3. Re-run [conan install](#build-and-test).
### 'protobuf/port_def.inc' file not found ```bash
conan remove 'grpc/*'
```
If `cmake --build .` results in an error due to a missing a protobuf file, then you might have generated CMake files for a different `build_type` than the `CMAKE_BUILD_TYPE` you passed to conan. **or**
Remove all libraries from Conan cache:
```bash
conan remove '*'
```
3. Re-run [conan export](#export-updated-recipes)
4. Re-run [conan install](#build-and-test).
### `protobuf/port_def.inc` file not found
If `cmake --build .` results in an error due to a missing a protobuf file, then
you might have generated CMake files for a different `build_type` than the
`CMAKE_BUILD_TYPE` you passed to Conan.
``` ```
/rippled/.build/pb-xrpl.libpb/xrpl/proto/ripple.pb.h:10:10: fatal error: 'google/protobuf/port_def.inc' file not found /rippled/.build/pb-xrpl.libpb/xrpl/proto/ripple.pb.h:10:10: fatal error: 'google/protobuf/port_def.inc' file not found

56
docs/build/environment.md vendored
View File

@@ -10,37 +10,35 @@ platforms: Linux, macOS, or Windows.
Package ecosystems vary across Linux distributions, Package ecosystems vary across Linux distributions,
so there is no one set of instructions that will work for every Linux user. so there is no one set of instructions that will work for every Linux user.
These instructions are written for Ubuntu 22.04. The instructions below are written for Debian 12 (Bookworm).
They are largely copied from the [script][1] used to configure our Docker
container for continuous integration.
That script handles many more responsibilities.
These instructions are just the bare minimum to build one configuration of
rippled.
You can check that codebase for other Linux distributions and versions.
If you cannot find yours there,
then we hope that these instructions can at least guide you in the right
direction.
``` ```
apt update export GCC_RELEASE=12
apt install --yes curl git libssl-dev pipx python3.10-dev python3-pip make g++-11 libprotobuf-dev protobuf-compiler sudo apt update
sudo apt install --yes gcc-${GCC_RELEASE} g++-${GCC_RELEASE} python3-pip \
python-is-python3 python3-venv python3-dev curl wget ca-certificates \
git build-essential cmake ninja-build libc6-dev
sudo pip install --break-system-packages conan
curl --location --remote-name \ sudo update-alternatives --install /usr/bin/cc cc /usr/bin/gcc-${GCC_RELEASE} 999
"https://github.com/Kitware/CMake/releases/download/v3.25.1/cmake-3.25.1.tar.gz" sudo update-alternatives --install \
tar -xzf cmake-3.25.1.tar.gz /usr/bin/gcc gcc /usr/bin/gcc-${GCC_RELEASE} 100 \
rm cmake-3.25.1.tar.gz --slave /usr/bin/g++ g++ /usr/bin/g++-${GCC_RELEASE} \
cd cmake-3.25.1 --slave /usr/bin/gcc-ar gcc-ar /usr/bin/gcc-ar-${GCC_RELEASE} \
./bootstrap --parallel=$(nproc) --slave /usr/bin/gcc-nm gcc-nm /usr/bin/gcc-nm-${GCC_RELEASE} \
make --jobs $(nproc) --slave /usr/bin/gcc-ranlib gcc-ranlib /usr/bin/gcc-ranlib-${GCC_RELEASE} \
make install --slave /usr/bin/gcov gcov /usr/bin/gcov-${GCC_RELEASE} \
cd .. --slave /usr/bin/gcov-tool gcov-tool /usr/bin/gcov-tool-${GCC_RELEASE} \
--slave /usr/bin/gcov-dump gcov-dump /usr/bin/gcov-dump-${GCC_RELEASE} \
pipx install 'conan<2' --slave /usr/bin/lto-dump lto-dump /usr/bin/lto-dump-${GCC_RELEASE}
pipx ensurepath sudo update-alternatives --auto cc
sudo update-alternatives --auto gcc
``` ```
[1]: https://github.com/thejohnfreeman/rippled-docker/blob/master/ubuntu-22.04/install.sh If you use different Linux distribution, hope the instruction above can guide
you in the right direction. We try to maintain compatibility with all recent
compiler releases, so if you use a rolling distribution like e.g. Arch or CentOS
then there is a chance that everything will "just work".
## macOS ## macOS
@@ -100,10 +98,10 @@ and use it to install Conan:
brew update brew update
brew install xz brew install xz
brew install pyenv brew install pyenv
pyenv install 3.10-dev pyenv install 3.11
pyenv global 3.10-dev pyenv global 3.11
eval "$(pyenv init -)" eval "$(pyenv init -)"
pip install 'conan<2' pip install 'conan'
``` ```
Install CMake with Homebrew too: Install CMake with Homebrew too: