From 30a3410ad2186c365914e20a583b979dc3fb9c88 Mon Sep 17 00:00:00 2001 From: johnslavik Date: Wed, 22 Apr 2026 14:11:34 +0200 Subject: [PATCH 1/6] gh-1547: Recommend --config-cache for configure Add ``--config-cache`` to all relevant ``./configure`` invocations in the front page and setup-building guide, matching what the WASM commands already do. Add a brief explanation noting that ``config.cache`` should be deleted when switching compilers or significantly changing the build environment. --- getting-started/setup-building.rst | 21 +++++++++++++++------ index.rst | 4 ++-- 2 files changed, 17 insertions(+), 8 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 110d718e95..871ecc3d88 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -192,7 +192,12 @@ for development is to configure it and then compile it. Configuration is typically:: - $ ./configure --with-pydebug + $ ./configure --config-cache --with-pydebug + +The ``--config-cache`` (``-C``) option speeds up repeated ``configure`` runs +by caching results in a ``config.cache`` file. If you switch compilers or +significantly change your build environment, delete ``config.cache`` before +re-running ``configure``. More flags are available to ``configure``, but this is the minimum you should do to get a pydebug build of CPython. @@ -283,7 +288,7 @@ to learn more about these options. .. code:: console - $ ./configure --enable-optimizations --with-lto + $ ./configure --config-cache --enable-optimizations --with-lto .. _windows-compiling: @@ -864,7 +869,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-openssl="$(brew --prefix openssl@3)" .. tab:: Python 3.10 @@ -873,7 +879,8 @@ some of CPython's modules (for example, ``zlib``). $ CPPFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \ LDFLAGS="-L$(brew --prefix gdbm)/lib -L$(brew --prefix xz)/lib" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-openssl="$(brew --prefix openssl@3)" \ --with-tcltk-libs="$(pkg-config --libs tcl tk)" \ --with-tcltk-includes="$(pkg-config --cflags tcl tk)" \ @@ -895,7 +902,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-system-libmpdec .. tab:: Python 3.11-3.12 @@ -904,7 +912,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug + ./configure --config-cache \ + --with-pydebug And finally, run ``make``:: diff --git a/index.rst b/index.rst index 997f599327..75de6b405e 100644 --- a/index.rst +++ b/index.rst @@ -43,13 +43,13 @@ instructions please see the :ref:`setup guide `. .. code-block:: shell - ./configure --with-pydebug && make -j $(nproc) + ./configure --config-cache --with-pydebug && make -j $(nproc) .. tab:: macOS .. code-block:: shell - ./configure --with-pydebug && make -j8 + ./configure --config-cache --with-pydebug && make -j8 .. tab:: Windows From 05ad04c792bb506a68533788b0eb1aa02d4513c7 Mon Sep 17 00:00:00 2001 From: johnslavik Date: Wed, 22 Apr 2026 14:12:02 +0200 Subject: [PATCH 2/6] gh-1547: Also mention --cache-file=config.cache alias --- getting-started/setup-building.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 871ecc3d88..dd1cbef7ab 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -194,10 +194,10 @@ Configuration is typically:: $ ./configure --config-cache --with-pydebug -The ``--config-cache`` (``-C``) option speeds up repeated ``configure`` runs -by caching results in a ``config.cache`` file. If you switch compilers or -significantly change your build environment, delete ``config.cache`` before -re-running ``configure``. +The ``--config-cache`` (short: ``-C``, equivalent: ``--cache-file=config.cache``) +option speeds up repeated ``configure`` runs by caching results in a +``config.cache`` file. If you switch compilers or significantly change your +build environment, delete ``config.cache`` before re-running ``configure``. More flags are available to ``configure``, but this is the minimum you should do to get a pydebug build of CPython. From 69463e6ab9ee046c707f4f35ef02180bcdc06efc Mon Sep 17 00:00:00 2001 From: johnslavik Date: Wed, 22 Apr 2026 14:42:33 +0200 Subject: [PATCH 3/6] gh-1547: Remove --config-cache from platform-specific configure commands --- getting-started/setup-building.rst | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index dd1cbef7ab..992033c063 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -288,7 +288,7 @@ to learn more about these options. .. code:: console - $ ./configure --config-cache --enable-optimizations --with-lto + $ ./configure --enable-optimizations --with-lto .. _windows-compiling: @@ -869,8 +869,7 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ - ./configure --config-cache \ - --with-pydebug \ + ./configure --with-pydebug \ --with-openssl="$(brew --prefix openssl@3)" .. tab:: Python 3.10 @@ -879,8 +878,7 @@ some of CPython's modules (for example, ``zlib``). $ CPPFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \ LDFLAGS="-L$(brew --prefix gdbm)/lib -L$(brew --prefix xz)/lib" \ - ./configure --config-cache \ - --with-pydebug \ + ./configure --with-pydebug \ --with-openssl="$(brew --prefix openssl@3)" \ --with-tcltk-libs="$(pkg-config --libs tcl tk)" \ --with-tcltk-includes="$(pkg-config --cflags tcl tk)" \ @@ -902,8 +900,7 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --config-cache \ - --with-pydebug \ + ./configure --with-pydebug \ --with-system-libmpdec .. tab:: Python 3.11-3.12 @@ -912,8 +909,7 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --config-cache \ - --with-pydebug + ./configure --with-pydebug And finally, run ``make``:: From 7e8285f0c7d30b13d906c84917273b901cdf47d7 Mon Sep 17 00:00:00 2001 From: johnslavik Date: Wed, 22 Apr 2026 14:44:13 +0200 Subject: [PATCH 4/6] gh-1547: Restructure --config-cache as optional speedup tip --- getting-started/setup-building.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 992033c063..0bedce6e46 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -192,16 +192,20 @@ for development is to configure it and then compile it. Configuration is typically:: - $ ./configure --config-cache --with-pydebug - -The ``--config-cache`` (short: ``-C``, equivalent: ``--cache-file=config.cache``) -option speeds up repeated ``configure`` runs by caching results in a -``config.cache`` file. If you switch compilers or significantly change your -build environment, delete ``config.cache`` before re-running ``configure``. + $ ./configure --with-pydebug More flags are available to ``configure``, but this is the minimum you should do to get a pydebug build of CPython. +To speed up repeated ``configure`` runs, use ``--config-cache`` (short: ``-C``, +equivalent: ``--cache-file=config.cache``):: + + $ ./configure --config-cache --with-pydebug + +This caches results in a ``config.cache`` file. If you switch compilers or +significantly change your build environment, delete ``config.cache`` before +re-running ``configure``. + .. note:: You might need to run ``make clean`` before or after re-running ``configure`` in a particular build directory. From f9a2af1c0a532aaaee0f0c029590dc596d98f723 Mon Sep 17 00:00:00 2001 From: johnslavik Date: Wed, 22 Apr 2026 14:45:31 +0200 Subject: [PATCH 5/6] gh-1547: Use tip admonition for --config-cache --- getting-started/setup-building.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 0bedce6e46..a849ffc194 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -197,14 +197,15 @@ Configuration is typically:: More flags are available to ``configure``, but this is the minimum you should do to get a pydebug build of CPython. -To speed up repeated ``configure`` runs, use ``--config-cache`` (short: ``-C``, -equivalent: ``--cache-file=config.cache``):: +.. tip:: + To speed up repeated ``configure`` runs, use ``--config-cache`` (short: + ``-C``, equivalent: ``--cache-file=config.cache``):: - $ ./configure --config-cache --with-pydebug + $ ./configure --config-cache --with-pydebug -This caches results in a ``config.cache`` file. If you switch compilers or -significantly change your build environment, delete ``config.cache`` before -re-running ``configure``. + This caches results in a ``config.cache`` file. If you switch compilers or + significantly change your build environment, delete ``config.cache`` before + re-running ``configure``. .. note:: You might need to run ``make clean`` before or after re-running ``configure`` From 091f2fcd35c8d41b7f437bd09b7be98e08477041 Mon Sep 17 00:00:00 2001 From: johnslavik Date: Thu, 23 Apr 2026 01:43:45 +0200 Subject: [PATCH 6/6] gh-1547: Add --config-cache to macOS platform-specific configure commands --- getting-started/setup-building.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index a849ffc194..60c7cbb859 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -874,7 +874,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-openssl="$(brew --prefix openssl@3)" .. tab:: Python 3.10 @@ -883,7 +884,8 @@ some of CPython's modules (for example, ``zlib``). $ CPPFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \ LDFLAGS="-L$(brew --prefix gdbm)/lib -L$(brew --prefix xz)/lib" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-openssl="$(brew --prefix openssl@3)" \ --with-tcltk-libs="$(pkg-config --libs tcl tk)" \ --with-tcltk-includes="$(pkg-config --cflags tcl tk)" \ @@ -905,7 +907,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-system-libmpdec .. tab:: Python 3.11-3.12 @@ -914,7 +917,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug + ./configure --config-cache \ + --with-pydebug And finally, run ``make``::