# GNUstep Base

$Revision: 24482 $
$Date: 2007-02-06 02:29:30 -0700 (Tue, 06 Feb 2007) $
2005 Free Software Foundation, Inc.
Base

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.

Read the Release Notes for the current release.

Compatibility

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 OpenStep Compliance section for more information on OpenStep Compliance.

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.

Conditional compilation

Adding an option to a makefile to define one of the following preprocessor constants will modify the API visible to software being compiled -

GS_GNUSTEP_V
Specifies the software version of the header being included.
Features in that header which are declared as having been introduced at or before the specified version, and not being removed until or after the specified version are available.
The version consists of five or six digits ... a major number (0-99) followed by a minor number (00-99) and a subminor number (00-99).
Features in the header file are marked as belonging to different version ranges using the GS_API_VERSION macro.
NB. This is the native versioning of the library being used via the header file. You can use this mechanism in your own libraries and frameworks.
GS_OPENSTEP_V
Used only for the software version in sequence of OpenStep specification and the NeXT/Apple implementation of that specification and its extensions.
Features in the header being included which are declared as having been introduced at or before the specified version, and not being removed until or after the specified version are available.
The version consists of five or six digits ... a major number (1-99) followed by a minor number (00-99) and a subminor number (00-99).
A major number of 1 indicates the OpenStep specification ... available as the GS_API_OSSPEC preprocessor constant.
A major number of 4 indicates the OPENSTEP implementation ... available as the GS_API_OPENSTEP preprocessor constant.
A major number of 10 indicates the MacOS-X implementation ... available as the GS_API_MACOSX preprocessor constant.
Features in the header file are marked as belonging to different version ranges using the GS_API_VERSION macro.
For MacOS-X compatibility, if this constant is not defined and MAC_OS_X_VERSION_MAX_ALLOWED is defined, then GS_OPENSTEP_V is defined to be MAC_OS_X_VERSION_MAX_ALLOWED.
Similarly, for MacOS-X we define MAC_OS_X_VERSION_10_2, MAC_OS_X_VERSION_10_3 etc as the appropriate numeric version numbers.

NB These preprocessor constants are used in developer code (ie the code that users of GNUstep write) rather than by the GNUstep software itself. 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).
The actual GNUstep libraries are always built with the full GNUstep API in place, so that the feature set is as consistent as possible.

The presence of these macros is also used by autogsdoc to generate information about which version of the API a particular feature belongs to.

User defaults
GNU-Debug

An array of strings that lists debug levels to be used within the program. These debug levels are merged with any which were set on the command line or added programmatically to the set given by the [NSProcessInfo-debugSet] method.

GSLogSyslog

Setting the user default `GSLogSyslog` to `YES` 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.
On mswindows, where syslog does not exist, this flag instead controls whether log/debug output is sent to the windows event log.

GSLogThread

Setting the user default `GSLogThread` to `YES` will cause NSLog and debug output to include the current thread in the logged message.
This is useful for debugging multi-threaded applications.

GSMacOSXCompatible

Setting the user default `GSMacOSXCompatible` to `YES` 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.

GSOldStyleGeometry

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.

GSSOCKS

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.
This default overrides the SOCKS5_SERVER and SOCKS_SERVER environment variables.

Local Time Zone

Used to specify the name of the timezone to be used by the NSTimeZone class.

NSWriteOldStylePropertyLists

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.

Reading of property lists is supported in either format, but only if GNUstep is built with the libxml library (which is needed to handle XML parsing).

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.

NSLanguages

An array of strings that lists the users prefered languages, in order or preference. If not found the default is just English.

Environment variables

There are some environment variables used by GNUstep base, where there would be problems obtaining data from the defaults system.

CRASH_ON_ABORT

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.

The CRASH_ON_ABORT environment variable can be used to override this behavior. If this is defined to NO, FALSE, or 0 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.

CRASH_ON_ZOMBIE

When the a message is sent to a zombie object (see the `NSZombieEnabled` environment variable) the base library allows you to specify whether the program should continue after logging the message, or have the program abort.
By default, the program will attempt to continue.

The `CRASH_ON_ZOMBIE` variable can be used to override this behavior. If this is defined to YES, TRUE, or 1 then the program will log the message sent to the zombie and then abort, producing a core dump on systems where that is possible.

GNUSTEP_STACK_TRACE

When this is set to YES a stack trace is placed in the user information dictionary of the NSException object created when an exception is raised. The trace is keyed on `GSStackTraceKey` and provides additional information to let you know where the exception occurred.

GNUSTEP_STRING_ENCODING

This is used to specify the default encoding for 8-bit strings (those used by 'cstring' methods of NSString).
It may be any of the 8-bit encodings supported by your system.

