[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9. The Modules of XEmacs


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1 A Summary of the Various XEmacs Modules

The following is a list of the sections describing the various modules (i.e. files) that implement XEmacs. Some of them are in this chapter; some of them are attached to the chapters describing the modules in question.

The following table contains cross-references from each module in XEmacs 21.5 to the section (if any) describing it.

intl-auto-encap-win32.cModules for Other Aspects of the Lisp Interpreter and Object System.
Emacs.ad.hModules for Interfacing with X Windows.
EmacsFrame.cModules for Interfacing with X Windows.
EmacsFrame.hModules for Interfacing with X Windows.
EmacsFrameP.hModules for Interfacing with X Windows.
EmacsManager.cModules for Interfacing with X Windows.
EmacsManager.hModules for Interfacing with X Windows.
EmacsManagerP.hModules for Interfacing with X Windows.
EmacsShell-sub.cModules for Interfacing with X Windows.
EmacsShell.cModules for Interfacing with X Windows.
EmacsShell.hModules for Interfacing with X Windows.
EmacsShellP.hModules for Interfacing with X Windows.
ExternalClient-Xlib.cModules for Interfacing with X Windows.
ExternalClient.cModules for Interfacing with X Windows.
ExternalClient.hModules for Interfacing with X Windows.
ExternalClientP.hModules for Interfacing with X Windows.
ExternalShell.cModules for Interfacing with X Windows.
ExternalShell.hModules for Interfacing with X Windows.
ExternalShellP.hModules for Interfacing with X Windows.
Makefile.in.in
abbrev.cModules for Other Aspects of the Lisp Interpreter and Object System.
alloc.cBasic Lisp Modules.
alloca.cLow-Level Modules.
alloca.s
backtrace.hBasic Lisp Modules.
balloon-x.c
balloon_help.c
balloon_help.h
base64-tests.elModules for Regression Testing.
bitmaps.hModules for other Display-Related Lisp Objects.
blocktype.cLow-Level Modules.
blocktype.hLow-Level Modules.
buffer.cModules for Standard Editing Operations.
buffer.hModules for Standard Editing Operations.
bufslots.hModules for Standard Editing Operations.
byte-compiler-tests.elModules for Regression Testing.
bytecode.cBasic Lisp Modules.
bytecode.hBasic Lisp Modules.
c-tests.elModules for Regression Testing.
callint.cModules for Standard Editing Operations.
case-tests.elModules for Regression Testing.
casefiddle.cModules for Other Aspects of the Lisp Interpreter and Object System.
casetab.cModules for Other Aspects of the Lisp Interpreter and Object System.
casetab.h
ccl-tests.elModules for Regression Testing.
charset.h
chartab.cModules for Other Aspects of the Lisp Interpreter and Object System.
chartab.hModules for Other Aspects of the Lisp Interpreter and Object System.
cm.cModules for the Redisplay Mechanism.
cm.hModules for the Redisplay Mechanism.
cmdloop.cEditor-Level Control Flow Modules.
cmds.cModules for Standard Editing Operations.
coding-system-slots.h
commands.hModules for Standard Editing Operations.
compiler.h
config.h.in
config.hLow-Level Modules.
conslots.h
console-gtk-impl.h
console-gtk.c
console-gtk.h
console-impl.h
console-msw-impl.h
console-msw.cModules for the Basic Displayable Lisp Objects.
console-msw.hModules for the Basic Displayable Lisp Objects.
console-stream-impl.h
console-stream.cModules for the Basic Displayable Lisp Objects.
console-stream.hModules for the Basic Displayable Lisp Objects.
console-tty-impl.h
console-tty.cModules for the Basic Displayable Lisp Objects.
console-tty.hModules for the Basic Displayable Lisp Objects.
console-x-impl.h
console-x.cModules for the Basic Displayable Lisp Objects.
console-x.hModules for the Basic Displayable Lisp Objects.
console.cModules for the Basic Displayable Lisp Objects.
console.hModules for the Basic Displayable Lisp Objects.
data.cBasic Lisp Modules.
database-tests.elModules for Regression Testing.
database.c
database.h
debug.cLow-Level Modules.
debug.hLow-Level Modules.
depend
device-gtk.c
device-impl.h
device-msw.cModules for the Basic Displayable Lisp Objects.
device-tty.cModules for the Basic Displayable Lisp Objects.
device-x.cModules for the Basic Displayable Lisp Objects.
device.cModules for the Basic Displayable Lisp Objects.
device.hModules for the Basic Displayable Lisp Objects.
devslots.h
dialog-gtk.c
dialog-msw.c
dialog-x.c
dialog.c
dired-msw.c
dired.cModules for Interfacing with the File System.
doc.cModules for Other Aspects of the Lisp Interpreter and Object System.
doprnt.cModules for Standard Editing Operations.
dragdrop.c
dragdrop.h
dump-data.c
dump-data.h
dump-id.c
dumper.c
dumper.h
dynarr.cLow-Level Modules.
ecrt0.cLow-Level Modules.
editfns.cModules for Standard Editing Operations.
elhash.cModules for Other Aspects of the Lisp Interpreter and Object System.
elhash.hModules for Other Aspects of the Lisp Interpreter and Object System.
emacs-marshals.c
emacs-new.c.old
emacs-widget-accessors.c
emacs.cLow-Level Modules.
emodules.c
emodules.h
esd.c
eval.cBasic Lisp Modules.
event-Xt.cEditor-Level Control Flow Modules.
event-gtk.c
event-gtk.h
event-msw.cEditor-Level Control Flow Modules.
event-stream.cEditor-Level Control Flow Modules.
event-tty.cEditor-Level Control Flow Modules.
event-unixoid.c
event-xlike-inc.c
events-mod.hEditor-Level Control Flow Modules.
events.cEditor-Level Control Flow Modules.
events.hEditor-Level Control Flow Modules.
extent-tests.elModules for Regression Testing.
extents-impl.h
extents.cModules for Standard Editing Operations.
extents.hModules for Standard Editing Operations.
extw-Xlib.cModules for Interfacing with X Windows.
extw-Xlib.hModules for Interfacing with X Windows.
extw-Xt.cModules for Interfacing with X Windows.
extw-Xt.hModules for Interfacing with X Windows.
faces.cModules for other Display-Related Lisp Objects.
faces.hModules for other Display-Related Lisp Objects.
file-coding.cModules for Internationalization.
file-coding.hModules for Internationalization.
fileio.cModules for Interfacing with the File System.
filelock.cModules for Interfacing with the File System.
filemode.cModules for Interfacing with the File System.
floatfns.cBasic Lisp Modules.
fns.cBasic Lisp Modules.
font-lock.cModules for other Display-Related Lisp Objects.
frame-gtk.c
frame-impl.h
frame-msw.cModules for the Basic Displayable Lisp Objects.
frame-tty.cModules for the Basic Displayable Lisp Objects.
frame-x.cModules for the Basic Displayable Lisp Objects.
frame.cModules for the Basic Displayable Lisp Objects.
frame.diff
frame.hModules for the Basic Displayable Lisp Objects.
frameslots.h
free-hook.cLow-Level Modules.
gccache-gtk.c
gccache-gtk.h
general-slots.h
general.cBasic Lisp Modules.
getloadavg.cModules for Interfacing with the Operating System.
getpagesize.hLow-Level Modules.
glade.c
glyphs-eimage.cModules for other Display-Related Lisp Objects.
glyphs-gtk.c
glyphs-gtk.h
glyphs-msw.cModules for other Display-Related Lisp Objects.
glyphs-msw.hModules for other Display-Related Lisp Objects.
glyphs-shared.c
glyphs-widget.cModules for other Display-Related Lisp Objects.
glyphs-x.cModules for other Display-Related Lisp Objects.
glyphs-x.hModules for other Display-Related Lisp Objects.
glyphs.cModules for other Display-Related Lisp Objects.
glyphs.hModules for other Display-Related Lisp Objects.
gmalloc.cLow-Level Modules.
gpmevent.cEditor-Level Control Flow Modules.
gpmevent.hEditor-Level Control Flow Modules.
gtk-glue.c
gtk-xemacs.c
gtk-xemacs.h
gui-gtk.c
gui-msw.c
gui-x.c
gui.c
gui.h
gutter.c
gutter.h
hash-table-tests.elModules for Regression Testing.
hash.cModules for Other Aspects of the Lisp Interpreter and Object System.
hash.hModules for Other Aspects of the Lisp Interpreter and Object System.
hpplay.cModules for Interfacing with the Operating System.
imgproc.c
imgproc.h
indent.cModules for the Redisplay Mechanism.
inline.cLow-Level Modules.
input-method-motif.c
input-method-xlib.c
insdel.cModules for Standard Editing Operations.
insdel.hModules for Standard Editing Operations.
intl-auto-encap-win32.c
intl-auto-encap-win32.h
intl-encap-win32.c
intl-win32.c
intl-x.c
intl.cModules for Internationalization.
iso-wide.hModules for Internationalization.
keymap.cEditor-Level Control Flow Modules.
keymap.hEditor-Level Control Flow Modules.
lastfile.cLow-Level Modules.
libinterface.c
libinterface.h
libsst.cModules for Interfacing with the Operating System.
libsst.hModules for Interfacing with the Operating System.
libst.hModules for Interfacing with the Operating System.
line-number.c
line-number.h
linuxplay.cModules for Interfacing with the Operating System.
lisp-disunion.hBasic Lisp Modules.
lisp-tests.elModules for Regression Testing.
lisp-union.hBasic Lisp Modules.
lisp.hBasic Lisp Modules.
lread.cBasic Lisp Modules.
lrecord.hBasic Lisp Modules.
lstream.cModules for Interfacing with the File System.
lstream.hModules for Interfacing with the File System.
macros.cEditor-Level Control Flow Modules.
macros.hEditor-Level Control Flow Modules.
make-src-depend
malloc.cLow-Level Modules.
marker.cModules for Standard Editing Operations.
md5-tests.elModules for Regression Testing.
md5.cModules for Other Aspects of the Lisp Interpreter and Object System.
mem-limits.hLow-Level Modules.
menubar-gtk.c
menubar-msw.cModules for other Display-Related Lisp Objects.
menubar-msw.hModules for other Display-Related Lisp Objects.
menubar-x.cModules for other Display-Related Lisp Objects.
menubar.cModules for other Display-Related Lisp Objects.
menubar.hModules for other Display-Related Lisp Objects.
minibuf.cEditor-Level Control Flow Modules.
miscplay.c
miscplay.h
mule-canna.cModules for Internationalization.
mule-ccl.cModules for Internationalization.
mule-ccl.h
mule-charset.cModules for Internationalization.
mule-charset.hModules for Internationalization.
mule-coding.cModules for Internationalization.
mule-mcpath.cModules for Internationalization.
mule-mcpath.hModules for Internationalization.
mule-tests.elModules for Regression Testing.
mule-wnnfns.cModules for Internationalization.
mule.cModules for Internationalization.
nas.cModules for Interfacing with the Operating System.
native-gtk-toolbar.c
ndir.hModules for Interfacing with the File System.
nt.c
ntheap.c
ntplay.c
number-gmp.c
number-gmp.h
number-mp.c
number-mp.h
number.c
number.h
fontcolor-gtk-impl.h
fontcolor-gtk.c
fontcolor-gtk.h
fontcolor-impl.h
fontcolor-msw-impl.h
fontcolor-msw.cModules for other Display-Related Lisp Objects.
fontcolor-msw.hModules for other Display-Related Lisp Objects.
fontcolor-tty-impl.h
fontcolor-tty.cModules for other Display-Related Lisp Objects.
fontcolor-tty.hModules for other Display-Related Lisp Objects.
fontcolor-x-impl.h
fontcolor-x.cModules for other Display-Related Lisp Objects.
fontcolor-x.hModules for other Display-Related Lisp Objects.
fontcolor.cModules for other Display-Related Lisp Objects.
fontcolor.hModules for other Display-Related Lisp Objects.
opaque.cModules for Other Aspects of the Lisp Interpreter and Object System.
opaque.hModules for Other Aspects of the Lisp Interpreter and Object System.
paths.h.in
paths.hLow-Level Modules.
ppc.ldscript
pre-crt0.cLow-Level Modules.
print.cBasic Lisp Modules.
process-nt.c
process-slots.h
process-unix.c
process.cModules for Interfacing with the Operating System.
process.elModules for Interfacing with the Operating System.
process.hModules for Interfacing with the Operating System.
procimpl.h
profile.c.orig
profile.c.rej
profile.c
profile.h
ralloc.cLow-Level Modules.
rangetab.cModules for Other Aspects of the Lisp Interpreter and Object System.
rangetab.h
realpath.cModules for Interfacing with the File System.
redisplay-gtk.c
redisplay-msw.cModules for the Redisplay Mechanism.
redisplay-output.cModules for the Redisplay Mechanism.
redisplay-tty.cModules for the Redisplay Mechanism.
redisplay-x.cModules for the Redisplay Mechanism.
redisplay.cModules for the Redisplay Mechanism.
redisplay.hModules for the Redisplay Mechanism.
regex.cModules for Standard Editing Operations.
regex.hModules for Standard Editing Operations.
regexp-tests.elModules for Regression Testing.
scrollbar-gtk.c
scrollbar-gtk.h
scrollbar-msw.cModules for other Display-Related Lisp Objects.
scrollbar-msw.hModules for other Display-Related Lisp Objects.
scrollbar-x.cModules for other Display-Related Lisp Objects.
scrollbar-x.hModules for other Display-Related Lisp Objects.
scrollbar.cModules for other Display-Related Lisp Objects.
scrollbar.hModules for other Display-Related Lisp Objects.
search.cModules for Standard Editing Operations.
select-xlike-inc.c
select-gtk.c
select-msw.cModules for Interfacing with X Windows.
select-x.cModules for Interfacing with X Windows.
select.cModules for Interfacing with X Windows.
select.hModules for Interfacing with X Windows.
sequence.cBasic Lisp Modules.
sgiplay.cModules for Interfacing with the Operating System.
sheap.c
signal.cLow-Level Modules.
sound.cModules for Interfacing with the Operating System.
sound.h
specifier.cModules for Other Aspects of the Lisp Interpreter and Object System.
specifier.hModules for Other Aspects of the Lisp Interpreter and Object System.
src-headers
strcat.c
strftime.c
sunplay.cModules for Interfacing with the Operating System.
sunpro.cModules for Interfacing with the Operating System.
symbol-tests.elModules for Regression Testing.
symbols.cBasic Lisp Modules.
symeval.hBasic Lisp Modules.
symsinit.hBasic Lisp Modules.
syntax-tests.elModules for Regression Testing.
syntax.cModules for Other Aspects of the Lisp Interpreter and Object System.
syntax.hModules for Other Aspects of the Lisp Interpreter and Object System.
sysdep.cModules for Interfacing with the Operating System.
sysdep.hModules for Interfacing with the Operating System.
sysdir.hModules for Interfacing with the Operating System.
sysdll.c
sysdll.h
sysfile.hModules for Interfacing with the Operating System.
sysfloat.hModules for Interfacing with the Operating System.
sysproc.hModules for Interfacing with the Operating System.
syspwd.hModules for Interfacing with the Operating System.
syssignal.hModules for Interfacing with the Operating System.
systime.hModules for Interfacing with the Operating System.
systty.hModules for Interfacing with the Operating System.
syswait.hModules for Interfacing with the Operating System.
syswindows.h
tag-tests.elModules for Regression Testing.
termcap.cModules for the Redisplay Mechanism.
terminfo.cModules for the Redisplay Mechanism.
test-harness.elModules for Regression Testing.
tests.c
text.c
text.h
toolbar-xlike.c
toolbar-xlike.h
toolbar-gtk.c
toolbar-msw.cModules for other Display-Related Lisp Objects.
toolbar-x.cModules for other Display-Related Lisp Objects.
toolbar.cModules for other Display-Related Lisp Objects.
toolbar.hModules for other Display-Related Lisp Objects.
tooltalk.cModules for Interfacing with the Operating System.
tooltalk.hModules for Interfacing with the Operating System.
tparam.cModules for the Redisplay Mechanism.
ui-byhand.c
ui-gtk.c
ui-gtk.h
undo.cModules for Standard Editing Operations.
unexaix.cLow-Level Modules.
unexalpha.cLow-Level Modules.
unexcw.c
unexec.cLow-Level Modules.
unexelf.cLow-Level Modules.
unexhp9k800.cLow-Level Modules.
unexnt.c
unexsol2-6.c
unicode.c
universe.hLow-Level Modules.
vm-limit.cLow-Level Modules.
weak-tests.elModules for Regression Testing.
widget.c
win32.c
window-impl.h
window.cModules for the Basic Displayable Lisp Objects.
window.hModules for the Basic Displayable Lisp Objects.
winslots.h
xemacs.def.in.in
xgccache.cModules for Interfacing with X Windows.
xgccache.hModules for Interfacing with X Windows.
xintrinsic.hModules for Interfacing with X Windows.
xintrinsicp.hModules for Interfacing with X Windows.
xmmanagerp.hModules for Interfacing with X Windows.
xmotif.h
xmprimitivep.hModules for Interfacing with X Windows.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2 Modules for Building XEmacs


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2.1 Modules for Build Configuration

 
configure’
‘config.h.in’
‘Makefile.in.in’
‘version.sh
 
configure.ac’
‘configure.in

See section The version.sh Script. See section The configure Script.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2.2 Modules for Compiling XEmacs

Please write this node!

This node should contain descriptions of files like the various Makefiles, and I guess cross-references to ellcc etc.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2.3 Modules for Preloading Lisp

Please write this node!

This node should contain descriptions of files like dumped-lisp.el (maybe that goes in Modules for Build Configuration supra?), update-elcs.el, and so on.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.3 Low-Level Modules

 
version.sh

This is a Bourne shell script which sets version-related variables. It is updated in the release process by the maintainer of each series or branch, and may also be automatically updated. See section The version.sh Script.

 
config.h

This is automatically generated from ‘config.h.in’ based on the results of configure tests and user-selected optional features and contains preprocessor definitions specifying the nature of the environment in which XEmacs is being compiled.

 
paths.h

This is automatically generated from ‘paths.h.in’ based on supplied configure values, and allows for non-standard installed configurations of the XEmacs directories. It’s currently broken, though.

 
emacs.c’
‘signal.c

emacs.c’ contains main() and other code that performs the most basic environment initializations and handles shutting down the XEmacs process (this includes kill-emacs, the normal way that XEmacs is exited; dump-emacs, which is used during the build process to write out the XEmacs executable; run-emacs-from-temacs, which can be used to start XEmacs directly when temacs has finished loading all the Lisp code; and emergency code to handle crashes [XEmacs tries to auto-save all files before it crashes]).

Low-level code that directly interacts with the Unix signal mechanism, however, is in ‘signal.c’. Note that this code does not handle system dependencies in interfacing to signals; that is handled using the ‘syssignal.h’ header file, described in section J below.

 
unexaix.c’
‘unexalpha.c’
‘unexec.c’
‘unexelf.c’
‘unexhp9k800.c

These modules contain code dumping out the XEmacs executable on various different systems. (This process is highly machine-specific and requires intimate knowledge of the executable format and the memory map of the process.) Only one of these modules is actually used; this is chosen by ‘configure’.

 
ecrt0.c’
‘lastfile.c’
‘pre-crt0.c

These modules are used in conjunction with the dump mechanism. On some systems, an alternative version of the C startup code (the actual code that receives control from the operating system when the process is started, and which calls main()) is required so that the dumping process works properly; ‘crt0.c’ provides this.

pre-crt0.c’ and ‘lastfile.c’ should be the very first and very last file linked, respectively. (Actually, this is not really true. ‘lastfile.c’ should be after all Emacs modules whose initialized data should be made constant, and before all other Emacs files and all libraries. In particular, the allocation modules ‘gmalloc.c’, ‘alloca.c’, etc. are normally placed past ‘lastfile.c’, and all of the files that implement Xt widget classes must be placed after ‘lastfile.c’ because they contain various structures that must be statically initialized and into which Xt writes at various times.) ‘pre-crt0.c’ and ‘lastfile.c’ contain exported symbols that are used to determine the start and end of XEmacs’ initialized data space when dumping.

 
inline.c

This module is used in connection with inline functions (available in some compilers). Often, inline functions need to have a corresponding non-inline function that does the same thing. This module is where they reside. It contains no actual code, but defines some special flags that cause inline functions defined in header files to be rendered as actual functions. It then includes all header files that contain any inline function definitions, so that each one gets a real function equivalent.

 
debug.c’
‘debug.h

These functions provide a system for doing internal consistency checks during code development. This system is not currently used; instead the simpler assert() macro is used along with the various checks provided by the ‘--error-check-*’ configuration options.

 
universe.h

This is not currently used.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.4 Basic Lisp Modules

 
lisp-disunion.h’
‘lisp-union.h’
‘lisp.h’
‘lrecord.h’
‘symsinit.h

These are the basic header files for all XEmacs modules. Each module includes ‘lisp.h’, which brings the other header files in. ‘lisp.h’ contains the definitions of the structures and extractor and constructor macros for the basic Lisp objects and various other basic definitions for the Lisp environment, as well as some general-purpose definitions (e.g. min() and max()). ‘lisp.h’ includes either ‘lisp-disunion.h’ or ‘lisp-union.h’, depending on whether USE_UNION_TYPE is defined. These files define the typedef of the Lisp object itself (as described above) and the low-level macros that hide the actual implementation of the Lisp object. All extractor and constructor macros for particular types of Lisp objects are defined in terms of these low-level macros.

As a general rule, all typedefs should go into the typedefs section of ‘lisp.h’ rather than into a module-specific header file even if the structure is defined elsewhere. This allows function prototypes that use the typedef to be placed into other header files. Forward structure declarations (i.e. a simple declaration like struct foo; where the structure itself is defined elsewhere) should be placed into the typedefs section as necessary.

lrecord.h’ contains the basic structures and macros that implement all record-type Lisp objects—i.e. all objects whose type is a field in their C structure, which includes all objects except the few most basic ones.

lisp.h’ contains prototypes for most of the exported functions in the various modules. Lisp primitives defined using DEFUN that need to be called by C code should be declared using EXFUN. Other function prototypes should be placed either into the appropriate section of lisp.h, or into a module-specific header file, depending on how general-purpose the function is and whether it has special-purpose argument types requiring definitions not in ‘lisp.h’.) All initialization functions are prototyped in ‘symsinit.h’.

 
alloc.c

