projects / platform / upstream / Vulkan-Tools.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
github: Use main instead of master
[platform/upstream/Vulkan-Tools.git] / BUILD.md
diff --git a/BUILD.md b/BUILD.md
index 6461bc3..f5d16b2 100644 (file)
--- a/BUILD.md
+++ b/BUILD.md
@@ -93,7 +93,7 @@ from this set of release binaries.
 If you don't wish the CMake code to download these binaries, then you must
 clone the [glslang repository](https://github.com/KhronosGroup/glslang) and
 build its `install` target. Follow the build instructions in the glslang
-[README.md](https://github.com/KhronosGroup/glslang/blob/master/README.md)
+[README.md](https://github.com/KhronosGroup/glslang/blob/main/README.md)
 file. Ensure that the `update_glslang_sources.py` script has been run as part
 of building glslang. You must also take note of the glslang install directory
 and pass it on the CMake command line for building this repository, as
@@ -206,17 +206,54 @@ on/off options currently supported by this repository:
 | BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the components with Xlib support. |
 | BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the components with Wayland support. |
 | BUILD_WSI_DIRECTFB_SUPPORT | Linux | `OFF` | Build the components with DirectFB support. |
-| 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. |
+| VULKANINFO_BUILD_DLL_VERSIONINFO | Windows | `""` | Set the Windows specific version information for Vulkaninfo. Format is "major.minor.patch.build". |
 
 These variables should be set using the `-D` option when invoking CMake to
 generate the native platform files.
 
+### CCACHE
+
+There are 2 methods to enable CCACHE:
+
+1.) Set environment variables
+
+```bash
+# Requires CMake 3.17 (https://cmake.org/cmake/help/latest/envvar/CMAKE_LANG_COMPILER_LAUNCHER.html)
+export CMAKE_CXX_COMPILER_LAUNCHER=/usr/bin/ccache
+export CMAKE_C_COMPILER_LAUNCHER=/usr/bin/ccache
+```
+
+2.) Pass in cache variables
+
+```
+cmake ... -D CMAKE_CXX_COMPILER_LAUNCHER=/usr/bin/ccache -D CMAKE_C_COMPILER_LAUNCHER=/usr/bin/ccache
+```
+
+### EXPORT_COMPILE_COMMANDS
+
+There are 2 methods to enable exporting compile commands:
+
+1.) Set environment variables
+
+```bash
+# Requires CMake 3.17 (https://cmake.org/cmake/help/latest/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.html)
+export CMAKE_EXPORT_COMPILE_COMMANDS=ON
+```
+
+2.) Pass in cache variables
+
+```
+cmake ... -D CMAKE_EXPORT_COMPILE_COMMANDS=ON
+```
+
+NOTE: Modern tools will generally enable exporting compile commands for you (e.g. VSCode).
+Also `CMAKE_EXPORT_COMPILE_COMMANDS` is implemented only by Makefile and Ninja generators. For other generators, this option is ignored.
+
 ## Building On Windows
 
 ### Windows Development Environment Requirements
@@ -382,7 +419,7 @@ repository to other Linux distributions.
 #### Required Package List
 
     sudo apt-get install git cmake build-essential libx11-xcb-dev \
-        libxkbcommon-dev libwayland-dev libxrandr-dev
+        libxkbcommon-dev libwayland-dev libxrandr-dev wayland-protocols
 
 ### Linux Build
 
@@ -459,13 +496,13 @@ Note vulkaninfo currently only supports Xcb and Xlib WSI display servers. See
 the CMakeLists.txt file in `Vulkan-Tools/vulkaninfo` for more info.
 
 You can select which WSI subsystem is used to execute the vkcube applications
-using a CMake option called DEMOS_WSI_SELECTION. Supported options are XCB
+using a CMake option called CUBE_WSI_SELECTION. Supported options are XCB
 (default), XLIB, and WAYLAND. Note that you must build using the corresponding
 BUILD_WSI_*_SUPPORT enabled at the base repository level. For instance,
 creating a build that will use Xlib when running the vkcube demos, your CMake
 command line might look like:
 