If this environment variable is not set, GNUstep attempts to use the characterset specified by your operating systems, locale information (using the standard nl_langinfo function) if possible.

If there is no usable operating system defined characterset, GNUstep defaults to NSISOLatin1StringEncoding.

GNUSTEP_HOST_CPU

Used in place of GNUSTEP_TARGET_CPU if the other is missing.

GNUSTEP_HOST_DIR

Used in place of GNUSTEP_TARGET_DIR if the other is missing.

GNUSTEP_HOST_OS

Used in place of GNUSTEP_TARGET_OS if the other is missing.

GNUSTEP_TARGET_CPU

Overrides the default value of the machine (hardware) name used on this system.

GNUSTEP_TARGET_DIR

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

GNUSTEP_TARGET_OS

Overrides the default value of the operating system name used on this system.

GNUSTEP_TZ

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.

GNUSTEP_CONFIG_FILE

This functionality may have been disabled if the base library was configured/built with the `--disable-environment-config-file` option.
If it is operational, the environment variable overrides the normal path to the gnustep config file used to determine the locations of paths for the gnustep system (see later).
This is provided to support the odd situation where you may want to simultaneously run applications using different sets of resources but linked to a single copy of the base library, or you want to use an alternative config file for some reason.

HOMEDRIVE

Used on ms-windows to locate the home directory.

HOMEPATH

Used on ms-windows to locate the home directory.

LANGUAGES

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.

LOGNAME

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.

LIBRARY_COMBO

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.

NSDeallocateZombies

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.

NSZombieEnabled

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.
You can set a breakpoint in this function and examine the process memory if you are running under a debugger.
As this overrides actual object deallocation, all memory allocated for objects will be leaked!
You can use the `CRASH_ON_ZOMBIE` environment variable to force an abort afdter the message is logged.

SOCKS5_SERVER

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).
This environment variable is used only if the GSSOCKS user default is not set.

SOCKS_SERVER

Equivalent to SOCKS5_SERVER, but used only if that is not defined.

TZ

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.

GNUstep Configuration File

