'\" t
.\"     Title: appstreamcli compose
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 28 Aug,2020
.\"    Manual: appstreamcli compose
.\"    Source: AppStream
.\"  Language: English
.\"
.TH "APPSTREAMCLI COMPOSE" "1" "" "AppStream" "appstreamcli compose"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
appstreamcli-compose \- Compose AppStream metadata catalog from directory trees
.SH "SYNOPSIS"
.HP \w'\fBappstreamcli\ compose\fR\ 'u
\fBappstreamcli compose\fR [\fBCOMMAND\fR]
.SH "DESCRIPTION"
.PP
This manual page documents briefly the
\fBappstreamcli compose\fR
command\&.
.PP
The
\fBappstreamcli compose\fR
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
\fBappstream\-generator\fR\&.
.PP
In order for the
\fBappstreamcli compose\fR
command to be available, you may need to install the optional compose module for
\fBappstreamcli\fR
first\&.
.PP
For more information about the AppStream project and the other components which are part of it, take a look at the AppStream pages at
\m[blue]\fBFreedesktop\&.org\fR\m[]\&\s-2\u[1]\d\s+2\&.
.SH "OPTIONS"
.PP
\fISOURCE\-DIRECTORIES\fR
.RS 4
A list of directories to process needs to be provided as positional parameters\&. Data from all directories will be combined into one output namespace\&.
.RE
.PP
\fB\-\-origin \fR\fB\fINAME\fR\fR
.RS 4
Set the AppStream data origin identifier\&. This can be a value like
"debian\-unstable\-main"
or
"flathub"\&.
.RE
.PP
\fB\-\-result\-root \fR\fB\fIDIR\fR\fR
.RS 4
Sets the directory where all generated output that is deployed to a user\*(Aqs 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\&.
.sp
If both
\fB\-\-data\-dir\fR
and
\fB\-\-icons\-dir\fR
are set,
\fB\-\-result\-root\fR
is not necessary and no data will be written to that directory\&.
.RE
.PP
\fB\-\-data\-dir \fR\fB\fIDIR\fR\fR
.RS 4
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
\fB\-\-result\-root\fR
to set an output location)\&.
.RE
.PP
\fB\-\-icons\-dir \fR\fB\fIDIR\fR\fR
.RS 4
Override the directory where the cached icons are exported to\&.
.RE
.PP
\fB\-\-hints\-dir \fR\fB\fIDIR\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-media\-dir \fR\fB\fIDIR\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-media\-baseurl \fR\fB\fIURL\fR\fR
.RS 4
The URL under which the contents of a directory set via
\fB\-\-media\-dir\fR
will be served\&. This value must be set if a media directory is created\&.
.RE
.PP
\fB\-\-prefix \fR\fB\fIDIR\fR\fR
.RS 4
Set the default prefix that is used in the processed directories\&. If none is set explicitly,
/usr
is assumed\&.
.RE
.PP
\fB\-\-print\-report \fR\fB\fIMODE\fR\fR
.RS 4
Print the issue hints report (that gets exported as HTML and YAML document when
\fB\-\-hints\-dir\fR
was set) to the console in text form\&.
.sp
Various print modes are supported:
\fIon\-error\fR
only prints a short report if the run failed (default),
\fIshort\fR
generates an abridged report that is always printed and
\fIfull\fR
results in a detailed report to be printed\&.
.RE
.PP
\fB\-\-no\-partial\-urls\fR
.RS 4
If set, all URLs in the generated data will be absolute and
media_baseurl
will not be used\&. This makes changing the media mirror harder without regenerating all data and is generally not recommended, to increase flexibility\&.
.RE
.PP
\fB\-\-icon\-policy \fR\fB\fIPOLICY\-STRING\fR\fR
.RS 4
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\&.
.sp
The icon\-policy string is comprised of comma\-separated
%{size}x%{size}@%{scale}=%{state}
statements\&. The
size
and
scale
are that of the respective icon, with the scale being allowed to be omitted if it is 1\&. The
state
can be one of
remote,
cached
or
cached\-remote\&.
.sp
By default, a policy of
48x48=cached,48x48@2=cached,64x64=cached,64x64@2=cached,128x128=cached\-remote,128x128@2=cached\-remote
is selected\&.
.RE
.PP
\fB\-\-allow\-custom \fR\fB\fICUSTOM\-KEY\-NAMES\fR\fR
.RS 4
By default, all
custom
entries set in MetaInfo input data are removed\&. This flag allows 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\&.
.RE
.PP
\fB\-\-components \fR\fB\fICOMPONENT\-IDs\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-no\-color\fR
.RS 4
Don\*(Aqt print colored output\&.
.RE
.PP
\fB\-\-verbose\fR
.RS 4
Display extra debugging information
.RE
.PP
\fB\-\-version\fR
.RS 4
Display the version number of appstreamcli compose
.RE
.SH "SEE ALSO"
.PP
\fBappstreamcli\fR(1),
\fBappstream-generator\fR(1)\&.
.SH "AUTHOR"
.PP
This manual page was written by Matthias Klumpp
<matthias@tenstral\&.net>\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2020-2024 Matthias Klumpp
.br
.SH "NOTES"
.IP " 1." 4
Freedesktop.org
.RS 4
\%https://www.freedesktop.org/wiki/Distributions/AppStream/
.RE