Epoch Installation Guide
Copyright (c) 1992 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.

INFORMATION 

The Epoch distribution now includes code to build an ASCII version of
GNU Emacs 18.58.  This is installed in the Epoch etc directory and is
invoked directly from Epoch if Epoch is started with the "-nw" flag or
if the DISPLAY variable is unset.

By default, the top-level Makefile and 'build-install' script will
build and install the ASCII version of GNU Emacs in this manner.  If
this is acceptable, follow the steps under "PREPARATION".  If you have
Emacs installed separately elsewhere, you can avoid this by following
the steps under "INSTALLING WITHOUT ASCII".

It is also possible for Epoch to share the lisp directory with GNU
Emacs 18.58 installed elsewhere.  To do this, follow the steps under
"SHARING LISP DIRECTORY BETWEEN EPOCH AND EMACS"

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 Epoch.
 
1) Choose a place in the file structure for the main directory 
   of Epoch code to reside.  This will ultimately have
   subdirectories named src, lisp, etc, ascii, etc.  Call this name
   $EPOCH.  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.
   Repeat with $BUILD/ascii/config.h-dist and $BUILD/ascii/config.h.  

   If copying the config.h file from the src directory to the ascii
   directory, note that the selected include files should be called
   "../src/config/_____.h" rather than "config/_____.h".

   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) Declare the place in the file system where Epoch will
   be once installed.  This is done in the files `src/paths.h' and
   `ascii/paths.h'.

   If you are using the shell-script `build-install'
   edit the assignment for the variable `EPOCH'.
   If you are using `make' in the main Epoch directory to do
   the installation, edit the definition of `LIBDIR' in `Makefile'
   in that directory.  `build-install' and `make' edit `src/paths.h' and
   `ascii/paths.h' automatically.

   If you are doing the building by hand (not using `build-install' or
   `make') then you yourself must copy $BUILD/src/paths.h-dist to
   paths.h, and edit it to contain the correct directory names:
   $EPOCH/epoch-lisp:$EPOCH/lisp for the directory for Lisp 
   libraries, and $EPOCH/etc for the directory for executables and 
   text files.  Also, you must copy $BUILD/ascii/paths.h-dist to
   $BUILD/ascii/paths.h and edit accordingly.

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

   Depending on the location which you have the X window system
   installed, you may wish to alter the PATH_APPDEFAULT define in
   src/paths.h to the correct absolute path to the app-defaults
   directory. 

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 Epoch 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.
   For example, if you would like to compile with optimization,
   you might want to change the definition of CFLAGS in the files
   $BUILD/src/ymakefile and $BUILD/ascii/ymakefile to use C_OPTIMIZE_SWITCH
   instead of C_DEBUG_SWITCH.

   Note that many Unix compilers have bugs that affect -O; if you use
   -O, be prepared to recompile without -O if you have any trouble.

   Note that many (most?) versions of debuggers
   other than GDB do not know how to handle programs like Emacs
   that use raw or cbreak mode, change other terminal status bits,
   and use asynchronous SIGIO signals for terminal input.
   However, most debuggers may work if Emacs uses a separate terminal
   from the one being used by the debugger, or if Emacs is using
   its own X window.

   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 .

   With GCC, you can use -O and -g together.  The easiest way to do this
   is to change C_DEBUG_SWITCH to include both -O and -g.  GCC is probably
   more reliable with -O than without, as it is tested more with -O.

   If you are running on a system not supporting symbolic links, you
   will need to edit the MFLAGS variable in the top level Makefile so
   that MFLAGS = "LN=cp".  This is used to share files between the
   ascii and src directories. 
  
7) If you wish to compile with GCC, you should use -traditional.
   This is needed for certain include files.  For more info, refer
   the INSTALL file of GCC.

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

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

(On system V, you need to use `make install.sysv' instead of `make install'.
 On Xenix, use `make install.xenix'.
 On AIX, use `make install.aix'.
 You can also try `make INSTALL=./install.sh install'
 on any kind of system.)

The last step of building Emacs involves running Emacs in a special
way.  At this time, if the directories that Emacs will refer to during
use for Lisp code and executables do not already exist, Emacs will
print a warning to this effect.  If you plan to have `make' create
these directories while it installs Emacs, then do not be alarmed by
the warnings.

The shell script `build-install' is an alternative to `make install'.
It is a little less sophisticated than the makefile, but probably
easier to customize for nonstandard kinds of installation.  If you
want to install in precisely the usual fashion, we recommend using
`make' rather than `build-install'.

INSTALLING WITHOUT ASCII

To install Epoch and reference an alternate version of ASCII emacs, do
the following: (You will be unable to run the 'build-install' script)

1) Do steps 1 through 8 from above, ignoring everything in the
   $BUILD/ascii directory

2) Edit the $BUILD/src/paths.h and change the PATH_ASCII define to a
   string containing the absolute path to the GNU Emacs executable.

3) Run 'make no.ascii' in the main directory of the Epoch distribution
   to build and install Epoch.  You are done! 

SHARING LISP DIRECTORY BETWEEN EPOCH AND EMACS

Epoch may share the lisp directory with GNU Emacs 18.58 which has been
previously installed.  To install Epoch while sharing the lisp directory,
do the following:  (You will be unable to run the 'build-install'
script or the top-level Makefile)

1) Edit $BUILD/src/config.h as mentioned above.

2) Cd to $BUILD/etc and run 'make'.

3) Edit $BUILD/src/paths.h as mentioned above.  Note that
   PATH_LOADSEARCH must contain the absolute path to both the epoch-lisp
   and (shared) lisp directories, delimited by a ':'.

4) Edit $BUILD/src/ymakefile.  The definition for 'lispdir' should be
   changed to the absolute path to the shared lisp directory.

5) Run 'make' in the $BUILD/src directory.

6) The $BUILD/lisp directory may be removed if another copy is being used.

BUILDING EPOCH

The steps below are done by the shell script `build-install'
or by running `make' in the main directory of the Epoch 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/epoch which is the runnable Epoch,
   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 Epoch version.
   This file contains documentation strings for all the
   functions in Epoch.  Each time you run make to make a new epoch,
   a new DOC file with a new name is made.  You must keep
   the DOC file for an Epoch version as long as you keep using
   that Epoch version.

3) Cd to $BUILD/ascii and run `make'
  
INSTALLATION

The steps below are done by the shell script `build-install'
or by running `make' in the main directory of the Epoch distribution
to install Epoch.

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

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

   You can delete $EPOCH/src/temacs.

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

   The program $EPOCH/etc/wakeup is invoked by Epoch when appropriate.

   The programs $EPOCH/etc/make-docfile and $EPOCH/etc/test-distrib
   are not used any more; they were used in building Epoch.

   $EPOCH/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 the $EPOCH/src subdirectory, except for xemacs,
   are not used by Epoch once it is built.

5) The files in the $EPOCH/ascii subdirectory are not used once Epoch
   is built, and may be deleted.

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