# Shekyl Installation Guide This guide documents how to build and run Shekyl from source using the current repository build system. It is intentionally Shekyl-native (binary names and commands), even where legacy docs still reference `monero*`. --- ## 1) What this guide covers - Supported platforms and practical build targets. - Required and optional dependencies. - Build flows using both top-level `Makefile` and direct CMake. - Shekyl binary names and first-run verification. - Common pitfalls (submodules, compatibility flags, RPC safety). --- ## 2) Supported platforms ### Documented by repository docs The project README documents build/run guidance for: - Linux and macOS - Windows (MSYS2/MinGW) - Raspberry Pi - FreeBSD, OpenBSD, NetBSD, Solaris ### Practical baseline If you are starting fresh, prefer: - Linux (Debian/Ubuntu/Fedora/Arch) - macOS - Windows via MSYS2 --- ## 3) Dependencies The dependency matrix is maintained in `README.md` and includes: - compiler/tooling: GCC, CMake, pkg-config - core libs: Boost, OpenSSL, libzmq/OpenPGM, libunbound, libsodium - optional libs/tools: libunwind, readline, expat, gtest, ccache, doxygen/graphviz - optional hardware wallet stack: hidapi, libusb, protobuf/protoc, libudev ### Rust integration behavior Rust modules are integrated via `cmake/BuildRust.cmake`: - if `cargo` is found, Rust workspace under `rust/` is built and linked - if `cargo` is not found, build continues with Rust modules disabled Install Rust toolchain when you want full Rust-enabled builds: ```bash curl https://sh.rustup.rs -sSf | sh source "$HOME/.cargo/env" ``` ### PQC build note Shekyl's rebooted chain design depends on Rust-based PQC components. Today: - some Rust modules are optional at build time - PQC implementation is still being completed Target state for the rebooted mainnet: - Rust toolchain will be a required dependency for consensus-valid builds - node operators, wallet builders, and release builders should assume a Rust-enabled build is mandatory - the canonical PQC design and transaction format are documented in `docs/POST_QUANTUM_CRYPTOGRAPHY.md` --- ## 4) Clone and prepare source Clone recursively to include required submodules: ```bash git clone --recursive cd Shekyl ``` If already cloned without submodules: ```bash git submodule update --init --force ``` Important: CMake checks submodule state and can fail if submodules are out of sync (unless you explicitly pass `-DMANUAL_SUBMODULES=1`). --- ## 5) Build on Linux/macOS ### Quick path (recommended) From repository root: ```bash make ``` This builds release artifacts under a `build/.../release` path (or `build/release`, depending on builddir mode). ### Common build targets ```bash make release-all # release + tests enabled at build time make release-test # release build, then run tests make debug # debug build make release-static # static build make coverage # debug + coverage + tests ``` ### Explicit CMake path (equivalent control) ```bash cmake -S . -B build -D CMAKE_BUILD_TYPE=Release -D BUILD_TESTS=ON cmake --build build --target all ``` --- ## 6) Build on Windows (MSYS2/MinGW) Open MSYS2 MinGW shell and install toolchain + dependencies (64-bit example): ```bash pacman -Syu pacman -S mingw-w64-x86_64-toolchain make mingw-w64-x86_64-cmake \ mingw-w64-x86_64-boost mingw-w64-x86_64-openssl mingw-w64-x86_64-zeromq \ mingw-w64-x86_64-libsodium mingw-w64-x86_64-hidapi mingw-w64-x86_64-unbound ``` Then: ```bash git clone --recursive cd Shekyl make release-static-win64 ``` For 32-bit builds use `make release-static-win32`. --- ## 7) Shekyl binary names and locations The current CMake targets produce: - daemon: `shekyld` - CLI wallet: `shekyl-wallet-cli` - wallet RPC: `shekyl-wallet-rpc` Typical output location: - `/bin/` For a common release flow: - `build/release/bin/shekyld` - `build/release/bin/shekyl-wallet-cli` - `build/release/bin/shekyl-wallet-rpc` Note: some legacy or upstream docs/config examples may still use older daemon/wallet names; use Shekyl names above for this repository. --- ## 8) First-run verification From your build output directory: ```bash ./shekyld --version ./shekyld --help ./shekyl-wallet-cli --help ./shekyl-wallet-rpc --help ``` Start daemon in foreground: ```bash ./shekyld ``` Start daemon detached: ```bash ./shekyld --log-file shekyld.log --detach ``` If running a public remote RPC node, always use restricted mode. --- ## 9) Optional compatibility/build flags ### Better libc compatibility across older Linux systems Use: ```bash cmake -S . -B build -D CMAKE_BUILD_TYPE=Release -DBACKCOMPAT=ON cmake --build build ``` ### Manual submodule override (advanced only) If you intentionally manage submodules outside CMake checks: ```bash cmake -S . -B build -DMANUAL_SUBMODULES=1 ``` ### Static builds and `-fPIC` Some static dependencies may need to be rebuilt with `-fPIC` for successful static linking. --- ## 10) Runtime safety notes - For public node operation, use restricted RPC mode. - On macOS, if you encounter refresh/runtime instability, try `--max-concurrency 1`. - Keep daemon and wallet versions from the same build. - Prefer explicit `--data-dir` and `--config-file` paths in service environments. --- ## 11) Troubleshooting ### CMake fails with submodule error Fix: ```bash git submodule update --init --force ``` Then rerun CMake. ### Rust components not built If configure output indicates cargo not found, install Rust/cargo and rebuild. ### Missing dependencies Install packages for your distro from the dependency section in `README.md`, then clean/rebuild. ### Built binaries do not run on older Linux distro Rebuild with `-DBACKCOMPAT=ON`. --- ## 12) Related docs - `README.md` (full dependency matrix and platform specifics) - `Makefile` (build targets) - `CMakeLists.txt` (build options, submodule checks, linker flags) - `shekyl-dev/docs/SEEDS_SETUP.md` (seed bootstrap model and runtime seed/peer controls) - `shekyl-dev/docs/SEED_NODE_DEPLOYMENT.md` (step-by-step seed node and shekyl.org caching deployment) - `docs/POST_QUANTUM_CRYPTOGRAPHY.md` (canonical PQC spec and reboot-only transaction format)