clio/docs/build-clio.md

How to build Clio

Clio is built with CMake and uses Conan for managing dependencies. It is written in C++20 and therefore requires a modern compiler.

Minimum Requirements

• Python 3.7
• Conan 1.55
• CMake 3.20
• [Optional] GCovr: needed for code coverage generation
• [Optional] CCache: speeds up compilation if you are going to compile Clio often

Compiler	Version
GCC	12.3
Clang	16
Apple Clang	15

Conan Configuration

Clio does not require anything other than compiler.cppstd=20 in your (~/.conan/profiles/default) Conan profile.

Note

Although Clio is built using C++23, it's required to set compiler.cppstd=20 for the time being as some of Clio's dependencies are not yet capable of building under C++23.

Mac example:

[settings]
os=Macos
os_build=Macos
arch=armv8
arch_build=armv8
compiler=apple-clang
compiler.version=15
compiler.libcxx=libc++
build_type=Release
compiler.cppstd=20
[conf]
tools.build:cxxflags+=["-DBOOST_ASIO_DISABLE_CONCEPTS"]

Linux example:

[settings]
os=Linux
os_build=Linux
arch=x86_64
arch_build=x86_64
compiler=gcc
compiler.version=12
compiler.libcxx=libstdc++11
build_type=Release
compiler.cppstd=20

Artifactory

Make sure artifactory is setup with Conan.

conan remote add --insert 0 conan-non-prod http://18.143.149.228:8081/artifactory/api/conan/conan-non-prod

Now you should be able to download the prebuilt xrpl package on some platforms.

Note

You may need to edit the ~/.conan/remotes.json file to ensure that this newly added artifactory is listed last. Otherwise, you could see compilation errors when building the project with gcc version 13 (or newer).

Remove old packages you may have cached.

conan remove -f xrpl

Building Clio

Navigate to Clio's root directory and run:

mkdir build && cd build
conan install .. --output-folder . --build missing --settings build_type=Release -o tests=True -o lint=False
cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel 8 # or without the number if you feel extra adventurous

Tip

You can omit the -o tests=True if you don't want to build clio_tests.

If successful, conan install will find the required packages and cmake will do the rest. You should see clio_server and clio_tests in the build directory (the current directory).

Tip

To generate a Code Coverage report, include -o coverage=True in the conan install command above, along with -o tests=True to enable tests. After running the cmake commands, execute make clio_tests-ccov. The coverage report will be found at clio_tests-llvm-cov/index.html.

Note

If you've built Clio before and the build is now failing, it's likely due to updated dependencies. Try deleting the build folder and then rerunning the Conan and CMake commands mentioned above.

Generating API docs for Clio

The API documentation for Clio is generated by Doxygen. If you want to generate the API documentation when building Clio, make sure to install Doxygen on your system.

To generate the API docs:

1. First, include -o docs=True in the conan install command. For example:

   mkdir build && cd build
   conan install .. --output-folder . --build missing --settings build_type=Release -o tests=True -o lint=False -o docs=True
   

2. Once that has completed successfully, run the cmake command and add the --target docs option:

   cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release ..
   cmake --build . --parallel 8 --target docs
   

3. Go to build/docs/html to view the generated files.

   Open the index.html file in your browser to see the documentation pages.

   

Building Clio with Docker

It is also possible to build Clio using Docker if you don't want to install all the dependencies on your machine.

docker run -it ghcr.io/xrplf/clio-ci:latest
git clone https://github.com/XRPLF/clio
mkdir build && cd build
conan install .. --output-folder . --build missing --settings build_type=Release -o tests=True -o lint=False
cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel 8 # or without the number if you feel extra adventurous

Developing against rippled in standalone mode

If you wish to develop against a rippled instance running in standalone mode there are a few quirks of both Clio and rippled that you need to keep in mind. You must:

1. Advance the rippled ledger to at least ledger 256.
2. Wait 10 minutes before first starting Clio against this standalone node.

Building with a Custom libxrpl

Sometimes, during development, you need to build against a custom version of libxrpl. (For example, you may be developing compatibility for a proposed amendment that is not yet merged to the main rippled codebase.) To build Clio with compatibility for a custom fork or branch of rippled, follow these steps:

1. First, pull/clone the appropriate rippled fork and switch to the branch you want to build. For example, the following example uses an in-development build with XLS-33d Multi-Purpose Tokens:

   git clone https://github.com/shawnxie999/rippled/
   cd rippled
   git switch mpt-1.1
   

2. Export a custom package to your local Conan store using a user/channel:

   conan export . my/feature
   

3. Patch your local Clio build to use the right package.

   Edit conanfile.py (from the Clio repository root). Replace the xrpl requirement with the custom package version from the previous step. This must also include the current version number from your rippled branch. For example:

   # ... (excerpt from conanfile.py)
       requires = [
       'boost/1.82.0',
       'cassandra-cpp-driver/2.17.0',
       'fmt/10.1.1',
       'protobuf/3.21.9',
       'grpc/1.50.1',
       'openssl/1.1.1u',
       'xrpl/2.3.0-b1@my/feature', # Update this line
       'libbacktrace/cci.20210118'
   ]
   

4. Build Clio as you would have before.

   See Building Clio for details.

Using clang-tidy for static analysis

The minimum clang-tidy version required is 19.0.

Clang-tidy can be run by Cmake when building the project. To achieve this, you just need to provide the option -o lint=True for the conan install command:

conan install .. --output-folder . --build missing --settings build_type=Release -o tests=True -o lint=True

By default Cmake will try to find clang-tidy automatically in your system. To force Cmake to use your desired binary, set the CLIO_CLANG_TIDY_BIN environment variable to the path of the clang-tidy binary. For example:

export CLIO_CLANG_TIDY_BIN=/opt/homebrew/opt/llvm@19/bin/clang-tidy