Building KTX

KTX uses the the CMake build system. Depending on your platform and how you configure it, it will create project/build files (e.g. an Xcode project, a Visual Studio solution or Make files) that allow you to build the software and more (See CMake generators).

KTX consist of the following parts

The libktx main library
Command line tools (for Linux / macOS / Windows)
Load test applications (for OpenGL^® 3, OpenGLES^® or Vulkan^®)
Documentation

Supported platforms (please to through their specific requirements first)

GNU/Linux
Apple macOS/iOS
Web/Emscripten
Windows
Android

The minimal way to a build is to clone this repository and run the following in a terminal

# Navigate to the root of your KTX-Software clone (replace with
# your actual path)
cd /path/to/KTX-Software

# This generates build/project files in the sub-folder `build`
cmake . -B build

# Compile the project
cmake --build build

This creates the libktx library and the command line tools. To create the complete project generate the project like this:

cmake . -B build -DKTX_FEATURE_LOADTEST_APPS=ON -DKTX_FEATURE_DOC=ON

If you need the library to be static, enable the KTX_FEATURE_STATIC_LIBRARY setting (always enabled on iOS and Emscripten).

Building

GNU/Linux

You need to install the following

CMake
gcc and g++ from the GNU Compiler Collection
GNU Make or Ninja (recommended)
Doxygen (only if generating documentation)

Additional requirements for the load tests applications

SDL2 development library
assimp development library
OpenGL development libraries
Vulkan development libraries
Vulkan SDK
zlib development library

On Ubuntu and Debian these can be installed via

sudo apt install build-essential cmake libzstd-dev ninja-build doxygen libsdl2-dev libgl1-mesa-glx libgl1-mesa-dev libvulkan1 libvulkan-dev libassimp-dev

KTX requires glslc, which comes with Vulkan SDK (in sub- folder x86_64/bin/glslc). Make sure the complete path to the tool is in in your environment's PATH variable. If you've followed Vulkan SDK install instructions for your platform this should already be set up. You can test it by running

export PATH=$PATH:/path/to/vulkansdk/x86_64/bin
# Should not fail and output version numbers
glslc --version

You should be able then to build like this

# First either configure a debug build of libktx and the tools
cmake . -G Ninja -B build
# ...or alternatively a release build including all targets
cmake . -G Ninja -B build -DCMAKE_BUILD_TYPE=Release -DKTX_FEATURE_LOADTEST_APPS=ON -DKTX_FEATURE_DOC=ON

# Compile the project
cmake --build build

Apple macOS/iOS

You need to install the following

CMake
Xcode
Doxygen (only if generating documentation)

For the load tests applications you need to install the Vulkan SDK. To build for iOS you need to set the CMake cache variable MOLTEN_VK_SDK to the root of MoltenVK inside the Vulkan SDK, if it is not already set. Caution: setup.env in the macOS Vulkan SDK sets VULKAN_SDK to the macOS folder of the SDK, a sibling of the MoltenVK folder. To build for other platforms, you shouldn't need to do anything else, but you might need to set the environment variable VULKAN_SDK to the root of the Vulkan SDK as a hint for FindVulkan.

Other dependencies (like zstd, SDL2 or the assimp library are included in this repository or come with Xcode).

NOTE: the iphoneos or MacOSX SDK version gets hardwired into the generated projects. After installing an Xcode update that has the SDK for a new version of iOS, builds will fail. The only way to remedy this is to delete the build folder and regenerate from scratch.

macOS

To build for macOS:

# This creates an Xcode project at `build/mac/KTX-Software.xcodeproj` containing the libktx and tools targets.
mkdir build
cmake -G Xcode -B build/mac

# If you want to build the load test apps as well, you have to set the `KTX_FEATURE_LOADTEST_APPS` parameter:
cmake -GXcode -Bbuild/mac -DKTX_FEATURE_LOADTEST_APPS=ON"

# Compile the project
cmake --build build/mac

Apple Silicon and Universal Binaries

Macs are either based on Intel or the newer Apple Silicon architecture. By default CMake configures to build for your host's platform, whichever it is. If you want to cross compile universal binaries (that support both platforms), add the parameter -DCMAKE_OSX_ARCHITECTURES="\$(ARCHS_STANDARD)" to cmake.

Known limitations:

Load tests apps are not supported on native Apple Silicon and cannot be cross compiled for Intel either

Intel Macs have support for SSE, but if you're building universal binaries, you have to disable SSE or the build will fail

Example how to build universal binaries

# Configure universal binaries and disable SSE 
cmake -G Xcode -B build-macos-universal -DCMAKE_OSX_ARCHITECTURES="\$(ARCHS_STANDARD)" -DBASISU_SUPPORT_SSE=OFF
# Build 
cmake --build build-macos-universal
# Easy way to check if the resulting binaries are universal

