XEmacs 21.2.39 "Millennium".

[chise/xemacs-chise.git.1] / man / xemacs / packages.texi

@c This is part of the XEmacs manual.
@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
@c See file xemacs.texi for copying conditions.
@node Packages, Basic, Startup Paths, Top
@comment  node-name,  next,  previous,  up

@section Packages
@cindex 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.

@menu
* Package Terminology:: Understanding different kinds of packages.
* Using Packages::      How to install and use packages.
* Building Packages::   Building packages from sources.
* Creating Packages::   The basics.
* Available Packages::  A brief, out-of-date, directory of packaged LISP.
@end menu

@node Package Terminology, Using Packages, , Packages
@comment  node-name,  next,  previous,  up

@subsection Package Flavors

There are two main flavors of packages.

@itemize @bullet
@item Regular Packages
@cindex regular packages
A regular package is one in which multiple files are involved and one
may not in general safely remove any of them.

@item Single-File Packages
@cindex 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.
@end itemize

@subsection 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.

@subsection Binary Packages
@cindex binary packages
Binary packages may be installed directly into an XEmacs package
hierarchy.

@subsection Source Packages
@cindex 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).

@node Using Packages, Building Packages, Package Terminology, Packages
@comment  node-name,  next,  previous,  up

@subsection Getting Started

