Difference between revisions of "Manifest.plist"

Latest revision as of 11:10, 8 October 2024

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.

Syntax

The manifest syntax is in Property List format. The representation is then either XML or GNUStep. There was an initiative to move from XML to GNUStep: https://bb.oolite.space/viewtopic.php?f=2&t=10039

XML Example

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
	<key>identifier</key>
	<string>oolite.oxp.EricWalch.PirateCove</string>
	<key>required_oolite_version</key>
	<string>1.74</string>
	<key>title</key>
	<string>Pirate Cove</string>
	<key>version</key>
	<string>1.4.2</string>
	<key>category</key>
	<string>Ambience</string>
	<key>description</key>
	<string>Adds pirate bases to te system that are situated in rock hermits.</string>
	<key>author</key>
	<string>Lazy Gun & Eric Walch</string>
	<key>information_url</key>
	<string>http://wiki.alioth.net/index.php/Pirate_Coves_OXP</string>
	<key>license</key>
	<string>CC-BY-NC-SA 3.0</string>
	<key>tags</key>
	<array>
		<string>Hermits</string>
		<string>Pirates</string>
	</array>
       <key>conflict_oxps</key>
       <array>
           <dict>
               <key>identifier</key>
               <string>oolite.conflictoxp.exp1</string>
               <key>version</key>
               <string>1.0</string>
           </dict>
           <dict>
               <key>identifier</key>
               <string>oolite.conflictoxp.exp2</string>
               <key>version</key>
               <string>1.0</string>
           </dict>
       </array>
       <key>requires_oxps</key>
       <array>
           <dict>
               <key>identifier</key>
               <string>oolite.requiredoxp.exp1</string>
               <key>version</key>
               <string>1.0</string>
           </dict>
           <dict>
               <key>identifier</key>
               <string>oolite.requiredoxp.exp2</string>
               <key>version</key>
               <string>1.0</string>
           </dict>
           <dict>
               <key>identifier</key>
               <string>oolite.requiredoxp.exp3</string>
               <key>version</key>
               <string>1.0</string>
           </dict>
       </array>
       <key>optional_oxps</key>
       <array>
           <dict>
               <key>identifier</key>
               <string>oolite.optionaloxp.exp1</string>
               <key>version</key>
               <string>1.0</string>
           </dict>
           <dict>
               <key>identifier</key>
               <string>oolite.optionaloxp.exp2</string>
               <key>version</key>
               <string>1.0</string>
           </dict>
           <dict>
               <key>identifier</key>
               <string>oolite.optionaloxp.exp3</string>
               <key>version</key>
               <string>1.0</string>
           </dict>
           <dict>
               <key>identifier</key>
               <string>oolite.optionaloxp.exp4</string>
               <key>version</key>
               <string>1.0</string>
           </dict>
       </array>
    </dict>
</plist>

GNUStep Example

This custom format is a list of key-value pairs, all wrapped between curly braces. Let's look at an example (this example is patchwork of stuff found across existing OXPs):

/* manifest.plist
 *
 * Author: Stormrider (Morgan Orr)
 *
 * This work is licensed under the Creative Commons
 * Attribution-Noncommercial-Share Alike 4.0 Unported License.
 *
 * To view a copy of this license, visit
 * http://creativecommons.org/licenses/by-nc-sa/4.0/ or send a letter
 * to Creative Commons, 171 Second Street, Suite 300, San Francisco,
 * California, 94105, USA.
 * 
 * I STRONGLY encourage the modification and development of this free software by anyone to meet your needs, I only ask that you give me credit for the original work. Thanks and enjoy.
 *
 * manifest.plist for the Darkside-Moonshine-Distillery.oxz.
 */
{
	identifier = "oolite.oxp.cim.camera-drones";
        identifier = oolite.oxp.Svengali.BGS;
	version = "1.4";
	title = "Camera Drones";
	required_oolite_version = "1.77";
 //	maximum_oolite_version = "1.80";
	description = "Drone cameras which provide a variety of alternative external views for your ship";
	category = "Equipment";
        author = "cim";
	license = "CC-BY-SA 3.0";
	download_url = "http://compsoc.dur.ac.uk/~cim/oolite/Camera_Drones_1.4.oxz";
	information_url = "http://wiki.alioth.net/index.php/Camera_Drones";
      	file_size = 1750;
	requires_oxps = (
		{
			"identifier" = "oolite.oxp.cim.ships-library";
			"version" = "0.6";
			"description" = "Requires the Ship's Library to be read";
		}		
	);
       requires_oxps: = (
          {
              identifier = "oolite.oxp.Svengali.Library";
              version = "1.7.1";
              description = "Library is a collection of useful snippets, helpers and resources to simplify some common tasks used by AddOns.";
          }
       );
	optional_oxps = (
		{
			identifier = "oolite.oxp.cim.combat-simulator";
			version = "1.1";
			description = "Combat Simulator";
		},
		{
			identifier = "oolite.oxp.Norby.Carriers";
			version = "0.9";
			description = "Carriers";
		},
		{
			"identifier" = "oolite.oxp.cim.ships-library";
			"version" = "0.6";
			"description" = "Requires the Ship's Library to be read";
		}		
	);
	version = 0.24;
        tags = (shields,);
        tags = ();
	"tags" = ("additional planets")
}

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";

Note that changing the identifier of an existing OXP will have the following consequences:

Oolite will not recognise the OXP as the same, and offer it as an upgrade
Oolite will not recognise the OXP as the same, and allow both old and new to be installed at once
OXPs which require the old OXP will not require the new OXP instead
OXPs which conflict with the old OXP will not automatically conflict with the new OXP
Other OXP tools may also have problems

Other than when an OXP is being forked (not merely adopted from its original maintainer) or where a version change is considered so significant that it's no longer a successor OXP (in which case, it's perhaps best treated as an entirely new OXP!) there should be no reason to change the identifier. If you do, some steps to help alleviate the problems:

Make sure the new OXP identifier conflicts with the old OXP identifier to prevent double installs
Make sure the new OXP conflicts with any OXP which conflicts with the old OXP, to reduce the number of immediate updates needed
Announce the change publicly well in advance of making it, and if there are OXPs requiring your old OXP, notify their maintainers.

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 catalog (the manifest index used by the expansion manager), 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";

upload_date

The date when the expansion was uploaded.

This field is actually populated by the expansion management functions on the Oolite website and not expected to be filled by expansion authors. See https://oolite.space/admin/ The format is the number of seconds since midnight of 01JAN1970 (also known as 'the epoch').

"upload_date" = 1397317583;

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";
  }
);

Links

Problems with the manifest.plist (2024) - when a downloaded oxp has then been modified