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