Red Hat Enterprise Linux 7 Red Hat Enterprise Linux Series Operating System Development Platform Developer Guide
PDF
Dokument
Reklaam
Reklaam
Red Hat Enterprise Linux 7 Developer Guide An introduction to application development tools in Red Hat Enterprise Linux 7 Red Hat Enterprise Linux 7 Developer Guide An introduction to application development tools in Red Hat Enterprise Linux 7 Edited by 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 14 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. . . . . . . . . . Preface . .hapt C . . . .er . .1. .. Collaborat . . . . . . . . . ing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. . . . . . . . . . 1.1. Co nc urrent Vers io ns Sys tem (CVS) 4 1.2. Ap ac he Sub vers io n (SVN) 11 1.3. G it 18 . .hapt C . . . .er . .2. .. Libraries . . . . . . . . and . . . .Runt . . . . ime . . . .Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 4. . . . . . . . . . 2 .1. Vers io n Info rmatio n 24 2 .2. Co mp atib ility 25 2 .3. Lib rary and Runtime Details 26 . .hapt C . . . .er . .3. . . Compiling . . . . . . . . . .and . . . .Building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 ........... 3 .1. G NU Co mp iler Co llec tio n (G CC) 53 3 .2. Dis trib uted Co mp iling 77 3 .3. Auto to o ls 3 .4. Ec lip s e Built-in Sp ec file Ed ito r 3 .5. CDT in Ec lip s e 77 79 79 3 .6 . b uild -id Uniq ue Id entific atio n o f Binaries 3 .7. So ftware Co llec tio ns and s c l-utils 80 81 . .hapt C . . . .er . .4. .. Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8. 3. . . . . . . . . . 4 .1. ELF Exec utab le Binaries 4 .2. Ins talling Deb ug info Pac kag es 83 84 4 .3. G DB 4 .4. Variab le Trac king at As s ig nments 4 .5. Pytho n Pretty-Printers 87 99 99 4 .6 . Deb ug g ing C/C+ + Ap p lic atio ns with Ec lip s e 10 2 . .hapt C . . . .er . .5. . .Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.0. 4. . . . . . . . . . 5 .1. Valg rind 10 4 5 .2. 5 .3. 5 .4. 5 .5. O Pro file Sys temTap Perfo rmanc e Co unters fo r Linux (PCL) To o ls and p erf ftrac e 10 7 110 114 117 . .hapt C . . . .er . .6. .. Red . . . . Hat . . . .Developer . . . . . . . . . T. oolset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.1. 9. . . . . . . . . . 6 .1. Red Hat Develo p er To o ls et Features 119 6 .2. Platfo rm Co mp atib ility 6 .3. Ad d itio nal Res o urc es 120 120 . .hapt C . . . .er . .7. .. Red . . . . Hat . . . .Soft . . . .ware . . . . Collect . . . . . . ions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.2. 2. . . . . . . . . . 7 .1. What is Red Hat So ftware Co llec tio ns ? 122 7 .2. What Do es Red Hat So ftware Co llec tio ns O ffer? 122 7 .3. Whic h Platfo rms Are Sup p o rted ? 7 .4. Ho w to Us e Red Hat So ftware Co llec tio ns ? 7 .5. Ho w to Dep lo y Ap p lic atio ns That Us e Red Hat So ftware Co llec tio ns ? 7 .6 . Ad d itio nal Res o urc es 125 125 126 126 . .hapt C . . . .er . .8. .. Document . . . . . . . . . at . . ion ...T . .ools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.2. 7. . . . . . . . . . 8 .1. Pub lic an 8 .2. Do xyg en 127 132 .Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.4. 0. . . . . . . . . . A .1. mallo p t 140 1 Red Hat Ent erprise Linux 7 Developer G uide A .1. mallo p t 140 . . . . . . . .rim malloc_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.4. 0. . . . . . . . . . . . . . . . . . .at malloc_st . .s. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.4. 1. . . . . . . . . . . . . . her Furt . . . Informat . . . . . . . .ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.4. 1. . . . . . . . . . . . . . . . . . .Hist Revision . . . ory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.4. 2. . . . . . . . . . I.ndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.4. 2. . . . . . . . . . 2 Preface Preface This book describes the some of the more commonly-used programming resources in Red Hat Enterprise Linux 7. Each phase of the application development process is described as a separate chapter, enumerating tools that accomplish different tasks for that particular phase. Note that this is not a comprehensive listing of all available development tools in Red Hat Enterprise Linux 7. In addition, each section herein does not contain detailed documentation of each tool. Rather, this book provides a brief overview of each tool, with a short description of updates to the tool in Red Hat Enterprise Linux 7 and (more importantly) with references to more detailed information. 3 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 6 supports three of the most popular open source revision control systems: CVS, SVN, and Git. The tools for these revision control systems provide access to a wide range of publicly available open source code, as well as the capability to set up individual internal code repositories. The following section provides a brief overview and references to relevant documentation for each tool. 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 Revision Control System (RCS), and 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 CVS client, a CVS server, and other related tools to the system. Se t t ing Up t he De fault Edit o r When using CVS 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: . ~ /. 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 CVS client to use Emacs as a text editor, type: 4 Chapt er 1 . Collaborat ing ~]$ echo "expo rt C VSED IT O R = emacs" >> ~ /. bashrc ~]$ . ~ /. 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 in 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 Imagine that the directory with your project has the following contents: 5 Red Hat Ent erprise Linux 7 Developer G uide ~]$ l s mypro ject AUTHORS doc INSTALL LICENSE Makefile README src TODO Also imagine that you have an empty CVS repository in ~ /cvs/. To import the project under pro ject in this repository with vendor tag myco mpany and release tag i ni t, 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 a 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 Imagine that you have a CVS repository in ~ /cvs/ 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 Adding a File 6 Chapt er 1 . Collaborat ing To add an existing file to a CVS repository and put it under revision control, change to the directory with its working copy 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 Imagine 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 its working copy 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 Imagine 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: 7 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. However, if you are only interested in what has changed in your working copy, you can 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 Imagine 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. If you are only interested in changes to a particular file, supply the file name on the command line. 8 Chapt er 1 . Collaborat ing Examp le 1.8. Viewin g ch an g es t o a wo rkin g co p y Imagine 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 its working copy 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 determine 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 Imagine 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 already is 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 commit -m "Updated the makefile." cvs commit: Examining . cvs commit: Examining doc 9 Red Hat Ent erprise Linux 7 Developer G uide ... 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 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 Imagine 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 Also imagine that somebody recently added C hang eLo g to the repository, removed the T O D O file from it, 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 cvs(1) — The manual page for the cvs client program provides detailed information on its usage. 10 Chapt er 1 . Collaborat ing 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 Concurrent Versions System (CVS), preserves the same development model, and addresses problems often encountered with CVS. 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 Subversion client, a Subversion server, and other related tools to the system. Se t t ing Up t he De fault Edit o r When using Subversion on the command line, certain commands such as svn i mpo rt or svn co 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: . ~ /. 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 Subversion 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 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 11 Red Hat Ent erprise Linux 7 Developer G uide 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 a 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 Imagine that the directory with your project has the following contents: ~]$ l s mypro ject AUTHORS doc INSTALL LICENSE Makefile README src TODO Also imagine that you have an empty Subversion repository in ~ /svn/ (in this example, /ho me/jo hn/svn/). To import the project under pro ject/trunk in 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 Adding project/doc/index.html Adding project/INSTALL Adding project/src ... 12 Chapt er 1 . Collaborat ing 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 a project in it. Note that svn_repository is a 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 Imagine 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 a 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 its working copy 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 Imagine 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 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: 13 Red Hat Ent erprise Linux 7 Developer G uide 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 its working copy 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 Imagine 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 its working copy and run the following command: svn d el ete file… Similarly, to remove a directory and all files that are in it, type: 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” . 14 Chapt er 1 . Collaborat ing Examp le 1.17. D elet in g a f ile f ro m a Su b versio n rep o sit o ry Imagine 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 SVN 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 (A for a file that is scheduled for addition, D for a file that is scheduled for removal, M for a file that contains local changes, C for a file with unresolved conflicts, ? for a file that 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 Imagine 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 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 15 Red Hat Ent erprise Linux 7 Developer G uide A M + COPYING 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. If you are only interested in 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 Imagine 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)" \ 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 its working copy 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 determine which editor to start, see Section 1.2.1, “ Installing and Configuring Subversion” . 16 Chapt er 1 . Collaborat ing 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 Imagine 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 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. 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 Imagine 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 Also imagine 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. 17 Red Hat Ent erprise Linux 7 Developer G uide 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 on the svn usage. svnad mi n hel p — The output of the svnad mi n hel p command provides detailed information on the svn ad min usage. 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 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. 18 Chapt er 1 . Collaborat ing 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 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: 19 Red Hat Ent erprise Linux 7 Developer G uide 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. If you omit the -m option, this 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.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” . 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. 20 Chapt er 1 . Collaborat ing 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 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 21 Red Hat Ent erprise Linux 7 Developer G uide 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 CVS or Subversion, 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 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 22 Chapt er 1 . Collaborat ing 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. 23 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” 24 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. 25 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 26 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> 27 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. 28 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 29 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 30 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 31 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 32 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. 33 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. GNOME Power Manager The backend program of the GNOME power management infrastructure is g no me-po wer-manag er. It was introduced in Red Hat Enterprise Linux 5 and provides a complete and integrated solution to power management under the GNOME desktop environment. In Red Hat Enterprise Linux 6, the storage-handling parts of hal was replaced by ud i sks, and the l i bg no mepri nt stack was replaced by print support in g tk2. 2 .3.6 .1 . GNOME Po we r Manage m e nt Ve rsio n Guide This section will detail what versions of g no me-po wer-manag ement are shipped with the various Red Hat Enterprise Linux versions. In general, however, Red Hat Enterprise Linux 4 ships with GNOME 2.8, Red Hat Enterprise Linux 5 ships with GNOME 2.16, and Red Hat Enterprise Linux 6 ships with GNOME 2.28. T ab le 2.2. D eskt o p C o mp o n en t s C o mp ariso n R ed H at En t erp rise Lin u x Versio n G N O ME Po wer Man ag emen t D eskt o p C o mp o n en t s 4 5 6 hal 0.4.2 0.5.8 0.5.14 34 Chapt er 2 . Libraries and Runt ime Support R ed H at En t erp rise Lin u x Versio n G N O ME Po wer Man ag emen t D eskt o p C o mp o n en t s 4 5 6 udisks glib2 gtk2 gnome-vfs2 libglade2 libgnomecanvas gnome-desktop gnome-media gnome-python2 libgnome libgnomeui libgnomeprint22 libgnomeprintui22 gnome-session gnome-power-manager gnome-applets gnome-panel N/A 2.4.7 2.4.13 2.8.2 2.4.0 2.8.0 2.8.0 2.8.0 2.6.0 2.8.0 2.8.0 2.8.0 2.8.0 2.8.0 N/A 2.8.0 2.8.1 N/A 2.12.3 2.10.4 2.16.2 2.6.0 2.14.0 2.16.0 2.16.1 2.16.0 2.16.0 2.16.0 2.12.1 2.12.1 2.16.0 2.16.0 2.16.0 2.16.1 1.0.1 2.22.5 2.18.9 2.24.2 2.6.4 2.26.0 2.28.2 2.29.91 2.28.0 2.28.0 2.24.1 N/A N/A 2.28.0 2.28.3 2.28.0 2.30.2 2 .3.6 .2 . API Change s fo r glib There are a number of API changes for glib between versions. Versio n 2.4 t o Versio n 2.12 Some of the differences in glib between version 2.4 and 2.12 (or between Red Hat Enterprise Linux 4 and Red Hat Enterprise Linux 5) are: GOption (a command line option parser) GKeyFile (a key/ini file parser) GObject toggle references GMappedFile (a map wrapper) GSlice (a fast memory allocator) GBookmarkFile (a bookmark file parser) Base64 encoding support Native atomic ops on s390 Updated Unicode support to 5 Atomic reference counting for GObject Versio n 2.12 t o Versio n 2.22 35 Red Hat Ent erprise Linux 7 Developer G uide Some of the differences in glib between version 2.12 and 2.22 (or between Red Hat Enterprise Linux 5 and Red Hat Enterprise Linux 6) are: GSequence (a list data structure that is implemented as a balanced tree) GRegex (a PCRE regex wrapper) Support for monotonic clocks XD G user dirs support GIO (a VFS library to replace gnome-vfs) GChecksum (support for hash algorithms such as MD 5 and SHA-256) GTest (a test framework) Support for sockets and network IO in GIO GHashTable performance improvements GMarkup performance improvements D ocumentation for glib, including indexes of new and deprecated APIs, is shipped in the glib2-devel package. 2 .3.6 .3. API Change s fo r GTK+ There are a number of API changes for GTK+ between versions. Versio n 2.4 t o Versio n 2.10 Some of the differences in GTK+ between version 2.4 and 2.10 (or between Red Hat Enterprise Linux 4 and Red Hat Enterprise Linux 5) are: GtkIconView GtkAboutD ialog GtkCellView GtkFileChooserButton GtkMenuToolButton GtkAssistant GtkLinkButton GtkRecentChooser GtkCellRendererCombo GtkCellRendererProgress GtkCellRendererAccel GtkCellRendererSpin GtkStatusIcon Printing Support 36 Chapt er 2 . Libraries and Runt ime Support Notebook tab D ND support Ellipsisation support in labels, progressbars and treeviews Support rotated text Improved themability Versio n 2.10 t o Versio n 2.18 Some of the differences in GTK+ between version 2.10 and 2.18 (or between Red Hat Enterprise Linux 4 and Red Hat Enterprise Linux 5) are: GtkScaleButton GtkVolumeButton GtkInfoBar GtkBuilder to replace libglade New tooltips API GtkMountOperation gtk_show_uri Scale marks Links in labels Support runtime font configuration changes Use GIO D ocumentation for GTK+, including indexes of new and deprecated APIs, is shipped in the gtk2-devel package. 2.3.7. 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.7 .1 . Backwards Co m pat ibilit y 37 Red Hat Ent erprise Linux 7 Developer G uide 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 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.7 .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.8. 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.8 .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. 38 Chapt er 2 . Libraries and Runt ime Support 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.8 .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 exists. 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. 39 Red Hat Ent erprise Linux 7 Developer G uide FThe 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.8 .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.9. Java Red Hat Enterprise Linux 7 is constantly updated to ship the latest version of JD K. The 40 Chapt er 2 . Libraries and Runt ime Support 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.9 .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- 41 Red Hat Ent erprise Linux 7 Developer G uide 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.9 .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.10. 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 42 Chapt er 2 . Libraries and Runt ime Support 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.1 0 .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.1 0 .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. 43 Red Hat Ent erprise Linux 7 Developer G uide 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.11. 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 1 .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. 44 Chapt er 2 . Libraries and Runt ime Support 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 45 Red Hat Ent erprise Linux 7 Developer G uide 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 1 .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. 46 Chapt er 2 . Libraries and Runt ime Support 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 1 .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 47 Red Hat Ent erprise Linux 7 Developer G uide 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.12. 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. 48 Chapt er 2 . Libraries and Runt ime Support 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 2 .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 49 Red Hat Ent erprise Linux 7 Developer G uide 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.12.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() 50 Chapt er 2 . Libraries and Runt ime Support Note D uring development it is possible to call the plug-in directly on the command line for easier debugging. 2.3.12.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, 51 Red Hat Ent erprise Linux 7 Developer G uide 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 2 .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). 52 Chapt er 3. Compiling and Building 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. 53 Red Hat Ent erprise Linux 7 Developer G uide 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 54 Chapt er 3. Compiling and Building 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. 55 Red Hat Ent erprise Linux 7 Developer G uide 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 56 Chapt er 3. Compiling and Building 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” . 57 Red Hat Ent erprise Linux 7 Developer G uide 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. 58 Chapt er 3. Compiling and Building 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). 59 Red Hat Ent erprise Linux 7 Developer G uide 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 } 60 Chapt er 3. Compiling and Building 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. 61 Red Hat Ent erprise Linux 7 Developer G uide 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. 62 Chapt er 3. Compiling and Building 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. 63 Red Hat Ent erprise Linux 7 Developer G uide 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 64 Chapt er 3. Compiling and Building 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 65 Red Hat Ent erprise Linux 7 Developer G uide 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. 66 Chapt er 3. Compiling and Building 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 67 Red Hat Ent erprise Linux 7 Developer G uide 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 68 Chapt er 3. Compiling and Building 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. 69 Red Hat Ent erprise Linux 7 Developer G uide 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] 70 Chapt er 3. Compiling and Building 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. 71 Red Hat Ent erprise Linux 7 Developer G uide 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. 72 Chapt er 3. Compiling and Building 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. 73 Red Hat Ent erprise Linux 7 Developer G uide 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. 74 Chapt er 3. Compiling and Building 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. 75 Red Hat Ent erprise Linux 7 Developer G uide 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 76 Chapt er 3. Compiling and Building 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. Aut ot ools Plug-in for Eclipse 77 Red Hat Ent erprise Linux 7 Developer G uide The Autotools suite is also integrated into the Eclipse ID E via the Autotools plug-in. This plug-in provides an Eclipse graphical user interface for Autotools, which is suitable for most C/C++ projects. As of Red Hat Enterprise Linux 6, this plug-in only supports two templates for new C/C++ projects: An empty project A " hello world" application The empty project template is used when importing projects into the C/C++ D evelopment Toolkit that already support Autotools. Future updates to the Autotools plug-in will include additional graphical user interfaces (wizards, for example) for creating shared libraries and other complex scenarios. The Red Hat Enterprise Linux 6 version of the Autotools plug-in also does not integrate g i t or mercuri al into Eclipse. As such, Autotools projects that use g i t repositories will be required to be checked out outside the Eclipse workspace. Afterwards, you can specify the source location for such projects in Eclipse. Any repository manipulation (commits, or updates for example) are done via the command line. 3.3.2. Configurat ion Script 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.3. 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: 78 Chapt er 3. Compiling and Building 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 . Eclipse Built -in Specfile Edit or The Specfile Editor Plug-in for Eclipse provides useful features to help developers manage . spec files. This plug-in allows users to leverage several Eclipse GUI features in editing . spec files, such as auto-completion, highlighting, file hyperlinks, and folding. In addition, the Specfile Editor Plug-in also integrates the rpml i nt tool into the Eclipse interface. rpml i nt is a command line tool that helps developers detect common RPM package errors. The richer visualization offered by the Eclipse interface helps developers quickly detect, view, and correct mistakes reported by rpml i nt. The Specfile Editor for Eclipse is provided by the ecl i pse-rpm-ed i to r package. For more information about this plug-in, see Specfile Editor User Guide in the Eclipse H elp C o n t en t s. 3.5. CDT in Eclipse The CDT (C/C++ D evelopment Tools) is an Eclipse project that adds support for developing C and C++ projects with Eclipse. A user can create three forms of projects: 1. Managed Make Project 2. Standard Make Project 3. Autotools Project 3.5.1. Managed Make Project A managed make CD T project, sometimes referred to as a managed project, is one where the details regarding how to build the project are automated on behalf of the end-user. This differs from the standard make project, another common type of CD T C/C++ project, whereby a user supplies a Makefile that has the build details specified. For a managed project, start by selecting the type of managed project and the required toolchain. The project type is categorized based on the ultimate target of the project, such as an executable, a shared library, or a static library. Within these categories there may be templates for more specific projects (a hello world sample executable project, for example) where base source files are already provided. These can then be further customized. A toolchain is the set of tools used to generate the target. Typically, a Red Hat Enterprise Linux C/C++ developer would select the Linux GCC toolchain, which uses GCC for compiling, linking and assembly. Each tool in the toolchain is associated with one or more input types, typically specified by file suffix (for example, . c or . h or . S) or by file name. The tool will have parameter settings which can be customized by the developer, and each tool has an output type it creates. The tool also has a command or binary executable associated with it which may overlap among multiple tools. The C compiler and linker, for example, can both use GCC, but the compiler and linker tools will each have 79 Red Hat Ent erprise Linux 7 Developer G uide different input and output types, as well as different settings presented to the developer. Customize the tool settings through Pro p ert ies > C /C + + B u ild > Set t in g s. The toolchain itself can be customized in order to add, remove, or replace the used tools through Pro p ert ies > C /C + + B u ild > T o o lch ain Ed it o r. New files, such as source files or header files, can be added to the project once it has been created. The new files are added automatically to the build based on their input types and the tool settings. Navigate to Pro ject > C /C + + B u ild under the B u ild er Set t in g s tab in order for the managed make project to generate a Makefile which can be distributed with the project. This facilitates the use of the Makefile outside Eclipse. For more information regarding managed make C/C++ projects, see the C/C++ Development User Guide which can be found by navigating to C o n cep t s > Pro ject T yp es, T asks > C reat in g a Pro ject , or R ef eren ce > C /C + + Pro p ert ies > C /C + + Pro ject Pro p ert ies > C /C + + B u ild > Set t in g s Pag e. 3.5.2. St andard Make Project A standard make CD T project is a traditional C project with a Makefile that is manually managed by the developer. Unlike the managed make project, there are no tool settings to be used in determining rules in the Makefile. Manual additions to the Makefile are required when new source files that are to be processed as part of the build are added to the project. If a pattern rule exists which the new file name matches (for example, . c: . o , which states how to process a file with the suffix . c into a file with the suffix . o ), then this is not required. The default make target for building the project is al l , and the default make target for cleaning the project is cl ean. It is also possible for a user to build other targets found in the Makefile. To do this use the Makefile Target dialog to create targets to run or build existing ones. Creating pseudo-targets that group multiple targets found in the makefile in a particular order is also done through the Makefile Target dialog. To access the specific create and build dialogs, select Pro ject > Make T arg et > C reat e... and Pro ject > Make T arg et > B u ild ... respectively. Alternatively, right click on reso urces in the project and select the Make T arg et s option to access either C reat e... or B u ild ... For more information regarding standard make C/C++ projects, see the C/C++ D evelopment user guide, accessed through C o n cep t s > Pro ject T yp es, T asks > C reat in g a p ro ject or R ef eren ce > C /C + + Pro p ert ies > C /C + + Pro ject Pro p ert ies > C /C + + B u ild > Set t in g s Pag e. 3.5.3. Aut ot ools Project An autotools project is a lot like a standard make project however the Makefile is usually generated as part of a configuration step that occurs prior to building. See Section 3.3, “ Autotools” for details on Autotools and the Autotools plug-in for Eclipse which adds support for this type of project. Like a standard make project, make targets can be run with the Make Target dialog. 3.6. 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 80 Chapt er 3. Compiling and Building [...] Note section [ 3] '.note.gnu.build-id' of 36 bytes at offset 0x274: 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.7. 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 - 81 Red Hat Ent erprise Linux 7 Developer G uide 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 Beta 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 82 Chapt er 4 . Debugging 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 83 Red Hat Ent erprise Linux 7 Developer G uide 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. 84 Chapt er 4 . Debugging 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 85 Red Hat Ent erprise Linux 7 Developer G uide .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.6, “ 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, 86 Chapt er 4 . Debugging 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. 87 Red Hat Ent erprise Linux 7 Developer G uide 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. 88 Chapt er 4 . Debugging 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 ) 89 Red Hat Ent erprise Linux 7 Developer G uide 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: 90 Chapt er 4 . Debugging (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); } } 91 Red Hat Ent erprise Linux 7 Developer G uide 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 92 Chapt er 4 . Debugging 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 . 93 Red Hat Ent erprise Linux 7 Developer G uide ( 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; } 94 Chapt er 4 . Debugging 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. 95 Red Hat Ent erprise Linux 7 Developer G uide 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 } 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 96 thread2 Chapt er 4 . Debugging 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 97 Red Hat Ent erprise Linux 7 Developer G uide 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 98 Chapt er 4 . Debugging 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. 99 Red Hat Ent erprise Linux 7 Developer G uide 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 { 100 Chapt er 4 . Debugging 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': 101 Red Hat Ent erprise Linux 7 Developer G uide 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. Debugging C/C++ Applicat ions wit h Eclipse The Eclipse C/C++ development tools have excellent integration with the GNU D ebugger (GD B). These Eclipse plug-ins take advantage of the latest features available in GD B. Starting a debugging session for an application is similar to launching the application through either the context menu's D eb u g As → C /C + + Ap p licat io n , or using the R u n menu. The context menu can be accessed in one of three ways: Clicking the right mouse button with the cursor in the editor. On the application binary. On the project containing the binary of interest. If more than one binary can be launched, a dialog will be presented to choose which one. After the session has started, a prompt will appear to switch to the D ebug perspective, which contains the following collection of views related to debugging. C o n t ro l View The Control View is known as the D ebug view and has buttons for stepping over and into code selections. It also allows for thread process suspension. So u rce C o d e Ed it o r View 102 Chapt er 4 . Debugging The Source Code Editor View reflects which source code lines correspond to the position of the debugger in the execution. By pressing the Instructi o n Steppi ng Mo d e button in the D ebug view toolbar, it is possible to control the execution of the application by assembly instruction instead of by source code line. C o n so le View The Console View displays the input and output that is available. Finally, variable data and other information can been found in the corresponding views in the D ebug perspective. For further details, see the C o n cep t s → D eb u g , G et t in g St art ed → D eb u g g in g Pro ject s, and T asks → R u n n in g an d D eb u g g in g Pro ject s sections of the C/C++ Development User Guide in the Help Contents. 103 Red Hat Ent erprise Linux 7 Developer G uide Chapter 5. Profiling 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 104 Chapt er 5. Profiling 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.4, “ 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 Plug-in for Eclipse The Valg rin d plug-in for Eclipse integrates several Valg rin d tools into Eclipse. This allows Eclipse users to seamlessly include profiling capabilities into their workflow. At present, the Valg rin d plug-in for Eclipse supports three Valg rin d tools: Memch eck Massif C ach eg rin d 105 Red Hat Ent erprise Linux 7 Developer G uide To launch a Valg rin d profile run, navigate to R u n > Pro f ile. This will open the Pro f ile As dialog, from which you can select a tool for a profile run. Fig u re 5.1. Pro f ile As To configure each tool for a profile run, navigate to R u n > Pro f ile C o n f ig u rat io n . This will open the Pro f ile C o n f ig u rat io n menu. 106 Chapt er 5. Profiling Fig u re 5.2. Pro f ile C o n f ig u rat io n The Valg rin d plug-in for Eclipse is provided by the ecl i pse-val g ri nd package. For more information about this plug-in, see Valgrind Integration User Guide in the Eclipse H elp C o n t en t s. 5.1.4 . 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. 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 107 Red Hat Ent erprise Linux 7 Developer G uide 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. 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 108 Chapt er 5. Profiling 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 Tilera tilepro Tilera tile-gx IBM System z10 IBM System z196 Intel Ivy Bridge ARMv7 Cortex-A5 ARMv7 Cortex-A15 109 Red Hat Ent erprise Linux 7 Developer G uide 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 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 110 Chapt er 5. Profiling 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. 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 111 Red Hat Ent erprise Linux 7 Developer G uide 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 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 112 Chapt er 5. Profiling 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. 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 113 Red Hat Ent erprise Linux 7 Developer G uide 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. 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. 114 Chapt er 5. Profiling 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) ] 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. 115 Red Hat Ent erprise Linux 7 Developer G uide 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 44.48% pdfxmltex 6.01% make 0.95% perl 0.17% kernel-doc 0.05% xmllint 0.05% cc1 0.03% cp 0.01% xmlto 0.01% sh 0.01% docproc 0.01% ld 0.01% gcc 0.00% rm 116 Chapt er 5. Profiling 0.00% 0.00% 0.00% 0.00% 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 Symbol ...... [.] [.] [.] [.] [.] [.] valuePop [.] [.] 5.5. 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. 5.5.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: 117 Red Hat Ent erprise Linux 7 Developer G uide 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 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. 5.5.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. 118 Chapt er 6 . Red Hat Developer T oolset Chapter 6. Red Hat Developer Toolset Red Hat D eveloper Toolset is a Red Hat offering for developers on the Red Hat Enterprise Linux platform, and provides a complete set of development and performance analysis tools that can be installed and used on multiple versions of Red Hat Enterprise Linux. Executables built with the Red Hat D eveloper Toolset toolchain can then also be deployed and run on multiple versions of Red Hat Enterprise Linux. Red Hat D eveloper Toolset does not replace the default system tools and libraries provided with Red Hat Enterprise Linux 7 when installed on this platform. Instead, a parallel set of developer tools provides an alternative, newer version of those tools for optional use by developers. Applications and libraries provided by Red Hat D eveloper Toolset do not replace the Red Hat Enterprise Linux system versions, nor are they used in preference to the system versions. The default compiler and debugger, for example, remain those provided by the base Red Hat Enterprise Linux system. D evelopers can pick and choose at any time which version of the tool they would like to use by using the scl utility. For details on how to install the product and invoke the executables, see the Red Hat D eveloper Toolset 3.0 User Guide. 6.1. Red Hat Developer T oolset Feat ures In comparison with Red Hat Enterprise Linux 7, Red Hat D eveloper Toolset provides more recent versions of the Eclip se development environment, G N U C o mp iler C o llect io n (GCC), G N U D eb u g g er (GD B), and other development and performance analysis tools as listed in Table 6.1, “ Red Hat D eveloper Toolset Components” . These updated tools allow developers to develop applications while using experimental C++14 language features, the latest compiler optimizations, parallel programming with OpenMP 4.0, and improved debugging support. T ab le 6 .1. R ed H at D evelo p er T o o lset C o mp o n en t s N ame Versio n D escrip t io n Eclipse 4.4 An integrated development environment with a graphical user interface. [a] GCC binutils 4.9.1 2.24 elfutils 0.159 dwz 0.11 GD B 7.8 ltrace 0.7.91 strace 4.8 memstomp 0.1.5 SystemTap 2.5 A portable compiler suite with support for C, C++, and Fortran. A collection of binary tools and other utilities to inspect and manipulate object files and binaries. A collection of binary tools and other utilities to inspect and manipulate ELF files. A tool to optimize D WARF debugging information contained in ELF shared libraries and ELF executables for size. A command line debugger for programs written in C, C++, and Fortran. A debugging tool to display calls to dynamic libraries that a program makes. It can also monitor system calls executed by programs. A debugging tool to monitor system calls that a program uses and signals it receives. A debugging tool to identify calls to library functions with overlapping memory regions that are not allowed by various standards. A tracing and probing tool to monitor the activities of the entire system without the need to instrument, recompile, install, and reboot. 119 Red Hat Ent erprise Linux 7 Developer G uide N ame Versio n D escrip t io n Valgrind 3.9.0 OProfile 0.9.9 D yninst 8.2 An instrumentation framework and a number of tools to profile applications in order to detect memory errors, identify memory management problems, and report any use of improper arguments in system calls. A system-wide profiler that uses the performance monitoring hardware on the processor to retrieve information about the kernel and executables on the system. A library for instrumenting and working with user-space executables during their execution. [a] If yo u intend to d evelo p ap p lic atio ns fo r Red Hat JBo s s Mid d leware o r req uire s up p o rt fo r O p enShift To o ls , it is rec o mmend ed that yo u us e Red Hat JBo s s Develo p er Stud io . 6.2. Plat form Compat ibilit y Red Hat D eveloper Toolset 3.0 is available for Red Hat Enterprise Linux 6 and 7 for 64-bit Intel and AMD architectures. Figure 6.1, “ Red Hat D eveloper Toolset 3.0 Compatibility Matrix” illustrates the support for binaries built with Red Hat D eveloper Toolset on a certain version of Red Hat Enterprise Linux when those binaries are run on various other versions of this system. For ABI compatibility information, see the ABI Compatibility section of the Red Hat Developer Toolset 3.0 User Guide. Fig u re 6 .1. R ed H at D evelo p er T o o lset 3.0 C o mp at ib ilit y Mat rix 6.3. Addit ional Resources For more information about Red Hat D eveloper Toolset, see the resources listed below. Red Hat D eveloper Toolset 3.0 Release Notes — The Release Notes for Red Hat D eveloper Toolset 3.0 provide important information available at the time of its release. Read this book to learn about system requirements or known problems of the product. 120 Chapt er 6 . Red Hat Developer T oolset Red Hat D eveloper Toolset 3.0 User Guide — The User Guide for Red Hat D eveloper Toolset 3.0 provides an overview of the product, explains how to invoke and use the Red Hat D eveloper Toolset versions of the tools, and links to resources with more in-depth information. Read this book to learn how to obtain, install, and use Red Hat D eveloper Toolset on your system, or for a detailed list of changes in this product. 121 Red Hat Ent erprise Linux 7 Developer G uide Chapter 7. Red Hat Software Collections 7.1. What is Red Hat Soft ware Collect ions? For certain applications, more recent versions of some software components are often needed in order to use their latest features. Red Hat Software Collections is a Red Hat offering that provides a set of dynamic programming languages, database servers, and related packages that are either more recent than their equivalent versions included in the base Red Hat Enterprise Linux system, or are available for this system for the first time. D ynamic languages, database servers, and other tools distributed with Red Hat Software Collections do not replace the default system tools provided with Red Hat Enterprise Linux 7, nor are they used in preference to these tools. The default versions of Perl and Po st g reSQ L, for example, remain those provided by the base Red Hat Enterprise Linux system. Users can pick and choose at any time which version of the tool they would like to run by using the scl utility. With the notable exception of N o d e.js, all Red Hat Software Collections components are fully supported under Red Hat Enterprise Linux Subscription Level Agreements, are functionally complete, and are intended for production use. Red Hat D eveloper Toolset is now a part of Red Hat Software Collections, included as a separate Software Collection. For more information about Red Hat D eveloper Toolset, see the Red Hat D eveloper Toolset Release Notes and the Red Hat D eveloper Toolset User Guide. 7.2. What Does Red Hat Soft ware Collect ions Offer? Red Hat Software Collections 1.2 provides recent versions of the tools listed in Table 7.1, “ 7 Components” . T ab le 7.1. 7 C o mp o n en t s C o mp o n en t So f t ware C o llec D escrip t io n t io n R ed H at D evelo p er T o o lset 3.0 devtoolset-3 Perl 5.16 .3 perl516 122 Red Hat D eveloper Toolset is designed for developers on the Red Hat_Enterprise Linux platform. It provides current versions of the G N U C o mp iler C o llect io n , G N U D eb u g g er, Eclip se development platform, and other development, debugging, and performance monitoring tools. For a complete list of components, see the Red Hat D eveloper Toolset Components table in the Red Hat Developer Toolset User Guide. A release of Perl with a number of additional utilities, scripts, and database connectors for MySQL and PostgreSQL. This version provides a large number of new features and enhancements, including new debugging options, improved Unicode support, and better performance. Also, it adds p erl- D at eT ime and mo d _p erl, which is supported only with the httpd24 Software Collection package. Chapt er 7 . Red Hat Soft ware Collect ions C o mp o n en t So f t ware C o llec D escrip t io n t io n PH P 5.4 .16 php54 PH P 5.5.6 php55 Pyt h o n 2.7.5 python27 Pyt h o n 3.3.2 python33 R u b y 1.9 .3 [a] ruby193 R u b y 2.0.0 ruby200 Ruby on ror40 R ails 4 .0.2 [a] A release of PHP with PEAR 1.9 .4 and a number of additional extensions. PHP 5.4 provides a number of language and interface improvements. The APC , memcach e, and Z en d O Pcach e extensions are also included. A release of PHP with enhanced language features including better exception handling, generators, and Z en d O Pcach e. The memcach e and mo n g o d b extensions are also included. A release of Python 2.7 with a number of additional utilities. This Python version provides various new features and enhancements, including a new ordered dictionary type, faster I/O operations, and improved forward compatibility with Python 3. The python27 Software Collections contains the Python 2.7.5 interpreter, a set of extension libraries useful for programming web applications and mo d _wsg i (only supported with the httpd24 Software Collection), MySQL and PostgreSQL database connectors, and n u mp y and scip y. A release of Python 3 with a number of additional utilities. This Software Collection gives developers on Red Hat_Enterprise Linux access to Python 3 and allows them to benefit from various advantages and new features of this version. The python33 Software Collection contains Python 3.3.2 interpreter, a set of extension libraries useful for programming web applications and mo d _wsg i (only supported with the httpd24 Software Collection), PostgreSQL database connector, and n u mp y and scip y. A release of Ruby 1.9.3 and R u b y o n R ails 3.2.8 with a large collection of Ruby gems. This Software Collection gives developers on Red Hat_Enterprise Linux access to Ruby 1.9, which provides a number of new features and enhancements, including improved Unicode support, enhanced threading, faster load times, and mo d _p assen g er, which is supported only with the httpd24 Software Collection package. A release of Ruby 2.0.0. This version provides substantial performance and reliability improvements and includes a number of new features and improved debugging capabilities, while maintaining source level backward compatibility with Ruby 1.9.3. A release of R u b y o n R ails 4 .0, a web application development framework written in the Ruby language. This version provides a number of new features and improvements and adds live streaming for persistent connections. This Software Collection is supported together with the ruby200 collection. 123 Red Hat Ent erprise Linux 7 Developer G uide C o mp o n en t So f t ware C o llec D escrip t io n t io n MariaD B 5.5.37 mariadb55 Mo n g o D B 2.4 .9 mongodb24 [b ] MySQ L 5.5.37 mysql55 Po st g reSQ L 9 .2.8 postgresql92 N o d e.js 0.10 [b ] [c ] nodejs010 n g in x 1.6 .1 nginx16 Ap ach e h t t p d 2.4 .6 httpd24 T h ermo st at 1.0.4 thermostat1 G it 1.9 .4 git19 D evAssist an t 0.9 .1 devassist09 124 A release of MariaD B, an alternative to MySQL for users of Red Hat_Enterprise Linux. MySQL is binary compatible with MariaD B and can be replaced with it without any data conversions. This version adds the PAM authentication plugin to MariaD B. A release of MongoD B, a cross-platform documentoriented database system classified as a NoSQL database. This Software Collection includes the mongo-java-driver package. A release of MySQL, which provides a number of new features and enhancements, including improved performance. A release of PostgreSQL, which provides a number of new features and enhancements, including cascading replication, native JSON support, improved scalability, and better performance. A release of Node.js with n p m 1.3.24 . This Software Collection gives users of Red Hat_Enterprise Linux access to this programming platform. A release of nginx, a web and proxy server with a focus on high concurrency, performance and low memory usage. This versions introduces a number of new features, including various SSL improvements, support for SPDY 3.1, cache revalidation with conditional requests, and authentication request module. A release of the Apache HTTP Server (httpd), including a high performance event-based processing model, enhanced SSL module and FastCGI support. The mo d _au t h _kerb module is also included. A release of Thermostat, a monitoring and instrumentation tool for the OpenJDK HotSpot JVM, with support for monitoring multiple JVM instances. This Software Collection depends on the mongodb24 component. A release of Git, a distributed revision control system with a peer-to-peer architecture. As opposed to centralized version control systems with a client-server model, Git ensures that each working copy of a Git repository is its exact copy with complete revision history. A release of D evAssistant, a tool designed to assist developers with creating and setting up basic projects in various programming languages, installing dependencies, setting up a development environment, and working with source control. D evAssistant supports the C, C++, Java, and Python programming languages but it is able to support working with any other language, framework, or tool due to its modular architecture. Chapt er 7 . Red Hat Soft ware Collect ions C o mp o n en t So f t ware C o llec D escrip t io n t io n Maven 3.0.5 maven30 A release of Maven, a software project management and comprehension tool used primarily for Java projects. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting, and documentation from a central piece of information. [a] A p art o f this So ftware Co llec tio n req uires a JavaSc rip t eng ine. The v8314 So ftware Co llec tio n inc lud ed in 7 p ro vid es the V8 JavaSc rip t eng ine and is s up p o rted o nly as the So ftware Co llec tio n' s d ep end enc y. [b ] This So ftware Co llec tio n als o req uires v8 31 4 . The v8314 So ftware Co llec tio n inc lud ed in 7 p ro vid es the V8 JavaSc rip t eng ine and is s up p o rted o nly as the So ftware Co llec tio n' s d ep end enc y. [c ] In 7, Node.js is inc lud ed as a Tec hno lo g y Preview. Fo r mo re info rmatio n ab o ut Red Hat Tec hno lo g y Previews , s ee http s ://ac c es s .red hat.c o m/s up p o rt/o ffering s /tec hp review/. 7.3. Which Plat forms Are Support ed? Red Hat Software Collections 1.2 is available for all supported releases of Red Hat Enterprise Linux 7 on AMD 64 and Intel 64 architectures. 7.4 . How t o Use Red Hat Soft ware Collect ions? To run an executable from a particular Software Collection, type the following command at a shell prompt: scl enabl e software_collection. . . ' command. . . ' Replace software_collection with a space-separated list of Software Collections you want to use and command with the command you want to run. For example, to execute a Perl program stored in a file named hel l o . pl with the Perl interpreter from the perl516 Software Collection, type: ~]$ scl enabl e perl 516 ' perl hel l o . pl ' Hello, World! To start a new shell session with executables from a selected Software Collection in preference to their Red Hat Enterprise Linux equivalents, type the following at a shell prompt: scl enabl e software_collection. . . bash Replace software_collection with a space-separated list of Software Collections you want to use. For example, to start a new shell session with the python27 and postgresql92 Software Collections as default, type: ~]$ scl enabl e pytho n27 po stg resq l 9 2 bash The list of Software Collections that are enabled in the current session is stored in the $X_SC LS environment variable, for instance: ~]$ echo $X_SC LS python27 postgresql92 125 Red Hat Ent erprise Linux 7 Developer G uide You can execute any command using the scl utility, causing it to be run with the executables from a selected Software Collection in preference to their possible Red Hat Enterprise Linux system equivalents. See Section 3.7, “ Software Collections and scl-utils” for more information on how to install and use this command line utility on your system. For a complete list of Software Collections that are distributed with Red Hat Software Collections, see Table 7.1, “ 7 Components” . For detailed instructions on how to use these Software Collections, see the Red Hat Software Collections 1.1 Release Notes. 7.5. How t o Deploy Applicat ions T hat Use Red Hat Soft ware Collect ions? In general, you can use one of the following two approaches to deploy an application that depends on a component from Red Hat Software Collections in production: install all required Software Collections and packages manually and then deploy your application, or create a new Software Collection for your application and specify all required Software Collections and other packages as dependencies. For more information on how to manually install individual Red Hat Software Collections components, see the Red Hat Software Collections 1.2 Release Notes. For a detailed explanation of how to create a custom Software Collection, read the Red Hat Developer Toolset Software Collections Guide. 7.6. Addit ional Resources Red Hat Software Collections 1.2 Release Notes — The Release Notes for Red Hat Software Collections 1.2 provides important information available at the time of its release. Read this book if you want to learn about system requirements or known problems of Red Hat Software Collections. Red Hat Software Collections 1.2 Packaging Guide — The Packaging Guide for Red Hat Software Collections 1.2 provides instructions on how to build custom Software Collections. 126 Chapt er 8 . Document at ion T ools Chapter 8. Documentation Tools Red Hat Enterprise Linux 7 has two documentation tools available to include documentation with a project. These are Pu b lican and D o xyg en . 8.1. Publican Publican a program is used to publish and process documentation through D ocBook XML. In the process of publishing books, it checks the XML to ensure it is valid and in a publishable standard. It is particularly useful for publishing the documentation accompanying a newly created application. 8.1.1. Commands Publican has a vast number of commands and actions available, all of which can be found in the -hel p or --man pages. The most common ones are: bui l d Converts the XML files into other formats more suitable for documentation (PD F, HTML, HTML-single, for example). create Creates a new book, including all the required files as discussed in Section 8.1.3, “ Files” . create_brand Creates a new brand, allowing all books to look the same, as discussed in Section 8.1.6, “ Brands” . packag e Packages the files of a book into an RPM ready to distribute. 8.1.2. Creat e a New Document Use the publ i can create command to create a new document including all the required files. There are a number of options available to append to the publ i can create. These are: --hel p Prints a list of accepted options for the publ i can create command. --name Doc_Name Set the name of the book. Keep in mind that the title must contain no spaces. --l ang Language_Code If this is not set, the default is en-US. The --l ang option sets the xml _l ang in the publ i can. cfg file and creates a directory with this name in the document directory. --versi o n version Set the version number of the product the book is about. 127 Red Hat Ent erprise Linux 7 Developer G uide --pro d uct Product_Name Set the name of the product the book is about. Keep in mind that this must contain no spaces. --brand brand Set the name of a brand to use to keep the look of the documents consistent. See --hel p for more options. Remember to change into the directory the book is to be created in before running publ i can create. This prevents the files and directories be added to the user's home directory. 8.1.3. Files When a book is made, a number of files are created in the book's directory. These files are required for the book to be built properly and should not be deleted. They are, however, required to be edited for links (such as chapters) to work, as well as to contain the correct information regarding authors and titles etc. These files are: publ i can. cfg This file configures the build options and always includes the parameters xml_lang (the language the book is in, en-US for example), type (the type of document, a book or a set, for example), and brand (the branding the document uses, found here: Section 8.1.6, “ Brands” . Red Hat, for example.). There are a number of optional parameters but these should be used cautiously as they can cause problems further on in areas like translation. A full list of these advanced parameters can be found in the Publican User Guide. The publ i can. cfg file is unlikely to be edited much beyond the initial creation. bo o k_i nfo . xml This file is the template of the book. It contains information such as the title, subtitle, author, publication number, and the book's ID number. It also contains the basic Publican information printed at the beginning of each publication with information on the notes, cautions, and warnings as well as a basic stylistic guide. This file will be edited often as every time a book is updated the publication number has to be incremented. Autho r_G ro up. xml This file is used to store information about the authors and contributors. Once initially set up it is unlikely further editing will be required unless a change of authorship occurs. C hapter. xml This file is an example of what the actual content will be. It is created as a place holder but unless it is linked in the Doc_Name.xml (below) it will not appear in the actual book. When writing content for the publication, new XML files are created, named appropriately (chpublican.xml, for example) and linked in D o c_Name. xml . When the book is built, the content of this file will form the content of the book. This specific file is unlikely to ever be edited but others like it will be edited constantly as content is changed, updated, added to or removed. Doc_Name. xml This file is the contents page of the publication. It contains a list of links to the various chapters a book is to contain. It will not actually be called 'D oc_Name' but will have whatever the title of the publication is in it's place (D eveloper_Guide.xml, for example). This 128 Chapt er 8 . Document at ion T ools will only be edited when new chapters are added, removed or rearranged. This must remain the same as Doc_Name. ent or the book will not build. Doc_Name. ent This file contains a list of local entities. By default YEAR is set to the current year and HOLDER has a reminder to place the copyright owner's name there. As with Doc_Name. xml , this file will not be called 'D oc_Name' but will be replaced with the title of the document (D eveloper_Guide.ent, for example). This is only likely to be edited once at the beginning of publication or if the copyright owner changes. This must remain the same as Doc_Name. xml or the book will not build. R evi si o n_Hi sto ry. xml When publ i can packag e is run, the first XML file containing a <revhi sto ry> tag is used to build the RPM revision history. 8 .1 .3.1 . Adding Me dia t o Do cum e nt at io n Occasionally it may become necessary to add various media to a document in order to illustrate what is being explained. Imag es The i mag es folder is created by publican in the document's directory. Store any images used in the document here. Then when entering an image into the document, link to the image inside the i mag es directory (. /i mag es/i mag e1. png , for example). C o d e Examp les As time passes and technology changes, a project's documentation will be required to be updated to reflect differences in code. To make this easier, create individual files for each code example in a preferred editor, then save them in a folder called extras in the document's directory. Then, when entering the code sample into the document, link to the file and the folder it is in. This way an example used in several places can be updated only once, and rather than search through a document looking for a specific item to change, all the code examples are located in the one place, saving time and effort. Arb it rary Files On occasion there may be a requirement for files not attached to the documentation to be bundled with the RPM (video tutorials, for example). Adding these files to a directory called fi l es in the publication's directory will allow them to be added to the RPM when the book is compiled. To link to any of these files, use the following XML: <xi:include parse="text" href="extras/fork/fork1.c" xmlns:xi="http://www.w3.org/2001/XInclude" /> 8.1.4 . Building a Document In the root directory, first run a test build to ensure that all the XML is correct and acceptable by typing publ i can bui l d --fo rmats= chosen_format --l ang s= chosen_language. For example, to build a document in US English and as a single HTML page, run publ i can bui l d -fo rmats= html -si ng l e --l ang s= en-US. Provided there are no errors the book will be built into 129 Red Hat Ent erprise Linux 7 Developer G uide the root directory where the pages can be viewed to see if it has the look required. It is recommended to do this regularly in order to make troubleshooting as easy as possible. Note When creating a build to test for any bugs in the XML code, sometimes it may be useful to use the --no val i d option. This skips over any cross-references and links that point to files or sections of the document that do not yet exist. Instead they are shown as three question marks (???). There are a number of different formats a document can be published in. These are: h t ml An ordinary HTML page with links to new pages for new chapters and sections. h t ml- sin g le One long HTML page where the links to new chapters and sections at the top of the page directing the user further down the page, rather than to new page. h t ml- d eskt o p One long HTML page where the links to new chapters and sections are in a panel on the left side of the document, directing the user further down the page, rather than to a new page. man A man page for Linux, UNIX, and other similar operating systems. pdf A PD F file. t est The XML is validated without actually creating a file for viewing. t xt A single text file. ep u b An e-book in EPUB format. eclip se An Eclipse help plug-in. 8.1.5. Packaging a Publicat ion Once the documentation is complete and can be built with no errors, run publ i can packag e -l ang = chosen_language. This will output SRPM packages to tmp/rpm in the document's directory, and binary RPM packages will go to tmp/rpm/no arch in the document's directory. By default, these packages are named productname-title-productnumber-[web]-language-editionpubsnumber.[build_target]. no arch. file_extension with the information for each of these sections coming from publ i can. cfg . 130 Chapt er 8 . Document at ion T ools 8.1.6. Brands Brands are used in a similar way as templates in that they create a level of consistency in appearance, with aspects like matching logos, images and color schemes, across a range of documents. This can be particularly useful when producing several books for the same application or the same bundle of applications. In order to create a new brand, it must have a name and a language. Run publ i can create_brand --name= brand --l ang = language_code. This will create a folder called publ i can-brand and place it in the publication's directory. This folder contains the following files: C O P Y ING Part of an SRPM package and containing the copyright license and details. d efaul ts. cfg Provides default values for the parameters that can be set in publ i can. cfg . Specifications from this file are applied first before applying those in the publ i can. cfg file. Therefore, values in the publ i can. cfg file override those in the d efaul ts. cfg file. It is best used for aspects that are routinely used throughout the documents but still allows writers to change settings. o verri d es. cfg Also provides values for the parameters that can be set in publ i can-brand . spec. Specifications from this file are applied last, thus overriding both the d efaul ts. cfg and the publ i can. cfg . It is best used for aspects the writers are not allowed to change. publ i can. cfg This file is similar to the publ i can. cfg file for a publication in that it configures basic information for the brand, such as version, release number and brand name. publ i can-brand . spec This file is used by the RPM Package Manager to package the publication into an RPM. R EAD ME Part of an SRPM package and providing a brief description of the package. A subdirectory, named by the language code, is also placed in this directory and contains the following files: Feed back. xml This is generated by default to allow readers to leave feedback. Customize it to contain the relevant contact details or a bug reporting process. Leg al _No ti ce. xml : Contains copyright information. Edit it to change the details of the chosen copyright license. Two more subdirectories are within this directory. The i mag es subdirectory contains a number of images of both raster (PNG) and vector (SVG) formats and serve as place holders for various navigation icons that can be changed by replacing the images. The css folder contains o verri d es. css, which sets the visual style for the brand, overriding those in co mmo n. css. 131 Red Hat Ent erprise Linux 7 Developer G uide In order to package the new brand ready for distribution, use the publ i can packag e command. By default this creates source RPM packages (SRPM Packages) but it can also create binary RPM packages using the option --bi nary. Packages are named publican-brand-versionrelease.[build_target].[no arch].file_extension with the required parameters taken from the publ i can. cfg file. Note SRPM packages have the file extension .src.rpm while binary RPM packages have the file extension .rpm Binary RPM packages include [bui l d _targ et]. no arch before the file extension, where [bui l d _targ et] represents the operating system and version that the package is built for as set by the o s_ver parameter in the publ i can. cfg file. The noarch element specifies that the package can be installed on any system, regardless of the system architecture. 8.1.7. Building a Websit e Publican can also build websites to manage documentation. This is mostly useful when only one person is maintaining the documentation, but where a team is working on the documentation Publican can generate RPM packages of documentation to install on a web server. The website created consists of a homepage, product and version description pages, and the pages for the documentation. In the publication's root directory, Publican creates a configuration file, an SQLite database file, and two subdirectories. There could be many configuration files depending on how many languages the documentation is published in, with a new subdirectory for each language. See Section 8.1.8, “ D ocumentation” for more information. 8.1.8. Document at ion Publican has comprehensive --man, --hel p and --hel p_acti o ns pages accessed from the terminal. For information on XML including the different tags available, see the D ocBook guide, DocBook: the definitive guide by Norman Walsh and Leonard Muellner, found here: http://www.docbook.org/tdg/en/html/docbook and specifically Part II: Reference for a list of all the tags and brief instructions on how to use them. There is also the comprehensive Publican User Guide accessed online at http://jfearn.fedorapeople.org/en-US/index.html or installed locally with yum i nstal l publ i cand o c. 8.2. 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. 8.2.1. Doxygen Support ed Out put and Languages D oxygen has support for output in: RTF (MS Word) 132 Chapt er 8 . Document at ion T ools 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 8.2.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. 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 133 Red Hat Ent erprise Linux 7 Developer G uide 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. 8.2.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 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. 134 Chapt er 8 . Document at ion T ools 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. 8.2.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. 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. 135 Red Hat Ent erprise Linux 7 Developer G uide /*! * ... 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. 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. 136 Chapt er 8 . Document at ion T ools /** 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 //!< 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 137 Red Hat Ent erprise Linux 7 Developer G uide 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 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. 138 Chapt er 8 . Document at ion T ools 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. 8.2.5. Resources More information can be found on the D oxygen website. Doxygen homepage Doxygen introduction Doxygen documentation Output formats 139 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 14 0 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. 14 1 Red Hat Ent erprise Linux 7 Developer G uide Revision History R evisio n 1- 4 Initial release for RHEL 7.0. Wed N o v 11 2014 R o b ert K rát ký Index Symbols .sp ec f ile - specfile Editor - compiling and building, Eclipse Built-in Specfile Editor 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 in u t ils - version, Red Hat D eveloper Toolset Features B o o st - libraries and runtime support, Boost 14 2 Revision Hist ory b o o st - d o c - 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 C D T in Eclip se - Compiling and building, CD T in Eclipse - Compiling and Building - Autotools Project, Autotools Project - Managed Make Project, Managed Make Project - Standard Make Project, Standard Make Project 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 14 3 Red Hat Ent erprise Linux 7 Developer G uide - 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 - 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 - plug-in for Eclipse, Autotools Plug-in for Eclipse - templates (supported), Autotools Plug-in for Eclipse - 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 specfile Editor, Eclipse Built-in Specfile Editor - plug-in for Eclipse, Eclipse Built-in Specfile Editor C o mp ilin g an d b u ild in g - CD T in Eclipse, CD T in Eclipse C o mp ilin g an d B u ild in g - CD T in Eclipse - Autotools Project, Autotools Project - Managed Make Project, Managed Make Project - Standard Make Project, Standard Make Project 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 14 4 Revision Hist ory co n t in u e - tools - GNU debugger, Simple GD B 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 - 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 - D ebugging C/C++ applications with Eclipse, D ebugging C/C++ Applications with Eclipse 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 C /C + + ap p licat io n s wit h Eclip se - D ebugging, D ebugging C/C++ Applications with Eclipse 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 14 5 Red Hat Ent erprise Linux 7 Developer G uide - 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 - 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 - 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 cu men t at io n T o o ls, D o cu men t at io n T o o ls - Publican, Publican - Adding media to documentation, Adding Media to D ocumentation - Brands, Brands - Building a document, Building a D ocument - Building a website, Building a Website - Commands, Commands - Create a new document, Create a New D ocument - Files, Files - Packaging a publication, Packaging a Publication - Publican documentation, D ocumentation D o xyg en 14 6 Revision Hist ory - 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 d wz - version, Red Hat D eveloper Toolset Features D yn in st - version, Red Hat D eveloper Toolset Features E Eclip se - profiling, Valgrind Plug-in for Eclipse - version, Red Hat D eveloper Toolset Features elf u t ils - version, Red Hat D eveloper Toolset Features 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 - profiling - ftrace, ftrace f u n d amen t al co mman d s - fundamentals 14 7 Red Hat Ent erprise Linux 7 Developer G uide - 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 O ME Po wer Man ag er - libraries and runtime support, GNOME Power Manager g n o me- p o wer- man ag er - GNOME Power Manager - libraries and runtime support, GNOME Power Manager 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 - version, Red Hat D eveloper Toolset 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 14 8 Revision Hist ory - starting an executable, Simple GD B - interfaces (CLI and machine), Alternative User Interfaces for GD B - 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 G N U D eb u g g er - version, Red Hat D eveloper Toolset Features 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 14 9 Red Hat Ent erprise Linux 7 Developer G uide - libraries and runtime support, Libraries and Runtime Support - profiling, Profiling - SystemTap, SystemTap ISO 14 4 82 St an d ard C + + lib rary - GNU C++ Standard Library - 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 150 Revision Hist ory - 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 - 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 GNOME Power Manager, GNOME Power Manager - gnome-power-manager, GNOME Power Manager - 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 151 Red Hat Ent erprise Linux 7 Developer G uide - Python, Python - documentation, Python D ocumentation - updates, Python Updates - Qt, Qt - documentation, Qt Library D ocumentation meta object compiler (MOC), Qt Qt Creator, Qt Creator qt-doc, Qt Library D ocumentation 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 lt race - version, Red Hat D eveloper Toolset Features 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 152 Revision Hist ory - Valgrind, Valgrind Tools memst o mp - version, Red Hat D eveloper Toolset Features 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 - 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 153 Red Hat Ent erprise Linux 7 Developer G uide - 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 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 - version, Red Hat D eveloper Toolset Features 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 154 Revision Hist ory - 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 - KD E D evelopment Framework - libraries and runtime support, KD E4 Architecture p lu g - in f o r Eclip se - Autotools - compiling and building, Autotools Plug-in for Eclipse - profiling - Valgrind, Valgrind Plug-in for Eclipse - specfile Editor - compiling and building, Eclipse Built-in Specfile Editor p ret t y- p rin t ers - Python pretty-printers - debugging, Python Pretty-Printers p rin t - tools - GNU debugger, Simple GD B Pro f ile As - Eclipse - profiling, Valgrind Plug-in for Eclipse Pro f ile C o n f ig u rat io n Men u - Eclipse - profiling, Valgrind Plug-in for Eclipse p ro f ilin g - conflict between perf and oprofile, Using OProfile, Using Perf - Eclipse, Valgrind Plug-in for Eclipse - Profile As, Valgrind Plug-in for Eclipse - Profile Configuration Menu, Valgrind Plug-in for Eclipse - ftrace, ftrace - introduction, Profiling - OProfile, OProfile - oprofiled, OProfile 155 Red Hat Ent erprise Linux 7 Developer G uide - 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 Pu b lican - D ocumentation Tools, Publican - Adding media to documentation, Adding Media to D ocumentation - Brands, Brands - Building a document, Building a D ocument - Building a website, Building a Website - Commands, Commands - Create a new document, Create a New D ocument - Files, Files - Packaging a publication, Packaging a Publication - Publican documentation, D ocumentation 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 R ed H at D evelo p er T o o lset - documentation, Additional Resources rep o rt - tools - Performance Counters for Linux (PCL) and perf, Perf Tool Commands req u ired p ackag es - compiling and building, D istributed Compiling 156 Revision Hist ory - 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 sp ecf ile Ed it o r - compiling and building, Eclipse Built-in Specfile Editor 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 157 Red Hat Ent erprise Linux 7 Developer G uide - Performance Counters for Linux (PCL) and perf, Perf Tool Commands st ep - tools - GNU debugger, Simple GD B st race - version, Red Hat D eveloper Toolset Features 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 su p p o rt ed t emp lat es - Autotools - compiling and building, Autotools Plug-in for Eclipse 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 - version, Red Hat D eveloper Toolset Features T T elep at h y - KD E D evelopment Framework - libraries and runtime support, KD E4 Architecture t emp lat es ( su p p o rt ed ) 158 Revision Hist ory - Autotools - compiling and building, Autotools Plug-in for Eclipse 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 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 159 Red Hat Ent erprise Linux 7 Developer G uide - plug-in for Eclipse, Valgrind Plug-in for Eclipse - tools, Valgrind Tools - usage, Using Valgrind - tools - cachegrind, Valgrind Tools callgrind, Valgrind Tools helgrind, Valgrind Tools massif, Valgrind Tools memcheck, Valgrind Tools - version, Red Hat D eveloper Toolset Features 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 W wid g et t o o lkit - Qt - libraries and runtime support, Qt 160 ">
/
Laadi alla
Lihtsalt sõbralik meeldetuletus. Saate dokumenti vaadata otse siin. Kuid mis kõige tähtsam, meie AI on selle juba läbi lugenud. See suudab keerulisi asju lihtsate terminitega selgitada, teie küsimustele vastata mis tahes keeles ja aidata teil kiiresti navigeerida isegi kõige pikemates või keerulisemates dokumentides.
Avalik link on uuendatud
Teie vestluse avalik link on uuendatud. You may view and manage your chat links after registration here.
Dokumendi avalik link
Reklaam
