3 Instructions for building this repository on Linux, Windows, and Android.
7 1. [Contributing](#contributing)
8 2. [Repository Set-Up](#repo-set-up)
9 3. [Windows Build](#windows-build)
10 4. [Linux Build](#linux-build)
11 5. [Android Build](#android-build)
15 ## Contributing to the Repository
17 If you intend to contribute, the preferred work flow is for you to develop
18 your contribution in a fork of this repository in your GitHub account and
19 then submit a pull request.
20 Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file in this repository for more details.
28 This repository does not contain a Vulkan-capable driver.
29 Before proceeding, it is strongly recommended that you obtain a Vulkan driver from your
30 graphics hardware vendor and install it properly.
32 ### Download the Repository
34 To create your local git repository:
36 git clone https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers
40 ## Building On Windows
42 ### Windows Build Requirements
44 Windows 7+ with the following software packages:
46 - Microsoft Visual Studio 2013 Update 4 Professional, VS2015 (any version), or VS2017 (any version).
47 - [CMake](http://www.cmake.org/download/)
48 - Tell the installer to "Add CMake to the system PATH" environment variable.
49 - [Python 3](https://www.python.org/downloads)
50 - Select to install the optional sub-package to add Python to the system PATH
52 - Ensure the `pip` module is installed (it should be by default)
53 - Python3.3 or later is necessary for the Windows py.exe launcher that is used to select python3
54 rather than python2 if both are installed
55 - [Git](http://git-scm.com/download/win)
56 - Tell the installer to allow it to be used for "Developer Prompt" as well as "Git Bash".
57 - Tell the installer to treat line endings "as is" (i.e. both DOS and Unix-style line endings).
58 - Install both the 32-bit and 64-bit versions, as the 64-bit installer does not install the
59 32-bit libraries and tools.
60 - Notes for using [Cygwin](https://www.cygwin.com)
61 - First, in a Cygwin shell:
62 - `./update_external_sources.sh --no-build`
63 - Then, in a Visual Studio Developer Command Prompt:
64 - Ensure python3.x and CMake in are in the path
65 - Run `update_external_sources.bat --no-sync`
66 - Run build_windows_targets.bat cmake
68 ### Windows Build - Microsoft Visual Studio
70 1. Open a Developer Command Prompt for VS201x
71 2. Change directory to `Vulkan-LoaderAndValidationLayers` -- the root of the cloned git repository
72 3. Run `update_external_sources.bat` -- this will download and build external components
73 4. Create a `build` directory, change into that directory, and run cmake
75 For example, for VS2017 (generators for other versions are [specified here](#win-cmake-generators)):
77 cmake -G "Visual Studio 15 2017 Win64" ..
79 This will create a Windows solution file named `VULKAN.sln` in the build directory.
81 Launch Visual Studio and open the "VULKAN.sln" solution file in the build folder.
82 You may select "Debug" or "Release" from the Solution Configurations drop-down list.
83 Start a build by selecting the Build->Build Solution menu item.
84 This solution copies the loader it built to each program's build directory
85 to ensure that the program uses the loader built from this solution.
87 #### The Update External Sources Batch File
89 Employing [optional parameters to **update_external_sources.bat**](#update-external-sources)
90 can streamline repository set-up.
92 ### Windows Tests and Demos
94 After making any changes to the repository, you should perform some quick sanity tests,
95 including the run_all_tests Powershell script and the cube demo with validation enabled.
97 To run the validation test script, open a Powershell Console,
98 change to the build/tests directory, and run:
106 .\run_all_tests.ps1 -Debug
108 This script will run the following tests:
110 - `vk_loader_validation_tests`:
111 Vulkan loader handle wrapping, allocation callback, and loader/layer interface tests
112 - `vk_layer_validation_tests`:
113 Test Vulkan validation layers
114 - `vkvalidatelayerdoc`:
115 Tests that validation database is up-to-date and is synchronized with the validation source code
117 To run the Cube demo with validation in a Debug build configuration:
119 - In the MSVC solution explorer, right-click on the `cube` project and select
120 `Set As Startup Project`
121 - Right click on cube again, select properties->Debugging->Command Arguments, change to
122 `--validate`, and save
123 - From the main menu, select Debug->Start Debugging, or from the toolbar click
124 `Local Windows Debugger`
126 Other demos that can be found in the build/demos directory are:
128 - `vulkaninfo`: Report GPU properties
129 - `smoketest`: A "smoke" test using more complex Vulkan rendering
133 [](#win-cmake-generators)
135 #### CMake Visual Studio Generators
137 The above example used Visual Studio 2017, and specified its generator as "Visual Studio 15 2017 Win64".
138 The chosen generator should match your Visual Studio version. Appropriate Visual Studio generators include:
140 | Build Platform | 64-bit Generator | 32-bit Generator |
141 |------------------------------|-------------------------------|-------------------------|
142 | Microsoft Visual Studio 2013 | "Visual Studio 12 2013 Win64" | "Visual Studio 12 2013" |
143 | Microsoft Visual Studio 2015 | "Visual Studio 14 2015 Win64" | "Visual Studio 14 2015" |
144 | Microsoft Visual Studio 2017 | "Visual Studio 15 2017 Win64" | "Visual Studio 15 2017" |
146 #### The Vulkan Loader Library
148 Vulkan programs must be able to find and use the vulkan-1.dll library.
149 While several of the test and demo projects in the Windows solution set this up automatically, doing so manually may be necessary for custom projects or solutions.
150 Make sure the library is either installed in the C:\Windows\System32 folder, or that the PATH environment variable includes the folder where the library resides.
152 To run Vulkan programs you must tell the Vulkan Loader where to find the libraries.
153 This is described in a `LoaderAndLayerInterface` document in the `loader` folder in this repository.
154 This describes both how ICDs and layers should be properly packaged, and how developers can point to ICDs and layers within their builds.
160 ### Linux Build Requirements
162 This repository has been built and tested on the two most recent Ubuntu LTS versions.
163 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, although earlier versions may work.
164 It should be straightforward to adapt this repository to other Linux distributions.
166 **Required Package List:**
168 sudo apt-get install git cmake build-essential libx11-xcb-dev libxkbcommon-dev libmirclient-dev libwayland-dev libxrandr-dev
172 Example debug build (Note that the update\_external\_sources script used below builds external tools into predefined locations.
173 See **Loader and Validation Layer Dependencies** for more information and other options):
175 1. In a Linux terminal, `cd Vulkan-LoaderAndValidationLayers` -- the root of the
176 cloned git repository
177 2. Execute `./update_external_sources.sh` -- this will download and build external components
178 3. Create a `build` directory, change into that directory, and run cmake:
183 cmake -DCMAKE_BUILD_TYPE=Debug ..
186 4. Change into the newly-created build directory
187 5. Run `make -j8` to begin the build
189 If your build system supports ccache, you can enable that via CMake option `-DUSE_CCACHE=On`
191 #### The Update External Sources script
193 Employing [optional parameters to **update_external_sources.sh**](#update-external-sources) can streamline repository set-up.
195 #### Using the new loader and layers
197 export LD_LIBRARY_PATH=<path to your repository root>/build/loader
198 export VK_LAYER_PATH=<path to your repository root>/build/layers
200 You can run the `vulkaninfo` application to see which driver, loader and layers are being used.
202 The `LoaderAndLayerInterface` document in the `loader` folder in this repository
203 is a specification that describes both how ICDs and layers should be properly packaged,
204 and how developers can point to ICDs and layers within their builds.
206 ### WSI Support Build Options
208 By default, the Vulkan Loader and Validation Layers are built with support for all 4 Vulkan-defined WSI display servers: Xcb, Xlib, Wayland, and Mir.
209 It is recommended to build the repository components with support for these display servers to maximize their usability across Linux platforms.
210 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`.
211 See the top-level CMakeLists.txt file for more info.
213 ### Linux Install to System Directories
215 Installing the files resulting from your build to the systems directories is optional since environment variables can usually be used instead to locate the binaries.
216 There are also risks with interfering with binaries installed by packages.
217 If you are certain that you would like to install your binaries to system directories, you can proceed with these instructions.
219 Assuming that you've built the code as described above and the current directory is still `build`, you can execute:
223 This command installs files to:
225 - `/usr/local/include/vulkan`: Vulkan include files
226 - `/usr/local/lib`: Vulkan loader and layers shared objects
227 - `/usr/local/bin`: vulkaninfo application
228 - `/usr/local/etc/vulkan/explicit_layer.d`: Layer JSON files
230 You may need to run `ldconfig` in order to refresh the system loader search cache on some Linux systems.
232 You can further customize the installation location by setting additional CMake variables to override their defaults.
233 For example, if you would like to install to `/tmp/build` instead of `/usr/local`, on your CMake command line specify:
235 -DCMAKE_INSTALL_PREFIX=/tmp/build
236 -DDEST_DIR=/tmp/build
238 Then run `make install` as before. The install step places the files in `/tmp/build`.
240 Using the `CMAKE_INSTALL_PREFIX` to customize the install location also modifies
241 the loader search paths to include searching for layers in the specified install location.
242 In this example, setting `CMAKE_INSTALL_PREFIX` to `/tmp/build` causes the loader to search
243 `/tmp/build/etc/vulkan/explicit_layer.d` and `/tmp/build/share/vulkan/explicit_layer.d`
244 for the layer JSON files.
245 The loader also searches the "standard" system locations of `/etc/vulkan/explicit_layer.d` and
246 `/usr/share/vulkan/explicit_layer.d` after searching the two locations under `/tmp/build`.
248 You can further customize the installation directories by using the CMake variables
249 `CMAKE_INSTALL_SYSCONFDIR` to rename the `etc` directory and `CMAKE_INSTALL_DATADIR`
250 to rename the `share` directory.
252 See the CMake documentation for more details on using these variables
253 to further customize your installation.
255 Also see the `LoaderAndLayerInterface` document in the `loader` folder in this
256 repository for more information about loader operation.
258 Note that some executables in this repository (e.g., `cube`) use the "rpath" linker directive to
259 load the Vulkan loader from the build directory, `build` in this example.
260 This means that even after installing the loader to the system directories, these executables still
261 use the loader from the build directory.
265 To uninstall the files from the system directories, you can execute:
269 ### Linux Tests and Demos
271 After making any changes to the repository, you should perform some quick sanity tests, including
272 the run_all_tests shell script and the cube demo with validation enabled.
274 To run the **validation test script**, in a terminal change to the build/tests directory and run:
276 VK_LAYER_PATH=../layers ./run_all_tests.sh
278 This script will run the following tests:
280 - `vk_loader_validation_tests`: Tests Vulkan Loader handle wrapping
281 - `vk_layer_validation_tests`: Test Vulkan validation layers
282 - `vkvalidatelayerdoc`: Tests that validation database is in up-to-date and in synchronization with
283 the validation source code
285 To run the **Cube demo** with validation, in a terminal change to the `build/demos`
288 VK_LAYER_PATH=../layers ./cube --validate
290 Other demos that can be found in the `build/demos` directory are:
292 - `vulkaninfo`: report GPU properties
293 - `smoketest`: A "smoke" test using more complex Vulkan rendering
295 You can select which WSI subsystem is used to build the demos using a CMake option
296 called DEMOS_WSI_SELECTION.
297 Supported options are XCB (default), XLIB, WAYLAND, and MIR.
298 Note that you must build using the corresponding BUILD_WSI_*_SUPPORT enabled at the
299 base repository level (all SUPPORT options are ON by default).
300 For instance, creating a build that will use Xlib to build the demos,
301 your CMake command line might look like:
303 cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Debug -DDEMOS_WSI_SELECTION=XLIB
307 #### Linux 32-bit support
309 Usage of this repository's contents in 32-bit Linux environments is not officially supported.
310 However, since this repository is supported on 32-bit Windows,
311 these modules should generally work on 32-bit Linux.
313 Here are some notes for building 32-bit targets on a 64-bit Ubuntu "reference" platform:
315 If not already installed, install the following 32-bit development libraries:
317 `gcc-multilib g++-multilib libx11-dev:i386`
319 This list may vary depending on your distribution and which windowing systems you are building for.
321 Set up your environment for building 32-bit targets:
326 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu
328 Again, your PKG_CONFIG configuration may be different, depending on your distribution.
330 If the libraries in the `external` directory have already been built for 64-bit targets,
331 delete or "clean" this directory and rebuild it with the above settings using the
332 `update_external_sources` shell script.
333 This is required because the libraries in `external` must be built for 32-bit in order
334 to be usable by the rest of the components in the repository.
336 Finally, rebuild the repository using `cmake` and `make`, as explained above.
340 ## Building On Android
342 Install the required tools for Linux and Windows covered above, then add the following.
344 ### Android Build Requirements
346 - Install [Android Studio 2.3](https://developer.android.com/studio/index.html) or later.
347 - From the "Welcome to Android Studio" splash screen, add the following components using
348 Configure > SDK Manager:
349 - SDK Platforms > Android 6.0 and newer
350 - SDK Tools > Android SDK Build-Tools
351 - SDK Tools > Android SDK Platform-Tools
352 - SDK Tools > Android SDK Tools
355 #### Add Android specifics to environment
357 For each of the below, you may need to specify a different build-tools version, as Android Studio will roll it forward fairly regularly.
361 export ANDROID_SDK_HOME=$HOME/Android/sdk
362 export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk-bundle
363 export PATH=$ANDROID_SDK_HOME:$PATH
364 export PATH=$ANDROID_NDK_HOME:$PATH
365 export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
369 set ANDROID_SDK_HOME=%LOCALAPPDATA%\Android\sdk
370 set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk-bundle
371 set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH%
375 export ANDROID_SDK_HOME=$HOME/Library/Android/sdk
376 export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk-bundle
377 export PATH=$ANDROID_NDK_PATH:$PATH
378 export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
380 Note: If `jarsigner` is missing from your platform, you can find it in the
381 Android Studio install or in your Java installation.
382 If you do not have Java, you can get it with something like the following:
384 sudo apt-get install openjdk-8-jdk
386 #### Additional OSX System Requirements
388 Tested on OSX version 10.12.4
390 Setup Homebrew and components
392 - Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
394 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
396 - Ensure Homebrew is at the beginning of your PATH:
398 export PATH=/usr/local/bin:$PATH
400 - Add packages with the following (may need refinement)
402 brew install cmake python python3 git
406 There are two options for building the Android layers.
407 Either using the SPIRV tools provided as part of the Android NDK, or using upstream sources.
408 To build with SPIRV tools from the NDK, remove the build-android/third_party directory created by
409 running update_external_sources_android.sh, (or avoid running update_external_sources_android.sh).
410 Use the following script to build everything in the repository for Android, including validation
411 layers, tests, demos, and APK packaging: This script does retrieve and use the upstream SPRIV tools.
416 Resulting validation layer binaries will be in build-android/libs.
417 Test and demo APKs can be installed on production devices with:
419 ./install_all.sh [-s <serial number>]
421 Note that there are no equivalent scripts on Windows yet, that work needs to be completed.
422 The following per platform commands can be used for layer only builds:
426 Follow the setup steps for Linux or OSX above, then from your terminal:
429 ./update_external_sources_android.sh --no-build
430 ./android-generate.sh
435 Follow the setup steps for Windows above, then from Developer Command Prompt for VS2013:
438 update_external_sources_android.bat
442 ### Android Tests and Demos
444 After making any changes to the repository you should perform some quick sanity tests,
445 including the layer validation tests and the cube and smoke demos with validation enabled.
447 #### Run Layer Validation Tests
449 Use the following steps to build, install, and run the layer validation tests for Android:
453 adb install -r bin/VulkanLayerValidationTests.apk
454 adb shell am start com.example.VulkanLayerValidationTests/android.app.NativeActivity
456 Alternatively, you can use the test_APK script to install and run the layer validation tests:
458 test_APK.sh -s <serial number> -p <plaform name> -f <gtest_filter>
460 #### Run Cube and Smoke with Validation
462 Use the following steps to build, install, and run Cube and Smoke for Android:
466 adb install -r ../demos/android/cube/bin/cube.apk
467 adb shell am start com.example.Cube/android.app.NativeActivity
469 To build, install, and run Cube with validation layers,
470 first build layers using steps above, then run:
474 adb install -r ../demos/android/cube-with-layers/bin/cube-with-layers.apk
476 ##### Run without validation enabled
478 adb shell am start com.example.CubeWithLayers/android.app.NativeActivity
480 ##### Run with validation enabled
482 adb shell am start -a android.intent.action.MAIN -c android-intent.category.LAUNCH -n com.example.CubeWithLayers/android.app.NativeActivity --es args "--validate"
484 vkjson_info for Android is built as an executable for devices with root access.
486 To use, simply push it to the device and run it:
489 adb push obj/local/<abi>/vkjson_info /data/tmp/
490 adb shell /data/tmp/vkjson_info
492 The resulting json file will be found in:
494 /sdcard/Android/<device_name>.json
496 To build, install, and run the Smoke demo for Android, run the following, and any prompts that come back from the script:
498 ./update_external_sources.sh --glslang
499 cd demos/smoke/android
500 export ANDROID_SDK_HOME=<path to Android/Sdk>
501 export ANDROID_NDK_HOME=<path to Android/Sdk/ndk-bundle>
503 adb shell am start -a android.intent.action.MAIN -c android-intent.category.LAUNCH -n com.example.Smoke/android.app.NativeActivity --es args "--validate"
505 ## Ninja Builds - All Platforms
507 The [Qt Creator IDE](https://qt.io/download-open-source/#section-2) can open a root CMakeList.txt
508 as a project directly, and it provides tools within Creator to configure and generate Vulkan SDK
509 build files for one to many targets concurrently.
510 Alternatively, when invoking CMake, use the `-G Codeblocks` Ninja option to generate Ninja build
511 files to be used as project files for QtCreator
513 - Follow the steps defined elsewhere for the OS using the update\_external\_sources script or as
514 shown in **Loader and Validation Layer Dependencies** below
515 - Open, configure, and build the glslang CMakeList.txt files. Note that building the glslang
516 project will provide access to spirv-tools and spirv-headers
517 - Then do the same with the Vulkan-LoaderAndValidationLayers CMakeList.txt file
518 - In order to debug with QtCreator, a
519 [Microsoft WDK: eg WDK 10](http://go.microsoft.com/fwlink/p/?LinkId=526733) is required.
521 Note that installing the WDK breaks the MSVC vcvarsall.bat build scripts provided by MSVC, requiring that the LIB, INCLUDE, and PATHenv variables be set to the WDK paths by some other means
523 [](#update-external-sources)
525 ## Update External Sources Optional Parameters
527 This script will default to building 64-bit _and_ 32-bit versions of debug _and_ release
528 configurations, which can take a substantial amount of time.
529 However, it supports the following options to select a particular build configuration which can
530 reduce the time needed for repository set-up:
532 | Command Line Option | Function |
533 |----------------------|----------------------------------------------|
534 | --32 | Build 32-bit targets only |
535 | --64 | Build 64-bit targets only |
536 | --release | Perform release builds only |
537 | --debug | Perform debug builds only |
538 | --no-build | Sync without building targets |
539 | --no-sync | Skip repository sync step |
541 For example, to target a Windows 64-bit debug development configuration, invoke the batch file as follows:
543 `update_external_sources.bat --64 --debug`
545 Similarly, invoking the same configuration for Linux would be:
547 `update_external_sources.sh --64 --debug`
549 ## Loader and Validation Layer Dependencies
551 The glslang repository is required to build and run Loader and Validation Layer components.
552 It is not a git sub-module of Vulkan-LoaderAndValidationLayers but Vulkan-LoaderAndValidationLayers
553 is linked to a specific revision of glslang.
554 This can be automatically cloned and built to predefined locations with the
555 `update_external_sources` scripts.
556 If a custom configuration is required, do the following steps:
558 1) clone the repository:
560 `git clone https://github.com/KhronosGroup/glslang.git`
562 2) checkout the correct version of the tree based on the contents of the
563 glslang\_revision file at the root of the Vulkan-LoaderAndValidationLayers tree
564 (do the same anytime that Vulkan-LoaderAndValidationLayers is updated from remote)
569 git checkout < [path to Vulkan-LoaderAndValidationLayers]\glslang_revision [in glslang repo]
575 git checkout `cat [path to Vulkan-LoaderAndValidationLayers]\glslang_revision` [in glslang repo]
578 3) Configure the glslang source tree with CMake and build it with your IDE of choice
580 4) Enable the `CUSTOM_GLSLANG_BIN_PATH` and `CUSTOM_SPIRV_TOOLS_BIN_PATH` options in the Vulkan-LoaderAndValidationLayers CMake configuration and point the `GLSLANG_BINARY_PATH` and `SPIRV_TOOLS_BINARY_PATH` variables to the correct location
582 5) If building on Windows with MSVC, set `DISABLE_BUILDTGT_DIR_DECORATION` to _On_.
583 If building on Windows, but without MSVC set `DISABLE_BUILD_PATH_DECORATION` to _On_
585 ## Optional software packages
587 - [Cygwin for windows](https://www.cygwin.com/)
588 - Cygwin provides some Linux-like tools, which can be valuable for working with the repository,
589 such as the BASH shell and git packages
590 - With appropriate adjustments, it is possible to use other shells and environments as well
592 - [Ninja on all platforms](https://github.com/ninja-build/ninja/releases)
593 - [The Ninja-build project](https://ninja-build.org)
594 - [Ninja Users Manual](https://ninja-build.org/manual.html)
596 - [QtCreator as IDE for CMake builds on all platforms](https://qt.io/download-open-source/#section-2)