[FR] Design and document a stable mechanism to pass `config_settings` to PEP517 backend

[mgorny]

Summary

The parameters accepted by the PEP517 build backend don't seem to be documented anywhere. Both --build-option and --global-option are only mentioned in CHANGES.rst, and build_meta.py code is so convoluted it's hard to figure out how they're supposed to be used correctly.

OS / Environment

No response

Additional Information

It would help people use config_settings correctly when building via PEP517 backend, and avoid surprises when incorrect uses stop working.

Code of Conduct

• I agree to follow the PSF Code of Conduct

[alex]

As a concrete example of something that I'd benefit from being documented: I was trying to figure out how to pass py-limited-api via --config-settings, and was struggling with the lack of docs on this.

[mgorny]

I'd use a way to pass options to build_ext and build_rust commands but I don't think that's possible at all right now.

[alex]

That's what the legacy pip wheel --build-options="..." did, however it's a no-op with PEP517 packages (see pypa/pip#6304), and config_settings are supposed to be the right way to do this now.

As you note, since they're not well documented it's a bit hard to piece together how to use them.

[abravalheri]

Hello guys, thank you very much for the issue and ping on this topic.

I am afraid that what you guys want to achieve right now is not exactly implemented yet.

I believe people can right now use something like:

python -m build -C--build-option="..."

However, by default the same config_settings will be passed to both wheel and sdist so it is very likely an error will be raised¹.

I have been thinking about this for a while and it is a tricky subject to address...
I think the most likely way forward would be converting the config_settings into a setup.cfg style file in build time and adding it to the list of config files. But that needs some work².

Footnotes

1. Unless the user specifically calls python -m build --sdist or python -m build --wheel, the options would need to be common for both bdist_wheel and sdist. ↩

2. I also happens that setuptools processes config files before sys.argv, so it is not a trivial implementation. ↩

[alex]

Thanks for the context, after staring (deeply) at various outputs, it seems that passing --config-settings=--build-option=--py-limited-api=cp37 doesn't work because the --py-limited-api=cp37 component is passed to get_requires_for_build_wheel, which doesn't accept it. I'm honestly very unsure if this is a bug.

[abravalheri]

It might as well be, I honestly don't know.
Since the initial implementation of the PEP 517 backend the same options config_settings are shared when calling get_requires*, build_sdist and build_wheel¹. I was not involved in this implementation so I don't know exactly what is the reasoning behind this logic.

My opinion is that config_settings needs some work. I am not sure if it is stable enough to be documented for end user consumption. Probably the best the users can do right now is to add/modify the setup.cfg files and add a [bdist_wheel] section there with the relevant configurations.

Footnotes

1. There was some discussion pointing out that --global-option and --build-option were not compatible with the legacy pip counterparts so I changed the names, however the behaviour of sharing the contents config_settings among the different hooks is more or less preserved. ↩

[leofang]

I think #2491 is related.

[beckermr]

I think once this removal (pypa/pip#11859) goes through, there won't be a way to pass options through. Certainly syntax like -C--global-option="" does not work currently.

[beckermr]

bump @abravalheri - The pip folks don't have any idea about this and so I think there is some urgency to make sure setuptools works with --config-settings.

[beckermr]

Agree with @leofang that #2491 is related.