Linking to the Library

Link to the library via CMake or configure your build system manually.

You can link Ultralight to your project using CMake or configure your build system manually.

The CMake package configures includes, link targets, and runtime file staging automatically. If you use another build system you can set includes and linker settings directly.

#Link via CMake

The SDK provides CMake configuration files that import library targets and stage runtime dependencies beside the compiled binary.

#Basic Configuration

To link Ultralight in CMake, find the package, link AppCore, and copy the runtime dependencies.

cmake_minimum_required(VERSION 3.15.0)
project(MyApp LANGUAGES C CXX)

find_package(Ultralight REQUIRED)

add_executable(MyApp WIN32 MACOSX_BUNDLE main.cpp)
target_link_libraries(MyApp PRIVATE Ultralight::AppCore)

# Copy the shared libraries and resources next to the executable.
ultralight_copy_runtime_files(MyApp)

if (CMAKE_SYSTEM_NAME MATCHES "Windows")
  # Use main instead of WinMain.
  set_target_properties(MyApp PROPERTIES LINK_FLAGS "/ENTRY:mainCRTStartup")
endif ()

Setting up the build requires three steps:

1. Call find_package(Ultralight REQUIRED) to import the library targets.
2. Link Ultralight::AppCore (or Ultralight::Ultralight) to your executable target.
3. Call ultralight_copy_runtime_files() to copy the shared libraries and resources next to the compiled binary.

📘 Linking Without AppCore

AppCore is optional— you only need it when calling App::Create() or using the default Platform implementations. If you create the renderer with Renderer::Create() and provide custom handlers, link Ultralight::Ultralight instead and do not ship the AppCore library.

#Locate the SDK

Pass the SDK root path to CMake using CMAKE_PREFIX_PATH when generating build files.

cmake -B build -DCMAKE_PREFIX_PATH=C:/ultralight-sdk

You can also point directly to the package folder with -DUltralight_DIR=<path>/lib/cmake/Ultralight.

#Imported Targets

The CMake package defines four layered targets— linking any target automatically pulls in each layer beneath it.

Most applications link Ultralight::AppCore, which includes every required target.

#Platform Reference Sources

AppCore includes prebuilt reference platform handlers for GPU drivers, font loaders, clipboards, file systems, CPU window surfaces (Windows and Linux only), a file logger, and audio outputs. Audio outputs require the Pro edition or higher (see Editions and Feature Macros).

If you create the renderer with Renderer::Create() or need custom handler modifications, you can build the reference implementations from source instead.

To add the reference handlers to a CMake project, include the platform directory and link Ultralight::Platform.

add_subdirectory(${ULTRALIGHT_PLATFORM_DIR} platform)
target_link_libraries(MyApp PRIVATE Ultralight::Platform)

#Link Manually

To configure another build system without CMake, add the SDK header directory, link the necessary libraries, and stage runtime files beside the compiled executable.

#Compiler Settings and Include Paths

C++ code requires a compiler configured for C++20 or later. C applications require C17 or later.

Add the SDK's include/ directory to the header search paths. This folder contains the Ultralight/, AppCore/, and JavaScriptCore/ headers.

#Link Libraries

Applications using AppCore link AppCore, Ultralight, and UltralightCore. If you create the renderer directly with Renderer::Create() and provide custom platform handlers, link Ultralight and UltralightCore instead.

Linking WebCore is optional— you only need it when calling the JavaScriptCore C API directly (the JS* functions from <JavaScriptCore/...>). The JavaScript API (js::) is part of Ultralight, so using it doesn't require linking WebCore.

#Stage Runtime Files

An application requires its runtime dependencies staged beside the compiled executable. The shared libraries sit in the same directory as the binary, while runtime resources sit inside an assets/ folder beside it.

#Shared Libraries

Runtime requirements differ from link time. Each shared library loads the layers beneath it, so every layer the application uses must sit beside the compiled binary. This includes WebCore— Ultralight loads it at runtime even when you didn't link against it.

Copy the shared libraries from the SDK's bin/ directory (.dll on Windows, .dylib on macOS, or .so on Linux):

• Applications using App::Create() — copy all four libraries: AppCore, Ultralight, WebCore, and UltralightCore.
• Applications using Renderer::Create() — copy Ultralight, WebCore, and UltralightCore. Leave AppCore out.

#Resources and the Web Inspector

Copy the SDK's resources/ folder to assets/resources/ beside the compiled executable.

If you open the Web Inspector, also copy the SDK's inspector/ folder to assets/inspector/.

#Set Run-Time Search Paths

On Windows, the OS searches the folder containing the executable for shared libraries automatically.

On macOS, the shared libraries use @rpath install names. Set the executable's rpath to @executable_path/ so the dynamic linker finds them beside the binary.

On Linux, set the executable's rpath to $ORIGIN (or configure LD_LIBRARY_PATH) so the dynamic linker resolves libraries from the application directory.

#Linux System Dependencies

The prebuilt Linux libraries require glibc 2.31 or newer.

When linking libAppCore.so, the host system also requires libX11, libX11-xcb, libxcb, libxcb-present, and libfontconfig. GTK 3 is loaded on demand only when your app displays a message box.

#Package for Distribution

For platform-specific bundling rules, install scripts, and macOS app bundle layout, see Shipping Your App.