jitx 4.2.1

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

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/.

Env	Purpose	Typical invocation
default	Interactive dev shell with the project installed editable.	hatch shell, hatch run python -m jitx ...
hatch-test	Unit-test runner; pytest + coverage pre-wired. Runs across the 3.12 / 3.13 / 3.14 matrix ([[tool.hatch.envs.test.matrix]]).	hatch test, hatch test --all, hatch test --cover — wrapped by mise run test.
hatch-static-analysis	Ruff-only env used by hatch fmt. Pinned to ruff==0.14.9.	hatch fmt, hatch fmt --check — wrapped by mise run check / check:fix.
types	Pyright + sphinx for type checking. Exposes the check and stats scripts.	hatch run types:check, hatch run types:stats.
integration	Opt-in slow tests under integration/tests/. Only pytest on top of the default deps — uses a single Python, not the matrix.	hatch -e integration run test — wrapped by mise run integration:test.

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.

Command	What it does
jitx find [PATH...]	Walks the given paths (or the current directory) and lists every discoverable Design subclass.
jitx build DESIGN...	Builds one or more designs identified by dotted name (pkg.module.DesignClass) or .py file path. Connects to a running JITX launcher over websocket; pass --uri, --port, --socket, or --host to point at it, or --dry to skip the connection and just exercise instantiation + translation. --no-dependency-check skips the up-front PyPI cooldown check.
jitx build-all	Discovers every design in the current directory and builds them all. Same connection flags as build; --generate-config additionally writes .vscode/launch.json and tasks.json for the resulting design list.
jitx project dependencies <subcmd>	Checks or upgrades declared Python dependencies against PyPI. check (the default when no subcommand is given) reports updates available within the declared constraints and is rate-limited via a .venv_sync_last cooldown file in cwd. upgrade applies those updates. Both surface packages where a newer release exists outside the declared constraint. Shared flags: --allow-prereleases (alias --pre) to consider pre-releases, --check-include-group NAME to include an optional-dependency group; upgrade also takes --editable-install to reinstall the current project in editable mode afterward.
jitx project layout <subcmd>	Manages the on-disk shape of a JITX project. Subcommands: init scaffolds a new project (writes pyproject.toml, .gitignore, .vscode/{launch,tasks,settings}.json, and a Python package containing __init__.py + a sample main.py); pyproject, gitignore, settings, and vscode each (re)write a single slice. All commands take an optional PATH (default cwd), and most accept --force to overwrite existing files instead of skipping or smart-merging. Run jitx project layout --help for the full subcommand list.

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.