Developer Guide

Prerequisites

Possible Code Forms

When using the C and C++ languages, there are three forms of code:

Handling of Code Forms in GCC

Producing executable code from source code requires two steps, which require different applications or tools. GCC can be used as an intelligent driver for both compilers and linkers. This allows you to use a single command gcc for any of the required actions. GCC automatically selects the actions required (compiling and linking), as well as their sequence:

It is possible to run GCC such that only step 1 happens, only step 2 happens, or both steps 1 and 2 happen. This is determined by the types of inputs and requested types of output.

Because larger projects require a build system which usually runs GCC separately for each action, it is helpful to always consider compilation and linking as two distinct actions, even if GCC can perform both at once.

Additional Resources

To create object code files from source files and not an executable file immediately, GCC must be instructed to create only object code files as its output. This action represents the basic operation of the build process for larger projects.

Prerequisites

Procedure

Additional Resources

Because debugging information is large, it is not included in executable files by default. To enable debugging of your C and C++ applications with it, you must explicitly instruct the compiler to create debugging information.

Enabling the Creation of Debugging Information with GCC

To enable the creation of debugging information with GCC when compiling and linking code, use the -g option:

$ gcc ... -g ...

Additional Resources

A single program can be transformed into more than one sequence of machine instructions. An optimal result can be achieved if more resources are allocated for analysis of the code during compilation.

Code Optimization with GCC

With GCC, it is possible to set the optimization level using the -Olevel option. This option accepts a set of values in place of the level.

For release builds, the optimization option -O2 is recommended.

During development, the -Og option is more useful for debugging the program or library in some situations. Because some bugs manifest only with certain optimization levels, ensure to test the program or library with the release optimization level.

GCC offers a large number of options to enable individual optimizations. For more information, see the following Additional Resources.

Additional Resources

When the compiler transforms source code to object code, it can add various checks to prevent commonly exploited situations and thus increase security. Choosing the right set of compiler options can help produce more secure programs and libraries, without changes to the source code.

Release Version Options

The following list of options is the recommended minimum for developers targeting Red Hat Enterprise Linux:

$ gcc ... -O2 -g -Wall -Wl,-z,now,-z,relro -fstack-protector-strong -D_FORTIFY_SOURCE=2 ...

Development Options

The following options are recommended to detect security flaws during development. Use these options in conjunction with the options for the release version:

$ gcc ... -Walloc-zero -Walloca-larger-than -Wextra -Wformat-security -Wvla-larger-than ...

Additional Resources

Linking is the final step when building a C or C++ application. Linking combines all object files and libraries into an executable file.

Prerequisites

Procedure

Additional Resources

The Red Hat ecosystem includes several versions of the GCC compiler and linker, provided in Red Hat Enterprise Linux and Red Hat Developer Toolset. The C++ ABI compatibility between these is as follows:

Additional Resources

This example shows the exact steps to build a sample minimal C program.

Prerequisites

Steps

Additional Resources

This example shows the exact steps to build a sample minimal C++ program.

Prerequisites

Procedure

A special file name convention is used for libraries: A library known as foo is expected to exist as the file libfoo.so or libfoo.a. This convention is automatically understood by the linking input options of gcc, but not by the output options:

Additional Resources

Developers have a choice of using static or dynamic linking when building applications with fully compiled languages. This section lists the differences, particularly in the contexti of using the C and C++ languages on Red Hat Enterprise Linux. To summarize, Red Hat discourages the use of static linking in applications for Red Hat Enterprise Linux.

Comparison of static and dynamic linking

Static linking makes libraries part of the resulting executable file. Dynamic linking keeps these libraries as separate files.

Dynamic and static linking can be compared in a number of ways:

As a result of the listed disadvantages, static linking should be avoided at all costs, particularly for whole applications and the glibc and libstdc++ libraries.

Reasons for static linking

Static linking might be a reasonable choice in some cases, such as:

Additional Resources

A library is a package of code which can be reused in your program. A C or C++ library consists of two parts:

Compiling Code That Uses a Library