file build-macos-universal/Debug/libktx.dylib
# outputs:
# build-macos-universal/Debug/libktx.dylib: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit dynamically linked shared library x86_64] [arm64]
# build-macos-universal/Debug/libktx.dylib (for architecture x86_64):	Mach-O 64-bit dynamically linked shared library x86_64
# build-macos-universal/Debug/libktx.dylib (for architecture arm64):	Mach-O 64-bit dynamically linked shared library arm64

file build-macos-universal/Debug/toktx
# outputs:
# build-macos-universal/Debug/toktx: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit executable x86_64] [arm64:Mach-O 64-bit executable arm64]
# build-macos-universal/Debug/toktx (for architecture x86_64):	Mach-O 64-bit executable x86_64
# build-macos-universal/Debug/toktx (for architecture arm64):	Mach-O 64-bit executable arm64

macOS signing

To sign the applications you need to set the following CMake variables:

Name	Value
XCODE_CODE_SIGN_IDENTITY	Owner of the Developer ID Application certificate to use for signing.
XCODE_DEVELOPMENT_TEAM	Development team of the certificate owner.

To sign the installation package you need to set the following variables:

Name	Value
PRODUCTBUILD_IDENTITY_NAME	Owner of the Developer ID Installer certificate to use for signing.
PRODUCTBUILD_KEYCHAIN_PATH	Path to the keychain file with the certificate. Blank if its in the default keychain.

iOS

To build for iOS:

# This creates an Xcode project at `build/ios/KTX-Software.xcodeproj` containing the libktx targets.
mkdir build # if it does not exist
cmake -G Xcode -B build/ios -DCMAKE_SYSTEM_NAME=iOS

# This creates a project to build the load test apps as well.
cmake -G Xcode -B build/ios -DKTX_FEATURE_LOADTEST_APPS=ON"

# Compile the project
cmake --build build -- -sdk iphoneos

If using the CMake GUI, when it asks you to specify the generator for the project, you need to check Specify options for cross-compiling and on the next screen make sure Operating System is set to iOS.

iOS signing

To sign the applications you need to set the following CMake variables:

Name	Value
XCODE_CODE_SIGN_IDENTITY	Owner of the Apple Development certificate to use for signing.
XCODE_DEVELOPMENT_TEAM	Development team used to create the Provisioning Profile. This may not be the same as the team of the Apple Development certificate owner.
XCODE_PROVISIONING_PROFILE	Name of the profile to use.

Web/Emscripten

There are two ways to build the Web version of the software: using Docker or using your own Emscripten installation.

Using Docker

Install Docker Desktop which is available for GNU/Linux, macOS and Windows.

In the repo root run

ci_scripts/build_wasm_docker.sh

This will build both Debug and Release configurations and will include the load test application. Builds are done with the official Emscripten Docker image. Output will be written to the folders build/web-{debug,release}.

If you are using Windows you will need a Unix-like shell such as the one with Git for Windows or one in Windows Subsystem for Linux (WSL) to run this script.

Using Your Own Emscripten Installation

Install Emscripten and follow the install instructions closely. After you've set up your emscripten environment in a terminal, run the following:

Debug:

# Configure
emcmake cmake -B build-web-debug . -DCMAKE_BUILD_TYPE=Debug

# Build
cmake --build build-web-debug --config Debug

Release:

# Configure
emcmake cmake -B build-web .

# Build
cmake --build build-web

To include the load test application into the build add -DKTX_FEATURE_LOADTEST_APPS=ON to either of the above configuration steps.

Web builds create two additional targets:

ktx_js, (libktx javascript wrapper)
msc_basis_transcoder_js (transcoder wrapper)

Note: The libktx wrapper does not use the transcoder wrapper. It directly uses the underlying c++ transcoder.

Windows

CMake can create solutions for Microsoft Visual Studio (2015/2017/2019 are supported by KTX).

Note: x86 (32-bit) Windows is not supported.

The CMake generators for Visual Studio 2017 and earlier generate projects whose default platform is Windows-x86. Since that is not supported by KTX-Software, the build will fail. To generate a project for x64 when using these earlier generators you must use CMake's -A option.

# -G shown for completeness. Not needed if you are happy
# with the CMake's default selection.
cmake -G "Visual Studio 15 2017" -B build -A x64 .

When using a more recent Visual Studio you simply need

cmake -B build .

To configure for Universal Windows Platform (Windows Store) you have to

Set the platform to x64, ARM or ARM64 (depending on your target device/platform)
Set the system name to WindowsStore
Provide a system version (e.g. 10.0)

Note: Support is currently limited to ktx and libktx_read (no tools, tests or load tests apps)

Example UWP configuration

cmake . -A ARM64 -B build_uwp_arm64 -DCMAKE_SYSTEM_NAME:String=WindowsStore -DCMAKE_SYSTEM_VERSION:String="10.0"
# Build `ktx.dll` only
cmake -B build_uwp_arm64 --target ktx

The NSIS compiler is needed if you intend to build packages.

CMake can include OpenGL ES versions of the KTX loader tests in the generated solution. To build and run these you need to install an OpenGL ES emulator. See below.

