Building and testing¶
Set-up¶
git clone https://github.com/AKJ7/CANExplorer.git
cd CANExplorer
uv sync # Runtime, dev, test and packaging dependencies in .venv
uv run canexplorer # Start the application
Dependencies are declared in pyproject.toml and locked in uv.lock. The dependency groups are dev (linters),
test, packaging (PyInstaller, Nuitka) and docs (MkDocs).
Docker¶
docker-compose.yml runs the project in a container with Python, the Qt libraries for headless tests and the
Linux CAN tools. The source is mounted; the virtual environment lives in a volume of its own.
docker compose run --rm test # The test suite
docker compose run --rm dev # A shell, e.g. for `uv sync && uv run pytest` or virtual CAN buses:
# sudo ip link add vcan0 type vcan && sudo ip link set vcan0 up
CAN_SERVER_TOKEN=secret docker compose up -d can-server # Share the host's can0, see Remote buses
The can-server service uses the host's network, so it sees the host's CAN interfaces and listens on port 8765;
CAN_SERVER_BUS (default vehicle=socketcan:can0:500000) and CAN_SERVER_PORT change the bus and the port, and
it does not start without CAN_SERVER_TOKEN. Set UID to your user id (id -u) when it is not 1000, so files
created in the source belong to you.
Tests¶
The tests run headless (Qt's offscreen platform) and use python-can's virtual interface, simulated ECUs and LIN
slaves, so no hardware is needed. They cover the core, the decoders and file formats, the scripting runtime, the Qt
models and controllers, and loading the QML user interface without warnings.
To test other Python versions without changing .venv:
Linting and formatting¶
CI fails on lint errors and on code that black would reformat.
Benchmark¶
Measures the receive pipeline (frames per second, with and without decoding) and the table models.
Documentation¶
The documentation is built with MkDocs and Material for MkDocs; the scripting API reference is generated from the docstrings with mkdocstrings.
uv run --group docs mkdocs serve # Live preview on http://127.0.0.1:8000
uv run --group docs mkdocs build --strict # Build into site/, failing on warnings such as broken links
The screenshots in docs/assets/screenshots are generated by driving the application with simulated buses: