install.texi

@node Top, Introduction, (dir), (dir)
@chapter GNUstep makefile package installation

@menu
* Introduction::                
* Configuration::               
* Installation::                
* Setup::                       
@end menu

@node Introduction, Configuration, Top, Top
@section 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
@url{http://www.gnustep.org}.

Quick installation instructions:

@example
./configure
make
make install
@end example

This will use the default 'FHS' filesystem layout rooted in /usr/local
(in other words, all of GNUstep will end up installed into /usr/local
in a Unix fashion).  Another popular option is

@example
./configure --with-layout=gnustep
make
make install
@end example

which will use the GNUstep filesystem (in other words, all of GNUstep
will end up installed into /usr/GNUstep using a GNUstep-tailored
filesystem layout).

To make and install the documentation:

@example
cd Documentation
make
make install
@end example

@node Configuration, Installation, Introduction, Top
@section 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:

@example
./configure
@end example

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

@example
./configure --with-layout=fhs
@end example

which installs GNUstep in /usr/local using the FHS layout (that is,
/usr/local/bin, /usr/local/lib, etc).  Another popular option is
'--with-layout=gnustep' which installs gnustep-make into a GNUstep
layout based on /usr/GNUstep (inside /usr/GNUstep/System,
/usr/GNUstep/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,

@example
./configure --prefix=/opt/gnustep
@end example

If you're confused and want to see exactly what directories will be
used for a certain choice of ./configure flags, you can check the
output of ./configure or even 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

@example
./configure --help
@end example

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

@menu
* Backend Bundles::             
* Alternate Libraries::         
* Alternate Thread Library::    
* Flat Structure::              
* Cross-Compiling::             
@end menu

@node Backend Bundles, Alternate Libraries, Configuration, Configuration
@subsection 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

@example
--disable-backend-bundle
@end example

in the arguments to configure.

@node Alternate Libraries, Alternate Thread Library, Backend Bundles, Configuration
@subsection Alternate Library Setup

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

@example
./configure --with-library-combo=apple-gnu-gnu
@end example

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

@node Alternate Thread Library, Flat Structure, Alternate Libraries, Configuration
@subsection 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. 

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

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:

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

@node Flat Structure, Cross-Compiling, Alternate Thread Library, Configuration
@subsection 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 @code{--disable-flattened} argument to configure.
You might also want to supply the @code{--enable-multi-platform} option.

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

@node Cross-Compiling,  , Flat Structure, Configuration
@subsection 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:

@example
./configure --target=i386-mingw32
make install
@end example

GNUstep normally is configured to work with only one target. To work
with multiple targets, you'll need to add @code{--disable-flattened}
and @code{--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.

@example
./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
@end example

@node Installation, Setup, Configuration, Top
@section Installation

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

@example
make install
@end example

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

@node Setup,  UserDomainSetup, Installation, Top
@section 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.

@menu
* Flattened::
* Non-Flattened::           
* UserDomainSetup::
* MultipleInstallations::
@end menu

@node Flattened, Non-Flattened, Setup, Setup
@subsection 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)

@node Non-Flattened, , Flattened, Setup
@subsection 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.

It is recommended that this option is used with the GNUstep filesystem
layout; and that the GNUstep environment is set up by sourcing the
GNUstep.sh file.

@example
. /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
@end example

(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, @file{.bash_profile} for Bash) or the ones
for the whole system (for example, @file{/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.

@node UserDomainSetup, MultipleInstallations, Setup, Setup
@section 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:

@example
GNUSTEP_USER_DIR=Test/GNUstep
@end example

@node MultipleInstallations, , UserDomainSetup, Setup
@section 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
@file{/etc/GNUstep/GNUstep.conf}.  You can create a second one that
uses a different config file; for example:

@example
./configure --prefix=/opt/mytest --with-config-file=/etc/GNUstep-mytest.conf --with-layout=gnustep
@end example

When you install, this second instance of gnustep-make will reside in
@file{/opt/mytest}, and have @file{/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:

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

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

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

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

@bye