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