www.riscos.com Technical Support: Acorn C/C++

CC and C++

CC is a desktop tool which provides an easy interface to the CC and Link programs that Acorn C/C++ installs in your computer's library. It constructs command lines and passes them to these programs. Likewise, C++ is a desktop tool that constructs command lines for the CC, CFront and Link programs in the library.

Because these two desktop tools are so similar, and share the underlying CC and Link programs, we describe them in the same chapter. Most of the rest of this chapter covers the CC and C++ options, and gives some programming examples.

If you are new to RISC OS and the Acorn C/C++ product, read the whole of this chapter before starting to use Acorn C/C++. If you are an experienced C or C++ programmer, you will find this chapter essential for reference, and may choose to tackle the Worked examples first.

The underlying programs

The CC compiler is a full implementation of ANSI C as described in the Introduction. It consists of a preprocessor and a code generator; it processes text files containing the source and headers of programs into linkable object files.

The Link program combines these object files to produce executable image files.

CFront is a C++ translator; it is a port of Release 3.0 of AT&T's CFront product. It converts C++ source code to C source code.

The characteristics of CC as a language implementation are defined in Part 2 - C language issues. Similar information for C++ is in Part 3 - C++ language issues.

How the tools use them

The command line that the CC tool produces first calls CC to preprocess and compile the source into object files; it then calls Link to link those object files.

The command line that the C++ tool produces first calls the CC preprocessor in a special C++ compatible mode; it then calls CFront to convert the resultant source files to C; it then calls CC to compile the C source into object files, again using a special C++ compatible mode; it finally calls Link to link those object files.

A note about Make

The Make tool (see the chapter entitled Make of the Desktop Tools guide) can also construct command lines for the underlying CC, CFront and Link programs. You'll find it a better tool for managing large projects. However, much of what is in this chapter is relevant, since Make both uses the same underlying programs, and sets options for those programs with the CC and C++ tools' user interfaces.

Getting started with CC and C++

To use the CC or C++ tool, first open the AcornC_C++.Tools directory display, then double click on !CC or !C++ as required. (You cannot start CC or C++ by double clicking on a file - the tools own no file type unlike, for example, Draw.)

The tool's icon appears on the icon bar:

 

Clicking Select on this icon, or dragging a source file from a directory display to this icon, brings up the SetUp dialogue box. To see this work, open the directory display for AcornC_C++.Examples, and then drag either CHello.c.HelloW to the CC icon, or C++Hello.c++.HelloW to the C++ icon. The SetUp dialogue box appears:

 

As you have dragged a source file to bring up this dialogue box, its name appears in the writable Source icon; otherwise this icon would have appeared containing the name of the last filename entered there, or be empty if there were none.

Clicking Menu on the SetUp dialogue box brings up the SetUp menu:

 

The SetUp dialogue box and menu specify the next compilation to be done. You start the next job by clicking Select on the Run button on the dialogue box (or on the Command line menu dialogue box). Clicking Select on the Cancel button removes the SetUp dialogue box and clears any changes you have just made to the options settings, leaving them back in the state they were in before you brought up the SetUp box. The options last until you adjust them again or reload the tool; or you can save the options for future use with an item from the main icon menu.

Ensure that the option settings are the defaults, as in the above pictures. Click on the Run button to compile either HelloW example with an integral link step. Save the executable image file produced in the directory above that holding the source, naming it HelloW, then double click Select on the file's icon to run it. The program runs, putting a Hello world message in the standard RISC OS command line window:

 

Libraries

C libraries

There are several libraries provided to support the C compiler:

• The stubs for the shared C library

  This provides all the standard facilities of the language, as defined by the ANSI standard document. Code using calls to the shared C library will be portable to other environments if an ANSI compiler and library are available for that environment. See the chapter entitled The C library.

• The ANSI library

  The ANSI library is a stand-alone version of the shared C library that contains a few extra functions useful in debugging and profiling your code. You should use it for development only, using the shared C library in any final product. See the chapter entitled The ANSI library.

• The Event library

  The purpose of the 'events' library is to allow the client to more easily dispatch Toolbox and Wimp events within Toolbox based applications. See the chapter entitled The Event library.

• The Wimp library

  This is a low-level library that provides veneers to the Wimp_... SWI calls; you may use it to interface directly with the Window Manager module. See the chapter entitled The Wimp library, and the RISC OS 3 Programmer's Reference Manual.

• The Toolbox library

  This library provides veneers onto the Toolbox SWIs; both the veneers and the SWIs are described in the accompanying User Interface Toolbox guide.

C++ libraries

The C++ compiler produces output which uses the ANSI C library (by linking with the stubs). A C++ program also needs to link with the C++ library which is held in AcornC.C++.libraries.c++lib.o.c++lib. This has support functions such as new and delete, and includes the streams and complex maths libraries.

File naming and placing conventions

This section explains the concept of a work directory, and describes the naming conventions used to identify the different classes of file you will come across when using Acorn C/C++.

Work directory

Both CC and C++ operate in a work directory. The work directory is where the tools place all output files that you don't explicitly place yourself by dragging from a Save As dialogue box. This includes object files to be linked by an integral link step, assembly language output and listing output. The work directory is also a place where some input source and header files are looked for - see the next sections for more details.

If you're using Make, the work directory is simply the directory containing the makefile controlling the job.

If you're using the CC or C++ tools, the work directory is formed from the directory containing the source file, modified by the relative path name specified by the Work directory option on the SetUp menu. The default Work directory SetUp menu value is ^.

For example, when compiling the example 'Hello world' C program with the default Work directory setting:

• The source is in the directory AcornC_C++.Examples.CHello.c
• The work directory is therefore AcornC_C++.Examples.CHello.c.^, i.e. AcornC_C++.Examples.CHello.

A typical directory arrangement is:

The resource files (such as !Run and Res) normally found in an application directory are not shown above. With directories arranged as above and default option settings, the work directories for both the Make and the CC/C++ tools are the same, namely Examples.!MyApp.

Filename conventions

The Acorn C/C++ system, in common with others, uses naming conventions to identify the classes of file involved in the compilation and linking process. Many systems use conventional suffixes for this. For example, the suffix .c denotes C source files on UNIX and MS-DOS systems. This convention clashes with Acorn's use of the full-stop character in pathnames. It is more natural under Acorn filing systems to use a prefix convention, e.g. c.foo, where c is the directory containing C source files, and foo is the filename.

However, portability is an increasingly important issue. CC recognises the standard file naming conventions and performs the appropriate transformations to construct valid RISC OS pathnames. The following sections summarise the conventions for referring to source, include, object and program files.

Rooted filenames

A filename is rooted if it is

• a RISC OS filename beginning with a '$' or an '&' - for example:

  $.library.h.baricon &.h.myheader

• a UNIX filename beginning with a '/' - for example:

  /library/baricon.h

• an MS-DOS filename beginning with a '\' - for example:

  \library\baricon.h

Rooted filenames are used by CC as absolute specifications of filenames, independent of work directories, search paths, etc. Rooted UNIX or MS-DOS filenames are converted into the Acorn syntax and prefix forms.

Source files

The CC and C++ tools specify the source files to be compiled on the command line they construct and pass to the underlying programs. Dragging a source file to the CC SetUp dialogue box specifies the file as an absolute rooted filename.

Make uses a makefile to specify the source files; their pathnames are normally given relative to the work directory. C source files will be looked for in the subdirectory c of the work directory. To aid portability, a file specified as foo.c in a makefile will be looked for in @.c.foo, where @ means the work directory. C++ source files are similarly looked for in the subdirectory c++.

Include files

The way in which the compiler searches for included files is dealt with in detail in the Include file searching. Here we describe the issues of naming header files and how to name them in #include lines in your C and C++ program source.

Include files are often headers for libraries, and are incorporated by issuing the #include directive - dealt with by the preprocessor - at the start of a source file. For instance, in the C HelloW example:

#include <stdio.h>

By convention, header files are placed in subdirectory h. This convention is followed here. You can use subdirectory h of the work directory for your own header files, which can be incorporated with a source line like:

#include "myfile.h" 

Note that both the example filenames stdio.h and myfile.h are in suffix form rather than Acorn prefix form. This is because you can make use of Acorn C/C++'s filename processing to interpret these, leaving program lines which do not need altering to port them to machines expecting suffixes.

To facilitate the porting of code from UNIX and MS-DOS to RISC OS, UNIX-style and MS-DOS-style filenames are translated to equivalent RISC OS-style filenames.

For example:

../include/defs.h  is translated to  ^.include.h.defs
..\cls\hash.h      is translated to  ^.cls.h.hash
includes.h         is translated to  h.includes

but:

system.defs        is translated to  system.defs

In the same way, the lists of directory names given as arguments to the compiler's Include and Default path SetUp options (see below) are translated to RISC OS format before being used, in the rare event that this is necessary.

Object files

If you use the CC or C++ tool to compile a single file with the SetUp dialogue box option Compile only enabled, you use a standard Save As dialogue box to save the resultant object file.Otherwise the object files created by the compiler are instead stored in the o subdirectory of the work directory. Thus the result of compiling c.sieve will be found in o.sieve.

Program files

If you haven't enabled the Compile only option on the CC or C++ tool's SetUp menu, the tool compiles sources to object files, and then links them with the C library stubs to produce an executable program file. You may find it convenient to save this program file in the work directory itself - there is no conventional suffix for these.

Compilation list files

If you enable the Listing option on the CC tool's SetUp menu, then for each compiled source file the CC tool creates a compilation listing file in the l subdirectory of the work directory. Thus compiling c.sieve with Listing enabled will by default result in the list file l.sieve being created.

The C++ tool does not have a Listing option.

Assembly list files

If the CC or C++ tool's SetUp menu option Assembler is enabled, no object code is generated. Instead, an assembly listing of the code is created. If only one assembly listing file is produced, you save it from a standard Save As dialogue box. If more than one is produced these are placed in the subdirectory s of the work directory. Thus compiling c.sieve with Assembler enabled can result in the assembly language file s.sieve being created.

Filename validity

The compiler does not check whether the filenames you give are acceptable -whether they contain only valid characters and are of acceptable length - this is done by the filing system.

Include file searching

The process of converting text C or C++ source to linkable object files of binary code can be seen as a pipeline of several processes. The first stage is preprocessing the source. It is at this stage that the text of header files is brought in at the position of #include directives in the source text.

The preprocessor - which is used by both the CC and C++ tools - handles #include directives of two forms:

#include <filename>

or

#include "filename"

You will normally include four types of header file:

• headers for the ANSI parts of the C library
• headers for the non-ANSI parts of the C library
• headers for the other libraries supplied with Acorn C/C++
• headers for your own include files.

A special feature of the Acorn C/C++ system is that the standard ANSI headers are built into the compiler, and are used by default. By writing the filename in the angle bracket form, you indicate that the include file is a system file, and thus ensure that the compiler looks first in its built-in filing system. Of the common types of header above, only the headers for the ANSI parts of the C library should be referred to as system files in angle brackets. Writing the filename in the double quote form indicates that the include file is a user file.

The headers for the non-ANSI parts of the main C library - kernel, pragmas, SWIs and varargs - are not built in to the compiler; nor are the headers for the other libraries supplied with Acorn C/C++. However, by default the CC and C++ tools both set the Include icon on their SetUp dialogue box to C:. This makes the preprocessor use the value of the C$Path system variable to find the headers for all the libraries supplied in AcornC_C++.Libraries.

You can include headers for other libraries by adding the parent of the h directory holding them to the Include writable icon on the tool's SetUp dialogue box. The easiest way to do so is to drag the included directory's icon from a directory display to the writable field.

As mentioned before, you can use the subdirectory h of the work directory for the last common type of header file - your own header files, which you refer to as user files with directives such as:

#include "myfile.h"

This is all you need to know for basic use of CC with largely default options. The rest of this section provides a level of detail useful for reference or studying if you wish to use CC in a non-standard way.

Reference section

The way in which the preprocessor looks for included files depends on three factors:

• whether the filename is rooted
• whether the filename in the #include directive is between angle brackets <> or double quotes ""
• use of the Include and Default path SetUp options (including the special filename :mem).

If a filename is not rooted (as defined earlier) the preprocessor looks for it in a sequence of directories called the search path.

Search path

The order of directories in the search path is as follows:

The compiler's own in-memory filing system.

This is only searched for #include <filename > directives when you have not enabled the SetUp menu's Default path option.

The current place (see the chapter entitled Nested includes).

This is only searched for #include "filename " directives.

Arguments to the SetUp dialogue box's Include option, if used.

As noted above, this is set to C: by default, and so all the directories supplied in AcornC_C++.Libraries will be searched.

The system search path:

• The path given as an argument to the Default path SetUp menu option (see below), if this is enabled; otherwise

  The value of the system variable C$Libroot, if this is set; otherwise

  $.Clib.

Nested includes

