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

   GNUstep-HOWTO

   Last Update: 3 November 1998

   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.

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 `GCC' and a modified version of the GNU
debugger `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.

Summary
=======

   Currently, you pretty much need to get and install the latest
versions of the following packages:
     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

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.

`ftp://ftp.gnu.org/pub/gnu'
     GCC, GDB, and other GNU tools, and GNUstep public releases

`ftp://ftp.sgi.com/graphics/tiff'
     TIFF library

`ftp://alpha.gnu.org/gnu/gnustep'
     GNUstep developer releases and snapshots

`ftp://ftp.gnustep.org/pub/gnustep'
     All GNUstep releases

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

     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

   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.

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:
     $ export CVSROOT=":pserver:anoncvs@cvs.net-community.com:/gnustep"

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

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

   Enter the password `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:
     $ cvs -z3 checkout modulename <press enter>

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

     $ cvs -z3 update <press enter>

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

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
`su root' instructions.

Compiling GNU make
------------------

   GNU make is required to compile all GNUstep packages.

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

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.

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

   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.

     ./configure --prefix=$GNUSTEP_SYSTEM_ROOT

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).

1. Uncompress GCC:
       cd /usr/src
       tar fvxz gcc-2.8.0.tar.gz

2. Configure the GCC compiler's makefile for your machine:
       ./configure

     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.

       ./configure --prefix=$GNUSTEP_SYSTEM_ROOT

     To enable multiple threads in the Objective-C library use the
     -ENABLE-THREADS=LIB argument to configure, where LIB is the thread
     library to use or -DISABLE-THREADS to use a single-threaded
     Objective-C runtime.  If your system has a native threads library,
     like Solaris or SGI, then the -ENABLE-THREADS parameter without
     the LIB specification will use that native threads library.

4. Compile GCC
     make bootstrap

5. Wait
       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.

6. Install GCC
       su root
       make install

7. Delete the GCC directory if you're low on disk space
       rm -rf /usr/src/gcc-2.8.0

Patching and Compiling GDB
--------------------------

1. Uncompress GDB, and patch it:
       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

2. Configure, compile and install GDB:
       cd /usr/src/gdb-4.17
       ./configure
       make
       su root
       make install

     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.

       ./configure --prefix=$GNUSTEP_SYSTEM_ROOT

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:

       ln -s /usr/local/bin/gdb /usr/bin/gdb

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

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.

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

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:

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

   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

     ./configure --with-library-combo=gnu-gnu-gnu-xraw

   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).

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.

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

   If you are using, or intend to compile the GCC Objective-C runtime
with threads, you need to specify the thread package you are using when
running configure:

     LIBS=-lpcthread; ./configure --prefix=/usr/local/GNUstep

   or if you have glibc2:

     LIBS=-lpthread; ./configure --prefix=/usr/local/GNUstep

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

     . /usr/local/GNUstep/Makefiles/GNUstep.sh

   in your `.profile' file will work. 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 `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.

     ./configure --prefix=$GNUSTEP_SYSTEM_ROOT

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.

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

Building a Foundation library
-----------------------------

   If you work with gstep-base:

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

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

       make OPTFLAG=-O

   If you work with libFoundation:

       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

Building the GUI libraries
--------------------------

   Compile the GUI library:

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

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

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

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:

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

Additional Installation
=======================

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

     . /usr/local/GNUstep/Makefiles/GNUstep.sh

   in your `.profile' file will work. 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 `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.

     cd
     mkdir GNUstep

   Next, set your local time zone.  There are three ways to do this,
pick one (see
`$GNUSTEP_SYSTEM_ROOT/Libraries/Resources/gnustep/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 TZ environment variable.

  3. Create the file






     `$GNUSTEP_SYSTEM_ROOT/Libraries/Resources/gnustep/NSTimeZones/localtime'
     with the name of the local time zone in it.

   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').

Test Tools and Applications
===========================

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

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

   Finally, run the tests in the Testing directory. 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 and Other Instructions
=======================================

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

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:

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

Unixware 2.1.3
--------------

   GNUstep installation on Unixware 2.1 systems

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)

2
     Install raft of the latest GNU software

     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.

          ==================================
          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;
          }
          ======================================

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

4
     Build gstep as normal.

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

          193.111.111.2 255.255.255.0

     and your startup file would contain the lines

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

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

