Gcc

Developer reference: this page includes exported implementation details. BUILD authors should prefer the User API reference.

GCC_TOOL

const GCC_TOOL

Undocumented.

GCC_GRAPH_TOOL_NAMES

const GCC_GRAPH_TOOL_NAMES

Undocumented.

gccArtifactName()

gccArtifactName(version, plat)

Return the toolchain archive filename for a version and platform: a Bootlin tarball name on Linux, a WinLibs zip name on Windows.

Returns: string

gccDownloadUrl()

gccDownloadUrl(version, plat)

Return the toolchain download URL for a version and platform: Bootlin on Linux, WinLibs on Windows.

Returns: string

gccSupportedPlatforms()

gccSupportedPlatforms()

Return the platforms Bootlin publishes a prebuilt gcc toolchain for. Bootlin only ships Linux; the arch set comes from the module's BOOTLIN_ARCH map.

Returns: Array<{ os: string, arch: string }>

gccCacheKey()

gccCacheKey(version, plat)

Return the named-cache key for a gcc toolchain version and platform.

Returns: string

GccToolchain (implementation class)

class GccToolchain

Implementation class. BUILD files should use gccToolchain().

Undocumented.

gccToolchain()

gccToolchain(version, opts = {})

Declare a gcc toolchain version and optionally set it as the default. toolchain release version on Linux (e.g. "2025.08-1"), WinLibs release tag on Windows (e.g. "16.1.0posix-14.0.0-ucrt-r4") — see requireSupportedPlatform's own comment for why these don't share a vocabulary. A plain string is used as-is for whichever platform is active; pass an object keyed by os to pin both platforms from one call (see this module's own pinned default at the bottom of the file). matching lockfile entry (warns instead of failing). Address of a workspace-owned lockfile instead of the shipped one; a plain string applies to the active platform, an object keyed by os pins each.

Returns: object Target handle for this gcc toolchain.

gccGraphTool()

gccGraphTool(version, { unsafeSystemPaths = false } = {})

Build the managed GCC distribution as a graph-native tool. launchers first on PATH instead of Bootlin's guard wrappers.

isGccToolchain()

isGccToolchain(toolchain)

Undocumented.

gccToolchainRecord()

gccToolchainRecord(tool, version)

Build the frozen cc-toolchain provider record for a given (tool, version) pair — the gcc side of the shared contract (kind, taskInputs, commands, cmakeConfigure, resolvesToolName, toolSpec, resolveState, edgeEnv; see rules/c/msvc's and rules/c/zig's own toolchain constructors for the other two providers, and rules/c/toolchain.js's ccToolchainForPlatform() for the platform-indexed union all three plug into). Exported (not just gccGraphToolchain() itself) so a test can build a record around a fake tool/version without gccGraphTool()'s real download+install task chain — see rules/c/index_test.js's own fakeGccGraphToolchain().

Returns: { kind: string, tool: object, version: string }

gccGraphToolchain()

gccGraphToolchain(version)

Graph-native gcc toolchain: gccGraphTool() wrapped with version metadata, mirroring rustGraphToolchain()'s shape (//rules/rust/toolchain) but scaled to gcc's single install directory (like Odin's one-directory case). See gccToolchainRecord() above for the shared cc-toolchain provider contract this also conforms to.

Returns: { kind: string, tool: object, version: string }

defaultGccGraphToolchain()

defaultGccGraphToolchain()

Return the currently configured default gcc toolchain as graph-native handles, or null if none is declared.

Returns: object|null

installGccToolchain()

installGccToolchain(version, source)

Install a local gcc toolchain directory into the named cache.

Returns: string|null Local path to the cached toolchain root.

resolveGccToolchainVersion()

resolveGccToolchainVersion(version)

Resolve an explicit or default gcc toolchain version.

Returns: string|null

defaultGccToolchainVersion()

defaultGccToolchainVersion()

Return the currently configured default gcc toolchain version.

Returns: string|null

defaultGccToolchain()

defaultGccToolchain()

Return the currently configured default gcc toolchain target handle.

Returns: object|null

gccGraphToolchainDir()

gccGraphToolchainDir(version)

The real, absolute host directory (bin/ inside it) a resolved gcc graph toolchain installed into, via the same named-cache cacheGet() real host path gccRustLinkDriverEnv() uses — usable directly from any sandbox (no tool mount needed), unlike exec.tool()'s sandbox-mount-relative path. See gccCMakeCompilerArgs() below for why rules/c/cmake needs this specifically (a real path, not a sandbox-relative one).

Returns: string

winlibsGccVersion()

winlibsGccVersion(version)

Parse the plain GCC release number out of a WinLibs release tag (see WINLIBS_TAG_RE's own doc comment for the tag shape), e.g. "16.1.0posix-14.0.0-ucrt-r4" -> "16.1.0". Needed because WinLibs' archive lays out its per-version runtime libs (libgcc.a, libgcc_eh.a) under lib/gcc/x86_64-w64-mingw32//, and that path segment is the bare GCC number, not the full WinLibs tag.

Returns: string

gccWindowsRuntimeArchives()

gccWindowsRuntimeArchives(version)

Real, absolute paths to the mingw-w64 runtime archives a raw COFF linker (lld-link, radlink, ...) needs that a normal gcc/clang frontend invocation would otherwise add on its own via its default-libs spec: the C++ ABI/runtime support library (new/delete, RTTI, exceptions), the SEH unwinder and its thread-local-storage emulation (which itself needs pthread), the pthreads API BoringSSL's Windows build still compiles against (mingw's own winpthreads implementation, not real POSIX threads), the mingw libc extensions GCC-compiled C sources assume (e.g. strcasecmp, the ___chkstk_ms stack-probe thunk), and — surprisingly, since this isn't GCC/mingw-specific at all — the UCRT C runtime itself (memcpy/malloc/strlen/...), which even a pure-Odin object file references and which Odin's own "default" (MSVC link.exe) backend otherwise supplies automatically but its lld-link path does not. Confirmed necessary by a real odin build failure once Odin's Windows link step was switched to -linker:lld (see rules/odin/index.js) to work around MSVC link.exe rejecting GCC-produced COMDAT sections: without these, linking anything at all on Windows via lld-link fails with dozens of "undefined symbol" errors, from plain UCRT functions up through C++-only ones like __gxx_personality_seh0, _Unwind_Resume, and operator new once a GCC/mingw-compiled C++ dependency (BoringSSL, webview) is in the link too.

Returns: string[]

gccCMakeCompilerArgs()

gccCMakeCompilerArgs(version, unsafeSystemPaths)

Real, absolute CMAKE_C_COMPILER/CMAKE_CXX_COMPILER/CMAKE_AR/CMAKE_RANLIB arguments for a resolved gcc graph toolchain, for use by rules/c/cmake's graph-native configure step (see #31/#62). Uses gccGraphToolchainDir()'s real host path rather than exec.tool()'s sandbox-mount-relative one — CMake bakes this value into build.ninja, which later replay actions read from a different sandbox than the one that ran configure, so it must be a path valid everywhere, not just within configure's own sandbox (the exact bug class gccRustLinkDriverEnv's own docstring already covers for rustc's -C linker=). Pinning CMAKE_RANLIB here matters beyond consistency with CMAKE_AR: left unset, CMake's own find_program() falls back to whatever ranlib exists on the host running imp build, baking that host-dependent absolute path (e.g. /usr/bin/ranlib) into build.ninja — a real hermeticity gap, and the root cause of #98 (CMake replay failing with "ranlib: not found" once that baked-in host path got rewritten to a bare name with no matching mount). CMAKE_CXX_COMPILER at the "-unsafe-paths" aliases (see gccGraphTool()'s own install-step comment) instead of the plain wrapper-backed ones, so CMake-supplied -I/-isystem/-L flags under /usr/include or /usr/lib aren't rejected by Bootlin's toolchain-wrapper. CMAKE_AR/CMAKE_RANLIB are unaffected — ar/ranlib aren't wrapped.

Returns: string[]

gccGraphToolSpec()

gccGraphToolSpec(version, name)

A legacy-shaped {name, cache, key, binDirs} tool spec for one of gcc's graph-install wrapper aliases ("clang"/"cc"/"c++"/"ar"), mountable directly via exec.action({tools: [...]})'s existing legacy-tool-spec passthrough (the same shape cmakeTool()/nativeToolSpec() already produce) — no cacheGet()/absolute-path plumbing needed by the caller. Needed because rules/c/cmake's graph-native replay bakes gccCMakeCompilerArgs()'s real absolute compiler paths into build.ninja at configure time, then rewrites them back to bare tool names ("clang"/"c++"/"ar") before replaying each edge (see ninja_graph.js's rewriteToolInvocations()) — those bare names need a real mount, not another absolute-path env trick, to resolve to this pinned gcc toolchain rather than whatever (if anything) is on a bare hermetic sandbox's PATH.

Returns: { name: string, cache: string, key: string, binDirs: string[] }

• rules/c/gcc/BUILD.js