flatpak · razzeee · Aug 8, 2026
diff --git a/doc/flatpak-builder.xml b/doc/flatpak-builder.xml
@@ -641,6 +641,19 @@
                 </para></listitem>
             </varlistentry>
 
+            <varlistentry>
+                <term><option>--appstream-compose-icon-policy=POLICY</option></term>
+
+                <listitem><para>
+                  Pass <literal>POLICY</literal> to
+                  <command>appstreamcli compose</command> as its icon policy.
+                  If this option is omitted, the default AppStream icon policy
+                  is preserved. This option requires an
+                  <command>appstreamcli</command> version that supports
+                  <option>--icon-policy</option>.
+                </para></listitem>
+            </varlistentry>
+
             <varlistentry>
                 <term><option>--add-tag=TAG</option></term>
 

diff --git a/src/builder-context.c b/src/builder-context.c
@@ -88,6 +88,7 @@ struct BuilderContext
   gboolean        no_shallow_clone;
   gboolean        opt_export_only;
   char           *opt_mirror_screenshots_url;
+  char           *opt_appstream_compose_icon_policy;
 
   BuilderSdkConfig *sdk_config;
 
@@ -134,6 +135,7 @@ builder_context_finalize (GObject *object)
   g_free (self->state_subdir);
   g_free (self->stop_at);
   g_free (self->opt_mirror_screenshots_url);
+  g_free (self->opt_appstream_compose_icon_policy);
   g_strfreev (self->cleanup);
   g_strfreev (self->cleanup_platform);
   glnx_release_lock_file(&self->rofiles_file_lock);
@@ -384,6 +386,20 @@ builder_context_get_opt_mirror_screenshots_url (BuilderContext *self)
   return self->opt_mirror_screenshots_url;
 }
 
+void
+builder_context_set_opt_appstream_compose_icon_policy (BuilderContext *self,
+                                                       const char     *policy)
+{
+  g_free (self->opt_appstream_compose_icon_policy);
+  self->opt_appstream_compose_icon_policy = g_strdup (policy);
+}
+
+const char *
+builder_context_get_opt_appstream_compose_icon_policy (BuilderContext *self)
+{
+  return self->opt_appstream_compose_icon_policy;
+}
+
 GFile *
 builder_context_find_in_sources_dirs (BuilderContext *self,
                                       ...)

