Clang modules builtin resolution falls back to missing symbol on Windows UCRT due to lazy deserialization

[atetubou]

Description

When compiling C++ code for Windows MSVC targets under Clang Modules (-fmodules), calls to standard library math builtins like __builtin_hypotf fail to link because the compiler generates references to the non-existent symbol hypotf instead of the UCRT-imported symbol _hypotf.

Why it fails:

1. Microsoft's Windows C Runtime (UCRT) does not export hypotf or _hypotl directly. UCRT only exports _hypotf (as __imp__hypotf in the dynamic import library).
2. To conform to standard C/C++, UCRT's <corecrt_math.h> declares _hypotf and defines hypotf as an inline wrapper function:

   __inline float hypotf(float _X, float _Y) { return _hypotf(_X, _Y); }

3. During code generation, Clang's CodeGen engine resolves __builtin_hypotf by searching the AST lookup table for a standard library declaration named hypotf (with C linkage).
4. Textual (non-modular) builds: The header <math.h> is textually parsed, eagerly loading the hypotf inline wrapper declaration. CodeGen binds to it, inlines it, and successfully generates a call to _hypotf (__imp__hypotf).
5. Modular builds: The header <math.h> is parsed as a module, storing its declarations inside a precompiled module file (.pcm). Under Clang Modules, declarations in PCM files are lazily deserialized only when looked up by name. Because the builtin call references __builtin_hypotf, hypotf is never looked up and is not deserialized. CodeGen fails to find the declaration and falls back to emitting a direct external reference to hypotf (which fails link).

---

Minimal Reproduction Steps

Create a directory containing the following files:

1. corecrt_math.h (UCRT mock)

// corecrt_math.h
#ifndef MOCK_CORECRT_MATH_H
#define MOCK_CORECRT_MATH_H

extern "C" {
#ifdef _DLL
__declspec(dllimport) float __cdecl _hypotf(float x, float y);
#else
float __cdecl _hypotf(float x, float y);
#endif

inline float __cdecl hypotf(float x, float y) {
  return _hypotf(x, y);
}
}

#endif

2. math.h (UCRT mock)

// math.h
#ifndef MOCK_MATH_H
#define MOCK_MATH_H

#include "corecrt_math.h"

#endif

3. __math/hypot.h (libc++ mock)

// __math/hypot.h
#ifndef MOCK_MATH_HYPOT_H
#define MOCK_MATH_HYPOT_H

inline float hypot(float x, float y) {
  return __builtin_hypotf(x, y);
}

#endif

4. cmath (libc++ mock)

// cmath
#ifndef MOCK_CMATH
#define MOCK_CMATH

#include "math.h"
#include "__math/hypot.h"

#endif

5. main.cc (User source)

#include "cmath"

float test_call(float x, float y) {
  return hypot(x, y);
}

6. std.modulemap

module std {
  module cmath {
    header "cmath"
    export *
  }
  module math_hypot {
    header "__math/hypot.h"
    export *
  }
}

7. ucrt.modulemap

module ucrt {
  module math {
    header "math.h"
    export *
  }
  module corecrt_math {
    header "corecrt_math.h"
    export *
  }
}

---

Compilation & IR Comparison

Case A: Textual Compilation (No Modules)

Compile textually to emit LLVM IR:

clang-cl.exe /c main.cc -Xclang -emit-llvm -D_DLL -target x86_64-pc-windows-msvc19.34.0 -I. /Fotextual.ll

Generated IR Output (working):

; The compiler resolves and inlines UCRT's wrapper, generating correct dllimport:
declare dllimport float @_hypotf(float noundef, float noundef)

Case B: Modular Compilation

First, compile the module PCM files directly:

# 1. Compile UCRT module
clang-cl.exe -c -x c++-module ucrt.modulemap -Xclang -emit-module -fmodules -fmodule-name=ucrt -fmodule-map-file=ucrt.modulemap -D_DLL -target x86_64-pc-windows-msvc19.34.0 -I. -o ucrt.pcm

# 2. Compile libc++ std module
clang-cl.exe -c -x c++-module std.modulemap -Xclang -emit-module -fmodules -fmodule-name=std -fmodule-map-file=std.modulemap -fmodule-map-file=ucrt.modulemap -fmodule-file=ucrt=ucrt.pcm -D_DLL -target x86_64-pc-windows-msvc19.34.0 -I. -o std.pcm

Next, compile main.cc using the PCMs:

