Skip to content
This repository has been archived by the owner on Jun 13, 2020. It is now read-only.

Latest commit

 

History

History
399 lines (316 loc) · 15.5 KB

BUILD.md

File metadata and controls

399 lines (316 loc) · 15.5 KB

Build Instructions

This document contains the instructions for building this repository on Linux and Windows.

This repository contains the Vulkan vktrace/replay development tools, supplementing the loader and validation layer core components found at https://github.com/KhronosGroup.

Get Additional Components

The public repository for LunarG vktrace is hosted at https://github.com/LunarG.

Linux System Requirements

These additional packages are needed for building the components in this repo.

Ubuntu

Ubuntu 16.04 LTS and 18.04 have been tested with this repo.

CMake 3.10.2 is recommended.

# Dependencies from included submodule components
sudo apt-get install git build-essential bison libx11-xcb-dev libxkbcommon-dev libwayland-dev libxrandr-dev libxcb-randr0-dev
# Additional dependencies for this repo:
sudo apt-get install wget autotools-dev libxcb-keysyms1 libxcb-keysyms1-dev libxcb-ewmh-dev
# If performing 32-bit builds, you will also need:
sudo apt-get install libc6-dev-i386 g++-multilib

Fedora Core

Fedora Core 28 and 29 were tested with this repo.

CMake 3.10.2 is recommended.

Additional package dependencies include:

# Dependencies from included submodule components
sudo dnf install git @development-tools glm-devel \
                 libpng-devel wayland-devel libpciaccess-devel \
                 libX11-devel libXpresent libxcb xcb-util libxcb-devel libXrandr-devel \
                 xcb-util-keysyms-devel xcb-util-wm-devel

Download the repository

To create your local git repository of vktrace:

cd YOUR_DEV_DIRECTORY

# Clone the vktrace repo
git clone --recurse-submodules [email protected]:LunarG/vktrace.git

# Enter the folder containing the cloned source
cd vktrace

# This will perform some initialization and ensure subcomponents are built:
./update_external_sources.sh    # linux
./update_external_sources.bat   # windows

Updating the Repository After a Pull

The vktrace repository contains a submodule named jsoncpp. You may occasionally have to update the source in that submodules. You will know this needs to be performed when you perform a pull, and you check the status of your tree with git status and something similar to the following shows:

(master *)] $ git status
On branch master
Your branch is up-to-date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   submodules/jsoncpp (new commits)

no changes added to commit (use "git add" and/or "git commit -a")

To resolve this, simply update the sub-module using:

git submodule update --recursive

Then, update the external sources as before:

# This will perform required subcomponent operations.
./update_external_sources.sh    # linux
./update_external_sources.bat   # windows

Now, you should be able to continue building as normal.

Repository Dependencies

This repository attempts to resolve some of its dependencies by using components found from the following places, in this order:

  1. CMake or Environment variable overrides (e.g., -DVULKAN_HEADERS_INSTALL_DIR)
  2. LunarG Vulkan SDK, located by the VULKAN_SDK environment variable
  3. System-installed packages, mostly applicable on Linux

Dependencies that cannot be resolved by the SDK or installed packages must be resolved with the "install directory" override and are listed below. The "install directory" override can also be used to force the use of a specific version of that dependency.

Vulkan-Headers

This repository has a required dependency on the Vulkan Headers repository. You must clone the headers repository and build its install target before building this repository. The Vulkan-Headers repository is required because it contains the Vulkan API definition files (registry) that are required to build the validation layers. You must also take note of the headers' install directory and pass it on the CMake command line for building this repository, as described below.

Vulkan-Loader

The tools in this repository depend on the Vulkan loader.

A loader can be used from an installed LunarG SDK, an installed Linux package, or from a driver installation on Windows.

If a loader is not available from any of these methods and/or it is important to use a loader built from a repository, then you must build the Vulkan-Loader repository with its install target. Take note of its install directory location and pass it on the CMake command line for building this repository, as described below.

Vulkan-ValidationLayers

The tools in this repository depend on the Vulkan validation layers.

Validation layers can be used from an installed LunarG SDK, an installed Linux package, or from a driver installation on Windows.

If the validation layers are not available from any of these methods and/or it is important to use the validation layers built from a repository, then you must build the Vulkan-ValidationLayers repository with its install target. Take note of its install directory location and pass it on the CMake command line for building this repository, as described below.

