Link Boundaries and Binary Size

CNA snapshot c6dec91f  ·  new since the 0.1.0 release  ·  source: docs/link-size-architecture.md

What a program contains

Each CNA module is a static archive, and a static link copies an archive member into an executable only when something already in the executable references a symbol it defines. A feature a program does not use is therefore not linked, provided nothing that is used names it indirectly. CNA keeps that true by cutting every structural reference that used to drag unrelated subsystems in, and it checks the result with link-footprint gates in its test suite.

The boundaries

Before this work, single references pulled whole subsystems into every program: one Guide call reached the Gamer Services client, libcurl and the embedded avatar catalog; every ContentManager named every content reader; Game’s constructor registered every .xnb reader; FrameworkDispatcher::Update called straight into streaming audio, the microphone and the media player; SpriteBatch::Begin used dynamic_cast on the five stock effects. Each such reference is now cut where the dependency is not real. The main boundaries:

Renderers are a build-time choice as before: the generated registry lists only the renderers a build compiles, one by default (see Runtime Renderer Selection).

What changed for content loading

A Game still declares all 61 built-in XNB readers registered (60 on toolchains without a native 128-bit integer), every ContentManager declares every built-in .cnb loader, and ContentTypeReaderManager, CnbLoaderRegistry and GetXnbReaderUsageSummary() answer queries, removals and re-registrations as they did when everything was registered eagerly. What changed is when a reader is installed: the first Load<T> of a type installs that type’s family, with or without a Game, including the value readers its files may name (a Song’s duration, a Video’s frame rate, a Model’s Tag); asking a registry for a reader or loader object by name installs everything. A reader you removed stays removed until the built-ins are registered again (a new Game, a new ContentManager, or RegisterBuiltinLoaders() for .cnb loaders). See XNB Loading.

Build options

These options change what is built or how it is optimized. None of them is needed to keep an unused feature out of a program.

SDL3_image is no longer built and its submodule is gone: nothing in CNA used it, and images are decoded by CNA’s own loader as before.

A size-oriented Release consumer configures CNA with:

cmake -S . -B build -DCMAKE_BUILD_TYPE=MinSizeRel \
      -DCNA_SHARED_LIBRARY=OFF -DCNA_OPTIMIZE_FOR_SIZE=ON   # optionally -DCNA_ENABLE_IPO=ON

and links only the module targets it needs:

add_subdirectory(path/to/cna CNA)
add_executable(MyGame main.cpp)
target_link_libraries(MyGame PRIVATE CNA::Runtime)         # Game, graphics, input, audio, content
target_link_libraries(MyGame PRIVATE CNA::GamerServices)   # only if it uses the Guide

CNA’s own complete example of a 2D consumer is tests/link_footprint/footprint_2d_game.cpp.

One measured game

CNA measured the effect on one game, Mobile Eggbert (a 2D game using textures, sounds, Guide.IsTrialMode and Guide.ShowMarketplace), on Linux x86-64 with OPENGLES3, GCC 14 and mold, before and after this work, with the same game source:

About 30 MB of the “before” size was the embedded avatar catalog, which this game never drew. These are CNA’s recorded figures for one game, one toolchain and one linker; nothing was re-measured for this page, and they are not a size guarantee for other programs. The same record notes what a 2D game still contains and why: sharp-runtime’s Decimal (about 30 KB, through the virtual BinaryReader::ReadDecimal), and, only in a build that opts into compiled XNA effects, MojoShader and the renderer’s compiled-effect support.

Checking a binary

• Sizes: size -A game, objcopy --strip-debug, strip. Debug information is most of a Debug executable and is not shipped; compare stripped sizes, and .rodata for embedded data.
• Why is X linked? Ask the linker that produced the binary, with the same command line: mold -Wl,--print-dependencies, lld -Wl,--why-extract=why.txt, or GNU ld -Wl,-Map=game.map followed by tools/link_audit/why_linked.py game.map --why X; tools/link_audit/link_closure.py lists every reference into an archive member.
• Regression gates: LinkFootprint_2DGame, LinkFootprint_GamerServicesGame, LinkFootprint_FullFeatures, LinkFootprint_CapabilityQuery, LinkFootprint_CameraOnly and LinkFootprint_TrayOnly (cmake/Tests/LinkFootprint.cmake, scripts/check_link_footprint.py), and the ModuleLinkClosure_* probes, which pin the archives each module’s consumer links. They read the probes with the toolchain’s nm and report a skip when it is unavailable. They are registered tests; this page did not run them.

Linkers and the C++ runtime

GNU ld, lld and mold must extract the same archive members, and they can differ when a shared library needs a standard-library symbol that a not-yet-extracted CNA object also defines (with C++20 and later, every CNA object carries weak copies of the std::string members it uses). CNA measured mold linking the service client, the system Guide and the avatar catalog into a multi-renderer 2D game that way. So a program that links CNA’s targets with a shared C++ runtime on ELF now names the runtime ahead of CNA’s archives (CNA::BuildConfig adds -Wl,--push-state,--as-needed -lstdc++ -Wl,--pop-state, or -lc++ for libc++), and the three linkers then extract the same members. A program that names CNA’s archives on a hand-written link line instead of linking its targets does not get this.

CNA_CXX_RUNTIME_LINKAGE decides it per program and configuration: SHARED gives every program the option and STATIC none; AUTO (the default) reads each program’s flags and the targets it links, keeps a static runtime wherever -static, -static-pie, -static-libstdc++, -nostdlib, -nostdlib++ or -nodefaultlibs is asked for (-static-libgcc alone does not count), and errs towards static where it cannot see the answer. Declare STATIC for a static runtime that no CMake setting shows, such as a compiler wrapper or a hand-named -Wl,-Bstatic -lstdc++. With a static runtime CNA adds nothing, and naming the static runtime first (target_link_options(MyGame PRIVATE "SHELL:-Wl,--push-state,-Bstatic -lstdc++ -Wl,--pop-state")) gives each linker the small closure again.

What it means for existing C++ code

Rebuild C++ consumers against this snapshot. The boundary work added virtual functions and changed class layouts, so C++ programs and libraries compiled against an earlier CNA are not binary-compatible with it. Source that only calls these APIs compiles unchanged. The visible changes:

• IPlatform::Supports(PlatformCapability) answers one capability; IPlatform::GetCamera() and GetTray() are no longer virtual and create the service on their first call. A custom IPlatform implementation overrides the protected GetCameraService() and GetTrayService() instead. Game::GetPlatformCapabilitiesEXT() reads the capability set on its first call, so an SDL3 game that never asks about cameras no longer starts SDL’s camera subsystem.
• Effect::IsStockEffectEXT() reports XNA’s five stock effects without RTTI, and Texture::AsTextureCubeEXT()/AsTexture3DEXT() answer what a dynamic_cast would; both are CNAEXT extensions.
• GraphicsDevice::GetShaderDialectEXT() returns the public CNA::ShaderDialectEXT from CNA/ShaderDialectEXT.hpp; the enumerators and values are unchanged.

The C API’s headers did not change for this work; see the Experimental C API for its own versioning.