The current place is the directory containing the source file (C or C++ source, or #included header) currently being processed by the compiler. Often, this will be the work directory.

When a file is found relative to an element of the search path, the name of the directory containing that file becomes the new current place. When the compiler has finished processing that file it restores the old current place. So at any given instant, there is a stack of current places corresponding to the stack of nested #includes.

For example, suppose the current place is $.include and the compiler is seeking the #included file "sys.defs.h" (or "sys.h.defs", "sys/defs.h", etc). Now suppose this is found as:

$.include.sys.h.defs.

Then the new current place becomes $.include.sys, and files #included by h.defs, whose names are not rooted, will be sought relative to $.include.sys.

This is the search rule used by BSD UNIX systems. If you wish, you can disable the stacking of current places using the SetUp menu option Features with the argument K, to get the search rule described originally by Kernighan and Ritchie in The C Programming Language. Then all non-rooted user includes are sought relative to the directory containing the source file being compiled.

In all this, the penultimate .c, .c++ and .h components of the path are omitted. These are logically part of the filename - a filename extension - not logically part of the directory structure. However, directory names other than c, c++, h, o and s are not so recognised (as filename extensions) and are used 'as is'. For example, the name sys.new.defs is exactly that: it is not translated to sys.defs.new and, if it is found, the new part of the name does become part of the new current path.

Use of :mem

You can use the SetUp menu option Default path to provide your own system search path, as mentioned in step The system search path: of the Search path above. The preprocessor will then use the argument you give to the Default path option as the system search path. You will only require this feature if you use implementations of the C library other than those provided with the Acorn C system.

Use of the Default path option also prevents a #include <filename > directive being first searched for in the in-memory filing system (see step The compiler's own in-memory filing system. of the Search path above). It can be reinstated by using the pseudo-filename :mem as an argument to the Default path or Include options. If :mem is included in the search path in this way, its position in the path is as specified - not necessarily first - so you can take complete control over where the compiler looks for #included files.

Use of C$Libroot

C$Libroot is an environment variable that you can use to provide your own system search path, as shown in step The system search path: of the Search path above. It is not needed for normal use of the compiler.

If C$Libroot is set, and you have not used the Default path option, the preprocessor will use the variable's value as the system search path. By default, C$Libroot is not set.

To set the value of C$Libroot to, for example, "$.MyLib", at the command line type:

*Set C$Libroot $.MyLib

This variable is also used by the Acorn C/C++ system as the library search path, if set. With the example given, the compiler will now look for include files in $.mylib.h, and for libraries in $.mylib.o.

The SetUp dialogue box

Clicking Select on the tool's icon bar icon or dragging a source file from a directory display to this icon brings up the tool's SetUp dialogue box:

&NBSP;

Source

This writable icon in the SetUp dialogue box contains the names of the source files to be compiled.

When the SetUp box is obtained by clicking on the tool's main icon, it comes up with this icon containing its previous setting. You can thus repeat your previous compilation by just clicking on the Run button.

If the SetUp box appears as a result of dragging a source file to the main icon, the writable Source icon appears containing the new source file name.

When the SetUp box appears the Source icon has input focus, and can be edited in the normal RISC OS fashion. If you select a further source file in a directory display and drag it to this writable icon, its name is added to a list of those already there.

If you drag pre-compiled or pre-assembled object files to the Source icon, they are included in the set of object files linked together in an integral link step after the source files themselves have been compiled to object files.

Include

This SetUp dialogue box icon adds specified directories to the list of places which are searched for #include files. The directories in the Include icon are searched in the order in which they are given. The path should end with the name of a directory, with no .h, which is added automatically.

The default setting of Include is to C:. This makes the preprocessor search for headers in the directories listed in the RISC OS environment variable C$Path, set by AcornC_C++.!SetPaths. The directories listed are those that hold all the libraries supplied with the product in AcornC_C++.Libraries

For more details of how to use #include lines and places searched for headers - both before and after those in this Include list - see the chapter entitled File naming and placing conventions.

Compile only

This option switches off or on the linking of object files. When enabled, the link step is not performed, and the tools output object files. If you're only compiling one source file, you drag the object file produced from a Save as dialogue box. Otherwise, multiple files are saved in the o subdirectory of the work directory.

If not enabled, both CC and C++ instead perform an integral link step, linking any object files produced by compilation to any additional ones dragged to the Source icon, and library files, producing an executable program file. You control the saving of this from a Save as dialogue box.

Compile only is not enabled by default.

Preprocess only

This option is not available for the C++ tool.

If this option is enabled, only the preprocessor phase of the compiler is executed. The output from the preprocessor is sent to the standard output window. The standard non-interactive tool output window save facility is useful here to save this output to a file or SrcEdit window. By default, comments are stripped from the output, but see the SetUp menu option Keep comments on Keep comments.

Preprocess only is not enabled by default.

Debug

This option switches on or off production of debugging tables. When enabled, extra information is included in the resultant object files and image files which enables source level debugging of the linked image by the DDT debugger. If this option is disabled, any image file finally produced can only be debugged at machine level.

If you are only compiling the source to object files, you must remember to enable debugging in the Link tool when you link them. If you don't, you'll lose the debugging information produced by the CC and C++ tools.

Debug is not enabled by default.

Throwback

This option switches editor throwback on or off. When enabled, if the DDEUtils module and SrcEdit are loaded, any compilation errors cause the editor to display an error browser. Double clicking Select on an error line in this browser makes the editor display the source file containing the error, with the offending line highlighted. See the chapter entitled SrcEdit of the accompanying Desktop Tools guide for more details.

Throwback is on by default.

The SetUp menu

Clicking Menu on the SetUp dialogue box brings up the SetUp menu. The CC menu contains some options not available on the C++ menu, but the two menus are otherwise virtually identical:

&NBSP;

The options on this menu are described in the following subsections.

The command line

The Command line item at the top of the SetUp menu leads to a small dialogue box in which the command line equivalent of the current SetUp options is displayed:

&NBSP;

Clicking on the Run action button in this dialogue box starts compilation in the same way as that in the main SetUp box. Pressing Return in the writable icon in this box has the same effect. Before starting compilation from the command line box, you can edit the command line textually, although this is not normally useful.

Controlling the preprocessor

Default path

The Default path entry on the SetUp menu leads to a writable icon in which you specify a comma-separated list of directories to be searched for included files:

&NBSP;

This overrides the system include path with the list of directories. You can specify the memory file system in the list by using the name :mem (in any case). An example is:

myhdrs,:mem,$.proj.public.hdrs

For more details of the system include path and searching for include files in general, see the chapter entitled File naming and placing conventions.

Default path is not enabled by default.

Keep comments

This option is not available for the C++ tool.

When enabled in conjunction with Preprocess only, this option retains comments in preprocessor output.

Keep comments is not enabled by default.

Define

The Define option on the SetUp menu leads to a writable icon in which you can predefine preprocessor macros:

&NBSP;

You can enter two forms of macro predefinition:

sym=value
sym

These both define sym as a preprocessor macro for the compilation. The two forms are equivalent to the lines:

#define sym value 
#define sym 1

at the head of the source file.

You can enter multiple symbols as a space-separated list.

Define is not enabled by default.

Undefine

The Undefine option on the SetUp menu leads to a writable icon in which you can undefine preprocessor macros:

&NBSP;

You enter the name of the macro concerned, eg:

sym

Use of this option is then equivalent to the line:

#undef sym

at the head of the source file.

You can enter multiple symbols as a space-separated list.

Undefine is not enabled by default.

Controlling code generation

Debug options

This option is not available for the C++ tool.

The Debug options option on the SetUp menu leads to a writable item in which you enter a set of modifier letters:

The modifier letters limit the debugging tables generated in response to enabling the Debug option on the SetUp dialogue box. The letters recognised are:

f	generate information on functions and top-level variables (outside functions) only
l	generate information only describing each line in the file
v	generate information only describing all variables

You can use these letters in any combination.

Debug options is not enabled by default.

Profile

This option is not available for the C++ tool.

Enabling this SetU menu option causes the compiler to generate code to count the number of times each function is executed. This is called profiling.

The counts can be printed by calling _mapstore() to print them to stderr or by calling _fmapstore("filename") to print them to a named file of your choice. You should do this just before the final statement of your program.

Profiling is not supported by the shared C library, so you must link programs to be profiled with ANSILib. If you wish, you can link with both Stubs and ANSILib, in which case only the code for _mapstore() and _fmapstore() will be included from ANSILib; your program will continue to use the shared C library, and will be much smaller than if linked with ANSILib alone.

The printed counts are lists of lineno : count pairs. The lineno value is the number of a line in your source code, and the count value is the number of times it was executed. Note that lineno is ambiguous: it may refer to a line in a #include file. However, this is rare and usually causes no confusion.

Provided you didn't compile your program with the Features option with f as an argument, blocks of counts will be interspersed with function names. In the simple cases, the output reduces to a list of line-pairs like:

function 
lineno: count, where count is the number of times function was executed. 

If you use the SetUp menu option Others to add the text -px to the command line, profiling of basic blocks within functions is performed in addition to profiling the functions. If you do this, the lineno values within each function relate to the start of each basic block. Sometimes, a statement (such as a for statement) may generate more than one basic block, so there can be two different counts for the same line.

Profiled programs run slowly. For example, when compiled with Profile enabled, Dhrystone 1.1 runs at about 5/8 speed; when compiled -px it runs at only about 3/8 speed.

There is no way, in this release of C, to relate execution counts to the proportion of time spent in each section of code. Nor is there any tool for annotating a source listing with profile counts. Future releases of C may address these issues.

Profile is not enabled by default.

Assembler

If this SetUp menu option is enabled, no object code is generated and, naturally, no attempt is make to link it. If only one assembly listing file is produced, you save it from a standard save dialogue box. If more than one is produced these are placed in the subdirectory s of the work directory.

Assembler is not enabled by default.

Module code

This SetUp menu option must be enabled when compiling code for linking into a RISC OS relocatable module, otherwise it should not be enabled. When enabled, code is produced which allows the module's static data to be separated from its code, hence be multiply instantiated.

Module code is not enabled by default.

Controlling the linker

Libraries

The Libraries option on the SetUp menu leads to a writable icon in which you specify a comma-separated list of filenames of libraries to be used in an integral link step:

&NBSP;

The libraries specified with this option are used instead of the standard one (AcornC_C++.Libraries.clib.o.Stubs), not in addition to it.

Libraries is not enabled by default.

Using the Features menu option

Features

The Features option on the SetUp menu leads to a small writable icon in which you can specify additional compiler features with single modifier letters:

&NBSP;

This entry controls a variety of compiler features, including certain checks on your code more rigorous than usual. At least one of the following modifier letters must be entered if Features are enabled:

a	Check for certain types of data flow anomalies. The compiler performs data flow analysis as part of code generation. The checks enabled by this option can sometimes indicate when an automatic variable has been used before it has been assigned a value.
c	Enable the Limited pcc option. This allows characters after #else and #endif preprocessor directives (treated as comments), and explicit casts of integers to function as pointers (forbidden by ANSI). These features are often required in order to use pcc-style include files in ANSI mode.
e	Check that external names used within the file are still unique when reduced to six case-insensitive characters. Some linkers only provide six significant characters in their symbol tables. This can cause problems with clashes if a system uses two names such as getExpr1 and getExpr2, which are only unique in the eighth character. The check can only be made within one compilation unit (source file) so cannot catch all such problems. Acorn C and C++ allow external names of up to 256 characters, so this is a portability aid.
f	Do not embed function names in the code area. The compiler does this to make the output produced by the stack backtrace function (which is the default signal handler) and _mapstore() more readable. Removing the names from the compiler makes the code slightly smaller (typically 5%) at the expense of less meaningful backtraces and _mapstore() outputs.
h	Check that all external objects are declared in some included header file, and that all static objects are used within the compilation unit in which they are defined. These checks support good modular programming practices.
i	In the listing file (see the Listing option) include the lines from any files included with directives of the form: #include "file"
j	As above, but for files included by lines of the form: #include <file>
k	Use K&R search rules for nested #include directives (the 'current place' is defined by the original source file and is not stacked; see the chapter entitled File naming and placing conventions for details).
m	Give a warning for preprocessor symbols that are defined but not used during the compilation
n	Embed function names in the code area (see f feature). This improves the readability of the output produced by the stack backtrace run time support function and the _mapstore() function (see Profile). However, it does increase the size of the code area slightly (around 5%). In general it is not useful to specify the f feature with Profile (i.e. -p).
p	Report on explicit casts of integers into pointers, eg: char *cp = (char *) anInteger; Implicit casts are reported anyway, unless suppressed by the Suppress warnings option.
u	By default, the source text as 'seen' by the compiler after preprocessing (expansion) is listed. If this feature is specified then the unexpanded source text, as written by the user, is listed. Consider the line p = NULL; By default, this will be listed as p=(0);. With the u feature specified, it will be listed as p=NULL;.
v	Report on all unused declarations, including those from standard headers.
w	Allow string literals to be writable, as expected by some UNIX code, by allocating them in the program's data area rather than the notionally read-only code area.

When writing high-quality production software, you are encouraged to use at least the fah Features options in the later stages of program development (the extra diagnostics produced can be annoying in the earlier stages).

Features is not enabled by default.

Handling warnings and errors

Suppress warnings

The Suppress warnings option on the SetUp menu prevents warnings from appearing.

For the C++ tool, all warnings are suppressed.

For the CC tool, this menu option leads to a writable icon in which you can enter a set of modifier letters:

&NBSP;

The modifier letters specify various kinds of warning message to be suppressed by CC. Usually the compiler is very free with its warnings, as this tends to indicate potential portability or other problems. However, too many such messages can be a nuisance in the early stages of porting a program from old-style C, so you can disable them.

The modifier letters for CC are:

a	Give no Use of = in a condition context warning. This is given when the compiler encounters statements such as if (a=b) {... where it is quite possible that == was intended.
d	Give no Deprecated declaration foo() - give arg types warning. Use of old-style function declarations is deprecated in ANSI C, and in a future version of the standard this feature may be removed. However, it is useful sometimes to suppress this warning when porting old code.
f	Give no Inventing "extern int foo()" message. This may be useful when compiling old-style C as if it were ANSI C.
n	Give no Implicit narrowing cast warning. This warning is issued when the compiler detects an assignment of an expression to an object of narrower width (eg long to int, float to int). This can cause problems with loss of precision for certain values.
p	Give no non-ANSI #include <...> warning. ANSI require that #include <...> should only be used for ANSI headers, but it can be useful to disable this warning when compiling code which does not conform to this aspect of the standard.
v	Give no Implicit return in non-void context warning. This is most often caused by a return from a function which was assumed to return int (because no other type was specified) but is in fact being used as a void function.

If you enter a space in the writable icon, then Select or Return, all warning messages from CC are suppressed.

Suppress errors

This option is not available for the C++ tool.

The Suppress errors option on the SetUp menu leads to a writable icon in which you can enter a set of modifier letters:

These modifier letters can be used to force CC to accept C source which would normally produce errors. If any of these options are needed, it means that the C source in question does not conform to the ANSI C standard (CC normally generates precisely the diagnostics required by ANSI).

The modifier letters are:

c	Suppresses all implicit cast errors, e.g. 'implicit cast of non-0 int to pointer'.
f	Suppresses errors for unclean casts such as short to pointer.
i	Suppresses syntax checking for #if.
p	Suppresses the error which occurs if there are extraneous characters at the end of a preprocessor line.
z	Suppresses the error if a zero-length array is used.

UNIX pcc

This option is not available for the C++ tool.

Enabling this SetUp menu option switches to compiling 'portable C compiler' C rather than ANSI C. This is based on the original Kernighan and Ritchie (K&R) definition of C, and is the dialect used on UNIX systems such as Acorn's RISC iX product. This option changes the syntax that is acceptable to the compiler, but the default header and library files are still used. See the section on this option in the Portability for more details.

UNIX pcc is not enabled by default.

Errors to file

This option is not available for the C++ tool.

Errors to file allows you to specify a file to which error messages are output for later inspection:

Listings

Listing

This option is not available for the C++ tool.

Enabling this SetUp menu option causes a listing file to be created. This consists of lines of source interleaved with error and warning messages. You can get finer control over the contents of this file using the Features option (see Using the Features menu option).

Listing is not enabled by default.

Choosing your work directory

Work directory

The Work directory entry on the SetUp menu leads to a writable icon in which you specify the work directory:

&NBSP;

The effect of this option is described in the File naming and placing conventions.

The default Work directory setting is ^.

Specifying other command line options

Others

The Others option on the SetUp menu leads to a writable icon in which you can add an arbitrary extra section of text to the command line to be passed to the relevant underlying program:

&NBSP;

This facility is useful if you wish to use any feature which is not supported by any of the other entries on the SetUp dialogue box and menu. This may be because the feature is used very little, or because it may not be supported in the future.

For a full description of command line options, see Command lines.

Output messages

The CC and C++ tools output text messages as they proceed. These include preprocessed source (see Preprocess only), warning and error messages. By default any such text is directed into a scrollable output window:

&NBSP;

This window is read-only; you can scroll up and down to view progress, but you cannot edit the text without first saving it. Clicking Select on the scrollable part of this window has no effect, to indicate this.

The contents of the window illustrated above are typical of those you see from a successful compilation - the title line of the compiler with version number, followed by no error messages.

Clicking Adjust on the close icon of the output window switches to the output summary dialogue box. This presents a reminder of the tool running (CC or C++), the status of the task (Running, Paused, Completed or Aborted), the time when the task was started and the number of lines of output that have been generated (ie those that are displayed by the output window):

&NBSP;

Clicking Adjust on the close icon of the summary box returns to the output window.

Both the above output displays follow the standard pattern of those of all the non-interactive Desktop tools. The common features of the non-interactive Desktop tools are covered in more detail in the General features of the accompanying Desktop Tools guide. Both tools' output displays and the menus brought up by clicking Menu on them offer the standard features allowing you to abort, pause, or continue execution (if the execution hasn't completed); and to save output text to a file, or repeat execution.

Error messages appear in the output viewer, with copies in the editor error browser when throwback is working. The appendixes C errors and warnings and C++ errors and warnings contain more details for interpreting error messages.

Preprocessed source appearing in the output window is often very large for compilation of complex source files. The scrolling of the output window is useful to view it, and to investigate it with the full facilities of the source editor, you can save the output text straight into the editor by dragging the output file icon to the SrcEdit main icon on the icon bar (providing Wimp$Scrap is properly set on your machine).

The icon bar menu

Clicking Menu on either the CC or the C++ icon on the icon bar gives the following menu:

&NBSP;

Save options saves all the tool's current options, including those set both from the SetUp dialogue box and from the Options item on this menu. When you restart the tool it is initialised with these options rather than the defaults.

The Options item on the main menu allows you to enable Auto run, Auto save or start the output display as either a text window (default) or summary box. When Auto run is enabled, dragging a source file to the tool's icon starts a compilation immediately with the current options, rather than displaying the SetUp box first. When Auto save is enabled, output object files are saved to suitable places automatically without producing a save dialogue box for you to drag the file from. Both Auto run and Auto save are off by default.

For a description of each option in the tool's menu see the chapter entitled General features of the accompanying Desktop Tools user guide.

Command lines

For normal use you do not need to understand the syntax of the underlying CC and C++ programs' command lines, as they are generated automatically for you from the SetUp dialogue box and menu settings.

The syntax of the command lines is:

cc «options» filenames
c++ «options» filenames

By default, the C compiler and C++ translator look for source files, and create object, assembler and listing files, beneath the current work directory.

Many aspects of the programs' operation can be controlled via command-line options. All options are prefixed by a minus sign. There are two classes of option: keywords and flags:

• Keywords are recognised in upper case or lower case.
• A flag is a single letter, sometimes followed by an argument. Whenever this is the case, the C compiler allows white space to be inserted between the flag letter and the argument. However, this is not always true of other C compilers, so in the following subsections we only list the form that would be acceptable to a UNIX C compiler. Similarly, we only use the case of the letter that would be accepted by a UNIX C compiler.

By using the conventions common to many C compilers, you can build portable makefiles that you can easily move between different environments.

The options are listed below. Where an option merely gives a page reference to a desktop equivalent, you should see that page for full details. Should you need to use any of the more esoteric options that have no direct desktop equivalent, remember that you can always add them to the SetUp menu's Others option (see Specifying other command line options).

Where an option is shaded, we recommend that you don't use it with C++. You may use all options with CC, save for the Translator options, which are used by CFront and hence irrelevant to CC.

Keyword options

Command line option		Description
-help		Outputs a summary of the command line options.
-pcc		Equivalent to UNIX pcc in SetUp menu; see UNIX pcc.
-fussy or -strict		Be extra strict about enforcing conformance to the ANSI standard or to pcc conventions (e.g. prohibit the volatile qualifier in -pcc mode).
-list		Equivalent to Errors to file in SetUp menu; see Errors to file.
-via file		Reads in extra command line arguments from the given filename.
-errors file		Equivalent to Listing in SetUp menu; see Listing.
-littleend or -li		Compile code suitable for a little-endian ARM.
-bigend or -be		Compile code suitable for a big-endian ARM.
-apcs «3»qualifiers		Specify which variant of the ARM Procedure Call Standard is to be used by the compiler. At least one qualifier must be present, and there must be no space between qualifiers. The following qualifiers are permitted:
	/26«bit»	26 bit APCS variant.
	/32«bit»	32 bit APCS variant.
	/reent«rant»	Reentrant APCS variant.
	/nonreent«rant»	Non reentrant APCS variant.
	/swst«ackcheck»	Software stack checking APCS variant.
	/noswst«ackcheck»	No software stack checking APCS variant.
	/fp	Use a dedicated frame-pointer register.
	/nofp	Do not use a frame-pointer.
	/fpe2	Floating point emulator 2 compatibility.
	/fpe3	Floating point emulator 3 compatibility.
	/fpr«egargs»	Floating point arguments passed in floating point registers.
	/nofpr«egargs»	Floating point arguments are not passed in floating point registers.
-depend dependfile		Saves include file dependency lists, which are suitable for use with 'make' utilities.
-throwback		Equivalent to Throwback option icon in SetUp dialogue box; see Throwback.
-desktop directory		Equivalent to Work directory in SetUp menu; see Work directory.
-C++		Assume C++ code is being processed. This option is only used by the C++ program, when invoking the compiler to pre-process C++ source before translation, and when compiling the generated C. When preprocessing under the -E option, comment handling is changed to correctly deal with C++'s '//' comments (which are terminated by the end of the source line), and #pragma lines are passed through to the preprocessor output. During the C compilation stage, use of this flag disables certain warnings (most notably 'no side-effect in void context', and messages about unused variables), otherwise produced by some rather odd code constructs in the generated C. It also arranges that in any warning or error reports, the original (type-qualified) C++ source names are printed rather than the modified names CFront generates in order to implement overloading.

Preprocessor options

Command line option	Description
-Idirectory	Equivalent to Include option icon in SetUp dialogue box; see Include.
-jdirectories	Equivalent to Default path in SetUp menu; see Default path.
-E	Equivalent to Preprocess only option icon in SetUp dialogue box; see Preprocess only.
-C	Equivalent to Keep comments in SetUp menu; see Keep comments.
-M	If this flag is specified, only the preprocessor phase of the compiler is executed (as with cc -E) but the only output produced is a list, on the standard output stream, of makefile dependency lines suitable for use by a make utility. This can be redirected to a file using standard UNIX/MS-DOS notation. For example: cc -M xxx.c >> Makefile.
-Dsymbol«=value»	Equivalent to Define in SetUp menu; see Define.
-Usymbol	Equivalent to Undefine in SetUp menu; see Undefine.

Translator options

These options affect the operation of CFront.

Command line option	Description
+v	Print commands as CFront executes them
+w	Equivalent to Suppress warnings in C++'s SetUp menu; see Suppress warnings. (Suppress warnings also uses CC's -W option.)
+p	Pedantic - compile strict C++
+g	Equivalent to Debug option icon in C++'s SetUp dialogue box; see Debug. (Debug also uses CC's -g option.)
-F	Send CFront output to stdout; do not compile it

