This documents the MKDUMP EMACS library, which is currently
maintained by John Pershing <JPershing@BBNA>.

                         DUMPING MADE EASY

The problem -- slow startup:

The more an init or EVARS file customizes an EMACS environment, the
slower that EMACS is to start up.  Setting or creating variables,
connecting keys to functions, defining word abbrevs, creating
buffers, turning on modes -- the time for each is additive, with no
time discount for doing a lot of them.

Loading a library of extended commands and functions is by itself
fast, but a library may require certain variables or keys to be set
and this can happen automatically upon loading.  (A library may
have a specially named function in it for this purpose; M-X Load
Library will run that function automatically.)  Many libraries will
only set variables the first time they are loaded; the second load
into the same environment is fast, particularly important for a
temporarily loaded library, such as a mail reader.  Nevertheless,
that first load is a problem and some libraries are notoriously
slow loaders.

The solution -- dump the environment:

The structure of the customized environment can be saved in a
special disk file called a "dump", so that startup does not have to
build that structure again -- it only has to read in this file.
The dump is not an entire EMACS: since much of EMACS (and the Teco
inside it) is shared between different customizations, the dump
need only contain what is private to this customization.

The dump is actually a runnable job, containing not only the
environment structure but also some startup code will get the
shared parts of the original EMACS.  (Getting them is fast.)  When
it is through starting up, you have a job that looks like the
original dumped EMACS job.

The simplest use of MKDUMP:

The only preparation necessary to use MKDUMP is to insert the
following line into your init file, at the top before any library
loading (note that there are TWO Altmodes at the end of the line):

MM Run Library^[MKDUMP^[^[

Or if you have an EVARS file, insert this line into it, at the top:

*: MM Run Library^[MKDUMP^[^[

This will prepare EMACS for later dumping by causing M-X Load
Library to start remembering exactly where it finds the libraries
it loads.

To make a dumped EMACS job, first start up EMACS the normal way:

	:EMACS<cr>				(on ITS)
	EMACS<cr>				(on Tenex or Tops-20)

Then type:

	M-X Dump EMACS<cr>

This will write the dump to the file TS DEMACS (on ITS), DEMACS.EXE
(on Tops-20), or DEMACS.SAV (on Tenex) in your home directory.

The next time you want to run EMACS, you can run the dump:

	:DEMACS<cr>				(on ITS)
	DEMACS<cr>				(on Tenex or Tops-20)

The dump will start up, load the shared parts of TECO and EMACS,
and then execute the default EMACS init.  That will print the
normal greeting message and handle any JCL ("job command line",
i.e. anything else on the line you type to DDT/EXEC).  For instance
you can have EMACS initially visiting a file by:

	:DEMACS FILE NAME<cr>			(on ITS)
	DEMACS FILE.NAME<cr>			(on Tenex or Tops-20)

If you do not want the greeting message or JCL processing, give an
argument to the Dump EMACS command and make a dump that is still
faster in startup (not recommended in general, as the default init
performs certain necessary actions):

	C-U M-X Dump EMACS<cr>

If you want to write the dump to some other file than TS DEMACS or
DEMACS.EXE, give the filename as a string argument to the Dump
EMACS command, e.g.:

	M-X Dump EMACS^[TS DUMPTY<cr>		(on ITS)
	M-X Dump EMACS^[EMACHS.EXE<cr>		(on Tenex or Tops-20)

Note that M-X Dump EMACS will dump an exact image of the EMACS,
including any buffers that have been created and any files that
have been visited.  Therefore, we suggest that you make the dump
just after EMACS starts up the slow way, before the environment
becomes too cluttered.  You may want to load and then kill certain
libraries that are first-time slow loaders (e.g. BABYL): in the
dump, they will appear to have already been loaded once, and
therefore loading them into the dump will be fast.

Also note that you can dump a DEMACS job too.  For instance, you
might make a small change to your init or EVARS file, set some
variable say, and don't want to restart slowly just for that.
Instead, start a fresh DEMACS, set the variable, and then do M-X
Dump EMACS.

The costs -- disk space, fragility, and missing new releases:

The dump file is typically not very large, but it size depends on
the amount of customization: the number of variables, word abbrevs,
and buffers and the size of the text in each of these.  If you
simply reconnect keys and reset variables, the dump should be about
5 records on ITS, 10 pages on Tenex or Tops-20.  (Same space -- the
record sizes are different.)

Even if you don't read or fully understand the problems discussed
below, realize that the way to handle them is simple: when you
suspect the dump is not working correctly, throw it away and make
another one.  Start again from your init file, let it slowly (and
carefully) build the environment, and then dump.  The new dump
should be ok.  The kinds of (typically confusing) errors that can
indicate a problem with the dump are: the dump won't start up at
all, complaining that some file doesn't exist; you get an
"?Internal Error..." message on Tenex/Tops-20 and are left back at
the EXEC; or you get an "...attempted to macro a meaningless
number" error.  If after redumping, the error still occurs, it is
some problem with EMACS and not the dump.

The dumped environment structure critically depends on the identity
of the other parts of the EMACS job: the Teco base and the loaded
libraries.  These parts are not included in the dump, but they are
referenced by it.  If any of them change or disappear, the dump
will not work.  Their identities are determined and recorded in the
dump by their real, full filenames.  (The filename includes any
version number, and will always be the file's name, rather than the
name of a link.  For example, M-x Load Library^[WORDAB<cr> checks
for DSK:EMACS;WORDAB ^Q:EJ, and finds it a link to DSK:EMACS;[WORD]
607.  The filename recorded in the dump is DSK:EMACS;[WORD] 607.)

Some libraries on ITS do not have version numbers, and thus new
releases of those libraries are indistinguishable by the dump.
When that dump environment tries to reference something in that
library, an error will occur.  (Note that on ITS some of the
commonly dumped libraries have versions: the basic EMACS library,
WORDAB, and TMACS.  On Twenex/Tenex, all libraries have version
numbers.)

A new release of a library with version numbers will not interfere
with a dump, but on the other hand you will not be using that new
release -- you will still be using the old one.  Thus to get the
benefit of the new bug fixes and features you will have to watch
for releases and then start from the init and redump.