XEmacs: Quickstart Package Guide

This text is intended to help you get started installing a new XEmacs and its packages from start. For details see the 'Startup Paths' and 'Packages' sections of the XEmacs info manual.

An overview of existing packages and their purpose may be found in the XEmacs 21 Packages CVS Repository document and under the XEmacs source tree in etc/PACKAGES.

Index

Real Real Quickstart FAQ

Q: Do I need to have the packages to compile XEmacs?
A: No.

Q: I really liked the old way that packages were bundled and do not want to mess with packages at all.
A: You can grab all the packages at once like you used to with old XEmacs versions, skip to the 'Sumo Tarball' section below. The win32 binary kit for Windows includes these Sumo packages as well.

A note of caution

The XEmacs package system is still being developed. Please expect a few minor hurdles on the way.

Some Package Theory

In order to reduce the size and increase the maintainability of XEmacs, the majority of the Elisp that came with previous releases have been unbundled. They have been replaced by the package system. Each elisp add-on (or groups of them when they are small) now comes in its own tarball that contains a small search hierarchy.

You select just the ones you need. Install them by untarring them into the right place. On startup XEmacs will find them, set up the load path correctly, install autoloads, etc, etc.

Package hierarchies

On startup XEmacs looks for packages in so called package hierarchies. These can be specified by the package-path parameter to the configure script.

However by default there are following three system wide hierarchies,

Local and 3rd party packages go here:

$prefix/lib/xemacs/site-packages

Only searched by MULE-enabled XEmacsen:

$prefix/lib/xemacs/mule-packages

Normal packages go here:

$prefix/lib/xemacs/xemacs-packages

Beta XEmacs (since 21.5.20 or so)

Package hierarchies go under $prefix/share/xemacs instead of $prefix/lib/xemacs.

where $prefix is the value of the prefix parameter to the configure script.

From within a running XEmacs you may type M-x describe-installation RET to find the value of Package path. M-x describe-variable RET configure-package-path RET will reveal the package path that was used to configure your XEmacs binary.

Packages for a native Windows build are also configured to be picked up in sub-directories site-packages, mule-packages, and xemacs-packages. However these are all relative to variable PACKAGE_PREFIX as defined in nt/xemacs.mak or on the nmake command line.

    ! if !defined(PACKAGE_PREFIX)
            PACKAGE_PREFIX=c:\Program Files\XEmacs
    ! endif
          

If you need to install XEmacs packages in places other than what configure-package-path defines, you may do so after setting the EMACSPACKAGEPATH environment variable.

Where to get the packages

Official XEmacs Packages:

These packages have received testing from XEmacs developers and bleeding-edge users and are available as documented in our Release Notice Archive.

Pre-Release XEmacs Packages:

These are the bleeding-edge packages made available as documented in our Release Notice Archive for testing purposes. Reporting Bugs is the best means to get any issues with these packages fixed.

Some package descriptions and links to other resources can be found on the XEmacs-related Packages page.

How to install the packages

Choose one of the following options:

1. All at once, using the 'Sumo Tarball'.
2. By hand.
3. Automatically, using the package tools from XEmacs.

The Sumo Tarball

Those with little time, cheap connections and plenty of disk space can install all packages at once using the Sumo tarballs. Download the file xemacs-sumo-<date>.tar.gz from the FTP site.

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

Note: They are called 'Sumo Tarballs' for good reason. They are currently about 21MB and 6MB (gzipped) respectively.

Install them by

Note: in recent beta XEmacs (since about 21.5) packages should be untarred in $prefix/share/xemacs, not $prefix/lib/xemacs.

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.

Installing by Hand

Note: in recent beta XEmacs (since about 21.5) both regular and MULE packages should be untarred in $prefix/share/xemacs/xemacs-packages and $prefix/share/xemacs/mule-packages, respectively.

Installing automatically

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:

After installing these by hand, you can start XEmacs. (It is a good idea to use 'xemacs -vanilla' here as your startup files might need things now moved to packages.)

• First you need to specify an FTP site to use. Use Tools->Packages->Set Download Site (or Options->Manage Packages->Add Download Site for XEmacs 21.1) in the menubar or type M-x customize-group RET package-get RET and customize package-get-remote. (You cannot use customize-variable as the variable is not known before loading the package code.)
  Alternatively, if you already have the packages on a local disk then you can specify this directly by typing M-x pui-add-install-directory. Please make sure you also have a corresponding copy of the package index there.