The large module ‘alloc.c’ implements all of the basic allocation and garbage collection for Lisp objects. The most commonly used Lisp objects are allocated in chunks, similar to the Blocktype data type described above; others are allocated in individually malloc()ed blocks. This module provides the foundation on which all other aspects of the Lisp environment sit, and is the first module initialized at startup.

Note that ‘alloc.c’ provides a series of generic functions that are not dependent on any particular object type, and interfaces to particular types of objects using a standardized interface of type-specific methods. This scheme is a fundamental principle of object-oriented programming and is heavily used throughout XEmacs. The great advantage of this is that it allows for a clean separation of functionality into different modules—new classes of Lisp objects, new event interfaces, new device types, new stream interfaces, etc. can be added transparently without affecting code anywhere else in XEmacs. Because the different subsystems are divided into general and specific code, adding a new subtype within a subsystem will in general not require changes to the generic subsystem code or affect any of the other subtypes in the subsystem; this provides a great deal of robustness to the XEmacs code.

 
eval.c’
‘backtrace.h

This module contains all of the functions to handle the flow of control. This includes the mechanisms of defining functions, calling functions, traversing stack frames, and binding variables; the control primitives and other special operators such as while, if, eval, let, and, or, progn, etc.; handling of non-local exits, unwind-protects, and exception handlers; entering the debugger; methods for the subr Lisp object type; etc. It does not include the read function, the print function, or the handling of symbols and obarrays.

