|
428
|
1 -*- mode:outline -*-
|
|
|
2
|
|
|
3 * Introduction
|
|
|
4 ==============
|
|
|
5
|
|
743
|
6 You are running a potentially unstable version of XEmacs. Please do
|
|
|
7 not report problems with Beta XEmacs to comp.emacs.xemacs. Report
|
|
1250
|
8 them to <xemacs-beta@xemacs.org>, preferably with
|
|
|
9 'M-x report-xemacs-bug RET'.
|
|
428
|
10
|
|
743
|
11 ** Mailing Lists
|
|
|
12 ================
|
|
|
13
|
|
|
14 *** XEmacs Beta Mailing List
|
|
|
15 ----------------------------
|
|
428
|
16
|
|
743
|
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).
|
|
|
22
|
|
1044
|
23 *** XEmacs Patches Mailing List
|
|
|
24 -------------------------------
|
|
428
|
25
|
|
743
|
26 XEmacs Patches records proposed changes to XEmacs, and their
|
|
1044
|
27 disposition. It is open subscription, and all patches that are
|
|
|
28 seriously proposed for inclusion in XEmacs should be posted here. You
|
|
743
|
29 can follow progress of your patch by subscribing to the mailing list
|
|
|
30 or in the archives.
|
|
|
31
|
|
1044
|
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.
|
|
|
35
|
|
|
36 *** XEmacs Design Mailing List
|
|
|
37 ------------------------------
|
|
|
38
|
|
|
39 XEmacs Design is for design discussions such as adding major features
|
|
|
40 or whole modules, or reimplementation of existing functions, to XEmacs.
|
|
|
41
|
|
|
42 *** List Administrivia
|
|
|
43 ----------------------
|
|
428
|
44
|
|
743
|
45 In the descriptions below, the word LIST (all uppercase) is a
|
|
1044
|
46 variable. Substitute "beta", "design", or "patches" as appropriate
|
|
|
47 (to get "xemacs-beta" as the mailbox for the XEmacs Beta mailing list,
|
|
1301
|
48 or <http://www.xemacs.org/Lists/#xemacs-beta> for its URL).
|
|
428
|
49
|
|
743
|
50 The XEmacs mailing lists are managed by the Mailman mailing list
|
|
|
51 package, and the usual Mailman commands work. Do not send mailing
|
|
1301
|
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
|
|
743
|
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
|
|
|
58
|
|
|
59 http://list-archive.xemacs.org/xemacs-LIST
|
|
428
|
60
|
|
1044
|
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.
|
|
|
63
|
|
743
|
64 *** Managing your subscription via the Web
|
|
|
65 ------------------------------------------
|
|
|
66
|
|
|
67 Subscription, unsubscription, and options (such as digests and
|
|
|
68 temporarily suspending delivery) can be accomplished via the web
|
|
1301
|
69 interface at <http://www.xemacs.org/Lists/#xemacs-LIST>.
|
|
428
|
70
|
|
743
|
71 *** Subscribing by e-mail
|
|
|
72 -------------------------
|
|
|
73
|
|
1301
|
74 Send an email message to <xemacs-LIST-request@xemacs.org> with
|
|
743
|
75 `subscribe' (without the quotes) as the BODY of the message.
|
|
428
|
76
|
|
743
|
77 *** Unsubscribing by e-mail
|
|
|
78 ---------------------------
|
|
|
79
|
|
1301
|
80 Send an email message to <xemacs-LIST-request@xemacs.org> with
|
|
743
|
81 `unsubscribe' (without the quotes) as the BODY of the message.
|
|
428
|
82
|
|
|
83 ** Beta Release Schedule
|
|
|
84 ========================
|
|
|
85
|
|
1250
|
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,
|
|
|
94 will go wrong).
|
|
|
95
|
|
|
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.
|
|
|
100
|
|
428
|
101
|
|
|
102 ** Reporting Problems
|
|
|
103 =====================
|
|
|
104
|
|
|
105 The best way to get problems fixed in XEmacs is to submit good problem
|
|
1250
|
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
|
|
|
110 important are:
|
|
428
|
111
|
|
|
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.
|
|
|
119
|
|
|
120 2. Attempt to recreate the problem starting with an invocation of
|
|
1255
|
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.
|
|
428
|
131
|
|
|
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.
|
|
|
139
|
|
|
140 ** Getting the Source
|
|
|
141 =====================
|
|
|
142
|
|
|
143 In addition to the normal tar distribution, XEmacs source is now
|
|
743
|
144 available via CVS. Please see
|
|
|
145
|
|
|
146 http://www.xemacs.org/Develop/cvsaccess.html
|
|
428
|
147
|
|
|
148 * Compiling Beta XEmacs
|
|
|
149 =======================
|
|
|
150
|
|
|
151 ** Building an XEmacs from patches
|
|
|
152 ==================================
|
|
|
153
|
|
1250
|
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
|
|
428
|
160 shell command:
|
|
|
161
|
|
1250
|
162 $ gunzip -c /tmp/xemacs-21.5.9-21.5.10.patch.gz | patch -p1
|
|
428
|
163
|
|
|
164 After patching, check to see that no patches were missed by doing
|
|
|
165 $ find . -name \*.rej -print
|
|
|
166
|
|
|
167 Any rejections should be treated as serious problems to be resolved
|
|
|
168 before building XEmacs.
|
|
|
169
|
|
|
170 After seeing that there were no rejections, issue the commands
|
|
|
171
|
|
|
172 $ ./config.status --recheck
|
|
1250
|
173 $ make beta > ./beta.err 2>&1
|
|
|
174 $ make check > ./xemacs-make-check.err 2>&1
|
|
428
|
175
|
|
1250
|
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'
|
|
428
|
178
|
|
|
179 ** Building XEmacs from a full distribution
|
|
1024
|
180 ===========================================
|
|
428
|
181
|
|
|
182 Locate a convenient place where you have at least 100MB of free space
|
|
|
183 and issue the command
|
|
|
184
|
|
1250
|
185 $ gunzip -c /tmp/xemacs-21.5.10.tar.gz | tar xvf -
|
|
428
|
186
|
|
1250
|
187 (or simply `tar zxvf /tmp/xemacs-21.5.10.tar.gz' if you use GNU tar).
|
|
428
|
188
|
|
|
189 cd to the top level directory and issue an appropriate configure
|
|
|
190 command. One maintainer uses the following at the time of this
|
|
|
191 writing:
|
|
|
192
|
|
|
193 ./configure \
|
|
1250
|
194 --extra-verbose \
|
|
|
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
|
|
428
|
203
|
|
1250
|
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').
|
|
428
|
208
|
|
1250
|
209 uname -a: Linux eicq 2.4.20 #1 Wed Dec 18 02:14:29 EST 2002 i586 unknown
|
|
428
|
210
|
|
1250
|
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'
|
|
|
212
|
|
|
213
|
|
|
214 XEmacs 21.5-b10 "burdock" (+CVS-20030131) configured for `i586-pc-linux'.
|
|
428
|
215
|
|
|
216
|
|
1250
|
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.
|
|
428
|
227
|
|
1250
|
228 Window System:
|
|
|
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.
|
|
|
240
|
|
|
241 TTY:
|
|
428
|
242 Compiling in support for ncurses.
|
|
|
243 Compiling in support for GPM (General Purpose Mouse).
|
|
1250
|
244
|
|
|
245 Images:
|
|
|
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.
|
|
|
252
|
|
|
253 Sound:
|
|
|
254 Compiling in support for sound (native).
|
|
|
255
|
|
|
256 Databases:
|
|
|
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.
|
|
|
261
|
|
|
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.
|
|
|
267
|
|
|
268 Mail:
|
|
|
269 Compiling in support for "dot-locking" mail spool file locking method.
|
|
|
270
|
|
|
271 Other Features:
|
|
|
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.
|
|
428
|
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: ---------------------------------------------------------
|
|
|
282
|
|
|
283
|
|
|
284
|
|
1250
|
285 Then...
|
|
|
286
|
|
|
287 $ make > ./beta.err 2>&1
|
|
|
288 $ make check > ./xemacs-make-check.err 2>&1
|
|
|
289
|
|
|
290 ...and you should have a working XEmacs.
|
|
428
|
291
|
|
|
292 After you have verified that you have a functional editor, fire up
|
|
|
293 your favorite mail program and send a build report to
|
|
1250
|
294 <xemacs-buildreports@xemacs.org>.
|
|
649
|
295
|
|
1250
|
296 Preferably this is best done from XEmacs, following these simple steps:
|
|
649
|
297
|
|
|
298 M-x customize-group RET build-report RET
|
|
|
299 M-x build-report RET
|
|
|
300
|
|
|
301 See also
|
|
1253
|
302 <http://www.xemacs.org/Releases/Public-21.2/tester.html#reporting>
|
|
649
|
303
|
|
|
304 If you create the report manually by other means, here is what the
|
|
|
305 build report should include:
|
|
428
|
306
|
|
|
307 1. Your hardware configuration (OS version, etc.)
|
|
|
308
|
|
|
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.
|
|
|
313
|
|
|
314 3. The options given to configure
|
|
|
315
|
|
|
316 4. The configuration report illustrated above
|
|
|
317
|
|
|
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.
|
|
|
321
|
|
|
322 5. Any other unusual items you feel should be brought to the attention
|
|
|
323 of the developers.
|
|
|
324
|
|
743
|
325
|
|
1024
|
326 * Packages
|
|
|
327 ==========
|
|
|
328
|
|
|
329 [Note: these instructions have been partly updated, but not carefully
|
|
|
330 reviewed in some time. Caveat tester.]
|
|
|
331
|
|
|
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).
|
|
|
336
|
|
|
337 When bootstrapping XEmacs, you may need to manually install some
|
|
|
338 packages (at least xemacs-base and efs). These packages are available
|
|
1250
|
339 by FTP at <ftp://ftp.xemacs.org/pub/xemacs/packages/>.
|
|
1024
|
340
|
|
|
341 ** Binary package installation
|
|
|
342 ==============================
|
|
|
343
|
|
|
344 Prerequisite: XEmacs 21.0-b1.
|
|
|
345
|
|
|
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.
|
|
|
350
|
|
|
351 ** Manual procedures for package management
|
|
|
352 ===========================================
|
|
|
353
|
|
|
354 Prerequisite: XEmacs 21.0
|
|
|
355
|
|
|
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:
|
|
|
361
|
|
1250
|
362 xemacs -vanilla -batch \
|
|
|
363 -eval \("setq autoload-package-name \"lisp-utils\""\) \
|
|
|
364 -f batch-update-directory lisp-utils
|
|
1024
|
365
|
|
|
366 The command to rebuild the custom-load.el file is:
|
|
|
367
|
|
1250
|
368 xemacs -vanilla -batch -f Custom-make-dependencies lisp-utils
|
|
1024
|
369
|
|
1250
|
370 To byte-compile both of these files the command is:
|
|
1024
|
371
|
|
|
372 xemacs -vanilla -batch -f batch-byte-compile \
|
|
|
373 lisp-utils/auto-autoloads.el lisp-utils/custom-load.el
|
|
|
374
|
|
1250
|
375 Of course, being a beta tester, you'd be aware that it is much easier
|
|
|
376 to manage your XEmacs packages with PUI.
|
|
|
377
|
|
1024
|
378 ** Building XEmacs and XEmacs packages from scratch
|
|
|
379 ===================================================
|
|
|
380
|
|
1250
|
381 To build everything completely from scratch isn't hard, just time
|
|
|
382 consuming.
|
|
1024
|
383
|
|
1250
|
384 *** Step 1 - grab the sources (core and packages)
|
|
1024
|
385
|
|
1250
|
386 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs login
|
|
|
387 [password: "cvs" (sans quotes)]
|
|
1024
|
388
|
|
1301
|
389 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs co -d xemacs-21.5 xemacs
|
|
1024
|
390
|
|
1250
|
391 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs co packages
|
|
|
392
|
|
|
393 *** Step 2 - build XEmacs
|
|
1024
|
394
|
|
1250
|
395 $ cd xemacs-21.5
|
|
|
396 $ ./configure [options...]
|
|
|
397 $ make > ./beta.err 2>&1
|
|
|
398 $ make check > ./xemacs-make-check.err 2>&1
|
|
1024
|
399
|
|
1250
|
400 And optionally:
|
|
1024
|
401
|
|
1250
|
402 $ make install > ./xemacs-make-install.err 2>&1
|
|
|
403
|
|
|
404 *** Step 3 - build and install the packages
|
|
1024
|
405
|
|
1250
|
406 $ cd packages
|
|
|
407 $ cp Local.rules.template Local.rules
|
|
1024
|
408
|
|
1250
|
409 Then edit Local.rules to suit your needs/environment
|
|
|
410 see: (Info-goto-node "(xemacs)Local.rules file") for details about
|
|
|
411 this file.
|
|
1024
|
412
|
|
1250
|
413 And then:
|
|
1024
|
414
|
|
1250
|
415 $ make install
|
|
1024
|
416
|
|
|
417 * Improving XEmacs
|
|
743
|
418 =================
|
|
|
419
|
|
428
|
420 ** Creating patches for submission
|
|
|
421 ==================================
|
|
|
422
|
|
1044
|
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
|
|
743
|
426 acknowledged and added to the distribution, or rejected with an
|
|
|
427 explanation. Progress of the patch is tracked on the XEmacs Patches
|
|
1044
|
428 mailing list, which is open subscription. (If a patch is simply
|
|
|
429 intended to facilitate discussion, "I mean something that works like
|
|
1250
|
430 this but this is really rough", a Cc to XEmacs Patches is optional,
|
|
1044
|
431 but doesn't hurt.)
|
|
428
|
432
|
|
|
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>.
|
|
|
436
|
|
|
437 Emailed patches should preferably be sent in MIME format and quoted
|
|
|
438 printable encoding (if necessary).
|
|
|
439
|
|
743
|
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
|
|
|
448 the GNU standards).
|
|
|
449
|
|
|
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
|
|
428
|
453 others make changes to the same source file.
|
|
|
454
|
|
|
455 An example of the `diff' usage:
|
|
|
456
|
|
|
457 $ diff -u OLDFILE NEWFILE
|
|
|
458
|
|
|
459 -or-
|
|
|
460
|
|
|
461 $ diff -c OLDFILE NEWFILE
|
|
|
462
|
|
|
463 Also, it is helpful if you create the patch in the top level of the
|
|
|
464 XEmacs source directory:
|
|
|
465
|
|
|
466 $ cp -p lwlib/xlwmenu.c lwlib/xlwmenu.c.orig
|
|
|
467 hack, hack, hack....
|
|
|
468 $ diff -u lwlib/xlwmenu.c.orig lwlib/xlwmenu.c
|
|
|
469
|
|
|
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
|
|
|
474 within XEmacs.
|
|
|
475
|
|
|
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
|
|
1250
|
480 examples of how to "Do The Right Thing".
|
|
428
|
481
|
|
743
|
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
|
|
1250
|
485 <http://www.gnu.org/prep/standards_toc.html> [Change Logs section]
|
|
743
|
486 for details.
|
|
|
487
|
|
|
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
|
|
1250
|
494 them to the mail. Context-less unified diffs (-U 0) are also
|
|
|
495 acceptable.
|
|
428
|
496
|
|
743
|
497 *** Patch discussion etiquette
|
|
|
498 -------------------------------
|
|
428
|
499
|
|
743
|
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
|
|
1250
|
505 to xemacs-patches. Intermediate cases are up to your judgment;
|
|
743
|
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.
|
|
|
508
|
|
|
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_
|
|
1044
|
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
|
|
|
513 widely read channel.
|
|
428
|
514
|
|
743
|
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."
|
|
428
|
519
|
|
743
|
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.)
|
|
1044
|
525 In this case, also use the keyword SUPERSEDES in the Subject header to
|
|
743
|
526 indicate that the old patch is no longer valid, and that this one
|
|
|
527 replaces it.
|
|
|
528
|
|
|
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.
|
|
|
531
|
|
|
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.
|
|
428
|
534
|
|
743
|
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.
|
|
|
539
|
|
1024
|
540 ** Large contributions
|
|
|
541 ======================
|
|
743
|
542
|
|
1024
|
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.
|
|
428
|
549
|
|
1024
|
550 *** Updates to existing packages
|
|
|
551 --------------------------------
|
|
743
|
552
|
|
1024
|
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.
|
|
428
|
559
|
|
1024
|
560 If the package is important to you, please consider becoming the
|
|
|
561 maintainer. (See "New packages", below.)
|
|
428
|
562
|
|
1024
|
563 *** New packages
|
|
|
564 ----------------
|
|
428
|
565
|
|
1024
|
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.
|
|
428
|
578
|
|
1024
|
579 You don't have to become the maintainer, but it virtually ensures
|
|
|
580 rapid acceptance of the package.
|
|
428
|
581
|
|
1024
|
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
|
|
1301
|
584 Package Release Engineer (Ville Skyttä <scop@xemacs.org> is currently
|
|
1335
|
585 serving with Norbert Koch <viteno@xemacs.org> assisting; Steve
|
|
1301
|
586 Youngs <youngs@xemacs.org> and Stephen Turnbull <stephen@xemacs.org>
|
|
|
587 also can help) are the most likely sources of advice.
|
|
428
|
588
|
|
1024
|
589 *** Syncing with GNU Emacs
|
|
|
590 --------------------------
|
|
428
|
591
|
|
1024
|
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
|
|
|
596 special attention:
|
|
428
|
597
|
|
1024
|
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.
|
|
428
|
600
|
|
1024
|
601 o GNU Emacs nomenclature often differs from that of XEmacs.
|
|
|
602 Sometimes syncing the names is desirable, other times not.
|
|
428
|
603
|
|
1024
|
604 o GNU Emacs functionality often differs from that of XEmacs.
|
|
|
605 Syncing functionality is often controversial.
|
|
428
|
606
|
|
1024
|
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
|
|
428
|
610
|
|
1024
|
611 /* Synched up with: FSF 21.3 by Stephen Turnbull */
|
|
428
|
612
|
|
1024
|
613 in the source file itself, as the last element of the prefatory
|
|
|
614 material (copyright notice and commentary). Obviously the comment
|
|
1301
|
615 marker needs to be changed to leading semicolons for Lisp, but
|
|
1024
|
616 otherwise the format is the same.
|
|
428
|
617
|
|
1024
|
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.
|
|
428
|
621
|
|
1024
|
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
|
|
|
626 comments.
|
|
428
|
627
|
|
1024
|
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.
|
