skip to content

In CMake, how do the STATIC, SHARED, MODULE, OBJECT and INTERFACE library kinds of add_library differ?

level: middleimportance: should knowfreq 55%

answer

  1. archive, linked binary, or plugin
  2. objects without an archive
  3. no sources, only usage requirements
  4. BUILD_SHARED_LIBS picks the default

basics

~20 s

STATIC archives object files for linking into consumers, SHARED builds a library loaded at run time, MODULE builds a plugin nothing may link, OBJECT compiles sources without archiving them, and INTERFACE builds nothing and only carries usage requirements.

solid answer

~40 s

`add_library(core STATIC ...)` produces an archive (`libcore.a`, `core.lib`) whose objects the linker copies into each consumer. `SHARED` links a dynamic library (`.so`, `.dylib`, `.dll`) that consumers reference and load at run time; CMake turns on `POSITION_INDEPENDENT_CODE` for it. `MODULE` is a plugin meant for `dlopen`-style loading, and CMake refuses to link it into another target. `OBJECT` compiles sources but produces no archive; consumers take the objects through `target_link_libraries` or `$<TARGET_OBJECTS:...>`. `INTERFACE` compiles nothing and produces no file; it exists to carry usage requirements, which makes it the natural shape for a header-only library. With no kind given, `add_library` creates `STATIC`, or `SHARED` when `BUILD_SHARED_LIBS` is true.

code

cmake · 10 lines
cmake
add_library(core STATIC core.cpp)         # archive linked into consumers
add_library(render SHARED render.cpp)     # loaded at run time
add_library(exporter MODULE exporter.cpp) # dlopen-only plugin
add_library(coreobj OBJECT vec.cpp)       # objects, no archive
add_library(core_api INTERFACE)           # header-only, no build step
target_include_directories(core_api INTERFACE include)

add_executable(app main.cpp)
target_link_libraries(app PRIVATE core render coreobj core_api)
# target_link_libraries(app PRIVATE exporter)  # configure error: MODULE

go deeper

for a junior

Name the five kinds and what each produces on disk, and know that a header-only library is an INTERFACE target.

for a middle

Explain BUILD_SHARED_LIBS as the default, why MODULE is unlinkable, how OBJECT libraries hand out objects, and why INTERFACE targets accept only INTERFACE items.

for a senior

Justify the kind from deployment needs: static by default, shared for run-time sharing or separate shipping, and object libraries when a static archive would drop unreferenced registration objects.

for a principal

Treat the kind as a packaging decision: shared libraries bring symbol visibility, ABI stability and deployment costs that a team must be ready to own.

## Why the kind matters `add_library` creates a **target**, and the kind decides what the build produces and how other targets may use it. The kind changes the link line, run-time loading, symbol visibility concerns and how usage requirements behave, so choosing it is a design decision rather than a formality. | Kind | Produces | Linkable by other targets | Typical use | |---|---|---|---| | `STATIC` | archive (`libcore.a`, `core.lib`) | yes | most internal libraries | | `SHARED` | `.so`, `.dylib`, or `.dll` plus import library | yes | libraries shared between executables or shipped separately | | `MODULE` | a loadable plugin | no | plugins opened at run time | | `OBJECT` | object files only | yes (since CMake 3.12) | compiling sources once for several targets | | `INTERFACE` | nothing | yes | header-only code, groups of usage requirements | ## STATIC and SHARED A **static library** is an archive of object files. The linker pulls the objects it needs into each executable that links it, so the archive is not needed at run time. Because an archive is never itself linked, CMake records its own link dependencies and adds them when linking the consumer. A **shared library** is a linked binary that consumers reference and the loader maps at run time. For `SHARED` and `MODULE` kinds CMake sets the `POSITION_INDEPENDENT_CODE` property to `ON` automatically. On Windows, CMake expects a `SHARED` library to export symbols and produce an import library; a DLL that exports nothing is meant to be a `MODULE`. When `add_library(core core.cpp)` names no kind, the choice comes from the `BUILD_SHARED_LIBS` variable: `STATIC` when it is false or unset, `SHARED` when true. That lets one switch at configure time (`-DBUILD_SHARED_LIBS=ON`) flip every library that did not name a kind. ## MODULE A **module library** is a plugin that the program loads with `dlopen` or `LoadLibrary`. CMake forbids linking it: `target_link_libraries(app PRIVATE plugin)` fails at configure time with a message that a target of type `MODULE_LIBRARY` may not be linked into another target and that one may link only to `INTERFACE`, `OBJECT`, `STATIC` or `SHARED` libraries, or to executables with `ENABLE_EXPORTS`. ## OBJECT An **object library** compiles its sources and stops there. Other targets consume the objects in two ways: - list `$<TARGET_OBJECTS:objlib>` among their sources; - link it with `target_link_libraries`, which adds its objects *and* its usage requirements to a direct consumer. The objects are added only to targets that link the object library directly. Its usage requirements can propagate further, but its object files do not travel transitively through, for example, a shared library that linked it. ## INTERFACE An **interface library** has no build step of its own. You fill its `INTERFACE_*` properties with `target_include_directories(lib INTERFACE ...)`, `target_compile_definitions(lib INTERFACE ...)` or `target_link_libraries(lib INTERFACE ...)`, and consumers that link it receive them. Typical uses: 1. a **header-only library**, whose only requirement is an include directory and perhaps a compile feature; 2. a **bundle of settings**, such as a warnings target several libraries link to; 3. an installed and exported target that carries requirements for package users. Because it has no build specification, an interface library accepts only `INTERFACE` items in the `target_*` commands; `target_include_directories(hdr PUBLIC inc)` fails with "target_include_directories may only set INTERFACE properties on INTERFACE targets". A header-only part of `core` might look like this: ```cmake add_library(core_api INTERFACE) target_include_directories(core_api INTERFACE include) target_compile_features(core_api INTERFACE cxx_std_20) add_executable(core_tests tests.cpp) target_link_libraries(core_tests PRIVATE core_api) ``` `core_tests` compiles with the include directory and at least C++20, yet no build rule exists for `core_api`: an interface library with no sources does not even appear as a target in the generated build system. ## Choosing - Default to **`STATIC`**, or to no kind with a project-wide `BUILD_SHARED_LIBS`, unless something must be loaded or shared at run time. - Choose **`SHARED`** when several executables or other languages load the same code, or the library ships on its own schedule. - Choose **`MODULE`** only for plugins. - Choose **`OBJECT`** when the same sources must land in several targets without an intermediate archive. - Choose **`INTERFACE`** for header-only code and pure requirement bundles.

  • When a project defines core with no kind, how do you build it as a shared library without editing CMakeLists.txt?
    Configure with `-DBUILD_SHARED_LIBS=ON`. `add_library` without an explicit kind consults that variable and creates `SHARED` instead of `STATIC`. Targets that name `STATIC` or `SHARED` explicitly ignore it, which is why libraries meant to follow the project-wide switch should omit the kind.
  • If a SHARED library links an OBJECT library, does an executable linking the SHARED library also receive those object files?
    No. The objects go into targets that link the object library directly, so they end up inside the shared library, and the executable gets them through it. The object library's usage requirements do propagate through a `PUBLIC` link, so the executable still compiles with its definitions and include paths.

  • An INTERFACE library is just a static library with no sources
  • A MODULE library can be linked like a SHARED one
  • add_library without a kind always creates a static library
  • OBJECT libraries pass their object files to every transitive consumer
  • Header-only code needs a dummy .cpp file to become a target