Tutorial: The OpenPrograms Package Manager (OPPM)

The OpenPrograms Package Manager, called OPPM, is a program available through a dungeon loot disk in OpenComputers. It provides a large variety of programs, from now on called “packages”, for you to download and install easily. It is meant to make users able to easily distribute their programs, it is supposed to make installing, updating and uninstalling packages just as easy as creating and registering them.

Using OPPM

For OPPM to work, you will need at least a Tier 2 case and an Internet card inserted.
Once you have acquired the floppy disk containing OPPM, the first thing you should do after insertion is run oppm install oppm to install the latest version of the package manager onto your main hard drive. Once that is done, you can shut down your computer, remove the floppy disk and restart.
OPPM supports a few arguments, which will be explained now:

  • oppm list [filter] [-i]
    This command lists all the available packages by their unique name. The list is sorted by alphabet. The optional argument filter will make the list only display the packages which have the specified filter in their name. The option -i makes the command only list packages which have already been installed.
  • oppm info <package>
    Lists further information about the specified program package, such as the full name, the author(s), a description of the package and additional notes the author might have added.
  • oppm install [-f] <package> [path]
    Downloads the package to a directory on you system; if no path has been specified, it will install it to the default path specified in oppm.cfg (which is /usr by default, and you should always install packages to the default path if you don't have a very good reason not to do so). The option -f forces the installation, meaning that any already existing file will be overwritten/replaced by the downloaded ones, and if path points to a non-existing directory, that directory will be created.
  • oppm update <package>
    This command uninstalls the specified package and re-downloads it, making sure you have the very-most up-to-date version of the package. If package is “all”, every package that is currently installed will be updated.
  • oppm uninstall <package>
    Removes every file of the specified package from your system.

Registering packages locally

Note: If you only want to use packages provided by other people and do not want to make any packages yourself, you can stop reading now.

Note 2: General knowledge of using Lua and GitHub is being required.

To register a package yourself, you need to have every file the program needs to run on some repository on GitHub. To register your program locally, open /etc/oppm.cfg; it should look like this:

snippet.lua
{
    --default installation path
    path="/usr",
    --Additional repositories and packages go here, for correct package syntax, check https://github.com/OpenPrograms/Vexatos-Programs/blob/master/oppm/etc/oppm.cfg
    repos={
    }
}

You might notice the table called repos. That's where you can register your own packages. Package registration follows a rather strict syntax to make sure it will be detected properly. This is an example oppm.cfg file, having added two different packages to oppm (The first one as a reference, the second one as an actual example):

snippet.lua
{
  --default installation path
  path="/usr",
  --Additional repositories and packages go here, for correct package syntax, check https://github.com/OpenPrograms/Vexatos-Programs/blob/master/oppm/etc/example-config.cfg
  repos={
    ["YourUsername/YourRepo"] = {
      ["example-package"] = {
        files = {
          ["master/somefolder/bar.lua"] = "/",--"/" means the file will be placed inside the folder the user specified, defaults to /usr
          ["master/somefolder/barinfo.txt"] = "//etc", -- double slash for using an absolute path
          [":master/otherfolder"] = "/share/something", -- A colon marks a folder, will include everything in that folder
          [":master/otherfolder"] = "//etc/something", -- This also works with absolute paths
          ["master/somefolder/barlib.lua"] = "/subfolder",--Places the file in a subfolder in the user-specified folder
          ["master/somefolder/libfolder/"] = "/"
        },
        dependencies = {
          ["GML"] = "/lib"--This package is installed into the specified subfolder
        },
        name = "Package name",--This is for "oppm info"
        description = "This is an example description",--This is for "oppm info"
        authors = "Someone, someone else",--This is for "oppm info"
        note = "Additional installation instructions, general instructions and additional information/notes go here, this is an optional line.",
        hidden = true, -- Add this optional line to make your package not visible in "oppm list", useful for custom dependency libraries
        repo="tree/master/somefolder" --Used by the website. This is where the package will link to on the website
      },
      ["yet-another-package"] = {
              ...
      }
    },
    ["OpenPrograms/samis-Programs"]={
      ["nidus"] = {
        ["files"] = {
          ["master/nidus/nidus.lua"] = "/bin", --executable programs should always be installed to /bin
          ["master/nidus/core.lua"] = "/lib/nidus", --libraries should always be installed to /lib
          ["master/nidus/hosts.db"] = "//var/lib/nidus"
        },
        ["repo"] = "tree/master/nidus",
        ["dependencies"] = {
          ["oop-system"] = "/"
        },
        ["name"] = "NiDuS DNS Server",
        ["description"] = "A DNS server that is light and easy to use. Uses its own protocol.",
        ["authors"] = "samis"
      },
    }
  }
}

Registering packages globally

If you want to make your packages globally available (so that everyone that wants to is able to easily install your programs), you need to ask Vexatos on the OpenComputers forums or on IRC to register your GitHub repository. This repo will need to have a file called programs.cfg in the root folder for OPPM to recognize it. That is where all your packages are registered. This is the reference for what is allowed to be in your programs.cfg file (See example.cfg):

snippet.lua
{--This is an example for a programs.cfg file. Please do not add any comments inside actual programs.lua files
  ["example-package"] = {
    files = {
      ["master/somefolder/bar.lua"] = "/",--"/" means the file will be placed inside the folder the user specified, defaults to /usr
      ["master/somefolder/barinfo.txt"] = "//etc", -- double slash for using an absolute path
      [":master/otherfolder"] = "/share/something", -- A colon marks a folder, will include everything in that folder
      [":master/otherfolder"] = "//etc/something", -- This also works with absolute paths
      ["master/somefolder/barlib.lua"] = "/subfolder",--Places the file in a subfolder in the user-specified folder
      ["master/somefolder/libfolder/"] = "/"
    },
    dependencies = {
      ["GML"] = "/lib"--This package is installed into the specified subfolder
    },
    name = "Package name",--This is for "oppm info"
    description = "This is an example description",--This is for "oppm info"
    authors = "Someone, someone else",--This is for "oppm info"
    note = "Additional installation instructions, general instructions and additional information/notes go here, this is an optional line.",
    hidden = true, -- Add this optional line to make your package not visible in "oppm list", useful for custom dependency libraries
    repo="tree/master/somefolder" --Used by the website. This is where the package will link to on the website
  },
  ["yet-another-package"] = {
          ...
  }
}

Here is a proper example for how your packages can be registered:

snippet.lua
{
  ["song"] = {
    files = {
      ["master/song/song.lua"] = "/lib",
      ["master/song/song-example1.lua"] = "/bin",
      ["master/song/song-example2.lua"] = "/bin"
    },
    name = "Song API",
    description = "An API to play whole songs using computer.beep",
    authors = "Vexatos",
    repo = "tree/master/song"
  },
  ["oppm"] = {
    files = {
      ["master/oppm/oppm.lua"] = "/bin",
      ["master/oppm/etc/oppm.cfg"] = "//etc",
      ["master/oppm/lib/oppm.lua"] = "/lib"
    },
    name = "OpenPrograms Package Manager",
    description = "A program to browse, download, install and update various useful programs and libraries",
    authors = "Vexatos",
    note = "If you are running this program on a floppy disk, run 'oppm install oppm' to install this program locally on your main Hard Drive.\n Consider running 'oppm update oppm' to get the latest version of this program.",
    repo = "tree/master/oppm"
  },
  ["drama"] = {
    files = {
        ["master/drama/drama.lua"] = "/bin",
    },
    name = "Drama Generator",
    description = "asie's Drama Generator inside OC",
    authors = "Vexatos",
    note = "Run and have fun!",
    repo = "tree/master/drama/drama.lua",
  }
}

I hope this tutorial helped explaining what OPPM does and how to use it. If you have any further questions, contact me (Vexatos) on the OC forums or on IRC.

Thanks for reading!

Contents