Development¶
This page is for working on bust itself. Report bugs and ideas as GitHub issues.
Set up¶
git clone https://github.com/logvik-org/bust.git
cd bust
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,docs]"
pre-commit install
bust runs on Python 3.9 to 3.14. mypy checks against 3.9.
Checks¶
Command |
What it does |
|---|---|
|
Run the test suite |
|
Type-check the package |
|
Run black and the whitespace, tab and line-ending checks |
|
Build this site, failing on any warning |
CI runs mypy and the tests on Python 3.9 to 3.14 (plus the next Python while it is in pre-release), builds the docs, builds the package and smoke-tests the wheel, runs the pre-commit hooks and simulates the generated VHDL. A pull request needs all of it green.
Golden files¶
Most tests regenerate the outputs of the examples in example/ and compare
them byte for byte with the committed files in example/<name>/. A change to
a template or generator that changes the output fails these tests until the
committed files are updated. To rewrite them from the current generator:
BUST_UPDATE_GOLDENS=1 pytest tests/test_suite.py
git diff example/
Review the diff before you commit it. It is the clearest record of what your change does to the generated code.
Simulation¶
sim/ simulates the generated example testbenches, and the hand-written
reference testbenches in hdl/prototype/, with the open-source nvc simulator
in Docker. You need Docker, but no local VHDL tools:
cd sim
make build # build the nvc + UVVM image once
make sim-axi # simulate the AXI4-Lite example
make help # list every target
sim/README.md describes the image and how to add a target. CI runs the
simulations when files under sim/, hdl/ or the generated example VHDL
change, and for every release.
Documentation¶
This site is built with Sphinx from the Markdown pages in docs/ and published
on Read the Docs, which rebuilds it for every push to master and every
release tag. The configuration is in .readthedocs.yaml and docs/conf.py.
The logo, the sidebar wordmark, the favicon and the GitHub social preview in
docs/images/ are drawn by scripts/make_logo.py. To change them, edit the
script and run it from the repository root. The PNG files need
pip install cairosvg. GitHub does not read the social preview from the
repository, so upload docs/images/social-preview.png again under Settings,
General, Social preview after a change.
Changelog¶
CHANGELOG.md follows Keep a Changelog.
Add user-facing changes under ## [Unreleased].
Releasing¶
The version is set in one place, __VERSION__ in bust/_version.py.
Versions follow PEP 440: 1.2.0a1,
1.2.0b1 and 1.2.0rc1 are pre-releases, and 1.2.0 is a final release.
On the branch you release from (
masterfor a final release), move theUnreleasedentries inCHANGELOG.mdunder a new## [<version>] - <date>heading, update the compare links at the bottom, set__VERSION__, and push.Publish a GitHub Release on that commit with the tag
v<version>, for examplev1.2.0. The tag must bevfollowed by exactly__VERSION__. For a pre-release, tick “Set as a pre-release”. pip installs pre-releases only when asked (pip install --pre bust).
Publishing the release starts .github/workflows/release.yml. It stops at the
first failing step:
The test and simulation workflows.
Build the sdist and wheel, after checking the tag against
__VERSION__.Upload them to TestPyPI.
Download the wheel from TestPyPI, check that it is the one step 2 built, install it and run
scripts/smoke-test.sh.Upload the same files to PyPI.
If a step fails for a reason outside the code, re-run the failed jobs. TestPyPI skips files it already has. If the code needs a fix and the release stopped before the TestPyPI upload, delete the release and its tag, fix the code and publish again. Once a version is on TestPyPI, a fix needs a new version, because neither index accepts the same file twice.
Uploads use PyPI Trusted Publishing through the testpypi and pypi GitHub
environments, so no tokens are stored in the repository.