3. 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.

3.1 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).

3.2 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 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.

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 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 preferred extension.

3.3 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 ellcc in link mode, by 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.

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.

3.4 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 internal 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-dependent directory that XEmacs searches for architecture-dependent files.

--mod-config

Prints the name of the configuration for which XEmacs and ellcc were compiled.

3.5 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 recognizes.

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.