source: x/lib/gtk4.xml@ d5da4e0

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

Update to gtk-4.16.1.
  • Property mode set to 100644
File size: 21.2 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 gtk4-download-http "&gnome-download-http;/gtk/&gtk4-minor;/gtk-&gtk4-version;.tar.xz">
8 <!ENTITY gtk4-download-ftp " ">
9 <!ENTITY gtk4-md5sum "d7bb643ef30d4611590964d82006fc78">
10 <!ENTITY gtk4-size "18 MB">
11 <!ENTITY gtk4-buildsize "914 MB (with docs; add 143 MB for tests)">
12 <!ENTITY gtk4-time "1.3 SBU (using parallelism=4; with docs; add 1.7 SBU for tests)">
13]>
14
15<sect1 id="gtk4" xreflabel="GTK-&gtk4-version;">
16 <?dbhtml filename="gtk4.html"?>
17
18 <title>GTK-&gtk4-version;</title>
19
20 <indexterm zone="gtk4">
21 <primary sortas="a-gtk4">GTK-4</primary>
22 </indexterm>
23
24 <sect2 role="package">
25 <title>Introduction to GTK 4</title>
26
27 <para>
28 The <application>GTK 4</application> package contains libraries used for
29 creating graphical user interfaces for applications.
30 </para>
31
32 &lfs122_checked;
33
34 <bridgehead renderas="sect3">Package Information</bridgehead>
35 <itemizedlist spacing="compact">
36 <listitem>
37 <para>
38 Download (HTTP): <ulink url="&gtk4-download-http;"/>
39 </para>
40 </listitem>
41 <listitem>
42 <para>
43 Download (FTP): <ulink url="&gtk4-download-ftp;"/>
44 </para>
45 </listitem>
46 <listitem>
47 <para>
48 Download MD5 sum: &gtk4-md5sum;
49 </para>
50 </listitem>
51 <listitem>
52 <para>
53 Download size: &gtk4-size;
54 </para>
55 </listitem>
56 <listitem>
57 <para>
58 Estimated disk space required: &gtk4-buildsize;
59 </para>
60 </listitem>
61 <listitem>
62 <para>
63 Estimated build time: &gtk4-time;
64 </para>
65 </listitem>
66 </itemizedlist>
67
68 <bridgehead renderas="sect3">GTK 4 Dependencies</bridgehead>
69
70 <bridgehead renderas="sect4">Required</bridgehead>
71 <para role="required">
72 <xref linkend="fribidi"/>,
73 <xref linkend="gdk-pixbuf"/>,
74 <xref linkend="graphene"/>,
75 <xref linkend="iso-codes"/>,
76 <xref linkend="libepoxy"/>,
77 <xref linkend="libxkbcommon"/>,
78 <xref linkend="pango"/>,
79 <xref linkend="pygobject3"/>, and
80 <xref linkend="wayland-protocols"/>
81 </para>
82
83 <bridgehead renderas="sect4">Recommended</bridgehead>
84 <para role="recommended">
85 <xref linkend="adwaita-icon-theme"/> (default for some gtk4 settings keys),
86 <xref linkend="gst10-plugins-bad"/>,
87 <xref linkend="glslc"/>,
88 <xref role='runtime' linkend="gst10-plugins-good"/> (runtime,
89 built with <xref role='nodep' linkend='libvpx'/>),
90 <xref linkend="hicolor-icon-theme"/> (needed for tests and for defaults), and
91 <xref linkend="librsvg"/>, and
92 <xref linkend="vulkan-loader"/>
93 </para>
94
95 <bridgehead renderas="sect4">Recommended (Required if building GNOME)</bridgehead>
96 <para role="recommended">
97 &gobject-introspection; and
98 <xref linkend="vulkan-loader"/>,
99 </para>
100
101 <bridgehead renderas="sect4">Optional</bridgehead>
102 <para role="optional">
103 <xref linkend="avahi"/> (for some tests),
104 <xref linkend="colord"/>,
105 <xref linkend="cups"/>,
106 <xref linkend="docutils"/>,
107 <xref linkend="gi-docgen"/>,
108 <xref role="runtime" linkend="highlight"/>
109 (runtime, only used by <command>gtk4-demo</command> for syntax
110 highlighting of demo source code),
111 <xref linkend="libcloudproviders"/>,
112 <xref linkend="sassc"/>,
113 <xref linkend="tracker3"/>,
114 <ulink url="https://github.com/OpenPrinting/cpdb-libs">cpdb</ulink>,
115 <ulink url="https://pypi.org/project/pydbus/">pydbus</ulink>
116 (for some tests), and
117 <ulink url="&sysprof-url;">sysprof</ulink>
118 </para>
119
120 </sect2>
121
122 <sect2 role="installation">
123 <title>Installation of GTK 4</title>
124
125 <para>
126 Install <application>GTK 4</application> by running the following
127 commands:
128 </para>
129
130<screen><userinput>mkdir build &amp;&amp;
131cd build &amp;&amp;
132
133meson setup --prefix=/usr \
134 --buildtype=release \
135 -D broadway-backend=true \
136 -D introspection=enabled \
137 -D vulkan=enabled \
138 .. &amp;&amp;
139ninja</userinput></screen>
140
141 <para>
142 If you have <xref linkend='gi-docgen'/> installed and wish to build
143 the API documentation for this package, issue:
144 </para>
145
146<screen remap='doc'><userinput>sed "s@'doc'@&amp; / 'gtk-&gtk4-version;'@" -i ../docs/reference/meson.build &amp;&amp;
147meson configure -D documentation=true &amp;&amp;
148ninja</userinput></screen>
149
150 <para>
151 To run the tests, issue:
152 </para>
153
154 <screen remap='test'><userinput>LIBGL_ALWAYS_SOFTWARE=1 \
155dbus-run-session meson test --setup x11 --no-suite needs-dmabuf</userinput></screen>
156
157 <para>
158 If you are in a Wayland session, replace the two occurences of
159 <literal>x11</literal> with <literal>wayland</literal>.
160
161 One test is known to fail if
162 <ulink url="https://gitlab.gnome.org/GNOME/cantarell-fonts">Cantrell fonts</ulink>
163 are not installed.
164
165 About a dozen of tests are known to fail with minor (mostly invisible)
166 differences between the render output and the shipped reference image.
167 Issue
168 <command>grep 'not ok' meson-logs/testlog-x11.txt -B3</command>
169 (use <filename>testlog-wayland.txt</filename> if testing in a Wayland
170 session) to list them and the image files showing the render output,
171 the reference output, and the differences. You may take a look at
172 those images to ensure the differences are insignificant.
173
174 Two <literal>headless</literal> tests are known to fail without the
175 external dependency pydbus installed.
176
177 Many tests will fail if <filename>~/.config/gtk-4.0/settings.ini</filename>
178 exists and the gtk-modules line is not commented out.
179
180 Several other tests may fail for unknown reason.
181
182 On systems with NVIDIA graphics cards, the tests may take significantly
183 longer than the above test time.
184 <!--
185 On some systems as many as 212 tests may fail (out of over 6100) for
186 unknown reasons.
187
188 I hope this is gone with LIBGL_ALWAYS_SOFTWARE and -\-no-suite dmabuf.
189 If not please restore them. - xry111
190 -->
191 </para>
192<!-- [pierre]: 4.6.0, wayland: 727 OK; 2 Expected Fail; 1 Fail; 1 Skipped
193 [bdubbs]: 4.6.3, x11, 724 OK, 2 Expected Fail, 12 Fail, 1 Skipped
194 [pierre]: 4.6.6, wayland, 738 OK, 2 Expected Fail, 1 Fail, 1 Skipped
195 [pierre]: 4.6.7, wayland, 737 OK, 2 Expected Fail, 1 Fail, 1 Skipped, 1 Timeout
196 [bdubbs]: 4.6.7, x11, 758 OK, 2 Expected Fail, 9 Fail, 1 Skipped, 1 Timeout
197 [pierre]: 4.8.1, wayland, 765 OK, 2 Expected Fail, 2 Fail, 1 Skipped
198 [bdubbs]: 4.8.2, x11, 753 OK, 2 Expected Fail, 14 Fail, 1 Skipped
199 [pierre]: 4.8.3, wayland, 760 OK, 2 Expected Fail, 5 Fail, 3 Skipped
200 [bdubbs]: 4.10.0, x11, 701 OK, 0 Expected Fail, 15 Fail, 1 Skipped, 2 Timeout
201 above over ssh
202 [bdubbs]: 4.10.0, x11, 712 OK, 0 Expected Fail, 6 Fail, 1 Skipped, 0 Timeout
203 above on native x11
204 [bdubbs]: 4.12.0, x11, 1453 OK, 0 Expected Fail, 9 Fail, 5 Skipped, 0 Timeout
205 above on native x11
206 [bdubbs]: 4.12.1, x11, 1455 OK, 0 Expected Fail, 7 Fail, 5 Skipped, 0 Timeout
207 above on native x11
208 [renodr]: 4.12.4, x11, 1535 OK, 0 Expected Fail, 8 Fail, 5 Skipped, 0 Timeout
209 above on native X11
210 [rahul]: 4.14.1, wayland, 4174 OK, 0 Expected Fail, 81 Fail, 2 Skipped, 0 Timeout
211 above on native wayland (Plasma 6)
212 [renodr]: 4.14.2, wayland, 4211 OK, 0 Expected Fail, 43 Fail, 2 Skipped, 0 Timeout
213 above on wayland in GNOME
214 [renodr]: 4.14.3, wayland, 4250 OK, 0 Expected Fail, 42 Fail, 2 Skipped, 0 Timeout
215 above on wayland in GNOME
216 [renodr]: 4.14.5, x11, 4252 OK, 0 Expected Fail, 37 Fail, 13 Skipped, 0 Timeout
217 above on X11 in IceWM
218 [bdubbs]: 4.16.0, x11, 5896 OK, 0 Expected Fail, 212 Fail, 16 Skipped, 0 Timeout
219 above on X11 in XFCE. Over ssh there were 24 Timeouts
220 [xry111]: 4.16.1, x11, 6121 OK, 0 Expected Fail, 14 Fail, 16 Skipped, 0 Timeout
221 above on X11 (Xwayland) in GNOME
222 [xry111]: 4.16.1, wayland, 6120 OK, 0 Expected Fail, 15 Fail, 16 Skipped, 0 Timeout
223 above on wayland in GNOME
224 [xry111]: 4.16.1, x11, 6119 OK, 0 Expected Fail, 16 Fail, 16 Skipped, 0 Timeout
225 above on X11 (Xwayland) in Weston
226 [xry111]: 4.16.1, x11, 6106 OK, 0 Expected Fail, 18 Fail, 25 Skipped, 2 Timeout
227 above on wayland in Weston
228 [bdubbs]: 4.16.1, x11, 5909 OK, 0 Expected Fail, 203 Fail, 16 Skipped, 26 Timeout
229 Over ssh there were 26 Timeouts.
230 On a direct xfce run (same system) I now get 204 fail and 10 Timeouts.
231-->
232
233 <para>
234 Now, as the <systemitem class="username">root</systemitem> user:
235 </para>
236
237<screen role="root"><userinput>ninja install</userinput></screen>
238 </sect2>
239
240 <sect2 role="commands">
241 <title>Command Explanations</title>
242
243 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
244 href="../../xincludes/meson-buildtype-release.xml"/>
245
246 <para>
247 <parameter>-D broadway-backend=true</parameter>: This switch enables the
248 HTML5 GDK backend.
249 </para>
250
251 <para>
252 <parameter>-D introspection=enabled</parameter>: This switch enables
253 using GObject Introspection to generate GIR bindings
254 of this packages. These bindings are required by GNOME.
255 </para>
256
257 <para>
258 <option>-D cloudproviders=enabled</option>: Use this switch if you have
259 <xref linkend="libcloudproviders" role="nodep"/> installed and wish to
260 enable support for cloud providers in a file chooser window.
261 </para>
262
263 <para>
264 <option>-D tracker=enabled</option>: Use this switch if you have
265 <xref linkend="tracker3"/> installed and wish to use search functionality
266 when running a file chooser.
267 </para>
268
269 <para>
270 <option>-D colord=enabled</option>: Use this switch if you have
271 <xref linkend="colord"/> installed and wish to use colord with the CUPS
272 printing backend.
273 </para>
274
275 <para>
276 <option>-D man-pages=true</option>: Use this switch if you have
277 <xref linkend='docutils'/> installed and wish to generate the man
278 pages.
279 </para>
280
281 <para>
282 <option>-D sysprof=enabled</option>: Use this switch if you have
283 <ulink url="&sysprof-url;">sysprof</ulink> installed and wish to enable
284 tracing support for GTK4-based applications.
285 </para>
286
287 <para>
288 <option>-D vulkan=disabled</option>: Use this switch instead of
289 <parameter>-D vulkan=enabled</parameter> if you don't have
290 <xref linkend="vulkan-loader"/> or <xref linkend="glslc"/> installed.
291 It will disable the Vulkan backend that the upstream prefers to use
292 on Wayland-based graphical environments.
293 </para>
294
295 <para>
296 <envar>LIBGL_ALWAYS_SOFTWARE=1</envar>: Force the test suite to use
297 the softpipe or llvmpipe driver from Mesa. The test suite is so
298 sensitive that the minor differences caused by a different Mesa
299 driver can trigger test failures.
300 </para>
301
302 <para>
303 <parameter>--no-suite dmabuf</parameter>: Disable the tests requiring
304 <filename class='devicefile'>/dev/udmabuf</filename>. This file does
305 not exist if the feature is not enabled in the kernel configuration,
306 and even if it exists it cannot be accessed as unprivileged users.
307 </para>
308 </sect2>
309
310 <sect2 role="configuration">
311 <title>Configuring GTK 4</title>
312
313 <sect3 id="gtk4-config">
314 <title>Config Files</title>
315 <para>
316 <filename>~/.config/gtk-4.0/settings.ini</filename> and
317 <filename>/usr/share/gtk-4.0/settings.ini</filename>
318 </para>
319
320 <indexterm zone="gtk4 gtk4-config">
321 <primary sortas="e-AA.home-gtk4-settings.ini">~/.config/gtk-4.0/settings.ini</primary>
322 </indexterm>
323
324 <indexterm zone="gtk4 gtk4-config">
325 <primary
326 sortas="e-usr-share-path-settings.ini">/usr/share/gtk-4.0/settings.ini</primary>
327 </indexterm>
328 </sect3>
329
330 <sect3><title>Configuration Information</title>
331
332 <para>
333 <application>GTK 4</application> themes change the way a
334 <application>GTK 4</application> application looks. An icon theme can
335 be used to change the icons that appear on the application's toolbar.
336 If you have installed a <application>GTK 4</application> theme (e.g.
337 the Adwaita theme built in <application>GTK 4</application>),
338 an icon theme (such as <xref linkend="oxygen-icons"/>) and/or a font
339 (<xref linkend="dejavu-fonts"/>), you can set your preferences in
340 <filename>~/.config/gtk-4.0/settings.ini</filename>, or the default
341 system-wide configuration file (as the
342 <systemitem class="username">root</systemitem> user), in
343 <filename>/usr/share/gtk-4.0/settings.ini</filename>. For the local
344 user, an example is:
345 </para>
346
347<screen><userinput>mkdir -pv ~/.config/gtk-4.0
348cat &gt; ~/.config/gtk-4.0/settings.ini &lt;&lt; "EOF"
349<literal>[Settings]
350gtk-theme-name = <replaceable>Adwaita</replaceable>
351gtk-icon-theme-name = <replaceable>oxygen</replaceable>
352gtk-font-name = <replaceable>DejaVu Sans 12</replaceable>
353gtk-cursor-theme-size = <replaceable>18</replaceable>
354gtk-xft-antialias = <replaceable>1</replaceable>
355gtk-xft-hinting = <replaceable>1</replaceable>
356gtk-xft-hintstyle = <replaceable>hintslight</replaceable>
357gtk-xft-rgba = <replaceable>rgb</replaceable>
358gtk-cursor-theme-name = <replaceable>Adwaita</replaceable></literal>
359EOF</userinput></screen>
360
361 <para>
362 There are many settings keys, some with default values. You can find
363 them at <ulink
364 url="https://developer.gnome.org/gtk4/stable/GtkSettings.html">Settings:
365 GTK 4 Reference Manual</ulink>.
366 </para>
367
368 </sect3>
369 </sect2>
370
371 <sect2 role="content">
372 <title>Contents</title>
373
374 <segmentedlist>
375 <segtitle>Installed Programs</segtitle>
376 <segtitle>Installed Libraries</segtitle>
377 <segtitle>Installed Directories</segtitle>
378
379 <seglistitem>
380 <seg>
381 gtk4-broadwayd,
382 gtk4-builder-tool,
383 gtk4-demo,
384 gtk4-demo-application,
385 gtk4-encode-symbolic-svg,
386 gtk4-icon-browser,
387 gtk4-launch,
388 gtk4-node-editor,
389 gtk4-print-editor,
390 gtk4-query-settings,
391 gtk4-update-icon-cache, and
392 gtk4-widget-factory
393 </seg>
394 <seg>
395 libgtk-4.so
396 </seg>
397 <seg>
398 /usr/include/gtk-4.0,
399 /usr/lib/gtk-4.0, and
400 /usr/share/gtk-4.0
401 </seg>
402 </seglistitem>
403 </segmentedlist>
404
405 <variablelist>
406 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
407 <?dbfo list-presentation="list"?>
408 <?dbhtml list-presentation="table"?>
409
410 <varlistentry id="gtk4-broadwayd">
411 <term><command>gtk4-broadwayd</command></term>
412 <listitem>
413 <para>
414 provides support for displaying GTK 4 applications in a web
415 browser using HTML5 and web sockets
416 </para>
417 <indexterm zone="gtk4 gtk4-broadwayd">
418 <primary sortas="b-gtk4-broadwayd">gtk4-broadwayd</primary>
419 </indexterm>
420 </listitem>
421 </varlistentry>
422
423 <varlistentry id="gtk4-builder-tool">
424 <term><command>gtk4-builder-tool</command></term>
425 <listitem>
426 <para>
427 performs various operations on GtkBuilder .ui files
428 </para>
429 <indexterm zone="gtk4 gtk4-builder-tool">
430 <primary sortas="b-gtk4-builder-tool">gtk4-builder-tool</primary>
431 </indexterm>
432 </listitem>
433 </varlistentry>
434
435 <varlistentry id="gtk4-demo">
436 <term><command>gtk4-demo</command></term>
437 <listitem>
438 <para>
439 is a simple program that demonstrates some of the tasks that can be
440 done with GTK 4
441 </para>
442 <indexterm zone="gtk4 gtk4-demo">
443 <primary sortas="b-gtk4-demo">gtk4-demo</primary>
444 </indexterm>
445 </listitem>
446 </varlistentry>
447
448 <varlistentry id="gtk4-demo-application">
449 <term><command>gtk4-demo-application</command></term>
450 <listitem>
451 <para>
452 is a simple GTK 4 application which is useful for testing
453 </para>
454 <indexterm zone="gtk4 gtk4-demo-application">
455 <primary sortas="b-gtk4-demo-application">gtk4-demo-application</primary>
456 </indexterm>
457 </listitem>
458 </varlistentry>
459
460 <varlistentry id="gtk4-encode-symbolic-svg">
461 <term><command>gtk4-encode-symbolic-svg</command></term>
462 <listitem>
463 <para>
464 converts symbolic SVG icons into special PNG files. GTK 4 can load
465 and recolor these PNGs, just like original SVGs, but loading them
466 is much faster
467 </para>
468 <indexterm zone="gtk4 gtk4-encode-symbolic-svg">
469 <primary sortas="b-gtk4-encode-symbolic-svg">gtk4-encode-symbolic-svg</primary>
470 </indexterm>
471 </listitem>
472 </varlistentry>
473
474 <varlistentry id="gtk4-icon-browser">
475 <term><command>gtk4-icon-browser</command></term>
476 <listitem>
477 <para>
478 is a utility to explore the icons in the current icon theme. It
479 shows icons in various sizes, their symbolic variants when
480 available, as well as a description of the icon and its context
481 </para>
482 <indexterm zone="gtk4 gtk4-icon-browser">
483 <primary sortas="b-gtk4-icon-browser">gtk4-icon-browser</primary>
484 </indexterm>
485 </listitem>
486 </varlistentry>
487
488 <varlistentry id="gtk4-launch">
489 <term><command>gtk4-launch</command></term>
490 <listitem>
491 <para>
492 launches an application using the given name. The name should match
493 the application .desktop file name (as seen in
494 <filename class="directory">/usr/share/applications</filename>),
495 with or without the '.desktop' extension
496 </para>
497 <indexterm zone="gtk4 gtk-launch">
498 <primary sortas="b-gtk4-launch">gtk4-launch</primary>
499 </indexterm>
500 </listitem>
501 </varlistentry>
502
503 <varlistentry id="gtk4-node-editor">
504 <term><command>gtk4-node-editor</command></term>
505 <listitem>
506 <para>
507 is a utility to show and edit render node files. Such render
508 node files can be obtained e.g. from the GTK inspector
509 </para>
510 <indexterm zone="gtk4 gtk4-node-editor">
511 <primary sortas="b-gtk4-node-editor">gtk4-node-editor</primary>
512 </indexterm>
513 </listitem>
514 </varlistentry>
515
516 <varlistentry id="gtk4-print-editor">
517 <term><command>gtk4-print-editor</command></term>
518 <listitem>
519 <para>
520 is a simple program to demonstrate printing using GTK 4
521 applications
522 </para>
523 <indexterm zone="gtk4 gtk4-print-editor">
524 <primary sortas="b-gtk4-print-editor">gtk4-print-editor</primary>
525 </indexterm>
526 </listitem>
527 </varlistentry>
528
529 <varlistentry id="gtk4-query-settings">
530 <term><command>gtk4-query-settings</command></term>
531 <listitem>
532 <para>
533 provides a complete listing of all settings related to GTK 4
534 </para>
535 <indexterm zone="gtk4 gtk4-query-settings">
536 <primary sortas="b-gtk4-query-settings">gtk4-query-settings</primary>
537 </indexterm>
538 </listitem>
539 </varlistentry>
540
541 <varlistentry id="gtk4-update-icon-cache">
542 <term><command>gtk4-update-icon-cache</command></term>
543 <listitem>
544 <para>
545 is an icon theme caching utility that creates mmap()able cache
546 files for icon themes
547 </para>
548 <indexterm zone="gtk4 gtk4-update-icon-cache">
549 <primary sortas="b-gtk4-update-icon-cache">gtk4-update-icon-cache</primary>
550 </indexterm>
551 </listitem>
552 </varlistentry>
553
554 <varlistentry id="gtk4-widget-factory">
555 <term><command>gtk4-widget-factory</command></term>
556 <listitem>
557 <para>
558 is a program to view GTK 4 themes and widgets
559 </para>
560 <indexterm zone="gtk4 gtk4-widget-factory">
561 <primary sortas="b-gtk4-widget-factory">gtk4-widget-factory</primary>
562 </indexterm>
563 </listitem>
564 </varlistentry>
565
566 <varlistentry id="libgtk-4">
567 <term><filename class="libraryfile">libgtk-4.so</filename></term>
568 <listitem>
569 <para>
570 contains functions that provide an API to implement graphical user
571 interfaces
572 </para>
573 <indexterm zone="gtk4 libgtk-4">
574 <primary sortas="c-libgtk-4">libgtk-4.so</primary>
575 </indexterm>
576 </listitem>
577 </varlistentry>
578 </variablelist>
579 </sect2>
580</sect1>
Note: See TracBrowser for help on using the repository browser.