Introduction

Packages are distributed in PAR format and can be installed from any configured repository. The packages will be extracted to /pkg/packages/<package_name>/.

Package structure

manifest.json *
settings.json
aliases.json
completions.json
hooks/
  install.lua
  startup.lua
  uninstall.lua
programs/
  main.lua
  ...
modules/
  helper.lua
  ...

Configuration files

manifest.json

The only mandatory one, used by the package uploader. Fields marked with* are mandatory:

{
  * "name": "package-name",
  * "version": "1.0.0",
    "author": "Dingus Mc Doofus",
    "description": "Something about the package",
    "dependencies": [
      package1_name,
      package2_name,
      ...
    ]
}

settings.json

Defines settings to be registered by pkg on startup. It must contain a JSON object with setting names as keys and definitions as values. The names of settings should be prefixed with the package name to avoid conflicts (see example below). Each definition must be an object with the format:

Key	Type	Description
description	string?	Description for this setting
type	string?	One of "number", "string", "boolean", "table"
default	any?	Default value for this setting

Example settings.json

{
  "package-name.debug_mode": {
    "description": "Enable debug printing",
    "type": "boolean",
    "default": false
  },
  "package-name.username": {
    "description": "Name of the user",
    "type": "string"
  }
}

aliases and completions

TODO: Define the files structure

hooks

Scripts executed by the manager when performing certain actions:

• startup.lua executed at startup
• install.lua executed during installation, after the package has been extracted
• uninstall.luaexecuted when uninstalling the package, before the manager deletes the package folder

programs and modules

Not mandatory, but suggested:

• programs/ contains any script meant to be used as a program, for which might be desirable to configure aliases and completions
• modules/ contains any script meant to be used as a module

Packages installation

Running pkg install package_name will:

• fetch the package, retrieving the latest version if not passed as extra arg
• extract it
• fetch any dependency found in the manifest dependencies field
• run the package install hook

Packages initialization

When rebooted, the computer startup.lua (in the computer's root) will run pkg init.

From this, pkg will go through the list of packages in the index, for each package performing the following steps (if the corresponding files are present):

• load the settings
• load aliases
• load completions
• execute the package init

When done, pkg will load user .setting and init.lua (in the computer's root).

Startup directives might be defined in startup.lua, but since it's used to bootstrap pkg it might change in the future (altho unlikely) and thus wiped out when pkg is updated, so init.lua is the safest way.

A similar reasoning goes for package settings: while possible to configure a package by editing its own settings.json, that might change when the package is updated, as such it will be safer to override the defaults in the computer's root .setting.

Repositories

Package repositories can be configured in /pkg/repositories.json. This file contains an array of objects with the format:

Key	Type	Description
name	string	Human-readable name for this repository
type	string	Type of this repository, see below for supported types

By default, pkg ships with:

[
  {
    "name": "main",
    "type": "forgejo",
    "domain": "forgejo.sillyjune.xyz",
    "owner": "motherpacker"
  }
]

The following types are available, each adding extra keys to the respository object:

"forgejo"

Fetches packages from the generic package registry of the given Forgejo instance.

Key	Type	Description
domain	string	Domain of this Forgejo instance, e.g. "forgejo.sillyjune.xyz"
owner	string	Username of the registry owner, e.g. "motherpacker"