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