Code generation options

If you are using C++, we recommend you only use the following from the code generation options below: -o, -g, -S and -zM.

Command line option	Description
-o file	The argument to the -o flag gives the name of the file which will hold the final output of the compilation step. In conjunction with -c, it gives the name of the object file; in conjunction with -S, it gives the name of the assembly language file. Otherwise, it names the final output of the link step.
-g«options»	Equivalent to Debug option icon in SetUp dialogue box and Debug options in SetUp menu; see pages Debug and Debug options.
-p«options»	Equivalent to Profile in SetUp menu; see Profile.
-S	Equivalent to Assembler in SetUp menu; see Assembler.
-zM	Equivalent to Module code in SetUp menu; see Module code.

Linker options

Command line option	Description
-c	Equivalent to Compile only option icon in SetUp dialogue box; see Compile only.
-llibraries	Equivalent to Libraries in SetUp menu; see Libraries.

Warning and error message options

If you are using C++, we recommend you only use the following from the warning and error message options below: -W.

Command line option	Description
-Woptions	Equivalent to Suppress warnings in SetUp menu; see Suppress warnings.
-eoptions	Equivalent to Suppress errors in SetUp menu; see Suppress errors.

Additional feature options

If you are using C++, we recommend you only use the following from the additional feature options below: -zr and -f.

