GNUstep Base Library README *************************** The GNUstep Base Library is a library of general-purpose, non-graphical Objective C objects. For example, it includes classes for strings, object collections, byte streams, typed coders, invocations, notifications, notification dispatchers, moments in time, network ports, remote object messaging support (distributed objects), event loops, and random number generators. It provides functionality that aims to implement the non-graphical portion of the OpenStep standard. In many cases, the `NS*' classes are implemented as wrappers around more featureful GNU classes. Here is some introductory info to get you started: Initial reading =============== The file `doc/GNUstep-FAQ' contains a brief overview of the library. It also tells you where to get the most recent version. The file `NEWS' has the library's feature history. The file `INSTALL' gives instructions for installing the library. Preparing to write code ======================= The documentation isn't much to speak of so far. Better documentation will be forthcoming, but the library needs to settle first. For now I recommend skipping `gnustep-base.info' and reading the header files instead. The headers for the classes are in `./src/include'. The GNUstep FAQ contains an outline of the class heirarchy, as well as a list of the differences between GNUstep and NeXT's implementation of OpenStep, and GNUstep's improvements over NeXT's implementation. The FAQ can be found in `doc/GNUstep-FAQ'. Outdated, preliminary documentation is available via `texinfo' in the files `gnustep-base.info' and `gnustep-base.texi'. Because texinfo doesn't yet handle `@deftypemethod', this documentation cannot yet be compiled into more readable forms. Overview of the classes ======================= Here is partial list of non-OpenStep classes, grouped by functionality. There are several GNU-specific protocols also. You can recognize the protocols by their name: they all end with "ing". * The collection objects all conform to the `Collecting' protocol. Reading `src/include/Collecting.h' is a good place to start. Protocols for collections that store their contents with keys and with indices can be found in `src/incliude/KeyedCollecting.h' and `src/include/IndexedCollecting.h' respectively. Examples of generic collections are `Set' and `Bag'. The keyed collections are `Dictionary' and `MappedCollector'. The classes `Array', `Queue', `GapArray', `LinkedList', `BinaryTree', `RBTree' and `SplayTree' are all indexed collections. * The string objects conform to the `String' protocol. `CString' provides an interface to strings based on ASCII bytes, and is currently the only concrete subclass of String. The interface between GNU `String' and OpenStep's `NSString' needs cleaning up and will change. For now, I recommend using `NSString'. * The public magnitude classes are `Time' and `Random'. The `Random' class works in conjunction with pseudo-random number generators that conform to the `RandomGenerating' protocol. The conforming class `RNGBerkeley' provides identical behavior to the BSD random() function. The class `RNGAdditiveCongruential' is an implementation of the additive congruential method. * Stream objects provide a consistent interface for reading and writing bytes. Read `src/include/Stream.h' to get the general idea. `StdioStream' objects work with files, file descriptors, FILE pointers and pipes to/from executables. `MemoryStream' objects work with memory buffers. * CStream objects provide a way to write C variables to Stream objects. Read `src/include/CStream.h' to understand the interface of the abstract superclass. `TextCStream' writes C variables in a human-readable ASCII format that can be manipulated with a text editor or with your choice of text-processing programs, like `awk' or `perl'. `BinaryCStream' writes C variables in a compact, illegible stream of bytes. `TextCStream' and `BinaryCStream' each write in machine-independant formats--so you can write on one machine architecture, and successfully read on another. `RawCStream' is like `BinaryCStream' accept it is machine-dependant; it useful for efficient Distributed Objects connections on the same machine. * Coders provide a formatted way of writing Objective C objects to CStream objects. After a coder is initialized with a stream, the coder can encode/decode interconnected webs of Objective C objects and C types and successfully keep track of complex interconnections between objects. See `src/include/Coder.h' for the abstract superclass interface; see `src/include/Coding.h' for the protocol adopted by objects that read and write themselves using coders. `Archiver' and `Unarchiver' are concrete subclasses that are used for writing/reading with files. `Coder's and `CStream's and `Stream's 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 `TcpPort'. This version of the distributed objects only works with sockets. A Mach port back-end should be on the way. See `doc/GNUstep-FAQ' for a detailed description of the cabilities and non-capabilities of GNU Distributed Objects. To begin using distributed objects, you only need to know about `Connection' class. You can see the full (documented!) interface in `src/include/Connection.h'. The long list of methods may be a little daunting, but actually, a lot can be done with just a few key methods: - (Connection*) newRegisteringAtName: name withRootObject: anObj; For registering your server object with the network. - (void) runConnection; For running the connection object returned by the above method, so that your server can start handling requests from clients. - (Proxy*) rootProxyAtName: name onHost: host; For connecting to a remote server. You get a proxy object for the remote server object, which, for messaging purposes, you can treat as if it were local. Where else to look ================== Examples -------- A few simple example programs can be found in `examples'. Read and enjoy. To compile them (after having compiled the library), type `make' in the `examples' directory. * `dictionary.m' demonstrates the basic features of the Dictionary object. * `stdio-stream.m' creates a StdioStream object that points to a file, writes to the file, then reads from the file. * `textcoding.m' shows how you can archive an object to a file in a human-readable text format, and then read it back in again. This format is handy for editing archived objects with a text editor, and is great when you want to modify/create an archive using a scripting language like `perl' or `awk'. * `first-server.m' and `first-client.m' show the distributed object version of "Hello, world". * `second-server.m' and `second-client.m' contain a more complex demonstration of distributed objects, with multiple clients, connection delegates, and invalidation notification. * `tcpport-server.m' and `tcpport-client.m' show a simple use of TcpPort objects. Test Programs ------------- Some of the programs I've used to test the library are in `./checks'. Many of them are pretty messy, (desperately trying to tickle that late night bug), but at least they show some code that works when the library compiles correctly. I'm looking for a volunteer to write some nicely organized test cases using `dejagnu'. Any takers? How can you help? ================= * Read the projects and questions in the `TODO' file. If you can volunteer for any of the projects, or if you have any useful comments send me email! <mccallum@gnu.ai.mit.edu> * Give me feedback! Tell me what you like; tell me what you think could be better. Send me bug reports. * Donate classes. If you write classes that fit in the libgnustep-base framework, I'd be happy to include them. Happy hacking! Andrew McCallum mccallum@gnu.ai.mit.edu
To: mccallum@cs.rochester.edu Subject: Re: Connection, Proxy Classes In-reply-to: Your message of "Fri, 04 Nov 1994 15:22:27 CDT." <199411042022.PAA13085@slate.cs.rochester.edu> Date: Tue, 08 Nov 1994 12:44:07 +1100 From: Masahiro Takatsuka <masa@judasa2.eng.monash.edu.au> Hello Andrew, I got libobjects and installed on DEC(Ultrix). A problem was that when I tried to compile checks/server.m, I got a error from "as0". After delete -g switch for compiling server.m, I successfully compiled it. I'd like to say "Thank you" for your work!!! Regards, Masa ============================================================================ Masahiro Takatsuka (MASA) e-mail: Masahiro.Takatsuka@eng.monash.edu.au(non-NeXTmail) ---------------------------------------------------------------------------- Intelligent Robotics Research Center :OzNeXT :xxxxxx Eng. Building 36, Room No. G04 :NeXus :92-00226 Department of Electrical & :CompuServe :71661,1331 Computer Systems Engineering :Nifty-serve :MGG1331 Monash University : Wellington Rd., Clayton :Tel.+61-3-905-5705 Victoria 3168, AUSTRALIA :Fax.+61-3-905-3454 ============================================================================ Date: Mon, 9 Jan 1995 14:03:21 -0700 (MST) From: Adam Fedor <fedor@mode.Colorado.EDU> Subject: Re: libobjects porting volunteers needed To: mccallum@cs.rochester.edu In-Reply-To: <199501092051.PAA06062@slate.cs.rochester.edu> Message-Id: <Pine.3.89.9501091354.C20349-0100000@mode.Colorado.EDU> Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On Mon, 9 Jan 1995 mccallum@cs.rochester.edu wrote: > > Did you look at README.ULTRIX in 0.1.2? > Yes. I also forgot to say that deleting the -g switch didn't help me, but deleting the -O switch did. Without this, I get the error: as0: Internal: server.m, line 1: scNil to scNil
Received: from cayuga.cs.rochester.edu (cayuga.cs.rochester.edu [192.5.53.209]) by slate.cs.rochester.edu (8.6.9/G) with ESMTP id LAA28657 for <mccallum>; Wed, 23 Aug 1995 11:56:35 -0400 Received: from mode.Colorado.EDU (mode.Colorado.EDU [128.138.248.167]) by cayuga.cs.rochester.edu (8.6.9/G) with ESMTP id LAA06539 for <mccallum@cs.rochester.edu>; Wed, 23 Aug 1995 11:56:34 -0400 Received: (from fedor@localhost) by mode.Colorado.EDU (8.6.12/8.6.11/UnixOps/Hesiod(SDM)) id JAA01294; Wed, 23 Aug 1995 09:56:31 -0600 Date: Wed, 23 Aug 1995 09:56:30 -0600 (MDT) From: Adam Fedor <fedor@mode.Colorado.EDU> Subject: Re: Georg Tuparev: include path To: Andrew McCallum <mccallum@cs.rochester.edu> In-Reply-To: <199508231454.KAA24578@slate.cs.rochester.edu> Message-ID: <Pine.3.89.9508230949.A1285-0100000@mode.Colorado.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII The OpenStep docs all have Foundation. It's a bit cumbersome to switch between them, but I assume when NeXT 4.0 comes out, they will have all switched to capital "Foundation". I don't really know though. For now I have this in my configure: AC_CHECK_HEADER(foundation/NSObject.h, found_objects=1 next_foundation=1, found_objects=0 next_foundation=0) if test $next_foundation = 1; then AC_DEFINE(NEXT_FOUNDATION) AC_DEFINE(NS_BLOCK_ASSERTIONS) fi and in each header file: #ifdef NEXT_FOUNDATION #import <foundation/NSObject.h> #else #include <Foundation/NSObject.h> #endif As I said, cumbersome, but it should work with ANY OpenStep complient foundation. [Alternatively, you could just make a soft link from `foundation' to `Foundation' -mccallum.]
Date: Fri, 3 May 96 11:10:16 +0200 From: Wolfgang Baron <wbaron@ixpoint.de> To: Adam Fedor <fedor@mode.colorado.edu> Subject: Re: NSAutoreleasePool and NSException problem > > I get: > > ... > test[10] = 100. > error: NSGCString (instance) > in characterAtIndex:, index out of range > Abort > > But when I change the count to 10 (at line 119 of the program), it works > fine. I don't see anything wrong with the program either. AAARGH!!!! I don't believe this. The problem was the following line, with which I compiled the program: gcc NSExceptionTest.m -L/usr/local/lib -lobjects -lobjc -L/usr/ucblib -lucb -lm Apparently, there are some serious bugs in the ucblib files. I changed the line to gcc NSExceptionTest.m -L/usr/local/lib -lobjects -lobjc -lm -lnsl And now it works just like under NeXTSTEP (even the rangecheck works)! Great! Maybe there should be some hint in a README file about linking code with libobjects.
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.