err.no Git - sope/blob - libFoundation/INSTALL.txt

   1 # $Id: INSTALL.txt,v 1.2 2004/07/15 17:32:19 helge Exp $
   2
   3 UPDATE: the OGo fork of libFoundation can only be build with gstep-make!
   4
   5 libFoundation can be built in two different ways:
   6
   7 1. as a standalone library.
   8 2. as the Foundation library in the GNUstep environment, instead of
   9 gnustep-base.
  10
  11 In both cases you can build the library with support for the Boehm's
  12 garbage collector.
  13
  14 To be able to build libFoundation you need either GCC 2.8.x or EGCS
  15 1.1. Older versions of GCC with the Objective-C patches are
  16 obsolete. You'll also need the GNUmake to compile libFoundation.
  17
  18
  19
  20 Which way to build libFoundation?
  21 =================================
  22
  23 People that don't want to use the library in the GNUstep environment
  24 should build it in the standalone mode. In this mode you're not
  25 required to specify any environment variables in order to make the
  26 library work. In the GNUstep environment you will have to specify the
  27 GNUSTEP_SYSTEM_ROOT in order for the library to find the resource
  28 files it needs.
  29
  30 For example applications like CGI programs that use libFoundation may
  31 want to use the standalone library as they don't have to setup a
  32 special environment.
  33
  34 People that want to use libFoundation as the Foundation library for
  35 GNUstep should build it for the GNUstep environment.
  36
  37 If you need libFoundation in both types of applications you can
  38 configure, compile and install it in both ways. The two versions of
  39 the library install their header files and libraries in different
  40 places and they do not interfere with each other.
  41
  42 IMPORTANT: If you compile libFoundation in the standalone mode be sure
  43 you don't have the gnustep-base headers in the include path or you'll
  44 encounter problems because the compiler will get them instead.
  45
  46
  47
  48 Boehm's garbage collector support
  49 =================================
  50
  51 Starting with 0.9.0, libFoundation supports the Boehm's garbage
  52 collector. You must have the Boehm's garbage collector support
  53 installed before building libFoundation.
  54
  55 Here are the steps you need to do to install the Boehm's garbage
  56 collector:
  57
  58 1. Download the package. The library was tested using the 4.12
  59 version, previous versions may work but they were not tested. The
  60 official site is:
  61
  62     http://reality.sgi.com/employees/boehm_mti/
  63
  64 Read carefully the Makefile and add the flags specific to your
  65 system. Don't add the -DNO_SIGNALS to the list of flags, as
  66 libFoundation uses signals internally. After you're sure everything is
  67 fine with the makefile, type 'make' followed by 'make test' which
  68 briefly tests the collector.
  69
  70 The next step is to install the collector. The makefile doesn't have
  71 an install target, so copy the gc.h and gc_typed.h files to
  72 /usr/local/include or to whatever location you prefer. Then copy the
  73 gc.a library into /usr/local/lib and rename it to libgc.a. This step
  74 is important, otherwise the configure script in libFoundation and the
  75 test programs you'll write will not work.
  76
  77 2. You need to compile a special version of the compiler which adds
  78 support for the Boehm's collector to the GNU runtime.
  79
  80 The currently supported compilers are GCC 2.8.1 and EGCS 1.1. The
  81 patches are contained in the libFoundation's distribution. Apply the
  82 appropriate patch for your compiler. Then configure the compiler using
  83
  84         ./configure --enable-objc-gc
  85
  86 Add whatever arguments you might need to the configure. Then compile
  87 the compiler following the instructions in the INSTALL file included
  88 with the compiler.
  89
  90 3. Configure libFoundation to be compiled with Boehm's GC support. To
  91 do this add --with-gc to the specific flags for your system. At this
  92 point you also have to decide in which environment you want to build
  93 libFoundation.
  94
  95 For an impatient user, just type the following if you want to build
  96 the library in the GNUstep environment.
  97
  98         ./configure --with-gnustep --with-gc
  99
 100 Or run the following if you want to build the library as a standalone
 101 library.
 102
 103         ./configure --with-gc
 104
 105 Configuring the library with support for Boehm's garbage collector
 106 does not imply that the built library will be automatically using the
 107 collector. Actually you can build two versions of the library, one
 108 that is garbage collected and another one that uses the normal
 109 reference counting mechanism.
 110
 111 To build the garbage collected library type:
 112
 113         make gc=yes
 114
 115 To build the normal library type in the OpenStep compatibility mode:
 116
 117         make
 118
 119 If you're building in the GNUstep environment you may want to add
 120 additional options like debug=yes.
 121
 122
 123
 124 Building libFoundation
 125 ======================
 126
 127 If you want to build the library with support for Boehm's garbage
 128 collector, please read the above part first.
 129
 130 1. If you want to build the library in the GNUstep environment, run
 131 the configure script with the --with-gnustep argument, otherwise just
 132 omit it:
 133
 134    ./configure --with-gnustep
 135
 136 If you need support for Boehm's garbage collector, just add the
 137 --with-gc flag:
 138
 139    ./configure --with-gnustep --with-gc
 140
 141 If you're building on a NeXTSTEP/OPENSTEP system read the note at the
 142 end of this file.
 143
 144 2. Run `make' to compile the package. If you're building in the
 145 GNUstep environment add any additional options you might need. For
 146 example if you want debugging and/or profile information to be
 147 included in the library:
 148
 149    make debug=yes [profile=yes]
 150
 151 where [profile=yes] means that profile=yes is an optional
 152 argument. Read the GNUstep's makefile package documentation to find
 153 out more about compiling in the GNUstep environment.
 154
 155 NOTE: In the standalone environment, debug=yes and profile=yes
 156 arguments have no meaning.
 157
 158 To build the garbage collected library add the gc=yes argument to the
 159 list of arguments you pass to make:
 160
 161    make gc=yes
 162
 163 This works with both the standalone and GNUstep environments.
 164
 165 3. Before you install the library you may want to set up the locales
 166 for your site. To do this go to the Resources/Defaults directory and
 167 modify the NSGlobalDomain.plist file as you wish. This file specifies
 168 the language and the time zone name of your site.
 169
 170 If your language is not included in the supported languages, you can
 171 create a new one using as model one of the existing language files.
 172
 173 The timezones are specified in the Resources/TimeZoneInfo
 174 directory. You should choose as time zone the one that coresponds to
 175 your geo-political region.
 176
 177 4. Type `make install' to install the library, the headers and the
 178 public binaries. Add the debug and profile arguments to the make
 179 process if you want that specific version to be installed:
 180
 181    make [debug=yes] [profile=yes] [gc=yes] install
 182
 183 5. To try out if the package works fine on your machine, you can run
 184 the tests from the FoundationTestsuite directory. All the tests are
 185 written using the DejaGnu testing framework. So if you don't have
 186 installed the package on your machine you have to install it before
 187 trying out these tests. Before compiling the FoundationTestsuite you
 188 will have to install the ObjCTest package that comes with the
 189 libFoundation's distribution.
 190
 191 The classes that intimately depend on the specific machine are
 192 NSMethodSignature and NSInvocation. If you get crashes when you run
 193 the NSInvocation and NSMethodSignature tests you have to look to the
 194 sources for these classes in the Foundation directory and to the files
 195 dependent on the target machine in config directory.
 196
 197 6. You can remove the object files and binaries using the `make clean'
 198 command. You can also remove all the generated files (the files
 199 generated by configure etc) with `make distclean'.
 200
 201
 202
 203 Notes for NeXTSTEP/OPENSTEP users
 204 =================================
 205
 206 If you're compiling the package on a NeXT system you can compile it to
 207 use with either the GNU or the NeXT Objective-C runtime. You can
 208 specify this by setting the OBJC_RUNTIME variable. For example:
 209
 210    OBJC_RUNTIME=gnu ./configure
 211
 212 will compile the package using the GNU runtime. Similarly, you can do:
 213
 214    OBJC_RUNTIME=next ./configure
 215
 216 In the last case you will be able to link the package with code
 217 compiled with the native compiler.
 218
 219 If you don't specify the OBJC_RUNTIME flag the code will be compiled
 220 with the default option for runtime. It is either -fnext-runtime on
 221 NeXT systems or -fgnu-runtime on the other machines.
 222
 223 You can also specify the compiler using the CC variable. The package
 224 has been compiled using the 2.6.3, 2.7.0 and 2.7.2.1 gcc versions,
 225 depending on machine. If you compile the package with other versions
 226 than 2.7.2.1 you will need to adapt yourself the Objective-C patch to
 227 the compiler sources. GCC 2.8.x and EGCS 1.0.x have not been tested.
 228
 229 Compiling the package on NeXT release 3.3 with the native compiler
 230 won't work. The native compiler doesn't support nested functions and
 231 variable arguments macros.
 232
 233 Starting with the 0.9.0 version the NeXTSTEP systems are no longer
 234 supported due to compiler and debugger problems on these systems. If
 235 somebody is willing to send us patches for NeXTSTEP, we'll incorporate
 236 them in the distribution.
 237
 238
 239
 240
 241 ! Local variables:
 242 ! mode: indented-text
 243 ! End: