1# Build Instructions 2 3Instructions for building this repository on Linux, Windows, and MacOS. 4 5## Table Of Contents 6 7- [Contributing to the Repository](#contributing-to-the-repository) 8- [Repository Content](#repository-content) 9 - [Installed Files](#installed-files) 10- [Repository Set-Up](#repository-set-up) 11 - [Display Drivers](#display-drivers) 12 - [Download the Repository](#download-the-repository) 13 - [Repository Dependencies](#repository-dependencies) 14 - [Build and Install Directories](#build-and-install-directories) 15 - [Building Dependent Repositories with Known-Good Revisions](#building-dependent-repositories-with-known-good-revisions) 16 - [Generated source code](#generated-source-code) 17 - [Build Options](#build-options) 18- [Building On Windows](#building-on-windows) 19 - [Windows Development Environment Requirements](#windows-development-environment-requirements) 20 - [Windows Build - Microsoft Visual Studio](#windows-build---microsoft-visual-studio) 21 - [Windows Notes](#windows-notes) 22 - [CMake Visual Studio Generators](#cmake-visual-studio-generators) 23 - [Using The Vulkan Loader Library in this Repository on Windows](#using-the-vulkan-loader-library-in-this-repository-on-windows) 24- [Building On Linux](#building-on-linux) 25 - [Linux Development Environment Requirements](#linux-development-environment-requirements) 26 - [Linux Build](#linux-build) 27- [Building on MacOS](#building-on-macos) 28 - [MacOS Development Environment Requirements](#macos-development-environment-requirements) 29 - [Clone the Repository](#clone-the-repository) 30 - [MacOS build](#macos-build) 31- [Building on Fuchsia](#building-on-fuchsia) 32- [Building on QNX](#building-on-qnx) 33 - [SDK Symbols](#sdk-symbols) 34 35 36## Contributing to the Repository 37 38If you intend to contribute, the preferred work flow is for you to develop 39your contribution in a fork of this repository in your GitHub account and then 40submit a pull request. Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file 41in this repository for more details. 42 43## Repository Content 44 45This repository contains the source code necessary to build the desktop Vulkan 46loader and its tests. 47 48### Installed Files 49 50The `install` target installs the following files under the directory 51indicated by *install_dir*: 52 53- *install_dir*`/lib` : The Vulkan loader library 54- *install_dir*`/bin` : The Vulkan loader library DLL (Windows) 55 56The `uninstall` target can be used to remove the above files from the install 57directory. 58 59## Repository Set-Up 60 61### Display Drivers 62 63This repository does not contain a Vulkan-capable driver. You will need to 64obtain and install a Vulkan driver from your graphics hardware vendor or from 65some other suitable source if you intend to run Vulkan applications. 66 67### Download the Repository 68 69To create your local git repository: 70 71 git clone https://github.com/KhronosGroup/Vulkan-Loader.git 72 73### Repository Dependencies 74 75This repository attempts to resolve some of its dependencies by using 76components found from the following places, in this order: 77 781. CMake or Environment variable overrides (e.g., -DVULKAN_HEADERS_INSTALL_DIR) 791. LunarG Vulkan SDK, located by the `VULKAN_SDK` environment variable 801. System-installed packages, mostly applicable on Linux 81 82Dependencies that cannot be resolved by the SDK or installed packages must be 83resolved with the "install directory" override and are listed below. The 84"install directory" override can also be used to force the use of a specific 85version of that dependency. 86 87#### Vulkan-Headers 88 89This repository has a required dependency on the [Vulkan Headers repository](https://github.com/KhronosGroup/Vulkan-Headers). 90You must clone the headers repository and build its `install` target before 91building this repository. The Vulkan-Headers repository is required because it 92contains the Vulkan API definition files (registry) that are required to build 93the loader. You must also take note of the headers install directory and pass 94it on the CMake command line for building this repository, as described below. 95 96#### Test Dependencies 97 98The loader tests depend on the [Google Test](https://github.com/google/googletest) library and 99on Windows platforms depends on the [Microsoft Detours](https://github.com/microsoft/Detours) library. 100 101To build the tests, pass the `-DUPDATE_DEPS=ON` and `-DBUILD_TESTS=ON` options when generating the project: 102```bash 103cmake ... -DUPDATE_DEPS=ON -DBUILD_TESTS=ON ... 104``` 105This will ensure googletest and detours is downloaded and the appropriate version is used. 106 107### Build and Install Directories 108 109A common convention is to place the `build` directory in the top directory of 110the repository and place the `install` directory as a child of the `build` 111directory. The remainder of these instructions follow this convention, 112although you can place these directories in any location. 113 114### Building Dependent Repositories with Known-Good Revisions 115 116There is a Python utility script, `scripts/update_deps.py`, that you can use 117to gather and build the dependent repositories mentioned above. 118This program also uses information stored in the `scripts/known-good.json` file 119to checkout dependent repository revisions that are known to be compatible with 120the revision of this repository that you currently have checked out. 121 122You can choose to do this manually or automatically. 123The first step to either is cloning the Vulkan-Loader repo and stepping into 124that newly cloned folder: 125 126``` 127 git clone git@github.com:KhronosGroup/Vulkan-Loader.git 128 cd Vulkan-Loader 129``` 130 131#### Manually 132 133To manually update the dependencies you now must create the build folder, and 134run the update deps script followed by the necessary CMake build commands: 135 136``` 137 mkdir build 138 cd build 139 ../scripts/update_deps.py 140 cmake -C helper.cmake .. 141 cmake --build . 142``` 143 144##### Notes About the Manual Option 145 146- You may need to adjust some of the CMake options based on your platform. See 147 the platform-specific sections later in this document. 148- The `update_deps.py` script fetches and builds the dependent repositories in 149 the current directory when it is invoked. In this case, they are built in 150 the `build` directory. 151- The `build` directory is also being used to build this 152 (Vulkan-ValidationLayers) repository. But there shouldn't be any conflicts 153 inside the `build` directory between the dependent repositories and the 154 build files for this repository. 155- The `--dir` option for `update_deps.py` can be used to relocate the 156 dependent repositories to another arbitrary directory using an absolute or 157 relative path. 158- The `update_deps.py` script generates a file named `helper.cmake` and places 159 it in the same directory as the dependent repositories (`build` in this 160 case). This file contains CMake commands to set the CMake `*_INSTALL_DIR` 161 variables that are used to point to the install artifacts of the dependent 162 repositories. You can use this file with the `cmake -C` option to set these 163 variables when you generate your build files with CMake. This lets you avoid 164 entering several `*_INSTALL_DIR` variable settings on the CMake command line. 165- If using "MINGW" (Git For Windows), you may wish to run 166 `winpty update_deps.py` in order to avoid buffering all of the script's 167 "print" output until the end and to retain the ability to interrupt script 168 execution. 169- Please use `update_deps.py --help` to list additional options and read the 170 internal documentation in `update_deps.py` for further information. 171 172 173#### Automatically 174 175On the other hand, if you choose to let the CMake scripts do all the 176heavy-lifting, you may just trigger the following CMake commands: 177 178``` 179 cmake -S. -Bbuild -DUPDATE_DEPS=On 180 cmake --build build 181``` 182 183##### Notes About the Automatic Option 184 185- You may need to adjust some of the CMake options based on your platform. See 186 the platform-specific sections later in this document. 187- The `build` directory is also being used to build this 188 (Vulkan-ValidationLayers) repository. But there shouldn't be any conflicts 189 inside the `build` directory between the dependent repositories and the 190 build files for this repository. 191 192 193### Generated source code 194 195This repository contains generated source code in the `loader/generated` 196directory which is not intended to be modified directly. Instead, changes should be 197made to the corresponding generator in the `scripts` directory. The source files can 198then be regenerated using `scripts/generate_source.py`: 199 200 python3 scripts/generate_source.py PATH_TO_VULKAN_HEADERS_REGISTRY_DIR 201 202A helper CMake target `VulkanLoader_generated_source` is also provided to simplify 203the invocation of `scripts/generate_source.py` from the build directory: 204 205 cmake --build . --target VulkanLoader_generated_source 206 207### Build Options 208 209When generating native platform build files through CMake, several options can 210be specified to customize the build. Some of the options are binary on/off 211options, while others take a string as input. The following is a table of all 212on/off options currently supported by this repository: 213 214| Option | Platform | Default | Description | 215| ---------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 216| BUILD_TESTS | All | `OFF` | Controls whether or not the loader tests are built. | 217| 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. | 218| 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. | 219| 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. | 220| BUILD_WSI_DIRECTFB_SUPPORT | Linux | `OFF` | Build the loader with the DirectFB entry points enabled. Without this, the DirectFB headers should not be needed, but the extension `VK_EXT_directfb_surface` won't be available. | 221| BUILD_WSI_SCREEN_QNX_SUPPORT | QNX | `OFF` | Build the loader with the QNX Screen entry points enabled. Without this the extension `VK_QNX_screen_surface` won't be available. | 222| 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. | 223| USE_CCACHE | Linux | `OFF` | Enable caching with the CCache program. | 224| USE_GAS | Linux | `ON` | Controls whether to build assembly files with the GNU assembler, else fallback to C code. | 225| USE_MASM | Windows | `ON` | Controls whether to build assembly files with MS assembler, else fallback to C code | 226| BUILD_STATIC_LOADER | macOS | `OFF` | This allows the loader to be built as a static library on macOS. Not tested, use at your own risk. | 227The following is a table of all string options currently supported by this repository: 228 229| Option | Platform | Default | Description | 230| --------------------------- | ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | 231| CMAKE_OSX_DEPLOYMENT_TARGET | MacOS | `10.12` | The minimum version of MacOS for loader deployment. | 232| 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. | 233| 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. | 234| BUILD_DLL_VERSIONINFO | Windows | `""` (empty string) | Allows setting the Windows specific version information for the Loader DLL. Format is "major.minor.patch.build". | 235 236These variables should be set using the `-D` option when invoking CMake to generate the native platform files. 237 238## Building On Windows 239 240### Windows Development Environment Requirements 241 242- Windows 243 - Any Personal Computer version supported by Microsoft 244- Microsoft [Visual Studio](https://www.visualstudio.com/) 245 - Versions 246 - [2015](https://www.visualstudio.com/vs/older-downloads/) 247 - [2017](https://www.visualstudio.com/vs/older-downloads/) 248 - [2019](https://www.visualstudio.com/vs/downloads/) 249 - The Community Edition of each of the above versions is sufficient, as 250 well as any more capable edition. 251- [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-win64-x64.zip) is recommended. 252 - Use the installer option to add CMake to the system PATH 253- Git Client Support 254 - [Git for Windows](http://git-scm.com/download/win) is a popular solution 255 for Windows 256 - Some IDEs (e.g., [Visual Studio](https://www.visualstudio.com/), 257 [GitHub Desktop](https://desktop.github.com/)) have integrated 258 Git client support 259 260### Windows Build - Microsoft Visual Studio 261 262The general approach is to run CMake to generate the Visual Studio project 263files. Then either run CMake with the `--build` option to build from the 264command line or use the Visual Studio IDE to open the generated solution and 265work with the solution interactively. 266 267#### Windows Quick Start 268 269Open a developer command prompt and enter: 270 271 cd Vulkan-Loader 272 mkdir build 273 cd build 274 cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir .. 275 cmake --build . 276 277The above commands instruct CMake to find and use the default Visual Studio 278installation to generate a Visual Studio solution and projects for the x64 279architecture. The second CMake command builds the Debug (default) 280configuration of the solution. 281 282Note that if you do not wish to use a developer command prompt, you may either 283run either `vcvars64.bat` or `vcvars32.bat` to set the required environment 284variables. 285 286#### Use `CMake` to Create the Visual Studio Project Files 287 288Change your current directory to the top of the cloned repository directory, 289create a build directory and generate the Visual Studio project files: 290 291 cd Vulkan-Loader 292 mkdir build 293 cd build 294 cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir .. 295 296> Note: The `..` parameter tells `cmake` the location of the top of the 297> repository. If you place your build directory someplace else, you'll need to 298> specify the location of the repository top differently. 299 300The `-A` option is used to select either the "Win32" or "x64" architecture. 301 302If a generator for a specific version of Visual Studio is required, you can 303specify it for Visual Studio 2015, for example, with: 304 305 64-bit: -G "Visual Studio 14 2015 Win64" 306 32-bit: -G "Visual Studio 14 2015" 307 308See this [list](#cmake-visual-studio-generators) of other possible generators 309for Visual Studio. 310 311When generating the project files, the absolute path to a Vulkan-Headers 312install directory must be provided. This can be done by setting the 313`VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the 314`VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In 315either case, the variable should point to the installation directory of a 316Vulkan-Headers repository built with the install target. 317 318The above steps create a Windows solution file named `Vulkan-Loader.sln` in 319the build directory. 320 321At this point, you can build the solution from the command line or open the 322generated solution with Visual Studio. 323 324#### Build the Solution From the Command Line 325 326While still in the build directory: 327 328 cmake --build . 329 330to build the Debug configuration (the default), or: 331 332 cmake --build . --config Release 333 334to make a Release build. 335 336#### Build the Solution With Visual Studio 337 338Launch Visual Studio and open the "Vulkan-Loader.sln" solution file in the 339build folder. You may select "Debug" or "Release" from the Solution 340Configurations drop-down list. Start a build by selecting the Build->Build 341Solution menu item. 342 343#### Windows Install Target 344 345The CMake project also generates an "install" target that you can use to copy 346the primary build artifacts to a specific location using a "bin, include, lib" 347style directory structure. This may be useful for collecting the artifacts and 348providing them to another project that is dependent on them. 349 350The default location is `$CMAKE_BINARY_DIR\install`, but can be changed with 351the `CMAKE_INSTALL_PREFIX` variable when first generating the project build 352files with CMake. 353 354You can build the install target from the command line with: 355 356 cmake --build . --config Release --target install 357 358or build the `INSTALL` target from the Visual Studio solution explorer. 359 360### Windows Tests 361 362The Vulkan-Loader repository contains some simple unit tests for the loader 363but no other test clients. 364 365To run the loader test script, open a Powershell Console, change to the 366`build\tests` directory, and run: 367 368For Release builds: 369 370 .\run_all_tests.ps1 371 372For Debug builds: 373 374 .\run_all_tests.ps1 -Debug 375 376This script will run the following tests: 377 378- `vk_loader_validation_tests`: 379 Vulkan loader handle wrapping, allocation callback, and loader/layer interface tests 380 381You can also change to either `build\tests\Debug` or `build\tests\Release` 382(depending on which one you built) and run the executable tests (`*.exe`) 383files from there. 384 385### Windows Notes 386 387#### CMake Visual Studio Generators 388 389The chosen generator should match one of the Visual Studio versions that you 390have installed. Generator strings that correspond to versions of Visual Studio 391include: 392 393| Build Platform | 64-bit Generator | 32-bit Generator | 394| ---------------------------- | ----------------------------- | ----------------------- | 395| Microsoft Visual Studio 2015 | "Visual Studio 14 2015 Win64" | "Visual Studio 14 2015" | 396| Microsoft Visual Studio 2017 | "Visual Studio 15 2017 Win64" | "Visual Studio 15 2017" | 397| Microsoft Visual Studio 2019 | "Visual Studio 16 2019" | "Visual Studio 16 2019" | 398 399Note that with Visual Studio 2019, the architecture will need to be specified with the `-A` 400flag for 64-bit builds. 401 402#### Using The Vulkan Loader Library in this Repository on Windows 403 404Vulkan programs must be able to find and use the Vulkan loader 405(`vulkan-1.dll`) library as well as any other libraries the program requires. 406One convenient way to do this is to copy the required libraries into the same 407directory as the program. The projects in this solution copy the Vulkan loader 408library and the "googletest" libraries to the `build\tests\Debug` or the 409`build\tests\Release` directory, which is where the 410`vk_loader_validation_test.exe` executable is found, depending on what 411configuration you built. (The loader validation tests use the "googletest" 412testing framework.) 413 414Other techniques include placing the library in a system folder 415(C:\Windows\System32) or in a directory that appears in the `PATH` environment 416variable. 417 418See the `LoaderAndLayerInterface` document in the `loader` folder in this 419repository for more information on how the loader finds driver libraries and 420layer libraries. The document also describes both how ICDs and layers should 421be packaged, and how developers can point to ICDs and layers within their 422builds. 423 424## Building On Linux 425 426### Linux Development Environment Requirements 427 428This repository has been built and tested on the two most recent Ubuntu LTS 429versions. Currently, the oldest supported version is Ubuntu 16.04, meaning 430that the minimum officially supported C++11 compiler version is GCC 5.4.0, 431although earlier versions may work. It should be straightforward to adapt this 432repository to other Linux distributions. 433 434[CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Linux-x86_64.tar.gz) is recommended. 435 436#### Required Package List 437 438 sudo apt-get install git build-essential libx11-xcb-dev \ 439 libxkbcommon-dev libwayland-dev libxrandr-dev 440 441### Linux Build 442 443The general approach is to run CMake to generate make files. Then either run 444CMake with the `--build` option or `make` to build from the command line. 445 446#### Linux Quick Start 447 448 cd Vulkan-Loader 449 mkdir build 450 cd build 451 cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir .. 452 make 453 454See below for the details. 455 456#### Use CMake to Create the Make Files 457 458Change your current directory to the top of the cloned repository directory, 459create a build directory and generate the make files. 460 461 cd Vulkan-Loader 462 mkdir build 463 cd build 464 cmake -DCMAKE_BUILD_TYPE=Debug \ 465 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \ 466 -DCMAKE_INSTALL_PREFIX=install .. 467 468> Note: The `..` parameter tells `cmake` the location of the top of the 469> repository. If you place your `build` directory someplace else, you'll need 470> to specify the location of the repository top differently. 471 472Use `-DCMAKE_BUILD_TYPE` to specify a Debug or Release build. 473 474When generating the project files, the absolute path to a Vulkan-Headers 475install directory must be provided. This can be done by setting the 476`VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the 477`VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In 478either case, the variable should point to the installation directory of a 479Vulkan-Headers repository built with the install target. 480 481> Note: For Linux, the default value for `CMAKE_INSTALL_PREFIX` is 482> `/usr/local`, which would be used if you do not specify 483> `CMAKE_INSTALL_PREFIX`. In this case, you may need to use `sudo` to install 484> to system directories later when you run `make install`. 485 486#### Build the Project 487 488You can just run `make` to begin the build. 489 490To speed up the build on a multi-core machine, use the `-j` option for `make` 491to specify the number of cores to use for the build. For example: 492 493 make -j4 494 495You can also use 496 497 cmake --build . 498 499If your build system supports ccache, you can enable that via CMake option 500`-DUSE_CCACHE=On` 501 502### Linux Notes 503 504#### Using The Vulkan Loader Library in this Repository on Linux 505 506The `vk_loader_validation_tests` executable is linked with an RPATH setting to 507allow it to find the Vulkan loader library in the repository's build 508directory. This allows the test executable to run and find this Vulkan loader 509library without installing the loader library to a directory searched by the 510system loader or in the `LD_LIBRARY_PATH`. 511 512If you want to test a Vulkan application that is not built within this 513repository with the loader you just built from this repository, you can direct 514the application to load it from your build directory: 515 516 export LD_LIBRARY_PATH=<path to your repository root>/build/loader 517 518#### WSI Support Build Options 519 520By default, the Vulkan Loader is built with support for the Vulkan-defined WSI 521display servers: Xcb, Xlib, and Wayland. It is recommended to build the 522repository components with support for these display servers to maximize their 523usability across Linux platforms. If it is necessary to build these modules 524without support for one of the display servers, the appropriate CMake option 525of the form `BUILD_WSI_xxx_SUPPORT` can be set to `OFF`. 526 527#### Linux Install to System Directories 528 529Installing the files resulting from your build to the systems directories is 530optional since environment variables can usually be used instead to locate the 531binaries. There are also risks with interfering with binaries installed by 532packages. If you are certain that you would like to install your binaries to 533system directories, you can proceed with these instructions. 534 535Assuming that you've built the code as described above and the current 536directory is still `build`, you can execute: 537 538 sudo make install 539 540This command installs files to `/usr/local` if no `CMAKE_INSTALL_PREFIX` is 541specified when creating the build files with CMake: 542 543- `/usr/local/lib`: Vulkan loader library and package config files 544 545You may need to run `ldconfig` in order to refresh the system loader search 546cache on some Linux systems. 547 548You can further customize the installation location by setting additional 549CMake variables to override their defaults. For example, if you would like to 550install to `/tmp/build` instead of `/usr/local`, on your CMake command line 551specify: 552 553 -DCMAKE_INSTALL_PREFIX=/tmp/build 554 555Then run `make install` as before. The install step places the files in 556`/tmp/build`. This may be useful for collecting the artifacts and providing 557them to another project that is dependent on them. 558 559Using the `CMAKE_INSTALL_PREFIX` to customize the install location also 560modifies the loader search paths to include searching for layers in the 561specified install location. In this example, setting `CMAKE_INSTALL_PREFIX` to 562`/tmp/build` causes the loader to search 563`/tmp/build/etc/vulkan/explicit_layer.d` and 564`/tmp/build/share/vulkan/explicit_layer.d` for the layer JSON files. The 565loader also searches the "standard" system locations of 566`/etc/vulkan/explicit_layer.d` and `/usr/share/vulkan/explicit_layer.d` after 567searching the two locations under `/tmp/build`. 568 569You can further customize the installation directories by using the CMake 570variables `CMAKE_INSTALL_SYSCONFDIR` to rename the `etc` directory and 571`CMAKE_INSTALL_DATADIR` to rename the `share` directory. 572 573See the CMake documentation for more details on using these variables to 574further customize your installation. 575 576Also see the `LoaderAndLayerInterface` document in the `loader` folder in this 577repository for more information about loader operation. 578 579Note that some executables in this repository (e.g., 580`vk_loader_validation_tests`) use the RPATH linker directive to load the 581Vulkan loader from the build directory, `build` in this example. This means 582that even after installing the loader to the system directories, these 583executables still use the loader from the build directory. 584 585#### Linux Uninstall 586 587To uninstall the files from the system directories, you can execute: 588 589 sudo make uninstall 590 591#### Linux Tests 592 593The Vulkan-Loader repository contains some simple unit tests for the loader 594but no other test clients. 595 596To run the loader test script, change to the `build/tests` directory, and run: 597 598 ./run_all_tests.sh 599 600This script will run the following tests: 601 602- `vk_loader_validation_tests`: Vulkan loader handle wrapping, allocation 603 callback, and loader/layer interface tests 604 605#### Linux 32-bit support 606 607Usage of this repository's contents in 32-bit Linux environments is not 608officially supported. However, since this repository is supported on 32-bit 609Windows, these modules should generally work on 32-bit Linux. 610 611Here are some notes for building 32-bit targets on a 64-bit Ubuntu "reference" 612platform: 613 614If not already installed, install the following 32-bit development libraries: 615 616`gcc-multilib g++-multilib libx11-dev:i386` 617 618This list may vary depending on your distribution and which windowing systems 619you are building for. 620 621Set up your environment for building 32-bit targets: 622 623 export ASFLAGS=--32 624 export CFLAGS=-m32 625 export CXXFLAGS=-m32 626 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu 627 628Again, your PKG_CONFIG configuration may be different, depending on your 629distribution. 630 631Finally, rebuild the repository using `cmake` and `make`, as explained above. 632 633## Building on MacOS 634 635### MacOS Development Environment Requirements 636 637Tested on OSX version 10.12.6 638 639Setup Homebrew and components 640 641- Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed. 642 643 /usr/bin/ruby -e "$(curl -fsSL \ 644 https://raw.githubusercontent.com/Homebrew/install/master/install)" 645 646- Ensure Homebrew is at the beginning of your PATH: 647 648 export PATH=/usr/local/bin:$PATH 649 650- Add packages with the following (may need refinement) 651 652 brew install python python3 git 653 654### Clone the Repository 655 656Clone the Vulkan-ValidationLayers repository: 657 658 git clone https://github.com/KhronosGroup/Vulkan-ValidationLayers.git 659 660### MacOS build 661 662[CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Darwin-x86_64.tar.gz) is recommended. 663 664#### CMake Generators 665 666This repository uses CMake to generate build or project files that are then 667used to build the repository. The CMake generators explicitly supported in 668this repository are: 669 670- Unix Makefiles 671- Xcode 672 673#### Building with the Unix Makefiles Generator 674 675This generator is the default generator. 676 677When generating the project files, the absolute path to a Vulkan-Headers 678install directory must be provided. This can be done by setting the 679`VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the 680`VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In 681either case, the variable should point to the installation directory of a 682Vulkan-Headers repository built with the install target. 683 684 mkdir build 685 cd build 686 cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir -DCMAKE_BUILD_TYPE=Debug .. 687 make 688 689To speed up the build on a multi-core machine, use the `-j` option for `make` 690to specify the number of cores to use for the build. For example: 691 692 make -j4 693 694#### Building with the Xcode Generator 695 696To create and open an Xcode project: 697 698 mkdir build-xcode 699 cd build-xcode 700 cmake -GXcode .. 701 open Vulkan-Loader.xcodeproj 702 703Within Xcode, you can select Debug or Release builds in the project's Build 704Settings. 705 706### Using the new macOS loader 707 708If you want to test a Vulkan application with the loader you just built, you 709can direct the application to load it from your build directory: 710 711 export DYLD_LIBRARY_PATH=<path to your repository>/build/loader 712 713### MacOS Tests 714 715The Vulkan-Loader repository contains some simple unit tests for the loader 716but no other test clients. 717 718Before you run these tests, you will need to clone and build the 719[MoltenVK](https://github.com/KhronosGroup/MoltenVK) repository. 720 721You will also need to direct your new loader to the MoltenVK ICD: 722 723 export VK_DRIVER_FILES=<path to MoltenVK repository>/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json 724 725To run the loader test script, change to the `build/tests` directory in your 726Vulkan-Loader repository, and run: 727 728 ./vk_loader_validation_tests 729 730## Building on Fuchsia 731 732Fuchsia uses the project's GN build system to integrate with the Fuchsia platform build. 733 734## Building on QNX 735 736QNX is using its own build system. The proper build environment must be set 737under the QNX host development system (Linux, Win64, MacOS) by invoking 738the shell/batch script provided with QNX installation. 739 740Then change working directory to the "build-qnx" in this project and type "make". 741It will build the ICD loader for all CPU targets supported by QNX. 742 743### SDK Symbols 744 745The Vulkan Loader is a component of the Fuchsia SDK, so it must explicitly declare its exported symbols in 746the file vulkan.symbols.api; see [SDK](https://fuchsia.dev/fuchsia-src/development/sdk). 747