Make {Program,Linker}Options.as_bytes a public API with backend-specific option handling

[leofang]

Description

Close #1327.
Close #1341.

This pull request refactors the way linker options are handled in the CUDA core experimental linker module, improving code organization and maintainability. The main change is the replacement of the formatted_options and option_keys attributes with dedicated methods for preparing options for different backends. Additionally, new program options are documented, and logging access is improved.

Refactoring and Backend Separation:

• Refactored the LinkerOptions class to use _prepare_nvjitlink_options and _prepare_driver_options methods for constructing options, instead of maintaining formatted_options and option_keys as persistent attributes. This makes the code cleaner and backend-specific logic more explicit. [1] [2] [3]
• Added the as_bytes method to LinkerOptions to provide a backend-specific way to get encoded options, with validation and error handling for backend selection.

Linker Initialization and Logging Improvements:

• Updated the Linker class to use the new option preparation methods during initialization, storing the options in the _MembersNeededForFinalize structure for later access (e.g., for logs), and ensuring correct log buffer usage for both backends. [1] [2] [3] [4]

Program Options Documentation:

• Expanded the documentation for ProgramOptions to include several new options related to compiler caching, time tracing, random seeds, fast compilation modes, and precompiled header (PCH) support for NVRTC, improving clarity for users.

Minor Code Maintenance:

• Added a missing import for CUDAError in _program.py to ensure error handling consistency.

Checklist

• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[leofang]

pre-commit.ci autofix

[leofang]

/ok to test 7b1ecbb

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-1355/
https://nvidia.github.io/cuda-python/pr-preview/pr-1355/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-1355/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-1355/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[mdboom]

Why is this as_bytes and not as_str? I understand the underlying C++ code probably disallows anything that isn't 7-bit ASCII, but bytes in Python are really intended for binary encoded things, not text like this. You can see even in these tests how that makes the code more cumbersome than it needs to be (explicitly decoding the result in order to use it).

Is this just backward compatibility? Maybe then we have to_str and a to_bytes that simply calls to_str and encodes the result, and then mark to_bytes as deprecated...

[leofang]

Python users don't need any of these. We already take good care of them. Also _as_bytes is currently a private API, so there is no concern in breaking it.

This API is needed by cccl-python because they want to pass it to the C level. Give them a list of bytes is appropriate because they can then do a zero-copy conversion to char* via Cython and pass it to C. NVIDIA/cccl#6873 and #1327 have the full context.

[leofang]

/ok to test 15f4b6a