libs-base/INSTALL

1 Introduction
==============

If you are installing this package as part of the GNUstep core packages,
read the file GNUstep-HOWTO for more complete instructions on how to
install the entire GNUstep package (including this library).
GNUstep-HOWTO is located in the gnustep-make package or at
<http://www.gnustep.org>

   There are two Objective-C toolchains available for GNUstep: the
original GNU Objective-C runtime bundled with GCC, and the new
libobjc2 runtime with Objective-C 2.0 features. Due to lack of
Objective-C 2.0 support in GCC, the libobjc2 runtime requires the
use of clang.

   Here is a list of some of the features of the libobjc2 runtime:

 * Modern Objective-C runtime APIs, initially introduced with OS X 10.5.
 * Fast message passing, and caching.
 * Blocks (closures).
 * @property syntax for declaring properties.
 * Efficient support for @synchronized()
 * Type-dependent dispatch, eliminating stack corruption from mismatched selectors.
 * Support for the associated reference APIs introduced with Mac OS X 10.6.
 * Support for the automatic reference counting APIs introduced with Mac OS X 10.7
 * Support for fast-path message dispatch for common methods (e.g. retain, release, autorelease).

   We recommend using the new toolchain when possible.

   This version of gnustep-base requires gnustep-make version 2.0.0 or
higher.

   Other external libraries that you may need to install include:

   * ffi (HIGHLY RECOMMENDED)
   * icu (HIGHLY RECOMMENDED)
   * gnutls (HIGHLY RECOMMENDED)
   * libxml2 (RECOMMENDED)
   * libxslt (OPTIONAL)
   * libavahi (RECOMMENDED for NSNetServices)
   * zlib (RECOMMENDED)
   * iconv (OPTIONAL, not needed if you have glibc)
   * openssl (OPTIONAL, not needed if you have gnutls)
   * libcurl (REQUIRED WHEN USING Objective-C 2.0 TOOLCHAIN)
   * libdispatch (RECOMMENDED)

   If you are installing the GNUstep libraries individually, make sure
you have installed the GNUstep Makefile package (gnustep-make) already,
and you have sourced the makefile script:
     . $GNUSTEP_SYSTEM_ROOT/Library/Makefiles/GNUstep.sh
   See the GNUstep-HOWTO for more information.

   After installing this library you should install gnustep-gui if you
are going to use graphical applications.

   When you configure this library, make sure you use the same
configuration options as with gstep-make.  Some additional options to
configure are described below.

   Quick installation instructions:

     ./configure
     make
     make install

   To make and install the documentation:

     cd Documentation
     make
     make install

2 Configuration
===============

Configuration is performed by running the 'configure' program at a shell
prompt.  You may want to use some of the optional arguments to the
'configure' program.  Type 'configure --help' for a list of these.  It
is not likely that you will need to use the '--prefix' option, since
gstep-base will automatically install in the directory specified by the
'GNUSTEP_SYSTEM_ROOT' environment variable (specified when you installed
gnustep-make).

   Some configuration options for the base library need to be specified
when configuring the gnustep-make package.  In most cases, it is a good
idea to specify the same configuration options when configuring both
packages, just to make sure.

   Also make sure you've read the machine-specific instructions for your
particular operating system and CPU. These instructions come with the
GNUstep-HOWTO and are also located at the GNUstep web site at
<http://www.gnustep.org>.

2.1 Reading Command-Line Arguments
----------------------------------

There are two features that change how GNUstep gets access to
command-line arguments and environment variables (normally passed to the
program in the 'main()' function.  These features are
'--enable-pass-arguments' and the '--enable-fake-main' option(s).

   The fake-main option _secretly_ renames the 'main()' function and
substitutes it's own function which stores the command line arguments
before calling the real main.

   The pass-arguments option absolves GNUstep of any effort to get the
command-line arguments and instead forces the developer to insert the
line

       [NSProcessInfo initializeWithArguments:argv count:argc environment:env];

   in the 'main()' function of their program.

   Normally, the configure script will determine if a program can read
process information directly from the system (for use by the class
NSProcessInfo) and enable or disable the fake-main hack automatically,
but if you find that configure is not doing this correctly, you can
force the fake-main hack to be used, which will always work.  Note that
if the fake-main hack is enabled, you need to include the header file
GSConfig.h in you main program - this is done by default if you include
NSObject.h or Foundation.h.  If you want to avoid the whole idea of the
fake-main hack, you can use the pass-arguments option.  In this case you
will be forced to call the NSProcessInfo initializeWithArguments method
to pass the program arguments to NSProcessInfo (This would be done
automatically if you use the NSApplicationMain function in a gui
application).

2.2 FFI Library
---------------

GNUstep's NSInvocations and Distributed Objects code involves detailed
manipulation of the stack and function calls using a library that
implements a Foreign-Function Interface (FFI), such as the libffi
library.  Use of libffi is automatically enabled if the libffi library
is found (and the same with ffcall, although libffi takes precedence),
unless specifically disabled with '--disable-do'.

3 Compilation
=============

To compile this library, type make.  After this is complete, type make
install (make sure you are the root user).  Some additional options you
can use with make are 'debug=yes' to make a debugging version of the
library and 'shared=no' to make a static version of the library.  See
the gstep-make package for more information on these options.

   If you can't install gstep-base as root, be sure to edit the
'Tools/gdomap.h' file and uncomment the last line.

   Copyright (C) 2005 Free Software Foundation

   Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.