Codebase¶
The parts of the codebase which are not described elsewhere: the Cli and the Compiler running the targets. The IR is described in Entities, and the targets in Targets.
Toolbox¶
The toolbox and the Makefile require that make is available. See the
utilities they provide by running:
make help
make help prints:
make[1]: Entering directory '/yace'
Usage:
make help ; Brief target description
make help-verbose ; Verbose target descriptions
make [target] ; Invoke the given 'target'
Targets:
all ; Do all: uninstall clean deps build install test
build ; Build the package (sdist and wheel)
bump ; bump the patch version in src/yace/__init__.py
clean ; clean build artifacts (build, dist, output)
default ; invoke: 'make uninstall', 'make install'
deps ; Tools for building yace and uploading it to PyPI
devenv ; build the development environment, the image CI runs in, from toolbox/devenv
devenv-pull ; pull the development environment of this tree from the registry
devenv-push ; push the development environment to the registry
devenv-run ; run CMD in the development environment, as devenv-shell would, e.g. CMD="make test"
devenv-shell ; a shell in the development environment, as your own user, the repository at /yace
docs ; generate documentation (command-output, section-gen, HTML) and open the HTML
docs-build ; generate documentation
docs-build-prep ; Install docs tooling and dependencies
docs-gen-entities ; Generate documentation of IR entities
docs-kmdo ; Generate command output using kmdo
docs-view ; open the HTML version documentation
example ; Parse the example library's header, failing on any diagnostic, then generate and check every target
format ; run code format (style, code-conventions and language-integrity) on staged changes
format-all ; run code format (style, code-conventions and language-integrity) on all files
help ; Print the description of every target
install ; install the wheel from 'make build' using pipx, with what 'make test' needs
install-source ; install the source tree, editable, using pipx along with the dev tools
survey ; Run yace parser survey across ~90 popular C libraries
test ; run pytest, from the pipx environment of yace, with coverage
uninstall ; uninstall via pipx
make[1]: Leaving directory '/yace'
Development environment¶
The development environment is a container image, built from
toolbox/devenv/Containerfile: Ubuntu with every toolchain a target checks
its bindings with, at pinned versions. That includes the Rust of the
rust-version the generated Cargo.toml declares, which the tests build
the fixture’s Rust checks with. The tag of the image is a digest of what it is
built from, and the image is published as ghcr.io/safl/yace-devenv. The
following command starts a shell in it, as your own user, with the repository
at /yace:
make devenv-shell
The following command runs a command in it, as CI runs those of its Linux jobs that need the toolchains:
make devenv-run CMD="make deps build install test PYTHON=python3.13"
As for any make variable, a $ in CMD is written $$.
With make devenv-pull you get the image of the tree you have checked out,
and after changing toolbox/devenv you build it with make devenv. Podman
is used when installed, Docker otherwise; set CONTAINER to choose.
CI pushes the image when the registry has none of its tag. A package that CI
creates is private, so a maintainer makes it public once, for make
devenv-pull to work without logging in. A pull request from a fork cannot
push, so one changing toolbox/devenv fails until the change is pushed from
the repository itself.
The macOS jobs of CI cannot run containers. They use the toolchains of the runner, with Python, Zig and Go installed by their actions.
main requires one check of a pull request, ci-result. That job of the
verify_and_publish workflow fails unless every other job of the workflow
succeeded. A change of only docs/ and Markdown files skips the jobs that
build and test, and the docs workflow builds it.
The tests build the module and the .pxd of the Cython target with Cython,
and check the stub with mypy. The tests of the Cython check and of the Cython
benchmark of examples/libfoo build with pip and meson-python. make
install installs Cython, meson-python, meson, ninja and mypy into the
environment of yace at the versions the Makefile pins, so the Linux
and macOS jobs both have them. The tests put the scripts of that environment
first on the PATH, where meson finds meson, ninja and cython.