Building From Sources

Native Nirmata daemon, command-line wallet and Qt 6 desktop wallet. Clone with submodules:

git clone --recursive https://github.com/NirmataNetwork/NirmataCore.git

The release scripts expect the NirmataGUI repository checked out next to NirmataCore (they read its generated interface); override the location with GUI_HTML_DIR if you keep it elsewhere.

Supported build environments

Platform	Tested toolchain	Desktop framework
Ubuntu 22.04 / 24.04 LTS	GCC, CMake 3.21+, OpenSSL 3, system Boost	Qt 6.8.3
Windows 10 / 11 x64	Visual Studio 2022	Qt 6.8.3 msvc2022_64
macOS 12+	Current Xcode/Clang, Homebrew	Qt 6.8.3

The GUI is built on Qt 6 — the required modules are WebEngine, WebChannel, Positioning, SerialPort and ImageFormats. Older instructions referencing Qt 5, Python 2 or OpenSSL 1.1 are obsolete; do not follow them.

Build the Angular interface

The desktop wallet's UI lives in a separate repository and is built first, from the adjacent checkout:

cd ../NirmataGUI/html_source
npm ci
npm run test
npm run build:desktop

Use Node.js 24 and npm 11. The generated interface is written to NirmataGUI/html.

Linux — Ubuntu 22.04 and 24.04

Install the native dependencies and Qt 6.8.3:

utils/install_deps_ubuntu.sh --with-qt
export QT_PREFIX_PATH="$HOME/.local/Qt/6.8.3/gcc_64"

install_deps_ubuntu.sh installs the same package set on both 22.04 and 24.04 — it detects which ALSA package name your release provides (libasound2 vs. libasound2t64) instead of hard-coding one. --with-qt fetches Qt 6.8.3 with aqtinstall into ~/.local/Qt rather than relying on the distro's own Qt packages, so the same script produces a working toolchain on either release. If Qt is already installed, omit --with-qt and point QT_PREFIX_PATH at your existing installation.

Build and stage the complete application:

GUI_HTML_DIR="$PWD/../NirmataGUI/html" utils/build_script_linux.sh

Output:

• build/linux-release/src/Nirmata — development executable;
• build/dist/Nirmata-linux-<arch>-<version>/ — staging directory;
• build/dist/Nirmata-linux-<arch>-<version>.tar.zst — release archive.

Launch it with run-nirmata.sh inside the staging directory. The .tar.zst archive is a native build and expects compatible system libraries on the target machine; use the AppImage target below when you need a self-contained package instead. On a headless server, QT_QPA_PLATFORM=offscreen is only for smoke tests — Qt WebEngine still needs its runtime libraries present.

AppImage

For a self-contained AppImage, install linuxdeploy and linuxdeploy-plugin-qt, make them available on PATH, then run:

utils/build_script_linux_appimage.sh

The AppImage bundles Qt WebEngine and the required desktop libraries, so it runs across Ubuntu (and other Linux) versions without depending on what's already installed on the target system. On a minimal build host where a runtime library only exists in a private sysroot, pass its full path through the colon-separated NIRMATA_EXTRA_LIBRARIES variable (for example libasound.so.2).

CLI-only build

Set BUILD_GUI=OFF to build the daemon and CLI wallet without the Qt GUI:

BUILD_GUI=OFF utils/build_script_linux.sh

Direct CMake build

cmake -S . -B build/local -DBUILD_GUI=ON -DSTATIC=OFF \
  -DCMAKE_PREFIX_PATH="$QT_PREFIX_PATH"
cmake --build build/local --parallel
ctest --test-dir build/local --output-on-failure

Add -D TESTNET=TRUE to build against testnet instead of mainnet.

Windows 10 and 11

Set the required paths and run the release script. It discovers Visual Studio 2022 and initializes the x64 toolchain automatically when not already running inside a Developer Command Prompt:

