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