source: x/installing/mesa.xml@ fedbe2f

12.1 ken/TL2024 lazarus rahul/power-profiles-daemon trunk xry111/llvm18
Last change on this file since fedbe2f was 2fea08c, checked in by Douglas R. Reno <renodr@…>, 4 months ago

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