RiscPkg User Guide
Version 0.3.1 (25 Feb 2005)
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;
- 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
- Dependencies (such as modules and fonts) can be satisfied
- 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.
Package managers by their nature have the potential to do serious harm
to your filesystem. At this stage of its development, the risks posed
RiscPkg itself (as opposed to software you may choose to
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.
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.
- 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.
- Optionally, create the configuration files
The required format is described below. If you do not supply these files
then the defaults in
!RiscPkg.Resources will be used
RiscPkg by double-clicking in the application
directory. It will install an icon on the icon bar.
- 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.
- 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.
- 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.
- 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.
- 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.
- Click on
Commit from the menu. This will download and
- Select RiscPkg again, then click on
Selection => Apps ...
from the menu. This should open a window containing an icon labelled
- 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.
- Once you have confirmed that the stub copy of
exists and is functional, you can delete the temporary bootstrap copy
used up to this point.
By default, the ‘real’ copy of
installed in the directory
Apps.Admin on the disc containing
!Boot directory. It can be moved if necessary, but you
mustn’t do so without at least telling
RiscPkg where it
has moved to.
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
- 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
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
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.)
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.
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.)
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,
Commit from the menu.
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,
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
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.
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:
Sources file, which controls where packages are
obtained from; and
Paths file, which controls where packages are placed
when they are installed.
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:
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
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.
Choices:RiscPkg.Paths contains a list of mappings
from logical to physical pathnames. Logical pathnames are those used within
the package file. For example,
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
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
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
RiscPkg will not be able to perform
The RiscPkg home page may be found at:
and the application itself downloaded from:
There is also a mailing list. To subscribe, send an empty message to:
with a subject of “subscribe”.
RiscPkg was inspired by
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.
zlib for data compression and
libcurl for downloading. It is compiled using the
RISC OS port of