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.