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
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
14 for the purposes of this section, is simply a list of directories which
15 SXEmacs searches successively in order to locate a file.)
17 @subsection SXEmacs Directory Hierarchies
19 @cindex directory hierarchies
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.
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
48 @subsection Package Hierarchies
49 @cindex package hierarchies
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.
56 SXEmacs locates packages in any of a number of package hierarchies.
57 Package hierarchies fall into three groups: @dfn{early}, @dfn{late},
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.
67 By default, SXEmacs expects an early package hierarchy in the
68 subdirectory @file{.sxemacs/xemacs-packages} of the user's home
71 Moreover, SXEmacs expects late hierarchies in the subdirectories
72 @file{site-packages}, @file{mule-packages}, @file{xemacs-packages}, and
73 @file{sxemacs-packages} (in that order) of the @file{<root>/lib/sxemacs}
74 subdirectory of one of the installation hierarchies. (If you run
75 in-place, these are direct subdirectories of the build directory.)
76 Furthermore, SXEmacs will also search these subdirectories in the
77 @file{<root>/lib/sxemacs-<VERSION>} subdirectory and prefer directories
80 By default, SXEmacs does not have a pre-configured last package
81 hierarchy. Last hierarchies are primarily for using package hierarchies
82 of outdated versions of XEmacs as a fallback option. For example, it is
83 possible to run SXEmacs with the 20.4 package hierarchy as a last
86 It is possible to specify at configure-time the location of the various
87 package hierarchies with the @code{--package-path} option to configure.
89 The early, late, and last components of the package path are separated
90 by double instead of single colons. If all three components are
91 present, they locate the early, late, and last package hierarchies
92 respectively. If two components are present, they locate the early and
93 late hierarchies. If only one component is present, it locates the
94 late hierarchy. At run time, the package path may also be specified via
95 the @code{EMACSPACKAGEPATH} environment variable.
97 An SXEmacs package is laid out just like a normal installed SXEmacs lisp
98 directory. It may have @file{lisp}, @file{etc}, @file{info}, and
99 @file{lib-src} subdirectories. SXEmacs adds these at appropriate places
100 within the various system-wide paths.
102 There may be any number of package hierarchy directories.
104 @subsection Directories and Paths
107 Here is a list of the various directories and paths SXEmacs tries to
108 locate during startup. SXEmacs distinguishes between directories and
109 paths specific to @dfn{version}, @dfn{site}, and @dfn{architecture}
110 when looking for them.
113 @item version-specific
114 @cindex version-specific directories
115 directories are specific to the version of SXEmacs they belong to and
116 typically reside under @file{<root>/lib/sxemacs-<VERSION>}.
118 @cindex site-specific directories
119 directories are independent of the version of SXEmacs they belong to and
120 typically reside under @file{<root>/lib/sxemacs}
121 @item architecture-specific
122 @cindex architecture-specific directories
123 directories are specific both to the version of SXEmacs and the
124 architecture it runs on and typically reside under
125 @file{<root>/lib/sxemacs-<VERSION>/<ARCHITECTURE>}.
128 During installation, all of these directories may also reside directly
129 under @file{<root>}, because that is where they are in the SXEmacs tarball.
131 If SXEmacs runs with the @code{-debug-paths} option (@pxref{Command
132 Switches}), it will print the values of these variables, hopefully
133 aiding in debugging any problems which come up.
138 @vindex lisp-directory
139 Contains the version-specific location of the Lisp files that come with
140 the core distribution of SXEmacs. SXEmacs will search it recursively to a
141 depth of 1 when setting up @code{load-path}.
145 Is where SXEmacs searches for SXEmacs Lisp files with commands like
148 It contains the package lisp directories (see further down) and the
149 version-specific core Lisp directories. If the environment variable
150 @code{EMACSLOADPATH} is set at startup, its directories are prepended to
152 @vindex EMACSLOADPATH
154 @item Info-directory-list
155 @vindex Info-directory-list
156 Contains the location of info files. (See @ref{(info)}.) It contains
157 the package info directories and the version-specific core
158 documentation. Moreover, SXEmacs will add @file{/usr/info},
159 @file{/usr/local/info} as well as the directories of the environment
160 variable @code{INFOPATH}
162 to @code{Info-directory-list}.
165 @vindex exec-directory
166 Is the directory of architecture-dependent files that come with SXEmacs,
167 especially executable programs intended for SXEmacs to invoke.
171 Is the path for executables which SXEmacs may want to start. It contains
172 the package executable paths as well as @code{exec-directory}, and the
173 directories of the environment variables @code{PATH}
175 and @code{EMACSPATH}.
179 @vindex doc-directory
180 Is the directory containing the architecture-specific @file{DOC} file
181 that contains documentation for SXEmacs' commands.
184 @vindex data-directory
185 Is the version-specific directory that contains core data files SXEmacs uses.
186 It may be initialized from the @code{EMACSDATA}
188 environment variable.
190 @item data-directory-list
191 @vindex data-directory-list
192 Is the path where SXEmacs looks for data files. It contains package data
193 directories as well as @code{data-directory}.