2 Installation and Troubleshooting

This is part 2 of the XEmacs Frequently Asked Questions list. This section is devoted to Installation, Maintenance and Troubleshooting.

2.0: Installation (General)

Q2.0.1: How do I build and install XEmacs?

See the file `etc/NEWS' for information on new features and other user-visible changes since the last version of XEmacs.

The file `INSTALL' in the top-level directory says how to bring up XEmacs on Unix and Cygwin, once you have loaded the entire subtree of this directory.

See the file `nt/README' for instructions on building XEmacs for Microsoft Windows.

See section Q2.1.1: How do I install the packages?, for the installation of (essential) add on packages.

Q2.0.2: Where do I find external libraries?

All external libraries used by XEmacs can be found on the XEmacs web site http://www.xemacs.org/Download/optLibs.html.

The library versions available here are known to work with XEmacs. (Newer versions will probably work as well but we can't guarantee it.) We try to keep the libraries up-to-date but may not always succeed. Check the above page for the canonical locations of the external libraries, allowing you to download the latest, bleeding-edge versions.

Q2.0.3: How do I specify the paths that XEmacs uses for finding files?

You can specify what paths to use by using a number of different flags when running configure. See the section MAKE VARIABLES in the top-level file INSTALL in the XEmacs distribution for a listing of those flags.

Most of the time, however, the simplest fix is: do not specify paths as you might for GNU Emacs. XEmacs can generally determine the necessary paths dynamically at run time. The only path that generally needs to be specified is the root directory to install into. That can be specified by passing the --prefix flag to configure. For a description of the XEmacs install tree, please consult the `NEWS' file.

Q2.0.4: Running XEmacs without installing

How can I just try XEmacs without installing it?

XEmacs will run in place without requiring installation and copying of the Lisp directories, and without having to specify a special build-time flag. It's the copying of the Lisp directories that requires so much space. XEmacs is largely written in Lisp.

A good method is to make a shell alias for xemacs:

alias xemacs=/src/xemacs-21.5/src/xemacs

(You will obviously use whatever directory you downloaded the source tree to instead of `/src/xemacs-21.5').

This will let you run XEmacs without massive copying.

Q2.0.5: XEmacs is too big

The space required by the installation directories can be reduced dramatically if desired. Gzip all the .el files. Remove all the packages you'll never want to use. Remove the TexInfo manuals. Remove the Info (and use just hardcopy versions of the manual). Remove most of the stuff in etc. Remove or gzip all the source code. Gzip or remove the C source code. Configure it so that copies are not made of the support lisp.

These are all Emacs Lisp source code and bytecompiled object code. You may safely gzip everything named *.el here. You may remove any package you don't use. Nothing bad will happen if you delete a package that you do not use. You must be sure you do not use it though, so be conservative at first.

Any package with the possible exceptions of xemacs-base, and EFS are candidates for removal. Ask yourself, Do I ever want to use this package? If the answer is no, then it is a candidate for removal.

First, gzip all the .el files. Then go about package by package and start gzipping the .elc files. Then run XEmacs and do whatever it is you normally do. If nothing bad happens, then remove the package. You can remove a package via the PUI interface (M-x pui-list-packages, then press d to mark the packages you wish to delete, and then x to delete them.

Another method is to do M-x package-get-delete-package.

2.1: Package Installation

Q2.1.1: How do I install the packages?

There are three ways to install the packages.

1. Manually, all at once, using the 'Sumo Tarball'.
2. Manually, using individual package tarballs.
3. Automatically, using the package tools from XEmacs.

If you don't want to mess with the packages, it is easiest to just grab them manually, all at once. (For the other two ways, See section Q2.1.2: Can I install the packages individually?, and See section Q2.1.3: Can I install the packages automatically?.) Download the file

`xemacs-sumo.tar.gz'

For an XEmacs compiled with Mule you also need

`xemacs-mule-sumo.tar.gz'

These are in the `packages' directory on your XEmacs mirror archive: ftp://ftp.xemacs.org/pub/xemacs/packages or its mirrors. N.B. They are called 'Sumo Tarballs' for good reason. They are currently about 19MB and 4.5MB (gzipped) respectively.

Install them on Unix and Mac OS X using the shell/Terminal command

cd $prefix/share/xemacs ; gunzip -c <tarballname> | tar xf -

Where `$prefix' is what you gave to the `--prefix' flag to `configure', and defaults to `/usr/local'.

If you have GNU tar you can use:

cd $prefix/share/xemacs ; tar zxvf <tarballname>

If you have the packages somewhere nonstandard and don't want to bother with `$prefix' (for example, you're a developer and are compiling the packages yourself, and want your own private copy of everything), you can also directly specify this using `configure'. To do this with 21.5 and above use the `--with-late-packages' parameter to specify the directory under which you untarred the above tarballs. Under 21.4 and previous you need to use `--package-path'. Using these options looks something like this:

   configure --package-path="~/.xemacs::/src/xemacs/site-packages:/src/xemacs/xemacs-packages:/src/xemacs/mule-packages" ...

Under Windows, you need to place the above `tar.gz' files in the directory specified using the `PACKAGE_PREFIX' value in `nt/config.inc' and by default is `\Program Files\XEmacs'. (To untar a `tar.gz' file you will need to use a utility such as WinZip, unless you have Cygwin or a similar environment installed, in which case the above Unix shell command should work fine.) If you want the packages somewhere else, just change `PACKAGE_PREFIX'.

Note that XEmacs finds the packages automatically anywhere underneath the directory tree where it expects to find the packages. All you need to do is put stuff there; you don't need to run any program to tell XEmacs to find the packages, or do anything of that sort.

