
@setfilename gnustep-howto.texi
@chapter GNUstep HOWTO

@c @paragraphindent 4

@ignore
This file gives a quick introduction to installing GNUstep.

Copyright (C) 1993 - 1998 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU Library General Public License'' is included exactly as
in the original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU Library General Public License'' and
this permission notice may be included in translations approved by the
Free Software Foundation instead of in the original English.
@end ignore

@format
   GNUstep-HOWTO

   Last Update: @today{}

   This document explains how to build the different components
   of GNUstep.

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

   Authors:  Pascal Forget <pascal@@wsc.com>,
             Ovidiu Predescu <ovidiu@@net-community.com>,
             Adam Fedor <fedor@@doc.com>.

   This file is part of GNUstep.
@end format

@section Introduction

This document explains how to build the GNUstep project along with all
the tools required to develop applications with it.

In order to easily compile and debug GNUstep projects, you will need the
latest GNU ObjC compiler @samp{GCC} and a modified version of the GNU
debugger @samp{GDB}.

You will need at least 80Mb of hard disk space in order to compile
the GNUstep project.  Luckily, you can delete the object files
and the uncompressed source code after each piece of the project
has been successfully built and installed in order to save some
space.  The biggest offender is the GCC compiler, which eats up 50Mb
of hard disk space while it compiles.

@section Summary

Currently, you pretty much need to get and install the latest versions
of the following packages:
@display
GCC or egcs
GDB and patch to make it work with better Objective-C
GNU make
TIFF library
DGS or Adobe DPS
gstep-core which is composed of the individual packages:
  gstep-make
  gstep-base or libFoundation
  gstep-gui
  gstep-xdps
  gstep-xraw
  gstep-extensions or FoundationExt
@end display

@section Getting the files

Most of the files needed by GNUstep are available from the following ftp
sites. Except for GCC, GDB, GNU make and TIFF, alpha.gnu.org 
should contain the latest versions of all the required
packages.

@table @samp
@item ftp://ftp.gnu.org/pub/gnu
GCC, GDB, and other GNU tools, and
GNUstep public releases
@item ftp://ftp.sgi.com/graphics/tiff		
TIFF library
@item ftp://alpha.gnu.org/gnu/gnustep		
GNUstep developer releases and snapshots
@item ftp://ftp.gnustep.org/pub/gnustep	
All GNUstep releases
@end table

You need the following packages of either the version given or any later
version, in order to compile GNUstep.

@example
gcc-2.8.0.tar.gz (The GCC compiler)
  ftp://ftp.gnu.org/pub/gnu or from other GNU mirror sites.
  You can also use egcs-1.0.1.tar.gz, from ftp://ftp.cygnus.com/pub/egcs

gdb-4.17.tar.gz (The GDB debugger)
make-3.75.tar.gz (You need GNU make to compile GNUstep).
  ftp://ftp.gnu.org/pub/gnu or from other GNU mirror sites.

gdb-4.17-objc-unoff-980505.patch.gz (For easier debugging of Objective-C).
  ftp://alpha.gnu.org/gnu/gnustep/contrib

tiff-970711.tar.gz (The TIFF library), or
  you can use tiff-v3.4beta036-tar.gz or greater version
  ftp://ftp.sgi.com/graphics/tiff/
  ftp://alpha.gnu.org/gnu/gnustep
  ftp://ftp.gnustep.org/pub/gnustep
    
pthreads-1.1.0.tar.gz (PCThreads for Linux/GNU Inel x86 systems)
  ftp://alpha.gnu.org/gnu/gnustep
  ftp://ftp.gnustep.org/pub/gnustep
or use glibc2 with pthread (linuxthreads)

gstep-core-0.5.0.tar.gz (Contains gstep-make, -extensions, -base, -gui, -xdps)
gstep-make-0.5.0.tar.gz (Makefile package)
gstep-base-0.5.0.tar.gz (Foundation)
gstep-gui-0.5.0.tar.gz (AppKit)
gstep-xdps-0.5.0.tar.gz (X11/PostScript backend)
gstep-xraw-980820.tar.gz (X11 backend)
gstep-extensions-980820.tar.gz (Foundation extensions)
dgs-0.5.0.tar.gz (The Display Ghostscript distribution)
  ftp://ftp.gnu.org/pub/gnu
  ftp://ftp.gnustep.org/pub/gnustep
  ftp://alpha.gnu.org/gnu/gnustep
  or get libraries via anonymous CVS