set QT_PREFIX_PATH=C:\Qt\6.8.3\msvc2022_64
set BOOST_ROOT=C:\local\boost_1_85_0
set BOOST_LIBRARYDIR=%BOOST_ROOT%\lib64-msvc-14.3
set OPENSSL_ROOT_DIR=C:\OpenSSL-Win64
set GUI_HTML_DIR=F:\GitHub\NirmataGUI\html
utils\build_script_windows.bat

The paths above are examples — use the actual locations on your build machine. Copy utils\configure_local_paths_msvs2022.example.cmd to utils\configure_local_paths_msvs2022.cmd, fill in your values, and call that local file before running the build script; it's git-ignored on purpose. OPENSSL_ROOT_DIR must point to a clean OpenSSL 3 installation — don't mix 1.1 and 3.x headers or libraries.

The deployable output is written to build\dist\Nirmata-Windows-x64. The script runs windeployqt, includes the OpenSSL runtime DLLs, then compiles utils\NIRNATA_CELL.iss with Inno Setup 6, producing the final installer at build\dist\installer\Nirmata-CELL-2.0.0-Windows-x64.exe. Override APP_VERSION, INSTALLER_OUTPUT_DIR or ISCC_EXE before running the script to change the defaults. Copying only Nirmata.exe out of the build tree is not enough to run it — Qt WebEngine needs the rest of the deployed files.

The installer registers both the nir: and legacy nirmata: URL protocols for payment deep links, in the form nir:action=send&address=<address>&amount=1.25&comment=Payment (values URL-encoded). Opening a link works whether the wallet is already running or not.

Windows test build

cmake -S . -B build\windows-tests -G "Visual Studio 17 2022" -A x64 ^
  -DBUILD_GUI=ON -DBUILD_TESTS=ON -DSTATIC=OFF ^
  -DCMAKE_PREFIX_PATH="%QT_PREFIX_PATH%" -DBOOST_ROOT="%BOOST_ROOT%" ^
  -DBOOST_LIBRARYDIR="%BOOST_LIBRARYDIR%" ^
  -DOPENSSL_ROOT_DIR="%OPENSSL_ROOT_DIR%"
cmake --build build\windows-tests --config Release --parallel --target ^
  unit_tests coretests db_tests crypto-tests hash-tests hash-target-tests
ctest --test-dir build\windows-tests -C Release --output-on-failure

macOS

Install Xcode command-line tools and dependencies:

xcode-select --install
brew install qt boost@1.85 openssl@3 cmake ninja rsync

Build the Angular bundle first (see above), then:

export QT_PREFIX_PATH="$(brew --prefix qt)"
GUI_HTML_DIR="$PWD/../NirmataGUI/html" utils/build_script_mac_osx.sh

The script creates and verifies an ad-hoc signed application and writes build/dist/nirmata-macos-<arch>.zip. For distribution outside your own machine, set CODESIGN_IDENTITY to a Developer ID Application identity and notarize the result outside the build script — no keychain password is stored in the repository. After a successful compile, PACKAGE_ONLY=true utils/build_script_mac_osx.sh repeats deployment, portability checks and signing without recompiling.

Useful options

All build scripts accept environment overrides:

• BUILD_DIR, DIST_DIR, GUI_HTML_DIR, JOBS;
• QT_PREFIX_PATH, BOOST_ROOT, OPENSSL_ROOT_DIR;
• testnet=true for a testnet build;
• BUILD_GUI=OFF with the Linux script for CLI-only binaries;
• -DNIRMATA_ENABLE_LTO=ON to opt into release LTO, after verifying the compiler and all Boost binaries use compatible definitions.

For the complete Linux test build (daemon/wallet unit tests, no GUI):

cmake -S . -B build/linux-tests -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_GUI=OFF -DBUILD_TESTS=ON -DSTATIC=OFF
cmake --build build/linux-tests --parallel --target \
  unit_tests coretests db_tests crypto-tests hash-tests
ctest --test-dir build/linux-tests --output-on-failure

Continuous integration

.github/workflows/build.yml builds Ubuntu 24.04, Windows Server 2022 and macOS 14 artifacts on every push. Keep Qt and Node versions aligned with NirmataGUI when updating the toolchain.