update.
[chise/xemacs-chise.git-] / etc / BETA
1                                 -*- mode:outline -*-
2
3 * Introduction
4 ==============
5
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.
9
10 ** Mailing Lists
11 ================
12
13 *** XEmacs Beta Mailing List
14 ----------------------------
15
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).
21
22 *** XEmacs Patches Mailing List
23 -------------------------------
24
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
29 or in the archives.
30
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.
34
35 *** XEmacs Design Mailing List
36 ------------------------------
37
38 XEmacs Design is for design discussions such as adding major features
39 or whole modules, or reimplementation of existing functions, to XEmacs.
40
41 *** List Administrivia
42 ----------------------
43
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).
48
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
57
58              http://list-archive.xemacs.org/xemacs-LIST
59
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.
62
63 *** Managing your subscription via the Web
64 ------------------------------------------
65
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.
69
70 *** Subscribing by e-mail
71 -------------------------
72
73 Send an email message to xemacs-LIST-request@xemacs.org with
74 `subscribe' (without the quotes) as the BODY of the message.
75
76 *** Unsubscribing by e-mail
77 ---------------------------
78
79 Send an email message to xemacs-LIST-request@xemacs.org with
80 `unsubscribe' (without the quotes) as the BODY of the message.
81
82 ** Beta Release Schedule
83 ========================
84
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.
91
92 ** Reporting Problems
93 =====================
94
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:
99
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.
107  
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.
119
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.
127
128 ** Getting the Source
129 =====================
130
131 In addition to the normal tar distribution, XEmacs source is now
132 available via CVS.  Please see
133
134             http://www.xemacs.org/Develop/cvsaccess.html
135
136 * Compiling Beta XEmacs
137 =======================
138
139 ** Building an XEmacs from patches
140 ==================================
141
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
148 shell command:
149
150 $ gunzip -c /tmp/xemacs-20.15-b10-20.15-b11.patch.gz | patch -p1
151
152 After patching, check to see that no patches were missed by doing
153 $ find . -name \*.rej -print
154
155 Any rejections should be treated as serious problems to be resolved
156 before building XEmacs.
157
158 After seeing that there were no rejections, issue the commands
159
160 $ ./config.status --recheck
161 $ make beta
162
163 and go play minesweep for a while on an older XEmacs while the binary
164 is rebuilt.
165
166 ** Building XEmacs from a full distribution
167 ===========================================
168
169 Locate a convenient place where you have at least 100MB of free space
170 and issue the command
171
172 $ gunzip -c /tmp/xemacs-20.15-b11.tar.gz | tar xvf -
173
174 (or simply `tar zxvf /tmp/xemacs-20.15-b11.tar.gz' if you use GNU tar).
175
176 cd to the top level directory and issue an appropriate configure
177 command.  One maintainer uses the following at the time of this
178 writing:
179
180 ./configure \
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
185
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.)
190
191 uname -a: Linux altair.xemacs.org 2.0.32 #2 Sun Nov 16 18:52:14 PST 1997 i586
192
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'
194
195
196 XEmacs 21.0-b34 "Oberhasli-pre2" configured for `i586-pc-linux'.
197
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.
227     Using WNN version 6.
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: ---------------------------------------------------------
243
244
245
246 Then type `make' and you should have a working XEmacs.
247
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.
251
252 Preferrably this is done from XEmacs, following these simple steps:
253
254 M-x customize-group RET build-report RET
255 M-x build-report RET
256
257 See also
258 http://www.xemacs.org/Releases/Public-21.2/tester.html#reporting
259
260 If you create the report manually by other means, here is what the
261 build report should include:
262
263 1. Your hardware configuration (OS version, etc.)
264
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.
269
270 3. The options given to configure
271
272 4. The configuration report illustrated above
273
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.
277
278 5. Any other unusual items you feel should be brought to the attention
279    of the developers.
280
281
282 * Packages
283 ==========
284
285 [Note: these instructions have been partly updated, but not carefully
286 reviewed in some time.  Caveat tester.]
287
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).
292
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/.
296
297 ** Binary package installation
298 ==============================
299
300 Prerequisite:  XEmacs 21.0-b1.
301
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.
306
307 ** Manual procedures for package management
308 ===========================================
309
310 Prerequisite: XEmacs 21.0
311
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:
317
318 xemacs -vanilla -batch -l autoload -f batch-update-directory lisp-utils
319
320 The command to rebuild the custom-load.el file is:
321
322 xemacs -vanilla -batch -l cus-dep -f Custom-make-dependencies lisp-utils
323
324 To bytecompile both of these files the command is:
325
326 xemacs -vanilla -batch -f batch-byte-compile \
327         lisp-utils/auto-autoloads.el lisp-utils/custom-load.el
328
329 ** Building XEmacs and XEmacs packages from scratch
330 ===================================================
331
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
334 building this way).
335
336 *** Phase 1 -- Get a minimal XEmacs binary with mule to build the package
337     lisp with.
338
339 **** Grab a mule-base tarball and install it into a newly created package
340      directory.
341
342 **** Configure XEmacs with mule and a package-path including the
343      directory created above.
344
345 **** Do a `make dist' to build an XEmacs binary.
346
347 *** Phase 2 -- Build and install the package lisp.
348
349 **** Modify XEmacs.rules for local paths and the XEmacs binary created in 
350      Phase 1.
351
352 **** Do a make from the top level package lisp source directory.[1]
353
354 **** Do `make bindist's on all the packages you wish to install and
355      remove the byproduct .tar.gz's.
356
357 *** Phase 3 -- If necessary, redump XEmacs
358     with the packages that require dump-time support and install it.
359
360 **** Reconfigure without Mule if you don't wish a Mule-ish XEmacs, and
361      rebuild XEmacs.
362
363 - or -
364
365 **** rm lib-src/DOC src/xemacs; make
366
367 **** Install or run in-place.
368
369 Note that this is in essence what `make all-elc' has always done.
370
371
372 * Improving XEmacs
373 =================
374
375 ** Creating patches for submission
376 ==================================
377
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,
386 but doesn't hurt.)
387
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>.
391
392 Emailed patches should preferably be sent in MIME format and quoted
393 printable encoding (if necessary).
394
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
403 the GNU standards).
404
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.
409
410 An example of the `diff' usage:
411
412 $ diff -u OLDFILE NEWFILE
413
414 -or-
415
416 $ diff -c OLDFILE NEWFILE
417
418 Also, it is helpful if you create the patch in the top level of the
419 XEmacs source directory:
420
421 $ cp -p lwlib/xlwmenu.c lwlib/xlwmenu.c.orig
422   hack, hack, hack....
423 $ diff -u lwlib/xlwmenu.c.orig lwlib/xlwmenu.c
424
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
429 within XEmacs.
430
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.
436
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]
441 for details.
442
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.
451
452 *** Patch discussion etiquette
453 -------------------------------
454
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.
463
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
468 widely read channel.
469
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."
474
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
482 replaces it.
483
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.
486
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.
489
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.
494
495 ** Large contributions
496 ======================
497
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.
504
505 *** Updates to existing packages
506 --------------------------------
507
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.
514
515 If the package is important to you, please consider becoming the
516 maintainer.  (See "New packages", below.)
517
518 *** New packages
519 ----------------
520
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.
533
534 You don't have to become the maintainer, but it virtually ensures
535 rapid acceptance of the package.
536
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.
543
544 *** Syncing with GNU Emacs
545 --------------------------
546
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
551 special attention:
552
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.
555
556   o GNU Emacs nomenclature often differs from that of XEmacs.
557     Sometimes syncing the names is desirable, other times not.
558
559   o GNU Emacs functionality often differs from that of XEmacs.
560     Syncing functionality is often controversial.
561
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
565
566 /* Synched up with: FSF 21.3 by Stephen Turnbull */
567
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.
572
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.
576
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
581 comments.
582
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.