#3 manages git commits in a repo by generating a commit file. This file probably should not be generated for editable installs. It's inaccurate because the state of the code in an editable install is not static. A more minor issue is that the file itself is not technically editable; the only way it gets updates is by rerunning the build command, and there's no safe way to symlink the file at install time due to the nature of wheel building going through zip files.

Description

The table in the README listing configuration options is useful to see what's available at a glance. It's also a great way to get an idea of what types of concerns rapids-build-backend is meant to address.

But the table format is really limiting... putting more than a few words describing a given configuration option would reduce the visual usefulness of the table fast (since it would grow the how table vertically).

At some point, I think it'd be useful to write dedicated documentation with long-form descriptions covering the following for each configuration option:

• what are the valid values?
• when might you want to override the default?
• how do the options relate to each other?

Benefits of this work

Improves the likelihood that someone building with this backend could be productive on their own.

Acceptance Criteria

• long form docs exist for all the config options

Approach

I am thinking something like a docs/config.rst, with content similar to this:

commit-file
'''''''''''''''''''

``rapids-build-backend`` automatically records the current git commit for the source tree it's building from, and writes that to a text file bundled into the wheel.

By default, that will be in a file `{[project].name}/GIT_COMMIT`. For example, given a `pyproject.toml` like this:

[project]
name = "sparkly-unicorn"

rapids-build-backend will write out that commit sha to a location ``./sparkly_unicorn/GIT_COMMIT``, relative to wherever that ``pyproject.toml`` file is.

Provide some other relative path here to override that behavior and tell it to write to a custom location.

I think it'd be fine for that to just live in a file in this repo. This issue could be considered "done", in my opinion, without setting up any docs rendering or hosting.

Some good references for this:

• https://scikit-build-core.readthedocs.io/en/latest/configuration.html
• https://setuptools.pypa.io/en/latest/userguide/datafiles.html

Notes

N/A

While working through rapidsai/rmm#1502, I've found myself struggling to debug problems of the form "rapids-build-backend isn't doing what I want, but also isn't raising any warnings or errors".

It'd be helpful to be able to turn on debug-level logging and see exactly what the library is doing.

For example, I'd like to be able to use logs to inspect what's happening in here:

References

Some related conversations:

• pypa/pip#6634
• scikit-build/scikit-build-core#513