[HIPIFY][feature] Implicit hipification of local header files - Part 1 by ranapratap55 · Pull Request #2402 · ROCm/HIPIFY

ranapratap55 · 2026-02-23T09:33:45Z

Problem Statement

hipify-clang currently only transforms the main source file passed as input. Local (quoted) headers included in the main file remain same as CUDA code. These headers often cannot be hipified individually because they are not self-contained headers which requires types, operators, and definitions from preceding includes in the parent source.

Example: dxtc.cu includes CudaMath.h, which uses float3 operators (+=, *, -) defined in helper_math.h. Hipifying CudaMath.h alone fails because these operators are unavailable. Similar cases:

Purpose

When hipify-clang sample.cu is run, the tool now implicitly detects and hipifies all local headers. No additional flags required.

#2402 (comment)

Implement the ability to implicitly hipify all header files that are included in the main file.

This redesign is based on feedback from #2275 and earlier iterations of this PR(#2402):

Implicit by default: no --local-headers / --local-headers-recursive flags
Single opt-out: --skip-local-headers when header processing is not desired

With #2349, we addressed nvcc's implicit cuda_runtime.h. Now, with this PR(#2402) we are implicitly transforming project-level header dependencies.

Solution

Local quoted headers hipified automatically, no flags needed.
hipify-clang sample.cu -I ../../../Common/

Skip header processing if not desired
hipify-clang --skip-local-headers sample.cu -I ../../../Common/

Supersedes #2275

Summary of changes in this PR

Local header hipification is now implicit by default. hipify-clang sample.cu automatically detects and hipifies all local headers recursively, no flags needed. Added --skip-local-headers as the single opt-out mechanism.

ToDo work (follow-up PRs):

Warning for non-self-contained headers: Warn (besides compiler’s error messaging) the user about imposibility to hipify a header file, which is not self-contained.
Folder-level hipification: Hipify everything in the provided folder.

emankov · 2026-02-24T14:42:39Z

Can we say that the main purpose of this PR is to allow hipifying header files individually as main translation units?

ranapratap55 · 2026-02-25T06:08:55Z

Can we say that the main purpose of this PR is to allow hipifying header files individually as main translation units?

Yes, correct. The main purpose is to allow hipifying local header files as main translation units. We are doing it by injecting their preceding includes from the parent source file using Clang's -include ArgumentsAdjusters which is to provide the necessary compilation context.

This feature is enabled via --local-headers / --local-headers-recursive and only applies to local (quoted) headers referenced in the main source file.

emankov · 2026-02-25T18:18:07Z

the parent source

How do we guarantee finding the parent source(s) for a particular header file so we can hipify it as the main translation unit?

ranapratap55 · 2026-02-26T06:01:58Z

the parent source

How do we guarantee finding the parent source(s) for a particular header file so we can hipify it as the main translation unit?

We don't need to discover/guess the parent source file. The user provides it explicitly while hipifying. The main source file passed to hipify-clang is always the parent. --local-headers simply extends hipification to that source file's local headers, using the source file itself as the context for preceding includes.

For example: hipify-clang --local-headers sample.cu: here sample.cu is known parent for its local headers (header1.h, header2.h, etc.,).

emankov · 2026-02-26T13:20:37Z

hipify-clang --local-headers sample.cu

That is what worries me most.

The user should know or learn about the main source file, or, in general, the source files that include that particular header file.
sample.cu is not a header file. Here we have misleading information for the end users.
We need to explain somewhere, somehow, this tricky feature (actually a workaround).
Finally, it makes hipify-clang even more complicated in use, which we definitely do not want, as users already consider hipify-clang complicated enough to prefer hipify-perl usage instead. And we want the opposite. We want users to prefer hipify-clang. It means that we need to simplify it AMAP and do more work under the hood implicitly.

Technically, the main problem is that we are trying to treat a file, a header file, which is not self-contained, as a source file for hipification (actually, compilation).

I want us to think about other approaches here.
For instance:

Warn (besides compiler’s error messaging) the user about imposibility to hipify a header file, which is not self-contained.
Implement the ability to implicitly hipify all header files that are included in the main file.
Hipify everything in the provided folder.

ranapratap55 · 2026-03-04T06:47:11Z

hipify-clang --local-headers sample.cu

That is what worries me most.

The user should know or learn about the main source file, or, in general, the source files that include that particular header file.

sample.cu is not a header file. Here we have misleading information for the end users.

We need to explain somewhere, somehow, this tricky feature (actually a workaround).

Finally, it makes hipify-clang even more complicated in use, which we definitely do not want, as users already consider hipify-clang complicated enough to prefer hipify-perl usage instead. And we want the opposite. We want users to prefer hipify-clang. It means that we need to simplify it AMAP and do more work under the hood implicitly.

Technically, the main problem is that we are trying to treat a file, a header file, which is not self-contained, as a source file for hipification (actually, compilation).

I want us to think about other approaches here. For instance:

Warn (besides compiler’s error messaging) the user about imposibility to hipify a header file, which is not self-contained.

Implement the ability to implicitly hipify all header files that are included in the main file.

Hipify everything in the provided folder.

As per our discussions/suggestions, I've reworked this PR to implement suggestion 2.
Local header hipification is now implicit by default. hipify-clang sample.cu automatically detects and hipifies all local headers recursively, no flags needed. Added --skip-local-headers as the single opt-out mechanism.

I will raise 2 separate PRs as a follow up for:

Warn the user for non-self-contained headers
Folder-level hipification

Updated PR title and description to reflect the changes.

emankov · 2026-03-31T17:35:35Z

