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>, preferably with
9 'M-x report-xemacs-bug RET'.
14 *** XEmacs Beta Mailing List
15 ----------------------------
17 If you are not subscribed to the XEmacs beta list you should be.
18 Currently all discussion of development issues, including bug reports
19 and coding discussion, takes place on the XEmacs Beta mailing list.
20 Only patches and administrative actions regarding patches are sent
21 elsewhere (to the XEmacs Patches list).
23 *** XEmacs Patches Mailing List
24 -------------------------------
26 XEmacs Patches records proposed changes to XEmacs, and their
27 disposition. It is open subscription, and all patches that are
28 seriously proposed for inclusion in XEmacs should be posted here. You
29 can follow progress of your patch by subscribing to the mailing list
32 Besides patches, only actions by members of the XEmacs Review Board
33 should be posted to this list. All discussion should be redirected to
34 XEmacs Beta or XEmacs Design.
36 *** XEmacs Design Mailing List
37 ------------------------------
39 XEmacs Design is for design discussions such as adding major features
40 or whole modules, or reimplementation of existing functions, to XEmacs.
42 *** List Administrivia
43 ----------------------
45 In the descriptions below, the word LIST (all uppercase) is a
46 variable. Substitute "beta", "design", or "patches" as appropriate
47 (to get "xemacs-beta" as the mailbox for the XEmacs Beta mailing list,
48 or <http://www.xemacs.org/Lists/#xemacs-beta> for its URL).
50 The XEmacs mailing lists are managed by the Mailman mailing list
51 package, and the usual Mailman commands work. Do not send mailing
52 list requests to the main address (<xemacs-LIST@xemacs.org>), always
53 send them to <xemacs-LIST-request@xemacs.org>. If you have problems
54 with the list itself, they should be brought to the attention of the
55 XEmacs Mailing List manager <list-manager@xemacs.org> (the same
56 mailbox, "list-manager", for all lists). All public mailing lists
57 have searchable archives. The URL is
59 http://list-archive.xemacs.org/xemacs-LIST
61 Note that the xemacs-LIST-admin address is used internally by the
62 Mailman software; it is NOT a synonym for xemacs-LIST-request.
64 *** Managing your subscription via the Web
65 ------------------------------------------
67 Subscription, unsubscription, and options (such as digests and
68 temporarily suspending delivery) can be accomplished via the web
69 interface at <http://www.xemacs.org/Lists/#xemacs-LIST>.
71 *** Subscribing by e-mail
72 -------------------------
74 Send an email message to <xemacs-LIST-request@xemacs.org> with
75 `subscribe' (without the quotes) as the BODY of the message.
77 *** Unsubscribing by e-mail
78 ---------------------------
80 Send an email message to <xemacs-LIST-request@xemacs.org> with
81 `unsubscribe' (without the quotes) as the BODY of the message.
83 ** Beta Release Schedule
84 ========================
86 We would like to achieve a weekly or fortnightly release cycle (you
87 know the Open Source model: release early, release often), and in a
88 perfect world that would indeed be the case. There are at least three
89 things that often get in the way of that goal: 1) The Release Manager
90 has a life outside of XEmacs (hard to believe, I know, but true),
91 2) we like to make releases that will build (at least on the Release
92 Manager's box), and 3) Murphy likes to throw a spanner in the works
93 right when you least expect it (Murphy's Law: Whatever can go wrong,
96 If you'd like to keep right up to date and ride the bleeding edge, use
97 CVS (see <http://www.xemacs.org/Develop/cvsaccess.html>). If you
98 can't use CVS for some reason and must use FTP, please let us know.
99 it will make it more likely that we release betas more often.
102 ** Reporting Problems
103 =====================
105 The best way to get problems fixed in XEmacs is to submit good problem
106 reports, 'M-x report-xemacs-bug RET' will help you do this (assuming
107 you have a usable XEmacs). Since this is beta software, problems are
108 certain to exist. Please read through all of part II of the XEmacs
109 FAQ for an overview of problem reporting. Other items which are most
112 1. Do not submit C stack backtraces without line numbers. Since it
113 is possible to compile optimized with debug information with GCC
114 it is never a good idea to compile XEmacs without the -g flag.
115 XEmacs runs on a variety of platforms, and often it is not
116 possible to recreate problems which afflict a specific platform.
117 The line numbers in the C stack backtrace help isolate where the
118 problem is actually occurring.
120 2. Attempt to recreate the problem starting with an invocation of
121 XEmacs with `xemacs -no-autoloads'. Quite often, problems are
122 due to package interdependencies, and the like. An actual bug
123 in XEmacs should be reproducible in a default configuration
124 without loading any special packages (or the one or two specific
125 packages that cause the bug to appear). If you have trouble
126 getting anything to work at all with the above invocation, use
127 `xemacs -vanilla' instead. If you need to load your user init
128 file or the site file to get the problem to occur, then it has
129 something to do with them, and you should try to isolate the
130 issue in those files.
132 3. A picture can be worth a thousand words. When reporting an
133 unusual display, it is generally best to capture the problem in a
134 screen dump and include that with the problem report. The easiest
135 way to get a screen dump is to use the xv program and its grab
136 function. Save the image as a GIF to keep bandwidth requirements
137 down without loss of information. MIME is the preferred method
138 for making the image attachments.
140 ** Getting the Source
141 =====================
143 In addition to the normal tar distribution, XEmacs source is now
144 available via CVS. Please see
146 http://www.xemacs.org/Develop/cvsaccess.html
148 * Compiling Beta XEmacs
149 =======================
151 ** Building an XEmacs from patches
152 ==================================
154 All beta releases of XEmacs are included with patches from the previous
155 version in an attempt to keep bandwidth requirements down. Patches
156 should be applied with the GNU patch program in something like the
157 following. Let's say you're upgrading XEmacs 21.5-beta9 to XEmacs
158 21.5-beta10 and you have a full unmodified XEmacs 21.5-beta9 source
159 tree to work with. Change to the top level directory and issue the
162 $ gunzip -c /tmp/xemacs-21.5.9-21.5.10.patch.gz | patch -p1
164 After patching, check to see that no patches were missed by doing
165 $ find . -name \*.rej -print
167 Any rejections should be treated as serious problems to be resolved
168 before building XEmacs.
170 After seeing that there were no rejections, issue the commands
172 $ ./config.status --recheck
173 $ make beta > ./beta.err 2>&1
174 $ make check > ./xemacs-make-check.err 2>&1
176 Redirect the output from make to those files because you'll use them
177 later when you send off a build report with 'M-x build-report RET'
179 ** Building XEmacs from a full distribution
180 ===========================================
182 Locate a convenient place where you have at least 100MB of free space
183 and issue the command
185 $ gunzip -c /tmp/xemacs-21.5.10.tar.gz | tar xvf -
187 (or simply `tar zxvf /tmp/xemacs-21.5.10.tar.gz' if you use GNU tar).
189 cd to the top level directory and issue an appropriate configure
190 command. One maintainer uses the following at the time of this
195 --site-prefixes=/usr/local/pgsql:/usr/local/BerkeleyDB.4.1 \
196 --dynamic=yes --with-gtk=no --with-gnome=no --with-toolbars \
197 --with-wmcommand --with-athena=next --with-menubars=lucid \
198 --with-scrollbars=athena --with-dialogs=athena --with-widgets=athena \
199 --with-gif --with-sound=native,noesd --with-site-lisp=no \
200 --with-site-modules --pdump --with-mule --with-xfs --debug \
201 --error-checking=all --memory-usage-stats --use-kkcc \
202 --with-clash-detection
204 Part of the configure output is a summary that looks something
205 like the following. (this summary is also available as the file
206 'Installation' in the top directory of your build tree, and via
207 the command 'M-x describe-installation RET').
209 uname -a: Linux eicq 2.4.20 #1 Wed Dec 18 02:14:29 EST 2002 i586 unknown
211 ./configure '--extra-verbose' '--site-prefixes=/usr/local/pgsql:/usr/local/BerkeleyDB.4.1' '--dynamic=yes' '--with-gtk=no' '--with-gnome=no' '--with-toolbars' '--with-wmcommand' '--with-athena=next' '--with-menubars=lucid' '--with-scrollbars=athena' '--with-dialogs=athena' '--with-widgets=athena' '--with-gif' '--with-sound=native,noesd' '--with-site-lisp=no' '--with-site-modules' '--pdump' '--with-mule' '--with-xfs' '--debug' '--error-checking=all' '--memory-usage-stats' '--use-kkcc' '--with-clash-detection'
214 XEmacs 21.5-b10 "burdock" (+CVS-20030131) configured for `i586-pc-linux'.
217 Compilation / Installation:
218 Source code location: /usr/local/src/xemacs
219 Installation prefix: /usr/local
220 Additional prefixes: /usr/local/pgsql /usr/local/BerkeleyDB.4.1
221 Operating system description file: `s/linux.h'
222 Machine description file: `m/intel386.h'
223 Compiler: gcc -Wall -Wno-switch -Winline -Wmissing-prototypes -Wsign-compare -Wundef -Wstrict-prototypes -Wshadow -Wmissing-declarations -O1 -ggdb3 -Wall -Wchar-subscripts -Wunused -Wundef -Wshadow -Wsign-compare -Wmissing-declarations -march=k6
224 Relocating allocator for buffers: no
225 GNU version of malloc: yes
226 - Using Doug Lea's new malloc from the GNU C Library.
229 Compiling in support for the X window system:
230 - X Windows headers location: /usr/X11/include
231 - X Windows libraries location: /usr/X11/lib
232 - Handling WM_COMMAND properly.
233 Compiling in support for the Athena widget set:
234 - Athena headers location: X11/neXtaw
235 - Athena library to link: neXtaw
236 Using Lucid menubars.
237 Using Athena scrollbars.
238 Using Athena dialog boxes.
239 Using Athena native widgets.
242 Compiling in support for ncurses.
243 Compiling in support for GPM (General Purpose Mouse).
246 Compiling in support for GIF images (builtin).
247 Compiling in support for XPM images.
248 Compiling in support for PNG images.
249 Compiling in support for JPEG images.
250 Compiling in support for TIFF images.
251 Compiling in support for X-Face message headers.
254 Compiling in support for sound (native).
257 Compiling in support for Berkeley database.
258 Compiling in support for PostgreSQL.
259 - Using PostgreSQL header file: libpq-fe.h
260 - Using PostgreSQL V7 bindings.
262 Internationalization:
263 Compiling in support for Mule (multi-lingual Emacs).
264 Compiling in support for XIM (X11R5+ I18N input method).
265 - Using raw Xlib to provide XIM support.
266 - Using XFontSet to provide bilingual menubar.
269 Compiling in support for "dot-locking" mail spool file locking method.
272 Inhibiting IPv6 canonicalization at startup.
273 Compiling in support for dynamic shared object modules.
274 Using the new GC algorithms.
275 Using the new portable dumper.
276 Compiling in support for extra debugging code.
277 WARNING: ---------------------------------------------------------
278 WARNING: Compiling in support for runtime error checking.
279 WARNING: XEmacs will run noticeably more slowly as a result.
280 WARNING: Error checking is on by default for XEmacs beta releases.
281 WARNING: ---------------------------------------------------------
287 $ make > ./beta.err 2>&1
288 $ make check > ./xemacs-make-check.err 2>&1
290 ...and you should have a working XEmacs.
292 After you have verified that you have a functional editor, fire up
293 your favorite mail program and send a build report to
294 <xemacs-buildreports@xemacs.org>.
296 Preferably this is best done from XEmacs, following these simple steps:
298 M-x customize-group RET build-report RET
302 <http://www.xemacs.org/Releases/Public-21.2/tester.html#reporting>
304 If you create the report manually by other means, here is what the
305 build report should include:
307 1. Your hardware configuration (OS version, etc.)
309 2. Version numbers of software in use (X11 version, system library
310 versions if appropriate, graphics library versions if appropriate).
311 If you're on a system like Linux, include all the version numbers
312 you can because chances are it makes a difference.
314 3. The options given to configure
316 4. The configuration report illustrated above
318 For convenience all of the above items are placed in a file called
319 `Installation' in the top level build directory. They are also
320 available by performing M-x describe-installation inside XEmacs.
322 5. Any other unusual items you feel should be brought to the attention
329 [Note: these instructions have been partly updated, but not carefully
330 reviewed in some time. Caveat tester.]
332 Starting with XEmacs 21.1, much of the functionality of XEmacs has
333 been unbundled into "the packages." For more information about the
334 package system, see the Info nodes on Packages (in the XEmacs User
335 Manual) and on Packaging (in the Lisp Reference).
337 When bootstrapping XEmacs, you may need to manually install some
338 packages (at least xemacs-base and efs). These packages are available
339 by FTP at <ftp://ftp.xemacs.org/pub/xemacs/packages/>.
341 ** Binary package installation
342 ==============================
344 Prerequisite: XEmacs 21.0-b1.
346 Binary packages are complete entities that can be untarred at the top
347 level of an XEmacs package hierarchy and work at runtime. To install files
348 in this directory, run the command `M-x package-admin-add-binary-package'
349 and fill in appropriate values to the prompts.
351 ** Manual procedures for package management
352 ===========================================
354 Prerequisite: XEmacs 21.0
356 When adding and deleting files from a lisp directory the
357 auto-autoloads.el (global symbols) and custom-load.el (Customization
358 groups) must be kept in synch. Assuming one is manipulating a
359 directory called `lisp-utils', the command to rebuild the
360 auto-autoloads.el file is:
362 xemacs -vanilla -batch \
363 -eval \("setq autoload-package-name \"lisp-utils\""\) \
364 -f batch-update-directory lisp-utils
366 The command to rebuild the custom-load.el file is:
368 xemacs -vanilla -batch -f Custom-make-dependencies lisp-utils
370 To byte-compile both of these files the command is:
372 xemacs -vanilla -batch -f batch-byte-compile \
373 lisp-utils/auto-autoloads.el lisp-utils/custom-load.el
375 Of course, being a beta tester, you'd be aware that it is much easier
376 to manage your XEmacs packages with PUI.
378 ** Building XEmacs and XEmacs packages from scratch
379 ===================================================
381 To build everything completely from scratch isn't hard, just time
384 *** Step 1 - grab the sources (core and packages)
386 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs login
387 [password: "cvs" (sans quotes)]
389 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs co -d xemacs-21.5 xemacs
391 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs co packages
393 *** Step 2 - build XEmacs
396 $ ./configure [options...]
397 $ make > ./beta.err 2>&1
398 $ make check > ./xemacs-make-check.err 2>&1
402 $ make install > ./xemacs-make-install.err 2>&1
404 *** Step 3 - build and install the packages
407 $ cp Local.rules.template Local.rules
409 Then edit Local.rules to suit your needs/environment
410 see: (Info-goto-node "(xemacs)Local.rules file") for details about
420 ** Creating patches for submission
421 ==================================
423 All patches to XEmacs that are seriously proposed for inclusion (eg,
424 bug fixes) should be mailed to <xemacs-patches@xemacs.org>. Each
425 patch will be reviewed by the patches review board, and will be
426 acknowledged and added to the distribution, or rejected with an
427 explanation. Progress of the patch is tracked on the XEmacs Patches
428 mailing list, which is open subscription. (If a patch is simply
429 intended to facilitate discussion, "I mean something that works like
430 this but this is really rough", a Cc to XEmacs Patches is optional,
433 Patches to XEmacs Lisp packages should be sent to the maintainer of
434 the package. If the maintainer is listed as `XEmacs Development Team'
435 patches should be sent to <xemacs-patches@xemacs.org>.
437 Emailed patches should preferably be sent in MIME format and quoted
438 printable encoding (if necessary).
440 The simplest way to create well-formed patches is to use CVS and
441 Didier Verna's Patcher library (available as patcher.el in the
442 xemacs-devel package). Patcher is new and requires some setup, but
443 most of the core developers are now using it for their own patches.
444 Patcher also can be configured to create patches for several projects,
445 and recognize the project from the directory it is invoked in. This
446 makes it a useful general tool (as long as XEmacs-style patches are
447 accepted at your other projects, which is likely since they conform to
450 When making patches by hand, please use the `-u' option, or if your
451 diff doesn't support it, `-c'. Using ordinary (context-free) diffs
452 are notoriously prone to error, since line numbers tend to change when
453 others make changes to the same source file.
455 An example of the `diff' usage:
457 $ diff -u OLDFILE NEWFILE
461 $ diff -c OLDFILE NEWFILE
463 Also, it is helpful if you create the patch in the top level of the
464 XEmacs source directory:
466 $ cp -p lwlib/xlwmenu.c lwlib/xlwmenu.c.orig
468 $ diff -u lwlib/xlwmenu.c.orig lwlib/xlwmenu.c
470 Also note that if you cut & paste from an xterm to an XEmacs mail buffer
471 you will probably lose due to tab expansion. The best thing to do is
472 to use an XEmacs shell buffer to run the diff commands, or ...
473 M-x cd to the appropriate directory, and issue the command `C-u M-!' from
476 Patches should be as single-minded as possible. Mammoth patches can
477 be very difficult to place into the right slot. They are much easier
478 to deal with when broken down into functional or conceptual chunks.
479 The patches submitted by Kyle Jones and Hrvoje Niksic are stellar
480 examples of how to "Do The Right Thing".
482 Each patch should be accompanied by an update to the appropriate
483 ChangeLog file. Guidelines for writing ChangeLog entries is governed
484 by the GNU coding standards. Please see
485 <http://www.gnu.org/prep/standards_toc.html> [Change Logs section]
488 Do not submit context diffs (either -c or -u) of ChangeLogs. Because
489 of the "stack" nature of ChangeLogs (new entries are always pushed on
490 the top), context diffs will fail to apply more often than they
491 succeed. Simply cutting and pasting the entry from an Emacs buffer to
492 the mail buffer (beware of tab expansion!) is probably easiest. The
493 Patcher library also will set up your ChangeLogs for you, and copy
494 them to the mail. Context-less unified diffs (-U 0) are also
497 *** Patch discussion etiquette
498 -------------------------------
500 If you intend a patch for _application_ to the sources as is, _always_
501 post it to xemacs-patches, even if there are minor points you would
502 like to have discussed by others. Not doing so will resulting in
503 patches getting "lost". If you expect that the patch will not be
504 acceptable, but are using it to stimulate discussion, then don't post
505 to xemacs-patches. Intermediate cases are up to your judgment;
506 unless you're sure you'll follow up with a "real" patch, better to err
507 on the side of posting to xemacs-patches.
509 Discussion of the _content_ of the patch (ie responses to reviewer
510 comments beyond "that's right, ok, I'll do it your way") should _always_
511 be posted to xemacs-beta or to xemacs-design. If you're not sure
512 which is more appropriate, send it to xemacs-beta. That is the most
515 If discussion results in a bright idea and you come up with a new
516 patch, normally you should post it to both mailing lists. The people
517 discussing on XEmacs Beta will want to know the outcome of the thread,
518 and you need to submit to XEmacs Patches as the "list of record."
520 If the old patch has been applied to CVS, then just submit the new one
521 as usual. If it has not been applied, then it is best to submit a new
522 patch against CVS. If possible do this as a reply to the original
523 patch post, or something following it in the thread. (The point is to
524 get the original patch post's Message-ID in your References header.)
525 In this case, also use the keyword SUPERSEDES in the Subject header to
526 indicate that the old patch is no longer valid, and that this one
529 These rules will result in a fair number of cross posts, but we don't
530 yet have a better way to handle that.
532 Note: Developers should never post to xemacs-patches unless there is a
533 patch in the post. We plan to enforce this with an automatic filter.
535 The exceptions are administrative. If you have commit authorization,
536 then post a short COMMIT notice to xemacs-patches when you commit to
537 CVS. Members of the Review Board will also post short notices of
538 administrative action (APPROVE, VETO, QUERY, etc) to xemacs-patches.
540 ** Large contributions
541 ======================
543 Perhaps you have a whole new mode, or a major synchronization with
544 upstream for a neglected package, or a synchronization with GNU Emacs
545 you would like to contribute. We welcome such contributions, but they
546 are likely to be relatively controversial, generate more comments and
547 requests for revision, and take longer to integrate. Please be
548 patient with the process.
550 *** Updates to existing packages
551 --------------------------------
553 If a package has gotten a bit out of date, or even started to bitrot,
554 we welcome patches to synchronize it with upstream/GNU Emacs versions.
555 Most packages end up varying somewhat from their GNU origins. See
556 "Syncing with GNU Emacs" for hints. Note that if you do a reasonably
557 large amount of syncing with GNU Emacs, you should log this in the
558 file itself as well as in the ChangeLog.
560 If the package is important to you, please consider becoming the
561 maintainer. (See "New packages", below.)
566 If you have a new mode or other large addition that does not require
567 changes to the core, please consider submitting it as a package, and
568 becoming the maintainer. You get direct commit privileges to the
569 repository for your package, "approval" privileges for your own
570 patches as well as third party patches to your package, and some
571 degree of veto power over patches you don't like. In return, you are
572 expected to maintain friendly liaison with the upstream developer (if
573 you aren't the upstream developer), keep watch on the XEmacs Patches
574 list for relevant patches, and be available by email to other
575 developers for discussion of changes that impact your package. It's
576 also a pretty standard route to the "core" development group, where we
577 have plenty of extra work waiting for volunteers.
579 You don't have to become the maintainer, but it virtually ensures
580 rapid acceptance of the package.
582 For help in creating new packages, see the (rather sparse) discussions
583 in the XEmacs User's Guide and the Lisp Reference Manual. The XEmacs
584 Package Release Engineer (Ville Skyttä <scop@xemacs.org> is currently
585 serving with Norbert Koch <viteno@xemacs.org> assisting; Steve
586 Youngs <youngs@xemacs.org> and Stephen Turnbull <stephen@xemacs.org>
587 also can help) are the most likely sources of advice.
589 *** Syncing with GNU Emacs
590 --------------------------
592 Syncing with GNU Emacs is an important activity. Although each
593 version has its advantages and areas of concentration, it is very
594 desirable that common functionality share specifications and APIs.
595 When porting GNU code to XEmacs, the following points should be given
598 o Recent GNU Emacsen cannot be built without Mule, but XEmacs can.
599 Make sure your changes do not assume the presence of Mule.
601 o GNU Emacs nomenclature often differs from that of XEmacs.
602 Sometimes syncing the names is desirable, other times not.
604 o GNU Emacs functionality often differs from that of XEmacs.
605 Syncing functionality is often controversial.
607 It is important that you let other developers know that
608 synchronization has taken place, to what degree, and when. For this
609 purpose, we use comments of the form
611 /* Synched up with: FSF 21.3 by Stephen Turnbull */
613 in the source file itself, as the last element of the prefatory
614 material (copyright notice and commentary). Obviously the comment
615 marker needs to be changed to leading semicolons for Lisp, but
616 otherwise the format is the same.
618 Of course you should note syncing as the purpose in the ChangeLog,
619 too. But entries get buried deep in the ChangeLog file, and may even
620 get moved to a separate ChangeLog.OLD file for rarely synched files.
622 Rather than dates we use the version of GNU Emacs to sync to. If the
623 synchronization is partial, add a new comment describing what has
624 actually been synched, leaving the description of the last full sync
625 in place. At each full sync, remove all previous synchronization
628 This applies to Lisp that we have broken out into packages, but
629 remains in the GNU Emacs core, as well to core Lisp in XEmacs.