From 9a4a49aeee53135c1f3344a6f6ba395bda46e093 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Thu, 5 Jan 2023 19:00:12 -0600 Subject: [PATCH 1/7] Remove obsolete build instructions --- .../CMakeSettings-example.json | 45 --- Builds/VisualStudio2019/README.md | 263 ----------------- Builds/linux/README.md | 269 ------------------ Builds/macos/README.md | 3 - 4 files changed, 580 deletions(-) delete mode 100644 Builds/VisualStudio2019/CMakeSettings-example.json delete mode 100644 Builds/VisualStudio2019/README.md delete mode 100644 Builds/linux/README.md delete mode 100644 Builds/macos/README.md diff --git a/Builds/VisualStudio2019/CMakeSettings-example.json b/Builds/VisualStudio2019/CMakeSettings-example.json deleted file mode 100644 index b90bfce6bb1..00000000000 --- a/Builds/VisualStudio2019/CMakeSettings-example.json +++ /dev/null @@ -1,45 +0,0 @@ -{ - // See https://go.microsoft.com//fwlink//?linkid=834763 for more information about this file. - "configurations": [ - { - "name": "x64-Debug", - "generator": "Visual Studio 16 2019", - "configurationType": "Debug", - "inheritEnvironments": [ "msvc_x64_x64" ], - "buildRoot": "${thisFileDir}\\build\\${name}", - "cmakeCommandArgs": "", - "buildCommandArgs": "-v:minimal", - "ctestCommandArgs": "", - "variables": [ - { - "name": "BOOST_ROOT", - "value": "C:\\lib\\boost" - }, - { - "name": "OPENSSL_ROOT", - "value": "C:\\lib\\OpenSSL-Win64" - } - ] - }, - { - "name": "x64-Release", - "generator": "Visual Studio 16 2019", - "configurationType": "Release", - "inheritEnvironments": [ "msvc_x64_x64" ], - "buildRoot": "${thisFileDir}\\build\\${name}", - "cmakeCommandArgs": "", - "buildCommandArgs": "-v:minimal", - "ctestCommandArgs": "", - "variables": [ - { - "name": "BOOST_ROOT", - "value": "C:\\lib\\boost" - }, - { - "name": "OPENSSL_ROOT", - "value": "C:\\lib\\OpenSSL-Win64" - } - ] - } - ] -} diff --git a/Builds/VisualStudio2019/README.md b/Builds/VisualStudio2019/README.md deleted file mode 100644 index e369eac6775..00000000000 --- a/Builds/VisualStudio2019/README.md +++ /dev/null @@ -1,263 +0,0 @@ -# Visual Studio 2019 Build Instructions - -## Important - -We do not recommend Windows for rippled production use at this time. Currently, -the Ubuntu platform has received the highest level of quality assurance, -testing, and support. Additionally, 32-bit Windows versions are not supported. - -## Prerequisites - -To clone the source code repository, create branches for inspection or -modification, build rippled under Visual Studio, and run the unit tests you will -need these software components - -| Component | Minimum Recommended Version | -|-----------|-----------------------| -| [Visual Studio 2019](README.md#install-visual-studio-2019)| 15.5.4 | -| [Git for Windows](README.md#install-git-for-windows)| 2.16.1 | -| [OpenSSL Library](README.md#install-openssl) | 1.1.1L | -| [Boost library](README.md#build-boost) | 1.70.0 | -| [CMake for Windows](README.md#optional-install-cmake-for-windows)* | 3.12 | - -\* Only needed if not using the integrated CMake in VS 2019 and prefer generating dedicated project/solution files. - -## Install Software - -### Install Visual Studio 2019 - -If not already installed on your system, download your choice of installer from -the [Visual Studio 2019 -Download](https://www.visualstudio.com/downloads/download-visual-studio-vs) -page, run the installer, and follow the directions. **You may need to choose the -`Desktop development with C++` workload to install all necessary C++ features.** - -Any version of Visual Studio 2019 may be used to build rippled. The **Visual -Studio 2019 Community** edition is available free of charge (see [the product -page](https://www.visualstudio.com/products/visual-studio-community-vs) for -licensing details), while paid editions may be used for an initial free-trial -period. - -### Install Git for Windows - -Git is a distributed revision control system. The Windows version also provides -the bash shell and many Windows versions of Unix commands. While there are other -varieties of Git (such as TortoiseGit, which has a native Windows interface and -integrates with the Explorer shell), we recommend installing [Git for -Windows](https://git-scm.com/) since it provides a Unix-like command line -environment useful for running shell scripts. Use of the bash shell under -Windows is mandatory for running the unit tests. - -### Install OpenSSL - -[Download the latest version of -OpenSSL.](http://slproweb.com/products/Win32OpenSSL.html) There will -several `Win64` bit variants available, you want the non-light -`v1.1` line. As of this writing, you **should** select - -* Win64 OpenSSL v1.1.1q - -and should **not** select - -* Anything with "Win32" in the name -* Anything with "light" in the name -* Anything with "EXPERIMENTAL" in the name -* Anything in the 3.0 line - rippled won't currently build with this version. - -Run the installer, and choose an appropriate location for your OpenSSL -installation. In this guide we use `C:\lib\OpenSSL-Win64` as the destination -location. - -You may be informed on running the installer that "Visual C++ 2008 -Redistributables" must first be installed first. If so, download it from the -[same page](http://slproweb.com/products/Win32OpenSSL.html), again making sure -to get the correct 32-/64-bit variant. - -* NOTE: Since rippled links statically to OpenSSL, it does not matter where the - OpenSSL .DLL files are placed, or what version they are. rippled does not use - or require any external .DLL files to run other than the standard operating - system ones. - -### Build Boost - -Boost 1.70 or later is required. - -[Download boost](http://www.boost.org/users/download/) and unpack it -to `c:\lib`. As of this writing, the most recent version of boost is 1.80.0, -which will unpack into a directory named `boost_1_80_0`. We recommended either -renaming this directory to `boost`, or creating a junction link `mklink /J boost -boost_1_80_0`, so that you can more easily switch between versions. - -Next, open **Developer Command Prompt** and type the following commands - -```powershell -cd C:\lib\boost -bootstrap -``` - -The rippled application is linked statically to the standard runtimes and -external dependencies on Windows, to ensure that the behavior of the executable -is not affected by changes in outside files. Therefore, it is necessary to build -the required boost static libraries using this command: - -```powershell -b2 -j --toolset=msvc-14.2 address-model=64 architecture=x86 link=static threading=multi runtime-link=shared,static stage -``` - -where you should replace `` with the number of parallel -invocations to use build, e.g. `bjam -j8 ...` would use up to 8 concurrent build -shell commands for the build. - -Building the boost libraries may take considerable time. When the build process -is completed, take note of both the reported compiler include paths and linker -library paths as they will be required later. - -### (Optional) Install CMake for Windows - -[CMake](http://cmake.org) is a cross platform build system generator. Visual -Studio 2019 includes an integrated version of CMake that avoids having to -manually run CMake, but it is undergoing continuous improvement. Users that -prefer to use standard Visual Studio project and solution files need to install -a dedicated version of CMake to generate them. The latest version can be found -at the [CMake download site](https://cmake.org/download/). It is recommended you -select the install option to add CMake to your path. - -## Clone the rippled repository - -If you are familiar with cloning github repositories, just follow your normal -process and clone `git@github.com:ripple/rippled.git`. Otherwise follow this -section for instructions. - -1. If you don't have a github account, sign up for one at - [github.com](https://github.com/). -2. Make sure you have Github ssh keys. For help see - [generating-ssh-keys](https://help.github.com/articles/generating-ssh-keys). - -Open the "Git Bash" shell that was installed with "Git for Windows" in the step -above. Navigate to the directory where you want to clone rippled (git bash uses -`/c` for windows's `C:` and forward slash where windows uses backslash, so -`C:\Users\joe\projs` would be `/c/Users/joe/projs` in git bash). Now clone the -repository and optionally switch to the *master* branch. Type the following at -the bash prompt: - -```powershell -git clone git@github.com:XRPLF/rippled.git -cd rippled -``` -If you receive an error about not having the "correct access rights" make sure -you have Github ssh keys, as described above. - -For a stable release, choose the `master` branch or one of the tagged releases -listed on [rippled's GitHub page](https://github.com/ripple/rippled/releases). - -``` -git checkout master -``` - -To test the latest release candidate, choose the `release` branch. - -``` -git checkout release -``` - -If you are doing development work and want the latest set of beta features, -you can consider using the `develop` branch instead. - -``` -git checkout develop -``` - -# Build using Visual Studio integrated CMake - -In Visual Studio 2017, Microsoft added [integrated IDE support for -cmake](https://blogs.msdn.microsoft.com/vcblog/2016/10/05/cmake-support-in-visual-studio/). -To begin, simply: - -1. Launch Visual Studio and choose **File | Open | Folder**, navigating to the - cloned rippled folder. -2. Right-click on `CMakeLists.txt` in the **Solution Explorer - Folder View** to - generate a `CMakeSettings.json` file. A sample settings file is provided - [here](/Builds/VisualStudio2019/CMakeSettings-example.json). Customize the - settings for `BOOST_ROOT`, `OPENSSL_ROOT` to match the install paths if they - differ from those in the file. -4. Select either the `x64-Release` or `x64-Debug` configuration from the - **Project Settings** drop-down. This should invoke the built-in CMake project - generator. If not, you can right-click on the `CMakeLists.txt` file and - choose **Configure rippled**. -5. Select the `rippled.exe` - option in the **Select Startup Item** drop-down. This will be the target - built when you press F7. Alternatively, you can choose a target to build from - the top-level **CMake | Build** menu. Note that at this time, there are other - targets listed that come from third party visual studio files embedded in the - rippled repo, e.g. `datagen.vcxproj`. Please ignore them. - -For details on configuring debugging sessions or further customization of CMake, -please refer to the [CMake tools for VS -documentation](https://docs.microsoft.com/en-us/cpp/ide/cmake-tools-for-visual-cpp). - -If using the provided `CMakeSettings.json` file, the executable will be in -``` -.\build\x64-Release\Release\rippled.exe -``` -or -``` -.\build\x64-Debug\Debug\rippled.exe -``` -These paths are relative to your cloned git repository. - -# Build using stand-alone CMake - -This requires having installed [CMake for -Windows](README.md#optional-install-cmake-for-windows). We do not recommend -mixing this method with the integrated CMake method for the same repository -clone. Assuming you included the cmake executable folder in your path, -execute the following commands within your `rippled` cloned repository: - -``` -mkdir build\cmake -cd build\cmake -cmake ..\.. -G"Visual Studio 16 2019" -Ax64 -DBOOST_ROOT="C:\lib\boost" -DOPENSSL_ROOT="C:\lib\OpenSSL-Win64" -DCMAKE_GENERATOR_TOOLSET=host=x64 -``` -Now launch Visual Studio 2019 and select **File | Open | Project/Solution**. -Navigate to the `build\cmake` folder created above and select the `rippled.sln` -file. You can then choose whether to build the `Debug` or `Release` solution -configuration. - -The executable will be in -``` -.\build\cmake\Release\rippled.exe -``` -or -``` -.\build\cmake\Debug\rippled.exe -``` -These paths are relative to your cloned git repository. - -# Unity/No-Unity Builds - -The rippled build system defaults to using -[unity source files](http://onqtam.com/programming/2018-07-07-unity-builds/) -to improve build times. In some cases it might be desirable to disable the -unity build and compile individual translation units. Here is how you can -switch to a "no-unity" build configuration: - -## Visual Studio Integrated CMake - -Edit your `CmakeSettings.json` (described above) by adding `-Dunity=OFF` -to the `cmakeCommandArgs` entry for each build configuration. - -## Standalone CMake Builds - -When running cmake to generate the Visual Studio project files, add -`-Dunity=OFF` to the command line options passed to cmake. - -**Note:** you will need to re-run the cmake configuration step anytime you -want to switch between unity/no-unity builds. - -# Unit Test (Recommended) - -`rippled` builds a set of unit tests into the server executable. To run these -unit tests after building, pass the `--unittest` option to the compiled -`rippled` executable. The executable will exit with summary info after running -the unit tests. - diff --git a/Builds/linux/README.md b/Builds/linux/README.md deleted file mode 100644 index 15a84a33e43..00000000000 --- a/Builds/linux/README.md +++ /dev/null @@ -1,269 +0,0 @@ -# Linux Build Instructions - -This document focuses on building rippled for development purposes under recent -Ubuntu linux distributions. To build rippled for Redhat, Fedora or Centos -builds, including docker based builds for those distributions, please consult -the [rippled-package-builder](https://github.com/ripple/rippled-package-builder) -repository. - -Note: Ubuntu 16.04 users may need to update their compiler (see the dependencies -section). For non Ubuntu distributions, the steps below should work by -installing the appropriate dependencies using that distribution's package -management tools. - - -## Dependencies - -gcc-8 or later is required. - -Use `apt-get` to install the dependencies provided by the distribution - -``` -$ apt-get update -$ apt-get install -y gcc g++ wget git cmake pkg-config libprotoc-dev protobuf-compiler libprotobuf-dev libssl-dev -``` - -To build the software in reporting mode, install these additional dependencies: -``` -$ apt-get install -y autoconf flex bison -``` - -Advanced users can choose to install newer versions of gcc, or the clang compiler. - -### Build Boost - -Boost 1.70 or later is required. We recommend downloading and compiling boost -with the following process: After changing to the directory where -you wish to download and compile boost, run -``` -$ wget https://boostorg.jfrog.io/artifactory/main/release/1.70.0/source/boost_1_70_0.tar.gz -$ tar -xzf boost_1_70_0.tar.gz -$ cd boost_1_70_0 -$ ./bootstrap.sh -$ ./b2 headers -$ ./b2 -j $(echo $(nproc)-2 | bc) -``` - -### (Optional) Dependencies for Building Source Documentation - -Source code documentation is not required for running/debugging rippled. That -said, the documentation contains some helpful information about specific -components of the application. For more information on how to install and run -the necessary components, see [this document](../../docs/README.md) - -## Build - -### Clone the rippled repository - -From a shell: - -``` -git clone git@github.com:ripple/rippled.git -cd rippled -``` - -For a stable release, choose the `master` branch or one of the tagged releases -listed on [GitHub](https://github.com/ripple/rippled/releases). - -``` -git checkout master -``` - -or to test the latest release candidate, choose the `release` branch. - -``` -git checkout release -``` - -If you are doing development work and want the latest set of untested -features, you can consider using the `develop` branch instead. - -``` -git checkout develop -``` - -### Configure Library Paths - -If you didn't persistently set the `BOOST_ROOT` environment variable to the -directory in which you compiled boost, then you should set it temporarily. - -For example, if you built Boost in your home directory `~/boost_1_70_0`, you -would run the following shell command: - -``` -export BOOST_ROOT=~/boost_1_70_0 -``` - -Alternatively, you can add `DBOOST_ROOT=~/boost_1_70_0` to the command line when -invoking `cmake`. - -### Generate Configuration - -All builds should be done in a separate directory from the source tree root -(a subdirectory is fine). For example, from the root of the ripple source tree: - -``` -mkdir build -cd build -``` - -followed by: - -``` -cmake -DCMAKE_BUILD_TYPE=Debug .. -``` - -If your operating system does not provide static libraries (Arch Linux, and -Manjaro Linux, for example), you must configure a non-static build by adding -`-Dstatic=OFF` to the above cmake line. - -`CMAKE_BUILD_TYPE` can be changed as desired for `Debug` vs. -`Release` builds (all four standard cmake build types are supported). - -To select a different compiler (most likely gcc will be found by default), pass -`-DCMAKE_C_COMPILER=` and -`-DCMAKE_CXX_COMPILER=` when configuring. If you prefer, -you can instead set `CC` and `CXX` environment variables which cmake will honor. - -#### Options During Configuration: - -The CMake file defines a number of configure-time options which can be -examined by running `cmake-gui` or `ccmake` to generated the build. In -particular, the `unity` option allows you to select between the unity and -non-unity builds. `unity` builds are faster to compile since they combine -multiple sources into a single compiliation unit - this is the default if you -don't specify. `nounity` builds can be helpful for detecting include omissions -or for finding other build-related issues, but aren't generally needed for -testing and running. - -* `-Dunity=ON` to enable/disable unity builds (defaults to ON) -* `-Dassert=ON` to enable asserts -* `-Djemalloc=ON` to enable jemalloc support for heap checking -* `-Dsan=thread` to enable the thread sanitizer with clang -* `-Dsan=address` to enable the address sanitizer with clang -* `-Dstatic=ON` to enable static linking library dependencies -* `-Dreporting=ON` to build code necessary for reporting mode (defaults to OFF) - -Several other infrequently used options are available - run `ccmake` or -`cmake-gui` for a list of all options. - -### Build - -Once you have generated the build system, you can run the build via cmake: - -``` -cmake --build . -- -j $(echo $(nproc)-2 | bc) -``` - -the `-j` parameter in this example tells the build tool to compile several -files in parallel. This value should be chosen roughly based on the number of -cores you have available and/or want to use for building. - -When the build completes successfully, you will have a `rippled` executable in -the current directory, which can be used to connect to the network (when -properly configured) or to run unit tests. - - -#### Optional Installation - -The rippled cmake build supports an installation target that will install -rippled as well as a support library that can be used to sign transactions. In -order to build and install the files, specify the `install` target when -building, e.g.: - -``` -cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/opt/local .. -cmake --build . --target install -- -j $(echo $(nproc)-2 | bc) -``` - -We recommend specifying `CMAKE_INSTALL_PREFIX` when configuring in order to -explicitly control the install location for your files. Without this setting, -cmake will typically install in `/usr/local`. It is also possible to "rehome" -the installation by specifying the `DESTDIR` env variable during the install phase, -e.g.: - -``` -DESTDIR=~/mylibs cmake --build . --target install -- -j $(echo $(nproc)-2 | bc) -``` - -in which case, the files would be installed in the `CMAKE_INSTALL_PREFIX` within -the specified `DESTDIR` path. - -#### Signing Library - -If you want to use the signing support library to create an application, there -are two simple mechanisms with cmake + git that facilitate this. - -With either option below, you will have access to a library from the -rippled project that you can link to in your own project's CMakeLists.txt, e.g.: - -``` -target_link_libraries (my-signing-app Ripple::xrpl_core) -``` - -##### Option 1: git submodules + add_subdirectory - -First, add the rippled repo as a submodule to your project repo: - -``` -git submodule add -b master https://github.com/ripple/rippled.git vendor/rippled -``` - -change the `vendor/rippled` path as desired for your repo layout. Furthermore, -change the branch name if you want to track a different rippled branch, such -as `develop`. - -Second, to bring this submodule into your project, just add the rippled subdirectory: - -``` -add_subdirectory (vendor/rippled) -``` - -##### Option 2: installed rippled + find_package - -First, follow the "Optional Installation" instructions above to -build and install the desired version of rippled. - -To make use of the installed files, add the following to your CMakeLists.txt file: - -``` -set (CMAKE_MODULE_PATH /opt/local/lib/cmake/ripple ${CMAKE_MODULE_PATH}) -find_package(Ripple REQUIRED) -``` - -change the `/opt/local` module path above to match your chosen installation prefix. - -## Unit Tests (Recommended) - -`rippled` builds a set of unit tests into the server executable. To run these unit -tests after building, pass the `--unittest` option to the compiled `rippled` -executable. The executable will exit with summary info after running the unit tests. - -## Workaround for a compile error in soci - -Compilation errors have been observed with Apple Clang 13.1.6+ and soci v4.x. soci compiles with the `-Werror` flag which causes warnings to be treated as errors. These warnings pertain to style (not correctness). However, they cause the cmake process to fail. - -Here's an example of how this looks: -``` -.../rippled/.nih_c/unix_makefiles/AppleClang_13.1.6.13160021/Debug/src/soci/src/core/session.cpp:450:66: note: in instantiation of function template specialization 'soci::use' requested here - return prepare << backEnd_->get_column_descriptions_query(), use(table_name, "t"); - ^ -1 error generated. -``` - -Please apply the below patch (courtesy of Scott Determan) to remove these errors. `.nih_c/unix_makefiles/AppleClang_13.1.6.13160021/Debug/src/soci/cmake/SociConfig.cmake` file needs to be edited. This file is an example for Mac OS and it might be slightly different for other OS/Architectures. - -``` -diff --git a/cmake/SociConfig.cmake b/cmake/SociConfig.cmake -index 97d907e4..11bcd1f3 100644 ---- a/cmake/SociConfig.cmake -+++ b/cmake/SociConfig.cmake -@@ -58,8 +58,8 @@ if (MSVC) - - else() - -- set(SOCI_GCC_CLANG_COMMON_FLAGS -- "-pedantic -Werror -Wno-error=parentheses -Wall -Wextra -Wpointer-arith -Wcast-align -Wcast-qual -Wfloat-equal -Woverloaded-virtual -Wredundant-decls -Wno-long-long") -+ set(SOCI_GCC_CLANG_COMMON_FLAGS "") -+ # "-pedantic -Werror -Wno-error=parentheses -Wall -Wextra -Wpointer-arith -Wcast-align -Wcast-qual -Wfloat-equal -Woverloaded-virtual -Wredundant-decls -Wno-long-long") -``` diff --git a/Builds/macos/README.md b/Builds/macos/README.md deleted file mode 100644 index 2a4e28deb68..00000000000 --- a/Builds/macos/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# macOS Build Instructions - -[Build and Run rippled on macOS](https://xrpl.org/build-run-rippled-macos.html) From 890a1098b83991a0afe09609a4c1a686bc551c12 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Thu, 2 Mar 2023 16:04:35 -0600 Subject: [PATCH 2/7] Refactor build instructions --- BUILD.md | 164 ++++++-------------------------------- docs/build/conan.md | 114 ++++++++++++++++++++++++++ docs/build/environment.md | 83 +++++++++++++++++++ 3 files changed, 221 insertions(+), 140 deletions(-) create mode 100644 docs/build/conan.md create mode 100644 docs/build/environment.md diff --git a/BUILD.md b/BUILD.md index a1376bdc5df..3a7283407d9 100644 --- a/BUILD.md +++ b/BUILD.md @@ -1,122 +1,3 @@ -## A crash course in CMake and Conan - -To better understand how to use Conan, -we should first understand _why_ we use Conan, -and to understand that, -we need to understand how we use CMake. - - -### CMake - -Technically, you don't need CMake to build this project. -You could manually compile every translation unit into an object file, -using the right compiler options, -and then manually link all those objects together, -using the right linker options. -However, that is very tedious and error-prone, -which is why we lean on tools like CMake. - -We have written CMake configuration files -([`CMakeLists.txt`](./CMakeLists.txt) and friends) -for this project so that CMake can be used to correctly compile and link -all of the translation units in it. -Or rather, CMake will generate files for a separate build system -(e.g. Make, Ninja, Visual Studio, Xcode, etc.) -that compile and link all of the translation units. -Even then, CMake has parameters, some of which are platform-specific. -In CMake's parlance, parameters are specially-named **variables** like -[`CMAKE_BUILD_TYPE`][build_type] or -[`CMAKE_MSVC_RUNTIME_LIBRARY`][runtime]. -Parameters include: - -- what build system to generate files for -- where to find the compiler and linker -- where to find dependencies, e.g. libraries and headers -- how to link dependencies, e.g. any special compiler or linker flags that - need to be used with them, including preprocessor definitions -- how to compile translation units, e.g. with optimizations, debug symbols, - position-independent code, etc. -- on Windows, which runtime library to link with - -For some of these parameters, like the build system and compiler, -CMake goes through a complicated search process to choose default values. -For others, like the dependencies, -_we_ had written in the CMake configuration files of this project -our own complicated process to choose defaults. -For most developers, things "just worked"... until they didn't, and then -you were left trying to debug one of these complicated processes, instead of -choosing and manually passing the parameter values yourself. - -You can pass every parameter to CMake on the command line, -but writing out these parameters every time we want to configure CMake is -a pain. -Most humans prefer to put them into a configuration file, once, that -CMake can read every time it is configured. -For CMake, that file is a [toolchain file][toolchain]. - - -### Conan - -These next few paragraphs on Conan are going to read much like the ones above -for CMake. - -Technically, you don't need Conan to build this project. -You could manually download, configure, build, and install all of the -dependencies yourself, and then pass all of the parameters necessary for -CMake to link to those dependencies. -To guarantee ABI compatibility, you must be sure to use the same set of -compiler and linker options for all dependencies _and_ this project. -However, that is very tedious and error-prone, which is why we lean on tools -like Conan. - -We have written a Conan configuration file ([`conanfile.py`](./conanfile.py)) -so that Conan can be used to correctly download, configure, build, and install -all of the dependencies for this project, -using a single set of compiler and linker options for all of them. -It generates files that contain almost all of the parameters that CMake -expects. -Those files include: - -- A single toolchain file. -- For every dependency, a CMake [package configuration file][pcf], - [package version file][pvf], and for every build type, a package - targets file. - Together, these files implement version checking and define `IMPORTED` - targets for the dependencies. - -The toolchain file itself amends the search path -([`CMAKE_PREFIX_PATH`][prefix_path]) so that [`find_package()`][find_package] -will [discover][search] the generated package configuration files. - -**Nearly all we must do to properly configure CMake is pass the toolchain -file.** -What CMake parameters are left out? -You'll still need to pick a build system generator, -and if you choose a single-configuration generator, -you'll need to pass the `CMAKE_BUILD_TYPE`, -which should match the `build_type` setting you gave to Conan. - -Even then, Conan has parameters, some of which are platform-specific. -In Conan's parlance, parameters are either settings or options. -**Settings** are shared by all packages, e.g. the build type. -**Options** are specific to a given package, e.g. whether to build and link -OpenSSL as a shared library. - -For settings, Conan goes through a complicated search process to choose -defaults. -For options, each package recipe defines its own defaults. - -You can pass every parameter to Conan on the command line, -but it is more convenient to put them in a [profile][profile]. -**All we must do to properly configure Conan is edit and pass the profile.** -By default, Conan will use the profile named "default". -You can let Conan create the default profile with this command: - -``` -conan profile new default --detect -``` - - ## Branches For a stable release, choose the `master` branch or one of the [tagged @@ -170,26 +51,29 @@ Until then, we advise Windows developers to use Visual Studio 2019. ## Prerequisites -To build this package, you will need Python (>= 3.7), -[Conan][] (>= 1.55), and [CMake][] (>= 3.16). - > **Warning** -> The commands in this document are not meant to be blindly copied and pasted. -> This document is written for multiple audiences, -> meaning that your particular circumstances may require some commands and not -> others. -> You should never run any commands without understanding what they do -> and why you are running them. +> 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](./docs/build/environment.md). > -> These instructions assume a basic familiarity with Conan and CMake. +> These instructions further assume a basic familiarity with Conan and CMake. > If you are unfamiliar with Conan, -> then please read the [crash course](#a-crash-course-in-cmake-and-conan) -> at the beginning of this document, +> then please read our [crash course](./docs/build/conan.md) > or the official [Getting Started][3] walkthrough. +To build this package, you will need Python (>= 3.7), +[Conan][] (>= 1.55, < 2), and [CMake][] (>= 3.16). + [Conan]: https://conan.io/downloads.html [CMake]: https://cmake.org/download/ +You'll need at least one Conan profile: + +``` +conan profile new default --detect +``` + You'll need to compile in the C++20 dialect: ``` @@ -235,15 +119,21 @@ conan profile update env.CC= default conan profile update env.CXX= default ``` +Export our [Conan recipe for Snappy](./external/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: +Linux or macOS: ``` -conan export external/snappy snappy/1.1.9@ mkdir .build cd .build conan install .. --output-folder . --build missing --settings build_type=Release @@ -256,7 +146,6 @@ The second is for a multi-configuration generator (e.g. Visual Studio) on Windows: ``` -conan export external/snappy snappy/1.1.9@ mkdir .build cd .build conan install .. --output-folder . --build missing --settings build_type=Release --settings compiler.runtime=MT @@ -270,11 +159,6 @@ cmake --build . --config Debug Now to explain the individual steps in each example: -1. Export our [Conan recipe for Snappy](./external/snappy). - - It does not explicitly link the C++ standard library, - which allows us to statically link it. - 1. Create a build directory (and move into it). You can choose any name you want. @@ -327,7 +211,7 @@ Now to explain the individual steps in each example: For a single-configuration generator, it will build whatever configuration you passed for `CMAKE_BUILD_TYPE`. -5. Test rippled. +1. Test rippled. The exact location of rippled in your build directory depends on your choice of CMake generator. diff --git a/docs/build/conan.md b/docs/build/conan.md new file mode 100644 index 00000000000..01fb7150d38 --- /dev/null +++ b/docs/build/conan.md @@ -0,0 +1,114 @@ +## A crash course in CMake and Conan + +To better understand how to use Conan, +we should first understand _why_ we use Conan, +and to understand that, +we need to understand how we use CMake. + + +### CMake + +Technically, you don't need CMake to build this project. +You could manually compile every translation unit into an object file, +using the right compiler options, +and then manually link all those objects together, +using the right linker options. +However, that is very tedious and error-prone, +which is why we lean on tools like CMake. + +We have written CMake configuration files +([`CMakeLists.txt`](./CMakeLists.txt) and friends) +for this project so that CMake can be used to correctly compile and link +all of the translation units in it. +Or rather, CMake will generate files for a separate build system +(e.g. Make, Ninja, Visual Studio, Xcode, etc.) +that compile and link all of the translation units. +Even then, CMake has parameters, some of which are platform-specific. +In CMake's parlance, parameters are specially-named **variables** like +[`CMAKE_BUILD_TYPE`][build_type] or +[`CMAKE_MSVC_RUNTIME_LIBRARY`][runtime]. +Parameters include: + +- what build system to generate files for +- where to find the compiler and linker +- where to find dependencies, e.g. libraries and headers +- how to link dependencies, e.g. any special compiler or linker flags that + need to be used with them, including preprocessor definitions +- how to compile translation units, e.g. with optimizations, debug symbols, + position-independent code, etc. +- on Windows, which runtime library to link with + +For some of these parameters, like the build system and compiler, +CMake goes through a complicated search process to choose default values. +For others, like the dependencies, +_we_ had written in the CMake configuration files of this project +our own complicated process to choose defaults. +For most developers, things "just worked"... until they didn't, and then +you were left trying to debug one of these complicated processes, instead of +choosing and manually passing the parameter values yourself. + +You can pass every parameter to CMake on the command line, +but writing out these parameters every time we want to configure CMake is +a pain. +Most humans prefer to put them into a configuration file, once, that +CMake can read every time it is configured. +For CMake, that file is a [toolchain file][toolchain]. + + +### Conan + +These next few paragraphs on Conan are going to read much like the ones above +for CMake. + +Technically, you don't need Conan to build this project. +You could manually download, configure, build, and install all of the +dependencies yourself, and then pass all of the parameters necessary for +CMake to link to those dependencies. +To guarantee ABI compatibility, you must be sure to use the same set of +compiler and linker options for all dependencies _and_ this project. +However, that is very tedious and error-prone, which is why we lean on tools +like Conan. + +We have written a Conan configuration file ([`conanfile.py`](./conanfile.py)) +so that Conan can be used to correctly download, configure, build, and install +all of the dependencies for this project, +using a single set of compiler and linker options for all of them. +It generates files that contain almost all of the parameters that CMake +expects. +Those files include: + +- A single toolchain file. +- For every dependency, a CMake [package configuration file][pcf], + [package version file][pvf], and for every build type, a package + targets file. + Together, these files implement version checking and define `IMPORTED` + targets for the dependencies. + +The toolchain file itself amends the search path +([`CMAKE_PREFIX_PATH`][prefix_path]) so that [`find_package()`][find_package] +will [discover][search] the generated package configuration files. + +**Nearly all we must do to properly configure CMake is pass the toolchain +file.** +What CMake parameters are left out? +You'll still need to pick a build system generator, +and if you choose a single-configuration generator, +you'll need to pass the `CMAKE_BUILD_TYPE`, +which should match the `build_type` setting you gave to Conan. + +Even then, Conan has parameters, some of which are platform-specific. +In Conan's parlance, parameters are either settings or options. +**Settings** are shared by all packages, e.g. the build type. +**Options** are specific to a given package, e.g. whether to build and link +OpenSSL as a shared library. + +For settings, Conan goes through a complicated search process to choose +defaults. +For options, each package recipe defines its own defaults. + +You can pass every parameter to Conan on the command line, +but it is more convenient to put them in a configuration file, once, that +Conan can read every time it is configured. +For Conan, that file is a [profile][profile]. +**All we must do to properly configure Conan is edit and pass the profile.** +By default, Conan will use the profile named "default". diff --git a/docs/build/environment.md b/docs/build/environment.md new file mode 100644 index 00000000000..8e6ba45aacc --- /dev/null +++ b/docs/build/environment.md @@ -0,0 +1,83 @@ +Our [build instructions][BUILD.md] assume you have a C++ development +environment complete with Git, Python, Conan, CMake, and a C++ compiler. +This document exists to help readers set one up on any of the Big Three +platforms: Linux, macOS, or Windows. + +[BUILD.md]: ../../BUILD.md + + +## Linux + +Package ecosystems vary across Linux distributions, +so there is no one set of instructions that will work for every Linux user. +These instructions are written for Ubuntu 22.04. +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 +apt install --yes curl git libssl-dev python3.10-dev python3-pip make g++-11 + +curl --location --remote-name \ + "https://github.com/Kitware/CMake/releases/download/v3.25.1/cmake-3.25.1.tar.gz" +tar -xzf cmake-3.25.1.tar.gz +rm cmake-3.25.1.tar.gz +cd cmake-3.25.1 +./bootstrap --parallel=$(nproc) +make --jobs $(nproc) +make install +cd .. + +pip3 install 'conan<2' +``` + +[1]: https://github.com/thejohnfreeman/rippled-docker/blob/master/ubuntu-22.04/install.sh + + +## macOS + +Open a Terminal and enter the below command to bring up a dialog to install +the command line developer tools. +Once it is finished, this command should return a version greater than the +minimum required (see [BUILD.md][]). + +``` +clang --version +``` + +The command line developer tools should include Git too: + +``` +git --version +``` + +Install [Homebrew][], +use it to install [pyenv][], +use it to install Python, +and use it to install Conan: + +[Homebrew]: https://brew.sh/ +[pyenv]: https://github.com/pyenv/pyenv + +``` +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +brew update +brew install pyenv +pyenv install 3.10-dev +pyenv global 3.10-dev +eval "$(pyenv init -)" +pip install 'conan<2' +``` + +Install CMake with Homebrew too: + +``` +brew install cmake +``` From e4b27ad56c0edf3dfb502ee1680ecc9c4abc0a6d Mon Sep 17 00:00:00 2001 From: John Freeman Date: Thu, 2 Mar 2023 17:10:45 -0600 Subject: [PATCH 3/7] Add installation instructions --- .gitignore | 3 +-- docs/build/install.md | 13 +++++++++++++ 2 files changed, 14 insertions(+), 2 deletions(-) create mode 100644 docs/build/install.md diff --git a/.gitignore b/.gitignore index 352d68e735e..5e4414e8e62 100644 --- a/.gitignore +++ b/.gitignore @@ -21,7 +21,6 @@ bin/project-cache.jam # Ignore object files. *.o -build .nih_c tags TAGS @@ -65,7 +64,7 @@ docs/html_doc # Xcode user-specific project settings # Xcode .DS_Store -*/build/* +/build/ *.pbxuser !default.pbxuser *.mode1v3 diff --git a/docs/build/install.md b/docs/build/install.md new file mode 100644 index 00000000000..1bdc456b6d8 --- /dev/null +++ b/docs/build/install.md @@ -0,0 +1,13 @@ +## From source + +From a source build, you can install rippled and libxrpl using CMake's +`--install` mode: + +``` +cmake --install . --prefix /opt/local +``` + +The default [prefix][1] is typically `/usr/local` on Linux and macOS and +`C:/Program Files/rippled` on Windows. + +[1]: https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html From c00e879294c1d9a9f9e54b44362257279f176d66 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Fri, 3 Mar 2023 07:46:11 -0600 Subject: [PATCH 4/7] Remove obsolete directory --- Builds/VisualStudio2017/README.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 Builds/VisualStudio2017/README.md diff --git a/Builds/VisualStudio2017/README.md b/Builds/VisualStudio2017/README.md deleted file mode 100644 index fce8e824a05..00000000000 --- a/Builds/VisualStudio2017/README.md +++ /dev/null @@ -1 +0,0 @@ -[Build instructions are currently located in `BUILD.md`](../../BUILD.md) From 03b53ff65284965d6754c96816ba102d9bb0305e Mon Sep 17 00:00:00 2001 From: Michael Legleux Date: Wed, 8 Mar 2023 15:01:16 -0800 Subject: [PATCH 5/7] Add package installation procedure --- docs/build/install.md | 135 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) diff --git a/docs/build/install.md b/docs/build/install.md index 1bdc456b6d8..36fdd72d1b5 100644 --- a/docs/build/install.md +++ b/docs/build/install.md @@ -11,3 +11,138 @@ The default [prefix][1] is typically `/usr/local` on Linux and macOS and `C:/Program Files/rippled` on Windows. [1]: https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html + +## Installation Steps using APT package manager + +1. Update repositories: + + sudo apt update -y + +2. Install utilities: + + sudo apt install -y apt-transport-https ca-certificates wget gnupg + +3. Add Ripple's package-signing GPG key to your list of trusted keys: + + sudo mkdir /usr/local/share/keyrings/ + wget -q -O - "https://repos.ripple.com/repos/api/gpg/key/public" | gpg --dearmor > ripple-key.gpg + sudo mv ripple-key.gpg /usr/local/share/keyrings + + +4. Check the fingerprint of the newly-added key: + + gpg /usr/local/share/keyrings/ripple-key.gpg + + The output should include an entry for Ripple such as the following: + + gpg: WARNING: no command supplied. Trying to guess what you mean ... + pub rsa3072 2019-02-14 [SC] [expires: 2026-02-17] + C0010EC205B35A3310DC90DE395F97FFCCAFD9A2 + uid TechOps Team at Ripple + sub rsa3072 2019-02-14 [E] [expires: 2026-02-17] + + + In particular, make sure that the fingerprint matches. (In the above example, the fingerprint is on the third line, starting with `C001`.) + +4. Add the appropriate Ripple repository for your operating system version: + + echo "deb [signed-by=/usr/local/share/keyrings/ripple-key.gpg] https://repos.ripple.com/repos/rippled-deb focal stable" | \ + sudo tee -a /etc/apt/sources.list.d/ripple.list + + The above example is appropriate for **Ubuntu 20.04 Focal Fossa**. For other operating systems, replace the word `focal` with one of the following: + + - `jammy` for **Ubuntu 22.04 Jammy Jellyfish** + - `bionic` for **Ubuntu 18.04 Bionic Beaver** + - `bullseye` for **Debian 11 Bullseye** + - `buster` for **Debian 10 Buster** + + If you want access to development or pre-release versions of `rippled`, use one of the following instead of `stable`: + + - `unstable` - Pre-release builds ([`release` branch](https://github.com/ripple/rippled/tree/release)) + - `nightly` - Experimental/development builds ([`develop` branch](https://github.com/ripple/rippled/tree/develop)) + + **Warning:** Unstable and nightly builds may be broken at any time. Do not use these builds for production servers. + +5. Fetch the Ripple repository. + + sudo apt -y update + +6. Install the `rippled` software package: + + sudo apt -y install rippled + +7. Check the status of the `rippled` service: + + systemctl status rippled.service + + The `rippled` service should start automatically. If not, you can start it manually: + + sudo systemctl start rippled.service + +8. Optional: allow `rippled` to bind to privileged ports. + + This allows you to serve incoming API requests on port 80 or 443. (If you want to do so, you must also update the config file's port settings.) + + sudo setcap 'cap_net_bind_service=+ep' /opt/ripple/bin/rippled + +## Installation Steps using YUM package manager + +1. Install the Ripple RPM repository: + + Choose the appropriate RPM repository for the stability of releases you want: + + - `stable` for the latest production release (`master` branch) + - `unstable` for pre-release builds (`release` branch) + - `nightly` for experimental/development builds (`develop` branch) + + *Stable* + + cat << REPOFILE | sudo tee /etc/yum.repos.d/ripple.repo + [ripple-stable] + name=XRP Ledger Packages + enabled=1 + gpgcheck=0 + repo_gpgcheck=1 + baseurl=https://repos.ripple.com/repos/rippled-rpm/stable/ + gpgkey=https://repos.ripple.com/repos/rippled-rpm/stable/repodata/repomd.xml.key + REPOFILE + + *Pre-release* + + cat << REPOFILE | sudo tee /etc/yum.repos.d/ripple.repo + [ripple-unstable] + name=XRP Ledger Packages + enabled=1 + gpgcheck=0 + repo_gpgcheck=1 + baseurl=https://repos.ripple.com/repos/rippled-rpm/unstable/ + gpgkey=https://repos.ripple.com/repos/rippled-rpm/unstable/repodata/repomd.xml.key + REPOFILE + + *Development* + + cat << REPOFILE | sudo tee /etc/yum.repos.d/ripple.repo + [ripple-nightly] + name=XRP Ledger Packages + enabled=1 + gpgcheck=0 + repo_gpgcheck=1 + baseurl=https://repos.ripple.com/repos/rippled-rpm/nightly/ + gpgkey=https://repos.ripple.com/repos/rippled-rpm/nightly/repodata/repomd.xml.key + REPOFILE + +2. Fetch the latest repo updates: + + sudo yum -y update + +3. Install the new `rippled` package: + + sudo yum install -y rippled + +4. Configure the `rippled` service to start on boot: + + sudo systemctl enable rippled.service + +5. Start the `rippled` service: + + sudo systemctl start rippled.service From 9959d547b6a4512e442530d9e9cc868e50178d40 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Thu, 23 Mar 2023 10:05:03 -0500 Subject: [PATCH 6/7] Amend install instructions --- docs/build/install.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/build/install.md b/docs/build/install.md index 36fdd72d1b5..eb4859fdee3 100644 --- a/docs/build/install.md +++ b/docs/build/install.md @@ -1,3 +1,11 @@ +This document contains instructions for installing rippled. +The APT package manager is common on Debian-based Linux distributions like +Ubuntu, +while the YUM package manager is common on Red Hat-based Linux distributions +like CentOS. +Installing from source is an option for all platforms, +and the only supported option for installing custom builds. + ## From source From a source build, you can install rippled and libxrpl using CMake's @@ -12,7 +20,7 @@ The default [prefix][1] is typically `/usr/local` on Linux and macOS and [1]: https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html -## Installation Steps using APT package manager +## With the APT package manager 1. Update repositories: @@ -85,7 +93,7 @@ The default [prefix][1] is typically `/usr/local` on Linux and macOS and sudo setcap 'cap_net_bind_service=+ep' /opt/ripple/bin/rippled -## Installation Steps using YUM package manager +## With the YUM package manager 1. Install the Ripple RPM repository: From 5ed671931de281c34e3ba885cfb735a9963cc88a Mon Sep 17 00:00:00 2001 From: John Freeman Date: Fri, 24 Mar 2023 14:31:28 -0500 Subject: [PATCH 7/7] Adopt suggestions --- docs/build/install.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/install.md b/docs/build/install.md index a0f0d1521d8..af0d6f335c0 100644 --- a/docs/build/install.md +++ b/docs/build/install.md @@ -118,7 +118,7 @@ The default [prefix][1] is typically `/usr/local` on Linux and macOS and gpgkey=https://repos.ripple.com/repos/rippled-rpm/stable/repodata/repomd.xml.key REPOFILE - *Pre-release* + *Unstable* cat << REPOFILE | sudo tee /etc/yum.repos.d/ripple.repo [ripple-unstable] @@ -130,7 +130,7 @@ The default [prefix][1] is typically `/usr/local` on Linux and macOS and gpgkey=https://repos.ripple.com/repos/rippled-rpm/unstable/repodata/repomd.xml.key REPOFILE - *Development* + *Nightly* cat << REPOFILE | sudo tee /etc/yum.repos.d/ripple.repo [ripple-nightly]