GNU Emacs Installation Guide
Copyright (c) 1988 Free software Foundation, Inc.

   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 the activities
   of the Free Software Foundation are approved by the Foundation.


PREPARATION

0) Make sure your system has enough swapping space allocated
 to handle a program whose pure code is 400k bytes or
 and whose data area is at least 150k and can reach 600k
 bytes or much more.  If the swapping space is insufficient, you
 will get an error in the command temacs -l loadup inc dump,
 found in $BUILD/src/ymakefile, or possibly when running the
 final dumped Emacs.
 
 Lucid GNU Emacs requires an ANSI C compiler, such as GCC.

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 $BUILD/src/config.h,
 and edit it to set the right options for your system.  The file
 $BUILD/etc/MACHINES may help you decide what to put there.
 If you need to override any of the definitions in the s- and m-
 files for your system and machine, do so by editing config.h,
 not by changing the s- and m- files.  Occasionally you may
 need to redefine parameters used in etc/movemail.c.

3) If you wish, you may declare the place in the file system where 
 Emacs will be once installed.  This is done in the file `src/paths.h'.
 This is no longer necessary, as emacs will figure out where it (and
 its associated runtime support files) are at startup time.

 If you are using the shell-script `build-install'
 edit the `set' command that sets the variable `EMACS'.
 If you are using `make' in the main Emacs directory to do
 the installation, edit the definition of `LIBDIR' in `Makefile'
 in that directory.  `build-install' and `make' edit `src/paths.h'
 automatically.

 If you are doing the building by hand (not using `build-install' or
 `make') and you want to hardwire pathnames into emacs, then you yourself
 must 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.

 You may leave paths.h empty; if pathnames are not specified in paths.h,
 then emacs will search the directory tree near where its executable is
 located for likely-looking candidates for the lisp and etc directories.

4) Look at $BUILD/lisp/paths.el; if some of those values
 are not right for your system, create a file
 $BUILD/lisp/site-init.el containing Lisp code to override them.
 You would use the Lisp function `setq'.  For example,

     (setq news-inews-program "/usr/bin/inews")

 is how you would override the default value of the
 variable news-inews-program (which is "/usr/local/inews").

5) 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.

6) Decide what compiler switches to use.
 You might want to replace the `-g' in the file $BUILD/src/ymakefile
 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.
  
7) Refer to the file $BUILD/etc/TERMS for information on
 fields you may wish to add to various termcap entries.

8) Edit the file $BUILD/src/lwlib/Imakefile, and set the parameters you
 desire.  

9) The directory $BUILD/src/lwlib/ contains a library of X routines that
 emacs uses.  You must compile this directory with an ANSI compiler, such 
 as GCC.  However, the Makefile in this directory is automatically generated
 using the `imake' program (a standard part of X.)  If you have not installed
 X in such a way that `imake' generates Makefiles that use GCC, then you 
 will have to edit the Makefile by hand after it has been automatically
 generated.

 This will be made easier in the future.

10) Run `make' in the main directory of the Emacs distribution
 to finish building and installing Emacs in the standard way.
 You are done!


BUILDING GNU EMACS
The steps below are done by the shell script `build-install'
or by running `make' in the main directory of the Emacs distribution.

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

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
 DOC 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 DOC file with a new name is made.  You must keep
 the DOC 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'
or by running `make' in the main directory of the Emacs distribution.

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.

 NOTE: if you have not hardwired pathnames into paths.h (and it is 
 recommended that you do not) then emacs needs to be able to find
 its lisp/ and etc/ directories.  The files $EMACS/lisp and $EMACS/etc
 must exist, and must be the appropriate directories or symbolic links
 to the appropriate directories, or emacs will not function correctly
 (if at all.)

 If the emacs executable in $EMACS/ is itself a symbolic link, then
 the lisp/ and etc/ directories may be in the directory of the file
 to which $EMACS/emacs is a link.

 If emacs does not find lisp/ and etc/ directories near where its
 executable is, then it will try /usr/local/lib/emacs/lisp/ and
 /usr/local/emacs/lisp/ as a last resort.  If these directories exist,
 but correspond to an older version of emacs (such as version 18) then
 emacs will not function correctly (if at all.)

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 used in building Emacs.

 $EMACS/etc/digest-doc can be used to convert DOC 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.


See the file PROBLEMS in this directory for a list of various
problems sometimes encountered, and what to do about them.
