-@node Packages, Abbrevs, Running, Top
+@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 Introduction to XEmacs Packages
+@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 separately
-available. The installer as well as the user can choose which
+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 @emph
+@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 deleted at
+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
+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 and gzipped for space
+build distribution tarballs (Unix Tar format files, gzipped for space
savings).
-@subsection Prerequisites for building Source Packages
+@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),
available from the XEmacs FTP site from the same place you obtained your
source package distributions.
-@subsection What you can do with Source Packages
+@subsection What You Can Do With Source Packages
NB: A global build operation doesn't exist yet as of 13 January 1998.
for installation into your own XEmacs installations or for
distributing to others.
-Supported operations from Make are:
+Supported operations from @file{make} are:
@table @code
@item clean
of TeXinfo documentation if present.
@item srckit
-Usually aliased to @code{make srckit-std}. This does a @code{make
+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.
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
+
projects / chise / xemacs-chise.git- / blobdiff