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
	BeOS
	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.2'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/.


LibGlade

Libglade is a powerful and easy way to build GTK+ dialogs. AbiWord requires libglade >= 2.0.


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


Prerequisites

	MSYS and MinGW free GNU build tools
or	
	Microsoft Visual C++ 5.0 or greater and cygwin unix shell layer

MSYS/MingW

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.


Microsoft Visual C++

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.

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


Getting the source:

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://sourceforge.net/projects/abiword/.  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

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)

If you wish to use JPEG images in AbiWord, you will need to download and install the libjpeg library.  More information on libjpeg can be found at http://www.ijg.org/. However, building with JPEG support is obsolete, you should instead use the JPEG plugin or one of the other image supporting plugins (e.g., AbiMagick).

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\'.

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.


Building AbiWord:

If using the MSYS/MinGW build system, start MSYS.  NB: It is currently impossible to use MSYS/MinGW along with the 'configure' style build system. To date, it only works with the 'diving make' build system.

If using MSVC with the cygwin system, start a 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:

	cd /path/to/abi

If using MSVC with the cygwin system, 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

If attempting to use the MSVC6 (or later) project files, follow the instructions in its README.TXT file. 


QNX:


Prerequisites: 

(See also: Windows and Unix requirements for more information)

	abi

	abidistfiles

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


BeOS:


Prerequisites:

(See QNX requirements)

Building on BeOS is similar to the other platforms.  We rely on the GNU command line utilities  bash, sed, gawk, etc.  On Intel systems we use GCC and on PPC we use MWCC.

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 distribution zip file (abi/dist/AbiSuite-x.y.z-$(arch).zip). Expand this in /boot/apps.  You can then run /boot/apps/AbiSuite/bin/AbiWord.


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.

