教程：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仓库。

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

如果你想创建自己的软件包，不论是因为你想更方便地在多台电脑上安装软件还是因为你想与他人分享软件，你需要创建一个Github仓库和一份软件包列表。软件包列表的位置取决你登记仓库的方式，但无论何种方式，其格式均相同。

这是软件包列表中可存在内容的参考（参见example.cfg）：

snippet.lua

{--这是programs.cfg文件的一份样例。请勿在实际的programs.lua文件中添加任何注释
  ["example-package"] = {
    files = {
      ["master/somefolder/bar.lua"] = "/",--"/"斜线代表文件将会被置于用户指定文件夹中，默认为/usr
      ["master/somefolder/barinfo.txt"] = "//etc", --双斜线代表使用绝对路径
      [":master/otherfolder"] = "/share/something", --冒号代表一个文件夹，将包含此文件夹中的所有内容
      [":master/otherfolder"] = "//etc/something", --此写法也可用于绝对路径
      ["master/somefolder/barlib.lua"] = "/subfolder",--将文件置于用于指定文件夹的一个子文件夹中
      ["?master/somefolder/something.cfg"] = "/" --此文件只会在并不存在时才会安装或更新，除非指定-f选项
    },
    dependencies = {
      ["GML"] = "/lib"--此软件包将会被安装到指定子文件夹中
    },
    name = "Package name",--此属性用于"oppm info"
    description = "This is an example description",--此属性用于"oppm info"
    authors = "Someone, someone else",--此属性用于"oppm info"
    note = "额外安装教程、通用教程以及额外信息/注释写在此处，此行内容为可选。",
    hidden = true, --添加此行可选内容，可以让你的软件包不显示在"oppm list"中，适用于自定义依赖库
    repo="tree/master/somefolder" --供网站使用。这代表软件包应当链接到网站何处
  },
  ["yet-another-package"] = {
          ...
  }
}

以下为三个真实存在软件的软件包列表样例：

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需要知道如何找到你的软件包列表以及其中描述的组成软件包所需的文件。根据你的目标不同，你有三种选择。

如果你开发的是只有自己使用的软件包（例如，用于更方便地将你编写的软件安装在多台电脑上，或者你想用外部编辑器来编写代码并将其安装到OC模组的电脑上），那么、oppm register命令可能是最简单的选择。

1. 创建一个公开Github仓库。
2. 在仓库中，确保有名为master的分支；OPPM只会在此分支内查找programs.cfg文件。
3. 在master分支中，在仓库的顶级目录中创建一个名为programs.cfg的文件，其中包含你的软件包列表。
4. 确保你已经推送了所有文件。
5. 以你的仓库名为参数运行oppm register命令。例如，你的Github用户名为MyUser并且你将仓库命名为MyOCPackages，你需要运行oppm register MyUser/MyOCPackages。

你的软件包现在会在oppm list中显示了，并且可以用oppm install安装，就像其他软件包一样。你对programs.cfg或者构成你软件包的文件作出的改动都可以影响到OPPM。但是因为Github系统有缓存，你在推送更改后可能需要等一会。而且OPPM也有缓存，你可能需要重启OC模组的电脑才能看到改动。

当然，只要你愿意，你可以把你的仓库名分享给其他人，他们也可以登记这个仓库并且使用你的软件。

请注意，你不必把所有软件都存放到master分支中。只有programs.cfg必须位于master分支的顶级目录中，但是鉴于files表中每个元素的第一个组成部分都是分支名，你也可以指向位于其他分支的软件。

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!