83 lines
2.6 KiB
Markdown
83 lines
2.6 KiB
Markdown
# Developer Guide & Repository Reference
|
|
|
|
This guide provides instructions for building, testing, linting, and contributing to the `nx9-wg` codebase.
|
|
|
|
---
|
|
|
|
## 1. Workspace Layout
|
|
|
|
The repository is organized as a Cargo workspace containing 6 crates and the root application binary:
|
|
|
|
- **`crates/nx9-wg-core`**: Common domain entities, RFC validators, cryptography, and configuration.
|
|
- **`crates/nx9-wg-db`**: SQLite database persistence layer, migration SQL scripts, and repository implementations.
|
|
- **`crates/nx9-wireguard`**: WireGuard Generic Netlink execution, RTNETLINK link management, config builder, and QR engine.
|
|
- **`crates/nx9-wg-network`**: RTNETLINK route management, `libnftables.so.1` integration, and procfs forwarding.
|
|
- **`crates/nx9-wg-api`**: Axum REST API router, WebSocket broadcaster, authentication middleware, and reconciliation engine.
|
|
- **`crates/nx9-wg-ui`**: Design tokens, CSS stylesheet compiler, view models, and SPA asset integration.
|
|
- **`src/main.rs`**: Root CLI command parser and daemon entry point.
|
|
|
|
---
|
|
|
|
## 2. Prerequisites & Build Commands
|
|
|
|
### Prerequisites
|
|
- **Rust Toolchain**: 1.85+ (Edition 2024).
|
|
- **C Compiler**: `gcc` or `clang` (for SQLite C amalgamation).
|
|
- **Linux Libraries**: `libnftables-dev` (Debian/Ubuntu) or `nftables-devel` / `libnftables` (Fedora/Arch).
|
|
|
|
### Build Commands
|
|
```bash
|
|
# Debug build
|
|
cargo build --workspace
|
|
|
|
# Release build
|
|
cargo build --release
|
|
|
|
# Format check
|
|
cargo fmt --all -- --check
|
|
|
|
# Clippy linter
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Test Execution & SAFE Mode (`LIVE=0`) vs Privileged Mode (`LIVE=1`)
|
|
|
|
To prevent accidental modifications to developer workstations, all integration and live kernel test scripts default to SAFE mode (`LIVE=0`):
|
|
|
|
```bash
|
|
# 1. Run full workspace unit & integration tests
|
|
cargo test --workspace
|
|
|
|
# 2. Run Comprehensive CLI Verification Suite (210 checks)
|
|
LIVE=0 bash scripts/test-cli-comprehensive.sh
|
|
|
|
# 3. Run Native Linux Integration Test Suite (20 checks)
|
|
LIVE=0 bash scripts/test-native-integration.sh
|
|
|
|
# 4. Run Dedicated Live Kernel Test Suite (24 checks)
|
|
LIVE=0 bash scripts/test-live-kernel.sh
|
|
```
|
|
|
|
### Privileged Real-Kernel Testing (`LIVE=1`)
|
|
> [!CAUTION]
|
|
> `LIVE=1` tests must ONLY be executed on a dedicated disposable Linux virtual machine or container with `CAP_NET_ADMIN`. Never execute `LIVE=1` on a production host.
|
|
|
|
```bash
|
|
# On a dedicated disposable VM as root:
|
|
sudo LIVE=1 bash scripts/test-live-kernel.sh
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Release Packaging
|
|
|
|
To build the self-contained release distribution archives:
|
|
|
|
```bash
|
|
bash scripts/package-release.sh
|
|
```
|
|
|
|
Outputs `.tar.gz`, `.tar.xz`, and `.sha256` files in `target/dist/`.
|