1 This is ../info/xemacs.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Running
35 Libraries of Lisp Code for Emacs
36 ================================
38 Lisp code for Emacs editing commands is stored in files whose names
39 conventionally end in `.el'. This ending tells Emacs to edit them in
40 Emacs-Lisp mode (*note Lisp Modes::).
44 * Loading:: Loading libraries of Lisp code into Emacs for use.
45 * Compiling Libraries:: Compiling a library makes it load and run faster.
46 * Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it.
49 File: xemacs.info, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries
55 Load the file FILE of Lisp code.
57 `M-x load-library LIBRARY'
58 Load the library named LIBRARY.
60 `M-x locate-library LIBRARY &optional NOSUFFIX'
61 Show the full path name of Emacs library LIBRARY.
63 To execute a file of Emacs Lisp, use `M-x load-file'. This command
64 reads the file name you provide in the minibuffer, then executes the
65 contents of that file as Lisp code. It is not necessary to visit the
66 file first; in fact, this command reads the file as found on disk, not
67 the text in an Emacs buffer.
69 Once a file of Lisp code is installed in the Emacs Lisp library
70 directories, users can load it using `M-x load-library'. Programs can
71 load it by calling `load-library', or with `load', a more primitive
72 function that is similar but accepts some additional arguments.
74 `M-x load-library' differs from `M-x load-file' in that it searches
75 a sequence of directories and tries three file names in each directory.
76 The three names are: first, the specified name with `.elc' appended;
77 second, the name with `.el' appended; third, the specified name alone.
78 A `.elc' file would be the result of compiling the Lisp file into byte
79 code; if possible, it is loaded in preference to the Lisp file itself
80 because the compiled file loads and runs faster.
82 Because the argument to `load-library' is usually not in itself a
83 valid file name, file name completion is not available. In fact, when
84 using this command, you usually do not know exactly what file name will
87 The sequence of directories searched by `M-x load-library' is
88 specified by the variable `load-path', a list of strings that are
89 directory names. The elements of this list may not begin with "`~'",
90 so you must call `expand-file-name' on them before adding them to the
91 list. The default value of the list contains the directory where the
92 Lisp code for Emacs itself is stored. If you have libraries of your
93 own, put them in a single directory and add that directory to
94 `load-path'. `nil' in this list stands for the current default
95 directory, but it is probably not a good idea to put `nil' in the list.
96 If you start wishing that `nil' were in the list, you should probably
97 use `M-x load-file' for this case.
99 The variable is initialized by the EMACSLOADPATH environment
100 variable. If no value is specified, the variable takes the default value
101 specified in the file `paths.h' when Emacs was built. If a path isn't
102 specified in `paths.h', a default value is obtained from the file
103 system, near the directory in which the Emacs executable resides.
105 Like `M-x load-library', `M-x locate-library' searches the
106 directories in `load-path' to find the file that `M-x load-library'
107 would load. If the optional second argument NOSUFFIX is non-`nil', the
108 suffixes `.elc' or `.el' are not added to the specified name LIBRARY
109 (like calling `load' instead of `load-library').
111 You often do not have to give any command to load a library, because
112 the commands defined in the library are set up to "autoload" that
113 library. Running any of those commands causes `load' to be called to
114 load the library; this replaces the autoload definitions with the real
115 ones from the library.
117 If autoloading a file does not finish, either because of an error or
118 because of a `C-g' quit, all function definitions made by the file are
119 undone automatically. So are any calls to `provide'. As a
120 consequence, the entire file is loaded a second time if you use one of
121 the autoloadable commands again. This prevents problems when the
122 command is no longer autoloading but is working incorrectly because the
123 file was only partially loaded. Function definitions are undone only
124 for autoloading; explicit calls to `load' do not undo anything if
125 loading is not completed.
127 The variable `after-load-alist' takes an alist of expressions to be
128 evaluated when particular files are loaded. Each element has the form
129 `(FILENAME forms...)'. When `load' is run and the filename argument is
130 FILENAME, the forms in the corresponding element are executed at the
133 FILENAME must match exactly. Normally FILENAME is the name of a
134 library, with no directory specified, since that is how load is
135 normally called. An error in `forms' does not undo the load, but it
136 does prevent execution of the rest of the `forms'.
139 File: xemacs.info, Node: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries
144 Emacs Lisp code can be compiled into byte-code which loads faster,
145 takes up less space when loaded, and executes faster.
147 `M-x batch-byte-compile'
148 Run byte-compile-file on the files remaining on the command line.
150 `M-x byte-compile-buffer &optional BUFFER'
151 Byte-compile and evaluate contents of BUFFER (default is current
154 `M-x byte-compile-file'
155 Compile a file of Lisp code named FILENAME into a file of byte
158 `M-x byte-compile-and-load-file FILENAME'
159 Compile a file of Lisp code named FILENAME into a file of byte
162 `M-x byte-recompile-directory DIRECTORY'
163 Recompile every `.el' file in DIRECTORY that needs recompilation.
166 Print disassembled code for OBJECT on (optional) STREAM.
168 `M-x make-obsolete FUNCTION NEW'
169 Make the byte-compiler warn that FUNCTION is obsolete and NEW
170 should be used instead.
172 `byte-compile-file' creates a byte-code compiled file from an
173 Emacs-Lisp source file. The default argument for this function is the
174 file visited in the current buffer. The function reads the specified
175 file, compiles it into byte code, and writes an output file whose name
176 is made by appending `c' to the input file name. Thus, the file
177 `rmail.el' would be compiled into `rmail.elc'. To compile a file of
178 Lisp code named FILENAME into a file of byte code and then load it, use
179 `byte-compile-and-load-file'. To compile and evaluate Lisp code in a
180 given buffer, use `byte-compile-buffer'.
182 To recompile all changed Lisp files in a directory, use `M-x
183 byte-recompile-directory'. Specify just the directory name as an
184 argument. Each `.el' file that has been byte-compiled before is
185 byte-compiled again if it has changed since the previous compilation.
186 A numeric argument to this command tells it to offer to compile each
187 `.el' file that has not been compiled yet. You must answer `y' or `n'
190 You can use the function `batch-byte-compile' to invoke Emacs
191 non-interactively from the shell to do byte compilation. When you use
192 this function, the files to be compiled are specified with command-line
193 arguments. Use a shell command of the form:
195 emacs -batch -f batch-byte-compile FILES...
197 Directory names may also be given as arguments; in that case,
198 `byte-recompile-directory' is invoked on each such directory.
199 `batch-byte-compile' uses all remaining command-line arguments as file
200 or directory names, then kills the Emacs process.
202 `M-x disassemble' explains the result of byte compilation. Its
203 argument is a function name. It displays the byte-compiled code in a
204 help window in symbolic form, one instruction per line. If the
205 instruction refers to a variable or constant, that is shown, too.
208 File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries
210 Converting Mocklisp to Lisp
211 ---------------------------
213 XEmacs can run Mocklisp files by converting them to Emacs Lisp first.
214 To convert a Mocklisp file, visit it and then type `M-x
215 convert-mocklisp-buffer'. Then save the resulting buffer of Lisp file
216 in a file whose name ends in `.el' and use the new file as a Lisp
219 You cannot currently byte-compile converted Mocklisp code. The
220 reason is that converted Mocklisp code uses some special Lisp features
221 to deal with Mocklisp's incompatible ideas of how arguments are
222 evaluated and which values signify "true" or "false".
225 File: xemacs.info, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running
227 Evaluating Emacs-Lisp Expressions
228 =================================
230 Lisp programs intended to be run in Emacs should be edited in
231 Emacs-Lisp mode; this will happen automatically for file names ending in
232 `.el'. By contrast, Lisp mode itself should be used for editing Lisp
233 programs intended for other Lisp systems. Emacs-Lisp mode can be
234 selected with the command `M-x emacs-lisp-mode'.
236 For testing of Lisp programs to run in Emacs, it is useful to be able
237 to evaluate part of the program as it is found in the Emacs buffer. For
238 example, if you change the text of a Lisp function definition and then
239 evaluate the definition, Emacs installs the change for future calls to
240 the function. Evaluation of Lisp expressions is also useful in any
241 kind of editing task for invoking non-interactive functions (functions
242 that are not commands).
245 Read a Lisp expression in the minibuffer, evaluate it, and print
246 the value in the minibuffer (`eval-expression').
249 Evaluate the Lisp expression before point, and print the value in
250 the minibuffer (`eval-last-sexp').
253 Evaluate the defun containing point or after point, and print the
254 value in the minibuffer (`eval-defun').
257 Evaluate all the Lisp expressions in the region.
259 `M-x eval-current-buffer'
260 Evaluate all the Lisp expressions in the buffer.
262 `M-<ESC>' (`eval-expression') is the most basic command for
263 evaluating a Lisp expression interactively. It reads the expression
264 using the minibuffer, so you can execute any expression on a buffer
265 regardless of what the buffer contains. When evaluation is complete,
266 the current buffer is once again the buffer that was current when
269 `M-<ESC>' can easily confuse users, especially on keyboards with
270 autorepeat, where it can result from holding down the <ESC> key for too
271 long. Therefore, `eval-expression' is normally a disabled command.
272 Attempting to use this command asks for confirmation and gives you the
273 option of enabling it; once you enable the command, you are no longer
274 required to confirm. *Note Disabling::.
276 In Emacs-Lisp mode, the key `C-M-x' is bound to the function
277 `eval-defun', which parses the defun containing point or following point
278 as a Lisp expression and evaluates it. The value is printed in the echo
279 area. This command is convenient for installing in the Lisp environment
280 changes that you have just made in the text of a function definition.
282 The command `C-x C-e' (`eval-last-sexp') performs a similar job but
283 is available in all major modes, not just Emacs-Lisp mode. It finds
284 the sexp before point, reads it as a Lisp expression, evaluates it, and
285 prints the value in the echo area. It is sometimes useful to type in an
286 expression and then, with point still after it, type `C-x C-e'.
288 If `C-M-x' or `C-x C-e' are given a numeric argument, they print the
289 value by inserting it into the current buffer at point, rather than in
290 the echo area. The argument value does not matter.
292 The most general command for evaluating Lisp expressions from a
293 buffer is `eval-region'. `M-x eval-region' parses the text of the
294 region as one or more Lisp expressions, evaluating them one by one.
295 `M-x eval-current-buffer' is similar, but it evaluates the entire
296 buffer. This is a reasonable way to install the contents of a file of
297 Lisp code that you are just ready to test. After finding and fixing a
298 bug, use `C-M-x' on each function that you change, to keep the Lisp
299 world in step with the source file.
302 File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running
304 The Emacs-Lisp Debugger
305 =======================
307 XEmacs contains a debugger for Lisp programs executing inside it.
308 This debugger is normally not used; many commands frequently get Lisp
309 errors when invoked in inappropriate contexts (such as `C-f' at the end
310 of the buffer) and it would be unpleasant to enter a special debugging
311 mode in this case. When you want to make Lisp errors invoke the
312 debugger, you must set the variable `debug-on-error' to non-`nil'.
313 Quitting with `C-g' is not considered an error, and `debug-on-error'
314 has no effect on the handling of `C-g'. However, if you set
315 `debug-on-quit' to be non-`nil', `C-g' will invoke the debugger. This
316 can be useful for debugging an infinite loop; type `C-g' once the loop
317 has had time to reach its steady state. `debug-on-quit' has no effect
320 You can make Emacs enter the debugger when a specified function is
321 called or at a particular place in Lisp code. Use `M-x debug-on-entry'
322 with argument FUN-NAME to have Emacs enter the debugger as soon as
323 FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the
324 function stop entering the debugger when called. (Redefining the
325 function also does this.) To enter the debugger from some other place
326 in Lisp code, you must insert the expression `(debug)' there and
327 install the changed code with `C-M-x'. *Note Lisp Eval::.
329 When the debugger is entered, it displays the previously selected
330 buffer in one window and a buffer named `*Backtrace*' in another
331 window. The backtrace buffer contains one line for each level of Lisp
332 function execution currently going on. At the beginning of the buffer
333 is a message describing the reason that the debugger was invoked, for
334 example, an error message if it was invoked due to an error.
336 The backtrace buffer is read-only and is in Backtrace mode, a special
337 major mode in which letters are defined as debugger commands. The
338 usual Emacs editing commands are available; you can switch windows to
339 examine the buffer that was being edited at the time of the error, and
340 you can switch buffers, visit files, and perform any other editing
341 operations. However, the debugger is a recursive editing level (*note
342 Recursive Edit::); it is a good idea to return to the backtrace buffer
343 and explicitly exit the debugger when you don't want to use it any
344 more. Exiting the debugger kills the backtrace buffer.
346 The contents of the backtrace buffer show you the functions that are
347 executing and the arguments that were given to them. It also allows you
348 to specify a stack frame by moving point to the line describing that
349 frame. The frame whose line point is on is considered the "current
350 frame". Some of the debugger commands operate on the current frame.
351 Debugger commands are mainly used for stepping through code one
352 expression at a time. Here is a list of them:
355 Exit the debugger and continue execution. In most cases,
356 execution of the program continues as if the debugger had never
357 been entered (aside from the effect of any variables or data
358 structures you may have changed while inside the debugger). This
359 includes entry to the debugger due to function entry or exit,
360 explicit invocation, and quitting or certain errors. Most errors
361 cannot be continued; trying to continue an error usually causes
362 the same error to occur again.
365 Continue execution, but enter the debugger the next time a Lisp
366 function is called. This allows you to step through the
367 subexpressions of an expression, and see what the subexpressions
368 do and what values they compute.
370 When you enter the debugger this way, Emacs flags the stack frame
371 for the function call from which you entered. The same function
372 is then called when you exit the frame. To cancel this flag, use
376 Set up to enter the debugger when the current frame is exited.
377 Frames that invoke the debugger on exit are flagged with stars.
380 Don't enter the debugger when the current frame is exited. This
381 cancels a `b' command on a frame.
384 Read a Lisp expression in the minibuffer, evaluate it, and print
385 the value in the echo area. This is equivalent to the command
386 `M-<ESC>', except that `e' is not normally disabled like `M-<ESC>'.
389 Terminate the program being debugged; return to top-level Emacs
392 If the debugger was entered due to a `C-g' but you really want to
393 quit, not to debug, use the `q' command.
396 Return a value from the debugger. The value is computed by
397 reading an expression with the minibuffer and evaluating it.
399 The value returned by the debugger makes a difference when the
400 debugger was invoked due to exit from a Lisp call frame (as
401 requested with `b'); then the value specified in the `r' command
402 is used as the value of that frame.
404 The debugger's return value also matters with many errors. For
405 example, `wrong-type-argument' errors will use the debugger's
406 return value instead of the invalid argument; `no-catch' errors
407 will use the debugger value as a throw tag instead of the tag that
408 was not found. If an error was signaled by calling the Lisp
409 function `signal', the debugger's return value is returned as the
413 File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running
415 Lisp Interaction Buffers
416 ========================
418 The buffer `*scratch*', which is selected when Emacs starts up, is
419 provided for evaluating Lisp expressions interactively inside Emacs.
420 Both the expressions you evaluate and their output goes in the buffer.
422 The `*scratch*' buffer's major mode is Lisp Interaction mode, which
423 is the same as Emacs-Lisp mode except for one command, <LFD>. In
424 Emacs-Lisp mode, <LFD> is an indentation command. In Lisp Interaction
425 mode, <LFD> is bound to `eval-print-last-sexp'. This function reads
426 the Lisp expression before point, evaluates it, and inserts the value
427 in printed representation before point.
429 The way to use the `*scratch*' buffer is to insert Lisp expressions
430 at the end, ending each one with <LFD> so that it will be evaluated.
431 The result is a complete typescript of the expressions you have
432 evaluated and their values.
434 The rationale for this feature is that Emacs must have a buffer when
435 it starts up, but that buffer is not useful for editing files since a
436 new buffer is made for every file that you visit. The Lisp interpreter
437 typescript is the most useful thing I can think of for the initial
438 buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp
442 File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running
444 Running an External Lisp
445 ========================
447 Emacs has facilities for running programs in other Lisp systems.
448 You can run a Lisp process as an inferior of Emacs, and pass
449 expressions to it to be evaluated. You can also pass changed function
450 definitions directly from the Emacs buffers in which you edit the Lisp
451 programs to the inferior Lisp process.
453 To run an inferior Lisp process, type `M-x run-lisp'. This runs the
454 program named `lisp', the same program you would run by typing `lisp'
455 as a shell command, with both input and output going through an Emacs
456 buffer named `*lisp*'. In other words, any "terminal output" from Lisp
457 will go into the buffer, advancing point, and any "terminal input" for
458 Lisp comes from text in the buffer. To give input to Lisp, go to the
459 end of the buffer and type the input, terminated by <RET>. The
460 `*lisp*' buffer is in Inferior Lisp mode, which has all the special
461 characteristics of Lisp mode and Shell mode (*note Shell Mode::).
463 Use Lisp mode to run the source files of programs in external Lisps.
464 You can select this mode with `M-x lisp-mode'. It is used automatically
465 for files whose names end in `.l' or `.lisp', as most Lisp systems
468 When you edit a function in a Lisp program you are running, the
469 easiest way to send the changed definition to the inferior Lisp process
470 is the key `C-M-x'. In Lisp mode, this key runs the function
471 `lisp-send-defun', which finds the defun around or following point and
472 sends it as input to the Lisp process. (Emacs can send input to any
473 inferior process regardless of what buffer is current.)
475 Contrast the meanings of `C-M-x' in Lisp mode (for editing programs
476 to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
477 programs to be run in Emacs): in both modes it has the effect of
478 installing the function definition that point is in, but the way of
479 doing so is different according to where the relevant Lisp environment
480 is found. *Note Lisp Modes::.
483 File: xemacs.info, Node: Packages, Next: Basic, Prev: Startup Paths, Up: Top
488 The XEmacs 21 distribution comes only with a very basic set of
489 built-in modes and packages. Most of the packages that were part of
490 the distribution of earlier versions of XEmacs are now available
491 separately. The installer as well as the user can choose which
492 packages to install; the actual installation process is easy. This
493 gives an installer the ability to tailor an XEmacs installation for
494 local needs with safe removal of unnecessary code.
498 * Package Terminology:: Understanding different kinds of packages.
499 * Installing Packages:: How to install packages.
500 * Building Packages:: Building packages from CVS sources.
501 * Local.rules File:: This is an important file don't forget to create/edit it.
502 * Creating Packages:: The basics.
503 * Available Packages:: A brief directory of packaged LISP.
506 File: xemacs.info, Node: Package Terminology, Next: Installing Packages, Up: Packages
514 There are two main flavors of packages.
516 * Regular Packages A regular package is one in which multiple files
517 are involved and one may not in general safely remove any of them.
519 * Single-File Packages A single-file package is an aggregate
520 collection of thematically related but otherwise independent lisp
521 files. These files are bundled together for download convenience
522 and individual files may be deleted at will without any loss of
523 functionality. However, we would recommend that you follow this
524 rule of thumb: "When in doubt, don't delete".
526 Package Distributions
527 ---------------------
529 XEmacs Lisp packages are distributed in two ways, depending on the
530 intended use. Binary Packages are for installers and end-users that can
531 be installed directly into an XEmacs package directory. Source Packages
532 are for developers and include all files necessary for rebuilding
533 bytecompiled lisp and creating tarballs for distribution.
538 Binary packages may be installed directly into an XEmacs package
544 Source packages contain all of the Package author's (where
545 appropriate in regular packages) source code plus all of the files
546 necessary to build distribution tarballs (Unix Tar format files,
547 gzipped for space savings).
549 Currently, source packages are only available via CVS. See
550 <http://cvs.xemacs.org/> for details.
553 File: xemacs.info, Node: Installing Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages
561 When you first download XEmacs 21, you will usually first grab the
562 "core distribution", a file called `xemacs-21.x.x.tar.gz'. (Replace the
563 21.x.x by the current version number.) The core distribution contains
564 the sources of XEmacs and a minimal set of Emacs Lisp files, which are
565 in the subdirectory named `lisp'. This subdirectory used to contain
566 all Emacs Lisp files distributed with XEmacs. Now, to conserve disk
567 space, most non-essential packages were made optional.
569 Choosing the Packages You Need
570 ------------------------------
572 The *Note Available Packages:: can currently be found in the same
573 ftp directory where you grabbed the core distribution from, and are
574 located in the subdirectory `packages'. Package file names follow the
575 naming convention `<package-name>-<version>-pkg.tar.gz'.
577 If you have EFS *Note (EFS)::, packages can be installed over the
578 network. Alternatively, if you have copies of the packages locally,
579 you can install packages from a local disk or CDROM.
581 The file `etc/PACKAGES' in the core distribution contains a list of
582 the *Note Available Packages:: at the time of the XEmacs release.
583 Packages are also listed on the `Options' menu under:
585 Options -> Customize -> Emacs -> Packages
587 However, don't select any of these menu picks unless you actually
588 want to install the given package (and have properly configured your
591 You can also get a list of available packages, and whether or not
592 they are installed, using the visual package browser and installer.
593 You can access it via the menus:
595 Options -> Manage Packages -> List & Install
597 Or, you can get to it via the keyboard:
599 M-x pui-list-packages
601 Hint to system administrators of multi-user systems: it might be a
602 good idea to install all packages and not interfere with the wishes of
605 If you can't find which package provides the feature you require, try
606 using the `package-get-package-provider' function. Eg., if you know
607 that you need `thingatpt', type:
609 M-x package-get-package-provider RET thingatpt
611 which will return something like (fsf-compat "1.08"). You can the use
612 one of the methods above for installing the package you want.
614 XEmacs and Installing Packages
615 ------------------------------
617 There are three main ways to install packages:
621 * Sumo:: All at once, using the 'Sumo Tarball'.
622 * Manually:: Using individual package tarballs.
623 * Automatically:: Using the package tools from XEmacs.
624 * Which Packages:: Which packages to install.
625 * Removing Packages:: Removing packages.
627 But regardless of the method you use to install packages, they can
628 only be used by XEmacs after a restart.
631 File: xemacs.info, Node: Sumo, Next: Manually, Up: Installing Packages
633 Installing the Sumo Packages:
634 =============================
636 Those with little time, cheap connections and plenty of disk space
637 can install all the packages at once using the sumo tarballs. Download
638 the file: `xemacs-sumo.tar.gz'
640 For an XEmacs compiled with Mule you also need:
641 `xemacs-mule-sumo.tar.gz'
643 N.B. They are called 'Sumo Tarballs' for good reason. They are
644 currently about 19MB and 4.5MB (gzipped) respectively.
648 `cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET'
650 Or, if you have GNU tar:
652 `cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET'
654 As the Sumo tarballs are not regenerated as often as the individual
655 packages, it is recommended that you use the automatic package tools
656 afterwards to pick up any recent updates.
659 File: xemacs.info, Node: Manually, Next: Automatically, Prev: Sumo, Up: Installing Packages
661 Manual Package Installation:
662 ============================
664 Fetch the packages from the FTP site, CD-ROM whatever. The filenames
665 have the form `name-<version>-pkg.tar.gz' and are gzipped tar files. For
666 a fresh install it is sufficient to untar the file at the top of the
669 Note: If you are upgrading packages already installed, it's best to
670 remove the old package first *Note Removing Packages::.
672 For example if we are installing the `xemacs-base' package (version
675 mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet
676 cd $prefix/lib/xemacs/xemacs-packages RET
677 gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
679 Or if you have GNU tar, the last step can be:
681 tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
683 For MULE related packages, it is best to untar into the mule-packages
684 hierarchy, i.e. for the `mule-base' package, version 1.37:
686 mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet
687 cd $prefix/lib/xemacs/mule-packages RET
688 gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
690 Or if you have GNU tar, the last step can be:
692 tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
695 File: xemacs.info, Node: Automatically, Next: Which Packages, Prev: Manually, Up: Installing Packages
697 Automatic Package Installation:
698 ===============================
700 XEmacs comes with some tools to make the periodic updating and
701 installing easier. It will notice if new packages or versions are
702 available and will fetch them from the FTP site.
704 Unfortunately this requires that a few packages are already in place.
705 You will have to install them by hand as above or use a SUMO tarball.
706 This requirement will hopefully go away in the future. The packages you
709 efs - To fetch the files from the FTP site or mirrors.
710 xemacs-base - Needed by efs.
714 mule-base - Needed if you want to use XEmacs with MULE.
716 After installing these by hand, fire up XEmacs and follow these
719 Note: The menus in XEmacs 21.2.x and up have changed slightly, so
720 where I mention "Options -> Manage Packages", substitute "Tools ->
723 1. Choose a download site. via menu: Options -> Manages Packages ->
724 Add Download Site via keyb: `M-x customize-variable RET
725 package-get-remote RET' (put in the details of remote host and
728 If the package tarballs _AND_ the package-index file are in a
729 local directory, you can: `M-x pui-add-install-directory RET'
731 2. Obtain a list of packages and display the list in a buffer named
732 `*Packages*'. menu: Options -> Manage Packages -> List & Install
733 keyb: `M-x pui-list-packages RET'
735 XEmacs will now connect to the remote site and download the latest
736 package-index file. If you see an error about the package-index
737 entries not being PGP signed, you can safely ignore this because
738 PGP has not been integrated into the XEmacs package tools yet.
740 The visual package browser will then display a list of all
741 packages. Help information will be displayed at the very bottom
742 of the buffer; you may have to scroll down to see it. You can
743 also press `?' to get the same help. From this buffer, you can
744 tell the package status by the character in the first column:
747 The package has not been installed.
750 The package has been installed, but a newer version is
751 available. The current version is out-of-date.
754 The package has been marked for installation/update.
756 If there is no character in the first column, the package has been
757 installed and is up-to-date.
759 From here, you can select or unselect packages for installation
760 using the <RET> key, the `Mouse-2' button or selecting "Select"
761 from the (Popup) Menu. Once you've finished selecting the
762 packages, you can press the `x' key (or use the menu) to actually
763 install the packages. Note that you will have to restart XEmacs
764 for XEmacs to recognize any new packages.
773 Toggle between selecting and unselecting a package for
777 Install selected packages.
780 View, in the minibuffer, additional information about the
781 package, such as the package date (not the build date) and
782 the package author. Moving the mouse over a package name
783 will also do the same thing.
786 Toggle between verbose and non-verbose package display.
789 Refresh the package display.
792 Kill the package buffer.
794 Moving the mouse over a package will also cause additional
795 information about the package to be displayed in the minibuffer.
797 3. Choose the packages you wish to install. mouse: Click button 2 on
798 the package name. keyb: `RET' on the package name
800 4. Make sure you have everything you need. menu: Packages -> Add
803 XEmacs will now search for packages that are required by the ones
804 that you have chosen to install and offer to select those packages
807 For novices and gurus alike, this step can save your bacon. It's
808 easy to forget to install a critical package.
810 5. Download and install the packages. menu: Packages ->
811 Install/Remove Selected keyb: `x'
813 You can also install packages using a semi-manual interface:
815 M-x package-get-all <return>
817 Enter the name of the package (e.g., `prog-modes'), and XEmacs will
818 search for the latest version and install it and any packages that it
822 File: xemacs.info, Node: Which Packages, Next: Removing Packages, Prev: Automatically, Up: Installing Packages
824 Which Packages to Install:
825 ==========================
827 This is difficult to say. When in doubt install a package. If you
828 administrate a big site it might be a good idea to just install
829 everything. A good minimal set of packages for XEmacs-latin1 would be
831 xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
832 edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes,
835 If you are using the XEmacs package tools, don't forget to do:
837 Packages -> Add Required
839 To make sure you have everything that the packages you have chosen to
842 See also *Note Available Packages:: for further descriptions of the
846 File: xemacs.info, Node: Removing Packages, Prev: Which Packages, Up: Installing Packages
851 Because the exact files and their locations contained in a package
852 may change it is recommended to remove a package first before
853 installing a new version. In order to facilitate removal each package
854 contains an `pgkinfo/MANIFEST.pkgname' file which list all the files
855 belonging to the package.
857 No need to panic, you don't have to go through the
858 `pkinfo/MANIFEST.pkgname' and manually delete the files. Instead, use
859 `M-x package-admin-delete-binary-package RET'.
861 Note that the interactive package tools included with XEmacs already
865 File: xemacs.info, Node: Building Packages, Next: Local.rules File, Prev: Installing Packages, Up: Packages
870 Currently, source packages are only available via anonymous CVS. See
871 <http://cvs.xemacs.org/> for details of checking out the
872 `xemacs-packages' module.
874 Prerequisites for Building Source Packages
875 ------------------------------------------
880 (or a BSD compatible install program).
883 (3.75 or later preferred).
886 (1.68 from texinfo-3.11 or later required).
894 `A properly configured `Local.rules' file.'
895 *Note Local.rules File::. And of course, XEmacs 21.0 or higher.
897 What You Can Do With Source Packages
898 ------------------------------------
900 The packages CVS sources are most useful for creating XEmacs package
901 tarballs for installation into your own XEmacs installations or for
902 distributing to others.
904 Supported operations from `make' are:
907 Bytecompile all files, build and bytecompile byproduct files like
908 `auto-autoloads.el' and `custom-load.el'. Create info version of
909 TeXinfo documentation if present.
912 Does a `make all' as well as create a binary package tarball in the
916 Bytecompile all files, build and bytecompile byproduct files like
917 `auto-autoloads.el' and `custom-load.el'. Create info version of
918 TeXinfo documentation if present. And install everything into the
922 Usually aliased to `srckit-std'. This does a `make distclean' and
923 creates a package source tarball in the staging directory. This
924 is generally only of use for package maintainers.
927 May be aliased to `binkit-sourceonly', `binkit-sourceinfo',
928 `binkit-sourcedata', or `binkit-sourcedatainfo'. `sourceonly'
929 indicates there is nothing to install in a data directory or info
930 directory. `sourceinfo' indicates that source and info files are
931 to be installed. `sourcedata' indicates that source and etc
932 (data) files are to be installed. `sourcedatainfo' indicates
933 source, etc (data), and info files are to be installed. A few
934 packages have needs beyond the basic templates so this is not yet
938 Runs the rules `srckit' followed by `binkit'. This is primarily
939 of use by XEmacs maintainers producing files for distribution.
942 Remove all built files except `auto-autoloads.el' and
946 Remove all created files.
949 File: xemacs.info, Node: Local.rules File, Next: Creating Packages, Prev: Building Packages, Up: Packages
951 The Local.rules File:
952 =====================
954 This file is used when building and installing packages from source.
955 In the top level of the CVS module, `xemacs-packages', contains the
956 file, `Local.rules.template'. Simply copy that to `Local.rules' and
957 edit it to suit your needs.
959 These are the variables in 'Local.rules' that you will need to
963 Set this to 't' if you want to do a "run in place". Setting this
964 doesn't work well with 'make bindist'
967 This is where you set the normal packages that you want to
969 XEMACS_PACKAGES = libs/xemacs-base comm/bbdb
971 XEMACS_STAGING = ${XEMACS_PACKAGES_BASE}/../PACKAGES
972 Set this to where you want normal packages to be installed to.
974 PACKAGE_INDEX = PACKAGE-INDEX
975 If you want the package-index file to have a different name,
979 Building from CVS defaults to building the Mule packages. Set
980 this to 't' if you don't want/have Mule
983 Same as for 'XEMACS_PACKAGES' except you list the Mule packages
984 you want to install here. eg:
985 MULE_PACKAGES = mule/mule-base mule/skk
987 MULE_STAGING = ${XEMACS_PACKAGES_BASE}/../MULE-PACKAGES
988 Set this to where you want Mule packages installed to. Note:
989 'make bindist' does not use this variable.
992 If your XEmacs isn't in your path, change this.
995 Set this to 't' if you are building on WinNT.
998 The path to your BSD compatible install program.
1001 The path to your tar program
1004 If you want bzip2 tarballs, set this.
1007 The path to your makeinfo program
1010 File: xemacs.info, Node: Creating Packages, Next: Available Packages, Prev: Local.rules File, Up: Packages
1015 Creating a package from an existing Lisp library is not very
1018 In addition to the Lisp libraries themselves, you need a
1019 `package-info.in' file and a simple `Makefile'. The rest is done by
1020 `XEmacs.rules', part of the packaging system infrastructure.
1022 `package-info.in' contains a single Lisp form like this:
1024 (name ; your package's name
1025 (standards-version 1.1
1027 author-version AUTHOR_VERSION
1029 build-date BUILD_DATE
1030 maintainer MAINTAINER
1031 distribution xemacs ; change to "mule" if MULE is needed
1035 description "description" ; a one-line description string
1039 provides (feature1 feature2) ; one for every `provides' form
1044 You must fill in the four commented lines. The value of `name' is
1045 the name of your package as an unquoted symbol. Normally it is the name
1046 of the main Lisp file or principal feature provided. The allowed values
1047 for distribution are `xemacs' and `mule'. Write them as unquoted
1048 symbols. The `description' is a quoted Lisp string; use the usual
1049 conventions. The value for `provides' is a list of feature symbols
1050 (written unquoted). All of the features provided by libraries in your
1051 package should be elements of this list. Implementing an automatic
1052 method for generating the `provides' line is desirable, but as yet
1055 The variables in upper-case are references to variables set in the
1056 `Makefile' or automatically generated. Do not change them; they are
1057 automatically filled in by the build process.
1059 The remaining lines refer to implementation constants
1060 (`standards-version'), or features that are unimplemented or have been
1061 removed (`priority' and `dump'). The `type' line is not normally
1062 relevant to external maintainers; the alternate value is `single-file',
1063 which refers to packages consed up out of a number of single-file
1064 libraries that are more or less thematically related. An example is
1065 `prog-modes'. Single-file packages are basically for administrative
1066 convenience, and new packages should generally be created as regular
1069 The `Makefile' is quite stylized. The idea is similar to an
1070 `Imakefile' or an `automake' file: the complexity is hidden in generic
1071 rules files, in this case the `XEmacs.rules' include file in the top
1072 directory of the packages hierarchy. Although a number of facilities
1073 are available for complex libraries, most simple packages' `Makefile's
1074 contain a copyright notice, a few variable definitions, an include for
1075 `XEmacs.rules', and a couple of standard targets.
1077 The first few `make' variables defined are `VERSION',
1078 `AUTHOR_VERSION', `MAINTAINER', `PACKAGE', `PKG_TYPE', `REQUIRES', and
1079 `CATEGORY'. All but one were described in the description of
1080 `package-info.in'. The last is an admistrative grouping. Current
1081 categories include `comm', `games', `libs', `mule', `oa', `os', `prog',
1082 and `wp'. *Note Available Packages::, for a list of categories.
1084 Next, define the variable `ELCS'. This contains the list of the
1085 byte-compiled Lisp files used by the package. These files and their
1086 `.el' versions will be included in the binary package. If there are
1087 other files (such as extra Lisp sources or an upstream `Makefile') that
1088 are normally placed in the installed Lisp directory, but not
1089 byte-compiled, they can be listed as the value of `EXTRA_SOURCES'.
1091 The include is simply
1092 include ../../XEmacs.rules
1094 The standard targets follow. These are
1096 all:: $(ELCS) auto-autoloads.elc
1098 srckit: srckit-alias
1100 binkit: binkit-alias
1102 Other targets (such as Texinfo sources) may need to be added as
1103 dependencies for the `all' target. Dependencies for `srckit' and
1104 `binkit' (that is, values for SRCKIT-ALIAS and BINKIT-ALIAS) are
1105 defined in `XEmacs.rules'. The most useful of these values are given
1106 in the following table.
1109 Usually set to `srckit-std'.
1112 May be set to `binkit-sourceonly', `binkit-sourceinfo',
1113 `binkit-sourcedata', or `binkit-sourcedatainfo'. `sourceonly'
1114 indicates there is nothing to install in a data directory or info
1115 directory. `sourceinfo' indicates that source and info files are
1116 to be installed. `sourcedata' indicates that source and etc
1117 (data) files are to be installed. `sourcedatainfo' indicates
1118 source, etc (data), and info files are to be installed.
1120 Data files include things like pixmaps for a package-specific
1121 toolbar, and are normally installed in `etc/PACKAGE_NAME'. A few
1122 packages have needs beyond the basic templates. See `XEmacs.rules' or
1123 a future revision of this manual for details.