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.04.3 LTS, 14.10, 15.04 and 15.10 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 graphviz libpng-dev
  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.04.3 LTS support of DRI 3
  27
  28 Ubuntu 14.04.3 LTS does not ship a xserver-xorg-video-intel package with supported DRI 3 on intel graphics.
  29 The xserver-xorg-video-intel package can be built from source with DRI 3 enabled.
  30 Use the following commands to enable DRI3 on ubuntu 14.04.3 LTS.
  31
  32 - Install packages used to build:
  33 ```
  34 sudo apt-get update
  35 sudo apt-get dist-upgrade
  36 sudo apt-get install devscripts
  37 sudo apt-get build-dep xserver-xorg-video-intel-lts-vivid
  38 ```
  39
  40 - Get the source code for xserver-xorg-video-intel-lts-vivid
  41 ```
  42 mkdir xserver-xorg-video-intel-lts-vivid_source
  43 cd xserver-xorg-video-intel-lts-vivid_source
  44 apt-get source xserver-xorg-video-intel-lts-vivid
  45 cd xserver-xorg-video-intel-lts-vivid-2.99.917
  46 debian/rules patch
  47 quilt new 'enable-DRI3'
  48 quilt edit configure.ac
  49 ```
  50
  51 - Use the editor to make these changes.
  52 ```
  53 --- a/configure.ac
  54 +++ b/configure.ac
  55 @@ -340,9 +340,9 @@
  56               [DRI2=yes])
  57  AC_ARG_ENABLE(dri3,
  58               AS_HELP_STRING([--enable-dri3],
  59 -                            [Enable DRI3 support [[default=no]]]),
  60 +                            [Enable DRI3 support [[default=yes]]]),
  61               [DRI3=$enableval],
  62 -             [DRI3=no])
  63 +             [DRI3=yes])
  64  AC_ARG_ENABLE(xvmc, AS_HELP_STRING([--disable-xvmc],
  65                                    [Disable XvMC support [[default=yes]]]),
  66 ```
  67 - Build and install xserver-xorg-video-intel-lts-vivid
  68 ```
  69 quilt refresh
  70 debian/rules clean
  71 debuild -us -uc
  72 sudo dpkg -i ../xserver-xorg-video-intel-lts-vivid_2.99.917-1~exp1ubuntu2.2~trusty1_amd64.deb
  73 ```
  74 - Prevent updates from replacing this version of the package.
  75 ```
  76 sudo bash -c 'echo xserver-xorg-video-intel-lts-vivid hold | dpkg --set-selections'
  77 ```
  78 - save your work then restart the X server with the next command.
  79 ```
  80 sudo service lightdm restart
  81 ```
  82 - After logging in again, check for success with this command and look for DRI3.
  83 ```
  84 xdpyinfo | grep DRI
  85 ```
  86
  87 ### Ubuntu 14.10 support of DRI 3
  88
  89 Warning: Recent versions of 14.10 have **REMOVED** DRI 3.
  90 Version: 2:2.99.914-1~exp1ubuntu4.1 is known to work.
  91 To see status of this package:
  92 ```
  93 dpkg -s xserver-xorg-video-intel
  94 ```
  95
  96 Note:
  97 Version 2:2.99.914-1~exp1ubuntu4.2 does not work anymore.
  98 To install the working driver from launchpadlibrarian.net:
  99 - Remove the current driver:
 100 ```
 101 sudo apt-get purge xserver-xorg-video-intel
 102 ```
 103 - Download the old driver:
 104 ```
 105 wget http://launchpadlibrarian.net/189418339/xserver-xorg-video-intel_2.99.914-1%7Eexp1ubuntu4.1_amd64.deb
 106 ```
 107 - Install the driver:
 108 ```
 109 sudo dpkg -i xserver-xorg-video-intel_2.99.914-1~exp1ubuntu4.1_amd64.deb
 110 ```
 111 - Pin the package to prevent updates
 112 ```
 113 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"
 114 ```
 115
 116 - Either restart Ubuntu or just X11.
 117
 118
 119 ### Ubuntu 15.04 support of DRI 3
 120
 121 Ubuntu 15.04 has never shipped a xserver-xorg-video-intel package with supported DRI 3 on intel graphics.
 122 The xserver-xorg-video-intel package can be built from source with DRI 3 enabled.
 123 Use the following commands to enable DRI3 on ubuntu 15.04.
 124
 125 - Install packages used to build:
 126 ```
 127 sudo apt-get update
 128 sudo apt-get dist-upgrade
 129 sudo apt-get install devscripts
 130 sudo apt-get build-dep xserver-xorg-video-intel
 131 ```
 132
 133 - Get the source code for xserver-xorg-video-intel
 134 ```
 135 mkdir xserver-xorg-video-intel_source
 136 cd xserver-xorg-video-intel_source
 137 apt-get source xserver-xorg-video-intel
 138 cd xserver-xorg-video-intel-2.99.917
 139 debian/rules patch
 140 quilt new 'enable-DRI3'
 141 quilt edit configure.ac
 142 ```
 143
 144 - Use the editor to make these changes.
 145 ```
 146 --- a/configure.ac
 147 +++ b/configure.ac
 148 @@ -340,9 +340,9 @@
 149               [DRI2=yes])
 150  AC_ARG_ENABLE(dri3,
 151               AS_HELP_STRING([--enable-dri3],
 152 -                            [Enable DRI3 support [[default=no]]]),
 153 +                            [Enable DRI3 support [[default=yes]]]),
 154               [DRI3=$enableval],
 155 -             [DRI3=no])
 156 +             [DRI3=yes])
 157  AC_ARG_ENABLE(xvmc, AS_HELP_STRING([--disable-xvmc],
 158                                    [Disable XvMC support [[default=yes]]]),
 159 ```
 160 - Build and install xserver-xorg-video-intel
 161 ```
 162 quilt refresh
 163 debian/rules clean
 164 debuild -us -uc
 165 sudo dpkg -i ../xserver-xorg-video-intel_2.99.917-1~exp1ubuntu2.2_amd64.deb
 166 ```
 167 - Prevent updates from replacing this version of the package.
 168 ```
 169 sudo bash -c 'echo xserver-xorg-video-intel hold | dpkg --set-selections'
 170 ```
 171 - save your work then restart the X server with the next command.
 172 ```
 173 sudo service lightdm restart
 174 ```
 175 - After logging in again, check for success with this command and look for DRI3.
 176 ```
 177 xdpyinfo | grep DRI
 178 ```
 179 ### Ubuntu 15.10 support of DRI 3
 180
 181 Ubuntu 15.10 has never shipped a xserver-xorg-video-intel package with supported DRI 3 on intel graphics.
 182 The xserver-xorg-video-intel package can be built from source with DRI 3 enabled.
 183 Use the following commands to enable DRI3 on ubuntu 15.10.
 184
 185 - Install packages used to build:
 186 ```
 187 sudo apt-get update
 188 sudo apt-get dist-upgrade
 189 sudo apt-get install devscripts
 190 sudo apt-get build-dep xserver-xorg-video-intel
 191 ```
 192
 193 - Get the source code for xserver-xorg-video-intel
 194 ```
 195 mkdir xserver-xorg-video-intel_source
 196 cd xserver-xorg-video-intel_source
 197 apt-get source xserver-xorg-video-intel
 198 cd xserver-xorg-video-intel-2.99.917+git20150808
 199 debian/rules patch
 200 quilt new 'enable-DRI3'
 201 quilt edit configure.ac
 202 ```
 203
 204 - Use the editor to make these changes.
 205 ```
 206 Index: xserver-xorg-video-intel-2.99.917+git20150808/configure.ac
 207 ===================================================================
 208 --- xserver-xorg-video-intel-2.99.917+git20150808.orig/configure.ac
 209 +++ xserver-xorg-video-intel-2.99.917+git20150808/configure.ac
 210 @@ -356,7 +356,7 @@ AC_ARG_WITH(default-dri,
 211             AS_HELP_STRING([--with-default-dri],
 212                            [Select the default maximum DRI level [default 2]]),
 213               [DRI_DEFAULT=$withval],
 214 -             [DRI_DEFAULT=2])
 215 +             [DRI_DEFAULT=3])
 216  if test "x$DRI_DEFAULT" = "x0"; then
 217         AC_DEFINE(DEFAULT_DRI_LEVEL, 0,[Default DRI level])
 218  else
 219 ```
 220 - Build and install xserver-xorg-video-intel
 221 ```
 222 quilt refresh
 223 debian/rules clean
 224 debuild -us -uc
 225 sudo dpkg -i ../xserver-xorg-video-intel_2.99.917+git20150808-0ubuntu4_amd64.deb
 226 ```
 227 - Prevent updates from replacing this version of the package.
 228 ```
 229 sudo bash -c 'echo xserver-xorg-video-intel hold | dpkg --set-selections'
 230 ```
 231 - save your work then restart the X server with the next command.
 232 ```
 233 sudo service lightdm restart
 234 ```
 235 - After logging in again, check for success with this command and look for DRI3.
 236 ```
 237 xdpyinfo | grep DRI
 238 ```
 239
 240
 241 ## Clone the repository
 242
 243 To create your local git repository:
 244 ```
 245 mkdir YOUR_DEV_DIRECTORY  # it's called GL-Next on Github, but the name doesn't matter
 246 cd YOUR_DEV_DIRECTORY
 247 git clone -o khronos git@gitlab.khronos.org:vulkan/LoaderAndTools.git .
 248 # Or substitute the URL from your forked repo for git@gitlab.khronos.org:vulkan/LoaderAndTools.git above.
 249 ```
 250
 251 ## Linux Build
 252
 253 The sample driver uses cmake and should work with the usual cmake options and utilities.
 254 The standard build process builds the icd, the icd loader and all the tests.
 255
 256 Example debug build:
 257 ```
 258 cd YOUR_DEV_DIRECTORY  # cd to the root of the vk git repository
 259 export KHRONOS_ACCOUNT_NAME= <subversion login name for svn checkout of BIL>
 260 ./update_external_sources.sh  # fetches and builds glslang, llvm, LunarGLASS, and BIL
 261 cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug
 262 cd dbuild
 263 make
 264 ```
 265
 266 To run VK programs you must tell the icd loader where to find the libraries.
 267 This is described in a specification in the Khronos documentation Git
 268 repository.  See the file:
 269 https://gitlab.khronos.org/vulkan/vulkan/blob/master/ecosystem/LinuxICDs.txt
 270
 271 This specification describes both how ICDs and layers should be properly
 272 packaged, and how developers can point to ICDs and layers within their builds.
 273
 274
 275 ## Linux Test
 276
 277 The test executibles can be found in the dbuild/tests directory. The tests use the Google
 278 gtest infrastructure. Tests available so far:
 279 - vkbase: Test basic entry points
 280 - vk_blit_tests: Test VK Blits (copy, clear, and resolve)
 281 - vk_image_tests: Test VK image related calls needed by render_test
 282 - vk_render_tests: Render a single triangle with VK. Triangle will be in a .ppm in
 283 the current directory at the end of the test.
 284 - vk_layer_validation_tests: Test Vulkan layers.
 285
 286 There are also a few shell and Python scripts that run test collections (eg,
 287 `run_all_tests.sh`).
 288
 289 ## Linux Demos
 290
 291 The demos executables can be found in the dbuild/demos directory. The demos use DRI 3
 292 to render directly onto window surfaces.
 293 - vulkaninfo: report GPU properties
 294 - tri: a textured triangle
 295 - cube: a textured spinning cube
 296
 297 ## Linux Render Nodes
 298
 299 The render tests depend on access to DRM render nodes.
 300 To make that available, a couple of config files need to be created to set a module option
 301 and make accessible device files.
 302 The system will need to be rebooted with these files in place to complete initialization.
 303 These commands will create the config files.
 304
 305 ```
 306 sudo tee /etc/modprobe.d/drm.conf << EOF
 307 # Enable render nodes
 308 options drm rnodes=1
 309 EOF
 310 # this will add the rnodes=1 option into the boot environment
 311 sudo update-initramfs -k all -u
 312 ```
 313 ```
 314 sudo tee /etc/udev/rules.d/drm.rules << EOF
 315 # Add permissions to render nodes
 316 SUBSYSTEM=="drm", ACTION=="add", DEVPATH=="/devices/*/renderD*", MODE="020666"
 317 EOF
 318 ```
 319
 320 ## Windows System Requirements
 321
 322 Windows 7+ with additional required software packages:
 323
 324 - Microsoft Visual Studio 2013 Professional.  Note: it is possible that lesser/older versions may work, but that has not been tested.
 325 - CMake (from http://www.cmake.org/download/).  Notes:
 326   - In order to build the VkTrace tools, you need at least version 3.0.
 327   - Tell the installer to "Add CMake to the system PATH" environment variable.
 328 - Python 3 (from https://www.python.org/downloads).  Notes:
 329   - Select to install the optional sub-package to add Python to the system PATH environment variable.
 330   - 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
 331 - Git (from http://git-scm.com/download/win).
 332   - 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.
 333   - Tell the installer to allow it to be used for "Developer Prompt" as well as "Git Bash".
 334   - Tell the installer to treat line endings "as is" (i.e. both DOS and Unix-style line endings).
 335 - Image Magick is used by the tests to compare images (from http://www.imagemagick.org/script/binary-releases.php)
 336   - Install each a 32-bit and a 64-bit version, as the 64-bit installer does not install the 32-bit libraries and tools.
 337     - For example:
 338       - 64-bit: http://www.imagemagick.org/download/binaries/ImageMagick-6.9.3-1-Q16-x64-dll.exe
 339       - 32-bit: http://www.imagemagick.org/download/binaries/ImageMagick-6.9.3-1-Q16-x86-dll.exe
 340   - For each of the installs, be sure to check box to "Install development headers and libraries"
 341 - glslang is required for demos and tests.
 342   - You can download and configure it (in a peer directory) here: https://github.com/KhronosGroup/glslang/blob/master/README.md
 343   - 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:
 344     - update_external_sources.bat --build-glslang
 345
 346 Optional software packages:
 347
 348 - Cygwin (from https://www.cygwin.com/).  Notes:
 349   - Cygwin provides some Linux-like tools, which are valuable for obtaining the source code, and running CMake.
 350     Especially valuable are the BASH shell and git packages.
 351   - If you don't want to use Cygwin, there are other shells and environments that can be used.
 352     You can also use a Git package that doesn't come from Cygwin.
 353
 354 ## Windows Build
 355
 356 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.
 357
 358 Example debug x64 build (e.g. in a "Developer Command Prompt for VS2013" window):
 359 ```
 360 cd LoaderAndTools  # cd to the root of the Vulkan git repository
 361 update_external_sources.bat --all
 362 mkdir build
 363 cd build
 364 cmake -G "Visual Studio 12 Win64" ..
 365 ```
 366
 367 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.
 368
 369 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.
 370
 371 To run VK programs you must tell the icd loader where to find the libraries.
 372 This is described in a specification in the Khronos documentation Git
 373 repository.  See the file:
 374 https://gitlab.khronos.org/vulkan/vulkan/blob/master/ecosystem/WindowsICDs.txt
 375
 376 This specification describes both how ICDs and layers should be properly
 377 packaged, and how developers can point to ICDs and layers within their builds.
 378
 379 ### Windows 64-bit Installation Notes
 380 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.
 381
 382 To do this, simply create and build the release versions of each target:
 383 ```
 384 cd LoaderAndTools  # cd to the root of the Vulkan git repository
 385 update_external_sources.bat --all
 386 mkdir build
 387 cd build
 388 cmake -G "Visual Studio 12 Win64" ..
 389 msbuild ALL_BUILD.vcxproj /p:Platform=x64 /p:Configuration=Release
 390 mkdir build32
 391 cd build32
 392 cmake -G "Visual Studio 12" ..
 393 msbuild ALL_BUILD.vcxproj /p:Platform=x86 /p:Configuration=Release
 394 ```
 395