Step by Step

The following sections present GCC options to let you control each stage of the compiling process: preprocessing, compiling, assembling, and linking. You can also perform the individual steps by invoking separate tools, such as the C preprocessor cpp, the assembler as, and the linker ld. GCC can also be configured to use such external programs on a given host system. For the sake of a uniform overview, however, this chapter shows you how to perform all four steps by invoking GCC and letting it control the process.

$ gcc -E -o circle.i circle.c

$ gcc -E -C -o circle.i circle.c

$ gcc -S circle.c

$ gcc -S -fverbose-asm circle.c

$ gcc -c circle.c

$ gcc -v -o circle -Wa,-as=circle.sym,-L circle.c

$ gcc -g -o circle -Wa,-a=circle.list,-L circle.c

// circle.c: Calculate the areas of circles and
// print them in ncurses mode

#include <curses.h>             // Console control functions
double circularArea( double r );  // Function for the math
void circle();                    // Function for output

int main()        // Starts and stops curses display mode
{

/* Set up the console behavior: */
    (void) initscr();      // Initialize the curses system
    keypad(stdscr, TRUE);  // Enable keyboard mapping
    (void) nonl();         // Disable line-end translation
    (void) cbreak();       // Take single input characters

/* Run the circle routine: */
    circle();
    printw( "Press any key to exit." );
    refresh();             // Put the output on the screen

/* Finish: */
    getch();               // Wait for user to press a key
    endwin();              // Shut down the ncurses console
    return 0;
}

// The circle.c program from Example 1.1 but replacing the
// standard library function printf() with printw() from the
// ncurses library.
void circle()
{
  double radius = 1.0, area = 0.0;
  printw("    Areas of Circles\n\n" );
  printw("     Radius          Area\n"
          "-------------------------\n" );
  area = circularArea( radius );
  printw( "%10.1f     %10.2f\n", radius, area );
  radius = 5.0;
  area = circularArea( radius );
  printw( "%10.1f     %10.2f\n", radius, area );
}

// Return the area of a circle with radius r
double circularArea( double r )
{
  const double pi = 3.1415926536; // Pi is a constant
  return  pi * r * r;
}

$ gcc -o circle circle.c -lncurses

$ gcc -o circle circle.c /usr/local/lib/libncurses.a

$ gcc -o circle -L/usr/local/lib -lncurses circle.c

$ gcc -lncurses -Wl,-Map,circle.map circle.c circulararea.c

Multiple Input Files

In Chapter 1, we went on to divide circle.c into two separate source files (see Examples 1-2 and 1-3). Compiling multiple source files results in multiple object files, each containing the machine code and symbols corresponding to the objects in one source file. GCC uses temporary files for the object output, unless you use the option -c to instruct it to compile only, and not link:

$ gcc -c circle.c
$ gcc -c circulararea.c

These commands produce two object files in the current working directory named circle.o and circulararea.o. You can achieve the same result by putting both source filenames on one GCC command line:

$ gcc -c circle.c circulararea.c

In practice, however, the compiler is usually invoked for one small task at a time. Large programs consist of many source files, which have to be compiled, tested, edited, and compiled again many times during development, and very few of the changes made between builds affect all source files. To save time, a tool such as make (see Chapter 20) controls the build process, invoking the compiler to recompile only those object files that are older than the latest version of the corresponding source file.

Once all the object files have been compiled from current source files, you can use GCC to link them:

$ gcc -o circle circle.o circulararea.o -lncurses

GCC assumes that files with the filename extension .o are object files to be linked.

$ gcc -o bigprg mainpart.c -x assembler trickypart.asm -x c otherpart.c

$ gcc -c circle.c circulararea.s /usr/lib/libm.a

Dynamic Linking and Shared Object Files

Shared libraries are special object files that can be linked to a program at runtime. The use of shared libraries has a number of advantages: a program’s executable file is smaller, and shared modules permit modular updating, as well as more efficient use of the available memory.

To create a shared object file, use GCC’s -shared option. The input file must be an existing object file. Here is a simple example using our circle program:

$ gcc -c circulararea.c
$ gcc -shared -o libcirculararea.so circulararea.o

The second of these two commands creates the shared object file libcirculararea.so. To link an executable to a shared object file, name the object file on the command line like any other object or library file:

$ gcc -c circle.c
$ gcc -o circle circle.o libcirculararea.so -lncurses