Command line option	Description
-zpAlphaNum	This flag can be used to emulate #pragma directives. The letter and digit which follow it are the same characters that would follow the '-' of a #pragma directive. See #pragma directives for details.
-zrnumber	This flag allows the size of (most) LDMs and (all) STMs to be controlled between the limits of 3 and 16 registers transferred. This can be used to help control interrupt latency where this is critical.
-ffeatures	Equivalent to Features in SetUp menu; see Features.

Worked examples

Several examples of C and C++ programs on the discs of Acorn C/C++ are worked through in this guide and in the Desktop Tools guide. A collection of examples are listed here illustrating various points and styles of working.

The following example programs are in the directory AcornC_C++.Examples, each in a subdirectory with the name of the example. For each program, we give a 'recipe' for how to compile, link and run the program. Filenames are given relative to the subdirectory containing each example unless otherwise stated. It is assumed that you have read the preceding parts of this chapter. For more details of the tool Make, see the chapter entitled Make of the accompanying Desktop Tools user guide. When you enter any command lines given below, you must first ensure that the currently-selected directory is the subdirectory containing the example being tried.

There are some further less trivial examples that we omit here. These show you how to implement more esoteric features, mainly involving interworking C and/or C++ with assembler. They are described elsewhere in the Acorn C/C++ manual set, together with necessary supporting technical information.

