* Installing Packages:: How to install packages.
* Building Packages:: Building packages from CVS sources.
* Local.rules File:: This is an important file that you must create.
-* Creating Packages:: The basics.
* Available Packages:: A brief directory of packaged LISP.
@end menu
There are two main flavors of packages.
@itemize @bullet
-@item
+@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
+@item
Single-File Packages
@cindex single-file packages
A single-file package is an aggregate collection of thematically
Currently, source packages are only available via CVS. See
@url{http://cvs.xemacs.org/} for details.
+
@node Installing Packages, Building Packages, Package Terminology, Packages
@comment node-name, next, previous, up
@cindex installing packages
subdirectory @file{packages}. Package file names follow
the naming convention @file{<package-name>-<version>-pkg.tar.gz}.
-If you have @ref{(EFS)}, packages can be installed over the network.
+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.
access it via the menus:
@example
- Tools -> Packages -> List and Install
+Tools -> Packages -> List and Install
@end example
Or, you can get to it via the keyboard:
@example
-M-x pui-list-packages
+@code{M-x pui-list-packages}
@end example
Hint to system administrators of multi-user systems: it might be a good
that you need @code{thingatpt}, type:
@example
-M-x package-get-package-provider RET thingatpt
+@code{M-x package-get-package-provider RET thingatpt}
@end example
-which will return something like (fsf-compat "1.08"). You can the use
+which will return something like @samp{(fsf-compat "1.08")}. You can the use
one of the methods above for installing the package you want.
@subsection XEmacs and Installing Packages
There are three main ways to install packages:
@menu
-* Sumo:: All at once, using the 'Sumo Tarball'.
-* Manually:: Using individual package tarballs.
* Automatically:: Using the package tools from XEmacs.
+* Manually:: Using individual package tarballs.
+* Sumo:: All at once, using the 'Sumo Tarball'.
* Which Packages:: Which packages to install.
* Removing Packages:: Removing packages.
@end menu
But regardless of the method you use to install packages, they can only
-be used by XEmacs after a restart.
-
-@node Sumo, Manually, ,Installing Packages
-@comment node-name, next, previous, up
-@cindex sumo package install
-@heading 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: @file{xemacs-sumo.tar.gz}
-
-For an XEmacs compiled with Mule you also need: @file{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:
-
-@code{cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET}
-
-Or, if you have GNU tar:
-
-@code{cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET}
+be used by XEmacs after a restart unless the package in question has not
+been previously installed.
-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.
-
-@node Manually, Automatically, Sumo, Installing Packages
-@comment node-name, next, previous, up
-@cindex manual package install
-@heading Manual Package Installation:
-Fetch the packages from the FTP site, CD-ROM whatever. The filenames
-have the form @file{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 @ref{Removing Packages}.
-
-For example if we are installing the @file{xemacs-base}
-package (version 1.48):
-
-@example
- 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
-@end example
-
-For MULE related packages, it is best to untar into the mule-packages
-hierarchy, i.e. for the @file{mule-base} package, version 1.37:
-
-@example
- 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
-@end example
-
-@node Automatically, Which Packages ,Manually, Installing Packages
+@node Automatically, Manually, ,Installing Packages
@comment node-name, next, previous, up
@cindex automatic package install
@cindex package tools
and optionally:
- mule-base - Needed if you want to use XEmacs with MULE.
+ mailcrypt - To do PGP verification of the @file{package-index}
+ file.
@end example
After installing these by hand, fire up XEmacs and follow these
steps.
@enumerate 1
-@item
+@item
Choose a download site.
-via menu: Tools -> Packages -> Add Download Site
+via menu: Tools -> Packages -> Set Download Site
via keyb: @code{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: @code{M-x pui-add-install-directory RET}
+local directory, you can: @code{M-x pui-set-local-package-get-directory RET}
-@item
+@item
Obtain a list of packages and display the list in a buffer named
@file{*Packages*}.
menu: Tools -> Packages -> List & Install
keyb: @code{M-x pui-list-packages RET}
XEmacs will now connect to the remote site and download the
-latest package-index file. If you see an error about the
-package-index entries not being PGP signed, you can safely
-ignore this because PGP has not been integrated into the XEmacs
-package tools yet.
+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
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.
+the Popup @kbd{Mouse-3} 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
@end table
Moving the mouse over a package will also cause additional information
-about the package to be displayed in the minibuffer.
+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.
-@item
+@item
Choose the packages you wish to install.
mouse: Click button 2 on the package name.
keyb: @kbd{RET} on the package name
-@item
+@item
Make sure you have everything you need.
menu: Packages -> Add Required
keyb: @kbd{r}
For novices and gurus alike, this step can save your bacon.
It's easy to forget to install a critical package.
-@item
+@item
Download and install the packages.
menu: Packages -> Install/Remove Selected
keyb: @kbd{x}
will search for the latest version and install it and any packages that
it depends upon.
-@node Which Packages, Removing Packages, Automatically, Installing Packages
+@heading 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:
+
+@example
+Tools -> Packages -> Set Download Site
+Tools -> Packages -> Update Installed Packages
+@end example
+
+
+@node Manually, Sumo, Automatically, Installing Packages
+@comment node-name, next, previous, up
+@cindex manual package install
+@heading Manual Package Installation:
+Fetch the packages from the FTP site, CD-ROM whatever. The filenames
+have the form @file{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 @ref{Removing Packages}.
+
+For example if we are installing the @file{xemacs-base}
+package (version 1.48):
+
+@example
+ 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
+@end example
+
+For MULE related packages, it is best to untar into the mule-packages
+hierarchy, i.e. for the @file{mule-base} package, version 1.37:
+
+@example
+ 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
+@end example
+
+@node Sumo, Which Packages, Manually, Installing Packages
+@comment node-name, next, previous, up
+@cindex sumo package install
+@heading 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: @file{xemacs-sumo.tar.gz}
+
+For an XEmacs compiled with Mule you also need: @file{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:
+
+@code{cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET}
+
+Or, if you have GNU tar:
+
+@code{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.
+
+@node Which Packages, Removing Packages, Sumo, Installing Packages
@comment node-name, next, previous, up
@cindex which packages
@cindex choosing packages
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
+text-modes, time, mailcrypt
If you are using the XEmacs package tools, don't forget to do:
@item GNU make
(3.75 or later preferred).
@item makeinfo
-(1.68 from texinfo-3.11 or later required).
+(4.2 from GNU texinfo 4.2 or later required).
@item GNU tar
(or equivalent).
@item GNU gzip
tarballs for installation into your own XEmacs installations or for
distributing to others.
-Supported operations from @file{make} are:
-
-@table @code
-@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 bindist
-Does a @code{make all} as well as create a binary package tarball in the
-staging directory.
-
-@item install
-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. And install everything into the
-staging directory.
-
-@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.
-
-@item clean
-Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.
-
-@item distclean
-Remove all created files.
-@end table
+For a list and description of the different @file{Makefile} targets,
+@xref{Makefile Targets,,,lispref}.
-@node Local.rules File, Creating Packages, Building Packages, Packages
+@node Local.rules File, Available Packages, Building Packages, Packages
@comment node-name, next, previous, up
@cindex local.rules
@heading The Local.rules File:
file, @file{Local.rules.template}. Simply copy that to
@file{Local.rules} and edit it to suit your needs.
-These are the variables in 'Local.rules' that you will need to
-address. Items that have default settings have those defaults shown.
-
-@table @var
-@item XEMACS = xemacs
-If your XEmacs isn't in your path, change this. Native MS Windows users
-should double quote this if the path has embedded spaces.
-
-@item BUILD_WITHOUT_MULE =
-Building from CVS defaults to building the Mule
-packages. Set this to 't' if you don't want/have Mule
-
-@item XEMACS_NATIVE_NT =
-Set this to 't' if you are building on WinNT. NT users should note that
-you still need the Cygwin environment to build the packages.
-
-@item XEMACS_INSTALLED_PACKAGES_ROOT = /usr/local/lib/xemacs
-This is the directory tree under which the installed packages go. Under
-this directory there would normally be @file{xemacs-packages/} for
-standard (non-Mule) packages, @file{mule-packages/} for Mule packages
-(if you built XEmacs with Mule), and possibly @file{site-packages/} for
-3rd party packages that aren't distributed by XEmacs.org.
-
-@item symlink =
-Set this to 't' if you want to do a "run in place".
-Setting this doesn't work well with 'make bindist'
-
-@item NONMULE_INSTALLED_PACKAGES_ROOT = $@{XEMACS_INSTALLED_PACKAGES_ROOT@}/xemacs-packages
-This is where the non-Mule packages are installed to. You probably
-don't want to change this.
-
-@item MULE_INSTALLED_PACKAGES_ROOT = $@{XEMACS_INSTALLED_PACKAGES_ROOT@}/mule-packages
-This is where the Mule packages are installed to. You probably don't
-want to change this. Please note that @code{make bindist} does
-@emph{not} use this variable. When doing a @code{make bindist}
-@emph{everything} goes into @var{NONMULE_INSTALLED_PACKAGES_ROOT}.
-
-@item NONMULE_PACKAGES = xemacs-packages
-This is where you set the non-Mule packages that you want to install. eg:
-@example
- XEMACS_PACKAGES = xemacs-packages/xemacs-base xemacs-packages/bbdb
-@end example
-
-@item MULE_PACKAGES = mule-packages
-Same as for 'XEMACS_PACKAGES' except you list the Mule
-packages you want to install here. eg:
-@example
- MULE_PACKAGES = mule-packages/mule-base mule-packages/skk
-@end example
-
-@item PACKAGE_INDEX = package-index
-If you want the package-index file to have a different
-name, change this.
+For a complete discussion of the @file{Local.rules} file,
+@xref{Local.rules File,,,lispref}.
-@item INSTALL = install -c
-The path to your BSD compatible install program.
-
-@item TAR = tar
-The path to your tar program
-
-@item BZIP2 =
-If you want bzip2 tarballs, set this.
-
-@item MAKEINFO = makeinfo
-The path to your makeinfo program
-@end table
-
-
-@node Creating Packages, Available Packages, Local.rules File, Packages
-@comment node-name, next, previous, up
-@cindex creating packages
-@heading Creating Packages:
-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" ; one-line period-terminated 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 first letter should be capitalized, and the
-string should end in a period. It need not be a complete sentence
-grammatically. 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
-administrative grouping. Current categories include @code{standard},
-and @code{mule}.
-
-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
+@node Available Packages, , Local.rules File, Packages
@comment node-name, next, previous, up
@cindex available packages
@cindex packages
looking for isn't here, please send a message to the
@email{xemacs-beta@@xemacs.org, XEmacs Beta list}.
-This data is up to date as of September 22, 2002.
+This data is up to date as of June 27, 2003.
@subsection Normal Packages
A very broad selection of elisp packages.
@item games
Tetris, Sokoban, and Snake.
+@item general-docs
+General documentation. Presently, empty.
+
@item gnats
XEmacs bug reports.
Miscellaneous Networking Utilities. This is a single-file package and
files may be deleted at will.
+@item ocaml
+Objective Caml editing support.
+
@item os-utils
Miscellaneous single-file O/S utilities, for printing, archiving,
compression, remote shells, etc.
-@item ocaml
-Objective Caml language support.
-
@item pc
PC style interface emulation.
@item perl-modes
Perl language support.
+@item pgg
+Emacs interface to various PGP implementations.
+
@item prog-modes
Miscellaneous single-file lisp files for various programming languages.
@item w3
A Web browser.
+@item x-symbol
+Semi WYSIWYG for LaTeX, HTML, etc, using additional fonts.
+
@item xemacs-base
Fundamental XEmacs support. Install this unless you wish a totally
naked XEmacs.