mirror of
https://github.com/XRPLF/clio.git
synced 2025-11-19 11:15:50 +00:00
184 lines
6.6 KiB
Markdown
184 lines
6.6 KiB
Markdown
# How to build Clio
|
|
|
|
Clio is built with [CMake](https://cmake.org/) and uses [Conan](https://conan.io/) for managing dependencies. It is written in C++20 and therefore requires a modern compiler.
|
|
|
|
## Minimum Requirements
|
|
|
|
- [Python 3.7](https://www.python.org/downloads/)
|
|
- [Conan 1.55](https://conan.io/downloads.html)
|
|
- [CMake 3.20](https://cmake.org/download/)
|
|
- [**Optional**] [GCovr](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html): needed for code coverage generation
|
|
- [**Optional**] [CCache](https://ccache.dev/): 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.
|
|
|
|
```sh
|
|
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.
|
|
|
|
```sh
|
|
conan remove -f xrpl
|
|
```
|
|
|
|
## Building Clio
|
|
|
|
Navigate to Clio's root directory and run:
|
|
|
|
```sh
|
|
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](https://www.doxygen.nl/index.html). 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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](https://www.docker.com/) if you don't want to install all the dependencies on your machine.
|
|
|
|
```sh
|
|
docker run -it rippleci/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](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0033d-multi-purpose-tokens):
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```py
|
|
# ... (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](#building-clio) for details.
|