When you first download XEmacs 21, you will usually first grab the
@dfn{core distribution},
@cindex core distribution
a file called
@file{xemacs-21.0.tar.gz}. (Replace the @t{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
@file{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.

@subsection 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 @file{packages/binary-packages}.  Package file names follow
the naming convention @file{<package-name>-<version>-pkg.tar.gz}.

If you have EFS @ref{(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 @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 @code{Options} menu under:

@example
        Options->Customize->Emacs->Packages
@end example

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:

@example
        Options->Manage Packages->List & Install
@end example

Or, you can get to it via the keyboard:

@example
M-x pui-list-packages
@end example

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 @code{package-get-package-provider} function. Eg., if you know 
that you need @code{thingatpt}, type:

@example
M-x package-get-package-provider RET thingatpt
@end example

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

@subsection XEmacs and Installing Packages

Normally, packages are installed over the network, using EFS
@ref{(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:

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

@xref{Init File}.

Here, you'd change @file{/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 @code{package-get-remote} using:

@example
        M-x pui-add-install-directory
@end example

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 @ref{(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 @code{package-get-remote}.

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

@example
        Options->Manage Packages->List & Install
@end example
or
@example
        Options->Manage Packages->Using Custom->Select-> ...
@end example

You can also access it using the keyboard:

@example
M-x pui-list-packages
@end example

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 @kbd{?} to get
the same help.  From this buffer, you can tell the package status by the
character in the first column:

@table @kbd
@item -
The package has not been installed.
@item *
The package has been installed, but a newer version is available.  The
current version is out-of-date.
@item +
The package has been marked for installation/update.
@end table

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 @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from
the (Popup) Menu.
Once you've finished selecting the packages, you can
press the @kbd{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:

@table @kbd
@item ?
Display simple help.
@item @key{RET}
@itemx @key{Mouse-2}
Toggle between selecting and unselecting a package for installation.
@item x
Install selected packages.
@item @key{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.
@item v
Toggle between verbose and non-verbose package display.
@item g
Refresh the package display.
@item q
Kill the package buffer.
@end table

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

@subsection Other package installation interfaces

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

@example
        Options->Customize->Emacs->Packages-> ...
@end example
or
@example
        Options->Manage Packages->Using Custom->Select-> ...
@end example

Set their state to on, and then do:

@example
        Options->Manage Packages->Using Custom->Update Packages
@end example

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:

@example
M-x package-get-all <return>
@end example

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

@subsection 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 @file{$HOME} directory:

@example
~/.xemacs/mule-packages
~/.xemacs/xemacs-packages
@end example

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:

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

@item
Decide where to install the packages: in the system package
directory, or in @file{~/.xemacs/mule-packages} or
@file{~/.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 @file{$HOME}
directory, create the directory, @file{~/.xemacs/mule-packages} or
@file{~/.xemacs/xemacs-packages}, respectively.

@item
Next, @code{cd} to the directory under which you want to install the
package(s).

@item
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:

@example
        gunzip < package.tar.gz | tar xvf -
@end example

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

Of course, if you use GNU @code{tar}, you could also use:

@example
        tar xvzf package.tar.gz
@end example

@comment What about native MS Windows users???

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

@end enumerate

@node Building Packages, Creating Packages, Using Packages, Packages
@comment  node-name,  next,  previous,  up

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

@subsection Prerequisites for Building Source Packages

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

@subsection 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 @file{make} are:

@table @code
@item clean
Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.

@item distclean
Remove XEmacs backups as well as the files deleted by @code{make clean}.

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

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

@item binkit
May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
@code{binkit-sourcedata}, or
@code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is
nothing to install in a data directory or info directory.
@code{sourceinfo} indicates that source and info files are to be
installed.  @code{sourcedata} indicates that source and etc (data) files
are to be installed.  @code{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.

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

@end table

@node Creating Packages, Available Packages, Building Packages, Packages
@comment  node-name,  next,  previous,  up

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

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

@file{package-info.in} contains a single Lisp form like this:

@example
(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
))
@end example

You must fill in the four commented lines.  The value of @code{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 @code{xemacs} and @code{mule}.  Write them as
unquoted symbols.  The @code{description} is a quoted Lisp string; use
the usual conventions.  The value for @code{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 @file{provides} line is
desirable, but as yet undone.

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

The remaining lines refer to implementation constants
(@code{standards-version}), or features that are unimplemented or have
been removed (@code{priority} and @code{dump}).  The @code{type} line is
not normally relevant to external maintainers; the alternate value is
@code{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 @code{prog-modes}.  Single-file packages are basically for
administrative convenience, and new packages should generally be created
as regular packages.

The @file{Makefile} is quite stylized.  The idea is similar to an
@file{Imakefile} or an @code{automake} file: the complexity is hidden in
generic rules files, in this case the @file{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'
@file{Makefile}s contain a copyright notice, a few variable definitions,
an include for @file{XEmacs.rules}, and a couple of standard targets.

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

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

The include is simply
@example
include ../../XEmacs.rules
@end example

The standard targets follow.  These are

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

srckit: srckit-alias

binkit: binkit-alias
@end example

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

@table @var
@item srckit-alias
Usually set to @code{srckit-std}.

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

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

@node Available Packages,  , Creating Packages, Packages
@comment  node-name,  next,  previous,  up

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!)

@subsection 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.

@table @file
@item Sun
Support for Sparcworks.

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

@item edebug
A Lisp debugger.

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

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

@item mail-lib
Fundamental lisp files for providing email support.

@item tooltalk
Support for building with Tooltalk.

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

@item 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.
@end table

@subsection Communications Packages (comm)

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

@table @file
@item footnote
Footnoting in mail message editing modes.

@item gnats
XEmacs bug reports.

@item gnus
The Gnus Newsreader and Mailreader.

@item mailcrypt
Support for messaging encryption with PGP.

@item mh-e
Front end support for MH.

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

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

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

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

@item tm
Emacs MIME support.

@item vm
An Emacs mailer.

@item w3
A Web browser.
@end table

@subsection Games and Amusements (games)

@table @file
@item cookie
Spook and Yow (Zippy quotes).

@item games
Tetris, Sokoban, and Snake.

@item mine
Minehunt.

@item misc-games
Other amusements and diversions.
@end table

@subsection Mule Support (mule)

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

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

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

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

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

@subsection Productivity Packages (oa)

@table @file
@item calendar
Calendar and diary support.

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

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

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

@item hm--html-menus
HTML editing.

@item ispell
Spell-checking with ispell.

@item pc
PC style interface emulation.

@item psgml
Validated HTML/SGML editing.

@item sgml
SGML/Linuxdoc-SGML editing.

@item slider
User interface tool.

@item speedbar
??? Document me.

@item strokes
Mouse enhancement utility.

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

@item time
Display time & date on the modeline.
@end table

@subsection Operating System Utilities (os)

@table @file
@item eterm
Terminal emulator.

@item igrep
Enhanced front-end for Grep.

@item ilisp
Front-end for Inferior Lisp.

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

@item view-process
A Unix process browsing tool.
@end table

@subsection Program Editing Support (prog)

@table @file
@item ada
Ada language support.

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

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

@item debug
GUD, gdb, dbx debugging support.

@item ediff
Interface over patch.

@item emerge
Another interface over patch.

@item pcl-cvs
CVS frontend.

@item prog-modes
Miscellaneous Lisp libraries for various programming languages.

@item scheme
Front-end support for Inferior Scheme.

@item sh-script
Support for editing shell scripts.

@item vc
Version control for free systems.

@item vc-cc
Version control for ClearCase.

@item vhdl
Support for VHDL.
@end table

@subsection Word Processing (wp)

@table @file
@item auctex
Basic TeX/LaTeX support.

@item crisp
Crisp/Brief emulation.

@item edt
DEC EDIT/EDT emulation.

@item texinfo
XEmacs TeXinfo support.

@item textools
Single-file TeX support.

@item tpu
DEC EDIT/TPU support.

@item viper
VI emulation support.
@end table