[PATCH 1/1] configure: prefer python's sphinx module

Using an explicit entry path script for sphinx can lead to confusing results: If the python binary belongs to a virtual environment, our configure script may still select a sphinx script that belongs to the system distribution packages. It is likely best to use python itself (whichever one the user provides) to resolve the sphinx script. This has a few benefits: 1. It will always be Python 3. Script entry points like 'sphinx-build' might attempt to invoke python2 -- or indeed, any version of python that the user did not specify with --python. 2. When using a user installation of sphinx, it will naturally prefer that version. 3. When using a virtual environment, it will naturally prefer that version. 4. Removing explicit python script entry points gives us greater control within the QEMU build ecosystem; we can be confident we are respecting the user's --python configuration, if any. It's my hope that this will make it simpler to integrate some optional pipenv functionality into the build for adding regression testing to our python module -- by offloading more of the python environment configuration and testing directly to the python tooling ecosystem. This would, ideally, free us up to use more modern python packages not always offered in older system distributions. (For instance, we already violate this requirement with sphinx, which does not have the necessary versions in our oldest build platforms.) Signed-off-by: John Snow <jsnow(a)redhat.com&gt; --- docs/system/deprecated.rst | 19 +++++++++++++++++++ configure | 20 +++++++++----------- 2 files changed, 28 insertions(+), 11 deletions(-) diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst index 544ece0a45e..a762a8c8043 100644 --- a/docs/system/deprecated.rst +++ b/docs/system/deprecated.rst @@ -17,6 +17,25 @@ they were first deprecated in the 2.10.0 release. What follows is a list of all features currently marked as deprecated. +Configure script options +------------------------ + +``--sphinx-build=`` (since 5.1) +''''''''''''''''''''''''''''''' + +The ``--sphinx-build`` option to select a specific sphinx-build entry +point is replaced by configuring Python accordingly. QEMU will now +default to using ``$python -m sphinx`` to use Python's preferred version +of sphinx. + +Python will generally default to preferring user packages installed with +``pip install --user`` first, and system distribution packages +second. By specifying a custom Python binary or activating a virtual +environment, Python will alter its module search behavior. As a last +resort, the PYTHONPATH environment variable can be modified to specify +an explicit directory. + + System emulator command line arguments -------------------------------------- diff --git a/configure b/configure index b01b5e3bed0..e04b9d836ee 100755 --- a/configure +++ b/configure @@ -932,16 +932,6 @@ do fi done -sphinx_build= -for binary in sphinx-build-3 sphinx-build -do - if has "$binary" - then - sphinx_build=$(command -v "$binary") - break - fi -done - # Check for ancillary tools used in testing genisoimage= for binary in genisoimage mkisofs @@ -1014,7 +1004,9 @@ for opt do ;; --python=*) python="$optarg" ;; - --sphinx-build=*) sphinx_build="$optarg" + --sphinx-build=*) + sphinx_build="$optarg" + echo "--sphinx-build is deprecated. QEMU uses the specified python's sphinx module." ;; --gcov=*) gcov_tool="$optarg" ;; @@ -4996,6 +4988,12 @@ has_sphinx_build() { "$TMPDIR1/sphinx/out" >> config.log 2>&1 } +# While we support --sphinx-build, defer to that. +# Otherwise, use the module execution feature of Python. +if ! has $sphinx_build; then + sphinx_build="$python -m sphinx" +fi + # Check if tools are available to build documentation. if test "$docs" != "no" ; then if has_sphinx_build; then -- 2.21.3