backtrace.h’ contains some structures related to stack frames and the flow of control.

 
lread.c

This module implements the Lisp reader and the read function, which converts text into Lisp objects, according to the read syntax of the objects, as described above. This is similar to the parser that is a part of all compilers.

 
print.c

This module implements the Lisp print mechanism and the print function and related functions. This is the inverse of the Lisp reader – it converts Lisp objects to a printed, textual representation. (Hopefully something that can be read back in using read to get an equivalent object.)

 
general.c’
‘symbols.c’
‘symeval.h

symbols.c’ implements the handling of symbols, obarrays, and retrieving the values of symbols. Much of the code is devoted to handling the special symbol-value-magic objects that define special types of variables—this includes buffer-local variables, variable aliases, variables that forward into C variables, etc. This module is initialized extremely early (right after ‘alloc.c’), because it is here that the basic symbols t and nil are created, and those symbols are used everywhere throughout XEmacs.

symeval.h’ contains the definitions of symbol structures and the DEFVAR_LISP() and related macros for declaring variables.

 
data.c’
‘floatfns.c’
‘fns.c’
‘sequence.c

These modules implement the methods and standard Lisp primitives for all the basic Lisp object types other than symbols (which are described above). ‘data.c’ contains all the predicates (primitives that return whether an object is of a particular type); the integer arithmetic functions; and the basic accessor and mutator primitives for the various object types. ‘sequence.c’ contains all the built-in functions for working with sequences (where, abstractly speaking, a sequence is an ordered set of objects, and can be represented by a list, string, vector, or bit-vector). ‘fns.c’ contains equal and a grab-bag of other functions that should probably be refactored elsewhere. ‘floatfns.c’ contains methods and primitives for floats and floating-point arithmetic.

 
bytecode.c’
‘bytecode.h

