source: x/installing/mesa.xml@ e929885

12.1 ken/TL2024 lazarus plabs/newcss python3.11 rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18
Last change on this file since e929885 was e929885, checked in by Douglas R. Reno <renodr@…>, 5 months ago

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