Mercurial > hg > xemacs-beta

comparison man/emodules.texi @ 388:aabb7f5b1c81 r21-2-9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-9
author cvs
date Mon, 13 Aug 2007 11:09:42 +0200
parents
children 74fd4e045ea6
comparison
equal deleted inserted replaced
387:f892a9d0bb8d 388:aabb7f5b1c81
1 \input texinfo @c -*-texinfo-*-
2
3 @c %**start of header
4 @setfilename ../info/emodules.info
5 @settitle Extending Emacs using C Modules
6 @c %**end of header
7
8 @c
9 @c Use some macros so that we can format for either XEmacs
10 @c or (shudder) GNU Emacs.
11 @c
12
13 @ifset XEMACS
14 @macro emacs
15 XEmacs
16 @end macro
17 @clear EMACS
18 @set HAVE_EMACS
19 @end ifset
20
21 @ifset EMACS
22 @macro emacs
23 Emacs
24 @end macro
25 @clear XEMACS
26 @set HAVE_EMACS
27 @end ifset
28
29 @ifclear HAVE_EMACS
30 @set XEMACS
31 @macro emacs
32 XEmacs
33 @end macro
34 @end ifclear
35
36 @ifinfo
37 This file documents the module loading technology of @emacs{}.
38
39 Copyright @copyright{} 1998 J. Kean Johnston.
40
41 Permission is granted to make and distribute verbatim copies of this
42 manual provided the copyright notice and this permission notice are
43 preserved on all copies.
44
45 @ignore
46 Permission is granted to process this file through TeX and print the
47 results, provided the printed document carries copying permission notice
48 identical to this one except for the removal of this paragraph (this
49 paragraph not being relevant to the printed manual).
50
51 @end ignore
52 Permission is granted to copy and distribute modified versions of this
53 manual under the conditions for verbatim copying, provided that the
54 entire resulting derived work is distributed under the terms of a
55 permission notice identical to this one.
56
57 Permission is granted to copy and distribute translations of this manual
58 into another language, under the above conditions for modified versions,
59 except that this permission notice may be stated in a translation
60 approved by the Foundation.
61
62 Permission is granted to copy and distribute modified versions of this
63 manual under the conditions for verbatim copying, provided also that the
64 section entitled ``GNU General Public License'' is included exactly as
65 in the original, and provided that the entire resulting derived work is
66 distributed under the terms of a permission notice identical to this
67 one.
68
69 Permission is granted to copy and distribute translations of this manual
70 into another language, under the above conditions for modified versions,
71 except that the section entitled ``GNU General Public License'' may be
72 included in a translation approved by the Free Software Foundation
73 instead of in the original English.
74 @end ifinfo
75
76 @c Combine indices.
77 @syncodeindex fn cp
78 @syncodeindex vr cp
79 @syncodeindex ky cp
80 @syncodeindex pg cp
81 @syncodeindex tp cp
82
83 @setchapternewpage odd
84 @finalout
85
86 @titlepage
87 @title Extending @emacs{} using C and C++
88 @subtitle Version 1.0, September 1998
89
90 @author J. Kean Johnston
91 @page
92 @vskip 0pt plus 1fill
93
94 @noindent
95 Copyright @copyright{} 1998 J. Kean Johnston. @*
96
97 @sp 2
98 Version 1.0 @*
99 September, 1998.@*
100
101 Permission is granted to make and distribute verbatim copies of this
102 manual provided the copyright notice and this permission notice are
103 preserved on all copies.
104
105 Permission is granted to copy and distribute modified versions of this
106 manual under the conditions for verbatim copying, provided also that the
107 section entitled ``GNU General Public License'' is included
108 exactly as in the original, and provided that the entire resulting
109 derived work is distributed under the terms of a permission notice
110 identical to this one.
111
112 Permission is granted to copy and distribute translations of this manual
113 into another language, under the above conditions for modified versions,
114 except that the section entitled ``GNU General Public License'' may be
115 included in a translation approved by the Free Software Foundation
116 instead of in the original English.
117 @end titlepage
118 @page
119
120 @ifinfo
121 @node Top, Introduction, (dir), (dir)
122 This Info file contains v1.0 of the @emacs{} dynamic loadable module
123 support documentation.
124 @menu
125 * Introduction:: Introducing Emacs Modules
126 * Annatomy of a Module:: Basic module layout and technology
127 * Using ellcc:: How to use the module compiler
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
134 Annatomy of a Module
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
139 * Loading other Modules:: How to load dependant modules
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
157 @node Introduction, Annatomy of a Module, Top, Top
158 @chapter Introduction
159
160 @emacs{} is a powerful, extensible editor. The traditional way of
161 extending the functionality of @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 @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.
169 So although Elisp is a general purpose language, and very ligh level,
170 there are times when it is desirable to descend to a lower level compiled
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
175 more commonly known language, and because it is compiled, more suited to
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
183 This manual describes a new way of extending @emacs{}, by using dynamic
184 loadable modules (also knows as dynamicaly loadable libraries (DLLs),
185 dynamic shared objects (DSOs) or just simply shared objectcs), which can
186 be written in C or C++ and loaded into @emacs{} at any time. I sometimes
187 refer to this technology as @dfn{CEmacs}, which is short for @dfn{C
188 Extensible Emacs}.
189
190 @emacs{} modules are configured into and installed with @emacs{} by
191 default on all systems that support loading of shared objects. From a
192 users perspective, the internals of @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
208 compiler modes (such as PIC mode), setting the correct include paths for
209 the location of @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 @emacs{}.
212
213 @item
214 @cindex header files
215 CEmacs also makes all of the relevant @emacs{} internal header files
216 availible for module authors to use. This is often required to get data
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 @emacs{} are exposed.
221 @xref{Top,,,internals,@emacs{} Internals Manual}, for a
222 more complete discussion on how to extend and understand @emacs{}. All of
223 the rules for C modules are discussed there.
224
225 @item
226 @cindex samples
227 Part of the @emacs{} distribution is a set of sample modules. These are
228 not installed when @emacs{} is, but remain in the @emacs{} source tree.
229 These modules live in the directory @file{modules}, which is a
230 sub-directory of the main @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 @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 @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 @emacs{} modules and work through several of the samples. Please be
247 sure that you have read the @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 @emacs{} source code to see how things are
252 done.
253
254 @node Annatomy of a Module, Using ellcc, Introduction, Top
255 @chapter Annatomy of a Module
256 @cindex annatomy
257 @cindex module skeleton
258 @cindex skeleton, module
259 @cindex module format
260 @cindex format, module
261
262 Each dynamically loadable @emacs{} extension (hereafter refered to as a
263 module) has a certain compulsory format, and must contain several
264 pieces of information and several mandatory functions. This chapter
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 @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
273 * Loading other Modules:: How to load dependant modules
274 @end menu
275
276 @node Required Header File, Required Functions, Annatomy of a Module, Annatomy of a Module
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
284 will include several other @emacs{} internal header files, and will set up
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
292 Depending on exactly what your module will be doing, you will probably
293 need to include one or more of the @emacs{} internal header files. When
294 you @code{#include <emodules.h>}, you will get a few of the most important
295 @emacs{} header files included automatically for you. The files included
296 are:
297
298 @table @file
299 @item lisp.h
300 This file contains most of the macros required for declaring Lisp object
301 types, macros for accessing Lisp objects, and global variable
302 declarations.
303
304 @item sysdep.h
305 All system dependant declarations and abstraction macros live here. You
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 @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 @emacs{} frames.
324 @end table
325
326 @node Required Functions, Required Variables, Required Header File, Annatomy of a Module
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
333 responsibility of these functions to load in any dependant modules, and to
334 declare all variables and functions which are to be made visibile to the
335 @emacs{} Lisp reader. Each of these functions performs a very specific
336 task, and they are executed in the correct order by @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
348 This required function is responsible for introducing to the Lisp reader
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
359 all internal @emacs{} source code.
360
361 @item modules_of_module
362 @findex modules_of_module
363 This optional function should be used to load in any modules which your
364 module depends on. The @emacs{} module loading code makes sure that the
365 same module is not loaded twice, so several modules can safely call the
366 module load function for the same module. Only one copy of each module
367 (at a given version) will ever be loaded.
368
369 @item docs_of_module
370 @findex docs_of_module
371 This is a required function, but not one which you need ever write.
372 This function is created automatically by @code{ellcc} when the module
373 initialization code is produced. It is required to document all
374 functions and variables declared in your module.
375 @end table
376
377 @node Required Variables, Loading other Modules, Required Functions, Annatomy of a Module
378 @section Required Variables
379 @cindex initialization
380 @cindex variables, required
381 @cindex required variables
382
383 Not only does a module need to declare the initialization functions
384 mentioned above, it is also required to provide certain variables which
385 the module loading code searches for in order to determine the viability
386 of a module. You are @emph{not} required to provide these variables in
387 your source files. They are automatically set up in the module
388 initialization file by the @code{ellcc} compiler. These variables are
389 discussed here simply for the sake of completeness.
390
391 @table @code
392 @item emodules_compiler
393 This is a variable of type @code{long}, and is used to indicate the
394 version of the @emacs{} loading technology that was used to produce the
395 module being loaded. This version number is completely unrelated to
396 the @emacs{} version number, as a given module may quite well work
397 regardless of the version of @emacs{} that was installed at the time the
398 module was created.
399
400 The @emacs{} modules version is used to differentiate between major
401 changes in the module loading technology, not versions of @emacs{}.
402
403 @item emodules_name
404 This is a short (typically 10 characters or less) name for the module,
405 and it is used as a suffix for all of the required functions. This is
406 also the name by which the module is recognised when loading dependant
407 modules. The name does not necessarily have to be the same as the
408 physical file name, although keeping the two names in sync is a pretty
409 good idea. The name must not be empty, and it must be a valid part of a
410 C function name. The value of this variable is appended to the function
411 names @code{syms_of_}, @code{vars_of_}, @code{modules_of_} and
412 @code{docs_of_} to form the actual function names that the module
413 loading code looks for when loading a module.
414
415 This variable is set by the @code{--mod-name} argument to @code{ellcc}.
416
417 @item emodules_version
418 This string variable is used to load specific versions of a module.
419 Rarely will two or more versions of a module be left lying around, but
420 just in case this does happen, this variable can be used to control
421 exactly which module should be loaded. See the Lisp function
422 @code{load-module} for more details. This variable is set by the
423 @code{--mod-version} argument to @code{ellcc}.
424
425 @item emodules_title
426 This is a string which describes the module, and can contain spaces or
427 other special characters. It is used solely for descriptive purposes,
428 and does not affect the loading of the module. The value is set by the
429 @code{--mod-title} argument to @code{ellcc}.
430 @end table
431
432 @node Loading other Modules, , Required Variables, Annatomy of a Module
433 @section Loading other Modules
434 @cindex dependancies
435 @findex modules_of_module
436 @findex emodules_load
437
438 During the loading of a module, it is the responsibility of the function
439 @code{modules_of_module} to load in any modules which the current module
440 depends on. If the module is stand-alone, and does not depend on other
441 modules, then this function can be left empty or even undeclared.
442 However, if it does have dependnacies, it must call
443 @code{emodules_load}:
444
445 @example @code
446 @cartouche
447 int emodules_load (CONST char *module,
448 CONST char *modname,
449 CONST char *modver)
450 @end cartouche
451 @end example
452
453 The first argument @var{module} is the name of the actual shared object
454 or DLL. You can omit the @file{.so}, @file{.ell} or @file{.dll}
455 extension of you wish. If you do not specify an absolute path name,
456 then the same rules as apply to loading Lisp modules are applied when
457 searching for the module. If the module cannot be found in any of the
458 standard places, and an absolute path name was not specified,
459 @code{emodules_load} will signal an error and loading of the module
460 will stop.
461
462 The second argument (@var{modname}) is the module name to load, and
463 must match the contents of the variable @var{emodule_name} in the
464 module to be loaded. A mis-match will cause the module load to fail. If
465 this parameter is @code{NULL} or empty, then no checks are performed
466 against the target module's @var{emodule_name} variable.
467
468 The last argument, @var{modver}, is the desired version of the module
469 to load, and is compared to the target module's
470 @var{emodule_version} value. If this parameter is not @code{NULL}
471 or empty, and the match fails, then the load of the module will fail.
472
473 @code{emodules_load} can be called recursively. If, at any point
474 during the loading of modules a failure is encountered, then all modules
475 that were loaded since the top level call to @code{emodules_load}
476 will be unloaded. This means that if any child modules fail to load,
477 then their parents will also fail to load. This does not include
478 previous successful calls to @code{emodules_load} at the top level.
479
480 @node Using ellcc, Defining Functions, Annatomy of a Module, Top
481 @chapter Using @code{ellcc}
482 @cindex @code{ellcc}
483 @cindex module compiler
484
485 Before discussing the anatomy of a module in greater detail, you should
486 be aware of the steps required in order to correctly compile and link a
487 module for use within @emacs{}. There is little difference between
488 compiling normal C code and compiling a module. In fact, all that
489 changes is the command used to compile the module, and a few extra
490 arguments to the compiler.
491
492 @emacs{} now ships with a new user utility, called @code{ellcc}. This
493 is the @dfn{Emacs Loadable Library C Compiler}. This is a wrapper
494 program that will invoke the real C compiler with the correct arguments
495 to compile and link your module. With the exception of a few command
496 line options, this program can be considered a replacement for your C
497 compiler. It accepts all of the same flags and arguments that your C
498 compiler does, so in many cases you can simply set the @code{make}
499 variable @code{CC} to @code{ellcc} and your code will be compiled as
500 an Emacs module rather than a static C object.
501
502 @code{ellcc} has three distinct modes of operation. It can be run in
503 compile, link or initialization mode. These modes are discussed in more
504 detail below. If you want @code{ellcc} to show the commands it is
505 executing, you can specify the option @code{--mode=verbose} to
506 @code{ellcc}. Specifying this option twice will enable certain extra
507 debugging messages to be displayed on the standard output.
508
509 @menu
510 * Compile Mode:: Compiling modules using ellcc
511 * Initialization Mode:: Generating documentation and variables
512 * Link Mode:: Creating the final loadable module
513 * Other ellcc options:: Other useful options
514 * Environment Variables:: How to control ellcc
515 @end menu
516
517 @node Compile Mode, Initialization Mode, Using ellcc, Using ellcc
518 @section Compile Mode
519 @cindex compiling
520
521 By default, @code{ellcc} is in @dfn{compile} mode. This means that it
522 assumes that all of the command line arguments are C compiler arguments,
523 and that you want to compile the specified source file or files. You
524 can force compile mode by specifying the @code{--mode=compile} argument
525 to @code{ellcc}.
526
527 In this mode, @code{ellcc} is simply a front-end to the same C compiler
528 that was used to create the @emacs{} binary itself. All @code{ellcc}
529 does in this mode is insert a few extra command line arguments before
530 the arguments you specify to @code{ellcc} itself. @code{ellcc} will
531 then invoke the C compiler to compile your module, and will return the
532 same exit codes and messages that your C compiler does.
533
534 By far the easiest way to compile modules is to construct a
535 @file{Makefile} as you would for a normal program, and simply insert, at
536 some appropriate place something similar to:
537
538 @example @code
539 @cartouche
540 CC=ellcc --mode=compile
541
542 .c.o:
543 $(CC) $(CFLAGS) -c $<
544 @end cartouche
545 @end example
546
547 After this, all you need to do is provide simple @code{make} rules for
548 compiling your module source files. Since modules are most useful when
549 they are small and self-contained, most modules will have a single
550 source file, aside from the module specific initialization file (see
551 below for details).
552
553 @node Initialization Mode, Link Mode, Compile Mode, Using ellcc
554 @section Initialization Mode
555 @cindex initialization
556 @cindex documentation
557
558 @emacs{} uses a rather bizarre way of documenting variables and
559 functions. Rather than have the documentation for compiled functions
560 and variables passed as static strings in the source code, the
561 documentation is included as a C comment. A special program, called
562 @file{make-docfile}, is used to scan the source code files and extract
563 the documentation from these comments, producing the @emacs{} @file{DOC}
564 file, which the internal help engine scans when the documentation for a
565 function or variable is requested.
566
567 Due to the internal construction of Lisp objects, subrs and other such
568 things, adding documentation for a compiled function or variable in a
569 compiled module, at any time after @emacs{} has been @dfn{dumped} is
570 somewhat problematic. Fortunately, as a module writer you are insulated
571 from the difficulties thanks to your friend @code{ellcc} and some
572 internal trickery in the module loading code. This is all done using
573 the @dfn{initialization} mode of @code{ellcc}.
574
575 The result of running @code{ellcc} in initialization mode is a C source
576 file which you compile with (you guessed it) @code{ellcc} in compile
577 mode. Initialization mode is where you set the module name, version,
578 title and gather together all of the documentaion strings for the
579 functions and vairables in your module. There are several options that
580 you are required to pass @code{ellcc} in initialization mode, the first
581 of which is the mode switch itself, @code{--mode=init}.
582
583 Next, you need to specify the name of the C source code file that
584 @code{ellcc} will produce, and you specify this using the
585 @code{--mod-output=FILENAME} argument. @var{FILENAME} is the name of
586 the C source code file that will contain the module variables and
587 @code{docs_of_module} function.
588
589 As discussed previously, each module requires a short @dfn{handle} or
590 module name. This is specified with the @code{--mod-name=NAME} option,
591 where @var{NAME} is the abbreviated module name. This @var{NAME} must
592 consist only of characters that are valid in C function and variable
593 names.
594
595 The module version is specified using @code{--mod-version=VERSION}
596 argument, with @var{VERSION} being any arbitrary version string. This
597 version can be passed as an optional second argument to the Lisp
598 function @code{load-module}, and as the third argument to the internal
599 module loading command @code{emodules_load}. This version string is
600 used to distinguish between different versions of the same module, and
601 to ensure that the module is loaded at a specific version.
602
603 Last, but not least, is the module title. Specified using the
604 @code{--mod-title=TITLE} option, the specified @var{TITLE} is used when
605 the list of loaded modules is displayed. The module title serves no
606 purpose other than to inform the user of the function of the module.
607 This string should be brief, as it has to be formatted to fit the
608 screen.
609
610 Following all of these parameters, you need to provide the list of all
611 source code modules that make up your module. These are the files which
612 are scanned by @file{make-docfile}, and provide the information required
613 to populate the @code{docs_of_module} function. Below is a sample
614 @file{Makefile} fragment which indicates how all of this is used.
615
616 @example @code
617 @cartouche
618 CC=ellcc --mode=compile
619 LD=ellcc --mode=link
620 MODINIT=ellcc --mode=init
621 CFLAGS=-O2 -DSOME_STUFF
622
623 .c.o:
624 $(CC) $(CFLAGS) -c $<
625
626 MODNAME=sample
627 MODVER=1.0.0
628 MODTITLE="Small sample module"
629
630 SRCS=modfile1.c modfile2.c modfile3.c
631 OBJS=$(SRCS:.c=.o)
632
633 all: sample.ell
634 clean:
635 rm -f $(OBJS) sample_init.o sample.ell
636
637 install: all
638 mkdir `ellcc --mod-location`/mymods > /dev/null
639 cp sample.ell `ellcc --mod-location`/mymods/sample.ell
640
641 sample.ell: $(OBJS) sample_init.o
642 $(LD) --mod-output=$@ $(OBJS) sample_init.o
643
644 sample_init.o: sample_init.c
645 sample_init.c: $(SRCS)
646 $(MODINIT) --mod-name=$(MODNAME) --mod-version=$(MODVER) \
647 --mod-title=$(MODTITLE) --mod-output=$@ $(SRCS)
648 @end cartouche
649 @end example
650
651 The above @file{Makefile} is, in fact, complete, and would compile the
652 sample module, and optionally install it. The @code{--mod-location}
653 argument to @code{ellcc} will produce, on the standard output, the base
654 location of the @emacs{} module directory. Each sub-directory of that
655 directory is automatically searched for for modules when they are loaded
656 with @code{load-module}. An alternative location would be
657 @file{/usr/local/lib/xemacs/site-modules}. That path can change
658 depending on the options the person who compiled @emacs{} chose, so you
659 can always determine the correct site location using the
660 @code{--mod-site-location} option. This directory is treated the same
661 way as the main module directory. Each sub-directory within it is
662 searched for a given module when the user attempts to load it. The
663 valid extensions that the loader attempts to use are @file{.so},
664 @file{.ell} and @file{.dll}. You can use any of these extensions,
665 although @file{.ell} is the prefered extension.
666
667 @node Link Mode, Other ellcc options, Initialization Mode, Using ellcc
668 @section Link Mode
669 @cindex linking
670
671 Once all of your source code files have been compiled (including the
672 generated init file) you need to link them all together to created the
673 loadable module. To do this, you invoke @code{ellcc} in link mode, by
674 pasing the @code{--mode-link} command. You need to specify the final
675 output file using the @code{--mod-output=NAME} command, but other than
676 that all other arguments are passed on directly to the system compiler
677 or linker, along with any other required arguments to create the
678 loadable module.
679
680 The module has complete access to all symbols that were present in the
681 dumped @emacs{}, so you do not need to link against libraries that were
682 linked in with the main executable. If your library uses some other
683 extra libraries, you will need to link with those. There is nothing
684 particularly complicated about link mode. All you need to do is make
685 sure you invoke it correctly in the @file{Makefile}. See the sample
686 @file{Makefile} above for an example of a well constructed
687 @file{Makefile} that invoked the linker correctly.
688
689 @node Other ellcc options, Environment Variables, Link Mode, Using ellcc
690 @section Other @code{ellcc} options
691 @cindex paths
692
693 Aside from the three main @code{ellcc} modes described above,
694 @code{ellcc} can accept several other options. These are typically used
695 in a @file{Makefile} to determine installation paths. @code{ellcc} also
696 allows you to over-ride several of its built-in compiler and linker
697 options using environment variables. Here is the complete list of
698 options that @code{ellcc} accepts.
699
700 @table @code
701 @item --mode=compile
702 Enables compilation mode. Use this to compile source modules.
703
704 @item --mode=link
705 Enabled link edit mode. Use this to create the final module.
706
707 @item --mode=init
708 Used to create the documentation function and to initialize other
709 required variables. Produces a C source file that must be compiled with
710 @code{ellcc} in compile mode before linking the final module.
711
712 @item --mode=verbose
713 Enables verbose mode. This will show you the commands that are being
714 executed, as well as the version number of @code{ellcc}. If you specify
715 this option twice, then some extra debugging information is displayed.
716
717 @item --mod-name=NAME
718 Sets the short internaml module @var{NAME} to the string specified,
719 which must consist only of valid C identifiers. Required during
720 initialization mode.
721
722 @item --mod-version=VERSION
723 Sets the internal module @var{VERSION} to the specified string.
724 Required during initialization mode.
725
726 @item --mod-title=TITLE
727 Sets the module descriptive @var{TITLE} to the string specified. This
728 string can contain any printable characters, but should not be too
729 long. It is required during initialization mode.
730
731 @item --mod-output=FILENAME
732 Used to control the output file name. This is used during
733 initialization mode to set the name of the C source file that will be
734 created to @var{FILENAME}. During link mode, it sets the name of the
735 final loadable module to @var{FILENAME}.
736
737 @item --mod-location
738 This will print the name of the standard module installation path on the
739 standard output and immediately exit @code{ellcc}. Use this option to
740 determine the directory prefix of where you should install your modules.
741
742 @item --mod-site-location
743 This will print the name of the site specific module location and exit.
744
745 @item --mod-archdir
746 Prints the name of the root of the architecture-dependant directory that
747 @emacs{} searches for architecture-dependant files.
748
749 @item --mod-config
750 Prints the name of the configuration for which @emacs{} and @code{ellcc}
751 were compiled.
752 @end table
753
754 @node Environment Variables, , Other ellcc options, Using ellcc
755 @section Environment Variables
756 @cindex environment variables
757
758 During its normal operation, @code{ellcc} uses the compiler and linker
759 flags that were determined at the time @emacs{} was configured. In
760 certain rare circumstances you may wish to over-ride the flags passed to
761 the compiler or linker, and you can do so using environment variables.
762 The table below lists all of the environment variables that @code{ellcc}
763 recognises.
764
765 @table @code
766 @item ELLCC
767 @cindex @code{ELLCC}
768 This is used to over-ride the name of the C compiler that is invoked by
769 @code{ellcc}.
770
771 @item ELLLD
772 @cindex @code{ELLLD}
773 Sets the name of the link editor to use to created the final module.
774
775 @item ELLCFLAGS
776 @cindex @code{ELLCFLAGS}
777 Sets the compiler flags passed on when compiling source modules. This
778 only sets the basic C compiler flags. There are certain hard-coded
779 flags that will always be passed.
780
781 @item ELLLDFLAGS
782 @cindex @code{ELLLDFLAGS}
783 Sets the flags passed on to the linker. This does @strong{not} include
784 the flags for enabling PIC mode. This just sets basic linker flags.
785
786 @item ELLDLLFLAGS
787 @cindex @code{ELLDLLFLAGS}
788 Sets the flags passed to the linker that are required to created shared
789 and loadable objects.
790
791 @item ELLPICFLAGS
792 @cindex @code{ELLPICFLAGS}
793 Sets the C compiler option required to produce an object file that is
794 suitable for including in a shared library. This option should turn on
795 PIC mode, or the moral equivalent thereof on the target system.
796
797 @item ELLMAKEDOC
798 @cindex @code{ELLMAKEDOC}
799 Sets the name of the @file{make-docfile} program to use. Usually
800 @code{ellcc} will use the version that was compiled and installed with
801 @emacs{}, but this option allows you to specify an alternative path.
802 Used during the compile phase of @emacs{} itself.
803 @end table
804
805 @node Defining Functions, Defining Variables, Using ellcc, Top
806 @chapter Defining Functions
807 @cindex defining functions
808
809 One of the main reasons you would ever write a module is to
810 provide one or more @dfn{functions} for the user or the editor to use.
811 The term
812 @dfn{function} is a bit overloaded here, as it refers to both a C
813 function and the way it appears to Lisp, which is a @dfn{subroutine}, or
814 simply a @dfn{subr}. A Lisp subr is also known as a Lisp primitive, but
815 that term applies less to dynamic modules. @xref{Writing Lisp
816 Primitives,,,internals,@emacs{} Internals Manual}, for details on how to
817 declare functions. You should familiarize yourself with the
818 instructions there. The format of the function declaration is identical
819 in modules.
820
821 Normal Lisp primitives document the functions they defining by including
822 the documentation as a C comment. During the build process, a program
823 called @file{make-docfile} is run, which will extract all of these
824 comments, build up a single large documentation file, and will store
825 pointers to the start of each documentation entry in the dumped @emacs{}.
826 This, of course, will not work for dynamic modules, as they are loaded
827 long after @emacs{} has been dumped. For this reason, we require a
828 special means for adding documentation for new subrs. This is what the
829 macro @code{CDOCSUBR} is used for, and this is used extensively during
830 @code{ellcc} initialization mode.
831
832 When using @code{DEFUN} in normal @emacs{} C code, the sixth
833 ``parameter'' is a C comment which documents the function. For a
834 dynamic module, we of course need to convert the C comment to a usable
835 string, and we need to set the documentation pointer of the subr to this
836 string. As a module programmer, you don't actually need to do any work
837 for this to happen. It is all taken care of in the
838 @code{docs_of_module} function created by @code{ellcc}.
839
840 @menu
841 * Using DEFUN:: Using the DEFUN macro to define functions
842 * Declaring Functions:: Declaring functions to the Lisp reader
843 @end menu
844
845 @node Using DEFUN, Declaring Functions, Defining Functions, Defining Functions
846 @section Using @code{DEFUN}
847 @cindex subrs
848 @findex DEFUN
849 @cindex functions, Lisp
850 @cindex functions, defining
851
852 Although the full syntax of a function declaration is discussed in the
853 @emacs{} internals manual in greater depth, what follows is a brief
854 description of how to define and implement a new Lisp primitive in a
855 module. This is done using the @code{DEFUN} macro. Here is a small
856 example:
857
858 @example @code
859 @cartouche
860 DEFUN ("my-function", Fmy_function, 1, 1, "FFile name: ", /*
861 Sample Emacs primitive function.
862
863 The specified FILE is frobricated before it is fnozzled.
864 */
865 (file))
866 @{
867 char *filename;
868
869 if (NILP(file))
870 return Qnil;
871
872 filename = (char *)XSTRING_DATA(file);
873 frob(filename);
874 return Qt;
875 @}
876 @end cartouche
877 @end example
878
879 The first argument is the name of the function as it will appear to the
880 Lisp reader. This must be provided as a string. The second argument is
881 the name of the actual C function that will be created. This is
882 typically the Lisp function name with a preceding capital @code{F}, with
883 hyphens converted to underscores. This must be a valid C function
884 name. Next come the minimum and maximum number of arguments,
885 respectively. This is used to ensure that the correct number of
886 arguments are passed to the function. Next is the @code{interactive}
887 definition. If this function is meant to be run by a user
888 interactively, then you need to specify the argument types and prompts
889 in this string. Please consult the @emacs{} Lisp manual for more
890 details. Next comes a C comment that is the documentation for this
891 function. This comment @strong{must} exist. Last comes the list of
892 function argument names, if any.
893
894 @node Declaring Functions, , Using DEFUN, Defining Functions
895 @section Declaring Functions
896 @findex DEFSUBR
897 @cindex functions, declaring
898
899 Simply writing the code for a function is not enough to make it
900 availible to the Lisp reader. You have to, during module
901 initialization, let the Lisp reader know about the new function. This
902 is done by calling @code{DEFSUBR} with the name of the function. This
903 is the sole purpose of the initialization function
904 @code{syms_of_module}. @xref{Required Functions}, for more details.
905
906 Each call to @code{DEFSUBR} takes as its only argument the name of the
907 function, which is the same as the second argument to the call to
908 @code{DEFUN}. Using the example function above, you would insert the
909 following code in the @code{syms_of_module} function:
910
911 @example @code
912 @cartouche
913 DEFSUBR(Fmy_function);
914 @end cartouche
915 @end example
916
917 This call will instruct @emacs{} to make the function visible to the Lisp
918 reader and will prepare for the insertion of the documentation into
919 the right place. Once this is done, the user can call the Lisp
920 function @code{my-function}, if it was defined as an interactive
921 function (which in this case it was).
922
923 Thats all there is to defining and announcing new functions. The rules
924 for what goes inside the functions, and how to write good modules, is
925 beyond the scope of this document. Please consult the @emacs{}
926 internals manual for more details.
927
928 @node Defining Variables, Index, Defining Functions, Top
929 @chapter Defining Variables
930 @cindex defining variables
931 @cindex defining objects
932 @findex DEFVAR_LISP
933 @findex DEFVAR_BOOL
934 @findex DEFVAR_INT
935 @cindex variables, Lisp
936 @cindex variables, defining
937 @cindex objects, defining
938 @cindex objects, Lisp
939
940 Rarely will you write a module that only contains functions. It is
941 common to also provide variables which can be used to control the
942 behaviour of the function, or store the results of the function being
943 executed. The actual C variable types are the same for modules
944 and internal @emacs{} primitives, and the declaration of the variables
945 is identical.
946
947 @xref{Adding Global Lisp Variables,,,internals,XEmacs Internals Manual},
948 for more information on variables and naming conventions.
949
950 Once your variables are defined, you need to initialize them and make
951 the Lisp reader aware of them. This is done in the
952 @code{vars_of_module} initialization function using special @emacs{}
953 macros such as @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}, @code{DEFVAR_INT}
954 etc. The best way to see how to use these macros is to look at existing
955 source code, or read the internals manual.
956
957 One @emph{very} important difference between @emacs{} variables and
958 module variables is how you use pure space. Simply put, you
959 @strong{never} use pure space in @emacs{} modules. The pure space
960 storage is of a limited size, and is initialized propperly during the
961 dumping of @emacs{}. Because variables are being added dynamically to
962 an already running @emacs{} when you load a module, you cannot use pure
963 space. Be warned: @strong{do not use pure space in modules. Repeat, do
964 not use pure space in modules.} Once again, to remove all doubts:
965 @strong{DO NOT USE PURE SPACE IN MODULES!!!}
966
967 Below is a small example which declares and initializes two
968 variables. You will note that this code takes into account the fact
969 that this module may very well be compiled into @emacs{} itself. This
970 is a prudent thing to do.
971
972 @example @code
973 @cartouche
974 Lisp_Object Vsample_string;
975 int sample_boolean;
976
977 void
978 vars_of_module()
979 @{
980 DEFVAR_LISP ("sample-string", &Vsample_string /*
981 This is a sample string, declared in a module.
982
983 Nothing magical about it.
984 */);
985
986 DEFVAR_BOOL("sample-boolean", &sample_boolean /*
987 *Sample user-settable boolean.
988 */);
989
990 sample_boolean = 0;
991 Vsample_string = build_string("My string");
992 @}
993 @end cartouche
994 @end example
995
996 @c Print the tables of contents
997 @contents
998 @c That's all
999
1000 @node Index, , Defining Variables, Top
1001 @unnumbered Index
1002
1003 @printindex cp
1004
1005 @bye
1006