The KTX loader tests use libSDL 2.0.12+. You do not need SDL if you only wish to build the library or tools.

The KTX vulkan loader tests require a Vulkan SDK and the Open Asset Import Library libassimp. You must install the former.

OpenGL ES Emulator for Windows

The es1loadtests and es3loadtests targets on Windows require an OpenGL ES emulator. Imagination Technologies PowerVR. emulator is recommended. Any of the other major emulators listed below could also be used:

Qualcomm Adreno
Google ANGLE^*
ARM Mali

If you want to run the es1loadtests you will need to use Imagination Technologies' PowerVR emulator as that alone supports OpenGL ES 1.1. You must set the CMake configuration variable OPENGL_ES_EMULATOR to the directory containing the .lib files of your chosen emulator.

^*You will need to build ANGLE yourself and copy the libs and dlls to the appropriate directories under other_lib/win. Note that ANGLE's OpenGL ES 3 support is not yet complete.

Android

Support is currently limited to libktx and libktx_read (no tools, tests or loadtest apps)

Requirements:

CMake
Android NDK

The path to the NDK, a CMake toolchain file (that comes with the NDK), the desired Android ABI and minimum API level have to be provided when configuring with CMake (see Android NDK CMake guide for more details/settings). Example:

export ANDROID_NDK=/path/to/Android_NDK #This is the location of Android NDK
# Configure
cmake . -B "build-android" \
-DANDROID_PLATFORM=android-24 \ # API level 24 equals Android 7.0
-DANDROID_ABI="arm64-v8a" \ # target platform
-DANDROID_NDK="$ANDROID_NDK" \
-DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK/build/cmake/android.toolchain.cmake" \ # Toolchain file in a subfolder of the NDK
-DBASISU_SUPPORT_SSE=OFF # Disable SSE

# Build
cmake --build "build-android"

Note: SSE has to be disabled currently (for ABIs x86 and x86_64) due to an issue.

Dependencies

SDL

Builds of SDL are provided in the KTX Git repo. These binaries were built from a post 2.0.12 changeset given below. However Standard SDL 2.0.12 works fine everywhere so you can download binaries from libsdl.org, if you prefer.

macOS Notes

If you wish to use the provided version of SDL in other applications on your system, you can install the framework. Open a shell and enter the following command

cp -R other_lib/mac/<configuration>/SDL2.framework /Library/Frameworks

replacing <configuration> with your choice of Debug or Release.

Building SDL from source

As noted above, KTX uses a post SDL 2.0.12 changeset, no. 13845 in the canonical Mercurial repo at https://hg.libsdl.org/SDL or the automated GitHub mirror at https://github.com/spurious/SDL-mirror. Clone the repo, checkout changeset 13845 and follow the SDL build instructions.

Copy the results of your build to the appropriate place under the other_lib directory.

Vulkan SDK

Download Vulkan SDK from Lunar G.

For Ubuntu (Xenial and Bionic) install packages are available. See Getting Started - Ubuntu for detailed instructions.

For other GNU/Linux distributions a .tar.gz file is available. See Getting Started - Tarball for detailed instructions.

For Windows install the Vulkan SDK via the installer.

For iOS and macOS, install the Vulkan SDK by copying the content of the mounted .dmg to some location of choice. You need version 1.2.141.2 or later. This SDK contains MoltenVK (Vulkan Portability on Metal) for both iOS and macOS.

Doxygen

You need this if you want to generate the libktx and ktxtools documentation. You need a minimum of version 1.8.14 to generate the documentation correctly. You can download binaries and also find instructions for building it from source at Doxygen downloads. Make sure the directory containing the doxygen executable is in your $PATH.

libassimp

You need to install the Open Asset Import Library libassimp on GNU/Linux and macOS if you want to build the KTX vulkan loader tests. The KTX Git repo has binaries for iOS and Windows. You'll find libassimp in the standard package manager on GNU/Linux. On macOS it can be installed via MacPorts or Brew.

{# vim: set ai ts=4 sts=4 sw=2 expandtab textwidth=75:}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

BUILDING.md

BUILDING.md

Building KTX

Building

GNU/Linux

Apple macOS/iOS

macOS

Apple Silicon and Universal Binaries

macOS signing

iOS

iOS signing

Web/Emscripten

Using Docker

Using Your Own Emscripten Installation

Windows

OpenGL ES Emulator for Windows

Android

Dependencies

SDL

macOS Notes

Building SDL from source

Vulkan SDK

Doxygen

libassimp

Files

BUILDING.md

Latest commit

History

BUILDING.md

File metadata and controls

Building KTX

Building

GNU/Linux

Apple macOS/iOS

macOS

Apple Silicon and Universal Binaries

macOS signing

iOS

iOS signing

Web/Emscripten

Using Docker

Using Your Own Emscripten Installation

Windows

OpenGL ES Emulator for Windows

Android

Dependencies

SDL

macOS Notes

Building SDL from source

Vulkan SDK

Doxygen

libassimp