-
Notifications
You must be signed in to change notification settings - Fork 1
Packages
A package definition consists of:
-
Package Name
-
List of Authors allowed to maintain the repository metadata
-
A listing of available builds for the package
-
A 'last modified' timestamp accurate to the nearest millisecond.
-
Updated when anything related to the package is changed (e.g. new builds are added).
Similarly, a build definition consists of:
-
Given Version
-
Arch (the version of Minecraft the mod is compatible with; e.g. 1.7.10)
-
Side (Client/Server/Universal)
-
Platform (Operating System and Bitness, e.g. Windows x64)
-
Interfaces this build provides
-
Interfaces required by this build
-
Dependencies upon other packages, optionally including a side specifier ** Side specifiers mean that the dependency is only required on the specified side
-
Conflicts with other packages specific to this or several builds
-
Whether or not the build is tagged as stable
-
An ordered list of hashes identifying chunks for packages, in the order they should be concatenated to yield the package file.
Finally, a package file is a gzipped tarball (e.g. package.tar.gz) consisting of:
- A package definition file, "package.json", containing the build definition sans the Recommended tag and the hash list, as well as the installation script for the package
- An optional Readme.md for the package in question
- All files referenced by the installation script
- No files which are not mentioned either here or by the installation script
A semantic version is used to ease the creation of dependencies and conflicts between packages. A given version is the version of a mod that the authors have assigned to it, which may or may not be the same as the semantic version. In the case that the given version is not a semantic version, the maintainer must choose a semantic version appropriately based on the compatibility of that version of the mod with previous versions of the mod. If the author does not provide compatibility information upon changes of a module, a breaking change will be assumed: the major stride of the version number will be incremented and all others will be reset to zero. Any combination of semantic version, arch, platform, and dependencies must be unique, in that the same dependency set may be required by multiple versions, or the same version may be published to support alternate dependency sets, and that each platform can receive all sides and arches.
Packages must define a process for installation through a declarative format. Files that will be placed by the installation procedure or removed by its reversal are to be named by the installation script with their paths both in the archive and in the resulting installation. Files that may be generated by the installed package, such as configuration files, may be defined as such in a separate manner. If these files are flagged as configuration files, they will be preserved past removal of the package as long as their parent directory persists. A purge operation will remove all files from a package, including configuration files. A client must delete any files not currently accounted for by any installed package previous to launching an instance.
{
source: "<URI>",
hash: "<Hash of sourced file>",
target: "<Path relative to instance root wherein the file will reside>",
}File declarations are required for any file to be installed by mpm.
-
source: The path of the file (relative to the root of the package) to be installed (e.g. "BetterStorage-1.6.4-0.8.0.45.jar").
- Optionally, a protocol can be specified for installing files located outside of packages, allowing URLs (e.g. "https://s3.amazonaws.com/Minecraft.Download/versions/1.8.3/minecraft_server.1.8.3.jar") and other such sources to be specified. "file://" URIs are not permissible.
-
hash: A SHA-256 hash of the source file, used to ensure the integrity of a file.
-
target: The full file-path of the file to install, relative to the instance root (e.g. "mods/BetterStorage-1.6.4-0.8.0.45.jar").
Any file which is not targeted by an existing mod will be removed on launch or configuration operations. Files flagged as type cache will be cleared on modifications to the package configuration. Any targeted as configuration are cleared only on purge operations.
Wildcard Targets are a valid option for situations where file paths of items a package may create are unpredictable. These may be most useful in extract definitions. Wildcard targets may only have the wildcard asterisk (*) at the end of their target path. Do not use wildcard paths in areas another package may modify, the changes will go unmonitored.
Multiple target combinations are possible by specification of an array of strings "targets" in place of the "target" attribute. Any file declaration may optionally specify a hash to help with instance file integrity validation.
Sourceless targets may be created for covering files created by the package at runtime. These files must be of types of either configuration or cache. Configuration files are preserved across uninstallation and reinstallation, but destroyed on purge, while cache files are destroyed upon any operation that changes the package selection. Optional files, unlike standard file declarations, can be specified with wildcard paths through the use of the asterisk (*) character.
{
type: "configuration",
targets: [
"config/ic2_addons/*",
"ic2.cfg"
]
}Extraction file declarations are possible through specification of an extract attribute. This attribute is an array of standard File Declarations, but does not support further extract operations. In a situation where this is necessitated, an alternative model should be instated which uses dependencies. In the internal file declaration, sources are relative to the source archive, and protocol modifiers are not available. The source file must be of a supported filetype (tar.gz, zip). Extract definitions may not be mixed with other types, and- for example- may not be directly claimed as configuration or cache; this behavior should instead be directed to the definitions sequence internal to the extract attribute.
{
source: "minecraft://1.7.4",
hash: "Hash of the file to be downloaded",
extract: [
...
]
}Hash Store files are accessible via the "hashstore://" URI modifier, wherein a descriptive name for the file will substitute for the URI. For example:
{
source: "hashstore://<SHA256 of the file>",
description: "Forge .2078 for 1.7.10",
target: "forge.jar",
}If a mod author does not permit mpm hosting of their project, hash store file declarations are useful for allowing dependencies on such mods to exist. If, for example, a user required a file the author did not allow redistribution of, the hash stores would not be able to provide for the hash request. The user would be informed of the file they must locate manually via the description given after the "hashstore:" modifier, as well as the hash of the file required. If this situation is common enough, it may be useful for "stub" packages to be registered to the repository, containing dependency and interface information for the non-distributable mod, a link to the author's download page, and an up to date file declaration for the version specified.
Importantly, files brought in from external sources should still specify what files they may cause to be created, such as configuration files, or these may be deleted in an unexpected or unwanted manner.
Interfaces are analogous to the notion of an interface in programming languages, whereas packages are analogous to classes. A package can provide (or “implement”) 0-to-many interfaces, and can require 0-to-many interfaces.
Interfaces consist of:
- Name
- Semantic Version
The semantic version for an interface is of the form “x.y”, where x is the major version and y is the minor version.
A package can list 0-to-many dependent packages and specify what versions of the package are acceptable. A dependency uses the following format:
<name@version[@side=Universal]>
Here are some examples (Omitting side specifiers):
<[email protected]>- Requires: 1.3.2 (strict)
<BuildCraft@~1.3.2>- Requires: [1.3.2, 1.4.0)
<BuildCraft@^1.3.2>- Requires: [1.3.2, 2.0.0)
<BuildCraft@+1.3.2>- Requires: >=1.3.2 (dangerous)
The side parameter of dependencies is optional, and will default to the current side if available, or universal otherwise. If neither are available on a package that has not specified this value, an error will be raised; as an example, a server-only mod cannot be installed on a client, and if a dependency lists the server-only mod as a standard dependency, the mod will be uninstallable. Tagging that dependency with a "server" side specifier will cause it to only request installation while on a server.
The parameter is not meant to force a dependency to install, but rather to only request installation of the package when the instance shares the same Side configuration. This allows a single package to have dependencies specifically for installation upon servers, clients, or both at once, and is the core component in allowing "modpack" package groups to be installed on both a client and a server without having a special version for each side. On the universal setting, the specifier is essentially ignored, and the current side will be preferred to a hybrid option, but no filtering will take place and resolution will continue as expected for universal or side-specific packages.