bytecode.c’ implements the byte-code interpreter and compiled-function objects, and ‘bytecode.h’ contains associated structures. Note that the byte-code compiler is written in Lisp.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.5 Modules for Standard Editing Operations

 
buffer.c’
‘buffer.h’
‘bufslots.h

buffer.c’ implements the buffer Lisp object type. This includes functions that create and destroy buffers; retrieve buffers by name or by other properties; manipulate lists of buffers (remember that buffers are permanent objects and stored in various ordered lists); retrieve or change buffer properties; etc. It also contains the definitions of all the built-in buffer-local variables (which can be viewed as buffer properties). It does not contain code to manipulate buffer-local variables (that’s in ‘symbols.c’, described above); or code to manipulate the text in a buffer.

buffer.h’ defines the structures associated with a buffer and the various macros for retrieving text from a buffer and special buffer positions (e.g. point, the default location for text insertion). It also contains macros for working with buffer positions and converting between their representations as character offsets and as byte offsets (under MULE, they are different, because characters can be multi-byte). It is one of the largest header files.

bufslots.h’ defines the fields in the buffer structure that correspond to the built-in buffer-local variables. It is its own header file because it is included many times in ‘buffer.c’, as a way of iterating over all the built-in buffer-local variables.

 
insdel.c’
‘insdel.h

