docs: update build instructions: (#4381)

* Remove obsolete build instructions.
* By using Conan, builders can choose which dependencies specifically to
  build and link as shared objects.
* Refactor the build instructions based on the plan in #4433.

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".

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
+```

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