@code{DEFVAR_LISP()}, @code{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 @value{emacs} source code.
+all internal @value{emacs} source code. If the module is intended to be
+usable statically linked into XEmacs, the actions of this function are
+severely restricted. @xref{General Coding Rules,,,internals,
+@value{emacs} Internals Manual}. Also see the comments in
+@file{src/emacs.c} (@code{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.
@item modules_of_module
@findex modules_of_module
then their parents will also fail to load. This does not include
previous successful calls to @code{emodules_load} at the top level.
+@strong{Warning:} Modules are @emph{not} loaded with the
+@code{RTLD_GLOBAL} flag. The practical upshot is that individual
+modules do not have access to each other's C symbols. One module cannot
+make a C function call to a function defined in another module, nor can
+it read or set a C variable in another module. All interaction between
+modules must, therefore, take place at the Lisp level. This is by
+design. Other projects have attempted to use @code{RTLD_GLOBAL}, only
+to find that spurious symbol name clashes were the result. Helper
+functions often have simple names, increasing the probability of such a
+clash. If you really need to share symbols between modules, create a
+shared library containing those symbols, and link your modules with
+that library. Otherwise, interactions between modules must take place
+via Lisp function calls and Lisp variables accesses.
+
@node Using ellcc, Defining Functions, Anatomy of a Module, Top
@chapter Using @code{ellcc}
@cindex @code{ellcc}
sample module, and optionally install it. The @code{--mod-location}
argument to @code{ellcc} will produce, on the standard output, the base
location of the @value{emacs} module directory. Each sub-directory of that
-directory is automatically searched for for modules when they are loaded
-with @code{load-module}. An alternative location would be
-@file{/usr/local/lib/xemacs/site-modules}. That path can change
-depending on the options the person who compiled @value{emacs} chose, so you
-can always determine the correct site location using the
-@code{--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 @file{.so},
-@file{.ell} and @file{.dll}. You can use any of these extensions,
-although @file{.ell} is the preferred extension.
+directory is automatically searched for modules when they are loaded with
+@code{load-module}. An alternative location would be
+@file{/usr/local/lib/xemacs/site-modules}. That path can change depending
+on the options the person who compiled @value{emacs} chose, so you can
+always determine the correct site location using the
+@code{--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 @file{.so}, @file{.ell} and @file{.dll}. You
+can use any of these extensions, although @file{.ell} is the preferred
+extension.
@node Link Mode, Other ellcc options, Initialization Mode, Using ellcc
@section 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 create the
loadable module. To do this, you invoke @code{ellcc} in link mode, by
-passing the @code{--mode-link} option. You need to specify the final
+passing the @code{--mode=link} option. You need to specify the final
output file using the @code{--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
projects / chise / xemacs-chise.git.1 / blobdiff