source: x/installing/mesa.xml

trunk
Last change on this file was f2964cc, checked in by Tim Tassonis <stuff@…>, 3 days ago

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