cgit.sxemacs.org Git - sxemacs/blob - info/sxemacs/startup.texi

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