README.md 4.96 KB
Newer Older
1
AppStream
2
=========
Matthias Klumpp's avatar
Matthias Klumpp committed
3
<img align="right" src="docs/images/src/png/appstream-logo.png">
4

Matthias Klumpp's avatar
Matthias Klumpp committed
5
6
7
8
9
10
11
12
13
14
15
AppStream is a collaborative effort for making machine-readable software metadata easily available to programs that need it.
It is part of the Freedesktop ecosystem and provides a convenient way to retrieve information about available software,
making it one of the building blocks for modern software centers.

AppStream consists of a specification to describe individual software component metadata in XML (so-called MetaInfo files), as well as
a derived specification for a metadata-collection format to provide a list of these metadata entries in XML or YAML for easy
consumption by software centers and other tools which need to know about available software in a repository.
In addition to the metadata specification, AppStream specifies a set of related features to help providing better metadata for software
repositories (primarily in Linux distributions).
This reference implementation of AppStream provides a shared library to work with these metadata files, features to index and query their
data quickly, as well as other useful related functionality to make building programs which work with software metadata very easy.
16

Matthias Klumpp's avatar
Matthias Klumpp committed
17
18
This repository contains:
 * the AppStream specification
Matthias Klumpp's avatar
Matthias Klumpp committed
19
20
21
 * the `appstreamcli` utility to access and edit metadata, manipulate caches, show diagnostic information, etc. (see `man appstreamcli`)
 * a GLib/GObject based library for reading and writing AppStream metadata in XML and YAML, accessing the system data pool, and auxiliary functionality
 * a Qt5 based library for accessing AppStream
22
23

## Useful Links
Matthias Klumpp's avatar
Matthias Klumpp committed
24
25
26
[AppStream Documentation](https://www.freedesktop.org/software/appstream/docs/) - The AppStream specification and help  
[Releases](https://www.freedesktop.org/software/appstream/releases/) - All (signed) releases of AppStream  
[AppStream on Freedesktop](https://www.freedesktop.org/wiki/Distributions/AppStream/) - The original Freedesktop.org page  
27

28
29
For help and development discussion, check out the [AppStream mailinglist](https://lists.freedesktop.org/mailman/listinfo/appstream).

Matthias Klumpp's avatar
Matthias Klumpp committed
30
31
32
33
34
35
36
37
38
## Users

If you are an upstream application author and want to add a MetaInfo file to your application, check out the
[Quickstart Guides](https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html) in the documentation.
An even quicker way to get to your metadata is using the [MetaInfo Creator](https://www.freedesktop.org/software/appstream/metainfocreator/)
web application. You can check out its source code [here](https://github.com/ximion/metainfocreator).

If you are a (Linux) distributor or owner of a software repository you want to generate AppStream Collection Metadata for,
you may want to take a look at the [AppStream Generator](https://github.com/ximion/appstream-generator) project.
Matthias Klumpp's avatar
Matthias Klumpp committed
39

40
## Developers
41
![Build Test](https://github.com/ximion/appstream/workflows/Build%20Test/badge.svg)
42
[![Translation status](https://hosted.weblate.org/widgets/appstream/-/svg-badge.svg)](https://hosted.weblate.org/engage/appstream/?utm_source=widget)
43
44
45

### Dependencies

Matthias Klumpp's avatar
Matthias Klumpp committed
46
#### Required
Matthias Klumpp's avatar
Matthias Klumpp committed
47
48
 * Meson (>= 0.48)
 * glib2 (>= 2.58)
49
50
 * GObject-Introspection
 * libxml2
51
 * libyaml
52
 * libcurl (>= 7.62)
Matthias Klumpp's avatar
Matthias Klumpp committed
53
 * LMDB
54

55
#### Optional
Matthias Klumpp's avatar
Matthias Klumpp committed
56
 * Vala Compiler (vapigen) (for Vala VAPI file)
Matthias Klumpp's avatar
Matthias Klumpp committed
57
 * [Snowball](https://snowballstem.org/download.html) (for stemming support)
58

59
#### Qt (for libappstream-qt)
Matthias Klumpp's avatar
Matthias Klumpp committed
60
 * Qt5 Core
61

62
63
64
65
66
67
68
#### Documentation / Specification
 * [DAPS](https://github.com/openSUSE/daps)

If you are using the released tarballs, the HTML documentation will be prebuilt and DAPS, which is a heavy
dependency, is not required to make it available locally. Of course, AppStream doesn't need the documentation
to function, so it can even be built completely without it.

Matthias Klumpp's avatar
Matthias Klumpp committed
69
### Build instructions
70

71
To compile AppStream, make sure that you have all required libraries (development files!) installed.
Matthias Klumpp's avatar
Matthias Klumpp committed
72
Then continue (the build system will complain about missing dependencies).
73

Matthias Klumpp's avatar
Matthias Klumpp committed
74
Use Meson to configure AppStream and build it with ninja:
75
```bash
76
77
mkdir build
cd build
Matthias Klumpp's avatar
Matthias Klumpp committed
78
79
80
meson <flags> ..
ninja
ninja test
81
82
```
Possible AppStream-specific flags are:  
83
84
 -Dqt=true          -- Build the Qt interface library (default: false)  
 -Dvapi=true        -- Build Vala API to use the library with the Vala programming language (default: false)  
85
 -Ddocs=true        -- Build specification and other documentation, requires DAPS (default: false)  
86
 -Dinstall-docs=true -- Install documentation (default: true)  
87
88
89
 -Dmaintainer=true  -- Enable strict compiler options - use this if you write a patch for AppStream (default: false)  
 -Dstemming=true    -- Enable support for stemming in fulltext searches (default: true)  
 -Dapt-support=true -- Enable integration with the APT package manager on Debian (default: false)
90

91
### Installation
92

Matthias Klumpp's avatar
Matthias Klumpp committed
93
To install the compiled binaries and required data, execute
Matthias Klumpp's avatar
Matthias Klumpp committed
94
`ninja install` with superuser permission.
Matthias Klumpp's avatar
Matthias Klumpp committed
95
96

## Translators
97
98
You can help translating AppStream via Weblate.
Check out the [AppStream Weblate Page](https://hosted.weblate.org/projects/appstream/translations/).