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

> Learn to build yaml-cpp as a shared library DLL SO by setting the CMake option YAML_BUILD_SHARED_LIBS=ON. Get dynamic linking for your C++ projects.

- Repository: [Jesse Beder/yaml-cpp](https://github.com/jbeder/yaml-cpp)
- Tags: how-to-guide
- Published: 2026-07-11

---

**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`](https://github.com/jbeder/yaml-cpp/blob/main/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:

```cmake
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:

```cmake
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`](https://github.com/jbeder/yaml-cpp/blob/main/CMakeLists.txt). This ensures the static library can be safely linked into other shared objects:

```cmake
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:

```bash
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:

```bash
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`](https://github.com/jbeder/yaml-cpp/blob/main/CMakeLists.txt) handle the proper placement of binaries across platforms:

```cmake
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
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`](https://github.com/jbeder/yaml-cpp/blob/main/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`](https://github.com/jbeder/yaml-cpp/blob/main/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`](https://github.com/jbeder/yaml-cpp/blob/main/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`](https://github.com/jbeder/yaml-cpp/blob/main/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.