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
79 sudo mount -o loop /home/me/downloads/kubuntu-7.04-alternate-i386.iso /tmp/cdrom
80 user-setup file:///tmp/cdrom
81
82 An URI must be specified as the "mirror" location, not a normal filename.
83
84 Adding Package Repositories to the Package Manager
85 --------------------------------------------------
86
87 To get access to repositories of packages beyond those provided by the basic
88 distribution, edit the /etc/apt/sources.list file inside the system. The
89 user-path script can help you find the exact location of the file:
90
91 user-path /etc/apt/sources.list
92
93 Or with defaults in the current directory:
94
95 ./user-path /etc/apt/sources.list
96
97 And you can edit the file directly with a text editor (such as vi) as follows:
98
99 vi `user-path /etc/apt/sources.list`
100
101 Or with defaults in the current directory:
102
103 vi `./user-path /etc/apt/sources.list`
104
105 Installing Packages
106 -------------------
107
108 To install packages from other repositories, invoke the user-apt-get script
109 with the options expected by the regular apt-get program. For example:
110
111 user-apt-get --help
112 user-apt-get update
113
114 It may be necessary to install the gnupg package to enable package signature
115 verification:
116
117 user-apt-get install gnupg
118
119 Then, other packages can be installed. For example:
120
121 user-apt-get install python-cmdsyntax
122
123 Provided that the specified packages are known and their dependencies can be
124 met, they will be installed into the system.
125
126 Installing Single Packages
127 --------------------------
128
129 To install individual package files, invoke the user-dpkg-i script with the
130 name of the package file. For example:
131
132 user-dpkg-i /home/me/downloads/python-cmdsyntax_0.91-0ubuntu2_all.deb
133
134 This script will copy the file into the personal package management
135 environment and run dpkg with the -i (install) option.
136
137 Using Packages
138 --------------
139
140 Unlike most packages installed in the usual way by the root user, the installed
141 packages will not reside within a directory hierarchy rooted at / - the top of
142 the filesystem. Instead, they will reside in a location such as the following:
143
144 /home/me/.userinstall
145 /tmp/packages
146
147 (The precise location may be found by running the user-path script.)
148
149 Consequently, to make use of the installed software, it may be necessary to
150 edit your environment in a number of ways so that it may be located and
151 correctly loaded, initialised and executed.
152
153 Using Python Packages
154 ---------------------
155
156 Installed Python packages may be made available to Python by defining the
157 PYTHONPATH to include the directories usually searched by Python, but which
158 are actually located within the personal package management environment. For
159 example, with the Python 2.5 site-packages directory:
160
161 PYTHONPATH=`user-path /usr/lib/python2.5/site-packages/` python2.5
162
163 More complicated extension modules may require further adjustments to the
164 LD_LIBRARY_PATH and PYTHONPATH variables:
165
166 export LD_LIBRARY_PATH=`./user-path /usr/lib`
167 export PYTHONPATH=`./user-path /usr/lib/python2.5/site-packages/`
168 export PYTHONPATH=${PYTHONPATH}:`./user-path /var/lib/python-support/python2.5`