Build and Install Directories

A common convention is to place the build directory in the top directory of the repository with a name of build and place the install directory as a child of the build directory with the name install. The remainder of these instructions follow this convention, although you can use any name for these directories and place them in any location.

Building Dependent Repositories with Known-Good Revisions

There is a Python utility script, scripts/update_deps.py, that you can use to gather and build the dependent repositories mentioned above. This script uses information stored in the scripts/known_good.json file to check out dependent repository revisions that are known to be compatible with the revision of this repository that you currently have checked out. As such, this script is useful as a quick-start tool for common use cases and default configurations.

For all platforms, start with:

git clone --recurse-submodules [email protected]:LunarG/vktrace.git
cd vktrace
mkdir build

For 64-bit Linux and MacOS, continue with:

./update_external_sources.sh
cd build
../scripts/update_deps.py
cmake -C helper.cmake ..
cmake --build .

For 64-bit Windows, continue with:

.\update_external_sources.bat
cd build
..\scripts\update_deps.py --arch x64
cmake -A x64 -C helper.cmake ..
cmake --build .

For 32-bit Windows, continue with:

.\update_external_sources.bat
cd build
..\scripts\update_deps.py --arch Win32
cmake -A Win32 -C helper.cmake ..
cmake --build .

Please see the more detailed build information later in this file if you have specific requirements for configuring and building these components.

Notes

  • You may need to adjust some of the CMake options based on your platform. See the platform-specific sections later in this document.
  • The update_deps.py script fetches and builds the dependent repositories in the current directory when it is invoked. In this case, they are built in the build directory.
  • The build directory is also being used to build this (VulkanTools) repository. But there shouldn't be any conflicts inside the build directory between the dependent repositories and the build files for this repository.
  • The --dir option for update_deps.py can be used to relocate the dependent repositories to another arbitrary directory using an absolute or relative path.
  • The update_deps.py script generates a file named helper.cmake and places it in the same directory as the dependent repositories (build in this case). This file contains CMake commands to set the CMake *_INSTALL_DIR variables that are used to point to the install artifacts of the dependent repositories. You can use this file with the cmake -C option to set these variables when you generate your build files with CMake. This lets you avoid entering several *_INSTALL_DIR variable settings on the CMake command line.
  • If using "MINGW" (Git For Windows), you may wish to run winpty update_deps.py in order to avoid buffering all of the script's "print" output until the end and to retain the ability to interrupt script execution.
  • Please use update_deps.py --help to list additional options and read the internal documentation in update_deps.py for further information.

Linux Build

This build process builds all items in the vktrace repository

Example debug build:

cd vktrace  # cd to the root of the vktrace git repository
cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=build/install -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_directory -DVULKAN_LOADER_INSTALL_DIR=absolute_path_to_install_directory -DVULKAN_VALIDATIONLAYERS_INSTALL_DIR=absolute_path_to_install_directory
cd dbuild
make -j8

Windows System Requirements

