build: Add dependency on wayland-protocols
[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 1. [Repository Content](#repository-content)
9 1. [Repository Set-Up](#repository-set-up)
10 1. [Windows Build](#building-on-windows)
11 1. [Linux Build](#building-on-linux)
12 1. [Android Build](#building-on-android)
13 1. [MacOS build](#building-on-macos)
14
15 ## Contributing to the Repository
16
17 If you intend to contribute, the preferred work flow is for you to develop
18 your contribution in a fork of this repository in your GitHub account and then
19 submit a pull request. Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file
20 in this repository for more details.
21
22 ## Repository Content
23
24 This repository contains the source code necessary to build the following components:
25
26 - vulkaninfo
27 - vkcube and vkcubepp demos
28 - mock ICD
29
30 ### Installed Files
31
32 The `install` target installs the following files under the directory
33 indicated by *install_dir*:
34
35 - *install_dir*`/bin` : The vulkaninfo, vkcube and vkcubepp executables
36 - *install_dir*`/lib` : The mock ICD library and JSON (Windows) (If INSTALL_ICD=ON)
37 - *install_dir*`/share/vulkan/icd.d` : mock ICD JSON (Linux/MacOS) (If INSTALL_ICD=ON)
38
39 The `uninstall` target can be used to remove the above files from the install
40 directory.
41
42 ## Repository Set-Up
43
44 ### Display Drivers
45
46 This repository does not contain a Vulkan-capable driver. You will need to
47 obtain and install a Vulkan driver from your graphics hardware vendor or from
48 some other suitable source if you intend to run Vulkan applications.
49
50 ### Download the Repository
51
52 To create your local git repository:
53
54     git clone https://github.com/KhronosGroup/Vulkan-Tools.git
55
56 ### Repository Dependencies
57
58 This repository attempts to resolve some of its dependencies by using
59 components found from the following places, in this order:
60
61 1. CMake or Environment variable overrides (e.g., -DVULKAN_HEADERS_INSTALL_DIR)
62 1. LunarG Vulkan SDK, located by the `VULKAN_SDK` environment variable
63 1. System-installed packages, mostly applicable on Linux
64
65 Dependencies that cannot be resolved by the SDK or installed packages must be
66 resolved with the "install directory" override and are listed below. The
67 "install directory" override can also be used to force the use of a specific
68 version of that dependency.
69
70 #### Vulkan-Headers
71
72 This repository has a required dependency on the
73 [Vulkan Headers repository](https://github.com/KhronosGroup/Vulkan-Headers).
74 You must clone the headers repository and build its `install` target before
75 building this repository. The Vulkan-Headers repository is required because it
76 contains the Vulkan API definition files (registry) that are required to build
77 the mock ICD. You must also take note of the headers install directory and
78 pass it on the CMake command line for building this repository, as described
79 below.
80
81 Note that this dependency can be ignored if not building the mock ICD
82 (CMake option: `-DBUILD_ICD=OFF`).
83
84 #### glslang
85
86 This repository has a required dependency on the `glslangValidator` (shader
87 compiler) for compiling the shader programs for the vkcube demos.
88
89 The CMake code in this repository downloads release binaries of glslang if a
90 build glslang repository is not provided. The glslangValidator is obtained
91 from this set of release binaries.
92
93 If you don't wish the CMake code to download these binaries, then you must
94 clone the [glslang repository](https://github.com/KhronosGroup/glslang) and
95 build its `install` target. Follow the build instructions in the glslang
96 [README.md](https://github.com/KhronosGroup/glslang/blob/master/README.md)
97 file. Ensure that the `update_glslang_sources.py` script has been run as part
98 of building glslang. You must also take note of the glslang install directory
99 and pass it on the CMake command line for building this repository, as
100 described below.
101
102 Note that this dependency can be ignored if not building the vkcube demo
103 (CMake option: `-DBUILD_CUBE=OFF`).
104
105 ### Build and Install Directories
106
107 A common convention is to place the build directory in the top directory of
108 the repository with a name of `build` and place the install directory as a
109 child of the build directory with the name `install`. The remainder of these
110 instructions follow this convention, although you can use any name for these
111 directories and place them in any location.
112
113 ### Building Dependent Repositories with Known-Good Revisions
114
115 There is a Python utility script, `scripts/update_deps.py`, that you can use to
116 gather and build the dependent repositories mentioned above. This script uses
117 information stored in the `scripts/known_good.json` file to check out dependent
118 repository revisions that are known to be compatible with the revision of this
119 repository that you currently have checked out. As such, this script is useful
120 as a quick-start tool for common use cases and default configurations.
121
122 For all platforms, start with:
123
124     git clone git@github.com:KhronosGroup/Vulkan-Tools.git
125     cd Vulkan-Tools
126     mkdir build
127     cd build
128
129 For 64-bit Linux and MacOS, continue with:
130
131     ../scripts/update_deps.py
132     cmake -C helper.cmake ..
133     cmake --build .
134
135 For 64-bit Windows, continue with:
136
137     ..\scripts\update_deps.py --arch x64
138     cmake -A x64 -C helper.cmake ..
139     cmake --build .
140
141 For 32-bit Windows, continue with:
142
143     ..\scripts\update_deps.py --arch Win32
144     cmake -A Win32 -C helper.cmake ..
145     cmake --build .
146
147 Please see the more detailed build information later in this file if you have
148 specific requirements for configuring and building these components.
149
150 #### Notes
151
152 - You may need to adjust some of the CMake options based on your platform. See
153   the platform-specific sections later in this document.
154 - The `update_deps.py` script fetches and builds the dependent repositories in
155   the current directory when it is invoked. In this case, they are built in
156   the `build` directory.
157 - The `build` directory is also being used to build this
158   (Vulkan-Tools) repository. But there shouldn't be any conflicts
159   inside the `build` directory between the dependent repositories and the
160   build files for this repository.
161 - The `--dir` option for `update_deps.py` can be used to relocate the
162   dependent repositories to another arbitrary directory using an absolute or
163   relative path.
164 - The `update_deps.py` script generates a file named `helper.cmake` and places
165   it in the same directory as the dependent repositories (`build` in this
166   case). This file contains CMake commands to set the CMake `*_INSTALL_DIR`
167   variables that are used to point to the install artifacts of the dependent
168   repositories. You can use this file with the `cmake -C` option to set these
169   variables when you generate your build files with CMake. This lets you avoid
170   entering several `*_INSTALL_DIR` variable settings on the CMake command line.
171 - If using "MINGW" (Git For Windows), you may wish to run
172   `winpty update_deps.py` in order to avoid buffering all of the script's
173   "print" output until the end and to retain the ability to interrupt script
174   execution.
175 - Please use `update_deps.py --help` to list additional options and read the
176   internal documentation in `update_deps.py` for further information.
177
178 ### Generated source code
179
180 This repository contains generated source code in the `icd/generated`
181 directory which is not intended to be modified directly. Instead, changes should be
182 made to the corresponding generator in the `scripts` directory. The source files can
183 then be regenerated using `scripts/generate_source.py`:
184
185     python3 scripts/generate_source.py PATH_TO_VULKAN_HEADERS_REGISTRY_DIR
186
187 A helper CMake target `VulkanTools_generated_source` is also provided to simplify
188 the invocation of `scripts/generate_source.py` from the build directory:
189
190     cmake --build . --target VulkanTools_generated_source
191
192 ### Build Options
193
194 When generating native platform build files through CMake, several options can
195 be specified to customize the build. Some of the options are binary on/off
196 options, while others take a string as input. The following is a table of all
197 on/off options currently supported by this repository:
198
199 | Option | Platform | Default | Description |
200 | ------ | -------- | ------- | ----------- |
201 | BUILD_CUBE | All | `ON` | Controls whether or not the vkcube demo is built. |
202 | BUILD_VULKANINFO | All | `ON` | Controls whether or not the vulkaninfo utility is built. |
203 | BUILD_ICD | All | `ON` | Controls whether or not the mock ICD is built. |
204 | INSTALL_ICD | All | `OFF` | Controls whether or not the mock ICD is installed as part of the install target. |
205 | BUILD_WSI_XCB_SUPPORT | Linux | `ON` | Build the components with XCB support. |
206 | BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the components with Xlib support. |
207 | BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the components with Wayland support. |
208 | BUILD_WSI_DIRECTFB_SUPPORT | Linux | `OFF` | Build the components with DirectFB support. |
209 | USE_CCACHE | Linux | `OFF` | Enable caching with the CCache program. |
210
211 The following is a table of all string options currently supported by this repository:
212
213 | Option | Platform | Default | Description |
214 | ------ | -------- | ------- | ----------- |
215 | CMAKE_OSX_DEPLOYMENT_TARGET | MacOS | `10.12` | The minimum version of MacOS for loader deployment. |
216 | VULKANINFO_BUILD_DLL_VERSIONINFO | Windows | `""` | Set the Windows specific version information for Vulkaninfo. Format is "major.minor.patch.build". |
217
218 These variables should be set using the `-D` option when invoking CMake to
219 generate the native platform files.
220
221 ## Building On Windows
222
223 ### Windows Development Environment Requirements
224
225 - Windows
226   - Any Personal Computer version supported by Microsoft
227 - Microsoft [Visual Studio](https://www.visualstudio.com/)
228   - Versions
229     - [2013 (update 4)](https://www.visualstudio.com/vs/older-downloads/)
230     - [2015](https://www.visualstudio.com/vs/older-downloads/)
231     - [2017](https://www.visualstudio.com/vs/downloads/)
232   - The Community Edition of each of the above versions is sufficient, as
233     well as any more capable edition.
234 - [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-win64-x64.zip) is recommended.
235   - Use the installer option to add CMake to the system PATH
236 - Git Client Support
237   - [Git for Windows](http://git-scm.com/download/win) is a popular solution
238     for Windows
239   - Some IDEs (e.g., [Visual Studio](https://www.visualstudio.com/),
240     [GitHub Desktop](https://desktop.github.com/)) have integrated
241     Git client support
242
243 ### Windows Build - Microsoft Visual Studio
244
245 The general approach is to run CMake to generate the Visual Studio project
246 files. Then either run CMake with the `--build` option to build from the
247 command line or use the Visual Studio IDE to open the generated solution and
248 work with the solution interactively.
249
250 #### Windows Quick Start
251
252     cd Vulkan-Tools
253     mkdir build
254     cd build
255     cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir
256     cmake --build .
257
258 The above commands instruct CMake to find and use the default Visual Studio
259 installation to generate a Visual Studio solution and projects for the x64
260 architecture. The second CMake command builds the Debug (default)
261 configuration of the solution.
262
263 See below for the details.
264
265 #### Use `CMake` to Create the Visual Studio Project Files
266
267 Change your current directory to the top of the cloned repository directory,
268 create a build directory and generate the Visual Studio project files:
269
270     cd Vulkan-Tools
271     mkdir build
272     cd build
273     cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir
274
275 > Note: The `..` parameter tells `cmake` the location of the top of the
276 > repository. If you place your build directory someplace else, you'll need to
277 > specify the location of the repository top differently.
278
279 The `-A` option is used to select either the "Win32" or "x64" architecture.
280
281 If a generator for a specific version of Visual Studio is required, you can
282 specify it for Visual Studio 2015, for example, with:
283
284     64-bit: -G "Visual Studio 14 2015 Win64"
285     32-bit: -G "Visual Studio 14 2015"
286
287 See this [list](#cmake-visual-studio-generators) of other possible generators
288 for Visual Studio.
289
290 When generating the project files, the absolute path to a Vulkan-Headers
291 install directory must be provided. This can be done by setting the
292 `VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the
293 `VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In
294 either case, the variable should point to the installation directory of a
295 Vulkan-Headers repository built with the install target.
296
297 The above steps create a Windows solution file named
298 `Vulkan-Tools.sln` in the build directory.
299
300 At this point, you can build the solution from the command line or open the
301 generated solution with Visual Studio.
302
303 #### Build the Solution From the Command Line
304
305 While still in the build directory:
306
307     cmake --build .
308
309 to build the Debug configuration (the default), or:
310
311     cmake --build . --config Release
312
313 to make a Release build.
314
315 #### Build the Solution With Visual Studio
316
317 Launch Visual Studio and open the "Vulkan-Tools.sln" solution file in the
318 build folder. You may select "Debug" or "Release" from the Solution
319 Configurations drop-down list. Start a build by selecting the Build->Build
320 Solution menu item.
321
322 #### Windows Install Target
323
324 The CMake project also generates an "install" target that you can use to copy
325 the primary build artifacts to a specific location using a "bin, include, lib"
326 style directory structure. This may be useful for collecting the artifacts and
327 providing them to another project that is dependent on them.
328
329 The default location is `$CMAKE_BINARY_DIR\install`, but can be changed with
330 the `CMAKE_INSTALL_PREFIX` variable when first generating the project build
331 files with CMake.
332
333 You can build the install target from the command line with:
334
335     cmake --build . --config Release --target install
336
337 or build the `INSTALL` target from the Visual Studio solution explorer.
338
339 #### Using a Loader Built from a Repository
340
341 If you do need to build and use your own loader, build the Vulkan-Loader
342 repository with the install target and modify your CMake invocation to add the
343 location of the loader's install directory:
344
345     cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
346                  -DVULKAN_LOADER_INSTALL_DIR=absolute_path_to_install_dir ..
347
348 #### Using glslang Built from a Repository
349
350 If you do need to build and use your own glslang, build the glslang repository
351 with the install target and modify your CMake invocation to add the location
352 of the glslang's install directory:
353
354     cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
355                  -DGLSLANG_INSTALL_DIR=absolute_path_to_install_dir ..
356
357 ### Windows Notes
358
359 #### CMake Visual Studio Generators
360
361 The chosen generator should match one of the Visual Studio versions that you
362 have installed. Generator strings that correspond to versions of Visual Studio
363 include:
364
365 | Build Platform               | 64-bit Generator              | 32-bit Generator        |
366 |------------------------------|-------------------------------|-------------------------|
367 | Microsoft Visual Studio 2013 | "Visual Studio 12 2013 Win64" | "Visual Studio 12 2013" |
368 | Microsoft Visual Studio 2015 | "Visual Studio 14 2015 Win64" | "Visual Studio 14 2015" |
369 | Microsoft Visual Studio 2017 | "Visual Studio 15 2017 Win64" | "Visual Studio 15 2017" |
370
371 ## Building On Linux
372
373 ### Linux Build Requirements
374
375 This repository has been built and tested on the two most recent Ubuntu LTS
376 versions. Currently, the oldest supported version is Ubuntu 16.04, meaning
377 that the minimum officially supported C++11 compiler version is GCC 5.4.0,
378 although earlier versions may work. It should be straightforward to adapt this
379 repository to other Linux distributions.
380
381 [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Linux-x86_64.tar.gz) is recommended.
382
383 #### Required Package List
384
385     sudo apt-get install git cmake build-essential libx11-xcb-dev \
386         libxkbcommon-dev libwayland-dev libxrandr-dev wayland-protocols
387
388 ### Linux Build
389
390 The general approach is to run CMake to generate make files. Then either run
391 CMake with the `--build` option or `make` to build from the command line.
392
393 #### Linux Quick Start
394
395     cd Vulkan-Tools
396     mkdir build
397     cd build
398     cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir ..
399     make
400
401 See below for the details.
402
403 #### Use CMake to Create the Make Files
404
405 Change your current directory to the top of the cloned repository directory,
406 create a build directory and generate the make files.
407
408     cd Vulkan-Tools
409     mkdir build
410     cd build
411     cmake -DCMAKE_BUILD_TYPE=Debug \
412           -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \
413           -DCMAKE_INSTALL_PREFIX=install ..
414
415 > Note: The `..` parameter tells `cmake` the location of the top of the
416 > repository. If you place your `build` directory someplace else, you'll need
417 > to specify the location of the repository top differently.
418
419 Use `-DCMAKE_BUILD_TYPE` to specify a Debug or Release build.
420
421 When generating the project files, the absolute path to a Vulkan-Headers
422 install directory must be provided. This can be done by setting the
423 `VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the
424 `VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In
425 either case, the variable should point to the installation directory of a
426 Vulkan-Headers repository built with the install target.
427
428 > Note: For Linux, the default value for `CMAKE_INSTALL_PREFIX` is
429 > `/usr/local`, which would be used if you do not specify
430 > `CMAKE_INSTALL_PREFIX`. In this case, you may need to use `sudo` to install
431 > to system directories later when you run `make install`.
432
433 #### Build the Project
434
435 You can just run `make` to begin the build.
436
437 To speed up the build on a multi-core machine, use the `-j` option for `make`
438 to specify the number of cores to use for the build. For example:
439
440     make -j4
441
442 You can also use
443
444     cmake --build .
445
446 If your build system supports ccache, you can enable that via CMake option `-DUSE_CCACHE=On`
447
448 ### Linux Notes
449
450 #### WSI Support Build Options
451
452 By default, the repository components are built with support for the
453 Vulkan-defined WSI display servers: Xcb, Xlib, and Wayland. It is recommended
454 to build the repository components with support for these display servers to
455 maximize their usability across Linux platforms. If it is necessary to build
456 these modules without support for one of the display servers, the appropriate
457 CMake option of the form `BUILD_WSI_xxx_SUPPORT` can be set to `OFF`.
458
459 Note vulkaninfo currently only supports Xcb and Xlib WSI display servers. See
460 the CMakeLists.txt file in `Vulkan-Tools/vulkaninfo` for more info.
461
462 You can select which WSI subsystem is used to execute the vkcube applications
463 using a CMake option called CUBE_WSI_SELECTION. Supported options are XCB
464 (default), XLIB, and WAYLAND. Note that you must build using the corresponding
465 BUILD_WSI_*_SUPPORT enabled at the base repository level. For instance,
466 creating a build that will use Xlib when running the vkcube demos, your CMake
467 command line might look like:
468
469     cmake -DCMAKE_BUILD_TYPE=Debug -DCUBE_WSI_SELECTION=XLIB ..
470
471 #### Linux Install to System Directories
472
473 Installing the files resulting from your build to the systems directories is
474 optional since environment variables can usually be used instead to locate the
475 binaries. There are also risks with interfering with binaries installed by
476 packages. If you are certain that you would like to install your binaries to
477 system directories, you can proceed with these instructions.
478
479 Assuming that you've built the code as described above and the current
480 directory is still `build`, you can execute:
481
482     sudo make install
483
484 This command installs files to `/usr/local` if no `CMAKE_INSTALL_PREFIX` is
485 specified when creating the build files with CMake.
486
487 You may need to run `ldconfig` in order to refresh the system loader search
488 cache on some Linux systems.
489
490 You can further customize the installation location by setting additional
491 CMake variables to override their defaults. For example, if you would like to
492 install to `/tmp/build` instead of `/usr/local`, on your CMake command line
493 specify:
494
495     -DCMAKE_INSTALL_PREFIX=/tmp/build
496
497 Then run `make install` as before. The install step places the files in
498 `/tmp/build`. This may be useful for collecting the artifacts and providing
499 them to another project that is dependent on them.
500
501 Note: The Mock ICD is not installed by default since it is a "null" driver
502 that does not render anything and is used for testing purposes. Installing it
503 to system directories may cause some applications to discover and use this
504 driver instead of other full drivers installed on the system. If you really
505 want to install this null driver, use:
506
507     -DINSTALL_ICD=ON
508
509 See the CMake documentation for more details on using these variables to
510 further customize your installation.
511
512 Also see the `LoaderAndLayerInterface` document in the `loader` folder of the
513 Vulkan-Loader repository for more information about loader and layer
514 operation.
515
516 #### Linux Uninstall
517
518 To uninstall the files from the system directories, you can execute:
519
520     sudo make uninstall
521
522 ### Linux Tests
523
524 After making any changes to the repository, you should perform some quick
525 sanity tests, such as running the vkcube demo with validation enabled.
526
527 To run the **vkcube application** with validation, in a terminal change to the
528 `build/cube` directory and run:
529
530     VK_LAYER_PATH=../path/to/validation/layers ./vkcube --validate
531
532 If you have an SDK installed and have run the setup script to set the
533 `VULKAN_SDK` environment variable, it may be unnecessary to specify a
534 `VK_LAYER_PATH`.
535
536 #### Linux 32-bit support
537
538 Usage of the contents of this repository in 32-bit Linux environments is not
539 officially supported. However, since this repository is supported on 32-bit
540 Windows, these modules should generally work on 32-bit Linux.
541
542 Here are some notes for building 32-bit targets on a 64-bit Ubuntu "reference"
543 platform:
544
545 If not already installed, install the following 32-bit development libraries:
546
547 `gcc-multilib g++-multilib libx11-dev:i386`
548
549 This list may vary depending on your distribution and which windowing systems
550 you are building for.
551
552 Set up your environment for building 32-bit targets:
553
554     export ASFLAGS=--32
555     export CFLAGS=-m32
556     export CXXFLAGS=-m32
557     export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu
558
559 Again, your PKG_CONFIG configuration may be different, depending on your
560 distribution.
561
562 Finally, rebuild the repository using `cmake` and `make`, as explained above.
563
564 ## Building On Android
565
566 Install the required tools for Linux and Windows covered above, then add the
567 following.
568
569 ### Android Build Requirements
570
571 - Install [Android Studio 2.3](https://developer.android.com/studio/index.html) or later.
572 - From the "Welcome to Android Studio" splash screen, add the following components using
573   Configure > SDK Manager:
574   - SDK Platforms > Android 6.0 and newer
575   - SDK Tools > Android SDK Build-Tools
576   - SDK Tools > Android SDK Platform-Tools
577   - SDK Tools > NDK (Side by side)
578
579 #### Add Android specifics to environment
580
581 For each of the below, you may need to specify a different build-tools and ndk
582 versions, as Android Studio will roll them forward fairly regularly.
583
584 On Linux:
585
586     export ANDROID_SDK_HOME=$HOME/Android/sdk
587     export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk/23.0.7599858
588     export PATH=$ANDROID_NDK_HOME:$PATH
589     export PATH=$ANDROID_SDK_HOME/platform-tools:$PATH
590     export PATH=$ANDROID_SDK_HOME/build-tools/31.0.0:$PATH
591
592 On Windows:
593
594     set ANDROID_SDK_HOME=%LOCALAPPDATA%\Android\sdk
595     set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk\23.0.7599858
596     set PATH=%ANDROID_NDK_HOME%;%PATH%
597     set PATH=%ANDROID_SDK_HOME%\platform-tools;%PATH%
598     set PATH=%ANDROID_SDK_HOME%\build-tools\31.0.0;%PATH%
599
600 On OSX:
601
602     export ANDROID_SDK_HOME=$HOME/Library/Android/sdk
603     export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/23.0.7599858
604     export PATH=$ANDROID_NDK_PATH:$PATH
605     export PATH=$ANDROID_SDK_HOME/platform-tools:$PATH
606     export PATH=$ANDROID_SDK_HOME/build-tools/31.0.0:$PATH
607
608 Note: If `jarsigner` is missing from your platform, you can find it in the
609 Android Studio install or in your Java installation. If you do not have Java,
610 you can get it with something like the following:
611
612   sudo apt-get install openjdk-8-jdk
613
614 ### Android Build
615
616 Use the following script to build the vkcube demo for Android:
617
618     cd build-android
619     ./build_all.sh
620
621 The APK can be installed on production devices with:
622
623     ./install_all.sh [-s <serial number>]
624
625 Note that there are no equivalent scripts on Windows yet, that work needs to
626 be completed.
627
628 ### Run vkcube
629
630 Use the following command to run vkcube for Android:
631
632     adb shell am start com.example.VkCube/android.app.NativeActivity
633
634 ## Building on MacOS
635
636 ### MacOS Build Requirements
637
638 Tested on OSX version 10.12.6
639
640 - [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Darwin-x86_64.tar.gz) is recommended.
641
642 Setup Homebrew and components
643
644 - Follow instructions on [brew.sh](http://brew.sh) to get Homebrew installed.
645
646       /usr/bin/ruby -e "$(curl -fsSL \
647           https://raw.githubusercontent.com/Homebrew/install/master/install)"
648
649 - Ensure Homebrew is at the beginning of your PATH:
650
651       export PATH=/usr/local/bin:$PATH
652
653 - Add packages with the following (may need refinement)
654
655       brew install python python3 git
656
657 ### Clone the Repository
658
659 Clone the Vulkan-Tools repository as defined above in the [Download the Repository](#download-the-repository)
660 section.
661
662 ### Get the External Libraries
663
664 [MoltenVK](https://github.com/KhronosGroup/MoltenVK) Library
665
666 - Building the vkcube and vulkaninfo applications require linking to the
667   MoltenVK Library (libMoltenVK.dylib)
668   - The following option should be used on the cmake command line to specify a
669     vulkan loader library: MOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK
670     making sure to specify an absolute path, like so: cmake
671     -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK ....
672
673 Vulkan Loader Library
674
675 - Building the vkcube and vulkaninfo applications require linking to the Vulkan
676   Loader Library (libvulkan.1.dylib)
677   - The following option should be used on the cmake command line to specify a
678     vulkan loader library:
679     VULKAN_LOADER_INSTALL_DIR=/absolute_path_to/Vulkan-Loader_install_dir
680     making sure to specify an absolute path.
681
682 ### MacOS build
683
684 #### CMake Generators
685
686 This repository uses CMake to generate build or project files that are then
687 used to build the repository. The CMake generators explicitly supported in
688 this repository are:
689
690 - Unix Makefiles
691 - Xcode
692
693 #### Building with the Unix Makefiles Generator
694
695 This generator is the default generator, so all that is needed for a debug
696 build is:
697
698         mkdir build
699         cd build
700         cmake -DCMAKE_BUILD_TYPE=Debug \
701               -DVULKAN_LOADER_INSTALL_DIR=/absolute_path_to/Vulkan-Loader_install_dir \
702               -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK \
703               -DCMAKE_INSTALL_PREFIX=install ..
704         make
705
706 To speed up the build on a multi-core machine, use the `-j` option for `make`
707 to specify the number of cores to use for the build. For example:
708
709     make -j4
710
711 You can now run the demo applications from the command line:
712
713     open cube/vkcube.app
714     open cube/vkcubepp.app
715     open vulkaninfo/vulkaninfo.app
716
717 Or you can locate them from `Finder` and launch them from there.
718
719 ##### The Install Target and RPATH
720
721 The applications you just built are "bundled applications", but the
722 executables are using the `RPATH` mechanism to locate runtime dependencies
723 that are still in your build tree.
724
725 To see this, run this command from your `build` directory:
726
727     otool -l cube/cube.app/Contents/MacOS/vkcube
728
729 and note that the `vkcube` executable contains loader commands:
730
731 - `LC_LOAD_DYLIB` to load `libvulkan.1.dylib` via an `@rpath`
732 - `LC_RPATH` that contains an absolute path to the build location of the Vulkan loader
733
734 This makes the bundled application "non-transportable", meaning that it won't
735 run unless the Vulkan loader is on that specific absolute path. This is useful
736 for debugging the loader or other components built in this repository, but not
737 if you want to move the application to another machine or remove your build
738 tree.
739
740 To address this problem, run:
741
742     make install
743
744 This step copies the bundled applications to the location specified by
745 CMAKE_INSTALL_PREFIX and "cleans up" the `RPATH` to remove any external
746 references and performs other bundle fix-ups. After running `make install`,
747 run the `otool` command again from the `build/install` directory and note:
748
749 - `LC_LOAD_DYLIB` is now `@executable_path/../MacOS/libvulkan.1.dylib`
750 - `LC_RPATH` is no longer present
751
752 The "bundle fix-up" operation also puts a copy of the Vulkan loader into the
753 bundle, making the bundle completely self-contained and self-referencing.
754
755 ##### The Non-bundled vulkaninfo Application
756
757 There is also a non-bundled version of the `vulkaninfo` application that you
758 can run from the command line:
759
760     vulkaninfo/vulkaninfo
761
762 If you run this from the build directory, vulkaninfo's RPATH is already
763 set to point to the Vulkan loader in the build tree, so it has no trouble
764 finding it. But the loader will not find the MoltenVK driver and you'll see a
765 message about an incompatible driver. To remedy this:
766
767     VK_ICD_FILENAMES=<path-to>/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json vulkaninfo/vulkaninfo
768
769 If you run `vulkaninfo` from the install directory, the `RPATH` in the
770 `vulkaninfo` application got removed and the OS needs extra help to locate
771 the Vulkan loader:
772
773     DYLD_LIBRARY_PATH=<path-to>/Vulkan-Loader/loader VK_ICD_FILENAMES=<path-to>/MoltenVK/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json vulkaninfo/vulkaninfo
774
775 #### Building with the Xcode Generator
776
777 To create and open an Xcode project:
778
779         mkdir build-xcode
780         cd build-xcode
781         cmake -DVULKAN_LOADER_INSTALL_DIR=/absolute_path_to/Vulkan-Loader_install_dir -DMOLTENVK_REPO_ROOT=/absolute_path_to/MoltenVK -GXcode ..
782         open VULKAN.xcodeproj
783
784 Within Xcode, you can select Debug or Release builds in the project's Build
785 Settings. You can also select individual schemes for working with specific
786 applications like `vkcube`.