However, XEmacs will only notice newly installed packages when it starts up, so you will have to restart if you are already running XEmacs.

For more details, See section `Startup Paths' in the XEmacs User's Manual, and See section `Packages' in the XEmacs User's Manual.

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.

NOTE: For detailed information about how the package hierarchies work, See section `Package Overview' in the XEmacs Lisp Reference Manual.

Q2.1.2: Can I install the packages individually?

Yes, you can download individual packages from the FTP site (see section Q2.1.1: How do I install the packages?). Since packages are automatically noticed at startup, you just have to put them in the right place.

Note: If you are upgrading packages already installed, it's best to remove the old package first (see section Q2.1.4: Can I upgrade or remove packages?).

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

   mkdir $prefix/share/xemacs/xemacs-packages RET # if it does not exist yet
   cd $prefix/share/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/share/xemacs/mule-packages RET # if it does not exist yet
   cd $prefix/share/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

Q2.1.3: Can I install the packages 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:

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

and optionally:

   mailcrypt    - For 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 resulting buffer, "*Packages*" has brief instructions at the end of the buffer.

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

Q2.1.4: Can I upgrade or remove 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 belonging to the package. M-x package-admin-delete-binary-package RET can be used to remove a package using this file.

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

Q2.1.5: Which packages to install?

Unless you are an advanced user, just install everything.

If you really want to install only what's absolutely needed, 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 section Q1.7.2: Which external packages are there?, for a description of the various packages.

Q2.1.6: Can you describe the package location process in more detail?

On startup XEmacs looks for packages in so-called package hierarchies. Normally, there are three system wide hierarchies, like this:

$prefix/sahre/xemacs/xemacs-packages/
     Normal packages go here.

$prefix/share/xemacs/mule-packages/
     Mule packages go here and are only searched by MULE-enabled XEmacsen.

$prefix/share/xemacs/site-packages/
     Local and 3rd party packages go here.

This is what you get when you untar the SUMO tarballs under `$prefix/share/xemacs'.

`$prefix' is specified using the `--prefix' parameter to `configure', and defaults to `usr/local'.

If the package path is not explicitly specified, XEmacs looks for the package directory `xemacs-packages' (and `mule-packages' and `site-packages') first under `~/.xemacs', then for a sister directory `lib/xemacs-VERSION' of the directory in which the XEmacs executable is located, then for a sister directory `lib/xemacs'. The XEmacs executable (under Unix at least) is installed by default in `/usr/local/bin'; this explains why XEmacs in its default installation will find packages that you put under `/usr/local/share/xemacs'.

You can specify where exactly XEmacs looks for packages by using the `--with-user-packages' (an alias for `--with-early-packages') or `--with-system-packages' (an alias for `--with-late-packages') or `--with-legacy-packages' (an alias for `--with-last-packages') parameters to `configure' (or the equivalent settings in `config.inc', under Windows), or setting the `EMACSEARLYPACKAGES', `EMACSLATEPACKAGES', and `EMACSLASTPACKAGES' environment variables (which have the same format as the configure options). See section Q2.1.1: How do I install the packages?.

See `configure.usage' for more info about the format of these `configure' parameters.

In addition to the system wide packages, each user can have his own packages installed under `~/.xemacs/'. If you want to install packages there using the interactive tools, you need to set package-get-install-to-user-init-directory to t.

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/share/xemacs/site-packages/lisp/'.

Q2.1.7: EFS fails with "500 AUTH not understood" (NEW)

A typical error: FTP Error: USER request failed; 500 AUTH not understood.

Thanks to Giacomo Boffi giacomo.boffi@polimi.it who recommends on comp.emacs.xemacs:

tell your ftp client to not attempt AUTH authentication (or do not use FTP servers that don't understand AUTH)

and notes that you need to add an element (often "-u") to `efs-ftp-program-args'. Use M-x customize-variable, and verify the needed flag with `man ftp' or other local documentation.

2.2: Unix/Mac OS X Installation (Also Relevant to Cygwin, MinGW)

Q2.2.1: Libraries in non-standard locations

