AbiWord Build Instructions

AbiWord is a C++ application which has a cross-platform architecture consisting of a large platform-independent core and a number of front-ends which use the native GUI of each of the platforms it supports. As a consequence of this, there are a number of different build systems used by AbiWord and a large number of build options. This document gives an introductory guide to building AbiWord and attempts to cover these various build options. However, the build changes often and inevitably there will be discrepancies between this guide and the reality of building AbiWord. If you find any errors or omissions, don't be afraid to ask about them on the mailing lists, or to file bugs at http://bugzilla.abisource.com/.

Contents

	Unix
	Windows
	QNX
	Mac OS X

Unix:


Prerequisites:

The principal build system on Unix systems (including Linux, Solaris, etc.) is based on the GNU automake tool. To compile and build AbiWord, you will need:
	A reasonably working C and C++ compiler (GNU's gcc and g++ come to mind, though others should work as well)
	GNU's make (called gmake sometimes); see Notes on using non-GNU make below.
	A Bourne compatible shell, such as sh, bash, zsh, ksh...

GTK+-2.0

AbiWord-2.4's Unix GUI is GTK+-2.2 based, which means that AbiWord on Unix does its drawing using the excellent GTK+ and GDK graphical tools. Therefore you will need GTK+-2.2 or 2.4 and its prerequisites installed, and their ancillary development packages. A list of the required packages and the packages themselves can be found at http://www.gtk.org/. Alternately, your OS provider might have pre-built packages for you, or they might be available from some trusted third party (collectively referred to as a "distribution") . We always recommend going with the tools your distribution provides, but you are in no means required to do so.

zlib

AbiWord also requires zlib. Zlib is usually installed on every machine under the sun, even those sold by SunTM. But, if for some reason you don't have it or you just want to get it anyway, http://www.gzip.org/zlib/ is the place for you. See also: configure --with-zlib

libpng

AbiWord also requires libpng. Like zlib, libpng is installed on most machines already. However, you may get the latest and greatest libpng here: http://www.libpng.org/pub/png/. See also: configure --with-libpng

iconv

AbiWord also requires a working iconv implementation. Note, that thing that ships on your Solaris 8, HP/UX, or AIX box isn't considered "working." AbiWord requires GNU libiconv 1.8 or later to be installed. Most every Linux box and some BSD boxen should be in the clear here, as the standard C library ships with an equivalent version of this package. If you're not on Linux or BSD, get libiconv here: http://www.gnu.org/software/libiconv/. See also: configure --with-libiconv

fribidi

AbiWord also requires the Fribidi library, version 0.10.4 or higher, which is available at http://sourceforge.net/projects/fribidi/. (Note: Do not use the fribidi in AbiWord's CVS since that is for Windows only!) See also: configure --with-fribidi

expat/libxml2

AbiWord also requires an XML parser in order to work. Don't be too worried about what that means - your system probably already has a working one installed. If you're in doubt, you can go grab expat (http://sourceforge.net/projects/expat/) or (preferably) libxml2 (http://xmlsoft.org/) or you can also get expat from AbiWord's CVS (cvs co expat). See also: configure --with-expat and configure --with-libxml2

popt

AbiWord also requires a little library called POPT to parse through command line arguments. POPT is probably installed on your Linux box, but if not, or if you are on most BSD or many  Solaris or something else entirely that doesn't have it, you can get it here (http://developer.gnome.org/arch/misc/popt.html) or you can also get popt from AbiWord's CVS (cvs co popt). See also: configure --with-popt

aspell/pspell

AbiWord can optionally take advantage of the Aspell/Pspell spell checkers. Get them at http://aspell.net/ if you're so inclined. A lot of newer distributions ship aspell/pspell. Don't worry if you don't get this, AbiWord will fall back to using its built-in ispell spell checker. Dictionaries for our ispell checker can be found at http://www.abisource.com/download/abispell.phtml. See also: configure --with-pspell

enchant

enchant is a new wrapper library that provides a tidy, single interface around the various dictionary libraries available, such as aspell, ispell, uspsell, myspell,... See description of enchant at http://www.abisource.com/enchant/. AbiWord will use the enchant library if it finds it.

Xft2/fontconfig

AbiWord takes advantage of the Xft2/FontConfig X11 font extensions. Your copy of AbiWord will look so pretty that you'll be the envy of all of your friends, peers, and coworkers. Get these at http://www.fontconfig.org/.

perl

AbiWord can be scripted (controlled and added onto via extensions) via a PERL interface if you so wish. PERL is available from http://www.perl.org/. See also: configure --enable-scripting

Getting the source:

Well, if you're here, you've probably downloaded the latest and greatest AbiWord sources. If not, you can always get the latest AbiWord source and binary packages from http://sourceforge.net/projects/abiword/. If you're more of the CVS type, you can find CVS instructions for checking out AbiWord here: http://www.abisource.com/developers/download.phtml.
If you have the big-bad source tar-ball, you can skip to the next section. If you're getting the source from CVS and are on Unix, here's what you need to cvs checkout:
	abi (Absolutely vital)
	abidistfiles (needed if you plan to make install)
	wv (highly recommended) Note: you can also get wv release tar-balls from wvWare's official site on SourceForge, http://sourceforge.net/projects/wvware/. For building AbiWord, however, the version of wv can be critical and so it is usually bundled with abi; for CVS AbiWord use AbiWord's CVS wv (use cvs co -r wv-1-0-0-STABLE wv). See also: configure --with-sys-wv.
	abiword-plugins (optional, for extra importer/exporters, nifty tools, and other toys)
And, if you don't have these already:
	libjpeg (optional but recommended)
	popt (if you don't have it)
	libpng (not optional but on most systems already)
	zlib (not optional but on most systems already)
	expat (either this or libxml2 is required, both can be found elsewhere)
	libiconv (if you have a missing or broken implementation)
	psiconv (if you want to build the psion importer plugin)


Configuring what you want built:

Because AbiWord uses the automake/autoconf build tools, you may already be familiar with this step and some of its more-common behaviors, quirks, and options.
If you enter the "abi" directory, you'll find a little (big) shell script there named "configure." This program will help you determine what features get built into AbiWord. If you're in a rush, uninterested, or clueless, you might just try:
	./configure
	make
	make install
which is also known as the "standard unix build practice." If you do this, more power to you. If you're interested in what you can play with, however, read on.
Common build options:
	--prefix=/some/path will let you put AbiWord in a particular directory. /usr is a common value, /usr/local is the default.
	--disable-shared will disable building a dynamically linked version of AbiWord. This means that AbiWord will be statically-linked with libgtk2.a, libglib2.a, ... if these exist. See --enable-static below.
	--enable-static will build a statically linked version of AbiWord. This means that your resulting binary will be huge, and have all of its dependencies (gtk2, glib2, etc.) included in it.  Beware that many operating environments don't include the static versions of most of abi's dependencies, which are required to link statically.
	--enable-debug will include useful messages and special symbols if you're a developer. If you're an ordinary user, steer clear of this option. It won't suit your palette.  It definitely increases the size of the resulting binary.
	--enable-scripting will enable you to script AbiWord using PERL. This is a cool feature if you have PERL installed, so I recommend trying it out.
	--with-XXX where XXX is the name of some resource/library. Options for these include "yes", "no", and a path to XXX's installation directory. So one could do:
	./configure --with-pspell=no [don't use pspell; same as --without-pspell]
	./configure --with-pspell=yes [use pspell, let configure try to find where it is installed; same as --with-pspell]
	./configure --with-pspell=/path/to/pspell [use pspell, but use the pspell found under that path] 
As always, ./configure --help will help shed some more light on these, and show you some more options that I'm intentionally excluding here. In most cases, configure will do what you want. It will find all of the dependencies and create a nice build environment for the AbiWord project. Running configure without any arguments is probably a good thing to do on most Linux and BSD systems. Solaris, HP/UX, and AIX people will probably have to pass a few of the "--with" options to configure in order to get a working AbiWord.
After running configure (assuming that configure worked and didn't spout any nasty messages at you), type 'make' and go grab a cup of coffee. AbiWord can build in about 8 minutes on a P4 1800. Your build times will vary depending on your configuration options, how good your machine is, what load your machine is under, ... as usual, multi-processor machines can use the jobserver (-j) mode.
When the 'make' part of this process is finished, you will want to install AbiWord. You can achieve this through typing 'make install' - this part may require you to be superuser (root), depending on your permissions and where you chose as your prefix (the default, /usr/local, usually requires superuser permission). You can do this through typing 'su' or 'sudo'. Please consult your manual pages or local system(s) administrator if you have questions.

NOTES FOR SOLARIS USERS:

If using the deprecated "diving make" build system, it may be necessary to suppress the static build ("make UNIX_CAN_BUILD_STATIC=0") and also, if the wv library is to be made correctly, to set "CC=gcc" and "export CC"  even though the path is set to /usr/local/bin:$PATH. Please see bug 4200.

NOTES ON USING NON-GNU MAKE:

Some incarnations of 'make', even though they are not GNU's, understand (or have an option to understand) GNU's syntax.  This will work fine, if it either can be told to use GNUmakefile (as the makefile input), or (if it looks for Makefile) from wherever you've run configure do:
for d in `find -name GNUmakefile | tr -d "GNUmakefile"`; do mv -f $d/GNUmakefile $d/Makefile; done
This will change all files in that directory and its subdirectories named GNUmakefile to Makefile, overwriting any files named Makefile that are in the way.  (Note: If you do this in abi/, and later want to try the diving make build system, you must re-extract the Makefiles or first move them to a safe place.)

Windows:


There are 4 different ways to build AbiWord on Windows:

	1.	Using the so-called "diving make" build system using MSYS and MINGW (used
		for our releases at the moment)
	2.	Using the so-called "diving make" build system using Microsoft Visual C++ 5.0
		or greater and the cygwin unix shell layer
	3.	Using Microsoft Visual C++ 6 or 7.1 project files
	4.	Using the autoconf style build system using MSYS and MINGW

Do get anything done, we first need to get the source code. 

Getting the source (this does NOT apply to the autoconf build system; If you intend to use this, skip immediately to section 4)
There are two methods for getting the AbiWord source code; source tar.gz files and CVS.

The source tar.gz files are packaged for building AbiWord.  You can find the latest version of the tar.gz on http://www.abisource.com/download/.  They will be typically labelled abiword-<version>.tar.gz.  Once download you can use WinZip or command line tools from MSYS or cygwin to unpackage the file and install the abiword sources locally to your hard disk.  The command line to unpackage the file from MSYS or cygwin is "tar xvfz abiword-*.tar.gz".

Concurrent Versions Systems (CVS) is used by the developers to maintain the source files of the project.  Information on CVS can be located at there web site http://www.cvshome.org/.  An excellent Window GUI for CVS is WinCVS and can be located at http://www.wincvs.org/, with links to other great CVS tools; alternately, you can download and install the MSYS DTK which includes a CVS client.

For AbiWord, the CVSROOT environment variable should be:
 :pserver:anoncvs@cvs.abisource.com:/cvsroot
The password for the anoncvs user is anoncvs.

From the command line version of CVS, a user would: 

	cd c:\existing_dir_for_cvs_download
	set CVSROOT=:pserver:anoncvs@cvs.abisource.com:/cvsroot
	set HOME=c:\existing_dir_for_.cvspass_file
	set HOMEDRIVE=c:\
	set HOMEPATH=\existing_dir_for_.cvspass_file
	cvs login
	cvs checkout <modules listed below>

CVS modules required to check out are:

	abi
	abidistfiles (only needed for make canonical and make distribution)
	expat
	fribidi
	libiconv
	libpng
	popt
	wv (use cvs co -r wv-1-0-0-STABLE wv)

The following modules may optionally be checked out as well:

	MSVC6	(if attempting to use MSVC project files)
	MSVC71	(like the above, but for Visual Studio .Net and later)

You will need the "zlib" library to build AbiWord.  The zlib "compiled DLL" version can be found at http://www.gzip.org/zlib/.  Extract the complete archive (i.e. headers, library files, and the compiled dll) to a peer directory named 'libs\zlib\'.

Note: As of the time of writing (Oct 2005), if you are using the Microsoft Visual C++ project files, you need to follow a slightly different procedure than that described above. Instead of obtaining zlib from http://www.gzip.org you need to check out the module "zlib" from CVS along with the modules listed above. You also need to check out the "psiconv" modules.

WARNING: The version of zlib on the CVS server is not as up to date as the version provided by www.gzip.org. As such, it almost certainly contains security vulnerabilities.

To build the distribution installer of AbiWord, you will need the latest version of NSIS 2, as well as the md5dll and untgz plugins.  These packages can be found at http://nsis.sourceforge.net/.  Additionally, the command make canonical can be used to build a directory structure useful for testing spellchecking and alternate languages. Install them according to the instructions.  If you do not install NSIS to C:\Program Files\NSIS, you will need to add makensis.exe to your PATH variable.


1.	Diving make using MSYS and MINGW

Prerequisites: MSYS and MinGW free GNU build tools

MSYS and MinGW provide a Windows port of popular GNU building tools and compilers.  MinGW provides the compiler, headers, and libraries to build Window binaries.  Information about it and how to download it can be found at http://www.mingw.org/.  MSYS was developed to provide MinGW an operating shell compliant with various GNU building scripts.  Information on MSYS can be found at http://www.mingw.org/msys.shtml.

Building AbiWord
Start MSYS and change the directory to the location of where you download/installed the AbiWord source:

	cd /path/to/abi

AbiWord uses a diving makefile build system.  Begin the build process by typing 

	make

This will build the AbiWord application and any associated tools and libraries.  The binary will be located in a subdirectory src/WIN32_etc.../bin or src/MINGW32_etc.../bin  To build an installable executable, issue the following command:

	make distribution

A setup_abiword.exe will be built and located in a dist subdirectory, if your NSIS and plugin installs are correctly set up.
Several build options are available and are detailed in the BUILD.txt file.  They are used during the build by replacing the make command above with:

	make option1 option2

The following are common for the Windows build:

ABI_BUILD_VERSION=x.y.z  	Set the version number for the build
ABI_OPT_DEBUG=1  		Builds a debug version of AbiWord
ABI_OPT_PERL=1			Enables Perl scripting
ABI_OPT_LIBJPEG=1		Enables you to view JPEG images
ABI_OPT_CURL=1			Enables automatic dictionary downloading


2.	Diving make using MSYS and MINGW


Prerequisites: Microsoft Visual C++ 5.0 or greater and the cygwin unix shell layer

For builders/developers with Microsoft Visual C++ (MSVC) compilers, there are two methods for building AbiWord;  command line with cygwin tools (intermittently maintained, and may not work) or the Microsoft Developer Project files (actively maintained, and will work).  MSVC 5 building is not actively done and will minimally require an updated Win32 platform SDK.
Building via MSVC command line using cygwin tools is the traditional method for building AbiWord and is used for the release builds.  You can find information about the cygwin tools at http://www.cygwin.com/.  Beyond the packages in the Base category during the Cygwin installation, only the "libintl1", "libiconv2" and "make" packages are required to build AbiWord.  The exact programs required are: cp, cut, echo, expr, make, mkdir, pwd, rm, sed, sh (bash), tar, uname, along with cygwin specific cygpath.exe and cygwin1.dll.  To obtain the source you may also want the cvs client.

Building AbiWord
Start the sygwin command/cmd shell.  Run VCVARS32.BAT which sets appropriate environment variables pointing paths, includes, libs that come with MSVC.  You will find this batch function typically in the bin directory under VC98.  Once these environment variables are set, from the same shell, launch cygwin.  Typically this is done via a cygwin.bat batch file located where you installed cygwin.

Change directory to the location of where you download/installed the AbiWord source. You will need to change directory to the full path where the AbiWord source is located using the /cygdrive folder.  For example, if your AbiWord source is in the /usr/src/abi directory of your Cygwin installation and Cygwin is installed in C:\cygwin, you will need to change directory to:

	cd /cygdrive/c/cygwin/usr/src/abi

AbiWord uses a diving makefile build system.  Begin the build process by typing 

	make

This will build the AbiWord application and any associated tools and libraries.  The binary will be located in a subdirectory src/WIN32_etc.../bin or src/MINGW32_etc.../bin  To build an installable executable, issue the following command:

	make distribution

A setup_abiword.exe will be built and located in a dist subdirectory, if your NSIS and plugin installs are correctly set up.
Several build options are available and are detailed in the BUILD.txt file.  They are used during the build by replacing the make command above with:

	make option1 option2

The following are common for the Windows build:

ABI_BUILD_VERSION=x.y.z  	Set the version number for the build
ABI_OPT_DEBUG=1  		Builds a debug version of AbiWord
ABI_OPT_PERL=1			Enables Perl scripting
ABI_OPT_LIBJPEG=1		Enables you to view JPEG images
ABI_OPT_CURL=1			Enables automatic dictionary downloading


3.	Using Microsoft Visual C++ 6 or 7.1 project files

The third method is to try the MSVC6 or MSVC7.1 project files that have been generated.  These project files are actively maintained and are only available for MSVC 6.0 and 7.1.  See the "Getting the sources" section below to use CVS to download the latest versions of these project files.

Building AbiWord
If attempting to use the MSVC project files, follow the instructions in the README.TXT file located in the directory holding the project files.


4.	Using the autoconf style build system using MSYS and MINGW

We assume that you have a 'recent' mingw and msys installed, including a recent w32api. Furthermore we assume you are installing all software in the /home/foobar/local prefix. Make sure to change this to match your setup.

1. Prerequisites:
	   pkgconfig, libiconv, gettext and glib

     Download and install the binaries and developer files from
     http://www.gimp.org/~tml/gimp/win32/downloads.html

	   popt

     Download and install the binaries and developer files from
     http://gnuwin32.sourceforge.net/packages/popt.htm

2. Start msys, and set up your environment by executing:

	export PKG_CONFIG_PATH=/home/foobar/local/lib/pkgconfig/
	export PATH=/home/foobar/local/bin:$PATH

3. We will compile the rest of the AbiWord dependencies ourselves. Feel free to use precompiled libraries, but we can't guarantee their correct functioning.

	fribidi (download the source tarball from http://fribidi.org/)

	NOTE: You'll need to patch the fribidi sources first if you are using version 0.10.4 or 0.10.5. To do this, open the file fribidi_benchmark.c, and simply remove the line 	"#include <sys/times.h>", around line 31. Next, replace the contents of the function utime (void) around line 91 with the single line: return 0; (we don't need it anyway).

     To build fribidi, execute the following commands (where x.y.z is the fribidi version number):

	cd fribidi-x.y.z
	./configure --prefix=/home/foobar/local
	make
	make install

	 zlib (download the source tarball from http://www.zlib.net/)

     To build zlib, execute the following commands (where x.y.z is the zlib version number):

	cd zlib-x.y.z
 	./configure --prefix=/home/foobar/local
	make
	make install

	   libpng (download the autoconf enabled tarball from http://libpng.sourceforge.net/)

     To build libpng, execute the following commands (where x.y.z is the libpng version number):

	cd libpng-x.y.z-config
	./autogen.sh
	./configure --prefix=/home/foobar/local CFLAGS="-I/home/foobar/local/include" LDFLAGS="-L/home/foobar/local/lib" 
	make
	make install

	   libxml2 (download the source tarball from http://xmlsoft.org/)

     To build libxml2, execute the following commands (where x.y.z is the libxml2 version number):

	./configure --without-ftp --without-http --prefix=/home/foobar/local/
	make
	make install

	libgsf (download the source tarball for version >= 1.12.1 from ftp://ftp.gnome.org/pub/gnome/sources/libgsf/)

     To build libgsf, execute the following commands (where x.y.z is the libgsf version number):

	cd libgsf-x.y.z
	./configure --prefix=/home/foobar/local/ --with-zlib=/home/foobar/local/
	make
	make install	

	   wvWare (shipped with the AbiWord source distribution)

	NOTE: at the moment you'll need the not-yet released wvWare >= 1.1.0, which is available in AbiWord's cvs.

	To build wvWare, execute the following commands (where x.y.z is the AbiWord version number):

     cd abiword-x.y.z/wv
     ./autogen.sh
     ./configure --with-png=/home/foobar/local --with-zlib=/home/foobar/local --prefix=/home/foobar/local
     make
     make install

4. To build AbiWord, execute the following commands (where x.y.z is the AbiWord version number):

	cd abiword-x.y.z/abi
	./autogen.sh
	./configure --with-sys-wv --with-libxml2 --with-zlib=/home/foobar/local --prefix=/home/foobar/local
	make

NOTE: "make install" doesn't work yet; instead just place the AbiWord-2.x binary that can be found in ./src/wp/main/win together with the glib, libgsf, libiconv, popt, libintl and libxml2 dll's in a directory of your liking. That should work just fine for now.


QNX:


Prerequisites: 

(See also: Windows and Unix requirements for more information)
	abi
	abidistfiles
	wv (use cvs co -r wv-1-0-0-STABLE wv)
You also need to have libpng, libiconv, libfribidi and libxml2. All except libfribidi are available from the QNX 3rd party CD. FriBiDi can be downloaded from http://www.qnxzone.com/~travis/packages/fribidi_x86-0.10.4-x86-public.qpr
Building on QNX is similar to the other unix-like platforms.  We rely on the command line utilities bash, sed, gawk, etc.  
There are 2 ways to build and run AbiWord:
	Developer Style:  just cd to abi and type 'make'.  To run AbiWord, cd to the bin directory and type 'AbiWord -lib ../AbiSuite' -- this will help AbiWord find the dictionary and other support files.
	End-User Style:  just cd to abi and type 'make distribution ABI_BUILD_VERSION=x.y.z' This will build a QNX 'Repository in a File' (src/pkg/qnx/abiword-x.y.z.qpr). Install this with 'pkg-installer -u abiword-x.y.z.qpr'.

Mac OS X:


X11 AbiWord

The official build method on Mac OS X is to use Project Builder to build the Cocoa front end. However, it is possible also to build for X11 - see the section on building for Unix. Note: You will need to specify --disable-Cocoa to configure. Apple's X11.app and X11 SDK betas are one source of X11, unfortunately based on XFree86 4.2 and lacking fontconfig/Xft2 - hopefully Apple will get its act together. XDarwin may be a better choice until then. fink (http://fink.sourceforge.net/) provides most of the packages needed by AbiWord.

Prerequisites (Cocoa):

Currently fink (http://fink.sourceforge.net/), in particular the libiconv and glib2 packages, is required in order to build the Cocoa port. Other dependencies are covered by modules in AbiWord's CVS. To get the source do:
	cvs -d:pserver:anoncvs@anoncvs.abisource.com:/cvsroot login
	CVS password:	(anoncvs)
	cvs -d:pserver:anoncvs@anoncvs.abisource.com:/cvsroot -z3 co abicocoa
This will check out a number of modules, including several which end in "pbx" - these contain the Project Builder files.
