Mercurial > hg > xemacs-beta

comparison man/beta.texi @ 2537:b7b90f750a78

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2005-01-31 20:08:32 by ben] Documentation updates GETTING.GNU.SOFTWARE, Makefile.in.in: Delete GETTING.GNU.SOFTWARE from SOURCES. PROBLEMS: Delete reference to check_cygwin_setup.sh. Delete stuff that is irrelevant, mislocated or woefully out-of-date. GNU, SERVICE: Delete. * ORDERS, ORDERS.EUROPE, ORDERS.JAPAN: Delete. * CHARSETS, CODINGS: Delete. * DEBUG, LPF, MORE.STUFF, MOTIVATION: Delete. aliases.ksh: Delete. (moved to xemacs-builds/steve) * README.HYPERBOLE, README.OO-BROWSER: Delete. * chr.png, chrm.png: Move to photos/. check_cygwin_setup.sh: Delete. * gnu.xpm, gnu.xbm, sink.xbm: Delete. * ms-kermit, ms-kermit-7bit: Delete. TERMS: Delete. * DISTRIB, FTP, MACHINES, MAILINGLISTS, PACKAGES: Delete and move to FAQ. BETA: Delete and move to man/beta.texi. README: Update. help.el: Removed. xemacs/help.texi: Delete references to DISTRIB. Point to FAQ. xemacs/new.texi: Update sample code for version checking. xemacs/xemacs.texi: Delete references to DISTRIB. Point directly to web site. Update stuff referring to GNU Emacs. Delete references to Win-Emacs. Makefile: Add beta.texi and built files. xemacs-faq.texi: Major overhaul of section 1. Add mailing list info, update downloading info, add info on CVS, etc. xemacs.mak: Also copy BUGS, README, COPYING and Installation.
author ben
date Mon, 31 Jan 2005 20:08:52 +0000
parents
children a9527fcdf77f
comparison
equal deleted inserted replaced
2536:7edc33019aa4 2537:b7b90f750a78
1 \input texinfo @c -*-texinfo-*-
2
3 @c %**start of header
4 @setfilename ../info/beta.info
5 @settitle Info on beta versions of XEmacs
6 @direntry
7 * Beta: (beta). Info on beta versions of XEmacs.
8 @end direntry
9 @c footnotestyle separate
10 @c paragraphindent 2
11 @c %**end of header
12
13 @ifinfo
14 This file describes info relevant to beta versions of XEmacs.
15
16 Copyright @copyright{} 2005 Ben Wing.
17
18 This file is part of XEmacs.
19
20 XEmacs is free software; you can redistribute it and/or modify it
21 under the terms of the GNU General Public License as published by the
22 Free Software Foundation; either version 2, or (at your option) any
23 later version.
24
25 XEmacs is distributed in the hope that it will be useful, but WITHOUT
26 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
27 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
28 for more details.
29
30 You should have received a copy of the GNU General Public License
31 along with XEmacs; see the file COPYING. If not, write to
32 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
33 Boston, MA 02111-1307, USA.
34 @end ifinfo
35
36 @c Combine indices.
37 @syncodeindex fn cp
38 @syncodeindex vr cp
39 @syncodeindex ky cp
40 @syncodeindex pg cp
41 @syncodeindex tp cp
42
43 @setchapternewpage odd
44 @finalout
45
46 @titlepage
47 @title Info on beta versions of XEmacs
48
49 @author XEmacs Development Team
50 @page
51 @vskip 0pt plus 1fill
52
53 @noindent
54 Copyright @copyright{} 2005 Ben Wing. @*
55
56 This file is part of XEmacs.
57
58 XEmacs is free software; you can redistribute it and/or modify it
59 under the terms of the GNU General Public License as published by the
60 Free Software Foundation; either version 2, or (at your option) any
61 later version.
62
63 XEmacs is distributed in the hope that it will be useful, but WITHOUT
64 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
65 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
66 for more details.
67
68 You should have received a copy of the GNU General Public License
69 along with XEmacs; see the file COPYING. If not, write to
70 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
71 Boston, MA 02111-1307, USA.
72 @end titlepage
73 @page
74
75 @ifinfo
76 @node Top, Introduction, (dir), (dir)
77 This Info file describes info relevant to beta versions of XEmacs.
78 @menu
79 * Introduction::
80 * Compiling Beta XEmacs::
81 * Packages::
82 * Improving XEmacs::
83
84 @detailmenu
85 --- The Detailed Node Listing ---
86
87 Introduction
88
89 * Mailing Lists::
90 * Beta Release Schedule::
91 * Reporting Problems::
92 * Getting the Source::
93
94 Mailing Lists
95
96 * XEmacs Beta Mailing List::
97 * XEmacs Patches Mailing List::
98 * XEmacs Design Mailing List::
99 * List Administrivia::
100 * Managing your subscription via the Web::
101 * Subscribing by e-mail::
102 * Unsubscribing by e-mail::
103
104 Compiling Beta XEmacs
105
106 * Building an XEmacs from patches::
107 * Building XEmacs from a full distribution::
108
109 Packages
110
111 * Binary package installation::
112 * Manual procedures for package management::
113 * Building XEmacs and XEmacs packages from scratch::
114
115 Improving XEmacs
116
117 * Creating patches for submission::
118 * Large contributions::
119
120 Creating patches for submission
121
122 * Patch discussion etiquette::
123
124 Large contributions
125
126 * Updates to existing packages::
127 * New packages::
128 * Syncing with GNU Emacs::
129
130 @end detailmenu
131 @end menu
132
133 @end ifinfo
134
135 @node Introduction, Compiling Beta XEmacs, Top, Top
136 @chapter Introduction
137
138 You are running a potentially unstable version of XEmacs. Please do
139 not report problems with Beta XEmacs to comp.emacs.xemacs. Report
140 them to @uref{mailto:xemacs-beta@@xemacs.org}, preferably with
141 @kbd{M-x report-xemacs-bug RET}.
142
143 @menu
144 * Mailing Lists::
145 * Beta Release Schedule::
146 * Reporting Problems::
147 * Getting the Source::
148 @end menu
149
150 @node Mailing Lists, Beta Release Schedule, Introduction, Introduction
151 @section Mailing Lists
152
153 @menu
154 * XEmacs Beta Mailing List::
155 * XEmacs Patches Mailing List::
156 * XEmacs Design Mailing List::
157 * List Administrivia::
158 * Managing your subscription via the Web::
159 * Subscribing by e-mail::
160 * Unsubscribing by e-mail::
161 @end menu
162
163 @node XEmacs Beta Mailing List, XEmacs Patches Mailing List, Mailing Lists, Mailing Lists
164 @subsection XEmacs Beta Mailing List
165
166 If you are not subscribed to the XEmacs beta list you should be.
167 Currently all discussion of development issues, including bug reports
168 and coding discussion, takes place on the XEmacs Beta mailing list.
169 Only patches and administrative actions regarding patches are sent
170 elsewhere (to the XEmacs Patches list).
171
172 @node XEmacs Patches Mailing List, XEmacs Design Mailing List, XEmacs Beta Mailing List, Mailing Lists
173 @subsection XEmacs Patches Mailing List
174
175 XEmacs Patches records proposed changes to XEmacs, and their
176 disposition. It is open subscription, and all patches that are
177 seriously proposed for inclusion in XEmacs should be posted here. You
178 can follow progress of your patch by subscribing to the mailing list
179 or in the archives.
180
181 Besides patches, only actions by members of the XEmacs Review Board
182 should be posted to this list. All discussion should be redirected to
183 XEmacs Beta or XEmacs Design.
184
185 @node XEmacs Design Mailing List, List Administrivia, XEmacs Patches Mailing List, Mailing Lists
186 @subsection XEmacs Design Mailing List
187
188 XEmacs Design is for design discussions such as adding major features
189 or whole modules, or reimplementation of existing functions, to XEmacs.
190
191 @node List Administrivia, Managing your subscription via the Web, XEmacs Design Mailing List, Mailing Lists
192 @subsection List Administrivia
193
194 In the descriptions below, the word LIST (all uppercase) is a
195 variable. Substitute "beta", "design", or "patches" as appropriate
196 (to get "xemacs-beta" as the mailbox for the XEmacs Beta mailing list,
197 or @uref{http://www.xemacs.org/Lists/#xemacs-beta} for its URL).
198
199 The XEmacs mailing lists are managed by the Mailman mailing list package,
200 and the usual Mailman commands work. Do not send mailing list requests to
201 the main address (@uref{mailto:xemacs-LIST@@xemacs.org}), always send them
202 to @uref{mailto:xemacs-LIST-request@@xemacs.org}. If you have problems with
203 the list itself, they should be brought to the attention of the XEmacs
204 Mailing List manager @uref{mailto:list-manager@@xemacs.org} (the same
205 mailbox, "list-manager", for all lists). All public mailing lists have
206 searchable archives. The URL is
207
208 @uref{http://list-archive.xemacs.org/xemacs-LIST}
209
210 Note that the xemacs-LIST-admin address is used internally by the
211 Mailman software; it is NOT a synonym for xemacs-LIST-request.
212
213 @node Managing your subscription via the Web, Subscribing by e-mail, List Administrivia, Mailing Lists
214 @subsection Managing your subscription via the Web
215
216 Subscription, unsubscription, and options (such as digests and
217 temporarily suspending delivery) can be accomplished via the web
218 interface at @uref{http://www.xemacs.org/Lists/#xemacs-LIST}.
219
220 @node Subscribing by e-mail, Unsubscribing by e-mail, Managing your subscription via the Web, Mailing Lists
221 @subsection Subscribing by e-mail
222
223 Send an email message to @uref{mailto:xemacs-LIST-request@@xemacs.org} with
224 @samp{subscribe} (without the quotes) as the BODY of the message.
225
226 @node Unsubscribing by e-mail, , Subscribing by e-mail, Mailing Lists
227 @subsection Unsubscribing by e-mail
228
229 Send an email message to @uref{mailto:xemacs-LIST-request@@xemacs.org} with
230 @samp{unsubscribe} (without the quotes) as the BODY of the message.
231
232 @node Beta Release Schedule, Reporting Problems, Mailing Lists, Introduction
233 @section Beta Release Schedule
234
235 We would like to achieve a weekly or fortnightly release cycle (you
236 know the Open Source model: release early, release often), and in a
237 perfect world that would indeed be the case. There are at least three
238 things that often get in the way of that goal: 1) The Release Manager
239 has a life outside of XEmacs (hard to believe, I know, but true),
240 2) we like to make releases that will build (at least on the Release
241 Manager's box), and 3) Murphy likes to throw a spanner in the works
242 right when you least expect it (Murphy's Law: Whatever can go wrong,
243 will go wrong).
244
245 If you'd like to keep right up to date and ride the bleeding edge, use
246 CVS (see @uref{http://www.xemacs.org/Develop/cvsaccess.html}). If you
247 can't use CVS for some reason and must use FTP, please let us know.
248 it will make it more likely that we release betas more often.
249
250
251 @node Reporting Problems, Getting the Source, Beta Release Schedule, Introduction
252 @section Reporting Problems
253
254 The best way to get problems fixed in XEmacs is to submit good problem
255 reports, @kbd{M-x report-xemacs-bug RET} will help you do this (assuming
256 you have a usable XEmacs). Since this is beta software, problems are
257 certain to exist. Please read through all of part II of the XEmacs
258 FAQ for an overview of problem reporting. Other items which are most
259 important are:
260
261 @enumerate
262 @item
263 Do not submit C stack backtraces without line numbers. Since it
264 is possible to compile optimized with debug information with GCC
265 it is never a good idea to compile XEmacs without the -g flag.
266 XEmacs runs on a variety of platforms, and often it is not
267 possible to recreate problems which afflict a specific platform.
268 The line numbers in the C stack backtrace help isolate where the
269 problem is actually occurring.
270
271 @item
272 Attempt to recreate the problem starting with an invocation of
273 XEmacs with @code{xemacs -no-autoloads}. Quite often, problems are
274 due to package interdependencies, and the like. An actual bug
275 in XEmacs should be reproducible in a default configuration
276 without loading any special packages (or the one or two specific
277 packages that cause the bug to appear). If you have trouble
278 getting anything to work at all with the above invocation, use
279 @code{xemacs -vanilla} instead. If you need to load your user init
280 file or the site file to get the problem to occur, then it has
281 something to do with them, and you should try to isolate the
282 issue in those files.
283
284 @item
285 A picture can be worth a thousand words. When reporting an
286 unusual display, it is generally best to capture the problem in a
287 screen dump and include that with the problem report. The easiest
288 way to get a screen dump is to use the xv program and its grab
289 function. Save the image as a GIF to keep bandwidth requirements
290 down without loss of information. MIME is the preferred method
291 for making the image attachments.
292 @end enumerate
293
294 @node Getting the Source, , Reporting Problems, Introduction
295 @section Getting the Source
296
297 In addition to the normal tar distribution, XEmacs source is now
298 available via CVS. Please see
299
300 @uref{http://www.xemacs.org/Develop/cvsaccess.html}
301
302 @node Compiling Beta XEmacs, Packages, Introduction, Top
303 @chapter Compiling Beta XEmacs
304
305 @menu
306 * Building an XEmacs from patches::
307 * Building XEmacs from a full distribution::
308 @end menu
309
310 @node Building an XEmacs from patches, Building XEmacs from a full distribution, Compiling Beta XEmacs, Compiling Beta XEmacs
311 @section Building an XEmacs from patches
312
313 All beta releases of XEmacs are included with patches from the previous
314 version in an attempt to keep bandwidth requirements down. Patches
315 should be applied with the GNU patch program in something like the
316 following. Let's say you're upgrading XEmacs 21.5-beta9 to XEmacs
317 21.5-beta10 and you have a full unmodified XEmacs 21.5-beta9 source
318 tree to work with. Change to the top level directory and issue the
319 shell command:
320
321 @example
322 $ gunzip -c /tmp/xemacs-21.5.9-21.5.10.patch.gz | patch -p1
323 @end example
324
325 After patching, check to see that no patches were missed by doing
326
327 @example
328 $ find . -name \*.rej -print
329 @end example
330
331 Any rejections should be treated as serious problems to be resolved
332 before building XEmacs.
333
334 After seeing that there were no rejections, issue the commands
335
336 @example
337 $ ./config.status --recheck
338 $ make beta > ./beta.err 2>&1
339 $ make check > ./xemacs-make-check.err 2>&1
340 @end example
341
342 Redirect the output from make to those files because you'll use them
343 later when you send off a build report with @kbd{M-x build-report RET}
344
345 @node Building XEmacs from a full distribution, , Building an XEmacs from patches, Compiling Beta XEmacs
346 @section Building XEmacs from a full distribution
347
348 @enumerate
349 @item
350 Locate a convenient place where you have at least 100MB of free space
351 and issue the command
352
353 @example
354 $ gunzip -c /tmp/xemacs-21.5.10.tar.gz | tar xvf -
355 @end example
356
357 (or simply @code{tar zxvf /tmp/xemacs-21.5.10.tar.gz} if you use GNU tar).
358
359 @item
360 cd to the top level directory and issue an appropriate configure
361 command.
362
363 @item
364 Run @code{configure}. If you are new, just consider running it with no
365 options, to see if you can get a succesful build. When you are more
366 experienced, you should put various flags in. Here is what we suggest:
367
368 @enumerate
369 @item
370 It's a good idea to use
371
372 @example
373 --extra-verbose
374 --debug
375 --memory-usage-stats
376 --error-checking=all
377 @end example
378
379 These turn on extra debugging info and checks. The last one in particular
380 will add a great deal of extra error-checking -- which will slow your XEmacs
381 down somewhat but is likely to catch bugs much sooner and make your bug
382 reports much more useful.
383
384 @item
385 You should also strongly consider
386
387 @example
388 --with-mule
389 --use-pkcc
390 --pdump
391 --with-clash-detection
392 --with-wmcommand
393 --with-xfs
394 @end example
395
396 These turn on optional features, which can always use testing.
397
398 @item
399 If you have gcc, consider using
400
401 @example
402 --compiler=gcc
403 --xemacs-compiler=g++
404 @end example
405
406 This will compile XEmacs using g++, which will turn on a lot of additional
407 error-checking.
408
409 @item
410 If your packages are not installed under /usr/local, you should add a
411 line like
412
413 @example
414 --package-path=~/.xemacs::/xemacs/site-packages:/xemacs/xemacs-packages:/xemacs/mule-packages
415 @end example
416
417 @item
418 If you want to build multiple configurations from the same source
419 tree, make separate build directories for each configuration, run
420 @code{configure} from the top level of these (currently empty)
421 directories and use an option like
422
423 @example
424 --srcdir=/xemacs/source-tree
425 @end example
426
427 (or wherever your source tree is). This will magically create symlinks and
428 populate your build directory.
429
430 @item
431 Use --site-prefixes (or --site-includes and --site-libraries) if you have
432 some packages that XEmacs can compile with that are located in an unusual
433 place. For example:
434
435 @example
436 --site-prefixes=/usr/local/pgsql:/usr/local/BerkeleyDB.4.1
437 @end example
438
439 @item
440 Depending on your build environment, consuder setting or not setting
441 options for menubars, scrollbars, window systems, native sound, etc. If
442 you're not sure, leave them out and let configure do the auto-detection.
443 (If you get bugs compiling GTK, use @code{--with-gtk=no --with-gnome=no}.)
444
445 Part of the configure output is a summary that looks something
446 like the following. (this summary is also available as the file
447 'Installation' in the top directory of your build tree, and via
448 the command @kbd{M-x describe-installation RET}).
449
450 @example
451 uname -a: Linux eicq 2.4.20 #1 Wed Dec 18 02:14:29 EST 2002 i586 unknown
452
453 ./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'
454
455
456 XEmacs 21.5-b10 "burdock" (+CVS-20030131) configured for `i586-pc-linux'.
457
458
459 Compilation / Installation:
460 Source code location: /usr/local/src/xemacs
461 Installation prefix: /usr/local
462 Additional prefixes: /usr/local/pgsql /usr/local/BerkeleyDB.4.1
463 Operating system description file: `s/linux.h'
464 Machine description file: `m/intel386.h'
465 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
466 Relocating allocator for buffers: no
467 GNU version of malloc: yes
468 - Using Doug Lea's new malloc from the GNU C Library.
469
470 Window System:
471 Compiling in support for the X window system:
472 - X Windows headers location: /usr/X11/include
473 - X Windows libraries location: /usr/X11/lib
474 - Handling WM_COMMAND properly.
475 Compiling in support for the Athena widget set:
476 - Athena headers location: X11/neXtaw
477 - Athena library to link: neXtaw
478 Using Lucid menubars.
479 Using Athena scrollbars.
480 Using Athena dialog boxes.
481 Using Athena native widgets.
482
483 TTY:
484 Compiling in support for ncurses.
485 Compiling in support for GPM (General Purpose Mouse).
486
487 Images:
488 Compiling in support for GIF images (builtin).
489 Compiling in support for XPM images.
490 Compiling in support for PNG images.
491 Compiling in support for JPEG images.
492 Compiling in support for TIFF images.
493 Compiling in support for X-Face message headers.
494
495 Sound:
496 Compiling in support for sound (native).
497
498 Databases:
499 Compiling in support for Berkeley database.
500 Compiling in support for PostgreSQL.
501 - Using PostgreSQL header file: libpq-fe.h
502 - Using PostgreSQL V7 bindings.
503
504 Internationalization:
505 Compiling in support for Mule (multi-lingual Emacs).
506 Compiling in support for XIM (X11R5+ I18N input method).
507 - Using raw Xlib to provide XIM support.
508 - Using XFontSet to provide bilingual menubar.
509
510 Mail:
511 Compiling in support for "dot-locking" mail spool file locking method.
512
513 Other Features:
514 Inhibiting IPv6 canonicalization at startup.
515 Compiling in support for dynamic shared object modules.
516 Using the new GC algorithms.
517 Using the new portable dumper.
518 Compiling in support for extra debugging code.
519 WARNING: WARNING: Compiling in support for runtime error checking.
520 WARNING: XEmacs will run noticeably more slowly as a result.
521 WARNING: Error checking is on by default for XEmacs beta releases.
522 WARNING:
523 @end example
524 @end enumerate
525
526
527 @item
528 Then...
529
530 @example
531 $ make > ./beta.err 2>&1
532 $ make check > ./xemacs-make-check.err 2>&1
533 @end example
534
535 ...and you should have a working XEmacs.
536
537 @item
538 After you have verified that you have a functional editor, fire up
539 your favorite mail program and send a build report to
540 @uref{mailto:xemacs-buildreports@@xemacs.org}.
541
542 Preferably this is best done from XEmacs, following these simple steps:
543
544 @enumerate
545 @kbd{M-x customize-group RET build-report RET}
546 @kbd{M-x build-report RET}
547 @end enumerate
548
549 See also
550 @uref{http://www.xemacs.org/Releases/Public-21.2/tester.html#reporting}
551
552 If you create the report manually by other means, here is what the
553 build report should include:
554
555 @enumerate
556 @item
557 Your hardware configuration (OS version, etc.)
558
559 @item
560 Version numbers of software in use (X11 version, system library
561 versions if appropriate, graphics library versions if appropriate).
562 If you're on a system like Linux, include all the version numbers
563 you can because chances are it makes a difference.
564
565 @item
566 The options given to configure
567
568 @item
569 The configuration report illustrated above
570
571 For convenience all of the above items are placed in a file called
572 `Installation' in the top level build directory. They are also
573 available by performing @kbd{M-x describe-installation} inside XEmacs.
574
575 @item
576 Any other unusual items you feel should be brought to the attention
577 of the developers.
578 @end enumerate
579 @end enumerate
580
581 @node Packages, Improving XEmacs, Compiling Beta XEmacs, Top
582 @chapter Packages
583
584 [Note: these instructions have been partly updated, but not carefully
585 reviewed in some time. Caveat tester.]
586
587 Starting with XEmacs 21.1, much of the functionality of XEmacs has
588 been unbundled into "the packages." For more information about the
589 package system, see the Info nodes on Packages (in the XEmacs User
590 Manual) and on Packaging (in the Lisp Reference).
591
592 When bootstrapping XEmacs, you may need to manually install some
593 packages (at least xemacs-base and efs). These packages are available
594 by FTP at @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/}.
595
596 @menu
597 * Binary package installation::
598 * Manual procedures for package management::
599 * Building XEmacs and XEmacs packages from scratch::
600 @end menu
601
602 @node Binary package installation, Manual procedures for package management, Packages, Packages
603 @section Binary package installation
604
605 Prerequisite: XEmacs 21.0-b1.
606
607 Binary packages are complete entities that can be untarred at the top
608 level of an XEmacs package hierarchy and work at runtime. To install files
609 in this directory, run the command @kbd{M-x package-admin-add-binary-package}
610 and fill in appropriate values to the prompts.
611
612 @node Manual procedures for package management, Building XEmacs and XEmacs packages from scratch, Binary package installation, Packages
613 @section Manual procedures for package management
614
615 Prerequisite: XEmacs 21.0
616
617 When adding and deleting files from a lisp directory the
618 auto-autoloads.el (global symbols) and custom-load.el (Customization
619 groups) must be kept in synch. Assuming one is manipulating a
620 directory called `lisp-utils', the command to rebuild the
621 auto-autoloads.el file is:
622
623 @example
624 xemacs -vanilla -batch \
625 -eval \("setq autoload-package-name \"lisp-utils\""\) \
626 -f batch-update-directory lisp-utils
627 @end example
628
629 The command to rebuild the custom-load.el file is:
630
631 @example
632 xemacs -vanilla -batch -f Custom-make-dependencies lisp-utils
633 @end example
634
635 To byte-compile both of these files the command is:
636
637 @example
638 xemacs -vanilla -batch -f batch-byte-compile \
639 lisp-utils/auto-autoloads.el lisp-utils/custom-load.el
640 @end example
641
642 Of course, being a beta tester, you'd be aware that it is much easier
643 to manage your XEmacs packages with PUI.
644
645 @node Building XEmacs and XEmacs packages from scratch, , Manual procedures for package management, Packages
646 @section Building XEmacs and XEmacs packages from scratch
647
648 To build everything completely from scratch isn't hard, just time
649 consuming.
650
651 @subheading Step 1 - grab the sources (core and packages)
652
653 @example
654 $ cvs -d :pserver:cvs@@cvs.xemacs.org:/pack/xemacscvs login
655 [password: "cvs" (sans quotes)]
656
657 $ cvs -d :pserver:cvs@@cvs.xemacs.org:/pack/xemacscvs co -d xemacs-21.5 xemacs
658
659 $ cvs -d :pserver:cvs@@cvs.xemacs.org:/pack/xemacscvs co packages
660 @end example
661
662 @subheading Step 2 - build XEmacs
663
664 @example
665 $ cd xemacs-21.5
666 $ ./configure [options...]
667 $ make > ./beta.err 2>&1
668 $ make check > ./xemacs-make-check.err 2>&1
669 @end example
670
671 And optionally:
672
673 @example
674 $ make install > ./xemacs-make-install.err 2>&1
675 @end example
676
677 @subheading Step 3 - build and install the packages
678
679 @example
680 $ cd packages
681 $ cp Local.rules.template Local.rules
682 @end example
683
684 Then edit Local.rules to suit your needs/environment
685 (@pxref{Local.rules file,,, xemacs, XEmacs User's Manual}) for details
686 about this file.
687
688 And then:
689
690 @example
691 $ make install
692 @end example
693
694 @node Improving XEmacs, , Packages, Top
695 @chapter Improving XEmacs
696
697 @menu
698 * Creating patches for submission::
699 * Large contributions::
700 @end menu
701
702 @node Creating patches for submission, Large contributions, Improving XEmacs, Improving XEmacs
703 @section Creating patches for submission
704
705 All patches to XEmacs that are seriously proposed for inclusion (eg,
706 bug fixes) should be mailed to @uref{mailto:xemacs-patches@@xemacs.org}. Each
707 patch will be reviewed by the patches review board, and will be
708 acknowledged and added to the distribution, or rejected with an
709 explanation. Progress of the patch is tracked on the XEmacs Patches
710 mailing list, which is open subscription. (If a patch is simply
711 intended to facilitate discussion, "I mean something that works like
712 this but this is really rough", a Cc to XEmacs Patches is optional,
713 but doesn't hurt.)
714
715 Patches to XEmacs Lisp packages should be sent to the maintainer of
716 the package. If the maintainer is listed as `XEmacs Development Team'
717 patches should be sent to @uref{mailto:xemacs-patches@@xemacs.org}.
718
719 Emailed patches should preferably be sent in MIME format and quoted
720 printable encoding (if necessary).
721
722 The simplest way to create well-formed patches is to use CVS and
723 Didier Verna's Patcher library (available as patcher.el in the
724 xemacs-devel package). Patcher is new and requires some setup, but
725 most of the core developers are now using it for their own patches.
726 Patcher also can be configured to create patches for several projects,
727 and recognize the project from the directory it is invoked in. This
728 makes it a useful general tool (as long as XEmacs-style patches are
729 accepted at your other projects, which is likely since they conform to
730 the GNU standards).
731
732 When making patches by hand, please use the `-u' option, or if your
733 diff doesn't support it, `-c'. Using ordinary (context-free) diffs
734 are notoriously prone to error, since line numbers tend to change when
735 others make changes to the same source file.
736
737 An example of the `diff' usage:
738
739 @example
740 $ diff -u OLDFILE NEWFILE
741 @end example
742
743 -or-
744
745 @example
746 $ diff -c OLDFILE NEWFILE
747 @end example
748
749 Also, it is helpful if you create the patch in the top level of the
750 XEmacs source directory:
751
752 @example
753 $ cp -p lwlib/xlwmenu.c lwlib/xlwmenu.c.orig
754 hack, hack, hack....
755 $ diff -u lwlib/xlwmenu.c.orig lwlib/xlwmenu.c
756 @end example
757
758 Also note that if you cut & paste from an xterm to an XEmacs mail
759 buffer you will probably lose due to tab expansion. The best thing to
760 do is to use an XEmacs shell buffer to run the diff commands, or ...
761 @kbd{M-x cd} to the appropriate directory, and issue the command
762 @kbd{C-u M-!} from within XEmacs.
763
764 Patches should be as single-minded as possible. Mammoth patches can
765 be very difficult to place into the right slot. They are much easier
766 to deal with when broken down into functional or conceptual chunks.
767 The patches submitted by Kyle Jones and Hrvoje Niksic are stellar
768 examples of how to "Do The Right Thing".
769
770 Each patch should be accompanied by an update to the appropriate
771 ChangeLog file. Guidelines for writing ChangeLog entries is governed
772 by the GNU coding standards. Please see
773 @uref{http://www.gnu.org/prep/standards_toc.html} [Change Logs section]
774 for details.
775
776 Do not submit context diffs (either -c or -u) of ChangeLogs. Because
777 of the "stack" nature of ChangeLogs (new entries are always pushed on
778 the top), context diffs will fail to apply more often than they
779 succeed. Simply cutting and pasting the entry from an Emacs buffer to
780 the mail buffer (beware of tab expansion!) is probably easiest. The
781 Patcher library also will set up your ChangeLogs for you, and copy
782 them to the mail. Context-less unified diffs (-U 0) are also
783 acceptable.
784
785 @menu
786 * Patch discussion etiquette::
787 @end menu
788
789 @node Patch discussion etiquette, , Creating patches for submission, Creating patches for submission
790 @subsection Patch discussion etiquette
791
792 If you intend a patch for _application_ to the sources as is, _always_
793 post it to xemacs-patches, even if there are minor points you would
794 like to have discussed by others. Not doing so will resulting in
795 patches getting "lost". If you expect that the patch will not be
796 acceptable, but are using it to stimulate discussion, then don't post
797 to xemacs-patches. Intermediate cases are up to your judgment;
798 unless you're sure you'll follow up with a "real" patch, better to err
799 on the side of posting to xemacs-patches.
800
801 Discussion of the _content_ of the patch (ie responses to reviewer
802 comments beyond "that's right, ok, I'll do it your way") should _always_
803 be posted to xemacs-beta or to xemacs-design. If you're not sure
804 which is more appropriate, send it to xemacs-beta. That is the most
805 widely read channel.
806
807 If discussion results in a bright idea and you come up with a new
808 patch, normally you should post it to both mailing lists. The people
809 discussing on XEmacs Beta will want to know the outcome of the thread,
810 and you need to submit to XEmacs Patches as the "list of record."
811
812 If the old patch has been applied to CVS, then just submit the new one
813 as usual. If it has not been applied, then it is best to submit a new
814 patch against CVS. If possible do this as a reply to the original
815 patch post, or something following it in the thread. (The point is to
816 get the original patch post's Message-ID in your References header.)
817 In this case, also use the keyword SUPERSEDES in the Subject header to
818 indicate that the old patch is no longer valid, and that this one
819 replaces it.
820
821 These rules will result in a fair number of cross posts, but we don't
822 yet have a better way to handle that.
823
824 Note: Developers should never post to xemacs-patches unless there is a
825 patch in the post. We plan to enforce this with an automatic filter.
826
827 The exceptions are administrative. If you have commit authorization,
828 then post a short COMMIT notice to xemacs-patches when you commit to
829 CVS. Members of the Review Board will also post short notices of
830 administrative action (APPROVE, VETO, QUERY, etc) to xemacs-patches.
831
832 @node Large contributions, , Creating patches for submission, Improving XEmacs
833 @section Large contributions
834
835 Perhaps you have a whole new mode, or a major synchronization with
836 upstream for a neglected package, or a synchronization with GNU Emacs
837 you would like to contribute. We welcome such contributions, but they
838 are likely to be relatively controversial, generate more comments and
839 requests for revision, and take longer to integrate. Please be
840 patient with the process.
841
842 @menu
843 * Updates to existing packages::
844 * New packages::
845 * Syncing with GNU Emacs::
846 @end menu
847
848 @node Updates to existing packages, New packages, Large contributions, Large contributions
849 @subsection Updates to existing packages
850
851 If a package has gotten a bit out of date, or even started to bitrot,
852 we welcome patches to synchronize it with upstream/GNU Emacs versions.
853 Most packages end up varying somewhat from their GNU origins. See
854 "Syncing with GNU Emacs" for hints. Note that if you do a reasonably
855 large amount of syncing with GNU Emacs, you should log this in the
856 file itself as well as in the ChangeLog.
857
858 If the package is important to you, please consider becoming the
859 maintainer. (See "New packages", below.)
860
861 @node New packages, Syncing with GNU Emacs, Updates to existing packages, Large contributions
862 @subsection New packages
863
864 If you have a new mode or other large addition that does not require
865 changes to the core, please consider submitting it as a package, and
866 becoming the maintainer. You get direct commit privileges to the
867 repository for your package, "approval" privileges for your own
868 patches as well as third party patches to your package, and some
869 degree of veto power over patches you don't like. In return, you are
870 expected to maintain friendly liaison with the upstream developer (if
871 you aren't the upstream developer), keep watch on the XEmacs Patches
872 list for relevant patches, and be available by email to other
873 developers for discussion of changes that impact your package. It's
874 also a pretty standard route to the "core" development group, where we
875 have plenty of extra work waiting for volunteers.
876
877 You don't have to become the maintainer, but it virtually ensures
878 rapid acceptance of the package.
879
880 For help in creating new packages, see the (rather sparse) discussions
881 in the XEmacs User's Guide and the Lisp Reference Manual. The XEmacs
882 Package Release Engineer (Ville Skyttä @uref{mailto:scop@@xemacs.org}
883 is currently serving with Norbert Koch @uref{mailto:viteno@@xemacs.org}
884 assisting; Steve Youngs @uref{mailto:youngs@@xemacs.org} and Stephen
885 Turnbull @uref{mailto:stephen@@xemacs.org} also can help) are the most
886 likely sources of advice.
887
888 @node Syncing with GNU Emacs, , New packages, Large contributions
889 @subsection Syncing with GNU Emacs
890
891 Syncing with GNU Emacs is an important activity. Although each
892 version has its advantages and areas of concentration, it is very
893 desirable that common functionality share specifications and APIs.
894 When porting GNU code to XEmacs, the following points should be given
895 special attention:
896
897 @itemize @bullet
898 @item
899 Recent GNU Emacsen cannot be built without Mule, but XEmacs can.
900 Make sure your changes do not assume the presence of Mule.
901
902 @item
903 GNU Emacs nomenclature often differs from that of XEmacs.
904 Sometimes syncing the names is desirable, other times not.
905
906 @item
907 GNU Emacs functionality often differs from that of XEmacs.
908 Syncing functionality is often controversial.
909 @end itemize
910
911 It is important that you let other developers know that
912 synchronization has taken place, to what degree, and when. For this
913 purpose, we use comments of the form
914
915 @example
916 /* Synched up with: FSF 21.3 by Stephen Turnbull */
917 @end example
918
919 in the source file itself, as the last element of the prefatory
920 material (copyright notice and commentary). Obviously the comment
921 marker needs to be changed to leading semicolons for Lisp, but
922 otherwise the format is the same.
923
924 Of course you should note syncing as the purpose in the ChangeLog,
925 too. But entries get buried deep in the ChangeLog file, and may even
926 get moved to a separate ChangeLog.OLD file for rarely synched files.
927
928 Rather than dates we use the version of GNU Emacs to sync to. If the
929 synchronization is partial, add a new comment describing what has
930 actually been synched, leaving the description of the last full sync
931 in place. At each full sync, remove all previous synchronization
932 comments.
933
934 This applies to Lisp that we have broken out into packages, but
935 remains in the GNU Emacs core, as well to core Lisp in XEmacs.
936
937 @c Print the tables of contents
938 @contents
939 @c That's all
940
941 @node Index, , Defining Variables, Top
942 @unnumbered Index
943
944 @printindex cp
945
946 @bye