Debug message fix
[sxemacs] / README.packages
1                                                             -*- Outline -*-
2 This file is in Outline mode.  It is best viewed under SXEmacs.
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 SXEmacs navigation tips: Press C-h t
9
10 The SXEmacs Packages Quick Start Guide
11 -------------------------------------
12
13 This text is intended to help you get started installing a new SXEmacs and
14 its packages.  For more details see the 'Startup Paths' and 'Packages'
15 sections of the SXEmacs info manual.
16
17 * Real Real Quickstart FAQ
18 --------------------------
19
20 Q. Do I need to have the packages to compile SXEmacs?
21
22 A. Theoretically, no -- SXEmacs 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 SXEmacs _useful_.
26
27 Q. How do I tell SXEmacs where to find the packages?
28
29 A. Normally, you put the packages under $prefix/share/sxemacs/*-packages, where
30    $prefix is specified using the `--prefix' parameter to `configure'.
31    (See `Package hierarchies' below).  However, if you have the packages
32    somewhere else (e.g. you're a developer and are compiling the packages
33    yourself, and want your own private copy of everything), use the
34    `--with-package-path' parameter, something like this:
35
36    configure --with-package-path="~/.sxemacs::/src/sxemacs/site-packages:/src/sxemacs/xemacs-packages:/src/sxemacs/mule-packages" ...
37
38 Q. After installing, I want SXEmacs to do `foo', but when I invoke it
39    (or click the toolbar button or select the menu item), nothing (or
40    an error) happens, and it used to work.
41
42 A. See the first FAQ; you may be missing a package that is essential to
43    you.  You can either track it down and install it, or install the
44    `Sumo Tarball' (see the second FAQ).
45
46 * A note of caution
47 -------------------
48
49 The SXEmacs package system is still in its infancy. Please expect a few
50 minor hurdles on the way. Also neither the interface nor the structure is
51 set in stone. The SXEmacs maintainers reserve the right to sacrifice
52 backwards compatibility as quirks are worked out over the coming
53 releases.
54
55 * Some package theory
56 ---------------------
57
58 In order to reduce the size and increase the maintainability of
59 SXEmacs, we don't bundle or ship any elisp packages, other than a
60 "bare bones" assortment of elisp that gives SXEmacs fairly basic
61 functionality. 
62
63 The SXEmacs team doesn't host any package repositories, and doesn't
64 maintain any packages.  But there's no need for concern, SXEmacs can
65 use the XEmacs packages without problem.
66
67 * Package hierarchies
68 ---------------------
69
70 On Startup SXEmacs looks for packages in so-called package hierarchies.
71 Normally, there are up to four system wide hierarchies, like this:
72
73 $prefix/share/sxemacs/xemacs-packages/
74      Normal packages go here.
75
76 $prefix/share/sxemacs/mule-packages/
77      Mule packages go here and are only searched by MULE-enabled SXEmacsen.
78
79 $prefix/share/sxemacs/site-packages/
80      Local and 3rd party packages go here.
81
82 $prefix/share/sxemacs/sxemacs-packages/
83      SXEmacs-specific go here (none exist yet)
84
85 This is what you get when you untar the SUMO tarballs under
86 $prefix/share/sxemacs.
87
88 $prefix is specified using the `--prefix' parameter to `configure', and
89 defaults to `/usr/local'.
90
91 If your packages are located in the above directories, SXEmacs will
92 automatically find them at startup; however, if you have your packages
93 somewhere else (e.g. you're a developer and are compiling the packages
94 yourself, and want your own private copy of everything), you can tell
95 SXEmacs specifically where to look for the packages by using the
96 `--with-package-path' parameter to the 'configure' script.  Normally, it looks
97 like this:
98
99 configure --with-package-path="~/.xemacs::/src/xemacs/site-packages:/src/xemacs/xemacs-packages:/src/xemacs/mule-packages" ...
100
101 See `configure --help' for more info about the format of this parameter.
102
103 Note: Most people will _not_ need to set --with-package-path
104
105 * Where to get the packages
106 ---------------------------
107
108 Packages are available from ftp://ftp.xemacs.org/pub/xemacs/packages
109 and its mirrors.
110
111 * Bootstrapping the package tools
112 ---------------------------------
113 You only need to read this section if you do not have _any_ XEmacs
114 packages installed.
115
116 Unlike XEmacs, SXEmacs' package tools are usable without having to
117 manually install any packages to "bootstrap" it.  There are two
118 requirements for this to work...
119
120         1. Your SXEmacs includes support for FFI. Configure
121            automatically detects it if you have it.  And this quick
122            test will return `t' if you do...
123
124                 M-: (featurep 'ffi) RET
125
126         2. libcurl.so installed.  Note that you do not need this library
127            to build SXEmacs.
128
129 All you have to do now is...
130
131         1. Set a download site...
132
133                 Menu:  Tools -> Packages -> Set Download Site ->
134
135         2. `M-x pui-bootstrap RET'
136
137 That's it!  What will happen is that SXEmacs will download and install
138 the latest package-index file.  Then it will download and install the
139 latest versions of the EFS and xemacs-base packages.  Finally, SXEmacs
140 will ask you if you want to install more packages.  At this point,
141 SXEmacs reverts back to "normal" PUI behaviour (using EFS to download
142 the packages).
143
144
145 * How to install the packages
146 -----------------------------
147 There are a few different ways to install packages:
148
149         1. Automatically, using the package tools from SXEmacs.
150         2. Manually, using individual package tarballs.
151         3. Manually, all at once, using the 'Sumo Tarball'.
152         4. The lazy (smart) XEmacs users' way.
153
154 ** Automatically, using the package tools from SXEmacs
155 -----------------------------------------------------
156
157 SXEmacs 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   (1) Choose a download site.
162       - via menu: Tools -> Packages -> Set Download Site 
163       - via keyb: M-x customize-variable RET package-get-remote RET
164         (put in the details of remote host and directory)
165
166       If the package tarballs _AND_ the package-index file are in a
167       local directory, you can: M-x pui-set-local-package-get-directory RET
168
169   (2) Obtain a list of packages and display the list in a buffer named
170       "*Packages*".
171       - menu: Tools -> Packages -> List & Install
172       - keyb: M-x pui-list-packages RET
173
174       SXEmacs will now connect to the remote site and download the
175       latest package-index file.
176
177       The resulting buffer, "*Packages*" has brief instructions at the
178       end of the buffer.
179
180   (3) Choose the packages you wish to install.
181       - mouse: Click button 2 on the package name.
182       -  keyb: RET on the package name
183
184   (4) Make sure you have everything you need.
185       - menu: Packages -> Add Required
186       - keyb: r
187
188       SXEmacs will now search for packages that are required by the
189       ones that you have chosen to install and offer to select
190       those packages also.
191
192       For novices and gurus alike, this step can save your bacon.
193       It's easy to forget to install a critical package.
194
195   (5) Download and install the packages.
196       - menu: Packages -> Install/Remove Selected
197       - keyb: x
198
199 ** Manually, using individual package tarballs
200 ----------------------------------------------
201
202 Fetch the packages from the FTP site, CD-ROM whatever. The filenames
203 have the form name-<version>-pkg.tar.gz and are gzipped tar files. For
204 a fresh install it is sufficient to untar the file at the top of the
205 package hierarchy. 
206
207 Note: If you are upgrading packages already installed, it's best to
208 remove the old package first (see 'Upgrading/Removing Packages' below).
209
210 For example if we are installing the 'xemacs-base'
211 package (version 1.48):
212
213    mkdir $prefix/share/sxemacs/xemacs-packages RET # if it does not exist yet
214    cd $prefix/share/sxemacs/xemacs-packages RET
215    gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
216
217 Or if you have GNU tar, the last step can be:
218
219    tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
220
221 For MULE related packages, it is best to untar into the mule-packages
222 hierarchy, i.e. for the mule-base package, version 1.37:
223
224    mkdir $prefix/share/sxemacs/mule-packages RET # if it does not exist yet
225    cd $prefix/share/sxemacs/mule-packages RET
226    gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
227
228 Or if you have GNU tar, the last step can be:
229
230    tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
231
232
233 ** Manually, all at once, using the 'Sumo Tarball'
234 --------------------------------------------------
235
236 Those with little time, cheap connections and plenty of disk space can
237 install all the packages at once using the sumo tarballs.
238 Download the file:
239
240    xemacs-sumo.tar.gz
241
242 For an SXEmacs compiled with Mule you also may want:
243
244    xemacs-mule-sumo.tar.gz
245
246 N.B. They are called 'Sumo Tarballs' for good reason. They are
247 currently about 19MB and 4.5MB (gzipped) respectively.
248
249 Install them by:
250
251    cd $prefix/share/sxemacs ; gunzip -c <tarballname> | tar xvf - RET
252
253 Or, if you have GNU tar:
254
255    cd $prefix/share/sxemacs ; tar zxvf /path/to/<tarballname> RET
256
257 As the Sumo tarballs are not regenerated as often as the individual
258 packages, it is recommended that you use the automatic package tools
259 afterwards to pick up any recent updates.
260
261 ** The lazy (smart) XEmacs users' way
262 -------------------------------------
263
264 If you are a XEmacs user and already have all the packages installed
265 in the XEmacs locations, here is a quick and easy way to get SXEmacs
266 to see and use them too...
267
268   ln -svf /usr/local/lib/xemacs /usr/local/share/sxemacs RET
269
270 You can do the same with your ~/.xemacs directory too...
271
272   ln -svf ~/.xemacs ~/.sxemacs RET
273
274
275 * After Installation
276 --------------------
277
278 Updated packages can only be used by SXEmacs after a restart.
279
280 * Which Packages to install?
281 ----------------------------
282
283 This is difficult to say. When in doubt install a package. If you
284 administrate a big site it might be a good idea to just install
285 everything. A good minimal set of packages for SXEmacs-latin1 would be
286
287 xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
288 edit-utils, mail-lib, net-utils, os-utils, prog-modes, text-modes,
289 time 
290
291 If you are using the SXEmacs package tools, don't forget to do:
292
293         Packages -> Add Required
294
295 To make sure you have everything that the packages you have chosen to
296 install need.
297
298 See also '.../etc/PACKAGES' for further descriptions of the individual
299 packages.
300
301 * Upgrading/Removing Packages
302 -----------------------------
303
304 As the exact files and their locations contained in a package may
305 change it is recommended to remove a package first before installing a
306 new version. In order to facilitate removal each package contains an
307 pgkinfo/MANIFEST.pkgname file which list all the files belong to the
308 package. M-x package-admin-delete-binary-package RET can be used to
309 remove a package using this file.
310
311 Note that the interactive package tools included with SXEmacs already do
312 this for you.
313
314 * User Package directories
315 --------------------------
316
317 In addition to the system wide packages, each user can have their own
318 packages installed under ${HOME}.  The default location is:
319 ${XDG_DATA_HOME}/sxemacs, which is normally ~/.local/share/sxemacs,
320 and is what SXEmacs will use if ${XDG_DATA_HOME} is not set.
321
322 Alternatively, these packages can be installed under ~/.sxemacs if
323 that is where you have set your `user-init-diretory' to.
324
325 If you want to install packages into your ${HOME} using the interactive
326 tools, you need to set 'package-get-install-to-user-directory' to 't'
327
328 * Site lisp/Site start
329 ----------------------
330
331 The site-packages hierarchy replaces the old 'site-lisp' directory.
332 SXEmacs no longer looks into a 'site-lisp' directly by default.
333 A good place to put 'site-start.el' would be in
334 $prefix/share/sxemacs/site-packages/lisp/
335
336 * Finding the right packages
337 ----------------------------
338
339 If you want to find out which package contains the functionality you
340 are looking for, use M-x package-get-package-provider, and give it a
341 symbol that is likely to be in that package.  
342
343 For example, if some code you want to use has a (require 'thingatpt)
344 in it:
345
346         M-x package-get-package-provider RET thingatpt RET
347
348 which will return something like: (fsf-compat "1.08").