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

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

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

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.

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.

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"

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.

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

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.

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.

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)

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.

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

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