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.

v1.1.0

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 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.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. Can be single-line or multiline.

homepage

A link to the program's homepage, if it has one.

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.

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

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 installed file (e.g. /bin/some-nonexistent-program.lua) and the corresponding SHA-256 hash (e.g. 00000000000000000000000000000000000000000000000000000000000000000).

rel

A table that contains information relating to other packages.

rel.depends

A 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.