Put 'Install dependencies' before 'Compile and build'

[erlend-aasland]

---

📚 Documentation preview 📚: https://cpython-devguide--1337.org.readthedocs.build/getting-started/setup-building/

[nedbat]

Originally I guess this was later because many people don't need those extra modules. Perhaps we could add a statement here like, "these dependencies are needed to build the complete standard library, but many people don't need those modules so it might be fine to skip this section." (but worded better).

[erlend-aasland]

Yeah, I agree, but I would prefer to do that in a follow-up PR.

[ezio-melotti]

I think it might even be better to just leave it afterward, but possibly add a note here with a short explanation and link to it.

IME, unless you are working on some specific module that require some of those extensions, you can just ignore this whole section.

Also the section currently explains how to install dependencies, but doesn't cover why/when you might want to do that.

[ezio-melotti]

(On a slightly unrelated note, that page seems a bit daunting, especially when -- at least on Linux -- you generally just need 3 commands: git clone, ./configure, and make. Maybe we should add a quick start at the top that just lists these commands and links to the various other sections for more details.)

[erlend-aasland]

From time to time we get "bug reports" from people who complain about extension modules that fail to build because of missing dependencies. This also happen on the Help forum on Discourse. We might get fewer reports like that with this change.

I do like the suggestion about adding a "tl;dr" where we spell out the clone-configure-make recipe on the top of the page.

[ezio-melotti]

From time to time we get "bug reports" from people who complain about extension modules that fail to build because of missing dependencies.

I remember having this discussion already a while ago, and IIRC the wording was changed to clarify that they are not blocking failures (or maybe it was just proposed and never implemented?).

Edit: this is the current message:
https://github.com/python/cpython/blob/4fc82b6d3b99f873179937215833e7a573ca7876/Tools/build/check_extension_modules.py#L221-L225

[erlend-aasland]

Examples of fairly recent bug reports bco. missing dependencies:

• Python3.12 BUG: ModuleNotFoundError: No module named '_bz2' cpython#116224
• Build failure of v3.12.0rc1 due to missing _gdbm on macOS cpython#108856
• Cannot build 3.11.4 on Raspberry pi cpython#105706

[ezio-melotti]

Thanks for the examples! ISTM that:

• Some users don't need the extra deps, and would benefit from a simpler process (i.e. cover configure/make first, and the installation of extra deps later). This group should include most contributors, which are the target audience for the devguide;
• Some users need the extra deps, and for them having the section about installing them first would be better. This group includes people that are manually installing Python to use it, and want all the extra bits.

Regardless of their intentions:

• IMHO adding a note at the beginning of the "Compile and build" section that links to the "Installing dependencies" section (with a short explanation about when/why you might want to do that) instead of moving the "Installing dependencies" at the top is a good enough compromise;
• The warning message about missing dependencies could be clarified further, and could possibly include a link to the devguide;
• The whole "setup and building" page could be streamlined a bit more with a simple list of steps that link to the various sections;

[hugovk]

Also update "below" -> "above" in "Compile and build":

-If you want to install these optional dependencies, consult the Install dependencies section below.
+If you want to install these optional dependencies, consult the Install dependencies section above.

[erlend-aasland]

Also update "below" -> "above" in "Compile and build":

Thanks; addressed in f23f169.

[erlend-aasland]

I opened an issue for this change; let's discuss how we want to solve this before continuing with a PR.