Difference between revisions of "Manifest.plist"

Revision as of 19:23, 29 April 2014

Note: this page describes a feature added in Oolite 1.79, that is still subject to potentially significant changes before release.

The manifest.plist file is placed in the root folder of the OXP or OXZ, and is a dictionary with the following required and optional keys. In OXZ-format expansion packs, this file is required and requires.plist may be omitted. In OXP-format expansion packs it is optional and requires.plist must also be included for compatibility.

Required keys

identifier

A unique text string identifying this OXP. This should generally be selected when the OXP is first created and not changed after that.

"identifier" = "oolite.oxp.author-name.oxp-name";

required_oolite_version

A string indicating the minimum Oolite version required to run this OXP. If this OXP is intended to be compatible with Oolite versions prior to 1.79 or is not distributed in OXZ format, then this information must be duplicated in a requires.plist file, as versions prior to 1.79 are not able to process manifest.plist files.

"required_oolite_version" = "1.79";

title

The human-readable title of the OXP. This should generally also be unique to avoid confusion.

"title" = "My OXP";

version

The version of this release of the OXP, in major.minor.release format (fewer or additional dots may be used, but all components should be numeric). Any released change to an OXP, no matter how small, should have a different version number to all previously released versions.

"version" = "1.1.3";

Mostly-required keys

These keys are not required for Oolite to be able to load an OXZ, but are required for it to be downloadable by the OXZ manager.

description

A short description of the OXP. Descriptions more than around 250 characters should be avoided.

"description" = "Adds a new station near the sun to systems with 'solar activity' in their description";

download_url

This parameter should only be used for OXPs released in OXZ format, and should provide a direct download link to the OXZ file. This parameter must not be used to link to anything other than an OXZ file. The download URL should be changed for each released version.

"download_url" = "http://www.oolite.org/example-1.1.3.oxz";

Note that because the download_url is no longer needed once the user has the OXZ file, there is no requirement for the copy of the manifest.plist inside the OXZ file to contain this tag, if for instance the file host being used does not allow the URL to be determined prior to uploading the file.

Optional keys

author

A text string describing the author or authors of the OXP.

"author" = "J Smith, OXPWriter19";

file_size

An advisory property giving an approximate size in bytes of the OXZ file. This is ignored when loading the OXZ but is displayed to users considering downloading the OXZ. (It therefore strictly only needs to be in the manifest index, not in the copy inside the OXZ itself). It is also ignored for packs distributed in OXP format.

"file_size" = 17988;

information_url

The URL of a web page (or a representative one of a set of web pages) where more information on this OXP may be obtained.

"information_url" = "http://wiki.alioth.net/ExampleOXP";

license

A short description of the copyright license the OXP is released under. A text file expanding on this should be included within the OXP: this is solely a summary to allow quick searching.

"license" = "Gnu Public License v2+";
"license" = "CC-BY-NC-SA 3.0 with extra terms";
"license" = "Use but do not modify";

maximum_oolite_version

The maximum version of Oolite this OXP is intended to work with. This should only be specified if future incompatibility is known.

"maximum_oolite_version" = "1.79.999";

Dependency management keys

The following optional keys are used to manage dependencies between OXPs. Each key takes a list of dictionaries, with the same format.

conflict_oxps

A list of OXPs which conflict with this OXP and should not be installed at the same time. If any OXP in this list is detected, then this OXP will not be loaded by Oolite, and the player will be notified through a message on the start up screen.

If OXPs A and B both declare conflicts with each other through a manifest.plist file, then Oolite will load one of the OXPs randomly.

optional_oxps

A description of OXPs which might be considered appropriate to install alongside this one - either because they enhance the functioning of the OXP or because this OXP has been designed to complement them, which are not required for the functioning of this OXP. No action will be taken if an optional OXP is missing.

requires_oxps

A list of OXPs which are required before this OXP can be used. For example, a retexture OXP might depend on the OXP which adds the original models. If any of the OXPs in this list are absent, then this OXP will not be loaded by Oolite, and the player will be notified through a message on the start up screen.

It is safe for OXP A to require OXP B and OXP B to require OXP A.

Keys used in dependency dictionaries

Each dependency dictionary in the above lists must contain an "identifier" and a "version" key. The "identifier" must match the "identifier" of the other OXP as set in its manifest.plist, and the "version" is the minimum version of that OXP required/conflicted with ("0" will match all versions).

Additionally, a "maximum_version" key may be added if the dependency OXP has relevant changes which make the dependency specific to a particular version, and a "description" key may be added to give a more readable description (maximum 256 characters and ideally much shorter) of the problem if the dependency is not met (this is especially important for "requires" dependencies, as the user may not be able to recognise an OXP they have never installed solely from its identifier)

"conflict_oxps" = (
  {
    "identifier" = "oolite.oxp.an-other.example-oxp";
    "version" = "0";
    "maximum_version" = "1.3.4";
    "description" = "This OXP and Example OXP do the same thing in different ways.
          If you install both the effects get combined badly. Version 1.3.5 and later of Example OXP
          has a check for this and will work correctly with it.";
  }
);

"requires_oxps" = (
  {
    "identifier" = "oolite.oxp.an-other.library-oxp";
    "version" = "1.3";
    "description" = "This OXP requires at least version 1.3 of Library OXP.";
  },
  {
    "identifier" = "oolite.oxp.an-other.shipset";
    "version" = "0.1";
    "description" = "This OXP requires Other's Shipset OXP";
  }
);

@@ Line 56: / Line 56: @@
  "download_url" = "<nowiki>http://www.oolite.org/example-1.1.3.oxz</nowiki>";
+Note that because the download_url is no longer needed once the user has the OXZ file, there is no requirement for the copy of the manifest.plist inside the OXZ file to contain this tag, if for instance the file host being used does not allow the URL to be determined prior to uploading the file.
 ==Optional keys==