Add NVCC inability to compile .hip files notice and workaround

[jamesxu2]

This docs change serves to clarify an error encountered when attempting to compile .hip files with nvcc, through hipcc.

e.g: As encountered by user in #3582

[jamesxu2]

This will probably need to be consolidated around a separate FAQ-rewrite PR, once that gets merged: #3596

[MKKnorr]

I wouldn't immediately tell the user to rename their files as a solution to this.

• HIP specifically provides hipcc as a wrapper around nvcc and amdclang++ to avoid these problems, so using hipcc would be one solution to this (even if that might not be desired by everyone, as hipcc also has some weird default settings)
• If that's not desired, the file extension does not have to be renamed, that sounds more like a last resort. nvcc provides an option like almost every other compiler to specify the language of the file to be compiled (https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#x-c-c-cu-x)
  • specifying cu is most likely going to be the safe bet, as that allows c++ and hip/cuda code, whereas c++ does not allow hip/cuda code afaik

[jamesxu2]

Okay, I see that I should have been more explicit that this is a hipcc issue. The reason for this amendment is that while hipcc will alias hip* functions to cu* functions, it does not affect the file extension and passes it through to nvcc, resulting in an ambiguous error.

I will do some research to see if that compiler flag (--xcu/--xc++) can be passed through the hipcc interface to nvcc, as an alternative to file renaming. I agree that is a better option.

Here is an example of what a user might encounter attempting to compile a .HIP file with hipcc:

HIP_PLATFORM=nvidia hipcc main.hip -o hello
nvcc fatal   : Don't know what to do with 'main.hip'    <--- this error message thrown by nvcc is ambiguous


[from debug log. Notice that nvcc is invoked with the main.hip source file as input.]
failed to [execute:/usr/local/cuda/bin/nvcc](http://execute/usr/local/cuda/bin/nvcc)  -Wno-deprecated-gpu-targets  -isystem /usr/local/cuda/include -isystem "/opt/rocm-6.2.0/include"  -Wno-deprecated-gpu-targets -lcuda -lcudart -L/usr/local/cuda/lib64  main.hip -o "hello"

[yxsamliu]

agree that --xcu seems to be viable solution

[jamesxu2]

Just did some testing, I confirm that we can pass -x cu or --x cu to nvcc through hipcc and nvcc is able to compile the .hip program.

Eg. This works: HIP_PLATFORM=nvidia hipcc hello.hip -o hello -x cu

Also, a sidenote: -xcu and --xcu are not parsed correctly by nvcc and result in
nvcc fatal : Unknown option '[-]-xcu'. This is a bit different than hipcc to amdclang++ which can parse -xhip properly by splitting the single character x flag from its argument.

I will amend this doc change and clarify that it pertains to the HIP_PLATFORM=nvidia hipcc usecase.

[jamesxu2]

@MKKnorr I have revised this change per @yxsamliu's and your comments. It has also been rebased to docs/develop instead of amd-staging to account for the moved how-to/faq.md to root/faq.rst.