  GGI Namespace rules
  Andreas Beck, Anderas.Beck@ggi-project.org
  $Date: 1998/07/01 12:18:15 $

  This document describes the "anti-namespace-pollution" rules for GGI.
  It contains hints about writing partable code as well.
  ______________________________________________________________________

  Table of Contents


  1. Preface

  2. Namespace rules

     2.1 Objective C
     2.2 C++
     2.3 GlibC
     2.4 Others

  3. Some additional portability comments



  ______________________________________________________________________

  1.  Preface

  We had several problems with programs not compiling on some
  architectures or compilers or problems with some language wrappers, as
  we had conflicting identifiers in some places.

  This document is an attempt to rectify this situation.


  2.  Namespace rules


  o  Anything that GGI exports to the world shall be prefixed with ggi_,
     ggi, Ggi or GGI (kgi_, kgi, Kgi or KGI respectively) as it would be
     done for other prefixes of the object in question.

  o  As an exception to this we allow things that should have only one
     common meaning like uint16 being an unsigned integer of 16 bit
     precision.

  o  enums and #defines used for bitfields and enumerations should be
     prefixed with GGI_ plus a shorthand of the fieldname they are used
     for.  E.g. GGI_GT_8BIT where GT is short for graphictype.

  There are some languages which are fairly C compatible and can make
  use of the #includes and the native calling interface without an
  intermediate wrapper. They have some keywords we should not touch (NOT
  AT ALL - even, if the code is never exported). The same applies for
  some functions/ variables of some common libraries.

  We have violated this rule in the past, so the cases where this has
  happened are marked with an old_name -> new_name entry to help porting
  old applications which suddenly break.

  All names on the left side of such rules and all other mentioned below
  are to be avoided.

  Please report all other namespace conflicts you encounter, so we can
  fix it.

  2.1.  Objective C


     self
        -> slf  (done)


     super
        o.k.

     nil
        o.k.

     Class
        o.k.

     SEL
        o.k.

     IMP
        o.k.

     BOOL
        o.k.

     Object
        o.k.

     NS*
        o.k.


     YES
        used in SVGAlib. Probably o.k. - not our problem.

     NO used in SVGAlib. See YES.


     id used throughout the source ... particularly EvStack.


  2.2.  C++


     inline
        C reserved word. o.k.

     const
        C reserved word. o.k.

     catch
        o.k.

     delete
        o.k.

     dynamic_cast
        o.k.

     explicit
        o.k.

     false
        o.k.


     friend
        o.k.

     mutable
        o.k.

     namespace
        o.k.

     new
        o.k. (once used in display.c, but that' in the kernel patch, so
        ...)

     operator
        o.k.

     protected
        o.k.

     public
        o.k.

     static_cast
        o.k.

     template
        o.k.

     throw
        o.k.

     true
        o.k.

     typeid
        o.k.

     typename
        o.k.

     using
        o.k.

     this
        o.k.

     try
        o.k.


     bool
        o.k

     class
        EvStack uses this. Should we allow C++ there ? (->clss)


     private
        -> priv (still used in kernel drivers ... well - they aren't
        C++)

     virtual
        -> virt



  2.3.  GlibC


     index
        -> ggiindex  (done)


  2.4.  Others


     ggi_sint, ggi_uint
        ???

     real
        These are commonly used for about anything ... Maybe prefix with
        ggi


  3.  Some additional portability comments


  Try to avoid :


  o  macros with variable number of arguments (gcc specific)

  o  iusing ' in macros (gcc doesn't like it) (i.e. no #error Didn't
     work !)

  o  inlining functions (gcc specific) (if you do, try to provide a
     fallback .c file)

  o  avoid doing things like

     (void *) struct->ptr = my_pretty_function;

     and instead declare arguments like :

     struct->ptr = ((int *)(int,int,int)) my_pretty_function;

  o  doing arithmetic on (void *) like in void *bla;*(bla+10)=blubb;.
     This is GCC specific and very confusing.

  o  If you write shell scripts, always use /bin/sh

  o  As most Linux-systems have /bin/sh symlinked to bash this won't
     help that much. I suggest that if you want to write/modify scripts
     you install at least one other Bourne-style shell and test your
     code with it.

  o  Never make ANY assumptions about the size of datatypes!  If your
     code depends on a datatype being of a certain size, use the
     [us]int* datatypes.

  o  Do NOT use uchar, ushort, uint or ulong! Those are very non-
     standard datatypes. Either use one of the GGI datatypes or unsigned
     <type>.

  o  Don't use gcc specific stuff unless you're writing code that is
     expected to be compiled with gcc only (ie. Linux kernel code)






