Download Red Hat Enterprise Linux 7 Developer Guide

Red Hat Enterprise Linux 7
Developer Guide
An introduction to application development tools in Red Hat Enterprise
Linux 7
Jacquelynn East
Don Domingo
Robert Krátký
Red Hat Enterprise Linux 7 Developer Guide
An introduction to application development tools in Red Hat Enterprise
Linux 7
Jacquelynn East
Red Hat Custo mer Co ntent Services
[email protected] m
Do n Do mingo
Red Hat Custo mer Co ntent Services
ddo mingo @redhat.co m
Ro bert Krátký
Red Hat Custo mer Co ntent Services
[email protected] m
Legal Notice
Co pyright © 20 15 Red Hat, Inc. and o thers.
This do cument is licensed by Red Hat under the Creative Co mmo ns Attributio n-ShareAlike 3.0
Unpo rted License. If yo u distribute this do cument, o r a mo dified versio n o f it, yo u must pro vide
attributio n to Red Hat, Inc. and pro vide a link to the o riginal. If the do cument is mo dified, all Red
Hat trademarks must be remo ved.
Red Hat, as the licenso r o f this do cument, waives the right to enfo rce, and agrees no t to assert,
Sectio n 4 d o f CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shado wman lo go , JBo ss, MetaMatrix, Fedo ra, the Infinity
Lo go , and RHCE are trademarks o f Red Hat, Inc., registered in the United States and o ther
co untries.
Linux ® is the registered trademark o f Linus To rvalds in the United States and o ther co untries.
Java ® is a registered trademark o f Oracle and/o r its affiliates.
XFS ® is a trademark o f Silico n Graphics Internatio nal Co rp. o r its subsidiaries in the United
States and/o r o ther co untries.
MySQL ® is a registered trademark o f MySQL AB in the United States, the Euro pean Unio n and
o ther co untries.
No de.js ® is an o fficial trademark o f Jo yent. Red Hat So ftware Co llectio ns is no t fo rmally
related to o r endo rsed by the o fficial Jo yent No de.js o pen so urce o r co mmercial pro ject.
The OpenStack ® Wo rd Mark and OpenStack Lo go are either registered trademarks/service
marks o r trademarks/service marks o f the OpenStack Fo undatio n, in the United States and o ther
co untries and are used with the OpenStack Fo undatio n's permissio n. We are no t affiliated with,
endo rsed o r spo nso red by the OpenStack Fo undatio n, o r the OpenStack co mmunity.
All o ther trademarks are the pro perty o f their respective o wners.
Abstract
This do cument describes the different features and utilities that make Red Hat Enterprise Linux 7
an ideal enterprise platfo rm fo r applicatio n develo pment.
T able of Cont ent s
T able of Contents
. .hapt
⁠C
. . . .er
. .1. .. Collaborat
. . . . . . . . . ing
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. . . . . . . . . .
⁠1.1. Co nc urrent Vers io ns Sys tem (CVS)
2
⁠1.2. Ap ac he Sub vers io n (SVN)
9
⁠1.3. G it
16
. .hapt
⁠C
. . . .er
. .2. .. Libraries
. . . . . . . . and
. . . .Runt
. . . . ime
. . . .Support
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 2. . . . . . . . . .
⁠2 .1. Vers io n Info rmatio n
22
⁠2 .2. Co mp atib ility
23
⁠2 .3. Lib rary and Runtime Details
24
. .hapt
⁠C
. . . .er
. .3.
. . Compiling
. . . . . . . . . .and
. . . .Building
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. 8. . . . . . . . . .
⁠3 .1. G NU Co mp iler Co llec tio n (G CC)
48
⁠3 .2. Dis trib uted Co mp iling
72
⁠3 .3. Auto to o ls
72
⁠3 .4. b uild -id Uniq ue Id entific atio n o f Binaries
⁠3 .5. So ftware Co llec tio ns and s c l-utils
73
74
. .hapt
⁠C
. . . .er
. .4. .. Debugging
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7. 6. . . . . . . . . .
⁠4 .1. ELF Exec utab le Binaries
76
⁠4 .2. Ins talling Deb ug info Pac kag es
77
⁠4 .3. G DB
80
⁠4 .4. Variab le Trac king at As s ig nments
92
⁠4 .5. Pytho n Pretty-Printers
92
⁠4 .6 . ftrac e
95
. .hapt
⁠C
. . . .er
. .5.
. .Monit
. . . . . oring
. . . . . Performance
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9. 7. . . . . . . . . .
⁠5 .1. Valg rind
97
⁠5 .2. O Pro file
99
⁠5 .3. Sys temTap
10 2
⁠5 .4. Perfo rmanc e Co unters fo r Linux (PCL) To o ls and p erf
10 5
. .hapt
⁠C
. . . .er
. .6. .. Writ
. . . .ing
. . .Document
. . . . . . . . . at
. .ion
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.0. 9. . . . . . . . . .
⁠6 .1. Do xyg en
10 9
.Appendix
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.1. 6. . . . . . . . . .
⁠A .1. mallo p t
116
. . . . . . . .rim
malloc_t
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.1. 6. . . . . . . . . .
. . . . . . . . .at
malloc_st
. .s. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.1. 7. . . . . . . . . .
. . . . her
Furt
. . . Informat
. . . . . . . .ion
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.1. 7. . . . . . . . . .
. . . . . . . . .Hist
Revision
. . . ory
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.1. 8. . . . . . . . . .
⁠I.ndex
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.1. 8. . . . . . . . . .
1
Red Hat Ent erprise Linux 7 Developer G uide
Chapter 1. Collaborating
Effective revision control is essential to all multi-developer projects. It allows all developers in a team
to create, review, revise, and document code in a systematic and orderly manner.
Red Hat_Enterprise Linux 7 is distributed with three of the most popular open source revision control
systems: C VS, SVN , and G it .
This chapter provides information on how to install and use these tools, as well as links to relevant
external documentation.
1.1. Concurrent Versions Syst em (CVS)
C o n cu rren t Versio n s Syst em, commonly abbreviated as C VS, is a centralized version control
system with a client-server architecture. It is a successor to the older R evisio n C o n t ro l Syst em
(R C S). C VS allows multiple developers to cooperate on the same project while keeping track of every
change made to the files that are under revision control.
1.1.1. Inst alling and Configuring CVS
Inst alling t he cvs Package
In Red Hat_Enterprise Linux 7, C VS is provided by the cvs package. To install the cvs package and
all its dependencies on your system, type the following at a shell prompt as ro o t:
yum i nstal l cvs
This installs a command line C VS client, a C VS server, and other related tools to the system.
Se t t ing Up t he De fault Edit o r
When using C VS on the command line, certain commands, such as cvs i mpo rt or cvs co mmi t,
require the user to write a short log message. To determine which text editor to start, the cvs client
application first reads the contents of the environment variable $C VSED IT O R , then reads the more
general environment variable $ED IT O R , and if none of these is set, it starts vi.
To persistently change the value of the $C VSED IT O R environment variable, run the following
command:
echo "expo rt C VSED IT O R = command" >> ~ /. bashrc
This adds the expo rt C VSED IT O R = command line to your ~ /. bashrc file. Replace command with a
command that runs the editor of your choice (for example, emacs). Note that for this change to take
effect in the current shell session, you must execute the commands in ~ /. bashrc by typing the
following at a shell prompt:
so urce ~ /. bashrc
Examp le 1.1. Set t in g u p t h e d ef au lt t ext ed it o r
To configure the C VS client to use Emacs as a text editor, type:
2
⁠Chapt er 1 . Collaborat ing
~]$ echo "expo rt C VSED IT O R = emacs" >> ~ /. bashrc
~]$ so urce ~ /. bashrc
1.1.2. Creat ing a New Reposit ory
A CVS repository is a central place to store files and directories that are under revision control, as well
as additional data, such as a complete history of changes or information about who made those
changes and when. A typical CVS repository stores multiple projects in separate subdirectories
called modules. When publicly accessible, it allows several developers to create a working copy of any
of the modules, make changes, and share these changes with others by committing them back to the
repository.
Init ializing an Em pt y Re po sit o ry
To create a new, empty CVS repository in a directory of your choice, run the following command:
cvs -d path i ni t
Note that path must be an absolute path to the directory in which you want to store the repository (for
example, /var/cvs/). Alternatively, you can specify this path by changing the value of the
$C VSR O O T environment variable:
expo rt C VSR O O T = path
This allows you to omit the path from cvs i ni t and other CVS-related commands:
cvs i ni t
Examp le 1.2. In it ializ in g a n ew C VS rep o sit o ry
To create an empty CVS repository in the ~ /cvs/ directory, type:
~]$ expo rt C VSR O O T = ~ /cvs
~]$ cvs i ni t
Im po rt ing Dat a t o a Re po sit o ry
To put an existing project under revision control, change to the directory in which the project is
stored and run the following command:
cvs [-d cvs_repository] i mpo rt [-m "commit message"] module vendor_tag
release_tag
Note that cvs_repository is a path to the CVS repository, module is the subdirectory into which you
want to import the project (such as pro ject), and vendor_tag and release_tag are vendor and release
tags.
Examp le 1.3. Imp o rt in g a p ro ject t o a C VS rep o sit o ry
3
Red Hat Ent erprise Linux 7 Developer G uide
Let us assume that the directory with your project has the following contents:
~]$ l s mypro ject
AUTHORS doc INSTALL
LICENSE
Makefile
README
src
TODO
Let us further assume that you have an empty CVS repository in the ~ /cvs/ directory. To import
the project under the pro ject directory in this repository with the myco mpany vendor tag and the
i ni t release tag, type:
myproject]$ expo rt C VSR O O T = ~ /cvs
myproject]$ cvs i mpo rt -m "Ini ti al i mpo rt. " pro ject myco mpany i ni t
N project/Makefile
N project/AUTHORS
N project/LICENSE
N project/TODO
N project/INSTALL
...
1.1.3. Checking Out a Working Copy
To check out a working copy of a project in a CVS repository, run the following command:
cvs -d cvs_repository checko ut module
This creates a new directory called module with a working copy of a project in it. Note that
cvs_repository is the URL of the CVS repository and module is the subdirectory in which the project is
stored (such as pro ject). Alternatively, you can set the $C VSR O O T environment variable as follows:
expo rt C VSR O O T = cvs_repository
Then you can use the cvs checko ut command without the -d option:
cvs checko ut module
Examp le 1.4 . C h eckin g o u t a wo rkin g co p y
Let us assume that you have a CVS repository in the ~ /cvs/ directory and that this repository
contains a module named pro ject. To check out a working copy of this module, type:
~]$ expo rt C VSR O O T = ~ /cvs
~]$ cvs checko ut pro ject
cvs checkout: Updating project
U project/AUTHORS
U project/INSTALL
U project/LICENSE
U project/Makefile
U project/TODO
1.1.4 . Adding and Delet ing Files
4
⁠Chapt er 1 . Collaborat ing
Adding a File
To add an existing file to a CVS repository and put it under revision control, change to the directory
with the working copy of the file and run the following command:
cvs ad d file
This schedules the file for addition to the CVS repository. To proceed and actually add the file to the
repository, run the cvs co mmi t command as described in Section 1.1.6, “ Committing Changes” .
Examp le 1.5. Ad d in g a f ile t o a C VS rep o sit o ry
Let us assume that the directory with your working copy of a CVS repository has the following
contents:
project]$ l s
AUTHORS ChangeLog
TODO
CVS
doc
INSTALL
LICENSE
Makefile
README
src
With the exception of C hang eLo g , all files and directories within this directory are already under
revision control. To schedule this file for addition to the CVS repository, type:
project]$ cvs ad d C hang eLo g
cvs add: scheduling file `ChangeLog' for addition
cvs add: use 'cvs commit' to add this file permanently
De le t ing a File
To remove a file from a CVS repository, change to the directory with the working copy of the file and
delete it locally:
rm file
Then schedule this file for removal by using the following command:
cvs remo ve file
To proceed and actually remove the file from the repository, run the cvs co mmi t command as
described in Section 1.1.6, “ Committing Changes” .
Examp le 1.6 . R emo vin g a f ile f ro m a C VS rep o sit o ry
Let us assume that the directory with your working copy of a CVS repository has the following
contents:
project]$ l s
AUTHORS ChangeLog
TODO
CVS
doc
INSTALL
LICENSE
Makefile
README
src
All files in this directory are under revision control. To schedule the T O D O file for removal from the
CVS repository, type:
5
Red Hat Ent erprise Linux 7 Developer G uide
project]$ rm T O D O
project]$ cvs remo ve T O D O
cvs remove: scheduling `TODO' for removal
cvs remove: use 'cvs commit' to remove this file permanently
1.1.5. Viewing Changes
Vie wing t he St at us
To determine the current status of a working copy, change to the directory with the working copy and
run the following command:
cvs status
This displays detailed information about each file that is under revision control, including its current
status (such as Up-to -d ate, Lo cal l y Ad d ed , Lo cal l y R emo ved , or Lo cal l y Mo d i fi ed )
and revision. To display only changes in your working copy, simplify the output by typing the
following at a shell prompt:
cvs status 2>/d ev/nul l | g rep Status: | g rep -v Up-to -d ate
Examp le 1.7. Viewin g t h e st at u s o f a wo rkin g co p y
Let us assume that the directory with your working copy of a CVS repository has the following
contents:
project]$ l s
AUTHORS ChangeLog
CVS
doc
INSTALL
LICENSE
Makefile
README
src
With the exception of C hang eLo g , which is scheduled for addition to the CVS repository, all files
and directories within this directory are already under revision control. The T O D O file, which is
also under revision control, has been scheduled for removal and is no longer present in the
working copy. Finally, Makefi l e contains local changes. To display the status of such a working
copy, type:
project]$ cvs status 2>/d ev/nul l | g rep Status: | g rep -v Up-to -d ate
File: ChangeLog
Status: Locally Added
File: Makefile
Status: Locally Modified
File: no file TODO
Status: Locally Removed
Vie wing Diffe re nce s
To view differences between a working copy and the checked-out content, change to the directory
with the working copy and run the following command:
cvs d i ff [file]
This displays changes to all files in the working copy. To display only changes to a particular file,
supply the file name on the command line.
6
⁠Chapt er 1 . Collaborat ing
Examp le 1.8. Viewin g ch an g es t o a wo rkin g co p y
Let us assume that the directory with your working copy of a CVS repository has the following
contents:
project]$ l s
AUTHORS ChangeLog
CVS
doc
INSTALL
LICENSE
Makefile
README
src
All files in this directory are under revision control, and Makefi l e contains local changes. To
view these changes, type:
project]$ cvs d i ff
cvs diff: Diffing .
cvs diff: ChangeLog is a new entry, no comparison available
Index: Makefile
===================================================================
RCS file: /home/john/cvs/project/Makefile,v
retrieving revision 1.1.1.1
diff -r1.1.1.1 Makefile
156c156
<
-rm -f $(MAN1)
-->
-rm -f $(MAN1) $(MAN7)
cvs diff: TODO was removed, no comparison available
cvs diff: Diffing doc
...
1.1.6. Commit t ing Changes
To share your changes with others and commit them to a CVS repository, change to the directory with
the working copy of your repository and run the following command:
cvs co mmi t [-m "commit message"]
Note that unless you specify the commit message on the command line, CVS opens an external text
editor (vi by default) for you to write it. For information on how to configure which editor to start, see
Section 1.1.1, “ Installing and Configuring CVS” .
Examp le 1.9 . C o mmit t in g ch an g es t o a C VS rep o sit o ry
Let us assume that the directory with your working copy of a CVS repository has the following
contents:
project]$ l s
AUTHORS ChangeLog
CVS
doc
INSTALL
LICENSE
Makefile
README
src
In this working copy, C hang eLo g is scheduled for addition to the CVS repository, Makefi l e is
already under revision control and contains local changes, and the T O D O file, which is also
under revision control, has been scheduled for removal and is no longer present in the working
copy. To commit these changes to the CVS repository, type:
project]$ cvs co mmi t -m "Upd ated the makefi l e. "
7
Red Hat Ent erprise Linux 7 Developer G uide
cvs commit: Examining .
cvs commit: Examining doc
...
RCS file: /home/john/cvsroot/project/ChangeLog,v
done
Checking in ChangeLog;
/home/john/cvsroot/project/ChangeLog,v <-- ChangeLog
initial revision: 1.1
done
Checking in Makefile;
/home/john/cvsroot/project/Makefile,v <-- Makefile
new revision: 1.2; previous revision: 1.1
done
Removing TODO;
/home/john/cvsroot/project/TODO,v <-- TODO
new revision: delete; previous revision: 1.1.1.1
done
1.1.7. Updat ing a Working Copy
To update a working copy and get the latest changes from a CVS repository, change to the directory
with the working copy of your repository and run the following command:
cvs upd ate
Examp le 1.10. U p d at in g a wo rkin g co p y
Let us assume that the directory with your working copy of a CVS repository has the following
contents:
project]$ l s
AUTHORS CVS
doc
INSTALL
LICENSE
Makefile
README
src TODO
Let us further assume that another user has recently added C hang eLo g to the repository,
removed T O D O , and made some changes to Makefi l e. To update this working copy, type:
myproject]$
cvs update:
U ChangeLog
U Makefile
cvs update:
cvs update:
cvs update:
cvs upd ate
Updating .
TODO is no longer in the repository
Updating doc
Updating src
1.1.8. Addit ional Resources
A detailed description of all supported features is beyond the scope of this book. For more
information, see the resources listed below.
Inst alle d Do cum e nt at io n
8
⁠Chapt er 1 . Collaborat ing
cvs(1) — The manual page for the cvs client program provides detailed information on its usage.
1.2. Apache Subversion (SVN)
Ap ach e Su b versio n , commonly abbreviated as SVN , is a centralized version control system with a
client-server architecture. It is a successor to the older C o n cu rren t Versio n s Syst em (C VS),
preserves the same development model, and addresses problems often encountered with C VS.
1.2.1. Inst alling and Configuring Subversion
Inst alling t he subve rsio n Package
In Red Hat_Enterprise Linux 7, Su b versio n is provided by the subversion package. To install the
subversion package and all its dependencies on your system, type the following at a shell prompt as
ro o t:
yum i nstal l subversi o n
This installs a command line Su b versio n client, a Su b versio n server, and other related tools to the
system.
Se t t ing Up t he De fault Edit o r
When using Su b versio n on the command line, certain commands, such as svn i mpo rt or
svn o mmi t, require the user to write a short log message. To determine which text editor to start, the
svn client application first reads the contents of the environment variable $SVN_ED IT O R , then reads
more general environment variables $VISUAL and $ED IT O R , and if none of these is set, it reports an
error.
To persistently change the value of the $SVN_ED IT O R environment variable, run the following
command:
echo "expo rt SVN_ED IT O R = command" >> ~ /. bashrc
This adds the expo rt SVN_ED IT O R = command line to your ~ /. bashrc file. Replace command with
a command that runs the editor of your choice (for example, emacs). Note that for this change to take
effect in the current shell session, you must execute the commands in ~ /. bashrc by typing the
following at a shell prompt:
so urce ~ /. bashrc
Examp le 1.11. Set t in g u p t h e d ef au lt t ext ed it o r
To configure the Su b versio n client to use Emacs as a text editor, type:
~]$ echo "expo rt SVN_ED IT O R = emacs" >> ~ /. bashrc
~]$ . ~ /. bashrc
1.2.2. Creat ing a New Reposit ory
9
Red Hat Ent erprise Linux 7 Developer G uide
A Subversion repository is a central place to store files and directories that are under revision control,
as well as additional data, such as a complete history of changes or information about who made
those changes and when. A typical Subversion repository stores multiple projects in separate
subdirectories. When publicly accessible, it allows several developers to create a working copy of any
of the subdirectories, make changes, and share these changes with others by committing them back to
the repository.
Init ializing an Em pt y Re po sit o ry
To create a new, empty Subversion repository in a directory of your choice, run the following
command:
svnad mi n create path
Note that path is an absolute or relative path to the directory in which you want to store the repository
(for example, /var/svn/). If the directory does not exist, svnad mi n create creates it for you.
Examp le 1.12. In it ializ in g a n ew Su b versio n rep o sit o ry
To create an empty Subversion repository in the ~ /svn/ directory, type:
~]$ svnad mi n create svn
Im po rt ing Dat a t o a Re po sit o ry
To put an existing project under revision control, run the following command:
svn i mpo rt local_path svn_repository/remote_path [-m "commit message"]
Note that local_path is an absolute or relative path to the directory in which you keep the project (use
. for the current working directory), svn_repository is the URL of the Subversion repository, and
remote_path is the target directory in the Subversion repository (for example, pro ject/trunk).
Examp le 1.13. Imp o rt in g a p ro ject t o a Su b versio n rep o sit o ry
Let us assume that the directory with your project has the following contents:
~]$ l s mypro ject
AUTHORS doc INSTALL
LICENSE
Makefile
README
src
TODO
Let us further assume that you have an empty Subversion repository in the ~ /svn/ directory (in
this example, /ho me/jo hn/svn/). To import the project under pro ject/trunk into this
repository, type:
~]$ svn i mpo rt mypro ject fi l e: ///ho me/jo hn/svn/pro ject/trunk -m
"Ini ti al i mpo rt. "
Adding
project/AUTHORS
Adding
project/doc
10
⁠Chapt er 1 . Collaborat ing
Adding
Adding
Adding
...
project/doc/index.html
project/INSTALL
project/src
1.2.3. Checking Out a Working Copy
To check out a working copy of a project in a Subversion repository, run the following command:
svn checko ut svn_repository/remote_path [directory]
This creates a new directory called directory with a working copy of the project in it. Note that
svn_repository is the URL of the Subversion repository, and remote_path is the subdirectory in which
the project is stored.
Examp le 1.14 . C h eckin g o u t a wo rkin g co p y
Let us assume that you have a Subversion repository in the ~ /svn/ directory (in this case,
/ho me/jo hn/svn/) and that this repository contains the latest version of the project in the
pro ject/trunk subdirectory. To check out a working copy of this project, type:
~]$ svn checko ut svn: ///ho me/jo hn/svn/pro ject/trunk pro ject
A
project/AUTHORS
A
project/doc
A
project/doc/index.html
A
project/INSTALL
A
project/src
...
1.2.4 . Adding, Renaming, and Delet ing Files
Adding a File o r Dire ct o ry
To add an existing file to a Subversion repository and put it under revision control, change to the
directory with a working copy of the file and run the following command:
svn ad d file
Similarly, to add a directory and all files that are in it, type:
svn ad d directory
This schedules the files and directories for addition to the Subversion repository. To proceed and
actually add this content to the repository, run the svn co mmi t command as described in
Section 1.2.6, “ Committing Changes” .
Examp le 1.15. Ad d in g a f ile t o a Su b versio n rep o sit o ry
Let us assume that the directory with your working copy of a Subversion repository has the
following contents:
11
Red Hat Ent erprise Linux 7 Developer G uide
project]$ l s
AUTHORS ChangeLog
doc
INSTALL
LICENSE
Makefile
README
src
TODO
With the exception of C hang eLo g , all files and directories within this directory are already under
revision control. To schedule this file for addition to the Subversion repository, type:
project]$ svn ad d C hang eLo g
A
ChangeLog
Re nam ing a File o r Dire ct o ry
To rename an existing file or directory in a Subversion repository, change to the directory with a
working copy of the file or the directory and run the following command:
svn mo ve old_name new_name
This creates a duplicate of the original file or directory, schedules it for addition, and automatically
deletes the original. To proceed and actually rename the content in the Subversion repository, run
the svn co mmi t command as described in Section 1.2.6, “ Committing Changes” .
Examp le 1.16 . R en amin g a f ile in a Su b versio n rep o sit o ry
Let us assume that the directory with your working copy of a Subversion repository has the
following contents:
project]$ l s
AUTHORS ChangeLog
doc
INSTALL
LICENSE
Makefile
README
src
TODO
All files in this directory are under revision control. To schedule the LIC ENSE file for renaming to
C O P Y ING , type:
project]$ svn mo ve LIC ENSE C O P Y ING
A
COPYING
D
LICENSE
Note that svn mo ve automatically renames the file in your working copy:
project]$ l s
AUTHORS ChangeLog
COPYING
doc
INSTALL
Makefile
README
src TODO
De le t ing a File o r Dire ct o ry
To remove a file from a Subversion repository, change to the directory with a working copy of the file
and run the following command:
svn d el ete file…
Similarly, to remove a directory and all files that are in it, type:
12
⁠Chapt er 1 . Collaborat ing
svn d el ete directory…
This schedules the files and directories for removal from the Subversion repository. To proceed and
actually remove this content from the repository, run the svn co mmi t command as described in
Section 1.2.6, “ Committing Changes” .
Examp le 1.17. D elet in g a f ile f ro m a Su b versio n rep o sit o ry
Let us assume that the directory with your working copy of a Subversion repository has the
following contents:
project]$ l s
AUTHORS ChangeLog
COPYING
doc
INSTALL
Makefile
README
src TODO
All files in this directory are under revision control. To schedule the T O D O file for removal from the
Subversion repository, type:
project]$ svn d el ete T O D O
D
TODO
Note that svn d el ete automatically deletes the file from your working copy:
project]$ l s
AUTHORS ChangeLog
COPYING
doc
INSTALL
Makefile
README
src
1.2.5. Viewing Changes
Vie wing t he St at us
To determine the current status of a working copy, change to the directory with the working copy and
run the following command:
svn status
This displays information about all changes to the working copy. See Table 1.1, “ Subversion Status
Symbols” for an explanation of the symbols used in the output of the svn status command.
T ab le 1.1. Su b versio n St at u s Symb o ls
Symb o l
Mean in g
A
D
M
C
?
File is scheduled for addition.
File is scheduled for removal.
File contains local changes.
File with contains unresolved conflicts.
File is not under revision control.
Examp le 1.18. Viewin g t h e st at u s o f a wo rkin g co p y
Let us assume that the directory with your working copy of a Subversion repository has the
following contents:
13
Red Hat Ent erprise Linux 7 Developer G uide
project]$ l s
AUTHORS ChangeLog
COPYING
doc
INSTALL
Makefile
README
src
With the exception of C hang eLo g , which is scheduled for addition to the Subversion repository,
all files and directories within this directory are already under revision control. The T O D O file,
which is also under revision control, has been scheduled for removal and is no longer present in
the working copy. The LIC ENSE file has been renamed to C O P Y ING , and Makefi l e contains
local changes. To display the status of such a working copy, type:
project]$ svn status
D
LICENSE
D
TODO
A
ChangeLog
A +
COPYING
M
Makefile
Vie wing Diffe re nce s
To view differences between a working copy and the checked-out content, change to the directory
with the working copy and run the following command:
svn d i ff [file]
This displays changes to all files in the working copy. To display only changes to a particular file,
supply the file name on the command line.
Examp le 1.19 . Viewin g ch an g es t o a wo rkin g co p y
Let us assume that the directory with your working copy of a Subversion repository has the
following contents:
project]$ l s
AUTHORS ChangeLog
COPYING
CVS
doc
INSTALL
Makefile
README
src
All files in this directory are under revision control and Makefi l e contains local changes. To
view these changes, type:
project]$ svn d i ff Makefi l e
Index: Makefile
===================================================================
--- Makefile
(revision 1)
+++ Makefile
(working copy)
@ @ -153,7 +153,7 @ @
-rmdir $(man1dir)
clean:
+
-rm -f $(MAN1)
-rm -f $(MAN1) $(MAN7)
%.1: %.pl
$(POD2MAN) --section=1 --release="Version $(VERSION)" \
14
⁠Chapt er 1 . Collaborat ing
1.2.6. Commit t ing Changes
To share your changes with others and commit them to a Subversion repository, change to the
directory with a working copy of the changes and run the following command:
svn co mmi t [-m "commit message"]
Note that unless you specify the commit message on the command line, Subversion opens an
external text editor for you to write it. For information on how to configure which editor to start, see
Section 1.2.1, “ Installing and Configuring Subversion” .
Examp le 1.20. C o mmit t in g ch an g es t o a Su b versio n rep o sit o ry
Let us assume that the directory with your working copy of a Subversion repository has the
following contents:
project]$ l s
AUTHORS ChangeLog
COPYING
doc
INSTALL
Makefile
README
src
In this working copy, C hang eLo g is scheduled for addition to the Subversion repository,
Makefi l e already is under revision control and contains local changes, and T O D O , which is
also under revision control, has been scheduled for removal and is no longer present in the
working copy. Additionally, the LIC ENSE file has been renamed to C O P Y ING . To commit these
changes to the Subversion repository, type:
project]$ svn co mmi t -m "Upd ated the makefi l e. "
Adding
COPYING
Adding
ChangeLog
Deleting
LICENSE
Sending
Makefile
Deleting
TODO
Transmitting file data ..
Committed revision 2.
1.2.7. Updat ing a Working Copy
To update a working copy and get the latest changes from a Subversion repository, change to the
directory with the working copy and run the following command:
svn upd ate
Examp le 1.21. U p d at in g a wo rkin g co p y
Let us assume that the directory with your working copy of a Subversion repository has the
following contents:
project]$ l s
AUTHORS doc
INSTALL
LICENSE
Makefile
README
src TODO
15
Red Hat Ent erprise Linux 7 Developer G uide
Let us further assume that somebody recently added C hang eLo g to the repository, removed the
T O D O file from it, changed the name of LIC ENSE to C O P Y ING , and made some changes to
Makefi l e. To update this working copy, type:
myproject]$ svn upd ate
D
LICENSE
D
TODO
A
COPYING
A
Changelog
M
Makefile
Updated to revision 2.
1.2.8. Addit ional Resources
A detailed description of all supported features is beyond the scope of this book. For more
information, see the resources listed below.
Inst alle d Do cum e nt at io n
svn hel p — The output of the svn hel p command provides detailed information about the use
of svn .
svnad mi n hel p — The output of the svnad mi n hel p command provides detailed information
about the use of svn ad min .
Online Do cum e nt at io n
Version Control with Subversion — The official Subversion website refers to the Version Control
with Subversion manual, which provides an in-depth description of Subversion, its administration,
and its usage.
1.3. Git
G it is a distributed revision control system with a peer-to-peer architecture. As opposed to centralized
version control systems with a client-server model, G it ensures that each working copy of a G it
repository is its exact copy with complete revision history. This not only allows you to work on and
contribute to projects without the need to have permission to push your changes to their official
repositories, but also makes it possible for you to work with no network connection.
1.3.1. Inst alling and Configuring Git
Inst alling t he git Package
In Red Hat_Enterprise Linux 7, G it is provided by the git package. To install the git package and all
its dependencies on your system, type the following at a shell prompt as ro o t:
~]# yum i nstal l g i t
Co nfiguring t he De fault T e xt Edit o r
Certain G it commands, such as g i t co mmi t, require the user to write a short message or make
some changes in an external text editor. To determine which text editor to start, G it attempts to read
16
⁠Chapt er 1 . Collaborat ing
the value of the G IT _ED IT O R environment variable, the co re. ed i to r configuration option, the
VISUAL environment variable, and finally the ED IT O R environment variable in this particular order.
If none of these options and variables are specified, the g i t command starts vi as a reasonable
default option.
To change the value of the co re. ed i to r configuration option in order to specify a different text
editor, type the following at a shell prompt:
g i t co nfi g --g l o bal co re. ed i to r command
Replace command with the command to be used to start the selected text editor.
Examp le 1.22. C o n f ig u rin g t h e D ef au lt T ext Ed it o r
To configure G it to use vi m as the default text editor, type the following at a shell prompt:
~]$ g i t co nfi g --g l o bal co re. ed i to r vi m
Se t t ing Up Use r Info rm at io n
In G it , each commit (or revision) is associated with the full name and email of the person responsible
for it. By default, G it uses an identity based on the user name and the host name.
To change the full name associated with your G it commits, type the following at a shell prompt:
g i t co nfi g --g l o bal user. name "full name"
To change the email address associated with your G it commits, type:
g i t co nfi g --g l o bal user. emai l "email_address"
Examp le 1.23. Set t in g U p U ser In f o rmat io n
To configure G it to use Jo hn D o e as your full name and jo hn@ exampl e. co m as your email
address, type the following at a shell prompt:
~]$ g i t co nfi g --g l o bal user. name "Jo hn D o e"
~]$ g i t co nfi g --g l o bal user. emai l "jo hn@ exampl e. co m"
1.3.2. Creat ing a New Reposit ory
A repository is a place where G it stores all files that are under revision control, as well as additional
data related to these files, such as the complete history of changes or information about who made
those changes and when. Unlike in centralized revision control systems like Subversion or CVS, a
G it repository and a working directory are usually the same. A typical G it repository also only stores
a single project and when publicly accessible, it allows anyone to create its clone with a complete
revision history.
Init ializing an Em pt y Re po sit o ry
17
Red Hat Ent erprise Linux 7 Developer G uide
To create a new, empty G it repository, change to the directory in which you want to keep the
repository and type the following at a shell prompt:
g i t i ni t
This creates a hidden directory named . g i t in which all repository information is stored.
Im po rt ing Dat a t o a Re po sit o ry
To put an existing project under revision control, create a G it repository in the directory with the
project and run the following command:
g i t ad d .
This marks all files and directories in the current working directory as ready to be added to the G it
repository. To proceed and actually add this content to the repository, commit the changes by typing
the following at a shell prompt:
g i t co mmi t [-m "commit message"]
Replace commit message with a short description of your revision. Omit the -m option to write the
commit message in an external text editor. For information on how to configure the default text editor,
see Section 1.3.1, “ Configuring the D efault Text Editor” .
1.3.3. Cloning an Exist ing Reposit ory
To clone an existing G it repository, type the following at a shell prompt:
g i t cl o ne git_repository [directory]
Replace git_repository with a URL or a path to the G it repository you want to clone, and directory with
a path to the directory in which you want to store the clone.
1.3.4 . Adding, Renaming, and Delet ing Files
Adding File s and Dire ct o rie s
To add an existing file to a G it repository and put it under revision control, change to the directory
with your local G it repository and type the following at a shell prompt:
g i t ad d file
Replace file with the file or files you want to add. This command marks the selected file or files as
ready to be added to the G it repository. Similarly, to add all files that are stored in a certain directory
to a G it repository, type:
g i t ad d directory
Replace directory with the directory or directories you want to add. This command marks all files in
the selected directory or directories as ready to be added to the G it repository.
To proceed and actually add this content to the repository, commit the changes as described in
Section 1.3.6, “ Committing Changes” .
18
⁠Chapt er 1 . Collaborat ing
Re nam ing File s and Dire ct o rie s
To rename an existing file or directory in a G it repository, change to the directory with your local G it
repository and type the following at a shell prompt:
g i t mv old_name new_name
Replace old_name with the current name of the file or directory and new_name with the new name. This
command renames the selected file or directory and marks it as ready to be renamed in the G it
repository.
To proceed and actually rename the content in the repository, commit the changes as described in
Section 1.3.6, “ Committing Changes” .
De le t ing File s and Dire ct o rie s
To delete an existing file from a G it repository, change to the directory with your local G it repository
and type the following at a shell prompt:
g i t rm file
Replace file with the file or files you want to delete. This command deletes all selected files and marks
them as ready to be deleted form the G it repository. Similarly, to delete all files that are stored in a
certain directory from a G it repository, type:
g i t rm -r directory
Replace directory with the directory or directories you want to delete. This command deletes all
selected directories and marks them as ready to be deleted from the G it repository.
To proceed and actually delete this content from the repository, commit the changes as described in
Section 1.3.6, “ Committing Changes” .
1.3.5. Viewing Changes
Vie wing t he Curre nt St at us
To determine the current status of your local G it repository, change to the directory with the
repository and type the following command at a shell prompt:
g i t status
This command displays information about all uncommitted changes in the repository (new fi l e,
renamed , d el eted , or mo d i fi ed ) and tells you which changes will be applied the next time you
commit them. For information on how to commit your changes, see Section 1.3.6, “ Committing
Changes” .
Vie wing Diffe re nce s
To view all changes in a G it repository, change to the directory with the repository and type the
following at a shell prompt:
g i t d i ff
19
Red Hat Ent erprise Linux 7 Developer G uide
This command displays changes between the files in the repository and their latest revision. If you
are only interested in changes in a particular file, supply its name on the command line as follows:
g i t d i ff file. . .
Replace file with the file or files you want to view.
1.3.6. Commit t ing Changes
To apply your changes to a G it repository and create a new revision, change to the directory with
the repository and type the following command at a shell prompt:
g i t co mmi t [-m "commit message"]
Replace commit message with a short description of your revision. This command commits all
changes in files that are explicitly marked as ready to be committed. To commit changes in all files
that are under revision control, add the -a command line option as follows:
g i t co mmi t -a [-m "commit message"]
Note that if you omit the -m option, the command allows you to write the commit message in an
external text editor. For information on how to configure the default text editor, see Section 1.3.1,
“ Configuring the D efault Text Editor” .
1.3.7. Sharing Changes
Unlike in centralized version control systems such as C VS or Su b versio n , when working with G it ,
project contributors usually do not make their changes in a single, central repository. Instead, they
either create a publicly accessible clone of their local repository, or submit their changes to others
over email as patches.
Pushing Change s t o a Public Re po sit o ry
To push your changes to a publicly accessible G it repository, change to the directory with your
local repository and type the following at a shell prompt:
g i t push remote_repository
Replace remote_repository with the name of the remote repository you want to push your changes to.
Note that the repository from which you originally cloned your local copy is automatically named
o ri g i n.
Cre at ing Pat che s fro m Individual Co m m it s
To create patches from your commits, change to the directory with your local G it repository and type
the following at a shell prompt:
g i t fo rmat-patch remote_repository
Replace remote_repository with the name of the remote repository from which you made your local
copy. This creates a patch for each commit that is not present in this remote repository.
1.3.8. Updat ing a Reposit ory
20
⁠Chapt er 1 . Collaborat ing
1.3.8. Updat ing a Reposit ory
To update your local copy of a G it repository and get the latest changes from a remote repository,
change to the directory with your local G it repository and type the following at a shell prompt:
g i t fetch remote_repository
Replace remote_repository with the name of the remote repository. This command fetches information
about the current status of the remote repository, allowing you to review these changes before
applying them to your local copy. To proceed and merge these changes with what you have in your
local G it repository, type:
g i t merg e remote_repository
Alternatively, you can perform both these steps at the same time by using the following command
instead:
g i t pul l remote_repository
1.3.9. Addit ional Resources
A detailed description of G it and its features is beyond the scope of this book. For more information
about this revision control system, see the resources listed below.
Inst alle d Do cum e nt at io n
g it t u t o rial(7) — The manual page named g it t u t o rial provides a brief introduction to G it and
its usage.
g it t u t o rial- 2(7) — The manual page named g it t u t o rial- 2 provides the second part of a brief
introduction to G it and its usage.
Git User's Manual — HTML documentation for G it is located at /usr/share/d o c/g i t1. 8. 3/user-manual . html .
Online Do cum e nt at io n
Pro Git — The online version of the Pro Git book provides a detailed description of G it , its
concepts and its usage.
21
Red Hat Ent erprise Linux 7 Developer G uide
Chapter 2. Libraries and Runtime Support
Red Hat Enterprise Linux supports the development of custom applications in a wide variety of
programming languages using proven, industrial-strength tools. This chapter describes the runtime
support libraries provided in Red Hat Enterprise Linux 7.
2.1. Version Informat ion
The following table compares the version information for runtime support packages in supported
programming languages between Red Hat Enterprise Linux 7, Red Hat Enterprise Linux 6, Red Hat
Enterprise Linux 5, and Red Hat Enterprise Linux 4.
This is not an exhaustive list. Instead, this is a survey of standard language runtimes, and key
dependencies for software developed on Red Hat Enterprise Linux 7.
T ab le 2.1. Lan g u ag e an d R u n t ime Lib rary Versio n s
Packag e N ame
R ed H at
En t erp rise 7
R ed H at
En t erp rise 6
R ed H at
En t erp rise 5
R ed H at
En t erp rise 4
glibc
libstdc++
boost
java
2.12
4.8
1.53
1.7
2.5
4.1
1.33
1.4, 1.5, and 1.6
2.3
3.4
1.32
1.4
python
php
ruby
httpd
postgresql
mysql
nss
openssl
libX11
firefox
kdebase
gtk2
2.7
5.4
2.0
2.4
9.2
5.4
3.15
1.0.1e
1.6
24.4
4.10
2.24
2.12
4.4
1.41
1.5 (IBM), 1.6
(IBM, OpenJD K,
Oracle Java)
2.6
5.3
1.8
2.2
8.4
5.1
3.12
1.0.0
1.3
3.6
4.3
2.18
2.4
5.1
1.8
2.2
8.1
5.0
3.12
0.9.8e
1.0
3.6
3.5
2.10
2.3
4.3
1.8
2.0
7.4
4.1
3.12
0.9.7a
3.6
3.3
2.04
Note
The co mpat-g l i bc RPM is included with Red Hat Enterprise Linux 7, but it is not a runtime
package and therefore not required for running anything. It is solely a development package,
containing header files and dummy libraries for linking. This allows compiling and linking
packages to run in older Red Hat Enterprise Linux versions (using co mpat-g cc-* against
those headers and libraries). Running rpm -q pi co mpat-g l i bc-* will provide some
information on how to use this package.
For more information on co mpat-g l i b, see Section 2.3.1, “ co mpat-g l i bc”
22
⁠Chapt er 2 . Libraries and Runt ime Support
2.2. Compat ibilit y
Compatibility specifies the portability of binary objects and source code across different instances of
a computer operating environment. Officially, Red Hat supports current release and two consecutive
prior versions. This means that applications built on Red Hat Enterprise Linux 4 and Red Hat
Enterprise Linux 5 will continue to run on Red Hat Enterprise Linux 6 as long as they comply with
Red Hat guidelines (using the symbols that have been white-listed, for example).
Red Hat understands that as an enterprise platform, customers rely on long-term deployment of their
applications. For this reason, applications built against C/C++ libraries with the help of compatibility
libraries continue to be supported for ten years.
There are two types of compatibility:
So u rce C o mp at ib ilit y
Source compatibility specifies that code will compile and execute in a consistent and
predictable way across different instances of the operating environment. This type of
compatibility is defined by conformance with specified Application Programming Interfaces
(APIs).
B in ary C o mp at ib ilit y
Binary Compatibility specifies that compiled binaries in the form of executables and
Dynamic Shared Objects (D SOs) will run correctly across different instances of the operating
environment. This type of compatibility is defined by conformance with specified Application
Binary Interfaces (ABIs).
For further information regarding this and all levels of compatibility between core and non-core
libraries, see Red Hat Enterprise Linux supported releases accessed at
https://access.redhat.com/support/policy/updates/errata/ and the general Red Hat Enterprise Linux
compatibility policy, accessed at https://access.redhat.com/site/articles/119073.
2.2.1. St at ic Linking
Static linking is emphatically discouraged for all Red Hat Enterprise Linux releases. Static linking
causes far more problems than it solves, and should be avoided at all costs.
The main drawback of static linking is that it is only guaranteed to work on the system on which it
was built, and even then only until the next release of glibc or libstdc++ (in the case of C++). There is
no forward or backward compatibility with a static build. Furthermore, any security fixes (or generalpurpose fixes) in subsequent updates to the libraries will not be available unless the affected
statically linked executables are re-linked.
A few more reasons why static linking should be avoided are:
Larger memory footprint.
Slower application startup time.
Reduced glibc features with static linking.
Security measures like load address randomization cannot be used.
D ynamic loading of shared objects outside of glibc is not supported.
For additional reasons to avoid static linking, see: Static Linking Considered Harmful.
23
Red Hat Ent erprise Linux 7 Developer G uide
2.3. Library and Runt ime Det ails
2.3.1. co mpat-g l i bc
co mpat-g l i bc provides a subset of the shared static libraries from previous versions of Red Hat
Enterprise Linux. For Red Hat Enterprise Linux 7, the following libraries are provided:
l i banl
l i bci d n
l i bcrypt
l i bc
l i bd l
l i bm
l i bnsl
l i bpthread
l i breso l v
l i brt
l i bthread _d b
l i buti l
This set of libraries allows developers to create a Red Hat Enterprise Linux 6 application with Red Hat
Enterprise Linux 7, provided the application uses only the above libraries. Use the following
command to do so:
# g cc -fg nu89 -i nl i ne -I /usr/l i b/x86 _6 4 -red hat-l i nux6 E/i ncl ud e -B
/usr/l i b/x86 _6 4 -red hat-l i nux6 E/l i b6 4 /
Important
Applications that violate the ISO with regards to overlapping source or destination memory
locations for memcpy and other functions will likely fail.
2.3.2. T he GNU C+ + St andard Library
The l i bstd c+ + package contains the GNU C++ Standard Library, which is an ongoing project to
implement the ISO 14882 Standard C++ library.
Installing the l i bstd c+ + package will provide just enough to satisfy link dependencies (that is,
only shared library files). To make full use of all available libraries and header files for C++
development, you must install l i bstd c+ + -d evel as well. The l i bstd c+ + -d evel package also
contains a GNU-specific implementation of the Standard Template Library (STL).
For Red Hat Enterprise Linux 4, 5, and 6, the C++ language and runtime implementation has
remained stable and as such no compatibility libraries are required for l i bstd c+ + . However, this is
24
⁠Chapt er 2 . Libraries and Runt ime Support
not the case for Red Hat Enterprise Linux 2 and 3. For Red Hat Enterprise Linux 2 co mpatl i bstd c+ + -29 6 is required to be installed. For Red Hat Enterprise Linux 3 co mpat-l i bstd c+ + 33 is required to be installed. Neither of these are installed by default so have to be added separately.
2 .3.2 .1 . GNU C++ St andard Library Updat e s
The Red Hat Enterprise Linux 6 version of the GNU C++ Standard Library features the following
improvements over its Red Hat Enterprise Linux 5 version:
Added support for elements of ISO C++ TR1, namely:
<tr1/array>
<tr1/co mpl ex>
<tr1/memo ry>
<tr1/functi o nal >
<tr1/rand o m>
<tr1/reg ex>
<tr1/tupl e>
<tr1/type_trai ts>
<tr1/uno rd ered _map>
<tr1/uno rd ered _set>
<tr1/uti l i ty>
<tr1/cmath>
Added support for elements of the upcoming ISO C++ standard, C++0x. These elements include:
<array>
<chro no >
<co nd i ti o n_vari abl e>
<fo rward _l i st>
<functi o nal >
<i ni tal i zer_l i st>
<mutex>
<rand o m>
<rati o >
<reg ex>
<system_erro r>
<thread >
<tupl e>
25
Red Hat Ent erprise Linux 7 Developer G uide
<type_trai ts>
<uno rd ered _map>
<uno rd ered _set>
Added support for the -fvi si bi l i ty command.
Added the following extensions:
__g nu_cxx: : typel i st
__g nu_cxx: : thro w_al l o cato r
For more information about updates to l i bstd c+ + in Red Hat Enterprise Linux, see the C++ Runtime
Library section of the following documents:
GCC 4.2 Release Series Changes, New Features, and Fixes: http://gcc.gnu.org/gcc-4.2/changes.html
GCC 4.3 Release Series Changes, New Features, and Fixes: http://gcc.gnu.org/gcc-4.3/changes.html
GCC 4.4 Release Series Changes, New Features, and Fixes: http://gcc.gnu.org/gcc-4.4/changes.html
2 .3.2 .2 . GNU C++ St andard Library Do cum e nt at io n
To use the man pages for library components, install the l i bstd c+ + -d o cs package. This will
provide man page information for nearly all resources provided by the library; for example, to view
information about the vecto r container, use its fully-qualified component name:
man std : : vecto r
This will display the following information (abbreviated):
std::vector(3)
std::vector(3)
NAME
std::vector A standard container which offers fixed time access to individual
elements in any order.
SYNOPSIS
Inherits std::_Vector_base< _Tp, _Alloc >.
Public Types
typedef _Alloc allocator_type
typedef __gnu_cxx::__normal_iterator< const_pointer, vector >
const_iterator
typedef _Tp_alloc_type::const_pointer const_pointer
typedef _Tp_alloc_type::const_reference const_reference
typedef std::reverse_iterator< const_iterator >
The l i bstd c+ + -d o cs package also provides manuals and reference information in HTML form at
the following directory:
fi l e: ///usr/share/d o c/l i bstd c+ + -d o cs-version/html /spi ne. html
The main site for the development of libstdc++ is hosted on gcc.gnu.org.
26
⁠Chapt er 2 . Libraries and Runt ime Support
2.3.3. Boost
The bo o st package contains a large number of free peer-reviewed portable C++ source libraries.
These libraries are suitable for tasks such as portable file-systems and time/date abstraction,
serialization, unit testing, thread creation and multi-process synchronization, parsing, graphing,
regular expression manipulation, and many others.
Installing the bo o st package will provide just enough libraries to satisfy link dependencies (that is,
only shared library files). To make full use of all available libraries and header files for C++
development, you must install bo o st-d evel as well.
The bo o st package is actually a meta-package, containing many library sub-packages. These subpackages can also be installed individually to provide finer inter-package dependency tracking. The
meta-package includes all of the following sub-packages:
bo o st-d ate-ti me
bo o st-fi l esystem
bo o st-g raph
bo o st-i o streams
bo o st-math
bo o st-pro g ram-o pti o ns
bo o st-pytho n
bo o st-reg ex
bo o st-seri al i zati o n
bo o st-si g nal s
bo o st-system
bo o st-test
bo o st-thread
bo o st-wave
Not included in the meta-package are packages for static linking or packages that depend on the
underlying Message Passing Interface (MPI) support.
MPI support is provided in two forms: one for the default Open MPI implementation ⁠ [1] , and another
for the alternate MPICH2 implementation. The selection of the underlying MPI library in use is up to
the user and depends on specific hardware details and user preferences. Please note that these
packages can be installed in parallel, as installed files have unique directory locations.
For Open MPI:
bo o st-o penmpi
bo o st-o penmpi -d evel
bo o st-g raph-o penmpi
bo o st-o penmpi -pytho n
27
Red Hat Ent erprise Linux 7 Developer G uide
For MPICH2:
bo o st-mpi ch2
bo o st-mpi ch2-d evel
bo o st-g raph-mpi ch2
bo o st-mpi ch2-pytho n
If static linkage cannot be avoided, the bo o st-stati c package will install the necessary static
libraries. Both thread-enabled and single-threaded libraries are provided.
2 .3.3.1 . Bo o st Updat e s
The Red Hat Enterprise Linux 6 version of Boost features many packaging improvements and new
features.
Several aspects of the bo o st package have changed. As noted above, the monolithic bo o st
package has been augmented by smaller, more discrete sub-packages. This allows for more control
of dependencies by users, and for smaller binary packages when packaging a custom application
that uses Boost.
In addition, both single-threaded and multi-threaded versions of all libraries are packaged. The
multi-threaded versions include the mt suffix, as per the usual Boost convention.
Boost also features the following new libraries:
Foreach
Statechart
TR1
Typeof
Xpressive
Asio
Bitmap
Circular Buffer
Function Types
Fusion
GIL
Interprocess
Intrusive
Math/Special Functions
Math/Statistical D istributions
MPI
System
28
⁠Chapt er 2 . Libraries and Runt ime Support
Accumulators
Exception
Units
Unordered
Proto
Flyweight
Scope Exit
Swap
Signals2
Property Tree
Many of the existing libraries have been improved, bug-fixed, and otherwise enhanced.
2 .3.3.2 . Bo o st Do cum e nt at io n
The bo o st-d o c package provides manuals and reference information in HTML form located in the
following directory:
fi l e: ///usr/share/d o c/bo o st-d o c-version/i nd ex. html
The main site for the development of Boost is hosted on boost.org.
2.3.4 . Qt
The q t package provides the Qt (pronounced " cute" ) cross-platform application development
framework used in the development of GUI programs. Aside from being a popular " widget toolkit" , Qt
is also used for developing non-GUI programs such as console tools and servers. Qt was used in
the development of notable projects such as Google Earth, KD E, Opera, OPIE, VoxOx, Skype, VLC
media player and VirtualBox. It is produced by Nokia's Qt D evelopment Frameworks division, which
came into being after Nokia's acquisition of the Norwegian company Trolltech, the original producer
of Qt, on June 17, 2008.
Qt uses standard C++ but makes extensive use of a special pre-processor called the Meta Object
Compiler (MOC) to enrich the language. Qt can also be used in other programming languages via
language bindings. It runs on all major platforms and has extensive internationalization support.
Non-GUI Qt features include SQL database access, XML parsing, thread management, network
support, and a unified cross-platform API for file handling.
D istributed under the terms of the GNU Lesser General Public License (among others), Qt is free and
open source software. The Red Hat Enterprise Linux 6 version of Qt supports a wide range of
compilers, including the GCC C++ compiler and the Visual Studio suite.
2 .3.4 .1 . Qt Updat e s
Some of the improvements the Red Hat Enterprise Linux 6 version of Qt include:
Advanced user experience
Ad van ced G rap h ics Ef f ect s: options for opacity, drop-shadows, blur, colorization, and
other similar effects
29
Red Hat Ent erprise Linux 7 Developer G uide
An imat io n an d St at e Mach in e: create simple or complex animations without the hassle of
managing complex code
Gesture and multi-touch support
Support for new platforms
Windows 7, Mac OSX 10.6, and other desktop platforms are now supported
Added support for mobile development; Qt is optimized for the upcoming Maemo 6 platform,
and will soon be ported to Maemo 5. In addition, Qt now supports the Symbian platform, with
integration for the S60 framework.
Added support for Real-Time Operating Systems such as QNX and VxWorks
Improved performance, featuring added support for hardware-accelerated rendering (along with
other rendering updates)
Updated cross-platform ID E
For more details on updates to Qt included in Red Hat Enterprise Linux 6, see the following links:
http://doc.qt.nokia.com/4.6/qt4-6-intro.html
http://doc.qt.nokia.com/4.6/qt4-intro.html
2 .3.4 .2 . Qt Cre at o r
Q t C reat o r is a cross-platform ID E tailored to the requirements of Qt developers. It includes the
following graphical tools:
An advanced C++ code editor
Integrated GUI layout and forms designer
Project and build management tools
Integrated, context-sensitive help system
Visual debugger
Rapid code navigation tools
2 .3.4 .3. Qt Library Do cum e nt at io n
The q t-d o c package provides HTML manuals and references located in
/usr/share/d o c/q t4 /html /. This package also provides the Qt Reference Documentation, which
is an excellent starting point for development within the Qt framework.
You can also install further demos and examples from q t-d emo s and q t-exampl es. To get an
overview of the capabilities of the Qt framework, see /usr/bi n/q td emo -q t4 (provided by q td emo s).
2.3.5. KDE Development Framework
The kd el i bs-d evel package provides the KD E libraries, which build on Qt to provide a framework
for making application development easier. The KD E development framework also helps provide
consistency across the KD E desktop environment.
2 .3.5 .1 . KDE4 Archit e ct ure
30
⁠Chapt er 2 . Libraries and Runt ime Support
2 .3.5 .1 . KDE4 Archit e ct ure
The KD E development framework's architecture in Red Hat Enterprise Linux uses KD E4, which is built
on the following technologies:
Plasma
Plasma replaces KD esktop in KD E4. Its implementation is based on the Q t G rap h ics
View Framewo rk, which was introduced in Qt 4.2. For more information about Plasma,
see http://techbase.kde.org/D evelopment/Architecture/KD E4/Plasma.
So n n et
So n n et is a multilingual spell-checking application that supports automatic language
detection, primary/backup dictionaries, and other useful features. It replaces kspel l 2 in
KD E4.
K IO
The KIO library provides a framework for network-transparent file handling, allowing users
to easily access files through network-transparent protocols. It also helps provides
standard file dialogs.
K JS/K H T ML
KJS and KHTML are fully-fledged JavaScript and HTML engines used by different
applications native to KD E4 (such as ko n q u ero r).
So lid
So lid is a hardware and network awareness framework that allows you to develop
applications with hardware interaction features. Its comprehensive API provides the
necessary abstraction to support cross-platform application development. For more
information, see http://techbase.kde.org/D evelopment/Architecture/KD E4/Solid.
Ph o n o n
Ph o n o n is a multimedia framework that helps you develop applications with multimedia
functionalities. It facilitates the usage of media capabilities within KD E. For more
information, see http://techbase.kde.org/D evelopment/Architecture/KD E4/Phonon.
T elep at h y
T elep at h y provides a real-time communication and collaboration framework within KD E4.
Its primary function is to tighten integration between different components within KD E. For a
brief overview on the project, see http://community.kde.org/RealTime_Communication_and_Collaboration.
Ako n ad i
Ako n ad i provides a framework for centralizing storage of Parallel Infrastructure Management
(PIM) components. For more information, see
http://techbase.kde.org/D evelopment/Architecture/KD E4/Akonadi.
O n lin e H elp wit h in K D E4
KD E4 also features an easy-to-use Qt-based framework for adding online help capabilities
to applications. Such capabilities include tooltips, hover-help information, and
kh elp cen t er manuals. For a brief overview on online help within KD E4, see
http://techbase.kde.org/D evelopment/Architecture/KD E4/Providing_Online_Help.
31
Red Hat Ent erprise Linux 7 Developer G uide
K XMLG U I
K XMLG U I is a framework for designing user interfaces using XML. This framework allows
you to design UI elements based on " actions" (defined by the developer) without having to
revise source code. For more information, see
http://techbase.kde.org/D evelopment/Architecture/KD E4/XMLGUI_Technology.
St rig i
St rig i is a desktop search daemon compatible with many desktop environments and
operating systems. It uses its own jst ream system which allows for deep indexing of files.
For more information on the development of St rig i, see
http://www.vandenoever.info/software/strigi/.
K N ewSt u f f 2
K N ewSt u f f 2 is a collaborative data sharing library used by many KD E4 applications. For
more information, see http://techbase.kde.org/Projects/KNS2.
2 .3.5 .2 . kde libs Do cum e nt at io n
The kd el i bs-api d o cs package provides HTML documentation for the KD E development
framework in /usr/share/d o c/HT ML/en/kd el i bs4 -api d o cs/. The following links also
provide details on KD E-related programming tasks:
http://techbase.kde.org/
http://techbase.kde.org/D evelopment/Tutorials
http://techbase.kde.org/D evelopment/FAQs
http://api.kde.org
2.3.6. NSS Shared Dat abases
The NSS shared database format, introduced on NSS 3.12, is now available in Red Hat Enterprise 6.
This encompasses a number of new features and components to improve access and usability.
Included, is the NSS certificate and key database which are now sqlite-based and allow for
concurrent access. The legacy key3. d b and cert8. d b are also replaced with new SQL databases
called key4 . d b and cert9 . d b. These new databases will store PKCS #11 token objects, which are
the same as what is currently stored in cert8. d b and key3. d b.
Having support for shared databases enables a system-wide NSS database. It resides in
/etc/pki /nssd b where globally trusted CA certificates become accessible to all applications. The
command rv = NSS_Ini tR ead Wri te("sq l : /etc/pki /nssd b"); initializes NSS for
applications. If the application is run with root privileges, then the system-wide database is available
on a read and write basis. However, if it is run with normal user privileges it becomes read only.
Additionally, a PEM PKCS #11 module for NSS allows applications to load into memory certificates
and keys stored in PEM-formatted files (for example, those produced by openssl).
2 .3.6 .1 . Backwards Co m pat ibilit y
The binary compatibility guarantees made by NSS upstream are preserved in NSS for Red Hat
Enterprise Linux 6. This guarantee states that the NSS 3.12 is backwards compatible with all older
NSS 3.x shared libraries. Therefore, a program linked with an older NSS 3.x shared library will work
without recompiling or relinking, and any applications that restrict the use of NSS APIs to the NSS
32
⁠Chapt er 2 . Libraries and Runt ime Support
Public Functions remain compatible with future versions of the NSS shared libraries.
Red Hat Enterprise Linux 5 and 4 run on the same version of NSS as Red Hat Enterprise Linux 6 so
there are no ABI or API changes. However, there are still differences as NSS's internal cryptographic
module in Red Hat Enterprise Linux 6 is the one from NSS 3.12, whereas Red Hat Enterprise Linux 5
and 4 still use the older one from NSS 3.15. This means that new functionality that had been
introduced with NSS 3.12, such as the shared database, is now available with Red Hat
Enterprise Linux 6's version of NSS.
2 .3.6 .2 . NSS Share d Dat abase s Do cum e nt at io n
Mozilla's wiki page explains the system-wide database rationale in great detail and can be accessed
here.
2.3.7. Pyt hon
The pytho n package adds support for the Python programming language. This package provides
the object and cached bytecode files required to enable runtime support for basic Python programs.
It also contains the pytho n interpreter and the pyd o c documentation tool. The pytho n-d evel
package contains the libraries and header files required for developing Python extensions.
Red Hat Enterprise Linux also ships with numerous pytho n-related packages. By convention, the
names of these packages have a pytho n prefix or suffix. Such packages are either library
extensions or python bindings to an existing library. For instance, d bus-pytho n is a Python
language binding for D -Bus.
Note that both cached bytecode (*. pyc/*. pyo files) and compiled extension modules (*. so files)
are incompatible between Python 2.4 (used in Red Hat Enterprise Linux 5), Python 2.6 (used in
Red Hat Enterprise Linux 6), and Python 2.7 (used in Red Hat Enterprise Linux 7). As such, you will
be required to rebuild any extension modules you use that are not part of Red Hat Enterprise Linux.
2 .3.7 .1 . Pyt ho n Updat e s
Red Hat Enterprise Linux 7 ships with Python 2.7. For information about these changes, see the
following project resource:
What's New in Python 2.7: http://docs.python.org/dev/whatsnew/2.7.html
Both resources also contain advice on porting code developed using previous Python versions.
33
Red Hat Ent erprise Linux 7 Developer G uide
Important
Python provides various APIs for use with C extension modules. One of these APIs,
PyCObject, was deprecated in Python 2.7. By default, deprecation warnings are ignored so
this will not normally cause any problems.
However, if the standard warning settings are overridden, there may be problems with modules
that use PyCObject and assume that the import succeeds. In particular, if warnings have been
set to " error" , it is possible to make the Python interpreter abort or even segfault when
importing such modules due to reading through the NULL pointer triggered by the deprecation
error.
To enable errors-for-warnings and use such a module, add an override so that a
P end i i ng D eprecati o nWarni ng is logged instead of raising an exception.
>>> import warnings
>>> warnings.simplefilter('error')
>>> warnings.simplefilter('default', PendingDeprecationWarning)
2 .3.7 .2 . Pyt ho n De bug Build
Red Hat Enterprise Linux 7 ships with a debug build of the python interpreter in the python-debug
package.
The debug interpreter (found in /usr/bi n/pytho n-d ebug ) runs at about half the speed as the
optimized interpreter (found in /usr/bi n/pytho n) and requires extentions models to be rebuilt for it
but is still of use when writing and debugging Python C extension modules. Within the debug build,
optimization levels are turned down, making it easier to step through code within the debugger.
The debug build is configured with additional debug settings:
--wi th-pyd ebug
Adds various useful methods to sys, such as sys. g etto tal refco unt() and
sys. g eto bjects().
--wi th-co unt-al l o cs
Enables the C O UNT _ALLO C S setting, which adds a sys. g etco unts() method, providing
information on all types.The default upstream behavior is to always dump this information
on std o ut when the process exits. This is patched downstream so that the information is
only dumped on exit if P Y T HO ND UMP C O UNT S is set in the environment.
--wi th-cal l -pro fi l e
Enables the C ALL_P R O FILE setting. This counts the number of function calls executed,
and on how the interpreter handled those calls.
--wi th-tsc ( o n ly o n x86 _6 4 an d p p c6 4 )
Adds a sys. settscd ump() method, adding very low-level profiling of the interpreter.
34
⁠Chapt er 2 . Libraries and Runt ime Support
The debug build uses the same bytecode files as the regular optimized build, but extension modules
(. so files) are not compatible. This is because the in-memory layout of Python objects differs due to
the extra instrumentation. Given an optimized extension model foo. so , the debug build is patched
to look for foo_d . so .
For more information on the debug build and its settings, see the notes upstream at
http://svn.python.org/projects/python/trunk/Misc/SpecialBuilds.txt.
2 .3.7 .3. Pyt ho n Do cum e nt at io n
For more information about Python, see man pytho n. You can also install pytho n-d o cs, which
provides HTML manuals and references in the following location:
fi l e: ///usr/share/d o c/pytho n-d o cs-version/html /i nd ex. html
For details on library and language components, use pyd o c component_name. For example,
pyd o c math will display the following information about the math Python module:
Help on module math:
NAME
math
FILE
/usr/lib64/python2.6/lib-dynload/mathmodule.so
DESCRIPTION
This module is always available. It provides access to the
mathematical functions defined by the C standard.
FUNCTIONS
acos[...]
acos(x)
Return the arc cosine (measured in radians) of x.
acosh[...]
acosh(x)
Return the hyperbolic arc cosine (measured in radians) of x.
asin(...)
asin(x)
Return the arc sine (measured in radians) of x.
asinh[...]
asinh(x)
Return the hyperbolic arc sine (measured in radians) of x.
The main site for the Python development project is hosted on python.org.
2.3.8. Java
Red Hat Enterprise Linux 7 is constantly updated to ship the latest version of JD K. The
35
Red Hat Ent erprise Linux 7 Developer G uide
java-version_number-o penjd k package adds support for the Java programming language.
This package provides the java interpreter. The java-version_number-o penjd k-d evel
package contains the javac compiler, as well as the libraries and header files required for
developing Java extensions.
Red Hat Enterprise Linux also ships with numerous java-related packages. By convention, the
names of these packages have a java prefix or suffix.
2 .3.8 .1 . Java Fe at ure s
Java has a number of new features with Red Hat Enterprise Linux 7. These include the following:
Su p p o rt f o r d yn amically- t yp ed lan g u ag es ( In vo keD yn amic)
Enhancements are made to Hotspot, Open JD K's Java Virtual Machine (JVM). These are
designed to support dynamically typed languages with minimal performance cost as
compared to statically typed languages and Java itself. Specifically, the invokedynamic
instruction was added to the Java bytecode specification and implemented in the JVM.
Small lan g u ag e en h an cemen t s ( Pro ject C o in )
A number of Java language-level improvements that provide programmer conveniences,
more elegant code, and reduces some common programming errors.
St rin g s in swit ch
In prior Java versions, switch statements allowed the use of byte, short, char, and int
primitives and their corresponding object types, as well as enums. As of Java 7, string
values may also be used in switch statements.
B in ary in t eg ral lit erals an d u n d ersco res in n u meric lit erals
Programmers may now express integral literals in binary form, or separate groups of digits
in numerical literal values by underscores, in order to improve code readability.
Mu lt i- cat ch
Java's catch syntax has been improved so that more than one exception type can be
caught in a single catch clause, reducing redundant code.
Mo re p recise ret h ro w
The Java 7 compiler has been improved so that a method that catches and then rethrows
an exception can be more precise in the throws clause of the method declaration in some
circumstances.
Imp ro ved t yp e in f eren ce f o r g en eric in st an ce creat io n ( d iamo n d )
This syntactical improvement allows programmers to use the diamond operator (that is, <>)
instead of the full generic type (for example, <ClassName>) when instantiating variables of
generic types. The type is inferred from that variable's declaration instead.
T ry- wit h - reso u rces st at emen t
This is a new form of try statement for use with closeable resources, such as streams and
files. Using this feature, programmers no longer need to explicitly close these resources.
Simp lif ied varag s met h o d in vo cat io n
Previously, a compiler warning would be issued when calling vararg methods with non-
36
⁠Chapt er 2 . Libraries and Runt ime Support
reifiable arguments. This has been removed and replaced with a warning at the declaration
of a vararg method that can accept non-reifiable arguments. An annotation can be used to
suppress this warning, in which case the developer takes responsibility that the arguments
are correct. This primarily applies to vararg methods that accept generic arguments.
C o n cu rren cy an d co llect io n s u p d at es
A number of new classes and interfaces, including a fork/join framework for divide and
conquer type algorithms, has been added to the java. uti l . co ncurrency package.
These can be useful for improving performance and correctness of multi-threaded
programs.
N ew I/O AIPs f o r t h e Java p lat f o rm
This includes a new file system API to improve cross-platform compatibility while making
graceful failure handling easier for developers. It provides improved socket/channel API in
the java. ni o . channel s package to remove unintuitive dependences on the java. net
package. It also provides a new asynchronous I/O API.
N imb u s lo o k an d f eel f o r swin g
Informally introduced in Java 6 under the co m. sun. java. swi ng package namespace,
Nimbus has a vector-graphics based look and feel for swing. With Java 7, it has become an
official API and moved to the javax. swi ng package.
2 .3.8 .2 . Java Do cum e nt at io n
For more information about Java, see man java. Some associated utilities also have their own
respective man pages.
You can also install other Java documentation packages for more details about specific Java
utilities. By convention, such documentation packages have the javad o c suffix (for example, d busjava-javad o c).
The main site for the development of Java is hosted on http://openjdk.java.net/. The main site for the
library runtime of Java is hosted on http://icedtea.classpath.org.
2.3.9. Ruby
The ruby package provides the Ruby interpreter and adds support for the Ruby programming
language. The ruby-d evel package contains the libraries and header files required for developing
Ruby extensions.
Red Hat Enterprise Linux also ships with numerous ruby-related packages. By convention, the
names of these packages have a ruby or rubyg em prefix or suffix. Such packages are either library
extensions or Ruby bindings to an existing library.
Examples of ruby-related packages include:
ruby-irb
ruby-libguestfs
ruby-libs
ruby-qpid
ruby-rdoc
37
Red Hat Ent erprise Linux 7 Developer G uide
ruby-ri
ruby-tcltk
rubygems
rubygem-bigdecimal
rubygem-devel
rubygem-io-console
rubygem-json
rubygem-minitest
rubygem-rake
Note
If the Bundler is used for managing application dependencies, please always use the Bundler
provided by the rubyg em-bund l er package. The upstream package is not compatible with
the RubyGems layout used by Red Hat Enterprise Linux 7.
2 .3.9 .1 . Ruby Updat e s
For information about updates to the Ruby language in Red Hat Enterprise Linux 7, see the following
resources:
fi l e: ///usr/share/d o c/ruby-version/NEWS
fi l e: ///usr/share/d o c/ruby-version/NEWS-version
Ruby has undergone significant changes in its filesystem layout, which now better conforms with
FHS. Binary libraries and extensions of Gems are placed under /usr/l i b (or /usr/l i b6 4 for 64bit systems) and pure Ruby libraries and Gems are placed under /usr/share. Gems are located in
three places according to the selected method of their installation:
/usr
/usr/l o cal
~ /. g em
2 .3.9 .2 . Ruby Do cum e nt at io n
For more information about Ruby, see man ruby. You can also use the ri command, which is the
Ruby API reference front end. For gem documentation, use the g em server command that makes
HTML manuals and references about gems installed on your system available in a browser.
Note
It may be necessary to install the -doc sub-package to make the documentation available
using the ri and g em server commands.
38
⁠Chapt er 2 . Libraries and Runt ime Support
The main site for the development of Ruby is hotsed on http://www.ruby-lang.org. The
http://www.ruby-doc.org site also contains Ruby documentation. Online documentation for gems can
be found at http://rdoc.info.
D ocumentation for the ri command can be found in /usr/share/ri /system.
2.3.10. Perl
The perl package adds support for the Perl programming language. This package provides some
of the Perl core modules, the Perl Language Interpreter, and the p erld o c tool. Red Hat
Enterprise Linux 7 ships with perl-5.16. To install all of the core modules, use the yum i nstal l
perl -co re command.
Red Hat also provides various perl modules in package form; these packages are named with the
perl -* prefix. These modules provide stand-alone applications, language extensions, Perl
libraries, and external library bindings.
An RPM package can contain more Perl modules. Each module intended for public use is provided
by the package in the form perl(The::Module). This expression can be passed to yum to install the
approprirate packages.
Examp le 2.1. In st all p erl mo d u le
# yum install 'perl(LWP::UserAgent)'
This will install the RPM package perl-libwww-perl, which contains the LWP::U serAg en t module,
allowing a programer to use the command use LWP : : UserAg ent;.
2 .3.1 0 .1 . Pe rl Updat e s
Red Hat Enterprise Linux 7 ships with perl 5.16 which has a number of changes since the 5.10
version shipped in Red Hat Enterprise Linux 6. These include:
Perl 5.12 U p d at es
Perl 5.12 has the following updates:
Perl conforms closer to the Unicode standard.
Experimental APIs allow Perl to be extended with " pluggable" keywords and syntax.
Perl will be able to keep accurate time well past the " Y2038" barrier.
Package version numbers can be directly specified in " package" statements.
Perl warns the user about the use of depreciated features by default.
The Perl 5.12 delta can be accessed at http://perldoc.perl.org/perl5120delta.html.
Perl 5.14 U p d at es
Perl 5.14 has the following updates:
Unicode 6.0 support.
Improved support for IPv6.
39
Red Hat Ent erprise Linux 7 Developer G uide
Easier auto-configuration of the CPAN client.
A new /r flag that makes s/// substitutions non-destructive.
New regular expression flags to control whether matched strings should be treated as
ASCII or Unicode.
New packag e Foo { } syntax.
Less memory and CPU usage than previous releases.
A number of bug fixes.
The Perl 5.14 delta can be accessed at http://perldoc.perl.org/perl5140delta.html.
Perl 5.16 U p d at es
Perl 5.16 has the following updates:
Support for Unicode 6.1.
$$ variable is writable.
Improved debugger.
Accessing Unicode database files directly is now depreciated; use Unicode::UCD instead.
Version::Requirements is depreciated in favor of CPAN::Meta::Requirements.
A number of perl4 libraries are removed:
abbrev.pl
assert.pl
bigfloat.pl
bigint.pl
bigrat.pl
cacheout.pl
complete.pl
ctime.pl
dotsh.pl
exceptions.pl
fastcwd.pl
flush.pl
getcwd.pl
getopt.pl
getopts.pl
hostname.pl
40
⁠Chapt er 2 . Libraries and Runt ime Support
importenv.pl
lib/find.pl
lib/finddepth.pl
look.pl
newgetopt.pl
open2.pl
open3.pl
pwd.pl
hellwords.pl
stat.pl
tainted.pl
termcap.pl
timelocal.pl
The Perl 5.16 delta can be accessed at http://perldoc.perl.org/perl5160delta.html.
2 .3.1 0 .2 . Inst allat io n
Perl's capabilities can be extended by installing additional modules. These modules come in the
following forms:
O f f icial R ed H at R PM
The official module packages can be installed with yum or rpm from the Red Hat
Enterprise Linux repositories. They are installed to /usr/share/perl 5 and either
/usr/l i b/perl 5 for 32bit architectures or /usr/l i b6 4 /perl 5 for 64bit architectures,
as well as vend o r_perl subdirectories.
Mo d u les f ro m C PAN
Use the cpan tool provided by the perl-CPAN package to install modules directly from the
CPAN website. They are installed to /usr/l o cal /share/perl 5 and either
/usr/l o cal /l i b/perl 5 for 32bit architectures or /usr/l o cal /l i b6 4 /perl 5 for
64bit architectures if these directories exist and are writable by the current user.
If the directories do not exist the cpan tool will offer different solutions.
Warning: You do not have write permission for Perl library
directories.
To install modules, you need to configure a local Perl library
directory or escalate your privileges. CPAN can help you by
bootstrapping the local::lib module or by configuring itself to
use 'sudo' (if available). You may also resolve this problem
manually if you need to customize your setup.
41
Red Hat Ent erprise Linux 7 Developer G uide
What approach do you want? (Choose 'local::lib', 'sudo' or
'manual')
[local::lib]
For example, if 'manual' is selected, it will assme the user will ensure the directories exist
and are writable before installing modules from CPAN.
T h ird p art y an d cu st o m mo d u le p ackag es
These packaged modules are installed to /usr/share/perl 5/vend o r_perl and either
/usr/l i b/perl 5/vend o r_perl for 32bit architectures or
/usr/l i b6 4 /perl 5/vend o r_perl for 64bit architectures. If their file names conflict with
Red Hat Enterprise Linux packages, either change the file names or properly replace the
Red Hat Enterprise Linux packages with the delivering packages.
Warning
If an official version of a module is already installed, installing its non-official version can
create conflicts in the /usr/share/man directory.
If an additional Perl module search path is necessary, the
/usr/l o cal /share/perl 5/si tecusto mi ze. pl script can be used for system-wide modification
(see the perl run(1) man page), or perl-homedir package for user specific modifications (see the
perl-homedir package description).
2 .3.1 0 .3. Pe rl Do cum e nt at io n
The perl d o c tool provides documentation on language and core modules. To learn more about a
module, use perl d o c mo d ul e_name. For example, perl d o c C G I will display the following
information about the CGI core module:
NAME
CGI - Handle Common Gateway Interface requests and responses
SYNOPSIS
use CGI;
my $q = CGI->new;
[...]
DESCRIPTION
CGI.pm is a stable, complete and mature solution for processing and
preparing HTTP requests and responses. Major features including
processing form submissions, file uploads, reading and writing cookies,
query string generation and manipulation, and processing and preparing
HTTP headers. Some HTML generation utilities are included as well.
[...]
PROGRAMMING STYLE
There are two styles of programming with CGI.pm, an object-oriented style
and a function-oriented style. In the object-oriented style you create
42
⁠Chapt er 2 . Libraries and Runt ime Support
one or more CGI objects and then use object methods to create the various
elements of the page. Each CGI object starts out with the list of named
parameters that were passed to your CGI script by the server.
[...]
For details on Perl functions, use perl d o c -f function_name. For example, perldoc -f split wil
display the following information about the split function:
split /PATTERN/,EXPR,LIMIT
split /PATTERN/,EXPR
split /PATTERN/
split
Splits the string EXPR into a list of strings and returns that
list. By default, empty leading fields are preserved, and empty trailing
ones are deleted. (If all fields are empty, they are considered to be
trailing.)
In scalar context, returns the number of fields found. In scalar and void
context it splits into the @ _ array. Use of split in scalar and void
context is deprecated, however, because it clobbers your subroutine
arguments.
If EXPR is omitted, splits the $_ string. If PATTERN is also omitted,
splits on whitespace (after skipping any leading whitespace). Anything
matching PATTERN is taken to be a delimiter separating the fields. (Note
that the delimiter may be longer than one character.)
[...]
Current perldoc documentation can be found on perldoc.perl.org.
Core and external modules are documented on the Comprehensive Perl Archive Network.
2.3.11. l i bSto rag eMg mt Plug-ins
Red Hat Enterprise Linux 7 ships with a new library called l i bSto rag eMg mt. It is a storage array
independent Application Programming Interface (API) that provides a stable and consistent API
allowing developers to programmatically manage different storage arrays and leverage the hardware
accelerated features provided.
For more information on the l i bSto rag eMg mt library see Red Hat's Storage Administration Guide.
This section details how to write plug-ins for the library.
Plug-ins work somewhat differently with the l i bSto rag eMg mt library. The plug-ins execute in their
own address space as stand-alone executables with inter-process communication (IPC) between the
client and plug-in. When a client application or the l i bSto rag eMg mt command line (l smcl i )
utilizes the library, the following occurs:
1. The library uses the uniform resource identifier (URI) and parses out which plug-in was
specified. For example, LSMC LI_UR I= si m: // refers to the simulator plug-in.
2. The library uses the plut-in name si m and looks for the unix domain socket in the socket
directory. The default directory is /var/run/l sm/i pc but this can be changed at run-time
by specifying the LSM_UD S_P AT H environment variable.
43
Red Hat Ent erprise Linux 7 Developer G uide
3. The client library opens the unix domain socket, causing the l smd daemon to accept the
connection from the client. The daemon then forks and executes the plut-in, passing the
socket descriptor on the command line to the plug-in. The client process now has a direct
connection to the plug-in.
4. The l smd is no longer in the path and goes back to sleep waiting for another process to
open a socket.
There are a number of benifits to this different design. These include:
If a daemon dies or is killed, any existing client plug-in sessions remain active.
If a plug-in crashes, the client process will remain operational.
The daemon needs to know nothing of the IPC protocol, keeping it simple.
The plug-in can be closed source if required by the vendor.
2 .3.1 1 .1 . Writ ing a plug in fo r l i bSto rag eMg mt library
The l i bSto rag eMg mt library has a plug-in API for both C and Python. Any language that supports
suckets and text can also be used to write a plug-in, but the library provides the abstraction that
hides this complexity.
The following are some general guidelines for plug-in design regardless of the programming
language used:
T h read in g o r mu lt i- p ro cess
The library does not provide locking, nor does it keep any global state. As such, it is valid for a client
to have a spearate plug-in instance in use for each thread or process. Plug-ins can anticipate that
multiple instances of themselves can and possibley will be running at concurrently to different arrays.
As the library provides a mechanism for long-running operations, multiple plug-in instances for the
same array are not needed.
Plu g - in s execu t e wit h n o n - ro o t p rivilag es
To reduce the potential for local exploits, plug-ins have reduced privilages. This needs to be taken
into account when writing and designing plug-ins.
Plu g - in lif et ime
The client API provides for a handle that is opened and closed for each plug-in instance. D uring this
time the plug-in is free to cache whatever data is necessary to provide correct opperation. When
using the l smcl i tool, the lifetime is only for one command.
Lo g g in g
Plug-ins log errors to sysl o g . Helper functions exist to facilitate this in the library.
Erro rs
The library uses well defined error codes in order to remain language agnostic. Additional error data
can be retrieved when they occur to provide textual error messages and optionally debug data from
the plug-in or the array itslef. It is the library callers' responsibility to retrieve this additional
information after an error occurs and before issuing another command. If additional error data exists
44
⁠Chapt er 2 . Libraries and Runt ime Support
and other functions are called, then the aditional error information will be lost. C does not support
exceptions. For languages that do support exceptions, a custom exception class containing the error
code and additional information is provided.
Lo cat io n an d n amin g
Plug-ins are located in the /usr/bi n directory. The name format must be _l smpl ug i n. This is
because when the daemon startsit iterates in the directory enumerating them.
Jo b C o n t ro l
The methods to get and set the time-out are used to specify how long the plug-in waits for a response
from the array. If an operation can not safely complete within the time-out, the call returns a job id so
that the client can check on the status of the operation. Job ID s are free form strings and are plug-in
defined. The plug-in implementation needs to determine everything about the asynchronous
operation from this string between invocations of the plug-in.
To write a plug-in, the following base functions or methods are required for all plug-ins, regardless of
the language used:
get/set timeout
startup/shutdown
job status
job free
capabilities
plug-in information
pools
systems
A unique name must also be chosen so that the main execuatble has the form name_l smpl ug i n.
The following sections detail how to write a plug-in for python and for C.
2.3.11.1.1. Writ in g a p lu g - in wit h Pyt h o n
First, implement the interface that supports the level of functionality to be provided (see
i pl ug i n. py). Most plug-ins will either inherit from lStorageAreaNetwork or INfs, or both if the plugin supports block and network file systems.
Next, call the plug-in runner, passing the name of the class and the command line arguments to it for
processing and executing the run method.
​# !/usr/bin/env python
​i mport sys
​from lsm.pluginrunner import PluginRunner
​from lsm.simulator import StorageSimulator
​i f __name__ == '__main__':
​
PluginRunner(StorageSimulator, sys.argv).run()
45
Red Hat Ent erprise Linux 7 Developer G uide
Note
D uring development it is possible to call the plug-in directly on the command line for easier
debugging.
2.3.11.1.2. Writ in g a p lu g - in wit h C
First, include the required header file #i ncl ud e
<l i bsto rag emg mt/l i bsto rag emg mt_pl ug _i nterface. h>.
Then, implement the callback functions that will be supported, along with the required ones.
Finally, pass the command line count and arguments to the library with load and unload functions.
​# include <libstoragemgmt/libstoragemgmt_plug_interface.h>
​# include <stdlib.h>
​# include <stdint.h>
​static char name[] = "Simple limited plug-in example";
​static char version [] = "0.01";
​struct plugin_data {
​
uint32_t tmo;
​
/* All your other variables as needed */
​} ;
​/ * Create the functions you plan on implementing that
​
match the callback signatures */
​static int tmoSet(lsm_plugin_ptr c, uint32_t timeout, lsm_flag flags )
​{
​
int rc = LSM_ERR_OK;
​
struct plugin_data *pd = (struct
plugin_data*)lsm_private_data_get(c);
​
/* Do something with state to set timeout */
​
pd->tmo = timeout;
​
return rc;
​
}
​static int tmoGet(lsm_plugin_ptr c, uint32_t *timeout, lsm_flag flags )
​
{
​
int rc = LSM_ERR_OK;
​
struct plugin_data *pd = (struct
plugin_data*)lsm_private_data_get(c);
​
/* Do something with state to get timeout */
​
*timeout = pd->tmo;
​
return rc;
​
}
​/ * Setup the function addresses in the appropriate
​
required callback structure */
​static struct lsm_mgmt_ops_v1 mgmOps = {
​
tmoSet,
​
tmoGet,
​
NULL,
46
⁠Chapt er 2 . Libraries and Runt ime Support
​
NULL,
NULL,
NULL,
NULL
​
​
​
​} ;
​i nt load( lsm_plugin_ptr c, const char *uri, const char *password,
​
uint32_t timeout, lsm_flag flags )
​{
​
/* Do plug-in specific init. and setup callback structures */
​
struct plugin_data *data = (struct plugin_data *)
​
malloc(sizeof(struct plugin_data));
​
if (!data) {
return LSM_ERR_NO_MEMORY;
}
​
​
​
/* Call back into the framework */
int rc = lsm_register_plugin_v1( c, data, & mgmOps, NULL, NULL, NULL);
return rc;
​
​
​}
​i nt unload( lsm_plugin_ptr c, lsm_flag flags)
​
{
​
/* Get a handle to your private data and do clean-up */
​
struct plugin_data *pd = (struct
plugin_data*)lsm_private_data_get(c);
​
free(pd);
​
return LSM_ERR_OK;
​
}
​i nt main(int argc, char *argv[] )
​
{
​
return lsm_plugin_init_v1(argc, argv, load, unload, name, version);
​
}
2 .3.1 1 .2 . Writ ing Plug-in Re fe re nce s
The libStorageMgmt Writing Plug-ins wiki
https://sourceforge.net/p/libstoragemgmt/wiki/WritingPlugins/
[1] MPI s up p o rt is no t availab le o n IBM Sys tem Z mac hines (where O p en MPI is no t availab le).
47
Red Hat Ent erprise Linux 7 Developer G uide
Chapter 3. Compiling and Building
Red Hat Enterprise Linux includes many packages used for software development, including tools for
compiling and building source code. This chapter discusses several of these packages and tools
used to compile source code.
3.1. GNU Compiler Collect ion (GCC)
The GNU Compiler Collection (GCC) is a set of tools for compiling a variety of programming
languages (including C, C++, ObjectiveC, ObjectiveC++, Fortran, and Ada) into highly optimized
machine code. These tools include various compilers (like g cc and g + + ), run-time libraries (like
l i bg cc, l i bstd c+ + , l i bg fo rtran, and l i bg o mp), and miscellaneous other utilities.
Red Hat Enterprise Linux 7 is on PPC64 architecture. This means that GCC generates code for
POWER7 platforms with tuning to POWER7 by default. The following tables detail the default codes
for various platforms:
T ab le 3.1. D ef au lt C o d es f o r i?86
O p t io n
D ef au lt C o d e
mtune
march
generic
x86-64
red hat-rpm-co nfi g , used for building packages, also contains the -mfpmath= sse option.
T ab le 3.2. D ef au lt C o d es f o r x86 _6 4
O p t io n
D ef au lt C o d e
mtune
march
generic
x86-64
T ab le 3.3. D ef au lt C o d es f o r s39 0 an d s39 0x
O p t io n
D ef au lt C o d e
mtune
march
zEC12
z196
T ab le 3.4 . D ef au lt C o d es f o r p p c, p p c6 4 , an d p p c6 4 p 7
O p t io n
D ef au lt C o d e
mtune
mcpu
power7
power7
The above table is for both 32-bit and 64-bit compilations.
It is possible to generate code for other targets using the -march= C P U option. Tuning the code for a
specific chip is performed by using the -mtune= C P U option. The -march option implies the -mtune
option. The -march= nati ve option instructs the compiler to generate code for the processor type of
the compiling machine.
48
⁠Chapt er 3. Compiling and Building
Note
The -march option does not exist on PPC64 architecture. Use the -mcpu option instead.
3.1.1. Changes in GCC
Red Hat D eveloper Toolset 2.0 is distributed with G C C 4 .8, which provides a number of bug fixes
and feature enhancements over the Red Hat Enterprise Linux system version and the version
included in Red Hat D eveloper Toolset 1.1. Below is a comprehensive list of new features and
compatibility changes in this release.
3.1 .1 .1 . Change s Since Re d Hat De ve lo pe r T o o lse t 1 .1
The following features have been added since the release of GCC included in Red Hat D eveloper
Toolset 1.1.
3.1.1.1.1. C aveat s
Ag g ressive Lo o p O p t imiz at io n s
The loop optimizer of GCC has been improved to use language constraints in order to derive bounds
for the number of iterations of a loop. The bounds are then used as a guide to loop unrolling,
peeling, and loop exit test optimizations.
The optimizations assume that the loop code does not invoke undefined behavior by, for example,
causing signed integer overflows or making out-of-bound array accesses. For example, consider the
following code fragment:
​u nsigned int foo()
​
{
​
unsigned int data_data[128];
​
​
for (int fd = 0; fd < 128; ++fd)
data_data[fd] = fd * (0x02000001); // error
​
return data_data[0];
​}
When the value of the fd variable is 64 or above, the fd * 0 x0 20 0 0 0 0 1 operation overflows,
which is invalid in both C and C++ for signed integers. In the example above, GCC may generate
incorrect code or enter an infinite loop.
To fix this error, use the appropriate casts when converting between signed and unsigned types to
avoid overflows, for instance:
​d ata_data[fd] = (uint32_t) fd * (0x02000001U); // ok
If necessary, this optimization can be turned off by using the new command line option -fno ag g ressi ve-l o o p-o pti mi zati o ns.
3.1.1.1.2. G en eral Imp ro vemen t s an d C h an g es
N ew Lo cal R eg ist er Allo cat o r
49
Red Hat Ent erprise Linux 7 Developer G uide
GCC 4.8 features a new Local Register Allocator (LRA), which replaces the 26-year old reload pass and
improves the quality of generated code. The new local register allocator is meant to be simpler, easier
to debug, and does a better job of register allocation.
Ad d ressSan it iz er
A fast memory error detector called AddressSanitizer has been added and can be enabled by using
the -fsani ti ze= ad d ress command line option. It augments memory access instructions in order
to detect use-after-free and out-of-bound accesses to objects on the heap.
T h read San it iz er
A fast data race detector called ThreadSanitizer has been added in GCC 4.8. The option to enable this
feature is -fsani ti ze= thread .
C o mp ilin g Ext remely Larg e Fu n ct io n s
Many scalability bottlenecks have been removed from GCC optimization passes. As a consequence,
it is now possible to compile extremely large functions with smaller memory consumption in less time.
N ew - O g O p t imiz at io n Level
A new general optimization level, -O g , has been introduced. This optimization level addresses the
need for fast compilation and a superior debugging experience while providing a reasonable level of
runtime performance. Overall, the development experience should be better than the default
optimization level -O 0 .
C aret D iag n o st ic Messag es
The diagnostic messages of GCC, which display a line of source code, now also show a caret that
indicates the column where the problem was detected. For example:
fred.cc:4:15: fatal error: foo: No such file or directory
#include <foo>
^
compilation terminated.
N ew - f ira- h o ist - p ressu re O p t io n
A new command line option, -fi ra-ho i st-pressure, has been added. This option uses the
register allocator to help decide when it is worthwhile to move expressions out of loops. It can reduce
the size of the compiler code, but it slows down the compiler. This option is enabled by default at O s.
N ew - f o p t - in f o O p t io n
A new command line option, -fo pt-i nfo , has been added. This option controls printing
information about the effects of particular optimization passes, and takes the following form:
-fo pt-i nfo [-info][= file_name]
The info part of the option controls what is printed. Replace it with o pti mi zed to print information
when optimization takes place, mi ssed to print information when optimization does not take place,
no te to print more verbose information, or o ptal l to print everything.
50
⁠Chapt er 3. Compiling and Building
Replace file_name with the name of the file in which you want the information to be written. If you omit
this part of the option, GCC writes the information to the standard error output stream.
For example, to display a list of optimizations that were enabled by the -O 2 option but had no effect
when compiling a file named fo o . c, type:
g cc -O 2 -fo pt-i nfo -mi ssed fo o . c
N ew - f lo o p - n est - o p t imiz e O p t io n
A new command line option, -fl o o p-nest-o pti mi ze, has been added. This option enables an
experimental ISL-based loop nest optimizer, a generic loop nest optimizer that is based on the Pluto
optimization algorithms and that calculates a loop structure optimized for data-locality and
paralelism. For more information about this optimizer, see http://pluto-compiler.sourceforge.net.
H o t an d C o ld At t rib u t es o n Lab els
The hot and cold function attributes can now also be applied to labels. Hot labels tell the compiler
that the execution path following the label is more likely than any other execution path, and cold
labels convey the opposite meaning. These attributes can be used in cases where
__bui l ti n_expect cannot be used, for instance with a computed g o to or asm g o to .
3.1.1.1.3. D eb u g g in g En h an cemen t s
D WAR F4
D WAR F4 is now used as the default debugging data format when generating debugging
information. To get the maximum benefit from this new debugging representation, use the latest
version of Valg rin d , elf u t ils, and G D B included in this release.
N ew - g sp lit - d warf O p t io n
A new command line option, -g spl i t-d warf, has been added. This option tells the compiler driver
to separate as much D WARF debugging information as possible into a separate output file with the
. d wo file extension, and allows the build system to avoid linking files with debugging information.
In order to be useful, this option requires a debugger capable of reading . d wo files, such as the
version of G D B included in Red Hat D eveloper Toolset 2.0.
Note
elf u t ils, Syst emT ap , and Valg rin d do not support the . d wo files.
3.1.1.1.4 . C + + C h an g es
Exp erimen t al C + + Feat u res f ro m an U p co min g St an d ard
g + + now supports a new command line option, -std = c+ + 1y. This option can be used for
experimentation with features proposed for the next revision of the standard that is expected around
2014. Currently, the only difference from -std = c+ + 11 is support for return type deduction in normal
functions as proposed in N3386.
N ew t h read _lo cal K eywo rd
51
Red Hat Ent erprise Linux 7 Developer G uide
g + + now implements the C++11 thread _l o cal keyword. In comparison with the GNU __thread
keyword, thread _l o cal allows dynamic initialization and destruction semantics.
The use of the thread _l o cal keyword has currently one important limitation: when the
d l cl o se() function is used to unload a dynamically loaded D SO that contains the definition of a
thread _l o cal object, the thread _l o cal object is destroyed, its destructor is called and the D SO
is unmapped from the address space of the process. If a thread in the process tries to access the
thread _l o cal object after this, the program may terminate unexpectedly. As a result, the
programmer may have to take extra care to ensure that thread _l o cal objects in a D SO are not
referred after it has been unloaded.
See also the next item for dynamic initialization issues.
D yn amic In it ializ at io n o f T h read - lo cal Variab les
The C++11 and OpenMP standards allow thread-local and thread-private variables to have dynamic
(that is, runtime) initialization. To support this, any use of such a variable goes through a wrapper
function that performs necessary initialization.
When the use and definition of the variable are in the same translation unit, this overhead can be
optimized away, but when the use is in a different translation unit, there is significant overhead even
if the variable does not actually need dynamic initialization. If the programmer can be sure that no
use of the variable in a non-defining translation unit needs to trigger dynamic initialization (either
because the variable is statically initialized, or a use of the variable in the defining translation unit
will be executed before any uses in another translation unit), they can avoid this overhead by using
the new -fno -extern-tl s-i ni t option.
By default, g + + uses the -fextern-tl s-i ni t option.
C + + 11 At t rib u t e Syn t ax
g + + now implements the C++11 attribute syntax, for example:
​[[noreturn]] void f();
C + + 11 Alig n men t Sp ecif ier
g + + now implements the C++11 alignment specifier, for example:
​a lignas(double) int i;
3.1.1.1.5. Fo rt ran C h an g es
3.1.1.1.5.1. C aveat s
The version of module files (the . mo d files) has been incremented. Fortran modules compiled by
earlier GCC versions have to be recompiled when they are used by files compiled with GCC 4.8, as
this version of GCC is not able to read . mo d files created by earlier versions; attempting to do so
fails with an error message.
Note
The ABI of the produced assembler data itself has not changed; object files and libraries are
fully compatible with older versions except as noted in Section 3.1.1.1.5.2, “ ABI Compatibility” .
52
⁠Chapt er 3. Compiling and Building
3.1.1.1.5.2. AB I C o mp at ib ilit y
Some internal names used in the assembler or object file have changed for symbols declared in the
specification part of a module. If an affected module — or a file using it via use association — is
recompiled, the module and all files which directly use such symbols have to be recompiled as well.
This change only affects the following kind of module symbols:
Procedure pointers. Note that C-interoperable function pointers (type(c_funptr)) are not
affected, nor are procedure-pointer components.
Deferred-length character strings.
3.1.1.1.5.3. O t h er C h an g es
BACKTRACE Intrinsic
A new intrinsic subroutine, BAC KT R AC E, has been added. This subroutine shows a backtrace at an
arbitrary place in user code, program execution continues normally afterwards.
Floating Point Numbers with “ q” as Exponential
Reading floating point numbers that use q for the exponential (such as 4 . 0 q 0 ) is now supported as
a vendor extension for better compatibility with old data files. It is strongly recommended to use the
equivalent but standard conforming e (such as 4 . 0 e0 ) for I/O.
For Fortran source code, consider replacing the q in floating-point literals by a kind parameter (such
as 4 . 0 e0 _q p with a suitable q p). Note that — in Fortran source code — replacing q with a simple e
is not equivalent.
GFORTRAN_TMPD IR Environment Variable
The G FO R T R AN_T MP D IR environment variable for specifying a non-default directory for files
opened with ST AT US= "SC R AT C H", is not used anymore. Instead, g fo rtran checks the POSIX/GNU
standard T MP D IR environment variable and if T MP D IR is not defined, g fo rtran falls back to other
methods to determine the directory for temporary files as documented in the user manual.
Fortran 2003
Support for unlimited polymorphic variables (C LASS(*)) has been added. Non-constant character
lengths are not yet supported.
TS 29113
Assumed types (T Y P E(*)) are now supported.
Experimental support for assumed-rank arrays (d i mensi o n(. . )) has been added. Note that at the
moment, the g fo rtran array descriptor is used, which is different from the array descriptor defined in
TS 29113. For more information, see the header file of g fo rtran or use the C h asm language
interoperability tools.
3.1.1.1.6 . x86 - sp ecif ic Imp ro vemen t s
N ew In st ru ct io n s
GCC 4.8 has added support for the Intel FXSR , XSAVE, and XSAVEO P T instructions. Corresponding
intrinsics and built-in functions can now be enabled by using the -mfxsr, -mxsave, and mxsaveo pt command line options respectively.
53
Red Hat Ent erprise Linux 7 Developer G uide
In addition, support for the R D SEED , AD C X, AD O X, and P R EFET C HW instructions has been added
and can be enabled by using the -mrd seed , -mad x, and -mprfchw command line options.
N ew B u ilt - in Fu n ct io n s t o D et ect R u n - t ime C PU T yp e an d ISA
A new built-in function, __bui l ti n_cpu_i s(), has been added to detect if the run-time CPU is of a
particular type. This function accepts one string literal argument with the CPU name, and returns a
positive integer on a match and zero otherwise. For example, __bui l ti n_cpu_i s("westmere")
returns a positive integer if the run-time CPU is an Intel Core i7 Westmere processor. For a complete
list of valid CPU names, see the user manual.
A new built-in function, __bui l ti n_cpu_suppo rts(), has been added to detect if the run-time
CPU supports a particular ISA feature. This function accepts one string literal argument with the ISA
feature, and returns a positive integer on a match and zero otherwise. For example,
__bui l ti n_cpu_suppo rts("ssse3") returns a positive integer if the run-time CPU supports
SSSE3 instructions. For a complete list of valid ISA names, see the user manual.
Important
If these built-in functions are called before any static constructors are invoked, such as IFUNC
initialization, then the CPU detection initialization must be explicitly run using this newly
provided built-in function, __bui l ti n_cpu_i ni t(). The initialization needs to be done only
once. For example, the following is sample invocation inside an IFUNC initializer:
​static void (*some_ifunc_resolver(void))(void)
​
{
​
__builtin_cpu_init();
​
if (__builtin_cpu_is("amdfam10h") ...
​
if (__builtin_cpu_supports("popcnt") ...
​
}
Fu n ct io n Mu lt iversio n in g
Function multiversioning allows the programmer to specify multiple versions of the same function,
each of which is specialized for a particular variant of a given target. At runtime, the appropriate
version is automatically executed depending upon the target where the execution takes place. For
example, consider the following code fragment:
​_ _attribute__ ((target ("default"))) int foo () { return 0; }
​_ _attribute__ ((target ("sse4.2"))) int foo () { return 1; }
​_ _attribute__ ((target ("arch=atom"))) int foo () { return 2; }
When the function fo o () is executed, the result returned depends upon the architecture where the
program runs, not the architecture where the program was compiled. See the GCC Wiki for more
details.
N ew R T M an d H LE In t rin sics
Support for the Intel RTM and HLE intrinsics, built-in functions, and code generation has been added
and can be enabled by using the -mrtm and -mhl e command line options. This is done via
intrinsics for Restricted Transactional Memory (RTM) and extensions to the memory model for Hardware
Lock Elision (HLE).
54
⁠Chapt er 3. Compiling and Building
For HLE, two new flags can be used to mark a lock as using hardware elision:
__AT O MIC _H LE_AC Q U IR E
Starts lock elision on a lock variable. The memory model in use must be
__AT O MIC _AC Q UIR E or stronger.
__AT O MIC _H LE_R ELEASE
Ends lock elision on a lock variable. The memory model must be __AT O MIC _R ELEASE or
stronger.
For example, consider the following code fragment:
​w hile (__atomic_exchange_n (& lockvar, 1, __ATOMIC_ACQUIRE
​
| __ATOMIC_HLE_ACQUIRE))
​
_mm_pause ();
​/ / work with the acquired lock
​_ _atomic_clear (& lockvar, __ATOMIC_RELEASE | __ATOMIC_HLE_RELEASE);
The new intrinsics that support Restricted Transactional Memory are:
unsi g ned _xbeg i n (vo i d )
Attempts to start a transaction. If it succeeds, this function returns _XBEG IN_ST AR T ED ,
otherwise it returns a status value indicating why the transaction could not be started.
vo i d _xend (vo i d )
Commits the current transaction. When no transaction is active, this function causes a fault.
All memory side effects of the transactions become visible to other threads in an atomic
manner.
i nt _xtest (vo i d )
Returns a non-zero value if a transaction is currently active, or zero if it is not.
vo i d _xabo rt (unsi g ned char status)
Aborts the current transaction. When no transaction is active, this is a no-op. The
parameter status is included in the return value of any _xbeg i n() call that is aborted by
this function.
The following example illustrates the use of these intrinsics:
​i f ((status = _xbegin ()) == _XBEGIN_STARTED)
​
{
​
// some code
​
_xend ();
​}
​e lse
​
{
​
// examine the status to see why the transaction failed and possibly
retry
​
}
55
Red Hat Ent erprise Linux 7 Developer G uide
T ran sact io n s U sin g T ran sact io n al Syn ch ro n iz at io n Ext en sio n s
Transactions in the transactional memory feature (the -fg nu-tm option) of GCC can now be run
using Transactional Synchronization Extensions (TSX) if available on x86 hardware.
Su p p o rt f o r AMD Family 15h Pro cesso rs
The x86 backend of GCC now supports CPUs based on AMD Family 15h cores with the 64-bit x86
instruction set support. This can be enabled by using the -march= bd ver3 option.
Su p p o rt f o r AMD Family 16 h Pro cesso rs
The x86 backend of GCC now supports CPUs based on AMD Family 16h cores with the 64-bit x86
instruction set support. This can be enabled by using the -march= btver2 option.
3.1 .1 .2 . Change s Since Re d Hat Ent e rprise Linux 6 .4 and 5 .9
The following features have been added since the release of GCC included in Red Hat
Enterprise Linux 6.4 and 5.9:
3.1.1.2.1. St at u s an d Feat u res
3.1.1.2.1.1. C + + 11
GCC 4.7 and later provides experimental support for building applications compliant with C++11
using the -std = c+ + 11 or -std = g nu+ + 11 command line options. However, there is no guarantee
for compatibility between C++11 code compiled by different versions of the compiler. See
Section 3.1.1.2.3.1, “ C++ ABI” for details.
The C++ runtime library, l i bstd c+ + , supports a majority of the C++11 features. However, there is no
or only partial support for some features such as certain properties on type traits or regular
expressions. For details, see the l i bstd c+ + documentation, which also lists implementationdefined behavior.
Support for C++11 excepti o n_ptr and future requires changes to the exception handling runtime
in the system libstdc++ package. These changes will be distributed through the normal Z -stream
channel. Application of all Red Hat Enterprise Linux errata may be required to see correct runtime
functionality when using these features.
3.1.1.2.1.2. C 11
GCC 4.7 and later provides experimental support for some of the features from the C11 revision of the
ISO C standard, and in addition to the previous (now deprecated) -std = c1x and -std = g nu1x
command line options, gcc now accepts -std = c11 and -std = g nu11. Note that since this support
is experimental, it may change incompatibly in future releases.
Examples for features that are supported are Unicode strings (including the predefined macros
__ST D C _UT F_16 __ and __ST D C _UT F_32__), nonreturning functions (_No return and
<stdnoreturn.h>), and alignment support (_Al i g nas, _Al i g no f, max_al i g n_t, and
<stdalign.h>).
3.1.1.2.1.3. Parallelism an d C o n cu rren cy
G C C 4 .7 an d lat er provides improved support for programming parallel applications:
1. The GCC compilers support the OpenMP API specification for parallel programming, version
3.1. See the OpenMP website for more information about this specification.
56
⁠Chapt er 3. Compiling and Building
2. The C++11 and C11 standards provide programming abstractions for multi-threaded
programs. The respective standard libraries include programming abstractions for threads
and thread-related features such as locks, condition variables, or futures. These new
versions of the standard also define a memory model that precisely specifies the runtime
behavior of a multi-threaded program, such as the guarantees provided by compilers and the
constraints programmers have to pay attention to when writing multi-threaded programs.
Note that support for the memory model is still experimental (see below for details). For more
information about the status of support for C++11 and C11, see Section 3.1.1.2.1.1, “ C++11”
and Section 3.1.1.2.1.2, “ C11” respectively.
The rest of this section describes two new GCC features in more detail. Both these features make it
easier for programmers to handle concurrency (such as when multiple threads do not run truly in
parallel but instead have to synchronize concurrent access to shared state), and both provide
atomicity for access to memory but differ in their scope, applicability, and complexity of runtime
support.
C++11 Types and GCC Built-ins for Atomic Memory Access
C++11 has support for atomic types. Access to memory locations of this type is atomic, and appears
as one indivisible access even when other threads access the same memory location concurrently.
The atomicity is limited to a single read or write access or one of the other atomic operations
supported by such types (for example, two subsequent operations executed on a variable of atomic
type are each atomic separately, but do not form one joint atomic operation).
An atomic type is declared as ato mi c<T>, where T is the non-atomic base type and must be trivially
copyable (for example, ato mi c<i nt> is an atomic integer). GCC does not yet support any base type
T, but only those that can be accessed atomically with the atomic instructions offered by the target
architecture. This is not a significant limitation in practice, given that atomics are primarily designed
to expose hardware primitives in an architecture-independent fashion; pointers and integrals that are
not larger than a machine word on the target are supported as base types. Using base types that are
not yet supported results in link-time errors.
The code generated for operations on atomic types, including the memory orders, implements the
semantics specified in the C++11 standard. However, support for the C++11 memory model is still
experimental, and for example GCC might not always preserve data-race freedom when optimizing
code.
GCC also supports new built-ins for atomic memory accesses, which follow the design of the memory
model and new atomic operations. The former set of synchronization built-ins (that is, those prefixed
with __sync) are still supported.
Transactional Memory
Transactional Memory (TM) allows programs to declare that a piece of code is supposed to execute as
a transaction, that is, virtually atomically and in isolation from other transactions. GCC's
transactional memory runtime library, l i bi tm, then ensures this atomicity guarantee when executing
the compiled program. Compared to atomic memory accesses, it is a higher-level programming
abstraction, because it is not limited to single memory locations, does not require special data types
for the data it modifies, and because transactions can contain arbitrary code and be nested within
other transactions (with some restrictions explained subsequently).
GCC implements transactions as specified in the D raft Specification for Transactional Language
Constructs for C++, version 1.1. This draft does not yet specify the language constructs for C, but
GCC already supports a C-compatible subset of the constructs when compiling C source code.
57
Red Hat Ent erprise Linux 7 Developer G uide
The main language constructs are transaction statements and expressions, and are declared by the
__transacti o n_ato mi c or __transacti o n_rel axed keywords followed by a compound
statement or expression, respectively. The following example illustrates how to increment a global
variable y if another variable x has a value less than 10:
​_ _transaction_atomic { if (x < 10) y++; }
This happens atomically even in a multi-threaded execution of the program. In particular, even
though the transaction can load x and y and store to y, all these memory accesses are virtually
executed as one indivisible step.
Note that in line with the C++11 memory model, programs that use transactions must be free of data
races. Transactions are guaranteed to be virtually executed serially in a global total order that is
determined by the transactional memory implementation and that is consistent with and contributes
to the happens-before order enforced by the rest of the program (that is, transaction semantics are
specified based on the C++11 memory model, see the draft specification linked above). Nonetheless,
if a program is not data-race-free, then it has undefined behavior. For example, a thread can first
initialize some data and then make it publicly accessible by code like this:
​i nit(data);
​_ _transaction_atomic { data_public = true;}
false
// data_public is initially
Another thread can then safely use the data, for instance:
​_ _transaction_atomic { if (data_public) use(data); }
However, the following code has a data race and thus results in undefined behavior:
​_ _transaction_atomic { temp = copy(data); if (data_public) use(temp); }
Here, co py(d ata) races with i ni t(d ata) in the initializing thread, because this can be executed
even if d ata_publ i c is not true. Another example for data races is one thread accessing a variable
x transactionally and another thread accessing it nontransactionally at potentially the same time.
Note that the data can be safely reclaimed using code like this (assuming only one thread ever does
this):
​_ _transaction_atomic { data_public = false; }
​d estruct(data);
Here, d estruct() does not race with potential concurrent uses of the data because after the
transaction finishes, it is guaranteed that d ata_publ i c is false and thus data is private. See the
specification and the C++11 memory model for more background information about this.
Note that even if transactions are required to virtually execute in a total order, this does not mean that
they execute mutually exclusive in time. Transactional memory implementations attempt to run
transactions as much in parallel as possible to provide scalable performance.
There are two variants of transactions: atomic transactions (__transacti o n_ato mi c) and relaxed
transactions (__transacti o n_rel axed ). The former guarantee atomicity with regard to all other
code, but allow only code that is known to not include nontransactional kinds of synchronization,
such as atomic or volatile memory access. In contrast, relaxed transactions allow all code (for
example calls to I/O functions), but only provide atomicity with regard to other transactions.
58
⁠Chapt er 3. Compiling and Building
Therefore, atomic transactions can be nested within other atomic and relaxed transactions, but
relaxed transactions can only be nested within other relaxed transactions. Furthermore, relaxed
transactions are likely to be executed with less performance, but this depends on the implementation
and available hardware.
GCC verifies these restrictions statically at compile time (for example, the requirements on code
allowed to be called from within atomic transactions). This has implications for when transactions
call functions that are defined within other compilation unit (source file) or within libraries. To enable
such cross-compilation-unit calls for transactional code, the respective functions must be marked to
contain code that is safe to use from within atomic transactions. Programmers can do so by adding
the transacti o n_safe function attribute to the declarations of these functions and by including
this declaration when defining the function. In turn, GCC then verifies that the code in these functions
is safe for atomic transactions and generates code accordingly. If the programmer does not follow
these constraints and/or steps, compile-time or link-time errors occur. Note that within a compilation
unit, GCC detects automatically whether a function is safe for use within transactions, and the
attributes therefore typically do not need to be added. See the draft specification linked above for
further details.
GCC's transactional memory support is designed in such a way that it does not decrease the
performance of programs that do not use transactions, nor the performance of nontransactional
code, except due to the normal kinds of interference by concurrent threads that use the same
resources such as the CPU.
Transactional memory support in GCC and l i bi tm is still experimental, and both the ABI and API
could change in the future if this is required due to the evolution of the specification of the language
constructs, or due to implementation requirements. Note that when executing applications built with
the -fg nu-tm command line option, it is currently a prerequisite to also have the appropriate version
of the l i bi tm. so . 1 shared library installed.
3.1.1.2.1.4 . Arch it ect u re- sp ecif ic O p t io n s
Red Hat D eveloper Toolset 2.0 is only available for Red Hat Enterprise Linux 5 and 6, both for the
32-bit and 64-bit Intel and AMD architectures. Consequently, the options described below are only
relevant to these architectures.
Optimization for several processors is now available through the command line options described in
Table 3.5, “ Processor Optimization Options” .
T ab le 3.5. Pro cesso r O p t imiz at io n O p t io n s
O p t io n
D escrip t io n
-march= co re2 and -mtune= co re2
-march= co rei 7 and -mtune= co rei 7
Optimization for Intel Core 2 processors.
Optimization for Intel Core i3, i5, and i7
processors.
Optimization for Intel Core i3, i5, and i7
processors with AVX.
Optimization for the Intel processor code-named
Ivy Bridge with RD RND , FSGSBASE, and F16C.
Optimization for a next-generation processor
from Intel with AVX2, FMA, BMI, BMI2, and
LZ CNT.
Optimization for AMD Opteron processors codenamed Piledriver.
Optimization for AMD family 14 processors
code-named Bobcat.
-march= co rei 7-avx and -mtune= co rei 7avx
-march= co re-avx-i
-march= co re-avx2
-march= bd ver2 and -mtune= bd ver2
-march= btver1 and -mtune= btver1
59
Red Hat Ent erprise Linux 7 Developer G uide
O p t io n
D escrip t io n
-march= bd ver1 and -mtune= bd ver1
Optimization for AMD family 15h processors
code-named Bulldozer.
Support for various processor-specific intrinsics and instructions is now available through the
command line options described in Table 3.6, “ Support for Processor-specific Intrinsics and
Instructions” .
T ab le 3.6 . Su p p o rt f o r Pro cesso r- sp ecif ic In t rin sics an d In st ru ct io n s
O p t io n
D escrip t io n
Support for Intel AVX2 intrinsics, built-in functions, and code generation.
Support for Intel BMI2 intrinsics, built-in functions, and code generation.
Implementation and automatic generation of __bui l ti n_cl z* using
the l zcnt instruction.
-mfma
Support for Intel FMA3 intrinsics and code generation.
-mfsg sbase
Enables the generation of new segment register read/write instructions
through dedicated built-ins.
-mrd rnd
Support for the Intel rd rnd instruction.
-mf16 c
Support for two additional AVX vector conversion instructions.
-mtbm
Support for TBM (Trailing Bit Manipulation) built-in functions and code
generation.
-mbmi
Support for AMD 's BMI (Bit Manipulation) built-in functions and code
generation.
-mcrc32
Support for crc32 intrinsics.
-mmo vbe
Enables the use of the mo vbe instruction to implement
__bui l ti n_bswap32 and __bui l ti n_bswap6 4 .
-mxo p, -mfma4 , and - Support for the XOP, FMA4, and LWP instruction sets for the AMD Orochi
ml wp
processors.
-mabm
Enables the use of the po pcnt and l zcnt instructions on AMD
processors.
-mpo pcnt
Enables the use of the po pcnt instruction on both AMD and Intel
processors.
-mavx2
-mbmi 2
-ml zcnt
When using the x87 floating-point unit, GCC now generates code that conforms to ISO C99 in terms
of handling of floating-point excess precision. This can be enabled by -fexcesspreci si o n= stand ard and disabled by -fexcess-preci si o n= fast. This feature is enabled by
default when using standards conformance options such as -std = c9 9 .
Vectors of type vecto r l o ng l o ng or vecto r l o ng are passed and returned using the same
method as other vectors with the VSX instruction set. Previously GCC did not adhere to the ABI for
128-bit vectors with 64-bit integer base types (see GCC PR 48857).
The -mreci p command line option has been added, which indicates whether the reciprocal and
reciprocal square root instructions should be used.
The -mvecl i babi = mass command line option has been added. This can be used to enable the
compiler to auto-vectorize mathematical functions using the Mathematical Acceleration Subsystem
library.
The -msi ng l e-pi c-base command line option has been added, which instructs the compiler to
avoid loading the P IC base register in function prologues. The PIC base register must be initialized
by the runtime system.
The -mbl o ck-mo ve-i nl i ne-l i mi t command line option has been added, which enables the
60
⁠Chapt er 3. Compiling and Building
user to control the maximum size of inlined memcpy calls and similar.
3.1.1.2.1.5. Lin k- t ime O p t imiz at io n
Link-time optimization (LTO) is a compilation technique in which GCC generates an internal
representation of each compiled input file in addition to the native code, and writes both to the output
object file. Subsequently, when several object files are linked together, GCC uses the internal
representations of the compiled code to optimize inter-procedurally across all the compilation units.
This can potentially improve the performance of the generated code (for example, functions defined
in one file can potentially be inlined when called in another file).
To enable LTO, the -fl to option needs to be specified at both compile time and link time. For further
details, including interoperability with linkers and parallel execution of LTO, see the documentation
for -fl to in the GCC 4.7.0 Manual. Also note that the internal representation is not a stable interface,
so LTO will only apply to code generated by the same version of GCC.
Note
Use of Link-time Optimization with debug generation is not yet supported in gcc 4.7 and 4.8
and so use of the -fl to and the -g options together is unsupported in Red Hat D eveloper
Toolset.
3.1.1.2.1.6 . Miscellan eo u s
-O fast is now supported as a general optimization level. It operates similar to -O 3, adds options
that can yield better-optimized code, but in turn might invalidate standards compliance (for example,
-ffast-math is enabled by -O fast).
GCC can now inform users about cases in which code generation might be improved by adding
attributes such as co nst, pure, and no return to functions declared in header files. Use the Wsug g est-attri bute= [co nst| pure| no return] command line option to enable this.
Assembler code can now make use of a goto feature that allows for jumps to labels in C code.
3.1.1.2.2. Lan g u ag e C o mp at ib ilit y
In this section, we describe the compatibility between the Red Hat D eveloper Toolset compilers and
the Red Hat Enterprise Linux system compilers at the programming-language level (for example,
differences in the implementation of language standards such as C99, or changes to the warnings
generated by -Wal l ).
Some of the changes are a result of bug fixing, and some old behaviors have been intentionally
changed in order to support new standards, or relaxed in standards-conforming ways to facilitate
compilation or runtime performance. Some of these changes are not visible to the naked eye and will
not cause problems when updating from older versions. However, some of these changes are visible,
and can cause grief to users porting to Red Hat D eveloper Toolset's version of GCC. The following
text attempts to identify major issues and suggests solutions.
3.1.1.2.2.1. C
Constant expressions are now handled by GCC in a way that conforms to C90 and C99. For code
expressions that can be transformed into constants by the compiler but are in fact not constant
expressions as defined by ISO C, this may cause warnings or errors.
61
Red Hat Ent erprise Linux 7 Developer G uide
Ill-formed redeclarations of library functions are no longer accepted by the compiler. In particular, a
function with a signature similar to the built-in declaration of a library function (for example, abo rt()
or memcpy()) must be declared with extern "C " to be considered as a redeclaration, otherwise it is
ill-formed.
D uplicate Member
Consider the following struct declaration:
​struct A { int *a; union { struct { int *a; }; }; };
Previously, this declaration used to be diagnosed just by the C++ compiler, now it is also diagnosed
by the C compiler. Because of the anonymous unions and structs, there is ambiguity about what . a
actually refers to and one of the fields therefore needs to be renamed.
3.1.1.2.2.2. C + +
Header D ependency Changes
<i o stream>, <stri ng >, and other STL headers that previously included <uni std . h> as an
implementation detail (to get some feature macros for g thr*. h purposes) no longer do so, because
it was a C++ standard violation. This can result in diagnostic output similar to the following:
error: ‘truncate’ was not declared in this scope
error: ‘sleep’ was not declared in this scope
error: ‘pipe’ was not declared in this scope
error: there are no arguments to 'offsetof' that depend on a template
parameter, so a declaration of 'offsetof' must be available
To fix this, add the following line early in the source or header files that need it:
​# include <unistd.h>
Many of the standard C++ library include files have been edited to no longer include <cstd d ef> to
get namespace-std -scoped versions of si ze_t and ptrd i ff_t. As such, C++ programs that used
the macros NULL or o ffseto f without including <cstd d ef> will no longer compile. The diagnostic
produced is similar to the following:
error: 'ptrdiff_t' does not name a type
error: 'size_t' has not been declared
error: 'NULL' was not declared in this scope
error: there are no arguments to 'offsetof' that depend on a template
parameter, so a declaration of 'offsetof' must be available
To fix this issue, add the following line:
​# include <cstddef>
Name Lookup Changes
G++ no longer performs an extra unqualified lookup that it incorrectly performed in the past. Instead,
it implements the two-phase lookup rules correctly, and an unqualified name used in a template must
have an appropriate declaration that:
1. is either in scope at the point of the template's definition, or
62
⁠Chapt er 3. Compiling and Building
2. can be found by argument-dependent lookup at the point of instantiation.
Code that incorrectly depends on a second unqualified lookup at the point of instantiation (such as
finding functions declared after the template or in dependent bases) will result in compile-time errors.
In some cases, the diagnostics provided by G++ include hints how to fix the bugs. Consider the
following code:
​t emplate<typename T>
​i nt t(T i)
​
{
​
return f(i);
​
}
​i nt f(int i)
​
{
​
return i;
​
}
​i nt main()
​
{
​
return t(1);
​
}
The following diagnostics output will be produced:
In instantiation of ‘int t(T) [with T = int]’
required from here
error: ‘f’ was not declared in this scope, and no declarations were found
by argument-dependent lookup at the point of instantiation [-fpermissive]
note: ‘int f(int)’ declared here, later in the translation unit
To correct the error in this example, move the declaration of function f() before the definition of
template function t(). The -fpermi ssi ve compiler flag turns compile-time errors into warnings and
can be used as a temporary workaround.
Uninitialized const
Consider the following declaration:
​struct A { int a; A (); };
​struct B : public A { };
​c onst B b;
An attempt to compile this code now fails with the following error:
error: uninitialized const ‘b’ [-fpermissive]
note: ‘const struct B’ has no user-provided default constructor
This happens, because B does not have a user-provided default constructor. Either an initializer
needs to be provided, or the default constructor needs to be added.
Visibility of Template Instantiations
The ELF symbol visibility of a template instantiation is now properly constrained by the visibility of its
template arguments. For instance, users that instantiate standard library components like
63
Red Hat Ent erprise Linux 7 Developer G uide
std : : vecto r with hidden user defined types such as struct my_hi d d en_struct can now
expect hidden visibility for std : : vecto r<my_hi d d en_struct> symbols. As a result, users that
compile with the -fvi si bi l i ty= hi d d en command line option should be aware of the visibility of
types included from the library headers used. If the header does not explicitly control symbol
visibility, types from those headers will be hidden, along with instantiations that use those types. For
instance, consider the following code:
​# include <vector>
// template std::vector has default
visibility
​# include <ctime>
// struct tm has hidden visibility
​t emplate class std::vector<tm>; // instantiation has hidden visibility
One approach to adjusting the visibility of a library header <fo o . h> is to create a forwarding
header on the -I include path consisting of the following:
​# pragma GCC visibility push(default)
​# include_next <foo.h>
​# pragma GCC visibility push
User-defined Literal Support
When compiling C++ with the -std = {c+ + 11,c+ + 0 x,g nu+ + 11,g nu+ + 0 x} command line option,
GCC 4.7.0 and later, unlike older versions, supports user-defined literals, which are incompatible with
some valid ISO C++03 code. In particular, white space is now needed after a string literal before
something that could be a valid user defined literal. Consider the following code:
​c onst char *p = "foobar"__TIME__;
In C++03, the __T IME__ macro expands to some string literal and is concatenated with the other
one. In C++11, __T IME__ is not expanded and instead, operator "" __T IME__ is being looked up,
which results in a warning like:
error: unable to find string literal operator ‘operator"" __TIME__’
This applies to any string literal followed without white space by some macro. To fix this, add some
white space between the string literal and the macro name.
Taking the Address of Temporary
Consider the following code:
​struct S { S (); int i; };
​v oid bar (S *);
​v oid foo () { bar (& S ()); }
Previously, an attempt to compile this code produced a warning message, now it fails with an error.
This can be fixed by adding a variable and passing the address of this variable instead of the
temporary. The -fpermi ssi ve compiler flag turns compile-time errors into warnings and can be
used as a temporary workaround.
Miscellaneous
G++ now sets the predefined macro __cpl uspl us to the correct value: 19 9 711L for C++98/03, and
20 110 3L for C++11.
64
⁠Chapt er 3. Compiling and Building
G++ now properly re-uses stack space allocated for temporary objects when their lifetime ends, which
can significantly lower stack consumption for some C++ functions. As a result of this, some code with
undefined behavior will now break.
When an extern declaration within a function does not match a declaration in the enclosing context,
G++ now properly declares the name within the namespace of the function rather than the
namespace which was open just before the function definition.
G++ now implements the proposed resolution of the C++ standard's core issue 253. D efault
initialization is allowed if it initializes all subobjects, and code that fails to compile can be fixed by
providing an initializer such as:
​struct A { A(); };
​struct B : A { int i; };
​c onst B b = B();
Access control is now applied to typed ef names used in a template, which may cause G++ to reject
some ill-formed code that was accepted by earlier releases. The -fno -access-co ntro l option can
be used as a temporary workaround until the code is corrected.
G++ now implements the C++ standard's core issue 176. Previously, G++ did not support using the
injected-class-name of a template base class as a type name, and lookup of the name found the
declaration of the template in the enclosing scope. Now lookup of the name finds the injected-classname, which can be used either as a type or as a template, depending on whether or not the name is
followed by a template argument list. As a result of this change, some code that was previously
accepted may be ill-formed, because:
1. the injected-class-name is not accessible because it is from a private base, or
2. the injected-class-name cannot be used as an argument for a template parameter.
In either of these cases, the code can be fixed by adding a nested-name-specifier to explicitly name
the template. The first can be worked around with -fno -access-co ntro l , the second is only
rejected with -ped anti c.
3.1.1.2.2.3. C /C + + Warn in g s
GCC 4.7.0 and later adds a number of new warnings that are either enabled by default, or by using
the -Wal l option. Although these warnings do not result in a compilation failure on their own, often
-Wal l is used in conjunction with -Werro r, causing these warnings to act like errors. This section
provides a list of these new or newly enabled warnings. Unless noted otherwise, these warnings
apply to both C and C++.
The behavior of the -Wal l command line option has changed and now includes the new warning
flags -Wunused -but-set-vari abl e and, with -Wal l -Wextra, -Wunused -but-setparameter. This may result in new warnings in code that compiled cleanly with previous versions of
GCC. For example, consider the following code:
​v oid fn (void)
​
{
​
int foo;
​
foo = bar ();
​
}
/* foo is never used.
*/
The following diagnostic output will be produced:
warning: variable "foo" set but not used [-Wunused-but-set-variable]
65
Red Hat Ent erprise Linux 7 Developer G uide
To fix this issue, first see if the unused variable or parameter can be removed without changing the
result or logic of the surrounding code. If not, annotate it with __attri bute__((__unused __)). As
a workaround, you can use the -Wno -erro r= unused -but-set-vari abl e or -Wno erro r= unused -but-set-parameter command line option.
The -Wenum-co mpare option causes GCC to report a warning when values of different enum types
are being compared. Previously, this option only worked for C++ programs, but now it works for C as
well. This warning is enabled by -Wal l and may be avoided by using a type cast.
Casting integers to larger pointer types now causes GCC to display a warning by default. To disable
these warnings, use the -Wno -i nt-to -po i nter-cast option, which is available for both C and
C++.
Conversions between NULL and non-pointer types now cause GCC to report a warning by default.
Previously, these warnings were only displayed when explicitly using -Wco nversi o n. To disable
these warnings, use the new -Wno -co nversi o n-nul l command line option.
GCC can now warn when a class that has virtual functions and a non-virtual destructor is destroyed
by using d el ete. This is unsafe to do because the pointer might see a base class that does not
have a virtual destructor. The warning is enabled by -Wal l and by a new command line option, Wd el ete-no n-vi rtual -d to r.
New -Wc+ + 11-co mpat and -Wc+ + 0 x-co mpat options are now available. These options cause
GCC to display a warning about C++ constructs whose meaning differs between ISO C++ 1998 and
ISO C++ 2011 (such as identifiers in ISO C++ 1998 that are keywords in ISO C++ 2011). This
warning is enabled by -Wal l and enables the -Wnarro wi ng option.
3.1.1.2.2.4 . Fo rt ran
3.1.1.2.2.4 .1. N ew Feat u res
A new compile flag -fstack-arrays has been added. This flag causes all local arrays to be put
on stack memory, which can significantly improve the performance of some programs. Note that
programs that use very large local arrays may require you to extend your runtime limits for stack
memory.
Compile time has been significantly improved. For example, the improvement may be noticeable
when working with programs that use large array constructors.
To improve code generation and diagnostics, the -fwho l e-fi l e compile flag is now enabled
by default, and can be used with a newly supported -fwho l e-pro g ram flag. To disable it, use
the deprecated -fno -who l e-fi l e flag.
A new command line option -M is now supported. Similarly to g cc, this option allows you to
generate Makefile dependencies. Note that the -cpp option may be required as well.
The -fi ni t-real = command line option now supports snan as a valid value. This allows you
to initialize REAL and COMPLEX variables with a signaling NaN (not a number), and requires you
to enable trapping (for example, by using the -ffpe-trap= command line option). Note that
compile-time optimizations may turn a signaling NaN into a quiet NaN.
A new command line option -fcheck= has been added. This option accepts the following
arguments:
The -fcheck= bo und s option is equivalent to the -fbo und s-check command line option.
The -fcheck= array-temps option is equivalent to the -fcheck-array-tempo rari es
command line option.
66
⁠Chapt er 3. Compiling and Building
The -fcheck= d o option checks for invalid modification of loop iteration variables.
The -fcheck= recursi ve option checks for recursive calls to subroutines or functions that
are not marked as recursive.
The -fcheck= po i nter option performs pointer association checks in calls, but does not
handle undefined pointers nor pointers in expressions.
The -fcheck= al l option enables all of the above options.
A new command line option -fno -pro tect-parens has been added. This option allows the
compiler to reorder REAL and COMPLEX expressions with no regard to parentheses.
When OpenMP's WO R KSHAR E is used, array assignments and WHER E will now be run in parallel.
More Fortran 2003 and Fortran 2008 mathematical functions can now be used as initialization
expressions.
The G C C $ compiler directive now enables support for some extended attributes such as
ST D C ALL.
3.1.1.2.2.4 .2. C o mp at ib ilit y C h an g es
The -O fast command line option now automatically enables the -fno -pro tect-parens and fstack-arrays flags.
Front-end optimizations can now be disabled by the -fno -fro ntend -o pti mi ze option, and
selected by the -ffro ntend -o pti mi ze option. The former is essentially only desirable if invalid
Fortran source code needs to be compiled (for example, when functions—as compared to
subroutines—have side-effects) or to work around compiler bugs.
The G FO R T R AN_USE_ST D ER R environment variable has been removed, and GNU Fortran now
always prints error messages to standard error.
The -fd ump-co re command line option and the G FO R T R AN_ER R O R _D UMP C O R E environment
variable have been removed. When encountering a serious error, GNU Fortran now always aborts
the execution of the program.
The -fbacktrace command line option is now enabled by default. When a fatal error occurs,
GNU Fortran now attempts to print a backtrace to standard error before aborting the execution of
the program. To disable this behavior, use the -fno -backtrace option.
GNU Fortran no longer supports the use of the -M command line option to generate Makefile
dependencies for the module path. To perform this operation, use the -J option instead.
To significantly reduce the number of warnings, the -Wco nversi o n command line option now
only displays warnings when a conversion leads to information loss, and a new command line
option -Wco nversi o n-extra has been added to display warnings about other conversions.
The -Wco nversi o n option is now enabled with -Wal l .
A new command line option -Wunused -d ummy-arg ument has been added. This option can be
used to display warnings about unused dummy arguments, and is now enabled with -Wal l . Note
that the -Wunused -vari abl e option previously also warned about unused dummy arguments.
The C O MMO N default padding has been changed. Previously, the padding was added before a
variable. Now it is added after a variable to increase the compatibility with other vendors, as well
as to help to obtain the correct output in some cases. Note that this behavior is in contrast with the
behavior of the -fal i g n-co mmo ns option.
67
Red Hat Ent erprise Linux 7 Developer G uide
GNU Fortran no longer links against the l i bg fo rtranbeg i n library. The MAIN__ assembler
symbol is the actual Fortran main program and is invoked by the mai n function, which is now
generated and put in the same object file as MAIN__. Note that the l i bg fo rtranbeg i n library is
still present for backward compatibility.
3.1.1.2.2.4 .3. Fo rt ran 2003 Feat u res
Improved but still experimental support for polymorphism between libraries and programs and for
complicated inheritance patterns.
Generic interface names which have the same name as derived types are now supported, which
allows the creation of constructor functions. Note that Fortran does not support static constructor
functions; only default initialization or an explicit structure-constructor initialization are available.
Automatic (re)allocation: In intrinsic assignments to allocatable variables, the left-hand side will
be automatically allocated (if unallocated) or reallocated (if the shape or type parameter is
different). To avoid the small performance penalty, you can use a(: ) = . . . instead of a =
. . . for arrays and character strings — or disable the feature using -std = f9 5 or -fno real l o c-l hs.
Experimental support of the ASSO C IAT E construct has been added.
In pointer assignments it is now possible to specify the lower bounds of the pointer and, for a
rank-1 or a simply contiguous data-target, to remap the bounds.
D eferred type parameter: For scalar allocatable and pointer variables the character length can
now be deferred.
Namelist variables with allocatable attribute, pointer attribute, and with a non-constant length type
parameter are now supported.
Support has been added for procedure-pointer function results and procedure-pointer
components (including PASS).
Support has been added for allocatable scalars (experimental), D EFER R ED type-bound
procedures, and the ER R MSG = argument of the ALLO C AT E and D EALLO C AT E statements.
The ALLO C AT E statement now supports type-specs and the SO UR C E= argument.
Rounding (R O UND = , R Z, ...) for output is now supported.
The INT _FAST {8,16 ,32,6 4 ,128}_T format for ISO _C _BIND ING intrinsic module type
parameters is now supported.
O P ER AT O R (*) and ASSIG NMENT (= ) are now allowed as G ENER IC type-bound procedures (i.e.
as type-bound operators).
3.1.1.2.2.4 .4 . Fo rt ran 2003 C o mp at ib ilit y
Extensible derived types with type-bound procedure or procedure pointer with P ASS attribute now
have to use C LASS in line with the Fortran 2003 standard; the workaround to use T Y P E is no longer
supported.
3.1.1.2.2.4 .5. Fo rt ran 2008 Feat u res
A new command line option -std = f20 0 8ts has been added. This option enables support for
programs that conform to the Fortran 2008 standard and the draft Technical Specification (TS)
29113 on Further Interoperability of Fortran with C. For more information, see the Chart of Fortran
TS 29113 Features supported by GNU Fortran.
68
⁠Chapt er 3. Compiling and Building
The D O C O NC UR R ENT construct is now supported. This construct can be used to specify that
individual loop iterations do not have any interdependencies.
Full single-image support except for polymorphic coarrays has been added, and can be enabled
by using the -fco array= si ng l e command line option. Additionally, GNU Fortran now provides
preliminary support for multiple images via an MPI-based coarray communication library. Note
that the library version is not yet usable as remote coarray access is not yet possible.
The ST O P and ER R O R ST O P statements have been updated to support all constant expressions.
The C O NT IG UO US attribute is now supported.
Use of ALLO C AT E with the MO LD argument is now supported.
The ST O R AG E_SIZE intrinsic inquiry function is now supported.
The NO R M2 and P AR IT Y intrinsic functions are now supported.
The following bit intrinsics have been added:
the P O P C NT and P O P P AR bit intrinsics for counting the number of 1 bits and returning the
parity;
the BG E, BG T , BLE, and BLT bit intrinsics for bitwise comparisons;
the D SHIFT L and D SHIFT R bit intrinsics for combined left and right shifts;
the MASKL and MASKR bit intrinsics for simple left and right justified masks;
the MER G E_BIT S bit intrinsic for a bitwise merge using a mask;
the SHIFT A, SHIFT L, and SHIFT R bit intrinsics for shift operations;
the transformational bit intrinsics IALL, IANY , and IP AR IT Y .
The EXEC UT E_C O MMAND _LINE intrinsic subroutine is now supported.
The IMP UR E attribute for procedures is now supported. This allows the use of ELEMENT AL
procedures without the restrictions of P UR E.
Null pointers (including NULL()) and unallocated variables can now be used as an actual
argument to optional non-pointer, non-allocatable dummy arguments, denoting an absent
argument.
Non-pointer variables with the T AR G ET attribute can now be used as an actual argument to
P O INT ER dummies with INT ENT (IN).
Pointers that include procedure pointers and those in a derived type (pointer components) can
now also be initialized by a target instead of only by NULL.
The EXIT statement (with construct-name) can now be used to leave the ASSO C IAT E, BLO C K, IF,
SELEC T C ASE, and SELEC T T Y P E constructs in addition to D O .
Internal procedures can now be used as actual arguments.
The named constants INT EG ER _KIND S, LO G IC AL_KIND S, R EAL_KIND S, and
C HAR AC T ER _KIND S of the intrinsic module ISO _FO R T R AN_ENV have been added. These arrays
contain the supported 'kind' values for the respective types.
69
Red Hat Ent erprise Linux 7 Developer G uide
The C _SIZEO F module procedures of the ISO _C _BIND ING S intrinsic module and the
C O MP ILER _VER SIO N and C O MP ILER _O P T IO NS module procedures of the
ISO _FO R T R AN_ENV intrinsic module have been implemented.
The O P EN statement now supports the NEWUNIT = option. This option returns a unique file unit
and therefore prevents inadvertent use of the same unit in different parts of the program.
Unlimited format items are now supported.
The INT {8,16 ,32} and R EAL{32,6 4 ,128} format for ISO _FO R T R AN_ENV intrinsic module
type parameters are now supported.
It is now possible to use complex arguments with the T AN, SINH, C O SH, T ANH, ASIN, AC O S, and
AT AN functions. Additionally, the new functions ASINH, AC O SH, and AT ANH have been added for
real and complex arguments, and AT AN(Y ,X) now serves as an alias for AT AN2(Y ,X).
The BLO C K construct has been implemented.
3.1.1.2.2.4 .6 . Fo rt ran 2008 C o mp at ib ilit y
The implementation of the ASY NC HR O NO US attribute in GCC is now compatible with the candidate
draft of TS 29113: Technical Specification on Further Interoperability with C.
3.1.1.2.2.4 .7. Fo rt ran 77 C o mp at ib ilit y
When the GNU Fortran compiler is issued with the -fno -si g n-zero option, the SIG N intrinsic now
behaves as if zero were always positive.
3.1.1.2.3. AB I C o mp at ib ilit y
This section describes compatibility between the Red Hat D eveloper Toolset compilers and the
system compilers at the application binary interface (ABI) level.
3.1.1.2.3.1. C + + AB I
Because the upstream GCC community development does not guarantee C++11 ABI compatibility
across major versions of GCC, the same applies to use of C++11 with Red Hat D eveloper Toolset.
Consequently, using the -std = c+ + 11 option is supported in Red Hat D eveloper Toolset 2.0 only
when all C++ objects compiled with that flag have been built using the same major version of Red Hat
D eveloper Toolset. The mixing of objects, binaries and libraries, built by the Red Hat Enterprise Linux
5 or 6 system toolchain GCC using the -std = c+ + 0 x or -std = g nu+ + 0 x flags, with those built with
the -std = c+ + 11 or -std = g nu+ + 11 flags using the GCC in Red Hat D eveloper Toolset is explicitly
not supported.
As later major versions of Red Hat D eveloper Toolset may use a later major release of GCC, forwardcompatibility of objects, binaries, and libraries built with the -std = c+ + 11 or -std = g nu+ + 11
options cannot be guaranteed, and so is not supported.
The default language standard setting for Red Hat D eveloper Toolset is C++98. Any C++98compliant binaries or libraries built in this default mode (or explicitly with -std = c+ + 9 8) can be
freely mixed with binaries and shared libraries built by the Red Hat Enterprise Linux 5 or 6 system
toolchain GCC. Red Hat recommends use of this default -std = c+ + 9 8 mode for production software
development.
70
⁠Chapt er 3. Compiling and Building
Important
Use of C++11 features in your application requires careful consideration of the above ABI
compatibility information.
Aside from the C++11 ABI, discussed above, the Red Hat Enterprise Linux Application Compatibility
Specification is unchanged for Red Hat D eveloper Toolset. When mixing objects built with Red Hat
D eveloper Toolset with those built with the Red Hat Enterprise Linux v5.x/v6.x toolchain (particularly
.o/.a files), the Red Hat D eveloper Toolset toolchain should be used for any linkage. This ensures
any newer library features provided only by Red Hat D eveloper Toolset are resolved at link-time.
A new standard mangling for SIMD vector types has been added to avoid name clashes on systems
with vectors of varying length. By default the compiler still uses the old mangling, but emits aliases
with the new mangling on targets that support strong aliases. -Wabi will now display a warning
about code that uses the old mangling.
3.1.1.2.3.2. Miscellan eo u s
GCC now optimizes calls to various standard C string functions such as strl en(), strchr(),
strcpy(), strcat() and stpcpy() (as well as their respective _FO R T IFY _SO UR C E variants) by
transforming them into custom, faster code. This means that there might be fewer or other calls to
those functions than in the original source code. The optimization is enabled by default at -O 2 or
higher optimization levels. It is disabled when using -fno -o pti mi ze-strl en or when optimizing
for size.
When compiling for 32-bit GNU/Linux and not optimizing for size, -fo mi t-frame-po i nter is now
enabled by default. The prior default setting can be chosen by using the -fno -o mi t-framepo i nter command line option.
Floating-point calculations on x86 targets and in strict C99 mode are now compiled by GCC with a
stricter standard conformance. This might result in those calculations executing significantly slower.
It can be disabled using -fexcess-preci si o n= fast.
3.1.1.2.4 . D eb u g g in g C o mp at ib ilit y
GCC now generates D WARF debugging information that uses more or newer D WARF features than
previously. GD B contained in Red Hat D eveloper Toolset can handle these features, but versions of
GD B older than 7.0 cannot. GCC can be restricted to only generate debugging information with older
D WARF features by using the -g d warf-2 -g stri ct-d warf or -g d warf-3 -g stri ct-d warf
options (the latter are handled partially by versions of GD B older than 7.0).
Many tools such as Valg rin d , Syst emT ap , or third-party debuggers utilize debugging information.
It is suggested to use the -g d warf-2 -g stri ct-d warf options with those tools.
Note
Use of Link-time Optimization with debug generation is not yet supported in gcc 4.7 and 4.8
and so use of the -fl to and the -g options together is unsupported in Red Hat D eveloper
Toolset.
3.1.1.2.5. O t h er C o mp at ib ilit y
GCC is now more strict when parsing command line options, and both g cc and g + + report an error
71
Red Hat Ent erprise Linux 7 Developer G uide
when invalid command line options are used. In particular, when only linking and not compiling
code, earlier versions of GCC ignored all options starting with --. For example, options accepted by
the linker such as --as-need ed and --expo rt-d ynami c are not accepted by g cc and g + +
anymore, and should now be directed to the linker using -Wl ,--as-need ed or -Wl ,--expo rtd ynami c if that is intended.
Because of the new link-time optimization feature (see Section 3.1.1.2.1.5, “ Link-time Optimization” ),
support for the older intermodule optimization framework has been removed and the -co mbi ne
command line option is not accepted anymore.
3.2. Dist ribut ed Compiling
Red Hat Enterprise Linux also supports distributed compiling. This involves transforming one compile
job into many smaller jobs; these jobs are distributed over a cluster of machines, which speeds up
build time (particularly for programs with large codebases). The d i stcc package provides this
capability.
To set up distributed compiling, install the following packages:
d i stcc
d i stcc-server
For more information about distributed compiling, see the man pages for d i stcc and d i stccd . The
following link also provides detailed information about the development of d i stcc:
http://code.google.com/p/distcc
3.3. Aut ot ools
GNU Autotools is a suite of command line tools that allow developers to build applications on
different systems, regardless of the installed packages or even Linux distribution. These tools aid
developers in creating a co nfi g ure script. This script runs prior to builds and creates the top-level
Makefi l es required to build the application. The co nfi g ure script may perform tests on the
current system, create additional files, or run other directives as per parameters provided by the
builder.
The Autotools suite's most commonly-used tools are:
au t o co n f
Generates the co nfi g ure script from an input file (co nfi g ure. ac, for example)
au t o make
Creates the Makefi l e for a project on a specific system
au t o scan
Generates a preliminary input file (that is, co nfi g ure. scan), which can be edited to
create a final co nfi g ure. ac to be used by auto co nf
All tools in the Autotools suite are part of the D evel o pment T o o l s group package. You can install
this package group to install the entire Autotools suite, or use yum to install any tools in the suite as
you wish.
3.3.1. Configurat ion Script
72
⁠Chapt er 3. Compiling and Building
The most crucial function of Autotools is the creation of the co nfi g ure script. This script tests
systems for tools, input files, and other features it can use in order to build the project ⁠ [2] . The
co nfi g ure script generates a Makefi l e which allows the make tool to build the project based on
the system configuration.
To create the co nfi g ure script, first create an input file. Then feed it to an Autotools utility in order to
create the co nfi g ure script. This input file is typically co nfi g ure. ac or Makefi l e. am; the
former is usually processed by auto co nf, while the later is fed to auto make.
If a Makefi l e. am input file is available, the auto make utility creates a Makefi l e template (that is,
Makefi l e. i n), which may see information collected at configuration time. For example, the
Makefi l e may have to link to a particular library if and only if that library is already installed. When
the co nfi g ure script runs, auto make will use the Makefi l e. i n templates to create a
Makefi l e.
If a co nfi g ure. ac file is available instead, then auto co nf will automatically create the
co nfi g ure script based on the macros invoked by co nfi g ure. ac. To create a preliminary
co nfi g ure. ac, use the auto scan utility and edit the file accordingly.
3.3.2. Aut ot ools Document at ion
Red Hat Enterprise Linux includes man pages for auto co nf, auto make, auto scan and most tools
included in the Autotools suite. In addition, the Autotools community provides extensive
documentation on auto co nf and auto make on the following websites:
http://www.gnu.org/software/autoconf/manual/autoconf.html
http://www.gnu.org/software/autoconf/manual/automake.html
The following is an online book describing the use of Autotools. Although the above online
documentation is the recommended and most up to date information on Autotools, this book is a
good alternative and introduction.
http://sourceware.org/autobook/
For information on how to create Autotools input files, see:
http://www.gnu.org/software/autoconf/manual/autoconf.html#Making-configure-Scripts
http://www.gnu.org/software/autoconf/manual/automake.html#Invoking-Automake
The following upstream example also illustrates the use of Autotools in a simple hel l o program:
http://www.gnu.org/software/hello/manual/hello.html
3.4 . build-id Unique Ident ificat ion of Binaries
Each executable or shared library built with Red Hat Enterprise Linux Server 6 or later is assigned a
unique identification 160-bit SHA-1 string, generated as a checksum of selected parts of the binary.
This allows two builds of the same program on the same host to always produce consistent build-ids
and binary content.
D isplay the build-id of a binary with the following command:
$ eu-readelf -n usr/bin/bash
[...]
Note section [ 3] '.note.gnu.build-id' of 36 bytes at offset 0x274:
73
Red Hat Ent erprise Linux 7 Developer G uide
Owner
Data size
Type
GNU
20
GNU_BUILD_ID
Build ID: efdd0b5e69b0742fa5e5bad0771df4d1df2459d1
Unique identificators of binaries are useful in cases such as analysing core files, documented
Section 4.2.1, “ Installing D ebuginfo Packages for Core Files Analysis” .
3.5. Soft ware Collect ions and scl-ut ils
With Software Collections, it is possible to build and concurrently install multiple versions of the
same RPM packages on a system. Software Collections have no impact on the system versions of the
packages installed by the conventional RPM package manager.
To enable support for Software Collections on a system, install the packages scl-utils and by typing
the following at a shell prompt as ro o t:
~]# yum i nstal l scl -uti l s
The scl-utils package provides the scl tool, which is used to enable a Software Collection and to run
applications in the Software Collection environment.
General usage of the scl tool can be described using the following syntax:
scl action software_collection_1 software_collection_2 command
Examp le 3.1. R u n n in g an Ap p licat io n D irect ly
To directly run Perl with the --versi o n option in the Software Collection named
so f t ware_co llect io n _1, execute the following command:
scl enabl e so ftware_co l l ecti o n_1 ' perl --versi o n'
Examp le 3.2. R u n n in g a Sh ell wit h Mu lt ip le So f t ware C o llect io n s En ab led
To run the B ash shell in the environment with multiple Software Collections enabled, execute the
following command:
scl enabl e so ftware_co l l ecti o n_1 so ftware_co l l ecti o n_2 bash
The command above enables two Software Collections named so f t ware_co llect io n _1 and
so f t ware_co llect io n _2.
Examp le 3.3. R u n n in g C o mman d s St o red in a File
To execute a number of commands, which are stored in a file, in the Software Collections
environment, run the following command:
cat cmd | scl enabl e so ftware_co l l ecti o n_1 -
74
⁠Chapt er 3. Compiling and Building
The above command executes commands, which are stored in the cmd file, in the environment of
the Software Collection named so f t ware_co llect io n _1.
For more information regarding Software Collections and scl -uti l s, see the Red Hat
Software Collections 1.2 Packaging Guide.
[2] Fo r info rmatio n ab o ut tes ts that co nfi g ure c an p erfo rm, s ee the fo llo wing link:
http ://www.g nu.o rg /s o ftware/auto c o nf/manual/auto c o nf.html#Exis ting -Tes ts
75
Red Hat Ent erprise Linux 7 Developer G uide
Chapter 4. Debugging
Useful, well-written software generally goes through several different phases of application
development, allowing ample opportunity for mistakes to be made. Some phases come with their own
set of mechanisms to detect errors. For example, during compilation an elementary semantic analysis
is often performed to make sure objects, such as variables and functions, are adequately described.
The error-checking mechanisms performed during each application development phase aims to
catch simple and obvious mistakes in code. The debugging phase helps to bring more subtle errors
to light that fell through the cracks during routine code inspection.
4 .1. ELF Execut able Binaries
Red Hat Enterprise Linux uses ELF for executable binaries, shared libraries, or debuginfo files. Within
these debuginfo ELF files, the D WARF format is used. Version 3 of D WARF is used in ELF files (that is,
g cc -g is equivalent to g cc -g d warf-3). D WARF debuginfo includes:
names of all the compiled functions and variables, including their target addresses in binaries
source files used for compilation, including their source line numbers
local variables location
Important
STABS is occasionally used with UNIX. STABS is an older, less capable format. Its use is
discouraged by Red Hat. GCC and GD B support STABS production and consumption on a
best effort basis only.
Within these ELF files, the GCC debuginfo level is also used. The default is level 2, where macro
information is not present; level 3 has C/C++ macro definitions included, but the debuginfo can be
very large with this setting. The command for the default g cc -g is the same as g cc -g 2. To
change the macro information to level three, use g cc -g 3.
There are multiple levels of debuginfo available. Use the command read el f -WS file to see
which sections are used in a file.
T ab le 4 .1. d eb u g in f o levels
B in ary St at e
C o mman d
N o t es
Stripped
stri p file
or
Only the symbols required for
runtime linkage with shared
libraries are present.
g cc -s -o file
ELF section in use: . d ynsym
g cc -o file
Only the names of functions
and variables are present, no
binding to the source files and
no types.
ELF symbols
ELF section in use: . symtab
76
⁠Chapt er 4 . Debugging
B in ary St at e
C o mman d
N o t es
D WARF debuginfo with macros
g cc -g -o file
The source file names and line
numbers are known, including
types.
ELF section in use: . d ebug _*
D WARF debuginfo with macros
g cc -g 3 -o file
Similar to g cc -g but the
macros are known to GD B.
ELF section in use:
. d ebug _macro
Note
GD B never interprets the source files, it only displays them as text. Use g cc -g and its
variants to store the information into D WARF.
Compiling a program or library with g cc -rd ynami c is discouraged. For specific symbols, use g cc
-Wl , --d ynami c-l i st= . . . instead. If g cc -rd ynami c is used, the stri p command or -s gcc
option have no effect. This is because all ELF symbols are kept in the binary for possible runtime
linkage with shared libraries.
ELF symbols can be read by the read el f -s file command.
D WARF symbols are read by the read el f -w file command.
The command read el f -wi file is a good verification of debuginfo, compiled within your
program. The commands stri p file or g cc -s are commonly accidentally executed on the output
during various compilation stages of the program.
The read el f -w file command can also be used to show a special section called . eh_frame
with a format and purpose is similar to the D WARF section . d ebug _frame. The . eh_frame section
is used for runtime C++ exception resolution and is present even if -g gcc option was not used. It is
kept in the primary RPM and is never present in the debuginfo RPMs.
D ebuginfo RPMs contain the sections . symtab and . d ebug _*. Neither . eh_frame,
. eh_frame_hd r, nor . d ynsym are moved or present in debuginfo RPMs as those sections are
needed during program runtime.
4 .2. Inst alling Debuginfo Packages
Red Hat Enterprise Linux also provides -d ebug i nfo packages for all architecture-dependent RPMs
included in the operating system. A packagenamed ebug i nfo -version-release. architecture. rpm package contains detailed information
about the relationship of the package source files and the final installed binary. The debuginfo
packages contain both . d ebug files, which in turn contain D WARF debuginfo and the source files
used for compiling the binary packages.
77
Red Hat Ent erprise Linux 7 Developer G uide
Note
Most of the debugger functionality is missed if attempting to debug a package without having
its debuginfo equivalent installed. For example, the names of exported shared library
functions will still be available, but the matching source file lines will not be without the
debuginfo package installed.
Use g cc compilation option -g for your own programs. The debugging experience is better if no
optimizations (gcc option -O , such as -O 2) is applied with -g .
For Red Hat Enterprise Linux 6, the debuginfo packages are now available on a new channel on the
Red Hat Network. To install the -d ebug i nfo package of a package (that is, typically
packagename-d ebug i nfo ), first the machine has to be subscribed to the corresponding
D ebuginfo channel. For example, for Red Hat Enterprise Server 6, the corresponding channel would
be R ed Hat Enterpri se Li nux Server D ebug i nfo (v. 6 ).
Red Hat Enterprise Linux system packages are compiled with optimizations (gcc option -O 2). This
means that some variables will be displayed as <o pti mi zed o ut>. Stepping through code will
'jump' a little but a crash can still be analyzed. If some debugging information is missing because of
the optimizations, the right variable information can be found by disassembling the code and
matching it to the source manually. This is applicable only in exceptional cases and is not suitable
for regular debugging.
For system packages, GD B informs the user if it is missing some debuginfo packages that limit its
functionality.
gdb ls
[...]
Reading symbols from /usr/bin/ls...(no debugging symbols found)...done.
Missing separate debuginfos, use: debuginfo-install coreutils-8.416.el6.x86_64
(gdb) q
If the system package to be debugged is known, use the command suggested by GD B above. It will
also automatically install all the debug packages packagename depends on.
# debuginfo-install packagename
4 .2.1. Inst alling Debuginfo Packages for Core Files Analysis
A core file is a representation of the memory image at the time of a process crash. For bug reporting
of system program crashes, Red Hat recommends the use of the ABRT tool, explained in the Automatic
Bug Reporting Tool chapter in the Red Hat Deployment Guide. If ABRT is not suitable for your purposes,
the steps it automates are explained here.
If the ul i mi t -c unl i mi ted setting is in use when a process crashes, the core file is dumped into
the current directory. The core file contains only the memory areas modified by the process from the
original state of disk files. In order to perform a full analysis of a crash, a core file is required to have:
the core file itself
the executable binary which has crashed, such as /usr/sbi n/send mai l
all the shared libraries loaded in the binary when it crashed
78
⁠Chapt er 4 . Debugging
.debug files and source files (both stored in debuginfo RPMs) for the executable and all of its
loaded libraries
For a proper analysis, either the exact version-release.architecture for all the RPMs
involved or the same build of your own compiled binaries is needed. At the time of the crash, the
application may have already recompiled or been updated by yum on the disk, rendering the files
inappropriate for the core file analysis.
The core file contains build-ids of all the binaries involved. For more information on build-id, see
Section 3.4, “ build-id Unique Identification of Binaries” . The contents of the core file can be
displayed by:
$ eu-unstrip -n --core=./core.9814
0x400000+0x207000 2818b2009547f780a5639c904cded443e564973e@ 0x400284
usr/bin/sleep /usr/lib/debug/bin/sleep.debug [exe]
0x7fff26fff000+0x1000
1e2a683b7d877576970e4275d41a6aaec280795e@ 0x7fff26fff340 . - linux-vdso.so.1
0x35e7e00000+0x3b6000
374add1ead31ccb449779bc7ee7877de3377e5ad@ 0x35e7e00280 /usr/lib64/libc2.14.90.so /usr/lib/debug/lib64/libc-2.14.90.so.debug libc.so.6
0x35e7a00000+0x224000
3ed9e61c2b7e707ce244816335776afa2ad0307d@ 0x35e7a001d8 /usr/lib64/ld2.14.90.so /usr/lib/debug/lib64/ld-2.14.90.so.debug ld-linux-x86-64.so.2
The meaning of the columns in each line are:
The in-memory address where the specific binary was mapped to (for example, 0 x4 0 0 0 0 0 in the
first line).
The size of the binary (for example, + 0 x20 70 0 0 in the first line).
The 160-bit SHA-1 build-id of the binary (for example,
2818b20 0 9 54 7f780 a56 39 c9 0 4 cd ed 4 4 3e56 4 9 73e in the first line).
The in-memory address where the build-id bytes were stored (for example, @ 0 x4 0 0 284 in the first
line).
The on-disk binary file, if available (for example, usr/bi n/sl eep in the first line). This was
found by eu-unstri p for this module.
The on-disk debuginfo file, if available (for example, /usr/l i b/d ebug /bi n/sl eep. d ebug ).
However, best practice is to use the binary file reference instead.
The shared library name as stored in the shared library list in the core file (for example,
l i bc. so . 6 in the third line).
For each build-id (for example, ab/cd ef0 1234 56 789 0 1234 56 789 0 1234 56 789 0 123) a symbolic
link is included in its debuginfo RPM. Using the /usr/bi n/sl eep executable above as an example,
the co reuti l s-d ebug i nfo RPM contains, among other files:
lrwxrwxrwx 1 root root 24 Nov 29 17:07 /usr/lib/debug/.buildid/28/18b2009547f780a5639c904cded443e564973e -> ../../../../../bin/sleep*
lrwxrwxrwx 1 root root 21 Nov 29 17:07 /usr/lib/debug/.buildid/28/18b2009547f780a5639c904cded443e564973e.debug ->
../../bin/sleep.debug
In some cases (such as loading a core file), GD B does not know the name, version, or release of a
name-d ebug i nfo -version-release. rpm package; it only knows the build-id. In such cases,
79
Red Hat Ent erprise Linux 7 Developer G uide
GD B suggests a different command:
gdb -c ./core
[...]
Missing separate debuginfo for the main executable filename
Try: yum --disablerepo='*' --enablerepo='*debug*' install
/usr/lib/debug/.build-id/ef/dd0b5e69b0742fa5e5bad0771df4d1df2459d1
The version-release.architecture of the binary package packagename-debuginfo-versionrelease.architecture.rpm must be an exact match. If it differs then GD B cannot use the debuginfo
package. Even the same version-release.architecture from a different build leads to an incompatible
debuginfo package. If GD B reports a missing debuginfo, ensure to recheck:
rpm -q packagename packagename-d ebug i nfo
The version-release.architecture definitions should match.
rpm -V packagename packagename-d ebug i nfo
This command should produce no output, except possibly modified configuration files of
packagename, for example.
rpm -q i packagename packagename-d ebug i nfo
The version-release.architecture should display matching information for Vendor, Build D ate,
and Build Host. For example, using a CentOS debuginfo RPM for a Red Hat
Enterprise Linux RPM package will not work.
If the required build-id is known, the following command can query which RPM contains it:
$ repoquery --disablerepo='*' --enablerepo='*-debug*' -qf
/usr/lib/debug/.build-id/ef/dd0b5e69b0742fa5e5bad0771df4d1df2459d1
For example, a version of an executable which matches the core file can be installed by:
# yum --enablerepo='*-debug*' install $(eu-unstrip -n --core=./core.9814
| sed -e 's#^[^ ]* \(..\)\([^@ ]*\).*$#/usr/lib/debug/.build-id/\1/\2#p'
-e 's/$/.debug/')
Similar methods are available if the binaries are not packaged into RPMs and stored in yum
repositories. It is possible to create local repositories with custom application builds by using
/usr/bi n/createrepo .
4 .3. GDB
Fundamentally, like most debuggers, GD B manages the execution of compiled code in a very closely
controlled environment. This environment makes possible the following fundamental mechanisms
necessary to the operation of GD B:
Inspect and modify memory within the code being debugged (for example, reading and setting
variables).
Control the execution state of the code being debugged, principally whether it's running or
stopped.
80
⁠Chapt er 4 . Debugging
D etect the execution of particular sections of code (for example, stop running code when it
reaches a specified area of interest to the programmer).
D etect access to particular areas of memory (for example, stop running code when it accesses a
specified variable).
Execute portions of code (from an otherwise stopped program) in a controlled manner.
D etect various programmatic asynchronous events such as signals.
The operation of these mechanisms rely mostly on information produced by a compiler. For example,
to view the value of a variable, GD B has to know:
The location of the variable in memory
The nature of the variable
This means that displaying a double-precision floating point value requires a very different process
from displaying a string of characters. For something complex like a structure, GD B has to know not
only the characteristics of each individual elements in the structure, but the morphology of the
structure as well.
GD B requires the following items in order to fully function:
D eb u g In f o rmat io n
Much of GD B's operations rely on a program's debug information. While this information
generally comes from compilers, much of it is necessary only while debugging a program,
that is, it is not used during the program's normal execution. For this reason, compilers do
not always make that information available by default — GCC, for instance, must be
explicitly instructed to provide this debugging information with the -g flag.
To make full use of GD B's capabilities, it is highly advisable to make the debug information
available first to GD B. GD B can only be of very limited use when run against code with no
available debug information.
So u rce C o d e
One of the most useful features of GD B (or any other debugger) is the ability to associate
events and circumstances in program execution with their corresponding location in source
code. This location normally refers to a specific line or series of lines in a source file. This,
of course, would require that a program's source code be available to GD B at debug time.
4 .3.1. Simple GDB
GD B literally contains dozens of commands. This section describes the most fundamental ones.
br ( b reakp o in t )
The breakpoint command instructs GD B to halt execution upon reaching a specified point
in the execution. That point can be specified a number of ways, but the most common are
just as the line number in the source file, or the name of a function. Any number of
breakpoints can be in effect simultaneously. This is frequently the first command issued
after starting GD B.
r ( ru n )
The run command starts the execution of the program. If run is executed with any
arguments, those arguments are passed on to the executable as if the program has been
started normally. Users normally issue this command after setting breakpoints.
81
Red Hat Ent erprise Linux 7 Developer G uide
Before an executable is started, or once the executable stops at, for example, a breakpoint, the state
of many aspects of the program can be inspected. The following commands are a few of the more
common ways things can be examined.
p ( p rin t )
The pri nt command displays the value of the argument given, and that argument can be
almost anything relevant to the program. Usually, the argument is the name of a variable of
any complexity, from a simple single value to a structure. An argument can also be an
expression valid in the current language, including the use of program variables and
library functions, or functions defined in the program being tested.
bt ( b ackt race)
The backtrace displays the chain of function calls used up until the execution was
terminated. This is useful for investigating serious bugs (such as segmentation faults) with
elusive causes.
l ( list )
When execution is stopped, the l i st command shows the line in the source code
corresponding to where the program stopped.
The execution of a stopped program can be resumed in a number of ways. The following are the most
common.
c ( co n t in u e)
The co nti nue command restarts the execution of the program, which will continue to
execute until it encounters a breakpoint, runs into a specified or emergent condition (for
example, an error), or terminates.
n ( n ext )
Like co nti nue, the next command also restarts execution; however, in addition to the
stopping conditions implicit in the co nti nue command, next will also halt execution at the
next sequential line of code in the current source file.
s ( st ep )
Like next, the step command also halts execution at each sequential line of code in the
current source file. However, if execution is currently stopped at a source line containing a
function call, GD B stops execution after entering the function call (rather than executing it).
fi ni ( f in ish )
Like the aforementioned commands, the fi ni sh command resumes executions, but halts
when execution returns from a function.
Finally, two essential commands:
q ( q u it )
This terminates the execution.
h ( h elp )
82
⁠Chapt er 4 . Debugging
The hel p command provides access to its extensive internal documentation. The
command takes arguments: hel p breakpo i nt (or h br), for example, shows a detailed
description of the breakpo i nt command. See the hel p output of each command for more
detailed information.
4 .3.2. Running GDB
This section will describe a basic execution of GD B, using the following simple program:
h ello .c
#include <stdio.h>
char hello[] = { "Hello, World!" };
int
main()
{
fprintf (stdout, "%s\n", hello);
return (0);
}
The following procedure illustrates the debugging process in its most basic form.
Pro ced u re 4 .1. D eb u g g in g a ' H ello Wo rld ' Pro g ram
1. Compile hello.c into an executable with the debug flag set, as in:
g cc -g -o hel l o hel l o . c
Ensure that the resulting binary hel l o is in the same directory as hel l o . c.
2. Run g d b on the hel l o binary, that is, g d b hel l o .
3. After several introductory comments, g d b will display the default GD B prompt:
(gdb)
4. The variable hel l o is global, so it can be seen even before the mai n procedure starts:
gdb) p hello
$1 = "Hello, World!"
(gdb) p hello[0]
$2 = 72 'H'
(gdb) p *hello
$3 = 72 'H'
(gdb)
Note that the pri nt targets hel l o [0 ] and *hel l o require the evaluation of an expression,
as does, for example, *(hel l o + 1):
(gdb) p *(hello + 1)
$4 = 101 'e'
5. Next, list the source:
83
Red Hat Ent erprise Linux 7 Developer G uide
(gdb) l
1
#include <stdio.h>
2
3
char hello[] = { "Hello, World!" };
4
5
int
6
main()
7
{
8
fprintf (stdout, "%s\n", hello);
9
return (0);
10
}
The l i st reveals that the fpri ntf call is on line 8. Apply a breakpoint on that line and
resume the code:
(gdb) br 8
Breakpoint 1 at 0x80483ed: file hello.c, line 8.
(gdb) r
Starting program: /home/moller/tinkering/gdb-manual/hello
Breakpoint 1, main () at hello.c:8
8
fprintf (stdout, "%s\n", hello);
6. Finally, use the next command to step past the fpri ntf call, executing it:
(gdb) n
Hello, World!
9
return (0);
The following sections describe more complex applications of GD B.
4 .3.3. Condit ional Breakpoint s
In many real-world cases, a program may perform its task well during the first few thousand times; it
may then start crashing or encountering errors during its eight thousandth iteration of the task.
D ebugging programs like this can be difficult, as it is hard to imagine a programmer with the patience
to issue a co nti nue command thousands of times just to get to the iteration that crashed.
Situations like this are common in real life, which is why GD B allows programmers to attach
conditions to a breakpoint. For example, consider the following program:
simp le.c
#include <stdio.h>
main()
{
int i;
for (i = 0;; i++) {
fprintf (stdout, "i = %d\n", i);
}
}
84
⁠Chapt er 4 . Debugging
To set a conditional breakpoint at the GD B prompt:
(gdb) br 8 if i == 8936
Breakpoint 1 at 0x80483f5: file iterations.c, line 8.
(gdb) r
With this condition, the program execution will eventually stop with the following output:
i
i
i
i
i
=
=
=
=
=
8931
8932
8933
8934
8935
Breakpoint 1, main () at iterations.c:8
8
fprintf (stdout, "i = %d\n", i);
Inspect the breakpoint information (using i nfo br) to review the breakpoint status:
(gdb) info br
Num
Type
Disp Enb Address
What
1
breakpoint
keep y
0x080483f5 in main at iterations.c:8
stop only if i == 8936
breakpoint already hit 1 time
4 .3.4 . Forked Execut ion
Among the more challenging bugs confronting programmers is where one program (the parent)
makes an independent copy of itself (a fork). That fork then creates a child process which, in turn,
fails. D ebugging the parent process may or may not be useful. Often the only way to get to the bug
may be by debugging the child process, but this is not always possible.
The set fo l l o w-fo rk-mo d e feature is used to overcome this barrier allowing programmers to
follow a a child process instead of the parent process.
set fo l l o w-fo rk-mo d e parent
The original process is debugged after a fork. The child process runs unimpeded. This is
the default.
set fo l l o w-fo rk-mo d e chi l d
The new process is debugged after a fork. The parent process runs unimpeded.
sho w fo l l o w-fo rk-mo d e
D isplay the current debugger response to a fork call.
Use the set d etach-o n-fo rk command to debug both the parent and the child processes after a
fork, or retain debugger control over them both.
set d etach-o n-fo rk o n
The child process (or parent process, depending on the value of fo l l o w-fo rk-mo d e)
will be detached and allowed to run independently. This is the default.
set d etach-o n-fo rk o ff
85
Red Hat Ent erprise Linux 7 Developer G uide
Both processes will be held under the control of GD B. One process (child or parent,
depending on the value of fo l l o w-fo rk-mo d e) is debugged as usual, while the other is
suspended.
sho w d etach-o n-fo rk
Show whether d etach-o n-fo rk mode is on or off.
Consider the following program:
f o rk.c
​# include <unistd.h>
​i nt main()
​
{
​ pid_t pid;
​ const char *name;
​
pid = fork();
if (pid == 0)
{
name = "I am the child";
}
else
{
name = "I am the parent";
}
return 0;
​
​
​
​
​
​
​
​
​
​}
This program, compiled with the command g cc -g fo rk. c -o fo rk -l pthread and examined
under GD B will show:
​g db ./fork
​[...]
​( gdb) break main
​B reakpoint 1 at 0x4005dc: file fork.c, line 8.
​( gdb) run
​[...]
​B reakpoint 1, main () at fork.c:8
​8
pid = fork();
​( gdb) next
​D etaching after fork from child process 3840.
​9
if (pid == 0)
​( gdb) next
​15
name = "I am the parent";
​( gdb) next
​17
return 0;
​( gdb) print name
​$ 1 = 0x400717 "I am the parent"
GD B followed the parent process and allowed the child process (process 3840) to continue
execution.
The following is the same test using set fo l l o w-fo rk-mo d e chi l d .
86
⁠Chapt er 4 . Debugging
​( gdb) set follow-fork-mode child
​( gdb) break main
​B reakpoint 1 at 0x4005dc: file fork.c, line 8.
​( gdb) run
​[...]
​B reakpoint 1, main () at fork.c:8
​8
pid = fork();
​( gdb) next
​[New process 3875]
​[Thread debugging using libthread_db enabled]
​[Switching to Thread 0x7ffff7fd5720 (LWP 3875)]
​9
if (pid == 0)
​( gdb) next
​11
name = "I am the child";
​( gdb) next
​17
return 0;
​( gdb) print name
​$ 2 = 0x400708 "I am the child"
​( gdb)
GD B switched to the child process here.
This can be permanent by adding the setting to the appropriate . g d bi ni t.
For example, if set fo l l o w-fo rk-mo d e ask is added to ~ /. g d bi ni t, then ask mode becomes
the default mode.
4 .3.5. Debugging Individual T hreads
GD B has the ability to debug individual threads, and to manipulate and examine them
independently. This functionality is not enabled by default. To do so use set no n-sto p o n and
set targ et-async o n. These can be added to . g d bi ni t. Once that functionality is turned on,
GD B is ready to conduct thread debugging.
For example, the following program creates two threads. These two threads, along with the original
thread executing main makes a total of three threads.
t h ree- t h read s.c
​# include <stdio.h>
​# include <pthread.h>
​# include <unistd.h>
​p thread_t thread;
​v oid* thread3 (void* d)
​
{
​ int count3 = 0;
​
while(count3 < 1000){
sleep(10);
printf("Thread 3: %d\n", count3++);
}
return NULL;
​
​
​
​
​}
87
Red Hat Ent erprise Linux 7 Developer G uide
​v oid* thread2 (void* d)
​
{
​ int count2 = 0;
​
while(count2 < 1000){
printf("Thread 2: %d\n", count2++);
}
return NULL;
​
​
​
​}
​i nt main (){
​
pthread_create (& thread, NULL, thread2, NULL);
pthread_create (& thread, NULL, thread3, NULL);
​
​
​
//Thread 1
int count1 = 0;
​
​
while(count1 < 1000){
printf("Thread 1: %d\n", count1++);
}
​
​
​
pthread_join(thread,NULL);
return 0;
​
​}
Compile this program in order to examine it under GD B.
​g cc -g three-threads.c -o three-threads
​g db ./three-threads
-lpthread
First set breakpoints on all thread functions; thread1, thread2, and main.
​( gdb) break thread3
​B reakpoint 1 at 0x4006c0: file three-threads.c, line 9.
​( gdb) break thread2
​B reakpoint 2 at 0x40070c: file three-threads.c, line 20.
​( gdb) break main
​B reakpoint 3 at 0x40074a: file three-threads.c, line 30.
Then run the program.
​( gdb) run
​[...]
​B reakpoint 3, main () at three-threads.c:30
​3 0
pthread_create (& thread, NULL, thread2, NULL);
​[...]
​( gdb) info threads
​* 1 Thread 0x7ffff7fd5720 (LWP 4620) main () at three-threads.c:30
​( gdb)
Note that the command i nfo thread s provides a summary of the program's threads and some
details about their current state. In this case there is only one thread that has been created so far.
88
⁠Chapt er 4 . Debugging
Continue execution some more.
​( gdb) next
​[New Thread 0x7ffff7fd3710 (LWP 4687)]
​3 1
pthread_create (& thread, NULL, thread3, NULL);
​( gdb)
​B reakpoint 2, thread2 (d=0x0) at three-threads.c:20
​2 0
int count2 = 0;
​n ext
​[New Thread 0x7ffff75d2710 (LWP 4688)]
​3 4
int count1 = 0;
​( gdb)
​B reakpoint 1, thread3 (d=0x0) at three-threads.c:9
​9
int count3 = 0;
​i nfo threads
​ 3 Thread 0x7ffff75d2710 (LWP 4688) thread3 (d=0x0) at threethreads.c:9
​ 2 Thread 0x7ffff7fd3710 (LWP 4687) thread2 (d=0x0) at threethreads.c:20
​* 1 Thread 0x7ffff7fd5720 (LWP 4620) main () at three-threads.c:34
Here, two more threads are created. The star indicates the thread currently under focus. Also, the
newly created threads have hit the breakpoint set for them in their initialization functions. Namely,
thread2() and thread3().
To begin real thread debugging, use the thread <thread number> command to switch the focus
to another thread.
​( gdb) thread 2
​[Switching to thread 2 (Thread 0x7ffff7fd3710 (LWP 4687))]#0
(d=0x0)
​
at three-threads.c:20
​2 0
int count2 = 0;
​( gdb) list
​15
return NULL;
​16 }
​17
​18 void* thread2 (void* d)
​19 {
​2 0
int count2 = 0;
​2 1
​2 2
while(count2 < 1000){
​2 3
printf("Thread 2: %d\n", count2++);
​2 4
}
thread2
Thread 2 stopped at line 20 in its function thread2().
​( gdb) next
​2 2
while(count2 < 1000){
​( gdb) print count2
​$ 1 = 0
​( gdb) next
​2 3
printf("Thread 2: %d\n", count2++);
​( gdb) next
89
Red Hat Ent erprise Linux 7 Developer G uide
​T hread 2: 0
​2 2
while(count2 < 1000){
​( gdb) next
​2 3
printf("Thread 2: %d\n", count2++);
​( gdb) print count2
​$ 2 = 1
​( gdb) info threads
​ 3 Thread 0x7ffff75d2710 (LWP 4688) thread3 (d=0x0) at threethreads.c:9
​* 2 Thread 0x7ffff7fd3710 (LWP 4687) thread2 (d=0x0) at threethreads.c:23
​ 1 Thread 0x7ffff7fd5720 (LWP 4620) main () at three-threads.c:34
​( gdb)
Above, a few lines of thread2 printed the counter count2 and left thread 2 at line 23 as is seen by the
output of 'info threads'.
Now thread3.
​( gdb) thread 3
​[Switching to thread 3 (Thread 0x7ffff75d2710 (LWP 4688))]#0
(d=0x0)
​
at three-threads.c:9
​9
int count3 = 0;
​( gdb) list
​
4
​5 pthread_t thread;
​
6
​7 void* thread3 (void* d)
​8 {
​9
int count3 = 0;
​10
​11
while(count3 < 1000){
​12
sleep(10);
​13
printf("Thread 3: %d\n", count3++);
​( gdb)
thread3
Thread three is a little different in that it has a sleep statement and executes slowly. Think of it as a
representation of an uninteresting IO thread. Because this thread is uninteresting, continue its
execution uninterrupted, using the co nti nue.
​( gdb) continue &
​( gdb) Thread 3: 0
​T hread 3: 1
​T hread 3: 2
​T hread 3: 3
Take note of the & at the end of the co nti nue. This allows the GD B prompt to return so other
commands can be executed. Using the i nterrupt, execution can be stopped should thread 3
become interesting again.
​( gdb) interrupt
​[Thread 0x7ffff75d2710 (LWP 4688)] #3 stopped.
​0 x000000343f4a6a6d in nanosleep () at ../sysdeps/unix/syscalltemplate.S:82
90
⁠Chapt er 4 . Debugging
​8 2 T_PSEUDO (SYSCALL_SYMBOL, SYSCALL_NAME, SYSCALL_NARGS)
It is also possible to go back to the original main thread and examine it some more.
​( gdb) thread 1
​[Switching to thread 1 (Thread 0x7ffff7fd5720 (LWP 4620))]#0 main ()
​
at three-threads.c:34
​3 4
int count1 = 0;
​( gdb) next
​3 6
while(count1 < 1000){
​( gdb) next
​3 7
printf("Thread 1: %d\n", count1++);
​( gdb) next
​T hread 1: 0
​3 6
while(count1 < 1000){
​( gdb) next
​3 7
printf("Thread 1: %d\n", count1++);
​( gdb) next
​T hread 1: 1
​3 6
while(count1 < 1000){
​( gdb) next
​3 7
printf("Thread 1: %d\n", count1++);
​( gdb) next
​T hread 1: 2
​3 6
while(count1 < 1000){
​( gdb) print count1
​$ 3 = 3
​( gdb) info threads
​ 3 Thread 0x7ffff75d2710 (LWP 4688) 0x000000343f4a6a6d in nanosleep ()
​
at ../sysdeps/unix/syscall-template.S:82
​ 2 Thread 0x7ffff7fd3710 (LWP 4687) thread2 (d=0x0) at threethreads.c:23
​* 1 Thread 0x7ffff7fd5720 (LWP 4620) main () at three-threads.c:36
​( gdb)
As can be seen from the output of info threads, the other threads are where they were left, unaffected
by the debugging of thread 1.
4 .3.6. Alt ernat ive User Int erfaces for GDB
GD B uses the command line as its default interface. However, it also has an API called machine
interface (MI). MI allows ID E developers to create other user interfaces to GD B.
Some examples of these interfaces are:
Eclip se ( C D T )
A graphical debugger interface integrated with the Eclipse development environment. More
information can be found at the Eclipse website.
N emiver
A graphical debugger interface which is well suited to the GNOME D esktop Environment.
More information can be found at the Nemiver website
Emacs
91
Red Hat Ent erprise Linux 7 Developer G uide
A GD B interface which is integrated with the emacs. More information can be found at the
Emacs website
4 .3.7. GDB Document at ion
For more detailed information about GD B, see the GD B manual:
http://sources.redhat.com/gdb/current/onlinedocs/gdb.html
Also, the commands i nfo g d b and man g d b will provide more concise information that is up to
date with the installed version of gdb.
4 .4 . Variable T racking at Assignment s
Variable Tracking at Assignments (VTA) is a new infrastructure included in GCC used to improve
variable tracking during optimizations. This allows GCC to produce more precise, meaningful, and
useful debugging information for GD B, SystemTap, and other debugging tools.
When GCC compiles code with optimizations enabled, variables are renamed, moved around, or
even removed altogether. As such, optimized compiling can cause a debugger to report that some
variables have been <optimized out>. With VTA enabled, optimized code is internally annotated to
ensure that optimization passes to transparently keep track of each variable's value, regardless of
whether the variable is moved or removed. The effect of this is more parameter and variable values
available, even for the optimized (g cc -O 2 -g built) code. It also displays the <optimized out>
message less.
VTA's benefits are more pronounced when debugging applications with inlined functions. Without
VTA, optimization could completely remove some arguments of an inlined function, preventing the
debugger from inspecting its value. With VTA, optimization will still happen, and appropriate
debugging information will be generated for any missing arguments.
VTA is enabled by default when compiling code with optimizations and debugging information
enabled (that is, g cc -O -g or, more commonly, g cc -O 2 -g ). To disable VTA during such
builds, add the -fno -var-tracki ng -assi g nments. In addition, the VTA infrastructure includes
the new g cc option -fco mpare-d ebug . This option tests code compiled by GCC with debug
information and without debug information: the test passes if the two binaries are identical. This test
ensures that executable code is not affected by any debugging options, which further ensures that
there are no hidden bugs in the debug code. Note that -fco mpare-d ebug adds significant cost in
compilation time. See man g cc for details about this option.
For more information about the infrastructure and development of VTA, see A Plan to Fix Local Variable
Debug Information in GCC, available at the following link:
http://gcc.gnu.org/wiki/Var_Tracking_Assignments
A slide deck version of this whitepaper is also available at
http://people.redhat.com/aoliva/papers/vta/slides.pdf.
4 .5. Pyt hon Pret t y-Print ers
The GD B command pri nt outputs comprehensive debugging information for a target application.
GD B aims to provide as much debugging data as it can to users; however, this means that for highly
complex programs the amount of data can become very cryptic.
92
⁠Chapt er 4 . Debugging
In addition, GD B does not provide any tools that help decipher GD B pri nt output. GD B does not
even empower users to easily create tools that can help decipher program data. This makes the
practice of reading and understanding debugging data quite arcane, particularly for large, complex
projects.
For most developers, the only way to customize GD B pri nt output (and make it more meaningful) is
to revise and recompile GD B. However, very few developers can actually do this. Further, this
practice will not scale well, particularly if the developer must also debug other programs that are
heterogeneous and contain equally complex debugging data.
To address this, the Red Hat Enterprise Linux version of GD B is now compatible with Python prettyprinters. This allows the retrieval of more meaningful debugging data by leaving the introspection,
printing, and formatting logic to a third-party Python script.
Compatibility with Python pretty-printers gives you the chance to truly customize GD B output as you
see fit. This makes GD B a more viable debugging solution to a wider range of projects, since you
now have the flexibility to adapt GD B output as required, and with greater ease. Further, developers
with intimate knowledge of a project and a specific programming language are best qualified in
deciding what kind of output is meaningful, allowing them to improve the usefulness of that output.
The Python pretty-printers implementation allows users to automatically inspect, format, and print
program data according to specification. These specifications are written as rules implemented via
Python scripts. This offers the following benefits:
Saf e
To pass program data to a set of registered Python pretty-printers, the GD B development team added
hooks to the GD B printing code. These hooks were implemented with safety in mind: the built-in GD B
printing code is still intact, allowing it to serve as a default fallback printing logic. As such, if no
specialized printers are available, GD B will still print debugging data the way it always did. This
ensures that GD B is backwards-compatible; users who do not require pretty-printers can still
continue using GD B.
H ig h ly C u st o miz ab le
This new " Python-scripted" approach allows users to distill as much knowledge as required into
specific printers. As such, a project can have an entire library of printer scripts that parses program
data in a unique manner specific to its user's requirements. There is no limit to the number of printers
a user can build for a specific project; what's more, being able to customize debugging data script by
script offers users an easier way to re-use and re-purpose printer scripts — or even a whole library of
them.
Easy t o Learn
The best part about this approach is its lower barrier to entry. Python scripting is comparatively easy
to learn and has a large library of free documentation available online. In addition, most
programmers already have basic to intermediate experience in Python scripting, or in scripting in
general.
Here is a small example of a pretty printer. Consider the following C++ program:
f ru it .cc
​e num Fruits {Orange, Apple, Banana};
​c lass Fruit
​
{
93
Red Hat Ent erprise Linux 7 Developer G uide
​
int fruit;
​ public:
​ Fruit (int f)
​
{
​
fruit = f;
​
}
​} ;
​i nt main()
​
{
​ Fruit myFruit(Apple);
​ return 0;
// line 17
​
}
This is compiled with the command g + + -g frui t. cc -o frui t. Now, examine this program
with GD B.
​g db ./fruit
​[...]
​( gdb) break 17
​B reakpoint 1 at 0x40056d: file fruit.cc, line 17.
​( gdb) run
​B reakpoint 1, main () at fruit.cc:17
​17
return 0;
// line 17
​( gdb) print myFruit
​$ 1 = {fruit = 1}
The output of {frui t = 1} is correct because that is the internal representation of 'fruit' in the data
structure 'Fruit'. However, this is not easily read by humans as it is difficult to tell which fruit the
integer 1 represents.
To solve this problem, write the following pretty printer:
​fruit.py
​c lass FruitPrinter:
​
def __init__(self, val):
​
self.val = val
​
def to_string (self):
fruit = self.val['fruit']
​
​
​
if (fruit == 0):
name = "Orange"
elif (fruit == 1):
name = "Apple"
elif (fruit == 2):
name = "Banana"
else:
name = "unknown"
return "Our fruit is " + name
​
​
​
​
​
​
​
​
​d ef lookup_type (val):
​
if str(val.type) == 'Fruit':
94
⁠Chapt er 4 . Debugging
​
return FruitPrinter(val)
return None
​
​g db.pretty_printers.append (lookup_type)
Examine this printer from the bottom up.
The line g d b. pretty_pri nters. append (l o o kup_type) adds the function l o o kup_type to
GD B's list of printer lookup functions.
The function l o o kup_type is responsible for examining the type of object to be printed, and
returning an appropriate pretty printer. The object is passed by GD B in the parameter val.
val . type is an attribute which represents the type of the pretty printer.
Frui tP ri nter is where the actual work is done. More specifically in the to _stri ng function of that
Class. In this function, the integer frui t is retrieved using the python dictionary syntax
sel f. val [' frui t' ]. Then the name is determined using that value. The string returned by this
function is the string that will be printed to the user.
After creating frui t. py, it must then be loaded into GD B with the following command:
(g d b) pytho n execfi l e("frui t. py")
The GDB and Python Pretty-Printers whitepaper provides more details on this feature. This whitepaper
also includes details and examples on how to write your own Python pretty-printer as well as how to
import it into GD B. See the following link for more information:
http://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html
4 .6. ft race
The ftrace framework provides users with several tracing capabilities, accessible through an
interface much simpler than SystemTap's. This framework uses a set of virtual files in the d ebug fs
file system; these files enable specific tracers. The ftrace function tracer outputs each function
called in the kernel in real time; other tracers within the ftrace framework can also be used to
analyze wakeup latency, task switches, kernel events, and the like.
You can also add new tracers for ftrace, making it a flexible solution for analyzing kernel events.
The ftrace framework is useful for debugging or analyzing latencies and performance issues that
take place outside of user-space. Unlike other profilers documented in this guide, ftrace is a built-in
feature of the kernel.
4 .6.1. Using ft race
The Red Hat Enterprise Linux kernels have been configured with the C O NFIG _FT R AC E= y option.
This option provides the interfaces required by ftrace. To use ftrace, mount the d ebug fs file
system as follows:
mo unt -t d ebug fs no d ev /sys/kernel /d ebug
All the ftrace utilities are located in /sys/kernel /d ebug /traci ng /. View the
/sys/kernel /d ebug /traci ng /avai l abl e_tracers file to find out what tracers are available
for your kernel:
cat /sys/kernel /d ebug /traci ng /avai l abl e_tracers
95
Red Hat Ent erprise Linux 7 Developer G uide
power wakeup irqsoff function sysprof sched_switch initcall nop
To use a specific tracer, write it to /sys/kernel /d ebug /traci ng /current_tracer. For example,
wakeup traces and records the maximum time it takes for the highest-priority task to be scheduled
after the task wakes up. To use it:
echo wakeup > /sys/kernel /d ebug /traci ng /current_tracer
To start or stop tracing, write to /sys/kernel /d ebug /traci ng /traci ng _o n, as in:
echo 1 > /sys/kernel /d ebug /traci ng /traci ng _o n (enables tracing)
echo 0 > /sys/kernel /d ebug /traci ng /traci ng _o n (disables tracing)
The results of the trace can be viewed from the following files:
/sys/kern el/d eb u g /t racin g /t race
This file contains human-readable trace output.
/sys/kern el/d eb u g /t racin g /t race_p ip e
This file contains the same output as /sys/kernel /d ebug /traci ng /trace, but is
meant to be piped into a command. Unlike /sys/kernel /d ebug /traci ng /trace,
reading from this file consumes its output.
4 .6.2. ft race Document at ion
The ftrace framework is fully documented in the following files:
ftrace - Function Tracer: fi l e: ///usr/share/d o c/kernel d o c-version/D o cumentati o n/trace/ftrace. txt
function tracer guts: fi l e: ///usr/share/d o c/kernel d o c-version/D o cumentati o n/trace/ftrace-d esi g n. txt
Note
The trace-cmd package provides a tool of the same name that can be a useful alternative to
ftrace. Further information is available on the trace-cmd man page.
96
⁠Chapt er 5. Monit oring Performance
Chapter 5. Monitoring Performance
D evelopers profile programs to focus attention on the areas of the program that have the largest
impact on performance. The types of data collected include what section of the program consumes
the most processor time, and where memory is allocated. Profiling collects data from the actual
program execution. Thus, the quality of the data collect is influenced by the actual tasks being
performed by the program. The tasks performed during profiling should be representative of actual
use; this ensures that problems arising from realistic use of the program are addressed during
development.
Red Hat Enterprise Linux includes a number of different tools (Valg rin d , O Pro f ile, perf, and
Syst emT ap ) to collect profiling data. Each tool is suitable for performing specific types of profile
runs, as described in the following sections.
5.1. Valgrind
Valg rin d is an instrumentation framework for building dynamic analysis tools that can be used to
profile applications in detail. Valg rin d tools are generally used to automatically detect many memory
management and threading problems. The Valg rin d suite also includes tools that allow the building
of new profiling tools as required.
Valg rin d provides instrumentation for user-space binaries to check for errors, such as the use of
uninitialized memory, improper allocation/freeing of memory, and improper arguments for
systemcalls. Its profiling tools can be used by normal users on most binaries; however, compared to
other profilers, Valg rin d profile runs are significantly slower. To profile a binary, Valg rin d rewrites
its executable and instruments the rewritten binary. Valg rin d 's tools are most useful for looking for
memory-related issues in user-space programs; it is not suitable for debugging time-specific issues
or kernel-space instrumentation/debugging.
Previously, Valg rin d did not support IBM System z architecture. However, as of 6.1, this support has
been added, meaning Valg rin d now supports all hardware architectures that are supported by
Red Hat Enterprise Linux 6.x.
5.1.1. Valgrind T ools
The Valg rin d suite is composed of the following tools:
memch eck
This tool detects memory management problems in programs by checking all reads from
and writes to memory and intercepting all system calls to mal l o c, new, free, and d el ete.
memch eck is perhaps the most used Valg rin d tool, as memory management problems
can be difficult to detect using other means. Such problems often remain undetected for
long periods, eventually causing crashes that are difficult to diagnose.
cach eg rin d
cach eg rin d is a cache profiler that accurately pinpoints sources of cache misses in code
by performing a detailed simulation of the I1, D 1 and L2 caches in the CPU. It shows the
number of cache misses, memory references, and instructions accruing to each line of
source code; cach eg rin d also provides per-function, per-module, and whole-program
summaries, and can even show counts for each individual machine instructions.
callg rin d
97
Red Hat Ent erprise Linux 7 Developer G uide
Like cacheg ri nd , cal l g ri nd can model cache behavior. However, the main purpose of
cal l g ri nd is to record callgraphs data for the executed code.
massif
massif is a heap profiler; it measures how much heap memory a program uses, providing
information on heap blocks, heap administration overheads, and stack sizes. Heap
profilers are useful in finding ways to reduce heap memory usage. On systems that use
virtual memory, programs with optimized heap memory usage are less likely to run out of
memory, and may be faster as they require less paging.
h elg rin d
In programs that use the POSIX pthreads threading primitives, h elg rin d detects
synchronization errors. Such errors are:
Misuses of the POSIX pthreads API
Potential deadlocks arising from lock ordering problems
D ata races (that is, accessing memory without adequate locking)
Valg rin d also allows you to develop your own profiling tools. In line with this, Valg rin d includes the
l ackey tool, which is a sample that can be used as a template for generating your own tools.
5.1.2. Using Valgrind
The val g ri nd package and its dependencies install all the necessary tools for performing a
Valg rin d profile run. To profile a program with Valg rin d , use:
val g ri nd --to o l = toolname program
See Section 5.1.1, “ Valgrind Tools” for a list of arguments for toolname. In addition to the suite of
Valg rin d tools, no ne is also a valid argument for toolname; this argument allows you to run a
program under Valg rin d without performing any profiling. This is useful for debugging or
benchmarking Valg rin d itself.
You can also instruct Valg rin d to send all of its information to a specific file. To do so, use the
option --l o g -fi l e= filename. For example, to check the memory usage of the executable file
hel l o and send profile information to o utput, use:
val g ri nd --to o l = memcheck --l o g -fi l e= o utput hel l o
See Section 5.1.3, “ Valgrind D ocumentation” for more information on Valg rin d , along with other
available documentation on the Valg rin d suite of tools.
5.1.3. Valgrind Document at ion
For more extensive information on Valg rin d , see man val g ri nd . Red Hat Enterprise Linux 6 also
provides a comprehensive Valgrind Documentation book, available as PD F and HTML in:
fi l e: ///usr/share/d o c/val g ri nd -version/val g ri nd _manual . pd f
fi l e: ///usr/share/d o c/val g ri nd -version/html /i nd ex. html
The Valgrind Integration User Guide in the Eclipse H elp C o n t en t salso provides detailed information
on the setup and usage of the Valg rin d plug-in for Eclipse. This guide is provided by the ecl i pseval g ri nd package.
98
⁠Chapt er 5. Monit oring Performance
5.2. OProfile
OProfile is a system-wide Linux profiler, capable of running at low overhead. It consists of a kernel
driver and a daemon for collecting raw sample data, along with a suite of tools for parsing that data
into meaningful information. OProfile is generally used by developers to determine which sections of
code consume the most amount of CPU time, and why.
D uring a profile run, OProfile uses the processor's performance monitoring hardware. Valg rin d
rewrites the binary of an application, and in turn instruments it. OProfile, on the other hand,profiles a
running application as-is. It sets up the performance monitoring hardware to take a sample every x
number of events (for example, cache misses or branch instructions). Each sample also contains
information on where it occurred in the program.
OProfile's profiling methods consume less resources than Valg rin d . However, OProfile requires root
privileges. OProfile is useful for finding " hot-spots" in code, and looking for their causes (for
example, poor cache performance, branch mispredictions).
Using OProfile involves starting the OProfile daemon (o pro fi l ed ), running the program to be
profiled, collecting the system profile data, and parsing it into a more understandable format.
OProfile provides several tools for every step of this process.
5.2.1. OProfile T ools
The most useful OProfile commands include the following:
o p erf
New in Red Hat Enterprise Linux 7, o perf uses the Linux Performance Events subsystem,
and so can completely replace use of the o pco ntro l daemon. See the Red Hat
Enterprise Linux 7 System Administrator's Guide for further details.
o p co n t ro l
This tool is used to start/stop the OProfile daemon and configure a profile session.
o p rep o rt
The o prepo rt command outputs binary image summaries, or per-symbol data, from
OProfile profiling sessions.
o p an n o t at e
The o panno tate command outputs annotated source and/or assembly from the profile
data of an OProfile session.
o p arch ive
The o parchi ve command generates a directory populated with executable, debug, and
OProfile sample files. This directory can be moved to another machine (via tar), where it
can be analyzed offline.
o p g p ro f
Like o prepo rt, the o pg pro f command outputs profile data for a given binary image from
an OProfile session. The output of o pg pro f is in g pro f format.
99
Red Hat Ent erprise Linux 7 Developer G uide
For a complete list of OProfile commands, see man o pro fi l e. For detailed information on each
OProfile command, see its corresponding man page. See Section 5.2.4, “ OProfile D ocumentation” for
other available documentation on OProfile.
5.2.2. Using OProfile
The o pro fi l e package and its dependencies install all the necessary utilities for executing
OProfile. To instruct OProfile to profile all the applications running on the system and to group the
samples for the shared libraries with the application using the library, run the following command:
# o pco ntro l --no -vml i nux --separate= l i brary --start
You can also start the OProfile daemon without collecting system data. To do so, use the option -start-d aemo n. The --sto p option halts data collection, while --shutd o wn terminates the OProfile
daemon.
Use o prepo rt, o panno tate, or o pg pro f to display the collected profiling data. By default, the data
collected by the OProfile daemon is stored in /var/l i b/o pro fi l e/sampl es/.
O Pro f ile co n f lict wit h Perf o rman ce C o u n t ers f o r Lin u x ( PC L) t o o ls
Both OProfile and Performance Counters for Linux (PCL) use the same hardware Performance
Monitoring Unit (PMU). If the PCL or the NMI watchdog timer are using the hardware PMU, a message
like the following occurs when starting OProfile:
# opcontrol --start
Using default event: CPU_CLK_UNHALTED:100000:0:1:1
Error: counter 0 not available nmi_watchdog using this resource ? Try:
opcontrol --deinit
echo 0 > /proc/sys/kernel/nmi_watchdog
Stop any perf commands running on the system, then turn off the NMI watchdog and reload the
OProfile kernel driver with the following commands:
# o pco ntro l --d ei ni t
# echo 0 > /pro c/sys/kernel /nmi _watchd o g
5.2.3. OProfile in Red Hat Ent erprise Linux 7
OProfile 0.9.8 has been released for Red Hat Enterprise Linux 7. This is an alpha version but has
proven stable for many users. With the 0.9.8 release OProfile can now also be used to profile specific
individual processes.
5 .2 .3.1 . Ne w Fe at ure s
A new o perf program is now available that allows non-root users to profile single processes. This
can also be used for system-wide profiling, but in this case root authority is required. This capability
requires a kernel version of 2.6.31 or greater.
OProfile also supports a number of new processors:
Tilera tile64
100
⁠Chapt er 5. Monit oring Performance
Tilera tilepro
Tilera tile-gx
IBM System z10
IBM System z196
Intel Ivy Bridge
ARMv7 Cortex-A5
ARMv7 Cortex-A15
ARMv7 Cortex-A7
5 .2 .3.2 . Inco m pat ibilit ie s wit h t he Pre vio us Re le ase
OProfile 0.9.8 has some incompatibilities with the previous release:
Support for pre-2.6 kernels has been removed.
With the removal of pre-2.6 support, the --wi th-kernel -suppo rt configure option is no longer
needed nor valid.
Sample header mtime field has changed to u64.
The co nfi g ure. i n file has been renamed to co nfi g ure. ac. This should a transparent
change.
5 .2 .3.3. Kno wn Pro ble m s and Lim it iat io ns
OProfile 0.9.8 has a few known problems and limitations. These are:
AMD Instruction Based Sampling (IBS) is not currently supported with the new operf program. Use
the l eg acy opcontrol commands for IBS profiling.
When using o perf to profile multiple events, the absolute number of events recorded will usually
be substantially fewer than expected. This is due to a bug in the Linux kernel's Performance
Events Subsystem that was fixed between Linux kernel version 3.1 and 3.5.
If NMI watchdog is not disabled on x86_64 systems, o pco ntro l may fail to allocate the hardware
performance counters it needs. The progress of this issue can be followed in bugzilla at
https://bugzilla.redhat.com/show_bug.cgi?id=683176.
Many Alpha ev67 events do not work. The progress of this issue can be followed in bugzilla
https://bugzilla.redhat.com/show_bug.cgi?id=931875.
5.2.4 . OProfile Document at ion
For a more extensive information on OProfile, see man o pro fi l e. Red Hat Enterprise Linux also
provides two comprehensive guides to OProfile in
fi l e: ///usr/share/d o c/o pro fi l e-version/:
O Pro f ile Man u al
A comprehensive manual with detailed instructions on the setup and use of OProfile is
found at fi l e: ///usr/share/d o c/o pro fi l e-version/o pro fi l e. html
101
Red Hat Ent erprise Linux 7 Developer G uide
O Pro f ile In t ern als
D ocumentation on the internal workings of OProfile, useful for programmers interested in
contributing to the OProfile upstream, can be found at
fi l e: ///usr/share/d o c/o pro fi l e-version/i nternal s. html
The OProfile Integration User Guide in the Eclipse H elp C o n t en t s also provides detailed information
on the setup and usage of the OProfile plug-in for Eclipse. This guide is provided by the ecl i pseo pro fi l e package.
5.3. Syst emT ap
SystemTap is a useful instrumentation platform for probing running processes and kernel activity on
the Linux system. To execute a probe:
1. Write SystemTap scripts that specify which system events (for example, virtual file system
reads, packet transmissions) should trigger specified actions (for example, print, parse, or
otherwise manipulate data).
2. SystemTap translates the script into a C program, which it compiles into a kernel module.
3. SystemTap loads the kernel module to perform the actual probe.
SystemTap scripts are useful for monitoring system operation and diagnosing system issues with
minimal intrusion into the normal operation of the system. You can quickly instrument running system
test hypotheses without having to recompile and re-install instrumented code. To compile a
SystemTap script that probes kernel-space, SystemTap uses information from three different kernel
information packages:
kernel -variant-d evel -version
kernel -variant-d ebug i nfo -version
kernel -d ebug i nfo -co mmo n-arch-version
These kernel information packages must match the kernel to be probed. In addition, to compile
SystemTap scripts for multiple kernels, the kernel information packages of each kernel must also be
installed.
An important new feature has been added as of Red Hat Enterprise Linux 6.1: the --remo te option.
This allows users to build the SystemTap module locally, and then execute it remotely via SSH. The
syntax to use this is --remo te [USER @ ]HO ST NAME; set the execution target to the specified SSH
host, optionally using a different username. This option may be repeated to target multiple execution
targets. Passes 1-4 are completed locally as normal to build the script, and then pass 5 copies the
module to the target and runs it.
5.3.1. DynInst wit h Syst emT ap 2.0
SystemTap 2.0 introduces experamental support for running instrumentation using the DynInst
system. D ynInst is a pure-userspace binary manipulation library that allows programs to modify
other running programs. It does this by inserting highly efficient instrumentation or other
modifications. SystemTap 2.0 and later can use this as a backend to run a restricted class of scripts.
In exchange for the restrictions, the instrumentation runs fast and entirely in user-space with no root
access or kernel module operations required. The restrictions are evolving but are tighter than those
for unprivileged user probing that relies on cryptography, kernel modules, and membership in
special groups.
102
⁠Chapt er 5. Monit oring Performance
To use this experamental backend, add an extra --runti me option on the stap command line:
$ stap --runtime=stapdyn script.stp -c command
If the script requires facilities beyond those available with D ynInst, SystemTap will advise. If this is
the case, the standard kernel-module-based backends will have to be used with the --runti me
option omitted.
5.3.2. Syst emT ap Compile Server
SystemTap in Red Hat Enterprise Linux 7 supports a compile server and client deployment. With this
setup, the kernel information packages of all client systems in the network are installed on just one
compile server host (or a few). When a client system attempts to compile a kernel module from a
SystemTap script, it remotely accesses the kernel information it requires from the centralized compile
server host.
A properly configured and maintained SystemTap compile server host offers the following benefits:
The system administrator can verify the integrity of kernel information packages before making the
packages available to users.
The identity of a compile server can be authenticated using the Secure Socket Layer (SSL). SSL
provides an encrypted network connection that prevents eavesdropping or tampering during
transmission.
Individual users can run their own servers and authorize them for their own use as trusted.
System administrators can authorize one or more servers on the network as trusted for use by all
users.
A server that has not been explicitly authorized is ignored, preventing any server impersonations
and similar attacks.
5.3.3. Syst emT ap Support for Unprivileged Users
For security purposes, users in an enterprise setting are rarely given privileged (that is, root or sud o )
access to their own machines. In addition, full SystemTap functionality should also be restricted to
privileged users, as this can provide the ability to completely take control of a system.
SystemTap in Red Hat Enterprise Linux 7 features a new option to the SystemTap client: -unpri vi l eg ed . This option allows an unprivileged user to run stap. Of course, several restrictions
apply to unprivileged users that attempt to run stap.
Note
An unprivileged user is a member of the group stapusr but is not a member of the group
stapd ev (and is not root).
Before loading any kernel modules created by unprivileged users, SystemTap verifies the integrity of
the module using standard digital (cryptographic) signing techniques. Each time the -unpri vi l eg ed option is used, the server checks the script against the constraints imposed for
unprivileged users. If the checks are successful, the server compiles the script and signs the resulting
103
Red Hat Ent erprise Linux 7 Developer G uide
module using a self-generated certificate. When the client attempts to load the module, staprun first
verifies the signature of the module by checking it against a database of trusted signing certificates
maintained and authorized by root.
Once a signed kernel module is successfully verified, staprun is assured that:
The module was created using a trusted systemtap server implementation.
The module was compiled using the --unpri vi l eg ed option.
The module meets the restrictions required for use by an unprivileged user.
The module has not been tampered with since it was created.
5.3.4 . SSL and Cert ificat e Management
SystemTap in Red Hat Enterprise Linux 7 implements authentication and security via certificates and
public/private key pairs. It is the responsibility of the system administrator to add the credentials (that
is, certificates) of compile servers to a database of trusted servers. SystemTap uses this database to
verify the identity of a compile server that the client attempts to access. Likewise, SystemTap also
uses this method to verify kernel modules created by compile servers using the --unpri vi l eg ed
option.
5 .3.4 .1 . Aut ho rizing Co m pile Se rve rs fo r Co nne ct io n
The first time a compile server is started on a server host, the compile server automatically generates
a certificate. This certificate verifies the compile server's identity during SSL authentication and
module signing.
In order for clients to access the compile server (whether on the same server host or from a client
machine), the system administrator must add the compile server's certificate to a database of trusted
servers. Each client host intending to use compile servers maintains such a database. This allows
individual users to customize their database of trusted servers, which can include a list of compile
servers authorized for their own use only.
5 .3.4 .2 . Aut ho rizing Co m pile Se rve rs fo r Mo dule Signing (fo r Unprivile ge d Use rs)
Unprivileged users can only load signed, authorized SystemTap kernel modules. For modules to be
recognized as such, they have to be created by a compile server whose certificate appears in a
database of trusted signers; this database must be maintained on each host where the module will be
loaded.
5 .3.4 .3. Aut o m at ic Aut ho rizat io n
Servers started using the stap-server initscript are automatically authorized to receive connections
from all clients on the same host.
Servers started by other means are automatically authorized to receive connections from clients on
the same host run by the user who started the server. This was implemented with convenience in
mind; users are automatically authorized to connect to a server they started themselves, provided
that both client and server are running on the same host.
Whenever root starts a compile server, all clients running on the same host automatically recognize
the server as authorized. However, Red Hat advises that you refrain from doing so.
104
⁠Chapt er 5. Monit oring Performance
Similarly, a compile server initiated through stap-server is automatically authorized as a trusted
signer on the host in which it runs. If the compile server was initiated through other means, it is not
automatically authorized as such.
5.3.5. Syst emT ap Document at ion
For more detailed information about SystemTap, see the following books (also provided by Red Hat):
SystemTap Beginner's Guide
SystemTap Tapset Reference
The SystemTap Beginner's Guide and SystemTap Tapset Reference are also available locally when you
install the systemtap package:
fi l e: ///usr/share/d o c/systemtap-version/SystemT ap_Beg i nners_G ui d e/i nd ex.
html
fi l e: ///usr/share/d o c/systemtap-version/SystemT ap_Beg i nners_G ui d e. pd f
fi l e: ///usr/share/d o c/systemtap-version/tapsets/i nd ex. html
fi l e: ///usr/share/d o c/systemtap-version/tapsets. pd f
Section 5.3.2, “ SystemTap Compile Server” , Section 5.3.3, “ SystemTap Support for Unprivileged
Users” , and Section 5.3.4, “ SSL and Certificate Management” are all excerpts from the SystemTap
Support for Unprivileged Users and Server Client Deployment whitepaper. This whitepaper also provides
more details on each feature, along with a case study to help illustrate their application in a realworld environment.
5.4 . Performance Count ers for Linux (PCL) T ools and perf
Performance Counters for Linux (PCL) is a new kernel-based subsystem that provides a framework for
collecting and analyzing performance data. These events will vary based on the performance
monitoring hardware and the software configuration of the system. Red Hat Enterprise Linux 6
includes this kernel subsystem to collect data and the user-space tool perf to analyze the collected
performance data.
The PCL subsystem can be used to measure hardware events, including retired instructions and
processor clock cycles. It can also measure software events, including major page faults and context
switches. For example, PCL counters can compute the Instructions Per Clock (IPC) from a process's
counts of instructions retired and processor clock cycles. A low IPC ratio indicates the code makes
poor use of the CPU. Other hardware events can also be used to diagnose poor CPU performance.
Performance counters can also be configured to record samples. The relative frequency of samples
can be used to identify which regions of code have the greatest impact on performance.
5.4 .1. Perf T ool Commands
Useful perf commands include the following:
p erf st at
This perf command provides overall statistics for common performance events, including
instructions executed and clock cycles consumed. Options allow selection of events other
than the default measurement events.
105
Red Hat Ent erprise Linux 7 Developer G uide
p erf reco rd
This perf command records performance data into a file which can be later analyzed
using perf repo rt.
p erf rep o rt
This perf command reads the performance data from a file and analyzes the recorded
data.
p erf list
This perf command lists the events available on a particular machine. These events will
vary based on the performance monitoring hardware and the software configuration of the
system.
Use perf hel p to obtain a complete list of perf commands. To retrieve man page information on
each perf command, use perf hel p command.
5.4 .2. Using Perf
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 al l
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
53328 context-switches
515 CPU-migrations
1843121 page-faults
789702529782 cycles
1050912611378 instructions
275538938708 branches
2888756216 branch-misses
4343060367 cache-references
428257037 cache-misses
263.779192511
#
#
#
#
#
#
#
#
#
#
0.925 CPUs
0.000 M/sec
0.000 M/sec
0.008 M/sec
3236.330 M/sec
1.331 IPC
1129.203 M/sec
1.048 %
17.799 M/sec
1.755 M/sec
seconds time elapsed
The perf tool can also record samples. For example, to record data on the make command and its
children, use:
# perf reco rd -- make al l
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) ]
106
⁠Chapt er 5. Monit oring Performance
As of Red Hat Enterprise Linux 6.4, a new functionality to the {} group syntax has been added that
allows the creation of event groups based on the way they are specified on the command line.
The current --g ro up or -g options remain the same; if it is specified for record, stat, or top
command, all the specified events become members of a single group with the first event as a group
leader.
The new {} group syntax allows the creation of a group like:
# perf reco rd -e ' {cycles, faults}' l s
The above results in a single event group containing cycles and faults events, with the cycles event as
the group leader.
All groups are created with regards to threads and CPUs. As such, recording an event group within
two threads on a server with four CPUs will create eight separate groups.
It is possible to use a standard event modifier for a group. This spans over all events in the group
and updates each event modifier settings.
# perf reco rd -r ' {faults:k,cache-references}: p'
The above command results in the : kp modifier being used for faults, and the : p modifier being used
for the cache-references event.
Perf o rman ce C o u n t ers f o r Lin u x ( PC L) T o o ls co n f lict wit h O Pro f ile
Both OProfile and Performance Counters for Linux (PCL) use the same hardware Performance
Monitoring Unit (PMU). If OProfile is currently running while attempting to use the PCL perf
command, an error message like the following occurs when starting OProfile:
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:
# o pco ntro l --d ei ni t
You can then analyze perf. d ata to determine the relative frequency of samples. The report output
includes the command, object, and function for the samples. Use perf repo rt to output an analysis
of perf. d ata. For example, the following command produces a report of the executable that
consumes the most time:
# perf repo rt --so rt= co mm
The resulting output:
# Samples: 1083783860000
#
# Overhead
Command
# ........ ...............
#
48.19%
xsltproc
107
Red Hat Ent erprise Linux 7 Developer G uide
44.48%
6.01%
0.95%
0.17%
0.05%
0.05%
0.03%
0.01%
0.01%
0.01%
0.01%
0.01%
0.00%
0.00%
0.00%
0.00%
0.00%
pdfxmltex
make
perl
kernel-doc
xmllint
cc1
cp
xmlto
sh
docproc
ld
gcc
rm
sed
git-diff-files
bash
git-diff-index
The column on the left shows the relative frequency of the samples. This output shows that make
spends most of this time in xsl tpro c and the pd fxml tex. To reduce the time for the make to
complete, focus on xsl tpro c and pd fxml tex. To list the functions executed by xsl tpro c, run:
# perf repo rt -n --co mm= xsl tpro c
This generates:
comm: xsltproc
# Samples: 472520675377
#
# Overhead Samples
Shared Object
# ........ .......... .............................
#
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
2.41%11379910918 libxml2.so.2.7.6
xmlXPathIsNaN__internal_alias
2.19%10340901937 libxml2.so.2.7.6
valuePush__internal_alias
108
Symbol
......
[.]
[.]
[.]
[.]
[.]
[.] valuePop
[.]
[.]
⁠Chapt er 6 . Writ ing Document at ion
Chapter 6. Writing Documentation
Red Hat_Enterprise Linux 7 offers the D o xyg en tool for generating documentation from source code
and for writing standalone documentation.
6.1. Doxygen
D oxygen is a documentation tool that creates reference material both online in HTML and offline in
Latex. It does this from a set of documented source files which makes it easy to keep the
documentation consistent and correct with the source code.
6.1.1. Doxygen Support ed Out put and Languages
D oxygen has support for output in:
RTF (MS Word)
PostScript
Hyperlinked PD F
Compressed HTML
Unix man pages
D oxygen supports the following programming languages:
C
C++
C#
Objective -C
ID L
Java
VHD L
PHP
Python
Fortran
D
6.1.2. Get t ing St art ed
D oxygen uses a configuration file to determine its settings, therefore it is paramount that this be
created correctly. Each project requires its own configuration file. The most painless way to create the
configuration file is with the command d o xyg en -g config-file. This creates a template
configuration file that can be easily edited. The variable config-file is the name of the configuration file.
109
Red Hat Ent erprise Linux 7 Developer G uide
If it is committed from the command it is called D oxyfile by default. Another useful option while
creating the configuration file is the use of a minus sign (-) as the file name. This is useful for
scripting as it will cause D oxygen to attempt to read the configuration file from standard input
(std i n).
The configuration file consists of a number of variables and tags, similar to a simple Makefile. For
example:
T AG NAME = VALUE1 VALUE2. . .
For the most part these can be left alone but should it be required to edit them see the configuration
page of the D oxygen documentation website for an extensive explanation of all the tags available.
There is also a GUI interface called d o xywi zard . If this is the preferred method of editing then
documentation for this function can be found on the Doxywizard usage page of the D oxygen
documentation website.
There are eight tags that are useful to become familiar with.
INP UT
For small projects consisting mainly of C or C++ source and header files it is not required to change
anything. However, if the project is large and consists of a source directory or tree, then assign the
root directory or directories to the INPUT tag.
FILE_P AT T ER NS
File patterns (for example, *. cpp or *. h) can be added to this tag allowing only files that match one
of the patterns to be parsed.
R EC UR SIVE
Setting this to yes will allow recursive parsing of a source tree.
EXC LUD E an d EXC LUD E_P AT T ER NS
These are used to further fine-tune the files that are parsed by adding file patterns to avoid. For
example, to omit all test directories from a source tree, use EXC LUD E_P AT T ER NS = */test/*.
EXT R AC T _ALL
When this is set to yes, doxygen will pretend that everything in the source files is documented to give
an idea of how a fully documented project would look. However, warnings regarding undocumented
members will not be generated in this mode; set it back to no when finished to correct this.
SO UR C E_BR O WSER an d INLINE_SO UR C ES
By setting the SO UR C E_BR O WSER tag to yes doxygen will generate a cross-reference to analyze a
piece of software's definition in its source files with the documentation existing about it. These
sources can also be included in the documentation by setting INLINE_SO UR C ES to yes.
6.1.3. Running Doxygen
Running d o xyg en config-file creates html , rtf, l atex, xml , and / or man directories in
whichever directory doxygen is started in, containing the documentation for the corresponding
filetype.
HT ML O UT P UT
110
⁠Chapt er 6 . Writ ing Document at ion
This documentation can be viewed with a HTML browser that supports cascading style sheets (CSS),
as well as D HTML and Javascript for some sections. Point the browser (for example, Mozilla, Safari,
Konqueror, or Internet Explorer 6) to the i nd ex. html in the html directory.
LaT eX O UT P UT
D oxygen writes a Makefi l e into the l atex directory in order to make it easy to first compile the
Latex documentation. To do this, use a recent teTeX distribution. What is contained in this directory
depends on whether the USE_P D FLAT EX is set to no . Where this is true, typing make while in the
l atex directory generates refman. d vi . This can then be viewed with xd vi or converted to
refman. ps by typing make ps. Note that this requires d vi ps.
There are a number of commands that may be useful. The command make ps_2o n1 prints two
pages on one physical page. It is also possible to convert to a PD F if a ghostscript interpreter is
installed by using the command make pd f. Another valid command is make pd f_2o n1. When
doing this set P D F_HY P ER LINKS and USE_P D FLAT EX tags to yes as this will cause Makefi l e will
only contain a target to build refman. pd f directly.
R T F O UT P UT
This file is designed to import into Microsoft Word by combining the RTF output into a single file:
refman. rtf. Some information is encoded using fields but this can be shown by selecting all
(C T R L+ A or Edit -> select all) and then right-click and select the to g g l e fi el d s option from the
drop down menu.
XML O UT P UT
The output into the xml directory consists of a number of files, each compound gathered by
doxygen, as well as an i nd ex. xml . An XSLT script, co mbi ne. xsl t, is also created that is used to
combine all the XML files into a single file. Along with this, two XML schema files are created,
i nd ex. xsd for the index file, and co mpo und . xsd for the compound files, which describe the
possible elements, their attributes, and how they are structured.
MAN P AG E O UT P UT
The documentation from the man directory can be viewed with the man program after ensuring the
manpath has the correct man directory in the man path. Be aware that due to limitations with the man
page format, information such as diagrams, cross-references and formulas will be lost.
6.1.4 . Document ing t he Sources
There are three main steps to document the sources.
1. First, ensure that EXT R AC T _ALL is set to no so warnings are correctly generated and
documentation is built properly. This allows doxygen to create documentation for
documented members, files, classes and namespaces.
2. There are two ways this documentation can be created:
A special d o cu men t at io n b lo ck
This comment block, containing additional marking so D oxygen knows it is part of
the documentation, is in either C or C++. It consists of a brief description, or a
detailed description. Both of these are optional. What is not optional, however, is
the in body description. This then links together all the comment blocks found in the
body of the method or function.
111
Red Hat Ent erprise Linux 7 Developer G uide
Note
While more than one brief or detailed description is allowed, this is not
recommended as the order is not specified.
The following will detail the ways in which a comment block can be marked as a
detailed description:
C-style comment block, starting with two asterisks (*) in the JavaD oc style.
/**
* ... documentation ...
*/
C-style comment block using the Qt style, consisting of an exclamation mark (!)
instead of an extra asterisk.
/*!
* ... documentation ...
*/
The beginning asterisks on the documentation lines can be left out in both cases
if that is preferred.
A blank beginning and end line in C++ also acceptable, with either three forward
slashes or two forward slashes and an exclamation mark.
///
/// ... documentation
///
or
//!
//! ... documentation ...
//!
Alternatively, in order to make the comment blocks more visible a line of asterisks
or forward slashes can be used.
/////////////////////////////////////////////////
/// ... documentation ...
/////////////////////////////////////////////////
or
/********************************************//**
* ... documentation ...
***********************************************/
Note that the two forwards slashes at the end of the normal comment block start
a special comment block.
112
⁠Chapt er 6 . Writ ing Document at ion
There are three ways to add a brief description to documentation.
To add a brief description use \bri ef above one of the comment blocks. This
brief section ends at the end of the paragraph and any further paragraphs are
the detailed descriptions.
/*! \brief brief documentation.
*
brief documentation.
*
* detailed documentation.
*/
By setting JAVAD O C _AUT O BR IEF to yes, the brief description will only last until
the first dot followed by a space or new line. Consequentially limiting the brief
description to a single sentence.
/** Brief documentation. Detailed documentation continues
* from here.
*/
This can also be used with the above mentioned three-slash comment blocks
(///).
The third option is to use a special C++ style comment, ensuring this does not
span more than one line.
/// Brief documentation.
/** Detailed documentation. */
or
//! Brief documentation.
//! Detailed documentation //! starts here
The blank line in the above example is required to separate the brief description
and the detailed description, and JAVAD O C _AUT O BR IEF must to be set to no .
Examples of how a documented piece of C++ code using the Qt style can be found
on the Doxygen documentation website
It is also possible to have the documentation after members of a file, struct, union,
class, or enum. To do this add a < marker in the comment block.\
int var; /*!< detailed description after the member */
Or in a Qt style as:
int var; /**< detailed description after the member */
or
int var; //!< detailed description after the member
//!<
113
Red Hat Ent erprise Linux 7 Developer G uide
or
int var; ///< detailed description after the member
///<
For brief descriptions after a member use:
int var; //!< brief description after the member
or
int var; ///< brief description after the member
Examples of these and how the HTML is produced can be viewed on the Doxygen
documentation website
D o cu men t at io n at o t h er p laces
While it is preferable to place documentation in front of the code it is documenting,
at times it is only possible to put it in a different location, especially if a file is to be
documented; after all it is impossible to place the documentation in front of a file.
This is best avoided unless it is absolutely necessary as it can lead to some
duplication of information.
To do this it is important to have a structural command inside the documentation
block. Structural commands start with a backslash (\) or an at-sign (@) for JavaD oc
and are followed by one or more parameters.
/*! \class Test
\brief A test class.
A more detailed description of class.
*/
In the above example the command \cl ass is used. This indicates that the
comment block contains documentation for the class 'Test'. Others are:
\struct: document a C-struct
\uni o n: document a union
\enum: document an enumeration type
\fn: document a function
\var: document a variable, typedef, or enum value
\d ef: document a #define
\typed ef: document a type definition
\fi l e: document a file
\namespace: document a namespace
\packag e: document a Java package
\i nterface: document an ID L interface
114
⁠Chapt er 6 . Writ ing Document at ion
3. Next, the contents of a special documentation block is parsed before being written to the
HTML and / Latex output directories. This includes:
a. Special commands are executed.
b. Any white space and asterisks (*) are removed.
c. Blank lines are taken as new paragraphs.
d. Words are linked to their corresponding documentation. Where the word is preceded
by a percent sign (% ) the percent sign is removed and the word remains.
e. Where certain patterns are found in the text, links to members are created. Examples of
this can be found on the automatic link generation page on the D oxygen documentation
website.
f. When the documentation is for Latex, HTML tags are interpreted and converted to
Latex equivalents. A list of supported HTML tags can be found on the HTML commands
page on the D oxygen documentation website.
6.1.5. Resources
More information can be found on the D oxygen website.
Doxygen homepage
Doxygen introduction
Doxygen documentation
Output formats
115
Red Hat Ent erprise Linux 7 Developer G uide
Appendix
A.1. mal l o pt
mal l o pt is a library call that allows a program to change the behavior of the malloc memory
allocator.
Examp le A.1. Allo cat o r h eu rist ics
An allocator has heuristics to determine long versus short lived objects. For the former, it attempts
to allocate with mmap. For the later, it attempts to allocate with sbrk.
In order to override these heuristics, set M_MMAP _T HR ESHO LD .
In multi-threaded applications, the allocator creates multiple arenas in response to lock contention in
existing arenas. This can improve the performance significantly for some multi-threaded applications
at the cost of an increase in memory usage. To keep this under control, limit the number of arenas
that can be created by using the mal l o pt interface.
The allocator has limits on the number of arenas it can create. For 32bit targets, it will create 2 * #
core arenas; for 64bit targets, it will create 8 * # core arenas. mal l o pt allows the developer to
override those limits.
Examp le A.2. mal l o pt
To ensure no more than eight arenas are created, issue the following library call:
mallopt (M_ARENA_MAX, 8);
The first argument for mal l o pt can be:
M_MXFAST
M_TRIM_THRESHOLD
M_TOP_PAD
M_MMAP_THRESHOLD
M_MMAP_MAX
M_CHECK_ACTION
M_PERTURB
M_ARENA_TEST
M_ARENA_MAX
Specific definitions for the above can be found at http://www.makelinux.net/man/3/M/mallopt.
mal l o c_tri m
116
malloc_st at s
mal l o c_tri m is a library call that requests the allocator return any unused memory back to the
operating system. This is normally automatic when an object is freed. However, in some cases when
freeing small objects, g l i bc might not immediately release the memory back to the operating system.
It does this so that the free memory can be used to satisfy upcoming memory allocation requests as it
is expensive to allocate from and release memory back to the operating system.
mal l o c_stats
mal l o c_stats is used to dump information about the allocator's internal state to std err. Using
mal l i nfo is similar to this, but it places the state into a structure instead.
Further Information
More information on mal l o pt can be found at http://www.makelinux.net/man/3/M/mallopt and
http://www.gnu.org/software/libc/manual/html_node/Malloc-Tunable-Parameters.html.
117
Red Hat Ent erprise Linux 7 Developer G uide
Revision History
R evisio n 1- 8
Build for 7.1 GA release.
T h u Feb 19 2015
R o b ert K rát ký
R evisio n 1- 6
Fri D ec 06 2014
Update to sort order on the Red Hat Customer Portal.
R o b ert K rát ký
R evisio n 1- 4
Build for 7.0 GA release.
R o b ert K rát ký
Wed N o v 11 2014
Index
A
AB I
- compatibility, ABI Compatibility
ad van t ag es
- Python pretty-printers
- debugging, Python Pretty-Printers
Ako n ad i
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
ap p licat io n b in ary in t erf ace ( see AB I)
arch it ect u re, K D E4
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
au t h o riz in g co mp ile servers f o r co n n ect io n
- SSL and certificate management
- SystemTap, Authorizing Compile Servers for Connection
au t o mat ic au t h o riz at io n
- SSL and certificate management
- SystemTap, Automatic Authorization
Au t o t o o ls
- compiling and building, Autotools
B
b ackt race
- tools
- GNU debugger, Simple GD B
B o o st
- libraries and runtime support, Boost
b o o st - d o c
118
Revision Hist ory
- Boost
- libraries and runtime support, Boost D ocumentation
b reakp o in t
- fundamentals
- GNU debugger, Simple GD B
b reakp o in t s ( co n d it io n al)
- GNU debugger, Conditional Breakpoints
b u ild - id
- compiling and building, build-id Unique Identification of Binaries
b u ild in g
- compiling and building, Compiling and Building
C
C + + St an d ard Lib rary, G N U
- libraries and runtime support, The GNU C++ Standard Library
C + + 0x, ad d ed su p p o rt f o r
- GNU C++ Standard Library
- libraries and runtime support, GNU C++ Standard Library Updates
C + + 11 ( see G N U C o mp iler C o llect io n )
C 11 ( see G N U C o mp iler C o llect io n )
cach eg rin d
- tools
- Valgrind, Valgrind Tools
callg rin d
- tools
- Valgrind, Valgrind Tools
cert if icat e man ag emen t
- SSL and certificate management
- SystemTap, SSL and Certificate Management
C o llab o rat in g , C o llab o rat in g
co mman d s
- fundamentals
- GNU debugger, Simple GD B
- profiling
- Valgrind, Valgrind Tools
- tools
- Performance Counters for Linux (PCL) and perf, Perf Tool Commands
co mmo n ly- u sed co mman d s
- Autotools
- compiling and building, Autotools
co mp at - g lib c
119
Red Hat Ent erprise Linux 7 Developer G uide
- libraries and runtime support, compat-glibc
co mp at ib ilit y
- GNU Compiler Collection, Language Compatibility, Compatibility Changes, Fortran
2003 Compatibility, Fortran 2008 Compatibility, Fortran 77 Compatibility, ABI
Compatibility, D ebugging Compatibility, Other Compatibility
- libraries and runtime support, Compatibility
co mp ile server
- SystemTap, SystemTap Compile Server
co mp ilin g an d b u ild in g
- Autotools, Autotools
- commonly-used commands, Autotools
- configuration script, Configuration Script
- documentation, Autotools D ocumentation
-
build-id, build-id Unique Identification of Binaries
distributed compiling, D istributed Compiling
GNU Compiler Collection, GNU Compiler Collection (GCC)
introduction, Compiling and Building
required packages, D istributed Compiling
C o n cu rren t Versio n s Syst em ( see C VS)
co n d it io n al b reakp o in t s
- GNU debugger, Conditional Breakpoints
co n f ig u rat io n scrip t
- Autotools
- compiling and building, Configuration Script
co n n ect io n au t h o riz at io n ( co mp ile servers)
- SSL and certificate management
- SystemTap, Authorizing Compile Servers for Connection
co n t in u e
- tools
- GNU debugger, Simple GD B
C VS
- Version control, Concurrent Versions System (CVS)
D
d eb u g f s f ile syst em
- profiling
- ftrace, ftrace
d eb u g g in g
- debuginfo-packages, Installing D ebuginfo Packages
- installation, Installing D ebuginfo Packages
- GNU debugger, GD B
- fundamental mechanisms, GD B
- GD B, GD B
- requirements, GD B
120
Revision Hist ory
- introduction, D ebugging
- Python pretty-printers, Python Pretty-Printers
- advantages, Python Pretty-Printers
- debugging output (formatted), Python Pretty-Printers
- documentation, Python Pretty-Printers
- pretty-printers, Python Pretty-Printers
- variable tracking at assignments (VTA), Variable Tracking at Assignments
d eb u g g in g a H ello Wo rld p ro g ram
- usage
- GNU debugger, Running GD B
d eb u g g in g o u t p u t ( f o rmat t ed )
- Python pretty-printers
- debugging, Python Pretty-Printers
d eb u g in f o - p ackag es
- debugging, Installing D ebuginfo Packages
d ist rib u t ed co mp ilin g
- compiling and building, D istributed Compiling
d o cu men t at io n
- Autotools
- compiling and building, Autotools D ocumentation
- Boost
- libraries and runtime support, Boost D ocumentation
- GNU C++ Standard Library
- libraries and runtime support, GNU C++ Standard Library D ocumentation
- GNU debugger, GD B D ocumentation
- Java
- libraries and runtime support, Java D ocumentation
- KD E D evelopment Framework
- libraries and runtime support, kdelibs D ocumentation
- OProfile
- profiling, OProfile D ocumentation
- Perl
- libraries and runtime support, Perl D ocumentation
- profiling
- ftrace, ftrace D ocumentation
- Python
- libraries and runtime support, Python D ocumentation
- Python pretty-printers
- debugging, Python Pretty-Printers
- Qt
- libraries and runtime support, Qt Library D ocumentation
121
Red Hat Ent erprise Linux 7 Developer G uide
- Ruby
- libraries and runtime support, Ruby D ocumentation
- SystemTap
- profiling, SystemTap D ocumentation
- Valgrind
- profiling, Valgrind D ocumentation
D o cu men t at io n , Writ in g D o cu men t at io n
- D oxygen, D oxygen
- D ocment sources, D ocumenting the Sources
- Getting Started, Getting Started
- Resources, Resources
- Running D oxygen, Running D oxygen
- Supported output and languages, D oxygen Supported Output and
Languages
D o xyg en
- D ocumentation, D oxygen
- document sources, D ocumenting the Sources
- Getting Started, Getting Started
- Resources, Resources
- Running D oxygen, Running D oxygen
- Supported output and languages, D oxygen Supported Output and
Languages
E
execu t io n ( f o rked )
- GNU debugger, Forked Execution
F
f in ish
- tools
- GNU debugger, Simple GD B
f o rked execu t io n
- GNU debugger, Forked Execution
f o rmat t ed d eb u g g in g o u t p u t
- Python pretty-printers
- debugging, Python Pretty-Printers
f ramewo rk ( f t race)
- profiling
- ftrace, ftrace
f t race
- profiling, ftrace
- debugfs file system, ftrace
- documentation, ftrace D ocumentation
- framework (ftrace), ftrace
- usage, Using ftrace
f u n ct io n t racer
122
Revision Hist ory
- profiling
- ftrace, ftrace
f u n d amen t al co mman d s
- fundamentals
- GNU debugger, Simple GD B
f u n d amen t al mech an isms
- GNU debugger
- debugging, GD B
f u n d amen t als
- GNU debugger, Simple GD B
G
g cc
- GNU Compiler Collection
- compiling and building, GNU Compiler Collection (GCC)
G DB
- GNU debugger
- debugging, GD B
G it
-
configuration, Installing and Configuring Git
documentation, Additional Resources
installation, Installing and Configuring Git
overview, Git
usage, Creating a New Repository
G N U C + + St an d ard Lib rary
- libraries and runtime support, The GNU C++ Standard Library
G N U C o mp iler C o llect io n
- compatibility, Language Compatibility, Compatibility Changes, Fortran 2003
Compatibility, Fortran 2008 Compatibility, Fortran 77 Compatibility, ABI Compatibility,
D ebugging Compatibility, Other Compatibility
- compiling and building, GNU Compiler Collection (GCC)
- features, Status and Features, New Features, Fortran 2003 Features, Fortran 2008
Features
G N U d eb u g g er
- conditional breakpoints, Conditional Breakpoints
- debugging, GD B
- documentation, GD B D ocumentation
- execution (forked), Forked Execution
- forked execution, Forked Execution
- fundamentals, Simple GD B
- breakpoint, Simple GD B
- commands, Simple GD B
- halting an executable, Simple GD B
- inspecting the state of an executable, Simple GD B
- starting an executable, Simple GD B
- interfaces (CLI and machine), Alternative User Interfaces for GD B
123
Red Hat Ent erprise Linux 7 Developer G uide
- thread and threaded debugging, D ebugging Individual Threads
- tools, Simple GD B
- backtrace, Simple GD B
- continue, Simple GD B
- finish, Simple GD B
- help, Simple GD B
- list, Simple GD B
- next, Simple GD B
- print, Simple GD B
- quit, Simple GD B
- step, Simple GD B
- usage, Running GD B
- debugging a Hello World program, Running GD B
- variations and environments, Alternative User Interfaces for GD B
H
h alt in g an execu t ab le
- fundamentals
- GNU debugger, Simple GD B
h elg rin d
- tools
- Valgrind, Valgrind Tools
h elp
- tools
- GNU debugger, Simple GD B
h o st ( co mp ile server h o st )
- compile server
- SystemTap, SystemTap Compile Server
I
in sp ect in g t h e st at e o f an execu t ab le
- fundamentals
- GNU debugger, Simple GD B
in st allat io n
- debuginfo-packages
- debugging, Installing D ebuginfo Packages
in t erf aces ( C LI an d mach in e)
- GNU debugger, Alternative User Interfaces for GD B
in t ro d u ct io n
- compiling and building, Compiling and Building
- debugging, D ebugging
- libraries and runtime support, Libraries and Runtime Support
- profiling, Monitoring Performance
- SystemTap, SystemTap
ISO 14 4 82 St an d ard C + + lib rary
- GNU C++ Standard Library
124
Revision Hist ory
- libraries and runtime support, The GNU C++ Standard Library
ISO C + + T R 1 elemen t s, ad d ed su p p o rt f o r
- GNU C++ Standard Library
- libraries and runtime support, GNU C++ Standard Library Updates
J
Java
- libraries and runtime support, Java
K
K D E D evelo p men t Framewo rk
- libraries and runtime support, KD E D evelopment Framework
K D E4 arch it ect u re
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
kd elib s- d evel
- KD E D evelopment Framework
- libraries and runtime support, KD E D evelopment Framework
kern el in f o rmat io n p ackag es
- profiling
- SystemTap, SystemTap
K H T ML
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
K IO
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
K JS
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
K N ewSt u f f 2
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
K XMLG U I
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
L
lib raries
- runtime support, Libraries and Runtime Support
lib raries an d ru n t ime su p p o rt
- Boost, Boost
- boost-doc, Boost D ocumentation
- documentation, Boost D ocumentation
125
Red Hat Ent erprise Linux 7 Developer G uide
-
message passing interface (MPI), Boost
meta-package, Boost
MPICH2, Boost
new libraries, Boost Updates
Open MPI, Boost
sub-packages, Boost
updates, Boost Updates
C++ Standard Library, GNU, The GNU C++ Standard Library
compat-glibc, compat-glibc
compatibility, Compatibility
GNU C++ Standard Library, The GNU C++ Standard Library
- C++0x, added support for, GNU C++ Standard Library Updates
- documentation, GNU C++ Standard Library D ocumentation
- ISO 14482 Standard C++ library, The GNU C++ Standard Library
- ISO C++ TR1 elements, added support for, GNU C++ Standard Library
Updates
- libstdc++-devel, The GNU C++ Standard Library
- libstdc++-docs, GNU C++ Standard Library D ocumentation
- Standard Template Library, The GNU C++ Standard Library
- updates, GNU C++ Standard Library Updates
- introduction, Libraries and Runtime Support
- Java, Java
- documentation, Java D ocumentation
- KD E D evelopment Framework, KD E D evelopment Framework
- Akonadi, KD E4 Architecture
- documentation, kdelibs D ocumentation
- KD E4 architecture, KD E4 Architecture
- kdelibs-devel, KD E D evelopment Framework
- KHTML, KD E4 Architecture
- KIO, KD E4 Architecture
- KJS, KD E4 Architecture
- KNewStuff2, KD E4 Architecture
- KXMLGUI, KD E4 Architecture
- Phonon, KD E4 Architecture
- Plasma, KD E4 Architecture
- Solid, KD E4 Architecture
- Sonnet, KD E4 Architecture
- Strigi, KD E4 Architecture
- Telepathy, KD E4 Architecture
- libstdc++, The GNU C++ Standard Library
- Perl, Perl
- documentation, Perl D ocumentation
- module installation, Installation
- updates, Perl Updates
- Python, Python
- documentation, Python D ocumentation
- updates, Python Updates
- Qt, Qt
-
126
documentation, Qt Library D ocumentation
meta object compiler (MOC), Qt
Qt Creator, Qt Creator
qt-doc, Qt Library D ocumentation
Revision Hist ory
- updates, Qt Updates
- widget toolkit, Qt
- Ruby, Ruby
- documentation, Ruby D ocumentation
- ruby-devel, Ruby
Lib rary an d R u n t ime D et ails
- NSS Shared D atabases, NSS Shared D atabases
- Backwards Compatibility, Backwards Compatibility
- D ocumentation, NSS Shared D atabases D ocumentation
lib st d c+ +
- libraries and runtime support, The GNU C++ Standard Library
lib st d c+ + - d evel
- GNU C++ Standard Library
- libraries and runtime support, The GNU C++ Standard Library
lib st d c+ + - d o cs
- GNU C++ Standard Library
- libraries and runtime support, GNU C++ Standard Library D ocumentation
list
- tools
- GNU debugger, Simple GD B
- Performance Counters for Linux (PCL) and perf, Perf Tool Commands
M
mach in e in t erf ace
- GNU debugger, Alternative User Interfaces for GD B
mallo p t , mallo p t
massif
- tools
- Valgrind, Valgrind Tools
mech an isms
- GNU debugger
- debugging, GD B
memch eck
- tools
- Valgrind, Valgrind Tools
messag e p assin g in t erf ace ( MPI)
- Boost
- libraries and runtime support, Boost
met a o b ject co mp iler ( MO C )
- Qt
- libraries and runtime support, Qt
met a- p ackag e
127
Red Hat Ent erprise Linux 7 Developer G uide
- Boost
- libraries and runtime support, Boost
mo d u le in st allat io n
- Perl
- libraries and runtime support, Installation
mo d u le sig n in g ( co mp ile server au t h o riz at io n )
- SSL and certificate management
- SystemTap, Authorizing Compile Servers for Module Signing (for
Unprivileged Users)
MPIC H 2
- Boost
- libraries and runtime support, Boost
N
n ew ext en sio n s
- GNU C++ Standard Library
- libraries and runtime support, GNU C++ Standard Library Updates
n ew lib raries
- Boost
- libraries and runtime support, Boost Updates
n ext
- tools
- GNU debugger, Simple GD B
N SS Sh ared D at ag b ases
- Library and Runtime D etails, NSS Shared D atabases
- Backwards Compatibility, Backwards Compatibility
- D ocumentation, NSS Shared D atabases D ocumentation
O
o p an n o t at e
- tools
- OProfile, OProfile Tools
o p arch ive
- tools
- OProfile, OProfile Tools
o p co n t ro l
- tools
- OProfile, OProfile Tools
O p en MPI
- Boost
- libraries and runtime support, Boost
o p erf
- tools
- OProfile, OProfile Tools
128
Revision Hist ory
o p g p ro f
- tools
- OProfile, OProfile Tools
o p rep o rt
- tools
- OProfile, OProfile Tools
O Pro f ile
- profiling, OProfile
- documentation, OProfile D ocumentation
- usage, Using OProfile
- tools, OProfile Tools
- opannotate, OProfile Tools
- oparchive, OProfile Tools
- opcontrol, OProfile Tools
- operf, OProfile Tools
- opgprof, OProfile Tools
- opreport, OProfile Tools
o p ro f iled
- OProfile
- profiling, OProfile
P
p erf
- profiling
- Performance Counters for Linux (PCL) and perf, Performance Counters for
Linux (PCL) Tools and perf
- usage
- Performance Counters for Linux (PCL) and perf, Using Perf
Perf o rman ce C o u n t ers f o r Lin u x ( PC L) an d p erf
- profiling, Performance Counters for Linux (PCL) Tools and perf
- subsystem (PCL), Performance Counters for Linux (PCL) Tools and perf
- tools, Perf Tool Commands
- commands, Perf Tool Commands
- list, Perf Tool Commands
- record, Perf Tool Commands
- report, Perf Tool Commands
- stat, Perf Tool Commands
- usage, Using Perf
- perf, Using Perf
Perl
- libraries and runtime support, Perl
Ph o n o n
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
Plasma
129
Red Hat Ent erprise Linux 7 Developer G uide
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
p ret t y- p rin t ers
- Python pretty-printers
- debugging, Python Pretty-Printers
p rin t
- tools
- GNU debugger, Simple GD B
p ro f ilin g
-
conflict between perf and oprofile, Using OProfile, Using Perf
ftrace, ftrace
introduction, Monitoring Performance
OProfile, OProfile
- oprofiled, OProfile
- Performance Counters for Linux (PCL) and perf, Performance Counters for Linux
(PCL) Tools and perf
- SystemTap, SystemTap
- D ynInst, D ynInst with SystemTap 2.0
- Valgrind, Valgrind
Pyt h o n
- libraries and runtime support, Python
Pyt h o n p ret t y- p rin t ers
- debugging, Python Pretty-Printers
Q
Qt
- libraries and runtime support, Qt
Q t C reat o r
- Qt
- libraries and runtime support, Qt Creator
qt-doc
- Qt
- libraries and runtime support, Qt Library D ocumentation
q u it
- tools
- GNU debugger, Simple GD B
R
reco rd
- tools
- Performance Counters for Linux (PCL) and perf, Perf Tool Commands
rep o rt
- tools
- Performance Counters for Linux (PCL) and perf, Perf Tool Commands
130
Revision Hist ory
req u ired p ackag es
- compiling and building, D istributed Compiling
- profiling
- SystemTap, SystemTap
req u iremen t s
- GNU debugger
- debugging, GD B
Ruby
- libraries and runtime support, Ruby
ru b y- d evel
- Ruby
- libraries and runtime support, Ruby
ru n t ime su p p o rt
- libraries, Libraries and Runtime Support
S
scrip t s ( Syst emT ap scrip t s)
- profiling
- SystemTap, SystemTap
sig n ed mo d u les
- SSL and certificate management
- SystemTap, Authorizing Compile Servers for Module Signing (for
Unprivileged Users)
- unprivileged user support
- SystemTap, SystemTap Support for Unprivileged Users
So lid
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
So n n et
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
SSL an d cert if icat e man ag emen t
- SystemTap, SSL and Certificate Management
St an d ard T emp lat e Lib rary
- GNU C++ Standard Library
- libraries and runtime support, The GNU C++ Standard Library
st art in g an execu t ab le
- fundamentals
- GNU debugger, Simple GD B
st at
- tools
- Performance Counters for Linux (PCL) and perf, Perf Tool Commands
131
Red Hat Ent erprise Linux 7 Developer G uide
st ep
- tools
- GNU debugger, Simple GD B
St rig i
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
su b - p ackag es
- Boost
- libraries and runtime support, Boost
su b syst em ( PC L)
- profiling
- Performance Counters for Linux (PCL) and perf, Performance Counters for
Linux (PCL) Tools and perf
Syst emT ap
- compile server, SystemTap Compile Server
- host (compile server host), SystemTap Compile Server
- profiling, SystemTap
- documentation, SystemTap D ocumentation
- D ynInst, D ynInst with SystemTap 2.0
- introduction, SystemTap
- kernel information packages, SystemTap
- required packages, SystemTap
- scripts (SystemTap scripts), SystemTap
- SSL and certificate management, SSL and Certificate Management
- automatic authorization, Automatic Authorization
- connection authorization (compile servers), Authorizing Compile Servers
for Connection
- module signing (compile server authorization), Authorizing Compile
Servers for Module Signing (for Unprivileged Users)
- unprivileged user support, SystemTap Support for Unprivileged Users
- signed modules, SystemTap Support for Unprivileged Users
T
T elep at h y
- KD E D evelopment Framework
- libraries and runtime support, KD E4 Architecture
t h read an d t h read ed d eb u g g in g
- GNU debugger, D ebugging Individual Threads
t o o ls
-
GNU debugger, Simple GD B
OProfile, OProfile Tools
Performance Counters for Linux (PCL) and perf, Perf Tool Commands
profiling
- Valgrind, Valgrind Tools
- Valgrind, Valgrind Tools
132
Revision Hist ory
U
u n p rivileg ed u ser su p p o rt
- SystemTap, SystemTap Support for Unprivileged Users
u n p rivileg ed u sers
- unprivileged user support
- SystemTap, SystemTap Support for Unprivileged Users
u p d at es
- Boost
- libraries and runtime support, Boost Updates
- GNU C++ Standard Library
- libraries and runtime support, GNU C++ Standard Library Updates
- Perl
- libraries and runtime support, Perl Updates
- Python
- libraries and runtime support, Python Updates
- Qt
- libraries and runtime support, Qt Updates
u sag e
- GNU debugger, Running GD B
- fundamentals, Simple GD B
- Performance Counters for Linux (PCL) and perf, Using Perf
- profiling
- ftrace, Using ftrace
- OProfile, Using OProfile
- Valgrind
- profiling, Using Valgrind
V
Valg rin d
- profiling, Valgrind
- commands, Valgrind Tools
- documentation, Valgrind D ocumentation
- tools, Valgrind Tools
- usage, Using Valgrind
- tools
-
cachegrind, Valgrind Tools
callgrind, Valgrind Tools
helgrind, Valgrind Tools
massif, Valgrind Tools
memcheck, Valgrind Tools
variab le t rackin g at assig n men t s ( VT A)
- debugging, Variable Tracking at Assignments
variat io n s an d en viro n men t s
- GNU debugger, Alternative User Interfaces for GD B
133
Red Hat Ent erprise Linux 7 Developer G uide
Versio n co n t ro l ( see C o llab o rat in g )
W
wid g et t o o lkit
- Qt
- libraries and runtime support, Qt
134