# Using the Freeware SDK

This document is an introduction to compiling with the Avigo Freeware SDK.

## Setup

First of course you need to unzip the
distributed SDK zip file, preserving the directory hierarchy. By that I mean be sure to use the -d option with the command line pkzip. (If you do use command line pkzip I recommend the much better freeware command line unzipper called simply unzip. It is distributed as part of the very nice Unix 95 Collection along with other Unix-like goodies such as 'gzip', 'rm', 'cp', 'mv' and more.)

Once you have unzipped you will have a directory structure that looks like this:

- avsdk
+- apps
+- bin
+- inc
+- lib

Gerard's free sdk is entirely command line based, so in order to make things easy you will need to have the avsdk\bin directory on your path. Under NT this can be done with the "System" control panel under "Environment". Under Win95 I think you have to put it in your autoexec.bat to make the change permanent. Or you can just say something like
   set PATH=%PATH%;C:\the\path\to\the\free\avsdk
At the command prompt you plan on using every time you start.

Just a note, you can also use relative paths, which can be handy and slightly more compact than full paths:

   set PATH=%PATH%;..\..\bin

## Building an App

Now let's try to build sokoban, which comes with the sdk. At the command prompt 'cd' to the avsdk\apps\sokoban directory. Now type 'avmake'. If your path has been set up properly, then avmake should produce a bunch of files including one called 'sokoban.app' You can use the Avigo Manager to send that over to your Avigo now, and try it out. Alternatively you can send it over with the great command line tool 'avapp' which Gerard includes in the SDK:
    avapp -p1 -rsokoban.app
(-p1 means use com1, -p2 com2, etc. -r means replace any existing sokoban.app that is already on the Avigo)

<...2 hours and 10 sokoban levels later...>

## Rolling Your Own

To make your own apps, the easiest way is to just copy the files for hellow or sokoban into a different directory, then edit them to suit your needs.

So what files are necessary? You need at least a .c file, a makefile, an icon.bmp file, and a .def file.

Copy the above files from, say, hellow, in a new directory for your app. Let's call it 'myapp'. Change the current directory to the new myapp directory with 'cd'.

1. Rename hellow.def to myapp.def
2. Rename hellow.c to myapp.c
3. Edit the makefile, replacing all occurrences of 'hellow' with 'myapp'. (On the 2nd and 3rd non-blank lines)
4. Edit myapp.def replacing all occurrences of 'hellow' with 'myapp'. The appname field is what the Avigo will use to refer to your app in the "Memory" applet's list of memory hogging apps. Of course, also change "G. Vermeulen" to whoever you are and the version to whatever version of your program this is.
5. Use an image editing program to edit icon.bmp. Do not change the size or the color depth. It must be a 2 color (black & white) bitmap to work on the Avigo.
6. Edit myapp.c to do what you want it to do. There are currently no API docs so for now you'll just have to figure it out by looking at the functions listed in avsdk/inc/avsys.h and by looking at various exapmple programs included with the free sdk and elsewhere on this site.
7. Type avmake to build your app. If it tells you of syntax errors, fix 'em and try avmake again until you get a .app file.
8. Use the Avigo Manager or avapp to send myapp.app over to your Avigo.
9. Try it out. If you're lucky your program won't crash the Avigo. If you're not lucky then you may have to reset the unit by poking a pin into the hole on the back. NOTE: it is VERY easy to make an app that won't exit. If you do, then reset is your only option, and that can be very time consuming. The lesson is to make SURE that your app will return from main() in response to some input.
Those are the basics. There are other factors that come into play if you want to draw sprites. I may write something up on that eventually, but for now examine sokoban to see how it handles sprite drawing.

## What's a Makefile?

At this point you can go ahead and start using the Freeware SDK to develop Avigo apps. But there may be one lingering question in your mind: "what the heck is a makefile?" You don't really need to know much about how makefiles work to use the SDK, but they are definitely worth figuring out. This section gives a brief introduction to make and makefiles to help you on your way to total enlightenment.

### Make Basics

A makefile is a list of rules which describe how to update targets based on their dependencies. In English that means "it says what to do when something needs to be done." Compiling programs is the most common use for make, but it can theoretically be used in any situation where something needs to happen when something else changes. Using make (or avmake) and a makefile is not necessary, just very convenient. If you use make you type this every time you wish to recompile:
    avmake
