1 SXEmacs Installation Guide
2 Copyright (C) 2005 - 2015 Steve Youngs
5 ,----[ In-Tree Builds Lead To Madness ]
6 | Please note that because of the complexity of SXEmacs and its build
7 | chain, we do not support building from within the source tree itself.
9 | So please, ALWAYS run `configure' and `make' from a separate directory,
10 | completely outside of the source tree.
12 | In the code examples below, "${SRCTREE}" refers to the path where
13 | your SXEmacs source files are stored.
17 Building from tarball release:
18 -----------------------------
19 (See "Building from git source" below if you got SXEmacs that way)
23 See ./configure --help for a description of all possible options,
26 $ ${SRCTREE}/configure [options]
34 Your version of SXEmacs includes a file called `PROBLEMS' in the top
35 directory of the source tarball. Please take a moment now to look
38 GNU make. Solaris make and BSD make just don't cut the mustard, so
39 make sure you use GNU make (sometimes installed as `gmake'). If you
40 don't have it, you can leech it from ftp://ftp.gnu.org/gnu/make
42 To build SXEmacs you need a C compiler that is C99 compliant. We
43 recommend GCC >= 3.1.1. Other compilers _may_ work, such as Intel's
44 ICC, but the SXEmacs project won't explicitly support any compiler
45 other than GCC. If you don't have such a compiler you can get GCC
46 from: http://gcc.gnu.org/.
48 Please note that SXEmacs _CANNOT_ be built with a C++ compiler.
50 Also, some configuration options may need external libraries that are
51 not shipped with SXEmacs. SXEmacs will determine which libraries it
52 needs at configuration time (when you run `${SRCTREE}/configure').
54 If configure can't find a particular library and you _do_ have it
55 installed, you can usually get configure to find it by adding to the
56 `--with-site-prefixes' option.
58 There are several optional external libraries you may use to extend
59 the feature-range of SXEmacs. See section `Optional Libraries'.
64 Our advice... _DON'T_ do it. Stripping object files doesn't buy you
65 anything other than a little bit of disc space. And in an era where
66 multi-Terabyte hard discs are common, the space saved by stripping is
67 inconsequential at best.
69 But that isn't the only reason why we suggest that you don't strip
70 SXEmacs. If you did, any bug reports you sent us would be useless
71 because the backtrace from any core dump wouldn't contain any useful
74 Another reason for not stripping comes from the complexity of SXEmacs
75 and how it is built. SXEmacs first compiles to a basic binary
76 (sometimes called "temacs"), and then it loads in a pile of lisp code
77 and other goodies, and dumps itself out to become the finished SXEmacs
78 binary. Add into that mix, the portable dumper (where a lot of stuff
79 for sxemacs actually resides _outside_ of the binary in a dump file)
80 and it becomes apparent that stripping may not even be possible. What
81 do you strip? temacs? the portable dump file? sxemacs binary?
83 Err on the side of caution and don't even try it.
86 Compiler Optimisations:
87 ----------------------
88 Considerable care has been taken to ensure that the maximum safe
89 compiler optimisation flags have been turned on by default. If you
90 wish to use your own flags, that's OK, but understand that sometimes
91 over-optimising (especially with something as complex as SXEmacs) can
92 actually have an adverse affect.
97 As of 22.1.17 SXEmacs is distributing a set of XEmacs packages.
98 However they are currently only available via HTTP so you will need
99 a FFI-enabled SXEmacs to download and install package through the
100 Package User Interface (PUI).
102 Like XEmacs, SXEmacs only comes with a minimal set of lisp libraries
103 to cover only basic editing and functions. To get fuller
104 functionality you need to install some extra elisp packages.
108 2) From the menubar, choose a download site:
110 Tools -> Packages -> Set Download Site -> Official Releases
113 "choose" might be a bit optimistic of a word as we currently only
114 have a single packages download site. That could change in the
115 future. The glass is half-full, yeah? ;-)
117 3) M-x pui-list-packages RET
119 It will ask you if you would like to update the package-index
120 file, or, if you don't have one yet (if this is your first time
121 running SXEmacs, you won't), offer to create one for you. In
122 either case, say "yes".
124 At this point you can choose which packages to install. There are
125 some brief instructions at the bottom of that "Packages" buffer.
130 As of 22.1.6 SXEmacs installs its files in a LFSH-compliant (Linux
131 FileSystem Hierarchy) way. Here is a small table:
133 now go to... before went to...
134 lisp share/sxemacs-$ver/lisp/ lib/sxemacs-22.1.6/lisp/
135 etc share/sxemacs-$ver/etc/ lib/sxemacs-22.1.6/etc/
136 info share/info/ lib/sxemacs-22.1.6/info/
137 headers include/sxemacs/$ver/ lib/sxemacs-22.1.6/<arch>/include/
139 The only thing that remained are modules which are located at
140 lib/sxemacs-22.1.6/<arch>/modules. Which is already FSH std
145 Optional libraries enhance your SXEmacs with additional features. Since
146 most of the added features are not mandatory for the core SXEmacs, we
147 decided to make them optional. That is, you can - but do not need to -
148 install them and incorporate them into SXEmacs.
150 Failure to detect optional libraries:
151 -------------------------------------
152 If the optional libraries are in a non-standard location, use
153 --with-site-prefixes option of configure. Ex:
155 ${SRCTREE}/configure --with-site-prefixes=/opt/local
157 You can specify a list of paths with --with-site-prefixes:
159 ${SRCTREE}/configure --with-site-prefixes=/opt/local:/sw
161 NOTE: Usage of --prefix does NOT imply that it is added to
162 site prefixes, so if you may need to add --with-site-prefixes
165 ${SRCTREE}/configure --prefix=/opt/local --with-site-prefixes=/opt/local
169 Multimedia Libraries:
171 In order to use MM features you need libraries which are responsible
172 for handling different types of media files, that is parses them,
173 demuxes them and decodes them to a raw form suitable for your audio
174 hardware. We call such libs multimedia libraries.
176 Note: To get multimedia working you also have to install at least one
177 audio output library. See next section.
180 http://www.mega-nerd.com/libsndfile/
186 http://www.underbit.com/products/mad/
188 - SoX (min version 14.1.0):
189 http://sox.sourceforge.net/
191 Note: Some of the media libraries above may in turn have dependencies
192 to even lower level libraries. Consult the documentation of the
195 The configure option to control media libraries is --with-media. It
199 Audio Output Libraries:
200 ----------------------
201 The other type of libraries for SXEmacs multimedia features cares for
202 the actual audio output, that is takes some raw audio data and feeds
203 it to your speakers (or somewhere else). We call those Audio Output
206 - OSS (Open Sound System): native on Linux and BSD. DEPRECATED!
208 - NAS (Network Audio System):
209 http://www.radscan.com/nas.html
211 - ESD (Enlightenment Sound Daemon):
212 ftp://ftp.gnome.org/pub/gnome/sources/esound/0.2/
215 http://pulseaudio.org/
217 - Jack (Jack Audio Connection Kit):
218 http://jackaudio.org/
220 - ALSA (Advanced Linux Sound Architecture): Linux-only
221 http://www.alsa-project.org/
223 - AO: generic and portable audio output
224 http://www.xiph.org/ao/
226 Note: Some of the audio libraries above may in turn have dependencies
227 to even lower level libraries. Consult the documentation of the
230 The configure option to control media libraries is --with-sound. It
234 Image Decoding Libraries:
235 ------------------------
236 For image media, SXEmacs provides support for various standard formats.
237 We call those Image Format Libraries.
239 - GIF: built-in, i.e. no extra library necessary
241 - XPM (X PixMap format): included in the X distribution, see for one
244 - PNG (Portable Network Graphic):
245 http://www.libpng.org/
251 http://www.remotesensing.org/libtiff/
253 - xface (base64 encoded xbm):
254 http://ftp.xemacs.org/pub/xemacs/aux/compface-1.5.2.tar.gz
256 The configure option to control media libraries is --with-image. It
260 Additional Number Types:
261 -----------------------
262 SXEmacs can extend its arithmetics enormously by using external
263 support. We refer to enhanced number types as ENT.
265 - GMP (GNU MultiPrecision arithmetics library):
266 ftp://ftp.gnu.org/gnu/gmp/
269 Available natively on BSD distributions. Also included in the
270 OpenSSL distribution.
272 - MPFR (Multi-Precision Floating point numbers with correct Rounding):
275 - MPC (Multi-Precision Complex numbers):
276 http://www.multiprecision.org/index.php?prog=mpc
278 The configure option to control ENT libraries is --with-ent. It
282 Foreign Function Interface:
283 --------------------------
284 Foreign functions open the world to any library on your system.
285 Download a source tarball from:
287 <ftp://sourceware.org/pub/libffi/>.
289 Or grab the latest git sources with:
291 git clone https://github.com/libffi/libffi
293 FFI is also available as part of GCC. It gets turned on if you
294 build the Java compiler, gcj. Strangely enough, not very many Linux
295 distros do this by default. Building GCC can take literally hours,
296 building libffi from sourceware takes literally seconds... I know
299 There is also a section about FFI in the PROBLEMS file, so check
300 that out if you are having any trouble.
302 The configure option for the FFI support is --with-ffi. It defaults
308 SXEmacs supports cryptographic algorithms and security protocols via
309 the OpenSSL toolkit. To make use of it build and install any version
311 http://www.openssl.org/
313 The configure option for OpenSSL support is --with-openssl which
319 SXEmacs can interact with databases managed by the PostgreSQL DBMS.
320 The functionality roughly corresponds to that of the libpq interface.
321 http://www.postgresql.org/
323 The configure option for PgSQL support is --with-postgresql and
324 defaults to `autodetect'.
330 Don't panic. Take a look at the PROBLEMS file first and see if your
331 issue is listed there.
334 If the build fails at the configure script, try to examine the output
335 and/or the more verbose config.log. If the culprit seems to be a
336 certain test or configure option, try to circumvent it. You can for one
337 disable almost any functionality using --without-<feature>.
340 If the build fails at the make stage somewhere, try to figure out which
341 functionality was attempted to make. If it appears to be at some of the
342 optional features, try configuring again with that option disabled. If
343 it seems to be a compiler or linker problem read suggestion number 4.
346 If the build fails and you have absolutely no clue why it does, contact
347 the friendly people at SXEmacs. For almost real-time help consider the
349 #sxemacs on freenode irc://irc.freenode.net/#sxemacs
351 If you cannot stand real-time help you can try the
352 SXEmacs developers mailing list sxemacs-devel@sxemacs.org
354 Unfortunately, because of spam issues, the SXEmacs mailing lists are
355 all "member only". This means that if you are not subscribed, it'll
356 go to the moderator. Our moderator is a very busy guy and he has to
357 filter through more spam than you can poke a stick at... occasionally
358 things can slip through the cracks. Your best bet is to subscribe to
359 the lists. We are truly sorry for this inconvenience.
361 Be sure to keep anything that could help to track the problem down, in
366 - core dump files if any
367 - your OS and machine architecture
368 - the steps you have done
370 There is a script under contrib called tar-build-failure.sh that
371 will attempt to gather this information and create a tar file with
374 Before submitting a report at https://issues.sxemacs.org/, please show
375 up either on the mailing list or the IRC channel. The developers can
376 tell you in much greater detail what they need and how you can get the
377 files and information you need.
380 Building from git source:
381 ------------------------
382 This is identical to building from the tarball sources, with the
383 addition of an extra step, and some extra requirements (that are most
384 likely already on your system). Remember that "in-tree" builds are
385 not supported, so configure and make from a directory outside the
389 $ ${SRCTREE}/configure [options]
396 The SXEmacs sources in the git repo do not contain _any_ generated
397 files. You will need recent versions of the GNU autotools (automake,
404 texinfo 5.2 (preferably 6.0)
406 Warnings from autogen.sh:
407 ------------------------
408 You may notice several warnings from running the autogen.sh script.
409 They can be safely ignored unless it dies completely or a configure
410 script isn't generated.
412 The two most common warnings seen are...
414 Warnings about underquoting of macros in /usr/share/aclocal/foo.m4
416 These are because recent versions of aclocal have become more strict
417 about quoting and you have some older style macros defined like:
418 AC_DEFUN(NAME, ...) instead of AC_DEFUN([NAME], ...).
420 Warnings about ETAGS variable being redefined
422 These are because automake has a pre-defined ETAGS target that
423 projects can use, unfortunately it doesn't fit in with our needs,
424 and isn't easily customisable. So we wrote our own ETAGS Makefile