\chapter{Developing Software for AROS}

\section{Setting up}

To compile code for AROS, you only need the binary distribution and
a C compiler. If you use Linux, you should have everything neccessary
already, if you use Amiga, install the ADE development environment
(see \lref{ADE}{ADE}).

\section{Compiling}

\section{AROS extensions}

AROS makes a few extensions to the original AmigaOS. Some of them are
transparent and compatible, others are only compatible and some or not.

\subsection{Macros}

AROS defines a couple of macros in various header files. To enable them, you
must define |AROS_ALMOST_COMPATIBLE|.

\begin{description}
\item{NEWLIST(list)}
Compatible: Yes\nl
Location: \filename{exec/lists.h}

Initializes a list. You must not use any list before you have initialized
it.

\item{GetHead(list)}
Compatible: Yes\nl
Location: \filename{exec/lists.h}

Returns a pointer to the first node of a list or |NULL| if the list
is empty.

\item{GetTail(list)}
Compatible: Yes\nl
Location: \filename{exec/lists.h}

Returns a pointer to the last node of a list or |NULL| if the list
is empty.

\item{GetSucc(node)}
Compatible: Yes\nl
Location: \filename{exec/lists.h}

Returns a pointer to the next node of a list or |NULL| if there is none.

\item{GetPred(list)}
Compatible: Yes\nl
Location: \filename{exec/lists.h}

Returns a pointer to the previous node of a list or |NULL| if there is none.

\item{ForeachNode(list,node)}
Compatible: Yes\nl
Location: \filename{exec/lists.h}

Iterates through a list. A block of code must follow this macro. The
block doesn't get executed if the list is empty. When the list terminates
|node| doesn't contain |NULL| but |node->ln_Succ| will be NULL. You
cannot use this macro if you want to delete the nodes in the list (ie.
you must not call |Remove()| inside the block of code following the
macro).

\begin{code}
/* Iterate through a list with complete nodes and print their names */
t = 1;
ForeachNode(list,node)
{
    if (node->ln_Name)
    {
	printf ("Node %d: %s\n", t++, node->ln_Name);

	if (!strcmp (node->ln_Name, "end"))
	    break;
    }
}

if (node->ln_Succ)
    printf ("Not all nodes have been processed\n");
else
    printf ("The list doesn't contain a node with the name \"end\"\n");
\end{code}

\item{INTUITIONNAME}
Compatible: Yes\nl
Location: \filename{intuition/intuition.h}

Contains the name of the Intuition library. You should use this in
|OpenLibrary()|, for example, to avoid typos.

\end{description}

\subsection{Resource Tracking (RT) *Updated*}

Everyone talks about RT but what's it anyway ? RT means three things:

\begin{enumeration}
\item The OS takes notes about allocated resources (eg. memory, windows,
libraries, devices, screens, etc).

\item The OS checks the usage of those resources (ie. Did you open
that window you want to render into ? Is it still open ? Is that a
window anyway ?)

\item The OS closes resources if they are no longer used (either because your
program crashed or because it exited without freeing them).

\end{enumeration}

The current implementation can do all three things but to enable it,
you must make some modifications to your code. The only disadvantage of
the current implementation is that the resources won't be freed if the
program crashes.

\begin{enumeration}
\item Add the following
lines to your code. It should be the first thing seen by the compiler:

\begin{code}
#define ENABLE_RT  1
\end{code}

If you replace the |1| by |0|, then RT will be silently disabled.

\item Add |#include <aros/rt.h>| after the last include from \filename{proto/}

\item Add |RT_Init();| as the first command in |main()|.

\item Call |RT_Exit()| before you terminate your program.

\item Recompile.

\end{enumeration}

The advantages are that you will get errors if you try to access
resources which you didn't allocate and that you will get a list
of resources which you didn't free at the end of your program.
All messages will contain the position in the code where the error
happened (if available) and the position in the code where the
resource was allocated (this is the reason why RT has to be compiled
in. It could be built into the OS, too, but it would be hard
to gather the information where an error occurred).

A good example about how to use RT and what it can do can be
found in \filename{AROS/workbench/demos/rtdemo.c}
(\link{Output of rtdemo}{rtdemo.log}).

The following resources are tracked:

\begin{itemize}
\item Memory in |AllocMem()|, |FreeMem()|, |AllocVec()| and |FreeVec()|

\item MsgPorts in |CreateMsgPort()|, |DeleteMsgPort()|, |CreatePort()|,
|DeletePort()| and |PutMsg()|

\item Files in |Open()|, |Close()|, |Read()| and |Write()|. |Read()| and
|Write()| also check their buffers.

\item Windows in |OpenWindow()|, |OpenWindowTags()|, |OpenWindowTagList()|,
|CloseWindow()|, |WindowToFront()|, |WindowToBack()|

\item Screens in |OpenScreen()|, |OpenScreenTags()|, |OpenScreenTagList()|,
|CloseScreen()|, |ScreenToFront()|, |ScreenToBack()|. |CloseScreen()| also
checks for open windows on the screen before closing.

\end{itemize}