This commit was generated by cvs2svn to compensate for changes in r1647,
[chise/xemacs-chise.git-] / etc / BETA
1                                 -*- mode:outline -*-
2
3 * Introduction
4 ==============
5
6 You are running an experimental version of XEmacs.  Please do not
7 report problems with Beta XEmacs to comp.emacs.xemacs.  Report them to
8 xemacs-beta@xemacs.org.
9
10 ** XEmacs Beta Mailing List
11 ===========================
12
13 *** Subscribing
14 ---------------
15
16 If you are not subscribed to the XEmacs beta list you should be.  Send
17 an email message to xemacs-beta-request@xemacs.org with `subscribe'
18 (without the quotes) as the BODY of the message.
19
20 *** Unsubscribing
21 -----------------
22
23 To unsubscribe from the list send an email message to
24 xemacs-beta-request@xemacs.org with `unsubscribe' (without the quotes)
25 as the BODY of the message.
26
27 *** Administrivia
28 -----------------
29
30 The XEmacs beta list is managed by the Majordomo mailing list package,
31 and the usual Majordomo commands work.  Do not send mailing list
32 requests to the main address (xemacs-beta@xemacs.org), always send
33 them to xemacs-beta-request@xemacs.org.  If you have problems with the
34 list itself, they should be brought to the attention of the XEmacs
35 Mailing List manager Jason Mastaler <list-manager@xemacs.org>.
36
37
38 ** Beta Release Schedule
39 ========================
40
41 The URL ftp://ftp.xemacs.org/pub/xemacs/beta/README always contains
42 the best estimate of when the next beta XEmacs will be released.  For
43 weekend betas the release time is generally in the vicinity of 2PM to
44 5PM US Pacific Time (Universal Time minus 8 hours).  For weekday
45 betas, the release time is generally in the vicinity of 8PM to
46 Midnight US Pacific Time on the listed day.
47
48 Betas are nominally a week apart, scheduled on every Saturday.
49 Midweek releases are made when a serious enough problem warrants it.
50
51
52 ** Reporting Problems
53 =====================
54
55 The best way to get problems fixed in XEmacs is to submit good problem
56 reports.  Since this is beta software, problems are certain to exist.
57 Please read through all of part II of the XEmacs FAQ for an overview
58 of problem reporting.  Other items which are most important are:
59
60 1.  Do not submit C stack backtraces without line numbers.  Since it
61     is possible to compile optimized with debug information with GCC
62     it is never a good idea to compile XEmacs without the -g flag.
63     XEmacs runs on a variety of platforms, and often it is not
64     possible to recreate problems which afflict a specific platform.
65     The line numbers in the C stack backtrace help isolate where the
66     problem is actually occurring.
67  
68 2.  Attempt to recreate the problem starting with an invocation of
69     XEmacs with `xemacs -q -no-site-file'.  Quite often, problems are
70     due to package interdependencies, and the like.  An actual bug in
71     XEmacs should be reproducible in a default configuration without
72     loading any special packages (or the one or two specific packages
73     that cause the bug to appear).
74
75 3.  A picture can be worth a thousand words.  When reporting an
76     unusual display, it is generally best to capture the problem in a
77     screen dump and include that with the problem report.  The easiest
78     way to get a screen dump is to use the xv program and its grab
79     function.  Save the image as a GIF to keep bandwidth requirements
80     down without loss of information.  MIME is the preferred method
81     for making the image attachments.
82
83 ** Getting the Source
84 =====================
85
86 In addition to the normal tar distribution, XEmacs source is now
87 available via CVS.  Please see the URL: <URL:http://cvs.xemacs.org/~xemacs/>.
88
89 * Compiling Beta XEmacs
90 =======================
91
92 ** Building an XEmacs from patches
93 ==================================
94
95 All beta releases of XEmacs are included with patches from the
96 previous version in an attempt to keep bandwidth requirements down.
97 Patches should be applied with the GNU patch program in something like
98 the following.  Let's say you're upgrading XEmacs 20.15-beta10 to
99 XEmacs 20.15-beta11 and you have a full unmodified XEmacs 20.15-beta10
100 source tree to work with.  Cd to the top level directory and issue the
101 shell command:
102
103 $ gunzip -c /tmp/xemacs-20.15-b10-20.15-b11.patch.gz | patch -p1
104
105 After patching, check to see that no patches were missed by doing
106 $ find . -name \*.rej -print
107
108 Any rejections should be treated as serious problems to be resolved
109 before building XEmacs.
110
111 After seeing that there were no rejections, issue the commands
112
113 $ ./config.status --recheck
114 $ make beta
115
116 and go play minesweep for a while on an older XEmacs while the binary
117 is rebuilt.
118
119 ** Building XEmacs from a full distribution
120 ==============================================
121
122 Locate a convenient place where you have at least 100MB of free space
123 and issue the command
124
125 $ gunzip -c /tmp/xemacs-20.15-b11.tar.gz | tar xvf -
126
127 (or simply `tar zxvf /tmp/xemacs-20.15-b11.tar.gz' if you use GNU tar).
128
129 cd to the top level directory and issue an appropriate configure
130 command.  One maintainer uses the following at the time of this
131 writing:
132
133 ./configure \
134         --cflags="-mpentium -march=pentium -O6 -g -fno-peep-spills" \
135         --error-checking=all --debug=yes \
136         --with-scrollbars=athena3d --with-dialogs=athena3d \
137         --with-mule --with-xfs --with-xim=xlib
138
139 Part of the configure output is a summary that looks something like:
140
141 uname -a: Linux altair.xemacs.org 2.0.32 #2 Sun Nov 16 18:52:14 PST 1997 i586
142
143 ./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'
144
145
146 XEmacs 21.0-b34 "Oberhasli-pre2" configured for `i586-pc-linux'.
147
148   Where should the build process find the source code?    /home/xemacs/xemacs-20.0
149   What installation prefix should install use?            /usr/local
150   What operating system and machine description files should XEmacs use?
151         `s/linux.h' and `m/intel386.h'
152   What compiler should XEmacs be built with?              gcc -mpentium -march=pentium -O6 -g -fno-peep-spills
153   Should XEmacs use the GNU version of malloc?            yes
154   (Using Doug Lea's new malloc from the GNU C Library.)
155   Should XEmacs use the relocating allocator for buffers? yes
156   What window system should XEmacs use?                   x11
157   Where do we find X Windows header files?                /usr/X11/include
158   Where do we find X Windows libraries?                   /usr/X11/lib
159   Compiling in support for XAUTH.
160   Compiling in support for XPM images.
161   Compiling in support for X-Face message headers.
162   Compiling in support for GIF image conversion.
163   Compiling in support for JPEG image conversion.
164   Compiling in support for PNG image conversion.
165   Compiling in support for TIFF image conversion.
166   Compiling in native sound support.
167   Compiling in support for Berkeley DB.
168   Compiling in support for GNU DBM.
169   Compiling in support for ncurses.
170   Compiling in support for GPM (General Purpose Mouse).
171   Compiling in Mule (multi-lingual) support.
172   Compiling in XIM (X11R5+ I18N input method) support.
173     Using raw Xlib to provide XIM support.
174     Using XFontSet to provide bilingual menubar.
175   Compiling in support for Canna on Mule.
176   Compiling in support for the WNN input method on Mule.
177     Using WNN version 6.
178   Compiling in support for OffiX.
179   Compiling in support for proper session-management.
180   Using Lucid menubars.
181   Using Athena-3d scrollbars.
182   Using Athena-3d dialog boxes.
183   Compiling in DLL support.
184   movemail will use "dot-locking" for locking mail spool files.
185   Using Lisp_Objects with minimal tagbits.
186   Compiling in extra code for debugging.
187   Compiling in code for checking XEmacs memory usage.
188   WARNING: ---------------------------------------------------------
189   WARNING: Compiling in support for runtime error checking.
190   WARNING: XEmacs will run noticeably more slowly as a result.
191   WARNING: Error checking is on by default for XEmacs beta releases.
192   WARNING: ---------------------------------------------------------
193
194
195
196 Then type `make' and you should have a working XEmacs.
197
198 After you have verified that you have a functional editor, fire up
199 your favorite mail program and send a build report to
200 xemacs-build-reports@xemacs.org.  The build report should include
201
202 1. Your hardware configuration (OS version, etc.)
203
204 2. Version numbers of software in use (X11 version, system library
205    versions if appropriate, graphics library versions if appropriate).
206    If you're on a system like Linux, include all the version numbers
207    you can because chances are it makes a difference.
208
209 3. The options given to configure
210
211 4. The configuration report illustrated above
212
213    For convenience all of the above items are placed in a file called
214    `Installation' in the top level build directory.  They are also
215    available by performing M-x describe-installation inside XEmacs.
216
217 5. Any other unusual items you feel should be brought to the attention
218    of the developers.
219
220 ** Creating patches for submission
221 ==================================
222
223 Patches to XEmacs should be mailed to <xemacs-patches@xemacs.org>.
224 Each patch will be reviewed by the patches review board, and will be
225 acked and added to the distribution, or rejected with an explanation.
226
227 Patches to XEmacs Lisp packages should be sent to the maintainer of
228 the package.  If the maintainer is listed as `XEmacs Development Team'
229 patches should be sent to <xemacs-patches@xemacs.org>.
230
231 Emailed patches should preferably be sent in MIME format and quoted
232 printable encoding (if necessary).
233
234 When making patches, please use the `-u' option, or if your diff
235 doesn't support it, `-c'.  Using ordinary (context-free) diffs are
236 notoriously prone to error, since line numbers tend to change when
237 others make changes to the same source file.
238
239 An example of the `diff' usage:
240
241 $ diff -u OLDFILE NEWFILE
242
243 -or-
244
245 $ diff -c OLDFILE NEWFILE
246
247 Also, it is helpful if you create the patch in the top level of the
248 XEmacs source directory:
249
250 $ cp -p lwlib/xlwmenu.c lwlib/xlwmenu.c.orig
251   hack, hack, hack....
252 $ diff -u lwlib/xlwmenu.c.orig lwlib/xlwmenu.c
253
254 Each patch should be accompanied by an update to the appropriate
255 ChangeLog file.  Please don't mail patches to ChangeLog because they
256 have an extremely high rate of failure; just mail us the new part of
257 the ChangeLog you added.
258
259 Also note that if you cut & paste from an xterm to an XEmacs mail buffer
260 you will probably lose due to tab expansion.  The best thing to do is
261 to use an XEmacs shell buffer to run the diff commands, or ...
262 M-x cd to the appropriate directory, and issue the command `C-u M-!' from
263 within XEmacs.
264
265 Guidelines for writing ChangeLog entries is governed by the GNU coding 
266 standards.  Please see
267         http://www.gnu.org/prep/standards_toc.html   [Change Logs section]
268 for details.
269
270 Patches should be as single-minded as possible.  Mammoth patches can
271 be very difficult to place into the right slot.  They are much easier
272 to deal with when broken down into functional or conceptual chunks.
273 The patches submitted by Kyle Jones and Hrvoje Niksic are stellar
274 examples of how to Do The Right Thing.
275
276 ** Packages directory on the FTP Site
277 =====================================
278
279 The packages directory
280         ftp://ftp.xemacs.org/pub/xemacs/beta/xemacs-21.0/packages/
281
282 is divided into subdirectory by the major type of package.
283
284 drwxr-xr-x   2 beta-f   beta-f      1024 Oct 10 00:43 binary-packages
285 drwxr-xr-x   2 beta-f   beta-f       512 Oct 10 00:44 package-sources
286 drwxr-xr-x   2 beta-f   beta-f       512 Oct 10 00:44 utils
287
288 ** Support Utilities (utils)
289 ============================
290
291 The utils directory contains tools to deal with current Lisp sources that
292 have not had yet gotten XEmacs package integration.  The script `xpackage.sh'
293 is used with Quassia Gnus.  Edit the appropriate variables at the top of
294 the script to reflect the local configuration and run it in the top level
295 directory of a Quassia Gnus source tree to install an update to Quassia Gnus.
296
297 ** Binary package installation (binary-packages)
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-21.0 -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-21.0 -vanilla -batch -l cus-dep \
323         -f Custom-make-dependencies lisp-utils
324
325 To bytecompile both of these files the command is:
326
327 xemacs-21.0 -vanilla -batch -f batch-byte-compile \
328         lisp-utils/auto-autoloads.el lisp-utils/custom-load.el
329
330 ** Building XEmacs and XEmacs packages from scratch
331 ===================================================
332
333 To build everything completely from scratch (not a high priority as a
334 design goal), the following procedure should work.  (I don't recommend
335 building this way).
336
337 *** Phase 1 -- Get a minimal XEmacs binary with mule to build the package
338     lisp with.
339
340 **** Grab a mule-base tarball and install it into a newly created package
341      directory.
342
343 **** Configure XEmacs with mule and a package-path including the
344      directory created above.
345
346 **** Do a `make dist' to build an XEmacs binary.
347
348 *** Phase 2 -- Build and install the package lisp.
349
350 **** Modify XEmacs.rules for local paths and the XEmacs binary created in 
351      Phase 1.
352
353 **** Do a make from the top level package lisp source directory.[1]
354
355 **** Do `make bindist's on all the packages you wish to install and
356      remove the byproduct .tar.gz's.
357
358 *** Phase 3 -- If necessary, redump XEmacs
359     with the packages that require dump-time support and install it.
360
361 **** Reconfigure without Mule if you don't wish a Mule-ish XEmacs, and
362      rebuild XEmacs.
363
364 - or -
365
366 **** rm lib-src/DOC src/xemacs; make
367
368 **** Install or run in-place.
369
370 Note that this is in essence what `make all-elc' has always done.