INSTALL

GNU Emacs Installation Guide
Copyright (c) 1985 Richard M. Stallman

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and permission notice are preserved,
   and that the distributor grants the recipient permission
   for further redistribution as permitted by this notice.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them,
   and that any new or changed statements about me (Richard Stallman)
   or my activities are approved by me.


PREPARATION

0) Make sure your system has enough swapping space allocated
 to handle a program whose pure code is 400k bytes (vax) or
 600k (68000), and whose data area is at least 150k and can
 reach 600k bytes.  If the swapping space is insufficient, you
 will get an error in the command temacs -l loadup inc dump,
 found in $BUILD/src/Makefile, or possibly when running the
 final dumped Emacs.
 
1) Choose a place in the file structure for the main directory
 of Emacs code to reside.  This will ultimately have
 subdirectories named src, lisp, etc, etc.  Call this name
 $EMACS.  Let $BUILD stand for the name the directory has now.

2) Copy $BUILD/src/config.h.dist to config.h, and edit it to
 set the right options for your system.

3) Copy $BUILD/src/paths.h.dist to paths.h, and edit it to
 contain the correct directory names: $EMACS/lisp for the
 directory for Lisp libraries, and $EMACS/etc for the
 directory for executables and text files.

 Emacs will use these names once it has been built.
 During building, Emacs searches the directory ../lisp for
 Lisp files before the directories specified in paths.h, and
 executable files are found in ../etc.  So the main Emacs
 directory $BUILD can be anywhere while Emacs is built, but
 must be renamed to $EMACS afterwards in order for Emacs to
 work properly.

4) Put into $BUILD/lisp/site-init.el any Lisp code
 you want loaded into Emacs before it is dumped out.

 This file is nonexistent in the distribution.
 You do not need to create it, if you have nothing
 to put in it.

5) Decide what compiler switches to use.
 You might want to replace the `-g' in the Makefile
 with `-O'.  If you are not running on 4.2 on a vax,
 it is possible that no debugger you have will be able
 to run Emacs with its symbol table, so you might as well
 use `-O' instead.  If you do have a debugger that works,
 it is probably best to use `-g' so that you are not
 helpless in the face of a problem.

6) Refer to the file $BUILD/etc/TERMS for information on
 fields you may wish to add to various termcap entries.

BUILDING GNU EMACS
The steps below are done by the shell script `build-install'.

1) Cd to $BUILD/etc and run `make'.
 This creates files named `ctags' and `etags' and `loadst'
 and `make-docfile' and `digest-doc' and `test-distrib'.

2) Cd to $BUILD/src and Run `make'
 This refers to files in the $BUILD/lisp and $BUILD/etc subdirectories
 using names ../lisp and ../etc.

 This creates a file $BUILD/src/xemacs which is the runnable Emacs,
 assigning it a new version number by incrementing the version
 stored in $BUILD/lisp/version.el.

 It also creates a file in $BUILD/etc, whose name is
 DOCSTR followed by the current Emacs version.
 This file contains documentation strings for all the
 functions in Emacs.  Each time you run make to make a new xemacs,
 a new DOCSTR file with a new name is made.  You must keep
 the DOCSTR file for an Emacs version as long as you keep using
 that Emacs version.


INSTALLATION
The steps below are done by the shell script `build-install'.

0) mv $BUILD $EMACS   if $BUILD and $EMACS are not the same.
 This moves the main Emacs directory to the name you have told
 Emacs (via paths.h) it is going to have.

1) Move the file $EMACS/xemacs to /usr/local/bin/emacs,
 or some other name in users' search paths.
 `xemacs' has an alternate name $EMACS/src/emacs-EMACSVERSION;
 you may wish to make a symbolic link
 named /usr/local/bin/emacs pointing to that alternate name,
 as an easy way of installing different versions.

 You can delete $EMACS/src/temacs.

3) Move the programs ctags and etags from $EMACS/etc
 to /usr/local/bin.  These programs are run by users as shell commands.

 The program $EMACS/etc/loadst is invoked by Emacs when appropriate.

 The programs $EMACS/etc/make-docfile and $EMACS/etc/test-distrib
 are not used any more; they were invoked from src/Makefile.

 $EMACS/etc/digest-doc can be used to convert DOCSTR into a
 file for users to read.  There is no important reason to move it.

4) The files in $EMACS/src subdirectory, except for xemacs,
 are not used by Emacs once it is built.


LOSSAGES
Known possible problems building and running GNU Emacs

* Watch out for .emacs files and EMACSLOADPATH environment vars

These control the actions of Emacs.
~/.emacs is your Emacs init file.
EMACSLOADPATH overrides which directories the function
"load" will search.

If you observe strange problems, check for these and get rid
of them, then try again.

* Fatal signal in the command  temacs -l loadup inc dump

This has been known to happen due to insufficient swapping
space available on the machine.

On 68000's, it has also happened because of bugs in the
subroutine `alloca'.  Verify that `alloca' works right, even
for large blocks (many pages).

