An introduction to application development tools in Red Hat Enterprise ..... Being
a graphical application, Eclipse is a welcome alternative for developers who ....
Guide or Reference > Menus and Actions in the Java Development User Guide.
Red Hat Enterprise Linux 6 Developer Guide
An introduction to application development tools in Red Hat Enterprise Linux 6
Robert Krátký
Don Domingo
Jacquelynn East
Red Hat Enterprise Linux 6 Developer Guide
An introduction to application development tools in Red Hat Enterprise Linux 6 Ro bert Krátký Red Hat Custo mer Co ntent Services
[email protected] m Do n Do mingo Red Hat Custo mer Co ntent Services Jacquelynn East Red Hat Custo mer Co ntent Services
Legal Notice Co pyright © 20 16 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, OpenShift, 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 6 an ideal enterprise platfo rm fo r applicatio n develo pment.
T able of Cont ent s
T able of Contents . .hapt C . . . .er . .1. .. Collaborat . . . . . . . . . ing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. . . . . . . . . . 1.1. G it 5 1.1.1. Ins talling and Co nfig uring G it 5 Ins talling the g it Pac kag e 5 C o nfig uring the Default Text Ed ito r 5 S etting Up Us er Info rmatio n 5 1.1.2. Creating a New Rep o s ito ry Initializ ing an Emp ty Rep o s ito ry Imp o rting Data to a Rep o s ito ry 1.1.3. Clo ning an Exis ting Rep o s ito ry 1.1.4. Ad d ing , Renaming , and Deleting Files A d d ing Files and Direc to ries R enaming Files and Direc to ries D eleting Files and Direc to ries
6 6 6 7 7 7 7 7
1.1.5. Viewing Chang es V iewing the Current Status V iewing Differenc es
8 8 8
1.1.6 . Co mmitting Chang es 1.1.7. Sharing Chang es
8 9
P us hing Chang es to a Pub lic Rep o s ito ry C reating Patc hes fro m Ind ivid ual Co mmits 1.1.8 . Up d ating a Rep o s ito ry 1.1.9 . Ad d itio nal Res o urc es Ins talled Do c umentatio n O nline Do c umentatio n .2. Ap ac he Sub vers io n (SVN) 1
9 9 9 10 10 10 10
1.2.1. Ins talling and Co nfig uring Sub vers io n Ins talling the s ub vers io n Pac kag e
10 10
S etting Up the Default Ed ito r 1.2.2. Creating a New Rep o s ito ry
10 11
Initializ ing an Emp ty Rep o s ito ry Imp o rting Data to a Rep o s ito ry
11 11
1.2.3. Chec king O ut a Wo rking Co p y 1.2.4. Ad d ing , Renaming , and Deleting Files A d d ing a File o r Direc to ry R enaming a File o r Direc to ry
12 12 12 13
D eleting a File o r Direc to ry 1.2.5. Viewing Chang es V iewing the Status V iewing Differenc es
14 14 14 15
1.2.6 . Co mmitting Chang es 1.2.7. Up d ating a Wo rking Co p y 1.2.8 . Ad d itio nal Res o urc es Ins talled Do c umentatio n O nline Do c umentatio n
16 16 17 17 17
1.3. Co nc urrent Vers io ns Sys tem (CVS) 1.3.1. Ins talling and Co nfig uring CVS Ins talling the c vs Pac kag e S etting Up the Default Ed ito r
17 17 17 18
1.3.2. Creating a New Rep o s ito ry Initializ ing an Emp ty Rep o s ito ry Imp o rting Data to a Rep o s ito ry
18 18 19
1
Developer G uide I mp o rting Data to a Rep o s ito ry 1.3.3. Chec king O ut a Wo rking Co p y 1.3.4. Ad d ing and Deleting Files
19 19 20
A d d ing a File D eleting a File 1.3.5. Viewing Chang es V iewing the Status
20 21 21 21
iewing Differenc es V 1.3.6 . Co mmitting Chang es 1.3.7. Up d ating a Wo rking Co p y 1.3.8 . Ad d itio nal Res o urc es Ins talled Do c umentatio n
22 23 23 24 24
. .hapt C . . . .er . .2. .. Libraries . . . . . . . . and . . . .Runt . . . . ime . . . .Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. 5. . . . . . . . . . 2 .1. Co mp atib ility 25 2 .1.1. Static Linking 25 2 .2. Lib rary and Runtime Details 26 2 .2.1. The G NU C+ + Stand ard Lib rary 26 2 .2.1.1. Ad d itio nal info rmatio n 2 .2.2. Bo o s t
26 27
2 .2.2.1. Ad d itio nal Info rmatio n 2 .2.3. Q t
27 27
2 .2.3.1. Q t Up d ates 2 .2.3.2. Q t Creato r
27 28
2 .2.3.3. Q t Lib rary Do c umentatio n
28
2 .2.4. KDE Develo p ment Framewo rk 2 .2.4.1. KDE4 Arc hitec ture
28 29
.2.4.2. kd elib s Do c umentatio n 2 2 .2.5. G NO ME Po wer Manag er
30 30
2 .2.5.1. G NO ME Po wer Manag ement Vers io n G uid e
30
2 .2.5.2. API Chang es fo r g lib 2 .2.5.3. API Chang es fo r G TK+
31 32
2 .2.6 . NSS Shared Datab as es 2 .2.6 .1. Bac kward s Co mp atib ility
33 33
2 .2.6 .2. NSS Shared Datab as es Do c umentatio n 2 .2.7. Pytho n 2 .2.7.1. Pytho n Up d ates 2 .2.7.2. Pytho n Do c umentatio n
34 34 34 34
2 .2.8 . Java 2 .2.8 .1. Java Do c umentatio n
35 35
2 .2.9 . Rub y 2 .2.9 .1. Rub y Do c umentatio n
35 36
2 .2.10 . Perl
36
2 .2.10 .1. Perl Up d ates 2 .2.10 .2. Ins tallatio n
36 38
2 .2.10 .3. Perl Do c umentatio n
39
. .hapt C . . . .er . .3. . . Compiling . . . . . . . . . .and . . . .Building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. 1. . . . . . . . . . 3 .1. G NU Co mp iler Co llec tio n (G CC) 41
2
3 .1.1. Lang uag e Co mp atib ility
41
3 .1.2. O b jec t Co mp atib ility and Intero p erab ility 3 .1.3. Running G CC
43 43
3 .1.3.1. Simp le C Us ag e
44
3 .1.3.2. Simp le C+ + Us ag e
44
T able of Cont ent s 3 .1.3.2. Simp le C+ + Us ag e 3 .1.3.3. Simp le Multi-File Us ag e
44 45
3 .1.3.4. Rec o mmend ed O p timiz atio n O p tio ns 3 .1.3.5. Us ing Pro file Feed b ac k to Tune O p timiz atio n Heuris tic s
46 47
3 .1.3.6 . Us ing 32-b it c o mp ilers o n a 6 4-b it ho s t
48
.1.4. G CC Do c umentatio n 3 3 .2. Auto to o ls
50 50
3 .2.1. Auto to o ls Plug -in fo r Ec lip s e 3 .2.2. Co nfig uratio n Sc rip t
50 51
3 .2.3. Auto to o ls Do c umentatio n
51
3 .3. b uild -id Uniq ue Id entific atio n o f Binaries
52
. .hapt C . . . .er . .4. .. Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 ........... 4 .1. ELF Exec utab le Binaries 53 4 .2. Ins talling Deb ug info Pac kag es
54
4 .2.1. Ins talling Deb ug info Pac kag es fo r Co re Files Analys is 4 .3. G DB
55 57
4 .3.1. Simp le G DB 4 .3.2. Running G DB
58 60
4 .3.3. Co nd itio nal Breakp o ints
61
4 .3.4. Fo rked Exec utio n 4 .3.5. Deb ug g ing Ind ivid ual Thread s
62 64
.3.6 . Alternative Us er Interfac es fo r G DB 4 4 .4. Variab le Trac king at As s ig nments
68 69
4 .5. Pytho n Pretty-Printers
69
. .hapt C . . . .er . .5. . .Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7. 3. . . . . . . . . . 5 .1. Valg rind 5 .1.1. Valg rind To o ls
73 73
5 .1.2. Us ing Valg rind
74
5 .1.3. Ad d itio nal info rmatio n 5 .2. O Pro file 5 .2.1. Us ing O Pro file 5 .2.2. O Pro file in Red Hat Enterp ris e Linux 7 5 .2.2.1. New Features 5 .2.2.2. Kno wn Pro b lems and Limitiatio ns 5 .2.3. O Pro file Do c umentatio n
74 74 75 77 77 77 77
5 .3. Sys temTap 5 .3.1. Ad d itio nal Info rmatio n
78 78
5 .4. Perfo rmanc e Co unters fo r Linux (PCL) To o ls and p erf
79
5 .4.1. Perf To o l Co mmand s .4.2. Us ing Perf 5 5 .5. ftrac e
79 79 82
5 .5.1. Us ing ftrac e
82
5 .5.2. ftrac e Do c umentatio n
83
. .hapt C . . . .er . .6. .. Document . . . . . . . . . at . . ion ...T . .ools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8. 4. . . . . . . . . . 6 .1. Do xyg en
84
6 .1.1. Do xyg en Sup p o rted O utp ut and Lang uag es 6 .1.2. G etting Started
84 84
6 .1.3. Running Do xyg en
85
6 .1.4. Do c umenting the So urc es
86
6 .1.5. Res o urc es
90
. .ppendix A . . . . . . . A. . . Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9. 1. . . . . . . . . . A .1. mallo p t
91
3
Developer G uide A .1. mallo p t
91
m allo c _trim m allo c _s tats
91 92
Further Info rmatio n
92
. .ppendix A . . . . . . . B. . . .Revision . . . . . . . .Hist . . . ory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9. 3. . . . . . . . . . I.ndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9. 3. . . . . . . . . .
4
Chapt er 1 . Collaborat ing
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: G it , SVN , and C VS. The following sections provide a brief overview and references to relevant documentation for each tool.
1.1. 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.1.1. Inst alling and Configuring Git Inst alling t he git Package In Red Hat Enterprise Linux 6, 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.
Examp le 1.1. 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
5
Developer G uide
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.2. 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.1.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: 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"]
6
Chapt er 1 . Collaborat ing
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.1.1, “ Configuring the D efault Text Editor” .
1.1.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.1.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.1.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. To proceed and actually rename the content in the repository, commit the changes as described in Section 1.1.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:
7
Developer G uide
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.1.6, “ Committing Changes” .
1.1.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.1.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.1.6. Commit t ing Changes To apply your changes to a G it repository and create a new revision, change to the directory with the repository and type the following command at a shell prompt: g i t co mmi t [-m "commit message"] Replace commit message with a short description of your revision. This command commits all changes in files that are explicitly marked as ready to be committed. To commit changes in all files that are under revision control, add the -a command line option as follows:
8
Chapt er 1 . Collaborat ing
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.1.1, “ Configuring the D efault Text Editor” .
1.1.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.1.8. Updat ing a Reposit ory To update your local copy of a G it repository and get the latest changes from a remote repository, change to the directory with your local G it repository and type the following at a shell prompt: g i t fetch remote_repository Replace remote_repository with the name of the remote repository. This command fetches information about the current status of the remote repository, allowing you to review these changes before applying them to your local copy. To proceed and merge these changes with what you have in your local G it repository, type: g i t merg e remote_repository Alternatively, you can perform both these steps at the same time by using the following command instead: g i t pul l remote_repository
9
Developer G uide
1.1.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. 7. 1/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.
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 6, 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
10
Chapt er 1 . Collaborat ing
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.3. 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 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.4 . 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).
11
Developer G uide
Examp le 1.5. 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 ...
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.6 . 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:
12
Chapt er 1 . Collaborat ing
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.7. 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: 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.8. 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
13
Developer G uide
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” .
Examp le 1.9 . 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
14
Chapt er 1 . Collaborat ing
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.10. 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 A + COPYING M Makefile
Vie wing Diffe re nce s To view differences between a working copy and the checked out content, change to the directory with the working copy and run the following command: svn d i ff [file…] This displays changes to all files in the working copy. If you are only interested in changes to a particular file, supply the file name on the command line.
Examp le 1.11. 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)
15
Developer G uide
@ @ -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” .
Examp le 1.12. 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
16
Chapt er 1 . Collaborat ing
Examp le 1.13. 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.
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. 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.3.1. Inst alling and Configuring CVS Inst alling t he cvs Package
17
Developer G uide
In Red Hat Enterprise Linux 6, 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.14 . 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: ~]$ echo "expo rt C VSED IT O R = emacs" >> ~ /. bashrc ~]$ . ~ /. bashrc
1.3.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:
18
Chapt er 1 . Collaborat ing
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.15. 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.16 . 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: ~]$ 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.3.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
19
Developer G uide
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.17. 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.3.4 . Adding and Delet ing Files Adding a File 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.3.6, “ Committing Changes” .
Examp le 1.18. 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
20
Chapt er 1 . Collaborat ing
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.3.6, “ Committing Changes” .
Examp le 1.19 . 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: 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.3.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.20. Viewin g t h e st at u s o f a wo rkin g co p y
21
Developer G uide
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.
Examp le 1.21. 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 ...
22
Chapt er 1 . Collaborat ing
1.3.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.3.1, “ Installing and Configuring CVS” .
Examp le 1.22. 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 ... RCS file: /home/john/cvsroot/project/ChangeLog,v done Checking in ChangeLog; /home/john/cvsroot/project/ChangeLog,v select all) and then right-click and select the to g g l e fi el d s option from the drop down menu. XML O UT P UT The output into the xml directory consists of a number of files, each compound gathered by doxygen, as well as an i nd ex. xml . An XSLT script, co mbi ne. xsl t, is also created that is used to combine all the XML files into a single file. Along with this, two XML schema files are created, i nd ex. xsd for the index file, and co mpo und . xsd for the compound files, which describe the possible elements, their attributes, and how they are structured. MAN P AG E O UT P UT The documentation from the man directory can be viewed with the man program after ensuring the manpath has the correct man directory in the man path. Be aware that due to limitations with the man page format, information such as diagrams, cross-references and formulas will be lost.
6.1.4 . Document ing t he Sources There are three main steps to document the sources. 1. First, ensure that EXT R AC T _ALL is set to no so warnings are correctly generated and documentation is built properly. This allows doxygen to create documentation for documented members, files, classes and namespaces. 2. There are two ways this documentation can be created: A special d o cu men t at io n b lo ck This comment block, containing additional marking so D oxygen knows it is part of the documentation, is in either C or C++. It consists of a brief description, or a detailed description. Both of these are optional. What is not optional, however, is the in body description. This then links together all the comment blocks found in the body of the method or function.
86
Chapt er 6 . Document at ion T ools
Note While more than one brief or detailed description is allowed, this is not recommended as the order is not specified. The following will detail the ways in which a comment block can be marked as a detailed description: C-style comment block, starting with two asterisks (*) in the JavaD oc style. /** * ... documentation ... */ C-style comment block using the Qt style, consisting of an exclamation mark (!) instead of an extra asterisk. /*! * ... documentation ... */ The beginning asterisks on the documentation lines can be left out in both cases if that is preferred. A blank beginning and end line in C++ also acceptable, with either three forward slashes or two forward slashes and an exclamation mark. /// /// ... documentation /// or //! //! ... documentation ... //! Alternatively, in order to make the comment blocks more visible a line of asterisks or forward slashes can be used. ///////////////////////////////////////////////// /// ... documentation ... ///////////////////////////////////////////////// or /********************************************//** * ... documentation ... ***********************************************/ Note that the two forwards slashes at the end of the normal comment block start a special comment block.
87
Developer G uide
There are three ways to add a brief description to documentation. To add a brief description use \bri ef above one of the comment blocks. This brief section ends at the end of the paragraph and any further paragraphs are the detailed descriptions. /*! \brief brief documentation. * brief documentation. * * detailed documentation. */ By setting JAVAD O C _AUT O BR IEF to yes, the brief description will only last until the first dot followed by a space or new line. Consequentially limiting the brief description to a single sentence. /** Brief documentation. Detailed documentation continues * from here. */ This can also be used with the above mentioned three-slash comment blocks (///). The third option is to use a special C++ style comment, ensuring this does not span more than one line. /// Brief documentation. /** Detailed documentation. */ or //! Brief documentation. //! Detailed documentation //! starts here The blank line in the above example is required to separate the brief description and the detailed description, and JAVAD O C _AUT O BR IEF must to be set to no . Examples of how a documented piece of C++ code using the Qt style can be found on the Doxygen documentation website It is also possible to have the documentation after members of a file, struct, union, class, or enum. To do this add a < marker in the comment block.\ int var; /*!< detailed description after the member */ Or in a Qt style as: int var; /**< detailed description after the member */ or int var; //!< detailed description after the member //!
