Fix SoX
[sxemacs] / INSTALL
1 SXEmacs Installation Guide
2 Copyright (C) 2005 - 2012 Steve Youngs
3
4
5 Building from tarball release: 
6 -----------------------------
7 (See "Building from git source" below if you got SXEmacs that way)
8
9 In a nutshell:
10 -------------
11 See ./configure --help for a description of all possible options,
12 then
13
14   $ ./configure [options]
15   $ make
16   $ make check
17   $ make install
18
19
20 Prerequisites:
21 -------------
22 Your version of SXEmacs includes a file called `PROBLEMS' in the top
23 directory of the source tarball.  Please take a moment now to look
24 over it.
25
26 GNU make.  Solaris make and BSD make just don't cut the mustard, so
27 make sure you use GNU make (sometimes installed as `gmake').  If you
28 don't have it, you can leech it from ftp://ftp.gnu.org/gnu/make
29
30 To build SXEmacs you need a C compiler that is C99 compliant.  We
31 recommend GCC >= 3.1.1.  Other compilers _may_ work, such as Intel's
32 ICC, but the SXEmacs project won't explicitly support any compiler
33 other than GCC.  If you don't have such a compiler you can get GCC
34 from: http://gcc.gnu.org/.
35
36 Please note that SXEmacs _CANNOT_ be built with a C++ compiler.
37
38 Also, some configuration options may need external libraries that are
39 not shipped with SXEmacs.  SXEmacs will determine which libraries it
40 needs at configuration time (when you run `./configure').
41
42 If configure can't find a particular library and you _do_ have it
43 installed, you can usually get configure to find it by adding to the
44 `--with-site-prefixes' option.
45
46 There are several optional external libraries you may use to extend
47 the feature-range of SXEmacs.  See section `Optional Libraries'.
48
49
50 Stripping:
51 ---------
52 Our advice... _DON'T_ do it.  Stripping object files doesn't buy you
53 anything other than a little bit of disc space.  And in an era where
54 multi-Terabyte hard discs are common, the space saved by stripping is
55 inconsequential at best.
56
57 But that isn't the only reason why we suggest that you don't strip
58 SXEmacs.  If you did, any bug reports you sent us would be useless
59 because the backtrace from any core dump wouldn't contain any useful
60 information.
61
62 Another reason for not stripping comes from the complexity of SXEmacs
63 and how it is built.  SXEmacs first compiles to a basic binary
64 (sometimes called "temacs"), and then it loads in a pile of lisp code
65 and other goodies, and dumps itself out to become the finished SXEmacs
66 binary.  Add into that mix, the portable dumper (where a lot of stuff
67 for sxemacs actually resides _outside_ of the binary in a dump file)
68 and it becomes apparent that stripping may not even be possible.  What
69 do you strip? temacs? the portable dump file? sxemacs binary?
70
71 Err on the side of caution and don't even try it.
72
73
74 Compiler Optimisations:
75 ----------------------
76 Considerable care has been taken to ensure that the maximum safe
77 compiler optimisation flags have been turned on by default.  If you
78 wish to use your own flags, that's OK, but understand that sometimes
79 over-optimising (especially with something as complex as SXEmacs) can
80 actually have an adverse affect.
81
82
83 Packages:
84 --------
85 Like XEmacs, SXEmacs only comes with a minimal set of lisp libraries
86 to cover only basic editing and functions.  To get fuller
87 functionality you need to install some extra elisp packages.  SXEmacs
88 doesn't actually distribute any elisp packages, but it can and does
89 use XEmacs packages.
90
91 Unlike XEmacs, SXEmacs does _NOT_ need any packages pre-installed
92 before its packaging tools (PUI) are usable.  To install elisp
93 packages into a virgin, packageless, SXEmacs, follow these steps...
94
95   1) Start SXEmacs
96
97   2) From the menubar, choose:
98
99           Tools -> Packages -> Set Download Site -> Official Releases
100             -> ...
101
102   3) M-x pui-bootstrap RET
103
104 After the "bootstrapping" is finished you'll be asked if you want to
105 install anymore packages.
106
107
108 File hierarchies:
109 ----------------
110 As of 22.1.6 SXEmacs installs its files in a LFSH-compliant (Linux
111 FileSystem Hierarchy) way.  Here is a small table:
112
113          now go to...                before went to...
114 lisp     share/sxemacs-$ver/lisp/  lib/sxemacs-22.1.6/lisp/
115 etc      share/sxemacs-$ver/etc/   lib/sxemacs-22.1.6/etc/
116 info     share/info/                 lib/sxemacs-22.1.6/info/
117 headers  include/sxemacs/$ver/     lib/sxemacs-22.1.6/<arch>/include/
118
119 The only thing that remained are modules which are located at
120 lib/sxemacs-22.1.6/<arch>/modules.  Which is already FSH std
121 anyway.
122
123 Optional Libraries:
124 ------------------
125 Optional libraries enhance your SXEmacs with additional features.  Since
126 most of the added features are not mandatory for the core SXEmacs, we
127 decided to make them optional.  That is, you can - but do not need to -
128 install them and incorporate them into SXEmacs.
129
130   Failure to detect optional libraries:
131   -------------------------------------
132   If the optional libraries are in a non-standard location, use
133   --with-site-prefixes option of configure. Ex:
134
135         ./configure --with-site-prefixes=/opt/local
136
137   You can specify a list of paths with --with-site-prefixes:
138
139         ./configure --with-site-prefixes=/opt/local:/sw
140
141   NOTE: Usage of --prefix does NOT imply that it is added to
142   site prefixes, so if you may need to add --with-site-prefixes
143   even with --prefix:
144         
145         ./configure --prefix=/opt/local --with-site-prefixes=/opt/local
146
147
148
149   Multimedia Libraries:
150   --------------------
151   In order to use MM features you need libraries which are responsible
152   for handling different types of media files, that is parses them,
153   demuxes them and decodes them to a raw form suitable for your audio
154   hardware.  We call such libs multimedia libraries.
155
156   Note: To get multimedia working you also have to install at least one
157   audio output library.  See next section.
158
159   - sndfile:
160     http://www.mega-nerd.com/libsndfile/
161
162   - ffmpeg:
163     http://ffmpeg.org/
164
165   - mad:
166     http://www.underbit.com/products/mad/
167
168   - SoX (min version 14.1.0):
169     http://sox.sourceforge.net/
170
171   Note: Some of the media libraries above may in turn have dependencies
172   to even lower level libraries.  Consult the documentation of the
173   respective project.
174
175   The configure option to control media libraries is --with-media.  It
176   defaults to `all'.
177
178
179   Audio Output Libraries:
180   ----------------------
181   The other type of libraries for SXEmacs multimedia features cares for
182   the actual audio output, that is takes some raw audio data and feeds
183   it to your speakers (or somewhere else).  We call those Audio Output
184   Libraries.
185
186   - OSS (Open Sound System): native on Linux and BSD. DEPRECATED!
187
188   - NAS (Network Audio System):
189     http://www.radscan.com/nas.html
190
191   - ESD (Enlightenment Sound Daemon):
192     ftp://ftp.gnome.org/pub/gnome/sources/esound/0.2/
193
194   - PulseAudio:
195     http://pulseaudio.org/
196
197   - Jack (Jack Audio Connection Kit):
198     http://jackaudio.org/
199
200   - ALSA (Advanced Linux Sound Architecture): Linux-only
201     http://www.alsa-project.org/
202
203   - AO: generic and portable audio output
204     http://www.xiph.org/ao/
205
206   Note: Some of the audio libraries above may in turn have dependencies
207   to even lower level libraries.  Consult the documentation of the
208   respective project.
209
210   The configure option to control media libraries is --with-sound.  It
211   defaults to `all'.
212
213
214   Image Decoding Libraries:
215   ------------------------
216   For image media, SXEmacs provides support for various standard formats.
217   We call those Image Format Libraries.
218
219   - GIF: built-in, i.e. no extra library necessary
220
221   - XPM (X PixMap format): included in the X distribution, see for one
222     http://www.x.org 
223
224   - PNG (Portable Network Graphic):
225     http://www.libpng.org/
226
227   - JPEG:
228     http://www.ijg.org/
229
230   - TIFF:
231     http://www.remotesensing.org/libtiff/
232
233   - xface (base64 encoded xbm):
234     http://ftp.xemacs.org/pub/xemacs/aux/compface-1.5.2.tar.gz
235
236   The configure option to control media libraries is --with-image.  It
237   defaults to `all'.
238
239
240   Additional Number Types:
241   -----------------------
242   SXEmacs can extend its arithmetics enormously by using external
243   support.  We refer to enhanced number types as ENT.
244
245   - GMP (GNU MultiPrecision arithmetics library):
246     ftp://ftp.gnu.org/gnu/gmp/
247
248   - BSD mp:
249     Available natively on BSD distributions.  Also included in the
250     OpenSSL distribution.
251
252   - MPFR (Multi-Precision Floating point numbers with correct Rounding):
253     http://www.mpfr.org
254
255   - MPC (Multi-Precision Complex numbers):
256     http://www.multiprecision.org/index.php?prog=mpc
257
258   The configure option to control ENT libraries is --with-ent.  It
259   defaults to `all'.
260
261
262   Foreign Function Interface:
263   --------------------------
264   Foreign functions open the world to any library on your system.
265   Download a source tarball from:
266
267     <ftp://sourceware.org/pub/libffi/>.
268
269   Or grab the latest CVS sources with:
270
271     cvs -d :pserver:anoncvs@sources.redhat.com:/cvs/libffi login
272        (password is ``anoncvs'')
273     cvs -d :pserver:anoncvs@sources.redhat.com:/cvs/libffi co libffi
274
275   FFI is also available as part of GCC.  It gets turned on if you
276   build the Java compiler, gcj.  Strangely enough, not very many Linux
277   distros do this by default.  Building GCC can take literally hours,
278   building libffi from sourceware takes literally seconds... I know
279   which I'd rather do.
280
281   There is also a section about FFI in the PROBLEMS file, so check
282   that out if you are having any trouble.
283
284   The configure option for the FFI support is --with-ffi.  It defaults
285   to `yes'.
286
287
288   OpenSSL interface:
289   -----------------
290   SXEmacs supports cryptographic algorithms and security protocols via
291   the OpenSSL toolkit.  To make use of it build and install any version
292   since 0.9.8.
293   http://www.openssl.org/
294
295   The configure option for OpenSSL support is --with-openssl which
296   defaults to `yes'.
297
298
299   PostgreSQL Support:
300   ------------------
301   SXEmacs can interact with databases managed by the PostgreSQL DBMS.
302   The functionality roughly corresponds to that of the libpq interface.
303   http://www.postgresql.org/
304
305   The configure option for PgSQL support is --with-postgresql and
306   defaults to `autodetect'.
307
308
309 The build failed:
310 ----------------
311 Suggestion 1:
312 Don't panic.  Take a look at the PROBLEMS file first and see if your
313 issue is listed there.
314
315 Suggestion 2:
316 If the build fails at the configure script, try to examine the output
317 and/or the more verbose config.log.  If the culprit seems to be a
318 certain test or configure option, try to circumvent it.  You can for one
319 disable almost any functionality using --without-<feature>.
320
321 Suggestion 3:
322 If the build fails at the make stage somewhere, try to figure out which
323 functionality was attempted to make.  If it appears to be at some of the
324 optional features, try configuring again with that option disabled.  If
325 it seems to be a compiler or linker problem read suggestion number 4.
326
327 Suggestion 4:
328 If the build fails and you have absolutely no clue why it does, contact
329 the friendly people at SXEmacs.  For almost real-time help consider the
330 IRC channel 
331   #sxemacs on freenode  irc://irc.freenode.net/#sxemacs
332
333 If you cannot stand real-time help you can try the
334   SXEmacs developers mailing list  sxemacs-devel@sxemacs.org
335
336 Unfortunately, because of spam issues, the SXEmacs mailing lists are
337 all "member only".  This means that if you are not subscribed, it'll
338 go to the moderator.  Our moderator is a very busy guy and he has to
339 filter through more spam than you can poke a stick at... occasionally
340 things can slip through the cracks.  Your best bet is to subscribe to
341 the lists.  We are truly sorry for this inconvenience.
342
343 Be sure to keep anything that could help to track the problem down, in
344 particular that is:
345 - configure output
346 - config.log
347 - make output
348 - core dump files if any
349 - your OS and machine architecture
350 - the steps you have done
351
352 There is a script under contrib called tar-build-failure.sh that
353 will attempt to gather this information and create a tar file with
354 helpful logs.
355
356 Before submitting a report at http://issues.sxemacs.org/, please show
357 up either on the mailing list or the IRC channel.  The developers can
358 tell you in much greater detail what they need and how you can get the
359 files and information you need.
360
361
362 Building from git source:
363 ------------------------
364 This is identical to building from the tarball sources, with the
365 addition of an extra step, and some extra requirements (that are most
366 likely already on your system).
367
368   $ ./autogen.sh
369   $ ./configure [options]
370   $ make
371   $ make check
372   $ make install
373
374 Extra requirements:
375 ------------------
376 The SXEmacs sources in the git repo do not contain _any_ generated
377 files.  You will need recent versions of the GNU autotools (automake,
378 autoconf).
379
380 You need at least...
381
382   automake 1.9.4
383   autoconf 2.60
384   texinfo 4.8
385
386 Warnings from autogen.sh:
387 ------------------------
388 You may notice several warnings from running the autogen.sh script.
389 They can be safely ignored unless it dies completely or a configure
390 script isn't generated.
391
392 The two most common warnings seen are...
393
394   Warnings about underquoting of macros in /usr/share/aclocal/foo.m4
395
396     These are because recent versions of aclocal have become more strict
397     about quoting and you have some older style macros defined like:
398     AC_DEFUN(NAME, ...) instead of AC_DEFUN([NAME], ...).
399
400   Warnings about ETAGS variable being redefined
401
402     These are because automake has a pre-defined ETAGS target that
403     projects can use, unfortunately it doesn't fit in with our needs,
404     and isn't easily customisable.  So we wrote our own ETAGS Makefile
405     target.
406