[docs] [issue35156] Consider revising documentation on Python Builds from source

[Jorge Ramos]

New submission from Jorge Ramos <neyuru at gmail.com>:

I want to build from source a 3.6 Python, using PGO for windows.

Followed instructions at https://devguide.python.org/setup/ (the original search from google was "build python from source windows"). From a newbie perspective there are several problems:

1) it is suggested that you should build first a "debug" python (header 1.3) but they don't tell you how.
2) it is suggested that you should first build via "PCBuild\build.bat" but they don't tell you that this builds a win32 platform. What if I want to build a x64 version? (lost much time here figuring out how)
3) I ran into problems when building with "PCBuild\build.bat" (header 1.3.2) because the dependencies where not all downloaded in the first pass (but this is a bug I could fill later). Lost much time here figuring why the build did not succeed.
4) in (1.3.2) it is suggested you keep reading in a readme file: https://github.com/python/cpython/blob/master/PCbuild/readme.txt This is the first time an optimization is mentioned (other than simply compiling from your machine. I did not know that using PGO was mandatory for real speedups compared to the downloadable “general” binaries).
5) In this very same readme, it says that there are other "subprojects" that you need to consider building with Python. Lost much time here trying to figure out that these subprojects are downloaded via "get_externals.bat" in the "Getting External Sources" section. Why not simply put the "Getting External Sources" section first and avoid worrying the newcomer of potential projects that are "not included with python"?
6) They tell you that PGO is automated via a "build_pgo.bat" file. But this does not exist. 
7) They tell you that first, you have to run the PGInstrument option in the build, but it is not clear what should be run next: PCBuild\build.bat -c PGUpdate -p x64" or "PCBuild\build.bat --pgo -p x64"
8) After 2 days of trying to build (and learn in the process by trial and error) I stumble upon YET ANOTHER WAY TO BUILD: the one found in "cpython\Tools\msi" NOT the first one: "cpython\PCbuild"

And this is the one I was interested in the first place: building an installable version of python (yet I have to figure out how to pack all cab files and such into one exe), not a developer’s python for testing. And after now 3 days with this, I noticed that all previous testing and building techniques are indeed reachable from "cpython\Tools\msi\buildrelease.bat -x64" which tries to build a python in x64 version AND using GPO (by default -in the x64 but not in the win32-, which is not mentioned in the documentation, by the way) also generating the dependencies required (I could have avoided losing some time if knowing this from the very beginning- see point 5)

As you can see, I lost few hours here, few there. And because I am not a developer (my intention is to have an optimized python for my PC for AI research) I lost much time trying to figure out things that are not explicitly said in the documentation: I managed to learn from other sources (googling around), by careful observation of the compilation results, and digging into the help section of each of the files used.
Hope I successfully communicated Python’s lack of proper documentation (just for the case of building from source!)

----------
assignee: docs at python
components: Documentation
messages: 329211
nosy: docs at python, neyuru
priority: normal
severity: normal
status: open
title: Consider revising documentation on Python Builds from source
type: enhancement
versions: Python 3.6

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue35156>
_______________________________________