If your libraries are in a non-standard location, you can specify the location using the following flags to `configure'. Under 21.4 or earlier:

--site-libraries=WHATEVER
--site-includes=WHATEVER

Under 21.5 or later:

--with-site-libraries=WHATEVER
--with-site-includes=WHATEVER

If you have multiple paths to specify, use the following syntax:

--site-libraries='/path/one /path/two /path/etc'

If the libraries and headers reside in the directories `lib' and `include' of a common root (say `/sw') then both can be specified with a single option:

--site-prefixes=WHATEVER

or for 21.5:

--with-site-prefixes=WHATEVER

Q2.2.2: Why can't I strip XEmacs?

Richard Cognot writes:

Because of the way XEmacs (and every other Emacsen, AFAIK) is built. The link gives you a bare-boned emacs (called temacs). temacs is then run, preloading some of the lisp files. The result is then dumped into a new executable, named xemacs, which will contain all of the preloaded lisp functions and data.

Now, during the dump itself, the executable (code+data+symbols) is written on disk using a special unexec() function. This function is obviously heavily system dependent. And on some systems, it leads to an executable which, although valid, cannot be stripped without damage. If memory serves, this is especially the case for AIX binaries. On other architectures it might work OK.

The Right Way to strip the emacs binary is to strip temacs prior to dumping xemacs. This will always work, although you can do that only if you install from sources (as temacs is `not' part of the binary kits).

Nat Makarevitch writes:

Here is the trick:

1. [ ./configure; make ]

2. rm src/xemacs

3. strip src/temacs

4. make

5. cp src/xemacs /usr/local/bin/xemacs

6. cp lib-src/DOC-19.16-XEmacs /usr/local/lib/xemacs-19.16/i586-unknown-linuxaout

Q2.2.3: X11/bitmaps/gray (or other X11-related file) not found.

The X11R6 distribution was monolithic, but the X11R7 distribution is much more modular. Many OS distributions omit these bitmaps (assuming nobody uses them, evidently). Your OS distribution should have a developer's package containing these files, probably with a name containing the string "bitmap". Known package names (you may need to add an extension such as .deb or .rpm) include x11/xbitmaps (Ubuntu) and xorg-x11-xbitmaps (Fedora Core 5).

2.3: Windows Installation (Windows, Cygwin, MinGW)

Q2.3.1: What exactly are all the different ways to build XEmacs under Windows?

XEmacs can be built in several ways in the MS Windows environment.

The standard way is what we call the "native" port. It uses the Win32 API and has no connection with X whatsoever -- it does not require X libraries to build, nor does it require an X server to run. The native port is the most reliable version and provides the best graphical support. Almost all development is geared towards this version, and there is little reason not to use it.

The second way to build is the Cygwin port. It takes advantage of Cygnus emulation library under Win32. See section and do I need them to run XEmacs?, for more information.

A third way is the MinGW port. It uses the Cygwin environment to build but does not require it at runtime. See section and do I need them to run XEmacs?, for more information.

Finally, you might also be able to build the non-Cygwin, non-MinGW "X" port. This was actually the first version of XEmacs that ran under MS Windows, and although the code is still in XEmacs, it's essentially orphaned and it's unlikely it will compile without a lot of work. If you want an MS Windows versin of XEmacs that supports X, use the Cygwin version. (The X support there is actively maintained, so that Windows developers can test the X support in XEmacs.)

Q2.3.2: What compiler/libraries do I need to compile XEmacs?

You need Visual C++ 4.2, 5.0, or 6.0 for the native version. (We have some beta testers currently trying to compile with VC.NET, aka version 7.0, but we can't yet report complete success.) For the Cygwin and MinGW versions, you need the Cygwin environment, which comes with GCC, the compiler used for those versions. See section and do I need them to run XEmacs?, for more information on Cygwin and MinGW.

Q2.3.3: How do I compile the native port?

Please read the file `nt/README' in the XEmacs distribution, which contains the full description.

Q2.3.4: What do I need for Cygwin?

You can find the Cygwin tools and compiler at:

http://www.cygwin.com/

Click on the `Install or update now!' link, which will download a file `setup.exe', which you can use to download everything else. (You will need to pick a mirror site; `mirrors.rcn.net' is probably the best.) You should go ahead and install everything -- you'll get various ancillary libraries that XEmacs needs or likes, e.g. XPM, PNG, JPEG, TIFF, etc. You can also get X Windows here, if you want to compile under X.

If you want to compile without X, you will need the `xpm-nox' library, which must be specifically selected in the Cygwin netinstaller; it is not selected by default. The package has had various names. Currently it is called `cygXpm-noX4.dll'.

Q2.3.5: How do I compile under Cygwin?

Similar as on Unix; use the usual `configure' and `make' process. Some problems to watch out for:

• make sure HOME is set. This controls where you `init.el' file comes from;

• `CYGWIN' needs to be set to `tty' for process support to work;

• picking up some other grep or other UNIX-like tools can kill configure;

• static heap too small, adjust `src/sheap-adjust.h' to a more positive number;

• (Unconfirmed) The Cygwin version doesn't understand `//machine/path' type paths so you will need to manually mount a directory of this form under a unix style directory for a build to work on the directory;

• If you're building WITHOUT X11, don't forget to change symlinks `/usr/lib/libXpm.a' and `/usr/lib/libXpm.dll.a' to point to the non-X versions of these libraries. By default they point to the X versions. So:

  /usr/lib/libXpm.a -> /usr/lib/libXpm-noX.a /usr/lib/libXpm.dll.a -> /usr/lib/libXpm-noX.dll.a

  (This advice may now be obsolete because of the availability of the cygXpm-noX4.dll package from Cygwin. Send confirmation to faq@xemacs.org.)

• Other problems are listed in the `PROBLEMS' file, in the top-level directory of the XEmacs sources.

Q2.3.6: How do I compile using MinGW (aka `the -mno-cygwin flag to gcc')?

Similar to the method for Unix. Things to remember:

• Specify the target host on the command line for `./configure', e.g. `./configure i586-pc-mingw32'.

• Be sure that your build directory is mounted such that it has the same path either as a cygwin path (`/build/xemacs') or as a Windows path (`c:\build\xemacs').

• Build `gcc -mno-cygwin' versions of the extra libs, i.e. `libpng', `compface', etc.

• Specify the target location of the extra libs on the command line to `configure', e.g.for 21.4 or earlier `./configure --site-prefixes=/build/libs i586-pc-mingw32' and for 21.5 or later `./configure --with-site-prefixes=/build/libs i586-pc-mingw32'.

Q2.3.7: How do I compile with X support?

To compile under Cygwin, all you need to do is install XFree86, which is available as part of the standard Cygwin installation. http://www.cygwin.com/. Once installed, `configure' should automatically find the X libraries and compile with X support.

As noted above, the non-Cygwin X support is basically orphaned, and probably won't work. But if it want to try, it's described in `nt/README' in some detail. Basically, you need to get X11 libraries from http://ftp.x.org, and compile them. If the precompiled versions are available somewhere, we don't know of it.

Q2.3.8: Cygwin XEmacs won't start -- cygXpm-noX4.dll was not found (NEW)

The Cygwin binary distributed with the netinstaller uses an external DLL to handle XPM images (such as toolbar buttons). You may get an error like

This application has failed to start because cygXpm-noX4.dll was not found.
Re-installing the application may fix this problem.

Andy Piper <andy@xemacs.org> sez:

cygXpm-noX4 is part of the cygwin distribution under libraries or
graphics, but is not installed by default. You need to run the
cygwin setup again and select this package.

Ie, reinstalling XEmacs won't help because it is not part of the XEmacs distribution.

2.4: General Troubleshooting

Q2.4.1: How do I deal with bugs or with problems building, installing, or running?

The file `PROBLEMS' contains information on many common problems that occur in building, installing and running XEmacs.

Reports of bugs in XEmacs should be sent to xemacs-beta@xemacs.org. You can also post to the newsgroup comp.emacs.xemacs (or equivalentlt, send to the mailing list xemacs@xemacs.org), but it is less likely that the developers will see it in a timely fashion. See section `Bugs' in the XEmacs User's Manual, for more information on how to report bugs. See section Q1.4.2: Which mailing lists are there?, for more information on mailing lists relating to XEmacs.

There are three ways to read the Bugs section.

1. In a printed copy of the XEmacs manual.

2. With Info. First, start XEmacs. From the menu, select `Help->Info (Online Docs)->Info Contents' to enter Info, then click on `XEmacs', then on `Bugs'. Or, use the keyboard: do C-h i to enter Info, then m XEmacs RET to get to the Emacs manual, then m Bugs RET to get to the section on bugs. Or use standalone Info in a like manner. (Standalone Info is part of the Texinfo distribution, not part of the XEmacs distribution.)

3. By hand. Do

   cat info/xemacs* | more "+/^File: xemacs.info, Node: Bugs,"

Q2.4.2: Help! XEmacs just crashed on me!

First of all, don't panic. Whenever XEmacs crashes, it tries extremely hard to auto-save all of your files before dying. (The main time that this will not happen is if the machine physically lost power or if you killed the XEmacs process using kill -9). The next time you try to edit those files, you will be informed that a more recent auto-save file exists. You can use M-x recover-file to retrieve the auto-saved version of the file.

You can use the command M-x recover-session after a crash to pick up where you left off.

Now, XEmacs is not perfect, and there may occasionally be times, or particular sequences of actions, that cause it to crash. If you can come up with a reproducible way of doing this (or even if you have a pretty good memory of exactly what you were doing at the time), the maintainers would be very interested in knowing about it. The best way to report a bug is using M-x report-emacs-bug (or by selecting `Send Bug Report...' from the Help menu). If that won't work (e.g. you can't get XEmacs working at all), send ordinary mail to xemacs-beta@xemacs.org. MAKE SURE to include the output from the crash, especially including the Lisp backtrace, as well as the XEmacs configuration from M-x describe-installation (or equivalently, the file `Installation' in the top of the build tree). Note that the developers do not usually follow `comp.emacs.xemacs' on a regular basis; thus, this is better for general questions about XEmacs than bug reports.

If at all possible, include a C stack backtrace of the core dump that was produced. This shows where exactly things went wrong, and makes it much easier to diagnose problems. To do this under Unix and Mac OS X, you need to locate the core file (it's called `core', and is usually sitting in the directory that you started XEmacs from, or your home directory if that other directory was not writable). Then, go to that directory and execute a command like:

gdb `which xemacs` core

and then issue the command `where' to get the stack backtrace. You might have to use dbx or some similar debugger in place of gdb. If you don't have any such debugger available, complain to your system administrator.

It's possible that a core file didn't get produced or the stack trace from gdb is garbage, in which case you're out of luck unless you can reproduce the bug. A nonexistent core file can happen in some circumstances on some operating systems, depending on what exactly triggered the crash. It's also possible, however, that your limits are set to turn them off. You may be able to reenable them using a command like `unlimit coredumpsize' or `ulimit -c'. (To find out how your limits are set, use the command `limit'.) However, if you didn't explicitly set your limits this way, go complain to your system administrator and tell him not to disable core files by default.

A garbaged stack trace can happen for various reasons. Some versions of gdb are broken on certain operating systems and aren't able to read the core file. It's also possible that the stack got overwritten during the crash. A very simple reason, however, is that your version of XEmacs was compiled without debugging information or had the debugging information stripped. A compilation with optimization can also result in partly or completely garbaged stack trace. In such cases, you will need to recompile XEmacs with debugging information and without optimization; See section How to debug an XEmacs problem with a debugger. Note also that core files currently don't work at all under Cygwin, and the only way to get a backtrace is to run XEmacs from gdb.

If you cannot get a backtrace from the core dump, but can reproduce the problem, try running XEmacs under gdb. The goal is to get clean C and Lisp backtraces and submit a bug report including full configuration information as described above, as this will greatly assist in the process of tracking down the bug. However, even partial information is better than none. The process of getting backtraces from gdb is described in detail in How to debug an XEmacs problem with a debugger.

If you're under Microsoft Windows, you're out of luck unless you happen to have a debugging aid installed on your system, for example Visual C++. In this case, the crash will result in a message giving you the option to enter a debugger (for example, by pressing `Cancel'). Do this and locate the stack-trace window. (If your XEmacs was built without debugging information, the stack trace may not be very useful.)

When making a problem report make sure that:

1. Report all of the information output by XEmacs during the crash.

2. You mention what O/S and Hardware you are running XEmacs on.

3. What version of XEmacs you are running.

4. What build options you are using.

5. If the problem is related to graphics and you are running Unix or Mac OS X, we will also need to know what version of the X Window System you are running, and what window manager you are using.

6. If the problem happened on a TTY, please include the terminal type.

7. Try very hard to get both C and Lisp backtraces, as described above.

Much of the information above is automatically generated by M-x report-emacs-bug. Even more, and often useful, information can be generated by redirecting the output of make and make check to a file (`beta.err' is the default used by build-report), and executing M-x build-report.

Q2.4.3: XEmacs crashes and I compiled it myself.

There have been a variety of reports of crashes due to compilers with buggy optimizers. If you are compiling with optimization, consider turning it off (see section How to debug an XEmacs problem with a debugger) and recompiling.

Please see the `PROBLEMS' file that comes with XEmacs (it's in the top-level source directory) to read what it says about your platform.

If you compiled XEmacs 21.4 or earlier using `--use-union-type', or 21.5 or later using `--enable-union-type' (or in either case used the option `USE_UNION_TYPE' in `config.inc' under Windows), try recompiling again without it. The union type has been known to trigger compiler errors in a number of cases.

Q2.4.4: How to debug an XEmacs problem with a debugger

If XEmacs does crash on you, one of the most productive things you can do to help get the bug fixed is to poke around a bit with the debugger. Here are some hints:

• First of all, if the crash is at all reproducible, consider very strongly recompiling your XEmacs with debugging symbols and with no optimization (e.g. with GCC use the compiler flags `-g -O0' -- that's an "oh" followed by a zero), and with the configure options `--debug=yes' and `--error-checking=all' (`--enable-debug=yes' and `--enable-error-checking=all' on XEmacs 21.5 or later). This will make your XEmacs run somewhat slower, but you are a lot more likely to catch the problem earlier (closer to its source). It makes it a lot easier to determine what's going on with a debugger. The way to control the compiler flags is with the configuration option `--cflags' (`--with-cflags' in 21.5). If you have a recent version of 21.5, you should use `--without-optimization' in preference to directly setting `--cflags'.

• If it's not a true crash (i.e., XEmacs is hung, or a zombie process), or it's inconvenient to run XEmacs again because XEmacs is already running or is running in batch mode as part of a bunch of scripts, you may be able to attach to the existing process with your debugger. Under Unix and Mac OS X, the typical way to do this is to first use some variant of the `ps' command to figure out the process ID of XEmacs, for example `ps -auxww | grep xemacs' under a BSD variant, `ps -elf | grep xemacs' under Linux or System V, or `ps -aW | grep xemacs' under Cygwin. Then run

  gdb /path/to/xemacs/xemacs ####

  Where #### is the process id of your XEmacs. (If you're not sure, try using `which xemacs'.) When gdb attaches, the xemacs will stop and you can type `where' in gdb to get a stack trace as usual. To get things moving again, you can just type `quit' in gdb. It'll tell you the program is running and ask if you want to quit anyways. Say `y' and it'll quit and have your emacs continue from where it was at.

  If you're running another debugger, a similar method may work, or you may have to run the debugger first and then use the attach command or something similar.

  Under Microsoft Windows, use the menu item `Build->Start Debug->Attach to Process...' and select the XEmacs process from the list given.

• If you're able to run XEmacs under a debugger and reproduce the crash, here are some things you can do:

• If XEmacs is hitting an assertion failure, put a breakpoint on assert_failed().

• If XEmacs is hitting some weird Lisp error that's causing it to crash (e.g. during startup), put a breakpoint on signal_1()---this is declared static in `eval.c'.

• If XEmacs is outputting lots of X errors, put a breakpoint on x_error_handler(); that will tell you which call is causing them. Note that the result may not be very useful by default because X Windows normally operates asynchronously: A bunch of commands are buffered up and then sent to the server all at once. This greatly improves performance over a network but means that an error may not be reported until the server receives the commands, which can be long after XEmacs made the erroneous calls. For best results, you need to make the X server synchronous before getting the backtrace. This can be done by starting XEmacs with the `-sync' option or executing the Lisp code (x-debug-mode t).

• Internally, you will probably see lots of variables that hold objects of type Lisp_Object. These are references to Lisp objects. Printing them out with the debugger probably won't be too useful--you'll likely just see a number. To decode them, do this:

  call debug_print (OBJECT)

  where OBJECT is whatever you want to decode (it can be a variable, a function call, etc.). This uses the Lisp printing routines to out a readable representation on the TTY from which the xemacs process was invoked.

  Under 21.5 and later, dp is defined as an easier-to-type equivalent of debug_print. You can also try dpa if you can't see the output from debug_print (this will return a string containing the output), or use debug_p3 if debug_print itself triggers a crash (this is a less comprehensive but super-safe way to print out a Lisp object).

• If you want to get a Lisp backtrace showing the Lisp call stack, do this:

  call debug_backtrace ()

  Under 21.5 and later, db is defined as an easier-to-type equivalent of debug_backtrace.

• Using debug_print and debug_backtrace has two disadvantages - they can only be used with a running (including hung or zombie) xemacs process, and they do not display the internal C structure of a Lisp Object. Even if all you've got is a core dump, all is not lost.

  If you're using GDB, there are some macros in the file `src/.gdbinit' in the XEmacs source distribution that should make it easier for you to decode Lisp objects. This file is automatically read by gdb if gdb is run in the directory where xemacs was built, and contains these useful macros to inspect the state of xemacs:

  pobj

  Usage: pobj lisp_object
  Print the internal C representation of a lisp object.

  xtype

  Usage: xtype lisp_object
  Print the Lisp type of a lisp object.

  lbt

  Usage: lbt
  Print the current Lisp stack trace. Requires a running xemacs process. (It works by calling the db routine described above.)

  ldp

  Usage: ldp lisp_object
  Print a Lisp Object value using the Lisp printer. Requires a running xemacs process. (It works by calling the dp routine described above.)

  run-temacs

  Usage: run-temacs
  Run temacs interactively, like xemacs. Use this with debugging tools (like purify) that cannot deal with dumping, or when temacs builds successfully, but xemacs does not.

  dump-temacs

  Usage: dump-temacs
  Run the dumping part of the build procedure. Use when debugging temacs, not xemacs! Use this when temacs builds successfully, but xemacs does not.

  check-xemacs

  Usage: check-xemacs
  Run the test suite. Equivalent to 'make check'.

  check-temacs

  Usage: check-temacs
  Run the test suite on temacs. Equivalent to 'make check-temacs'. Use this with debugging tools (like purify) that cannot deal with dumping, or when temacs builds successfully, but xemacs does not.

  If you are using Sun's `dbx' debugger, there is an equivalent file `src/.dbxrc', which defines the same commands for dbx.

• If you're using a debugger to get a C stack backtrace and you're seeing stack traces with some of the innermost frames mangled, it may be due to dynamic linking. (This happens especially under Linux.) Consider reconfiguring with `--dynamic=no' (`--with-dynamic=no' in 21.5 or later). Also, sometimes (again under Linux), stack backtraces of core dumps will have the frame where the fatal signal occurred mangled; if you can obtain a stack trace while running the XEmacs process under a debugger, the stack trace should be clean.

  Curtiss suggests upgrading to ld.so version 1.8 if dynamic linking and debugging is a problem on Linux.

• If you're using a debugger to get a C stack backtrace and you're getting a completely mangled and bogus stack trace, it's probably due to one of the following:
  1. Your executable has been stripped. Bad news. Tell your sysadmin not to do this--it doesn't accomplish anything except to save a bit of disk space, and makes debugging much much harder.

  2. Your stack is getting trashed. Debugging this is hard; you have to do a binary-search type of narrowing down where the crash occurs, until you figure out exactly which line is causing the problem. Of course, this only works if the bug is highly reproducible. Also, in many cases if you run XEmacs from the debugger, the debugger can protect the stack somewhat. However, if the stack is being smashed, it is typically the case that there is a wild pointer somewhere in the program, often quite far from where the crash occurs.

  3. If your stack trace has exactly one frame in it, with address 0x0, this could simply mean that XEmacs attempted to execute code at that address, e.g. through jumping to a null function pointer. Unfortunately, under those circumstances, GDB under Linux doesn't know how to get a stack trace. (Yes, this is the fourth Linux-related problem I've mentioned. I have no idea why GDB under Linux is so bogus. Complain to the GDB authors, or to comp.os.linux.development.system.) Again, you'll have to use the narrowing-down process described above.

  4. You will get a Lisp backtrace output when XEmacs crashes, so you'll have something useful.

• If you compile with the newer gcc variants gcc-2.8 or egcs, you will also need gdb 4.17 or above. Earlier releases of gdb can't handle the debug information generated by the newer compilers.

• In versions of XEmacs before 21.2.27, `src/.gdbinit' was named `src/gdbinit'. This had the disadvantage of not being sourced automatically by gdb, so you had to set that up yourself.

• If you are running Microsoft Windows, the the file `nt/README' for further information about debugging XEmacs.

Q2.4.5: I get a cryptic error message when trying to do something.

When I try to use some particular option of some particular package, I get a cryptic error message in the minibuffer.

If the message went by too quickly, use `Help->Recent Messages' from the menubar (or type C-h l) to see recent messages.

If you can't figure out what's going on, select `Options->Troubleshooting->Debug on Error' from the menubar (or type M-: then (setq debug-on-error t)) then try and make the error happen again. This will put in the debugger (you can get out of this and continue what you were doing before by typing c) and give you a backtrace that may be enlightening. If not, try reading through this FAQ; if that fails, you could try posting to `comp.emacs.xemacs' (making sure to include the backtrace) and someone may be able to help. If you can identify which XEmacs Lisp source file the error is coming from you can get a more detailed stack backtrace by doing the following:

1. Visit the .el file in an XEmacs buffer.

2. Issue the command M-x eval-current-buffer.

3. Reproduce the error.

For more information on debugging Lisp code, See section `Debugging' in XEmacs Lisp Reference Manual.

Q2.4.6: XEmacs hangs when I try to do something.

XEmacs might just be slow; some operations take a long time. XEmacs may also be waiting on a response from the network, for example when you are trying to send mail.

You can usually interrupt XEmacs by typing C-g. If not (for example, Lisp code explicitly disabled this by setting inhibit-quit), you can use the "critical quit" mechanism by typing Control-Shift-G. This should also pop you into the debugger and give you a backtrace, which can tell you where the problem is (see section How to debug an XEmacs problem with a debugger). (Note that setting debug-on-quit or selecting `Options->Troubleshooting->Debug on Quit' will also cause regular C-g to enter the debugger and give you a backtrace.)

If you can't interrupt XEmacs this way, or for some reason XEmacs is not talking to the keyboard, you can try sending the `SIGINT' signal using the `kill' command.

If the Lisp backtrace isn't enlightening, or if XEmacs is so hung that you can't interrupt it at all, you could try attaching to the process and getting a C stack backtrace. See section How to debug an XEmacs problem with a debugger.

Q2.4.7: I get an error message when XEmacs is running in batch mode.

Typically this happens when you are trying to compile some Elisp code. If you are doing this as part of XEmacs or the XEmacs packages, you should automatically get a backtrace, which can help you determine the source of the problem. In other cases, you can get equivalent results by setting the environment variable `XEMACSDEBUG' to `(setq stack-trace-on-error t load-always-display-messages t load-ignore-out-of-date-elc-files t load-show-full-path-in-messages t)' (this needs to be all on one line; to set an environment variable, use `export XEMACSDEBUG='FOO'' under `bash', `zsh', etc. or `setenv XEMACSDEBUG 'FOO'' under `csh' and `tcsh'). `XEMACSDEBUG' specifies Lisp code that will be executed at startup time.

If the backtrace is not sufficiently useful in helping you diagnose the problem, you should consider using a debugger such as GDB. See section How to debug an XEmacs problem with a debugger. You probably want to set a breakpoint on signal_1. Since such errors often occur during compiling, which is often triggered by a complex command run from a make suite, it may be easier to attach to the process once it's running.

Under Microsoft Windows (and perhaps other operating systems), there is another useful trick you can do if you have configured with debugging support (configure option `--debug' (`--with-debug' in 21.5) or setting `DEBUG_XEMACS' in `nt/config.inc'). Set the environment variable `XEMACSDEBUG' (as described above) to `(setq debug-on-error t)'. Then, when an error occurs noninteractively, instead of trying to invoke the Lisp debugger (which obviously won't work), XEmacs will break out to a C debugger using (force-debugging-signal t). NOTE: This runs abort()!!! (As well as and after executing INT 3 under MS Windows, which should invoke a debugger if it's active.) This is guaranteed to kill XEmacs! (But in this situation, XEmacs is about to die anyway, and if no debugger is present, this will usefully dump core.)

Q2.4.8: The keyboard or mouse is not working properly, or I have some other event-related problem.

XEmacs has various facilities for debugging event handling.

First, try setting the variable debug-emacs-events to non-zero. This will output various information showing which events are being received and how they are being translated. This may show you, for example, that a key command is getting intercepted using key-translation-map; this problem can otherwise be very tricky to debug.

Under X, you can see exactly which events are being received from the window system by setting x-debug-events to non-zero. (The value `1' gives you regular output, and `2' gives you verbose output, including all parameters.)

