diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/app-developers.md | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/doc/app-developers.md b/doc/app-developers.md new file mode 100644 index 0000000..dad5da7 --- /dev/null +++ b/doc/app-developers.md @@ -0,0 +1,69 @@ +Tools in GNOME Software for application developers +================================================== + +GNOME Software is often where users will first come into contact with an +application which they might later install, so the impression the user gets of +that application is important. Application developers want to see how their +application will appear in GNOME Software, and to have some control over it. + +GNOME Software provides some tools to help with this. + +If there is a supported tool which is not in this document, please +[submit a merge request](https://gitlab.gnome.org/GNOME/gnome-software/-/merge_requests/new) +to document it. + +Metainfo/Appstream +------------------ + +The information about an application comes from its metainfo (or, as it was +previously known: appdata) file. Metainfo files for multiple applications are +concatenated into ‘appstream’ files. Almost all of the customisation which GNOME +Software provides for applications comes from information in metainfo or +appstream files. + +So the first thing to check for your application is that its metainfo file is +complete and valid. See the +[metainfo file specification](https://www.freedesktop.org/software/appstream/docs/). + +To validate your metainfo file, run +``` +appstreamcli validate /path/to/app.metainfo.xml +``` + +You can add this as a unit test to your application by adding the following to +the appropriate `meson.build` in your application: +``` +metainfo_file = files('com.example.MyApp.metainfo.xml') +appstreamcli = find_program('appstreamcli', required: false) +if appstreamcli.found() + test ( + 'Validate metainfo file', + appstreamcli, + args: ['validate', '--no-net', metainfo_file], + ) +endif +``` + +Context tiles +------------- + +The context tiles which are shown on an application’s details page in GNOME +Software are derived from the application’s metainfo. + +There’s more detailed information about them, and the information they are built +from, [on the GNOME Software wiki](https://gitlab.gnome.org/GNOME/gnome-software/-/wikis/Software-metadata). + +Previewing the details page for an application +---------------------------------------------- + +GNOME Software allows previewing how an application will appear, by loading its +metainfo file directly. This allows previewing in-progress changes to an +application without publishing it to a repository. + +Do this with the `--show-metainfo` argument: +``` +gnome-software --show-metainfo=/path/to/app.metainfo.xml,icon=/path/to/icon.png +``` + +This will show the application in the details page of GNOME Software, and will +also display it in the featured carousel on the overview page. |