Introduction
------------

The userinstall distribution consists of a number of scripts, together with a
short configuration file, which allows non-root users to set up and use their
own package and dependency management facilities and to download and install
Debian packages without having to obtain root privileges. The software within
installed packages may then be used, subject to certain constraints such as
program environments, library paths, and so on. In effect, userinstall
provides a personal package manager.

Contact, Copyright and Licence Information
------------------------------------------

The current Web page for userinstall at the time of release is:

http://www.boddie.org.uk/paul/userinstall.html

Copyright and licence information can be found in the docs directory - see
docs/COPYING.txt and docs/gpl-3.0.txt for more information.

Dependencies
------------

fakeroot        Tested with 1.5.10ubuntu2
fakechroot      Tested with 2.5-1.1
debootstrap     Tested with 0.3.3.2ubuntu3

Configuration
-------------

If the system defaults are not to be used, or if userinstall is not installed
as a system package, the userinstall-defaults file supplied with the
distribution may be edited to specify the nature and location of the personal
package manager. The following settings can be edited:

DISTNAME        This should reflect the distribution being used and need only
                be altered in special situations.
PACKAGEROOT     The location of the personal package manager in the
                filesystem.

If a completely new userinstall-defaults file is created, it is essential that
the above variables be defined so that the scripts know where to create or to
find the personal package manager.

Creating a Personal Package Manager
-----------------------------------

In order to install packages as a non-root user, first invoke the user-setup
script; this will create and initialise a basic Debian system with a basic set
of packages installed. For example, with userinstall installed as a system
package, using the system defaults:

user-setup

Or with defaults in the current directory:

./user-setup

It is possible to override the "template" for the system by specifying a
"mirror" location. This is useful if you have the CD or DVD image for the
distribution already mounted in the filesystem. For example:

user-setup file:///cdrom
user-setup file:///home/me/downloads/kubuntu-7.04-alternate-i386.iso

An URI must be specified as the "mirror" location, not a normal filename.

Adding Package Repositories to the Package Manager
--------------------------------------------------

To get access to repositories of packages beyond those provided by the basic
distribution, edit the /etc/apt/sources.list file inside the system. The
user-path script can help you find the exact location of the file:

user-path /etc/apt/sources.list

Or with defaults in the current directory:

./user-path /etc/apt/sources.list

And you can edit the file directly with a text editor (such as vi) as follows:

vi `user-path /etc/apt/sources.list`

Or with defaults in the current directory:

vi `./user-path /etc/apt/sources.list`

Installing Packages
-------------------

To install packages from other repositories, invoke the user-apt-get script
with the options expected by the regular apt-get program. For example:

user-apt-get --help
user-apt-get update
user-apt-get install python-cmdsyntax

Provided that the specified packages are known and their dependencies can be
met, they will be installed into the system.

Installing Single Packages
--------------------------

To install individual package files, invoke the user-dpkg-i script with the
name of the package file. For example:

user-dpkg-i /home/me/downloads/python-cmdsyntax_0.91-0ubuntu2_all.deb

This script will copy the file into the personal package management
environment and run dpkg with the -i (install) option.

Using Packages
--------------

Unlike most packages installed in the usual way by the root user, the installed
packages will not reside within a directory hierarchy rooted at / - the top of
the filesystem. Instead, they will reside in a location such as the following:

/home/me/.userinstall
/tmp/packages

(The precise location may be found by running the user-path script.)

Consequently, to make use of the installed software, it may be necessary to
edit your environment in a number of ways so that it may be located and
correctly loaded, initialised and executed.

Using Python Packages
---------------------

Installed Python packages may be made available to Python by defining the
PYTHONPATH to include the directories usually searched by Python, but which
are actually located within the personal package management environment. For
example, with the Python 2.5 site-packages directory:

PYTHONPATH=`user-path /usr/lib/python2.5/site-packages/` python2.5

More complicated extension modules may require further adjustments to the
LD_LIBRARY_PATH and PYTHONPATH variables:

export LD_LIBRARY_PATH=`./user-path /usr/lib`
export PYTHONPATH=`./user-path /usr/lib/python2.5/site-packages/`
export PYTHONPATH=${PYTHONPATH}:`./user-path /var/lib/python-support/python2.5`
