RISC OS cogwheel

— The RISC OS Packaging Project —

RiscPkg User Guide

Home
Packages
Distributions
Source Code
Bugs
Mailing Lists
Documents
Publications
Services
Contact

RiscPkg User Guide

Version 0.3.1 (25 Feb 2005)

Introduction

RiscPkg is a package manager for RISC OS. Its three main functions are:

  • to download and install new software packages on request;
  • to update installed software packages when new versions are released; and
  • to remove software packages when they are no longer needed.

Unnecessary interaction with the user is avoided. Once the user has set policy for whereabouts different types of file should be placed, RiscPkg implements that policy automatically. If one package requires another in order to run, a request to install the first package will cause the second to be installed also. If a package has been installed automatically but is no longer needed, it is removed.

Software must be distributed using a specific package format to make this behaviour possible. Initially the number of packages available in this format is likely to be quite small but it is hoped that the collection will grow with time.

Although RISC OS does not need a package manager in quite the same way as (for example) GNU/Linux does, there are benefits to be gained by using one:

  • The work needed to keep large numbers of packages up to date is greatly reduced.
  • Dependencies (such as modules and fonts) can be satisfied automatically.
  • An easy mechanism for satisfying dependencies makes it more likely that resources will be shared.
  • A package collection will make software easier to find, and help to ensure its quality and continued availablilty.

Please note that although RiscPkg provides the means to scatter package content far and wide across the filesystem, that is absolutely not its intended purpose. With a few exceptions, the files that belong to a RISC OS application can and should be bundled into an application directory.

Not everyone will want to use RiscPkg and it is not intended that package files become the only (or even the main) method of distributing RISC OS software. However, just in case a package file is the only format to hand, nothing has been done to prevent it being used outside RiscPkg. A package is simply a zip file with a particular directory structure and a few special files. It can be unpacked using any of the usual tools.

A Warning

Package managers by their nature have the potential to do serious harm to your filesystem. At this stage of its development, the risks posed by RiscPkg itself (as opposed to software you may choose to install using RiscPkg) are judged to be as follows:

  • failure of software that RiscPkg has installed: moderate
  • failure of other software: low but non-negligible
  • corruption or deletion of user data: very low

If you use your machine for any purpose where such failure could result in serious harm then it is strongly recommended that you make sufficiently frequent and regular backups of your programs and data to avoid such harm.

No Warranty

RiscPkg is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Installing RiscPkg

  1. Obtain a copy of the !RiscPkg application directory. This copy will not be installed permanently, but rather used to bootstrap a managed version. If you have a suitable image filing system then it can be run from within an archive.
  2. Optionally, create the configuration files Choices:RiscPkg.Sources and Choices:RiscPkg.Paths. The required format is described below. If you do not supply these files then the defaults in !RiscPkg.Resources will be used automatically.
  3. Run RiscPkg by double-clicking in the application directory. It will install an icon on the icon bar.
  4. Click on the RiscPkg icon. This normally opens the main window, but if you have not used RiscPkg before it will instead ask you to create a package database directory.
  5. Create the package database directory as instructed. In principle it can be placed anywhere, but the default location of !Boot.Resources is recommended for most users.
  6. Click on the RiscPkg icon again, which should open the main window. If you have not used RiscPkg before then this window will be empty.
  7. Open the window menu and click on Update. This will attempt to download lists of available packages from the sources you have specified. Depending on the sources you have chosen, you will probably need to be connected to the internet for this to work. When the update is complete, a list of available packages should appear.
  8. Look for the package RiscPkg. (If this does not appear, none of the sources ou have chosen provide RiscPkg, in which case you probably want to add one that does.) Select this package by clicking on it, then click on Package => Install from the menu. A small letter ‘i’ should appear next to the package to indicate that it is selected for installation.
  9. Click on Commit from the menu. This will download and install RiscPkg.
  10. Select RiscPkg again, then click on Selection => Apps ... from the menu. This should open a window containing an icon labelled !RiscPkg.
  11. Drag the !RiscPkg icon from the window to a directory of your choosing. Provided you are using the default settings, this will create an ‘application stub’ which looks and behaves like !RiscPkg but is really only a pointer.
  12. Once you have confirmed that the stub copy of RiscPkg exists and is functional, you can delete the temporary bootstrap copy used up to this point.

