+++ /dev/null
-This is Info file ../info/emodules.info, produced by Makeinfo version
-1.68 from the input file emodules.texi.
-
- This file documents the module loading technology of XEmacs.
-
- Copyright (C) 1998 J. Kean Johnston.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: emodules.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
-
- This Info file contains v1.0 of the XEmacs dynamic loadable module
-support documentation.
-
-* Menu:
-
-* Introduction:: Introducing Emacs Modules
-* Annatomy 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
-* Index:: Concept Index
-
- -- The Detailed Node Listing --
-
-Annatomy 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
-
-Using `ellcc'
-
-* Compile Mode:: Compiling modules using ellcc
-* Initialization Mode:: Generating documentation and variables
-* Link Mode:: Creating the final loadable module
-* Other ellcc options:: Other useful options
-* Environment Variables:: How to control ellcc
-
-Defining Functions
-
-* Using DEFUN:: Using the DEFUN macro to define functions
-* Declaring Functions:: Declaring functions to the Lisp reader
-
-\1f
-File: emodules.info, Node: Introduction, Next: Annatomy of a Module, Prev: Top, Up: Top
-
-Introduction
-************
-
- XEmacs is a powerful, extensible editor. The traditional way of
-extending the functionality of XEmacs is to use its built-in Lisp
-language (called Emacs Lisp, or Elisp for short). However, while Elisp
-is a full programming language and capable of extending XEmacs in more
-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,
-there are times when it is desirable to descend to a lower level
-compiled language for speed purposes.
-
- Secondly, Elisp (or Lisp in general) is not a very common language
-any more, except for certain circles in the computer industry. C is a
-far more commonly known language, and because it is compiled, more
-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
-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 modules are configured into and installed with XEmacs by
-default on all systems that support loading of shared objects. From a
-users perspective, the internals of XEmacs modules are irrelevant. All
-a user will ever need to know about shared objects is the name of the
-shared object when they want to load a given module. From a developers
-perspective though, a lot more is provided.
-
- * Of primary interest is the `ellcc' program. This program is
- created during compile time, and is intended to abstract compiler
- specific characteristics from the developer. This program is
- called to compile and link all objects that will make up the final
- shared object, and accepts all common C compiler flags. `ellcc'
- also sets up the correct environment for compiling modules by
- enabling any special compiler modes (such as PIC mode), setting
- the correct include paths for the location of XEmacs internal
- header files etc. The program will also invoke the linker
- correctly to created the final shared object which is loaded into
- XEmacs.
-
- * CEmacs also makes all of the relevant XEmacs internal header
- files availible 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
- modules, most of the internals of XEmacs are exposed. *Note Top:
- (internals)Top, for a more complete discussion on how to extend
- and understand XEmacs. All of the rules for C modules are
- discussed there.
-
- * Part of the XEmacs distribution is a set of sample modules.
- These are not installed when XEmacs is, but remain in the XEmacs
- source tree. These modules live in the directory `modules', which
- is a sub-directory of the main XEmacs source code directory.
- Please look at the samples carefully, and maybe even use them as a
- basis for making your own modules. Most of the concepts required
- for writing extension modules are covered in the samples.
-
- * Last, but not least is this manual. This can be viewed from
- within XEmacs, and it can be printed out as well. It is the
- intention of this document that it will describe everything you
- need to know about extending XEmacs in C. If you do not find this
- to be the case, please contact the author(s).
-
- The rest of this document will discuss the actual mechanics of
-XEmacs modules and work through several of the samples. Please be sure
-that you have read the XEmacs Internals Manual and understand
-everything in it. The concepts there apply to all modules. This
-document may have some overlap, but it is the internals manual which
-should be considered the final authority. It will also help a great
-deal to look at the actual XEmacs source code to see how things are
-done.
-
-\1f
-File: emodules.info, Node: Annatomy of a Module, Next: Using ellcc, Prev: Introduction, Up: Top
-
-Annatomy of a Module
-********************
-
- Each dynamically loadable XEmacs extension (hereafter refered 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
-`modules/simple/sample.c' in the main XEmacs source code tree.
-
-* Menu:
-
-* 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
-
-\1f
-File: emodules.info, Node: Required Header File, Next: Required Functions, Prev: Annatomy of a Module, Up: Annatomy of a Module
-
-Required Header File
-====================
-
- Every module must include the file `<emodules.h>'. This will
-include several other XEmacs internal header files, and will set up
-certain vital macros. One of the most important files included by
-`emodules.h' is the generated `config.h' file, which contains all of
-the required system abstraction macros and definitions. Most modules
-will probably require some pre-processor conditionals based on
-constants defined in `config.h'. Please read that file to familiarize
-yourself with the macros defined there.
-
- Depending on exactly what your module will be doing, you will
-probably need to include one or more of the XEmacs internal header
-files. When you `#include <emodules.h>', you will get a few of the
-most important XEmacs header files included automatically for you. The
-files included are:
-
-`lisp.h'
- This file contains most of the macros required for declaring Lisp
- object types, macros for accessing Lisp objects, and global
- variable declarations.
-
-`sysdep.h'
- All system dependant 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.
-
-`window.h'
- This header file defines the window structures and Lisp types, and
- provides functions and macros for manipulating multiple XEmacs
- windows.
-
-`buffer.h'
- All macros and function declarations for manipulating internal and
- user visible buffers appear in this file.
-
-`insdel.h'
- This header provides the information required for performing text
- insertion and deletion.
-
-`frame.h'
- Provides the required structure, macro and function definitions for
- manipulating XEmacs frames.
-
-\1f
-File: emodules.info, Node: Required Functions, Next: Required Variables, Prev: Required Header File, Up: Annatomy 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
-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.
-Here, briefly, are the required module functions. Note that the actual
-function names do not end with the string `_module', but rather they
-end with the abbreviated module name by which the module is known.
-More on the module name and its importance later. Just bear in mind
-that the text `_module' in the functions below is simply a
-place-holder, not an actual function name.
-
-`syms_of_module'
- This required function is responsible for introducing to the Lisp
- reader all functions that you have defined in your module using
- `DEFUN()'. Note that *only* functions are declared here, using
- the `DEFSUBR()' macro. No variables are declared.
-
-`vars_of_module'
- This required function contains calls to macros such as
- `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.
-
-`modules_of_module'
- This optional function should be used to load in any modules which
- your module depends on. The XEmacs module loading code makes sure
- that the same module is not loaded twice, so several modules can
- safely call the module load function for the same module. Only
- one copy of each module (at a given version) will ever be loaded.
-
-`docs_of_module'
- This is a required function, but not one which you need ever write.
- This function is created automatically by `ellcc' when the module
- initialization code is produced. It is required to document all
- 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
-
-Required Variables
-==================
-
- Not only does a module need to declare the initialization functions
-mentioned above, it is also required to provide certain variables which
-the module loading code searches for in order to determine the viability
-of a module. You are *not* required to provide these variables in your
-source files. They are automatically set up in the module
-initialization file by the `ellcc' compiler. These variables are
-discussed here simply for the sake of completeness.
-
-`emodules_compiler'
- This is a variable of type `long', and is used to indicate the
- version of the XEmacs loading technology that was used to produce
- the module being loaded. This version number is completely
- unrelated to the XEmacs version number, as a given module may
- quite well work regardless of the version of XEmacs that was
- installed at the time the module was created.
-
- The XEmacs modules version is used to differentiate between major
- changes in the module loading technology, not versions of XEmacs.
-
-`emodules_name'
- 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
- 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
- function name. The value of this variable is appended to the
- function names `syms_of_', `vars_of_', `modules_of_' and
- `docs_of_' to form the actual function names that the module
- loading code looks for when loading a module.
-
- This variable is set by the `--mod-name' argument to `ellcc'.
-
-`emodules_version'
- This string variable is used to load specific versions of a module.
- Rarely will two or more versions of a module be left lying around,
- but just in case this does happen, this variable can be used to
- control exactly which module should be loaded. See the Lisp
- function `load-module' for more details. This variable is set by
- the `--mod-version' argument to `ellcc'.
-
-`emodules_title'
- This is a string which describes the module, and can contain
- spaces or other special characters. It is used solely for
- descriptive purposes, and does not affect the loading of the
- 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
-
-Loading other Modules
-=====================
-
- During the loading of a module, it is the responsibility of the
-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
-`emodules_load':
-
- 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.
-If you do not specify an absolute path name, then the same rules as
-apply to loading Lisp modules are applied when searching for the
-module. If the module cannot be found in any of the standard places,
-and an absolute path name was not specified, `emodules_load' will
-signal an error and loading of the module will stop.
-
- The second argument (MODNAME) is the module name to load, and must
-match the contents of the variable EMODULE_NAME in the module to be
-loaded. A mis-match will cause the module load to fail. If this
-parameter is `NULL' or empty, then no checks are performed against the
-target module's EMODULE_NAME variable.
-
- The last argument, MODVER, is the desired version of the module to
-load, and is compared to the target module's EMODULE_VERSION value. If
-this parameter is not `NULL' or empty, and the match fails, then the
-load of the module will fail.
-
- `emodules_load' can be called recursively. If, at any point during
-the loading of modules a failure is encountered, then all modules that
-were loaded since the top level call to `emodules_load' will be
-unloaded. This means that if any child modules fail to load, then
-their parents will also fail to load. This does not include previous
-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
-
-Using `ellcc'
-*************
-
- Before discussing the anatomy of a module in greater detail, you
-should be aware of the steps required in order to correctly compile and
-link a module for use within XEmacs. There is little difference between
-compiling normal C code and compiling a module. In fact, all that
-changes is the command used to compile the module, and a few extra
-arguments to the compiler.
-
- XEmacs now ships with a new user utility, called `ellcc'. This is
-the "Emacs Loadable Library C Compiler". This is a wrapper program
-that will invoke the real C compiler with the correct arguments to
-compile and link your module. With the exception of a few command line
-options, this program can be considered a replacement for your C
-compiler. It accepts all of the same flags and arguments that your C
-compiler does, so in many cases you can simply set the `make' variable
-`CC' to `ellcc' and your code will be compiled as an Emacs module
-rather than a static C object.
-
- `ellcc' has three distinct modes of operation. It can be run in
-compile, link or initialization mode. These modes are discussed in more
-detail below. If you want `ellcc' to show the commands it is
-executing, you can specify the option `--mode=verbose' to `ellcc'.
-Specifying this option twice will enable certain extra debugging
-messages to be displayed on the standard output.
-
-* Menu:
-
-* Compile Mode:: Compiling modules using ellcc
-* Initialization Mode:: Generating documentation and variables
-* Link Mode:: Creating the final loadable module
-* Other ellcc options:: Other useful options
-* Environment Variables:: How to control ellcc
-
-\1f
-File: emodules.info, Node: Compile Mode, Next: Initialization Mode, Prev: Using ellcc, Up: Using ellcc
-
-Compile Mode
-============
-
- By default, `ellcc' is in "compile" mode. This means that it
-assumes that all of the command line arguments are C compiler arguments,
-and that you want to compile the specified source file or files. You
-can force compile mode by specifying the `--mode=compile' argument to
-`ellcc'.
-
- In this mode, `ellcc' is simply a front-end to the same C compiler
-that was used to create the XEmacs binary itself. All `ellcc' does in
-this mode is insert a few extra command line arguments before the
-arguments you specify to `ellcc' itself. `ellcc' will then invoke the
-C compiler to compile your module, and will return the same exit codes
-and messages that your C compiler does.
-
- By far the easiest way to compile modules is to construct a
-`Makefile' as you would for a normal program, and simply insert, at
-some appropriate place something similar to:
-
- CC=ellcc --mode=compile
-
- .c.o:
- $(CC) $(CFLAGS) -c $<
-
- After this, all you need to do is provide simple `make' rules for
-compiling your module source files. Since modules are most useful when
-they are small and self-contained, most modules will have a single
-source file, aside from the module specific initialization file (see
-below for details).
-
-\1f
-File: emodules.info, Node: Initialization Mode, Next: Link Mode, Prev: Compile Mode, Up: Using ellcc
-
-Initialization Mode
-===================
-
- XEmacs uses a rather bizarre way of documenting variables and
-functions. Rather than have the documentation for compiled functions
-and variables passed as static strings in the source code, the
-documentation is included as a C comment. A special program, called
-`make-docfile', is used to scan the source code files and extract the
-documentation from these comments, producing the XEmacs `DOC' file,
-which the internal help engine scans when the documentation for a
-function or variable is requested.
-
- Due to the internal construction of Lisp objects, subrs and other
-such things, adding documentation for a compiled function or variable
-in a compiled module, at any time after XEmacs has been "dumped" is
-somewhat problematic. Fortunately, as a module writer you are insulated
-from the difficulties thanks to your friend `ellcc' and some internal
-trickery in the module loading code. This is all done using the
-"initialization" mode of `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
-required to pass `ellcc' in initialization mode, the first of which is
-the mode switch itself, `--mode=init'.
-
- Next, you need to specify the name of the C source code file that
-`ellcc' will produce, and you specify this using the
-`--mod-output=FILENAME' argument. FILENAME is the name of the C source
-code file that will contain the module variables and `docs_of_module'
-function.
-
- As discussed previously, each module requires a short "handle" or
-module name. This is specified with the `--mod-name=NAME' option,
-where NAME is the abbreviated module name. This NAME must consist only
-of characters that are valid in C function and variable names.
-
- The module version is specified using `--mod-version=VERSION'
-argument, with VERSION being any arbitrary version string. This
-version can be passed as an optional second argument to the Lisp
-function `load-module', and as the third argument to the internal
-module loading command `emodules_load'. This version string is used to
-distinguish between different versions of the same module, and to
-ensure that the module is loaded at a specific version.
-
- Last, but not least, is the module title. Specified using the
-`--mod-title=TITLE' option, the specified TITLE is used when the list
-of loaded modules is displayed. The module title serves no purpose
-other than to inform the user of the function of the module. This
-string should be brief, as it has to be formatted to fit the screen.
-
- Following all of these parameters, you need to provide the list of
-all source code modules that make up your module. These are the files
-which are scanned by `make-docfile', and provide the information
-required to populate the `docs_of_module' function. Below is a sample
-`Makefile' fragment which indicates how all of this is used.
-
- CC=ellcc --mode=compile
- LD=ellcc --mode=link
- MODINIT=ellcc --mode=init
- CFLAGS=-O2 -DSOME_STUFF
-
- .c.o:
- $(CC) $(CFLAGS) -c $<
-
- MODNAME=sample
- MODVER=1.0.0
- MODTITLE="Small sample module"
-
- SRCS=modfile1.c modfile2.c modfile3.c
- OBJS=$(SRCS:.c=.o)
-
- all: sample.ell
- clean:
- rm -f $(OBJS) sample_init.o sample.ell
-
- install: all
- mkdir `ellcc --mod-location`/mymods > /dev/null
- cp sample.ell `ellcc --mod-location`/mymods/sample.ell
-
- sample.ell: $(OBJS) sample_init.o
- $(LD) --mod-output=$ $(OBJS) sample_init.o
-
- sample_init.o: sample_init.c
- sample_init.c: $(SRCS)
- $(MODINIT) --mod-name=$(MODNAME) --mod-version=$(MODVER) \
- --mod-title=$(MODTITLE) --mod-output=$ $(SRCS)
-
- The above `Makefile' is, in fact, complete, and would compile the
-sample module, and optionally install it. The `--mod-location'
-argument to `ellcc' will produce, on the standard output, the base
-location of the XEmacs module directory. Each sub-directory of that
-directory is automatically searched for for modules when they are loaded
-with `load-module'. An alternative location would be
-`/usr/local/lib/xemacs/site-modules'. That path can change depending
-on the options the person who compiled XEmacs chose, so you can always
-determine the correct site location using the `--mod-site-location'
-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.
-
-\1f
-File: emodules.info, Node: Link Mode, Next: Other ellcc options, Prev: Initialization Mode, Up: Using ellcc
-
-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
-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
-other arguments are passed on directly to the system compiler or
-linker, along with any other required arguments to create the loadable
-module.
-
- The module has complete access to all symbols that were present in
-the dumped XEmacs, so you do not need to link against libraries that
-were linked in with the main executable. If your library uses some
-other extra libraries, you will need to link with those. There is
-nothing particularly complicated about link mode. All you need to do
-is make sure you invoke it correctly in the `Makefile'. See the sample
-`Makefile' above for an example of a well constructed `Makefile' that
-invoked the linker correctly.
-
-\1f
-File: emodules.info, Node: Other ellcc options, Next: Environment Variables, Prev: Link Mode, Up: Using ellcc
-
-Other `ellcc' options
-=====================
-
- Aside from the three main `ellcc' modes described above, `ellcc' can
-accept several other options. These are typically used in a `Makefile'
-to determine installation paths. `ellcc' also allows you to over-ride
-several of its built-in compiler and linker options using environment
-variables. Here is the complete list of options that `ellcc' accepts.
-
-`--mode=compile'
- Enables compilation mode. Use this to compile source modules.
-
-`--mode=link'
- Enabled link edit mode. Use this to create the final module.
-
-`--mode=init'
- Used to create the documentation function and to initialize other
- required variables. Produces a C source file that must be
- compiled with `ellcc' in compile mode before linking the final
- module.
-
-`--mode=verbose'
- Enables verbose mode. This will show you the commands that are
- being executed, as well as the version number of `ellcc'. If you
- specify this option twice, then some extra debugging information
- 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
- initialization mode.
-
-`--mod-version=VERSION'
- Sets the internal module VERSION to the specified string.
- Required during initialization mode.
-
-`--mod-title=TITLE'
- Sets the module descriptive TITLE to the string specified. This
- string can contain any printable characters, but should not be too
- long. It is required during initialization mode.
-
-`--mod-output=FILENAME'
- Used to control the output file name. This is used during
- initialization mode to set the name of the C source file that will
- be created to FILENAME. During link mode, it sets the name of the
- final loadable module to FILENAME.
-
-`--mod-location'
- This will print the name of the standard module installation path
- on the standard output and immediately exit `ellcc'. Use this
- option to determine the directory prefix of where you should
- install your modules.
-
-`--mod-site-location'
- This will print the name of the site specific module location and
- exit.
-
-`--mod-archdir'
- Prints the name of the root of the architecture-dependant
- directory that XEmacs searches for architecture-dependant files.
-
-`--mod-config'
- Prints the name of the configuration for which XEmacs and `ellcc'
- were compiled.
-
-\1f
-File: emodules.info, Node: Environment Variables, Prev: Other ellcc options, Up: Using ellcc
-
-Environment Variables
-=====================
-
- During its normal operation, `ellcc' uses the compiler and linker
-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.
-
-`ELLCC'
- This is used to over-ride the name of the C compiler that is
- invoked by `ellcc'.
-
-`ELLLD'
- Sets the name of the link editor to use to created the final
- module.
-
-`ELLCFLAGS'
- Sets the compiler flags passed on when compiling source modules.
- This only sets the basic C compiler flags. There are certain
- hard-coded flags that will always be passed.
-
-`ELLLDFLAGS'
- Sets the flags passed on to the linker. This does *not* include
- the flags for enabling PIC mode. This just sets basic linker
- flags.
-
-`ELLDLLFLAGS'
- Sets the flags passed to the linker that are required to created
- shared and loadable objects.
-
-`ELLPICFLAGS'
- Sets the C compiler option required to produce an object file that
- is suitable for including in a shared library. This option should
- turn on PIC mode, or the moral equivalent thereof on the target
- system.
-
-`ELLMAKEDOC'
- Sets the name of the `make-docfile' program to use. Usually
- `ellcc' will use the version that was compiled and installed with
- XEmacs, but this option allows you to specify an alternative path.
- Used during the compile phase of XEmacs itself.
-
-\1f
-File: emodules.info, Node: Defining Functions, Next: Defining Variables, Prev: Using ellcc, Up: Top
-
-Defining Functions
-******************
-
- One of the main reasons you would ever write a module is to provide
-one or more "functions" for the user or the editor to use. The term
-"function" is a bit overloaded here, as it refers to both a C function
-and the way it appears to Lisp, which is a "subroutine", or simply a
-"subr". A Lisp subr is also known as a Lisp primitive, but that term
-applies less to dynamic modules. *Note Writing Lisp Primitives:
-(internals)Writing Lisp Primitives, for details on how to declare
-functions. You should familiarize yourself with the instructions
-there. The format of the function declaration is identical in modules.
-
- Normal Lisp primitives document the functions they defining by
-including the documentation as a C comment. During the build process,
-a program called `make-docfile' is run, which will extract all of these
-comments, build up a single large documentation file, and will store
-pointers to the start of each documentation entry in the dumped XEmacs.
-This, of course, will not work for dynamic modules, as they are loaded
-long after XEmacs has been dumped. For this reason, we require a
-special means for adding documentation for new subrs. This is what the
-macro `CDOCSUBR' is used for, and this is used extensively during
-`ellcc' initialization mode.
-
- When using `DEFUN' in normal XEmacs C code, the sixth "parameter" is
-a C comment which documents the function. For a dynamic module, we of
-course need to convert the C comment to a usable string, and we need to
-set the documentation pointer of the subr to this string. As a module
-programmer, you don't actually need to do any work for this to happen.
-It is all taken care of in the `docs_of_module' function created by
-`ellcc'.
-
-* Menu:
-
-* Using DEFUN:: Using the DEFUN macro to define functions
-* Declaring Functions:: Declaring functions to the Lisp reader
-
-\1f
-File: emodules.info, Node: Using DEFUN, Next: Declaring Functions, Prev: Defining Functions, Up: Defining Functions
-
-Using `DEFUN'
-=============
-
- Although the full syntax of a function declaration is discussed in
-the XEmacs internals manual in greater depth, what follows is a brief
-description of how to define and implement a new Lisp primitive in a
-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.
- */
- (file))
- {
- char *filename;
-
- if (NILP(file))
- return Qnil;
-
- filename = (char *)XSTRING_DATA(file);
- frob(filename);
- return Qt;
- }
-
- The first argument is the name of the function as it will appear to
-the Lisp reader. This must be provided as a string. The second
-argument is the name of the actual C function that will be created.
-This is typically the Lisp function name with a preceding capital `F',
-with hyphens converted to underscores. This must be a valid C function
-name. Next come the minimum and maximum number of arguments,
-respectively. This is used to ensure that the correct number of
-arguments are passed to the function. Next is the `interactive'
-definition. If this function is meant to be run by a user
-interactively, then you need to specify the argument types and prompts
-in this string. Please consult the XEmacs Lisp manual for more
-details. Next comes a C comment that is the documentation for this
-function. This comment *must* exist. Last comes the list of function
-argument names, if any.
-
-\1f
-File: emodules.info, Node: Declaring Functions, Prev: Using DEFUN, Up: Defining Functions
-
-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
-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'.
-*Note Required Functions::, for more details.
-
- Each call to `DEFSUBR' takes as its only argument the name of the
-function, which is the same as the second argument to the call to
-`DEFUN'. Using the example function above, you would insert the
-following code in the `syms_of_module' function:
-
- DEFSUBR(Fmy_function);
-
- This call will instruct XEmacs to make the function visible to the
-Lisp reader and will prepare for the insertion of the documentation into
-the right place. Once this is done, the user can call the Lisp
-function `my-function', if it was defined as an interactive function
-(which in this case it was).
-
- Thats all there is to defining and announcing new functions. The
-rules for what goes inside the functions, and how to write good
-modules, is beyond the scope of this document. Please consult the
-XEmacs internals manual for more details.
-
-\1f
-File: emodules.info, Node: Defining Variables, Next: Index, Prev: Defining Functions, Up: Top
-
-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
-executed. The actual C variable types are the same for modules and
-internal XEmacs primitives, and the declaration of the variables is
-identical.
-
- *Note Adding Global Lisp Variables: (internals)Adding Global Lisp
-Variables, for more information on variables and naming conventions.
-
- Once your variables are defined, you need to initialize them and make
-the Lisp reader aware of them. This is done in the `vars_of_module'
-initialization function using special XEmacs macros such as
-`DEFVAR_LISP', `DEFVAR_BOOL', `DEFVAR_INT' etc. The best way to see
-how to use these macros is to look at existing source code, or read the
-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
-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.*
-Once again, to remove all doubts: *DO NOT USE PURE SPACE IN MODULES!!!*
-
- Below is a small example which declares and initializes two
-variables. You will note that this code takes into account the fact
-that this module may very well be compiled into XEmacs itself. This is
-a prudent thing to do.
-
- Lisp_Object Vsample_string;
- int sample_boolean;
-
- void
- vars_of_module()
- {
- DEFVAR_LISP ("sample-string", &Vsample_string /*
- This is a sample string, declared in a module.
-
- Nothing magical about it.
- */);
-
- DEFVAR_BOOL("sample-boolean", &sample_boolean /*
- *Sample user-settable boolean.
- */);
-
- sample_boolean = 0;
- Vsample_string = build_string("My string");
- }
-
-\1f
-File: emodules.info, Node: Index, Prev: Defining Variables, Up: Top
-
-Index
-*****
-
-* Menu:
-
-* annatomy: Annatomy of a Module.
-* compiler: Introduction.
-* compiling: Compile Mode.
-* config.h: Required Header File.
-* defining functions: Defining Functions.
-* defining objects: Defining Variables.
-* defining variables: Defining Variables.
-* DEFSUBR: Declaring Functions.
-* DEFUN: Using DEFUN.
-* DEFVAR_BOOL: Defining Variables.
-* DEFVAR_INT: Defining Variables.
-* DEFVAR_LISP: Defining Variables.
-* dependancies: 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.
-* ELLCFLAGS: Environment Variables.
-* ELLDLLFLAGS: Environment Variables.
-* ELLLD: Environment Variables.
-* ELLLDFLAGS: Environment Variables.
-* ELLMAKEDOC: Environment Variables.
-* ELLPICFLAGS: Environment Variables.
-* Emacs Modules: Introduction.
-* emodules.h: Required Header File.
-* emodules_load: Loading other Modules.
-* environment variables: Environment Variables.
-* format, module: Annatomy of a Module.
-* functions, declaring: Declaring Functions.
-* functions, defining: Using DEFUN.
-* functions, Lisp: Using DEFUN.
-* functions, required: Required Functions.
-* header files: Introduction.
-* help: Introduction.
-* include files: Required Header File.
-* initialization <1>: Required Variables.
-* initialization <2>: Initialization Mode.
-* 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.
-* objects, defining: Defining Variables.
-* objects, Lisp: Defining Variables.
-* paths: Other ellcc options.
-* required functions: Required Functions.
-* required header: Required Header File.
-* required variables: Required Variables.
-* samples: Introduction.
-* shared object: Introduction.
-* skeleton, module: Annatomy of a Module.
-* subrs: Using DEFUN.
-* syms_of_module: Required Functions.
-* variables, defining: Defining Variables.
-* variables, Lisp: Defining Variables.
-* variables, required: Required Variables.
-* vars_of_module: Required Functions.
-
-
-\1f
-Tag Table:
-Node: Top\7f1562
-Node: Introduction\7f2908
-Node: Annatomy of a Module\7f7417
-Node: Required Header File\7f8233
-Node: Required Functions\7f10154
-Node: Required Variables\7f12403
-Node: Loading other Modules\7f15090
-Node: Using ellcc\7f17148
-Node: Compile Mode\7f18943
-Node: Initialization Mode\7f20311
-Node: Link Mode\7f25343
-Node: Other ellcc options\7f26490
-Node: Environment Variables\7f29070
-Node: Defining Functions\7f30761
-Node: Using DEFUN\7f32772
-Node: Declaring Functions\7f34483
-Node: Defining Variables\7f35826
-Node: Index\7f38071
-\1f
-End Tag Table
projects / chise / xemacs-chise.git.1 / blobdiff