build(wheel): make libcuopt a thin metapackage

.github/workflows/build.yaml

@@ -208,7 +208,8 @@ jobs:
       id-token: write
       packages: read
       pull-requests: read
-    needs: [build-details]
+    # Links against the client/mathopt/routing wheels' installed .so's instead of recompiling them.
+    needs: [build-details, wheel-build-libcuopt-client, wheel-build-libcuopt-mathopt, wheel-build-libcuopt-routing]
     secrets: inherit # zizmor: ignore[secrets-inherit]
     uses: rapidsai/shared-workflows/.github/workflows/wheels-build.yaml@release/26.10
     with:
@@ -291,7 +292,8 @@ jobs:
       id-token: write
       packages: read
       pull-requests: read
-    needs: [build-details]
+    # Links against the client wheel's installed libcuopt_client.so instead of recompiling it.
+    needs: [build-details, wheel-build-libcuopt-client]
     secrets: inherit # zizmor: ignore[secrets-inherit]
     uses: rapidsai/shared-workflows/.github/workflows/wheels-build.yaml@release/26.10
     with:
@@ -334,7 +336,8 @@ jobs:
       id-token: write
       packages: read
       pull-requests: read
-    needs: [build-details]
+    # Links against the client wheel's installed libcuopt_client.so instead of recompiling it.
+    needs: [build-details, wheel-build-libcuopt-client]
     secrets: inherit # zizmor: ignore[secrets-inherit]
     uses: rapidsai/shared-workflows/.github/workflows/wheels-build.yaml@release/26.10
     with:
@@ -371,7 +374,12 @@ jobs:
       package-type: cpp
       publish-wheel-search-key: cuopt_wheel_cpp_libcuopt_routing
   wheel-build-cuopt:
-    needs: [build-details, wheel-build-libcuopt]
+    needs:
+      - build-details
+      - wheel-build-libcuopt
+      - wheel-build-libcuopt-client
+      - wheel-build-libcuopt-mathopt
+      - wheel-build-libcuopt-routing
     permissions:
       actions: read
       contents: read

.github/workflows/pr.yaml

@@ -595,25 +595,6 @@ jobs:
       script: "ci/test_java.sh"
       artifact-name: "cuopt-java"
       file_to_upload: "java/cuopt/target/"
-  wheel-build-libcuopt:
-    needs: [build-details, compute-matrix-filters, changed-files]
-    if: fromJSON(needs.changed-files.outputs.changed_file_groups).test_python_wheels
-    permissions:
-      actions: read
-      contents: read
-      id-token: write
-      packages: read
-      pull-requests: read
-    secrets: inherit # zizmor: ignore[secrets-inherit]
-    uses: rapidsai/shared-workflows/.github/workflows/wheels-build.yaml@release/26.10
-    with:
-      # build for every combination of arch and CUDA version, but only for the latest Python
-      matrix_filter: ${{ needs.compute-matrix-filters.outputs.libcuopt_filter }}
-      package-type: cpp
-      package-name: libcuopt
-      build_type: pull-request
-      build-datetime: ${{ needs.build-details.outputs.build-datetime }}
-      script: ci/build_wheel_libcuopt.sh
   wheel-build-libcuopt-client:
     needs: [build-details, compute-matrix-filters, changed-files]
     if: fromJSON(needs.changed-files.outputs.changed_file_groups).test_python_wheels
@@ -635,7 +616,7 @@ jobs:
       build-datetime: ${{ needs.build-details.outputs.build-datetime }}
       script: ci/build_wheel_libcuopt_client.sh
   wheel-build-libcuopt-mathopt:
-    needs: [build-details, compute-matrix-filters, changed-files]
+    needs: [build-details, compute-matrix-filters, changed-files, wheel-build-libcuopt-client]
     if: fromJSON(needs.changed-files.outputs.changed_file_groups).test_python_wheels
     permissions:
       actions: read
@@ -654,7 +635,7 @@ jobs:
       build-datetime: ${{ needs.build-details.outputs.build-datetime }}
       script: ci/build_wheel_libcuopt_mathopt.sh
   wheel-build-libcuopt-routing:
-    needs: [build-details, compute-matrix-filters, changed-files]
+    needs: [build-details, compute-matrix-filters, changed-files, wheel-build-libcuopt-client]
     if: fromJSON(needs.changed-files.outputs.changed_file_groups).test_python_wheels
     permissions:
       actions: read
@@ -672,8 +653,40 @@ jobs:
       build_type: pull-request
       build-datetime: ${{ needs.build-details.outputs.build-datetime }}
       script: ci/build_wheel_libcuopt_routing.sh
+  wheel-build-libcuopt:
+    needs:
+      - build-details
+      - compute-matrix-filters
+      - changed-files
+      - wheel-build-libcuopt-client
+      - wheel-build-libcuopt-mathopt
+      - wheel-build-libcuopt-routing
+    if: fromJSON(needs.changed-files.outputs.changed_file_groups).test_python_wheels
+    permissions:
+      actions: read
+      contents: read
+      id-token: write
+      packages: read
+      pull-requests: read
+    secrets: inherit # zizmor: ignore[secrets-inherit]
+    uses: rapidsai/shared-workflows/.github/workflows/wheels-build.yaml@release/26.10
+    with:
+      # build for every combination of arch and CUDA version, but only for the latest Python
+      matrix_filter: ${{ needs.compute-matrix-filters.outputs.libcuopt_filter }}
+      package-type: cpp
+      package-name: libcuopt
+      build_type: pull-request
+      build-datetime: ${{ needs.build-details.outputs.build-datetime }}
+      script: ci/build_wheel_libcuopt.sh
   wheel-build-cuopt:
-    needs: [build-details, wheel-build-libcuopt, compute-matrix-filters, changed-files]
+    needs:
+      - build-details
+      - wheel-build-libcuopt
+      - wheel-build-libcuopt-client
+      - wheel-build-libcuopt-mathopt
+      - wheel-build-libcuopt-routing
+      - compute-matrix-filters
+      - changed-files
     if: fromJSON(needs.changed-files.outputs.changed_file_groups).test_python_wheels
     permissions:
       actions: read

ci/build_wheel_cuopt.sh

