        GNUstep HOWTO
        *************

        Last Update:

        This document explains how to build the different components of the
        GNUstep core libraries and GNUstep Launchpad.

        Copyright (C) 1996 - 2001 Free Software Foundation, Inc.

        Permission is granted to copy, distribute and/or modify this document
        under the terms of the GNU Free Documentation License, Version 1.1 or
        any later version published by the Free Software Foundation.

     [file version.texi not included]

Introduction
************

This document explains how to build the GNUstep core libraries or GNUstep Launchpad. The core libraries, along with associated tools and other files provide everything necessary for a working GNUstep system. GNUstep Launchpad consists of the non-graphical libraries of GNUstep.

In order to easily compile and debug GNUstep projects, you will need the GNU Objective-C compiler GCC as well as various other GNU packages.

You will need at least 80Mb of hard disk space (150Mb prefered) in order to compile the GNUstep core libraries.

Summary
*******

In order to compile the libraries, you need to compile and install the following packages first (if you don't already have them):

  * gcc (Version 2.8.0 or greater, 3.0.4 or greater recommended)

  * GNU make (Version 3.75 or greater)

  * gdb, if you plan to do any debugging

You may also need to install some of the following libraries and packages described below. Most of these packages are optional, but some are required.

ffcall libraries (HIGHLY RECOMMENDED)
     This is a library that provides stack frame handling for NSInvocation and NSConnection. This library is highly recommended. The previous builtin method for stack frame handling is no longer supported and may be removed in the future.  ffcall is under GNU GPL. As a special exception, if used in GNUstep or in derivate works of GNUstep, the included parts of ffcall are under GNU LGPL.

WindowMaker (Version >= 0.62) (OPTIONAL)
     GNUstep and WindowMaker work together to provide a consistant interface. Although it is not required, GNUstep will work much better if you use it with the WindowMaker window manager. In addition, WindowMaker includes some functionality that GNUstep uses that would otherwise not be available. Get WindowMaker from http://www.windowmaker.org.

libxml2 (OPTIONAL)
     The libxml library (Version 2) is used to translate some of the documentation for GNUstep and to provide suport for MacOS-X compatible XML-based property-lists. It is recommended but not currently required.

openssl (OPTIONAL)
     The openssl library is used to provide support for https connections by the NSURL and HSURLHandle classes.  This functionality is compiled as a separate bundle since the OpenSSL license is not compatible with GPL, and in the hopes that if someone writes an openssl replacement, it can quickly be used by creating another bundle.

libiconv (OPTIONAL)
     Unicode support functions (iconv) come with glibc version 2.1 or greater. If you don't have this, you can get the separate libiconv library from http://clisp.cons.org/~haible/packages-libiconv.html. However, neither one is required to use GNUstep.

gnustep-objc package (for gcc version < 3.0) (RECOMMENDED)
     This is a special version of the Objective-C runtime that include several bug fixes and features that were not in gcc versions previous to 3.0. It is available at ftp://ftp.gnustep.org/pub/gnustep/libs which compiles using the GNUstep Makefile package (so you don't have to get the entire gcc dist). Make sure to set the THREADING variable in the GNUmakefile. It's possible to compile the library static (make shared=no) and just copy to the place where the gcc libobjc library is (type gcc -v to get this location). Note you have to install gnustep-make (below) before installing this library.

The TIFF library (libtiff) (Version 3.4beta36 or greater) (REQUIRED)
     The GUI library uses this to handle loading and saving TIFF images.

DGS, the XFree86 DPS extension, or Adobe DPS (OPTIONAL)
     If you want to use the features of a Display Postscript (DPS)backend. Note that it is not required since you can use the XGPS backend that is Xlib based.  Note that the DPS backend is also still experimental and not recommended.  DPS can be obtained from the following locations:

       * DGS client/server, ftp://ftp.gnustep.org/pub/gnustep/dgs

       * XFree86 DPS, http://dps.sourceforge.net/

       * Adobe DPS, (contact your OS distributor)

PCThreads (OPTIONAL)
     For GNU/Linux systems on Intel x86 processors. PCThreads is no longer necessary (and should not be used) on GNU/Linux systems with glibc version 2, such as Debian 2.0 and RedHat 5.x and greater.

GDB and Objective-C patch (OPTIONAL)
     GDB can be obtained from ftp://ftp.gnu.org/gnu/gdb. The patch to make it work better with GNUstep can be obtained from ftp://ftp.gnustep.org/pub/gnustep

Compiling and Installing the packages
*************************************

Get the following individual packages:

  * gnustep-make

  * gnustep-base

  * gnustep-gui

  * gnustep-xgps

For GNUstep Launchpad, substitue gnustep-guile and jigs for gnustep-gui and gnustep-xgps/xdps.

See http://www.gnustep.org for information on where to get these packages.  Only one of gnustep-xgps or gnustep-xdps is required. We currently recommend gnustep-xgps.

Make sure you install all the previously mentioned libraries first before configuring and building GNUstep (Except you need to install gnustep-objc after installing gnustep-make).

Note: you will need to be able to install packages as root (at least the base library) for applications to work correctly.

For installation on specific systems, read the machine specific instructions at the end of this document or appropriate README files in the gnustep-make Documentation directory (such as README.MingW for Windows).

Using a Display Postscript System
=================================

Please skip this instruction unless you really know what you are doing. The DPS backend is not well developed. You are better off sticking to the gnustep-xgps backend.

Install a Display PostScript system if you want to use the XDPS backend. You do not need it if you want to use the XGPS backend. Some systems, like Sun Microcomputers(TM) already have a DPS system installed. Linux/GNU systems need to use a free implementation of DPS (described in the Introduction.)

If you are installing DGS, follow the installation instructions included with the DGS package. If you are installing the XFree86 DPS extension, follow the instructions included with that package (and note that you need to be running XFree86 version 4.0 or greater).

Installing the Core Libraries
=============================

The GNUstep packages uses the Autoconf mechanism for configuration; it checks some host capabilties which are used by all GNUstep software.  To configure just type:

     ./configure

The GNUstep makefile package needs a root directory.  If the GNUSTEP_SYSTEM_ROOT environment variable is set then configure will use its value as the root directory.  You can also specify the root directory when you run configure with the prefix paramter; the following command makes /usr/local/GNUstep the root directory:

     ./configure --prefix=/usr/local/GNUstep/System

If you do not have the GNUSTEP_SYSTEM_ROOT environment variable set and you do not specify a root directory when running configure, then configure will use /usr/GNUstep/System as the default root directory.

Alternate Library Setup
-----------------------

Read the installation instructions in the Makefile package (make) for more installation options. Make sure you use the same configuration options when configuring each GNUstep library.

Building the Package
--------------------

To build the individual packages, use this familiar set of commands for each pacakge (add any additional options you decide upon):

     ./configure
     make
     make install

Start with the Makefile Pacakge (gnustep-make). After installing gnustep-make you need to execute GNUstep's shell configuration script, as follows:

      . /usr/GNUstep/System/Makefiles/GNUstep.sh

before proceeding any further. Then do gnustep-objc. Before building gnustep-objc, edit GNUmakefile and set the THREADING variable to the thread library used on your system (usually its posix, but you can leave it at single if you don't need threads). At this point you should probably re-configure, make and install gnustep-make, so it can pick up on any threading information that gnustep-objc provides.

Now do gnustep-base, gnustep-gui and finally gnustep-xgps (or gnustep-xdps). For GNUstep Launchpad, do gnustep-guile and jigs (although both of these are optional).

NOTE: If you are trying to install the packages without root permission, you need to change one thing in the base library. Edit the file gnustep-base/Tools/gdomap.h and uncomment the last line.

Additional Installation
***********************

Environment Setup
=================

Add the shell script GNUstep.sh located in the Makefile package to your shell startup file (such as .profile). For instance:

     GNUSTEP_SYSTEM_ROOT=/usr/GNUstep
     export GNUSTEP_SYSTEM_ROOT
     . $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.sh

in your .profile file will work (Note the period at the beginning of the line). It defines environment variables that are needed to find GNUstep files and executables.  Users of csh need to use the GNUstep.csh script. Read the make package README for more info. Some systems, like GNU/Linux have an /etc/profile.d directory where scripts can be executed automatically. If you want to set up GNUstep for every user on your system, you can try copying/linking the GNUstep.sh there. For csh or tcsh, try

     setenv GNUSTEP_SYSTEM_ROOT /usr/GNUstep
     source $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.csh

GNUstep Home
============

Set up your home GNUstep directory. This is where user defaults are kept as well as other user configuration files. User installed apps, libraries, etc are also here (if the default user directory is used).

     cd
     mkdir GNUstep

Time Zone
=========

Next, set your local time zone.  There are four ways to do this, pick one (see $GNUSTEP_SYSTEM_ROOT/Libraries/Resources/NSTimeZones/zones for typical time zones):

 1. Use the defaults utility to set ``Local Time Zone'' to your local time zone (defaults is installed with GNUstep in the Tools directory). Type something like ``defaults write NSGlobalDomain "Local Time Zone" GB''.

 2. Set the GNUSTEP_TZ environment variable.

 3. Create the file $GNUSTEP_SYSTEM_ROOT/Libraries/Resources/NSTimeZones/localtime with the name of the local time zone in it.

 4. Set the TZ environment variable (this may conflict with other software on your system though).

DPS Information
===============

If you are using a built-in DPS server, you may need to set the PSRESOURCEPATH environment variable (on Solaris, it's set to /usr/openwin/lib/X11).

GNUstep deamons
===============

Set up your system to execute some GNUstep deamons. If you don't do this, they will be started automatically when you run your first GNUstep app:

  * gdomap - Put this in a system startup file, like /etc/rc.local or /etc/rc.d/rc.local (customize for your system)

          GNUSTEP_SYSTEM_ROOT=/usr/GNUstep
          if [ -f $GNUSTEP_SYSTEM_ROOT/Tools/ix86/linux-gnu/gdomap ]; then
            $GNUSTEP_SYSTEM_ROOT/Tools/ix86/linux-gnu/gdomap
          fi

  * gdnc - Put this after executing GNUstep.sh in your local .profile

  * gpbs - Put this after executing GNUstep.sh in your local .profile

     if [ `gdomap -L GDNCServer | grep Unable` ]; then
       echo "Starting GNUstep services..."
       gdnc
       gpbs
     fi

Test Tools and Applications
***************************

Test programs for the base library are in base/Testing. Example applications are located in the gstep-examples package.  To make these, just uncompress and untar this package, cd to the appropriate directory, and type make. You will need to install the GNUstep core libraries first before doing this.

To run the examples. Use the openapp utility that is part of the GNUstep makefile package (and stored in $GNUSTEP_SYSTEM_ROOT/Tools). Usage is:

     openapp [--library-combo=...] application [additional arguments to app]

Good Luck!

Machine Specific Instructions
*****************************

     [file machines.texi not included]

Getting Libraries via Anonymous CVS
***********************************

If you didn't get one of the snapshots, or if you want to be sure to stay on the bleading edge, then you should get the libraries via CVS. Go to http://savannah.gnu.org/cvs/?group_id=99 for information on how to get anonymous CVS access.

If you haven't already done so, change to the directory, where you want the source to reside. To get a list of potential modules to check out, type

     cvs -z3 checkout -c

For instance, to check our core, which contains all the GNUstep code libraries:

     cvs -z3 checkout core

After you have checked out the source you can compile it as usual. To update the source, go into the directory of the source tree you want to update, for example, go into 'xgps', and type:

     cvs -z3 update -Pd

You don't have to re-checkout after you have the source, just update!

Acknowledgements
****************

        Authors:  Adam Fedor <fedor@gnu.org>,
                  Pascal Forget <pascal@wsc.com>,
                  Ovidiu Predescu <ovidiu@net-community.com>,
                  Camille Troillard <tuscland@wanadoo.fr>
                  Richard Frith-MacDonald <richard@brainstorm.co.uk>

        This file is part of GNUstep.