Mercurial > hg > xemacs-beta

comparison man/xemacs/startup.texi @ 296:5a79be0ef6a8 r21-0b46

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-0b46
author cvs
date Mon, 13 Aug 2007 10:38:46 +0200
parents
children 9ea74add5d37
comparison
equal deleted inserted replaced
295:9d5da8baa111 296:5a79be0ef6a8
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 @emph{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 moved to a different place. (This last case is not as
26 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 @emph{hierachies} 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 @emph{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 under all 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: @emph{early}, @emph{late},
57 and @emph{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 a
67 subdirectory @file{.xemacs} of the user's home directory.
68
69 Moreover, XEmacs expects late hierarchies in the subdirectories
70 @file{site-packages}, @file{mule-packages}, and @file{xemacs-packages}
71 (in that order) of the @file{<root>/lib/xemacs} subdirectory of one of
72 the installation hierarchies. (If you run in-place, these are directr
73 subdirectories of the build directory.) Furthermore, XEmacs will also
74 search these subdirectories in the @file{<root>/lib/xemacs-<VERSION>}
75 subdirectory and prefer directories found there.
76
77 By default, XEmacs does not have a pre-configured last package
78 hierarchy. Last hierarchies are primarily for using package
79 hierarchies of outdated versions of XEmacs as a fallback option. For
80 example, it is possible to run XEmacs with the 20.4 package hierarchy
81 as a last hierarchy.
82
83 It is possible to specify at configure-time the location of the various
84 package hierarchies with the @code{--package-path} option to configure.
85 @cindex package path
86 The early, late, and last components of the package path are separated
87 by double instead of single colons. If three components are present,
88 they are locate the early, late, and last package hierarchies
89 respectively. If two components are present, they locate the early and
90 late hierarchies. If only one component is present, it locates the late
91 hierarchy. At run time, the package path may also be specified via the
92 @code{PACKAGEPATH} environment variable.
93
94 An XEmacs package is laid out just like a normal installed XEmacs lisp
95 directory. It may have @file{lisp}, @file{etc}, @file{info}, and
96 @file{lib-src} subdirectories. XEmacs adds these at appropriate places
97 within the various system-wide paths.
98
99 There may be any number of package hierarchy directories.
100
101 @subsection Directories and Paths
102 @cindex paths
103
104 Here is a list of the various directories and paths XEmacs tries to
105 locate during startup. XEmacs distinguishes between directories and
106 paths specific to @emph{version}, @emph{site}, and @emph{architecture}
107 when looking for them.
108
109 @table @code
110 @item version-specific
111 directories are specific to the version of XEmacs they belong to and
112 typically reside under @file{<root>/lib/xemacs-<VERSION>}.
113 @item site-specific
114 directories are independent of the version of XEmacs they belong to and
115 typically reside under @file{<root>/lib/xemacs}
116 @item architecture-specific
117 directories are specific both to the version of XEmacs and the
118 architecture it runs on and typically reside under
119 @file{<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>}.
120 @end table
121
122 During installation, all of these directories may also reside directly
123 under @file{<root>}, because that is where they are in the XEmacs tarball.
124
125 If XEmacs runs with the @code{-debug-paths} option (@xref{Command
126 Switches}), it will print the values of these variables, hopefully
127 aiding in debugging any problems which come up.
128
129 @table @code
130
131 @item lisp-directory
132 @vindex lisp-directory
133 Contains the version-specific location of the Lisp files that come with
134 the core distribution of XEmacs. XEmacs will search it recursively to a
135 depth of 1 when setting up @code{load-path}.
136
137 @item load-path
138 @vindex load-path
139 Is where XEmacs searches for XEmacs Lisp files with commands like
140 @code{load-library}.
141 @findex load-library
142 It contains the package lisp directories (see further down) and the
143 version-specific core Lisp directories. If the environment variable
144 @code{EMACSLOADPATH} is set at startup, its directories are prepended to
145 @code{load-path}.
146 @vindex EMACSLOADPATH
147
148 @item Info-directory-list
149 @vindex Info-directory-list
150 Contains the location of info files. (See @ref{(info)}.) It contains
151 the package info directories and the version-specific core
152 documentation. Moreover, XEmacs will add @file{/usr/info},
153 @file{/usr/local/info} as well as the directories of the environment
154 variable @code{INFOPATH}
155 @vindex INFOPATH
156 to @code{Info-directory-list}.
157
158 @item lock-directory
159 @itemx superlock-file
160 @vindex lock-directory
161 @vindex superlock-file
162 Are the site-specific locations of the lock directory and the superlock
163 file, respectively. The @code{lock-directory} variable may also be
164 initialized from the @code{EMACSLOCKDIR}
165 @vindex EMACSLOCKDIR
166 environment variable.
167
168 @item exec-directory
169 @vindex exec-directory
170 Is the directory of architecture-dependent files that come with XEmacs,
171 especially executable programs intended for XEmacs to invoke.
172
173 @item exec-path
174 @vindex exec-path
175 Is the path for executables which XEmacs may want to start. It contains
176 the package executable paths as well as @code{exec-directory}, and the
177 directories of the environment variables @code{PATH}
178 @vindex PATH
179 and @code{EMACSPATH}.
180 @vindex EMCSPATH
181
182 @item doc-directory
183 @vindex doc-directory
184 Is the directory containing the architecture-specific @file{DOC} file
185 that contains documentation for XEmacs' commands.
186
187 @item data-directory
188 @vindex data-directory
189 Is the version-specific directory that contains core data files XEmacs uses.
190 It may be initialized from the @code{EMACSDATA}
191 @vindex EMACSDATA
192 environment variable.
193
194 @item data-directory-list
195 @vindex data-directory-list
196 Is the path where XEmacs looks for data files. It contains package data
197 directories as well as @code{data-directory}.
198
199 @end table
200
201