-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Co-authored-by: Maurice Laveaux <m.laveaux@tue.nl>
- Loading branch information
Showing
30 changed files
with
2,624 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| name: Python | ||
|
|
||
| # spell-checker:ignore pyproject,pydata,jakebailey,CIBW | ||
|
|
||
| on: | ||
| push: | ||
| branches: [main] | ||
| paths: | ||
| - bindings/python/** | ||
| - pyproject.toml | ||
| - crates/** | ||
| - Cargo.* | ||
| pull_request: | ||
| branches: [main] | ||
| paths: | ||
| - bindings/python/** | ||
| - pyproject.toml | ||
| - crates/** | ||
| - Cargo.* | ||
|
|
||
| env: | ||
| CARGO_TERM_COLOR: always | ||
|
|
||
| jobs: | ||
| lint-test-doc: | ||
| name: Lint, Test & Doc | ||
|
|
||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: 3.x | ||
| - name: Install tools & dependencies | ||
| run: python -m pip install --upgrade pip ruff sphinx pydata-sphinx-theme cibuildwheel pytest | ||
| - name: Build | ||
| run: python -m pip install . | ||
| - name: Ruff check | ||
| run: ruff check --output-format=github | ||
| - name: Ruff format check | ||
| run: ruff format --check | ||
| - uses: jakebailey/pyright-action@v2 | ||
| - name: Test | ||
| run: pytest | ||
| - name: Sphinx | ||
| run: sphinx-build -W bindings/python/doc build/python-doc | ||
|
|
||
| linux-buildwheel: | ||
| name: Build wheels for Linux | ||
|
|
||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - uses: docker/setup-qemu-action@v3 | ||
| with: | ||
| platforms: arm64,s390x,ppc64le | ||
| - name: Install cibuildwheel | ||
| run: python3 -m pip install cibuildwheel | ||
| - name: Build (linux-buildwheel.py) | ||
| run: python3 bindings/python/build/linux-buildwheel.py --install-targets --archs all | ||
| - uses: actions/upload-artifact@v4 | ||
| with: | ||
| name: python-wheels-linux | ||
| path: wheelhouse/*.whl | ||
|
|
||
| mac-buildwheel: | ||
| name: Build wheels for macOS | ||
|
|
||
| runs-on: ${{ matrix.os.image }} | ||
| strategy: | ||
| matrix: | ||
| os: | ||
| - { arch: x86_64, image: macos-13 } | ||
| - { arch: arm64, image: macos-14 } | ||
|
|
||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - name: Install cbindgen | ||
| run: brew install cbindgen | ||
| - name: Build wheels | ||
| uses: pypa/cibuildwheel@v2.17.0 | ||
| env: | ||
| CIBW_ARCHS_MACOS: native | ||
|
|
||
| - uses: actions/upload-artifact@v4 | ||
| with: | ||
| name: python-wheels-mac-${{ matrix.os.arch }} | ||
| path: ./wheelhouse/*.whl | ||
|
|
||
| win-buildwheel: | ||
| name: Build wheels for Windows | ||
|
|
||
| runs-on: windows-latest | ||
|
|
||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - name: Install Rust targets | ||
| run: rustup target add aarch64-pc-windows-msvc | ||
| - name: Build wheels | ||
| uses: pypa/cibuildwheel@v2.17.0 | ||
| env: | ||
| CIBW_ARCHS_WINDOWS: all | ||
| CIBW_TEST_SKIP: "*-win_arm64" | ||
|
|
||
| - uses: actions/upload-artifact@v4 | ||
| with: | ||
| name: python-wheels-win | ||
| path: ./wheelhouse/*.whl |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| # Developing the Python Bindings | ||
|
|
||
| To start developing, create a virtual environment (`python -m venv .venv`) and run: | ||
|
|
||
| just devtools-py | ||
|
|
||
| This will install a few development tools and run `pip install --editable .`. The latter makes all your edits in Python files available in the virtual environment without the need to run any install commands again. Behind the scenes, the `pip install` command builds the `oxidd-ffi` crate in release mode, generates `target/include/oxidd.h` using `cbindgen`, and compiles a Python extension module called `_oxidd` via CFFI. This also means that if you change the Rust code, you need to run `pip install --editable .` again. | ||
|
|
||
|
|
||
| ## Common Actions | ||
|
|
||
| Most actions can be run using `just` (a tool similar to `make`, available on `crates.io` and via the respective package manager on most systems): | ||
|
|
||
| - `just fmt-py`: Run `ruff` as formatter | ||
| - `just lint-py`: Run `ruff` as linter and `pyright` as static type checker | ||
| - `just doc-py`: Build documentation using Sphinx. The output is placed in `target/python/doc`. | ||
| - `just test-py`: Run `pytest` and report test coverage to `target/python/coverage`. | ||
|
|
||
|
|
||
| ## Build Process Internals | ||
|
|
||
| We currently use `setuptools` for the build process. Therefore, the entrypoint is `setup.py` in the project root. `setuptools` is in the progress of migrating away from `setup.py`, so most settings are already taken from `pyproject.toml`. The remaining settings in `setup.py` cannot yet be specified in `pyproject.toml`. `setup.py` mainly registers a CFFI module with `bindings/python/build/ffi.py` as the build script. The latter invokes `cargo`, `cbindgen`, and compilation via CFFI. | ||
|
|
||
| There are different ways to link the OxiDD library and the Python extension module together. To control this, there is the `OXIDD_PYFFI_LINK_MODE` environment variable, which can be: | ||
| - `static`: Statically link against `liboxidd_ffi.a` or `oxidd_ffi.lib` in the `target/<profile>` directory. | ||
|
|
||
| This is the mode we will be using for shipping via PyPI since we do not need to mess around with the RPath (which does not exist on Windows anyway). It is also the default mode on Windows. | ||
| - `shared-system`: Dynamically link against a system-installed `liboxidd.so`, `liboxidd.dylib`, or `oxidd.dll`, respectively. | ||
|
|
||
| This mode is useful for packaging in, e.g., Linux distributions. With this mode, we do not need to ship the main OxiDD library in both packages, `liboxidd` and `python3-oxidd`. We can furthermore decouple updates of the two packages. | ||
| - `shared-dev`: Dynamically link against `liboxidd_ffi.so`, `liboxidd_ffi.dylib`, or `oxidd_ffi.dll` in the `target/<profile>` directory. | ||
|
|
||
| This mode is the default for developing on Unix systems. When tuning heuristics for instance, a simple `cargo build --release` suffices, no `pip install --editable .` is required before re-running the Python script. On Windows, setting this mode up requires extra work, since there is no RPath like on Unix systems. | ||
|
|
||
| Building Python wheels is possible using [`cibuildwheel`](https://cibuildwheel.pypa.io/en/stable/). To build for Linux, we use a wrapper script (`./build/linux-buildwheel.py`) around `cibuildwheel` to avoid installing a Rust toolchain in the containers. It will both cross-compile the `oxidd-ffi` crate for all the specified target architectures and run `cbindgen` on the host system. Only compiling the Python module and packaging is left to the `cibuildwheel` containers. We pass the environment variable `OXIDD_PYFFI_CONTAINER_BUILD=1` to the build script to indicate that it should run neither `cargo build` nor `cbindgen` but look for `liboxidd_ffi.a` in the respective target subdirectory (e.g., `target/aarch64-unknown-linux-gnu/release`). `OXIDD_PYFFI_CONTAINER_BUILD=1` also implies `OXIDD_PYFFI_LINK_MODE=static`. Note that building for non-native architectures requires [emulation](https://cibuildwheel.pypa.io/en/stable/faq/#emulation). |
Empty file.
Oops, something went wrong.