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