<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.0//EN" "http://www.gnustep.org/gsdoc-1_0_0.xml">
<gsdoc base="Base">
  <head>
    <title>GNUstep Base</title>
    <author name="Richard Frith-Macdonald">
      <email address="rfm@gnu.org"/>
      <url url="http://www.gnustep.org/developers/whoiswho.html"/>
    </author>
    <version>$Revision: 1.7 $</version>
    <date>$Date: 2003/04/04 04:02:52 $</date>
  </head>
  <body>
    <chapter>
      <heading>Base</heading>
      <p>
	The GNUstep base library is a free software package implementing
        the API of the OpenStep Foundation Kit (tm), including later
	additions.  This documentation package describes the core of the
	base library, for documentation on additional classes, see the
	BaseAdditions documentation package.
      </p>
      <index scope="project" type="title" />
      <section>
	<heading>Compatibility</heading>
	<p>
	  GNUstep is generally compatible with the OpenStep specification and
	  with recent developments of the MacOS (cocoa) API.  Where MacOS
	  deviates from the OpenStep API, GNUstep generally attempts to
	  support both versions.  In some cases the newer MacOS APIs are
	  incompatible with OpenStep, and GNUstep usually supports the richer
	  version. See the
	  <uref url="OpenStepCompliance.html">OpenStep Compliance</uref> section
	  for more information on OpenStep Compliance.
	</p>
	<p>
	  In order to deal with compatiblity issues, GNUstep uses two
	  mechanisms - it provides conditionally compiled sections of
	  the library header files, so that software can be built that
	  will conform strictly to a particular API, and it provides
	  user default settings to control the behavior of the library
	  at runtime.
	</p>
	<subsect>
	  <heading>Conditional compilation</heading>
	  <p>
	    Adding an option to a makefile to define one of the following
	    preprocessor constants will modify the API visible to software
	    being compiled -
	  </p>
	  <deflist>
	    <term>NO_GNUSTEP</term>
	    <desc>
	      GNUstep specific extensions to the OpenStep and MacOS cocoa
	      APIs are excluded from the headers.
	    </desc>
	    <term>STRICT_MACOS_X</term>
	    <desc>
	      Only methods and classes that are part of the MacOS cocoa
	      API are made available in the headers.
	    </desc>
	    <term>STRICT_OPENSTEP</term>
	    <desc>
	      Only methods and classes that are part of the OpenStep
	      specification are made available in the headers.
	    </desc>
	  </deflist>
	  <p>
	    <em>NB</em> These preprocessor constants are used in
	    <em>developer code</em> (ie the code that users of GNUstep write)
	    rather than by the GNUstep software itsself.  They permit a
	    developer to ensure that he/she does not write code which depends
	    upon API not present on other implementations (in practice,
	    MacOS-X or some old OPENSTEP systems).<br />
	    The actual GNUstep libraries are always built with the full
	    GNUstep API in place, so that the feature set is as consistent
	    as possible.
	  </p>
	</subsect>
	<subsect>
	  <heading>User defaults</heading>
	  <deflist>
	    <term>GSLogSyslog</term>
	    <desc>
	      <p>
		Setting the user default <code>GSLogSyslog</code> to
		<code>YES</code> will cause log/debug output to be sent to
		the syslog facility (on systems which support it), rather
		than to the standard error stream.  This is useful in
		environments where stderr has been re-used strangely for
		some reason.
	      </p>
	    </desc>
	    <term>GSMacOSXCompatible</term>
	    <desc>
	      <p>
		Setting the user default <code>GSMacOSXCompatible</code> to
		<code>YES</code> will cause MacOS compatible behavior to be
		the default at runtime.  This default may however be overridden
		to provide more fine grained control of system behavior.
	      </p>
	    </desc>
	    <term>GSOldStyleGeometry</term>
	    <desc>
	      <p>
		Specifies whether the functions for producing strings
		describing geometric structures (NSStringFromPoint(),
		NSStringFromSize(), and NSStringFromRect()) should produce
		strings conforming to the OpenStep specification or to
		MacOS-X behavior.  The functions for parsing those strings
		should cope with both cases anyway.
	      </p>
	    </desc>
	    <term>GSSOCKS</term>
	    <desc>
	      <p>
		May be used to specify a default SOCKS5 server (and optionally
		a port separated from the server by a colon) to which tcp/ip
	        connections made using the NSFileHandle extension methods
		should be directed.<br />
		This default overrides the SOCKS5_SERVER and SOCKS_SERVER
		environment variables.
	      </p>
	    </desc>
	    <term>Local Time Zone</term>
	    <desc>
	      <p>
		Used to specify the name of the timezone to be used by the
		<ref type="class" id="NSTimeZone">NSTimeZone</ref> class.
	      </p>
	    </desc>
	    <term>NSWriteOldStylePropertyLists</term>
	    <desc>
	      <p>
		Specifies whether text property-list output should be in
		the default MacOS-X format (XML), or in the more human
		readable (but less powerful) original OpenStep format.
	      </p>
	      <p>
		Reading of property lists is supported in either format,
		but <em>only</em> if GNUstep is built with the libxml
		library (which is needed to handle XML parsing).
	      </p>
	      <p>
		NB. MacOS-X generates illegal XML for some strings - those
		which contain characters not legal in XML.  GNUstep always
		generates legal XML, at the cost of a certain degree of
		compatibility.  GNUstep XML property lists use a backslash
		to escape illegal chatracters, and consequently any string
		containing either a backslash or an illegal character will
		be written differently to the same string on MacOS-X.
	      </p>
	    </desc>
	    <term>NSLanguages</term>
	    <desc>
              <p>
              An array of strings that lists the users prefered languages,
              in order or preference. If not found the default is just 
              English.
              </p>
	    </desc>
	  </deflist>
	</subsect>
	<subsect>
	  <heading>Environment variables</heading>
	  <p>
	    There are some environment variables used by GNUstep base, where
	    there would be problems onbtaining data from the defaults asystem.
	  </p>
	  <deflist>
	    <term>CRASH_ON_ABORT</term>
	    <desc>
	      <p>
		The default exception handler will either cause the program to
		simply terminate, or to crash - leaving a core dump.  The
		standard behavior is to leave a core dump if the library was
		built for debugging, and to simply exit if it was not.
	      </p>
	      <p>
		The CRASH_ON_ABORT environment variable can be used to
		override this behavior.  If this is defined to <em>NO</em>,
		<em>FALSE</em>, or <em>0</em> then the program will simply
		exit when an exception occurs.  Any other value of the
		variable will cause the program to generate a core dump.
	      </p>
	    </desc>
	    <term>GNUSTEP_STRING_ENCODING</term>
	    <desc>
	      <p>
		This is used to specify the default encoding for 8-bit
		strings.  It defaults to NSISOLatin1StringEncoding, but
		may be any of the 8-bit encodings supported by your system
		(excluding multi-byte encodings).
	      </p>
	    </desc>
	    <term>GNUSTEP_HOST_CPU</term>
	    <desc>
	      <p>
		Used in place of GNUSTEP_TARGET_CPU if the other is missing.
	      </p>
	    </desc>
	    <term>GNUSTEP_HOST_DIR</term>
	    <desc>
	      <p>
		Used in place of GNUSTEP_TARGET_DIR if the other is missing.
	      </p>
	    </desc>
	    <term>GNUSTEP_HOST_OS</term>
	    <desc>
	      <p>
		Used in place of GNUSTEP_TARGET_OS if the other is missing.
	      </p>
	    </desc>
	    <term>GNUSTEP_LOCAL_ROOT</term>
	    <desc>
	      <p>
		Used to specify the GNUstep root directory for local
		(non-system) resources.  Typically all locally produced
		or contributed software is installed relative to this.
	      </p>
	    </desc>
	    <term>GNUSTEP_NETWORK_ROOT</term>
	    <desc>
	      <p>
		Used to specify the GNUstep root directory for local
		(non-system) resources that are intended to be shared
		across a local network.  Typically this is an NFS exported
		directory shared by many machines.  It provides an
		alternative to GNUSTEP_LOCAL_ROOT.
	      </p>
	    </desc>
	    <term>GNUSTEP_SYSTEM_ROOT</term>
	    <desc>
	      <p>
		Used to specify the GNUstep system root directory ... all
		system libraries, tools, applications, headers, resources
		in general are located relative to this.
	      </p>
	    </desc>
	    <term>GNUSTEP_USER_ROOT</term>
	    <desc>
	      <p>
		This environment variable, commonly set by the make system,
		is <strong>not</strong> used by GNUstep programs.  Instead
		values from <code>.GNUsteprc</code> are used (see later).
	      </p>
	    </desc>
	    <term>GNUSTEP_TARGET_CPU</term>
	    <desc>
	      <p>
		Overrides the default value of the machine (hardware)
		name used on this system.
	      </p>
	    </desc>
	    <term>GNUSTEP_TARGET_DIR</term>
	    <desc>
	      <p>
		Overrides the default path used to locate subdirectories
		for GNUstep binaries withing bundles and applications.
		This is normally equivalent to a path made up of the
		GNUSTEP_TARGET_CPU and GNUSTEP_TARGET_OS
	      </p>
	    </desc>
	    <term>GNUSTEP_TARGET_OS</term>
	    <desc>
	      <p>
		Overrides the default value of the operating system
		name used on this system.
	      </p>
	    </desc>
	    <term>GNUSTEP_TZ</term>
	    <desc>
	      <p>
		Used to specify the timezone to be used if there is no
		timezone specified in the user defaults system.
		The preferred
		mechanism is to use the 'Local Time Zone' value from the
		user defaults system.
	      </p>
	    </desc>
	    <term>HOMEDRIVE</term>
	    <desc>
	      <p>
		Used on windoze to locate the home directory.
	      </p>
	    </desc>
	    <term>HOMEPATH</term>
	    <desc>
	      <p>
		Used on windoze to locate the home directory.
	      </p>
	    </desc>
            <term>LANGUAGES</term>
            <desc>
              <p>
                If there is no NSLanguages user default set, and there is
		no language infromation available in the native system locale
		mechanism, then this environment variable is used to provide
		a list of the languages that the user prefers to use.
		languages listed in this variable must be separated by
		semicolons.
              </p>
            </desc>
            <term>LOGNAME</term>
            <desc>
              <p>
                This is used as the default value for the current user
		(as returned by the NSUserName() functions).  If it is not
		specified, or contains an illegal value, other methods are
		used to get the user name.
              </p>
            </desc>
            <term>LIBRARY_COMBO</term>
            <desc>
              <p>
                Used to override the default value of the combination
		of standard libraries used to build binaries.  This
		value locates the final subdirectory used to locate binaries.
              </p>
            </desc>
	    <term>NSDeallocateZombies</term>
	    <desc>
	      <p>
		This may be used in conjunction with NSZombieEnabled to specify
		whether the objects should really be deallocated.  If you set
		this to YES, the zombie logging will only work until the
		deallocated memory is re-used.
	      </p>
	    </desc>
	    <term>NSZombieEnabled</term>
	    <desc>
	      <p>
		If this is set to YES, then deallocation of an object causes
	        the object to be morphed into a Zombie ... a special object
		which will call the GNUstep specific GSLogZombie() function
		to log the method call.<br />
		You can set a breakpoint in this function and examine the
		process memory if you are running under a debugger.<br />
		As this overrides actual object deallocation, all memory
		allocated for objects will be leaked!
	      </p>
	    </desc>
	    <term>SOCKS5_SERVER</term>
	    <desc>
	      <p>
		Specifies the default socks server to be used when making
		outgoing tcp/ip connections using NSFileHandle.  This may
		also specify a port after the host name (and spearated
		from it by a colon).<br />
		This environment variable is used only if the GSSOCKS
		user default is not set.
	      </p>
	    </desc>
	    <term>SOCKS_SERVER</term>
	    <desc>
	      <p>
		Equivalent to SOCKS5_SERVER, but used only if that is not
		defined.
	      </p>
	    </desc>

	    <term>TZ</term>
	    <desc>
	      <p>
		Used to specify the timezone to be used if there is no
		timezone specified by any other mechanism.  The preferred
		mechanism is to use the 'Local Time Zone' value from the
		user defaults system.
	      </p>
	    </desc>

	  </deflist>
	</subsect>
	<subsect>
	  <heading>.GNUsteprc files</heading>
	  <p>
	    The locations of the directories in which user specific files and
	    the user defaults database are stored are defined in the
	    <code>.GNUsteprc</code> files.<br />
	    If no location is given for user specific files, they are stored
	    in the GNUstep subdirectory of the users home directory.<br />
	    If a separate location is not given for the defaults database, it
	    is stored in the same directory as other user specific files.<br />
	  </p>
	  <p>
	    The presence of a <code>.GNUsteprc</code> file in a users home
	    directory premits the user to customize file locations using
	    two commands -
	  </p>
	  <deflist>
	    <term>GNUSTEP_DEFAULTS_ROOT=...</term>
	    <desc>
	      The text after the '=' is taken to be the path to the users
	      files.  If it begins with a '~' character, the users home
	      directory is prepended to it.
	    </desc>
	    <term>GNUSTEP_USER_ROOT=...</term>
	    <desc>
	      The text after the '=' is taken to be the path to the users
	      files.  If it begins with a '~' character, the users home
	      directory is prepended to it.
	    </desc>
	  </deflist>
	  <p>
	    The presence of a <code>.GNUsteprc</code> file in the GNUstep
	    system directory may provide default paths for all users and
	    may even override user specific files.  The content of this file
	    is as for the user specific file, but permits two additional
	    commands -
	  </p>
	  <deflist>
	    <term>FORCE_DEFAULTS_ROOT</term>
	    <desc>
	      If this line is present, and the file specifies a
	      GNUSTEP_DEFAULTS_ROOT, then the value given in the system-wide
	      file is used irrespective of the user specific file.
	      Otherwise, the value in the user specific file takes precedence.
	    </desc>
	    <term>FORCE_USER_ROOT</term>
	    <desc>
	      If this line is present, and the file specifies a
	      GNUSTEP_USER_ROOT, then the value given in the system-wide
	      file is used irrespective of the user specific file.
	      Otherwise, the value in the user specific file takes precedence.
	    </desc>
	  </deflist>
	</subsect>
      </section>
    </chapter>
    <back>
      <index scope="project" type="class" />
      <index scope="project" type="protocol" />
    </back>
  </body>
</gsdoc>
