÷ƒ’À;è TeX output 1999.04.01:0230‹ÿÿÿÿŸòŽ ƒ3* þšé‘Gó$ÂÖN ¼j cmbx12ÏGNU–ƧCo‘¥ãding“StandardsŽ‘GŸ 0‰±ž¸ §ó6ÂÖN ff cmbx12áRicŒÌhard‘ffStallmanŽŸlast–ffups3dated“MarcŒÌh“26,“1999ŽŸÌ̉±ž¸ŽŒ‹*ŸòŽ ƒ3*Ÿ‹EW‘GóKñ`y ó3 cmr10»Cop•²!yrigh“t‘±ž«‚cŽŽŽ‘¦fó!",š ó3 cmsy10Ä ŽŽŽŽ‘@»1992,–¦f1993,“1994,“1995,“1996,“1997,“1998“F›ÿeree“Soft•²!w“are–¦fF˜oundation,“Inc.Ž¤33‘GPš²!ermission–Þ²is“gran˜ted“to“mak˜e“and“distribute“v˜erbatim“copies“of“this“man˜ual“pro˜vided“theŽ© 33‘Gcop•²!yrigh“t–¦fnotice“and“this“pMÞermission“notice“are“preserv²!ed“on“all“copies.Ž¡‘GPš²!ermission–Ô'is“gran˜ted“to“cop˜y“and“distribute“moMÞdi ed“v˜ersions“of“this“man˜ual“under“the“con-Ž¦‘Gditions–™1for“vš²!erbatim“cop˜ying,‘›Õpro˜vided“that“the“en˜tire“resulting“deriv˜ed“w˜ork“is“distributedŽ¦‘Gunder–¦fthe“terms“of“a“pMÞermission“notice“iden²!tical“to“this“one.Ž¡‘GPš²!ermission–ûris“gran˜ted“to“cop˜y“and“distribute“translations“of“this“man˜ual“in˜to“another“lan-Ž¦‘Gguage,‘{nunder–p°the“abšMÞo•²!v“e–p°conditions“for“mo˜di ed“v²!ersions,‘{nexcept“that“this“p˜ermission“noticeŽ¦‘Gmaš²!y–¦fbMÞe“stated“in“a“translation“appro˜v˜ed“b˜y“the“F‘ÿeree“Soft˜w˜are“F‘ÿeoundation.ŽŽŒ‹Ÿò‘G»Chapter–¦f2:‘ÝÝKeeping“F›ÿeree“Soft•²!w“are‘¦fF˜ree’ð¨1ŽŽŽ ƒ3* ý ÌÖ‘Gó-ÂÖN G® cmbx12Ø1‘ ¸QAb›Š=out–z³the“GNU“Co˜ding“StandardsŽŽŸ#˜6‘!G»The–rdGNU‘rVCoMÞding“Standards“wš²!ere“written“b˜y“Ric˜hard“Stallman“and“other“GNU‘rVPro‘›»jectŽ¤ 33‘Gv•²!olun“teers.‘²7Their–#tpurpMÞose“is“to“makš²!e“the“GNU‘#Rsystem“clean,–=¤consisten˜t,“and–#teasy“to“install.Ž¡‘GThis–³ÙdošMÞcumen²!t“can“also“b˜e“read“as“a“guide“to“writing“p˜ortable,‘ä[robust“and“reliable“programs.Ž¡‘GIt–nƒfoMÞcuses“on“programs“written“in“C,“but“manš²!y“of“the“rules“and“principles“are“useful“ev˜en“ifŽ¡‘Gy²!ou–¦dwrite“in“another“programming“language.‘ÝÜThe“rules“often“state“reasons“for“writing“in“aŽ¡‘Gcertain‘¦fw•²!a“y‘ÿe.Ž©ª4‘!GCorrections–ÅQor“suggestions“for“this“došMÞcumen²!t“should“b˜e“senš²!t“to“óßê«the“pacš²!k‘ÿdDage“has“a“v˜ersion“n˜um˜bMÞer“whic˜h“is“di eren˜t“from“this“program'sŽ¡‘Kâ:v•²!ersion›3¹n“um“bMÞer,‘Wy“ou˜can˜men“tion˜the˜pac“k‘ÿdDage˜v“ersion˜n“um“b•MÞer˜just˜b“efore˜theŽ¡‘Kâ:close-paren²!thesis.Ž¦‘Kâ:If–yš²!ou“óÒ ž& ó3 cmb10½need“»to“men˜tion“the“v˜ersion“n˜um˜bMÞers“of“libraries“whic˜h“are“distributedŽ¡‘Kâ:separately–Ùˆfrom“the“pacš²!k‘ÿdDage“whic˜h“con˜tains“this“program,‘&Py˜ou“can“do“so“b˜yŽ¡‘Kâ:prinš²!ting–Qtan“additional“line“of“v˜ersion“info“for“eac˜h“library“y˜ou“w˜an˜t“to“men˜tion.Ž¡‘Kâ:Use–¦fthe“same“format“for“these“lines“as“for“the“ rst“line.Ž¦‘Kâ:Please–²œdo“not“men²!tion“all“of“the“libraries“that“the“program“uses“\just“forŽ¡‘Kâ:completeness"|that–&2w²!ould“proMÞduce“a“lot“of“unhelpful“clutter.‘ ]BPlease“men-Ž¡‘Kâ:tion–Ilibrary“vš²!ersion“n˜um˜bMÞers“only“if“y˜ou“ nd“in“practice“that“they“are“v˜eryŽ¡‘Kâ:impMÞortanš²!t–¦fto“y˜ou“in“debugging.Ž¦‘Kâ:The–Rwfolloš²!wing“line,‘c@after“the“v˜ersion“n˜um˜bšMÞer“line“or“lines,‘c@should“b˜e“a“cop•²!yrigh“tŽ¡‘Kâ:notice.‘£If–è"more“than“one“cop•²!yrigh“t–è"notice“is“called“for,‘ø‘put“eac²!h“on“a“separateŽ¡‘Kâ:line.Ž¦‘Kâ:Next–ýdshould“folloš²!w“a“brief“statemen˜t“that“the“program“is“free“soft˜w˜are,‘1and“thatŽ¡‘Kâ:users–i¤are“free“to“copš²!y“and“c˜hange“it“on“certain“conditions.‘'—If“the“program“isŽ¡‘Kâ:co•²!v“ered›5Íb“y˜the˜GNU‘5±GPL,˜sa“y˜so˜here.‘¸UAlso˜men“tion˜that˜there˜is˜no˜w“arran“t“y‘ÿe,Ž¡‘Kâ:to–¦fthe“extenš²!t“pMÞermitted“b˜y“la˜w.Ž¦‘Kâ:It–};is“ok“to“ nish“the“output“with“a“list“of“the“ma‘›»jor“authors“of“the“program,‘…wasŽ¡‘Kâ:a›¦fw•²!a“y˜of˜giving˜credit.Ž¦‘Kâ:Here's–¦fan“example“of“output“that“follo²!ws“these“rules:ŽŸ1™‘hʼGNU–¿ªEmacs“19.34.5Ž¤ €‘hÊCopyright–¿ª(C)“1996“Free“Software“Foundation,“Inc.Ž¡‘hÊGNU–¿ªEmacs“comes“with“NO“WARRANTY,ŽŽŒ‹ lwŸò‘G»Chapter–¦f4:‘ÝÝProgram“Beha²!vior“for“All“Programs’È3Ç9ŽŽŽ ƒ3* ý ÌÖ‘hʼto–¿ªthe“extent“permitted“by“law.Ž¤ €‘hÊYou–¿ªmay“redistribute“copies“of“GNU“EmacsŽ¡‘hÊunder–¿ªthe“terms“of“the“GNU“General“Public“License.Ž¡‘hÊFor–¿ªmore“information“about“these“matters,Ž¡‘hÊsee–¿ªthe“files“named“COPYING.Ž©L ‘Kâ:»Y‘ÿeou–‚Öshould“adapt“this“to“y²!our“program,›¹òof“course,˜ lling“in“the“propMÞer“y²!ear,Ž¤ 33‘Kâ:cop•²!yrigh“t–~Uholder,›´Qname“of“program,˜and“the“references“to“distribution“terms,Ž¡‘Kâ:and–¦fcš²!hanging“the“rest“of“the“w˜ording“as“necessary‘ÿe.Ž¦‘Kâ:This›)Acop•²!yrigh“t˜notice˜only˜needs˜to˜men“tion˜the˜most˜recen“t˜y“ear˜in˜whic“hŽ¡‘Kâ:c•²!hanges›=w“ere˜made|there's˜no˜need˜to˜list˜the˜y“ears˜for˜previous˜v“ersions'Ž¡‘Kâ:cš²!hanges.‘ÖõY‘ÿeou–‘®don't“ha˜v˜e“to“men˜tion“the“name“of“the“program“in“these“notices,Ž¡‘Kâ:if–¦fthat“is“incon•²!v“enien“t,–¦fsince“it“appMÞeared“in“the“ rst“line.ŽŸdå‘G¼--help‘R÷»This–d±option“should“output“brief“doMÞcumenš²!tation“for“ho˜w“to“in˜v˜ok˜e“the“program,Ž¡‘Kâ:on–¾¨standard“output,‘íthen“exit“successfully‘ÿe.‘žOther“options“and“argumen²!ts“shouldŽ¡‘Kâ:bšMÞe–\ignored“once“this“is“seen,‘‰…and“the“program“should“not“p˜erform“its“normalŽ¡‘Kâ:function.Ž¦‘Kâ:Near–Mthe“end“of“the“`¼--help»'“option's“output“there“should“bMÞe“a“line“that“sa²!ysŽ¡‘Kâ:where–¦fto“mail“bug“repMÞorts.‘ÝÝIt“should“ha•²!v“e–¦fthis“format:ŽŸ˜Ù‘hʼReport–¿ªbugs“to“¿mailing-address¼.ŽŸ|<‘Gá4.5‘™T‘þ¦fable–f@of“Long“OptionsŽŽŸdå‘!G»Here–ÉEis“a“table“of“long“options“used“b²!y“GNU‘Èúprograms.‘FzIt“is“surely“incomplete,‘übutŽ¡‘Gwš²!e–bêaim“to“list“all“the“options“that“a“new“program“migh˜t“w˜an˜t“to“bMÞe“compatible“with.‘hIfŽ¡‘Gy²!ou–€øuse“names“not“already“in“the“table,›ˆtplease“send“¼gnu@gnu.org“»a“list“of“them,˜with“theirŽ¡‘Gmeanings,–¦fso“w²!e“can“upMÞdate“the“table.ŽŸ}¾‘G`¼after-date»'Ž¡‘Kâ:`¼-N»'–¦fin“¼tar».Ž¤då‘G`¼all»'‘"|Ÿ`¼-a»'–¦fin“¼du»,“¼ls»,“¼nm»,“¼stty»,“¼uname»,“and“¼unexpand».Ž¡‘G`¼all-text»'Ž© 33‘Kâ:`¼-a»'–¦fin“¼diff».Ž¡‘G`¼almost-all»'Ž¦‘Kâ:`¼-A»'–¦fin“¼ls».Ž¡‘G`¼append»'‘=¡`¼-a»'–¦fin“¼etags»,“¼tee»,“¼time»;“`¼-r»'“in“¼tar».Ž¡‘G`¼archive»'‘ }÷`¼-a»'–¦fin“¼cp».Ž¡‘G`¼archive-name»'Ž¦‘Kâ:`¼-n»'–¦fin“¼shar».Ž¡‘G`¼arglength»'Ž¦‘Kâ:`¼-l»'–¦fin“¼m4».Ž¡‘G`¼ascii»'‘ýK`¼-a»'–¦fin“¼diff».Ž¡‘G`¼assign»'‘=¡`¼-v»'–¦fin“¼gawk».ŽŽŒ‹ zRŸò‘G»Chapter–¦f4:‘ÝÝProgram“Beha²!vior“for“All“Programs’º-10ŽŽŽ ƒ3* ý ÌÖ‘G`¼assume-new»'Ž¤ 33‘Kâ:`¼-W»'–¦fin“Mak²!e.Ž©ÌÍ‘G`¼assume-old»'Ž¡‘Kâ:`¼-o»'–¦fin“Mak²!e.Ž¦‘G`¼auto-check»'Ž¡‘Kâ:`¼-a»'–¦fin“¼recode».Ž¦‘G`¼auto-pager»'Ž¡‘Kâ:`¼-a»'–¦fin“¼wdiff».Ž¦‘G`¼auto-reference»'Ž¡‘Kâ:`¼-A»'–¦fin“¼ptx».Ž¦‘G`¼avoid-wraps»'Ž¡‘Kâ:`¼-n»'–¦fin“¼wdiff».Ž¦‘G`¼background»'Ž¡‘Kâ:F‘ÿeor–¦fservš²!er“programs,“run“in“the“bac˜kground.Ž¦‘G`¼backward-search»'Ž¡‘Kâ:`¼-B»'–¦fin“¼ctags».Ž¦‘G`¼basename»'Ž¡‘Kâ:`¼-f»'–¦fin“¼shar».Ž¦‘G`¼batch»'‘ýKUsed–¦fin“GDB.Ž¦‘G`¼baud»'‘¼õUsed–¦fin“GDB.Ž¦‘G`¼before»'‘=¡`¼-b»'–¦fin“¼tac».Ž¦‘G`¼binary»'‘=¡`¼-b»'–¦fin“¼cpio“»and“¼diff».Ž¦‘G`¼bits-per-code»'Ž¡‘Kâ:`¼-b»'–¦fin“¼shar».Ž¦‘G`¼block-size»'Ž¡‘Kâ:Used–¦fin“¼cpio“»and“¼tar».Ž¦‘G`¼blocks»'‘=¡`¼-b»'–¦fin“¼head“»and“¼tail».Ž¦‘G`¼break-file»'Ž¡‘Kâ:`¼-b»'–¦fin“¼ptx».Ž¦‘G`¼brief»'‘ýKUsed–¦fin“v‘ÿdDarious“programs“to“mak²!e“output“shorter.Ž¦‘G`¼bytes»'‘ýK`¼-c»'–¦fin“¼head»,“¼split»,“and“¼tail».Ž¦‘G`¼c++»'‘"|Ÿ`¼-C»'–¦fin“¼etags».Ž¦‘G`¼catenate»'Ž¡‘Kâ:`¼-A»'–¦fin“¼tar».Ž¦‘G`¼cd»'‘(“win“(x,“y,“z)ŽŸ €‘EøD&&‘¿ªremaining_condition)Ž¦‘!G»T‘ÿery–to“a•²!v“oid›ha“ving˜t“w“o˜opMÞerators˜of˜di eren“t˜precedence˜at˜the˜same˜lev“el˜of˜inden“tation.Ž¡‘GF‘ÿeor–¦fexample,“don't“write“this:ŽŸ–/‘.ùœ¼mode–¿ª=“(inmode[j]“==“VOIDmodeŽ¤ €‘\öì||–¿ªGET_MODE_SIZE“(outmode[j])“>“GET_MODE_SIZE“(inmode[j])Ž¡‘\öì?–¿ªoutmode[j]“:“inmode[j]);Ž¦‘!G»Instead,–¦fuse“extra“parenš²!theses“so“that“the“inden˜tation“sho˜ws“the“nesting:ŽŸ–/‘.ùœ¼mode–¿ª=“((inmode[j]“==“VOIDmodeŽ¡‘b¶–||–¿ª(GET_MODE_SIZE“(outmode[j])“>“GET_MODE_SIZE“(inmode[j])))Ž¡‘\öì?–¿ªoutmode[j]“:“inmode[j]);Ž¦‘!G»Insert–¾Pextra“parenš²!theses“so“that“Emacs“will“inden˜t“the“cošMÞde“prop˜erly–ÿe.‘%›F“or‘¾Pexample,‘ÄKtheŽŸ 33‘Gfollo•²!wing›¦finden“tation˜loMÞoks˜nice˜if˜y“ou˜do˜it˜b“y˜hand,˜but˜Emacs˜w“ould˜mess˜it˜up:ŽŸ–/‘.ùœ¼v–¿ª=“rup->ru_utime.tv_sec*1000“+“rup->ru_utime.tv_usec/1000Ž¡‘EøD+–¿ªrup->ru_stime.tv_sec*1000“+“rup->ru_stime.tv_usec/1000;Ž¦‘!G»But–¦fadding“a“set“of“parenš²!theses“solv˜es“the“problem:ŽŸ–/‘.ùœ¼v–¿ª=“(rup->ru_utime.tv_sec*1000“+“rup->ru_utime.tv_usec/1000Ž¡‘K·î+–¿ªrup->ru_stime.tv_sec*1000“+“rup->ru_stime.tv_usec/1000);Ž¦‘!G»F‘ÿeormat–¦fdo-while“statemenš²!ts“lik˜e“this:ŽŸ–/‘.ùœ¼doŽ¡‘:xð{Ž¡‘EøDa–¿ª=“foo“(a);Ž¡‘:xð}Ž¡‘.ùœwhile–¿ª(a“>“0);ŽŽŒ‹ÝHŸò‘G»Chapter–¦f5:‘ÝÝMaking“The“Best“Use“of“C’îXE27ŽŽŽ ƒ3* ý ÌÖ‘!GPlease–[Yuse“formfeed“cš²!haracters“(con˜trol-L)‘[*to“divide“the“program“in˜to“pages“at“logicalŽ¤ 33‘Gplaces–,^(but“not“within“a“function).‘oÄIt“doMÞes“not“matter“just“ho²!w“long“the“pages“are,‘MÛsinceŽ¡‘Gthey–û:do“not“ha•²!v“e–û:to“ t“on“a“prinš²!ted“page.‘ÜYThe“formfeeds“should“appMÞear“alone“on“lines“b˜yŽ¡‘Gthemselv²!es.ŽŸ$LÌ‘Gá5.2‘™CommenŒÌting–f@Y›þ¦four“W˜orkŽŽŸQë‘!G»Evš²!ery–"program“should“start“with“a“commen˜t“sa˜ying“brie y“what“it“is“for.‘±¾Example:‘›®`¼fmtŽ¡‘G-–¦ffilter“for“simple“filling“of“text»'.Ž©Që‘!GPlease–pÇwrite“the“commen²!ts“in“a“GNU‘p“program“in“English,‘£_bMÞecause“English“is“the“oneŽ¡‘Glanguage–dthat“nearly“all“programmers“in“all“counš²!tries“can“read.‘ÇÅIf“y˜ou“do“not“write“EnglishŽ¡‘Gwš²!ell,‘~âplease–S–write“commen˜ts“in“English“as“w˜ell“as“y˜ou“can,‘~âthen“ask“other“pMÞeople“to“helpŽ¡‘Grewrite–W6them.‘ðLIf“yš²!ou“can't“write“commen˜ts“in“English,‘ƒiplease“ nd“someone“to“w˜ork“withŽ¡‘Gyš²!ou–¦fand“translate“y˜our“commen˜ts“in˜to“English.Ž¦‘!GPlease–£put“a“commenš²!t“on“eac˜h“function“sa˜ying“what“the“function“doMÞes,‘Éòwhat“sorts“ofŽ¡‘Gargumenš²!ts–pŸit“gets,‘£-and“what“the“pMÞossible“v‘ÿdDalues“of“argumen˜ts“mean“and“are“used“for.‘<‡ItŽ¡‘Gis–å¦not“necessary“to“duplicate“in“wš²!ords“the“meaning“of“the“C‘å–argumen˜t“declarations,‘õvif“a“CŽ¡‘Gt²!ypšMÞe–ž>is“b˜eing“used“in“its“customary“fashion.‘Û%If“there“is“an²!ything“nonstandard“ab˜out“its“useŽ¡‘G(sucš²!h–Òas“an“argumen˜t“of“t˜ypMÞe“¼char‘¦f*“»whic˜h“is“really“the“address“of“the“second“c˜haracter“of“aŽ¡‘Gstring,›ƒAnot–zwthe“ rst),˜or“anš²!y“pMÞossible“v‘ÿdDalues“that“w˜ould“not“w˜ork“the“w˜a˜y“one“w˜ould“expMÞectŽ¡‘G(sucš²!h–¦fas,“that“strings“con˜taining“newlines“are“not“guaran˜teed“to“w˜ork),“bMÞe“sure“to“sa˜y“so.Ž¦‘!GAlso–¦fexplain“the“signi cance“of“the“return“v‘ÿdDalue,“if“there“is“one.Ž¦‘!GPlease–®xput“t•²!w“o–®xspaces“after“the“end“of“a“senš²!tence“in“y˜our“commen˜ts,‘°|so“that“the“EmacsŽ¡‘Gsenš²!tence– Îcommands“will“w˜ork.‘±UAlso,‘;†please“write“complete“sen˜tences“and“capitalize“the“ rstŽ¡‘Gwš²!ord.‘nÎIf–aa“lo˜w˜er-case“iden˜ti er“comes“at“the“bMÞeginning“of“a“sen˜tence,‘¸don't“capitalize“it!Ž¡‘GChanging–5öthe“spMÞelling“makš²!es“it“a“di eren˜t“iden˜ti er.‘ŒŒIf“y˜ou“don't“lik˜e“starting“a“sen˜tenceŽ¡‘Gwith–”a“lo•²!w“er–”case“letter,‘Ïpwrite“the“senš²!tence“di eren˜tly“(e.g.,‘Ïp\The“iden˜ti er“lo˜w˜er-case“isŽ¡‘»+.–§‘.“.Ž‘"~").Ž¦‘!GThe–¥¸commenš²!t“on“a“function“is“m˜uc˜h“clearer“if“y˜ou“use“the“argumen˜t“names“to“spMÞeakŽ¡‘GabMÞout–ùsthe“argumen²!t“v›ÿdDalues.‘×The“v˜ariable“name“itself“should“bMÞe“lo•²!w“er–ùscase,‘6but“write“it“inŽ¡‘GuppšMÞer–`Écase“when“y²!ou“are“sp˜eaking“ab˜out“the“v›ÿdDalue“rather“than“the“v˜ariable“itself.‘ Th²!us,Ž¡‘G\the–¦finošMÞde“n•²!um“b˜er–¦fNODE‘¨/‰x³HøŽ‘ñ'NUM"“rather“than“\an“ino˜de".Ž¦‘!GThere–4¡is“usually“no“purpšMÞose“in“restating“the“name“of“the“function“in“the“commen²!t“b˜eforeŽ¡‘Git,‘)wbšMÞecause–Üthe“reader“can“see“that“for“himself.‘~ÔThere“migh²!t“b˜e“an“exception“when“theŽ¡‘Gcommenš²!t–¦fis“so“long“that“the“function“itself“w˜ould“bšMÞe“o “the“b˜ottom“of“the“screen.Ž¦‘!GThere–¦fshould“bMÞe“a“commenš²!t“on“eac˜h“static“v‘ÿdDariable“as“w˜ell,“lik˜e“this:ŽŸž¸‘.ùœ¼/*–¿ªNonzero“means“truncate“lines“in“the“display;Ž¤ €‘@8šzero–¿ªmeans“continue“them.‘ T*/Ž¡‘.ùœint‘¿ªtruncate_lines;Ž¦‘!G»Evš²!ery–»`¼#endif»'“should“ha˜v˜e“a“commen˜t,‘ÉÐexcept“in“the“case“of“short“conditionals“(just“aŽ¤ 33‘Gfew–ËÝlines)“that“are“not“nested.‘NCThe“commen²!t“should“state“the“condition“of“the“conditionalŽ¡‘Gthat–;=is“ending,‘P«¾including–ˆSits“sense».‘º%`¼#else»'–;=should“ha•²!v“e–;=a“commen²!t“describing“the“conditionŽ¡‘G¾and‘êêsense‘y»of–¦fthe“coMÞde“that“follo²!ws.‘ÝÝF‘ÿeor“example:ŽŽŒ‹åõŸò‘G»Chapter–¦f5:‘ÝÝMaking“The“Best“Use“of“C’îXE28ŽŽŽ ƒ3* ý ÌÖ‘.ùœ¼#ifdef‘¿ªfooŽ¤ ÿ‘:xð...ŽŽ¡‘.ùœ#else–¿ª/*“not“foo“*/Ž¡‘:xð...ŽŽ¡‘.ùœ#endif–¿ª/*“not“foo“*/ŽŽ¤?Š¡‘.ùœ#ifdef‘¿ªfooŽ¤ ÿ‘:xð...ŽŽ¡‘.ùœ#endif–¿ª/*“foo“*/ŽŽŸ(c|‘G»but,–¦fbš²!y“con˜trast,“write“the“commen˜ts“this“w˜a˜y“for“a“`¼#ifndef»':ŽŸ‰æ‘.ùœ¼#ifndef‘¿ªfooŽ¤ ÿ‘:xð...ŽŽ¡‘.ùœ#else–¿ª/*“foo“*/Ž¡‘:xð...ŽŽ¡‘.ùœ#endif–¿ª/*“foo“*/ŽŽ¡‘.ùœ#ifndef‘¿ªfooŽ¤ ÿ‘:xð...ŽŽ¡‘.ùœ#endif–¿ª/*“not“foo“*/ŽŽŸ7d‘Gá5.3‘™Clean–f@Use“of“C“ConstructsŽŽŸ=‘!G»Please–™;explicitly“declare“all“argumen²!ts“to“functions.‘ÙyDon't“omit“them“just“bMÞecause“theyŽ¤ 33‘Gare‘¦f¼int»s.Ž©=‘!GDeclarations–T=of“external“functions“and“functions“to“appMÞear“later“in“the“source“ le“shouldŽ¡‘Gall–xŽgo“in“one“place“near“the“bšMÞeginning“of“the“ le“(somewhere“b˜efore“the“ rst“functionŽ¡‘Gde nition–Ædin“the“ le),‘dor“else“should“go“in“a“header“ le.‘=ØDon't“put“¼extern“»declarationsŽ¡‘Ginside‘¦ffunctions.Ž¦‘!GIt–êused“to“bšMÞe“common“practice“to“use“the“same“lo˜cal“v‘ÿdDariables“(with“names“likš²!e“¼tem»)“o˜v˜erŽ¡‘Gand›¾Qo•²!v“er˜for˜di eren“t˜v‘ÿdDalues˜within˜one˜function.‘%žInstead˜of˜doing˜this,‘ÄLit˜is˜bMÞetter˜declareŽ¡‘Ga–ƒ«separate“lošMÞcal“v‘ÿdDariable“for“eac²!h“distinct“purp˜ose,‘Šand“givš²!e“it“a“name“whic˜h“is“meaningful.Ž¡‘GThis–C×not“only“makš²!es“programs“easier“to“understand,‘Wit“also“facilitates“optimization“b˜y“go•MÞo“dŽ¡‘Gcompilers.‘Ø›Y‘ÿeou–– can“also“mo•²!v“e–– the“declaration“of“eacš²!h“loMÞcal“v‘ÿdDariable“in˜to“the“smallest“scopMÞeŽ¡‘Gthat–¦fincludes“all“its“uses.‘ÝÝThis“makš²!es“the“program“ev˜en“cleaner.Ž¦‘!GDon't–¦fuse“loMÞcal“v‘ÿdDariables“or“parameters“that“shadoš²!w“global“iden˜ti ers.Ž¦‘!GDon't–ÍÄdeclare“m²!ultiple“v‘ÿdDariables“in“one“declaration“that“spans“lines.‘S÷Start“a“new“decla-Ž¡‘Gration–¦fon“eac²!h“line,“instead.‘ÝÝF‘ÿeor“example,“instead“of“this:Ž¤‰æ‘.ùœ¼int‘þ¨foo,ŽŸ ÿ‘W7Bbar;ŽŽŸã}‘G»write–¦feither“this:Ž¡‘.ùœ¼int–¿ªfoo,“bar;Ž¦‘G»or‘¦fthis:Ž¡‘.ùœ¼int‘¿ªfoo;ŽŸ €‘.ùœint‘¿ªbar;Ž¦‘G»(If–¦fthey“are“global“v‘ÿdDariables,“eacš²!h“should“ha˜v˜e“a“commen˜t“preceding“it“an˜yw˜a˜y‘ÿe.)Ž¦‘!GWhen–tyš²!ou“ha˜v˜e“an“¼if»-¼else“»statemen˜t“nested“in“another“¼if“»statemen˜t,‘"qalw˜a˜ys“put“bracesŽŸ 33‘Garound–¦fthe“¼if»-¼else».‘ÝÝThš²!us,“nev˜er“write“lik˜e“this:ŽŽŒ‹õ¶Ÿò‘G»Chapter–¦f5:‘ÝÝMaking“The“Best“Use“of“C’îXE29ŽŽŽ ƒ3* ý ÌÖ‘.ùœ¼if‘¿ª(foo)Ž¤ €‘:xðif‘¿ª(bar)Ž¡‘EøDwin‘¿ª();Ž¡‘:xðelseŽ¡‘EøDlose‘¿ª();Ž©Þf‘G»alw•²!a“ys›¦flik“e˜this:ŽŸ+3‘.ùœ¼if‘¿ª(foo)Ž¡‘:xð{Ž¡‘EøDif‘¿ª(bar)Ž¡‘Qw˜win‘¿ª();Ž¡‘EøDelseŽ¡‘Qw˜lose‘¿ª();Ž¡‘:xð}Ž¦‘!G»If–JAyš²!ou“ha˜v˜e“an“¼if“»statemen˜t“nested“inside“of“an“¼else“»statemen˜t,‘\¯either“write“¼else‘¦fif“»onŽŸ 33‘Gone–¦fline,“lik²!e“this,ŽŸ+3‘.ùœ¼if‘¿ª(foo)Ž¡‘:xð...ŽŽ¡‘.ùœelse–¿ªif“(bar)Ž¡‘:xð...ŽŽ¦‘G»with–çÜits“¼then»-part“indenš²!ted“lik˜e“the“preceding“¼then»-part,‘89or“write“the“nested“¼if“»withinŽŸ 33‘Gbraces–¦flik²!e“this:ŽŸ+3‘.ùœ¼if‘¿ª(foo)Ž¡‘:xð...ŽŽ¡‘.ùœelseŽ¡‘:xð{Ž¡‘EøDif‘¿ª(bar)Ž¡‘Qw˜...ŽŽ¡‘:xð}Ž¦‘!G»Don't–†Qdeclare“bšMÞoth“a“structure“tag“and“v‘ÿdDariables“or“t²!yp˜edefs“in“the“same“declaration.Ž¤ 33‘GInstead,‘+ declare–ÝPthe“structure“tag“separately“and“then“use“it“to“declare“the“v‘ÿdDariables“orŽ¡‘Gt²!ypMÞedefs.Ž¦‘!GT‘ÿery–¦fto“a•²!v“oid›¦fassignmen“ts˜inside˜¼if»-conditions.‘ÝÝF‘ÿeor˜example,˜don't˜write˜this:Ž¤+3‘.ùœ¼if–¿ª((foo“=“(char“*)“malloc“(sizeof“*foo))“==“0)ŽŸ €‘:xðfatal–¿ª("virtual“memory“exhausted");Ž¦‘G»instead,–¦fwrite“this:Ž¡‘.ùœ¼foo–¿ª=“(char“*)“malloc“(sizeof“*foo);Ž¤ €‘.ùœif–¿ª(foo“==“0)Ž¡‘:xðfatal–¿ª("virtual“memory“exhausted");Ž¦‘!G»Don't–P©makš²!e“the“program“ugly“to“placate“¼lint».‘ܦPlease“don't“insert“an˜y“casts“to“¼void».Ž¤ 33‘GZero–ðŠwithout“a“cast“is“pšMÞerfectly“ ne“as“a“n²!ull“p˜oinš²!ter“constan˜t,‘éexcept“when“calling“a“v‘ÿdDarargsŽ¡‘Gfunction.ŽŸ˜‘Gá5.4‘™Naming–f@V›þ¦fariables“and“F˜unctionsŽŽŸÞf‘!G»The–×names“of“global“v‘ÿdDariables“and“functions“in“a“program“servš²!e“as“commen˜ts“of“a“sort.Ž¡‘GSo–Ydon't“c²!hošMÞose“terse“names|instead,‘…¨lo˜ok“for“names“that“giv²!e“useful“information“ab˜outŽŽŒ‹ÿ\Ÿò‘G»Chapter–¦f5:‘ÝÝMaking“The“Best“Use“of“C’îXE30ŽŽŽ ƒ3* ý ÌÖ‘Gthe–~omeaning“of“the“v‘ÿdDariable“or“function.‘ЋIn“a“GNU‘~eprogram,›†nnames“should“bMÞe“English,˜lik²!eŽ¤ 33‘Gother‘¦fcommen²!ts.Ž©‘!GLošMÞcal–¸(v‘ÿdDariable“names“can“b˜e“shorter,‘ü˜b˜ecause“they“are“used“only“within“one“con²!text,Ž¡‘Gwhere–¦f(presumably)“commen²!ts“explain“their“purpMÞose.Ž¦‘!GT‘ÿery–3mto“limit“yš²!our“use“of“abbreviations“in“sym˜bMÞol“names.‘·ŠIt“is“ok“to“mak˜e“a“few“abbrevia-Ž¡‘Gtions,›…„explain–}Kwhat“they“mean,˜and“then“use“them“frequen²!tly‘ÿe,˜but“don't“use“lots“of“obscureŽ¡‘Gabbreviations.Ž¦‘!GPlease–\ôuse“underscores“to“separate“wš²!ords“in“a“name,‘k¥so“that“the“Emacs“w˜ord“commandsŽ¡‘Gcan–bMÞe“useful“within“them.‘™SSticš²!k“to“lo˜w˜er“case;‘!reserv˜e“uppMÞer“case“for“macros“and“¼enumŽ¡‘G»constanš²!ts,–¦fand“for“name-pre xes“that“follo˜w“a“uniform“con˜v˜en˜tion.Ž¦‘!GF‘ÿeor–ïzexample,‘¿yš²!ou“should“use“names“lik˜e“¼ignore_space_change_flag»;‘don't“use“namesŽ¡‘Glik²!e‘¦f¼iCantReadThis».Ž¦‘!GV‘ÿeariables–that“indicate“whether“command-line“options“ha•²!v“e–bšMÞeen“sp˜eci ed“should“b˜eŽ¡‘Gnamed–ƒafter“the“meaning“of“the“option,‘4not“after“the“option-letter.‘®to“a˜v˜oid“creating“gratuitous“problems“on“olderŽ¡‘GSystem–«ÛV‘«Ùsystems.›î;Y‘ÿeou“can“use“the“program“¼doschk“»to“test“for“this.˜¼doschk“»also“tests“forŽ¡‘GpMÞotenš²!tial–\name“con icts“if“the“ les“w˜ere“loaded“on˜to“an“MS-DOS‘[é le“system|somethingŽ¡‘Gy•²!ou›¦fma“y˜or˜ma“y˜not˜care˜abMÞout.ŽŸ!8>‘Gá5.5‘™P•ŒÌortabilit“y›f@bs3et“w“een˜System˜T“yps3esŽŽŸ‘!G»In–Zthe“Unix“w•²!orld,‘i_\pšMÞortabilit“y"–Zrefers“to“p˜orting“to“di erenš²!t“Unix“v˜ersions.‘ÄoF‘ÿeor“a“GNUŽ¡‘Gprogram,–¦fthis“kind“of“pMÞortabilitš²!y“is“desirable,“but“not“paramoun˜t.Ž¦‘!GThe–Õcprimary“purpMÞose“of“GNU›Õ.soft•²!w“are–Õcis“to“run“on“top“of“the“GNU˜k²!ernel,‘ÿ0compiled“withŽ¡‘Gthe›Ó•GNU–ÓŠC“compiler,‘Þáon˜v‘ÿdDarious˜t•²!ypMÞes˜of˜Ácpu».‘ekThe˜amoun“t˜and˜kinds˜of˜v‘ÿdDariation˜amongŽ¡‘GGNU‘½ßsystems–¾'on“di erenš²!t“Ácpu»s“will“bMÞe“comparable“to“the“v‘ÿdDariation“among“Lin˜ux-basedŽ¡‘GGNU›?Ïsystems–?éor“among“BSD˜systems“tošMÞda²!y‘ÿe.‘»´So“the“kinds“of“p˜ortabilit²!y“that“are“absolutelyŽ¡‘Gnecessary–¦fare“quite“limited.Ž¦‘!GBut–>émanš²!y“users“do“run“GNU‘>€soft˜w˜are“on“non-GNU‘>€Unix“or“Unix-lik˜e“systems.‘ §eSoŽ¡‘GsuppMÞorting–¦fa“v‘ÿdDarietš²!y“of“Unix-lik˜e“systems“is“desirable,“although“not“paramoun˜t.Ž¦‘!GThe–?…easiest“w•²!a“y–?…to“ac•²!hiev“e›?…pMÞortabilit“y˜to˜most˜Unix-lik“e˜systems˜is˜to˜use˜AutoMÞconf.‘»’It'sŽ¡‘Gunlikš²!ely–µöthat“y˜our“program“needs“to“kno˜w“more“information“abMÞout“the“host“platform“thanŽ¡‘GAutošMÞconf–"bcan“pro²!vide,‘<Ésimply“b˜ecause“most“of“the“programs“that“need“sucš²!h“kno˜wledge“ha˜v˜eŽ¡‘Galready–¦fbMÞeen“written.Ž¦‘!GAvš²!oid–¸(using“the“format“of“semi-in˜ternal“data“bases“(e.g.,‘ü™directories)“when“there“is“aŽ¡‘Ghigher-lev•²!el›¦falternativ“e˜(¼readdir»).Ž¦‘!GAs–l1for“systems“that“are“not“likš²!e“Unix,‘wÖsuc˜h“as“MSDOS,“Windo˜ws,‘wÖthe“Macin˜tosh,‘wÖVMS,Ž¡‘Gand–¦fMVS,“suppMÞorting“them“is“usually“so“m•²!uc“h›¦fw“ork˜that˜it˜is˜bMÞetter˜if˜y“ou˜don't.ŽŽŒ‹âŸò‘G»Chapter–¦f5:‘ÝÝMaking“The“Best“Use“of“C’îXE31ŽŽŽ ƒ3* ý ÌÖ‘!GThe–ôplanned“GNU‘ó®kš²!ernel“is“not“ nished“y˜et,‘Gkbut“y˜ou“can“tell“whic˜h“facilities“it“willŽ¤ 33‘Gpro•²!vide›˜Hb“y˜loMÞoking˜at˜the˜GNU–˜ C“Library˜Man²!ual.‘³‚The˜GNU“k•²!ernel˜is˜based˜on˜Mac“h,Ž¡‘Gso–ththe“features“of“Macš²!h“will“also“bMÞe“a˜v‘ÿdDailable.‘GäHo˜w˜ev˜er,‘§èif“y˜ou“use“Mac˜h“features,‘§èy˜ou'llŽ¡‘Gprobably›¦fha•²!v“e˜trouble˜debugging˜y“our˜program˜toMÞda“y‘ÿe.ŽŸ ÖÛ‘Gá5.6‘™P•ŒÌortabilit“y›f@bs3et“w“een˜çcpuásŽŽŸï‹‘!G»Evš²!en–ÓðGNU‘Ó£systems“will“di er“bMÞecause“of“di erences“among“Ácpu“»t˜ypMÞes|for“example,Ž¡‘Gdi erence–’win“bš²!yte“ordering“and“alignmen˜t“requiremen˜ts.‘×8It“is“absolutely“essen˜tial“to“handleŽ¡‘Gthese›n7di erences.‘5OHo•²!w“ev“er,‘ *don't˜mak“e˜an“y˜e ort˜to˜cater˜to˜the˜pMÞossibilit“y˜that˜an˜¼intŽ¡‘G»will–¦fbšMÞe“less“than“32“bits.‘ÝÝW‘ÿee“don't“supp˜ort“16-bit“mac²!hines“in“GNU.Ž©ï‹‘!GDon't–<ðassume“that“the“address“of“an“¼int“»ob‘›»ject“is“also“the“address“of“its“least-signi can²!tŽ¡‘Gbš²!yte.‘ÝÝThis–¦fis“false“on“big-endian“mac˜hines.‘ÝÝTh˜us,“don't“mak˜e“the“follo˜wing“mistak˜e:ŽŸ‚not“an“Áansi“»protot˜ypMÞe.‘²”The“more“y˜ou“spšMÞecify“ab˜out“the“function,‘>‚theŽ¡‘'¿«more–¦flik²!ely“a“con ict.Ž¦‘ ØÄŽ‘'¿«»In–¦fparticular,“don't“unconditionally“declare“¼malloc“»or“¼realloc».Ž¦‘'¿«Most–”%GNU‘” programs“use“those“functions“just“once,‘—Ëin“functions“con•²!v“en“tionally‘”%namedŽ¡‘'¿«¼xmalloc–K»and“¼xrealloc».‘˯These“functions“call“¼malloc“»and“¼realloc»,–t(respMÞectiv²!ely‘ÿe,“andŽ¡‘'¿«c•²!hec“k–¦fthe“results.Ž¦‘'¿«Because–ž¼xmalloc“»and“¼xrealloc“»are“de ned“in“yš²!our“program,‘Ÿ°y˜ou“can“declare“them“inŽ¡‘'¿«other–¦f les“without“anš²!y“risk“of“t˜ypMÞe“con ict.Ž¦‘'¿«On–(most“systems,›H‹¼int“»is“the“same“length“as“a“pMÞoin•²!ter;‘hùth“us,˜the–(calls“to“¼malloc“»andŽ¡‘'¿«¼realloc–[³»wš²!ork“ ne.‘Ä÷F‘ÿeor“the“few“exceptional“systems“(mostly“64-bit“mac˜hines),‘j¤y˜ou“canŽ¡‘'¿«use–Ös½conditionalized“»declarations“of“¼malloc“»and“¼realloc»|or“put“these“declarations“inŽ¡‘'¿«con guration–¦f les“spMÞeci c“to“those“systems.Ž¦‘ ØÄŽ‘'¿«»The–átstring“functions“require“spMÞecial“treatmenš²!t.‘Some“Unix“systems“ha˜v˜e“a“header“ leŽ¡‘'¿«`¼string.h»';‘T×others›Å\ha•²!v“e˜`¼strings.h»'.–:ÀNeither˜ le˜name˜is˜pMÞortable.“There˜are˜t•²!w“oŽ¡‘'¿«things–>cyš²!ou“can“do:‘ Öuse“AutoMÞconf“to“ gure“out“whic˜h“ le“to“include,‘daor“don't“includeŽ¡‘'¿«either‘¦f le.Ž¦‘ ØÄŽ‘'¿«»If–ßâyš²!ou“don't“include“either“strings“ le,‘–y˜ou“can't“get“declarations“for“the“string“functionsŽ¡‘'¿«from–¦fthe“header“ le“in“the“usual“w•²!a“y‘ÿe.Ž¦‘'¿«That–Å causes“less“of“a“problem“than“yš²!ou“migh˜t“think.‘9ÒThe“new˜er“Áansi“»string“functionsŽ¡‘'¿«should–œ7bMÞe“a•²!v“oided›œ7an“yw“a“y˜bMÞecause˜man“y˜systems˜still˜don't˜suppMÞort˜them.‘ÚxThe˜stringŽ¡‘'¿«functions–¦fy²!ou“can“use“are“these:ŽŸG®‘D¨¼strcpy–>þstrncpy“strcat“strncatŽ¤ €‘D¨strlen‘>þstrcmp‘þ¨strncmpŽ¡‘D¨strchr‘>þstrrchrŽ¦‘'¿«»The–± copš²!y“and“concatenate“functions“w˜ork“ ne“without“a“declaration“as“long“as“y˜ouŽ¤ 33‘'¿«don't–ˆÖuse“their“v›ÿdDalues.‘ÔUsing“their“v˜alues“without“a“declaration“fails“on“systems“whereŽ¡‘'¿«the–ÏTwidth“of“a“pšMÞoin²!ter“di ers“from“the“width“of“¼int»,‘Ùand“p˜erhaps“in“other“cases.‘X¨It“isŽ¡‘'¿«trivial–¦fto“a•²!v“oid–¦fusing“their“v‘ÿdDalues,“so“do“that.ŽŽŒ‹!#‘Ÿò‘G»Chapter–¦f5:‘ÝÝMaking“The“Best“Use“of“C’îXE33ŽŽŽ ƒ3* ý ÌÖ‘'¿«The–äÑcompare“functions“and“¼strlen“»w²!ork“ ne“without“a“declaration“on“most“systems,Ž¤ 33‘'¿«pMÞossibly–|fall“the“ones“that“GNU‘|[soft•²!w“are–|fruns“on.‘ÏÝY‘ÿeou“ma²!y“ nd“it“necessary“to“declareŽ¡‘'¿«them–¦f½conditionally“»on“a“few“systems.Ž©Üb‘'¿«The–’ searcš²!h“functions“m˜ust“bMÞe“declared“to“return“¼char‘¦f*».‘×FLuc˜kily‘ÿe,‘–•there“is“no“v‘ÿdDariationŽ¡‘'¿«in–^$the“data“t²!ypMÞe“they“return.›ÅÇBut“there“is“v‘ÿdDariation“in“their“names.˜Some“systems“giv²!eŽ¡‘'¿«these–ýfunctions“the“names“¼index“»and“¼rindex»;‘Iuother“systems“use“the“names“¼strchr“»andŽ¡‘'¿«¼strrchr».‘ SSome–‘ãsystems“suppšMÞort“b˜oth“pairs“of“names,‘ÌÁbut“neither“pair“w²!orks“on“allŽ¡‘'¿«systems.Ž¦‘'¿«Y‘ÿeou– 'should“picš²!k“a“single“pair“of“names“and“use“it“throughout“y˜our“program.‘K!(No˜w˜a-Ž¡‘'¿«daš²!ys,‘ºit–‹Pis“bMÞetter“to“c˜hoMÞose“¼strchr“»and“¼strrchr“»for“new“programs,‘ºsince“those“are“theŽ¡‘'¿«standard–3Áansi“»names.)›·jDeclare“bMÞoth“of“those“names“as“functions“returning“¼char‘¦f*».˜OnŽ¡‘'¿«systems–Xwhic²!h“don't“suppMÞort“those“names,‘g¼de ne“them“as“macros“in“terms“of“the“otherŽ¡‘'¿«pair.‘®F‘ÿeor–²example,‘´èhere“is“what“to“put“at“the“bMÞeginning“of“y²!our“ le“(or“in“a“header)“ifŽ¡‘'¿«y•²!ou›¦fw“an“t˜to˜use˜the˜names˜¼strchr˜»and˜¼strrchr˜»throughout:ŽŸ)/‘D¨¼#ifndef‘¿ªHAVE_STRCHRŽ¤ €‘D¨#define–¿ªstrchr“indexŽ¡‘D¨#endifŽ¡‘D¨#ifndef‘¿ªHAVE_STRRCHRŽ¡‘D¨#define–¿ªstrrchr“rindexŽ¡‘D¨#endifŽŸ‘D¨char–¿ª*strchr“();Ž¡‘D¨char–¿ª*strrchr“();ŽŸ.¿‘!G»Here–¬ñw²!e“assume“that“¼HAVE_STRCHR“»and“¼HAVE_STRRCHR“»are“macros“de ned“in“systemsŽ¤ 33‘Gwhere–8áthe“correspšMÞonding“functions“exist.‘•MOne“w•²!a“y–8áto“get“them“prop˜erly“de ned“is“to“useŽ¡‘GAutoMÞconf.ŽŸ"Mé‘Gá5.8‘™InŒÌternationalizationŽŽŸ…‘!G»GNU›JBhas–JYa“library“called“GNU˜gettext“that“mak²!es“it“easy“to“translate“the“messages“in“aŽ¡‘Gprogram–U¡inš²!to“v‘ÿdDarious“languages.‘ÂñY‘ÿeou“should“use“this“library“in“ev˜ery“program.‘ÂñUse“EnglishŽ¡‘Gfor–ð the“messages“as“they“appMÞear“in“the“program,‘„and“let“gettext“proš²!vide“the“w˜a˜y“to“translateŽ¡‘Gthem–¦fin²!to“other“languages.Ž©…‘!GUsing–ùGNU‘øçgettext“in•²!v“olv“es–ùputting“a“call“to“the“¼gettext“»macro“around“eac²!h“string“thatŽ¡‘Gmighš²!t–¦fneed“translation|lik˜e“this:ŽŸÒ]‘.ùœ¼printf–¿ª(gettext“("Processing“file“`%s'..."));Ž¦‘G»This–[ÀpMÞermits“GNU‘[­gettext“to“replace“the“string“¼"Processing–¦ffile“`%s'..."–[À»with“a“trans-Ž¡‘Glated‘¦fv²!ersion.Ž¦‘!GOnce–€÷a“program“uses“gettext,‘ˆtplease“makš²!e“a“pMÞoin˜t“of“writing“calls“to“¼gettext“»when“y˜ouŽ¡‘Gadd–¦fnew“strings“that“call“for“translation.Ž¦‘!GUsing–¸GNU‘ gettext“in“a“pacš²!k‘ÿdDage“in˜v˜olv˜es“spMÞecifying“a“¿text“domain“name‘£¿»for“the“pac˜k-Ž¡‘Gage.‘ÇrThe–ôBtext“domain“name“is“used“to“separate“the“translations“for“this“pac²!k‘ÿdDage“from“theŽ¡‘Gtranslations–;«for“other“pac²!k‘ÿdDages.‘ºINormally‘ÿe,‘Qthe“text“domain“name“should“bMÞe“the“same“as“theŽ¡‘Gname–¦fof“the“pac²!k‘ÿdDage|for“example,“`¼fileutils»'“for“the“GNU“ le“utilities.ŽŽŒ‹"2ŽŸò‘G»Chapter–¦f6:‘ÝÝDoMÞcumen²!ting“Programs’ýf¬34ŽŽŽ ƒ3* ý ÌÖ‘!GT‘ÿeo–F½enable“gettext“to“wš²!ork“w˜ell,‘nÒa˜v˜oid“writing“coMÞde“that“mak˜es“assumptions“abMÞout“theŽ¤ 33‘Gstructure–á†of“wš²!ords“or“sen˜tences.‘>When“y˜ou“w˜an˜t“the“precise“text“of“a“sen˜tence“to“v‘ÿdDaryŽ¡‘GdepMÞending–8\on“the“data,‘œÙuse“t•²!w“o–8\or“more“alternativš²!e“string“constan˜ts“eac˜h“con˜taining“aŽ¡‘Gcomplete–žsenš²!tences,‘\+rather“than“inserting“conditionalized“w˜ords“or“phrases“in˜to“a“singleŽ¡‘Gsen•²!tence‘¦fframew“ork.Ž¤³3‘!GHere–¦fis“an“example“of“what“not“to“do:Ž©‘.ùœ¼printf–¿ª("%d“file%s“processed",“nfiles,ŽŸ €‘\öìnfiles–¿ª!=“1“?“"s"“:“"");Ž¡‘G»The–ð^problem“with“that“example“is“that“it“assumes“that“plurals“are“made“b²!y“adding“`s'.‘»ÄIfŽŸ 33‘Gyš²!ou–¦fapply“gettext“to“the“format“string,“lik˜e“this,Ž¦‘.ùœ¼printf–¿ª(gettext“("%d“file%s“processed"),“nfiles,ŽŸ €‘\öìnfiles–¿ª!=“1“?“"s"“:“"");Ž¡‘G»the–`gmessage“can“use“di erenš²!t“w˜ords,‘ngbut“it“will“still“bMÞe“forced“to“use“`s'“for“the“plural.‘ƈHereŽŸ 33‘Gis–¦fa“bMÞetter“w•²!a“y:Ž¦‘.ùœ¼printf–¿ª((nfiles“!=“1“?“"%d“files“processed"Ž¤ €‘b¶–:–¿ª"%d“file“processed"),Ž¡‘\öìnfiles);ŽŸ³3‘G»This›¦fw•²!a“y‘ÿe,˜y“ou˜can˜apply˜gettext˜to˜eac“h˜of˜the˜t“w“o˜strings˜indepMÞenden“tly:Ž¦‘.ùœ¼printf–¿ª((nfiles“!=“1“?“gettext“("%d“files“processed")Ž¡‘b¶–:–¿ªgettext“("%d“file“processed")),Ž¡‘\öìnfiles);Ž¤³3‘G»This–tried_implicit–¿ª?“""“:“"“not");Ž¡‘G»Adding–Êy¼gettext“»calls“to“this“cošMÞde“cannot“giv²!e“correct“results“for“all“languages,‘~b˜ecauseŽ¤ 33‘Gnegation–ÃPin“some“languages“requires“adding“wš²!ords“at“more“than“one“place“in“the“sen˜tence.Ž¡‘GBy–جconš²!trast,‘å=adding“¼gettext“»calls“doMÞes“the“job“straigh˜tfo˜w˜ardly“if“the“coMÞde“starts“out“lik˜eŽ¡‘Gthis:Ž¦‘.ùœ¼printf‘¿ª(f->tried_implicitŽ¤ €‘\öì?–¿ª"#‘ TImplicit“rule“search“has“been“done.\n",Ž¡‘\öì:–¿ª"#‘ TImplicit“rule“search“has“not“been“done.\n");ŽŸÿ‘Gá5.9‘™MmapŽŽŸ³3‘!G»Don't–…±assume“that“¼mmap“»either“wš²!orks“on“all“ les“or“fails“for“all“ les.‘{½It“ma˜y“w˜ork“onŽ¤ 33‘Gsome–¦f les“and“fail“on“others.Ž©³3‘!GThe–PjpropšMÞer“w•²!a“y–Pjto“use“¼mmap“»is“to“try“it“on“the“sp˜eci c“ le“for“whicš²!h“y˜ou“w˜an˜t“to“useŽ¡‘Git|and–>if“¼mmap“»doMÞesn't“wš²!ork,‘ʳfall“bac˜k“on“doing“the“job“in“another“w˜a˜y“using“¼read“»andŽ¡‘G¼write».Ž¦‘!GThe–}Nreason“this“precaution“is“needed“is“that“the“GNU›}k²!ernel“(the“HURD)˜pro²!vides“aŽ¡‘Guser-extensible–ýô le“system,‘×in“whicš²!h“there“can“bMÞe“man˜y“di eren˜t“kinds“of“\ordinary“ les."Ž¡‘GMan²!y–C›of“them“suppšMÞort“¼mmap»,‘W]but“some“do“not.‘¼ïIt“is“imp˜ortanš²!t“to“mak˜e“programs“handle“allŽ¡‘Gthese–¦fkinds“of“ les.ŽŽŒ‹#?PŸò‘G»Chapter–¦f6:‘ÝÝDoMÞcumen²!ting“Programs’ýf¬35ŽŽŽ ƒ3* ý ÌÖ‘GØ6‘ ¸QDo‘Š=cumen‘ÿuÂting‘z³ProgramsŽŽŸ0""‘Gá6.1‘™GNU‘f@ManŒÌualsŽŽŸW:‘!G»The–™mpreferred“w•²!a“y–™mto“doMÞcumenš²!t“part“of“the“GNU‘™.system“is“to“write“a“man˜ual“in“theŽ¤ 33‘GT‘ÿeexinfo–)formatting“language.‘ñ'This“mak²!es“it“pšMÞossible“to“pro˜duce“a“go˜o˜d“qualit²!y“formattedŽ¡‘Gb•MÞo“ok,‘…using–|¹T‘þ,³Ÿ[wEŽ‘B X,“and“to“generate“an“Info“ le.‘ÏùIt“is“also“pMÞossible“to“generate“HTML‘|®outputŽ¡‘Gfrom–O0T›ÿeexinfo“source.‘Ø;See“the“T˜exinfo“manš²!ual,‘ybeither“the“hardcop˜y‘ÿe,‘ybor“the“on-line“v˜ersionŽ¡‘Ga²!v‘ÿdDailable–¦fthrough“¼info“»or“the“Emacs“Info“subsystem“(óßêplease“cop˜y“the“distribution“terms“of“the“GNUŽ¡‘GEmacs–\‘Manš²!ual,‘Šand“adapt“it“b˜y“mošMÞdifying“appropriately“the“list“of“sp˜ecial“c²!hapters“thatŽ¡‘Gma²!y–¦fnot“bšMÞe“mo˜di ed“or“deleted.Ž¦‘!GIf–š"the“manš²!ual“doMÞes“not“con˜tain“an˜y“suc˜h“c˜hapters,‘œ–then“imitate“the“simpler“distributionŽ¡‘Gterms–¦fof“the“T‘ÿeexinfo“man²!ual.ŽŽŒ‹%\žŸò‘G»Chapter–¦f6:‘ÝÝDoMÞcumen²!ting“Programs’ýf¬37ŽŽŽ ƒ3* ý ÌÖ‘Gá6.4‘™The–f@NEWS“FileŽŽ©Œ‘!G»In–addition“to“its“manš²!ual,‘6jthe“pac˜k‘ÿdDage“should“ha˜v˜e“a“ le“named“`¼NEWS»'“whic˜h“con˜tainsŽ¤ 33‘Ga–ŠØlist“of“user-visible“cš²!hanges“w˜orth“men˜tioning.‘Ô®In“eac˜h“new“release,‘[add“items“to“the“fron˜tŽ¡‘Gof–Ù¾the“ le“and“idenš²!tify“the“v˜ersion“they“pMÞertain“to.‘wåDon't“discard“old“items;‘ójlea˜v˜e“them“inŽ¡‘Gthe–?k le“after“the“newš²!er“items.‘¨ìThis“w˜a˜y‘ÿe,‘e¬a“user“upgrading“from“an˜y“previous“v˜ersion“canŽ¡‘Gsee–¦fwhat“is“new.ŽŸŒ‘!GIf–ǽthe“`¼NEWS»'“ le“gets“vš²!ery“long,‘Ðmo˜v˜e“some“of“the“older“items“in˜to“a“ le“named“`¼ONEWS»'Ž¡‘Gand–¦fput“a“note“at“the“end“referring“the“user“to“that“ le.ŽŸ&B^‘Gá6.5‘™Change‘f@LogsŽŽ¦‘!G»Keep–®a“cš²!hange“log“to“describMÞe“all“the“c˜hanges“made“to“program“source“ les.‘¨õThe“purpMÞoseŽ¡‘Gof–pÄthis“is“so“that“pšMÞeople“in•²!v“estigating–pÄbugs“in“the“future“will“kno²!w“ab˜out“the“c²!hangesŽ¡‘Gthat–oŒmighš²!t“ha˜v˜e“in˜trošMÞduced“the“bug.‘9POften“a“new“bug“can“b˜e“found“b²!y“lo˜oking“at“whatŽ¡‘Gw•²!as›–Àrecen“tly˜c“hanged.‘®ëMore˜impMÞortan“tly‘ÿe,‘ÒÖc“hange˜logs˜can˜help˜y“ou˜eliminate˜conceptualŽ¡‘Ginconsistencies›—^bMÞet•²!w“een˜di eren“t˜parts˜of˜a˜program,‘Óœb“y˜giving˜y“ou˜a˜history˜of˜ho“w˜theŽ¡‘Gcon icting–¦fconcepts“arose“and“who“they“came“from.ŽŸ β‘Gó?ÂÖN  #× cmbx12ê6.5.1‘d(Change–íMLog“ConceptsŽŽ¦‘!G»Y‘ÿeou–ÂÞcan“think“of“the“cš²!hange“log“as“a“conceptual“\undo“list"“whic˜h“explains“ho˜w“earlierŽ¡‘Gv•²!ersions›.‰w“ere˜di eren“t˜from˜the˜curren“t˜v“ersion.‘vEP“eople˜can˜see˜the˜curren“t˜v“ersion;‘rštheyŽ¡‘Gdon't–½need“the“cš²!hange“log“to“tell“them“what“is“in“it.‘!µWhat“they“w˜an˜t“from“a“c˜hange“log“isŽ¡‘Ga–¦fclear“explanation“of“hoš²!w“the“earlier“v˜ersion“di ered.Ž©Œ‘!GThe–Äocš²!hange“log“ le“is“normally“called“`¼ChangeLog»'“and“co˜v˜ers“an“en˜tire“directory‘ÿe.‘7øEac˜hŽ¡‘Gdirectory–‰can“ha•²!v“e–‰its“oš²!wn“c˜hange“log,‘0or“a“directory“can“use“the“c˜hange“log“of“its“paren˜tŽ¡‘Gdirectory{it's–¦fup“to“y²!ou.Ž¦‘!GAnother–g©alternativš²!e“is“to“record“c˜hange“log“information“with“a“v˜ersion“con˜trol“systemŽ¡‘Gsucš²!h–Bas“R˜CS‘Ašor“CVS.“This“can“bMÞe“con˜v˜erted“automatically“to“a“`¼ChangeLog»'“ le“usingŽ¡‘G¼rcs2log»;–¦fin“Emacs,“the“command“ÂC-x“v“a“»(¼vc-update-change-log»)“doMÞes“the“job.Ž¦‘!GThere's–ù&no“need“to“describšMÞe“the“full“purp˜ose“of“the“cš²!hanges“or“ho˜w“they“w˜ork“together.‘¤IfŽ¡‘Gyš²!ou–fóthink“that“a“c˜hange“calls“for“explanation,‘s¤y˜ou're“probably“righ˜t.‘È·Please“do“explain“it|Ž¡‘Gbut–•Žplease“put“the“explanation“in“commen²!ts“in“the“cošMÞde,‘˜ìwhere“p˜eople“will“see“it“whenev²!erŽ¡‘Gthey–<ésee“the“coMÞde.‘º´F‘ÿeor“example,‘R\New“function"“is“enough“for“the“cš²!hange“log“when“y˜ou“addŽ¡‘Ga–£function,‘âCbšMÞecause“there“should“b˜e“a“commen²!t“b˜efore“the“function“de nition“to“explainŽ¡‘Gwhat–¦fit“doMÞes.Ž¦‘!GHo•²!w“ev“er,‘ϸsometimes–”Bit“is“useful“to“write“one“line“to“describšMÞe“the“o•²!v“erall–”Bpurp˜ose“of“aŽ¡‘Gbatcš²!h–¦fof“c˜hanges.Ž¦‘!GThe–Ð easiest“w•²!a“y–Ð to“add“an“en²!try“to“`¼ChangeLog»'“is“with“the“Emacs“command“ÂM-x‘¦fadd-Ž¡‘Gchange-log-entry».‘˜üAn–:enš²!try“should“ha˜v˜e“an“asterisk,‘_the“name“of“the“c˜hanged“ le,‘_andŽ¡‘Gthen–Ö×in“parenš²!theses“the“name“of“the“c˜hanged“functions,‘âôv‘ÿdDariables“or“whatev˜er,‘âôfollo˜w˜ed“b˜yŽ¡‘Ga–¦fcolon.‘ÝÝThen“describMÞe“the“cš²!hanges“y˜ou“made“to“that“function“or“v‘ÿdDariable.ŽŽŒ‹&iuŸò‘G»Chapter–¦f6:‘ÝÝDoMÞcumen²!ting“Programs’ýf¬38ŽŽŽ ƒ3* ý ÌÖ‘Gê6.5.2‘d(St–áyle–íMof“Change“LogsŽŽŸÿÿ‘!G»Here–¦fare“some“examples“of“cš²!hange“log“en˜tries:ŽŸLÌ‘.ùœ¼*–¿ªregister.el“(insert-register):“Return“nil.Ž© €‘.ùœ(jump-to-register):‘¿ªLikewise.Ž¤‘.ùœ*–¿ªsort.el“(sort-subr):“Return“nil.Ž¡‘.ùœ*–¿ªtex-mode.el“(tex-bibtex-file,“tex-file,“tex-region):Ž¦‘.ùœRestart–¿ªthe“tex“shell“if“process“is“gone“or“stopped.Ž¦‘.ùœ(tex-shell-running):–¿ªNew“function.Ž¡‘.ùœ*–¿ªexpr.c“(store_one_arg):“Round“size“up“for“move_block_to_reg.Ž¦‘.ùœ(expand_call):–¿ªRound“up“when“emitting“USE“insns.Ž¦‘.ùœ*–¿ªstmt.c“(assign_parms):“Round“size“up“for“move_block_from_reg.Ž©ÿÿ‘!G»It's–‹simpMÞortanš²!t“to“name“the“c˜hanged“function“or“v‘ÿdDariable“in“full.‘ŒDon't“abbreviate“functionŽ¤ 33‘Gor– cv‘ÿdDariable“names,‘#cand“don't“comš²!bine“them.‘ ÕSubsequen˜t“main˜tainers“will“often“searc˜h“forŽ¡‘Ga–ò{function“name“to“ nd“all“the“cš²!hange“log“en˜tries“that“pMÞertain“to“it;‘…if“y˜ou“abbreviate“theŽ¡‘Gname,–¦fthey“wš²!on't“ nd“it“when“they“searc˜h.Ž¦‘!GF‘ÿeor–Éyexample,‘õ¨some“pMÞeople“are“tempted“to“abbreviate“groups“of“function“names“b²!y“writingŽ¡‘G`¼*–¦fregister.el“({insert,jump-to}-register)»';‘icthis–(dis“not“a“go•MÞo“d–(didea,‘Häsince“searc²!hingŽ¡‘Gfor–¦f¼jump-to-register“»or“¼insert-register“»wš²!ould“not“ nd“that“en˜try‘ÿe.Ž¦‘!GSeparate–÷Æunrelated“cš²!hange“log“en˜tries“with“blank“lines.‘£¨When“t˜w˜o“en˜tries“represen˜t“partsŽ¡‘Gof–Í“the“same“cš²!hange,‘×_so“that“they“w˜ork“together,‘×_then“don't“put“blank“lines“bMÞet˜w˜een“them.Ž¡‘GThen–óÆyš²!ou“can“omit“the“ le“name“and“the“asterisk“when“successiv˜e“en˜tries“are“in“the“sameŽ¡‘G le.ŽŸ$™™‘Gê6.5.3‘d(Simple‘íMChangesŽŽŸÿÿ‘!G»Certain–¦fsimple“kinds“of“cš²!hanges“don't“need“m˜uc˜h“detail“in“the“c˜hange“log.Ž¦‘!GWhen–UÑyš²!ou“c˜hange“the“calling“sequence“of“a“function“in“a“simple“fashion,‘eïand“y˜ou“c˜hangeŽ¡‘Gall–£&the“callers“of“the“function,‘£Ìthere“is“no“need“to“makš²!e“individual“en˜tries“for“all“the“callersŽ¡‘Gthat–‰Žyš²!ou“c˜hanged.‘~êJust“write“in“the“en˜try“for“the“function“bMÞeing“called,‘†\All“callers“c˜hanged."ŽŸLÌ‘.ùœ¼*–¿ªkeyboard.c“(Fcommand_execute):“New“arg“SPECIAL.ŽŸ €‘.ùœAll–¿ªcallers“changed.Ž¦‘!G»When–(yš²!ou“c˜hange“just“commen˜ts“or“doMÞc“strings,‘:Ùit“is“enough“to“write“an“en˜try“for“theŽ¡‘G le,–¦fwithout“menš²!tioning“the“functions.‘ÝÝJust“\DoMÞc“ xes"“is“enough“for“the“c˜hange“log.Ž¦‘!GThere's–Í,no“need“to“makš²!e“c˜hange“log“en˜tries“for“doMÞcumen˜tation“ les.‘R.This“is“bMÞecauseŽ¡‘GdošMÞcumen²!tation–®žis“not“susceptible“to“bugs“that“are“hard“to“ x.‘ö†Do˜cumen²!tation“do˜es“notŽ¡‘Gconsist–5öof“parts“that“mš²!ust“in˜teract“in“a“precisely“engineered“fashion.‘ŒŒT‘ÿeo“correct“an“error,Ž¡‘Gyš²!ou–°Æneed“not“kno˜w“the“history“of“the“erroneous“passage;‘µöit“is“enough“to“compare“what“theŽ¡‘GdoMÞcumen•²!tation›¦fsa“ys˜with˜the˜w“a“y˜the˜program˜actually˜w“orks.ŽŽŒ‹'wÍŸò‘G»Chapter–¦f6:‘ÝÝDoMÞcumen²!ting“Programs’ýf¬39ŽŽŽ ƒ3* ý ÌÖ‘Gê6.5.4‘d(Conditional‘íMChangesŽŽŸ‘!G»C‘75programs–7Roften“conš²!tain“compile-time“¼#if“»conditionals.‘¸ÖMan˜y“c˜hanges“are“conditional;Ž¤ 33‘Gsometimes–²Myš²!ou“add“a“new“de nition“whic˜h“is“en˜tirely“con˜tained“in“a“conditional.‘“It“is“v˜eryŽ¡‘Guseful–¦fto“indicate“in“the“cš²!hange“log“the“conditions“for“whic˜h“the“c˜hange“applies.Ž©‘!GOur›ì_con•²!v“en“tion˜for˜indicating˜conditional˜c“hanges˜is˜to˜use˜square˜brac“k“ets˜around˜theŽ¡‘Gname–¦fof“the“condition.Ž¦‘!GHere–À[is“a“simple“example,‘ÆÙdescribing“a“cš²!hange“whic˜h“is“conditional“but“doMÞes“not“ha˜v˜e“aŽ¡‘Gfunction–¦for“en•²!tit“y–¦fname“assoMÞciated“with“it:ŽŸ\‘.ùœ¼*–¿ªxterm.c“[SOLARIS2]:“Include“string.h.Ž¦‘!G»Here–íàis“an“enš²!try“describing“a“new“de nition“whic˜h“is“en˜tirely“conditional.‘´JThis“newŽ¡‘Gde nition–¦ffor“the“macro“¼FRAME_WINDOW_P“»is“used“only“when“¼HAVE_X_WINDOWS“»is“de ned:ŽŸ\‘.ùœ¼*–¿ªframe.h“[HAVE_X_WINDOWS]“(FRAME_WINDOW_P):“Macro“defined.Ž¦‘!G»Here–ÚÄis“an“enš²!try“for“a“c˜hange“within“the“function“¼init_display»,‘gÛwhose“de nitionŽ¡‘Gas–V‘a“whole“is“unconditional,‘šbut“the“cš²!hanges“themselv˜es“are“con˜tained“in“a“`¼#ifdefŽ¡‘GHAVE_LIBNCURSES»'‘¦fconditional:Ž¤\‘.ùœ¼*–¿ªdispnew.c“(init_display)“[HAVE_LIBNCURSES]:“If“X,“call“tgetent.Ž¦‘!G»Here–]ãis“an“enš²!try“for“a“c˜hange“that“tak˜es“a ect“only“when“a“certain“macro“is“¾not‘gÍ»de ned:Ž¡‘.ùœ¼(gethostname)–¿ª[!HAVE_SOCKETS]:“Replace“with“winsock“version.ŽŸ%ff‘Gá6.6‘™Man‘f@PŒÌagesŽŽŸ‘!G»In–‡/the“GNU‘‡'pro‘›»ject,‘mman“pages“are“secondary‘ÿe.‘ÓuIt“is“not“necessary“or“expMÞected“for“ev²!eryŽ¤ 33‘GGNU‘Ô}program–Ô²to“ha•²!v“e–Ô²a“man“page,‘þ£but“some“of“them“do.‘—÷It's“yš²!our“c˜hoice“whether“to“includeŽ¡‘Ga–¦fman“page“in“y²!our“program.Ž¦‘!GWhen–$Êyš²!ou“mak˜e“this“decision,‘Dcconsider“that“suppMÞorting“a“man“page“requires“con˜tin˜ualŽ¡‘Ge ort–þeacš²!h“time“the“program“is“c˜hanged.‘¥ÄThe“time“y˜ou“spMÞend“on“the“man“page“is“time“tak˜enŽ¡‘Ga•²!w“a“y–¦ffrom“more“useful“w²!ork.Ž¦‘!GF‘ÿeor–º;a“simple“program“whicš²!h“c˜hanges“little,‘¿0upMÞdating“the“man“page“ma˜y“bMÞe“a“small“job.Ž¡‘GThen–¦fthere“is“little“reason“not“to“include“a“man“page,“if“yš²!ou“ha˜v˜e“one.Ž¦‘!GF‘ÿeor–Ça“large“program“that“cš²!hanges“a“great“deal,‘ó¼upMÞdating“a“man“page“ma˜y“bMÞe“a“substan˜tialŽ¡‘Gburden.‘š@If–Ûa“user“o ers“to“donate“a“man“page,‘yš²!ou“ma˜y“ nd“this“gift“costly“to“accept.‘š@It“ma˜yŽ¡‘Gb•MÞe›ù#b“etter˜to˜refuse˜the˜man˜page˜unless˜the˜same˜p“erson˜agrees˜to˜tak²!e˜full˜resp“onsibilit²!y˜forŽ¡‘Gmainš²!taining–”it|so“that“y˜ou“can“w˜ash“y˜our“hands“of“it“en˜tirely‘ÿe.‘°—If“this“v˜olun˜teer“later“ceasesŽ¡‘Gto–þdo“the“job,‘ìthen“don't“feel“obliged“to“picš²!k“it“up“y˜ourself;‘)Ôit“ma˜y“bšMÞe“b˜etter“to“withdra²!wŽ¡‘Gthe–¦fman“page“from“the“distribution“un²!til“someone“else“agrees“to“upMÞdate“it.Ž¦‘!GWhen–²œa“program“cš²!hanges“only“a“little,‘õ©y˜ou“ma˜y“feel“that“the“discrepancies“are“smallŽ¡‘Genough–>Åthat“the“man“page“remains“useful“without“upMÞdating.‘¦ûIf“so,‘dÝput“a“prominen²!t“noteŽ¡‘Gnear–¼the“bMÞeginning“of“the“man“page“explaining“that“yš²!ou“don't“main˜tain“it“and“that“theŽ¡‘GT‘ÿeexinfo–=`manš²!ual“is“more“authoritativ˜e.‘ ¢ËThe“note“should“sa˜y“ho˜w“to“access“the“T‘ÿeexinfoŽ¡‘GdoMÞcumen²!tation.ŽŽŒ‹(ƒÛŸò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e40ŽŽŽ ƒ3* ý ÌÖ‘Gá6.7‘™Reading–f@other“ManŒÌualsŽŽ©ÝÞ‘!G»There–¬Jma²!y“bšMÞe“non-free“b˜o˜oks“or“do˜cumen²!tation“ les“that“describ˜e“the“program“y²!ou“areŽ¤ 33‘GdoMÞcumen²!ting.ŽŸÝÞ‘!GIt–Ê is“ok“to“use“these“došMÞcumen²!ts“for“reference,‘ö•just“as“the“author“of“a“new“algebra“textb˜o˜okŽ¡‘Gcan–´˜read“other“b•MÞo“oks–´˜on“algebra.‘rA‘´”large“pšMÞortion“of“an²!y“non- ction“b˜o˜ok“consists“of“facts,Ž¡‘Gin–Athis“case“facts“abMÞout“hoš²!w“a“certain“program“w˜orks,‘hkand“these“facts“are“necessarily“theŽ¡‘Gsame–{for“ev•²!ery“one–{who“writes“abšMÞout“the“sub‘›»ject.‘CBut“b˜e“careful“not“to“copš²!y“y˜our“outlineŽ¡‘Gstructure,–Cwš²!ording,“tables–ÿor“examples“from“preexisting“non-free“doMÞcumen˜tation.‘çïCop˜yingŽ¡‘Gfrom–¦ffree“doMÞcumenš²!tation“ma˜y“bMÞe“ok;“please“c˜hec˜k“with“the“FSF“abMÞout“the“individual“case.ŽŸ#UU‘GØ7‘ ¸QThe–z³Release“Pro‘Š=cessŽŽŸ33‘!G»Making–@£a“release“is“more“than“just“bundling“up“y²!our“source“ les“in“a“tar“ le“and“puttingŽ¡‘Git–[òup“for“FTP›ÿe.“Y˜ou“should“set“up“yš²!our“soft˜w˜are“so“that“it“can“bMÞe“con gured“to“run“on“aŽ¡‘Gv‘ÿdDarietš²!y–Úôof“systems.‘{ˆY‘ÿeour“Mak˜e le“should“conform“to“the“GNU‘Úçstandards“describšMÞed“b˜elo²!w,Ž¡‘Gand–ÀYyš²!our“directory“la˜y˜out“should“also“conform“to“the“standards“discussed“bMÞelo˜w.‘+µDoing“soŽ¡‘Gmakš²!es–¦fit“easy“to“include“y˜our“pac˜k‘ÿdDage“in˜to“the“larger“framew˜ork“of“all“GNU“soft˜w˜are.ŽŸ ªª‘Gá7.1‘™HoŒÌw–f@Con guration“Should“W‘þ¦forkŽŽ¦‘!G»Eac²!h–îZGNU‘îGdistribution“should“come“with“a“shell“script“named“¼configure».‘µ¸This“scriptŽ¡‘Gis–EÖgivš²!en“argumen˜ts“whic˜h“describMÞe“the“kind“of“mac˜hine“and“system“y˜ou“w˜an˜t“to“compile“theŽ¡‘Gprogram‘¦ffor.Ž©ÝÞ‘!GThe–Ú7¼configure“»script“m²!ust“record“the“con guration“options“so“that“they“a ect“compi-Ž¡‘Glation.Ž¦‘!GOne› ºw•²!a“y˜to˜do˜this˜is˜to˜mak“e˜a˜link˜from˜a˜standard˜name˜suc“h˜as˜`¼config.h»'˜to˜theŽ¡‘GpropMÞer–í]con guration“ le“for“the“cš²!hosen“system.‘²ÃIf“y˜ou“use“this“tec˜hnique,‘ÿthe“distributionŽ¡‘Gshould–éÓ¾not‘ó½»conš²!tain“a“ le“named“`¼config.h»'.‘¨#This“is“so“that“pMÞeople“w˜on't“bMÞe“able“to“buildŽ¡‘Gthe–¦fprogram“without“con guring“it“ rst.Ž¦‘!GAnother–Wgthing“that“¼configure“»can“do“is“to“edit“the“Makš²!e le.‘ðáIf“y˜ou“do“this,‘ƒ¨the“dis-Ž¡‘Gtribution–3should“¾not‘<ú»con²!tain“a“ le“named“`¼Makefile»'.‘ ƒÜInstead,‘–:it“should“include“a“ leŽ¡‘G`¼Makefile.in»'–Kwhicš²!h“con˜tains“the“input“used“for“editing.‘¿nOnce“again,‘]\this“is“so“that“pMÞeopleŽ¡‘Gw²!on't–¦fbMÞe“able“to“build“the“program“without“con guring“it“ rst.Ž¦‘!GIf–S:¼configure“»doMÞes“write“the“`¼Makefile»',‘~othen“`¼Makefile»'“should“ha•²!v“e–S:a“target“namedŽ¡‘G`¼Makefile»'–¬Mwhic²!h“causes“¼configure“»to“bMÞe“rerun,‘íÆsetting“up“the“same“con guration“thatŽ¡‘Gw²!as–@Nset“up“last“time.‘«”The“ les“that“¼configure“»reads“should“bšMÞe“listed“as“dep˜endencies“ofŽ¡‘G`¼Makefile»'.Ž¦‘!GAll–éžthe“ les“whicš²!h“are“output“from“the“¼configure“»script“should“ha˜v˜e“commen˜ts“at“theŽ¡‘GbMÞeginning–÷Cexplaining“that“they“w²!ere“generated“automatically“using“¼configure».‘ÐuThis“is“soŽ¡‘Gthat–¦fusers“wš²!on't“think“of“trying“to“edit“them“b˜y“hand.Ž¦‘!GThe–7ä¼configure“»script“should“write“a“ le“named“`¼config.status»'“whicš²!h“describMÞes“whic˜hŽ¡‘Gcon guration–>¥options“wš²!ere“spMÞeci ed“when“the“program“w˜as“last“con gured.‘»GThis“ le“shouldŽ¡‘GbMÞe–¦fa“shell“script“whic²!h,“if“run,“will“recreate“the“same“con guration.ŽŽŒ‹)‘–Ÿò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e41ŽŽŽ ƒ3* ý ÌÖ‘!GThe–£ô¼configure“»script“should“accept“an“option“of“the“form“`¼--srcdir=¿dirname‘»'“to“spMÞecifyŽ¤ 33‘Gthe– ðdirectory“where“sources“are“found“(if“it“is“not“the“currenš²!t“directory).‘Í|This“mak˜es“itŽ¡‘GpMÞossible–„¸to“build“the“program“in“a“separate“directory‘ÿe,‘‹tso“that“the“actual“source“directory“isŽ¡‘Gnot‘¦fmoMÞdi ed.Ž© ‘!GIf–Ã×the“user“došMÞes“not“sp˜ecify“`¼--srcdir»',‘Ë4then“¼configure“»should“c•²!hec“k–Ã×b˜oth“`¼.»'“and“`¼..»'Ž¡‘Gto–ÕJsee“if“it“can“ nd“the“sources.‘j‰If“it“ nds“the“sources“in“one“of“these“places,‘áit“should“useŽ¡‘Gthem–3÷from“there.‘†‘Otherwise,›W\it“should“repMÞort“that“it“cannot“ nd“the“sources,˜and“shouldŽ¡‘Gexit–¦fwith“nonzero“status.Ž¦‘!GUsually–¾ºthe“easy“w•²!a“y–¾ºto“suppMÞort“`¼--srcdir»'“is“bš²!y“editing“a“de nition“of“¼VPATH“»in˜to“theŽ¡‘GMakš²!e le.‘µ³Some–-çrules“ma˜y“need“to“refer“explicitly“to“the“spMÞeci ed“source“directory–ÿe.‘µ³T“o‘-çmak˜eŽ¡‘Gthis–írpMÞossible,‘ÿ5¼configure“»can“add“to“the“Mak²!e le“a“v›ÿdDariable“named“¼srcdir“»whose“v˜alue“isŽ¡‘Gprecisely–¦fthe“spMÞeci ed“directory‘ÿe.Ž¦‘!GThe–åμconfigure“»script“should“also“takš²!e“an“argumen˜t“whic˜h“spMÞeci es“the“t˜ypMÞe“of“systemŽ¡‘Gto–¦fbuild“the“program“for.‘ÝÝThis“argumenš²!t“should“loMÞok“lik˜e“this:ŽŸPØ‘.ùœ¿cpu¼-¿compan²!y¼-¿systemŽ¦‘!G»F‘ÿeor–¦fexample,“a“Sun“3“migh²!t“bMÞe“`¼m68k-sun-sunos4.1»'.Ž¦‘!GThe–^k¼configure“»script“needs“to“bšMÞe“able“to“deco˜de“all“plausible“alternativš²!es“for“ho˜w“toŽ¡‘GdescribMÞe–Sßa“mac•²!hine.‘æGTh“us,‘=`¼sun3-sunos4.1»'›Sßw“ould˜bMÞe˜a˜v‘ÿdDalid˜alias.‘æGF‘ÿeor˜man“y˜programs,Ž¡‘G`¼vax-dec-ultrix»'–»ãw²!ould“bšMÞe“an“alias“for“`¼vax-dec-bsd»',‘ÁBsimply“b˜ecause“the“di erences“b˜e-Ž¡‘Gt•²!w“een–x!Ultrix“and“ÁBSD‘x»are“rarely“noticeable,‘bbut“a“few“programs“migh²!t“need“to“distinguishŽ¡‘Gthem.Ž¦‘!GThere–É is“a“shell“script“called“`¼config.sub»'“that“y²!ou“can“use“as“a“subroutine“to“v‘ÿdDalidateŽ¡‘Gsystem–¦ft²!ypMÞes“and“canonicalize“aliases.Ž¦‘!GOther–ÇØoptions“are“pšMÞermitted“to“sp˜ecify“in“more“detail“the“soft•²!w“are–ÇØor“hardwš²!are“presen˜tŽ¡‘Gon–¦fthe“macš²!hine,“and“include“or“exclude“optional“parts“of“the“pac˜k‘ÿdDage:ŽŸÔã‘G`¼--enable-¿feature‘»[¼=¿parameter‘É)»]'Ž¡‘Kâ:Con gure–Â"the“pacš²!k‘ÿdDage“to“build“and“install“an“optional“user-lev˜el“facilit˜y“calledŽ¡‘Kâ:¿feature».‘Õ0This–Œ^alloš²!ws“users“to“c˜hoMÞose“whic˜h“optional“features“to“include.‘Õ0GivingŽ¡‘Kâ:an–¦foptional“¿parameter‘o»of“`¼no»'“should“omit“¿feature»,“if“it“is“built“b²!y“default.Ž¦‘Kâ:No–Ïœ`¼--enable»'“option“should“½ev²!er“»cause“one“feature“to“replace“another.‘YNoŽ¡‘Kâ:`¼--enable»'–@Œoption“should“evš²!er“substitute“one“useful“bMÞeha˜vior“for“another“usefulŽ¡‘Kâ:bšMÞeha²!vior.‘ÜThe–¥Íonly“prop˜er“use“for“`¼--enable»'“is“for“questions“of“whether“toŽ¡‘Kâ:build–¦fpart“of“the“program“or“exclude“it.ŽŸÔã‘G`¼--with-¿pac²!k‘ÿdDage‘»'Ž¡‘Kâ:The– 5pacš²!k‘ÿdDage“¿pac˜k‘ÿdDage‘§<»will“bMÞe“installed,‘#(so“con gure“this“pac˜k‘ÿdDage“to“w˜ork“withŽ¡‘Kâ:¿pac²!k‘ÿdDage».Ž¦‘Kâ:Pš²!ossible–Òrv‘ÿdDalues“of“¿pac˜k‘ÿdDage‘oy»include“`¼gnu-as»'“(or“`¼gas»'),–u`¼gnu-ld»',“`¼gnu-libc»',Ž¡‘Kâ:`¼gdb»',–¦f`¼x»',“and“`¼x-toolkit»'.Ž¦‘Kâ:Do–!¢not“use“a“`¼--with»'“option“to“spMÞecify“the“ le“name“to“use“to“ nd“certain“ les.Ž¡‘Kâ:That–¦fis“outside“the“scopMÞe“of“what“`¼--with»'“options“are“for.Ž¤Ôã‘G`¼--nfp»'‘ýKThe–¦ftarget“macš²!hine“has“no“ oating“pMÞoin˜t“proMÞcessor.Ž¡‘G`¼--gas»'‘ýKThe–TÓtarget“macš²!hine“assem˜bler“is“GAS,“the“GNU‘T¦assem˜bler.‘é#This“is“obsolete;ŽŸ 33‘Kâ:users–¦fshould“use“`¼--with-gnu-as»'“instead.ŽŽŒ‹* Ÿò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e42ŽŽŽ ƒ3* ý ÌÖ‘G`¼--x»'‘"|ŸThe–Ãtarget“macš²!hine“has“the“X‘Windo˜w“System“installed.‘«§This“is“obsolete;‘AúusersŽ¤ 33‘Kâ:should–¦fuse“`¼--with-x»'“instead.ŽŸPu‘!GAll–2ļconfigure“»scripts“should“accept“all“of“these“\detail"“options,‘UÜwhether“or“not“theyŽ¡‘Gmak•²!e›Ð[an“y˜di erence˜to˜the˜particular˜pac“k‘ÿdDage˜at˜hand.‘–„In˜particular,‘û*they˜should˜accept˜an“yŽ¡‘Goption–’Úthat“starts“with“`¼--with-»'“or“`¼--enable-»'.‘×YThis“is“so“users“will“bMÞe“able“to“con gureŽ¡‘Gan–¦fen²!tire“GNU“source“tree“at“once“with“a“single“set“of“options.Ž©ÁÔ‘!GY‘ÿeou–_Cwill“note“that“the“categories“`¼--with-»'“and“`¼--enable-»'“are“narro²!w:‘O—they“½do“notŽ¡‘G»proš²!vide–ä°a“place“for“an˜y“sort“of“option“y˜ou“migh˜t“think“of.›˜»That“is“delibMÞerate.˜W‘ÿee“w•²!an“t‘ä°toŽ¡‘Glimit–¯8the“pMÞossible“con guration“options“in“GNU›¯6soft•²!w“are.‘øRW‘ÿee–¯8do“not“w•²!an“t‘¯8GNU˜programsŽ¡‘Gto›¦fha•²!v“e˜idiosyncratic˜con guration˜options.Ž¦‘!GP•²!ac“k‘ÿdDages–žˆthat“pšMÞerform“part“of“the“compilation“pro˜cess“ma²!y“supp˜ort“cross-compilation.‘…éInŽ¡‘Gsucš²!h–÷4a“case,‘>the“host“and“target“mac˜hines“for“the“program“ma˜y“bMÞe“di eren˜t.‘£wThe“¼configureŽ¡‘G»script–Ëshould“normally“treat“the“spšMÞeci ed“t²!yp˜e“of“system“as“b˜oth“the“host“and“the“target,Ž¡‘Gthš²!us–¦fproMÞducing“a“program“whic˜h“w˜orks“for“the“same“t˜ypMÞe“of“mac˜hine“that“it“runs“on.Ž¦‘!GThe›æ¸w•²!a“y˜to˜build˜a˜cross-compiler,›öÌcross-assem“bler,˜or–æ¸what“ha•²!v“e‘æ¸y“ou,˜is–æ¸to“spMÞecify“theŽ¡‘Goption–&¡`¼--host=¿hostt²!ypšMÞe‘»'“when“running“¼configure».‘³FThis“sp˜eci es“the“host“system“withoutŽ¡‘Gcš²!hanging–ë÷the“t˜ypMÞe“of“target“system.‘Ÿ¸The“syn˜tax“for“¿hostt˜ypšMÞe‘ˆþ»is“the“same“as“describ˜ed“ab˜o•²!v“e.Ž¦‘!GBoMÞotstrapping–õua“cross-compiler“requires“compiling“it“on“a“mac²!hine“other“than“the“hostŽ¡‘Git–°|will“run“on.‘üCompilation“pacš²!k‘ÿdDages“accept“a“con guration“option“`¼--build=¿hostt˜ypMÞe‘»'“forŽ¡‘GspMÞecifying–Ðwthe“con guration“on“whicš²!h“y˜ou“will“compile“them,‘Úüin“case“that“is“di eren˜t“fromŽ¡‘Gthe‘¦fhost.Ž¦‘!GPrograms–ºkfor“whic²!h“cross-opMÞeration“is“not“meaningful“need“not“accept“the“`¼--host»'“op-Ž¡‘Gtion,‘K—bšMÞecause–4ãcon guring“an“en²!tire“op˜erating“system“for“cross-op˜eration“is“not“a“meaningfulŽ¡‘Gthing.Ž¦‘!GSome–Lprograms“ha•²!v“e›Lw“a“ys˜of˜con guring˜themselv“es˜automatically‘ÿe.‘?If˜y“our˜program˜isŽ¡‘Gset–¦fup“to“do“this,“yš²!our“¼configure“»script“can“simply“ignore“most“of“its“argumen˜ts.ŽŸ«â‘Gá7.2‘™Mak•ŒÌe le‘f@Con“v“en“tionsŽŽ©ÁÔ‘!G»This– and“this“some-Ž¡‘Gtimes–ÝUcreates“confusion“or“misbšMÞeha²!vior.‘‚©So“it“is“a“go˜o˜d“idea“to“set“the“sux“list“explicitlyŽ¡‘Gusing–¦fonly“the“suxes“yš²!ou“need“in“the“particular“Mak˜e le,“lik˜e“this:ŽŸ¡‘.ùœ¼.SUFFIXES:ŽŸ €‘.ùœ.SUFFIXES:–¿ª.c“.oŽ¦‘G»The–~ rst“line“clears“out“the“sux“list,‘pthe“second“inš²!troMÞduces“all“suxes“whic˜h“ma˜y“bMÞeŽ¡‘Gsub‘›»ject–¦fto“implicit“rules“in“this“Mak²!e le.ŽŽŒ‹+¯Ÿò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e43ŽŽŽ ƒ3* ý ÌÖ‘!GDon't–‚¤assume“that“`¼.»'“is“in“the“path“for“command“execution.‘r—When“y²!ou“need“to“runŽ¤ 33‘Gprograms–0àthat“are“a“part“of“yš²!our“pac˜k‘ÿdDage“during“the“mak˜e,‘S~please“mak˜e“sure“that“it“usesŽ¡‘G`¼./»'–‚ïif“the“program“is“built“as“part“of“the“makš²!e“or“`¼$(srcdir)/»'“if“the“ le“is“an“unc˜hangingŽ¡‘Gpart–¦fof“the“source“coMÞde.‘ÝÝWithout“one“of“these“pre xes,“the“currenš²!t“searc˜h“path“is“used.Ž©ŸŸ‘!GThe–øˆdistinction“bMÞet•²!w“een–øˆ`¼./»'“(the“¿build“directory‘ð»)“and“`¼$(srcdir)/»'“(the“¿source“direc-Ž¡‘Gtory‘ð»)–Éis“impšMÞortan²!t“b˜ecause“users“can“build“in“a“separate“directory“using“the“`¼--srcdir»'Ž¡‘Goption–¦fto“`¼configure»'.‘ÝÝA“rule“of“the“form:ŽŸìl‘.ùœ¼foo.1–¿ª:“foo.man“sedscriptŽŸ €‘\öìsed–¿ª-e“sedscript“foo.man“>“foo.1Ž¦‘G»will–cfail“when“the“build“directory“is“not“the“source“directory‘ÿe,‘¹ábMÞecause“`¼foo.man»'“andŽ¡‘G`¼sedscript»'–¦fare“in“the“the“source“directory‘ÿe.Ž¦‘!GWhen–Ÿusing“GNU‘‡¼make»,‘mrelying“on“`¼VPATH»'“to“ nd“the“source“ le“will“w²!ork“in“the“caseŽ¡‘Gwhere–Åthere“is“a“single“depMÞendency“ le,‘5since“the“¼make“»automatic“v‘ÿdDariable“`¼$<»'“will“represen²!tŽ¡‘Gthe–‚_source“ le“wherevš²!er“it“is.‘qÉ(Man˜y“v˜ersions“of“¼make“»set“`¼$<»'“only“in“implicit“rules.)‘qÉAŽ¡‘GMakš²!e le–¦ftarget“lik˜eŽ¤ìl‘.ùœ¼foo.o–¿ª:“bar.cŽŸ €‘\öì$(CC)–¿ª-I.“-I$(srcdir)“$(CFLAGS)“-c“bar.c“-o“foo.oŽ¦‘G»should–¦finstead“bMÞe“written“asŽ¡‘.ùœ¼foo.o–¿ª:“bar.cŽŸ €‘\öì$(CC)–¿ª-I.“-I$(srcdir)“$(CFLAGS)“-c“$<“-o“$@Ž¦‘G»in–vorder“to“alloš²!w“`¼VPATH»'“to“w˜ork“correctly‘ÿe.‘NZWhen“the“target“has“m˜ultiple“depMÞendencies,Ž¤ 33‘Gusing–ï;an“explicit“`¼$(srcdir)»'“is“the“easiest“w•²!a“y–ï;to“makš²!e“the“rule“w˜ork“w˜ell.‘¸\F‘ÿeor“example,Ž¡‘Gthe–¦ftarget“abšMÞo•²!v“e–¦ffor“`¼foo.1»'“is“b˜est“written“as:ŽŸìl‘.ùœ¼foo.1–¿ª:“foo.man“sedscriptŽŸ €‘\öìsed–¿ª-e“$(srcdir)/sedscript“$(srcdir)/foo.man“>“$@Ž¦‘!G»GNU‘‹îdistributions–Œ6usually“conš²!tain“some“ les“whic˜h“are“not“source“ les|for“example,‘ĦInfoŽ¡‘G les,›1oand–¡the“output“from“AutoMÞconf,˜Automak²!e,˜Bison“or“Flex.‘+ŽSince“these“ les“normallyŽ¡‘GappšMÞear–\úin“the“source“directory‘ÿe,‘Šžthey“should“alw•²!a“ys–\úapp˜ear“in“the“source“directory‘ÿe,‘Šžnot“inŽ¡‘Gthe–òbuild“directory‘ÿe.‘#‚So“Mak²!e le“rules“to“upšMÞdate“them“should“put“the“up˜dated“ les“in“theŽ¡‘Gsource‘¦fdirectory‘ÿe.Ž¦‘!GHo•²!w“ev“er,‘Î|if–Æxa“ le“došMÞes“not“app˜ear“in“the“distribution,‘Î|then“the“Mak²!e le“should“not“putŽ¡‘Git–C×in“the“source“directory‘ÿe,‘WbMÞecause“building“a“program“in“ordinary“circumstances“should“notŽ¡‘GmoMÞdify–¦fthe“source“directory“in“anš²!y“w˜a˜y‘ÿe.Ž¦‘!GT‘ÿery–÷.to“makš²!e“the“build“and“installation“targets,‘ `at“least“(and“all“their“subtargets)“w˜orkŽ¡‘Gcorrectly–¦fwith“a“parallel“¼make».ŽŸØØ‘Gê7.2.2‘d(Utilities–íMin“Mak–áe lesŽŽŸŸŸ‘!G»W‘ÿerite–ìÐthe“Makš²!e le“commands“(and“an˜y“shell“scripts,‘þjsuc˜h“as“¼configure»)“to“run“in“¼sh»,Ž¡‘Gnot–¦fin“¼csh».‘ÝÝDon't“use“an²!y“spMÞecial“features“of“¼ksh“»or“¼bash».Ž¦‘!GThe–ó¼configure“»script“and“the“Mak²!e le“rules“for“building“and“installation“should“not“useŽ¡‘Gan²!y–¦futilities“directly“except“these:ŽŸìl‘.ùœ¼cat–¿ªcmp“cp“diff“echo“egrep“expr“false“grep“install-infoŽŸ €‘.ùœln–¿ªls“mkdir“mv“pwd“rm“rmdir“sed“sleep“sort“tar“test“touch“trueŽŽŒ‹,½ÏŸò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e44ŽŽŽ ƒ3* ý ÌÖ‘!GThe–¦fcompression“program“¼gzip“»can“bMÞe“used“in“the“¼dist“»rule.Ž¤ŠÇ‘!GStic²!k–ÃŒto“the“generally“suppMÞorted“options“for“these“programs.‘5NF‘ÿeor“example,‘ Õdon't“useŽ© 33‘G`¼mkdir–¦f-p»',“con•²!v“enien“t–¦fas“it“ma²!y“bšMÞe,“b˜ecause“most“systems“don't“supp˜ort“it.Ž¡‘!GIt–wþis“a“go•MÞo“d–wþidea“to“a•²!v“oid–wþcreating“symš²!bMÞolic“links“in“mak˜e les,‘Fsince“a“few“systems“don'tŽ¦‘GsuppMÞort‘¦fthem.Ž¡‘!GThe–à Mak²!e le“rules“for“building“and“installation“can“also“use“compilers“and“related“pro-Ž¦‘Ggrams,‘5but–Ásshould“do“so“via“¼make“»v‘ÿdDariables“so“that“the“user“can“substitute“alternativ²!es.Ž¦‘GHere–¦fare“some“of“the“programs“w²!e“mean:Ž©×”‘.ùœ¼ar–¿ªbison“cc“flex“install“ld“ldconfig“lexŽŸ €‘.ùœmake–¿ªmakeinfo“ranlib“texi2dvi“yaccŽ¡‘!G»Use–¦fthe“follo²!wing“¼make“»v‘ÿdDariables“to“run“those“programs:Ž¦‘.ùœ¼$(AR)–¿ª$(BISON)“$(CC)“$(FLEX)“$(INSTALL)“$(LD)“$(LDCONFIG)“$(LEX)ŽŸ €‘.ùœ$(MAKE)–¿ª$(MAKEINFO)“$(RANLIB)“$(TEXI2DVI)“$(YACC)Ž¡‘!G»When–ùyš²!ou“use“¼ranlib“»or“¼ldconfig»,‘,Þy˜ou“should“mak˜e“sure“nothing“bad“happMÞens“if“theŽ¤ 33‘Gsystem–e¤doMÞes“not“ha•²!v“e–e¤the“program“in“question.‘ –Arrange“to“ignore“an“error“from“thatŽ¡‘Gcommand,‘¾and–Ëzprin²!t“a“message“bMÞefore“the“command“to“tell“the“user“that“failure“of“thisŽ¡‘Gcommand–ísdošMÞes“not“mean“a“problem.‘³(The“Auto˜conf“`¼AC_PROG_RANLIB»'“macro“can“helpŽ¡‘Gwith‘¦fthis.)Ž©ŠÇ‘!GIf–æÊyš²!ou“use“sym˜bMÞolic“links,‘öây˜ou“should“implemen˜t“a“fallbac˜k“for“systems“that“don't“ha˜v˜eŽ¡‘Gsym²!bMÞolic‘¦flinks.Ž¦‘!GAdditional–¦futilities“that“can“bMÞe“used“via“Mak²!e“v‘ÿdDariables“are:ŽŸ×”‘.ùœ¼chgrp–¿ªchmod“chown“mknodŽ¦‘!G»It–:is“ok“to“use“other“utilities“in“Makš²!e le“pMÞortions“(or“scripts)“in˜tended“only“for“particularŽ¡‘Gsystems–¦fwhere“yš²!ou“kno˜w“those“utilities“exist.ŽŸ¼‘Gê7.2.3‘d(V‘þÄ£ariables–íMfor“Spiecifying“CommandsŽŽŸŠÇ‘!G»Makš²!e les–Œ‘should“pro˜vide“v‘ÿdDariables“for“o˜v˜erriding“certain“commands,–‘¼options,“and–Œ‘so“on.Ž¦‘!GIn–äoparticular,‘ :yš²!ou“should“run“most“utilit˜y“programs“via“v‘ÿdDariables.‘6Th˜us,‘ :if“y˜ou“use“Bison,Ž¡‘Gha•²!v“e–­„a“v›ÿdDariable“named“¼BISON“»whose“default“v˜alue“is“set“with“`¼BISON–¦f=“bison»',‘¯Kand–­„refer“toŽ¡‘Git–¦fwith“¼$(BISON)“»whenevš²!er“y˜ou“need“to“use“Bison.Ž¦‘!GFile–_ managemenš²!t“utilities“suc˜h“as“¼ln»,–mȼrm»,“¼mv»,“and–_ so“on,‘mÈneed“not“bMÞe“referred“to“throughŽ¡‘Gv‘ÿdDariables–¦fin“this“w•²!a“y‘ÿe,–¦fsince“users“don't“need“to“replace“them“with“other“programs.Ž¦‘!GEac²!h–éprogram-name“v›ÿdDariable“should“come“with“an“options“v˜ariable“that“is“used“to“supplyŽ¡‘Goptions–}Oto“the“program.‘b˜AppMÞend“`¼FLAGS»'“to“the“program-name“v‘ÿdDariable“name“to“get“theŽ¡‘Goptions–¨Ãv‘ÿdDariable“name|for“example,‘©Z¼BISONFLAGS».‘äô(The“names“¼CFLAGS“»for“the“C‘¨Âcompiler,Ž¡‘G¼YFLAGS–|ò»for“y²!acc,›…åthat“pšMÞertain“to“one“sp˜eci c“macš²!hine.‘§[Users“should“nev˜er“need“to“moMÞdifyŽ¡‘Kâ: les–É»in“this“directory“to“con gure“the“pacš²!k‘ÿdDage's“opMÞeration;‘Ûeput“suc˜h“con gura-Ž¡‘Kâ:tion–¯%information“in“separate“ les“that“go“in“`¼$(datadir)»'“or“`¼$(sysconfdir)»'.Ž¡‘Kâ:`¼$(localstatedir)»'–£]should“normally“bMÞe“`¼/usr/local/var»',‘"™but“write“it“asŽ¡‘Kâ:`¼$(prefix)/var»'.‘ÝÝ(If–¦fy²!ou“are“using“AutoMÞconf,“write“it“as“`¼@localstatedir@»'.)Ž¦‘G`¼libdir»'‘=¡The–Ì“directory“for“ob››»ject“ les“and“libraries“of“ob˜ject“coMÞde.‘ PcDo“not“installŽ¡‘Kâ:executables–•vhere,‘Q9they“probably“ough²!t“to“go“in“`¼$(libexecdir)»'“instead.Ž¡‘Kâ:The–"‹v‘ÿdDalue“of“¼libdir“»should“normally“bMÞe“`¼/usr/local/lib»',‘”but“write“it“asŽ¡‘Kâ:`¼$(exec_prefix)/lib»'.‘ÝÝ(If–¦fy²!ou“are“using“AutoMÞconf,“write“it“as“`¼@libdir@»'.)Ž¦‘G`¼infodir»'‘ }÷The–edirectory“for“installing“the“Info“ les“for“this“pac²!k‘ÿdDage.‘ÈBy“default,‘rit“shouldŽ¡‘Kâ:bšMÞe–ß!`¼/usr/local/info»',‘íObut“it“should“b˜e“written“as“`¼$(prefix)/info»'.‘ˆ (If“y²!ouŽ¡‘Kâ:are–¦fusing“AutoMÞconf,“write“it“as“`¼@infodir@»'.)Ž¦‘G`¼lispdir»'‘ }÷The–q?directory“for“installing“anš²!y“Emacs“Lisp“ les“in“this“pac˜k‘ÿdDage.‘Ì&By“default,‘{áitŽ¡‘Kâ:should–¹ƒbšMÞe“`¼/usr/local/share/emacs/site-lisp»',‘¾Kbut“it“should“b˜e“written“asŽ¡‘Kâ:`¼$(prefix)/share/emacs/site-lisp»'.ŽŸ–f‘Kâ:If–×…yš²!ou“are“using“AutoMÞconf,‘ãÍwrite“the“default“as“`¼@lispdir@»'.‘q:In“order“to“mak˜eŽ¡‘Kâ:`¼@lispdir@»'–¦fwš²!ork,“y˜ou“need“the“follo˜wing“lines“in“y˜our“`¼configure.in»'“ le:ŽŸã3‘hʼlispdir='${datadir}/emacs/site-lisp'ŽŸ €‘hÊAC_SUBST(lispdir)Ž¦‘G»`¼includedir»'Ž¡‘Kâ:The–cTdirectory“for“installing“header“ les“to“bMÞe“included“b²!y“user“programsŽ¡‘Kâ:with–éêthe“C‘é`¼#include»'“preprošMÞcessor“directiv²!e.‘¨hThis“should“normally“b˜eŽ¡‘Kâ:`¼/usr/local/include»',‘­ƒbut–~write“it“as“`¼$(prefix)/include»'.‘ "$(If“y²!ou“areŽ¡‘Kâ:using–¦fAutoMÞconf,“write“it“as“`¼@includedir@»'.)ŽŸ–f‘Kâ:Most–Vcompilers“other“than“GCC‘·do“not“loMÞok“for“header“ les“in“directoryŽ¡‘Kâ:`¼/usr/local/include»'.‘'BSo–¾Ýinstalling“the“header“ les“this“w•²!a“y–¾Ýis“only“usefulŽ¡‘Kâ:with–´ÇGCC.“Sometimes“this“is“not“a“problem“bMÞecause“some“libraries“are“onlyŽ¡‘Kâ:really–Ïbinš²!tended“to“w˜ork“with“GCC.“But“some“libraries“are“in˜tended“to“w˜orkŽ¡‘Kâ:with–ùother“compilers.‘Õ²They“should“install“their“header“ les“in“t•²!w“o‘ùplaces,‘ ©oneŽ¡‘Kâ:spšMÞeci ed–¦fb²!y“¼includedir“»and“one“sp˜eci ed“b²!y“¼oldincludedir».ŽŽŒ‹0÷“Ÿò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e48ŽŽŽ ƒ3* ý ÌÖ‘G`¼oldincludedir»'Ž¤ 33‘Kâ:The–3Ýdirectory“for“installing“`¼#include»'“header“ les“for“use“with“compilers“otherŽ¡‘Kâ:than– AGCC.“This“should“normally“bMÞe“`¼/usr/include»'.‘ m(If“y²!ou“are“using“Auto-Ž¡‘Kâ:conf,–¦fy²!ou“can“write“it“as“`¼@oldincludedir@»'.)Ž©k‘Kâ:The– ‘Makš²!e le“commands“should“c˜hec˜k“whether“the“v‘ÿdDalue“of“¼oldincludedir“»isŽ¡‘Kâ:empt²!y‘ÿe.‘Ä\If–æit“is,‘ÛÅthey“should“not“try“to“use“it;‘¥they“should“cancel“the“secondŽ¡‘Kâ:installation–¦fof“the“header“ les.Ž¦‘Kâ:A‘°÷pac²!k‘ÿdDage–±;should“not“replace“an“existing“header“in“this“directory“unless“theŽ¡‘Kâ:header–ùJcame“from“the“same“pac•²!k‘ÿdDage.‘ÖˆTh“us,‘Nif›ùJy“our˜F‘ÿeoMÞo˜pac“k‘ÿdDage˜pro“vides˜aŽ¡‘Kâ:header–÷ le“`¼foo.h»',‘Ÿ§then“it“should“install“the“header“ le“in“the“¼oldincludedirŽ¡‘Kâ:»directory–phif“either“(1)“there“is“no“`¼foo.h»'“there“or“(2)“the“`¼foo.h»'“that“existsŽ¡‘Kâ:came–¦ffrom“the“F‘ÿeoMÞo“pac²!k‘ÿdDage.Ž¦‘Kâ:T›ÿeo–ׯtell“whether“`¼foo.h»'“came“from“the“F˜oMÞo“pac²!k‘ÿdDage,‘äput“a“magic“string“in“theŽ¡‘Kâ: le|part–¦fof“a“commen²!t|and“¼grep“»for“that“string.Ž¤ó£‘!GUnix-stš²!yle–¦fman“pages“are“installed“in“one“of“the“follo˜wing:Ž¡‘G`¼mandir»'‘=¡The–1¶top-levš²!el“directory“for“installing“the“man“pages“(if“an˜y)“for“this“pac˜k‘ÿdDage.‘¶øItŽ¤ 33‘Kâ:will–Qnormally“bMÞe“`¼/usr/local/man»',‘ňbut“y²!ou“should“write“it“as“`¼$(prefix)/man»'.Ž¡‘Kâ:(If–¦fy²!ou“are“using“AutoMÞconf,“write“it“as“`¼@mandir@»'.)Ž¤ó£‘G`¼man1dir»'‘ }÷The– —directory“for“installing“section“1“man“pages.‘ªíW‘ÿerite“it“as“`¼$(mandir)/man1»'.Ž¡‘G`¼man2dir»'‘ }÷The–Xñdirectory“for“installing“section“2“man“pages.‘Ä W‘ÿerite“it“as“`¼$(mandir)/man2»'Ž¡‘G`¼...Ž‘>ÿ»'Ž¦‘Kâ:½Don't–Q1makš²!e“the“primary“doMÞcumen˜tation“for“an˜y“GNU‘Qsoft˜w˜are“bMÞe“a“man“page.Ž¤ 33‘Kâ:W›ÿerite–ßma“man²!ual“in“T˜exinfo“instead.‘ˆóMan“pages“are“just“for“the“sak²!e“of“pMÞeopleŽ¡‘Kâ:running–¦fGNU“soft•²!w“are–¦fon“Unix,“whic²!h“is“a“secondary“application“only‘ÿe.Ž©ó£‘G»`¼manext»'‘=¡The–| le“name“extension“for“the“installed“man“page.‘ FThis“should“con²!tain“aŽ¡‘Kâ:p•MÞerio“d›¦ffollo•²!w“ed˜b“y˜the˜appropriate˜digit;˜it˜should˜normally˜bMÞe˜`¼.1»'.Ž¦‘G`¼man1ext»'‘ }÷The–¦f le“name“extension“for“installed“section“1“man“pages.Ž¦‘G`¼man2ext»'‘ }÷The–¦f le“name“extension“for“installed“section“2“man“pages.Ž¦‘G`¼...Ž‘>ÿ»'‘"|žUse–Ô£these“names“instead“of“`¼manext»'“if“the“pac²!k‘ÿdDage“needs“to“install“man“pagesŽ¡‘Kâ:in–¦fmore“than“one“section“of“the“man²!ual.Ž¦‘!GAnd–¦f nally‘ÿe,“yš²!ou“should“set“the“follo˜wing“v‘ÿdDariable:Ž¦‘G`¼srcdir»'‘=¡The–³directory“for“the“sources“bMÞeing“compiled.‘ .ÃThe“v›ÿdDalue“of“this“v˜ariable“isŽ¡‘Kâ:normally–Kžinserted“bš²!y“the“¼configure“»shell“script.‘¿š(If“y˜ou“are“using“Autconf,‘]ÆuseŽ¡‘Kâ:`¼srcdir–¦f=“@srcdir@»'.)Ž¦‘!GF‘ÿeor‘¦fexample:ŽŸ`8‘.ùœ¼#–¿ªCommon“prefix“for“installation“directories.Ž¤ €‘.ùœ#–¿ªNOTE:“This“directory“must“exist“when“you“start“the“install.Ž¡‘.ùœprefix–¿ª=“/usr/localŽ¡‘.ùœexec_prefix–¿ª=“$(prefix)Ž¡‘.ùœ#–¿ªWhere“to“put“the“executable“for“the“command“`gcc'.Ž¡‘.ùœbindir–¿ª=“$(exec_prefix)/binŽŽŒ‹1øŸò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e49ŽŽŽ ƒ3* ý ÌÖ‘.ùœ¼#–¿ªWhere“to“put“the“directories“used“by“the“compiler.Ž¤ €‘.ùœlibexecdir–¿ª=“$(exec_prefix)/libexecŽ¡‘.ùœ#–¿ªWhere“to“put“the“Info“files.Ž¡‘.ùœinfodir–¿ª=“$(prefix)/infoŽ©ý‘!G»If–>´yš²!our“program“installs“a“large“n˜um˜bMÞer“of“ les“in˜to“one“of“the“standard“user-spMÞeci edŽ¤ 33‘Gdirectories,‘lit–ý®mighš²!t“bMÞe“useful“to“group“them“in˜to“a“subMÞdirectory“particular“to“that“program.Ž¡‘GIf–¦fyš²!ou“do“this,“y˜ou“should“write“the“¼install“»rule“to“create“these“subMÞdirectories.Ž¦‘!GDo–Wnot“expšMÞect“the“user“to“include“the“sub˜directory“name“in“the“v‘ÿdDalue“of“an²!y“of“theŽ¡‘Gv›ÿdDariables–þ÷listed“abMÞo•²!v“e.‘çThe–þ÷idea“of“ha²!ving“a“uniform“set“of“v˜ariable“names“for“installationŽ¡‘Gdirectories–Â*is“to“enable“the“user“to“spMÞecify“the“exact“same“v‘ÿdDalues“for“sevš²!eral“di eren˜t“GNUŽ¡‘Gpacš²!k‘ÿdDages.‘ÌIn–pÒorder“for“this“to“bMÞe“useful,‘{‰all“the“pac˜k‘ÿdDages“m˜ust“bMÞe“designed“so“that“they“willŽ¡‘Gw²!ork–¦fsensibly“when“the“user“doMÞes“so.ŽŸ”¹‘Gê7.2.5‘d(Standard–íMT‘þÄ£argets“for“UsersŽŽŸý‘!G»All–¦fGNU“programs“should“ha•²!v“e–¦fthe“folloš²!wing“targets“in“their“Mak˜e les:ŽŸb½‘G`¼all»'‘"|ŸCompile–›Zthe“en²!tire“program.›„ÙThis“should“bMÞe“the“default“target.˜This“target“needŽ¡‘Kâ:not–%#rebuild“anš²!y“doMÞcumen˜tation“ les;‘d‚Info“ les“should“normally“bMÞe“included“inŽ¡‘Kâ:the–¦fdistribution,“and“Dš²!VI“ les“should“bMÞe“made“only“when“explicitly“ask˜ed“for.Ž©˜a‘Kâ:By–×|default,›Þthe“Mak²!e“rules“should“compile“and“link“with“`¼-g»',˜so“that“executableŽ¡‘Kâ:programs›Zèha•²!v“e˜debugging˜sym“b•MÞols.‘ûdUsers˜who˜don't˜mind˜b“eing˜helpless˜canŽ¡‘Kâ:strip–¦fthe“executables“later“if“they“wish.ŽŸý‘G`¼install»'‘ }÷Compile–Æ:the“program“and“cop²!y“the“executables,–Î/libraries,“and–Æ:so“on“to“the“ leŽ¡‘Kâ:names–!ñwhere“they“should“reside“for“actual“use.‘±¶If“there“is“a“simple“test“to“v²!erifyŽ¡‘Kâ:that–¦fa“program“is“propMÞerly“installed,“this“target“should“run“that“test.Ž¦‘Kâ:Do–U·not“strip“executables“when“installing“them.‘ëÑDevil-ma²!y-care“users“can“useŽ¡‘Kâ:the–¦f¼install-strip“»target“to“do“that.Ž¦‘Kâ:If–ºpšMÞossible,‘-write“the“¼install“»target“rule“so“that“it“do˜es“not“mo˜dify“an²!ything“inŽ¡‘Kâ:the–ù˜directory“where“the“program“wš²!as“built,‘dpro˜vided“`¼make‘¦fall»'“has“just“bMÞeenŽ¡‘Kâ:done.‘o–This–¤is“con•²!v“enien“t–¤for“building“the“program“under“one“user“name“andŽ¡‘Kâ:installing–¦fit“under“another.Ž¦‘Kâ:The–Ïzcommands“should“create“all“the“directories“in“whic²!h“ les“are“to“bMÞe“installed,Ž¡‘Kâ:if–—hthey“don't“already“exist.‘ØÞThis“includes“the“directories“spMÞeci ed“as“the“v‘ÿdDaluesŽ¡‘Kâ:of–iÖthe“v‘ÿdDariables“¼prefix“»and“¼exec_prefix»,‘uòas“w²!ell“as“all“subMÞdirectories“that“areŽ¡‘Kâ:needed.‘½—One›E“w•²!a“y˜to˜do˜this˜is˜b“y˜means˜of˜an˜¼installdirs˜»target˜as˜describMÞedŽ¡‘Kâ:bMÞelo²!w.Ž¦‘Kâ:Use–X`¼-»'“bMÞefore“an²!y“command“for“installing“a“man“page,‘g¾so“that“¼make“»will“ignoreŽ¡‘Kâ:anš²!y– 6errors.‘ªxThis“is“in“case“there“are“systems“that“don't“ha˜v˜e“the“Unix“man“pageŽ¡‘Kâ:doMÞcumen²!tation–¦fsystem“installed.Ž¦‘Kâ:The›ìAw•²!a“y˜to˜install˜Info˜ les˜is˜to˜cop“y˜them˜in“to˜`¼$(infodir)»'˜with˜¼$(INSTALL_Ž¡‘Kâ:DATA)–?€»(see“Section“7.2.3“[Command“V‘ÿeariables],›¥Åpage“44),˜and“then“run“theŽ¡‘Kâ:¼install-info–λprogram“if“it“is“presen²!t.‘Tâ¼install-info“»is“a“program“that“editsŽ¡‘Kâ:the–Æ÷Info“`¼dir»'“ le“to“add“or“upMÞdate“the“menš²!u“en˜try“for“the“giv˜en“Info“ le;‘×?it“isŽ¡‘Kâ:part–¦fof“the“T‘ÿeexinfo“pac²!k‘ÿdDage.‘ÝÝHere“is“a“sample“rule“to“install“an“Info“ le:ŽŽŒ‹2óŸò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e50ŽŽŽ ƒ3* ý ÌÖ‘hʼ$(DESTDIR)$(infodir)/foo.info:‘¿ªfoo.infoŽ¤ €’–Çß$(POST_INSTALL)Ž¡‘hÊ#–¿ªThere“may“be“a“newer“info“file“in“.“than“in“srcdir.Ž¡’–Çß-if–¿ªtest“-f“foo.info;“then“d=.;“\Ž¡’œ‡‰else–¿ªd=$(srcdir);“fi;“\Ž¡’–Çß$(INSTALL_DATA)–¿ª$$d/foo.info“$(DESTDIR)$@;“\Ž¡‘hÊ#–¿ªRun“install-info“only“if“it“exists.Ž¡‘hÊ#–¿ªUse“`if'“instead“of“just“prepending“`-'“to“theŽ¡‘hÊ#–¿ªline“so“we“notice“real“errors“from“install-info.Ž¡‘hÊ#–¿ªWe“use“`$(SHELL)“-c'“because“some“shells“do“notŽ¡‘hÊ#–¿ªfail“gracefully“when“there“is“an“unknown“command.Ž¡’–Çßif–¿ª$(SHELL)“-c“'install-info“--version'“\Ž¡’¨Ý>/dev/null–¿ª2>&1;“then“\Ž¡’¢G3install-info–¿ª--dir-file=$(DESTDIR)$(infodir)/dir“\Ž¡’íÕ$(DESTDIR)$(infodir)/foo.info;‘¿ª\Ž¡’–Çßelse–¿ªtrue;“fiŽ©®‘Kâ:»When–êwriting“the“¼install“»target,‘a‹yš²!ou“m˜ust“classify“all“the“commands“in˜toŽ¤ 33‘Kâ:three–€Ncategories:‘ÊÑnormal“ones,‘‡ì¿pre-installation“»commands“and“¿pMÞost-installationŽ¡‘Kâ:»commands.‘ÝÝSee–¦fSection“7.2.6“[Install“Command“Categories],“page“53.ŽŸ(õ‘G`¼uninstall»'Ž¡‘Kâ:Delete–¦fall“the“installed“ les|the“copies“that“the“`¼install»'“target“creates.Ž¦‘Kâ:This–>êrule“should“not“moMÞdify“the“directories“where“compilation“is“done,‘Sœonly“theŽ¡‘Kâ:directories–¦fwhere“ les“are“installed.Ž¦‘Kâ:The–=Duninstallation“commands“are“divided“inš²!to“three“categories,‘RJjust“lik˜e“the“in-Ž¡‘Kâ:stallation–/Ûcommands.‘¶ZSee“Section“7.2.6“[Install“Command“Categories],‘G‘page“53.ŽŸ(õ‘G`¼install-strip»'Ž¡‘Kâ:Likš²!e–ãÛ¼install»,‘38but“strip“the“executable“ les“while“installing“them.‘–=In“man˜yŽ¡‘Kâ:cases,–¦fthe“de nition“of“this“target“can“bMÞe“v²!ery“simple:ŽŸúá‘hʼinstall-strip:Ž¤ €’–Çß$(MAKE)–¿ªINSTALL_PROGRAM='$(INSTALL_PROGRAM)“-s'“\Ž¡’ÄÅ/installŽ¦‘Kâ:»Normally–wš²!e“do“not“recommend“stripping“an“executable“unless“y˜ou“are“sure“theŽ¤ 33‘Kâ:program–Ùhas“no“bugs.‘wSHo•²!w“ev“er,‘æWit–Ùcan“bšMÞe“reasonable“to“install“a“stripp˜ed“exe-Ž¡‘Kâ:cutable–‘for“actual“execution“while“sa²!ving“the“unstrippMÞed“executable“elsewhereŽ¡‘Kâ:in–¦fcase“there“is“a“bug.ŽŸ(õ‘G`¼clean»'Ž¦‘Kâ:Delete–!Îall“ les“from“the“currenš²!t“directory“that“are“normally“created“b˜y“build-Ž¡‘Kâ:ing–ó>the“program.›ÄeDon't“delete“the“ les“that“record“the“con guration.˜AlsoŽ¡‘Kâ:preservš²!e–£8 les“that“could“bMÞe“made“b˜y“building,‘£Ûbut“normally“aren't“bMÞecause“theŽ¡‘Kâ:distribution–¦fcomes“with“them.Ž¦‘Kâ:Delete–¦f`¼.dvi»'“ les“here“if“they“are“not“part“of“the“distribution.ŽŸ(õ‘G`¼distclean»'Ž¡‘Kâ:Delete–Ãaall“ les“from“the“currenš²!t“directory“that“are“created“b˜y“con guring“orŽ¡‘Kâ:building–ÌRthe“program.‘O¡If“yš²!ou“ha˜v˜e“unpac˜k˜ed“the“source“and“built“the“programŽŽŒ‹3!°Ÿò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e51ŽŽŽ ƒ3* ý ÌÖ‘Kâ:without–dzcreating“anš²!y“other“ les,‘“ÿ`¼make‘¦fdistclean»'“should“lea˜v˜e“only“the“ lesŽ¤ 33‘Kâ:that–¦fw²!ere“in“the“distribution.Ž©°[‘G`¼mostlyclean»'Ž¡‘Kâ:Likš²!e–·6`¼clean»',‘ûjbut“ma˜y“refrain“from“deleting“a“few“ les“that“pMÞeople“normallyŽ¡‘Kâ:don't›r±w•²!an“t˜to˜recompile.‘Ì¡F‘ÿeor˜example,‘} the˜`¼mostlyclean»'˜target˜for˜GCC‘r¤doMÞesŽ¡‘Kâ:not–²delete“`¼libgcc.a»',‘1ÖbMÞecause“recompiling“it“is“rarely“necessary“and“tak²!es“a“lotŽ¡‘Kâ:of‘¦ftime.Ž¦‘G`¼maintainer-clean»'Ž¡‘Kâ:Delete–¤ûalmost“evš²!erything“from“the“curren˜t“directory“that“can“bMÞe“reconstructedŽ¡‘Kâ:with–jŸthis“Makš²!e le.‘*‰This“t˜ypically“includes“ev˜erything“deleted“b˜y“¼distclean»,Ž¡‘Kâ:plus–¦fmore:‘ÝÝC“source“ les“proMÞduced“b²!y“Bison,“tags“tables,“Info“ les,“and“so“on.Ž©qÇ‘Kâ:The–ãªreason“wš²!e“sa˜y“\almost“ev˜erything"“is“that“running“the“command“`¼makeŽ¡‘Kâ:maintainer-clean»'–à—should“not“delete“`¼configure»'“ev²!en“if“`¼configure»'“can“bMÞeŽ¡‘Kâ:remade–hyš²!ou“ nd“y˜ou“need“to“unpac˜k“the“full“distribution“again,‘dhdon'tŽ¡‘Kâ:blame‘¦fus.Ž¦‘Kâ:T‘ÿeo–nhelp“makš²!e“users“a˜w˜are“of“this,‘/the“commands“for“the“spMÞecial“¼maintainer-Ž¡‘Kâ:clean–¦f»target“should“start“with“these“t•²!w“o:Ž©¾”‘hʼ@echo–¿ª'This“command“is“intended“for“maintainers“to“use;“it'ŽŸ €‘hÊ@echo–¿ª'deletes“files“that“may“need“special“tools“to“rebuild.'Ž¤°[‘G»`¼TAGS»'‘¼õUpMÞdate–¦fa“tags“table“for“this“program.Ž¡‘G`¼info»'‘¼õGenerate–¦fanš²!y“Info“ les“needed.‘ÝÝThe“bMÞest“w˜a˜y“to“write“the“rules“is“as“follo˜ws:Ž¦‘hʼinfo:‘¿ªfoo.infoŽŸ‘hÊfoo.info:–¿ªfoo.texi“chap1.texi“chap2.texiŽŸ €’–Çß$(MAKEINFO)‘¿ª$(srcdir)/foo.texiŽ¤qÇ‘Kâ:»Y‘ÿeou–V¬mš²!ust“de ne“the“v‘ÿdDariable“¼MAKEINFO“»in“the“Mak˜e le.‘ î®It“should“run“theŽ© 33‘Kâ:¼makeinfo–¦f»program,“whic²!h“is“part“of“the“T‘ÿeexinfo“distribution.Ž¡‘Kâ:Normally–fÐa“GNU‘fždistribution“comes“with“Info“ les,‘–êand“that“means“the“InfoŽ¦‘Kâ: les–DÇare“presenš²!t“in“the“source“directory‘ÿe.‘¹Therefore,‘l_the“Mak˜e“rule“for“an“infoŽ¦‘Kâ: le–¨should“upMÞdate“it“in“the“source“directory‘ÿe.‘â·When“users“build“the“pac²!k‘ÿdDage,Ž¦‘Kâ:ordinarily–ù*Mak²!e“will“not“upšMÞdate“the“Info“ les“b˜ecause“they“will“already“b˜e“upŽ¦‘Kâ:to‘¦fdate.ŽŸ°[‘G`¼dvi»'‘"|ŸGenerate–¦fDš²!VI“ les“for“all“T‘ÿeexinfo“doMÞcumen˜tation.‘ÝÝF‘ÿeor“example:ŽŸ¾”‘hʼdvi:‘¿ªfoo.dviŽŽŒ‹4,ÕŸò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e52ŽŽŽ ƒ3* ý ÌÖ‘hʼfoo.dvi:–¿ªfoo.texi“chap1.texi“chap2.texiŽŸ €’–Çß$(TEXI2DVI)‘¿ª$(srcdir)/foo.texiŽ©žI‘Kâ:»Y‘ÿeou–V¬mš²!ust“de ne“the“v‘ÿdDariable“¼TEXI2DVI“»in“the“Mak˜e le.‘ î®It“should“run“theŽ¤ 33‘Kâ:program–z°¼texi2dvi»,‘¯Âwhicš²!h“is“part“of“the“T‘ÿeexinfo“distribution.Ÿü¾óÙ“ Rcmr7¬1Ž‘ ×-»Alternativ˜ely‘ÿe,Ž¡‘Kâ:write–¦fjust“the“depMÞendencies,“and“alloš²!w“GNU“¼make“»to“pro˜vide“the“command.ŽŸ _‘G`¼dist»'‘¼õCreate–¥ia“distribution“tar“ le“for“this“program.‘݉The“tar“ le“should“bMÞe“set“up“soŽ¡‘Kâ:that–õëthe“ le“names“in“the“tar“ le“start“with“a“subMÞdirectory“name“whic²!h“is“theŽ¡‘Kâ:name–…Íof“the“pacš²!k‘ÿdDage“it“is“a“distribution“for.‘ÒÿThis“name“can“include“the“v˜ersionŽ¡‘Kâ:n•²!um“bMÞer.Ž¦‘Kâ:F‘ÿeor–Íexample,‘Ö§the“distribution“tar“ le“of“GCC‘Ìövš²!ersion“1.40“unpac˜ks“in˜to“a“sub-Ž¡‘Kâ:directory–¦fnamed“`¼gcc-1.40»'.Ž¦‘Kâ:The–P easiest“w•²!a“y–P to“do“this“is“to“create“a“subMÞdirectory“appropriately“named,‘aauseŽ¡‘Kâ:¼ln–¦f»or“¼cp“»to“install“the“propšMÞer“ les“in“it,“and“then“¼tar“»that“sub˜directory‘ÿe.Ž¦‘Kâ:Compress–&^the“tar“ le“ le“with“¼gzip».‘]ÅF‘ÿeor“example,‘F\the“actual“distribution“ leŽ¡‘Kâ:for–¦fGCC“v²!ersion“1.40“is“called“`¼gcc-1.40.tar.gz»'.Ž¦‘Kâ:The–÷ò¼dist“»target“should“explicitly“depMÞend“on“all“non-source“ les“that“are“inŽ¡‘Kâ:the– \distribution,‘bto“mak²!e“sure“they“are“up“to“date“in“the“distribution.‘ ¾SeeŽ¡‘Kâ:Section–¦f7.3“[Making“Releases],“page“54.ŽŸ _‘G`¼check»'‘ýKPš²!erform–‹êself-tests“(if“an˜y).‘ŽiThe“user“m˜ust“build“the“program“bMÞefore“runningŽ¡‘Kâ:the–1Ðtests,‘Tªbut“need“not“install“the“program;‘w„y²!ou“should“write“the“self-tests“soŽ¡‘Kâ:that–¦fthey“w²!ork“when“the“program“is“built“but“not“installed.Ž©tt‘!GThe–Ö›folloš²!wing“targets“are“suggested“as“con˜v˜en˜tional“names,‘â¨for“programs“in“whic˜h“theyŽ¡‘Gare‘¦fuseful.Ž¦‘G¼installcheckŽ¡‘Kâ:»Pš²!erform– installation“tests“(if“an˜y).‘©ëThe“user“m˜ust“build“and“install“the“programŽ¡‘Kâ:bMÞefore–±{running“the“tests.‘ÿY‘ÿeou“should“not“assume“that“`¼$(bindir)»'“is“in“theŽ¡‘Kâ:searc²!h‘¦fpath.ŽŸ _‘G¼installdirsŽ¡‘Kâ:»It's–ºuseful“to“add“a“target“named“`¼installdirs»'“to“create“the“directoriesŽ¡‘Kâ:where–8e les“are“installed,‘\åand“their“paren²!t“directories.‘“ÛThere“is“a“script“calledŽ¡‘Kâ:`¼mkinstalldirs»'–®whicš²!h“is“con˜v˜enien˜t“for“this;‘1Ùy˜ou“can“ nd“it“in“the“T‘ÿeexinfoŽ¡‘Kâ:pacš²!k‘ÿdDage.‘ÝÝY‘ÿeou–¦fcan“use“a“rule“lik˜e“this:ŽŸë‘hʼ#–¿ªMake“sure“all“installation“directories“(e.g.“$(bindir))Ž¤ €‘hÊ#–¿ªactually“exist“by“making“them“if“necessary.Ž¡‘hÊinstalldirs:‘¿ªmkinstalldirsŽ¡’–Çß$(srcdir)/mkinstalldirs–¿ª$(bindir)“$(datadir)“\Ž¡’ ¿Ï$(libdir)–¿ª$(infodir)“\Ž¡’ ¿Ï$(mandir)ŽŸžI‘Kâ:»This–ËZrule“should“not“moMÞdify“the“directories“where“compilation“is“done.‘”ÙIt“shouldŽ¤ 33‘Kâ:do–¦fnothing“but“create“installation“directories.Ž‘GŸ 3͉ffŠ=Ÿ ó/‘ óŸü¾¬1ŽŽ‘¼texi2dvi–Ä»uses“T‘þ,³Ÿ[wEŽ›B X‘eto“do“the“real“w²!ork“of“formatting.‘ 1øT‘þ,³Ÿ[wEŽ˜X‘eis“not“distributed“withŽ¡‘T‘ÿeexinfo.ŽŽŒ‹59·Ÿò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e53ŽŽŽ ƒ3* ý ÌÖ‘Gê7.2.6‘d(Install–íMCommand“CategoriesŽŽŸ€‘!G»When–ì?writing“the“¼install“»target,‘ýµyš²!ou“m˜ust“classify“all“the“commands“in˜to“three“cate-Ž¤ 33‘Ggories:‘ÝÝnormal–¦fones,“¿pre-installation“»commands“and“¿pMÞost-installation“»commands.Ž©€‘!GNormal–ücommands“mo•²!v“e–ü les“in²!to“their“propšMÞer“places,‘…and“set“their“mo˜des.‘ÞõThey“ma²!yŽ¡‘Gnot–¦falter“anš²!y“ les“except“the“ones“that“come“en˜tirely“from“the“pac˜k‘ÿdDage“they“bMÞelong“to.Ž¦‘!GPre-installation–9and“pMÞost-installation“commands“ma²!y“alter“other“ les;‘:Hin“particular,‘$¨theyŽ¡‘Gcan–¦fedit“global“con guration“ les“or“data“bases.Ž¦‘!GPre-installation–Acommands“are“t²!ypically“executed“bMÞefore“the“normal“commands,‘§¸andŽ¡‘GpMÞost-installation–¦fcommands“are“t²!ypically“run“after“the“normal“commands.Ž¦‘!GThe–!>most“common“use“for“a“pMÞost-installation“command“is“to“run“¼install-info».‘NdThisŽ¡‘Gcannot–?bMÞe“done“with“a“normal“command,‘ʵsince“it“alters“a“ le“(the“Info“directory)“whic²!hŽ¡‘GdoMÞes–x×not“come“enš²!tirely“and“solely“from“the“pac˜k‘ÿdDage“bšMÞeing“installed.‘έIt“is“a“p˜ost-installationŽ¡‘Gcommand–‡ebšMÞecause“it“needs“to“b˜e“done“after“the“normal“command“whicš²!h“installs“the“pac˜k‘ÿdDage'sŽ¡‘GInfo‘¦f les.Ž¦‘!GMost–˜oprograms“don't“need“anš²!y“pre-installation“commands,‘›:but“w˜e“ha˜v˜e“the“feature“justŽ¡‘Gin–¦fcase“it“is“needed.Ž¦‘!GT‘ÿeo–÷·classify“the“commands“in“the“¼install“»rule“in²!to“these“three“categories,‘§insert“¿categoryŽ¡‘Glines‘è»among–¦fthem.‘ÝÝA“category“line“spMÞeci es“the“category“for“the“commands“that“follo²!w.Ž¦‘!GA‘»category–»Èline“consists“of“a“tab“and“a“reference“to“a“spMÞecial“Mak²!e“v‘ÿdDariable,‘ plus“anŽ¡‘Goptional–Wcommenš²!t“at“the“end.‘ÃjThere“are“three“v‘ÿdDariables“y˜ou“can“use,‘fíone“for“eac˜h“category;Ž¡‘Gthe–=­v‘ÿdDariable“name“spMÞeci es“the“category‘ÿe.‘£±Category“lines“are“no-ops“in“ordinary“executionŽ¡‘GbMÞecause–Ethese“three“Makš²!e“v‘ÿdDariables“are“normally“unde ned“(and“y˜ou“¾should‘V­not‘/»de ne“themŽ¡‘Gin–¦fthe“mak²!e le).Ž¦‘!GHere–/ware“the“three“pMÞossible“category“lines,‘Q»eacš²!h“with“a“commen˜t“that“explains“what“itŽ¡‘Gmeans:ŽŸÌÍ‘\öì¼$(PRE_INSTALL)‘¾R#‘¿ª»Pre-install–¦fcommands“follo²!w.Ž¤ €‘\öì¼$(POST_INSTALL)‘þ¨#‘¿ª»Pš²!ost-install–¦fcommands“follo˜w.Ž¡‘\öì¼$(NORMAL_INSTALL)‘ T#‘¿ª»Normal–¦fcommands“follo²!w.Ž¦‘!GIf–Šºy²!ou“don't“use“a“category“line“at“the“bMÞeginning“of“the“¼install“»rule,‘Call“the“commandsŽ¤ 33‘Gare––qclassi ed“as“normal“unš²!til“the“ rst“category“line.‘Ø‹If“y˜ou“don't“use“an˜y“category“lines,‘™¢allŽ¡‘Gthe–¦fcommands“are“classi ed“as“normal.Ž¦‘!GThese–¦fare“the“category“lines“for“¼uninstall»:ŽŸÌÍ‘\öì¼$(PRE_UNINSTALL)‘¾R#‘¿ª»Pre-uninstall–¦fcommands“follo²!w.Ž¤ €‘\öì¼$(POST_UNINSTALL)‘þ¨#‘¿ª»Pš²!ost-uninstall–¦fcommands“follo˜w.Ž¡‘\öì¼$(NORMAL_UNINSTALL)‘ T#‘¿ª»Normal–¦fcommands“follo²!w.Ž¦‘!GTš²!ypically‘ÿe,‘U¶a–ÿspre-uninstall“command“w˜ould“bMÞe“used“for“deleting“en˜tries“from“the“InfoŽ¤ 33‘Gdirectory‘ÿe.Ž¦‘!GIf–3®the“¼install“»or“¼uninstall“»target“has“anš²!y“depMÞendencies“whic˜h“act“as“subroutines“ofŽ¡‘Ginstallation,›ºPthen–¶Ty²!ou“should“start“¾e‘ÿp¹ach‘_»depMÞendency's“commands“with“a“category“line,˜andŽ¡‘Gstart–úœthe“main“target's“commands“with“a“category“line“also.‘Ú€This“w•²!a“y‘ÿe,‘O©y“ou–úœcan“ensureŽ¡‘Gthat–£eacš²!h“command“is“placed“in“the“righ˜t“category“regardless“of“whic˜h“of“the“depMÞendenciesŽ¡‘Gactually‘¦frun.Ž¦‘!GPre-installation–‡and“pMÞost-installation“commands“should“not“run“an²!y“programs“except“forŽ¡‘Gthese:ŽŽŒ‹6F[Ÿò‘G»Chapter–¦f7:‘ÝÝThe“Release“ProMÞcess’ e54ŽŽŽ ƒ3* ý ÌÖ‘.ùœ¼[–¿ªbasename“bash“cat“chgrp“chmod“chown“cmp“cp“dd“diff“echoŽ¤ €‘.ùœegrep–¿ªexpand“expr“false“fgrep“find“getopt“grep“gunzip“gzipŽ¡‘.ùœhostname–¿ªinstall“install-info“kill“ldconfig“ln“ls“md5sumŽ¡‘.ùœmkdir–¿ªmkfifo“mknod“mv“printenv“pwd“rm“rmdir“sed“sort“teeŽ¡‘.ùœtest–¿ªtouch“true“uname“xargs“yesŽ©:C‘!G»The–6´reason“for“distinguishing“the“commands“in“this“w•²!a“y–6´is“for“the“sak²!e“of“making“binaryŽ¤ 33‘Gpac•²!k›ÿdDages.‘Ö´T“ypically–ìa“binary“pac²!k˜age“con²!tains“all“the“executables“and“other“ les“that“needŽ¡‘Gto–¾QbšMÞe“installed,‘ÄLand“has“its“o²!wn“metho˜d“of“installing“them|so“it“do˜es“not“need“to“run“theŽ¡‘Gnormal–™Uinstallation“commands.‘Ù‚But“installing“the“binary“pac²!k‘ÿdDage“doMÞes“need“to“execute“theŽ¡‘Gpre-installation–¦fand“pMÞost-installation“commands.Ž¦‘!GPrograms–ç¨to“build“binary“pacš²!k‘ÿdDages“w˜ork“b˜y“extracting“the“pre-installation“and“pMÞost-Ž¡‘Ginstallation–¦fcommands.‘ÝÝHere“is“one“w•²!a“y–¦fof“extracting“the“pre-installation“commands:ŽŸ‡‘.ùœ¼make–¿ª-n“install“-o“all“\Ž¤ €‘Qw˜PRE_INSTALL=pre-install‘¿ª\Ž¡‘Qw˜POST_INSTALL=post-install‘¿ª\Ž¡‘Qw˜NORMAL_INSTALL=normal-install‘¿ª\Ž¡‘:xð|–¿ªgawk“-f“pre-install.awkŽ¦‘G»where–¦fthe“ le“`¼pre-install.awk»'“could“con²!tain“this:ŽŸ‡‘.ùœ¼$0–¿ª~“/^\t[“\t]*(normal_install|post_install)[“\t]*$/“{on“=“0}Ž¡‘.ùœon–¿ª{print“$0}Ž¡‘.ùœ$0–¿ª~“/^\t[“\t]*pre_install[“\t]*$/“{on“=“1}Ž¦‘!G»The–_…resulting“ le“of“pre-installation“commands“is“executed“as“a“shell“script“as“part“ofŽ¤ 33‘Ginstalling–¦fthe“binary“pac²!k‘ÿdDage.ŽŸ§‘Gá7.3‘™Making‘f@ReleasesŽŽŸ:C‘!G»P•²!ac“k‘ÿdDage–‡the“distribution“of“¼Foo–¦fversion“69.96–‡»up“in“a“gzippMÞed“tar“ le“with“the“nameŽ¡‘G`¼foo-69.96.tar.gz»'.‘ÝÝIt–¦fshould“unpacš²!k“in˜to“a“subMÞdirectory“named“`¼foo-69.96»'.Ž¦‘!GBuilding–ùUand“installing“the“program“should“nevš²!er“moMÞdify“an˜y“of“the“ les“con˜tained“in“theŽ¡‘Gdistribution.‘zàThis–Ú¼means“that“all“the“ les“that“form“part“of“the“program“in“anš²!y“w˜a˜y“m˜ustŽ¡‘GbMÞe–ù5classi ed“inš²!to“¿source“ les‘l·»and“¿non-source“ les».‘ÖJSource“ les“are“written“b˜y“h˜umans“andŽ¡‘Gnev•²!er›,uc“hanged˜automatically;‘o|non-source˜ les˜are˜proMÞduced˜from˜source˜ les˜b“y˜programsŽ¡‘Gunder–¦fthe“conš²!trol“of“the“Mak˜e le.Ž¦‘!GThe–h½distribution“should“conš²!tain“a“ le“named“`¼README»'“whic˜h“giv˜es“the“name“of“theŽ¡‘Gpac²!k‘ÿdDage,‘þand–Fa“general“description“of“what“it“došMÞes.‘î}It“is“also“go˜o˜d“to“explain“the“purp˜oseŽ¡‘Gof–Mßeacš²!h“of“the“ rst-lev˜el“subMÞdirectories“in“the“pac˜k‘ÿdDage,‘w¼if“there“are“an˜y‘ÿe.‘ÔGThe“`¼README»'“ leŽ¡‘Gshould– ueither“state“the“vš²!ersion“n˜um˜bMÞer“of“the“pac˜k‘ÿdDage,‘%ùor“refer“to“where“in“the“pac˜k‘ÿdDage“itŽ¡‘Gcan–¦fbMÞe“found.Ž¦‘!GThe–Q&`¼README»'“ le“should“refer“to“the“ le“`¼INSTALL»',‘b3whicš²!h“should“con˜tain“an“explanationŽ¡‘Gof–¦fthe“installation“proMÞcedure.Ž¦‘!GThe–+`¼README»'“ le“should“also“refer“to“the“ le“whicš²!h“con˜tains“the“cop˜ying“conditions.‘´ÃTheŽ¡‘GGNU› ›GPL,– Âif“used,‘,Ishould“bMÞe“in“a“ le“called“`¼COPYING»'.‘ªüIf“the“GNU˜LGPL˜is“used,‘,Iit“shouldŽ¡‘GbMÞe–¦fin“a“ le“called“`¼COPYING.LIB»'.Ž¦‘!GNaturally‘ÿe,‘mall–Ç9the“source“ les“mš²!ust“bMÞe“in“the“distribution.‘@UIt“is“ok‘ÿdDa˜y“to“include“non-Ž¡‘Gsource–ìÏ les“in“the“distribution,‘þiproš²!vided“they“are“up-to-date“and“mac˜hine-indepMÞenden˜t,‘þisoŽŽŒ‹7UIŸò‘G»Chapter–¦f8:‘ÝÝReferences“to“Non-F‘ÿeree“Soft•²!w“are–¦fand“DoMÞcumen²!tation‘pcª55ŽŽŽ ƒ3* ý ÌÖ‘Gthat–_building“the“distribution“normally“will“nev²!er“moMÞdify“them.‘ ÈW‘ÿee“commonly“includeŽ¤ 33‘Gnon-source–©h les“proMÞduced“bš²!y“Bison,–ª)¼lex»,“T‘þ,³Ÿ[wEŽ‘B X,–©hand“¼makeinfo»;‘ªêthis“helps“a˜v˜oid“unnecessaryŽ¡‘Gdep•MÞendencies›…b“et•²!w“een˜our˜distributions,‘ so˜that˜users˜can˜install˜whic“hev“er˜pac“k‘ÿdDages˜theyŽ¡‘Gw•²!an“t–¦fto“install.Ž©1%‘!GNon-source–tú les“that“migh²!t“actually“bšMÞe“mo˜di ed“b²!y“building“and“installing“the“programŽ¡‘Gshould– Õ½nevš²!er“»bMÞe“included“in“the“distribution.‘ª­So“if“y˜ou“do“distribute“non-source“ les,‘+‹alw˜a˜ysŽ¡‘Gmakš²!e–¦fsure“they“are“up“to“date“when“y˜ou“mak˜e“a“new“distribution.Ž¦‘!GMakš²!e–@_sure“that“the“directory“in˜to“whic˜h“the“distribution“unpac˜ks“(as“w˜ell“as“an˜y“sub-Ž¡‘Gdirectories)–Æare“all“w²!orld-writable“(ošMÞctal“mo˜de“777).‘<·This“is“so“that“old“v²!ersions“of“¼tarŽ¡‘G»whic•²!h›´ipreserv“e˜the˜o“wnership˜and˜pMÞermissions˜of˜the˜ les˜from˜the˜tar˜arc“hiv“e˜will˜bMÞe˜ableŽ¡‘Gto–¦fextract“all“the“ les“ev²!en“if“the“user“is“unprivileged.Ž¦‘!GMakš²!e–¦fsure“that“all“the“ les“in“the“distribution“are“w˜orld-readable.Ž¦‘!GMakš²!e–¸èsure“that“no“ le“name“in“the“distribution“is“more“than“14“c˜haracters“long.‘Ž³Lik˜ewise,Ž¡‘Gno–R» le“created“bš²!y“building“the“program“should“ha˜v˜e“a“name“longer“than“14“c˜haracters.‘ÁùTheŽ¡‘Greason–Úçfor“this“is“that“some“systems“adhere“to“a“foMÞolish“in²!terpretation“of“the“Áposix“»standard,Ž¡‘Gand–¦frefuse“to“opMÞen“a“longer“name,“rather“than“truncating“as“they“did“in“the“past.Ž¦‘!GDon't–›ÿinclude“anš²!y“sym˜bMÞolic“links“in“the“distribution“itself.‘…If“the“tar“ le“con˜tains“sym˜bMÞolicŽ¡‘Glinks,‘ãrthen–²¶pMÞeople“cannot“evš²!en“unpac˜k“it“on“systems“that“don't“suppMÞort“sym˜bMÞolic“links.‘Œ¢Also,Ž¡‘Gdon't–ƒñuse“mš²!ultiple“names“for“one“ le“in“di eren˜t“directories,‘»TbMÞecause“certain“ le“systemsŽ¡‘Gcannot–¦fhandle“this“and“that“prev•²!en“ts›¦funpac“king˜the˜distribution.Ž¦‘!GT‘ÿery–Yãto“mak²!e“sure“that“all“the“ le“names“will“bMÞe“unique“on“MS-DOS.“A‘Yµname“on“MS-Ž¡‘GDOS‘Üconsists–Ü°of“up“to“8“cš²!haracters,‘jAoptionally“follo˜w˜ed“b˜y“a“p•MÞerio“d–Ü°and“up“to“threeŽ¡‘Gcš²!haracters.‘ =’MS-DOS‘ÅÁwill–ÆMtruncate“extra“c˜haracters“bšMÞoth“b˜efore“and“after“the“p˜erio˜d.Ž¡‘GThš²!us,‘ȃ`¼foobarhacker.c»'–[Jand“`¼foobarhacker.o»'“are“not“am˜biguous;‘5¼they“are“truncatedŽ¡‘Gto–¦f`¼foobarha.c»'“and“`¼foobarha.o»',“whic²!h“are“distinct.Ž¦‘!GInclude–ñin“yš²!our“distribution“a“cop˜y“of“the“`¼texinfo.tex»'“y˜ou“used“to“test“prin˜t“an˜yŽ¡‘G`¼*.texinfo»'–¦for“`¼*.texi»'“ les.Ž¦‘!GLik•²!ewise,‘]^if›Ky“our˜program˜uses˜small˜GNU‘Ksoft“w“are˜pac“k‘ÿdDages˜lik“e˜regex,–]^getopt,“obstac²!k,Ž¡‘Gor––btermcap,‘™–include“them“in“the“distribution“ le.‘؆Leaš²!ving“them“out“w˜ould“mak˜e“the“distri-Ž¡‘Gbution–C* le“a“little“smaller“at“the“expšMÞense“of“p˜ossible“incon•²!v“enience–C*to“a“user“who“do˜esn'tŽ¡‘Gkno²!w–¦fwhat“other“ les“to“get.ŽŸ3²CŸí‘GØ8‘ ¸QReferences–z³to“Non-F‘þaGree“Soft–ÿuÂw“are‘z³andŽŸ‘%éDo‘Š=cumen‘ÿuÂtationŽŽŸ- ‘!G»A–_GNU“program–—should“not“recommend“use“of“an²!y“non-free“program.‘iqW‘ÿee“can't“stopŽ¡‘Gsome–.apšMÞeople“from“writing“proprietary“programs,‘Fbor“stop“other“p˜eople“from“using“them.‘µÛButŽ¡‘Gwš²!e–¦fcan“and“should“a˜v˜oid“helping“to“adv˜ertise“them“to“new“customers.Ž¦‘!GSometimes–Ùit“is“impMÞortanš²!t“to“men˜tion“ho˜w“to“build“y˜our“pac˜k‘ÿdDage“on“top“of“some“non-freeŽ¡‘GopMÞerating–´system“or“other“non-free“base“pacš²!k‘ÿdDage.‘+ÇIn“suc˜h“cases,‘1‡please“men˜tion“the“nameŽ¡‘Gof–b¦the“non-free“pacš²!k‘ÿdDage“or“system“in“the“briefest“pMÞossible“w˜a˜y‘ÿe.‘ÇHDon't“include“an˜y“referencesŽ¡‘Gfor– ¡where“to“ nd“more“information“abšMÞout“the“proprietary“program.‘ªFThe“goal“should“b˜e“thatŽ¡‘GpšMÞeople–„already“using“the“proprietary“program“will“get“the“advice“they“need“ab˜out“ho²!w“toŽŽŒ‹8cJŸò‘G»Chapter–¦f8:‘ÝÝReferences“to“Non-F‘ÿeree“Soft•²!w“are–¦fand“DoMÞcumen²!tation‘pcª56ŽŽŽ ƒ3* ý ÌÖ‘Guse– y²!our“free“program,‘:õwhile“pMÞeople“who“don't“already“use“the“proprietary“program“will“notŽ¤ 33‘Gsee–¦fanš²!ything“to“encourage“them“to“tak˜e“an“in˜terest“in“it.ŽŸ33‘!GLik•²!ewise,‘Ra›0GNU‘/üpac“k‘ÿdDage˜should˜not˜refer˜the˜user˜to˜an“y˜non-free˜doMÞcumen“tation˜forŽ¡‘Gfree›åísoft•²!w“are.‘µThe˜need˜for˜free˜doMÞcumen“tation˜to˜go˜with˜free˜soft“w“are˜is˜no“w˜a˜ma‘›»jor˜foMÞcusŽ¡‘Gof–M the“GNU‘Lópro‘›»ject;‘jÓto“shoš²!w“that“w˜e“are“serious“abšMÞout“the“need“for“free“do˜cumen•²!tation,‘^éw“eŽ¡‘Gmš²!ust–¦fnot“undermine“our“pMÞosition“b˜y“recommending“use“of“doMÞcumen˜tation“that“isn't“free.ŽŽŒ‹ÿÿÿÿs’Ÿò’À¥T»iŽŽŽ ƒ3* ý ÌÖ‘GØT‘þaGable–z³of“Con–ÿuÂten“tsŽŽŸ"d ‘Gá1‘32Abšs3out–ffthe“GNU“Co˜ding“Standards‘^«‘32ó7F C–ff cmbxti10â.Ž–…‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž‘J á1ŽŸkþ‘G2‘32Keeping–ffF›þ¦free“Soft•ŒÌw“are‘ffF˜ree‘»Š‘32â.Ž–…‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž‘§á1Ž¤ÿ‘6G»2.1‘ ó5Referring–¦fto“Proprietary“ProgramsY%‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ .U»1Ž© 33‘6G2.2‘ ó5Accepting‘¦fCon²!tributions‘_§‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ 4×»2ŽŸ2‘Gá3‘32General–ffProgram“Design‘X]‘32â.Ž–…‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž‘CÒá2Ž¡‘6G»3.1‘ ó5Compatibilitš²!y–¦fwith“Other“Implemen˜tations‘$‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ÚT»2Ž¦‘6G3.2‘ ó5Using–¦fNon-standard“F‘ÿeeaturesUO‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ *»3Ž¦‘6G3.3‘ ó5Áansi–¦f»C“and“pre-Áansi“»C‘Mú‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ #*»3Ž¦‘6G3.4‘ ó5Using–¦fLanguages“Other“Than“C‘‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ rH»4ŽŸ2‘Gá4‘32Program–ffBehaŒÌvior“for“All“ProgramsË‘32â.Ž–…‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž‘ üAá5Ž¡‘6G»4.1‘ ó5W‘ÿeriting–¦fRobust“Programs‘µå‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ‹»5Ž¦‘6G4.2‘ ó5Library‘¦fBeha²!vior‘ô‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ Ü%»6Ž¦‘6G4.3‘ ó5F‘ÿeormatting–¦fError“Messages‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘å7»6Ž¦‘6G4.4‘ ó5Standards–¦ffor“Command“Line“In²!terfacesh«‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ =Û»7Ž¦‘6G4.5‘ ó5T‘ÿeable–¦fof“Long“Options‘ÿ‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ÔO»9Ž¦‘6G4.6‘ ó5Memory‘¦fUsage‘Þz‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ³«»25ŽŸ2‘Gá5‘32Making–ffThe“Best“Use“of“C‘@9‘32â.Ž–…‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž‘+¯á25Ž¡‘6G»5.1‘ ó5F–ÿeormatting›¦fY“our˜Source˜CoMÞde‘૑阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ µÜ»25Ž¦‘6G5.2‘ ó5Commen²!ting–¦fY›ÿeour“W˜ork‘>*‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ Z»27Ž¦‘6G5.3‘ ó5Clean–¦fUse“of“C“Constructs‘-ʑ阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ û»28Ž¦‘6G5.4‘ ó5Naming–¦fV›ÿeariables“and“F˜unctions‘‰Ê‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ^û»29Ž¦‘6G5.5‘ ó5P•²!ortabilit“y›¦fbMÞet“w“een˜System˜T“ypMÞes‘‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ Û1»30Ž¦‘6G5.6‘ ó5P•²!ortabilit“y›¦fbMÞet“w“een˜Ácpu»s‘֑阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ Ö»31Ž¦‘6G5.7‘ ó5Calling–¦fSystem“F‘ÿeunctions‘rQ‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ G‚»31Ž¦‘6G5.8‘ ó5In²!ternationalization‘sU‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ H…»33Ž¦‘6G5.9‘ ó5Mmap‘ë‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ e»34ŽŸ2‘Gá6‘32Dos3cumenŒÌting‘ffPrograms‘3‘32â.Ž–…‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž‘~á35Ž¡‘6G»6.1‘ ó5GNU‘¦fMan²!uals‘7 ‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ;»35Ž¦‘6G6.2‘ ó5Man²!ual–¦fStructure“Details‘À/‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ •`»36Ž¦‘6G6.3‘ ó5License–¦ffor“Man²!uals‘Û‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ °¯»36Ž¦‘6G6.4‘ ó5The–¦fNEWS“File‘ב阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ s»37Ž¦‘6G6.5‘ ó5Change‘¦fLogs‘¤á‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ z»37Ž¦‘ZG6.5.1‘ ó5Change–¦fLog“Concepts‘Ø?‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ­o»37Ž¦‘ZG6.5.2‘ ó5St²!yle–¦fof“Change“Logs‘„ƒ‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ Y´»38Ž¦‘ZG6.5.3‘ ó5Simple‘¦fChanges‘Ba‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ‘»38Ž¦‘ZG6.5.4‘ ó5Conditional‘¦fChanges‘Ã;‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ˜k»39Ž¦‘6G6.6‘ ó5Man‘¦fP²!ages‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘Û?»39Ž¦‘6G6.7‘ ó5Reading–¦fother“Man²!uals‘š‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ o>»40ŽŽŒ‹ÿÿÿþv¿Ÿò’½š©»iiŽŽŽ ƒ3* ý†ÌÖ‘Gá7‘32The–ffRelease“Pros3cess‘vw‘32â.Ž–…‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž‘aíá40ŽŸÿ‘6G»7.1‘ ó5Ho²!w–¦fCon guration“Should“W‘ÿeork‘[‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ 0B»40Ž¤ 33‘6G7.2‘ ó5Mak•²!e le‘¦fCon“v“en“tions‘9†‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ¶»42Ž¡‘ZG7.2.1‘ ó5General›¦fCon•²!v“en“tions˜for˜Mak“e les‘jM‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ?~»42Ž¡‘ZG7.2.2‘ ó5Utilities–¦fin“Mak²!e les‘W-‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ,^»43Ž¡‘ZG7.2.3‘ ó5V‘ÿeariables–¦ffor“SpMÞecifying“Commands‘²é‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ˆ»44Ž¡‘ZG7.2.4‘ ó5V‘ÿeariables–¦ffor“Installation“Directories‘{‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ P6»45Ž¡‘ZG7.2.5‘ ó5Standard–¦fT‘ÿeargets“for“Users‘p ‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ E9»49Ž¡‘ZG7.2.6‘ ó5Install–¦fCommand“Categoriestƒ‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ I³»53Ž¡‘6G7.3‘ ó5Making‘¦fReleases‘(‘阾.Ž–.Ô‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž“‘é˜.Ž‘ ýÍ»54ŽŸ33‘Gá8‘32References–ffto“Non-F‘þ¦free“Soft•ŒÌw“are‘ffandŽŸ‘2w«Dos3cumenŒÌtation‘“‘32â.Ž–…‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž“‘32.Ž‘~’á55ŽŽŒø¢dƒ’À;è‡ Çïÿ<ó?ÂÖN  #× cmbx12ó<Œ-øff cmcsc10ó7F C–ff cmbxti10ó6ÂÖN ff cmbx12ó-ÂÖN G® cmbx12ó$ÂÖN ¼j cmbx12ó!",š ó3 cmsy10óßê