Docs need better examples of how to use --config-setting

[jontwo]

It's not clear how to use --config-setting - there is only one vague example in the doc and even looking at the source code doesn't throw any light on it.

I did find a few clues in #202, so for example the equivalent command to

$ python setup.py bdist_wheel --build-number 999

is

$ python -m build --wheel -C="--build-option=--build-number" -C="--build-option=999"

As the comments in #202 say, this is unintuitive and is also pretty ugly. Ideally --config-setting could be made more user-friendly, but at least if there were examples like this in the doc it would be more helpful.

[eabase]

I'm trying to do the same:

# Going from deprecated: 
python setup.py build --compiler=mingw32

# To the promoted:
python -m build -n -w -C="--build-option=--compiler=mingw32"

not working

[jontwo]

I think you have to add the key and value as separate -C options, so

python -m build -n -w -C="--build-option=--compiler" -C="--build-option=mingw32"

[henryiii]

How you use -C really depends on the backend. Setuptools is really weird, in that it requires one option for each. An example for scikit-build-core would be:

python -m build -Clogging.level=info -Ccmake.define.SOME_CMAKE_VAR=foobar

[LIONEFAN]

Hi @jontwo . I have a question, if you use this command
$ python -m build --wheel -C="--build-option=--build-number" -C="--build-option=999"
how to receive the argument "build-number" in the setup.py?

[jontwo]

All I know is what I've written above - no idea what setup.py does with the value once you pass it in, sorry.

[jontwo]

Bumping this because the docs still do not make it clear how to use --config-option and the parser has changed with v1.0.0 so what I had previously managed to get working now gives an error.

So, with build<1, I was doing this:

python -m build --wheel --no-isolation -C="--build-option=--build-number" -C="--build-option=${GDAL_VERSION//\./}"

but now that gives the error:

usage: _in_process.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: _in_process.py --help [cmd1 cmd2 ...]
   or: _in_process.py --help-commands
   or: _in_process.py cmd --help

error: option --build-number not recognized

ERROR Backend subprocess exited when trying to invoke get_requires_for_build_wheel

Looking at the code - https://github.com/pypa/build/blob/main/src/build/__main__.py#L334 and https://github.com/pypa/build/blob/main/src/build/__main__.py#L362 - it seems the parser has changed so I need to somehow enter the config options differently. Please give me a clue how to do this, because I have tried the following and none of them work. Either there is an error or the wheel builds, but the name does not contain the build number, so the option was ignored.

python -m build --wheel -C="--build-number=364"
python -m build --wheel -C="--build-number" -C="364"
python -m build --wheel -C="--build-number 364"
python -m build --wheel -C--build-number -C364

For the record, python setup.py bdist_wheel --build-number 364 does exactly what I want. I need the build equivalent of this command.

[jontwo]

Interesting, I can get it to print out the help and --build-number is there.

$ python -m build --wheel -C="--build-option=--help"
* Creating venv isolated environment...
* Installing packages in isolated environment... (Cython, numpy, setuptools, wheel)
* Getting build dependencies for wheel...
Compiling farm/rasters/water_fill.pyx because it depends on /tmp/build-env-035upa01/lib/python3.10/site-packages/Cython/Includes/libc/string.pxd.
[1/1] Cythonizing farm/rasters/water_fill.pyx
Common commands: (see '--help-commands' for more)

  setup.py build      will build the package underneath 'build/'
  setup.py install    will install the package

Global options:
  --verbose (-v)  run verbosely (default)
  --quiet (-q)    run quietly (turns verbosity off)
  --dry-run (-n)  don't actually do anything
  --help (-h)     show detailed help message
  --no-user-cfg   ignore pydistutils.cfg in your home directory

Options for 'egg_info' command:
  --egg-base (-e)   directory containing .egg-info directories (default: top
                    of the source tree)
  --tag-date (-d)   Add date stamp (e.g. 20050528) to version number
  --tag-build (-b)  Specify explicit tag to add to version number
  --no-date (-D)    Don't include date stamp [default]

usage: _in_process.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: _in_process.py --help [cmd1 cmd2 ...]
   or: _in_process.py --help-commands
   or: _in_process.py cmd --help

* Installing packages in isolated environment... (wheel)
* Building wheel...
Common commands: (see '--help-commands' for more)

  setup.py build      will build the package underneath 'build/'
  setup.py install    will install the package

Global options:
  --verbose (-v)  run verbosely (default)
  --quiet (-q)    run quietly (turns verbosity off)
  --dry-run (-n)  don't actually do anything
  --help (-h)     show detailed help message
  --no-user-cfg   ignore pydistutils.cfg in your home directory

Options for 'bdist_wheel' command:
  --bdist-dir (-b)  temporary directory for creating the distribution
  --plat-name (-p)  platform name to embed in generated filenames (default:
                    linux_x86_64)
  --keep-temp (-k)  keep the pseudo-installation tree around after creating
                    the distribution archive
  --dist-dir (-d)   directory to put final built distributions in
  --skip-build      skip rebuilding everything (for testing/debugging)
  --relative        build the archive using relative paths (default: false)
  --owner (-u)      Owner name used when creating a tar file [default: current
                    user]
  --group (-g)      Group name used when creating a tar file [default: current
                    group]
  --universal       make a universal wheel (default: false)
  --compression     zipfile compression (one of: stored, deflated) (default:
                    'deflated')
  --python-tag      Python implementation compatibility tag (default: 'py3')
  --build-number    Build number for this particular version. As specified in
                    PEP-0427, this must start with a digit. [default: None]
  --py-limited-api  Python tag (cp32|cp33|cpNN) for abi3 wheel tag (default:
                    false)

[jontwo]

Got it - the answer was in #264. You have to specify which stage you are aiming the options at, in this case bdist_wheel.

python -m build --wheel -C="--build-option=bdist_wheel" -C="--build-option=--build-number" -C="--build-option=264"

[henryiii]

This is specific to setuptools, and something I think they are trying to improve. I'd be fine to have some backend-specific examples, though.