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
- 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
| 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. |
-| USE_CCACHE | Linux | `OFF` | Enable caching with the CCache program. |
+| 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: Continuous integration tools use [CMake 3.12.2](https://github.com/Kitware/CMake/releases/tag/v3.12.2) for Windows
+- [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.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
### 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.
-The continuous integration tools use [CMake 3.12.4](https://github.com/Kitware/CMake/releases/tag/v3.12.4) for Linux
+[CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Linux-x86_64.tar.gz) is recommended.
#### Required Package List
sudo apt-get install git cmake build-essential libx11-xcb-dev \
- libxkbcommon-dev libwayland-dev libxrandr-dev
+ libxkbcommon-dev libwayland-dev libxrandr-dev wayland-protocols
### Linux Build
the CMakeLists.txt file in `Vulkan-Tools/vulkaninfo` for more info.
You can select which WSI subsystem is used to execute the vkcube applications
-using a CMake option called DEMOS_WSI_SELECTION. Supported options are XCB
+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 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
- 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:
+be completed.
-#### Linux and OSX
+### Run vkcube
-Follow the setup steps for Linux or OSX above, then from your terminal:
+Use the following command to run vkcube for Android:
- 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 vkcube
-demo 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 vkcube with Validation
-
-TODO: This must be reworked to pull in layers from the ValidationLayers repo
-
-Use the following steps to build, install, and run vkcube for Android:
-
- cd build-android
- ./build_all.sh
- adb install -r ../demos/android/cube/bin/vkcube.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
-The continuous integration tools use [CMake 3.11.3](https://github.com/Kitware/CMake/releases/tag/v3.11.3) for MacOS
+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.
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 (may need refinement)
- brew install cmake python python3 git
+ brew install python python3 git
### Clone the Repository
open cube/vkcube.app
open cube/vkcubepp.app
- open vulkaninfo/vulkaninfo.app
Or you can locate them from `Finder` and launch them from there.
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.
-##### 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