-    cmake -DCMAKE_BUILD_TYPE=Debug -DDEMOS_WSI_SELECTION=XLIB ..
+    cmake -DCMAKE_BUILD_TYPE=Debug -DCUBE_WSI_SELECTION=XLIB ..
 
 #### Linux Install to System Directories
 
@@ -573,34 +610,36 @@ following.
   - SDK Platforms > Android 6.0 and newer
   - SDK Tools > Android SDK Build-Tools
   - SDK Tools > Android SDK Platform-Tools
-  - SDK Tools > Android SDK Tools
-  - SDK Tools > NDK
+  - SDK Tools > NDK (Side by side)
 
 #### Add Android specifics to environment
 
-For each of the below, you may need to specify a different build-tools
-version, as Android Studio will roll it forward fairly regularly.
+For each of the below, you may need to specify a different build-tools and ndk
+versions, as Android Studio will roll them forward fairly regularly.
 
 On Linux:
 
     export ANDROID_SDK_HOME=$HOME/Android/sdk
-    export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk-bundle
-    export PATH=$ANDROID_SDK_HOME:$PATH
+    export ANDROID_NDK_HOME=$HOME/Android/sdk/ndk/23.0.7599858
     export PATH=$ANDROID_NDK_HOME:$PATH
-    export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
+    export PATH=$ANDROID_SDK_HOME/platform-tools:$PATH
+    export PATH=$ANDROID_SDK_HOME/build-tools/31.0.0:$PATH
 
 On Windows:
 
     set ANDROID_SDK_HOME=%LOCALAPPDATA%\Android\sdk
-    set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk-bundle
-    set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH%
+    set ANDROID_NDK_HOME=%LOCALAPPDATA%\Android\sdk\ndk\23.0.7599858
+    set PATH=%ANDROID_NDK_HOME%;%PATH%
+    set PATH=%ANDROID_SDK_HOME%\platform-tools;%PATH%
+    set PATH=%ANDROID_SDK_HOME%\build-tools\31.0.0;%PATH%
 
 On OSX:
 
     export ANDROID_SDK_HOME=$HOME/Library/Android/sdk
-    export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk-bundle
+    export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/23.0.7599858
     export PATH=$ANDROID_NDK_PATH:$PATH
-    export PATH=$ANDROID_SDK_HOME/build-tools/23.0.3:$PATH
+    export PATH=$ANDROID_SDK_HOME/platform-tools:$PATH
+    export PATH=$ANDROID_SDK_HOME/build-tools/31.0.0:$PATH
 
 Note: If `jarsigner` is missing from your platform, you can find it in the
 Android Studio install or in your Java installation. If you do not have Java,
@@ -608,128 +647,36 @@ you can get it with something like the following:
 
   sudo apt-get install openjdk-8-jdk
 
-#### Additional OSX System Requirements
-
-Tested on OSX version 10.13.3
-
-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)"
-
-- Ensure Homebrew is at the beginning of your PATH:
-
-      export PATH=/usr/local/bin:$PATH
-
-- Add packages with the following:
-
-      brew install python
-
 ### Android Build
 
-There are two options for building the Android tools. Either using the SPIRV
-tools provided as part of the Android NDK, or using upstream sources. To build
-with SPIRV tools from the NDK, remove the build-android/third_party directory
-created by running update_external_sources_android.sh, (or avoid running
-update_external_sources_android.sh). Use the following script to build
-everything in the repository for Android, including validation layers, tests,
-demos, and APK packaging: This script does retrieve and use the upstream SPRIV
-tools.
+Use the following script to build the vkcube demo for Android:
 
     cd build-android
     ./build_all.sh
 
