Packages
========

The XEmacs 21 distribution comes only with a very basic set of built-in modes and packages.  Most of the packages that were part of the distribution of earlier versions of XEmacs are now available separately.  The installer as well as the user can choose which packages to install; the actual installation process is easy. This gives an installer the ability to tailor an XEmacs installation for local needs with safe removal of unnecessary code.

Package Flavors
---------------

There are two main flavors of packages.

  * Regular Packages A regular package is one in which multiple files are involved and one may not in general safely remove any of them.

  * Single-File Packages A single-file package is an aggregate collection of thematically related but otherwise independent lisp files.  These files are bundled together for download convenience and individual files may be deleted at will without any loss of functionality.

Package Distributions
---------------------

XEmacs Lisp packages are distributed in two ways, depending on the intended use.  Binary Packages are for installers and end-users and may be installed directly into an XEmacs package directory.  Source Packages are for developers and include all files necessary for rebuilding bytecompiled lisp and creating tarballs for distribution.

Binary Packages
---------------

Binary packages may be installed directly into an XEmacs package hierarchy.

Source Packages
---------------

Source packages contain all of the Package author's (where appropriate in regular packages) source code plus all of the files necessary to build distribution tarballs (Unix Tar format files, gzipped for space savings).

Getting Started
---------------

When you first download XEmacs 21, you will usually first grab the core distribution, a file called xemacs-21.0.tar.gz. (Replace the 21.0 by the current version number.)  The core distribution contains the sources of XEmacs and a minimal set of Emacs Lisp files, which are in the subdirectory named lisp.  This subdirectory used to contain all Emacs Lisp files distributed with XEmacs.  Now, to conserve disk space, most non-essential packages were made optional.

Choosing the Packages You Need
------------------------------

The available packages can currently be found in the same ftp directory where you grabbed the core distribution from, and are located in the subdirectory packages/binary-packages.  Package file names follow the naming convention <package-name>-<version>-pkg.tar.gz.

If you have EFS (EFS), packages can be installed over the network. Alternatively, if you have copies of the packages locally, you can install packages from a local disk or CDROM.

The file etc/PACKAGES in the core distribution contains a list of the packages available at the time of the XEmacs release.  Packages are also listed on the Options menu under:

             Options->Customize->Emacs->Packages

However, don't select any of these menu picks unless you actually want to install the given package (and have properly configured your system to do so).

You can also get a list of available packages, and whether or not they are installed, using the visual package browser and installer.  You can access it via the menus:

             Options->Manage Packages->List & Install

Or, you can get to it via the keyboard:

     M-x pui-list-packages

Hint to system administrators of multi-user systems: it might be a good idea to install all packages and not interfere with the wishes of your users.

If you can't find which package provides the feature you require, try using the package-get-package-provider function. Eg., if you know that you need thingatpt, type:

     M-x package-get-package-provider RET thingatpt

which will return something like (fsf-compat "1.06"). You can the use one of the methods above for installing the package you want.

XEmacs and Installing Packages
------------------------------

Normally, packages are installed over the network, using EFS (EFS).  However, you may not have network access, or you may already have some or all of the packages on a local disk, such as a CDROM.  If you want to install from a local disk, you must first tell XEmacs where to find the package binaries.  This is done by adding a line like the following to your init file:

     (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
                                    package-get-remote))

See Init File.

Here, you'd change /my/path/to/package/binaries to be the path to your local package binaries.  Next, restart XEmacs, and you're ready to go (advanced users can just re-evaluate the sexp).

If you are installing from a temporary, one-time directory, you can also add these directory names to package-get-remote using:

             M-x pui-add-install-directory

Note, however, that any directories added using this function are not saved; this information will be lost when you quit XEmacs.

If you're going to install over the network, you only have to insure that EFS (EFS) works, and that it can get outside a firewall, if you happen to be behind one.  You shouldn't have to do anything else; XEmacs already knows where to go. However you can add your own mirrors to this list. See package-get-remote.

The easiest way to install a package is to use the visual package browser and installer, using the menu pick:

             Options->Manage Packages->List & Install

or

             Options->Manage Packages->Using Custom->Select-> ...

You can also access it using the keyboard:

     M-x pui-list-packages

The visual package browser will then display a list of all packages. Help information will be displayed at the very bottom of the buffer; you may have to scroll down to see it.  You can also press ? to get the same help.  From this buffer, you can tell the package status by the character in the first column:

-
     The package has not been installed.

*
     The package has been installed, but a newer version is available.  The current version is out-of-date.

+
     The package has been marked for installation/update.

If there is no character in the first column, the package has been installed and is up-to-date.

From here, you can select or unselect packages for installation using the RET key, the Mouse-2 button or selecting "Select" from the (Popup) Menu. Once you've finished selecting the packages, you can press the x key (or use the menu) to actually install the packages. Note that you will have to restart XEmacs for XEmacs to recognize any new packages.

Key summary:

?
     Display simple help.

RET
Mouse-2
     Toggle between selecting and unselecting a package for installation.

x
     Install selected packages.

SPC
     View, in the minibuffer, additional information about the package, such as the package date (not the build date) and the package author.  Moving the mouse over a package name will also do the same thing.

v
     Toggle between verbose and non-verbose package display.

g
     Refresh the package display.

q
     Kill the package buffer.

Moving the mouse over a package will also cause additional information about the package to be displayed in the minibuffer.

Other package installation interfaces
-------------------------------------

For an alternative package interface, you can select packages from the customize menus, under:

             Options->Customize->Emacs->Packages-> ...

or

             Options->Manage Packages->Using Custom->Select-> ...

Set their state to on, and then do:

             Options->Manage Packages->Using Custom->Update Packages

This will automatically retrieve the packages you have selected from the XEmacs ftp site or your local disk, and install them into XEmacs.  Additionally it will update any packages you already have installed to the newest version.  Note that if a package is newly installed you will have to restart XEmacs for the change to take effect.

You can also install packages using a semi-manual interface:

     M-x package-get-all <return>

Enter the name of the package (e.g., prog-modes), and XEmacs will search for the latest version (as listed in the lisp file lisp/package-get-base.el), and install it and any packages that it depends upon.

Manual Binary Package Installation
----------------------------------

Pre-compiled, binary packages can be installed in either a system package directory (this is determined when XEmacs is compiled), or in one of the following subdirectories of your $HOME directory:

     ~/.xemacs/mule-packages
     ~/.xemacs/xemacs-packages

Packages in the former directory will only be found by a Mule-enabled XEmacs.

XEmacs does not have to be running to install binary packages, although XEmacs will not know about any newly-installed packages until you restart XEmacs.  Note, however, that installing a newer version of a package while XEmacs is running could cause strange errors in XEmacs; it's best to exit XEmacs before upgrading an existing package.

To install binary packages manually:

 1. Download the package(s) that you want to install.  Each binary package will typically be a gzip'd tarball.

 2. Decide where to install the packages: in the system package directory, or in ~/.xemacs/mule-packages or ~/.xemacs/xemacs-packages, respectively.  If you want to install the packages in the system package directory, make sure you can write into that directory.  If you want to install in your $HOME directory, create the directory, ~/.xemacs/mule-packages or ~/.xemacs/xemacs-packages, respectively.

 3. Next, cd to the directory under which you want to install the package(s).

 4. From this directory, uncompress and extract each of the gzip'd tarballs that you downloaded in step 1.  Unix and Cygnus cygwin users will typically do this using the commands:

                  gunzip < package.tar.gz | tar xvf -

     Above, replace package.tar.gz with the filename of the package that you downloaded in step 1.

     Of course, if you use GNU tar, you could also use:

                  tar xvzf package.tar.gz

 5. That's it.  Quit and restart XEmacs to get it to recognize any new or changed packages.

Source packages are available from the packages/source-packages subdirectory of your favorite XEmacs distribution site.  Alternatively, they are available via CVS from cvs.xemacs.org.  Look at http://cvs.xemacs.org for instructions.

Prerequisites for Building Source Packages
------------------------------------------

You must have GNU cp, GNU install (or a BSD compatible install program) GNU make (3.75 or later preferred), makeinfo (1.68 from texinfo-3.11 or later required), GNU tar and XEmacs 21.0.  The source packages will untar into a correct directory structure.  At the top level you must have XEmacs.rules and package-compile.el.  These files are available from the XEmacs FTP site from the same place you obtained your source package distributions.

What You Can Do With Source Packages
------------------------------------

NB:  A global build operation doesn't exist yet as of 13 January 1998.

Source packages are most useful for creating XEmacs package tarballs for installation into your own XEmacs installations or for distributing to others.

Supported operations from make are:

clean
     Remove all built files except auto-autoloads.el and custom-load.el.

distclean
     Remove XEmacs backups as well as the files deleted by make clean.

all
     Bytecompile all files, build and bytecompile byproduct files like auto-autoloads.el and custom-load.el.  Create info version of TeXinfo documentation if present.

srckit
     Usually aliased to srckit-std.  This does a make distclean and creates a package source tarball in the staging directory.  This is generally only of use for package maintainers.

