The primary specification and design document for the unicornpkg library and format.

v1.0.0

The initial specification version.

Package tables are the primary way of setting up packages with unicornpkg. They are a Lua table or a function that returns a Lua table.

The only required fields are name and pkgType, but more are recommended if you want your package to be useful.

Fields

unicornSpec

This specifies the version of the package table. This should always be set to v1.0.0.

name

This should be the same as the filename without the .lua extension.

desc

A description of the contents of the package table. Can be single-line or multiline.

maintainer

The name or pseudonym of the maintainer of the package table.

licensing

The license of the package and its contents. Should be a valid OSI identifier, or CCPL if the license is the ComputerCraft Public License.

version

The version of a package. If a project does not have versioning, do not fill out this field.

This field expects a valid SemVer string, without the v prefix.

pkgType

Specifies the package type; see Package providers for more information.

The string is formatted based on the domain of the provider; for example, GitHub's provider is com.github, and Bitbucket's provider is org.bitbucket.

instdat

A table that contains information specific to the pkgType. See individual package providers for more information.

script

A table that contains scripts that should be called at various points in the package's life.

script.preinstall

A block of Lua source code that is called before the package table is installed.

script.postinstall

A block of Lua source code that is called after the package table is installed.

script.preremove

A block of Lua source code that is called before the package is removed.

script.postremove

A block of Lua source code that is called after the package is removed.

security

A table that contains hashes and other security-related data.

security.sha256

A table that contains a name of the file (k) and the corresponding SHA-256 hash (v).

rel

A table that contains information relating to other packages.

rel.depends

A numbered table that lists required packages.

rel.conflicts

A numbered table that lists packages which break when they are installed with this package.

Package providers are the workhorse of unicornpkg; they allow you to use various online services to install packages.

Custom package providers can be created by having a .lua file in the /lib/unicorn/provider directory. That Lua file should return a single function which takes one argument (a package table) and installs a package table upon being called, with no interactive prompting.

Package remotes are a feature in unicornpkg that allow you to download package tables semi-automatically.

Specification

Remote

The remote is a simple HTTPS server. It's usually a GitHub repository, but other hosts should work fine.

Each package should be a file on the package remote ending in .lua.

All packages on the remote should return valid package tables.

Retrieval on the client

The client will have a folder called /etc/unicorn/remotes/ that will contain one serialised file per remote. Each serialised file should contain a url keyword specifiying the full HTTP path to the remote, as well as a packages table that contains known packages from that remote.

unicorn.hoof.update() should parse each file in /etc/unicorn/remotes and update the packages table.

unicorn.hoof.get() should parse each file in /etc/unicorn/remotes/ and download the requested file to /tmp/unicorn/{package_name}.lua, and then unicorn.install() should install said file.

unicornpkg recommends the following paths for package contents:

• /bin for executable Lua files. This path should be on shell.path.
• /lib for modules, APIs, and libraries. This path should be on package.path if you're writing complementary software.
• /usr/share/help/ for help files. This path should be on help.path.
• /usr/libexec for executable files for use by other programs. This path should not be on shell.path or package.path.
• /usr/libLoadAPI for APIs meant to be loaded by os.loadAPI. This path should not be on package.path. Packages should refrain from loading their APIs into the global environment by default.
• /etc/startup for files that should be executed when starting the machine.
  • Implementations MAY encourage use /startup instead when compatibility with older versions of ComputerCraft is not desired. Such older versions require /startup to be a file.
• /home for user data, or /home/{user} if you are writing a multi-user system.

If your use-case is not specified here, follow IEEE 1003.1-2017 (POSIX).

Indev (unstable)

The first revision of the specification. The only thing that is different from v1.0.0 is that instdat.filemaps and pkgType has been removed in favor of instdat.providers.

This a draft! Nothing in this version of the specification has been implemented in the reference implementation!

Package tables are the primary way of setting up packages with unicornpkg. They MUST be a Lua table. The fields name, pkgType, and unicornSpec MUST be defined.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Fields

unicornSpec

This specifies the version of the package table. This should always be set to v1.1.0.

name

This should be the same as the filename without the .lua extension.

desc

A description of the contents of the package table, as a string. Can be single-line or multiline.

homepage

A link to the program's homepage, if it has one. If set, this MUST be an absolute-URL string as defined by the WHATWG URL Standard.

maintainer

The name or pseudonym of the maintainer of the package table. This MUST be expressed as a string, if set.

