docs: More BUILD.md updates
[platform/upstream/Vulkan-Tools.git] / BUILD.md
1 # Build Instructions
2
3 Instructions for building this repository on Linux, Windows, Android, and MacOS.
4
5 ## Index
6
7 1. [Contributing](#contributing-to-the-repository)
8 2. [Repository Set-Up](#repository-set-up)
9 3. [Windows Build](#building-on-windows)
10 4. [Linux Build](#building-on-linux)
11 5. [Android Build](#building-on-android)
12 6. [MacOS build](#building-on-macos)
13
14 ## Contributing to the Repository
15
16 If you intend to contribute, the preferred work flow is for you to develop
17 your contribution in a fork of this repository in your GitHub account and
18 then submit a pull request.
19 Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file in this repository for more details.
20
21 ## Repository Set-Up
22
23 ### Display Drivers
24
25 This repository does not contain a Vulkan-capable driver.
26 Before proceeding, it is strongly recommended that you obtain a Vulkan driver from your
27 graphics hardware vendor and install it properly.
28
29 ### Download the Repository
30
31 To create your local git repository:
32
33     git clone https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers
34
35 ## Building On Windows
36
37 ### Windows Build Requirements
38
39 Windows 7+ with the following software packages:
40
41 - Microsoft Visual Studio 2013 Update 4 Professional, VS2015 (any version), or VS2017 (any version).
42 - [CMake](http://www.cmake.org/download/)
43   - Tell the installer to "Add CMake to the system PATH" environment variable.
44 - [Python 3](https://www.python.org/downloads)
45   - Select to install the optional sub-package to add Python to the system PATH
46     environment variable.
47   - Ensure the `pip` module is installed (it should be by default)
48   - Python3.3 or later is necessary for the Windows py.exe launcher that is used to select python3
49   rather than python2 if both are installed
50 - [Git](http://git-scm.com/download/win)
51   - Tell the installer to allow it to be used for "Developer Prompt" as well as "Git Bash".
52   - Tell the installer to treat line endings "as is" (i.e. both DOS and Unix-style line endings).
53   - Install both the 32-bit and 64-bit versions, as the 64-bit installer does not install the
54     32-bit libraries and tools.
55
56 ### Windows Build - Microsoft Visual Studio
57
58 1. Open a Developer Command Prompt for VS201x
59 2. Change directory to `Vulkan-LoaderAndValidationLayers` -- the root of the cloned git repository
60 3. Run 'git submodule update --init --recursive' -- this will download in-tree external dependencies
61 4. Create a `build` directory, change into that directory, and run cmake
62
63 For example, for VS2017 (generators for other versions are [specified here](#cmake-visual-studio-generators)):
64
65     cmake -G "Visual Studio 15 2017 Win64" ..
66
67 This will create a Windows solution file named `VULKAN.sln` in the build directory.
68
69 Launch Visual Studio and open the "VULKAN.sln" solution file in the build folder.
70 You may select "Debug" or "Release" from the Solution Configurations drop-down list.
71 Start a build by selecting the Build->Build Solution menu item.
72 This solution copies the loader it built to each program's build directory
73 to ensure that the program uses the loader built from this solution.
74
75 ### Windows Tests and Demos
76
77 After making any changes to the repository, you should perform some quick sanity tests,
78 including the run_all_tests Powershell script and the cube demo with validation enabled.
79
80 To run the validation test script, open a Powershell Console,
81 change to the build/tests directory, and run:
82
83 For Release builds:
84
85     .\run_all_tests.ps1
86
87 For Debug builds:
88
89     .\run_all_tests.ps1 -Debug
90
91 This script will run the following tests:
92
93 - `vk_loader_validation_tests`:
94   Vulkan loader handle wrapping, allocation callback, and loader/layer interface tests
95 - `vk_layer_validation_tests`:
96   Test Vulkan validation layers
97 - `vkvalidatelayerdoc`:
98   Tests that validation database is up-to-date and is synchronized with the validation source code
99
100 To run the Cube demo with validation in a Debug build configuration:
101
102 - In the MSVC solution explorer, right-click on the `cube` project and select
103  `Set As Startup Project`
104 - Right click on cube again, select properties->Debugging->Command Arguments, change to
105  `--validate`, and save
106 - From the main menu, select Debug->Start Debugging, or from the toolbar click
107  `Local Windows Debugger`
108
109 Other applications that can be found in the Vulkan-Tools repository are:
110
111 - `vulkaninfo`: Report GPU properties
112
113 ### Windows Notes
114
115 #### CMake Visual Studio Generators
116
117 The above example used Visual Studio 2017, and specified its generator as "Visual Studio 15 2017 Win64".
118 The chosen generator should match your Visual Studio version. Appropriate Visual Studio generators include:
119
120 | Build Platform               | 64-bit Generator              | 32-bit Generator        |
121 |------------------------------|-------------------------------|-------------------------|
122 | Microsoft Visual Studio 2013 | "Visual Studio 12 2013 Win64" | "Visual Studio 12 2013" |
123 | Microsoft Visual Studio 2015 | "Visual Studio 14 2015 Win64" | "Visual Studio 14 2015" |
124 | Microsoft Visual Studio 2017 | "Visual Studio 15 2017 Win64" | "Visual Studio 15 2017" |
125
126 #### The Vulkan Loader Library
127
128 TODO: LOADER_REPO_ROOT
129
130 Vulkan programs must be able to find and use the vulkan-1.dll library.
131 While several of the test and demo projects in the Windows solution set this up automatically, doing so manually may be necessary for custom projects or solutions.
132 Make sure the library is either installed in the C:\Windows\System32 folder, or that the PATH environment variable includes the folder where the library resides.
133
134 ## Building On Linux
135
136 ### Linux Build Requirements
137
138 This repository has been built and tested on the two most recent Ubuntu LTS versions.
139 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.
140 It should be straightforward to adapt this repository to other Linux distributions.
141
142 **Required Package List:**
143
144     sudo apt-get install git cmake build-essential libx11-xcb-dev libxkbcommon-dev libmirclient-dev libwayland-dev libxrandr-dev
145
146 ### Linux Build
147
148 Example debug build
149
150 See **Loader and Validation Layer Dependencies** for more information and other options):
151
152 1. In a Linux terminal, `cd Vulkan-Tools` -- the root of the cloned git repository
153 2. Execute 'git submodule update --init --recursive' -- this will download in-tree external components
154 3. Create a `build` directory, change into that directory, and run cmake:
155
156         mkdir build
157         cd build
158         cmake -DCMAKE_BUILD_TYPE=Debug ..
159
160 4. Run `make -j8` to begin the build
161
162 If your build system supports ccache, you can enable that via CMake option `-DUSE_CCACHE=On`
163
164 #### Using the new loader and layers
165
166     export LD_LIBRARY_PATH=<path to your repository root>/build/loader
167     export VK_LAYER_PATH=<path to your repository root>/build/layers
168
169 You can run the `vulkaninfo` application to see which driver, loader and layers are being used.
170
171 ### WSI Support Build Options
172
173 By default, the Vulkan Tools are built with support for all 4 Vulkan-defined WSI display servers: Xcb, Xlib, Wayland, and Mir.
174 It is recommended to build the repository components with support for these display servers to maximize their usability across Linux platforms.
175 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`.
176 See the top-level CMakeLists.txt file for more info.
177
178 ### Linux Install to System Directories
179
180 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.
181 There are also risks with interfering with binaries installed by packages.
182 If you are certain that you would like to install your binaries to system directories, you can proceed with these instructions.
183
184 Assuming that you have built the code as described above and the current directory is still `build`, you can execute:
185
186     sudo make install
187
188 This command installs files to:
189
190 - `/usr/local/include/vulkan`:  Vulkan include files
191 - `/usr/local/lib`:  Vulkan Tools shared objects
192 - `/usr/local/bin`:  vulkaninfo application
193 - `/usr/local/bin`:  cube application
194 - `/usr/local/bin`:  cubepp application
195
196 You may need to run `ldconfig` in order to refresh the system loader search cache on some Linux systems.
197
198 You can further customize the installation location by setting additional CMake variables to override their defaults.
199 For example, if you would like to install to `/tmp/build` instead of `/usr/local`, on your CMake command line specify:
200
201     -DCMAKE_INSTALL_PREFIX=/tmp/build
202     -DDEST_DIR=/tmp/build
203
204 Then run `make install` as before. The install step places the files in `/tmp/build`.
205
206 You can further customize the installation directories by using the CMake variables
207 `CMAKE_INSTALL_SYSCONFDIR` to rename the `etc` directory and `CMAKE_INSTALL_DATADIR`
208 to rename the `share` directory.
209
210 See the CMake documentation for more details on using these variables
211 to further customize your installation.
212
213 ### Linux Uninstall
214
215 To uninstall the files from the system directories, you can execute:
216
217     sudo make uninstall
218
219 ### Linux Tests
220
221 After making any changes to the repository, you should perform some quick sanity tests, such as
222 running the cube demo with validation enabled.
223
224 To run the **Cube application** with validation, in a terminal change to the `build/cube`
225 directory and run:
226
227     VK_LAYER_PATH=../path/to/validation/layers ./cube --validate
228
229 You can select which WSI subsystem is used to build the cube applications using a CMake option
230 called DEMOS_WSI_SELECTION.
231 Supported options are XCB (default), XLIB, WAYLAND, and MIR.
232 Note that you must build using the corresponding BUILD_WSI_*_SUPPORT enabled at the
233 base repository level (all SUPPORT options are ON by default).
234 For instance, creating a build that will use Xlib to build the demos,
235 your CMake command line might look like:
236
237     cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Debug -DDEMOS_WSI_SELECTION=XLIB
238
239 ### Linux Notes
240
241 #### Linux 32-bit support
242
243 Usage of the contents of this repository in 32-bit Linux environments is not officially supported.
244 However, since this repository is supported on 32-bit Windows,
245 these modules should generally work on 32-bit Linux.
246
247 Here are some notes for building 32-bit targets on a 64-bit Ubuntu "reference" platform:
248
249 If not already installed, install the following 32-bit development libraries:
250
251 `gcc-multilib g++-multilib libx11-dev:i386`
252
253 This list may vary depending on your distribution and which windowing systems you are building for.
254
255 Set up your environment for building 32-bit targets:
256
257     export ASFLAGS=--32
258     export CFLAGS=-m32
259     export CXXFLAGS=-m32
260     export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu
261
262 Again, your PKG_CONFIG configuration may be different, depending on your distribution.
263
264 Finally, rebuild the repository using `cmake` and `make`, as explained above.
265
266 ## Building On Android
267
268 Install the required tools for Linux and Windows covered above, then add the following.
269
270 ### Android Build Requirements
271
272 - Install [Android Studio 2.3](https://developer.android.com/studio/index.html) or later.
273 - From the "Welcome to Android Studio" splash screen, add the following components using
274   Configure > SDK Manager:
275   - SDK Platforms > Android 6.0 and newer
276   - SDK Tools > Android SDK Build-Tools
277   - SDK Tools > Android SDK Platform-Tools
278   - SDK Tools > Android SDK Tools
279   - SDK Tools > NDK
280
281 #### Add Android specifics to environment
282
283 For each of the below, you may need to specify a different build-tools version, as Android Studio will roll it forward fairly regularly.
284
285 On Linux:
286
287     export ANDROID_SDK_HOME=$HOME/Android/sdk
288     export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk-bundle
289     export PATH=$ANDROID_SDK_HOME:$PATH
290     export PATH=$ANDROID_NDK_HOME:$PATH
291     export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
292
293 On Windows:
294
295     set ANDROID_SDK_HOME=%LOCALAPPDATA%\Android\sdk
296     set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk-bundle
297     set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH%
298
299 On OSX:
300
301     export ANDROID_SDK_HOME=$HOME/Library/Android/sdk
302     export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk-bundle
303     export PATH=$ANDROID_NDK_PATH:$PATH
304     export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
305
306 Note: If `jarsigner` is missing from your platform, you can find it in the
307 Android Studio install or in your Java installation.
308 If you do not have Java, you can get it with something like the following:
309
310   sudo apt-get install openjdk-8-jdk
311
312 #### Additional OSX System Requirements
313
314 Tested on OSX version 10.13.3
315
316 Setup Homebrew and components
317
318 - Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
319
320       /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
321
322 - Ensure Homebrew is at the beginning of your PATH:
323
324       export PATH=/usr/local/bin:$PATH
325
326 - Add packages with the following:
327
328       brew install cmake python
329
330 ### Android Build
331
332 There are two options for building the Android tools.
333 Either using the SPIRV tools provided as part of the Android NDK, or using upstream sources.
334 To build with SPIRV tools from the NDK, remove the build-android/third_party directory created by
335 running update_external_sources_android.sh, (or avoid running update_external_sources_android.sh).
336 Use the following script to build everything in the repository for Android, including validation
337 layers, tests, demos, and APK packaging: This script does retrieve and use the upstream SPRIV tools.
338
339     cd build-android
340     ./build_all.sh
341
342 Test and application APKs can be installed on production devices with:
343
344     ./install_all.sh [-s <serial number>]
345
346 Note that there are no equivalent scripts on Windows yet, that work needs to be completed.
347 The following per platform commands can be used for layer only builds:
348
349 #### Linux and OSX
350
351 Follow the setup steps for Linux or OSX above, then from your terminal:
352
353     cd build-android
354     ./update_external_sources_android.sh --no-build
355     ./android-generate.sh
356     ndk-build -j4
357
358 #### Windows
359
360 Follow the setup steps for Windows above, then from Developer Command Prompt for VS2013:
361
362     cd build-android
363     update_external_sources_android.bat
364     android-generate.bat
365     ndk-build
366
367 ### Android Tests and Demos
368
369 After making any changes to the repository you should perform some quick sanity tests,
370 including the layer validation tests and the cube and smoke demos with validation enabled.
371
372 #### Run Layer Validation Tests
373
374 Use the following steps to build, install, and run the layer validation tests for Android:
375
376     cd build-android
377     ./build_all.sh
378     adb install -r bin/VulkanLayerValidationTests.apk
379     adb shell am start com.example.VulkanLayerValidationTests/android.app.NativeActivity
380
381 Alternatively, you can use the test_APK script to install and run the layer validation tests:
382
383     test_APK.sh -s <serial number> -p <plaform name> -f <gtest_filter>
384
385 #### Run Cube with Validation
386
387 TODO: This must be reworked to pull in layers from the ValidationLayers repo
388
389 Use the following steps to build, install, and run Cube for Android:
390
391     cd build-android
392     ./build_all.sh
393     adb install -r ../demos/android/cube/bin/cube.apk
394     adb shell am start com.example.Cube/android.app.NativeActivity
395
396 To build, install, and run Cube with validation layers,
397 first build layers using steps above, then run:
398
399     cd build-android
400     ./build_all.sh
401     adb install -r ../demos/android/cube-with-layers/bin/cube-with-layers.apk
402
403 ##### Run without validation enabled
404
405     adb shell am start com.example.CubeWithLayers/android.app.NativeActivity
406
407 ##### Run with validation enabled
408
409     adb shell am start -a android.intent.action.MAIN -c android-intent.category.LAUNCH -n com.example.CubeWithLayers/android.app.NativeActivity --es args "--validate"
410
411 ## Building on MacOS
412
413 ### MacOS Build Requirements
414
415 Tested on OSX version 10.12.6
416
417 Setup Homebrew and components
418
419 - Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
420
421       /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
422
423 - Ensure Homebrew is at the beginning of your PATH:
424
425       export PATH=/usr/local/bin:$PATH
426
427 - Add packages with the following (may need refinement)
428
429       brew install cmake python python3 git
430
431 ### Clone the Repository
432
433 Clone the Vulkan-LoaderAndValidationLayers repository:
434
435     git clone https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers.git
436
437 ### Get the External Libraries
438
439 TODO: Update with macOS procedure for satisfying external dependencies
440
441 ### MacOS build
442
443 #### CMake Generators
444
445 This repository uses CMake to generate build or project files that are
446 then used to build the repository.
447 The CMake generators explicitly supported in this repository are:
448
449 - Unix Makefiles
450 - Xcode
451
452 #### Building with the Unix Makefiles Generator
453
454 This generator is the default generator, so all that is needed for a debug
455 build is:
456
457         mkdir build
458         cd build
459         cmake -DCMAKE_BUILD_TYPE=Debug ..
460         make
461
462 To speed up the build on a multi-core machine, use the `-j` option for `make`
463 to specify the number of cores to use for the build.
464 For example:
465
466     make -j4
467
468 You can now run the demo applications from the command line:
469
470     open demos/cube.app
471     open demos/cubepp.app
472     open demos/vulkaninfo.app
473
474 Or you can locate them from `Finder` and launch them from there.
475
476 ##### The Install Target and RPATH
477
478 The applications you just built are "bundled applications", but the executables
479 are using the `RPATH` mechanism to locate runtime dependencies that are still
480 in your build tree.
481
482 To see this, run this command from your `build` directory:
483
484     otool -l demos/cube.app/Contents/MacOS/cube
485
486 and note that the `cube` executable contains loader commands:
487
488 - `LC_LOAD_DYLIB` to load `libvulkan.1.dylib` via an `@rpath`
489 - `LC_RPATH` that contains an absolute path to the build location of the Vulkan loader
490
491 This makes the bundled application "non-transportable", meaning that it won't run
492 unless the Vulkan loader is on that specific absolute path.
493 This is useful for debugging the loader or other components built in this repository,
494 but not if you want to move the application to another machine or remove your build tree.
495
496 To address this problem, run:
497
498     make install
499
500 This step "cleans up" the `RPATH` to remove any external references
501 and performs other bundle fix-ups.
502 After running `make install`, re-run the `otool` command again and note:
503
504 - `LC_LOAD_DYLIB` is now `@executable_path/../MacOS/libvulkan.1.dylib`
505 - `LC_RPATH` is no longer present
506
507 The "bundle fix-up" operation also puts a copy of the Vulkan loader into the bundle,
508 making the bundle completely self-contained and self-referencing.
509
510 Note that the "install" target has a very different meaning compared to the Linux
511 "make install" target.
512 The Linux "install" copies the targets to system directories.
513 In MacOS, "install" means fixing up application bundles.
514 In both cases, the "install" target operations clean up the `RPATH`.
515
516 ##### The Non-bundled vulkaninfo Application
517
518 There is also a non-bundled version of the `vulkaninfo` application that you can
519 run from the command line:
520
521     demos/vulkaninfo
522
523 If you run this before you run "make install", vulkaninfo's RPATH is already set
524 to point to the Vulkan loader in the build tree, so it has no trouble finding it.
525 But the loader will not find the MoltenVK driver and you'll see a message about an
526 incompatible driver.  To remedy this:
527
528     VK_ICD_FILENAMES=../external/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json demos/vulkaninfo
529
530 If you run `vulkaninfo` after doing a "make install", the `RPATH` in the `vulkaninfo` application
531 got removed and the OS needs extra help to locate the Vulkan loader:
532
533     DYLD_LIBRARY_PATH=loader VK_ICD_FILENAMES=../external/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json demos/vulkaninfo
534
535 #### Building with the Xcode Generator
536
537 To create and open an Xcode project:
538
539         mkdir build-xcode
540         cd build-xcode
541         cmake -GXcode ..
542         open VULKAN.xcodeproj
543
544 Within Xcode, you can select Debug or Release builds in the project's Build Settings.
545 You can also select individual schemes for working with specific applications like `cube`.
546
547 ## Ninja Builds - All Platforms
548
549 The [Qt Creator IDE](https://qt.io/download-open-source/#section-2) can open a root CMakeList.txt
550 as a project directly, and it provides tools within Creator to configure and generate Vulkan SDK
551 build files for one to many targets concurrently.
552 Alternatively, when invoking CMake, use the `-G "Codeblocks - Ninja"` option to generate Ninja build
553 files to be used as project files for QtCreator
554
555 - Open, configure, and build the glslang CMakeList.txt files. Note that building the glslang
556   project will provide access to spirv-tools and spirv-headers
557 - Then do the same with the Vulkan-LoaderAndValidationLayers CMakeList.txt file
558 - In order to debug with QtCreator, a
559   [Microsoft WDK: eg WDK 10](http://go.microsoft.com/fwlink/p/?LinkId=526733) is required.
560
561 Note that installing the WDK breaks the MSVC vcvarsall.bat build scripts provided by MSVC,
562 requiring that the LIB, INCLUDE, and PATHenv variables be set to the WDK paths by some other means
563
564 ## Vulkan-Tools Dependencies
565
566 The glslang repository is required to build and run Vulkan Tools components.
567 It is not a git sub-module of Vulkan-Tools, but glslang components are required to build
568 the cube and vulkaninfo applications.
569
570 If an existing glslang repository installation is unavailable, do the following steps:
571
572 1) clone the repository:
573
574     `git clone https://github.com/KhronosGroup/glslang.git`
575
576 2) Configure the glslang source tree with CMake and build it with your IDE of choice
577
578 3) Pass the location of the glslang repository via your cmake command like so:
579
580     cmake -DGLSLANG_REPO_ROOT=c:\development\glslang
581
582 4) If building on Windows with MSVC, set `DISABLE_BUILDTGT_DIR_DECORATION` to _On_.
583  If building on Windows, but without MSVC set `DISABLE_BUILD_PATH_DECORATION` to _On_
584
585 ## Optional software packages
586
587 - [Cygwin for windows](https://www.cygwin.com/)
588   - Cygwin provides some Linux-like tools, which can be valuable for working with the repository,
589     such as the BASH shell and git packages
590   - With appropriate adjustments, it is possible to use other shells and environments as well
591
592 - [Ninja on all platforms](https://github.com/ninja-build/ninja/releases)
593 - [The Ninja-build project](https://ninja-build.org)
594 - [Ninja Users Manual](https://ninja-build.org/manual.html)
595
596 - [QtCreator as IDE for CMake builds on all platforms](https://qt.io/download-open-source/#section-2)