Skip to content

CONCEPT Cited by 1 source

Symbol renamespacing

Definition

Symbol renamespacing is the automated rewrite of a C++ codebase to place all of its symbols inside a flavor-specific namespace, so that multiple otherwise-identical copies of the library can coexist in the same binary without ODR violations.

Example from Meta's WebRTC shim:

webrtc::*            →   webrtc_latest::*    (upstream copy)
webrtc::*            →   webrtc_legacy::*    (legacy fork copy)

Every fully-qualified name in the flavor's source tree is rewritten by a scripted pass, so every symbol in the final compilation is unique from its counterpart in the other flavor.

Why scripted, not manual

libwebrtc contains thousands of types, free functions, globals, and enums across hundreds of files. Manually renamespacing each one is a multi-engineer-month task prone to error. Meta's approach:

"We built scripts that systematically rewrite every C++ namespace in a given WebRTC version, so the webrtc:: namespace in the latest upstream copy becomes webrtc_latest::, while the legacy copy becomes webrtc_legacy::. This rename was applied to every external namespace in the library." (sources/2026-04-09-meta-escaping-the-fork-webrtc-modernization)

The scripts run against each new upstream release — so the renaming cost is amortized across every upgrade, not paid once.

Handling non-namespaced symbols

Not everything in a C++ codebase lives in a namespace. The shim's full renamespacing strategy covers:

  1. Namespaced symbols — scripted rewrite of namespace declarations and fully-qualified usages.
  2. Global C functions, free variables, non-namespaced classes — moved into flavor-specific namespaces where possible; where not possible (e.g. extern "C" symbols with fixed names), given flavor-specific identifier suffixes.
  3. Macros — RTC_CHECK / RTC_LOG and similar preprocessor symbols don't respect namespaces. Meta's handling: "removing spurious includes, renaming rarely-used macros, or sharing internal WebRTC modules across versions where possible, like rtc_base." The last sub-case intentionally avoids renamespacing for macros that are safe to share.

Shared-module optimization

Not every internal module requires two copies. Some — rtc_base is the WebRTC example — are stable enough across flavors that one shared copy is safe. Sharing shrinks binary size and cuts the shim surface. The trade-off: if a future upstream release changes the shared module in a flavor-incompatible way, the shared-module assumption breaks and that module has to move back to per-flavor.

Relationship to the shim

Symbol renamespacing makes dual-stack linking possible. The shim layer sits on top of a renamespaced binary, choosing between webrtc_legacy::* and webrtc_latest::* at runtime. The bulk using declarations technique then imports the chosen flavor back into a familiar webrtc:: namespace for existing call sites.

Seen in

Last updated · 319 distilled / 1,201 read