diff --git a/src/builder-context.h b/src/builder-context.h
@@ -193,6 +193,11 @@ void            builder_context_set_opt_mirror_screenshots_url (BuilderContext *
 
 const char *    builder_context_get_opt_mirror_screenshots_url (BuilderContext *self);
 
+void            builder_context_set_opt_appstream_compose_icon_policy (BuilderContext *self,
+                                                                        const char     *policy);
+
+const char *    builder_context_get_opt_appstream_compose_icon_policy (BuilderContext *self);
+
 BuilderSdkConfig * builder_context_get_sdk_config (BuilderContext *self);
 
 gboolean builder_context_ccache_available_in_sdk (BuilderContext *self,

diff --git a/src/builder-main.c b/src/builder-main.c
@@ -94,6 +94,7 @@ static gboolean opt_log_system_bus;
 static gboolean opt_yes;
 static gint64 opt_source_date_epoch = SOURCE_DATE_EPOCH_DEFAULT;
 static gchar *opt_as_url_policy = NULL;
+static gchar *opt_appstream_compose_icon_policy = NULL;
 
 static GOptionEntry entries[] = {
   { "verbose", 'v', 0, G_OPTION_ARG_NONE, &opt_verbose, "Print debug information during command processing", NULL },
@@ -151,6 +152,7 @@ static GOptionEntry entries[] = {
   { "no-shallow-clone", 0, 0, G_OPTION_ARG_NONE, &opt_no_shallow_clone, "Don't use shallow clones when mirroring git repos", NULL },
   { "override-source-date-epoch", 0, 0, G_OPTION_ARG_INT64, &opt_source_date_epoch, "Use this timestamp to perform the build, instead of the last modification time of the manifest.", NULL },
   { "compose-url-policy", 0, 0, G_OPTION_ARG_STRING, &opt_as_url_policy, "Set the AppStream compose URL policy to either 'partial' (default) or 'full'", "POLICY" },
+  { "appstream-compose-icon-policy", 0, 0, G_OPTION_ARG_STRING, &opt_appstream_compose_icon_policy, "Set the AppStream compose icon policy", "POLICY" },
   { NULL }
 };
 
@@ -617,6 +619,7 @@ main (int    argc,
   builder_context_set_bundle_sources (build_context, opt_bundle_sources);
   builder_context_set_opt_export_only (build_context, opt_export_only);
   builder_context_set_opt_mirror_screenshots_url (build_context, opt_mirror_screenshots_url);
+  builder_context_set_opt_appstream_compose_icon_policy (build_context, opt_appstream_compose_icon_policy);
 
   if (opt_mirror_screenshots_url)
     {

diff --git a/src/builder-manifest.c b/src/builder-manifest.c
@@ -1944,6 +1944,7 @@ builder_manifest_checksum_for_cleanup (BuilderManifest *self,
   builder_cache_checksum_str (cache, self->desktop_file_name_prefix);
   builder_cache_checksum_str (cache, self->desktop_file_name_suffix);
   builder_cache_checksum_boolean (cache, self->appstream_compose);
+  builder_cache_checksum_str (cache, builder_context_get_opt_appstream_compose_icon_policy (context));
 
   for (l = self->expanded_modules; l != NULL; l = l->next)
     {
@@ -2436,6 +2437,7 @@ cmpstringp (const void *p1, const void *p2)
 static gboolean
 appstreamcli_compose (GError             **error,
                       BuilderAsUrlPolicy   as_url_policy,
+                      const char          *icon_policy,
                       ...)
 {
   g_autoptr(GPtrArray) args = NULL;
@@ -2449,7 +2451,10 @@ appstreamcli_compose (GError             **error,
   if (as_url_policy == BUILDER_AS_URL_POLICY_FULL)
     g_ptr_array_add (args, g_strdup ("--no-partial-urls"));
 
-  va_start (ap, as_url_policy);
+  if (icon_policy != NULL)
+    g_ptr_array_add (args, g_strdup_printf ("--icon-policy=%s", icon_policy));
+
+  va_start (ap, icon_policy);
   while ((arg = va_arg (ap, const gchar *)))
     g_ptr_array_add (args, g_strdup (arg));
   g_ptr_array_add (args, NULL);
@@ -3100,6 +3105,7 @@ builder_manifest_cleanup (BuilderManifest *self,
           const char *opt_mirror_screenshots_url = builder_context_get_opt_mirror_screenshots_url (context);
           gboolean opt_export_only = builder_context_get_opt_export_only (context);
           BuilderAsUrlPolicy as_url_policy = builder_context_get_as_url_policy (context);
+          const char *icon_policy = builder_context_get_opt_appstream_compose_icon_policy (context);
 
           if (opt_mirror_screenshots_url && !opt_export_only)
             {
@@ -3112,6 +3118,7 @@ builder_manifest_cleanup (BuilderManifest *self,
               g_print ("Saving screenshots in %s\n", flatpak_file_get_path_cached (media_dir));
               if (!appstreamcli_compose (error,
                                          as_url_policy,
+                                         icon_policy,
                                          "--prefix=/",
                                          origin,
                                          arg_base_url,
@@ -3129,6 +3136,7 @@ builder_manifest_cleanup (BuilderManifest *self,
               g_print ("Running appstreamcli compose\n");
               if (!appstreamcli_compose (error,
                                          as_url_policy,
+                                         icon_policy,
                                          "--prefix=/",
                                          origin,
                                          result_root_arg,

diff --git a/tests/meson.build b/tests/meson.build
@@ -137,6 +137,7 @@ if get_option('installed_tests')
     'org.flatpak_builder.gui.metainfo.xml',
     'org.flatpak.appstream_media.json',
     'org.test.Hello-256.png',
+    'org.test.Hello-512.png',
     'org.flatpak.install_test.json',
     'test-locale-cleanup.json',
     'test-runtime-platform.json',

diff --git a/tests/org.flatpak.appstream_media.json b/tests/org.flatpak.appstream_media.json
@@ -4,19 +4,20 @@
     "sdk": "org.test.Sdk",
     "rename-desktop-file": "org.flatpak_builder.gui.desktop",
     "rename-appdata-file": "org.flatpak_builder.gui.metainfo.xml",
-    "rename-icon": "org.test.Hello-256",
+    "rename-icon": "org.test.Hello-512",
     "command": "hello",
     "modules": [
         {
             "name": "appstream_media",
             "buildsystem": "simple",
             "build-commands": [
                 "mkdir -p ${FLATPAK_DEST}/bin ${FLATPAK_DEST}/share/metainfo ${FLATPAK_DEST}/share/applications",
-                "mkdir -p ${FLATPAK_DEST}/share/icons/hicolor/256x256/apps",
+                "mkdir -p ${FLATPAK_DEST}/share/icons/hicolor/256x256/apps ${FLATPAK_DEST}/share/icons/hicolor/256x256@2/apps",
                 "cp -vf hello.sh ${FLATPAK_DEST}/bin/hello",
                 "cp -vf org.flatpak_builder.gui.metainfo.xml ${FLATPAK_DEST}/share/metainfo",
                 "cp -vf org.flatpak_builder.gui.desktop ${FLATPAK_DEST}/share/applications",
-                "cp -vf org.test.Hello-256.png ${FLATPAK_DEST}/share/icons/hicolor/256x256/apps"
+                "cp -vf org.test.Hello-256.png ${FLATPAK_DEST}/share/icons/hicolor/256x256/apps/org.test.Hello-512.png",
+                "cp -vf org.test.Hello-512.png ${FLATPAK_DEST}/share/icons/hicolor/256x256@2/apps"
             ],
             "sources": [
                 {
@@ -37,6 +38,10 @@
                 {
                     "type": "file",
                     "path": "org.test.Hello-256.png"
+                },
+                {
+                    "type": "file",
+                    "path": "org.test.Hello-512.png"
                 }
             ]
         }

diff --git a/tests/org.test.Hello-512.png b/tests/org.test.Hello-512.png
diff --git a/tests/test-builder.sh b/tests/test-builder.sh
@@ -23,7 +23,7 @@ set -euo pipefail
 
 skip_without_fuse
 
-echo "1..13"
+echo "1..14"
 
 setup_repo
 install_repo
@@ -55,6 +55,7 @@ cp $(dirname $0)/org.flatpak_builder.gui.json .
 cp $(dirname $0)/org.flatpak_builder.gui.metainfo.xml .
 cp $(dirname $0)/org.test.Hello.png .
 cp $(dirname $0)/org.test.Hello-256.png .
+cp $(dirname $0)/org.test.Hello-512.png .
 cp $(dirname $0)/org.flatpak.appstream_media.json .
 cp $(dirname $0)/org.flatpak.install_test.json .
 cp $(dirname $0)/test-locale-cleanup.json .
@@ -197,6 +198,32 @@ else
     echo "ok # Skip AppStream < 0.16.3"
 fi
 
+# test compose icon policy
+if appstream_has_version 1 0 2; then
+    # Prime the cleanup cache with a non-retina remote icon policy.
+    APPDIR=builddir_icon_policy \
+    run_build \
+        --mirror-screenshots-url=https://example.org/media \
+        --state-dir .fp-compose-icon-policy \
+        --appstream-compose-icon-policy=64x64=cached,128x128=remote \
+        org.flatpak.appstream_media.json
+
+    # Changing only the policy must invalidate cleanup and emit the retina icon.
+    APPDIR=builddir_icon_policy \
+    run_build \
+        --mirror-screenshots-url=https://example.org/media \
+        --state-dir .fp-compose-icon-policy \
+        --appstream-compose-icon-policy=64x64=cached,256x256@2=remote \
+        org.flatpak.appstream_media.json
+
+    find builddir_icon_policy/files/share/app-info/media -path "*/icons/256x256@2/org.flatpak.appstream_media.png" -type f | grep -q .
+    gzip -cdq builddir_icon_policy/files/share/app-info/xmls/org.flatpak.appstream_media.xml.gz | grep -Eq '<icon type="remote" width="256" height="256" scale="2">'
+
+    echo "ok appstream compose icon policy"
+else
+    echo "ok # Skip AppStream < 1.0.2"
+fi
+
 # test install
 APPDIR=builddir run_build --user --install org.flatpak.install_test.json