insdel.c’ contains low-level functions for inserting and deleting text in a buffer, keeping track of changed regions for use by redisplay, and calling any before-change and after-change functions that may have been registered for the buffer. It also contains the actual functions that convert between byte offsets and character offsets.

insdel.h’ contains associated headers.

 
marker.c

This module implements the marker Lisp object type, which conceptually is a pointer to a text position in a buffer that moves around as text is inserted and deleted, so as to remain in the same relative position. This module doesn’t actually move the markers around – that’s handled in ‘insdel.c’. This module just creates them and implements the primitives for working with them. As markers are simple objects, this does not entail much.

Note that the standard arithmetic primitives (e.g. +) accept markers in place of integers and automatically substitute the value of marker-position for the marker, i.e. an integer describing the current buffer position of the marker.

 
extents.c’
‘extents.h

This module implements the extent Lisp object type, which is like a marker that works over a range of text rather than a single position. Extents are also much more complex and powerful than markers and have a more efficient (and more algorithmically complex) implementation. The implementation is described in detail in comments in ‘extents.c’.

The code in ‘extents.c’ works closely with ‘insdel.c’ so that extents are properly moved around as text is inserted and deleted. There is also code in ‘extents.c’ that provides information needed by the redisplay mechanism for efficient operation. (Remember that extents can have display properties that affect [sometimes drastically, as in the invisible property] the display of the text they cover.)

 
editfns.c

