Mercurial > hg > xemacs-beta
annotate man/beta.texi @ 5157:1fae11d56ad2
redo memory-usage mechanism, add way of dynamically initializing Lisp objects
-------------------- ChangeLog entries follow: --------------------
lisp/ChangeLog addition:
2010-03-18 Ben Wing <ben@xemacs.org>
* diagnose.el (show-memory-usage):
Rewrite to take into account API changes in memory-usage functions.
src/ChangeLog addition:
2010-03-18 Ben Wing <ben@xemacs.org>
* alloc.c:
* alloc.c (disksave_object_finalization_1):
* alloc.c (lisp_object_storage_size):
* alloc.c (listu):
* alloc.c (listn):
* alloc.c (Fobject_memory_usage_stats):
* alloc.c (compute_memusage_stats_length):
* alloc.c (Fobject_memory_usage):
* alloc.c (Ftotal_object_memory_usage):
* alloc.c (malloced_storage_size):
* alloc.c (common_init_alloc_early):
* alloc.c (reinit_alloc_objects_early):
* alloc.c (reinit_alloc_early):
* alloc.c (init_alloc_once_early):
* alloc.c (syms_of_alloc):
* alloc.c (reinit_vars_of_alloc):
* buffer.c:
* buffer.c (struct buffer_stats):
* buffer.c (compute_buffer_text_usage):
* buffer.c (compute_buffer_usage):
* buffer.c (buffer_memory_usage):
* buffer.c (buffer_objects_create):
* buffer.c (syms_of_buffer):
* buffer.c (vars_of_buffer):
* console-impl.h (struct console_methods):
* dynarr.c (Dynarr_memory_usage):
* emacs.c (main_1):
* events.c (clear_event_resource):
* extents.c:
* extents.c (compute_buffer_extent_usage):
* extents.c (extent_objects_create):
* extents.h:
* faces.c:
* faces.c (compute_face_cachel_usage):
* faces.c (face_objects_create):
* faces.h:
* general-slots.h:
* glyphs.c:
* glyphs.c (compute_glyph_cachel_usage):
* glyphs.c (glyph_objects_create):
* glyphs.h:
* lisp.h:
* lisp.h (struct usage_stats):
* lrecord.h:
* lrecord.h (enum lrecord_type):
* lrecord.h (struct lrecord_implementation):
* lrecord.h (MC_ALLOC_CALL_FINALIZER_FOR_DISKSAVE):
* lrecord.h (DEFINE_DUMPABLE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_FROB_BLOCK_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_FROB_BLOCK_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_INTERNAL_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_SIZABLE_INTERNAL_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_FROB_BLOCK_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_FROB_BLOCK_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_INTERNAL_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_SIZABLE_INTERNAL_LISP_OBJECT):
* lrecord.h (MAKE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_MODULE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_MODULE_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_MODULE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_MODULE_SIZABLE_LISP_OBJECT):
* lrecord.h (MAKE_MODULE_LISP_OBJECT):
* lrecord.h (INIT_LISP_OBJECT):
* lrecord.h (INIT_MODULE_LISP_OBJECT):
* lrecord.h (UNDEF_LISP_OBJECT):
* lrecord.h (UNDEF_MODULE_LISP_OBJECT):
* lrecord.h (DECLARE_LISP_OBJECT):
* lrecord.h (DECLARE_MODULE_API_LISP_OBJECT):
* lrecord.h (DECLARE_MODULE_LISP_OBJECT):
* lstream.c:
* lstream.c (syms_of_lstream):
* lstream.c (vars_of_lstream):
* marker.c:
* marker.c (compute_buffer_marker_usage):
* mc-alloc.c (mc_alloced_storage_size):
* mc-alloc.h:
* mule-charset.c:
* mule-charset.c (struct charset_stats):
* mule-charset.c (compute_charset_usage):
* mule-charset.c (charset_memory_usage):
* mule-charset.c (mule_charset_objects_create):
* mule-charset.c (syms_of_mule_charset):
* mule-charset.c (vars_of_mule_charset):
* redisplay.c:
* redisplay.c (compute_rune_dynarr_usage):
* redisplay.c (compute_display_block_dynarr_usage):
* redisplay.c (compute_glyph_block_dynarr_usage):
* redisplay.c (compute_display_line_dynarr_usage):
* redisplay.c (compute_line_start_cache_dynarr_usage):
* redisplay.h:
* scrollbar-gtk.c (gtk_compute_scrollbar_instance_usage):
* scrollbar-msw.c (mswindows_compute_scrollbar_instance_usage):
* scrollbar-x.c (x_compute_scrollbar_instance_usage):
* scrollbar.c (compute_scrollbar_instance_usage):
* scrollbar.h:
* symbols.c:
* symbols.c (reinit_symbol_objects_early):
* symbols.c (init_symbols_once_early):
* symbols.c (reinit_symbols_early):
* symbols.c (defsymbol_massage_name_1):
* symsinit.h:
* ui-gtk.c:
* ui-gtk.c (emacs_gtk_object_getprop):
* ui-gtk.c (emacs_gtk_object_putprop):
* ui-gtk.c (ui_gtk_objects_create):
* unicode.c (compute_from_unicode_table_size_1):
* unicode.c (compute_to_unicode_table_size_1):
* unicode.c (compute_from_unicode_table_size):
* unicode.c (compute_to_unicode_table_size):
* window.c:
* window.c (struct window_stats):
* window.c (compute_window_mirror_usage):
* window.c (compute_window_usage):
* window.c (window_memory_usage):
* window.c (window_objects_create):
* window.c (syms_of_window):
* window.c (vars_of_window):
* window.h:
Redo memory-usage mechanism, make it general; add way of dynamically
initializing Lisp object types -- OBJECT_HAS_METHOD(), similar to
CONSOLE_HAS_METHOD().
(1) Create OBJECT_HAS_METHOD(), OBJECT_HAS_PROPERTY() etc. for
specifying that a Lisp object type has a particular method or
property. Call such methods with OBJECT_METH, MAYBE_OBJECT_METH,
OBJECT_METH_OR_GIVEN; retrieve properties with OBJECT_PROPERTY.
Methods that formerly required a DEFINE_*GENERAL_LISP_OBJECT() to
specify them (getprop, putprop, remprop, plist, disksave) now
instead use the dynamic-method mechanism. The main benefit of
this is that new methods or properties can be added without
requiring that the declaration statements of all existing methods
be modified. We have to make the `struct lrecord_implementation'
non-const, but I don't think this should have any effect on speed --
the only possible method that's really speed-critical is the
mark method, and we already extract those out into a separate
(non-const) array for increased cache locality.
Object methods need to be reinitialized after pdump, so we put
them in separate functions such as face_objects_create(),
extent_objects_create() and call them appropriately from emacs.c
The only current object property (`memusage_stats_list') that
objects can specify is a Lisp object and gets staticpro()ed so it
only needs to be set during dump time, but because it references
symbols that might not exist in a syms_of_() function, we
initialize it in vars_of_(). There is also an object property
(`num_extra_memusage_stats') that is automatically initialized based
on `memusage_stats_list'; we do that in reinit_vars_of_alloc(),
which is called after all vars_of_() functions are called.
`disksaver' method was renamed `disksave' to correspond with the
name normally given to the function (e.g. disksave_lstream()).
(2) Generalize the memory-usage mechanism in `buffer-memory-usage',
`window-memory-usage', `charset-memory-usage' into an object-type-
specific mechanism called by a single function
`object-memory-usage'. (Former function `object-memory-usage'
renamed to `total-object-memory-usage'). Generalize the mechanism
of different "slices" so that we can have different "classes" of
memory described and different "slices" onto each class; `t'
separates classes, `nil' separates slices. Currently we have
three classes defined: the memory of an object itself,
non-Lisp-object memory associated with the object (e.g. arrays or
dynarrs stored as fields in the object), and Lisp-object memory
associated with the object (other internal Lisp objects stored in
the object). This isn't completely finished yet and we might need
to further separate the "other internal Lisp objects" class into
two classes.
The memory-usage mechanism uses a `struct usage_stats' (renamed
from `struct overhead_stats') to describe a malloc-view onto a set
of allocated memory (listing how much was requested and various
types of overhead) and a more general `struct generic_usage_stats'
(with a `struct usage_stats' in it) to hold all statistics about
object memory. `struct generic_usage_stats' contains an array of
32 Bytecounts, which are statistics of unspecified semantics. The
intention is that individual types declare a corresponding struct
(e.g. `struct window_stats') with the same structure but with
specific fields in place of the array, corresponding to specific
statistics. The number of such statistics is an object property
computed from the list of tags (Lisp symbols describing the
statistics) stored in `memusage_stats_list'. The idea here is to
allow particular object types to customize the number and
semantics of the statistics where completely avoiding consing.
This doesn't matter so much yet, but the intention is to have the
memory usage of all objects computed at the end of GC, at the same
time as other statistics are currently computed. The values for
all statistics for a single type would be added up to compute
aggregate values for all objects of a specific type. To make this
efficient, we can't allow any memory allocation at all.
(3) Create some additional functions for creating lists that
specify the elements directly as args rather than indirectly through
an array: listn() (number of args given), listu() (list terminated
by Qunbound).
(4) Delete a bit of remaining unused C window_config stuff, also
unused lrecord_type_popup_data.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Thu, 18 Mar 2010 10:50:06 -0500 |
| parents | 1cecc3e9f0a0 |
| children | 308d34e9f07d |
| rev | line source |
|---|---|
| 2537 | 1 \input texinfo @c -*-texinfo-*- |
| 2 | |
| 2547 | 3 @c This file is in Texinfo format. |
| 4 @c If for some reason you do not have the formatted version available, | |
| 5 @c this file is more or less readable as plain text. | |
| 6 @c Skip to the line beginning "@node Introduction". | |
| 7 | |
| 2537 | 8 @c %**start of header |
| 9 @setfilename ../info/beta.info | |
| 10 @settitle Info on beta versions of XEmacs | |
| 11 @direntry | |
| 12 * Beta: (beta). Info on beta versions of XEmacs. | |
| 13 @end direntry | |
| 14 @c footnotestyle separate | |
| 15 @c paragraphindent 2 | |
| 16 @c %**end of header | |
| 17 | |
| 18 @ifinfo | |
| 19 This file describes info relevant to beta versions of XEmacs. | |
| 20 | |
| 21 Copyright @copyright{} 2005 Ben Wing. | |
| 2547 | 22 Copyright @copyright{} 2005 Free Software Foundation, Inc. |
| 2537 | 23 |
| 24 This file is part of XEmacs. | |
| 25 | |
| 26 XEmacs is free software; you can redistribute it and/or modify it | |
| 27 under the terms of the GNU General Public License as published by the | |
| 28 Free Software Foundation; either version 2, or (at your option) any | |
| 29 later version. | |
| 30 | |
| 31 XEmacs is distributed in the hope that it will be useful, but WITHOUT | |
| 32 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| 33 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| 34 for more details. | |
| 35 | |
| 36 You should have received a copy of the GNU General Public License | |
| 37 along with XEmacs; see the file COPYING. If not, write to | |
| 38 the Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
| 39 Boston, MA 02111-1307, USA. | |
| 40 @end ifinfo | |
| 41 | |
| 42 @c Combine indices. | |
| 43 @syncodeindex fn cp | |
| 44 @syncodeindex vr cp | |
| 45 @syncodeindex ky cp | |
| 46 @syncodeindex pg cp | |
| 47 @syncodeindex tp cp | |
| 48 | |
| 49 @setchapternewpage odd | |
| 50 @finalout | |
| 51 | |
| 52 @titlepage | |
| 53 @title Info on beta versions of XEmacs | |
| 54 | |
| 55 @author XEmacs Development Team | |
| 56 @page | |
| 57 @vskip 0pt plus 1fill | |
| 58 | |
| 59 @noindent | |
| 3388 | 60 Copyright @copyright{} 2006 Free Software Foundation. @* |
| 2537 | 61 Copyright @copyright{} 2005 Ben Wing. @* |
| 62 | |
| 63 This file is part of XEmacs. | |
| 64 | |
| 65 XEmacs is free software; you can redistribute it and/or modify it | |
| 66 under the terms of the GNU General Public License as published by the | |
| 67 Free Software Foundation; either version 2, or (at your option) any | |
| 68 later version. | |
| 69 | |
| 70 XEmacs is distributed in the hope that it will be useful, but WITHOUT | |
| 71 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| 72 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| 73 for more details. | |
| 74 | |
| 75 You should have received a copy of the GNU General Public License | |
| 76 along with XEmacs; see the file COPYING. If not, write to | |
| 77 the Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
| 78 Boston, MA 02111-1307, USA. | |
| 79 @end titlepage | |
| 80 @page | |
| 81 | |
| 82 @ifinfo | |
| 83 @node Top, Introduction, (dir), (dir) | |
| 84 This Info file describes info relevant to beta versions of XEmacs. | |
| 85 @menu | |
| 86 * Introduction:: | |
| 3388 | 87 * Building Beta XEmacs:: |
| 2537 | 88 * Packages:: |
| 3388 | 89 * Reporting Problems:: |
| 2537 | 90 * Improving XEmacs:: |
| 3388 | 91 * Index:: |
| 2537 | 92 |
| 93 @detailmenu | |
| 94 --- The Detailed Node Listing --- | |
| 95 | |
| 96 Introduction | |
| 97 | |
| 98 * Mailing Lists:: | |
| 99 * Beta Release Schedule:: | |
| 100 | |
| 101 Mailing Lists | |
| 102 | |
| 103 * XEmacs Beta Mailing List:: | |
| 104 * XEmacs Patches Mailing List:: | |
| 105 * XEmacs Design Mailing List:: | |
| 106 * List Administrivia:: | |
| 107 * Managing your subscription via the Web:: | |
| 108 * Subscribing by e-mail:: | |
| 109 * Unsubscribing by e-mail:: | |
| 110 | |
| 3388 | 111 Building Beta XEmacs |
| 2537 | 112 |
| 3388 | 113 * Getting the Source:: |
| 2537 | 114 * Building an XEmacs from patches:: |
| 115 * Building XEmacs from a full distribution:: | |
| 116 | |
| 117 Packages | |
| 118 | |
| 119 * Binary package installation:: | |
| 120 * Manual procedures for package management:: | |
| 121 * Building XEmacs and XEmacs packages from scratch:: | |
| 122 | |
| 123 Improving XEmacs | |
| 124 | |
| 125 * Creating patches for submission:: | |
| 126 * Large contributions:: | |
| 127 | |
| 128 Creating patches for submission | |
| 129 | |
| 130 * Patch discussion etiquette:: | |
| 131 | |
| 132 Large contributions | |
| 133 | |
| 134 * Updates to existing packages:: | |
| 135 * New packages:: | |
| 136 * Syncing with GNU Emacs:: | |
| 137 | |
| 138 @end detailmenu | |
| 139 @end menu | |
| 140 | |
| 141 @end ifinfo | |
| 142 | |
| 3388 | 143 |
| 144 @node Introduction, Building Beta XEmacs, Top, Top | |
| 2537 | 145 @chapter Introduction |
| 146 | |
| 147 You are running a potentially unstable version of XEmacs. Please do | |
| 148 not report problems with Beta XEmacs to comp.emacs.xemacs. Report | |
| 149 them to @uref{mailto:xemacs-beta@@xemacs.org}, preferably with | |
| 150 @kbd{M-x report-xemacs-bug RET}. | |
| 151 | |
| 152 @menu | |
| 153 * Mailing Lists:: | |
| 154 * Beta Release Schedule:: | |
| 155 @end menu | |
| 156 | |
| 3388 | 157 |
| 2537 | 158 @node Mailing Lists, Beta Release Schedule, Introduction, Introduction |
| 159 @section Mailing Lists | |
| 160 | |
| 161 @menu | |
| 162 * XEmacs Beta Mailing List:: | |
| 163 * XEmacs Patches Mailing List:: | |
| 164 * XEmacs Design Mailing List:: | |
| 165 * List Administrivia:: | |
| 166 * Managing your subscription via the Web:: | |
| 167 * Subscribing by e-mail:: | |
| 168 * Unsubscribing by e-mail:: | |
| 169 @end menu | |
| 170 | |
| 3388 | 171 |
| 2537 | 172 @node XEmacs Beta Mailing List, XEmacs Patches Mailing List, Mailing Lists, Mailing Lists |
| 173 @subsection XEmacs Beta Mailing List | |
| 174 | |
| 175 If you are not subscribed to the XEmacs beta list you should be. | |
| 176 Currently all discussion of development issues, including bug reports | |
| 177 and coding discussion, takes place on the XEmacs Beta mailing list. | |
| 178 Only patches and administrative actions regarding patches are sent | |
| 179 elsewhere (to the XEmacs Patches list). | |
| 180 | |
| 3388 | 181 |
| 2537 | 182 @node XEmacs Patches Mailing List, XEmacs Design Mailing List, XEmacs Beta Mailing List, Mailing Lists |
| 183 @subsection XEmacs Patches Mailing List | |
| 184 | |
| 185 XEmacs Patches records proposed changes to XEmacs, and their | |
| 186 disposition. It is open subscription, and all patches that are | |
| 187 seriously proposed for inclusion in XEmacs should be posted here. You | |
| 188 can follow progress of your patch by subscribing to the mailing list | |
| 189 or in the archives. | |
| 190 | |
| 191 Besides patches, only actions by members of the XEmacs Review Board | |
| 192 should be posted to this list. All discussion should be redirected to | |
| 193 XEmacs Beta or XEmacs Design. | |
| 194 | |
| 3388 | 195 |
| 2537 | 196 @node XEmacs Design Mailing List, List Administrivia, XEmacs Patches Mailing List, Mailing Lists |
| 197 @subsection XEmacs Design Mailing List | |
| 198 | |
| 199 XEmacs Design is for design discussions such as adding major features | |
| 200 or whole modules, or reimplementation of existing functions, to XEmacs. | |
| 201 | |
| 202 @node List Administrivia, Managing your subscription via the Web, XEmacs Design Mailing List, Mailing Lists | |
| 203 @subsection List Administrivia | |
| 204 | |
| 205 In the descriptions below, the word LIST (all uppercase) is a | |
| 206 variable. Substitute "beta", "design", or "patches" as appropriate | |
| 207 (to get "xemacs-beta" as the mailbox for the XEmacs Beta mailing list, | |
| 208 or @uref{http://www.xemacs.org/Lists/#xemacs-beta} for its URL). | |
| 209 | |
| 210 The XEmacs mailing lists are managed by the Mailman mailing list package, | |
| 211 and the usual Mailman commands work. Do not send mailing list requests to | |
| 212 the main address (@uref{mailto:xemacs-LIST@@xemacs.org}), always send them | |
| 213 to @uref{mailto:xemacs-LIST-request@@xemacs.org}. If you have problems with | |
| 214 the list itself, they should be brought to the attention of the XEmacs | |
| 215 Mailing List manager @uref{mailto:list-manager@@xemacs.org} (the same | |
| 216 mailbox, "list-manager", for all lists). All public mailing lists have | |
| 217 searchable archives. The URL is | |
| 218 | |
| 219 @uref{http://list-archive.xemacs.org/xemacs-LIST} | |
| 220 | |
| 221 Note that the xemacs-LIST-admin address is used internally by the | |
| 222 Mailman software; it is NOT a synonym for xemacs-LIST-request. | |
| 223 | |
| 3388 | 224 |
| 2537 | 225 @node Managing your subscription via the Web, Subscribing by e-mail, List Administrivia, Mailing Lists |
| 226 @subsection Managing your subscription via the Web | |
| 227 | |
| 228 Subscription, unsubscription, and options (such as digests and | |
| 229 temporarily suspending delivery) can be accomplished via the web | |
| 230 interface at @uref{http://www.xemacs.org/Lists/#xemacs-LIST}. | |
| 231 | |
| 3388 | 232 |
| 2537 | 233 @node Subscribing by e-mail, Unsubscribing by e-mail, Managing your subscription via the Web, Mailing Lists |
| 234 @subsection Subscribing by e-mail | |
| 235 | |
| 236 Send an email message to @uref{mailto:xemacs-LIST-request@@xemacs.org} with | |
| 237 @samp{subscribe} (without the quotes) as the BODY of the message. | |
| 238 | |
| 3388 | 239 |
| 2537 | 240 @node Unsubscribing by e-mail, , Subscribing by e-mail, Mailing Lists |
| 241 @subsection Unsubscribing by e-mail | |
| 242 | |
| 243 Send an email message to @uref{mailto:xemacs-LIST-request@@xemacs.org} with | |
| 244 @samp{unsubscribe} (without the quotes) as the BODY of the message. | |
| 245 | |
| 3388 | 246 |
| 247 @node Beta Release Schedule, , Mailing Lists, Introduction | |
| 2537 | 248 @section Beta Release Schedule |
| 249 | |
| 250 We would like to achieve a weekly or fortnightly release cycle (you | |
| 251 know the Open Source model: release early, release often), and in a | |
| 252 perfect world that would indeed be the case. There are at least three | |
| 253 things that often get in the way of that goal: 1) The Release Manager | |
| 254 has a life outside of XEmacs (hard to believe, I know, but true), | |
| 255 2) we like to make releases that will build (at least on the Release | |
| 256 Manager's box), and 3) Murphy likes to throw a spanner in the works | |
| 257 right when you least expect it (Murphy's Law: Whatever can go wrong, | |
| 258 will go wrong). | |
| 259 | |
| 260 If you'd like to keep right up to date and ride the bleeding edge, use | |
| 261 CVS (see @uref{http://www.xemacs.org/Develop/cvsaccess.html}). If you | |
| 262 can't use CVS for some reason and must use FTP, please let us know. | |
| 263 it will make it more likely that we release betas more often. | |
| 264 | |
| 265 | |
| 3388 | 266 @node Building Beta XEmacs, Packages, Introduction, Top |
| 267 @chapter Building Beta XEmacs | |
| 2537 | 268 |
| 3388 | 269 @menu |
| 270 * Getting the Source:: | |
| 271 * Building an XEmacs from patches:: | |
| 272 * Building XEmacs from a full distribution:: | |
| 273 @end menu | |
| 2537 | 274 |
| 3388 | 275 |
| 276 @node Getting the Source, Building an XEmacs from patches, Building Beta XEmacs, Building Beta XEmacs | |
| 277 @section Getting the Source | |
| 2537 | 278 |
| 3388 | 279 We provide the traditional tarballs and release-to-release patchkits for |
| 280 each beta release. @xref{Beta Release Schedule}. These are available | |
| 281 at | |
| 2537 | 282 |
| 3388 | 283 @uref{ftp://ftp.xemacs.org/pub/xemacs/beta/} |
| 2537 | 284 |
| 285 In addition to the normal tar distribution, XEmacs source is now | |
| 286 available via CVS. Please see | |
| 287 | |
| 288 @uref{http://www.xemacs.org/Develop/cvsaccess.html} | |
| 289 | |
| 3388 | 290 You can also browse the repository via ViewCVS |
| 2537 | 291 |
| 3388 | 292 @uref{http://cvs.xemacs.org/} |
| 2537 | 293 |
| 3388 | 294 |
| 295 @node Building an XEmacs from patches, Building XEmacs from a full distribution, Getting the Source, Building Beta XEmacs | |
| 2537 | 296 @section Building an XEmacs from patches |
| 297 | |
| 3388 | 298 All beta releases of XEmacs provide patches from the previous version as |
| 299 an alternative to keep bandwidth requirements down. These patches are | |
| 300 actually scripts generated by the @file{makepatch} program, and can be | |
| 301 run if you have the @file{applypatch} program. Patches may also be | |
| 302 applied with the GNU patch program in something like the following. | |
| 303 Let's say you're upgrading XEmacs 21.5-beta9 to XEmacs 21.5-beta10 and | |
| 304 you have a full unmodified XEmacs 21.5-beta9 source tree to work with. | |
| 305 Change to the top level directory and issue the shell command: | |
| 2537 | 306 |
| 307 @example | |
| 308 $ gunzip -c /tmp/xemacs-21.5.9-21.5.10.patch.gz | patch -p1 | |
| 309 @end example | |
| 310 | |
| 311 After patching, check to see that no patches were missed by doing | |
| 312 | |
| 313 @example | |
| 314 $ find . -name \*.rej -print | |
| 315 @end example | |
| 316 | |
| 317 Any rejections should be treated as serious problems to be resolved | |
| 318 before building XEmacs. | |
| 319 | |
| 320 After seeing that there were no rejections, issue the commands | |
| 321 | |
| 322 @example | |
| 323 $ ./config.status --recheck | |
| 324 $ make beta > ./beta.err 2>&1 | |
| 325 $ make check > ./xemacs-make-check.err 2>&1 | |
| 326 @end example | |
| 327 | |
| 328 Redirect the output from make to those files because you'll use them | |
| 329 later when you send off a build report with @kbd{M-x build-report RET} | |
| 330 | |
| 3388 | 331 |
| 332 @node Building XEmacs from a full distribution, , Building an XEmacs from patches, Building Beta XEmacs | |
| 2537 | 333 @section Building XEmacs from a full distribution |
| 334 | |
| 335 @enumerate | |
| 336 @item | |
| 3388 | 337 Locate a convenient place where you have at least 200MB of free space |
| 338 (approximately 100MB for sources and compiled Lisp, and 100MB for | |
| 339 objects and other generated files) and issue the command | |
| 2537 | 340 |
| 341 @example | |
| 342 $ gunzip -c /tmp/xemacs-21.5.10.tar.gz | tar xvf - | |
| 343 @end example | |
| 344 | |
| 345 (or simply @code{tar zxvf /tmp/xemacs-21.5.10.tar.gz} if you use GNU tar). | |
| 346 | |
| 347 @item | |
| 348 cd to the top level directory and issue an appropriate configure | |
| 349 command. | |
| 350 | |
| 351 @item | |
| 352 Run @code{configure}. If you are new, just consider running it with no | |
| 4312 | 353 options, to see if you can get a successful build. When you are more |
| 2537 | 354 experienced, you should put various flags in. Here is what we suggest: |
| 355 | |
| 356 @enumerate | |
| 357 @item | |
| 358 It's a good idea to use | |
| 359 | |
| 360 @example | |
| 2647 | 361 --enable-debug |
| 362 --enable-memory-usage-stats | |
| 363 --enable-error-checking=all | |
| 2537 | 364 @end example |
| 365 | |
| 366 These turn on extra debugging info and checks. The last one in particular | |
| 367 will add a great deal of extra error-checking -- which will slow your XEmacs | |
| 368 down somewhat but is likely to catch bugs much sooner and make your bug | |
| 369 reports much more useful. | |
| 370 | |
| 371 @item | |
| 372 You should also strongly consider | |
| 373 | |
| 374 @example | |
| 2647 | 375 --enable-mule |
| 376 --enable-kkcc | |
| 377 --enable-pdump | |
| 378 --enable-clash-detection | |
| 2537 | 379 --with-wmcommand |
| 380 --with-xfs | |
| 381 @end example | |
| 382 | |
| 383 These turn on optional features, which can always use testing. | |
| 384 | |
| 385 @item | |
| 386 If you have gcc, consider using | |
| 387 | |
| 388 @example | |
| 2647 | 389 --with-compiler=gcc |
| 390 --with-xemacs-compiler=g++ | |
| 2537 | 391 @end example |
| 392 | |
| 3388 | 393 This will compile XEmacs using g++, which is generally much stricter |
| 394 about type-checking than C compilers like gcc. | |
| 2537 | 395 |
| 396 @item | |
| 397 If your packages are not installed under /usr/local, you should add a | |
| 398 line like | |
| 399 | |
| 400 @example | |
| 2647 | 401 --with-package-path=~/.xemacs::/xemacs/site-packages:/xemacs/xemacs-packages:/xemacs/mule-packages |
| 2537 | 402 @end example |
| 403 | |
| 404 @item | |
| 405 If you want to build multiple configurations from the same source | |
| 406 tree, make separate build directories for each configuration, run | |
| 407 @code{configure} from the top level of these (currently empty) | |
| 408 directories and use an option like | |
| 409 | |
| 410 @example | |
| 411 --srcdir=/xemacs/source-tree | |
| 412 @end example | |
| 413 | |
| 414 (or wherever your source tree is). This will magically create symlinks and | |
| 415 populate your build directory. | |
| 416 | |
| 417 @item | |
| 2647 | 418 Use --with-site-prefixes (or --with-site-includes and |
| 419 ---with-site-libraries) if you have some packages that XEmacs can | |
| 420 compile with that are located in an unusual place. For example: | |
| 2537 | 421 |
| 422 @example | |
| 2647 | 423 --with-site-prefixes=/usr/local/pgsql:/usr/local/BerkeleyDB.4.1 |
| 2537 | 424 @end example |
| 425 | |
| 426 @item | |
| 4312 | 427 Depending on your build environment, consider setting or not setting |
| 2537 | 428 options for menubars, scrollbars, window systems, native sound, etc. If |
| 429 you're not sure, leave them out and let configure do the auto-detection. | |
| 430 (If you get bugs compiling GTK, use @code{--with-gtk=no --with-gnome=no}.) | |
| 431 | |
| 432 Part of the configure output is a summary that looks something | |
| 433 like the following. (this summary is also available as the file | |
| 434 'Installation' in the top directory of your build tree, and via | |
| 435 the command @kbd{M-x describe-installation RET}). | |
| 436 | |
| 437 @example | |
| 2647 | 438 uname -a: Darwin laptop.local 7.7.0 Darwin Kernel Version 7.7.0: Sun Nov 7 16:06:51 PST 2004; root:xnu/xnu-517.9.5.obj~1/RELEASE_PPC Power Macintosh powerpc |
| 2537 | 439 |
| 2647 | 440 ./configure '--with-site-prefixes=/sw' '--without-ldap' '--with-dynamic=yes' '--with-gtk=no' '--with-gnome=no' '--enable-toolbars' '--with-wmcommand' '--with-athena=3d' '--enable-menubars=lucid' '--enable-scrollbars=athena' '--enable-dialogs=athena' '--enable-widgets=athena' '--with-gif' '--enable-sound=native,noesd' '--with-site-lisp=no' '--with-site-modules' '--enable-pdump' '--enable-mule' '--with-xfs' '--enable-debug' '--enable-error-checking=all' '--enable-memory-usage-stats' '--enable-kkcc' '--enable-clash-detection' |
| 2537 | 441 |
| 442 | |
| 2647 | 443 XEmacs 21.5-b19 "chives" (+CVS-20050226) configured for `powerpc-apple-darwin7.7.0'. |
| 444 | |
| 445 WARNING: -------------------------------------------------------------- | |
| 446 WARNING: This was produced from a new autoconf-2.5 based configuration. | |
| 447 WARNING: If this configuration seems buggy then copy etc/configure-2.13 | |
| 448 WARNING: to configure and try again. Also please report the bug. | |
| 449 WARNING: -------------------------------------------------------------- | |
| 450 | |
| 451 Compilation Environment and Installation Defaults: | |
| 2537 | 452 Source code location: /usr/local/src/xemacs |
| 453 Installation prefix: /usr/local | |
| 2647 | 454 Additional prefixes: /sw |
| 455 Operating system description file: `s/darwin.h' | |
| 456 Machine description file: `m/powerpc.h' | |
| 457 Compiler version: gcc (GCC) 3.3 20030304 (Apple Computer, Inc. build 1671) | |
| 458 - GCC specs file: /usr/libexec/gcc/darwin/ppc/3.3/specs | |
| 459 - Compiler command: gcc -Wall -Wno-switch -Wundef -Wsign-compare -Wno-char-subscripts -Wpacked -Wpointer-arith -Wunused-parameter -g | |
| 460 libc version: | |
| 2537 | 461 Relocating allocator for buffers: no |
| 2647 | 462 GNU version of malloc: no |
| 463 - The GNU allocators don't work with this system configuration. | |
| 2537 | 464 |
| 465 Window System: | |
| 466 Compiling in support for the X window system: | |
| 2647 | 467 - X Windows headers location: /usr/X11R6/include |
| 468 - X Windows libraries location: /usr/X11R6/lib | |
| 2537 | 469 - Handling WM_COMMAND properly. |
| 470 Compiling in support for the Athena widget set: | |
| 2647 | 471 - Athena headers location: X11/Xaw3d |
| 472 - Athena library to link: Xaw3d | |
| 2537 | 473 Using Lucid menubars. |
| 474 Using Athena scrollbars. | |
| 475 Using Athena dialog boxes. | |
| 476 Using Athena native widgets. | |
| 477 | |
| 478 TTY: | |
| 479 Compiling in support for ncurses. | |
| 480 | |
| 481 Images: | |
|
4708
1cecc3e9f0a0
Use giflib or libungif to provide GIF support, instead of using internal
Jerry James <james@xemacs.org>
parents:
4312
diff
changeset
|
482 Compiling in support for GIF images. |
| 2537 | 483 Compiling in support for XPM images. |
| 484 Compiling in support for PNG images. | |
| 485 Compiling in support for JPEG images. | |
| 486 Compiling in support for TIFF images. | |
| 487 Compiling in support for X-Face message headers. | |
| 488 | |
| 489 Sound: | |
| 490 | |
| 491 Databases: | |
| 492 Compiling in support for Berkeley database. | |
| 2647 | 493 Compiling in support for GNU DBM. |
| 2537 | 494 Compiling in support for PostgreSQL. |
| 2647 | 495 - Using PostgreSQL header file: postgresql/libpq-fe.h |
| 2537 | 496 - Using PostgreSQL V7 bindings. |
| 497 | |
| 498 Internationalization: | |
| 499 Compiling in support for Mule (multi-lingual Emacs). | |
| 500 Compiling in support for XIM (X11R5+ I18N input method). | |
| 501 - Using raw Xlib to provide XIM support. | |
| 502 - Using XFontSet to provide bilingual menubar. | |
| 503 | |
| 504 Mail: | |
| 2647 | 505 Compiling in support for "file" mail spool file locking method. |
| 2537 | 506 |
| 507 Other Features: | |
| 508 Inhibiting IPv6 canonicalization at startup. | |
| 509 Compiling in support for dynamic shared object modules. | |
| 510 Using the new GC algorithms. | |
| 511 Using the new portable dumper. | |
| 512 Compiling in support for extra debugging code. | |
| 2647 | 513 Compiling in support for runtime error checking. |
| 514 WARNING: --------------------------------------------------------- | |
| 2537 | 515 WARNING: XEmacs will run noticeably more slowly as a result. |
| 516 WARNING: Error checking is on by default for XEmacs beta releases. | |
| 2647 | 517 WARNING: --------------------------------------------------------- |
| 2537 | 518 @end example |
| 519 @end enumerate | |
| 520 | |
| 521 | |
| 522 @item | |
| 523 Then... | |
| 524 | |
| 525 @example | |
| 526 $ make > ./beta.err 2>&1 | |
| 527 $ make check > ./xemacs-make-check.err 2>&1 | |
| 528 @end example | |
| 529 | |
| 530 ...and you should have a working XEmacs. | |
| 531 | |
| 532 @item | |
| 533 After you have verified that you have a functional editor, fire up | |
| 534 your favorite mail program and send a build report to | |
| 535 @uref{mailto:xemacs-buildreports@@xemacs.org}. | |
| 536 | |
| 537 Preferably this is best done from XEmacs, following these simple steps: | |
| 538 | |
| 539 @enumerate | |
| 540 @kbd{M-x customize-group RET build-report RET} | |
| 541 @kbd{M-x build-report RET} | |
| 542 @end enumerate | |
| 543 | |
| 544 See also | |
| 545 @uref{http://www.xemacs.org/Releases/Public-21.2/tester.html#reporting} | |
| 546 | |
| 547 If you create the report manually by other means, here is what the | |
| 548 build report should include: | |
| 549 | |
| 550 @enumerate | |
| 551 @item | |
| 552 Your hardware configuration (OS version, etc.) | |
| 553 | |
| 554 @item | |
| 555 Version numbers of software in use (X11 version, system library | |
| 556 versions if appropriate, graphics library versions if appropriate). | |
| 557 If you're on a system like Linux, include all the version numbers | |
| 558 you can because chances are it makes a difference. | |
| 559 | |
| 560 @item | |
| 561 The options given to configure | |
| 562 | |
| 563 @item | |
| 564 The configuration report illustrated above | |
| 565 | |
| 566 For convenience all of the above items are placed in a file called | |
| 567 `Installation' in the top level build directory. They are also | |
| 568 available by performing @kbd{M-x describe-installation} inside XEmacs. | |
| 569 | |
| 570 @item | |
| 571 Any other unusual items you feel should be brought to the attention | |
| 572 of the developers. | |
| 573 @end enumerate | |
| 574 @end enumerate | |
| 575 | |
| 3388 | 576 |
| 577 @node Packages, Reporting Problems, Building Beta XEmacs, Top | |
| 2537 | 578 @chapter Packages |
| 579 | |
| 580 [Note: these instructions have been partly updated, but not carefully | |
| 581 reviewed in some time. Caveat tester.] | |
| 582 | |
| 583 Starting with XEmacs 21.1, much of the functionality of XEmacs has | |
| 584 been unbundled into "the packages." For more information about the | |
| 585 package system, see the Info nodes on Packages (in the XEmacs User | |
| 586 Manual) and on Packaging (in the Lisp Reference). | |
| 587 | |
| 588 When bootstrapping XEmacs, you may need to manually install some | |
| 589 packages (at least xemacs-base and efs). These packages are available | |
| 590 by FTP at @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/}. | |
| 591 | |
| 592 @menu | |
| 593 * Binary package installation:: | |
| 594 * Manual procedures for package management:: | |
| 595 * Building XEmacs and XEmacs packages from scratch:: | |
| 596 @end menu | |
| 597 | |
| 3388 | 598 |
| 2537 | 599 @node Binary package installation, Manual procedures for package management, Packages, Packages |
| 600 @section Binary package installation | |
| 601 | |
| 602 Prerequisite: XEmacs 21.0-b1. | |
| 603 | |
| 604 Binary packages are complete entities that can be untarred at the top | |
| 605 level of an XEmacs package hierarchy and work at runtime. To install files | |
| 606 in this directory, run the command @kbd{M-x package-admin-add-binary-package} | |
| 607 and fill in appropriate values to the prompts. | |
| 608 | |
| 3388 | 609 |
| 2537 | 610 @node Manual procedures for package management, Building XEmacs and XEmacs packages from scratch, Binary package installation, Packages |
| 611 @section Manual procedures for package management | |
| 612 | |
| 613 Prerequisite: XEmacs 21.0 | |
| 614 | |
| 615 When adding and deleting files from a lisp directory the | |
| 616 auto-autoloads.el (global symbols) and custom-load.el (Customization | |
| 617 groups) must be kept in synch. Assuming one is manipulating a | |
| 618 directory called `lisp-utils', the command to rebuild the | |
| 619 auto-autoloads.el file is: | |
| 620 | |
| 621 @example | |
| 622 xemacs -vanilla -batch \ | |
| 623 -eval \("setq autoload-package-name \"lisp-utils\""\) \ | |
| 624 -f batch-update-directory lisp-utils | |
| 625 @end example | |
| 626 | |
| 627 The command to rebuild the custom-load.el file is: | |
| 628 | |
| 629 @example | |
| 630 xemacs -vanilla -batch -f Custom-make-dependencies lisp-utils | |
| 631 @end example | |
| 632 | |
| 633 To byte-compile both of these files the command is: | |
| 634 | |
| 635 @example | |
| 636 xemacs -vanilla -batch -f batch-byte-compile \ | |
| 637 lisp-utils/auto-autoloads.el lisp-utils/custom-load.el | |
| 638 @end example | |
| 639 | |
| 640 Of course, being a beta tester, you'd be aware that it is much easier | |
| 641 to manage your XEmacs packages with PUI. | |
| 642 | |
| 3388 | 643 |
| 644 @node Building XEmacs and XEmacs packages from scratch, , Manual procedures for package management, Packages | |
| 2537 | 645 @section Building XEmacs and XEmacs packages from scratch |
| 646 | |
| 647 To build everything completely from scratch isn't hard, just time | |
| 648 consuming. | |
| 649 | |
| 650 @subheading Step 1 - grab the sources (core and packages) | |
| 651 | |
| 652 @example | |
| 653 $ cvs -d :pserver:cvs@@cvs.xemacs.org:/pack/xemacscvs login | |
| 654 [password: "cvs" (sans quotes)] | |
| 655 | |
| 656 $ cvs -d :pserver:cvs@@cvs.xemacs.org:/pack/xemacscvs co -d xemacs-21.5 xemacs | |
| 657 | |
| 658 $ cvs -d :pserver:cvs@@cvs.xemacs.org:/pack/xemacscvs co packages | |
| 659 @end example | |
| 660 | |
| 661 @subheading Step 2 - build XEmacs | |
| 662 | |
| 663 @example | |
| 664 $ cd xemacs-21.5 | |
| 665 $ ./configure [options...] | |
| 666 $ make > ./beta.err 2>&1 | |
| 667 $ make check > ./xemacs-make-check.err 2>&1 | |
| 668 @end example | |
| 669 | |
| 670 And optionally: | |
| 671 | |
| 672 @example | |
| 673 $ make install > ./xemacs-make-install.err 2>&1 | |
| 674 @end example | |
| 675 | |
| 676 @subheading Step 3 - build and install the packages | |
| 677 | |
| 678 @example | |
| 679 $ cd packages | |
| 680 $ cp Local.rules.template Local.rules | |
| 681 @end example | |
| 682 | |
| 683 Then edit Local.rules to suit your needs/environment | |
| 684 (@pxref{Local.rules file,,, xemacs, XEmacs User's Manual}) for details | |
| 685 about this file. | |
| 686 | |
| 687 And then: | |
| 688 | |
| 689 @example | |
| 690 $ make install | |
| 691 @end example | |
| 692 | |
| 3388 | 693 |
| 694 @node Reporting Problems, Improving XEmacs, Packages, Top | |
| 695 @section Reporting Problems | |
| 696 | |
| 697 The best way to get problems fixed in XEmacs is to submit good problem | |
| 698 reports, @kbd{M-x report-xemacs-bug RET} will help you do this (assuming | |
| 699 you have a usable XEmacs). Since this is beta software, problems are | |
| 700 certain to exist. Please read through all of part II of the XEmacs | |
| 701 FAQ for an overview of problem reporting. | |
| 702 @xref{Installation, Installation and Troubleshooting, , xemacs-faq}. | |
| 703 The most relevant parts are in section 2.4, General Troubleshooting. | |
| 704 @c #### Why doesn't this link work? | |
| 705 @c @ref{Q2.4.1, General Troubleshooting, , xemacs-faq}. | |
| 706 Other items which are most important are: | |
| 707 | |
| 708 @enumerate | |
| 709 @item | |
| 710 Do not submit C stack backtraces without line numbers. Since it | |
| 711 is possible to compile optimized with debug information with GCC | |
| 712 it is never a good idea to compile XEmacs without the -g flag. | |
| 713 XEmacs runs on a variety of platforms, and often it is not | |
| 714 possible to recreate problems which afflict a specific platform. | |
| 715 The line numbers in the C stack backtrace help isolate where the | |
| 716 problem is actually occurring. | |
| 717 | |
| 718 @item | |
| 719 Attempt to recreate the problem starting with an invocation of | |
| 720 XEmacs with @code{xemacs -no-autoloads}. Quite often, problems are | |
| 721 due to package interdependencies, and the like. An actual bug | |
| 722 in XEmacs should be reproducible in a default configuration | |
| 723 without loading any special packages (or the one or two specific | |
| 724 packages that cause the bug to appear). If you have trouble | |
| 725 getting anything to work at all with the above invocation, use | |
| 726 @code{xemacs -vanilla} instead. If you need to load your user init | |
| 727 file or the site file to get the problem to occur, then it has | |
| 728 something to do with them, and you should try to isolate the | |
| 729 issue in those files. | |
| 730 | |
| 731 @item | |
| 732 A picture can be worth a thousand words. When reporting an | |
| 733 unusual display, it is generally best to capture the problem in a | |
| 734 screen dump and include that with the problem report. The easiest | |
| 735 way to get a screen dump is to use the xv program and its grab | |
|
4708
1cecc3e9f0a0
Use giflib or libungif to provide GIF support, instead of using internal
Jerry James <james@xemacs.org>
parents:
4312
diff
changeset
|
736 function. Save the image as a PNG to keep bandwidth requirements |
| 3388 | 737 down without loss of information. MIME is the preferred method |
| 738 for making the image attachments. | |
| 739 @end enumerate | |
| 740 | |
| 741 | |
| 742 @node Improving XEmacs, Index, Reporting Problems, Top | |
| 2537 | 743 @chapter Improving XEmacs |
| 744 | |
| 745 @menu | |
| 746 * Creating patches for submission:: | |
| 747 * Large contributions:: | |
| 748 @end menu | |
| 749 | |
| 750 @node Creating patches for submission, Large contributions, Improving XEmacs, Improving XEmacs | |
| 751 @section Creating patches for submission | |
| 752 | |
| 753 All patches to XEmacs that are seriously proposed for inclusion (eg, | |
| 754 bug fixes) should be mailed to @uref{mailto:xemacs-patches@@xemacs.org}. Each | |
| 755 patch will be reviewed by the patches review board, and will be | |
| 756 acknowledged and added to the distribution, or rejected with an | |
| 757 explanation. Progress of the patch is tracked on the XEmacs Patches | |
| 758 mailing list, which is open subscription. (If a patch is simply | |
| 759 intended to facilitate discussion, "I mean something that works like | |
| 760 this but this is really rough", a Cc to XEmacs Patches is optional, | |
| 761 but doesn't hurt.) | |
| 762 | |
| 763 Patches to XEmacs Lisp packages should be sent to the maintainer of | |
| 764 the package. If the maintainer is listed as `XEmacs Development Team' | |
| 765 patches should be sent to @uref{mailto:xemacs-patches@@xemacs.org}. | |
| 766 | |
| 767 Emailed patches should preferably be sent in MIME format and quoted | |
| 768 printable encoding (if necessary). | |
| 769 | |
| 770 The simplest way to create well-formed patches is to use CVS and | |
| 771 Didier Verna's Patcher library (available as patcher.el in the | |
| 772 xemacs-devel package). Patcher is new and requires some setup, but | |
| 773 most of the core developers are now using it for their own patches. | |
| 774 Patcher also can be configured to create patches for several projects, | |
| 775 and recognize the project from the directory it is invoked in. This | |
| 776 makes it a useful general tool (as long as XEmacs-style patches are | |
| 777 accepted at your other projects, which is likely since they conform to | |
| 778 the GNU standards). | |
| 779 | |
| 780 When making patches by hand, please use the `-u' option, or if your | |
| 781 diff doesn't support it, `-c'. Using ordinary (context-free) diffs | |
| 782 are notoriously prone to error, since line numbers tend to change when | |
| 783 others make changes to the same source file. | |
| 784 | |
| 785 An example of the `diff' usage: | |
| 786 | |
| 787 @example | |
| 788 $ diff -u OLDFILE NEWFILE | |
| 789 @end example | |
| 790 | |
| 791 -or- | |
| 792 | |
| 793 @example | |
| 794 $ diff -c OLDFILE NEWFILE | |
| 795 @end example | |
| 796 | |
| 797 Also, it is helpful if you create the patch in the top level of the | |
| 798 XEmacs source directory: | |
| 799 | |
| 800 @example | |
| 801 $ cp -p lwlib/xlwmenu.c lwlib/xlwmenu.c.orig | |
| 802 hack, hack, hack.... | |
| 803 $ diff -u lwlib/xlwmenu.c.orig lwlib/xlwmenu.c | |
| 804 @end example | |
| 805 | |
| 806 Also note that if you cut & paste from an xterm to an XEmacs mail | |
| 807 buffer you will probably lose due to tab expansion. The best thing to | |
| 808 do is to use an XEmacs shell buffer to run the diff commands, or ... | |
| 809 @kbd{M-x cd} to the appropriate directory, and issue the command | |
| 810 @kbd{C-u M-!} from within XEmacs. | |
| 811 | |
| 812 Patches should be as single-minded as possible. Mammoth patches can | |
| 813 be very difficult to place into the right slot. They are much easier | |
| 814 to deal with when broken down into functional or conceptual chunks. | |
| 815 The patches submitted by Kyle Jones and Hrvoje Niksic are stellar | |
| 816 examples of how to "Do The Right Thing". | |
| 817 | |
| 818 Each patch should be accompanied by an update to the appropriate | |
| 819 ChangeLog file. Guidelines for writing ChangeLog entries is governed | |
| 820 by the GNU coding standards. Please see | |
| 821 @uref{http://www.gnu.org/prep/standards_toc.html} [Change Logs section] | |
| 822 for details. | |
| 823 | |
| 824 Do not submit context diffs (either -c or -u) of ChangeLogs. Because | |
| 825 of the "stack" nature of ChangeLogs (new entries are always pushed on | |
| 826 the top), context diffs will fail to apply more often than they | |
| 827 succeed. Simply cutting and pasting the entry from an Emacs buffer to | |
| 828 the mail buffer (beware of tab expansion!) is probably easiest. The | |
| 829 Patcher library also will set up your ChangeLogs for you, and copy | |
| 830 them to the mail. Context-less unified diffs (-U 0) are also | |
| 831 acceptable. | |
| 832 | |
| 833 @menu | |
| 834 * Patch discussion etiquette:: | |
| 835 @end menu | |
| 836 | |
| 837 @node Patch discussion etiquette, , Creating patches for submission, Creating patches for submission | |
| 838 @subsection Patch discussion etiquette | |
| 839 | |
| 840 If you intend a patch for _application_ to the sources as is, _always_ | |
| 841 post it to xemacs-patches, even if there are minor points you would | |
| 842 like to have discussed by others. Not doing so will resulting in | |
| 843 patches getting "lost". If you expect that the patch will not be | |
| 844 acceptable, but are using it to stimulate discussion, then don't post | |
| 845 to xemacs-patches. Intermediate cases are up to your judgment; | |
| 846 unless you're sure you'll follow up with a "real" patch, better to err | |
| 847 on the side of posting to xemacs-patches. | |
| 848 | |
| 849 Discussion of the _content_ of the patch (ie responses to reviewer | |
| 850 comments beyond "that's right, ok, I'll do it your way") should _always_ | |
| 851 be posted to xemacs-beta or to xemacs-design. If you're not sure | |
| 852 which is more appropriate, send it to xemacs-beta. That is the most | |
| 853 widely read channel. | |
| 854 | |
| 855 If discussion results in a bright idea and you come up with a new | |
| 856 patch, normally you should post it to both mailing lists. The people | |
| 857 discussing on XEmacs Beta will want to know the outcome of the thread, | |
| 858 and you need to submit to XEmacs Patches as the "list of record." | |
| 859 | |
| 860 If the old patch has been applied to CVS, then just submit the new one | |
| 861 as usual. If it has not been applied, then it is best to submit a new | |
| 862 patch against CVS. If possible do this as a reply to the original | |
| 863 patch post, or something following it in the thread. (The point is to | |
| 864 get the original patch post's Message-ID in your References header.) | |
| 865 In this case, also use the keyword SUPERSEDES in the Subject header to | |
| 866 indicate that the old patch is no longer valid, and that this one | |
| 867 replaces it. | |
| 868 | |
| 869 These rules will result in a fair number of cross posts, but we don't | |
| 870 yet have a better way to handle that. | |
| 871 | |
| 872 Note: Developers should never post to xemacs-patches unless there is a | |
| 873 patch in the post. We plan to enforce this with an automatic filter. | |
| 874 | |
| 875 The exceptions are administrative. If you have commit authorization, | |
| 876 then post a short COMMIT notice to xemacs-patches when you commit to | |
| 877 CVS. Members of the Review Board will also post short notices of | |
| 878 administrative action (APPROVE, VETO, QUERY, etc) to xemacs-patches. | |
| 879 | |
| 880 @node Large contributions, , Creating patches for submission, Improving XEmacs | |
| 881 @section Large contributions | |
| 882 | |
| 883 Perhaps you have a whole new mode, or a major synchronization with | |
| 884 upstream for a neglected package, or a synchronization with GNU Emacs | |
| 885 you would like to contribute. We welcome such contributions, but they | |
| 886 are likely to be relatively controversial, generate more comments and | |
| 887 requests for revision, and take longer to integrate. Please be | |
| 888 patient with the process. | |
| 889 | |
| 890 @menu | |
| 891 * Updates to existing packages:: | |
| 892 * New packages:: | |
| 893 * Syncing with GNU Emacs:: | |
| 894 @end menu | |
| 895 | |
| 896 @node Updates to existing packages, New packages, Large contributions, Large contributions | |
| 897 @subsection Updates to existing packages | |
| 898 | |
| 899 If a package has gotten a bit out of date, or even started to bitrot, | |
| 900 we welcome patches to synchronize it with upstream/GNU Emacs versions. | |
| 901 Most packages end up varying somewhat from their GNU origins. See | |
| 902 "Syncing with GNU Emacs" for hints. Note that if you do a reasonably | |
| 903 large amount of syncing with GNU Emacs, you should log this in the | |
| 904 file itself as well as in the ChangeLog. | |
| 905 | |
| 906 If the package is important to you, please consider becoming the | |
| 907 maintainer. (See "New packages", below.) | |
| 908 | |
| 909 @node New packages, Syncing with GNU Emacs, Updates to existing packages, Large contributions | |
| 910 @subsection New packages | |
| 911 | |
| 912 If you have a new mode or other large addition that does not require | |
| 913 changes to the core, please consider submitting it as a package, and | |
| 914 becoming the maintainer. You get direct commit privileges to the | |
| 915 repository for your package, "approval" privileges for your own | |
| 916 patches as well as third party patches to your package, and some | |
| 917 degree of veto power over patches you don't like. In return, you are | |
| 918 expected to maintain friendly liaison with the upstream developer (if | |
| 919 you aren't the upstream developer), keep watch on the XEmacs Patches | |
| 920 list for relevant patches, and be available by email to other | |
| 921 developers for discussion of changes that impact your package. It's | |
| 922 also a pretty standard route to the "core" development group, where we | |
| 923 have plenty of extra work waiting for volunteers. | |
| 924 | |
| 925 You don't have to become the maintainer, but it virtually ensures | |
| 926 rapid acceptance of the package. | |
| 927 | |
| 928 For help in creating new packages, see the (rather sparse) discussions | |
| 2547 | 929 in the XEmacs User's Guide and the Lisp Reference Manual. The |
| 930 participants in the XEmacs Beta mailing list | |
| 931 @uref{mailto:xemacs-beta@@xemacs.org} and the XEmacs Package Release | |
| 932 Engineer are the most likely sources of advice. See | |
| 933 @uref{http://www.xemacs.org/Develop/jobs.html#package,jobs.html} for | |
| 934 current information about package release engineers. | |
| 2537 | 935 |
| 3388 | 936 |
| 2537 | 937 @node Syncing with GNU Emacs, , New packages, Large contributions |
| 938 @subsection Syncing with GNU Emacs | |
| 939 | |
| 940 Syncing with GNU Emacs is an important activity. Although each | |
| 941 version has its advantages and areas of concentration, it is very | |
| 942 desirable that common functionality share specifications and APIs. | |
| 943 When porting GNU code to XEmacs, the following points should be given | |
| 944 special attention: | |
| 945 | |
| 946 @itemize @bullet | |
| 947 @item | |
| 948 Recent GNU Emacsen cannot be built without Mule, but XEmacs can. | |
| 2547 | 949 Make sure that changes that depend on the presence of Mule are |
| 950 appropriately conditionalized, with @samp{#ifdef MULE} in C code and | |
| 951 with @samp{(featurep 'mule)} in Lisp. | |
| 2537 | 952 |
| 953 @item | |
| 954 GNU Emacs nomenclature often differs from that of XEmacs. | |
| 955 Sometimes syncing the names is desirable, other times not. | |
| 956 | |
| 957 @item | |
| 958 GNU Emacs functionality often differs from that of XEmacs. | |
| 959 Syncing functionality is often controversial. | |
| 960 @end itemize | |
| 961 | |
| 962 It is important that you let other developers know that | |
| 963 synchronization has taken place, to what degree, and when. For this | |
| 964 purpose, we use comments of the form | |
| 965 | |
| 966 @example | |
| 2547 | 967 /* Synched up with: GNU 21.3 by Stephen Turnbull */ |
| 2537 | 968 @end example |
| 969 | |
| 970 in the source file itself, as the last element of the prefatory | |
| 971 material (copyright notice and commentary). Obviously the comment | |
| 972 marker needs to be changed to leading semicolons for Lisp, but | |
| 2547 | 973 otherwise the format is the same. (Older sync comments may have ``FSF'' |
| 974 in place of ``GNU''. They're equally accurate in our opinion, but | |
| 975 Richard Stallman and other GNU developers consider the term ``FSF | |
| 976 Emacs'' ``insulting''. Please use ``GNU'' in new sync comments.) | |
| 2537 | 977 |
| 978 Of course you should note syncing as the purpose in the ChangeLog, | |
| 979 too. But entries get buried deep in the ChangeLog file, and may even | |
| 980 get moved to a separate ChangeLog.OLD file for rarely synched files. | |
| 981 | |
| 982 Rather than dates we use the version of GNU Emacs to sync to. If the | |
| 983 synchronization is partial, add a new comment describing what has | |
| 984 actually been synched, leaving the description of the last full sync | |
| 985 in place. At each full sync, remove all previous synchronization | |
| 986 comments. | |
| 987 | |
| 988 This applies to Lisp that we have broken out into packages, but | |
| 989 remains in the GNU Emacs core, as well to core Lisp in XEmacs. | |
| 990 | |
| 991 @c Print the tables of contents | |
| 992 @contents | |
| 993 @c That's all | |
| 994 | |
| 3388 | 995 |
| 2547 | 996 @node Index, , Improving XEmacs, Top |
| 2537 | 997 @unnumbered Index |
| 998 | |
| 999 @printindex cp | |
| 1000 | |
| 1001 @bye |