Windows 7+ with additional required software packages:

  • Microsoft Visual Studio 2015 Professional or 2017 Professional. Note: it is possible that lesser/older versions may work, but not guaranteed.
  • CMake 3.10.2 is recommended.
    • Tell the installer to "Add CMake to the system PATH" environment variable.
  • Python 3 (from https://www.python.org/downloads). Notes:
    • Select to install the optional sub-package to add Python to the system PATH environment variable.
    • Need python3.3 or later to get the Windows py.exe launcher that is used to get python3 rather than python2 if both are installed on Windows
  • Git (from http://git-scm.com/download/win).
    • Tell the installer to allow it to be used for "Developer Prompt" as well as "Git Bash".
    • Tell the installer to treat line endings "as is" (i.e. both DOS and Unix-style line endings).

Optional software packages:

  • Cygwin (from https://www.cygwin.com/). Notes:
    • Cygwin provides some Linux-like tools, which are valuable for obtaining the source code, and running CMake. Especially valuable are the BASH shell and git packages.
    • If you do not wish to use Cygwin, there are other shells and environments that can be used. You can also use a Git package that does not come from Cygwin.

Windows Build

Cygwin is used in order to obtain a local copy of the Git repository, and to run the CMake command that creates Visual Studio files. Visual Studio is used to build the software, and will re-run CMake as appropriate.

To build all Windows targets (e.g. in a "Developer Command Prompt for VS2015" window):

cd vktrace  # cd to the root of the vktrace git repository
cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug -G "Visual Studio 14 2015 Win64" -DCMAKE_INSTALL_PREFIX=build/install -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_directory -DVULKAN_LOADER_INSTALL_DIR=absolute_path_to_install_directory -DVULKAN_VALIDATIONLAYERS_INSTALL_DIR=absolute_path_to_install_directory
cmake --build dbuild --config Debug --target install

At this point, you can use Windows Explorer to launch Visual Studio by double-clicking on the "VULKAN.sln" file in the \build folder. Once Visual Studio comes up, you can select "Debug" or "Release" from a drop-down list. You can start a build with either the menu (Build->Build Solution), or a keyboard shortcut (Ctrl+Shift+B). As part of the build process, Python scripts will create additional Visual Studio files and projects, along with additional source files. All of these auto-generated files are under the "build" folder.

Vulkan programs must be able to find and use the Vulkan-1.dll library. Make sure it is either installed in the C:\Windows\System32 folder, or the PATH environment variable includes the folder that it is located in.

Windows 64-bit Installation Notes

If you plan on creating a Windows Install file (done in the windowsRuntimeInstaller sub-directory) you will need to build for both 32-bit and 64-bit Windows since both versions of EXEs and DLLs exist simultaneously on Windows 64.

To do this, simply create and build the release versions of each target:

cd vktrace  # cd to the root of the Vulkan git repository
mkdir build
cd build
cmake -G "Visual Studio 14 Win64" ..
msbuild ALL_BUILD.vcxproj /p:Platform=x64 /p:Configuration=Release
mkdir build32
cd build32
cmake -G "Visual Studio 14" ..
msbuild ALL_BUILD.vcxproj /p:Platform=x86 /p:Configuration=Release

Android Build

Install the required tools for Linux and Windows covered above, then add the following.

Android Studio

  • Install 2.1 or later version of Android Studio
  • From the "Welcome to Android Studio" splash screen, add the following components using Configure > SDK Manager:
    • SDK Tools > Android NDK

Add NDK to path

On Linux:

export PATH=$HOME/Android/Sdk/ndk-bundle:$PATH

On Windows:

set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH%

On OSX:

export PATH=$HOME/Library/Android/sdk/ndk-bundle:$PATH

Additional OSX System Requirements

Tested on OSX version 10.11.4

Setup Homebrew and components

  • Follow instructions on 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 (may need refinement)
brew install python python3 git

Build steps for Android

Use the following to ensure the Android build works.

Linux

Follow the setup steps for Linux, then from your terminal:

cd build-android
./update_external_sources_android.sh
./android-generate.sh
ndk-build -j $(nproc)

OSX

Follow the setup steps for OSX above, then from your terminal:

cd build-android
./update_external_sources_android.sh
./android-generate.sh
ndk-build -j $(sysctl -n hw.ncpu)

Windows

Follow the setup steps for Windows above, then from Developer Command Prompt for VS2015:

cd build-android
update_external_sources_android.bat
android-generate.bat
ndk-build

Android usage

See the vktracereplay.sh file for a working example of how to use vktrace/vkreplay and the screenshot layers.

Two additional scripts have been added to facilitate tracing and replaying any APK. Note that these two scripts do not install anything for you, so make sure your target APK, vktrace, vktrace_layer, and vkreplay all use the same ABI.

./create_trace.sh --serial 0123456789 --abi armeabi-v7a --package com.example.CubeWithLayers  --activity android.app.NativeActivity
adb install --abi armeabi-v7a
./replay_trace.sh --serial 0123456789 --tracefile com.example.CubeWithLayers0.vktrace

An example of using the scripts on Linux and macOS:

./build_vktracereplay.sh
./vktracereplay.sh \
 --serial 12345678 \
 --abi armeabi-v7a \
 --apk ../demos/android/cube-with-layers/bin/cube-with-layers.apk \
 --package com.example.CubeWithLayers \
 --frame 50

And on Windows:

build_vktracereplay.bat ^
vktracereplay.bat ^
 --serial 12345678 ^
 --abi armeabi-v7a ^
 --apk ..\demos\android\cube-with-layers\bin\NativeActivity-debug.apk ^
 --package com.example.CubeWithLayers ^
 --frame 50