From e867242cf619900f07ccc450389c247438e9d4e6 Mon Sep 17 00:00:00 2001
From: Alexandre Duret-Lutz <adl@lrde.epita.fr>
Date: Tue, 4 Oct 2022 11:15:07 +0200
Subject: [PATCH] Update troubleshouting instruction for Python bindings

For issue #512

* README: Update instructions.
* configure.ac: Add some code to warn if Python files will be
installed in a place that is not searched up by default.  Add
--with-pythondir support.
* NEWS: Mention --with-pythondir.
---
 NEWS         |  5 +++++
 README       | 40 +++++++++++++++++++++++++++-------------
 configure.ac | 25 +++++++++++++++++++++++++
 3 files changed, 57 insertions(+), 13 deletions(-)

diff --git a/NEWS b/NEWS
index 262414d67..88c689bfc 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,11 @@ New in spot 2.10.6.dev  (not yet released)
 
   Build:
 
+  - configure will now diagnose situation where Python bindings will
+    be installed in a directory that is not part of Python's search
+    path.  A new configure option --with-pythondir can be used to
+    modify this installation path.
+
   - A new configure option --enable-pthread enable the compilation of
     Spot with -pthread, and activate the parallel version of some
     algorithms.  If Spot is compiled with -pthread enabled, any user
diff --git a/README b/README
index a0b7c9579..458da2d99 100644
--- a/README
+++ b/README
@@ -110,16 +110,16 @@ Spot follows the traditional `./configure && make && make check &&
 make install' process.  People unfamiliar with the GNU Build System
 should read the file INSTALL for generic instructions.
 
-If you plan to use the Python binding, we recommend you use one
-of the following --prefix options when calling configure:
+If you plan to use the Python bindings, we recommend you use the
+following --prefix options when calling configure:
 
-  --prefix /usr
-  --prefix /usr/local  (the default)
-  --prefix ~/.local    (if you do not have root permissions)
+  --prefix ~/.local
 
-The reason is that all these locations are usually automatically
-searched by Python.  If you use a different prefix directory, you may
-have to tune the PYTHONPATH environment variable.
+The reason is that ~/.local/lib/python3.X/site-packages, where Spot's
+Python bindings will be installed, is automatically searched by
+Python.  If you use a different prefix directory, you may have to tune
+the PYTHONPATH environment variable, or use the --with-pythondir
+option to specify different installation paths.
 
 In addition to its usual options, ./configure will accept some
 flags specific to Spot:
@@ -250,17 +250,31 @@ To test the Python bindings, try running
   >>> import spot
   >>> print(spot.version())
 
-If you installed Spot with a prefix that is not one of those suggested
-in the "Building and installing" section, it is likely that the above
-import statement will fail to locate the spot package.  You can show
-the list of directories that are searched by Python using:
+If you installed Spot with a prefix that is not searched by Python by
+default it is likely that the above import statement will fail to
+locate the spot package.  You can show the list of directories that
+are searched by Python using:
 
   % python3
   >>> import sys
   >>> print(sys.path)
 
 And you can modify that list of searched directories using the
-PYTHONPATH environment variable.
+PYTHONPATH environment variable.  Alternatively, you can instruct Spot
+to install its Python files in one of those directory using the
+--with-pythondir configure option.  As an example, an issue in
+distributions derived from Debian is that if you run
+
+  ./configure && make && make install
+
+Python files get installed in /usr/local/lib/python3.X/site-packages
+while Debian's version of Python only looks for them into
+/usr/local/lib/python3.X/dist-packages instead.  You can fix that by
+instructing configure that you want packages installed into the right
+directory instead:
+
+  ./configure --with-pythondir=/usr/local/lib/python3.X/dist-packages \
+     && make && make install
 
 To test if man pages can be found, simply try:
 
diff --git a/configure.ac b/configure.ac
index 2d6b4be1f..e2e16d63a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -189,9 +189,14 @@ if test "x${enable_python:-yes}" = xyes; then
   AC_MSG_NOTICE([You may configure with --disable-python ]dnl
 [if you do not need Python bindings.])
   adl_CHECK_PYTHON
+
+  AC_ARG_WITH([pythondir],
+  [AS_HELP_STRING([--with-pythondir], [override the computed pythondir])],
+  [pythondir=$withval], [])
 fi
 
 
+
 adl_ENABLE_DEBUG
 ad_GCC_OPTIM
 adl_NDEBUG
@@ -290,3 +295,23 @@ case $VERSION:$enable_devel in
     echo '==================================================================='
   ;;
 esac
+
+case $enable_python in
+    yes)
+        pd=$pythondir
+        eval pd=$pd
+        eval pd=$pd
+        $PYTHON -c "
+import sys
+if '$pd' in sys.path:
+   exit()
+else:
+   print('\nWARNING: Python bindings will be installed in $pd')
+   print('         however this path is not searched by default by $PYTHON.')
+   print('\n$PYTHON\'s sys.path contains the following paths:\n',
+         '\n'.join(sys.path))
+   print('\nUse --with-pythondir=... if you wish '
+         'to change this installation path.')
+"
+        ;;
+esac