-Test and application APKs can be installed on production devices with:
+The APK can be installed on production devices with:
 
     ./install_all.sh [-s <serial number>]
 
 Note that there are no equivalent scripts on Windows yet, that work needs to
-be completed. The following per platform commands can be used for layer only
-builds:
+be completed.
 
-#### Linux and OSX
-
-Follow the setup steps for Linux or OSX above, then from your terminal:
-
-    cd build-android
-    ./update_external_sources_android.sh --no-build
-    ./android-generate.sh
-    ndk-build -j4
+### Run vkcube
 
-#### Windows
+Use the following command to run vkcube for Android:
 
-Follow the setup steps for Windows above, then from Developer Command Prompt
-for VS2013:
-
-    cd build-android
-    update_external_sources_android.bat
-    android-generate.bat
-    ndk-build
-
-### Android Tests and Demos
-
-After making any changes to the repository you should perform some quick
-sanity tests, including the layer validation tests and the vkcube 
-demo with validation enabled.
-
-#### Run Layer Validation Tests
-
-Use the following steps to build, install, and run the layer validation tests
-for Android:
-
-    cd build-android
-    ./build_all.sh
-    adb install -r bin/VulkanLayerValidationTests.apk
-    adb shell am start com.example.VulkanLayerValidationTests/android.app.NativeActivity
-
-Alternatively, you can use the test_APK script to install and run the layer
-validation tests:
-
-    test_APK.sh -s <serial number> -p <platform name> -f <gtest_filter>
-
-#### Run vkcube with Validation
-
-TODO: This must be reworked to pull in layers from the ValidationLayers repo
-
-Use the following steps to build, install, and run vkcube for Android:
-
-    cd build-android
-    ./build_all.sh
-    adb install -r ../demos/android/cube/bin/vkcube.apk
-    adb shell am start com.example.Cube/android.app.NativeActivity
-
-To build, install, and run Cube with validation layers,
-first build layers using steps above, then run:
-
-    cd build-android
-    ./build_all.sh
-    adb install -r ../demos/android/cube-with-layers/bin/cube-with-layers.apk
-
-##### Run without validation enabled
-
-    adb shell am start com.example.CubeWithLayers/android.app.NativeActivity
-
-##### Run with validation enabled
-
-    adb shell am start -a android.intent.action.MAIN -c android-intent.category.LAUNCH -n com.example.CubeWithLayers/android.app.NativeActivity --es args "--validate"
+    adb shell am start com.example.VkCube/android.app.NativeActivity
 
 ## Building on MacOS
 
 ### MacOS Build Requirements
 
-Tested on OSX version 10.12.6
+Tested on OSX version 10.12
 
-- [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Darwin-x86_64.tar.gz) is recommended.
+NOTE: To force the OSX version set the environment variable [MACOSX_DEPLOYMENT_TARGET](https://cmake.org/cmake/help/latest/envvar/MACOSX_DEPLOYMENT_TARGET.html) when building VVL and it's dependencies.
 
 Setup Homebrew and components
 
-- 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)"
-
 - Ensure Homebrew is at the beginning of your PATH:
 
       export PATH=/usr/local/bin:$PATH
@@ -796,7 +743,6 @@ You can now run the demo applications from the command line:
 
     open cube/vkcube.app
     open cube/vkcubepp.app
-    open vulkaninfo/vulkaninfo.app
 
 Or you can locate them from `Finder` and launch them from there.
 
@@ -836,10 +782,9 @@ run the `otool` command again from the `build/install` directory and note:
 The "bundle fix-up" operation also puts a copy of the Vulkan loader into the
 bundle, making the bundle completely self-contained and self-referencing.
 
-##### The Non-bundled vulkaninfo Application
+##### The vulkaninfo Application
 
-There is also a non-bundled version of the `vulkaninfo` application that you
-can run from the command line:
+There is also a `vulkaninfo` application that you can run from the command line:
 
     vulkaninfo/vulkaninfo
 
Domain: Graphics System / GL;