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

ToPCC

ToPCC is a desktop tool which provides an easy interface to the ToPCC program that Acorn C/C++ installs in your computer's library. The ToPCC tool constructs command lines and passes them to the ToPCC program. ToPCC helps convert program source written in the ANSI style of C to program source in the PCC style of C. PCC is the UNIX Portable C Compiler, and closely follows K&R C, as defined by B Kernighan and D Ritchie in their book The C Programming Language.

ToPCC enables you to write (with care) programs that can be automatically converted between the ANSI and PCC dialects of C, hence assisting you in constructing easily portable programs. The associated tool ToANSI makes approximately the reverse translations to ToPCC. For more details of portability issues, see the chapter entitled Portability. The changes that ToPCC makes to C source are listed in the ToPCC C translation below.

ToPCC is one of the non-interactive DDE tools, its desktop user interface being provided by the FrontEnd module. It shares many common features with the other non-interactive tools. These common features are described in the General features of the accompanying Desktop Tools guide.

ToPCC C translation

ToPCC makes the following transformations to C source code or header text:

• Function declarations of the form

  type foo(args);

  are rewritten as

  type foo(/* args */);

  Any comment tokens /* or */ in args are removed.

• Function definitions of the form

  type foo(type a1, type a2) {...}

  are rewritten as

  type foo(a1, a2) 
  type a1; 
  type a2;

• A ... in the function definition is interpreted as int va_alist. Full translation of variadic functions is not performed.
• type foo(void)

  is rewritten as

  type foo()

• Type void * is converted to VoidStar which can be typedef'd to something suitable (eg char *).
• Unsigned and unsigned long constants are rewritten using the typecasts (unsigned) and (unsigned long).

  For example, 300ul becomes (unsigned long)300L.

Note that ToPCC performs only simple textual translations and is not able to reliably diagnose C syntax errors, which may produce surprising results, so it is best to use ToPCC only on code you already know compiles.

A note about Make

Since porting programs is usually a one-off process involving some experimentation, only direct use of ToPCC makes sense. You cannot use ToPCC from Make.

Starting ToPCC

To start the ToPCC tool, first open the AcornC_C++.Tools directory display, then double click on !ToPCC. Its 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, from which you control the running of ToPCC:

ToPCC has hardly any options for its use, so its interface is simpler than most of the other Acorn C/C++ tools.

The File writable icon is for the name of the description file to be processed. If you displayed the SetUp dialogue box by clicking on the ToPCC icon bar icon, you will want to fill this in by dragging a source file from a directory display to this icon before running ToPCC.

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

Command line shows you the command line that will be passed to the underlying ToPCC program; you can then alter it if necessary.

Options leads to a writable field in which you can specify one or more single letter options:

These options are:

c	Don't remove the keyword const
e	Don't remove #error ... directives
l	Don't remove #line ... directives
p	Don't remove #pragma ... directives
s	Don't remove keyword signed
t	Don't remove the second argument to va_start()
v	Don't remove the keyword volatile

The icon bar menu

Clicking Menu on the ToPCC application icon on the icon bar gives access to the following options:

For a description of each option in the application menu see the chapter entitled General features of the accompanying Desktop Tools guide.

Example output

Running ToPCC displays any error messages in the standard text output window for non-interactive tools. If all goes well this window is empty:

As an example of using the tool ToPCC, open an empty SrcEdit text window and type the following example C source line in it:

int foo(float a);

Check that your Wimp$Scrap environment variable is set to a sensible file name, then save your new text file straight onto the ToPCC icon bar icon. Run ToPCC, then save the output text file straight onto the SrcEdit icon bar icon. The translated file looks like:

int foo(/* float a */);

Command line interface

For normal use you do not need to understand the syntax of the ToPCC command line, as it is generated automatically for you from the SetUp dialogue box setting before it is used.

The syntax of the ToPCC command line is:

topcc «options» «infile «outfile»»

options	A minus '-' followed by one or more letters controlling individual features of the conversion; see Options. As well as the options listed there, the -d option describes ToPCC, and the -help option gives the command line syntax and options.
infile	Filename of the input C source or header text file, which defaults to stdin.
outfile	Filename of the output C source or header text file, which defaults to stdout.