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 .emacs file:

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

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 make 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.