Mercurial > hg > xemacs-beta
annotate man/xemacs/startup.texi @ 5169:6c6d78781d59
cleanup of code related to xfree(), better KKCC backtrace capabilities, document XD_INLINE_LISP_OBJECT_BLOCK_PTR, fix some memory leaks, other code cleanup
-------------------- ChangeLog entries follow: --------------------
src/ChangeLog addition:
2010-03-24 Ben Wing <ben@xemacs.org>
* array.h:
* array.h (XD_LISP_DYNARR_DESC):
* dumper.c (pdump_register_sub):
* dumper.c (pdump_store_new_pointer_offsets):
* dumper.c (pdump_reloc_one_mc):
* elhash.c:
* gc.c (lispdesc_one_description_line_size):
* gc.c (kkcc_marking):
* lrecord.h:
* lrecord.h (IF_NEW_GC):
* lrecord.h (enum memory_description_type):
* lrecord.h (enum data_description_entry_flags):
* lrecord.h (struct opaque_convert_functions):
Rename XD_LISP_OBJECT_BLOCK_PTR to XD_INLINE_LISP_OBJECT_BLOCK_PTR
and document it in lrecord.h.
* data.c:
* data.c (finish_marking_weak_lists):
* data.c (continue_marking_ephemerons):
* data.c (finish_marking_ephemerons):
* elhash.c (MARK_OBJ):
* gc.c:
* gc.c (lispdesc_indirect_count_1):
* gc.c (struct):
* gc.c (kkcc_bt_push):
* gc.c (kkcc_gc_stack_push):
* gc.c (kkcc_gc_stack_push_lisp_object):
* gc.c (kkcc_gc_stack_repush_dirty_object):
* gc.c (KKCC_DO_CHECK_FREE):
* gc.c (mark_object_maybe_checking_free):
* gc.c (mark_struct_contents):
* gc.c (mark_lisp_object_block_contents):
* gc.c (register_for_finalization):
* gc.c (mark_object):
* gc.h:
* lisp.h:
* profile.c:
* profile.c (mark_profiling_info_maphash):
Clean up KKCC code related to DEBUG_XEMACS. Rename
kkcc_backtrace() to kkcc_backtrace_1() and add two params: a
`size' arg to control how many stack elements to print and a
`detailed' arg to control whether Lisp objects are printed using
`debug_print()'. Create front-ends to kkcc_backtrace_1() --
kkcc_detailed_backtrace(), kkcc_short_backtrace(),
kkcc_detailed_backtrace_full(), kkcc_short_backtrace_full(), as
well as shortened versions kbt(), kbts(), kbtf(), kbtsf() -- to
call it with various parameter values. Add an `is_lisp' field to
the stack and backtrace structures and use it to keep track of
whether an object pushed onto the stack is a Lisp object or a
non-Lisp structure; in kkcc_backtrace_1(), don't try to print a
non-Lisp structure as a Lisp object.
* elhash.c:
* extents.c:
* file-coding.c:
* lrecord.h:
* lrecord.h (IF_NEW_GC):
* marker.c:
* marker.c (Fmarker_buffer):
* mule-coding.c:
* number.c:
* rangetab.c:
* specifier.c:
New macros IF_OLD_GC(), IF_NEW_GC() to simplify declaration of
Lisp objects when a finalizer may exist in one but not the other.
Use them appropriately.
* extents.c (finalize_extent_info):
Don't zero out data->soe and data->extents before trying to free,
else we get memory leaks.
* lrecord.h (enum lrecord_type):
Make the first lrecord type have value 1 not 0 so that 0 remains
without implementation and attempts to interpret zeroed memory
as a Lisp object will be more obvious.
* array.c (Dynarr_free):
* device-msw.c (msprinter_delete_device):
* device-tty.c (free_tty_device_struct):
* device-tty.c (tty_delete_device):
* dialog-msw.c (handle_directory_dialog_box):
* dialog-x.c:
* emacs.c (free_argc_argv):
* emodules.c (attempt_module_delete):
* file-coding.c (chain_finalize_coding_stream_1):
* file-coding.c (chain_finalize_coding_stream):
* glyphs-eimage.c:
* glyphs-eimage.c (jpeg_instantiate_unwind):
* glyphs-eimage.c (gif_instantiate_unwind):
* glyphs-eimage.c (png_instantiate_unwind):
* glyphs-eimage.c (tiff_instantiate_unwind):
* imgproc.c:
* imgproc.c (build_EImage_quantable):
* insdel.c (uninit_buffer_text):
* mule-coding.c (iso2022_finalize_detection_state):
* objects-tty.c (tty_finalize_color_instance):
* objects-tty.c (tty_finalize_font_instance):
* objects-tty.c (tty_font_list):
* process.c:
* process.c (finalize_process):
* redisplay.c (add_propagation_runes):
* scrollbar-gtk.c:
* scrollbar-gtk.c (gtk_free_scrollbar_instance):
* scrollbar-gtk.c (gtk_release_scrollbar_instance):
* scrollbar-msw.c:
* scrollbar-msw.c (mswindows_free_scrollbar_instance):
* scrollbar-msw.c (unshow_that_mofo):
* scrollbar-x.c (x_free_scrollbar_instance):
* scrollbar-x.c (x_release_scrollbar_instance):
* select-x.c:
* select-x.c (x_handle_selection_request):
* syntax.c:
* syntax.c (uninit_buffer_syntax_cache):
* text.h (eifree):
If possible, whenever we call xfree() on a field in a structure,
set the field to 0 afterwards. A lot of code is written so that
it checks the value being freed to see if it is non-zero before
freeing it -- doing this and setting the value to 0 afterwards
ensures (a) we won't try to free twice if the cleanup code is
called twice; (b) if the object itself stays around, KKCC won't
crash when attempting to mark the freed field.
* rangetab.c:
Add a finalization method when not NEW_GC to avoid memory leaks.
(#### We still get memory leaks when NEW_GC; need to convert gap
array to Lisp object).
author | Ben Wing <ben@xemacs.org> |
---|---|
date | Wed, 24 Mar 2010 01:22:51 -0500 |
parents | 9c4bf82eaac2 |
children |
rev | line source |
---|---|
444 | 1 @node Startup Paths, Packages, Command Switches, Top |
428 | 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 | |
442 | 42 hierarchies XEmacs was able to scrounge up. In a |
428 | 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 | |
442 | 66 By default, XEmacs expects an early package hierarchy in the |
67 subdirectory @file{.xemacs/xemacs-packages} of the user's home | |
68 directory. | |
428 | 69 |
70 Moreover, XEmacs expects late hierarchies in the subdirectories | |
71 @file{site-packages}, @file{mule-packages}, and @file{xemacs-packages} | |
5148
9c4bf82eaac2
Reflect change from `lib' to `share' in docs.
Mike Sperber <sperber@deinprogramm.de>
parents:
3179
diff
changeset
|
72 (in that order) of the @file{<root>/share/xemacs} subdirectory of one of |
428 | 73 the installation hierarchies. (If you run in-place, these are direct |
74 subdirectories of the build directory.) Furthermore, XEmacs will also | |
5148
9c4bf82eaac2
Reflect change from `lib' to `share' in docs.
Mike Sperber <sperber@deinprogramm.de>
parents:
3179
diff
changeset
|
75 search these subdirectories in the @file{<root>/share/xemacs-<VERSION>} |
428 | 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 | |
442 | 81 possible to run XEmacs 21 with the 20.4 package hierarchy as a last |
428 | 82 hierarchy. |
83 | |
84 It is possible to specify at configure-time the location of the various | |
3179 | 85 package directories with the @code{--with-user-packages} (an alias for |
86 @samp{--with-early-packages}), @code{--with-system-packages} (an alias | |
87 for @samp{--with-late-packages}), and @code{--with-legacy-packages} (an | |
88 alias for @samp{--with-last-packages}) options to configure. | |
428 | 89 @cindex package path |
3179 | 90 At run time, the package directories may also be specified via the |
91 @code{EMACSEARLYPACKAGES}, @code{EMACSLATEPACKAGES}, and | |
92 @code{EMACSLASTPACKAGES} environment variables. | |
428 | 93 |
1183 | 94 An XEmacs package hierarchy is laid out just like a normal installed |
1258 | 95 XEmacs directory. It may have @file{lisp}, @file{etc}, @file{info}, and |
96 @file{lib-src} subdirectories. (The @file{lib-src} subdirectory | |
97 contains architecture-independent general-purpose scripts interpreted by | |
98 the shell or Perl. Java is also being widely used, but Java programs | |
99 are generally found under @file{etc}, because they are specific to | |
100 particular packages such as @file{JDE} and @file{xslt}.) XEmacs adds | |
101 these at appropriate places within the various system-wide paths. | |
428 | 102 |
103 There may be any number of package hierarchy directories. | |
104 | |
105 @subsection Directories and Paths | |
106 @cindex paths | |
107 | |
108 Here is a list of the various directories and paths XEmacs tries to | |
109 locate during startup. XEmacs distinguishes between directories and | |
110 paths specific to @dfn{version}, @dfn{site}, and @dfn{architecture} | |
111 when looking for them. | |
112 | |
113 @table @code | |
114 @item version-specific | |
115 @cindex version-specific directories | |
5148
9c4bf82eaac2
Reflect change from `lib' to `share' in docs.
Mike Sperber <sperber@deinprogramm.de>
parents:
3179
diff
changeset
|
116 directories (such as @file{etc}, the @file{info} of the installed XEmacs |
9c4bf82eaac2
Reflect change from `lib' to `share' in docs.
Mike Sperber <sperber@deinprogramm.de>
parents:
3179
diff
changeset
|
117 and its Lisp files in @file{lisp}) are specific to the version of XEmacs |
9c4bf82eaac2
Reflect change from `lib' to `share' in docs.
Mike Sperber <sperber@deinprogramm.de>
parents:
3179
diff
changeset
|
118 they belong to and typically reside under |
9c4bf82eaac2
Reflect change from `lib' to `share' in docs.
Mike Sperber <sperber@deinprogramm.de>
parents:
3179
diff
changeset
|
119 @file{<root>/share/xemacs-<VERSION>}. |
428 | 120 @item site-specific |
121 @cindex site-specific directories | |
5148
9c4bf82eaac2
Reflect change from `lib' to `share' in docs.
Mike Sperber <sperber@deinprogramm.de>
parents:
3179
diff
changeset
|
122 directories are independent of the version of XEmacs and |
9c4bf82eaac2
Reflect change from `lib' to `share' in docs.
Mike Sperber <sperber@deinprogramm.de>
parents:
3179
diff
changeset
|
123 typically reside under @file{<root>/share/xemacs}. |
428 | 124 @item architecture-specific |
125 @cindex architecture-specific directories | |
126 directories are specific both to the version of XEmacs and the | |
127 architecture it runs on and typically reside under | |
128 @file{<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>}. | |
129 @end table | |
130 | |
131 During installation, all of these directories may also reside directly | |
132 under @file{<root>}, because that is where they are in the XEmacs tarball. | |
133 | |
134 If XEmacs runs with the @code{-debug-paths} option (@pxref{Command | |
135 Switches}), it will print the values of these variables, hopefully | |
136 aiding in debugging any problems which come up. | |
137 | |
138 @table @code | |
139 | |
140 @item lisp-directory | |
141 @vindex lisp-directory | |
142 Contains the version-specific location of the Lisp files that come with | |
143 the core distribution of XEmacs. XEmacs will search it recursively to a | |
144 depth of 1 when setting up @code{load-path}. | |
145 | |
146 @item load-path | |
147 @vindex load-path | |
148 Is where XEmacs searches for XEmacs Lisp files with commands like | |
149 @code{load-library}. | |
150 @findex load-library | |
151 It contains the package lisp directories (see further down) and the | |
152 version-specific core Lisp directories. If the environment variable | |
153 @code{EMACSLOADPATH} is set at startup, its directories are prepended to | |
154 @code{load-path}. | |
155 @vindex EMACSLOADPATH | |
156 | |
157 @item Info-directory-list | |
158 @vindex Info-directory-list | |
159 Contains the location of info files. (See @ref{(info)}.) It contains | |
160 the package info directories and the version-specific core | |
161 documentation. Moreover, XEmacs will add @file{/usr/info}, | |
162 @file{/usr/local/info} as well as the directories of the environment | |
163 variable @code{INFOPATH} | |
164 @vindex INFOPATH | |
165 to @code{Info-directory-list}. | |
166 | |
167 @item exec-directory | |
168 @vindex exec-directory | |
169 Is the directory of architecture-dependent files that come with XEmacs, | |
170 especially executable programs intended for XEmacs to invoke. | |
171 | |
172 @item exec-path | |
173 @vindex exec-path | |
174 Is the path for executables which XEmacs may want to start. It contains | |
175 the package executable paths as well as @code{exec-directory}, and the | |
176 directories of the environment variables @code{PATH} | |
177 @vindex PATH | |
178 and @code{EMACSPATH}. | |
179 @vindex EMACSPATH | |
180 | |
181 @item doc-directory | |
182 @vindex doc-directory | |
183 Is the directory containing the architecture-specific @file{DOC} file | |
184 that contains documentation for XEmacs' commands. | |
185 | |
186 @item data-directory | |
187 @vindex data-directory | |
188 Is the version-specific directory that contains core data files XEmacs uses. | |
189 It may be initialized from the @code{EMACSDATA} | |
190 @vindex EMACSDATA | |
191 environment variable. | |
192 | |
193 @item data-directory-list | |
194 @vindex data-directory-list | |
195 Is the path where XEmacs looks for data files. It contains package data | |
196 directories as well as @code{data-directory}. | |
197 | |
198 @end table | |
199 | |
200 |