A similar facility exists under MS Windows: Set debug-mswindows-events to non-zero. (The value `1' gives you regular output. The value `2' gives you verbose output, including all parameters. The value `3' gives you super-gorily-detailed output.)

Q2.4.9: C-g doesn't work for me. Is it broken?

C-g does work for most people in most circumstances. If it doesn't, there are two possible explanations:

1. XEmacs is hung in a way that prevents C-g from working. This can happen when code is wrapped with a binding of inhibit-quit to t; you should still be able interrupt XEmacs using "critical quit". On the other hand, XEmacs may be seriously wedged. (If you're lucky, sending `SIGINT' to the XEmacs process will interrupt it.) See section XEmacs hangs when I try to do something..

2. C-g is indeed broken on your system. To test, try executing (while t) from the `*scratch*' buffer. If C-g doesn't interrupt, then it's broken. This used to happen with systems where `SIGIO' was broken, but `BROKEN_SIGIO' wasn't defined. However, there may not be very many such systems nowadays.

Q2.4.10: How do I debug process-related problems?

Under MS Windows, you can set the variable debug-mswindows-process-command-lines to non-`nil' to get information on exactly what is getting passed to a process. This can be useful in determining problems with quoting. (Under Unix, a process receives each argument separately, but under MS Windows a single command line is received, and arguments with spaces or other special characters in them must be quoted. Unfortunately this means that each process, potentially at least, has its own quoting conventions, and the code to process quoting conventions in `cmd.exe', the Visual C++ startup code and the like is baroque and poorly documented. XEmacs uses the variable mswindows-construct-process-command-line-alist to construct a command line from a list of arguments based on the command to be run, but it is (and cannot be) a perfect solution.)

