Skip to content

Commit 22b7cfa

Browse files
jamescowensjamescowens
committed
Add build-dependencies.md and update build.md and cmake-options.md
1 parent 13363ef commit 22b7cfa

File tree

3 files changed

+181
-31
lines changed

3 files changed

+181
-31
lines changed

‎doc/build-dependencies.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Gridcoin Build Dependencies
2+
3+
This document lists the package commands required to set up a build environment for Gridcoin on various operating systems.
4+
5+
## Linux (Native Build)
6+
7+
These packages are required to build the Gridcoin client to run on your local Linux machine.
8+
9+
### Debian / Ubuntu / Mint
10+
```bash
11+
sudo apt-get update
12+
sudo apt-get install \
13+
build-essential libtool autotools-dev automake pkg-config bsdmainutils python3 \
14+
cmake git curl \
15+
libssl-dev libevent-dev libboost-all-dev \
16+
libminiupnpc-dev libqrencode-dev libzip-dev \
17+
qt6-base-dev qt6-tools-dev qt6-l10n-tools libqt6charts6-dev
18+
````
19+
20+
### Fedora / RHEL
21+
22+
```bash
23+
sudo dnf install \
24+
gcc-c++ libtool automake autoconf pkgconf-pkg-config python3 \
25+
cmake git curl \
26+
openssl-devel libevent-devel boost-devel \
27+
miniupnpc-devel qrencode-devel libzip-devel \
28+
qt6-qtbase-devel qt6-qttools-devel qt6-qtcharts-devel
29+
```
30+
31+
### openSUSE
32+
33+
```bash
34+
sudo zypper install \
35+
-t pattern devel_basis \
36+
libtool automake autoconf pkg-config python3 \
37+
cmake git curl \
38+
libopenssl-devel libevent-devel boost-devel \
39+
miniupnpc-devel qrencode-devel libzip-devel \
40+
qt6-base-devel qt6-tools-devel qt6-charts-devel
41+
```
42+
43+
### Arch Linux / Manjaro
44+
45+
```bash
46+
sudo pacman -S \
47+
base-devel python cmake git \
48+
boost libevent miniupnpc libzip qrencode \
49+
qt6-base qt6-tools qt6-charts
50+
```
51+
52+
-----
53+
54+
## Linux (Windows Cross-Compilation)
55+
56+
These packages are required **in addition** to the native dependencies if you intend to build Windows binaries from a Linux host.
57+
58+
### Debian / Ubuntu (WSL)
59+
60+
```bash
61+
# Required for the cross-compiler and NSIS installer generator
62+
sudo apt-get install g++-mingw-w64-x86-64 nsis
63+
```
64+
65+
### Fedora
66+
67+
```bash
68+
sudo dnf install mingw64-gcc-c++ mingw64-nsis
69+
```
70+
71+
### openSUSE
72+
73+
```bash
74+
sudo zypper install mingw64-cross-gcc-c++ nsis
75+
```
76+
77+
### Arch Linux
78+
79+
```bash
80+
# Requires packages from AUR
81+
paru -S mingw-w64-gcc nsis
82+
```
83+
84+
-----
85+
86+
## macOS (Homebrew)
87+
88+
```bash
89+
brew install cmake boost libevent qt@6 openssl@3 zeromq
90+
```
91+
92+
-----
93+
94+
## BSD Variants
95+
96+
### FreeBSD
97+
98+
```bash
99+
pkg install git cmake boost-libs qt6 libevent openssl
100+
```
101+
102+
### OpenBSD
103+
104+
```bash
105+
pkg_add git cmake boost qt6 libevent
106+
```

‎doc/build.md‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,19 +25,22 @@ This document covers the three primary build targets:
2525

2626
* **CMake:** 3.18 or later
2727
* **Compiler:** GCC (C++17 support required) or Clang. If your system compiler is not compliant, you will need to install
28-
a compiler that is C++17 compliant and use -DCMAKE_CXX_COMPILER=\<C++ compiler\> and -DCMAKE_C_COMPILER=\<C compiler\>
28+
a compiler that is C++17 compliant and use -DCMAKE_CXX_COMPILER=\< C++ compiler \> and -DCMAKE_C_COMPILER=\< C compiler \>
2929
* **Qt:** Version 5.15 or 6.x
30-
* **Boost:** Version 1.70 or later
30+
* **Boost:** Version 1.60 or later
31+
* Please refer to [link](build-dependencies.md) (build-dependencies.md) for packages that must be installed before building.
3132

3233
-----
3334

3435
## Quick Reference
3536

36-
| Target | Primary Use Case | Key CMake Flags |
37+
| Target | Primary Use Case |
3738
| :--- | :--- | :--- |
38-
| **Linux Native** | Development, Package Maintainers | `cmake -B build` |
39-
| **Linux Static** | Portable Releases (Tarballs) | `-DSTATIC_LIBS=ON` (requires `depends`) |
40-
| **Windows** | Windows Installer/Executable | `-DCMAKE_TOOLCHAIN_FILE=...` (requires `depends`) |
39+
| **Linux Native** | Development, Package Maintainers |
40+
| **Linux Static** | Portable releases, especially useful for older distributions that can't meet native package dependencies |
41+
| **Windows Cross-Compile** | Windows installer/Executable |
42+
43+
Please refer to [Link](cmake-builds.md) for a list of cmake configuration options.
4144

4245
-----
4346

@@ -62,7 +65,7 @@ cmake -B build \
6265
-DENABLE_PIE=ON \
6366
-DENABLE_DOCS=ON \
6467
-DENABLE_TESTS=ON \
65-
-DCMAKE_BUILD_TYPE=\<Release \| RelWithDebInfo \| Debug - see table below\>
68+
-DCMAKE_BUILD_TYPE=\< Release | RelWithDebInfo | Debug - see table below \>
6669
```
6770