CHello

Purpose:	The standard most trivial C program. Try it as an exercise.
Source:	c.HelloW
Compile using:	default CC SetUp options
Run by:	double clicking on HelloW
Clean up by:	deleting HelloW and o.HelloW

C++Hello

Purpose:	The standard most trivial C++ program. Try it as an exercise.
Source:	c++.HelloW
Compile using:	default C++ SetUp options
Run by:	double clicking on HelloW
Clean up by:	deleting HelloW and o.HelloW

Sieve

Purpose:	The Sieve of Eratosthenes is often presented as a standard benchmark, though it is not very meaningful in this context.
Source:	c.Sieve
Compile using:	default CC SetUp options
Run by:	double clicking on Sieve
Clean up by:	deleting Sieve and o.Sieve

Dhrystone 2.1

Purpose:	Dhrystone 2.1 is the standard integer benchmark. Its results require careful interpretation (it often overstates the real performance of machines). Try as a first exercise in using the Make utility (!Make).
Sources:	h.dhry c.dhry_1 c.dhry_2
Makefile:	Makefile
Build by:	double clicking on Makefile, with default Make options
Run by:	double clicking on Dhrystone Reply with any number in the range 20000 to 250000 to the prompt for number of iterations. Try a big number such as 200000 and time the execution with a stopwatch or sweep second hand to confirm the claimed performance. Note how performance depends on screen mode.
Rebuild by:	double clicking on Makefile again (try altering some of the options in Makefile with Make between rebuilds: eg compile in UNIX pcc mode or link with ANSILib instead of Stubs).
Clean up by:	deleting Dhrystone, o.dhry_1 and o.dhry2.

