From 08fef38ea0129ab5f244f85381a8653c093d40db Mon Sep 17 00:00:00 2001 From: John Freeman Date: Thu, 5 Jan 2023 18:27:53 -0600 Subject: [PATCH] Update build instructions (#4376) Document minimum compiler version; how to choose compiler; how to fix missing `std::result_of`; how to create Conan profile. --- BUILD.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 77 insertions(+), 7 deletions(-) diff --git a/BUILD.md b/BUILD.md index c686c0a51b4..76ed7f4595b 100644 --- a/BUILD.md +++ b/BUILD.md @@ -23,9 +23,21 @@ git checkout develop ## Platforms -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 development is not supported. +rippled is written in the C++20 dialect and includes the `` header. +The [minimum compiler versions][2] 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, @@ -50,7 +62,7 @@ there is a crash course at the end of this document. You'll need to compile in the C++20 dialect: ``` -conan profile update settings.cppstd=20 default +conan profile update settings.compiler.cppstd=20 default ``` Linux developers will commonly have a default Conan [profile][] that compiles @@ -73,6 +85,25 @@ 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__COMPILER`) in the +generated CMake toolchain file: + +``` +conan profile update 'conf.tools.build:compiler_executables={"c": "", "cpp": ""}' 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= default +conan profile update env.CXX= default +``` + ## How to build and test @@ -190,20 +221,52 @@ with their default values in parentheses. - `reporting` (OFF): Build the reporting mode feature. - `tests` (ON): Build tests. - `unity` (ON): Configure a [unity build][5]. +- `san` (): Enable a sanitizer with Clang. Choices are `thread` and `address`. ### Troubleshooting -If you get a linker error like the one below suggesting that you recompile +#### 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 'env.CFLAGS="-DBOOST_ASIO_HAS_STD_INVOKE_RESULT"' default +conan profile update 'env.CXXFLAGS="-DBOOST_ASIO_HAS_STD_INVOKE_RESULT"' default +conan profile update 'tools.build:cflags+=["-DBOOST_ASIO_HAS_STD_INVOKE_RESULT"]' default +conan profile update '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][1] 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`. +when calling `conan install`: ``` -/usr/bin/ld.gold: error: /home/username/.conan/data/boost/1.77.0/_/_/package/dc8aedd23a0f0a773a5fcdcfe1ae3e89c4205978/lib/libboost_container.a(alloc_lib.o): requires unsupported dynamic reloc 11; recompile with -fPIC +conan install --build boost ... ``` @@ -336,9 +399,16 @@ 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 +``` [1]: https://github.com/conan-io/conan-center-index/issues/13168 +[2]: https://en.cppreference.com/w/cpp/compiler_support/20 [5]: https://en.wikipedia.org/wiki/Unity_build [build_type]: https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html [runtime]: https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html