NAME

       library-combo - GNUstep Make support for cross-compilation.

DESCRIPTION

       This  manual  page  is about cross-compilation and fat binaries. Fat binaries are packages
       that you can supply which  contain  more  the  one  binary  of  your  program  (e.g.  your
       application). So you can support multiple platforms with a single package.

       To  support  this  your system has to be built in a non-flattened way. Meaning that during
       the installation of gnustep-make you should  have  selected  --disable-flattened  and  the
       types  of  library  combinations  you  want  to  support, through the --with-library-combo
       option. With library combinations we mean the Objective-C runtime, the Foundation  library
       and the Application library. For more details about this see the LIBRARY-COMBO section.

       If  you installed your GNUstep system in a non-flattened way all system dependend binaries
       are installed in subdirectories with  cpu/os/library-combo  information.  That  means  for
       instance     that     the     gnustep-base     library     will     be     installed    in
       Library/Libraries/ix86/linux/gnu-gnu-gnu/ when you are on an  Intel  x86  system,  running
       linux with the GNU runtime for Objective-C and you installed GNUstep.

       For  each  and  every  library-combo  that  you  want  to  support  you  should create the
       environment through gnustep-make, because it installs a different config.make  to  support
       its own CC, OPTFLAGS, etc. flags.

   LIBRARY-COMBO
       An  important  issue is to let to a package the ability to deal with various libraries and
       configurations available now:

       Objective-C runtimes
              In the Objective-C world there are three major  runtimes:  the  NeXT  runtime,  the
              Apple  runtime  and  the  GNU  runtime  (both  with  and without garbage collection
              enabled). They are different in several respects and  a  program  or  library  that
              works at the runtime level should be aware of them.

       Foundation libraries
              There are several Foundation libraries an application or tool can be written on top
              of: NeXT Foundation library which runs on NeXTStep/OPENSTEP systems,  gnustep-base,
              libFoundation and Apple Cocoa system.

       Graphical interfaces
              Until now three libraries provide or try to provide OpenStep compliant systems: the
              AppKit from NeXT, gnustep-gui and Cocoa from Apple.

       If a program wants to work with all the possible combinations  it  will  have  to  provide
       different  binaries for each combination because it's not possible to have a tool compiled
       for NeXT Foundation that runs with gnustep-base or vice-versa. To summarize, a program can
       be compiled for these combinations:

       Objective-C runtime
              nx  (for  NeXT),  gnu  (for  GNU  without  garbage collection), gnugc (for GNU with
              garbage collection), apple (for Apple)

       Foundation library
              nx (for NeXT), gnu (for gnustep-base), fd (for  libFoundation),  apple  (for  Apple
              Cocoa)

       GUI library
              nx (for NeXT), gnu (for gnustep-gui), apple (for Apple Cocoa)

       We'll  denote  the  fact that an application was compiled for a certain combination of the
       above values by using the abbreviations of the different  subsystems  and  placing  dashes
       between  them.  For  example an application compiled for NeXT Foundation using NeXT AppKit
       will have the compile attribute nx-nx-nx. An application compiled for Apple Cocoa with the
       GNU  compiler  for  Objective-C  gnu-apple-apple and another one compiled for gnustep-base
       using gnustep-gui under Unix will be denoted by gnu-gnu-gnu. Here is a list of some of the
       possible combinations:

          Runtime     Foundation     GUI
            nx            nx         nx
            nx            fd         gnu
            gnu           gnu        gnu
            gnu           fd         gnu
           gnugc          gnu        gnu
           gnugc          fd         gnu
           apple         apple       apple
           apple          gnu        gnu

       Note that one can choose his/her own packages to build; it is not required to have all the
       packages installed on the system. Not having all of them installed limits only the ability
       to build and distribute binaries for those missing combinations.

   DIRECTORY STRUCTURE
       For  cross-compilation  in a non-flattened directory structure is recommended, so that you
       can store on the same directory structure binaries for different machines.   The  standard
       GNUstep  filesystem  layout  is  normally used when a non-flattened directory structure is
       being used; this is  obtained  with  the  --with-layout=gnustep  option  when  configuring
       gnustep-make.   The  entire  GNUstep  installation is then created inside /usr/GNUstep (or
       another directory if you use the  --prefix=...   option  when  configuring  gnustep-make).
       Directories  that  contain  binaries (such as the Libraries directory) inside /usr/GNUstep
       are then set up to support fat binaries as follows:

       Libraries/
         ix86/
           linux-gnu/
             gnu-gnu-gnu/
                 libgnustep-base.so
                 libgnustep-gui.so
             gnu-fd-gnu/
                 libFoundation.so
                 libgnustep-gui.so

       To allow the right libraries to be found, you  need  to  source  GNUstep.sh  before  using
       GNUstep, and you need to start up your application by using openapp, which will locate the
       right binary for your library combo.

   BUILDING FOR A LIBRARY-COMBO
       The makefile package will allow the user to choose between different library combinations.
       To specify a combination you want to compile for just type:

         $ make library_combo=library-combo

       For   instance   if  you  want  to  choose  to  compile  using  the  GNUstep's  Foundation
       implementation and use the GNUstep GUI library on a GNU/Linux  machine  you  can  do  like
       this:

         $ make library_combo=gnu-gnu-gnu

       If  your project requires running configure before compiling there are two issues you have
       to keep in mind. 'configure' is used to determine the existence of particular header files
       and/or  of  some  specific functionality in the system header files. This thing is usually
       done by creating a config.h file which contains a couple of defines  like  HAVE_...  which
       say if the checked functionality is present or not.

       Another  usage  of  configure  is  to determine some specific libraries to link against to
       and/or some specific tools. A typical  GNUstep  program  is  not  required  to  check  for
       additional  libraries  because  this  step  is  done  by  the time the makefile package is
       installed. If the project still needs to check for additional libraries and/or tools,  the
       recommended  way is to output a config.mak file which is included by the main GNUmakefile,
       instead of using Makefile.in files which are modified by configure.  The  reason  for  not
       doing  this  is to avoid having the makefiles contain target dependencies like above, this
       way keeping only one makefile instead of several for each target machine.

       The makefile package is written for GNU  make  because  it  provides  some  very  powerful
       features  that save time both in writing the package but also at runtime, when you compile
       a project.

   BUILDING FOR AN ARCHITECTURE
       In order to build a  project  for  multiple  architectures  you'll  need  the  development
       environment  for  the  target  machine  installed  on your machine. This includes a cross-
       compiler together with all the additional tools like the assembler and linker, the  target
       header files and all the libraries you need.

       The GNUstep makefile package should be able to compile and link an application for another
       machine just by typing

         $ make target=target-triplet

       where target-triplet is the canonical system name as reported by config.guess.

   USING A LIBRARY-COMBO
       When you use library-combos, you must always source GNUstep.sh.  That allows you to switch
       library  paths  on  the  fly.  If  you want to switch to a different library-combo in your
       shell, and if you are using bash, it's common to first source  GNUstep-reset.sh  to  reset
       all  shell  variables, then to source GNUstep.sh again. Let's assume we use gnu-gnu-gnu as
       our current LIBRARY_COMBO and we want to switch to gnugc-gnu-gnu, then we would use:

         . /usr/GNUstep/System/Library/Makefiles/GNUstep-reset.sh
         export LIBRARY_COMBO=gnugc-gnu-gnu
         . /usr/GNUstep/System/Library/Makefiles/GNUstep.sh

SEE ALSO

       debugapp(1), GNUstep(7), gnustep-config(1), openapp(1)

HISTORY

       Work on gnustep-make started in 1997 by Scott Christley <scottc@net-community.com>.

       Version 2.0.0 of gnustep-make introduced many changes with previous  releases,  which  was
       mainly the work of Nicola Pero <nicola.pero@meta-innovation.com>

AUTHORS

       This  man-page  was  written  by  Dennis  Leeuw  <dleeuw@made-it.com>  based on the DESIGN
       document from the gnustep-make source tree.

CREDITS

       The DESIGN document was written by Ovidiu Predescu.

       This work  could  only  be  as  is  due  to  the  notes  and  corrects  from  Nicola  Pero
       <nicola.pero@meta-innovation.com>.

COPYRIGHT

       Copyright (C) 2007 Free Software Foundation, Inc.

       Copying  and distribution of this file, with or without modification, are permitted in any
       medium without royalty provided the copyright notice and this notice are preserved.