@@ -31,6 +31,15 @@ LIBCUOPT_WHEELHOUSE=$(rapids-download-from-github "$(rapids-artifact-name wheel_
 
 echo "libcuopt-${RAPIDS_PY_CUDA_SUFFIX} @ file://$(echo ${LIBCUOPT_WHEELHOUSE}/libcuopt_*.whl)" >> "${PIP_CONSTRAINT}"
 
+LIBCUOPT_CLIENT_WHEELHOUSE=$(rapids-download-from-github "$(rapids-artifact-name wheel_cpp libcuopt_client cuopt)")
+echo "libcuopt-client @ file://$(echo ${LIBCUOPT_CLIENT_WHEELHOUSE}/libcuopt_client-*.whl)" >> "${PIP_CONSTRAINT}"
+
+LIBCUOPT_MATHOPT_WHEELHOUSE=$(rapids-download-from-github "$(rapids-artifact-name wheel_cpp libcuopt_mathopt cuopt --cuda "$RAPIDS_CUDA_VERSION")")
+echo "libcuopt-mathopt-${RAPIDS_PY_CUDA_SUFFIX} @ file://$(echo ${LIBCUOPT_MATHOPT_WHEELHOUSE}/libcuopt_mathopt_*.whl)" >> "${PIP_CONSTRAINT}"
+
+LIBCUOPT_ROUTING_WHEELHOUSE=$(rapids-download-from-github "$(rapids-artifact-name wheel_cpp libcuopt_routing cuopt --cuda "$RAPIDS_CUDA_VERSION")")
+echo "libcuopt-routing-${RAPIDS_PY_CUDA_SUFFIX} @ file://$(echo ${LIBCUOPT_ROUTING_WHEELHOUSE}/libcuopt_routing_*.whl)" >> "${PIP_CONSTRAINT}"
+
 EXCLUDE_ARGS=(
   --exclude "libraft.so"
   --exclude "libcublas.so.*"

ci/build_wheel_libcuopt.sh

@@ -9,6 +9,17 @@ source rapids-init-pip
 package_name="libcuopt"
 package_dir="python/libcuopt"
 
+RAPIDS_PY_CUDA_SUFFIX="$(rapids-wheel-ctk-name-gen "${RAPIDS_CUDA_VERSION}")"
+
+LIBCUOPT_CLIENT_WHEELHOUSE=$(rapids-download-from-github "$(rapids-artifact-name wheel_cpp libcuopt_client cuopt)")
+echo "libcuopt-client @ file://$(echo ${LIBCUOPT_CLIENT_WHEELHOUSE}/libcuopt_client-*.whl)" >> "${PIP_CONSTRAINT}"
+
+LIBCUOPT_MATHOPT_WHEELHOUSE=$(rapids-download-from-github "$(rapids-artifact-name wheel_cpp libcuopt_mathopt cuopt --cuda "$RAPIDS_CUDA_VERSION")")
+echo "libcuopt-mathopt-${RAPIDS_PY_CUDA_SUFFIX} @ file://$(echo ${LIBCUOPT_MATHOPT_WHEELHOUSE}/libcuopt_mathopt_*.whl)" >> "${PIP_CONSTRAINT}"
+
+LIBCUOPT_ROUTING_WHEELHOUSE=$(rapids-download-from-github "$(rapids-artifact-name wheel_cpp libcuopt_routing cuopt --cuda "$RAPIDS_CUDA_VERSION")")
+echo "libcuopt-routing-${RAPIDS_PY_CUDA_SUFFIX} @ file://$(echo ${LIBCUOPT_ROUTING_WHEELHOUSE}/libcuopt_routing_*.whl)" >> "${PIP_CONSTRAINT}"
+
 # Install rockylinux repo
 if command -v dnf &> /dev/null; then
     bash ci/utils/update_rockylinux_repo.sh
@@ -25,6 +36,8 @@ elif command -v apt-get &> /dev/null; then
     apt-get install -y uuid-dev
 fi
 
+source rapids-configure-sccache
+
 # Install Protobuf + gRPC (protoc + grpc_cpp_plugin)
 bash ci/utils/install_protobuf_grpc.sh
 
@@ -37,7 +50,7 @@ python ci/utils/install_modern_libgomp.py "${MODERN_LIBGOMP_DIR}"
 # Also build our own cuDSS threading layer against this same libgomp (see cpp/CMakeLists.txt,
 # cpp/src/barrier/cudss_mtlayer_cuopt.cpp), instead of cuDSS's prebuilt one, so both actually
 # share one instance, not just the same flavor. Conda keeps cuDSS's default (#1219 discussion).
-export SKBUILD_CMAKE_ARGS="-DOpenMP_gomp_LIBRARY:FILEPATH=${MODERN_LIBGOMP_DIR}/libgomp.so.1.0.0;-DCUOPT_BUILD_CUSTOM_CUDSS_MTLAYER=ON"
+export SKBUILD_CMAKE_ARGS="-DOpenMP_gomp_LIBRARY:FILEPATH=${MODERN_LIBGOMP_DIR}/libgomp.so.1.0.0;-DCUOPT_BUILD_CUSTOM_CUDSS_MTLAYER=ON;-DCUOPT_FIND_CLIENT_EXTERNALLY=ON;-DCUOPT_FIND_MATHOPT_EXTERNALLY=ON;-DCUOPT_FIND_ROUTING_EXTERNALLY=ON"
 
 # auditwheel repair does its own dependency resolution separately from the compiler; without
 # this it can't see our fetched copy and silently vendors the old Rocky 8 system one instead.
@@ -99,6 +112,9 @@ EXCLUDE_ARGS=(
   --exclude "libcurand.so.*"
   --exclude "libcusolver.so.*"
   --exclude "libcusparse.so.*"
+  --exclude "libcuopt_client.so"
+  --exclude "libcuopt_mathopt.so"
+  --exclude "libcuopt_routing.so"
   --exclude "libnccl.so.*"
   --exclude "libnvJitLink.so*"
   --exclude "librapids_logger.so"

ci/build_wheel_libcuopt_client.sh

@@ -29,6 +29,8 @@ elif command -v apt-get &> /dev/null; then
     apt-get install -y uuid-dev
 fi
 
+source rapids-configure-sccache
+
 # Install Protobuf + gRPC (protoc + grpc_cpp_plugin)
 bash ci/utils/install_protobuf_grpc.sh
 

ci/build_wheel_libcuopt_mathopt.sh

@@ -13,6 +13,9 @@ source rapids-init-pip
 package_name="libcuopt_mathopt"
 package_dir="python/libcuopt_mathopt"
 
+LIBCUOPT_CLIENT_WHEELHOUSE=$(rapids-download-from-github "$(rapids-artifact-name wheel_cpp libcuopt_client cuopt)")
+echo "libcuopt-client @ file://$(echo ${LIBCUOPT_CLIENT_WHEELHOUSE}/libcuopt_client-*.whl)" >> "${PIP_CONSTRAINT}"
+
 # Install rockylinux repo
 if command -v dnf &> /dev/null; then
     bash ci/utils/update_rockylinux_repo.sh
@@ -29,6 +32,8 @@ elif command -v apt-get &> /dev/null; then
     apt-get install -y uuid-dev
 fi
 
+source rapids-configure-sccache
+
 # Install Protobuf + gRPC (protoc + grpc_cpp_plugin)
 bash ci/utils/install_protobuf_grpc.sh
 
@@ -41,7 +46,7 @@ python ci/utils/install_modern_libgomp.py "${MODERN_LIBGOMP_DIR}"
 # Also build our own cuDSS threading layer against this same libgomp (see cpp/CMakeLists.txt,
 # cpp/src/barrier/cudss_mtlayer_cuopt.cpp), instead of cuDSS's prebuilt one, so both actually
 # share one instance, not just the same flavor. Conda keeps cuDSS's default (#1219 discussion).
-export SKBUILD_CMAKE_ARGS="-DOpenMP_gomp_LIBRARY:FILEPATH=${MODERN_LIBGOMP_DIR}/libgomp.so.1.0.0;-DCUOPT_BUILD_CUSTOM_CUDSS_MTLAYER=ON"
+export SKBUILD_CMAKE_ARGS="-DOpenMP_gomp_LIBRARY:FILEPATH=${MODERN_LIBGOMP_DIR}/libgomp.so.1.0.0;-DCUOPT_BUILD_CUSTOM_CUDSS_MTLAYER=ON;-DCUOPT_FIND_CLIENT_EXTERNALLY=ON;-DSKIP_ROUTING_BUILD=ON"
 
 # auditwheel repair does its own dependency resolution separately from the compiler; without
 # this it can't see our fetched copy and silently vendors the old Rocky 8 system one instead.

ci/build_wheel_libcuopt_routing.sh

@@ -13,6 +13,9 @@ source rapids-init-pip
 package_name="libcuopt_routing"
 package_dir="python/libcuopt_routing"
 
+LIBCUOPT_CLIENT_WHEELHOUSE=$(rapids-download-from-github "$(rapids-artifact-name wheel_cpp libcuopt_client cuopt)")
+echo "libcuopt-client @ file://$(echo ${LIBCUOPT_CLIENT_WHEELHOUSE}/libcuopt_client-*.whl)" >> "${PIP_CONSTRAINT}"
+
 # Install rockylinux repo
 if command -v dnf &> /dev/null; then
     bash ci/utils/update_rockylinux_repo.sh
@@ -29,6 +32,8 @@ elif command -v apt-get &> /dev/null; then
     apt-get install -y uuid-dev
 fi
 
+source rapids-configure-sccache
+
 # Install Protobuf + gRPC (protoc + grpc_cpp_plugin)
 bash ci/utils/install_protobuf_grpc.sh
 
@@ -41,7 +46,7 @@ python ci/utils/install_modern_libgomp.py "${MODERN_LIBGOMP_DIR}"
 # Also build our own cuDSS threading layer against this same libgomp (see cpp/CMakeLists.txt,
 # cpp/src/barrier/cudss_mtlayer_cuopt.cpp), instead of cuDSS's prebuilt one, so both actually
 # share one instance, not just the same flavor. Conda keeps cuDSS's default (#1219 discussion).
-export SKBUILD_CMAKE_ARGS="-DOpenMP_gomp_LIBRARY:FILEPATH=${MODERN_LIBGOMP_DIR}/libgomp.so.1.0.0;-DCUOPT_BUILD_CUSTOM_CUDSS_MTLAYER=ON"
+export SKBUILD_CMAKE_ARGS="-DOpenMP_gomp_LIBRARY:FILEPATH=${MODERN_LIBGOMP_DIR}/libgomp.so.1.0.0;-DCUOPT_BUILD_CUSTOM_CUDSS_MTLAYER=ON;-DCUOPT_FIND_CLIENT_EXTERNALLY=ON;-DSKIP_MATHOPT_BUILD=ON;-DSKIP_GRPC_BUILD=ON"
 
 # auditwheel repair does its own dependency resolution separately from the compiler; without
 # this it can't see our fetched copy and silently vendors the old Rocky 8 system one instead.

ci/release/update-version.sh

@@ -103,6 +103,9 @@ DEPENDENCIES=(
   cuopt-server
   cuopt-sh-client
   libcuopt
+  libcuopt-client
+  libcuopt-mathopt
+  libcuopt-routing
   libcuopt-tests
   libraft-headers
   librmm

ci/test_doc_examples.sh

@@ -33,6 +33,8 @@ GRPC_PID=""
 # C library paths (set by find_cuopt_libraries)
 include_path=""
 lib_path=""
+client_include_path=""
+client_lib_path=""
 
 # Create results directory
 mkdir -p "${RESULTS_DIR}"
@@ -361,12 +363,14 @@ test_c_examples() {
         # Clean and build
         if [ -f "Makefile" ]; then
             log_info "  Building C examples..."
-            local make_vars=""
-            [ -n "${include_path}" ] && make_vars="${make_vars} INCLUDE_PATH=${include_path}"
-            [ -n "${lib_path}" ] && make_vars="${make_vars} LIBCUOPT_LIBRARY_PATH=${lib_path}"
+            local make_vars=()
+            [ -n "${include_path}" ] && make_vars+=("INCLUDE_PATH=${include_path}")
+            [ -n "${lib_path}" ] && make_vars+=("LIBCUOPT_LIBRARY_PATH=${lib_path}")
+            make_vars+=("CLIENT_INCLUDE_PATH=${client_include_path:-${include_path}}")
+            make_vars+=("CLIENT_LIBRARY_PATH=${client_lib_path:-${lib_path}}")
 
             if make clean > "${RESULTS_DIR}/c-clean-${relative_path//\//_}.log" 2>&1 && \
-               make ${make_vars} all > "${RESULTS_DIR}/c-build-${relative_path//\//_}.log" 2>&1; then
+               make "${make_vars[@]}" all > "${RESULTS_DIR}/c-build-${relative_path//\//_}.log" 2>&1; then
                 log_success "  C examples built successfully"
             else
                 log_failure "  Failed to build C examples"
@@ -461,6 +465,8 @@ find_cuopt_libraries() {
     # Reset global variables
     include_path=""
     lib_path=""
+    client_include_path=""
+    client_lib_path=""
 
     # Get Python site-packages directory
     local site_packages=""
@@ -485,9 +491,10 @@ find_cuopt_libraries() {
             found_header=$(find "${search_dir}" -name "cuopt_c.h" -path "*/mathematical_optimization/*" 2>/dev/null | head -1)
 
             if [ -n "${found_header}" ]; then
-                # Check if this is a Python package installation (contains libcuopt/include)
-                if echo "${found_header}" | grep -q "/libcuopt/include/"; then
-                    # Python package structure: /path/to/libcuopt/include/cuopt/mathematical_optimization/cuopt_c.h
+                # Check if this is a Python package installation (contains libcuopt*/include, e.g.
+                # libcuopt/ or the per-component libcuopt_client/, libcuopt_mathopt/, libcuopt_routing/)
+                if echo "${found_header}" | grep -qE "/libcuopt[a-z_]*/include/"; then
+                    # Python package structure: /path/to/libcuopt*/include/cuopt/mathematical_optimization/cuopt_c.h
                     # Extract the include directory by going up 3 directories from the header file
                     include_path=$(dirname "$(dirname "$(dirname "${found_header}")")")
                 else
@@ -499,32 +506,71 @@ find_cuopt_libraries() {
         fi
 
         if [ -z "${lib_path}" ]; then
-            # Search for libcuopt.so in both lib and lib64 directories
+            # The C examples link -lcuopt_mathopt directly, not the libcuopt umbrella (which
+            # no longer bundles it -- it's in libcuopt-mathopt's own wheel since the split).
             local found_lib
-            found_lib=$(find "${search_dir}" -name "libcuopt.so" \( -path "*/lib/*" -o -path "*/lib64/*" \) 2>/dev/null | head -1)
+            found_lib=$(find "${search_dir}" -name "libcuopt_mathopt.so" \( -path "*/lib/*" -o -path "*/lib64/*" \) 2>/dev/null | head -1)
             if [ -n "${found_lib}" ]; then
                 lib_path=$(dirname "${found_lib}")
             fi
         fi
 
-        # Break early if both found
-        if [ -n "${include_path}" ] && [ -n "${lib_path}" ]; then
+        if [ -z "${client_include_path}" ] && [ -n "${include_path}" ] && \
+           [ ! -f "${include_path}/cuopt/status_codes.h" ]; then
+            local found_status_codes
+            found_status_codes=$(find "${search_dir}" -path "*/cuopt/status_codes.h" 2>/dev/null | head -1)
+            if [ -n "${found_status_codes}" ]; then
+                client_include_path=$(dirname "$(dirname "${found_status_codes}")")
+            fi
+        fi
+
+        if [ -z "${client_lib_path}" ] && [ -n "${lib_path}" ] && \
+           [ ! -f "${lib_path}/libcuopt_client.so" ]; then
+            local found_client_lib
+            found_client_lib=$(find "${search_dir}" -name "libcuopt_client.so" \( -path "*/lib/*" -o -path "*/lib64/*" \) 2>/dev/null | head -1)
+            if [ -n "${found_client_lib}" ]; then
+                client_lib_path=$(dirname "${found_client_lib}")
+            fi
+        fi
+
+        # Break early if everything needed is found
+        if [ -n "${include_path}" ] && [ -n "${lib_path}" ] && \
+           { [ -n "${client_include_path}" ] || [ -f "${include_path}/cuopt/status_codes.h" ]; } && \
+           { [ -n "${client_lib_path}" ] || [ -f "${lib_path}/libcuopt_client.so" ]; }; then
             break
         fi
     done
 
-    if [ -z "${include_path}" ] || [ -z "${lib_path}" ]; then
+    local client_include_found=false
+    if [ -n "${client_include_path}" ] || [ -f "${include_path}/cuopt/status_codes.h" ]; then
+        client_include_found=true
+    fi
+    local client_lib_found=false
+    if [ -n "${client_lib_path}" ] || [ -f "${lib_path}/libcuopt_client.so" ]; then
+        client_lib_found=true
+    fi
+
+    if [ -z "${include_path}" ] || [ -z "${lib_path}" ] || \
+       [ "${client_include_found}" = false ] || [ "${client_lib_found}" = false ]; then
         log_failure "Could not find cuOpt headers or libraries"
         if [ -z "${include_path}" ]; then
             log_failure "  Missing: INCLUDE_PATH (searched for cuopt_c.h)"
         fi
         if [ -z "${lib_path}" ]; then
-            log_failure "  Missing: LIBCUOPT_LIBRARY_PATH (searched for libcuopt.so)"
+            log_failure "  Missing: LIBCUOPT_LIBRARY_PATH (searched for libcuopt_mathopt.so)"
+        fi
+        if [ "${client_include_found}" = false ]; then
+            log_failure "  Missing: client include path (searched for status_codes.h)"
+        fi
+        if [ "${client_lib_found}" = false ]; then
+            log_failure "  Missing: client library path (searched for libcuopt_client.so)"
         fi
         return 1
     else
         log_info "Found: INCLUDE_PATH=${include_path}"
         log_info "Found: LIBCUOPT_LIBRARY_PATH=${lib_path}"
+        [ -n "${client_include_path}" ] && log_info "Found: client_include_path=${client_include_path}"
+        [ -n "${client_lib_path}" ] && log_info "Found: client_lib_path=${client_lib_path}"
         return 0
     fi
 }