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.

TOC