# Link the runtime into your project
Add the dotLottie C header and library to a Makefile, CMake project, Xcode target, or Android build, and resolve the system libraries it depends on.

Once you have a library and a `dotlottie_player.h` for your target, integrating it is ordinary C library work: add the header's directory to your include path, add the library to your link line, and make sure the shared library can be found at runtime.

## What you need on the link line

| Flag                | Value                                            |
| ------------------- | ------------------------------------------------ |
| Include path        | The directory containing `dotlottie_player.h`    |
| Library search path | The directory containing the library             |
| Library name        | `dotlottie_player` or `dotlottie_rs` — see below |

<Callout type="warning" title="The library name depends on how you built it">
  A direct `cargo rustc` build produces `libdotlottie_rs`, so you link `-ldotlottie_rs`. The `make native`, `make
    android-*`, and `make windows-*` targets **rename** the artifact to `dotlottie_player`, so you link
  `-ldotlottie_player`. Linux packaged builds keep the `libdotlottie_rs` name. Check the filename before writing your
  link flags.
</Callout>

## Include the header

The header is generated with C++ compatibility, so the same include works from both languages and no `extern "C"` wrapper is needed:

```c
#include "dotlottie_player.h"
```

## Add it to your build

<Tabs
  defaultValue="make"
  items={[
  { label: 'Make / GCC / Clang', value: 'make' },
  { label: 'CMake', value: 'cmake' },
  { label: 'Xcode', value: 'xcode' },
  { label: 'Android', value: 'android' },
]}
>
  <TabsContent value="make">
    ```make
    DOTLOTTIE_DIR = release/native/dotlottie-player

    player: main.c
    	$(CC) main.c \
    		-I$(DOTLOTTIE_DIR)/include \
    		-L$(DOTLOTTIE_DIR)/lib \
    		-ldotlottie_player \
    		-o $@
    ```

    Because the library is shared, the loader has to find it when you run the program. During development the simplest approach is an environment variable:

    ```bash
    LD_LIBRARY_PATH=release/native/dotlottie-player/lib ./player animation.lottie
    ```

    On macOS the variable is `DYLD_LIBRARY_PATH`. For anything you ship, embed a run path instead so no environment setup is needed:

    ```bash
    -Wl,-rpath,'$$ORIGIN/../lib'        # Linux
    -Wl,-rpath,@executable_path/../lib  # macOS
    ```
  </TabsContent>

  <TabsContent value="cmake">
    ```cmake
    cmake_minimum_required(VERSION 3.16)
    project(dotlottie_demo C)

    set(DOTLOTTIE_DIR ${CMAKE_SOURCE_DIR}/release/native/dotlottie-player)

    add_library(dotlottie_player SHARED IMPORTED)
    set_target_properties(dotlottie_player PROPERTIES
      IMPORTED_LOCATION "${DOTLOTTIE_DIR}/lib/libdotlottie_player.so"
      INTERFACE_INCLUDE_DIRECTORIES "${DOTLOTTIE_DIR}/include"
    )

    add_executable(dotlottie_demo main.c)
    target_link_libraries(dotlottie_demo PRIVATE dotlottie_player)
    ```

    Point `IMPORTED_LOCATION` at `.dylib` on macOS or `.dll.lib` on Windows. To link the static library instead, declare it as `STATIC IMPORTED` and use the `.a` or `.lib` file — then add the system libraries listed under [Resolve system dependencies](#resolve-system-dependencies).
  </TabsContent>

  <TabsContent value="xcode">
    Use the XCFramework produced by `make apple`, which contains every slice and its module map:

    1. Drag `release/apple/DotLottiePlayer.xcframework` into your Xcode project.
    2. In your target's **General** tab, add it under **Frameworks, Libraries, and Embedded Content**.
    3. Set it to **Embed & Sign** for iOS and macOS application targets.

    The header is the framework's umbrella header, so Swift and Objective-C can import the C API as a module without a bridging header:

    ```swift
    import DotLottiePlayer

    let player = dotlottie_new_player(0)
    ```

    From Objective-C or C++, include it as a framework header:

    ```objc
    #import <DotLottiePlayer/dotlottie_player.h>
    ```

    If you built with the WebGPU backend, also embed `release/apple/WgpuNative.xcframework`.
  </TabsContent>

  <TabsContent value="android">
    Copy the build output into your Gradle module so the `jniLibs` tree is picked up automatically:

    ```text
    app/src/main/
    ├── cpp/include/dotlottie_player.h
    └── jniLibs/
        ├── arm64-v8a/
        │   ├── libdotlottie_player.so
        │   └── libc++_shared.so
        └── armeabi-v7a/
            └── ...
    ```

    Then link it from your native module's `CMakeLists.txt`:

    ```cmake
    add_library(dotlottie_player SHARED IMPORTED)
    set_target_properties(dotlottie_player PROPERTIES
      IMPORTED_LOCATION
        ${CMAKE_SOURCE_DIR}/src/main/jniLibs/${ANDROID_ABI}/libdotlottie_player.so
      INTERFACE_INCLUDE_DIRECTORIES
        ${CMAKE_SOURCE_DIR}/src/main/cpp/include
    )

    target_link_libraries(my_native_lib PRIVATE dotlottie_player)
    ```

    Both `.so` files must ship in the APK. Gradle packages everything under `jniLibs/<abi>/` automatically, so keep `libc++_shared.so` next to the player.

    If your animations contain audio, call `dotlottie_init_android()` once with your `JavaVM` and Android context before loading them.
  </TabsContent>
</Tabs>

## Resolve system dependencies

The runtime links a few system libraries depending on the features you built with. Shared library builds resolve these for you; **static builds require you to add them explicitly**.

| Condition              | Additional libraries                                     |
| ---------------------- | -------------------------------------------------------- |
| Always (ThorVG is C++) | The C++ standard library — `-lstdc++` or `-lc++`         |
| Android                | `libc++_shared.so`, shipped alongside the player         |
| `tvg-threads` on Linux | `-lpthread`                                              |
| `tvg-wg` on Linux      | `-lvulkan`                                               |
| `tvg-wg` on macOS      | `Metal`, `QuartzCore`, `Foundation`, `AppKit` frameworks |
| `tvg-wg` on iOS        | `Metal`, `QuartzCore`, `Foundation`, `UIKit` frameworks  |

Linking from C rather than C++ is fine, but the C++ runtime still has to be on the link line because ThorVG is C++. Linking with `clang++`/`g++` instead of `clang`/`gcc` is the easiest way to get that right.

## Verify the link

A minimal translation unit is enough to confirm the header and library agree:

```c
#include "dotlottie_player.h"
#include <stdio.h>

int main(void) {
  DotLottiePlayer *player = dotlottie_new_player(0);
  printf("player created: %s\n", player ? "yes" : "no");
  dotlottie_destroy(player);
  return 0;
}
```

If this compiles, links, and prints `player created: yes`, your integration is correct.

## Next steps

- [Render your first animation](/en/runtimes/distributions/native/v0.x/first-animation) — load a file and draw frames
- [How the C API works](/en/runtimes/distributions/native/v0.x/how-the-c-api-works) — handles, results, and ownership