docs/install.rst

   1 Compiling and Installing
   2 ========================
   3
   4 #. `Prerequisites for building <#prereq-general>`__
   5
   6    -  `General prerequisites <#prereq-general>`__
   7    -  `For DRI and hardware acceleration <#prereq-dri>`__
   8
   9 #. `Building with meson <#meson>`__
  10 #. `Building with SCons (Windows/Linux) <#scons>`__
  11 #. `Building with AOSP (Android) <#android>`__
  12 #. `Library Information <#libs>`__
  13 #. `Building OpenGL programs with pkg-config <#pkg-config>`__
  14
  15 .. _prereq-general:
  16
  17 1. Prerequisites for building
  18 -----------------------------
  19
  20 1.1 General
  21 ~~~~~~~~~~~
  22
  23 Build system
  24 ^^^^^^^^^^^^
  25
  26 -  `meson <https://mesonbuild.com>`__ is required when building on \*nix
  27    platforms and is supported on windows.
  28 -  `SCons <http://www.scons.org/>`__ is an alternative for building on
  29    Windows and Linux.
  30 -  Android Build system when building as native Android component. Meson
  31    is used when when building ARC.
  32
  33 Compiler
  34 ^^^^^^^^
  35
  36 The following compilers are known to work, if you know of others or
  37 you're willing to maintain support for other compiler get in touch.
  38
  39 -  GCC 4.2.0 or later (some parts of Mesa may require later versions)
  40 -  clang - exact minimum requirement is currently unknown.
  41 -  Microsoft Visual Studio 2015 or later is required, for building on
  42    Windows.
  43
  44 Third party/extra tools.
  45 ^^^^^^^^^^^^^^^^^^^^^^^^
  46
  47 -  `Python <https://www.python.org/>`__ - Python is required. When
  48    building with scons 2.7 is required. When building with meson 3.5 or
  49    newer is required.
  50 -  `Python Mako module <http://www.makotemplates.org/>`__ - Python Mako
  51    module is required. Version 0.8.0 or later should work.
  52 -  lex / yacc - for building the Mesa IR and GLSL compiler.
  53
  54    On Linux systems, flex and bison versions 2.5.35 and 2.4.1,
  55    respectively, (or later) should work. On Windows with MinGW, install
  56    flex and bison with:
  57
  58    ::
  59
  60       mingw-get install msys-flex msys-bison
  61
  62    For MSVC on Windows, install `Win
  63    flex-bison <http://winflexbison.sourceforge.net/>`__.
  64
  65 **Note**: Some versions can be buggy (eg. flex 2.6.2) so do try others
  66 if things fail.
  67
  68 .. _prereq-dri:
  69
  70 1.2 Requirements
  71 ~~~~~~~~~~~~~~~~
  72
  73 The requirements depends on the features selected at configure stage.
  74 Check/install the respective -devel package as prompted by the configure
  75 error message.
  76
  77 Here are some common ways to retrieve most/all of the dependencies based
  78 on the packaging tool used by your distro.
  79
  80 ::
  81
  82      zypper source-install --build-deps-only Mesa # openSUSE/SLED/SLES
  83      yum-builddep mesa # yum Fedora, OpenSuse(?)
  84      dnf builddep mesa # dnf Fedora
  85      apt-get build-dep mesa # Debian and derivatives
  86      ... # others
  87
  88 .. _meson:
  89
  90 2. Building with meson
  91 ----------------------
  92
  93 **Meson >= 0.46.0 is required**
  94
  95 Meson is the latest build system in mesa, it is currently able to build
  96 for \*nix systems like Linux and BSD, macOS, Haiku, and Windows.
  97
  98 The general approach is:
  99
 100 ::
 101
 102      meson builddir/
 103      ninja -C builddir/
 104      sudo ninja -C builddir/ install
 105
 106 On windows you can also use the visual studio backend
 107
 108 ::
 109
 110      meson builddir --backend=vs
 111      cd builddir
 112      msbuild mesa.sln /m
 113
 114 Please read the `detailed meson instructions <meson.html>`__ for more
 115 information
 116
 117 .. _scons:
 118
 119 3. Building with SCons (Windows/Linux)
 120 --------------------------------------
 121
 122 To build Mesa with SCons on Linux or Windows do
 123
 124 ::
 125
 126        scons
 127
 128 The build output will be placed in
 129 build/\ *platform*-*machine*-*debug*/..., where *platform* is for
 130 example linux or windows, *machine* is x86 or x86_64, optionally
 131 followed by -debug for debug builds.
 132
 133 To build Mesa with SCons for Windows on Linux using the MinGW
 134 crosscompiler toolchain do
 135
 136 ::
 137
 138        scons platform=windows toolchain=crossmingw machine=x86 libgl-gdi
 139
 140 This will create:
 141
 142 -  build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll — Mesa
 143    + Gallium + softpipe (or llvmpipe), binary compatible with Windows's
 144    opengl32.dll
 145
 146 Put them all in the same directory to test them. Additional information
 147 is available in `README.WIN32 <README.WIN32>`__.
 148
 149 .. _android:
 150
 151 4. Building with AOSP (Android)
 152 -------------------------------
 153
 154 Currently one can build Mesa for Android as part of the AOSP project,
 155 yet your experience might vary.
 156
 157 In order to achieve that one should update their local manifest to point
 158 to the upstream repo, set the appropriate BOARD_GPU_DRIVERS and build
 159 the libGLES_mesa library.
 160
 161 FINISHME: Improve on the instructions add references to Rob H
 162 repos/Jenkins, Android-x86 and/or other resources.
 163
 164 .. _libs:
 165
 166 5. Library Information
 167 ----------------------
 168
 169 When compilation has finished, look in the top-level ``lib/`` (or
 170 ``lib64/``) directory. You'll see a set of library files similar to
 171 this:
 172
 173 ::
 174
 175    lrwxrwxrwx    1 brian    users          10 Mar 26 07:53 libGL.so -> libGL.so.1*
 176    lrwxrwxrwx    1 brian    users          19 Mar 26 07:53 libGL.so.1 -> libGL.so.1.5.060100*
 177    -rwxr-xr-x    1 brian    users     3375861 Mar 26 07:53 libGL.so.1.5.060100*
 178    lrwxrwxrwx    1 brian    users          14 Mar 26 07:53 libOSMesa.so -> libOSMesa.so.6*
 179    lrwxrwxrwx    1 brian    users          23 Mar 26 07:53 libOSMesa.so.6 -> libOSMesa.so.6.1.060100*
 180    -rwxr-xr-x    1 brian    users       23871 Mar 26 07:53 libOSMesa.so.6.1.060100*
 181
 182 **libGL** is the main OpenGL library (i.e. Mesa), while **libOSMesa** is
 183 the OSMesa (Off-Screen) interface library.
 184
 185 If you built the DRI hardware drivers, you'll also see the DRI drivers:
 186
 187 ::
 188
 189    -rwxr-xr-x   1 brian users 16895413 Jul 21 12:11 i915_dri.so
 190    -rwxr-xr-x   1 brian users 16895413 Jul 21 12:11 i965_dri.so
 191    -rwxr-xr-x   1 brian users 11849858 Jul 21 12:12 r200_dri.so
 192    -rwxr-xr-x   1 brian users 11757388 Jul 21 12:12 radeon_dri.so
 193
 194 If you built with Gallium support, look in lib/gallium/ for
 195 Gallium-based versions of libGL and device drivers.
 196
 197 .. _pkg-config:
 198
 199 6. Building OpenGL programs with pkg-config
 200 -------------------------------------------
 201
 202 Running ``ninja install`` will install package configuration files for
 203 the pkg-config utility.
 204
 205 When compiling your OpenGL application you can use pkg-config to
 206 determine the proper compiler and linker flags.
 207
 208 For example, compiling and linking a GLUT application can be done with:
 209
 210 ::
 211
 212       gcc `pkg-config --cflags --libs glut` mydemo.c -o mydemo