CModule

Purpose:	To illustrate how to implement a module in C. You can also use it as another exercise in using Make. For more details on constructing relocatable modules in C see the chapter entitled How to write relocatable modules in C.
Sources:	c.CModule CModuleHdr
Build using:	CC of c.CModule with options Compile only and Module code enabled, saving output object file as o.CModule. CMHG of cmhg.CModuleHdr to o.CModuleHdr. Link of o.CModule, o.CModuleHdr and AcornC_C++.Libraries.CLib.o.Stubs with Module enabled to the output file CModule.
or by:	double clicking on Makefile, with default Make options.
Run from:	the command line using CModule
Test from:	the command line using: help tm1 help tm2 tm1 hello tm2 1 2 3 4 5 tm1 1 2 3 tm2 hello (try other combinations too) *BASIC > SYS &88000 : REM should give an error > SYS &88001 : REM should give divide by 0 error > SYS &88002 : REM no error, just a message > SYS &88003 : REM no error, just a message > SYS &88004 : REM same as &88000... (now repeat some of these after issuing some invalid * commands...) >*foo > SYS &88002 etc. >QUIT
Clean up by:	from the command line typing: RMKill TestCModule deleting CModule, o.CModule and o.CModuleHdr or running Make on Makefile with target clean selected.

Desktop application examples

The desktop applications !Hyper, !MinApp and !TBoxCalc and the various versions of SaveAs are all too complex to be described here in great detail.

They are best built by double clicking on their Makefiles. They can be run by double clicking on their application icons.