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