Mercurial > hg > xemacs-beta
annotate man/emodules.texi @ 5167:e374ea766cc1
clean up, rearrange allocation statistics code
-------------------- ChangeLog entries follow: --------------------
src/ChangeLog addition:
2010-03-21 Ben Wing <ben@xemacs.org>
* alloc.c:
* alloc.c (assert_proper_sizing):
* alloc.c (c_readonly):
* alloc.c (malloced_storage_size):
* alloc.c (fixed_type_block_overhead):
* alloc.c (lisp_object_storage_size):
* alloc.c (inc_lrecord_stats):
* alloc.c (dec_lrecord_stats):
* alloc.c (pluralize_word):
* alloc.c (object_memory_usage_stats):
* alloc.c (Fobject_memory_usage):
* alloc.c (compute_memusage_stats_length):
* alloc.c (disksave_object_finalization_1):
* alloc.c (Fgarbage_collect):
* mc-alloc.c:
* mc-alloc.c (mc_alloced_storage_size):
* mc-alloc.h:
No functionality change here. Collect the allocations-statistics
code that was scattered throughout alloc.c into one place. Add
remaining section headings so that all sections have headings
clearly identifying the start of the section and its purpose.
Expose mc_alloced_storage_size() even when not MEMORY_USAGE_STATS;
this fixes build problems and is related to the export of
lisp_object_storage_size() and malloced_storage_size() when
non-MEMORY_USAGE_STATS in the previous change set.
author | Ben Wing <ben@xemacs.org> |
---|---|
date | Sun, 21 Mar 2010 04:41:49 -0500 |
parents | bb6a375da086 |
children |
rev | line source |
---|---|
428 | 1 \input texinfo @c -*-texinfo-*- |
2 | |
3 @c %**start of header | |
4 @setfilename ../info/emodules.info | |
5 @settitle Extending Emacs using C Modules | |
721 | 6 @direntry |
7 * Emodules: (emodules). XEmacs dynamically loadable module support. | |
8 @end direntry | |
9 @c footnotestyle separate | |
10 @c paragraphindent 2 | |
428 | 11 @c %**end of header |
12 | |
13 @c | |
14 @c Use some macros so that we can format for either XEmacs | |
15 @c or (shudder) GNU Emacs. | |
16 @c | |
17 | |
18 @ifset XEMACS | |
19 @set emacs XEmacs | |
20 @clear EMACS | |
21 @set HAVE-EMACS | |
22 @end ifset | |
23 | |
24 @ifset EMACS | |
25 @set emacs Emacs | |
26 @clear XEMACS | |
27 @set HAVE-EMACS | |
28 @end ifset | |
29 | |
30 @ifclear HAVE-EMACS | |
31 @set XEMACS | |
32 @set emacs XEmacs | |
33 @end ifclear | |
34 | |
5007
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
35 @c TODO: Merge the info-only and TeX-only license text, since they are |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
36 @c identical. |
428 | 37 @ifinfo |
38 This file documents the module loading technology of @value{emacs}. | |
39 | |
40 Copyright @copyright{} 1998 J. Kean Johnston. | |
41 | |
42 Permission is granted to make and distribute verbatim copies of this | |
43 manual provided the copyright notice and this permission notice are | |
44 preserved on all copies. | |
45 | |
5007
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
46 This file is part of XEmacs. |
428 | 47 |
5007
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
48 XEmacs is free software; you can redistribute it and/or modify it |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
49 under the terms of the GNU General Public License as published by the |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
50 Free Software Foundation; either version 2, or (at your option) any |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
51 later version. |
428 | 52 |
5007
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
53 XEmacs is distributed in the hope that it will be useful, but WITHOUT |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
54 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
55 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
56 for more details. |
428 | 57 |
5007
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
58 You should have received a copy of the GNU General Public License |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
59 along with XEmacs; see the file COPYING. If not, write to |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
60 the Free Software Foundation, Inc., 51 Franklin Street - Fifth Floor, |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
61 Boston, MA 02110-1301, USA. |
428 | 62 @end ifinfo |
63 | |
64 @c Combine indices. | |
65 @syncodeindex fn cp | |
66 @syncodeindex vr cp | |
67 @syncodeindex ky cp | |
68 @syncodeindex pg cp | |
69 @syncodeindex tp cp | |
70 | |
71 @setchapternewpage odd | |
72 @finalout | |
73 | |
74 @titlepage | |
75 @title Extending @value{emacs} using C and C++ | |
76 @subtitle Version 1.0, September 1998 | |
77 | |
78 @author J. Kean Johnston | |
79 @page | |
80 @vskip 0pt plus 1fill | |
81 | |
82 @noindent | |
83 Copyright @copyright{} 1998 J. Kean Johnston. @* | |
84 | |
85 @sp 2 | |
86 Version 1.0 @* | |
87 September, 1998.@* | |
88 | |
5007
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
89 This file is part of XEmacs. |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
90 |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
91 XEmacs is free software; you can redistribute it and/or modify it |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
92 under the terms of the GNU General Public License as published by the |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
93 Free Software Foundation; either version 2, or (at your option) any |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
94 later version. |
428 | 95 |
5007
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
96 XEmacs is distributed in the hope that it will be useful, but WITHOUT |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
97 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
98 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
99 for more details. |
428 | 100 |
5007
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
101 You should have received a copy of the GNU General Public License |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
102 along with XEmacs; see the file COPYING. If not, write to |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
103 the Free Software Foundation, Inc., 51 Franklin Street - Fifth Floor, |
bb6a375da086
Relicense J. Kean Johnston's emodules.texi as GPL v2 or later. See
Jerry James <james@xemacs.org>
parents:
4953
diff
changeset
|
104 Boston, MA 02110-1301, USA. |
428 | 105 @end titlepage |
106 @page | |
107 | |
108 @ifinfo | |
109 @node Top, Introduction, (dir), (dir) | |
721 | 110 This Info file contains v1.0 of the @value{emacs} dynamically loadable |
111 module support documentation. | |
428 | 112 @menu |
113 * Introduction:: Introducing Emacs Modules | |
442 | 114 * Anatomy of a Module:: Basic module layout and technology |
428 | 115 * Using ellcc:: How to use the module compiler |
2972 | 116 * Distribution with XEmacs:: Adding your module to the distribution |
428 | 117 * Defining Functions:: Creating new Lisp primitives |
118 * Defining Variables:: Creating new Lisp variables | |
119 * Index:: Concept Index | |
120 | |
121 --- The Detailed Node Listing --- | |
122 | |
442 | 123 Anatomy of a Module |
428 | 124 |
125 * Required Header File:: Always include <emodules.h> | |
126 * Required Functions:: Functions you must always provide | |
127 * Required Variables:: Variables whose values you must provide | |
442 | 128 * Loading other Modules:: How to load dependent modules |
428 | 129 |
130 Using @code{ellcc} | |
131 | |
132 * Compile Mode:: Compiling modules using ellcc | |
133 * Initialization Mode:: Generating documentation and variables | |
134 * Link Mode:: Creating the final loadable module | |
135 * Other ellcc options:: Other useful options | |
136 * Environment Variables:: How to control ellcc | |
137 | |
138 Defining Functions | |
139 | |
140 * Using DEFUN:: Using the DEFUN macro to define functions | |
141 * Declaring Functions:: Declaring functions to the Lisp reader | |
142 @end menu | |
143 | |
144 @end ifinfo | |
145 | |
442 | 146 @node Introduction, Anatomy of a Module, Top, Top |
428 | 147 @chapter Introduction |
148 | |
149 @value{emacs} is a powerful, extensible editor. The traditional way of | |
150 extending the functionality of @value{emacs} is to use its built-in Lisp | |
151 language (called Emacs Lisp, or Elisp for short). However, while Elisp | |
152 is a full programming language and capable of extending @value{emacs} in more | |
153 ways than you can imagine, it does have its short-comings. | |
154 | |
155 Firstly, Elisp is an interpreted language, and this has serious speed | |
156 implications. Like all other interpreted languages (like Java), Elisp | |
157 is often suitable only for certain types of application or extension. | |
440 | 158 So although Elisp is a general purpose language, and very high level, |
442 | 159 there are times when it is desirable to descend to a lower level compiled |
428 | 160 language for speed purposes. |
161 | |
162 Secondly, Elisp (or Lisp in general) is not a very common language any | |
163 more, except for certain circles in the computer industry. C is a far | |
442 | 164 more commonly known language, and because it is compiled, more suited to |
428 | 165 a wider range of applications, especially those that require low level |
166 access to a system or need to be as quick as possible. | |
167 | |
168 @cindex Emacs Modules | |
169 @cindex DLL | |
170 @cindex DSO | |
171 @cindex shared object | |
721 | 172 This manual describes a new way of extending @value{emacs}, by using |
173 dynamically loadable modules (also known as dynamically loadable | |
174 libraries (DLLs), dynamic shared objects (DSOs) or just simply shared | |
175 objects), which can be written in C or C++ and loaded into @value{emacs} | |
176 at any time. I sometimes refer to this technology as @dfn{CEmacs}, | |
177 which is short for @dfn{C Extensible Emacs}. | |
428 | 178 |
179 @value{emacs} modules are configured into and installed with @value{emacs} by | |
180 default on all systems that support loading of shared objects. From a | |
181 users perspective, the internals of @value{emacs} modules are irrelevant. | |
182 All a user will ever need to know about shared objects is the name of | |
183 the shared object when they want to load a given module. From a | |
184 developers perspective though, a lot more is provided. | |
185 | |
186 @itemize @bullet | |
187 @item | |
188 @pindex ellcc | |
189 @cindex compiler | |
190 @cindex linker | |
191 Of primary interest is the @code{ellcc} program. This program is | |
192 created during compile time, and is intended to abstract compiler | |
193 specific characteristics from the developer. This program is called to | |
194 compile and link all objects that will make up the final shared object, | |
195 and accepts all common C compiler flags. @code{ellcc} also sets up the | |
196 correct environment for compiling modules by enabling any special | |
442 | 197 compiler modes (such as PIC mode), setting the correct include paths for |
428 | 198 the location of @value{emacs} internal header files etc. The program will also |
199 invoke the linker correctly to created the final shared object which is | |
200 loaded into @value{emacs}. | |
201 | |
202 @item | |
203 @cindex header files | |
204 CEmacs also makes all of the relevant @value{emacs} internal header files | |
442 | 205 available for module authors to use. This is often required to get data |
428 | 206 structure definitions and external variable declarations. The header |
207 files installed include the module specific header file | |
208 @file{emodules.h}. Due to the nature of dynamic modules, most of the | |
209 internals of @value{emacs} are exposed. | |
442 | 210 @xref{Top,,,internals,@value{emacs} Internals Manual}, for a |
211 more complete discussion on how to extend and understand @value{emacs}. All of | |
428 | 212 the rules for C modules are discussed there. |
213 | |
214 @item | |
215 @cindex samples | |
216 Part of the @value{emacs} distribution is a set of sample modules. These are | |
217 not installed when @value{emacs} is, but remain in the @value{emacs} source tree. | |
218 These modules live in the directory @file{modules}, which is a | |
219 sub-directory of the main @value{emacs} source code directory. Please look at | |
220 the samples carefully, and maybe even use them as a basis for making | |
221 your own modules. Most of the concepts required for writing extension | |
222 modules are covered in the samples. | |
223 | |
224 @item | |
225 @cindex documentation | |
226 @cindex help | |
227 Last, but not least is this manual. This can be viewed from within | |
228 @value{emacs}, and it can be printed out as well. It is the intention of this | |
229 document that it will describe everything you need to know about | |
230 extending @value{emacs} in C. If you do not find this to be the case, please | |
231 contact the author(s). | |
232 @end itemize | |
233 | |
234 The rest of this document will discuss the actual mechanics of | |
235 @value{emacs} modules and work through several of the samples. Please be | |
236 sure that you have read the @value{emacs} Internals Manual and understand | |
237 everything in it. The concepts there apply to all modules. This | |
238 document may have some overlap, but it is the internals manual which | |
239 should be considered the final authority. It will also help a great | |
240 deal to look at the actual @value{emacs} source code to see how things are | |
241 done. | |
242 | |
442 | 243 @node Anatomy of a Module, Using ellcc, Introduction, Top |
244 @chapter Anatomy of a Module | |
245 @cindex anatomy | |
428 | 246 @cindex module skeleton |
247 @cindex skeleton, module | |
248 @cindex module format | |
249 @cindex format, module | |
250 | |
442 | 251 Each dynamically loadable @value{emacs} extension (hereafter referred to as a |
252 module) has a certain compulsory format, and must contain several | |
253 pieces of information and several mandatory functions. This chapter | |
428 | 254 describes the basic layout of a module, and provides a very simple |
255 sample. The source for this sample can be found in the file | |
256 @file{modules/simple/sample.c} in the main @value{emacs} source code tree. | |
257 | |
258 @menu | |
259 * Required Header File:: Always include <emodules.h> | |
260 * Required Functions:: Functions you must always provide | |
261 * Required Variables:: Variables whose values you must provide | |
442 | 262 * Loading other Modules:: How to load dependent modules |
428 | 263 @end menu |
264 | |
442 | 265 @node Required Header File, Required Functions, Anatomy of a Module, Anatomy of a Module |
428 | 266 @section Required Header File |
267 @cindex required header | |
268 @cindex include files | |
269 | |
270 @cindex emodules.h | |
271 @cindex config.h | |
272 Every module must include the file @file{<emodules.h>}. This | |
442 | 273 will include several other @value{emacs} internal header files, and will set up |
428 | 274 certain vital macros. One of the most important files included by |
275 @file{emodules.h} is the generated @file{config.h} file, which contains | |
276 all of the required system abstraction macros and definitions. Most | |
277 modules will probably require some pre-processor conditionals based on | |
278 constants defined in @file{config.h}. Please read that file to | |
279 familiarize yourself with the macros defined there. | |
280 | |
442 | 281 Depending on exactly what your module will be doing, you will probably |
428 | 282 need to include one or more of the @value{emacs} internal header files. When |
442 | 283 you @code{#include <emodules.h>}, you will get a few of the most important |
428 | 284 @value{emacs} header files included automatically for you. The files included |
285 are: | |
286 | |
287 @table @file | |
288 @item lisp.h | |
442 | 289 This file contains most of the macros required for declaring Lisp object |
428 | 290 types, macros for accessing Lisp objects, and global variable |
291 declarations. | |
292 | |
293 @item sysdep.h | |
442 | 294 All system dependent declarations and abstraction macros live here. You |
428 | 295 should never call low level system functions directly. Rather, you |
296 should use the abstraction macros provided in this header file. | |
297 | |
298 @item window.h | |
299 This header file defines the window structures and Lisp types, and | |
300 provides functions and macros for manipulating multiple @value{emacs} windows. | |
301 | |
302 @item buffer.h | |
303 All macros and function declarations for manipulating internal and user | |
304 visible buffers appear in this file. | |
305 | |
306 @item insdel.h | |
307 This header provides the information required for performing text | |
308 insertion and deletion. | |
309 | |
310 @item frame.h | |
311 Provides the required structure, macro and function definitions for | |
312 manipulating @value{emacs} frames. | |
313 @end table | |
314 | |
442 | 315 @node Required Functions, Required Variables, Required Header File, Anatomy of a Module |
428 | 316 @section Required Functions |
317 @cindex initialization | |
318 @cindex functions, required | |
319 @cindex required functions | |
320 | |
321 Every module requires several initialization functions. It is the | |
442 | 322 responsibility of these functions to load in any dependent modules, and to |
323 declare all variables and functions which are to be made visible to the | |
428 | 324 @value{emacs} Lisp reader. Each of these functions performs a very specific |
325 task, and they are executed in the correct order by @value{emacs}. All of | |
326 these functions are @code{void} functions which take no arguments. | |
327 Here, briefly, are the required module functions. Note that the actual | |
328 function names do not end with the string @code{_module}, but rather | |
329 they end with the abbreviated module name by which the module is known. | |
330 More on the module name and its importance later. Just bear in mind | |
331 that the text @code{_module} in the functions below is simply a | |
332 place-holder, not an actual function name. | |
333 | |
334 @table @code | |
335 @item syms_of_module | |
336 @findex syms_of_module | |
442 | 337 This required function is responsible for introducing to the Lisp reader |
428 | 338 all functions that you have defined in your module using |
339 @code{DEFUN()}. Note that @emph{only} functions are declared here, using | |
340 the @code{DEFSUBR()} macro. No variables are declared. | |
341 | |
342 @item vars_of_module | |
343 @findex vars_of_module | |
344 This required function contains calls to macros such as | |
345 @code{DEFVAR_LISP()}, @code{DEFVAR_BOOL()} etc, and its purpose is to | |
346 declare and initialize all and any variables that your module defines. | |
347 They syntax for declaring variables is identical to the syntax used for | |
450 | 348 all internal @value{emacs} source code. If the module is intended to be |
349 usable statically linked into XEmacs, the actions of this function are | |
350 severely restricted. @xref{General Coding Rules,,,internals, | |
351 @value{emacs} Internals Manual}. Also see the comments in | |
352 @file{src/emacs.c} (@code{main_1}). Modules which perform | |
353 initializations not permitted by these rules will probably work, but | |
354 dual-use (dynamic loading and static linking) modules will require very | |
355 careful, and possibly fragile, coding. | |
428 | 356 |
357 @item modules_of_module | |
358 @findex modules_of_module | |
359 This optional function should be used to load in any modules which your | |
442 | 360 module depends on. The @value{emacs} module loading code makes sure that the |
428 | 361 same module is not loaded twice, so several modules can safely call the |
362 module load function for the same module. Only one copy of each module | |
363 (at a given version) will ever be loaded. | |
364 | |
365 @item docs_of_module | |
366 @findex docs_of_module | |
367 This is a required function, but not one which you need ever write. | |
368 This function is created automatically by @code{ellcc} when the module | |
369 initialization code is produced. It is required to document all | |
370 functions and variables declared in your module. | |
371 @end table | |
372 | |
442 | 373 @node Required Variables, Loading other Modules, Required Functions, Anatomy of a Module |
428 | 374 @section Required Variables |
375 @cindex initialization | |
376 @cindex variables, required | |
377 @cindex required variables | |
378 | |
379 Not only does a module need to declare the initialization functions | |
380 mentioned above, it is also required to provide certain variables which | |
442 | 381 the module loading code searches for in order to determine the viability |
428 | 382 of a module. You are @emph{not} required to provide these variables in |
383 your source files. They are automatically set up in the module | |
384 initialization file by the @code{ellcc} compiler. These variables are | |
385 discussed here simply for the sake of completeness. | |
386 | |
387 @table @code | |
388 @item emodules_compiler | |
389 This is a variable of type @code{long}, and is used to indicate the | |
390 version of the @value{emacs} loading technology that was used to produce the | |
391 module being loaded. This version number is completely unrelated to | |
392 the @value{emacs} version number, as a given module may quite well work | |
442 | 393 regardless of the version of @value{emacs} that was installed at the time the |
428 | 394 module was created. |
395 | |
396 The @value{emacs} modules version is used to differentiate between major | |
397 changes in the module loading technology, not versions of @value{emacs}. | |
398 | |
399 @item emodules_name | |
400 This is a short (typically 10 characters or less) name for the module, | |
401 and it is used as a suffix for all of the required functions. This is | |
442 | 402 also the name by which the module is recognized when loading dependent |
428 | 403 modules. The name does not necessarily have to be the same as the |
404 physical file name, although keeping the two names in sync is a pretty | |
442 | 405 good idea. The name must not be empty, and it must be a valid part of a |
406 C function name. The value of this variable is appended to the function | |
428 | 407 names @code{syms_of_}, @code{vars_of_}, @code{modules_of_} and |
408 @code{docs_of_} to form the actual function names that the module | |
409 loading code looks for when loading a module. | |
410 | |
411 This variable is set by the @code{--mod-name} argument to @code{ellcc}. | |
412 | |
413 @item emodules_version | |
414 This string variable is used to load specific versions of a module. | |
415 Rarely will two or more versions of a module be left lying around, but | |
416 just in case this does happen, this variable can be used to control | |
417 exactly which module should be loaded. See the Lisp function | |
418 @code{load-module} for more details. This variable is set by the | |
419 @code{--mod-version} argument to @code{ellcc}. | |
420 | |
421 @item emodules_title | |
422 This is a string which describes the module, and can contain spaces or | |
423 other special characters. It is used solely for descriptive purposes, | |
424 and does not affect the loading of the module. The value is set by the | |
425 @code{--mod-title} argument to @code{ellcc}. | |
426 @end table | |
427 | |
442 | 428 @node Loading other Modules, , Required Variables, Anatomy of a Module |
428 | 429 @section Loading other Modules |
442 | 430 @cindex dependencies |
428 | 431 @findex modules_of_module |
432 @findex emodules_load | |
433 | |
434 During the loading of a module, it is the responsibility of the function | |
435 @code{modules_of_module} to load in any modules which the current module | |
436 depends on. If the module is stand-alone, and does not depend on other | |
437 modules, then this function can be left empty or even undeclared. | |
442 | 438 However, if it does have dependencies, it must call |
428 | 439 @code{emodules_load}: |
440 | |
441 @example | |
442 @cartouche | |
442 | 443 int emodules_load (const char *module, |
444 const char *modname, | |
445 const char *modver) | |
428 | 446 @end cartouche |
447 @end example | |
448 | |
442 | 449 The first argument @var{module} is the name of the actual shared object |
428 | 450 or DLL. You can omit the @file{.so}, @file{.ell} or @file{.dll} |
451 extension of you wish. If you do not specify an absolute path name, | |
452 then the same rules as apply to loading Lisp modules are applied when | |
453 searching for the module. If the module cannot be found in any of the | |
454 standard places, and an absolute path name was not specified, | |
442 | 455 @code{emodules_load} will signal an error and loading of the module |
428 | 456 will stop. |
457 | |
458 The second argument (@var{modname}) is the module name to load, and | |
459 must match the contents of the variable @var{emodule_name} in the | |
442 | 460 module to be loaded. A mis-match will cause the module load to fail. If |
428 | 461 this parameter is @code{NULL} or empty, then no checks are performed |
462 against the target module's @var{emodule_name} variable. | |
463 | |
464 The last argument, @var{modver}, is the desired version of the module | |
465 to load, and is compared to the target module's | |
466 @var{emodule_version} value. If this parameter is not @code{NULL} | |
467 or empty, and the match fails, then the load of the module will fail. | |
468 | |
469 @code{emodules_load} can be called recursively. If, at any point | |
442 | 470 during the loading of modules a failure is encountered, then all modules |
428 | 471 that were loaded since the top level call to @code{emodules_load} |
472 will be unloaded. This means that if any child modules fail to load, | |
473 then their parents will also fail to load. This does not include | |
474 previous successful calls to @code{emodules_load} at the top level. | |
475 | |
880 | 476 @strong{Warning:} Modules are @emph{not} loaded with the |
477 @code{RTLD_GLOBAL} flag. The practical upshot is that individual | |
478 modules do not have access to each other's C symbols. One module cannot | |
479 make a C function call to a function defined in another module, nor can | |
480 it read or set a C variable in another module. All interaction between | |
481 modules must, therefore, take place at the Lisp level. This is by | |
482 design. Other projects have attempted to use @code{RTLD_GLOBAL}, only | |
483 to find that spurious symbol name clashes were the result. Helper | |
484 functions often have simple names, increasing the probability of such a | |
485 clash. If you really need to share symbols between modules, create a | |
486 shared library containing those symbols, and link your modules with | |
487 that library. Otherwise, interactions between modules must take place | |
488 via Lisp function calls and Lisp variables accesses. | |
489 | |
2972 | 490 @node Using ellcc, Distribution with XEmacs, Anatomy of a Module, Top |
428 | 491 @chapter Using @code{ellcc} |
492 @cindex @code{ellcc} | |
493 @cindex module compiler | |
494 | |
495 Before discussing the anatomy of a module in greater detail, you should | |
496 be aware of the steps required in order to correctly compile and link a | |
497 module for use within @value{emacs}. There is little difference between | |
498 compiling normal C code and compiling a module. In fact, all that | |
499 changes is the command used to compile the module, and a few extra | |
500 arguments to the compiler. | |
501 | |
502 @value{emacs} now ships with a new user utility, called @code{ellcc}. This | |
503 is the @dfn{Emacs Loadable Library C Compiler}. This is a wrapper | |
504 program that will invoke the real C compiler with the correct arguments | |
505 to compile and link your module. With the exception of a few command | |
506 line options, this program can be considered a replacement for your C | |
507 compiler. It accepts all of the same flags and arguments that your C | |
508 compiler does, so in many cases you can simply set the @code{make} | |
509 variable @code{CC} to @code{ellcc} and your code will be compiled as | |
510 an Emacs module rather than a static C object. | |
511 | |
512 @code{ellcc} has three distinct modes of operation. It can be run in | |
442 | 513 compile, link or initialization mode. These modes are discussed in more |
428 | 514 detail below. If you want @code{ellcc} to show the commands it is |
515 executing, you can specify the option @code{--mode=verbose} to | |
516 @code{ellcc}. Specifying this option twice will enable certain extra | |
517 debugging messages to be displayed on the standard output. | |
518 | |
519 @menu | |
520 * Compile Mode:: Compiling modules using ellcc | |
521 * Initialization Mode:: Generating documentation and variables | |
522 * Link Mode:: Creating the final loadable module | |
523 * Other ellcc options:: Other useful options | |
524 * Environment Variables:: How to control ellcc | |
525 @end menu | |
526 | |
527 @node Compile Mode, Initialization Mode, Using ellcc, Using ellcc | |
528 @section Compile Mode | |
529 @cindex compiling | |
530 | |
531 By default, @code{ellcc} is in @dfn{compile} mode. This means that it | |
442 | 532 assumes that all of the command line arguments are C compiler arguments, |
428 | 533 and that you want to compile the specified source file or files. You |
534 can force compile mode by specifying the @code{--mode=compile} argument | |
535 to @code{ellcc}. | |
536 | |
537 In this mode, @code{ellcc} is simply a front-end to the same C compiler | |
538 that was used to create the @value{emacs} binary itself. All @code{ellcc} | |
539 does in this mode is insert a few extra command line arguments before | |
540 the arguments you specify to @code{ellcc} itself. @code{ellcc} will | |
541 then invoke the C compiler to compile your module, and will return the | |
542 same exit codes and messages that your C compiler does. | |
543 | |
544 By far the easiest way to compile modules is to construct a | |
442 | 545 @file{Makefile} as you would for a normal program, and simply insert, at |
428 | 546 some appropriate place something similar to: |
547 | |
548 @example | |
549 @cartouche | |
550 CC=ellcc --mode=compile | |
551 | |
552 .c.o: | |
553 $(CC) $(CFLAGS) -c $< | |
554 @end cartouche | |
555 @end example | |
556 | |
557 After this, all you need to do is provide simple @code{make} rules for | |
558 compiling your module source files. Since modules are most useful when | |
559 they are small and self-contained, most modules will have a single | |
560 source file, aside from the module specific initialization file (see | |
561 below for details). | |
562 | |
563 @node Initialization Mode, Link Mode, Compile Mode, Using ellcc | |
564 @section Initialization Mode | |
565 @cindex initialization | |
566 @cindex documentation | |
567 | |
568 @value{emacs} uses a rather bizarre way of documenting variables and | |
569 functions. Rather than have the documentation for compiled functions | |
570 and variables passed as static strings in the source code, the | |
571 documentation is included as a C comment. A special program, called | |
572 @file{make-docfile}, is used to scan the source code files and extract | |
442 | 573 the documentation from these comments, producing the @value{emacs} @file{DOC} |
428 | 574 file, which the internal help engine scans when the documentation for a |
575 function or variable is requested. | |
576 | |
577 Due to the internal construction of Lisp objects, subrs and other such | |
578 things, adding documentation for a compiled function or variable in a | |
579 compiled module, at any time after @value{emacs} has been @dfn{dumped} is | |
442 | 580 somewhat problematic. Fortunately, as a module writer you are insulated |
428 | 581 from the difficulties thanks to your friend @code{ellcc} and some |
582 internal trickery in the module loading code. This is all done using | |
583 the @dfn{initialization} mode of @code{ellcc}. | |
584 | |
585 The result of running @code{ellcc} in initialization mode is a C source | |
586 file which you compile with (you guessed it) @code{ellcc} in compile | |
587 mode. Initialization mode is where you set the module name, version, | |
442 | 588 title and gather together all of the documentation strings for the |
589 functions and variables in your module. There are several options that | |
428 | 590 you are required to pass @code{ellcc} in initialization mode, the first |
591 of which is the mode switch itself, @code{--mode=init}. | |
592 | |
593 Next, you need to specify the name of the C source code file that | |
594 @code{ellcc} will produce, and you specify this using the | |
595 @code{--mod-output=FILENAME} argument. @var{FILENAME} is the name of | |
596 the C source code file that will contain the module variables and | |
597 @code{docs_of_module} function. | |
598 | |
599 As discussed previously, each module requires a short @dfn{handle} or | |
600 module name. This is specified with the @code{--mod-name=NAME} option, | |
601 where @var{NAME} is the abbreviated module name. This @var{NAME} must | |
602 consist only of characters that are valid in C function and variable | |
603 names. | |
604 | |
605 The module version is specified using @code{--mod-version=VERSION} | |
606 argument, with @var{VERSION} being any arbitrary version string. This | |
607 version can be passed as an optional second argument to the Lisp | |
608 function @code{load-module}, and as the third argument to the internal | |
609 module loading command @code{emodules_load}. This version string is | |
610 used to distinguish between different versions of the same module, and | |
611 to ensure that the module is loaded at a specific version. | |
612 | |
613 Last, but not least, is the module title. Specified using the | |
614 @code{--mod-title=TITLE} option, the specified @var{TITLE} is used when | |
615 the list of loaded modules is displayed. The module title serves no | |
616 purpose other than to inform the user of the function of the module. | |
617 This string should be brief, as it has to be formatted to fit the | |
618 screen. | |
619 | |
620 Following all of these parameters, you need to provide the list of all | |
442 | 621 source code modules that make up your module. These are the files which |
622 are scanned by @file{make-docfile}, and provide the information required | |
428 | 623 to populate the @code{docs_of_module} function. Below is a sample |
624 @file{Makefile} fragment which indicates how all of this is used. | |
625 | |
626 @example | |
627 @cartouche | |
628 CC=ellcc --mode=compile | |
629 LD=ellcc --mode=link | |
630 MODINIT=ellcc --mode=init | |
631 CFLAGS=-O2 -DSOME_STUFF | |
632 | |
633 .c.o: | |
634 $(CC) $(CFLAGS) -c $< | |
635 | |
636 MODNAME=sample | |
637 MODVER=1.0.0 | |
638 MODTITLE="Small sample module" | |
639 | |
640 SRCS=modfile1.c modfile2.c modfile3.c | |
641 OBJS=$(SRCS:.c=.o) | |
642 | |
643 all: sample.ell | |
644 clean: | |
645 rm -f $(OBJS) sample_init.o sample.ell | |
646 | |
647 install: all | |
648 mkdir `ellcc --mod-location`/mymods > /dev/null | |
649 cp sample.ell `ellcc --mod-location`/mymods/sample.ell | |
650 | |
651 sample.ell: $(OBJS) sample_init.o | |
652 $(LD) --mod-output=$@ $(OBJS) sample_init.o | |
653 | |
654 sample_init.o: sample_init.c | |
655 sample_init.c: $(SRCS) | |
656 $(MODINIT) --mod-name=$(MODNAME) --mod-version=$(MODVER) \ | |
657 --mod-title=$(MODTITLE) --mod-output=$@ $(SRCS) | |
658 @end cartouche | |
659 @end example | |
660 | |
661 The above @file{Makefile} is, in fact, complete, and would compile the | |
662 sample module, and optionally install it. The @code{--mod-location} | |
663 argument to @code{ellcc} will produce, on the standard output, the base | |
664 location of the @value{emacs} module directory. Each sub-directory of that | |
625 | 665 directory is automatically searched for modules when they are loaded with |
666 @code{load-module}. An alternative location would be | |
667 @file{/usr/local/lib/xemacs/site-modules}. That path can change depending | |
668 on the options the person who compiled @value{emacs} chose, so you can | |
669 always determine the correct site location using the | |
670 @code{--mod-site-location} option. This directory is treated the same way | |
671 as the main module directory. Each sub-directory within it is searched for | |
672 a given module when the user attempts to load it. The valid extensions that | |
673 the loader attempts to use are @file{.so}, @file{.ell} and @file{.dll}. You | |
674 can use any of these extensions, although @file{.ell} is the preferred | |
675 extension. | |
428 | 676 |
677 @node Link Mode, Other ellcc options, Initialization Mode, Using ellcc | |
678 @section Link Mode | |
679 @cindex linking | |
680 | |
681 Once all of your source code files have been compiled (including the | |
442 | 682 generated init file) you need to link them all together to create the |
428 | 683 loadable module. To do this, you invoke @code{ellcc} in link mode, by |
450 | 684 passing the @code{--mode=link} option. You need to specify the final |
442 | 685 output file using the @code{--mod-output=NAME} option, but other than |
428 | 686 that all other arguments are passed on directly to the system compiler |
687 or linker, along with any other required arguments to create the | |
688 loadable module. | |
689 | |
690 The module has complete access to all symbols that were present in the | |
691 dumped @value{emacs}, so you do not need to link against libraries that were | |
692 linked in with the main executable. If your library uses some other | |
693 extra libraries, you will need to link with those. There is nothing | |
694 particularly complicated about link mode. All you need to do is make | |
695 sure you invoke it correctly in the @file{Makefile}. See the sample | |
696 @file{Makefile} above for an example of a well constructed | |
697 @file{Makefile} that invoked the linker correctly. | |
698 | |
699 @node Other ellcc options, Environment Variables, Link Mode, Using ellcc | |
700 @section Other @code{ellcc} options | |
701 @cindex paths | |
702 | |
703 Aside from the three main @code{ellcc} modes described above, | |
704 @code{ellcc} can accept several other options. These are typically used | |
442 | 705 in a @file{Makefile} to determine installation paths. @code{ellcc} also |
428 | 706 allows you to over-ride several of its built-in compiler and linker |
707 options using environment variables. Here is the complete list of | |
708 options that @code{ellcc} accepts. | |
709 | |
710 @table @code | |
711 @item --mode=compile | |
712 Enables compilation mode. Use this to compile source modules. | |
713 | |
714 @item --mode=link | |
715 Enabled link edit mode. Use this to create the final module. | |
716 | |
717 @item --mode=init | |
718 Used to create the documentation function and to initialize other | |
442 | 719 required variables. Produces a C source file that must be compiled with |
428 | 720 @code{ellcc} in compile mode before linking the final module. |
721 | |
722 @item --mode=verbose | |
723 Enables verbose mode. This will show you the commands that are being | |
442 | 724 executed, as well as the version number of @code{ellcc}. If you specify |
428 | 725 this option twice, then some extra debugging information is displayed. |
726 | |
727 @item --mod-name=NAME | |
442 | 728 Sets the short internal module @var{NAME} to the string specified, |
428 | 729 which must consist only of valid C identifiers. Required during |
730 initialization mode. | |
731 | |
732 @item --mod-version=VERSION | |
733 Sets the internal module @var{VERSION} to the specified string. | |
734 Required during initialization mode. | |
735 | |
736 @item --mod-title=TITLE | |
737 Sets the module descriptive @var{TITLE} to the string specified. This | |
738 string can contain any printable characters, but should not be too | |
739 long. It is required during initialization mode. | |
740 | |
741 @item --mod-output=FILENAME | |
742 Used to control the output file name. This is used during | |
743 initialization mode to set the name of the C source file that will be | |
744 created to @var{FILENAME}. During link mode, it sets the name of the | |
745 final loadable module to @var{FILENAME}. | |
746 | |
747 @item --mod-location | |
442 | 748 This will print the name of the standard module installation path on the |
428 | 749 standard output and immediately exit @code{ellcc}. Use this option to |
750 determine the directory prefix of where you should install your modules. | |
751 | |
752 @item --mod-site-location | |
753 This will print the name of the site specific module location and exit. | |
754 | |
755 @item --mod-archdir | |
442 | 756 Prints the name of the root of the architecture-dependent directory that |
757 @value{emacs} searches for architecture-dependent files. | |
428 | 758 |
759 @item --mod-config | |
442 | 760 Prints the name of the configuration for which @value{emacs} and @code{ellcc} |
428 | 761 were compiled. |
762 @end table | |
763 | |
764 @node Environment Variables, , Other ellcc options, Using ellcc | |
765 @section Environment Variables | |
766 @cindex environment variables | |
767 | |
768 During its normal operation, @code{ellcc} uses the compiler and linker | |
769 flags that were determined at the time @value{emacs} was configured. In | |
442 | 770 certain rare circumstances you may wish to over-ride the flags passed to |
428 | 771 the compiler or linker, and you can do so using environment variables. |
442 | 772 The table below lists all of the environment variables that @code{ellcc} |
773 recognizes. | |
428 | 774 |
775 @table @code | |
776 @item ELLCC | |
777 @cindex @code{ELLCC} | |
778 This is used to over-ride the name of the C compiler that is invoked by | |
779 @code{ellcc}. | |
780 | |
781 @item ELLLD | |
782 @cindex @code{ELLLD} | |
783 Sets the name of the link editor to use to created the final module. | |
784 | |
785 @item ELLCFLAGS | |
786 @cindex @code{ELLCFLAGS} | |
787 Sets the compiler flags passed on when compiling source modules. This | |
788 only sets the basic C compiler flags. There are certain hard-coded | |
789 flags that will always be passed. | |
790 | |
791 @item ELLLDFLAGS | |
792 @cindex @code{ELLLDFLAGS} | |
793 Sets the flags passed on to the linker. This does @strong{not} include | |
794 the flags for enabling PIC mode. This just sets basic linker flags. | |
795 | |
796 @item ELLDLLFLAGS | |
797 @cindex @code{ELLDLLFLAGS} | |
798 Sets the flags passed to the linker that are required to created shared | |
799 and loadable objects. | |
800 | |
801 @item ELLPICFLAGS | |
802 @cindex @code{ELLPICFLAGS} | |
803 Sets the C compiler option required to produce an object file that is | |
804 suitable for including in a shared library. This option should turn on | |
805 PIC mode, or the moral equivalent thereof on the target system. | |
806 | |
807 @item ELLMAKEDOC | |
808 @cindex @code{ELLMAKEDOC} | |
809 Sets the name of the @file{make-docfile} program to use. Usually | |
810 @code{ellcc} will use the version that was compiled and installed with | |
811 @value{emacs}, but this option allows you to specify an alternative path. | |
812 Used during the compile phase of @value{emacs} itself. | |
813 @end table | |
814 | |
2972 | 815 @node Distribution with XEmacs, Defining Functions, Using ellcc, Top |
816 @chapter Adding Modules to the XEmacs Distribution | |
817 @cindex XEmacs integration | |
818 @cindex integration, XEmacs | |
819 @cindex modules and configure.ac | |
820 @cindex configure.ac, modules and | |
821 @cindex modules and Makefiles | |
822 @cindex Makefiles, modules and | |
823 | |
824 #### This section needs to be filled out. | |
825 | |
826 @strong{Warning: The procedure described in the section is subject to | |
827 change, as it is very stylized and thus a good candidate for further | |
828 automation.} | |
829 | |
830 Modules distributed with XEmacs are placed in the @file{modules} | |
831 subdirectory of the root of the source tree. Each module's code is | |
832 placed in a separate subdirectory. The build infrastructure for a | |
833 module consists of a @file{Makefile.in.in}, a @file{configure.ac}, and | |
834 @file{install-sh}. @file{install-sh} is a constant, and may simply be | |
835 copied from an existing module. | |
836 | |
837 Most of the job of building a module is encapsulated in | |
838 @file{modules/common/Makefile.common} and in @file{ellcc}. The module's | |
839 @file{Makefile.in.in} normally needs only to define module name and | |
840 version information, and include @file{modules/common/Makefile.common}. | |
841 The @file{configure.ac} is very module-specific, and little can be said | |
842 about its contents. However, since no logic that depends on XEmacs | |
843 itself or other modules needs to be present, it is easier to write and | |
844 maintain than if it were contained in the XEmacs distribution's | |
845 @file{configure.ac}. | |
846 | |
847 Modules can usually be trivially built in to the XEmacs binary. To make | |
848 this work, you need to duplicate the detection logic for any resources | |
849 the module requires in the top-level @file{configure.ac}. Since module | |
850 objects may be linked into modules or into @file{xemacs}, instead of | |
851 adding library path and library information directly to some | |
852 @file{@var{subsystem}_libs} variable, you should add them to a | |
853 @file{@var{module}_libs} variable, which in turn must be added to | |
854 @code{ld_libs_module} in the section ``Compute SUBST-itutable variables.'' | |
855 | |
856 Furthermore, in @file{src/Makefile.in.in} you add rules to build the | |
857 object without the module wrapper, and conditionalize these and the | |
858 addition of the object to @code{objs} on @code{HAVE_SHLIB}. The right | |
859 way to do this is somewhat indirect. Study the integration of LDAP and | |
860 PostgreSQL for the details. | |
861 | |
862 | |
863 @node Defining Functions, Defining Variables, Distribution with XEmacs, Top | |
428 | 864 @chapter Defining Functions |
865 @cindex defining functions | |
866 | |
867 One of the main reasons you would ever write a module is to | |
868 provide one or more @dfn{functions} for the user or the editor to use. | |
442 | 869 The term |
428 | 870 @dfn{function} is a bit overloaded here, as it refers to both a C |
871 function and the way it appears to Lisp, which is a @dfn{subroutine}, or | |
872 simply a @dfn{subr}. A Lisp subr is also known as a Lisp primitive, but | |
873 that term applies less to dynamic modules. @xref{Writing Lisp | |
874 Primitives,,,internals,@value{emacs} Internals Manual}, for details on how to | |
875 declare functions. You should familiarize yourself with the | |
442 | 876 instructions there. The format of the function declaration is identical |
428 | 877 in modules. |
878 | |
442 | 879 Normal Lisp primitives document the functions they defining by including |
428 | 880 the documentation as a C comment. During the build process, a program |
881 called @file{make-docfile} is run, which will extract all of these | |
882 comments, build up a single large documentation file, and will store | |
883 pointers to the start of each documentation entry in the dumped @value{emacs}. | |
884 This, of course, will not work for dynamic modules, as they are loaded | |
885 long after @value{emacs} has been dumped. For this reason, we require a | |
886 special means for adding documentation for new subrs. This is what the | |
887 macro @code{CDOCSUBR} is used for, and this is used extensively during | |
888 @code{ellcc} initialization mode. | |
889 | |
890 When using @code{DEFUN} in normal @value{emacs} C code, the sixth | |
891 ``parameter'' is a C comment which documents the function. For a | |
892 dynamic module, we of course need to convert the C comment to a usable | |
442 | 893 string, and we need to set the documentation pointer of the subr to this |
428 | 894 string. As a module programmer, you don't actually need to do any work |
895 for this to happen. It is all taken care of in the | |
896 @code{docs_of_module} function created by @code{ellcc}. | |
897 | |
898 @menu | |
899 * Using DEFUN:: Using the DEFUN macro to define functions | |
900 * Declaring Functions:: Declaring functions to the Lisp reader | |
901 @end menu | |
902 | |
903 @node Using DEFUN, Declaring Functions, Defining Functions, Defining Functions | |
904 @section Using @code{DEFUN} | |
905 @cindex subrs | |
906 @findex DEFUN | |
907 @cindex functions, Lisp | |
908 @cindex functions, defining | |
909 | |
775 | 910 The full syntax of a function declaration is discussed in the |
911 @value{emacs} internals manual in greater depth. @ref{Writing Lisp | |
912 Primitives,,,internals,@value{emacs} Internals Manual}. What follows is | |
913 a brief description of how to define and implement a new Lisp primitive | |
914 in a module. This is done using the @code{DEFUN} macro. Here is a | |
915 small example: | |
428 | 916 |
917 @example | |
918 @cartouche | |
919 DEFUN ("my-function", Fmy_function, 1, 1, "FFile name: ", /* | |
920 Sample Emacs primitive function. | |
921 | |
442 | 922 The specified FILE is frobnicated before it is fnozzled. |
428 | 923 */ |
924 (file)) | |
925 @{ | |
926 char *filename; | |
927 | |
928 if (NILP(file)) | |
929 return Qnil; | |
930 | |
931 filename = (char *)XSTRING_DATA(file); | |
932 frob(filename); | |
933 return Qt; | |
934 @} | |
935 @end cartouche | |
936 @end example | |
937 | |
938 The first argument is the name of the function as it will appear to the | |
442 | 939 Lisp reader. This must be provided as a string. The second argument is |
428 | 940 the name of the actual C function that will be created. This is |
442 | 941 typically the Lisp function name with a preceding capital @code{F}, with |
428 | 942 hyphens converted to underscores. This must be a valid C function |
943 name. Next come the minimum and maximum number of arguments, | |
944 respectively. This is used to ensure that the correct number of | |
945 arguments are passed to the function. Next is the @code{interactive} | |
946 definition. If this function is meant to be run by a user | |
947 interactively, then you need to specify the argument types and prompts | |
948 in this string. Please consult the @value{emacs} Lisp manual for more | |
949 details. Next comes a C comment that is the documentation for this | |
950 function. This comment @strong{must} exist. Last comes the list of | |
951 function argument names, if any. | |
952 | |
953 @node Declaring Functions, , Using DEFUN, Defining Functions | |
954 @section Declaring Functions | |
955 @findex DEFSUBR | |
956 @cindex functions, declaring | |
957 | |
958 Simply writing the code for a function is not enough to make it | |
442 | 959 available to the Lisp reader. You have to, during module |
428 | 960 initialization, let the Lisp reader know about the new function. This |
961 is done by calling @code{DEFSUBR} with the name of the function. This | |
962 is the sole purpose of the initialization function | |
963 @code{syms_of_module}. @xref{Required Functions}, for more details. | |
964 | |
965 Each call to @code{DEFSUBR} takes as its only argument the name of the | |
966 function, which is the same as the second argument to the call to | |
967 @code{DEFUN}. Using the example function above, you would insert the | |
968 following code in the @code{syms_of_module} function: | |
969 | |
970 @example | |
971 @cartouche | |
972 DEFSUBR(Fmy_function); | |
973 @end cartouche | |
974 @end example | |
975 | |
976 This call will instruct @value{emacs} to make the function visible to the Lisp | |
977 reader and will prepare for the insertion of the documentation into | |
978 the right place. Once this is done, the user can call the Lisp | |
979 function @code{my-function}, if it was defined as an interactive | |
980 function (which in this case it was). | |
981 | |
4312 | 982 That's all there is to defining and announcing new functions. The rules |
428 | 983 for what goes inside the functions, and how to write good modules, is |
984 beyond the scope of this document. Please consult the @value{emacs} | |
985 internals manual for more details. | |
986 | |
987 @node Defining Variables, Index, Defining Functions, Top | |
988 @chapter Defining Variables | |
989 @cindex defining variables | |
990 @cindex defining objects | |
991 @findex DEFVAR_LISP | |
992 @findex DEFVAR_BOOL | |
993 @findex DEFVAR_INT | |
994 @cindex variables, Lisp | |
995 @cindex variables, defining | |
996 @cindex objects, defining | |
997 @cindex objects, Lisp | |
998 | |
999 Rarely will you write a module that only contains functions. It is | |
1000 common to also provide variables which can be used to control the | |
442 | 1001 behavior of the function, or store the results of the function being |
428 | 1002 executed. The actual C variable types are the same for modules |
1003 and internal @value{emacs} primitives, and the declaration of the variables | |
1004 is identical. | |
1005 | |
442 | 1006 @xref{Adding Global Lisp Variables,,,internals,XEmacs Internals Manual}, |
428 | 1007 for more information on variables and naming conventions. |
1008 | |
1009 Once your variables are defined, you need to initialize them and make | |
1010 the Lisp reader aware of them. This is done in the | |
1011 @code{vars_of_module} initialization function using special @value{emacs} | |
442 | 1012 macros such as @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}, @code{DEFVAR_INT} |
1013 etc. The best way to see how to use these macros is to look at existing | |
428 | 1014 source code, or read the internals manual. |
1015 | |
1016 One @emph{very} important difference between @value{emacs} variables and | |
1017 module variables is how you use pure space. Simply put, you | |
1018 @strong{never} use pure space in @value{emacs} modules. The pure space | |
442 | 1019 storage is of a limited size, and is initialized properly during the |
428 | 1020 dumping of @value{emacs}. Because variables are being added dynamically to |
1021 an already running @value{emacs} when you load a module, you cannot use pure | |
1022 space. Be warned: @strong{do not use pure space in modules. Repeat, do | |
1023 not use pure space in modules.} Once again, to remove all doubts: | |
1024 @strong{DO NOT USE PURE SPACE IN MODULES!!!} | |
1025 | |
1026 Below is a small example which declares and initializes two | |
1027 variables. You will note that this code takes into account the fact | |
1028 that this module may very well be compiled into @value{emacs} itself. This | |
1029 is a prudent thing to do. | |
1030 | |
1031 @example | |
1032 @cartouche | |
1033 Lisp_Object Vsample_string; | |
1034 int sample_boolean; | |
1035 | |
1036 void | |
1037 vars_of_module() | |
1038 @{ | |
1039 DEFVAR_LISP ("sample-string", &Vsample_string /* | |
1040 This is a sample string, declared in a module. | |
1041 | |
1042 Nothing magical about it. | |
1043 */); | |
1044 | |
1045 DEFVAR_BOOL("sample-boolean", &sample_boolean /* | |
1046 *Sample user-settable boolean. | |
1047 */); | |
1048 | |
1049 sample_boolean = 0; | |
4953
304aebb79cd3
function renamings to track names of char typedefs
Ben Wing <ben@xemacs.org>
parents:
4312
diff
changeset
|
1050 Vsample_string = build_ascstring ("My string"); |
428 | 1051 @} |
1052 @end cartouche | |
1053 @end example | |
1054 | |
1055 @c Print the tables of contents | |
1056 @contents | |
1057 @c That's all | |
1058 | |
1059 @node Index, , Defining Variables, Top | |
1060 @unnumbered Index | |
1061 | |
1062 @printindex cp | |
1063 | |
1064 @bye | |
1065 |