
Build Instructions -- Linux, Solaris, AIX, ...
----------------------------------------------

The Linux tree should build easily assuming that you have all the tools
properly installed.  You'll need gcc, make, and all the tools which usually
accompany them.

For AIX, please see the notes below.

You'll also need GTK version 1.2.7 or later.

Building the tree is a pretty simple process.  We use a "diving make" system,
where virtually every directory in the tree hierarchy has its own Makefile,
which contains the instructions for how to build the contents of that directory.

If you are building on Slackware with libc5 (or any platform without iconv
installed on it) using the diving make system, run 'make ABI_REQUIRE_PEER_ICONV=1' 
as your make line.

There are several ways to build and run AbiWord:

[1] Developer Style:  just cd into the abi directory and type 'make'
    and then 'make install'.  This will install the AbiSuite support
    files and create abiword and AbiWord symlinks in /usr/bin or
    /usr/local/bin to the executable.  This is a short-cut to creating
    a normal package and installing it.

[2] End-User Style:  just cd into the abi directory and type
    'make distribution ABI_BUILD_VERSION=x.y.z ABI_DIST_TARGET=<fmt>'
    where <fmt> is one or more of 'tgz', 'rpm', 'deb', 'slp', 'pkg', 'depot'.
    This will create one or more archive files in abi/dist.  These
    may then be installed in the normal manner.

    AbiWord's Default RPM
    ---------------------

    make distribution ABI_BUILD_VERSION=x.y.z ABI_RELEASE_NUMBER=n \
                      ABI_DIST_TARGET=rpm OUT=<dir> \
                      ABI_BUILD_PACKAGER="You <email@of.yourse.lf>"

    The OUT=<dir> is important, since the default value is 'src' which means
    that all the object files are placed in the abi/src tree - which you *don't*
    want. It is best to use an abosulte path to an existing directory (<dir>)
    outside of any of the AbiWord modules, e.g. OUT=/tmp

    AbiWord Plugin RPMs
    -------------------

    Plugins sometimes have awkward dependencies so not all of them are built
    by default by 'make distribution [OPTIONS]'. If you wish to change which
    plugins are built, then you will need to edit the RPM spec *template*:

    abi/src/pkg/linux/rpm/abiword.spec-template

    lines 13- have plugin build option settings ('0' or '1').

    If you are building from CVS, you will need to run autogen.sh in
    abiword-plugins in order to create the build system.

    AIX platform Notes
    ------------------

    You need the current GNU versions of some programs instead of AIX's
    ones : make, m4, ...

    You also need some program not available with AIX: bash, automake ...
    Have a look here :
      http://www.bull.de/pub/
      http://freeware.bull.net/
    
    Build it using the autoconf build system:

    $ cd .../abiword/abi

    $ alias make=/usr/local/bin/make
    $ alias m4=/usr/local/bin/m4

    $ export CPPFLAGS="-D_ALL_SOURCE -D_BSD"
    $ export LDFLAGS="-Wl,-bbigtoc"
    $ export CC=gcc

    $ bash ./autogen.sh   ( maybe 2 times )
    $ bash ./configure

    $ make
    # make install


Build Instructions -- Windows NT
--------------------------------

Building on Windows NT is remarkably similar to building on Linux.  We
use the same set of Makefiles on Linux as well as NT.  You'll need to
get the CygWin32 tool set from Cygnus before you can build.  See
http://www.cygnus.com/misc/gnu-win32/ for information and downloads.
The file you need should be called cdk.exe on B19 and full.exe on B20.1,
and it's going to be around 14 megabytes.  [This file is on the CD.]
Installing this stuff on your NT machine will create an environment
which looks remarkably like a UNIX box.  You'll get a standard bash
shell, GNU make, and all the standard UNIX utilities like sed, gawk,
cp, ls, mv, and so on.  This environment is the key which allows us
to use the same set of Makefiles for both NT and Linux.

Just in case you're wondering, yes, it should be possible to build
this tree with a subset of the tools.  There's 14 meg of stuff there,
and we don't *really* need all of it.  However, we haven't had time or
motivation to identify the specific set of apps we need.  Disk space
is cheap.  If you decide to make the effort to do so, please let us
know, and we'll share that information with other developers.

