Suggestions

[Jonathan Coxhead]

 | Firstly, I'm a bit uncomfortable about this use of |bool| in any 
case.
 | Wouldn't a better way be to typedef our own boolean operator, e.g.
 | |typedef int BOOL| and then use that throughout the library code. 

   Hold on, hold on!

   |bool| **is** "our own boolean operator"!

   I don't want to see a situation where we end up with 
"OSLibBoolean_Type", as well as "OSLibInclude$Path"!

   If other libraries use "bool", we have to come up with some 
solution to enable us to work together, but I think this is best done 
in a case-by-case basis. 

   This issue is complicated by the fact that the new C standard 
(C99) defines a boolean type. We should use this in C99 systems. 
Luckily, the name they chose was "bool", so to get that part of it 
right, all we would have to do is replace, in "types.h"

      typedef int bool;
      #ifndef FALSE
      #define FALSE ((bool) 0)
      #endif
      #ifndef TRUE
      #define TRUE ((bool) 1)
      #endif

with

      #if defined __STDC_VERSION__ && __STDC_VERSION__ >= 199901L
      #include <stdbool.h>
      #define TRUE true
      #define FALSE false
      #else
      typedef int bool;
      #ifndef FALSE
      #define FALSE ((bool) 0)
      #endif
      #ifndef TRUE
      #define TRUE ((bool) 1)
      #endif
      #endif

 | In order to ensure the interface doesn't break, we could then 
|typedef
 | bool BOOL|, wrapped up in an ifdef as Ainsley proposes (but with an
 | extra test || !defined( BOOL_UNDEFINED ) ) and let the user decide
 | whether or not he wants to define bool himself.
 | 
 | That would make the library's use of BOOL independent of any
 | compiler's definition (or not) of bool.

   But it wouldn't do much for libraries that happen to use |BOOL|, 
of which there are doubtless many.

   The whole subject booleans in C is a complicated one, because they 
are not provided by the language, but most libraries want to provide 
one. Spellings I myself have seen include |bool, Bool, BOOL, _Bool, 
boole, boolean, Boolean|, with values |true, True, TRUE, false, 
False, FALSE|.

   C99 attempts to reduce the confusion by specifying |bool, true, 
false|, and I suppose we should converge on those. Definitions I've 
seen include

      static int const false = 0;
      static int const true  = 1;
      #define false 0
      #define true  1
      enum {false, true};

and others. There is also a standard way to identify the C version, 
which I wrote out above.

   It might be good to use |true| and |false| throughout the next 
release (though also still defining |TRUE| and |FALSE|, as used at 
the moment, to avoid breaking any old code).

   The issue is further complicated by the fact that---as well as 
every libraries getting in their own favourite definitions---OSLib is 
designed to be usable as source code in 5 different *languages*:

      C89
      C99 (if we like)
      C++
      GNU C (based on C89, but extended a lot)
      GNU C++

   (We have no intention of supporting pre-1989 C source, i e, no 
prototypes.)

   We should solve the issue at the langauge level first, then work 
out how to coexist with other important libraries. I don't know what 
the most reliable mechanism is for distinguishing these. How about

      #if defined __cplusplus
         #if defined __GNUC__
            ... GNU C++ code here ...
         #else
            ... C++ code here ...
         #endif
      #else
         #if defined __GNUC__
            ... GNU C code here ...
         #elif defined __STDC_VERSION__ && __STDC_VERSION__ >= 199901L
            ... C99 code here ...
         #else
            ... C89 code here ...
      #endif
      #endif

   Does that work in all known cases?

   Then the facilities are:

      C++, GNU C++: |bool, true, false| are all built-in
      C99:          |bool, true, false| are provided in <stdbool.h>
      C89:          Must roll your own (we use |int, TRUE, FALSE|)
      GNU C:        Don't know. Any info available?

 | Secondly, I'm also a bit uncomfortable about the use of the
 | (undocumented) macro __swi, which is only applicable to a single
 | compiler, itself no longer maintained, and probably no longer the
 | mainstream compiler for the platform. How much real benefit does it
 | bestow on the library code?

   This is what it says in the readme:

 | * (*Experimental*) Use inline SWIs where possible: 252 out of 2429
 | SWI veneers happen to be A P C S-conforming, and may be replaced
 | by single SWI instructions in the caller. Only supported by
 | Norcroft C release 5, but enabled by default: IF YOU ARE NOT USING
 | NORCROFT C RELEASE 5 OR LATER, you must disable the feature by
 | using the -D__swi option on the compiler command line (e g, 
 |
 |       cc -D__swi c.progfile
 |
 | with a hyphen, a capital 'D', 2 underscores, and 'swi' in lower
 | case). You must also do this when using C++ via CFront (which
 | doesn't understand it either). The reason this feature is
 | experimental is that the relevant flavour of A P C S requires that
 | function calls should preserve flags, which is not guaranteed (an
 | inlinable SWI will always be an x-clear SWI, and will therefore
 | definitely clear V). If this is a problem in practice, the feature
 | will be reviewed. 

   So, it only works with Norcroft C---surely still used?---and it 
saves a few instructions. But notice that, even in this early form, 
it is technically in violation of the flavour of A P C S that it 
ought to be conforming to: A P C S says that the call must preserve 
flags, and the SWI might not. I went ahead with it anyway, because 
one of the people working in the compiler group told me that the 
compiler did not rely on the flags being preserved anywhere, so it 
was safe. This is not a very firm guarantee!!

   Maybe Stewart could comment on whether it's still worth it?

 | I proposed previously that it should be dropped entirely, but got 
no
 | response. Would it be worth considering this?

   Certainly. It's very cute technology, but it might not be worth 
saving. If you compile the canonical RISC O S "Hello, World" 
programme:

      #include "os.h"

      int main (void)
      {
         os_write0 ("Hello, World!\r\n");
         return 0;
      }

you get the snappy

              ADR     R0, hello
              SWI     OS_Write0
              MOVS    PC, LR
      hello   =       "Hello, World!\r\n"

for a total of 12 bytes of code. It's very clever---but is it useful?

        /|
 o o o (_|/
        /|
       (_/