AOF Examples (v1.01 14 Oct 1997)
------------
These are some 'simple' examples of how AOF code can be used. There's no useful code here really because I've only used JFPatch for linking with C, and as an
alternate CMHG type program. However, there is a large amount of JFPatch code
in my GMail program (well, 5 or 6 functions) so it /does/ work...

For examples of how you might write library routines, see !JFPatch.Libraries.
I'm working on porting some of the simple libraries towards C so that it may
be possible to do 'something' with them. malloc and free and probably the
most important of these and they seem to work perfectly at the moment.

JFPatch code is contained in a j directory. This will be compiled directly
into an object aof file, launching the intermediate Basic code required
without any intervention. The object file will have the same name as the
source file /regardless/ of the out directive (iff the AOF source is in the j
directory, otherwise the OUT name will be used).

To use with Make, you should add the following to !Make.choices.tools :
--8<--------
JFPatch
j
-depend !Depend -throwback -out $@
JFPatch -in $< $(jfpatchflags)


--8<--------

To link with C code you will probably want to include JFP:, generate 'module
code' and use the 'non-software stack checking' variant of apcs (other->
'-apcs /noswst'). Also you'll probably want to set link to 'Module'.
In summary, CCflags += -IJFP: -zM -apcs /noswst 
            Linkflags += -rmf

The examples currently available are :

MainTest  My 'main test' routines - this is the major test program I'm using
          as the base line of what's stabley supported. Even then I don't
          guarentee anything.
          At the moment this program calls C code and tests that the returns
          are ok. There is also a test of the inverse.
History   This is a larger test and I've not examined it carefully enough to
          see what's actually happening, but it seems ok. History is a simple
          library I wrote in C for Chris Johns' IRC client - he's not used it
          but what the hell :-) - and with no modifications except for the
          includes it seems to work fine with JFPatch.


Supported things
----------------
 * Export of labels                          +++ SAFE +++
   .|label|
 * Export of labels renamed as exported       +++ OK +++
   .|label->newname|
 * PC relative relocations (jumps)           +++ SAFE +++
   B[L]<cc>  |label|[+<anything>]
 * Extended B/SWI with APCS                  +++ SAFE +++
   X[BL|SWI]<cc>   |label|,<apcs reg>*
 * Word/Double/Byte import of symbols        +++ SAFE +++
   EQUD      |label|[+<anything>]
 * Constant setting (in Pre)                  +++ OK +++
   |label| = <value>
 * Multiple areas                            +++ SAFE +++
   # AREA "<name>" [CODE] [READONLY] [SWSTK] 
 * Direct relocations in Module definition    +++ OK +++
   Init    |<label>|
 * Debug areas                                +++ NA +++
   Type    AOF Debug


Meanings of comments
--------------------
  +++ SAFE +++   : I trust this to work and have had no problems in recent
                   times.
   +++ OK +++    : This seems to work, but has not been extensively tested -
                   trust it until something breaks, then assume that it is
                   at fault.
+++ UNTESTED +++ : This may have had a test or two on it, but never anything
                   that might be even vaguely called rigorous.

   +++ NA +++    : This is not currently available, but planned. There 'may'
                   be partial support in the compiler, but this is almost
                   guarenteed not to work.

