How to Compile, Link and Build GNU Emacs under VMS
==================================================

A runnable Emacs on VMS consists of two files, an exe file and a map
file.  (It also refers to a DOC file in the [-.etc] sibling directory.
These files are made automatically and kept straight by Emacs version
number.)

For an Emacs being built and tested, these files are `temacs.exe' and
`temacs.dump' in this directory.

For an installed Emacs, these files are `emacs.exe' and `emacs.dump' in
the directory above this one.  These names are known only in the file
`emacs.com', also in the [.vms] directory.

* Run emacs.com
  This sets up the logical names used by everything else.  You *must*
  run this first. 

* Run config.com.
  This will copy vmspaths.h to paths.h then copy [.src]config.h_in to
  config.h and edit it to use the correct version of VMS (4.0, 4.2, 4.4,
  or 5.5).  You should look over the contents of config.h to make sure
  you like the way things are set up.

* Run compile.com.
  This will recompile any files that need to be recompiled.  You can
  force it to recompile all C files by giving it an argument (any
  argument).  Or, you can run precomp.com to define a command `ccom'
  that can be used to compile any specific C file you want.

  If you compile with optimization, note that in compiler version 3.0
  there is a bug affecting inline functions.  So you must specify
  /OPTIMIZE=NOINLINE when compiling `dispnew.c'.  If you still have
  problems, try using /NOOPT. 

  Compilation will give you lots of warnings about symbols longer than
  30 characters.  You must just ignore them.  Alternatively, you can
  compile the C program `vms-pp.c' and run all the .C and .H files
  through that program and then compile the results.  (On VMS versions
  before 4.4, the program is called `vms_pp.c'.)

  ***If you use `vms-pp.c', please save the originals .c and .h files
  and distribute them rather than the transformed files if you wish to 
  distribute copies of Emacs.  Help minimize confusion!***

* Run link.com.
  This will link the compiled files into `temacs.exe'.  You will get
  lots of linker warnings telling you that there were compiler warnings.
  Just ignore them. 

* Run complink.com.
  This will compile and link the files in the [emacs.etc] directory.
  This must be done before `makedoc.com' can be run. 

* Run makedoc.com.
  This will create or update the file `[-.etc]doc.'.  This must be done
  if that file does not yet exist or if any of the Emacs C sources or
  preloaded Lisp sources has changed.  It must be done before
  `build.com' is run in order to take effect.

* Run build.com. 
  This runs `temacs.exe', initializes it and preloads some Lisp code, and
  dumps the map file `temacs.dump' containing a copy of all the impure
  storage after initialization. 

* Run testemacs.com.
  This defines the `runtemacs' command to run `temacs.exe' with its map
  file `temacs.dump'.  This step is optional, and allows you to test
  whether or not emacs is running.

To install an Emacs, rename `temacs.dump' as `[-]emacs.dump' and rename
  `temacs.exe' as `[-]emacs.exe'.