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 * Creating Packages:: The basics.
23 * Available Packages:: A brief, out-of-date, directory of packaged LISP.
26 @node Package Terminology, Using Packages, , Packages
27 @comment node-name, next, previous, up
29 @subsection Package Flavors
31 There are two main flavors of packages.
34 @item Regular Packages
35 @cindex regular packages
36 A regular package is one in which multiple files are involved and one
37 may not in general safely remove any of them.
39 @item Single-File Packages
40 @cindex single-file packages
41 A single-file package is an aggregate collection of thematically
42 related but otherwise independent lisp files. These files are bundled
43 together for download convenience and individual files may be deleted at
44 will without any loss of functionality.
47 @subsection Package Distributions
49 XEmacs Lisp packages are distributed in two ways, depending on the
50 intended use. Binary Packages are for installers and end-users and may
51 be installed directly into an XEmacs package directory. Source Packages
52 are for developers and include all files necessary for rebuilding
53 bytecompiled lisp and creating tarballs for distribution.
55 @subsection Binary Packages
56 @cindex binary packages
57 Binary packages may be installed directly into an XEmacs package
60 @subsection Source Packages
61 @cindex source packages
62 Source packages contain all of the Package author's (where appropriate
63 in regular packages) source code plus all of the files necessary to
64 build distribution tarballs (Unix Tar format files, gzipped for space
67 @node Using Packages, Building Packages, Package Terminology, Packages
68 @comment node-name, next, previous, up
70 @subsection Getting Started
72 When you first download XEmacs 21, you will usually first grab the
73 @dfn{core distribution},
74 @cindex core distribution
76 @file{xemacs-21.0.tar.gz}. (Replace the @t{21.0} by the current version
77 number.) The core distribution contains the sources of XEmacs and a
78 minimal set of Emacs Lisp files, which are in the subdirectory named
79 @file{lisp}. This subdirectory used to contain all Emacs Lisp files
80 distributed with XEmacs. Now, to conserve disk space, most
81 non-essential packages were made optional.
83 @subsection Choosing the Packages You Need
85 The available packages can currently be found in the same ftp directory
86 where you grabbed the core distribution from, and are located in the
87 subdirectory @file{packages/binary-packages}. Package file names follow
88 the naming convention @file{<package-name>-<version>-pkg.tar.gz}.
90 If you have EFS @ref{(EFS)}, packages can be installed over the network.
91 Alternatively, if you have copies of the packages locally, you can
92 install packages from a local disk or CDROM.
94 The file @file{etc/PACKAGES} in the core distribution contains a list of
95 the packages available at the time of the XEmacs release. Packages are
96 also listed on the @code{Options} menu under:
99 Options->Customize->Emacs->Packages
102 However, don't select any of these menu picks unless you actually want
103 to install the given package (and have properly configured your system
106 You can also get a list of available packages, and whether or not they
107 are installed, using the visual package browser and installer. You can
108 access it via the menus:
111 Options->Manage Packages->List & Install
114 Or, you can get to it via the keyboard:
117 M-x pui-list-packages
120 Hint to system administrators of multi-user systems: it might be a good
121 idea to install all packages and not interfere with the wishes of your
124 If you can't find which package provides the feature you require, try
125 using the @code{package-get-package-provider} function. Eg., if you know
126 that you need @code{thingatpt}, type:
129 M-x package-get-package-provider RET thingatpt
132 which will return something like (fsf-compat "1.06"). You can the use
133 one of the methods above for installing the package you want.
135 @subsection XEmacs and Installing Packages
137 Normally, packages are installed over the network, using EFS
138 @ref{(EFS)}. However, you may not have network access, or you may
139 already have some or all of the packages on a local disk, such as a
140 CDROM. If you want to install from a local disk, you must first tell
141 XEmacs where to find the package binaries. This is done by adding a line
142 like the following to your init file:
145 (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
151 Here, you'd change @file{/my/path/to/package/binaries} to be the path
152 to your local package binaries. Next, restart XEmacs, and you're ready
153 to go (advanced users can just re-evaluate the sexp).
155 If you are installing from a temporary, one-time directory, you can also
156 add these directory names to @code{package-get-remote} using:
159 M-x pui-add-install-directory
162 Note, however, that any directories added using this function are not
163 saved; this information will be lost when you quit XEmacs.
165 If you're going to install over the network, you only have to insure
166 that EFS @ref{(EFS)} works, and that it can get outside a firewall, if
167 you happen to be behind one. You shouldn't have to do anything else;
168 XEmacs already knows where to go. However you can add your own mirrors
169 to this list. See @code{package-get-remote}.
171 The easiest way to install a package is to use the visual package
172 browser and installer, using the menu pick:
175 Options->Manage Packages->List & Install
179 Options->Manage Packages->Using Custom->Select-> ...
182 You can also access it using the keyboard:
185 M-x pui-list-packages
188 The visual package browser will then display a list of all packages.
189 Help information will be displayed at the very bottom of the buffer; you
190 may have to scroll down to see it. You can also press @kbd{?} to get
191 the same help. From this buffer, you can tell the package status by the
192 character in the first column:
196 The package has not been installed.
198 The package has been installed, but a newer version is available. The
199 current version is out-of-date.
201 The package has been marked for installation/update.
204 If there is no character in the first column, the package has been
205 installed and is up-to-date.
207 From here, you can select or unselect packages for installation using
208 the @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from
210 Once you've finished selecting the packages, you can
211 press the @kbd{x} key (or use the menu) to actually install the
212 packages. Note that you will have to restart XEmacs for XEmacs to
213 recognize any new packages.
222 Toggle between selecting and unselecting a package for installation.
224 Install selected packages.
226 View, in the minibuffer, additional information about the package, such
227 as the package date (not the build date) and the package author. Moving
228 the mouse over a package name will also do the same thing.
230 Toggle between verbose and non-verbose package display.
232 Refresh the package display.
234 Kill the package buffer.
237 Moving the mouse over a package will also cause additional information
238 about the package to be displayed in the minibuffer.
240 @subsection Other package installation interfaces
242 For an alternative package interface, you can select packages from the
243 customize menus, under:
246 Options->Customize->Emacs->Packages-> ...
250 Options->Manage Packages->Using Custom->Select-> ...
253 Set their state to on, and then do:
256 Options->Manage Packages->Using Custom->Update Packages
259 This will automatically retrieve the packages you have selected from the
260 XEmacs ftp site or your local disk, and install them into
261 XEmacs. Additionally it will update any packages you already have
262 installed to the newest version. Note that if a package is newly
263 installed you will have to restart XEmacs for the change to take effect.
265 You can also install packages using a semi-manual interface:
268 M-x package-get-all <return>
271 Enter the name of the package (e.g., @code{prog-modes}), and XEmacs
272 will search for the latest version (as listed in the lisp file
273 @file{lisp/package-get-base.el}), and install it and any packages that
276 @subsection Manual Binary Package Installation
278 Pre-compiled, binary packages can be installed in either a system
279 package directory (this is determined when XEmacs is compiled), or in
281 subdirectories of your @file{$HOME} directory:
284 ~/.xemacs/mule-packages
285 ~/.xemacs/xemacs-packages
288 Packages in the former directory will only be found by a Mule-enabled
291 XEmacs does not have to be running to install binary packages, although
292 XEmacs will not know about any newly-installed packages until you
293 restart XEmacs. Note, however, that installing a newer version of a
294 package while XEmacs is running could cause strange errors in XEmacs;
295 it's best to exit XEmacs before upgrading an existing package.
297 To install binary packages manually:
301 Download the package(s) that you want to install. Each binary package
302 will typically be a gzip'd tarball.
305 Decide where to install the packages: in the system package
306 directory, or in @file{~/.xemacs/mule-packages} or
307 @file{~/.xemacs/xemacs-packages}, respectively. If you want to install
308 the packages in the system package directory, make sure you can write
309 into that directory. If you want to install in your @file{$HOME}
310 directory, create the directory, @file{~/.xemacs/mule-packages} or
311 @file{~/.xemacs/xemacs-packages}, respectively.
314 Next, @code{cd} to the directory under which you want to install the
318 From this directory, uncompress and extract each of the gzip'd tarballs
319 that you downloaded in step 1. Unix and Cygnus cygwin users will
320 typically do this using the commands:
323 gunzip < package.tar.gz | tar xvf -
326 Above, replace @file{package.tar.gz} with the filename of the
327 package that you downloaded in step 1.
329 Of course, if you use GNU @code{tar}, you could also use:
332 tar xvzf package.tar.gz
335 @comment What about native MS Windows users???
338 That's it. Quit and restart XEmacs to get it to recognize any new or
343 @node Building Packages, Creating Packages, Using Packages, Packages
344 @comment node-name, next, previous, up
346 Source packages are available from the @file{packages/source-packages}
347 subdirectory of your favorite XEmacs distribution site. Alternatively,
348 they are available via CVS from @file{cvs.xemacs.org}. Look at
349 @file{http://cvs.xemacs.org} for instructions.
351 @subsection Prerequisites for Building Source Packages
353 You must have GNU @code{cp}, GNU @code{install} (or a BSD compatible
354 @code{install} program) GNU @code{make} (3.75 or later preferred),
355 @code{makeinfo} (1.68 from @code{texinfo-3.11} or later required), GNU
356 @code{tar} and XEmacs 21.0. The source packages will untar into a
357 correct directory structure. At the top level you must have
358 @file{XEmacs.rules} and @file{package-compile.el}. These files are
359 available from the XEmacs FTP site from the same place you obtained your
360 source package distributions.
362 @subsection What You Can Do With Source Packages
364 NB: A global build operation doesn't exist yet as of 13 January 1998.
366 Source packages are most useful for creating XEmacs package tarballs
367 for installation into your own XEmacs installations or for
368 distributing to others.
370 Supported operations from @file{make} are:
374 Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.
377 Remove XEmacs backups as well as the files deleted by @code{make clean}.
380 Bytecompile all files, build and bytecompile byproduct files like
381 @file{auto-autoloads.el} and @file{custom-load.el}. Create info version
382 of TeXinfo documentation if present.
385 Usually aliased to @code{srckit-std}. This does a @code{make
386 distclean} and creates a package source tarball in the staging
387 directory. This is generally only of use for package maintainers.
390 May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
391 @code{binkit-sourcedata}, or
392 @code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is
393 nothing to install in a data directory or info directory.
394 @code{sourceinfo} indicates that source and info files are to be
395 installed. @code{sourcedata} indicates that source and etc (data) files
396 are to be installed. @code{sourcedatainfo} indicates source, etc
397 (data), and info files are to be installed. A few packages have needs
398 beyond the basic templates so this is not yet complete.
401 Runs the rules @code{srckit} followed by @code{binkit}. This is
402 primarily of use by XEmacs maintainers producing files for distribution.
406 @node Creating Packages, Available Packages, Building Packages, Packages
407 @comment node-name, next, previous, up
409 Creating a package from an existing Lisp library is not very difficult.
411 In addition to the Lisp libraries themselves, you need a
412 @file{package-info.in} file and a simple @file{Makefile}. The rest is
413 done by @file{XEmacs.rules}, part of the packaging system
416 @file{package-info.in} contains a single Lisp form like this:
419 (name ; your package's name
420 (standards-version 1.1
422 author-version AUTHOR_VERSION
424 build-date BUILD_DATE
425 maintainer MAINTAINER
426 distribution xemacs ; change to "mule" if MULE is needed
430 description "description" ; a one-line description string
434 provides (feature1 feature2) ; one for every `provides' form
440 You must fill in the four commented lines. The value of @code{name} is
441 the name of your package as an unquoted symbol. Normally it is the name
442 of the main Lisp file or principal feature provided. The allowed values
443 for distribution are @code{xemacs} and @code{mule}. Write them as
444 unquoted symbols. The @code{description} is a quoted Lisp string; use
445 the usual conventions. The value for @code{provides} is a list of
446 feature symbols (written unquoted). All of the features provided by
447 libraries in your package should be elements of this list. Implementing
448 an automatic method for generating the @file{provides} line is
449 desirable, but as yet undone.
451 The variables in upper-case are references to variables set in the
452 @file{Makefile} or automatically generated. Do not change them; they
453 are automatically filled in by the build process.
455 The remaining lines refer to implementation constants
456 (@code{standards-version}), or features that are unimplemented or have
457 been removed (@code{priority} and @code{dump}). The @code{type} line is
458 not normally relevant to external maintainers; the alternate value is
459 @code{single-file}, which refers to packages consed up out of a number
460 of single-file libraries that are more or less thematically related. An
461 example is @code{prog-modes}. Single-file packages are basically for
462 administrative convenience, and new packages should generally be created
465 The @file{Makefile} is quite stylized. The idea is similar to an
466 @file{Imakefile} or an @code{automake} file: the complexity is hidden in
467 generic rules files, in this case the @file{XEmacs.rules} include file
468 in the top directory of the packages hierarchy. Although a number of
469 facilities are available for complex libraries, most simple packages'
470 @file{Makefile}s contain a copyright notice, a few variable definitions,
471 an include for @file{XEmacs.rules}, and a couple of standard targets.
473 The first few @code{make} variables defined are @code{VERSION},
474 @code{AUTHOR_VERSION}, @code{MAINTAINER}, @code{PACKAGE},
475 @code{PKG_TYPE}, @code{REQUIRES}, and @code{CATEGORY}. All but one were
476 described in the description of @file{package-info.in}. The last is an
477 admistrative grouping. Current categories include @code{comm},
478 @code{games}, @code{libs}, @code{mule}, @code{oa}, @code{os},
479 @code{prog}, and @code{wp}. @ref{Available Packages}, for a list of
482 Next, define the variable @code{ELCS}. This contains the list of the
483 byte-compiled Lisp files used by the package. These files and their
484 @file{.el} versions will be included in the binary package. If there
485 are other files (such as extra Lisp sources or an upstream
486 @file{Makefile}) that are normally placed in the installed Lisp
487 directory, but not byte-compiled, they can be listed as the value of
488 @code{EXTRA_SOURCES}.
490 The include is simply
492 include ../../XEmacs.rules
495 The standard targets follow. These are
498 all:: $(ELCS) auto-autoloads.elc
505 Other targets (such as Texinfo sources) may need to be added as
506 dependencies for the @code{all} target. Dependencies for @code{srckit}
507 and @code{binkit} (that is, values for @var{srckit-alias} and
508 @var{binkit-alias}) are defined in @file{XEmacs.rules}. The most useful
509 of these values are given in the following table.
513 Usually set to @code{srckit-std}.
516 May be set to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
517 @code{binkit-sourcedata}, or
518 @code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is
519 nothing to install in a data directory or info directory.
520 @code{sourceinfo} indicates that source and info files are to be
521 installed. @code{sourcedata} indicates that source and etc (data) files
522 are to be installed. @code{sourcedatainfo} indicates source, etc
523 (data), and info files are to be installed.
526 Data files include things like pixmaps for a package-specific toolbar,
527 and are normally installed in @file{etc/@var{PACKAGE_NAME}}. A few
528 packages have needs beyond the basic templates. See @file{XEmacs.rules}
529 or a future revision of this manual for details.
531 @node Available Packages, , Creating Packages, Packages
532 @comment node-name, next, previous, up
534 This section is surely out-of-date. If you're sure that XEmacs is
535 able to do something, but your installed XEmacs won't do it for you,
536 it's probably in a package. If you can't find it in this section,
537 that's a bug---please report it. It is very hard to keep this section
538 up-to-date; your reports, comments, and questions will help a lot.
540 This data is up-to-date as of 10 February 1999. (Ouch! I told you!)
542 @subsection Library Packages (libs)
544 These packages are required to build and support most of the rest of
545 XEmacs. By design, xemacs-base is a `regular' package. Use restraint
546 when adding new files there as it is required by almost everything.
550 Support for Sparcworks.
553 A Portable Emacs Library. Used by XEmacs MIME support.
559 The DIRectory EDitor is for manipulating, and running commands on
560 files in a directory.
563 Treat files on remote systems the same as local files.
566 Fundamental lisp files for providing email support.
569 Support for building with Tooltalk.
572 Fundamental XEmacs support. Install this unless you wish a totally
576 XEmacs Lisp developer support. This package contains utilities for
577 supporting Lisp development. It is a single-file package so it may be
581 @subsection Communications Packages (comm)
583 These packages provide support for various communications, primarily
588 Footnoting in mail message editing modes.
594 The Gnus Newsreader and Mailreader.
597 Support for messaging encryption with PGP.
600 Front end support for MH.
603 Miscellaneous Networking Utilities. This is a single-file package and
604 files may be deleted at will.
607 Emacs implementation of the ph client to CCSO/qi directory servers.
610 An obsolete Emacs mailer. If you do not already use it don't start.
613 An Emacs citation tool. Useful with all Emacs Mailers and Newsreaders.
625 @subsection Games and Amusements (games)
629 Spook and Yow (Zippy quotes).
632 Tetris, Sokoban, and Snake.
638 Other amusements and diversions.
641 @subsection Mule Support (mule)
645 Wnn (4.2 and 6) support. SJ3 support. Must be installed prior to
649 Quail. Used for everything other than English and Japanese.
652 Used for localized menubars (French and Japanese) and localized splash
656 Basic Mule support. Must be installed prior to building with Mule.
659 Another Japanese Language Input Method. Can be used without a
660 separate process running as a dictionary server.
663 @subsection Productivity Packages (oa)
667 Calendar and diary support.
670 Single file lisp packages for various XEmacs goodies. Load this and
671 weed out the junk you don't want.
674 Forms editing support (obsolete, use the builtin Widget instead).
677 Provide a WM icon based on major mode.
683 Spell-checking with ispell.
686 PC style interface emulation.
689 Validated HTML/SGML editing.
692 SGML/Linuxdoc-SGML editing.
701 Mouse enhancement utility.
704 Various single file lisp packages for editing text files.
707 Display time & date on the modeline.
710 @subsection Operating System Utilities (os)
717 Enhanced front-end for Grep.
720 Front-end for Inferior Lisp.
723 Miscellaneous single-file O/S utilities, for printing, archiving,
724 compression, remote shells, etc.
727 A Unix process browsing tool.
730 @subsection Program Editing Support (prog)
734 Ada language support.
737 Basic single-file add-ons for editing C code.
740 C, C++ and Java language support.
743 GUD, gdb, dbx debugging support.
746 Interface over patch.
749 Another interface over patch.
755 Miscellaneous Lisp libraries for various programming languages.
758 Front-end support for Inferior Scheme.
761 Support for editing shell scripts.
764 Version control for free systems.
767 Version control for ClearCase.
773 @subsection Word Processing (wp)
777 Basic TeX/LaTeX support.
780 Crisp/Brief emulation.
783 DEC EDIT/EDT emulation.
786 XEmacs TeXinfo support.
789 Single-file TeX support.
792 DEC EDIT/TPU support.
795 VI emulation support.