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