# $Id: INSTALL.txt,v 1.2 2004/07/15 17:32:19 helge Exp $

UPDATE: the OGo fork of libFoundation can only be build with gstep-make!

libFoundation can be built in two different ways:

1. as a standalone library.
2. as the Foundation library in the GNUstep environment, instead of
gnustep-base.

In both cases you can build the library with support for the Boehm's
garbage collector.

To be able to build libFoundation you need either GCC 2.8.x or EGCS
1.1. Older versions of GCC with the Objective-C patches are
obsolete. You'll also need the GNUmake to compile libFoundation.



Which way to build libFoundation?
=================================

People that don't want to use the library in the GNUstep environment
should build it in the standalone mode. In this mode you're not
required to specify any environment variables in order to make the
library work. In the GNUstep environment you will have to specify the
GNUSTEP_SYSTEM_ROOT in order for the library to find the resource
files it needs.

For example applications like CGI programs that use libFoundation may
want to use the standalone library as they don't have to setup a
special environment.

People that want to use libFoundation as the Foundation library for
GNUstep should build it for the GNUstep environment.

If you need libFoundation in both types of applications you can
configure, compile and install it in both ways. The two versions of
the library install their header files and libraries in different
places and they do not interfere with each other.

IMPORTANT: If you compile libFoundation in the standalone mode be sure
you don't have the gnustep-base headers in the include path or you'll
encounter problems because the compiler will get them instead.



Boehm's garbage collector support
=================================

Starting with 0.9.0, libFoundation supports the Boehm's garbage
collector. You must have the Boehm's garbage collector support
installed before building libFoundation.

Here are the steps you need to do to install the Boehm's garbage
collector:

1. Download the package. The library was tested using the 4.12
version, previous versions may work but they were not tested. The
official site is:

    http://reality.sgi.com/employees/boehm_mti/

Read carefully the Makefile and add the flags specific to your
system. Don't add the -DNO_SIGNALS to the list of flags, as
libFoundation uses signals internally. After you're sure everything is
fine with the makefile, type 'make' followed by 'make test' which
briefly tests the collector.

The next step is to install the collector. The makefile doesn't have
an install target, so copy the gc.h and gc_typed.h files to
/usr/local/include or to whatever location you prefer. Then copy the
gc.a library into /usr/local/lib and rename it to libgc.a. This step
is important, otherwise the configure script in libFoundation and the
test programs you'll write will not work.

2. You need to compile a special version of the compiler which adds
support for the Boehm's collector to the GNU runtime. 

The currently supported compilers are GCC 2.8.1 and EGCS 1.1. The
patches are contained in the libFoundation's distribution. Apply the
appropriate patch for your compiler. Then configure the compiler using

	./configure --enable-objc-gc

Add whatever arguments you might need to the configure. Then compile
the compiler following the instructions in the INSTALL file included
with the compiler.

3. Configure libFoundation to be compiled with Boehm's GC support. To
do this add --with-gc to the specific flags for your system. At this
point you also have to decide in which environment you want to build
libFoundation.

For an impatient user, just type the following if you want to build
the library in the GNUstep environment.

	./configure --with-gnustep --with-gc

Or run the following if you want to build the library as a standalone
library.

	./configure --with-gc

Configuring the library with support for Boehm's garbage collector
does not imply that the built library will be automatically using the
collector. Actually you can build two versions of the library, one
that is garbage collected and another one that uses the normal
reference counting mechanism.

To build the garbage collected library type:

	make gc=yes

To build the normal library type in the OpenStep compatibility mode:

	make

If you're building in the GNUstep environment you may want to add
additional options like debug=yes.



Building libFoundation
======================

If you want to build the library with support for Boehm's garbage
collector, please read the above part first.

1. If you want to build the library in the GNUstep environment, run
the configure script with the --with-gnustep argument, otherwise just
omit it:

   ./configure --with-gnustep

If you need support for Boehm's garbage collector, just add the
--with-gc flag:

   ./configure --with-gnustep --with-gc

If you're building on a NeXTSTEP/OPENSTEP system read the note at the
end of this file.

2. Run `make' to compile the package. If you're building in the
GNUstep environment add any additional options you might need. For
example if you want debugging and/or profile information to be
included in the library:

   make debug=yes [profile=yes]

where [profile=yes] means that profile=yes is an optional
argument. Read the GNUstep's makefile package documentation to find
out more about compiling in the GNUstep environment.

NOTE: In the standalone environment, debug=yes and profile=yes
arguments have no meaning.

To build the garbage collected library add the gc=yes argument to the
list of arguments you pass to make:

   make gc=yes

This works with both the standalone and GNUstep environments.

3. Before you install the library you may want to set up the locales
for your site. To do this go to the Resources/Defaults directory and
modify the NSGlobalDomain.plist file as you wish. This file specifies
the language and the time zone name of your site.

If your language is not included in the supported languages, you can
create a new one using as model one of the existing language files.

The timezones are specified in the Resources/TimeZoneInfo
directory. You should choose as time zone the one that coresponds to
your geo-political region.

4. Type `make install' to install the library, the headers and the
public binaries. Add the debug and profile arguments to the make
process if you want that specific version to be installed:

   make [debug=yes] [profile=yes] [gc=yes] install

5. To try out if the package works fine on your machine, you can run
the tests from the FoundationTestsuite directory. All the tests are
written using the DejaGnu testing framework. So if you don't have
installed the package on your machine you have to install it before
trying out these tests. Before compiling the FoundationTestsuite you
will have to install the ObjCTest package that comes with the
libFoundation's distribution.

The classes that intimately depend on the specific machine are
NSMethodSignature and NSInvocation. If you get crashes when you run
the NSInvocation and NSMethodSignature tests you have to look to the
sources for these classes in the Foundation directory and to the files
dependent on the target machine in config directory.

6. You can remove the object files and binaries using the `make clean'
command. You can also remove all the generated files (the files
generated by configure etc) with `make distclean'.



Notes for NeXTSTEP/OPENSTEP users
=================================

If you're compiling the package on a NeXT system you can compile it to
use with either the GNU or the NeXT Objective-C runtime. You can
specify this by setting the OBJC_RUNTIME variable. For example:

   OBJC_RUNTIME=gnu ./configure

will compile the package using the GNU runtime. Similarly, you can do:

   OBJC_RUNTIME=next ./configure

In the last case you will be able to link the package with code
compiled with the native compiler.

If you don't specify the OBJC_RUNTIME flag the code will be compiled
with the default option for runtime. It is either -fnext-runtime on
NeXT systems or -fgnu-runtime on the other machines.

You can also specify the compiler using the CC variable. The package
has been compiled using the 2.6.3, 2.7.0 and 2.7.2.1 gcc versions,
depending on machine. If you compile the package with other versions
than 2.7.2.1 you will need to adapt yourself the Objective-C patch to
the compiler sources. GCC 2.8.x and EGCS 1.0.x have not been tested.

Compiling the package on NeXT release 3.3 with the native compiler
won't work. The native compiler doesn't support nested functions and
variable arguments macros.

Starting with the 0.9.0 version the NeXTSTEP systems are no longer
supported due to compiler and debugger problems on these systems. If
somebody is willing to send us patches for NeXTSTEP, we'll incorporate
them in the distribution.




! Local variables:
! mode: indented-text
! End:
