-This is Info file ../../info/internals.info, produced by Makeinfo
-version 1.68 from the input file internals.texi.
+This is ../info/internals.info, produced by makeinfo version 4.0b from
+internals/internals.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
-* Internals: (internals). XEmacs Internals Manual.
+* Internals: (internals). XEmacs Internals Manual.
END-INFO-DIR-ENTRY
Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
Foundation instead of in the original English.
\1f
-File: internals.info, Node: Working With Character and Byte Positions, Next: Conversion to and from External Data, Prev: Character-Related Data Types, Up: Coding for Mule
-
-Working With Character and Byte Positions
------------------------------------------
-
- Now that we have defined the basic character-related types, we can
-look at the macros and functions designed for work with them and for
-conversion between them. Most of these macros are defined in
-`buffer.h', and we don't discuss all of them here, but only the most
-important ones. Examining the existing code is the best way to learn
-about them.
-
-`MAX_EMCHAR_LEN'
- This preprocessor constant is the maximum number of buffer bytes
- per Emacs character, i.e. the byte length of an `Emchar'. It is
- useful when allocating temporary strings to keep a known number of
- characters. For instance:
-
- {
- Charcount cclen;
- ...
- {
- /* Allocate place for CCLEN characters. */
- Bufbyte *buf = (Bufbyte *)alloca (cclen * MAX_EMCHAR_LEN);
- ...
-
- If you followed the previous section, you can guess that,
- logically, multiplying a `Charcount' value with `MAX_EMCHAR_LEN'
- produces a `Bytecount' value.
-
- In the current Mule implementation, `MAX_EMCHAR_LEN' equals 4.
- Without Mule, it is 1.
-
-`charptr_emchar'
-`set_charptr_emchar'
- The `charptr_emchar' macro takes a `Bufbyte' pointer and returns
- the `Emchar' stored at that position. If it were a function, its
- prototype would be:
-
- Emchar charptr_emchar (Bufbyte *p);
-
- `set_charptr_emchar' stores an `Emchar' to the specified byte
- position. It returns the number of bytes stored:
-
- Bytecount set_charptr_emchar (Bufbyte *p, Emchar c);
-
- It is important to note that `set_charptr_emchar' is safe only for
- appending a character at the end of a buffer, not for overwriting a
- character in the middle. This is because the width of characters
- varies, and `set_charptr_emchar' cannot resize the string if it
- writes, say, a two-byte character where a single-byte character
- used to reside.
-
- A typical use of `set_charptr_emchar' can be demonstrated by this
- example, which copies characters from buffer BUF to a temporary
- string of Bufbytes.
-
- {
- Bufpos pos;
- for (pos = beg; pos < end; pos++)
- {
- Emchar c = BUF_FETCH_CHAR (buf, pos);
- p += set_charptr_emchar (buf, c);
- }
- }
-
- Note how `set_charptr_emchar' is used to store the `Emchar' and
- increment the counter, at the same time.
-
-`INC_CHARPTR'
-`DEC_CHARPTR'
- These two macros increment and decrement a `Bufbyte' pointer,
- respectively. They will adjust the pointer by the appropriate
- number of bytes according to the byte length of the character
- stored there. Both macros assume that the memory address is
- located at the beginning of a valid character.
-
- Without Mule support, `INC_CHARPTR (p)' and `DEC_CHARPTR (p)'
- simply expand to `p++' and `p--', respectively.
-
-`bytecount_to_charcount'
- Given a pointer to a text string and a length in bytes, return the
- equivalent length in characters.
-
- Charcount bytecount_to_charcount (Bufbyte *p, Bytecount bc);
-
-`charcount_to_bytecount'
- Given a pointer to a text string and a length in characters,
- return the equivalent length in bytes.
-
- Bytecount charcount_to_bytecount (Bufbyte *p, Charcount cc);
-
-`charptr_n_addr'
- Return a pointer to the beginning of the character offset CC (in
- characters) from P.
-
- Bufbyte *charptr_n_addr (Bufbyte *p, Charcount cc);
-
-\1f
File: internals.info, Node: Conversion to and from External Data, Next: General Guidelines for Writing Mule-Aware Code, Prev: Working With Character and Byte Positions, Up: Coding for Mule
Conversion to and from External Data
The interface to conversion between the internal and external
representations of text are the numerous conversion macros defined in
-`buffer.h'. Before looking at them, we'll look at the external formats
-supported by these macros.
-
- Currently meaningful formats are `FORMAT_BINARY', `FORMAT_FILENAME',
-`FORMAT_OS', and `FORMAT_CTEXT'. Here is a description of these.
-
-`FORMAT_BINARY'
- Binary format. This is the simplest format and is what we use in
- the absence of a more appropriate format. This converts according
- to the `binary' coding system:
-
- a. On input, bytes 0-255 are converted into characters 0-255.
+`buffer.h'. There used to be a fixed set of external formats supported
+by these macros, but now any coding system can be used with these
+macros. The coding system alias mechanism is used to create the
+following logical coding systems, which replace the fixed external
+formats. The (dontusethis-set-symbol-value-handler) mechanism was
+enhanced to make this possible (more work on that is needed - like
+remove the `dontusethis-' prefix).
+
+`Qbinary'
+ This is the simplest format and is what we use in the absence of a
+ more appropriate format. This converts according to the `binary'
+ coding system:
+
+ a. On input, bytes 0-255 are converted into (implicitly Latin-1)
+ characters 0-255. A non-Mule xemacs doesn't really know about
+ different character sets and the fonts to display them, so
+ the bytes can be treated as text in different 1-byte
+ encodings by simply setting the appropriate fonts. So in a
+ sense, non-Mule xemacs is a multi-lingual editor if, for
+ example, different fonts are used to display text in
+ different buffers, faces, or windows. The specifier
+ mechanism gives the user complete control over this kind of
+ behavior.
b. On output, characters 0-255 are converted into bytes 0-255
- and other characters are converted into `X'.
+ and other characters are converted into `~'.
-`FORMAT_FILENAME'
- Format used for filenames. In the original Mule, this is
- user-definable with the `pathname-coding-system' variable. For
- the moment, we just use the `binary' coding system.
+`Qfile_name'
+ Format used for filenames. This is user-definable via either the
+ `file-name-coding-system' or `pathname-coding-system' (now
+ obsolete) variables.
-`FORMAT_OS'
+`Qnative'
Format used for the external Unix environment--`argv[]', stuff
from `getenv()', stuff from the `/etc/passwd' file, etc.
+ Currently this is the same as Qfile_name. The two should be
+ distinguished for clarity and possible future separation.
+
+`Qctext'
+ Compound-text format. This is the standard X11 format used for
+ data stored in properties, selections, and the like. This is an
+ 8-bit no-lock-shift ISO2022 coding system. This is a real coding
+ system, unlike Qfile_name, which is user-definable.
+
+ There are two fundamental macros to convert between external and
+internal format.
+
+ `TO_INTERNAL_FORMAT' converts external data to internal format, and
+`TO_EXTERNAL_FORMAT' converts the other way around. The arguments each
+of these receives are a source type, a source, a sink type, a sink, and
+a coding system (or a symbol naming a coding system).
+
+ A typical call looks like
+ TO_EXTERNAL_FORMAT (LISP_STRING, str, C_STRING_MALLOC, ptr, Qfile_name);
+
+ which means that the contents of the lisp string `str' are written
+to a malloc'ed memory area which will be pointed to by `ptr', after the
+function returns. The conversion will be done using the `file-name'
+coding system, which will be controlled by the user indirectly by
+setting or binding the variable `file-name-coding-system'.
+
+ Some sources and sinks require two C variables to specify. We use
+some preprocessor magic to allow different source and sink types, and
+even different numbers of arguments to specify different types of
+sources and sinks.
+
+ So we can have a call that looks like
+ TO_INTERNAL_FORMAT (DATA, (ptr, len),
+ MALLOC, (ptr, len),
+ coding_system);
+
+ The parenthesized argument pairs are required to make the
+preprocessor magic work.
+
+ Here are the different source and sink types:
+
+``DATA, (ptr, len),''
+ input data is a fixed buffer of size LEN at address PTR
+
+``ALLOCA, (ptr, len),''
+ output data is placed in an alloca()ed buffer of size LEN pointed
+ to by PTR
+
+``MALLOC, (ptr, len),''
+ output data is in a malloc()ed buffer of size LEN pointed to by PTR
+
+``C_STRING_ALLOCA, ptr,''
+ equivalent to `ALLOCA (ptr, len_ignored)' on output.
+
+``C_STRING_MALLOC, ptr,''
+ equivalent to `MALLOC (ptr, len_ignored)' on output
+
+``C_STRING, ptr,''
+ equivalent to `DATA, (ptr, strlen (ptr) + 1)' on input
+
+``LISP_STRING, string,''
+ input or output is a Lisp_Object of type string
+
+``LISP_BUFFER, buffer,''
+ output is written to `(point)' in lisp buffer BUFFER
+
+``LISP_LSTREAM, lstream,''
+ input or output is a Lisp_Object of type lstream
+
+``LISP_OPAQUE, object,''
+ input or output is a Lisp_Object of type opaque
- Perhaps should be the same as FORMAT_FILENAME.
-
-`FORMAT_CTEXT'
- Compound-text format. This is the standard X format used for data
- stored in properties, selections, and the like. This is an 8-bit
- no-lock-shift ISO2022 coding system.
-
- The macros to convert between these formats and the internal format,
-and vice versa, follow.
-
-`GET_CHARPTR_INT_DATA_ALLOCA'
-`GET_CHARPTR_EXT_DATA_ALLOCA'
- These two are the most basic conversion macros.
- `GET_CHARPTR_INT_DATA_ALLOCA' converts external data to internal
- format, and `GET_CHARPTR_EXT_DATA_ALLOCA' converts the other way
- around. The arguments each of these receives are PTR (pointer to
- the text in external format), LEN (length of texts in bytes), FMT
- (format of the external text), PTR_OUT (lvalue to which new text
- should be copied), and LEN_OUT (lvalue which will be assigned the
- length of the internal text in bytes). The resulting text is
- stored to a stack-allocated buffer. If the text doesn't need
- changing, these macros will do nothing, except for setting LEN_OUT.
-
- The macros above take many arguments which makes them unwieldy.
- For this reason, a number of convenience macros are defined with
- obvious functionality, but accepting less arguments. The general
- rule is that macros with `INT' in their name convert text to
- internal Emacs representation, whereas the `EXT' macros convert to
- external representation.
-
-`GET_C_CHARPTR_INT_DATA_ALLOCA'
-`GET_C_CHARPTR_EXT_DATA_ALLOCA'
- As their names imply, these macros work on C char pointers, which
- are zero-terminated, and thus do not need LEN or LEN_OUT
- parameters.
-
-`GET_STRING_EXT_DATA_ALLOCA'
-`GET_C_STRING_EXT_DATA_ALLOCA'
- These two macros convert a Lisp string into an external
- representation. The difference between them is that
- `GET_STRING_EXT_DATA_ALLOCA' stores its output to a generic
- string, providing LEN_OUT, the length of the resulting external
- string. On the other hand, `GET_C_STRING_EXT_DATA_ALLOCA' assumes
- that the caller will be satisfied with output string being
- zero-terminated.
-
- Note that for Lisp strings only one conversion direction makes
- sense.
-
-`GET_C_CHARPTR_EXT_BINARY_DATA_ALLOCA'
-`GET_CHARPTR_EXT_BINARY_DATA_ALLOCA'
-`GET_STRING_BINARY_DATA_ALLOCA'
-`GET_C_STRING_BINARY_DATA_ALLOCA'
-`GET_C_CHARPTR_EXT_FILENAME_DATA_ALLOCA'
-`...'
- These macros convert internal text to a specific external
- representation, with the external format being encoded into the
- name of the macro. Note that the `GET_STRING_...' and
- `GET_C_STRING...' macros lack the `EXT' tag, because they only
- make sense in that direction.
-
-`GET_C_CHARPTR_INT_BINARY_DATA_ALLOCA'
-`GET_CHARPTR_INT_BINARY_DATA_ALLOCA'
-`GET_C_CHARPTR_INT_FILENAME_DATA_ALLOCA'
-`...'
- These macros convert external text of a specific format to its
- internal representation, with the external format being incoded
- into the name of the macro.
+ Often, the data is being converted to a '\0'-byte-terminated string,
+which is the format required by many external system C APIs. For these
+purposes, a source type of `C_STRING' or a sink type of
+`C_STRING_ALLOCA' or `C_STRING_MALLOC' is appropriate. Otherwise, we
+should try to keep XEmacs '\0'-byte-clean, which means using (ptr, len)
+pairs.
+
+ The sinks to be specified must be lvalues, unless they are the lisp
+object types `LISP_LSTREAM' or `LISP_BUFFER'.
+
+ For the sink types `ALLOCA' and `C_STRING_ALLOCA', the resulting
+text is stored in a stack-allocated buffer, which is automatically
+freed on returning from the function. However, the sink types `MALLOC'
+and `C_STRING_MALLOC' return `xmalloc()'ed memory. The caller is
+responsible for freeing this memory using `xfree()'.
+
+ Note that it doesn't make sense for `LISP_STRING' to be a source for
+`TO_INTERNAL_FORMAT' or a sink for `TO_EXTERNAL_FORMAT'. You'll get an
+assertion failure if you try.
\1f
File: internals.info, Node: General Guidelines for Writing Mule-Aware Code, Next: An Example of Mule-Aware Code, Prev: Conversion to and from External Data, Up: Coding for Mule
This section contains some general guidance on how to write
Mule-aware code, as well as some pitfalls you should avoid.
-*Never use `char' and `char *'.*
+_Never use `char' and `char *'._
In XEmacs, the use of `char' and `char *' is almost always a
mistake. If you want to manipulate an Emacs character from "C",
use `Emchar'. If you want to examine a specific octet in the
pointer to move through the internal text, use `Bufbyte *'. Also
note that you almost certainly do not need `Emchar *'.
-*Be careful not to confuse `Charcount', `Bytecount', and `Bufpos'.*
+_Be careful not to confuse `Charcount', `Bytecount', and `Bufpos'._
The whole point of using different types is to avoid confusion
about the use of certain variables. Lest this effect be
nullified, you need to be careful about using the right types.
-*Always convert external data*
+_Always convert external data_
It is extremely important to always convert external data, because
XEmacs can crash if unexpected 8bit sequences are copied to its
internal buffers literally.
This means that when a system function, such as `readdir', returns
- a string, you need to convert it using one of the conversion macros
- described in the previous chapter, before passing it further to
- Lisp. In the case of `readdir', you would use the
- `GET_C_CHARPTR_INT_FILENAME_DATA_ALLOCA' macro.
+ a string, you may need to convert it using one of the conversion
+ macros described in the previous chapter, before passing it
+ further to Lisp.
+
+ Actually, most of the basic system functions that accept
+ '\0'-terminated string arguments, like `stat()' and `open()', have
+ been *encapsulated* so that they are they `always' do internal to
+ external conversion themselves. This means you must pass
+ internally encoded data, typically the `XSTRING_DATA' of a
+ Lisp_String to these functions. This is actually a design bug,
+ since it unexpectedly changes the semantics of the system
+ functions. A better design would be to provide separate versions
+ of these system functions that accepted Lisp_Objects which were
+ lisp strings in place of their current `char *' arguments.
+
+ int stat_lisp (Lisp_Object path, struct stat *buf); /* Implement me */
Also note that many internal functions, such as `make_string',
accept Bufbytes, which removes the need for them to convert the
An Example of Mule-Aware Code
-----------------------------
- As an example of Mule-aware code, we shall will analyze the `string'
+ As an example of Mule-aware code, we will analyze the `string'
function, which conses up a Lisp string from the character arguments it
receives. Here is the definition, pasted from `alloc.c':
Techniques for XEmacs Developers
================================
- To make a quantified XEmacs, do: `make quantmacs'.
+ To make a purified XEmacs, do: `make puremacs'. To make a
+quantified XEmacs, do: `make quantmacs'.
- You simply can't dump Quantified and Purified images. Run the image
-like so: `quantmacs -batch -l loadup.el run-temacs XEMACS-ARGS...'.
+ You simply can't dump Quantified and Purified images (unless using
+the portable dumper). Purify gets confused when xemacs frees memory in
+one process that was allocated in a _different_ process on a different
+machine!. Run it like so:
+ temacs -batch -l loadup.el run-temacs XEMACS-ARGS...
Before you go through the trouble, are you compiling with all
-debugging and error-checking off? If not try that first. Be warned
+debugging and error-checking off? If not, try that first. Be warned
that while Quantify is directly responsible for quite a few
optimizations which have been made to XEmacs, doing a run which
generates results which can be acted upon is not necessarily a trivial
Function calls in elisp are especially expensive. Iterating over a
long list is going to be 30 times faster implemented in C than in Elisp.
- To get started debugging XEmacs, take a look at the `gdbinit' and
-`dbxrc' files in the `src' directory. *Note Q2.1.15 - How to Debug an
-XEmacs problem with a debugger: (xemacs-faq)Q2.1.15 - How to Debug an
-XEmacs problem with a debugger.
+ Heavily used small code fragments need to be fast. The traditional
+way to implement such code fragments in C is with macros. But macros
+in C are known to be broken.
+
+ Macro arguments that are repeatedly evaluated may suffer from
+repeated side effects or suboptimal performance.
+
+ Variable names used in macros may collide with caller's variables,
+causing (at least) unwanted compiler warnings.
+
+ In order to solve these problems, and maintain statement semantics,
+one should use the `do { ... } while (0)' trick while trying to
+reference macro arguments exactly once using local variables.
+
+ Let's take a look at this poor macro definition:
+
+ #define MARK_OBJECT(obj) \
+ if (!marked_p (obj)) mark_object (obj), did_mark = 1
+
+ This macro evaluates its argument twice, and also fails if used like
+this:
+ if (flag) MARK_OBJECT (obj); else do_something();
+
+ A much better definition is
+
+ #define MARK_OBJECT(obj) do { \
+ Lisp_Object mo_obj = (obj); \
+ if (!marked_p (mo_obj)) \
+ { \
+ mark_object (mo_obj); \
+ did_mark = 1; \
+ } \
+ } while (0)
+
+ Notice the elimination of double evaluation by using the local
+variable with the obscure name. Writing safe and efficient macros
+requires great care. The one problem with macros that cannot be
+portably worked around is, since a C block has no value, a macro used
+as an expression rather than a statement cannot use the techniques just
+described to avoid multiple evaluation.
+
+ In most cases where a macro has function semantics, an inline
+function is a better implementation technique. Modern compiler
+optimizers tend to inline functions even if they have no `inline'
+keyword, and configure magic ensures that the `inline' keyword can be
+safely used as an additional compiler hint. Inline functions used in a
+single .c files are easy. The function must already be defined to be
+`static'. Just add another `inline' keyword to the definition.
+
+ inline static int
+ heavily_used_small_function (int arg)
+ {
+ ...
+ }
+
+ Inline functions in header files are trickier, because we would like
+to make the following optimization if the function is _not_ inlined
+(for example, because we're compiling for debugging). We would like the
+function to be defined externally exactly once, and each calling
+translation unit would create an external reference to the function,
+instead of including a definition of the inline function in the object
+code of every translation unit that uses it. This optimization is
+currently only available for gcc. But you don't have to worry about the
+trickiness; just define your inline functions in header files using this
+pattern:
+
+ INLINE_HEADER int
+ i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg);
+ INLINE_HEADER int
+ i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg)
+ {
+ ...
+ }
+
+ The declaration right before the definition is to prevent warnings
+when compiling with `gcc -Wmissing-declarations'. I consider issuing
+this warning for inline functions a gcc bug, but the gcc maintainers
+disagree.
+
+ Every header which contains inline functions, either directly by
+using `INLINE_HEADER' or indirectly by using `DECLARE_LRECORD' must be
+added to `inline.c''s includes to make the optimization described above
+work. (Optimization note: if all INLINE_HEADER functions are in fact
+inlined in all translation units, then the linker can just discard
+`inline.o', since it contains only unreferenced code).
+
+ To get started debugging XEmacs, take a look at the `.gdbinit' and
+`.dbxrc' files in the `src' directory. See the section in the XEmacs
+FAQ on How to Debug an XEmacs problem with a debugger.
After making source code changes, run `make check' to ensure that
-you haven't introduced any regressions. If you're feeling ambitious,
-you can try to improve the test suite in `tests/automated'.
+you haven't introduced any regressions. If you want to make xemacs more
+reliable, please improve the test suite in `tests/automated'.
+
+ Did you make sure you didn't introduce any new compiler warnings?
+
+ Before submitting a patch, please try compiling at least once with
+
+ configure --with-mule --with-union-type --error-checking=all
Here are things to know when you create a new source file:
<...>' syntax, not the `#include "..."' syntax. The generated
headers are:
- `config.h puresize-adjust.h sheap-adjust.h paths.h Emacs.ad.h'
+ `config.h sheap-adjust.h paths.h Emacs.ad.h'
The basic rule is that you should assume builds using `--srcdir'
and the `#include <...>' syntax needs to be used when the
to-be-included generated file is in a potentially different
- directory *at compile time*. The non-obvious C rule is that
- `#include "..."' means to search for the included file in the
- same directory as the including file, *not* in the current
- directory.
+ directory _at compile time_. The non-obvious C rule is that
+ `#include "..."' means to search for the included file in the same
+ directory as the including file, _not_ in the current directory.
- * Header files should *not* include `<config.h>' and `"lisp.h"'. It
+ * Header files should _not_ include `<config.h>' and `"lisp.h"'. It
is the responsibility of the `.c' files that use it to do so.
- * If the header uses `INLINE', either directly or through
- `DECLARE_LRECORD', then it must be added to `inline.c''s includes.
- * Try compiling at least once with
+ Here is a checklist of things to do when creating a new lisp object
+type named FOO:
+
+ 1. create FOO.h
+
+ 2. create FOO.c
+
+ 3. add definitions of `syms_of_FOO', etc. to `FOO.c'
+
+ 4. add declarations of `syms_of_FOO', etc. to `symsinit.h'
- gcc --with-mule --with-union-type --error-checking=all
+ 5. add calls to `syms_of_FOO', etc. to `emacs.c'
- * Did I mention that you should run the test suite?
- make check
+ 6. add definitions of macros like `CHECK_FOO' and `FOOP' to `FOO.h'
+
+ 7. add the new type index to `enum lrecord_type'
+
+ 8. add a DEFINE_LRECORD_IMPLEMENTATION call to `FOO.c'
+
+ 9. add an INIT_LRECORD_IMPLEMENTATION call to `syms_of_FOO.c'
\1f
File: internals.info, Node: A Summary of the Various XEmacs Modules, Next: Allocation of Objects in XEmacs Lisp, Prev: Rules When Writing New C Code, Up: Top
* Modules for Internationalization::
\1f
-File: internals.info, Node: Low-Level Modules, Next: Basic Lisp Modules, Up: A Summary of the Various XEmacs Modules
+File: internals.info, Node: Low-Level Modules, Next: Basic Lisp Modules, Prev: A Summary of the Various XEmacs Modules, Up: A Summary of the Various XEmacs Modules
Low-Level Modules
=================
of the process.) Only one of these modules is actually used; this is
chosen by `configure'.
- crt0.c
+ ecrt0.c
lastfile.c
pre-crt0.c
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
+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
instead the simpler `assert()' macro is used along with the various
checks provided by the `--error-check-*' configuration options.
- prefix-args.c
-
- This is actually the source for a small, self-contained program used
-during building.
-
universe.h
This is not currently used.
Basic Lisp Modules
==================
- emacsfns.h
lisp-disunion.h
lisp-union.h
lisp.h
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.
+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
All initialization functions are prototyped in `symsinit.h'.
alloc.c
- pure.c
- puresize.h
The large module `alloc.c' implements all of the basic allocation and
garbage collection for Lisp objects. The most commonly used Lisp
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
+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
subtypes in the subsystem; this provides a great deal of robustness to
the XEmacs code.
- `pure.c' contains the declaration of the "purespace" array. Pure
-space is a hack used to place some constant Lisp data into the code
-segment of the XEmacs executable, even though the data needs to be
-initialized through function calls. (See above in section VIII for more
-info about this.) During startup, certain sorts of data is
-automatically copied into pure space, and other data is copied manually
-in some of the basic Lisp files by calling the function `purecopy',
-which copies the object if possible (this only works in temacs, of
-course) and returns the new object. In particular, while temacs is
-executing, the Lisp reader automatically copies all compiled-function
-objects that it reads into pure space. Since compiled-function objects
-are large, are never modified, and typically comprise the majority of
-the contents of a compiled-Lisp file, this works well. While XEmacs is
-running, any attempt to modify an object that resides in pure space
-causes an error. Objects in pure space are never garbage collected -
-almost all of the time, they're intended to be permanent, and in any
-case you can't write into pure space to set the mark bits.
-
- `puresize.h' contains the declaration of the size of the pure space
-array. This depends on the optional features that are compiled in, any
-extra purespace requested by the user at compile time, and certain other
-factors (e.g. 64-bit machines need more pure space because their Lisp
-objects are larger). The smallest size that suffices should be used, so
-that there's no wasted space. If there's not enough pure space, you
-will get an error during the build process, specifying how much more
-pure space is needed.
-
eval.c
backtrace.h
primitives and other special forms 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'
+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
`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
+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
`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.
+structures. Note that the byte-code _compiler_ is written in Lisp.
\1f
File: internals.info, Node: Modules for Standard Editing Operations, Next: Editor-Level Control Flow Modules, Prev: Basic Lisp Modules, Up: A Summary of the Various XEmacs Modules
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
+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.
=================================
event-Xt.c
+ event-msw.c
event-stream.c
event-tty.c
+ events-mod.h
+ gpmevent.c
+ gpmevent.h
events.c
events.h
Note that the choice of whether to use `event-Xt.c' or `event-tty.c'
is made at compile time! Or at the very latest, it is made at startup
-time. `event-Xt.c' handles events for *both* X and TTY frames;
+time. `event-Xt.c' handles events for _both_ X and TTY frames;
`event-tty.c' is only used when X support is not compiled into XEmacs.
The reason for this is that there is only one event loop in XEmacs:
thus, it needs to be able to receive events from all different kinds of
"execute" those events; `dispatch-event' looks up events in the
relevant keymaps.)
- keyboard.c
+ cmdloop.c
- `keyboard.c' contains functions that implement the actual editor
-command loop - i.e. the event loop that cyclically retrieves and
+ `cmdloop.c' contains functions that implement the actual editor
+command loop--i.e. the event loop that cyclically retrieves and
dispatches events. This code is also rather tricky, just like
`event-stream.c'.
Modules for the Basic Displayable Lisp Objects
==============================================
- device-ns.h
- device-stream.c
- device-stream.h
+ console-msw.c
+ console-msw.h
+ console-stream.c
+ console-stream.h
+ console-tty.c
+ console-tty.h
+ console-x.c
+ console-x.h
+ console.c
+ console.h
+
+ These modules implement the "console" Lisp object type. A console
+contains multiple display devices, but only one keyboard and mouse.
+Most of the time, a console will contain exactly one device.
+
+ Consoles are the top of a lisp object inclusion hierarchy. Consoles
+contain devices, which contain frames, which contain windows.
+
+ device-msw.c
device-tty.c
- device-tty.h
device-x.c
- device-x.h
device.c
device.h
The reason for this is that all of these subsystems have the same
subtypes (X, TTY, NeXTstep, Microsoft Windows, etc.) as devices do.
- frame-ns.h
+ frame-msw.c
frame-tty.c
frame-x.c
- frame-x.h
frame.c
frame.h
faces.h
bitmaps.h
- glyphs-ns.h
+ glyphs-eimage.c
+ glyphs-msw.c
+ glyphs-msw.h
+ glyphs-widget.c
glyphs-x.c
glyphs-x.h
glyphs.c
glyphs.h
- objects-ns.h
+ objects-msw.c
+ objects-msw.h
objects-tty.c
objects-tty.h
objects-x.c
objects.c
objects.h
+ menubar-msw.c
+ menubar-msw.h
menubar-x.c
menubar.c
+ menubar.h
+ scrollbar-msw.c
+ scrollbar-msw.h
scrollbar-x.c
scrollbar-x.h
scrollbar.c
scrollbar.h
+ toolbar-msw.c
toolbar-x.c
toolbar.c
toolbar.h
font-lock.c
- This file provides C support for syntax highlighting - i.e.
+ This file provides C support for syntax highlighting--i.e.
highlighting different syntactic constructs of a source file in
different colors, for easy reading. The C support is provided so that
this is fast.
gifalloc.c
These modules decode GIF-format image files, for use with glyphs.
+These files were removed due to Unisys patent infringement concerns.
\1f
File: internals.info, Node: Modules for the Redisplay Mechanism, Next: Modules for Interfacing with the File System, Prev: Modules for other Display-Related Lisp Objects, Up: A Summary of the Various XEmacs Modules
===================================
redisplay-output.c
+ redisplay-msw.c
redisplay-tty.c
redisplay-x.c
redisplay.c
projects / chise / xemacs-chise.git- / blobdiff