1 Compiling and Installing
2 ========================
10 1. Prerequisites for building
11 -----------------------------
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.
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.
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.
35 Third party/extra tools.
36 ^^^^^^^^^^^^^^^^^^^^^^^^
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.
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
47 .. code-block:: console
49 mingw-get install msys-flex msys-bison
51 For MSVC on Windows, install `Win
52 flex-bison <http://winflexbison.sourceforge.net/>`__.
56 Some versions can be buggy (e.g. Flex 2.6.2) so do try others
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.
66 Here are some common ways to retrieve most/all of the dependencies based
67 on the packaging tool used by your distro.
69 .. code-block:: console
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
77 2. Building with meson
78 ----------------------
80 **Meson >= 0.46.0 is required**
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.
85 The general approach is:
87 .. code-block:: console
91 sudo ninja -C builddir/ install
93 On Windows you can also use the Visual Studio backend
95 .. code-block:: console
97 meson builddir --backend=vs
101 Please read the :doc:`detailed meson instructions <meson>` for more
104 3. Running against a local build
105 --------------------------------
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
114 First, configure Mesa and install in the temporary location:
116 .. code-block:: console
118 meson builddir/ -Dprefix="$MESA_INSTALLDIR" OTHER_OPTIONS
119 ninja -C builddir/ install
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
125 .. code-block:: console
127 meson builddir/ -Dprefix="$MESA_INSTALLDIR" \
128 -Dgallium-drivers=swrast -Dvulkan-drivers=swrast
129 ninja -C builddir/ install
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.
138 .. code-block:: console
140 LD_LIBRARY_PATH="$MESA_INSTALLDIR/lib64" glxinfo
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.
149 .. code-block:: console
151 VK_ICD_FILENAMES="$MESA_INSTALLDIR/share/vulkan/icd/my_icd.json" vulkaninfo
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``.
160 .. code-block:: console
162 OCL_ICD_VENDORS="$MESA_INSTALLDIR/etc/OpenCL/vendors" clinfo
164 Unlike Vulkan, OpenCL takes a path to the whole ``vendors`` folder and will
165 enumerate any drivers found there.
167 Troubleshooting local builds
168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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:
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
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.
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.
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.
190 4. Building with AOSP (Android)
191 -------------------------------
195 5. Library Information
196 ----------------------
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
202 .. code-block:: console
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*
211 **libGL** is the main OpenGL library (i.e. Mesa), while **libOSMesa** is
212 the OSMesa (Off-Screen) interface library.
214 If you built the DRI hardware drivers, you'll also see the DRI drivers:
216 .. code-block:: console
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
223 If you built with Gallium support, look in lib/gallium/ for
224 Gallium-based versions of libGL and device drivers.
226 6. Building OpenGL programs with pkg-config
227 -------------------------------------------
229 Running ``ninja install`` will install package configuration files for
230 the pkg-config utility.
232 When compiling your OpenGL application you can use pkg-config to
233 determine the proper compiler and linker flags.
235 For example, compiling and linking a GLUT application can be done with:
237 .. code-block:: console
239 gcc `pkg-config --cflags --libs glut` mydemo.c -o mydemo