build(cython): link each extension module against the component it uses

cpp/CMakeLists.txt

@@ -1253,11 +1253,27 @@ It pulls both solver engines whether or not you use them, so prefer a component
 
 ]=])
 
+# cuopt::client exists in every configuration, but only carries the gRPC client when
+# SKIP_GRPC_BUILD was off, so its presence alone tells a consumer nothing. Export the
+# answer: the Python bindings use it to skip the gRPC extension module, which would
+# otherwise fail to link against a client built without that arm.
+# CUOPT_HAS_GRPC_ROUTING is reported separately rather than inferred from cuopt::routing:
+# it is CUOPT_ENABLE_GRPC_ROUTING that gates cython_grpc_client_vrp.cpp, and the two would
+# diverge the moment the VRP arm gains an option of its own.
+if(SKIP_GRPC_BUILD)
+    set(cuopt_code_string "set(CUOPT_HAS_GRPC OFF)\nset(CUOPT_HAS_GRPC_ROUTING OFF)")
+elseif(CUOPT_ENABLE_GRPC_ROUTING)
+    set(cuopt_code_string "set(CUOPT_HAS_GRPC ON)\nset(CUOPT_HAS_GRPC_ROUTING ON)")
+else()
+    set(cuopt_code_string "set(CUOPT_HAS_GRPC ON)\nset(CUOPT_HAS_GRPC_ROUTING OFF)")
+endif()
+
 rapids_export(INSTALL cuopt
         EXPORT_SET cuopt-exports
         GLOBAL_TARGETS cuopt ${CUOPT_COMPONENT_EXPORT_NAMES}
         NAMESPACE cuopt::
         DOCUMENTATION doc_string
+        FINAL_CODE_BLOCK cuopt_code_string
 )
 
 # ###############################################################################################
@@ -1267,6 +1283,7 @@ rapids_export(BUILD cuopt
         GLOBAL_TARGETS cuopt ${CUOPT_COMPONENT_EXPORT_NAMES}
         NAMESPACE cuopt::
         DOCUMENTATION doc_string
+        FINAL_CODE_BLOCK cuopt_code_string
 )
 
 # ##################################################################################################

python/cuopt/cuopt/CMakeLists.txt

@@ -3,15 +3,34 @@
 # SPDX-License-Identifier: Apache-2.0
 # cmake-format: on
 
-add_subdirectory(distance_engine)
 add_subdirectory(linear_programming/data_model)
 add_subdirectory(linear_programming/io)
 add_subdirectory(linear_programming/solver)
 add_subdirectory(linear_programming/solver_settings)
-add_subdirectory(grpc)
+# The gRPC extension wraps cython_grpc_client, which is only compiled into cuopt::client
+# when SKIP_GRPC_BUILD is off. The target exists either way, so ask the exported flags.
+# It needs the VRP arm too: one module covers both, and it calls submit_vrp/result_vrp,
+# which live in cython_grpc_client_vrp.cpp and are dropped with the routing engine.
+if(CUOPT_HAS_GRPC AND CUOPT_HAS_GRPC_ROUTING)
+    add_subdirectory(grpc)
+else()
+    message(STATUS "cuOpt built without gRPC or without its VRP arm -- skipping the gRPC client extension module")
+endif()
 
-add_subdirectory(routing)
+# These two link cuopt::routing, which a SKIP_ROUTING_BUILD install does not provide.
+# Tested on the found package rather than on SKIP_ROUTING_BUILD: this build only does
+# find_package(cuopt) and never sees that option, so the variable would be empty here
+# and the guard would always pass.
+if(TARGET cuopt::routing)
+    add_subdirectory(distance_engine)
+    add_subdirectory(routing)
+else()
+    message(STATUS "cuopt::routing not found -- skipping the routing and distance_engine extension modules")
+endif()
 
+# No sources here -- every extension module is created in a subdirectory, and each links
+# the component it actually resolves symbols from. Anything added here would link the
+# cuopt umbrella and pull in both engines, so add it to the owning subdirectory instead.
 set(cython_sources)
 set(linked_libraries cuopt::cuopt)
 

python/cuopt/cuopt/distance_engine/CMakeLists.txt

@@ -1,10 +1,10 @@
 # cmake-format: off
-# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2023-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 # cmake-format: on
 
 set(cython_sources waypoint_matrix_wrapper.pyx)
-set(linked_libraries cuopt::cuopt)
+set(linked_libraries cuopt::routing)
 
 rapids_cython_create_modules(SOURCE_FILES "${cython_sources}" LINKED_LIBRARIES "${linked_libraries}" ASSOCIATED_TARGETS cuopt
                                                                                CXX)

python/cuopt/cuopt/grpc/client/CMakeLists.txt

@@ -7,7 +7,7 @@
 # unit: they wrap the same C++ client object, and keeping them together lets the
 # client be detached from the engines as a single package later.
 set(cython_sources grpc_client.pyx)
-set(linked_libraries cuopt::cuopt)
+set(linked_libraries cuopt::client)
 
 rapids_cython_create_modules(
   CXX

python/cuopt/cuopt/linear_programming/data_model/CMakeLists.txt

@@ -4,7 +4,7 @@
 # cmake-format: on
 
 set(cython_sources data_model_wrapper.pyx)
-set(linked_libraries cuopt::cuopt)
+set(linked_libraries cuopt::mathopt cuopt::client)
 
 rapids_cython_create_modules(SOURCE_FILES "${cython_sources}" LINKED_LIBRARIES "${linked_libraries}" ASSOCIATED_TARGETS cuopt
                                                                                CXX)

python/cuopt/cuopt/linear_programming/internals/CMakeLists.txt

@@ -1,10 +1,13 @@
 # cmake-format: off
-# SPDX-FileCopyrightText: Copyright (c) 2022-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2022-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 # cmake-format: on
 
 set(cython_sources internals.pyx)
-set(linked_libraries cuopt::cuopt)
+# internals resolves no cuOpt symbols at all -- it is callback plumbing -- but still
+# needs the public headers, which arrive through the target interface. The client is the
+# leaf, so this gives headers without pulling in an engine.
+set(linked_libraries cuopt::client)
 rapids_cython_create_modules(
   CXX
   SOURCE_FILES "${cython_sources}"

python/cuopt/cuopt/linear_programming/io/CMakeLists.txt

@@ -1,10 +1,10 @@
 # cmake-format: off
-# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 # cmake-format: on
 
 set(cython_sources parser_wrapper.pyx)
-set(linked_libraries cuopt::cuopt)
+set(linked_libraries cuopt::client)
 
 rapids_cython_create_modules(SOURCE_FILES "${cython_sources}" LINKED_LIBRARIES "${linked_libraries}" ASSOCIATED_TARGETS cuopt
                                                                                CXX)

python/cuopt/cuopt/linear_programming/solver/CMakeLists.txt

@@ -4,7 +4,7 @@
 # cmake-format: on
 
 set(cython_sources solver_wrapper.pyx)
-set(linked_libraries cuopt::cuopt)
+set(linked_libraries cuopt::mathopt cuopt::client)
 
 rapids_cython_create_modules(SOURCE_FILES "${cython_sources}" LINKED_LIBRARIES "${linked_libraries}" ASSOCIATED_TARGETS cuopt
                                                                                CXX)

python/cuopt/cuopt/linear_programming/solver_settings/CMakeLists.txt

@@ -4,7 +4,7 @@
 # cmake-format: on
 
 set(cython_sources solver_settings.pyx)
-set(linked_libraries cuopt::cuopt)
+set(linked_libraries cuopt::mathopt cuopt::client)
 
 rapids_cython_create_modules(SOURCE_FILES "${cython_sources}" LINKED_LIBRARIES "${linked_libraries}" ASSOCIATED_TARGETS cuopt
                                                                                CXX)

python/cuopt/cuopt/routing/CMakeLists.txt

@@ -1,10 +1,10 @@
 # cmake-format: off
-# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2023-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 # cmake-format: on
 
 set(cython_sources vehicle_routing_wrapper.pyx utils_wrapper.pyx)
-set(linked_libraries cuopt::cuopt)
+set(linked_libraries cuopt::routing cuopt::client)
 
 rapids_cython_create_modules(SOURCE_FILES "${cython_sources}" LINKED_LIBRARIES "${linked_libraries}" ASSOCIATED_TARGETS cuopt
                                                                                CXX)