The header files describe the interface of the library: The functions and variables available in the library. Information from the header files is needed for compiling the code.

Typically, header files of a library will be placed in a different directory than your application’s code. To tell GCC where the header files are, use the -I option:

$ gcc ... -Iinclude_path ...

Replace include_path with the actual path to the header file directory.

The -I option can be used multiple times to add multiple directories with header files. When looking for a header file, these directories are searched in the order of their appearance in the -I options.

Linking Code That Uses a Library

When linking an executable file, both the object code of your application and the binary code of the library must be available. The code for static and dynamic libraries is present in different forms:

To tell GCC where the archives or shared object files of a library are, use the -L option:

$ gcc ... -Llibrary_path -lfoo ...

Replace library_path with the actual path to the library directory.

The -L option can be used multiple times to add multiple directories. When looking for a library, these directories are searched in the order of their -L options.

The order of options matters: GCC cannot link against a library foo unless it knows the directory of this library. Therefore, use the -L options to specify library directories before using the -l options for linking against libraries.

Compiling and Linking Code Which Uses a Library in One Step

When the situation allows the code to be compiled and linked in one gcc command, use the options for both situations mentioned above at once.

Additional Resources

Static libraries are available as archives containing object files. After linking, they become part of the resulting executable file.

Prerequisites

Procedure

To link a program from source and object files, add a statically linked library foo, which is named libfoo.a:

Dynamic libraries are available as standalone executable files, required at both linking time and run time. They stay independent of your application’s executable file.

Prerequisites

Linking a Program Against a Dynamic Library

To link a program against a dynamic library foo:

$ gcc ... -Llibrary_path -lfoo ...

When a program is linked against a dynamic library, the resulting program must always load the library at run time. There are two options for locating the library:

Using an rpath Value Stored in the Executable File

The rpath is a special value saved as a part of an executable file when it is being linked. Later, when the program is loaded from its executable file, the runtime linker will use the rpath value to locate the library files.

While linking with GCC, to store the path library_path as an rpath:

$ gcc ... -Llibrary_path -lfoo -Wl,-rpath=library_path ...

The path library_path must point to a directory containing the file libfoo.so.

To run the program later, execute:

$ ./program

Using the LD_LIBRARY_PATH Environment Variable

If no rpath is found in the program’s executable file, the runtime linker will use the LD_LIBRARY_PATH environment variable. The value of this variable must be changed for each program according to the path where the shared library objects are located.

To run the program without rpath set, with libraries present in the library_path, execute:

$ export LD_LIBRARY_PATH=library_path:$LD_LIBRARY_PATH
$ ./program

Leaving out the rpath value offers flexibility, but requires setting the LD_LIBRARY_PATH variable every time the program is to run.

Placing the Library into the Default Directories

The runtime linker configuration specifies a number of directories as a default location of dynamic library files. To use this default behaviour, copy your library to the appropriate directory.

A full description of the dynamic linker behavior is out of scope for this document. For more information, see the following resources:

Sometimes it is required to link some libraries statically and some dynamically.

Prerequisites

Introduction

gcc recognizes both dynamic and static libraries. When the -lfoo option is encountered, gcc will first attempt to locate a shared object (a .so file) containing a dynamically linked version of the foo library, and then look for the archive file (.a) containing a static version of the library. Thus, the following situations can result from this search:

Because of these rules, the best way to select the static or dynamic version of a library for linking is having only that version found by gcc. This can be controlled to some extent by using or leaving out directories containing the library versions when specifying the -Lpath options.

Additionally, because dynamic linking is the default, the only situation where linking must be explicitly specified is when a library with both versions present should be linked statically. There are two possible solutions:

Specifying the static libraries by file

Usually, gcc is instructed to link against a library foo with the -lfoo option. However, it is possible to specify the full path to the file libfoo.a containing the library instead:

$ gcc ... path/to/libfoo.a ...

From the file extension .a, gcc will understand that this is a library to link with the program. However, specifying the full path to the library file is a less flexible method.

Using the -Wl option

