Lines Matching +full:build +full:- +full:and +full:- +full:run +full:- +full:tests
1 # Build Instructions
3 Instructions for building this repository on Linux, Windows, Android, and
8 1. [Contributing](#contributing-to-the-repository)
9 1. [Repository Content](#repository-content)
10 1. [Repository Set-Up](#repository-set-up)
11 1. [Windows Build](#building-on-windows)
12 1. [Linux Build](#building-on-linux)
13 1. [Android Build](#building-on-android)
14 1. [MacOS build](#building-on-macos)
19 your contribution in a fork of this repository in your GitHub account and then
25 This repository contains the source code necessary to build the Vulkan
26 validation layers and their tests.
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)
40 ## Repository Set-Up
44 This repository does not contain a Vulkan-capable driver. You will need to
45 obtain and install a Vulkan driver from your graphics hardware vendor or from
46 some other suitable source if you intend to run Vulkan applications.
52 git clone https://github.com/KhronosGroup/Vulkan-ValidationLayers.git
59 1. CMake or Environment variable overrides (e.g., -DVULKAN_HEADERS_INSTALL_DIR)
61 1. System-installed packages, mostly applicable on Linux
64 resolved with the "install directory" override and are listed below. The
68 #### Vulkan-Headers
71 [Vulkan Headers repository](https://github.com/KhronosGroup/Vulkan-Headers).
72 You must clone the headers repository and build its `install` target before
73 building this repository. The Vulkan-Headers repository is required because it
74 contains the Vulkan API definition files (registry) that are required to build
76 directory and pass it on the CMake command line for building this repository,
84 required to build the validation layers. You must clone the glslang repository
85 and build its `install` target. Follow the build instructions in the glslang
87 file. Ensure that the `update_glslang_sources.py` script has been run as part
89 and pass it on the CMake command line for building this repository, as
94 The validation layer tests depend on the
96 framework and do not build unless this framework is downloaded into the
100 Vulkan-ValidationLayers repository and run:
104 git checkout tags/release-1.8.1
106 before configuring your build with CMake.
108 If you do not need the tests, there is no need to download this
111 #### Vulkan-Loader
113 The validation layer tests depend on the Vulkan loader when they execute and
114 so a loader is needed only if the tests are built and run.
119 If a loader is not available from any of these methods and/or it is important
120 to use a loader built from a repository, then you must build the
121 [Vulkan-Loader repository](https://github.com/KhronosGroup/Vulkan-Loader.git)
122 with its install target. Take note of its install directory location and pass
125 If you do not intend to run the tests, you do not need a Vulkan loader.
127 ### Build and Install Directories
129 A common convention is to place the build directory in the top directory of
130 the repository with a name of `build` and place the install directory as a
131 child of the build directory with the name `install`. The remainder of these
133 directories and place them in any location.
135 ### Building Dependent Repositories with Known-Good Revisions
138 gather and build the dependent repositories mentioned above. This script uses
142 as a quick-start tool for common use cases and default configurations.
146 git clone git@github.com:KhronosGroup/Vulkan-ValidationLayers.git
147 cd Vulkan-ValidationLayers
148 mkdir build
149 cd build
151 For 64-bit Linux and MacOS, continue with:
154 cmake -C helper.cmake ..
155 cmake --build .
157 For 64-bit Windows, continue with:
159 ..\scripts\update_deps.py --arch x64
160 cmake -A x64 -C helper.cmake ..
161 cmake --build .
163 For 32-bit Windows, continue with:
165 ..\scripts\update_deps.py --arch Win32
166 cmake -A Win32 -C helper.cmake ..
167 cmake --build .
169 Please see the more detailed build information later in this file if you have
170 specific requirements for configuring and building these components.
174 - You may need to adjust some of the CMake options based on your platform. See
175 the platform-specific sections later in this document.
176 - The `update_deps.py` script fetches and builds the dependent repositories in
178 the `build` directory.
179 - The `build` directory is also being used to build this
180 (Vulkan-ValidationLayers) repository. But there shouldn't be any conflicts
181 inside the `build` directory between the dependent repositories and the
182 build files for this repository.
183 - The `--dir` option for `update_deps.py` can be used to relocate the
186 - The `update_deps.py` script generates a file named `helper.cmake` and places
187 it in the same directory as the dependent repositories (`build` in this
190 repositories. You can use this file with the `cmake -C` option to set these
191 variables when you generate your build files with CMake. This lets you avoid
193 - If using "MINGW" (Git For Windows), you may wish to run
195 "print" output until the end and to retain the ability to interrupt script
197 - Please use `update_deps.py --help` to list additional options and read the
210 the invocation of `scripts/generate_source.py` from the build directory:
212 cmake --build . --target VulkanVL_generated_source
214 ### Build Options
216 When generating native platform build files through CMake, several options can
217 be specified to customize the build. Some of the options are binary on/off
222 | ------ | -------- | ------- | ----------- |
225 | BUILD_TESTS | All | `???` | Controls whether or not the validation layer tests are built. The def…
226 | INSTALL_TESTS | All | `OFF` | Controls whether or not the validation layer tests are installed. T…
227 | BUILD_WSI_XCB_SUPPORT | Linux | `ON` | Build the components with XCB support. |
228 | BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the components with Xlib support. |
229 | BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the components with Wayland support. |
235 | ------ | -------- | ------- | ----------- |
238 These variables should be set using the `-D` option when invoking CMake to
245 - Windows
246 - Any Personal Computer version supported by Microsoft
247 - Microsoft [Visual Studio](https://www.visualstudio.com/)
248 - Versions
249 - [2015](https://www.visualstudio.com/vs/older-downloads/)
250 - [2017](https://www.visualstudio.com/vs/downloads/)
251 - The Community Edition of each of the above versions is sufficient, as
253 - [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-win64-x64.zip) is recommended.
254 - Use the installer option to add CMake to the system PATH
255 - Git Client Support
256 - [Git for Windows](http://git-scm.com/download/win) is a popular solution
258 - Some IDEs (e.g., [Visual Studio](https://www.visualstudio.com/),
262 ### Windows Build - Microsoft Visual Studio
264 The general approach is to run CMake to generate the Visual Studio project
265 files. Then either run CMake with the `--build` option to build from the
266 command line or use the Visual Studio IDE to open the generated solution and
271 cd Vulkan-ValidationLayers
272 mkdir build
273 cd build
274 cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
275 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir ..
276 cmake --build .
278 The above commands instruct CMake to find and use the default Visual Studio
279 installation to generate a Visual Studio solution and projects for the x64
288 create a build directory and generate the Visual Studio project files:
290 cd Vulkan-ValidationLayers
291 mkdir build
292 cd build
293 cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
294 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir ..
297 > repository. If you place your build directory someplace else, you'll need to
300 The `-A` option is used to select either the "Win32" or "x64" architecture.
305 64-bit: -G "Visual Studio 14 2015 Win64"
306 32-bit: -G "Visual Studio 14 2015"
308 See this [list](#cmake-visual-studio-generators) of other possible generators
311 When generating the project files, the absolute path to a Vulkan-Headers
314 `VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In
316 Vulkan-Headers repository built with the install target.
321 `GLSLANG_INSTALL_DIR` CMake variable with the `-D` CMake option. In either
326 `Vulkan-ValidationLayers.sln` in the build directory.
328 At this point, you can build the solution from the command line or open the
331 #### Build the Solution From the Command Line
333 While still in the build directory:
335 cmake --build .
337 to build the Debug configuration (the default), or:
339 cmake --build . --config Release
341 to make a Release build.
343 #### Build the Solution With Visual Studio
345 Launch Visual Studio and open the "Vulkan-ValidationLayers.sln" solution file
346 in the build folder. You may select "Debug" or "Release" from the Solution
347 Configurations drop-down list. Start a build by selecting the Build->Build
353 the primary build artifacts to a specific location using a "bin, include, lib"
354 style directory structure. This may be useful for collecting the artifacts and
358 the `CMAKE_INSTALL_PREFIX` variable when first generating the project build
361 You can build the install target from the command line with:
363 cmake --build . --config Release --target install
365 or build the `INSTALL` target from the Visual Studio solution explorer.
369 If you do need to build and use your own loader, build the Vulkan-Loader
370 repository with the install target and modify your CMake invocation to add the
373 cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
374 -DVULKAN_LOADER_INSTALL_DIR=absolute_path_to_install_dir \
375 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir ..
377 ### Windows Tests and Demos
380 sanity tests, including the run_all_tests Powershell script. In addition,
382 [vkcube demo](https://www.github.com/KhronosGroup/Vulkan-Tools.git)
385 To run the validation test script, open a Powershell Console, change to the
386 build/tests directory, and run:
394 .\run_all_tests.ps1 -Debug
396 This script will run the following tests:
398 - `vk_layer_validation_tests`:
409 | Build Platform | 64-bit Generator | 32-bit Generator |
410 |------------------------------|-------------------------------|-------------------------|
416 Vulkan programs must be able to find and use the Vulkan loader
417 (`vulkan-1.dll`) library as well as any other libraries the program requires.
421 Vulkan loader library and the "googletest" libraries to the
422 `build\tests\Debug` or the `build\tests\Release` directory, which is where the
424 layer validation tests use the "googletest" testing framework.)
428 ### Linux Build Requirements
430 This repository has been built and tested on the two most recent Ubuntu LTS
436 [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Linux-x86_64.tar.gz) is recommended.
440 sudo apt-get install git build-essential libx11-xcb-dev \
441 libxkbcommon-dev libwayland-dev libxrandr-dev \
442 libegl1-mesa-dev
444 ### Linux Build
446 The general approach is to run CMake to generate make files. Then either run
447 CMake with the `--build` option or `make` to build from the command line.
451 cd Vulkan-ValidationLayers
452 mkdir build
453 cd build
454 cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
455 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir ..
463 create a build directory and generate the make files.
465 cd Vulkan-ValidationLayers
466 mkdir build
467 cd build
468 cmake -DCMAKE_BUILD_TYPE=Debug \
469 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
470 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir \
471 -DCMAKE_INSTALL_PREFIX=install ..
474 > repository. If you place your `build` directory someplace else, you'll need
477 Use `-DCMAKE_BUILD_TYPE` to specify a Debug or Release build.
479 When generating the project files, the absolute path to a Vulkan-Headers
482 `VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In
484 Vulkan-Headers repository built with the install target.
489 `GLSLANG_INSTALL_DIR` CMake variable with the `-D` CMake option. In either
496 > to system directories later when you run `make install`.
498 #### Build the Project argument
500 You can just run `make` to begin the build.
502 To speed up the build on a multi-core machine, use the `-j` option for `make`
503 to specify the number of cores to use for the build. For example:
505 make -j4
509 cmake --build .
511 If your build system supports ccache, you can enable that via CMake option `-DUSE_CCACHE=On`
515 #### WSI Support Build Options
518 Vulkan-defined WSI display servers: Xcb, Xlib, and Wayland. It is recommended
519 to build the repository components with support for these display servers to
520 maximize their usability across Linux platforms. If it is necessary to build
526 Installing the files resulting from your build to the systems directories is
532 Assuming that you've built the code as described above and the current
533 directory is still `build`, you can execute:
538 specified when creating the build files with CMake:
540 - `/usr/local/lib`: Vulkan layers shared objects
541 - `/usr/local/share/vulkan/explicit_layer.d`: Layer JSON files
543 You may need to run `ldconfig` in order to refresh the system loader search
548 install to `/tmp/build` instead of `/usr/local`, on your CMake command line
551 -DCMAKE_INSTALL_PREFIX=/tmp/build
553 Then run `make install` as before. The install step places the files in
554 `/tmp/build`. This may be useful for collecting the artifacts and providing
561 Vulkan-Loader repository for more information about loader and layer
570 #### Linux Tests
572 To run the **validation test script**, in a terminal change to the build/tests directory and run:
576 This script will run the following tests:
578 - `vk_layer_validation_tests`: Test Vulkan validation layers
580 #### Linux 32-bit support
582 Usage of this repository's contents in 32-bit Linux environments is not
583 officially supported. However, since this repository is supported on 32-bit
584 Windows, these modules should generally work on 32-bit Linux.
586 Here are some notes for building 32-bit targets on a 64-bit Ubuntu "reference"
589 If not already installed, install the following 32-bit development libraries:
591 `gcc-multilib g++-multilib libx11-dev:i386`
593 This list may vary depending on your distribution and which windowing systems
596 Set up your environment for building 32-bit targets:
598 export ASFLAGS=--32
599 export CFLAGS=-m32
600 export CXXFLAGS=-m32
601 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu
605 Finally, rebuild the repository using `cmake` and `make`, as explained above.
609 export VK_LAYER_PATH=<path to your repository root>/build/layers
611 You can run the `vkcube` or `vulkaninfo` applications from the Vulkan-Tools
612 repository to see which driver, loader and layers are being used.
616 Install the required tools for Linux and Windows covered above, then add the
619 ### Android Build Requirements
624 - Install [Android Studio 2.3](https://developer.android.com/studio/index.html)
626 - From the "Welcome to Android Studio" splash screen, add the following
628 - SDK Platforms > Android 8.0.0 and newer
629 - SDK Tools > Android SDK Build-Tools
630 - SDK Tools > Android SDK Platform-Tools
631 - SDK Tools > Android SDK Tools
632 - SDK Tools > NDK
636 For each of the below, you may need to specify a different build-tools
642 export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk-bundle
645 export PATH=$ANDROID_SDK_HOME/build-tools/26.0.3:$PATH
650 set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk-bundle
651 set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH%
656 export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk-bundle
658 export PATH=$ANDROID_SDK_HOME/build-tools/26.0.3:$PATH
664 sudo apt-get install openjdk-8-jdk
670 Setup Homebrew and components
672 - Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
674 … /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
676 - Ensure Homebrew is at the beginning of your PATH:
680 - Add packages with the following:
684 ### Android Build
687 tools provided as part of the Android NDK, or using upstream sources. To build
688 with SPIRV tools from the NDK, remove the build-android/third_party directory
690 update_external_sources_android.sh). Use the following script to build
691 everything in the repository for Android, including validation layers, tests,
692 demos, and APK packaging: This script does retrieve and use the upstream SPRIV
695 cd build-android
698 Resulting validation layer binaries will be in build-android/libs. Test and
701 ./install_all.sh [-s <serial number>]
707 #### Linux and OSX
711 cd build-android
712 ./update_external_sources_android.sh --no-build
713 ndk-build -j4
720 cd build-android
722 ndk-build
724 ### Android Tests and Demos
727 sanity tests, including the layer validation tests and the vkcube
730 #### Run Layer Validation Tests
732 Use the following steps to build, install, and run the layer validation tests
735 cd build-android
737 adb install -r bin/VulkanLayerValidationTests.apk
740 Alternatively, you can use the test_APK script to install and run the layer
741 validation tests:
743 test_APK.sh -s <serial number> -p <plaform name> -f <gtest_filter>
747 ### MacOS Build Requirements
751 [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Darwin-x86_64.tar.gz) is recommended.
753 Setup Homebrew and components
755 - Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
757 … /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
759 - Ensure Homebrew is at the beginning of your PATH:
763 - Add packages with the following (may need refinement)
769 Clone the Vulkan-ValidationLayers repository:
771 git clone https://github.com/KhronosGroup/Vulkan-ValidationLayers.git
773 ### MacOS build
777 This repository uses CMake to generate build or project files that are then
778 used to build the repository. The CMake generators explicitly supported in
781 - Unix Makefiles
782 - Xcode
787 build is:
789 mkdir build
790 cd build
791 cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
792 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir \
793 -DCMAKE_BUILD_TYPE=Debug ..
796 To speed up the build on a multi-core machine, use the `-j` option for `make`
797 to specify the number of cores to use for the build. For example:
799 make -j4
803 To create and open an Xcode project:
805 mkdir build-xcode
806 cd build-xcode
807 cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
808 -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir \
809 -GXcode ..
812 Within Xcode, you can select Debug or Release builds in the Build Settings of the project.
816 export VK_LAYER_PATH=<path to your repository root>/build/layers
818 You can run the `vulkaninfo` applications from the Vulkan-Tools repository to
819 see which driver, loader and layers are being used.
821 ### MacOS Tests
823 After making any changes to the repository, you should perform the included sanity tests by running
826 These test require a manual path to an ICD to run properly on MacOS.
830 - MoltenVK ICD
831 - Mock ICD
835 Clone and build the [MoltenVK](https://github.com/KhronosGroup/MoltenVK) repository.
837 You will have to direct the loader from Vulkan-Loader to the MoltenVK ICD:
843 Clone and build the [Vulkan-Tools](https://github.com/KhronosGroup/Vulkan-Tools) repository.
845 You will have to direct the loader from Vulkan-Loader to the Mock ICD:
847 export VK_ICD_FILENAMES=<path to Vulkan-Tools repository>/build/icd/VkICD_mock_icd.json
849 #### Running the Tests argument
851 To run the **validation test script**, in a terminal change to the build/tests directory and run:
855 This script will run the following tests:
857 - `vk_layer_validation_tests`: Test Vulkan validation layers
859 Further testing and sanity checking can be achieved by running the vkcube and
861 [Vulkan-Tools](https://github.com/KhronosGroup/Vulkan-Tools)
864 Note that MoltenVK is still adding Vulkan features and some tests may fail.