diff options
author | Richard Hughes <richard@hughsie.com> | 2014-06-17 11:56:17 +0100 |
---|---|---|
committer | Richard Hughes <richard@hughsie.com> | 2014-06-17 12:01:32 +0100 |
commit | 693675c5cff1981eab2a8a15d74359f63e04b9ee (patch) | |
tree | b869f3ed61a75ab62ead6d473dabda1fcb0c93f6 /README.md | |
parent | dd8a4c907b88d819df866de490b01d98d8799dd4 (diff) | |
download | appstream-glib-693675c5cff1981eab2a8a15d74359f63e04b9ee.tar.gz |
Add appstream-build from the createrepo_as project
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 139 |
1 files changed, 128 insertions, 11 deletions
@@ -31,16 +31,6 @@ copy. To do the latter just do: make make install -More Information ----------------- - -If you want to actually generate metadata rather than just consuming it, you -probably want to be looking at: https://github.com/hughsie/createrepo_as or if -you're completely lost, GNOME Software is a GUI tool that uses this library to -implement a software center. See `src/plugins/gs-plugin-appstream.c` if you -want some more examples on using this library where speed and latency really -matter. - Hacking ------- @@ -48,10 +38,137 @@ If you want a new feature, or have found a bug or a way to crash this library, please report as much information as you can to the issue tracker: https://github.com/hughsie/appstream-glib/issues -- patches very welcome. -New functionality or crash fixes should include a test in `src/as-self-test.c` +New functionality or crash fixes should include a test in `libappstream-builder/as-self-test.c` to ensure we don't regress in the future. New functionality should also be thread safe and also not leak *any* memory for success or failure cases. +appstream-builder +================= + +appstream-builder is a tool that allows us to create AppStream metadata from a +directory of packages. +It is typically used when generating distribution metadata, usually at the same +time as modifyrepo or createrepo. + +What this tool does: + + * Searches a directory of packages and reads just the RPM header of each. + * If a package contains an interesting file, just the relevant files are + decompressed from the package archive. + * A set of plugins are run on the extracted files, and if these match certain + criteria `AsbApplication` objects are created. + * Any screenshots referenced are downloaded to a local cache. + This is optional and can be disabled with `--nonet`. + * When all the packages are processed, some of the `AsbApplication` objects are + merged into single applications. This is how fonts are collected. + * The `AsbApplication` objects are serialized to XML and written to a + compressed archive. + * Any application icons or screenshots referenced are written to a .tar archive. + +Getting Started +----------- + +To run appstream-builder you either need to install the package containing the +binary and data files, or you can build a local copy. To do the latter just do: + + dnf install automake autoconf libtool rpm-devel \ + gtk3-devel sqlite-devel libsoup-devel + ./autogen.sh + make + +To actually run the extractor you can do: + + ./appstream-builder --verbose \ + --max-threads=8 \ + --log-dir=/tmp/logs \ + --packages-dir=/mnt/archive/Megarpms/21/Packages \ + --temp-dir=/mnt/ssd/AppStream/tmp \ + --output-dir=./repodata \ + --screenshot-url=http://megarpms.org/screenshots/ \ + --basename="megarpms-21" + +This will output a lot of progress text. Now, go and make a cup of tea and wait +patiently if you have a lot of packages to process. After this is complete +you should finally see: + + Writing ./repodata/megarpms-21.xml.gz + Writing ./repodata/megarpms-21-icons.tar + Done! + +You now have two choices what to do with these files. You can either upload +them with the rest of the metadata you ship (e.g. in the same directory as +`repomd.xml` and `primary.sqlite.bz2`) which will work with Fedora 21. + +For Fedora 20, you have to actually install these files, so you can do something +like this in the megarpms-release.spec file: + + Source1: http://www.megarpms.org/temp/megarpms-20.xml.gz + Source2: http://www.megarpms.org/temp/megarpms-20-icons.tar.gz + + %install + mkdir -p %{buildroot}%{_datadir}/app-info/xmls + cp %{SOURCE1} %{buildroot}%{_datadir}/app-info/xmls + mkdir -p %{buildroot}%{_datadir}/app-info/icons/megarpms-20 + tar xvzf %{SOURCE2} + cd - + +or, if your distro ships a new enough libappstream-glib: + + %install + DESTDIR=%{buildroot} appstream-util install %{SOURCE1} %{SOURCE2} + +This ensures that gnome-software can access both data files when starting up. + +What is an application +----------- + +Applications are defined in the context of AppStream as such: + + * Installs a desktop file and would be visible in a desktop + * Has an metadata extractor (e.g. libappstream-builder/plugins/asb-plugin-gstreamer.c) + and includes an AppData file + +Guidelines for applications +----------- + +These guidelines explain how we filter applications from a package set. + +First, some key words: + * **SHOULD**: The application should do this if possible + * **MUST**: The application or addon must do this to be included + * **CANNOT**: the application or addon must not do this + +The current rules of inclusion are thus: + + * Icons **MUST** be installed in `/usr/share/pixmaps/*`, `/usr/share/icons/*`, + `/usr/share/icons/hicolor/*/apps/*`, or `/usr/share/${app_name}/icons/*` + * Desktop files **MUST** be installed in `/usr/share/applications/` + or `/usr/share/applications/kde4/` + * Desktop files **MUST** have `Name`, `Comment` and `Icon` entries + * Valid applications with `NoDisplay=true` **MUST** have an AppData file. + * Applications with `Categories=Settings`, `Categories=ConsoleOnly` or + `Categories=DesktopSettings` **MUST** have an AppData file. + * Applications **MUST** have had an upstream release in the last 5 years or + have an AppData file. + * Application icon **MUST** be available in 48x48 or larger + * Applications must have at least one main or additional category listed + in the desktop file or supply an AppData file. + See http://standards.freedesktop.org/menu-spec/latest/apa.html and + http://standards.freedesktop.org/menu-spec/latest/apas02.html for the + full `Categories` list. + * Codecs **MUST** have an AppData file + * Input methods **MUST** have an AppData file + * If included, AppData files **MUST** be valid XML + * AppData files **MUST** be installed into `/usr/share/appdata` + * Application icons **CANNOT** use XPM or ICO format + * Applications **CANNOT** use obsolete toolkits such as GTK+-1.2 or QT3 + * Applications that ship a desktop file **SHOULD** include an AppData file. + * Screenshots **SHOULD** be in 16:9 aspect ratio + * Application icons **SHOULD** have an alpha channel + * Applications **SHOULD** ship a 64x64 PNG format icon or SVG + * AppData files **SHOULD** include translations + * Desktop files **SHOULD** include translations + License ---- |