1# Build Instructions 2 3Instructions for building this repository on Linux, Windows, Android, and 4MacOS. 5 6## Index 7 81. [Contributing](#contributing-to-the-repository) 91. [Repository Content](#repository-content) 101. [Repository Set-Up](#repository-set-up) 111. [Windows Build](#building-on-windows) 121. [Linux Build](#building-on-linux) 131. [Android Build](#building-on-android) 141. [MacOS build](#building-on-macos) 15 16## Contributing to the Repository 17 18If you intend to contribute, the preferred work flow is for you to develop 19your contribution in a fork of this repository in your GitHub account and then 20submit a pull request. Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file 21in this repository for more details. 22 23## Repository Content 24 25This repository contains the source code necessary to build the Vulkan 26validation layers and their tests. 27 28### Installed Files 29 30The `install` target installs the following files under the directory 31indicated by *install_dir*: 32 33- *install_dir*`/lib` : The Vulkan validation layer libraries 34- *install_dir*`/share/vulkan/explicit_layer.d` : The Vulkan validation layer 35 JSON files (Linux and MacOS) 36 37The `uninstall` target can be used to remove the above files from the install 38directory. 39 40## Repository Set-Up 41 42### Display Drivers 43 44This repository does not contain a Vulkan-capable driver. You will need to 45obtain and install a Vulkan driver from your graphics hardware vendor or from 46some other suitable source if you intend to run Vulkan applications. 47 48### Download the Repository 49 50To create your local git repository: 51 52 git clone https://github.com/KhronosGroup/Vulkan-ValidationLayers.git 53 54### Repository Dependencies 55 56This repository attempts to resolve some of its dependencies by using 57components found from the following places, in this order: 58 591. CMake or Environment variable overrides (e.g., -DVULKAN_HEADERS_INSTALL_DIR) 601. LunarG Vulkan SDK, located by the `VULKAN_SDK` environment variable 611. System-installed packages, mostly applicable on Linux 62 63Dependencies that cannot be resolved by the SDK or installed packages must be 64resolved with the "install directory" override and are listed below. The 65"install directory" override can also be used to force the use of a specific 66version of that dependency. 67 68#### Vulkan-Headers 69 70This repository has a required dependency on the 71[Vulkan Headers repository](https://github.com/KhronosGroup/Vulkan-Headers). 72You must clone the headers repository and build its `install` target before 73building this repository. The Vulkan-Headers repository is required because it 74contains the Vulkan API definition files (registry) that are required to build 75the validation layers. You must also take note of the headers' install 76directory and pass it on the CMake command line for building this repository, 77as described below. 78 79#### glslang 80 81This repository has a required dependency on the 82[glslang repository](https://github.com/KhronosGroup/glslang). 83The glslang repository is required because it contains components that are 84required to build the validation layers. You must clone the glslang repository 85and build its `install` target. Follow the build instructions in the glslang 86[README.md](https://github.com/KhronosGroup/glslang/blob/master/README.md) 87file. Ensure that the `update_glslang_sources.py` script has been run as part 88of building glslang. You must also take note of the glslang install directory 89and pass it on the CMake command line for building this repository, as 90described below. 91 92#### Google Test 93 94The validation layer tests depend on the 95[Google Test](https://github.com/google/googletest) 96framework and do not build unless this framework is downloaded into the 97repository's `external` directory. 98 99To obtain the framework, change your current directory to the top of your 100Vulkan-ValidationLayers repository and run: 101 102 git clone https://github.com/google/googletest.git external/googletest 103 cd external/googletest 104 git checkout tags/release-1.8.1 105 106before configuring your build with CMake. 107 108If you do not need the tests, there is no need to download this 109framework. 110 111#### Vulkan-Loader 112 113The validation layer tests depend on the Vulkan loader when they execute and 114so a loader is needed only if the tests are built and run. 115 116A loader can be used from an installed LunarG SDK, an installed Linux package, 117or from a driver installation on Windows. 118 119If a loader is not available from any of these methods and/or it is important 120to use a loader built from a repository, then you must build the 121[Vulkan-Loader repository](https://github.com/KhronosGroup/Vulkan-Loader.git) 122with its install target. Take note of its install directory location and pass 123it on the CMake command line for building this repository, as described below. 124 125If you do not intend to run the tests, you do not need a Vulkan loader. 126 127### Build and Install Directories 128 129A common convention is to place the build directory in the top directory of 130the repository with a name of `build` and place the install directory as a 131child of the build directory with the name `install`. The remainder of these 132instructions follow this convention, although you can use any name for these 133directories and place them in any location. 134 135### Building Dependent Repositories with Known-Good Revisions 136 137There is a Python utility script, `scripts/update_deps.py`, that you can use 138to gather and build the dependent repositories mentioned above. This program 139also uses information stored in the `scripts/known-good.json` file to checkout 140dependent repository revisions that are known to be compatible with the 141revision of this repository that you currently have checked out. 142 143Here is a usage example for this repository: 144 145 git clone git@github.com:KhronosGroup/Vulkan-ValidationLayers.git 146 cd Vulkan-ValidationLayers 147 mkdir build 148 cd build 149 ../scripts/update_deps.py 150 cmake -C helper.cmake .. 151 cmake --build . 152 153#### Notes 154 155- You may need to adjust some of the CMake options based on your platform. See 156 the platform-specific sections later in this document. 157- The `update_deps.py` script fetches and builds the dependent repositories in 158 the current directory when it is invoked. In this case, they are built in 159 the `build` directory. 160- The `build` directory is also being used to build this 161 (Vulkan-ValidationLayers) repository. But there shouldn't be any conflicts 162 inside the `build` directory between the dependent repositories and the 163 build files for this repository. 164- The `--dir` option for `update_deps.py` can be used to relocate the 165 dependent repositories to another arbitrary directory using an absolute or 166 relative path. 167- The `update_deps.py` script generates a file named `helper.cmake` and places 168 it in the same directory as the dependent repositories (`build` in this 169 case). This file contains CMake commands to set the CMake `*_INSTALL_DIR` 170 variables that are used to point to the install artifacts of the dependent 171 repositories. You can use this file with the `cmake -C` option to set these 172 variables when you generate your build files with CMake. This lets you avoid 173 entering several `*_INSTALL_DIR` variable settings on the CMake command line. 174- If using "MINGW" (Git For Windows), you may wish to run 175 `winpty update_deps.py` in order to avoid buffering all of the script's 176 "print" output until the end and to retain the ability to interrupt script 177 execution. 178- Please use `update_deps.py --help` to list additional options and read the 179 internal documentation in `update_deps.py` for further information. 180 181### Build Options 182 183When generating native platform build files through CMake, several options can 184be specified to customize the build. Some of the options are binary on/off 185options, while others take a string as input. The following is a table of all 186on/off options currently supported by this repository: 187 188| Option | Platform | Default | Description | 189| ------ | -------- | ------- | ----------- | 190| BUILD_LAYERS | All | `ON` | Controls whether or not the validation layers are built. | 191| BUILD_LAYER_SUPPORT_FILES | All | `OFF` | Controls whether or not layer support files are built if the layers are not built. | 192| BUILD_TESTS | All | `???` | Controls whether or not the validation layer tests are built. The default is `ON` when the Google Test repository is cloned into the `external` directory. Otherwise, the default is `OFF`. | 193| INSTALL_TESTS | All | `OFF` | Controls whether or not the validation layer tests are installed. This option is only available when a copy of Google Test is available 194| BUILD_WSI_XCB_SUPPORT | Linux | `ON` | Build the components with XCB support. | 195| BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the components with Xlib support. | 196| BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the components with Wayland support. | 197| USE_CCACHE | Linux | `OFF` | Enable caching with the CCache program. | 198 199The following is a table of all string options currently supported by this repository: 200 201| Option | Platform | Default | Description | 202| ------ | -------- | ------- | ----------- | 203| CMAKE_OSX_DEPLOYMENT_TARGET | MacOS | `10.12` | The minimum version of MacOS for loader deployment. | 204 205These variables should be set using the `-D` option when invoking CMake to 206generate the native platform files. 207 208## Building On Windows 209 210### Windows Development Environment Requirements 211 212- Windows 213 - Any Personal Computer version supported by Microsoft 214- Microsoft [Visual Studio](https://www.visualstudio.com/) 215 - Versions 216 - [2013 (update 4)](https://www.visualstudio.com/vs/older-downloads/) 217 - [2015](https://www.visualstudio.com/vs/older-downloads/) 218 - [2017](https://www.visualstudio.com/vs/downloads/) 219 - The Community Edition of each of the above versions is sufficient, as 220 well as any more capable edition. 221- [CMake](http://www.cmake.org/download/) (Version 2.8.11 or better) 222 - Use the installer option to add CMake to the system PATH 223- Git Client Support 224 - [Git for Windows](http://git-scm.com/download/win) is a popular solution 225 for Windows 226 - Some IDEs (e.g., [Visual Studio](https://www.visualstudio.com/), 227 [GitHub Desktop](https://desktop.github.com/)) have integrated 228 Git client support 229 230### Windows Build - Microsoft Visual Studio 231 232The general approach is to run CMake to generate the Visual Studio project 233files. Then either run CMake with the `--build` option to build from the 234command line or use the Visual Studio IDE to open the generated solution and 235work with the solution interactively. 236 237#### Windows Quick Start 238 239 cd Vulkan-ValidationLayers 240 mkdir build 241 cd build 242 cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \ 243 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir .. 244 cmake --build . 245 246The above commands instruct CMake to find and use the default Visual Studio 247installation to generate a Visual Studio solution and projects for the x64 248architecture. The second CMake command builds the Debug (default) 249configuration of the solution. 250 251See below for the details. 252 253#### Use `CMake` to Create the Visual Studio Project Files 254 255Change your current directory to the top of the cloned repository directory, 256create a build directory and generate the Visual Studio project files: 257 258 cd Vulkan-ValidationLayers 259 mkdir build 260 cd build 261 cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \ 262 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir .. 263 264> Note: The `..` parameter tells `cmake` the location of the top of the 265> repository. If you place your build directory someplace else, you'll need to 266> specify the location of the repository top differently. 267 268The `-A` option is used to select either the "Win32" or "x64" architecture. 269 270If a generator for a specific version of Visual Studio is required, you can 271specify it for Visual Studio 2015, for example, with: 272 273 64-bit: -G "Visual Studio 14 2015 Win64" 274 32-bit: -G "Visual Studio 14 2015" 275 276See this [list](#cmake-visual-studio-generators) of other possible generators 277for Visual Studio. 278 279When generating the project files, the absolute path to a Vulkan-Headers 280install directory must be provided. This can be done by setting the 281`VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the 282`VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In 283either case, the variable should point to the installation directory of a 284Vulkan-Headers repository built with the install target. 285 286When generating the project files, the absolute path to a glslang install 287directory must be provided. This can be done by setting the 288`GLSLANG_INSTALL_DIR` environment variable or by setting the 289`GLSLANG_INSTALL_DIR` CMake variable with the `-D` CMake option. In either 290case, the variable should point to the installation directory of a glslang 291repository built with the install target. 292 293The above steps create a Windows solution file named 294`Vulkan-ValidationLayers.sln` in the build directory. 295 296At this point, you can build the solution from the command line or open the 297generated solution with Visual Studio. 298 299#### Build the Solution From the Command Line 300 301While still in the build directory: 302 303 cmake --build . 304 305to build the Debug configuration (the default), or: 306 307 cmake --build . --config Release 308 309to make a Release build. 310 311#### Build the Solution With Visual Studio 312 313Launch Visual Studio and open the "Vulkan-ValidationLayers.sln" solution file 314in the build folder. You may select "Debug" or "Release" from the Solution 315Configurations drop-down list. Start a build by selecting the Build->Build 316Solution menu item. 317 318#### Windows Install Target 319 320The CMake project also generates an "install" target that you can use to copy 321the primary build artifacts to a specific location using a "bin, include, lib" 322style directory structure. This may be useful for collecting the artifacts and 323providing them to another project that is dependent on them. 324 325The default location is `$CMAKE_BINARY_DIR\install`, but can be changed with 326the `CMAKE_INSTALL_PREFIX` variable when first generating the project build 327files with CMake. 328 329You can build the install target from the command line with: 330 331 cmake --build . --config Release --target install 332 333or build the `INSTALL` target from the Visual Studio solution explorer. 334 335#### Using a Loader Built from a Repository 336 337If you do need to build and use your own loader, build the Vulkan-Loader 338repository with the install target and modify your CMake invocation to add the 339location of the loader's install directory: 340 341 cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \ 342 -DVULKAN_LOADER_INSTALL_DIR=absolute_path_to_install_dir \ 343 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir .. 344 345### Windows Tests and Demos 346 347After making any changes to the repository, you should perform some quick 348sanity tests, including the run_all_tests Powershell script. In addition, 349running sample applications such as the 350[vkcube demo](https://www.github.com/KhronosGroup/Vulkan-Tools.git) 351with validation enabled is advised. 352 353To run the validation test script, open a Powershell Console, change to the 354build/tests directory, and run: 355 356For Release builds: 357 358 .\run_all_tests.ps1 359 360For Debug builds: 361 362 .\run_all_tests.ps1 -Debug 363 364This script will run the following tests: 365 366- `vk_layer_validation_tests`: 367 Test Vulkan validation layers 368 369### Windows Notes 370 371#### CMake Visual Studio Generators 372 373The chosen generator should match one of the Visual Studio versions that you 374have installed. Generator strings that correspond to versions of Visual Studio 375include: 376 377| Build Platform | 64-bit Generator | 32-bit Generator | 378|------------------------------|-------------------------------|-------------------------| 379| Microsoft Visual Studio 2013 | "Visual Studio 12 2013 Win64" | "Visual Studio 12 2013" | 380| Microsoft Visual Studio 2015 | "Visual Studio 14 2015 Win64" | "Visual Studio 14 2015" | 381| Microsoft Visual Studio 2017 | "Visual Studio 15 2017 Win64" | "Visual Studio 15 2017" | 382 383#### Using The Vulkan Loader Library in this Repository on Windows 384 385Vulkan programs must be able to find and use the Vulkan loader 386(`vulkan-1.dll`) library as well as any other libraries the program requires. 387One convenient way to do this is to copy the required libraries into the same 388directory as the program. If you provided a loader repository location via the 389`VULKAN_LOADER_INSTALL_DIR` variable, the projects in this solution copy the 390Vulkan loader library and the "googletest" libraries to the 391`build\tests\Debug` or the `build\tests\Release` directory, which is where the 392test executables are found, depending on what configuration you built. (The 393layer validation tests use the "googletest" testing framework.) 394 395## Building On Linux 396 397### Linux Build Requirements 398 399This repository has been built and tested on the two most recent Ubuntu LTS 400versions. Currently, the oldest supported version is Ubuntu 14.04, meaning 401that the minimum supported compiler versions are GCC 4.8.2 and Clang 3.4, 402although earlier versions may work. It should be straightforward to adapt this 403repository to other Linux distributions. 404 405#### Required Package List 406 407 sudo apt-get install git cmake build-essential libx11-xcb-dev \ 408 libxkbcommon-dev libwayland-dev libxrandr-dev \ 409 libegl1-mesa-dev 410 411### Linux Build 412 413The general approach is to run CMake to generate make files. Then either run 414CMake with the `--build` option or `make` to build from the command line. 415 416#### Linux Quick Start 417 418 cd Vulkan-ValidationLayers 419 mkdir build 420 cd build 421 cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \ 422 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir .. 423 make 424 425See below for the details. 426 427#### Use CMake to Create the Make Files 428 429Change your current directory to the top of the cloned repository directory, 430create a build directory and generate the make files. 431 432 cd Vulkan-ValidationLayers 433 mkdir build 434 cd build 435 cmake -DCMAKE_BUILD_TYPE=Debug \ 436 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \ 437 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir \ 438 -DCMAKE_INSTALL_PREFIX=install .. 439 440> Note: The `..` parameter tells `cmake` the location of the top of the 441> repository. If you place your `build` directory someplace else, you'll need 442> to specify the location of the repository top differently. 443 444Use `-DCMAKE_BUILD_TYPE` to specify a Debug or Release build. 445 446When generating the project files, the absolute path to a Vulkan-Headers 447install directory must be provided. This can be done by setting the 448`VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the 449`VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In 450either case, the variable should point to the installation directory of a 451Vulkan-Headers repository built with the install target. 452 453When generating the project files, the absolute path to a glslang install 454directory must be provided. This can be done by setting the 455`GLSLANG_INSTALL_DIR` environment variable or by setting the 456`GLSLANG_INSTALL_DIR` CMake variable with the `-D` CMake option. In either 457case, the variable should point to the installation directory of a glslang 458repository built with the install target. 459 460> Note: For Linux, the default value for `CMAKE_INSTALL_PREFIX` is 461> `/usr/local`, which would be used if you do not specify 462> `CMAKE_INSTALL_PREFIX`. In this case, you may need to use `sudo` to install 463> to system directories later when you run `make install`. 464 465#### Build the Project 466 467You can just run `make` to begin the build. 468 469To speed up the build on a multi-core machine, use the `-j` option for `make` 470to specify the number of cores to use for the build. For example: 471 472 make -j4 473 474You can also use 475 476 cmake --build . 477 478If your build system supports ccache, you can enable that via CMake option `-DUSE_CCACHE=On` 479 480### Linux Notes 481 482#### WSI Support Build Options 483 484By default, the repository components are built with support for the 485Vulkan-defined WSI display servers: Xcb, Xlib, and Wayland. It is recommended 486to build the repository components with support for these display servers to 487maximize their usability across Linux platforms. If it is necessary to build 488these modules without support for one of the display servers, the appropriate 489CMake option of the form `BUILD_WSI_xxx_SUPPORT` can be set to `OFF`. 490 491#### Linux Install to System Directories 492 493Installing the files resulting from your build to the systems directories is 494optional since environment variables can usually be used instead to locate the 495binaries. There are also risks with interfering with binaries installed by 496packages. If you are certain that you would like to install your binaries to 497system directories, you can proceed with these instructions. 498 499Assuming that you've built the code as described above and the current 500directory is still `build`, you can execute: 501 502 sudo make install 503 504This command installs files to `/usr/local` if no `CMAKE_INSTALL_PREFIX` is 505specified when creating the build files with CMake: 506 507- `/usr/local/lib`: Vulkan layers shared objects 508- `/usr/local/share/vulkan/explicit_layer.d`: Layer JSON files 509 510You may need to run `ldconfig` in order to refresh the system loader search 511cache on some Linux systems. 512 513You can further customize the installation location by setting additional 514CMake variables to override their defaults. For example, if you would like to 515install to `/tmp/build` instead of `/usr/local`, on your CMake command line 516specify: 517 518 -DCMAKE_INSTALL_PREFIX=/tmp/build 519 520Then run `make install` as before. The install step places the files in 521`/tmp/build`. This may be useful for collecting the artifacts and providing 522them to another project that is dependent on them. 523 524See the CMake documentation for more details on using these variables to 525further customize your installation. 526 527Also see the `LoaderAndLayerInterface` document in the `loader` folder of the 528Vulkan-Loader repository for more information about loader and layer 529operation. 530 531#### Linux Uninstall 532 533To uninstall the files from the system directories, you can execute: 534 535 sudo make uninstall 536 537#### Linux Tests 538 539To run the **validation test script**, in a terminal change to the build/tests directory and run: 540 541 VK_LAYER_PATH=../layers ./run_all_tests.sh 542 543This script will run the following tests: 544 545- `vk_layer_validation_tests`: Test Vulkan validation layers 546 547#### Linux 32-bit support 548 549Usage of this repository's contents in 32-bit Linux environments is not 550officially supported. However, since this repository is supported on 32-bit 551Windows, these modules should generally work on 32-bit Linux. 552 553Here are some notes for building 32-bit targets on a 64-bit Ubuntu "reference" 554platform: 555 556If not already installed, install the following 32-bit development libraries: 557 558`gcc-multilib g++-multilib libx11-dev:i386` 559 560This list may vary depending on your distribution and which windowing systems 561you are building for. 562 563Set up your environment for building 32-bit targets: 564 565 export ASFLAGS=--32 566 export CFLAGS=-m32 567 export CXXFLAGS=-m32 568 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu 569 570Again, your PKG_CONFIG configuration may be different, depending on your distribution. 571 572Finally, rebuild the repository using `cmake` and `make`, as explained above. 573 574#### Using the new layers 575 576 export VK_LAYER_PATH=<path to your repository root>/build/layers 577 578You can run the `vkcube` or `vulkaninfo` applications from the Vulkan-Tools 579repository to see which driver, loader and layers are being used. 580 581## Building On Android 582 583Install the required tools for Linux and Windows covered above, then add the 584following. 585 586### Android Build Requirements 587 588- Install [Android Studio 2.3](https://developer.android.com/studio/index.html) 589 or later. 590- From the "Welcome to Android Studio" splash screen, add the following 591 components using Configure > SDK Manager: 592 - SDK Platforms > Android 6.0 and newer 593 - SDK Tools > Android SDK Build-Tools 594 - SDK Tools > Android SDK Platform-Tools 595 - SDK Tools > Android SDK Tools 596 - SDK Tools > NDK 597 598#### Add Android specifics to environment 599 600For each of the below, you may need to specify a different build-tools 601version, as Android Studio will roll it forward fairly regularly. 602 603On Linux: 604 605 export ANDROID_SDK_HOME=$HOME/Android/sdk 606 export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk-bundle 607 export PATH=$ANDROID_SDK_HOME:$PATH 608 export PATH=$ANDROID_NDK_HOME:$PATH 609 export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH 610 611On Windows: 612 613 set ANDROID_SDK_HOME=%LOCALAPPDATA%\Android\sdk 614 set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk-bundle 615 set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH% 616 617On OSX: 618 619 export ANDROID_SDK_HOME=$HOME/Library/Android/sdk 620 export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk-bundle 621 export PATH=$ANDROID_NDK_PATH:$PATH 622 export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH 623 624Note: If `jarsigner` is missing from your platform, you can find it in the 625Android Studio install or in your Java installation. If you do not have Java, 626you can get it with something like the following: 627 628 sudo apt-get install openjdk-8-jdk 629 630#### Additional OSX System Requirements 631 632Tested on OSX version 10.13.3 633 634Setup Homebrew and components 635 636- Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed. 637 638 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" 639 640- Ensure Homebrew is at the beginning of your PATH: 641 642 export PATH=/usr/local/bin:$PATH 643 644- Add packages with the following: 645 646 brew install cmake python 647 648### Android Build 649 650There are two options for building the Android layers. Either using the SPIRV 651tools provided as part of the Android NDK, or using upstream sources. To build 652with SPIRV tools from the NDK, remove the build-android/third_party directory 653created by running update_external_sources_android.sh, (or avoid running 654update_external_sources_android.sh). Use the following script to build 655everything in the repository for Android, including validation layers, tests, 656demos, and APK packaging: This script does retrieve and use the upstream SPRIV 657tools. 658 659 cd build-android 660 ./build_all.sh 661 662Resulting validation layer binaries will be in build-android/libs. Test and 663demo APKs can be installed on production devices with: 664 665 ./install_all.sh [-s <serial number>] 666 667Note that there are no equivalent scripts on Windows yet, that work needs to 668be completed. The following per platform commands can be used for layer only 669builds: 670 671#### Linux and OSX 672 673Follow the setup steps for Linux or OSX above, then from your terminal: 674 675 cd build-android 676 ./update_external_sources_android.sh --no-build 677 ./android-generate.sh 678 ndk-build -j4 679 680#### Windows 681 682Follow the setup steps for Windows above, then from Developer Command Prompt 683for VS2013: 684 685 cd build-android 686 update_external_sources_android.bat 687 android-generate.bat 688 ndk-build 689 690### Android Tests and Demos 691 692After making any changes to the repository you should perform some quick 693sanity tests, including the layer validation tests and the vkcube 694demo with validation enabled. 695 696#### Run Layer Validation Tests 697 698Use the following steps to build, install, and run the layer validation tests 699for Android: 700 701 cd build-android 702 ./build_all.sh 703 adb install -r bin/VulkanLayerValidationTests.apk 704 adb shell am start com.example.VulkanLayerValidationTests/android.app.NativeActivity 705 706Alternatively, you can use the test_APK script to install and run the layer 707validation tests: 708 709 test_APK.sh -s <serial number> -p <plaform name> -f <gtest_filter> 710 711## Building on MacOS 712 713### MacOS Build Requirements 714 715Tested on OSX version 10.12.6 716 717Setup Homebrew and components 718 719- Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed. 720 721 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" 722 723- Ensure Homebrew is at the beginning of your PATH: 724 725 export PATH=/usr/local/bin:$PATH 726 727- Add packages with the following (may need refinement) 728 729 brew install cmake python python3 git 730 731### Clone the Repository 732 733Clone the Vulkan-ValidationLayers repository: 734 735 git clone https://github.com/KhronosGroup/Vulkan-ValidationLayers.git 736 737### MacOS build 738 739#### CMake Generators 740 741This repository uses CMake to generate build or project files that are then 742used to build the repository. The CMake generators explicitly supported in 743this repository are: 744 745- Unix Makefiles 746- Xcode 747 748#### Building with the Unix Makefiles Generator 749 750This generator is the default generator, so all that is needed for a debug 751build is: 752 753 mkdir build 754 cd build 755 cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \ 756 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir \ 757 -DCMAKE_BUILD_TYPE=Debug .. 758 make 759 760To speed up the build on a multi-core machine, use the `-j` option for `make` 761to specify the number of cores to use for the build. For example: 762 763 make -j4 764 765#### Building with the Xcode Generator 766 767To create and open an Xcode project: 768 769 mkdir build-xcode 770 cd build-xcode 771 cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \ 772 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir \ 773 -GXcode .. 774 open VULKAN.xcodeproj 775 776Within Xcode, you can select Debug or Release builds in the Build Settings of the project. 777 778#### Using the new layers on MacOS 779 780 export VK_LAYER_PATH=<path to your repository root>/build/layers 781 782You can run the `vulkaninfo` applications from the Vulkan-Tools repository to 783see which driver, loader and layers are being used. 784 785### MacOS Tests 786 787After making any changes to the repository, you should perform the included sanity tests by running 788the run_all_tests shell script. 789 790These test require a manual path to an ICD to run properly on MacOS. 791 792You can use: 793 794- MoltenVK ICD 795- Mock ICD 796 797#### Using MoltenVK ICD 798 799Clone and build the [MoltenVK](https://github.com/KhronosGroup/MoltenVK) repository. 800 801You will have to direct the loader from Vulkan-Loader to the MoltenVK ICD: 802 803 export VK_ICD_FILENAMES=<path to MoltenVK repository>/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json 804 805#### Using Mock ICD 806 807Clone and build the [Vulkan-Tools](https://github.com/KhronosGroup/Vulkan-Tools) repository. 808 809You will have to direct the loader from Vulkan-Loader to the Mock ICD: 810 811 export VK_ICD_FILENAMES=<path to Vulkan-Tools repository>/build/icd/VkICD_mock_icd.json 812 813#### Running the Tests 814 815To run the **validation test script**, in a terminal change to the build/tests directory and run: 816 817 VK_LAYER_PATH=../layers ./run_all_tests.sh 818 819This script will run the following tests: 820 821- `vk_layer_validation_tests`: Test Vulkan validation layers 822 823Further testing and sanity checking can be achieved by running the vkcube and 824vulkaninfo applications in the 825[Vulkan-Tools](https://github.com/KhronosGroup/Vulkan-Tools) 826repository. 827 828Note that MoltenVK is still adding Vulkan features and some tests may fail. 829