Skip to content

getting-started.md

Latest commit

 

History

History
161 lines (121 loc) · 4.8 KB

getting-started.md

File metadata and controls

161 lines (121 loc) · 4.8 KB
Raw

Getting Started

This guide covers the shortest supported paths for installing LXMF-rs, building a checkout, running the host tools, and adding the Rust libraries to an application.

Install a stable release

The v0.12.0 release adds the scoped Reticulum 1.5.4-dev feature update on the tested RNS 1.5.2-compatible baseline. It provides Linux, macOS, and Windows archives, Debian and RPM packages, a Windows MSI, SBOMs, and checksum files. Choose the asset for your platform and verify it against SHA256SUMS.txt before extracting or installing it.

For example, after downloading the Linux x86-64 archive and SHA256SUMS.txt into the same directory:

grep 'lxmf-rs_0.12.0_linux-x86_64.tar.gz$' SHA256SUMS.txt | sha256sum -c -
tar -xzf lxmf-rs_0.12.0_linux-x86_64.tar.gz

The latest release page is the durable entry point for future versions. Release claims and evidence boundaries are described in the release notes and current roadmap.

Build from source

The workspace requires Rust 1.85 or newer. The bootstrap helper checks the Rust toolchains, installs the repository's Cargo tools, fetches locked dependencies, and runs a formatting smoke check:

git clone https://github.com/FreeTAKTeam/LXMF-rs.git
cd LXMF-rs
make bootstrap

The direct script form is:

./tools/scripts/bootstrap-dev.sh

To inspect an existing environment without installing tools or running the smoke check:

./tools/scripts/bootstrap-dev.sh --check --skip-smoke

Build the user-facing host tools with:

cargo build --release -p lxmf-cli -p reticulumd -p rns-tools

Run locally

Start reticulumd on its default local Unix RPC endpoint:

cargo run -p reticulumd --bin reticulumd

Useful command entry points include:

cargo run -p lxmf-cli --bin lxmf -- --help
cargo run -p lxmf-cli --bin lxmd -- --help
cargo run -p rns-tools --bin rnsd -- --help
cargo run -p rns-tools --bin rnstatus-rs -- --help
cargo run -p rns-tools --bin rnx -- --help

Optional rngit WebP conversion

rngit can convert image media to WebP while serving pages, but the Rust package does not bundle or require a native image converter. Install one of these executables and make it available on PATH to enable conversion:

  • ImageMagick 7: magick
  • ImageMagick 6: convert
  • GraphicsMagick: gm
  • FFmpeg: ffmpeg
  • Libav: avconv

Without a converter, with RNGIT_MEDIA_BACKEND set to an unavailable backend, or when conversion fails, rngit serves the original media bytes. Select a specific backend by setting RNGIT_MEDIA_BACKEND to one of the executable names above; automatic selection follows the built-in preference order. Use --no-media-conversion to disable conversion. --media-quality (default 85) and --media-max-dimension configure the WebP output. Conversion is bounded to 8 seconds and converted output is capped at 32 MiB.

For the complete command options, run cargo run -p rns-tools --bin rngit -- --help.

For a working daemon-and-client flow, continue with the checked examples. For production operation, use the reticulumd deployment runbook or the lxmd systemd guide.

Add the Rust libraries

The umbrella crates provide the simplest dependency surface:

[dependencies]
lxmf = "0.12.0"
reticulum-rs = "0.12.0"

Applications that need narrower features can depend on component crates:

[dependencies]
lxmf-sdk = "0.12.0"
lxmf-wire = "0.12.0"
reticulum-rs-core = "0.12.0"
reticulum-rs-transport = "0.12.0"
reticulum-rs-rpc = "0.12.0"

Use the SDK quickstart for a minimal client, the SDK guide for lifecycle and backend choices, and the workspace guide for package responsibilities.

Validate a checkout

Start with the checks closest to your change:

cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo test --workspace --tests
cargo clippy --workspace --all-targets --all-features --no-deps -- -D warnings
tools/scripts/check-boundaries.sh

The repository also provides consolidated gates:

cargo xtask ci
cargo run -p xtask -- architecture-checks
cargo xtask release-check

Read the contributor guide before submitting changes and the release-readiness runbook before treating local results as release evidence.

Next steps