Building, Debugging, Documenting

O.S. Laboratory

Agenda
Building
Make

Debugging
Gdb

Documenting
Doxygen
2

Build c!ain
An automatic build c!ain i" u"e#ul to$
%om&ile t!ou"and" o# "ource #ile". %om&ile 'uickly$ (it!out running manually t!e com&iler and (it!out recom&iling u&)to)date #ile". %om&ile ea"ily$ t!ird &artie" mu"t be able to com&ile t!e code. %om&ile on *ariou" &lat#orm".

Build c!ain$ Make

Make$
,raditional build c!ain in -nix en*ironment. .e'uire" a con#iguration #ile /Makefile0. Su&&ort command line &arameter". Ba"ed on t!e conce&t o# dependency. Ba"ed on t!e conce&t o# timestamp.

%on"$
1ot ea"ily &ortable. S&ace /indentation0 "en"iti*e "emantic".
+

Make#ile
Make#ile contain"$
%on#iguration *ariable".
3.g. (!ic! com&iler and linker to u"e, #lag" to be &a""ed to com&iler and linker.

Directi*e" /e.g. com&iling in"truction"0

4target5$ 4main "ource #ile5 4ot!er #ile"...5 \tab 4com&iling6linking command"5
1O,3$ !eader" de&ending on ot!er !eader" can be 7u&dated8 by u"ing touch
2

Make#ile
:ariable"$
:A.1AM3; :AL-3L<S,
A""ign" a li"t o# *alue", at reading time /&ortable0.

:A.1AM3$; :AL-3L<S,
A""ign" to a *ariable a li"t o# *alue" immediately /G1-0.

:A.1AM3=; :AL-3L<S,
Add" t!e li"t o# *alue" to &re*iou" a""igned *alue".

>/:A.1AM30
.ead" a *ariable.
9

Make#ile
%ommon *ariable name"$
%%$ t!e % com&iler
%@LAGS$ #lag" #or t!e % com&iler.

%AA$ t!e %== com&iler.

%AA@LAGS$ #lag" #or t!e %== com&iler.

LD$ t!e linker.

LD@LAGS$ #lag" #or t!e linker LDL<BS$ librarie" to link.
?

Make#ile
Crede#ined macro"$
>D$ t!e target. >4$ t!e #ir"t de&endency. >E$ all t!e de&endencie". >F$ modi#ied #ile". G$ t!e current #ile.

Make#ile$ S&ecial target"

@ir"t target$
3xecuted i# make i" run (it!out ot!er &arameter".

%ommon target name"$

all$ com&ile" and link" all t!e target". clean$ delete" generated #ile". in"tall$ in"tall" all generated #ile". !el&$ &rint" a li"t o# &o""ible target". doc$ generate" documentation.

.CIO1J
%ollect" a" de&endencie" target" (!ic! do not matc! any generated #ile name /e.g. all, clean0.
H

Make#ile$ .unning
.un make (it! Make#ile, on de#ault target$
make

.un make in &arallel /o&tional$ max number o# &arallel t!read"0$

make )M+

.un make (it! MyMake a" con#ig #ile$

make )# MyMake

.un make (it! a "&eci#ic target /a&&.x0$

make a&&.x
KL

Make#ile 3xam&le K
@ile"$
<m&lementation$ main.c com.c set.c Ieader"$ com.h set.h, located into include.

Auxiliary librarie"$
Standard % math library. %u"tom libsupport.so located into lib.

KK

Make#ile 3xam&le K
# Configuring: CC:= gcc LD:= gcc CFLAGS:= -c -Wall -Iinclude LDFLAGS:= -Llib LDLIBS:= -lsupport -lm
K2

Make#ile 3xam&le K
# Sources: S CS:= main!c com!c set!c # "b#ects: "B$S:= $(SRCS:.c=.o)

Make#ile 3xam&le K
# De%ault target: all: m&app!' m&app!': ()"B$S* @echo Lin+ing (, @$(LD) $(LDFLAGS) -o $@ $^ $(LDLIBS) clean: ,rm -!o m&app!'
K+

Make#ile 3xam&le K
# Compiling. b& using # pattern matc/ing: .o: .c ,ec/o (, ,()CC* ()CFLAGS* -o (, (0 .!"#$%: &'' c'e&n
K2

Make#ile 3xam&le K
3xam&le K &ro"$
:ery "!ort. :ery reu"able.

3xam&le K con"$
1ot #ine tuned$ doe" not ca&ture de&endencie" related to !eader #ile".

K9

Make#ile 3xam&le 2
# Fine tuned compiling: (&in.o: (&in.c inc'u)e*co(.h inc'u)e*+e,.h ,ec/o (, ,()CC* ()CFLAGS* -o (, (0 +e,.o: +e,.c inc'u)e*+e,.h ,ec/o (, ,()CC* ()CFLAGS* -o (, (0 co(.o: co(.c inc'u)e*co(.h inc'u)e*+e,.h ,ec/o (, ,()CC* ()CFLAGS* -o (, (0
K?

Make#ile 3xam&le 2
3xam&le 2 &ro"$
%a&ture" all t!e de&endencie". :ery "a#e, e*en in ca"e o# &arallel com&iling.

3xam&le 2 con"$
Longer to (rite. %annot be reu"ed.

KB

Agenda
Building
Make

Debugging
Gdb

Documenting
Doxygen
KH

Debugging
:eri#ication and debugging$
One o# t!e !arde"t &!a"e" o# de*elo&ment. ,!e mo"t time con"uming acti*ity /?L)BLG0

<t i" #undamental to u"e tool" to$

Sim&li#y debugging. S&eed u& t!e bug #ixing. A*oid "trange be!a*ior" due to bu##ered met!od" in ca"e o# "eg#ault.
2L

Debugger
A debugger allo("$
,o "u"&end t!e execution o# a &rogram in "&eci#ic &oint". ,o execute t!e &rogram "te& by "te&. ,o in"&ect *ariable *alue" at run)time.

2K

Debugger
GDB /Gnu Debugger0$
@ree and o&en "ource. Standard tool u"ed (it! gcc. .e'uire" an enric!ed executable$
gcc )g$ com&ile (it! debugging in#o". gcc )ggdb$ a" )g, but targeting gdb ex&licitly.

%ommand line tool.

DDD i" t!e mo"t #amou" gra&!ical inter#ace /no more maintained0. cgdb$ a textual inter#ace (ritten by u"ing %ur"e".
22

GDB$ Ba"ic %ommand"

Load an executable (it! gdb gdb myNexec.x gdb ))arg" myNexec.x 4&rogram arg"5 Ouit #rom gdb$ 'uit 6 ' Set e*entual executable argument" "et arg" 4argument"5 Iel& about a to&ic /e.g. about a command0 !el& 4to&ic5
2

GDB Break&oint"
Break&oint$
A break&oint mark" a &lace in t!e "ource code. ,!e execution o# a &rogram i" "u"&ended (!en a break&oint i" reac!ed. -"e#ul to in"&ect t!e &rogram at runtime in a "&eci#ic &lace. GDB "yntax$
break 6 b 4#ile$line5 break 6 b 4met!od1ame5
2+

GDB Patc!
Patc! &oint
Su"&end" t!e execution (!ene*er a (atc!ed ex&re""ion c!ange" it" *alue. -"e#ul to c!eck t!e e*olution o# a *ariable. GDB "yntax$
(atc! 4ex&re""ion5

22

GDB 3x&re""ion e*aluation

Crint
Crint" t!e re"ult o# an ex&re""ion, by u"ing t!e current *alue" #or t!e *ariable". -"e#ul to in"&ect *ariable". GDB "yntax$
&rint 6 & 4ex&re""ion5

29

GDB Stack in"&ection

Backtrace
Crinting t!e li"t o# la"t met!od called. Allo(" to under"tand t!e execution order. GDB "yntax$
backtrace 6 bt

@rame
Crint" in#o" about t!e current met!od "tack. GDB "yntax$
#rame 6 # /"!ort de"cr0 in#o #rame 6 in#o # /long0
2?

GDB 3xecution
3xecute" a &rogram #rom t!e beginning$ run 6 r Q4argument"5R %ontinue" t!e execution, #rom t!e reac!ed &oint$ continue 6 c 3xecute t!e next line atomically$ next 6 n 3xecute t!e next in"truction, going into e*entual met!od" called$ "te& 6 " .e&eat t!e la"t command$ Sreturn
2B

Agenda
Building
Make

Debugging
Gdb

Documenting
Doxygen
2H

Documenting
Documentation$
@or u"er"$
Manual", guide", tutorial", etc.. AC< documentation /#or librarie"0.

@or de*elo&er"$
AC< documentation. <m&lementation code documentation. Ot!er /u"e ca"e", "&eci#ication, etc.0.
L

Documenting
Source code documentation$
%omment" #or t!e AC<.
Automatic generation o# AC< documentation.

%omment" on im&lementation detail".

3mbedded in t!e "ource code.

Doxygen
Doxygen$
,ool #or automatic generation o# AC< documentation. .un" on many &lat#orm". @ree and o&en "ource. Su&&ort" many language".
%, %==, Ta*a.

Su&&ort" many out&ut #ormat".

HTML, Latex, .,@.
2

.unning Doxygen
Generate a con#iguration #ile /Doxy#ile0$
doxygen )g

%on#igure t!e Doxy#ile$

emac" Doxy#ile

.un doxygen$
doxygen

.un (it! a "&eci#ic con#iguration #ile$

doxygen %on#ig@ile

Doxygen %on#iguration
Main con#iguration &arameter"$
C.OT3%,N1AM3 /e.g. MyLib0 O-,C-,ND<.3%,O.J /e.g. doc0 <1C-, 6 @<L3NCA,,3.1S /e.g. "rc0 .3%-.S<:3 /e.g. J3S0 3A%L-D3 6 3A%L-D3NCA,,3.1S /U.Ma*a0 G313.A,3NU /e.g. G313.A,3NI,ML0
+

Doxygen ,ag"
Doxygen &ar"e" "&ecial comment"$
6UU %omment &ar"ed U6
6U %omment not &ar"ed U6

666 %omment &ar"ed

66 %omment not &ar"ed

Doxygen acce&t tag" to manage "&ecial documentation$

Dtag Stag
2

Doxygen ,ag"
Main tag"$
Dbrie# 4comment5
A "!ort comment.

D&aram 4&aram1ame5 4comment5

@or met!od &arameter

Dreturn 4comment5
@or met!od return *alue.

Dt!ro( 4exce&tion1ame5 4comment5

@or exce&tion" t!ro(n by a met!od /not #or %0
9

Doxygen ,ag"
,ag" #or global documentation$
<n#ormation about #ile content$
6UU D#ile U 4comment 5 U6

Grou&ing logically related met!od"$

6UU Dname 4grou&1ame5U6 6UDV U6 4met!od"Pit!,!eirDocumentation5 6UDW U6
?

Doxygen 3xam&le
1-- ,name List accessors! -1 1-,2 -1 1-- ,brie% Gets t/e element at gi3en position! - Linear comple'it&! - ,param l 4/e list! - ,param pos 4/e position! - ,return 4/e stored element! -1 3oid - getList5lement) List - l. int pos *6 1-,7 -1
B