libFoundation-0.8.0.tar.gz (Alternate Foundation)
  ftp://ftp.gnustep.org/pub/gnustep
  ftp://alpha.gnu.org/gnu/gnustep
  ftp://ftp.gnu.org/pub/gnu

@end example

You may get either one of the Foundations libraries (you only need to 
take one of them, not both) gstep-base or libFoundation.

Note that you should get the latest version available, not necessarily
the one listed here. For the more adventurous, and since the project is
still in development, it might be better to get the latest snapshot
located in the snap or snapshot subdirectories at
ftp://alpha.gnu.org/gnu/gnustep/snap or the other appropriate ftp locations.

For the following instructions, some version numbers are replaced by XXX.
You shoule replace the 'X's with the version of the package you have.

@section 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 core via CVS:

The quick and painless CVS tutorial (by michael hanni (slightly modified) 

    First, set the CVSROOT environment variable. If you are using
bash/sh you can do something like this at the prompt:
@example
$ export CVSROOT=":pserver:anoncvs@@cvs.net-community.com:/gnustep" 
@end example

    Second, if this is the first time loging into the CVS server:
@example
$ cvs login <press enter> 
@end example

    You should get a password prompt soon after:
@example
(Logging in to anoncvs@@cvs.net-community.com) 
CVS password:  
@end example

    Enter the password @samp{anoncvs}. This should return you to your
prompt. From here you can checkout any module in the CVS server you
like. To checkout a module you do this:
@example
$ cvs -z3 checkout modulename <press enter> 
@end example

    The -z3 merely tells the cvs server to compess everything to a
certain compression level before it sends it to you. 

    If you haven't already done so, change to the directory, where you
want the source to reside.
    
    Next, you want to get the whole core, so you do:
@example
$ cvs -z3 checkout core
@end example

    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 'xraw', and type:

@example
$ cvs -z3 update <press enter> 
@end example

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

@section Compiling and Installing the packages

Note that the following instructions assume you are installing the
libraries in a directory owned by root. If you are installing the
libraries in a place that you as a user can write to, you can skip the
@samp{su root} instructions.

@subsection Compiling GNU make

GNU make is required to compile all GNUstep packages.

@example
cd /usr/src
tar fvxz make-XXX.tar.gz
cd make-XXX
./configure
make
su root
make install
@end example

@subsection Compiling PCThreads

For GNU/Linux systems on Intel x86 processors, the PCThreads library is
known to work with GNUstep.  PCThreads version 1.1.0 is an enhanced version
of PCThread 1.0.0 with better support for GNUstep. PCThreads may no longer
be necessary on all GNU/Linux systems, such as Debian 2.0 or other systems
with glibc2.

@example
cd /usr/src
tar fvxz pthreads-1.1.0.tar.gz
cd pthreads-1.1.0
./configure
make
su root
make install
@end example

If you are using the GNUstep makefile package and wish PCThreads to be
installed with the GNUstep directory structure; then you should specify the
GNUstep system root as the prefix when you configure the package.

@example
./configure --prefix=$GNUSTEP_SYSTEM_ROOT
@end example

@subsection Compiling GCC

The following commands assume that all the aforementioned files have
been copied to the /usr/src directory on your machine.  If you already
have GCC 2.8.0 installed on your system then there is no need to compile
it again, just set up your PATH so that the new GCC is used for
compiling GNUstep.

Special note for Solaris users.  GNUstep works on Solaris/Intel systems;
however, GCC 2.8.0 has problems, so you must use the older patched GCC
2.7.2 instead.  GCC 2.8.0 has also induced a problem on Solaris/Sparc
systems; however, there is a patch to fix this in the contrib directory
on the ftp sites (This is also true for egcs-1.0.1).

@table @asis
@item 1. Uncompress GCC:

@format
  cd /usr/src
  tar fvxz gcc-2.8.0.tar.gz
@end format

@item 2. Configure the GCC compiler's makefile for your machine:

@format
  ./configure
@end format

If you are using the GNUstep makefile package and wish GCC to be
installed within the GNUstep directory structure; then you should
specify the GNUstep system root as the prefix when you configure the
package.  This setup requires that you compile and install the GNUstep
Makefile Package before configuring GCC.

@format
  ./configure --prefix=$GNUSTEP_SYSTEM_ROOT
@end format

To enable multiple threads in the Objective-C library use the
@var{--enable-threads=lib} argument to configure, where @var{lib} is the
thread library to use or @var{--disable-threads} to use a
single-threaded Objective-C runtime.  If your system has a native
threads library, like Solaris or SGI, then the @var{--enable-threads}
parameter without the @var{lib} specification will use that native
threads library.

@item 4. Compile GCC

make bootstrap

@item 5. Wait

@format
  If you have a Pentium Pro, go drink a coffee.
  If you have a fast Pentium, count from 0 to 100 in your head.
  If you have a slow Pentium, go eat a bagel.
  If you have a 486, go watch the news.
  If you have a 386, come back tomorrow.
@end format

@item 6. Install GCC

@format
  su root
  make install
@end format

@item 7. Delete the GCC directory if you're low on disk space

@format
  rm -rf /usr/src/gcc-2.8.0
@end format
@end table

@subsection Patching and Compiling GDB

@table @asis
@item 1. Uncompress GDB, and patch it:

@format
  cd /usr/src
  tar fvxz gdb-4.17.tar.gz
  gunzip gdb-4.17-objc-unoff-980505.patch.gz
  cd gdb-4.16
  patch -p1 < ../gdb-4.17-objc-unoff-980505.patch
@end format

@item 2. Configure, compile and install GDB:

@format
  cd /usr/src/gdb-4.17
  ./configure
  make
  su root
  make install
@end format

If you are using the GNUstep makefile package and wish GDB to be
installed with the GNUstep directory structure; then you should specify
the GNUstep system root as the prefix when you configure the package.
This setup requires that you compile and install the GNUstep Makefile
Package before configuring GCC.

@format
  ./configure --prefix=$GNUSTEP_SYSTEM_ROOT
@end format

@item 3. Make sure GDB is where you think it is

On Linux/GNU, GDB should be installed in /usr/bin, whereas on other
systems, the default installation path is usually /usr/local/bin.  If
you have a Linux/GNU box, you can do this:

@format
  ln -s /usr/local/bin/gdb /usr/bin/gdb
@end format

Note that this is only a suggestion, you are free to do
whatever you want.
@end table

@subsection Compiling the TIFF library

You don't need a customized version of the TIFF library, or necessarily
even the newest one, but the customized version located at the GNUstep
ftp sites will install in the GNUstep directory structure. If you do use
the customized verion you need to make and install the Makefile
package (described below) first.

@example
  cd /usr/src
  tar fvxz tiff-XXXXX.tar.gz
  cd tiff-XXX
  ./configure
  make
  su root
  make install
@end example

@subsection Installing the GNUstep libraries

If you have the gstep-core package, you can make and install all the
GNUstep core packages at one time. If you already have a TIFF library
and a Display Postscript system installed, you can do this following the
example instructions below.  If you don't already have a TIFF library or
DPS, you have to do things in a slightly different order.

If you have the separate gstep packages, skip to the next section
(Installing the Makefile package).

First decide where you want the GNUstep files to go, and use this as
an argument to configure. If you don't choose
a location, the default is /usr/GNUstep.  The example below shows how
to configure the packages for installation in /usr/local/GNUstep.

If you don't have the TIFF library or DPS, first make and install the
Makefile package, the TIFF library and DGS, as shown in the following
three sections.

After you have TIFF and DPS/DGS installed, make the core libraries:

@example
tar fvxz gstep-core-XXXXX.tar.gz
cd gstep-core-XXXX
./configure --prefix=/usr/local/GNUstep
make
su root
make install
@end example

Skip to the Additional Instructions sections to finish up installation
of the GNUstep system.

Alternate libraries:

You can specify compilation of alternate libraries by using the
--with-library-combo option. You need to have these libraries unpacked in a
subdirectory under the gstep directory, then you can say

@example
./configure --with-library-combo=gnu-gnu-gnu-xraw
@end example

to compile with the xraw library rather than the xdps. Currently the
xraw library is better supported than xdps, so this may be something you
want to do.

With the various GNUstep libraries you can use the various
switches, shared and debug. As in ``make shared=no debug=yes'' (Make sure
you use the same switches for every package you compile, and also when
you install).

@subsection Installing the Makefile package

Decide where you want the GNUstep files to go, and use this as
an argument to configure in the makefile package. If you don't choose
a location, the default is /usr/GNUstep.  The example below shows how
to configure the packages for installation in /usr/local/GNUstep.

@example
tar fvxz gstep-make-XXXXXX.tar.gz
cd gstep-XXXXXX/make
./configure --prefix=/usr/local/GNUstep
make
su root
make install
@end example

After this you should add the shell script @file{GNUstep.sh} in the makefile
package to your shell startup file (such as @file{.profile}). For instance:

@example
. /usr/local/GNUstep/Makefiles/GNUstep.sh
@end example

in your @file{.profile} file will work. It defines environment variables that
are needed to find GNUstep files and executables.  Users of csh need
to use the @file{GNUstep.csh} script. Read the @file{README} for more info.

GNUstep packages will automatically install in this directory structure. You
can install other packages (such as GCC) in the same structure if you specify
the GNUstep system root as the prefix when you configure the package.

@example
./configure --prefix=$GNUSTEP_SYSTEM_ROOT
@end example

@subsection Building DGS

If you have a real Display Postscript system already on your computer,
you don't necessarily need DGS. Linux/GNU michines need DGS.
You can also read the file DGS-HOWTO located at the ftp machines listed 
above.

@example
  tar fvxz dgs-XXXXXX.tar.gz
  cd dgs-XXXXXX/dgs
  ./configure
  make
  su root
  make install
@end example


@subsection Building a Foundation library

If you work with gstep-base:

@example
  cd /usr/src
  tar fvxz gstep-base-XXXXXX.tar.gz
  cd gstep-XXXXXX/base
  ./configure
  make
  su root
  make install
@end example

On some Linux systems, you may have to change the optimization level
(particularly if you get an error compiling mframe.m):

@example
  make OPTFLAG=-O
@end example

If you work with libFoundation:

@example
  cd /usr/src
  tar zxf libFoundation-0.8.0.tar.gz
  cd libFoundation-0.8.0/libFoundation
  ./configure --with-gnustep
  make
  su root
  make install
@end example

@subsection Building the GUI libraries

Compile the GUI library:

@example
  cd /usr/src
  tar zxf gstep-gui-XXXXXX.tar.gz
  cd gstep-XXXXXX/gui
  make
  su root
  make install
@end example

Compile the backend library (replace xdps with xraw to compile the xraw lib):

@example
  cd /usr/src
  tar zxf gstep-xdps-XXXXXX.tar.gz
  cd gstep-XXXXXX/xdps
  ./configure
  make
  cd Testing
  make
@end example

@subsection Building the Foundation extensions

The Foundation extensions have some useful features in them. The one
reason you definitely might want to use it is to read in GNUstep model
files which store User Interface structures in ASCII format, and can
also be used to translate NeXT and OpenStep NIB files to GNUstep model
format.

Compiling:

@example
  cd /usr/src
  tar zxf FoundationExt-XXX.tar.gz
  cd extensions
  make
  su root
  make install
@end example

@section Additional Installation

If you haven't already done so when installing the Makefile package,
you should add the shell script @file{GNUstep.sh} in the Makefile
package to your shell startup file (such as @file{.profile}). For instance:

@example
. /usr/local/GNUstep/Makefiles/GNUstep.sh
@end example

in your @file{.profile} file will work. It defines environment variables that
are needed to find GNUstep files and executables.  Users of csh need
to use the @file{GNUstep.csh} script. Read the @file{README} for more info.

Set up your home GNUstep directory. This is where user defaults are
kept, and in the future, other files may be kept there.

@example
cd
mkdir GNUstep
@end example

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

@enumerate
@item 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''.

@item Set the @var{TZ} environment variable.

@item Create the file @file{$GNUSTEP_SYSTEM_ROOT/Libraries/Resources/gnustep/NSTimeZones/localtime} with the name of the local time zone in it.
@end enumerate

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

@section Test Tools and Applications

Test tools for the base library are in @file{base/checks}, test applications 
for xraw and xdps are in the @file{Testing} directory under these libraries.
To make these test, just cd to the appropriate directory and type
@var{make}.  If you haven't already installed the libraries, you'll at least
need to set @var{GNUSTEP_SYSTEM_ROOT} to point to the top-level gstep
directory. Here's an exmample:

@example
cd xraw/Testing
GNUSTEP_SYSTEM_ROOT=/home/users/fedor/src/gstep-0.5.0 make
@end example

Finally, run the tests in the Testing directory. Use the openapp utility
that is part of the GNUstep makefile package (and stored in
@file{$GNUSTEP_SYSTEM_ROOT/Tools}). Usage is:

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

Good Luck!

@section Machine Specific and Other Instructions

This section contains instructions specific to machine types, plus other
various caveats, hints, and suggestions.

@subsection Better debugging and compiling just the Objective-C runtime

Normally, the Objective-C runtime is compiled with debugging information,
which actually makes debugging of user apps frustrating because stepping
into a method call will actually cause gdb to step into the internal
Objective-C method call mechanism, which you don't want most of the time.

The way to avoid this is to compile the Objective-C runtime library without
debugging information. Here's how:

@example
cd egcs-build-directory/gcc
rm -f objc/*.o
make CFLAGS=-O2 libobjc.a
cp libobjc.a your-egcs-installation-dir
@end example

@subsection Unixware 2.1.3

GNUstep installation on Unixware 2.1 systems

@table @asis

@item   1
Tune the kernel to increase the argument space so that we can pass long
command-line argument strings to processes (which the makefiles do)
(/etc/conf/bin/idtune ARG_MAX 102400)

@item   2
Install raft of the latest GNU software

@format
gzip            (you need this to unpack other stuff)
make            (to build everything)
m4              (for autoconf etc)
autoconf        (if you need to change anything)
bison
flex
binutils        (required by gcc if you want to debug)
gcc-2.8.1
                (configure --with-gnu-as --with-gnu-ld --with-stabs)
                NB. gcc-2.8.1 needs a fix to __do_global_dtors_aux()
                in crtstuff.c on Unixware 2.1.3
                (and possibly other unixware versions)
                The fix is already in recent versions of egcs.

@end format

@example
==================================
static void
__do_global_dtors_aux ()
@{
  static func_ptr *p = __DTOR_LIST__ + 1;
  static int completed = 0;

  if (completed)
    return;

  while (*p)
    @{
      p++;
      (*(p-1)) ();
    @}

#ifdef EH_FRAME_SECTION_ASM_OP
  __deregister_frame_info (__EH_FRAME_BEGIN__);
#endif
  completed = 1;
@}
======================================
@end example

@item   3
Having got gcc working - it's probably a good idea to rebuild 
all your GNU software using it!

@item   4
Build gstep as normal.

@item   5
The SIOCGIFCONF ioctl doesn't work on unixware 

So I have added a '-a' flag to gdomap to give it the name of a file
containing IP address and netmask information for the network interfaces
on the system.

You need to set up a file (I suggest '/etc/gdomap_addresses') containing
the information for your machine and modify your system startup files in
/etc/rc?.d to run gdomap, telling it to use that file.

eg. If your machine has an IP address of '193.111.111.2' and is on a
class-C network, your /etc/gdomap_addresses file would contain the line

@example
193.111.111.2 255.255.255.0
@end example

and your startup file would contain the lines

@example
. /usr/local/GNUstep/Makefiles/GNUstep.sh
gdomap -a /etc/gdomap_addresses
@end example

@end table

If you don't set gdomap up correctly, Distributed Objects will not
work.


