gitlab-ci: fix testing whether a variable with a given name is set or not
[mesa.git] / 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