Quick typo fix (missing semi-colon)

[sxemacs] / PROBLEMS

                                                  -*- mode:outline -*-

At the time of this release (SXEmacs 22.1.14), SXEmacs has the
following idiosyncrasies: 

* File Locations
================

** User init file (C-h v user-init-file)

SXEmacs searches for its init file in `~/.sxemacs/init.el'.
Symlinking your old ~/.xemacs directory should be enough to get you up
and running.

    $ ln -s ~/.xemacs ~/.sxemacs RET

BTW, unlike XEmacs, SXEmacs doesn't attempt to "migrate" your old init
file or Gnu/Emacs .emacs file.

** Packages Hierarchy

The default location that SXEmacs searches for packages is
`$prefix/share/sxemacs/'.  The same as for the user-init-file, a
symlink is all you need to get up and running.

    $ ln -s /usr/local/lib/xemacs /usr/local/share/sxemacs RET


* Build Quirks
==============

** FFI

*** FFI is not included with your distro

Sadly, some Linux distributions (hello Fedora) don't ship a libffi
package, and their GCC does NOT include libffi or FFI headers either.
In this instance you have 2 options...

  1) Get the standalone package of libffi at
     <http://sourceware.org/libffi/>.

  2) Compile your own GCC from source, making sure you enable the java
     compiler.  Enabling java in your GCC build is the only way to get
     libffi built.

Obviously, option #1 there is the easiest and quickest path to
FFI-enabled SXEmacsen, and it is the option that we recommend.

Oh, and please nag your distro to have FFI included by default.

*** FFI is included in your GCC but you see missing header errors

Often libffi headers aren't completely installed.  If you are getting
errors in effi.c that seem to be hinged from something like...

  /usr/include/ffi.h:63:23: ffitarget.h: No such file or directory

You need to find `ffitarget.h' and put it in the same directory as
your `ffi.h'.  Your libffi came with GCC, so you'll find it within
your GCC directories:

  $ dirname $(gcc -print-libgcc-file-name)
/usr/lib/gcc-lib/i586-pc-linux-gnu/3.3.1

Using that example, ffitarget.h would be in...

  /usr/lib/gcc-lib/i586-pc-linux-gnu/3.3.1/libffi/

Just copy or symlink the ffitarget.h there to /usr/include

*** FFI on SELinux enabled machines

If you are running with SELinux enabled and configure fails with
messages like the following in `config.log'...

  error while loading shared libraries: /usr/local/lib/libffi.so.1:
  cannot restore segment prot after reloc: Permission denied

You need to correct the default security context for `libffi.so'.

  $ chcon -t textrel_shlib_t /usr/local/lib/libffi.so

** PostgreSQL

The autoconf tests for PostgreSQL support have changed.  SXEmacs'
configure script now uses `pg_config' to determine whether or not to
enable PostgreSQL.  Because of this you may have to set you $PATH
environment to include the pgsql bin directory.  It is normally
`/usr/local/pgsql/bin/'.  Another popular directory on Solaris 9 is
`/opt/crw/postgresql/bin/'.  Check with your site administrator.

Bash users can do it like this...

  export PATH=/usr/local/pgsql/bin:$PATH

*** Solaris 9 with 64-bit PostgreSQL

There has also been a report that on Solaris 9 you may also need to
configure with `--with-cflags='-mcpu=ultrasparc -m64''.  Apparently
GCC on Solaris 9 defaults to building 32-bit, so you lose if you have
64-bit PostgreSQL.

** 64-bit test suite failure

We have had a couple of reports of the test suite failing on 64-bit
systems.  The error is like this (or similar)...

Testing /usr/src/sxemacs/modules/ase/ase-heap-tests.el...
Loading ase_heap v0.0.0 (SXEmacs module: ase-heap)
Loaded module ase_heap v0.0.0 (SXEmacs module: ase-heap)Fatal error: assertion failed, file alloc.c, line 298, block != (void*)0xCAFEBABEDEADBEEF
make[3]: *** [check-am] Aborted

At this point we are not too sure exactly what the issue is.  It looks
like it might be a bug in the malloc or free code of the libc.  We do
know that not all 64-bit systems are affected, so far, only Fedora
Core 7, and Gentoo on x86_64.

