ROVLib Tutorial - Basics
© Jason Tribbeck 2002
ROVLib Tutorial - Basics© Jason Tribbeck 2002 |
|
This tutorial will show you the basics of an ROVLib application, and also test your system configuration to see if you can compile applications to use ROVLib.
The code will be built upon, until we have created a useful application - a simple DrawFile previewer.
The application we will be creating will be the simplest of all applications - namely something that will sit as a RISC OS application in the task manager and wait until it is told to quit.
The first thing to do is to look at the MakeFile:
# File: makefile
# Jason Tribbeck
# MakeFile for a ROVLib tutorial
THROWBACK = -ThrowBack
# Usual compiler stuff
CC = cc
ASM = objasm
DRLINK = drlink -no
ALINK = drlink -m -no
CCFLAGS = -c -Depend !depend -IROV: -IC: $(THROWBACK)
ASMFLAGS = -Depend !depend -quit $(THROWBACK)
# Libraries:
LIB = C:o.stubs ROV:o.ROVLib
# Objects:
BAOBJS = BasicApp.o
default: BasicApp
BasicApp: $(BAOBJS)
$(DRLINK) -o $@ $(BAOBJS) $(LIB)
.c.o:
$(CC) $(CCFLAGS) -ff -zps1 $*
.s.o:
$(ASM) $(ASMFLAGS) -o $@ $<
# Static dependencies:
# Dynamic dependencies:
The lines of interest have been highlighted in red.
The first rule in this MakeFile is the default rule. This is telling us
that we will be building a file called BasicApp. Later tutorials may
build more than one object file, but since this is the first tutorial, we'll keep it
simple.
BAOBJS is set to include one object file, namely BasicApp.o.
This one object file is generated from a C file called BasicApp.c.
If you've never seen a rule such as .c.o or .s.o, then this
is basically saying "In order to build a .o file from a .c
file, then this is the rule that we will be using." It allows us to create a
shorthand for common rules.
Finally, in order to build BasicApp, we need the object list, or just
BasicApp.o built, and then linked with ROVLib as well as the SharedCLibrary
stubs (C:o.stubs).
The source code for this simple application is very simple:
/**
* BasicApp.c - a very basic application using ROVLib
*/
/* Include 4 standard C header files */
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <ctype.h>
/* Include the RISC OS kernel header file */
#include "kernel.h"
/* Include the ROVLib header files */
#include "main.h"
int main(int argc, char **argv) {
/* Initialise the ROVLib system */
main_init("A basic application");
/* Poll forever (or at least until told to quit!) */
main_poll();
}
Again, the interesting lines have been highlighted in red.
After including a few standard header files, we include the ROVLib main.h
header file. This header file contains the function prototypes for the core of the ROVLib
system, but we are only using the task initialisation and task polling parts of it.
The first actual piece of code we call initialises the task as a ROVLib application. The
string "A basic application" is the name of the task that is displayed in
the RISC OS task manager.
The last piece of code will poll the WIMP awaiting events to take place. Since ROVLib is designed to perform as much of the more tedious work for you, you do not have to wrap the function around a loop, nor do you have to listen for events yourself (unlike other libraries). Internally, ROVLib performs the polling loop, as well as listening for the important WIMP events.
As you can see, there really isn't a lot to it.
You can use something like !AMU to compile it up - simply drop the MakeFile
onto the AMU icon, and it will compile up. If everything goes nicely, you'll end up with
the output looking like:
cc -c -Depend !depend -IROV: -IC: -ThrowBack -ff -zps1 BasicApp Norcroft RISC OS ARM C vsn 5.05 (Acorn Computers Ltd) [Jan 11 1995] drlink -no -o BasicApp BasicApp.o C:o.stubs ROV:o.ROVLib Drlink AOF Linker Version 0.34 01/02/98
If it didn't go nicely, then you'll probably end up with:
cc -c -Depend !depend -IROV: -IC: -ThrowBack -ff -zps1 BasicApp Norcroft RISC OS ARM C vsn 5.05 (Acorn Computers Ltd) [Jan 11 1995] "c.BasicApp", line 16: Serious error: #include file "main.h" wouldn't open "c.BasicApp", line 19: Warning: inventing 'extern int main_init();' "c.BasicApp", line 22: Warning: inventing 'extern int main_poll();' c.BasicApp: 2 warnings, 0 errors, 1 serious error AMU: *** exit (1) *** AMU: *** 'default' not re-made because of errors ***
If this is what you got, then you need to ensure that you have a system variable
ROV$Path set to the location of your ROVLib binary files. What I have done
in the past is create a simple Obey file:
Set ROV$Path <Obey$Dir>.
This file is saved inside the ROVLib binary directory, called anything you want (I call
mine "!" for convenience), and run it before the first time you compile
anything using ROVLib. A much better alternative is to put this in your !Boot
sequence, so you do not need to remember to run it each time.
Simply running the !BasicApp Obey file will run the BasicApp
compiled application. You won't see anything appear (we haven't got on to that part
yet), so you may think that it hasn't actually done anything. However, if you look at
your RISC OS Task Manager's window, you will see that there is an application called
"A basic application".
If you take a look at the following screenshot, you will see that among my applications is the basic application task:
Press MENU over the application name in the task manager, and go to the right of "Task 'A basic application'", and choose "Quit". This will cause the basic application to die.
One of the design goals of ROVLib was that it should produce applications of minimal size. This application, when compiled using DRLink with the "-nounused" flag enabled has created an application of just under 10K. It is quite large if you consider that if you were to use a pure SWI interface it would have been 4-5K, but it is doing a lot more than just initialising and polling (the equivalent BASIC program would be around 200 bytes!). The extra functionality we will be coming on to in later tutorials.
Note that using !Squeeze, this application becomes just 5K in size.
This tutorial has shown you how to create and compile a very basic application using ROVLib.