Chapter 3: Compiling the Application

In the previous chapter, we put together a very simple application in C using OSLib to access the parts of the Wimp that we required. Before it can be tried out, we’ll need to compile it – we’ll look at how to do that now.

There are two choices of compiler when it comes to using C on RISC OS: the port of GCC, and CC which comes as part of the Desktop Development Environment (or DDE) from RISC OS Open Ltd (which is more usually refered to as “Norcroft” after its original authors: Arthur Norman and Alan Mycroft). In this tutorial we’re going to concentrate on the DDE, since that’s the ‘native’ compiler and that one that’s still used for all OS development.

Once installed, the DDE consists of two main folders on the hard disc: AcornC/C++ in the root directory, and DDE within Apps – both are shown in Figure 3.1. Other folders are also included in the install: the most important are probably the DDE manuals folder which is placed in Documents and Sources which is placed in the root directory of the disc.

Figure 3.1: The main contents of the DDE

Installing OSLib

To be able to compile our application, we’ll also require the OSLib library to be available: this doesn’t come as standard with the DDE, but is easily obtained from the OSLib website. Follow the link to the Zip Archives and then on to the latest release – at the time of writing, this was Version 7.00. From the “Library downloads” section, fetch the version of OSLib for “Acorn/Norcroft and GCCSDK GCC 3.4.x”; for this tutorial, there’s no need to download OSLibSupport. It’s a good idea to also download the StrongHelp manual from the “Other downloads” section: this documents all of the functions, types and constants defined by the library.

With the two zip files downloaded from the OSLib site, the files shown in Figure 3.2 should now be available. Note that the screenshot shows version 7.00: the filenames – and contents – of the archives may vary in future releases.

Figure 3.2: The OSLib library (version 7.00 here) comes in two separate archives

There’s no set way to install OSLib, so it’s very much a matter of personal preference. In this case, we’ll copy the contents of the main OSLib archive into a folder called OSLib which has been created in the AcornC/C++ folder as shown in Figure 3.3. This keeps the library together with the other DDE resources. The StrongHelp manual can be put wherever we like: storing it with the documentation, or with other StrongHelp manuals, might be a good idea.

Figure 3.3: The OSLib files installed ready for use

In the OSLib folder that we’ve just created is an Obey file called SetVars;. In a similar way to the DDE’s !SetPaths application, SetVars must be run (or double-clicked) before attempting to use OSLib in a compilation.

Creating a project

To get our new project started, we’ll begin by launching the DDE and setting up OSLib. Open the AcornC/C++ folder and double-click on !SetPaths to set up the DDE environment (as shown in Figure 3.3); next open the OSLib folder and double-click on SetVars to do the same for OSLib. These actions set up system variables which will allow all the necessary files and resources to be found until the machine is shut down or reset.

The next thing to do is to create a home for the files that form our new application: for now, that’s just a single text file containing the C source code introduced as Listing 2.1 in the previous chapter. Using Zap, the result will look something like that shown in Figure 3.4.

Figure 3.4: The listing typed into Zap

Next, we need to set some folders up on disc to take the project and all its files. Create a folder somewhere to house the project – here we’ve called it SimpleCApp – and inside it create three more folders called c, h and o. Save the text file as main inside the c folder, as shown in Figure 3.5.

Figure 3.5: The project folders on disc

The three folders are used to get around the lack of filename extensions in RISC OS: while compilers on other systems would tend to put a ‘.c’ extenstion on the end of C source files (main.c in our case), the DDC stores them without extensions inside folders. Thus the ‘.c’ files live in the c folder, ‘.h’ files in the h folder, and so on.

At present our project is simple enough not to need any header files, but we’ve created an h folder for them ready for when we do need it. The o folder will take any object files (whose names would end with ‘.o’ on other systems) created during the compilation. A complete set of the project’s files can be found in Download 3.1.

Download 3.1
The source code and files in this example are licenced under the EUPL v1.1.

Compiling the code

To compile the code, we’re going to use the CC compiler that comes with the DDE. Assuming that the environment has been installed in its default state (as described above), go to the Apps folder on the hard disc, then into DDE, and double-click on !CC to install it on the iconbar.

Drag the main file from our project on to the iconbar icon to open the CC window: the Source field should show the full filename. As standard, the compiler is set up to use just the libraries shipped with the DDE – those which form ‘standard’ C, along with those forming the standard RISC OS development environment. Our application also uses OSLib, and as it’s a third-party library – albeit a commonly used one – we’ll need to tell CC how to find it. The first step is to locate the header file referred to by the

#include "oslib/wimp.h"

at the top of the file.

When run, the SetVars obey file in the OSLib folder sets up a couple of system variables to point to the library: OSLib$Path and OSLib$Dir. For the instalation shown in Figure 3.3, these are set as shown in Figure 3.6.

Figure 3.6: OSLib’s SetVars creates two system variable to point to the library

Since the OSLib folder pointed to by these variables contains another folder called oslib which in turn holds all of the library’s header files, telling the compiler to ‘include’ OSLib: will ensure that the #include works as intended (since wimp.h can be found at OSLib:oslib.h.wimp). We therefore need to add OSLib: to the comma-separated list in the Include field as shown in Figure 3.7.

Figure 3.7: OSLib needs to be added to the list of include paths known to CC

It’s also necessary to tell CC where to find the OSLib library itself: click Menu over the CC window, slide over Libraries and add OSLib:o.OSLib32 to the start of the comma-separated list as shown in Figure 3.8.

Figure 3.8: The OSLib file itself must also be added to the list of libraries

With the OSLib library set up, click on Run to start the compilation. A throwback window will open and, if there are no errors, a save dialogue will appear as shown in Figure 3.9. Clicking OK will by default save the file in the project folder.

Figure 3.9: Compiling and saving the code

The main application can now be run by double-clicking on it: if all goes well, it should perform exactly the same as the original BASIC application shown in Figure 1.1.