From: Karl Schultz Date: Mon, 18 Jun 2018 19:44:40 +0000 (-0600) Subject: doc: Update BUILD.md [skip ci] X-Git-Tag: submit/tizen/20181227.054638~73 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=51a4a5b235dec1fc13b83e1abbabed6d228aba3a;p=platform%2Fupstream%2FVulkan-Loader.git doc: Update BUILD.md [skip ci] --- diff --git a/BUILD.md b/BUILD.md index b2fdcc52..6d77ed28 100644 --- a/BUILD.md +++ b/BUILD.md @@ -5,105 +5,209 @@ Instructions for building this repository on Linux, Windows, and MacOS. ## Index 1. [Contributing](#contributing-to-the-repository) -2. [Repository Set-Up](#repository-set-up) -3. [Windows Build](#building-on-windows) -4. [Linux Build](#building-on-linux) -5. [MacOS build](#building-on-macos) +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. [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. +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 desktop Vulkan +loader and its tests. + +### Installed Files + +The `install` target installs the following files under the directory +indicated by *install_dir*: + +- *install_dir*`/include/vulkan` : `vk_layer_dispatch_table.h` +- *install_dir*`/lib` : The Vulkan loader library +- *install_dir*`/bin` : The Vulkan loader library DLL (Windows) + +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. -Before proceeding, it is strongly recommended that you obtain a Vulkan driver from your -graphics hardware vendor and install it properly. +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-Loader + git clone https://github.com/KhronosGroup/Vulkan-Loader.git + +### Repository Dependencies + +This repository attempts to resolve some of its dependencies by using +components found from the following places, in this order: + +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 + +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 loader. 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. + +#### Google Test + +The loader tests depend on the [Google Test](https://github.com/google/googletest) +framework and do not build unless this framework is downloaded into the +repository's `external` directory. + +To obtain the framework, change your current directory to the top of your +Vulkan-Loader repository and run: + + git clone https://github.com/google/googletest.git external/googletest + +before configuring your build with CMake. + +If you do not need the loader tests, there is no need to download this +framework. + +### Build and Install Directories + +A common convention is to place the `build` directory in the top directory of +the repository and place the `install` directory as a child of the `build` +directory. The remainder of these instructions follow this convention, +although you can place these directories in any location. + +### 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_LOADER | All | `ON` | Controls whether or not the loader is built. Setting this to `OFF` will allow building the tests against a loader that is installed to the system. | +| BUILD_TESTS | All | `ON` | Controls whether or not the loader tests are built. This option is only available when a copy of Google Test is available in the "external" directory. | +| BUILD_WSI_XCB_SUPPORT | Linux | `ON` | Build the loader with the XCB entry points enabled. Without this, the XCB headers should not be needed, but the extension `VK_KHR_xcb_surface` won't be available. | +| BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the loader with the Xlib entry points enabled. Without this, the X11 headers should not be needed, but the extension `VK_KHR_xlib_surface` won't be available. | +| BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the loader with the Wayland entry points enabled. Without this, the Wayland headers should not be needed, but the extension `VK_KHR_wayland_surface` won't be available. | +| BUILD_WSI_MIR_SUPPORT | Linux | `OFF` | Build the loader with the Mir entry points enabled. Without this, the Mir headers should not be needed, but the extension `VK_KHR_mir_surface` won't be available. | +| ENABLE_STATIC_LOADER | Windows | `OFF` | By default, the loader is built as a dynamic library. This allows it to be built as a static library, instead. | +| ENABLE_WIN10_ONECORE | Windows | `OFF` | Link the loader to the [OneCore](https://msdn.microsoft.com/en-us/library/windows/desktop/mt654039.aspx) umbrella library, instead of the standard Win32 ones. | +| USE_CCACHE | Linux | `OFF` | Enable caching with the CCache program. | + +The following is a table of all string options currently supported by this repository: + +| Option | Platform | Default | Description | +| ------ | -------- | ------- | ----------- | +| CMAKE_OSX_DEPLOYMENT_TARGET | MacOS | `10.12` | The minimum version of MacOS for loader deployment. | +| FALLBACK_CONFIG_DIRS | Linux/MacOS | `/etc/xdg` | Configuration path(s) to use instead of `XDG_CONFIG_DIRS` if that environment variable is unavailable. The default setting is freedesktop compliant. | +| FALLBACK_DATA_DIRS | Linux/MacOS | `/usr/local/share:/usr/share` | Configuration path(s) to use instead of `XDG_DATA_DIRS` if that environment variable is unavailable. The default setting is freedesktop compliant. | + +These variables should be set using the `-D` option when invoking +CMake to generate the native platform files. ## Building On Windows -### Windows Build Requirements - -Windows 7+ with the following software packages: - -- Microsoft Visual Studio 2013 Update 4 Professional, VS2015 (any version), or VS2017 (any version). -- [Vulkan-Headers](https://github.com/KhronosGroup/Vulkan-Headers) - - Vulkan headers should be built with the "install" target. Generally, you will want to use the - `CMAKE_INSTALL_PREFIX` and remember where you set this to. -- [CMake](http://www.cmake.org/download/) - - Tell the installer to "Add CMake to the system PATH" environment variable. -- [Python 3](https://www.python.org/downloads) - - 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) - - Python3.3 or later is necessary for the Windows py.exe launcher that is used to select python3 - rather than python2 if both are installed -- [Git](http://git-scm.com/download/win) - - 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 both the 32-bit and 64-bit versions, as the 64-bit installer does not install the - 32-bit libraries and tools. -- [Google Test](https://github.com/google/googletest) (Tests only) - - To build the loader tests, clone google test into the "external" directory like: - git clone https://github.com/google/googletest external/googletest - - If you do not include Google Test, the repo will still build, but the tests will be omitted +### Windows Development Environment Requirements + +- 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](http://www.cmake.org/download/) (Version 2.8.11 or better) + - 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 ### Windows Build - Microsoft Visual Studio -The general approach is to run `cmake` to generate the VS project files. -Then either run `cmake` again to build from the command line or use the -Visual Studio IDE to open the generated solution and work with the solution -interactively. +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. + +#### Windows Quick Start -It should be possible to perform these `cmake` invocations from any one of the Windows -"terminal programs", including the standard Windows Command Prompt, MSBuild Command Prompt, -PowerShell, MINGW, CygWin, etc. + cd Vulkan-Loader + mkdir build + cd build + cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir .. + cmake --build . -#### Use `cmake` to create the VS project files +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. -Switch to the top of the cloned repository directory, -create a build directory and generate the VS project files. -When generating the project files, the location to a Vulkan-Headers install -directory must be provided. This can be done by setting the environment variable -`VULKAN_HEADERS_INSTALL_DIR` or by setting it as a CMake flag. -In either case, the variable should point to the installation directory of the -Vulkan-Headers repo: +See below for the details. + +#### Use `CMake` to Create the Visual Studio Project Files + +Change your current directory to the top of the cloned repository directory, +create a build directory and generate the Visual Studio project files: cd Vulkan-Loader mkdir build cd build - cmake -DVULKAN_HEADERS_INSTALL_DIR=C:\SampleDir .. + cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir .. + +> 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. -As it starts generating the project files, `cmake` responds with something like: +The `-A` option is used to select either the "Win32" or "x64" architecture. - -- Building for: Visual Studio 14 2015 +If a generator for a specific version of Visual Studio is required, you can +specify it for Visual Studio 2015, for example, with: -which is a 32-bit generator. + 64-bit: -G "Visual Studio 14 2015 Win64" + 32-bit: -G "Visual Studio 14 2015" -If this is not what you want, you can supply one of the -[specific generators](#cmake-visual-studio-generators). -For example: +See this [list](#cmake-visual-studio-generators) of other possible generators +for Visual Studio. - cmake -DVULKAN_HEADERS_INSTALL_DIR=C:\SampleDir -G "Visual Studio 14 2015 Win64" .. +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. -This creates a Windows 64-bit solution file named `Vulkan-Loader.sln` -in the build directory for Visual Studio 2015. +The above steps create a Windows solution file named `Vulkan-Loader.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 +#### Build the Solution From the Command Line While still in the build directory: @@ -115,23 +219,25 @@ to build the Debug configuration (the default), or: to make a Release build. -#### Build the solution with Visual Studio +#### Build the Solution With Visual Studio -Launch Visual Studio and open the "Vulkan-Loader.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. +Launch Visual Studio and open the "Vulkan-Loader.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 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. -You can build the install target with: +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 @@ -142,8 +248,8 @@ or build the `INSTALL` target from the Visual Studio solution explorer. The Vulkan-Loader repository contains some simple unit tests for the loader but no other test clients. -To run the loader test script, open a Powershell Console, -change to the `build\tests` directory, and run: +To run the loader test script, open a Powershell Console, change to the +`build\tests` directory, and run: For Release builds: @@ -159,15 +265,16 @@ This script will run the following tests: Vulkan loader handle wrapping, allocation callback, and loader/layer interface tests You can also change to either `build\tests\Debug` or `build\tests\Release` -(depending on which one you built) and run the executable tests (`*.exe`) files -from there. +(depending on which one you built) and run the executable tests (`*.exe`) +files from there. ### Windows Notes #### CMake Visual Studio Generators -The chosen generator should match one of the Visual Studio versions that you have installed. -Appropriate Visual Studio generators include: +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 | |------------------------------|-------------------------------|-------------------------| @@ -175,182 +282,222 @@ Appropriate Visual Studio generators include: | 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" | -#### The Vulkan Loader Library +#### Using The Vulkan Loader Library in this Repository on Windows -Vulkan programs must be able to find and use the Vulkan loader (`vulkan-1.dll`) -library as well as any other libraries the program requires. +Vulkan programs must be able to find and use the Vulkan loader +(`vulkan-1.dll`) library as well as any other libraries the program requires. One convenient way to do this is to copy the required libraries into the same -directory as the program. -The projects in this solution copy the Vulkan loader library and the "googletest" -libraries to the `build\tests\Debug` or the `build\tests\Release` directory, -which is where the `vk_loader_validation_test.exe` executable is found, depending -on what configuration you built. -(The loader validation tests use the "googletest" testing framework.) - -Other techniques include placing the library in a system folder (C:\Windows\System32) or in a -directory that appears in the `PATH` environment variable. - -See the `LoaderAndLayerInterface` document in the `loader` folder in this repository -for more information on how the loader finds driver libraries and layer libraries. -The document also describes both how ICDs and layers should be packaged, -and how developers can point to ICDs and layers within their builds. +directory as the program. The projects in this solution copy the Vulkan loader +library and the "googletest" libraries to the `build\tests\Debug` or the +`build\tests\Release` directory, which is where the +`vk_loader_validation_test.exe` executable is found, depending on what +configuration you built. (The loader validation tests use the "googletest" +testing framework.) + +Other techniques include placing the library in a system folder +(C:\Windows\System32) or in a directory that appears in the `PATH` environment +variable. + +See the `LoaderAndLayerInterface` document in the `loader` folder in this +repository for more information on how the loader finds driver libraries and +layer libraries. The document also describes both how ICDs and layers should +be packaged, and how developers can point to ICDs and layers within their +builds. ## Building On Linux -### Linux Build Requirements +### Linux Development Environment Requirements -This repository has been built and tested on the two most recent Ubuntu LTS versions. -Currently, the oldest supported version is Ubuntu 14.04, meaning that the minimum supported compiler versions are GCC 4.8.2 and Clang 3.4, although earlier versions may work. -It should be straightforward to adapt this repository to other Linux distributions. +This repository has been built and tested on the two most recent Ubuntu LTS +versions. Currently, the oldest supported version is Ubuntu 14.04, meaning +that the minimum supported compiler versions are GCC 4.8.2 and Clang 3.4, +although earlier versions may work. It should be straightforward to adapt this +repository to other Linux distributions. -**Required Package List:** +#### Required Package List - sudo apt-get install git cmake build-essential libx11-xcb-dev libxkbcommon-dev libmirclient-dev libwayland-dev libxrandr-dev + sudo apt-get install git cmake build-essential libx11-xcb-dev \ + libxkbcommon-dev libmirclient-dev libwayland-dev libxrandr-dev -In addition to this, the [Vulkan-Headers](https://github.com/KhronosGroup/Vulkan-Headers) repo should be -built and installed to the directory of your choosing. This can be done by setting `CMAKE_INSTALL_PREFIX` -and running the "install" target from within the Vulkan-Headers repository. +### Linux Build -In addition to this, the loader tests require that a copy of Google Test be present in the "external" directory. -The loader will still build if Google Test is not provided, but the tests will be skipped. -To get a copy of Google Test, run: +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. - git clone https://github.com/google/googletest external/googletest +#### Linux Quick Start + + cd Vulkan-Loader + mkdir build + cd build + cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir .. + make +See below for the details. -### Linux Build +#### Use CMake to Create the Make Files -Switch to the top of the cloned repository directory, +Change your current directory to the top of the cloned repository directory, create a build directory and generate the make files. -When generating the project files, the location to a Vulkan-Headers install -directory must be provided. This can be done by setting the environment variable -`VULKAN_HEADERS_INSTALL_DIR` or by setting it as a CMake flag. -In either case, the variable should point to the installation directory of the -Vulkan-Headers repo: cd Vulkan-Loader mkdir build cd build - cmake -DVULKAN_HEADERS_INSTALL_DIR=/sample/dir -DCMAKE_BUILD_TYPE=Debug .. + cmake -DCMAKE_BUILD_TYPE=Debug \ + -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \ + -DCMAKE_INSTALL_PREFIX=install .. -Run `make -j8` to begin the build. +> 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. -If your build system supports ccache, you can enable that via CMake option `-DUSE_CCACHE=On` +Use `-DCMAKE_BUILD_TYPE` to specify a Debug or Release build. -#### Using the new loader +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. -If you want to test a Vulkan application with the loader you just built from the -[Vulkan-Loader repository](https://github.com/KhronosGroup/Vulkan-Loader), you can -direct the application to load it from your build directory: +> 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`. - export LD_LIBRARY_PATH=/build/loader +#### Build the Project + +You can just run `make` to begin the build. -The `LoaderAndLayerInterface.md` 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. +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 -### WSI Support Build Options +You can also use -By default, the Vulkan Loader is built with support for all 4 Vulkan-defined WSI display servers: Xcb, Xlib, Wayland, and Mir. -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`. -See the top-level CMakeLists.txt file for more info. + cmake --build . -### Linux Install to System Directories +If your build system supports ccache, you can enable that via CMake option +`-DUSE_CCACHE=On` + +### Linux Notes + +#### Using The Vulkan Loader Library in this Repository on Linux + +The `vk_loader_validation_tests` executable is linked with an RPATH setting to +allow it to find the Vulkan loader library in the repository's build +directory. This allows the test executable to run and find this Vulkan loader +library without installing the loader library to a directory searched by the +system loader or in the `LD_LIBRARY_PATH`. + +If you want to test a Vulkan application that is not built within this +repository with the loader you just built from this repository, you can direct +the application to load it from your build directory: + + export LD_LIBRARY_PATH=/build/loader -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. +#### WSI Support Build Options -Assuming that you've built the code as described above and the current directory is still `build`, you can execute: +By default, the Vulkan Loader is 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`. + +#### 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: +This command installs files to `/usr/local` if no `CMAKE_INSTALL_PREFIX` is +specified when creating the build files with CMake: -- `/usr/local/include/vulkan`: Vulkan include files - `/usr/local/lib`: Vulkan loader library and package config files -You may need to run `ldconfig` in order to refresh the system loader search cache on some Linux systems. +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: +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 - -DDEST_DIR=/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. +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. -Using the `CMAKE_INSTALL_PREFIX` to customize the install location also modifies -the loader search paths to include searching for layers in the specified install location. -In this example, setting `CMAKE_INSTALL_PREFIX` to `/tmp/build` causes the loader to search -`/tmp/build/etc/vulkan/explicit_layer.d` and `/tmp/build/share/vulkan/explicit_layer.d` -for the layer JSON files. -The loader also searches the "standard" system locations of `/etc/vulkan/explicit_layer.d` and -`/usr/share/vulkan/explicit_layer.d` after searching the two locations under `/tmp/build`. +Using the `CMAKE_INSTALL_PREFIX` to customize the install location also +modifies the loader search paths to include searching for layers in the +specified install location. In this example, setting `CMAKE_INSTALL_PREFIX` to +`/tmp/build` causes the loader to search +`/tmp/build/etc/vulkan/explicit_layer.d` and +`/tmp/build/share/vulkan/explicit_layer.d` for the layer JSON files. The +loader also searches the "standard" system locations of +`/etc/vulkan/explicit_layer.d` and `/usr/share/vulkan/explicit_layer.d` after +searching the two locations under `/tmp/build`. -You can further customize the installation directories by using the CMake variables -`CMAKE_INSTALL_SYSCONFDIR` to rename the `etc` directory and `CMAKE_INSTALL_DATADIR` -to rename the `share` directory. +You can further customize the installation directories by using the CMake +variables `CMAKE_INSTALL_SYSCONFDIR` to rename the `etc` directory and +`CMAKE_INSTALL_DATADIR` to rename the `share` directory. -See the CMake documentation for more details on using these variables -to further customize your installation. +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 in this repository for more information about loader operation. -Note that some executables in this repository (e.g., `vk_loader_validation_tests`) -use the "rpath" linker directive to -load the Vulkan loader from the build directory, `build` in this example. -This means that even after installing the loader to the system directories, these executables still -use the loader from the build directory. +Note that some executables in this repository (e.g., +`vk_loader_validation_tests`) use the RPATH linker directive to load the +Vulkan loader from the build directory, `build` in this example. This means +that even after installing the loader to the system directories, these +executables still use the loader from the build directory. -### Linux Uninstall +#### Linux Uninstall To uninstall the files from the system directories, you can execute: sudo make uninstall -### Linux Tests +#### Linux Tests The Vulkan-Loader repository contains some simple unit tests for the loader but no other test clients. -To run the loader test script, -change to the `build/tests` directory, and run: +To run the loader test script, change to the `build/tests` directory, and run: ./run_all_tests.sh This script will run the following tests: -- `vk_loader_validation_tests`: - Vulkan loader handle wrapping, allocation callback, and loader/layer interface tests - -### Linux Notes - -#### RPATH - -The `vk_loader_validation_tests` executable is linked with an `RPATH` setting to allow -it to find the Vulkan loader library in the repository's build directory. -This allows the test executable to run and find this Vulkan loader library -without installing the loader library to a directory searched by the system -loader or in the `LD_LIBRARY_PATH`. +- `vk_loader_validation_tests`: Vulkan loader handle wrapping, allocation + callback, and loader/layer interface tests #### Linux 32-bit support -Usage of this repository's contents 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. +Usage of this repository's contents 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: +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. +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: @@ -359,13 +506,14 @@ Set up your environment for building 32-bit targets: export CXXFLAGS=-m32 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu -Again, your PKG_CONFIG configuration may be different, depending on your distribution. +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 MacOS -### MacOS Build Requirements +### MacOS Development Environment Requirements Tested on OSX version 10.12.6 @@ -373,7 +521,8 @@ 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)" + /usr/bin/ruby -e "$(curl -fsSL \ + https://raw.githubusercontent.com/Homebrew/install/master/install)" - Ensure Homebrew is at the beginning of your PATH: @@ -383,23 +532,19 @@ Setup Homebrew and components brew install cmake python python3 git - In addition to this, the [Vulkan-Headers](https://github.com/KhronosGroup/Vulkan-Headers) repo should be - built and installed to the directory of your choosing. This can be done by setting `CMAKE_INSTALL_PREFIX` - and running the "install" target from within the Vulkan-Headers repository. +### Clone the Repository -- The loader tests require that a copy of Google Test be present in the "external" directory. - The loader will still build if Google Test is not provided, but the tests will be skipped. - To get a copy of Google Test, run: +Clone the Vulkan-ValidationLayers repository: - git clone https://github.com/google/googletest external/googletest + git clone https://github.com/KhronosGroup/Vulkan-ValidationLayers.git ### 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: +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 @@ -407,20 +552,21 @@ The CMake generators explicitly supported in this repository are: #### Building with the Unix Makefiles Generator This generator is the default generator. -However, when generating the project files, the location to a Vulkan-Headers install -directory must be provided. This can be done by setting the environment variable -`VULKAN_HEADERS_INSTALL_DIR` or by setting it as a CMake flag. -In either case, the variable should point to the installation directory of the -Vulkan-Headers repo: - mkdir build - cd build - cmake -DVULKAN_HEADERS_INSTALL_DIR=/sample/dir -DCMAKE_BUILD_TYPE=Debug .. - make +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. + + mkdir build + cd build + cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir -DCMAKE_BUILD_TYPE=Debug .. + 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: +to specify the number of cores to use for the build. For example: make -j4 @@ -428,77 +574,34 @@ For example: To create and open an Xcode project: - mkdir build-xcode - cd build-xcode - cmake -GXcode .. - open Vulkan-Loader.xcodeproj + mkdir build-xcode + cd build-xcode + cmake -GXcode .. + open Vulkan-Loader.xcodeproj -Within Xcode, you can select Debug or Release builds in the project's Build Settings. +Within Xcode, you can select Debug or Release builds in the project's Build +Settings. ### Using the new macOS loader -If you want to test a Vulkan application with the loader you just built, you can direct the application to load it from your build directory: +If you want to test a Vulkan application with the loader you just built, you +can direct the application to load it from your build directory: - export DYLD_LIBRARY_PATH=/build/loader + export DYLD_LIBRARY_PATH=/build/loader ### MacOS Tests -The Vulkan-Loader repository contains some simple unit tests for the loader but no other test clients. +The Vulkan-Loader repository contains some simple unit tests for the loader +but no other test clients. -Before you run these tests, you will need to clone and build the [MoltenVK](https://github.com/KhronosGroup/MoltenVK) repository. +Before you run these tests, you will need to clone and build the +[MoltenVK](https://github.com/KhronosGroup/MoltenVK) repository. You will also need to direct your new loader to the MoltenVK ICD: - export VK_ICD_FILENAMES=/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json - -To run the loader test script, change to the `build/tests` directory in your Vulkan-Loader repository, and run: - - ./vk_loader_validation_tests - -## Optional software packages - -- [Cygwin for windows](https://www.cygwin.com/) - - Cygwin provides some Linux-like tools, which can be valuable for working with the repository, - such as the BASH shell and git packages - - With appropriate adjustments, it is possible to use other shells and environments as well - -- [Ninja on all platforms](https://github.com/ninja-build/ninja/releases) -- [The Ninja-build project](https://ninja-build.org) -- [Ninja Users Manual](https://ninja-build.org/manual.html) - -- [QtCreator as IDE for CMake builds on all platforms](https://qt.io/download-open-source/#section-2) - -## 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_LOADER | All | `ON` | Controls whether or not the loader is built. Setting this to `OFF` will allow building the tests against a loader that is installed to the system. | -| BUILD_TESTS | All | `ON` | Controls whether or not the loader tests are built. This option is only available when a copy of Google Test is available in the "external" directory. | -| BUILD_WSI_XCB_SUPPORT | Linux | `ON` | Build the loader with the XCB entry points enabled. Without this, the XCB headers should not be needed, but the extension `VK_KHR_xcb_surface` won't be available. | -| BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the loader with the Xlib entry points enabled. Without this, the X11 headers should not be needed, but the extension `VK_KHR_xlib_surface` won't be available. | -| BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the loader with the Wayland entry points enabled. Without this, the Wayland headers should not be needed, but the extension `VK_KHR_wayland_surface` won't be available. | -| BUILD_WSI_MIR_SUPPORT | Linux | `OFF` | Build the loader with the Mir entry points enabled. Without this, the Mir headers should not be needed, but the extension `VK_KHR_mir_surface` won't be available. | -| ENABLE_STATIC_LOADER | Windows | `OFF` | By default, the loader is built as a dynamic library. This allows it to be built as a static library, instead. | -| ENABLE_WIN10_ONECORE | Windows | `OFF` | Link the loader to the [OneCore](https://msdn.microsoft.com/en-us/library/windows/desktop/mt654039.aspx) umbrella library, instead of the standard Win32 ones. | -| USE_CCACHE | Linux | `OFF` | Enable caching with the CCache program. | - -The following is a table of all string options currently supported by this repsitory: - -| Option | Platform | Default | Description | -| ------ | -------- | ------- | ----------- | -| CMAKE_OSX_DEPLOYMENT_TARGET | MacOS | `10.12` | The minimum version of MacOS for loader deployment. | -| FALLBACK_CONFIG_DIRS | Linux/MacOS | `/etc/xdg` | Configuration path(s) to use instead of `XDG_CONFIG_DIRS` if that environment variable is unavailable. The default setting is freedesktop compliant. | -| FALLBACK_DATA_DIRS | Linux/MacOS | `/usr/local/share:/usr/share` | Configuration path(s) to use instead of `XDG_DATA_DIRS` if that environment variable is unavailable. The default setting is freedesktop compliant. | - -These environment variables should be set using the `-D` flag when invoking CMake to generate the native platform files. -For example, to generate a Linux makefile with the tests disabled and a custom configuration directory, one would run: + export VK_ICD_FILENAMES=/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json -```shell -cmake .. -DBUILD_TESTS=OFF -DFALLBACK_CONFIG_DIRS=/my/custom/location -``` +To run the loader test script, change to the `build/tests` directory in your +Vulkan-Loader repository, and run: -The directory can then be built as usual, which on Linux would simply be the `make` command. + ./vk_loader_validation_tests