Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
174 lines (122 loc) · 4.82 KB

CONTRIBUTING.md

File metadata and controls

174 lines (122 loc) · 4.82 KB

RGB Lib Python bindings development

The goal of this project is to produce Python bindings for rgb-lib, which is included as a submodule. The bindings are created by the rgb-lib-uniffi project, which is located inside the rgb-lib submodule.

Build

In order to build the bindings package(s), clone the project (git clone https://github.com/RGB-Tools/rgb-lib-python --recurse-submodules), enter the project root (cd rgb-lib-python) and follow the next instructions.

Always make sure the submodules are up-to-date:

git submodule update --init --recursive

The builds of the native Rust library and of the python bindings are carried out in Docker, using cross.

Requirements

Local project

In order to build or install the project on the local machine, cross needs to be properly configured first. To do so, run:

poetry run python -c 'import build_packages; build_packages.setup_cross()'

The package can then be built with:

poetry build

or installed with:

poetry install

Packages

The project build system produces wheels (.whl files) for each supported platform, plus the source distrubution (sdist, .tar.gz files).

First, the development dependencies need to be installed:

poetry install --no-root --only=dev

Then, in order to build all the packages, run:

poetry run python build_packages.py

The package build script will restore the submodules to the committed revisions, then build the required docker images and use them to build the wheels for all supported platforms, then build the sdist. Once the build is complete, the generated files will be available in the dist/ directory. Finally, the script will cleanup the build artifacts and restore the submodules to the committed revisions.

Wheel tags

The build.py script contains the wheel tags associated to the supported platforms. See Python's platform compatibility tags for details. You can use sysconfig.get_platform() and platform.machine() to get the data for the running system.

Special care is necessary for macosx wheels, as there sysconfig.get_platform() returns what the Python interpreter was built for (e.g. the system python reports macosx-10.9-universal2, while homebrew python 3.12 might return macosx-14.0-arm64) and the operating system (e.g. version 15.1.1) version is not used in a numerical comparison. To have wheels successfully install it's important to tag them with the correct major version but use 0 as the minor version (e.g. macosx-12.0-arm64 will install on OSX 12.7 but macosx-12.3-arm64 won't).

Submodule update

Manual updates to submodules are overwritten during the build process, which resets all the submodules before and after the actual build process.

For this reason, in order to have changes in submodules take effect at build time, they need to have been committed.

The cross submodule (and its docker/cross-toolchains submodule) are set to the commits defined in the build_packages.py (CROSS_COMMIT and CROSS_TOOLCHAIN_COMMIT) by the build process.

Format

To format the code of the build scripts, from the project root run:

poetry run black *.py

Lint

To lint the code of the build scripts, from the project root run:

poetry run flake8 *.py
poetry run pylint *.py

Publish

Publishing to PyPI is handled with poetry (version 2.0 or later).

Make sure the dist/ directory only contains the expected packages (e.g. using poetry build produces a wheel that's not meant to be published). The best way do to this is to empty the dist/ directory and then build all the packages. To check what would be published use poetry publish --dry-run.

To configure the access token, which only needs to be done once, run:

poetry config pypi-token.pypi <token>

To publish a new release run:

poetry publish

Test PyPI

To use the test PyPI instance, the repository needs to be configured in poetry:

poetry config repositories.test-pypi https://test.pypi.org/legacy/

An access token then needs to also be set:

poetry config pypi-token.test-pypi <token>

Publishing needs to specify the registry:

poetry publish -r test-pypi

To install the package from test PyPI:

pip install --index-url https://test.pypi.org/simple/ rgb-lib