Q2.4.11: XEmacs is outputting lots of X errors.

If this is happening, we would very much like to know what's causing them. To find this out, see How to debug an XEmacs problem with a debugger. Try to get both a C and Lisp backtrace, and send them along with the full error output to xemacs-beta@xemacs.org.

Q2.4.12: After upgrading, XEmacs won't do `foo' any more!

You have been used to doing `foo', but now when you invoke it (or click the toolbar button or select the menu item), nothing (or an error) happens. The simplest explanation is that you are missing a package that is essential to you. You can either track it down and install it (there is a list of packages and brief descriptions of their contents in `etc/PACKAGES'), or install the `Sumo Tarball' (see section How do I figure out which packages to install?).

2.5: Startup-Related Problems

Q2.5.1: XEmacs cannot connect to my X Terminal!

Help! I can not get XEmacs to display on my Envizex X-terminal!

Try setting the DISPLAY variable using the numeric IP address of the host you are running XEmacs from.

Q2.5.2 Startup problems related to paths or package locations.

First of all, if XEmacs can't find the packages, check to make sure that you put the packages in the right place, or that you told XEmacs where to look for the packages when you compiled it. See section Q2.1.1: How do I install the packages?.

If something is still going wrong, or you get a startup warning about not being able to deduce some paths, you can get detailed information on the path-searching process at startup by setting the environment variable `EMACSDEBUGPATHS' to a non-null value. One thing to look for if you're having package problems is the value of `configure-package-path'. This corresponds to what was compiled into XEmacs using the `--package-prefix' or `--package-path' parameter (see section Q2.1.1: How do I install the packages?). If this has the value of `nil', this means that no value was compiled into XEmacs using these parameters.

