Info Catalog elisp: GNU Emacs Internals elisp: Pure Storage

elisp: Building Emacs

 
 E.1 Building Emacs
 ==================
 
 This section explains the steps involved in building the Emacs
 executable.  You don’t have to know this material to build and install
 Emacs, since the makefiles do all these things automatically.  This
 information is pertinent to Emacs developers.
 
    Building Emacs requires GNU Make version 3.81 or later.
 
    Compilation of the C source files in the ‘src’ directory produces an
 executable file called ‘temacs’, also called a “bare impure Emacs”.  It
 contains the Emacs Lisp interpreter and I/O routines, but not the
 editing commands.
 
    The command ‘temacs -l loadup’ would run ‘temacs’ and direct it to
 load ‘loadup.el’.  The ‘loadup’ library loads additional Lisp libraries,
 which set up the normal Emacs editing environment.  After this step, the
 Emacs executable is no longer “bare”.
 
    Because it takes some time to load the standard Lisp files, the
 ‘temacs’ executable usually isn’t run directly by users.  Instead, as
 one of the last steps of building Emacs, the command ‘temacs -batch -l
 loadup dump’ is run.  The special ‘dump’ argument causes ‘temacs’ to
 dump out an executable program, called ‘emacs’, which has all the
 standard Lisp files preloaded.  (The ‘-batch’ argument prevents ‘temacs’
 from trying to initialize any of its data on the terminal, so that the
 tables of terminal information are empty in the dumped Emacs.)
 
    The dumped ‘emacs’ executable (also called a “pure” Emacs) is the one
 which is installed.  The variable ‘preloaded-file-list’ stores a list of
 the Lisp files preloaded into the dumped Emacs.  If you port Emacs to a
 new operating system, and are not able to implement dumping, then Emacs
 must load ‘loadup.el’ each time it starts.
 
    You can specify additional files to preload by writing a library
 named ‘site-load.el’ that loads them.  You may need to rebuild Emacs
 with an added definition
 
      #define SITELOAD_PURESIZE_EXTRA N
 
 to make N added bytes of pure space to hold the additional files; see
 ‘src/puresize.h’.  (Try adding increments of 20000 until it is big
 enough.)  However, the advantage of preloading additional files
 decreases as machines get faster.  On modern machines, it is usually not
 advisable.
 
    After ‘loadup.el’ reads ‘site-load.el’, it finds the documentation
 strings for primitive and preloaded functions (and variables) in the
 file ‘etc/DOC’ where they are stored, by calling ‘Snarf-documentation’
 (Accessing Documentation Definition of Snarf-documentation.).
 
    You can specify other Lisp expressions to execute just before dumping
 by putting them in a library named ‘site-init.el’.  This file is
 executed after the documentation strings are found.
 
    If you want to preload function or variable definitions, there are
 three ways you can do this and make their documentation strings
 accessible when you subsequently run Emacs:
 
    • Arrange to scan these files when producing the ‘etc/DOC’ file, and
      load them with ‘site-load.el’.
 
    • Load the files with ‘site-init.el’, then copy the files into the
      installation directory for Lisp files when you install Emacs.
 
    • Specify a ‘nil’ value for ‘byte-compile-dynamic-docstrings’ as a
      local variable in each of these files, and load them with either
      ‘site-load.el’ or ‘site-init.el’.  (This method has the drawback
      that the documentation strings take up space in Emacs all the
      time.)
 
    It is not advisable to put anything in ‘site-load.el’ or
 ‘site-init.el’ that would alter any of the features that users expect in
 an ordinary unmodified Emacs.  If you feel you must override normal
 features for your site, do it with ‘default.el’, so that users can
 override your changes if they wish.  Startup Summary.  Note that
 if either ‘site-load.el’ or ‘site-init.el’ changes ‘load-path’, the
 changes will be lost after dumping.  Library Search.  To make a
 permanent change to ‘load-path’, use the ‘--enable-locallisppath’ option
 of ‘configure’.
 
    In a package that can be preloaded, it is sometimes necessary (or
 useful) to delay certain evaluations until Emacs subsequently starts up.
 The vast majority of such cases relate to the values of customizable
 variables.  For example, ‘tutorial-directory’ is a variable defined in
 ‘startup.el’, which is preloaded.  The default value is set based on
 ‘data-directory’.  The variable needs to access the value of
 ‘data-directory’ when Emacs starts, not when it is dumped, because the
 Emacs executable has probably been installed in a different location
 since it was dumped.
 
  -- Function: custom-initialize-delay symbol value
      This function delays the initialization of SYMBOL to the next Emacs
      start.  You normally use this function by specifying it as the
      ‘:initialize’ property of a customizable variable.  (The argument
      VALUE is unused, and is provided only for compatibility with the
      form Custom expects.)
 
    In the unlikely event that you need a more general functionality than
 ‘custom-initialize-delay’ provides, you can use ‘before-init-hook’
 (Startup Summary).
 
  -- Function: dump-emacs to-file from-file
      This function dumps the current state of Emacs into an executable
      file TO-FILE.  It takes symbols from FROM-FILE (this is normally
      the executable file ‘temacs’).
 
      If you want to use this function in an Emacs that was already
      dumped, you must run Emacs with ‘-batch’.
 

Info Catalog elisp: GNU Emacs Internals elisp: Pure Storage