source: x/lib/gtk4.xml@ c87169be

trunk
Last change on this file since c87169be was c87169be, checked in by Xi Ruoyao <xry111@…>, 7 days ago

Some adjustment in gtk4, and fix a typo in glslc
  • Property mode set to 100644
File size: 18.7 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 "33666e441030f3a965d2a1d2834dda8a">
10 <!ENTITY gtk4-size "18 MB">
11 <!ENTITY gtk4-buildsize "913 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="colord"/>,
104 <xref linkend="cups"/>,
105 <xref linkend="docutils"/>,
106 <xref linkend="gi-docgen"/>,
107 <xref role="runtime" linkend="highlight"/>
108 (runtime, only used by <command>gtk4-demo</command> for syntax
109 highlighting of demo source code),
110 <xref linkend="libcloudproviders"/>,
111 <xref linkend="sassc"/>,
112 <xref linkend="tracker3"/>,
113 <ulink url="https://github.com/OpenPrinting/cpdb-libs">cpdb</ulink>, and
114 <ulink url="&sysprof-url;">sysprof</ulink>
115 </para>
116
117 </sect2>
118
119 <sect2 role="installation">
120 <title>Installation of GTK 4</title>
121
122 <para>
123 Install <application>GTK 4</application> by running the following
124 commands:
125 </para>
126
127<screen><userinput>mkdir build &amp;&amp;
128cd build &amp;&amp;
129
130meson setup --prefix=/usr \
131 --buildtype=release \
132 -D broadway-backend=true \
133 -D introspection=enabled \
134 -D vulkan=enabled \
135 .. &amp;&amp;
136ninja</userinput></screen>
137
138 <para>
139 If you have <xref linkend='gi-docgen'/> installed and wish to build
140 the API documentation for this package, issue:
141 </para>
142
143<screen remap='doc'><userinput>sed "s@'doc'@&amp; / 'gtk-&gtk4-version;'@" -i ../docs/reference/meson.build &amp;&amp;
144meson configure -D documentation=true &amp;&amp;
145ninja</userinput></screen>
146
147 <para>
148 To run the tests, issue: <command>dbus-run-session meson test --setup
149 x11</command>. If you are in a Wayland session, replace x11 with wayland.
150
151 Nine tests are known to fail if
152 <ulink url="https://gitlab.gnome.org/GNOME/cantarell-fonts">Cantrell fonts</ulink>
153 are not installed.
154
155 Many tests will fail if <filename>~/.config/gtk-4.0/settings.ini</filename>
156 exists and the gtk-modules line is not commented out.
157
158 On systems with NVIDIA graphics cards, the tests may take significantly
159 longer than the above test time.
160
161 On some systems as many as 212 tests may fail (out of over 6100) for
162 unknown reasons.
163 </para>
164<!-- [pierre]: 4.6.0, wayland: 727 OK; 2 Expected Fail; 1 Fail; 1 Skipped
165 [bdubbs]: 4.6.3, x11, 724 OK, 2 Expected Fail, 12 Fail, 1 Skipped
166 [pierre]: 4.6.6, wayland, 738 OK, 2 Expected Fail, 1 Fail, 1 Skipped
167 [pierre]: 4.6.7, wayland, 737 OK, 2 Expected Fail, 1 Fail, 1 Skipped, 1 Timeout
168 [bdubbs]: 4.6.7, x11, 758 OK, 2 Expected Fail, 9 Fail, 1 Skipped, 1 Timeout
169 [pierre]: 4.8.1, wayland, 765 OK, 2 Expected Fail, 2 Fail, 1 Skipped
170 [bdubbs]: 4.8.2, x11, 753 OK, 2 Expected Fail, 14 Fail, 1 Skipped
171 [pierre]: 4.8.3, wayland, 760 OK, 2 Expected Fail, 5 Fail, 3 Skipped
172 [bdubbs]: 4.10.0, x11, 701 OK, 0 Expected Fail, 15 Fail, 1 Skipped, 2 Timeout
173 above over ssh
174 [bdubbs]: 4.10.0, x11, 712 OK, 0 Expected Fail, 6 Fail, 1 Skipped, 0 Timeout
175 above on native x11
176 [bdubbs]: 4.12.0, x11, 1453 OK, 0 Expected Fail, 9 Fail, 5 Skipped, 0 Timeout
177 above on native x11
178 [bdubbs]: 4.12.1, x11, 1455 OK, 0 Expected Fail, 7 Fail, 5 Skipped, 0 Timeout
179 above on native x11
180 [renodr]: 4.12.4, x11, 1535 OK, 0 Expected Fail, 8 Fail, 5 Skipped, 0 Timeout
181 above on native X11
182 [rahul]: 4.14.1, wayland, 4174 OK, 0 Expected Fail, 81 Fail, 2 Skipped, 0 Timeout
183 above on native wayland (Plasma 6)
184 [renodr]: 4.14.2, wayland, 4211 OK, 0 Expected Fail, 43 Fail, 2 Skipped, 0 Timeout
185 above on wayland in GNOME
186 [renodr]: 4.14.3, wayland, 4250 OK, 0 Expected Fail, 42 Fail, 2 Skipped, 0 Timeout
187 above on wayland in GNOME
188 [renodr]: 4.14.5, x11, 4252 OK, 0 Expected Fail, 37 Fail, 13 Skipped, 0 Timeout
189 above on X11 in IceWM
190 [bdubbs]: 4.16.0, x11, 5896 OK, 0 Expected Fail, 212 Fail, 16 Skipped, 0 Timeout
191 above on X11 in XFCE. Over ssh there were 24 Timeouts
192-->
193
194 <para>
195 Now, as the <systemitem class="username">root</systemitem> user:
196 </para>
197
198<screen role="root"><userinput>ninja install</userinput></screen>
199 </sect2>
200
201 <sect2 role="commands">
202 <title>Command Explanations</title>
203
204 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
205 href="../../xincludes/meson-buildtype-release.xml"/>
206
207 <para>
208 <parameter>-D broadway-backend=true</parameter>: This switch enables the
209 HTML5 GDK backend.
210 </para>
211
212 <para>
213 <parameter>-D introspection=enabled</parameter>: This switch enables
214 using GObject Introspection to generate GIR bindings
215 of this packages. These bindings are required by GNOME.
216 </para>
217
218 <para>
219 <option>-D cloudproviders=enabled</option>: Use this switch if you have
220 <xref linkend="libcloudproviders" role="nodep"/> installed and wish to
221 enable support for cloud providers in a file chooser window.
222 </para>
223
224 <para>
225 <option>-D tracker=enabled</option>: Use this switch if you have
226 <xref linkend="tracker3"/> installed and wish to use search functionality
227 when running a file chooser.
228 </para>
229
230 <para>
231 <option>-D colord=enabled</option>: Use this switch if you have
232 <xref linkend="colord"/> installed and wish to use colord with the CUPS
233 printing backend.
234 </para>
235
236 <para>
237 <option>-D man-pages=true</option>: Use this switch if you have
238 <xref linkend='docutils'/> installed and wish to generate the man
239 pages.
240 </para>
241
242 <para>
243 <option>-D sysprof=enabled</option>: Use this switch if you have
244 <ulink url="&sysprof-url;">sysprof</ulink> installed and wish to enable
245 tracing support for GTK4-based applications.
246 </para>
247
248 <para>
249 <option>-D vulkan=disabled</option>: Use this switch instead of
250 <parameter>-D vulkan=enabled</parameter> if you don't have
251 <xref linkend="vulkan-loader"/> or <xref linkend="glslc"/> installed.
252 It will disable the Vulkan backend that the upstream prefers to use
253 on Wayland-based graphical environments.
254 </para>
255
256 </sect2>
257
258 <sect2 role="configuration">
259 <title>Configuring GTK 4</title>
260
261 <sect3 id="gtk4-config">
262 <title>Config Files</title>
263 <para>
264 <filename>~/.config/gtk-4.0/settings.ini</filename> and
265 <filename>/usr/share/gtk-4.0/settings.ini</filename>
266 </para>
267
268 <indexterm zone="gtk4 gtk4-config">
269 <primary sortas="e-AA.home-gtk4-settings.ini">~/.config/gtk-4.0/settings.ini</primary>
270 </indexterm>
271
272 <indexterm zone="gtk4 gtk4-config">
273 <primary
274 sortas="e-usr-share-path-settings.ini">/usr/share/gtk-4.0/settings.ini</primary>
275 </indexterm>
276 </sect3>
277
278 <sect3><title>Configuration Information</title>
279
280 <para>
281 <application>GTK 4</application> themes change the way a
282 <application>GTK 4</application> application looks. An icon theme can
283 be used to change the icons that appear on the application's toolbar.
284 If you have installed a <application>GTK 4</application> theme (e.g.
285 the Adwaita theme built in <application>GTK 4</application>),
286 an icon theme (such as <xref linkend="oxygen-icons"/>) and/or a font
287 (<xref linkend="dejavu-fonts"/>), you can set your preferences in
288 <filename>~/.config/gtk-4.0/settings.ini</filename>, or the default
289 system-wide configuration file (as the
290 <systemitem class="username">root</systemitem> user), in
291 <filename>/usr/share/gtk-4.0/settings.ini</filename>. For the local
292 user, an example is:
293 </para>
294
295<screen><userinput>mkdir -pv ~/.config/gtk-4.0
296cat &gt; ~/.config/gtk-4.0/settings.ini &lt;&lt; "EOF"
297<literal>[Settings]
298gtk-theme-name = <replaceable>Adwaita</replaceable>
299gtk-icon-theme-name = <replaceable>oxygen</replaceable>
300gtk-font-name = <replaceable>DejaVu Sans 12</replaceable>
301gtk-cursor-theme-size = <replaceable>18</replaceable>
302gtk-xft-antialias = <replaceable>1</replaceable>
303gtk-xft-hinting = <replaceable>1</replaceable>
304gtk-xft-hintstyle = <replaceable>hintslight</replaceable>
305gtk-xft-rgba = <replaceable>rgb</replaceable>
306gtk-cursor-theme-name = <replaceable>Adwaita</replaceable></literal>
307EOF</userinput></screen>
308
309 <para>
310 There are many settings keys, some with default values. You can find
311 them at <ulink
312 url="https://developer.gnome.org/gtk4/stable/GtkSettings.html">Settings:
313 GTK 4 Reference Manual</ulink>.
314 </para>
315
316 </sect3>
317 </sect2>
318
319 <sect2 role="content">
320 <title>Contents</title>
321
322 <segmentedlist>
323 <segtitle>Installed Programs</segtitle>
324 <segtitle>Installed Libraries</segtitle>
325 <segtitle>Installed Directories</segtitle>
326
327 <seglistitem>
328 <seg>
329 gtk4-broadwayd,
330 gtk4-builder-tool,
331 gtk4-demo,
332 gtk4-demo-application,
333 gtk4-encode-symbolic-svg,
334 gtk4-icon-browser,
335 gtk4-launch,
336 gtk4-node-editor,
337 gtk4-print-editor,
338 gtk4-query-settings,
339 gtk4-update-icon-cache, and
340 gtk4-widget-factory
341 </seg>
342 <seg>
343 libgtk-4.so
344 </seg>
345 <seg>
346 /usr/include/gtk-4.0,
347 /usr/lib/gtk-4.0, and
348 /usr/share/gtk-4.0
349 </seg>
350 </seglistitem>
351 </segmentedlist>
352
353 <variablelist>
354 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
355 <?dbfo list-presentation="list"?>
356 <?dbhtml list-presentation="table"?>
357
358 <varlistentry id="gtk4-broadwayd">
359 <term><command>gtk4-broadwayd</command></term>
360 <listitem>
361 <para>
362 provides support for displaying GTK 4 applications in a web
363 browser using HTML5 and web sockets
364 </para>
365 <indexterm zone="gtk4 gtk4-broadwayd">
366 <primary sortas="b-gtk4-broadwayd">gtk4-broadwayd</primary>
367 </indexterm>
368 </listitem>
369 </varlistentry>
370
371 <varlistentry id="gtk4-builder-tool">
372 <term><command>gtk4-builder-tool</command></term>
373 <listitem>
374 <para>
375 performs various operations on GtkBuilder .ui files
376 </para>
377 <indexterm zone="gtk4 gtk4-builder-tool">
378 <primary sortas="b-gtk4-builder-tool">gtk4-builder-tool</primary>
379 </indexterm>
380 </listitem>
381 </varlistentry>
382
383 <varlistentry id="gtk4-demo">
384 <term><command>gtk4-demo</command></term>
385 <listitem>
386 <para>
387 is a simple program that demonstrates some of the tasks that can be
388 done with GTK 4
389 </para>
390 <indexterm zone="gtk4 gtk4-demo">
391 <primary sortas="b-gtk4-demo">gtk4-demo</primary>
392 </indexterm>
393 </listitem>
394 </varlistentry>
395
396 <varlistentry id="gtk4-demo-application">
397 <term><command>gtk4-demo-application</command></term>
398 <listitem>
399 <para>
400 is a simple GTK 4 application which is useful for testing
401 </para>
402 <indexterm zone="gtk4 gtk4-demo-application">
403 <primary sortas="b-gtk4-demo-application">gtk4-demo-application</primary>
404 </indexterm>
405 </listitem>
406 </varlistentry>
407
408 <varlistentry id="gtk4-encode-symbolic-svg">
409 <term><command>gtk4-encode-symbolic-svg</command></term>
410 <listitem>
411 <para>
412 converts symbolic SVG icons into special PNG files. GTK 4 can load
413 and recolor these PNGs, just like original SVGs, but loading them
414 is much faster
415 </para>
416 <indexterm zone="gtk4 gtk4-encode-symbolic-svg">
417 <primary sortas="b-gtk4-encode-symbolic-svg">gtk4-encode-symbolic-svg</primary>
418 </indexterm>
419 </listitem>
420 </varlistentry>
421
422 <varlistentry id="gtk4-icon-browser">
423 <term><command>gtk4-icon-browser</command></term>
424 <listitem>
425 <para>
426 is a utility to explore the icons in the current icon theme. It
427 shows icons in various sizes, their symbolic variants when
428 available, as well as a description of the icon and its context
429 </para>
430 <indexterm zone="gtk4 gtk4-icon-browser">
431 <primary sortas="b-gtk4-icon-browser">gtk4-icon-browser</primary>
432 </indexterm>
433 </listitem>
434 </varlistentry>
435
436 <varlistentry id="gtk4-launch">
437 <term><command>gtk4-launch</command></term>
438 <listitem>
439 <para>
440 launches an application using the given name. The name should match
441 the application .desktop file name (as seen in
442 <filename class="directory">/usr/share/applications</filename>),
443 with or without the '.desktop' extension
444 </para>
445 <indexterm zone="gtk4 gtk-launch">
446 <primary sortas="b-gtk4-launch">gtk4-launch</primary>
447 </indexterm>
448 </listitem>
449 </varlistentry>
450
451 <varlistentry id="gtk4-node-editor">
452 <term><command>gtk4-node-editor</command></term>
453 <listitem>
454 <para>
455 is a utility to show and edit render node files. Such render
456 node files can be obtained e.g. from the GTK inspector
457 </para>
458 <indexterm zone="gtk4 gtk4-node-editor">
459 <primary sortas="b-gtk4-node-editor">gtk4-node-editor</primary>
460 </indexterm>
461 </listitem>
462 </varlistentry>
463
464 <varlistentry id="gtk4-print-editor">
465 <term><command>gtk4-print-editor</command></term>
466 <listitem>
467 <para>
468 is a simple program to demonstrate printing using GTK 4
469 applications
470 </para>
471 <indexterm zone="gtk4 gtk4-print-editor">
472 <primary sortas="b-gtk4-print-editor">gtk4-print-editor</primary>
473 </indexterm>
474 </listitem>
475 </varlistentry>
476
477 <varlistentry id="gtk4-query-settings">
478 <term><command>gtk4-query-settings</command></term>
479 <listitem>
480 <para>
481 provides a complete listing of all settings related to GTK 4
482 </para>
483 <indexterm zone="gtk4 gtk4-query-settings">
484 <primary sortas="b-gtk4-query-settings">gtk4-query-settings</primary>
485 </indexterm>
486 </listitem>
487 </varlistentry>
488
489 <varlistentry id="gtk4-update-icon-cache">
490 <term><command>gtk4-update-icon-cache</command></term>
491 <listitem>
492 <para>
493 is an icon theme caching utility that creates mmap()able cache
494 files for icon themes
495 </para>
496 <indexterm zone="gtk4 gtk4-update-icon-cache">
497 <primary sortas="b-gtk4-update-icon-cache">gtk4-update-icon-cache</primary>
498 </indexterm>
499 </listitem>
500 </varlistentry>
501
502 <varlistentry id="gtk4-widget-factory">
503 <term><command>gtk4-widget-factory</command></term>
504 <listitem>
505 <para>
506 is a program to view GTK 4 themes and widgets
507 </para>
508 <indexterm zone="gtk4 gtk4-widget-factory">
509 <primary sortas="b-gtk4-widget-factory">gtk4-widget-factory</primary>
510 </indexterm>
511 </listitem>
512 </varlistentry>
513
514 <varlistentry id="libgtk-4">
515 <term><filename class="libraryfile">libgtk-4.so</filename></term>
516 <listitem>
517 <para>
518 contains functions that provide an API to implement graphical user
519 interfaces
520 </para>
521 <indexterm zone="gtk4 libgtk-4">
522 <primary sortas="c-libgtk-4">libgtk-4.so</primary>
523 </indexterm>
524 </listitem>
525 </varlistentry>
526 </variablelist>
527 </sect2>
528</sect1>
Note: See TracBrowser for help on using the repository browser.