Q2.5.3: XEmacs won't start without network, or starts slowly.

If XEmacs starts when you're on the network, but fails when you're not on the network, you may be missing a "localhost" entry in your `/etc/hosts' file. The file should contain an entry like:

127.0.0.1        localhost

Add that line, and XEmacs will be happy. If your network is unreliable, such as a Wifi network, you may experience delays but eventually XEmacs starts up. This may be due to having the lookup order give precedence to DNS over the hosts file (often lookup order is defined in one of the files `/etc/host.conf', `/etc/nsswitch.conf', or `/etc/resolv.conf', depending on OS). See your system documentation for this configuration. Note that changing the lookup order is a workaround; there are good reasons to have DNS come earlier by default. Make sure those reasons are less important to you than a quick XEmacs startup.

Q2.5.4: Startup warnings about deducing proper fonts?

How can I avoid the startup warnings about deducing proper fonts?

This is highly dependent on your installation, but try with the following font as your base font for XEmacs and see what it does:

-adobe-courier-medium-r-*-*-*-120-*-*-*-*-iso8859-1

More precisely, do the following in your resource file:

Emacs.default.attributeFont: \
-adobe-courier-medium-r-*-*-*-120-*-*-*-*-iso8859-1

If you just don't want to see the `*Warnings*' buffer at startup time, you can set this:

(setq display-warning-minimum-level 'error)

The buffer still exists; it just isn't in your face.

Q2.5.5: Warnings from incorrect key modifiers.

The following information comes from the `PROBLEMS' file that comes with XEmacs.

If you're having troubles with HP/UX it is because HP/UX defines the modifiers wrong in X. Here is a shell script to fix the problem; be sure that it is run after VUE configures the X server.

#! /bin/sh
xmodmap 2> /dev/null - << EOF
keysym Alt_L = Meta_L
keysym Alt_R = Meta_R
EOF

xmodmap - << EOF
clear mod1
keysym Mode_switch = NoSymbol
add mod1 = Meta_L
keysym Meta_R = Mode_switch
add mod2 = Mode_switch
EOF

Q2.5.6: XEmacs 21.1 on Windows used to spawn an ugly console window on every startup. Has that been fixed?

Yes.

The console was there because `temacs' (and in turn, `xemacs') was a console application, and Windows typically creates a new console for a console process unless the creating process requests that one isn't created. This used to be fixed with `runemacs', a small Windows application that existed merely to start `xemacs', stating that it didn't want a console.

XEmacs 21.4 fixes this cleanly by the virtue of being a true "GUI" application. The explanation of what that means is included for educational value.

When building an application to be run in a Win32 environment, you must state which sub-system it is to run in. Valid subsystems include "console" and "gui". The subsystem you use affects the run time libraries linked into your application, the start up function that is run before control is handed over to your application, the entry point to your program, and how Windows normally invokes your program. (Console programs automatically get a console created for them at startup if their stdin/stdout don't point anywhere useful, which is the case when run from the GUI. This is a stupid design, of course -- instead, the console should get created only when the first I/O actually occurs! GUI programs have an equally stupid design: When called from `CMD.EXE'/`COMMAND.COM', their stdin/stdout will be set to point nowhere useful, even though the command shell has its own stdin/stdout. It's as if someone who had learned a bit about stdio but had no actual knowledge of interprocess communication designed the scheme; unfortunately, the whole process-communication aspect of the Win32 API is equally badly designed.) For example, the entry point for a console app is "main" (which is what you'd expect for a C/C++ program), but the entry point for a "gui" app is "WinMain". This confuses and annoys a lot of programmers who've grown up on Unix systems, where the kernel doesn't really care whether your application is a gui program or not.