By default, the ‘real’ copy of RiscPkg is installed in the directory Apps.Admin on the disc containing your !Boot directory. It can be moved if necessary, but you mustn’t do so without at least telling RiscPkg where it has moved to.

Using RiscPkg

Introduction

At any given time, a package can be in one of five possible states:

  • installed (package fully unpacked and configured);
  • half-configured (package fully unpacked, but configuration interrupted or in progress);
  • unpacked (files unpacked and in their correct location, but package not configured);
  • half-unpacked (unpack operation interrupted or in progress);
  • removed (static files removed but configuration files remain); and
  • not present (package fully purged or was never installed).

In addition to its current state, each package also has a selected state. When you decide which packages to install and which to remove, it is the selected state that is modified immediately. Only when you commit the changes does RiscPkg try to make the current state equal to the selected state.

The Main Window

Clicking on the RiscPkg icon causes the main window to appear. This contains a table which shows the current state, selected state, name and description of each available package.

The current state of a package is indicated by one of the following codes: ‘i’ for installed, ‘hc’ for half-configured, ‘u’ for unpacked, ‘hu’ for half-unpacked, ‘r’ for removed and blank for not present. This may be followed by the code ‘a’ if the package was installed automatically to satify a dependency, and ‘h’ if the package is on hold.

The selected state is given using a different set of codes which indicate what action will be taken with respect to the current state. These are ‘i’ for install, ‘u’ for unpack, ‘r’ for remove and ‘p’ for purge. As above, if the package was selected automatically this is indicated by an ‘a’

Note that the selected state of a package has nothing to do with whether the package is selected so far as the RISC OS desktop is concerned. The latter is shown in the usual manner (by highlighting the line or lines in question) and allows the usual mouse operations.

Updating the Package List

RiscPkg does not update the list of available packages unless you tell it to. (That is why the list is initially empty.) Click on Update from the menu to download from each of the configured sources then rebuild the list.

How often it is necessary to update will depend on which distribution you are using. A stable distribution will change rarely, except perhaps for security updates. The unstable distribution you will need to update regularly because the packages it refers to are likely to disappear as they are superceded.

Installing Packages

To install a package, select it then click on Package => Install from the menu. This will cause it to be selected for installation, indicated by a small letter ‘i’ in the selected status column. If the package has dependencies then they will also be selected for installation (but with the ‘a’ flag to indicate that the installation was automatic).

You can select any number of packages for installation in one batch. When you are ready, click Commit frm the menu. This will cause the packages to be downloaded and installed.

As a safety measure, RiscPkg will not overwrite files that already exist. Instead, it displays all conflicting pathnames in a window and cancels the installation. This is most likely to happen for modules and fonts. If you wish to proceed with the installation then you must either delete the conflicting files or move them to another location. (The latter course of action is recommended in case you wish to revert.)

Removing Packages

To remove a package, select it then click on Package => Remove from the menu. This will cause it to be selected for removal, indicated by a small letter ‘r’ in the selected status column. Alternatively you can click on Package => Purge, indicated by a small letter ‘p’, to delete all traces of the package (including any configuration files). If the packages had dependencies which are no longer needed then they are selected for removal too.

You can select any number of packages for removal, and you can both install and remove in one batch. When you are ready, click Commit from the menu.

Upgrading Packages

To upgrade individual packages, select them for installation as if they were new packages. If a new version is available then an ‘i’ will appear in the selected state column. To upgrade all installed packages, click Upgrade from the menu. In either case, click Commit for the upgrade to take effect.

The Applications Window

For convenience, it is possible to ask RiscPkg to list the applications provided by a given set of installed packages. It is then possible to perform a variety of common operations on those applications. To do this, select the packages of interest then click on Selection => Apps ... from the menu. Note that the resulting window will only contain applications provided by packages that are currently installed.