binkit
     May be aliased to binkit-sourceonly, binkit-sourceinfo, binkit-sourcedata, or binkit-sourcedatainfo. sourceonly indicates there is nothing to install in a data directory or info directory. sourceinfo indicates that source and info files are to be installed.  sourcedata indicates that source and etc (data) files are to be installed.  sourcedatainfo indicates source, etc (data), and info files are to be installed.  A few packages have needs beyond the basic templates so this is not yet complete.

dist
     Runs the rules srckit followed by binkit.  This is primarily of use by XEmacs maintainers producing files for distribution.

Creating a package from an existing Lisp library is not very difficult.

In addition to the Lisp libraries themselves, you need a package-info.in file and a simple Makefile.  The rest is done by XEmacs.rules, part of the packaging system infrastructure.

package-info.in contains a single Lisp form like this:

     (name                               ; your package's name
       (standards-version 1.1
        version VERSION
        author-version AUTHOR_VERSION
        date DATE
        build-date BUILD_DATE
        maintainer MAINTAINER
        distribution xemacs              ; change to "mule" if MULE is needed
        priority high
        category CATEGORY
        dump nil
        description "description"        ; a one-line description string
        filename FILENAME
        md5sum MD5SUM
        size SIZE
        provides (feature1 feature2)     ; one for every `provides' form
        requires (REQUIRES)
        type regular
     ))

You must fill in the four commented lines.  The value of name is the name of your package as an unquoted symbol.  Normally it is the name of the main Lisp file or principal feature provided.  The allowed values for distribution are xemacs and mule.  Write them as unquoted symbols.  The description is a quoted Lisp string; use the usual conventions.  The value for provides is a list of feature symbols (written unquoted).  All of the features provided by libraries in your package should be elements of this list.  Implementing an automatic method for generating the provides line is desirable, but as yet undone.

The variables in upper-case are references to variables set in the Makefile or automatically generated.  Do not change them; they are automatically filled in by the build process.

The remaining lines refer to implementation constants (standards-version), or features that are unimplemented or have been removed (priority and dump).  The type line is not normally relevant to external maintainers; the alternate value is single-file, which refers to packages consed up out of a number of single-file libraries that are more or less thematically related.  An example is prog-modes.  Single-file packages are basically for administrative convenience, and new packages should generally be created as regular packages.

The Makefile is quite stylized.  The idea is similar to an Imakefile or an automake file: the complexity is hidden in generic rules files, in this case the XEmacs.rules include file in the top directory of the packages hierarchy.  Although a number of facilities are available for complex libraries, most simple packages' Makefiles contain a copyright notice, a few variable definitions, an include for XEmacs.rules, and a couple of standard targets.

The first few make variables defined are VERSION, AUTHOR_VERSION, MAINTAINER, PACKAGE, PKG_TYPE, REQUIRES, and CATEGORY.  All but one were described in the description of package-info.in.  The last is an admistrative grouping.  Current categories include comm, games, libs, mule, oa, os, prog, and wp.  Available Packages, for a list of categories.

Next, define the variable ELCS.  This contains the list of the byte-compiled Lisp files used by the package.  These files and their .el versions will be included in the binary package.  If there are other files (such as extra Lisp sources or an upstream Makefile) that are normally placed in the installed Lisp directory, but not byte-compiled, they can be listed as the value of EXTRA_SOURCES.

The include is simply

     include ../../XEmacs.rules

The standard targets follow.  These are

     all:: $(ELCS) auto-autoloads.elc

     srckit: srckit-alias

     binkit: binkit-alias

Other targets (such as Texinfo sources) may need to be added as dependencies for the all target.  Dependencies for srckit and binkit (that is, values for SRCKIT-ALIAS and BINKIT-ALIAS) are defined in XEmacs.rules.  The most useful of these values are given in the following table.

srckit-alias
     Usually set to srckit-std.

binkit-alias
     May be set to binkit-sourceonly, binkit-sourceinfo, binkit-sourcedata, or binkit-sourcedatainfo.  sourceonly indicates there is nothing to install in a data directory or info directory. sourceinfo indicates that source and info files are to be installed.  sourcedata indicates that source and etc (data) files are to be installed.  sourcedatainfo indicates source, etc (data), and info files are to be installed.

Data files include things like pixmaps for a package-specific toolbar, and are normally installed in etc/PACKAGE_NAME.  A few packages have needs beyond the basic templates.  See XEmacs.rules or a future revision of this manual for details.

This section is surely out-of-date.  If you're sure that XEmacs is able to do something, but your installed XEmacs won't do it for you, it's probably in a package.  If you can't find it in this section, that's a bug---please report it.  It is very hard to keep this section up-to-date; your reports, comments, and questions will help a lot.

This data is up-to-date as of 10 February 1999.  (Ouch!  I told you!)

Library Packages (libs)
-----------------------

These packages are required to build and support most of the rest of XEmacs.  By design, xemacs-base is a `regular' package.  Use restraint when adding new files there as it is required by almost everything.

Sun
     Support for Sparcworks.

apel
     A Portable Emacs Library.  Used by XEmacs MIME support.

edebug
     A Lisp debugger.

dired
     The DIRectory EDitor is for manipulating, and running commands on files in a directory.

efs
     Treat files on remote systems the same as local files.

mail-lib
     Fundamental lisp files for providing email support.

tooltalk
     Support for building with Tooltalk.

xemacs-base
     Fundamental XEmacs support.  Install this unless you wish a totally naked XEmacs.

xemacs-devel
     XEmacs Lisp developer support.  This package contains utilities for supporting Lisp development.  It is a single-file package so it may be tailored.

Communications Packages (comm)
------------------------------

These packages provide support for various communications, primarily email and usenet.

footnote
     Footnoting in mail message editing modes.

gnats
     XEmacs bug reports.

gnus
     The Gnus Newsreader and Mailreader.

mailcrypt
     Support for messaging encryption with PGP.

mh-e
     Front end support for MH.

net-utils
     Miscellaneous Networking Utilities.  This is a single-file package and files may be deleted at will.

ph
     Emacs implementation of the ph client to CCSO/qi directory servers.

rmail
     An obsolete Emacs mailer.  If you do not already use it don't start.

supercite
     An Emacs citation tool.  Useful with all Emacs Mailers and Newsreaders.

tm
     Emacs MIME support.

vm
     An Emacs mailer.

w3
     A Web browser.

Games and Amusements (games)
----------------------------

cookie
     Spook and Yow (Zippy quotes).

games
     Tetris, Sokoban, and Snake.

mine
     Minehunt.

misc-games
     Other amusements and diversions.

Mule Support (mule)
-------------------

egg-its
     Wnn (4.2 and 6) support.  SJ3 support.  Must be installed prior to XEmacs build.

leim
     Quail.  Used for everything other than English and Japanese.

locale
     Used for localized menubars (French and Japanese) and localized splash screens (Japanese).

mule-base
     Basic Mule support.  Must be installed prior to building with Mule.

skk
     Another Japanese Language Input Method.  Can be used without a separate process running as a dictionary server.

Productivity Packages (oa)
--------------------------

calendar
     Calendar and diary support.

edit-utils
     Single file lisp packages for various XEmacs goodies.  Load this and weed out the junk you don't want.

forms
     Forms editing support (obsolete, use the builtin Widget instead).

frame-icon
     Provide a WM icon based on major mode.

hm--html-menus
     HTML editing.

ispell
     Spell-checking with ispell.

pc
     PC style interface emulation.

psgml
     Validated HTML/SGML editing.

sgml
     SGML/Linuxdoc-SGML editing.

slider
     User interface tool.

speedbar
     ??? Document me.

strokes
     Mouse enhancement utility.

text-modes
     Various single file lisp packages for editing text files.

time
     Display time & date on the modeline.

Operating System Utilities (os)
-------------------------------

eterm
     Terminal emulator.

igrep
     Enhanced front-end for Grep.

ilisp
     Front-end for Inferior Lisp.

os-utils
     Miscellaneous single-file O/S utilities, for printing, archiving, compression, remote shells, etc.

view-process
     A Unix process browsing tool.

Program Editing Support (prog)
------------------------------

ada
     Ada language support.

c-support
     Basic single-file add-ons for editing C code.

cc-mode
     C, C++ and Java language support.

debug
     GUD, gdb, dbx debugging support.

ediff
     Interface over patch.

emerge
     Another interface over patch.

pcl-cvs
     CVS frontend.

prog-modes
     Miscellaneous Lisp libraries for various programming languages.

scheme
     Front-end support for Inferior Scheme.

sh-script
     Support for editing shell scripts.

vc
     Version control for free systems.

vc-cc
     Version control for ClearCase.

vhdl
     Support for VHDL.

Word Processing (wp)
--------------------

auctex
     Basic TeX/LaTeX support.

crisp
     Crisp/Brief emulation.

edt
     DEC EDIT/EDT emulation.

texinfo
     XEmacs TeXinfo support.

textools
     Single-file TeX support.

tpu
     DEC EDIT/TPU support.

viper
     VI emulation support.