1 \input texinfo @c -*-texinfo-*-
4 @setfilename emodules.info
5 @settitle Extending Emacs using C Emodules
9 @set LAST_UPDATED May 3rd, 2008
12 This file documents the emodule loading technology of SXEmacs.
14 Copyright @copyright{} 1998 J. Kean Johnston.
15 Copyright @copyright{} 2007 Sebastian Freundt.
16 Copyright @copyright{} 2008 Steve Youngs.
18 Permission is granted to make and distribute verbatim copies of this
19 manual provided the copyright notice and this permission notice are
20 preserved on all copies.
23 Permission is granted to process this file through TeX and print the
24 results, provided the printed document carries copying permission notice
25 identical to this one except for the removal of this paragraph (this
26 paragraph not being relevant to the printed manual).
29 Permission is granted to copy and distribute modified versions of this
30 manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this manual
35 into another language, under the above conditions for modified versions,
36 except that this permission notice may be stated in a translation
37 approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of this
40 manual under the conditions for verbatim copying, provided also that the
41 section entitled ``GNU General Public License'' is included exactly as
42 in the original, and provided that the entire resulting derived work is
43 distributed under the terms of a permission notice identical to this
46 Permission is granted to copy and distribute translations of this manual
47 into another language, under the above conditions for modified versions,
48 except that the section entitled ``GNU General Public License'' may be
49 included in a translation approved by the Free Software Foundation
50 instead of in the original English.
60 @setchapternewpage odd
64 @title Extending SXEmacs using C and C++
65 @subtitle Version 2.0, September 2007
67 @author J. Kean Johnston
68 @author Sebastian Freundt
74 Copyright @copyright{} 1998 J. Kean Johnston. @*
75 Copyright @copyright{} 2007 Sebastian Freundt. @*
76 Copyright @copyright{} 2008 Steve Youngs. @*
79 Version @value{VERSION} @*
80 @value{LAST_UPDATED} @*
82 Permission is granted to make and distribute verbatim copies of this
83 manual provided the copyright notice and this permission notice are
84 preserved on all copies.
86 Permission is granted to copy and distribute modified versions of this
87 manual under the conditions for verbatim copying, provided also that the
88 section entitled ``GNU General Public License'' is included
89 exactly as in the original, and provided that the entire resulting
91 ived work is distributed under the terms of a permission notice
92 identical to this one.
94 Permission is granted to copy and distribute translations of this manual
95 into another language, under the above conditions for modified versions,
96 except that the section entitled ``GNU General Public License'' may be
97 included in a translation approved by the Free Software Foundation
98 instead of in the original English.
103 @dircategory SXEmacs Editor
105 * Emodules: (emodules). SXEmacs dynamic loadable emodule support.
113 This Info file contains @value{VERSION} of the SXEmacs dynamic loadable emodule
114 support documentation.
117 * Introduction:: Introducing emodules
118 * Anatomy of a Emodule:: Basic emodule layout and technology
119 * Building your Emodule:: How to build emodules
120 * Defining Functions:: Creating new Lisp primitives
121 * Defining Variables:: Creating new Lisp variables
122 * Finding & Loading Emodules:: The module-load-path
123 * Index:: Concept Index
125 @c @c Can't do that when using the simple node structure
127 @c --- The Detailed Node Listing ---
129 @c Anatomy of a Module
131 @c * Special Header Files:: Better include <emodules-ng.h>
132 @c * Recognised Functions:: Specially treated functions
133 @c * Recognised Variables:: Specially treated variables
134 @c * Loading other Modules:: How to load dependent modules
136 @c @c @c museum section?
137 @c @c Using @code{ellcc}
139 @c @c * Compile Mode:: Compiling modules using ellcc
140 @c @c * Initialization Mode:: Generating documentation and variables
141 @c @c * Link Mode:: Creating the final loadable module
142 @c @c * Other ellcc options:: Other useful options
143 @c @c * Environment Variables:: How to control ellcc
145 @c Building your Module
147 @c * Configuring:: How to
148 @c * Compiling and linking:: How to
149 @c * More Ideas:: Other things you might want
151 @c Defining Functions
153 @c * Using DEFUN:: Using the DEFUN macro to define functions
154 @c * Declaring Functions:: Declaring functions to the Lisp reader
160 @chapter Introduction
162 SXEmacs is a powerful, extensible editor. The traditional way of
163 extending the functionality of SXEmacs is to use its built-in Lisp
164 language (called Emacs Lisp, or elisp for short). However, while elisp
165 is a full programming language and capable of extending SXEmacs in more
166 ways than you can imagine, it does have its short-comings.
168 Firstly, elisp is an interpreted language, and this has serious speed
169 implications. Like all other interpreted languages (like Java), elisp
170 is often suitable only for certain types of application or extension.
171 So although elisp is a general purpose language, and very high level,
172 there are times when it is desirable to descend to a lower level compiled
173 language for speed purposes.
175 Secondly, elisp (or Lisp in general) is not a very common language any
176 more, except for certain circles in the computer industry. C is a far
177 more commonly known language, and because it is compiled, more suited to
178 a wider range of applications, especially those that require low level
179 access to a system or need to be as quick as possible.
181 @cindex Emacs Modules
184 @cindex shared object
186 This manual describes a way of extending SXEmacs using dynamic
187 sharable objects (DSOs aka dynamic loadable modules aka dynamically
188 loadable libraries, or just simply shared objects), which can
189 be written in C or C++ (or more generally in anything that can be
190 compiled to native object code on platforms that support shared
191 objects). After the build, they can be loaded into SXEmacs at any
194 SXEmacs emodule support is detected and enabled during configure time
195 by default on all systems that support loading of shared objects,
196 provided libtool and libltdl is properly installed. From a users
197 perspective, the internals of SXEmacs emodules are irrelevant.
198 All a user will ever need to know about shared objects is the name of
199 the shared object when they want to load a given emodule. From a
200 developers perspective though, a lot more is provided.
202 @c keep? museum section maybe?
207 @c Of primary interest is the @code{ellcc} program. This program is
208 @c created during compile time, and is intended to abstract compiler
209 @c specific characteristics from the developer. This program is called to
210 @c compile and link all objects that will make up the final shared object,
211 @c and accepts all common C compiler flags. @code{ellcc} also sets up the
212 @c correct environment for compiling modules by enabling any special
213 @c compiler modes (such as PIC mode), setting the correct include paths for
214 @c the location of @value{emacs} internal header files etc. The program will also
215 @c invoke the linker correctly to created the final shared object which is
216 @c loaded into @value{emacs}.
219 @c @cindex header files
220 @c CEmacs also makes all of the relevant @value{emacs} internal header files
221 @c available for module authors to use. This is often required to get data
222 @c structure definitions and external variable declarations. The header
223 @c files installed include the module specific header file
224 @c @file{emodules.h}. Due to the nature of dynamic modules, most of the
225 @c internals of @value{emacs} are exposed.
226 @c @xref{Top,,,internals,@value{emacs} Internals Manual}, for a
227 @c more complete discussion on how to extend and understand @value{emacs}. All of
228 @c the rules for C modules are discussed there.
232 @c Part of the @value{emacs} distribution is a set of sample modules. These are
233 @c not installed when @value{emacs} is, but remain in the @value{emacs} source tree.
234 @c These modules live in the directory @file{modules}, which is a
235 @c sub-directory of the main @value{emacs} source code directory. Please look at
236 @c the samples carefully, and maybe even use them as a basis for making
237 @c your own modules. Most of the concepts required for writing extension
238 @c modules are covered in the samples.
241 @c @cindex documentation
243 @c Last, but not least is this manual. This can be viewed from within
244 @c @value{emacs}, and it can be printed out as well. It is the intention of this
245 @c document that it will describe everything you need to know about
246 @c extending @value{emacs} in C. If you do not find this to be the case, please
247 @c contact the author(s).
250 The rest of this document will discuss the actual mechanics of
251 SXEmacs emodules and work through several of the samples. Please be
252 sure that you have read the SXEmacs Internals Manual and understand
253 everything in it. The concepts there apply to all emodules. This
254 document may have some overlap, but it is the internals manual which
255 should be considered the final authority. It will also help a great
256 deal to look at the actual SXEmacs source code to see how things are
260 @node Anatomy of a Emodule
261 @chapter Anatomy of a Emodule
263 @cindex module skeleton
264 @cindex skeleton, module
265 @cindex module format
266 @cindex format, module
268 A dynamically loadable SXEmacs extension (hereafter referred to as a
269 emodule) can carry certain special pieces of information and functions
270 which are then used in a predefined special way. This chapter
271 describes the basic layout of such a emodule, and provides a very
275 * Special Header Files:: Better include <emodules-ng.h>
276 * Recognised Functions:: Specially treated functions
277 * Recognised Variables:: Specially treated variables
278 * Loading other Emodules:: Additional notes on dependent emodules
282 @node Special Header Files
283 @section Special Header Files
285 @cindex include files
287 @cindex emodules-ng.h
290 Every emodule better includes the file @file{emodules-ng.h}. This
291 will primarily set up certain vital macros. If you want to stay close
292 to the rest of the SXEmacs binary, for example provide lisp bindings
293 of your stuff or implement functionality depending on whether or not
294 SXEmacs was configured with a certain feature, you should have a
295 thorough glance at @file{sxemacs.h}.
297 Most emodules will probably require some pre-processor conditionals
298 based on constants defined in @file{config.h} which is included
299 automatically upon inclusion of @file{sxemacs.h}. This file is
300 automatically generated during the configure phase of SXEmacs, its
301 prototype is @file{config.h.in} which in turn is autogenerated from
302 various macros in the @file{m4/} directory and @file{configure.ac}.
304 Depending on what your emodule will be doing at last, you will
305 probably need to include other header files as well.
323 @node Recognised Functions
324 @section Recognised Functions
325 @cindex functions, specially treated
326 @cindex recognised functions
328 A typical emodule will implement a fancy feature (or hopefully many
329 thereof) and thence be willing to provide a lisp binding in the
330 surface, e.g. a function, or anything similar to make use of the
331 feature. Sounds simple, is simple: SXEmacs just asks its inbuilt
332 crystal ball to determine which of your functions was meant to appear
335 Albeit tempting with respect to simplicity and comfort this
336 behaviour is technically an effort to realise. SXEmacs therefore
337 treats some symbols of your emodule in a special way.
340 Code which is run after opening the emodule and all its requisite
343 Usually this carries all the bindings you want to export to the lisp
344 surface, such as macros, functions, variables and (lisp) symbols.
345 Moreover, depending on your code this can be used to initialise
346 private setups, such as private tables or memory blocks.
350 Code which is run upon a reload of the emodule.
352 Normally this is just a @code{deinit();} call followed by another
353 @code{init();} call. The reason to have a special entry point for
354 reinitialisation is that, roughly, @code{reinit()} is not exactly just
355 a @code{deinit(); init();} sequence. For instance you might want to
356 avoid to initialise certain private memory blocks again because their
357 setup was a very expensive operation.
361 Code which is run after closing all of a emodule's requisites upon a
362 @code{unload-module} request.
364 Usually you would unleash all your privately held resources and unbind
365 any exported variables, functions, macros, and so forth.
369 A special function called to incorporate documentation strings for
372 Normally this entry point is generated automatically using the
373 @file{make-docfile} utility.
376 All these function are truly optional. Their signature is actually
378 @code{void(*)(emodng_t)}
380 but you can also make them
385 Quick notes re emodule unloading. It seems quite natural to be
386 able to unload stuff, at least in the perfect world. While this is
387 still true if your emodule provides truly complementary functionality
388 (whatever that is) it becomes a critical issue once you truly
389 intervene or even replace internal functionality. We are @emph{NOT}
390 barring you from unloading your emodule nor are we saying you should
391 avoid that feature but you should be aware of its dramatical
392 consequences when done sloppily.
394 The best comparison we can come up with is the concept of emodules
395 for the linux kernel. Imagine you were a emodule providing ultra fast
396 access to, say, scsi drives and therefore had to oust the kernel's
397 normal handlers for those drives. Now after unloading your emodule you
398 would reestablish the old, superseded handlers, would you not? As
399 mentioned before, today's system are usually not equipped with a
400 superior intelligence being able to completely understand your concept
401 and your mode of operation in order to automatically withdraw, or
402 simply revert, your actions just by looking at the emodule's code.
405 Ergo @emph{YOU} are responsible to restore the state of the system!
407 It does not necessarily mean that you have to unwind completely to
408 the exact state before you entered the scene, no, you are `only'
409 encouraged to leave a working system behind, whatever that means in
410 the context of your emodule.
414 Carefully consider if you want to unbind exported lisp variables.
416 If they are not filled with special lisp objects only your emodule
417 knows about it is definitely wise to leave them in the environment.
420 Carefully consider if you want to unbind exported macros.
422 After all a macro is just a piece of code which produces another piece
423 of code under the influence of some variables passed to it, so why not
427 Carefully consider if you want to unbind exported functions.
429 This is a bit more delicate. The lisp language does not distinguish
430 between code and data and your function could have ended up literally
431 anywhere. Simply unbinding your functions, using @code{UNDEFSUBR} or
432 @code{Ffmakunbound}, will possibly turn any reference to them into an
433 error generator. This is especially annoying when your emodule's
434 functions were used in so frequented hooks like @code{pre-gc-hook}.
436 Solution: Do not unbind your functions. Instead rebind them to
437 something which has the same input signature but, for instance,
438 produces an unmistakable message. Be prolific!
441 Any other scenario not covered here is basically either a real
442 auxiliary, read optionally, thing where unloading does not harm at
443 all, or it really affects the guts of SXEmacs in which case we take it
444 for granted that you know what you are doing anyway.
448 @node Recognised Variables
449 @section Recognised Variables
450 @cindex variables, specially treated
451 @cindex recognised variables
453 Basically there is only one specially-treated variable.
456 A @code{const char *} array which lists the names of all requisite
457 modules and is terminated with a @code{NULL} entry. These are opened
458 and initialised before the actual emodule is initialised.
461 Like the specially-treated functions above, this variable is also
462 optional. Moreover, the same naming policies apply, and most
463 importantly there is a convenience macro which hides the raw C work
466 @deffn macro REQUIRE name &rest names
467 Proclaim the requisite emodules of @var{name}. Set up and fill the
468 @code{dependencies} variable from @var{names} as discussed above.
472 @node Loading other Emodules
473 @section Loading other Emodules
476 Sometimes it is necessary to use functions, or generally symbols,
477 defined in a foreign emodule you depend on. In general it is
478 impossible to open (as in @code{dlopen()}) your emodule to extract the
479 @code{dependencies} variable when you refer to one of these external
480 symbols in your code. The corresponding error message goes along the
483 @code{Cannot open modules foo: Undefined symbol bar.}
489 The emodule itself can contain dynamic references to other libraries,
490 or, most likely, symbols from the SXEmacs binary. However, they have
491 to be resolvable, and in fact are tried to be resolved, when opening a
492 module. Now if you refer to symbols defined in another emodule
493 @footnote{This was not possible with the old emodule system} you, the
494 user, have to load that other emodule before.
497 So what's the rant about that @var{dependencies} thingiedingie?
499 As mentioned above the new @code{load-module} function will exactly
500 relieve you, the user, of this task provided the emodule proclaimed
501 the list of its dependencies. Now this seems to be a charade, in
502 order to open the emodule to read its dependencies you, the user, have
503 to load all of its dependencies because naively opening the emodule
504 will yield nothing but the error above when foreign symbols are used.
506 The solution is to provide a, sort of, low-quality draught version
507 of the foreign functions you, the emodule author, refer to. The
508 missing link here are the so-called @dfn{weak symbols}. They
509 usually do not carry any real information (variable) or functionality
510 (function) and are meant to be overwritten by the ``real'' symbol as
511 soon as possible. When properly coded their life-time spans just
512 about the time from opening the emodule to opening the requisite
513 module which, hopefully, defines real symbol and thence replaces the
517 Imagine @samp{module-A} is doing all the hard work and provides the
520 /* inside module-A.c */
521 bool solve_complex_problem(void)
529 Now @samp{module-B} contains a function @code{void
530 compute_lotto_numbers(void)} which goes:
533 /* inside module-B.c */
534 void compute_lotto_numbers(void)
536 if (solve_complex_problem()) @{
537 /* lotto numbers found, hooray! print them */
546 Leaving it like that will effectively bar your users from computing
547 the lotto numbers and I personally would hate you, the emodule
548 developer, for the rest of my life. However, to finish this example
549 using weak symbols you would additionally put into @file{module-B.c}:
553 bool solve_complex_problem(void) __attribute__((weak));
555 bool solve_complex_problem(void)
562 Some practical hints:
565 If you have included @file{sxemacs.h} already you can use its
566 @code{WEAK} and @code{WEAK_EXTERN} macros to hide the compiler
567 specific attribute declaration.
569 This magic spell can also be applied to C variables.
571 Do not simply make your weak version of a function a no-op, rather
572 make it notify your users or yourself that the weak version is still
573 in effect. This can save you a lot of trouble when things go wrong
574 and the weak version is stronger than you thought or never
575 overridden or the like.
579 @node Building your Emodule
580 @chapter Building your Emodule
581 @cindex module building
583 In contrast to former emodule concepts, the current <wordhere> is much
584 more flexible in all respects. This is a drama however since there is
585 no @emph{THE} way to do it and hence this section is only a showcase.
586 Nonetheless, we try to give a few more examples, clues even, in the
587 @ref{More Ideas} section below, obviously in the hope that they turn
591 * Configuring:: How to
592 * Compiling and linking:: How to
593 * More Ideas:: Other things you might want
597 @section Configuring your emodule
599 This step really depends on the purpose of your emodule. So we cut it
600 really short here. Consider this passage an assortment of useful
605 SXEmacs by default installs its configuration file @file{config.h} in
606 its header directory, @file{$prefix/include/sxemacs/@var{version}/} by
607 default, so you can conditionalise on whatever has been configured by
610 SXEmacs installs all its configure tests (written in m4) into
611 aclocal's macro directory, @file{$prefix/share/aclocal/} by default,
612 so you can basically repeat every single test which facilitates the
613 scenario where your emodule is configured differently than SXEmacs.
616 @node Compiling and linking
617 @section Compiling and linking your emodule
619 Basically using autotools and libtool your emodule is compiled with
623 module_LTLIBRARIES = my-module
624 my_module_SOURCES = source1.c source2.c @dots{}
625 my_module_LDFLAGS = -module
627 @file{Makefile.am} assuming @var{moduledir} is properly defined.
630 It becomes a wee bit more complex than that if you define lisp
631 bindings for which documentation strings are supposed to be exported.
635 module_LTLIBRARIES = my-module.la
636 my_module_la_SOURCES = source1.c source2.c @dots{}
637 nodist_my_module_la_SOURCES = source.doc.c
638 my_module_la_LDFLAGS = -module
639 BUILT_SOURCES = source.doc.c
642 source.doc.c: $(my_module_la_SOURCES)
643 $(make_docfile) --modname $* -E $@ $^
645 @file{Makefile.am} for emodule @samp{my-module} with built
646 documentation strings
649 Note: In both examples we assume that you defined a (make) variable
650 moduledir. The final emodule will be installed there. In the second
651 example we also assume that the variable @var{make_docfile} points to
652 the @file{make-docfile} utility.
658 The sole purpose of the above examples is to show off. Making
659 emodules has become as easy as making children, but basically you are
660 not restricted to the above way. Hence an assortment of useful clues:
664 The basic manual compilation command for C sources goes along the
667 gcc -g -O2 -shared -o my-module.so.0 my-source.c
673 f77 -g -O2 -shared -o my-module.so.0 my-source.f
677 Emodules themselves can be linked to a whole world of shared libraries,
678 they are automatically loaded. Linking emodules to other emodules is
679 possible on some platforms but in general not portable.
682 The @file{make-docfile} utility can always be very easily found when
683 you know the location of an installed SXEmacs binary. Instead of
684 calling @file{make-docfile} directly you would call
685 @code{sxemacs --make-docfile} and pass all arguments you would
686 normally pass thereafter.
688 The target of the example in the previous section then reads:
690 make_docfile = sxemacs --make-docfile
693 source.doc.c: $(my_module_la_SOURCES)
694 $(make_docfile) --modname $* -E $@ $^
698 Basically the suffix @file{.doc.c} is not compulsory. In fact, you
699 can choose whatever you like there. In our eyes this is yet
700 convenient since the created file is indeed a C file and hence there
701 will be no trouble for any @samp{.c.o} rules you might have to cope
702 with the compilation.
704 On the other hand, having its suffix be @file{.doc.c} facilitates the
705 use of a pattern-based rule in your Makefile when your emodule consists
706 of many single source files which otherwise means that you had to
707 create a @samp{@var{file}.doc.c} rule for each file.
709 We ourselves use the following pattern-based rule:
711 make_docfile = $(SXEMACS) --make-docfile
715 $(make_docfile) --modname $* -E $@ $<
717 where the @var{SXEMACS} variable points to the just built
718 @file{sxemacs} binary.
720 For all make-agnostics the above rule means that given a C file
721 @file{foo.c} the rule to create a file @file{foo.doc.c} with the
722 documentation strings in it goes:
724 $(SXEMACS) --make-docfile --modname foo -E foo.doc.c foo.c
726 when the command is maximally expanded.
729 The @file{make-docfile} utility itself does not (yet) come with a
730 sensible @samp{--help} output. Here in short the explanation you may
733 make-docfile [--modname <name>] -E <outfile> <infile> [<infile> @dots{}]
739 @c @node Compile Mode, Initialization Mode, Using ellcc, Using ellcc
740 @c @section Compile Mode
743 @c By default, @code{ellcc} is in @dfn{compile} mode. This means that it
744 @c assumes that all of the command line arguments are C compiler arguments,
745 @c and that you want to compile the specified source file or files. You
746 @c can force compile mode by specifying the @code{--mode=compile} argument
749 @c In this mode, @code{ellcc} is simply a front-end to the same C compiler
750 @c that was used to create the @value{emacs} binary itself. All @code{ellcc}
751 @c does in this mode is insert a few extra command line arguments before
752 @c the arguments you specify to @code{ellcc} itself. @code{ellcc} will
753 @c then invoke the C compiler to compile your module, and will return the
754 @c same exit codes and messages that your C compiler does.
756 @c By far the easiest way to compile modules is to construct a
757 @c @file{Makefile} as you would for a normal program, and simply insert, at
758 @c some appropriate place something similar to:
762 @c CC=ellcc --mode=compile
765 @c $(CC) $(CFLAGS) -c $<
769 @c After this, all you need to do is provide simple @code{make} rules for
770 @c compiling your module source files. Since modules are most useful when
771 @c they are small and self-contained, most modules will have a single
772 @c source file, aside from the module specific initialization file (see
773 @c below for details).
775 @c @node Initialization Mode, Link Mode, Compile Mode, Using ellcc
776 @c @section Initialization Mode
777 @c @cindex initialization
778 @c @cindex documentation
780 @c @value{emacs} uses a rather bizarre way of documenting variables and
781 @c functions. Rather than have the documentation for compiled functions
782 @c and variables passed as static strings in the source code, the
783 @c documentation is included as a C comment. A special program, called
784 @c @file{make-docfile}, is used to scan the source code files and extract
785 @c the documentation from these comments, producing the @value{emacs} @file{DOC}
786 @c file, which the internal help engine scans when the documentation for a
787 @c function or variable is requested.
789 @c Due to the internal construction of Lisp objects, subrs and other such
790 @c things, adding documentation for a compiled function or variable in a
791 @c compiled module, at any time after @value{emacs} has been @dfn{dumped} is
792 @c somewhat problematic. Fortunately, as a module writer you are insulated
793 @c from the difficulties thanks to your friend @code{ellcc} and some
794 @c internal trickery in the module loading code. This is all done using
795 @c the @dfn{initialization} mode of @code{ellcc}.
797 @c The result of running @code{ellcc} in initialization mode is a C source
798 @c file which you compile with (you guessed it) @code{ellcc} in compile
799 @c mode. Initialization mode is where you set the module name, version,
800 @c title and gather together all of the documentation strings for the
801 @c functions and variables in your module. There are several options that
802 @c you are required to pass @code{ellcc} in initialization mode, the first
803 @c of which is the mode switch itself, @code{--mode=init}.
805 @c Next, you need to specify the name of the C source code file that
806 @c @code{ellcc} will produce, and you specify this using the
807 @c @code{--mod-output=FILENAME} argument. @var{FILENAME} is the name of
808 @c the C source code file that will contain the module variables and
809 @c @code{docs_of_module} function.
811 @c As discussed previously, each module requires a short @dfn{handle} or
812 @c module name. This is specified with the @code{--mod-name=NAME} option,
813 @c where @var{NAME} is the abbreviated module name. This @var{NAME} must
814 @c consist only of characters that are valid in C function and variable
817 @c The module version is specified using @code{--mod-version=VERSION}
818 @c argument, with @var{VERSION} being any arbitrary version string. This
819 @c version can be passed as an optional second argument to the Lisp
820 @c function @code{load-module}, and as the third argument to the internal
821 @c module loading command @code{emodules_load}. This version string is
822 @c used to distinguish between different versions of the same module, and
823 @c to ensure that the module is loaded at a specific version.
825 @c Last, but not least, is the module title. Specified using the
826 @c @code{--mod-title=TITLE} option, the specified @var{TITLE} is used when
827 @c the list of loaded modules is displayed. The module title serves no
828 @c purpose other than to inform the user of the function of the module.
829 @c This string should be brief, as it has to be formatted to fit the
832 @c Following all of these parameters, you need to provide the list of all
833 @c source code modules that make up your module. These are the files which
834 @c are scanned by @file{make-docfile}, and provide the information required
835 @c to populate the @code{docs_of_module} function. Below is a sample
836 @c @file{Makefile} fragment which indicates how all of this is used.
840 @c CC=ellcc --mode=compile
841 @c LD=ellcc --mode=link
842 @c MODINIT=ellcc --mode=init
843 @c CFLAGS=-O2 -DSOME_STUFF
846 @c $(CC) $(CFLAGS) -c $<
850 @c MODTITLE="Small sample module"
852 @c SRCS=modfile1.c modfile2.c modfile3.c
853 @c OBJS=$(SRCS:.c=.o)
857 @c rm -f $(OBJS) sample_init.o sample.ell
860 @c mkdir `ellcc --mod-location`/mymods > /dev/null
861 @c cp sample.ell `ellcc --mod-location`/mymods/sample.ell
863 @c sample.ell: $(OBJS) sample_init.o
864 @c $(LD) --mod-output=$@ $(OBJS) sample_init.o
866 @c sample_init.o: sample_init.c
867 @c sample_init.c: $(SRCS)
868 @c $(MODINIT) --mod-name=$(MODNAME) --mod-version=$(MODVER) \
869 @c --mod-title=$(MODTITLE) --mod-output=$@ $(SRCS)
873 @c The above @file{Makefile} is, in fact, complete, and would compile the
874 @c sample module, and optionally install it. The @code{--mod-location}
875 @c argument to @code{ellcc} will produce, on the standard output, the base
876 @c location of the @value{emacs} module directory. Each sub-directory of that
877 @c directory is automatically searched for modules when they are loaded with
878 @c @code{load-module}. An alternative location would be
879 @c @file{/usr/local/lib/sxemacs/site-modules}. That path can change depending
880 @c on the options the person who compiled @value{emacs} chose, so you can
881 @c always determine the correct site location using the
882 @c @code{--mod-site-location} option. This directory is treated the same way
883 @c as the main module directory. Each sub-directory within it is searched for
884 @c a given module when the user attempts to load it. The valid extensions that
885 @c the loader attempts to use are @file{.so}, @file{.ell} and @file{.dll}. You
886 @c can use any of these extensions, although @file{.ell} is the preferred
889 @c @node Link Mode, Other ellcc options, Initialization Mode, Using ellcc
890 @c @section Link Mode
893 @c Once all of your source code files have been compiled (including the
894 @c generated init file) you need to link them all together to create the
895 @c loadable module. To do this, you invoke @code{ellcc} in link mode, by
896 @c passing the @code{--mode=link} option. You need to specify the final
897 @c output file using the @code{--mod-output=NAME} option, but other than
898 @c that all other arguments are passed on directly to the system compiler
899 @c or linker, along with any other required arguments to create the
902 @c The module has complete access to all symbols that were present in the
903 @c dumped @value{emacs}, so you do not need to link against libraries that were
904 @c linked in with the main executable. If your library uses some other
905 @c extra libraries, you will need to link with those. There is nothing
906 @c particularly complicated about link mode. All you need to do is make
907 @c sure you invoke it correctly in the @file{Makefile}. See the sample
908 @c @file{Makefile} above for an example of a well constructed
909 @c @file{Makefile} that invoked the linker correctly.
911 @c @node Other ellcc options, Environment Variables, Link Mode, Using ellcc
912 @c @section Other @code{ellcc} options
915 @c Aside from the three main @code{ellcc} modes described above,
916 @c @code{ellcc} can accept several other options. These are typically used
917 @c in a @file{Makefile} to determine installation paths. @code{ellcc} also
918 @c allows you to over-ride several of its built-in compiler and linker
919 @c options using environment variables. Here is the complete list of
920 @c options that @code{ellcc} accepts.
923 @c @item --mode=compile
924 @c Enables compilation mode. Use this to compile source modules.
927 @c Enabled link edit mode. Use this to create the final module.
930 @c Used to create the documentation function and to initialize other
931 @c required variables. Produces a C source file that must be compiled with
932 @c @code{ellcc} in compile mode before linking the final module.
934 @c @item --mode=verbose
935 @c Enables verbose mode. This will show you the commands that are being
936 @c executed, as well as the version number of @code{ellcc}. If you specify
937 @c this option twice, then some extra debugging information is displayed.
939 @c @item --mod-name=NAME
940 @c Sets the short internal module @var{NAME} to the string specified,
941 @c which must consist only of valid C identifiers. Required during
942 @c initialization mode.
944 @c @item --mod-version=VERSION
945 @c Sets the internal module @var{VERSION} to the specified string.
946 @c Required during initialization mode.
948 @c @item --mod-title=TITLE
949 @c Sets the module descriptive @var{TITLE} to the string specified. This
950 @c string can contain any printable characters, but should not be too
951 @c long. It is required during initialization mode.
953 @c @item --mod-output=FILENAME
954 @c Used to control the output file name. This is used during
955 @c initialization mode to set the name of the C source file that will be
956 @c created to @var{FILENAME}. During link mode, it sets the name of the
957 @c final loadable module to @var{FILENAME}.
959 @c @item --mod-location
960 @c This will print the name of the standard module installation path on the
961 @c standard output and immediately exit @code{ellcc}. Use this option to
962 @c determine the directory prefix of where you should install your modules.
964 @c @item --mod-site-location
965 @c This will print the name of the site specific module location and exit.
967 @c @item --mod-archdir
968 @c Prints the name of the root of the architecture-dependent directory that
969 @c @value{emacs} searches for architecture-dependent files.
971 @c @item --mod-config
972 @c Prints the name of the configuration for which @value{emacs} and @code{ellcc}
976 @c @node Environment Variables, , Other ellcc options, Using ellcc
977 @c @section Environment Variables
978 @c @cindex environment variables
980 @c During its normal operation, @code{ellcc} uses the compiler and linker
981 @c flags that were determined at the time @value{emacs} was configured. In
982 @c certain rare circumstances you may wish to over-ride the flags passed to
983 @c the compiler or linker, and you can do so using environment variables.
984 @c The table below lists all of the environment variables that @code{ellcc}
989 @c @cindex @code{ELLCC}
990 @c This is used to over-ride the name of the C compiler that is invoked by
994 @c @cindex @code{ELLLD}
995 @c Sets the name of the link editor to use to created the final module.
998 @c @cindex @code{ELLCFLAGS}
999 @c Sets the compiler flags passed on when compiling source modules. This
1000 @c only sets the basic C compiler flags. There are certain hard-coded
1001 @c flags that will always be passed.
1004 @c @cindex @code{ELLLDFLAGS}
1005 @c Sets the flags passed on to the linker. This does @strong{not} include
1006 @c the flags for enabling PIC mode. This just sets basic linker flags.
1008 @c @item ELLDLLFLAGS
1009 @c @cindex @code{ELLDLLFLAGS}
1010 @c Sets the flags passed to the linker that are required to created shared
1011 @c and loadable objects.
1013 @c @item ELLPICFLAGS
1014 @c @cindex @code{ELLPICFLAGS}
1015 @c Sets the C compiler option required to produce an object file that is
1016 @c suitable for including in a shared library. This option should turn on
1017 @c PIC mode, or the moral equivalent thereof on the target system.
1020 @c @cindex @code{ELLMAKEDOC}
1021 @c Sets the name of the @file{make-docfile} program to use. Usually
1022 @c @code{ellcc} will use the version that was compiled and installed with
1023 @c @value{emacs}, but this option allows you to specify an alternative path.
1024 @c Used during the compile phase of @value{emacs} itself.
1028 @node Defining Functions
1029 @chapter Defining Functions
1030 @cindex defining functions
1032 One of the main reasons you would ever write a emodule is to
1033 provide one or more @dfn{functions} for the user or the editor to use.
1034 The term @dfn{function} is a bit overloaded here, as it refers to both
1035 a C function and the way it appears to Lisp, which is a
1036 @dfn{subroutine}, or simply a @dfn{subr}.
1038 A Lisp subr is also known as a Lisp primitive, but that term applies
1039 less to dynamic emodules. @xref{Writing Lisp
1040 Primitives,,,internals,SXEmacs Internals Manual}, for details on
1041 how to declare functions.
1043 Normal Lisp primitives document the functions they define by
1044 including the documentation as a C comment. During the build process,
1045 a program called @file{make-docfile} is run, which will extract all of
1046 these comments, build up a single large documentation file, and will
1047 store pointers to the start of each documentation entry in the dumped
1051 * Using DEFUN:: Using the DEFUN macro to define functions
1052 * Declaring Functions:: Declaring functions to the Lisp reader
1057 @section Using @code{DEFUN}
1060 @cindex functions, Lisp
1061 @cindex functions, defining
1063 Although the full syntax of a function declaration is discussed in the
1064 SXEmacs internals manual in greater depth, what follows is a brief
1065 description of how to define and implement a new Lisp primitive in a
1066 module. This is done using the @code{DEFUN} macro. Here is a small
1071 DEFUN("my-function", Fmy_function, 1, 1, "FFile name: ", /*
1072 Sample Emacs primitive function.
1074 The specified FILE is frobnicated before it is fnozzled.
1083 filename = (char *)XSTRING_DATA(file);
1090 The first argument is the name of the function as it will appear to the
1091 Lisp reader. This must be provided as a string. The second argument is
1092 the name of the actual C function that will be created. This is
1093 typically the Lisp function name with a preceding capital @code{F}, with
1094 hyphens converted to underscores. This must be a valid C function
1095 name. Next come the minimum and maximum number of arguments,
1096 respectively. This is used to ensure that the correct number of
1097 arguments are passed to the function. Next is the @code{interactive}
1098 definition. If this function is meant to be run by a user
1099 interactively, then you need to specify the argument types and prompts
1100 in this string. Please consult the SXEmacs Lisp manual for more
1101 details. Next comes a C comment that is the documentation for this
1102 function. Last comes the list of function argument names, if any.
1104 @node Declaring Functions
1105 @section Declaring Functions
1107 @cindex functions, declaring
1109 Simply writing the code for a function is not enough to make it
1110 available to the Lisp reader. You should use the specially treated
1111 @code{init} function in your emodule to let the lisp reader know about
1112 all the great subroutines you have coded, @xref{Recognised Functions}.
1114 This is done by calling @code{DEFSUBR} with the name of the
1115 function (its C name, ya know?) as its only argument. Using the
1116 example function above, your body of the @code{init} function would
1123 DEFSUBR(Fmy_function);
1128 This call will instruct SXEmacs to make the function visible to the
1129 Lisp reader and will prepare for the insertion of the documentation
1130 into the right place. Once this is done, the user can call the Lisp
1131 function @code{my-function}.
1133 Basically, that is all you need to define and proclaim new functional
1134 lisp bindings. The rules for what goes inside the functions, and how
1135 to write good emodules, is beyond the scope of this document. Please
1136 consult the SXEmacs internals manual for more details.
1139 @node Defining Variables
1140 @chapter Defining Variables
1141 @cindex defining variables
1142 @cindex defining objects
1146 @cindex variables, Lisp
1147 @cindex variables, defining
1148 @cindex objects, defining
1149 @cindex objects, Lisp
1151 Rarely will you write a emodule that only contains functions. It is
1152 common to also provide variables which can be used to control the
1153 behaviour of functions or store a certain state or simply the results
1154 of a function being executed. The actual C variable types are the
1155 same for emodules and internal SXEmacs primitives, and the declaration
1156 of the variables is identical.
1158 @xref{Adding Global Lisp Variables,,,internals,SXEmacs Internals Manual},
1159 for more information on variables and naming conventions.
1161 Once your variables are defined and initialised properly, you need
1162 to make the Lisp reader aware of them. This is done in the specially
1163 treated @code{init} function of your emodule using special SXEmacs
1164 macros such as @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}, @code{DEFVAR_INT}
1165 etc. The best way to see how to use these macros is to look at existing
1166 source code, or read the internals manual.
1168 Below is a small example which declares and properly proclaims two
1169 variables. You will note that this code takes into account the fact
1170 that this emodule may very well be compiled into SXEmacs itself. This
1171 is a prudent thing to do.
1175 Lisp_Object Vsample_string;
1180 DEFVAR_LISP("sample-string", &Vsample_string /*
1181 This is a sample string, declared in a module.
1183 Nothing magical about it.
1186 DEFVAR_BOOL("sample-boolean", &sample_boolean /*
1187 *Sample user-settable boolean.
1191 Vsample_string = build_string("My string");
1196 @node Finding & Loading Emodules
1197 @chapter Finding & Loading Emodules
1198 @cindex module load path
1199 @cindex module-load-path
1201 @cindex finding emodules
1202 @cindex module loading
1203 @cindex emodule loading
1204 @cindex loading modules
1205 @cindex loading emodules
1208 Loading a SXEmacs Emodules is usually simply a matter of@dots{}
1210 @code{(require 'emodname)}
1212 Emodules can also be loaded interactively with@dots{}
1214 @code{M-x load-module}
1216 @dfn{#'load-module} supports completion, making it a bit easier for
1219 The default search path for Emodules (also known as
1220 @dfn{module-load-path}) is@dots{}
1223 @file{~/.sxemacs/$machinetriplet/modules}
1224 @file{$prefix/lib/sxemacs/$machinetriplet/site-modules}
1225 @file{$prefix/lib/sxemacs-$version/$machinetriplet/modules}
1228 Searching recurses down one level below these directories. The
1229 @dfn{module-load-path} is also part of the standard @dfn{load-path}.
1230 This means that if an emodule shares the same feature symbol name as a
1231 elisp library in the @dfn{load-path}, that one that is loaded from a
1232 @dfn{#'require} call will be the one that is higher up in the
1235 It is possible to set the @dfn{module-load-path} at SXEmacs configure
1236 time using the @option{--with-module-path=PATH} configure option. But
1237 you normally would @emph{not} need to do this, as SXEmacs' build chain
1238 is smart enough to set sane defaults.
1240 Locating where a particular emodule is installed on disc can be done
1241 with the function, @dfn{#'locate-module}.
1243 To see which emodules are loaded in the current SXEmacs session, use
1244 @dfn{#'list-modules}. It returns a list of emodule names (strings),
1245 or if called interactively, it displays the list of emodules in the
1246 echo area. The names are the emodules' @emph{internal}.
1250 @result{} ("cl" "cl-loop" "ase" "ase_set")
1255 @c Print the tables of contents