RiscPkg User Guide
Version 0.3.1 (25 Feb 2005) IntroductionRiscPkg 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 WarningPackage 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 WarrantyRiscPkg 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 - 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
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. - Run
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
install RiscPkg . - Select RiscPkg again, then click on
Selection => Apps ...
from the menu. This should open a window containing an icon labelled
!RiscPkg . - 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
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 IntroductionAt 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 WindowClicking 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 ListRiscPkg 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 PackagesTo 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 PackagesTo 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 PackagesTo 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 WindowFor 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 IntroductionRiscPkg 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 fileThe 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 fileThe 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). SupportThe 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”. AcknowledgementsRiscPkg 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 .
|