Easy C++ Manual

Easy C++ Manual

The compiler

The general form of the compiler command is:

*cc [filename],... [qualifiers]

Qualifiers are keywords that modify the operation of the compiler, and are described in detail later in this chapter.

By default, C compiles source files in subdirectory c of the current directory, and produces object code (in Acorn Object Format) which is placed in subdirectory o of the current directory using the same filename as the source. During compilation, any errors in the source code are reported, and only when all errors have been corrected will the object code be generated.

Naming conventions

In the example given above where $.Programs.General is the current directory, Easy C compiles the source program $.Programs.General.c.HelloW to produce the object file $.Programs.General.o.HelloW . This naming convention is similar to that provided in many other C systems, and should be suitable for most users. However, it may be altered by modifying the system variables C$Source and C$Object using the *set command. C$Source specifies which subdirectory of the current directory contains the C source code, and C$Object specifies which subdirectory of the current directory the object code will be saved in.

The default filename

If the compiler is invoked without specifying a source name, C uses the name specified by the system variable C$CompileFile, which is set by default to HelloW . So typing:

*cc

will compile HelloW in the usual way. You can change the default source filename for example:

*set C$CompileFile program

Compiling multiple files

A number of files may be compiled in one operation by specifying their names separated by commas after the cc command. For example:

*cc file1,file2,file3

This command will generate object files o.file1 , o.file2 and o.file3 .

Include files

Include files are those incorporated into a C program using the #include directive at the start of a source file. Include files are generally headers for libraries, but may also be users own include files. By convention, header files are placed in subdirectory h ; the 'h' may be specified before or after the the filename in the #include directive. Both of the following examples include the header file stdio, but for maximum portability, the first form should normally be used.

#include <stdio.h>

#include <h.stdio>

The C preprocessor handles two forms of #include directives:

System headers

If the filename is placed between angle brackets ( <> ), it indicates that it is a system header file. The order of directories in the search path is:

1. At the path specified by the -include qualifier (if there is one). This is stored in the system variable C$LocalHeaders.

2. At the path specified by the system variable C$HeaderFiles. By default, C$HeaderFiles is set to !EasyC . Within directory !EasyC is an h directory containing all the standard system headers.

Local headers

If the filename is placed between double quotes ( "" ), it indicates that it is a local header file. The order of directories in the search path is:

1. In the local subdirectory h of the current directory.

2. Paths 1 and 2 specified for system headers above.

If the header filename begins with $ or & then it is said to be rooted . Easy C uses rooted filenames exactly as they are entered.

Error messages

During compilation, C generates Errors, Warnings and Informationals. If the compiler cannot understand the source code, an error message is displayed, and object code is not generated. Compilation stops at the end of the source code, or after a specified number of errors have been found (20 by default). Please note that once an error has been detected, other errors may be reported later as a direct consequence of it. Warnings and Informationals are for information only, and do not prevent object code from being generated.

Compiler qualifiers

The compiler is controlled by appending qualifiers to the cc command. Qualifiers are prefixed by a minus sign - , and may be in upper or lower case. A full list of compiler qualifiers may be displayed by entering:

*help cc

In the listing produced, optional parameters are shown in square brackets [] , and the default setting for each qualifier is shown in round brackets () . The vertical bar | is used to separate further modifiers, which may be abbreviated to their initial letters. Notice that many qualifiers may be preceded by the word no to turn the qualifier off.

Quali fier -list

Abbreviation -l

Default -nolist

This qualifier creates a listing of the C source file as it is being compiled. The listing contains lines of source code with line numbers, together with any error or warning messages. Fuller control over the contents of the file can be controlled using the -show qualifier. To compile HelloW and produce a listing, enter:

*cc HelloW -list

By default, C puts listing files in subdirectory list of the current directory using the same name as the source filename. If subdirectory list does not exist, an error message will be displayed.

The name of the default directory for listings is specified by the system variable C$List which may be modified if required. Alternatively, the listing may be directed to any specified file by giving a full pathname, for example:

*cc HelloW -list=$.listings.HelloW_1

Quali fier -optimise

Abbreviation -o

Default -optimise=all

C carries out program optimisation at compile time to produce faster and more compact code. In some situations it may be preferable to switch off all, or individual types of optimisation. This is done with the optimise qualifier. To turn off all optimisation use:

*cc HelloW -nooptimise

If you wish to compile using just Fold optimisation, enter:

*cc HelloW -optimise=fold

The types of optimisation currently supported are:

Fold Evaluates constant expressions at compile time. PeepHole Removes redundant instructions in the executable code.

Quali fier -standard

Abbreviation -s

Default -standard=ANSI

This qualifier is used to ensure that programs conform to a specified standard, and is an aid to producing portable code. For example, if you wish to ensure that your program conforms to the original Kernighan and Ritchie (KR) definition of C, use the following:

*cc HelloW -standard=KR

This changes the syntax acceptable to the compiler, and generates warnings for any code that does not conform. The standards currently supported are:

KR The original Kernighan and Ritchie definition of C. ANSI The implementation of C as defined by the ANSI standard. Extended The extensions added in Easy C. C++ The Easy C++ implementation of the language.

Quali fier -object

Abbreviation -ob

Default -object

The object code generated by the compiler is normally saved in subdirectory o of the current directory, using the same name as the source filename. You may specify a full object pathname using this qualifier, for example:

*cc HelloW -object=$.newname

Quali fier -warnings

Abbreviation -w

Default -warnings

Warnings notify the user that the program contains non-portable or undesirable code. In such circumstances, the compiler displays the offending line number followed by the appropriate warning message. Warnings do not stop the compilation, and object code is still generated. Normally warnings are a useful aid to programming, and are particularly useful for producing portable code. However, if too many warnings are given they may become a nuisance, and can be disabled using:

*cc HelloW -nowarnings

This qualifier can also be followed by a warning level (documented on page 27):

*cc HelloW -warnings=3

Quali fier -informationals

Abbreviation -i

Default -informationals

Informationals notify the user of minor errors or idiosyncrasies in the code. Informationals are the least serious errors that C reports and do not stop the compilation. Informationals may be disabled using:

*cc HelloW -noinformationals

Quali fier -define

Abbreviation -d

Thee -define qualifier allows macros to be defined at compile time. The following example defines macro START :

*cc HelloW -define=START

A number of macros may be defined as follows:

*cc HelloW -define=START,END,LENGTH

To assign values to macros use:

*cc HelloW -define="START 0","END 99","LENGTH 100"

Notice that the macros include a space, and therefore must be enclosed in quotes.

Quali fier -debug

Abbreviation -deb

Default -nodebug

This qualifier is used to specify that debugging information should be generated for use with a separate source level debugger.

Quali fier -errorlimit

Abbreviation -e

Default -errorlimit=20

The qualifier -errorlimit sets the number of errors after which the compiler will terminate. The error limit may be changed by specifying an integer after the qualifier -errorlimit , for example:

*cc HelloW -errorlimit=5

If you want the compiler to compile to the end of the source file regardless of the number of errors found, switch off the error limit using:

*cc HelloW -noerrorlimit

Quali fier -show

Abbreviation -sh

Default -show=source

The -show qualifier controls the listing produced by the -list qualifier. It has seven modifiers which determine what information is included in the listing. For example, if you wish to list assembler code and variables, use:

*cc HelloW -list -show=code,variables

The modifiers are:

Source The C source code is included in the listing.

Expanded Each line is listed twice, with macros expanded in the second line.

Code ARM assembler code is included in the listing.

Variables Lists the variables used, and how they are assigned to the registers.

Includes The source code for any include files is included in the listing.

All All of the above modifiers are used.

None None of the above; the listing contains only error or compiler messages.

Quali fier -silent

Abbreviation -si

Default -nosilent

The -silent qualifier switches off all output during compilation, except for any error messages.

Quali fier -includes

Abbreviation -inc

Default -includes=""

The -include qualifier allows you to specify the path that C will search for local headers i.e. if you include a local header file using the form:

#include "MyHeader.h"

To include $.Programs.General.LocalHead.h.MyHeader in a program NewProg , use the following command:

*cc NewProg -include=$.Programs.LocalHead

The -includes qualifier sets the system variable C$LocalHeaders.

Quali fier -link

Abbreviation -lin

Default -nolink

If the -link qualifier is specified, C links the program automatically after compilation. So the command *cc HelloW -link is equivalent to the following two commands:

*cc HelloW *link HelloW

If the -link qualifier is used, Easy C does not generate an object file, saving time especially on floppy discs and networks (this is not true when compiling from the WIMP front-end—object files are always generated). The -link qualifier may be used when compiling a number of source files, for example:

*cc file1,file2,file3 -link

The object code produced is named after the first filename specified i.e. file1 .

Quali fier -run

Abbreviation -r

Default -norun

If the -run qualifier is specified, C links and runs the program automatically after compilation. The executable file produced will have the same name as the source file. So the command *cc HelloW -run is equivalent to the following three commands:

*cc HelloW *link HelloW *HelloW

Quali fier -image

Abbreviation -im

Default -image

The -image qualifier allows you to specify the full pathname of the file to which the final executable program should be written. The -image qualifier is relevant only if there is a -link or -run qualifier on the command line. For example:

*cc HelloW -link -image=$.hello *cc HelloW -run -image=prog

If -image is omitted, the source filename is used, and is written to the current directory.

Quali fier -library

Abbreviation -lib

Default -library

By default object files are linked with the library specified by Lib$Library (set to STDCLib). The -library qualifier allows you to specify a range of libraries to be linked if the link or -run qualifiers are specified. For example:

*cc HelloW -link -library=STDCLib,ROSLib

Quali fier -base

Abbreviation -b

Default -base=&8000

The -base qualifier sets the base address of the executable code. For example:

*cc HelloW -link -base=&A000

It is relevant only if the -link qualifier is specified.

Quali fier -map

Abbreviation -m

Default -nomap

The -map qualifier is used to produce a map of the functions linked by the -link qualifier. Map files are normally saved in subdirectory map of the current directory with the same filename as the source. If the directory does not exist an error will be displayed.

*cc HelloW -link -map *cc HelloW -link -map=$.mapfile

Further details of the -map qualifier are given below in the section on the linker.

Quali fier -throwback

Abbreviation -th

Default -nothrowback

This qualifier causes errors generated by the compiler to be transmitted to a suitable editor using the throwback facility. Editors currently supporting throwback include SourceEdit and DeskEdit. This facility is only intended for use from the Easy C front-end in the desktop.

Quali fier -desktop

Abbreviation -des

Default -nodesktop

This qualifier causes the compiler to ignore the usual directory naming conventions, and accept full pathnames for source and object files. This facility is only intended for use from the Easy C front-end in the desktop.

Quali fier -profile

Abbreviation -p

Default -profile=none

This qualifier allows the time spent executing functions or specific lines of code to be reported. If this qualifier is used, the program must be run using a speparate debugger or profiler otherwise an error will be reported. There are four modifiers which determine how this qualifier operates:

Function The profiler will give the execution time for functions.

Line The profiler will give execution time for lines.

Both Both of the above will be selected.

None No profile information will be inserted in the code.

APDL and ProAction