build(cmake): split libcuopt into cuopt_client / cuopt_mathopt / cuopt_routing component libs

[ramakrishnap-nv]

Splits libcuopt.so into three component SHARED libraries — cuopt_client, cuopt_mathopt, cuopt_routing — and ships libcuopt.so as a GNU ld script naming them.

Packaging is unchanged: still one libcuopt wheel and one libcuopt conda package. This PR is the prerequisite for the per-solver package split tracked in #1635.

Consumer impact

-lcuopt keeps working, and CMake consumers are unaffected.

libcuopt.so is no longer an ELF object. It is a linker script:

INPUT(libcuopt_mathopt.so libcuopt_routing.so)

This is the mechanism glibc uses for libc.so. It is needed because ld does not resolve a consumer's undefined symbols through a dependency's DT_NEEDED (--no-copy-dt-needed-entries, the default since binutils 2.22), so a thin umbrella library would have forced every C consumer to name the components explicitly. With the script, gcc app.c -lcuopt links exactly as before. cuopt::cuopt is now an INTERFACE target, so find_package(cuopt) and the Cython modules are unchanged. cuopt_client is not named in the script because it arrives through the other components' DT_NEEDED.

Two consequences worth noting:

• dlopen("libcuopt.so") no longer works — load the components instead. load.py does this.
• Anything previously linked against libcuopt.so needs a rebuild, since its DT_NEEDED now names a file that is not ELF.

find_package(cuopt) exposes cuopt::cuopt plus cuopt::routing and cuopt::mathopt.

Components

Sizes are stripped. Every cross-library reference has a matching DT_NEEDED.

Component	Size	Contents	Depends on
cuopt_client	2.4 MB	host problem representation, parsers, wire protocol, LP/MIP and VRP gRPC clients, solve_remote	nothing — leaf, no CUDA
cuopt_routing	26.5 MB	VRP / routing engine	cuopt_client (8 symbols)
cuopt_mathopt	43.8 MB	LP / MIP / QP / SOCP engine, utilities	cuopt_client (206 symbols)

