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 includes code to build both X and ASCII
versions; the ASCII version is equivalent to GNU Emacs 18.58 (with no
X or Epoch extensions).  

The ASCII version 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 environment variable is unset.

By default, the top-level Makefile and 'build-install' script will
build and install the ASCII version of Epoch in this manner.  If this
is acceptable, follow the steps under "PREPARATION".  If you have GNU
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

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.
   
   NOTE: It is *NOT* possible to build the ASCII version of Epoch with
   X support; be certain that you do not have HAVE_X_WINDOWS defined
   in $BUILD/ascii/config.h (by default, it is not).

   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.
        
   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 some 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 Epoch involves running Epoch in a special
way.  At this time, if the directories that Epoch will refer to during
use for Lisp code and executables do not already exist, Epoch will
print a warning to this effect.  If you plan to have `make' create
these directories while it installs Epoch, 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 it is
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! 

(If you know that ASCII Emacs will never be invoked, then you can just
omit step 2 above.)


SHARING LISP DIRECTORY BETWEEN EPOCH AND EMACS

Epoch may share the lisp directory with a copy of 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 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.
