Support clang-dumper include archives with entrypoints.txt

[lm-sousa]

Context

specs-feup/clang-dumper now publishes include archives as release assets for Linux, macOS, and Windows. The new archive format no longer assumes every top-level directory is itself an include root.

Each archive contains:

• minimal copied include-root directories, with duplicated ancestor folders collapsed
• an entrypoints.txt file at the archive root

entrypoints.txt lists the relative paths inside the extracted archive that must be passed as system include roots, in order.

Example Linux shape:

clang/
usr/
entrypoints.txt

Example Linux entrypoints.txt:

usr/c++/14
usr/x86_64-linux-gnu/c++/14
usr/c++/14/backward
clang
usr/x86_64-linux-gnu
usr

Example Windows shape:

clang/
mingw/
entrypoints.txt

Example Windows entrypoints.txt:

mingw/c++/v1
clang
mingw

Why Clava needs a change

Current Clava behavior in ClangAstParser/src/pt/up/fe/specs/clang/ClangResources.java extracts include zips and then adds every top-level extracted folder as a system include, sorted by folder name.

That works for the older archives where the folder layout encoded the include roots via numeric prefixes. It will not work for the new minimal archives, because some include roots are nested under copied ancestors and must be read from entrypoints.txt.

Required behavior

When an extracted include archive contains entrypoints.txt:

• read the file from the extracted archive root
• preserve the file order exactly
• for each non-empty line, resolve it relative to the extracted archive root
• add the resolved path as a system include root
• do not sort these paths
• do not hardcode folder names such as usr, clang, mingw, 01-*, etc.

Backward compatibility:

• if entrypoints.txt is absent, throw.

Important files

• ClangAstParser/src/pt/up/fe/specs/clang/ClangResources.java
• ClangAstParser/src/pt/up/fe/specs/clang/dumper/ClangAstDumper.java
• ClangAstParser/src/pt/up/fe/specs/clang/ClangAstWebResource.java

Recommended prompt for the implementation agent

Update Clava to support the new clang-dumper include archive format.

Context:
clang-dumper include packages now contain minimal copied include roots plus an entrypoints.txt file at the archive root. entrypoints.txt lists, in order, the relative paths inside the extracted archive that must be passed as system include roots. This replaces the old assumption that every top-level extracted folder is itself an include root.

Task:
In ../clava, update ClangAstParser resource extraction/use so that when an extracted include archive contains entrypoints.txt, Clava reads it and adds those listed paths, relative to the extracted archive folder, as system includes in file order. Do not preserve backward compatibility: if entrypoints.txt is absent, throw.

Important files to inspect:
- ClangAstParser/src/pt/up/fe/specs/clang/ClangResources.java
- ClangAstParser/src/pt/up/fe/specs/clang/dumper/ClangAstDumper.java
- ClangAstParser/src/pt/up/fe/specs/clang/ClangAstWebResource.java

Acceptance:
- New archives with entrypoints.txt work.
- Old archives without throw.
- Include order follows entrypoints.txt exactly.
- Do not hardcode archive folder names such as usr, clang, mingw, 01-*, etc.

Notes

The current clang-dumper test runner already consumes entrypoints.txt for Windows CI and normalizes the resulting include paths. Clava should do the equivalent when using packaged include archives.