clang-cl.exe -c main.cc -emit-llvm -S -fmodules -fmodule-map-file=std.modulemap -fmodule-map-file=ucrt.modulemap -fmodule-file=std=std.pcm -fmodule-file=ucrt=ucrt.pcm -D_DLL -target x86_64-pc-windows-msvc19.34.0 -I. -o repro_modular.ll

Generated IR Output (broken):

; The compiler fails to deserialize the UCRT declaration, falling back to:
declare dso_local float @hypotf(float noundef, float noundef)

This is derived from Chromium build issue in https://ci.chromium.org/ui/p/chromium/builders/ci/Win%20x64%20Builder%20%28dbg%29/190643/overview (tracked internally as http://b/525295309)

[llvmorg-github-actions]

@llvm/issue-subscribers-clang-modules

Author: Takuto Ikuta (atetubou)

Details

Description

When compiling C++ code for Windows MSVC targets under Clang Modules (-fmodules), calls to standard library math builtins like __builtin_hypotf fail to link because the compiler generates references to the non-existent symbol hypotf instead of the UCRT-imported symbol _hypotf.

Why it fails:

1. Microsoft's Windows C Runtime (UCRT) does not export hypotf or _hypotl directly. UCRT only exports _hypotf (as __imp__hypotf in the dynamic import library).
2. To conform to standard C/C++, UCRT's <corecrt_math.h> declares _hypotf and defines hypotf as an inline wrapper function:

   __inline float hypotf(float _X, float _Y) { return _hypotf(_X, _Y); }

3. During code generation, Clang's CodeGen engine resolves __builtin_hypotf by searching the AST lookup table for a standard library declaration named hypotf (with C linkage).
4. Textual (non-modular) builds: The header <math.h> is textually parsed, eagerly loading the hypotf inline wrapper declaration. CodeGen binds to it, inlines it, and successfully generates a call to _hypotf (__imp__hypotf).
5. Modular builds: The header <math.h> is parsed as a module, storing its declarations inside a precompiled module file (.pcm). Under Clang Modules, declarations in PCM files are lazily deserialized only when looked up by name. Because the builtin call references __builtin_hypotf, hypotf is never looked up and is not deserialized. CodeGen fails to find the declaration and falls back to emitting a direct external reference to hypotf (which fails link).

---

Minimal Reproduction Steps

Create a directory containing the following files:

1. corecrt_math.h (UCRT mock)

// corecrt_math.h
#ifndef MOCK_CORECRT_MATH_H
#define MOCK_CORECRT_MATH_H

extern "C" {
#ifdef _DLL
__declspec(dllimport) float __cdecl _hypotf(float x, float y);
#else
float __cdecl _hypotf(float x, float y);
#endif

inline float __cdecl hypotf(float x, float y) {
  return _hypotf(x, y);
}
}

#endif

2. math.h (UCRT mock)

// math.h
#ifndef MOCK_MATH_H
#define MOCK_MATH_H

#include "corecrt_math.h"

#endif

3. __math/hypot.h (libc++ mock)

// __math/hypot.h
#ifndef MOCK_MATH_HYPOT_H
#define MOCK_MATH_HYPOT_H

inline float hypot(float x, float y) {
  return __builtin_hypotf(x, y);
}

#endif

4. cmath (libc++ mock)

// cmath
#ifndef MOCK_CMATH
#define MOCK_CMATH

#include "math.h"
#include "__math/hypot.h"

#endif

5. main.cc (User source)

#include "cmath"

float test_call(float x, float y) {
  return hypot(x, y);
}

6. std.modulemap

module std {
  module cmath {
    header "cmath"
    export *
  }
  module math_hypot {
    header "__math/hypot.h"
    export *
  }
}

7. ucrt.modulemap

module ucrt {
  module math {
    header "math.h"
    export *
  }
  module corecrt_math {
    header "corecrt_math.h"
    export *
  }
}

---

Compilation & IR Comparison

Case A: Textual Compilation (No Modules)

Compile textually to emit LLVM IR:

clang-cl.exe /c main.cc -Xclang -emit-llvm -D_DLL -target x86_64-pc-windows-msvc19.34.0 -I. /Fotextual.ll

Generated IR Output (working):

; The compiler resolves and inlines UCRT's wrapper, generating correct dllimport:
declare dllimport float @<!-- -->_hypotf(float noundef, float noundef)

Case B: Modular Compilation

First, compile the module PCM files directly:

