Compile libavif for iOS with Xcode

This article provides a straightforward, step-by-step guide on how developers can compile the libavif library for iOS using Xcode. You will learn how to set up the build environment, configure CMake for iOS cross-compilation, build the static library using Xcode command-line tools, and package the output into an XCFramework for seamless integration into iOS applications.

Prerequisites

Before starting, ensure you have the following tools installed on your macOS system:

Xcode and Xcode Command Line Tools.
CMake (can be installed via Homebrew using brew install cmake).
Git for cloning the source code.

Step 1: Clone the libavif Repository

Open your terminal and clone the official libavif repository. It is recommended to clone the repository recursively to fetch any required submodules:

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

Step 2: Set Up an iOS CMake Toolchain

To cross-compile library code for iOS architectures (like arm64 for physical devices and x86_64/arm64 for the Simulator), you need an iOS CMake toolchain file.

You can use a widely adopted public toolchain file like ios.toolchain.cmake (available on GitHub from user leetal). Download this file and place it in your parent directory or the root of your libavif folder.

Step 3: Configure the Build with CMake

You need to generate Xcode projects for both the physical iOS device and the iOS Simulator.

Create a separate build directory for the physical device build:

mkdir build_ios && cd build_ios
cmake .. \
  -G Xcode \
  -DCMAKE_TOOLCHAIN_FILE=../ios.toolchain.cmake \
  -DPLATFORM=OS64 \
  -DAVIF_BUILD_APPS=OFF \
  -DAVIF_BUILD_TESTS=OFF
cd ..

Next, create a build directory for the iOS Simulator build:

mkdir build_sim && cd build_sim
cmake .. \
  -G Xcode \
  -DCMAKE_TOOLCHAIN_FILE=../ios.toolchain.cmake \
  -DPLATFORM=SIMULATOR64 \
  -DAVIF_BUILD_APPS=OFF \
  -DAVIF_BUILD_TESTS=OFF
cd ..

Note: By default, libavif requires an external decoder/encoder codec (such as libaom or dav1d). To build a fully functioning AVIF decoder, you should compile your chosen codec for iOS first, and pass its path to CMake using flags like -DAVIF_CODEC_AOM=ON.

Step 4: Build the Library using Xcode

With the Xcode project files generated by CMake, you can compile the static libraries using the xcodebuild command line tool.

Run the following command to build the library for physical iOS devices:

xcodebuild -project build_ios/AVIF.xcodeproj -scheme avif -configuration Release -sdk iphoneos build

Run the following command to build the library for the iOS Simulator:

xcodebuild -project build_sim/AVIF.xcodeproj -scheme avif -configuration Release -sdk iphonesimulator build

Step 5: Package the Libraries into an XCFramework

To make the compiled library easy to distribute and use inside Xcode projects, package the device and simulator .a static libraries into a single unified XCFramework.

Run the following command in your terminal:

xcodebuild -create-xcframework \
  -library build_ios/Release-iphoneos/libavif.a \
  -headers include \
  -library build_sim/Release-iphonesimulator/libavif.a \
  -headers include \
  -output libavif.xcframework

Step 6: Integrate into Xcode

Open your iOS target project in Xcode.
Drag and drop the newly created libavif.xcframework folder into the Frameworks, Libraries, and Embedded Content section of your target settings.
Ensure the framework is set to Do Not Embed (since it is a static library package).
Import the header files in your objective-C or Swift code (using a bridging header) to begin decoding AVIF images.