editfns.c’ contains the standard Lisp primitives for working with a buffer’s text, and calls the low-level functions in ‘insdel.c’. It also contains primitives for working with point (the default buffer insertion location).

editfns.c’ also contains functions for retrieving various characteristics from the external environment: the current time, the process ID of the running XEmacs process, the name of the user who ran this XEmacs process, etc. It’s not clear why this code is in ‘editfns.c’.

 
callint.c’
‘cmds.c’
‘commands.h

These modules implement the basic interactive commands, i.e. user-callable functions. Commands, as opposed to other functions, have special ways of getting their parameters interactively (by querying the user), as opposed to having them passed in a normal function invocation. Many commands are not really meant to be called from other Lisp functions, because they modify global state in a way that’s often undesired as part of other Lisp functions.

callint.c’ implements the mechanism for querying the user for parameters and calling interactive commands. The bulk of this module is code that parses the interactive spec that is supplied with an interactive command.

cmds.c’ implements the basic, most commonly used editing commands: commands to move around the current buffer and insert and delete characters. These commands are implemented using the Lisp primitives defined in ‘editfns.c’.

commands.h’ contains associated structure definitions and prototypes.

 
regex.c’
‘regex.h’
‘search.c

search.c’ implements the Lisp primitives for searching for text in a buffer, and some of the low-level algorithms for doing this. In particular, the fast fixed-string Boyer-Moore search algorithm is implemented in ‘search.c’. The low-level algorithms for doing regular-expression searching, however, are implemented in ‘regex.c’ and ‘regex.h’. These two modules are largely independent of XEmacs, and are similar to (and based upon) the regular-expression routines used in ‘grep’ and other GNU utilities.

 
doprnt.c

doprnt.c’ implements formatted-string processing, similar to printf() command in C.

 
undo.c

This module implements the undo mechanism for tracking buffer changes. Most of this could be implemented in Lisp.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.6 Modules for Interfacing with the File System

 
lstream.c’
‘lstream.h

These modules implement the stream Lisp object type. This is an internal-only Lisp object that implements a generic buffering stream. The idea is to provide a uniform interface onto all sources and sinks of data, including file descriptors, stdio streams, chunks of memory, Lisp buffers, Lisp strings, etc. That way, I/O functions can be written to the stream interface and can transparently handle all possible sources and sinks. (For example, the read function can read data from a file, a string, a buffer, or even a function that is called repeatedly to return data, without worrying about where the data is coming from or what-size chunks it is returned in.)

Note that in the C code, streams are called lstreams (for “Lisp streams”) to distinguish them from other kinds of streams, e.g. stdio streams and C++ I/O streams.

Similar to other subsystems in XEmacs, lstreams are separated into generic functions and a set of methods for the different types of lstreams. ‘lstream.c’ provides implementations of many different types of streams; others are provided, e.g., in ‘file-coding.c’.

 
fileio.c

This implements the basic primitives for interfacing with the file system. This includes primitives for reading files into buffers, writing buffers into files, checking for the presence or accessibility of files, canonicalizing file names, etc. Note that these primitives are usually not invoked directly by the user: There is a great deal of higher-level Lisp code that implements the user commands such as find-file and save-buffer. This is similar to the distinction between the lower-level primitives in ‘editfns.c’ and the higher-level user commands in ‘commands.c’ and ‘simple.el’.

 
filelock.c

This file provides functions for detecting clashes between different processes (e.g. XEmacs and some external process, or two different XEmacs processes) modifying the same file. (XEmacs can optionally use the ‘lock/’ subdirectory to provide a form of “locking” between different XEmacs processes.) This module is also used by the low-level functions in ‘insdel.c’ to ensure that, if the first modification is being made to a buffer whose corresponding file has been externally modified, the user is made aware of this so that the buffer can be synched up with the external changes if necessary.

 
filemode.c

This file provides some miscellaneous functions that construct a ‘rwxr-xr-x’-type permissions string (as might appear in an ‘ls’-style directory listing) given the information returned by the stat() system call.

 
dired.c’
‘ndir.h

These files implement the XEmacs interface to directory searching. This includes a number of primitives for determining the files in a directory and for doing filename completion. (Remember that generic completion is handled by a different mechanism, in ‘minibuf.c’.)

ndir.h’ is a header file used for the directory-searching emulation functions provided in ‘sysdep.c’ (see section J below), for systems that don’t provide any directory-searching functions. (On those systems, directories can be read directly as files, and parsed.)

 
realpath.c

This file provides an implementation of the realpath() function for expanding symbolic links, on systems that don’t implement it or have a broken implementation.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.7 Modules for Other Aspects of the Lisp Interpreter and Object System

 
elhash.c’
‘elhash.h’
‘hash.c’
‘hash.h

These files provide two implementations of hash tables. Files ‘hash.c’ and ‘hash.h’ provide a generic C implementation of hash tables which can stand independently of XEmacs. Files ‘elhash.c’ and ‘elhash.h’ provide a separate implementation of hash tables that can store only Lisp objects, and knows about Lispy things like garbage collection, and implement the hash-table Lisp object type.

 
specifier.c’
‘specifier.h