# 1. Compile UCRT module
clang-cl.exe -c -x c++-module ucrt.modulemap -Xclang -emit-module -fmodules -fmodule-name=ucrt -fmodule-map-file=ucrt.modulemap -D_DLL -target x86_64-pc-windows-msvc19.34.0 -I. -o ucrt.pcm

# 2. Compile libc++ std module
clang-cl.exe -c -x c++-module std.modulemap -Xclang -emit-module -fmodules -fmodule-name=std -fmodule-map-file=std.modulemap -fmodule-map-file=ucrt.modulemap -fmodule-file=ucrt=ucrt.pcm -D_DLL -target x86_64-pc-windows-msvc19.34.0 -I. -o std.pcm

Next, compile main.cc using the PCMs:

clang-cl.exe -c main.cc -emit-llvm -S -fmodules -fmodule-map-file=std.modulemap -fmodule-map-file=ucrt.modulemap -fmodule-file=std=std.pcm -fmodule-file=ucrt=ucrt.pcm -D_DLL -target x86_64-pc-windows-msvc19.34.0 -I. -o repro_modular.ll

Generated IR Output (broken):

; The compiler fails to deserialize the UCRT declaration, falling back to:
declare dso_local float @<!-- -->hypotf(float noundef, float noundef)

[atetubou]

@zmodem @ChuanqiXu9 I made another fix as #209997. Does that look good for you? Or you still want to know the reason of behavior difference between Windows and Linux before fixing this?

[atetubou]

I asked gemini to investigate the non-module resolution path of hypot calling in clang. And it showed the following summary. Considering that we want to keep lazy deserialization in module build as far as possible, I think proposed fix reasonable to me for modules build.

---

Investigation: Built-in Library Function Resolution in Non-Module vs. Clang Modules Builds

Overview

