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

   GNUstep-HOWTO

   Last Update: 17 February 2000

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

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

Introduction
============

   This document explains how to build the GNUstep core libraries.  The
are also other language specific and machine specific HOWTOs in the
Documentation subdirectory of the GNUstep core package and on the
GNUstep website.

   There is a nice document similar to this one in PDF format that
explains how to install GNUstep. It's avalable at
`http://www.gnustep.org' in the Documentation section.

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

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)

   * GNU make (Version 3.75 or greater)

   * The TIFF library (libtiff) (Version 3.4beta36 or greater)

   After installing these packages, get the GNUstep core libraries
package (gstep-core), or the following individual packages:

   * gstep-make

   * gstep-base

   * gstep-gui

   * gstep-xdps

   * gstep-xgps

   See `http://www.gnustep.org' for information on where to get these
packages.  Gstep-core contains everything you need to compile and
install a functional GNUstep developement system.

   Other packages you may need to get depending on the type of system
you are using, include:

   * 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 XGPS
     backend that is Xlib based.

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

   * GDB and patch to make it work better with Objective-C

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

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

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

   Other 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 the default backend.  To
see more options you can use with configure, type

     ./configure --help

   Look particularly at the end of the list that configure gives, as
these options are specific to GNUstep. For instance, if you installed
the tiff library in other than a normal directory, you can use the
`--with-tiff-include' option to tell configure where it is.

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

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

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

   If you have a real Display Postscript system already on your
computer, you don't necessarily need DGS. Linux/GNU machines 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
=======================

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

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

   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/powerpc/linux-gnu/gdomap ]; then
            $GNUSTEP_SYSTEM_ROOT/Tools/powerpc/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

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

   Test programs for the base library are in `base/Testing', test
applications are in the `Testing' directory.  To make these, just cd to
the appropriate directory and type make. Generally you will need to
install GNUstep first before doing this.

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

   \input texinfo    Below is a list of machines that people have
attempted to compile GNUstep on. GNUstep compiles with little or no
trouble on many of the more popular operating systems. Some machines
marked with _Unstable_ may have some trouble or may not work at all.

   A recommended compiler is listed for each machine, if known. You
should try to use the recommended compiler for compiling GNUstep, as
GNUstep is quite complex and tends provoke a lot of errors in some
compilers. Even versions newer than the listed compiler may not work,
so don't just get the latest version of a compiler expecting it to be
better than previous versions.

   If you have compiled GNUstep on a specific machine, please send
information about what you needed and any special instructions needed
to the GNUstep maintainer <gnustep-maintainers@gnu.org>.

   If your having mysterious trouble with a machine, try compiling
GNUstep without optimization. Particularly in the newer GCC compilers,
optimization can break some code. The easiest way to do this is when
configuring: `CFLAGS="" ./configure'. Or `make OPTFLAG=""'.

Debian/DEC-Alpha
----------------

`Recommended compiler'
     Unknown

`Extra libs needed'
     Unknown

`Special Instructions'
     Unknown

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

`Recommended compiler'
     gcc 2.95.2