The gcc option -Wl is a special option for passing options to the underlying linker. Syntax of this option differs from the other gcc options. The -Wl option is followed by a comma-separated list of linker options, while other gcc options require a space-separated list of options. The ld linker used by gcc offers the options -Bstatic and -Bdynamic to specify whether libraries following this option should be linked statically or dynamically, respectively. After passing -Bstatic and a library to the linker, the default dynamic linking behaviour must be restored manually for the following libraries to be linked dynamically with the -Bdynamic option.

To link a program, linking a library first statically (libfirst.a) and second dynamically (libsecond.so), run:

$ gcc ... -Wl,-Bstatic -lfirst -Wl,-Bdynamic -lsecond ...

Additional Resources

A special file name convention is used for libraries: A library known as foo is expected to exist as the file libfoo.so or libfoo.a. This convention is automatically understood by the linking input options of gcc, but not by the output options:

Additional Resources

Dynamically loaded libraries (shared objects) use a mechanism called soname to manage multiple compatible versions of a library.

Prerequisites

Problem Introduction

A dynamically loaded library (shared object) exists as an independent executable file. This makes it possible to update the library without updating the applications that depend on it. However, the following problems arise with this concept:

The soname Mechanism

To resolve this, Linux uses a mechanism called soname.

A library foo version X.Y is ABI-compatible with other versions with the same value of X in the version number. Minor changes preserving compatibility increase the number Y. Major changes that break compatibility increase the number X.

The actual library foo version X.Y exists as the file libfoo.so.x.y. Inside the library file, a soname is recorded with the value libfoo.so.x to signal the compatibility.

When applications are built, the linker looks for the library by searching for the file libfoo.so. A symbolic link with this name must exist, pointing to the actual library file. The linker then reads the soname from the library file and records it into the application executable file. Finally, the linker creates the application so that it declares dependency on the library using the soname, not name or file name.

When the runtime dynamic linker links an application before running, it reads the soname from the executable file of the application. This soname is libfoo.so.x. A symbolic link with this name must exist, pointing to the actual library file. This allows loading the library, regardless of the Y component of the version, because the soname does not change.

Reading soname from a File

To display the soname of a library file somelibrary:

$ objdump -p somelibrary | grep SONAME

Replace somelibrary with the actual file name of the library you wish to examine.

Dynamically linked libraries (shared objects) allow resource conservation through code reuse and increased security by easier updates of the library code. This section describes the steps to build and install a dynamic library from source.

Prerequisites

Procedure

Additional Resources

Creating libraries for static linking is possible through the conversion of object files into a special type of archive file.

Prerequisites

Procedure

Additional Resources

To create a usable form (usually executable files) from the source files of a particular project, perform several necessary steps. Record the actions and their sequence to be able to repeat them later.

Red Hat Enterprise Linux contains GNU make, a build system designed for this purpose.

Prerequisites

GNU make

GNU make reads Makefiles which contain the instructions describing the build process. A Makefile contains multiple rules that describe a way to satisfy a certain condition (target) with a specific action (recipe). Rules can hierarchically depend on another rule.

Running make without any options makes it look for a Makefile in the current directory and attempt to reach the default target. The actual Makefile file name can be one of Makefile, makefile, and GNUmakefile. The default target is determined from the Makefile contents.

Makefile Details

Makefiles use a relatively simple syntax for defining variables and rules, which consists of a target and a recipe. The target specifies the output if a rule is executed. The lines with recipes must start with the tab character.

Typically, a Makefile contains rules for compiling source files, a rule for linking the resulting object files, and a target that serves as the entry point at the top of the hierarchy.

Consider the following Makefile for building a C program which consists of a single file, hello.c.

all: hello

hello: hello.o
        gcc hello.o -o hello

hello.o: hello.c
        gcc -c hello.c -o hello.o

This specifies that to reach the target all, the file hello is required. To get hello, one needs hello.o (linked by gcc), which in turn is created from hello.c (compiled by gcc).

The target all is the default target because it is the first target that does not start with a period. Running make without any arguments is then identical to running make all, if the current directory contains this Makefile.

Typical Makefile

