Inqlude uses manifest files to capture meta data of Qt libraries for further inspection and processing. The meta data is stored as JSON formatted files in the file system. This document describes the format.
All data is stored in a manifest directory. It can have an arbitrary name and path, but by default the inqlude command line tool assumes the path ~/.inqlude/manifests.
The manifest directory is under version control by git.
Each library represented in the Inqlude system has its own sub-directory in the manifest directory. The name of the sub-directory is the name of the library. See there for more information about its specification and how it's used.
Each version of the library has its own manifest file in the library sub-directory. The name of the manifest file is of the format:
<name>.<release_date>.manifest
The name and release_date parts have to be identical to the corresponding attributes stored in the manifest file with the same names.
The manifest files are formatted as JSON and contain a list of structured attributes describing the library and the specific version represented by the concrete file.
These are the attributes:
This is a reference to the schema which is used in the manifest file. The schema follows the JSON Schema specification.
The schema comes in three flavors: "generic", "release", and "proprietary-release". They differ in what fields are required, the meaning of fields is the same in all. "generic" is a subset of "proprietary-release", which is a subset of "release".
Each schema has an identifier. The current identifier for the release schema is "http://inqlude.org/schema/release-manifest-v1#". It includes the version number. The other identifiers are the same, but instead of "release" they use the corresponding sub string identifying the flavor.
The schema and its versioning is used to make expectations of tools and processing explicit and adapt to schema changes.
If the schema is changed in a way incompatible with processing tools, the schema version number has to be increased.
As Inqlude currently still is in alpha, changes to the schema are to be expected and while we will try to not break things, there might be some incompatible changes without changing the version number during development. This will stop, when we have reached beta state.
$schema is a mandatory attribute
Name of the library
The name of the library has to be a lower-case string with only alphanumeric characters. It has to be identical with the name part of the manifest file names and the name of the directory where the manifest is stored in the manifest repository.
As a convention Qt bindings to other libraries are named with the name of the other library and a "-qt" suffix. For example the Qt bindings to PackageKit are named "packagekit-qt" in Inqlude.
It's used as internal handle by the tools and shows up where it needs to be processed by software, e.g. as an identifier as parameter of the command line tool or as part of the URL on the web site. The name has to be identical with the value of the name attribute of the manifest files representing the different versions of the library.
name is a mandatory attribute
The real name of the library that is displayed in the website.
This holds the name in a way formatted for best human readability. This can contain characters which are upper-case, lower-case, alphanumeric, symbols and special signs.
display_name is an optional attribute
Date, when the version was released
release_date is a mandatory attribute in the release schemas
Version of the release
version is a mandatory attribute in the release schemas
One-line summary describing the library
This is the main description of the library used in summary lists etc.
summary is a mandatory attribute
Array of strings identifying the topics to which the library belongs.
Topics are used to categorize libraries. Each library has at least one topic, but can have more than one.
At the moment valid topics are:
"API", "Artwork", "Bindings", "Communication", "Data", "Desktop", "Development", "Graphics", "Logging", "Mobile", "Multimedia", "Printing", "QML", "Scripting", "Security", "Text", "Web", "Widgets"
topics is an optional attribute, preferred to have at least one topic
List of URLs relevant to the library
All URLs are represented as a key specifying the type of the URL and the actual URL itself. Arbitrary types can be defined. Some types are used for specific purposes and get special treatment.
All these URLs are meant to be consumed by humans, so they should work and make sense when shown in a web browser. Other than that they don't have very strict requirements. They are not necessarily meant to be read programmatically.
The following types are recognized:
| Attribute | Description |
|---|---|
homepage |
Home page of the library. This is the main URL used as entry point for looking up information about the library. All manifests should contain a homepage URL. |
download |
Download area where the source code of the library can be downloaded. This is not the download of the specific version of the library. This is described in the packages section. |
vcs |
URL of the source code repository where the library is developed. This should point to the home of the repo, not to a specific release. |
tutorial |
URL to tutorial-style documentation how to use the library. |
api_docs |
URL to reference documentation of the API of the library. |
description_source |
If the description text is taken from another source this URL points to the source. |
announcement |
Link to release announcement |
mailing_list |
Mailing list for discussing the library |
contact |
Contact information |
custom |
Array of pairs of title and URL of custom links |
the homepage is a mandatory url attribute
List of licenses under which the library can be used
Array of identifier strings of the software licenses under which the library can be used. This can be a free-form string, but there is a list of predefined strings for the most often used licenses:
- "LGPLv2.1+": Lesser GNU Public License 2.1 or later
- "GPLv2+": GNU Public License v2 or later
- "GPLv3+": GNU Public License v3 or later
there must be at least one license
Full description of the library
The description is a text describing the library. It can be of arbitrary length. The text is formatted using Markdown.
description is a mandatory attribute
List of authors
Array of author names and email addresses. The standard email address format "John Doe jdoe@example.com" is used.
Maturity of the release
This attribute is a flag for identifying the maturity of the release. It's used to identify stable, test, and development versions.
The flag has to be one of the following identifiers:
- "stable": for stable releases ready for production use
- "beta": for pre-releases of stable versions used for gathering feedback, not recommended for production use
- "alpha": preview releases, not suitable for production use
maturity is a mandatory attribute, it's optional in the generic schema
List of supported platforms
Array of strings identifying the platforms on which the library runs.
Supported values are:
- "Linux"
- "Windows"
- "OS X"
- "Android"
- "iOS"
there must be at least one platform
List of packages of the release
This section contains a list of data on packaged versions of the library, which can be used to run it on specific systems. This includes the source code release, but also platform-specific binary packages.
For each type of package there is a type-specific format to describe the package. The following types are supported:
This is the source code of the release. It has one URL to the file, which can be used to download the code.
source is a mandatory package attribute in the release schema, it's optional in the proprietary-release schema
openSUSE binary packages. For each version of openSUSE there is a separate entry.
Each entry contains the package_name, repository, and source_rpm attributes. The repository contains a url and a name sub-attribute.
Generic link to an Ubuntu binary package.
Generic link to generic Linux binary package.
Generic link to generic Windows binary package.
Generic link to generic Mac OS binary package.
Name of a group
The group optionally specifies the name of a group of libraries the library described by the manifest belongs to.
At the moment only the value "kde-frameworks" is used.