Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
tutorial:program:oppm [2015/02/04 16:57]
vexatos [Registering packages locally]
tutorial:program:oppm [2021/01/20 18:00]
hawk777 Include “oppm register” and reorganize to deduplicate
Line 2: Line 2:
 ============================================ ============================================
  
-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.+The OpenPrograms Package Manager, called OPPM, is a program available through a dungeon ​[[item:​loot_disks|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 ##Using OPPM
Line 24: Line 24:
 Removes every file of the specified package from your system. Removes every file of the specified package from your system.
  
-##​Registering packages locally +- `oppm register <​userorgroup>/<​repository>​` 
-_Note_If you only want to use packages provided by other people and do not want to make any packages yourselfyou can stop reading now.+Adds the Github repository found at `https://​github.com/<​userorgroup>/<​repository>​` as an additional source of programs. The repository must have a branch named `master`and that branch must contain a properly structured file named `programs.cfg` in its root directory.
  
-_Note 2_General knowledge ​of using Lua and GitHub is being required.+- `oppm unregister <​userorgroup>/<​repository>​` 
 +Removes the Github repository found at `https://​github.com/<​userorgroup>/<​repository>​` from the list of additional repositories to search.
  
-To register a package yourself, ​you need to have every file the program needs to run on some repository on [[https://​github.com/​|GitHub]]. +_Note_: If you only want to use packages provided by other people and do not want to make any packages ​yourselfyou can stop reading now.
-To register your program locally, open /​etc/​oppm.cfg;​ it should look like this: +
-```lua +
-+
-    --default installation path +
-    path="/​usr",​ +
-    --Additional repositories and packages ​go herefor correct package syntax, check https://​github.com/​OpenPrograms/​Vexatos-Programs/​blob/​master/​op-manager/​etc/​opconfig.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 filehaving added two different packages ​to oppm (The first one as [[https://​github.com/​OpenPrograms/​Vexatos-Programs/​blob/​master/​op-manager/​etc/​example-config.cfg|reference]], the second one as an actual example):+##The format of a packages ​table 
 +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 peopleyou will need to create ​Github repository and a packages tableWhere the packages table lives depends on the method you use to register your repositorybut its format is the same for all methods.
  
-```lua +This is the reference for what is allowed to be in your packages table (see [[https://​github.com/​OpenPrograms/​Vexatos-Programs/​blob/​master/​oppm/​example.cfg|example.cfg]]):​
-+
-  --default installation path +
-  path="/​usr",​ +
-  --Additional repositories and packages go here, for correct package syntax, check https://​github.com/​OpenPrograms/​Vexatos-Programs/​blob/​master/​op-manager/​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/​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 [[http://​oc.cil.li/​index.php?/​index|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 [[https://​github.com/​OpenPrograms/​Vexatos-Programs/​blob/​master/​op-manager/​example.cfg|example.cfg]]):​+
  
 ```lua ```lua
Line 101: Line 43:
       ["​master/​somefolder/​bar.lua"​] = "/",​--"/"​ means the file will be placed inside the folder the user specified, defaults to /usr       ["​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/​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/​barlib.lua"​] = "/​subfolder",​--Places the file in a subfolder in the user-specified folder
-      ["​master/​somefolder/​libfolder/"] = "/"​+      ["?master/​somefolder/​something.cfg"] = "/" ​-- This file will only be installed or updated if it doesn'​t exist already, unless option -f is specified
     },     },
     dependencies = {     dependencies = {
Line 115: Line 59:
   },   },
   ["​yet-another-package"​] = {   ["​yet-another-package"​] = {
-      ​...+          ​...
   }   }
 } }
 ``` ```
  
-Here is a proper ​example ​for how your packages ​can be registered:+Here is an example ​of a packages ​table for three real programs:
 ```lua ```lua
 { {
Line 136: Line 80:
   ["​oppm"​] = {   ["​oppm"​] = {
     files = {     files = {
-      ["​master/​op-manager/​oppm.lua"​] = "/​bin",​ +      ["​master/​oppm/​oppm.lua"​] = "/​bin",​ 
-      ["​master/​op-manager/​etc/​oppm.cfg"​] = "//​etc",​ +      ["​master/​oppm/​etc/​oppm.cfg"​] = "//​etc",​ 
-      ["​master/​op-manager/​lib/​oppm.lua"​] = "/​lib"​+      ["​master/​oppm/​lib/​oppm.lua"​] = "/​lib"​
     },     },
     name = "​OpenPrograms Package Manager",​     name = "​OpenPrograms Package Manager",​
Line 144: Line 88:
     authors = "​Vexatos",​     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.",​     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/​op-manager"+    repo = "​tree/​master/​oppm"
   },   },
   ["​drama"​] = {   ["​drama"​] = {
Line 155: Line 99:
     note = "Run and have fun!",     note = "Run and have fun!",
     repo = "​tree/​master/​drama/​drama.lua",​     repo = "​tree/​master/​drama/​drama.lua",​
 +  }
 +}
 +```
 +
 +##​Registering a repository
 +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.
 +
 +###oppm register
 +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.
 +
 +###​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 [[http://​oc.cil.li/​index.php?/​index|OpenComputers forums]] or on IRC to register your GitHub repository. Your GitHub repository needs to look exactly the same as described in [[#oppm register|the previous section]].
 +
 +###oppm.cfg
 +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:
 +```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 [[https://​github.com/​OpenPrograms/​Vexatos-Programs/​blob/​master/​oppm/​etc/​example-config.cfg|reference]],​ the second one as an actual example):
 +
 +```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"​
 +      },
 +    }
   }   }
 } }