docs/install.rst

   1 Compiling and Installing
   2 ========================
   3
   4 .. toctree::
   5    :maxdepth: 1
   6    :hidden:
   7
   8    meson
   9
  10 1. Prerequisites for building
  11 -----------------------------
  12
  13 1.1 General
  14 ~~~~~~~~~~~
  15
  16 Build system
  17 ^^^^^^^^^^^^
  18
  19 -  `Meson <https://mesonbuild.com>`__ is required when building on \*nix
  20    platforms and on Windows.
  21 -  Android Build system when building as native Android component. Meson
  22    is used when building ARC.
  23
  24 Compiler
  25 ^^^^^^^^
  26
  27 The following compilers are known to work, if you know of others or
  28 you're willing to maintain support for other compiler get in touch.
  29
  30 -  GCC 8.0.0 or later (some parts of Mesa may require later versions)
  31 -  Clang 5.0 or later (some parts of Mesa may require later versions)
  32 -  Microsoft Visual Studio 2019 Version 16.11 or later and
  33    Windows SDK of at least 20348 is required, for building on Windows.
  34
  35 Third party/extra tools.
  36 ^^^^^^^^^^^^^^^^^^^^^^^^
  37
  38 -  `Python <https://www.python.org/>`__ - Python 3.5 or newer is required.
  39 -  `Python Mako module <http://www.makotemplates.org/>`__ - Python Mako
  40    module is required. Version 0.8.0 or later should work.
  41 -  Lex / Yacc - for building the Mesa IR and GLSL compiler.
  42
  43    On Linux systems, Flex and Bison versions 2.5.35 and 2.4.1,
  44    respectively, (or later) should work. On Windows with MinGW, install
  45    Flex and Bison with:
  46
  47    .. code-block:: console
  48
  49       mingw-get install msys-flex msys-bison
  50
  51    For MSVC on Windows, install `Win
  52    flex-bison <http://winflexbison.sourceforge.net/>`__.
  53
  54 .. note::
  55
  56    Some versions can be buggy (e.g. Flex 2.6.2) so do try others
  57    if things fail.
  58
  59 1.2 Requirements
  60 ~~~~~~~~~~~~~~~~
  61
  62 The requirements depends on the features selected at configure stage.
  63 Check/install the respective development package as prompted by the
  64 configure error message.
  65
  66 Here are some common ways to retrieve most/all of the dependencies based
  67 on the packaging tool used by your distro.
  68
  69 .. code-block:: console
  70
  71      zypper source-install --build-deps-only Mesa # openSUSE/SLED/SLES
  72      yum-builddep mesa # yum Fedora, OpenSuse(?)
  73      dnf builddep mesa # dnf Fedora
  74      apt-get build-dep mesa # Debian and derivatives
  75      ... # others
  76
  77 2. Building with meson
  78 ----------------------
  79
  80 **Meson >= 0.46.0 is required**
  81
  82 Meson is the latest build system in mesa, it is currently able to build
  83 for \*nix systems like Linux and BSD, macOS, Haiku, and Windows.
  84
  85 The general approach is:
  86
  87 .. code-block:: console
  88
  89      meson builddir/
  90      ninja -C builddir/
  91      sudo ninja -C builddir/ install
  92
  93 On Windows you can also use the Visual Studio backend
  94
  95 .. code-block:: console
  96
  97      meson builddir --backend=vs
  98      cd builddir
  99      msbuild mesa.sln /m
 100
 101 Please read the :doc:`detailed meson instructions <meson>` for more
 102 information
 103
 104 3. Running against a local build
 105 --------------------------------
 106
 107 It's often necessary or useful when debugging driver issues or testing new
 108 branches to run against a local build of Mesa without doing a system-wide
 109 install.  To do this, choose a temporary location for the install.  A directory
 110 called ``installdir`` inside your mesa tree is as good as anything.  All of the
 111 commands below will assume ``$MESA_INSTALLDIR`` is an absolute path to this
 112 location.
 113
 114 First, configure Mesa and install in the temporary location:
 115
 116 .. code-block:: console
 117
 118    meson builddir/ -Dprefix="$MESA_INSTALLDIR" OTHER_OPTIONS
 119    ninja -C builddir/ install
 120
 121 where ``OTHER_OPTIONS`` is replaced by any meson configuration options you may
 122 want.  For instance, if you want to build the LLVMpipe drivers, it would look
 123 like this:
 124
 125 .. code-block:: console
 126
 127    meson builddir/ -Dprefix="$MESA_INSTALLDIR" \
 128       -Dgallium-drivers=swrast -Dvulkan-drivers=swrast
 129    ninja -C builddir/ install
 130
 131 Once Mesa has built and installed to ``$MESA_INSTALLDIR``, you can run any app
 132 against your temporary install by setting the right environment variables.
 133 Which variable you have to set depends on the API.
 134
 135 OpenGL
 136 ~~~~~~
 137
 138 .. code-block:: console
 139
 140    LD_LIBRARY_PATH="$MESA_INSTALLDIR/lib64" glxinfo
 141
 142 You may need to use ``lib`` instead of ``lib64`` on some systems or a full
 143 library specifier on debian.  Look inside ``installdir`` for the directory that
 144 contains ``libGL.so`` and use that one.
 145
 146 Vulkan
 147 ~~~~~~
 148
 149 .. code-block:: console
 150
 151    VK_ICD_FILENAMES="$MESA_INSTALLDIR/share/vulkan/icd/my_icd.json" vulkaninfo
 152
 153 where ``my_icd.json`` is replaced with the actual ICD json file name.  This
 154 will depend on your driver.  For instance, the 64-bit Lavapipe driver ICD file
 155 is named ``lvp_icd.x86_64.json``.
 156
 157 OpenCL
 158 ~~~~~~
 159
 160 .. code-block:: console
 161
 162    OCL_ICD_VENDORS="$MESA_INSTALLDIR/etc/OpenCL/vendors" clinfo
 163
 164 Unlike Vulkan, OpenCL takes a path to the whole ``vendors`` folder and will
 165 enumerate any drivers found there.
 166
 167 Troubleshooting local builds
 168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 169
 170 If you are trying to run an app against a local build and it's not working,
 171 here are a few things to check:
 172
 173  1. Double-check your paths and try with the simplest app you can.  Before
 174     banging your head on a Steam game, make sure your path works with
 175     ``glxgears`` first.
 176
 177  2. Watch out for wrapper scripts.  Some more complex apps such as games have
 178     big start-up scripts.  Sometimes those scripts scrub the environment or set
 179     ``LD_LIBRARY_PATH`` to something in the game's install directory.
 180
 181  3. Is your Mesa build the same arch as your app?  Lots of games are still
 182     32-bit and your Mesa build is probably 64-bit by default.
 183
 184  4. 32 and 64-bit builds in the same local install directory doesn't typically
 185     work.  Distributions go to great lengths to make this work in your system
 186     install and it's hard to get it right for a local install.  If you've
 187     recently built 64-bit and are now building 32-bit, throw away the install
 188     directory first to prevent conflicts.
 189
 190 4. Building with AOSP (Android)
 191 -------------------------------
 192
 193 <TODO>
 194
 195 5. Library Information
 196 ----------------------
 197
 198 When compilation has finished, look in the top-level ``lib/`` (or
 199 ``lib64/``) directory. You'll see a set of library files similar to
 200 this:
 201
 202 .. code-block:: console
 203
 204    lrwxrwxrwx    1 brian    users          10 Mar 26 07:53 libGL.so -> libGL.so.1*
 205    lrwxrwxrwx    1 brian    users          19 Mar 26 07:53 libGL.so.1 -> libGL.so.1.5.060100*
 206    -rwxr-xr-x    1 brian    users     3375861 Mar 26 07:53 libGL.so.1.5.060100*
 207    lrwxrwxrwx    1 brian    users          14 Mar 26 07:53 libOSMesa.so -> libOSMesa.so.6*
 208    lrwxrwxrwx    1 brian    users          23 Mar 26 07:53 libOSMesa.so.6 -> libOSMesa.so.6.1.060100*
 209    -rwxr-xr-x    1 brian    users       23871 Mar 26 07:53 libOSMesa.so.6.1.060100*
 210
 211 **libGL** is the main OpenGL library (i.e. Mesa), while **libOSMesa** is
 212 the OSMesa (Off-Screen) interface library.
 213
 214 If you built the DRI hardware drivers, you'll also see the DRI drivers:
 215
 216 .. code-block:: console
 217
 218    -rwxr-xr-x   1 brian users 16895413 Jul 21 12:11 i915_dri.so
 219    -rwxr-xr-x   1 brian users 16895413 Jul 21 12:11 i965_dri.so
 220    -rwxr-xr-x   1 brian users 11849858 Jul 21 12:12 r200_dri.so
 221    -rwxr-xr-x   1 brian users 11757388 Jul 21 12:12 radeon_dri.so
 222
 223 If you built with Gallium support, look in lib/gallium/ for
 224 Gallium-based versions of libGL and device drivers.
 225
 226 6. Building OpenGL programs with pkg-config
 227 -------------------------------------------
 228
 229 Running ``ninja install`` will install package configuration files for
 230 the pkg-config utility.
 231
 232 When compiling your OpenGL application you can use pkg-config to
 233 determine the proper compiler and linker flags.
 234
 235 For example, compiling and linking a GLUT application can be done with:
 236
 237 .. code-block:: console
 238
 239       gcc `pkg-config --cflags --libs glut` mydemo.c -o mydemo