1 This is ../info/emodules.info, produced by makeinfo version 4.6 from
4 This file documents the module loading technology of XEmacs.
6 Copyright (C) 1998 J. Kean Johnston.
8 Permission is granted to make and distribute verbatim copies of this
9 manual provided the copyright notice and this permission notice are
10 preserved on all copies.
12 Permission is granted to copy and distribute modified versions of
13 this manual under the conditions for verbatim copying, provided that the
14 entire resulting derived work is distributed under the terms of a
15 permission notice identical to this one.
17 Permission is granted to copy and distribute translations of this
18 manual into another language, under the above conditions for modified
19 versions, except that this permission notice may be stated in a
20 translation approved by the Foundation.
22 Permission is granted to copy and distribute modified versions of
23 this manual under the conditions for verbatim copying, provided also
24 that the section entitled "GNU General Public License" is included
25 exactly as in the original, and provided that the entire resulting
26 derived work is distributed under the terms of a permission notice
27 identical to this one.
29 Permission is granted to copy and distribute translations of this
30 manual into another language, under the above conditions for modified
31 versions, except that the section entitled "GNU General Public License"
32 may be included in a translation approved by the Free Software
33 Foundation instead of in the original English.
36 File: emodules.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
38 This Info file contains v1.0 of the XEmacs dynamic loadable module
39 support documentation.
43 * Introduction:: Introducing Emacs Modules
44 * Anatomy of a Module:: Basic module layout and technology
45 * Using ellcc:: How to use the module compiler
46 * Defining Functions:: Creating new Lisp primitives
47 * Defining Variables:: Creating new Lisp variables
48 * Index:: Concept Index
50 --- The Detailed Node Listing ---
54 * Required Header File:: Always include <emodules.h>
55 * Required Functions:: Functions you must always provide
56 * Required Variables:: Variables whose values you must provide
57 * Loading other Modules:: How to load dependent modules
61 * Compile Mode:: Compiling modules using ellcc
62 * Initialization Mode:: Generating documentation and variables
63 * Link Mode:: Creating the final loadable module
64 * Other ellcc options:: Other useful options
65 * Environment Variables:: How to control ellcc
69 * Using DEFUN:: Using the DEFUN macro to define functions
70 * Declaring Functions:: Declaring functions to the Lisp reader
73 File: emodules.info, Node: Introduction, Next: Anatomy of a Module, Prev: Top, Up: Top
78 XEmacs is a powerful, extensible editor. The traditional way of
79 extending the functionality of XEmacs is to use its built-in Lisp
80 language (called Emacs Lisp, or Elisp for short). However, while Elisp
81 is a full programming language and capable of extending XEmacs in more
82 ways than you can imagine, it does have its short-comings.
84 Firstly, Elisp is an interpreted language, and this has serious speed
85 implications. Like all other interpreted languages (like Java), Elisp
86 is often suitable only for certain types of application or extension.
87 So although Elisp is a general purpose language, and very high level,
88 there are times when it is desirable to descend to a lower level
89 compiled language for speed purposes.
91 Secondly, Elisp (or Lisp in general) is not a very common language
92 any more, except for certain circles in the computer industry. C is a
93 far more commonly known language, and because it is compiled, more
94 suited to a wider range of applications, especially those that require
95 low level access to a system or need to be as quick as possible.
97 This manual describes a new way of extending XEmacs, by using dynamic
98 loadable modules (also known as dynamically loadable libraries (DLLs),
99 dynamic shared objects (DSOs) or just simply shared objects), which can
100 be written in C or C++ and loaded into XEmacs at any time. I sometimes
101 refer to this technology as "CEmacs", which is short for "C Extensible
104 XEmacs modules are configured into and installed with XEmacs by
105 default on all systems that support loading of shared objects. From a
106 users perspective, the internals of XEmacs modules are irrelevant. All
107 a user will ever need to know about shared objects is the name of the
108 shared object when they want to load a given module. From a developers
109 perspective though, a lot more is provided.
111 * Of primary interest is the `ellcc' program. This program is
112 created during compile time, and is intended to abstract compiler
113 specific characteristics from the developer. This program is
114 called to compile and link all objects that will make up the final
115 shared object, and accepts all common C compiler flags. `ellcc'
116 also sets up the correct environment for compiling modules by
117 enabling any special compiler modes (such as PIC mode), setting
118 the correct include paths for the location of XEmacs internal
119 header files etc. The program will also invoke the linker
120 correctly to created the final shared object which is loaded into
123 * CEmacs also makes all of the relevant XEmacs internal header
124 files available for module authors to use. This is often required
125 to get data structure definitions and external variable
126 declarations. The header files installed include the module
127 specific header file `emodules.h'. Due to the nature of dynamic
128 modules, most of the internals of XEmacs are exposed. *Note Top:
129 (internals)Top, for a more complete discussion on how to extend
130 and understand XEmacs. All of the rules for C modules are
133 * Part of the XEmacs distribution is a set of sample modules.
134 These are not installed when XEmacs is, but remain in the XEmacs
135 source tree. These modules live in the directory `modules', which
136 is a sub-directory of the main XEmacs source code directory.
137 Please look at the samples carefully, and maybe even use them as a
138 basis for making your own modules. Most of the concepts required
139 for writing extension modules are covered in the samples.
141 * Last, but not least is this manual. This can be viewed from
142 within XEmacs, and it can be printed out as well. It is the
143 intention of this document that it will describe everything you
144 need to know about extending XEmacs in C. If you do not find this
145 to be the case, please contact the author(s).
147 The rest of this document will discuss the actual mechanics of
148 XEmacs modules and work through several of the samples. Please be sure
149 that you have read the XEmacs Internals Manual and understand
150 everything in it. The concepts there apply to all modules. This
151 document may have some overlap, but it is the internals manual which
152 should be considered the final authority. It will also help a great
153 deal to look at the actual XEmacs source code to see how things are
157 File: emodules.info, Node: Anatomy of a Module, Next: Using ellcc, Prev: Introduction, Up: Top
162 Each dynamically loadable XEmacs extension (hereafter referred to as a
163 module) has a certain compulsory format, and must contain several
164 pieces of information and several mandatory functions. This chapter
165 describes the basic layout of a module, and provides a very simple
166 sample. The source for this sample can be found in the file
167 `modules/simple/sample.c' in the main XEmacs source code tree.
171 * Required Header File:: Always include <emodules.h>
172 * Required Functions:: Functions you must always provide
173 * Required Variables:: Variables whose values you must provide
174 * Loading other Modules:: How to load dependent modules
177 File: emodules.info, Node: Required Header File, Next: Required Functions, Prev: Anatomy of a Module, Up: Anatomy of a Module
182 Every module must include the file `<emodules.h>'. This will include
183 several other XEmacs internal header files, and will set up certain
184 vital macros. One of the most important files included by `emodules.h'
185 is the generated `config.h' file, which contains all of the required
186 system abstraction macros and definitions. Most modules will probably
187 require some pre-processor conditionals based on constants defined in
188 `config.h'. Please read that file to familiarize yourself with the
189 macros defined there.
191 Depending on exactly what your module will be doing, you will
192 probably need to include one or more of the XEmacs internal header
193 files. When you `#include <emodules.h>', you will get a few of the
194 most important XEmacs header files included automatically for you. The
198 This file contains most of the macros required for declaring Lisp
199 object types, macros for accessing Lisp objects, and global
200 variable declarations.
203 All system dependent declarations and abstraction macros live
204 here. You should never call low level system functions directly.
205 Rather, you should use the abstraction macros provided in this
209 This header file defines the window structures and Lisp types, and
210 provides functions and macros for manipulating multiple XEmacs
214 All macros and function declarations for manipulating internal and
215 user visible buffers appear in this file.
218 This header provides the information required for performing text
219 insertion and deletion.
222 Provides the required structure, macro and function definitions for
223 manipulating XEmacs frames.
226 File: emodules.info, Node: Required Functions, Next: Required Variables, Prev: Required Header File, Up: Anatomy of a Module
231 Every module requires several initialization functions. It is the
232 responsibility of these functions to load in any dependent modules, and
233 to declare all variables and functions which are to be made visible to
234 the XEmacs Lisp reader. Each of these functions performs a very
235 specific task, and they are executed in the correct order by XEmacs.
236 All of these functions are `void' functions which take no arguments.
237 Here, briefly, are the required module functions. Note that the actual
238 function names do not end with the string `_module', but rather they
239 end with the abbreviated module name by which the module is known.
240 More on the module name and its importance later. Just bear in mind
241 that the text `_module' in the functions below is simply a
242 place-holder, not an actual function name.
245 This required function is responsible for introducing to the Lisp
246 reader all functions that you have defined in your module using
247 `DEFUN()'. Note that _only_ functions are declared here, using
248 the `DEFSUBR()' macro. No variables are declared.
251 This required function contains calls to macros such as
252 `DEFVAR_LISP()', `DEFVAR_BOOL()' etc, and its purpose is to
253 declare and initialize all and any variables that your module
254 defines. They syntax for declaring variables is identical to the
255 syntax used for all internal XEmacs source code. If the module is
256 intended to be usable statically linked into XEmacs, the actions
257 of this function are severely restricted. *Note General Coding
258 Rules: (internals)General Coding Rules. Also see the comments in
259 `src/emacs.c' (`main_1'). Modules which perform initializations
260 not permitted by these rules will probably work, but dual-use
261 (dynamic loading and static linking) modules will require very
262 careful, and possibly fragile, coding.
265 This optional function should be used to load in any modules which
266 your module depends on. The XEmacs module loading code makes sure
267 that the same module is not loaded twice, so several modules can
268 safely call the module load function for the same module. Only
269 one copy of each module (at a given version) will ever be loaded.
272 This is a required function, but not one which you need ever write.
273 This function is created automatically by `ellcc' when the module
274 initialization code is produced. It is required to document all
275 functions and variables declared in your module.
278 File: emodules.info, Node: Required Variables, Next: Loading other Modules, Prev: Required Functions, Up: Anatomy of a Module
283 Not only does a module need to declare the initialization functions
284 mentioned above, it is also required to provide certain variables which
285 the module loading code searches for in order to determine the viability
286 of a module. You are _not_ required to provide these variables in your
287 source files. They are automatically set up in the module
288 initialization file by the `ellcc' compiler. These variables are
289 discussed here simply for the sake of completeness.
292 This is a variable of type `long', and is used to indicate the
293 version of the XEmacs loading technology that was used to produce
294 the module being loaded. This version number is completely
295 unrelated to the XEmacs version number, as a given module may
296 quite well work regardless of the version of XEmacs that was
297 installed at the time the module was created.
299 The XEmacs modules version is used to differentiate between major
300 changes in the module loading technology, not versions of XEmacs.
303 This is a short (typically 10 characters or less) name for the
304 module, and it is used as a suffix for all of the required
305 functions. This is also the name by which the module is
306 recognized when loading dependent modules. The name does not
307 necessarily have to be the same as the physical file name,
308 although keeping the two names in sync is a pretty good idea. The
309 name must not be empty, and it must be a valid part of a C
310 function name. The value of this variable is appended to the
311 function names `syms_of_', `vars_of_', `modules_of_' and
312 `docs_of_' to form the actual function names that the module
313 loading code looks for when loading a module.
315 This variable is set by the `--mod-name' argument to `ellcc'.
318 This string variable is used to load specific versions of a module.
319 Rarely will two or more versions of a module be left lying around,
320 but just in case this does happen, this variable can be used to
321 control exactly which module should be loaded. See the Lisp
322 function `load-module' for more details. This variable is set by
323 the `--mod-version' argument to `ellcc'.
326 This is a string which describes the module, and can contain
327 spaces or other special characters. It is used solely for
328 descriptive purposes, and does not affect the loading of the
329 module. The value is set by the `--mod-title' argument to `ellcc'.
332 File: emodules.info, Node: Loading other Modules, Prev: Required Variables, Up: Anatomy of a Module
334 Loading other Modules
335 =====================
337 During the loading of a module, it is the responsibility of the function
338 `modules_of_module' to load in any modules which the current module
339 depends on. If the module is stand-alone, and does not depend on other
340 modules, then this function can be left empty or even undeclared.
341 However, if it does have dependencies, it must call `emodules_load':
343 int emodules_load (const char *module,
347 The first argument MODULE is the name of the actual shared object or
348 DLL. You can omit the `.so', `.ell' or `.dll' extension of you wish.
349 If you do not specify an absolute path name, then the same rules as
350 apply to loading Lisp modules are applied when searching for the
351 module. If the module cannot be found in any of the standard places,
352 and an absolute path name was not specified, `emodules_load' will
353 signal an error and loading of the module will stop.
355 The second argument (MODNAME) is the module name to load, and must
356 match the contents of the variable EMODULE_NAME in the module to be
357 loaded. A mis-match will cause the module load to fail. If this
358 parameter is `NULL' or empty, then no checks are performed against the
359 target module's EMODULE_NAME variable.
361 The last argument, MODVER, is the desired version of the module to
362 load, and is compared to the target module's EMODULE_VERSION value. If
363 this parameter is not `NULL' or empty, and the match fails, then the
364 load of the module will fail.
366 `emodules_load' can be called recursively. If, at any point during
367 the loading of modules a failure is encountered, then all modules that
368 were loaded since the top level call to `emodules_load' will be
369 unloaded. This means that if any child modules fail to load, then
370 their parents will also fail to load. This does not include previous
371 successful calls to `emodules_load' at the top level.
373 *Warning:* Modules are _not_ loaded with the `RTLD_GLOBAL' flag.
374 The practical upshot is that individual modules do not have access to
375 each other's C symbols. One module cannot make a C function call to a
376 function defined in another module, nor can it read or set a C variable
377 in another module. All interaction between modules must, therefore,
378 take place at the Lisp level. This is by design. Other projects have
379 attempted to use `RTLD_GLOBAL', only to find that spurious symbol name
380 clashes were the result. Helper functions often have simple names,
381 increasing the probability of such a clash. If you really need to
382 share symbols between modules, create a shared library containing those
383 symbols, and link your modules with that library. Otherwise,
384 interactions between modules must take place via Lisp function calls
385 and Lisp variables accesses.
388 File: emodules.info, Node: Using ellcc, Next: Defining Functions, Prev: Anatomy of a Module, Up: Top
393 Before discussing the anatomy of a module in greater detail, you should
394 be aware of the steps required in order to correctly compile and link a
395 module for use within XEmacs. There is little difference between
396 compiling normal C code and compiling a module. In fact, all that
397 changes is the command used to compile the module, and a few extra
398 arguments to the compiler.
400 XEmacs now ships with a new user utility, called `ellcc'. This is
401 the "Emacs Loadable Library C Compiler". This is a wrapper program
402 that will invoke the real C compiler with the correct arguments to
403 compile and link your module. With the exception of a few command line
404 options, this program can be considered a replacement for your C
405 compiler. It accepts all of the same flags and arguments that your C
406 compiler does, so in many cases you can simply set the `make' variable
407 `CC' to `ellcc' and your code will be compiled as an Emacs module
408 rather than a static C object.
410 `ellcc' has three distinct modes of operation. It can be run in
411 compile, link or initialization mode. These modes are discussed in more
412 detail below. If you want `ellcc' to show the commands it is
413 executing, you can specify the option `--mode=verbose' to `ellcc'.
414 Specifying this option twice will enable certain extra debugging
415 messages to be displayed on the standard output.
419 * Compile Mode:: Compiling modules using ellcc
420 * Initialization Mode:: Generating documentation and variables
421 * Link Mode:: Creating the final loadable module
422 * Other ellcc options:: Other useful options
423 * Environment Variables:: How to control ellcc
426 File: emodules.info, Node: Compile Mode, Next: Initialization Mode, Prev: Using ellcc, Up: Using ellcc
431 By default, `ellcc' is in "compile" mode. This means that it assumes
432 that all of the command line arguments are C compiler arguments, and
433 that you want to compile the specified source file or files. You can
434 force compile mode by specifying the `--mode=compile' argument to
437 In this mode, `ellcc' is simply a front-end to the same C compiler
438 that was used to create the XEmacs binary itself. All `ellcc' does in
439 this mode is insert a few extra command line arguments before the
440 arguments you specify to `ellcc' itself. `ellcc' will then invoke the
441 C compiler to compile your module, and will return the same exit codes
442 and messages that your C compiler does.
444 By far the easiest way to compile modules is to construct a
445 `Makefile' as you would for a normal program, and simply insert, at
446 some appropriate place something similar to:
448 CC=ellcc --mode=compile
451 $(CC) $(CFLAGS) -c $<
453 After this, all you need to do is provide simple `make' rules for
454 compiling your module source files. Since modules are most useful when
455 they are small and self-contained, most modules will have a single
456 source file, aside from the module specific initialization file (see
460 File: emodules.info, Node: Initialization Mode, Next: Link Mode, Prev: Compile Mode, Up: Using ellcc
465 XEmacs uses a rather bizarre way of documenting variables and
466 functions. Rather than have the documentation for compiled functions
467 and variables passed as static strings in the source code, the
468 documentation is included as a C comment. A special program, called
469 `make-docfile', is used to scan the source code files and extract the
470 documentation from these comments, producing the XEmacs `DOC' file,
471 which the internal help engine scans when the documentation for a
472 function or variable is requested.
474 Due to the internal construction of Lisp objects, subrs and other
475 such things, adding documentation for a compiled function or variable
476 in a compiled module, at any time after XEmacs has been "dumped" is
477 somewhat problematic. Fortunately, as a module writer you are insulated
478 from the difficulties thanks to your friend `ellcc' and some internal
479 trickery in the module loading code. This is all done using the
480 "initialization" mode of `ellcc'.
482 The result of running `ellcc' in initialization mode is a C source
483 file which you compile with (you guessed it) `ellcc' in compile mode.
484 Initialization mode is where you set the module name, version, title
485 and gather together all of the documentation strings for the functions
486 and variables in your module. There are several options that you are
487 required to pass `ellcc' in initialization mode, the first of which is
488 the mode switch itself, `--mode=init'.
490 Next, you need to specify the name of the C source code file that
491 `ellcc' will produce, and you specify this using the
492 `--mod-output=FILENAME' argument. FILENAME is the name of the C source
493 code file that will contain the module variables and `docs_of_module'
496 As discussed previously, each module requires a short "handle" or
497 module name. This is specified with the `--mod-name=NAME' option,
498 where NAME is the abbreviated module name. This NAME must consist only
499 of characters that are valid in C function and variable names.
501 The module version is specified using `--mod-version=VERSION'
502 argument, with VERSION being any arbitrary version string. This
503 version can be passed as an optional second argument to the Lisp
504 function `load-module', and as the third argument to the internal
505 module loading command `emodules_load'. This version string is used to
506 distinguish between different versions of the same module, and to
507 ensure that the module is loaded at a specific version.
509 Last, but not least, is the module title. Specified using the
510 `--mod-title=TITLE' option, the specified TITLE is used when the list
511 of loaded modules is displayed. The module title serves no purpose
512 other than to inform the user of the function of the module. This
513 string should be brief, as it has to be formatted to fit the screen.
515 Following all of these parameters, you need to provide the list of
516 all source code modules that make up your module. These are the files
517 which are scanned by `make-docfile', and provide the information
518 required to populate the `docs_of_module' function. Below is a sample
519 `Makefile' fragment which indicates how all of this is used.
521 CC=ellcc --mode=compile
523 MODINIT=ellcc --mode=init
524 CFLAGS=-O2 -DSOME_STUFF
527 $(CC) $(CFLAGS) -c $<
531 MODTITLE="Small sample module"
533 SRCS=modfile1.c modfile2.c modfile3.c
538 rm -f $(OBJS) sample_init.o sample.ell
541 mkdir `ellcc --mod-location`/mymods > /dev/null
542 cp sample.ell `ellcc --mod-location`/mymods/sample.ell
544 sample.ell: $(OBJS) sample_init.o
545 $(LD) --mod-output=$ $(OBJS) sample_init.o
547 sample_init.o: sample_init.c
548 sample_init.c: $(SRCS)
549 $(MODINIT) --mod-name=$(MODNAME) --mod-version=$(MODVER) \
550 --mod-title=$(MODTITLE) --mod-output=$ $(SRCS)
552 The above `Makefile' is, in fact, complete, and would compile the
553 sample module, and optionally install it. The `--mod-location'
554 argument to `ellcc' will produce, on the standard output, the base
555 location of the XEmacs module directory. Each sub-directory of that
556 directory is automatically searched for modules when they are loaded
557 with `load-module'. An alternative location would be
558 `/usr/local/lib/xemacs/site-modules'. That path can change depending
559 on the options the person who compiled XEmacs chose, so you can always
560 determine the correct site location using the `--mod-site-location'
561 option. This directory is treated the same way as the main module
562 directory. Each sub-directory within it is searched for a given module
563 when the user attempts to load it. The valid extensions that the
564 loader attempts to use are `.so', `.ell' and `.dll'. You can use any
565 of these extensions, although `.ell' is the preferred extension.
568 File: emodules.info, Node: Link Mode, Next: Other ellcc options, Prev: Initialization Mode, Up: Using ellcc
573 Once all of your source code files have been compiled (including the
574 generated init file) you need to link them all together to create the
575 loadable module. To do this, you invoke `ellcc' in link mode, by
576 passing the `--mode=link' option. You need to specify the final output
577 file using the `--mod-output=NAME' option, but other than that all
578 other arguments are passed on directly to the system compiler or
579 linker, along with any other required arguments to create the loadable
582 The module has complete access to all symbols that were present in
583 the dumped XEmacs, so you do not need to link against libraries that
584 were linked in with the main executable. If your library uses some
585 other extra libraries, you will need to link with those. There is
586 nothing particularly complicated about link mode. All you need to do
587 is make sure you invoke it correctly in the `Makefile'. See the sample
588 `Makefile' above for an example of a well constructed `Makefile' that
589 invoked the linker correctly.
592 File: emodules.info, Node: Other ellcc options, Next: Environment Variables, Prev: Link Mode, Up: Using ellcc
594 Other `ellcc' options
595 =====================
597 Aside from the three main `ellcc' modes described above, `ellcc' can
598 accept several other options. These are typically used in a `Makefile'
599 to determine installation paths. `ellcc' also allows you to over-ride
600 several of its built-in compiler and linker options using environment
601 variables. Here is the complete list of options that `ellcc' accepts.
604 Enables compilation mode. Use this to compile source modules.
607 Enabled link edit mode. Use this to create the final module.
610 Used to create the documentation function and to initialize other
611 required variables. Produces a C source file that must be
612 compiled with `ellcc' in compile mode before linking the final
616 Enables verbose mode. This will show you the commands that are
617 being executed, as well as the version number of `ellcc'. If you
618 specify this option twice, then some extra debugging information
622 Sets the short internal module NAME to the string specified, which
623 must consist only of valid C identifiers. Required during
626 `--mod-version=VERSION'
627 Sets the internal module VERSION to the specified string.
628 Required during initialization mode.
631 Sets the module descriptive TITLE to the string specified. This
632 string can contain any printable characters, but should not be too
633 long. It is required during initialization mode.
635 `--mod-output=FILENAME'
636 Used to control the output file name. This is used during
637 initialization mode to set the name of the C source file that will
638 be created to FILENAME. During link mode, it sets the name of the
639 final loadable module to FILENAME.
642 This will print the name of the standard module installation path
643 on the standard output and immediately exit `ellcc'. Use this
644 option to determine the directory prefix of where you should
645 install your modules.
647 `--mod-site-location'
648 This will print the name of the site specific module location and
652 Prints the name of the root of the architecture-dependent
653 directory that XEmacs searches for architecture-dependent files.
656 Prints the name of the configuration for which XEmacs and `ellcc'
660 File: emodules.info, Node: Environment Variables, Prev: Other ellcc options, Up: Using ellcc
662 Environment Variables
663 =====================
665 During its normal operation, `ellcc' uses the compiler and linker flags
666 that were determined at the time XEmacs was configured. In certain
667 rare circumstances you may wish to over-ride the flags passed to the
668 compiler or linker, and you can do so using environment variables. The
669 table below lists all of the environment variables that `ellcc'
673 This is used to over-ride the name of the C compiler that is
677 Sets the name of the link editor to use to created the final
681 Sets the compiler flags passed on when compiling source modules.
682 This only sets the basic C compiler flags. There are certain
683 hard-coded flags that will always be passed.
686 Sets the flags passed on to the linker. This does *not* include
687 the flags for enabling PIC mode. This just sets basic linker
691 Sets the flags passed to the linker that are required to created
692 shared and loadable objects.
695 Sets the C compiler option required to produce an object file that
696 is suitable for including in a shared library. This option should
697 turn on PIC mode, or the moral equivalent thereof on the target
701 Sets the name of the `make-docfile' program to use. Usually
702 `ellcc' will use the version that was compiled and installed with
703 XEmacs, but this option allows you to specify an alternative path.
704 Used during the compile phase of XEmacs itself.
707 File: emodules.info, Node: Defining Functions, Next: Defining Variables, Prev: Using ellcc, Up: Top
712 One of the main reasons you would ever write a module is to provide one
713 or more "functions" for the user or the editor to use. The term
714 "function" is a bit overloaded here, as it refers to both a C function
715 and the way it appears to Lisp, which is a "subroutine", or simply a
716 "subr". A Lisp subr is also known as a Lisp primitive, but that term
717 applies less to dynamic modules. *Note Writing Lisp Primitives:
718 (internals)Writing Lisp Primitives, for details on how to declare
719 functions. You should familiarize yourself with the instructions
720 there. The format of the function declaration is identical in modules.
722 Normal Lisp primitives document the functions they defining by
723 including the documentation as a C comment. During the build process,
724 a program called `make-docfile' is run, which will extract all of these
725 comments, build up a single large documentation file, and will store
726 pointers to the start of each documentation entry in the dumped XEmacs.
727 This, of course, will not work for dynamic modules, as they are loaded
728 long after XEmacs has been dumped. For this reason, we require a
729 special means for adding documentation for new subrs. This is what the
730 macro `CDOCSUBR' is used for, and this is used extensively during
731 `ellcc' initialization mode.
733 When using `DEFUN' in normal XEmacs C code, the sixth "parameter" is
734 a C comment which documents the function. For a dynamic module, we of
735 course need to convert the C comment to a usable string, and we need to
736 set the documentation pointer of the subr to this string. As a module
737 programmer, you don't actually need to do any work for this to happen.
738 It is all taken care of in the `docs_of_module' function created by
743 * Using DEFUN:: Using the DEFUN macro to define functions
744 * Declaring Functions:: Declaring functions to the Lisp reader
747 File: emodules.info, Node: Using DEFUN, Next: Declaring Functions, Prev: Defining Functions, Up: Defining Functions
752 Although the full syntax of a function declaration is discussed in the
753 XEmacs internals manual in greater depth, what follows is a brief
754 description of how to define and implement a new Lisp primitive in a
755 module. This is done using the `DEFUN' macro. Here is a small example:
757 DEFUN ("my-function", Fmy_function, 1, 1, "FFile name: ", /*
758 Sample Emacs primitive function.
760 The specified FILE is frobnicated before it is fnozzled.
769 filename = (char *)XSTRING_DATA(file);
774 The first argument is the name of the function as it will appear to
775 the Lisp reader. This must be provided as a string. The second
776 argument is the name of the actual C function that will be created.
777 This is typically the Lisp function name with a preceding capital `F',
778 with hyphens converted to underscores. This must be a valid C function
779 name. Next come the minimum and maximum number of arguments,
780 respectively. This is used to ensure that the correct number of
781 arguments are passed to the function. Next is the `interactive'
782 definition. If this function is meant to be run by a user
783 interactively, then you need to specify the argument types and prompts
784 in this string. Please consult the XEmacs Lisp manual for more
785 details. Next comes a C comment that is the documentation for this
786 function. This comment *must* exist. Last comes the list of function
787 argument names, if any.
790 File: emodules.info, Node: Declaring Functions, Prev: Using DEFUN, Up: Defining Functions
795 Simply writing the code for a function is not enough to make it
796 available to the Lisp reader. You have to, during module
797 initialization, let the Lisp reader know about the new function. This
798 is done by calling `DEFSUBR' with the name of the function. This is
799 the sole purpose of the initialization function `syms_of_module'.
800 *Note Required Functions::, for more details.
802 Each call to `DEFSUBR' takes as its only argument the name of the
803 function, which is the same as the second argument to the call to
804 `DEFUN'. Using the example function above, you would insert the
805 following code in the `syms_of_module' function:
807 DEFSUBR(Fmy_function);
809 This call will instruct XEmacs to make the function visible to the
810 Lisp reader and will prepare for the insertion of the documentation into
811 the right place. Once this is done, the user can call the Lisp
812 function `my-function', if it was defined as an interactive function
813 (which in this case it was).
815 Thats all there is to defining and announcing new functions. The
816 rules for what goes inside the functions, and how to write good
817 modules, is beyond the scope of this document. Please consult the
818 XEmacs internals manual for more details.
821 File: emodules.info, Node: Defining Variables, Next: Index, Prev: Defining Functions, Up: Top
826 Rarely will you write a module that only contains functions. It is
827 common to also provide variables which can be used to control the
828 behavior of the function, or store the results of the function being
829 executed. The actual C variable types are the same for modules and
830 internal XEmacs primitives, and the declaration of the variables is
833 *Note Adding Global Lisp Variables: (internals)Adding Global Lisp
834 Variables, for more information on variables and naming conventions.
836 Once your variables are defined, you need to initialize them and make
837 the Lisp reader aware of them. This is done in the `vars_of_module'
838 initialization function using special XEmacs macros such as
839 `DEFVAR_LISP', `DEFVAR_BOOL', `DEFVAR_INT' etc. The best way to see
840 how to use these macros is to look at existing source code, or read the
843 One _very_ important difference between XEmacs variables and module
844 variables is how you use pure space. Simply put, you *never* use pure
845 space in XEmacs modules. The pure space storage is of a limited size,
846 and is initialized properly during the dumping of XEmacs. Because
847 variables are being added dynamically to an already running XEmacs when
848 you load a module, you cannot use pure space. Be warned: *do not use
849 pure space in modules. Repeat, do not use pure space in modules.*
850 Once again, to remove all doubts: *DO NOT USE PURE SPACE IN MODULES!!!*
852 Below is a small example which declares and initializes two
853 variables. You will note that this code takes into account the fact
854 that this module may very well be compiled into XEmacs itself. This is
855 a prudent thing to do.
857 Lisp_Object Vsample_string;
863 DEFVAR_LISP ("sample-string", &Vsample_string /*
864 This is a sample string, declared in a module.
866 Nothing magical about it.
869 DEFVAR_BOOL("sample-boolean", &sample_boolean /*
870 *Sample user-settable boolean.
874 Vsample_string = build_string("My string");
878 File: emodules.info, Node: Index, Prev: Defining Variables, Up: Top
885 * anatomy: Anatomy of a Module.
886 * compiler: Introduction.
887 * compiling: Compile Mode.
888 * config.h: Required Header File.
889 * defining functions: Defining Functions.
890 * defining objects: Defining Variables.
891 * defining variables: Defining Variables.
892 * DEFSUBR: Declaring Functions.
893 * DEFUN: Using DEFUN.
894 * DEFVAR_BOOL: Defining Variables.
895 * DEFVAR_INT: Defining Variables.
896 * DEFVAR_LISP: Defining Variables.
897 * dependencies: Loading other Modules.
899 * docs_of_module: Required Functions.
900 * documentation <1>: Initialization Mode.
901 * documentation: Introduction.
903 * ELLCC: Environment Variables.
904 * ellcc <1>: Using ellcc.
905 * ellcc: Introduction.
906 * ELLCFLAGS: Environment Variables.
907 * ELLDLLFLAGS: Environment Variables.
908 * ELLLD: Environment Variables.
909 * ELLLDFLAGS: Environment Variables.
910 * ELLMAKEDOC: Environment Variables.
911 * ELLPICFLAGS: Environment Variables.
912 * Emacs Modules: Introduction.
913 * emodules.h: Required Header File.
914 * emodules_load: Loading other Modules.
915 * environment variables: Environment Variables.
916 * format, module: Anatomy of a Module.
917 * functions, declaring: Declaring Functions.
918 * functions, defining: Using DEFUN.
919 * functions, Lisp: Using DEFUN.
920 * functions, required: Required Functions.
921 * header files: Introduction.
922 * help: Introduction.
923 * include files: Required Header File.
924 * initialization <1>: Initialization Mode.
925 * initialization <2>: Required Variables.
926 * initialization: Required Functions.
927 * linker: Introduction.
928 * linking: Link Mode.
929 * module compiler: Using ellcc.
930 * module format: Anatomy of a Module.
931 * module skeleton: Anatomy of a Module.
932 * modules_of_module <1>: Loading other Modules.
933 * modules_of_module: Required Functions.
934 * objects, defining: Defining Variables.
935 * objects, Lisp: Defining Variables.
936 * paths: Other ellcc options.
937 * required functions: Required Functions.
938 * required header: Required Header File.
939 * required variables: Required Variables.
940 * samples: Introduction.
941 * shared object: Introduction.
942 * skeleton, module: Anatomy of a Module.
943 * subrs: Using DEFUN.
944 * syms_of_module: Required Functions.
945 * variables, defining: Defining Variables.
946 * variables, Lisp: Defining Variables.
947 * variables, required: Required Variables.
948 * vars_of_module: Required Functions.
954 Node: Introduction
\7f2883
955 Node: Anatomy of a Module
\7f7388
956 Node: Required Header File
\7f8199
957 Node: Required Functions
\7f10115
958 Node: Required Variables
\7f12836
959 Node: Loading other Modules
\7f15519
960 Node: Using ellcc
\7f18432
961 Node: Compile Mode
\7f20223
962 Node: Initialization Mode
\7f21588
963 Node: Link Mode
\7f26615
964 Node: Other ellcc options
\7f27757
965 Node: Environment Variables
\7f30333
966 Node: Defining Functions
\7f32022
967 Node: Using DEFUN
\7f34030
968 Node: Declaring Functions
\7f35738
969 Node: Defining Variables
\7f37078