Embedded LLD Phase 5: Windows

[SeanTAllen]

Phase 5 implementation plan for the Embedded LLD project. This phase switches native Windows linking from the external MSVC link.exe command (invoked via system() through cmd /C) to embedded LLD's COFF driver (lld::coff::link).

Scope

What this phase delivers:

• Embedded LLD COFF linking for native Windows builds (x86-64 and ARM64)
• Reuse of existing vcvars.c path discovery for SDK/MSVC paths
• --linker kept as escape hatch to legacy system() path

What this phase does NOT do:

• Cross-compilation to Windows targets from non-Windows hosts — future work
• Change vcvars.c path discovery — reused as-is
• Support BSD targets — Phase 6
• Remove the legacy linker path — Phase 7

Prerequisites

All in place from earlier phases:

• LLD libraries built and linked into ponyc (Phase 1, PR Embedded LLD Phase 1: Build infrastructure + CRT objects #4945)
• LLD_HAS_DRIVER(coff) declaration already present in genexe.cc line 7
• genexe.cc is C++ (Phase 1)
• program_lib_build_args_embedded() API available (Phase 1)
• Pattern established by link_exe_lld_elf() and link_exe_lld_macho() for argument vector construction, LLD invocation, verbose logging, and error handling (Phases 2-4)

Steps

Step 1: Move C++ and LLD includes outside the POSIX guard

File: src/libponyc/codegen/genexe.cc

The LLVM and C++ standard library headers needed for LLD invocation are currently inside #ifdef PLATFORM_IS_POSIX_BASED (lines 27-35). Windows needs them too. Move <llvm/Support/raw_ostream.h>, <vector>, and <string> outside the guard. Keep <unistd.h>, <sys/stat.h>, <dirent.h>, and <llvm/TargetParser/Triple.h> inside — these are POSIX-specific or only used by ELF/Mach-O helpers.

Before:

#ifdef PLATFORM_IS_POSIX_BASED
#  include <unistd.h>
#  include <sys/stat.h>
#  include <dirent.h>
#  include <llvm/TargetParser/Triple.h>
#  include <llvm/Support/raw_ostream.h>
#  include <vector>
#  include <string>
#endif

After:

#include <llvm/Support/raw_ostream.h>
#include <vector>
#include <string>

#ifdef PLATFORM_IS_POSIX_BASED
#  include <unistd.h>
#  include <sys/stat.h>
#  include <dirent.h>
#  include <llvm/TargetParser/Triple.h>
#endif

Step 2: Implement link_exe_lld_coff()

File: src/libponyc/codegen/genexe.cc

Add a new static function inside an #ifdef PLATFORM_IS_WINDOWS block, placed after the #endif closing the PLATFORM_IS_POSIX_BASED block (after line 1228) and before the link_exe() function (line 1230).

#ifdef PLATFORM_IS_WINDOWS
static bool link_exe_lld_coff(compile_t* c, ast_t* program,
  const char* file_o)

Function flow (mirrors the pattern from link_exe_lld_elf() and link_exe_lld_macho()):

1. Discover MSVC/SDK paths: Call vcvars_get() — same as the legacy path. Error if it fails.
2. Compute output filename: suffix_filename(c, c->opt->output, "", c->filename, ".exe").
3. Print linking message if verbosity >= VERBOSITY_MINIMAL.
4. Build library args: Call program_lib_build_args_embedded(program, c->opt).
5. Determine architecture: Use compile-time _M_ARM64 / _M_X64 macros — same as the legacy path.
6. Warn about ignored flags: If c->opt->link_ldcmd != NULL, emit a warning.
7. Construct LLD argument vector (see below).
8. Log command if verbosity >= VERBOSITY_TOOL_INFO.
9. Call lld::lldMain() with COFF driver.
10. Handle result: check return code, report errors.

Argument vector construction:

lld-link                                // argv[0] — selects COFF driver
/DEBUG                                  // enable debug info
/NOLOGO                                 // suppress banner
/MACHINE:<arch>                         // ARM64 or x64
/ignore:4099                            // ignore "debug info not found" warnings
/OUT:<file_exe>                         // output executable
<file_o>                                // compiled Pony program
/LIBPATH:<ucrt_path>                    // UCRT (if present)
/LIBPATH:<kernel32_path>                // Windows SDK
/LIBPATH:<msvcrt_path>                  // MSVC runtime
/LIBPATH:<user_paths...>                // from program_lib_build_args_embedded()
<user_libs...>.lib                      // user libraries with .lib suffix
<default_libs>                          // kernel32.lib msvcrt.lib etc.
libponyrt.lib                           // unless --runtimebc

Detailed argument construction:

std::vector<const char*> args;
char buf[MAX_PATH + 32];

args.push_back("lld-link");
args.push_back("/DEBUG");
args.push_back("/NOLOGO");

snprintf(buf, sizeof(buf), "/MACHINE:%s", arch);
args.push_back(stringtab(buf));

args.push_back("/ignore:4099");

snprintf(buf, sizeof(buf), "/OUT:%s", file_exe);
args.push_back(stringtab(buf));

// Object file.
args.push_back(file_o);

// UCRT library path (Windows 10+ SDK).
if(strlen(vcvars.ucrt) > 0)
{
  snprintf(buf, sizeof(buf), "/LIBPATH:%s", vcvars.ucrt);
  args.push_back(stringtab(buf));
}

// Windows SDK kernel32 path.
snprintf(buf, sizeof(buf), "/LIBPATH:%s", vcvars.kernel32);
args.push_back(stringtab(buf));

// MSVC runtime lib path.
snprintf(buf, sizeof(buf), "/LIBPATH:%s", vcvars.msvcrt);
args.push_back(stringtab(buf));

// User library search paths.
size_t path_count = program_lib_path_count(program);
for(size_t i = 0; i < path_count; i++)
{
  const char* path = program_lib_path_at(program, i);
  snprintf(buf, sizeof(buf), "/LIBPATH:%s", path);
  args.push_back(stringtab(buf));
}

// User libraries (append .lib suffix for non-absolute paths).
size_t lib_count = program_lib_count(program);
for(size_t i = 0; i < lib_count; i++)
{
  const char* lib = program_lib_at(program, i);
  if(is_path_absolute(lib))
  {
    args.push_back(lib);
  }
  else
  {
    snprintf(buf, sizeof(buf), "%s.lib", lib);
    args.push_back(stringtab(buf));
  }
}

// Default Windows system libraries.
// vcvars.default_libs is a space-separated string; tokenize into
// individual arguments for embedded LLD.
char default_libs_copy[MAX_PATH];
strncpy(default_libs_copy, vcvars.default_libs, MAX_PATH - 1);
default_libs_copy[MAX_PATH - 1] = '\0';

char* tok = strtok(default_libs_copy, " ");
while(tok != NULL)
{
  args.push_back(stringtab(tok));
  tok = strtok(NULL, " ");
}

// Pony runtime.
if(!c->opt->runtimebc)
{
  args.push_back("libponyrt.lib");
}

// Log the command if verbose.
if(c->opt->verbosity >= VERBOSITY_TOOL_INFO)
{
  std::string cmd;
  for(size_t i = 0; i < args.size(); i++)
  {
    if(i > 0) cmd += " ";
    cmd += args[i];
  }
  fprintf(stderr, "%s\n", cmd.c_str());
}

What's NOT in the argument list (and why):

• No CRT objects: Windows CRT initialization is handled implicitly through msvcrt.lib / vcruntime.lib. The MSVC linker (and LLD's COFF driver) automatically finds the entry point (mainCRTStartup).
• No --sysroot: Windows doesn't use the sysroot concept. SDK/MSVC paths are discovered via vcvars.
• No -rpath: Windows doesn't embed runtime library search paths in executables. DLLs are found via PATH or side-by-side manifests.
• No --export-dynamic: Not applicable to COFF/PE. The legacy Windows code doesn't pass an equivalent of -rdynamic.
• No --strip-debug: The legacy code always passes /DEBUG and doesn't check c->opt->strip_debug. Phase 5 preserves this behavior.
• No PIE: Windows executables use ASLR by default (/DYNAMICBASE is on by default in LLD-link). No explicit flag needed.
• No -static: The --static option is Linux/musl only. Windows doesn't have a static-binary mode in ponyc.

LLD invocation (same pattern as ELF/Mach-O):

std::vector<const char*> lld_args(args.begin(), args.end());
std::string lld_stdout_str;
std::string lld_stderr_str;
llvm::raw_string_ostream lld_stdout(lld_stdout_str);
llvm::raw_string_ostream lld_stderr(lld_stderr_str);

lld::Result result = lld::lldMain(
  lld_args,
  lld_stdout,
  lld_stderr,
  {{lld::WinLink, &lld::coff::link},
   {lld::Gnu, &lld::elf::link},
   {lld::Darwin, &lld::macho::link},
   {lld::MinGW, &lld::mingw::link},
   {lld::Wasm, &lld::wasm::link}});

if(result.retCode != 0)
{
  errorf(errors, NULL, "unable to link: %s", lld_stderr_str.c_str());
  return false;
}

return true;

Note: lldMain() selects the driver based on argv[0]. When argv[0] is lld-link, it selects the COFF driver. All five drivers are registered to match the five LLD_HAS_DRIVER declarations at the top of the file.

Step 3: Add routing logic in link_exe()

File: src/libponyc/codegen/genexe.cc

Add routing between the end of the POSIX LLD routing (line 1259, #endif) and the start of the legacy code (line 1261, const char* ponyrt):

#endif  // PLATFORM_IS_POSIX_BASED (existing line 1259)

#ifdef PLATFORM_IS_WINDOWS
  if(c->opt->linker == NULL)
  {
    return link_exe_lld_coff(c, program, file_o);
  }
#endif

  const char* ponyrt = c->opt->runtimebc ? "" :  // existing line 1261

Routing logic:

--linker	Path taken
not set	Embedded LLD COFF
set	Legacy (system() via cmd /C)

When --linker is set, control falls through to the legacy Windows code at line 1441, which picks up the user-specified linker and invokes it via system().

Why this routing is simpler than Linux/macOS:

• No cross-compilation to consider (Windows cross-compilation is future work)
• No sanitizer guard needed (ponyc doesn't support sanitizer builds on Windows)
• No runtime triple check needed — PLATFORM_IS_WINDOWS is a compile-time guard; if it's defined, the target is Windows

Step 4: No CI workflow changes needed

All existing Windows CI jobs exercise the new code path automatically — no workflow changes required:

Tier 1 (PR):

• x86-64 Windows MSVC (windows-2025): .\make.ps1 -Command test with Debug and Release configs

Tier 2 (daily):

• arm64 Windows MSVC (windows-11-arm): .\make.ps1 -Command test with Debug and Release configs

Both tiers also build examples (.\make.ps1 -Command build-examples).

The existing CI jobs compile and link Pony programs. With the routing change, these programs will be linked via embedded LLD instead of link.exe. If embedded LLD produces incorrect binaries, the tests will fail — no additional test infrastructure is needed.

Step 5: Verification with verbose output

After the change, running with -V4 on Windows should show lld-link /DEBUG /NOLOGO ... instead of cmd /C ""...\link.exe" /DEBUG .... This is implicitly tested by CI (if linking fails, tests fail).

Step 6: Release notes

Classification: changed. Native Windows builds now use embedded LLD instead of the external MSVC link.exe linker. --linker provides an escape hatch to use an external linker.

Since this is a single change type, use the standard automation: create .release-notes/embedded-lld-windows.md and apply the changelog - changed label.

Release note content:

## Native Windows builds now use embedded LLD

Windows linking now uses the embedded LLD linker (COFF driver) instead of invoking the MSVC `link.exe` command. This is part of the ongoing work to eliminate external linker dependencies across all platforms.

If the embedded linker causes issues, use `--linker=<path-to-link.exe>` to fall back to the system linker.

Design Decisions

Why Windows is the simplest platform switch

Windows linking is structurally the simplest of all the platform switches because:

• No CRT objects to manage: Windows CRT initialization is handled implicitly through the standard libs (msvcrt.lib, vcruntime.lib).
• No glibc/musl or dynamic/static split: Windows has one CRT, one linking model.
• No sysroot concept: Paths are discovered via vcvars (registry + vswhere).
• Arguments are nearly identical: LLD's COFF driver (lld-link) accepts the same arguments as MSVC's link.exe. The switch is essentially replacing system("cmd /C ...") with lld::lldMain() using the same argument list.

vcvars_get() reuse

The existing vcvars_get() function discovers SDK and MSVC installation paths via the Windows registry and vswhere.exe. Embedded LLD still needs these paths to find kernel32.lib, ucrt.lib, and the MSVC runtime libraries. The discovery logic is reused unchanged.

The vcvars fields vcvars.link (path to link.exe) and vcvars.ar (path to lib.exe) are still populated by vcvars_get() but not used when embedded LLD handles linking. This is harmless — the discovery is a side effect of finding the MSVC installation path.

/LIBPATH: quoting: drop the quotes

The legacy code wraps vcvars paths in double quotes within the /LIBPATH: argument (/LIBPATH:"%s"). This is necessary because the entire link command is passed through cmd /C and system(), where shell tokenization would split on spaces in paths like C:\Program Files (x86)\....

With embedded LLD, each argument is a discrete entry in the vector — no shell involved. Including literal quote characters in the path would cause LLD to look for a path that literally includes " characters, which would fail. The embedded LLD path uses /LIBPATH:<path> without quotes, consistent with how -L<path> is handled in the ELF and Mach-O paths.

default_libs tokenization

The legacy code pastes vcvars.default_libs as a single string into the system() command, relying on shell tokenization to split it. For embedded LLD, each library must be a separate argument. strtok() on a local copy is the simplest approach and matches the string's structure (space-separated .lib names).

An alternative would be to change vcvars.c to store libraries as an array instead of a string. This would be cleaner but touches more code than necessary. If Phase 7 (cleanup) removes the legacy path entirely, vcvars.c can be refactored then.

No sanitizer guard

The Linux and macOS routing includes a sanitizer guard (#if defined(PONY_SANITIZER)) that falls back to the legacy path for native sanitizer builds. Windows doesn't need this guard because ponyc doesn't support sanitizer builds on Windows — there's no PONY_SANITIZER handling in the Windows linking code, and -fsanitize is a GCC/Clang concept.

Architecture: compile-time detection preserved

The legacy code uses _M_ARM64 and _M_X64 compile-time macros to determine the target architecture. This is preserved because Windows builds are always native (cross-compilation to Windows is future work). When cross-compilation support is added later, this would change to runtime triple inspection.

No --strip-debug on Windows

The legacy code always passes /DEBUG to link.exe and doesn't check c->opt->strip_debug. Phase 5 preserves this behavior. Adding --strip support on Windows is a separate improvement that would need its own consideration.

All LLD drivers registered

The lldMain() call registers all five LLD drivers, matching the five LLD_HAS_DRIVER declarations at the top of the file, consistent with the pattern established in Phase 4.

What doesn't change

• No CI workflow changes — existing Windows CI exercises the new path automatically
• vcvars.c path discovery — reused unchanged
• --linker escape hatch — still falls through to legacy path
• --link-ldcmd — ignored with a warning under embedded LLD (currently meaningless on Windows anyway, but now explicitly warned)
• Architecture detection — still compile-time _M_ARM64 / _M_X64
• Default system libraries — same set (kernel32.lib, msvcrt.lib, Ws2_32.lib, etc.)
• Linux/macOS linking — unaffected, uses link_exe_lld_elf() / link_exe_lld_macho()

Testing

Build command: .\make.ps1 -Command test -Config Debug

CI coverage (all existing, no new entries):

Target	Tier	Workflow
x86-64 Windows MSVC (windows-2025)	1 (PR)	pr-ponyc.yml
arm64 Windows MSVC (windows-11-arm)	2 (daily)	ponyc-tier2.yml

Verification: Running with -V4 on Windows should show lld-link /DEBUG /NOLOGO ... instead of cmd /C ""...\link.exe" /DEBUG ....

Risk Assessment

Low risk. Windows linking is the simplest platform because the argument list is a near-1:1 translation from the legacy link.exe invocation. No CRT objects, no sysroot, no static/dynamic split, no libc variants. LLD's COFF driver is specifically designed to be a drop-in replacement for link.exe. The --linker escape hatch provides an immediate workaround if anything unexpected arises.

Known risk: LLD COFF driver compatibility. LLD's COFF driver may handle some edge cases differently from MSVC's link.exe (e.g., /ignore:4099 warning suppression, PDB generation details). The existing Windows CI (x86-64 tier 1, arm64 tier 2) provides solid coverage. If LLD COFF issues surface, --linker=<path-to-link.exe> is the immediate mitigation.

Known risk: Path spaces without quoting. The switch from quoted /LIBPATH:"..." (for cmd.exe shell) to unquoted /LIBPATH:... (direct API) is a behavioral change. Windows SDK paths commonly contain spaces (e.g., C:\Program Files (x86)\Windows Kits\...). This works correctly because each argument is a discrete entry in the vector — no shell tokenization can split on spaces. LLD's COFF driver handles /LIBPATH: parsing correctly for paths with spaces when passed as individual arguments.

Files Modified

File	Change
src/libponyc/codegen/genexe.cc	Move includes outside POSIX guard, add link_exe_lld_coff(), add routing in link_exe()
.release-notes/embedded-lld-windows.md	Release notes for the change

[SeanTAllen]

Implemented in PR #4996.