3 Instructions for building this repository on Linux, Windows, Android, and MacOS.
7 1. [Contributing](#contributing-to-the-repository)
8 2. [Repository Set-Up](#repository-set-up)
9 3. [Windows Build](#building-on-windows)
10 4. [Linux Build](#building-on-linux)
11 5. [Android Build](#building-on-android)
12 6. [MacOS build](#building-on-macos)
14 ## Contributing to the Repository
16 If you intend to contribute, the preferred work flow is for you to develop
17 your contribution in a fork of this repository in your GitHub account and
18 then submit a pull request.
19 Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file in this repository for more details.
25 This repository does not contain a Vulkan-capable driver.
26 Before proceeding, it is strongly recommended that you obtain a Vulkan driver from your
27 graphics hardware vendor and install it properly.
29 ### Download the Repository
31 To create your local git repository:
33 git clone https://github.com/KhronosGroup/Vulkan-ValidationLayers
35 ## Building On Windows
37 ### Windows Build Requirements
39 Windows 7+ with the following software packages:
41 - Microsoft Visual Studio 2013 Update 4 Professional, VS2015 (any version), or VS2017 (any version).
42 - [CMake](http://www.cmake.org/download/)
43 - Tell the installer to "Add CMake to the system PATH" environment variable.
44 - [Python 3](https://www.python.org/downloads)
45 - Select to install the optional sub-package to add Python to the system PATH
47 - Ensure the `pip` module is installed (it should be by default)
48 - Python3.3 or later is necessary for the Windows py.exe launcher that is used to select python3
49 rather than python2 if both are installed
50 - [Git](http://git-scm.com/download/win)
51 - Tell the installer to allow it to be used for "Developer Prompt" as well as "Git Bash".
52 - Tell the installer to treat line endings "as is" (i.e. both DOS and Unix-style line endings).
53 - Install both the 32-bit and 64-bit versions, as the 64-bit installer does not install the
54 32-bit libraries and tools.
55 - Vulkan Loader Library
56 - Building the cube and vulkaninfo applications require linking to the Vulkan Loader Library (vulkan-1.dll).
57 Locating the library for this repo can be done in two different ways:
58 - The Vulkan SDK can be installed. In this case, cmake should be able to locate the loader repo through the VulkanSDK
60 - The library can be built from the [Vulkan-Loader](https://github.com/KhronosGroup/Vulkan-Loader.git) repository.
61 In this case, the following option should be used on the cmake command line:
62 LOADER_REPO_ROOT=c:\absolute_path_to\Vulkan-Loader
63 and use absolute (not relative) paths, like so:
64 cmake -DLOADER_REPO_ROOT=c:\absolute_path_to\Vulkan-Loader ....
65 - [glslang](https://github.com/KhronosGroup/glslang)
66 - By default, the build scripts will attempt to download the necessary components from the glslang repo.
67 However, if a specific version of this file is required, please see the [Custom glslang Version](#custom-glslang-version) section below.
69 ### Windows Build - Microsoft Visual Studio
71 1. Open a Developer Command Prompt for VS201x
72 2. Change directory to `Vulkan-Tools` -- the root of the cloned git repository
73 3. Run 'git submodule update --init --recursive' -- this will download in-tree external dependencies
74 4. Create a `build` directory, change into that directory, and run cmake
76 For example, assuming an SDK is installed, for VS2017 (generators for other versions are [specified here](#cmake-visual-studio-generators)):
78 cmake "Visual Studio 15 2017 Win64" ..
80 If a specific version of the Loader is requred, specify the root of the loader repository, like so:
82 cmake -DLOADER_REPO_ROOT=c:/absolute_path_to/Vulkan-Loader -G "Visual Studio 15 2017 Win64" ..
84 This will create a Windows solution file named `Vulkan-Tools.sln` in the build directory.
86 Launch Visual Studio and open the "Vulkan-Tools.sln" solution file in the build folder.
87 You may select "Debug" or "Release" from the Solution Configurations drop-down list.
88 Start a build by selecting the Build->Build Solution menu item.
89 This solution copies the loader it built to each program's build directory
90 to ensure that the program uses the loader built from this solution.
94 #### CMake Visual Studio Generators
96 The above example used Visual Studio 2017, and specified its generator as "Visual Studio 15 2017 Win64".
97 The chosen generator should match your Visual Studio version. Appropriate Visual Studio generators include:
99 | Build Platform | 64-bit Generator | 32-bit Generator |
100 |------------------------------|-------------------------------|-------------------------|
101 | Microsoft Visual Studio 2013 | "Visual Studio 12 2013 Win64" | "Visual Studio 12 2013" |
102 | Microsoft Visual Studio 2015 | "Visual Studio 14 2015 Win64" | "Visual Studio 14 2015" |
103 | Microsoft Visual Studio 2017 | "Visual Studio 15 2017 Win64" | "Visual Studio 15 2017" |
107 ### Linux Build Requirements
109 This repository has been built and tested on the two most recent Ubuntu LTS versions.
110 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.
111 It should be straightforward to adapt this repository to other Linux distributions.
113 **Required Package List:**
115 sudo apt-get install git cmake build-essential libx11-xcb-dev libxkbcommon-dev libmirclient-dev libwayland-dev libxrandr-dev
117 - [glslang](https://github.com/KhronosGroup/glslang)
118 - By default, the build scripts will attempt to download the necessary components from the glslang repo.
119 However, if a specific version of this file is required, please see the [Custom glslang Version](#custom-glslang-version) section below.
121 Vulkan Loader Library
122 - Building the cube and vulkaninfo applications require linking to the Vulkan Loader Library (libvulkan-1.so).
123 - The following option should be used on the cmake command line to specify a vulkan loader library:
124 LOADER_REPO_ROOT=c:\absolute_path_to\Vulkan-Loader
125 makeing sure to specify an absoute path, like so:
126 cmake -DLOADER_REPO_ROOT=c:\absolute_path_to\Vulkan-Loader ....
132 See **Loader and Validation Layer Dependencies** for more information and other options:
134 1. In a Linux terminal, `cd Vulkan-Tools` -- the root of the cloned git repository
135 2. Execute 'git submodule update --init --recursive' -- this will download in-tree external components
136 3. Create a `build` directory, change into that directory, and run cmake:
140 # If an SDK is installed and the setup-env.sh script has been run,
141 cmake -DCMAKE_BUILD_TYPE=Debug ..
142 # Else if a specific version of the loader is desired, indicate the root of the loader repository like so:
143 cmake -DLOADER_REPO_ROOT=/absolute_path_to/Vulkan-Loader -DCMAKE_BUILD_TYPE=Debug ..
145 4. Run `make -j8` to begin the build
147 If your build system supports ccache, you can enable that via CMake option `-DUSE_CCACHE=On`
149 ### WSI Support Build Options
151 By default, the Vulkan Tools are built with support for all 4 Vulkan-defined WSI display servers: Xcb, Xlib, Wayland, and Mir.
152 It is recommended to build the repository components with support for these display servers to maximize their usability across Linux platforms.
153 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`.
154 See the top-level CMakeLists.txt file for more info.
156 ### Linux Install to System Directories
158 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.
159 There are also risks with interfering with binaries installed by packages.
160 If you are certain that you would like to install your binaries to system directories, you can proceed with these instructions.
162 Assuming that you have built the code as described above and the current directory is still `build`, you can execute:
166 This command installs files to:
168 - `/usr/local/include/vulkan`: Vulkan include files
169 - `/usr/local/lib`: Vulkan Tools shared objects
170 - `/usr/local/bin`: vulkaninfo application
171 - `/usr/local/bin`: cube application
172 - `/usr/local/bin`: cubepp application
174 You may need to run `ldconfig` in order to refresh the system loader search cache on some Linux systems.
176 You can further customize the installation location by setting additional CMake variables to override their defaults.
177 For example, if you would like to install to `/tmp/build` instead of `/usr/local`, on your CMake command line specify:
179 -DCMAKE_INSTALL_PREFIX=/tmp/build
180 -DDEST_DIR=/tmp/build
182 Then run `make install` as before. The install step places the files in `/tmp/build`.
184 You can further customize the installation directories by using the CMake variables
185 `CMAKE_INSTALL_SYSCONFDIR` to rename the `etc` directory and `CMAKE_INSTALL_DATADIR`
186 to rename the `share` directory.
188 See the CMake documentation for more details on using these variables
189 to further customize your installation.
193 To uninstall the files from the system directories, you can execute:
199 After making any changes to the repository, you should perform some quick sanity tests, such as
200 running the cube demo with validation enabled.
202 To run the **Cube application** with validation, in a terminal change to the `build/cube`
205 VK_LAYER_PATH=../path/to/validation/layers ./cube --validate
207 You can select which WSI subsystem is used to build the cube applications using a CMake option
208 called DEMOS_WSI_SELECTION.
209 Supported options are XCB (default), XLIB, WAYLAND, and MIR.
210 Note that you must build using the corresponding BUILD_WSI_*_SUPPORT enabled at the
211 base repository level (all SUPPORT options are ON by default).
212 For instance, creating a build that will use Xlib to build the demos,
213 your CMake command line might look like:
215 cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Debug -DDEMOS_WSI_SELECTION=XLIB
219 #### Linux 32-bit support
221 Usage of the contents of this repository in 32-bit Linux environments is not officially supported.
222 However, since this repository is supported on 32-bit Windows,
223 these modules should generally work on 32-bit Linux.
225 Here are some notes for building 32-bit targets on a 64-bit Ubuntu "reference" platform:
227 If not already installed, install the following 32-bit development libraries:
229 `gcc-multilib g++-multilib libx11-dev:i386`
231 This list may vary depending on your distribution and which windowing systems you are building for.
233 Set up your environment for building 32-bit targets:
238 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu
240 Again, your PKG_CONFIG configuration may be different, depending on your distribution.
242 Finally, rebuild the repository using `cmake` and `make`, as explained above.
244 ## Building On Android
246 Install the required tools for Linux and Windows covered above, then add the following.
248 ### Android Build Requirements
250 - Install [Android Studio 2.3](https://developer.android.com/studio/index.html) or later.
251 - From the "Welcome to Android Studio" splash screen, add the following components using
252 Configure > SDK Manager:
253 - SDK Platforms > Android 6.0 and newer
254 - SDK Tools > Android SDK Build-Tools
255 - SDK Tools > Android SDK Platform-Tools
256 - SDK Tools > Android SDK Tools
259 #### Add Android specifics to environment
261 For each of the below, you may need to specify a different build-tools version, as Android Studio will roll it forward fairly regularly.
265 export ANDROID_SDK_HOME=$HOME/Android/sdk
266 export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk-bundle
267 export PATH=$ANDROID_SDK_HOME:$PATH
268 export PATH=$ANDROID_NDK_HOME:$PATH
269 export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
273 set ANDROID_SDK_HOME=%LOCALAPPDATA%\Android\sdk
274 set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk-bundle
275 set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH%
279 export ANDROID_SDK_HOME=$HOME/Library/Android/sdk
280 export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk-bundle
281 export PATH=$ANDROID_NDK_PATH:$PATH
282 export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
284 Note: If `jarsigner` is missing from your platform, you can find it in the
285 Android Studio install or in your Java installation.
286 If you do not have Java, you can get it with something like the following:
288 sudo apt-get install openjdk-8-jdk
290 #### Additional OSX System Requirements
292 Tested on OSX version 10.13.3
294 Setup Homebrew and components
296 - Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
298 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
300 - Ensure Homebrew is at the beginning of your PATH:
302 export PATH=/usr/local/bin:$PATH
304 - Add packages with the following:
306 brew install cmake python
310 There are two options for building the Android tools.
311 Either using the SPIRV tools provided as part of the Android NDK, or using upstream sources.
312 To build with SPIRV tools from the NDK, remove the build-android/third_party directory created by
313 running update_external_sources_android.sh, (or avoid running update_external_sources_android.sh).
314 Use the following script to build everything in the repository for Android, including validation
315 layers, tests, demos, and APK packaging: This script does retrieve and use the upstream SPRIV tools.
320 Test and application APKs can be installed on production devices with:
322 ./install_all.sh [-s <serial number>]
324 Note that there are no equivalent scripts on Windows yet, that work needs to be completed.
325 The following per platform commands can be used for layer only builds:
329 Follow the setup steps for Linux or OSX above, then from your terminal:
332 ./update_external_sources_android.sh --no-build
333 ./android-generate.sh
338 Follow the setup steps for Windows above, then from Developer Command Prompt for VS2013:
341 update_external_sources_android.bat
345 ### Android Tests and Demos
347 After making any changes to the repository you should perform some quick sanity tests,
348 including the layer validation tests and the cube and smoke demos with validation enabled.
350 #### Run Layer Validation Tests
352 Use the following steps to build, install, and run the layer validation tests for Android:
356 adb install -r bin/VulkanLayerValidationTests.apk
357 adb shell am start com.example.VulkanLayerValidationTests/android.app.NativeActivity
359 Alternatively, you can use the test_APK script to install and run the layer validation tests:
361 test_APK.sh -s <serial number> -p <plaform name> -f <gtest_filter>
363 #### Run Cube with Validation
365 TODO: This must be reworked to pull in layers from the ValidationLayers repo
367 Use the following steps to build, install, and run Cube for Android:
371 adb install -r ../demos/android/cube/bin/cube.apk
372 adb shell am start com.example.Cube/android.app.NativeActivity
374 To build, install, and run Cube with validation layers,
375 first build layers using steps above, then run:
379 adb install -r ../demos/android/cube-with-layers/bin/cube-with-layers.apk
381 ##### Run without validation enabled
383 adb shell am start com.example.CubeWithLayers/android.app.NativeActivity
385 ##### Run with validation enabled
387 adb shell am start -a android.intent.action.MAIN -c android-intent.category.LAUNCH -n com.example.CubeWithLayers/android.app.NativeActivity --es args "--validate"
391 ### MacOS Build Requirements
393 Tested on OSX version 10.12.6
395 Setup Homebrew and components
397 - Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
399 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
401 - Ensure Homebrew is at the beginning of your PATH:
403 export PATH=/usr/local/bin:$PATH
405 - Add packages with the following (may need refinement)
407 brew install cmake python python3 git
409 - [glslang](https://github.com/KhronosGroup/glslang)
410 - By default, the build scripts will attempt to download the necessary components from the glslang repo.
411 However, if a specific version of this file is required, please see the [Custom glslang Version](#custom-glslang-version) section below.
413 ### Clone the Repository
415 Clone the Vulkan-LoaderAndValidationLayers repository:
417 git clone https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers.git
419 ### Get the External Libraries
421 TODO: Update with macOS procedure for satisfying external dependencies
425 #### CMake Generators
427 This repository uses CMake to generate build or project files that are
428 then used to build the repository.
429 The CMake generators explicitly supported in this repository are:
434 #### Building with the Unix Makefiles Generator
436 This generator is the default generator, so all that is needed for a debug
441 cmake -DCMAKE_BUILD_TYPE=Debug ..
444 To speed up the build on a multi-core machine, use the `-j` option for `make`
445 to specify the number of cores to use for the build.
450 You can now run the demo applications from the command line:
453 open demos/cubepp.app
454 open demos/vulkaninfo.app
456 Or you can locate them from `Finder` and launch them from there.
458 ##### The Install Target and RPATH
460 The applications you just built are "bundled applications", but the executables
461 are using the `RPATH` mechanism to locate runtime dependencies that are still
464 To see this, run this command from your `build` directory:
466 otool -l demos/cube.app/Contents/MacOS/cube
468 and note that the `cube` executable contains loader commands:
470 - `LC_LOAD_DYLIB` to load `libvulkan.1.dylib` via an `@rpath`
471 - `LC_RPATH` that contains an absolute path to the build location of the Vulkan loader
473 This makes the bundled application "non-transportable", meaning that it won't run
474 unless the Vulkan loader is on that specific absolute path.
475 This is useful for debugging the loader or other components built in this repository,
476 but not if you want to move the application to another machine or remove your build tree.
478 To address this problem, run:
482 This step "cleans up" the `RPATH` to remove any external references
483 and performs other bundle fix-ups.
484 After running `make install`, re-run the `otool` command again and note:
486 - `LC_LOAD_DYLIB` is now `@executable_path/../MacOS/libvulkan.1.dylib`
487 - `LC_RPATH` is no longer present
489 The "bundle fix-up" operation also puts a copy of the Vulkan loader into the bundle,
490 making the bundle completely self-contained and self-referencing.
492 Note that the "install" target has a very different meaning compared to the Linux
493 "make install" target.
494 The Linux "install" copies the targets to system directories.
495 In MacOS, "install" means fixing up application bundles.
496 In both cases, the "install" target operations clean up the `RPATH`.
498 ##### The Non-bundled vulkaninfo Application
500 There is also a non-bundled version of the `vulkaninfo` application that you can
501 run from the command line:
505 If you run this before you run "make install", vulkaninfo's RPATH is already set
506 to point to the Vulkan loader in the build tree, so it has no trouble finding it.
507 But the loader will not find the MoltenVK driver and you'll see a message about an
508 incompatible driver. To remedy this:
510 VK_ICD_FILENAMES=../external/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json demos/vulkaninfo
512 If you run `vulkaninfo` after doing a "make install", the `RPATH` in the `vulkaninfo` application
513 got removed and the OS needs extra help to locate the Vulkan loader:
515 DYLD_LIBRARY_PATH=loader VK_ICD_FILENAMES=../external/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json demos/vulkaninfo
517 #### Building with the Xcode Generator
519 To create and open an Xcode project:
524 open VULKAN.xcodeproj
526 Within Xcode, you can select Debug or Release builds in the project's Build Settings.
527 You can also select individual schemes for working with specific applications like `cube`.
529 ## Ninja Builds - All Platforms
531 The [Qt Creator IDE](https://qt.io/download-open-source/#section-2) can open a root CMakeList.txt
532 as a project directly, and it provides tools within Creator to configure and generate Vulkan SDK
533 build files for one to many targets concurrently.
534 Alternatively, when invoking CMake, use the `-G "Codeblocks - Ninja"` option to generate Ninja build
535 files to be used as project files for QtCreator
537 - Open, configure, and build the Vulkan-Tools CMakeList.txt file
538 - In order to debug with QtCreator, a
539 [Microsoft WDK: eg WDK 10](http://go.microsoft.com/fwlink/p/?LinkId=526733) is required.
541 Note that installing the WDK breaks the MSVC vcvarsall.bat build scripts provided by MSVC,
542 requiring that the LIB, INCLUDE, and PATHenv variables be set to the WDK paths by some other means
544 ## Custom glslang version
546 The Glslang repository is not a git sub-module of Vulkan-Tools, but glslang components are required to build
547 the cube and vulkaninfo applications. By default, the cmake scripts will download the required
548 components into the repo 'glslang' directory.
550 If a specific version of the glslang components is desired, perform the following steps:
552 1) clone the glslang repository:
554 `git clone https://github.com/KhronosGroup/glslang.git`
556 2) Configure the glslang source tree with CMake and build it with your IDE of choice
558 3) Pass the location of the glslang repository using an absolute path via your cmake command like so:
560 cmake -DGLSLANG_REPO_ROOT=c:\absolute_path_to\glslang
562 4) If building on Windows with MSVC, set `DISABLE_BUILDTGT_DIR_DECORATION` to _On_.
563 If building on Windows, but without MSVC set `DISABLE_BUILD_PATH_DECORATION` to _On_
565 ## Optional software packages
567 - [Cygwin for windows](https://www.cygwin.com/)
568 - Cygwin provides some Linux-like tools, which can be valuable for working with the repository,
569 such as the BASH shell and git packages
570 - With appropriate adjustments, it is possible to use other shells and environments as well
572 - [Ninja on all platforms](https://github.com/ninja-build/ninja/releases)
573 - [The Ninja-build project](https://ninja-build.org)
574 - [Ninja Users Manual](https://ninja-build.org/manual.html)
576 - [QtCreator as IDE for CMake builds on all platforms](https://qt.io/download-open-source/#section-2)