libobjc/README

   1
   2 GNU Objective C notes
   3 *********************
   4
   5 This document is to explain what has been done, and a little about how
   6 specific features differ from other implementations.  The runtime has
   7 been completely rewritten in gcc 2.4.  The earlier runtime had several
   8 severe bugs and was rather incomplete.  The compiler has had several
   9 new features added as well.
  10
  11 This is not documentation for Objective C, it is usable to someone
  12 who knows Objective C from somewhere else.
  13
  14
  15 Runtime API functions
  16 =====================
  17
  18 The runtime is modeled after the NeXT Objective C runtime.  That is,
  19 most functions have semantics as it is known from the NeXT.  The
  20 names, however, have changed.  All runtime API functions have names
  21 of lowercase letters and underscores as opposed to the
  22 `traditional' mixed case names.
  23         The runtime api functions are not documented as of now.
  24 Someone offered to write it, and did it, but we were not allowed to
  25 use it by his university (Very sad story).  We have started writing
  26 the documentation over again.  This will be announced in appropriate
  27 places when it becomes available.
  28
  29
  30 Protocols
  31 =========
  32
  33 Protocols are now fully supported.  The semantics is exactly as on the
  34 NeXT.  There is a flag to specify how protocols should be typechecked
  35 when adopted to classes.  The normal typechecker requires that all
  36 methods in a given protocol must be implemented in the class that
  37 adopts it -- it is not enough to inherit them.  The flag
  38 `-Wno-protocol' causes it to allow inherited methods, while
  39 `-Wprotocols' is the default which requires them defined.
  40
  41
  42 +load
  43 ===========
  44 This method, if defined, is called for each class and category
  45 implementation when the class is loaded into the runtime.  This method
  46 is not inherited, and is thus not called for a subclass that doesn't
  47 define it itself.  Thus, each +load method is called exactly once by
  48 the runtime.  The runtime invocation of this method is thread safe.
  49
  50
  51 +initialize
  52 ===========
  53
  54 This method, if defined, is called before any other instance or class
  55 methods of that particular class.  For the GNU runtime, this method is
  56 not inherited, and is thus not called as initializer for a subclass that
  57 doesn't define it itself.  Thus, each +initialize method is called exactly
  58 once by the runtime (or never if no methods of that particular class is
  59 never called).  It is wise to guard against multiple invocations anyway
  60 to remain portable with the NeXT runtime.  The runtime invocation of
  61 this method is thread safe.
  62
  63
  64 Passivation/Activation/Typedstreams
  65 ===================================
  66
  67 This is supported in the style of NeXT TypedStream's.  Consult the
  68 headerfile Typedstreams.h for api functions.  I (Kresten) have
  69 rewritten it in Objective C, but this implementation is not part of
  70 2.4, it is available from the GNU Objective C prerelease archive.
  71    There is one difference worth noting concerning objects stored with
  72 objc_write_object_reference (aka NXWriteObjectReference).  When these
  73 are read back in, their object is not guaranteed to be available until
  74 the `-awake' method is called in the object that requests that object.
  75 To objc_read_object you must pass a pointer to an id, which is valid
  76 after exit from the function calling it (like e.g. an instance
  77 variable).  In general, you should not use objects read in until the
  78 -awake method is called.
  79
  80
  81 Acknowledgements
  82 ================
  83
  84 The GNU Objective C team: Geoffrey Knauth <gsk@marble.com> (manager),
  85 Tom Wood <wood@next.com> (compiler) and Kresten Krab Thorup
  86 <krab@iesd.auc.dk> (runtime) would like to thank a some people for
  87 participating in the development of the present GNU Objective C.
  88
  89 Paul Burchard <burchard@geom.umn.edu> and Andrew McCallum
  90 <mccallum@cs.rochester.edu> has been very helpful debugging the
  91 runtime.   Eric Herring <herring@iesd.auc.dk> has been very helpful
  92 cleaning up after the documentation-copyright disaster and is now
  93 helping with the new documentation.
  94
  95 Steve Naroff <snaroff@next.com> and Richard Stallman
  96 <rms@gnu.ai.mit.edu> has been very helpful with implementation details
  97 in the compiler.
  98
  99
 100 Bug Reports
 101 ===========
 102
 103 Please read the section `Submitting Bugreports' of the gcc manual
 104 before you submit any bugs.