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. PREPARATION 0) Make sure your system has enough swapping space allocated to handle a program whose pure code is 400k bytes and whose data area is at least 200k 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 the makefile run in step 6. 1) Edit src/config.h to set the right options for your system. 2) Edit src/paths.h to contain your name for the directory for Lisp libraries for Emacs and your name for the directory for runnable files and text files that Emacs refers to. Use the names for the directories where Emacs should refer to those files once it is built. During the process of building Emacs, these directories are referred to as ../lisp and ../etc (from the `src' subdirectory), so you need not move the `lisp' and `etc' subdirectory contents to their final locations before building a runnable Emacs. But the runnable Emacs itself will look for these files ONLY in the places specified in paths.h. 3) If you wish to place the info documentation structure in a directory that is not a sibling of the directory that is specified in step 2 for runnable and text files, create a file lisp/site-init.el containing (setq Info-directory "INFODIRECTORYFILENAME") If you are content to have these two directories as siblings, you need not do anything; that is the default. 4) Put into site-init.el any other Lisp code you want loaded into Emacs before it is dumped out. BUILDING GNU EMACS 1) Run `make' in the subdirectory named `etc'. This creates files named `ctags' and `etags' and `loadst' and `make-docfile'. 2) Run `make' in the subdirectory named `src'. This refers to files in the `lisp' and `etc' subdirectories using names ../lisp and ../etc. This creates a file named `xemacs' which is the runnable Emacs, assigning it a new version number by incrementing the version stored in ../lisp/version.el. It also creates a file in the ../etc directory 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 1) Move the file `src/xemacs' to a filename under which it can be run by users. You can delete the `src/temacs' file. 2) Move the `lisp', `etc' and `info' subdirectories' contents to the directories specified in PREPARATION steps 2 and 3. The newly built `xemacs' file expects to find things in the directories you specified in the paths.h file, not in ../lisp or ../etc. 3) Move the programs `ctags' and `etags' from the `etc' subdirectory to a directory in users' command search paths. These programs are run by users as shell commands. The program `loadst' is invoked by Emacs and should be moved to the directory specified in paths.h, along with the text files in the `etc' subdirectory. The program `make-docfile' is not needed any more; it was used to make the DOCSTR file. 4) The files in the `src' subdirectory, except for `xemacs', are not used by Emacs once it is built. LOSSAGES Known possible problems building GNU Emacs * Watch out for .emacs files and EMACS-LOAD-PATH environment vars These control the actions of Emacs. ~/.emacs is your Emacs init file. EMACS-LOAD-PATH 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. * 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. * 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 I have heard that GNU Emacs contains expressions that are "too complicated" for 68000 C compilers to handle. GNU Emacs has not yet been run successfully on a 68000, but work is being done on it. * 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. You might be able to get around this by redefining it as `long' and redefining the accessor macros (in lisp.h) to use shifting, anding and oring to extract and modify fields. * 68000 Random Lossages It has been observed that make-docfile, when invoked from src/Makefile, fails with error code 68. Nobody knows why this happens, because the when make-docfile is invoked with the same arguments from a separate shell script on the same system it works.