How to Build yaml-cpp as a Shared Library (DLL/SO)

Set the CMake option YAML_BUILD_SHARED_LIBS=ON when configuring yaml-cpp to generate a shared library (.dll on Windows, .so on Linux, .dylib on macOS) instead of the default static archive.

The yaml-cpp library uses CMake for all supported platforms. While the default configuration produces a static library, a single option flag switches the build to produce dynamically linked binaries suitable for sharing across multiple applications.

The YAML_BUILD_SHARED_LIBS CMake Option

In CMakeLists.txt at line 18, the project defines the YAML_BUILD_SHARED_LIBS option that controls whether the output is a static or shared library:

option(YAML_BUILD_SHARED_LIBS "Build yaml-cpp shared library" ${BUILD_SHARED_LIBS})

The build logic at lines 39-45 evaluates this option to set the target type and labeling:

if (YAML_BUILD_SHARED_LIBS)
    set(yaml-cpp-type SHARED)
    set(yaml-cpp-label-postfix "shared")
else()
    set(yaml-cpp-type STATIC)
    set(yaml-cpp-label-postfix "static")
endif()

When YAML_BUILD_SHARED_LIBS is enabled, the yaml-cpp target is created with the SHARED attribute, causing the compiler to produce a dynamic library appropriate for the platform.

Position-Independent Code for Static Compatibility

When building a shared library is not enabled, yaml-cpp automatically enables Position-Independent Code (PIC) at line 80 in CMakeLists.txt. This ensures the static library can be safely linked into other shared objects:

if (NOT YAML_BUILD_SHARED_LIBS)
    set_property(TARGET yaml-cpp PROPERTY POSITION_INDEPENDENT_CODE ${YAML_ENABLE_PIC})
endif()

This distinction is important when mixing static and shared libraries in larger projects.

Building yaml-cpp as a Shared Library from Source

To compile yaml-cpp as a shared library, clone the repository and pass the configuration flag during the CMake generation step:

git clone https://github.com/jbeder/yaml-cpp.git
cd yaml-cpp
mkdir build && cd build
cmake -DYAML_BUILD_SHARED_LIBS=ON ..
cmake --build .

On Windows with Visual Studio, you may need to specify the configuration:

cmake -DYAML_BUILD_SHARED_LIBS=ON .. -A x64
cmake --build . --config Release

This process generates libyaml-cpp.so on Linux, libyaml-cpp.dylib on macOS, or yaml-cpp.dll (plus import library yaml-cpp.lib) on Windows.

Installing and Linking the Shared Library

The install rules defined at lines 47-52 in CMakeLists.txt handle the proper placement of binaries across platforms:

install(TARGETS yaml-cpp
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})

Runtime files (DLLs) go to the binary directory, while shared objects (.so/.dylib) and import libraries go to the library directory.

To consume the library in a downstream CMake project, use the exported yaml-cpp::yaml-cpp target:

cmake_minimum_required(VERSION 3.15)
project(MyApp)

find_package(yaml-cpp REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE yaml-cpp::yaml-cpp)

The target name remains identical whether you link against the static or shared version.

Platform-Specific Runtime Considerations

When deploying applications that link against the shared library, ensure the operating system can locate the binary at runtime:

• Linux: Set the LD_LIBRARY_PATH environment variable to include the installation directory, or install to a standard system path like /usr/local/lib and run ldconfig.
• Windows: Place yaml-cpp.dll in the same directory as your executable, or add the library directory to the PATH environment variable.
• macOS: Use DYLD_LIBRARY_PATH to specify custom library locations, or install to /usr/local/lib covered by the default rpath.

Summary

• Pass -DYAML_BUILD_SHARED_LIBS=ON to CMake to switch from static to shared library output.
• The option is defined in CMakeLists.txt at line 18 and controls the target type at lines 39-45.
• Static builds automatically enable Position-Independent Code at line 80 for compatibility with shared object linking.
• Shared libraries install to ${CMAKE_INSTALL_BINDIR} for DLLs and ${CMAKE_INSTALL_LIBDIR} for .so/.dylib files.
• Link using the yaml-cpp::yaml-cpp target in downstream CMake projects regardless of library type.

Frequently Asked Questions

How do I enable shared library build in yaml-cpp?

Pass -DYAML_BUILD_SHARED_LIBS=ON to CMake during the configuration step. This sets the internal yaml-cpp-type variable to SHARED in CMakeLists.txt (lines 39-40), producing a .dll, .so, or .dylib file instead of a static archive.

What is the default library type for yaml-cpp?

By default, yaml-cpp builds as a static library. The YAML_BUILD_SHARED_LIBS option defaults to the value of CMake's global BUILD_SHARED_LIBS variable if defined; otherwise, the static configuration is selected at lines 43-44 of CMakeLists.txt.

Do I need to change my C++ code when switching from static to shared?

No. The public API in include/yaml-cpp/yaml.h remains identical regardless of linkage type. Your include statements and parsing code work unchanged; only the CMake configuration and deployment steps differ between static and shared builds.

How do I handle runtime library paths on Linux?

Either install the shared library to a standard system path like /usr/local/lib (which typically requires administrator privileges), or set the LD_LIBRARY_PATH environment variable to include your custom installation directory before running your executable.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}