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-Tools
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 Currently, the build directory *must* be named either 'build' or 'build32'.
66 - [glslang](https://github.com/KhronosGroup/glslang)
67 - By default, the build scripts will attempt to download the necessary components from the glslang repo.
68 However, if a specific version of this file is required, please see the [Custom glslang Version](#custom-glslang-version) section below.
70 ### Windows Build - Microsoft Visual Studio
72 1. Open a Developer Command Prompt for VS201x
73 2. Change directory to `Vulkan-Tools` -- the root of the cloned git repository
74 3. Run 'git submodule update --init --recursive' -- this will download in-tree external dependencies
75 4. Create a `build` directory, change into that directory, and run cmake
77 For example, assuming an SDK is installed, for VS2017 (generators for other versions are [specified here](#cmake-visual-studio-generators)):
79 cmake "Visual Studio 15 2017 Win64" ..
81 If a specific version of the Loader is requred, specify the root of the loader repository, like so:
83 cmake -DLOADER_REPO_ROOT=c:/absolute_path_to/Vulkan-Loader -G "Visual Studio 15 2017 Win64" ..
85 This will create a Windows solution file named `Vulkan-Tools.sln` in the build directory.
87 Launch Visual Studio and open the "Vulkan-Tools.sln" solution file in the build folder.
88 You may select "Debug" or "Release" from the Solution Configurations drop-down list.
89 Start a build by selecting the Build->Build Solution menu item.
90 This solution copies the loader it built to each program's build directory
91 to ensure that the program uses the loader built from this solution.
93 #### Windows Install Target
95 The CMake project also generates an "install" target that you can use to
96 copy the primary build artifacts to a specific location using a
97 "bin, include, lib" style directory structure.
98 This may be useful for collecting the artifacts and providing them to
99 another project that is dependent on them.
101 The default location is `$CMAKE_BINARY_DIR\install`, but can be changed
102 with the `CMAKE_INSTALL_PREFIX` variable.
103 You can build the install target with:
105 cmake --build . --config Release --target install
107 or build the `INSTALL` target from the Visual Studio solution explorer.
111 #### CMake Visual Studio Generators
113 The above example used Visual Studio 2017, and specified its generator as "Visual Studio 15 2017 Win64".
114 The chosen generator should match your Visual Studio version. Appropriate Visual Studio generators include:
116 | Build Platform | 64-bit Generator | 32-bit Generator |
117 |------------------------------|-------------------------------|-------------------------|
118 | Microsoft Visual Studio 2013 | "Visual Studio 12 2013 Win64" | "Visual Studio 12 2013" |
119 | Microsoft Visual Studio 2015 | "Visual Studio 14 2015 Win64" | "Visual Studio 14 2015" |
120 | Microsoft Visual Studio 2017 | "Visual Studio 15 2017 Win64" | "Visual Studio 15 2017" |
124 ### Linux Build Requirements
126 This repository has been built and tested on the two most recent Ubuntu LTS versions.
127 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.
128 It should be straightforward to adapt this repository to other Linux distributions.
130 **Required Package List:**
132 sudo apt-get install git cmake build-essential libx11-xcb-dev libxkbcommon-dev libmirclient-dev libwayland-dev libxrandr-dev
134 - [glslang](https://github.com/KhronosGroup/glslang)
135 - By default, the build scripts will attempt to download the necessary components from the glslang repo.
136 However, if a specific version of this file is required, please see the [Custom glslang Version](#custom-glslang-version) section below.
138 Vulkan Loader Library
139 - Building the cube and vulkaninfo applications require linking to the Vulkan Loader Library (libvulkan.so.1).
140 - The following option should be used on the cmake command line to specify a vulkan loader library:
141 LOADER_REPO_ROOT=/absolute_path_to/Vulkan-Loader
142 making sure to specify an absoute path, like so:
143 cmake -DLOADER_REPO_ROOT=/absolute_path_to/Vulkan-Loader ....
144 Currently, the build directory *must* be named either 'build' or 'build32'.
150 See **Loader and Validation Layer Dependencies** for more information and other options:
152 1. In a Linux terminal, `cd Vulkan-Tools` -- the root of the cloned git repository
153 2. Execute 'git submodule update --init --recursive' -- this will download in-tree external components
154 3. Create a `build` directory, change into that directory, and run cmake:
158 # If an SDK is installed and the setup-env.sh script has been run,
159 cmake -DCMAKE_BUILD_TYPE=Debug ..
160 # Else if a specific version of the loader is desired, indicate the root of the loader repository like so:
161 cmake -DLOADER_REPO_ROOT=/absolute_path_to/Vulkan-Loader -DCMAKE_BUILD_TYPE=Debug ..
163 4. Run `make -j8` to begin the build
165 If your build system supports ccache, you can enable that via CMake option `-DUSE_CCACHE=On`
167 ### WSI Support Build Options
169 By default, the Vulkan Tools cube and cubepp are built with support for all 4 Vulkan-defined WSI display servers: Xcb, Xlib, Wayland, and Mir.
170 It is recommended to build the repository components with support for these display servers to maximize their usability across Linux platforms.
171 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`.
172 See the CMakeLists.txt file in `Vulkan-Tools/cube` for more info.
174 Note vulkaninfo currently only supports Xcb and Xlib WSI display servers. See the CMakeLists.txt file in `Vulkan-Tools/vulkaninfo` for more info.
176 ### Linux Install to System Directories
178 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.
179 There are also risks with interfering with binaries installed by packages.
180 If you are certain that you would like to install your binaries to system directories, you can proceed with these instructions.
182 Assuming that you have built the code as described above and the current directory is still `build`, you can execute:
186 This command installs files to:
188 - `/usr/local/lib`: Vulkan Tools shared objects (e.g., Mock ICD shared library)
189 - `/usr/local/bin`: cube, cubepp, and vulkaninfo applications
190 - `/usr/local/share/vulkan/icd.d`: Mock ICD JSON file
192 You may need to run `ldconfig` in order to refresh the system loader search cache on some Linux systems.
194 Note: The Mock ICD is not installed by default since it is a "null" driver that does not render anything
195 and is used for testing purposes.
196 Installing it to system directories may cause some applications to discover and use
197 this driver instead of other full drivers installed on the system.
198 If you really want to install this null driver, use:
202 You can further customize the installation location by setting additional CMake variables to override their defaults.
203 For example, if you would like to install to `/tmp/build` instead of `/usr/local`, on your CMake command line specify:
205 -DCMAKE_INSTALL_PREFIX=/tmp/build
206 -DDEST_DIR=/tmp/build
208 Then run `make install` as before. The install step places the files in `/tmp/build`.
210 You can further customize the installation directories by using the CMake variables
211 `CMAKE_INSTALL_SYSCONFDIR` to rename the `etc` directory and `CMAKE_INSTALL_DATADIR`
212 to rename the `share` directory.
214 See the CMake documentation for more details on using these variables
215 to further customize your installation.
219 To uninstall the files from the system directories, you can execute:
221 sudo make uninstall-Vulkan-Tools
225 After making any changes to the repository, you should perform some quick sanity tests, such as
226 running the cube demo with validation enabled.
228 To run the **Cube application** with validation, in a terminal change to the `build/cube`
231 VK_LAYER_PATH=../path/to/validation/layers ./cube --validate
233 You can select which WSI subsystem is used to build the cube applications using a CMake option
234 called DEMOS_WSI_SELECTION.
235 Supported options are XCB (default), XLIB, WAYLAND, and MIR.
236 Note that you must build using the corresponding BUILD_WSI_*_SUPPORT enabled at the
237 base repository level (all SUPPORT options are ON by default).
238 For instance, creating a build that will use Xlib to build the demos,
239 your CMake command line might look like:
241 cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Debug -DDEMOS_WSI_SELECTION=XLIB
245 #### Linux 32-bit support
247 Usage of the contents of this repository in 32-bit Linux environments is not officially supported.
248 However, since this repository is supported on 32-bit Windows,
249 these modules should generally work on 32-bit Linux.
251 Here are some notes for building 32-bit targets on a 64-bit Ubuntu "reference" platform:
253 If not already installed, install the following 32-bit development libraries:
255 `gcc-multilib g++-multilib libx11-dev:i386`
257 This list may vary depending on your distribution and which windowing systems you are building for.
259 Set up your environment for building 32-bit targets:
264 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu
266 Again, your PKG_CONFIG configuration may be different, depending on your distribution.
268 Finally, rebuild the repository using `cmake` and `make`, as explained above.
270 ## Building On Android
272 Install the required tools for Linux and Windows covered above, then add the following.
274 ### Android Build Requirements
276 - Install [Android Studio 2.3](https://developer.android.com/studio/index.html) or later.
277 - From the "Welcome to Android Studio" splash screen, add the following components using
278 Configure > SDK Manager:
279 - SDK Platforms > Android 6.0 and newer
280 - SDK Tools > Android SDK Build-Tools
281 - SDK Tools > Android SDK Platform-Tools
282 - SDK Tools > Android SDK Tools
285 #### Add Android specifics to environment
287 For each of the below, you may need to specify a different build-tools version, as Android Studio will roll it forward fairly regularly.
291 export ANDROID_SDK_HOME=$HOME/Android/sdk
292 export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk-bundle
293 export PATH=$ANDROID_SDK_HOME:$PATH
294 export PATH=$ANDROID_NDK_HOME:$PATH
295 export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
299 set ANDROID_SDK_HOME=%LOCALAPPDATA%\Android\sdk
300 set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk-bundle
301 set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH%
305 export ANDROID_SDK_HOME=$HOME/Library/Android/sdk
306 export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk-bundle
307 export PATH=$ANDROID_NDK_PATH:$PATH
308 export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
310 Note: If `jarsigner` is missing from your platform, you can find it in the
311 Android Studio install or in your Java installation.
312 If you do not have Java, you can get it with something like the following:
314 sudo apt-get install openjdk-8-jdk
316 #### Additional OSX System Requirements
318 Tested on OSX version 10.13.3
320 Setup Homebrew and components
322 - Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
324 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
326 - Ensure Homebrew is at the beginning of your PATH:
328 export PATH=/usr/local/bin:$PATH
330 - Add packages with the following:
332 brew install cmake python
336 There are two options for building the Android tools.
337 Either using the SPIRV tools provided as part of the Android NDK, or using upstream sources.
338 To build with SPIRV tools from the NDK, remove the build-android/third_party directory created by
339 running update_external_sources_android.sh, (or avoid running update_external_sources_android.sh).
340 Use the following script to build everything in the repository for Android, including validation
341 layers, tests, demos, and APK packaging: This script does retrieve and use the upstream SPRIV tools.
346 Test and application APKs can be installed on production devices with:
348 ./install_all.sh [-s <serial number>]
350 Note that there are no equivalent scripts on Windows yet, that work needs to be completed.
351 The following per platform commands can be used for layer only builds:
355 Follow the setup steps for Linux or OSX above, then from your terminal:
358 ./update_external_sources_android.sh --no-build
359 ./android-generate.sh
364 Follow the setup steps for Windows above, then from Developer Command Prompt for VS2013:
367 update_external_sources_android.bat
371 ### Android Tests and Demos
373 After making any changes to the repository you should perform some quick sanity tests,
374 including the layer validation tests and the cube and smoke demos with validation enabled.
376 #### Run Layer Validation Tests
378 Use the following steps to build, install, and run the layer validation tests for Android:
382 adb install -r bin/VulkanLayerValidationTests.apk
383 adb shell am start com.example.VulkanLayerValidationTests/android.app.NativeActivity
385 Alternatively, you can use the test_APK script to install and run the layer validation tests:
387 test_APK.sh -s <serial number> -p <plaform name> -f <gtest_filter>
389 #### Run Cube with Validation
391 TODO: This must be reworked to pull in layers from the ValidationLayers repo
393 Use the following steps to build, install, and run Cube for Android:
397 adb install -r ../demos/android/cube/bin/cube.apk
398 adb shell am start com.example.Cube/android.app.NativeActivity
400 To build, install, and run Cube with validation layers,
401 first build layers using steps above, then run:
405 adb install -r ../demos/android/cube-with-layers/bin/cube-with-layers.apk
407 ##### Run without validation enabled
409 adb shell am start com.example.CubeWithLayers/android.app.NativeActivity
411 ##### Run with validation enabled
413 adb shell am start -a android.intent.action.MAIN -c android-intent.category.LAUNCH -n com.example.CubeWithLayers/android.app.NativeActivity --es args "--validate"
417 ### MacOS Build Requirements
419 Tested on OSX version 10.12.6
421 Setup Homebrew and components
423 - Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
425 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
427 - Ensure Homebrew is at the beginning of your PATH:
429 export PATH=/usr/local/bin:$PATH
431 - Add packages with the following (may need refinement)
433 brew install cmake python python3 git
435 - [glslang](https://github.com/KhronosGroup/glslang)
436 - By default, the build scripts will attempt to download the necessary components from the glslang repo.
437 However, if a specific version of this file is required, please see the [Custom glslang Version](#custom-glslang-version) section below.
439 ### Clone the Repository
441 Clone the Vulkan-LoaderAndValidationLayers repository:
443 git clone https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers.git
445 ### Get the External Libraries
447 [MoltenVK](https://github.com/KhronosGroup/MoltenVK) Library
449 - Building the cube and vulkaninfo applications require linking to the MoltenVK Library (libMoltenVK.dylib)
450 - The following option should be used on the cmake command line to specify a vulkan loader library:
451 MOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK making sure to specify an absolute path, like so:
452 cmake -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK ....
454 Vulkan Loader Library
456 - Building the cube and vulkaninfo applications require linking to the Vulkan Loader Library (libvulkan.1.dylib)
457 - The following option should be used on the cmake command line to specify a vulkan loader library:
458 LOADER_REPO_ROOT=/absolute_path_to/Vulkan-Loader making sure to specify an absolute path, like so:
459 cmake -DLOADER_REPO_ROOT=/absolute_path_to/Vulkan-Loader ....
463 #### CMake Generators
465 This repository uses CMake to generate build or project files that are
466 then used to build the repository.
467 The CMake generators explicitly supported in this repository are:
472 #### Building with the Unix Makefiles Generator
474 This generator is the default generator, so all that is needed for a debug
479 cmake -DCMAKE_BUILD_TYPE=Debug -DLOADER_REPO_ROOT=/absolute_path_to/Vulkan-Loader -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK ..
482 To speed up the build on a multi-core machine, use the `-j` option for `make`
483 to specify the number of cores to use for the build.
488 You can now run the demo applications from the command line:
492 open vulkaninfo/vulkaninfo.app
494 Or you can locate them from `Finder` and launch them from there.
496 ##### The Install Target and RPATH
498 The applications you just built are "bundled applications", but the executables
499 are using the `RPATH` mechanism to locate runtime dependencies that are still
502 To see this, run this command from your `build` directory:
504 otool -l cube/cube.app/Contents/MacOS/cube
506 and note that the `cube` executable contains loader commands:
508 - `LC_LOAD_DYLIB` to load `libvulkan.1.dylib` via an `@rpath`
509 - `LC_RPATH` that contains an absolute path to the build location of the Vulkan loader
511 This makes the bundled application "non-transportable", meaning that it won't run
512 unless the Vulkan loader is on that specific absolute path.
513 This is useful for debugging the loader or other components built in this repository,
514 but not if you want to move the application to another machine or remove your build tree.
516 To address this problem, run:
520 This step "cleans up" the `RPATH` to remove any external references
521 and performs other bundle fix-ups.
522 After running `make install`, re-run the `otool` command again and note:
524 - `LC_LOAD_DYLIB` is now `@executable_path/../MacOS/libvulkan.1.dylib`
525 - `LC_RPATH` is no longer present
527 The "bundle fix-up" operation also puts a copy of the Vulkan loader into the bundle,
528 making the bundle completely self-contained and self-referencing.
530 Note that the "install" target has a very different meaning compared to the Linux
531 "make install" target.
532 The Linux "install" copies the targets to system directories.
533 In MacOS, "install" means fixing up application bundles.
534 In both cases, the "install" target operations clean up the `RPATH`.
536 ##### The Non-bundled vulkaninfo Application
538 There is also a non-bundled version of the `vulkaninfo` application that you can
539 run from the command line:
541 vulkaninfo/vulkaninfo
543 If you run this before you run "make install", vulkaninfo's RPATH is already set
544 to point to the Vulkan loader in the build tree, so it has no trouble finding it.
545 But the loader will not find the MoltenVK driver and you'll see a message about an
546 incompatible driver. To remedy this:
548 VK_ICD_FILENAMES=<path-to>/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json demos/vulkaninfo
550 If you run `vulkaninfo` after doing a "make install", the `RPATH` in the `vulkaninfo` application
551 got removed and the OS needs extra help to locate the Vulkan loader:
553 DYLD_LIBRARY_PATH=<path-to>/Vulkan-Loader/loader VK_ICD_FILENAMES=<path-to>/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json demos/vulkaninfo
555 #### Building with the Xcode Generator
557 To create and open an Xcode project:
561 cmake -DLOADER_REPO_ROOT=/absolute_path_to/Vulkan-Loader -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK -GXcode ..
562 open VULKAN.xcodeproj
564 Within Xcode, you can select Debug or Release builds in the project's Build Settings.
565 You can also select individual schemes for working with specific applications like `cube`.
567 ## Ninja Builds - All Platforms
569 The [Qt Creator IDE](https://qt.io/download-open-source/#section-2) can open a root CMakeList.txt
570 as a project directly, and it provides tools within Creator to configure and generate Vulkan SDK
571 build files for one to many targets concurrently.
572 Alternatively, when invoking CMake, use the `-G "Codeblocks - Ninja"` option to generate Ninja build
573 files to be used as project files for QtCreator
575 - Open, configure, and build the Vulkan-Tools CMakeList.txt file
576 - In order to debug with QtCreator, a
577 [Microsoft WDK: eg WDK 10](http://go.microsoft.com/fwlink/p/?LinkId=526733) is required.
579 Note that installing the WDK breaks the MSVC vcvarsall.bat build scripts provided by MSVC,
580 requiring that the LIB, INCLUDE, and PATHenv variables be set to the WDK paths by some other means
582 ## Custom glslang version
584 The Glslang repository is not a git sub-module of Vulkan-Tools, but glslang components are required to build
585 the cube and cubepp applications. By default, the cmake scripts will download the required
586 components into the repo 'glslang' directory.
588 If a *specific* version of the glslang components is desired, perform the following steps:
590 1) clone the glslang repository:
592 `git clone https://github.com/KhronosGroup/glslang.git`
594 2) Configure the glslang source tree with CMake and build it with your IDE of choice, following the instructions
595 in the glslang BUILD.md document including using the INSTALL_PREFIX and 'make install'. Note the install directory.
597 3) Pass the location of the glslang install directory using an absolute path via your cmake command like so:
599 cmake -DGLSLANG_INSTALL_DIR=c:\absolute_path_to\glslang\build\install
601 ## Optional software packages
603 - [Cygwin for windows](https://www.cygwin.com/)
604 - Cygwin provides some Linux-like tools, which can be valuable for working with the repository,
605 such as the BASH shell and git packages
606 - With appropriate adjustments, it is possible to use other shells and environments as well
608 - [Ninja on all platforms](https://github.com/ninja-build/ninja/releases)
609 - [The Ninja-build project](https://ninja-build.org)
610 - [Ninja Users Manual](https://ninja-build.org/manual.html)
612 - [QtCreator as IDE for CMake builds on all platforms](https://qt.io/download-open-source/#section-2)