• Invoke Tools->Packages->List and Install (or Options->Manage Packages->List & Install for XEmacs 21.1) from the menubar or type M-x pui-list-packages RET. XEmacs will now first try to fetch a new version of the package index from the FTP site.
  • If you get the error message Error in process filter: (ftp-error FTP Error: ... 229 Entering Extended Passive Mode ..., your efs is too old and the index has not been updated, even though one is shown. Fetch and install an efs update by hand, as explained above. You don't need to worry about the currently installed efs; just unpack the efs package in your xemacs-packages directory.
    Now you need to terminate and start XEmacs again, to use the new code.
  • If you get the error message Error in process filter: (ftp-error FTP Error: ... 500 Unknown command ..., or any similar `500' error message, your index has not been updated either. Then you need to use a different XEmacs mirror: your ftp client sends extended commands that the server doesn't understand and efs does not handle the resulting error messages.
    You need to terminate and restart XEmacs before you can change a mirror.
  • You might be asked if an old package index shall be overwritten, or if an index shall be created in ~/.xemacs, maybe it will ask to create this directory. You will also be asked if you want to load the package database. Confirm all those questions.
  • When you have mailcrypt and GPG or PGP installed, XEmacs will try to verify the downloaded package index.
    • If you have GPG installed, you might get the error message Can't check signature: Public key 82EDF2C1D1DD84CD not found. (The key id might be different.) Then you don't have the public key of the person who signed the package index - at time of this writing, Norbert Koch.
      Enter the following command on the command line:

      gpg --keyserver hkp://wwwkeys.pgp.net --recv-key 82EDF2C1D1DD84CD

      (Of course, you need to use the public key id from XEmacs' error message in the gpg command.) You might get a warning that the HKP interface is experimental - don't worry, it works. Then comes the message that a public key got imported.
      If your command hangs, there might be several possibilites. One of the key servers might not be reachable; stop the command with Ctrl-C and issue it again. If it still hangs, your firewall might forbid outbound connections to the key servers. Then fetch http://ftp.xemacs.org/pgp-keys/norbert_koch.asc, save it to a file, and call gpg --import with that file.
      Update your package index, use Packages -> Update Package Index in the menubar or type M-x package-get-update-base RET. This time it'll finish with the message `Updated package database'.
    • If you get the message `The message was corrupt' and if you have the GPG key imported, try again updating the package index, maybe again another time. Sometimes, verification with GPG does not succeed for unknown reasons.
    • If you have PGP installed, confirm the question that keys shall be fetched.
    • If you still have problems with package index verification, use Customize to turn it off. By menu, that's Options -> Customize -> Emacs -> Package Tools -> Package Get -> Require Signed Base Updates. As command, type M-x customize-variable RET package-get-require-signed-base-updates RET. But this should be the last resort, as verifying downloads is an important security measure.
    • If you had any GPG or PGP problems, you have to restart this task item; list and install the packages again.
• XEmacs will show you a buffer named *Packages* with an overview of available and installed packages, including a short description. In this buffer you can select which packages you want by using the mouse or typing RET.
• When you are finished choosing packages, invoke Packages->Install/Remove Selected from the menubar or type x to begin installing packages.

After Installation

New packages can only be used by XEmacs after a restart.

Note to MULE users

It is a good idea to keep packages that are MULE-only separate by putting them in the mule-packages hierarchy. Non-Mule XEmacsen will ignore packages in mule-packages so it is safe to have that directory in the package path of a Non-Mule XEmacs.

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:

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

Unfortunately the package system currently provides neither dependencies nor conflicts. This will be a future enhancement. The above set includes most packages that are used by others.

As mentioned before, an overview of existing packages and their purpose may be found at ../Develop/packages.html and under the XEmacs source tree in etc/PACKAGES.

Upgrading/Removing Packages

As 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 a pkginfo/MANIFEST.pkgname file which lists all the files that belong to the package. The function package-admin-delete-binary-package can be used to remove a package; it uses the manifest information internally.

Note that the interactive package tools included with XEmacs already do this for you. It is recommended to use them unless you need to script the package upgrade/removal process.

User Package directories

In addition to the system wide packages, users can have their own packagee hierarchies (mule-packages and xemacs-packages) installed in ~/.xemacs. If you want to install packages there using the interactive tools, you need to set the variable 'pui-package-install-dest-dir' to ~/.xemacs yourself.

Site lisp/Site start

The site-packages hierarchy replaces the old site-lisp directory. XEmacs no longer looks into a site-lisp directly by default. A good place to put site-start.el would be in $prefix/lib/xemacs/site-packages/lisp/

Note: in recent beta XEmacs (since about 21.5) it is recommended you place site LISP in $prefix/share/xemacs/site-packages/lisp, not $prefix/lib/xemacs/site-packages/lisp.