教程：OpenPrograms软件包管理器(OPPM)

OpenPrograms软件包管理器（The OpenPrograms Package Manager），简称OPPM，是OpenComputers模组的一个可从地牢奖励箱软盘中获取的软件。此软件提供了种类繁多的程序（下文称为“软件包”）供您方便地下载与安装。此软件致力于帮助用户降低分发自己程序的难度，在此软件上安装、升级与卸载软件就像创建与登记软件那么容易。

为了能够使用OPPM，你需要拥有至少二级的机箱，并插入因特网卡。 在你获得了装有OPPM的软盘之后，把它插到电脑里，然后你首先应该运行oppm install oppm来将最新版本的软件包管理器安装到你的主硬盘上。安装完成后，你可以随意关闭电脑、取出磁盘或重启电脑。

OPPM支持若干参数，参数将会在下文讲解：

• oppm list [filter] [-i]
  此命令将会列出所有可用软件包的名称。列表按字母顺序排列。可选参数filter可以让列表只显示名称匹配指定过滤条件的软件包。-i选项可以让命令仅列出已经被安装的软件包。
• oppm info <package>
  列出指定软件包的详细信息，例如完整名称、作者、软件包描述以及作者可能添加的其他额外注释。
• oppm install [-f] <package> [path]
  将软件包下载到你系统中的某个目录；若不指定path参数，则会安装到在oppm.cfg中指定的默认路径（默认为/usr，如果你没有特别理由，就不要改动安装位置）。-f选项可以强制安装，即已存在的任何文件都将被下载的文件覆盖/替换。并且如果path指向不存在的目录，则会创建此目录。
• oppm update <package>
  此命令将会卸载并重新安装指定软件包，以确保你能拥有软件包的最新版本。若package参数为“all”，则会更新已安装的所有软件包。
• oppm uninstall <package>
  从你的系统中移除指定软件包的所有文件。
• oppm register <userorgroup>/<repository> 将位于https://github.com/<userorgroup>/<repository>的Github仓库作为额外软件源添加。仓库中必须有名为master的分支，且此分支的根目录下必须有名为programs.cfg的文件结构配置文件。
• oppm unregister <userorgroup>/<repository> 从额外软件源列表中移除位于https://github.com/<userorgroup>/<repository>的Github仓库。

注： 如果你只是想使用他人提供的软件包，而并不想自己制作软件包，那么可以停止阅读了。

If you want to create your own packages, either to make it easier to install your software on multiple computers or because you want to share it with other people, you will need to create a Github repository and a packages table. Where the packages table lives depends on the method you use to register your repository, but its format is the same for all methods.

This is the reference for what is allowed to be in your packages table (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/something.cfg"] = "/" -- This file will only be installed or updated if it doesn't exist already, unless option -f is specified
    },
    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 an example of a packages table for three real programs:

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",
  }
}

OPPM needs to know how to find your packages table and the files that make up the packages it describes. Depending on your goal, there are three options available.

If you are developing packages that are only for your own use (e.g. as a way to easily install software you wrote on multiple computers, or because you want to use an external editor to edit your code and install it on an OpenComputers computer), the oppm register command is probably the easiest option.

1. Create a public GitHub repository.
2. Within the repository, ensure there is a branch named master; OPPM will only look for programs.cfg in this branch.
3. In the master branch, at the top level of the repository, create a file named programs.cfg containing your packages table.
4. Make sure you have pushed all your work.
5. Run oppm register for your repository name; for example, if your GitHub username is MyUser and you named your repository MyOCPackages, you would run oppm register MyUser/MyOCPackages.

Your packages will now appear in oppm list and can be installed with oppm install just like any other packages. Any changes you make to programs.cfg or to the files making up your packages will become available to OPPM, though due to caching in GitHub’s systems you may need to wait a short time after pushing, and due to caching in OPPM you may need to reboot the OpenComputers computer before you will see the changes.

Of course, you can share the name of your repository with other people who can also register it and use your programs if you wish.

Note that you do not need to develop all your software on the master branch. programs.cfg needs to live at the top level of the master branch, but since the first path component of each element in the files table is a branch name, you can refer to programs in other branches.

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. Your GitHub repository needs to look exactly the same as described in the previous section.

You can also add an additional repository by editing /etc/oppm.cfg. The difference with this method is that you need to place the entire packages table in /etc/oppm.cfg rather than in the repository (the repository can contain a packages table, but it will be ignored if you use this method).

In most cases oppm register is preferable because it allows you to write the packages table only once (rather than having to copy it to every computer and keep it up to date) and to keep it together in the same place as your code and data files. However, this method may be useful if you wish to install Lua programs from some repository that is not your own, and that repository does not provide a programs.cfg file.

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. Each entry in the table has a repository name (GitHub UserOrGroup/RepoName) as its key and the corresponding packages table as its value. 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"
      },
    }
  }
}

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!