And if you don't you type something like this:
    avcp -I../../inc myapp.c | avcc > myapp.asm
avas myapp.asm
avlink -s -omyapp -b_code=0x4000 -b_data=0x8000 ../../lib/crt.rel myapp.rel
avmkapp myapp.def

In the old days before make I guess that's pretty much what people did. Fortunately you don't have to. You can use make and save your fingers for coding. But you won't just save your fingers work, you'll save your computer work too. That's becuase make automatically determines the minimal amount of work it has to do in order to update your program.

So how does make do it's magic? It's all in the rules. Rules take the form:

target: dependencies
actions

That says that target needs to be updated when any of the dependencies change by executing the actions. Typically targets and dependencies are files. Make figures out which dependencies have changed by comparing the last modified dates on the files: if the date on any of the dependencies is newer than that on the target then it knows it must execute actions. Otherwise it knows it doesn't have to do anything. That's how it saves your computer work. IMPORTANT: any actions must begin with a tab character. This is the source of many subtle bugs in makefiles.

Let's look at a concrete example from hellow's makefile:

$(appname).app:$(appname).s19 $(appname).def icon.bmp avmkapp$(appname).def

$(varname) is the syntax for using variables in makefiles. At the top of the file appears the line "appname = hellow", which tells make that it should replace any occurrence of$(appname) with the string "hellow". So lets do that ourselves:
hellow.app:hellow.s19 hellow.def icon.bmp
avmkapp hellow.def

This tells make that if any of hellow.s19, hellow.def or icon.bmp has changed more recently than hellow.app then hellow.app needs to be updated by executing the command "avmkapp hellow.def".

These lines are very similar:

$(appname).s19:$(rels)
avlink -s -o$(appname) -b_code=0x4000 -b_data=0x8000 ../../lib/crt.rel$(rels)

They say that hellow.s19 should be remade with that "avlink" command when any of the $(rels) change. That all makes sense, but what if we wanted to say that any file ending in ".c" should be compiled to become a ".rel" file? That's what these lines do: .c.rel: avcp -I../../inc$*.c | avcc > $*.asm avas$*.asm

The $* is a special variable which make automatically sets to be whatever file was found that ended in ".c" (without the ".c" part). ### Running Make You can make just a particular target by specifying it on the command line. For instance to make just the .s19 file for hellow and stop there, you can type avmake hellow.s19. If you don't specify a target a default is picked which in this case turns out to be the ".app". Usually the first rule specifies the default, I'm not sure why that's not the case in the makefiles that come with the free sdk. The important thing is that one rule can trigger other rules to be used too. For instance if you are trying to make hellow.app, make will see from the dependency list that it depends on hellow.s19. It will then search for a rule that has hellow.s19 as a target to see if it also needs to be updated. When it finds hellow.s19 as a target it checks its dependencies and looks if they are described by any targets, and so on. In this way eventually everything that needs to be updated gets updated. ### Special targets Targets don't have to be real files. There are two special targets in the hellow makefile: "install" and "clean". None of the default targets depend upon these targets, so they will never be invoked by simply running "avmake". They can, however, be invoked directly by typing "avmake install" or "avmake clean". Here is what those two rules look like: install: avapp -p2 -r$(appname).app

clean:
del *.s19
del *.rel
del *.asm
del *.app

The install target runs avapp to install the app on the Avigo using com port 2. If your Avigo cradle is not on COM2, then edit the makefile and change the -p2 to whatevery port you use. The clean target deletes all the files generated by the make process. One note: on my WinNT 4.0/SP3 machine, avmake exited with an error when it tried to invoke the "del" command. I'm not sure why, but after installing the
Unix 95 Collection and changing the clean target to use "rm" everything was fine:
clean:
rm *.s19
rm *.rel
rm *.asm
rm *.app

One final hint. If you have .c files that include certain .h files that you are likely to change from time to time, you can make a rule for that .c file that makes that dependency explicit so that make knows to recompile when the header changes:
myfile.rel: myfile.c myfile.h
avcp -I../../inc $*.c | avcc >$*.asm
avas \$*.asm


### Further Make References

If this intro to make leaves you thirsting for more, check out

Bill Baxter (Send mail)
Last updated: 15-Oct-1998