source: appstream-generator/docs/usage.md @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 2.4 KB
Line 
1# AppStream Generator Usage
2
3## How to use
4
5### Generating distro metadata
6To generate AppStream distribution metadata for your repository, create a local
7mirror of the repository first.
8Then create a new folder, and write a `asgen-config.json` configuration file for the
9metadata generator. Details on the file and an example can be found in [the asgen-config docs](asgen-config.md).
10
11After the config file has been written, you can generate the metadata as follows:
12```Bash
13cd /srv/asgen/workspace # path where the asgen-config.json file is located
14appstream-generator process chromodoris # replace "chromodoris" with the name of the suite you want to analyze
15```
16The generator is assuming you have enough memory and disk space on your machine to cache stuff.
17Resulting metadata will be placed in `export/data/`, machine-readable issue-hints can be found in `export/hints/` and the processed screenshots and icons are located in `export/media/`.
18
19In order to drop old packages and cruft from the databases, you should run
20```Bash
21appstream-generator cleanup
22```
23every once in a while. This will drop all superseded packages and data from the caches.
24
25If you do not want to `cd` into the workspace directory, you can also use the `--workspace|-w` flag to define a workspace.
26
27### Validating metadata
28You can validate the resulting metadata using the AppStream client tools.
29Use `appstreamcli validate <metadata>.xml.gz` for XML metadata, and `dep11-validate <dep11file>.yml.gz` for YAML. This will check the files for mistakes and compliance with the specification.
30
31Keep in mind that the generator will always generate spec-compliant metadata, but might - depending on the input - produce data which has smaller flaws (e.g. formatting issues in the long descriptions). In these cases, issue-hints will have been emitted, so the package maintainers can address the metadata issues.
32
33## Troubleshooting
34
35### Memory Usage
36The `appstream-generator` will not hesitate to use RAM, and also decide to use lots of it if enough is available. This is especially true when scanning new packages for their contents and storing the information in the LMDB database.
37Ideally make sure that you are running a 64bit system with at least 4GB of RAM if you want to use the generator properly.
38For the generator, speed matters more than RAM usage. You can use cgroups to limit the amount of memory the generator uses.
39
40### Profiling
41TODO
Note: See TracBrowser for help on using the repository browser.