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.