1 @c This is part of the SXEmacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
3 @c Copyright (C) 2005 Steve Youngs
4 @c See file sxemacs.texi for copying conditions.
5 @node Packages, Basic, Startup Paths, Top
6 @comment node-name, next, previous, up
11 The SXEmacs distribution comes only with a very basic set of built-in
12 modes and packages. Most of the packages that were part of the
13 distribution of earlier versions of XEmacs (prior to XEmacs 21) are now
14 available separately. The installer as well as the user can choose
15 which packages to install; the actual installation process is easy.
16 This gives an installer the ability to tailor an SXEmacs installation
17 for local needs with safe removal of unnecessary code.
20 * Package Terminology:: Understanding different kinds of packages.
21 * Bootstrapping PUI:: Making SXEmacs Package Tools Usable.
22 * Installing Packages:: How to install packages.
23 * Building Packages:: Building packages from CVS sources.
24 * Local.rules File:: This is an important file that you must create.
25 * Available Packages:: A brief directory of packaged LISP.
28 @node Package Terminology, Bootstrapping PUI, , Packages
29 @comment node-name, next, previous, up
30 @heading Package Terminology:
31 @subsection Package Flavors
33 There are two main flavors of packages.
38 @cindex regular packages
39 A regular package is one in which multiple files are involved and one
40 may not in general safely remove any of them, unless removing the entire
45 @cindex single-file packages
46 A single-file package is an aggregate collection of thematically
47 related but otherwise independent lisp files. These files are bundled
48 together for download convenience and individual files may be deleted at
49 will without any loss of functionality. However, we would recommend
50 that you follow this rule of thumb: "When in doubt, don't delete".
53 @subsection Package Distributions
54 @cindex package distributions
55 XEmacs Lisp packages are distributed in two ways, depending on the
56 intended use. Binary Packages are for installers and end-users that can
57 be installed directly into an XEmacs package directory. Source Packages
58 are for developers and include all files necessary for rebuilding
59 bytecompiled lisp and creating tarballs for distribution.
61 @subsection Binary Packages
62 @cindex binary packages
63 Binary packages may be installed directly into an XEmacs package
66 @subsection Source Packages
67 @cindex source packages
68 Source packages contain all of the Package author's (where appropriate
69 in regular packages) source code plus all of the files necessary to
70 build distribution tarballs (Unix Tar format files, gzipped for space
73 Currently, source packages are only available via CVS. See
74 @url{http://cvs.xemacs.org/} for details.
76 @node Bootstrapping PUI, Installing Packages, Package Terminology, Packages
77 @comment node-name, next, previous, up
78 @cindex pui, bootstrap
79 @cindex pui, initialise
80 @cindex pui, initialize
81 @heading Making SXEmacs Package Tools Usable
83 As you may be aware, SXEmacs uses the same packaging tools (@dfn{PUI})
84 as XEmacs. What you may not be aware of is that PUI is useless until
85 you manually install a couple of packages. Yep, that's right, you
86 can't use PUI to install packages unless you install some packages
89 Well @emph{that} was for XEmacs, @emph{this} is SXEmacs! SXEmacs can
90 @dfn{bootstrap} PUI @strong{without} needing @strong{any} packages to
91 be pre-installed. It does so via FFI (@dfn{Foreign Function Interface})
94 Your SXEmacs needed to be configured with @code{--enable-ffi} when it
95 was built, and you also need @file{libcurl} on your system. Most
96 Linux distributions have @file{libcurl} installed as part of their
97 standard installation. So you are more than likely good to go
98 already. But if you are not sure, try:
100 @code{M-: (require 'ffi-curl) RET}
103 It will not succeed if you don't have either FFI or @file{libcurl}.
105 @subheading How To Bootstrap PUI (aka, achieving @dfn{PUI-nirvana})
108 Set @var{package-get-remote}.
110 Menu: Tools -> Packages -> Set Download Site ->
112 @code{M-x pui-bootstrap RET}
115 @strong{That's it!} What will happen is that SXEmacs will download
116 and install the latest package-index file. Then it will download and
117 install the latest versions of the EFS and xemacs-base packages.
118 Finally, SXEmacs will ask you if you want to install more packages.
119 At this point, SXEmacs reverts back to @dfn{normal} PUI behaviour (using
120 EFS to download the packages).
122 That wasn't hard, was it?
124 @node Installing Packages, Building Packages, Bootstrapping PUI, Packages
125 @comment node-name, next, previous, up
126 @cindex installing packages
128 @heading Installing Packages:
129 @subsection Getting Started
131 When you first download SXEmacs, you will usually first grab the
132 @dfn{core distribution},
133 @cindex core distribution
135 @file{sxemacs-22.x.x.tar.gz}. (Replace the @t{22.x.x} by the current version
136 number.) The core distribution contains the sources of SXEmacs and a
137 minimal set of Emacs Lisp files, which are in the subdirectory named
140 @subsection Choosing the Packages You Need
141 @cindex choosing packages
142 The @ref{Available Packages} can currently be found at
143 @uref{ftp://ftp.xemacs.org/, the XEmacs FTP site}, or any of its
144 mirrors. Look in the subdirectory @file{packages}. Package file names
145 follow the naming convention @file{<package-name>-<version>-pkg.tar.gz}.
147 If you have EFS @ref{(EFS)}, packages can be installed over the network.
148 Alternatively, if you have copies of the packages locally, you can
149 install packages from a local disk or CDROM.
151 The file @file{etc/PACKAGES} in the core distribution contains a list of
152 the @ref{Available Packages} at the time of the SXEmacs release.
154 You can also get a list of available packages, and whether or not they
155 are installed, using the visual package browser and installer. You can
156 access it via the menus:
159 Tools -> Packages -> List and Install
162 Or, you can get to it via the keyboard:
165 @code{M-x pui-list-packages}
168 Hint to system administrators of multi-user systems: it might be a good
169 idea to install all packages and not interfere with the wishes of your
172 If you can't find which package provides the feature you require, try
173 using the @code{package-get-package-provider} function. Eg., if you know
174 that you need @code{thingatpt}, type:
177 @code{M-x package-get-package-provider RET thingatpt}
180 which will return something like @samp{(fsf-compat "1.08")}. You can the use
181 one of the methods above for installing the package you want.
183 @subsection SXEmacs and Installing Packages
185 There are three main ways to install packages:
188 * Automatically:: Using the package tools from SXEmacs.
189 * Manually:: Using individual package tarballs.
190 * Sumo:: All at once, using the 'Sumo Tarball'.
191 * Which Packages:: Which packages to install.
192 * Removing Packages:: Removing packages.
195 But regardless of the method you use to install packages, they can only
196 be used by SXEmacs after a restart unless the package in question has not
197 been previously installed.
199 @node Automatically, Manually, ,Installing Packages
200 @comment node-name, next, previous, up
201 @cindex automatic package install
202 @cindex package tools
203 @heading Automatic Package Installation:
204 SXEmacs comes with some tools to make the periodic updating and
205 installing easier. It will notice if new packages or versions are
206 available and will fetch them from the FTP site.
208 Unfortunately this requires that a few packages are already in place.
209 You will have to install them by hand @pxref{Manually}, or use a SUMO
210 tarball. This requirement will hopefully go away in the future. And,
211 indeed it has, @xref{Bootstrapping PUI}.
213 If you are unlucky enough to have a @dfn{FFI-enabled} SXEmacs, you
214 will have to manually install the EFS and xemacs-base packages
219 Choose a download site.
220 via menu: Tools -> Packages -> Set Download Site
221 via keyb: @code{M-x customize-variable RET package-get-remote RET}
222 (put in the details of remote host and directory)
224 If the package tarballs _AND_ the package-index file are in a
225 local directory, you can: @code{M-x pui-set-local-package-get-directory RET}
228 Obtain a list of packages and display the list in a buffer named
230 menu: Tools -> Packages -> List & Install
231 keyb: @code{M-x pui-list-packages RET}
233 SXEmacs will now connect to the remote site and download the
234 latest package-index file.
236 The visual package browser will then display a list of all packages.
237 Help information will be displayed at the very bottom of the buffer; you
238 may have to scroll down to see it. You can also press @kbd{?} to get
239 the same help. From this buffer, you can tell the package status by the
240 character in the first column:
244 The package has not been installed.
246 The package has been installed, but a newer version is available. The
247 current version is out-of-date.
249 The package has been marked for installation/update.
252 If there is no character in the first column, the package has been
253 installed and is up to date.
255 From here, you can select or unselect packages for installation using
256 the @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from
257 the Popup @kbd{Mouse-3} Menu.
258 Once you've finished selecting the packages, you can
259 press the @kbd{x} key (or use the menu) to actually install the
260 packages. Note that you will have to restart SXEmacs for SXEmacs to
261 recognize any new packages.
270 Toggle between selecting and unselecting a package for installation.
272 Install selected packages.
274 View, in the minibuffer, additional information about the package, such
275 as the package date (not the build date) and the package author. Moving
276 the mouse over a package name will also do the same thing.
278 Toggle between verbose and non-verbose package display.
280 Refresh the package display.
282 Kill the package buffer.
285 Moving the mouse over a package will also cause additional information
286 about the package to be displayed in the minibuffer. If you have
287 balloon-help enabled a balloon-help frame will pop up and display
288 additional package information also.
292 Choose the packages you wish to install.
293 mouse: Click button 2 on the package name.
294 keyb: @kbd{RET} on the package name
297 Make sure you have everything you need.
298 menu: Packages -> Add Required
301 SXEmacs will now search for packages that are required by the
302 ones that you have chosen to install and offer to select
305 For novices and gurus alike, this step can save your bacon.
306 It's easy to forget to install a critical package.
309 Download and install the packages.
310 menu: Packages -> Install/Remove Selected
314 You can also install packages using a semi-manual interface:
317 M-x package-get-all <return>
320 Enter the name of the package (e.g., @code{prog-modes}), and SXEmacs
321 will search for the latest version and install it and any packages that
324 @heading Keeping Packages Up To Date:
325 Once you have the packages you want installed (using any of the above
326 methods) you'll want to keep them up to date. You can do this easily
330 Tools -> Packages -> Set Download Site
331 Tools -> Packages -> Update Installed Packages
335 @node Manually, Sumo, Automatically, Installing Packages
336 @comment node-name, next, previous, up
337 @cindex manual package install
338 @heading Manual Package Installation:
339 Fetch the packages from the FTP site, CD-ROM whatever. The filenames
340 have the form @file{name-<version>-pkg.tar.gz} and are gzipped tar files. For
341 a fresh install it is sufficient to untar the file at the top of the
344 Note: If you are upgrading packages already installed, it's best to
345 remove the old package first @ref{Removing Packages}.
347 For example if we are installing the @file{xemacs-base}
348 package (version 1.48):
351 mkdir $prefix/share/sxemacs/xemacs-packages RET # if it does not exist yet
352 cd $prefix/share/sxemacs/xemacs-packages RET
353 gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
355 Or if you have GNU tar, the last step can be:
357 tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
360 For MULE related packages, it is best to untar into the mule-packages
361 hierarchy, i.e. for the @file{mule-base} package, version 1.37:
364 mkdir $prefix/share/sxemacs/mule-packages RET # if it does not exist yet
365 cd $prefix/share/sxemacs/mule-packages RET
366 gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
368 Or if you have GNU tar, the last step can be:
370 tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
373 @node Sumo, Which Packages, Manually, Installing Packages
374 @comment node-name, next, previous, up
375 @cindex sumo package install
376 @heading Installing the Sumo Packages:
377 Those with little time, cheap connections and plenty of disk space can
378 install all the packages at once using the sumo tarballs.
379 Download the file: @file{xemacs-sumo.tar.gz}
381 For an SXEmacs compiled with Mule you also need: @file{xemacs-mule-sumo.tar.gz}
383 N.B. They are called 'Sumo Tarballs' for good reason. They are
384 currently about 19MB and 4.5MB (gzipped) respectively.
388 @code{cd $prefix/share/sxemacs ; gunzip -c <tarballname> | tar xvf - RET}
390 Or, if you have GNU tar:
392 @code{cd $prefix/share/sxemacs ; tar zxvf /path/to/<tarballname> RET}
394 As the Sumo tarballs are not regenerated as often as the individual
395 packages, it is recommended that you use the automatic package tools
396 afterwards to pick up any recent updates.
398 @node Which Packages, Removing Packages, Sumo, Installing Packages
399 @comment node-name, next, previous, up
400 @cindex which packages
401 @cindex choosing packages
402 @heading Which Packages to Install:
403 This is difficult to say. When in doubt install a package. If you
404 administrate a big site it might be a good idea to just install
405 everything. A good minimal set of packages for SXEmacs-latin1 would be
407 xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
408 edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes,
409 text-modes, time, mailcrypt
411 If you are using the SXEmacs package tools, don't forget to do:
413 Packages -> Add Required
415 To make sure you have everything that the packages you have chosen to
418 See also @ref{Available Packages} for further descriptions of the individual
421 @node Removing Packages, ,Which Packages, Installing Packages
422 @comment node-name, next, previous, up
423 @cindex removing packages
424 @cindex deleting packages
425 @heading Removing Packages:
426 Because the exact files and their locations contained in a package may
427 change it is recommended to remove a package first before installing a
428 new version. In order to facilitate removal each package contains an
429 @file{pgkinfo/MANIFEST.pkgname} file which list all the files belonging
432 No need to panic, you don't have to go through the
433 @file{pkinfo/MANIFEST.pkgname} and manually delete the files. Instead, use
434 @code{M-x package-get-delete-package RET}.
436 Note that the interactive package tools included with SXEmacs already do
439 @node Building Packages, Local.rules File, Installing Packages, Packages
440 @comment node-name, next, previous, up
441 @cindex building packages
442 @cindex package building
443 @heading Building Packages:
444 Currently, source packages are only available via anonymous CVS. See
445 @url{http://cvs.xemacs.org/} for details of checking out the
446 @file{xemacs-packages} module.
448 @subsection Prerequisites for Building Source Packages
453 (or a BSD compatible install program).
455 (3.75 or later preferred).
457 (4.2 from GNU texinfo 4.2 or later required).
462 @item A properly configured @file{Local.rules} file.
463 @ref{Local.rules File}.
465 And of course, SXEmacs.
467 @subsection What You Can Do With Source Packages
469 The packages CVS sources are most useful for creating XEmacs package
470 tarballs for installation into your own SXEmacs installations or for
471 distributing to others.
473 For a list and description of the different @file{Makefile} targets,
474 @xref{Makefile Targets,,,lispref}.
476 @node Local.rules File, Available Packages, Building Packages, Packages
477 @comment node-name, next, previous, up
479 @heading The Local.rules File:
480 This file is used when building and installing packages from source. In
481 the top level of the CVS module, @file{packages}, contains the
482 file, @file{Local.rules.template}. Simply copy that to
483 @file{Local.rules} and edit it to suit your needs.
485 For a complete discussion of the @file{Local.rules} file,
486 @xref{Local.rules File,,,lispref}.
488 @node Available Packages, , Local.rules File, Packages
489 @comment node-name, next, previous, up
490 @cindex available packages
492 @heading Available Packages:
493 This section lists the Lisp packages that are currently available from
494 xemacs.org and it's mirrors. If a particular package that you are
495 looking for isn't here, please send a message to the
496 @email{xemacs-beta@@xemacs.org, XEmacs Beta list}.
498 This data is up to date as of June 27, 2003.
500 @subsection Normal Packages
501 A very broad selection of elisp packages.
505 Support for Sparcworks.
508 Ada language support.
511 A Portable Emacs Library. Used by XEmacs MIME support.
514 Basic TeX/LaTeX support.
517 The Big Brother Data Base: a rolodex-like database program.
520 Build XEmacs using custom widgets.
521 This package is cannot be used to build SXEmacs because SXEmacs has
522 different @file{configure} options from XEmacs.
525 Basic single-file add-ons for editing C code.
531 Calendar and diary support.
534 C, C++ and Java language support.
537 Support for the Clearcase version control system.
540 "Fortune cookie"-style messages. Includes Spook (suspicious phrases)
541 and Yow (Zippy quotes).
544 Crisp/Brief emulation.
547 GUD, gdb, dbx debugging support.
550 Interface to RFC2229 dictionary servers.
553 The DIRectory EDitor is for manipulating, and running commands on
554 files in a directory.
557 DocBook editing support.
560 Crypto functionality in Emacs Lisp.
566 Interface over patch.
569 Single file lisp packages for various XEmacs goodies. Load this and
570 weed out the junk you don't want.
573 DEC EDIT/EDT emulation.
576 Treat files on remote systems the same as local files.
579 Enhanced Implementation of Emacs Interpreted Objects.
582 Portable Emacs Lisp utilities library.
585 Another interface over patch.
588 Command shell implemented entirely in Emacs Lisp.
591 ESS: Emacs Speaks Statistics.
597 Emacs Unified Directory Client (LDAP, PH).
600 Footnoting in mail message editing modes.
603 Forms editing support (obsolete, use the built-in Widget instead).
606 Fortran language support.
609 Provide a WM icon based on major mode.
612 GNU Emacs compatibility files.
615 Tetris, Sokoban, and Snake.
618 General documentation. Presently, empty.
624 The Gnus Newsreader and Mailreader.
627 Haskell language support.
633 Advanced replacement for buffer-menu.
636 Editing and Shell mode for the Interactive Data Language.
639 Enhanced front-end for Grep.
642 Front-end for interacting with Inferior Lisp (external lisps).
645 Spell-checking with ispell.
648 Java language and development support.
651 IRC (Internet Relay Chat) client for Emacs.
654 Fundamental lisp files for providing email support.
657 Support for messaging encryption with PGP.
660 Messaging in an Emacs World; a MIME-based email program.
663 Front end support for MH.
666 Elisp implementation of the game 'Minehunt'.
669 Other amusements and diversions.
672 Support for Multiple Major Modes within a single buffer.
675 Miscellaneous Networking Utilities. This is a single-file package and
676 files may be deleted at will.
679 Objective Caml editing support.
682 Miscellaneous single-file O/S utilities, for printing, archiving,
683 compression, remote shells, etc.
686 PC style interface emulation.
692 Provides programmatic completion.
695 Perl language support.
698 Emacs interface to various PGP implementations.
701 Miscellaneous single-file lisp files for various programming languages.
704 Print buffers to PostScript printers.
707 Validated HTML/SGML editing.
710 A collection of DTDs for psgml. Note that this package is deprecated
711 and will be removed in the future, most likely Q2/2003. Instead of using
712 this, you should install needed DTDs yourself.
715 Python language support.
718 Emacs support for LaTeX cross-references, citations.
721 An obsolete Emacs mailer. If you do not already use it don't start.
724 Ruby language support.
727 Simple Authentication and Security Layer (SASL) library.
730 Front-end support for Inferior Scheme.
736 SGML/Linuxdoc-SGML editing.
739 Support for editing shell scripts.
742 Manage Sieve email filtering scripts.
748 Standard ML editing support.
751 XEmacs Sun sound files.
754 XEmacs Microsoft sound files.
757 Provides a separate frame with convenient references.
760 Mouse enhancement utility.
763 An Emacs citation tool. Useful with all Emacs Mailers and Newsreaders.
766 XEmacs TeXinfo support.
769 Various single file lisp packages for editing text files.
772 Single-file TeX support.
775 Display time & date on the modeline.
778 Emacs MIME support. Not needed for Gnus >= 5.8.0
781 Support for building with Tooltalk.
784 DEC EDIT/TPU support.
787 Remote shell-based file editing. This is similar to EFS or Ange-FTP,
788 but works with rsh/ssh and rcp/scp.
791 Version Control for Free systems.
794 Version Control for ClearCase. This package will shortly be
795 replaced with clearcase.el
801 A Unix process browsing tool.
804 VI emulation support.
813 Semi WYSIWYG for LaTeX, HTML, etc, using additional fonts.
816 Fundamental XEmacs support. Install this unless you wish a totally
820 XEmacs Lisp developer support. This package contains utilities for
821 supporting Lisp development. It is a single-file package so it may be
828 A minor mode for (X)Emacs which allows running an XSLT processor on a
835 @subsection Mule Support (mule)
837 MULti-lingual Enhancement. Support for world scripts such as
838 Latin, Arabic, Cyrillic, Chinese, Japanese, Greek, Hebrew etc.
839 To use these packages your SXEmacs must be compiled with Mule
844 Lisp Interface to EDICT, Kanji Dictionary.
847 Wnn (4.2 and 6) support. SJ3 support. Must be installed prior to
851 Unify character sets in a buffer. When characters belong to disjoint
852 character sets, this attempts to translate the characters so
853 that they belong to one character set. If the buffer coding system is
854 not sufficient, this suggests different coding systems.
857 Quail. Used for everything other than English and Japanese.
860 Used for localized menubars (French and Japanese) and localized splash
864 Dictionary support. (This isn't an English dictionary program)
867 Basic Mule support. Must be installed prior to building with Mule.
870 Extended coding systems (including Unicode) for SXEmacs.
873 Another Japanese Language Input Method. Can be used without a
874 separate process running as a dictionary server.