Permalink
Fetching contributors…
Cannot retrieve contributors at this time
270 lines (171 sloc) 8.83 KB

Inqlude manifest format

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.

Directory structure

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.

Manifest file format

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:

$schema

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

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

display_name

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

release_date

Date, when the version was released

release_date is a mandatory attribute in the release schemas

version

Version of the release

version is a mandatory attribute in the release schemas

summary

One-line summary describing the library

This is the main description of the library used in summary lists etc.

summary is a mandatory attribute

topics

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

urls

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

licenses

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

description

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

authors

List of authors

Array of author names and email addresses. The standard email address format "John Doe jdoe@example.com" is used.

maturity

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

platforms

List of supported platforms

Array of strings identifying the platforms on which the library runs.

Supported values are:

  • "Linux"
  • "Windows"
  • "OS X"

there must be at least one platform

packages

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:

source

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

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.

ubuntu

Generic link to an Ubuntu binary package.

linux

Generic link to generic Linux binary package.

windows

Generic link to generic Windows binary package.

osx

Generic link to generic Mac OS binary package.

group

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.