docs: Update instructions how to (re)generate conan.lock file (#6070)

This change updates the instructions for how to generate a Conan lockfile that is compatible with Linux, macOS, and Windows.

Whenever Conan dependencies change, the Conan lock file needs to be regenerated. However, different OSes have slightly different requirements, and thus require slightly different dependencies. Luckily a single `conan.lock` file can be used, as long as the union of dependencies is included.

The current instructions in the `BUILD.md` file are insufficient to regenerate the lock file such that it is compatible with all OSes, which this change addresses. The three profiles contain the bare minimum needed to generate the lockfile; it does not particularly matter whether the build type is Debug or Release, for instance.

Author: bthomee

BUILD.md

@@ -88,6 +88,13 @@ These instructions assume a basic familiarity with Conan and CMake. If you are
 unfamiliar with Conan, then please read [this crash course](./docs/build/conan.md) or the official
 [Getting Started][3] walkthrough.
 
+#### Conan lockfile
+
+To achieve reproducible dependencies, we use a [Conan lockfile](https://docs.conan.io/2/tutorial/versioning/lockfiles.html),
+which has to be updated every time dependencies change.
+
+Please see the [instructions on how to regenerate the lockfile](conan/lockfile/README.md).
+
 #### Default profile
 
 We recommend that you import the provided `conan/profiles/default` profile:
@@ -450,33 +457,6 @@ tools.build:cxxflags=['-DBOOST_ASIO_DISABLE_CONCEPTS']
    The location of `rippled` binary in your build directory depends on your
    CMake generator. Pass `--help` to see the rest of the command line options.
 
-#### Conan lockfile
-
-To achieve reproducible dependencies, we use [Conan lockfile](https://docs.conan.io/2/tutorial/versioning/lockfiles.html).
-
-The `conan.lock` file in the repository contains a "snapshot" of the current dependencies.
-It is implicitly used when running `conan` commands, you don't need to specify it.
-
-You have to update this file every time you add a new dependency or change a revision or version of an existing dependency.
-
-> [!NOTE]
-> Conan uses local cache by default when creating a lockfile.
->
-> To ensure, that lockfile creation works the same way on all developer machines, you should clear the local cache before creating a new lockfile.
-
-To create a new lockfile, run the following commands in the repository root:
-
-```bash
-conan remove '*' --confirm
-rm conan.lock
-# This ensure that xrplf remote is the first to be consulted
-conan remote add --force --index 0 xrplf https://conan.ripplex.io
-conan lock create . -o '&:jemalloc=True' -o '&:rocksdb=True'
-```
-
-> [!NOTE]
-> If some dependencies are exclusive for some OS, you may need to run the last command for them adding `--profile:all <PROFILE>`.
-
 ## Coverage report
 
 The coverage report is intended for developers using compilers GCC

conan/lockfile/README.md

@@ -0,0 +1,42 @@
+# Conan lockfile
+
+To achieve reproducible dependencies, we use a [Conan lockfile](https://docs.conan.io/2/tutorial/versioning/lockfiles.html).
+
+The `conan.lock` file in the repository contains a "snapshot" of the current
+dependencies. It is implicitly used when running `conan` commands, so you don't
+need to specify it.
+
+You have to update this file every time you add a new dependency or change a
+revision or version of an existing dependency.
+
+## Updating the lockfile
+
+To update a lockfile, run the following commands from the repository root:
+
+```bash
+# Ensure that the xrplf remote is the first to be consulted, so any recipes we
+# patched are used. We also add it there to not created huge diff when the
+# official Conan Center Index is updated.
+conan remote add --force --index 0 xrplf https://conan.ripplex.io
+
+# Remove all local packages to prevent the local cache from influencing the
+# lockfile.
+conan remove '*' --confirm
+
+# Create a new lockfile that is compatible with Linux, macOS, and Windows. The
+# first create command will create a new lockfile, while the subsequent create
+# commands will merge any additional dependencies into the created lockfile.
+rm conan.lock
+conan lock create . \
+  --options '&:jemalloc=True' \
+  --options '&:rocksdb=True' \
+  --profile:all=conan/lockfile/linux.profile
+conan lock create . \
+  --options '&:jemalloc=True' \
+  --options '&:rocksdb=True' \
+  --profile:all=conan/lockfile/macos.profile
+conan lock create . \
+  --options '&:jemalloc=True' \
+  --options '&:rocksdb=True' \
+  --profile:all=conan/lockfile/windows.profile
+```

conan/lockfile/linux.profile

@@ -0,0 +1,8 @@
+[settings]
+arch=x86_64
+build_type=Release
+compiler=gcc
+compiler.cppstd=20
+compiler.libcxx=libstdc++11
+compiler.version=13
+os=Linux

conan/lockfile/macos.profile

@@ -0,0 +1,8 @@
+[settings]
+arch=armv8
+build_type=Release
+compiler=apple-clang
+compiler.cppstd=20
+compiler.libcxx=libc++
+compiler.version=17.0
+os=Macos

conan/lockfile/windows.profile

@@ -0,0 +1,9 @@
+[settings]
+arch=x86_64
+build_type=Release
+compiler=msvc
+compiler.cppstd=20
+compiler.runtime=dynamic
+compiler.runtime_type=Release
+compiler.version=194
+os=Windows