1 GNUstep makefile package installation
***************************************

1.1 Introduction
================

If you are installing this package as part of the GNUstep core
libraries, read the file GNUstep-HOWTO for more complete instructions
on how to install the entire GNUstep package (including this package).
GNUstep-HOWTO comes with this distribution.

   This should be the first GNUstep package you install. Before
installing this package, install ffcall or libffi and any other
libraries that GNUstep may need (see the GNUstep-HOWTO). Read and
follow the instructions on setting up the GNUstep environement below.
Then install gnustep-base.

   Make sure you've read the machine-specific instructions for your
particular operating system and CPU. These instructions come with the
GNUstep-HOWTO and are also located at the GNUstep web site at
`http://www.gnustep.org'.

   Quick installation instructions:

     ./configure
     make
     make install

   This will use the default GNUstep filesystem layout (in other words,
all of GNUstep will end up installed into /usr/GNUstep).  If you are on
a Unix system, another popular option is

     ./configure --with-layout=fhs
     make
     make install

   which will use the FHS (in other words, all of GNUstep will end up
installed into /usr/local).

   To make and install the documentation:

     cd Documentation
     make
     make install

1.2 Configuration
=================

The GNUstep packages uses the Autoconf mechanism for configuration; it
checks some host capabilties which are used by all GNUstep software.
To configure just type:

     ./configure

   The GNUstep makefile package needs to know which filesystem layout to
use when installing; this determines the way that various directories
in the GNUstep domains (SYSTEM, NETWORK, LOCAL, USER) are mapped to
local directories on disk.  In the FilesystemLayouts/README file you
can find detailed information on filesystem layouts.

   To specify a filesystem layout, use the -with-layout=xxx option.  The
default is

     ./configure --with-layout=gnustep

   which installs GNUstep in /usr/GNUstep using the GNUstep layout (that
is, /usr/GNUstep/System, /usr/GNUstep/Local, ~/GNUstep).  Another
popular option is '-with-layout=fhs' which installs gnustep-make into
FHS directories based on /usr/local.  Check the FilesystemLayouts for
more options.

   If you want to install the same layout but in a different location
(for example, /opt/gnustep), you can use -prefix=xxx,

     ./configure --prefix=/opt/gnustep

   If you're confused and want to see exactly what directories will be
used for a certain choice of ./configure flags, have a look at the
GNUstep.conf file that is generated by ./configure.  It will list the
full paths to all the relevant GNUstep directories that would be used
if you install the software with that configuration.

   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. Some of these are described
below.

   With the GNUstep packages you can use various switches, such as
shared and debug, to control compilation. for example, "make shared=no
debug=yes" compiles using static libraries with debugging information.
(Make sure you use the same switches for every package you compile, and
also when you install).

1.2.1 Backend Bundles
---------------------

By default, the gnustep-make package specifies that GUI backends are
built as a bundle and loaded in at runtime. This allows one to switch
backends by simply redefining a user default. If you do not want this
behavior (for instance, if bundles do not work on your platform), it
can be disabled using

     --disable-backend-bundle

   in the arguments to configure.

1.2.2 Alternate Library Setup
-----------------------------

You can specify compilation of alternate libraries by using the
with-library-combo option.

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

   to compile with Apple's runtime on Darwin, for example. See the
DESIGN document for more examples of the variety of library combos.

1.2.3 Alternate Thread Library
------------------------------

You can specify compilation of an alternate thread library from the one
that is normally used (or if GNUstep does not know what your normal
library is) with the with-thread-lib option.

     ./configure --with-thread-lib="-L/usr/local/lib -lgthread -lglib"

   to use libgthread as your threading library. Note that the
Objective-C runtime (libobjc) must have a compatible threading backend
in order to use this threading library and you must set the appropriate
threading backend by hand in the GNUmakefile if you are using
gnustep-objc. If you also need to set compiler flags, use the CPPFLAGS
variable when calling configure:

     CPPFLAGS="-I/usr/local/include" ./configure --with-thread-lib="-L/usr/local/lib -lgthread -lglib"

1.2.4 Configuring for a non-flattened structure
-----------------------------------------------

GNUstep is normally configured to support a single target/combo. If you
are interested in supporting more than one target and/or combo, it's
possible to configure GNUstep to use a non-'flattened' directory
structure.  You do this by supplying the `--disable-flattened' argument
to configure.  You might also want to supply the
`--enable-multi-platform' option.

   In a flattened structure, files are stored at the top-level rather
than in a `$(GNUSTEP_CPU)/$(GNUSTEP_OS)/$(LIBRARY_COMBO)' subdirectory.

1.2.5 Configuring for a cross-compile target
--------------------------------------------

By default when you run configure, it assumes that you want to create
executables for the same host that you are compiling on; however, the
GNUstep makefile package has been designed to support cross-compiling
just as easily as normal compiling.  In order to add a cross-compile
target to the GNUstep makefile package, you must rerun configure for
that target and reinstall the makefile package.  By rerunning
configure, the appropriate target settings are determined, and
reinstalling the makefile package installs the appropriate files for
that target.  The target parameter is used to specify the target
platform for cross-compiling:

     ./configure --target=i386-mingw32
     make install

   GNUstep normally is configured to work with only one target. To work