This command creates an executable that dynamically links to libcirculararea.so at runtime. Of course, you will also have to make sure that your program can find the shared library at runtime—either by installing your libraries in a standard directory, such as /usr/lib, or by setting an appropriate environment variable such as LIBRARY_PATH. The mechanisms for configuring dynamic loading vary from one system to another.

If shared libraries are available on your system but you want to avoid using them—to exclude a potential opening for rogue code, for example—there are two ways to build statically linked executables with GCC. One is to use the -static option, as in the following command:

$ gcc -static -o circle circle.o circulararea.o -lncurses

The other is to specify a statically linking version of the external library instead of using the -l option on the command line:

$ gcc -o circle circle.o circulararea.o /usr/lib/libncurses.a

The resulting program file may be much larger than the dynamically linked one, however.

Freestanding Programs

In addition to the object and library files you specify on the GCC command line, the linker must also link in the system-specific startup code that the program needs in order to load and interact smoothly with the operating system. This code is already on hand in a standard object file named crt0.o, which contains the actual entry point of the executable program. (The crt stands for “C runtime.”) On most systems, GCC also links programs by default with initialization and clean-up routines in object files named crtbegin.o and crtend.o.

However, if you are writing a freestanding program, such as an operating system or an application for an embedded microcontroller, you can instruct GCC not to link this code by using the -ffreestanding and -nostartfiles options. The option -nostdlib allows you to disable automatic linking to the C standard library. If you use this option, you must provide your own versions of any standard functions used in your program. Finally, in a freestanding environment, a C program need not begin with main(). You can use the linking option -ename on the GCC command line to specify an alternative entry point for your program.

The -O Levels

Each of the -O options represents a number of individual optimization techniques. The-O optimization levels are cumulative: -O2 includes all the optimizations in-O1, and -O3 includes -O2. For complete and detailed descriptions of the different levels, and the many -f optimization options that they represent, see the GCC reference manual. The following list offers a brief description of each level:

-O0

Turn off all optimization options.

-O, -O1

Try to make the executable program smaller and faster, but without increasing compiling time excessively. The techniques applied include merging identical constants, basic loop optimization, and grouping stack operations after successive function calls. A -O with no number is interpreted as -O1.

-O2

Apply almost all of the supported optimization techniques that do not involve a tradeoff between program size and execution speed. This option generally increases the time needed to compile. In addition to the optimizations enabled by -O1, the compiler performs common subexpression elimination, or CSE, which involves detecting mathematically equivalent expressions in the program and rewriting the code to evaluate them only once, saving the value in an unnamed variable for reuse. Furthermore, instructions are reordered to reduce the time spent waiting for data moving between memory and CPU registers. Incidentally, the data flow analysis performed at this level of optimization also allows the compiler to provide additional warnings about the use of uninitialized variables.

-O3

Generate inline functions and enable more flexible allocation of variables to processor registers. Includes the -O2 optimizations.

-Os

Optimize for size. This option is like -O2, but without those performance optimizations that are likely to increase the code size. Furthermore, block reordering and the alignment of functions and other jump destinations on power-of-two byte boundaries are disabled. If you want small executables, you should be compiling with the GCC option -s, which instructs the linker to strip all the symbol tables out of the executable output file after all the necessary functions and objects have been linked. This makes the finished program file significantly smaller, and is often used in building a production version.

The following example illustrates how -O options are used:

$ gcc -Wall -O3 -o circle circle.c circulararea.c -lncurses

This command uses -O3 to enable the majority of the supported optimization techniques.

The -f Flags

GCC’s many -f options give you even finer control over optimization. For example, you can set a general optimization level using an -O option, and then turn off a certain technique. Here is an example:

$ gcc -Wall -O3 -fno-inline-functions -o circle circle.c \
circulararea.c -lncurses

The options -O3 -fno-inline-functions in this command enable all the optimizations grouped in -O3 except inline compiling of functions.

There are also flags to enable many optimizations that are not included in any -O level, such as -funroll-loops; this option replaces loop statements that have a known, small number of iterations with repetitive, linear code sequences, thus saving jumps and loop-counter operations. A full list of the hundred or so -f options that control GCC’s individual optimization flags would be too long for this chapter, but the examples in this section offer a hint of the capabilities available. If you need a certain compiler feature, there’s a good chance you’ll find it in the GCC manual.

Floating-Point Optimization