This module implements the specifier Lisp object type. This is primarily used for displayable properties, and allows for values that are specific to a particular buffer, window, frame, device, or device class, as well as a default value existing. This is used, for example, to control the height of the horizontal scrollbar or the appearance of the default, bold, or other faces. The specifier object consists of a number of specifications, each of which maps from a buffer, window, etc. to a value. The function specifier-instance looks up a value given a window (from which a buffer, frame, and device can be derived).

 
chartab.c’
‘chartab.h’
‘casetab.c

chartab.c’ and ‘chartab.h’ implement the char table Lisp object type, which maps from characters or certain sorts of character ranges to Lisp objects. The implementation of this object type is optimized for the internal representation of characters. Char tables come in different types, which affect the allowed object types to which a character can be mapped and also dictate certain other properties of the char table.

casetab.c’ implements one sort of char table, the case table, which maps characters to other characters of possibly different case. These are used by XEmacs to implement case-changing primitives and to do case-insensitive searching.

 
syntax.c’
‘syntax.h

This module implements syntax tables, another sort of char table that maps characters into syntax classes that define the syntax of these characters (e.g. a parenthesis belongs to a class of ‘open’ characters that have corresponding ‘close’ characters and can be nested). This module also implements the Lisp scanner, a set of primitives for scanning over text based on syntax tables. This is used, for example, to find the matching parenthesis in a command such as forward-sexp, and by ‘font-lock.c’ to locate quoted strings, comments, etc.

Syntax codes are implemented as bitfields in an int. Bits 0-6 contain the syntax code itself, bit 7 is a special prefix flag used for Lisp, and bits 16-23 contain comment syntax flags. From the Lisp programmer’s point of view, there are 11 flags: 2 styles X 2 characters X {start, end} flags for two-character comment delimiters, 2 style flags for one-character comment delimiters, and the prefix flag.