* temacs prints "Command key out of range 0-127"
* or, temacs runs and dumps xemacs, but xemacs totally fails to work.
* or, temacs gets errors dumping xemacs

This can be because the .elc files have been garbled.  Do not be
fooled by the fact that most of a .elc file is text: these are
binary files and can contain all 256 byte values.

In particular `shar' cannot be used for transmitting GNU Emacs.
It typically truncates "lines".  What appear to be "lines" in
a binary file can of course be of any length.  Even once `shar'
itself is made to work correctly, `sh' discards null characters
when unpacking the shell archive.

I have also seen character \177 changed into \377.  I do not know
what transfer means caused this problem.  Various network
file transfer programs are suspected of clobbering the high bit.

The only verified ways to transfer GNU Emacs are `tar'
and rcp or internet ftp between two Unix systems, or chaosnet
cftp.

If you have a copy of Emacs that has been damaged in its
nonprinting characters, you can fix them:

 1) Record the names of all the .elc files.
 2) Delete all the .elc files.
 3) Recompile alloc.c with a value of PURESIZE twice as large.
     You might as well save the old alloc.o.
 4) Remake xemacs.  It should work now.
 5) Running xemacs, do Meta-x byte-compile-file repeatedly
  to recreate all the .elc files that used to exist.
 6) Reinstall the old alloc.o (undoing changes to alloc.c if any)
  and remake temacs.
 7) Remake xemacs.  It should work now, with valid .elc files.

* temacs prints "Pure Lisp storage exhausted"

This means that the Lisp code loaded from the .elc and .el
files during  temacs -l loadup inc dump  took up more
space than was allocated.

This could be caused by
 1) adding code to the preloaded Lisp files
 2) adding more preloaded packages in loadup.el
 3) getting the wrong .el or .elc files
   (not from the directory you expected).
 4) deleting some .elc files that are supposed to exist.
   This would cause the source files (.el files) to be
   loaded instead.  They take up more room, so you lose.

* Changes made to .el files do not take effect.

You may have forgotten to recompile them into .elc files.
Then the old .elc files will be loaded, and your changes
will not be seen.  To fix this, do M-x byte-recompile-directory
and specify the directory that contains the Lisp files.

* rmail gets error getting new mail

rmail gets new mail from /usr/spool/mail/$USER using a program
called movemail.  This program interlocks with /bin/mail using
the protocol defined by /bin/mail, which involves creating a
lock file.  It must be able to write in /usr/spool/mail
in order to do this.

* Emacs spontaneously displays "I-search: " at the bottom of the screen.

This means that Control-S/Control-Q "flow control" is being used.
C-s/C-q flow control is bad for Emacs editors because it takes away
C-s and C-q as user commands.  Since editors do not output long streams
of text without user commands, there is no need for a user-issuable
"stop output" command in an editor; therefore, a properly designed
flow control mechanism would transmit all possible input characters
without interference.  Designing such a mechanism is easy, for a person
with at least half a brain.

There are three possible reasons why flow control could be taking place:

  1) Terminal has not been told to disable flow control
  2) Insufficient padding for the terminal in use
  3) Some sort of terminal concentrator or line switch is responsible

First of all, many terminals have a set-up mode which controls
whether they generate flow control characters.  This must be
set to "no flow control" in order for Emacs to work.  Sometimes
there is an escape sequence that the computer can send to turn
flow control off and on.  If so, perhaps the termcap `ti' string
should turn flow control off, and the `te' string should turn it on.

Once the terminal has been told "no flow control", you may find it
needs more padding.  The amount of padding Emacs sends is controlled
by the termcap entry for the terminal in use, and by the output baud
rate as known by the kernel.  The shell command `stty' will print
your output baud rate; `stty' with suitable arguments will set it if
it is wrong.  Setting to a higher speed causes increased padding.  If
the results are wrong for the correct speed, there is probably a
problem in the termcap entry.  You must speak to a local Unix wizard
to fix this.  Perhaps you are just using the wrong terminal type.

For terminals that lack a "no flow control" mode, sometimes just
giving lots of padding will prevent actual generation of flow control
codes.  You might as well try it.