6871
### Step 2: Build & Test
@@ -116,7 +119,7 @@ cmake -B build_linux_depends \
116119
-DDEP_LIB="${DEP_LIB}" \
117120
-DCMAKE_CXX_FLAGS="-fPIE" \
118121
-DCMAKE_EXE_LINKER_FLAGS="-static-libgcc -static-libstdc++ -Wl,-Bdynamic" \
119-
-DCMAKE_BUILD_TYPE=\<Release \| RelWithDebInfo \| Debug - see table below\>
122+
-DCMAKE_BUILD_TYPE=\< Release | RelWithDebInfo | Debug - see table below \>
120123
```
121124

122125
### Step 3: Build & Test
@@ -137,7 +140,7 @@ sudo cmake --install build
137140

138141
-----
139142

140-
## 3\. Windows Build (Cross-Compile)
143+
## 3\. Windows Cross-Compile Build
141144

142145
This procedure generates a Windows 64-bit executable (`.exe`) from a Linux host using the Mingw-w64 toolchain provided by the `depends` system.
143146

@@ -171,7 +174,7 @@ cmake -B build_win64 \
171174
-DSYSTEM_XXD=ON \
172175
-DCMAKE_CROSSCOMPILING_EMULATOR=/usr/bin/wine \
173176
-DCMAKE_EXE_LINKER_FLAGS="-static" \
174-
-DCMAKE_BUILD_TYPE=\<Release \| RelWithDebInfo \| Debug - see table below\>
177+
-DCMAKE_BUILD_TYPE=\< Release | RelWithDebInfo | Debug - see table below \>
175178
```
176179

177180
### Step 3: Build & Test

‎doc/cmake-options.md‎

Lines changed: 62 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,77 @@
1-
## CMake Build Options
1+
# CMake Build Options Reference
22

3-
You can use GUI (`cmake-gui`) or TUI (`ccmake`) to browse and toggle all
4-
available options:
3+
This document details the CMake configuration options available for Gridcoin. These flags control which features are compiled, how dependencies are found, and how the final executable is linked.
54

6-
```bash
7-
mkdir build && cd build
8-
cmake ..
9-
ccmake .
10-
```
5+
## General Configuration
6+
7+
| Option | Default | Description |
8+
| :--- | :--- | :--- |
9+
| `CMAKE_BUILD_TYPE` | *Empty* | Controls optimization and debug symbols. Recommended values: `RelWithDebInfo` (Default/Dev), `Release` (Production), `Debug`. If left empty, no optimization is applied. |
10+
| `ENABLE_GUI` | `OFF` | Builds the Qt-based graphical user interface (`gridcoinresearch`). If `OFF`, only the daemon (`gridcoinresearchd`) is built. |
11+
| `ENABLE_TESTS` | `OFF` | Builds the unit test suite (`src/test/`). Recommended for all developers. |
12+
| `ENABLE_DOCS` | `OFF` | Generates Doxygen documentation. |
13+
| `STATIC_LIBS` | `OFF` | Forces the build system to look for static libraries (`.a`) instead of shared libraries (`.so`). Required for `depends` builds. |
14+
| `ENABLE_PIE` | `OFF` | Enables Position Independent Executables (PIE) for hardening. Recommended for Linux production builds. |
15+
16+
---
1117

12-
### Common configurations
18+
## Features & Dependencies
1319

