diff options
Diffstat (limited to 'doc')
31 files changed, 271 insertions, 21 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index aa3d186b..7ef61bdf 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -87,6 +87,7 @@ EXTRA_DIST = \ $(xml_files) \ docbook.css \ flatpak-docs.xml.in \ + meson.build \ xmlto-config.xsl \ $(NULL) diff --git a/doc/flatpak-build-finish.xml b/doc/flatpak-build-finish.xml index 81a72452..fa5c9ff0 100644 --- a/doc/flatpak-build-finish.xml +++ b/doc/flatpak-build-finish.xml @@ -134,7 +134,7 @@ Expose a well-known socket to the application. This updates the [Context] group in the metadata. SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, - ssh-auth, pcsc, cups. + ssh-auth, pcsc, cups, gpg-agent. This option can be used multiple times. </para><para> The fallback-x11 option makes the X11 socket available only if @@ -151,7 +151,7 @@ Don't expose a well known socket to the application. This updates the [Context] group in the metadata. SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, - ssh-auth, pcsc, cups. + ssh-auth, pcsc, cups, gpg-agent. This option can be used multiple times. </para></listitem> </varlistentry> diff --git a/doc/flatpak-build.xml b/doc/flatpak-build.xml index a48e2acd..d1157667 100644 --- a/doc/flatpak-build.xml +++ b/doc/flatpak-build.xml @@ -149,7 +149,7 @@ Expose a well-known socket to the application. This overrides to the Context section from the application metadata. <arg choice="plain">SOCKET</arg> must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, - ssh-auth, pcsc, cups. + ssh-auth, pcsc, cups, gpg-agent. This option can be used multiple times. </para></listitem> </varlistentry> @@ -161,7 +161,7 @@ Don't expose a well-known socket to the application. This overrides to the Context section from the application metadata. <arg choice="plain">SOCKET</arg> must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, - ssh-auth, pcsc, cups. + ssh-auth, pcsc, cups, gpg-agent. This option can be used multiple times. </para></listitem> </varlistentry> diff --git a/doc/flatpak-config.xml b/doc/flatpak-config.xml index c64339de..51d6ea1e 100644 --- a/doc/flatpak-config.xml +++ b/doc/flatpak-config.xml @@ -135,6 +135,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-create-usb.xml b/doc/flatpak-create-usb.xml index f687f4dd..bffb7342 100644 --- a/doc/flatpak-create-usb.xml +++ b/doc/flatpak-create-usb.xml @@ -110,6 +110,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-flatpakref.xml b/doc/flatpak-flatpakref.xml index 7e2991cf..88359701 100644 --- a/doc/flatpak-flatpakref.xml +++ b/doc/flatpak-flatpakref.xml @@ -108,18 +108,23 @@ <listitem><para>The url of a webpage describing the application or runtime.</para></listitem> </varlistentry> <varlistentry> - <term><option>DeployCollectionID</option> (string)</term> + <term><option>DeploySideloadCollectionID</option> (string)</term> <listitem><para> The collection ID of the remote, if it has one. This uniquely identifies the collection of apps in the remote, to allow peer to peer - redistribution. It is recommended to use this key over CollectionID because - only newer clients pay attention to it (and older clients don't handle + redistribution (see <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>). + It is recommended to use this key over DeployCollectionID or CollectionID because + only newer clients (Flatpak 1.12.8 or later) pay attention to it (and older clients don't handle collection IDs properly). </para></listitem> </varlistentry> <varlistentry> + <term><option>DeployCollectionID</option> (string)</term> + <listitem><para>This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.</para></listitem> + </varlistentry> + <varlistentry> <term><option>CollectionID</option> (string)</term> - <listitem><para>This is deprecated but still supported for backwards compatibility. Use DeployCollectionID instead.</para></listitem> + <listitem><para>This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.</para></listitem> </varlistentry> <varlistentry> diff --git a/doc/flatpak-flatpakrepo.xml b/doc/flatpak-flatpakrepo.xml index a92e1183..0e8a4d0d 100644 --- a/doc/flatpak-flatpakrepo.xml +++ b/doc/flatpak-flatpakrepo.xml @@ -122,18 +122,23 @@ </para></listitem> </varlistentry> <varlistentry> - <term><option>DeployCollectionID</option> (string)</term> + <term><option>DeploySideloadCollectionID</option> (string)</term> <listitem><para> The collection ID of the remote, if it has one. This uniquely identifies the collection of apps in the remote, to allow peer to peer - redistribution. It is recommended to use this key over CollectionID because - only newer clients pay attention to it (and older clients don't handle + redistribution (see <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>). + It is recommended to use this key over DeployCollectionID or CollectionID because + only newer clients (Flatpak 1.12.8 or later) pay attention to it (and older clients don't handle collection IDs properly). </para></listitem> </varlistentry> <varlistentry> + <term><option>DeployCollectionID</option> (string)</term> + <listitem><para>This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.</para></listitem> + </varlistentry> + <varlistentry> <term><option>CollectionID</option> (string)</term> - <listitem><para>This is deprecated but still supported for backwards compatibility. Use DeployCollectionID instead.</para></listitem> + <listitem><para>This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.</para></listitem> </varlistentry> </variablelist> </refsect2> diff --git a/doc/flatpak-history.xml b/doc/flatpak-history.xml index 62a56bf6..1c23e164 100644 --- a/doc/flatpak-history.xml +++ b/doc/flatpak-history.xml @@ -70,6 +70,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-info.xml b/doc/flatpak-info.xml index a4448f4d..3383c28a 100644 --- a/doc/flatpak-info.xml +++ b/doc/flatpak-info.xml @@ -73,6 +73,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-install.xml b/doc/flatpak-install.xml index 09011599..51c3d100 100644 --- a/doc/flatpak-install.xml +++ b/doc/flatpak-install.xml @@ -148,6 +148,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-list.xml b/doc/flatpak-list.xml index 91fdff5c..edb9ed4b 100644 --- a/doc/flatpak-list.xml +++ b/doc/flatpak-list.xml @@ -74,6 +74,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-make-current.xml b/doc/flatpak-make-current.xml index 4e7da211..7158840a 100644 --- a/doc/flatpak-make-current.xml +++ b/doc/flatpak-make-current.xml @@ -72,6 +72,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-mask.xml b/doc/flatpak-mask.xml index ec904af3..60624729 100644 --- a/doc/flatpak-mask.xml +++ b/doc/flatpak-mask.xml @@ -84,6 +84,7 @@ org.some.App/arm </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-metadata.xml b/doc/flatpak-metadata.xml index 8467bc6a..49b6cfc3 100644 --- a/doc/flatpak-metadata.xml +++ b/doc/flatpak-metadata.xml @@ -262,6 +262,7 @@ <filename>/app</filename>, <filename>/bin</filename>, <filename>/boot</filename>, + <filename>/efi</filename>, <filename>/etc</filename>, <filename>/lib</filename>, <filename>/lib32</filename>, diff --git a/doc/flatpak-override.xml b/doc/flatpak-override.xml index ed1ba52b..bdd9d974 100644 --- a/doc/flatpak-override.xml +++ b/doc/flatpak-override.xml @@ -47,10 +47,12 @@ By default the application gets access to the resources it requested when it is started. But the user can override it on a particular instance by specifying extra arguments to - flatpak run, or every time by using flatpak override. + <command>flatpak run</command>, or every time by using + <command>flatpak override</command>. </para> <para> - If the application id is not specified then the overrides affect all applications, + If the application ID <arg choice="plain">APP</arg> is not specified + then the overrides affect all applications, but the per-application overrides can override the global overrides. </para> <para> @@ -76,6 +78,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> @@ -131,7 +134,7 @@ Expose a well-known socket to the application. This overrides to the Context section from the application metadata. <arg choice="plain">SOCKET</arg> must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, - ssh-auth, pcsc, cups. + ssh-auth, pcsc, cups, gpg-agent. This option can be used multiple times. </para></listitem> </varlistentry> @@ -143,7 +146,7 @@ Don't expose a well-known socket to the application. This overrides to the Context section from the application metadata. <arg choice="plain">SOCKET</arg> must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, - ssh-auth, pcsc, cups. + ssh-auth, pcsc, cups, gpg-agent. This option can be used multiple times. </para></listitem> </varlistentry> diff --git a/doc/flatpak-pin.xml b/doc/flatpak-pin.xml index 04e5312a..dad64911 100644 --- a/doc/flatpak-pin.xml +++ b/doc/flatpak-pin.xml @@ -89,6 +89,7 @@ org.some.Runtime/arm </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-remote-add.xml b/doc/flatpak-remote-add.xml index b081b753..8f4579f6 100644 --- a/doc/flatpak-remote-add.xml +++ b/doc/flatpak-remote-add.xml @@ -81,6 +81,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-remote-delete.xml b/doc/flatpak-remote-delete.xml index fd7337a2..9affd5cf 100644 --- a/doc/flatpak-remote-delete.xml +++ b/doc/flatpak-remote-delete.xml @@ -68,6 +68,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-remote-info.xml b/doc/flatpak-remote-info.xml index 971efb83..394bacad 100644 --- a/doc/flatpak-remote-info.xml +++ b/doc/flatpak-remote-info.xml @@ -75,6 +75,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-remote-ls.xml b/doc/flatpak-remote-ls.xml index 5178c9d4..0bb32f1a 100644 --- a/doc/flatpak-remote-ls.xml +++ b/doc/flatpak-remote-ls.xml @@ -74,6 +74,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-remote-modify.xml b/doc/flatpak-remote-modify.xml index 3529dbfa..2edb5d13 100644 --- a/doc/flatpak-remote-modify.xml +++ b/doc/flatpak-remote-modify.xml @@ -68,6 +68,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-remotes.xml b/doc/flatpak-remotes.xml index 583d4f1c..e2d13de8 100644 --- a/doc/flatpak-remotes.xml +++ b/doc/flatpak-remotes.xml @@ -65,6 +65,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-repair.xml b/doc/flatpak-repair.xml index a2c4d31d..97b9688d 100644 --- a/doc/flatpak-repair.xml +++ b/doc/flatpak-repair.xml @@ -84,6 +84,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-run.xml b/doc/flatpak-run.xml index f8d9e5ee..4e37f910 100644 --- a/doc/flatpak-run.xml +++ b/doc/flatpak-run.xml @@ -92,11 +92,17 @@ <member>XDG_DATA_DIRS</member> <member>XDG_RUNTIME_DIR</member> <member>SHELL</member> + <member>TEMP</member> + <member>TEMPDIR</member> + <member>TMP</member> <member>TMPDIR</member> <member>PYTHONPATH</member> <member>PERLLIB</member> <member>PERL5LIB</member> <member>XCURSOR_PATH</member> + <member>KRB5CCNAME</member> + <member>XKB_CONFIG_ROOT</member> + <member>GIO_EXTRA_MODULES</member> </simplelist> <para> Also several environment variables with the prefix "GST_" that are used by gstreamer @@ -162,6 +168,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> @@ -298,7 +305,7 @@ Expose a well known socket to the application. This overrides to the Context section from the application metadata. <arg choice="plain">SOCKET</arg> must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, - ssh-auth, pcsc, cups. + ssh-auth, pcsc, cups, gpg-agent. This option can be used multiple times. </para></listitem> </varlistentry> @@ -310,7 +317,7 @@ Don't expose a well known socket to the application. This overrides to the Context section from the application metadata. <arg choice="plain">SOCKET</arg> must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, - ssh-auth, pcsc, cups. + ssh-auth, pcsc, cups, gpg-agent. This option can be used multiple times. </para></listitem> </varlistentry> @@ -574,9 +581,9 @@ key=v1;v2; <listitem><para> Allow filtered access to the session dbus connection. This is the default, except when run with --sandbox. </para><para> - Isandbox mode, even if you allow access to the session bus the sandbox cannot talk to or own + In sandbox mode, even if you allow access to the session bus the sandbox cannot talk to or own the application ids (org.the.App.*) on the bus (unless explicitly added), only names in the - .Sandbox subset (org.the.App.Sandbox.*). + .Sandboxed subset (org.the.App.Sandboxed.* and org.mpris.MediaPlayer2.org.the.App.Sandboxed.*). </para></listitem> </varlistentry> diff --git a/doc/flatpak-search.xml b/doc/flatpak-search.xml index 6d111c28..389d37de 100644 --- a/doc/flatpak-search.xml +++ b/doc/flatpak-search.xml @@ -53,6 +53,7 @@ <variablelist> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-uninstall.xml b/doc/flatpak-uninstall.xml index 3930e01d..cc29c049 100644 --- a/doc/flatpak-uninstall.xml +++ b/doc/flatpak-uninstall.xml @@ -106,6 +106,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/flatpak-update.xml b/doc/flatpak-update.xml index f8c4c19d..feaaf278 100644 --- a/doc/flatpak-update.xml +++ b/doc/flatpak-update.xml @@ -111,6 +111,7 @@ </varlistentry> <varlistentry> + <term><option>-u</option></term> <term><option>--user</option></term> <listitem><para> diff --git a/doc/meson.build b/doc/meson.build new file mode 100644 index 00000000..5a935758 --- /dev/null +++ b/doc/meson.build @@ -0,0 +1,133 @@ +# Copyright 2022 Collabora Ltd. +# SPDX-License-Identifier: LGPL-2.1-or-later + +if build_gtk_doc + subdir('reference') +endif + +xsltproc_flags = [ + '--nonet', + '--stringparam', 'man.output.quietly', '1', + '--stringparam', 'funcsynopsis.style', 'ansi', + '--stringparam', 'man.th.extra1.suppress', '1', + '--stringparam', 'man.authors.section.enabled', '0', + '--stringparam', 'man.copyright.section.enabled', '0', +] + +man1 = [ + 'flatpak', + 'flatpak-remotes', + 'flatpak-remote-add', + 'flatpak-remote-delete', + 'flatpak-remote-modify', + 'flatpak-remote-ls', + 'flatpak-remote-info', + 'flatpak-install', + 'flatpak-config', + 'flatpak-update', + 'flatpak-uninstall', + 'flatpak-mask', + 'flatpak-pin', + 'flatpak-list', + 'flatpak-info', + 'flatpak-make-current', + 'flatpak-run', + 'flatpak-override', + 'flatpak-enter', + 'flatpak-ps', + 'flatpak-document-export', + 'flatpak-document-unexport', + 'flatpak-document-info', + 'flatpak-documents', + 'flatpak-permission-remove', + 'flatpak-permissions', + 'flatpak-permission-show', + 'flatpak-permission-reset', + 'flatpak-permission-set', + 'flatpak-build-init', + 'flatpak-build', + 'flatpak-build-bundle', + 'flatpak-build-import-bundle', + 'flatpak-build-finish', + 'flatpak-build-export', + 'flatpak-build-update-repo', + 'flatpak-build-sign', + 'flatpak-build-commit-from', + 'flatpak-repo', + 'flatpak-search', + 'flatpak-create-usb', + 'flatpak-repair', + 'flatpak-kill', + 'flatpak-history', + 'flatpak-spawn', +] + +man5 = [ + 'flatpak-metadata', + 'flatpak-flatpakrepo', + 'flatpak-flatpakref', + 'flatpak-remote', + 'flatpak-installation', +] + +xml_files = [] + +foreach pair : [[man1, '1'], [man5, '5']] + pages = pair[0] + section = pair[1] + + foreach man : pages + xml_files += [man + '.xml'] + + if build_man_pages + custom_target( + man + '.' + section, + input : [man + '.xml'], + output : [man + '.' + section], + command : [ + xsltproc, + '-o', '@OUTPUT@', + ] + xsltproc_flags + [ + manpages_xsl, + '@INPUT@', + ], + build_by_default : true, + install : true, + install_dir : get_option('mandir') / ('man' + section), + ) + endif + endforeach +endforeach + +if xmlto.found() + cdata = configuration_data() + cdata.set('VERSION', meson.project_version()) + cdata.set('srcdir', meson.current_source_dir()) + flatpak_docs_xml = configure_file( + input : 'flatpak-docs.xml.in', + output : 'flatpak-docs.xml', + configuration : cdata, + ) + custom_target( + 'flatpak-docs.html', + input : [ + flatpak_docs_xml, + 'xmlto-config.xsl', + ], + output : ['flatpak-docs.html'], + depend_files : xml_files, + command : [ + xmlto, + '-o', meson.current_build_dir(), + ] + get_option('xmlto_flags') + [ + '--skip-validation', + 'xhtml-nochunks', + '-m', '@INPUT1@', + '@INPUT0@', + ], + build_by_default : true, + install : true, + install_dir : docdir, + ) + install_data('docbook.css', install_dir : docdir) +endif diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am index 6aaa3451..e8f5b30f 100644 --- a/doc/reference/Makefile.am +++ b/doc/reference/Makefile.am @@ -78,6 +78,7 @@ include $(top_srcdir)/gtk-doc.make CLEANFILES += $(xml_files) +EXTRA_DIST += meson.build EXTRA_DIST += version.xml.in if ENABLE_GTK_DOC_CHECK diff --git a/doc/reference/meson.build b/doc/reference/meson.build new file mode 100644 index 00000000..a881b0cb --- /dev/null +++ b/doc/reference/meson.build @@ -0,0 +1,74 @@ +# Copyright 2022 Collabora Ltd. +# SPDX-License-Identifier: LGPL-2.1-or-later + +cdata = configuration_data() +cdata.set('FLATPAK_MAJOR_VERSION', flatpak_major_version) +cdata.set('FLATPAK_MINOR_VERSION', flatpak_minor_version) +cdata.set('FLATPAK_MICRO_VERSION', flatpak_micro_version) +configure_file( + configuration : cdata, + input : 'version.xml.in', + output : 'version.xml', +) + +# We're really only doing this to generate the Docbook XML. +doc_gdbus = gnome.gdbus_codegen( + 'doc-dbus-generated', + sources : [ + project_source_root / 'data/org.freedesktop.Flatpak.Authenticator.xml', + project_source_root / 'data/org.freedesktop.Flatpak.xml', + project_source_root / 'data/org.freedesktop.impl.portal.PermissionStore.xml', + project_source_root / 'data/org.freedesktop.portal.Documents.xml', + project_source_root / 'data/org.freedesktop.portal.Flatpak.xml', + ], + namespace : 'doc', + docbook : 'dbus', +) + +gnome.gtkdoc( + 'flatpak', + main_xml : 'libflatpak-docs.xml', + namespace : 'flatpak', + src_dir : [ + project_build_root / 'common', + project_source_root / 'common', + ], + content_files : doc_gdbus[2], + dependencies : base_deps + [libflatpak_dep], + ignore_headers : [ + 'valgrind-private.h', + 'flatpak-bwrap-private.h', + 'flatpak-chain-input-stream-private.h', + 'flatpak-common-types-private.h', + 'flatpak-context-private.h', + 'flatpak-dbus-generated.h', + 'flatpak-dir-private.h', + 'flatpak-document-dbus-generated.h', + 'flatpak-enum-types.h', + 'flatpak-exports-private.h', + 'flatpak-installed-ref-private.h', + 'flatpak-json-oci-private.h', + 'flatpak-json-private.h', + 'flatpak-oci-registry-private.h', + 'flatpak-progress-private.h', + 'flatpak-remote-private.h', + 'flatpak-remote-ref-private.h', + 'flatpak-run-private.h', + 'flatpak-systemd-dbus-generated.h', + 'flatpak-installation-private.h', + 'flatpak-transaction-private.h', + 'flatpak-utils-private.h', + 'flatpak-utils-base-private.h', + 'flatpak-utils-http-private.h', + 'flatpak-instance-private.h', + 'flatpak-auth-private.h', + 'flatpak-parental-controls-private.h', + 'flatpak-appdata-private.h', + 'flatpak-zstd-decompressor-private.h', + ], + install : true, + scan_args : [ + '--ignore-decorators=FLATPAK_EXTERN', + '--rebuild-types', + ], +) diff --git a/doc/release-checklist.md b/doc/release-checklist.md index cf0d1ef0..01d1b256 100644 --- a/doc/release-checklist.md +++ b/doc/release-checklist.md @@ -2,7 +2,8 @@ Flatpak release checklist ========================= * Update NEWS -* Update version number in `configure.ac` and release date in `NEWS` +* Update version number in `configure.ac` **and** `meson.build` +* Update release date in `NEWS` * Commit the changes * `make distcheck` * This will update `po/`; commit those changes too |