-cl::opt<bool> OptLocalHeadersRecursive("local-headers-recursive",
-  cl::desc("Enable hipification of quoted local headers recursively"),
+cl::opt<bool> SkipLocalHeaders("skip-local-headers",
+  cl::desc("Skip implicit hipification of local (quoted) headers included in the main source file"),


What if the "local" headers are included with <>?

I believe this is out of scope. Angled-bracket includes files are resolved using -I search paths. They represent system headers or external library dependencies.

But I do think there is edge case like, if a project uses #include <mylib/utils.h> via -I project/src flag, that would require resolving each angled-bracket against every -I path. That is a meaningful work and requires a separate PR of its own.

#2505: Angle-bracket local header hipification (#include <>)

emankov · 2026-03-31T18:18:42Z

+  bool collectPrecedingIncludes(const std::string &mainSourceAbspath,
+                                const std::string &targetHeaderAbspath,
+                                std::vector<std::string> &outIncludes) {
+    std::string mainSourceContent;
+    if (!readFile(mainSourceAbspath, mainSourceContent)) {
+      errs() << sHipify << sError << "Cannot read source files: "
+            << mainSourceAbspath << "\n";
+      return false;
+    }
+
+    std::string targetFileName = std::string(sys::path::filename(targetHeaderAbspath));
+    std::istringstream iss(mainSourceContent);
+    std::string line;
+    std::smatch m;
+
+    while (std::getline(iss, line)) {
+      if (std::regex_match(line, m, LocalIncludeRe)) {
+        std::string quotedName = m[1].str();
+        std::string quotedFileName = std::string(sys::path::filename(quotedName));
+        if (quotedFileName == targetFileName)
+          break;
+        std::string absPath;
+        if (resolveLocalIncludeInternal(mainSourceAbspath, quotedName, absPath))
+          outIncludes.push_back(absPath);
+      }
+
+      if (std::regex_search(line, m, SystemIncludeRe)) {
+        outIncludes.push_back(m[1].str());
+      }
+    }
+
+    return true;
+  }
+}


Looks like the collectPrecedingIncludes only scans the immediate parentPath.
What about deeply nested headers?

yes, correct.
collectPrecedingIncludes scans only one level (the immediate parent). This is intentional for this PR, it was designed for (main.cu → A.h → B.h) where B.h depends on explicitly included before it in A.h and collectPrecedingIncludes(A.h, B.h) finds exactly what B.h needs.

I considered collecting full ancestor chain recursively (for nested headers) but that results in over-injection. When two of those injected headers define same symbol, we get redefinition errors.

I would like to take this (deeply nested headers) as a follow-up PR. We track the full ancestors list and modify from {hdr, parentPath} to {hdr, vector<parentChain>}. And only injects that appear in ancestors(parents) up to the nearest file that explicitly includes the current target. This avoids over-injection issue.

#2507: Transitive preceding includes for deeply nested recursive headers

ranapratap55 · 2026-04-07T11:21:02Z

Follow up work

[HIPIFY][#2402] Transitive preceding includes for deeply nested recursive headers #2507: Transitive preceding includes for deeply nested recursive headers
[HIPIFY][#2402] hipify project-local headers included with angle brackets (<>) #2505: Angle-bracket local header hipification (#include <>)

emankov · 2026-04-16T20:50:19Z

The added tests cover basic recursion and depth-1 injection of “includes”. However, the test that verifies the transitive context is preserved during recursive traversal is still needed.

Please add a test that includes a non-self-contained header with a recursion depth of 2 or more. For example, the root .cu file includes <cmath> and parent.h; parent.h includes child.h; and child.h uses sqrtf but does not include <cmath> itself. This is essential to ensure that the inherited compilation context is correctly propagated down the inclusion chain and is not dropped when processing nested files.

emankov · 2026-04-16T20:54:28Z

I honestly believe we need to preserve -local-headers and --local-headers-recursive, since the feature you're introducing is experimental and shouldn't be used by default. What do you think, @ranapratap55?

…jection via ArgumentsAdjusters

…ntext test

ranapratap55 · 2026-04-20T10:18:20Z

The added tests cover basic recursion and depth-1 injection of “includes”. However, the test that verifies the transitive context is preserved during recursive traversal is still needed.

Please add a test that includes a non-self-contained header with a recursion depth of 2 or more. For example, the root .cu file includes <cmath> and parent.h; parent.h includes child.h; and child.h uses sqrtf but does not include <cmath> itself. This is essential to ensure that the inherited compilation context is correctly propagated down the inclusion chain and is not dropped when processing nested files.

I've adapted to use <algorithm> + std::sort

transitive_system_include.cu: includes <algorithm> and transitive_parent.h
transitive_parent.h: includes transitive_child.h and <cuda_runtime.h>, but no <algorithm>
transitive_child.h: uses std::sort and cudaMalloc, includes neither <algorithm> nor <cuda_runtime.h>

collectAncestorSystemIncludes walks the ancestor chain and collects <algorithm> from the main src file, then injects it before compiling transitive_child.h. If this propagation breaks, the test fails directly.

ranapratap55 · 2026-04-20T10:31:20Z

I honestly believe we need to preserve -local-headers and --local-headers-recursive, since the feature you're introducing is experimental and shouldn't be used by default. What do you think, @ranapratap55?

Thanks for raising this and it is a fair concern.

Based on our earlier discussions, we collectively moved toward implicit-by-default to lower the barrier for users. The current revision already has multiple layers in place for end users like

Opt-out flag: --skip-local-headers for users who don't want automatic hipification
Non-self-contained header warning: [HIPIFY] warning: non-self-contained header is emitted when a header cannot be hipified in isolation and with a note warning the user to run the parent source file instead

And I am thinking to add below

Auto-hipification notice: an info-level message [HIPIFY] note: local headers detected: hipifying automatically. Use --skip-local-headers to disable.

With these measures together I believe the implicit behavior is transparent. That said, I am happy to address any specific scenario where this causes harm directly rather than revert the design.

What do you think? @emankov

ranapratap55 requested review from emankov and searlmc1 as code owners February 23, 2026 09:33

ranapratap55 requested review from SyamaAmd and kzhuravl February 23, 2026 09:34

ranapratap55 self-assigned this Feb 23, 2026

ranapratap55 added fix It fixes bug feature Feature request or implementation labels Feb 23, 2026

ranapratap55 mentioned this pull request Feb 23, 2026

[HIPIFY][feature] Add header injection fallback for local headers hipification #2275

Draft

ranapratap55 force-pushed the users/ranapratap55/implict-local-headers branch from 5e6249f to 353ebef Compare March 4, 2026 06:20

ranapratap55 changed the title ~~[HIPIFY][feature] Local header hipification with preceding include injection via ArgumentsAdjusters~~ [HIPIFY][feature] Implicit hipification of local header files Mar 4, 2026

ranapratap55 added the partial Partial fix or implementation label Mar 20, 2026

ranapratap55 changed the title ~~[HIPIFY][feature] Implicit hipification of local header files~~ [HIPIFY][feature] Implicit hipification of local header files - Part 1 Mar 20, 2026

ranapratap55 force-pushed the users/ranapratap55/implict-local-headers branch from 353ebef to d10566f Compare March 24, 2026 07:43

ranapratap55 mentioned this pull request Mar 25, 2026

[HIPIFY][#2402] Warn users for non-self-contained header hipification in isolation - Part 2 #2447

Draft

emankov requested changes Mar 31, 2026

View reviewed changes

ranapratap55 force-pushed the users/ranapratap55/implict-local-headers branch from d10566f to 7d568b6 Compare April 6, 2026 17:10

ranapratap55 requested a review from emankov April 7, 2026 10:55

This was referenced Apr 7, 2026

[HIPIFY][#2402] hipify project-local headers included with angle brackets (<>) #2505

Open

[HIPIFY][#2402] Transitive preceding includes for deeply nested recursive headers #2507

Open

emankov requested changes Apr 9, 2026

View reviewed changes

Comment thread src/LocalHeader.cpp Outdated

Comment thread src/LocalHeader.cpp Outdated

ranapratap55 force-pushed the users/ranapratap55/implict-local-headers branch from 8d1113a to 8a1adf5 Compare April 13, 2026 05:54

ranapratap55 requested a review from emankov April 13, 2026 06:11

ranapratap55 added 7 commits April 20, 2026 10:24

[HIPIFY][feature] Local header hipification with preceding include in…

6713351

…jection via ArgumentsAdjusters

[HIPIFY][doc][NFC] Updated the licence

5b51fec

[HIPIFY][feature] Implicit hipification of local header files

d7e165f

[HIPIFY][fix] Fix regex, premature loop break, and duplicate warnings

5f73c4a

[HIPIFY][fix] Fix compile_commands json issue

a694fb1

[HIPIFY][fix] Fix regex and structured bindings

18fba25

[HIPIFY][fix] Refactor include scanning and add depth-2 transitive co…

e198b45

…ntext test

ranapratap55 force-pushed the users/ranapratap55/implict-local-headers branch from 8a1adf5 to e198b45 Compare April 20, 2026 10:12

Conversation

ranapratap55 commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem Statement

Purpose

Solution

Summary of changes in this PR

Uh oh!

emankov commented Feb 24, 2026

Uh oh!

ranapratap55 commented Feb 25, 2026

Uh oh!

emankov commented Feb 25, 2026

Uh oh!

ranapratap55 commented Feb 26, 2026

Uh oh!

emankov commented Feb 26, 2026

Uh oh!

ranapratap55 commented Mar 4, 2026

Uh oh!

Uh oh!

Uh oh!

emankov Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

ranapratap55 Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

ranapratap55 Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

emankov Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

ranapratap55 Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

ranapratap55 Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ranapratap55 commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

emankov commented Apr 16, 2026

Uh oh!

emankov commented Apr 16, 2026

Uh oh!

ranapratap55 commented Apr 20, 2026

Uh oh!

ranapratap55 commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ranapratap55 commented Feb 23, 2026 •

edited

Loading

ranapratap55 commented Apr 7, 2026 •

edited

Loading

ranapratap55 commented Apr 20, 2026 •

edited

Loading