<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

  <!ENTITY date        "<date>28 Aug,2020</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY package     "appstreamcli compose">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
	<refentryinfo>
	<title>appstreamcli compose</title>
	<copyright>
		<year>2020-2024</year>
		<holder>Matthias Klumpp</holder>
	</copyright>
	<productname>AppStream</productname>
	&date;
	</refentryinfo>

	<refmeta>
		<refentrytitle>appstreamcli compose</refentrytitle>
		<manvolnum>1</manvolnum>
	</refmeta>
	<refnamediv>
		<refname>appstreamcli-compose</refname>
		<refpurpose>Compose AppStream metadata catalog from directory trees</refpurpose>
	</refnamediv>

       <refsynopsisdiv>
	       <cmdsynopsis>
		       <command>&package;</command>
		       <group>
			       <option>COMMAND</option>
		       </group>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>Description</title>
		<para>
			This manual page documents briefly the <command>&package;</command> command.
		</para>
		<para>
			The <command>&package;</command> tool is used to construct AppStream metadata catalogs from directory trees.
			The tool will also perform many related metadata generation actions, like resizing icons and
			screenshots and merging in data from referenced desktop-entry files as well as translation status
			information.
			Therefore, the tool provides a fast way to test how the final processed metadata for an application
			that is shipped to users may look like.
			It also provides a way to easily generate AppStream data for projects which do not need a more complex data
			generator like <command>appstream-generator</command>.
		</para>
		<para>
			In order for the <command>&package;</command> command to be available, you may need to install the
			optional compose module for <command>appstreamcli</command> first.
		</para>
		<para>
			For more information about the AppStream project and the other components which are part of it, take a look at
			the AppStream pages at <ulink url="https://www.freedesktop.org/wiki/Distributions/AppStream/">Freedesktop.org</ulink>.
		</para>
	</refsect1>

	<refsect1>
		<title>Options</title>
		<variablelist>

			<varlistentry>
				<term><replaceable>SOURCE-DIRECTORIES</replaceable></term>
				<listitem>
					<para>
						A list of directories to process needs to be provided as positional parameters.
						Data from all directories will be combined into one output namespace.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--origin <replaceable>NAME</replaceable></option></term>
				<listitem>
					<para>
						Set the AppStream data origin identifier. This can be a value like
						<code>"debian-unstable-main"</code> or <code>"flathub"</code>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--result-root <replaceable>DIR</replaceable></option></term>
				<listitem>
					<para>
						Sets the directory where all generated output that is deployed to a user's
						machine is exported to. If this parameter is not set and we only have one
						directory to process, we use that directory as default output path.
					</para>
					<para>
						If both <option>--data-dir</option> and <option>--icons-dir</option> are
						set, <option>--result-root</option> is not necessary and no data will be
						written to that directory.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--data-dir <replaceable>DIR</replaceable></option></term>
				<listitem>
					<para>
						Override the directory where the generated AppStream metadata catalog
						will be written to. Data will be written directly to this directory, and
						no supdirectories will be created (unlike when using <option>--result-root</option>
						to set an output location).
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--icons-dir <replaceable>DIR</replaceable></option></term>
				<listitem>
					<para>
						Override the directory where the cached icons are exported to.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--hints-dir <replaceable>DIR</replaceable></option></term>
				<listitem>
					<para>
						Set a directory where hints reported generated during metadata processing
						are saved to. If this parameter is not set, no HTML/YAML hint reports
						will be saved.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--media-dir <replaceable>DIR</replaceable></option></term>
				<listitem>
					<para>
						If set, creates a directory with media content (icons, screenshots, ...) that
						can be served via a webserver. The metadata will be extended to include information
						about these remote media.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--media-baseurl <replaceable>URL</replaceable></option></term>
				<listitem>
					<para>
						The URL under which the contents of a directory set via <option>--media-dir</option>
						will be served. This value must be set if a media directory is created.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--prefix <replaceable>DIR</replaceable></option></term>
				<listitem>
					<para>
						Set the default prefix that is used in the processed directories. If
						none is set explicitly, <filename>/usr</filename> is assumed.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--print-report <replaceable>MODE</replaceable></option></term>
				<listitem>
					<para>
						Print the issue hints report (that gets exported as HTML and YAML
						document when <option>--hints-dir</option> was set) to the console
						in text form.
					</para>
					<para>
						Various print modes are supported: <replaceable>on-error</replaceable> only prints a
						short report if the run failed (default), <replaceable>short</replaceable> generates
						an abridged report that is always printed and <replaceable>full</replaceable> results
						in a detailed report to be printed.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--no-partial-urls</option></term>
				<listitem>
					<para>
						If set, all URLs in the generated data will be absolute and <code>media_baseurl</code> will not be used.
						This makes changing the media mirror harder without regenerating all data and is generally not recommended,
						to increase flexibility.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--icon-policy <replaceable>POLICY-STRING</replaceable></option></term>
				<listitem>
					<para>
						Override the existing icon policy with a custom one. The icon policy sets how icons of
						different sizes should be dealt with. They can be in the icon cache only, be a remote icon in
						the media location or be both cached and available in the remote location.
					</para>
					<para>
						The icon-policy string is comprised of comma-separated <code>%{size}x%{size}@%{scale}=%{state}</code> statements.
						The <code>size</code> and <code>scale</code> are that of the respective icon, with the scale being allowed to be
						omitted if it is 1. The <code>state</code> can be one of <literal>remote</literal>, <literal>cached</literal> or
						<literal>cached-remote</literal>.
					</para>
					<para>
						By default, a policy of <code>48x48=cached,48x48@2=cached,64x64=cached,64x64@2=cached,128x128=cached-remote,128x128@2=cached-remote</code>
						is selected.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--allow-custom <replaceable>CUSTOM-KEY-NAMES</replaceable></option></term>
				<listitem>
					<para>
						By default, all <literal>custom</literal> entries set in MetaInfo input data are removed.
						This flag allows one to whitelist custom keys to be propagated to the final catalog output data.
						The custom-key names should be provided as a comma-separated list.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--components <replaceable>COMPONENT-IDs</replaceable></option></term>
				<listitem>
					<para>
						Set a comma-separated list of AppStream component IDs that should be
						considered for the generated metadata. All components that exist in
						the input data but are not mentioned in this list will be ignored
						for the generated output.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--no-color</option></term>
				<listitem>
					<para>Don't print colored output.</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--verbose</option></term>
				<listitem>
					<para>Display extra debugging information</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--version</option></term>
				<listitem>
					<para>Display the version number of &package;</para>
				</listitem>
			</varlistentry>

		</variablelist>
	</refsect1>

	<refsect1>
		<title>See Also</title>
		<para>
			<citerefentry><refentrytitle>appstreamcli</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
			<citerefentry><refentrytitle>appstream-generator</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
		</para>
	</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>
	This manual page was written by Matthias Klumpp <email>matthias@tenstral.net</email>.
</para>
</refsect1>
</refentry>