Some of the optimization options that are not included in the -O groups pertain to floating-point operations. The C99 floating-point environment supports scientific and mathematical applications with a high degree of numeric accuracy, but for a given application, you might be more interested in speed than in the best floating-point math available. For such cases, the -ffast-math option defines the preprocessor macro __FAST_MATH__, indicating that the compiler makes no claim to conform to IEEE and ISO floating-point math standards. The -ffast-math flag is a group option, which enables the following six individual options:

-fno-math-errno

Disables the use of the global variable errno for math functions that represent a single floating-point instruction.

-funsafe-math-optimizations

The “unsafe math optimizations” are those that might violate floating-point math standards, or that do away with verification of arguments and results. Using such optimizations may involve linking code that modifies the floating-point processor’s control flags.

-fno-trapping-math

Generates “nonstop” code on the assumption that no math exceptions will be raised that can be handled by the user program.

-ffinite-math-only

Generates executable code that disregards infinities and NaN (“not a number”) values in arguments and results.

-fno-rounding-math

This option indicates that your program does not depend on a certain rounding behavior, and does not attempt to change the floating-point environment’s default rounding mode. This setting is currently the default, and its opposite, -frounding-math, is still experimental.

-fno-signaling-nans

This option permits optimizations that limit the number of floating-point exceptions that may be raised by signaling NaNs. This setting is currently the default, and its opposite, -fsignaling-nans, is still experimental.

Architecture-Specific Optimization

For certain system architectures, GCC provides options to produce optimized code for specific members of the processor family, taking into account features such as memory alignment, model-specific CPU instructions, stack structures, increased floating-point precision, prefetching and pipelining, and others. These machine-specific options begin with the prefix -m. If you want to compile your code to make the most of a specific target system, read about the available options in the GCC reference manual.

For several processor types, such as the Sparc, ARM, and RS/6000-PowerPC series, the option -mcpu=cpu generates machine code for the specific CPU type’s register set, instruction set, and scheduling behavior. Programs compiled with this option may not run at all on a different model in the same CPU family. The GCC reference manual lists the available cpu abbreviations for each series.

The option -mtune=cpu is more tolerant. Code generated with -mtune=cpu uses optimized scheduling parameters for the given CPU model but adheres to the family’s common instructions and registers, so that it should still run on a related model.

For the Intel x86 series, the -mcpu=cpu option is the same as -mtune=cpu. The option to enable a model-specific instruction set is -march=cpu. Here’s an example:

$ gcc -Wall -O -march=athlon-4 -o circle circle.c circulararea.c \
-lncurses

This command line compiles a program for the AMD Athlon XP CPU.

Why Not Optimize?

Sometimes there are good reasons not to optimize. In general, compiling with optimization takes longer and requires more memory than without optimization. How much more depends on the techniques that are applied. Furthermore, the performance gains obtained by a given optimization technique depend on both the given program and the target architecture. If you really need optimum performance, you need to choose the techniques that will work in your specific circumstances.

You can combine both -O and-f optimization options with GCC’s -g option to include debugging information in the compiled program, but if you do, the results may be hard to follow in a debugging program; optimization can change the order of operations, and variables defined in the program may not remain associated with one register, or may even be optimized out of existence. For these reasons, many developers find it easier to optimize only after a program has been debugged.

Some optimization options may also conflict with strict conformance to the ISO C standard, such as merging variables declared with const as if they were constants. If standards-conformance is critical, and sometimes it is, there are certain optimizations you may not wish to pursue.

Another issue you may encounter is that some optimization techniques result in nondeterministic code generation. For example, the compiler’s guess as to which branch of a conditional jump will be taken most often may involve randomness. If you are programming real-time applications, you’ll probably want to be careful to ensure deterministic behavior.

Finally, when developing multithreaded programs, you need to be aware of how shared memory access works and the features that the threads library offers to control it (see Chapter 14), because optimization can involve rearranging the order of memory access operations, and even eliminate operations that appear superfluous to the compiler in the scope of a single thread.

In any case, if you want to be sure of getting the greatest possible runtime performance, or if you need to know in detail how GCC is arriving at the exact machine code for your C program, there is no substitute for testing and comparing your specific program’s performance with the various optimization options.

Command-Line Options

-c

Preprocess, compile, and assemble only (i.e., don’t link).

-C

Leave comments in when preprocessing.

-Dname[=definition]

Defines the symbol name.

-ename

Start program execution at name.

-E

Preprocess only; output to stdout, unless used with -o.

-ffast-math

Permit faster floating-point arithmetic methods at the cost of accuracy or precision.

-ffinite-math-only