Neither engine has a DT_NEEDED on the other, which is what makes the per-solver package split possible. libcuopt_client.so has no CUDA, rmm or raft in NEEDED and no undefined cuopt:: symbols, so it resolves standalone — that is what makes a GPU-free client install possible (#1872).

Binaries: cuopt_cli needs client and mathopt only (0 routing symbols); cuopt_grpc_server needs all three. #1635 records where each lands.

Components that were tried and removed

Both were dropped after measuring the built libraries rather than reading the CMake.

cuopt_base held shared utilities, on the assumption that both engines resolved process-global singletons from it. libcuopt_mathopt.so referenced 9 symbols from it; routing, grpc, client, cuopt_cli and cuopt_grpc_server referenced none, and routing carried no DT_NEEDED on it at all. Its rationale had also eroded: the logger became header-only per component in #1778, linear algebra moved into cuopt_mathopt after review, and #1809 replaced the process-wide seed generator with per-worker RNGs. Four utility files shipped as a 1 MB library for one caller, so they now build into cuopt_mathopt.

cuopt_grpc held the gRPC bridge. Once #1884 moved the routing arm into cuopt_client, and solve_remote.cpp moved there too, what remained was 18 KB holding one source file: an ELF constructor calling register_remote_solvers. It exported no cuOpt symbols — its 11 dynamic symbols were incidental raft and libstdc++ template instantiations leaked from headers. As a shipped package it would have been a wheel and a conda output containing a constructor and nothing callable.

Remote-solve dispatch, simplified

Review raised that the atomic function pointers, the constructor registration and the dlopen should not be needed. They existed to break a cycle: solve_lp_remote and solve_mip_remote lived in the gRPC component, which depended on math-opt, so math-opt could not call them.

That cycle is gone. Both entry points now live in cuopt_client, which is a leaf, and cuopt_mathopt links it — the dependency is one-way. So both call sites became direct calls, and remote_solve_registry.{hpp,cpp}, grpc_registration.cpp, both std::atomic function pointers, the ready flag, register_remote_solvers and ensure_remote_solvers_loaded are all deleted. Net -163 lines.

The one case the registry handled was a build without gRPC, where the remote entry points do not exist and the null pointer degraded to a runtime error. That is now a compile-time guard on CUOPT_ENABLE_GRPC, with the same error text preserved.

This also removes solve_lp_remote_fn_t and solve_mip_remote_fn_t, which a reviewer asked to unify — there is now no type to unify.

Also in this PR

• WRITE_FATBIN applied fatbin.ld to the umbrella, which held no device code after the split — the section grouping had silently become a no-op. It now applies to the components that carry the fatbins.
• conda prefix_detection.ignore listed only libcuopt.so, which is no longer a binary; it now lists the components.
• The umbrella translation unit and its --as-needed anchor symbols are gone entirely — the linker script makes them unnecessary.
• cuopt_routing referenced 8 symbols from cuopt_client with no DT_NEEDED, resolving only because something else had pulled the client in. A routing-only install would have failed at load; the link is now explicit.

Testing

Full build clean, no undefined references. Remote execution verified end to end against a forked server: CpuOnlyWithServerTest.lp_solve and .mip_solve pass, exercising the new direct dispatch through the C API.

Verified separately: bare -lcuopt links without --allow-shlib-undefined and the resulting binary runs; find_package(cuopt) resolves the targets; load.py loads all components and the C API resolves.

cuopt_client links librmm

libcuopt_client.so links librmm for two symbols it never meaningfully uses: cuda_stream_view's constructor, emitted by static initializers rmm's header creates in every including translation unit for globals the client never names, and device_buffer's destructor, instantiated through the std::variant in linear_programming_ret_t whose GPU alternative the remote client never constructs.

cuopt_client_objs already listed rmm::rmm, but an OBJECT library does not propagate its link interface to a target built from $<TARGET_OBJECTS:...>, so the shared library carried two undefined rmm symbols and no DT_NEEDED. That resolved by accident while libcuopt.so was a real ELF linking rmm; once it became a linker script, a Cython extension loading the client directly failed to import.

This does not reintroduce CUDA: librmm.so is 1.5 MB with no CUDA in its own NEEDED, and its only CUDA-ish dependency is cuda-version, a 21.6 KB metapackage with no files. A GPU-free client install still works. Removing the need entirely is tracked in #1890.

Remote log callback

CpuOnlyWithServerTest.log_callback_remote failed on every conda-cpp-tests config: the remote solve succeeded but no streamed log lines reached the callback. Fixed here, and #1878 closed.

The components are built with hidden visibility, so each got its own copy of the inline thread_local holding the registration. cuOptSetLogCallback lives in cuopt_c.cpp, which builds into cuopt_mathopt, while the remote-solve log forwarding reads it from solve_remote.cpp in cuopt_client — two copies, so the remote path saw no callback. Marking it CUOPT_EXPORT lets the dynamic linker collapse them into one. Registration remains scoped per thread, which is what keeps concurrent solves from capturing each other's callback.

A split-only bug: it passes on a monolithic build, which is why it survived until libcuopt.so became a linker script.

Next steps (#1635)

1. Relink the Cython extension modules — all nine link cuopt::cuopt. Until they link their actual component, every extension pulls the full graph.
2. Per-component install components and header installation — both are monolithic today.
3. Split the wheels and conda recipes — libcuopt-client / -mathopt / -routing plus a libcuopt metapackage, and cuopt-grpc-server for the server binary.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[ramakrishnap-nv]

/ok to test ec81ebc

[ramakrishnap-nv]

@CodeRabbit review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Changes

cuOpt componentized build and remote execution

Layer / File(s)	Summary
Component source aggregation cpp/src/.../CMakeLists.txt	CMake propagates nested source lists and aggregates base, routing, and mathematical-optimization sources.
Component libraries and dependencies cpp/CMakeLists.txt, cpp/cmake/umbrella.cpp.in	Shared component targets, dependencies, umbrella linkage, installation exports, and executable linkage are updated.
Dynamic remote-solver registration cpp/include/.../remote_solve_registry.hpp, cpp/src/grpc/..., cpp/src/pdlp/..., cpp/src/mip_heuristics/solve.cu, cpp/cuopt_cli.cpp	Remote LP and MIP execution uses registered callbacks and loads gRPC on demand.
Distribution and examples ci/*, conda/recipes/libcuopt/recipe.yaml, python/libcuopt/CMakeLists.txt, docs/cuopt/...	Packaging, RPATHs, C example linking, and documentation link checking are updated.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• NVIDIA/cuopt#1625: Both changes update shared-library target construction, linkage, and symbol/export behavior.
• NVIDIA/cuopt#1683: Both changes update CMake source aggregation for the MIP build.

Suggested reviewers: tmckayus, bdice, akifcorduk, aliceb-nv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description directly explains the component-library split, umbrella library behavior, consumer impact, remote-solve changes, packaging, testing, and follow-up work.
Title check	✅ Passed	The title clearly identifies the primary change: splitting libcuopt into client, mathematical-optimization, and routing component libraries.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch feat/split-routing-lp-libs

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/split-routing-lp-libs

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

cpp/CMakeLists.txt (1)

902-918: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Exported component names should match the documented API

cuopt::base / cuopt::lp are build-tree aliases only. The install/export set will expose the real targets (cuopt::cuopt_base, cuopt::cuopt_lp, etc.) unless those targets set EXPORT_NAME, so a consumer using find_package(cuopt) won’t be able to link against cuopt::base as documented.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cpp/CMakeLists.txt` around lines 902 - 918, Update the component target
export configuration used by the rapids_export INSTALL and BUILD calls so
installed targets retain the documented names cuopt::base, cuopt::routing,
cuopt::lp, and cuopt::grpc. Set the appropriate EXPORT_NAME values on the
underlying cuopt_component targets, while preserving cuopt::cuopt as the
umbrella target and keeping build-tree aliases consistent.

🧹 Nitpick comments (2)

cpp/CMakeLists.txt (2)

549-556: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Give the git hash lookup a fallback for non-git source trees.

Without RESULT_VARIABLE/ERROR_QUIET, tarball builds leak git's error to the configure log and bake an empty hash into build_info.hpp.

♻️ Proposed fallback

 execute_process(
         COMMAND git rev-parse --short HEAD
         WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
         OUTPUT_VARIABLE GIT_COMMIT_HASH
         OUTPUT_STRIP_TRAILING_WHITESPACE
+        RESULT_VARIABLE _git_hash_result
+        ERROR_QUIET
 )
+if(NOT _git_hash_result EQUAL 0 OR GIT_COMMIT_HASH STREQUAL "")
+    set(GIT_COMMIT_HASH "unknown")
+endif()

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cpp/CMakeLists.txt` around lines 549 - 556, Update the git hash lookup in the
top-level CMake configuration to capture the execute_process result and suppress
stderr for source trees without Git metadata. When the lookup fails, assign a
stable non-empty fallback hash before the existing GIT_COMMIT_HASH message and
build_info.hpp generation; preserve the real short HEAD value for Git checkouts.

---

664-675: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoff

cuopt_objs duplicates the component include/definition setup.

The object library re-declares papilo/pslp/dejavu includes, CUDSS defines, and architecture defines that cuopt_configure_component (plus cuopt_lp) already establish. Since cuopt_objs backs cuopt_static for the test builds, drift here means tests compile under a different configuration than shipped libraries. Consider factoring the shared include/definition block into a helper both paths call.

Also applies to: 693-694, 720-724

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cpp/CMakeLists.txt` around lines 664 - 675, Refactor the shared include
directories and compile definitions currently duplicated by cuopt_objs and the
cuopt_configure_component/cuopt_lp setup into a reusable CMake helper. Invoke
that helper for both cuopt_objs and the shipped-library path, including the
papilo/pslp/dejavu includes, CUDSS definitions, and architecture definitions,
while preserving target-specific settings such as POSITION_INDEPENDENT_CODE and
logging definitions.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@cpp/CMakeLists.txt`:
- Around line 902-918: Update the component target export configuration used by
the rapids_export INSTALL and BUILD calls so installed targets retain the
documented names cuopt::base, cuopt::routing, cuopt::lp, and cuopt::grpc. Set
the appropriate EXPORT_NAME values on the underlying cuopt_component targets,
while preserving cuopt::cuopt as the umbrella target and keeping build-tree
aliases consistent.

---

Nitpick comments:
In `@cpp/CMakeLists.txt`:
- Around line 549-556: Update the git hash lookup in the top-level CMake
configuration to capture the execute_process result and suppress stderr for
source trees without Git metadata. When the lookup fails, assign a stable
non-empty fallback hash before the existing GIT_COMMIT_HASH message and
build_info.hpp generation; preserve the real short HEAD value for Git checkouts.
- Around line 664-675: Refactor the shared include directories and compile
definitions currently duplicated by cuopt_objs and the
cuopt_configure_component/cuopt_lp setup into a reusable CMake helper. Invoke
that helper for both cuopt_objs and the shipped-library path, including the
papilo/pslp/dejavu includes, CUDSS definitions, and architecture definitions,
while preserving target-specific settings such as POSITION_INDEPENDENT_CODE and
logging definitions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 2d788dd1-855a-4038-900e-9a3eab8f07be

📥 Commits

Reviewing files that changed from the base of the PR and between 91134a2 and ec81ebc.

📒 Files selected for processing (13)

• conda/recipes/libcuopt/recipe.yaml
• cpp/CMakeLists.txt
• cpp/src/CMakeLists.txt
• cpp/src/barrier/CMakeLists.txt
• cpp/src/branch_and_bound/CMakeLists.txt
• cpp/src/cuts/CMakeLists.txt
• cpp/src/dual_simplex/CMakeLists.txt
• cpp/src/io/CMakeLists.txt
• cpp/src/linear_algebra/CMakeLists.txt
• cpp/src/math_optimization/CMakeLists.txt
• cpp/src/mip_heuristics/CMakeLists.txt
• cpp/src/pdlp/CMakeLists.txt
• cpp/src/routing/CMakeLists.txt

[ramakrishnap-nv]

/ok to test a54e62a

[github-actions]

CI Test Summary

✅ All 31 test job(s) passed.

[ramakrishnap-nv]

/ok to test 705167f

[ramakrishnap-nv]

/ok to test 1bc38f7

[ramakrishnap-nv]

/ok to test 8511bd0

[ramakrishnap-nv]

/ok to test

[ramakrishnap-nv]

/ok to test

[ramakrishnap-nv]

/ok to test

[ramakrishnap-nv]

/ok to test

[ramakrishnap-nv]

/ok to test

[ramakrishnap-nv]

/ok to test