This repository contains the source code necessary to build the following components:
- vulkaninfo
-- cube and cubepp demos
+- vkcube and vkcubepp demos
- mock ICD
### Installed Files
The `install` target installs the following files under the directory
indicated by *install_dir*:
-- *install_dir*`/bin` : The vulkaninfo, cube and cubepp executables
+- *install_dir*`/bin` : The vulkaninfo, vkcube and vkcubepp executables
- *install_dir*`/lib` : The mock ICD library and JSON (Windows) (If INSTALL_ICD=ON)
- *install_dir*`/share/vulkan/icd.d` : mock ICD JSON (Linux/MacOS) (If INSTALL_ICD=ON)
#### glslang
This repository has a required dependency on the `glslangValidator` (shader
-compiler) for compiling the shader programs for the cube demos.
+compiler) for compiling the shader programs for the vkcube demos.
The CMake code in this repository downloads release binaries of glslang if a
build glslang repository is not provided. The glslangValidator is obtained
If you don't wish the CMake code to download these binaries, then you must
clone the [glslang repository](https://github.com/KhronosGroup/glslang) and
build its `install` target. Follow the build instructions in the glslang
-[README.md](https://github.com/KhronosGroup/glslang/blob/master/README.md)
+[README.md](https://github.com/KhronosGroup/glslang/blob/main/README.md)
file. Ensure that the `update_glslang_sources.py` script has been run as part
of building glslang. You must also take note of the glslang install directory
and pass it on the CMake command line for building this repository, as
described below.
-Note that this dependency can be ignored if not building the cube demo
+Note that this dependency can be ignored if not building the vkcube demo
(CMake option: `-DBUILD_CUBE=OFF`).
### Build and Install Directories
instructions follow this convention, although you can use any name for these
directories and place them in any location.
+### Building Dependent Repositories with Known-Good Revisions
+
+There is a Python utility script, `scripts/update_deps.py`, that you can use to
+gather and build the dependent repositories mentioned above. This script uses
+information stored in the `scripts/known_good.json` file to check out dependent
+repository revisions that are known to be compatible with the revision of this
+repository that you currently have checked out. As such, this script is useful
+as a quick-start tool for common use cases and default configurations.
+
+For all platforms, start with:
+
+ git clone git@github.com:KhronosGroup/Vulkan-Tools.git
+ cd Vulkan-Tools
+ mkdir build
+ cd build
+
+For 64-bit Linux and MacOS, continue with:
+
+ ../scripts/update_deps.py
+ cmake -C helper.cmake ..
+ cmake --build .
+
+For 64-bit Windows, continue with:
+
+ ..\scripts\update_deps.py --arch x64
+ cmake -A x64 -C helper.cmake ..
+ cmake --build .
+
+For 32-bit Windows, continue with:
+
+ ..\scripts\update_deps.py --arch Win32
+ cmake -A Win32 -C helper.cmake ..
+ cmake --build .
+
+Please see the more detailed build information later in this file if you have
+specific requirements for configuring and building these components.
+
+#### Notes
+
+- You may need to adjust some of the CMake options based on your platform. See
+ the platform-specific sections later in this document.
+- The `update_deps.py` script fetches and builds the dependent repositories in
+ the current directory when it is invoked. In this case, they are built in
+ the `build` directory.
+- The `build` directory is also being used to build this
+ (Vulkan-Tools) repository. But there shouldn't be any conflicts
+ inside the `build` directory between the dependent repositories and the
+ build files for this repository.
+- The `--dir` option for `update_deps.py` can be used to relocate the
+ dependent repositories to another arbitrary directory using an absolute or
+ relative path.
+- The `update_deps.py` script generates a file named `helper.cmake` and places
+ it in the same directory as the dependent repositories (`build` in this
+ case). This file contains CMake commands to set the CMake `*_INSTALL_DIR`
+ variables that are used to point to the install artifacts of the dependent
+ repositories. You can use this file with the `cmake -C` option to set these
+ variables when you generate your build files with CMake. This lets you avoid
+ entering several `*_INSTALL_DIR` variable settings on the CMake command line.
+- If using "MINGW" (Git For Windows), you may wish to run
+ `winpty update_deps.py` in order to avoid buffering all of the script's
+ "print" output until the end and to retain the ability to interrupt script
+ execution.
+- Please use `update_deps.py --help` to list additional options and read the
+ internal documentation in `update_deps.py` for further information.
+
+### Generated source code
+
+This repository contains generated source code in the `icd/generated`
+directory which is not intended to be modified directly. Instead, changes should be
+made to the corresponding generator in the `scripts` directory. The source files can
+then be regenerated using `scripts/generate_source.py`:
+
+ python3 scripts/generate_source.py PATH_TO_VULKAN_HEADERS_REGISTRY_DIR
+
+A helper CMake target `VulkanTools_generated_source` is also provided to simplify
+the invocation of `scripts/generate_source.py` from the build directory:
+
+ cmake --build . --target VulkanTools_generated_source
+
### Build Options
When generating native platform build files through CMake, several options can
| Option | Platform | Default | Description |
| ------ | -------- | ------- | ----------- |
-| BUILD_CUBE | All | `ON` | Controls whether or not the cube demo is built. |
+| BUILD_CUBE | All | `ON` | Controls whether or not the vkcube demo is built. |
| BUILD_VULKANINFO | All | `ON` | Controls whether or not the vulkaninfo utility is built. |
| BUILD_ICD | All | `ON` | Controls whether or not the mock ICD is built. |
| INSTALL_ICD | All | `OFF` | Controls whether or not the mock ICD is installed as part of the install target. |
| BUILD_WSI_XCB_SUPPORT | Linux | `ON` | Build the components with XCB support. |
| BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the components with Xlib support. |
| BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the components with Wayland support. |
-| BUILD_WSI_MIR_SUPPORT | Linux | `OFF` | Build the components with Mir support. |
+| BUILD_WSI_DIRECTFB_SUPPORT | Linux | `OFF` | Build the components with DirectFB support. |
The following is a table of all string options currently supported by this repository:
| Option | Platform | Default | Description |
| ------ | -------- | ------- | ----------- |
-| CMAKE_OSX_DEPLOYMENT_TARGET | MacOS | `10.12` | The minimum version of MacOS for loader deployment. |
+| VULKANINFO_BUILD_DLL_VERSIONINFO | Windows | `""` | Set the Windows specific version information for Vulkaninfo. Format is "major.minor.patch.build". |
These variables should be set using the `-D` option when invoking CMake to
generate the native platform files.
+### CCACHE
+
+There are 2 methods to enable CCACHE:
+
+1.) Set environment variables
+
+```bash
+# Requires CMake 3.17 (https://cmake.org/cmake/help/latest/envvar/CMAKE_LANG_COMPILER_LAUNCHER.html)
+export CMAKE_CXX_COMPILER_LAUNCHER=/usr/bin/ccache
+export CMAKE_C_COMPILER_LAUNCHER=/usr/bin/ccache
+```
+
+2.) Pass in cache variables
+
+```
+cmake ... -D CMAKE_CXX_COMPILER_LAUNCHER=/usr/bin/ccache -D CMAKE_C_COMPILER_LAUNCHER=/usr/bin/ccache
+```
+
+### EXPORT_COMPILE_COMMANDS
+
+There are 2 methods to enable exporting compile commands:
+
+1.) Set environment variables
+
+```bash
+# Requires CMake 3.17 (https://cmake.org/cmake/help/latest/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.html)
+export CMAKE_EXPORT_COMPILE_COMMANDS=ON
+```
+
+2.) Pass in cache variables
+
+```
+cmake ... -D CMAKE_EXPORT_COMPILE_COMMANDS=ON
+```
+
+NOTE: Modern tools will generally enable exporting compile commands for you (e.g. VSCode).
+Also `CMAKE_EXPORT_COMPILE_COMMANDS` is implemented only by Makefile and Ninja generators. For other generators, this option is ignored.
+
## Building On Windows
### Windows Development Environment Requirements
- [2017](https://www.visualstudio.com/vs/downloads/)
- The Community Edition of each of the above versions is sufficient, as
well as any more capable edition.
-- [CMake](http://www.cmake.org/download/) (Version 2.8.11 or better)
+- [CMake 3.17.2](https://cmake.org/files/v3.17/cmake-3.17.2-win64-x64.zip) is recommended.
- Use the installer option to add CMake to the system PATH
- Git Client Support
- [Git for Windows](http://git-scm.com/download/win) is a popular solution
Change your current directory to the top of the cloned repository directory,
create a build directory and generate the Visual Studio project files:
- cd Vulkan-Loader
+ cd Vulkan-Tools
mkdir build
cd build
cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir
### Linux Build Requirements
This repository has been built and tested on the two most recent Ubuntu LTS
-versions. Currently, the oldest supported version is Ubuntu 14.04, meaning
-that the minimum supported compiler versions are GCC 4.8.2 and Clang 3.4,
+versions. Currently, the oldest supported version is Ubuntu 16.04, meaning
+that the minimum officially supported C++11 compiler version is GCC 5.4.0,
although earlier versions may work. It should be straightforward to adapt this
repository to other Linux distributions.
+[CMake 3.17.2](https://cmake.org/files/v3.17/cmake-3.17.2-Linux-x86_64.tar.gz) is recommended.
+
#### Required Package List
sudo apt-get install git cmake build-essential libx11-xcb-dev \
- libxkbcommon-dev libmirclient-dev libwayland-dev libxrandr-dev
+ libxkbcommon-dev libwayland-dev libxrandr-dev wayland-protocols
### Linux Build
Note vulkaninfo currently only supports Xcb and Xlib WSI display servers. See
the CMakeLists.txt file in `Vulkan-Tools/vulkaninfo` for more info.
-You can select which WSI subsystem is used to execute the cube applications
-using a CMake option called DEMOS_WSI_SELECTION. Supported options are XCB
+You can select which WSI subsystem is used to execute the vkcube applications
+using a CMake option called CUBE_WSI_SELECTION. Supported options are XCB
(default), XLIB, and WAYLAND. Note that you must build using the corresponding
BUILD_WSI_*_SUPPORT enabled at the base repository level. For instance,
-creating a build that will use Xlib when running the cube demos, your CMake
+creating a build that will use Xlib when running the vkcube demos, your CMake
command line might look like:
- cmake -DCMAKE_BUILD_TYPE=Debug -DDEMOS_WSI_SELECTION=XLIB ..
+ cmake -DCMAKE_BUILD_TYPE=Debug -DCUBE_WSI_SELECTION=XLIB ..
#### Linux Install to System Directories
### Linux Tests
After making any changes to the repository, you should perform some quick
-sanity tests, such as running the cube demo with validation enabled.
+sanity tests, such as running the vkcube demo with validation enabled.
-To run the **Cube application** with validation, in a terminal change to the
+To run the **vkcube application** with validation, in a terminal change to the
`build/cube` directory and run:
- VK_LAYER_PATH=../path/to/validation/layers ./cube --validate
+ VK_LAYER_PATH=../path/to/validation/layers ./vkcube --validate
If you have an SDK installed and have run the setup script to set the
`VULKAN_SDK` environment variable, it may be unnecessary to specify a
- SDK Platforms > Android 6.0 and newer
- SDK Tools > Android SDK Build-Tools
- SDK Tools > Android SDK Platform-Tools
- - SDK Tools > Android SDK Tools
- - SDK Tools > NDK
+ - SDK Tools > NDK (Side by side)
#### Add Android specifics to environment
-For each of the below, you may need to specify a different build-tools
-version, as Android Studio will roll it forward fairly regularly.
+For each of the below, you may need to specify a different build-tools and ndk
+versions, as Android Studio will roll them forward fairly regularly.
On Linux:
export ANDROID_SDK_HOME=$HOME/Android/sdk
- export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk-bundle
- export PATH=$ANDROID_SDK_HOME:$PATH
+ export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk/23.0.7599858
export PATH=$ANDROID_NDK_HOME:$PATH
- export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
+ export PATH=$ANDROID_SDK_HOME/platform-tools:$PATH
+ export PATH=$ANDROID_SDK_HOME/build-tools/31.0.0:$PATH
On Windows:
set ANDROID_SDK_HOME=%LOCALAPPDATA%\Android\sdk
- set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk-bundle
- set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH%
+ set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk\23.0.7599858
+ set PATH=%ANDROID_NDK_HOME%;%PATH%
+ set PATH=%ANDROID_SDK_HOME%\platform-tools;%PATH%
+ set PATH=%ANDROID_SDK_HOME%\build-tools\31.0.0;%PATH%
On OSX:
export ANDROID_SDK_HOME=$HOME/Library/Android/sdk
- export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk-bundle
+ export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/23.0.7599858
export PATH=$ANDROID_NDK_PATH:$PATH
- export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
+ export PATH=$ANDROID_SDK_HOME/platform-tools:$PATH
+ export PATH=$ANDROID_SDK_HOME/build-tools/31.0.0:$PATH
Note: If `jarsigner` is missing from your platform, you can find it in the
Android Studio install or in your Java installation. If you do not have Java,
sudo apt-get install openjdk-8-jdk
-#### Additional OSX System Requirements
-
-Tested on OSX version 10.13.3
-
-Setup Homebrew and components
-
-- Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
-
- /usr/bin/ruby -e "$(curl -fsSL \
- https://raw.githubusercontent.com/Homebrew/install/master/install)"
-
-- Ensure Homebrew is at the beginning of your PATH:
-
- export PATH=/usr/local/bin:$PATH
-
-- Add packages with the following:
-
- brew install cmake python
-
### Android Build
-There are two options for building the Android tools. Either using the SPIRV
-tools provided as part of the Android NDK, or using upstream sources. To build
-with SPIRV tools from the NDK, remove the build-android/third_party directory
-created by running update_external_sources_android.sh, (or avoid running
-update_external_sources_android.sh). Use the following script to build
-everything in the repository for Android, including validation layers, tests,
-demos, and APK packaging: This script does retrieve and use the upstream SPRIV
-tools.
+Use the following script to build the vkcube demo for Android:
cd build-android
./build_all.sh
-Test and application APKs can be installed on production devices with:
+The APK can be installed on production devices with:
./install_all.sh [-s <serial number>]
Note that there are no equivalent scripts on Windows yet, that work needs to
-be completed. The following per platform commands can be used for layer only
-builds:
-
-#### Linux and OSX
-
-Follow the setup steps for Linux or OSX above, then from your terminal:
-
- cd build-android
- ./update_external_sources_android.sh --no-build
- ./android-generate.sh
- ndk-build -j4
-
-#### Windows
-
-Follow the setup steps for Windows above, then from Developer Command Prompt
-for VS2013:
-
- cd build-android
- update_external_sources_android.bat
- android-generate.bat
- ndk-build
-
-### Android Tests and Demos
-
-After making any changes to the repository you should perform some quick
-sanity tests, including the layer validation tests and the cube and smoke
-demos with validation enabled.
-
-#### Run Layer Validation Tests
-
-Use the following steps to build, install, and run the layer validation tests
-for Android:
-
- cd build-android
- ./build_all.sh
- adb install -r bin/VulkanLayerValidationTests.apk
- adb shell am start com.example.VulkanLayerValidationTests/android.app.NativeActivity
-
-Alternatively, you can use the test_APK script to install and run the layer
-validation tests:
-
- test_APK.sh -s <serial number> -p <platform name> -f <gtest_filter>
-
-#### Run Cube with Validation
+be completed.
-TODO: This must be reworked to pull in layers from the ValidationLayers repo
+### Run vkcube
-Use the following steps to build, install, and run Cube for Android:
+Use the following command to run vkcube for Android:
- cd build-android
- ./build_all.sh
- adb install -r ../demos/android/cube/bin/cube.apk
- adb shell am start com.example.Cube/android.app.NativeActivity
-
-To build, install, and run Cube with validation layers,
-first build layers using steps above, then run:
-
- cd build-android
- ./build_all.sh
- adb install -r ../demos/android/cube-with-layers/bin/cube-with-layers.apk
-
-##### Run without validation enabled
-
- adb shell am start com.example.CubeWithLayers/android.app.NativeActivity
-
-##### Run with validation enabled
-
- adb shell am start -a android.intent.action.MAIN -c android-intent.category.LAUNCH -n com.example.CubeWithLayers/android.app.NativeActivity --es args "--validate"
+ adb shell am start com.example.VkCube/android.app.NativeActivity
## Building on MacOS
### MacOS Build Requirements
-Tested on OSX version 10.12.6
+Tested on OSX version 10.12
-Setup Homebrew and components
-
-- Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
+NOTE: To force the OSX version set the environment variable [MACOSX_DEPLOYMENT_TARGET](https://cmake.org/cmake/help/latest/envvar/MACOSX_DEPLOYMENT_TARGET.html) when building VVL and it's dependencies.
- /usr/bin/ruby -e "$(curl -fsSL \
- https://raw.githubusercontent.com/Homebrew/install/master/install)"
+Setup Homebrew and components
- Ensure Homebrew is at the beginning of your PATH:
- Add packages with the following (may need refinement)
- brew install cmake python python3 git
+ brew install python python3 git
### Clone the Repository
[MoltenVK](https://github.com/KhronosGroup/MoltenVK) Library
-- Building the cube and vulkaninfo applications require linking to the
+- Building the vkcube and vulkaninfo applications require linking to the
MoltenVK Library (libMoltenVK.dylib)
- The following option should be used on the cmake command line to specify a
vulkan loader library: MOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK
Vulkan Loader Library
-- Building the cube and vulkaninfo applications require linking to the Vulkan
+- Building the vkcube and vulkaninfo applications require linking to the Vulkan
Loader Library (libvulkan.1.dylib)
- The following option should be used on the cmake command line to specify a
vulkan loader library:
mkdir build
cd build
- cmake -DCMAKE_BUILD_TYPE=Debug -DVULKAN_LOADER_INSTALL_DIR=/absolute_path_to/Vulkan-Loader_install_dir -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK ..
+ cmake -DCMAKE_BUILD_TYPE=Debug \
+ -DVULKAN_LOADER_INSTALL_DIR=/absolute_path_to/Vulkan-Loader_install_dir \
+ -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK \
+ -DCMAKE_INSTALL_PREFIX=install ..
make
To speed up the build on a multi-core machine, use the `-j` option for `make`
You can now run the demo applications from the command line:
- open cube/cube.app
- open cube/cubepp.app
- open vulkaninfo/vulkaninfo.app
+ open cube/vkcube.app
+ open cube/vkcubepp.app
Or you can locate them from `Finder` and launch them from there.
To see this, run this command from your `build` directory:
- otool -l cube/cube.app/Contents/MacOS/cube
+ otool -l cube/cube.app/Contents/MacOS/vkcube
-and note that the `cube` executable contains loader commands:
+and note that the `vkcube` executable contains loader commands:
- `LC_LOAD_DYLIB` to load `libvulkan.1.dylib` via an `@rpath`
- `LC_RPATH` that contains an absolute path to the build location of the Vulkan loader
make install
-This step "cleans up" the `RPATH` to remove any external references and
-performs other bundle fix-ups. After running `make install`, re-run the
-`otool` command again and note:
+This step copies the bundled applications to the location specified by
+CMAKE_INSTALL_PREFIX and "cleans up" the `RPATH` to remove any external
+references and performs other bundle fix-ups. After running `make install`,
+run the `otool` command again from the `build/install` directory and note:
- `LC_LOAD_DYLIB` is now `@executable_path/../MacOS/libvulkan.1.dylib`
- `LC_RPATH` is no longer present
The "bundle fix-up" operation also puts a copy of the Vulkan loader into the
bundle, making the bundle completely self-contained and self-referencing.
-Note that the "install" target has a very different meaning compared to the
-Linux "make install" target. The Linux "install" copies the targets to system
-directories. In MacOS, "install" means fixing up application bundles. In both
-cases, the "install" target operations clean up the `RPATH`.
-
-##### The Non-bundled vulkaninfo Application
+##### The vulkaninfo Application
-There is also a non-bundled version of the `vulkaninfo` application that you
-can run from the command line:
+There is also a `vulkaninfo` application that you can run from the command line:
vulkaninfo/vulkaninfo
-If you run this before you run "make install", vulkaninfo's RPATH is already
+If you run this from the build directory, vulkaninfo's RPATH is already
set to point to the Vulkan loader in the build tree, so it has no trouble
finding it. But the loader will not find the MoltenVK driver and you'll see a
message about an incompatible driver. To remedy this:
- VK_ICD_FILENAMES=<path-to>/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json demos/vulkaninfo
+ VK_ICD_FILENAMES=<path-to>/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json vulkaninfo/vulkaninfo
-If you run `vulkaninfo` after doing a "make install", the `RPATH` in the
-`vulkaninfo` application got removed and the OS needs extra help to locate the
-Vulkan loader:
+If you run `vulkaninfo` from the install directory, the `RPATH` in the
+`vulkaninfo` application got removed and the OS needs extra help to locate
+the Vulkan loader:
- DYLD_LIBRARY_PATH=<path-to>/Vulkan-Loader/loader VK_ICD_FILENAMES=<path-to>/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json demos/vulkaninfo
+ DYLD_LIBRARY_PATH=<path-to>/Vulkan-Loader/loader VK_ICD_FILENAMES=<path-to>/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json vulkaninfo/vulkaninfo
#### Building with the Xcode Generator
Within Xcode, you can select Debug or Release builds in the project's Build
Settings. You can also select individual schemes for working with specific
-applications like `cube`.
+applications like `vkcube`.
projects / platform / upstream / Vulkan-Tools.git / blobdiff