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. After installing this package, install ffcall and any other libraries that GNUstep may need (see the GNUstep-HOWTO). Then install gnustep-base.

When you configure additional libraries, make sure you use the same configuration options as with gstep-make.

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

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 a root directory.  If the GNUSTEP_SYSTEM_ROOT environment variable is set then configure will use its value as the root directory.  You can also specify the root directory when you run configure with the prefix paramter; the following command makes /usr/local/GNUstep the root directory:

     ./configure --prefix=/usr/local/GNUstep

If you do not have the GNUSTEP_SYSTEM_ROOT environment variable set and you do not specify a root directory when running configure, then configure will use /usr/GNUstep as the default root directory.

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

to compile with Apple's (NexT'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 (gnustep-objc) 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 when compiling gnustep-objc. If you also need to set compiler flags, use the CFLAGS variable when calling configure:

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

Warnings for deprecated #import
-------------------------------

The #import directive, often found in legacy Objective-C code from the NeXTstep and OpenStep era (and more recently on code from the Apple MacOS X Cocoa environment), is deprecated.  You should use #include instead whenever possible, and even if you use #import, you should protect all your headers against multiple inclusions.  The GCC compiler automatically emits a warning whenever you use #import.  For political and historical reasons (basically for fear of annoying legacy and MacOS X users), these warnings are disabled by gnustep-make.  But if you are not a legacy (/MacOS X) user and/or you want to make sure your Objective-C code is not using any deprecated feature, you should configure gnustep-make with --disable-import:

     ./configure --disable-import

If you are a legacy or MacOS X user, and wonder why #import is deprecated, please search the web and the GCC and GNUstep mailing list archives - there are very precise and sound technical reasons.

Configuring the GNUstep makefile package 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

Note that configuring and installing for a cross-compile target does not eliminate or overwrite the files for any other targets that you may have configured.  So if you wish to setup the GNUstep makefile package for multiple targets then just perform the above steps multiple times.

     ./configure --target=i386-mingw32
     make install
     ./configure --target=sparc-solaris2.5
     make install
     ./configure --target=alpha-linux-gnu
     make install

Configuring the GNUstep makefile package for a flattened structure
------------------------------------------------------------------

On systems where you know you are only interested in supporting a single operating system, cpu type, and library combination, it's possible to configure GNUstep to use a 'flattened' directory structure. You do this by supplying the '--enable-flattened' argument to configure.

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

You lose a lot of versatility with this layout, but it's simpler (less intimidating) for naive users to handle.

Installation
============

After you configure the GNUstep makefile package, then you need to compile the programs that come with the package.  Currently there is only a single C program which needs to be compiled; all of the other files are either shell scripts or makefile fragments, so you can compile and install the makefile package in one step with:

     make install

After you have installed the GNUstep makefile package, there is still some minor administration to be performed.  Based upon whether you are setting up the GNUstep environment for a single user or all users on your system, perform the appropriate step below.

Setting up the GNUstep
======================

Setting up the GNUstep environment for all users
------------------------------------------------

The GNUstep environment and thus usage of the makefile package is based almost solely upon the GNUSTEP_SYSTEM_ROOT environment variable.  So essentially the setup involved is to make sure that the variable is defined for all users.  The GNUstep.sh file within the makefile package contains all of the environment variable settings required, so you want to call that shell.  Some systems, like GNU/Linux have an /etc/profile.d directory where scripts can be executed automatically. Just copy GNUstep.sh to this directory for it to work. For other UNIX systems, there might be a system wide script that everyone uses, such as /etc/bashrc, where you could add lines similar to these:

     # Setup for the GNUstep environment
     . /usr/GNUstep/System/Makefiles/GNUstep.sh

This will source in the GNUstep.sh file and set the environment variables; thus making them available for all users. Before executing this script, you can setup a default path for scripts in the makefiles package to use for searching for tools and apps by defining the variable GNUSTEP_PATHPREFIX_LIST (and exporting it). By default, it's set to

     $GNUSTEP_USER_ROOT:$GNUSTEP_LOCAL_ROOT:$GNUSTEP_SYSTEM_ROOT

which might look something like this:

     ~/GNUstep:/usr/GNUstep/Local:/usr/GNUstep/System

when all is done.

NB. This path is NOT used by GNUstep tools and applications themselves ... they use a standard function NSSearchPathForDirectoriesInDomains() to locate files instead.

Setting up the GNUstep environment for a single user
----------------------------------------------------

The GNUstep environment and thus usage of the makefile package is based almost solely upon the GNUSTEP_SYSTEM_ROOT environment variable. So essentially the setup involved is to make sure that the variable is defined for the user.  The GNUstep.sh file within the makefile package contains all of the environment variable settings required, so you want to call that shell when the user logs in to the system.  Most shells have some file that you read upon login, for example the BASH shell reads the .bash_profile file in the user's home directory.  So you can add the following lines to that file:

     # Setup for the GNUstep environment
     if [ -f $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.sh ]; then
       . $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.sh
     fi

This will source in the GNUstep.sh file and set the environment variables; thus making them available for the user.

The GNUstep.sh file will set up GNUSTEP_USER_ROOT to the GNUstep subdirectory of the users home directory by default.  This may be overridden by a user providing a .GNUsteprc file in their home directory.

     # Set up to store GNUstep files directly in my home directory
     GNUSTEP_USER_ROOT=~