X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Femodules.info;h=15eb210d27cf1930ec2f8c87cbe78055f6f04053;hb=b5f26301ee1ad7dbc9ad1c22e5b8564b5161d9ad;hp=9b95d110e5f6386650e158e66958341b51c6c44f;hpb=b73e352f264e9da0a00159dc29f318305cbe8636;p=chise%2Fxemacs-chise.git diff --git a/info/emodules.info b/info/emodules.info index 9b95d11..15eb210 100644 --- a/info/emodules.info +++ b/info/emodules.info @@ -1,4 +1,4 @@ -This is ../info/emodules.info, produced by makeinfo version 4.0 from +This is ../info/emodules.info, produced by makeinfo version 4.0b from emodules.texi. This file documents the module loading technology of XEmacs. @@ -41,7 +41,7 @@ support documentation. * 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 @@ -49,12 +49,12 @@ support documentation. --- The Detailed Node Listing --- -Annatomy of a Module +Anatomy of a Module * Required Header File:: Always include * 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' @@ -70,7 +70,7 @@ Defining Functions * Declaring Functions:: Declaring functions to the Lisp reader  -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 ************ @@ -84,7 +84,7 @@ ways than you can imagine, it does have its short-comings. 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. @@ -95,8 +95,8 @@ suited to a wider range of applications, especially those that require 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". @@ -121,7 +121,7 @@ perspective though, a lot more is provided. 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 @@ -154,13 +154,13 @@ deal to look at the actual XEmacs source code to see how things are done.  -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 @@ -171,10 +171,10 @@ sample. The source for this sample can be found in the file * Required Header File:: Always include * 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  -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 ==================== @@ -200,7 +200,7 @@ files included are: 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. @@ -223,14 +223,14 @@ files included are: manipulating XEmacs frames.  -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. @@ -252,7 +252,14 @@ place-holder, not an actual function name. `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 @@ -268,7 +275,7 @@ place-holder, not an actual function name. functions and variables declared in your module.  -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 ================== @@ -296,7 +303,7 @@ discussed here simply for the sake of completeness. 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 @@ -322,7 +329,7 @@ discussed here simply for the sake of completeness. module. The value is set by the `--mod-title' argument to `ellcc'.  -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 ===================== @@ -331,12 +338,12 @@ 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. @@ -365,7 +372,7 @@ their parents will also fail to load. This does not include previous successful calls to `emodules_load' at the top level.  -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' ************* @@ -462,8 +469,8 @@ trickery in the module loading code. This is all done using the 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'. @@ -542,7 +549,7 @@ option. This directory is treated the same way as the main module 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.  File: emodules.info, Node: Link Mode, Next: Other ellcc options, Prev: Initialization Mode, Up: Using ellcc @@ -551,10 +558,10 @@ Link Mode ========= 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. @@ -599,8 +606,8 @@ variables. Here is the complete list of options that `ellcc' accepts. 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' @@ -629,8 +636,8 @@ variables. Here is the complete list of options that `ellcc' accepts. 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' @@ -647,7 +654,7 @@ flags that were determined at the time XEmacs was configured. In 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 @@ -737,7 +744,7 @@ module. This is done using the `DEFUN' macro. Here is a small example: 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)) { @@ -773,7 +780,7 @@ Declaring Functions =================== 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'. @@ -805,7 +812,7 @@ Defining Variables 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. @@ -823,7 +830,7 @@ internals manual. 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.* @@ -862,7 +869,7 @@ Index * Menu: -* annatomy: Annatomy of a Module. +* anatomy: Anatomy of a Module. * compiler: Introduction. * compiling: Compile Mode. * config.h: Required Header File. @@ -874,7 +881,7 @@ Index * 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. @@ -893,7 +900,7 @@ Index * 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. @@ -907,8 +914,8 @@ Index * linker: Introduction. * linking: Link Mode. * module compiler: Using ellcc. -* module format: Annatomy of a Module. -* module skeleton: Annatomy of a Module. +* 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. @@ -919,7 +926,7 @@ Index * 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. @@ -930,23 +937,23 @@ Index  Tag Table: -Node: Top1536 +Node: Top1537 Node: Introduction2884 -Node: Annatomy of a Module7393 -Node: Required Header File8209 -Node: Required Functions10130 -Node: Required Variables12379 -Node: Loading other Modules15066 -Node: Using ellcc17124 -Node: Compile Mode18919 -Node: Initialization Mode20287 -Node: Link Mode25319 -Node: Other ellcc options26466 -Node: Environment Variables29046 -Node: Defining Functions30737 -Node: Using DEFUN32748 -Node: Declaring Functions34459 -Node: Defining Variables35802 -Node: Index38047 +Node: Anatomy of a Module7392 +Node: Required Header File8206 +Node: Required Functions10125 +Node: Required Variables12849 +Node: Loading other Modules15535 +Node: Using ellcc17592 +Node: Compile Mode19386 +Node: Initialization Mode20754 +Node: Link Mode25788 +Node: Other ellcc options26933 +Node: Environment Variables29512 +Node: Defining Functions31203 +Node: Using DEFUN33214 +Node: Declaring Functions34925 +Node: Defining Variables36268 +Node: Index38511  End Tag Table