You also need Visual C++ 5.0.  Obviously, we don't use the IDE at all,
but we do use the compiler, headers, libraries, and so on.  You'll
need them all to be in your PATH, since the Makefiles will expect them
to be readily available.

Additionally, AbiWord uses the PNG and zlib libraries.  Both of these are 
available from our website [and included on the CD], and are peers of the
abi tree.  Once you have all this stuff downloaded, AbiWord should build
just fine.  The main AbiWord makefile will take care of building everything.

There are 2 ways to build and run AbiWord:

[1] 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.

[2] End-User Style:  just cd to abi and type 'make distribution ABI_BUILD_VERSION=x.y.z'
    This will build a setup program (abi/dist/setup.exe).  If you then run the
    setup program it will do a normal Win32 installation and create desktop
    icons and start menu items.

Build Instructions -- QNX
--------------------------

Building on QNX is similar to the other unix like platforms.  We rely on 
the command line utilities for bash, sed, gawk, etc.  

There are 2 ways to build and run AbiWord:

[1] 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.

[2] 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/build/qnx/abiword-x.y.z.qpr).
		Install this with 'pkg-installer -u abiword-x.y.z.qpr'.

Components that you will need to checkout from CVS, or have installed, are:
	abi 
		You wouldn't be reading this if you didn't have this checked out
	abidistfiles
		This contains the basic spelling libraries and is needed for building
		a distribution (ie [2])
	wv
		This contains the Word converter library
	expat
		This contains the XML parser library
	zlib
		This is used for compression
	libpng
		This is used for AbiWord's internal graphics representation
	libiconv
		This is used for internationalization and character support
	psiconv
		This is used for the Psion importer.
	

Build Instructions -- BeOS
--------------------------

Building on BeOS is similar to the other platforms.  We rely on the
GNU command line utilities for 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:

[1] 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.

[2] 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.


Build Instructions -- MacOS
---------------------------

This will build a PowerPC version of AbiWord. Currently 68k is not supported.

You will need to get:
-zlib
-libpng
-libiconv

Two different solutions:

[1] using Metrowerks CodeWarrior. Open the project in src/config/platform/macos.mcp (or 
macos.xml if you don't have version 6.0 of CodeWarrior).

[2] using MPW. Start MPW shell, go to the abi directory and execute the script mpw-build.
It will work with MPW 3.5 GM. Currently Metrowerks MPW compilers are not supported.


Build Instructions -- darwin: MacOS X | XDarwin
-----------------------------------------------

There are three ways to build AbiWord for MacOS X:

(1) The 1st native port, which uses the Cocoa API to provide a delicious
    Aqua interface. No Mac enthusiast should put up with anything less.

(2) The 2nd native port, which uses the Carbon API.

(3) The UNIX build. Although this lacks the silky, sexy finish of the
    native port, it has the undeniable advantage that it works. If your
    X server is set up rootless then the burden of interface is light.

Whichever you're building, or trying to, here are a few guidelines:

(a) There are two options to build Abiword - with make, or with
    configure then make. Use the latter. The former is no longer the
    recommended process for MacOS X (none of the developers use it with
    MacOS X, so you'd be on your own).

(b) If building from CVS:
    MacOS X ships with autoconf (2.13). You will also need automake.

    * * * WARNING * * *

    Don't use automake-1.5, cos it don't work. Any of the automake-1.4
    releases, or automake-1.5d and up, should be fine.

(c) It's probably safe to ignore this next bit of advice, but come back
    to it if you experience mysterious problems...

    Learn to be very paranoid about /bin/sh. Paranoia can be healthy.
    darwin ships with a /bin/sh which is zsh, which behaves like sh
    99.99% of the time - it is, of course, the other 0.01% that causes
    problems.

    I strongly recommend that you install bash. Rumour has it that even
    Apple wants to use bash. The compile options are a little
    intimidating, I know, but I never do it the same way twice and I've
    never had any problems. Put your faith in GNU...

    Once you've got bash installed, in for example /oss/bin/bash, add
    the following lines to your .bashrc:

	export SHELL=/oss/bin/bash
	export CONFIG_SHELL=/oss/bin/bash

    (replacing /oss/bin/bash with whatever path you've used) and start
    bash.

    When running build scripts like autogen.sh or configure, use bash
    explicitly:

	[ENVIRONMENT] /oss/bin/bash autogen.sh
	[ENVIRONMENT] /oss/bin/bash configure [OPTIONS]

    Note to experts: if the configure script has been created with
    autoconf >= 2.50, it may be worth adding SHELL=/oss/bin/bash to
    [ENVIRONMENT], e.g.:

	/oss/bin/bash configure SHELL=/oss/bin/bash ...

    If you think you know better than Apple (which, let's face it, in
    this instance you probably do) you can save yourself all of this
    stuff and bother by replacing /bin/sh with bash - just don't expect
    any sympathy from me if Software Update complains about it.

(d) Next, and no one said this was going to be easy, there are a few
    libraries you will need to install before you start on AbiWord.

    If you prefer, you can get them precompiled, either via fink or
    GNU-Darwin or MacOSX-forked.net or one of their cousins. (There's
    a new one every day.) If you're only interested in AbiWord, then
    fjf's Crazy Wormhole collection may be better:

	http://www.crazy-wormhole.com/

    WARNING: Use Crazy Wormhole *only* if you plan to make a bundle.

    Most recent releases of libraries are darwin-friendly, though there
    are exceptions. Adding -no-cpp-precomp to CPPFLAGS solves a few
    problems here and there.

    You require libpng and libiconv, and it's best to get the latest
    releases. An optional extra is libjpeg. For the XDarwin build you
    require gettext, glib and gtk+ as well.

    You will also need either expat or libxml2. (I think there's a
    version of expat burrowed deep inside the MacOS X frameworks, but I
    don't know how to use it.) expat gets distributed with AbiWord, but
    I [fjf] prefer libxml2 because it has HTML support (even if AbiWord
    can't quite use it yet). libxml2 is released frequently; make sure
    to get a recent release.

	libpng		http://www.libpng.org/pub/png/libpng.html
	libiconv	ftp://ftp.gnu.org/pub/gnu/libiconv/
	gettext		ftp://ftp.gnu.org/pub/gnu/gettext/
	glib & gtk+	http://www.gtk.org/
	expat		http://sourceforge.net/projects/expat
	libxml2		ftp://ftp.gnome.org/pub/GNOME/stable/sources/libxml/

Building AbiWord

If you are building from CVS, you must first run autogen.sh:

	./autogen.sh

or, if you are taking my paranoid advice from (c) above:

	/oss/bin/bash autogen.sh

Then, or otherwise, run configure. To build for Cocoa & Aqua:

	./configure --prefix=/Users/me/wherever

or '/oss/bin/bash configure etc.'. To build for Carbon & Aqua:

	./configure --disable-Cocoa --prefix=/Users/me/wherever

or '/oss/bin/bash configure etc.'. To build for XDarwin:

	./configure --disable-Cocoa --disable-Carbon --prefix=/Users/me/wherever

and similarly. Depending on where you installed the various libraries,
you will probably need to add these to the search paths:

	./configure CPPFLAGS="-I/Users/me/wherever/include" LDFLAGS="-L/Users/me/wherever/lib"

and so on and so forth. It looks horribly messy, but it's not so bad once
you get to know it. Kinda like mature cheddar. Or mature whisky, if you
prefer. [Stop being silly. - Ed.]

Finally, or almost so, and you thought we'd never get there, type

	make

(or 'make SHELL=/oss/bin/bash'), sit back with a wedge and a dram, and
contemplate with pleasure the owning of a Mac.

On successful completion of the make process (it has been known), finish
with:

	make install

If you're building for XDarwin, and you don't want to build a bundle,
then you're done. Enjoy!

=======================================================================================
FAQ
=======================================================================================

Where is the executable?
------------------------

The AbiWord executable is created in abi/src/$(OS)_$(OS_VERSION)_$(OS_ARCH)_OBJ/bin.
(on my machine this is abi/src/WIN32_4.0_i386_OBJ/bin/AbiWord.exe)  You may use this
copy to run for debugging or experimentation, but you should probably go ahead and
do an install.


Where are the other generated files?
------------------------------------

The object files (.o or .obj) are placed in abi/src/<platform>/obj
The library files (.a, .so, or .lib) are also placed in this directory.
