build(wheel): split libcuopt into per-component wheels

[ramakrishnap-nv]

Adds a wheel per component, using the install components from #1926 via scikit-build-core's install.components.

Wheel	Contents	Dependencies beyond rmm / rapids-logger
libcuopt-client	libcuopt_client.so	none — no CUDA wheels at all
libcuopt-mathopt	libcuopt_mathopt.so, cuopt_cli	cuda-toolkit, cudss, nccl, nvjitlink
libcuopt-routing	libcuopt_routing.so	cuda-toolkit[cublas,cudart] only
libcuopt	ld script, cuopt_grpc_server	depends on the three above

A routing-only install no longer pulls cudss, nccl or nvjitlink. Dependencies were split from each library's measured DT_NEEDED rather than by dividing the existing list.

libcuopt no longer bundles the libraries; it depends on them, and its load_library delegates to the component packages, client first since mathopt and routing both have a DT_NEEDED on it. pip install libcuopt is unchanged for users.

Also folds in the CMake export restructure that was #1963: each component gets its own export set, since CMake will not export a target that references targets outside its own export set, and a single umbrella export left every component's targets file computing the wrong _IMPORT_PREFIX. The installed config rebuilds the umbrella's links from whichever components are present. The two changes only work together -- without it the component wheels cannot resolve each other -- so they are reviewed as one.

Each wheel configures the whole C++ tree, so this trades CI build time for install size, with sccache absorbing the repeats. Building once and packaging three times would need build_wheel.sh restructured — worth doing separately if the cost shows up.

🤖 Generated with Claude Code

[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.

[github-actions]

CI Test Summary

✅ All 32 test job(s) passed.

[Iroy30]

Do we have tests for individual components?

These are the Agent reviewed concerns:

1. cuopt_cli can't start from a standalone libcuopt-mathopt install. The CLI installs with COMPONENT mathopt (cpp/CMakeLists.txt:1499), so it's in the wheel, and libcuopt-mathopt declares the console script. But cuopt_cli links cuopt_client directly (cpp/CMakeLists.txt:1482-1487, explicitly, because --no-copy-dt-needed-entries won't let it reach client through mathopt), libcuopt_client.so is excluded from vendoring, and commit 2335024 removed $ORIGIN/../../libcuopt_client/lib64 from the RPATH list. The justification there — load_library() loads the client first, so glibc satisfies the DT_NEEDED from an already-loaded object — is correct for import libcuopt_mathopt, but cuopt_cli is a native binary with DT_RUNPATH and no Python in the process. It should fail with libcuopt_client.so: cannot open shared object file. Restoring the sibling entry for the executables would fix it; either way the check is pip install libcuopt-mathopt && cuopt_cli --help in a clean container.

2. libcudss_mtlayer_cuopt.so is missing from the mathopt wheel. All four build scripts set CUOPT_BUILD_CUSTOM_CUDSS_MTLAYER=ON, and that target installs with COMPONENT runtime (cpp/CMakeLists.txt:1287-1292), while the wheel stages only mathopt and mathopt-dev. With the custom layer built, CUDSS_MT_LIB_FILE_NAME is the bare soname rather than the full path, resolved against the calling object's RUNPATH — which works in libcuopt where the file sits beside libcuopt_mathopt.so in lib64, and not in the split wheel where it's absent. Either add runtime to install.components or move the target to COMPONENT mathopt

[ramakrishnap-nv]

Both concerns are real. Checked them against the built artifacts rather than the intent, and fixed both in 0bea735.

1. cuopt_cli and libcuopt_client.so — confirmed.

$ objdump -p cpp/build/cuopt_cli | grep NEEDED
  NEEDED  libcuopt_mathopt.so
  NEEDED  libcuopt_client.so     <-- direct, as you said

libcuopt_client.so is in --exclude for the mathopt wheel (ci/build_wheel_libcuopt_mathopt.sh:112), and the wheel RPATH list has no sibling entry after 2335024, so $ORIGIN/../lib64 resolves only libcuopt_mathopt.so. Your reading of that commit is right: preloading via load_library() covers the libraries, not a native binary.

Fixed by restoring the sibling entries for the executables only, leaving the libraries as 2335024 left them — the distinction being whether there is a Python interpreter in the process.

2. libcudss_mtlayer_cuopt.so — confirmed, and wider than the wheel.

COMPONENT runtime is staged by nothing: not the three component wheels, and not conda either, where every output installs by name (--component client, mathopt, ...). So it was already missing from the conda packages on main; the split only extended that to the wheels.

Worth noting the failure mode is graceful, not fatal — sparse_cholesky.cuh:288 logs "could not pin ..." and drops to single-threaded cuDSS. A silent performance regression, which is why nothing caught it.

Moved to COMPONENT mathopt rather than adding runtime to the wheel's list, since the barrier solver is its only consumer, and that fixes the wheel and conda together. Verified:

$ cmake --install . --component mathopt --prefix /tmp/mtprefix
bin/cuopt_cli
lib/libcudss_mtlayer_cuopt.so   <-- now present, beside its loader
lib/libcuopt_mathopt.so

On tests for individual components — partly, and the gap is exactly where these two slipped through.

conda has a per-output isolation test: each loads its own .so with RTLD_NOW in an environment holding only that package's dependencies, which is what catches an unsatisfied DT_NEEDED.

The wheels have nothing. They are built and published but never installed or imported in CI, and no test runs cuopt_cli as an executable in either packaging. Both fixes above are therefore unguarded against regression — I have confirmed #2 by installing the component, but #1's real check is the one you named, pip install libcuopt-mathopt && cuopt_cli --help in a clean container, and there is no job that does it.

Happy to add a wheel smoke-test job here — install each component wheel in a clean env, ctypes.CDLL each library, run cuopt_cli --help — or to file it as a follow-up if you would rather not grow this PR. Which do you prefer?

[Iroy30]

thanks for addressing the reviews!

[ramakrishnap-nv]

Correct, and it's a regression. Fixed in e85ad59.

A consumer against the build tree got cuopt_FOUND=1, cuopt::cuopt defined, no components, and empty INTERFACE_LINK_LIBRARIES -- so it failed at link time, not configure time.

It worked before this PR: the components were all in cuopt-exports, the set rapids_export(BUILD) writes. Splitting them out left that set holding only the umbrella.

Fix is an export(EXPORT ...) beside each install(EXPORT ...). Both trees now report cuopt::cuopt links = 'cuopt::client;cuopt::mathopt;cuopt::routing'; the install path is unchanged, only an added call.

[ramakrishnap-nv]

/merge