BUILD.md

   1 # Build Instructions
   2 This project fully supports Linux today.
   3 Support for Windows is for the loader and layers (additional info below).  Additional Windows support will be coming in Q1'15.
   4 Support for Android is TBD.
   5
   6 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).
   7
   8 ##Linux System Requirements
   9 Ubuntu 14.10 needed for DRI 3
  10
  11 ```
  12 sudo apt-get install git subversion cmake libgl1-mesa-dev freeglut3-dev libglm-dev libpng12-dev libmagickwand-dev qt5-default
  13 sudo apt-get build-dep mesa
  14 ```
  15 Warning: Recent versions of 14.10 have **REMOVED** DRI 3.
  16 Version: 2:2.99.914-1~exp1ubuntu4.1 is known to work.
  17 To see status of this package:
  18 ```
  19 dpkg -s xserver-xorg-video-intel
  20 ```
  21
  22 Note:
  23 Version 2:2.99.914-1~exp1ubuntu4.2 does not work anymore.
  24 To install the working driver from launchpadlibrarian.net:
  25 - Remove the current driver:
  26 ```
  27 sudo apt-get purge xserver-xorg-video-intel
  28 ```
  29 - Download the old driver:
  30 ```
  31 wget http://launchpadlibrarian.net/189418339/xserver-xorg-video-intel_2.99.914-1%7Eexp1ubuntu4.1_amd64.deb
  32 ```
  33 - Install the driver:
  34 ```
  35 sudo dpkg -i xserver-xorg-video-intel_2.99.914-1~exp1ubuntu4.1_amd64.deb
  36 ```
  37 - Either restart Ubuntu or just X11.
  38
  39 ##Linux Build
  40
  41 The sample driver uses cmake and should work with the usual cmake options and utilities.
  42 The standard build process builds the icd, the icd loader and all the tests.
  43
  44 Example debug build:
  45 ```
  46 cd GL-Next  # cd to the root of the xgl git repository
  47 export KHRONOS_ACCOUNT_NAME= <subversion login name for svn checkout of BIL>
  48 ./update_external_sources.sh  # fetches and builds glslang, llvm, LunarGLASS, and BIL
  49 cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug
  50 cd dbuild
  51 make
  52 ```
  53
  54 To run XGL programs you must tell the icd loader where to find the libraries. Set the
  55 environment variable LIBXGL_DRIVERS_PATH to the driver path. For example:
  56 ```
  57 export LIBXGL_DRIVERS_PATH=$PWD/icd/intel
  58 ```
  59
  60 To enable debug and validation layers with your XGL programs you must tell the icd loader
  61 where to find the layer libraries. Set the environment variable LIBXGL_LAYERS_PATH to
  62 the layer folder and indicate the layers you want loaded via LIBXGL_LAYER_NAMES.
  63 For example, to enable the APIDump and DrawState layers, do:
  64 ```
  65 export LIBXGL_LAYERS_PATH=$PWD/layers
  66 export LIBXGL_LAYER_NAMES=APIDump:DrawState
  67 ```
  68
  69 ##Linux Test
  70
  71 The test executibles can be found in the dbuild/tests directory. The tests use the Google
  72 gtest infrastructure. Tests available so far:
  73 - xglinfo: Report GPU properties
  74 - xglbase: Test basic entry points
  75 - xgl_blit_tests: Test XGL Blits (copy, clear, and resolve)
  76 - xgl_image_tests: Test XGL image related calls needed by render_test
  77 - xgl_render_tests: Render a single triangle with XGL. Triangle will be in a .ppm in
  78 the current directory at the end of the test.
  79
  80 ##Linux Demos
  81
  82 The demos executables can be found in the dbuild/demos directory. The demos use DRI 3
  83 to render directly onto window surfaces.
  84 - tri: a textured triangle
  85 - cube: a textured spinning cube
  86
  87 ##Linux Render Nodes
  88
  89 The render tests depend on access to DRM render nodes.
  90 To make that available, a couple of config files need to be created to set a module option
  91 and make accessible device files.
  92 The system will need to be rebooted with these files in place to complete initialization.
  93 These commands will create the config files.
  94
  95 ```
  96 sudo tee /etc/modprobe.d/drm.conf << EOF
  97 # Enable render nodes
  98 options drm rnodes=1
  99 EOF
 100 # this will add the rnodes=1 option into the boot environment
 101 sudo update-initramfs -k all -u
 102 ```
 103 ```
 104 sudo tee /etc/udev/rules.d/drm.rules << EOF
 105 # Add permissions to render nodes
 106 SUBSYSTEM=="drm", ACTION=="add", DEVPATH=="/devices/*/renderD*", MODE="020666"
 107 EOF
 108 ```
 109
 110 ##Windows System Requirements
 111
 112 Windows 7+ with additional, software:
 113
 114 - Microsoft Visual Studio 2013 Professional.  Note: it is possible that lesser/older versions may work, but that has not been tested.
 115 - CMake (from http://www.cmake.org/cmake/resources/software.html).  Note: Configure to add itself to the system PATH environment variable.
 116 - Python 3 (from https://www.python.org/downloads).  Note: Configure to add itself to the system PATH environment variable.
 117 - Cygwin (especially a BASH shell and git packages--from https://www.cygwin.com/).
 118
 119 ##Windows Build
 120
 121 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.
 122
 123 Example debug build:
 124 ```
 125 cd GL-Next  # cd to the root of the xgl git repository
 126 mkdir _out64
 127 cd _out64
 128 cmake -G "Visual Studio 12 Win64" ..
 129 ```
 130
 131 At this point, you can use Windows Explorer to launch Visual Studio by double-clicking on the "XGL.sln" file in the _out64 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 "_out64" folder.
 132
 133 To run XGL programs you must have an appropriate icd (installable client driver) that is either installed in the C:\Windows\System32 folder, or pointed to by the
 134 environment variable LIBXGL_DRIVERS_PATH.  This environment variable cannot be set with Cygwin, but must be set via Windows, and may require a system restart in order for it to take effect.  Here is how to set this environment variable on a Windows 7 system:
 135
 136 - Launch Control Panel (e.g. Start->Control Panel)
 137 - Within the search box, type "environment variable" and click on "Edit the system environment variables" (or navigate there via "System and Security->System->Advanced system settings").
 138 - This will launch a window with several tabs, one of which is "Advanced".  Click on the "Environment Variables..." button.
 139 - For either "User variables" or "System variables" click "New...".
 140 - Enter "LIBXGL_DRIVERS_PATH" as the variable name, and an appropriate Windows path to where your driver DLL is (e.g. C:\Users\username\GL-Next\_out64\icd\drivername\Debug).
 141
 142 It is possible to specify multiple icd folders.  Simply use a semi-colon (i.e. ";") to separate folders in the environment variable.
 143
 144 The icd loader searches in all of the folders for files that are named "XGL_*.dll" (e.g. "XGL_foo.dll").  It attempts to dynamically load these files, and look for appropriate functions.
 145
 146 To enable debug and validation layers with your XGL programs you must tell the icd loader
 147 where to find the layer libraries, and which ones you desire to use.  The default folder for layers is C:\Windows\System32.  However, you can use the following environment variables to specify alternate locations, and to specify which layers to use:
 148
 149 - LIBXGL_LAYERS_PATH (semi-colon-delimited set of folders to look for layers)
 150 - LIBXGL_LAYER_NAMES (color-delimited list of layer names)
 151
 152 For example, to enable the APIDump and DrawState layers, set:
 153
 154 - "LIBXGL_LAYERS_PATH" to "C:\Users\username\GL-Next\_out64\layers\Debug"
 155 - "LIBXGL_LAYER_NAMES to "APIDump:DrawState"
 156
 157 The icd loader searches in all of the folders for files that are named "XGLLayer*.dll" (e.g. "XGLLayerParamChecker.dll").  It attempts to dynamically load these files, and look for appropriate functions.