The atopile toolchain¶

Setting up atopile¶

uv --version                 # 0.12.21 (pins.json); install uv with pipx or into a private venv
yapnr atopile setup          # ~/.cache/yapnr/atopile/<lock-id>/, about 15 s with a warm uv cache
yapnr atopile info
yapnr doctor                 # "atopile   0.15.8 via yapnr atopile setup (...) (ok)"

setup creates <root>/<lock-id>/ (root: $YAPNR_ATOPILE_HOME, else $XDG_CACHE_HOME/yapnr/atopile, else ~/.cache/yapnr/atopile); the lock id is the first 12 hex digits of the sha256 of the platform’s lock and pins.json, so a new lock gets a new directory:

• python/: CPython 3.14.7 from python-build-standalone release 20260929, installed by uv; the release is checked against pins.json.

• venv/: installed with uv pip install --require-hashes --no-deps from yapnr/frontends/atopile/locks/requirements-<platform>.lock. Every file is one the lock names by sha256; nothing is resolved at install time.

• yapnr-atopile-env.json: written last. An environment without it is incomplete and is rebuilt. It records the platform, the lock, the versions, and on linux-aarch64 the name and sha256 of the self-built atopile wheel.

With setup --root DIR, builds find the environment with YAPNR_ATOPILE_HOME=DIR (or YAPNR_ATO_PYTHON), and yapnr atopile info --root DIR reports it.

setup never runs atopile’s command line (the version is read from package metadata), so it cannot touch the user’s KiCad or atopile configuration.

tools/atopile/update_locks.sh          # rewrite the locks
tools/atopile/update_locks.sh --check  # fail if a re-resolution differs

tools/atopile/build_wheel.sh /tmp/atopile-wheel
yapnr atopile setup --wheel /tmp/atopile-wheel/atopile-0.15.8-*.whl

Building¶

yapnr atopile build path/to/project                 # build "default"
yapnr atopile build path/to/project -b mini --out out/mini

For each build the runner:

1. copies the project into a fresh work directory (without the top-level build/, manufacturing/ and yapnr-out/, any .git or __pycache__, or atopile’s caches; .ato/modules is kept). With --files-from LIST it copies exactly the files the list names (paths relative to the project; the Bazel rule passes its declared inputs). The source tree is never written; --update-layout copies the new layout back, and nothing else does;

2. writes every part of the project’s parts lock (yapnr-parts.lock.json) into the copy, each file checked against the cache’s sha256. A part directory already in the tree with other content is an error (--replace-parts overwrites it);

3. writes the stock KiCad footprint libraries that the sources reference into the build’s fp-lib-table (below);

4. starts the offline picker on the loopback interface, answering from the catalog entries of the locked parts and any --catalog files;

5. runs python -m atopile build -b <build> -t ... -x default -x datasheets -x collect-manufacturing -v with the allowlisted environment and a deadline (--timeout, default 1800 s). On the deadline the whole process tree is stopped and killed, atopile’s forkserver and workers included;

6. frames the board if asked (--outline-margin-mm: parts moved into view, a fitted sheet and an Edge.Cuts rectangle; for code-only example boards);

7. copies the named outputs and result.json into --out (default ./yapnr-out/<project>/<build>). An existing output directory is replaced only when it holds an earlier build’s result.json; the project directory never is.

The default targets are build-design, bom, variable-report, power-tree and pinout. Allowed besides: manifest, stackup, data-interface-layout, and the KiCad exports mfg-data, step, glb, 2d-image and 3d-image. atopile always adds its default target, whose datasheet downloads reach the network; the runner excludes it, and datasheets.

The board, its fp-lib-table and the outputs are wherever atopile puts them for the project’s ato.yaml: paths.layout and paths.build, and a build’s own paths.layout, fp_lib_table and output_base. As in atopile, a layout directory holding one board of another name (KiCad’s autosaves aside) is that build’s board, and two are an error. Every path must stay inside the project. The outputs are named after the build whatever the board’s file name; result.json records the board’s path in the project (layout).

build/manifest.json is never copied: it holds absolute paths.

result.json records the atopile version and where it was found, the targets, the exit code, the sha256 of every output, the parts and the sha256 of the parts lock and of the catalog the picker served, the KiCad version, every request the picker answered, the LCSC ids attached from the project’s parts, and anything the hook refused. Its input id is the sha256 of the board with every UUID replaced by the nil UUID: atopile stamps fresh UUIDs on each build, and two builds of the same sources give the same input id.

--online lets atopile download a picked part that is not in the project from EasyEDA (as ato create part does). Such a build depends on a third-party service and is not reproducible; use it only while authoring.

Parts¶

A project keeps its parts out of its tree: yapnr-parts.lock.json, next to ato.yaml, pins each part by content id, and the build materializes them from the part cache:

{
  "parts": [
    {
      "id": "211d87d939ed74ac0b1ff2b144459c44792c3acaa40496cebd4e3d57af14780b",
      "lcsc": "C990000001",
      "name": "Yapnr_Synthetic_SR1K"
    }
  ],
  "parts_dir": "elec/src/parts",
  "schema": "yapnr-atopile-parts-lock-v1"
}

yapnr atopile lock-parts path/to/project --upload --imported-from "my-board"   # parts -> cache
yapnr atopile materialize path/to/project                                     # cache -> tree

