D) Mixed Binaries
=================

Actually there are two similar ones:

1) Mixed Binaries

These files contain both PPC and 68k code. Some functions (the ones
that will profit most of the PPC) are done in PPC Code, others in
68k Code. Mixed Binaries are useful for "quick porting", especially
concerning Projects that were 100% 68k ASM at the start.

2) Fat Binaries

These contain PPC and 68k versions of ALL functions of the program.
The program runs on PPC-Systems and 68k systems (big advantage), but
the executable size is twice the normal size. Before you start a
Fat Binary, think, if using two versions with two different project
files (and two executables) is not better for your purpose. Fat Binaries
are a bit more complicated to code and really ... BIG.

The main interesting application for Fat Binaries are "Mixed-Fat-Libraries",
like described in the document libs.txt.

This document explains how to create Mixed and Fat Binaries. I assume you
already read c.txt.

1) Mixed Binaries
-----------------

The principial steps to create a Mixed Binary would be:

- Start a StormC Project File
- Select Mixed Binary and Amiga-OS Mixed Binary and Debugversion as Options

It is VERY important that, when the Mixed Binary is compiled for the first
time, it is compiled with "Debugversion" enabled. StormC needs this to create
the files for the Automatic Contextswitch. Later compiles, after the initial
one, don't need anymore "Debugversion" to be set then, so you can change
the Options in the StormC Settings after the initial compile, if you want.

Now StormC will create two project Files, one of them having the ending _PPC.
The PPC Project will be included into the 68k Project by StormC. Now you code
all files, that should be PPC-Native into the PPC-Project, and all files, that
should be 68k, into the 68k-Project.

- Then you compile the PPC Project
- After this you include the object file(s) of the PPC Project to the 68k
  Project (important !!!)
- Now you compile the 68k project, and everything is done.

Note, that you do not need any "special PPC Stuff", everything is done automatically
by the Compiler. Of course you have to follow the general guidelines as to
PPC Coding (for example not using 68k registers in PPC Code) like outlined in c.txt.

Think careful about:

- Does this program make sense as Mixed Binary ? (Would using two project files,
  one for 68k, one for PPC, not make more sense ?)
- Which functions make sense for putting them into PPC Code

Note:

- 68k and PPC can SHARE their Global Variables. You simply do a extern-declaration
  in the other module.
- main() is always in 68k, in a Mixed Binary

Example:

test.c
------

int bla=3;
void main
{
 ppctest();
}

test_PPC.c
----------

#include <stdio.h>

extern int bla; // Global Variable Sharing

void ppctest(void)
{
 printf("%i\n",bla);
}

2) Fat Binaries
---------------

The main difference between Fat Binaries, is, that (nearly) all functions exist in two versions,
one for 68k, one for PPC. For an 68k system always the 68k version will be used, for
a PPC Systems, sometimes the PPC version will be used. Note, that sometimes 68k functions
might be used even on a PPC System (in functions that contain a LOT of OS-Calls for example,
to reduce the number of Contextswitches). Reducing Contextswitches is REALLY important.

Example:

test.c
------

#include <clib/exec_protos.h>
#include <pragma/exec_lib.h>
#include <exec/libraries.h>

struct Library *PowerPCBase=0;

void test68k()
{
 printf("68k!\n");
}

void main()
{
 PowerPCBase=OpenLibrary("powerpc.library",7);
 if (PowerPCBase) testPPC();
 else test68k();
}

test_PPC.c
----------

void testPPC()
{
 printf("PPC!\n");
}

Note, that an easier way exists to find out if a 68k or a PPC System exists... this
example is only for example purposes :)

As you see, doing a Fat Binary is some work. Consider doing two versions (one for 68k,
one for PPC, using the __PPC__ for special code) instead. The Source will look much
better and easier portable this way. But well, Fat Binaries HAVE their advantages
(especially when used for Shared Libraries, see libs.txt about this).

One last note:

The Automatic Contextswitch cannot switch to functions with register-parameters
(the only exeption for this rule are Shared library functions, which it CAN handle,
even as register-parameters are used). If you need to call a 68k function with
register parameters that is NOT a Shared Library function, there are two ways:

A) calling a 68k function without register parameters, which then calls the
   function WITH register parameters.
B) Doing a manual Contextswitch

Note, that A) or B) also has to be used, if you want to call a 68k Shared Library
function inside of the IMPLEMENTATION of the library (once the library is compiled,
you do not need A) or B), the Automatic Contextswitch can then handle this).

For more information about Shared Libraries, read libs.txt.