# Build Instructions
-This document contains the instructions for building this repository on Linux and Windows.
-This repository does not contain a Vulkan-capable driver.
-Before proceeding, it is strongly recommended that you obtain a Vulkan driver from your graphics hardware vendor
-and install it.
+Instructions for building this repository on Linux, Windows, Android, and MacOS.
-Note: The sample Vulkan Intel driver for Linux (ICD) is being deprecated in favor of other driver options from Intel.
-This driver has been moved to the [VulkanTools repo](https://github.com/LunarG/VulkanTools).
-Further instructions regarding this ICD are available there.
+## Index
-## Git the Bits
+1. [Contributing](#contributing-to-the-repository)
+1. [Repository Content](#repository-content)
+1. [Repository Set-Up](#repository-set-up)
+1. [Windows Build](#building-on-windows)
+1. [Linux Build](#building-on-linux)
+1. [Android Build](#building-on-android)
+1. [MacOS build](#building-on-macos)
+
+## Contributing to the Repository
+
+If you intend to contribute, the preferred work flow is for you to develop
+your contribution in a fork of this repository in your GitHub account and then
+submit a pull request. Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file
+in this repository for more details.
+
+## Repository Content
+
+This repository contains the source code necessary to build the following components:
+
+- vulkaninfo
+- vkcube and vkcubepp demos
+- mock ICD
+
+### Installed Files
+
+The `install` target installs the following files under the directory
+indicated by *install_dir*:
+
+- *install_dir*`/bin` : The vulkaninfo, vkcube and vkcubepp executables
+- *install_dir*`/lib` : The mock ICD library and JSON (Windows) (If INSTALL_ICD=ON)
+- *install_dir*`/share/vulkan/icd.d` : mock ICD JSON (Linux/MacOS) (If INSTALL_ICD=ON)
+
+The `uninstall` target can be used to remove the above files from the install
+directory.
+
+## Repository Set-Up
+
+### Display Drivers
+
+This repository does not contain a Vulkan-capable driver. You will need to
+obtain and install a Vulkan driver from your graphics hardware vendor or from
+some other suitable source if you intend to run Vulkan applications.
+
+### Download the Repository
To create your local git repository:
-```
-git clone https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers
-```
-If you intend to contribute, the preferred work flow is for you to develop your contribution
-in a fork of this repo in your GitHub account and then submit a pull request.
-Please see the CONTRIBUTING.md file in this respository for more details.
+ git clone https://github.com/KhronosGroup/Vulkan-Tools.git
-## Linux Build
+### Repository Dependencies
-The build process uses CMake to generate makefiles for this project.
-The build generates the loader, layers, and tests.
+This repository attempts to resolve some of its dependencies by using
+components found from the following places, in this order:
-This repo has been built and tested on Ubuntu 14.04.3 LTS, 14.10, 15.04 and 15.10.
-It should be straightforward to use it on other Linux distros.
+1. CMake or Environment variable overrides (e.g., -DVULKAN_HEADERS_INSTALL_DIR)
+1. LunarG Vulkan SDK, located by the `VULKAN_SDK` environment variable
+1. System-installed packages, mostly applicable on Linux
-These packages are needed to build this repository:
-```
-sudo apt-get install git cmake build-essential bison libxcb1-dev
+Dependencies that cannot be resolved by the SDK or installed packages must be
+resolved with the "install directory" override and are listed below. The
+"install directory" override can also be used to force the use of a specific
+version of that dependency.
+
+#### Vulkan-Headers
+
+This repository has a required dependency on the
+[Vulkan Headers repository](https://github.com/KhronosGroup/Vulkan-Headers).
+You must clone the headers repository and build its `install` target before
+building this repository. The Vulkan-Headers repository is required because it
+contains the Vulkan API definition files (registry) that are required to build
+the mock ICD. You must also take note of the headers install directory and
+pass it on the CMake command line for building this repository, as described
+below.
+
+Note that this dependency can be ignored if not building the mock ICD
+(CMake option: `-DBUILD_ICD=OFF`).
+
+#### glslang
+
+This repository has a required dependency on the `glslangValidator` (shader
+compiler) for compiling the shader programs for the vkcube demos.
+
+The CMake code in this repository downloads release binaries of glslang if a
+build glslang repository is not provided. The glslangValidator is obtained
+from this set of release binaries.
+
+If you don't wish the CMake code to download these binaries, then you must
+clone the [glslang repository](https://github.com/KhronosGroup/glslang) and
+build its `install` target. Follow the build instructions in the glslang
+[README.md](https://github.com/KhronosGroup/glslang/blob/main/README.md)
+file. Ensure that the `update_glslang_sources.py` script has been run as part
+of building glslang. You must also take note of the glslang install directory
+and pass it on the CMake command line for building this repository, as
+described below.
+
+Note that this dependency can be ignored if not building the vkcube demo
+(CMake option: `-DBUILD_CUBE=OFF`).
+
+### Build and Install Directories
+
+A common convention is to place the build directory in the top directory of
+the repository with a name of `build` and place the install directory as a
+child of the build directory with the name `install`. The remainder of these
+instructions follow this convention, although you can use any name for these
+directories and place them in any location.
+
+### Building Dependent Repositories with Known-Good Revisions
+
+There is a Python utility script, `scripts/update_deps.py`, that you can use to
+gather and build the dependent repositories mentioned above. This script uses
+information stored in the `scripts/known_good.json` file to check out dependent
+repository revisions that are known to be compatible with the revision of this
+repository that you currently have checked out. As such, this script is useful
+as a quick-start tool for common use cases and default configurations.
+
+For all platforms, start with:
+
+ git clone git@github.com:KhronosGroup/Vulkan-Tools.git
+ cd Vulkan-Tools
+ mkdir build
+ cd build
+
+For 64-bit Linux and MacOS, continue with:
+
+ ../scripts/update_deps.py
+ cmake -C helper.cmake ..
+ cmake --build .
+
+For 64-bit Windows, continue with:
+
+ ..\scripts\update_deps.py --arch x64
+ cmake -A x64 -C helper.cmake ..
+ cmake --build .
+
+For 32-bit Windows, continue with:
+
+ ..\scripts\update_deps.py --arch Win32
+ cmake -A Win32 -C helper.cmake ..
+ cmake --build .
+
+Please see the more detailed build information later in this file if you have
+specific requirements for configuring and building these components.
+
+#### Notes
+
+- You may need to adjust some of the CMake options based on your platform. See
+ the platform-specific sections later in this document.
+- The `update_deps.py` script fetches and builds the dependent repositories in
+ the current directory when it is invoked. In this case, they are built in
+ the `build` directory.
+- The `build` directory is also being used to build this
+ (Vulkan-Tools) repository. But there shouldn't be any conflicts
+ inside the `build` directory between the dependent repositories and the
+ build files for this repository.
+- The `--dir` option for `update_deps.py` can be used to relocate the
+ dependent repositories to another arbitrary directory using an absolute or
+ relative path.
+- The `update_deps.py` script generates a file named `helper.cmake` and places
+ it in the same directory as the dependent repositories (`build` in this
+ case). This file contains CMake commands to set the CMake `*_INSTALL_DIR`
+ variables that are used to point to the install artifacts of the dependent
+ repositories. You can use this file with the `cmake -C` option to set these
+ variables when you generate your build files with CMake. This lets you avoid
+ entering several `*_INSTALL_DIR` variable settings on the CMake command line.
+- If using "MINGW" (Git For Windows), you may wish to run
+ `winpty update_deps.py` in order to avoid buffering all of the script's
+ "print" output until the end and to retain the ability to interrupt script
+ execution.
+- Please use `update_deps.py --help` to list additional options and read the
+ internal documentation in `update_deps.py` for further information.
+
+### Generated source code
+
+This repository contains generated source code in the `icd/generated`
+directory which is not intended to be modified directly. Instead, changes should be
+made to the corresponding generator in the `scripts` directory. The source files can
+then be regenerated using `scripts/generate_source.py`:
+
+ python3 scripts/generate_source.py PATH_TO_VULKAN_HEADERS_REGISTRY_DIR
+
+A helper CMake target `VulkanTools_generated_source` is also provided to simplify
+the invocation of `scripts/generate_source.py` from the build directory:
+
+ cmake --build . --target VulkanTools_generated_source
+
+### Build Options
+
+When generating native platform build files through CMake, several options can
+be specified to customize the build. Some of the options are binary on/off
+options, while others take a string as input. The following is a table of all
+on/off options currently supported by this repository:
+
+| Option | Platform | Default | Description |
+| ------ | -------- | ------- | ----------- |
+| BUILD_CUBE | All | `ON` | Controls whether or not the vkcube demo is built. |
+| BUILD_VULKANINFO | All | `ON` | Controls whether or not the vulkaninfo utility is built. |
+| BUILD_ICD | All | `ON` | Controls whether or not the mock ICD is built. |
+| INSTALL_ICD | All | `OFF` | Controls whether or not the mock ICD is installed as part of the install target. |
+| BUILD_WSI_XCB_SUPPORT | Linux | `ON` | Build the components with XCB support. |
+| BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the components with Xlib support. |
+| BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the components with Wayland support. |
+| BUILD_WSI_DIRECTFB_SUPPORT | Linux | `OFF` | Build the components with DirectFB support. |
+
+The following is a table of all string options currently supported by this repository:
+
+| Option | Platform | Default | Description |
+| ------ | -------- | ------- | ----------- |
+| VULKANINFO_BUILD_DLL_VERSIONINFO | Windows | `""` | Set the Windows specific version information for Vulkaninfo. Format is "major.minor.patch.build". |
+
+These variables should be set using the `-D` option when invoking CMake to
+generate the native platform files.
+
+### CCACHE
+
+There are 2 methods to enable CCACHE:
+
+1.) Set environment variables
+
+```bash
+# Requires CMake 3.17 (https://cmake.org/cmake/help/latest/envvar/CMAKE_LANG_COMPILER_LAUNCHER.html)
+export CMAKE_CXX_COMPILER_LAUNCHER=/usr/bin/ccache
+export CMAKE_C_COMPILER_LAUNCHER=/usr/bin/ccache
```
-Example debug build:
+2.) Pass in cache variables
+
+```
+cmake ... -D CMAKE_CXX_COMPILER_LAUNCHER=/usr/bin/ccache -D CMAKE_C_COMPILER_LAUNCHER=/usr/bin/ccache
```
-cd Vulkan-LoaderAndValidationLayers # cd to the root of the cloned git repository
-./update_external_sources.sh # Fetches and builds glslang and spirv-tools
-cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug
-cd dbuild
-make
+
+### EXPORT_COMPILE_COMMANDS
+
+There are 2 methods to enable exporting compile commands:
+
+1.) Set environment variables
+
+```bash
+# Requires CMake 3.17 (https://cmake.org/cmake/help/latest/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.html)
+export CMAKE_EXPORT_COMPILE_COMMANDS=ON
```
-If you have installed a Vulkan driver obtained from your graphics hardware vendor, the install process should
-have configured the driver so that the Vulkan loader can find and load it.
+2.) Pass in cache variables
-If you want to use the loader and layers that you have just built:
```
-export LD_LIBRARY_PATH=<path to your repository root>/dbuild/loader
-export VK_LAYER_PATH=<path to your repository root>/dbuild/layers
+cmake ... -D CMAKE_EXPORT_COMPILE_COMMANDS=ON
```
-Note that if you have installed the [LunarG Vulkan SDK](https://vulkan.lunarg.com),
-you will also have the SDK version of the loader and layers installed in your default system libraries.
-You can run the `vulkaninfo` application to see which driver, loader and layers are being used.
+NOTE: Modern tools will generally enable exporting compile commands for you (e.g. VSCode).
+Also `CMAKE_EXPORT_COMPILE_COMMANDS` is implemented only by Makefile and Ninja generators. For other generators, this option is ignored.
-The `LoaderAndLayerInterface` document in the `loader` folder in this repository is a specification that
-describes both how ICDs and layers should be properly
-packaged, and how developers can point to ICDs and layers within their builds.
+## Building On Windows
-## Validation Test
+### Windows Development Environment Requirements
-The test executables can be found in the dbuild/tests directory.
-Some of the tests that are available:
-- vk_layer_validation_tests: Test Vulkan layers.
+- Windows
+ - Any Personal Computer version supported by Microsoft
+- Microsoft [Visual Studio](https://www.visualstudio.com/)
+ - Versions
+ - [2013 (update 4)](https://www.visualstudio.com/vs/older-downloads/)
+ - [2015](https://www.visualstudio.com/vs/older-downloads/)
+ - [2017](https://www.visualstudio.com/vs/downloads/)
+ - The Community Edition of each of the above versions is sufficient, as
+ well as any more capable edition.
+- [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-win64-x64.zip) is recommended.
+ - Use the installer option to add CMake to the system PATH
+- Git Client Support
+ - [Git for Windows](http://git-scm.com/download/win) is a popular solution
+ for Windows
+ - Some IDEs (e.g., [Visual Studio](https://www.visualstudio.com/),
+ [GitHub Desktop](https://desktop.github.com/)) have integrated
+ Git client support
-There are also a few shell and Python scripts that run test collections (eg,
-`run_all_tests.sh`).
+### Windows Build - Microsoft Visual Studio
-## Linux Demos
+The general approach is to run CMake to generate the Visual Studio project
+files. Then either run CMake with the `--build` option to build from the
+command line or use the Visual Studio IDE to open the generated solution and
+work with the solution interactively.
-Some demos that can be found in the dbuild/demos directory are:
-- vulkaninfo: report GPU properties
-- tri: a textured triangle (which is animated to demonstrate Z-clipping)
-- cube: a textured spinning cube
-- smoke/smoke: A "smoke" test using a more complex Vulkan demo
+#### Windows Quick Start
-## Windows System Requirements
+ cd Vulkan-Tools
+ mkdir build
+ cd build
+ cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir
+ cmake --build .
-Windows 7+ with additional required software packages:
+The above commands instruct CMake to find and use the default Visual Studio
+installation to generate a Visual Studio solution and projects for the x64
+architecture. The second CMake command builds the Debug (default)
+configuration of the solution.
-- Microsoft Visual Studio 2013 Professional. Note: it is possible that lesser/older versions may work, but that has not been tested.
-- CMake (from http://www.cmake.org/download/). Notes:
- - Tell the installer to "Add CMake to the system PATH" environment variable.
-- Python 3 (from https://www.python.org/downloads). Notes:
- - Select to install the optional sub-package to add Python to the system PATH environment variable.
- - Ensure the pip module is installed (it should be by default)
- - Need python3.3 or later to get the Windows py.exe launcher that is used to get python3 rather than python2 if both are installed on Windows
- - 32 bit python works
-- Git (from http://git-scm.com/download/win).
- - Note: If you use Cygwin, you can normally use Cygwin's "git.exe". However, in order to use the "update_external_sources.bat" script, you must have this version.
- - Tell the installer to allow it to be used for "Developer Prompt" as well as "Git Bash".
- - Tell the installer to treat line endings "as is" (i.e. both DOS and Unix-style line endings).
- - Install each a 32-bit and a 64-bit version, as the 64-bit installer does not install the 32-bit libraries and tools.
-- glslang is required for demos and tests.
- - You can download and configure it (in a peer directory) here: https://github.com/KhronosGroup/glslang/blob/master/README.md
- - A windows batch file has been included that will pull and build the correct version. Run it from Developer Command Prompt for VS2013 like so:
- - update_external_sources.bat --build-glslang
+See below for the details.
-Optional software packages:
+#### Use `CMake` to Create the Visual Studio Project Files
-- Cygwin (from https://www.cygwin.com/). Notes:
- - Cygwin provides some Linux-like tools, which are valuable for obtaining the source code, and running CMake.
- Especially valuable are the BASH shell and git packages.
- - If you don't want to use Cygwin, there are other shells and environments that can be used.
- You can also use a Git package that doesn't come from Cygwin.
+Change your current directory to the top of the cloned repository directory,
+create a build directory and generate the Visual Studio project files:
-## Windows Build
+ cd Vulkan-Tools
+ mkdir build
+ cd build
+ cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir
-Cygwin is used in order to obtain a local copy of the Git repository, and to run the CMake command that creates Visual Studio files. Visual Studio is used to build the software, and will re-run CMake as appropriate.
+> Note: The `..` parameter tells `cmake` the location of the top of the
+> repository. If you place your build directory someplace else, you'll need to
+> specify the location of the repository top differently.
-To build all Windows targets (e.g. in a "Developer Command Prompt for VS2013" window):
-```
-cd Vulkan-LoaderAndValidationLayers # cd to the root of the cloned git repository
-update_external_sources.bat --all
-build_windows_targets.bat
-```
+The `-A` option is used to select either the "Win32" or "x64" architecture.
+
+If a generator for a specific version of Visual Studio is required, you can
+specify it for Visual Studio 2015, for example, with:
+
+ 64-bit: -G "Visual Studio 14 2015 Win64"
+ 32-bit: -G "Visual Studio 14 2015"
+
+See this [list](#cmake-visual-studio-generators) of other possible generators
+for Visual Studio.
+
+When generating the project files, the absolute path to a Vulkan-Headers
+install directory must be provided. This can be done by setting the
+`VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the
+`VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In
+either case, the variable should point to the installation directory of a
+Vulkan-Headers repository built with the install target.
+
+The above steps create a Windows solution file named
+`Vulkan-Tools.sln` in the build directory.
+
+At this point, you can build the solution from the command line or open the
+generated solution with Visual Studio.
+
+#### Build the Solution From the Command Line
+
+While still in the build directory:
+
+ cmake --build .
+
+to build the Debug configuration (the default), or:
+
+ cmake --build . --config Release
+
+to make a Release build.
+
+#### Build the Solution With Visual Studio
+
+Launch Visual Studio and open the "Vulkan-Tools.sln" solution file in the
+build folder. You may select "Debug" or "Release" from the Solution
+Configurations drop-down list. Start a build by selecting the Build->Build
+Solution menu item.
+
+#### Windows Install Target
+
+The CMake project also generates an "install" target that you can use to copy
+the primary build artifacts to a specific location using a "bin, include, lib"
+style directory structure. This may be useful for collecting the artifacts and
+providing them to another project that is dependent on them.
+
+The default location is `$CMAKE_BINARY_DIR\install`, but can be changed with
+the `CMAKE_INSTALL_PREFIX` variable when first generating the project build
+files with CMake.
+
+You can build the install target from the command line with:
+
+ cmake --build . --config Release --target install
+
+or build the `INSTALL` target from the Visual Studio solution explorer.
+
+#### Using a Loader Built from a Repository
+
+If you do need to build and use your own loader, build the Vulkan-Loader
+repository with the install target and modify your CMake invocation to add the
+location of the loader's install directory:
+
+ cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
+ -DVULKAN_LOADER_INSTALL_DIR=absolute_path_to_install_dir ..
+
+#### Using glslang Built from a Repository
+
+If you do need to build and use your own glslang, build the glslang repository
+with the install target and modify your CMake invocation to add the location
+of the glslang's install directory:
+
+ cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
+ -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir ..
+
+### Windows Notes
+
+#### CMake Visual Studio Generators
+
+The chosen generator should match one of the Visual Studio versions that you
+have installed. Generator strings that correspond to versions of Visual Studio
+include:
+
+| Build Platform | 64-bit Generator | 32-bit Generator |
+|------------------------------|-------------------------------|-------------------------|
+| Microsoft Visual Studio 2013 | "Visual Studio 12 2013 Win64" | "Visual Studio 12 2013" |
+| Microsoft Visual Studio 2015 | "Visual Studio 14 2015 Win64" | "Visual Studio 14 2015" |
+| Microsoft Visual Studio 2017 | "Visual Studio 15 2017 Win64" | "Visual Studio 15 2017" |
+
+## Building On Linux
+
+### Linux Build Requirements
+
+This repository has been built and tested on the two most recent Ubuntu LTS
+versions. Currently, the oldest supported version is Ubuntu 16.04, meaning
+that the minimum officially supported C++11 compiler version is GCC 5.4.0,
+although earlier versions may work. It should be straightforward to adapt this
+repository to other Linux distributions.
+
+[CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Linux-x86_64.tar.gz) is recommended.
+
+#### Required Package List
+
+ sudo apt-get install git cmake build-essential libx11-xcb-dev \
+ libxkbcommon-dev libwayland-dev libxrandr-dev wayland-protocols
+
+### Linux Build
+
+The general approach is to run CMake to generate make files. Then either run
+CMake with the `--build` option or `make` to build from the command line.
+
+#### Linux Quick Start
+
+ cd Vulkan-Tools
+ mkdir build
+ cd build
+ cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir ..
+ make
+
+See below for the details.
+
+#### Use CMake to Create the Make Files
+
+Change your current directory to the top of the cloned repository directory,
+create a build directory and generate the make files.
+
+ cd Vulkan-Tools
+ mkdir build
+ cd build
+ cmake -DCMAKE_BUILD_TYPE=Debug \
+ -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
+ -DCMAKE_INSTALL_PREFIX=install ..
+
+> Note: The `..` parameter tells `cmake` the location of the top of the
+> repository. If you place your `build` directory someplace else, you'll need
+> to specify the location of the repository top differently.
+
+Use `-DCMAKE_BUILD_TYPE` to specify a Debug or Release build.
+
+When generating the project files, the absolute path to a Vulkan-Headers
+install directory must be provided. This can be done by setting the
+`VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the
+`VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In
+either case, the variable should point to the installation directory of a
+Vulkan-Headers repository built with the install target.
+
+> Note: For Linux, the default value for `CMAKE_INSTALL_PREFIX` is
+> `/usr/local`, which would be used if you do not specify
+> `CMAKE_INSTALL_PREFIX`. In this case, you may need to use `sudo` to install
+> to system directories later when you run `make install`.
+
+#### Build the Project
+
+You can just run `make` to begin the build.
+
+To speed up the build on a multi-core machine, use the `-j` option for `make`
+to specify the number of cores to use for the build. For example:
+
+ make -j4
+
+You can also use
+
+ cmake --build .
+
+If your build system supports ccache, you can enable that via CMake option `-DUSE_CCACHE=On`
+
+### Linux Notes
+
+#### WSI Support Build Options
+
+By default, the repository components are built with support for the
+Vulkan-defined WSI display servers: Xcb, Xlib, and Wayland. It is recommended
+to build the repository components with support for these display servers to
+maximize their usability across Linux platforms. 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`.
+
+Note vulkaninfo currently only supports Xcb and Xlib WSI display servers. See
+the CMakeLists.txt file in `Vulkan-Tools/vulkaninfo` for more info.
+
+You can select which WSI subsystem is used to execute the vkcube applications
+using a CMake option called CUBE_WSI_SELECTION. Supported options are XCB
+(default), XLIB, and WAYLAND. Note that you must build using the corresponding
+BUILD_WSI_*_SUPPORT enabled at the base repository level. For instance,
+creating a build that will use Xlib when running the vkcube demos, your CMake
+command line might look like:
+
+ cmake -DCMAKE_BUILD_TYPE=Debug -DCUBE_WSI_SELECTION=XLIB ..
+
+#### Linux Install to System Directories
+
+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. There are also risks with interfering with binaries installed by
+packages. If you are certain that you would like to install your binaries to
+system directories, you can proceed with these instructions.
+
+Assuming that you've built the code as described above and the current
+directory is still `build`, you can execute:
+
+ sudo make install
+
+This command installs files to `/usr/local` if no `CMAKE_INSTALL_PREFIX` is
+specified when creating the build files with CMake.
+
+You may need to run `ldconfig` in order to refresh the system loader search
+cache on some Linux systems.
+
+You can further customize the installation location by setting additional
+CMake variables to override their defaults. For example, if you would like to
+install to `/tmp/build` instead of `/usr/local`, on your CMake command line
+specify:
+
+ -DCMAKE_INSTALL_PREFIX=/tmp/build
+
+Then run `make install` as before. The install step places the files in
+`/tmp/build`. This may be useful for collecting the artifacts and providing
+them to another project that is dependent on them.
+
+Note: The Mock ICD is not installed by default since it is a "null" driver
+that does not render anything and is used for testing purposes. Installing it
+to system directories may cause some applications to discover and use this
+driver instead of other full drivers installed on the system. If you really
+want to install this null driver, use:
+
+ -DINSTALL_ICD=ON
+
+See the CMake documentation for more details on using these variables to
+further customize your installation.
+
+Also see the `LoaderAndLayerInterface` document in the `loader` folder of the
+Vulkan-Loader repository for more information about loader and layer
+operation.
+
+#### Linux Uninstall
-At this point, you can use Windows Explorer to launch Visual Studio by double-clicking on the "VULKAN.sln" file in the \build folder. Once Visual Studio comes up, you can select "Debug" or "Release" from a drop-down list. You can start a build with either the menu (Build->Build Solution), or a keyboard shortcut (Ctrl+Shift+B). As part of the build process, Python scripts will create additional Visual Studio files and projects, along with additional source files. All of these auto-generated files are under the "build" folder.
+To uninstall the files from the system directories, you can execute:
-Vulkan programs must be able to find and use the vulkan-1.dll library. Make sure it is either installed in the C:\Windows\System32 folder, or the PATH environment variable includes the folder that it is located in.
+ sudo make uninstall
-To run Vulkan programs you must tell the icd loader where to find the libraries.
-This is described in a `LoaderAndLayerInterface` document in the `loader` folder in this repository.
-This specification describes both how ICDs and layers should be properly
-packaged, and how developers can point to ICDs and layers within their builds.
+### Linux Tests
+
+After making any changes to the repository, you should perform some quick
+sanity tests, such as running the vkcube demo with validation enabled.
+
+To run the **vkcube application** with validation, in a terminal change to the
+`build/cube` directory and run:
+
+ VK_LAYER_PATH=../path/to/validation/layers ./vkcube --validate
+
+If you have an SDK installed and have run the setup script to set the
+`VULKAN_SDK` environment variable, it may be unnecessary to specify a
+`VK_LAYER_PATH`.
+
+#### Linux 32-bit support
+
+Usage of the contents of this repository in 32-bit Linux environments is not
+officially supported. However, since this repository is supported on 32-bit
+Windows, these modules should generally work on 32-bit Linux.
+
+Here are some notes for building 32-bit targets on a 64-bit Ubuntu "reference"
+platform:
+
+If not already installed, install the following 32-bit development libraries:
+
+`gcc-multilib g++-multilib libx11-dev:i386`
+
+This list may vary depending on your distribution and which windowing systems
+you are building for.
+
+Set up your environment for building 32-bit targets:
+
+ export ASFLAGS=--32
+ export CFLAGS=-m32
+ export CXXFLAGS=-m32
+ export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu
+
+Again, your PKG_CONFIG configuration may be different, depending on your
+distribution.
+
+Finally, rebuild the repository using `cmake` and `make`, as explained above.
+
+## Building On Android
-## Android Build
Install the required tools for Linux and Windows covered above, then add the
following.
-### Android Studio
-- Install Android Studio 2.1, latest Preview (tested with 4):
- - http://tools.android.com/download/studio/canary
-- From the "Welcome to Android Studio" splash screen, add the following components using Configure > SDK Manager:
- - SDK Platforms > Android N Preview
- - SDK Tools > Android NDK
-#### Add NDK to path
+### Android Build Requirements
+
+- Install [Android Studio 2.3](https://developer.android.com/studio/index.html) or later.
+- From the "Welcome to Android Studio" splash screen, add the following components using
+ Configure > SDK Manager:
+ - SDK Platforms > Android 6.0 and newer
+ - SDK Tools > Android SDK Build-Tools
+ - SDK Tools > Android SDK Platform-Tools
+ - SDK Tools > NDK (Side by side)
+
+#### Add Android specifics to environment
+
+For each of the below, you may need to specify a different build-tools and ndk
+versions, as Android Studio will roll them forward fairly regularly.
On Linux:
-```
-export PATH=$HOME/Android/sdk/ndk-bundle:$PATH
-```
+
+ export ANDROID_SDK_HOME=$HOME/Android/sdk
+ export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk/23.0.7599858
+ export PATH=$ANDROID_NDK_HOME:$PATH
+ export PATH=$ANDROID_SDK_HOME/platform-tools:$PATH
+ export PATH=$ANDROID_SDK_HOME/build-tools/31.0.0:$PATH
+
On Windows:
-```
-set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH%
-```
+
+ set ANDROID_SDK_HOME=%LOCALAPPDATA%\Android\sdk
+ set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk\23.0.7599858
+ set PATH=%ANDROID_NDK_HOME%;%PATH%
+ set PATH=%ANDROID_SDK_HOME%\platform-tools;%PATH%
+ set PATH=%ANDROID_SDK_HOME%\build-tools\31.0.0;%PATH%
+
On OSX:
-```
-export PATH=$HOME/Library/Android/sdk/ndk-bundle:$PATH
-```
-### Additional OSX System Requirements
-Tested on OSX version 10.11.4
- Setup Homebrew and components
-- Follow instructions on [brew.sh](http://brew.sh) to get homebrew installed.
-```
-/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-```
+ export ANDROID_SDK_HOME=$HOME/Library/Android/sdk
+ export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/23.0.7599858
+ export PATH=$ANDROID_NDK_PATH:$PATH
+ export PATH=$ANDROID_SDK_HOME/platform-tools:$PATH
+ export PATH=$ANDROID_SDK_HOME/build-tools/31.0.0:$PATH
+
+Note: If `jarsigner` is missing from your platform, you can find it in the
+Android Studio install or in your Java installation. If you do not have Java,
+you can get it with something like the following:
+
+ sudo apt-get install openjdk-8-jdk
+
+### Android Build
+
+Use the following script to build the vkcube demo for Android:
+
+ cd build-android
+ ./build_all.sh
+
+The APK can be installed on production devices with:
+
+ ./install_all.sh [-s <serial number>]
+
+Note that there are no equivalent scripts on Windows yet, that work needs to
+be completed.
+
+### Run vkcube
+
+Use the following command to run vkcube for Android:
+
+ adb shell am start com.example.VkCube/android.app.NativeActivity
+
+## Building on MacOS
+
+### MacOS Build Requirements
+
+Tested on OSX version 10.12
+
+NOTE: To force the OSX version set the environment variable [MACOSX_DEPLOYMENT_TARGET](https://cmake.org/cmake/help/latest/envvar/MACOSX_DEPLOYMENT_TARGET.html) when building VVL and it's dependencies.
+
+Setup Homebrew and components
+
- Ensure Homebrew is at the beginning of your PATH:
-```
-export PATH=$HOME/homebrew/bin:$PATH
-```
+
+ export PATH=/usr/local/bin:$PATH
+
- Add packages with the following (may need refinement)
-```
-brew install cmake
-brew install python
-brew install python3
-```
-### Build steps for Android
-Use the following to ensure the Android build works.
-#### Linux and OSX
-Follow the setup steps for Linux or OSX above, then from your terminal:
-```
-cd build-android
-./update_external_sources_android.sh
-./android-generate.sh
-ndk-build
-```
-#### Windows
-Follow the setup steps for Windows above, then from Developer Command Prompt for VS2013:
-```
-cd build-android
-update_external_sources_android.bat
-android-generate.bat
-ndk-build
-```
+
+ brew install python python3 git
+
+### Clone the Repository
+
+Clone the Vulkan-Tools repository as defined above in the [Download the Repository](#download-the-repository)
+section.
+
+### Get the External Libraries
+
+[MoltenVK](https://github.com/KhronosGroup/MoltenVK) Library
+
+- Building the vkcube and vulkaninfo applications require linking to the
+ MoltenVK Library (libMoltenVK.dylib)
+ - The following option should be used on the cmake command line to specify a
+ vulkan loader library: MOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK
+ making sure to specify an absolute path, like so: cmake
+ -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK ....
+
+Vulkan Loader Library
+
+- Building the vkcube and vulkaninfo applications require linking to the Vulkan
+ Loader Library (libvulkan.1.dylib)
+ - The following option should be used on the cmake command line to specify a
+ vulkan loader library:
+ VULKAN_LOADER_INSTALL_DIR=/absolute_path_to/Vulkan-Loader_install_dir
+ making sure to specify an absolute path.
+
+### MacOS build
+
+#### CMake Generators
+
+This repository uses CMake to generate build or project files that are then
+used to build the repository. The CMake generators explicitly supported in
+this repository are:
+
+- Unix Makefiles
+- Xcode
+
+#### Building with the Unix Makefiles Generator
+
+This generator is the default generator, so all that is needed for a debug
+build is:
+
+ mkdir build
+ cd build
+ cmake -DCMAKE_BUILD_TYPE=Debug \
+ -DVULKAN_LOADER_INSTALL_DIR=/absolute_path_to/Vulkan-Loader_install_dir \
+ -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK \
+ -DCMAKE_INSTALL_PREFIX=install ..
+ make
+
+To speed up the build on a multi-core machine, use the `-j` option for `make`
+to specify the number of cores to use for the build. For example:
+
+ make -j4
+
+You can now run the demo applications from the command line:
+
+ open cube/vkcube.app
+ open cube/vkcubepp.app
+
+Or you can locate them from `Finder` and launch them from there.
+
+##### The Install Target and RPATH
+
+The applications you just built are "bundled applications", but the
+executables are using the `RPATH` mechanism to locate runtime dependencies
+that are still in your build tree.
+
+To see this, run this command from your `build` directory:
+
+ otool -l cube/cube.app/Contents/MacOS/vkcube
+
+and note that the `vkcube` executable contains loader commands:
+
+- `LC_LOAD_DYLIB` to load `libvulkan.1.dylib` via an `@rpath`
+- `LC_RPATH` that contains an absolute path to the build location of the Vulkan loader
+
+This makes the bundled application "non-transportable", meaning that it won't
+run unless the Vulkan loader is on that specific absolute path. This is useful
+for debugging the loader or other components built in this repository, but not
+if you want to move the application to another machine or remove your build
+tree.
+
+To address this problem, run:
+
+ make install
+
+This step copies the bundled applications to the location specified by
+CMAKE_INSTALL_PREFIX and "cleans up" the `RPATH` to remove any external
+references and performs other bundle fix-ups. After running `make install`,
+run the `otool` command again from the `build/install` directory and note:
+
+- `LC_LOAD_DYLIB` is now `@executable_path/../MacOS/libvulkan.1.dylib`
+- `LC_RPATH` is no longer present
+
+The "bundle fix-up" operation also puts a copy of the Vulkan loader into the
+bundle, making the bundle completely self-contained and self-referencing.
+
+##### The vulkaninfo Application
+
+There is also a `vulkaninfo` application that you can run from the command line:
+
+ vulkaninfo/vulkaninfo
+
+If you run this from the build directory, vulkaninfo's RPATH is already
+set to point to the Vulkan loader in the build tree, so it has no trouble
+finding it. But the loader will not find the MoltenVK driver and you'll see a
+message about an incompatible driver. To remedy this:
+
+ VK_ICD_FILENAMES=<path-to>/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json vulkaninfo/vulkaninfo
+
+If you run `vulkaninfo` from the install directory, the `RPATH` in the
+`vulkaninfo` application got removed and the OS needs extra help to locate
+the Vulkan loader:
+
+ DYLD_LIBRARY_PATH=<path-to>/Vulkan-Loader/loader VK_ICD_FILENAMES=<path-to>/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json vulkaninfo/vulkaninfo
+
+#### Building with the Xcode Generator
+
+To create and open an Xcode project:
+
+ mkdir build-xcode
+ cd build-xcode
+ cmake -DVULKAN_LOADER_INSTALL_DIR=/absolute_path_to/Vulkan-Loader_install_dir -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK -GXcode ..
+ open VULKAN.xcodeproj
+
+Within Xcode, you can select Debug or Release builds in the project's Build
+Settings. You can also select individual schemes for working with specific
+applications like `vkcube`.
projects / platform / upstream / Vulkan-Tools.git / blobdiff