GNU Objective-C Class Library
*****************************

The GNUstep Base Library (libgnustep-base) is a library of
general-purpose, non-graphical Objective C objects written by Andrew
McCallum.  What `libg++' is to GNU's C++, `libgnustep-base' is to GNU's
Objective C.

   The library features collection objects for maintaining groups of
objects and C types, strings for handling collections of characters,
streams for I/O to various destinations, coders for formating objects
and C types to byte streams, ports for network packet transmission,
distributed objects (remote object messaging), pseudo-random number
generators, and time handling facilities.

   * The heirarchy of collection objects are similar in spirit to
     Smalltalk's collections.  A deep inheritance heirarchy provides
     good uniformity of method names across different collection
     classes.  All collections can hold simple C types (such as int's
     and floats) as well as Objects.  The collection classes include
     simple collections (Set, Bag), collections with contents
     accessible by unordered keys (Dictionary, MappedCollector),
     collections with ordered contents (Array, LinkedList, Stack,
     Queue, Heap, BinaryTree, RBTree, SplayTree, GapArray).  There is
     also a DelegatePool object that can forward messages it receives
     to an arbitrary number of delegate objects.

   * String objects...

   * Stream objects provide a consistent interface for reading and
     writing bytes.  `StdioStream' objects work with files, file
     descriptors, FILE pointers and pipes to/from executables.
     `MemoryStream' objects work with memory buffers that grow
     automatically as needed.  For all Stream objects there are methods
     for writing/reading arbitrary n-length buffers, newline-terminated
     lines, and printf-style strings.

   * Coders provide a formatted way of writing to Streams.  After a
     coder is initialized with a stream, the coder can encode/decode
     Objective C objects and C types in an architecture-independent
     way.  The currently available concrete coder classes are
     `BinaryCoder', for reading and writing a compact stream of
     illegible bytes, and `TextCoder', for reading and writing
     human-readable structured textual representation (which you can
     also process with `perl', `awk', or whatever scripting language
     you like).

     Coders and streams can be mixed and matched so that programmers can
     choose the destination and the format separately.

   * The distributed object support classes are `Connection', `Proxy',
     `ConnectedCoder', `Port' and `SocketPort'.  This version of the
     distributed objects only works with sockets.  A Mach port back-end
     should be on the way.

     [NOTE: The GNU distributed object facilities have the same
     ease-of-use as NeXT's; be warned, however, that they are not
     compatible with each other.  They have different class
     heirarchies, different instance variables, different method names,
     different implementation strategies and different network message
     formats.  You cannot communicate with a NeXT NXConnection using a
     GNU Connection.  NXConnection creates NXProxy objects for local
     objects as well as remote objects; GNU Connection doesn't need and
     doesn't create proxies for local objects.  NXProxy asks it's
     remote target for the method encoding types and caches the results;
     GNU Proxy gets the types directly from the local GNU "typed
     selector" mechanism and has no need for querying the remote target
     or caching encoding types.  The NXProxy for the remote root object
     always has name 0 and, once set, you cannot change the root object
     of a NXConnection; the GNU Proxy for the remote root object has a
     target address value just like all other Proxy's, and you can
     change the root object as many times as you like.  See the
     "lacking-capabilities" list below for a partial list of things
     that NXConnection can do that GNU Connection cannot.]

     Here is a partial list of what the current distributed objects
     system can do:
          * It can pass and return all simple C types, including char*, float
            and double, both by value and by reference.
          * It can pass structures by value and by reference, return
            structures by reference.  The structures can contain arrays.
          * It obeys all the type qualifiers: oneway, in, out, inout, const.
          * It can pass and return objects, either bycopy or with proxies.
            An object encoded multiple times in a single message is properly
            decoded on the other side.
          * Proxies to remote objects are automatically created as they are
            returned.  Proxies passed back where they came from are decoded
            as the correct local object.
          * It can wait for an incoming message and timeout after a
            specified period.
          * A server can handle multiple clients.
          * The server will ask its delegate before making new connections.
          * The server can make call-back requests of the client, and keep
            it all straight even when the server has multiple clients.
          * A client will automatically form a connection to another client
            if an object from the other client is vended to it. (i.e. Always
            make a direct connection rather than forwarding messages twice,
            once into the server, from there out to the other client.)
          * The server will clean up its connection to a client if the client
            says goodbye (i.e. if the client connection is freed).
          * When the connection is being freed it will send a invalidation
            notification message to those objects that have registered for
            such notification.
          * Servers and clients can be on different machines of different
            architectures; byte-order and all other architecture-dependent
            nits are taken care of for you.  You can have SPARC, i386, m68k,
            and MIPS machines all distributed-object'ing away together in
            one big web of client-server connections!

     Here is a partial list of what the current distributed objects
     system does *not* do:
          * Run multi-threaded.
          * Detect port deaths (due to remote application crash, for example)
            and do something graceful.
          * Send exceptions in the server back to the client.
          * Return structures by value.
          * Use Mach ports, pass Mach ports, pass Mach virtual memory.
          * Send messages more reliably than UDP.  It does detect reply
            timeouts and message-out-of-order conditions, but it's reaction
            is simply to abort.
          * Claim to be thoroughly tested.

Getting It, and Compiling It
============================

   The library is available by anonymous ftp at URL:
     ftp://prep.ai.mit.edu/pub/gnu/libgnustep-base-0.2.12.tar.gz
   Since `prep' is heavily loaded, you are encouraged to use GNU mirror
sites.

   The most recent (not necessarily tested) snapshots of the library
will be placed at `ftp://alpha.gnu.ai.mit.edu/gnu'.

   THIS INFORMATION IS OUT-OF-DATE.

   The library requires gcc 2.7.2 or higher.  The library does not work
with the NEXTSTEP 3.2 compiler because that version of NeXT's cc cannot
handle nested functions.  Until a later release from NeXT, NEXTSTEP
users will have to install gcc.  See the `INSTALL' file for more
instructions about compiling and installing the library.

   The library has been successfully compiled and tested with the
following configurations:
       mips-sgi-irix5.2

   Some previous snapshots of the library worked with these
configurations, but they haven't been tested recently.  We are looking
for a volunteer to write a test suite using dejagnu.
       sparc-sun-sunos4.1.3
       m68k-next-nextstep3.0
       rs6000-ibm-aix3.2
       sparc-sun-solaris2.3
       i386-unknown-linux
       i386-sun-solaris2.4
       i386-unknown-sysv4.0
       mips-dec-ultrix4.2
       HP/UX 9.01

   It is known not to work with:
       alpha-dec-osf

GNUStep
=======

   The `libgnustep-base' library already contains many of the GNUStep
common classes: List, HashTable, Storage, NXStringTable.  In the future
it will also contain the foundation kit classes for GNUStep.  Progress
is already being made on this front.

Contact:
========

     Andrew McCallum
     mccallum@gnu.ai.mit.edu

