6 You are running a potentially unstable version of XEmacs. Please do
7 not report problems with Beta XEmacs to comp.emacs.xemacs. Report
8 them to xemacs-beta@xemacs.org.
13 *** XEmacs Beta Mailing List
14 ----------------------------
16 If you are not subscribed to the XEmacs beta list you should be.
17 Currently all discussion of development issues, including bug reports
18 and coding discussion, takes place on the XEmacs Beta mailing list.
19 Only patches and administrative actions regarding patches are sent
20 elsewhere (to the XEmacs Patches list).
22 ** XEmacs Patches Mailing List
23 ==============================
25 XEmacs Patches records proposed changes to XEmacs, and their
26 disposition. It is open subscription, but only patches and actions by
27 members of the XEmacs Review Board should be posted to this list. You
28 can follow progress of your patch by subscribing to the mailing list
34 In the descriptions below, the word LIST (all uppercase) is a
35 variable. Substitute "beta" or "patches" as appropriate (to get
36 "xemacs-beta" as the mailbox for the XEmacs Beta mailing list, or
37 http://www.xemacs.org/Lists/#xemacs-beta for its URL).
39 The XEmacs mailing lists are managed by the Mailman mailing list
40 package, and the usual Mailman commands work. Do not send mailing
41 list requests to the main address (xemacs-LIST@xemacs.org), always
42 send them to xemacs-LIST-request@xemacs.org. If you have problems
43 with the list itself, they should be brought to the attention of the
44 XEmacs Mailing List manager <list-manager@xemacs.org> (the same
45 mailbox, "list-manager", for all lists). All public mailing lists
46 have searchable archives. The URL is
48 http://list-archive.xemacs.org/xemacs-LIST
50 *** Managing your subscription via the Web
51 ------------------------------------------
53 Subscription, unsubscription, and options (such as digests and
54 temporarily suspending delivery) can be accomplished via the web
55 interface at http://www.xemacs.org/Lists/#xemacs-LIST.
57 *** Subscribing by e-mail
58 -------------------------
60 Send an email message to xemacs-LIST-request@xemacs.org with
61 `subscribe' (without the quotes) as the BODY of the message.
63 *** Unsubscribing by e-mail
64 ---------------------------
66 Send an email message to xemacs-LIST-request@xemacs.org with
67 `unsubscribe' (without the quotes) as the BODY of the message.
69 ** Beta Release Schedule
70 ========================
72 Betas are now released rather sporadically. We would like to achieve
73 a weekly release schedule, but personnel availability does not
74 permit. For access to the most recent code, use CVS (see
75 http://www.xemacs.org/Develop/cvsaccess.html for more information).
76 If you have need for FTP access, please let us know. It will make it
77 more likely that we release betas more often.
82 The best way to get problems fixed in XEmacs is to submit good problem
83 reports. Since this is beta software, problems are certain to exist.
84 Please read through all of part II of the XEmacs FAQ for an overview
85 of problem reporting. Other items which are most important are:
87 1. Do not submit C stack backtraces without line numbers. Since it
88 is possible to compile optimized with debug information with GCC
89 it is never a good idea to compile XEmacs without the -g flag.
90 XEmacs runs on a variety of platforms, and often it is not
91 possible to recreate problems which afflict a specific platform.
92 The line numbers in the C stack backtrace help isolate where the
93 problem is actually occurring.
95 2. Attempt to recreate the problem starting with an invocation of
96 XEmacs with `xemacs -q -no-site-file -no-autoloads'. Quite often,
97 problems are due to package interdependencies, and the like. An
98 actual bug in XEmacs should be reproducible in a default
99 configuration without loading any special packages (or the one or
100 two specific packages that cause the bug to appear). If you have
101 trouble getting anything to work at all with the above invocation,
102 use `xemacs -q -no-site-file' instead. If you need to load your
103 user init file or the site file to get the problem to occur, then
104 it has something to do with them, and you should try to isolate
105 the issue in those files.
107 3. A picture can be worth a thousand words. When reporting an
108 unusual display, it is generally best to capture the problem in a
109 screen dump and include that with the problem report. The easiest
110 way to get a screen dump is to use the xv program and its grab
111 function. Save the image as a GIF to keep bandwidth requirements
112 down without loss of information. MIME is the preferred method
113 for making the image attachments.
115 ** Getting the Source
116 =====================
118 In addition to the normal tar distribution, XEmacs source is now
119 available via CVS. Please see
121 http://www.xemacs.org/Develop/cvsaccess.html
123 * Compiling Beta XEmacs
124 =======================
126 ** Building an XEmacs from patches
127 ==================================
129 All beta releases of XEmacs are included with patches from the
130 previous version in an attempt to keep bandwidth requirements down.
131 Patches should be applied with the GNU patch program in something like
132 the following. Let's say you're upgrading XEmacs 20.15-beta10 to
133 XEmacs 20.15-beta11 and you have a full unmodified XEmacs 20.15-beta10
134 source tree to work with. Cd to the top level directory and issue the
137 $ gunzip -c /tmp/xemacs-20.15-b10-20.15-b11.patch.gz | patch -p1
139 After patching, check to see that no patches were missed by doing
140 $ find . -name \*.rej -print
142 Any rejections should be treated as serious problems to be resolved
143 before building XEmacs.
145 After seeing that there were no rejections, issue the commands
147 $ ./config.status --recheck
150 and go play minesweep for a while on an older XEmacs while the binary
153 ** Building XEmacs from a full distribution
154 ===========================================
156 Locate a convenient place where you have at least 100MB of free space
157 and issue the command
159 $ gunzip -c /tmp/xemacs-20.15-b11.tar.gz | tar xvf -
161 (or simply `tar zxvf /tmp/xemacs-20.15-b11.tar.gz' if you use GNU tar).
163 cd to the top level directory and issue an appropriate configure
164 command. One maintainer uses the following at the time of this
168 --cflags="-mpentium -march=pentium -O6 -g -fno-peep-spills" \
169 --error-checking=all --debug=yes \
170 --with-scrollbars=athena3d --with-dialogs=athena3d \
171 --with-mule --with-xfs --with-xim=xlib
173 Part of the configure output is a summary that looks something like
174 the following. (In XEmacs 21.1 and later, this summary is also
175 available as the file Installation in the top directory of your build
176 tree, and via the command M-x describe-installation.)
178 uname -a: Linux altair.xemacs.org 2.0.32 #2 Sun Nov 16 18:52:14 PST 1997 i586
180 ./configure '--cflags=-mpentium -march=pentium -O6 -g -fno-peep-spills' '--error-checking=all' '--debug=yes' '--with-scrollbars=athena3d' '--with-dialogs=athena3d' '--with-mule' '--with-xfs' '--with-xim=xlib'
183 XEmacs 21.0-b34 "Oberhasli-pre2" configured for `i586-pc-linux'.
185 Where should the build process find the source code? /home/xemacs/xemacs-20.0
186 What installation prefix should install use? /usr/local
187 What operating system and machine description files should XEmacs use?
188 `s/linux.h' and `m/intel386.h'
189 What compiler should XEmacs be built with? gcc -mpentium -march=pentium -O6 -g -fno-peep-spills
190 Should XEmacs use the GNU version of malloc? yes
191 (Using Doug Lea's new malloc from the GNU C Library.)
192 Should XEmacs use the relocating allocator for buffers? yes
193 What window system should XEmacs use? x11
194 Where do we find X Windows header files? /usr/X11/include
195 Where do we find X Windows libraries? /usr/X11/lib
196 Compiling in support for XAUTH.
197 Compiling in support for XPM images.
198 Compiling in support for X-Face message headers.
199 Compiling in support for GIF image conversion.
200 Compiling in support for JPEG image conversion.
201 Compiling in support for PNG image conversion.
202 Compiling in support for TIFF image conversion.
203 Compiling in native sound support.
204 Compiling in support for Berkeley DB.
205 Compiling in support for GNU DBM.
206 Compiling in support for ncurses.
207 Compiling in support for GPM (General Purpose Mouse).
208 Compiling in Mule (multi-lingual) support.
209 Compiling in XIM (X11R5+ I18N input method) support.
210 Using raw Xlib to provide XIM support.
211 Using XFontSet to provide bilingual menubar.
212 Compiling in support for Canna on Mule.
213 Compiling in support for the WNN input method on Mule.
215 Compiling in support for OffiX.
216 Compiling in support for proper session-management.
217 Using Lucid menubars.
218 Using Athena-3d scrollbars.
219 Using Athena-3d dialog boxes.
220 Compiling in DLL support.
221 movemail will use "dot-locking" for locking mail spool files.
222 Using Lisp_Objects with minimal tagbits.
223 Compiling in extra code for debugging.
224 Compiling in code for checking XEmacs memory usage.
225 WARNING: ---------------------------------------------------------
226 WARNING: Compiling in support for runtime error checking.
227 WARNING: XEmacs will run noticeably more slowly as a result.
228 WARNING: Error checking is on by default for XEmacs beta releases.
229 WARNING: ---------------------------------------------------------
233 Then type `make' and you should have a working XEmacs.
235 After you have verified that you have a functional editor, fire up
236 your favorite mail program and send a build report to
237 xemacs-build-reports@xemacs.org.
239 Preferrably this is done from XEmacs, following these simple steps:
241 M-x customize-group RET build-report RET
245 http://www.xemacs.org/Releases/Public-21.2/tester.html#reporting
247 If you create the report manually by other means, here is what the
248 build report should include:
250 1. Your hardware configuration (OS version, etc.)
252 2. Version numbers of software in use (X11 version, system library
253 versions if appropriate, graphics library versions if appropriate).
254 If you're on a system like Linux, include all the version numbers
255 you can because chances are it makes a difference.
257 3. The options given to configure
259 4. The configuration report illustrated above
261 For convenience all of the above items are placed in a file called
262 `Installation' in the top level build directory. They are also
263 available by performing M-x describe-installation inside XEmacs.
265 5. Any other unusual items you feel should be brought to the attention
272 [Note: these instructions have been partly updated, but not carefully
273 reviewed in some time. Caveat tester.]
275 Starting with XEmacs 21.1, much of the functionality of XEmacs has
276 been unbundled into "the packages." For more information about the
277 package system, see the Info nodes on Packages (in the XEmacs User
278 Manual) and on Packaging (in the Lisp Reference).
280 When bootstrapping XEmacs, you may need to manually install some
281 packages (at least xemacs-base and efs). These packages are available
282 by FTP at ftp://ftp.xemacs.org/pub/xemacs/packages/.
284 ** Binary package installation
285 ==============================
287 Prerequisite: XEmacs 21.0-b1.
289 Binary packages are complete entities that can be untarred at the top
290 level of an XEmacs package hierarchy and work at runtime. To install files
291 in this directory, run the command `M-x package-admin-add-binary-package'
292 and fill in appropriate values to the prompts.
294 ** Manual procedures for package management
295 ===========================================
297 Prerequisite: XEmacs 21.0
299 When adding and deleting files from a lisp directory the
300 auto-autoloads.el (global symbols) and custom-load.el (Customization
301 groups) must be kept in synch. Assuming one is manipulating a
302 directory called `lisp-utils', the command to rebuild the
303 auto-autoloads.el file is:
305 xemacs -vanilla -batch -l autoload -f batch-update-directory lisp-utils
307 The command to rebuild the custom-load.el file is:
309 xemacs -vanilla -batch -l cus-dep -f Custom-make-dependencies lisp-utils
311 To bytecompile both of these files the command is:
313 xemacs -vanilla -batch -f batch-byte-compile \
314 lisp-utils/auto-autoloads.el lisp-utils/custom-load.el
316 ** Building XEmacs and XEmacs packages from scratch
317 ===================================================
319 To build everything completely from scratch (not a high priority as a
320 design goal), the following procedure should work. (I don't recommend
323 *** Phase 1 -- Get a minimal XEmacs binary with mule to build the package
326 **** Grab a mule-base tarball and install it into a newly created package
329 **** Configure XEmacs with mule and a package-path including the
330 directory created above.
332 **** Do a `make dist' to build an XEmacs binary.
334 *** Phase 2 -- Build and install the package lisp.
336 **** Modify XEmacs.rules for local paths and the XEmacs binary created in
339 **** Do a make from the top level package lisp source directory.[1]
341 **** Do `make bindist's on all the packages you wish to install and
342 remove the byproduct .tar.gz's.
344 *** Phase 3 -- If necessary, redump XEmacs
345 with the packages that require dump-time support and install it.
347 **** Reconfigure without Mule if you don't wish a Mule-ish XEmacs, and
352 **** rm lib-src/DOC src/xemacs; make
354 **** Install or run in-place.
356 Note that this is in essence what `make all-elc' has always done.
362 ** Creating patches for submission
363 ==================================
365 Patches to XEmacs should be mailed to <xemacs-patches@xemacs.org>.
366 Each patch will be reviewed by the patches review board, and will be
367 acknowledged and added to the distribution, or rejected with an
368 explanation. Progress of the patch is tracked on the XEmacs Patches
369 mailing list, which is open subscription.
371 Patches to XEmacs Lisp packages should be sent to the maintainer of
372 the package. If the maintainer is listed as `XEmacs Development Team'
373 patches should be sent to <xemacs-patches@xemacs.org>.
375 Emailed patches should preferably be sent in MIME format and quoted
376 printable encoding (if necessary).
378 The simplest way to create well-formed patches is to use CVS and
379 Didier Verna's Patcher library (available as patcher.el in the
380 xemacs-devel package). Patcher is new and requires some setup, but
381 most of the core developers are now using it for their own patches.
382 Patcher also can be configured to create patches for several projects,
383 and recognize the project from the directory it is invoked in. This
384 makes it a useful general tool (as long as XEmacs-style patches are
385 accepted at your other projects, which is likely since they conform to
388 When making patches by hand, please use the `-u' option, or if your
389 diff doesn't support it, `-c'. Using ordinary (context-free) diffs
390 are notoriously prone to error, since line numbers tend to change when
391 others make changes to the same source file.
393 An example of the `diff' usage:
395 $ diff -u OLDFILE NEWFILE
399 $ diff -c OLDFILE NEWFILE
401 Also, it is helpful if you create the patch in the top level of the
402 XEmacs source directory:
404 $ cp -p lwlib/xlwmenu.c lwlib/xlwmenu.c.orig
406 $ diff -u lwlib/xlwmenu.c.orig lwlib/xlwmenu.c
408 Also note that if you cut & paste from an xterm to an XEmacs mail buffer
409 you will probably lose due to tab expansion. The best thing to do is
410 to use an XEmacs shell buffer to run the diff commands, or ...
411 M-x cd to the appropriate directory, and issue the command `C-u M-!' from
414 Patches should be as single-minded as possible. Mammoth patches can
415 be very difficult to place into the right slot. They are much easier
416 to deal with when broken down into functional or conceptual chunks.
417 The patches submitted by Kyle Jones and Hrvoje Niksic are stellar
418 examples of how to Do The Right Thing.
420 Each patch should be accompanied by an update to the appropriate
421 ChangeLog file. Guidelines for writing ChangeLog entries is governed
422 by the GNU coding standards. Please see
423 http://www.gnu.org/prep/standards_toc.html [Change Logs section]
426 Do not submit context diffs (either -c or -u) of ChangeLogs. Because
427 of the "stack" nature of ChangeLogs (new entries are always pushed on
428 the top), context diffs will fail to apply more often than they
429 succeed. Simply cutting and pasting the entry from an Emacs buffer to
430 the mail buffer (beware of tab expansion!) is probably easiest. The
431 Patcher library also will set up your ChangeLogs for you, and copy
432 them to the mail. Contextless unified diffs (-U 0) are also
433 acceptable but perhaps more trouble than they are worth.
435 *** Patch discussion etiquette
436 -------------------------------
438 If you intend a patch for _application_ to the sources as is, _always_
439 post it to xemacs-patches, even if there are minor points you would
440 like to have discussed by others. Not doing so will resulting in
441 patches getting "lost". If you expect that the patch will not be
442 acceptable, but are using it to stimulate discussion, then don't post
443 to xemacs-patches. Intermediate cases are up to your judgement;
444 unless you're sure you'll follow up with a "real" patch, better to err
445 on the side of posting to xemacs-patches.
447 Discussion of the _content_ of the patch (ie responses to reviewer
448 comments beyond "that's right, ok, I'll do it your way") should _always_
449 be posted to xemacs-beta. (We may split xemacs-beta into code
450 discussion and stuff that is more relevant to non-developer testers at
451 some point, but at this point xemacs-beta is the correct place for
454 If discussion results in a bright idea and you come up with a new
455 patch, normally you should post it to both mailing lists. The people
456 discussing on XEmacs Beta will want to know the outcome of the thread,
457 and you need to submit to XEmacs Patches as the "list of record."
459 If the old patch has been applied to CVS, then just submit the new one
460 as usual. If it has not been applied, then it is best to submit a new
461 patch against CVS. If possible do this as a reply to the original
462 patch post, or something following it in the thread. (The point is to
463 get the original patch post's Message-ID in your References header.)
464 In this case, also use the keyword SUPERCEDES in the Subject header to
465 indicate that the old patch is no longer valid, and that this one
468 These rules will result in a fair number of cross posts, but we don't
469 yet have a better way to handle that.
471 Note: Developers should never post to xemacs-patches unless there is a
472 patch in the post. We plan to enforce this with an automatic filter.
474 The exceptions are administrative. If you have commit authorization,
475 then post a short COMMIT notice to xemacs-patches when you commit to
476 CVS. Members of the Review Board will also post short notices of
477 administrative action (APPROVE, VETO, QUERY, etc) to xemacs-patches.
479 ** Large contributions
480 ======================
482 Perhaps you have a whole new mode, or a major synchronization with
483 upstream for a neglected package, or a synchronization with GNU Emacs
484 you would like to contribute. We welcome such contributions, but they
485 are likely to be relatively controversial, generate more comments and
486 requests for revision, and take longer to integrate. Please be
487 patient with the process.
489 *** Updates to existing packages
490 --------------------------------
492 If a package has gotten a bit out of date, or even started to bitrot,
493 we welcome patches to synchronize it with upstream/GNU Emacs versions.
494 Most packages end up varying somewhat from their GNU origins. See
495 "Syncing with GNU Emacs" for hints. Note that if you do a reasonably
496 large amount of syncing with GNU Emacs, you should log this in the
497 file itself as well as in the ChangeLog.
499 If the package is important to you, please consider becoming the
500 maintainer. (See "New packages", below.)
505 If you have a new mode or other large addition that does not require
506 changes to the core, please consider submitting it as a package, and
507 becoming the maintainer. You get direct commit privileges to the
508 repository for your package, "approval" privileges for your own
509 patches as well as third party patches to your package, and some
510 degree of veto power over patches you don't like. In return, you are
511 expected to maintain friendly liaison with the upstream developer (if
512 you aren't the upstream developer), keep watch on the XEmacs Patches
513 list for relevant patches, and be available by email to other
514 developers for discussion of changes that impact your package. It's
515 also a pretty standard route to the "core" development group, where we
516 have plenty of extra work waiting for volunteers.
518 You don't have to become the maintainer, but it virtually ensures
519 rapid acceptance of the package.
521 For help in creating new packages, see the (rather sparse) discussions
522 in the XEmacs User's Guide and the Lisp Reference Manual. The XEmacs
523 Package Release Engineer (Ville Skyttä <ville.skytta@xemacs.org> is
524 currently serving with Peter Brown <rendhalver@users.sourceforge.net>
525 assisting; Steve Youngs <youngs@xemacs.org> and Stephen Turnbull
526 <stephen@xemacs.org> also can help) is the most likely source of advice.
528 *** Syncing with GNU Emacs
529 --------------------------
531 Syncing with GNU Emacs is an important activity. Although each
532 version has its advantages and areas of concentration, it is very
533 desirable that common functionality share specifications and APIs.
534 When porting GNU code to XEmacs, the following points should be given
537 o Recent GNU Emacsen cannot be built without Mule, but XEmacs can.
538 Make sure your changes do not assume the presence of Mule.
540 o GNU Emacs nomenclature often differs from that of XEmacs.
541 Sometimes syncing the names is desirable, other times not.
543 o GNU Emacs functionality often differs from that of XEmacs.
544 Syncing functionality is often controversial.
546 It is important that you let other developers know that
547 synchronization has taken place, to what degree, and when. For this
548 purpose, we use comments of the form
550 /* Synched up with: FSF 21.3 by Stephen Turnbull */
552 in the source file itself, as the last element of the prefatory
553 material (copyright notice and commentary). Obviously the comment
554 marker needs to be changed to leading semicolons for Lisp, but
555 otherwise the format is the same.
557 Of course you should note syncing as the purpose in the ChangeLog,
558 too. But entries get buried deep in the ChangeLog file, and may even
559 get moved to a separate ChangeLog.OLD file for rarely synched files.
561 Rather than dates we use the version of GNU Emacs to sync to. If the
562 synchronization is partial, add a new comment describing what has
563 actually been synched, leaving the description of the last full sync
564 in place. At each full sync, remove all previous synchronization
567 This applies to Lisp that we have broken out into packages, but
568 remains in the GNU Emacs core, as well to core Lisp in XEmacs.