FREE X427 board for the first 50 college students · first 50offer ends 31 Dec

NAVRBOTEC

Reading view

nav

navChapter 2 of 10

Design goals

This chapter describes what nav is built to do, using only what the repository states. Where the repository gives a decision but no reason, the text says so.

Git-based dependencies, no registry#

The README states the position directly: "Dependencies are pulled directly from GitHub via git; no package registry is required." NavHAL itself is fetched the same way as every other dependency.

The library ABI (docs/LIBRARY_ABI.md) says the same thing from the library author's side: "There is no package server: a library is a Git repository, and GitHub is the host." Section 10 names the consequence for identity: "There is no central index and no name lookup: the URL is the identity." A dependency is declared by source:

bme280  = { git = "https://github.com/jane/nav-bme280", ref = "v1.2.0" }
mylib   = { path = "../mylib" }

Exactly one of git or path is allowed per entry. A path dependency is for developing a library alongside an app and is "not publishable". Section 12 describes publishing as pushing source and tagging a release: "There is nothing to upload and no account on a nav service; access control is the repository's own." Libraries are source trees only; the stated reason is that an embedded target is a cross-product of arch, vendor, family, board, toolchain and capability set, "which does not scale" for precompiled binaries.

History: the removed registry#

The README says: "Earlier versions used a self-hosted package registry; it was removed in favor of the simpler git-based approach." That sentence is the only stated reason. The repo does not say what specifically made the registry too complex.

Three files under docs/ are history, not current design: docs/plan.md, docs/mvp.md and docs/auth.md. They describe the registry that was removed. plan.md is an architecture document titled "Embedded Package & Build Manager Architecture". mvp.md is a feature matrix for "self-hosted infrastructure", with a registry backend and index synchronisation. auth.md covers registry authentication, with opaque API tokens and ~/.nav/credentials.toml. None of this applies to nav as it is now. The ABI document replaces pieces of it explicitly; for example, section 12 says "CI replaces the quarantine worker", and discovery is "out of band for v1".

Reproducible pins#

Git refs such as tags and branches can move, so nav records the commit they resolved to. Section 10 of the ABI: "nav.lock records the resolved commit SHA for every git dependency. nav build uses the locked SHA; only nav update moves it." A force-moved tag "is detected as a SHA mismatch and fails the build." Section 12 adds that integrity is "the commit SHA in nav.lock, not a tarball hash".

An empty ref is allowed for local experiments, but nav warns "because it is not reproducible." This shows that reproducibility is an intended property, not a side effect.

Pinning NavHAL#

NavHAL is pinned the same way. A project names it in nav.toml:

[navhal]
ref = "v0.4.0"                      # a tag, branch or commit; default "stable"

nav.lock stores url, ref and commit under a navhal key; src/core/lockfile.cpp reads and renders exactly those three fields, and also a list of git pins with a name in addition. The first nav build or nav create writes the commit, and "every later build links extern/NavHAL to exactly that commit." Each commit has its own checkout under ~/.nav/navhal/commits/, "so apps pinned to different versions build side by side". If a branch ref now points elsewhere and the locked commit is not cached, the build stops. nav update "re-resolves NavHAL's [navhal] ref and every locked library ref from upstream and rewrites their nav.lock pins." Moving a pin is therefore an explicit command.

An extern/NavHAL that is a real directory (vendored) "is left alone".

One CLI over cmake and the ARM toolchain#

The README describes nav as a tool that "scaffolds a project, resolves dependencies from git, cross-compiles with the ARM toolchain, flashes the result to hardware, and opens a serial monitor — so a normal edit / build / flash / debug loop is a few short commands." The quick start is nav create, nav build, nav upload, nav monitor. nav.toml carries backend = "cmake" under [build], and the README says nav build cross-compiles "with the arm-none-eabi toolchain". nav check verifies that the toolchain and flasher are present and working.

The repo does not state a rationale for choosing cmake as the backend.

Generated build files#

A project's CMakeLists.txt is produced from templates/cmakelists.txt.in, whose header comment begins "Nav-generated board context. Generated by nav build from share/nav/boards/." The README gives the project's inputs as nav.toml fields: sources, include directories, defines, flags, linker fragment and libc choice. nav build expands source globs "into build/nav-app.cmake each time". It also writes <build dir>/nav-effective.config from the app's .config and passes it to NavHAL by path, so "the shared checkout is never written and concurrent builds ... do not race".

Because the build file is generated from a template, an old project can fall behind the template. nav regen handles this: it "rewrites a nav-generated CMakeLists.txt from the current template, after saving the old one as CMakeLists.txt.old. It refuses a CMakeLists.txt that nav did not generate." A project made by an older nav keeps building as before. If its nav.toml uses [build] keys, nav build says so and the fix is nav regen.

The repo does not state a general reason for preferring generated CMake over hand-written CMake. What it shows is that the manifest holds the settings and the template turns them into CMake.

Sources#

  • README.md: intro (lines 1-10), Commands table (nav check, nav update, nav regen rows, lines 37-51), [build] section (lines 53-78), nav regen (lines 119-120), Pinning NavHAL (lines 193-226), Dependencies (lines 246-250).
  • docs/LIBRARY_ABI.md: intro (lines 1-15), section 10 Dependencies (lines 278-352), section 12 Distribution (lines 370-395).
  • src/core/lockfile.cpp: load_lockfile and render_lockfile (lines 27-145), for the fields pinned.
  • templates/cmakelists.txt.in: header comment (line 3). templates/nav.toml.in: [build] backend (lines 1-15).
  • docs/plan.md, docs/mvp.md, docs/auth.md: opening sections only, as history of the removed registry.