Skip to content

Commit 1a02bcf

Browse files
joebonrichiejoebonrichie
committed
docs/packaging: Update docs for appstream & appstream-generator
We are nuking our use of `appstream-glib` and `appstream-builder`. Explain how to run `appstreamcli compose` on a single package as well as running `appstream-generator` against a repository. The `solus-appstream-data` will be archived so any relevant docs from there will need to be moved over. The "debugging failures" section will likely need to be expanded but due to `appstream-generator` being less anal and better supporting the spec some previous issues may not apply.
1 parent 377ef08 commit 1a02bcf

File tree

1 file changed

+82
-5
lines changed

1 file changed

+82
-5
lines changed

‎docs/packaging/appstream-metainfo.md

+82-5
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ There are a few scenarios that Packagers might encounter:
2525
| 2 | An application contains appstream metainfo in the source package but we do not install it | Install the appstream metainfo to `/usr/share/metainfo`. _Example_: [here](https://github.com/getsolus/packages/commit/0a726a53454e7c8a6b0e66de69d59bcc66f0fc19) |
2626
| 3 | An application doesn't contain appstream metainfo in the source package but it exists on Flathub | Borrow and tweak the appstream metainfo from the Flathub repo. Encourage upstream project to add it to their source. _Example_: [here](https://github.com/getsolus/packages/commit/da2f65b93f412da43d1db9edbcb08bb90517a0eb) |
2727
| 4 | An application doesn't provide appstream metainfo and it doesn't exist on flathub | Write the appstream metadata, submit it to upstream project. _Example_: [here](https://github.com/getsolus/packages/commit/414219d8b2ceeabe85178d3a467f81b9131016f4) |
28-
| 5 | Appstream metainfo is provided but generation of it is failing | See [here](https://github.com/getsolus/solus-appstream-data#debugging-failures). _Example_: [here](https://github.com/getsolus/packages/commit/583b7c742caf50e2f66a70e9b62e9b91566c03f5). |
28+
| 5 | Appstream metainfo is provided but generation of it is failing | See [here](#testing-appstream-metainfo). _Example_: [here](https://github.com/getsolus/packages/commit/583b7c742caf50e2f66a70e9b62e9b91566c03f5). |
2929

3030
AppStream metainfo is to be installed in the `/usr/share/metainfo/` directory. It must be placed in the package which should be installed in order to get the software described by the respective metadata. This means that you might need to move the _.metainfo.xml or _.appdata.xml to the right (sub)package.
3131

@@ -35,14 +35,91 @@ In case your AppStream metainfo is describing a desktop application (you can tel
3535

3636
- Clone the package repo
3737

38-
- Build it or eopkg fetch pkgname
38+
- Build it or eopkg fetch pkgname e.g. `eopkg fetch sunshine`.
3939

40-
- Run `sudo eopkg it appstream-glib`, `appstream-builder --packages-dir=. --include-failed -v`
40+
- Extract the package e.g. `uneopkg sunshine-0.23.1-15-1-x86_64.eopkg`. This will unzip the `.eopkg` file containing the `metainfo.xml` and `files.xml` meta information as well as extract the contained `install.tar.xz` archive to a folder called `install`.
4141

42-
- Look in the `example-failed.xml.gz` file to see if the appstream generation failed
42+
- Ensure `appstream compose` is available and install it if it's not `sudo eopkg it appstream`.
4343

44-
- Look in the `example.xml.gz` file to see if the appstream generation succeeded.
44+
- Run a report against the extracted install directory `appstream compose install/`.
45+
- If it reports `Success!` there is nothing to do.
46+
- If it reports warnings they should be rectified if possible.
47+
- If it reports errors they should definately be rectified so that the appstream for that package is composed into the catalog.
48+
49+
To fix any potential warnings or errors you can edit the metainfo file in `install/usr/share/metainfo/` then rerun `appstream compose install/` to verify the issues have been rectified. A patch then can be created to be submitted to the upstream project if it provides the metainfo then that patch can also be applied to the solus monorepo for the corresponding package. If the upstream doesn't provide the metainfo file then a patch should be submitted directly to the corresponding package in the solus monorepo instead.
4550

4651
## Other Info
4752

4853
A package must provide one appstream metainfo file, an icon file and a .desktop file for AppStream generation to succeed. However, there are exceptions to this. If an application provides more than one AppStream metainfo file then the package must be subpackaged for generation of all the appstream metainfo files to succeed.
54+
55+
## Debugging Failures
56+
57+
The `appstreamcli compose` tool will normally give good hints about failures but the most common issues are:
58+
59+
- A `.desktop` file cannot be matched to the metainfo file.
60+
- By default, the `.desktop` file name must match the `<id>` provided in `.xml` file in `/usr/share/metainfo/`. For example, the if you have `<id>org.foobar.mypackage</id>` the `.desktop` file should
61+
be called `org.foobar.mypackage.desktop`. However, there is an exception to this if the metainfo provides a launchable tag. For example, if the metainfo contains `<launchable type="desktop-id">mypackage.desktop</launchable>` then the `.desktop` file can be just called `mypackage.desktop`. For more information view the upstream documentation [here](https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Application.html#spec-appdata-introduction)
62+
63+
64+
## Running `appstream-generator`
65+
66+
`appstream-generator` is a tool that supports composing a catalog against complex data sources. For our purposes, it provides a backend for Solus that understands a repository managed by `eopkg` as well as individual `.eopkg` files themselves. Individual packagers should be unlikely to need to use this tool unless they are managing a medium to long term repository that they need appstream data for.
67+
68+
To generate a catalog with appstream generator a `asgen-config.json` file must be provided.
69+
70+
Here is a example configuration file for running against local repositories.
71+
```json
72+
{
73+
"ProjectName": "Solus",
74+
"ArchiveRoot": "/var/lib/solbuild",
75+
"MediaBaseUrl": "http://localhost:8000/export/media",
76+
"HtmlBaseUrl": "http://localhost:8000/export/html",
77+
"Backend": "solus",
78+
"Suites": {
79+
"local": {
80+
"sections": ["main"],
81+
"architectures": ["x86_64"]
82+
}
83+
}
84+
}
85+
```
86+
87+
A local repository should contain a `eopkg-index.xml` file as well as `.eopkg` files. Remember to run, `eopkg index --skip-signing` in the root of the local repository before starting to ensure the index is up to date. In the sample provided above the eopkg index file should reside in `/var/lib/solbuild/local/eopkg-index.xml`.
88+
89+
To generate the catalog run `appstream-generator process local --verbose`. Depending on the size of the repository this may take a long time, subsequent runs will take far less time
90+
as the packages are held in a database and cached.
91+
92+
To view the HTML report you can start a http server with `python3 -m http.server 8000`, enter `http://localhost:8000/` in your web browser, then navigate to `export/html/`.
93+
94+
It can also be ran against a remote repository, here is a sample configuration.
95+
```json
96+
{
97+
"ProjectName": "Solus",
98+
"ArchiveRoot": "https://fastly.getsol.us/repo",
99+
"MediaBaseUrl": "https://appstream.getsol.us/media",
100+
"HtmlBaseUrl": "https://appstream.getsol.us",
101+
"Backend": "solus",
102+
"Suites": {
103+
"gwendraeth": {
104+
"sections": ["main"],
105+
"architectures": ["x86_64"]
106+
},
107+
"gwendraeth-updates": {
108+
"sections": ["main"],
109+
"architectures": ["x86_64"]
110+
"dataPriority": 10,
111+
"baseSuite": "gwendraeth"
112+
}
113+
}
114+
}
115+
```
116+
117+
In this example appstream-generator will run against two suites which correspond to the "gwendraeth" and "gwendraeth-updates" repositories. Where the index URL for "gwendraeth" would correspond to `https://fastly.getsol.us/repo/gwendraeth/eopkg-index.xml.xz` in this example.
118+
119+
To generate a catalog for just gwendraeth run `appstream-generator process gwendraeth --verbose`. To generate a catalog against gwendraeth _as well as_ any differences in the gwendraeth-updates repository run `appstream-generator process gwendraeth-updates --verbose`. Appstream generator is smart enough to only process `.eopkg` files that are different in the "gwendraeth-updates" repository in this case.
120+
121+
For more documentation consult [upstream](https://github.com/ximion/appstream-generator/tree/master/docs).
122+
123+
### Idiosyncracies
124+
125+
If `appstream-generator` has already successfully processed a package, if the package is "bumped" but the version has not changed then appstream generator will not process it. If you _need_ to reprocess a package in the catalog in this case; build and index the package as normal. You can then "forget" the package e.g. `appstream-generator forget gnome-calculator/48.1/x86_64`, then reprocess the suite to reprocess the metainfo for the offending package.

0 commit comments

Comments
 (0)