[DOC]: Document relevant CCCL macros

fbusato commented 1 month ago

Is this a duplicate?

[x] I confirmed there appear to be no duplicate issues for this bug and that I agree to the Code of Conduct

Is this for new documentation, or an update to existing docs?

New

Describe the incorrect/future/missing documentation

CCCL macros are very curated and are tested across many configurations in all projects that adopt CCCL. Some examples:

host/device: _CCCL_HOST_DEVICE
standard attributes: _CCCL_FALLTHROUGH, _CCCL_NODISCARD
compiler macros: _CCCL_CUDA_COMPILER
buildins: _CCCL_HAS_BUILTIN
dialects: _CCCL_STD_VER,
etc.

These macros can be documented and exposed to users

If this is a correction, please provide a link to the incorrect documentation. If this is a new documentation request, please link to where you have looked.

https://nvidia.github.io/cccl/libcudacxx/extended_api/macro.html

miscco commented 1 month ago

That is a hard no.

Exposing those macros to users prevents us from ever changing them again if need be. We recently spend a lot of time cleaning up our internal infrastructure and its been a pain to have to ensure backwards compatibility with publicly exposed Thrust and CUB macros.

fbusato commented 1 month ago

that's true, backwards compatibility is problematic. However, we should at least list these macros (or a subset of them) somewhere. As an external user, I would prefer taking the risk even if internal only instead of reimplementing many of them, at least initially...

miscco commented 1 month ago

That is not how it works. The moment we list something user will use that and complain if it fails.

jrhemstad commented 1 month ago

These macros should be documented in a Developer Guide. That is not the same as making them part of the public API.

bernhardmgruber commented 3 weeks ago

I agree with @jrhemstad. It would also help me as a CCCL developer to have a list of those macros in a guide intended only for CCCL developers.

NVIDIA / cccl