JITX

Design complex circuit boards by writing simple code and streamline your existing design process.

Development setup

This repo uses mise for toolchain management and task running, with Hatch handling env creation and the Python matrix under the hood. The test suite runs against Python 3.12, 3.13, and 3.14, so all three interpreters need to be available locally.

Prerequisites

Install mise: https://mise.jdx.dev/getting-started.html

Bootstrap

From the repo root:

mise trust           # accept this repo's mise.toml
mise install         # installs Python 3.12/3.13/3.14, pipx, and Hatch
mise run setup       # creates the default dev env at .hatch/envs/default

After mise install, open a new shell (or run eval "$(mise hook-env)") so newly installed tools land on your PATH.

Common tasks

Day-to-day commands are exposed as mise tasks:

mise run test              # full 3.12/3.13/3.14 matrix
mise run check             # ruff format check + lint + pyright
mise run check:fix         # ruff format + lint --fix + pyright
mise run dev:link-jitxcore # editable-install sibling ../py-jitxcore for local co-dev
mise tasks                 # full list

Drop to Hatch directly when you need finer control (hatch test, hatch test --cover, hatch -e types shell, etc.).

Hatch environments

All envs are declared in pyproject.toml under [tool.hatch.envs.*]. Hatch creates them on demand under .hatch/envs/.

Reserved env names (hatch-test, hatch-static-analysis) are what Hatch itself looks up when you call hatch test / hatch fmt. The others are arbitrary project envs.

Run hatch env show to see the full resolved env list with their dependencies, scripts, and matrix expansion. It's the quickest way to catch a silently-ignored typo in an env name ([tool.hatch.envs.hatch-tests] won't warn — it'll just never run).

Integration tests

The integration/ tree contains a real-launcher harness that drives the jitx-client binary against a tiny test project. It requires a sibling jitx-client checkout with a built build/bin/launcher.

mise run integration:setup   # verifies symlinks + materializes jitx.params
mise run integration:test    # spawns launcher, signs in if needed, runs pytest

The first run signs in to JITX with shared dev credentials from integration/tests/credentials.py and caches the license under integration/jitx_root/licenses/ (gitignored). Unit tests (mise run test) ignore integration/ and stay fast.

The CLI surface (python -m jitx ... plus the legacy direct entrypoints python -m jitx.run.dependencies and python -m jitx.vscode.config) is exercised by integration/tests/test_cli.py, which shells out to the in-tree CLI via the integration/tests/harness/cli.py helper. These cases don't need the launcher — they use --help, --dry, and tmp_path — so they run in a couple of seconds as part of mise run integration:test.

Command-line interface

Installing this package exposes a jitx console script. The same surface is also reachable via python -m jitx ... and, for the two subcommands whose logic lives in their own modules, via python -m jitx.run.dependencies and python -m jitx.vscode.config directly.

The legacy top-level jitx find, jitx build, and jitx build-all remain callable for back-compat (CI scripts, VS Code launch configs) but are hidden from --help; jitx design find / jitx design build (with --all) are the documented home.

Two global flags apply to every subcommand:

• --format {json,text} switches between machine-readable JSON output and the default human-readable tree format.
• --logging {DEBUG,INFO,WARNING,ERROR,CRITICAL} sets the root log level (default INFO).

Run jitx --help or jitx <command> --help for the full per-command flag list.