A more typical Makefile uses variables for generalization of the steps and adds a target "clean" which removes everything but the source files.

CC=gcc
CFLAGS=-c -Wall
SOURCE=hello.c
OBJ=$(SOURCE:.c=.o)
EXE=hello

all: $(SOURCE) $(EXE)

$(EXE): $(OBJ)
        $(CC) $(OBJ) -o $@

%.o: %.c
        $(CC) $(CFLAGS) $< -o $@

clean:
        rm -rf $(OBJ) $(EXE)

Adding more source files to such a Makefile requires adding them to the line where the SOURCE variable is defined.

Additional resources

Build a sample C program using a Makefile by following the steps in the example below.

Prerequisites

Procedure

Additional Resources

For more information about make, see the resources listed below.

Installed Documentation

Online Documentation

To debug applications and libraries, debugging information is required. The following sections describe how to obtain this information.

$ gcc ... -g ...

To find why an application does not work properly, control its execution and examine its internal state with a debugger. This section describes how to use the GNU Debugger (GDB) for this task.

$ gdb program

(gdb) file path/to/program

The executable code of applications interacts with the code of the operating system and shared libraries. Recording an activity log of these interactions can provide enough insight into the application’s behavior without debugging the actual application code. Alternatively, analyzing an application’s interactions can help to pinpoint the conditions in which a bug manifests.

$ ltrace ... |& tee your_log_file.log

This section describes what a core dump is and how to use it.

Prerequisites

Description

A core dump is a copy of a part of the application’s memory at the moment the application stopped working, stored in the ELF format. It contains all the application’s internal variables and stack, which enables inspection of the application’s final state. When augmented with the respective executable file and debugging information, it is possible to analyze a core dump file with a debugger in a way similar to analyzing a running program.

The Linux operating system kernel can record core dumps automatically, if this functionality is enabled. Alternatively, you can send a signal to any running application to generate a core dump regardless of its actual state.

To record application crashes, set up core dump saving and add information about the system.

Procedure

Additional Resources

Prerequisites

Procedure

Additional Resources

The workflow of core dump debugging enables the analysis of the offline state of the program. In some cases it is advantageous to use this workflow with a program that is still running, such as when it is hard to access the environment with the process. You can use the gcore command to dump memory of any process while it is still running.

Prerequisites

Procedure

To dump a process memory using gcore:

Additional resources

You can mark the memory of processes as not to be dumped. This can save resources and ensure additional security if the process memory contains sensitive data. Both kernel core dumps (kdump) and manual core dumps (gcore, GDB) do not dump memory marked this way.

In some cases, it is necessary to dump the whole contents of the process memory regardless of these protections. This procedure shows how to do this using the GDB debugger.

Prerequisites

Procedure

Additional Resources

The Valgrind suite is composed of the following tools:

memcheck functions as the default tool when no specific tool is selected.

The valgrind package and its dependencies install all the necessary tools for performing a Valgrind profile run. To profile a program with Valgrind, use:

$ valgrind --tool=toolname program

See Section 22.1, “Valgrind Tools” for a list of arguments for toolname. In addition to the suite of Valgrind tools, none is also a valid argument for toolname; this argument allows you to run a program under Valgrind without performing any profiling. This is useful for debugging or benchmarking Valgrind itself.

You can also instruct Valgrind to send all of its information to a specific file. To do so, use the option --log-file=filename. For example, to check the memory usage of the executable file hello and send profile information to output, use:

$ valgrind --tool=memcheck --log-file=output hello

See Section 22.3, “Additional information” for more information on Valgrind, along with other available documentation on the Valgrind suite of tools.

For more extensive information on Valgrind, see man valgrind. Red Hat Enterprise Linux also provides a comprehensive Valgrind Documentation book available as PDF and HTML in:

operf is the recommended tool for collecting profiling data. The tool does not require any initial configuration, and all options are passed to it on the command line. Unlike the legacy opcontrol tool, operf can run without root privileges. See the Using operf chapter in the System Administrator’s Guide for detailed instructions on how to use the operf tool.

$ ocount -e INST_RETIRED -- sleep 1