For reasons not altogether clear, and are lost in the mists of time and tradition, XEmacs on Win32 started out as a console application, and therefore a console was automatically created for it. (It may have been made a console application partly because a console is needed in some circumstances, especially under Win95, to interrupt, terminate, or send signals to a child process, and because of the bogosity mentioned above with GUI programs and the standard command shell. Currently, XEmacs just creates and immediately hides a console when necessary, and works around the "no useful stdio" problem by creating its own console window as necessary to display messages in.)

Q2.5.7: XEmacs issues messages about "auto-autoloads already loaded."

On Sat, 05 Mar 2011 11:54:47 -0500, in Message-ID: <4D726AD7.7020303@gmail.com> on xemacs-beta, Raymond Toy reported:

[N]ow every time I start xemacs, I get 100+ error messages stating that the auto-autoload for every package has already been loaded.

When you have many duplicate packages, a common cause is that XEmacs finds package root directories that are duplicates of each other. This can occur in some automounter configurations, or when the roots share some subtrees via symlinks. In this case, you will get a warning for all of the packages you have installed. Although this is basically a site configuration problem, please report these cases. XEmacs is already aware of many automounter artifacts, and automatically adjusts for them. Code is being added to try to detect symlinks. We may not be able to handle every case, but we'd like to know about them, and where possible incorporate workarounds.

Package root directories are specified at configuration time via the --prefix, --exec-prefix, and the `--with-*-packages' options; at runtime relative to the XEmacs binary (`../share' and `..' (for run-in-place)); and at runtime via the `EMACS*PACKAGES' environment variables. Unless you have special needs, it is best to install XEmacs and the packages (configuring with --with-prefix=$prefix for XEmacs and by untarring the SUMOs in `$prefix/share/xemacs/'.

Note that older versions of XEmacs (21.1, 21.4, and early releases of 21.5) by default expect the packages to be installed under `$prefix/lib' rather than `$prefix/share'. See the documentation for `configure' for how to point XEmacs at `$prefix/share/xemacs/' if that is preferred, or older XEmacsen need to share packages with recent versions.