Disregard infinities and NaN (“not a number”) values.

-ffreestanding

Compile as a freestanding (not hosted) program.

-finline-functions, -fno-inline-functions

Enable/disable inline functions.

-fno-math-errno

Disable the errno variable for simple math functions.

-fmerge-constants

Put identical constants in a single location.

-fno-trapping-math

Generate “nonstop” floating-point code.

-frounding-math

Don’t disregard the rounding-mode features of the floating-point environment (experimental).

-fsignaling-nans

Allow all exceptions raised by signaling NaNs (experimental).

-fsyntax-only

Don’t compile or link; just test input for syntax.

-funroll-loops, -fno-unroll-loops

Enable/disable loop optimization.

-funsafe-math-optimizations

Permit optimizations that don’t conform to standards and/or don’t verify values.

-fverbose-asm

Include C variable names as comments in assembly language.

-g[format]

Compile for debugging.

-Idirectory[:directory[…]]

Search for header files in the specified path.

-I-

Distinguish between -Ipath for #include <filename> and -Ipath for #include "filename" (deprecated).

-iquotedirectory[:directory[…]]

Search the specified path for header files specified in quotation marks (#include "filename").

-isysrootdirectory

Prepend the specified directory to the system root directory to find header files.

-lbasename

Link with library libbasename.so or libbasename.a.

-Ldirectory[:directory[…]]

Search for library files in the specified path.

-march=cpu

Intel x86: Generate model-specific code.

-mcpu=cpu

Sparc, ARM, and RS/6000-PowerPC: Generate model-specific code.

Intel x86: Optimize scheduling for the specified CPU model.

-mtune=cpu

Optimize scheduling for the specified CPU model.

-nostartfiles

Don’t link startup code.

-nostdlib

Don’t link with the standard library.

-o filename

Direct output to the specified file.

-O0

Turn off all optimization options.

-O, -O1

Perform some optimization without taking much time.

-O2

Perform more optimization, including data flow analysis.

-O3

Perform still more optimization, including inline function compilation.

-Os

Optimize for size.

-p

Link in code to output profiling information.

-pedantic-errors

Fail on nonstandard usage.

-pg

Link in code to output profiling information for gprof.

-s

Strip symbol tables from executable file.

-S

Preprocess and translate into assembly language only.

-save-temps

Save intermediate output files.

-shared

Create a shared object file for dynamic linking.

-static

Don’t link to shared object files.

-std=iso9899:1990, -std=c89, -ansi

Support ISO/IEC 9899:1990.

-std=iso9899:199409

Support ISO/IEC 9899:1989 and AMD1.

-std=c99

Support ISO/IEC 9899:1999.

-std=c11

Support ISO/IEC 9899:2011.

-std=gnu89

Like -ansi, plus GNU extensions (GCC’s default before version 5).

-std=gnu99

Like -std=c99, plus GNU extensions.

-std=gnu11

Like -std=c11, plus GNU extensions (GCC’s default beginning with version 5).

--sysrootdirectory

Prepend the specified directory to the system root directory to find header and library files. If the -isysroot option is not used, the --sysroot option affects both library and header file searches.

-traditional

Support old-style C. Deprecated; supported only with -E.

-trigraphs

Support ISO C trigraphs.

-Uname

“Undefine” the symbol name.

-v

Be verbose: print the options applied at each step of compiling.

--version

Output GCC version and license information.

-w

Disable all warnings.

-Wa,option[,option[…]]

Pass options to assembler command line.

-Wall

Output warnings about a broad range of problems in source code.

-Wl,option[,option[…]]

Pass options to linker command line.

-Werror

Fail on all warnings.

-Wextra

Output warnings about legal but questionable usage.

-Wtraditional

Warn about differences to old-style C.

-x filetype

Treat subsequent files as being of the specified type.

Environment Variables

CPATH, C_INCLUDE_PATH

Colon-separated list of directories to search for header files, after those indicated by -Idirectory on the command line.

COMPILER_PATH

Colon-separated list of directories to search for GCC’s own subprogram files.

GCC_EXEC_PREFIX

A prefix for GCC to add to the names of its subprograms when invoking them. May end with a slash.

LIBRARY_PATH

Colon-separated list of directories to search for linker and library files, after directories specified by -Ldirectory on the command line.

LD_LIBRARY_PATH

Colon-separated list of directories to search for shared library files. Read not by GCC but by executables dynamically linked against shared libraries.

TMPDIR

Directory to use for temporary files.