From 9d2730ca0e6d09dd91a548780a3c6450a2bceb4c Mon Sep 17 00:00:00 2001 From: JScottBranson Date: Thu, 30 Oct 2025 14:53:35 -0400 Subject: [PATCH 01/25] Update the index page for building. --- .../docs/infrastructure/building-xahau/index.mdx | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/content/docs/docs/infrastructure/building-xahau/index.mdx b/src/content/docs/docs/infrastructure/building-xahau/index.mdx index 12a6f91..6f8d09b 100644 --- a/src/content/docs/docs/infrastructure/building-xahau/index.mdx +++ b/src/content/docs/docs/infrastructure/building-xahau/index.mdx @@ -1,9 +1,15 @@ --- title: Building Xahau -description: A Guide to Setting Up the Development Environment. +description: Setting Up the xahaud Build Environment --- -This section provides detailed instructions for setting up the build environment on both Ubuntu 22.04 and macOS 13.5.2. -The building Xahau chapter will guide you through the process of establishing environmental variables, installing core and **Xahaud** dependencies, and compiling the software, including the acquisition and setup of essential components like LLVM, Boost, WasmEdge, and Protobuf. +Building software, such as xahaud, from the openly available source code is a complex process that requires in-depth knowledge and experience. Thus, there are multiple approaches that developers might take, depending on the environment (e.g., Linux, MacOS, Windows). The instructions in the following documentation chapters are meant to simplify and expand on those in the [xahaud GitHub repository](https://github.com/Xahau/xahaud/blob/dev/BUILD.md). Developers might need to deviate from these instructions to accomplish specific tasks or to ensure compatibility with specific operating systems. -The steps explain why certain versions and configurations are needed to ensure compatibility and optimal performance. Ending with cloning the Xahau repository and creating the **Xahaud** target, which sets developers on the path to adding to or deploying the Xahau network. +## Basics of Building Software from Source +When developers write software, they do so in programming languages that are designed to be human readable. However, it is not efficient for computers to run this human readable code. Thus, there is a need for software to be "compiled" from human readable code into bytecode that can be quickly read and interpreted by a computer. + +Adding complexity to this process, developers often rely on software that was written by other developers, called "dependencies" because one software package depends on (requires) the other. In order for these dependencies to be included in the final product, they must be "linked" to the code before the code is compiled. The linking process can be very intensive, as dependencies for the original software package might have their own dependencies (which in turn can have even more dependencies, adding layers). Developers rely on tools, such as Conan, to simplify the process of locating, configuring, and linking dependencies. + +The entire process of ensuring dependencies are met, compiling software into a machine optimized format, and running tests against the final product is called "building". + +Since xahaud is [published as open source software on GitHub](https://github.com/Xahau/xahaud), anyone may view, audit, modify, build, and run the code. Building from the source code enables certainty that the product being run is based off of the publicly viewable source code, which also has a full audit trail. Thus, validator operators who prioritize a maximum level of security should consider building from source. From 4b5484fcd663f427243112b6a21c965b093e4183 Mon Sep 17 00:00:00 2001 From: JScottBranson Date: Thu, 30 Oct 2025 15:04:18 -0400 Subject: [PATCH 02/25] Update navigation to avoid specific OS versions. --- astro.config.mjs | 4 ++-- .../docs/docs/infrastructure/building-xahau/index.mdx | 2 ++ .../building-xahau/{mac-os-13-5-2.mdx => macos.mdx} | 7 +------ .../building-xahau/{ubuntu-22-04.mdx => ubuntu.mdx} | 7 +------ 4 files changed, 6 insertions(+), 14 deletions(-) rename src/content/docs/docs/infrastructure/building-xahau/{mac-os-13-5-2.mdx => macos.mdx} (94%) rename src/content/docs/docs/infrastructure/building-xahau/{ubuntu-22-04.mdx => ubuntu.mdx} (93%) diff --git a/astro.config.mjs b/astro.config.mjs index f2f74bb..73b53a7 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -292,8 +292,8 @@ export default defineConfig({ collapsed: true, items: [ 'docs/infrastructure/building-xahau', - 'docs/infrastructure/building-xahau/ubuntu-22-04', - 'docs/infrastructure/building-xahau/mac-os-13-5-2', + 'docs/infrastructure/building-xahau/ubuntu', + 'docs/infrastructure/building-xahau/macos', ], }, ], diff --git a/src/content/docs/docs/infrastructure/building-xahau/index.mdx b/src/content/docs/docs/infrastructure/building-xahau/index.mdx index 6f8d09b..71808e9 100644 --- a/src/content/docs/docs/infrastructure/building-xahau/index.mdx +++ b/src/content/docs/docs/infrastructure/building-xahau/index.mdx @@ -5,6 +5,8 @@ description: Setting Up the xahaud Build Environment Building software, such as xahaud, from the openly available source code is a complex process that requires in-depth knowledge and experience. Thus, there are multiple approaches that developers might take, depending on the environment (e.g., Linux, MacOS, Windows). The instructions in the following documentation chapters are meant to simplify and expand on those in the [xahaud GitHub repository](https://github.com/Xahau/xahaud/blob/dev/BUILD.md). Developers might need to deviate from these instructions to accomplish specific tasks or to ensure compatibility with specific operating systems. +The following articles detail the process of setting up a build environment and building xahaud across various operating system environments. + ## Basics of Building Software from Source When developers write software, they do so in programming languages that are designed to be human readable. However, it is not efficient for computers to run this human readable code. Thus, there is a need for software to be "compiled" from human readable code into bytecode that can be quickly read and interpreted by a computer. diff --git a/src/content/docs/docs/infrastructure/building-xahau/mac-os-13-5-2.mdx b/src/content/docs/docs/infrastructure/building-xahau/macos.mdx similarity index 94% rename from src/content/docs/docs/infrastructure/building-xahau/mac-os-13-5-2.mdx rename to src/content/docs/docs/infrastructure/building-xahau/macos.mdx index 297000c..78fbd43 100644 --- a/src/content/docs/docs/infrastructure/building-xahau/mac-os-13-5-2.mdx +++ b/src/content/docs/docs/infrastructure/building-xahau/macos.mdx @@ -1,11 +1,6 @@ --- -title: Mac OS - 15.3.2 (24D81) +title: macOS --- -import { Aside } from '@astrojs/starlight/components'; - - ## CMake Legacy Building diff --git a/src/content/docs/docs/infrastructure/building-xahau/ubuntu-22-04.mdx b/src/content/docs/docs/infrastructure/building-xahau/ubuntu.mdx similarity index 93% rename from src/content/docs/docs/infrastructure/building-xahau/ubuntu-22-04.mdx rename to src/content/docs/docs/infrastructure/building-xahau/ubuntu.mdx index 528c9ac..da63a53 100644 --- a/src/content/docs/docs/infrastructure/building-xahau/ubuntu-22-04.mdx +++ b/src/content/docs/docs/infrastructure/building-xahau/ubuntu.mdx @@ -1,11 +1,6 @@ --- -title: Ubuntu - 22.04 +title: Ubuntu --- -import { Aside } from '@astrojs/starlight/components'; - - ## CMake Legacy Building From 83ac16023f63f8099e6c884d3de3e8fe06d26486 Mon Sep 17 00:00:00 2001 From: JScottBranson Date: Thu, 30 Oct 2025 20:00:09 -0400 Subject: [PATCH 03/25] Minor changes, including adding links and renaming the build chapter from 'xahau' to 'xahaud'. --- astro.config.mjs | 8 ++++---- .../{building-xahau => building-xahaud}/index.mdx | 2 +- .../{building-xahau => building-xahaud}/macos.mdx | 0 .../{building-xahau => building-xahaud}/ubuntu.mdx | 0 .../docs/docs/infrastructure/enabling-validation.mdx | 2 +- .../docs/docs/infrastructure/installing-xahaud.mdx | 4 ++-- .../docs/docs/infrastructure/system-requirements.mdx | 2 +- 7 files changed, 9 insertions(+), 9 deletions(-) rename src/content/docs/docs/infrastructure/{building-xahau => building-xahaud}/index.mdx (99%) rename src/content/docs/docs/infrastructure/{building-xahau => building-xahaud}/macos.mdx (100%) rename src/content/docs/docs/infrastructure/{building-xahau => building-xahaud}/ubuntu.mdx (100%) diff --git a/astro.config.mjs b/astro.config.mjs index 73b53a7..9e2449d 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -288,12 +288,12 @@ export default defineConfig({ 'docs/infrastructure/interacting', 'docs/infrastructure/advanced-configuration', { - label: 'Building Xahau (Dev)', + label: 'Building xahaud (Advanced)', collapsed: true, items: [ - 'docs/infrastructure/building-xahau', - 'docs/infrastructure/building-xahau/ubuntu', - 'docs/infrastructure/building-xahau/macos', + 'docs/infrastructure/building-xahaud', + 'docs/infrastructure/building-xahaud/ubuntu', + 'docs/infrastructure/building-xahaud/macos', ], }, ], diff --git a/src/content/docs/docs/infrastructure/building-xahau/index.mdx b/src/content/docs/docs/infrastructure/building-xahaud/index.mdx similarity index 99% rename from src/content/docs/docs/infrastructure/building-xahau/index.mdx rename to src/content/docs/docs/infrastructure/building-xahaud/index.mdx index 71808e9..b7753da 100644 --- a/src/content/docs/docs/infrastructure/building-xahau/index.mdx +++ b/src/content/docs/docs/infrastructure/building-xahaud/index.mdx @@ -1,5 +1,5 @@ --- -title: Building Xahau +title: Building xahaud description: Setting Up the xahaud Build Environment --- diff --git a/src/content/docs/docs/infrastructure/building-xahau/macos.mdx b/src/content/docs/docs/infrastructure/building-xahaud/macos.mdx similarity index 100% rename from src/content/docs/docs/infrastructure/building-xahau/macos.mdx rename to src/content/docs/docs/infrastructure/building-xahaud/macos.mdx diff --git a/src/content/docs/docs/infrastructure/building-xahau/ubuntu.mdx b/src/content/docs/docs/infrastructure/building-xahaud/ubuntu.mdx similarity index 100% rename from src/content/docs/docs/infrastructure/building-xahau/ubuntu.mdx rename to src/content/docs/docs/infrastructure/building-xahaud/ubuntu.mdx diff --git a/src/content/docs/docs/infrastructure/enabling-validation.mdx b/src/content/docs/docs/infrastructure/enabling-validation.mdx index 7922ac6..a214b92 100644 --- a/src/content/docs/docs/infrastructure/enabling-validation.mdx +++ b/src/content/docs/docs/infrastructure/enabling-validation.mdx @@ -30,7 +30,7 @@ The Xahau Network utilizes the [Governance Game](../../features/governance-game) Switching a stock xahaud server into a validator is a straight forward process. Essentially, users will generate a public/private keypair, which is then used to generate a token using an ephemeral key derived from the master pair. That token is installed into the `xahaud.cfg` file, thereby instructing xahaud to propose validations to the Network. ### Building the Validation Keys Tool -At this time, there is not an official release of the software used for generating validation keys. Thus, users can either build the tool from scratch or rely on a packaged version provided with rippled (this tool is not packaged with the xahaud binary). The instructions for building the tool are the same as the instructions for building rippled, and they are provided on the [ripple/validator-keys-tool](https://github.com/ripple/validator-keys-tool) repository page. There are also some [packaged binaries](https://github.com/jscottbranson/xahau-examples/) available in unofficial repositories. Users seeking to generate keys for production validators should build the tool from scratch on a secure, air-gapped machine. +At this time, there is not an official release of the software used for generating validation keys. Thus, users can either build the tool from scratch or rely on a packaged version provided with rippled (this tool is not packaged with the xahaud binary). The instructions for building the tool are the same as the instructions for [building xahaud](../building-xahaud), and they are provided on the [ripple/validator-keys-tool](https://github.com/ripple/validator-keys-tool) repository page. There are also some [packaged binaries](https://github.com/jscottbranson/xahau-examples/) available in unofficial repositories. Users seeking to generate keys for production validators should build the tool from scratch on a secure, air-gapped machine. While xahaud provides the `validation_create` [Admin API method](../../features/http-websocket-apis/admin-api-methods), this method is NOT capable of generating the necessary validation token or allowing for domain verification. Thus, despite the name, the `validation_create` method is used to create public/private keys to identify a server broadly, for example when [clustering multiple servers](../advanced-configuration). diff --git a/src/content/docs/docs/infrastructure/installing-xahaud.mdx b/src/content/docs/docs/infrastructure/installing-xahaud.mdx index 329fa09..cd69e44 100644 --- a/src/content/docs/docs/infrastructure/installing-xahaud.mdx +++ b/src/content/docs/docs/infrastructure/installing-xahaud.mdx @@ -53,8 +53,8 @@ This peering is relevant for both Docker containers and local installations. Docker Containerhttps://github.com/Xahau/mainnet-dockerhttps://github.com/Xahau/Xahau-Testnet-Docker Local Install Scriptshttps://raw.githubusercontent.com/Xahau/mainnet-docker/refs/heads/main/xahaud-install-update.shhttps://github.com/Xahau/Xahau-Testnet-Docker/blob/main/xahaud-install-update.sh Binary Releaseshttps://build.xahau.techSame as Mainnet -Sample Configuration Filehttps://github.com/Xahau/mainnet-docker/blob/main/store/etc/xahaud.sample.cfghttps://github.com/Xahau/Xahau-Testnet-Docker/blob/main/store/etc/xahaud.cfg -Sample Trusted Validators (UNL) Filehttps://github.com/Xahau/mainnet-docker/blob/main/store/etc/validators-xahau.sample.txthttps://github.com/Xahau/Xahau-Testnet-Docker/blob/main/store/etc/validators-xahau.txt +Sample Configuration Filehttps://github.com/Xahau/xahaud/blob/dev/cfg/xahaud-example.cfghttps://github.com/Xahau/Xahau-Testnet-Docker/blob/main/store/etc/xahaud.cfg +Sample Trusted Validators (UNL) Filehttps://github.com/Xahau/xahaud/blob/dev/cfg/validators-example.txthttps://github.com/Xahau/Xahau-Testnet-Docker/blob/main/store/etc/validators-xahau.txt Documented Configuration Fileshttps://github.com/Xahau/xahaud/tree/dev/cfgSame as Mainnet Github Build Actions (release numbers)https://github.com/Xahau/xahaud/actions?query=branch%3Arelease+is%3Asuccess+build+using+dockerSame as Mainnet diff --git a/src/content/docs/docs/infrastructure/system-requirements.mdx b/src/content/docs/docs/infrastructure/system-requirements.mdx index 8933bc5..fc60613 100644 --- a/src/content/docs/docs/infrastructure/system-requirements.mdx +++ b/src/content/docs/docs/infrastructure/system-requirements.mdx @@ -17,7 +17,7 @@ It is possible to run xahaud in diverse configurations, based on a users needs. * Machines storing full history must use XFS or similar to avoid limitations with single file size in EXT4 (max. file size of 16TB). If storing less history, EXT4 is sufficient. * It may be possible to run xahaud on machines that do not meet the below "Minimum" specifications for production servers. However, doing so risks instability. * These system requirements may grow over time. For example, disk space for full history servers is consistently increasing. -* As of August 6, 2025 the full history for the Xahau Network is approximately 8TB. +* As of November 1, 2025 the full history for the Xahau Network is 10TB. ## Recommended Specs for Production xahaud Servers From 506876fbb12c14b68fb803637e168240354c9b76 Mon Sep 17 00:00:00 2001 From: JScottBranson Date: Wed, 5 Nov 2025 13:04:42 -0500 Subject: [PATCH 04/25] Stash edits to the Linux build instructions. --- astro.config.mjs | 2 +- .../infrastructure/building-xahaud/linux.mdx | 115 +++++++++++++ .../infrastructure/building-xahaud/ubuntu.mdx | 161 ------------------ 3 files changed, 116 insertions(+), 162 deletions(-) create mode 100644 src/content/docs/docs/infrastructure/building-xahaud/linux.mdx delete mode 100644 src/content/docs/docs/infrastructure/building-xahaud/ubuntu.mdx diff --git a/astro.config.mjs b/astro.config.mjs index 9e2449d..dd857dd 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -292,7 +292,7 @@ export default defineConfig({ collapsed: true, items: [ 'docs/infrastructure/building-xahaud', - 'docs/infrastructure/building-xahaud/ubuntu', + 'docs/infrastructure/building-xahaud/linux', 'docs/infrastructure/building-xahaud/macos', ], }, diff --git a/src/content/docs/docs/infrastructure/building-xahaud/linux.mdx b/src/content/docs/docs/infrastructure/building-xahaud/linux.mdx new file mode 100644 index 0000000..d53fdd0 --- /dev/null +++ b/src/content/docs/docs/infrastructure/building-xahaud/linux.mdx @@ -0,0 +1,115 @@ +--- +title: Linux Build Instructions +--- +import { Aside } from '@astrojs/starlight/components'; + + + +These instructions are designed to work for Debian and Red Hat (9 or 10) based Linux distributions. While some instructions overlap, differences across operating systems are noted. While efforts are made to test builds across operating systems, Ubuntu is the most tested and supported environment for building and running xahaud. + +For additional instructions, refer to the [BUILD.md](https://github.com/Xahau/xahaud/blob/dev/BUILD.md) in the Xahau/xahaud Github Repository. + +## The Build Environment + +Maintaining different build environments (Python3 venvs, Conan2 profiles, etc.) is a complex task, even more so as underlying operating systems often rely on or expect specific versions of software. Thus, those new to the build process may benefit from writing bash scripts that are used on machines that reset their state at reboot. Configuring a Linux system to completely forget all the software that was installed or modified during runtime provides an easy path to recover from build errors. Typically, an amnesiac operating system is run as a virtual machine with a very large amount of memory available, as all changes are written to memory instead of disk. Building xahaud can take close to 32GB of memory, if all software dependencies/requirements are installed in a memory based overlay file system. + +It is also possible to use Docker or other container systems to create specific build environments. + +The following subsections address configuring build environments with the required software dependencies. + +### Containerized Environments +Will go here... + +### Amnesiac Operating System Environments + +To configure an amnesic operating system using Debian based systems: +``` +# Install the 'overlayroot' software package +apt update && apt install overlayroot + +# Update the configuration file to enable an in-memory overlay file system +sudo sed -i 's/^overlayroot=.*/overlayroot="tmpfs:swap=1,recurse=0"/' /etc/overlayroot.conf + +# Rebuild initramfs +update-initramfs -u +``` + +To configure an amnesic operating system using RHEL 9/10 based systems: +``` +# Ensure dracut is installed +dnf install dracut -y + +# Configure dracut to support the overlay +printf 'add_drivers+=" overlay "\n' > /etc/dracut.conf.d/overlay.conf # Use this line for RHEL 9 +printf 'add_drivers+=" overlay "\nadd_dracutmodules+=" overlayfs "\n' > /etc/dracut.conf.d/overlay.conf # Use this line for RHEL 10 + +# Rebuild +dracut -f + +# Update the boot image to use a systemd volatile overlay +grubby --update-kernel=ALL --args="systemd.volatile=overlay" +``` +To disable amnesia on Debian based systems: +1. Hold `Shift` or `Esc` during boot to enter the GRUB menu (be careful not to enter the BIOS by pressing `Esc` before the firmware logo). +2. Press `e` to edit the Ubuntu boot entry. +3. Edit only the `overlayroot=` option to read `overlayroot=disabled`. This will allow a one-time boot into a system with a memory. +4. To permanently disable amnesia, run `sudo sed -i '/^overlayroot=/c\overlayroot="disabled"' /etc/overlayroot.conf` to change `overlayroot="disabled"` in the /etc/overlayroot.conf file. Then update initramfs `sudo update-initramfs -u`. + +To disable amnesia on RHEL 9/10 based systems: +1. Press `e` at the boot menu to edit the options. +2. Remove the "systemd.volatile=overlay" option. +3. Press `F10` to boot. +4. To permanently disable amnesia, run `grubby --update-kernel=ALL --remove-args="systemd.volatile=overlay"` + +### Installing Dependencies + +For compatibility, it is important to attend to specific versions of software used in the build process. Current requirements include: + + +| Dependency | Version | +| :---------- | :-------- | +| Python3 | >= 3.10 | +| Conan | >= 2.x | +| Ninja Build | ? | +| GCC / G++ | >= 11.x | +| CMake | >= 3.16 | + +| Dependency | Working Version | +| ---------- | --------------- | +| GCC / G++ | 14.0.3 | +| LLVM | 14.0.3 | +| LLD | 14.0.3 | +| Boost | 1.86.0 | +| CMake | 3.23.1 | +| Protobuf | 3.20.0 | +| WasmEdge | 0.11.2 | + + +Debian/Ubuntu users can install required dependencies using these commands: +``` +sudo apt install -y git curl wget python3-pip python3-venv python3-dev ca-certificates gcc g++ build-essential cmake ninja-build libc6-dev libssl-dev libsqlite3-dev +``` + +Likewise, RHEL 9 or RHEL 10 users can install dependencies: +``` +sudo dnf install epel-release && sudo dnf update -y +sudo dnf config-manager --set-enabled crb -y +sudo dnf install curl wget git ca-certificates cmake glibc-headers glibc-devel ninja-build perl-interpreter perl perl-FindBin sqlite-devel -y +sudo dnf groupinstall "Development Tools" -y +``` + +## Clone the Xahau/xahaud GitHub Repository +Before building, acquire a local copy of the GitHub xahaud repository: + +`git clone https://github.com/Xahau/xahaud.git` + +It is possible to build from other forks of the repository, simply adjust the above URL as needed. + +### Select the Repository Branch +The primary branch used for xahaud development is `dev`. Users who prefer to build from an alternate branch can do so: + +`git checkout [branch name]` + +## Installing Conan2 +will go here... + diff --git a/src/content/docs/docs/infrastructure/building-xahaud/ubuntu.mdx b/src/content/docs/docs/infrastructure/building-xahaud/ubuntu.mdx deleted file mode 100644 index da63a53..0000000 --- a/src/content/docs/docs/infrastructure/building-xahaud/ubuntu.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Ubuntu ---- - -## CMake Legacy Building - -| Dependency | Working Version | -| ---------- | --------------- | -| GCC / G++ | 14.0.3 | -| LLVM | 14.0.3 | -| LLD | 14.0.3 | -| Boost | 1.86.0 | -| CMake | 3.23.1 | -| Protobuf | 3.20.0 | -| WasmEdge | 0.11.2 | - -### Set Build Env Variables - -First make a dependency directory. I like to use `~/dependencies` - -``` -mkdir ~/dependencies -``` - -Next we need to set the environment variables. - -### Set Versions Env Variables - - - -``` -export UBUNTU_VERSION=jammy -export LLVM_VERSION=14 -export CMAKE_VERSION=3.23.1 -export BOOST_VERSION=1.86.0 -export WASMEDGE_VERSION=0.11.2 -export PROTOBUF_VERSION=3.20.0 -``` - -### Set Build Env Variables - -``` -export DEP_DIR=~/dependencies -export BOOST_FOLDER_NAME="boost_$(echo "$BOOST_VERSION" | sed 's/\./_/g')" -export BOOST_ROOT=$DEP_DIR/$BOOST_FOLDER_NAME -export Boost_LIBRARY_DIRS=$BOOST_ROOT/libs -export BOOST_INCLUDEDIR=$BOOST_ROOT/boost -export Boost_INCLUDE_DIRS=$BOOST_ROOT/boost -export LLVM_DIR=/usr/lib/llvm-$LLVM_VERSION/lib/cmake/llvm -export LLVM_LIBRARY_DIR=/usr/lib/llvm-$LLVM_VERSION/lib -export LLD_DIR=/usr/lib/llvm-$LLVM_VERSION/lib/cmake/lld -export CC=gcc -export CXX=g++ -export CFLAGS="-DBOOST_ASIO_HAS_STD_INVOKE_RESULT" -export CXXFLAGS="-DBOOST_ASIO_HAS_STD_INVOKE_RESULT" -export BOOST_CXXFLAGS="-DBOOST_ASIO_HAS_STD_INVOKE_RESULT" -export LDFLAGS="-L$BOOST_ROOT/lib" -export CPPFLAGS="-I$BOOST_ROOT/include" -export LDFLAGS="-L/usr/lib/llvm-$LLVM_VERSION/lib" -export CPPFLAGS="-I/usr/lib/llvm-$LLVM_VERSION/include" -``` - -### Install Core Dependencies - -``` -apt update && \ -apt install -y build-essential software-properties-common wget curl git pkg-config zlib1g-dev libssl-dev autoconf libtool unzip gcc g++ ninja-build && \ -wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key | tee /etc/apt/trusted.gpg.d/apt.llvm.org.asc && \ -add-apt-repository "deb http://apt.llvm.org/$UBUNTU_VERSION/ llvm-toolchain-$UBUNTU_VERSION-$LLVM_VERSION main" && \ -add-apt-repository ppa:deadsnakes/ppa && \ -apt-cache policy python3.9 && \ -apt install -y python3.9 python3-pip llvm-$LLVM_VERSION-dev liblld-$LLVM_VERSION-dev libpolly-$LLVM_VERSION-dev -``` - - - -``` -sudo nano /etc/apt/sources.list -# Scroll down and remove -deb http://apt.llvm.org/ llvm-toolchain-- main -# Add the apt-repo directly with add-apt-repository "deb http://apt.llvm.org/jammy/ llvm-toolchain-jammy-14 main" -``` - -### Install Xahaud Dependencies - -Install CMake - -``` -cd $DEP_DIR && \ -wget https://github.com/Kitware/CMake/releases/download/v$CMAKE_VERSION/cmake-$CMAKE_VERSION-Linux-x86_64.sh && \ -sudo sh cmake-$CMAKE_VERSION-Linux-x86_64.sh --prefix=/usr/local --exclude-subdir -``` - -Install Protobuf - -``` -cd $DEP_DIR && \ -wget -nc https://github.com/protocolbuffers/protobuf/releases/download/v$PROTOBUF_VERSION/protobuf-all-$PROTOBUF_VERSION.tar.gz && \ -tar -xzf protobuf-all-$PROTOBUF_VERSION.tar.gz && \ -cd protobuf-$PROTOBUF_VERSION/ && \ -./autogen.sh && \ -./configure --prefix=/usr --disable-shared link=static && \ -make -j$(nproc) && \ -sudo make install -``` - -Install Boost - -``` -cd $DEP_DIR && \ -wget https://boostorg.jfrog.io/artifactory/main/release/$BOOST_VERSION/source/$BOOST_FOLDER_NAME.tar.gz && \ -tar -xvzf $BOOST_FOLDER_NAME.tar.gz && \ -cd $BOOST_FOLDER_NAME && \ -./bootstrap.sh && \ -./b2 -j$(nproc) -``` - -Install WasmEdge - -``` -cd $DEP_DIR && \ -wget -nc -q https://github.com/WasmEdge/WasmEdge/archive/refs/tags/$WASMEDGE_VERSION.zip && \ -unzip -o $WASMEDGE_VERSION.zip && \ -cd WasmEdge-$WASMEDGE_VERSION && \ -mkdir build && \ -cd build && \ -cmake -DCMAKE_BUILD_TYPE=Release -DWASMEDGE_BUILD_SHARED_LIB=OFF -DWASMEDGE_BUILD_STATIC_LIB=ON -DWASMEDGE_BUILD_AOT_RUNTIME=ON -DWASMEDGE_FORCE_DISABLE_LTO=ON -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DWASMEDGE_LINK_LLVM_STATIC=ON -DWASMEDGE_BUILD_PLUGINS=OFF -DWASMEDGE_LINK_TOOLS_STATIC=ON .. && \ -make -j$(nproc) && \ -sudo make install -``` - -### Clone the repository - -``` -mkdir ~/projects && \ -cd ~/projects && \ -git clone https://github.com/Xahau/xahaud.git && \ -cd xahaud && \ -git checkout dev -``` - -### Build Xahaud - -From the root `xahaud` directory: - -```shellscript -mkdir build && \ -cd build && \ -cmake -DCMAKE_BUILD_TYPE=Debug -DLLVM_DIR=$LLVM_DIR -DLLVM_LIBRARY_DIR=$LLVM_LIBRARY_DIR .. && \ -cmake --build . --target rippled --parallel -j$(nproc) -``` - -Start the built node - -``` -./rippled -``` From 01a04ba57cd93f2e345db9f341538fc37f3ff21a Mon Sep 17 00:00:00 2001 From: JScottBranson Date: Fri, 7 Nov 2025 16:45:52 -0500 Subject: [PATCH 05/25] Expand Linux build instructions. --- astro.config.mjs | 8 +- .../index.mdx | 0 .../infrastructure/build-xahaud/linux.mdx | 169 ++++++++++++++++++ .../macos.mdx | 0 .../infrastructure/building-xahaud/linux.mdx | 115 ------------ .../docs/infrastructure/installing-xahaud.mdx | 2 +- 6 files changed, 174 insertions(+), 120 deletions(-) rename src/content/docs/docs/infrastructure/{building-xahaud => build-xahaud}/index.mdx (100%) create mode 100644 src/content/docs/docs/infrastructure/build-xahaud/linux.mdx rename src/content/docs/docs/infrastructure/{building-xahaud => build-xahaud}/macos.mdx (100%) delete mode 100644 src/content/docs/docs/infrastructure/building-xahaud/linux.mdx diff --git a/astro.config.mjs b/astro.config.mjs index dd857dd..28f1cdd 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -288,12 +288,12 @@ export default defineConfig({ 'docs/infrastructure/interacting', 'docs/infrastructure/advanced-configuration', { - label: 'Building xahaud (Advanced)', + label: 'Build xahaud (Advanced)', collapsed: true, items: [ - 'docs/infrastructure/building-xahaud', - 'docs/infrastructure/building-xahaud/linux', - 'docs/infrastructure/building-xahaud/macos', + 'docs/infrastructure/build-xahaud', + 'docs/infrastructure/build-xahaud/linux', + 'docs/infrastructure/build-xahaud/macos', ], }, ], diff --git a/src/content/docs/docs/infrastructure/building-xahaud/index.mdx b/src/content/docs/docs/infrastructure/build-xahaud/index.mdx similarity index 100% rename from src/content/docs/docs/infrastructure/building-xahaud/index.mdx rename to src/content/docs/docs/infrastructure/build-xahaud/index.mdx diff --git a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx new file mode 100644 index 0000000..d8fe7b0 --- /dev/null +++ b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx @@ -0,0 +1,169 @@ +--- +title: Linux Build Instructions +--- +import { Aside } from '@astrojs/starlight/components'; + + + +These instructions are designed to work for Debian and Red Hat (9 or 10) based Linux distributions. While some instructions overlap, differences across operating systems are noted. While efforts are made to test builds across operating systems, Ubuntu is the most tested and supported environment for building and running xahaud. Please be advised that building software from source code is a complex task that requires advanced technical knowledge an experience. It is possible to make changes at an operating system level that cannot be easily recovered from. Anyone undertaking the build process does so at their own risk. + +For additional instructions, refer to the [BUILD.md](https://github.com/Xahau/xahaud/blob/dev/BUILD.md) in the Xahau/xahaud Github Repository. + +## The Build Environment + +Maintaining different build environments (Python3 venvs, Conan2 profiles, etc.) is a complex task, even more so as underlying operating systems often rely on or expect specific versions of software. Thus, those new to the build process may benefit from using containers or writing bash scripts that are used on machines that reset their state at reboot. + +The following subsections address configuring build environments with the required software dependencies. + +### Containerized Environments +Will go here... + +### Amnesiac Operating System Environments + +Configuring a Linux system to completely forget all the software that was installed or modified during runtime provides an easy path to recover from build errors. Typically, an amnesiac operating system is run as a virtual machine with a very large amount of memory available, as all changes are written to memory instead of disk. Building xahaud can take over 20 GB of memory, if all software dependencies/requirements are installed in a memory based overlay file system. It is typically possible to install most of the software dependencies (using `apt` or `dnf`) prior to making the system amnesiac, thereby reducing required memory. + +To configure an amnesic operating system using Debian based systems: +``` +# Install the 'overlayroot' software package +apt update && apt install overlayroot + +# Update the configuration file (/etc/overlayroot.conf) to enable an in-memory overlay file system. +sudo sed -i 's/^overlayroot=.*/overlayroot="tmpfs:swap=1,recurse=0"/' /etc/overlayroot.conf + +# Rebuild initramfs +update-initramfs -u + +# Reboot into the overlay +reboot + +# After rebooting, it is possible to remount the overlay filesystem with more memory, as only 50% of available memory is dedicated to the overlayfs by default. +When resizing memory, ensure some memory remains available for system use. The following will remount with the overlayfs set to use 30G of memory, adjust as needed. +sudo mount -o remount,size=30G /media/root-rw +``` + +To configure an amnesic operating system using RHEL 9/10 based systems: +``` +# Ensure dracut is installed +dnf install dracut -y + +# Configure dracut to support the overlay +printf 'add_drivers+=" overlay "\n' > /etc/dracut.conf.d/overlay.conf # Use this line for RHEL 9 +printf 'add_drivers+=" overlay "\nadd_dracutmodules+=" overlayfs "\n' > /etc/dracut.conf.d/overlay.conf # Use this line for RHEL 10 + +# Rebuild +dracut -f + +# Update the boot image to use a systemd volatile overlay +grubby --update-kernel=ALL --args="systemd.volatile=overlay" +``` +To disable amnesia on Debian based systems: +1. Press `e` to edit the Ubuntu boot entry. +2. On the line starting with "linux..." edit or add `overlayroot=` option to read `overlayroot=disabled`. This will allow a one-time boot into a system with a memory. +3. To permanently disable amnesia, run `sudo sed -i '/^overlayroot=/c\overlayroot="disabled"' /etc/overlayroot.conf` to change `overlayroot="disabled"` in the /etc/overlayroot.conf file. Then update initramfs `sudo update-initramfs -u`. + +To disable amnesia on RHEL 9/10 based systems: +1. Press `e` at the boot menu to edit the options. +2. Remove the "systemd.volatile=overlay" option. +3. Press `F10` to boot. +4. To permanently disable amnesia, run `grubby --update-kernel=ALL --remove-args="systemd.volatile=overlay"` + +## Install Dependencies + +For compatibility, it is important to attend to specific versions of software used in the build process. xahaud is written in the C++20 language. + +Current requirements for building xahaud include: + + +| Dependency | Version | +| :---------- | :-------- | +| Python3 | >= 3.10 | +| Conan | >= 2.x | +| Ninja Build | ? | +| GCC / G++ | >= 14.x | +| CMake | >= 3.23 | + +Debian/Ubuntu users can install required dependencies using these commands: +``` +sudo apt install -y git curl wget python3-pip python3-venv python3-dev ca-certificates gcc g++ build-essential cmake ninja-build libc6-dev libssl-dev libsqlite3-dev +``` + +Likewise, RHEL 9 or RHEL 10 users can install dependencies: +``` +sudo dnf install epel-release && sudo dnf update -y +sudo dnf config-manager --set-enabled crb -y +sudo dnf groupinstall "Development Tools" -y +sudo dnf install curl wget git ca-certificates cmake glibc-headers glibc-devel ninja-build perl-interpreter perl perl-FindBin sqlite-devel libstdc++ libstdc++-devel libstdc++-static gcc-c++ -y +``` + +## Clone the Xahau/xahaud GitHub Repository +Before building, acquire a local copy of the GitHub xahaud repository: + +`git clone https://github.com/Xahau/xahaud.git` + +It is possible to build from other forks of the repository, simply adjust the above URL as needed. + +### Select the Repository Branch +The primary branch used for xahaud development is `dev`. Users who prefer to build from an alternate branch can do so: + +`git checkout [branch name]` + +### Prepare the build directory +Create a directory inside the xahaud repository to house the files generated during the build process: + +`mkdir [/path/to/xahaud_github_repo]/.build` + +## Install and Configure Conan2 +1. Ensure you are in the build directory: `cd [/path/to/xahaud_github_repo]/.build` + +2. Create a Python3 virtual environment (venv) in the `env` directory: `python3 -m venv env` + +3. Activate the virtual environment: `source ./env/bin/activate` + +4. Update PIP so the latest versions of software are available: `pip install --upgrade pip` + +5. Install Conan2: `pip install conan` + +6. Create a new Conan2 profile (if you haven't already): `conan profile detect` + +7. Install the Conan recipes for the snappy, soci, and wasmedge dependencies: +``` +conan export external/snappy --version 1.1.10 --user xahaud --channel stable +conan export external/soci --version 4.0.3 --user xahaud --channel stable +conan export external/wasmedge --version 0.11.2 --user xahaud --channel stable +``` +8. Review your Conan2 profile, located in: `/home/[username]/.conan2/profiles/default`. If needed, add: +``` +[settings] +compiler.cppstd=20 +compiler.libcxx=libstdc++11 +``` +9. It might be necessary to include the following lines at the end of your Conan2 profile: +``` +[conf] +tools.build:cxxflags=['-Wno-restrict'] +``` + +## Build xahaud +Inside the `.build` directory, with the Python3 virtual environment active, adjust "build_type" and then run the following: + +`conan install .. --output-folder . --build missing --settings build_type=["Release" or "Debug"] -c tools.build:verbosity=verbose -c tools.compilation:verbosity=verbose` + +If needed, additional options can be passed to Conan2: + +`conan install .. --output-folder . --build missing --settings build_type=["Release" or "Debug"] -s compiler=gcc -s compiler.version=12 -s compiler.libcxx=libstdc++11 -s compiler.cppstd=20 -c tools.build:verbosity=verbose -c tools.compilation:verbosity=verbose se -g VirtualBuildEnv -g VirtualRunEnv` + +After Conan2 is complete, run cmake: + +``` +cmake -DCMAKE_POLICY_DEFAULT_CMP0091=NEW \ + -DCMAKE_BUILD_TYPE=$RELEASE_TYPE \ + -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \ + .. +``` + +Finally, use cmake to complete the build process: `cmake --build .` + +The output file will be named `rippled` and located in the `.build` directory. Rename the file to 'xahaud', and move it to it's final location (being careful not to overwrite the 'xahaud' GitHub repository). + +## Test the Build +Will go here... diff --git a/src/content/docs/docs/infrastructure/building-xahaud/macos.mdx b/src/content/docs/docs/infrastructure/build-xahaud/macos.mdx similarity index 100% rename from src/content/docs/docs/infrastructure/building-xahaud/macos.mdx rename to src/content/docs/docs/infrastructure/build-xahaud/macos.mdx diff --git a/src/content/docs/docs/infrastructure/building-xahaud/linux.mdx b/src/content/docs/docs/infrastructure/building-xahaud/linux.mdx deleted file mode 100644 index d53fdd0..0000000 --- a/src/content/docs/docs/infrastructure/building-xahaud/linux.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Linux Build Instructions ---- -import { Aside } from '@astrojs/starlight/components'; - - - -These instructions are designed to work for Debian and Red Hat (9 or 10) based Linux distributions. While some instructions overlap, differences across operating systems are noted. While efforts are made to test builds across operating systems, Ubuntu is the most tested and supported environment for building and running xahaud. - -For additional instructions, refer to the [BUILD.md](https://github.com/Xahau/xahaud/blob/dev/BUILD.md) in the Xahau/xahaud Github Repository. - -## The Build Environment - -Maintaining different build environments (Python3 venvs, Conan2 profiles, etc.) is a complex task, even more so as underlying operating systems often rely on or expect specific versions of software. Thus, those new to the build process may benefit from writing bash scripts that are used on machines that reset their state at reboot. Configuring a Linux system to completely forget all the software that was installed or modified during runtime provides an easy path to recover from build errors. Typically, an amnesiac operating system is run as a virtual machine with a very large amount of memory available, as all changes are written to memory instead of disk. Building xahaud can take close to 32GB of memory, if all software dependencies/requirements are installed in a memory based overlay file system. - -It is also possible to use Docker or other container systems to create specific build environments. - -The following subsections address configuring build environments with the required software dependencies. - -### Containerized Environments -Will go here... - -### Amnesiac Operating System Environments - -To configure an amnesic operating system using Debian based systems: -``` -# Install the 'overlayroot' software package -apt update && apt install overlayroot - -# Update the configuration file to enable an in-memory overlay file system -sudo sed -i 's/^overlayroot=.*/overlayroot="tmpfs:swap=1,recurse=0"/' /etc/overlayroot.conf - -# Rebuild initramfs -update-initramfs -u -``` - -To configure an amnesic operating system using RHEL 9/10 based systems: -``` -# Ensure dracut is installed -dnf install dracut -y - -# Configure dracut to support the overlay -printf 'add_drivers+=" overlay "\n' > /etc/dracut.conf.d/overlay.conf # Use this line for RHEL 9 -printf 'add_drivers+=" overlay "\nadd_dracutmodules+=" overlayfs "\n' > /etc/dracut.conf.d/overlay.conf # Use this line for RHEL 10 - -# Rebuild -dracut -f - -# Update the boot image to use a systemd volatile overlay -grubby --update-kernel=ALL --args="systemd.volatile=overlay" -``` -To disable amnesia on Debian based systems: -1. Hold `Shift` or `Esc` during boot to enter the GRUB menu (be careful not to enter the BIOS by pressing `Esc` before the firmware logo). -2. Press `e` to edit the Ubuntu boot entry. -3. Edit only the `overlayroot=` option to read `overlayroot=disabled`. This will allow a one-time boot into a system with a memory. -4. To permanently disable amnesia, run `sudo sed -i '/^overlayroot=/c\overlayroot="disabled"' /etc/overlayroot.conf` to change `overlayroot="disabled"` in the /etc/overlayroot.conf file. Then update initramfs `sudo update-initramfs -u`. - -To disable amnesia on RHEL 9/10 based systems: -1. Press `e` at the boot menu to edit the options. -2. Remove the "systemd.volatile=overlay" option. -3. Press `F10` to boot. -4. To permanently disable amnesia, run `grubby --update-kernel=ALL --remove-args="systemd.volatile=overlay"` - -### Installing Dependencies - -For compatibility, it is important to attend to specific versions of software used in the build process. Current requirements include: - - -| Dependency | Version | -| :---------- | :-------- | -| Python3 | >= 3.10 | -| Conan | >= 2.x | -| Ninja Build | ? | -| GCC / G++ | >= 11.x | -| CMake | >= 3.16 | - -| Dependency | Working Version | -| ---------- | --------------- | -| GCC / G++ | 14.0.3 | -| LLVM | 14.0.3 | -| LLD | 14.0.3 | -| Boost | 1.86.0 | -| CMake | 3.23.1 | -| Protobuf | 3.20.0 | -| WasmEdge | 0.11.2 | - - -Debian/Ubuntu users can install required dependencies using these commands: -``` -sudo apt install -y git curl wget python3-pip python3-venv python3-dev ca-certificates gcc g++ build-essential cmake ninja-build libc6-dev libssl-dev libsqlite3-dev -``` - -Likewise, RHEL 9 or RHEL 10 users can install dependencies: -``` -sudo dnf install epel-release && sudo dnf update -y -sudo dnf config-manager --set-enabled crb -y -sudo dnf install curl wget git ca-certificates cmake glibc-headers glibc-devel ninja-build perl-interpreter perl perl-FindBin sqlite-devel -y -sudo dnf groupinstall "Development Tools" -y -``` - -## Clone the Xahau/xahaud GitHub Repository -Before building, acquire a local copy of the GitHub xahaud repository: - -`git clone https://github.com/Xahau/xahaud.git` - -It is possible to build from other forks of the repository, simply adjust the above URL as needed. - -### Select the Repository Branch -The primary branch used for xahaud development is `dev`. Users who prefer to build from an alternate branch can do so: - -`git checkout [branch name]` - -## Installing Conan2 -will go here... - diff --git a/src/content/docs/docs/infrastructure/installing-xahaud.mdx b/src/content/docs/docs/infrastructure/installing-xahaud.mdx index cd69e44..c8110d8 100644 --- a/src/content/docs/docs/infrastructure/installing-xahaud.mdx +++ b/src/content/docs/docs/infrastructure/installing-xahaud.mdx @@ -5,7 +5,7 @@ description: >- --- When running a node, users will have to configure settings based on whether the node will run on the test network or the main network. When transitioning a single node from one network to the other, database files must be wiped, except wallet.db, which contains the server's identity credentials. -In addition to [building from scratch](../building-xahau), there are three ways to install xahaud: Docker, locally, and using a portable binary. The below install methods all rely on the xahaud builds published at: [https://build.xahau.tech](https://build.xahau.tech), though the end result is different. +In addition to [building from scratch](../build-xahaud), there are three ways to install xahaud: Docker, locally, and using a portable binary. The below install methods all rely on the xahaud builds published at: [https://build.xahau.tech](https://build.xahau.tech), though the end result is different. ## Docker Container To run xahaud in a Docker Container: From 795a32cd667b8419f92c02ca811d2ec2949a92fe Mon Sep 17 00:00:00 2001 From: JScottBranson Date: Fri, 7 Nov 2025 16:59:22 -0500 Subject: [PATCH 06/25] Minor edits/revisons/formatting. --- .../infrastructure/build-xahaud/linux.mdx | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx index d8fe7b0..87ae77a 100644 --- a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx +++ b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx @@ -144,26 +144,28 @@ tools.build:cxxflags=['-Wno-restrict'] ``` ## Build xahaud -Inside the `.build` directory, with the Python3 virtual environment active, adjust "build_type" and then run the following: +1. Inside the `.build` directory, with the Python3 virtual environment active, adjust "build_type" to either "Release" or "Debug" and run the below command. It is possible to run the command twice to generate files for each "build_type". +``` +conan install .. --output-folder . --build missing --settings build_type=["Release" or "Debug"] -c tools.build:verbosity=verbose -c tools.compilation:verbosity=verbose +``` -`conan install .. --output-folder . --build missing --settings build_type=["Release" or "Debug"] -c tools.build:verbosity=verbose -c tools.compilation:verbosity=verbose` +2. If needed, additional options can be passed to Conan2: +``` +conan install .. --output-folder . --build missing --settings build_type=["Release" or "Debug"] -s compiler=gcc -s compiler.version=12 -s compiler.libcxx=libstdc++11 -s compiler.cppstd=20 -c tools.build:verbosity=verbose -c tools.compilation:verbosity=verbose se -g VirtualBuildEnv -g VirtualRunEnv +``` -If needed, additional options can be passed to Conan2: - -`conan install .. --output-folder . --build missing --settings build_type=["Release" or "Debug"] -s compiler=gcc -s compiler.version=12 -s compiler.libcxx=libstdc++11 -s compiler.cppstd=20 -c tools.build:verbosity=verbose -c tools.compilation:verbosity=verbose se -g VirtualBuildEnv -g VirtualRunEnv` - -After Conan2 is complete, run cmake: +3. After Conan2 is complete, run cmake. Do not specify "DCMAKE_BUILD_TYPE" if building from multiple configurations (both "Release" and "Debug"). ``` cmake -DCMAKE_POLICY_DEFAULT_CMP0091=NEW \ - -DCMAKE_BUILD_TYPE=$RELEASE_TYPE \ + -DCMAKE_BUILD_TYPE=["Release" or "Debug"] \ -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \ .. ``` -Finally, use cmake to complete the build process: `cmake --build .` +4. Finally, use cmake to complete the build process: `cmake --build . ['--config Release' or '--config Debug' if multiple types were generated]`. -The output file will be named `rippled` and located in the `.build` directory. Rename the file to 'xahaud', and move it to it's final location (being careful not to overwrite the 'xahaud' GitHub repository). +The output file is named `rippled` and is located in the `.build` directory. If multiple build types (both "Release" and "Debug") were specified, the final product will be located at: `.build/["Release" or "Debug"]/rippled` Rename the file to 'xahaud', and move it to it's final location (being careful not to overwrite the 'xahaud' GitHub repository). Mark the final file as executable, and download a configuration file and validators file as needed. ## Test the Build -Will go here... +`./xahaud --unittest` From 335e52efe9a9d9004e38da2292f03d8c71df724c Mon Sep 17 00:00:00 2001 From: JScottBranson Date: Mon, 10 Nov 2025 10:58:00 -0500 Subject: [PATCH 07/25] Move dependency version table to index page from Linux build page. Minor edits. Add warning 'aside' on index page for build instructions. --- .../infrastructure/build-xahaud/index.mdx | 29 +++++++++++++++++++ .../infrastructure/build-xahaud/linux.mdx | 20 ++----------- 2 files changed, 32 insertions(+), 17 deletions(-) diff --git a/src/content/docs/docs/infrastructure/build-xahaud/index.mdx b/src/content/docs/docs/infrastructure/build-xahaud/index.mdx index b7753da..ee738c5 100644 --- a/src/content/docs/docs/infrastructure/build-xahaud/index.mdx +++ b/src/content/docs/docs/infrastructure/build-xahaud/index.mdx @@ -3,10 +3,16 @@ title: Building xahaud description: Setting Up the xahaud Build Environment --- +import { Aside } from '@astrojs/starlight/components'; + Building software, such as xahaud, from the openly available source code is a complex process that requires in-depth knowledge and experience. Thus, there are multiple approaches that developers might take, depending on the environment (e.g., Linux, MacOS, Windows). The instructions in the following documentation chapters are meant to simplify and expand on those in the [xahaud GitHub repository](https://github.com/Xahau/xahaud/blob/dev/BUILD.md). Developers might need to deviate from these instructions to accomplish specific tasks or to ensure compatibility with specific operating systems. The following articles detail the process of setting up a build environment and building xahaud across various operating system environments. + + ## Basics of Building Software from Source When developers write software, they do so in programming languages that are designed to be human readable. However, it is not efficient for computers to run this human readable code. Thus, there is a need for software to be "compiled" from human readable code into bytecode that can be quickly read and interpreted by a computer. @@ -15,3 +21,26 @@ Adding complexity to this process, developers often rely on software that was wr The entire process of ensuring dependencies are met, compiling software into a machine optimized format, and running tests against the final product is called "building". Since xahaud is [published as open source software on GitHub](https://github.com/Xahau/xahaud), anyone may view, audit, modify, build, and run the code. Building from the source code enables certainty that the product being run is based off of the publicly viewable source code, which also has a full audit trail. Thus, validator operators who prioritize a maximum level of security should consider building from source. + +## Dependencies + +For compatibility, it is important to attend to specific versions of software used in the build process. xahaud is written in the C++20 language. + +Current requirements for building xahaud include: + + +| Dependency | Version | +| :---------- | :-------- | +| Python3 | >= 3.7 | +| GCC / G++ | >= 14.x | +| CMake | >= 3.16 | +| Conan | 2.x | +| openssl | 1.1.1 | +| boost | 1.86.0 | +| SQLite3 | 3.42.0 | +| Snappy* | 1.1.10 | +| SOCI* | 4.0.3 | +| WasmEdge* | 0.11.2 | + +\* Included in the Xahau/xahaud GitHub repository. + diff --git a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx index 87ae77a..ae55878 100644 --- a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx +++ b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx @@ -4,8 +4,7 @@ title: Linux Build Instructions import { Aside } from '@astrojs/starlight/components'; - -These instructions are designed to work for Debian and Red Hat (9 or 10) based Linux distributions. While some instructions overlap, differences across operating systems are noted. While efforts are made to test builds across operating systems, Ubuntu is the most tested and supported environment for building and running xahaud. Please be advised that building software from source code is a complex task that requires advanced technical knowledge an experience. It is possible to make changes at an operating system level that cannot be easily recovered from. Anyone undertaking the build process does so at their own risk. +These instructions are designed to work for Debian (i.e., Ubuntu 22.04 and 24.04) and Red Hat Enterprise Linux (9 or 10) based distributions. While some instructions overlap, differences across operating systems are noted. While efforts are made to test builds across operating systems, Ubuntu is the most tested and supported environment for building and running xahaud. For additional instructions, refer to the [BUILD.md](https://github.com/Xahau/xahaud/blob/dev/BUILD.md) in the Xahau/xahaud Github Repository. @@ -69,19 +68,6 @@ To disable amnesia on RHEL 9/10 based systems: ## Install Dependencies -For compatibility, it is important to attend to specific versions of software used in the build process. xahaud is written in the C++20 language. - -Current requirements for building xahaud include: - - -| Dependency | Version | -| :---------- | :-------- | -| Python3 | >= 3.10 | -| Conan | >= 2.x | -| Ninja Build | ? | -| GCC / G++ | >= 14.x | -| CMake | >= 3.23 | - Debian/Ubuntu users can install required dependencies using these commands: ``` sudo apt install -y git curl wget python3-pip python3-venv python3-dev ca-certificates gcc g++ build-essential cmake ninja-build libc6-dev libssl-dev libsqlite3-dev @@ -125,7 +111,7 @@ Create a directory inside the xahaud repository to house the files generated dur 6. Create a new Conan2 profile (if you haven't already): `conan profile detect` -7. Install the Conan recipes for the snappy, soci, and wasmedge dependencies: +7. Install the Conan recipes for the Snappy, SOCI, and WasmEdge dependencies, included in the "xahaud" GitHub repository: ``` conan export external/snappy --version 1.1.10 --user xahaud --channel stable conan export external/soci --version 4.0.3 --user xahaud --channel stable @@ -168,4 +154,4 @@ cmake -DCMAKE_POLICY_DEFAULT_CMP0091=NEW \ The output file is named `rippled` and is located in the `.build` directory. If multiple build types (both "Release" and "Debug") were specified, the final product will be located at: `.build/["Release" or "Debug"]/rippled` Rename the file to 'xahaud', and move it to it's final location (being careful not to overwrite the 'xahaud' GitHub repository). Mark the final file as executable, and download a configuration file and validators file as needed. ## Test the Build -`./xahaud --unittest` +To run unit tests: `./xahaud --unittest` From 566281bb9b69bf8350d5789d1f4c49ba79671794 Mon Sep 17 00:00:00 2001 From: JScottBranson Date: Tue, 11 Nov 2025 11:31:36 -0500 Subject: [PATCH 08/25] Stash minor edits to sync with Jose updating the website :) --- .../infrastructure/build-xahaud/index.mdx | 6 +- .../infrastructure/build-xahaud/linux.mdx | 120 +++++++++--------- .../infrastructure/build-xahaud/macos.mdx | 11 +- .../infrastructure/enabling-validation.mdx | 7 +- 4 files changed, 73 insertions(+), 71 deletions(-) diff --git a/src/content/docs/docs/infrastructure/build-xahaud/index.mdx b/src/content/docs/docs/infrastructure/build-xahaud/index.mdx index ee738c5..151c6be 100644 --- a/src/content/docs/docs/infrastructure/build-xahaud/index.mdx +++ b/src/content/docs/docs/infrastructure/build-xahaud/index.mdx @@ -1,6 +1,6 @@ --- title: Building xahaud -description: Setting Up the xahaud Build Environment +description: Setting Up the xahaud Build Environment and Compiling xahaud --- import { Aside } from '@astrojs/starlight/components'; @@ -13,7 +13,7 @@ The following articles detail the process of setting up a build environment and Building software from source code is a complex task requiring advanced technical knowledge and experience. It is possible to make changes at an operating system level that cannot be easily recovered from. Undertake the build process at your own risk. This documentation is designed to guide, rather than be definitively accurate. -## Basics of Building Software from Source +## Building Software from Source When developers write software, they do so in programming languages that are designed to be human readable. However, it is not efficient for computers to run this human readable code. Thus, there is a need for software to be "compiled" from human readable code into bytecode that can be quickly read and interpreted by a computer. Adding complexity to this process, developers often rely on software that was written by other developers, called "dependencies" because one software package depends on (requires) the other. In order for these dependencies to be included in the final product, they must be "linked" to the code before the code is compiled. The linking process can be very intensive, as dependencies for the original software package might have their own dependencies (which in turn can have even more dependencies, adding layers). Developers rely on tools, such as Conan, to simplify the process of locating, configuring, and linking dependencies. @@ -34,7 +34,7 @@ Current requirements for building xahaud include: | Python3 | >= 3.7 | | GCC / G++ | >= 14.x | | CMake | >= 3.16 | -| Conan | 2.x | +| Conan2 | 2.x | | openssl | 1.1.1 | | boost | 1.86.0 | | SQLite3 | 3.42.0 | diff --git a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx index ae55878..bedfbbf 100644 --- a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx +++ b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx @@ -8,63 +8,9 @@ These instructions are designed to work for Debian (i.e., Ubuntu 22.04 and 24.04 For additional instructions, refer to the [BUILD.md](https://github.com/Xahau/xahaud/blob/dev/BUILD.md) in the Xahau/xahaud Github Repository. -## The Build Environment - -Maintaining different build environments (Python3 venvs, Conan2 profiles, etc.) is a complex task, even more so as underlying operating systems often rely on or expect specific versions of software. Thus, those new to the build process may benefit from using containers or writing bash scripts that are used on machines that reset their state at reboot. - -The following subsections address configuring build environments with the required software dependencies. - -### Containerized Environments -Will go here... - -### Amnesiac Operating System Environments - -Configuring a Linux system to completely forget all the software that was installed or modified during runtime provides an easy path to recover from build errors. Typically, an amnesiac operating system is run as a virtual machine with a very large amount of memory available, as all changes are written to memory instead of disk. Building xahaud can take over 20 GB of memory, if all software dependencies/requirements are installed in a memory based overlay file system. It is typically possible to install most of the software dependencies (using `apt` or `dnf`) prior to making the system amnesiac, thereby reducing required memory. - -To configure an amnesic operating system using Debian based systems: -``` -# Install the 'overlayroot' software package -apt update && apt install overlayroot - -# Update the configuration file (/etc/overlayroot.conf) to enable an in-memory overlay file system. -sudo sed -i 's/^overlayroot=.*/overlayroot="tmpfs:swap=1,recurse=0"/' /etc/overlayroot.conf - -# Rebuild initramfs -update-initramfs -u - -# Reboot into the overlay -reboot - -# After rebooting, it is possible to remount the overlay filesystem with more memory, as only 50% of available memory is dedicated to the overlayfs by default. -When resizing memory, ensure some memory remains available for system use. The following will remount with the overlayfs set to use 30G of memory, adjust as needed. -sudo mount -o remount,size=30G /media/root-rw -``` - -To configure an amnesic operating system using RHEL 9/10 based systems: -``` -# Ensure dracut is installed -dnf install dracut -y - -# Configure dracut to support the overlay -printf 'add_drivers+=" overlay "\n' > /etc/dracut.conf.d/overlay.conf # Use this line for RHEL 9 -printf 'add_drivers+=" overlay "\nadd_dracutmodules+=" overlayfs "\n' > /etc/dracut.conf.d/overlay.conf # Use this line for RHEL 10 - -# Rebuild -dracut -f - -# Update the boot image to use a systemd volatile overlay -grubby --update-kernel=ALL --args="systemd.volatile=overlay" -``` -To disable amnesia on Debian based systems: -1. Press `e` to edit the Ubuntu boot entry. -2. On the line starting with "linux..." edit or add `overlayroot=` option to read `overlayroot=disabled`. This will allow a one-time boot into a system with a memory. -3. To permanently disable amnesia, run `sudo sed -i '/^overlayroot=/c\overlayroot="disabled"' /etc/overlayroot.conf` to change `overlayroot="disabled"` in the /etc/overlayroot.conf file. Then update initramfs `sudo update-initramfs -u`. - -To disable amnesia on RHEL 9/10 based systems: -1. Press `e` at the boot menu to edit the options. -2. Remove the "systemd.volatile=overlay" option. -3. Press `F10` to boot. -4. To permanently disable amnesia, run `grubby --update-kernel=ALL --remove-args="systemd.volatile=overlay"` + ## Install Dependencies @@ -155,3 +101,63 @@ The output file is named `rippled` and is located in the `.build` directory. If ## Test the Build To run unit tests: `./xahaud --unittest` + + +## Build Environments + +Maintaining different build environments (Python3 venvs, Conan2 profiles, etc.) is a complex task, even more so as underlying operating systems often rely on or expect specific versions of software. Thus, those new to the build process may benefit from using containers or writing bash scripts that are used on machines that reset their state at reboot. + +The following subsections address configuring build environments with the required software dependencies. + +### Containerized Environments +Will go here... + +### Amnesiac Operating System Environments + +Configuring a Linux system to completely forget all the software that was installed or modified during runtime provides an easy path to recover from build errors. Typically, an amnesiac operating system is run as a virtual machine with a very large amount of memory available, as all changes are written to memory instead of disk. Building xahaud can take over 20 GB of memory, if all software dependencies/requirements are installed in a memory based overlay file system. It is typically possible to install most of the software dependencies (using `apt` or `dnf`) prior to making the system amnesiac, thereby reducing required memory. + +To configure an amnesic operating system using Debian based systems: +``` +# Install the 'overlayroot' software package +apt update && apt install overlayroot + +# Update the configuration file (/etc/overlayroot.conf) to enable an in-memory overlay file system. +sudo sed -i 's/^overlayroot=.*/overlayroot="tmpfs:swap=1,recurse=0"/' /etc/overlayroot.conf + +# Rebuild initramfs +update-initramfs -u + +# Reboot into the overlay +reboot + +# After rebooting, it is possible to remount the overlay filesystem with more memory, as only 50% of available memory is dedicated to the overlayfs by default. +When resizing memory, ensure some memory remains available for system use. The following will remount with the overlayfs set to use 30G of memory, adjust as needed. +sudo mount -o remount,size=30G /media/root-rw +``` + +To configure an amnesic operating system using RHEL 9/10 based systems: +``` +# Ensure dracut is installed +dnf install dracut -y + +# Configure dracut to support the overlay +printf 'add_drivers+=" overlay "\n' > /etc/dracut.conf.d/overlay.conf # Use this line for RHEL 9 +printf 'add_drivers+=" overlay "\nadd_dracutmodules+=" overlayfs "\n' > /etc/dracut.conf.d/overlay.conf # Use this line for RHEL 10 + +# Rebuild +dracut -f + +# Update the boot image to use a systemd volatile overlay +grubby --update-kernel=ALL --args="systemd.volatile=overlay" +``` +To disable amnesia on Debian based systems: +1. Press `e` to edit the Ubuntu boot entry. +2. On the line starting with "linux..." edit or add `overlayroot=` option to read `overlayroot=disabled`. This will allow a one-time boot into a system with a memory. +3. To permanently disable amnesia, run `sudo sed -i '/^overlayroot=/c\overlayroot="disabled"' /etc/overlayroot.conf` to change `overlayroot="disabled"` in the /etc/overlayroot.conf file. Then update initramfs `sudo update-initramfs -u`. + +To disable amnesia on RHEL 9/10 based systems: +1. Press `e` at the boot menu to edit the options. +2. Remove the "systemd.volatile=overlay" option. +3. Press `F10` to boot. +4. To permanently disable amnesia, run `grubby --update-kernel=ALL --remove-args="systemd.volatile=overlay"` + diff --git a/src/content/docs/docs/infrastructure/build-xahaud/macos.mdx b/src/content/docs/docs/infrastructure/build-xahaud/macos.mdx index 78fbd43..84bbd18 100644 --- a/src/content/docs/docs/infrastructure/build-xahaud/macos.mdx +++ b/src/content/docs/docs/infrastructure/build-xahaud/macos.mdx @@ -2,17 +2,8 @@ title: macOS --- -## CMake Legacy Building +import { Aside } from '@astrojs/starlight/components'; -| Dependency | Working Versions | -| ----------- | ---------------- | -| Apple Clang | 14.3.1, 16.0.0 | -| LLVM | 14, 16 | -| LLD | 14, 16 | -| Boost | 1.86.0 | -| CMake | 3.23.1 | -| Protobuf | 3.20.0 | -| WasmEdge | 0.11.2 | ### Using Apple Clang 14.3.1 diff --git a/src/content/docs/docs/infrastructure/enabling-validation.mdx b/src/content/docs/docs/infrastructure/enabling-validation.mdx index a214b92..106495c 100644 --- a/src/content/docs/docs/infrastructure/enabling-validation.mdx +++ b/src/content/docs/docs/infrastructure/enabling-validation.mdx @@ -1,6 +1,9 @@ --- title: Enabling Validation in xahaud --- +import { Aside } from '@astrojs/starlight/components'; + + Validators are xahaud nodes that are configured with an additional public/private keypair, which is used to sign each proposed ledger. Thus, validators are the primary mechanism used to achieve consensus regarding the order in which transactions are applied on the Xahau Network. ## Background Considerations @@ -30,9 +33,11 @@ The Xahau Network utilizes the [Governance Game](../../features/governance-game) Switching a stock xahaud server into a validator is a straight forward process. Essentially, users will generate a public/private keypair, which is then used to generate a token using an ephemeral key derived from the master pair. That token is installed into the `xahaud.cfg` file, thereby instructing xahaud to propose validations to the Network. ### Building the Validation Keys Tool -At this time, there is not an official release of the software used for generating validation keys. Thus, users can either build the tool from scratch or rely on a packaged version provided with rippled (this tool is not packaged with the xahaud binary). The instructions for building the tool are the same as the instructions for [building xahaud](../building-xahaud), and they are provided on the [ripple/validator-keys-tool](https://github.com/ripple/validator-keys-tool) repository page. There are also some [packaged binaries](https://github.com/jscottbranson/xahau-examples/) available in unofficial repositories. Users seeking to generate keys for production validators should build the tool from scratch on a secure, air-gapped machine. +At this time, there is not an official binary release of the software used for generating validation keys. Thus, users can either build the tool from scratch or rely on unofficial builds. The instructions for building the tool are the same as the instructions for [building xahaud](../building-xahaud), and they are provided on the [Xahau/validator-keys-tool](https://github.com/Xahau/validator-keys-tool) repository page. There are also some [packaged binaries](https://github.com/jscottbranson/xahau-examples/) available in unofficial repositories. Users seeking to generate keys for production validators should build the tool from scratch on a secure, air-gapped machine. + ### Generating and Installing Validation Keys Consider using an offline machine to generate validation keys and a validation token. From 960778c6b75a437dec90535ac3c2df26434d082c Mon Sep 17 00:00:00 2001 From: JScottBranson Date: Fri, 5 Dec 2025 15:57:41 -0500 Subject: [PATCH 09/25] Add Docker instructions to Linux build page. --- .../infrastructure/build-xahaud/linux.mdx | 114 ++++++++++++++++-- 1 file changed, 104 insertions(+), 10 deletions(-) diff --git a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx index bedfbbf..84e6259 100644 --- a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx +++ b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx @@ -4,12 +4,12 @@ title: Linux Build Instructions import { Aside } from '@astrojs/starlight/components'; -These instructions are designed to work for Debian (i.e., Ubuntu 22.04 and 24.04) and Red Hat Enterprise Linux (9 or 10) based distributions. While some instructions overlap, differences across operating systems are noted. While efforts are made to test builds across operating systems, Ubuntu is the most tested and supported environment for building and running xahaud. +These instructions are designed to work for Debian (i.e., Ubuntu 22.04 and 24.04) and Red Hat Enterprise Linux (9 or 10) based distributions. Many instructions overlap, though differences across operating systems are noted throughout. Efforts are made to test builds across operating systems, however, Ubuntu is the most tested and supported environment for building and running xahaud. -For additional instructions, refer to the [BUILD.md](https://github.com/Xahau/xahaud/blob/dev/BUILD.md) in the Xahau/xahaud Github Repository. +For additional instructions, refer to the [BUILD.md](https://github.com/Xahau/xahaud/blob/dev/BUILD.md) in the Xahau/xahaud GitHub Repository. ## Install Dependencies @@ -103,18 +103,112 @@ The output file is named `rippled` and is located in the `.build` directory. If To run unit tests: `./xahaud --unittest` -## Build Environments +## Build Environments for Beginners -Maintaining different build environments (Python3 venvs, Conan2 profiles, etc.) is a complex task, even more so as underlying operating systems often rely on or expect specific versions of software. Thus, those new to the build process may benefit from using containers or writing bash scripts that are used on machines that reset their state at reboot. +Maintaining different build environments (Python3 venvs, Conan2 profiles, etc.) is a complex task, even more so as underlying operating systems often rely on or expect specific versions of software. Thus, those new to the build process may benefit from using containers or writing bash scripts that are used on virtual machines that reset their state at reboot. -The following subsections address configuring build environments with the required software dependencies. +The following subsections address the basics of configuring amnesiac and container based build environments. -### Containerized Environments -Will go here... +### Containers +It is possible to use [Docker](https://docker.com) or other containerized environments to contain the build process, thereby keeping the underlying system clean. Using containers has the additional advantage of easily testing builds in multiple environments. For example, containers based on RHEL, Debian, and other distributions can be configured to use diverse compiler versions. Further, features like Multistage Dockerfiles enable users to build then deploy (run) xahaud using a single script. Users can also take advantage of Docker's `buildx` plugin, which provides an easy means to building for multiple platforms concurrently. -### Amnesiac Operating System Environments +#### Install Docker +``` +# Debian/Ubuntu: +sudo apt update && sudo apt install docker.io docker-compose-v2 docker-buildx -Configuring a Linux system to completely forget all the software that was installed or modified during runtime provides an easy path to recover from build errors. Typically, an amnesiac operating system is run as a virtual machine with a very large amount of memory available, as all changes are written to memory instead of disk. Building xahaud can take over 20 GB of memory, if all software dependencies/requirements are installed in a memory based overlay file system. It is typically possible to install most of the software dependencies (using `apt` or `dnf`) prior to making the system amnesiac, thereby reducing required memory. +# RHEL (requires adding the docker.com repository): +sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo +sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +``` + +After installing, it is possible to add your local user account to Docker, so interacting with Docker does not require root/sudo access: `sudo usermod -aG docker $USER`. + +#### Example Dockerfile +For ease and consistency, it is possible to use Dockerfile scripts (e.g., buildx, multistage, docker-compose v2, etc.) to configure the build environment and to complete the build process. + +For example, xahaud can be compiled inside an Ubuntu 24.04 Docker container using a Dockerfile to describe the container, download and install dependencies, and build the final product. Note that the following code follows the same steps outlined earlier on this page for the general Linux build process, the steps are simply applied inside an isolated container. It is possible to add additional variables or adjust the following code to customize the build process. + +``` +# ~~~~ Arguments used to customize the container and build ~~~~ +ARG BASE_IMAGE=ubuntu:24.04 # Operating system for the build container +ARG REPO_URL=https://github.com/Xahau/xahaud # URL for the repository with the code to be compiled +ARG REPO_BRANCH=dev # Repository branch that will be used for the build +ARG RELEASE_TYPE=Release # Set to "Release" or "Debug" + +# ~~~~ Initiate a container ~~~~ +FROM --platform=$BUILDPLATFORM ${BASE_IMAGE} AS builder + +ARG REPO_URL +ARG REPO_BRANCH +ARG RELEASE_TYPE + +ENV DEBIAN_FRONTEND=noninteractive \ + BASE_DIR=/build \ + CONAN2_DIR=/root/.conan2 + +# ~~~~ Install build dependencies ~~~~ +RUN apt-get update \ + && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + git curl wget ca-certificates \ + python3 python3-pip python3-venv \ + build-essential cmake ninja-build \ + libc6-dev libssl-dev libsqlite3-dev pkg-config \ + && rm -rf /var/lib/apt/lists/* + +# ~~~~ Clone the xahaud GitHub repository and create a '.build' directory ~~~~ +RUN git clone ${REPO_URL} xahaud && \ + cd xahaud && \ + git checkout ${REPO_BRANCH} && \ + mkdir -p .build + +# ~~~~ Configure Python3 virtual environment and install Conan2 ~~~~ +RUN python3 -m venv ${BASE_DIR}/env && \ + . ${BASE_DIR}/env/bin/activate && \ + pip install --upgrade pip && \ + pip install conan + +# ~~~~ Configure Conan2 profile (the following assumes the user wishes to use cppstd version 20) ~~~~ +RUN . ${BASE_DIR}/env/bin/activate && \ + conan profile detect && \ + CONAN2_PROFILE="${CONAN2_DIR}/profiles/default" && \ + if grep -q '^compiler\.cppstd=' "$CONAN2_PROFILE"; then \ + sed -i 's/^compiler\.cppstd=.*/compiler.cppstd=20/' "$CONAN2_PROFILE"; \ + else \ + echo 'compiler.cppstd=20' >> "$CONAN2_PROFILE"; \ + fi && \ + if ! grep -Fqx "[conf]" "$CONAN2_PROFILE"; then \ + printf "[conf]\ntools.build:cxxflags=['-Wno-restrict']\n" >> "$CONAN2_PROFILE"; \ + fi + +# ~~~~ Export Conan recipies for snappy, soci, and wasmedge ~~~~ +RUN . ${BASE_DIR}/env/bin/activate && \ + cd ${BASE_DIR}/xahaud && \ + conan export external/snappy --version 1.1.10 --user xahaud --channel stable && \ + conan export external/soci --version 4.0.3 --user xahaud --channel stable && \ + conan export external/wasmedge --version 0.11.2 --user xahaud --channel stable + +# ~~~~ Build xahaud ~~~~ +RUN . ${BASE_DIR}/env/bin/activate && \ + cd ${BASE_DIR}/xahaud/.build && \ + conan install .. --output-folder . \ + --settings build_type=${RELEASE_TYPE} \ + --build missing \ + -c tools.build:verbosity=verbose \ + -c tools.compilation:verbosity=verbose \ + -g VirtualBuildEnv \ + -g VirtualRunEnv && \ + cmake -DCMAKE_POLICY_DEFAULT_CMP0091=NEW \ + -DCMAKE_BUILD_TYPE=${RELEASE_TYPE} \ + -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \ + .. && \ + cmake --build . --parallel $(nproc) + +``` + +### Amnesiac Operating Systems + +Configuring a Linux system to completely forget all the software that was installed or modified during runtime provides an easy path to recover from build errors. Typically, an amnesiac operating system is run as a virtual machine with a very large amount of memory available, as all changes are written to memory instead of disk. Building xahaud can take over 20 GB of memory, if all software dependencies/requirements are installed in a memory based overlay file system. It is typically possible to install most of the software dependencies (using `apt` or `dnf`) prior to making the system amnesiac, thereby reducing required memory. To configure an amnesic operating system using Debian based systems: ``` From 4d316aaaae811803aedb319b380cb060fdb1b944 Mon Sep 17 00:00:00 2001 From: JScottBranson Date: Fri, 5 Dec 2025 16:19:29 -0500 Subject: [PATCH 10/25] Minor edits to the linux page. Add a note linking to the BUILD.md file and delete all content (which is outdated) from the macOS page. --- .../infrastructure/build-xahaud/linux.mdx | 17 +- .../infrastructure/build-xahaud/macos.mdx | 169 +----------------- 2 files changed, 14 insertions(+), 172 deletions(-) diff --git a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx index 84e6259..55bd5f0 100644 --- a/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx +++ b/src/content/docs/docs/infrastructure/build-xahaud/linux.mdx @@ -6,7 +6,7 @@ import { Aside } from '@astrojs/starlight/components'; These instructions are designed to work for Debian (i.e., Ubuntu 22.04 and 24.04) and Red Hat Enterprise Linux (9 or 10) based distributions. Many instructions overlap, though differences across operating systems are noted throughout. Efforts are made to test builds across operating systems, however, Ubuntu is the most tested and supported environment for building and running xahaud. -For additional instructions, refer to the [BUILD.md](https://github.com/Xahau/xahaud/blob/dev/BUILD.md) in the Xahau/xahaud GitHub Repository. +For additional instructions, refer to the [BUILD.md](https://github.com/Xahau/xahaud/blob/dev/BUILD.md) file in the Xahau/xahaud GitHub Repository.