If you are really unlucky, your terminal is connected to the computer
through a concentrator which sends flow control to the computer, or it
insists on sending flow control itself no matter how much padding you
give it.  You are screwed!  You should replace the terminal or
concentrator with a properly designed one.  In the mean time,
some drastic measures can make Emacs semi-work.

One drastic measure to ignore C-s and C-q, while sending enough
padding that the terminal will not really lose any output.
Ignoring C-s and C-q can be done by using keyboard-translate-table
to map them into an undefined character such as C-^ or C-\.  Sending
lots of padding is done by changing the termcap entry.

An even more drastic measure is to make Emacs understand flow control.
Do (set-input-mode nil t).  Emacs will then interpret C-s and C-q as
flow control commands.  You will lose the ability to use them for
Emacs commands.  Also, as a consequence of using CBREAK mode, the
terminal's Meta-key, if any, will not work, and C-g will be liable to
cause a loss of output which will produce garbage on the screen.  You
can use keyboard-translate-table to map two other input characters
(such as C-^ and C-\) into C-s and C-q, so that you can still search
and quote.

I have no intention of ever redisigning the Emacs command set for
the assumption that terminals use C-s/C-q flow control.  This
flow control technique is a bad design, and terminals that need
it are bad merchandise and should not be purchased.  If you can
get some use out of GNU Emacs on inferior terminals, I am glad,
but I will not make Emacs worse for properly designed systems
for the sake of inferior systems.

* Control-S and Control-Q commands are ignored completely.

For some reason, your system is using brain-damaged ^S/^Q flow
control despite Emacs's attempts to turn it off.  Perhaps your
terminal is connected to the computer through a concentrator
that wants to use flow control.

You should first try to tell the concentrator not to use flow control.
If you succeed in this, try making the terminal work without
flow control, as described in the preceding section.

If that line of approach is not successful, map some other characters
into C-s and C-q using keyboard-translate-table.  I suggest C-^ and
C-\.

* Screen is updated wrong, but only on one kind of terminal.

This could mean that the termcap entry you are using for that
terminal is wrong, or it could mean that Emacs has a bug handing
the combination of features specified for that terminal.

The first step in tracking this down is to record what characters
Emacs is sending to the terminal.  Execute the Lisp expression
(open-termscript "./emacs-script") to make Emacs write all
terminal output into the file ~/emacs-script as well; then do
what makes the screen update wrong, and look at the file
and decode the characters using the manual for the terminal.
There are several possibilities:

1) The characters sent are correct, according to the terminal manual.

In this case, there is no obvious bug in Emacs, and most likely you
need more padding, or possibly the terminal manual is wrong.

2) The characters sent are incorrect, due to an obscure aspect
 of the terminal behavior not described in an obvious way
 by termcap.

This case is hard.  It will be necessary to think of a way for
Emacs to distinguish between terminals with this kind of behavior
and other terminals that behave subtly differently but are
classified the same by termcap; or else find an algorithm for
Emacs to use that avoids the difference.  Such changes must be
tested on many kinds of terminals.

3) The termcap entry is wrong.

Watch out for termcap entries for VT100's that fail to specify
the sf string, or that omit the padding needed for the sf and sr
strings (2msec per line affected).

4) The characters sent are incorrect, and clearly cannot be
 right for any terminal with the termcap entry you were using.

This is unambiguously an Emacs bug, and can probably be fixed
in term.c, scroll.c, cm.c or dispnew.c.

* Output from Control-V is slow.

On many bit-map terminals, scrolling operations are fairly slow.
Often the termcap entry for the type of terminal in use fails
to inform Emacs of this.  The two lines at the bottom of the screen
before a Control-V command are supposed to appear at the top after
the Control-V command.  If Emacs thinks scrolling the lines is fast,
it will scroll them to the top of the screen.

If scrolling is slow but Emacs thinks it is fast, the usual reason is
that the termcap entry for the terminal you are using does not
specify any padding time for the `al' and `dl' strings.  Emacs
concludes that these operations take only as much time as it takes to
send the commands at whatever line speed you are using.  You must
fix the termcap entry to specify, for the `al' and `dl', as much
time as the operations really take.

Currently Emacs thinks in terms of serial lines which send characters
at a fixed rate, so that any operation which takes time for the
terminal to execute must also be padded.  With bit-map terminals
operated across networks, often the network provides some sort of
flow control so that padding is never needed no matter how slow
an operation is.  You must still specify a padding time if you want
Emacs to realize that the operation takes a long time.  This will
cause padding characters to be sent unnecessarily, but they do
not really cost much.  They will be transmitted while the scrolling
is happening and then discarded quickly by the terminal.

