1 Introduction
2 ------------
3
4 The userinstall distribution consists of a number of scripts, together with a
5 short configuration file, which allows non-root users to set up and use their
6 own package and dependency management facilities and to download and install
7 Debian packages without having to obtain root privileges. The software within
8 installed packages may then be used, subject to certain constraints such as
9 program environments, library paths, and so on. In effect, userinstall
10 provides a personal package manager.
11
12 Contact, Copyright and Licence Information
13 ------------------------------------------
14
15 The current Web page for userinstall at the time of release is:
16
17 http://www.boddie.org.uk/paul/userinstall.html
18
19 Copyright and licence information can be found in the docs directory - see
20 docs/COPYING.txt and docs/gpl-3.0.txt for more information.
21
22 Thanks to Piotr Roszatycki, the maintainer of fakechroot, for helpfully fixing
23 system call coverage in that utility in order to support cross-distribution
24 bootstrapping.
25
26 Dependencies
27 ------------
28
29 fakeroot Tested with 1.5.10ubuntu2
30 fakechroot 2.8 or later required
31 debootstrap Tested with 0.3.3.2ubuntu3 on Ubuntu Hoary 5.04, 1.0.7~feisty1
32 on Ubuntu Hoary 7.04
33
34 New in userinstall 0.1.1 (Changes since userinstall 0.1)
35 --------------------------------------------------------
36
37 * Fixed an argument parsing error in the user-setup script.
38
39 Configuration
40 -------------
41
42 If the system defaults are not to be used, or if userinstall is not installed
43 as a system package, the userinstall-defaults file supplied with the
44 distribution may be edited to specify the nature and location of the personal
45 package manager. The following settings can be edited:
46
47 DISTNAME This should reflect the distribution being used and need only
48 be altered in special situations. Note that the setup process
49 may not work with different distributions due to library
50 incompatibilities.
51
52 PACKAGEROOT The location of the personal package manager in the
53 filesystem.
54
55 If a completely new userinstall-defaults file is created, it is essential that
56 the above variables be defined so that the scripts know where to create or to
57 find the personal package manager.
58
59 Creating a Personal Package Manager
60 -----------------------------------
61
62 In order to install packages as a non-root user, first invoke the user-setup
63 script; this will create and initialise a basic Debian system with a basic set
64 of packages installed. For example, with userinstall installed as a system
65 package, using the system defaults:
66
67 user-setup
68
69 Or with defaults in the current directory:
70
71 ./user-setup
72
73 It is possible to override the "template" for the system by specifying a
74 "mirror" location. This is useful if you have the CD or DVD image for the
75 distribution already mounted in the filesystem. For example:
76
77 user-setup file:///cdrom
78 user-setup file:///home/me/downloads/kubuntu-7.04-alternate-i386.iso
79
80 An URI must be specified as the "mirror" location, not a normal filename.
81
82 Adding Package Repositories to the Package Manager
83 --------------------------------------------------
84
85 To get access to repositories of packages beyond those provided by the basic
86 distribution, edit the /etc/apt/sources.list file inside the system. The
87 user-path script can help you find the exact location of the file:
88
89 user-path /etc/apt/sources.list
90
91 Or with defaults in the current directory:
92
93 ./user-path /etc/apt/sources.list
94
95 And you can edit the file directly with a text editor (such as vi) as follows:
96
97 vi `user-path /etc/apt/sources.list`
98
99 Or with defaults in the current directory:
100
101 vi `./user-path /etc/apt/sources.list`
102
103 Installing Packages
104 -------------------
105
106 To install packages from other repositories, invoke the user-apt-get script
107 with the options expected by the regular apt-get program. For example:
108
109 user-apt-get --help
110 user-apt-get update
111
112 It may be necessary to install the gnupg package to enable package signature
113 verification:
114
115 user-apt-get install gnupg
116
117 Then, other packages can be installed. For example:
118
119 user-apt-get install python-cmdsyntax
120
121 Provided that the specified packages are known and their dependencies can be
122 met, they will be installed into the system.
123
124 Installing Single Packages
125 --------------------------
126
127 To install individual package files, invoke the user-dpkg-i script with the
128 name of the package file. For example:
129
130 user-dpkg-i /home/me/downloads/python-cmdsyntax_0.91-0ubuntu2_all.deb
131
132 This script will copy the file into the personal package management
133 environment and run dpkg with the -i (install) option.
134
135 Using Packages
136 --------------
137
138 Unlike most packages installed in the usual way by the root user, the installed
139 packages will not reside within a directory hierarchy rooted at / - the top of
140 the filesystem. Instead, they will reside in a location such as the following:
141
142 /home/me/.userinstall
143 /tmp/packages
144
145 (The precise location may be found by running the user-path script.)
146
147 Consequently, to make use of the installed software, it may be necessary to
148 edit your environment in a number of ways so that it may be located and
149 correctly loaded, initialised and executed.
150
151 Using Python Packages
152 ---------------------
153
154 Installed Python packages may be made available to Python by defining the
155 PYTHONPATH to include the directories usually searched by Python, but which
156 are actually located within the personal package management environment. For
157 example, with the Python 2.5 site-packages directory:
158
159 PYTHONPATH=`user-path /usr/lib/python2.5/site-packages/` python2.5
160
161 More complicated extension modules may require further adjustments to the
162 LD_LIBRARY_PATH and PYTHONPATH variables:
163
164 export LD_LIBRARY_PATH=`./user-path /usr/lib`
165 export PYTHONPATH=`./user-path /usr/lib/python2.5/site-packages/`
166 export PYTHONPATH=${PYTHONPATH}:`./user-path /var/lib/python-support/python2.5`