license

The license of the package's contents. This MUST be expressed as an SPDX License Expression as defined in the SPDX Specification, v3.0.1.

Package definitions MAY be a different license from the license of the package's contents.

SPDX extensions

Packages MAY use CCPL and MMPL in license expressions to refer to the ComputerCraft Public License and Minecraft Mod Public License, respectively. New projects SHOULD refrain from using these licenses. If CCPL or MMPL ever become defined in the SPDX License List, those definitions MUST take precedence.

Other than the exceptions above, implementations SHOULD avoid bespoke extensions to the SPDX License List.

version

The version of a package. If a project does not have versioning, this value SHOULD be set to nil.

This field expects a valid SemVer string, without the v prefix.

instdat

A table that contains more tables that have information specific to package providers.

Each table should be structured like this:

{
	{
		provider = "com.github";
		repo_owner = "unicornpkg";
		repo_name = "cli";
		filemaps = {
			["unicorntool/init.lua"] = "/bin/unicorntool.lua";
			["doc/man/unicorntool.txt"] = "/usr/share/help/unicorntool.txt";
		};
	};
	{
		provider = "com.github"; -- You can do multiple tables with the same `provider` value!
		repo_owner = "unicornpkg";
		repo_name = "some-nonexistent-repo";
		filemaps = {
			["init.lua"] = "/bin/some-nonexistent-program.lua";
		}
	};
}

See individual package providers for more information.

script

A table that contains scripts that should be called at various points in the package's life.

script.preinstall

This value, if set, MUST be a string of Lua source code. It SHOULD be executed before the package is installed.

script.postinstall

This value, if set, MUST be a string of Lua source code. It SHOULD be executed after the package is installed.

script.preremove

This value, if set, MUST be a string of Lua source code. It SHOULD be executed before the package is removed.

script.postremove

This value, if set, MUST be a string of Lua source code. It SHOULD be executed after the package is removed.

security

A table that contains hashes and other security-related data.

Implementations MUST prevent packages with invalid hashes from being installed.

security.sha256

A table that contains a name of the installed file (e.g. /bin/some-nonexistent-program.lua) and the corresponding SHA-256 hash represented as a 256-bit hexadecimal string.

SHA-256 hashes MUST be generated by a compliant implementation of FIPS 180-4, Secure Hash Standard (SHS), or a later revision of that standard.

rel

A table that contains information relating to other packages.

rel.depends

An integer-indexed table that lists required packages.

rel.conflicts

An integer-indexed table that lists packages which break when they are installed with this package.

Package providers are the workhorse of unicornpkg; they allow you to use various online services to install packages.

Custom package providers can be created by having a .lua file in the /lib/unicorn/provider directory. That Lua file should return a single function which takes one argument (a package table) and installs a package table upon being called, with no interactive prompting.

Package remotes are a feature in unicornpkg that allow you to download package tables semi-automatically.

Specification

Remote

The remote is a simple HTTPS server. It's usually a GitHub repository, but other hosts should work fine.

Each package should be a file on the package remote ending in .lua.

All packages on the remote should return valid package tables.

Retrieval on the client

The client will have a folder called /etc/unicorn/remotes/ that will contain one serialised file per remote. Each serialised file should contain a url keyword specifiying the full HTTP path to the remote, as well as a packages table that contains known packages from that remote.

unicorn.hoof.update() should parse each file in /etc/unicorn/remotes and update the packages table.

unicorn.hoof.get() should parse each file in /etc/unicorn/remotes/ and download the requested file to /tmp/unicorn/{package_name}.lua, and then unicorn.install() should install said file.

unicornpkg recommends the following paths for package contents:

• /bin for executable Lua files. This path should be on shell.path.
• /lib for modules, APIs, and libraries. This path should be on package.path if you're writing complementary software.
• /usr/share/help/ for help files. This path should be on help.path.
• /usr/libexec for executable files for use by other programs. This path should not be on shell.path or package.path.
• /usr/libLoadAPI for APIs meant to be loaded by os.loadAPI. This path should not be on package.path. Packages should refrain from loading their APIs into the global environment by default.
• /etc/startup for files that should be executed when starting the machine.
  • Implementations MAY encourage use /startup instead when compatibility with older versions of ComputerCraft is not desired. Such older versions require /startup to be a file.
• /home for user data, or /home/{user} if you are writing a multi-user system.

If your use-case is not specified here, follow IEEE 1003.1-2017 (POSIX).