Next: Index Up: Building Unix Squeak ( Previous: 2 Generating your own Contents Index
Note: This section is intended primarily for plugin developers.
If your plugin requires no platform-specific tweaks then there's nothing for you to do. configure (and config.status) will provide a default Makefile for it that should work. If your plugin requires only platform-independent tweaks (and/or additional hand-written code) then these go in platforms/Cross/plugins, and there's nothing for you to do (in Unixland).
On the other hand, if you require special configure tests or additional declarations/rules in your plugin's Makefile then you need to specify them explicitly.
Note: Unix Squeak subscribes to the following philopsophy:
Absolutely everything that is specific to Unix (sources, headers, configure and Makefile extensions, etc.) lives under platforms/unix.
In other words: there is not (nor aught there be) any Unix-related information under the platforms/Cross directory. (Unix Squeak is entirely encapsulated under platforms/unix and is utterly immune to ``random junk'' elsewhere in the platforms tree.)
First you must create a new directory
under platforms/unix/plugins named after your plugin. This directory
will hold the files describing the additional configuration checks
and/or Makefile contents. For example, if your plugin is
called ``MyCoolPlugin'' then
$ mkdir platforms/unix/plugins/MyCoolPlugin
would be the thing to do. (The following sections will refer to this directory as platdep since the full path is quite a mouthful of typing for my lazy fingers.)
Your plugin can ask configure to run additional tests (and to set additional variables in its output files) simply by including a file called acinclude.m4 in it's platdep directory.
Note: The configure script is `compiled' from several other files. If you create a `platdep./acinclude.m4' file then you must `recompile' configure. You can do this by `cd'ing to unix/config and running `make', or (if you have GNU make) from the blddir like this:
$ make -C ../platforms/unix/config
In addition to the usual autoconf macros, the following macros are available specifically for Squeak plugins to use:
This is similar to the autoconf `AC_CHECK_LIB' macro.
func is the name of a function required by the plugin, defined in the external (system) library lib. The macro checks that the library is available (via `-llib') and then adds it to the list of libraries required by the plugin (see the explanation of [plibs] in Section 3.2.1 for a description of how library dependencies for plugins are handled).
If func cannot be found in lib then the plugin will be disabled and a message to that effect printed during configuration. (The VM can still be built, without rerunning VMMaker or reconfiguring, and the plugin will simply be ommitted from it.)
This is similar to the autoconf `AC_DEFINE_UNQUOTED' macro.
keyword is a Makefile keyword (usually of the form `[name]') and text is arbitrary text to be associated with it. Calling this macro causes mkmf to substitute text for all occurrences of keyword in the Makefile generated for the plugin.
The following variables are also set during the execution of a plugin-specific acinclude.m4:
Three mechanisms are avilable for this:
Before proceeding, let's take a minute to understand how Unix Squeak compiles and links files in its default Makefile for plugins. The default Makefile looks like this:
# default Makefile for Unix Squeak plugins
[make_cfg]
[make_plg]
XINCLUDES = [includes]
OBJS = [targets]
TARGET = [target]
PLIBS = [plibs]
[make_inc]
$(TARGET) : $(OBJS) Makefile
$(LINK) $(TARGET) $(OBJS) $(PLIBS)
[make_targets]
.force :
Note: The keywords appearing between `[ square brackets ]' are substituted during configuration by a preprocessor called `mkmf' according to the kind of plugin (internal/external) being built.
[make_cfg] is the configured variable section. It contains the platform-specific information gleaned by configure while it was figuring out which compiler you have, what flags your linker needs, where to install stuff, and so on.
[make_plg] contains a handful of definitions which depend on whether the plugin is being compiled as internal or external:
o the extension for object files a the extension for plugins COMPILE the command to compile a source file into an object file LINK the command to link one or more object files into a plugin
For internal plugins: $o is `.o' and $a is `.a'. $(COMPILE) is the C compiler (`$(CC) ... -o', so the first thing after the command must be the output filename) and $(LINK) is archiver (`ar -rc', again requiring the output file to follow immediately). Note that internal plugins are built as `ar' archives before being linked into the final binary.
For external plugins: $o is `.lo', $a is `.la', and $(COMPILE) and $(LINK) are invocations of `libtool' to create position-independent objects and shared libraries (with a `-o' appearing right at the end, so the first thing after the command must be the output filename).
[includes]
is a list of `-Idir'
compiler flags, one for each of the
directories
src/plugins/name
in which at least one header file is present.
src/vm/intplugins/name
platforms/Cross/plugins/name
platforms/unix/plugins/name
[targets]
is a list of object files
corresponding to the source (.c) files found in
the directories:
src/plugins/name/*.c
where each source file has been stripped of the directory name and had the
`.c' converted into `$o'.
src/vm/intplugins/name/*.c
platforms/Cross/plugins/name/*.c
platforms/unix/plugins/name/*.c
[target] is the name of the plugin, including the $a extension.
[plibs] is a list of zero or more libraries on which the plugin depends (as detected using the macro AC_PLUGIN_CHECK_LIB in the plugin-specific acinclude.m4). If the plugin is being built internally then this list is empty and the required libraries are included in the final link command. If the plugin is being built externally then the plugin itself (a shared object) is linked against these libraries (via [plist]) rather than with the main VM binary.
(This is to ensure that a missing shared object needed by an external plugin will only affect the operation of that plugin and not prevent the rest of the VM from running, which would be the case if the entire VM were linked against it.)
[make_inc] is the contents of the Makefile.inc file in your plugin's platdep directory (or empty if this file doesn't exist).
[make_targets] is a list of rules for building the files listed in [targets]. Each rule looks like this:
You should never pass additional flags to these commands explicitly. This is because you cannot know how they are defined. (Their definitions depend on whether the plugin is being built internally or externally -- and might even change radically in future releases of Unix Squeak.)
Instead you should pass additional compiler/linker flags to these commands by setting the following variables in `Makefile.inc' or `Makefile.in':
XCPPFLAGS `-I' flags for cpp XDEFS `-D' flags for cpp XCFLAGS anything to be passed to the compiler XLDFLAGS anything to be passed to the linker
Note: `mkmf' already uses `XINCLUDES' to pass the list of directories containing plugin header files to cpp. You can redefine it if you like, but make sure that `[includes]' appears in its definition (or in the definition of `XCPPFLAGS').
mkmf looks for a file in your plugin's platdep directory called `mkmf.subdirs'. If this file exists then it should contain a list of directory names relative to the top-level directory (the one containing the src and platform directories). These directories will be added to the list of locations searched for `.c' and `.h' files while constructing the substitutions for `[includes]', `[targets]' and `[make_targets]'.
If the file platdep/Makefile.inc exists then mkmf will substitute its contents into the Makefile in place of the [make_inc] keyword.
Note: Makefile.inc is read into the Makefile under construction before mkmf performs substitutions on the `[keyword]'s. In other words, your Makefile.inc can use the above keywords to include relevant declarations and rules without worrying about whether the plugin is internal or external.
If neither of the above are sufficient then you can create a complete Makefile template called platdep/Makefile.in. mkmf will use this template instead of the default Makefile template shown earlier, and will perform keyword substitutions on it as described above to create the final Makefile. (In other words, simply copying the default template shown earlier will result in a Makefile identical to the one that mkmf would have produced by default.
By way of example we'll look at how two existing plugins specialise their configuration and Makefiles.
The B3DAcceleratorPlugin requires OpenGL in order to compile. The file unix/plugins/B3DAcceleratorPlugin/acinclude.m4 contains a single call to an autoconf-style macro:
This works similarly to the autoconf `AC_SEARCH_LIBS' macro: If a library libGL.{a,so} (OpenGL) exists and exports the function glIsEnabled() then `-lGL' is added to the final VM link command. Otherwise the plugin is disabled (and a message warning of the fact is printed).
Note: There's a bug here. This should also check for `GL_VERSION_1_1' in headers.
The Mpeg3Plugin requires a (modified) libmpeg to be compiled along with it. The sources for this library are in (several) subdirectories of Cross/Meg3Plugin and they require additional cpp definitions in order to compile correctly.
To cope with the additional directories, unix/plugins/Mpeg3Plugin/mkmf.subdirs simply lists them:
To cope with the additional cpp definitions, we could have written a tiny Makefile.inc containing:
Unfortunately the additional source directories contain various utility and test programs (which must not be built) so we cannot rely on mkmf generating the correct [targets] list.
Instead we just copy the default Makefile ``template'' (shown above) as Mpeg3Plugin/Makefile.in and insert the required list of targets (and cpp definition) manually. The end result looks like this:
# Makefile.in for Mpeg3Plugin in Unix Squeak
[make_cfg]
[make_plg]
TARGET = Mpeg3Plugin$a
PLUGIN = Mpeg3Plugin$o
VIDEO = getpicture$o headers$o idct$o macroblocks$o etc...
AUDIO = dct$o header$o layer1$o layer2$o layer3$o etc...
LIBMPEG = bitstream$o changesForSqueak$o libmpeg3$o etc...
OBJS = $(PLUGIN) $(VIDEO) $(AUDIO) $(LIBMPEG)
XINCLUDES = [includes]
XDEFS = -DNOPTHREADS
$(TARGET) : $(OBJS) Makefile
$(LINK) $(TARGET) $(OBJS)
[make_targets]
.force :
Note: The default `[make_targets]' will contain additional rules for the objects that we're trying to avoid building (because it's built from an exhaustive list of `.c' files in the source directories). This does no harm since the offending rules can never be triggered (their targets are not listed in `OBJS').
VMMaker will refuse to compile a plugin if it thinks the plugin requires platform support. This is ``all-or-nothing'': if platform support is required on one platform then it is required on all platforms (even if the plugin compiles quite happily without platform support in Unix).
The easiest way to add ``null'' platform support is to place an empty `Makefile.inc' in the plugin's platdep directory. (To see this in action, look in unix/plugins/JPEGReadWriter2Plugin.)
(Where ``all else failing'' is defined as: ``after trying for 20 minutes and still getting nowhere''.)
If you're writing a plugin that needs platform support (beyond dumb inclusion of a few additional `.c' files) and this document has been of no help at all (or if you understood it but you're still suffering from ``all else failing'') then send me mail and I'll be happy to help you with the various platdep files.
2009-08-12