scons517 0.0.1.post2

Pep 517 compliant Python Distribution Wheel Builder

Scons517

Project Status

This project is unmaintained. It is the result of exploring some ideas for an interface to SCons for building Python wheel distributions.

If you're interested in using SCons to build Python Wheels, see enscons.

If you're interested in picking up this project or in using this name for a different project, contact me.

About

Pep 517 compliant Python Distribution Wheel Builder

This project's primary goal is to provide a simple and extensible set of tools for building Python wheels without using setuptools. Setuptools has served the Python community well, but I've often been frustrated when trying to extend it in uncommon ways.

For example, extending setuptools to also run build steps such as building a webpack bundle or running Django's collectstatic routine are non-trivial to add.

This led me to the enscons project which provides a set of wheel building tools on top of the Scons build framework. Enscons works well (and you should use it if you want a more stable and mature project) but for compiling C extension modules, it still calls into setuptools under the hood.

So this project started out as an experiment to see if I could eliminate setuptools entirely and still provide C-extension support and the full power of Scons. I also started to re-imagine the interface to make things (in my opinion) a bit more straightforward.

Using Scons517

Enough history. How do you use it?

There are two files you need in the root of your project directory:

pyproject.toml

This should contain at a minimum a [build-system] section declaring Scons517 as the build backend, and a [project] section with at a minimum a name and a version key.

For example:

[build-system]
build-backend = "scons517.api"
requires = [
    "scons517",
]

[project]
name = "example-project"
version = "0.0.1"
dependencies = [
    "dep1",
    "dep2",
]
readme = "README.md"

The formal list of keys allowed in the [project] table are defined by the PyPA specification page on Declaring project metadata

sconstruct.py

This file defines your build targets and how to build them. Here's the minimal boilerplate for a pure-python distribution with no platform-specific dependencies:

import scons517

env = Environment(tools=["default", scons517.tool])
tag = scons517.get_pure_tag()
sources = ["add_your_source_files_here.py"]

wheel = env.Wheel(tag=tag)
wheel.add_sources(sources)

sdist = env.SDist(["pyproject.toml", "sconstruct.py"] + sources)

editable = env.Editable(tag, ".")

env.Alias("wheel", wheel.target)
env.Alias("sdist", sdist)
env.Alias("editable", editable)

The sconstruct file must define the two target aliases wheel, sdist. An editable target enables editable installs (pip install -e)

For examples compiling extension modules and cython modules, see the tests/examples/ directory.

Building a project

Once you have those two files in place, build your wheel using a compatible build frontend such as build

Install it with

pip install build

Then build your wheel with

python -m build

Your wheel files will be placed in the dist/ directory by default.