===========
Win32 build
===========
Under win32 you should use the 'Makefile' files that were created manually, you will find
them in each plugin directory. Do not use the nextgen.sh scripts or configure.
==========
UNIX build
==========
=====================
1. Copyright & Licensing
=====================
nextgen.sh is Copyright (C) 2001, 2002 AbiSource, Inc. and is licensed under the
GNU GPL (see COPYING).
See individual plugins for copyright and licensing. GNU GPL should be assumed unless
explicitly stated otherwise.
==============================
2. Configuring in abiword-plugins
==============================
'./configure --help' lists a number of options.
Most importantly, plugins can be enabled/disabled via configure options. configure --help
will list these options. Recommended practice is to set the default to all disabled using
--disable-all option, and to enable specific plugins. For example, to build only the HTML
importer you would do:
./configure --disable-all --enable-html [--with-libxml2=/opt/libxml2-2.4.13]
The AbiWord sources are required for most plugins, and abiword-plugins/configure requires
them. It searches for a peer directory called 'abi' and (if found) assumes it to be the
AbiWord sources. Otherwise, or to override this selection, use the --with-abiword=<dir>
option to configure to specify the real location (dir) of the AbiWord sources.
An installation directory is required as well. Plugins are now installed in
$(libdir)/AbiWord-2.0/plugins and either --prefix=<dir> or --libdir=<dir> can be specified to
configure. (Note: This needs to match the value of $(prefix)/lib or $(libdir) specified
when building AbiWord.)
By default, AbiWord searches for plugins in $(libdir)/AbiWord-2.0/plugins and in
$HOME/.AbiSuite/AbiWord-2.0/plugins (this has changed since the 1.1.3 alpha release).
NOTE: Enabling & Disabling Plugins
In addition to --enable-all/--disable-all and --enable-<plugin>/--disable-<plugin>,
plugins can also be enabled/disabled using --with-<plugin>/--without-<plugin>,
and in fact the with/without method has precedence, principally to allow easier custom
configuration via RPM spec scripts.
NOTE: Built-In Plugins
If, for whatever reason, you want to build AbiWord and link the plugins statically
then you need to build the plugins first, configuring as follows:
./configure --disable-shared --with-builtin-plugins [etc.]
then "make" but *not* "make install". You must "configure --with-builtin-plugins ..."
in abi; abi's configure, unless you specify which plugins you want, will auto-detect
plugins by searching for (static) libAbi*.a plugins.
===========================
3. The nextgen.sh Build System
===========================
-----------------
Developer's notes
-----------------
The recommended build method for UNIX et al. is to use the GNU development utilities autoconf,
automake and libtool, since building modules is tricky business and nothing does it better
(i.e., more portably) than libtool - which is not to say that libtool is without problems,
since even CVS libtool has problems with darwin (most of them zsh-related) and no doubt there
are issues on some other operating systems...
abiword-plugins/nextgen.sh is a script which (a) detects plugins, and (b) creates the umbrella
build system. This makes it easy to add new plugins.
a. Plugin Detection
Any subdirectory of abiword-plugins which contains a file called 'plugin.m4' is treated
as a plugin source directory. This file sets a number of variables that influence the
behaviours of both abiword-plugins/nextgen.sh and abiword-plugins/configure.
plugin.m4 has the following structure. At the top is a sequence of lines starting with
"dnl= ". This serves a dual purpose. autoconf/m4 will treat the "dnl" as a comment
indicator and will ignore the line. /bin/sh will treat the "dnl= " as an environment
variable statement, and will parse the rest of the line properly. This is necessary
because both nextgen.sh and autoconf use plugin.m4.
This variables set in the header for nextgen.sh are:
abi_plugin_macro
The name of an autoconf/m4 macro defined later in the plugin.m4 that configure should
use for plugin configuration.
abi_plugin_files
A list of files, relative to the plugin directory, that configure should create.
Typically this would be: abi_plugin_files="GNUmakefile xp/GNUmakefile".
abi_plugin_desc
A short, one-line description of the plugin.
abi_plugin_enable
A simple "yes" or "no" indicating whether the plugin should be enabled by default.
[I'm not convinced this works - fjf]
The final shell statement in the header must be:
dnl= return
This stops nextgen.sh from looking at the rest of the file, which can contain any
autoconf/m4 macros you care to define.
To disable the plugin, have your macro set abi_plugin_disable=yes
You can add status messages by using the ABI_PLUGIN_REPORT([...]) macro.
Substitutions @ABI_CPPFLAGS@ and @ABI_PLUGIN_DIR@ (the plugin installation directory)
are defined earlier by configure.
b. The Umbrella Build System
abiword-plugins/nextgen.sh will not recurse into directories with a 'plugin.m4'. Instead
it will tag these as plugins, and will construct a GNUmakefile.am tree that reaches all
plugin sources. These GNUmakefile.am files consist of a single SUBDIRS rule, e.g.:
SUBDIRS = OpenWriter bz2abw graphics
In this example, the first two are plugins and the 3rd is a subdirectory containing
further plugins (AbiGdkPixbuf and magick). abiword-plugins/nextgen.sh will therefore
create a GNUmakefile.am in graphics but not in OpenWriter or bz2abw.
NOTE: The use of 'GNUmakefile' presumes the use of GNU make.
NOTE: There is a bug in automake-1.5 which causes problems when using 'GNUmakefile'.
Either use an earlier version of automake or add the following at line 16 of
$prefix/share/aclocal/depout.m4:
GNUmakefile) dirpart=.;;
*/GNUmakefile) dirpart=`echo "$mf" | sed -e 's|/[^/]*$||'`;;
Once the GNUmakefile.am tree is constrcuted, abiword-plugins/nextgen.sh creates
abiword-plugins/configure.{in,ac}, runs libtoolize, aclocal, automake and autoconf.
17th September, 2002
Francis James Franklin <fjf@alinameridon.com>