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