* Menu:
* Introduction:: Introducing Emacs Modules
-* Annatomy of a Module:: Basic module layout and technology
+* Anatomy of a Module:: Basic module layout and technology
* Using ellcc:: How to use the module compiler
* Defining Functions:: Creating new Lisp primitives
* Defining Variables:: Creating new Lisp variables
--- The Detailed Node Listing ---
-Annatomy of a Module
+Anatomy of a Module
* Required Header File:: Always include <emodules.h>
* Required Functions:: Functions you must always provide
* Required Variables:: Variables whose values you must provide
-* Loading other Modules:: How to load dependant modules
+* Loading other Modules:: How to load dependent modules
Using `ellcc'
* Declaring Functions:: Declaring functions to the Lisp reader
\1f
-File: emodules.info, Node: Introduction, Next: Annatomy of a Module, Prev: Top, Up: Top
+File: emodules.info, Node: Introduction, Next: Anatomy of a Module, Prev: Top, Up: Top
Introduction
************
Firstly, Elisp is an interpreted language, and this has serious speed
implications. Like all other interpreted languages (like Java), Elisp
is often suitable only for certain types of application or extension.
-So although Elisp is a general purpose language, and very ligh level,
+So although Elisp is a general purpose language, and very high level,
there are times when it is desirable to descend to a lower level
compiled language for speed purposes.
low level access to a system or need to be as quick as possible.
This manual describes a new way of extending XEmacs, by using dynamic
-loadable modules (also knows as dynamicaly loadable libraries (DLLs),
-dynamic shared objects (DSOs) or just simply shared objectcs), which can
+loadable modules (also known as dynamically loadable libraries (DLLs),
+dynamic shared objects (DSOs) or just simply shared objects), which can
be written in C or C++ and loaded into XEmacs at any time. I sometimes
refer to this technology as "CEmacs", which is short for "C Extensible
Emacs".
XEmacs.
* CEmacs also makes all of the relevant XEmacs internal header
- files availible for module authors to use. This is often required
+ files available for module authors to use. This is often required
to get data structure definitions and external variable
declarations. The header files installed include the module
specific header file `emodules.h'. Due to the nature of dynamic
done.
\1f
-File: emodules.info, Node: Annatomy of a Module, Next: Using ellcc, Prev: Introduction, Up: Top
+File: emodules.info, Node: Anatomy of a Module, Next: Using ellcc, Prev: Introduction, Up: Top
-Annatomy of a Module
-********************
+Anatomy of a Module
+*******************
- Each dynamically loadable XEmacs extension (hereafter refered to as a
-module) has a certain compulsory format, and must contain several
+ Each dynamically loadable XEmacs extension (hereafter referred to as
+a module) has a certain compulsory format, and must contain several
pieces of information and several mandatory functions. This chapter
describes the basic layout of a module, and provides a very simple
sample. The source for this sample can be found in the file
* Required Header File:: Always include <emodules.h>
* Required Functions:: Functions you must always provide
* Required Variables:: Variables whose values you must provide
-* Loading other Modules:: How to load dependant modules
+* Loading other Modules:: How to load dependent modules
\1f
-File: emodules.info, Node: Required Header File, Next: Required Functions, Prev: Annatomy of a Module, Up: Annatomy of a Module
+File: emodules.info, Node: Required Header File, Next: Required Functions, Prev: Anatomy of a Module, Up: Anatomy of a Module
Required Header File
====================
variable declarations.
`sysdep.h'
- All system dependant declarations and abstraction macros live
+ All system dependent declarations and abstraction macros live
here. You should never call low level system functions directly.
Rather, you should use the abstraction macros provided in this
header file.
manipulating XEmacs frames.
\1f
-File: emodules.info, Node: Required Functions, Next: Required Variables, Prev: Required Header File, Up: Annatomy of a Module
+File: emodules.info, Node: Required Functions, Next: Required Variables, Prev: Required Header File, Up: Anatomy of a Module
Required Functions
==================
Every module requires several initialization functions. It is the
-responsibility of these functions to load in any dependant modules, and
-to declare all variables and functions which are to be made visibile to
+responsibility of these functions to load in any dependent modules, and
+to declare all variables and functions which are to be made visible to
the XEmacs Lisp reader. Each of these functions performs a very
specific task, and they are executed in the correct order by XEmacs.
All of these functions are `void' functions which take no arguments.
`DEFVAR_LISP()', `DEFVAR_BOOL()' etc, and its purpose is to
declare and initialize all and any variables that your module
defines. They syntax for declaring variables is identical to the
- syntax used for all internal XEmacs source code.
+ syntax used for all internal XEmacs source code. If the module is
+ intended to be usable statically linked into XEmacs, the actions
+ of this function are severely restricted. *Note General Coding
+ Rules: (internals)General Coding Rules. Also see the comments in
+ `src/emacs.c' (`main_1'). Modules which perform initializations
+ not permitted by these rules will probably work, but dual-use
+ (dynamic loading and static linking) modules will require very
+ careful, and possibly fragile, coding.
`modules_of_module'
This optional function should be used to load in any modules which
functions and variables declared in your module.
\1f
-File: emodules.info, Node: Required Variables, Next: Loading other Modules, Prev: Required Functions, Up: Annatomy of a Module
+File: emodules.info, Node: Required Variables, Next: Loading other Modules, Prev: Required Functions, Up: Anatomy of a Module
Required Variables
==================
This is a short (typically 10 characters or less) name for the
module, and it is used as a suffix for all of the required
functions. This is also the name by which the module is
- recognised when loading dependant modules. The name does not
+ recognized when loading dependent modules. The name does not
necessarily have to be the same as the physical file name,
although keeping the two names in sync is a pretty good idea. The
name must not be empty, and it must be a valid part of a C
module. The value is set by the `--mod-title' argument to `ellcc'.
\1f
-File: emodules.info, Node: Loading other Modules, Prev: Required Variables, Up: Annatomy of a Module
+File: emodules.info, Node: Loading other Modules, Prev: Required Variables, Up: Anatomy of a Module
Loading other Modules
=====================
function `modules_of_module' to load in any modules which the current
module depends on. If the module is stand-alone, and does not depend
on other modules, then this function can be left empty or even
-undeclared. However, if it does have dependnacies, it must call
+undeclared. However, if it does have dependencies, it must call
`emodules_load':
- int emodules_load (CONST char *module,
- CONST char *modname,
- CONST char *modver)
+ int emodules_load (const char *module,
+ const char *modname,
+ const char *modver)
The first argument MODULE is the name of the actual shared object or
DLL. You can omit the `.so', `.ell' or `.dll' extension of you wish.
successful calls to `emodules_load' at the top level.
\1f
-File: emodules.info, Node: Using ellcc, Next: Defining Functions, Prev: Annatomy of a Module, Up: Top
+File: emodules.info, Node: Using ellcc, Next: Defining Functions, Prev: Anatomy of a Module, Up: Top
Using `ellcc'
*************
The result of running `ellcc' in initialization mode is a C source
file which you compile with (you guessed it) `ellcc' in compile mode.
Initialization mode is where you set the module name, version, title
-and gather together all of the documentaion strings for the functions
-and vairables in your module. There are several options that you are
+and gather together all of the documentation strings for the functions
+and variables in your module. There are several options that you are
required to pass `ellcc' in initialization mode, the first of which is
the mode switch itself, `--mode=init'.
directory. Each sub-directory within it is searched for a given module
when the user attempts to load it. The valid extensions that the
loader attempts to use are `.so', `.ell' and `.dll'. You can use any
-of these extensions, although `.ell' is the prefered extension.
+of these extensions, although `.ell' is the preferred extension.
\1f
File: emodules.info, Node: Link Mode, Next: Other ellcc options, Prev: Initialization Mode, Up: Using ellcc
=========
Once all of your source code files have been compiled (including the
-generated init file) you need to link them all together to created the
+generated init file) you need to link them all together to create the
loadable module. To do this, you invoke `ellcc' in link mode, by
-pasing the `--mode-link' command. You need to specify the final output
-file using the `--mod-output=NAME' command, but other than that all
+passing the `--mode=link' option. You need to specify the final output
+file using the `--mod-output=NAME' option, but other than that all
other arguments are passed on directly to the system compiler or
linker, along with any other required arguments to create the loadable
module.
is displayed.
`--mod-name=NAME'
- Sets the short internaml module NAME to the string specified,
- which must consist only of valid C identifiers. Required during
+ Sets the short internal module NAME to the string specified, which
+ must consist only of valid C identifiers. Required during
initialization mode.
`--mod-version=VERSION'
exit.
`--mod-archdir'
- Prints the name of the root of the architecture-dependant
- directory that XEmacs searches for architecture-dependant files.
+ Prints the name of the root of the architecture-dependent
+ directory that XEmacs searches for architecture-dependent files.
`--mod-config'
Prints the name of the configuration for which XEmacs and `ellcc'
certain rare circumstances you may wish to over-ride the flags passed to
the compiler or linker, and you can do so using environment variables.
The table below lists all of the environment variables that `ellcc'
-recognises.
+recognizes.
`ELLCC'
This is used to over-ride the name of the C compiler that is
DEFUN ("my-function", Fmy_function, 1, 1, "FFile name: ", /*
Sample Emacs primitive function.
- The specified FILE is frobricated before it is fnozzled.
+ The specified FILE is frobnicated before it is fnozzled.
*/
(file))
{
===================
Simply writing the code for a function is not enough to make it
-availible to the Lisp reader. You have to, during module
+available to the Lisp reader. You have to, during module
initialization, let the Lisp reader know about the new function. This
is done by calling `DEFSUBR' with the name of the function. This is
the sole purpose of the initialization function `syms_of_module'.
Rarely will you write a module that only contains functions. It is
common to also provide variables which can be used to control the
-behaviour of the function, or store the results of the function being
+behavior of the function, or store the results of the function being
executed. The actual C variable types are the same for modules and
internal XEmacs primitives, and the declaration of the variables is
identical.
One _very_ important difference between XEmacs variables and module
variables is how you use pure space. Simply put, you *never* use pure
space in XEmacs modules. The pure space storage is of a limited size,
-and is initialized propperly during the dumping of XEmacs. Because
+and is initialized properly during the dumping of XEmacs. Because
variables are being added dynamically to an already running XEmacs when
you load a module, you cannot use pure space. Be warned: *do not use
pure space in modules. Repeat, do not use pure space in modules.*
* Menu:
-* annatomy: Annatomy of a Module.
+* anatomy: Anatomy of a Module.
* compiler: Introduction.
* compiling: Compile Mode.
* config.h: Required Header File.
* DEFVAR_BOOL: Defining Variables.
* DEFVAR_INT: Defining Variables.
* DEFVAR_LISP: Defining Variables.
-* dependancies: Loading other Modules.
+* dependencies: Loading other Modules.
* DLL: Introduction.
* docs_of_module: Required Functions.
* documentation <1>: Initialization Mode.
* documentation: Introduction.
* DSO: Introduction.
-* ellcc <1>: Introduction.
-* ellcc: Using ellcc.
* ELLCC: Environment Variables.
+* ellcc <1>: Using ellcc.
+* ellcc: Introduction.
* ELLCFLAGS: Environment Variables.
* ELLDLLFLAGS: Environment Variables.
* ELLLD: Environment Variables.
* emodules.h: Required Header File.
* emodules_load: Loading other Modules.
* environment variables: Environment Variables.
-* format, module: Annatomy of a Module.
+* format, module: Anatomy of a Module.
* functions, declaring: Declaring Functions.
* functions, defining: Using DEFUN.
* functions, Lisp: Using DEFUN.
* header files: Introduction.
* help: Introduction.
* include files: Required Header File.
-* initialization <1>: Required Variables.
-* initialization <2>: Initialization Mode.
+* initialization <1>: Initialization Mode.
+* initialization <2>: Required Variables.
* initialization: Required Functions.
* linker: Introduction.
* linking: Link Mode.
* module compiler: Using ellcc.
-* module format: Annatomy of a Module.
-* module skeleton: Annatomy of a Module.
-* modules_of_module <1>: Required Functions.
-* modules_of_module: Loading other Modules.
+* module format: Anatomy of a Module.
+* module skeleton: Anatomy of a Module.
+* modules_of_module <1>: Loading other Modules.
+* modules_of_module: Required Functions.
* objects, defining: Defining Variables.
* objects, Lisp: Defining Variables.
* paths: Other ellcc options.
* required variables: Required Variables.
* samples: Introduction.
* shared object: Introduction.
-* skeleton, module: Annatomy of a Module.
+* skeleton, module: Anatomy of a Module.
* subrs: Using DEFUN.
* syms_of_module: Required Functions.
* variables, defining: Defining Variables.
\1f
Tag Table:
Node: Top\7f1536
-Node: Introduction\7f2884
-Node: Annatomy of a Module\7f7393
-Node: Required Header File\7f8209
-Node: Required Functions\7f10130
-Node: Required Variables\7f12379
-Node: Loading other Modules\7f15066
-Node: Using ellcc\7f17124
-Node: Compile Mode\7f18919
-Node: Initialization Mode\7f20287
-Node: Link Mode\7f25319
-Node: Other ellcc options\7f26466
-Node: Environment Variables\7f29046
-Node: Defining Functions\7f30737
-Node: Using DEFUN\7f32748
-Node: Declaring Functions\7f34459
-Node: Defining Variables\7f35802
-Node: Index\7f38047
+Node: Introduction\7f2883
+Node: Anatomy of a Module\7f7391
+Node: Required Header File\7f8205
+Node: Required Functions\7f10124
+Node: Required Variables\7f12848
+Node: Loading other Modules\7f15534
+Node: Using ellcc\7f17591
+Node: Compile Mode\7f19385
+Node: Initialization Mode\7f20753
+Node: Link Mode\7f25787
+Node: Other ellcc options\7f26932
+Node: Environment Variables\7f29511
+Node: Defining Functions\7f31202
+Node: Using DEFUN\7f33213
+Node: Declaring Functions\7f34924
+Node: Defining Variables\7f36267
+Node: Index\7f38510
\1f
End Tag Table
projects / chise / xemacs-chise.git.1 / blobdiff