14-
* Build with GUI, QR code support and DBus support:
20+
These options toggle specific functionality within the Gridcoin client.
1521

16-
`cmake .. -DENABLE_GUI=ON -DENABLE_QRENCODE=ON -DUSE_DBUS=ON`
22+
| Option | Default | Why Use It? | Dependencies |
23+
| :--- | :--- | :--- | :--- |
24+
| `ENABLE_UPNP` | `OFF` | **Universal Plug and Play.** Allows the client to automatically map ports on your router for incoming connections. Useful for home users behind NAT. | `miniupnpc` |
25+
| `DEFAULT_UPNP` | `OFF` | If `ENABLE_UPNP` is ON, this sets the default runtime behavior to "Start with UPnP enabled". | `ENABLE_UPNP` |
26+
| `ENABLE_QRENCODE` | `OFF` | **QR Codes.** Allows the GUI to display QR codes for wallet addresses. Convenient for mobile payments. | `libqrencode` |
27+
| `USE_DBUS` | `OFF` | **Desktop Bus.** Enables OS notifications on Linux desktops (e.g., "Staked a block!"). | `QtDBus` |
28+
| `USE_QT6` | `OFF` | Builds against Qt 6 instead of Qt 5. Recommended for modern Linux distributions. | `Qt6` |
1729

18-
* Build with UPnP:
30+
---
1931

20-
`cmake .. -DENABLE_UPNP=ON -DDEFAULT_UPNP=ON`
32+
## Advanced / Cross-Compilation
2133

22-
* Enable PIE and disable assembler routines:
34+
These options are primarily used by the `depends` system or advanced users.
2335

24-
`cmake .. -DENABLE_PIE=ON -DUSE_ASM=OFF`
36+
| Option | Default | Description |
37+
| :--- | :--- | :--- |
38+
| `SYSTEM_XXD` | `OFF` | Uses the host system's `xxd` binary instead of building one. **Required** when cross-compiling (e.g., Linux -> Windows). |
39+
| `SYSTEM_UNIVALUE` | `OFF` | Links against a system-installed `libunivalue` instead of the in-tree submodule. |
40+
| `SYSTEM_SECP256K1` | `OFF` | Links against a system-installed `libsecp256k1`. |
41+
| `SYSTEM_LEVELDB` | `OFF` | Links against a system-installed `libleveldb`. |
42+
| `SYSTEM_BDB` | `OFF` | Links against a system-installed Berkeley DB. *Note: Gridcoin requires BDB 5.3, which is rare in modern distros.* |
43+
44+
## Example Configurations
45+
46+
### Standard Developer Build (Linux)
47+
```bash
48+
cmake -B build -DENABLE_GUI=ON -DENABLE_QRENCODE=ON -DUSE_DBUS=ON \
49+
-DENABLE_TESTS=ON -DENABLE_UPNP=ON -DDEFAULT_UPNP=ON \
50+
-DCMAKE_BUILD_TYPE=RelWithDebInfo
51+
````
2552

26-
* Build a static binary:
53+
### Minimal GUI Developer Build (Linux)
54+
```bash
55+
cmake -B build -DENABLE_GUI=ON -DENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo
56+
````
2757
28-
`cmake .. -DSTATIC_LIBS=ON -DSTATIC_RUNTIME=ON`
58+
### Minimal GUI Developer Build (Linux) for Detailed Debug
59+
```bash
60+
cmake -B build -DENABLE_GUI=ON -DENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Debug
61+
```
2962

30-
* Build tests and docs, run `lupdate`:
63+
### Headless Server / Daemon Only
3164

32-
`cmake .. -DENABLE_DOCS=ON -DENABLE_TESTS=ON -DLUPDATE=ON`
65+
```bash
66+
cmake -B build -DENABLE_GUI=OFF -DENABLE_UPNP=OFF -DCMAKE_BUILD_TYPE=Release
67+
```
3368

34-
* Build with system libraries:
69+
### Full Feature Release
3570

36-
`cmake .. -DSYSTEM_BDB=ON -DSYSTEM_LEVELDB=ON -DSYSTEM_SECP256K1=ON -DSYSTEM_UNIVALUE=ON -DSYSTEM_XXD=ON`
71+
```bash
72+
cmake -B build \
73+
-DENABLE_GUI=ON -DENABLE_QRENCODE=ON -DUSE_DBUS=ON \
74+
-DENABLE_UPNP=ON -DDEFAULT_UPNP=ON \
75+
-DENABLE_PIE=ON \
76+
-DCMAKE_BUILD_TYPE=Release
77+
```

0 commit comments

Comments
 (0)