Events were actively counted for 1.0 seconds.
Event counts (actual) for /bin/sleep:
Event Count % time counted
INST_RETIRED 683,011 100.00

For more extensive information on OProfile, see the oprofile(1) manual page. Red Hat Enterprise Linux also provides two comprehensive guides to OProfile in file:///usr/share/doc/oprofile-_version_pass:attributes[{blank}]/:

For more detailed information about SystemTap, see the following Red Hat documentation:

Useful perf commands include the following:

Use perf help to obtain a complete list of perf commands. To retrieve man page information on each perf command, use perf help command.

Using the basic PCL infrastructure for collecting statistics or samples of program execution is relatively straightforward. This section provides simple examples of overall statistics and sampling.

To collect statistics on make and its children, use the following command:

# perf stat -- make all

The perf command collects a number of different hardware and software counters. It then prints the following information:

Performance counter stats for 'make all':

  244011.782059  task-clock-msecs         #      0.925 CPUs
          53328  context-switches         #      0.000 M/sec
            515  CPU-migrations           #      0.000 M/sec
        1843121  page-faults              #      0.008 M/sec
   789702529782  cycles                   #   3236.330 M/sec
  1050912611378  instructions             #      1.331 IPC
   275538938708  branches                 #   1129.203 M/sec
     2888756216  branch-misses            #      1.048 %
     4343060367  cache-references         #     17.799 M/sec
      428257037  cache-misses             #      1.755 M/sec

  263.779192511  seconds time elapsed

The perf tool can also record samples. For example, to record data on the make command and its children, use:

# perf record -- make all

This prints out the file in which the samples are stored, along with the number of samples collected:

[ perf record: Woken up 42 times to write data ]
[ perf record: Captured and wrote 9.753 MB perf.data (~426109 samples) ]

Error: open_counter returned with 16 (Device or resource busy). /usr/bin/dmesg may provide additional information.

Fatal: Not all events could be opened.

To use the perf command, first shut down OProfile:

# opcontrol --deinit

You can then analyze perf.data to determine the relative frequency of samples. The report output includes the command, object, and function for the samples. Use perf report to output an analysis of perf.data. For example, the following command produces a report of the executable that consumes the most time:

# perf report --sort=comm

The resulting output:

# Samples: 1083783860000
#
# Overhead          Command
# ........  ...............
#
    48.19%         xsltproc
    44.48%        pdfxmltex
     6.01%             make
     0.95%             perl
     0.17%       kernel-doc
     0.05%          xmllint
     0.05%              cc1
     0.03%               cp
     0.01%            xmlto
     0.01%               sh
     0.01%          docproc
     0.01%               ld
     0.01%              gcc
     0.00%               rm
     0.00%              sed
     0.00%   git-diff-files
     0.00%             bash
     0.00%   git-diff-index

The column on the left shows the relative amount of samples. This output shows that make spends most of this time in xsltproc and pdfxmltex. To reduce the time for make to complete, focus on xsltproc and pdfxmltex. To list functions executed by xsltproc, run:

# perf report -n --comm=xsltproc

This generates:

comm: xsltproc
# Samples: 472520675377
#
# Overhead  Samples                    Shared Object  Symbol
# ........ ..........  .............................  ......
#
    45.54%215179861044  libxml2.so.2.7.6               [.] xmlXPathCmpNodesExt
    11.63%54959620202  libxml2.so.2.7.6               [.] xmlXPathNodeSetAdd__internal_alias
     8.60%40634845107  libxml2.so.2.7.6               [.] xmlXPathCompOpEval
     4.63%21864091080  libxml2.so.2.7.6               [.] xmlXPathReleaseObject
     2.73%12919672281  libxml2.so.2.7.6               [.] xmlXPathNodeSetSort__internal_alias
     2.60%12271959697  libxml2.so.2.7.6               [.] valuePop
     2.41%11379910918  libxml2.so.2.7.6               [.] xmlXPathIsNaN__internal_alias
     2.19%10340901937  libxml2.so.2.7.6               [.] valuePush__internal_alias