Skip to content

Latest commit

 

History

History
319 lines (241 loc) · 11.1 KB

BUILD.md

File metadata and controls

319 lines (241 loc) · 11.1 KB

Branches

For a stable release, choose the master branch or one of the tagged releases.

git checkout master

For the latest release candidate, choose the release branch.

git checkout release

If you are contributing or want the latest set of untested features, then use the develop branch.

git checkout develop

Platforms

rippled is written in the C++20 dialect and includes the <concepts> header. The minimum compiler versions that can compile this dialect are given below:

Compiler Minimum Version
GCC 10
Clang 13
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 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.

Prerequisites

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.

These instructions further assume a basic familiarity with Conan and CMake. If you are unfamiliar with Conan, then please read our crash course or the official Getting Started walkthrough.

To build this package, you will need Python (>= 3.7), Conan (>= 1.55, < 2), and CMake (>= 3.16).

You'll need at least one Conan profile:

conan profile new default --detect

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 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

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.

Windows developers must build rippled and its dependencies for the x64 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. This setting will set the correct variables (CMAKE_<LANG>_COMPILER) in the generated CMake toolchain file:

conan profile update 'conf.tools.build:compiler_executables={"c": "<path>", "cpp": "<path>"}' default

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:

conan profile update env.CC=<path> default
conan profile update env.CXX=<path> default

Export 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.

conan export external/snappy snappy/1.1.9@

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:

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:

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:

  1. Create a build directory (and move into it).

    You can choose any name you want.

    Conan will generate some files in what it calls the "install folder". These files are implementation details that you don't need to worry about. By default, the install folder is your current working directory. If you don't move into your build directory before calling Conan, then you may be annoyed to see it polluting your project root directory with these files. To make Conan put them in your build directory, you'll have to add the option --install-folder or -if to every conan install command.

  2. 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 have a different build_type setting. A second command with the same build_type setting will just 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.

  3. Configure CMake once.

    For all choices of generator, pass the toolchain file generated by Conan. It will be located at $OUTPUT_FOLDER/build/generators/conan_toolchain.cmake. If you are using a single-configuration generator, then pass the CMake variable CMAKE_BUILD_TYPE and make sure it matches the build_type setting you chose in the previous step.

    This step is where you may pass build options for rippled.

  4. Build rippled.

    For a multi-configuration generator, you must pass the option --config to select the build configuration. For a single-configuration generator, it will build whatever configuration you passed for CMAKE_BUILD_TYPE.

  5. Test rippled.

    The exact location of rippled in your build directory depends on your choice of CMake generator. You can run unit tests by passing --unittest. Pass --help to see the rest of the command line options.

Options

The unity option allows you to select between unity and non-unity builds. 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.

Below are the most commonly used options, with their default values in parentheses.

  • assert (OFF): Enable assertions.
  • reporting (OFF): Build the reporting mode feature.
  • tests (ON): Build tests.
  • unity (ON): Configure a unity build.
  • san (): Enable a sanitizer with Clang. Choices are thread and address.

Troubleshooting

Conan

If you find trouble building dependencies after changing Conan settings, then you should retry after removing the Conan cache:

rm -rf ~/.conan/data

no std::result_of

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 bulid:

conan profile update 'options.boost:extra_b2_flags="define=BOOST_ASIO_HAS_STD_INVOKE_RESULT"' default
conan profile update 'env.CFLAGS="-DBOOST_ASIO_HAS_STD_INVOKE_RESULT"' default
conan profile update 'env.CXXFLAGS="-DBOOST_ASIO_HAS_STD_INVOKE_RESULT"' default
conan profile update 'conf.tools.build:cflags+=["-DBOOST_ASIO_HAS_STD_INVOKE_RESULT"]' default
conan profile update 'conf.tools.build:cxxflags+=["-DBOOST_ASIO_HAS_STD_INVOKE_RESULT"]' default

recompile with -fPIC

/usr/bin/ld.gold: error: /home/username/.conan/data/boost/1.77.0/_/_/package/.../lib/libboost_container.a(alloc_lib.o):
  requires unsupported dynamic reloc 11; recompile with -fPIC

If you get a linker error like the one above suggesting that you recompile Boost with position-independent code, the reason is most likely that Conan downloaded a bad binary distribution of the dependency. For now, 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:

conan install --build boost ...

How to add a dependency

If you want to experiment with a new package, here are the steps to get it working:

  1. Search for the package on Conan Center.
  2. In conanfile.py:
    1. Add a version of the package to the requires property.
    2. Change any default options for the package by adding them to the default_options property (with syntax '$package:$option': $value)
  3. In CMakeLists.txt:
    1. Add a call to find_package($package REQUIRED).
    2. Link a library from the package to the target ripple_libs (search for the existing call to target_link_libraries(ripple_libs INTERFACE ...)).
  4. Start coding! Don't forget to include whatever headers you need from the package.