Trailgen
Trailgen is a native Rust workbench for finding, drawing, inspecting, and keeping long-day hiking routes. The GUI is the product frontend. Its vector map, trail acquisition, route search, editor, project Library, and GPX export share one engine.
Install
Cargo places the unified trailgen binary under its configured binary root.
For a checkout build, ./scripts/install-local.sh installs the same binary
beneath ~/.local/bin. Bare trailgen resumes the last chosen project or
opens the project deck. New projects conventionally live beneath the host
platform's Documents directory in trailgen/; Trailgen honors the directory
reported by the operating system and never invents a Linux ~/Documents.
Trailgen is release-tested on Linux/X11, Linux/Wayland, macOS on Apple and Intel silicon, and 64-bit Windows. Linux delivery is the ordinary Cargo install above. Releases also carry an unsigned universal macOS disk image and an unsigned current-user Windows installer; Gatekeeper or SmartScreen may therefore require an explicit user override.
Projects are portable directories rooted by trailgen.toml. Project content, including the canonical saved-trail Library, stays in that directory. View and window state belongs under $XDG_STATE_HOME/trailgen, app-wide preferences under $XDG_CONFIG_HOME/trailgen, and shared map cache under $XDG_CACHE_HOME/trailgen.
Workflow
- Create a project and pan to its territory.
- Draw one or more bronze-framed map areas. Trailgen acquires and indexes their union.
- Draw a trail directly from support points, or place a trailhead and search by distance, moving time, climb, target lower-limb load, and shape.
- Inspect a trail on the full map and elevation profile. Save it when it deserves durable project identity.
- In Saved Trails, press
↥beside its name to export GPX. Unsaved candidates and unfinished edits cannot be exported.
The GPX carries one contiguous hiking track, the Library name, elevations where known, and the saved measurements in its description. Upload that file to AllTrails as a custom route, then open it under Saved → Lists → Custom routes & maps for navigation. See the AllTrails handoff.
The default US corpus combines OpenStreetMap/Overpass, USGS National Digital Trails, spatially applicable state-park authorities, and cached Mapzen terrain tiles. New York and Texas are the first admitted state providers. Provider responses are independently sequestered beneath sources/, fingerprinted, and rebuilt through one graph path before cache/graph.bin becomes ready. Informal standing, wayfinding, terrain, and legal access remain distinct facts. See data sources.
Keyboard
F1 or ? opens the generated command guide for the current workspace. An
underlined letter is an Alt mnemonic. Tab and Shift+Tab traverse controls
inside the active inspector panel; physical Control+Tab and
Control+Shift+Tab move between panels on every platform. Primary shortcuts
use Command on macOS and Control elsewhere.
Trailgen declares typed commands once. The same declaration routes their accelerators, supplies button labels and mnemonic underlines, and populates the guide with current availability and refusal reasons. Map gestures and other target-relative interactions remain in the guide without pretending to be global commands.
Debug Shell
The shell is deliberately incomplete. It exposes only operations already owned by the GUI application service:
Bare trailgen and trailgen gui launch the same native workbench. saved prints durable Library identities and names. export invokes the same saved-trail GPX writer as the ↥ control; it does not regenerate, reinterpret, or select transient candidates. New shell commands belong here only when a concrete debugging need appears and shared product logic already owns the operation.
Verification
scripts/verify-install proves a sterile non-default install and Cargo-tracked
uninstall. scripts/test-gui is the hermetic X11 acceptance gate. Its
complete user stories cover GUI project creation and provider acquisition,
saved-trail refinement and restart, twelve-candidate comparison under cadence
budgets, manual trail design, saved GPX export, and productive work while graph
armament is deliberately stalled. It also proves generated-help presentation,
modal key isolation, and inspector-panel traversal. scripts/test-wayland owns the narrower
isolated Wayland contract: native launch, first presentation, semantic witness,
and nonblack compositor capture.
scripts/package executes a locked workspace package transaction for every
publishable crate without relying on already-published internal versions.
scripts/release VERSION publish requires the pushed commit and a valid signed
tag, repeats every gate, publishes the five-crate graph in dependency order,
then verifies the complete registry-resolved package graph. The pinned Foundry
workflow publishes the unsigned native artifacts and a machine-readable support
receipt only after the declared proof graph passes.
See installation, project state, model, physical load and moving time, and known limitations.
License
Licensed under either Apache-2.0 or MIT, at your option.