Merge branch 'borglab:develop' into develop

Author: PeterCalifano

.github/scripts/python_wheels/cibw_before_all.sh

@@ -14,17 +14,47 @@ export PYTHON="python${PYTHON_VERSION}"
 
 if [ "$(uname)" == "Linux" ]; then
     # manylinux2014 is based on CentOS 7, so use yum to install dependencies
-    yum install -y wget
-
-    # Install Boost from source
-    wget https://archives.boost.io/release/1.87.0/source/boost_1_87_0.tar.gz --quiet
-    tar -xzf boost_1_87_0.tar.gz
-    cd boost_1_87_0
-    ./bootstrap.sh --prefix=/opt/boost
-    ./b2 install --prefix=/opt/boost --with=all 
-    cd ..
+    yum install -y wget doxygen
 elif [ "$(uname)" == "Darwin" ]; then
-    brew install wget cmake boost
+    brew install cmake doxygen
+
+    # If MACOSX_DEPLOYMENT_TARGET is not explicitly set, default to the version of the host system.
+    if [[ -z "${MACOSX_DEPLOYMENT_TARGET}" ]]; then
+        export MACOSX_DEPLOYMENT_TARGET="$(sw_vers -productVersion | cut -d '.' -f 1-2)"
+    fi
+fi
+
+# Install Boost from source
+wget https://archives.boost.io/release/1.87.0/source/boost_1_87_0.tar.gz --quiet
+tar -xzf boost_1_87_0.tar.gz
+cd boost_1_87_0
+
+BOOST_PREFIX="$HOME/opt/boost"
+./bootstrap.sh --prefix=${BOOST_PREFIX}
+
+if [ "$(uname)" == "Linux" ]; then
+    ./b2 install --prefix=${BOOST_PREFIX} --with=all -d0
+elif [ "$(uname)" == "Darwin" ]; then
+    ./b2 install --prefix=${BOOST_PREFIX} --with=all -d0 \
+        cxxflags="-mmacosx-version-min=${MACOSX_DEPLOYMENT_TARGET}" \
+        linkflags="-mmacosx-version-min=${MACOSX_DEPLOYMENT_TARGET}"
+fi
+cd ..
+
+# Export paths so CMake or build system can find Boost
+export BOOST_ROOT="${BOOST_PREFIX}"
+export BOOST_INCLUDEDIR="${BOOST_PREFIX}/include"
+export BOOST_LIBRARYDIR="${BOOST_PREFIX}/lib"
+
+# Ensure runtime linker can find Boost libraries
+export LD_LIBRARY_PATH="${BOOST_LIBRARYDIR}:$LD_LIBRARY_PATH" # For Linux
+export REPAIR_LIBRARY_PATH="${BOOST_LIBRARYDIR}:$DYLD_LIBRARY_PATH" # For macOS, REPAIR_LIBRARY_PATH is used by delocate
+
+if [ "$(uname)" == "Darwin" ]; then
+    # Explicitly add rpath to Boost dylibs so delocate can find them
+    for dylib in ${BOOST_LIBRARYDIR}/*.dylib; do
+        install_name_tool -add_rpath "@loader_path" "$dylib"
+    done
 fi
 
 $(which $PYTHON) -m pip install -r $PROJECT_DIR/python/dev_requirements.txt
@@ -48,11 +78,15 @@ cmake $PROJECT_DIR \
     -DGTSAM_PYTHON_VERSION=$PYTHON_VERSION \
     -DPYTHON_EXECUTABLE:FILEPATH=$(which $PYTHON) \
     -DGTSAM_ALLOW_DEPRECATED_SINCE_V43=OFF \
-    -DCMAKE_INSTALL_PREFIX=$PROJECT_DIR/gtsam_install
+    -DCMAKE_INSTALL_PREFIX=$PROJECT_DIR/gtsam_install \
+    -DGTSAM_GENERATE_DOC_XML=1 \
+    -DGTWRAP_ADD_DOCSTRINGS=ON
 
-cd $PROJECT_DIR/build/python
+# Generate Doxygen XML documentation
+doxygen build/doc/Doxyfile
 
 # Install the Python wrapper module and generate Python stubs
+cd $PROJECT_DIR/build/python
 if [ "$(uname)" == "Linux" ]; then
     make -j $(nproc) install
     make -j $(nproc) python-stubs

.github/workflows/build-cibw.yml

@@ -76,22 +76,40 @@ jobs:
             manylinux_image: manylinux2014
 
           # MacOS x86_64
-          # - os: macos-13
-          #   python_version: "3.10"
-          #   cibw_python_version: 310
-          #   platform_id: macosx_x86_64
-          # - os: macos-13
-          #   python_version: "3.11"
-          #   cibw_python_version: 311
-          #   platform_id: macosx_x86_64
-          # - os: macos-13
-          #   python_version: "3.12"
-          #   cibw_python_version: 312
-          #   platform_id: macosx_x86_64
-          # - os: macos-13
-          #   python_version: "3.13"
-          #   cibw_python_version: 313
-          #   platform_id: macosx_x86_64
+          - os: macos-13
+            python_version: "3.10"
+            cibw_python_version: 310
+            platform_id: macosx_x86_64
+          - os: macos-13
+            python_version: "3.11"
+            cibw_python_version: 311
+            platform_id: macosx_x86_64
+          - os: macos-13
+            python_version: "3.12"
+            cibw_python_version: 312
+            platform_id: macosx_x86_64
+          - os: macos-13
+            python_version: "3.13"
+            cibw_python_version: 313
+            platform_id: macosx_x86_64
+
+          # MacOS arm64
+          - os: macos-14
+            python_version: "3.10"
+            cibw_python_version: 310
+            platform_id: macosx_arm64
+          - os: macos-14
+            python_version: "3.11"
+            cibw_python_version: 311
+            platform_id: macosx_arm64
+          - os: macos-14
+            python_version: "3.12"
+            cibw_python_version: 312
+            platform_id: macosx_arm64
+          - os: macos-14
+            python_version: "3.13"
+            cibw_python_version: 313
+            platform_id: macosx_arm64
 
     steps:
       - name: Checkout
@@ -130,6 +148,14 @@ jobs:
         run: |
           cmake . -B build -DGTSAM_BUILD_PYTHON=1 -DGTSAM_PYTHON_VERSION=${{ matrix.python_version }}
 
+      # If on macOS, we previously installed boost using homebrew for the first build.
+      # We need to uninstall it before building the wheels with cibuildwheel, which will
+      # install boost from source.
+      - name: Uninstall Boost (MacOS)
+        if: runner.os == 'macOS'
+        run: |
+          brew uninstall boost
+
       - name: Build and test wheels
         env:
           # Generate the platform identifier. See https://cibuildwheel.pypa.io/en/stable/options/#build-skip.
@@ -139,6 +165,13 @@ jobs:
           CIBW_ARCHS: all
           CIBW_ENVIRONMENT_PASS_LINUX: DEVELOP TIMESTAMP
 
+          # Set the minimum required MacOS version for the wheels.
+          MACOSX_DEPLOYMENT_TARGET: 10.15
+
+          # Set DYLD_LIBRARY_PATH to REPAIR_LIBRARY_PATH, which is set in cibw_before_all.sh. REPAIR_LIBRARY_PATH
+          # simply appends BOOST_LIBRARYDIR to the path, which is required during during link-time repair.
+          CIBW_REPAIR_WHEEL_COMMAND_MACOS: DYLD_LIBRARY_PATH=$REPAIR_LIBRARY_PATH delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel}
+
           # Use build instead of pip wheel to build the wheels. This is recommended by PyPA.
           # See https://cibuildwheel.pypa.io/en/stable/options/#build-frontend.
           CIBW_BUILD_FRONTEND: "build"

.github/workflows/build-linux.yml

@@ -3,9 +3,9 @@ name: Linux CI
 on:
   pull_request:
     paths-ignore:
-      - '**.md'
-      - '**.ipynb' 
-      - 'myst.yml'
+      - "**.md"
+      - "**.ipynb"
+      - "myst.yml"
 
 # Every time you make a push to your PR, it cancel immediately the previous checks,
 # and start a new one. The other runner will be available more quickly to your PR.
@@ -30,25 +30,25 @@ jobs:
         # Github Actions requires a single row to be added to the build matrix.
         # See https://help.github.com/en/articles/workflow-syntax-for-github-actions.
         name: [
-            # "Bracket" the versions from GCC [9-14] and Clang [9-16]
-            ubuntu-20.04-gcc-9,
-            ubuntu-20.04-clang-9,
+            # "Bracket" the versions from GCC [9-14] and Clang [11-16]
+            ubuntu-22.04-gcc-9,
+            ubuntu-22.04-clang-11,
             ubuntu-24.04-gcc-14,
             ubuntu-24.04-clang-16,
           ]
 
         build_type: [Debug, Release]
         build_unstable: [ON]
         include:
-          - name: ubuntu-20.04-gcc-9
-            os: ubuntu-20.04
+          - name: ubuntu-22.04-gcc-9
+            os: ubuntu-22.04
             compiler: gcc
             version: "9"
 
-          - name: ubuntu-20.04-clang-9
-            os: ubuntu-20.04
+          - name: ubuntu-22.04-clang-11
+            os: ubuntu-22.04
             compiler: clang
-            version: "9"
+            version: "11"
 
           - name: ubuntu-24.04-gcc-14
             os: ubuntu-24.04

.github/workflows/build-python.yml

@@ -22,18 +22,18 @@ jobs:
         id: filter
         uses: dorny/paths-filter@v3
         with:
-          predicate-quantifier: 'every' # If any changed file matches every filter, proceed with build
+          predicate-quantifier: "every" # If any changed file matches every filter, proceed with build
           filters: |
             relevant_changes:
               - '!**.md'
               - '!**.ipynb' 
               - '!myst.yml'
-              
+
   build:
     # Only run build if relevant files have been modified in this PR.
     needs: check-paths
     if: needs.check-paths.outputs.should_run == 'true'
-    
+
     name: ${{ matrix.name }} ${{ matrix.build_type }} Python ${{ matrix.python_version }}
     runs-on: ${{ matrix.os }}
 
@@ -52,8 +52,8 @@ jobs:
         # See https://help.github.com/en/articles/workflow-syntax-for-github-actions.
         name:
           [
-            ubuntu-20.04-gcc-9,
-            ubuntu-20.04-clang-9,
+            ubuntu-22.04-gcc-9,
+            ubuntu-22.04-clang-11,
             macos-13-xcode-14.2,
             macos-14-xcode-15.4,
             windows-2022-msbuild,
@@ -62,15 +62,15 @@ jobs:
         build_type: [Release]
         python_version: [3]
         include:
-          - name: ubuntu-20.04-gcc-9
-            os: ubuntu-20.04
+          - name: ubuntu-22.04-gcc-9
+            os: ubuntu-22.04
             compiler: gcc
             version: "9"
 
-          - name: ubuntu-20.04-clang-9
-            os: ubuntu-20.04
+          - name: ubuntu-22.04-clang-11
+            os: ubuntu-22.04
             compiler: clang
-            version: "9"
+            version: "11"
 
           - name: macos-13-xcode-14.2
             os: macos-13

README.md

@@ -15,11 +15,11 @@ matrices.
 
 The current support matrix is:
 
-| Platform           | Compiler  | Build Status                                                                     |
-|:------------------:|:---------:|:--------------------------------------------------------------------------------:|
-| Ubuntu 20.04/22.04 | gcc/clang | ![Linux CI](https://github.com/borglab/gtsam/workflows/Linux%20CI/badge.svg)     |
-| macOS              | clang     | ![macOS CI](https://github.com/borglab/gtsam/workflows/macOS%20CI/badge.svg)     |
-| Windows            | MSVC      | ![Windows CI](https://github.com/borglab/gtsam/workflows/Windows%20CI/badge.svg) |
+|      Platform      | Compiler  |                                   Build Status                                   |
+| :----------------: | :-------: | :------------------------------------------------------------------------------: |
+| Ubuntu 22.04/24.04 | gcc/clang |   ![Linux CI](https://github.com/borglab/gtsam/workflows/Linux%20CI/badge.svg)   |
+|       macOS        |   clang   |   ![macOS CI](https://github.com/borglab/gtsam/workflows/macOS%20CI/badge.svg)   |
+|      Windows       |   MSVC    | ![Windows CI](https://github.com/borglab/gtsam/workflows/Windows%20CI/badge.svg) |
 
 
 On top of the C++ library, GTSAM includes [wrappers for MATLAB & Python](#wrappers).

doc/CMakeLists.txt

@@ -4,10 +4,12 @@ option(GTSAM_BUILD_DOCS                  "Enable/Disable building of doxygen doc
 # configure doxygen
 option(GTSAM_BUILD_DOC_HTML              "Enable/Disable doxygen HTML output"    ON)
 option(GTSAM_BUILD_DOC_LATEX             "Enable/Disable doxygen LaTeX output"   OFF)
+option(GTSAM_GENERATE_DOC_XML            "Enable/Disable doxygen XML output"     OFF)
 
 # add a target to generate API documentation with Doxygen
 if (GTSAM_BUILD_DOCS)
-    # Convert configuration to YES/NO variables
+    # The following if statements convert ON/OFF CMake flags to YES/NO variables
+    # since Doxygen expects YES/NO for boolean options.
     if (GTSAM_BUILD_DOC_HTML)
         set(GTSAM_BUILD_DOC_HTML_YN "YES")
     else() 
@@ -20,6 +22,12 @@ if (GTSAM_BUILD_DOCS)
         set(GTSAM_BUILD_DOC_LATEX_YN "NO")
     endif()
 
+    if (GTSAM_GENERATE_DOC_XML)
+        set(GTSAM_GENERATE_XML_YN "YES")
+    else() 
+        set(GTSAM_GENERATE_XML_YN "NO")
+    endif()
+
     # GTSAM core subfolders
     set(gtsam_doc_subdirs 
         gtsam/base

doc/Doxyfile.in

@@ -2120,7 +2120,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = @GTSAM_GENERATE_XML_YN@
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

doc/examples.md

@@ -0,0 +1,3 @@
+# Examples
+
+This section contains python examples in interactive Python notebooks (`*.ipynb`). Python notebooks with an <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> button near the top can be opened in your browser, where you can run the files yourself and make edits to play with and understand GTSAM.