git.chise.org Git - chise/xemacs-chise.git.1/blob - man/xemacs/startup.texi

   1 @node Startup Paths, Basic, Command Switches, Top
   2 @comment  node-name,  next,  previous,  up
   3 @section How XEmacs finds Directories and Files
   4
   5 @cindex startup paths
   6 @cindex directories
   7
   8 XEmacs deals with a multitude of files during operation.  These files
   9 are spread over many directories, and XEmacs determines the location of
  10 most of these directories at startup and organizes them into various
  11 paths.  (A @dfn{path},
  12 @cindex path
  13 for the purposes of this section, is simply a list of directories which
  14 XEmacs searches successively in order to locate a file.)
  15
  16 @subsection XEmacs Directory Hierarchies
  17 @cindex hierarchies
  18 @cindex directory hierarchies
  19
  20 Many of the files XEmacs looks for are located within the XEmacs
  21 installation itself.  However, there are several views of what actually
  22 constitutes the "XEmacs installation": XEmacs may be run from the
  23 compilation directory, it may be installed into arbitrary directories,
  24 spread over several directories unrelated to each other.  Moreover, it
  25 may subsequently be moved to a different place.  (This last case is not
  26 as uncommon as it sounds.  Binary kits work this way.)  Consequently,
  27 XEmacs has quite complex procedures in place to find directories, no
  28 matter where they may be hidden.
  29
  30 XEmacs will always respect directory options passed to @code{configure}.
  31 However, if it cannot locate a directory at the configured place, it
  32 will initiate a search for the directory in any of a number of
  33 @dfn{hierarchies} rooted under a directory which XEmacs assumes contain
  34 parts of the XEmacs installation; it may locate several such hierarchies
  35 and search across them.  (Typically, there are just one or two
  36 hierarchies: the hierarchy where XEmacs was or will be installed, and
  37 the one where it is being built.)  Such a directory containing a
  38 hierarchy is called a @dfn{root}.
  39 @cindex root of a hierarchy
  40 Whenever this section refers to a directory using the shorthand
  41 @code{<root>}, it means that XEmacs searches for it under all
  42 hierarchies XEmacs was able to scrounge up.  In a
  43 running XEmacs, the hierarchy roots are stored in the variable
  44 @code{emacs-roots}.
  45 @vindex emacs-roots
  46
  47 @subsection Package Hierarchies
  48 @cindex package hierarchies
  49
  50 Many relevant directories and files XEmacs uses are actually not part of
  51 the core installation.  They are part of any of the many packages
  52 usually installed on top of an XEmacs installation.  (@xref{Packages}.)
  53 Hence, they play a prominent role in the various paths XEmacs sets up.
  54
  55 XEmacs locates packages in any of a number of package hierarchies.
  56 Package hierarchies fall into three groups: @dfn{early}, @dfn{late},
  57 and @dfn{last},
  58 @cindex early package hierarchies
  59 @cindex late package hierarchies
  60 @cindex last package hierarchies
  61 according to the relative location at which they show
  62 up in the various XEmacs paths.  Early package hierarchies are at the
  63 very front, late ones somewhere in the middle, and last hierarchies are
  64 (you guessed it) last.
  65
  66 By default, XEmacs expects an early package hierarchy in the
  67 subdirectory @file{.xemacs/xemacs-packages} of the user's home
  68 directory.
  69
  70 Moreover, XEmacs expects late hierarchies in the subdirectories
  71 @file{site-packages}, @file{mule-packages}, and @file{xemacs-packages}
  72 (in that order) of the @file{<root>/lib/xemacs} subdirectory of one of
  73 the installation hierarchies.  (If you run in-place, these are direct
  74 subdirectories of the build directory.)  Furthermore, XEmacs will also
  75 search these subdirectories in the @file{<root>/lib/xemacs-<VERSION>}
  76 subdirectory and prefer directories found there.
  77
  78 By default, XEmacs does not have a pre-configured last package
  79 hierarchy.  Last hierarchies are primarily for using package hierarchies
  80 of outdated versions of XEmacs as a fallback option.  For example, it is
  81 possible to run XEmacs 21 with the 20.4 package hierarchy as a last
  82 hierarchy.
  83
  84 It is possible to specify at configure-time the location of the various
  85 package hierarchies with the @code{--package-path} option to configure.
  86 @cindex package path
  87 The early, late, and last components of the package path are separated
  88 by double instead of single colons.  If all three components are
  89 present, they locate the early, late, and last package hierarchies
  90 respectively.  If two components are present, they locate the early and
  91 late hierarchies.  If only one component is present, it locates the
  92 late hierarchy.  At run time, the package path may also be specified via
  93 the @code{EMACSPACKAGEPATH} environment variable.
  94
  95 An XEmacs package is laid out just like a normal installed XEmacs lisp
  96 directory.  It may have @file{lisp}, @file{etc}, @file{info}, and
  97 @file{lib-src} subdirectories.  XEmacs adds these at appropriate places
  98 within the various system-wide paths.
  99
 100 There may be any number of package hierarchy directories.
 101
 102 @subsection Directories and Paths
 103 @cindex paths
 104
 105 Here is a list of the various directories and paths XEmacs tries to
 106 locate during startup.  XEmacs distinguishes between directories and
 107 paths specific to @dfn{version}, @dfn{site}, and @dfn{architecture}
 108 when looking for them.
 109
 110 @table @code
 111 @item version-specific
 112 @cindex version-specific directories
 113 directories are specific to the version of XEmacs they belong to and
 114 typically reside under @file{<root>/lib/xemacs-<VERSION>}.
 115 @item site-specific
 116 @cindex site-specific directories
 117 directories are independent of the version of XEmacs they belong to and
 118 typically reside under @file{<root>/lib/xemacs}
 119 @item architecture-specific
 120 @cindex architecture-specific directories
 121 directories are specific both to the version of XEmacs and the
 122 architecture it runs on and typically reside under
 123 @file{<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>}.
 124 @end table
 125
 126 During installation, all of these directories may also reside directly
 127 under @file{<root>}, because that is where they are in the XEmacs tarball.
 128
 129 If XEmacs runs with the @code{-debug-paths} option (@pxref{Command
 130 Switches}), it will print the values of these variables, hopefully
 131 aiding in debugging any problems which come up.
 132
 133 @table @code
 134
 135 @item lisp-directory
 136 @vindex lisp-directory
 137 Contains the version-specific location of the Lisp files that come with
 138 the core distribution of XEmacs.  XEmacs will search it recursively to a
 139 depth of 1 when setting up @code{load-path}.
 140
 141 @item load-path
 142 @vindex load-path
 143 Is where XEmacs searches for XEmacs Lisp files with commands like
 144 @code{load-library}.
 145 @findex load-library
 146 It contains the package lisp directories (see further down) and the
 147 version-specific core Lisp directories.  If the environment variable
 148 @code{EMACSLOADPATH} is set at startup, its directories are prepended to
 149 @code{load-path}.
 150 @vindex EMACSLOADPATH
 151
 152 @item Info-directory-list
 153 @vindex Info-directory-list
 154 Contains the location of info files.  (See @ref{(info)}.)  It contains
 155 the package info directories and the version-specific core
 156 documentation.  Moreover, XEmacs will add @file{/usr/info},
 157 @file{/usr/local/info} as well as the directories of the environment
 158 variable @code{INFOPATH}
 159 @vindex INFOPATH
 160 to @code{Info-directory-list}.
 161
 162 @item exec-directory
 163 @vindex exec-directory
 164 Is the directory of architecture-dependent files that come with XEmacs,
 165 especially executable programs intended for XEmacs to invoke.
 166
 167 @item exec-path
 168 @vindex exec-path
 169 Is the path for executables which XEmacs may want to start.  It contains
 170 the package executable paths as well as @code{exec-directory}, and the
 171 directories of the environment variables @code{PATH}
 172 @vindex PATH
 173 and @code{EMACSPATH}.
 174 @vindex EMACSPATH
 175
 176 @item doc-directory
 177 @vindex doc-directory
 178 Is the directory containing the architecture-specific @file{DOC} file
 179 that contains documentation for XEmacs' commands.
 180
 181 @item data-directory
 182 @vindex data-directory
 183 Is the version-specific directory that contains core data files XEmacs uses.
 184 It may be initialized from the @code{EMACSDATA}
 185 @vindex EMACSDATA
 186 environment variable.
 187
 188 @item data-directory-list
 189 @vindex data-directory-list
 190 Is the path where XEmacs looks for data files.  It contains package data
 191 directories as well as @code{data-directory}.
 192
 193 @end table
 194
 195