cmd/link, runtime: document Windows DLL package init mechanism

[Copilot]

Windows DLLs built with -buildmode=c-shared or -buildmode=c-archive use the .ctors section to invoke package init functions before any exported functions are called. This mechanism was undocumented in the codebase.

Changes

• cmd/link/internal/ld/pe.go: Document addInitArray() function explaining:

  • .ctors section creation and purpose
  • Windows loader processing of function pointers
  • Runtime initialization entry point (_rt0_{arch}_windows_lib)
  • Parallel with ELF .init_array mechanism

• runtime/rt0_windows_*.s (amd64, 386, arm64): Clarify:

  • When _rt0_{arch}_windows_lib is invoked by Windows loader
  • Distinction between c-shared (DLL) and c-archive (static library) paths
  • Initialization flow: runtime setup → package inits → return to loader

How It Works

1. Linker creates .ctors section containing pointer to _rt0_{arch}_windows_lib
2. Windows loader processes .ctors on DLL load, calling the entry point
3. Entry point initializes Go runtime and executes package inits in dependency order
4. Control returns to loader; exported functions are now safe to call

This is the Windows equivalent of .init_array on ELF systems.

Original prompt

How windows dll's implement packages init functions?

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.