Configure Static libavif Build Using CMake

This article provides a direct guide on how to configure and compile a static build of libavif, the reference library for the AVIF image format, using CMake. You will learn the specific CMake configuration flags required to disable shared libraries and ensure that both libavif and its associated codecs are compiled as static archives.

Step 1: Obtain the Source Code and Dependencies

To build libavif statically, you need the source code. You must also ensure that the AV1 codecs (such as aom, dav1d, or rav1e) are built statically so they can be bundled or linked properly.

The easiest way to handle dependencies for a static build is to use the helper scripts provided in the ext directory of the libavif repository.

git clone https://github.com/AOMediaCodec/libavif.git
cd libavif

To build the aom codec locally and statically, run the helper script before configuring CMake:

cd ext
# On Linux/macOS:
./aom.cmd
# On Windows (cmd):
aom.cmd
cd ..

Step 2: Configure the CMake Build

To configure a static build, the most critical CMake variable to set is BUILD_SHARED_LIBS to OFF. This tells CMake to generate static libraries (.a on Unix-like systems, or .lib on Windows) instead of dynamic ones.

Run the following CMake command from the root of the libavif directory:

cmake -S . -B build \
  -DBUILD_SHARED_LIBS=OFF \
  -DAVIF_CODEC_AOM=LOCAL \
  -DAVIF_LOCAL_AOM=ON \
  -DAVIF_BUILD_APPS=OFF

Explanation of the CMake Flags:

-DBUILD_SHARED_LIBS=OFF: Disables the creation of shared/dynamic libraries, forcing CMake to output a static library (libavif.a or avif.lib).
-DAVIF_CODEC_AOM=LOCAL: Instructs libavif to use the local aom sources you downloaded in the ext directory.
-DAVIF_LOCAL_AOM=ON: Tells the build system to compile the local aom library statically alongside libavif.
-DAVIF_BUILD_APPS=OFF: Optional. Disables building the command-line tools (avifenc, avifdec) if you only need the static library itself.

Step 3: Build the Library

Once the configuration is complete, compile the library using the CMake build tool:

cmake --build build --config Release

For multi-core compilation to speed up the process, you can append the parallel build flag:

cmake --build build --config Release --parallel

Step 4: Locate the Static Library

After the build process completes successfully, the static library file will be located in the build directory:

Linux/macOS: build/libavif.a
Windows: build/Release/avif.lib

When linking this static library into your own application, ensure you also link against any dependencies used during the build, such as libaom and standard system math/threading libraries (e.g., pthread on Linux).