TheRock/docs/development/hipcc_deprecation.md

hipcc Deprecation Guide

hipcc is a compiler wrapper that historically injected HIP-specific flags (include paths, device library paths, GPU target flags, etc.) before invoking clang++. TheRock is deprecating hipcc in favor of calling amdclang++ directly, which is a symlink to the same underlying clang binary with the HIP toolchain configured by CMake.

This document explains why the change is being made, what the equivalents are, and how to migrate your project.

Why deprecate hipcc?

• Redundant indirection. The amd-hip CMake toolchain already injects --hip-path, --hip-device-lib-path, and all other necessary flags via CMAKE_CXX_FLAGS_INIT. hipcc was doing the same thing via shell script logic, creating two overlapping mechanisms for the same job.
• CMake-native HIP support. CMake has had first-class HIP language support since CMake 3.21. Projects using enable_language(HIP) or set_source_files_properties(... PROPERTIES LANGUAGE HIP) work correctly with CMAKE_HIP_COMPILER pointing to amdclang++ directly — no wrapper needed.
• Transparency. Direct amdclang++ invocations produce cleaner build logs, better IDE integration (via compile_commands.json), and easier debugging of compiler flags.
• hipconfig. hipconfig is the companion introspection tool bundled with hipcc. Callers that used hipconfig --version, --cxxflags, or --ldflags should migrate to CMake-native equivalents (see below).

What changed in TheRock

• The amd-hip compiler toolchain now explicitly sets CMAKE_HIP_COMPILER to amdclang++ (our built clang) in the generated _toolchain.cmake file.
• --rtlib=compiler-rt --unwindlib=libgcc linker flags are now injected via CMAKE_EXE_LINKER_FLAGS_INIT and CMAKE_SHARED_LINKER_FLAGS_INIT, replacing the equivalent flags hipcc provided.
• hipcc is no longer listed as a COMPILER_TOOLCHAIN or RUNTIME_DEPS entry for subprojects that use the amd-hip toolchain.
• The test script test_libhipcxx_hipcc.py has been renamed to test_libhipcxx_amdclang.py and updated to use amdclang++ directly.

Note: The hipcc binary is still built as part of TheRock for now as a compatibility shim. This will be removed in a future PR once all downstream consumers have migrated.

Flag equivalency table

The following table maps hipcc's implicit behavior to the explicit flags or CMake variables that replace it when using amdclang++ directly.

hipcc behavior	amdclang++ / CMake equivalent
Injects -I<hip>/include	--hip-path=<path> (set in CMAKE_CXX_FLAGS_INIT)
Injects --hip-device-lib-path=<path>	--hip-device-lib-path=<path> (set in CMAKE_CXX_FLAGS_INIT)
Sets HIP compiler in CMake	CMAKE_HIP_COMPILER set to amdclang++ in toolchain
Adds --rtlib=compiler-rt --unwindlib=libgcc	Added to CMAKE_EXE_LINKER_FLAGS_INIT and CMAKE_SHARED_LINKER_FLAGS_INIT
Auto-detects GPU targets via rocm_agent_enumerator	AMDGPU_TARGETS / CMAKE_HIP_ARCHITECTURES set by TheRock super-project
Defines -D__HIP_PLATFORM_AMD__	Added by hip-config.cmake target properties via find_package(hip)

Migrating a CMake project

Compiler

Replace any explicit CMAKE_CXX_COMPILER=hipcc with CMAKE_CXX_COMPILER=amdclang++:

# Before
cmake -DCMAKE_CXX_COMPILER=hipcc ...

# After
cmake -DCMAKE_CXX_COMPILER=amdclang++ ...

If your project uses CMake's native HIP language support, set CMAKE_HIP_COMPILER instead of (or in addition to) CMAKE_CXX_COMPILER:

cmake -DCMAKE_HIP_COMPILER=amdclang++ ...

When building inside TheRock, this is handled automatically by the amd-hip toolchain — you do not need to set these manually.

HIP_HIPCC_EXECUTABLE

Some projects (including older versions of libhipcxx) use the HIP_HIPCC_EXECUTABLE CMake variable to locate hipcc. Replace this with the direct path to amdclang++:

# Before
-DHIP_HIPCC_EXECUTABLE=/path/to/rocm/bin/hipcc

# After
# Not needed — use CMAKE_HIP_COMPILER or CMAKE_CXX_COMPILER instead

hipconfig introspection

Projects that called hipconfig to retrieve version or path information should migrate to CMake-native equivalents:

hipconfig invocation	CMake equivalent
hipconfig --version	hip_VERSION (set by find_package(hip REQUIRED))
hipconfig --hip-version	hip_VERSION
hipconfig --cxxflags	Use hip::host and hip::device imported targets
hipconfig --ldflags	Use hip::host and hip::device imported targets
hipconfig --hippath	HIP_PATH environment variable or hip_DIR CMake variable
hipconfig --rocmpath	ROCM_PATH environment variable
hipconfig --compiler	CMAKE_HIP_COMPILER

Example of migrating a version check in CMake:

# Before — calls hipconfig at configure time
find_program(HIPCONFIG_EXEC hipconfig REQUIRED)
execute_process(
  COMMAND ${HIPCONFIG_EXEC} --version
  OUTPUT_VARIABLE HIP_VERSION
  OUTPUT_STRIP_TRAILING_WHITESPACE
)

# After — version already available from find_package
find_package(hip REQUIRED)
set(HIP_VERSION ${hip_VERSION})

Migrating a Makefile or shell-based project

For projects that invoke hipcc directly in a Makefile or shell script, replace it with amdclang++ and add the required flags explicitly:

# Before
hipcc -o my_kernel my_kernel.cpp --offload-arch=gfx1100

# After
amdclang++ \
  --hip-path=${ROCM_PATH} \
  --hip-device-lib-path=${ROCM_PATH}/lib/llvm/amdgcn/bitcode \
  -x hip \
  --offload-arch=gfx1100 \
  -o my_kernel my_kernel.cpp

When using a TheRock build, the --hip-path and --hip-device-lib-path values are available from the toolchain's _toolchain.cmake or from the hip-config.cmake installed in <dist>/lib/cmake/hip/.