source: x/installing/mesa.xml@ 8040828

12.0 12.1 ken/TL2024 ken/tuningfonts lazarus plabs/newcss python3.11 rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18
Last change on this file since 8040828 was 8b095de, checked in by Bruce Dubbs <bdubbs@…>, 11 months ago

Update to mesa-23.1.5.
  • Property mode set to 100644
File size: 20.5 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY mesa-download-http "https://mesa.freedesktop.org/archive/mesa-&mesa-version;.tar.xz">
8 <!ENTITY mesa-download-ftp "ftp://ftp.freedesktop.org/pub/mesa/mesa-&mesa-version;.tar.xz">
9 <!ENTITY mesa-md5sum "d532eeadbfef5913b34dd6a01e99f2ab">
10 <!ENTITY mesa-size "18 MB">
11 <!ENTITY mesa-buildsize "462 MB (with docs, add 221 MB for tests)">
12 <!ENTITY mesa-time "2.2 SBU (with docs; add 0.6 SBU for tests; both with parallelism=4)">
13]>
14
15<sect1 id="mesa" xreflabel="Mesa-&mesa-version;">
16 <?dbhtml filename="mesa.html"?>
17
18
19 <title>Mesa-&mesa-version;</title>
20
21 <indexterm zone="mesa">
22 <primary sortas="a-Mesa">Mesa</primary>
23 </indexterm>
24
25 <sect2 role="package">
26 <title>Introduction to Mesa</title>
27
28 <para>
29 <application>Mesa</application> is an OpenGL compatible 3D graphics
30 library.
31 </para>
32
33 <note>
34 <para>
35 <application>Mesa</application> is updated relatively often. You may
36 want to use the latest available &mesa-major-minor;.x mesa version.
37 </para>
38 </note>
39
40 &lfs113_checked;
41
42 <bridgehead renderas="sect3">Package Information</bridgehead>
43 <itemizedlist spacing="compact">
44 <listitem>
45 <para>
46 Download (HTTP): <ulink url="&mesa-download-http;"/>
47 </para>
48 </listitem>
49 <listitem>
50 <para>
51 Download (FTP): <ulink url="&mesa-download-ftp;"/>
52 </para>
53 </listitem>
54 <listitem>
55 <para>
56 Download MD5 sum: &mesa-md5sum;
57 </para>
58 </listitem>
59 <listitem>
60 <para>
61 Download size: &mesa-size;
62 </para>
63 </listitem>
64 <listitem>
65 <para>
66 Estimated disk space required: &mesa-buildsize;
67 </para>
68 </listitem>
69 <listitem>
70 <para>
71 Estimated build time: &mesa-time;
72 </para>
73 </listitem>
74 </itemizedlist>
75
76 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
77 <itemizedlist spacing="compact">
78 <!-- 9 Apr 23. Change to unversioned patch since it never changes. -->
79 <listitem>
80 <para>
81 Recommended patch:
82 <ulink url="&patch-root;/mesa-add_xdemos-2.patch"/>
83 (installs 2 demo programs for testing Mesa - not needed if you
84 install the <ulink url="https://archive.mesa3d.org/demos/">
85 mesa-demos</ulink> package)
86 </para>
87 </listitem>
88 </itemizedlist>
89
90 <bridgehead renderas="sect3">Mesa Dependencies</bridgehead>
91
92 <bridgehead renderas="sect4">Required</bridgehead>
93 <para role="required">
94 <xref linkend="xorg7-lib"/>,
95 <xref linkend="libdrm"/>, and
96 <xref linkend="Mako"/>
97 </para>
98
99 <bridgehead renderas="sect4">Recommended</bridgehead>
100 <para role="recommended">
101
102 <xref role="first" linkend="libva"/> (to provide VA-API support for some
103 gallium drivers, note that there is a circular dependency. You must
104 build <application>libva</application> first without EGL and GLX support,
105 install this package, and rebuild <application>libva</application>),
106
107 <xref linkend="libvdpau"/> (to build VDPAU drivers),
108
109 <xref linkend="llvm"/> (required for Gallium3D, nouveau, and radeonsi
110 drivers and for swrast, the software rasterizer which is sometimes referred
111 to as llvmpipe. See <ulink role="nodep"
112 url="https://docs.mesa3d.org/systems.html"/> for more information), and
113
114 <xref linkend="wayland-protocols"/> (required for
115 <xref role="nodep" linkend='plasma5-build'/>,
116 GNOME, and recommended for <xref role="nodep" linkend='gtk3'/>)
117 </para>
118
119 <bridgehead renderas="sect4">Optional</bridgehead>
120 <para role="optional">
121 <xref linkend="libgcrypt"/>,
122 <xref linkend="libunwind"/>,
123 <xref linkend="lm_sensors"/> <!-- for libsensors according to Meson -->,
124 <xref linkend="nettle"/>,
125 <xref linkend="valgrind"/>,
126 <ulink url="https://archive.mesa3d.org/demos/">mesa-demos</ulink>
127 (provides more than 300 extra demos to test
128 <application>Mesa</application>; this includes the same programs added by
129 the patch above),
130 <ulink url="https://omxil.sourceforge.net/">Bellagio OpenMAX Integration
131 Layer</ulink> (for mobile platforms),
132 <ulink url="https://github.com/KhronosGroup/glslang">glslang</ulink>
133 (for vulkan drivers),
134 <ulink url="https://github.com/tizonia/tizonia-openmax-il/wiki/Tizonia-OpenMAX-IL/">
135 libtizonia</ulink>, and
136 <ulink url="https://github.com/KhronosGroup/Vulkan-Loader">Vulkan-Loader</ulink>
137 </para>
138<!--
139 <note>
140 <para>
141 The instructions below assume that
142 <application>LLVM</application> with the r600/amdgpu and host backends
143 and run-time type information (RTTI - needed for nouveau) are installed.
144 You will need to modify the instructions if you
145 choose not to install all of these. For an explanation of Gallium3D see
146 <ulink url="https://en.wikipedia.org/wiki/Gallium3D"/>.
147 </para>
148 </note>
149-->
150 </sect2>
151
152 <sect2 role="kernel" id="mesa-kernel"
153 xreflabel='Mesa Kernel Configuration'>
154 <title>Kernel Configuration</title>
155
156 <para>
157 Enable the following options in the kernel configuration and
158 recompile the kernel if necessary:
159 </para>
160
161 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
162 href="mesa-kernel.xml"/>
163
164 <note>
165 <para>
166 The corresponding Mesa Gallium3D driver name is provided as the
167 comment for the configuration entries. If you don't know the name
168 of the Mesa Gallium3D driver for your GPU, see <xref
169 linkend="mesa-gallium-drivers"/> below.
170 </para>
171
172 <para>
173 <option>CONFIG_DRM_RADEON</option>,
174 <option>CONFIG_DRM_AMDGPU</option>,
175 <option>CONFIG_DRM_NOUVEAU</option>, and
176 <option>CONFIG_DRM_I915</option> may require firmware.
177 See <xref linkend='postlfs-firmware'/> for details.
178 </para>
179
180 <para>
181 Selecting <option>CONFIG_DRM_RADEON</option> or
182 <option>CONFIG_DRM_AMDGPU</option> as
183 <quote><literal>y</literal></quote> is not recommended. If it is, any
184 required firmware must be built as a part of the kernel image or the
185 initramfs for the driver to function correctly.
186 </para>
187
188 <para>
189 The sub-entries under <option>CONFIG_DRM_AMDGPU</option> are used
190 to ensure the AMDGPU kernel driver supports all GPUs using the
191 <literal>radeonsi</literal> driver. They are not needed if you
192 won't need <option>CONFIG_DRM_AMDGPU</option> itself. They
193 may be unneeded for some GPU models.
194 </para>
195
196 <para>
197 For <literal>swrast</literal>, <option>CONFIG_DRM_VGEM</option>
198 is not strictly needed but recommended as an optimization.
199 </para>
200 </note>
201 <indexterm zone="mesa mesa-kernel">
202 <primary sortas="d-mesa">mesa</primary>
203 </indexterm>
204 </sect2>
205
206 <sect2 role="installation">
207 <title>Installation of Mesa</title>
208
209 <para>
210 If you have downloaded the xdemos patch (needed if testing the Xorg
211 installation per BLFS instructions), apply it by running the following
212 command:
213 </para>
214
215<!--<screen><userinput>patch -Np1 -i ../mesa-&mesa-version;-add_xdemos-1.patch</userinput></screen>-->
216<screen><userinput>patch -Np1 -i ../mesa-add_xdemos-2.patch</userinput></screen>
217
218 <!-- Note that freedreno, vc4, and virgl all need special support from
219 libdrm - renodr
220 For me, libdrm does not mention virgl, but mesa accepts it. AFAICS
221 freedreno is for qualcom hardware, libdrm will build for it on suitable
222 systems. VC4 is for the Broadcom VC4 used in the raspberry pi - ken -->
223<!--
224 <note>
225 <para>
226 The measurements above, and the Contents below, are for a full build.
227 Many people will not wish to install drivers they cannot use, so the
228 following paragraphs explain how to limit the drivers, and give an
229 example which can be be reduced or amended as necessary.
230 </para>
231 </note>
232
233-->
234<!--
235 <para>
236 The (non-gallium) DRI drivers available in X86 are auto, <emphasis>or
237 alternatively a choice from</emphasis> i915, i965, nouveau, r100, r200,
238 and swrast. Use 'auto' to build all available DRI drivers, or use an
239 empty string (DRI_DRIVERS="") if you wish to only build gallium drivers.
240 </para>
241
242 <para>
243 The platforms ("window systems") available for X86 linux are x11, wayland,
244 drm, and surfaceless. By not specifying anything, the meson
245 build-system will build for all these platforms if you have the
246 dependencies, identical to if you had specified '-Dplatforms=auto'.
247 </para>
248
249 <para>
250 Modify the commands below for your desired drivers. The drivers listed
251 below will cover most modern video cards and virtual machines. For help in
252 selecting drivers see <ulink url="https://docs.mesa3d.org/systems.html"/>.
253-->
254 <!-- these two don't seem to be mentioned in that mesa link -->
255<!--
256 For intel drivers, specify crocus for i965 gen 4 through to haswell, iris
257 for broadwell and later.
258 </para>
259
260 <note>
261 <para>
262 Although the nouveau drivers can be built for both gallium and dri, the
263 i915 driver can only be built for one or the other.
264 </para>
265 </note>
266
267<screen><userinput>GALLIUM_DRV="crocus,i915,iris,nouveau,r600,radeonsi,svga,swrast,virgl"
268DRI_DRIVERS="i965,nouveau"</userinput></screen>
269-->
270
271 <para>
272 Install <application>Mesa</application> by running the following
273 commands:
274 </para>
275
276<screen><userinput>mkdir build &amp;&amp;
277cd build &amp;&amp;
278
279meson setup \
280 --prefix=$XORG_PREFIX \
281 --buildtype=release \
282 -Dplatforms=x11,wayland \
283 -Dgallium-drivers=auto \
284 -Dvulkan-drivers="" \
285 -Dvalgrind=disabled \
286 -Dlibunwind=disabled \
287 .. &amp;&amp;
288
289ninja</userinput></screen>
290
291 <para>
292 To test the results, issue:
293 <command>meson configure -Dbuild-tests=true &amp;&amp; ninja test</command>.
294 <!-- Glibc performance regression:
295 https://sourceware.org/pipermail/libc-alpha/2023-August/150653.html
296 I can only hope it won't cause severe performace issue in
297 practice for now... -->
298 One test named <filename>SparseArrayTest</filename> is known to
299 timeout with Glibc-2.38.
300 </para>
301<!-- All 88 tests passed for me for 22.3.3 [pierre]
302 All 90 tests passed for me for 23.1.0 [bdubbs]
303-->
304
305 <para>
306 Now, as the <systemitem class="username">root</systemitem> user:
307 </para>
308
309<screen role="root"><userinput>ninja install</userinput></screen>
310
311 <para>
312 If desired, install the optional documentation by running
313 the following commands as the
314 <systemitem class="username">root</systemitem> user:
315 </para>
316
317<screen role="root"
318 remap="doc"><userinput>install -v -dm755 /usr/share/doc/mesa-&mesa-version; &amp;&amp;
319cp -rfv ../docs/* /usr/share/doc/mesa-&mesa-version;</userinput></screen>
320
321 </sect2>
322
323 <sect2 role="commands">
324 <title>Command Explanations</title>
325
326 <para>
327 <parameter>--buildtype=release</parameter>: This switch ensures a
328 fully-optimized build, and disables debug assertions which will
329 severely slow down the libraries in certain use-cases. Without this
330 switch, build sizes can span into the 2GB range.
331 </para>
332
333 <para>
334 <anchor id='mesa-gallium-drivers' xreflabel='Mesa Gallium3D Drivers'/>
335 <parameter>-Dgallium-drivers=auto</parameter>: This parameter
336 controls which Gallium3D drivers should be built.
337 <literal>auto</literal> selects all Gallium3D drivers available
338 for x86: <literal>r300</literal> (for ATI Radeon 9000 or Radeon X
339 series), <literal>r600</literal> (for AMD/ATI Radeon HD 2000-6000
340 series), <literal>radeonsi</literal> (for AMD Radeon HD 7000 or newer
341 AMD GPU models), <literal>nouveau</literal>
342 (for Supported NVIDIA GPUs, they are listed as all
343 <quote>3D features</quote> either <quote>DONE</quote> or
344 <quote>N/A</quote> in <ulink
345 url='https://nouveau.freedesktop.org/FeatureMatrix.html'>the Nouveau
346 status page</ulink>), <literal>virgl</literal> (for QEMU virtual GPU
347 with <application>virglrender</application> support; note that BLFS
348 <xref linkend='qemu'/> is not built with
349 <application>virglrender</application>), <literal>svga</literal>
350 (for VMWare virtual GPU), <literal>swrast</literal> (using CPU for 3D
351 rasterisation; note that it's much slower than using a modern
352 3D-capable GPU, so it should be only used if the GPU is not supported
353 by other drivers), <literal>iris</literal> (for Intel GPUs shipped
354 with Broadwell or newer CPUs), <literal>crocus</literal> (for Intel
355 GMA 3000, X3000 series, 4000 series, or X4000 series GPUs shipped with
356 chipsets, or Intel HD GPUs shipped with pre-Broadwell CPUs),
357 <literal>i915</literal> (for Intel GMA 900, 950, 3100, or 3150 GPUs
358 shipped with chipsets or Atom D/N 4xx/5xx CPUs). You may replace
359 <literal>auto</literal> with a comma-separated list to build only
360 a subset of these drivers if you precisely know which drivers you
361 need, for example
362 <option>-Dgallium-drivers=radeonsi,iris,swrast</option>.
363 </para>
364<!--
365 <para>
366 <parameter>-Dosmesa=true</parameter>: This switch enables building
367 the <filename class="libraryfile">libOSMesa</filename> library and
368 provides Gallium3D support in it. It requires the swrast gallium driver.
369 </para>
370-->
371
372 <para>
373 <parameter>-Dplatforms="..."</parameter>: This parameter
374 controls which windowing systems will be supported. Available
375 linux platforms are x11 and wayland.
376 </para>
377
378 <para>
379 <parameter>-Dvulkan-drivers=""</parameter>: This switch allows choosing
380 which Vulkan drivers are built. The default is auto, but this requires
381 the optional dependencies <application>glslang</application> and
382 <application>Vulkan-Loader</application>. Vulkan is a newer API
383 designed for utilizing the GPUs with a performance better than OpenGL,
384 but nothing in BLFS benefits from it for now. So we pass an empty
385 list in order to remove the need for these dependencies.
386 </para>
387
388 <para>
389 <parameter>-Dvalgrind=disabled</parameter>: This parameter disables
390 the usage of Valgrind during the build process. Remove this parameter
391 if you have Valgrind installed, and wish to check for memory leaks.
392 </para>
393
394 <para>
395 <parameter>-Dlibunwind=disabled</parameter>: This parameter disables
396 the usage of libunwind.
397 </para>
398
399 <para>
400 <command>meson configure -Dbuild-tests=true</command>: This command will
401 reconfigure the build to set <option>-Dbuild-tests=true</option>, but
402 keep the other options specified in the <command>meson setup</command>
403 command unchanged. It allows <command>ninja test</command> to build and
404 run unit tests.
405 </para>
406
407 <para>
408 <option>-Degl-native-platform="..."</option>: This parameter
409 controls which Embedded Graphics Library support will be built. Available
410 linux options are auto (default), x11, wayland, surfaceless, and drm.
411 </para>
412
413 </sect2>
414
415 <sect2 role="content">
416 <title>Contents</title>
417
418 <segmentedlist>
419 <segtitle>Installed Programs</segtitle>
420 <segtitle>Installed Libraries</segtitle><!-- in /usr/lib -->
421 <segtitle>Installed Drivers</segtitle><!-- in /usr/lib/<subdir> -->
422 <segtitle>Installed Directories</segtitle>
423
424 <seglistitem>
425 <seg>
426 glxgears and glxinfo
427 </seg>
428 <seg>
429 libEGL.so,
430 libGL.so,
431 libGLESv1_CM.so,
432 libGLESv2.so,
433 libgbm.so,
434 libglapi.so, and
435 libxatracker.so
436 </seg>
437 <seg>
438 <!-- d3dadapter9.so (optional)
439 I guess this is useless today, Wine applications use Vulkan
440 through libvkd3d, and new games with native Linux support
441 likely uses Vulkan directly. -->
442 <!-- Begin gallium DRI drivers (*_dri.so) and VA-API drivers
443 (*_drv_video.so): this is the full set -->
444 crocus_dri.so,
445 i915_dri.so,
446 iris_dri.so,
447 kms_swrast_dri.so,
448 nouveau_dri.so,
449 nouveau_drv_video.so,
450 r300_dri.so,
451 r600_dri.so,
452 r600_drv_video.so,
453 radeonsi_dri.so,
454 radeonsi_drv_video.so,
455 swrast_dri.so,
456 virtio_gpu_dri.so,
457 virtio_gpu_drv_video.so,
458 vmwgfx_dri.so,
459 <!-- End DRI Drivers -->
460 <!-- Begin VDPAU drivers -->
461 libvdpau_nouveau.so,
462 libvdpau_r300.so
463 libvdpau_r600.so, and
464 libvdpau_radeonsi.so
465 libvdpau_virtio_gpu.so
466 <!-- End VDPAU drivers -->
467 (Many of these drivers are hard-linked).
468 </seg>
469 <seg>
470 <!-- $XORG_PREFIX/include/GL is installed by xorg-protos -->
471 $XORG_PREFIX/{include/{EGL,GLES,GLES2,GLES3,KHR},
472 $XORG_PREFIX/lib/{dri,vdpau}},
473 $XORG_PREFIX/share/drirc.d (contains workarounds for various applications,
474 particularly browsers and games),
475 and /usr/share/doc/mesa-&mesa-version;
476 </seg>
477 </seglistitem>
478 </segmentedlist>
479
480 <variablelist>
481 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
482 <?dbfo list-presentation="list"?>
483 <?dbhtml list-presentation="table"?>
484
485 <varlistentry id="glxgears">
486 <term><command>glxgears</command></term>
487 <listitem>
488 <para>
489 is a GL demo useful for troubleshooting graphics
490 problems
491 </para>
492 <indexterm zone="mesa glxgears">
493 <primary sortas="b-glxgears">glxgears</primary>
494 </indexterm>
495 </listitem>
496 </varlistentry>
497
498 <varlistentry id="glxinfo">
499 <term><command>glxinfo</command></term>
500 <listitem>
501 <para>
502 is a diagnostic program that displays information about the
503 graphics hardware and installed GL libraries
504 </para>
505 <indexterm zone="mesa glxinfo">
506 <primary sortas="b-glxinfo">glxinfo</primary>
507 </indexterm>
508 </listitem>
509 </varlistentry>
510
511 <varlistentry id="libEGL">
512 <term><filename class="libraryfile">libEGL.so</filename></term>
513 <listitem>
514 <para>
515 provides a native platform graphics interface as
516 defined by the EGL-1.4 specification
517 </para>
518 <indexterm zone="mesa libEGL">
519 <primary sortas="c-libGL">libEGL.so</primary>
520 </indexterm>
521 </listitem>
522 </varlistentry>
523
524 <varlistentry id="libgbm">
525 <term><filename class="libraryfile">libgbm.so</filename></term>
526 <listitem>
527 <para>
528 is the <application>Mesa</application> Graphics Buffer
529 Manager library
530 </para>
531 <indexterm zone="mesa libgbm">
532 <primary sortas="c-libgbm">libgbm.so</primary>
533 </indexterm>
534 </listitem>
535 </varlistentry>
536
537 <varlistentry id="libGLESv1_CM">
538 <term><filename class="libraryfile">libGLESv1_CM.so</filename></term>
539 <listitem>
540 <para>
541 is the <application>Mesa</application> OpenGL ES 1.1 library
542 </para>
543 <indexterm zone="mesa libGLESv1_CM">
544 <primary sortas="c-libGLESv1_CM">libGLESv1_CM.so</primary>
545 </indexterm>
546 </listitem>
547 </varlistentry>
548
549 <varlistentry id="libGLES2">
550 <term><filename class="libraryfile">libGLES2.so</filename></term>
551 <listitem>
552 <para>
553 is the <application>Mesa</application> OpenGL ES 2.0 library
554 </para>
555 <indexterm zone="mesa libGLES2">
556 <primary sortas="c-libGLES2">libGLES2.so</primary>
557 </indexterm>
558 </listitem>
559 </varlistentry>
560
561 <varlistentry id="libGL">
562 <term><filename class="libraryfile">libGL.so</filename></term>
563 <listitem>
564 <para>
565 is the main <application>Mesa</application> OpenGL library
566 </para>
567 <indexterm zone="mesa libGL">
568 <primary sortas="c-libGL">libGL.so</primary>
569 </indexterm>
570 </listitem>
571 </varlistentry>
572
573 </variablelist>
574
575 </sect2>
576
577</sect1>
Note: See TracBrowser for help on using the repository browser.