Most bit-map terminals provide commands for inserting or deleting
multiple lines at once.  Define the `AL' and `DL' strings in the
termcap entry to say how to do these things, and you will have
fast output without wasted padding characters.  These strings should
each contain a single %-spec saying how to send the number of lines
to be scrolled.  These %-specs are like those in the termcap
`cm' string.

You should also define the `IC' and `DC' strings if your terminal
has a command to insert or delete multiple characters.  These
take the number of positions to insert or delete as an argument.

* You type Control-H (Backspace) expecting to delete characters.

Put `stty dec' in your .login file and your problems will disappear
after a day or two.

The choice of Backspace for erasure was based on confusion,
caused by the fact that backspacing causes erasure on most
display terminals.  But it is a mistake.  Deletion of text
is not the same thing as backspacing followed by faulty overprinting.
I do not wish to propagate this confusion by conforming to it.

For this reason, I believe `stty dec' is the right mode to use,
and I have designed Emacs to go with that.  If there were a thousand
other control characters, I would define Control-h to delete as well;
but there are not very many other control characters, and I think
that providing the most mnemonic possible Help character is more
important than adapting to people who don't use `stty dec'.

If you are obstinate about confusing buggy overprinting with deletion,
you can redefine Backspace in your .emacs file:
  (global-set-key "\b" 'delete-backward-char)
You may then wish to put the function  help-command  on some
other key.  I leave to you the task of deciding which key.

* ld complains because `alloca' is not defined on your system.

Alloca is a library function in 4.2bsd, which is used very heavily by
GNU Emacs.  Use of malloc instead is very difficult, as you would have
to arrange for the storage to be freed, and do so even in the case of
a longjmp happening inside a subroutine.  Many subroutines in Emacs
can do longjmp.

Therefore, if your system does not have alloca, add a definition valid
for your CPU type to the file alloca.s.  alloca must be written in
assembler language.  I am happy to receive versions of alloca for
additional CPUs and add them to the distribution.

alloca (N) should return the address of an N-byte block of memory
added dynamically to the current stack frame.

* Vax C compiler bugs affecting Emacs.

You may get one of these problems compiling Emacs:

   foo.c line nnn: compiler error: no table entry for op STASG
   foo.c: fatal error in /lib/ccom

These are due to bugs in the C compiler; the code is valid C.
Unfortunately, the bugs are unpredictable: the same construct
may compile properly or trigger one of these bugs, depending
on what else is in the source file being compiled.  Even changes
in header files that should not affect the file being compiled
can affect whether the bug happens.  In addition, sometimes files
that compile correctly on one machine get this bug on another machine.

As a result, it is hard for me to make sure this bug will not affect
you.  I have attempted to find and alter these constructs, but more
can always appear.  However, I can tell you how to deal with it if it
should happen.  The bug comes from having an indexed reference to an
array of Lisp_Objects, as an argument in a function call:
  Lisp_Object *args;
  ...
   ... foo (5, args[i], ...)...
putting the argument into a temporary variable first, as in
  Lisp_Object *args;
  Lisp_Object tem;
  ...
   tem = args[i];
   ... foo (r, tem, ...)...
causes the problem to go away.
The `contents' field of a Lisp vector is an array of Lisp_Objects,
so you may see the problem happening with indexed references to that.

* 68000 C compiler problems

Various 68000 compilers have different problems.
These are some that have been observed.

** Using value of assignment expression on union type loses.
This means that  x = y = z;  or  foo (x = z);  does not work
if x is of type Lisp_Object.

** "cannot reclaim" error.

This means that an expression is too complicated.  You get the correct
line number in the error message.  The code must be rewritten with
simpler expressions.

** XCONS, XSTRING, etc macros produce incorrect code.

If temacs fails to run at all, this may be the cause.
Compile this test program and look at the assembler code:

struct foo { char x; unsigned int y : 24; };

lose (arg)
     struct foo arg;
{
  test ((int *) arg.y);
}

If the code is incorrect, your compiler has this problem.
In the XCONS, etc., macros in lisp.h you must replace (a).u.val with
((a).u.val + coercedummy) where coercedummy is declared as int.

* PC AT compiler problems

I am told this compiler fails to handle the comma operator.
I have eliminated many uses of the comma operator since
receiving that news, but I'm sure many more remain.

* C compilers lose on returning unions

I hear that some C compilers cannot handle returning
a union type.  Most of the functions in GNU Emacs return
type Lisp_Object, which is currently defined as a union.

This problem will not happen if the m-...h file for your type
of machine defines NO_UNION_TYPE.  That is the recommended setting now.