Link the dotLottie Native Runtime into a C or C++ Project

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

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.

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:

#include "dotlottie_player.h"

Add it to your build

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:

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:

-Wl,-rpath,'$$ORIGIN/../lib'        # Linux
-Wl,-rpath,@executable_path/../lib  # macOS

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:

#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 — load a file and draw frames
How the C API works — handles, results, and ownership

Link the runtime into your project