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