The following operations are provided:

  • create an application stub
  • create a LinkFS symbolic link
  • copy application
  • move application (not yet implemented)
  • boot application
  • run application
  • display help for application
  • view directory that contains application

All of these facilities are available from the menu. By default, dragging an application out of the window creates an application stub. This can be changed to linking, copying or moving by means of the options submenu. Double-clicking on an application causes it to run.

The recommeneded method of use is that you create stubs or links to simulate the disc layout you would have chosen if installing by hand. If you want to modify an application for any reason then take a local copy of it and modify that. Don't try to micro-manage where RiscPkg places individual applications — it really doesn’t matter, because stubs or links can make them appear to be anywhere.

Configuring RiscPkg

Introduction

RiscPkg is supplied with default configuration files which are used if no others are specified. These will suffice for many users, but they are only defaults and can be overridden if a different local policy is desired.

Currently there are two configuration files:

  • the Sources file, which controls where packages are obtained from; and
  • the Paths file, which controls where packages are placed when they are installed.

The Sources file

The file Choices:RiscPkg.Sources contains a list of sources from which package index files can be obtained. Each line consists of a source type (pkg for an index of binary packages) followed by a URL. For example:

pkg http://riscpkg.org.uk/dist/unstable

Comments are introduced by a hash character. Blank lines are ignored. If more than one version of a package is found, the one with the highest version number is used. If more than one copy of the same package version is found, the source used is the first one listed.

If you don‘t provide a Sources file then the default is used instead. At present this fetches the unstable distribution from http://www.riscpkg.org/. (The stable distribution would be preferable for new users, but currently there is no stable distribution.)

If you do provide a Sources file then it completely replaces the default. To add to (rather than replace) the default sources you must re-list them explicitly.

The Paths file

The file Choices:RiscPkg.Paths contains a list of mappings from logical to physical pathnames. Logical pathnames are those used within the package file. For example, System.310.Modules.CLib refers to a location within the active !System folder without making any assumption as to the physical location of that folder.

Each line of the paths file consists of a logical pathname, followed by followed by an equals-sign, followed by a physical pathname. These components must be separated by whitespace. For example:

RiscPkg = <Packages$Dir>.Info.@
Apps = <Boot$Dir>.^.Apps
System = <System$Dir>
SysVars = <Packages$Dir>.SysVars

Comments are introduced by a hash character. Blank lines are ignored. Each logical and physical pathname acts as the root of a sub-tree and applies to any file within that sub-tree. If two or more logical pathnames match then the longest one is used. An at-sign is converted into the name of the package to which the file belongs, so the file RiscPkg.Control from the package Foo would become <Packages$Dir>.Info.Foo.Control.

In principle you are free to choose any mappings you wish and the package manager will act accordingly. In practice, the scope for doing so is fairly limited if you want installed packages to work afterwards. The best way to ensure correct behaviour is to refer to locations indirectly using system variables. For example, the mapping given above for System will work even if the system folder moves.

One path that is freely changable is Apps. This is where applications are installed, and there is no requirement for them to be placed in any particular location. However the location you choose should not be used for any other purpose: if you want to mix applications and user data in the same directory then create symbolic links to the applications.

If you supply a Paths file then it takes precedence over the default but does not necessarily replace it. Any paths that you do not specify will continue to use the default mapping.

Be aware that if you change the Paths file while there are packages installed, you must make corresponding changes to the physical filesystem (otherwise RiscPkg will not be able to perform upgrades correctly).

Support

The RiscPkg home page may be found at:

http://www.riscpkg.org/

and the application itself downloaded from:

http://www.riscpkg.org/RiscPkg.zip

There is also a mailing list. To subscribe, send an empty message to:

riscpkg-request@sagitta.demon.co.uk

with a subject of “subscribe”.

Acknowledgements

RiscPkg was inspired by apt and dpkg, the programs at the core of the Debian GNU/Linux package management system. All of the code is new, but many of the concepts and file formats have been copied or adapted.

RiscPkg uses zlib for data compression and libcurl for downloading. It is compiled using the RISC OS port of gcc.