config-settings support needs docs

[rgommers]

This is a follow-up issue for gh-167. The most important thing to add is docs. The invocations are verbose and argument quoting can be difficult, so we need a good number of one-liners as usage examples (there are some near the bottom of gh-167).

Also, it's possible that there's still an issue with functionality. --config-settings doesn't take multiple arguments at once, so if you'd want to pass multiple arguments to meson setup, it seems like there's no good way to do it. Something like:

python -m pip install . --no-build-isolation --config-settings='setup-args=-Dblas=blas' --config-settings='setup-args=-Dlapack=lapack'

seems to just use one of the two arguments. @tacaswell and I tried for a while, and didn't get it to work. It's possible we missed something.

[eli-schwartz]

Sounds like maybe the config-settings design is that the backend is responsible for taking a single setup-args=... and doing its own word splitting on the value to convert it from a command line string to a list of arguments?

(For comparison, meson setup -Dopt=val supports array-type values. We handle this as comma-separated values, or optionally also as meson setup -Dopt="['val1', 'val2']".)

[dnicolodi]

I haven't found this documented any better than here https://peps.python.org/pep-0517/#config-settings where is only very vaguely defined. But this works with build:

python3 -m build -w -n . -Csetup-args=-Doptimization=3 -Csetup-args=-Ddebug=true

thus I think the design is for the option to be repeated. But this brings the questions: why setup-args plural?

[dnicolodi]

https://github.com/mesonbuild/meson-python/issues/59#issuecomment-1327142388

[tacaswell]

I missed that this existed and created #235 which has error logs.