1 @c This is part of the XEmacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
3 @c See file xemacs.texi for copying conditions.
4 @node Packages, Basic, Startup Paths, Top
5 @comment node-name, next, previous, up
10 The XEmacs 21 distribution comes only with a very basic set of
11 built-in modes and packages. Most of the packages that were part of
12 the distribution of earlier versions of XEmacs are now available
13 separately. The installer as well as the user can choose which
14 packages to install; the actual installation process is easy.
15 This gives an installer the ability to tailor an XEmacs installation for
16 local needs with safe removal of unnecessary code.
19 * Package Terminology:: Understanding different kinds of packages.
20 * Using Packages:: How to install and use packages.
21 * Building Packages:: Building packages from sources.
22 * Available Packages:: A brief, out-of-date, directory of packaged LISP.
25 @node Package Terminology, Using Packages, , Packages
26 @comment node-name, next, previous, up
28 @subsection Package Flavors
30 There are two main flavors of packages.
33 @item Regular Packages
34 @cindex regular packages
35 A regular package is one in which multiple files are involved and one
36 may not in general safely remove any of them.
38 @item Single-File Packages
39 @cindex single-file packages
40 A single-file package is an aggregate collection of thematically
41 related but otherwise independent lisp files. These files are bundled
42 together for download convenience and individual files may be deleted at
43 will without any loss of functionality.
46 @subsection Package Distributions
48 XEmacs Lisp packages are distributed in two ways, depending on the
49 intended use. Binary Packages are for installers and end-users and may
50 be installed directly into an XEmacs package directory. Source Packages
51 are for developers and include all files necessary for rebuilding
52 bytecompiled lisp and creating tarballs for distribution.
54 @subsection Binary Packages
55 @cindex binary packages
56 Binary packages may be installed directly into an XEmacs package
59 @subsection Source Packages
60 @cindex source packages
61 Source packages contain all of the Package author's (where appropriate
62 in regular packages) source code plus all of the files necessary to
63 build distribution tarballs (Unix Tar format files, gzipped for space
66 @node Using Packages, Building Packages, Package Terminology, Packages
67 @comment node-name, next, previous, up
69 @subsection Getting Started
71 When you first download XEmacs 21, you will usually first grab the
72 @dfn{core distribution},
73 @cindex core distribution
75 @file{xemacs-21.0.tar.gz}. (Replace the @t{21.0} by the current version
76 number.) The core distribution contains the sources of XEmacs and a
77 minimal set of Emacs Lisp files, which are in the subdirectory named
78 @file{lisp}. This subdirectory used to contain all Emacs Lisp files
79 distributed with XEmacs. Now, to conserve disk space, most
80 non-essential packages were made optional.
82 @subsection Choosing the Packages You Need
84 The available packages can currently be found in the same ftp directory
85 where you grabbed the core distribution from, and are located in the
86 subdirectory @file{packages/binary-packages}. Package file names follow
87 the naming convention @file{<package-name>-<version>-pkg.tar.gz}.
89 If you have EFS @ref{(EFS)}, packages can be installed over the network.
90 Alternatively, if you have copies of the packages locally, you can
91 install packages from a local disk or CDROM.
93 The file @file{etc/PACKAGES} in the core distribution contains a list of
94 the packages available at the time of the XEmacs release. Packages are
95 also listed on the @code{Options} menu under:
98 Options->Customize->Emacs->Packages
101 However, don't select any of these menu picks unless you actually want
102 to install the given package (and have properly configured your system
105 You can also get a list of available packages, and whether or not they
106 are installed, using the visual package browser and installer. You can
107 access it via the menus:
110 Options->Manage Packages->List & Install
113 Or, you can get to it via the keyboard:
116 M-x pui-list-packages
119 Hint to system administrators of multi-user systems: it might be a good
120 idea to install all packages and not interfere with the wishes of your
123 If you can't find which package provides the feature you require, try
124 using the @code{package-get-package-provider} function. Eg., if you know
125 that you need @code{thingatpt}, type:
128 M-x package-get-package-provider RET thingatpt
131 which will return something like (fsf-compat "1.06"). You can the use
132 one of the methods above for installing the package you want.
134 @subsection XEmacs and Installing Packages
136 Normally, packages are installed over the network, using EFS
137 @ref{(EFS)}. However, you may not have network access, or you may
138 already have some or all of the packages on a local disk, such as a
139 CDROM. If you want to install from a local disk, you must first tell
140 XEmacs where to find the package binaries. This is done by adding a line
141 like the following to your init file:
144 (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
150 Here, you'd change @file{/my/path/to/package/binaries} to be the path
151 to your local package binaries. Next, restart XEmacs, and you're ready
152 to go (advanced users can just re-evaluate the sexp).
154 If you are installing from a temporary, one-time directory, you can also
155 add these directory names to @code{package-get-remote} using:
158 M-x pui-add-install-directory
161 Note, however, that any directories added using this function are not
162 saved; this information will be lost when you quit XEmacs.
164 If you're going to install over the network, you only have to insure
165 that EFS @ref{(EFS)} works, and that it can get outside a firewall, if
166 you happen to be behind one. You shouldn't have to do anything else;
167 XEmacs already knows where to go. However you can add your own mirrors
168 to this list. See @code{package-get-remote}.
170 The easiest way to install a package is to use the visual package
171 browser and installer, using the menu pick:
174 Options->Manage Packages->List & Install
178 Options->Manage Packages->Using Custom->Select-> ...
181 You can also access it using the keyboard:
184 M-x pui-list-packages
187 The visual package browser will then display a list of all packages.
188 Help information will be displayed at the very bottom of the buffer; you
189 may have to scroll down to see it. You can also press @kbd{?} to get
190 the same help. From this buffer, you can tell the package status by the
191 character in the first column:
195 The package has not been installed.
197 The package has been installed, but a newer version is available. The
198 current version is out-of-date.
200 The package has been marked for installation/update.
203 If there is no character in the first column, the package has been
204 installed and is up-to-date.
206 From here, you can select or unselect packages for installation using
207 the @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from
209 Once you've finished selecting the packages, you can
210 press the @kbd{x} key (or use the menu) to actually install the
211 packages. Note that you will have to restart XEmacs for XEmacs to
212 recognize any new packages.
221 Toggle between selecting and unselecting a package for installation.
223 Install selected packages.
225 View, in the minibuffer, additional information about the package, such
226 as the package date (not the build date) and the package author. Moving
227 the mouse over a package name will also do the same thing.
229 Toggle between verbose and non-verbose package display.
231 Refresh the package display.
233 Kill the package buffer.
236 Moving the mouse over a package will also cause additional information
237 about the package to be displayed in the minibuffer.
239 @subsection Other package installation interfaces
241 For an alternative package interface, you can select packages from the
242 customize menus, under:
245 Options->Customize->Emacs->Packages-> ...
249 Options->Manage Packages->Using Custom->Select-> ...
252 Set their state to on, and then do:
255 Options->Manage Packages->Using Custom->Update Packages
258 This will automatically retrieve the packages you have selected from the
259 XEmacs ftp site or your local disk, and install them into
260 XEmacs. Additionally it will update any packages you already have
261 installed to the newest version. Note that if a package is newly
262 installed you will have to restart XEmacs for the change to take effect.
264 You can also install packages using a semi-manual interface:
267 M-x package-get-all <return>
270 Enter the name of the package (e.g., @code{prog-modes}), and XEmacs
271 will search for the latest version (as listed in the lisp file
272 @file{lisp/package-get-base.el}), and install it and any packages that
275 @subsection Manual Binary Package Installation
277 Pre-compiled, binary packages can be installed in either a system
278 package directory (this is determined when XEmacs is compiled), or in
280 subdirectories of your @file{$HOME} directory:
283 ~/.xemacs/mule-packages
284 ~/.xemacs/xemacs-packages
287 Packages in the former directory will only be found by a Mule-enabled
290 XEmacs does not have to be running to install binary packages, although
291 XEmacs will not know about any newly-installed packages until you
292 restart XEmacs. Note, however, that installing a newer version of a
293 package while XEmacs is running could cause strange errors in XEmacs;
294 it's best to exit XEmacs before upgrading an existing package.
296 To install binary packages manually:
300 Download the package(s) that you want to install. Each binary package
301 will typically be a gzip'd tarball.
304 Decide where to install the packages: in the system package
305 directory, or in @file{~/.xemacs/mule-packages} or
306 @file{~/.xemacs/xemacs-packages}, respectively. If you want to install
307 the packages in the system package directory, make sure you can write
308 into that directory. If you want to install in your @file{$HOME}
309 directory, create the directory, @file{~/.xemacs/mule-packages} or
310 @file{~/.xemacs/xemacs-packages}, respectively.
313 Next, @code{cd} to the directory under which you want to install the
317 From this directory, uncompress and extract each of the gzip'd tarballs
318 that you downloaded in step 1. Unix and Cygnus cygwin users will
319 typically do this using the commands:
322 gunzip < package.tar.gz | tar xvf -
325 Above, replace @file{package.tar.gz} with the filename of the
326 package that you downloaded in step 1.
328 Of course, if you use GNU @code{tar}, you could also use:
331 tar xvzf package.tar.gz
334 @comment What about native MS Windows users???
337 That's it. Quit and restart XEmacs to get it to recognize any new or
342 @node Building Packages, Available Packages, Using Packages, Packages
343 @comment node-name, next, previous, up
345 Source packages are available from the @file{packages/source-packages}
346 subdirectory of your favorite XEmacs distribution site. Alternatively,
347 they are available via CVS from @file{cvs.xemacs.org}. Look at
348 @file{http://cvs.xemacs.org} for instructions.
350 @subsection Prerequisites for Building Source Packages
352 You must have GNU @code{cp}, GNU @code{install} (or a BSD compatible
353 @code{install} program) GNU @code{make} (3.75 or later preferred),
354 @code{makeinfo} (1.68 from @code{texinfo-3.11} or later required), GNU
355 @code{tar} and XEmacs 21.0. The source packages will untar into a
356 correct directory structure. At the top level you must have
357 @file{XEmacs.rules} and @file{package-compile.el}. These files are
358 available from the XEmacs FTP site from the same place you obtained your
359 source package distributions.
361 @subsection What You Can Do With Source Packages
363 NB: A global build operation doesn't exist yet as of 13 January 1998.
365 Source packages are most useful for creating XEmacs package tarballs
366 for installation into your own XEmacs installations or for
367 distributing to others.
369 Supported operations from @file{make} are:
373 Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.
376 Remove XEmacs backups as well as the files deleted by @code{make clean}.
379 Bytecompile all files, build and bytecompile byproduct files like
380 @file{auto-autoloads.el} and @file{custom-load.el}. Create info version
381 of TeXinfo documentation if present.
384 Usually aliased to @code{make srckit-std}. This does a @code{make
385 distclean} and creates a package source tarball in the staging
386 directory. This is generally only of use for package maintainers.
389 May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
390 @code{binkit-sourcedata}, or
391 @code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is
392 nothing to install in a data directory or info directory.
393 @code{sourceinfo} indicates that source and info files are to be
394 installed. @code{sourcedata} indicates that source and etc (data) files
395 are to be installed. @code{sourcedatainfo} indicates source, etc
396 (data), and info files are to be installed. A few packages have needs
397 beyond the basic templates so this is not yet complete.
400 Runs the rules @code{srckit} followed by @code{binkit}. This is
401 primarily of use by XEmacs maintainers producing files for distribution.
405 @node Available Packages, , Building Packages, Packages
406 @comment node-name, next, previous, up
408 This section is surely out-of-date. If you're sure that XEmacs is
409 able to do something, but your installed XEmacs won't do it for you,
410 it's probably in a package. If you can't find it in this section,
411 that's a bug---please report it. It is very hard to keep this section
412 up-to-date; your reports, comments, and questions will help a lot.
414 This data is up-to-date as of 10 February 1999. (Ouch! I told you!)
416 @subsection Library Packages (libs)
418 These packages are required to build and support most of the rest of
419 XEmacs. By design, xemacs-base is a `regular' package. Use restraint
420 when adding new files there as it is required by almost everything.
424 Support for Sparcworks.
427 A Portable Emacs Library. Used by XEmacs MIME support.
433 The DIRectory EDitor is for manipulating, and running commands on
434 files in a directory.
437 Treat files on remote systems the same as local files.
440 Fundamental lisp files for providing email support.
443 Support for building with Tooltalk.
446 Fundamental XEmacs support. Install this unless you wish a totally
450 XEmacs Lisp developer support. This package contains utilities for
451 supporting Lisp development. It is a single-file package so it may be
455 @subsection Communications Packages (comm)
457 These packages provide support for various communications, primarily
462 Footnoting in mail message editing modes.
468 The Gnus Newsreader and Mailreader.
471 Support for messaging encryption with PGP.
474 Front end support for MH.
477 Miscellaneous Networking Utilities. This is a single-file package and
478 files may be deleted at will.
481 Emacs implementation of the ph client to CCSO/qi directory servers.
484 An obsolete Emacs mailer. If you do not already use it don't start.
487 An Emacs citation tool. Useful with all Emacs Mailers and Newsreaders.
499 @subsection Games and Amusements (games)
503 Spook and Yow (Zippy quotes).
506 Tetris, Sokoban, and Snake.
512 Other amusements and diversions.
515 @subsection Mule Support (mule)
519 Wnn (4.2 and 6) support. SJ3 support. Must be installed prior to
523 Quail. Used for everything other than English and Japanese.
526 Used for localized menubars (French and Japanese) and localized splash
530 Basic Mule support. Must be installed prior to building with Mule.
533 Another Japanese Language Input Method. Can be used without a
534 separate process running as a dictionary server.
537 @subsection Productivity Packages (oa)
541 Calendar and diary support.
544 Single file lisp packages for various XEmacs goodies. Load this and
545 weed out the junk you don't want.
548 Forms editing support (obsolete, use the builtin Widget instead).
551 Provide a WM icon based on major mode.
557 Spell-checking with ispell.
560 PC style interface emulation.
563 Validated HTML/SGML editing.
566 SGML/Linuxdoc-SGML editing.
575 Mouse enhancement utility.
578 Various single file lisp packages for editing text files.
581 Display time & date on the modeline.
584 @subsection Operating System Utilities (os)
591 Enhanced front-end for Grep.
594 Front-end for Inferior Lisp.
597 Miscellaneous single-file O/S utilities, for printing, archiving,
598 compression, remote shells, etc.
601 A Unix process browsing tool.
604 @subsection Program Editing Support (prog)
608 Ada language support.
611 Basic single-file add-ons for editing C code.
614 C, C++ and Java language support.
617 GUD, gdb, dbx debugging support.
620 Interface over patch.
623 Another interface over patch.
629 Miscellaneous single-file lisp files for various programming languages.
632 Front-end support for Inferior Scheme.
635 Support for editing shell scripts.
638 Version Control for Free systems.
641 Version Control for ClearCase. This package must be installed prior
642 to building XEmacs [broken as of XEmacs 20.5-beta19].
648 @subsection Word Processing (wp)
652 Basic TeX/LaTeX support.
655 Crisp/Brief emulation.
658 DEC EDIT/EDT emulation.
661 XEmacs TeXinfo support.
664 Single-file TeX support.
667 DEC EDIT/TPU support.
670 VI emulation support.