From 286ed531e5076473bc54e5852394196f80d0a0af Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Tue, 27 Feb 2024 17:51:06 +0300 Subject: [PATCH] Document default build configuration --- plugins/python-build/README.md | 37 ++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/plugins/python-build/README.md b/plugins/python-build/README.md index 7b0601cd..1f074fb8 100644 --- a/plugins/python-build/README.md +++ b/plugins/python-build/README.md @@ -98,6 +98,43 @@ custom definition files. [definitions]: https://github.com/pyenv/pyenv/tree/master/plugins/python-build/share/python-build +### Default build configuration + +Without the user customizing the build with environment variables (see below), +`python-build` builds Python with mostly default Configure options +to maintain the principle of the least surprise. + +The exceptions -- non-default options that are set by default -- are listed below: + +| Option/Behavior | Rationale | +------------------------------- +| `--enable-shared` is on by default. Pass `--disable-shared` to Configure options to override | The official CPython Docker image uses it. It's required to embed CPython. | +| argument to `--enable-universalsdk` is ignored and set to `/` | +| `--with-universal-archs` defaults to `universal2` on ARM64 architecture | the only dual-architecture Macs in use today are Apple Silicon which can only build that one | +| argument to `--enable-framework` is ignored and set to a specific value | CPython's build logic requires a very specific argument to avoid installing the `Applications` part globally | +| argument to `--enable-unicode` in non-MacOS is overridden to `ucs4` for 2.x-3.3 | +| `MACOSX_DEPLOYMENT_TARGET` defaults to the running MacOS version | + + +#### Integration with 3rd-party package ecosystems + +##### Homebrew + +Homebrew is used to find dependency packages if `brew` is found on `PATH`: +* In MacOS, or +* If the running Pyenv itself is installed with Homebrew + +Set `PYTHON_BUILD_USE_HOMEBREW` or `PYTHON_BUILD_SKIP_HOMEBREW` to override this default. + +When Homebrew is used, its `include` and `lib` paths are added to compiler search path (the latter is also set as `rpath`), +and also Python dependencies that are typically keg-only are searched for in the Homebrew installation and added individually. + +##### Portage + +In FreeBSD, if `pkg` is on PATH, Ports are searched for some dependencies that Configure is known to not search for via `pkg-config`. +(Later versions of CPython search for more packages via `pkg-config` so this may eventually become redundant.) + + ### Special environment variables You can set certain environment variables to control the build process.