|
rippled
|
| :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. |
These instructions also assume a basic familiarity with Conan and CMake. If you are unfamiliar with Conan, you can read our crash course or the official Getting Started walkthrough.
For a stable release, choose the master branch or one of the tagged releases.
For the latest release candidate, choose the release branch.
For the latest set of untested features, or to contribute, choose the develop branch.
See System Requirements.
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.
[^1]: It is possible to build with Conan 2.x, but the instructions are significantly different, which is why we are not recommending it yet. Notably, the conan profile update command is removed in 2.x. Profiles must be edited by hand.
rippled is written in the C++20 dialect and includes the <concepts> header. The minimum compiler versions required are:
| Compiler | Version |
|---|---|
| GCC | 11 |
| Clang | 13 |
| Apple Clang | 13.1.6 |
| MSVC | 19.23 |
The Ubuntu operating system has received the highest level of quality assurance, testing, and support.
Here are sample instructions for setting up a C++ development environment on Linux.
Many rippled engineers use macOS for development.
Here are sample instructions for setting up a C++ development environment on macOS.
Windows is not recommended for production use at this time.
After you have a C++ development environment 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 or the official Getting Started walkthrough.
You'll need at least one Conan profile:
Update the compiler settings:
Configure Conan (1.x only) to use recipe revisions:
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:
Ensure inter-operability between boost::string_view and std::string_view types:
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:
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:
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:
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. Replace <path> with paths to the desired compilers:
conan profile update env.CC=<path> defaultconan profile update env.CXX=<path> defaultExport our Conan recipe for Snappy. It does not explicitly link the C++ standard library, which allows you to statically link it with GCC, if you want.
Export our Conan recipe for RocksDB. It does not override paths to dependencies when building with Visual Studio.
Export our Conan recipe for SOCI. It patches their CMake to correctly import its dependencies.
Export our Conan recipe for NuDB. It fixes some source files to add missing #includes.
Create a build directory and move into it.
You can use any directory name. Conan treats your working directory as an install folder and generates files with implementation details. You don't need to worry about these files, but make sure to change your working directory to your build directory before calling Conan.
Note: You can specify a directory for the installation files by adding the install-folder or -if option to every conan install command in the next step.
Generate CMake files for every configuration you want to build.
For a single-configuration generator, e.g. Unix Makefiles or Ninja, you only need to run this command once. For a multi-configuration generator, e.g. Visual Studio, you may want to run it more than once.
Each of these commands should also have a different build_type setting. A second command with the same build_type setting will overwrite the files generated by the first. You can pass the build type on the command line with --settings build_type=$BUILD_TYPE or in the profile itself, under the section [settings] with the key build_type.
If you are using a Microsoft Visual C++ compiler, then you will need to ensure consistency between the build_type setting and the compiler.runtime setting.
When build_type is Release, compiler.runtime should be MT.
When build_type is Debug, compiler.runtime should be MTd.
Configure CMake and pass the toolchain file generated by Conan, located at $OUTPUT_FOLDER/build/generators/conan_toolchain.cmake.
Single-config generators:
Pass the CMake variable CMAKE_BUILD_TYPE and make sure it matches the build_type setting you chose in the previous step.
Multi-config generators:
Note: You can pass build options for rippled in this step.
Build rippled.
For a single-configuration generator, it will build whatever configuration you passed for CMAKE_BUILD_TYPE. For a multi-configuration generator, you must pass the option --config to select the build configuration.
Single-config generators:
Multi-config generators:
Test rippled.
Single-config generators:
Multi-config generators:
The location of rippled in your build directory depends on your CMake generator. Pass --help to see the rest of the command line options.
The coverage report is intended for developers using compilers GCC or Clang (including Apple Clang). It is generated by the build target coverage, which is only enabled when the coverage option is set, e.g. with --options coverage=True in conan or -Dcoverage=ON variable in cmake
Prerequisites for the coverage report:
gcov for GCC (installed with the compiler by default) orllvm-cov for Clang (installed with the compiler by default)Debug build typeA coverage report is created when the following steps are completed, in order:
rippled binary built with instrumentation data, enabled by the coverage option mentioned abovegcovr tool (which internally invokes either gcov or llvm-cov) to assemble both instrumentation data and the coverage capture data into a coverage reportThe above steps are automated into a single target coverage. The instrumented rippled binary can also be used for regular development or testing work, at the cost of extra disk space utilization and a small performance hit (to store coverage capture). In case of a spurious failure of unit tests, it is possible to re-run the coverage target without rebuilding the rippled binary (since it is simply a dependency of the coverage report target). It is also possible to select only specific tests for the purpose of the coverage report, by setting the coverage_test variable in cmake
The default coverage report format is html-details, but the user can override it to any of the formats listed in Builds/CMake/CodeCoverage.cmake by setting the coverage_format variable in cmake. It is also possible to generate more than one format at a time by setting the coverage_extra_args variable in cmake. The specific command line used to run the gcovr tool will be displayed if the CODE_COVERAGE_VERBOSE variable is set.
By default, the code coverage tool runs parallel unit tests with --unittest-jobs set to the number of available CPU cores. This may cause spurious test errors on Apple. Developers can override the number of unit test jobs with the coverage_test_parallelism variable in cmake.
Example use with some cmake variables set:
After the coverage target is completed, the generated coverage report will be stored inside the build directory, as either of:
coverage._extension_ , with a suitable extension for the report format, orcoverage, with the index.html and other files inside, for the html-details or html-nested report formats.| Option | Default Value | Description |
|---|---|---|
assert | OFF | Enable assertions. |
coverage | OFF | Prepare the coverage report. |
san | N/A | Enable a sanitizer with Clang. Choices are thread and address. |
tests | OFF | Build tests. |
unity | ON | Configure a unity build. |
xrpld | OFF | Build the xrpld (rippled) application, and not just the libxrpl library. |
Unity builds may be faster for the first build (at the cost of much more memory) since they concatenate sources into fewer translation units. Non-unity builds may be faster for incremental builds, and can be helpful for detecting #include omissions.
After any updates or changes to dependencies, you may need to do the following:
If your compiler version is recent enough to have removed std::result_of as part of C++20, e.g. Apple Clang 15.0, then you might need to add a preprocessor definition to your build.
If you are compiling with an early version of Clang 16, then you might hit a regression when compiling C++20 that manifests as an error in a Boost header. You can workaround it by adding this preprocessor definition:
If you get a linker error suggesting that you recompile Boost with position-independent code, such as:
Conan most likely downloaded a bad binary distribution of the dependency. This seems to be a bug in Conan just for Boost 1.77.0 compiled with GCC for Linux. The solution is to build the dependency locally by passing --build boost when calling conan install.
If you want to experiment with a new package, follow these steps:
conanfile.py:requires property.default_options property (with syntax ‘’$package:$option': $value).Modify [CMakeLists.txt](./CMakeLists.txt):
- Add a call tofind_package($package REQUIRED)
.
Link a library from the package to the targetripple_libs (search for the existing call totarget_link_libraries(ripple_libs INTERFACE ...)`).
Start coding! Don't forget to include whatever headers you need from the package. 1.9.5