source: x/installing/mesa.xml@ c833c06

trunk
Last change on this file since c833c06 was c833c06, checked in by Bruce Dubbs <bdubbs@…>, 5 weeks ago

Changes for mesa and xorg-server.

The patch for xorg-server, xorg-server-21.1.13-tearfree_backport-2.patch,
was changed to a -2 version to allow the package to build with gcc14.

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