Apply new glyph-image conventions for `ks-x1001'.
[chise/xemacs-chise.git] / README.packages
1                                                             -*- Outline -*-
2 This file is in Outline mode.  It is best viewed under XEmacs.
3
4 Press C-c C-o (Ctrl+c Ctrl+o) now to see a list of headings.
5   To expand a heading:  Put the cursor on the heading and press C-c C-s
6 To collapse a heading:  Press C-c C-d
7
8 For general XEmacs navigation tips: Press C-h t
9
10 The XEmacs Packages Quick Start Guide
11 -------------------------------------
12
13 This text is intended to help you get started installing a new XEmacs and
14 its packages.  For more details see the 'Startup Paths' and 'Packages'
15 sections of the XEmacs info manual.
16
17 * Real Real Quickstart FAQ
18 --------------------------
19
20 Q. Do I need to have the packages to compile XEmacs?
21
22 A. Theoretically, no -- XEmacs will build and install just fine without any
23    packages installed.  However, only the most basic editing functions will
24    be available with no packages installed, so installing packages is an
25    essential part of making your installed XEmacs _useful_.
26
27 Q. I really liked the old way that packages were bundled and do not
28    want to mess with packages at all.
29
30 A. You can grab all the packages at once like you used to with old
31    XEmacs versions, skip to the 'Sumo Tarball' section below.
32
33 Q. How do I tell XEmacs where to find the packages?
34
35 A. Normally, you put the packages under $prefix/lib/packages, where
36    $prefix is specified using the `--prefix' parameter to `configure'.
37    (See `Package hierarchies' below).  However, if you have the packages
38    somewhere else (e.g. you're a developer and are compiling the packages
39    yourself, and want your own private copy of everything), use the
40    `--package-path' parameter, something like this:
41
42    configure --package-path="~/.xemacs::/src/xemacs/site-packages:/src/xemacs/xemacs-packages:/src/xemacs/mule-packages" ...
43
44 Q. After installing, I want XEmacs to do `foo', but when I invoke it
45    (or click the toolbar button or select the menu item), nothing (or
46    an error) happens, and it used to work.
47
48 A. See the first FAQ; you may be missing a package that is essential to
49    you.  You can either track it down and install it, or install the
50    `Sumo Tarball' (see the second FAQ).
51
52 * A note of caution
53 -------------------
54
55 The XEmacs package system is still in its infancy. Please expect a few
56 minor hurdles on the way. Also neither the interface nor the structure is
57 set in stone. The XEmacs maintainers reserve the right to sacrifice
58 backwards compatibility as quirks are worked out over the coming
59 releases.
60
61 * Some package theory
62 ---------------------
63
64 In order to reduce the size and increase the maintainability of XEmacs,
65 the majority of the Elisp packages that came with previous releases
66 have been unbundled. They have been replaced by the package system.
67 Each elisp add-on (or groups of them when they are small) now comes
68 in its own tarball that contains a small search hierarchy.
69
70 You select just the ones you need. Install them by untarring them into
71 the right place. On startup XEmacs will find them, set up the load
72 path correctly, install autoloads, etc, etc.
73
74 * Package hierarchies
75 ---------------------
76
77 On Startup XEmacs looks for packages in so-called package hierarchies.
78 Normally, there are three system wide hierarchies, like this:
79
80 $prefix/lib/xemacs/xemacs-packages/
81      Normal packages go here.
82
83 $prefix/lib/xemacs/mule-packages/
84      Mule packages go here and are only searched by MULE-enabled XEmacsen.
85
86 $prefix/lib/xemacs/site-packages/
87      Local and 3rd party packages go here.
88
89 This is what you get when you untar the SUMO tarballs under
90 $prefix/lib/xemacs.
91
92 $prefix is specified using the `--prefix' parameter to `configure', and
93 defaults to `usr/local'.
94
95 If your packages are located in the above directories, XEmacs will
96 automatically find them at startup; however, if you have your packages
97 somewhere else (e.g. you're a developer and are compiling the packages
98 yourself, and want your own private copy of everything), you can tell
99 XEmacs specifically where to look for the packages by using the
100 `--package-path' parameter to the 'configure' script.  Normally, it looks
101 like this:
102
103 configure --package-path="~/.xemacs::/src/xemacs/site-packages:/src/xemacs/xemacs-packages:/src/xemacs/mule-packages" ...
104
105 See `configure.usage' for more info about the format of this parameter.
106
107 * Where to get the packages
108 ---------------------------
109
110 Packages are available from ftp://ftp.xemacs.org/pub/xemacs/packages
111 and its mirrors.
112
113 * How to install the packages
114 -----------------------------
115 There are a few different ways to install packages:
116
117         1. Automatically, using the package tools from XEmacs.
118         2. Manually, using individual package tarballs.
119         3. Manually, all at once, using the 'Sumo Tarball'.
120
121 ** Automatically, using the package tools from XEmacs
122 -----------------------------------------------------
123
124 XEmacs comes with some tools to make the periodic updating and
125 installing easier. It will notice if new packages or versions are
126 available and will fetch them from the FTP site.
127
128 Unfortunately this requires that a few packages are already in place.
129 You will have to install them by hand as above or use a SUMO tarball.
130 This requirement will hopefully go away in the future. The packages
131 you need are:
132
133    efs          - To fetch the files from the FTP site or mirrors.
134    xemacs-base  - Needed by efs.
135
136 and optionally:
137
138    mailcrypt    - For PGP verification of the package-index file.
139
140 After installing these by hand, fire up XEmacs and follow these
141 steps.
142
143   (1) Choose a download site.
144       - via menu: Tools -> Packages -> Set Download Site 
145       - via keyb: M-x customize-variable RET package-get-remote RET
146         (put in the details of remote host and directory)
147
148       If the package tarballs _AND_ the package-index file are in a
149       local directory, you can: M-x pui-set-local-package-get-directory RET
150
151   (2) Obtain a list of packages and display the list in a buffer named
152       "*Packages*".
153       - menu: Tools -> Packages -> List & Install
154       - keyb: M-x pui-list-packages RET
155
156       XEmacs will now connect to the remote site and download the
157       latest package-index file.
158
159       The resulting buffer, "*Packages*" has brief instructions at the
160       end of the buffer.
161
162   (3) Choose the packages you wish to install.
163       - mouse: Click button 2 on the package name.
164       -  keyb: RET on the package name
165
166   (4) Make sure you have everything you need.
167       - menu: Packages -> Add Required
168       - keyb: r
169
170       XEmacs will now search for packages that are required by the
171       ones that you have chosen to install and offer to select
172       those packages also.
173
174       For novices and gurus alike, this step can save your bacon.
175       It's easy to forget to install a critical package.
176
177   (5) Download and install the packages.
178       - menu: Packages -> Install/Remove Selected
179       - keyb: x
180
181 ** Manually, using individual package tarballs
182 ----------------------------------------------
183
184 Fetch the packages from the FTP site, CD-ROM whatever. The filenames
185 have the form name-<version>-pkg.tar.gz and are gzipped tar files. For
186 a fresh install it is sufficient to untar the file at the top of the
187 package hierarchy. 
188
189 Note: If you are upgrading packages already installed, it's best to
190 remove the old package first (see 'Upgrading/Removing Packages' below).
191
192 For example if we are installing the 'xemacs-base'
193 package (version 1.48):
194
195    mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet
196    cd $prefix/lib/xemacs/xemacs-packages RET
197    gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
198
199 Or if you have GNU tar, the last step can be:
200
201    tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
202
203 For MULE related packages, it is best to untar into the mule-packages
204 hierarchy, i.e. for the mule-base package, version 1.37:
205
206    mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet
207    cd $prefix/lib/xemacs/mule-packages RET
208    gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
209
210 Or if you have GNU tar, the last step can be:
211
212    tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
213
214
215 ** Manually, all at once, using the 'Sumo Tarball'
216 --------------------------------------------------
217
218 Those with little time, cheap connections and plenty of disk space can
219 install all the packages at once using the sumo tarballs.
220 Download the file:
221
222    xemacs-sumo.tar.gz
223
224 For an XEmacs compiled with Mule you also need:
225
226    xemacs-mule-sumo.tar.gz
227
228 N.B. They are called 'Sumo Tarballs' for good reason. They are
229 currently about 19MB and 4.5MB (gzipped) respectively.
230
231 Install them by:
232
233    cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET
234
235 Or, if you have GNU tar:
236
237    cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET
238
239 As the Sumo tarballs are not regenerated as often as the individual
240 packages, it is recommended that you use the automatic package tools
241 afterwards to pick up any recent updates.
242
243 * After Installation
244 --------------------
245
246 Updated packages can only be used by XEmacs after a restart.
247
248 * Which Packages to install?
249 ----------------------------
250
251 This is difficult to say. When in doubt install a package. If you
252 administrate a big site it might be a good idea to just install
253 everything. A good minimal set of packages for XEmacs-latin1 would be
254
255 xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
256 edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes,
257 text-modes, time, mailcrypt
258
259 If you are using the XEmacs package tools, don't forget to do:
260
261         Packages -> Add Required
262
263 To make sure you have everything that the packages you have chosen to
264 install need.
265
266 See also '.../etc/PACKAGES' for further descriptions of the individual
267 packages.
268
269 * Upgrading/Removing Packages
270 -----------------------------
271
272 As the exact files and their locations contained in a package may
273 change it is recommended to remove a package first before installing a
274 new version. In order to facilitate removal each package contains an
275 pgkinfo/MANIFEST.pkgname file which list all the files belong to the
276 package. M-x package-admin-delete-binary-package RET can be used to
277 remove a package using this file.
278
279 Note that the interactive package tools included with XEmacs already do
280 this for you.
281
282 * User Package directories
283 --------------------------
284
285 In addition to the system wide packages, each user can have his own
286 packages installed under "~/.xemacs/". If you want to install packages
287 there using the interactive tools, you need to set
288 'package-get-install-to-user-init-directory' to 't'
289
290 * Site lisp/Site start
291 ----------------------
292
293 The site-packages hierarchy replaces the old 'site-lisp' directory.
294 XEmacs no longer looks into a 'site-lisp' directly by default.
295 A good place to put 'site-start.el' would be in
296 $prefix/lib/xemacs/site-packages/lisp/
297
298 * Finding the right packages
299 ----------------------------
300
301 If you want to find out which package contains the functionality you
302 are looking for, use M-x package-get-package-provider, and give it a
303 symbol that is likely to be in that package.  
304
305 For example, if some code you want to use has a (require 'thingatpt)
306 in it:
307
308         M-x package-get-package-provider RET thingatpt RET
309
310 which will return something like: (fsf-compat "1.08").