Mercurial > hg > xemacs-beta

comparison man/internals/internals.texi @ 272:c5d627a313b1 r21-0b34

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-0b34
author cvs
date Mon, 13 Aug 2007 10:28:48 +0200
parents 8efd647ea9ca
children c42ec1d1cded
comparison
equal deleted inserted replaced
271:c7b7086b0a39 272:c5d627a313b1
982 easy upgrading of parts of a system without upgrading the rest. It 982 easy upgrading of parts of a system without upgrading the rest. It
983 would be impossible to pre-determine and pre-specify the information for 983 would be impossible to pre-determine and pre-specify the information for
984 all possible configurations. 984 all possible configurations.
985 985
986 When configure is done running, it generates @file{Makefile}s and the 986 When configure is done running, it generates @file{Makefile}s and the
987 file @file{config.h} (which describes the features of your system) from 987 file @file{src/config.h} (which describes the features of your system)
988 template files. You then run @file{make}, which compiles the auxiliary 988 from template files. You then run @file{make}, which compiles the
989 code and programs in @file{lib-src/} and @file{lwlib/} and the main 989 auxiliary code and programs in @file{lib-src/} and @file{lwlib/} and the
990 XEmacs executable in @file{src/}. The result of this is an executable 990 main XEmacs executable in @file{src/}. The result of compiling and
991 called @file{temacs}, which is @emph{not} the XEmacs executable. 991 linking is an executable called @file{temacs}, which is @emph{not} the
992 @file{temacs} by itself cannot function as an editor or even display any 992 final XEmacs executable. @file{temacs} by itself is not intended to
993 windows on the screen, and if you simply run it, it will exit 993 function as an editor or even display any windows on the screen, and if
994 immediately. The Makefile runs @file{temacs} with certain options that 994 you simply run it, it will exit immediately. The @file{Makefile} runs
995 cause it to initialize itself, read in a number of basic Lisp files, and 995 @file{temacs} with certain options that cause it to initialize itself,
996 then dump itself out into a new executable called @file{xemacs}. This 996 read in a number of basic Lisp files, and then dump itself out into a
997 new executable has been pre-initialized and contains pre-digested Lisp 997 new executable called @file{xemacs}. This new executable has been
998 code that is necessary for the editor to function (this includes most 998 pre-initialized and contains pre-digested Lisp code that is necessary
999 basic Lisp functions, e.g. @code{not}, that can be defined in terms of 999 for the editor to function (this includes most basic Lisp functions,
1000 other Lisp primitives; some initialization code that is called when 1000 e.g. @code{not}, that can be defined in terms of other Lisp primitives;
1001 certain objects, such as frames, are created; and all of the standard 1001 some initialization code that is called when certain objects, such as
1002 keybindings and code for the actions they result in). This executable, 1002 frames, are created; and all of the standard keybindings and code for
1003 @file{xemacs}, is the executable that you run to use the XEmacs editor. 1003 the actions they result in). This executable, @file{xemacs}, is the
1004 executable that you run to use the XEmacs editor.
1005
1006 Although @file{temacs} is not intended to be run as an editor, it can,
1007 by using the incantation @code{temacs -batch -l loadup.el run-temacs}.
1008 This is useful when the dumping procedure described above is broken, or
1009 when using certain program debugging tools such as Purify. These tools
1010 get mighty confused by the tricks played by the XEmacs build process,
1011 such as allocation memory in one process, and freeing it in the next.
1004 1012
1005 @node XEmacs From the Inside, The XEmacs Object System (Abstractly Speaking), XEmacs From the Perspective of Building, Top 1013 @node XEmacs From the Inside, The XEmacs Object System (Abstractly Speaking), XEmacs From the Perspective of Building, Top
1006 @chapter XEmacs From the Inside 1014 @chapter XEmacs From the Inside
1007 1015
1008 Internally, XEmacs is quite complex, and can be very confusing. To 1016 Internally, XEmacs is quite complex, and can be very confusing. To
1449 1457
1450 converts to a symbol whose name is @code{"foobar"}. This is done by 1458 converts to a symbol whose name is @code{"foobar"}. This is done by
1451 looking up the string equivalent in the global variable 1459 looking up the string equivalent in the global variable
1452 @code{obarray}, whose contents should be an obarray. If no symbol 1460 @code{obarray}, whose contents should be an obarray. If no symbol
1453 is found, a new symbol with the name @code{"foobar"} is automatically 1461 is found, a new symbol with the name @code{"foobar"} is automatically
1454 created and adding it to @code{obarray}; this process is called 1462 created and added to @code{obarray}; this process is called
1455 @dfn{interning} the symbol. 1463 @dfn{interning} the symbol.
1456 @cindex interning 1464 @cindex interning
1457 1465
1458 @example 1466 @example
1459 (foo . bar) 1467 (foo . bar)
1460 @end example 1468 @end example
1550 mark bit of the ones that are marked.) 1558 mark bit of the ones that are marked.)
1551 1559
1552 Lisp objects use the typedef @code{Lisp_Object}, but the actual C type 1560 Lisp objects use the typedef @code{Lisp_Object}, but the actual C type
1553 used for the Lisp object can vary. It can be either a simple type 1561 used for the Lisp object can vary. It can be either a simple type
1554 (@code{long} on the DEC Alpha, @code{int} on other machines) or a 1562 (@code{long} on the DEC Alpha, @code{int} on other machines) or a
1555 structure whose fields are bit fields that line up properly (actually, 1563 structure whose fields are bit fields that line up properly (actually, a
1556 it's a union of structures that's used). Generally the simple integral 1564 union of structures that's used). Generally the simple integral type is
1557 type is preferable because it ensures that the compiler will actually 1565 preferable because it ensures that the compiler will actually use a
1558 use a machine word to represent the object (some compilers will use more 1566 machine word to represent the object (some compilers will use more
1559 general and less efficient code for unions and structs even if they can 1567 general and less efficient code for unions and structs even if they can
1560 fit in a machine word). The union type, however, has the advantage of 1568 fit in a machine word). The union type, however, has the advantage of
1561 stricter type checking (if you accidentally pass an integer where a Lisp 1569 stricter type checking (if you accidentally pass an integer where a Lisp
1562 object is desired, you get a compile error), and it makes it easier to 1570 object is desired, you get a compile error), and it makes it easier to
1563 decode Lisp objects when debugging. The choice of which type to use is 1571 decode Lisp objects when debugging. The choice of which type to use is
1564 determined by the presence or absence of the preprocessor constant 1572 determined by the presence or absence of the preprocessor constant
1565 @code{NO_UNION_TYPE}. (Shouldn't it be @code{USE_UNION_TYPE}, with 1573 @code{USE_UNION_TYPE}.
1566 opposite semantics? ``Hysterical reasons'', of course.)
1567 1574
1568 @cindex record type 1575 @cindex record type
1569 Note that there are only eight types that the tag can represent, 1576 Note that there are only eight types that the tag can represent,
1570 but many more actual types than this. This is handled by having 1577 but many more actual types than this. This is handled by having
1571 one of the tag types specify a meta-type called a @dfn{record}; 1578 one of the tag types specify a meta-type called a @dfn{record};
1625 These macros are of the form @code{XSET@var{TYPE} (@var{lvalue}, @var{result})}, 1632 These macros are of the form @code{XSET@var{TYPE} (@var{lvalue}, @var{result})},
1626 i.e. they have to be a statement rather than just used in an expression. 1633 i.e. they have to be a statement rather than just used in an expression.
1627 The reason for this is that standard C doesn't let you ``construct'' a 1634 The reason for this is that standard C doesn't let you ``construct'' a
1628 structure (but GCC does). Granted, this sometimes isn't too convenient; 1635 structure (but GCC does). Granted, this sometimes isn't too convenient;
1629 for the case of integers, at least, you can use the function 1636 for the case of integers, at least, you can use the function
1630 @code{make_number()}, which constructs and @emph{returns} an integer 1637 @code{make_int()}, which constructs and @emph{returns} an integer
1631 Lisp object. Note that the @code{XSET@var{TYPE}()} macros are also 1638 Lisp object. Note that the @code{XSET@var{TYPE}()} macros are also
1632 affected by @code{ERROR_CHECK_TYPECHECK} and make sure that the 1639 affected by @code{ERROR_CHECK_TYPECHECK} and make sure that the
1633 structure is of the right type in the case of record types, where the 1640 structure is of the right type in the case of record types, where the
1634 type is contained in the structure. 1641 type is contained in the structure.
1635 1642
2308 @file{lisp.h} contains the definitions of the structures and extractor 2315 @file{lisp.h} contains the definitions of the structures and extractor
2309 and constructor macros for the basic Lisp objects and various other 2316 and constructor macros for the basic Lisp objects and various other
2310 basic definitions for the Lisp environment, as well as some 2317 basic definitions for the Lisp environment, as well as some
2311 general-purpose definitions (e.g. @code{min()} and @code{max()}). 2318 general-purpose definitions (e.g. @code{min()} and @code{max()}).
2312 @file{lisp.h} includes either @file{lisp-disunion.h} or 2319 @file{lisp.h} includes either @file{lisp-disunion.h} or
2313 @file{lisp-union.h}, depending on whether @code{NO_UNION_TYPE} is 2320 @file{lisp-union.h}, depending on whether @code{USE_UNION_TYPE} is
2314 defined. These files define the typedef of the Lisp object itself (as 2321 defined. These files define the typedef of the Lisp object itself (as
2315 described above) and the low-level macros that hide the actual 2322 described above) and the low-level macros that hide the actual
2316 implementation of the Lisp object. All extractor and constructor macros 2323 implementation of the Lisp object. All extractor and constructor macros
2317 for particular types of Lisp objects are defined in terms of these 2324 for particular types of Lisp objects are defined in terms of these
2318 low-level macros. 2325 low-level macros.
3989 internal lists and such things.) 3996 internal lists and such things.)
3990 3997
3991 Note that @code{obarray} is one of the @code{staticpro()}d things. 3998 Note that @code{obarray} is one of the @code{staticpro()}d things.
3992 Therefore, all functions and variables get marked through this. 3999 Therefore, all functions and variables get marked through this.
3993 @item 4000 @item
3994 Any shadowed bindings that are sitting on the specpdl stack. 4001 Any shadowed bindings that are sitting on the @code{specpdl} stack.
3995 @item 4002 @item
3996 Any objects sitting in currently active (Lisp) stack frames, 4003 Any objects sitting in currently active (Lisp) stack frames,
3997 catches, and condition cases. 4004 catches, and condition cases.
3998 @item 4005 @item
3999 A couple of special-case places where active objects are 4006 A couple of special-case places where active objects are
4036 4043
4037 @item 4044 @item
4038 It is actually possible for a single @code{struct gcpro} to 4045 It is actually possible for a single @code{struct gcpro} to
4039 protect a contiguous array of any number of values, rather than 4046 protect a contiguous array of any number of values, rather than
4040 just a single lvalue. To effect this, call @code{GCPRO@var{n}} as usual on 4047 just a single lvalue. To effect this, call @code{GCPRO@var{n}} as usual on
4041 the first object in the array and then set @code{gcpron.nvars}. 4048 the first object in the array and then set @code{gcpro@var{n}.nvars}.
4042 4049
4043 @item 4050 @item
4044 @strong{Strings are relocated.} What this means in practice is that the 4051 @strong{Strings are relocated.} What this means in practice is that the
4045 pointer obtained using @code{XSTRING_DATA()} is liable to change at any 4052 pointer obtained using @code{XSTRING_DATA()} is liable to change at any
4046 time, and you should never keep it around past any function call, or 4053 time, and you should never keep it around past any function call, or
5084 x1 x2 x3 ...)} is equivalent to @code{(eval (list fun (quote x1) (quote 5091 x1 x2 x3 ...)} is equivalent to @code{(eval (list fun (quote x1) (quote
5085 x2) (quote x3) ...))}. @code{Ffuncall()} contains its own code to do 5092 x2) (quote x3) ...))}. @code{Ffuncall()} contains its own code to do
5086 the evaluation, however, and is almost identical to eval. 5093 the evaluation, however, and is almost identical to eval.
5087 5094
5088 @code{Fapply()} implements Lisp @code{apply}, which is very similar to 5095 @code{Fapply()} implements Lisp @code{apply}, which is very similar to
5089 funcall except that if the last argument is a list, the result is the 5096 @code{funcall} except that if the last argument is a list, the result is the
5090 same as if each of the arguments in the list had been passed separately. 5097 same as if each of the arguments in the list had been passed separately.
5091 @code{Fapply()} does some business to expand the last argument if it's a 5098 @code{Fapply()} does some business to expand the last argument if it's a
5092 list, then calls @code{Ffuncall()} to do the work. 5099 list, then calls @code{Ffuncall()} to do the work.
5093 5100
5094 @code{apply1()}, @code{call0()}, @code{call1()}, @code{call2()}, and 5101 @code{apply1()}, @code{call0()}, @code{call1()}, @code{call2()}, and
5112 unwind-protects. @code{specpdl} holds an array of @code{struct specbinding}'s, 5119 unwind-protects. @code{specpdl} holds an array of @code{struct specbinding}'s,
5113 @code{specpdl_ptr} points to the beginning of the free bindings in the 5120 @code{specpdl_ptr} points to the beginning of the free bindings in the
5114 array, @code{specpdl_size} specifies the total number of binding slots 5121 array, @code{specpdl_size} specifies the total number of binding slots
5115 in the array, and @code{max_specpdl_size} specifies the maximum number 5122 in the array, and @code{max_specpdl_size} specifies the maximum number
5116 of bindings the array can be expanded to hold. @code{grow_specpdl()} 5123 of bindings the array can be expanded to hold. @code{grow_specpdl()}
5117 increases the size of the specpdl array, multiplying its size by 2 but 5124 increases the size of the @code{specpdl} array, multiplying its size by
5118 never exceeding max_specpdl_size (except that if this number is less 5125 2 but never exceeding @code{max_specpdl_size} (except that if this
5119 than 400, it is first set to 400). 5126 number is less than 400, it is first set to 400).
5120 5127
5121 @code{specbind()} binds a symbol to a value and is used for local 5128 @code{specbind()} binds a symbol to a value and is used for local
5122 variables and @code{let} forms. The symbol and its old value (which 5129 variables and @code{let} forms. The symbol and its old value (which
5123 might be @code{Qunbound}, indicating no prior value) are recorded in the 5130 might be @code{Qunbound}, indicating no prior value) are recorded in the
5124 specpdl array, and @code{specpdl_size} is increased by 1. 5131 specpdl array, and @code{specpdl_size} is increased by 1.
5125 5132
5126 @code{record_unwind_protect()} implements an @dfn{unwind-protect}, 5133 @code{record_unwind_protect()} implements an @dfn{unwind-protect},
5127 which, when placed around a section of code, ensures that some specified 5134 which, when placed around a section of code, ensures that some specified
5128 cleanup routine will be executed even if the code exits abnormally 5135 cleanup routine will be executed even if the code exits abnormally
5129 (e.g. through a @code{throw} or quit). @code{record_unwind_protect()} 5136 (e.g. through a @code{throw} or quit). @code{record_unwind_protect()}
5130 simply adds a new specbinding to the specpdl array and stores the 5137 simply adds a new specbinding to the @code{specpdl} array and stores the
5131 appropriate information in it. The cleanup routine can either be a C 5138 appropriate information in it. The cleanup routine can either be a C
5132 function, which is stored in the @code{func} field, or a @code{progn} 5139 function, which is stored in the @code{func} field, or a @code{progn}
5133 form, which is stored in the @code{old_value} field. 5140 form, which is stored in the @code{old_value} field.
5134 5141
5135 @code{unbind_to()} removes specbindings from the specpdl array until 5142 @code{unbind_to()} removes specbindings from the @code{specpdl} array
5136 the specified position is reached. Each specbinding can be one of three 5143 until the specified position is reached. Each specbinding can be one of
5137 types: 5144 three types:
5138 5145
5139 @enumerate 5146 @enumerate
5140 @item 5147 @item
5141 an unwind-protect with a C cleanup function (@code{func} is not 0, and 5148 an unwind-protect with a C cleanup function (@code{func} is not 0, and
5142 @code{old_value} holds an argument to be passed to the function); 5149 @code{old_value} holds an argument to be passed to the function);
5198 instance that created the catch. 5205 instance that created the catch.
5199 5206
5200 @code{internal_catch()} is fairly straightforward. It stores into the 5207 @code{internal_catch()} is fairly straightforward. It stores into the
5201 @code{struct catchtag} the tag name and the current values of 5208 @code{struct catchtag} the tag name and the current values of
5202 @code{backtrace_list}, @code{lisp_eval_depth}, @code{gcprolist}, and the 5209 @code{backtrace_list}, @code{lisp_eval_depth}, @code{gcprolist}, and the
5203 offset into the specpdl array, sets a jump point with @code{_setjmp()} 5210 offset into the @code{specpdl} array, sets a jump point with @code{_setjmp()}
5204 (storing the jump point into the @code{struct catchtag}), and calls the 5211 (storing the jump point into the @code{struct catchtag}), and calls the
5205 function. Control will return to @code{internal_catch()} either when 5212 function. Control will return to @code{internal_catch()} either when
5206 the function exits normally or through a @code{_longjmp()} to this jump 5213 the function exits normally or through a @code{_longjmp()} to this jump
5207 point. In the latter case, @code{throw} will store the value to be 5214 point. In the latter case, @code{throw} will store the value to be
5208 returned into the @code{struct catchtag} before jumping. When it's 5215 returned into the @code{struct catchtag} before jumping. When it's