Internally, however, the characters used in multi-character delimiters will have non-comment-character syntax classes (e.g., the ‘/’ in C’s ‘/*’ comment-start delimiter has “punctuation” (here meaning “operator-like”) class in C modes). Thus in a mixed comment style, such as C++’s ‘//’ to end of line, is represented by giving ‘/’ the “punctuation” class and the “style b first character of start sequence” and “style b second character of start sequence” flags. The fact that class is not punctuation allows the syntax scanner to recognize that this is a multi-character delimiter. The ‘newline’ character is given (single-character) “comment-end” class and the “style b first character of end sequence” flag. The “comment-end” class allows the scanner to determine that no second character is needed to terminate the comment.

There used to be a syntax class ‘Sextword’. A character of ‘Sextword’ class is a word-constituent but a word boundary may exist between two such characters. Ken’ichi HANDA <handa@etl.go.jp> explains the purpose of the Sextword syntax category:

Japanese words are not separated by spaces, which makes finding word boundaries very difficult. Theoretically it’s impossible without using natural language processing techniques. But, by defining pseudo-words as below (much simplified for letting you understand it easily) for Japanese, we can have a convenient forward-word function for Japanese.

 
A Japanese word is a sequence of characters that consists of
zero or more Kanji characters followed by zero or more
Hiragana characters.

Then, the problem is that now we can’t say that a sequence of word-constituents makes up a word. For instance, both Hiragana “A” and Kanji “KAN” are word-constituents but the sequence of these two letters can’t be a single word.

So, we introduced Sextword for Japanese letters.

There seems to have been some controversy about this category, as it has been removed, readded, and removed again. Currently neither GNU Emacs (21.3.99) nor XEmacs (21.5.17) seems to use it.

 
casefiddle.c

This module implements various Lisp primitives for upcasing, downcasing and capitalizing strings or regions of buffers.

 
rangetab.c

This module implements the range table Lisp object type, which provides for a mapping from ranges of fixnums to arbitrary Lisp objects.

 
opaque.c’
‘opaque.h

This module implements the opaque Lisp object type, an internal-only Lisp object that encapsulates an arbitrary block of memory so that it can be managed by the Lisp allocation system. To create an opaque object, you call make_opaque(), passing a pointer to a block of memory. An object is created that is big enough to hold the memory, which is copied into the object’s storage. The object will then stick around as long as you keep pointers to it, after which it will be automatically reclaimed.

Opaque objects can also have an arbitrary mark method associated with them, in case the block of memory contains other Lisp objects that need to be marked for garbage-collection purposes. (If you need other object methods, such as a finalize method, you should just go ahead and create a new Lisp object type—it’s not hard.)

 
abbrev.c

This function provides a few primitives for doing dynamic abbreviation expansion. In XEmacs, most of the code for this has been moved into Lisp. Some C code remains for speed and because the primitive self-insert-command (which is executed for all self-inserting characters) hooks into the abbrev mechanism. (self-insert-command is itself in C only for speed.)

 
doc.c

This function provides primitives for retrieving the documentation strings of functions and variables. These documentation strings contain certain special markers that get dynamically expanded (e.g. a reverse-lookup is performed on some named functions to retrieve their current key bindings). Some documentation strings (in particular, for the built-in primitives and pre-loaded Lisp functions) are stored externally in a file ‘DOC’ in the ‘lib-src/’ directory and need to be fetched from that file. (Part of the build stage involves building this file, and another part involves constructing an index for this file and embedding it into the executable, so that the functions in ‘doc.c’ do not have to search the entire ‘DOC’ file to find the appropriate documentation string.)

 
md5.c

This function provides a Lisp primitive that implements the MD5 secure hashing scheme, used to create a large hash value of a string of data such that the data cannot be derived from the hash value. This is used for various security applications on the Internet.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.8 Modules for Interfacing with the Operating System

 
process.el’
‘process.c’
‘process.h

These modules allow XEmacs to spawn and communicate with subprocesses and network connections.

process.el’ implements (through the call-process primitive) what are called synchronous subprocesses. This means that XEmacs runs a program, waits till it’s done, and retrieves its output. A typical example might be calling the ‘ls’ program to get a directory listing.

process.c’ and ‘process.h’ implement asynchronous subprocesses. This means that XEmacs starts a program and then continues normally, not waiting for the process to finish. Data can be sent to the process or retrieved from it as it’s running. This is used for the shell command (which provides a front end onto a shell program such as ‘csh’), the mail and news readers implemented in XEmacs, etc. The result of calling start-process to start a subprocess is a process object, a particular kind of object used to communicate with the subprocess. You can send data to the process by passing the process object and the data to send-process, and you can specify what happens to data retrieved from the process by setting properties of the process object. (When the process sends data, XEmacs receives a process event, which says that there is data ready. When dispatch-event is called on this event, it reads the data from the process and does something with it, as specified by the process object’s properties. Typically, this means inserting the data into a buffer or calling a function.) Another property of the process object is called the sentinel, which is a function that is called when the process terminates.

Process objects are also used for network connections (connections to a process running on another machine). Network connections are started with open-network-stream but otherwise work just like subprocesses.

 
sysdep.c’
‘sysdep.h

These modules implement most of the low-level, messy operating-system interface code. This includes various device control (ioctl) operations for file descriptors, TTY’s, pseudo-terminals, etc. (usually this stuff is fairly system-dependent; thus the name of this module), and emulation of standard library functions and system calls on systems that don’t provide them or have broken versions.

 
sysdir.h’
‘sysfile.h’
‘sysfloat.h’
‘sysproc.h’
‘syspwd.h’
‘syssignal.h’
‘systime.h’
‘systty.h’
‘syswait.h

These header files provide consistent interfaces onto system-dependent header files and system calls. The idea is that, instead of including a standard header file like ‘<sys/param.h>’ (which may or may not exist on various systems) or having to worry about whether all system provide a particular preprocessor constant, or having to deal with the four different paradigms for manipulating signals, you just include the appropriate ‘sys*.h’ header file, which includes all the right system header files, defines and missing preprocessor constants, provides a uniform interface onto system calls, etc.

sysdir.h’ provides a uniform interface onto directory-querying functions. (In some cases, this is in conjunction with emulation functions in ‘sysdep.c’.)

sysfile.h’ includes all the necessary header files for standard system calls (e.g. read()), ensures that all necessary open() and stat() preprocessor constants are defined, and possibly (usually) substitutes sugared versions of read(), write(), etc. that automatically restart interrupted I/O operations.

sysfloat.h’ includes the necessary header files for floating-point operations.

sysproc.h’ includes the necessary header files for calling select(), fork(), execve(), socket operations, and the like, and ensures that the FD_*() macros for descriptor-set manipulations are available.

syspwd.h’ includes the necessary header files for obtaining information from ‘/etc/passwd’ (the functions are emulated under VMS).

syssignal.h’ includes the necessary header files for signal-handling and provides a uniform interface onto the different signal-handling and signal-blocking paradigms.

systime.h’ includes the necessary header files and provides uniform interfaces for retrieving the time of day, setting file access/modification times, getting the amount of time used by the XEmacs process, etc.

systty.h’ buffers against the infinitude of different ways of controlling TTY’s.

syswait.h’ provides a uniform way of retrieving the exit status from a wait()ed-on process (some systems use a union, others use an int).

 
hpplay.c’
‘libsst.c’
‘libsst.h’
‘libst.h’
‘linuxplay.c’
‘nas.c’
‘sgiplay.c’
‘sound.c’
‘sunplay.c

These files implement the ability to play various sounds on some types of computers. You have to configure your XEmacs with sound support in order to get this capability.

sound.c’ provides the generic interface. It implements various Lisp primitives and variables that let you specify which sounds should be played in certain conditions. (The conditions are identified by symbols, which are passed to ding to make a sound. Various standard functions call this function at certain times; if sound support does not exist, a simple beep results.

sgiplay.c’, ‘sunplay.c’, ‘hpplay.c’, and ‘linuxplay.c’ interface to the machine’s speaker for various different kind of machines. This is called native sound.

nas.c’ interfaces to a computer somewhere else on the network using the NAS (Network Audio Server) protocol, playing sounds on that machine. This allows you to run XEmacs on a remote machine, with its display set to your local machine, and have the sounds be made on your local machine, provided that you have a NAS server running on your local machine.

libsst.c’, ‘libsst.h’, and ‘libst.h’ provide some additional functions for playing sound on a Sun SPARC but are not currently in use.

 
tooltalk.c’
‘tooltalk.h

These two modules implement an interface to the ToolTalk protocol, which is an interprocess communication protocol implemented on some versions of Unix. ToolTalk is a high-level protocol that allows processes to register themselves as providers of particular services; other processes can then request a service without knowing or caring exactly who is providing the service. It is similar in spirit to the DDE protocol provided under Microsoft Windows. ToolTalk is a part of the new CDE (Common Desktop Environment) specification and is used to connect the parts of the SPARCWorks development environment.

 
getloadavg.c

This module provides the ability to retrieve the system’s current load average. (The way to do this is highly system-specific, unfortunately, and requires a lot of special-case code.)

 
sunpro.c

This module provides a small amount of code used internally at Sun to keep statistics on the usage of XEmacs.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.