This file is the master configuration file for GNUstep. It can be used to set the base location of all the standard paths that GNUstep programs use or know about. The location of this file depends on how the Base library was configured and/or what operating system it was configured on. On a GNU/Linux system, the default would be /etc/GNUstep/GNUstep.conf for instance, while on mswindows it would be ./GNUstep.conf.
The location of this file can be specified when the base library is configured ... using the `--with-config-file=` option of the `configure` script.
The configuration file is not actually required to exist, and if it does not exist, then default values will be used. for the standard path locations (these default values may be specified using the `--with-default-config=` option of the `configure` script.
If you want to force the internal defaults to be used, you can use `--with-config-file=` to specify a path with a trailing '/' (ie with no filename) as the base library will refrain from trying to load configuration from a file of no name.
System paths are defined by the following:

GNUSTEP_SYSTEM_ROOT
Used to specify the GNUstep system root directory ... all system libraries, tools, applications, headers, resources in general are located relative to this.
GNUSTEP_NETWORK_ROOT
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 but is usually defined to the same value.
GNUSTEP_LOCAL_ROOT
Used to specify the GNUstep root directory for local (non-system) resources. Typically all locally produced or contributed software is installed relative to this.

Paths for each user are defined by the following:

GNUSTEP_USER_DIR
Path for user specific GNUstep resources (eg. 'GNUstep'). Relative to the user's home directory.
GNUSTEP_USER_CONFIG_FILE
Name of user configuration file (eg. '.GNUstep.conf') relative to the user's home directory.
Can be specified as an empty string to ensure that no user specific config file is loaded.
GNUSTEP_USER_DEFAULTS_DIR
Name of directory for user defaults files. Relative to the user's home directory.
On mswindows this may be set to be ':REGISTRY:' to have defaults stored in the windows registry rather than in the standard file format.
On any system this may be set to ':INTERNAL:' to use only internal defaults domains (NSArgumentDomain, NSRegistrationDomain, and GSConfigDomain).

The user's home directory is taken to be the standard home directory for that user on the system
On unix, that is the user's home directory from the password file, while on windows it's the value given by the HOMEDRIVE and HOMEPATH environment variables (or the USERPROFILE environment variable if the others can't be used).

Support is provided to locate OS/PLATFORM directories. A conf file may provide the definitions below (with examples typical for when GNUstep is installed according to the Linux Filesystem Hierarchy standard):

GNUSTEP_SYS_APPS
Place for system/os applications (eg. '/bin')
GNUSTEP_SYS_LIBS
Place for system/os shared libraries (eg. '/lib')
GNUSTEP_SYS_ADMIN
Place for system administration tools (eg. '/sbin')
GNUSTEP_PLATFORM_APPS
Place for non-gnustep applications (eg. '/usr/bin')
GNUSTEP_PLATFORM_LIBS
Place for application shared libraries (eg. '/usr/lib')
GNUSTEP_PLATFORM_RESOURCES
Place for shared application resources (eg. '/usr/share')
GNUSTEP_PLATFORM_ADMIN
Place for non-critical administrative tools (eg. '/usr/sbin')
GNUSTEP_PLATFORM_LOCAL_APPS
Place for machine local applications (eg. '/usr/local/bin')
GNUSTEP_PLATFORM_LOCAL_LIBS
Place for machine local shared libraries (eg. '/usr/local/lib/')
GNUSTEP_PLATFORM_LOCAL_RESOURCES
Place for machine local resources. (eg. '/usr/local/share')

These add to the path for NSSystemDomainMask, or NSLocalDomainMask as appropriate.

All the above values from the configuration file are made available in the NSUserDefaults system at runtime, in the GSConfigDomain of the defaults.
In addition, the configuration file may contain the key GNUSTEP_EXTRA with a value set to be a comma separated list of extra key names which are to be allowed in the config file. This lets you add more key/value pairs to the config file intended to be seen in the NSUserDefaults system.
However, you must take care that any key names you choose do not conflict with variable names used with the GNUstep Makefiles package or your configuration script may cause problems when building software.

The exact format of the configuration file is expected to be that of a basic unix "conf" style file, with one key = value per line (the format a unix shell can 'source' in order to define shell variables).
This configuration file uses the escape sequence and quoting conventions of the standard bourne shell.
The only Keys permitted are those listed above (plus any specified in the GNUSTEP_EXTRA list), and all consist of uppercase letters, digits, and underscores, and must not begin with a digit.
A value may be any quoted string (or an unquoted string containing no white space).
Lines beginning with a hash '#' are deemed comment lines and ignored.
The backslash character may be used as an escape character anywhere in the file except within a singly quoted string (where it is taken literally).
A backslash followed immediately by a newline (except in a singly quoted string) is removed completely along with the newline ... it thus serves to join lines so that they are treated as a single line.
NB. Since ms-windows uses backslash characters in paths, it is a good idea to specify path values in the config file as singly quoted strings to avoid having to double all occurrences of the backslash.

Relocatable packages

The configuration files system has two features which make it possible to build standalone packages containing the entire GNUstep system in a form which can be moved anywhere and just run.

Firstly, variables in the configuration file which define paths, are expected to by full path specifications, except for the special case in which they begin with dot-slash (./). In this case the text after the dot-slash is appended to the path to the directory containing the configuration file (or specified to contain the configuration file if no configuration file exists) to form the value used.

Secondly, If the value of the path built in to the base library as the location of the config file (or specified by the GNUSTEP_CONFIG_FILE environment variable unless that option was disabled when the base library was configured) begins with a dot and slash (./) then the path used for that file is made relative to the base library.
ie the text after the dot-slash is appended to the path of the directory containing the gnustep-base library.

So you can bundle the whole lot together in one directory, and configure various relative paths in that directory, then move the directory around wherever you like.

If you wish to lock down a production system for distribution as a relocatable package, so it can be installed anywhere, but users can't accidentally change the config file and mess up paths, you can specify the config file name as a path with a trailing slash so that the base library will not read it, and will use the builtin default values.
To do this, you would configure using the options `--with-config-file=./` and `--with-default-file=myConfig` where myConfig is a file containing the paths you want to use relative to the location the base library gets installed in.
The paths from that file will be built in to the base library as defaults, and library will use them rather than attempting to read a config file at runtime.

.GNUstep.conf files

The user specific configuration file is read after the system configuration file and may generally override values from the main file. To prevent the use specific file from being read, the system manager may define GNUSTEP_USER_CONFIG_FILE in the main file to be an empty string.
In any case, the user specific file is not read if a program is running setuid.

Unless disabled (as specified above) the presence of a `.GNUstep.conf` file in a users home directory permits the user to customize file locations using all the same commands as the system directory, though any attempt to redefine GNUSTEP_USER_CONFIG_FILE is of course ignored.
Attempts to redefine the users home directory at this level are also ignored.

User specific files are stored in the locaton given by GNUSTEP_USER_DIR (by default, the `GNUstep` subdirectory of the users home directory).
The defaults database for a user is stored in the subdirectory of the users home directory given by GNUSTEP_USER_DEFAULTS_DIR (by default, the `GNUstep/Defaults` subdirectory). On mswindows this may be set to be ':REGISTRY:' to have defaults stored in the windows registry rather than in the standard file format.
On any system this may be set to ':INTERNAL:' to use only internal defaults domains (NSArgumentDomain, NSRegistrationDomain, and GSConfigDomain).

API Documentation
Functions
Types and Constants