Permit building python bindings separately from gz-math library (backport #636)

CMakeLists.txt

@@ -111,28 +111,18 @@ else()
       set(Python3_EXECUTABLE ${PYTHON_EXECUTABLE})
       find_package(PythonLibs QUIET)
       # we found the interpreter but did we also find the libs? both are required
-      set(Python3_FOUND ${PYTHONLIBS_FOUND})
+      set(Python3_Development_FOUND ${PYTHONLIBS_FOUND})
       set(Python3_VERSION ${PYTHONLIBS_VERSION_STRING})
     endif()
   else()
     find_package(Python3 QUIET COMPONENTS Interpreter Development)
   endif()
 
-  if (NOT Python3_FOUND)
+  if (NOT Python3_Development_FOUND)
     GZ_BUILD_WARNING("Python3 is missing: Python interfaces are disabled.")
     message (STATUS "Searching for Python3 - not found.")
   else()
     message (STATUS "Searching for Python3 - found version ${Python3_VERSION}.")
-
-    set(PYBIND11_PYTHON_VERSION 3)
-    find_package(pybind11 2.2 QUIET)
-
-    if (${pybind11_FOUND})
-      message (STATUS "Searching for pybind11 - found version ${pybind11_VERSION}.")
-    else()
-      GZ_BUILD_WARNING("pybind11 is missing: Python interfaces are disabled.")
-      message (STATUS "Searching for pybind11 - not found.")
-    endif()
   endif()
 endif()
 

src/CMakeLists.txt

@@ -18,7 +18,7 @@ gz_build_tests(TYPE UNIT SOURCES ${gtest_sources})
 add_subdirectory(graph)
 
 # Bindings subdirectories
-if (pybind11_FOUND AND NOT SKIP_PYBIND11)
+if (Python3_Development_FOUND AND NOT SKIP_PYBIND11)
   add_subdirectory(python_pybind11)
 endif()
 

src/python_pybind11/CMakeLists.txt

@@ -1,4 +1,16 @@
-if(${CMAKE_VERSION} VERSION_LESS "3.12.0")
+# Detect if we are doing a standalone build of the bindings, using an external gz-math
+if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
+  cmake_minimum_required(VERSION 3.22.1)
+  set(GZ_MATH_VER 7)
+  project(gz-math${GZ_MATH_VER}-python VERSION ${GZ_MATH_VER})
+  find_package(gz-math${PROJECT_VERSION_MAJOR} REQUIRED)
+  set(PROJECT_LIBRARY_TARGET_NAME "gz-math${PROJECT_VERSION_MAJOR}::gz-math${PROJECT_VERSION_MAJOR}")
+  # require python dependencies to be found
+  find_package(Python3 COMPONENTS Interpreter Development REQUIRED)
+  set(CMAKE_REQUIRE_FIND_PACKAGE_pybind11 TRUE)
+  include(GNUInstallDirs)
+  include(CTest)
+elseif(${CMAKE_VERSION} VERSION_LESS "3.12.0")
   # TODO: remove once the minimum CMake version is increased
   if(WIN32 AND CMAKE_BUILD_TYPE STREQUAL "Debug")
     # pybind11 logic for setting up a debug build when both a debug and release
@@ -8,6 +20,16 @@ if(${CMAKE_VERSION} VERSION_LESS "3.12.0")
   endif()
 endif()
 
+set(PYBIND11_PYTHON_VERSION 3)
+find_package(pybind11 2.2 QUIET)
+
+if (${pybind11_FOUND})
+  message(STATUS "Searching for pybind11 - found version ${pybind11_VERSION}.")
+else()
+  message(WARNING "pybind11 is missing: Python interfaces are disabled.")
+  return()
+endif()
+
 message(STATUS "Building pybind11 interfaces")
 set(BINDINGS_MODULE_NAME "math${PROJECT_VERSION_MAJOR}")
 # Split from main extension and converted to pybind11
@@ -96,7 +118,7 @@ if(USE_SYSTEM_PATHS_FOR_PYTHON_INSTALLATION)
   endif()
 else()
   # If not a system installation, respect local paths
-  set(GZ_PYTHON_INSTALL_PATH ${GZ_LIB_INSTALL_DIR}/python)
+  set(GZ_PYTHON_INSTALL_PATH ${CMAKE_INSTALL_LIBDIR}/python)
 endif()
 
 set(GZ_PYTHON_INSTALL_PATH "${GZ_PYTHON_INSTALL_PATH}/gz")

tutorials/installation.md

@@ -38,9 +38,9 @@ you should use `ign-math<#>`.
 
 ### macOS
 
-On macOS, add OSRF packages:
+On macOS, after installing the [Homebrew package manager](https://brew.sh),
+add OSRF packages:
   ```
-  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   brew tap osrf/simulation
   ```
 
@@ -92,6 +92,13 @@ The optional Eigen component of Gazebo Math requires:
   sudo apt-get install libeigen3-dev
   ```
 
+The optional Python bindings of Gazebo Math require:
+
+* [Pybind11](https://pybind11.readthedocs.io/en/stable/index.html). Refer to the [Pybind11 Documentation](https://pybind11.readthedocs.io/en/stable/installing.html) for installation instructions. On Ubuntu systems, `apt-get` can be used to install Pybind11:
+  ```
+  sudo apt-get install python3-pybind11
+  ```
+
 The optional Ruby tests of Gazebo Math require:
 
 * [Ruby](https://www.ruby-lang.org/). Refer to the [Ruby Documentation](https://www.ruby-lang.org/downloads/) for installation instructions. On Ubuntu systems `apt-get` can be used to install Ubuntu Package `ruby-dev`:
@@ -228,6 +235,34 @@ The optional Eigen component of Gazebo Math requires:
   cmake --install . --config Release
   ```
 
+### cmake parameters
+
+| Name            | Type | Default | Description                                |
+|-----------------|------|---------|--------------------------------------------|
+| `SKIP_PYBIND11` | BOOL | OFF     | Set to ON to skip building python bindings |
+
+### Building Python bindings separately from main library
+
+If you want to build Python bindings separately from the main gz-math library
+(for example if you want to build Python bindings for multiple versions of Python),
+you can invoke cmake on the `src/python_pybind11` folder instead of the root folder.
+Specify the path to the python executable with which you wish to build bindings
+in the `Python3_EXECUTABLE` cmake variable.
+Specify the install path for the bindings in the `CMAKE_INSTALL_PREFIX`
+variable, and be sure to set your `PYTHONPATH` accordingly after install.
+
+```bash
+cd gz-math
+mkdir build_python3
+cd build_python3
+cmake ../src/python_pybind11 \
+    -DPython3_EXECUTABLE=/usr/local/bin/python3.12 \
+    -DCMAKE_INSTALL_PREFIX=<prefix>
+```
+
+See the homebrew [gz-math8 formula](https://github.com/osrf/homebrew-simulation/blob/ccda47647ed9aeb38f0ea1ec8804fd1501058de1/Formula/gz-math8.rb#L12-L52)
+for an example of building bindings for multiple versions of Python.
+
 # Documentation
 
 API and tutorials can be found at [https://gazebosim.org/libs/math](https://gazebosim.org/libs/math).