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.

NOTE: For detailed information about how the package hierarchies work, see Package Overview (XEmacs Lisp Reference Manual).

Package Terminology:
====================

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.  However, we would recommend that you follow this rule of thumb: "When in doubt, don't delete".

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

XEmacs Lisp packages are distributed in two ways, depending on the intended use.  Binary Packages are for installers and end-users that can 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).

Currently, source packages are only available via CVS.  See http://cvs.xemacs.org/ for details.

Installing Packages:
====================

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

When you first download XEmacs 21, you will usually first grab the core distribution, a file called xemacs-21.x.x.tar.gz. (Replace the 21.x.x 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.  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 Available Packages at the time of the XEmacs release.

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:

     Tools -> Packages -> List and 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.08"). You can the use one of the methods above for installing the package you want.

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

There are three main ways to install packages:

But regardless of the method you use to install packages, they can only be used by XEmacs after a restart unless the package in question has not been previously installed.

Automatic Package Installation:
===============================

XEmacs comes with some tools to make the periodic updating and installing easier. It will notice if new packages or versions are available and will fetch them from the FTP site.

Unfortunately this requires that a few packages are already in place. You will have to install them by hand as above or use a SUMO tarball. This requirement will hopefully go away in the future. The packages you need are:

        efs          - To fetch the files from the FTP site or mirrors.
        xemacs-base  - Needed by efs.

     and optionally:

        mailcrypt    - To do PGP verification of the package-index
                       file.

After installing these by hand, fire up XEmacs and follow these steps.

 1. Choose a download site. via menu: Tools -> Packages -> Set Download Site via keyb: M-x customize-variable RET package-get-remote RET (put in the details of remote host and directory)

     If the package tarballs _AND_ the package-index file are in a local directory, you can: M-x pui-set-local-package-get-directory RET

 2. Obtain a list of packages and display the list in a buffer named *Packages*. menu: Tools -> Packages -> List & Install keyb: M-x pui-list-packages RET

     XEmacs will now connect to the remote site and download the latest package-index file.

     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 Mouse-3 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.  If you have balloon-help enabled a balloon-help frame will pop up and display additional package information also.

 3. Choose the packages you wish to install. mouse: Click button 2 on the package name. keyb: RET on the package name

 4. Make sure you have everything you need. menu: Packages -> Add Required keyb: r

     XEmacs will now search for packages that are required by the ones that you have chosen to install and offer to select those packages also.

     For novices and gurus alike, this step can save your bacon. It's easy to forget to install a critical package.

 5. Download and install the packages. menu: Packages -> Install/Remove Selected keyb: x

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 and install it and any packages that it depends upon.

Keeping Packages Up To Date:
============================

Once you have the packages you want installed (using any of the above methods) you'll want to keep them up to date.  You can do this easily from the menubar:

     Tools -> Packages -> Set Download Site
     Tools -> Packages -> Update Installed Packages

Manual Package Installation:
============================

Fetch the packages from the FTP site, CD-ROM whatever. The filenames have the form name-<version>-pkg.tar.gz and are gzipped tar files. For a fresh install it is sufficient to untar the file at the top of the package hierarchy.

NOTE: If you are upgrading packages already installed, it's best to remove the old package first Removing Packages.

For example if we are installing the xemacs-base package (version 1.48):

        mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet
        cd $prefix/lib/xemacs/xemacs-packages RET
        gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET

     Or if you have GNU tar, the last step can be:

        tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET

For MULE related packages, it is best to untar into the mule-packages hierarchy, i.e. for the mule-base package, version 1.37:

        mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet
        cd $prefix/lib/xemacs/mule-packages RET
        gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET

     Or if you have GNU tar, the last step can be:

        tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET

NOTE: For more detailed information about how the package hierarchies work, see Package Overview (XEmacs Lisp Reference Manual).

Installing the Sumo Packages:
=============================

Those with little time, cheap connections and plenty of disk space can install all the packages at once using the sumo tarballs. Download the file: xemacs-sumo.tar.gz

For an XEmacs compiled with Mule you also need: xemacs-mule-sumo.tar.gz

N.B. They are called 'Sumo Tarballs' for good reason. They are currently about 19MB and 4.5MB (gzipped) respectively.

Install them by:

cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET

Or, if you have GNU tar:

cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET

As the Sumo tarballs are not regenerated as often as the individual packages, it is recommended that you use the automatic package tools afterwards to pick up any recent updates.

Which Packages to Install:
==========================

This is difficult to say. When in doubt install a package. If you administrate a big site it might be a good idea to just install everything. A good minimal set of packages for XEmacs-latin1 would be

xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs, edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes, text-modes, time, mailcrypt

If you are using the XEmacs package tools, don't forget to do:

Packages -> Add Required

To make sure you have everything that the packages you have chosen to install need.

See also Available Packages for further descriptions of the individual packages.

Removing Packages:
==================

Because the exact files and their locations contained in a package may change it is recommended to remove a package first before installing a new version. In order to facilitate removal each package contains an pgkinfo/MANIFEST.pkgname file which list all the files belonging to the package.

No need to panic, you don't have to go through the pkinfo/MANIFEST.pkgname and manually delete the files.  Instead, use M-x package-get-delete-package RET.

Note that the interactive package tools included with XEmacs already do this for you.

Building Packages:
==================

Currently, source packages are only available via anonymous CVS.  See http://cvs.xemacs.org/ for details of checking out the xemacs-packages module.

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

GNU cp

GNU install
     (or a BSD compatible install program).

GNU make
     (3.75 or later preferred).

makeinfo
     (4.2 from GNU texinfo 4.2 or later required).

GNU tar
     (or equivalent).

GNU gzip
     (or equivalent).

A properly configured Local.rules file.
     Local.rules File.

And of course, XEmacs 21.0 or higher.

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

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

For a list and description of the different Makefile targets, see Makefile Targets (XEmacs Lisp Reference Manual).

The Local.rules File:
=====================

This file is used when building and installing packages from source.  In the top level of the CVS module, packages, contains the file, Local.rules.template.  Simply copy that to Local.rules and edit it to suit your needs.

For a complete discussion of the Local.rules file, see Local.rules File (XEmacs Lisp Reference Manual).

Available Packages:
===================

This section lists the Lisp packages that are currently available from xemacs.org and it's mirrors.  If a particular package that you are looking for isn't here, please send a message to the XEmacs Beta list.

This data is up to date as of June 27, 2003.

Normal Packages
---------------

A very broad selection of elisp packages.

Sun
     Support for Sparcworks.

ada
     Ada language support.

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

auctex
     Basic TeX/LaTeX support.

bbdb
     The Big Brother Data Base: a rolodex-like database program.

build
     Build XEmacs using custom widgets.

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

calc
     Emacs calculator.

calendar
     Calendar and diary support.

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

clearcase
     Support for the Clearcase version control system.

cookie
     "Fortune cookie"-style messages. Includes Spook (suspicious phrases) and Yow (Zippy quotes).

crisp
     Crisp/Brief emulation.

debug
     GUD, gdb, dbx debugging support.

dictionary
     Interface to RFC2229 dictionary servers.

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

docbookide
     DocBook editing support.

ecrypto
     Crypto functionality in Emacs Lisp.

edebug
     A Lisp debugger.

ediff
     Interface over patch.

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

edt
     DEC EDIT/EDT emulation.

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

eieio
     Enhanced Implementation of Emacs Interpreted Objects.

elib
     Portable Emacs Lisp utilities library.

emerge
     Another interface over patch.

eshell
     Command shell implemented entirely in Emacs Lisp.

ess
     ESS: Emacs Speaks Statistics.

eterm
     Terminal emulator.

eudc
     Emacs Unified Directory Client (LDAP, PH).

footnote
     Footnoting in mail message editing modes.

forms
     Forms editing support (obsolete, use the built-in Widget instead).

fortran-modes
     Fortran language support.

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

fsf-compat
     GNU Emacs compatibility files.

games
     Tetris, Sokoban, and Snake.

general-docs
     General documentation.  Presently, empty.

gnats
     XEmacs bug reports.

gnus
     The Gnus Newsreader and Mailreader.

haskell-mode
     Haskell language support.

hm--html-menus
     HTML editing.

ibuffer
     Advanced replacement for buffer-menu.

idlwave
     Editing and Shell mode for the Interactive Data Language.

igrep
     Enhanced front-end for Grep.

ilisp
     Front-end for interacting with Inferior Lisp (external lisps).

ispell
     Spell-checking with ispell.

jde
     Java language and development support.

liece
     IRC (Internet Relay Chat) client for Emacs.

mail-lib
     Fundamental lisp files for providing email support.

mailcrypt
     Support for messaging encryption with PGP.

mew
     Messaging in an Emacs World; a MIME-based email program.

mh-e
     Front end support for MH.

mine
     Elisp implementation of the game 'Minehunt'.

misc-games
     Other amusements and diversions.

mmm-mode
     Support for Multiple Major Modes within a single buffer.

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

ocaml
     Objective Caml editing support.

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

pc
     PC style interface emulation.

pcl-cvs
     CVS frontend.

pcomplete
     Provides programmatic completion.

perl-modes
     Perl language support.

pgg
     Emacs interface to various PGP implementations.

prog-modes
     Miscellaneous single-file lisp files for various programming languages.

ps-print
     Print buffers to PostScript printers.

psgml
     Validated HTML/SGML editing.

psgml-dtds
     A collection of DTDs for psgml.  Note that this package is deprecated and will be removed in the future, most likely Q2/2003.  Instead of using this, you should install needed DTDs yourself.

python-modes
     Python language support.

reftex
     Emacs support for LaTeX cross-references, citations.

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

ruby-modes
     Ruby language support.

sasl
     Simple Authentication and Security Layer (SASL) library.

scheme
     Front-end support for Inferior Scheme.

semantic
     Semantic bovinator.

sgml
     SGML/Linuxdoc-SGML editing.

sh-script
     Support for editing shell scripts.

sieve
     Manage Sieve email filtering scripts.

slider
     User interface tool.

sml-mode
     Standard ML editing support.

sounds-au
     XEmacs Sun sound files.

sounds-wav
     XEmacs Microsoft sound files.

speedbar
     Provides a separate frame with convenient references.

strokes
     Mouse enhancement utility.

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

texinfo
     XEmacs TeXinfo support.

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

textools
     Single-file TeX support.

time
     Display time & date on the modeline.

tm
     Emacs MIME support. Not needed for Gnus >= 5.8.0

tooltalk
     Support for building with Tooltalk.

tpu
     DEC EDIT/TPU support.

tramp
     Remote shell-based file editing.  This is similar to EFS or Ange-FTP, but works with rsh/ssh and rcp/scp.

vc
     Version Control for Free systems.

vc-cc
     Version Control for ClearCase.  This package will shortly be replaced with clearcase.el

vhdl
     Support for VHDL.

view-process
     A Unix process browsing tool.

viper
     VI emulation support.

vm
     An Emacs mailer.

w3
     A Web browser.

x-symbol
     Semi WYSIWYG for LaTeX, HTML, etc, using additional fonts.

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.

xslide
     XSL editing support.

xslt-process
     A minor mode for (X)Emacs which allows running an XSLT processor on a buffer.

zenirc
     ZENIRC IRC Client.

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

MULti-lingual Enhancement.  Support for world scripts such as Latin, Arabic, Cyrillic, Chinese, Japanese, Greek, Hebrew etc. To use these packages your XEmacs must be compiled with Mule support.

edict
     Lisp Interface to EDICT, Kanji Dictionary.

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

latin-unity
     Unify character sets in a buffer. When characters belong to disjoint character sets, this attempts to translate the characters so that they belong to one character set. If the buffer coding system is not sufficient, this suggests different coding systems.

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

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

lookup
     Dictionary support. (This isn't an English dictionary program)

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

mule-ucs
     Extended coding systems (including Unicode) for XEmacs.

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