BUILD.md

   1 # Build Instructions
   2 This project fully supports Linux today.
   3 Support for Windows is for the loader, layers, and the VkTrace trace/replay tools.
   4 Support for Android is TBD.
   5
   6 ## Git the Bits
   7
   8 Make sure you have access to the Khronos GitLab repository at gitlab.khronos.org.  Once you do, the
   9 preferred work flow is to clone the repo, create a branch, push branch to gitlab and then
  10 issue a merge request to integrate that work back into the repo.
  11
  12 Note: If you are doing ICD (driver) development, please make sure to look at documentation in the [ICD Loader](loader/README.md) and the [Sample Driver](icd).
  13
  14 ## Linux System Requirements
  15 Ubuntu 14.10 and 15.04 have been used with the sample driver.
  16
  17 These packages are used for building and running the samples.
  18 ```
  19 sudo apt-get install git subversion cmake libgl1-mesa-dev freeglut3-dev libglm-dev libmagickwand-dev qt5-default libpciaccess-dev libpthread-stubs0-dev libudev-dev bison
  20 sudo apt-get build-dep mesa
  21 ```
  22
  23 The sample driver uses DRI3 for its window system interface.
  24 That requires extra configuration of Ubuntu systems.
  25
  26 ### Ubuntu 14.10 support of DRI 3
  27
  28 Warning: Recent versions of 14.10 have **REMOVED** DRI 3.
  29 Version: 2:2.99.914-1~exp1ubuntu4.1 is known to work.
  30 To see status of this package:
  31 ```
  32 dpkg -s xserver-xorg-video-intel
  33 ```
  34
  35 Note:
  36 Version 2:2.99.914-1~exp1ubuntu4.2 does not work anymore.
  37 To install the working driver from launchpadlibrarian.net:
  38 - Remove the current driver:
  39 ```
  40 sudo apt-get purge xserver-xorg-video-intel
  41 ```
  42 - Download the old driver:
  43 ```
  44 wget http://launchpadlibrarian.net/189418339/xserver-xorg-video-intel_2.99.914-1%7Eexp1ubuntu4.1_amd64.deb
  45 ```
  46 - Install the driver:
  47 ```
  48 sudo dpkg -i xserver-xorg-video-intel_2.99.914-1~exp1ubuntu4.1_amd64.deb
  49 ```
  50 - Pin the package to prevent updates
  51 ```
  52 sudo bash -c "echo $'Package: xserver-xorg-video-intel\nPin: version 2:2.99.914-1~exp1ubuntu4.1\nPin-Priority: 1001' > /etc/apt/preferences.d/xserver-xorg-video-intel"
  53 ```
  54
  55 - Either restart Ubuntu or just X11.
  56
  57
  58 ### Ubuntu 15.04 support of DRI 3
  59
  60 Ubuntu 15.04 has never shipped a xserver-xorg-video-intel package with supported DRI 3 on intel graphics.
  61 The xserver-xorg-video-intel package can be built from source with DRI 3 enabled.
  62 Use the following commands to enable DRI3 on ubuntu 15.04.
  63
  64 - Install packages used to build:
  65 ```
  66 sudo apt-get update
  67 sudo apt-get dist-upgrade
  68 sudo apt-get install devscripts
  69 sudo apt-get build-dep xserver-xorg-video-intel
  70 ```
  71
  72 - Get the source code for xserver-xorg-video-intel
  73 ```
  74 mkdir xserver-xorg-video-intel_source
  75 cd xserver-xorg-video-intel_source
  76 apt-get source xserver-xorg-video-intel
  77 cd xserver-xorg-video-intel-2.99.917
  78 debian/rules patch
  79 quilt new 'enable-DRI3'
  80 quilt edit configure.ac
  81 ```
  82
  83 - Use the editor to make these changes.
  84 ```
  85 --- a/configure.ac
  86 +++ b/configure.ac
  87 @@ -340,9 +340,9 @@
  88               [DRI2=yes])
  89  AC_ARG_ENABLE(dri3,
  90               AS_HELP_STRING([--enable-dri3],
  91 -                            [Enable DRI3 support [[default=no]]]),
  92 +                            [Enable DRI3 support [[default=yes]]]),
  93               [DRI3=$enableval],
  94 -             [DRI3=no])
  95 +             [DRI3=yes])
  96  AC_ARG_ENABLE(xvmc, AS_HELP_STRING([--disable-xvmc],
  97                                    [Disable XvMC support [[default=yes]]]),
  98 ```
  99 - Build and install xserver-xorg-video-intel
 100 ```
 101 quilt refresh
 102 debian/rules clean
 103 debuild -us -uc
 104 sudo dpkg -i ../xserver-xorg-video-intel_2.99.917-1~exp1ubuntu2.2_amd64.deb
 105 ```
 106 - Prevent updates from replacing this version of the package.
 107 ```
 108 sudo bash -c 'echo xserver-xorg-video-intel hold | dpkg --set-selections'
 109 ```
 110 - save your work then restart the X server with the next command.
 111 ```
 112 sudo service lightdm restart
 113 ```
 114 - After logging in again, check for success with this command and look for DRI3.
 115 ```
 116 xdpyinfo | grep DRI
 117 ```
 118 ### Ubuntu 15.10 support of DRI 3
 119
 120 Ubuntu 15.10 has never shipped a xserver-xorg-video-intel package with supported DRI 3 on intel graphics.
 121 The xserver-xorg-video-intel package can be built from source with DRI 3 enabled.
 122 Use the following commands to enable DRI3 on ubuntu 15.10.
 123
 124 - Install packages used to build:
 125 ```
 126 sudo apt-get update
 127 sudo apt-get dist-upgrade
 128 sudo apt-get install devscripts
 129 sudo apt-get build-dep xserver-xorg-video-intel
 130 ```
 131
 132 - Get the source code for xserver-xorg-video-intel
 133 ```
 134 mkdir xserver-xorg-video-intel_source
 135 cd xserver-xorg-video-intel_source
 136 apt-get source xserver-xorg-video-intel
 137 cd xserver-xorg-video-intel-2.99.917+git20150808
 138 debian/rules patch
 139 quilt new 'enable-DRI3'
 140 quilt edit configure.ac
 141 ```
 142
 143 - Use the editor to make these changes.
 144 ```
 145 Index: xserver-xorg-video-intel-2.99.917+git20150808/configure.ac
 146 ===================================================================
 147 --- xserver-xorg-video-intel-2.99.917+git20150808.orig/configure.ac
 148 +++ xserver-xorg-video-intel-2.99.917+git20150808/configure.ac
 149 @@ -356,7 +356,7 @@ AC_ARG_WITH(default-dri,
 150             AS_HELP_STRING([--with-default-dri],
 151                            [Select the default maximum DRI level [default 2]]),
 152               [DRI_DEFAULT=$withval],
 153 -             [DRI_DEFAULT=2])
 154 +             [DRI_DEFAULT=3])
 155  if test "x$DRI_DEFAULT" = "x0"; then
 156         AC_DEFINE(DEFAULT_DRI_LEVEL, 0,[Default DRI level])
 157  else
 158 ```
 159 - Build and install xserver-xorg-video-intel
 160 ```
 161 quilt refresh
 162 debian/rules clean
 163 debuild -us -uc
 164 sudo dpkg -i ../xserver-xorg-video-intel_2.99.917+git20150808-0ubuntu4_amd64.deb
 165 ```
 166 - Prevent updates from replacing this version of the package.
 167 ```
 168 sudo bash -c 'echo xserver-xorg-video-intel hold | dpkg --set-selections'
 169 ```
 170 - save your work then restart the X server with the next command.
 171 ```
 172 sudo service lightdm restart
 173 ```
 174 - After logging in again, check for success with this command and look for DRI3.
 175 ```
 176 xdpyinfo | grep DRI
 177 ```
 178
 179
 180 ## Clone the repository
 181
 182 To create your local git repository:
 183 ```
 184 mkdir YOUR_DEV_DIRECTORY  # it's called GL-Next on Github, but the name doesn't matter
 185 cd YOUR_DEV_DIRECTORY
 186 git clone -o khronos git@gitlab.khronos.org:vulkan/LoaderAndTools.git .
 187 # Or substitute the URL from your forked repo for git@gitlab.khronos.org:vulkan/LoaderAndTools.git above.
 188 ```
 189
 190 ## Linux Build
 191
 192 The sample driver uses cmake and should work with the usual cmake options and utilities.
 193 The standard build process builds the icd, the icd loader and all the tests.
 194
 195 Example debug build:
 196 ```
 197 cd YOUR_DEV_DIRECTORY  # cd to the root of the vk git repository
 198 export KHRONOS_ACCOUNT_NAME= <subversion login name for svn checkout of BIL>
 199 ./update_external_sources.sh  # fetches and builds glslang, llvm, LunarGLASS, and BIL
 200 cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug
 201 cd dbuild
 202 make
 203 ```
 204
 205 To run VK programs you must tell the icd loader where to find the libraries.
 206 This is described in a specification in the Khronos documentation Git
 207 repository.  See the file:
 208 https://gitlab.khronos.org/vulkan/vulkan/blob/master/ecosystem/LinuxICDs.txt
 209
 210 This specification describes both how ICDs and layers should be properly
 211 packaged, and how developers can point to ICDs and layers within their builds.
 212
 213
 214 ## Linux Test
 215
 216 The test executibles can be found in the dbuild/tests directory. The tests use the Google
 217 gtest infrastructure. Tests available so far:
 218 - vkbase: Test basic entry points
 219 - vk_blit_tests: Test VK Blits (copy, clear, and resolve)
 220 - vk_image_tests: Test VK image related calls needed by render_test
 221 - vk_render_tests: Render a single triangle with VK. Triangle will be in a .ppm in
 222 the current directory at the end of the test.
 223 - vk_layer_validation_tests: Test Vulkan layers.
 224
 225 There are also a few shell and Python scripts that run test collections (eg,
 226 `run_all_tests.sh`).
 227
 228 ## Linux Demos
 229
 230 The demos executables can be found in the dbuild/demos directory. The demos use DRI 3
 231 to render directly onto window surfaces.
 232 - vulkaninfo: report GPU properties
 233 - tri: a textured triangle
 234 - cube: a textured spinning cube
 235
 236 ## Linux Render Nodes
 237
 238 The render tests depend on access to DRM render nodes.
 239 To make that available, a couple of config files need to be created to set a module option
 240 and make accessible device files.
 241 The system will need to be rebooted with these files in place to complete initialization.
 242 These commands will create the config files.
 243
 244 ```
 245 sudo tee /etc/modprobe.d/drm.conf << EOF
 246 # Enable render nodes
 247 options drm rnodes=1
 248 EOF
 249 # this will add the rnodes=1 option into the boot environment
 250 sudo update-initramfs -k all -u
 251 ```
 252 ```
 253 sudo tee /etc/udev/rules.d/drm.rules << EOF
 254 # Add permissions to render nodes
 255 SUBSYSTEM=="drm", ACTION=="add", DEVPATH=="/devices/*/renderD*", MODE="020666"
 256 EOF
 257 ```
 258
 259 ## Windows System Requirements
 260
 261 Windows 7+ with additional required software packages:
 262
 263 - Microsoft Visual Studio 2013 Professional.  Note: it is possible that lesser/older versions may work, but that has not been tested.
 264 - CMake (from http://www.cmake.org/download/).  Notes:
 265   - In order to build the VkTrace tools, you need at least version 3.0.
 266   - Tell the installer to "Add CMake to the system PATH" environment variable.
 267 - Python 3 (from https://www.python.org/downloads).  Notes:
 268   - Select to install the optional sub-package to add Python to the system PATH environment variable.
 269   - 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
 270 - Git (from http://git-scm.com/download/win).
 271   - Note: If you use Cygwin, you can normally use Cygwin's "git.exe".  However, in order to use the "update_external_sources.bat" script, you must have this version.
 272   - Tell the installer to allow it to be used for "Developer Prompt" as well as "Git Bash".
 273   - Tell the installer to treat line endings "as is" (i.e. both DOS and Unix-style line endings).
 274 - Image Magick is used by the tests to compare images (from http://www.imagemagick.org/script/binary-releases.php)
 275   - Be sure to check box to "Install development headers and libraries"
 276 - glslang is required for demos and tests.
 277   - You can download and configure it (in a peer directory) here: https://github.com/KhronosGroup/glslang/blob/master/README.md
 278   - A windows batch file has been included that will pull and build the correct version.  Run it from Developer Command Prompt for VS2013 like so:
 279     - update_external_sources.bat --build-glslang
 280
 281 Optional software packages:
 282
 283 - Cygwin (from https://www.cygwin.com/).  Notes:
 284   - Cygwin provides some Linux-like tools, which are valuable for obtaining the source code, and running CMake.
 285     Especially valuable are the BASH shell and git packages.
 286   - If you don't want to use Cygwin, there are other shells and environments that can be used.
 287     You can also use a Git package that doesn't come from Cygwin.
 288
 289 ## Windows Build
 290
 291 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.
 292
 293 Example debug build (e.g. in a "Developer Command Prompt for VS2013" window):
 294 ```
 295 cd LoaderAndTools  # cd to the root of the Vulkan git repository
 296 update_external_sources.bat --build-glslang
 297 mkdir build
 298 cd build
 299 cmake -G "Visual Studio 12 Win64" ..
 300 ```
 301
 302 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.
 303
 304 VK programs must be able to find and use the VK.dll libary. Make sure it is either installed in the C:\Windows\System32 folder, or the PATH enviroment variable includes the folder that it is located in.
 305
 306 To run VK programs you must tell the icd loader where to find the libraries.
 307 This is described in a specification in the Khronos documentation Git
 308 repository.  See the file:
 309 https://gitlab.khronos.org/vulkan/vulkan/blob/master/ecosystem/WindowsICDs.txt
 310
 311 This specification describes both how ICDs and layers should be properly
 312 packaged, and how developers can point to ICDs and layers within their builds.