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

   GNUstep-HOWTO

   Last Update: 9 February 1999

   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>.
             Camille Troillard <tuscland@wanadoo.fr>

   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 GNU Objective-C 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
=======

   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.

Required packages:
    GNU make
          To process the makefile frameworks. This package is necessary
          to compile every GNUstep packages, but can also be used for
          `GCC' or `egcs'

          Suggested files
             - make-3.75.tar.gz

          Avaible at:
             - ftp://ftp.gnu.org/pub/gnu or other GNU mirror sites

    GCC or egcs
          To compile everything that is needed

          Suggested files:
             - gcc-2.8.0.tar.gz

             - egcs-1.0.1.tar.gz

          Avaible at:
             - ftp://ftp.gnu.org/pub/gnu

             - ftp://ftp.cygnus.com/pub/egcs

    TIFF library
          If you do not have one yet. Most of Linux distributions
          provide a TIFF library in the installation disks

          Suggested files:
             - tiff-970711.tar.gz

             - tiff-v3.4beta036-tar.gz or greater version

          Avaible at:
             - ftp://ftp.sgi.com/graphics/tiff

             - ftp://alpha.gnu.org/gnu/gnustep

             - ftp://ftp.gnustep.org/pub/gnustep

    gstep-core
          Which is composed of the individual packages:
             * gstep-make

             * gstep-base(*)

             * gstep-gui

             * gstep-xdps

             * gstep-xraw

          gstep-core contains everything you need to compile and
          install a functionnal GNUstep system.

          Note: You can replace * annoted package by libFoundation. You
          may get either one of the Foundations libraries (you only
          need to take one of them, not both) gstep-base or
          libFoundation.

          Suggested files:
             - gstep-core-0.5.0.tar.gz

               Or the individual packages:

             - gstep-make-0.5.0.tar.gz

             - gstep-base-0.5.0.tar.gz(*)

             - gstep-gui-0.5.0.tar.gz

             - gstep-xdps-0.5.0.tar.gz

             - gstep-xraw-980820.tar.gz

             - gstep-extensions-980820.tar.gz(*)

               Alternatives to (*) marked packages:

             - libFoundation-0.8.0.tar.gz

          Avaible at:
               GNUstep developer releases and snapshots:

             - ftp://alpha.gnu.org/gnu/gnustep

               All GNUstep releases:

             - ftp://ftp.gnustep.org/pub/gnustep

Optionnal/Developpement-use packages:
    DGS or Adobe DPS
          If you want to use the features of a Postscript backend. Note
          that it is not required since you can use the XRAW backend
          that is Xlib based

          Suggested files:
             - dgs-0.5.0.tar.gz

          Avaible at:
             - ftp://ftp.gnu.org/pub/gnu

             - ftp://ftp.gnustep.org/pub/gnustep

             - ftp://alpha.gnu.org/gnu/gnustep

    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.

          Suggested files:
             - pthreads-1.1.0.tar.gz

          Avaible at:
             - ftp://alpha.gnu.org/gnu/gnustep

             - ftp://ftp.gnustep.org/pub/gnustep

    GDB and patch to make it work with better Objective-C
          If you want to debug Objective-C applications with GNUstep.
          Note: It is recomended to get GDB though GNUstep is still in
          a developpement stage.

          Suggested files:
             - gdb-4.17.tar.gz

             - gdb-4.17-objc-unoff-980505.patch.gz (For easier
               debugging of Objective-C).

          Avaible at:
               The GDB release

             - ftp://ftp.gnu.org/pub/gnu or other GNU mirror sites

               The GDB ObjC patch

             - ftp://alpha.gnu.org/gnu/gnustep/contrib

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: you will need to be able to install packages as root (at least
the base library) for applications to work correctly.

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

   GNU make is required to compile all GNUstep packages. Install GNU
make according to the instructions in the package. Most likely, you can
just type:

     ./configure
     make
     su root
     make install

Compiling PCThreads
-------------------

   GNU/Linux systems that do not use linuxthreads (provided by glibc2)
have to use PCThreads. If you have a recent version of GNU/Linux, you
probably don't need to install this package (*note Machine Specific::.).

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

   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.

   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. On some systems, thread support
is enabled by default, so you may not need to add this argument to
configure.

   To compile gcc, type

make bootstrap

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

Installing the Core Libraries
-----------------------------

   If you have the gstep-core package, you can make and install all the
GNUstep core packages at one time. You can install individual packages,
but you must install the Makefile package first if you want to do this
(*note 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. Please
don't forget to read the special note included in this section.

   If you don't have the TIFF library and/or DPS libraries, and you
want to use them, you should install those libraries first (*note DGS
Library::.), and then come back to this section.

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

   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

   SPECIAL NOTE: 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-xdps

   to compile with the xdps library rather than xraw.

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

Compiling the TIFF library
--------------------------

   Install the TIFF library if you haven't got one yet.

   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.

Building DGS
------------

   Install DGS if you want to use the XDPS backend, you do not need it
if you want to use the XRAW backend.

   If you have a real Display Postscript system already on your
computer, you don't necessarily need DGS. Linux/GNU michines need DGS.

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

   If you want to install individual packages, rather than installing
the core package, you must install the Makefile package first.
Configuring the Makefile package is similar to configuring the Core
Package (*note Core Package::.).

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 programs for the base library are in `base/Testing', 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 Instructions
=============================

   This section contains instructions specific to machine types and OS
types.

FreeBSD 3.x
-----------

   Need to add -ljpeg to CONFIG_SYSTEMS_LIBS in make/config.make. This
could be fixed now, but it doesn't hurt.

FreeBSD 2.2.x
-------------

   Use /stand/sysinstall to install these packages if you have not
already done so:

gmake           (GNU make)
gcc 2.8.x

   Seems to compile ok, but some XRAW tests crash. Possibly due to a
performace 'hack' in base. Might be a good idea to upgrade to FeeBSD
3.x.

Intel/GNU-Linux (RedHat 5.x)
----------------------------

   Comes with a a good version of gcc and a threads library so you don't
need wither of these.  Make sure you set CC=egcs before configuring, as
in:

     export CC=egcs
     configure ....

   Since RedHat also comes with an old version of gcc standard.

MIPS/Irix6.4
------------

   Not ported at all to this machine. Might be better now, but no
current testing.  A lot of files in xraw don't compile - get internal
compiler errors using gcc 2.8.1.

NetBSD
------

   Static libraries only.

PowerPC/LinuxPPC
----------------

   Had problems with lots of test apps not running but this may have
been the same fix as on MKLinux, however, it was not tested on LinuxPPC.
node OpenBSD 2.4, Intel/Solaris, NetBSD, PowerPC/LinuxPPC

OpenBSD 2.4
-----------

   Static libraries only. Several warnings.

Intel/Solaris
-------------

   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.

Sparc/Solaris 2.5.1, 2.6
------------------------

   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). It's possible that the
newest versions have this patch already.

PowerPC/GNU-Linux (MkLinux DR 3)
--------------------------------

   Comes with a good version of gcc.  Seems to compile and install ok,
althouth DR3 has an old version of glibc, which requires some
workarounds which should be taken care of in the configuration. Not
completely tested, so some aspects, particular object invocations and
DO may not work properly.

   If you want threads, you'll probably have to get the latest gcc
compiler and glibc library (which has the threads library) and install
both.

Windows NT with CYGWIN
----------------------

   Bugs in CYGWIN that prevent compilation. No GUI backend.

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.

Other Instructions
==================

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

