libs-base/Documentation/gnustep-howto.texi

\input texinfo @c -*-texinfo-*-

@setfilename gnustep-howto.texi

@paragraphindent 4

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

Copyright (C) 1993, 1996 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 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.
@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
a modified version of the GNU C compiler gcc and 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.

@section Summary

Currently, you pretty much need to get and install the latest versions
of the following packages:
@display
gcc, gdb, and assorted patches to make them work with Objective-C
GNU make
tiff library
DGS or Adobe DPS
gstep-make
gstep-base or libFoundation
gstep-gui
gstep-xpds
@end display

@section Getting the files

Most of the files needed by GNUstep are available from the following ftp 
sites. Except for gcc, gdb, make and libtiff, alpha.gnu.org and 
zarquon 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
@item ftp://ftp.gnustep.org/pub/gnustep	
All GNUstep releases
@item ftp://zarquon.mathi.uni-heidelberg.de/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.7.2.1.tar.gz (The gcc compiler. Version 2.7.2 also works):
gdb-4.16.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.

gcc-2.7.2.1-objc-970318.diff.gz (patch for multi-threaded Obj-C runtime)
  From the gstep-base distribution (gcc-2.7.2.1-objc.diff) or
  ftp://alpha.gnu.org/gnu/gnustep
  ftp://ftp.gnustep.org/pub/gnustep/developer
  ftp://zarquon.mathi.uni-heidelberg.de/pub/GNUstep/developer/releases
gdb-4.16-objc-971112.diff.gz (A patch for easier debugging of Objective-C code).
  ftp://alpha.gnu.org/gnu/gnustep
  ftp://ftp.gnustep.org/pub/gnustep/developer

tiff-v3.4beta036-tar.gz (The TIFF library)
tiff-970711.tar.gz
  ftp://ftp.sgi.com/graphics/tiff/
  ftp://alpha.gnu.org/gnu/gnustep
  ftp://zarquon.mathi.uni-heidelberg.de/pub/GNUstep/related
    
pcthreads-1.1.0.tar.gz (PCThreads for Linux/GNU Inel x86 systems)
  ftp://alpha.gnu.org/gnu/gnustep
  
gstep-make-971102.tar.gz (Makefile package)
dgs-970711.tar.gz (The Display Ghostscript distribution)
gstep-base-971102.tar.gz (Foundation)
gstep-gui-971102.tar.gz (AppKit)
gstep-xdps-971102.tar.gz (X11/PostScript backend)
  ftp://alpha.gnu.org/gnu/gnustep/snap
  ftp://ftp.gnustep.org/pub/gnustep/developer/snap
  ftp://zarquon.mathi.uni-heidelberg.de/pub/GNUstep/developer/snapshots

libFoundation-0.8.0.tar.gz (Foundation)
  ftp://zarquon.mathi.uni-heidelberg.de/pub/GNUstep
  ftp://alpha.gnu.org/gnu/gnustep
@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 these 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 Compiling and Installing the packages

@subsection Compiling 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 Installing the Makefile package

First 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-make-XXXXXX
./configure --prefix=/usr/local/GNUstep
su root
make install
@end example

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:

@example
LIBS=-lthread; ./configure --prefix=/usr/local/GNUstep
@end example

After this you should add the shell script @file{GNUstep.sh} in the makefile
package to you initialization 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 change the @file{GNUstep.sh} script so it will work with csh. 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 Compiling PCThreads

For Linux/GNU 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.

@example
cd /usr/src
tar fvxz pcthreads-1.1.0.tar.gz
cd pcthreads-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 Patching and Compiling GCC

The following commands assume that all the aforementioned files have been
copied to the /usr/src directory on your machine.

@table @asis
@item 1. Uncompress gcc:

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

@item 2. Apply the Objective-C runtime patch. 
Go inside the GCC directory and issue
the command (Make sure you have the correct patch for the version of gcc):

@format
  cd gcc-2.7.2.1
  cat gcc-2.7.2.1-objc.diff | patch -p1
@end format

@item 3. 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 with the GNUstep directory structure; then you should specify the
  GNUstep system root as the prefix when you configure the package.

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

@item 4. Compile gcc

4.1 With a single-threaded Objective-C runtime:

make OBJC_THREAD_FILE=thr-single

or

4.2 With thread support appropriate for your system

make

or

4.3 With PCThreads support (Linux/GNU)

make OBJC_THREAD_FILE=thr-pthreads

@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.7.2.1
@end format
@end table

@subsection Patching and Compiling GDB

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

@format
  cd /usr/src
  tar fvxz gdb-4.16.tar.gz
  gunzip gdb-4.16-objc-971112.diff.gz
  cd gdb-4.16
  patch -p1 < ../gdb-4.16-objc-971112.diff
@end format

@item Configure, compile and install gdb:

@format
  cd /usr/src/gdb-4.16
  ./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.

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

@item 4. 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 libtiff

You don't need a customized version of libtiff, or necessarily even the
newest one, but the customized version located at the GNUstep ftp sites
will install in the GNUstep directory structure.

@example
  cd /usr/src
  tar fvxz tiff-XXXXX.tar.gz
  cd tiff-XXX
  ./configure
  make
  su root
  make install
@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
  ./configure
  make
  su root
  make install
@end example

@subsection Building a Foundation library

With this and the following packages you can use the various switches,
shared, debug. As in ``make shared=no debug=yes'' (Make sure you use the
same switches for every package you compile). If you work with gstep-base:

@example
  cd /usr/src
  tar fvxz gstep-base-XXXXXX.tar.gz
  cd gstep-base-XXXXXX
  ./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-gui
  make
  su root
  make install
@end example

Compile the XDPS library:

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

@section Additional Installation

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:

@enumerate
@item Use the dwrite utility to set ``Local Time Zone'' to your local
time zone.

@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

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!