with multiple targets, you'll need to add `--disable-flattened' and
`--enable-multi-platform' to the configure flags.  Files for the
different targets will not be overwritten when you configure and install
the make package several times.

     ./configure --disable-flattened --enable-multi-platform --target=i386-mingw32
     make install
     ./configure --disable-flattened --enable-multi-platform --target=sparc-solaris2.5
     make install
     ./configure --disable-flattened --enable-multi-platform --target=alpha-linux-gnu
     make install

1.3 Installation
================

After you configure the GNUstep makefile package, you can go straight
into installation (there is nothing to compile):

     make install

   After you have installed the GNUstep makefile package, there might
still be some minor administration to be performed, depending on your
configuration.

1.4 Setting up the GNUstep environment
======================================

GNUstep-make will install all programs and libraries in the directories
specified by the filesystem layout that you choose.

   In here we explain how to set up your environment so that the
operating system can find the programs and libraries in these
directories.

   The procedure depends on the type of layout (flattened or
non-flattened), and on the amount of advanced options that you want to
use.

1.4.1 Flattened (default) Setup
-------------------------------

In a flattened setup (the default unless you use the -disable-flattened
configure argument), you can use a simple setup where you just need to
make sure that the few program and library directories are found by the
shell/linker.

   Check the description of your filesystem in FilesystemLayouts to find
precise simplified instructions for your layout.

   In general, you need to your GNUSTEP_SYSTEM_TOOLS,
GNUSTEP_NETWORK_TOOLS and GNUSTEP_LOCAL_TOOLS to your PATH, and add
your GNUSTEP_SYSTEM_LIBRARIES, GNUSTEP_NETWORK_LIBRARIES and
GNUSTEP_LOCAL_LIBRARIES to your linker paths (which is /etc/ld.so.conf
on GNU/Linux).

   To build software, you also need to set GNUSTEP_MAKEFILES. (PS: This
requirement is likely to go away soon)

1.4.2 Non-Flattend (fat binary) Setup
-------------------------------------

(Advanced configuration)

   If the setup is non-flattened (ie, fat binary support is enabled)
programs and libraries will be installed in appropriate subdirectories
so that binaries for different machines/library-combos can coexist.
This is the case only if you configure gnustep-make with the option
-disable-flattened.

   In this case, the recommended solution for setting up the GNUstep
environment is to source the GNUstep.sh file.

     . /usr/GNUstep/System/Library/Makefiles/GNUstep.sh

   (change the path to be the path to your GNUstep.sh file on disk.
Common cases include /usr/GNUstep/System/Library/Libraries/Makefiles
and /usr/local/share/GNUstep/Makefiles)

   You can run this command in your shell every time, or you may want to
add the command to your shell startup scripts - either the ones for
your own user (for example, `.bash_profile' for Bash) or the ones for
the whole system (for example, `/etc/profile' on GNU/Linux).

   Please note that you need to execute this command both to build
software using gnustep-make and to run software installed by
gnustep-make.

1.5 Setting up your GNUstep User domain
=======================================

(Advanced configuration)

   The USER domain is generally expected to be in your home directory;
you can use the USER domain to install programs or libraries in your
home directory without affecting other users.

   If you want to access programs or libraries installed in your USER
domain, then you really need to source GNUstep.sh in all cases (both
flattened and non-flattened), as explained in the Non-Flattened section.

   If you want to change the filesystem layout of your USER domain
(without reinstalling gnustep-make or affecting other people's USER
domains), you can do so at runtime by creating a file called
~/.GNUstep.conf (this might have a different name if your filesystem
layout specifies otherwise).

   In that file, you can set all the GNUSTEP_USER_* variables set in
GNUstep.conf.  Check your GNUstep.conf for a full description.  Here is
an example in which all the GNUstep domain is moved into ~/Test/GNUstep
instead of ~/GNUstep:

     GNUSTEP_USER_DIR=Test/GNUstep

1.6 Having multiple gnustep-makes installed at the same time
============================================================

(Advanced configuration)

   You can install gnustep-make multiple times in different directories
by using a different config file for each.  But if you do, then you
must make sure that you can easily switch the operating system paths
from one installation to the other.  An easy way to do this is to
configure your GNUstep by using GNUstep.sh as explained in the
non-flattened instructions.

   Your default gnustep-make installation is the one described in the
default GNUstep.conf file for the system; on GNU/Linux this is
`/etc/GNUstep/GNUstep.conf'.  You can create a second one that uses a
different config file; for example:

     ./configure --prefix=/opt/mytest --with-config-file=/etc/GNUstep-mytest.conf

   When you install, this second instance of gnustep-make will reside in
`/opt/mytest', and have `/etc/GNUstep-mytest.conf' as config file.

   To use this second installation instead of the first one, you only
need to set the GNUSTEP_CONFIG_FILE variable to point to the next
config file and source GNUstep.sh:

     export GNUSTEP_CONFIG_FILE=/etc/GNUstep-mytest.conf
     . /opt/mytest/System/Library/Makefies/GNUstep.sh

   To stop using a GNUstep installation, reset your GNUstep environment
with the GNUstep-reset.sh script and destroy the variable
GNUSTEP_CONFIG_FILE -

     . /opt/mytest/System/Library/Makefies/GNUstep-reset.sh
     unset GNUSTEP_CONFIG_FILE

   After this, you are ready to start using a new one (by setting a new
GNUSTEP_CONFIG_FILE and then sourcing the GNUstep.sh of the new one).