home *** CD-ROM | disk | FTP | other *** search
/ Peanuts NeXT Software Archives / Peanuts-3.iso / OpenStep / systems / gnustep / sources / gstep-base-0.2.7.README next >
Encoding:
Text File  |  1996-09-02  |  8.6 KB  |  199 lines
  1. GNUstep Base Library README
  2. ***************************
  3.  
  4. The GNUstep Base Library is a library of general-purpose, non-graphical
  5. Objective C objects.  For example, it includes classes for strings,
  6. object collections, byte streams, typed coders, invocations,
  7. notifications, notification dispatchers, moments in time, network ports,
  8. remote object messaging support (distributed objects), event loops, and
  9. random number generators.
  10.  
  11.    It provides functionality that aims to implement the non-graphical
  12. portion of the OpenStep standard.  In many cases, the `NS*' classes are
  13. implemented as wrappers around more featureful GNU classes.
  14.  
  15.    Here is some introductory info to get you started:
  16.  
  17. Initial reading
  18. ===============
  19.  
  20.    The file `doc/GNUstep-FAQ' contains a brief overview of the library.
  21. It also tells you where to get the most recent version.
  22.  
  23.    The file `NEWS' has the library's feature history.
  24.  
  25.    The file `INSTALL' gives instructions for installing the library.
  26.  
  27. Preparing to write code
  28. =======================
  29.  
  30.    The documentation isn't much to speak of so far.  Better
  31. documentation will be forthcoming, but the library needs to settle
  32. first.  For now I recommend skipping `gnustep-base.info' and reading
  33. the header files instead.  The headers for the classes are in
  34. `./src/include'.
  35.  
  36.    The GNUstep FAQ contains an outline of the class heirarchy, as well
  37. as a list of the differences between GNUstep and NeXT's implementation
  38. of OpenStep, and GNUstep's improvements over NeXT's implementation.  The
  39. FAQ can be found in `doc/GNUstep-FAQ'.
  40.  
  41.    Outdated, preliminary documentation is available via `texinfo' in
  42. the files `gnustep-base.info' and `gnustep-base.texi'.  Because texinfo
  43. doesn't yet handle `@deftypemethod', this documentation cannot yet be
  44. compiled into more readable forms.
  45.  
  46. Overview of the classes
  47. =======================
  48.  
  49.    Here is partial list of non-OpenStep classes, grouped by
  50. functionality.
  51.  
  52.    There are several GNU-specific protocols also.  You can recognize the
  53. protocols by their name: they all end with "ing".
  54.  
  55.    * The collection objects all conform to the `Collecting' protocol.
  56.      Reading `src/include/Collecting.h' is a good place to start.
  57.      Protocols for collections that store their contents with keys and
  58.      with indices can be found in `src/incliude/KeyedCollecting.h' and
  59.      `src/include/IndexedCollecting.h' respectively.  Examples of
  60.      generic collections are `Set' and `Bag'.  The keyed collections are
  61.      `Dictionary' and `MappedCollector'.  The classes `Array', `Queue',
  62.      `GapArray', `LinkedList', `BinaryTree', `RBTree' and `SplayTree'
  63.      are all indexed collections.
  64.  
  65.    * The string objects conform to the `String' protocol.  `CString'
  66.      provides an interface to strings based on ASCII bytes, and is
  67.      currently the only concrete subclass of String.  The interface
  68.      between GNU `String' and OpenStep's `NSString' needs cleaning up
  69.      and will change.  For now, I recommend using `NSString'.
  70.  
  71.    * The public magnitude classes are `Time' and `Random'.  The
  72.      `Random' class works in conjunction with pseudo-random number
  73.      generators that conform to the `RandomGenerating' protocol.  The
  74.      conforming class `RNGBerkeley' provides identical behavior to the
  75.      BSD random() function.  The class `RNGAdditiveCongruential' is an
  76.      implementation of the additive congruential method.
  77.  
  78.    * Stream objects provide a consistent interface for reading and
  79.      writing bytes.  Read `src/include/Stream.h' to get the general
  80.      idea.  `StdioStream' objects work with files, file descriptors,
  81.      FILE pointers and pipes to/from executables.  `MemoryStream'
  82.      objects work with memory buffers.
  83.  
  84.    * CStream objects provide a way to write C variables to Stream
  85.      objects.  Read `src/include/CStream.h' to understand the interface
  86.      of the abstract superclass.  `TextCStream' writes C variables in a
  87.      human-readable ASCII format that can be manipulated with a text
  88.      editor or with your choice of text-processing programs, like `awk'
  89.      or `perl'.  `BinaryCStream' writes C variables in a compact,
  90.      illegible stream of bytes.  `TextCStream' and `BinaryCStream' each
  91.      write in machine-independant formats--so you can write on one
  92.      machine architecture, and successfully read on another.
  93.      `RawCStream' is like `BinaryCStream' accept it is
  94.      machine-dependant; it useful for efficient Distributed Objects
  95.      connections on the same machine.
  96.  
  97.    * Coders provide a formatted way of writing Objective C objects to
  98.      CStream objects.  After a coder is initialized with a stream, the
  99.      coder can encode/decode interconnected webs of Objective C objects
  100.      and C types and successfully keep track of complex
  101.      interconnections between objects.  See `src/include/Coder.h' for
  102.      the abstract superclass interface; see `src/include/Coding.h' for
  103.      the protocol adopted by objects that read and write themselves
  104.      using coders.  `Archiver' and `Unarchiver' are concrete subclasses
  105.      that are used for writing/reading with files.
  106.  
  107.      `Coder's and `CStream's and `Stream's can be mixed and matched so
  108.      that programmers can choose the destination and the format
  109.      separately.
  110.  
  111.    * The distributed object support classes are `Connection', `Proxy',
  112.      `ConnectedCoder', `Port' and `TcpPort'.  This version of the
  113.      distributed objects only works with sockets.  A Mach port back-end
  114.      should be on the way.
  115.  
  116.      See `doc/GNUstep-FAQ' for a detailed description of the cabilities
  117.      and non-capabilities of GNU Distributed Objects.
  118.  
  119.      To begin using distributed objects, you only need to know about
  120.      `Connection' class.  You can see the full (documented!) interface
  121.      in `src/include/Connection.h'.  The long list of methods may be a
  122.      little daunting, but actually, a lot can be done with just a few
  123.      key methods:
  124.  
  125.           - (Connection*) newRegisteringAtName: name
  126.               withRootObject: anObj;
  127.                 For registering your server object with the network.
  128.           
  129.           - (void) runConnection;
  130.                 For running the connection object returned by the above
  131.                 method, so that your server can start handling requests from
  132.                 clients.
  133.           
  134.           - (Proxy*) rootProxyAtName: name
  135.               onHost: host;
  136.                 For connecting to a remote server.  You get a proxy object for
  137.                 the remote server object, which, for messaging purposes, you
  138.                 can treat as if it were local.
  139.  
  140. Where else to look
  141. ==================
  142.  
  143. Examples
  144. --------
  145.  
  146.      A few simple example programs can be found in `examples'.  Read
  147. and enjoy.  To compile them (after having compiled the library), type
  148. `make' in the `examples' directory.
  149.  
  150.         * `dictionary.m' demonstrates the basic features of the
  151.           Dictionary object.
  152.  
  153.         * `stdio-stream.m' creates a StdioStream object that points to
  154.           a file, writes to the file, then reads from the file.
  155.  
  156.         * `textcoding.m' shows how you can archive an object to a file
  157.           in a human-readable text format, and then read it back in
  158.           again.  This format is handy for editing archived objects
  159.           with a text editor, and is great when you want to
  160.           modify/create an archive using a scripting language like
  161.           `perl' or `awk'.
  162.  
  163.         * `first-server.m' and `first-client.m' show the distributed
  164.           object version of "Hello, world".
  165.  
  166.         * `second-server.m' and `second-client.m' contain a more
  167.           complex demonstration of distributed objects, with multiple
  168.           clients, connection delegates, and invalidation notification.
  169.  
  170.         * `tcpport-server.m' and `tcpport-client.m' show a simple use
  171.           of TcpPort objects.
  172.  
  173. Test Programs
  174. -------------
  175.  
  176.      Some of the programs I've used to test the library are in
  177. `./checks'.  Many of them are pretty messy, (desperately trying to
  178. tickle that late night bug), but at least they show some code that works
  179. when the library compiles correctly.  I'm looking for a volunteer to
  180. write some nicely organized test cases using `dejagnu'.  Any takers?
  181.  
  182. How can you help?
  183. =================
  184.  
  185.         * Read the projects and questions in the `TODO' file.  If you
  186.           can volunteer for any of the projects, or if you have any
  187.           useful comments send me email!  <mccallum@gnu.ai.mit.edu>
  188.  
  189.         * Give me feedback!  Tell me what you like; tell me what you
  190.           think could be better.  Send me bug reports.
  191.  
  192.         * Donate classes.  If you write classes that fit in the
  193.           libgnustep-base framework, I'd be happy to include them.
  194.  
  195.           Happy hacking!
  196.                  Andrew McCallum
  197.                  mccallum@gnu.ai.mit.edu
  198.  
  199.