cudaPackages: introduce cudaLib and switch from backendStdenv to cudaStdenv

[ConnorBaker]

Important

Introduction of cudaLib has been split into #406531. This PR is closed as discussions about goals and implementation details of cudaStdenv need to happen first.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 25.05 Release Notes (or backporting 24.11 and 25.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[SomeoneSerge]

1. IMO we should reserve the name cudaStdenv for when it's actually sufficient to build a package with CUDA support. The reason backendStdenv was not named that is because it isn't a "cuda stdenv". Let's brainstorm what's missing: having to simultaneously add nvcc and cudart (and the custom stdenv) is one part of the puzzle
2. I think we should make as many of the helpers we have "private" as we can: this applies to most of the content of cudaFlags (flags? let's delete one of these too) and I think should apply to cudaLib. By "making private" I mean changing the names to begin with __ and documenting them as private (subject to change, including in a backport) in the manual. EDIT: I see now you're not introducing it into the attribute tree yet, so it's not a concern I suppose?

[ConnorBaker]

1. IMO we should reserve the name cudaStdenv for when it's actually sufficient to build a package with CUDA support. The reason backendStdenv was not named that is because it isn't a "cuda stdenv". Let's brainstorm what's missing: having to simultaneously add nvcc and cudart (and the custom stdenv) is one part of the puzzle

Fair point -- I'm thinking:

{
  # NVCC is required to compile CUDA code.
  nativeBuildInputs = [ cuda_nvcc ];
  # The CUDA runtime is required by most CUDA applications and depends on the headers
  # provided by CCCL.
  buildInputs =
    [
      cuda_cudart
      cuda_cccl
    ]
    # CUDA compat is included when non-null and available on the host platform.
    ++ lib.optionals (cuda_compat != null && lib.availableOn stdenv.hostPlatform cuda_compat) [
      cuda_compat
    ];
}

2. I think we should make as many of the helpers we have "private" as we can: this applies to most of the content of cudaFlags (flags? let's delete one of these too) and I think should apply to cudaLib. By "making private" I mean changing the names to begin with __ and documenting them as private (subject to change, including in a backport) in the manual.

My intention with introducing cudaLib was to create a centralized library of functions and data necessary to create, modify, or extend CUDA package sets, both to float out commonalities in our packaging in-tree and to enable out-of-tree users to make use of our tooling without needing to vendor or duplicate a bunch of stuff we don't otherwise expose. I'm not opposed to making some of them private (or migrating them to lib proper), but I feel that doing that for the majority would be counter to what I want for cudaLib. Does that make sense, and or do you have thoughts on how to expose a minimal public interface which still allows for re-use?

On the topic of flags, I've had a TODO hanging around for a while to remove cudaFlags -- do you have a preference for one name over the other? I like flags because it's short, but cudaFlags makes it more clear what it is in cases where it's inherited in package expressions outside of the cudaPackages scope. In the same vein, I'm supposing we'd call our standard environment cudaStdenv and not just stdenv. On the other hand, having the cuda prefix within the cudaPackages scope feels repetitive... but at least you know which scope it's coming from!

[SomeoneSerge]

Fair point -- I'm thinking:

Ja-ja, are we brainstorming already? Great. Here come some more considerations. **Minor**: - I'd move `propagatedBuildInputs = [ setupCudaHook ]` from NVCC to `*Stdenv` (unless cf. **Major**) - It must be possible  to use `*Stdenv` with NVC++ and Clang instead of NVCC **Major** This is in response to

In the same vein, I'm supposing we'd call our standard environment

|cudaStdenv| and not just |stdenv| - The difference I anticipate for `backendStdenv` and `cudaPackages.stdenv` is that the latter should be fit for using in Nixpkgs' `overrideStdenv` and should treat `cuda{Support,Capabilities` as part of the `hostPlatform`:   - Rebuilding something non-CUDA, like `chromium`, with `cudaPackages.stdenv` should not trigger a rebuild (i.e. overlay reduces to a no-op and uses the modern stdenv's tools, libs, and hooks)   - Building a real CUDA package, like `torch` and it must have a way to signal it "can be built with CUDA support" (NVCC in nativeBuildInputs? Maybe, I don't like this), enforces the compatible stdenv, prevents lib{c,stdc++} leakages, and adds NVCC & CUDA hooks.   - `cudaPackages.stdenv.cudaSupport` can be used to test whether the platform we're building for "supports CUDA" at all; it can be used instead of `{ config, cudaSupport ? config.cudaSupport }` to test for "what's hypothetically supported" (this somehow needs to be disentangled from "whether the _current_package is requested to be built with CUDA kernels on") Onto `cudaLib`.

a centralized library of functions and data necessary to create,

modify, or extend CUDA package sets :+1: I was thinking along the same lines (would you like some `libcudb.nix`?), I'm surely pro-change. But this time I want to clearly disclaim liabilities

I like |flags| because it's short, but |cudaFlags| makes it more

clear what it is in cases where it's inherited in package expressions outside of the |cudaPackages| scope My vote is definitely `flags`: if we inherit outside the scope we can choose a longer local name.

[ConnorBaker]

Excellent points!

In terms of moving this PR forward, is it acceptable to you if:

1. I keep the name of backendStdenv instead of renaming it to cudaStdenv (all the additional attributes would remain as needed for further refactors)
2. I update the names and documentation of the functions in cudaLib.utils to indicate there are no stability guarantees (I'm thinking a single underscore, as double-underscore seems to be mostly used by Nix)
3. I do a tree-wide refactor to remove cudaFlags and replace it with flags

I want to have a further discussion with you about the implementation of a cudaStdenv with the properties you've outlined above, but I think that will be a longer series of discussions and I don't want to hold up landing fixes for package set leakage and introduction of pkgsCuda.

[SomeoneSerge]

single underscore Seems like you're right. tree-wide cudaFlags -> flags Separate PR to avoid extra yak-shaving? I think that will be a longer series of discussions Safe to assume so 👍 expose ... minimal functionality to ... create, modify, or extend CUDA package sets I didn't comment on this part - exactly my concern right now too! The artifact I was hoping to introduce at the top-level is something like a "cuda (metadata) database", which could be re-instatiated with a different set of manifests, and a function approx. of the form `DB -> VersionConstraints -> List Extension -> CudaPackageSet`

On 12/05/2025 17.07, Connor Baker wrote: ConnorBaker left a comment (NixOS/nixpkgs#405751) Excellent points! In terms of moving this PR forward, is it acceptable to you if: 1. I keep the name of `backendStdenv` instead of renaming it to `cudaStdenv` (all the additional attributes would remain as needed for further refactors) 2. I update the names and documentation of the functions in `cudaLib.utils` to indicate there are no stability guarantees (I'm thinking a single underscore, as double-underscore seems to be mostly used by Nix) 3. I do a tree-wide refactor to remove `cudaFlags` and replace it with `flags` I want to have a further discussion with you about the implementation of a `cudaStdenv` with the properties you've outlined above, but I think that will be a longer series of discussions and I don't want to hold up landing fixes for package set leakage and introduction of `pkgsCuda`.

-- SomeoneSerge <https://someonex.net>

[ConnorBaker]

Introduction of cudaLib has been split into #406531. This PR is closed as discussions about goals and implementation details of cudaStdenv need to happen first.