diff --git a/pep-0517.txt b/pep-0517.txt index a60bb399274..16240bb3865 100644 --- a/pep-0517.txt +++ b/pep-0517.txt @@ -378,15 +378,17 @@ Config settings config_settings -This argument, which is passed to all hooks, is an arbitrary -dictionary provided as an "escape hatch" for users to pass ad-hoc -configuration into individual package builds. Build backends MAY -assign any semantics they like to this dictionary. Build frontends -SHOULD provide some mechanism for users to specify arbitrary -string-key/string-value pairs to be placed in this dictionary. For -example, they might support some syntax like ``--package-config -CC=gcc``. Build frontends MAY also provide arbitrary other mechanisms -for users to place entries in this dictionary. For example, ``pip`` +This argument, which is passed to all hooks, is a dictionary that allows users +to pass additional configuration to backend. Build frontend SHOULD provide +user interface to specify string-key/string-value pairs to be placed in this +dictionary. For example, they might support CLI option like ``--package-config +CC=gcc``, which will be transformed into ``config_settings`` dict like this:: + + { + "CC": "gcc", + } + +Some frontends MAY also map legacy options into the dict. For example, ``pip`` might choose to map a mix of modern and legacy command line arguments like:: @@ -400,22 +402,13 @@ into a ``config_settings`` dictionary like:: { "CC": "gcc", - "--global-option": ["--some-global-option"], - "--build-option": ["--build-option1", "--build-option2"], + "global-option": "--some-global-option"], + "build-option": "--build-option1,--build-option2"], } -Of course, it's up to users to make sure that they pass options which -make sense for the particular build backend and package that they are -building. - -The hooks may be called with positional or keyword arguments, so backends -implementing them should be careful to make sure that their signatures match -both the order and the names of the arguments above. - All hooks are run with working directory set to the root of the source -tree, and MAY print arbitrary informational text on stdout and -stderr. They MUST NOT read from stdin, and the build frontend MAY -close stdin before invoking the hooks. +tree, and MAY print to stdout and stderr. They MUST NOT, however, read from +stdin, and the build frontend MAY close stdin before invoking the hooks. The build frontend may capture stdout and/or stderr from the backend. If the backend detects that an output stream is not a terminal/console (e.g.