This report documents the detailed code path and execution mechanism in Clang when resolving built-in library functions (such as __builtin_hypotf) to target C functions (such as MSVC UCRT's inline float hypotf(...) which calls _hypotf).

Specifically, it explains why non-module (textual header inclusion) builds succeed in emitting inline function wrappers without explicit AST lookups, whereas Clang Modules builds fail without explicit on-demand deserialization.

---

Code Flow in Non-Module Compilation (Textual Includes)

Example Code Context

// corecrt_math.h (MSVC UCRT pattern)
extern "C" {
__declspec(dllimport) float __cdecl _hypotf(float x, float y);
inline float __cdecl hypotf(float x, float y) {
  return _hypotf(x, y);
}
}

// __math/hypot.h
inline float hypot(float x, float y) {
  return __builtin_hypotf(x, y); // Calls built-in library function
}

// main.cc
float test_call(float x, float y) {
  return hypot(x, y);
}

---

Step-by-Step Execution Path in Non-Module Builds

1. Header Parsing Phase:

   • As corecrt_math.h is parsed textually, Clang's Parser/Sema creates a FunctionDecl for inline float hypotf(float, float).
   • Clang's CodeGenModule scans top-level declarations and registers hypotf into its internal DeferredDecls map:

     // CodeGenModule.h
     llvm::DenseMap<StringRef, GlobalDecl> DeferredDecls;

2. Built-in Function Evaluation Phase:

   • CodeGen emits code for test_call -> hypot -> __builtin_hypotf.
   • CodeGenFunction::EmitBuiltinExpr evaluates __builtin_hypotf and identifies it as a library function (BI.isLibFunction(...)):

     // clang/lib/CodeGen/CGBuiltin.cpp:L7033-L7037
     const auto &BI = getContext().BuiltinInfo;
     if (!shouldEmitBuiltinAsIR(BuiltinID, BI, *this) &&
         BI.isLibFunction(BuiltinID))
       return emitLibraryCall(*this, FD, E,
                              CGM.getBuiltinLibFunction(FD, BuiltinID));

   • CodeGenFunction calls CodeGenModule::getBuiltinLibFunction(FD, BuiltinID).

3. GetOrCreateLLVMFunction & DeferredDecls Lookup:

   • getBuiltinLibFunction extracts the target C function name "hypotf" and calls GetOrCreateLLVMFunction("hypotf", Ty, D).
   • Inside GetOrCreateLLVMFunction (clang/lib/CodeGen/CodeGenModule.cpp:L5630-L5636):

     auto DDI = DeferredDecls.find(MangledName); // MangledName = "hypotf"
     if (DDI != DeferredDecls.end()) {
       addDeferredDeclToEmit(DDI->second);
       DeferredDecls.erase(DDI);
     }

   • Because hypotf was pre-registered into DeferredDecls during header parsing, DeferredDecls.find("hypotf") succeeds.

4. IR Emission:

   • addDeferredDeclToEmit queues hypotf for IR emission.
   • At the end of the translation unit, CodeGenModule::EmitDeferred() emits the definition body of hypotf (define linkonce_odr float @hypotf), which contains the call to _hypotf (call float @_hypotf).

---

Empirical Debug Log Evidence

To verify this execution path in a non-module build, temporary debug logging (llvm::errs()) was inserted into key functions in CodeGenModule.cpp and CGBuiltin.cpp.

Debug Log Insertions

1. In CodeGenModule::getBuiltinLibFunction (clang/lib/CodeGen/CGBuiltin.cpp:L270):

   llvm::errs() << "[DEBUG_LOG] getBuiltinLibFunction called for Name: " << Name << "\n";

2. In CodeGenModule::GetOrCreateLLVMFunction (clang/lib/CodeGen/CodeGenModule.cpp:L5630-L5632):

   auto DDI = DeferredDecls.find(MangledName);
   if (DDI != DeferredDecls.end()) {
     llvm::errs() << "[DEBUG_LOG] DeferredDecls FOUND and queued for emission for MangledName: " << MangledName << "\n";
     addDeferredDeclToEmit(DDI->second);
     DeferredDecls.erase(DDI);
   }

3. In CodeGenModule::EmitDeferred (clang/lib/CodeGen/CodeGenModule.cpp:L4001-L4004):

   for (GlobalDecl &D : CurDeclsToEmit) {
     if (const auto *ND = dyn_cast<NamedDecl>(D.getDecl())) {
       llvm::errs() << "[DEBUG_LOG] EmitDeferred emitting decl: " << ND->getNameAsString() << "\n";
     }

Collected Output Log:

[DEBUG_LOG] DeferredDecls FOUND and queued for emission for MangledName: ?hypot@@YAMMM@Z
[DEBUG_LOG] EmitDeferred emitting decl: hypot
[DEBUG_LOG] getBuiltinLibFunction called for Name: hypotf
[DEBUG_LOG] DeferredDecls FOUND and queued for emission for MangledName: hypotf
[DEBUG_LOG] EmitDeferred emitting decl: hypotf

This empirically confirms that non-module builds rely on DeferredDecls pre-populated during textual header parsing to emit the inline wrapper.

---

Why Clang Modules Fail Without Explicit AST Lookup

Feature	Non-Module (Textual Include)	Clang Modules (PCM)
Header Parsing	Textual parsing populates DeferredDecls for all inline functions.	Headers are not parsed textually; PCM AST nodes are lazily deserialized.
DeferredDecls Status	Pre-populated with hypotf.	Empty for hypotf (since hypotf wasn't referenced via Sema Name Lookup).
GetOrCreateLLVMFunction("hypotf")	Finds hypotf in DeferredDecls -> Emits inline body (_hypotf).	Fails to find hypotf in DeferredDecls -> Emits external fallback (declare float @hypotf).
Result	Link succeeds (_hypotf called).	Linker error (unresolved external symbol hypotf).

Fix Rationale

Adding explicit AST lookup in CodeGenModule::getBuiltinLibFunction:

DeclarationName DecName = &Context.Idents.get(Name);
DeclContext::lookup_result Decls = Context.getTranslationUnitDecl()->lookup(DecName);

Triggers ASTReader to lazily deserialize hypotf from the PCM on demand only when __builtin_hypotf is actually used, preserving the performance benefits of Clang Modules' Lazy Deserialization while resolving the inline definition correctly.

[zmodem]

+@jyknight too since he's commented on the previous iterations of this.

(I think we've got three PRs going for this now: #209997, #207135, #204792).

I made another fix as #209997. Does that look good for you?

Hmm, I'm not completely against it, but it still feels like it's papering over problems with how these builtin calls are emitted.

It seems the original idea was for Clang to call these libc functions directly, and by accident it also happened to work if the functions are inline definitions in an included header. With your patch, I suppose we'd extend this behavior to work in modules builds too.

Or you still want to know the reason of behavior difference between Windows and Linux before fixing this?

I think the modules vs textual headers difference is will understood. That seems deterministic though. Yes, it would be good to understand where the non-determinism reported in #204792 comes from too.

[atetubou]

I'm still not sure what is the proper fix we can get concensus, but for the workaround in chromium we use /alternatename to avoid this error https://crrev.com/c/8204706.