gh-109054: Document configure variables

[vstinner]

• Issue: ARM Raspbian 3.x fails to build _testcapi extension: undefined symbol: __atomic_fetch_or_8 #109054

---

📚 Documentation preview 📚: https://cpython-previews--109224.org.readthedocs.build/

[vstinner]

I'm not sure if adding a new dedicated Variables section is the best home for all these variables.

I chose to use .. cmdoption:: NAME syntax to avoid name conflicts with compiler flags defined with .. envvar:: NAME such as: https://docs.python.org/dev/using/configure.html#compiler-flags

I used ./configure --help | grep '^\s\+[A-Z]\{2,\}' command to list all configure variables, see @erlend-aasland's comment: #109101 (comment)

Initially, I just wrote this PR to document LIBATOMIC :-)

[vstinner]

I reorganized the doc. I'm not sure between envvar and cmdoption. The current doc uses envvar.

cc @hugovk

[vstinner]

@erlend-aasland: it seems like the whole "3.3.4. Libraries Options" section is new in Python 3.11, all xxx_CFLAGS and xxx_LIBS, no?

[vstinner]

PROFILE_TASK was added in Python 3.8.

[erlend-aasland]

@erlend-aasland: it seems like the whole "3.3.4. Libraries Options" section is new in Python 3.11, all xxx_CFLAGS and xxx_LIBS, no?

Yes, it came with the setup.py migration we did.

[erlend-aasland]

How about Third-party dependencies or Options for third-party dependencies?

[vstinner]

Go for "Options for third-party dependencies".

[vstinner]

@erlend-aasland: I updated my PR, would you mind to review it again?

[erlend-aasland]

This is going away with #109344:

Suggested change

	.. cmdoption:: LIBATOMIC
	Linker flags when ``cpython/pyatomic.h`` header file is used.
	Default: ``LIBATOMIC='-latomic'`` if ``libatomic`` is needed, or
	``LIBATOMIC=''`` otherwise (also the default when Python is cross-compiled).
	.. versionadded:: 3.13

[vstinner]

I understand that you want me to remove this variable in the doc, so I removed it.

[vstinner]

Oh sorry for the noise, I tried a Git tool which messed up with my PR. I fixed my PR.

[vstinner]

PR rebased on the main branch.

[ezio-melotti]

I would keep the PR focused and handle capitalization issues in a separate PR.
New titles should follow the existing conventions, even if it doesn't match the preferred capitalization specified by the devguide. A follow-up PR can fix it.

[vstinner]

I would keep the PR focused and handle capitalization issues in a separate PR.

Hum, ok, I reverted these changes. I didn't expect that changing a few titles would be so controversial :-)

[vstinner]

@erlend-aasland@hugovk@ezio-melotti: I rebased my PR on the main branch, squashed commits, I reverted title casing change (don't use Titlecase Anymore). Please review the updated PR.

@ezio-melotti: I applied your sugsestions to use :samp:, thanks.

[hugovk]

Looks good, although I'll leave approval for someone who knows about these flags 👍

[AA-Turner]

Looks good Sphinx-wise. (But same caveat as Hugo wrt the flags)

A

[vstinner]

Thanks for the reviews. If someone has more remarks, feel free to propose a PR :-)

[erlend-aasland]

LGTM! Thanks for documenting these things.