The picker serves the catalog entries of the locked LCSC ids only, so a type pick chooses among parts the build can attach offline. --catalog adds catalog files (the first catalog wins on a repeated LCSC id).

The offline picker¶

The picker speaks atopile 0.15.8’s components API:

Type queries (resistors, capacitors, inductors) filter by kind, package (R0402 matches 0402) and every constrained parameter: a part matches when its band (the nominal value widened by its tolerance, or a rated value) lies inside the requested interval, and a part that lacks a constrained parameter does not match. Basic parts rank first, then the value closest to the middle of the request. The server binds only literal loopback addresses, requires a loopback Host header, limits request bodies, and never logs the Authorization header.

Catalogs use the yapnr-picker-catalog-v1 schema (JSON; YAML when PyYAML is available):

{
  "schema": "yapnr-picker-catalog-v1",
  "provenance": { "source": "...", "retrieved": "2026-09-30", "licence_note": "..." },
  "parts": [
    {
      "lcsc": "C990000001",
      "mpn": "SR1K",
      "manufacturer": "yapnr-synthetic",
      "package": "0603",
      "kind": "resistor",
      "description": "synthetic 1 kohm 1 % 0603 resistor",
      "params": { "resistance_ohm": 1000.0, "tolerance_pct": 1.0, "voltage_max_v": 75.0 },
      "basic": true,
      "stock": "unknown"
    }
  ]
}

Kinds: ic, resistor, capacitor, inductor, diode, led, transistor, connector, crystal, fuse, switch, module, mechanical, other. Parameters: resistance_ohm, capacitance_f, inductance_h, voltage_max_v, power_max_w, current_max_a, saturation_current_a, dc_resistance_ohm, self_resonant_frequency_hz, tolerance_pct, tempco. A validation error lists every problem.

stock is a count or "unknown". atopile needs numbers, so the picker sends 0 for an unknown stock and a price of 0.0 when none is known; nothing treats a picker answer as evidence that a part can be ordered.

yapnr picker catalog import <splanc-catalog.json> -o catalog.json converts Splanc’s layout (lists of parts by type): resistance_ohms becomes params.resistance_ohm, the kind comes from the list (passives by the unit in the description), and nothing else is read out of the descriptions.

Bazel¶

The atopile environment is a toolchain, found by a repository rule with the same discovery as the runner (@yapnr_atopile, bazel/atopile/repo.bzl), and yapnr_atopile_build runs the runner as an action:

load("@yapnr//bazel/atopile:defs.bzl", "yapnr_atopile_build")

yapnr_atopile_build(
    name = "board",
    ato_yaml = "ato.yaml",
    srcs = glob(["elec/src/**", "elec/layout/**"]) + ["yapnr-parts.lock.json"],
    build = "default",
    cache = "https://parts.example.org",  # or --action_env=YAPNR_PART_CACHE=<dir or URL>
)

It produces board.kicad_pcb, board.bom.csv, board.result.json, the board.out/ directory and a YapnrAtopileBuildInfo provider. The action is local and no-remote (it uses an environment and a cache Bazel does not track) and not requires-network. It copies only the declared srcs (which must lie inside the project’s directory) into its work directory, so an undeclared file next to them (an untracked layout, say) can neither change the build nor make a cached result stale. The part cache is the cache attribute, else --action_env=YAPNR_PART_CACHE; there is no default inside Bazel (the strict action environment has no HOME), and a project with a parts lock and neither fails at once. Without an atopile environment only such targets fail, with the reason; after yapnr atopile setup, refetch with bazel fetch --force @yapnr_atopile//... (or change one of the discovery variables). //tests/fixtures/atopile:synthetic is a manual example.

Versions¶

• yapnr pins atopile 0.15.8, the version Splanc’s boards were built with.

• 0.15.9 comes in through an A/B on the synthetic fixture and Splanc’s builds, which must give equal netlists, variables reports and annotation resolution; a version change is a one-line requirements.in edit plus regenerated locks and a new pins.json.

• The frontend depends on stable outputs only (.ato text, atopile_address footprint fields, the JSON reports). The hook is written for 0.15.8 and fails loudly on anything else.

Tests¶

• bazel test //tests/unit/atopile/... //tests/unit/partcache/...: hermetic. Synthetic parts; the runner runs against a fake atopile interpreter (isolation, environment, outputs, input ids, a deadline kill of a process tree); the hook against fake atopile modules, including in spawn and forkserver workers.

• //tests/e2e/atopile:test_atopile_build (tags atopile, manual): real atopile 0.15.8 builds of a synthetic project, each twice with the same input id: without any pick, with one pick by LCSC id and with one type pick, both served by the picker from a temporary part cache. A project with a git dependency must fail offline without cloning it, and every build skips atopile’s reload of an open board in a running KiCad. Run it after yapnr atopile setup:

  bazel test //tests/e2e/atopile:all --test_env=YAPNR_ATOPILE_HOME="$HOME/.cache/yapnr/atopile"
  

From Splanc¶

Not done yet¶

• The /opt/atopile environment in the yapnr image (A4): the builder stage for the aarch64 wheel, the notices, the size measurement.

• An A/B of KiCad 9 against KiCad 10 on netlists and DRC. No end-to-end project references a stock Library:Footprint yet, so whether atopile 0.15.8 reads every KiCad 10 stock footprint is unchecked; the referenced-library scan reads .ato text only.

• yapnr parts add (the port of gen_parts_robust.sh, A6), catalog builders (A7) and the board macro (A8).