NOTE: Python is needed for working on generated code, and helping grab dependencies. While it‘s not technically required, it’s practically required for most users.
This repository contains generated source code which is not intended to be modified directly.
A helper CMake target tools_codegen is also provided to simplify the invocation of scripts/generate_source.py from the build directory:
cmake -S . -B build -D TOOLS_CODEGEN=ON cmake --build build --target tools_codegen
NOTE: TOOLS_CODEGEN is OFF by default.
The following will be enough for most people, for more detailed instructions, see below.
git clone https://github.com/KhronosGroup/Vulkan-Tools.git cd Vulkan-Tools cmake -S . -B build -D UPDATE_DEPS=ON -D BUILD_WERROR=ON -D BUILD_TESTS=ON -D CMAKE_BUILD_TYPE=Debug cmake --build build --config Debug
By default BUILD_WERROR is OFF. The idiom for open source projects is to NOT enable warnings as errors.
System/language package managers have to build on multiple different platforms and compilers.
By defaulting to ON we cause issues for package managers since there is no standard way to disable warnings until CMake 3.24
Add -D BUILD_WERROR=ON to your workflow. Or use the dev preset shown below which will also enabling warnings as errors.
Currently this repo has a custom process for grabbing C/C++ dependencies.
Keep in mind this repo predates tools like vcpkg, conan, etc. Our process is most similar to vcpkg.
By specifying -D UPDATE_DEPS=ON when configuring CMake we grab dependencies listed in known_good.json.
All we are doing is streamlining building/installing the known good dependencies and helping CMake find the dependencies.
This is done via a combination of Python and CMake scripting.
Misc Useful Information:
UPDATE_DEPS is OFF. The intent is to be friendly by default to system/language package managers.update_deps.py manually but it isn't recommended for most users.Typically most developers alter known_good.json with the commit/branch they are testing.
Alternatively you can modify CMAKE_PREFIX_PATH as follows.
# Delete the CMakeCache.txt which will cache find_* results rm -rf build/ cmake -S . -B build/ ... -D CMAKE_PREFIX_PATH=~/foobar/vulkan_headers_install/ ...
This repository is regularly built and tested on the two most recent Ubuntu LTS versions.
sudo apt-get install git build-essential python3 cmake # Linux WSI system libraries sudo apt-get install libwayland-dev xorg-dev
By default, the repository components are built with support for the Vulkan-defined WSI display servers: Xcb, Xlib, and Wayland. It is recommended to build the repository components with support for these display servers to maximize their usability across Linux platforms. If it is necessary to build these modules without support for one of the display servers, the appropriate CMake option of the form BUILD_WSI_xxx_SUPPORT can be set to OFF.
Usage of this repository's contents in 32-bit Linux environments is not officially supported. However, since this repository is supported on 32-bit Windows, these modules should generally work on 32-bit Linux.
Here are some notes for building 32-bit targets on a 64-bit Ubuntu “reference” platform:
# 32-bit libs # your PKG_CONFIG configuration may be different, depending on your distribution sudo apt-get install gcc-multilib g++-multilib libx11-dev:i386
Set up your environment for building 32-bit targets:
export ASFLAGS=--32 export CFLAGS=-m32 export CXXFLAGS=-m32 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu
Note: Anything less than Visual Studio 2019 is not guaranteed to compile/work.
Run CMake to generate Visual Studio project files.
# NOTE: By default CMake picks the latest version of Visual Studio as the default generator. cmake -S . -B build # Open the Visual Studio solution cmake --open build
See the CMake documentation for further information on Visual Studio generators.
NOTE: Windows developers don't have to develop in Visual Studio. Visual Studio just helps streamlining the needed C++ toolchain requirements (compilers, linker, etc).
NOTE: MacOS developers don't have to develop in Xcode. Xcode just helps streamlining the needed C++ toolchain requirements (compilers, linker, etc). Similar to Visual Studio on Windows.
To create and open an Xcode project:
# Create the Xcode project cmake -S . -B build -G Xcode # Open the Xcode project cmake --open build
See the CMake documentation for further information on the Xcode generator.
Welcome to Android Studio splash screen, add the following components using the SDK Manager:NOTE: The following commands are streamlined for Linux but easily transferable to other platforms. The main intent is setting 2 environment variables and ensuring the NDK and build tools are in the PATH.
# Set environment variables # https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md#environment-variables-2 export ANDROID_SDK_ROOT=$HOME/Android/Sdk export ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/X.Y.Z # Modify path export PATH=$ANDROID_SDK_ROOT/build-tools/X.Y.Z:$PATH # (Optional if you have new enough version of CMake + Ninja) export PATH=$ANDROID_SDK_ROOT/cmake/3.22.1/bin:$PATH # Verify SDK build-tools is set correctly which aapt # Verify CMake/Ninja are in the path which cmake which ninja # Check apksigner apksigner --help
Note: If apksigner gives a java: not found error you do not have Java in your path.
# A common way to install on the system sudo apt install default-jre
Invoking CMake directly to build the binary is relatively simple.
See https://developer.android.com/ndk/guides/cmake#command-line for CMake NDK documentation.
# Build release binary for arm64-v8a cmake -S . -B build \ -D CMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \ -D ANDROID_PLATFORM=26 \ -D CMAKE_ANDROID_ARCH_ABI=arm64-v8a \ -D CMAKE_ANDROID_STL_TYPE=c++_static \ -D ANDROID_USE_LEGACY_TOOLCHAIN_FILE=NO \ -D CMAKE_BUILD_TYPE=Release \ -D UPDATE_DEPS=ON \ -G Ninja cmake --build build cmake --install build --prefix build/install
Alternatively users can also use scripts/android.py to build the binaries.
# Build release binaries for arm64-v8a python3 scripts/android.py --config Release --app-abi arm64-v8a --app-stl c++_static
android.py can also streamline building for multiple ABIs:
# Build release binaries for all ABIs python3 scripts/android.py --config Release --app-abi 'armeabi-v7a arm64-v8a x86 x86_64' --app-stl c++_static
NOTE: The above methods will only build the vulkaninfo and libVkCube. It won't create an APK.
Furthermore vulkaninfo is intended to run as an executable (No APK).
Creating the VkCube.apk is a bit of an involved process since it requires running multiple CLI tools after the CMake build has finished.
As a result users are enouraged to use scripts/android.py to build the APK.
This script handles wrapping CMake and various Android CLI tools to create the APK for you.
# Build a complete APK with debug binaries for all ABIS python3 scripts/android.py --config Debug --app-abi 'armeabi-v7a arm64-v8a x86 x86_64' --app-stl c++_shared --apk # Build a clean APK with release binaries for arm64-v8a python3 scripts/android.py --config Release --app-abi arm64-v8a --app-stl c++_shared --apk --clean
Note: scripts/android.py will place the APK in the build-android/bin directory.
See tests/README.md for running VkCube.apk / vulkaninfo on Android.
/bin : The vulkaninfo, vkcube and vkcubepp executablesIf INSTALL_ICD is configured then MockICD will be installed as follows:
For Unix operating systems:
/bin : The Mock ICD/share/vulkan/icd.d : Mock ICD JSONFor WIN32:
/bin : The Mock ICD and JSONAfter you have built your project you can install using CMake's install functionality.
CMake Docs:
# EX: Installs Release artifacts into `build/install` directory. # NOTE: --config is only needed for multi-config generators (Visual Studio, Xcode, etc) cmake --install build/ --config Release --prefix build/install