`Extra libs needed'
     Unknown

`Special Instructions'
     You need to use gmake not make to compile the GNUstep packages. A
     special port of gdb can be used with the Objective-C patches from
     <ftp://ftp.pcnet.com/users/eischen/FreeBSD/gdb-4.17-port.tar.gz>

     The best compiler for GNUstep is the latest release of the GNU
     Compiler Collection (GCC).  You can find it at
     <http://egcs.cygnus.com/>.

     If you want to use the native POSIX threads support from `libc_r'
     pass `--enable-threads=posix' to configure.  This is the
     recommended option as this is the FreeBSD threads package that
     gives the best results -with others you may be unable to run some
     examples like `diningPhilosophers'.

     The whole compilation process can fail if you have another threads
     library installed so watch out for installed packages like `pth'
     and such.  Besides the support for libc_r, GNUstep will also look
     for `pth' and `pcthreads', so if you have installed them and they
     aren't detected prepare to write a nice bug report.

     This can be done more much easily by using the port version.  Just
     `cd' to `/usr/ports/lang/egcs' and do a `"make WANT_THREADS=yes
     install"'.  Easy.

     If configure cannot find tiff.h or the tiff library and you have
     it installed in a non-standard place (even `/usr/local'), you may
     need to pass these flags to configure:
     `CFLAGS="-I/usr/local/include"' and `LDFLAGS="-L/usr/local/lib"'.

     GNUstep 0.6.0 uses code to access the /proc filesystem, which may
     be broken on BSD machines. To avoid this configure with the
     argument -enable-fake-main.  Later versions of GNUstep should
     check for a broken /proc filesystem.

FreeBSD 2.x (_Unstable!_)
-------------------------

`Recommended compiler'
     gcc 2.8.x

`Extra libs needed'
     Unknown

`Special Instructions'
     Only static libraries work on this system.  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 tests crash. Possibly due to a
     performace 'hack' in base. Might be a good idea to upgrade to
     FeeBSD 3.x.  You need to use gmake not make to compile the GNUstep
     packages.

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

`Recommended compiler'
     The egcs compiler that comes with RedHat

`Extra libs needed'
     Unknown

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

          export CC=egcs
          configure ....

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

GNU-Linux/PowerPC (LinuxPPC 4.x)
--------------------------------

`Recommended compiler'
     egcs-2.90.25 980302 (egcs-1.0.2 prerelease).  glibc-0.961212-1h.
     gdb: 4.16.97.

`Extra libs needed'
     None.

`Special Instructions'
     egcs-1.1.2 does NOT work.

GNU-Linux/PowerPC (LinuxPPC 5.x)
--------------------------------

`Recommended compiler'
     egcs-1.1.2 (default compiler), or gcc-2.95

`Extra libs needed'
     None.

`Special Instructions'
     You need to compile without optimization or the compiler will not
     be able to compile several files (CFLAGS="" ./configure). Compiling
     with CFLAGS="-O" also works. The gcc-2.95 compiler fixes this
     problem.  There may be a problem with the X server that causes
     programs to crash with a X_QueryColors error. If so, get a newer X
     server at
     <ftp://ftp.linuxppc.org/linuxppc/contrib/linuxppc-1999/software/XFree86-FBDev-3.3.3.1-49b.ppc.rpm>.
     Distributed Objects (and Invocations) does not work well on PPC.

Irix 6.4/MIPS (_Unstable!_)
---------------------------

`Recommended compiler'
     Unknown

`Extra libs needed'
     Unknown

`Special Instructions'
     Not ported at all to this machine. Might be better now, but no
     current testing.  Some files don't compile - get internal compiler
     errors using gcc 2.8.1.

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

`Recommended compiler'
     egcs-2.90.25 980302 (egcs-1.0.2 prerelease) which comes standard
     with DR 3.

`Extra libs needed'
     None.

`Special Instructions'
     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.

NetBSD (_Unstable!_)
--------------------

`Recommended compiler'
     Unknown

`Extra libs needed'
     Unknown

`Special Instructions'
     Can only compile with static libraries.

     If configure cannot find tiff.h or the tiff library and you have
     it installed in a non-standard place (even `/usr/local'), you may
     need to pass these flags to configure:
     `CFLAGS="-I/usr/local/include"' and `LDFLAGS="-L/usr/local/lib"'.

     GNUstep 0.6.0 uses code to access the /proc filesystem, which may
     be broken on BSD machines. To avoid this configure with the
     argument -enable-fake-main.  Later versions of GNUstep should
     check for a broken /proc filesystem.

Netwinder (_Unstable!_)
-----------------------

`Recommended compiler'
     Build #12 of the system.

`Extra libs needed'
     Unknown

`Special Instructions'
     See <http://www.netwinder.org/~patrix>

OpenBSD 2.x  (_Unstable!_)
--------------------------

`Recommended compiler'
     Unknown

`Extra libs needed'
     Unknown

`Special Instructions'
     Can only compile with static libraries. Gives a lot of warnings

     GNUstep 0.6.0 uses code to access the /proc filesystem, which may
     be broken on BSD machines. To avoid this configure with the
     argument -enable-fake-main.  Later versions of GNUstep should
     check for a broken /proc filesystem.

OSF Alpha  (_Unstable!_)
------------------------

   Information is for Version 3.2C

`Recommended compiler'
     egcs-1.1.1/1.1.2, gcc-2.95

`Extra libs needed'
     Unknown

`Special Instructions'
     Can only compile with static libraries. Compiler may fail when
     linking executables (e.g. gdnc). Standard ranlib and ar programs
     are to feable to create libraries. Should use GNU binutils
     versions. Linker sometimes fails to find symbols, in which case
     you may need to link with a library twice. For instance, add an
     extra -lgnustep-xgps in ADDTIONAL_TOOL_LIBS in the
     GNUmakefile(.preamble).

Solaris 2.5.1/Sparc
-------------------

`Recommended compiler'
     Unknown

`Extra libs needed'
     tiff, Don't use the one in /usr/openwin

`Special Instructions'
     GCC 2.8.0 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 all versions of egcs up through 1.1.2
     (and perhaps beyond)).

     To avoid using the tiff library in /usr/openwin, configure like
     this:
          LIBS=-L/usr/local/lib ./configure
     if, for instance, you have put a newer tiff library in
     /usr/local/lib

Solaris 2.6/Sparc
-----------------

`Recommended compiler'
     egcs-2.91.60 (1.1.2?), egcs-1.0.1, gcc 2.8.1

`Extra libs needed'
     tiff, Don't use the one in /usr/openwin

`Special Instructions'
     GCC 2.8.0 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 all versions of egcs up through 1.1.2
     (and perhaps beyond)).

     To avoid using the tiff library in /usr/openwin, configure like
     this:
          LIBS=-L/usr/local/lib ./configure
     if, for instance, you have put a newer tiff library in
     /usr/local/lib You may also have to add -lposix4 if you compiled
     gcc with posix threads (the default in egcs 1.1.2, at least).

   Even with the about patch, distributed objects and invocations still
don't seem to work well. Unfortuneatly, this means none of the GUI
programs work bacuse they rely on starting up a distributed objects
server.

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

`Recommended compiler'
     egcs 1.1.2

`Extra libs needed'
     Unknown

`Special Instructions'
     Make sure there are no -g compiler flags (specify `CFLAGS=
     ./configure', when configuring) or remove it from `OPTFLAG'
     make/config.make. You will probable get a lot of text relocation
     warnings, which probably can be ignored.

Suse 6.1/Intel
--------------

`Recommended compiler'
     Standard

`Extra libs needed'
     None

`Special Instructions'
     None

Unixware-2.1.3/Intel
--------------------

`Recommended compiler'
     Unknown

`Extra libs needed'
     Unknown

   Special Instructions for 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 sometimes doesn't work on unixware after
     applying some of the OS patches.

     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.

Windows NT with CYGWIN (_Unstable!_)
------------------------------------

`Recommended compiler'
     Unknown

`Extra libs needed'
     Unknown

`Special Instructions'
     Bugs in CYGWIN that prevent compilation (though with a fairly easy
     workaround).  No GUI backend.

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

     cvs -z3 update -Pd

   You don't have to re-checkout after you have the source, just update!
Also try `cvs checkout -c' to get a list of available modules.

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

Acknowledgements
================

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

   This file is part of GNUstep.

