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
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
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.
Adding an option to a makefile to define one of the following preprocessor constants will modify the API visible to software being compiled -
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.
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.
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.
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.
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.
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.
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.
Used to specify the name of the timezone to be used by the NSTimeZone class.
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.
An array of strings that lists the users prefered languages, in order or preference. If not found the default is just English.
There are some environment variables used by GNUstep base, where there would be problems obtaining data from the defaults system.
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.
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.
May be set to unix to enforce unix style path
handling, or windows to enforce mswindows style
path handling, or anu other value (including unset) for the
default behavior where both styles of paths should be
managed in the best way possible.
The option to enforce either upre unix or pure windows style path handling (and hence this environment variable) may be removed in a later release.
Used in place of GNUSTEP_TARGET_CPU if the other is missing.
Used in place of GNUSTEP_TARGET_DIR if the other is missing.
Used in place of GNUSTEP_TARGET_OS if the other is missing.
Used to specify the GNUstep root directory for local (non-system) resources. Typically all locally produced or contributed software is installed relative to this.
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.
Used to specify the GNUstep system root directory ... all system libraries, tools, applications, headers, resources in general are located relative to this.
This environment variable, commonly set by the make system, is not used by GNUstep programs. Instead values from the GNUstep configuration file are used (see later).
Overrides the default value of the machine (hardware) name used on this system.
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
Overrides the default value of the operating system name used on this system.
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.
Used on windoze to locate the home directory.
Used on windoze to locate the home directory.
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.
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.
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.
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.
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!
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.
Equivalent to SOCKS5_SERVER, but used only if that is not defined.
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.
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.
The location of this file can be overridden using the
GNUSTEP_CONFIG_FILE environment variable (unless the base libarary
had this feature specifically turned off using the
--disable-environment-config-file option when the
configure script was run prior to building it.
The configuration file is not actually required to exist.
If it does not exist, then default values will be used
for the standard path locations.
System paths are defined by the following:
Paths for each user are defined by the following:
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
Win32GetUserProfileDirectory() function.
Support is provided to locate OS/PLATFORM directories. A conf file may provide the definitions below:
These add to the path for NSSystemDomainMask, or NSLocalDomainMask as appropriate.
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, wariables 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 dot-slash is replaced by the path to the directory containing the configuration file (or specified to contain the configuration file if no configuration file exists).
Secondly, If the value specified by GNUSTEP_CONFIG_FILE (or
built into the base library) itself begins with a dot and
slash (./) then the path used for that file is made relative
to the base library.
ie the dot-slash is replaced by the path to 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.
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.
The locations of the directories in which user specific files and
the user defaults database are stored may be defined in the
file given by GNUSTEP_USER_CONFIG_FILE (by default,
.GNUstep.conf).
If no location is given for user specific files, they are stored
in the locaton given by GNUSTEP_USER_DIR (by default, the
GNUstep subdirectory of the users home
directory).
If a separate location is not given for the defaults database, it
is stored in the subdirectory of the users home directory given by
GNUSTEP_USER_DEFAULTS_DIR (by default, the
GNUstep/Defaults subdirectory).
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.