One user has reported that using `-O1' in CFLAGS prevents it.

But even with this test failure, SXEmacs still runs and opperates
without incident.  In fact, the failure can't be reproduced when
running the test suite interactively.  With that in mind, it should be
safe to install if you see this failure.

We'll endeavour to get to the bottom of this one ASAP, if you think
you can help, let us know.

** m4, libtool, autoconf, automake, and whatnot

SXEmacs tries to cope with any combination of versions of the above
programs.  However, there is one lower bound, autoconf 2.60, and
unfortunately this has an impact on the other parts of the build
tools.

To cut it really short, here is the minimum known-to-work combination:
- autoconf 2.62, automake 1.9.6, libtool 1.5.22, m4 1.4.6

In general we support (as of April, 2010):
- autoconf >= 2.62, including current git versions
- automake 1.9.6, 1.10, 1.10a, 1.11.1, and current git versions
- libtool 1.5.N with N >= 22, libtool >= 2.1a (current CVS version)
- m4 1.4.M with M >= 6 plus current git versions

Note that many libtool packages shipped with the distros (OpenSuSE,
Debian, just to name two) are _broken_.  Make sure you compile
your own libtool in case you want to rerun autogen.sh or bootstrap
the build chain, and double check that you use --enable-ltdl-install
when doing so.

If you are on a platform that has its own _non_gnu libtool (like OS/X
Leopard) add --program-prefix=g to your gnu libtool configure so it
installs as glibtool and doesn't clobber your other one.

Sometimes it helps just to copy over the libtool script manually:
cp -a $(type -p libtool) ${top_builddir}

*** ylwrap fails with sed errors

Some versions of the ylwrap script provided by autotools uses commas
as separators in sed commands. As such if your build path uses commas
the ylwrap will fail. 

Sample message (where the build path was /Users/njsf/Projects/SXEmacs/nsx-up/,,mac):

/Users/njsf/Projects/SXEmacs/nsx-up/,,mac/lib-src/make-docfile --modname cl-loop -E cl-loop.doc.c ../../../modules/cl/cl-loop.c
/bin/sh ../../../ylwrap ../../../modules/cl/cl-loop-parser.y y.tab.c cl-loop-parser.c y.tab.h cl-loop-parser.h y.output
cl-loop-parser.output -- bison -y  -d
sed: 1: "s,/Users/njsf/Projects/ ...": bad flag in substitute command: 'm'
sed: 1: "s,/Users/njsf/Projects/ ...": bad flag in substitute command: 'm'

The workaround is to use a path without commas in it.


*** Missing libltdl.la (Solaris 2.8)

We've had a report that missing libtool on Solaris 2.8 isn't detected
and so the included libtool still isn't used.  If you see an error
about a missing libltdl.la all you need to do is configure SXEmacs
with... 

  --with-included-ltdl

** configure

*** configure on FreeBSD, NetBSD, OpenBSD, etc.

Building SXEmacs on *BSD as far as we know requires the GNU Bourne
Again SHell (bash) versions 3 or 4.

bash is available for all tier 1 architectures as a binary package and 
and for tier 2/3 as a port.

To run configure successfully...

    CONFIG_SHELL=/path/to/bash $CONFIG_SHELL configure [option, ...]

** bdwgc and gcc and code optimisation

There are some weird optimisation issues with the Boehm-Demers-Weiser
garbage collector (hereafter BDWGC) and the GCC C compilers of the 2 and
3 series.  The build will crash like this:

  Loading build-autoloads.el...
  Loading loadup-el.el...
  Loading loadup.el...make[3]: *** [auto-autoloads.el] Segmentation fault
  (core dumped)
  make[3]: Leaving directory

The C backtrace will look like:

  #0  0xbff9a2f0 in ?? ()
  #1  0xb7eaf7d6 in GC_invoke_finalizers () at finalize.c:787
  #2  0xb7eaf8ed in GC_notify_or_invoke_finalizers () at finalize.c:844
  #3  0xb7eb2c8c in GC_generic_malloc (lb=32, k=0) at malloc.c:190

If this is true for you, you may want to try another optimisation level:

  ./configure CFLAGS="-g -O2"

If this still does not work out either dispense with BDWGC support or
use a recent C compiler.  ATTOW, all GCC 4.x compilers (including SVN)
should work.

** ENT

ENT is basically a conglomerate of internally and externally implemented
arithmetics.  Hence it supports a number of libraries, some of which
overlap in their functionality, some others do not but then break at the
compatibility layer.

One of the most likely problems is the GMP vs. MPFR issue.  In past
times, mpfr (a multiprecision library for floats with exact rounding
facilities) has been a part of the GMP distribution.  Later on, mpfr got
separated from it and has been developed independently while the version
of mpfr which ships with GMP stayed the same.  Now that scenario is
exactly the problem.

Inattentive distributions (like Fedora) still deliver packages of GMP
with the old'n'incompatible mpfr library.  SXEmacs will disable the MPFR
support on such systems by default (at configure time).  However, if you
install a supported version of mpfr in parallel to the packaged ones on
such a system SXEmacs autodetection correctly reports that a sane
version of mpfr is available and enables it.  Nonetheless, the according
build may fail (or the build may even succeed but calling the binary may
fail), like this:

number-mpfr.o: In function `ent_lt_BIGFR_T':
/home/martin/src/edit/sxemacs-main/src/number-mpfr.c:661: undefined
reference to `mpfr_less_p'
number-mpfr.o: In function `ent_gt_BIGFR_T':
/home/martin/src/edit/sxemacs-main/src/number-mpfr.c:671: undefined
reference to `mpfr_greater_p'
...

Especially note that we _only_ support the standalone version of MPFR,
and not the one distributed with GMP.

Solution:
---------
Either:
   Badger your distributor and demand separate packages for GMP and
   MPFR.
Or:
   Remove the GMP package and install your own build -- available at
   http://swox.com/gmp -- afterwards install your own build of mpfr (the
   one from http://www.mpfr.org)

Reconfigure and rebuild SXEmacs afterwards.


* XEmacs Packages
=================

We have identified 2 packages so far that don't work "out of the box"
with SXEmacs.  In both of these the problem is with parsing version
information.  Patches have been sent to the appropriate maintainer to
fix the problem and are included here in case the packages haven't
been updated by the time you install SXEmacs.

Update:  The EFS, and Dired XEmacs packages that are currently
available from the "Pre-Releases" area of XEmacs package mirrors are
both now compatible with SXEmacs and do not need the patches mentioned
here.

** EFS

Here is the patch to make EFS work with SXEmacs:

(Note: the current EFS package that XEmacs distributes has this
patch installed) 

Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/efs/ChangeLog,v
retrieving revision 1.41
diff -u -U0 -r1.41 ChangeLog
--- ChangeLog   4 Oct 2004 08:54:56 -0000       1.41
+++ ChangeLog   14 Jan 2005 02:43:10 -0000
@@ -0,0 +1,6 @@
+2005-01-14  Steve Youngs  <steve@sxemacs.org>
+
+       * efs-fnh.el (efs-handle-emacs-version): Use `emacs-*-version'
+       variables for version info instead of string-matching through
+       `emacs-version'. 
+
Index: efs-fnh.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/efs/efs-fnh.el,v
retrieving revision 1.13
diff -u -u -r1.13 efs-fnh.el
--- efs-fnh.el  2 Oct 2004 14:06:00 -0000       1.13
+++ efs-fnh.el  14 Jan 2005 02:42:59 -0000
@@ -36,15 +36,17 @@
   (let ((ehev-match-data (match-data)))
     (unwind-protect
        (let ((xemacsp (string-match "XEmacs" emacs-version))
-             ver subver)
-         (or (string-match "^\\([0-9]+\\)\\.\\([0-9]+\\)" emacs-version)
-             (error "efs does not work with emacs version %s" emacs-version))
-         (setq ver (string-to-int (substring emacs-version
-                                             (match-beginning 1)
-                                             (match-end 1)))
-               subver (string-to-int (substring emacs-version
-                                                (match-beginning 2)
-                                                (match-end 2))))
+             (ver emacs-major-version)
+             (subver emacs-minor-version))
+         (unless ver
+           (or (string-match "^\\([0-9]+\\)\\.\\([0-9]+\\)" emacs-version)
+               (error "efs does not work with emacs version %s" emacs-version))
+           (setq ver (string-to-int (substring emacs-version
+                                               (match-beginning 1)
+                                               (match-end 1)))
+                 subver (string-to-int (substring emacs-version
+                                                  (match-beginning 2)
+                                                  (match-end 2)))))
          (cond
           
           ;; XEmacs (emacs-version looks like \"19.xx XEmacs\")

** Dired

Here is the patch to make Dired work with SXEmacs:

(Note: the current Dired package that XEmacs distributes has this
patch installed) 

Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/dired/ChangeLog,v
retrieving revision 1.19
diff -u -U0 -r1.19 ChangeLog
--- ChangeLog   4 Oct 2004 08:54:24 -0000       1.19
+++ ChangeLog   14 Jan 2005 02:37:37 -0000
@@ -0,0 +1,7 @@
+2005-01-14  Steve Youngs  <steve@sxemacs.org>
+
+       * dired.el: Use `emacs-*-version' variables for finding version
+       information instead of string-matching through `emacs-version'.
+
+       * diff.el (diff-emacs-19-p): Ditto.
+
Index: diff.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/dired/diff.el,v
retrieving revision 1.4
diff -u -u -r1.4 diff.el
--- diff.el     2 Oct 2004 14:06:17 -0000       1.4
+++ diff.el     14 Jan 2005 02:37:23 -0000
@@ -72,7 +72,7 @@
 ;;; Internal variables
 
 (defconst diff-emacs-19-p
-  (let ((ver (string-to-int (substring emacs-version 0 2))))
+  (let ((ver emacs-major-version))
     (>= ver 19)))
 
 (or diff-emacs-19-p (require 'emacs-19))
Index: dired.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/dired/dired.el,v
retrieving revision 1.7
diff -u -u -r1.7 dired.el
--- dired.el    2 Oct 2004 14:06:19 -0000       1.7
+++ dired.el    14 Jan 2005 02:37:25 -0000
@@ -80,13 +80,15 @@
 ;; Testing against the string `Lucid' breaks InfoDock.  How many years has
 ;; it been since Lucid went away?
 (let ((lucid-p (string-match "XEmacs" emacs-version))
-      ver subver)
-  (or (string-match "^\\([0-9]+\\)\\.\\([0-9]+\\)" emacs-version)
-      (error "dired does not work with emacs version %s" emacs-version))
-  (setq ver (string-to-int (substring emacs-version (match-beginning 1)
-                                     (match-end 1)))
-       subver (string-to-int (substring emacs-version (match-beginning 2)
-                                        (match-end 2))))
+      (ver emacs-major-version)
+      (subver emacs-minor-version))
+  (unless ver
+    (or (string-match "^\\([0-9]+\\)\\.\\([0-9]+\\)" emacs-version)
+       (error "dired does not work with emacs version %s" emacs-version))
+    (setq ver (string-to-int (substring emacs-version (match-beginning 1)
+                                       (match-end 1)))
+         subver (string-to-int (substring emacs-version (match-beginning 2)
+                                          (match-end 2)))))
   (cond
    ((= ver 18)
     (require 'emacs-19)
@@ -6616,11 +6618,12 @@
 ;;;; --------------------------------------------------------------
 
 (let ((lucid-p (string-match "XEmacs" emacs-version))
-      ver)
-  (or (string-match "^\\([0-9]+\\)\\." emacs-version)
-      (error "Weird emacs version %s" emacs-version))
-  (setq ver (string-to-int (substring emacs-version (match-beginning 1)
-                                     (match-end 1))))
+      (ver emacs-major-version))
+  (unless ver
+    (or (string-match "^\\([0-9]+\\)\\." emacs-version)
+       (error "Weird emacs version %s" emacs-version))
+    (setq ver (string-to-int (substring emacs-version (match-beginning 1)
+                                       (match-end 1)))))
 
   ;; Reading with history.
   (if (>= ver 19)


* Problems with running SXEmacs
===============================

** FFI Related

*** ffi-wand.el refuses to load.

Can't load library `libMagickWand': libgomp.so.1: shared object cannot be
dlopen()ed

If you get that error when trying to load ffi-wand, it is because you
have a ImageMagick that is using OpenMP (currently only svn HEAD).  To
fix this you will need to rebuild ImageMagick, making sure that you
configure it using --disable-openmp.

See: <http://issues.sxemacs.org/show_bug.cgi?id=104>

** Multimedia Goodness

*** SXEmacs hangs or crashes during (init-asynchronousity).

This is most likely a known effect (we do not want to call it bug,
since there is no definite location) with certain (g)libc and kernel
combinations under Linux.  If it crashes analyse the core file, it
should look like this:

#0  0x4014ebc4 in __sigsuspend (set=0xbffffbb4) at 
../sysdeps/unix/sysv/linux/sigsuspend.c:48
#1  0x40101b34 in __pthread_wait_for_restart_signal (self=0x401116e0) at 
pthread.c:786
#2  0x40101138 in __pthread_create_2_1 (thread=0x206f8dc, attr=0xbffffc58, 
start_routine=0x20043ac <console>, arg=0xbffffd88) at restart.h:26

A definite fault-prone setup is using kernel 2.6.x in conjunction with
glibc-2.1.1.

*** SXEmacs hangs or crashes before it ought to playback sound.

As before, this is most likely a suspicious (g)libc/kernel
combination.

*** SXEmacs dumps core when using the ALSA audio device

This has been reported to happen with old ALSA libraries (1.0.3 to be
precise).  At the moment it is uncertain at which version these
problems disappear (no developer wants to downgrade to a non-working
ALSA :D).  We highly suggest to use the version 1.0.10 and above, or
not use ALSA at all.

*** SXEmacs in async mode does not play simultaneous sounds with ALSA

This is due to missing (hardware-)mixing capabilities of your
soundcard.  There is a user-space plugin called dmix, which can
effectively circumvent this issue.

*** SXEmacs dumps core when using the aRts audio device

Does it?  Please report details (version number of aRts, backtrace,
etc.).

*** SXEmacs crashes when using state sentinels with asynchronous sounds

This is a known bug (#13 in our bug database).  At the moment the only
advise we can give is: do not use sentinels before 22.1.7.
Also see our bug database at http://issues.sxemacs.org

*** make-media-stream seems to recognise any file as valid audio

This is a known issue with fully-featured ffmpeg builds.  The current
code in SXEmacs blindly relies on FFmpeg when it reports a file or
string as valid audio.  There is no way to double-check that at the
moment.  However, you can perform the additional check yourself if
you have taglib installed.  Use the included ffi-taglib.el.


* Original XEmacs PROBLEMS File
===============================
From here down is a reproduction of the original XEmacs PROBLEMS
file.  Much of it is already fixed in SXEmacs (and in XEmacs too).
We're keeping it here for prosperity, or until somebody finds the time
to go through it all and remove the irrelevant stuff. :-)

Note: Some irrelevant stuff purged (mostly windows rubbish) 2010-04-01

This file describes various problems that have been encountered
in compiling, installing and running XEmacs.  It has been updated for
XEmacs 21.5.

This file is rather large, but we have tried to sort the entries by
their respective relevance for XEmacs, but may have not succeeded
completely in that task.  The file is divided into four parts:

 - Problems with building XEmacs
 - Problems with running XEmacs
 - Compatibility problems
 - Mule issues

Use `C-c C-f' to move to the next equal level of outline, and
`C-c C-b' to move to previous equal level.  `C-h m' will give more
info about the Outline mode.

Also, Try finding the things you need using one of the search commands
XEmacs provides (e.g. `C-s').

General advice:

    WATCH OUT for your init file! (~/.xemacs/init.el or ~/.emacs)  If
    you observe strange problems, invoke XEmacs with the `-vanilla'
    option and see if you can repeat the problem.

    Note that most of the problems described here manifest at RUN
    time, even those described as BUILD problems.  It is quite unusual
    for a released XEmacs to fail to build.  So a "build problem"
    requires you to tweak the build environment, then rebuild XEmacs.
    A "runtime problem" is one that can be fixed by proper
    configuration of the existing build.  Compatibility problems and
    Mule issues are generally runtime problems, but are treated
    separately for convenience.


* Problems with building XEmacs
===============================

** General

    Much general information is in INSTALL.  If it's covered in
    INSTALL, we don't repeat it here.

*** How do I configure to get the buffer tabs/progress bars?

These features depend on support for "native widgets".  Use the
--with-widgets option to configure.  Configuration of widgets is
automatic for "modern" toolkits (MS Windows, GTK, and Motif), but if
you are using Xt and the Athena widgets, you will probably want to
specify a "3d" widget set.  See configure --usage, and don't forget to
install the corresponding development libraries.

*** I know I have libfoo installed, but configure doesn't find it.

Typical of Linux systems with package managers.  To link with a shared
library, you only need the shared library.  To compile objects that
link with it, you need the headers---and distros don't provide them with
the libraries.  You need the additional "development" package, too.

*** When using gcc, you get the error message "undefined symbol __fixunsdfsi".
When using gcc, you get the error message "undefined symbol __main".

This means that you need to link with the gcc library.  It may be called
"gcc-gnulib" or "libgcc.a"; figure out where it is, and define LIB_GCC in
config.h to point to it.

It may also work to use the GCC version of `ld' instead of the standard one.

*** src/Makefile and lib-src/Makefile are truncated--most of the file missing.

This can happen if configure uses GNU sed version 2.03.  That version
had a bug.  GNU sed version 2.05 works properly.

** Motif

Motif is the X11 version of the Gnus torture test: if there's a way to
crash, Motif will find it.  With the open source release of Motif, it