automake.texi 503 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355835683578358835983608361836283638364836583668367836883698370837183728373837483758376837783788379838083818382838383848385838683878388838983908391839283938394839583968397839883998400840184028403840484058406840784088409841084118412841384148415841684178418841984208421842284238424842584268427842884298430843184328433843484358436843784388439844084418442844384448445844684478448844984508451845284538454845584568457845884598460846184628463846484658466846784688469847084718472847384748475847684778478847984808481848284838484848584868487848884898490849184928493849484958496849784988499850085018502850385048505850685078508850985108511851285138514851585168517851885198520852185228523852485258526852785288529853085318532853385348535853685378538853985408541854285438544854585468547854885498550855185528553855485558556855785588559856085618562856385648565856685678568856985708571857285738574857585768577857885798580858185828583858485858586858785888589859085918592859385948595859685978598859986008601860286038604860586068607860886098610861186128613861486158616861786188619862086218622862386248625862686278628862986308631863286338634863586368637863886398640864186428643864486458646864786488649865086518652865386548655865686578658865986608661866286638664866586668667866886698670867186728673867486758676867786788679868086818682868386848685868686878688868986908691869286938694869586968697869886998700870187028703870487058706870787088709871087118712871387148715871687178718871987208721872287238724872587268727872887298730873187328733873487358736873787388739874087418742874387448745874687478748874987508751875287538754875587568757875887598760876187628763876487658766876787688769877087718772877387748775877687778778877987808781878287838784878587868787878887898790879187928793879487958796879787988799880088018802880388048805880688078808880988108811881288138814881588168817881888198820882188228823882488258826882788288829883088318832883388348835883688378838883988408841884288438844884588468847884888498850885188528853885488558856885788588859886088618862886388648865886688678868886988708871887288738874887588768877887888798880888188828883888488858886888788888889889088918892889388948895889688978898889989008901890289038904890589068907890889098910891189128913891489158916891789188919892089218922892389248925892689278928892989308931893289338934893589368937893889398940894189428943894489458946894789488949895089518952895389548955895689578958895989608961896289638964896589668967896889698970897189728973897489758976897789788979898089818982898389848985898689878988898989908991899289938994899589968997899889999000900190029003900490059006900790089009901090119012901390149015901690179018901990209021902290239024902590269027902890299030903190329033903490359036903790389039904090419042904390449045904690479048904990509051905290539054905590569057905890599060906190629063906490659066906790689069907090719072907390749075907690779078907990809081908290839084908590869087908890899090909190929093909490959096909790989099910091019102910391049105910691079108910991109111911291139114911591169117911891199120912191229123912491259126912791289129913091319132913391349135913691379138913991409141914291439144914591469147914891499150915191529153915491559156915791589159916091619162916391649165916691679168916991709171917291739174917591769177917891799180918191829183918491859186918791889189919091919192919391949195919691979198919992009201920292039204920592069207920892099210921192129213921492159216921792189219922092219222922392249225922692279228922992309231923292339234923592369237923892399240924192429243924492459246924792489249925092519252925392549255925692579258925992609261926292639264926592669267926892699270927192729273927492759276927792789279928092819282928392849285928692879288928992909291929292939294929592969297929892999300930193029303930493059306930793089309931093119312931393149315931693179318931993209321932293239324932593269327932893299330933193329333933493359336933793389339934093419342934393449345934693479348934993509351935293539354935593569357935893599360936193629363936493659366936793689369937093719372937393749375937693779378937993809381938293839384938593869387938893899390939193929393939493959396939793989399940094019402940394049405940694079408940994109411941294139414941594169417941894199420942194229423942494259426942794289429943094319432943394349435943694379438943994409441944294439444944594469447944894499450945194529453945494559456945794589459946094619462946394649465946694679468946994709471947294739474947594769477947894799480948194829483948494859486948794889489949094919492949394949495949694979498949995009501950295039504950595069507950895099510951195129513951495159516951795189519952095219522952395249525952695279528952995309531953295339534953595369537953895399540954195429543954495459546954795489549955095519552955395549555955695579558955995609561956295639564956595669567956895699570957195729573957495759576957795789579958095819582958395849585958695879588958995909591959295939594959595969597959895999600960196029603960496059606960796089609961096119612961396149615961696179618961996209621962296239624962596269627962896299630963196329633963496359636963796389639964096419642964396449645964696479648964996509651965296539654965596569657965896599660966196629663966496659666966796689669967096719672967396749675967696779678967996809681968296839684968596869687968896899690969196929693969496959696969796989699970097019702970397049705970697079708970997109711971297139714971597169717971897199720972197229723972497259726972797289729973097319732973397349735973697379738973997409741974297439744974597469747974897499750975197529753975497559756975797589759976097619762976397649765976697679768976997709771977297739774977597769777977897799780978197829783978497859786978797889789979097919792979397949795979697979798979998009801980298039804980598069807980898099810981198129813981498159816981798189819982098219822982398249825982698279828982998309831983298339834983598369837983898399840984198429843984498459846984798489849985098519852985398549855985698579858985998609861986298639864986598669867986898699870987198729873987498759876987798789879988098819882988398849885988698879888988998909891989298939894989598969897989898999900990199029903990499059906990799089909991099119912991399149915991699179918991999209921992299239924992599269927992899299930993199329933993499359936993799389939994099419942994399449945994699479948994999509951995299539954995599569957995899599960996199629963996499659966996799689969997099719972997399749975997699779978997999809981998299839984998599869987998899899990999199929993999499959996999799989999100001000110002100031000410005100061000710008100091001010011100121001310014100151001610017100181001910020100211002210023100241002510026100271002810029100301003110032100331003410035100361003710038100391004010041100421004310044100451004610047100481004910050100511005210053100541005510056100571005810059100601006110062100631006410065100661006710068100691007010071100721007310074100751007610077100781007910080100811008210083100841008510086100871008810089100901009110092100931009410095100961009710098100991010010101101021010310104101051010610107101081010910110101111011210113101141011510116101171011810119101201012110122101231012410125101261012710128101291013010131101321013310134101351013610137101381013910140101411014210143101441014510146101471014810149101501015110152101531015410155101561015710158101591016010161101621016310164101651016610167101681016910170101711017210173101741017510176101771017810179101801018110182101831018410185101861018710188101891019010191101921019310194101951019610197101981019910200102011020210203102041020510206102071020810209102101021110212102131021410215102161021710218102191022010221102221022310224102251022610227102281022910230102311023210233102341023510236102371023810239102401024110242102431024410245102461024710248102491025010251102521025310254102551025610257102581025910260102611026210263102641026510266102671026810269102701027110272102731027410275102761027710278102791028010281102821028310284102851028610287102881028910290102911029210293102941029510296102971029810299103001030110302103031030410305103061030710308103091031010311103121031310314103151031610317103181031910320103211032210323103241032510326103271032810329103301033110332103331033410335103361033710338103391034010341103421034310344103451034610347103481034910350103511035210353103541035510356103571035810359103601036110362103631036410365103661036710368103691037010371103721037310374103751037610377103781037910380103811038210383103841038510386103871038810389103901039110392103931039410395103961039710398103991040010401104021040310404104051040610407104081040910410104111041210413104141041510416104171041810419104201042110422104231042410425104261042710428104291043010431104321043310434104351043610437104381043910440104411044210443104441044510446104471044810449104501045110452104531045410455104561045710458104591046010461104621046310464104651046610467104681046910470104711047210473104741047510476104771047810479104801048110482104831048410485104861048710488104891049010491104921049310494104951049610497104981049910500105011050210503105041050510506105071050810509105101051110512105131051410515105161051710518105191052010521105221052310524105251052610527105281052910530105311053210533105341053510536105371053810539105401054110542105431054410545105461054710548105491055010551105521055310554105551055610557105581055910560105611056210563105641056510566105671056810569105701057110572105731057410575105761057710578105791058010581105821058310584105851058610587105881058910590105911059210593105941059510596105971059810599106001060110602106031060410605106061060710608106091061010611106121061310614106151061610617106181061910620106211062210623106241062510626106271062810629106301063110632106331063410635106361063710638106391064010641106421064310644106451064610647106481064910650106511065210653106541065510656106571065810659106601066110662106631066410665106661066710668106691067010671106721067310674106751067610677106781067910680106811068210683106841068510686106871068810689106901069110692106931069410695106961069710698106991070010701107021070310704107051070610707107081070910710107111071210713107141071510716107171071810719107201072110722107231072410725107261072710728107291073010731107321073310734107351073610737107381073910740107411074210743107441074510746107471074810749107501075110752107531075410755107561075710758107591076010761107621076310764107651076610767107681076910770107711077210773107741077510776107771077810779107801078110782107831078410785107861078710788107891079010791107921079310794107951079610797107981079910800108011080210803108041080510806108071080810809108101081110812108131081410815108161081710818108191082010821108221082310824108251082610827108281082910830108311083210833108341083510836108371083810839108401084110842108431084410845108461084710848108491085010851108521085310854108551085610857108581085910860108611086210863108641086510866108671086810869108701087110872108731087410875108761087710878108791088010881108821088310884108851088610887108881088910890108911089210893108941089510896108971089810899109001090110902109031090410905109061090710908109091091010911109121091310914109151091610917109181091910920109211092210923109241092510926109271092810929109301093110932109331093410935109361093710938109391094010941109421094310944109451094610947109481094910950109511095210953109541095510956109571095810959109601096110962109631096410965109661096710968109691097010971109721097310974109751097610977109781097910980109811098210983109841098510986109871098810989109901099110992109931099410995109961099710998109991100011001110021100311004110051100611007110081100911010110111101211013110141101511016110171101811019110201102111022110231102411025110261102711028110291103011031110321103311034110351103611037110381103911040110411104211043110441104511046110471104811049110501105111052110531105411055110561105711058110591106011061110621106311064110651106611067110681106911070110711107211073110741107511076110771107811079110801108111082110831108411085110861108711088110891109011091110921109311094110951109611097110981109911100111011110211103111041110511106111071110811109111101111111112111131111411115111161111711118111191112011121111221112311124111251112611127111281112911130111311113211133111341113511136111371113811139111401114111142111431114411145111461114711148111491115011151111521115311154111551115611157111581115911160111611116211163111641116511166111671116811169111701117111172111731117411175111761117711178111791118011181111821118311184111851118611187111881118911190111911119211193111941119511196111971119811199112001120111202112031120411205112061120711208112091121011211112121121311214112151121611217112181121911220112211122211223112241122511226112271122811229112301123111232112331123411235112361123711238112391124011241112421124311244112451124611247112481124911250112511125211253112541125511256112571125811259112601126111262112631126411265112661126711268112691127011271112721127311274112751127611277112781127911280112811128211283112841128511286112871128811289112901129111292112931129411295112961129711298112991130011301113021130311304113051130611307113081130911310113111131211313113141131511316113171131811319113201132111322113231132411325113261132711328113291133011331113321133311334113351133611337113381133911340113411134211343113441134511346113471134811349113501135111352113531135411355113561135711358113591136011361113621136311364113651136611367113681136911370113711137211373113741137511376113771137811379113801138111382113831138411385113861138711388113891139011391113921139311394113951139611397113981139911400114011140211403114041140511406114071140811409114101141111412114131141411415114161141711418114191142011421114221142311424114251142611427114281142911430114311143211433114341143511436114371143811439114401144111442114431144411445114461144711448114491145011451114521145311454114551145611457114581145911460114611146211463114641146511466114671146811469114701147111472114731147411475114761147711478114791148011481114821148311484114851148611487114881148911490114911149211493114941149511496114971149811499115001150111502115031150411505115061150711508115091151011511115121151311514115151151611517115181151911520115211152211523115241152511526115271152811529115301153111532115331153411535115361153711538115391154011541115421154311544115451154611547115481154911550115511155211553115541155511556115571155811559115601156111562115631156411565115661156711568115691157011571115721157311574115751157611577115781157911580115811158211583115841158511586115871158811589115901159111592115931159411595115961159711598115991160011601116021160311604116051160611607116081160911610116111161211613116141161511616116171161811619116201162111622116231162411625116261162711628116291163011631116321163311634116351163611637116381163911640116411164211643116441164511646116471164811649116501165111652116531165411655116561165711658116591166011661116621166311664116651166611667116681166911670116711167211673116741167511676116771167811679116801168111682116831168411685116861168711688116891169011691116921169311694116951169611697116981169911700117011170211703117041170511706117071170811709117101171111712117131171411715117161171711718117191172011721117221172311724117251172611727117281172911730117311173211733117341173511736117371173811739117401174111742117431174411745117461174711748117491175011751117521175311754117551175611757117581175911760117611176211763117641176511766117671176811769117701177111772117731177411775117761177711778117791178011781117821178311784117851178611787117881178911790117911179211793117941179511796117971179811799118001180111802118031180411805118061180711808118091181011811118121181311814118151181611817118181181911820118211182211823118241182511826118271182811829118301183111832118331183411835118361183711838118391184011841118421184311844118451184611847118481184911850118511185211853118541185511856118571185811859118601186111862118631186411865118661186711868118691187011871118721187311874118751187611877118781187911880118811188211883118841188511886118871188811889118901189111892118931189411895118961189711898118991190011901119021190311904119051190611907119081190911910119111191211913119141191511916119171191811919119201192111922119231192411925119261192711928119291193011931119321193311934119351193611937119381193911940119411194211943119441194511946119471194811949119501195111952119531195411955119561195711958119591196011961119621196311964119651196611967119681196911970119711197211973119741197511976119771197811979119801198111982119831198411985119861198711988119891199011991119921199311994119951199611997119981199912000120011200212003120041200512006120071200812009120101201112012120131201412015120161201712018120191202012021120221202312024120251202612027120281202912030120311203212033120341203512036120371203812039120401204112042120431204412045120461204712048120491205012051120521205312054120551205612057120581205912060120611206212063120641206512066120671206812069120701207112072120731207412075120761207712078120791208012081120821208312084120851208612087120881208912090120911209212093120941209512096120971209812099121001210112102121031210412105121061210712108121091211012111121121211312114121151211612117121181211912120121211212212123121241212512126121271212812129121301213112132121331213412135121361213712138121391214012141121421214312144121451214612147121481214912150121511215212153121541215512156121571215812159121601216112162121631216412165121661216712168121691217012171121721217312174121751217612177121781217912180121811218212183121841218512186121871218812189121901219112192121931219412195121961219712198121991220012201122021220312204122051220612207122081220912210122111221212213122141221512216122171221812219122201222112222122231222412225122261222712228122291223012231122321223312234122351223612237122381223912240122411224212243122441224512246122471224812249122501225112252122531225412255122561225712258122591226012261122621226312264122651226612267122681226912270122711227212273122741227512276122771227812279122801228112282122831228412285122861228712288122891229012291122921229312294122951229612297122981229912300123011230212303123041230512306123071230812309123101231112312123131231412315123161231712318123191232012321123221232312324123251232612327123281232912330123311233212333123341233512336123371233812339123401234112342123431234412345123461234712348123491235012351123521235312354123551235612357123581235912360123611236212363123641236512366123671236812369123701237112372123731237412375123761237712378123791238012381123821238312384123851238612387123881238912390123911239212393123941239512396123971239812399124001240112402124031240412405124061240712408124091241012411124121241312414124151241612417124181241912420124211242212423124241242512426124271242812429124301243112432124331243412435124361243712438124391244012441124421244312444124451244612447124481244912450124511245212453124541245512456124571245812459124601246112462124631246412465124661246712468124691247012471124721247312474124751247612477124781247912480124811248212483124841248512486124871248812489124901249112492124931249412495124961249712498124991250012501125021250312504125051250612507125081250912510125111251212513125141251512516125171251812519125201252112522125231252412525125261252712528125291253012531125321253312534125351253612537125381253912540125411254212543125441254512546125471254812549125501255112552125531255412555125561255712558125591256012561125621256312564125651256612567125681256912570125711257212573125741257512576125771257812579125801258112582125831258412585125861258712588125891259012591125921259312594125951259612597125981259912600126011260212603126041260512606126071260812609126101261112612126131261412615126161261712618126191262012621126221262312624126251262612627126281262912630126311263212633126341263512636126371263812639126401264112642126431264412645126461264712648126491265012651126521265312654126551265612657126581265912660126611266212663126641266512666126671266812669126701267112672126731267412675126761267712678126791268012681126821268312684126851268612687126881268912690126911269212693126941269512696126971269812699127001270112702127031270412705127061270712708127091271012711127121271312714127151271612717127181271912720127211272212723127241272512726127271272812729127301273112732127331273412735127361273712738127391274012741127421274312744127451274612747127481274912750127511275212753127541275512756127571275812759127601276112762127631276412765127661276712768127691277012771127721277312774127751277612777127781277912780127811278212783127841278512786127871278812789127901279112792127931279412795127961279712798127991280012801128021280312804128051280612807128081280912810128111281212813128141281512816128171281812819128201282112822128231282412825128261282712828128291283012831128321283312834128351283612837128381283912840128411284212843128441284512846128471284812849128501285112852128531285412855128561285712858128591286012861128621286312864128651286612867128681286912870128711287212873128741287512876128771287812879128801288112882128831288412885128861288712888128891289012891128921289312894128951289612897128981289912900129011290212903129041290512906129071290812909129101291112912129131291412915129161291712918129191292012921129221292312924129251292612927129281292912930129311293212933129341293512936129371293812939129401294112942129431294412945129461294712948129491295012951129521295312954129551295612957129581295912960129611296212963129641296512966129671296812969129701297112972129731297412975129761297712978129791298012981129821298312984129851298612987129881298912990129911299212993129941299512996129971299812999130001300113002130031300413005130061300713008130091301013011130121301313014130151301613017130181301913020130211302213023130241302513026130271302813029130301303113032130331303413035130361303713038130391304013041130421304313044130451304613047130481304913050130511305213053130541305513056130571305813059130601306113062130631306413065130661306713068130691307013071130721307313074130751307613077130781307913080130811308213083130841308513086130871308813089130901309113092130931309413095130961309713098130991310013101131021310313104131051310613107131081310913110131111311213113131141311513116131171311813119131201312113122131231312413125131261312713128131291313013131131321313313134131351313613137131381313913140131411314213143131441314513146131471314813149131501315113152131531315413155131561315713158131591316013161131621316313164131651316613167131681316913170131711317213173131741317513176131771317813179131801318113182131831318413185131861318713188131891319013191131921319313194131951319613197131981319913200132011320213203132041320513206132071320813209132101321113212132131321413215
  1. \input texinfo @c -*-texinfo-*-
  2. @c %**start of header
  3. @setfilename automake.info
  4. @settitle automake
  5. @documentencoding UTF-8
  6. @documentlanguage en
  7. @setchapternewpage off
  8. @c %**end of header
  9. @include version.texi
  10. @c @ovar(ARG, DEFAULT)
  11. @c -------------------
  12. @c The ARG is an optional argument. To be used for macro arguments in
  13. @c their documentation (@defmac).
  14. @macro ovar{varname}
  15. @r{[}@var{\varname\}@r{]}
  16. @end macro
  17. @set PACKAGE_BUGREPORT bug-automake@@gnu.org
  18. @copying
  19. This manual is for GNU Automake (version @value{VERSION},
  20. @value{UPDATED}), a program that creates GNU standards-compliant
  21. Makefiles from template files.
  22. Copyright @copyright{} 1995-2017 Free Software Foundation, Inc.
  23. @quotation
  24. Permission is granted to copy, distribute and/or modify this document
  25. under the terms of the GNU Free Documentation License,
  26. Version 1.3 or any later version published by the Free Software
  27. Foundation; with no Invariant Sections, with no Front-Cover texts,
  28. and with no Back-Cover Texts. A copy of the license is included in the
  29. section entitled ``GNU Free Documentation License.''
  30. @end quotation
  31. @end copying
  32. @dircategory Software development
  33. @direntry
  34. * Automake: (automake). Making GNU standards-compliant Makefiles.
  35. @end direntry
  36. @dircategory Individual utilities
  37. @direntry
  38. * aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4.
  39. * automake-invocation: (automake)automake Invocation. Generating Makefile.in.
  40. @end direntry
  41. @titlepage
  42. @title GNU Automake
  43. @subtitle For version @value{VERSION}, @value{UPDATED}
  44. @author David MacKenzie
  45. @author Tom Tromey
  46. @author Alexandre Duret-Lutz
  47. @author Ralf Wildenhues
  48. @author Stefano Lattarini
  49. @page
  50. @vskip 0pt plus 1filll
  51. @insertcopying
  52. @end titlepage
  53. @contents
  54. @c We use the following macros to define indices:
  55. @c @cindex concepts, and anything that does not fit elsewhere
  56. @c @vindex Makefile variables
  57. @c @trindex targets
  58. @c @acindex Autoconf/Automake/Libtool/M4/... macros
  59. @c @opindex tool options
  60. @c Define an index of configure macros.
  61. @defcodeindex ac
  62. @c Define an index of options.
  63. @defcodeindex op
  64. @c Define an index of targets.
  65. @defcodeindex tr
  66. @c Define an index of commands.
  67. @defcodeindex cm
  68. @c Put the macros in the function index.
  69. @syncodeindex ac fn
  70. @c Put everything else into one index (arbitrarily chosen to be the
  71. @c concept index).
  72. @syncodeindex op cp
  73. @syncodeindex tr cp
  74. @syncodeindex cm cp
  75. @ifnottex
  76. @node Top
  77. @comment node-name, next, previous, up
  78. @top GNU Automake
  79. @insertcopying
  80. @menu
  81. * Introduction:: Automake's purpose
  82. * Autotools Introduction:: An Introduction to the Autotools
  83. * Generalities:: General ideas
  84. * Examples:: Some example packages
  85. * automake Invocation:: Creating a Makefile.in
  86. * configure:: Scanning configure.ac, using aclocal
  87. * Directories:: Declaring subdirectories
  88. * Programs:: Building programs and libraries
  89. * Other Objects:: Other derived objects
  90. * Other GNU Tools:: Other GNU Tools
  91. * Documentation:: Building documentation
  92. * Install:: What gets installed
  93. * Clean:: What gets cleaned
  94. * Dist:: What goes in a distribution
  95. * Tests:: Support for test suites
  96. * Rebuilding:: Automatic rebuilding of Makefile
  97. * Options:: Changing Automake's behavior
  98. * Miscellaneous:: Miscellaneous rules
  99. * Include:: Including extra files in an Automake template
  100. * Conditionals:: Conditionals
  101. * Silencing Make:: Obtain less verbose output from @command{make}
  102. * Gnits:: The effect of @option{--gnu} and @option{--gnits}
  103. * Not Enough:: When Automake is not Enough
  104. * Distributing:: Distributing the Makefile.in
  105. * API Versioning:: About compatibility between Automake versions
  106. * Upgrading:: Upgrading to a Newer Automake Version
  107. * FAQ:: Frequently Asked Questions
  108. * Copying This Manual:: How to make copies of this manual
  109. * Indices:: Indices of variables, macros, and concepts
  110. @detailmenu
  111. --- The Detailed Node Listing ---
  112. An Introduction to the Autotools
  113. * GNU Build System:: Introducing the GNU Build System
  114. * Use Cases:: Use Cases for the GNU Build System
  115. * Why Autotools:: How Autotools Help
  116. * Hello World:: A Small Hello World Package
  117. Use Cases for the GNU Build System
  118. * Basic Installation:: Common installation procedure
  119. * Standard Targets:: A list of standard Makefile targets
  120. * Standard Directory Variables:: A list of standard directory variables
  121. * Standard Configuration Variables:: Using configuration variables
  122. * config.site:: Using a config.site file
  123. * VPATH Builds:: Parallel build trees
  124. * Two-Part Install:: Installing data and programs separately
  125. * Cross-Compilation:: Building for other architectures
  126. * Renaming:: Renaming programs at install time
  127. * DESTDIR:: Building binary packages with DESTDIR
  128. * Preparing Distributions:: Rolling out tarballs
  129. * Dependency Tracking:: Automatic dependency tracking
  130. * Nested Packages:: The GNU Build Systems can be nested
  131. A Small Hello World
  132. * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
  133. * amhello's configure.ac Setup Explained::
  134. * amhello's Makefile.am Setup Explained::
  135. General ideas
  136. * General Operation:: General operation of Automake
  137. * Strictness:: Standards conformance checking
  138. * Uniform:: The Uniform Naming Scheme
  139. * Length Limitations:: Staying below the command line length limit
  140. * Canonicalization:: How derived variables are named
  141. * User Variables:: Variables reserved for the user
  142. * Auxiliary Programs:: Programs automake might require
  143. Some example packages
  144. * Complete:: A simple example, start to finish
  145. * true:: Building true and false
  146. Scanning @file{configure.ac}, using @command{aclocal}
  147. * Requirements:: Configuration requirements
  148. * Optional:: Other things Automake recognizes
  149. * aclocal Invocation:: Auto-generating aclocal.m4
  150. * Macros:: Autoconf macros supplied with Automake
  151. Auto-generating aclocal.m4
  152. * aclocal Options:: Options supported by aclocal
  153. * Macro Search Path:: How aclocal finds .m4 files
  154. * Extending aclocal:: Writing your own aclocal macros
  155. * Local Macros:: Organizing local macros
  156. * Serials:: Serial lines in Autoconf macros
  157. * Future of aclocal:: aclocal's scheduled death
  158. Autoconf macros supplied with Automake
  159. * Public Macros:: Macros that you can use.
  160. * Private Macros:: Macros that you should not use.
  161. Directories
  162. * Subdirectories:: Building subdirectories recursively
  163. * Conditional Subdirectories:: Conditionally not building directories
  164. * Alternative:: Subdirectories without recursion
  165. * Subpackages:: Nesting packages
  166. Conditional Subdirectories
  167. * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
  168. * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
  169. * Subdirectories with AC_SUBST:: Another way for conditional recursion
  170. * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
  171. Building Programs and Libraries
  172. * A Program:: Building a program
  173. * A Library:: Building a library
  174. * A Shared Library:: Building a Libtool library
  175. * Program and Library Variables:: Variables controlling program and
  176. library builds
  177. * Default _SOURCES:: Default source files
  178. * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
  179. * Program Variables:: Variables used when building a program
  180. * Yacc and Lex:: Yacc and Lex support
  181. * C++ Support:: Compiling C++ sources
  182. * Objective C Support:: Compiling Objective C sources
  183. * Objective C++ Support:: Compiling Objective C++ sources
  184. * Unified Parallel C Support:: Compiling Unified Parallel C sources
  185. * Assembly Support:: Compiling assembly sources
  186. * Fortran 77 Support:: Compiling Fortran 77 sources
  187. * Fortran 9x Support:: Compiling Fortran 9x sources
  188. * Java Support with gcj:: Compiling Java sources using gcj
  189. * Vala Support:: Compiling Vala sources
  190. * Support for Other Languages:: Compiling other languages
  191. * Dependencies:: Automatic dependency tracking
  192. * EXEEXT:: Support for executable extensions
  193. Building a program
  194. * Program Sources:: Defining program sources
  195. * Linking:: Linking with libraries or extra objects
  196. * Conditional Sources:: Handling conditional sources
  197. * Conditional Programs:: Building a program conditionally
  198. Building a Shared Library
  199. * Libtool Concept:: Introducing Libtool
  200. * Libtool Libraries:: Declaring Libtool Libraries
  201. * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
  202. * Conditional Libtool Sources:: Choosing Library Sources Conditionally
  203. * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
  204. * Libtool Modules:: Building Libtool Modules
  205. * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
  206. * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
  207. * Libtool Issues:: Common Issues Related to Libtool's Use
  208. Common Issues Related to Libtool's Use
  209. * Error required file ltmain.sh not found:: The need to run libtoolize
  210. * Objects created both with libtool and without:: Avoid a specific build race
  211. Fortran 77 Support
  212. * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
  213. * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
  214. * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
  215. Mixing Fortran 77 With C and C++
  216. * How the Linker is Chosen:: Automatic linker selection
  217. Fortran 9x Support
  218. * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
  219. Other Derived Objects
  220. * Scripts:: Executable scripts
  221. * Headers:: Header files
  222. * Data:: Architecture-independent data files
  223. * Sources:: Derived sources
  224. Built Sources
  225. * Built Sources Example:: Several ways to handle built sources.
  226. Other GNU Tools
  227. * Emacs Lisp:: Emacs Lisp
  228. * gettext:: Gettext
  229. * Libtool:: Libtool
  230. * Java:: Java bytecode compilation (deprecated)
  231. * Python:: Python
  232. Building documentation
  233. * Texinfo:: Texinfo
  234. * Man Pages:: Man pages
  235. What Gets Installed
  236. * Basics of Installation:: What gets installed where
  237. * The Two Parts of Install:: Installing data and programs separately
  238. * Extending Installation:: Adding your own rules for installation
  239. * Staged Installs:: Installation in a temporary location
  240. * Install Rules for the User:: Useful additional rules
  241. What Goes in a Distribution
  242. * Basics of Distribution:: Files distributed by default
  243. * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
  244. * The dist Hook:: A target for last-minute distribution changes
  245. * Checking the Distribution:: @samp{make distcheck} explained
  246. * The Types of Distributions:: A variety of formats and compression methods
  247. Support for test suites
  248. * Generalities about Testing:: Generic concepts and terminology about testing
  249. * Simple Tests:: Listing test scripts in @code{TESTS}
  250. * Custom Test Drivers:: Writing and using custom test drivers
  251. * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
  252. * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
  253. * Install Tests:: Running tests on installed packages
  254. Simple Tests
  255. * Scripts-based Testsuites:: Automake-specific concepts and terminology
  256. * Serial Test Harness:: Older (and discouraged) serial test harness
  257. * Parallel Test Harness:: Generic concurrent test harness
  258. Using the TAP test protocol
  259. * Introduction to TAP::
  260. * Use TAP with the Automake test harness::
  261. * Incompatibilities with other TAP parsers and drivers::
  262. * Links and external resources on TAP::
  263. Custom Test Drivers
  264. * Overview of Custom Test Drivers Support::
  265. * Declaring Custom Test Drivers::
  266. * API for Custom Test Drivers::
  267. API for Custom Test Drivers
  268. * Command-line arguments for test drivers::
  269. * Log files generation and test results recording::
  270. * Testsuite progress output::
  271. Changing Automake's Behavior
  272. * Options generalities:: Semantics of Automake option
  273. * List of Automake options:: A comprehensive list of Automake options
  274. Miscellaneous Rules
  275. * Tags:: Interfacing to cscope, etags and mkid
  276. * Suffixes:: Handling new file extensions
  277. Conditionals
  278. * Usage of Conditionals:: Declaring conditional content
  279. * Limits of Conditionals:: Enclosing complete statements
  280. Silencing Make
  281. * Make verbosity:: Make is verbose by default
  282. * Tricks For Silencing Make:: Standard and generic ways to silence make
  283. * Automake Silent Rules:: How Automake can help in silencing make
  284. When Automake Isn't Enough
  285. * Extending:: Adding new rules or overriding existing ones.
  286. * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
  287. Frequently Asked Questions about Automake
  288. * CVS:: CVS and generated files
  289. * maintainer-mode:: missing and AM_MAINTAINER_MODE
  290. * Wildcards:: Why doesn't Automake support wildcards?
  291. * Limitations on File Names:: Limitations on source and installed file names
  292. * Errors with distclean:: Files left in build directory after distclean
  293. * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
  294. * Renamed Objects:: Why are object files sometimes renamed?
  295. * Per-Object Flags:: How to simulate per-object flags?
  296. * Multiple Outputs:: Writing rules for tools with many output files
  297. * Hard-Coded Install Paths:: Installing to hard-coded locations
  298. * Debugging Make Rules:: Strategies when things don't work as expected
  299. * Reporting Bugs:: Feedback on bugs and feature requests
  300. Copying This Manual
  301. * GNU Free Documentation License:: License for copying this manual
  302. Indices
  303. * Macro Index:: Index of Autoconf macros
  304. * Variable Index:: Index of Makefile variables
  305. * General Index:: General index
  306. @end detailmenu
  307. @end menu
  308. @end ifnottex
  309. @node Introduction
  310. @chapter Introduction
  311. Automake is a tool for automatically generating @file{Makefile.in}s
  312. from files called @file{Makefile.am}. Each @file{Makefile.am} is
  313. basically a series of @command{make} variable
  314. definitions@footnote{These variables are also called @dfn{make macros}
  315. in Make terminology, however in this manual we reserve the term
  316. @dfn{macro} for Autoconf's macros.}, with rules being thrown in
  317. occasionally. The generated @file{Makefile.in}s are compliant with
  318. the GNU Makefile standards.
  319. @cindex GNU Makefile standards
  320. The GNU Makefile Standards Document
  321. (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
  322. is long, complicated, and subject to change. The goal of Automake is to
  323. remove the burden of Makefile maintenance from the back of the
  324. individual GNU maintainer (and put it on the back of the Automake
  325. maintainers).
  326. The typical Automake input file is simply a series of variable definitions.
  327. Each such file is processed to create a @file{Makefile.in}.
  328. @cindex Constraints of Automake
  329. @cindex Automake constraints
  330. Automake does constrain a project in certain ways; for instance, it
  331. assumes that the project uses Autoconf (@pxref{Top, , Introduction,
  332. autoconf, The Autoconf Manual}), and enforces certain restrictions on
  333. the @file{configure.ac} contents.
  334. @cindex Automake requirements
  335. @cindex Requirements, Automake
  336. Automake requires @command{perl} in order to generate the
  337. @file{Makefile.in}s. However, the distributions created by Automake are
  338. fully GNU standards-compliant, and do not require @command{perl} in order
  339. to be built.
  340. @cindex Bugs, reporting
  341. @cindex Reporting bugs
  342. @cindex E-mail, bug reports
  343. For more information on bug reports, @xref{Reporting Bugs}.
  344. @node Autotools Introduction
  345. @chapter An Introduction to the Autotools
  346. If you are new to Automake, maybe you know that it is part of a set of
  347. tools called @emph{The Autotools}. Maybe you've already delved into a
  348. package full of files named @file{configure}, @file{configure.ac},
  349. @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
  350. some of them claiming to be @emph{generated by} Autoconf or Automake.
  351. But the exact purpose of these files and their relations is probably
  352. fuzzy. The goal of this chapter is to introduce you to this machinery,
  353. to show you how it works and how powerful it is. If you've never
  354. installed or seen such a package, do not worry: this chapter will walk
  355. you through it.
  356. If you need some teaching material, more illustrations, or a less
  357. @command{automake}-centered continuation, some slides for this
  358. introduction are available in Alexandre Duret-Lutz's
  359. @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
  360. Autotools Tutorial}.
  361. This chapter is the written version of the first part of his tutorial.
  362. @menu
  363. * GNU Build System:: Introducing the GNU Build System
  364. * Use Cases:: Use Cases for the GNU Build System
  365. * Why Autotools:: How Autotools Help
  366. * Hello World:: A Small Hello World Package
  367. @end menu
  368. @node GNU Build System
  369. @section Introducing the GNU Build System
  370. @cindex GNU Build System, introduction
  371. It is a truth universally acknowledged, that as a developer in
  372. possession of a new package, you must be in want of a build system.
  373. In the Unix world, such a build system is traditionally achieved using
  374. the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
  375. Manual}). You express the recipe to build your package in a
  376. @file{Makefile}. This file is a set of rules to build the files in
  377. the package. For instance the program @file{prog} may be built by
  378. running the linker on the files @file{main.o}, @file{foo.o}, and
  379. @file{bar.o}; the file @file{main.o} may be built by running the
  380. compiler on @file{main.c}; etc. Each time @command{make} is run, it
  381. reads @file{Makefile}, checks the existence and modification time of
  382. the files mentioned, decides what files need to be built (or rebuilt),
  383. and runs the associated commands.
  384. When a package needs to be built on a different platform than the one
  385. it was developed on, its @file{Makefile} usually needs to be adjusted.
  386. For instance the compiler may have another name or require more
  387. options. In 1991, David J. MacKenzie got tired of customizing
  388. @file{Makefile} for the 20 platforms he had to deal with. Instead, he
  389. handcrafted a little shell script called @file{configure} to
  390. automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
  391. autoconf, The Autoconf Manual}). Compiling his package was now
  392. as simple as running @code{./configure && make}.
  393. @cindex GNU Coding Standards
  394. Today this process has been standardized in the GNU project. The GNU
  395. Coding Standards (@pxref{Managing Releases, The Release Process, ,
  396. standards, The GNU Coding Standards}) explains how each package of the
  397. GNU project should have a @file{configure} script, and the minimal
  398. interface it should have. The @file{Makefile} too should follow some
  399. established conventions. The result? A unified build system that
  400. makes all packages almost indistinguishable by the installer. In its
  401. simplest scenario, all the installer has to do is to unpack the
  402. package, run @code{./configure && make && make install}, and repeat
  403. with the next package to install.
  404. We call this build system the @dfn{GNU Build System}, since it was
  405. grown out of the GNU project. However it is used by a vast number of
  406. other packages: following any existing convention has its advantages.
  407. @cindex Autotools, introduction
  408. The Autotools are tools that will create a GNU Build System for your
  409. package. Autoconf mostly focuses on @file{configure} and Automake on
  410. @file{Makefile}s. It is entirely possible to create a GNU Build
  411. System without the help of these tools. However it is rather
  412. burdensome and error-prone. We will discuss this again after some
  413. illustration of the GNU Build System in action.
  414. @node Use Cases
  415. @section Use Cases for the GNU Build System
  416. @cindex GNU Build System, use cases
  417. @cindex GNU Build System, features
  418. @cindex Features of the GNU Build System
  419. @cindex Use Cases for the GNU Build System
  420. @cindex @file{amhello-1.0.tar.gz}, location
  421. @cindex @file{amhello-1.0.tar.gz}, use cases
  422. In this section we explore several use cases for the GNU Build System.
  423. You can replay all of these examples on the @file{amhello-1.0.tar.gz}
  424. package distributed with Automake. If Automake is installed on your
  425. system, you should find a copy of this file in
  426. @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
  427. @var{prefix} is the installation prefix specified during configuration
  428. (@var{prefix} defaults to @file{/usr/local}, however if Automake was
  429. installed by some GNU/Linux distribution it most likely has been set
  430. to @file{/usr}). If you do not have a copy of Automake installed,
  431. you can find a copy of this file inside the @file{doc/} directory of
  432. the Automake package.
  433. Some of the following use cases present features that are in fact
  434. extensions to the GNU Build System. Read: they are not specified by
  435. the GNU Coding Standards, but they are nonetheless part of the build
  436. system created by the Autotools. To keep things simple, we do not
  437. point out the difference. Our objective is to show you many of the
  438. features that the build system created by the Autotools will offer to
  439. you.
  440. @menu
  441. * Basic Installation:: Common installation procedure
  442. * Standard Targets:: A list of standard Makefile targets
  443. * Standard Directory Variables:: A list of standard directory variables
  444. * Standard Configuration Variables:: Using configuration variables
  445. * config.site:: Using a config.site file
  446. * VPATH Builds:: Parallel build trees
  447. * Two-Part Install:: Installing data and programs separately
  448. * Cross-Compilation:: Building for other architectures
  449. * Renaming:: Renaming programs at install time
  450. * DESTDIR:: Building binary packages with DESTDIR
  451. * Preparing Distributions:: Rolling out tarballs
  452. * Dependency Tracking:: Automatic dependency tracking
  453. * Nested Packages:: The GNU Build Systems can be nested
  454. @end menu
  455. @node Basic Installation
  456. @subsection Basic Installation
  457. @cindex Configuration, basics
  458. @cindex Installation, basics
  459. @cindex GNU Build System, basics
  460. The most common installation procedure looks as follows.
  461. @example
  462. ~ % @kbd{tar zxf amhello-1.0.tar.gz}
  463. ~ % @kbd{cd amhello-1.0}
  464. ~/amhello-1.0 % @kbd{./configure}
  465. @dots{}
  466. config.status: creating Makefile
  467. config.status: creating src/Makefile
  468. @dots{}
  469. ~/amhello-1.0 % @kbd{make}
  470. @dots{}
  471. ~/amhello-1.0 % @kbd{make check}
  472. @dots{}
  473. ~/amhello-1.0 % @kbd{su}
  474. Password:
  475. /home/adl/amhello-1.0 # @kbd{make install}
  476. @dots{}
  477. /home/adl/amhello-1.0 # @kbd{exit}
  478. ~/amhello-1.0 % @kbd{make installcheck}
  479. @dots{}
  480. @end example
  481. @cindex Unpacking
  482. The user first unpacks the package. Here, and in the following
  483. examples, we will use the non-portable @code{tar zxf} command for
  484. simplicity. On a system without GNU @command{tar} installed, this
  485. command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
  486. The user then enters the newly created directory to run the
  487. @file{configure} script. This script probes the system for various
  488. features, and finally creates the @file{Makefile}s. In this toy
  489. example there are only two @file{Makefile}s, but in real-world projects,
  490. there may be many more, usually one @file{Makefile} per directory.
  491. It is now possible to run @code{make}. This will construct all the
  492. programs, libraries, and scripts that need to be constructed for the
  493. package. In our example, this compiles the @file{hello} program.
  494. All files are constructed in place, in the source tree; we will see
  495. later how this can be changed.
  496. @code{make check} causes the package's tests to be run. This step is
  497. not mandatory, but it is often good to make sure the programs that
  498. have been built behave as they should, before you decide to install
  499. them. Our example does not contain any tests, so running @code{make
  500. check} is a no-op.
  501. @cindex su, before @code{make install}
  502. After everything has been built, and maybe tested, it is time to
  503. install it on the system. That means copying the programs,
  504. libraries, header files, scripts, and other data files from the
  505. source directory to their final destination on the system. The
  506. command @code{make install} will do that. However, by default
  507. everything will be installed in subdirectories of @file{/usr/local}:
  508. binaries will go into @file{/usr/local/bin}, libraries will end up in
  509. @file{/usr/local/lib}, etc. This destination is usually not writable
  510. by any user, so we assume that we have to become root before we can
  511. run @code{make install}. In our example, running @code{make install}
  512. will copy the program @file{hello} into @file{/usr/local/bin}
  513. and @file{README} into @file{/usr/local/share/doc/amhello}.
  514. A last and optional step is to run @code{make installcheck}. This
  515. command may run tests on the installed files. @code{make check} tests
  516. the files in the source tree, while @code{make installcheck} tests
  517. their installed copies. The tests run by the latter can be different
  518. from those run by the former. For instance, there are tests that
  519. cannot be run in the source tree. Conversely, some packages are set
  520. up so that @code{make installcheck} will run the very same tests as
  521. @code{make check}, only on different files (non-installed
  522. vs.@: installed). It can make a difference, for instance when the
  523. source tree's layout is different from that of the installation.
  524. Furthermore it may help to diagnose an incomplete installation.
  525. Presently most packages do not have any @code{installcheck} tests
  526. because the existence of @code{installcheck} is little known, and its
  527. usefulness is neglected. Our little toy package is no better: @code{make
  528. installcheck} does nothing.
  529. @node Standard Targets
  530. @subsection Standard @file{Makefile} Targets
  531. So far we have come across four ways to run @command{make} in the GNU
  532. Build System: @code{make}, @code{make check}, @code{make install}, and
  533. @code{make installcheck}. The words @code{check}, @code{install}, and
  534. @code{installcheck}, passed as arguments to @command{make}, are called
  535. @dfn{targets}. @code{make} is a shorthand for @code{make all},
  536. @code{all} being the default target in the GNU Build System.
  537. Here is a list of the most useful targets that the GNU Coding Standards
  538. specify.
  539. @table @code
  540. @item make all
  541. @trindex all
  542. Build programs, libraries, documentation, etc.@: (same as @code{make}).
  543. @item make install
  544. @trindex install
  545. Install what needs to be installed, copying the files from the
  546. package's tree to system-wide directories.
  547. @item make install-strip
  548. @trindex install-strip
  549. Same as @code{make install}, then strip debugging symbols. Some
  550. users like to trade space for useful bug reports@enddots{}
  551. @item make uninstall
  552. @trindex uninstall
  553. The opposite of @code{make install}: erase the installed files.
  554. (This needs to be run from the same build tree that was installed.)
  555. @item make clean
  556. @trindex clean
  557. Erase from the build tree the files built by @code{make all}.
  558. @item make distclean
  559. @trindex distclean
  560. Additionally erase anything @code{./configure} created.
  561. @item make check
  562. @trindex check
  563. Run the test suite, if any.
  564. @item make installcheck
  565. @trindex installcheck
  566. Check the installed programs or libraries, if supported.
  567. @item make dist
  568. @trindex dist
  569. Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
  570. files.
  571. @end table
  572. @node Standard Directory Variables
  573. @subsection Standard Directory Variables
  574. @cindex directory variables
  575. The GNU Coding Standards also specify a hierarchy of variables to
  576. denote installation directories. Some of these are:
  577. @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
  578. @headitem Directory variable @tab Default value
  579. @item @code{prefix} @tab @code{/usr/local}
  580. @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
  581. @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
  582. @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
  583. @item @w{@ @ @ @ @dots{}}
  584. @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
  585. @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
  586. @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
  587. @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
  588. @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
  589. @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
  590. @item @w{@ @ @dots{}}
  591. @end multitable
  592. @c We should provide a complete table somewhere, but not here. The
  593. @c complete list of directory variables it too confusing as-is. It
  594. @c requires some explanations that are too complicated for this
  595. @c introduction. Besides listing directories like localstatedir
  596. @c would make the explanations in ``Two-Part Install'' harder.
  597. Each of these directories has a role which is often obvious from its
  598. name. In a package, any installable file will be installed in one of
  599. these directories. For instance in @code{amhello-1.0}, the program
  600. @file{hello} is to be installed in @var{bindir}, the directory for
  601. binaries. The default value for this directory is
  602. @file{/usr/local/bin}, but the user can supply a different value when
  603. calling @command{configure}. Also the file @file{README} will be
  604. installed into @var{docdir}, which defaults to
  605. @file{/usr/local/share/doc/amhello}.
  606. @opindex --prefix
  607. As a user, if you wish to install a package on your own account, you
  608. could proceed as follows:
  609. @example
  610. ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
  611. @dots{}
  612. ~/amhello-1.0 % @kbd{make}
  613. @dots{}
  614. ~/amhello-1.0 % @kbd{make install}
  615. @dots{}
  616. @end example
  617. This would install @file{~/usr/bin/hello} and
  618. @file{~/usr/share/doc/amhello/README}.
  619. The list of all such directory options is shown by
  620. @code{./configure --help}.
  621. @node Standard Configuration Variables
  622. @subsection Standard Configuration Variables
  623. @cindex configuration variables, overriding
  624. The GNU Coding Standards also define a set of standard configuration
  625. variables used during the build. Here are some:
  626. @table @asis
  627. @item @code{CC}
  628. C compiler command
  629. @item @code{CFLAGS}
  630. C compiler flags
  631. @item @code{CXX}
  632. C++ compiler command
  633. @item @code{CXXFLAGS}
  634. C++ compiler flags
  635. @item @code{LDFLAGS}
  636. linker flags
  637. @item @code{CPPFLAGS}
  638. C/C++ preprocessor flags
  639. @item @dots{}
  640. @end table
  641. @command{configure} usually does a good job at setting appropriate
  642. values for these variables, but there are cases where you may want to
  643. override them. For instance you may have several versions of a
  644. compiler installed and would like to use another one, you may have
  645. header files installed outside the default search path of the
  646. compiler, or even libraries out of the way of the linker.
  647. Here is how one would call @command{configure} to force it to use
  648. @command{gcc-3} as C compiler, use header files from
  649. @file{~/usr/include} when compiling, and libraries from
  650. @file{~/usr/lib} when linking.
  651. @example
  652. ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
  653. CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
  654. @end example
  655. Again, a full list of these variables appears in the output of
  656. @code{./configure --help}.
  657. @node config.site
  658. @subsection Overriding Default Configuration Setting with @file{config.site}
  659. @cindex @file{config.site} example
  660. When installing several packages using the same setup, it can be
  661. convenient to create a file to capture common settings.
  662. If a file named @file{@var{prefix}/share/config.site} exists,
  663. @command{configure} will source it at the beginning of its execution.
  664. Recall the command from the previous section:
  665. @example
  666. ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
  667. CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
  668. @end example
  669. Assuming we are installing many package in @file{~/usr}, and will
  670. always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
  671. @code{LDFLAGS}, we can automate this by creating the following
  672. @file{~/usr/share/config.site} file:
  673. @example
  674. test -z "$CC" && CC=gcc-3
  675. test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
  676. test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
  677. @end example
  678. Now, any time a @file{configure} script is using the @file{~/usr}
  679. prefix, it will execute the above @file{config.site} and define
  680. these three variables.
  681. @example
  682. ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
  683. configure: loading site script /home/adl/usr/share/config.site
  684. @dots{}
  685. @end example
  686. @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
  687. Manual}, for more information about this feature.
  688. @node VPATH Builds
  689. @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
  690. @cindex Parallel build trees
  691. @cindex VPATH builds
  692. @cindex source tree and build tree
  693. @cindex build tree and source tree
  694. @cindex trees, source vs.@: build
  695. The GNU Build System distinguishes two trees: the source tree, and
  696. the build tree.
  697. The source tree is rooted in the directory containing
  698. @file{configure}. It contains all the sources files (those that are
  699. distributed), and may be arranged using several subdirectories.
  700. The build tree is rooted in the directory in which @file{configure}
  701. was run, and is populated with all object files, programs, libraries,
  702. and other derived files built from the sources (and hence not
  703. distributed). The build tree usually has the same subdirectory layout
  704. as the source tree; its subdirectories are created automatically by
  705. the build system.
  706. If @file{configure} is executed in its own directory, the source and
  707. build trees are combined: derived files are constructed in the same
  708. directories as their sources. This was the case in our first
  709. installation example (@pxref{Basic Installation}).
  710. A common request from users is that they want to confine all derived
  711. files to a single directory, to keep their source directories
  712. uncluttered. Here is how we could run @file{configure} to build
  713. everything in a subdirectory called @file{build/}.
  714. @example
  715. ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
  716. ~ % @kbd{cd amhello-1.0}
  717. ~/amhello-1.0 % @kbd{mkdir build && cd build}
  718. ~/amhello-1.0/build % @kbd{../configure}
  719. @dots{}
  720. ~/amhello-1.0/build % @kbd{make}
  721. @dots{}
  722. @end example
  723. These setups, where source and build trees are different, are often
  724. called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
  725. @emph{parallel build} is misleading: the word @emph{parallel} is a
  726. reference to the way the build tree shadows the source tree, it is not
  727. about some concurrency in the way build commands are run. For this
  728. reason we refer to such setups using the name @emph{VPATH builds} in
  729. the following. @emph{VPATH} is the name of the @command{make} feature
  730. used by the @file{Makefile}s to allow these builds (@pxref{General
  731. Search, , @code{VPATH} Search Path for All Prerequisites, make, The
  732. GNU Make Manual}).
  733. @cindex multiple configurations, example
  734. @cindex debug build, example
  735. @cindex optimized build, example
  736. VPATH builds have other interesting uses. One is to build the same
  737. sources with multiple configurations. For instance:
  738. @c Keep in sync with amhello-cflags.sh
  739. @example
  740. ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
  741. ~ % @kbd{cd amhello-1.0}
  742. ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
  743. ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
  744. @dots{}
  745. ~/amhello-1.0/debug % @kbd{make}
  746. @dots{}
  747. ~/amhello-1.0/debug % cd ../optim
  748. ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
  749. @dots{}
  750. ~/amhello-1.0/optim % @kbd{make}
  751. @dots{}
  752. @end example
  753. With network file systems, a similar approach can be used to build the
  754. same sources on different machines. For instance, suppose that the
  755. sources are installed on a directory shared by two hosts: @code{HOST1}
  756. and @code{HOST2}, which may be different platforms.
  757. @example
  758. ~ % @kbd{cd /nfs/src}
  759. /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
  760. @end example
  761. On the first host, you could create a local build directory:
  762. @example
  763. [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
  764. [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
  765. ...
  766. [HOST1] /tmp/amh % @kbd{make && sudo make install}
  767. ...
  768. @end example
  769. @noindent
  770. (Here we assume that the installer has configured @command{sudo} so it
  771. can execute @code{make install} with root privileges; it is more convenient
  772. than using @command{su} like in @ref{Basic Installation}).
  773. On the second host, you would do exactly the same, possibly at
  774. the same time:
  775. @example
  776. [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
  777. [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
  778. ...
  779. [HOST2] /tmp/amh % @kbd{make && sudo make install}
  780. ...
  781. @end example
  782. @cindex read-only source tree
  783. @cindex source tree, read-only
  784. In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
  785. directory from being read-only. In fact VPATH builds are also a means
  786. of building packages from a read-only medium such as a CD-ROM. (The
  787. FSF used to sell CD-ROM with unpacked source code, before the GNU
  788. project grew so big.)
  789. @node Two-Part Install
  790. @subsection Two-Part Installation
  791. In our last example (@pxref{VPATH Builds}), a source tree was shared
  792. by two hosts, but compilation and installation were done separately on
  793. each host.
  794. The GNU Build System also supports networked setups where part of the
  795. installed files should be shared amongst multiple hosts. It does so
  796. by distinguishing architecture-dependent files from
  797. architecture-independent files, and providing two @file{Makefile}
  798. targets to install each of these classes of files.
  799. @trindex install-exec
  800. @trindex install-data
  801. These targets are @code{install-exec} for architecture-dependent files
  802. and @code{install-data} for architecture-independent files.
  803. The command we used up to now, @code{make install}, can be thought of
  804. as a shorthand for @code{make install-exec install-data}.
  805. From the GNU Build System point of view, the distinction between
  806. architecture-dependent files and architecture-independent files is
  807. based exclusively on the directory variable used to specify their
  808. installation destination. In the list of directory variables we
  809. provided earlier (@pxref{Standard Directory Variables}), all the
  810. variables based on @var{exec-prefix} designate architecture-dependent
  811. directories whose files will be installed by @code{make install-exec}.
  812. The others designate architecture-independent directories and will
  813. serve files installed by @code{make install-data}. @xref{The Two Parts
  814. of Install}, for more details.
  815. Here is how we could revisit our two-host installation example,
  816. assuming that (1) we want to install the package directly in
  817. @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
  818. two hosts.
  819. On the first host we would run
  820. @example
  821. [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
  822. [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
  823. ...
  824. [HOST1] /tmp/amh % @kbd{make && sudo make install}
  825. ...
  826. @end example
  827. On the second host, however, we need only install the
  828. architecture-specific files.
  829. @example
  830. [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
  831. [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
  832. ...
  833. [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
  834. ...
  835. @end example
  836. In packages that have installation checks, it would make sense to run
  837. @code{make installcheck} (@pxref{Basic Installation}) to verify that
  838. the package works correctly despite the apparent partial installation.
  839. @node Cross-Compilation
  840. @subsection Cross-Compilation
  841. @cindex cross-compilation
  842. To @dfn{cross-compile} is to build on one platform a binary that will
  843. run on another platform. When speaking of cross-compilation, it is
  844. important to distinguish between the @dfn{build platform} on which
  845. the compilation is performed, and the @dfn{host platform} on which the
  846. resulting executable is expected to run. The following
  847. @command{configure} options are used to specify each of them:
  848. @table @option
  849. @item --build=@var{build}
  850. @opindex --build=@var{build}
  851. The system on which the package is built.
  852. @item --host=@var{host}
  853. @opindex --host=@var{host}
  854. The system where built programs and libraries will run.
  855. @end table
  856. When the @option{--host} is used, @command{configure} will search for
  857. the cross-compiling suite for this platform. Cross-compilation tools
  858. commonly have their target architecture as prefix of their name. For
  859. instance my cross-compiler for MinGW32 has its binaries called
  860. @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
  861. @code{i586-mingw32msvc-as}, etc.
  862. @cindex MinGW cross-compilation example
  863. @cindex cross-compilation example
  864. Here is how we could build @code{amhello-1.0} for
  865. @code{i586-mingw32msvc} on a GNU/Linux PC.
  866. @c Keep in sync with amhello-cross-compile.sh
  867. @smallexample
  868. ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
  869. checking for a BSD-compatible install... /usr/bin/install -c
  870. checking whether build environment is sane... yes
  871. checking for gawk... gawk
  872. checking whether make sets $(MAKE)... yes
  873. checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
  874. checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
  875. checking for C compiler default output file name... a.exe
  876. checking whether the C compiler works... yes
  877. checking whether we are cross compiling... yes
  878. checking for suffix of executables... .exe
  879. checking for suffix of object files... o
  880. checking whether we are using the GNU C compiler... yes
  881. checking whether i586-mingw32msvc-gcc accepts -g... yes
  882. checking for i586-mingw32msvc-gcc option to accept ANSI C...
  883. @dots{}
  884. ~/amhello-1.0 % @kbd{make}
  885. @dots{}
  886. ~/amhello-1.0 % @kbd{cd src; file hello.exe}
  887. hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
  888. @end smallexample
  889. The @option{--host} and @option{--build} options are usually all we
  890. need for cross-compiling. The only exception is if the package being
  891. built is itself a cross-compiler: we need a third option to specify
  892. its target architecture.
  893. @table @option
  894. @item --target=@var{target}
  895. @opindex --target=@var{target}
  896. When building compiler tools: the system for which the tools will
  897. create output.
  898. @end table
  899. For instance when installing GCC, the GNU Compiler Collection, we can
  900. use @option{--target=@/@var{target}} to specify that we want to build
  901. GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
  902. @option{--target}, we can actually cross-compile a cross-compiler;
  903. such a three-way cross-compilation is known as a @dfn{Canadian cross}.
  904. @xref{Specifying Names, , Specifying the System Type, autoconf, The
  905. Autoconf Manual}, for more information about these @command{configure}
  906. options.
  907. @node Renaming
  908. @subsection Renaming Programs at Install Time
  909. @cindex Renaming programs
  910. @cindex Transforming program names
  911. @cindex Programs, renaming during installation
  912. The GNU Build System provides means to automatically rename
  913. executables and manpages before they are installed (@pxref{Man Pages}).
  914. This is especially convenient
  915. when installing a GNU package on a system that already has a
  916. proprietary implementation you do not want to overwrite. For instance,
  917. you may want to install GNU @command{tar} as @command{gtar} so you can
  918. distinguish it from your vendor's @command{tar}.
  919. This can be done using one of these three @command{configure} options.
  920. @table @option
  921. @item --program-prefix=@var{prefix}
  922. @opindex --program-prefix=@var{prefix}
  923. Prepend @var{prefix} to installed program names.
  924. @item --program-suffix=@var{suffix}
  925. @opindex --program-suffix=@var{suffix}
  926. Append @var{suffix} to installed program names.
  927. @item --program-transform-name=@var{program}
  928. @opindex --program-transform-name=@var{program}
  929. Run @code{sed @var{program}} on installed program names.
  930. @end table
  931. The following commands would install @file{hello}
  932. as @file{/usr/local/bin/test-hello}, for instance.
  933. @example
  934. ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
  935. @dots{}
  936. ~/amhello-1.0 % @kbd{make}
  937. @dots{}
  938. ~/amhello-1.0 % @kbd{sudo make install}
  939. @dots{}
  940. @end example
  941. @node DESTDIR
  942. @subsection Building Binary Packages Using DESTDIR
  943. @vindex DESTDIR
  944. The GNU Build System's @code{make install} and @code{make uninstall}
  945. interface does not exactly fit the needs of a system administrator
  946. who has to deploy and upgrade packages on lots of hosts. In other
  947. words, the GNU Build System does not replace a package manager.
  948. Such package managers usually need to know which files have been
  949. installed by a package, so a mere @code{make install} is
  950. inappropriate.
  951. @cindex Staged installation
  952. The @code{DESTDIR} variable can be used to perform a staged
  953. installation. The package should be configured as if it was going to
  954. be installed in its final location (e.g., @code{--prefix /usr}), but
  955. when running @code{make install}, the @code{DESTDIR} should be set to
  956. the absolute name of a directory into which the installation will be
  957. diverted. From this directory it is easy to review which files are
  958. being installed where, and finally copy them to their final location
  959. by some means.
  960. @cindex Binary package
  961. For instance here is how we could create a binary package containing a
  962. snapshot of all the files to be installed.
  963. @c Keep in sync with amhello-binpkg.sh
  964. @example
  965. ~/amhello-1.0 % @kbd{./configure --prefix /usr}
  966. @dots{}
  967. ~/amhello-1.0 % @kbd{make}
  968. @dots{}
  969. ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
  970. @dots{}
  971. ~/amhello-1.0 % @kbd{cd ~/inst}
  972. ~/inst % @kbd{find . -type f -print > ../files.lst}
  973. ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
  974. ./usr/bin/hello
  975. ./usr/share/doc/amhello/README
  976. @end example
  977. After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
  978. uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
  979. instead of @samp{.} as argument for @command{tar} avoids entries for
  980. each subdirectory in the archive: we would not like @command{tar} to
  981. restore the modification time of @file{/}, @file{/usr/}, etc.)
  982. Note that when building packages for several architectures, it might
  983. be convenient to use @code{make install-data} and @code{make
  984. install-exec} (@pxref{Two-Part Install}) to gather
  985. architecture-independent files in a single package.
  986. @xref{Install}, for more information.
  987. @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
  988. @c UNINSTALL counterparts.
  989. @node Preparing Distributions
  990. @subsection Preparing Distributions
  991. @cindex Preparing distributions
  992. @cindex Packages, preparation
  993. @cindex Distributions, preparation
  994. We have already mentioned @code{make dist}. This target collects all
  995. your source files and the necessary parts of the build system to
  996. create a tarball named @file{@var{package}-@var{version}.tar.gz}.
  997. @cindex @code{distcheck} better than @code{dist}
  998. Another, more useful command is @code{make distcheck}. The
  999. @code{distcheck} target constructs
  1000. @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
  1001. but it additionally ensures most of the use cases presented so far
  1002. work:
  1003. @itemize @bullet
  1004. @item
  1005. It attempts a full compilation of the package (@pxref{Basic
  1006. Installation}), unpacking the newly constructed tarball, running
  1007. @code{make}, @code{make check}, @code{make install}, as well as
  1008. @code{make installcheck}, and even @code{make dist},
  1009. @item
  1010. it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
  1011. @item
  1012. it makes sure @code{make clean}, @code{make distclean}, and @code{make
  1013. uninstall} do not omit any file (@pxref{Standard Targets}),
  1014. @item
  1015. and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
  1016. @end itemize
  1017. All of these actions are performed in a temporary directory, so that no
  1018. root privileges are required. Please note that the exact location and the
  1019. exact structure of such a subdirectory (where the extracted sources are
  1020. placed, how the temporary build and install directories are named and how
  1021. deeply they are nested, etc.) is to be considered an implementation detail,
  1022. which can change at any time; so do not rely on it.
  1023. Releasing a package that fails @code{make distcheck} means that one of
  1024. the scenarios we presented will not work and some users will be
  1025. disappointed. Therefore it is a good practice to release a package
  1026. only after a successful @code{make distcheck}. This of course does
  1027. not imply that the package will be flawless, but at least it will
  1028. prevent some of the embarrassing errors you may find in packages
  1029. released by people who have never heard about @code{distcheck} (like
  1030. @code{DESTDIR} not working because of a typo, or a distributed file
  1031. being erased by @code{make clean}, or even @code{VPATH} builds not
  1032. working).
  1033. @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
  1034. @code{make distcheck}. @xref{Checking the Distribution}, for more
  1035. information about @code{distcheck}.
  1036. @node Dependency Tracking
  1037. @subsection Automatic Dependency Tracking
  1038. @cindex Dependency tracking
  1039. Dependency tracking is performed as a side-effect of compilation.
  1040. Each time the build system compiles a source file, it computes its
  1041. list of dependencies (in C these are the header files included by the
  1042. source being compiled). Later, any time @command{make} is run and a
  1043. dependency appears to have changed, the dependent files will be
  1044. rebuilt.
  1045. Automake generates code for automatic dependency tracking by default,
  1046. unless the developer chooses to override it; for more information,
  1047. @pxref{Dependencies}.
  1048. When @command{configure} is executed, you can see it probing each
  1049. compiler for the dependency mechanism it supports (several mechanisms
  1050. can be used):
  1051. @example
  1052. ~/amhello-1.0 % @kbd{./configure --prefix /usr}
  1053. @dots{}
  1054. checking dependency style of gcc... gcc3
  1055. @dots{}
  1056. @end example
  1057. Because dependencies are only computed as a side-effect of the
  1058. compilation, no dependency information exists the first time a package
  1059. is built. This is OK because all the files need to be built anyway:
  1060. @code{make} does not have to decide which files need to be rebuilt.
  1061. In fact, dependency tracking is completely useless for one-time builds
  1062. and there is a @command{configure} option to disable this:
  1063. @table @option
  1064. @item --disable-dependency-tracking
  1065. @opindex --disable-dependency-tracking
  1066. Speed up one-time builds.
  1067. @end table
  1068. Some compilers do not offer any practical way to derive the list of
  1069. dependencies as a side-effect of the compilation, requiring a separate
  1070. run (maybe of another tool) to compute these dependencies. The
  1071. performance penalty implied by these methods is important enough to
  1072. disable them by default. The option @option{--enable-dependency-tracking}
  1073. must be passed to @command{configure} to activate them.
  1074. @table @option
  1075. @item --enable-dependency-tracking
  1076. @opindex --enable-dependency-tracking
  1077. Do not reject slow dependency extractors.
  1078. @end table
  1079. @xref{Dependency Tracking Evolution, , Dependency Tracking Evolution,
  1080. automake-history, Brief History of Automake}, for some discussion about
  1081. the different dependency tracking schemes used by Automake over the years.
  1082. @node Nested Packages
  1083. @subsection Nested Packages
  1084. @cindex Nested packages
  1085. @cindex Packages, nested
  1086. @cindex Subpackages
  1087. Although nesting packages isn't something we would recommend to
  1088. someone who is discovering the Autotools, it is a nice feature worthy
  1089. of mention in this small advertising tour.
  1090. Autoconfiscated packages (that means packages whose build system have
  1091. been created by Autoconf and friends) can be nested to arbitrary
  1092. depth.
  1093. A typical setup is that package A will distribute one of the libraries
  1094. it needs in a subdirectory. This library B is a complete package with
  1095. its own GNU Build System. The @command{configure} script of A will
  1096. run the @command{configure} script of B as part of its execution,
  1097. building and installing A will also build and install B. Generating a
  1098. distribution for A will also include B.
  1099. It is possible to gather several packages like this. GCC is a heavy
  1100. user of this feature. This gives installers a single package to
  1101. configure, build and install, while it allows developers to work on
  1102. subpackages independently.
  1103. When configuring nested packages, the @command{configure} options
  1104. given to the top-level @command{configure} are passed recursively to
  1105. nested @command{configure}s. A package that does not understand an
  1106. option will ignore it, assuming it is meaningful to some other
  1107. package.
  1108. @opindex --help=recursive
  1109. The command @code{configure --help=recursive} can be used to display
  1110. the options supported by all the included packages.
  1111. @xref{Subpackages}, for an example setup.
  1112. @node Why Autotools
  1113. @section How Autotools Help
  1114. @cindex Autotools, purpose
  1115. There are several reasons why you may not want to implement the GNU
  1116. Build System yourself (read: write a @file{configure} script and
  1117. @file{Makefile}s yourself).
  1118. @itemize @bullet
  1119. @item
  1120. As we have seen, the GNU Build System has a lot of
  1121. features (@pxref{Use Cases}).
  1122. Some users may expect features you have not implemented because
  1123. you did not need them.
  1124. @item
  1125. Implementing these features portably is difficult and exhausting.
  1126. Think of writing portable shell scripts, and portable
  1127. @file{Makefile}s, for systems you may not have handy. @xref{Portable
  1128. Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
  1129. convince yourself.
  1130. @item
  1131. You will have to upgrade your setup to follow changes to the GNU
  1132. Coding Standards.
  1133. @end itemize
  1134. The GNU Autotools take all this burden off your back and provide:
  1135. @itemize @bullet
  1136. @item
  1137. Tools to create a portable, complete, and self-contained GNU Build
  1138. System, from simple instructions.
  1139. @emph{Self-contained} meaning the resulting build system does not
  1140. require the GNU Autotools.
  1141. @item
  1142. A central place where fixes and improvements are made:
  1143. a bug-fix for a portability issue will benefit every package.
  1144. @end itemize
  1145. Yet there also exist reasons why you may want NOT to use the
  1146. Autotools@enddots{} For instance you may be already using (or used to)
  1147. another incompatible build system. Autotools will only be useful if
  1148. you do accept the concepts of the GNU Build System. People who have their
  1149. own idea of how a build system should work will feel frustrated by the
  1150. Autotools.
  1151. @node Hello World
  1152. @section A Small Hello World
  1153. @cindex Example Hello World
  1154. @cindex Hello World example
  1155. @cindex @file{amhello-1.0.tar.gz}, creation
  1156. In this section we recreate the @file{amhello-1.0} package from
  1157. scratch. The first subsection shows how to call the Autotools to
  1158. instantiate the GNU Build System, while the second explains the
  1159. meaning of the @file{configure.ac} and @file{Makefile.am} files read
  1160. by the Autotools.
  1161. @anchor{amhello Explained}
  1162. @menu
  1163. * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
  1164. * amhello's configure.ac Setup Explained::
  1165. * amhello's Makefile.am Setup Explained::
  1166. @end menu
  1167. @node Creating amhello
  1168. @subsection Creating @file{amhello-1.0.tar.gz}
  1169. Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
  1170. The package is simple enough so that we will only need to write 5
  1171. files. (You may copy them from the final @file{amhello-1.0.tar.gz}
  1172. that is distributed with Automake if you do not want to write them.)
  1173. Create the following files in an empty directory.
  1174. @itemize @bullet
  1175. @item
  1176. @file{src/main.c} is the source file for the @file{hello} program. We
  1177. store it in the @file{src/} subdirectory, because later, when the package
  1178. evolves, it will ease the addition of a @file{man/} directory for man
  1179. pages, a @file{data/} directory for data files, etc.
  1180. @example
  1181. ~/amhello % @kbd{cat src/main.c}
  1182. #include <config.h>
  1183. #include <stdio.h>
  1184. int
  1185. main (void)
  1186. @{
  1187. puts ("Hello World!");
  1188. puts ("This is " PACKAGE_STRING ".");
  1189. return 0;
  1190. @}
  1191. @end example
  1192. @item
  1193. @file{README} contains some very limited documentation for our little
  1194. package.
  1195. @example
  1196. ~/amhello % @kbd{cat README}
  1197. This is a demonstration package for GNU Automake.
  1198. Type 'info Automake' to read the Automake manual.
  1199. @end example
  1200. @item
  1201. @file{Makefile.am} and @file{src/Makefile.am} contain Automake
  1202. instructions for these two directories.
  1203. @example
  1204. ~/amhello % @kbd{cat src/Makefile.am}
  1205. bin_PROGRAMS = hello
  1206. hello_SOURCES = main.c
  1207. ~/amhello % @kbd{cat Makefile.am}
  1208. SUBDIRS = src
  1209. dist_doc_DATA = README
  1210. @end example
  1211. @item
  1212. Finally, @file{configure.ac} contains Autoconf instructions to
  1213. create the @command{configure} script.
  1214. @example
  1215. ~/amhello % @kbd{cat configure.ac}
  1216. AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
  1217. AM_INIT_AUTOMAKE([-Wall -Werror foreign])
  1218. AC_PROG_CC
  1219. AC_CONFIG_HEADERS([config.h])
  1220. AC_CONFIG_FILES([
  1221. Makefile
  1222. src/Makefile
  1223. ])
  1224. AC_OUTPUT
  1225. @end example
  1226. @end itemize
  1227. @cindex @command{autoreconf}, example
  1228. Once you have these five files, it is time to run the Autotools to
  1229. instantiate the build system. Do this using the @command{autoreconf}
  1230. command as follows:
  1231. @example
  1232. ~/amhello % @kbd{autoreconf --install}
  1233. configure.ac: installing './install-sh'
  1234. configure.ac: installing './missing'
  1235. configure.ac: installing './compile'
  1236. src/Makefile.am: installing './depcomp'
  1237. @end example
  1238. At this point the build system is complete.
  1239. In addition to the three scripts mentioned in its output, you can see
  1240. that @command{autoreconf} created four other files: @file{configure},
  1241. @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
  1242. The latter three files are templates that will be adapted to the
  1243. system by @command{configure} under the names @file{config.h},
  1244. @file{Makefile}, and @file{src/Makefile}. Let's do this:
  1245. @example
  1246. ~/amhello % @kbd{./configure}
  1247. checking for a BSD-compatible install... /usr/bin/install -c
  1248. checking whether build environment is sane... yes
  1249. checking for gawk... no
  1250. checking for mawk... mawk
  1251. checking whether make sets $(MAKE)... yes
  1252. checking for gcc... gcc
  1253. checking for C compiler default output file name... a.out
  1254. checking whether the C compiler works... yes
  1255. checking whether we are cross compiling... no
  1256. checking for suffix of executables...
  1257. checking for suffix of object files... o
  1258. checking whether we are using the GNU C compiler... yes
  1259. checking whether gcc accepts -g... yes
  1260. checking for gcc option to accept ISO C89... none needed
  1261. checking for style of include used by make... GNU
  1262. checking dependency style of gcc... gcc3
  1263. configure: creating ./config.status
  1264. config.status: creating Makefile
  1265. config.status: creating src/Makefile
  1266. config.status: creating config.h
  1267. config.status: executing depfiles commands
  1268. @end example
  1269. @trindex distcheck
  1270. @cindex @code{distcheck} example
  1271. You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
  1272. being created at the end after @command{configure} has probed the
  1273. system. It is now possible to run all the targets we wish
  1274. (@pxref{Standard Targets}). For instance:
  1275. @example
  1276. ~/amhello % @kbd{make}
  1277. @dots{}
  1278. ~/amhello % @kbd{src/hello}
  1279. Hello World!
  1280. This is amhello 1.0.
  1281. ~/amhello % @kbd{make distcheck}
  1282. @dots{}
  1283. =============================================
  1284. amhello-1.0 archives ready for distribution:
  1285. amhello-1.0.tar.gz
  1286. =============================================
  1287. @end example
  1288. Note that running @command{autoreconf} is only needed initially when
  1289. the GNU Build System does not exist. When you later change some
  1290. instructions in a @file{Makefile.am} or @file{configure.ac}, the
  1291. relevant part of the build system will be regenerated automatically
  1292. when you execute @command{make}.
  1293. @command{autoreconf} is a script that calls @command{autoconf},
  1294. @command{automake}, and a bunch of other commands in the right order.
  1295. If you are beginning with these tools, it is not important to figure
  1296. out in which order all of these tools should be invoked and why. However,
  1297. because Autoconf and Automake have separate manuals, the important
  1298. point to understand is that @command{autoconf} is in charge of
  1299. creating @file{configure} from @file{configure.ac}, while
  1300. @command{automake} is in charge of creating @file{Makefile.in}s from
  1301. @file{Makefile.am}s and @file{configure.ac}. This should at least
  1302. direct you to the right manual when seeking answers.
  1303. @node amhello's configure.ac Setup Explained
  1304. @subsection @code{amhello}'s @file{configure.ac} Setup Explained
  1305. @cindex @file{configure.ac}, Hello World
  1306. Let us begin with the contents of @file{configure.ac}.
  1307. @example
  1308. AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
  1309. AM_INIT_AUTOMAKE([-Wall -Werror foreign])
  1310. AC_PROG_CC
  1311. AC_CONFIG_HEADERS([config.h])
  1312. AC_CONFIG_FILES([
  1313. Makefile
  1314. src/Makefile
  1315. ])
  1316. AC_OUTPUT
  1317. @end example
  1318. This file is read by both @command{autoconf} (to create
  1319. @file{configure}) and @command{automake} (to create the various
  1320. @file{Makefile.in}s). It contains a series of M4 macros that will be
  1321. expanded as shell code to finally form the @file{configure} script.
  1322. We will not elaborate on the syntax of this file, because the Autoconf
  1323. manual has a whole section about it (@pxref{Writing Autoconf Input, ,
  1324. Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
  1325. The macros prefixed with @code{AC_} are Autoconf macros, documented
  1326. in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
  1327. Index, autoconf, The Autoconf Manual}). The macros that start with
  1328. @code{AM_} are Automake macros, documented later in this manual
  1329. (@pxref{Macro Index}).
  1330. The first two lines of @file{configure.ac} initialize Autoconf and
  1331. Automake. @code{AC_INIT} takes in as parameters the name of the package,
  1332. its version number, and a contact address for bug-reports about the
  1333. package (this address is output at the end of @code{./configure
  1334. --help}, for instance). When adapting this setup to your own package,
  1335. by all means please do not blindly copy Automake's address: use the
  1336. mailing list of your package, or your own mail address.
  1337. @opindex -Wall
  1338. @opindex -Werror
  1339. @opindex foreign
  1340. The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
  1341. @command{automake} (@pxref{Options}). @option{-Wall} and
  1342. @option{-Werror} ask @command{automake} to turn on all warnings and
  1343. report them as errors. We are speaking of @strong{Automake} warnings
  1344. here, such as dubious instructions in @file{Makefile.am}. This has
  1345. absolutely nothing to do with how the compiler will be called, even
  1346. though it may support options with similar names. Using @option{-Wall
  1347. -Werror} is a safe setting when starting to work on a package: you do
  1348. not want to miss any issues. Later you may decide to relax things a
  1349. bit. The @option{foreign} option tells Automake that this package
  1350. will not follow the GNU Standards. GNU packages should always
  1351. distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
  1352. etc. We do not want @command{automake} to complain about these
  1353. missing files in our small example.
  1354. The @code{AC_PROG_CC} line causes the @command{configure} script to
  1355. search for a C compiler and define the variable @code{CC} with its
  1356. name. The @file{src/Makefile.in} file generated by Automake uses the
  1357. variable @code{CC} to build @file{hello}, so when @command{configure}
  1358. creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
  1359. @code{CC} with the value it has found. If Automake is asked to create
  1360. a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
  1361. not define it, it will suggest you add a call to @code{AC_PROG_CC}.
  1362. The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
  1363. @command{configure} script to create a @file{config.h} file gathering
  1364. @samp{#define}s defined by other macros in @file{configure.ac}. In our
  1365. case, the @code{AC_INIT} macro already defined a few of them. Here
  1366. is an excerpt of @file{config.h} after @command{configure} has run:
  1367. @smallexample
  1368. @dots{}
  1369. /* Define to the address where bug reports for this package should be sent. */
  1370. #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
  1371. /* Define to the full name and version of this package. */
  1372. #define PACKAGE_STRING "amhello 1.0"
  1373. @dots{}
  1374. @end smallexample
  1375. As you probably noticed, @file{src/main.c} includes @file{config.h} so
  1376. it can use @code{PACKAGE_STRING}. In a real-world project,
  1377. @file{config.h} can grow really big, with one @samp{#define} per
  1378. feature probed on the system.
  1379. The @code{AC_CONFIG_FILES} macro declares the list of files that
  1380. @command{configure} should create from their @file{*.in} templates.
  1381. Automake also scans this list to find the @file{Makefile.am} files it must
  1382. process. (This is important to remember: when adding a new directory
  1383. to your project, you should add its @file{Makefile} to this list,
  1384. otherwise Automake will never process the new @file{Makefile.am} you
  1385. wrote in that directory.)
  1386. Finally, the @code{AC_OUTPUT} line is a closing command that actually
  1387. produces the part of the script in charge of creating the files
  1388. registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
  1389. @cindex @command{autoscan}
  1390. When starting a new project, we suggest you start with such a simple
  1391. @file{configure.ac}, and gradually add the other tests it requires.
  1392. The command @command{autoscan} can also suggest a few of the tests
  1393. your package may need (@pxref{autoscan Invocation, , Using
  1394. @command{autoscan} to Create @file{configure.ac}, autoconf, The
  1395. Autoconf Manual}).
  1396. @node amhello's Makefile.am Setup Explained
  1397. @subsection @code{amhello}'s @file{Makefile.am} Setup Explained
  1398. @cindex @file{Makefile.am}, Hello World
  1399. We now turn to @file{src/Makefile.am}. This file contains
  1400. Automake instructions to build and install @file{hello}.
  1401. @example
  1402. bin_PROGRAMS = hello
  1403. hello_SOURCES = main.c
  1404. @end example
  1405. A @file{Makefile.am} has the same syntax as an ordinary
  1406. @file{Makefile}. When @command{automake} processes a
  1407. @file{Makefile.am} it copies the entire file into the output
  1408. @file{Makefile.in} (that will be later turned into @file{Makefile} by
  1409. @command{configure}) but will react to certain variable definitions
  1410. by generating some build rules and other variables.
  1411. Often @file{Makefile.am}s contain only a list of variable definitions as
  1412. above, but they can also contain other variable and rule definitions that
  1413. @command{automake} will pass along without interpretation.
  1414. Variables that end with @code{_PROGRAMS} are special variables
  1415. that list programs that the resulting @file{Makefile} should build.
  1416. In Automake speak, this @code{_PROGRAMS} suffix is called a
  1417. @dfn{primary}; Automake recognizes other primaries such as
  1418. @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
  1419. to different types of files.
  1420. The @samp{bin} part of the @code{bin_PROGRAMS} tells
  1421. @command{automake} that the resulting programs should be installed in
  1422. @var{bindir}. Recall that the GNU Build System uses a set of variables
  1423. to denote destination directories and allow users to customize these
  1424. locations (@pxref{Standard Directory Variables}). Any such directory
  1425. variable can be put in front of a primary (omitting the @code{dir}
  1426. suffix) to tell @command{automake} where to install the listed files.
  1427. Programs need to be built from source files, so for each program
  1428. @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
  1429. @command{automake} will look for another variable named
  1430. @code{@var{prog}_SOURCES} listing its source files. There may be more
  1431. than one source file: they will all be compiled and linked together.
  1432. Automake also knows that source files need to be distributed when
  1433. creating a tarball (unlike built programs). So a side-effect of this
  1434. @code{hello_SOURCES} declaration is that @file{main.c} will be
  1435. part of the tarball created by @code{make dist}.
  1436. Finally here are some explanations regarding the top-level
  1437. @file{Makefile.am}.
  1438. @example
  1439. SUBDIRS = src
  1440. dist_doc_DATA = README
  1441. @end example
  1442. @code{SUBDIRS} is a special variable listing all directories that
  1443. @command{make} should recurse into before processing the current
  1444. directory. So this line is responsible for @command{make} building
  1445. @file{src/hello} even though we run it from the top-level. This line
  1446. also causes @code{make install} to install @file{src/hello} before
  1447. installing @file{README} (not that this order matters).
  1448. The line @code{dist_doc_DATA = README} causes @file{README} to be
  1449. distributed and installed in @var{docdir}. Files listed with the
  1450. @code{_DATA} primary are not automatically part of the tarball built
  1451. with @code{make dist}, so we add the @code{dist_} prefix so they get
  1452. distributed. However, for @file{README} it would not have been
  1453. necessary: @command{automake} automatically distributes any
  1454. @file{README} file it encounters (the list of other files
  1455. automatically distributed is presented by @code{automake --help}).
  1456. The only important effect of this second line is therefore to install
  1457. @file{README} during @code{make install}.
  1458. One thing not covered in this example is accessing the installation
  1459. directory values (@pxref{Standard Directory Variables}) from your
  1460. program code, that is, converting them into defined macros. For this,
  1461. @pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
  1462. @node Generalities
  1463. @chapter General ideas
  1464. The following sections cover a few basic ideas that will help you
  1465. understand how Automake works.
  1466. @menu
  1467. * General Operation:: General operation of Automake
  1468. * Strictness:: Standards conformance checking
  1469. * Uniform:: The Uniform Naming Scheme
  1470. * Length Limitations:: Staying below the command line length limit
  1471. * Canonicalization:: How derived variables are named
  1472. * User Variables:: Variables reserved for the user
  1473. * Auxiliary Programs:: Programs automake might require
  1474. @end menu
  1475. @node General Operation
  1476. @section General Operation
  1477. Automake works by reading a @file{Makefile.am} and generating a
  1478. @file{Makefile.in}. Certain variables and rules defined in the
  1479. @file{Makefile.am} instruct Automake to generate more specialized code;
  1480. for instance, a @code{bin_PROGRAMS} variable definition will cause rules
  1481. for compiling and linking programs to be generated.
  1482. @cindex Non-standard targets
  1483. @cindex @code{git-dist}, non-standard example
  1484. @trindex git-dist
  1485. The variable definitions and rules in the @file{Makefile.am} are
  1486. copied mostly verbatim into the generated file, with all variable
  1487. definitions preceding all rules. This allows you to add almost
  1488. arbitrary code into the generated @file{Makefile.in}. For instance,
  1489. the Automake distribution includes a non-standard rule for the
  1490. @code{git-dist} target, which the Automake maintainer uses to make
  1491. distributions from the source control system.
  1492. @cindex GNU make extensions
  1493. Note that most GNU make extensions are not recognized by Automake. Using
  1494. such extensions in a @file{Makefile.am} will lead to errors or confusing
  1495. behavior.
  1496. @cindex Append operator
  1497. @cmindex +=
  1498. A special exception is that the GNU make append operator, @samp{+=}, is
  1499. supported. This operator appends its right hand argument to the variable
  1500. specified on the left. Automake will translate the operator into
  1501. an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
  1502. Automake tries to keep comments grouped with any adjoining rules or
  1503. variable definitions.
  1504. @cindex Limitations of automake parser
  1505. @cindex Automake parser, limitations of
  1506. @cindex indentation in Makefile.am
  1507. Generally, Automake is not particularly smart in the parsing of unusual
  1508. Makefile constructs, so you're advised to avoid fancy constructs or
  1509. ``creative'' use of whitespace.
  1510. @c Keep this in sync with doc-parsing-buglets-tabs.sh
  1511. For example, @key{TAB} characters cannot be used between a target name
  1512. and the following ``@code{:}'' character, and variable assignments
  1513. shouldn't be indented with @key{TAB} characters.
  1514. @c Keep this in sync with doc-parsing-buglets-colneq-subst.sh
  1515. Also, using more complex macro in target names can cause trouble:
  1516. @example
  1517. % @kbd{cat Makefile.am}
  1518. $(FOO:=x): bar
  1519. % @kbd{automake}
  1520. Makefile.am:1: bad characters in variable name '$(FOO'
  1521. Makefile.am:1: ':='-style assignments are not portable
  1522. @end example
  1523. @cindex Make targets, overriding
  1524. @cindex Make rules, overriding
  1525. @cindex Overriding make rules
  1526. @cindex Overriding make targets
  1527. A rule defined in @file{Makefile.am} generally overrides any such
  1528. rule of a similar name that would be automatically generated by
  1529. @command{automake}. Although this is a supported feature, it is generally
  1530. best to avoid making use of it, as sometimes the generated rules are
  1531. very particular.
  1532. @cindex Variables, overriding
  1533. @cindex Overriding make variables
  1534. Similarly, a variable defined in @file{Makefile.am} or
  1535. @code{AC_SUBST}ed from @file{configure.ac} will override any
  1536. definition of the variable that @command{automake} would ordinarily
  1537. create. This feature is more often useful than the ability to
  1538. override a rule. Be warned that many of the variables generated by
  1539. @command{automake} are considered to be for internal use only, and their
  1540. names might change in future releases.
  1541. @cindex Recursive operation of Automake
  1542. @cindex Automake, recursive operation
  1543. @cindex Example of recursive operation
  1544. When examining a variable definition, Automake will recursively examine
  1545. variables referenced in the definition. For example, if Automake is
  1546. looking at the content of @code{foo_SOURCES} in this snippet
  1547. @c Keep in sync with interp.sh
  1548. @example
  1549. xs = a.c b.c
  1550. foo_SOURCES = c.c $(xs)
  1551. @end example
  1552. it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
  1553. contents of @code{foo_SOURCES}.
  1554. @cindex @code{##} (special Automake comment)
  1555. @cindex Special Automake comment
  1556. @cindex Comment, special to Automake
  1557. Automake also allows a form of comment that is @emph{not} copied into
  1558. the output; all lines beginning with @samp{##} (leading spaces allowed)
  1559. are completely ignored by Automake.
  1560. It is customary to make the first line of @file{Makefile.am} read:
  1561. @cindex Makefile.am, first line
  1562. @cindex First line of Makefile.am
  1563. @example
  1564. ## Process this file with automake to produce Makefile.in
  1565. @end example
  1566. @c FIXME document customary ordering of Makefile.am here!
  1567. @node Strictness
  1568. @section Strictness
  1569. @cindex Non-GNU packages
  1570. While Automake is intended to be used by maintainers of GNU packages, it
  1571. does make some effort to accommodate those who wish to use it, but do
  1572. not want to use all the GNU conventions.
  1573. @cindex Strictness, defined
  1574. @cindex Strictness, @option{foreign}
  1575. @cindex @option{foreign} strictness
  1576. @cindex Strictness, @option{gnu}
  1577. @cindex @option{gnu} strictness
  1578. @cindex Strictness, @option{gnits}
  1579. @cindex @option{gnits} strictness
  1580. To this end, Automake supports three levels of @dfn{strictness}---the
  1581. strictness indicating how stringently Automake should check standards
  1582. conformance.
  1583. The valid strictness levels are:
  1584. @table @option
  1585. @item foreign
  1586. Automake will check for only those things that are absolutely
  1587. required for proper operations. For instance, whereas GNU standards
  1588. dictate the existence of a @file{NEWS} file, it will not be required in
  1589. this mode. This strictness will also turn off some warnings by default
  1590. (among them, portability warnings).
  1591. The name comes from the fact that Automake is intended to be
  1592. used for GNU programs; these relaxed rules are not the standard mode of
  1593. operation.
  1594. @item gnu
  1595. Automake will check---as much as possible---for compliance to the GNU
  1596. standards for packages. This is the default.
  1597. @item gnits
  1598. Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
  1599. standards}. These are based on the GNU standards, but are even more
  1600. detailed. Unless you are a Gnits standards contributor, it is
  1601. recommended that you avoid this option until such time as the Gnits
  1602. standard is actually published (which may never happen).
  1603. @end table
  1604. @xref{Gnits}, for more information on the precise implications of the
  1605. strictness level.
  1606. @node Uniform
  1607. @section The Uniform Naming Scheme
  1608. @cindex Uniform naming scheme
  1609. Automake variables generally follow a @dfn{uniform naming scheme} that
  1610. makes it easy to decide how programs (and other derived objects) are
  1611. built, and how they are installed. This scheme also supports
  1612. @command{configure} time determination of what should be built.
  1613. @cindex @code{_PROGRAMS} primary variable
  1614. @cindex @code{PROGRAMS} primary variable
  1615. @cindex Primary variable, @code{PROGRAMS}
  1616. @cindex Primary variable, defined
  1617. @vindex _PROGRAMS
  1618. At @command{make} time, certain variables are used to determine which
  1619. objects are to be built. The variable names are made of several pieces
  1620. that are concatenated together.
  1621. The piece that tells @command{automake} what is being built is commonly called
  1622. the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
  1623. list of programs that are to be compiled and linked.
  1624. @vindex PROGRAMS
  1625. @cindex @code{pkgdatadir}, defined
  1626. @cindex @code{pkgincludedir}, defined
  1627. @cindex @code{pkglibdir}, defined
  1628. @cindex @code{pkglibexecdir}, defined
  1629. @vindex pkgdatadir
  1630. @vindex pkgincludedir
  1631. @vindex pkglibdir
  1632. @vindex pkglibexecdir
  1633. @cindex @code{PACKAGE}, directory
  1634. A different set of names is used to decide where the built objects
  1635. should be installed. These names are prefixes to the primary, and they
  1636. indicate which standard directory should be used as the installation
  1637. directory. The standard directory names are given in the GNU standards
  1638. (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
  1639. Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
  1640. @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
  1641. non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
  1642. @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
  1643. @cindex @code{EXTRA_}, prepending
  1644. For each primary, there is one additional variable named by prepending
  1645. @samp{EXTRA_} to the primary name. This variable is used to list
  1646. objects that may or may not be built, depending on what
  1647. @command{configure} decides. This variable is required because Automake
  1648. must statically know the entire list of objects that may be built in
  1649. order to generate a @file{Makefile.in} that will work in all cases.
  1650. @cindex @code{EXTRA_PROGRAMS}, defined
  1651. @cindex Example, @code{EXTRA_PROGRAMS}
  1652. @cindex @command{cpio} example
  1653. For instance, @command{cpio} decides at configure time which programs
  1654. should be built. Some of the programs are installed in @code{bindir},
  1655. and some are installed in @code{sbindir}:
  1656. @example
  1657. EXTRA_PROGRAMS = mt rmt
  1658. bin_PROGRAMS = cpio pax
  1659. sbin_PROGRAMS = $(MORE_PROGRAMS)
  1660. @end example
  1661. Defining a primary without a prefix as a variable, e.g.,
  1662. @samp{PROGRAMS}, is an error.
  1663. Note that the common @samp{dir} suffix is left off when constructing the
  1664. variable names; thus one writes @samp{bin_PROGRAMS} and not
  1665. @samp{bindir_PROGRAMS}.
  1666. Not every sort of object can be installed in every directory. Automake
  1667. will flag those attempts it finds in error (but see below how to override
  1668. the check if you really need to).
  1669. Automake will also diagnose obvious misspellings in directory names.
  1670. @cindex Extending list of installation directories
  1671. @cindex Installation directories, extending list
  1672. Sometimes the standard directories---even as augmented by
  1673. Automake---are not enough. In particular it is sometimes useful, for
  1674. clarity, to install objects in a subdirectory of some predefined
  1675. directory. To this end, Automake allows you to extend the list of
  1676. possible installation directories. A given prefix (e.g., @samp{zar})
  1677. is valid if a variable of the same name with @samp{dir} appended is
  1678. defined (e.g., @samp{zardir}).
  1679. For instance, the following snippet will install @file{file.xml} into
  1680. @samp{$(datadir)/xml}.
  1681. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  1682. @example
  1683. xmldir = $(datadir)/xml
  1684. xml_DATA = file.xml
  1685. @end example
  1686. This feature can also be used to override the sanity checks Automake
  1687. performs to diagnose suspicious directory/primary couples (in the
  1688. unlikely case these checks are undesirable, and you really know what
  1689. you're doing). For example, Automake would error out on this input:
  1690. @c Should be tested in primary-prefix-invalid-couples.sh
  1691. @example
  1692. # Forbidden directory combinations, automake will error out on this.
  1693. pkglib_PROGRAMS = foo
  1694. doc_LIBRARIES = libquux.a
  1695. @end example
  1696. @noindent
  1697. but it will succeed with this:
  1698. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  1699. @example
  1700. # Work around forbidden directory combinations. Do not use this
  1701. # without a very good reason!
  1702. my_execbindir = $(pkglibdir)
  1703. my_doclibdir = $(docdir)
  1704. my_execbin_PROGRAMS = foo
  1705. my_doclib_LIBRARIES = libquux.a
  1706. @end example
  1707. The @samp{exec} substring of the @samp{my_execbindir} variable lets
  1708. the files be installed at the right time (@pxref{The Two Parts of
  1709. Install}).
  1710. @cindex @samp{noinst_} primary prefix, definition
  1711. @vindex noinst_
  1712. The special prefix @samp{noinst_} indicates that the objects in question
  1713. should be built but not installed at all. This is usually used for
  1714. objects required to build the rest of your package, for instance static
  1715. libraries (@pxref{A Library}), or helper scripts.
  1716. @cindex @samp{check_} primary prefix, definition
  1717. @vindex check_
  1718. The special prefix @samp{check_} indicates that the objects in question
  1719. should not be built until the @samp{make check} command is run. Those
  1720. objects are not installed either.
  1721. The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
  1722. @samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
  1723. @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
  1724. @samp{TEXINFOS}.
  1725. @vindex PROGRAMS
  1726. @vindex LIBRARIES
  1727. @vindex LTLIBRARIES
  1728. @vindex LISP
  1729. @vindex PYTHON
  1730. @vindex JAVA
  1731. @vindex SCRIPTS
  1732. @vindex DATA
  1733. @vindex HEADERS
  1734. @vindex MANS
  1735. @vindex TEXINFOS
  1736. Some primaries also allow additional prefixes that control other
  1737. aspects of @command{automake}'s behavior. The currently defined prefixes
  1738. are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
  1739. These prefixes are explained later (@pxref{Program and Library Variables})
  1740. (@pxref{Man Pages}).
  1741. @node Length Limitations
  1742. @section Staying below the command line length limit
  1743. @cindex command line length limit
  1744. @cindex ARG_MAX
  1745. Traditionally, most unix-like systems have a length limitation for the
  1746. command line arguments and environment contents when creating new
  1747. processes (see for example
  1748. @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
  1749. overview on this issue),
  1750. which of course also applies to commands spawned by @command{make}.
  1751. POSIX requires this limit to be at least 4096 bytes, and most modern
  1752. systems have quite high limits (or are unlimited).
  1753. In order to create portable Makefiles that do not trip over these
  1754. limits, it is necessary to keep the length of file lists bounded.
  1755. Unfortunately, it is not possible to do so fully transparently within
  1756. Automake, so your help may be needed. Typically, you can split long
  1757. file lists manually and use different installation directory names for
  1758. each list. For example,
  1759. @example
  1760. data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N}
  1761. @end example
  1762. @noindent
  1763. may also be written as
  1764. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  1765. @example
  1766. data_DATA = file1 @dots{} file@var{N}
  1767. data2dir = $(datadir)
  1768. data2_DATA = file@var{N+1} @dots{} file@var{2N}
  1769. @end example
  1770. @noindent
  1771. and will cause Automake to treat the two lists separately during
  1772. @code{make install}. See @ref{The Two Parts of Install} for choosing
  1773. directory names that will keep the ordering of the two parts of
  1774. installation Note that @code{make dist} may still only work on a host
  1775. with a higher length limit in this example.
  1776. Automake itself employs a couple of strategies to avoid long command
  1777. lines. For example, when @samp{$@{srcdir@}/} is prepended to file
  1778. names, as can happen with above @code{$(data_DATA)} lists, it limits
  1779. the amount of arguments passed to external commands.
  1780. Unfortunately, some system's @command{make} commands may prepend
  1781. @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
  1782. source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
  1783. Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
  1784. may have to switch to use GNU Make, or refrain from using VPATH builds,
  1785. in order to stay below the length limit.
  1786. For libraries and programs built from many sources, convenience archives
  1787. may be used as intermediates in order to limit the object list length
  1788. (@pxref{Libtool Convenience Libraries}).
  1789. @node Canonicalization
  1790. @section How derived variables are named
  1791. @cindex canonicalizing Automake variables
  1792. Sometimes a Makefile variable name is derived from some text the
  1793. maintainer supplies. For instance, a program name listed in
  1794. @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
  1795. variable. In cases like this, Automake canonicalizes the text, so that
  1796. program names and the like do not have to follow Makefile variable naming
  1797. rules. All characters in the name except for letters, numbers, the
  1798. strudel (@@), and the underscore are turned into underscores when making
  1799. variable references.
  1800. For example, if your program is named @file{sniff-glue}, the derived
  1801. variable name would be @samp{sniff_glue_SOURCES}, not
  1802. @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
  1803. @file{libmumble++.a} should be listed in the
  1804. @samp{libmumble___a_SOURCES} variable.
  1805. The strudel is an addition, to make the use of Autoconf substitutions in
  1806. variable names less obfuscating.
  1807. @node User Variables
  1808. @section Variables reserved for the user
  1809. @cindex variables, reserved for the user
  1810. @cindex user variables
  1811. Some @file{Makefile} variables are reserved by the GNU Coding Standards
  1812. for the use of the ``user''---the person building the package. For
  1813. instance, @code{CFLAGS} is one such variable.
  1814. Sometimes package developers are tempted to set user variables such as
  1815. @code{CFLAGS} because it appears to make their job easier. However,
  1816. the package itself should never set a user variable, particularly not
  1817. to include switches that are required for proper compilation of the
  1818. package. Since these variables are documented as being for the
  1819. package builder, that person rightfully expects to be able to override
  1820. any of these variables at build time.
  1821. To get around this problem, Automake introduces an automake-specific
  1822. shadow variable for each user flag variable. (Shadow variables are
  1823. not introduced for variables like @code{CC}, where they would make no
  1824. sense.) The shadow variable is named by prepending @samp{AM_} to the
  1825. user variable's name. For instance, the shadow variable for
  1826. @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
  1827. the author(s) of the @file{Makefile.am} and @file{configure.ac}
  1828. files---may adjust these shadow variables however necessary.
  1829. @xref{Flag Variables Ordering}, for more discussion about these
  1830. variables and how they interact with per-target variables.
  1831. @node Auxiliary Programs
  1832. @section Programs automake might require
  1833. @cindex Programs, auxiliary
  1834. @cindex Auxiliary programs
  1835. Automake sometimes requires helper programs so that the generated
  1836. @file{Makefile} can do its work properly. There are a fairly large
  1837. number of them, and we list them here.
  1838. Although all of these files are distributed and installed with
  1839. Automake, a couple of them are maintained separately. The Automake
  1840. copies are updated before each release, but we mention the original
  1841. source in case you need more recent versions.
  1842. @table @code
  1843. @item ar-lib
  1844. This is a wrapper primarily for the Microsoft lib archiver, to make
  1845. it more POSIX-like.
  1846. @item compile
  1847. This is a wrapper for compilers that do not accept options @option{-c}
  1848. and @option{-o} at the same time. It is only used when absolutely
  1849. required. Such compilers are rare, with the Microsoft C/C++ Compiler
  1850. as the most notable exception. This wrapper also makes the following
  1851. common options available for that compiler, while performing file name
  1852. translation where needed: @option{-I}, @option{-L}, @option{-l},
  1853. @option{-Wl,} and @option{-Xlinker}.
  1854. @item config.guess
  1855. @itemx config.sub
  1856. These two programs compute the canonical triplets for the given build,
  1857. host, or target architecture. These programs are updated regularly to
  1858. support new architectures and fix probes broken by changes in new
  1859. kernel versions. Each new release of Automake comes with up-to-date
  1860. copies of these programs. If your copy of Automake is getting old,
  1861. you are encouraged to fetch the latest versions of these files from
  1862. @url{http://savannah.gnu.org/git/?group=config} before making a
  1863. release.
  1864. @item depcomp
  1865. This program understands how to run a compiler so that it will
  1866. generate not only the desired output but also dependency information
  1867. that is then used by the automatic dependency tracking feature
  1868. (@pxref{Dependencies}).
  1869. @item install-sh
  1870. This is a replacement for the @command{install} program that works on
  1871. platforms where @command{install} is unavailable or unusable.
  1872. @item mdate-sh
  1873. This script is used to generate a @file{version.texi} file. It examines
  1874. a file and prints some date information about it.
  1875. @item missing
  1876. This wraps a number of programs that are typically only required by
  1877. maintainers. If the program in question doesn't exist, or seems to old,
  1878. @command{missing} will print an informative warning before failing out,
  1879. to provide the user with more context and information.
  1880. @item mkinstalldirs
  1881. This script used to be a wrapper around @samp{mkdir -p}, which is not
  1882. portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
  1883. finds that @samp{mkdir -p} does not work, this makes one less script to
  1884. distribute.
  1885. For backward compatibility @file{mkinstalldirs} is still used and
  1886. distributed when @command{automake} finds it in a package. But it is no
  1887. longer installed automatically, and it should be safe to remove it.
  1888. @item py-compile
  1889. This is used to byte-compile Python scripts.
  1890. @item test-driver
  1891. This implements the default test driver offered by the parallel
  1892. testsuite harness.
  1893. @item texinfo.tex
  1894. Not a program, this file is required for @samp{make dvi}, @samp{make
  1895. ps} and @samp{make pdf} to work when Texinfo sources are in the
  1896. package. The latest version can be downloaded from
  1897. @url{http://www.gnu.org/software/texinfo/}.
  1898. @item ylwrap
  1899. This program wraps @command{lex} and @command{yacc} to rename their
  1900. output files. It also ensures that, for instance, multiple
  1901. @command{yacc} instances can be invoked in a single directory in
  1902. parallel.
  1903. @end table
  1904. @node Examples
  1905. @chapter Some example packages
  1906. This section contains two small examples.
  1907. The first example (@pxref{Complete}) assumes you have an existing
  1908. project already using Autoconf, with handcrafted @file{Makefile}s, and
  1909. that you want to convert it to using Automake. If you are discovering
  1910. both tools, it is probably better that you look at the Hello World
  1911. example presented earlier (@pxref{Hello World}).
  1912. The second example (@pxref{true}) shows how two programs can be built
  1913. from the same file, using different compilation parameters. It
  1914. contains some technical digressions that are probably best skipped on
  1915. first read.
  1916. @menu
  1917. * Complete:: A simple example, start to finish
  1918. * true:: Building true and false
  1919. @end menu
  1920. @node Complete
  1921. @section A simple example, start to finish
  1922. @cindex Complete example
  1923. Let's suppose you just finished writing @code{zardoz}, a program to make
  1924. your head float from vortex to vortex. You've been using Autoconf to
  1925. provide a portability framework, but your @file{Makefile.in}s have been
  1926. ad-hoc. You want to make them bulletproof, so you turn to Automake.
  1927. @cindex @code{AM_INIT_AUTOMAKE}, example use
  1928. The first step is to update your @file{configure.ac} to include the
  1929. commands that @command{automake} needs. The way to do this is to add an
  1930. @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
  1931. @example
  1932. AC_INIT([zardoz], [1.0])
  1933. AM_INIT_AUTOMAKE
  1934. @dots{}
  1935. @end example
  1936. Since your program doesn't have any complicating factors (e.g., it
  1937. doesn't use @code{gettext}, it doesn't want to build a shared library),
  1938. you're done with this part. That was easy!
  1939. @cindex @command{aclocal} program, introduction
  1940. @cindex @file{aclocal.m4}, preexisting
  1941. @cindex @file{acinclude.m4}, defined
  1942. Now you must regenerate @file{configure}. But to do that, you'll need
  1943. to tell @command{autoconf} how to find the new macro you've used. The
  1944. easiest way to do this is to use the @command{aclocal} program to
  1945. generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
  1946. already have an @file{aclocal.m4}, because you had to write some hairy
  1947. macros for your program. The @command{aclocal} program lets you put
  1948. your own macros into @file{acinclude.m4}, so simply rename and then
  1949. run:
  1950. @example
  1951. mv aclocal.m4 acinclude.m4
  1952. aclocal
  1953. autoconf
  1954. @end example
  1955. @cindex @command{zardoz} example
  1956. Now it is time to write your @file{Makefile.am} for @code{zardoz}.
  1957. Since @code{zardoz} is a user program, you want to install it where the
  1958. rest of the user programs go: @code{bindir}. Additionally,
  1959. @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
  1960. script uses @code{AC_REPLACE_FUNCS}, so you need to link against
  1961. @samp{$(LIBOBJS)}. So here's what you'd write:
  1962. @example
  1963. bin_PROGRAMS = zardoz
  1964. zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
  1965. zardoz_LDADD = $(LIBOBJS)
  1966. info_TEXINFOS = zardoz.texi
  1967. @end example
  1968. Now you can run @samp{automake --add-missing} to generate your
  1969. @file{Makefile.in} and grab any auxiliary files you might need, and
  1970. you're done!
  1971. @node true
  1972. @section Building true and false
  1973. @cindex Example, @command{false} and @command{true}
  1974. @cindex @command{false} Example
  1975. @cindex @command{true} Example
  1976. Here is another, trickier example. It shows how to generate two
  1977. programs (@code{true} and @code{false}) from the same source file
  1978. (@file{true.c}). The difficult part is that each compilation of
  1979. @file{true.c} requires different @code{cpp} flags.
  1980. @example
  1981. bin_PROGRAMS = true false
  1982. false_SOURCES =
  1983. false_LDADD = false.o
  1984. true.o: true.c
  1985. $(COMPILE) -DEXIT_CODE=0 -c true.c
  1986. false.o: true.c
  1987. $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
  1988. @end example
  1989. Note that there is no @code{true_SOURCES} definition. Automake will
  1990. implicitly assume that there is a source file named @file{true.c}
  1991. (@pxref{Default _SOURCES}), and
  1992. define rules to compile @file{true.o} and link @file{true}. The
  1993. @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
  1994. will override the Automake generated rule to build @file{true.o}.
  1995. @code{false_SOURCES} is defined to be empty---that way no implicit value
  1996. is substituted. Because we have not listed the source of
  1997. @file{false}, we have to tell Automake how to link the program. This is
  1998. the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
  1999. variable, holding the dependencies of the @file{false} target will be
  2000. automatically generated by Automake from the content of
  2001. @code{false_LDADD}.
  2002. The above rules won't work if your compiler doesn't accept both
  2003. @option{-c} and @option{-o}. The simplest fix for this is to introduce a
  2004. bogus dependency (to avoid problems with a parallel @command{make}):
  2005. @example
  2006. true.o: true.c false.o
  2007. $(COMPILE) -DEXIT_CODE=0 -c true.c
  2008. false.o: true.c
  2009. $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
  2010. @end example
  2011. As it turns out, there is also a much easier way to do this same task.
  2012. Some of the above technique is useful enough that we've kept the
  2013. example in the manual. However if you were to build @code{true} and
  2014. @code{false} in real life, you would probably use per-program
  2015. compilation flags, like so:
  2016. @c Keep in sync with specflg7.sh and specflg8.sh
  2017. @example
  2018. bin_PROGRAMS = false true
  2019. false_SOURCES = true.c
  2020. false_CPPFLAGS = -DEXIT_CODE=1
  2021. true_SOURCES = true.c
  2022. true_CPPFLAGS = -DEXIT_CODE=0
  2023. @end example
  2024. In this case Automake will cause @file{true.c} to be compiled twice,
  2025. with different flags. In this instance, the names of the object files
  2026. would be chosen by automake; they would be @file{false-true.o} and
  2027. @file{true-true.o}. (The name of the object files rarely matters.)
  2028. @node automake Invocation
  2029. @chapter Creating a @file{Makefile.in}
  2030. @c This node used to be named "Invoking automake". This @anchor
  2031. @c allows old links to still work.
  2032. @anchor{Invoking automake}
  2033. @cindex Multiple @file{configure.ac} files
  2034. @cindex Invoking @command{automake}
  2035. @cindex @command{automake}, invoking
  2036. @cindex Invocation of @command{automake}
  2037. @cindex @command{automake}, invocation
  2038. To create all the @file{Makefile.in}s for a package, run the
  2039. @command{automake} program in the top level directory, with no
  2040. arguments. @command{automake} will automatically find each
  2041. appropriate @file{Makefile.am} (by scanning @file{configure.ac};
  2042. @pxref{configure}) and generate the corresponding @file{Makefile.in}.
  2043. Note that @command{automake} has a rather simplistic view of what
  2044. constitutes a package; it assumes that a package has only one
  2045. @file{configure.ac}, at the top. If your package has multiple
  2046. @file{configure.ac}s, then you must run @command{automake} in each
  2047. directory holding a @file{configure.ac}. (Alternatively, you may rely
  2048. on Autoconf's @command{autoreconf}, which is able to recurse your
  2049. package tree and run @command{automake} where appropriate.)
  2050. You can optionally give @command{automake} an argument; @file{.am} is
  2051. appended to the argument and the result is used as the name of the
  2052. input file. This feature is generally only used to automatically
  2053. rebuild an out-of-date @file{Makefile.in}. Note that
  2054. @command{automake} must always be run from the topmost directory of a
  2055. project, even if being used to regenerate the @file{Makefile.in} in
  2056. some subdirectory. This is necessary because @command{automake} must
  2057. scan @file{configure.ac}, and because @command{automake} uses the
  2058. knowledge that a @file{Makefile.in} is in a subdirectory to change its
  2059. behavior in some cases.
  2060. @vindex AUTOCONF
  2061. Automake will run @command{autoconf} to scan @file{configure.ac} and
  2062. its dependencies (i.e., @file{aclocal.m4} and any included file),
  2063. therefore @command{autoconf} must be in your @env{PATH}. If there is
  2064. an @env{AUTOCONF} variable in your environment it will be used
  2065. instead of @command{autoconf}, this allows you to select a particular
  2066. version of Autoconf. By the way, don't misunderstand this paragraph:
  2067. @command{automake} runs @command{autoconf} to @strong{scan} your
  2068. @file{configure.ac}, this won't build @file{configure} and you still
  2069. have to run @command{autoconf} yourself for this purpose.
  2070. @cindex @command{automake} options
  2071. @cindex Options, @command{automake}
  2072. @cindex Strictness, command line
  2073. @command{automake} accepts the following options:
  2074. @cindex Extra files distributed with Automake
  2075. @cindex Files distributed with Automake
  2076. @cindex @file{config.guess}
  2077. @table @code
  2078. @item -a
  2079. @itemx --add-missing
  2080. @opindex -a
  2081. @opindex --add-missing
  2082. Automake requires certain common files to exist in certain situations;
  2083. for instance, @file{config.guess} is required if @file{configure.ac} invokes
  2084. @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
  2085. files (@pxref{Auxiliary Programs}); this option will cause the missing
  2086. ones to be automatically added to the package, whenever possible. In
  2087. general if Automake tells you a file is missing, try using this option.
  2088. By default Automake tries to make a symbolic link pointing to its own
  2089. copy of the missing file; this can be changed with @option{--copy}.
  2090. Many of the potentially-missing files are common scripts whose
  2091. location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
  2092. Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
  2093. file is considered missing, and where the missing file is added
  2094. (@pxref{Optional}).
  2095. In some strictness modes, additional files are installed, see @ref{Gnits}
  2096. for more information.
  2097. @item --libdir=@var{dir}
  2098. @opindex --libdir
  2099. Look for Automake data files in directory @var{dir} instead of in the
  2100. installation directory. This is typically used for debugging.
  2101. @item --print-libdir
  2102. @opindex --print-libdir
  2103. Print the path of the installation directory containing Automake-provided
  2104. scripts and data files (like e.g., @file{texinfo.texi} and
  2105. @file{install-sh}).
  2106. @item -c
  2107. @opindex -c
  2108. @itemx --copy
  2109. @opindex --copy
  2110. When used with @option{--add-missing}, causes installed files to be
  2111. copied. The default is to make a symbolic link.
  2112. @item -f
  2113. @opindex -f
  2114. @itemx --force-missing
  2115. @opindex --force-missing
  2116. When used with @option{--add-missing}, causes standard files to be reinstalled
  2117. even if they already exist in the source tree. This involves removing
  2118. the file from the source tree before creating the new symlink (or, with
  2119. @option{--copy}, copying the new file).
  2120. @item --foreign
  2121. @opindex --foreign
  2122. Set the global strictness to @option{foreign}. For more information, see
  2123. @ref{Strictness}.
  2124. @item --gnits
  2125. @opindex --gnits
  2126. Set the global strictness to @option{gnits}. For more information, see
  2127. @ref{Gnits}.
  2128. @item --gnu
  2129. @opindex --gnu
  2130. Set the global strictness to @option{gnu}. For more information, see
  2131. @ref{Gnits}. This is the default strictness.
  2132. @item --help
  2133. @opindex --help
  2134. Print a summary of the command line options and exit.
  2135. @item -i
  2136. @itemx --ignore-deps
  2137. @opindex -i
  2138. This disables the dependency tracking feature in generated
  2139. @file{Makefile}s; see @ref{Dependencies}.
  2140. @item --include-deps
  2141. @opindex --include-deps
  2142. This enables the dependency tracking feature. This feature is enabled
  2143. by default. This option is provided for historical reasons only and
  2144. probably should not be used.
  2145. @item --no-force
  2146. @opindex --no-force
  2147. Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
  2148. @file{configure.ac}. This option causes it to only update those
  2149. @file{Makefile.in}s that are out of date with respect to one of their
  2150. dependents.
  2151. @item -o @var{dir}
  2152. @itemx --output-dir=@var{dir}
  2153. @opindex -o
  2154. @opindex --output-dir
  2155. Put the generated @file{Makefile.in} in the directory @var{dir}.
  2156. Ordinarily each @file{Makefile.in} is created in the directory of the
  2157. corresponding @file{Makefile.am}. This option is deprecated and will be
  2158. removed in a future release.
  2159. @item -v
  2160. @itemx --verbose
  2161. @opindex -v
  2162. @opindex --verbose
  2163. Cause Automake to print information about which files are being read or
  2164. created.
  2165. @item --version
  2166. @opindex --version
  2167. Print the version number of Automake and exit.
  2168. @item -W CATEGORY
  2169. @itemx --warnings=@var{category}
  2170. @opindex -W
  2171. @opindex --warnings
  2172. Output warnings falling in @var{category}. @var{category} can be
  2173. one of:
  2174. @table @code
  2175. @item gnu
  2176. warnings related to the GNU Coding Standards
  2177. (@pxref{Top, , , standards, The GNU Coding Standards}).
  2178. @item obsolete
  2179. obsolete features or constructions
  2180. @item override
  2181. user redefinitions of Automake rules or variables
  2182. @item portability
  2183. portability issues (e.g., use of @command{make} features that are
  2184. known to be not portable)
  2185. @item extra-portability
  2186. extra portability issues related to obscure tools. One example of such
  2187. a tool is the Microsoft @command{lib} archiver.
  2188. @item syntax
  2189. weird syntax, unused variables, typos
  2190. @item unsupported
  2191. unsupported or incomplete features
  2192. @item all
  2193. all the warnings
  2194. @item none
  2195. turn off all the warnings
  2196. @item error
  2197. treat warnings as errors
  2198. @end table
  2199. A category can be turned off by prefixing its name with @samp{no-}. For
  2200. instance, @option{-Wno-syntax} will hide the warnings about unused
  2201. variables.
  2202. The categories output by default are @samp{obsolete}, @samp{syntax} and
  2203. @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
  2204. are enabled in @option{--gnu} and @option{--gnits} strictness.
  2205. @c Checked by extra-portability.sh
  2206. Turning off @samp{portability} will also turn off @samp{extra-portability},
  2207. and similarly turning on @samp{extra-portability} will also turn on
  2208. @samp{portability}. However, turning on @samp{portability} or turning
  2209. off @samp{extra-portability} will not affect the other category.
  2210. @vindex WARNINGS
  2211. The environment variable @env{WARNINGS} can contain a comma separated
  2212. list of categories to enable. It will be taken into account before the
  2213. command-line switches, this way @option{-Wnone} will also ignore any
  2214. warning category enabled by @env{WARNINGS}. This variable is also used
  2215. by other tools like @command{autoconf}; unknown categories are ignored
  2216. for this reason.
  2217. @end table
  2218. @vindex AUTOMAKE_JOBS
  2219. If the environment variable @env{AUTOMAKE_JOBS} contains a positive
  2220. number, it is taken as the maximum number of Perl threads to use in
  2221. @command{automake} for generating multiple @file{Makefile.in} files
  2222. concurrently. This is an experimental feature.
  2223. @node configure
  2224. @chapter Scanning @file{configure.ac}, using @command{aclocal}
  2225. @cindex @file{configure.ac}, scanning
  2226. @cindex Scanning @file{configure.ac}
  2227. @cindex Using @command{aclocal}
  2228. @cindex @command{aclocal}, using
  2229. Automake scans the package's @file{configure.ac} to determine certain
  2230. information about the package. Some @command{autoconf} macros are required
  2231. and some variables must be defined in @file{configure.ac}. Automake
  2232. will also use information from @file{configure.ac} to further tailor its
  2233. output.
  2234. Automake also supplies some Autoconf macros to make the maintenance
  2235. easier. These macros can automatically be put into your
  2236. @file{aclocal.m4} using the @command{aclocal} program.
  2237. @menu
  2238. * Requirements:: Configuration requirements
  2239. * Optional:: Other things Automake recognizes
  2240. * aclocal Invocation:: Auto-generating aclocal.m4
  2241. * Macros:: Autoconf macros supplied with Automake
  2242. @end menu
  2243. @node Requirements
  2244. @section Configuration requirements
  2245. @cindex Automake requirements
  2246. @cindex Requirements of Automake
  2247. @acindex AM_INIT_AUTOMAKE
  2248. The one real requirement of Automake is that your @file{configure.ac}
  2249. call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
  2250. required for proper Automake operation (@pxref{Macros}).
  2251. Here are the other macros that Automake requires but which are not run
  2252. by @code{AM_INIT_AUTOMAKE}:
  2253. @table @code
  2254. @item AC_CONFIG_FILES
  2255. @itemx AC_OUTPUT
  2256. @acindex AC_CONFIG_FILES
  2257. @acindex AC_OUTPUT
  2258. These two macros are usually invoked as follows near the end of
  2259. @file{configure.ac}.
  2260. @example
  2261. @dots{}
  2262. AC_CONFIG_FILES([
  2263. Makefile
  2264. doc/Makefile
  2265. src/Makefile
  2266. src/lib/Makefile
  2267. @dots{}
  2268. ])
  2269. AC_OUTPUT
  2270. @end example
  2271. Automake uses these to determine which files to create (@pxref{Output, ,
  2272. Creating Output Files, autoconf, The Autoconf Manual}). A listed file
  2273. is considered to be an Automake generated @file{Makefile} if there
  2274. exists a file with the same name and the @file{.am} extension appended.
  2275. Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
  2276. generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
  2277. When using @code{AC_CONFIG_FILES} with multiple input files, as in
  2278. @example
  2279. AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
  2280. @end example
  2281. @noindent
  2282. @command{automake} will generate the first @file{.in} input file for
  2283. which a @file{.am} file exists. If no such file exists the output
  2284. file is not considered to be generated by Automake.
  2285. Files created by @code{AC_CONFIG_FILES}, be they Automake
  2286. @file{Makefile}s or not, are all removed by @samp{make distclean}.
  2287. Their inputs are automatically distributed, unless they
  2288. are the output of prior @code{AC_CONFIG_FILES} commands.
  2289. Finally, rebuild rules are generated in the Automake @file{Makefile}
  2290. existing in the subdirectory of the output file, if there is one, or
  2291. in the top-level @file{Makefile} otherwise.
  2292. The above machinery (cleaning, distributing, and rebuilding) works
  2293. fine if the @code{AC_CONFIG_FILES} specifications contain only
  2294. literals. If part of the specification uses shell variables,
  2295. @command{automake} will not be able to fulfill this setup, and you will
  2296. have to complete the missing bits by hand. For instance, on
  2297. @c Keep in sync with output11.sh
  2298. @example
  2299. file=input
  2300. @dots{}
  2301. AC_CONFIG_FILES([output:$file],, [file=$file])
  2302. @end example
  2303. @noindent
  2304. @command{automake} will output rules to clean @file{output}, and
  2305. rebuild it. However the rebuild rule will not depend on @file{input},
  2306. and this file will not be distributed either. (You must add
  2307. @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
  2308. source file.)
  2309. Similarly
  2310. @c Keep in sync with output11.sh
  2311. @example
  2312. file=output
  2313. file2=out:in
  2314. @dots{}
  2315. AC_CONFIG_FILES([$file:input],, [file=$file])
  2316. AC_CONFIG_FILES([$file2],, [file2=$file2])
  2317. @end example
  2318. @noindent
  2319. will only cause @file{input} to be distributed. No file will be
  2320. cleaned automatically (add @samp{DISTCLEANFILES = output out}
  2321. yourself), and no rebuild rule will be output.
  2322. Obviously @command{automake} cannot guess what value @samp{$file} is
  2323. going to hold later when @file{configure} is run, and it cannot use
  2324. the shell variable @samp{$file} in a @file{Makefile}. However, if you
  2325. make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
  2326. that is compatible with @command{make}'s syntax) and furthermore use
  2327. @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
  2328. @file{Makefile}, then @command{automake} will be able to use
  2329. @samp{$@{file@}} to generate all of these rules. For instance, here is
  2330. how the Automake package itself generates versioned scripts for its
  2331. test suite:
  2332. @example
  2333. AC_SUBST([APIVERSION], @dots{})
  2334. @dots{}
  2335. AC_CONFIG_FILES(
  2336. [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
  2337. [chmod +x tests/aclocal-$@{APIVERSION@}],
  2338. [APIVERSION=$APIVERSION])
  2339. AC_CONFIG_FILES(
  2340. [tests/automake-$@{APIVERSION@}:tests/automake.in],
  2341. [chmod +x tests/automake-$@{APIVERSION@}])
  2342. @end example
  2343. @noindent
  2344. Here cleaning, distributing, and rebuilding are done automatically,
  2345. because @samp{$@{APIVERSION@}} is known at @command{make}-time.
  2346. Note that you should not use shell variables to declare
  2347. @file{Makefile} files for which @command{automake} must create
  2348. @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
  2349. @command{automake} needs to know the file name when it runs in order
  2350. to check whether @file{Makefile.am} exists. (In the very hairy case
  2351. that your setup requires such use of variables, you will have to tell
  2352. Automake which @file{Makefile.in}s to generate on the command-line.)
  2353. It is possible to let @command{automake} emit conditional rules for
  2354. @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
  2355. (@pxref{Optional}).
  2356. To summarize:
  2357. @itemize @bullet
  2358. @item
  2359. Use literals for @file{Makefile}s, and for other files whenever possible.
  2360. @item
  2361. Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
  2362. for files that @command{automake} should ignore.
  2363. @item
  2364. Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
  2365. that @command{automake} should not ignore.
  2366. @end itemize
  2367. @end table
  2368. @node Optional
  2369. @section Other things Automake recognizes
  2370. @cindex Macros Automake recognizes
  2371. @cindex Recognized macros by Automake
  2372. Every time Automake is run it calls Autoconf to trace
  2373. @file{configure.ac}. This way it can recognize the use of certain
  2374. macros and tailor the generated @file{Makefile.in} appropriately.
  2375. Currently recognized macros and their effects are:
  2376. @ftable @code
  2377. @item AC_CANONICAL_BUILD
  2378. @itemx AC_CANONICAL_HOST
  2379. @itemx AC_CANONICAL_TARGET
  2380. @vindex build_triplet
  2381. @vindex host_triplet
  2382. @vindex target_triplet
  2383. Automake will ensure that @file{config.guess} and @file{config.sub}
  2384. exist. Also, the @file{Makefile} variables @code{build_triplet},
  2385. @code{host_triplet} and @code{target_triplet} are introduced. See
  2386. @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
  2387. The Autoconf Manual}.
  2388. @item AC_CONFIG_AUX_DIR
  2389. Automake will look for various helper scripts, such as
  2390. @file{install-sh}, in the directory named in this macro invocation.
  2391. @c This list is accurate relative to version 1.11
  2392. (The full list of scripts is:
  2393. @file{ar-lib},
  2394. @file{config.guess},
  2395. @file{config.sub},
  2396. @file{depcomp},
  2397. @file{compile},
  2398. @file{install-sh},
  2399. @file{ltmain.sh},
  2400. @file{mdate-sh},
  2401. @file{missing},
  2402. @file{mkinstalldirs},
  2403. @file{py-compile},
  2404. @file{test-driver},
  2405. @file{texinfo.tex},
  2406. @file{ylwrap}.)
  2407. Not all scripts are always searched for; some scripts
  2408. will only be sought if the generated @file{Makefile.in} requires them.
  2409. If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
  2410. their standard locations. For @file{mdate-sh},
  2411. @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
  2412. source directory corresponding to the current @file{Makefile.am}. For
  2413. the rest, the standard location is the first one of @file{.}, @file{..},
  2414. or @file{../..} (relative to the top source directory) that provides any
  2415. one of the helper scripts. @xref{Input, , Finding `configure' Input,
  2416. autoconf, The Autoconf Manual}.
  2417. Required files from @code{AC_CONFIG_AUX_DIR} are automatically
  2418. distributed, even if there is no @file{Makefile.am} in this directory.
  2419. @item AC_CONFIG_LIBOBJ_DIR
  2420. Automake will require the sources file declared with
  2421. @code{AC_LIBSOURCE} (see below) in the directory specified by this
  2422. macro.
  2423. @item AC_CONFIG_HEADERS
  2424. Automake will generate rules to rebuild these headers from the
  2425. corresponding templates (usually, the template for a @file{foo.h}
  2426. header being @file{foo.h.in}). Older versions of Automake
  2427. required the use of @code{AM_CONFIG_HEADER}; this is no longer
  2428. the case, and that macro has indeed been removed.
  2429. As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
  2430. specification using shell variables will be ignored as far as
  2431. cleaning, distributing, and rebuilding is concerned.
  2432. @item AC_CONFIG_LINKS
  2433. Automake will generate rules to remove @file{configure} generated
  2434. links on @samp{make distclean} and to distribute named source files as
  2435. part of @samp{make dist}.
  2436. As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
  2437. specification using shell variables will be ignored as far as cleaning
  2438. and distributing is concerned. (There are no rebuild rules for links.)
  2439. @item AC_LIBOBJ
  2440. @itemx AC_LIBSOURCE
  2441. @itemx AC_LIBSOURCES
  2442. @vindex LIBOBJS
  2443. Automake will automatically distribute any file listed in
  2444. @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
  2445. Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
  2446. an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
  2447. @file{file.c} will be distributed automatically by Automake. This
  2448. encompasses many macros like @code{AC_FUNC_ALLOCA},
  2449. @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
  2450. By the way, direct assignments to @code{LIBOBJS} are no longer
  2451. supported. You should always use @code{AC_LIBOBJ} for this purpose.
  2452. @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
  2453. autoconf, The Autoconf Manual}.
  2454. @item AC_PROG_RANLIB
  2455. This is required if any libraries are built in the package.
  2456. @xref{Particular Programs, , Particular Program Checks, autoconf, The
  2457. Autoconf Manual}.
  2458. @item AC_PROG_CXX
  2459. This is required if any C++ source is included. @xref{Particular
  2460. Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
  2461. @item AC_PROG_OBJC
  2462. This is required if any Objective C source is included. @xref{Particular
  2463. Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
  2464. @item AC_PROG_OBJCXX
  2465. This is required if any Objective C++ source is included. @xref{Particular
  2466. Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
  2467. @item AC_PROG_F77
  2468. This is required if any Fortran 77 source is included. @xref{Particular
  2469. Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
  2470. @item AC_F77_LIBRARY_LDFLAGS
  2471. This is required for programs and shared libraries that are a mixture of
  2472. languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
  2473. C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
  2474. @item AC_FC_SRCEXT
  2475. Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
  2476. of files with the respective source extension (@pxref{Fortran Compiler, ,
  2477. Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
  2478. @item AC_PROG_FC
  2479. This is required if any Fortran 90/95 source is included. This macro is
  2480. distributed with Autoconf version 2.58 and later. @xref{Particular
  2481. Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
  2482. @item AC_PROG_LIBTOOL
  2483. Automake will turn on processing for @command{libtool} (@pxref{Top, ,
  2484. Introduction, libtool, The Libtool Manual}).
  2485. @item AC_PROG_YACC
  2486. @vindex YACC
  2487. If a Yacc source file is seen, then you must either use this macro or
  2488. define the variable @code{YACC} in @file{configure.ac}. The former is
  2489. preferred (@pxref{Particular Programs, , Particular Program Checks,
  2490. autoconf, The Autoconf Manual}).
  2491. @item AC_PROG_LEX
  2492. If a Lex source file is seen, then this macro must be used.
  2493. @xref{Particular Programs, , Particular Program Checks, autoconf, The
  2494. Autoconf Manual}.
  2495. @item AC_REQUIRE_AUX_FILE
  2496. For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
  2497. @command{automake} will ensure that @file{@var{file}} exists in the
  2498. aux directory, and will complain otherwise. It
  2499. will also automatically distribute the file. This macro should be
  2500. used by third-party Autoconf macros that require some supporting
  2501. files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
  2502. above. @xref{Input, , Finding @command{configure} Input, autoconf,
  2503. The Autoconf Manual}.
  2504. @item AC_SUBST
  2505. The first argument is automatically defined as a variable in each
  2506. generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
  2507. used for this variable. @xref{Setting Output Variables, , Setting
  2508. Output Variables, autoconf, The Autoconf Manual}.
  2509. For every substituted variable @var{var}, @command{automake} will add
  2510. a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
  2511. Many Autoconf macros invoke @code{AC_SUBST} to set output variables
  2512. this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
  2513. @code{X_LIBS}. Thus, you can access these variables as
  2514. @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
  2515. if @code{AC_PATH_XTRA} is called.
  2516. @item AM_CONDITIONAL
  2517. This introduces an Automake conditional (@pxref{Conditionals}).
  2518. @item AM_COND_IF
  2519. This macro allows @code{automake} to detect subsequent access within
  2520. @file{configure.ac} to a conditional previously introduced with
  2521. @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
  2522. (@pxref{Usage of Conditionals}).
  2523. @item AM_GNU_GETTEXT
  2524. This macro is required for packages that use GNU gettext
  2525. (@pxref{gettext}). It is distributed with gettext. If Automake sees
  2526. this macro it ensures that the package meets some of gettext's
  2527. requirements.
  2528. @item AM_GNU_GETTEXT_INTL_SUBDIR
  2529. This macro specifies that the @file{intl/} subdirectory is to be built,
  2530. even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
  2531. of @samp{external}.
  2532. @item AM_MAINTAINER_MODE(@ovar{default-mode})
  2533. @opindex --enable-maintainer-mode
  2534. @opindex --disable-maintainer-mode
  2535. This macro adds an @option{--enable-maintainer-mode} option to
  2536. @command{configure}. If this is used, @command{automake} will cause
  2537. ``maintainer-only'' rules to be turned off by default in the
  2538. generated @file{Makefile.in}s, unless @var{default-mode} is
  2539. @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
  2540. conditional, which you can use in your own @file{Makefile.am}.
  2541. @xref{maintainer-mode}.
  2542. @item AM_SUBST_NOTMAKE(@var{var})
  2543. Prevent Automake from defining a variable @var{var}, even if it is
  2544. substituted by @command{config.status}. Normally, Automake defines a
  2545. @command{make} variable for each @command{configure} substitution,
  2546. i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
  2547. definition from Automake. If @code{AC_SUBST} has not been called
  2548. for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
  2549. Preventing variable definitions may be useful for substitution of
  2550. multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
  2551. unintended results.
  2552. @item m4_include
  2553. Files included by @file{configure.ac} using this macro will be
  2554. detected by Automake and automatically distributed. They will also
  2555. appear as dependencies in @file{Makefile} rules.
  2556. @code{m4_include} is seldom used by @file{configure.ac} authors, but
  2557. can appear in @file{aclocal.m4} when @command{aclocal} detects that
  2558. some required macros come from files local to your package (as opposed to
  2559. macros installed in a system-wide directory, @pxref{aclocal Invocation}).
  2560. @end ftable
  2561. @node aclocal Invocation
  2562. @section Auto-generating aclocal.m4
  2563. @c This node used to be named "Invoking automake". This @anchor
  2564. @c allows old links to still work.
  2565. @anchor{Invoking aclocal}
  2566. @cindex Invocation of @command{aclocal}
  2567. @cindex @command{aclocal}, Invocation
  2568. @cindex Invoking @command{aclocal}
  2569. @cindex @command{aclocal}, Invoking
  2570. Automake includes a number of Autoconf macros that can be used in
  2571. your package (@pxref{Macros}); some of them are actually required by
  2572. Automake in certain situations. These macros must be defined in your
  2573. @file{aclocal.m4}; otherwise they will not be seen by
  2574. @command{autoconf}.
  2575. The @command{aclocal} program will automatically generate
  2576. @file{aclocal.m4} files based on the contents of @file{configure.ac}.
  2577. This provides a convenient way to get Automake-provided macros,
  2578. without having to search around. The @command{aclocal} mechanism
  2579. allows other packages to supply their own macros (@pxref{Extending
  2580. aclocal}). You can also use it to maintain your own set of custom
  2581. macros (@pxref{Local Macros}).
  2582. At startup, @command{aclocal} scans all the @file{.m4} files it can
  2583. find, looking for macro definitions (@pxref{Macro Search Path}). Then
  2584. it scans @file{configure.ac}. Any mention of one of the macros found
  2585. in the first step causes that macro, and any macros it in turn
  2586. requires, to be put into @file{aclocal.m4}.
  2587. @emph{Putting} the file that contains the macro definition into
  2588. @file{aclocal.m4} is usually done by copying the entire text of this
  2589. file, including unused macro definitions as well as both @samp{#} and
  2590. @samp{dnl} comments. If you want to make a comment that will be
  2591. completely ignored by @command{aclocal}, use @samp{##} as the comment
  2592. leader.
  2593. When a file selected by @command{aclocal} is located in a subdirectory
  2594. specified as a relative search path with @command{aclocal}'s @option{-I}
  2595. argument, @command{aclocal} assumes the file belongs to the package
  2596. and uses @code{m4_include} instead of copying it into
  2597. @file{aclocal.m4}. This makes the package smaller, eases dependency
  2598. tracking, and cause the file to be distributed automatically.
  2599. (@xref{Local Macros}, for an example.) Any macro that is found in a
  2600. system-wide directory, or via an absolute search path will be copied.
  2601. So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
  2602. some relative directory should be considered outside the package.
  2603. The contents of @file{acinclude.m4}, if this file exists, are also
  2604. automatically included in @file{aclocal.m4}. We recommend against
  2605. using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
  2606. @vindex AUTOM4TE
  2607. @cindex autom4te
  2608. While computing @file{aclocal.m4}, @command{aclocal} runs
  2609. @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
  2610. autoconf, The Autoconf Manual}) in order to trace the macros that are
  2611. really used, and omit from @file{aclocal.m4} all macros that are
  2612. mentioned but otherwise unexpanded (this can happen when a macro is
  2613. called conditionally). @command{autom4te} is expected to be in the
  2614. @env{PATH}, just as @command{autoconf}. Its location can be
  2615. overridden using the @env{AUTOM4TE} environment variable.
  2616. @menu
  2617. * aclocal Options:: Options supported by aclocal
  2618. * Macro Search Path:: How aclocal finds .m4 files
  2619. * Extending aclocal:: Writing your own aclocal macros
  2620. * Local Macros:: Organizing local macros
  2621. * Serials:: Serial lines in Autoconf macros
  2622. * Future of aclocal:: aclocal's scheduled death
  2623. @end menu
  2624. @node aclocal Options
  2625. @subsection aclocal Options
  2626. @cindex @command{aclocal}, Options
  2627. @cindex Options, @command{aclocal}
  2628. @command{aclocal} accepts the following options:
  2629. @table @code
  2630. @item --automake-acdir=@var{dir}
  2631. @opindex --automake-acdir
  2632. Look for the automake-provided macro files in @var{dir} instead of
  2633. in the installation directory. This is typically used for debugging.
  2634. @item --system-acdir=@var{dir}
  2635. @opindex --system-acdir
  2636. Look for the system-wide third-party macro files (and the special
  2637. @file{dirlist} file) in @var{dir} instead of in the installation
  2638. directory. This is typically used for debugging.
  2639. @item --diff[=@var{command}]
  2640. @opindex --diff
  2641. Run @var{command} on M4 file that would be installed or overwritten
  2642. by @option{--install}. The default @var{command} is @samp{diff -u}.
  2643. This option implies @option{--install} and @option{--dry-run}.
  2644. @item --dry-run
  2645. @opindex --dry-run
  2646. Do not actually overwrite (or create) @file{aclocal.m4} and M4
  2647. files installed by @option{--install}.
  2648. @item --help
  2649. @opindex --help
  2650. Print a summary of the command line options and exit.
  2651. @item -I @var{dir}
  2652. @opindex -I
  2653. Add the directory @var{dir} to the list of directories searched for
  2654. @file{.m4} files.
  2655. @item --install
  2656. @opindex --install
  2657. Install system-wide third-party macros into the first directory
  2658. specified with @samp{-I @var{dir}} instead of copying them in the
  2659. output file.
  2660. @c Keep in sync with aclocal-install-absdir.sh
  2661. Note that this will happen also if @var{dir} is an absolute path.
  2662. @cindex serial number and @option{--install}
  2663. When this option is used, and only when this option is used,
  2664. @command{aclocal} will also honor @samp{#serial @var{number}} lines
  2665. that appear in macros: an M4 file is ignored if there exists another
  2666. M4 file with the same basename and a greater serial number in the
  2667. search path (@pxref{Serials}).
  2668. @item --force
  2669. @opindex --force
  2670. Always overwrite the output file. The default is to overwrite the output
  2671. file only when really needed, i.e., when its contents changes or if one
  2672. of its dependencies is younger.
  2673. This option forces the update of @file{aclocal.m4} (or the file
  2674. specified with @file{--output} below) and only this file, it has
  2675. absolutely no influence on files that may need to be installed by
  2676. @option{--install}.
  2677. @item --output=@var{file}
  2678. @opindex --output
  2679. Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
  2680. @item --print-ac-dir
  2681. @opindex --print-ac-dir
  2682. Prints the name of the directory that @command{aclocal} will search to
  2683. find third-party @file{.m4} files. When this option is given, normal
  2684. processing is suppressed. This option was used @emph{in the past} by
  2685. third-party packages to determine where to install @file{.m4} macro
  2686. files, but @emph{this usage is today discouraged}, since it causes
  2687. @samp{$(prefix)} not to be thoroughly honored (which violates the
  2688. GNU Coding Standards), and a similar semantics can be better obtained
  2689. with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
  2690. @item --verbose
  2691. @opindex --verbose
  2692. Print the names of the files it examines.
  2693. @item --version
  2694. @opindex --version
  2695. Print the version number of Automake and exit.
  2696. @item -W CATEGORY
  2697. @item --warnings=@var{category}
  2698. @opindex -W
  2699. @opindex --warnings
  2700. Output warnings falling in @var{category}. @var{category} can be
  2701. one of:
  2702. @table @code
  2703. @item syntax
  2704. dubious syntactic constructs, underquoted macros, unused macros, etc.
  2705. @item unsupported
  2706. unknown macros
  2707. @item all
  2708. all the warnings, this is the default
  2709. @item none
  2710. turn off all the warnings
  2711. @item error
  2712. treat warnings as errors
  2713. @end table
  2714. All warnings are output by default.
  2715. @vindex WARNINGS
  2716. The environment variable @env{WARNINGS} is honored in the same
  2717. way as it is for @command{automake} (@pxref{automake Invocation}).
  2718. @end table
  2719. @node Macro Search Path
  2720. @subsection Macro Search Path
  2721. @cindex Macro search path
  2722. @cindex @command{aclocal} search path
  2723. By default, @command{aclocal} searches for @file{.m4} files in the following
  2724. directories, in this order:
  2725. @table @code
  2726. @item @var{acdir-APIVERSION}
  2727. This is where the @file{.m4} macros distributed with Automake itself
  2728. are stored. @var{APIVERSION} depends on the Automake release used;
  2729. for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
  2730. @item @var{acdir}
  2731. This directory is intended for third party @file{.m4} files, and is
  2732. configured when @command{automake} itself is built. This is
  2733. @file{@@datadir@@/aclocal/}, which typically
  2734. expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
  2735. value of @var{acdir}, use the @option{--print-ac-dir} option
  2736. (@pxref{aclocal Options}).
  2737. @end table
  2738. As an example, suppose that @command{automake-1.11.2} was configured with
  2739. @option{--prefix=@-/usr/local}. Then, the search path would be:
  2740. @enumerate
  2741. @item @file{/usr/local/share/aclocal-1.11.2/}
  2742. @item @file{/usr/local/share/aclocal/}
  2743. @end enumerate
  2744. The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
  2745. be changed respectively through aclocal options @option{--system-acdir}
  2746. and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
  2747. that these options are only intended for use by the internal Automake
  2748. test suite, or for debugging under highly unusual situations; they are
  2749. not ordinarily needed by end-users.
  2750. As explained in (@pxref{aclocal Options}), there are several options that
  2751. can be used to change or extend this search path.
  2752. @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
  2753. Any extra directories specified using @option{-I} options
  2754. (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
  2755. @samp{aclocal -I /foo -I /bar} results in the following search path:
  2756. @enumerate
  2757. @item @file{/foo}
  2758. @item @file{/bar}
  2759. @item @var{acdir}-@var{APIVERSION}
  2760. @item @var{acdir}
  2761. @end enumerate
  2762. @subsubheading Modifying the Macro Search Path: @file{dirlist}
  2763. @cindex @file{dirlist}
  2764. There is a third mechanism for customizing the search path. If a
  2765. @file{dirlist} file exists in @var{acdir}, then that file is assumed to
  2766. contain a list of directory patterns, one per line. @command{aclocal}
  2767. expands these patterns to directory names, and adds them to the search
  2768. list @emph{after} all other directories. @file{dirlist} entries may
  2769. use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
  2770. For example, suppose
  2771. @file{@var{acdir}/dirlist} contains the following:
  2772. @example
  2773. /test1
  2774. /test2
  2775. /test3*
  2776. @end example
  2777. @noindent
  2778. and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
  2779. Then, the search path would be
  2780. @c @code looks better than @file here
  2781. @enumerate
  2782. @item @code{/foo}
  2783. @item @code{/bar}
  2784. @item @var{acdir}-@var{APIVERSION}
  2785. @item @var{acdir}
  2786. @item @code{/test1}
  2787. @item @code{/test2}
  2788. @end enumerate
  2789. @noindent
  2790. and all directories with path names starting with @code{/test3}.
  2791. If the @option{--system-acdir=@var{dir}} option is used, then
  2792. @command{aclocal} will search for the @file{dirlist} file in
  2793. @var{dir}; but remember the warnings above against the use of
  2794. @option{--system-acdir}.
  2795. @file{dirlist} is useful in the following situation: suppose that
  2796. @command{automake} version @code{1.11.2} is installed with
  2797. @samp{--prefix=/usr} by the system vendor. Thus, the default search
  2798. directories are
  2799. @c @code looks better than @file here
  2800. @enumerate
  2801. @item @code{/usr/share/aclocal-1.11/}
  2802. @item @code{/usr/share/aclocal/}
  2803. @end enumerate
  2804. However, suppose further that many packages have been manually
  2805. installed on the system, with $prefix=/usr/local, as is typical. In
  2806. that case, many of these ``extra'' @file{.m4} files are in
  2807. @file{/usr/local/share/aclocal}. The only way to force
  2808. @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
  2809. always call @samp{aclocal -I /usr/local/share/aclocal}. This is
  2810. inconvenient. With @file{dirlist}, one may create a file
  2811. @file{/usr/share/aclocal/dirlist} containing only the single line
  2812. @example
  2813. /usr/local/share/aclocal
  2814. @end example
  2815. Now, the ``default'' search path on the affected system is
  2816. @c @code looks better than @file here
  2817. @enumerate
  2818. @item @code{/usr/share/aclocal-1.11/}
  2819. @item @code{/usr/share/aclocal/}
  2820. @item @code{/usr/local/share/aclocal/}
  2821. @end enumerate
  2822. without the need for @option{-I} options; @option{-I} options can be reserved
  2823. for project-specific needs (@file{my-source-dir/m4/}), rather than
  2824. using it to work around local system-dependent tool installation
  2825. directories.
  2826. Similarly, @file{dirlist} can be handy if you have installed a local
  2827. copy of Automake in your account and want @command{aclocal} to look for
  2828. macros installed at other places on the system.
  2829. @anchor{ACLOCAL_PATH}
  2830. @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
  2831. @cindex @env{ACLOCAL_PATH}
  2832. The fourth and last mechanism to customize the macro search path is
  2833. also the simplest. Any directory included in the colon-separated
  2834. environment variable @env{ACLOCAL_PATH} is added to the search path
  2835. @c Keep in sync with aclocal-path-precedence.sh
  2836. and takes precedence over system directories (including those found via
  2837. @file{dirlist}), with the exception of the versioned directory
  2838. @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
  2839. passed via @option{-I} will take precedence over directories in
  2840. @env{ACLOCAL_PATH}.
  2841. @c Keep in sync with aclocal-path-installed.sh
  2842. Also note that, if the @option{--install} option is used, any @file{.m4}
  2843. file containing a required macro that is found in a directory listed in
  2844. @env{ACLOCAL_PATH} will be installed locally.
  2845. @c Keep in sync with aclocal-path-installed-serial.sh
  2846. In this case, serial numbers in @file{.m4} are honored too,
  2847. @pxref{Serials}.
  2848. Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
  2849. using a global copy of Automake and want @command{aclocal} to look for
  2850. macros somewhere under your home directory.
  2851. @subsubheading Planned future incompatibilities
  2852. The order in which the directories in the macro search path are currently
  2853. looked up is confusing and/or suboptimal in various aspects, and is
  2854. probably going to be changed in the future Automake release. In
  2855. particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
  2856. might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
  2857. directories in @file{@var{acdir}/dirlist} might end up taking precedence
  2858. over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
  2859. @node Extending aclocal
  2860. @subsection Writing your own aclocal macros
  2861. @cindex @command{aclocal}, extending
  2862. @cindex Extending @command{aclocal}
  2863. The @command{aclocal} program doesn't have any built-in knowledge of any
  2864. macros, so it is easy to extend it with your own macros.
  2865. This can be used by libraries that want to supply their own Autoconf
  2866. macros for use by other programs. For instance, the @command{gettext}
  2867. library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
  2868. any package using @command{gettext}. When the library is installed, it
  2869. installs this macro so that @command{aclocal} will find it.
  2870. A macro file's name should end in @file{.m4}. Such files should be
  2871. installed in @file{$(datadir)/aclocal}. This is as simple as writing:
  2872. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  2873. @example
  2874. aclocaldir = $(datadir)/aclocal
  2875. aclocal_DATA = mymacro.m4 myothermacro.m4
  2876. @end example
  2877. @noindent
  2878. Please do use @file{$(datadir)/aclocal}, and not something based on
  2879. the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
  2880. Paths}, for arguments). It might also be helpful to suggest to
  2881. the user to add the @file{$(datadir)/aclocal} directory to his
  2882. @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
  2883. @command{aclocal} will find the @file{.m4} files installed by your
  2884. package automatically.
  2885. A file of macros should be a series of properly quoted
  2886. @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
  2887. Autoconf Manual}). The @command{aclocal} programs also understands
  2888. @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
  2889. Autoconf Manual}), so it is safe to put each macro in a separate file.
  2890. Each file should have no side effects but macro definitions.
  2891. Especially, any call to @code{AC_PREREQ} should be done inside the
  2892. defined macro, not at the beginning of the file.
  2893. @cindex underquoted @code{AC_DEFUN}
  2894. @acindex AC_DEFUN
  2895. @acindex AC_PREREQ
  2896. Starting with Automake 1.8, @command{aclocal} will warn about all
  2897. underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
  2898. lot of people, because @command{aclocal} was not so strict in the past
  2899. and many third party macros are underquoted; and we have to apologize
  2900. for this temporary inconvenience. The reason we have to be stricter
  2901. is that a future implementation of @command{aclocal} (@pxref{Future of
  2902. aclocal}) will have to temporarily include all of these third party
  2903. @file{.m4} files, maybe several times, including even files that are
  2904. not actually needed. Doing so should alleviate many problems of the
  2905. current implementation, however it requires a stricter style from the
  2906. macro authors. Hopefully it is easy to revise the existing macros.
  2907. For instance,
  2908. @example
  2909. # bad style
  2910. AC_PREREQ(2.68)
  2911. AC_DEFUN(AX_FOOBAR,
  2912. [AC_REQUIRE([AX_SOMETHING])dnl
  2913. AX_FOO
  2914. AX_BAR
  2915. ])
  2916. @end example
  2917. @noindent
  2918. should be rewritten as
  2919. @example
  2920. AC_DEFUN([AX_FOOBAR],
  2921. [AC_PREREQ([2.68])dnl
  2922. AC_REQUIRE([AX_SOMETHING])dnl
  2923. AX_FOO
  2924. AX_BAR
  2925. ])
  2926. @end example
  2927. Wrapping the @code{AC_PREREQ} call inside the macro ensures that
  2928. Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually
  2929. used. Most importantly, quoting the first argument of @code{AC_DEFUN}
  2930. allows the macro to be redefined or included twice (otherwise this
  2931. first argument would be expanded during the second definition). For
  2932. consistency we like to quote even arguments such as @code{2.68} that
  2933. do not require it.
  2934. If you have been directed here by the @command{aclocal} diagnostic but
  2935. are not the maintainer of the implicated macro, you will want to
  2936. contact the maintainer of that macro. Please make sure you have the
  2937. latest version of the macro and that the problem hasn't already been
  2938. reported before doing so: people tend to work faster when they aren't
  2939. flooded by mails.
  2940. Another situation where @command{aclocal} is commonly used is to
  2941. manage macros that are used locally by the package, @ref{Local
  2942. Macros}.
  2943. @node Local Macros
  2944. @subsection Handling Local Macros
  2945. Feature tests offered by Autoconf do not cover all needs. People
  2946. often have to supplement existing tests with their own macros, or
  2947. with third-party macros.
  2948. There are two ways to organize custom macros in a package.
  2949. The first possibility (the historical practice) is to list all your
  2950. macros in @file{acinclude.m4}. This file will be included in
  2951. @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
  2952. henceforth be visible to @command{autoconf}. However if it contains
  2953. numerous macros, it will rapidly become difficult to maintain, and it
  2954. will be almost impossible to share macros between packages.
  2955. The second possibility, which we do recommend, is to write each macro
  2956. in its own file and gather all these files in a directory. This
  2957. directory is usually called @file{m4/}. Then it's enough to update
  2958. @file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIRS}:
  2959. @example
  2960. AC_CONFIG_MACRO_DIRS([m4])
  2961. @end example
  2962. @command{aclocal} will then take care of automatically adding @file{m4/}
  2963. to its search path for m4 files.
  2964. When @samp{aclocal} is run, it will build an @file{aclocal.m4}
  2965. that @code{m4_include}s any file from @file{m4/} that defines a
  2966. required macro. Macros not found locally will still be searched in
  2967. system-wide directories, as explained in @ref{Macro Search Path}.
  2968. Custom macros should be distributed for the same reason that
  2969. @file{configure.ac} is: so that other people have all the sources of
  2970. your package if they want to work on it. Actually, this distribution
  2971. happens automatically because all @code{m4_include}d files are
  2972. distributed.
  2973. However there is no consensus on the distribution of third-party
  2974. macros that your package may use. Many libraries install their own
  2975. macro in the system-wide @command{aclocal} directory (@pxref{Extending
  2976. aclocal}). For instance, Guile ships with a file called
  2977. @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
  2978. be used to define setup compiler and linker flags appropriate for
  2979. using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
  2980. cause @command{aclocal} to copy @file{guile.m4} into
  2981. @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
  2982. it will not be distributed. Technically, that means a user who
  2983. needs to rebuild @file{aclocal.m4} will have to install Guile first.
  2984. This is probably OK, if Guile already is a requirement to build the
  2985. package. However, if Guile is only an optional feature, or if your
  2986. package might run on architectures where Guile cannot be installed,
  2987. this requirement will hinder development. An easy solution is to copy
  2988. such third-party macros in your local @file{m4/} directory so they get
  2989. distributed.
  2990. Since Automake 1.10, @command{aclocal} offers the option @code{--install}
  2991. to copy these system-wide third-party macros in your local macro directory,
  2992. helping to solve the above problem.
  2993. With this setup, system-wide macros will be copied to @file{m4/}
  2994. the first time you run @command{aclocal}. Then the locally installed
  2995. macros will have precedence over the system-wide installed macros
  2996. each time @command{aclocal} is run again.
  2997. One reason why you should keep @option{--install} in the flags even
  2998. after the first run is that when you later edit @file{configure.ac}
  2999. and depend on a new macro, this macro will be installed in your
  3000. @file{m4/} automatically. Another one is that serial numbers
  3001. (@pxref{Serials}) can be used to update the macros in your source tree
  3002. automatically when new system-wide versions are installed. A serial
  3003. number should be a single line of the form
  3004. @example
  3005. #serial @var{nnn}
  3006. @end example
  3007. @noindent
  3008. where @var{nnn} contains only digits and dots. It should appear in
  3009. the M4 file before any macro definition. It is a good practice to
  3010. maintain a serial number for each macro you distribute, even if you do
  3011. not use the @option{--install} option of @command{aclocal}: this allows
  3012. other people to use it.
  3013. @node Serials
  3014. @subsection Serial Numbers
  3015. @cindex serial numbers in macros
  3016. @cindex macro serial numbers
  3017. @cindex @code{#serial} syntax
  3018. @cindex @command{aclocal} and serial numbers
  3019. Because third-party macros defined in @file{*.m4} files are naturally
  3020. shared between multiple projects, some people like to version them.
  3021. This makes it easier to tell which of two M4 files is newer. Since at
  3022. least 1996, the tradition is to use a @samp{#serial} line for this.
  3023. A serial number should be a single line of the form
  3024. @example
  3025. # serial @var{version}
  3026. @end example
  3027. @noindent
  3028. where @var{version} is a version number containing only digits and
  3029. dots. Usually people use a single integer, and they increment it each
  3030. time they change the macro (hence the name of ``serial''). Such a
  3031. line should appear in the M4 file before any macro definition.
  3032. The @samp{#} must be the first character on the line,
  3033. and it is OK to have extra words after the version, as in
  3034. @example
  3035. #serial @var{version} @var{garbage}
  3036. @end example
  3037. Normally these serial numbers are completely ignored by
  3038. @command{aclocal} and @command{autoconf}, like any genuine comment.
  3039. However when using @command{aclocal}'s @option{--install} feature, these
  3040. serial numbers will modify the way @command{aclocal} selects the
  3041. macros to install in the package: if two files with the same basename
  3042. exist in your search path, and if at least one of them uses a
  3043. @samp{#serial} line, @command{aclocal} will ignore the file that has
  3044. the older @samp{#serial} line (or the file that has none).
  3045. Note that a serial number applies to a whole M4 file, not to any macro
  3046. it contains. A file can contains multiple macros, but only one
  3047. serial.
  3048. Here is a use case that illustrates the use of @option{--install} and
  3049. its interaction with serial numbers. Let's assume we maintain a
  3050. package called MyPackage, the @file{configure.ac} of which requires a
  3051. third-party macro @code{AX_THIRD_PARTY} defined in
  3052. @file{/usr/share/aclocal/thirdparty.m4} as follows:
  3053. @example
  3054. # serial 1
  3055. AC_DEFUN([AX_THIRD_PARTY], [...])
  3056. @end example
  3057. MyPackage uses an @file{m4/} directory to store local macros as
  3058. explained in @ref{Local Macros}, and has
  3059. @example
  3060. AC_CONFIG_MACRO_DIRS([m4])
  3061. @end example
  3062. @noindent
  3063. in its @file{configure.ac}.
  3064. Initially the @file{m4/} directory is empty. The first time we run
  3065. @command{aclocal --install}, it will notice that
  3066. @itemize @bullet
  3067. @item
  3068. @file{configure.ac} uses @code{AX_THIRD_PARTY}
  3069. @item
  3070. No local macros define @code{AX_THIRD_PARTY}
  3071. @item
  3072. @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
  3073. with serial 1.
  3074. @end itemize
  3075. @noindent
  3076. Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
  3077. and @command{aclocal} was given the @option{--install} option, it will
  3078. copy this file in @file{m4/thirdparty.m4}, and output an
  3079. @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
  3080. The next time @samp{aclocal --install} is run, something different
  3081. happens. @command{aclocal} notices that
  3082. @itemize @bullet
  3083. @item
  3084. @file{configure.ac} uses @code{AX_THIRD_PARTY}
  3085. @item
  3086. @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
  3087. with serial 1.
  3088. @item
  3089. @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
  3090. with serial 1.
  3091. @end itemize
  3092. @noindent
  3093. Because both files have the same serial number, @command{aclocal} uses
  3094. the first it found in its search path order (@pxref{Macro Search
  3095. Path}). @command{aclocal} therefore ignores
  3096. @file{/usr/share/aclocal/thirdparty.m4} and outputs an
  3097. @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
  3098. Local directories specified with @option{-I} are always searched before
  3099. system-wide directories, so a local file will always be preferred to
  3100. the system-wide file in case of equal serial numbers.
  3101. Now suppose the system-wide third-party macro is changed. This can
  3102. happen if the package installing this macro is updated. Let's suppose
  3103. the new macro has serial number 2. The next time @samp{aclocal --install}
  3104. is run the situation is the following:
  3105. @itemize @bullet
  3106. @item
  3107. @file{configure.ac} uses @code{AX_THIRD_PARTY}
  3108. @item
  3109. @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
  3110. with serial 1.
  3111. @item
  3112. @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
  3113. with serial 2.
  3114. @end itemize
  3115. @noindent
  3116. When @command{aclocal} sees a greater serial number, it immediately
  3117. forgets anything it knows from files that have the same basename and a
  3118. smaller serial number. So after it has found
  3119. @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
  3120. @command{aclocal} will proceed as if it had never seen
  3121. @file{m4/thirdparty.m4}. This brings us back to a situation similar
  3122. to that at the beginning of our example, where no local file defined
  3123. the macro. @command{aclocal} will install the new version of the
  3124. macro in @file{m4/thirdparty.m4}, in this case overriding the old
  3125. version. MyPackage just had its macro updated as a side effect of
  3126. running @command{aclocal}.
  3127. If you are leery of letting @command{aclocal} update your local
  3128. macro, you can run @samp{aclocal --diff} to review the changes
  3129. @samp{aclocal --install} would perform on these macros.
  3130. Finally, note that the @option{--force} option of @command{aclocal} has
  3131. absolutely no effect on the files installed by @option{--install}. For
  3132. instance, if you have modified your local macros, do not expect
  3133. @option{--install --force} to replace the local macros by their
  3134. system-wide versions. If you want to do so, simply erase the local
  3135. macros you want to revert, and run @samp{aclocal --install}.
  3136. @node Future of aclocal
  3137. @subsection The Future of @command{aclocal}
  3138. @cindex @command{aclocal}'s scheduled death
  3139. @command{aclocal} is expected to disappear. This feature really
  3140. should not be offered by Automake. Automake should focus on
  3141. generating @file{Makefile}s; dealing with M4 macros really is
  3142. Autoconf's job. The fact that some people install Automake just to use
  3143. @command{aclocal}, but do not use @command{automake} otherwise is an
  3144. indication of how that feature is misplaced.
  3145. The new implementation will probably be done slightly differently.
  3146. For instance, it could enforce the @file{m4/}-style layout discussed in
  3147. @ref{Local Macros}.
  3148. We have no idea when and how this will happen. This has been
  3149. discussed several times in the past, but someone still has to commit
  3150. to that non-trivial task.
  3151. From the user point of view, @command{aclocal}'s removal might turn
  3152. out to be painful. There is a simple precaution that you may take to
  3153. make that switch more seamless: never call @command{aclocal} yourself.
  3154. Keep this guy under the exclusive control of @command{autoreconf} and
  3155. Automake's rebuild rules. Hopefully you won't need to worry about
  3156. things breaking, when @command{aclocal} disappears, because everything
  3157. will have been taken care of. If otherwise you used to call
  3158. @command{aclocal} directly yourself or from some script, you will
  3159. quickly notice the change.
  3160. Many packages come with a script called @file{bootstrap} or
  3161. @file{autogen.sh}, that will just call @command{aclocal},
  3162. @command{libtoolize}, @command{gettextize} or @command{autopoint},
  3163. @command{autoconf}, @command{autoheader}, and @command{automake} in
  3164. the right order. Actually this is precisely what @command{autoreconf}
  3165. can do for you. If your package has such a @file{bootstrap} or
  3166. @file{autogen.sh} script, consider using @command{autoreconf}. That
  3167. should simplify its logic a lot (less things to maintain, yum!), it's
  3168. even likely you will not need the script anymore, and more to the point
  3169. you will not call @command{aclocal} directly anymore.
  3170. For the time being, third-party packages should continue to install
  3171. public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
  3172. is replaced by another tool it might make sense to rename the
  3173. directory, but supporting @file{/usr/share/aclocal/} for backward
  3174. compatibility should be really easy provided all macros are properly
  3175. written (@pxref{Extending aclocal}).
  3176. @node Macros
  3177. @section Autoconf macros supplied with Automake
  3178. Automake ships with several Autoconf macros that you can use from your
  3179. @file{configure.ac}. When you use one of them it will be included by
  3180. @command{aclocal} in @file{aclocal.m4}.
  3181. @menu
  3182. * Public Macros:: Macros that you can use.
  3183. * Obsolete Macros:: Macros that will soon be removed.
  3184. * Private Macros:: Macros that you should not use.
  3185. @end menu
  3186. @c consider generating the following subsections automatically from m4 files.
  3187. @node Public Macros
  3188. @subsection Public Macros
  3189. @table @code
  3190. @item AM_INIT_AUTOMAKE([OPTIONS])
  3191. @acindex AM_INIT_AUTOMAKE
  3192. Runs many macros required for proper operation of the generated Makefiles.
  3193. @vindex AUTOMAKE_OPTIONS
  3194. Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a
  3195. space-separated list of Automake options that should be applied to
  3196. every @file{Makefile.am} in the tree. The effect is as if
  3197. each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
  3198. @acindex AC_INIT
  3199. This macro can also be called in another, @emph{deprecated} form:
  3200. @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
  3201. there are two required arguments: the package and the version number.
  3202. This usage is mostly obsolete because the @var{package} and @var{version}
  3203. can be obtained from Autoconf's @code{AC_INIT} macro. However,
  3204. differently from what happens for @code{AC_INIT} invocations, this
  3205. @code{AM_INIT_AUTOMAKE} invocation supports shell variables' expansions
  3206. in the @code{PACKAGE} and @code{VERSION} arguments (which otherwise
  3207. defaults, respectively, to the @code{PACKAGE_TARNAME} and
  3208. @code{PACKAGE_VERSION} defined via the @code{AC_INIT} invocation;
  3209. @pxref{AC_INIT, , The @code{AC_INIT} macro, autoconf, The Autoconf Manual});
  3210. and this can be still be useful in some selected situations.
  3211. Our hope is that future Autoconf versions will improve their support
  3212. for package versions defined dynamically at configure runtime; when
  3213. (and if) this happens, support for the two-args @code{AM_INIT_AUTOMAKE}
  3214. invocation will likely be removed from Automake.
  3215. @anchor{Modernize AM_INIT_AUTOMAKE invocation}
  3216. If your @file{configure.ac} has:
  3217. @example
  3218. AC_INIT([src/foo.c])
  3219. AM_INIT_AUTOMAKE([mumble], [1.5])
  3220. @end example
  3221. @noindent
  3222. you should modernize it as follows:
  3223. @example
  3224. AC_INIT([mumble], [1.5])
  3225. AC_CONFIG_SRCDIR([src/foo.c])
  3226. AM_INIT_AUTOMAKE
  3227. @end example
  3228. Note that if you're upgrading your @file{configure.ac} from an earlier
  3229. version of Automake, it is not always correct to simply move the
  3230. package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
  3231. @code{AC_INIT}, as in the example above. The first argument to
  3232. @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
  3233. Automake}), not the tarball name (e.g., @samp{automake}) that you used
  3234. to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
  3235. tarball name from the package name, which should work for most but not
  3236. all package names. (If it doesn't work for yours, you can use the
  3237. four-argument form of @code{AC_INIT} to provide the tarball name
  3238. explicitly).
  3239. @cindex @code{PACKAGE}, prevent definition
  3240. @cindex @code{VERSION}, prevent definition
  3241. @opindex no-define
  3242. By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
  3243. @code{VERSION}. This can be avoided by passing the @option{no-define}
  3244. option (@pxref{List of Automake options}):
  3245. @example
  3246. AM_INIT_AUTOMAKE([no-define ...])
  3247. @end example
  3248. @item AM_PATH_LISPDIR
  3249. @acindex AM_PATH_LISPDIR
  3250. @vindex EMACS
  3251. @vindex lispdir
  3252. Searches for the program @command{emacs}, and, if found, sets the
  3253. output variable @code{lispdir} to the full path to Emacs' site-lisp
  3254. directory.
  3255. Note that this test assumes the @command{emacs} found to be a version
  3256. that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
  3257. emacsen can cause this test to hang (some, like old versions of
  3258. MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
  3259. exit, which is hardly obvious for a non-emacs user). In most cases,
  3260. however, you should be able to use @kbd{C-c} to kill the test. In
  3261. order to avoid problems, you can set @env{EMACS} to ``no'' in the
  3262. environment, or use the @option{--with-lispdir} option to
  3263. @command{configure} to explicitly set the correct path (if you're sure
  3264. you have an @command{emacs} that supports Emacs Lisp).
  3265. @item AM_PROG_AR(@ovar{act-if-fail})
  3266. @acindex AM_PROG_AR
  3267. @vindex AR
  3268. You must use this macro when you use the archiver in your project, if
  3269. you want support for unusual archivers such as Microsoft @command{lib}.
  3270. The content of the optional argument is executed if the archiver
  3271. interface is not recognized; the default action is to abort configure
  3272. with an error message.
  3273. @item AM_PROG_AS
  3274. @acindex AM_PROG_AS
  3275. @vindex CCAS
  3276. @vindex CCASFLAGS
  3277. Use this macro when you have assembly code in your project. This will
  3278. choose the assembler for you (by default the C compiler) and set
  3279. @code{CCAS}, and will also set @code{CCASFLAGS} if required.
  3280. @item AM_PROG_CC_C_O
  3281. @acindex AM_PROG_CC_C_O
  3282. This is an obsolescent macro that checks that the C compiler supports
  3283. the @option{-c} and @option{-o} options together. Note that, since
  3284. Automake 1.14, the @code{AC_PROG_CC} is rewritten to implement such
  3285. checks itself, and thus the explicit use of @code{AM_PROG_CC_C_O}
  3286. should no longer be required.
  3287. @item AM_PROG_LEX
  3288. @acindex AM_PROG_LEX
  3289. @acindex AC_PROG_LEX
  3290. @cindex HP-UX 10, @command{lex} problems
  3291. @cindex @command{lex} problems with HP-UX 10
  3292. Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
  3293. Program Checks, autoconf, The Autoconf Manual}), but uses the
  3294. @command{missing} script on systems that do not have @command{lex}.
  3295. HP-UX 10 is one such system.
  3296. @item AM_PROG_GCJ
  3297. @acindex AM_PROG_GCJ
  3298. @vindex GCJ
  3299. @vindex GCJFLAGS
  3300. This macro finds the @command{gcj} program or causes an error. It sets
  3301. @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
  3302. GNU Compiler Collection.
  3303. @item AM_PROG_UPC([@var{compiler-search-list}])
  3304. @acindex AM_PROG_UPC
  3305. @vindex UPC
  3306. Find a compiler for Unified Parallel C and define the @code{UPC}
  3307. variable. The default @var{compiler-search-list} is @samp{upcc upc}.
  3308. This macro will abort @command{configure} if no Unified Parallel C
  3309. compiler is found.
  3310. @item AM_MISSING_PROG(@var{name}, @var{program})
  3311. @acindex AM_MISSING_PROG
  3312. @vindex MISSING
  3313. Find a maintainer tool @var{program} and define the @var{name}
  3314. environment variable with its location. If @var{program} is not
  3315. detected, then @var{name} will instead invoke the @command{missing}
  3316. script, in order to give useful advice to the user about the missing
  3317. maintainer tool. @xref{maintainer-mode}, for more information on when
  3318. the @command{missing} script is appropriate.
  3319. @item AM_SILENT_RULES
  3320. @acindex AM_SILENT_RULES
  3321. Control the machinery for less verbose build output
  3322. (@pxref{Automake Silent Rules}).
  3323. @item AM_WITH_DMALLOC
  3324. @acindex AM_WITH_DMALLOC
  3325. @cindex @command{dmalloc}, support for
  3326. @vindex WITH_DMALLOC
  3327. @opindex --with-dmalloc
  3328. Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
  3329. the user runs @command{configure} with @option{--with-dmalloc}, then
  3330. define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
  3331. @end table
  3332. @node Obsolete Macros
  3333. @subsection Obsolete Macros
  3334. @cindex obsolete macros
  3335. @cindex autoupdate
  3336. Although using some of the following macros was required in past
  3337. releases, you should not use any of them in new code. @emph{All
  3338. these macros will be removed in the next major Automake version};
  3339. if you are still using them, running @command{autoupdate} should
  3340. adjust your @file{configure.ac} automatically (@pxref{autoupdate
  3341. Invocation, , Using @command{autoupdate} to Modernize
  3342. @file{configure.ac}, autoconf, The Autoconf Manual}).
  3343. @emph{Do it NOW!}
  3344. @table @code
  3345. @item AM_PROG_MKDIR_P
  3346. @acindex AM_PROG_MKDIR_P
  3347. @cindex @code{mkdir -p}, macro check
  3348. @vindex MKDIR_P
  3349. @vindex mkdir_p
  3350. From Automake 1.8 to 1.9.6 this macro used to define the output
  3351. variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
  3352. -d}, or @code{mkinstalldirs}.
  3353. Nowadays Autoconf provides a similar functionality with
  3354. @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
  3355. Program Checks, autoconf, The Autoconf Manual}), however this defines
  3356. the output variable @code{MKDIR_P} instead. In case you are still
  3357. using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac},
  3358. or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am},
  3359. you are advised to switch ASAP to the more modern Autoconf-provided
  3360. interface instead; both the macro and the variable might be removed
  3361. in a future major Automake release.
  3362. @end table
  3363. @node Private Macros
  3364. @subsection Private Macros
  3365. The following macros are private macros you should not call directly.
  3366. They are called by the other public macros when appropriate. Do not
  3367. rely on them, as they might be changed in a future version. Consider
  3368. them as implementation details; or better, do not consider them at all:
  3369. skip this section!
  3370. @ftable @code
  3371. @item _AM_DEPENDENCIES
  3372. @itemx AM_SET_DEPDIR
  3373. @itemx AM_DEP_TRACK
  3374. @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
  3375. These macros are used to implement Automake's automatic dependency
  3376. tracking scheme. They are called automatically by Automake when
  3377. required, and there should be no need to invoke them manually.
  3378. @item AM_MAKE_INCLUDE
  3379. This macro is used to discover how the user's @command{make} handles
  3380. @code{include} statements. This macro is automatically invoked when
  3381. needed; there should be no need to invoke it manually.
  3382. @item AM_PROG_INSTALL_STRIP
  3383. This is used to find a version of @code{install} that can be used to
  3384. strip a program at installation time. This macro is automatically
  3385. included when required.
  3386. @item AM_SANITY_CHECK
  3387. This checks to make sure that a file created in the build directory is
  3388. newer than a file in the source directory. This can fail on systems
  3389. where the clock is set incorrectly. This macro is automatically run
  3390. from @code{AM_INIT_AUTOMAKE}.
  3391. @end ftable
  3392. @node Directories
  3393. @chapter Directories
  3394. For simple projects that distribute all files in the same directory
  3395. it is enough to have a single @file{Makefile.am} that builds
  3396. everything in place.
  3397. In larger projects, it is common to organize files in different
  3398. directories, in a tree. For example, there could be a directory
  3399. for the program's source, one for the testsuite, and one for the
  3400. documentation; or, for very large projects, there could be one
  3401. directory per program, per library or per module.
  3402. The traditional approach is to build these subdirectories recursively,
  3403. employing @emph{make recursion}: each directory contains its
  3404. own @file{Makefile}, and when @command{make} is run from the top-level
  3405. directory, it enters each subdirectory in turn, and invokes there a
  3406. new @command{make} instance to build the directory's contents.
  3407. Because this approach is very widespread, Automake offers built-in
  3408. support for it. However, it is worth nothing that the use of make
  3409. recursion has its own serious issues and drawbacks, and that it's
  3410. well possible to have packages with a multi directory layout that
  3411. make little or no use of such recursion (examples of such packages
  3412. are GNU Bison and GNU Automake itself); see also the @ref{Alternative}
  3413. section below.
  3414. @menu
  3415. * Subdirectories:: Building subdirectories recursively
  3416. * Conditional Subdirectories:: Conditionally not building directories
  3417. * Alternative:: Subdirectories without recursion
  3418. * Subpackages:: Nesting packages
  3419. @end menu
  3420. @node Subdirectories
  3421. @section Recursing subdirectories
  3422. @cindex @code{SUBDIRS}, explained
  3423. In packages using make recursion, the top level @file{Makefile.am} must
  3424. tell Automake which subdirectories are to be built. This is done via
  3425. the @code{SUBDIRS} variable.
  3426. @vindex SUBDIRS
  3427. The @code{SUBDIRS} variable holds a list of subdirectories in which
  3428. building of various sorts can occur. The rules for many targets
  3429. (e.g., @code{all}) in the generated @file{Makefile} will run commands
  3430. both locally and in all specified subdirectories. Note that the
  3431. directories listed in @code{SUBDIRS} are not required to contain
  3432. @file{Makefile.am}s; only @file{Makefile}s (after configuration).
  3433. This allows inclusion of libraries from packages that do not use
  3434. Automake (such as @code{gettext}; see also @ref{Third-Party
  3435. Makefiles}).
  3436. In packages that use subdirectories, the top-level @file{Makefile.am} is
  3437. often very short. For instance, here is the @file{Makefile.am} from the
  3438. GNU Hello distribution:
  3439. @example
  3440. EXTRA_DIST = BUGS ChangeLog.O README-alpha
  3441. SUBDIRS = doc intl po src tests
  3442. @end example
  3443. When Automake invokes @command{make} in a subdirectory, it uses the value
  3444. of the @code{MAKE} variable. It passes the value of the variable
  3445. @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
  3446. @file{Makefile.am} if there are flags you must always pass to
  3447. @command{make}.
  3448. @vindex MAKE
  3449. @vindex AM_MAKEFLAGS
  3450. The directories mentioned in @code{SUBDIRS} are usually direct
  3451. children of the current directory, each subdirectory containing its
  3452. own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
  3453. subdirectories. Automake can be used to construct packages of
  3454. arbitrary depth this way.
  3455. By default, Automake generates @file{Makefiles} that work depth-first
  3456. in postfix order: the subdirectories are built before the current
  3457. directory. However, it is possible to change this ordering. You can
  3458. do this by putting @samp{.} into @code{SUBDIRS}. For instance,
  3459. putting @samp{.} first will cause a prefix ordering of
  3460. directories.
  3461. Using
  3462. @example
  3463. SUBDIRS = lib src . test
  3464. @end example
  3465. @noindent
  3466. will cause @file{lib/} to be built before @file{src/}, then the
  3467. current directory will be built, finally the @file{test/} directory
  3468. will be built. It is customary to arrange test directories to be
  3469. built after everything else since they are meant to test what has
  3470. been constructed.
  3471. In addition to the built-in recursive targets defined by Automake
  3472. (@code{all}, @code{check}, etc.), the developer can also define his
  3473. own recursive targets. That is done by passing the names of such
  3474. targets as arguments to the m4 macro @code{AM_EXTRA_RECURSIVE_TARGETS}
  3475. in @file{configure.ac}. Automake generates rules to handle the
  3476. recursion for such targets; and the developer can define real actions
  3477. for them by defining corresponding @code{-local} targets.
  3478. @example
  3479. % @kbd{cat configure.ac}
  3480. AC_INIT([pkg-name], [1.0]
  3481. AM_INIT_AUTOMAKE
  3482. AM_EXTRA_RECURSIVE_TARGETS([foo])
  3483. AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
  3484. AC_OUTPUT
  3485. % @kbd{cat Makefile.am}
  3486. SUBDIRS = sub
  3487. foo-local:
  3488. @@echo This will be run by "make foo".
  3489. % @kbd{cat sub/Makefile.am}
  3490. SUBDIRS = src
  3491. % @kbd{cat sub/src/Makefile.am}
  3492. foo-local:
  3493. @@echo This too will be run by a "make foo" issued either in
  3494. @@echo the 'sub/src/' directory, the 'sub/' directory, or the
  3495. @@echo top-level directory.
  3496. @end example
  3497. @node Conditional Subdirectories
  3498. @section Conditional Subdirectories
  3499. @cindex Subdirectories, building conditionally
  3500. @cindex Conditional subdirectories
  3501. @cindex @code{SUBDIRS}, conditional
  3502. @cindex Conditional @code{SUBDIRS}
  3503. It is possible to define the @code{SUBDIRS} variable conditionally if,
  3504. like in the case of GNU Inetutils, you want to only build a subset of
  3505. the entire package.
  3506. To illustrate how this works, let's assume we have two directories
  3507. @file{src/} and @file{opt/}. @file{src/} should always be built, but we
  3508. want to decide in @command{configure} whether @file{opt/} will be built
  3509. or not. (For this example we will assume that @file{opt/} should be
  3510. built when the variable @samp{$want_opt} was set to @samp{yes}.)
  3511. Running @command{make} should thus recurse into @file{src/} always, and
  3512. then maybe in @file{opt/}.
  3513. However @samp{make dist} should always recurse into both @file{src/}
  3514. and @file{opt/}. Because @file{opt/} should be distributed even if it
  3515. is not needed in the current configuration. This means
  3516. @file{opt/Makefile} should be created @emph{unconditionally}.
  3517. There are two ways to setup a project like this. You can use Automake
  3518. conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
  3519. variables (@pxref{Setting Output Variables, , Setting Output
  3520. Variables, autoconf, The Autoconf Manual}). Using Automake
  3521. conditionals is the preferred solution. Before we illustrate these
  3522. two possibilities, let's introduce @code{DIST_SUBDIRS}.
  3523. @menu
  3524. * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
  3525. * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
  3526. * Subdirectories with AC_SUBST:: Another way for conditional recursion
  3527. * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
  3528. @end menu
  3529. @node SUBDIRS vs DIST_SUBDIRS
  3530. @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
  3531. @cindex @code{DIST_SUBDIRS}, explained
  3532. Automake considers two sets of directories, defined by the variables
  3533. @code{SUBDIRS} and @code{DIST_SUBDIRS}.
  3534. @code{SUBDIRS} contains the subdirectories of the current directory
  3535. that must be built (@pxref{Subdirectories}). It must be defined
  3536. manually; Automake will never guess a directory is to be built. As we
  3537. will see in the next two sections, it is possible to define it
  3538. conditionally so that some directory will be omitted from the build.
  3539. @code{DIST_SUBDIRS} is used in rules that need to recurse in all
  3540. directories, even those that have been conditionally left out of the
  3541. build. Recall our example where we may not want to build subdirectory
  3542. @file{opt/}, but yet we want to distribute it? This is where
  3543. @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
  3544. @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
  3545. Precisely, @code{DIST_SUBDIRS} is used by @samp{make
  3546. maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
  3547. other recursive rules use @code{SUBDIRS}.
  3548. If @code{SUBDIRS} is defined conditionally using Automake
  3549. conditionals, Automake will define @code{DIST_SUBDIRS} automatically
  3550. from the possible values of @code{SUBDIRS} in all conditions.
  3551. If @code{SUBDIRS} contains @code{AC_SUBST} variables,
  3552. @code{DIST_SUBDIRS} will not be defined correctly because Automake
  3553. does not know the possible values of these variables. In this case
  3554. @code{DIST_SUBDIRS} needs to be defined manually.
  3555. @node Subdirectories with AM_CONDITIONAL
  3556. @subsection Subdirectories with @code{AM_CONDITIONAL}
  3557. @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
  3558. @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
  3559. @c Keep in sync with subdir-am-cond.sh
  3560. @file{configure} should output the @file{Makefile} for each directory
  3561. and define a condition into which @file{opt/} should be built.
  3562. @example
  3563. @dots{}
  3564. AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
  3565. AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
  3566. @dots{}
  3567. @end example
  3568. Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
  3569. as follows.
  3570. @example
  3571. if COND_OPT
  3572. MAYBE_OPT = opt
  3573. endif
  3574. SUBDIRS = src $(MAYBE_OPT)
  3575. @end example
  3576. As you can see, running @command{make} will rightly recurse into
  3577. @file{src/} and maybe @file{opt/}.
  3578. @vindex DIST_SUBDIRS
  3579. As you can't see, running @samp{make dist} will recurse into both
  3580. @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
  3581. @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
  3582. @code{DIST_SUBDIRS} variable.
  3583. In this case Automake will define @samp{DIST_SUBDIRS = src opt}
  3584. automatically because it knows that @code{MAYBE_OPT} can contain
  3585. @samp{opt} in some condition.
  3586. @node Subdirectories with AC_SUBST
  3587. @subsection Subdirectories with @code{AC_SUBST}
  3588. @cindex @code{SUBDIRS} and @code{AC_SUBST}
  3589. @cindex @code{AC_SUBST} and @code{SUBDIRS}
  3590. @c Keep in sync with subdir-ac-subst.sh
  3591. Another possibility is to define @code{MAYBE_OPT} from
  3592. @file{./configure} using @code{AC_SUBST}:
  3593. @example
  3594. @dots{}
  3595. if test "$want_opt" = yes; then
  3596. MAYBE_OPT=opt
  3597. else
  3598. MAYBE_OPT=
  3599. fi
  3600. AC_SUBST([MAYBE_OPT])
  3601. AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
  3602. @dots{}
  3603. @end example
  3604. In this case the top-level @file{Makefile.am} should look as follows.
  3605. @example
  3606. SUBDIRS = src $(MAYBE_OPT)
  3607. DIST_SUBDIRS = src opt
  3608. @end example
  3609. The drawback is that since Automake cannot guess what the possible
  3610. values of @code{MAYBE_OPT} are, it is necessary to define
  3611. @code{DIST_SUBDIRS}.
  3612. @node Unconfigured Subdirectories
  3613. @subsection Unconfigured Subdirectories
  3614. @cindex Subdirectories, configured conditionally
  3615. The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
  3616. users that try to @emph{configure and build} subdirectories
  3617. conditionally. Here by configuring we mean creating the
  3618. @file{Makefile} (it might also involve running a nested
  3619. @command{configure} script: this is a costly operation that explains
  3620. why people want to do it conditionally, but only the @file{Makefile}
  3621. is relevant to the discussion).
  3622. The above examples all assume that every @file{Makefile} is created,
  3623. even in directories that are not going to be built. The simple reason
  3624. is that we want @samp{make dist} to distribute even the directories
  3625. that are not being built (e.g., platform-dependent code), hence
  3626. @file{make dist} must recurse into the subdirectory, hence this
  3627. directory must be configured and appear in @code{DIST_SUBDIRS}.
  3628. Building packages that do not configure every subdirectory is a tricky
  3629. business, and we do not recommend it to the novice as it is easy to
  3630. produce an incomplete tarball by mistake. We will not discuss this
  3631. topic in depth here, yet for the adventurous here are a few rules to
  3632. remember.
  3633. @cartouche
  3634. @itemize
  3635. @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
  3636. It makes little sense to have a directory in @code{SUBDIRS} that
  3637. is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
  3638. which directories listed in the latter should be built.
  3639. @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
  3640. must be configured.
  3641. I.e., the @file{Makefile} must exists or the recursive @command{make}
  3642. rules will not be able to process the directory.
  3643. @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
  3644. So that the cleaning rules remove the generated @file{Makefile}s.
  3645. It would be correct to see @code{DIST_SUBDIRS} as a variable that
  3646. lists all the directories that have been configured.
  3647. @end itemize
  3648. @end cartouche
  3649. In order to prevent recursion in some unconfigured directory you
  3650. must therefore ensure that this directory does not appear in
  3651. @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
  3652. @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
  3653. @code{DIST_SUBDIRS} explicitly, it will be default to
  3654. @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
  3655. = $(SUBDIRS)}.
  3656. Of course, directories that are omitted from @code{DIST_SUBDIRS} will
  3657. not be distributed unless you make other arrangements for this to
  3658. happen (for instance, always running @samp{make dist} in a
  3659. configuration where all directories are known to appear in
  3660. @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
  3661. distribute these directories).
  3662. @cindex Subdirectories, not distributed
  3663. In few packages, unconfigured directories are not even expected to
  3664. be distributed. Although these packages do not require the
  3665. aforementioned extra arrangements, there is another pitfall. If the
  3666. name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
  3667. @command{automake} will make sure the directory exists. Consequently
  3668. @command{automake} cannot be run on such a distribution when one
  3669. directory has been omitted. One way to avoid this check is to use the
  3670. @code{AC_SUBST} method to declare conditional directories; since
  3671. @command{automake} does not know the values of @code{AC_SUBST}
  3672. variables it cannot ensure the corresponding directory exists.
  3673. @node Alternative
  3674. @section An Alternative Approach to Subdirectories
  3675. If you've ever read Peter Miller's excellent paper,
  3676. @uref{http://miller.emu.id.au/pmiller/books/rmch/,
  3677. Recursive Make Considered Harmful}, the preceding sections on the use of
  3678. make recursion will probably come as unwelcome advice. For those who
  3679. haven't read the paper, Miller's main thesis is that recursive
  3680. @command{make} invocations are both slow and error-prone.
  3681. Automake provides sufficient cross-directory support @footnote{We
  3682. believe. This work is new and there are probably warts.
  3683. @xref{Introduction}, for information on reporting bugs.} to enable you
  3684. to write a single @file{Makefile.am} for a complex multi-directory
  3685. package.
  3686. By default an installable file specified in a subdirectory will have its
  3687. directory name stripped before installation. For instance, in this
  3688. example, the header file will be installed as
  3689. @file{$(includedir)/stdio.h}:
  3690. @example
  3691. include_HEADERS = inc/stdio.h
  3692. @end example
  3693. @vindex nobase_
  3694. @cindex @code{nobase_} prefix
  3695. @cindex Path stripping, avoiding
  3696. @cindex Avoiding path stripping
  3697. However, the @samp{nobase_} prefix can be used to circumvent this path
  3698. stripping. In this example, the header file will be installed as
  3699. @file{$(includedir)/sys/types.h}:
  3700. @example
  3701. nobase_include_HEADERS = sys/types.h
  3702. @end example
  3703. @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
  3704. @cindex @code{dist_} and @code{nobase_}
  3705. @cindex @code{nodist_} and @code{nobase_}
  3706. @vindex dist_
  3707. @vindex nodist_
  3708. @samp{nobase_} should be specified first when used in conjunction with
  3709. either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
  3710. Control}). For instance:
  3711. @example
  3712. nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
  3713. @end example
  3714. Finally, note that a variable using the @samp{nobase_} prefix can
  3715. often be replaced by several variables, one for each destination
  3716. directory (@pxref{Uniform}). For instance, the last example could be
  3717. rewritten as follows:
  3718. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  3719. @example
  3720. imagesdir = $(pkgdatadir)/images
  3721. soundsdir = $(pkgdatadir)/sounds
  3722. dist_images_DATA = images/vortex.pgm
  3723. dist_sounds_DATA = sounds/whirl.ogg
  3724. @end example
  3725. @noindent
  3726. This latter syntax makes it possible to change one destination
  3727. directory without changing the layout of the source tree.
  3728. Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
  3729. rule, in that there is no particular installation order guarantee for
  3730. an otherwise equivalent set of variables without @samp{nobase_} prefix.
  3731. @node Subpackages
  3732. @section Nesting Packages
  3733. @cindex Nesting packages
  3734. @cindex Subpackages
  3735. @acindex AC_CONFIG_SUBDIRS
  3736. @acindex AC_CONFIG_AUX_DIR
  3737. In the GNU Build System, packages can be nested to arbitrary depth.
  3738. This means that a package can embed other packages with their own
  3739. @file{configure}, @file{Makefile}s, etc.
  3740. These other packages should just appear as subdirectories of their
  3741. parent package. They must be listed in @code{SUBDIRS} like other
  3742. ordinary directories. However the subpackage's @file{Makefile}s
  3743. should be output by its own @file{configure} script, not by the
  3744. parent's @file{configure}. This is achieved using the
  3745. @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
  3746. AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
  3747. autoconf, The Autoconf Manual}).
  3748. Here is an example package for an @code{arm} program that links with
  3749. a @code{hand} library that is a nested package in subdirectory
  3750. @file{hand/}.
  3751. @code{arm}'s @file{configure.ac}:
  3752. @example
  3753. AC_INIT([arm], [1.0])
  3754. AC_CONFIG_AUX_DIR([.])
  3755. AM_INIT_AUTOMAKE
  3756. AC_PROG_CC
  3757. AC_CONFIG_FILES([Makefile])
  3758. # Call hand's ./configure script recursively.
  3759. AC_CONFIG_SUBDIRS([hand])
  3760. AC_OUTPUT
  3761. @end example
  3762. @code{arm}'s @file{Makefile.am}:
  3763. @example
  3764. # Build the library in the hand subdirectory first.
  3765. SUBDIRS = hand
  3766. # Include hand's header when compiling this directory.
  3767. AM_CPPFLAGS = -I$(srcdir)/hand
  3768. bin_PROGRAMS = arm
  3769. arm_SOURCES = arm.c
  3770. # link with the hand library.
  3771. arm_LDADD = hand/libhand.a
  3772. @end example
  3773. Now here is @code{hand}'s @file{hand/configure.ac}:
  3774. @example
  3775. AC_INIT([hand], [1.2])
  3776. AC_CONFIG_AUX_DIR([.])
  3777. AM_INIT_AUTOMAKE
  3778. AC_PROG_CC
  3779. AM_PROG_AR
  3780. AC_PROG_RANLIB
  3781. AC_CONFIG_FILES([Makefile])
  3782. AC_OUTPUT
  3783. @end example
  3784. @noindent
  3785. and its @file{hand/Makefile.am}:
  3786. @example
  3787. lib_LIBRARIES = libhand.a
  3788. libhand_a_SOURCES = hand.c
  3789. @end example
  3790. When @samp{make dist} is run from the top-level directory it will
  3791. create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
  3792. code as well as the @file{hand} subdirectory. This package can be
  3793. built and installed like any ordinary package, with the usual
  3794. @samp{./configure && make && make install} sequence (the @code{hand}
  3795. subpackage will be built and installed by the process).
  3796. When @samp{make dist} is run from the hand directory, it will create a
  3797. self-contained @file{hand-1.2.tar.gz} archive. So although it appears
  3798. to be embedded in another package, it can still be used separately.
  3799. The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
  3800. force Automake and Autoconf to search for auxiliary scripts in the
  3801. current directory. For instance, this means that there will be two
  3802. copies of @file{install-sh}: one in the top-level of the @code{arm}
  3803. package, and another one in the @file{hand/} subdirectory for the
  3804. @code{hand} package.
  3805. The historical default is to search for these auxiliary scripts in
  3806. the parent directory and the grandparent directory. So if the
  3807. @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
  3808. @file{hand/configure.ac}, that subpackage would share the auxiliary
  3809. script of the @code{arm} package. This may looks like a gain in size
  3810. (a few kilobytes), but it is actually a loss of modularity as the
  3811. @code{hand} subpackage is no longer self-contained (@samp{make dist}
  3812. in the subdirectory will not work anymore).
  3813. Packages that do not use Automake need more work to be integrated this
  3814. way. @xref{Third-Party Makefiles}.
  3815. @node Programs
  3816. @chapter Building Programs and Libraries
  3817. A large part of Automake's functionality is dedicated to making it easy
  3818. to build programs and libraries.
  3819. @menu
  3820. * A Program:: Building a program
  3821. * A Library:: Building a library
  3822. * A Shared Library:: Building a Libtool library
  3823. * Program and Library Variables:: Variables controlling program and
  3824. library builds
  3825. * Default _SOURCES:: Default source files
  3826. * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
  3827. * Program Variables:: Variables used when building a program
  3828. * Yacc and Lex:: Yacc and Lex support
  3829. * C++ Support:: Compiling C++ sources
  3830. * Objective C Support:: Compiling Objective C sources
  3831. * Objective C++ Support:: Compiling Objective C++ sources
  3832. * Unified Parallel C Support:: Compiling Unified Parallel C sources
  3833. * Assembly Support:: Compiling assembly sources
  3834. * Fortran 77 Support:: Compiling Fortran 77 sources
  3835. * Fortran 9x Support:: Compiling Fortran 9x sources
  3836. * Java Support with gcj:: Compiling Java sources using gcj
  3837. * Vala Support:: Compiling Vala sources
  3838. * Support for Other Languages:: Compiling other languages
  3839. * Dependencies:: Automatic dependency tracking
  3840. * EXEEXT:: Support for executable extensions
  3841. @end menu
  3842. @node A Program
  3843. @section Building a program
  3844. In order to build a program, you need to tell Automake which sources
  3845. are part of it, and which libraries it should be linked with.
  3846. This section also covers conditional compilation of sources or
  3847. programs. Most of the comments about these also apply to libraries
  3848. (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
  3849. @menu
  3850. * Program Sources:: Defining program sources
  3851. * Linking:: Linking with libraries or extra objects
  3852. * Conditional Sources:: Handling conditional sources
  3853. * Conditional Programs:: Building a program conditionally
  3854. @end menu
  3855. @node Program Sources
  3856. @subsection Defining program sources
  3857. @cindex @code{PROGRAMS}, @code{bindir}
  3858. @vindex _PROGRAMS
  3859. @vindex bin_PROGRAMS
  3860. @vindex sbin_PROGRAMS
  3861. @vindex libexec_PROGRAMS
  3862. @vindex pkglibexec_PROGRAMS
  3863. @vindex noinst_PROGRAMS
  3864. @vindex check_PROGRAMS
  3865. In a directory containing source that gets built into a program (as
  3866. opposed to a library or a script), the @code{PROGRAMS} primary is used.
  3867. Programs can be installed in @code{bindir}, @code{sbindir},
  3868. @code{libexecdir}, @code{pkglibexecdir}, or not at all
  3869. (@code{noinst_}). They can also be built only for @samp{make check}, in
  3870. which case the prefix is @samp{check_}.
  3871. For instance:
  3872. @example
  3873. bin_PROGRAMS = hello
  3874. @end example
  3875. In this simple case, the resulting @file{Makefile.in} will contain code
  3876. to generate a program named @code{hello}.
  3877. Associated with each program are several assisting variables that are
  3878. named after the program. These variables are all optional, and have
  3879. reasonable defaults. Each variable, its use, and default is spelled out
  3880. below; we use the ``hello'' example throughout.
  3881. The variable @code{hello_SOURCES} is used to specify which source files
  3882. get built into an executable:
  3883. @example
  3884. hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
  3885. @end example
  3886. This causes each mentioned @file{.c} file to be compiled into the
  3887. corresponding @file{.o}. Then all are linked to produce @file{hello}.
  3888. @cindex @code{_SOURCES} primary, defined
  3889. @cindex @code{SOURCES} primary, defined
  3890. @cindex Primary variable, @code{SOURCES}
  3891. @vindex _SOURCES
  3892. If @code{hello_SOURCES} is not specified, then it defaults to the single
  3893. file @file{hello.c} (@pxref{Default _SOURCES}).
  3894. @vindex _SOURCES
  3895. @vindex SOURCES
  3896. Multiple programs can be built in a single directory. Multiple programs
  3897. can share a single source file, which must be listed in each
  3898. @code{_SOURCES} definition.
  3899. @cindex Header files in @code{_SOURCES}
  3900. @cindex @code{_SOURCES} and header files
  3901. Header files listed in a @code{_SOURCES} definition will be included in
  3902. the distribution but otherwise ignored. In case it isn't obvious, you
  3903. should not include the header file generated by @file{configure} in a
  3904. @code{_SOURCES} variable; this file should not be distributed. Lex
  3905. (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
  3906. and Lex}.
  3907. @node Linking
  3908. @subsection Linking the program
  3909. If you need to link against libraries that are not found by
  3910. @command{configure}, you can use @code{LDADD} to do so. This variable is
  3911. used to specify additional objects or libraries to link with; it is
  3912. inappropriate for specifying specific linker flags, you should use
  3913. @code{AM_LDFLAGS} for this purpose.
  3914. @vindex LDADD
  3915. @vindex AM_LDFLAGS
  3916. @cindex @code{prog_LDADD}, defined
  3917. Sometimes, multiple programs are built in one directory but do not share
  3918. the same link-time requirements. In this case, you can use the
  3919. @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
  3920. program as it appears in some @code{_PROGRAMS} variable, and usually
  3921. written in lowercase) to override @code{LDADD}. If this variable exists
  3922. for a given program, then that program is not linked using @code{LDADD}.
  3923. @vindex maude_LDADD
  3924. For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
  3925. linked against the library @file{libcpio.a}. However, @code{rmt} is
  3926. built in the same directory, and has no such link requirement. Also,
  3927. @code{mt} and @code{rmt} are only built on certain architectures. Here
  3928. is what cpio's @file{src/Makefile.am} looks like (abridged):
  3929. @example
  3930. bin_PROGRAMS = cpio pax $(MT)
  3931. libexec_PROGRAMS = $(RMT)
  3932. EXTRA_PROGRAMS = mt rmt
  3933. LDADD = ../lib/libcpio.a $(INTLLIBS)
  3934. rmt_LDADD =
  3935. cpio_SOURCES = @dots{}
  3936. pax_SOURCES = @dots{}
  3937. mt_SOURCES = @dots{}
  3938. rmt_SOURCES = @dots{}
  3939. @end example
  3940. @cindex @code{_LDFLAGS}, defined
  3941. @vindex maude_LDFLAGS
  3942. @code{@var{prog}_LDADD} is inappropriate for passing program-specific
  3943. linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
  3944. @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
  3945. this purpose.
  3946. @cindex @code{_DEPENDENCIES}, defined
  3947. @vindex maude_DEPENDENCIES
  3948. @vindex EXTRA_maude_DEPENDENCIES
  3949. It is also occasionally useful to have a program depend on some other
  3950. target that is not actually part of that program. This can be done
  3951. using either the @code{@var{prog}_DEPENDENCIES} or the
  3952. @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
  3953. the contents both variables, but no further interpretation is done.
  3954. Since these dependencies are associated to the link rule used to
  3955. create the programs they should normally list files used by the link
  3956. command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
  3957. files. In rare cases you may need to add other kinds of files such as
  3958. linker scripts, but @emph{listing a source file in
  3959. @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
  3960. before all the components of a program are built, consider using the
  3961. @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
  3962. If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
  3963. Automake. The automatically-assigned value is the contents of
  3964. @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
  3965. @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
  3966. configure substitutions that are left in are only @samp{$(LIBOBJS)} and
  3967. @samp{$(ALLOCA)}; these are left because it is known that they will not
  3968. cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
  3969. generated.
  3970. @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
  3971. may be used.
  3972. The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
  3973. you merely want to augment the @command{automake}-generated
  3974. @code{@var{prog}_DEPENDENCIES} rather than replacing it.
  3975. @cindex @code{LDADD} and @option{-l}
  3976. @cindex @option{-l} and @code{LDADD}
  3977. We recommend that you avoid using @option{-l} options in @code{LDADD}
  3978. or @code{@var{prog}_LDADD} when referring to libraries built by your
  3979. package. Instead, write the file name of the library explicitly as in
  3980. the above @code{cpio} example. Use @option{-l} only to list
  3981. third-party libraries. If you follow this rule, the default value of
  3982. @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
  3983. omit the other ones.
  3984. @node Conditional Sources
  3985. @subsection Conditional compilation of sources
  3986. You can't put a configure substitution (e.g., @samp{@@FOO@@} or
  3987. @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
  3988. @code{_SOURCES} variable. The reason for this is a bit hard to
  3989. explain, but suffice to say that it simply won't work. Automake will
  3990. give an error if you try to do this.
  3991. Fortunately there are two other ways to achieve the same result. One is
  3992. to use configure substitutions in @code{_LDADD} variables, the other is
  3993. to use an Automake conditional.
  3994. @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
  3995. @cindex @code{EXTRA_prog_SOURCES}, defined
  3996. Automake must know all the source files that could possibly go into a
  3997. program, even if not all the files are built in every circumstance. Any
  3998. files that are only conditionally built should be listed in the
  3999. appropriate @code{EXTRA_} variable. For instance, if
  4000. @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
  4001. in @code{hello}, the @file{Makefile.am} would contain:
  4002. @example
  4003. bin_PROGRAMS = hello
  4004. hello_SOURCES = hello-common.c
  4005. EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
  4006. hello_LDADD = $(HELLO_SYSTEM)
  4007. hello_DEPENDENCIES = $(HELLO_SYSTEM)
  4008. @end example
  4009. @noindent
  4010. You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
  4011. @file{configure.ac}:
  4012. @example
  4013. @dots{}
  4014. case $host in
  4015. *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
  4016. *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
  4017. esac
  4018. AC_SUBST([HELLO_SYSTEM])
  4019. @dots{}
  4020. @end example
  4021. In this case, the variable @code{HELLO_SYSTEM} should be replaced by
  4022. either @file{hello-linux.o} or @file{hello-generic.o}, and added to
  4023. both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
  4024. built and linked in.
  4025. @subsubheading Conditional Compilation using Automake Conditionals
  4026. An often simpler way to compile source files conditionally is to use
  4027. Automake conditionals. For instance, you could use this
  4028. @file{Makefile.am} construct to build the same @file{hello} example:
  4029. @example
  4030. bin_PROGRAMS = hello
  4031. if LINUX
  4032. hello_SOURCES = hello-linux.c hello-common.c
  4033. else
  4034. hello_SOURCES = hello-generic.c hello-common.c
  4035. endif
  4036. @end example
  4037. In this case, @file{configure.ac} should setup the @code{LINUX}
  4038. conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
  4039. When using conditionals like this you don't need to use the
  4040. @code{EXTRA_} variable, because Automake will examine the contents of
  4041. each variable to construct the complete list of source files.
  4042. If your program uses a lot of files, you will probably prefer a
  4043. conditional @samp{+=}.
  4044. @example
  4045. bin_PROGRAMS = hello
  4046. hello_SOURCES = hello-common.c
  4047. if LINUX
  4048. hello_SOURCES += hello-linux.c
  4049. else
  4050. hello_SOURCES += hello-generic.c
  4051. endif
  4052. @end example
  4053. @node Conditional Programs
  4054. @subsection Conditional compilation of programs
  4055. @cindex Conditional programs
  4056. @cindex Programs, conditional
  4057. Sometimes it is useful to determine the programs that are to be built
  4058. at configure time. For instance, GNU @code{cpio} only builds
  4059. @code{mt} and @code{rmt} under special circumstances. The means to
  4060. achieve conditional compilation of programs are the same you can use
  4061. to compile source files conditionally: substitutions or conditionals.
  4062. @subsubheading Conditional Programs using @command{configure} Substitutions
  4063. @vindex EXTRA_PROGRAMS
  4064. @cindex @code{EXTRA_PROGRAMS}, defined
  4065. In this case, you must notify Automake of all the programs that can
  4066. possibly be built, but at the same time cause the generated
  4067. @file{Makefile.in} to use the programs specified by @command{configure}.
  4068. This is done by having @command{configure} substitute values into each
  4069. @code{_PROGRAMS} definition, while listing all optionally built programs
  4070. in @code{EXTRA_PROGRAMS}.
  4071. @example
  4072. bin_PROGRAMS = cpio pax $(MT)
  4073. libexec_PROGRAMS = $(RMT)
  4074. EXTRA_PROGRAMS = mt rmt
  4075. @end example
  4076. As explained in @ref{EXEEXT}, Automake will rewrite
  4077. @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
  4078. @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
  4079. Obviously it cannot rewrite values obtained at run-time through
  4080. @command{configure} substitutions, therefore you should take care of
  4081. appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
  4082. ['mt$@{EXEEXT@}'])}.
  4083. @subsubheading Conditional Programs using Automake Conditionals
  4084. You can also use Automake conditionals (@pxref{Conditionals}) to
  4085. select programs to be built. In this case you don't have to worry
  4086. about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
  4087. @c Keep in sync with exeext.sh
  4088. @example
  4089. bin_PROGRAMS = cpio pax
  4090. if WANT_MT
  4091. bin_PROGRAMS += mt
  4092. endif
  4093. if WANT_RMT
  4094. libexec_PROGRAMS = rmt
  4095. endif
  4096. @end example
  4097. @node A Library
  4098. @section Building a library
  4099. @cindex @code{_LIBRARIES} primary, defined
  4100. @cindex @code{LIBRARIES} primary, defined
  4101. @cindex Primary variable, @code{LIBRARIES}
  4102. @vindex _LIBRARIES
  4103. @vindex lib_LIBRARIES
  4104. @vindex pkglib_LIBRARIES
  4105. @vindex noinst_LIBRARIES
  4106. Building a library is much like building a program. In this case, the
  4107. name of the primary is @code{LIBRARIES}. Libraries can be installed in
  4108. @code{libdir} or @code{pkglibdir}.
  4109. @xref{A Shared Library}, for information on how to build shared
  4110. libraries using libtool and the @code{LTLIBRARIES} primary.
  4111. Each @code{_LIBRARIES} variable is a list of the libraries to be built.
  4112. For instance, to create a library named @file{libcpio.a}, but not install
  4113. it, you would write:
  4114. @example
  4115. noinst_LIBRARIES = libcpio.a
  4116. libcpio_a_SOURCES = @dots{}
  4117. @end example
  4118. The sources that go into a library are determined exactly as they are
  4119. for programs, via the @code{_SOURCES} variables. Note that the library
  4120. name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
  4121. variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
  4122. not @samp{libcpio.a_SOURCES}.
  4123. @vindex maude_LIBADD
  4124. Extra objects can be added to a library using the
  4125. @code{@var{library}_LIBADD} variable. This should be used for objects
  4126. determined by @command{configure}. Again from @code{cpio}:
  4127. @c Keep in sync with pr401c.sh
  4128. @example
  4129. libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
  4130. @end example
  4131. In addition, sources for extra objects that will not exist until
  4132. configure-time must be added to the @code{BUILT_SOURCES} variable
  4133. (@pxref{Sources}).
  4134. Building a static library is done by compiling all object files, then
  4135. by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
  4136. library and the list of objects, and finally by calling
  4137. @samp{$(RANLIB)} on that library. You should call
  4138. @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
  4139. @code{RANLIB} (Automake will complain otherwise). You should also
  4140. call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
  4141. archivers such as Microsoft lib. @code{ARFLAGS} will default to
  4142. @code{cru}; you can override this variable by setting it in your
  4143. @file{Makefile.am} or by @code{AC_SUBST}ing it from your
  4144. @file{configure.ac}. You can override the @code{AR} variable by
  4145. defining a per-library @code{maude_AR} variable (@pxref{Program and
  4146. Library Variables}).
  4147. @cindex Empty libraries
  4148. Be careful when selecting library components conditionally. Because
  4149. building an empty library is not portable, you should ensure that any
  4150. library always contains at least one object.
  4151. To use a static library when building a program, add it to
  4152. @code{LDADD} for this program. In the following example, the program
  4153. @file{cpio} is statically linked with the library @file{libcpio.a}.
  4154. @example
  4155. noinst_LIBRARIES = libcpio.a
  4156. libcpio_a_SOURCES = @dots{}
  4157. bin_PROGRAMS = cpio
  4158. cpio_SOURCES = cpio.c @dots{}
  4159. cpio_LDADD = libcpio.a
  4160. @end example
  4161. @node A Shared Library
  4162. @section Building a Shared Library
  4163. @cindex Shared libraries, support for
  4164. Building shared libraries portably is a relatively complex matter.
  4165. For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
  4166. Libtool Manual}) was created to help build shared libraries in a
  4167. platform-independent way.
  4168. @menu
  4169. * Libtool Concept:: Introducing Libtool
  4170. * Libtool Libraries:: Declaring Libtool Libraries
  4171. * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
  4172. * Conditional Libtool Sources:: Choosing Library Sources Conditionally
  4173. * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
  4174. * Libtool Modules:: Building Libtool Modules
  4175. * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
  4176. * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
  4177. * Libtool Issues:: Common Issues Related to Libtool's Use
  4178. @end menu
  4179. @node Libtool Concept
  4180. @subsection The Libtool Concept
  4181. @cindex @command{libtool}, introduction
  4182. @cindex libtool library, definition
  4183. @cindex suffix @file{.la}, defined
  4184. @cindex @file{.la} suffix, defined
  4185. Libtool abstracts shared and static libraries into a unified concept
  4186. henceforth called @dfn{libtool libraries}. Libtool libraries are
  4187. files using the @file{.la} suffix, and can designate a static library,
  4188. a shared library, or maybe both. Their exact nature cannot be
  4189. determined until @file{./configure} is run: not all platforms support
  4190. all kinds of libraries, and users can explicitly select which
  4191. libraries should be built. (However the package's maintainers can
  4192. tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
  4193. macro, libtool, The Libtool Manual}.)
  4194. @cindex suffix @file{.lo}, defined
  4195. Because object files for shared and static libraries must be compiled
  4196. differently, libtool is also used during compilation. Object files
  4197. built by libtool are called @dfn{libtool objects}: these are files
  4198. using the @file{.lo} suffix. Libtool libraries are built from these
  4199. libtool objects.
  4200. You should not assume anything about the structure of @file{.la} or
  4201. @file{.lo} files and how libtool constructs them: this is libtool's
  4202. concern, and the last thing one wants is to learn about libtool's
  4203. guts. However the existence of these files matters, because they are
  4204. used as targets and dependencies in @file{Makefile}s rules when
  4205. building libtool libraries. There are situations where you may have
  4206. to refer to these, for instance when expressing dependencies for
  4207. building source files conditionally (@pxref{Conditional Libtool
  4208. Sources}).
  4209. @cindex @file{libltdl}, introduction
  4210. People considering writing a plug-in system, with dynamically loaded
  4211. modules, should look into @file{libltdl}: libtool's dlopening library
  4212. (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
  4213. This offers a portable dlopening facility to load libtool libraries
  4214. dynamically, and can also achieve static linking where unavoidable.
  4215. Before we discuss how to use libtool with Automake in details, it
  4216. should be noted that the libtool manual also has a section about how
  4217. to use Automake with libtool (@pxref{Using Automake, , Using Automake
  4218. with Libtool, libtool, The Libtool Manual}).
  4219. @node Libtool Libraries
  4220. @subsection Building Libtool Libraries
  4221. @cindex @code{_LTLIBRARIES} primary, defined
  4222. @cindex @code{LTLIBRARIES} primary, defined
  4223. @cindex Primary variable, @code{LTLIBRARIES}
  4224. @cindex Example of shared libraries
  4225. @vindex lib_LTLIBRARIES
  4226. @vindex pkglib_LTLIBRARIES
  4227. @vindex _LTLIBRARIES
  4228. Automake uses libtool to build libraries declared with the
  4229. @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
  4230. list of libtool libraries to build. For instance, to create a libtool
  4231. library named @file{libgettext.la}, and install it in @code{libdir},
  4232. write:
  4233. @example
  4234. lib_LTLIBRARIES = libgettext.la
  4235. libgettext_la_SOURCES = gettext.c gettext.h @dots{}
  4236. @end example
  4237. Automake predefines the variable @code{pkglibdir}, so you can use
  4238. @code{pkglib_LTLIBRARIES} to install libraries in
  4239. @samp{$(libdir)/@@PACKAGE@@/}.
  4240. If @file{gettext.h} is a public header file that needs to be installed
  4241. in order for people to use the library, it should be declared using a
  4242. @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
  4243. Headers listed in the latter should be internal headers that are not
  4244. part of the public interface.
  4245. @example
  4246. lib_LTLIBRARIES = libgettext.la
  4247. libgettext_la_SOURCES = gettext.c @dots{}
  4248. include_HEADERS = gettext.h @dots{}
  4249. @end example
  4250. A package can build and install such a library along with other
  4251. programs that use it. This dependency should be specified using
  4252. @code{LDADD}. The following example builds a program named
  4253. @file{hello} that is linked with @file{libgettext.la}.
  4254. @example
  4255. lib_LTLIBRARIES = libgettext.la
  4256. libgettext_la_SOURCES = gettext.c @dots{}
  4257. bin_PROGRAMS = hello
  4258. hello_SOURCES = hello.c @dots{}
  4259. hello_LDADD = libgettext.la
  4260. @end example
  4261. @noindent
  4262. Whether @file{hello} is statically or dynamically linked with
  4263. @file{libgettext.la} is not yet known: this will depend on the
  4264. configuration of libtool and the capabilities of the host.
  4265. @node Conditional Libtool Libraries
  4266. @subsection Building Libtool Libraries Conditionally
  4267. @cindex libtool libraries, conditional
  4268. @cindex conditional libtool libraries
  4269. Like conditional programs (@pxref{Conditional Programs}), there are
  4270. two main ways to build conditional libraries: using Automake
  4271. conditionals or using Autoconf @code{AC_SUBST}itutions.
  4272. The important implementation detail you have to be aware of is that
  4273. the place where a library will be installed matters to libtool: it
  4274. needs to be indicated @emph{at link-time} using the @option{-rpath}
  4275. option.
  4276. For libraries whose destination directory is known when Automake runs,
  4277. Automake will automatically supply the appropriate @option{-rpath}
  4278. option to libtool. This is the case for libraries listed explicitly in
  4279. some installable @code{_LTLIBRARIES} variables such as
  4280. @code{lib_LTLIBRARIES}.
  4281. However, for libraries determined at configure time (and thus
  4282. mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
  4283. final installation directory. For such libraries you must add the
  4284. @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
  4285. hand.
  4286. The examples below illustrate the differences between these two methods.
  4287. Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
  4288. variable set at @file{./configure}-time to either @file{libfoo.la},
  4289. @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
  4290. appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
  4291. relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
  4292. the link rule for these two libraries. Therefore the @option{-rpath}
  4293. argument must be explicitly supplied.
  4294. @c Keep in sync with ltcond.sh
  4295. @example
  4296. EXTRA_LTLIBRARIES = libfoo.la libbar.la
  4297. lib_LTLIBRARIES = $(WANTEDLIBS)
  4298. libfoo_la_SOURCES = foo.c @dots{}
  4299. libfoo_la_LDFLAGS = -rpath '$(libdir)'
  4300. libbar_la_SOURCES = bar.c @dots{}
  4301. libbar_la_LDFLAGS = -rpath '$(libdir)'
  4302. @end example
  4303. Here is how the same @file{Makefile.am} would look using Automake
  4304. conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
  4305. Automake is able to compute the @option{-rpath} setting itself, because
  4306. it's clear that both libraries will end up in @samp{$(libdir)} if they
  4307. are installed.
  4308. @c Keep in sync with ltcond.sh
  4309. @example
  4310. lib_LTLIBRARIES =
  4311. if WANT_LIBFOO
  4312. lib_LTLIBRARIES += libfoo.la
  4313. endif
  4314. if WANT_LIBBAR
  4315. lib_LTLIBRARIES += libbar.la
  4316. endif
  4317. libfoo_la_SOURCES = foo.c @dots{}
  4318. libbar_la_SOURCES = bar.c @dots{}
  4319. @end example
  4320. @node Conditional Libtool Sources
  4321. @subsection Libtool Libraries with Conditional Sources
  4322. Conditional compilation of sources in a library can be achieved in the
  4323. same way as conditional compilation of sources in a program
  4324. (@pxref{Conditional Sources}). The only difference is that
  4325. @code{_LIBADD} should be used instead of @code{_LDADD} and that it
  4326. should mention libtool objects (@file{.lo} files).
  4327. So, to mimic the @file{hello} example from @ref{Conditional Sources},
  4328. we could build a @file{libhello.la} library using either
  4329. @file{hello-linux.c} or @file{hello-generic.c} with the following
  4330. @file{Makefile.am}.
  4331. @c Keep in sync with ltcond2.sh
  4332. @example
  4333. lib_LTLIBRARIES = libhello.la
  4334. libhello_la_SOURCES = hello-common.c
  4335. EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
  4336. libhello_la_LIBADD = $(HELLO_SYSTEM)
  4337. libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
  4338. @end example
  4339. @noindent
  4340. And make sure @command{configure} defines @code{HELLO_SYSTEM} as
  4341. either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
  4342. Or we could simply use an Automake conditional as follows.
  4343. @c Keep in sync with ltcond2.sh
  4344. @example
  4345. lib_LTLIBRARIES = libhello.la
  4346. libhello_la_SOURCES = hello-common.c
  4347. if LINUX
  4348. libhello_la_SOURCES += hello-linux.c
  4349. else
  4350. libhello_la_SOURCES += hello-generic.c
  4351. endif
  4352. @end example
  4353. @node Libtool Convenience Libraries
  4354. @subsection Libtool Convenience Libraries
  4355. @cindex convenience libraries, libtool
  4356. @cindex libtool convenience libraries
  4357. @vindex noinst_LTLIBRARIES
  4358. @vindex check_LTLIBRARIES
  4359. Sometimes you want to build libtool libraries that should not be
  4360. installed. These are called @dfn{libtool convenience libraries} and
  4361. are typically used to encapsulate many sublibraries, later gathered
  4362. into one big installed library.
  4363. Libtool convenience libraries are declared by directory-less variables
  4364. such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
  4365. @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
  4366. not need an @option{-rpath} flag at link time (actually this is the only
  4367. difference).
  4368. Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
  4369. built. Those listed in @code{check_LTLIBRARIES} are built only upon
  4370. @samp{make check}. Finally, libraries listed in
  4371. @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
  4372. rules to build them, but if the library does not appear as a Makefile
  4373. dependency anywhere it won't be built (this is why
  4374. @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
  4375. Here is a sample setup merging libtool convenience libraries from
  4376. subdirectories into one main @file{libtop.la} library.
  4377. @c Keep in sync with ltconv.sh
  4378. @example
  4379. # -- Top-level Makefile.am --
  4380. SUBDIRS = sub1 sub2 @dots{}
  4381. lib_LTLIBRARIES = libtop.la
  4382. libtop_la_SOURCES =
  4383. libtop_la_LIBADD = \
  4384. sub1/libsub1.la \
  4385. sub2/libsub2.la \
  4386. @dots{}
  4387. # -- sub1/Makefile.am --
  4388. noinst_LTLIBRARIES = libsub1.la
  4389. libsub1_la_SOURCES = @dots{}
  4390. # -- sub2/Makefile.am --
  4391. # showing nested convenience libraries
  4392. SUBDIRS = sub2.1 sub2.2 @dots{}
  4393. noinst_LTLIBRARIES = libsub2.la
  4394. libsub2_la_SOURCES =
  4395. libsub2_la_LIBADD = \
  4396. sub21/libsub21.la \
  4397. sub22/libsub22.la \
  4398. @dots{}
  4399. @end example
  4400. When using such setup, beware that @command{automake} will assume
  4401. @file{libtop.la} is to be linked with the C linker. This is because
  4402. @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
  4403. default language. If @code{libtop_la_SOURCES} was not empty,
  4404. @command{automake} would select the linker as explained in @ref{How
  4405. the Linker is Chosen}.
  4406. If one of the sublibraries contains non-C source, it is important that
  4407. the appropriate linker be chosen. One way to achieve this is to
  4408. pretend that there is such a non-C file among the sources of the
  4409. library, thus forcing @command{automake} to select the appropriate
  4410. linker. Here is the top-level @file{Makefile} of our example updated
  4411. to force C++ linking.
  4412. @example
  4413. SUBDIRS = sub1 sub2 @dots{}
  4414. lib_LTLIBRARIES = libtop.la
  4415. libtop_la_SOURCES =
  4416. # Dummy C++ source to cause C++ linking.
  4417. nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
  4418. libtop_la_LIBADD = \
  4419. sub1/libsub1.la \
  4420. sub2/libsub2.la \
  4421. @dots{}
  4422. @end example
  4423. @samp{EXTRA_*_SOURCES} variables are used to keep track of source
  4424. files that might be compiled (this is mostly useful when doing
  4425. conditional compilation using @code{AC_SUBST}, @pxref{Conditional
  4426. Libtool Sources}), and the @code{nodist_} prefix means the listed
  4427. sources are not to be distributed (@pxref{Program and Library
  4428. Variables}). In effect the file @file{dummy.cxx} does not need to
  4429. exist in the source tree. Of course if you have some real source file
  4430. to list in @code{libtop_la_SOURCES} there is no point in cheating with
  4431. @code{nodist_EXTRA_libtop_la_SOURCES}.
  4432. @node Libtool Modules
  4433. @subsection Libtool Modules
  4434. @cindex modules, libtool
  4435. @cindex libtool modules
  4436. @cindex @option{-module}, libtool
  4437. These are libtool libraries meant to be dlopened. They are
  4438. indicated to libtool by passing @option{-module} at link-time.
  4439. @example
  4440. pkglib_LTLIBRARIES = mymodule.la
  4441. mymodule_la_SOURCES = doit.c
  4442. mymodule_la_LDFLAGS = -module
  4443. @end example
  4444. Ordinarily, Automake requires that a library's name start with
  4445. @code{lib}. However, when building a dynamically loadable module you
  4446. might wish to use a "nonstandard" name. Automake will not complain
  4447. about such nonstandard names if it knows the library being built is a
  4448. libtool module, i.e., if @option{-module} explicitly appears in the
  4449. library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
  4450. variable when no per-library @code{_LDFLAGS} variable is defined).
  4451. As always, @code{AC_SUBST} variables are black boxes to Automake since
  4452. their values are not yet known when @command{automake} is run.
  4453. Therefore if @option{-module} is set via such a variable, Automake
  4454. cannot notice it and will proceed as if the library was an ordinary
  4455. libtool library, with strict naming.
  4456. If @code{mymodule_la_SOURCES} is not specified, then it defaults to
  4457. the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
  4458. @node Libtool Flags
  4459. @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
  4460. @cindex @code{_LIBADD}, libtool
  4461. @cindex @code{_LDFLAGS}, libtool
  4462. @cindex @code{_LIBTOOLFLAGS}, libtool
  4463. @vindex AM_LIBTOOLFLAGS
  4464. @vindex LIBTOOLFLAGS
  4465. @vindex maude_LIBTOOLFLAGS
  4466. As shown in previous sections, the @samp{@var{library}_LIBADD}
  4467. variable should be used to list extra libtool objects (@file{.lo}
  4468. files) or libtool libraries (@file{.la}) to add to @var{library}.
  4469. The @samp{@var{library}_LDFLAGS} variable is the place to list
  4470. additional libtool linking flags, such as @option{-version-info},
  4471. @option{-static}, and a lot more. @xref{Link mode, , Link mode,
  4472. libtool, The Libtool Manual}.
  4473. The @command{libtool} command has two kinds of options: mode-specific
  4474. options and generic options. Mode-specific options such as the
  4475. aforementioned linking flags should be lumped with the other flags
  4476. passed to the tool invoked by @command{libtool} (hence the use of
  4477. @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
  4478. options include @option{--tag=@var{tag}} and @option{--silent}
  4479. (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
  4480. Libtool Manual} for more options) should appear before the mode
  4481. selection on the command line; in @file{Makefile.am}s they should
  4482. be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
  4483. If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
  4484. @code{AM_LIBTOOLFLAGS} is used instead.
  4485. These flags are passed to libtool after the @option{--tag=@var{tag}}
  4486. option computed by Automake (if any), so
  4487. @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
  4488. good place to override or supplement the @option{--tag=@var{tag}}
  4489. setting.
  4490. The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
  4491. not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
  4492. Variables Ordering}. It allows users to run @samp{make
  4493. LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
  4494. @command{libtool} can also be influenced by the Automake support
  4495. for silent rules (@pxref{Automake Silent Rules}).
  4496. @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
  4497. @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
  4498. @cindex @code{LTLIBOBJS}, special handling
  4499. @cindex @code{LIBOBJS}, and Libtool
  4500. @cindex @code{LTALLOCA}, special handling
  4501. @cindex @code{ALLOCA}, and Libtool
  4502. @vindex LTLIBOBJS
  4503. @vindex LIBOBJS
  4504. @vindex LTALLOCA
  4505. @vindex ALLOCA
  4506. @acindex AC_LIBOBJ
  4507. Where an ordinary library might include @samp{$(LIBOBJS)} or
  4508. @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
  4509. @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
  4510. the object files that libtool operates on do not necessarily end in
  4511. @file{.o}.
  4512. Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
  4513. performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
  4514. @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
  4515. @node Libtool Issues
  4516. @subsection Common Issues Related to Libtool's Use
  4517. @menu
  4518. * Error required file ltmain.sh not found:: The need to run libtoolize
  4519. * Objects created both with libtool and without:: Avoid a specific build race
  4520. @end menu
  4521. @node Error required file ltmain.sh not found
  4522. @subsubsection Error: @samp{required file `./ltmain.sh' not found}
  4523. @cindex @file{ltmain.sh} not found
  4524. @cindex @command{libtoolize}, no longer run by @command{automake}
  4525. @cindex @command{libtoolize} and @command{autoreconf}
  4526. @cindex @command{autoreconf} and @command{libtoolize}
  4527. @cindex @file{bootstrap} and @command{autoreconf}
  4528. @cindex @file{autogen.sh} and @command{autoreconf}
  4529. Libtool comes with a tool called @command{libtoolize} that will
  4530. install libtool's supporting files into a package. Running this
  4531. command will install @file{ltmain.sh}. You should execute it before
  4532. @command{aclocal} and @command{automake}.
  4533. People upgrading old packages to newer autotools are likely to face
  4534. this issue because older Automake versions used to call
  4535. @command{libtoolize}. Therefore old build scripts do not call
  4536. @command{libtoolize}.
  4537. Since Automake 1.6, it has been decided that running
  4538. @command{libtoolize} was none of Automake's business. Instead, that
  4539. functionality has been moved into the @command{autoreconf} command
  4540. (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
  4541. The Autoconf Manual}). If you do not want to remember what to run and
  4542. when, just learn the @command{autoreconf} command. Hopefully,
  4543. replacing existing @file{bootstrap} or @file{autogen.sh} scripts by
  4544. a call to @command{autoreconf} should also free you from any similar
  4545. incompatible change in the future.
  4546. @node Objects created both with libtool and without
  4547. @subsubsection Objects @samp{created with both libtool and without}
  4548. Sometimes, the same source file is used both to build a libtool
  4549. library and to build another non-libtool target (be it a program or
  4550. another library).
  4551. Let's consider the following @file{Makefile.am}.
  4552. @example
  4553. bin_PROGRAMS = prog
  4554. prog_SOURCES = prog.c foo.c @dots{}
  4555. lib_LTLIBRARIES = libfoo.la
  4556. libfoo_la_SOURCES = foo.c @dots{}
  4557. @end example
  4558. @noindent
  4559. (In this trivial case the issue could be avoided by linking
  4560. @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
  4561. @code{prog_SOURCES}. But let's assume we really want to keep
  4562. @file{prog} and @file{libfoo.la} separate.)
  4563. Technically, it means that we should build @file{foo.$(OBJEXT)} for
  4564. @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
  4565. that in the course of creating @file{foo.lo}, libtool may erase (or
  4566. replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
  4567. Therefore, when Automake detects this situation it will complain
  4568. with a message such as
  4569. @example
  4570. object 'foo.$(OBJEXT)' created both with libtool and without
  4571. @end example
  4572. A workaround for this issue is to ensure that these two objects get
  4573. different basenames. As explained in @ref{Renamed Objects}, this
  4574. happens automatically when per-targets flags are used.
  4575. @example
  4576. bin_PROGRAMS = prog
  4577. prog_SOURCES = prog.c foo.c @dots{}
  4578. prog_CFLAGS = $(AM_CFLAGS)
  4579. lib_LTLIBRARIES = libfoo.la
  4580. libfoo_la_SOURCES = foo.c @dots{}
  4581. @end example
  4582. @noindent
  4583. Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
  4584. when the @code{prog_CFLAGS} is defined, it is used instead of
  4585. @code{AM_CFLAGS}. However as a side effect it will cause
  4586. @file{prog.c} and @file{foo.c} to be compiled as
  4587. @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
  4588. the issue.
  4589. @node Program and Library Variables
  4590. @section Program and Library Variables
  4591. Associated with each program is a collection of variables that can be
  4592. used to modify how that program is built. There is a similar list of
  4593. such variables for each library. The canonical name of the program (or
  4594. library) is used as a base for naming these variables.
  4595. In the list below, we use the name ``maude'' to refer to the program or
  4596. library. In your @file{Makefile.am} you would replace this with the
  4597. canonical name of your program. This list also refers to ``maude'' as a
  4598. program, but in general the same rules apply for both static and dynamic
  4599. libraries; the documentation below notes situations where programs and
  4600. libraries differ.
  4601. @vtable @code
  4602. @item maude_SOURCES
  4603. This variable, if it exists, lists all the source files that are
  4604. compiled to build the program. These files are added to the
  4605. distribution by default. When building the program, Automake will cause
  4606. each source file to be compiled to a single @file{.o} file (or
  4607. @file{.lo} when using libtool). Normally these object files are named
  4608. after the source file, but other factors can change this. If a file in
  4609. the @code{_SOURCES} variable has an unrecognized extension, Automake
  4610. will do one of two things with it. If a suffix rule exists for turning
  4611. files with the unrecognized extension into @file{.o} files, then
  4612. @command{automake} will treat this file as it will any other source file
  4613. (@pxref{Support for Other Languages}). Otherwise, the file will be
  4614. ignored as though it were a header file.
  4615. The prefixes @code{dist_} and @code{nodist_} can be used to control
  4616. whether files listed in a @code{_SOURCES} variable are distributed.
  4617. @code{dist_} is redundant, as sources are distributed by default, but it
  4618. can be specified for clarity if desired.
  4619. It is possible to have both @code{dist_} and @code{nodist_} variants of
  4620. a given @code{_SOURCES} variable at once; this lets you easily
  4621. distribute some files and not others, for instance:
  4622. @example
  4623. nodist_maude_SOURCES = nodist.c
  4624. dist_maude_SOURCES = dist-me.c
  4625. @end example
  4626. By default the output file (on Unix systems, the @file{.o} file) will
  4627. be put into the current build directory. However, if the option
  4628. @option{subdir-objects} is in effect in the current directory then the
  4629. @file{.o} file will be put into the subdirectory named after the
  4630. source file. For instance, with @option{subdir-objects} enabled,
  4631. @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
  4632. people prefer this mode of operation. You can specify
  4633. @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
  4634. @cindex Subdirectory, objects in
  4635. @cindex Objects in subdirectory
  4636. @item EXTRA_maude_SOURCES
  4637. Automake needs to know the list of files you intend to compile
  4638. @emph{statically}. For one thing, this is the only way Automake has of
  4639. knowing what sort of language support a given @file{Makefile.in}
  4640. requires. @footnote{There are other, more obscure reasons for
  4641. this limitation as well.} This means that, for example, you can't put a
  4642. configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
  4643. variable. If you intend to conditionally compile source files and use
  4644. @file{configure} to substitute the appropriate object names into, e.g.,
  4645. @code{_LDADD} (see below), then you should list the corresponding source
  4646. files in the @code{EXTRA_} variable.
  4647. This variable also supports @code{dist_} and @code{nodist_} prefixes.
  4648. For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
  4649. sources that may need to be built, but should not be distributed.
  4650. @item maude_AR
  4651. A static library is created by default by invoking @samp{$(AR)
  4652. $(ARFLAGS)} followed by the name of the library and then the objects
  4653. being put into the library. You can override this by setting the
  4654. @code{_AR} variable. This is usually used with C++; some C++
  4655. compilers require a special invocation in order to instantiate all the
  4656. templates that should go into a library. For instance, the SGI C++
  4657. compiler likes this variable set like so:
  4658. @example
  4659. libmaude_a_AR = $(CXX) -ar -o
  4660. @end example
  4661. @item maude_LIBADD
  4662. Extra objects can be added to a @emph{library} using the @code{_LIBADD}
  4663. variable. For instance, this should be used for objects determined by
  4664. @command{configure} (@pxref{A Library}).
  4665. In the case of libtool libraries, @code{maude_LIBADD} can also refer
  4666. to other libtool libraries.
  4667. @item maude_LDADD
  4668. Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
  4669. @file{*.la}) can be added to a @emph{program} by listing them in the
  4670. @code{_LDADD} variable. For instance, this should be used for objects
  4671. determined by @command{configure} (@pxref{Linking}).
  4672. @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
  4673. program-specific linker flags (except for @option{-l}, @option{-L},
  4674. @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
  4675. for this purpose.
  4676. For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
  4677. could link your program against the X libraries like so:
  4678. @example
  4679. maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
  4680. @end example
  4681. We recommend that you use @option{-l} and @option{-L} only when
  4682. referring to third-party libraries, and give the explicit file names
  4683. of any library built by your package. Doing so will ensure that
  4684. @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
  4685. @item maude_LDFLAGS
  4686. This variable is used to pass extra flags to the link step of a program
  4687. or a shared library. It overrides the @code{AM_LDFLAGS} variable.
  4688. @item maude_LIBTOOLFLAGS
  4689. This variable is used to pass extra options to @command{libtool}.
  4690. It overrides the @code{AM_LIBTOOLFLAGS} variable.
  4691. These options are output before @command{libtool}'s @option{--mode=@var{mode}}
  4692. option, so they should not be mode-specific options (those belong to
  4693. the compiler or linker flags). @xref{Libtool Flags}.
  4694. @item maude_DEPENDENCIES
  4695. @itemx EXTRA_maude_DEPENDENCIES
  4696. It is also occasionally useful to have a target (program or library)
  4697. depend on some other file that is not actually part of that target.
  4698. This can be done using the @code{_DEPENDENCIES} variable. Each
  4699. target depends on the contents of such a variable, but no further
  4700. interpretation is done.
  4701. Since these dependencies are associated to the link rule used to
  4702. create the programs they should normally list files used by the link
  4703. command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
  4704. for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
  4705. and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
  4706. may need to add other kinds of files such as linker scripts, but
  4707. @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
  4708. some source file needs to be built before all the components of a
  4709. program are built, consider using the @code{BUILT_SOURCES} variable
  4710. (@pxref{Sources}).
  4711. If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
  4712. The automatically-assigned value is the contents of @code{_LDADD} or
  4713. @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
  4714. @option{-dlopen} and @option{-dlpreopen} options removed. The configure
  4715. substitutions that are left in are only @samp{$(LIBOBJS)} and
  4716. @samp{$(ALLOCA)}; these are left because it is known that they will not
  4717. cause an invalid value for @code{_DEPENDENCIES} to be generated.
  4718. @code{_DEPENDENCIES} is more likely used to perform conditional
  4719. compilation using an @code{AC_SUBST} variable that contains a list of
  4720. objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
  4721. Sources}.
  4722. The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
  4723. you merely want to augment the @command{automake}-generated
  4724. @code{_DEPENDENCIES} variable rather than replacing it.
  4725. @item maude_LINK
  4726. You can override the linker on a per-program basis. By default the
  4727. linker is chosen according to the languages used by the program. For
  4728. instance, a program that includes C++ source code would use the C++
  4729. compiler to link. The @code{_LINK} variable must hold the name of a
  4730. command that can be passed all the @file{.o} file names and libraries
  4731. to link against as arguments. Note that the name of the underlying
  4732. program is @emph{not} passed to @code{_LINK}; typically one uses
  4733. @samp{$@@}:
  4734. @example
  4735. maude_LINK = $(CCLD) -magic -o $@@
  4736. @end example
  4737. If a @code{_LINK} variable is not supplied, it may still be generated
  4738. and used by Automake due to the use of per-target link flags such as
  4739. @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
  4740. they apply.
  4741. @item maude_CCASFLAGS
  4742. @itemx maude_CFLAGS
  4743. @itemx maude_CPPFLAGS
  4744. @itemx maude_CXXFLAGS
  4745. @itemx maude_FFLAGS
  4746. @itemx maude_GCJFLAGS
  4747. @itemx maude_LFLAGS
  4748. @itemx maude_OBJCFLAGS
  4749. @itemx maude_OBJCXXFLAGS
  4750. @itemx maude_RFLAGS
  4751. @itemx maude_UPCFLAGS
  4752. @itemx maude_YFLAGS
  4753. @cindex per-target compilation flags, defined
  4754. Automake allows you to set compilation flags on a per-program (or
  4755. per-library) basis. A single source file can be included in several
  4756. programs, and it will potentially be compiled with different flags for
  4757. each program. This works for any language directly supported by
  4758. Automake. These @dfn{per-target compilation flags} are
  4759. @samp{_CCASFLAGS},
  4760. @samp{_CFLAGS},
  4761. @samp{_CPPFLAGS},
  4762. @samp{_CXXFLAGS},
  4763. @samp{_FFLAGS},
  4764. @samp{_GCJFLAGS},
  4765. @samp{_LFLAGS},
  4766. @samp{_OBJCFLAGS},
  4767. @samp{_OBJCXXFLAGS},
  4768. @samp{_RFLAGS},
  4769. @samp{_UPCFLAGS}, and
  4770. @samp{_YFLAGS}.
  4771. When using a per-target compilation flag, Automake will choose a
  4772. different name for the intermediate object files. Ordinarily a file
  4773. like @file{sample.c} will be compiled to produce @file{sample.o}.
  4774. However, if the program's @code{_CFLAGS} variable is set, then the
  4775. object file will be named, for instance, @file{maude-sample.o}. (See
  4776. also @ref{Renamed Objects}).
  4777. In compilations with per-target flags, the ordinary @samp{AM_} form of
  4778. the flags variable is @emph{not} automatically included in the
  4779. compilation (however, the user form of the variable @emph{is} included).
  4780. So for instance, if you want the hypothetical @file{maude} compilations
  4781. to also use the value of @code{AM_CFLAGS}, you would need to write:
  4782. @example
  4783. maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
  4784. @end example
  4785. @xref{Flag Variables Ordering}, for more discussion about the
  4786. interaction between user variables, @samp{AM_} shadow variables, and
  4787. per-target variables.
  4788. @item maude_SHORTNAME
  4789. On some platforms the allowable file names are very short. In order to
  4790. support these systems and per-target compilation flags at the same
  4791. time, Automake allows you to set a ``short name'' that will influence
  4792. how intermediate object files are named. For instance, in the following
  4793. example,
  4794. @example
  4795. bin_PROGRAMS = maude
  4796. maude_CPPFLAGS = -DSOMEFLAG
  4797. maude_SHORTNAME = m
  4798. maude_SOURCES = sample.c @dots{}
  4799. @end example
  4800. @noindent
  4801. the object file would be named @file{m-sample.o} rather than
  4802. @file{maude-sample.o}.
  4803. This facility is rarely needed in practice,
  4804. and we recommend avoiding it until you find it is required.
  4805. @end vtable
  4806. @node Default _SOURCES
  4807. @section Default @code{_SOURCES}
  4808. @vindex _SOURCES
  4809. @vindex SOURCES
  4810. @cindex @code{_SOURCES}, default
  4811. @cindex default @code{_SOURCES}
  4812. @vindex AM_DEFAULT_SOURCE_EXT
  4813. @code{_SOURCES} variables are used to specify source files of programs
  4814. (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
  4815. libraries (@pxref{A Shared Library}).
  4816. When no such variable is specified for a target, Automake will define
  4817. one itself. The default is to compile a single C file whose base name
  4818. is the name of the target itself, with any extension replaced by
  4819. @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
  4820. For example if you have the following somewhere in your
  4821. @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
  4822. @example
  4823. lib_LIBRARIES = libfoo.a sub/libc++.a
  4824. @end example
  4825. @noindent
  4826. @file{libfoo.a} will be built using a default source file named
  4827. @file{libfoo.c}, and @file{sub/libc++.a} will be built from
  4828. @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
  4829. would be built from @file{sub_libc___a.c}, i.e., the default source
  4830. was the canonized name of the target, with @file{.c} appended.
  4831. We believe the new behavior is more sensible, but for backward
  4832. compatibility @command{automake} will use the old name if a file or a rule
  4833. with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
  4834. @cindex @code{check_PROGRAMS} example
  4835. @vindex check_PROGRAMS
  4836. Default sources are mainly useful in test suites, when building many
  4837. test programs each from a single source. For instance, in
  4838. @example
  4839. check_PROGRAMS = test1 test2 test3
  4840. AM_DEFAULT_SOURCE_EXT = .cpp
  4841. @end example
  4842. @noindent
  4843. @file{test1}, @file{test2}, and @file{test3} will be built
  4844. from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
  4845. Without the last line, they will be built from @file{test1.c},
  4846. @file{test2.c}, and @file{test3.c}.
  4847. @cindex Libtool modules, default source example
  4848. @cindex default source, Libtool modules example
  4849. Another case where this is convenient is building many Libtool modules
  4850. (@file{module@var{n}.la}), each defined in its own file
  4851. (@file{module@var{n}.c}).
  4852. @example
  4853. AM_LDFLAGS = -module
  4854. lib_LTLIBRARIES = module1.la module2.la module3.la
  4855. @end example
  4856. @cindex empty @code{_SOURCES}
  4857. @cindex @code{_SOURCES}, empty
  4858. Finally, there is one situation where this default source computation
  4859. needs to be avoided: when a target should not be built from sources.
  4860. We already saw such an example in @ref{true}; this happens when all
  4861. the constituents of a target have already been compiled and just need
  4862. to be combined using a @code{_LDADD} variable. Then it is necessary
  4863. to define an empty @code{_SOURCES} variable, so that @command{automake}
  4864. does not compute a default.
  4865. @example
  4866. bin_PROGRAMS = target
  4867. target_SOURCES =
  4868. target_LDADD = libmain.a libmisc.a
  4869. @end example
  4870. @node LIBOBJS
  4871. @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
  4872. @cindex @code{LIBOBJS}, example
  4873. @cindex @code{ALLOCA}, example
  4874. @cindex @code{LIBOBJS}, special handling
  4875. @cindex @code{ALLOCA}, special handling
  4876. @vindex LTLIBOBJS
  4877. @vindex LIBOBJS
  4878. @vindex LTALLOCA
  4879. @vindex ALLOCA
  4880. The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
  4881. files that should be compiled into the project to provide an
  4882. implementation for functions that are missing or broken on the host
  4883. system. They are substituted by @file{configure}.
  4884. @acindex AC_LIBOBJ
  4885. These variables are defined by Autoconf macros such as
  4886. @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
  4887. Generic Function Checks, autoconf, The Autoconf Manual}), or
  4888. @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
  4889. Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
  4890. macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
  4891. populate @samp{$(LIBOBJS)}.
  4892. @acindex AC_LIBSOURCE
  4893. Using these variables is very similar to doing conditional compilation
  4894. using @code{AC_SUBST} variables, as described in @ref{Conditional
  4895. Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
  4896. @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
  4897. variable, or to the @samp{*_LIBADD} variable when building a library.
  4898. However there is no need to list the corresponding sources in
  4899. @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
  4900. automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
  4901. dependencies, and it will discover the list of corresponding source
  4902. files automatically (by tracing the invocations of the
  4903. @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
  4904. @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
  4905. either need to add these variables manually, or use
  4906. @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
  4907. These variables are usually used to build a portability library that
  4908. is linked with all the programs of the project. We now review a
  4909. sample setup. First, @file{configure.ac} contains some checks that
  4910. affect either @code{LIBOBJS} or @code{ALLOCA}.
  4911. @example
  4912. # configure.ac
  4913. @dots{}
  4914. AC_CONFIG_LIBOBJ_DIR([lib])
  4915. @dots{}
  4916. AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
  4917. AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
  4918. AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
  4919. AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
  4920. @dots{}
  4921. AC_CONFIG_FILES([
  4922. lib/Makefile
  4923. src/Makefile
  4924. ])
  4925. AC_OUTPUT
  4926. @end example
  4927. @acindex AC_CONFIG_LIBOBJ_DIR
  4928. The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
  4929. of these object files are to be found in the @file{lib/} directory.
  4930. Automake can also use this information, otherwise it expects the
  4931. source files are to be in the directory where the @samp{$(LIBOBJS)}
  4932. and @samp{$(ALLOCA)} variables are used.
  4933. The @file{lib/} directory should therefore contain @file{malloc.c},
  4934. @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
  4935. @file{Makefile.am}:
  4936. @example
  4937. # lib/Makefile.am
  4938. noinst_LIBRARIES = libcompat.a
  4939. libcompat_a_SOURCES =
  4940. libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
  4941. @end example
  4942. The library can have any name, of course, and anyway it is not going
  4943. to be installed: it just holds the replacement versions of the missing
  4944. or broken functions so we can later link them in. Many projects
  4945. also include extra functions, specific to the project, in that
  4946. library: they are simply added on the @code{_SOURCES} line.
  4947. @cindex Empty libraries and @samp{$(LIBOBJS)}
  4948. @cindex @samp{$(LIBOBJS)} and empty libraries
  4949. There is a small trap here, though: @samp{$(LIBOBJS)} and
  4950. @samp{$(ALLOCA)} might be empty, and building an empty library is not
  4951. portable. You should ensure that there is always something to put in
  4952. @file{libcompat.a}. Most projects will also add some utility
  4953. functions in that directory, and list them in
  4954. @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
  4955. be empty.
  4956. Finally here is how this library could be used from the @file{src/}
  4957. directory.
  4958. @example
  4959. # src/Makefile.am
  4960. # Link all programs in this directory with libcompat.a
  4961. LDADD = ../lib/libcompat.a
  4962. bin_PROGRAMS = tool1 tool2 @dots{}
  4963. tool1_SOURCES = @dots{}
  4964. tool2_SOURCES = @dots{}
  4965. @end example
  4966. When option @option{subdir-objects} is not used, as in the above
  4967. example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
  4968. be used in the directory where their sources lie. E.g., here it would
  4969. be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
  4970. @file{src/Makefile.am}. However if both @option{subdir-objects} and
  4971. @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
  4972. in other directories. For instance @file{src/Makefile.am} could be
  4973. changed as follows.
  4974. @example
  4975. # src/Makefile.am
  4976. AUTOMAKE_OPTIONS = subdir-objects
  4977. LDADD = $(LIBOBJS) $(ALLOCA)
  4978. bin_PROGRAMS = tool1 tool2 @dots{}
  4979. tool1_SOURCES = @dots{}
  4980. tool2_SOURCES = @dots{}
  4981. @end example
  4982. Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
  4983. file names that end with @samp{.$(OBJEXT)}, they are not suitable for
  4984. Libtool libraries (where the expected object extension is @file{.lo}):
  4985. @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
  4986. @code{LTLIBOBJS} is defined automatically by Autoconf and should not
  4987. be defined by hand (as in the past), however at the time of writing
  4988. @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
  4989. @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
  4990. autoconf, The Autoconf Manual}.
  4991. @node Program Variables
  4992. @section Variables used when building a program
  4993. Occasionally it is useful to know which @file{Makefile} variables
  4994. Automake uses for compilations, and in which order (@pxref{Flag
  4995. Variables Ordering}); for instance, you might need to do your own
  4996. compilation in some special cases.
  4997. Some variables are inherited from Autoconf; these are @code{CC},
  4998. @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
  4999. @code{LIBS}.
  5000. @vindex CC
  5001. @vindex CFLAGS
  5002. @vindex CPPFLAGS
  5003. @vindex DEFS
  5004. @vindex LDFLAGS
  5005. @vindex LIBS
  5006. There are some additional variables that Automake defines on its own:
  5007. @vtable @code
  5008. @item AM_CPPFLAGS
  5009. The contents of this variable are passed to every compilation that invokes
  5010. the C preprocessor; it is a list of arguments to the preprocessor. For
  5011. instance, @option{-I} and @option{-D} options should be listed here.
  5012. Automake already provides some @option{-I} options automatically, in a
  5013. separate variable that is also passed to every compilation that invokes
  5014. the C preprocessor. In particular it generates @samp{-I.},
  5015. @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
  5016. @file{config.h} (if you've used @code{AC_CONFIG_HEADERS}). You can
  5017. disable the default @option{-I} options using the @option{nostdinc}
  5018. option.
  5019. When a file to be included is generated during the build and not part
  5020. of a distribution tarball, its location is under @code{$(builddir)},
  5021. not under @code{$(srcdir)}. This matters especially for packages that
  5022. use header files placed in sub-directories and want to allow builds
  5023. outside the source tree (@pxref{VPATH Builds}). In that case we
  5024. recommend to use a pair of @option{-I} options, such as, e.g.,
  5025. @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
  5026. @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
  5027. Note that the reference to the build tree should come before the
  5028. reference to the source tree, so that accidentally leftover generated
  5029. files in the source directory are ignored.
  5030. @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
  5031. per-library) @code{_CPPFLAGS} variable if it is defined.
  5032. @item INCLUDES
  5033. This does the same job as @code{AM_CPPFLAGS} (or any per-target
  5034. @code{_CPPFLAGS} variable if it is used). It is an older name for the
  5035. same functionality. This variable is deprecated; we suggest using
  5036. @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
  5037. @item AM_CFLAGS
  5038. This is the variable the @file{Makefile.am} author can use to pass
  5039. in additional C compiler flags. In some situations, this is
  5040. not used, in preference to the per-executable (or per-library)
  5041. @code{_CFLAGS}.
  5042. @item COMPILE
  5043. This is the command used to actually compile a C source file. The
  5044. file name is appended to form the complete command line.
  5045. @item AM_LDFLAGS
  5046. This is the variable the @file{Makefile.am} author can use to pass
  5047. in additional linker flags. In some situations, this is not used, in
  5048. preference to the per-executable (or per-library) @code{_LDFLAGS}.
  5049. @item LINK
  5050. This is the command used to actually link a C program. It already
  5051. includes @samp{-o $@@} and the usual variable references (for instance,
  5052. @code{CFLAGS}); it takes as ``arguments'' the names of the object files
  5053. and libraries to link in. This variable is not used when the linker is
  5054. overridden with a per-target @code{_LINK} variable or per-target flags
  5055. cause Automake to define such a @code{_LINK} variable.
  5056. @end vtable
  5057. @node Yacc and Lex
  5058. @section Yacc and Lex support
  5059. Automake has somewhat idiosyncratic support for Yacc and Lex.
  5060. Automake assumes that the @file{.c} file generated by @command{yacc}
  5061. (or @command{lex}) should be named using the basename of the input
  5062. file. That is, for a yacc source file @file{foo.y}, Automake will
  5063. cause the intermediate file to be named @file{foo.c} (as opposed to
  5064. @file{y.tab.c}, which is more traditional).
  5065. The extension of a yacc source file is used to determine the extension
  5066. of the resulting C or C++ source and header files. Note that header
  5067. files are generated only when the @option{-d} Yacc option is used; see
  5068. below for more information about this flag, and how to specify it.
  5069. Files with the extension @file{.y} will thus be turned into @file{.c}
  5070. sources and @file{.h} headers; likewise, @file{.yy} will become
  5071. @file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
  5072. @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
  5073. and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
  5074. Similarly, lex source files can be used to generate C or C++; the
  5075. extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
  5076. @file{.lpp} are recognized.
  5077. You should never explicitly mention the intermediate (C or C++) file
  5078. in any @code{SOURCES} variable; only list the source file.
  5079. The intermediate files generated by @command{yacc} (or @command{lex})
  5080. will be included in any distribution that is made. That way the user
  5081. doesn't need to have @command{yacc} or @command{lex}.
  5082. If a @command{yacc} source file is seen, then your @file{configure.ac} must
  5083. define the variable @code{YACC}. This is most easily done by invoking
  5084. the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
  5085. Program Checks, autoconf, The Autoconf Manual}).
  5086. @vindex YFLAGS
  5087. @vindex AM_YFLAGS
  5088. When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
  5089. @code{YFLAGS}. The latter is a user variable and the former is
  5090. intended for the @file{Makefile.am} author.
  5091. @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
  5092. @command{yacc}. Automake knows what this means and will automatically
  5093. adjust its rules to update and distribute the header file built by
  5094. @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
  5095. @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
  5096. options; for example, it won't be recognized if @code{AM_YFLAGS} is
  5097. @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
  5098. @option{-t -d}.}.
  5099. What Automake cannot guess, though, is where this
  5100. header will be used: it is up to you to ensure the header gets built
  5101. before it is first used. Typically this is necessary in order for
  5102. dependency tracking to work when the header is included by another
  5103. file. The common solution is listing the header file in
  5104. @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
  5105. @example
  5106. BUILT_SOURCES = parser.h
  5107. AM_YFLAGS = -d
  5108. bin_PROGRAMS = foo
  5109. foo_SOURCES = @dots{} parser.y @dots{}
  5110. @end example
  5111. If a @command{lex} source file is seen, then your @file{configure.ac}
  5112. must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
  5113. to do this (@pxref{Particular Programs, , Particular Program Checks,
  5114. autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
  5115. (@pxref{Macros}) is recommended.
  5116. @vindex LFLAGS
  5117. @vindex AM_LFLAGS
  5118. When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
  5119. @code{LFLAGS}. The latter is a user variable and the former is
  5120. intended for the @file{Makefile.am} author.
  5121. When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
  5122. rebuild rule for distributed Yacc and Lex sources are only used when
  5123. @code{maintainer-mode} is enabled, or when the files have been erased.
  5124. @cindex @command{ylwrap}
  5125. @cindex @command{yacc}, multiple parsers
  5126. @cindex Multiple @command{yacc} parsers
  5127. @cindex Multiple @command{lex} lexers
  5128. @cindex @command{lex}, multiple lexers
  5129. When @command{lex} or @command{yacc} sources are used, @code{automake -a}
  5130. automatically installs an auxiliary program called @command{ylwrap} in
  5131. your package (@pxref{Auxiliary Programs}).
  5132. This program is used by the build rules to rename the output of these
  5133. tools, and makes it possible to include multiple @command{yacc} (or
  5134. @command{lex}) source files in a single directory. (This is necessary
  5135. because yacc's output file name is fixed, and a parallel make could
  5136. conceivably invoke more than one instance of @command{yacc}
  5137. simultaneously.)
  5138. For @command{yacc}, simply managing locking is insufficient. The output of
  5139. @command{yacc} always uses the same symbol names internally, so it isn't
  5140. possible to link two @command{yacc} parsers into the same executable.
  5141. We recommend using the following renaming hack used in @command{gdb}:
  5142. @example
  5143. #define yymaxdepth c_maxdepth
  5144. #define yyparse c_parse
  5145. #define yylex c_lex
  5146. #define yyerror c_error
  5147. #define yylval c_lval
  5148. #define yychar c_char
  5149. #define yydebug c_debug
  5150. #define yypact c_pact
  5151. #define yyr1 c_r1
  5152. #define yyr2 c_r2
  5153. #define yydef c_def
  5154. #define yychk c_chk
  5155. #define yypgo c_pgo
  5156. #define yyact c_act
  5157. #define yyexca c_exca
  5158. #define yyerrflag c_errflag
  5159. #define yynerrs c_nerrs
  5160. #define yyps c_ps
  5161. #define yypv c_pv
  5162. #define yys c_s
  5163. #define yy_yys c_yys
  5164. #define yystate c_state
  5165. #define yytmp c_tmp
  5166. #define yyv c_v
  5167. #define yy_yyv c_yyv
  5168. #define yyval c_val
  5169. #define yylloc c_lloc
  5170. #define yyreds c_reds
  5171. #define yytoks c_toks
  5172. #define yylhs c_yylhs
  5173. #define yylen c_yylen
  5174. #define yydefred c_yydefred
  5175. #define yydgoto c_yydgoto
  5176. #define yysindex c_yysindex
  5177. #define yyrindex c_yyrindex
  5178. #define yygindex c_yygindex
  5179. #define yytable c_yytable
  5180. #define yycheck c_yycheck
  5181. #define yyname c_yyname
  5182. #define yyrule c_yyrule
  5183. @end example
  5184. For each define, replace the @samp{c_} prefix with whatever you like.
  5185. These defines work for @command{bison}, @command{byacc}, and
  5186. traditional @code{yacc}s. If you find a parser generator that uses a
  5187. symbol not covered here, please report the new name so it can be added
  5188. to the list.
  5189. @node C++ Support
  5190. @section C++ Support
  5191. @cindex C++ support
  5192. @cindex Support for C++
  5193. Automake includes full support for C++.
  5194. Any package including C++ code must define the output variable
  5195. @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
  5196. the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
  5197. Program Checks, autoconf, The Autoconf Manual}).
  5198. A few additional variables are defined when a C++ source file is seen:
  5199. @vtable @code
  5200. @item CXX
  5201. The name of the C++ compiler.
  5202. @item CXXFLAGS
  5203. Any flags to pass to the C++ compiler.
  5204. @item AM_CXXFLAGS
  5205. The maintainer's variant of @code{CXXFLAGS}.
  5206. @item CXXCOMPILE
  5207. The command used to actually compile a C++ source file. The file name
  5208. is appended to form the complete command line.
  5209. @item CXXLINK
  5210. The command used to actually link a C++ program.
  5211. @end vtable
  5212. @node Objective C Support
  5213. @section Objective C Support
  5214. @cindex Objective C support
  5215. @cindex Support for Objective C
  5216. Automake includes some support for Objective C.
  5217. Any package including Objective C code must define the output variable
  5218. @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
  5219. the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
  5220. Program Checks, autoconf, The Autoconf Manual}).
  5221. A few additional variables are defined when an Objective C source file
  5222. is seen:
  5223. @vtable @code
  5224. @item OBJC
  5225. The name of the Objective C compiler.
  5226. @item OBJCFLAGS
  5227. Any flags to pass to the Objective C compiler.
  5228. @item AM_OBJCFLAGS
  5229. The maintainer's variant of @code{OBJCFLAGS}.
  5230. @item OBJCCOMPILE
  5231. The command used to actually compile an Objective C source file. The
  5232. file name is appended to form the complete command line.
  5233. @item OBJCLINK
  5234. The command used to actually link an Objective C program.
  5235. @end vtable
  5236. @node Objective C++ Support
  5237. @section Objective C++ Support
  5238. @cindex Objective C++ support
  5239. @cindex Support for Objective C++
  5240. Automake includes some support for Objective C++.
  5241. Any package including Objective C++ code must define the output variable
  5242. @code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use
  5243. the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular
  5244. Program Checks, autoconf, The Autoconf Manual}).
  5245. A few additional variables are defined when an Objective C++ source file
  5246. is seen:
  5247. @vtable @code
  5248. @item OBJCXX
  5249. The name of the Objective C++ compiler.
  5250. @item OBJCXXFLAGS
  5251. Any flags to pass to the Objective C++ compiler.
  5252. @item AM_OBJCXXFLAGS
  5253. The maintainer's variant of @code{OBJCXXFLAGS}.
  5254. @item OBJCXXCOMPILE
  5255. The command used to actually compile an Objective C++ source file. The
  5256. file name is appended to form the complete command line.
  5257. @item OBJCXXLINK
  5258. The command used to actually link an Objective C++ program.
  5259. @end vtable
  5260. @node Unified Parallel C Support
  5261. @section Unified Parallel C Support
  5262. @cindex Unified Parallel C support
  5263. @cindex Support for Unified Parallel C
  5264. Automake includes some support for Unified Parallel C.
  5265. Any package including Unified Parallel C code must define the output
  5266. variable @code{UPC} in @file{configure.ac}; the simplest way to do
  5267. this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
  5268. A few additional variables are defined when a Unified Parallel C
  5269. source file is seen:
  5270. @vtable @code
  5271. @item UPC
  5272. The name of the Unified Parallel C compiler.
  5273. @item UPCFLAGS
  5274. Any flags to pass to the Unified Parallel C compiler.
  5275. @item AM_UPCFLAGS
  5276. The maintainer's variant of @code{UPCFLAGS}.
  5277. @item UPCCOMPILE
  5278. The command used to actually compile a Unified Parallel C source file.
  5279. The file name is appended to form the complete command line.
  5280. @item UPCLINK
  5281. The command used to actually link a Unified Parallel C program.
  5282. @end vtable
  5283. @node Assembly Support
  5284. @section Assembly Support
  5285. Automake includes some support for assembly code. There are two forms
  5286. of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
  5287. (@file{*.S} or @file{*.sx}).
  5288. @vindex CCAS
  5289. @vindex CCASFLAGS
  5290. @vindex CPPFLAGS
  5291. @vindex AM_CCASFLAGS
  5292. @vindex AM_CPPFLAGS
  5293. The variable @code{CCAS} holds the name of the compiler used to build
  5294. assembly code. This compiler must work a bit like a C compiler; in
  5295. particular it must accept @option{-c} and @option{-o}. The values of
  5296. @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
  5297. definition) is passed to the compilation. For preprocessed files,
  5298. @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
  5299. and @code{AM_CPPFLAGS} are also used.
  5300. The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
  5301. @code{CCASFLAGS} for you (unless they are already set, it simply sets
  5302. @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
  5303. flags), but you are free to define these variables by other means.
  5304. Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
  5305. @command{automake} as being files containing assembly code.
  5306. @node Fortran 77 Support
  5307. @comment node-name, next, previous, up
  5308. @section Fortran 77 Support
  5309. @cindex Fortran 77 support
  5310. @cindex Support for Fortran 77
  5311. Automake includes full support for Fortran 77.
  5312. Any package including Fortran 77 code must define the output variable
  5313. @code{F77} in @file{configure.ac}; the simplest way to do this is to use
  5314. the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
  5315. Program Checks, autoconf, The Autoconf Manual}).
  5316. A few additional variables are defined when a Fortran 77 source file is
  5317. seen:
  5318. @vtable @code
  5319. @item F77
  5320. The name of the Fortran 77 compiler.
  5321. @item FFLAGS
  5322. Any flags to pass to the Fortran 77 compiler.
  5323. @item AM_FFLAGS
  5324. The maintainer's variant of @code{FFLAGS}.
  5325. @item RFLAGS
  5326. Any flags to pass to the Ratfor compiler.
  5327. @item AM_RFLAGS
  5328. The maintainer's variant of @code{RFLAGS}.
  5329. @item F77COMPILE
  5330. The command used to actually compile a Fortran 77 source file. The file
  5331. name is appended to form the complete command line.
  5332. @item FLINK
  5333. The command used to actually link a pure Fortran 77 program or shared
  5334. library.
  5335. @end vtable
  5336. Automake can handle preprocessing Fortran 77 and Ratfor source files in
  5337. addition to compiling them@footnote{Much, if not most, of the
  5338. information in the following sections pertaining to preprocessing
  5339. Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
  5340. Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
  5341. also contains some support for creating programs and shared libraries
  5342. that are a mixture of Fortran 77 and other languages (@pxref{Mixing
  5343. Fortran 77 With C and C++}).
  5344. These issues are covered in the following sections.
  5345. @menu
  5346. * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
  5347. * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
  5348. * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
  5349. @end menu
  5350. @node Preprocessing Fortran 77
  5351. @comment node-name, next, previous, up
  5352. @subsection Preprocessing Fortran 77
  5353. @cindex Preprocessing Fortran 77
  5354. @cindex Fortran 77, Preprocessing
  5355. @cindex Ratfor programs
  5356. @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
  5357. rule runs just the preprocessor to convert a preprocessable Fortran 77
  5358. or Ratfor source file into a strict Fortran 77 source file. The precise
  5359. command used is as follows:
  5360. @table @file
  5361. @item .F
  5362. @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
  5363. $(AM_FFLAGS) $(FFLAGS)}
  5364. @item .r
  5365. @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
  5366. @end table
  5367. @node Compiling Fortran 77 Files
  5368. @comment node-name, next, previous, up
  5369. @subsection Compiling Fortran 77 Files
  5370. @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
  5371. @file{N.r} by running the Fortran 77 compiler. The precise command used
  5372. is as follows:
  5373. @table @file
  5374. @item .f
  5375. @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
  5376. @item .F
  5377. @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
  5378. $(AM_FFLAGS) $(FFLAGS)}
  5379. @item .r
  5380. @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
  5381. @end table
  5382. @node Mixing Fortran 77 With C and C++
  5383. @comment node-name, next, previous, up
  5384. @subsection Mixing Fortran 77 With C and C++
  5385. @cindex Fortran 77, mixing with C and C++
  5386. @cindex Mixing Fortran 77 with C and C++
  5387. @cindex Linking Fortran 77 with C and C++
  5388. @cindex cfortran
  5389. @cindex Mixing Fortran 77 with C and/or C++
  5390. Automake currently provides @emph{limited} support for creating programs
  5391. and shared libraries that are a mixture of Fortran 77 and C and/or C++.
  5392. However, there are many other issues related to mixing Fortran 77 with
  5393. other languages that are @emph{not} (currently) handled by Automake, but
  5394. that are handled by other packages@footnote{For example,
  5395. @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
  5396. addresses all of these inter-language issues, and runs under nearly all
  5397. Fortran 77, C and C++ compilers on nearly all platforms. However,
  5398. @command{cfortran} is not yet Free Software, but it will be in the next
  5399. major release.}.
  5400. Automake can help in two ways:
  5401. @enumerate
  5402. @item
  5403. Automatic selection of the linker depending on which combinations of
  5404. source code.
  5405. @item
  5406. Automatic selection of the appropriate linker flags (e.g., @option{-L} and
  5407. @option{-l}) to pass to the automatically selected linker in order to link
  5408. in the appropriate Fortran 77 intrinsic and run-time libraries.
  5409. @cindex @code{FLIBS}, defined
  5410. @vindex FLIBS
  5411. These extra Fortran 77 linker flags are supplied in the output variable
  5412. @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
  5413. @xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
  5414. The Autoconf Manual}.
  5415. @end enumerate
  5416. If Automake detects that a program or shared library (as mentioned in
  5417. some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
  5418. code that is a mixture of Fortran 77 and C and/or C++, then it requires
  5419. that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
  5420. @file{configure.ac}, and that either @code{$(FLIBS)}
  5421. appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
  5422. (for shared libraries) variables. It is the responsibility of the
  5423. person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
  5424. appears in the appropriate @code{_LDADD} or
  5425. @code{_LIBADD} variable.
  5426. @cindex Mixed language example
  5427. @cindex Example, mixed language
  5428. For example, consider the following @file{Makefile.am}:
  5429. @example
  5430. bin_PROGRAMS = foo
  5431. foo_SOURCES = main.cc foo.f
  5432. foo_LDADD = libfoo.la $(FLIBS)
  5433. pkglib_LTLIBRARIES = libfoo.la
  5434. libfoo_la_SOURCES = bar.f baz.c zardoz.cc
  5435. libfoo_la_LIBADD = $(FLIBS)
  5436. @end example
  5437. In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
  5438. is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
  5439. been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
  5440. Automake would have issued a warning.
  5441. @menu
  5442. * How the Linker is Chosen:: Automatic linker selection
  5443. @end menu
  5444. @node How the Linker is Chosen
  5445. @comment node-name, next, previous, up
  5446. @subsubsection How the Linker is Chosen
  5447. @cindex Automatic linker selection
  5448. @cindex Selecting the linker automatically
  5449. When a program or library mixes several languages, Automake choose the
  5450. linker according to the following priorities. (The names in
  5451. parentheses are the variables containing the link command.)
  5452. @enumerate
  5453. @item
  5454. @vindex GCJLINK
  5455. Native Java (@code{GCJLINK})
  5456. @item
  5457. @vindex OBJCXXLINK
  5458. Objective C++ (@code{OBJCXXLINK})
  5459. @item
  5460. @vindex CXXLINK
  5461. C++ (@code{CXXLINK})
  5462. @item
  5463. @vindex F77LINK
  5464. Fortran 77 (@code{F77LINK})
  5465. @item
  5466. @vindex FCLINK
  5467. Fortran (@code{FCLINK})
  5468. @item
  5469. @vindex OBJCLINK
  5470. Objective C (@code{OBJCLINK})
  5471. @item
  5472. @vindex UPCLINK
  5473. Unified Parallel C (@code{UPCLINK})
  5474. @item
  5475. @vindex LINK
  5476. C (@code{LINK})
  5477. @end enumerate
  5478. For example, if Fortran 77, C and C++ source code is compiled
  5479. into a program, then the C++ linker will be used. In this case, if the
  5480. C or Fortran 77 linkers required any special libraries that weren't
  5481. included by the C++ linker, then they must be manually added to an
  5482. @code{_LDADD} or @code{_LIBADD} variable by the user writing the
  5483. @file{Makefile.am}.
  5484. Automake only looks at the file names listed in @file{_SOURCES}
  5485. variables to choose the linker, and defaults to the C linker.
  5486. Sometimes this is inconvenient because you are linking against a
  5487. library written in another language and would like to set the linker
  5488. more appropriately. @xref{Libtool Convenience Libraries}, for a
  5489. trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
  5490. A per-target @code{_LINK} variable will override the above selection.
  5491. Per-target link flags will cause Automake to write a per-target
  5492. @code{_LINK} variable according to the language chosen as above.
  5493. @node Fortran 9x Support
  5494. @comment node-name, next, previous, up
  5495. @section Fortran 9x Support
  5496. @cindex Fortran 9x support
  5497. @cindex Support for Fortran 9x
  5498. Automake includes support for Fortran 9x.
  5499. Any package including Fortran 9x code must define the output variable
  5500. @code{FC} in @file{configure.ac}; the simplest way to do this is to use
  5501. the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
  5502. Program Checks, autoconf, The Autoconf Manual}).
  5503. A few additional variables are defined when a Fortran 9x source file is
  5504. seen:
  5505. @vtable @code
  5506. @item FC
  5507. The name of the Fortran 9x compiler.
  5508. @item FCFLAGS
  5509. Any flags to pass to the Fortran 9x compiler.
  5510. @item AM_FCFLAGS
  5511. The maintainer's variant of @code{FCFLAGS}.
  5512. @item FCCOMPILE
  5513. The command used to actually compile a Fortran 9x source file. The file
  5514. name is appended to form the complete command line.
  5515. @item FCLINK
  5516. The command used to actually link a pure Fortran 9x program or shared
  5517. library.
  5518. @end vtable
  5519. @menu
  5520. * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
  5521. @end menu
  5522. @node Compiling Fortran 9x Files
  5523. @comment node-name, next, previous, up
  5524. @subsection Compiling Fortran 9x Files
  5525. @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
  5526. @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
  5527. by running the Fortran 9x compiler. The precise command used
  5528. is as follows:
  5529. @table @file
  5530. @item .f90
  5531. @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
  5532. @item .f95
  5533. @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
  5534. @item .f03
  5535. @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
  5536. @item .f08
  5537. @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
  5538. @end table
  5539. @node Java Support with gcj
  5540. @comment node-name, next, previous, up
  5541. @section Compiling Java sources using gcj
  5542. @cindex Java support with gcj
  5543. @cindex Support for Java with gcj
  5544. @cindex Java to native code, compilation
  5545. @cindex Compilation of Java to native code
  5546. Automake includes support for natively compiled Java, using @command{gcj},
  5547. the Java front end to the GNU Compiler Collection (rudimentary support
  5548. for compiling Java to bytecode using the @command{javac} compiler is
  5549. also present, @emph{albeit deprecated}; @pxref{Java}).
  5550. Any package including Java code to be compiled must define the output
  5551. variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
  5552. must also be defined somehow (either in @file{configure.ac} or
  5553. @file{Makefile.am}). The simplest way to do this is to use the
  5554. @code{AM_PROG_GCJ} macro.
  5555. @vindex GCJFLAGS
  5556. By default, programs including Java source files are linked with
  5557. @command{gcj}.
  5558. As always, the contents of @code{AM_GCJFLAGS} are passed to every
  5559. compilation invoking @command{gcj} (in its role as an ahead-of-time
  5560. compiler, when invoking it to create @file{.class} files,
  5561. @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
  5562. options to @command{gcj} from @file{Makefile.am}, this variable, and not
  5563. the user variable @code{GCJFLAGS}, should be used.
  5564. @vindex AM_GCJFLAGS
  5565. @command{gcj} can be used to compile @file{.java}, @file{.class},
  5566. @file{.zip}, or @file{.jar} files.
  5567. When linking, @command{gcj} requires that the main class be specified
  5568. using the @option{--main=} option. The easiest way to do this is to use
  5569. the @code{_LDFLAGS} variable for the program.
  5570. @node Vala Support
  5571. @comment node-name, next, previous, up
  5572. @section Vala Support
  5573. @cindex Vala Support
  5574. @cindex Support for Vala
  5575. Automake provides initial support for Vala
  5576. (@uref{http://www.vala-project.org/}).
  5577. This requires valac version 0.7.0 or later, and currently requires
  5578. the user to use GNU @command{make}.
  5579. @example
  5580. foo_SOURCES = foo.vala bar.vala zardoc.c
  5581. @end example
  5582. Any @file{.vala} file listed in a @code{_SOURCES} variable will be
  5583. compiled into C code by the Vala compiler. The generated @file{.c} files
  5584. are distributed. The end user does not need to have a Vala compiler installed.
  5585. Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
  5586. that will locate the Vala compiler and optionally check its version
  5587. number.
  5588. @defmac AM_PROG_VALAC (@ovar{minimum-version}, @ovar{action-if-found},
  5589. @ovar{action-if-not-found})
  5590. Search for a Vala compiler in @env{PATH}. If it is found, the variable
  5591. @code{VALAC} is set to point to it (see below for more details). This
  5592. macro takes three optional arguments. The first argument, if present,
  5593. is the minimum version of the Vala compiler required to compile this
  5594. package. If a compiler is found and satisfies @var{minimum-version},
  5595. then @var{action-if-found} is run (this defaults to do nothing).
  5596. Otherwise, @var{action-if-not-found} is run. If @var{action-if-not-found}
  5597. is not specified, the default value is to print a warning in case no
  5598. compiler is found, or if a too-old version of the compiler is found.
  5599. @end defmac
  5600. There are a few variables that are used when compiling Vala sources:
  5601. @vtable @code
  5602. @item VALAC
  5603. Absolute path to the Vala compiler, or simply @samp{valac} if no
  5604. suitable compiler Vala could be found at configure runtime.
  5605. @item VALAFLAGS
  5606. Additional arguments for the Vala compiler.
  5607. @item AM_VALAFLAGS
  5608. The maintainer's variant of @code{VALAFLAGS}.
  5609. @example
  5610. lib_LTLIBRARIES = libfoo.la
  5611. libfoo_la_SOURCES = foo.vala
  5612. @end example
  5613. @end vtable
  5614. Note that currently, you cannot use per-target @code{*_VALAFLAGS}
  5615. (@pxref{Renamed Objects}) to produce different C files from one Vala
  5616. source file.
  5617. @node Support for Other Languages
  5618. @comment node-name, next, previous, up
  5619. @section Support for Other Languages
  5620. Automake currently only includes full support for C, C++ (@pxref{C++
  5621. Support}), Objective C (@pxref{Objective C Support}),
  5622. Objective C++ (@pxref{Objective C++ Support}),
  5623. Fortran 77
  5624. (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
  5625. and Java (@pxref{Java Support with gcj}). There is only rudimentary
  5626. support for other languages, support for which will be improved based
  5627. on user demand.
  5628. Some limited support for adding your own languages is available via the
  5629. suffix rule handling (@pxref{Suffixes}).
  5630. @node Dependencies
  5631. @section Automatic dependency tracking
  5632. As a developer it is often painful to continually update the
  5633. @file{Makefile.am} whenever the include-file dependencies change in a
  5634. project. Automake supplies a way to automatically track dependency
  5635. changes (@pxref{Dependency Tracking}).
  5636. @cindex Dependency tracking
  5637. @cindex Automatic dependency tracking
  5638. Automake always uses complete dependencies for a compilation,
  5639. including system headers. Automake's model is that dependency
  5640. computation should be a side effect of the build. To this end,
  5641. dependencies are computed by running all compilations through a
  5642. special wrapper program called @command{depcomp}. @command{depcomp}
  5643. understands how to coax many different C and C++ compilers into
  5644. generating dependency information in the format it requires.
  5645. @samp{automake -a} will install @command{depcomp} into your source
  5646. tree for you. If @command{depcomp} can't figure out how to properly
  5647. invoke your compiler, dependency tracking will simply be disabled for
  5648. your build.
  5649. @cindex @command{depcomp}
  5650. Experience with earlier versions of Automake (@pxref{Dependency Tracking
  5651. Evolution, , Dependency Tracking Evolution, automake-history, Brief History
  5652. of Automake}) taught us that it is not reliable to generate dependencies
  5653. only on the maintainer's system, as configurations vary too much. So
  5654. instead Automake implements dependency tracking at build time.
  5655. Automatic dependency tracking can be suppressed by putting
  5656. @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
  5657. passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
  5658. (this should be the preferred way). Or, you can invoke @command{automake}
  5659. with the @option{-i} option. Dependency tracking is enabled by default.
  5660. @vindex AUTOMAKE_OPTIONS
  5661. @opindex no-dependencies
  5662. The person building your package also can choose to disable dependency
  5663. tracking by configuring with @option{--disable-dependency-tracking}.
  5664. @cindex Disabling dependency tracking
  5665. @cindex Dependency tracking, disabling
  5666. @node EXEEXT
  5667. @section Support for executable extensions
  5668. @cindex Executable extension
  5669. @cindex Extension, executable
  5670. @cindex Windows
  5671. On some platforms, such as Windows, executables are expected to have an
  5672. extension such as @file{.exe}. On these platforms, some compilers (GCC
  5673. among them) will automatically generate @file{foo.exe} when asked to
  5674. generate @file{foo}.
  5675. Automake provides mostly-transparent support for this. Unfortunately
  5676. @emph{mostly} doesn't yet mean @emph{fully}. Until the English
  5677. dictionary is revised, you will have to assist Automake if your package
  5678. must support those platforms.
  5679. One thing you must be aware of is that, internally, Automake rewrites
  5680. something like this:
  5681. @example
  5682. bin_PROGRAMS = liver
  5683. @end example
  5684. to this:
  5685. @example
  5686. bin_PROGRAMS = liver$(EXEEXT)
  5687. @end example
  5688. The targets Automake generates are likewise given the @samp{$(EXEEXT)}
  5689. extension.
  5690. The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
  5691. are also rewritten if they contain filenames that have been declared as
  5692. programs in the same @file{Makefile}. (This is mostly useful when some
  5693. programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
  5694. However, Automake cannot apply this rewriting to @command{configure}
  5695. substitutions. This means that if you are conditionally building a
  5696. program using such a substitution, then your @file{configure.ac} must
  5697. take care to add @samp{$(EXEEXT)} when constructing the output variable.
  5698. Sometimes maintainers like to write an explicit link rule for their
  5699. program. Without executable extension support, this is easy---you
  5700. simply write a rule whose target is the name of the program. However,
  5701. when executable extension support is enabled, you must instead add the
  5702. @samp{$(EXEEXT)} suffix.
  5703. This might be a nuisance for maintainers who know their package will
  5704. never run on a platform that has
  5705. executable extensions. For those maintainers, the @option{no-exeext}
  5706. option (@pxref{Options}) will disable this feature. This works in a
  5707. fairly ugly way; if @option{no-exeext} is seen, then the presence of a
  5708. rule for a target named @code{foo} in @file{Makefile.am} will override
  5709. an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
  5710. the @option{no-exeext} option, this use will give a diagnostic.
  5711. @node Other Objects
  5712. @chapter Other Derived Objects
  5713. Automake can handle derived objects that are not C programs. Sometimes
  5714. the support for actually building such objects must be explicitly
  5715. supplied, but Automake will still automatically handle installation and
  5716. distribution.
  5717. @menu
  5718. * Scripts:: Executable scripts
  5719. * Headers:: Header files
  5720. * Data:: Architecture-independent data files
  5721. * Sources:: Derived sources
  5722. @end menu
  5723. @node Scripts
  5724. @section Executable Scripts
  5725. @cindex @code{_SCRIPTS} primary, defined
  5726. @cindex @code{SCRIPTS} primary, defined
  5727. @cindex Primary variable, @code{SCRIPTS}
  5728. @vindex _SCRIPTS
  5729. @cindex Installing scripts
  5730. It is possible to define and install programs that are scripts. Such
  5731. programs are listed using the @code{SCRIPTS} primary name. When the
  5732. script is distributed in its final, installable form, the
  5733. @file{Makefile} usually looks as follows:
  5734. @vindex SCRIPTS
  5735. @example
  5736. # Install my_script in $(bindir) and distribute it.
  5737. dist_bin_SCRIPTS = my_script
  5738. @end example
  5739. Scripts are not distributed by default; as we have just seen, those
  5740. that should be distributed can be specified using a @code{dist_}
  5741. prefix as with other primaries.
  5742. @cindex @code{SCRIPTS}, installation directories
  5743. @vindex bin_SCRIPTS
  5744. @vindex sbin_SCRIPTS
  5745. @vindex libexec_SCRIPTS
  5746. @vindex pkgdata_SCRIPTS
  5747. @vindex pkglibexec_SCRIPTS
  5748. @vindex noinst_SCRIPTS
  5749. @vindex check_SCRIPTS
  5750. Scripts can be installed in @code{bindir}, @code{sbindir},
  5751. @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
  5752. Scripts that need not be installed can be listed in
  5753. @code{noinst_SCRIPTS}, and among them, those which are needed only by
  5754. @samp{make check} should go in @code{check_SCRIPTS}.
  5755. When a script needs to be built, the @file{Makefile.am} should include
  5756. the appropriate rules. For instance the @command{automake} program
  5757. itself is a Perl script that is generated from @file{automake.in}.
  5758. Here is how this is handled:
  5759. @example
  5760. bin_SCRIPTS = automake
  5761. CLEANFILES = $(bin_SCRIPTS)
  5762. EXTRA_DIST = automake.in
  5763. do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
  5764. -e 's,[@@]PERL[@@],$(PERL),g' \
  5765. -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
  5766. -e 's,[@@]VERSION[@@],$(VERSION),g' \
  5767. @dots{}
  5768. automake: automake.in Makefile
  5769. $(do_subst) < $(srcdir)/automake.in > automake
  5770. chmod +x automake
  5771. @end example
  5772. Such scripts for which a build rule has been supplied need to be
  5773. deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
  5774. sources have to be distributed, usually with @code{EXTRA_DIST}
  5775. (@pxref{Basics of Distribution}).
  5776. Another common way to build scripts is to process them from
  5777. @file{configure} with @code{AC_CONFIG_FILES}. In this situation
  5778. Automake knows which files should be cleaned and distributed, and what
  5779. the rebuild rules should look like.
  5780. For instance if @file{configure.ac} contains
  5781. @example
  5782. AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
  5783. @end example
  5784. @noindent
  5785. to build @file{src/my_script} from @file{src/my_script.in}, then a
  5786. @file{src/Makefile.am} to install this script in @code{$(bindir)} can
  5787. be as simple as
  5788. @example
  5789. bin_SCRIPTS = my_script
  5790. CLEANFILES = $(bin_SCRIPTS)
  5791. @end example
  5792. @noindent
  5793. There is no need for @code{EXTRA_DIST} or any build rule: Automake
  5794. infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
  5795. @code{CLEANFILES} is still useful, because by default Automake will
  5796. clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
  5797. @code{clean}.
  5798. Although this looks simpler, building scripts this way has one
  5799. drawback: directory variables such as @code{$(datadir)} are not fully
  5800. expanded and may refer to other directory variables.
  5801. @node Headers
  5802. @section Header files
  5803. @cindex @code{_HEADERS} primary, defined
  5804. @cindex @code{HEADERS} primary, defined
  5805. @cindex Primary variable, @code{HEADERS}
  5806. @vindex _HEADERS
  5807. @vindex noinst_HEADERS
  5808. @cindex @code{HEADERS}, installation directories
  5809. @cindex Installing headers
  5810. @vindex include_HEADERS
  5811. @vindex oldinclude_HEADERS
  5812. @vindex pkginclude_HEADERS
  5813. Header files that must be installed are specified by the
  5814. @code{HEADERS} family of variables. Headers can be installed in
  5815. @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
  5816. other directory you may have defined (@pxref{Uniform}). For instance,
  5817. @example
  5818. include_HEADERS = foo.h bar/bar.h
  5819. @end example
  5820. @noindent
  5821. will install the two files as @file{$(includedir)/foo.h} and
  5822. @file{$(includedir)/bar.h}.
  5823. The @code{nobase_} prefix is also supported,
  5824. @example
  5825. nobase_include_HEADERS = foo.h bar/bar.h
  5826. @end example
  5827. @noindent
  5828. will install the two files as @file{$(includedir)/foo.h} and
  5829. @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
  5830. @vindex noinst_HEADERS
  5831. Usually, only header files that accompany installed libraries need to
  5832. be installed. Headers used by programs or convenience libraries are
  5833. not installed. The @code{noinst_HEADERS} variable can be used for
  5834. such headers. However when the header actually belongs to a single
  5835. convenience library or program, we recommend listing it in the
  5836. program's or library's @code{_SOURCES} variable (@pxref{Program
  5837. Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
  5838. the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
  5839. right variable to use in a directory containing only headers and no
  5840. associated library or program.
  5841. All header files must be listed somewhere; in a @code{_SOURCES}
  5842. variable or in a @code{_HEADERS} variable. Missing ones will not
  5843. appear in the distribution.
  5844. For header files that are built and must not be distributed, use the
  5845. @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
  5846. @code{nodist_prog_SOURCES}. If these generated headers are needed
  5847. during the build, you must also ensure they exist before they are
  5848. used (@pxref{Sources}).
  5849. @node Data
  5850. @section Architecture-independent data files
  5851. @cindex @code{_DATA} primary, defined
  5852. @cindex @code{DATA} primary, defined
  5853. @cindex Primary variable, @code{DATA}
  5854. @vindex _DATA
  5855. Automake supports the installation of miscellaneous data files using the
  5856. @code{DATA} family of variables.
  5857. @vindex DATA
  5858. @vindex data_DATA
  5859. @vindex sysconf_DATA
  5860. @vindex sharedstate_DATA
  5861. @vindex localstate_DATA
  5862. @vindex pkgdata_DATA
  5863. Such data can be installed in the directories @code{datadir},
  5864. @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
  5865. @code{pkgdatadir}.
  5866. By default, data files are @emph{not} included in a distribution. Of
  5867. course, you can use the @code{dist_} prefix to change this on a
  5868. per-variable basis.
  5869. Here is how Automake declares its auxiliary data files:
  5870. @example
  5871. dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
  5872. @end example
  5873. @node Sources
  5874. @section Built Sources
  5875. Because Automake's automatic dependency tracking works as a side-effect
  5876. of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
  5877. target should not be compiled before its dependencies are made, but
  5878. these dependencies are unknown until the target is first compiled.
  5879. Ordinarily this is not a problem, because dependencies are distributed
  5880. sources: they preexist and do not need to be built. Suppose that
  5881. @file{foo.c} includes @file{foo.h}. When it first compiles
  5882. @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
  5883. @file{foo.c}. As a side-effect of this compilation @command{depcomp}
  5884. records the @file{foo.h} dependency so that following invocations of
  5885. @command{make} will honor it. In these conditions, it's clear there is
  5886. no problem: either @file{foo.o} doesn't exist and has to be built
  5887. (regardless of the dependencies), or accurate dependencies exist and
  5888. they can be used to decide whether @file{foo.o} should be rebuilt.
  5889. It's a different story if @file{foo.h} doesn't exist by the first
  5890. @command{make} run. For instance, there might be a rule to build
  5891. @file{foo.h}. This time @file{file.o}'s build will fail because the
  5892. compiler can't find @file{foo.h}. @command{make} failed to trigger the
  5893. rule to build @file{foo.h} first by lack of dependency information.
  5894. @vindex BUILT_SOURCES
  5895. @cindex @code{BUILT_SOURCES}, defined
  5896. The @code{BUILT_SOURCES} variable is a workaround for this problem. A
  5897. source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
  5898. or @samp{make check} (or even @samp{make install}) before other
  5899. targets are processed. However, such a source file is not
  5900. @emph{compiled} unless explicitly requested by mentioning it in some
  5901. other @code{_SOURCES} variable.
  5902. So, to conclude our introductory example, we could use
  5903. @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
  5904. any other target (including @file{foo.o}) during @samp{make all} or
  5905. @samp{make check}.
  5906. @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
  5907. must be created early in the build process can be listed in this
  5908. variable. Moreover, all built sources do not necessarily have to be
  5909. listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
  5910. doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
  5911. another source), because it's a known dependency of the associated
  5912. object.
  5913. It might be important to emphasize that @code{BUILT_SOURCES} is
  5914. honored only by @samp{make all}, @samp{make check} and @samp{make
  5915. install}. This means you cannot build a specific target (e.g.,
  5916. @samp{make foo}) in a clean tree if it depends on a built source.
  5917. However it will succeed if you have run @samp{make all} earlier,
  5918. because accurate dependencies are already available.
  5919. The next section illustrates and discusses the handling of built sources
  5920. on a toy example.
  5921. @menu
  5922. * Built Sources Example:: Several ways to handle built sources.
  5923. @end menu
  5924. @node Built Sources Example
  5925. @subsection Built Sources Example
  5926. Suppose that @file{foo.c} includes @file{bindir.h}, which is
  5927. installation-dependent and not distributed: it needs to be built. Here
  5928. @file{bindir.h} defines the preprocessor macro @code{bindir} to the
  5929. value of the @command{make} variable @code{bindir} (inherited from
  5930. @file{configure}).
  5931. We suggest several implementations below. It's not meant to be an
  5932. exhaustive listing of all ways to handle built sources, but it will give
  5933. you a few ideas if you encounter this issue.
  5934. @subsubheading First Try
  5935. This first implementation will illustrate the bootstrap issue mentioned
  5936. in the previous section (@pxref{Sources}).
  5937. Here is a tentative @file{Makefile.am}.
  5938. @example
  5939. # This won't work.
  5940. bin_PROGRAMS = foo
  5941. foo_SOURCES = foo.c
  5942. nodist_foo_SOURCES = bindir.h
  5943. CLEANFILES = bindir.h
  5944. bindir.h: Makefile
  5945. echo '#define bindir "$(bindir)"' >$@@
  5946. @end example
  5947. This setup doesn't work, because Automake doesn't know that @file{foo.c}
  5948. includes @file{bindir.h}. Remember, automatic dependency tracking works
  5949. as a side-effect of compilation, so the dependencies of @file{foo.o} will
  5950. be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
  5951. The symptom is as follows.
  5952. @example
  5953. % make
  5954. source='foo.c' object='foo.o' libtool=no \
  5955. depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
  5956. depmode=gcc /bin/sh ./depcomp \
  5957. gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
  5958. foo.c:2: bindir.h: No such file or directory
  5959. make: *** [foo.o] Error 1
  5960. @end example
  5961. In this example @file{bindir.h} is not distributed nor installed, and
  5962. it is not even being built on-time. One may wonder if the
  5963. @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
  5964. line simply states that @file{bindir.h} is a source of @code{foo}, so
  5965. for instance, it should be inspected while generating tags
  5966. (@pxref{Tags}). In other words, it does not help our present problem,
  5967. and the build would fail identically without it.
  5968. @subsubheading Using @code{BUILT_SOURCES}
  5969. A solution is to require @file{bindir.h} to be built before anything
  5970. else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
  5971. @example
  5972. bin_PROGRAMS = foo
  5973. foo_SOURCES = foo.c
  5974. nodist_foo_SOURCES = bindir.h
  5975. BUILT_SOURCES = bindir.h
  5976. CLEANFILES = bindir.h
  5977. bindir.h: Makefile
  5978. echo '#define bindir "$(bindir)"' >$@@
  5979. @end example
  5980. See how @file{bindir.h} gets built first:
  5981. @example
  5982. % make
  5983. echo '#define bindir "/usr/local/bin"' >bindir.h
  5984. make all-am
  5985. make[1]: Entering directory `/home/adl/tmp'
  5986. source='foo.c' object='foo.o' libtool=no \
  5987. depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
  5988. depmode=gcc /bin/sh ./depcomp \
  5989. gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
  5990. gcc -g -O2 -o foo foo.o
  5991. make[1]: Leaving directory `/home/adl/tmp'
  5992. @end example
  5993. However, as said earlier, @code{BUILT_SOURCES} applies only to the
  5994. @code{all}, @code{check}, and @code{install} targets. It still fails
  5995. if you try to run @samp{make foo} explicitly:
  5996. @example
  5997. % make clean
  5998. test -z "bindir.h" || rm -f bindir.h
  5999. test -z "foo" || rm -f foo
  6000. rm -f *.o
  6001. % : > .deps/foo.Po # Suppress previously recorded dependencies
  6002. % make foo
  6003. source='foo.c' object='foo.o' libtool=no \
  6004. depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
  6005. depmode=gcc /bin/sh ./depcomp \
  6006. gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
  6007. foo.c:2: bindir.h: No such file or directory
  6008. make: *** [foo.o] Error 1
  6009. @end example
  6010. @subsubheading Recording Dependencies manually
  6011. Usually people are happy enough with @code{BUILT_SOURCES} because they
  6012. never build targets such as @samp{make foo} before @samp{make all}, as
  6013. in the previous example. However if this matters to you, you can
  6014. avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
  6015. the @file{Makefile.am}.
  6016. @example
  6017. bin_PROGRAMS = foo
  6018. foo_SOURCES = foo.c
  6019. nodist_foo_SOURCES = bindir.h
  6020. foo.$(OBJEXT): bindir.h
  6021. CLEANFILES = bindir.h
  6022. bindir.h: Makefile
  6023. echo '#define bindir "$(bindir)"' >$@@
  6024. @end example
  6025. You don't have to list @emph{all} the dependencies of @file{foo.o}
  6026. explicitly, only those that might need to be built. If a dependency
  6027. already exists, it will not hinder the first compilation and will be
  6028. recorded by the normal dependency tracking code. (Note that after
  6029. this first compilation the dependency tracking code will also have
  6030. recorded the dependency between @file{foo.o} and
  6031. @file{bindir.h}; so our explicit dependency is really useful to
  6032. the first build only.)
  6033. Adding explicit dependencies like this can be a bit dangerous if you are
  6034. not careful enough. This is due to the way Automake tries not to
  6035. overwrite your rules (it assumes you know better than it).
  6036. @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
  6037. output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
  6038. because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
  6039. target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
  6040. Always check the generated @file{Makefile.in} if you do this.
  6041. @subsubheading Build @file{bindir.h} from @file{configure}
  6042. It's possible to define this preprocessor macro from @file{configure},
  6043. either in @file{config.h} (@pxref{Defining Directories, , Defining
  6044. Directories, autoconf, The Autoconf Manual}), or by processing a
  6045. @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
  6046. (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
  6047. Autoconf Manual}).
  6048. At this point it should be clear that building @file{bindir.h} from
  6049. @file{configure} works well for this example. @file{bindir.h} will exist
  6050. before you build any target, hence will not cause any dependency issue.
  6051. The Makefile can be shrunk as follows. We do not even have to mention
  6052. @file{bindir.h}.
  6053. @example
  6054. bin_PROGRAMS = foo
  6055. foo_SOURCES = foo.c
  6056. @end example
  6057. However, it's not always possible to build sources from
  6058. @file{configure}, especially when these sources are generated by a tool
  6059. that needs to be built first.
  6060. @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
  6061. Another attractive idea is to define @code{bindir} as a variable or
  6062. function exported from @file{bindir.o}, and build @file{bindir.c}
  6063. instead of @file{bindir.h}.
  6064. @example
  6065. noinst_PROGRAMS = foo
  6066. foo_SOURCES = foo.c bindir.h
  6067. nodist_foo_SOURCES = bindir.c
  6068. CLEANFILES = bindir.c
  6069. bindir.c: Makefile
  6070. echo 'const char bindir[] = "$(bindir)";' >$@@
  6071. @end example
  6072. @file{bindir.h} contains just the variable's declaration and doesn't
  6073. need to be built, so it won't cause any trouble. @file{bindir.o} is
  6074. always dependent on @file{bindir.c}, so @file{bindir.c} will get built
  6075. first.
  6076. @subsubheading Which is best?
  6077. There is no panacea, of course. Each solution has its merits and
  6078. drawbacks.
  6079. You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
  6080. foo} on a clean tree is important to you.
  6081. You won't add explicit dependencies if you are leery of overriding
  6082. an Automake rule by mistake.
  6083. Building files from @file{./configure} is not always possible, neither
  6084. is converting @file{.h} files into @file{.c} files.
  6085. @node Other GNU Tools
  6086. @chapter Other GNU Tools
  6087. Since Automake is primarily intended to generate @file{Makefile.in}s for
  6088. use in GNU programs, it tries hard to interoperate with other GNU tools.
  6089. @menu
  6090. * Emacs Lisp:: Emacs Lisp
  6091. * gettext:: Gettext
  6092. * Libtool:: Libtool
  6093. * Java:: Java bytecode compilation (deprecated)
  6094. * Python:: Python
  6095. @end menu
  6096. @node Emacs Lisp
  6097. @section Emacs Lisp
  6098. @cindex @code{_LISP} primary, defined
  6099. @cindex @code{LISP} primary, defined
  6100. @cindex Primary variable, @code{LISP}
  6101. @vindex _LISP
  6102. @vindex lisp_LISP
  6103. @vindex noinst_LISP
  6104. Automake provides some support for Emacs Lisp. The @code{LISP} primary
  6105. is used to hold a list of @file{.el} files. Possible prefixes for this
  6106. primary are @code{lisp_} and @code{noinst_}. Note that if
  6107. @code{lisp_LISP} is defined, then @file{configure.ac} must run
  6108. @code{AM_PATH_LISPDIR} (@pxref{Macros}).
  6109. @vindex dist_lisp_LISP
  6110. @vindex dist_noinst_LISP
  6111. Lisp sources are not distributed by default. You can prefix the
  6112. @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
  6113. @code{dist_noinst_LISP}, to indicate that these files should be
  6114. distributed.
  6115. Automake will byte-compile all Emacs Lisp source files using the Emacs
  6116. found by @code{AM_PATH_LISPDIR}, if any was found. When performing such
  6117. byte-compilation, the flags specified in the (developer-reserved)
  6118. @code{AM_ELCFLAGS} and (user-reserved) @code{ELCFLAGS} make variables
  6119. will be passed to the Emacs invocation.
  6120. Byte-compiled Emacs Lisp files are not portable among all versions of
  6121. Emacs, so it makes sense to turn this off if you expect sites to have
  6122. more than one version of Emacs installed. Furthermore, many packages
  6123. don't actually benefit from byte-compilation. Still, we recommend
  6124. that you byte-compile your Emacs Lisp sources. It is probably better
  6125. for sites with strange setups to cope for themselves than to make the
  6126. installation less nice for everybody else.
  6127. There are two ways to avoid byte-compiling. Historically, we have
  6128. recommended the following construct.
  6129. @example
  6130. lisp_LISP = file1.el file2.el
  6131. ELCFILES =
  6132. @end example
  6133. @noindent
  6134. @code{ELCFILES} is an internal Automake variable that normally lists
  6135. all @file{.elc} files that must be byte-compiled. Automake defines
  6136. @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
  6137. variable explicitly prevents byte-compilation.
  6138. Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
  6139. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  6140. @example
  6141. lisp_DATA = file1.el file2.el
  6142. @end example
  6143. Note that these two constructs are not equivalent. @code{_LISP} will
  6144. not install a file if Emacs is not installed, while @code{_DATA} will
  6145. always install its files.
  6146. @node gettext
  6147. @section Gettext
  6148. @cindex GNU Gettext support
  6149. @cindex Gettext support
  6150. @cindex Support for GNU Gettext
  6151. If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
  6152. turns on support for GNU gettext, a message catalog system for
  6153. internationalization
  6154. (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
  6155. The @code{gettext} support in Automake requires the addition of one or
  6156. two subdirectories to the package: @file{po} and possibly also @file{intl}.
  6157. The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
  6158. @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
  6159. Automake ensures that these directories exist and are mentioned in
  6160. @code{SUBDIRS}.
  6161. @node Libtool
  6162. @section Libtool
  6163. Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
  6164. libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
  6165. @xref{A Shared Library}.
  6166. @node Java
  6167. @section Java bytecode compilation (deprecated)
  6168. @cindex @code{_JAVA} primary, defined
  6169. @cindex @code{JAVA} primary, defined
  6170. @cindex Primary variable, @code{JAVA}
  6171. @cindex Java to bytecode, compilation
  6172. @cindex Compilation of Java to bytecode
  6173. Automake provides some minimal support for Java bytecode compilation with
  6174. the @code{JAVA} primary (in addition to the support for compiling Java to
  6175. native machine code; @pxref{Java Support with gcj}). Note however that
  6176. @emph{the interface and most features described here are deprecated}.
  6177. Future Automake releases will strive to provide a better and cleaner
  6178. interface, which however @emph{won't be backward-compatible}; the present
  6179. interface will probably be removed altogether some time after the
  6180. introduction of the new interface (if that ever materializes). In any
  6181. case, the current @code{JAVA} primary features are frozen and will no
  6182. longer be developed, not even to take bug fixes.
  6183. Any @file{.java} files listed in a @code{_JAVA} variable will be
  6184. compiled with @code{JAVAC} at build time. By default, @file{.java}
  6185. files are not included in the distribution, you should use the
  6186. @code{dist_} prefix to distribute them.
  6187. Here is a typical setup for distributing @file{.java} files and
  6188. installing the @file{.class} files resulting from their compilation.
  6189. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  6190. @example
  6191. javadir = $(datadir)/java
  6192. dist_java_JAVA = a.java b.java @dots{}
  6193. @end example
  6194. @cindex @code{JAVA} restrictions
  6195. @cindex Restrictions for @code{JAVA}
  6196. Currently Automake enforces the restriction that only one @code{_JAVA}
  6197. primary can be used in a given @file{Makefile.am}. The reason for this
  6198. restriction is that, in general, it isn't possible to know which
  6199. @file{.class} files were generated from which @file{.java} files, so
  6200. it would be impossible to know which files to install where. For
  6201. instance, a @file{.java} file can define multiple classes; the resulting
  6202. @file{.class} file names cannot be predicted without parsing the
  6203. @file{.java} file.
  6204. There are a few variables that are used when compiling Java sources:
  6205. @vtable @code
  6206. @item JAVAC
  6207. The name of the Java compiler. This defaults to @samp{javac}.
  6208. @item JAVACFLAGS
  6209. The flags to pass to the compiler. This is considered to be a user
  6210. variable (@pxref{User Variables}).
  6211. @item AM_JAVACFLAGS
  6212. More flags to pass to the Java compiler. This, and not
  6213. @code{JAVACFLAGS}, should be used when it is necessary to put Java
  6214. compiler flags into @file{Makefile.am}.
  6215. @item JAVAROOT
  6216. The value of this variable is passed to the @option{-d} option to
  6217. @code{javac}. It defaults to @samp{$(top_builddir)}.
  6218. @item CLASSPATH_ENV
  6219. This variable is a shell expression that is used to set the
  6220. @env{CLASSPATH} environment variable on the @code{javac} command line.
  6221. (In the future we will probably handle class path setting differently.)
  6222. @end vtable
  6223. @node Python
  6224. @section Python
  6225. @cindex @code{_PYTHON} primary, defined
  6226. @cindex @code{PYTHON} primary, defined
  6227. @cindex Primary variable, @code{PYTHON}
  6228. @vindex _PYTHON
  6229. Automake provides support for Python compilation with the
  6230. @code{PYTHON} primary. A typical setup is to call
  6231. @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
  6232. following in @file{Makefile.am}:
  6233. @example
  6234. python_PYTHON = tree.py leave.py
  6235. @end example
  6236. Any files listed in a @code{_PYTHON} variable will be byte-compiled
  6237. with @command{py-compile} at install time. @command{py-compile}
  6238. actually creates both standard (@file{.pyc}) and optimized
  6239. (@file{.pyo}) byte-compiled versions of the source files. Note that
  6240. because byte-compilation occurs at install time, any files listed in
  6241. @code{noinst_PYTHON} will not be compiled. Python source files are
  6242. included in the distribution by default, prepend @code{nodist_} (as in
  6243. @code{nodist_python_PYTHON}) to omit them.
  6244. Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
  6245. that will determine some Python-related directory variables (see
  6246. below). If you have called @code{AM_PATH_PYTHON} from
  6247. @file{configure.ac}, then you may use the variables
  6248. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  6249. @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
  6250. files in your @file{Makefile.am}, depending on where you want your files
  6251. installed (see the definitions of @code{pythondir} and
  6252. @code{pkgpythondir} below).
  6253. @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
  6254. @ovar{action-if-not-found})
  6255. Search for a Python interpreter on the system. This macro takes three
  6256. optional arguments. The first argument, if present, is the minimum
  6257. version of Python required for this package: @code{AM_PATH_PYTHON}
  6258. will skip any Python interpreter that is older than @var{version}.
  6259. If an interpreter is found and satisfies @var{version}, then
  6260. @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
  6261. run.
  6262. If @var{action-if-not-found} is not specified, as in the following
  6263. example, the default is to abort @command{configure}.
  6264. @example
  6265. AM_PATH_PYTHON([2.2])
  6266. @end example
  6267. @noindent
  6268. This is fine when Python is an absolute requirement for the package.
  6269. If Python >= 2.5 was only @emph{optional} to the package,
  6270. @code{AM_PATH_PYTHON} could be called as follows.
  6271. @example
  6272. AM_PATH_PYTHON([2.5],, [:])
  6273. @end example
  6274. If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
  6275. called, then that will be the only Python interpreter that is tried.
  6276. @code{AM_PATH_PYTHON} creates the following output variables based on
  6277. the Python installation found during configuration.
  6278. @end defmac
  6279. @vtable @code
  6280. @item PYTHON
  6281. The name of the Python executable, or @samp{:} if no suitable
  6282. interpreter could be found.
  6283. Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
  6284. will abort if Python is absent), the value of @code{PYTHON} can be used
  6285. to setup a conditional in order to disable the relevant part of a build
  6286. as follows.
  6287. @example
  6288. AM_PATH_PYTHON(,, [:])
  6289. AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
  6290. @end example
  6291. @item PYTHON_VERSION
  6292. The Python version number, in the form @var{major}.@var{minor}
  6293. (e.g., @samp{2.5}). This is currently the value of
  6294. @samp{sys.version[:3]}.
  6295. @item PYTHON_PREFIX
  6296. The string @samp{$@{prefix@}}. This term may be used in future work
  6297. that needs the contents of Python's @samp{sys.prefix}, but general
  6298. consensus is to always use the value from @command{configure}.
  6299. @item PYTHON_EXEC_PREFIX
  6300. The string @samp{$@{exec_prefix@}}. This term may be used in future work
  6301. that needs the contents of Python's @samp{sys.exec_prefix}, but general
  6302. consensus is to always use the value from @command{configure}.
  6303. @item PYTHON_PLATFORM
  6304. The canonical name used by Python to describe the operating system, as
  6305. given by @samp{sys.platform}. This value is sometimes needed when
  6306. building Python extensions.
  6307. @item pythondir
  6308. The directory name for the @file{site-packages} subdirectory of the
  6309. standard Python install tree.
  6310. @item pkgpythondir
  6311. This is the directory under @code{pythondir} that is named after the
  6312. package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
  6313. as a convenience.
  6314. @item pyexecdir
  6315. This is the directory where Python extension modules (shared libraries)
  6316. should be installed. An extension module written in C could be declared
  6317. as follows to Automake:
  6318. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  6319. @example
  6320. pyexec_LTLIBRARIES = quaternion.la
  6321. quaternion_la_SOURCES = quaternion.c support.c support.h
  6322. quaternion_la_LDFLAGS = -avoid-version -module
  6323. @end example
  6324. @item pkgpyexecdir
  6325. This is a convenience variable that is defined as
  6326. @samp{$(pyexecdir)/$(PACKAGE)}.
  6327. @end vtable
  6328. All of these directory variables have values that start with either
  6329. @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
  6330. fine in @file{Makefiles}, but it makes these variables hard to use in
  6331. @file{configure}. This is mandated by the GNU coding standards, so
  6332. that the user can run @samp{make prefix=/foo install}. The Autoconf
  6333. manual has a section with more details on this topic
  6334. (@pxref{Installation Directory Variables, , Installation Directory
  6335. Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
  6336. Install Paths}.
  6337. @node Documentation
  6338. @chapter Building documentation
  6339. Currently Automake provides support for Texinfo and man pages.
  6340. @menu
  6341. * Texinfo:: Texinfo
  6342. * Man Pages:: Man pages
  6343. @end menu
  6344. @node Texinfo
  6345. @section Texinfo
  6346. @cindex @code{_TEXINFOS} primary, defined
  6347. @cindex @code{TEXINFOS} primary, defined
  6348. @cindex Primary variable, @code{TEXINFOS}
  6349. @cindex HTML output using Texinfo
  6350. @cindex PDF output using Texinfo
  6351. @cindex PS output using Texinfo
  6352. @cindex DVI output using Texinfo
  6353. @vindex _TEXINFOS
  6354. @vindex info_TEXINFOS
  6355. If the current directory contains Texinfo source, you must declare it
  6356. with the @code{TEXINFOS} primary. Generally Texinfo files are converted
  6357. into info, and thus the @code{info_TEXINFOS} variable is most commonly used
  6358. here. Any Texinfo source file should have the @file{.texi} extension.
  6359. Automake also accepts @file{.txi} or @file{.texinfo} extensions, but their
  6360. use is discouraged now, and will elicit runtime warnings.
  6361. Automake generates rules to build @file{.info}, @file{.dvi},
  6362. @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
  6363. sources. Following the GNU Coding Standards, only the @file{.info}
  6364. files are built by @samp{make all} and installed by @samp{make
  6365. install} (unless you use @option{no-installinfo}, see below).
  6366. Furthermore, @file{.info} files are automatically distributed so that
  6367. Texinfo is not a prerequisite for installing your package.
  6368. It is worth noting that, contrary to what happens with the other formats,
  6369. the generated @file{.info} files are by default placed in @code{srcdir}
  6370. rather than in the @code{builddir}. This can be changed with the
  6371. @option{info-in-builddir} option.
  6372. @trindex dvi
  6373. @trindex html
  6374. @trindex pdf
  6375. @trindex ps
  6376. @trindex install-dvi
  6377. @trindex install-html
  6378. @trindex install-pdf
  6379. @trindex install-ps
  6380. Other documentation formats can be built on request by @samp{make
  6381. dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
  6382. can be installed with @samp{make install-dvi}, @samp{make install-ps},
  6383. @samp{make install-pdf} and @samp{make install-html} explicitly.
  6384. @samp{make uninstall} will remove everything: the Texinfo
  6385. documentation installed by default as well as all the above optional
  6386. formats.
  6387. All of these targets can be extended using @samp{-local} rules
  6388. (@pxref{Extending}).
  6389. @cindex Texinfo flag, @code{VERSION}
  6390. @cindex Texinfo flag, @code{UPDATED}
  6391. @cindex Texinfo flag, @code{EDITION}
  6392. @cindex Texinfo flag, @code{UPDATED-MONTH}
  6393. @cindex @code{VERSION} Texinfo flag
  6394. @cindex @code{UPDATED} Texinfo flag
  6395. @cindex @code{EDITION} Texinfo flag
  6396. @cindex @code{UPDATED-MONTH} Texinfo flag
  6397. @cindex @file{mdate-sh}
  6398. If the @file{.texi} file @code{@@include}s @file{version.texi}, then
  6399. that file will be automatically generated. The file @file{version.texi}
  6400. defines four Texinfo flags you can reference using
  6401. @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
  6402. @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
  6403. @table @code
  6404. @item EDITION
  6405. @itemx VERSION
  6406. Both of these flags hold the version number of your program. They are
  6407. kept separate for clarity.
  6408. @item UPDATED
  6409. This holds the date the primary @file{.texi} file was last modified.
  6410. @item UPDATED-MONTH
  6411. This holds the name of the month in which the primary @file{.texi} file
  6412. was last modified.
  6413. @end table
  6414. The @file{version.texi} support requires the @command{mdate-sh}
  6415. script; this script is supplied with Automake and automatically
  6416. included when @command{automake} is invoked with the
  6417. @option{--add-missing} option.
  6418. If you have multiple Texinfo files, and you want to use the
  6419. @file{version.texi} feature, then you have to have a separate version
  6420. file for each Texinfo file. Automake will treat any include in a
  6421. Texinfo file that matches @file{vers*.texi} just as an automatically
  6422. generated version file.
  6423. Sometimes an info file actually depends on more than one @file{.texi}
  6424. file. For instance, in GNU Hello, @file{hello.texi} includes the file
  6425. @file{fdl.texi}. You can tell Automake about these dependencies using
  6426. the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
  6427. @vindex TEXINFOS
  6428. @vindex _TEXINFOS
  6429. @example
  6430. info_TEXINFOS = hello.texi
  6431. hello_TEXINFOS = fdl.texi
  6432. @end example
  6433. @cindex @file{texinfo.tex}
  6434. By default, Automake requires the file @file{texinfo.tex} to appear in
  6435. the same directory as the @file{Makefile.am} file that lists the
  6436. @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
  6437. @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
  6438. autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
  6439. there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
  6440. @option{--add-missing} is given, and takes care of its distribution.
  6441. However, if you set the @code{TEXINFO_TEX} variable (see below),
  6442. it overrides the location of the file and turns off its installation
  6443. into the source as well as its distribution.
  6444. The option @option{no-texinfo.tex} can be used to eliminate the
  6445. requirement for the file @file{texinfo.tex}. Use of the variable
  6446. @code{TEXINFO_TEX} is preferable, however, because that allows the
  6447. @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
  6448. @cindex Option, @code{no-installinfo}
  6449. @cindex Target, @code{install-info}
  6450. @cindex @code{install-info} target
  6451. @cindex @code{no-installinfo} option
  6452. @opindex no-installinfo
  6453. @trindex install-info
  6454. Automake generates an @code{install-info} rule; some people apparently
  6455. use this. By default, info pages are installed by @samp{make
  6456. install}, so running @code{make install-info} is pointless. This can
  6457. be prevented via the @code{no-installinfo} option. In this case,
  6458. @file{.info} files are not installed by default, and user must
  6459. request this explicitly using @samp{make install-info}.
  6460. @vindex AM_UPDATE_INFO_DIR
  6461. By default, @code{make install-info} and @code{make uninstall-info}
  6462. will try to run the @command{install-info} program (if available) to
  6463. update (or create/remove) the @file{@code{$@{infodir@}}/dir} index.
  6464. If this is undesired, it can be prevented by exporting the
  6465. @code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
  6466. The following variables are used by the Texinfo build rules.
  6467. @vtable @code
  6468. @item MAKEINFO
  6469. The name of the program invoked to build @file{.info} files. This
  6470. variable is defined by Automake. If the @command{makeinfo} program is
  6471. found on the system then it will be used by default; otherwise
  6472. @command{missing} will be used instead.
  6473. @item MAKEINFOHTML
  6474. The command invoked to build @file{.html} files. Automake
  6475. defines this to @samp{$(MAKEINFO) --html}.
  6476. @item MAKEINFOFLAGS
  6477. User flags passed to each invocation of @samp{$(MAKEINFO)} and
  6478. @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
  6479. not expected to be defined in any @file{Makefile}; it can be used by
  6480. users to pass extra flags to suit their needs.
  6481. @item AM_MAKEINFOFLAGS
  6482. @itemx AM_MAKEINFOHTMLFLAGS
  6483. Maintainer flags passed to each @command{makeinfo} invocation. Unlike
  6484. @code{MAKEINFOFLAGS}, these variables are meant to be defined by
  6485. maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
  6486. passed to @code{makeinfo} when building @file{.info} files; and
  6487. @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
  6488. files.
  6489. @c Keep in sync with txinfo-many-output-formats.sh
  6490. For instance, the following setting can be used to obtain one single
  6491. @file{.html} file per manual, without node separators.
  6492. @example
  6493. AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
  6494. @end example
  6495. @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
  6496. This means that defining @code{AM_MAKEINFOFLAGS} without defining
  6497. @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
  6498. and @file{.html} files.
  6499. @item TEXI2DVI
  6500. The name of the command that converts a @file{.texi} file into a
  6501. @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
  6502. with the Texinfo package.
  6503. @item TEXI2PDF
  6504. The name of the command that translates a @file{.texi} file into a
  6505. @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
  6506. @item DVIPS
  6507. The name of the command that builds a @file{.ps} file out of a
  6508. @file{.dvi} file. This defaults to @samp{dvips}.
  6509. @item TEXINFO_TEX
  6510. If your package has Texinfo files in many directories, you can use the
  6511. variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
  6512. @file{texinfo.tex} for your package. The value of this variable should
  6513. be the relative path from the current @file{Makefile.am} to
  6514. @file{texinfo.tex}:
  6515. @example
  6516. TEXINFO_TEX = ../doc/texinfo.tex
  6517. @end example
  6518. @end vtable
  6519. @node Man Pages
  6520. @section Man Pages
  6521. @cindex @code{_MANS} primary, defined
  6522. @cindex @code{MANS} primary, defined
  6523. @cindex Primary variable, @code{MANS}
  6524. @vindex _MANS
  6525. @vindex man_MANS
  6526. A package can also include man pages (but see the GNU standards on this
  6527. matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
  6528. pages are declared using the @code{MANS} primary. Generally the
  6529. @code{man_MANS} variable is used. Man pages are automatically installed in
  6530. the correct subdirectory of @code{mandir}, based on the file extension.
  6531. File extensions such as @file{.1c} are handled by looking for the valid
  6532. part of the extension and using that to determine the correct
  6533. subdirectory of @code{mandir}. Valid section names are the digits
  6534. @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
  6535. Sometimes developers prefer to name a man page something like
  6536. @file{foo.man} in the source, and then rename it to have the correct
  6537. suffix, for example @file{foo.1}, when installing the file. Automake
  6538. also supports this mode. For a valid section named @var{section},
  6539. there is a corresponding directory named @samp{man@var{section}dir},
  6540. and a corresponding @code{_MANS} variable. Files listed in such a
  6541. variable are installed in the indicated section. If the file already
  6542. has a valid suffix, then it is installed as-is; otherwise the file
  6543. suffix is changed to match the section.
  6544. For instance, consider this example:
  6545. @example
  6546. man1_MANS = rename.man thesame.1 alsothesame.1c
  6547. @end example
  6548. @noindent
  6549. In this case, @file{rename.man} will be renamed to @file{rename.1} when
  6550. installed, but the other files will keep their names.
  6551. @cindex Target, @code{install-man}
  6552. @cindex Option, @option{no-installman}
  6553. @cindex @code{install-man} target
  6554. @cindex @option{no-installman} option
  6555. @opindex no-installman
  6556. @trindex install-man
  6557. By default, man pages are installed by @samp{make install}. However,
  6558. since the GNU project does not require man pages, many maintainers do
  6559. not expend effort to keep the man pages up to date. In these cases, the
  6560. @option{no-installman} option will prevent the man pages from being
  6561. installed by default. The user can still explicitly install them via
  6562. @samp{make install-man}.
  6563. For fast installation, with many files it is preferable to use
  6564. @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
  6565. do not need to be renamed.
  6566. Man pages are not currently considered to be source, because it is not
  6567. uncommon for man pages to be automatically generated. Therefore they
  6568. are not automatically included in the distribution. However, this can
  6569. be changed by use of the @code{dist_} prefix. For instance here is
  6570. how to distribute and install the two man pages of GNU @command{cpio}
  6571. (which includes both Texinfo documentation and man pages):
  6572. @example
  6573. dist_man_MANS = cpio.1 mt.1
  6574. @end example
  6575. The @code{nobase_} prefix is meaningless for man pages and is
  6576. disallowed.
  6577. @vindex notrans_
  6578. @cindex @code{notrans_} prefix
  6579. @cindex Man page renaming, avoiding
  6580. @cindex Avoiding man page renaming
  6581. Executables and manpages may be renamed upon installation
  6582. (@pxref{Renaming}). For manpages this can be avoided by use of the
  6583. @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
  6584. allowing to access a library function @samp{foo} from the command line.
  6585. The way to avoid renaming of the @file{foo.3} manpage is:
  6586. @example
  6587. man_MANS = foo.1
  6588. notrans_man_MANS = foo.3
  6589. @end example
  6590. @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
  6591. @cindex @code{dist_} and @code{notrans_}
  6592. @cindex @code{nodist_} and @code{notrans_}
  6593. @samp{notrans_} must be specified first when used in conjunction with
  6594. either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
  6595. Control}). For instance:
  6596. @example
  6597. notrans_dist_man3_MANS = bar.3
  6598. @end example
  6599. @node Install
  6600. @chapter What Gets Installed
  6601. @cindex Installation support
  6602. @cindex @samp{make install} support
  6603. Naturally, Automake handles the details of actually installing your
  6604. program once it has been built. All files named by the various
  6605. primaries are automatically installed in the appropriate places when the
  6606. user runs @samp{make install}.
  6607. @menu
  6608. * Basics of Installation:: What gets installed where
  6609. * The Two Parts of Install:: Installing data and programs separately
  6610. * Extending Installation:: Adding your own rules for installation
  6611. * Staged Installs:: Installation in a temporary location
  6612. * Install Rules for the User:: Useful additional rules
  6613. @end menu
  6614. @node Basics of Installation
  6615. @section Basics of Installation
  6616. A file named in a primary is installed by copying the built file into
  6617. the appropriate directory. The base name of the file is used when
  6618. installing.
  6619. @example
  6620. bin_PROGRAMS = hello subdir/goodbye
  6621. @end example
  6622. In this example, both @samp{hello} and @samp{goodbye} will be installed
  6623. in @samp{$(bindir)}.
  6624. Sometimes it is useful to avoid the basename step at install time. For
  6625. instance, you might have a number of header files in subdirectories of
  6626. the source tree that are laid out precisely how you want to install
  6627. them. In this situation you can use the @code{nobase_} prefix to
  6628. suppress the base name step. For example:
  6629. @example
  6630. nobase_include_HEADERS = stdio.h sys/types.h
  6631. @end example
  6632. @noindent
  6633. will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
  6634. in @samp{$(includedir)/sys}.
  6635. For most file types, Automake will install multiple files at once, while
  6636. avoiding command line length issues (@pxref{Length Limitations}). Since
  6637. some @command{install} programs will not install the same file twice in
  6638. one invocation, you may need to ensure that file lists are unique within
  6639. one variable such as @samp{nobase_include_HEADERS} above.
  6640. You should not rely on the order in which files listed in one variable
  6641. are installed. Likewise, to cater for parallel make, you should not
  6642. rely on any particular file installation order even among different
  6643. file types (library dependencies are an exception here).
  6644. @node The Two Parts of Install
  6645. @section The Two Parts of Install
  6646. Automake generates separate @code{install-data} and @code{install-exec}
  6647. rules, in case the installer is installing on multiple machines that
  6648. share directory structure---these targets allow the machine-independent
  6649. parts to be installed only once. @code{install-exec} installs
  6650. platform-dependent files, and @code{install-data} installs
  6651. platform-independent files. The @code{install} target depends on both
  6652. of these targets. While Automake tries to automatically segregate
  6653. objects into the correct category, the @file{Makefile.am} author is, in
  6654. the end, responsible for making sure this is done correctly.
  6655. @trindex install-data
  6656. @trindex install-exec
  6657. @trindex install
  6658. @cindex Install, two parts of
  6659. Variables using the standard directory prefixes @samp{data},
  6660. @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
  6661. @samp{pkgdata}, or @samp{pkginclude} are installed by
  6662. @code{install-data}.
  6663. Variables using the standard directory prefixes @samp{bin},
  6664. @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
  6665. @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
  6666. For instance, @code{data_DATA} files are installed by @code{install-data},
  6667. while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
  6668. Any variable using a user-defined directory prefix with
  6669. @samp{exec} in the name (e.g.,
  6670. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  6671. @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
  6672. other user-defined prefixes are installed by @code{install-data}.
  6673. @node Extending Installation
  6674. @section Extending Installation
  6675. It is possible to extend this mechanism by defining an
  6676. @code{install-exec-local} or @code{install-data-local} rule. If these
  6677. rules exist, they will be run at @samp{make install} time. These
  6678. rules can do almost anything; care is required.
  6679. @trindex install-exec-local
  6680. @trindex install-data-local
  6681. Automake also supports two install hooks, @code{install-exec-hook} and
  6682. @code{install-data-hook}. These hooks are run after all other install
  6683. rules of the appropriate type, exec or data, have completed. So, for
  6684. instance, it is possible to perform post-installation modifications
  6685. using an install hook. @xref{Extending}, for some examples.
  6686. @cindex Install hook
  6687. @node Staged Installs
  6688. @section Staged Installs
  6689. @vindex DESTDIR
  6690. Automake generates support for the @code{DESTDIR} variable in all
  6691. install rules. @code{DESTDIR} is used during the @samp{make install}
  6692. step to relocate install objects into a staging area. Each object and
  6693. path is prefixed with the value of @code{DESTDIR} before being copied
  6694. into the install area. Here is an example of typical DESTDIR usage:
  6695. @example
  6696. mkdir /tmp/staging &&
  6697. make DESTDIR=/tmp/staging install
  6698. @end example
  6699. The @command{mkdir} command avoids a security problem if the attacker
  6700. creates a symbolic link from @file{/tmp/staging} to a victim area;
  6701. then @command{make} places install objects in a directory tree built under
  6702. @file{/tmp/staging}. If @file{/gnu/bin/foo} and
  6703. @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
  6704. would install @file{/tmp/staging/gnu/bin/foo} and
  6705. @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
  6706. This feature is commonly used to build install images and packages
  6707. (@pxref{DESTDIR}).
  6708. Support for @code{DESTDIR} is implemented by coding it directly into
  6709. the install rules. If your @file{Makefile.am} uses a local install
  6710. rule (e.g., @code{install-exec-local}) or an install hook, then you
  6711. must write that code to respect @code{DESTDIR}.
  6712. @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
  6713. for another usage example.
  6714. @node Install Rules for the User
  6715. @section Install Rules for the User
  6716. Automake also generates rules for targets @code{uninstall},
  6717. @code{installdirs}, and @code{install-strip}.
  6718. @trindex uninstall
  6719. @trindex installdirs
  6720. @trindex install-strip
  6721. Automake supports @code{uninstall-local} and @code{uninstall-hook}.
  6722. There is no notion of separate uninstalls for ``exec'' and ``data'', as
  6723. these features would not provide additional functionality.
  6724. Note that @code{uninstall} is not meant as a replacement for a real
  6725. packaging tool.
  6726. @node Clean
  6727. @chapter What Gets Cleaned
  6728. @cindex @samp{make clean} support
  6729. The GNU Makefile Standards specify a number of different clean rules.
  6730. @xref{Standard Targets, , Standard Targets for Users, standards,
  6731. The GNU Coding Standards}.
  6732. Generally the files that can be cleaned are determined automatically by
  6733. Automake. Of course, Automake also recognizes some variables that can
  6734. be defined to specify additional files to clean. These variables are
  6735. @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
  6736. @code{MAINTAINERCLEANFILES}.
  6737. @vindex MOSTLYCLEANFILES
  6738. @vindex CLEANFILES
  6739. @vindex DISTCLEANFILES
  6740. @vindex MAINTAINERCLEANFILES
  6741. @trindex mostlyclean-local
  6742. @trindex clean-local
  6743. @trindex distclean-local
  6744. @trindex maintainer-clean-local
  6745. When cleaning involves more than deleting some hard-coded list of
  6746. files, it is also possible to supplement the cleaning rules with your
  6747. own commands. Simply define a rule for any of the
  6748. @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
  6749. or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
  6750. case is deleting a directory, for instance, a directory created by the
  6751. test suite:
  6752. @example
  6753. clean-local:
  6754. -rm -rf testSubDir
  6755. @end example
  6756. Since @command{make} allows only one set of rules for a given target,
  6757. a more extensible way of writing this is to use a separate target
  6758. listed as a dependency:
  6759. @example
  6760. clean-local: clean-local-check
  6761. .PHONY: clean-local-check
  6762. clean-local-check:
  6763. -rm -rf testSubDir
  6764. @end example
  6765. As the GNU Standards aren't always explicit as to which files should
  6766. be removed by which rule, we've adopted a heuristic that we believe
  6767. was first formulated by Fran@,{c}ois Pinard:
  6768. @itemize @bullet
  6769. @item
  6770. If @command{make} built it, and it is commonly something that one would
  6771. want to rebuild (for instance, a @file{.o} file), then
  6772. @code{mostlyclean} should delete it.
  6773. @item
  6774. Otherwise, if @command{make} built it, then @code{clean} should delete it.
  6775. @item
  6776. If @command{configure} built it, then @code{distclean} should delete it.
  6777. @item
  6778. If the maintainer built it (for instance, a @file{.info} file), then
  6779. @code{maintainer-clean} should delete it. However
  6780. @code{maintainer-clean} should not delete anything that needs to exist
  6781. in order to run @samp{./configure && make}.
  6782. @end itemize
  6783. We recommend that you follow this same set of heuristics in your
  6784. @file{Makefile.am}.
  6785. @node Dist
  6786. @chapter What Goes in a Distribution
  6787. @menu
  6788. * Basics of Distribution:: Files distributed by default
  6789. * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
  6790. * The dist Hook:: A target for last-minute distribution changes
  6791. * Checking the Distribution:: @samp{make distcheck} explained
  6792. * The Types of Distributions:: A variety of formats and compression methods
  6793. @end menu
  6794. @node Basics of Distribution
  6795. @section Basics of Distribution
  6796. @cindex @samp{make dist}
  6797. @vindex PACKAGE
  6798. @vindex VERSION
  6799. @trindex dist
  6800. The @code{dist} rule in the generated @file{Makefile.in} can be used
  6801. to generate a gzipped @code{tar} file and other flavors of archive for
  6802. distribution. The file is named based on the @code{PACKAGE} and
  6803. @code{VERSION} variables automatically defined by either the
  6804. @code{AC_INIT} invocation or by a @emph{deprecated} two-arguments
  6805. invocation of the @code{AM_INIT_AUTOMAKE} macro (see @ref{Public Macros}
  6806. for how these variables get their values, from either defaults or explicit
  6807. values -- it's slightly trickier than one would expect).
  6808. More precisely the gzipped @code{tar} file is named
  6809. @samp{$@{PACKAGE@}-$@{VERSION@}.tar.gz}.
  6810. @vindex GZIP_ENV
  6811. You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
  6812. is run. The default setting is @option{--best}.
  6813. @cindex @code{m4_include}, distribution
  6814. @cindex @code{include}, distribution
  6815. @acindex m4_include
  6816. @cmindex include
  6817. For the most part, the files to distribute are automatically found by
  6818. Automake: all source files are automatically included in a distribution,
  6819. as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
  6820. has a built-in list of commonly used files that are automatically
  6821. included if they are found in the current directory (either physically,
  6822. or as the target of a @file{Makefile.am} rule); this list is printed by
  6823. @samp{automake --help}. Note that some files in this list are actually
  6824. distributed only if other certain conditions hold (for example,
  6825. @c Keep in sync with autodist-config-headers.sh
  6826. the @file{config.h.top} and @file{config.h.bot} files are automatically
  6827. distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
  6828. in @file{configure.ac}). Also, files that are read by @command{configure}
  6829. (i.e.@: the source files corresponding to the files specified in various
  6830. Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
  6831. automatically distributed. Files included in a @file{Makefile.am} (using
  6832. @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
  6833. helper scripts installed with @samp{automake --add-missing} are also
  6834. distributed.
  6835. @vindex EXTRA_DIST
  6836. Still, sometimes there are files that must be distributed, but which
  6837. are not covered in the automatic rules. These files should be listed in
  6838. the @code{EXTRA_DIST} variable. You can mention files from
  6839. subdirectories in @code{EXTRA_DIST}.
  6840. You can also mention a directory in @code{EXTRA_DIST}; in this case the
  6841. entire directory will be recursively copied into the distribution.
  6842. Please note that this will also copy @emph{everything} in the directory,
  6843. including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
  6844. version control files; thus we recommend against using this feature
  6845. as-is. However, you can use the @code{dist-hook} feature to
  6846. ameliorate the problem; @pxref{The dist Hook}.
  6847. @vindex SUBDIRS
  6848. @vindex DIST_SUBDIRS
  6849. If you define @code{SUBDIRS}, Automake will recursively include the
  6850. subdirectories in the distribution. If @code{SUBDIRS} is defined
  6851. conditionally (@pxref{Conditionals}), Automake will normally include
  6852. all directories that could possibly appear in @code{SUBDIRS} in the
  6853. distribution. If you need to specify the set of directories
  6854. conditionally, you can set the variable @code{DIST_SUBDIRS} to the
  6855. exact list of subdirectories to include in the distribution
  6856. (@pxref{Conditional Subdirectories}).
  6857. @node Fine-grained Distribution Control
  6858. @section Fine-grained Distribution Control
  6859. @vindex dist_
  6860. @vindex nodist_
  6861. Sometimes you need tighter control over what does @emph{not} go into the
  6862. distribution; for instance, you might have source files that are
  6863. generated and that you do not want to distribute. In this case
  6864. Automake gives fine-grained control using the @code{dist} and
  6865. @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
  6866. prefixed with @code{dist_} to add the listed files to the distribution.
  6867. Similarly, @code{nodist_} can be used to omit the files from the
  6868. distribution.
  6869. As an example, here is how you would cause some data to be distributed
  6870. while leaving some source code out of the distribution:
  6871. @example
  6872. dist_data_DATA = distribute-this
  6873. bin_PROGRAMS = foo
  6874. nodist_foo_SOURCES = do-not-distribute.c
  6875. @end example
  6876. @node The dist Hook
  6877. @section The dist Hook
  6878. @trindex dist-hook
  6879. Occasionally it is useful to be able to change the distribution before
  6880. it is packaged up. If the @code{dist-hook} rule exists, it is run
  6881. after the distribution directory is filled, but before the actual
  6882. distribution archives are created. One way to use this is for
  6883. removing unnecessary files that get recursively included by specifying
  6884. a directory in @code{EXTRA_DIST}:
  6885. @example
  6886. EXTRA_DIST = doc
  6887. dist-hook:
  6888. rm -rf `find $(distdir)/doc -type d -name .svn`
  6889. @end example
  6890. @c The caveats described here should be documented in 'disthook.sh'.
  6891. @noindent
  6892. Note that the @code{dist-hook} recipe shouldn't assume that the regular
  6893. files in the distribution directory are writable; this might not be the
  6894. case if one is packaging from a read-only source tree, or when a
  6895. @code{make distcheck} is being done. For similar reasons, the recipe
  6896. shouldn't assume that the subdirectories put into the distribution
  6897. directory as effect of having them listed in @code{EXTRA_DIST} are
  6898. writable. So, if the @code{dist-hook} recipe wants to modify the
  6899. content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
  6900. distribution directory, it should explicitly to make it writable first:
  6901. @example
  6902. EXTRA_DIST = README doc
  6903. dist-hook:
  6904. chmod u+w $(distdir)/README $(distdir)/doc
  6905. echo "Distribution date: `date`" >> README
  6906. rm -f $(distdir)/doc/HACKING
  6907. @end example
  6908. @vindex distdir
  6909. @vindex top_distdir
  6910. Two variables that come handy when writing @code{dist-hook} rules are
  6911. @samp{$(distdir)} and @samp{$(top_distdir)}.
  6912. @samp{$(distdir)} points to the directory where the @code{dist} rule
  6913. will copy files from the current directory before creating the
  6914. tarball. If you are at the top-level directory, then @samp{distdir =
  6915. $(PACKAGE)-$(VERSION)}. When used from subdirectory named
  6916. @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
  6917. @samp{$(distdir)} can be a relative or absolute path, do not assume
  6918. any form.
  6919. @samp{$(top_distdir)} always points to the root directory of the
  6920. distributed tree. At the top-level it's equal to @samp{$(distdir)}.
  6921. In the @file{foo/} subdirectory
  6922. @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
  6923. @samp{$(top_distdir)} too can be a relative or absolute path.
  6924. Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
  6925. (@pxref{Subpackages}), then @samp{$(distdir)} and
  6926. @samp{$(top_distdir)} are relative to the package where @samp{make
  6927. dist} was run, not to any sub-packages involved.
  6928. @node Checking the Distribution
  6929. @section Checking the Distribution
  6930. @cindex @samp{make distcheck}
  6931. @trindex distcheck
  6932. Automake also generates a @code{distcheck} rule that can be of help
  6933. to ensure that a given distribution will actually work. Simplifying
  6934. a bit, we can say this rule first makes a distribution, and then,
  6935. @emph{operating from it}, takes the following steps:
  6936. @itemize
  6937. @item
  6938. tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
  6939. @code{srcdir} and all its content made @emph{read-only};
  6940. @item
  6941. runs the test suite (with @command{make check}) on this fresh build;
  6942. @item
  6943. installs the package in a temporary directory (with @command{make
  6944. install}), and tries runs the test suite on the resulting installation
  6945. (with @command{make installcheck});
  6946. @item
  6947. checks that the package can be correctly uninstalled (by @command{make
  6948. uninstall}) and cleaned (by @code{make distclean});
  6949. @item
  6950. finally, makes another tarball to ensure the distribution is
  6951. self-contained.
  6952. @end itemize
  6953. All of these actions are performed in a temporary directory. Please
  6954. note that the exact location and the exact structure of such a directory
  6955. (where the read-only sources are placed, how the temporary build and
  6956. install directories are named and how deeply they are nested, etc.) is
  6957. to be considered an implementation detail, which can change at any time;
  6958. so do not reply on it.
  6959. @vindex AM_DISTCHECK_CONFIGURE_FLAGS
  6960. @vindex DISTCHECK_CONFIGURE_FLAGS
  6961. @subheading DISTCHECK_CONFIGURE_FLAGS
  6962. Building the package involves running @samp{./configure}. If you need
  6963. to supply additional flags to @command{configure}, define them in the
  6964. @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
  6965. @file{Makefile.am}. The user can still extend or override the flags
  6966. provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
  6967. on the command line when invoking @command{make}.
  6968. @c See automake bug#14991 for more details about how the following holds.
  6969. It's worth nothing that @command{make distcheck} needs complete control
  6970. over the @command{configure} options @option{--srcdir} and
  6971. @option{--prefix}, so those options cannot be overridden by
  6972. @code{AM_DISTCHECK_CONFIGURE_FLAGS} nor by
  6973. @code{DISTCHECK_CONFIGURE_FLAGS}.
  6974. Also note that developers are encouraged to strive to make their code
  6975. buildable without requiring any special configure option; thus, in
  6976. general, you shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}.
  6977. However, there might be few scenarios in which the use of this variable
  6978. is justified.
  6979. GNU @command{m4} offers an example. GNU @command{m4} configures by
  6980. default with its experimental and seldom used "changeword" feature
  6981. disabled; so in its case it is useful to have @command{make distcheck}
  6982. run configure with the @option{--with-changeword} option, to ensure that
  6983. the code for changeword support still compiles correctly.
  6984. GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
  6985. variable to stress-test the use of @option{--program-prefix=g}, since at
  6986. one point the @command{m4} build system had a bug where @command{make
  6987. installcheck} was wrongly assuming it could blindly test "@command{m4}",
  6988. rather than the just-installed "@command{gm4}".
  6989. @trindex distcheck-hook
  6990. @subheading distcheck-hook
  6991. If the @code{distcheck-hook} rule is defined in your top-level
  6992. @file{Makefile.am}, then it will be invoked by @code{distcheck} after
  6993. the new distribution has been unpacked, but before the unpacked copy
  6994. is configured and built. Your @code{distcheck-hook} can do almost
  6995. anything, though as always caution is advised. Generally this hook is
  6996. used to check for potential distribution errors not caught by the
  6997. standard mechanism. Note that @code{distcheck-hook} as well as
  6998. @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
  6999. are not honored in a subpackage @file{Makefile.am}, but the flags from
  7000. @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
  7001. are passed down to the @command{configure} script of the subpackage.
  7002. @cindex @samp{make distcleancheck}
  7003. @trindex distcleancheck
  7004. @vindex DISTCLEANFILES
  7005. @vindex distcleancheck_listfiles
  7006. @subheading distcleancheck
  7007. Speaking of potential distribution errors, @code{distcheck} also
  7008. ensures that the @code{distclean} rule actually removes all built
  7009. files. This is done by running @samp{make distcleancheck} at the end of
  7010. the @code{VPATH} build. By default, @code{distcleancheck} will run
  7011. @code{distclean} and then make sure the build tree has been emptied by
  7012. running @samp{$(distcleancheck_listfiles)}. Usually this check will
  7013. find generated files that you forgot to add to the @code{DISTCLEANFILES}
  7014. variable (@pxref{Clean}).
  7015. The @code{distcleancheck} behavior should be OK for most packages,
  7016. otherwise you have the possibility to override the definition of
  7017. either the @code{distcleancheck} rule, or the
  7018. @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
  7019. @code{distcleancheck} completely, add the following rule to your
  7020. top-level @file{Makefile.am}:
  7021. @example
  7022. distcleancheck:
  7023. @@:
  7024. @end example
  7025. If you want @code{distcleancheck} to ignore built files that have not
  7026. been cleaned because they are also part of the distribution, add the
  7027. following definition instead:
  7028. @c Keep in sync with distcleancheck.sh
  7029. @example
  7030. distcleancheck_listfiles = \
  7031. find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
  7032. sh '@{@}' ';'
  7033. @end example
  7034. The above definition is not the default because it's usually an error if
  7035. your Makefiles cause some distributed files to be rebuilt when the user
  7036. build the package. (Think about the user missing the tool required to
  7037. build the file; or if the required tool is built by your package,
  7038. consider the cross-compilation case where it can't be run.) There is
  7039. an entry in the FAQ about this (@pxref{Errors with distclean}), make
  7040. sure you read it before playing with @code{distcleancheck_listfiles}.
  7041. @cindex @samp{make distuninstallcheck}
  7042. @trindex distuninstallcheck
  7043. @vindex distuninstallcheck_listfiles
  7044. @subheading distuninstallcheck
  7045. @code{distcheck} also checks that the @code{uninstall} rule works
  7046. properly, both for ordinary and @code{DESTDIR} builds. It does this
  7047. by invoking @samp{make uninstall}, and then it checks the install tree
  7048. to see if any files are left over. This check will make sure that you
  7049. correctly coded your @code{uninstall}-related rules.
  7050. By default, the checking is done by the @code{distuninstallcheck} rule,
  7051. and the list of files in the install tree is generated by
  7052. @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
  7053. a shell command to run that prints the list of files to stdout).
  7054. Either of these can be overridden to modify the behavior of
  7055. @code{distcheck}. For instance, to disable this check completely, you
  7056. would write:
  7057. @example
  7058. distuninstallcheck:
  7059. @@:
  7060. @end example
  7061. @node The Types of Distributions
  7062. @section The Types of Distributions
  7063. Automake generates rules to provide archives of the project for
  7064. distributions in various formats. Their targets are:
  7065. @table @asis
  7066. @item @code{dist-gzip}
  7067. Generate a @samp{gzip} tar archive of the distribution. This is the
  7068. only format enabled by default.
  7069. @trindex dist-gzip
  7070. @vindex BZIP2
  7071. @item @code{dist-bzip2}
  7072. Generate a @samp{bzip2} tar archive of the distribution. bzip2 archives
  7073. are frequently smaller than gzipped archives.
  7074. By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
  7075. To make it use a different one, set the @env{BZIP2} environment variable.
  7076. For example, @samp{make dist-bzip2 BZIP2=-7}.
  7077. @trindex dist-bzip2
  7078. @item @code{dist-lzip}
  7079. Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
  7080. archives are frequently smaller than @command{bzip2}-compressed archives.
  7081. @trindex dist-lzip
  7082. @vindex XZ_OPT
  7083. @item @code{dist-xz}
  7084. Generate an @samp{xz} tar archive of the distribution. @command{xz}
  7085. archives are frequently smaller than @command{bzip2}-compressed archives.
  7086. By default, this rule makes @samp{xz} use a compression option of
  7087. @option{-e}. To make it use a different one, set the @env{XZ_OPT}
  7088. environment variable. For example, run this command to use the
  7089. default compression ratio, but with a progress indicator:
  7090. @samp{make dist-xz XZ_OPT=-ve}.
  7091. @trindex dist-xz
  7092. @item @code{dist-zip}
  7093. Generate a @samp{zip} archive of the distribution.
  7094. @trindex dist-zip
  7095. @item @code{dist-tarZ}
  7096. Generate a tar archive of the distribution, compressed with the
  7097. historical (and obsolescent) program @command{compress}. This
  7098. option is deprecated, and it and the corresponding functionality
  7099. will be removed altogether in Automake 2.0.
  7100. @trindex dist-tarZ
  7101. @item @code{dist-shar}
  7102. Generate a @samp{shar} archive of the distribution. This format
  7103. archive is obsolescent, and use of this option is deprecated.
  7104. It and the corresponding functionality will be removed altogether
  7105. in Automake 2.0.
  7106. @trindex dist-shar
  7107. @end table
  7108. The rule @code{dist} (and its historical synonym @code{dist-all})
  7109. will create archives in all the enabled formats (@pxref{List of
  7110. Automake options} for how to change this list). By default, only
  7111. the @code{dist-gzip} target is hooked to @code{dist}.
  7112. @node Tests
  7113. @chapter Support for test suites
  7114. @cindex Test suites
  7115. @cindex @code{make check}
  7116. @trindex check
  7117. Automake can generate code to handle two kinds of test suites. One is
  7118. based on integration with the @command{dejagnu} framework. The other
  7119. (and most used) form is based on the use of generic test scripts, and
  7120. its activation is triggered by the definition of the special @code{TESTS}
  7121. variable. This second form allows for various degrees of sophistication
  7122. and customization; in particular, it allows for concurrent execution
  7123. of test scripts, use of established test protocols such as TAP, and
  7124. definition of custom test drivers and test runners.
  7125. @noindent
  7126. In either case, the testsuite is invoked via @samp{make check}.
  7127. @menu
  7128. * Generalities about Testing:: Concepts and terminology about testing
  7129. * Simple Tests:: Listing test scripts in @code{TESTS}
  7130. * Custom Test Drivers:: Writing and using custom test drivers
  7131. * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
  7132. * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
  7133. * Install Tests:: Running tests on installed packages
  7134. @end menu
  7135. @node Generalities about Testing
  7136. @section Generalities about Testing
  7137. The purpose of testing is to determine whether a program or system behaves
  7138. as expected (e.g., known inputs produce the expected outputs, error
  7139. conditions are correctly handled or reported, and older bugs do not
  7140. resurface).
  7141. @cindex test case
  7142. The minimal unit of testing is usually called @emph{test case}, or simply
  7143. @emph{test}. How a test case is defined or delimited, and even what
  7144. exactly @emph{constitutes} a test case, depends heavily on the testing
  7145. paradigm and/or framework in use, so we won't attempt any more precise
  7146. definition. The set of the test cases for a given program or system
  7147. constitutes its @emph{testsuite}.
  7148. @cindex test harness
  7149. @cindex testsuite harness
  7150. A @emph{test harness} (also @emph{testsuite harness}) is a program or
  7151. software component that executes all (or part of) the defined test cases,
  7152. analyzes their outcomes, and report or register these outcomes
  7153. appropriately. Again, the details of how this is accomplished (and how
  7154. the developer and user can influence it or interface with it) varies
  7155. wildly, and we'll attempt no precise definition.
  7156. @cindex test pass
  7157. @cindex test failure
  7158. A test is said to @emph{pass} when it can determine that the condition or
  7159. behaviour it means to verify holds, and is said to @emph{fail} when it can
  7160. determine that such condition of behaviour does @emph{not} hold.
  7161. @cindex test skip
  7162. Sometimes, tests can rely on non-portable tools or prerequisites, or
  7163. simply make no sense on a given system (for example, a test checking a
  7164. Windows-specific feature makes no sense on a GNU/Linux system). In this
  7165. case, accordingly to the definition above, the tests can neither be
  7166. considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
  7167. they are not run, or their result is anyway ignored for what concerns
  7168. the count of failures an successes. Skips are usually explicitly
  7169. reported though, so that the user will be aware that not all of the
  7170. testsuite has really run.
  7171. @cindex xfail
  7172. @cindex expected failure
  7173. @cindex expected test failure
  7174. @cindex xpass
  7175. @cindex unexpected pass
  7176. @cindex unexpected test pass
  7177. It's not uncommon, especially during early development stages, that some
  7178. tests fail for known reasons, and that the developer doesn't want to
  7179. tackle these failures immediately (this is especially true when the
  7180. failing tests deal with corner cases). In this situation, the better
  7181. policy is to declare that each of those failures is an @emph{expected
  7182. failure} (or @emph{xfail}). In case a test that is expected to fail ends
  7183. up passing instead, many testing environments will flag the result as a
  7184. special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
  7185. @cindex hard error
  7186. @cindex Distinction between errors and failures in testsuites
  7187. Many testing environments and frameworks distinguish between test failures
  7188. and hard errors. As we've seen, a test failure happens when some invariant
  7189. or expected behaviour of the software under test is not met. An @emph{hard
  7190. error} happens when e.g., the set-up of a test case scenario fails, or when
  7191. some other unexpected or highly undesirable condition is encountered (for
  7192. example, the program under test experiences a segmentation fault).
  7193. @node Simple Tests
  7194. @section Simple Tests
  7195. @menu
  7196. * Scripts-based Testsuites:: Automake-specific concepts and terminology
  7197. * Serial Test Harness:: Older (and discouraged) serial test harness
  7198. * Parallel Test Harness:: Generic concurrent test harness
  7199. @end menu
  7200. @node Scripts-based Testsuites
  7201. @subsection Scripts-based Testsuites
  7202. If the special variable @code{TESTS} is defined, its value is taken to be
  7203. a list of programs or scripts to run in order to do the testing. Under
  7204. the appropriate circumstances, it's possible for @code{TESTS} to list
  7205. also data files to be passed to one or more test scripts defined by
  7206. different means (the so-called ``log compilers'', @pxref{Parallel Test
  7207. Harness}).
  7208. Test scripts can be executed serially or concurrently. Automake supports
  7209. both these kinds of test execution, with the parallel test harness being
  7210. the default. The concurrent test harness relies on the concurrence
  7211. capabilities (if any) offered by the underlying @command{make}
  7212. implementation, and can thus only be as good as those are.
  7213. By default, only the exit statuses of the test scripts are considered when
  7214. determining the testsuite outcome. But Automake allows also the use of
  7215. more complex test protocols, either standard (@pxref{Using the TAP test
  7216. protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can't
  7217. enable such protocols when the serial harness is used, though.
  7218. In the rest of this section we are going to concentrate mostly on
  7219. protocol-less tests, since we cover test protocols in a later section
  7220. (again, @pxref{Custom Test Drivers}).
  7221. @cindex Exit status 77, special interpretation
  7222. @cindex Exit status 99, special interpretation
  7223. When no test protocol is in use, an exit status of 0 from a test script will
  7224. denote a success, an exit status of 77 a skipped test, an exit status of 99
  7225. an hard error, and any other exit status will denote a failure.
  7226. @cindex Tests, expected failure
  7227. @cindex Expected test failure
  7228. @vindex XFAIL_TESTS
  7229. @vindex DISABLE_HARD_ERRORS
  7230. @cindex Disabling hard errors
  7231. You may define the variable @code{XFAIL_TESTS} to a list of tests
  7232. (usually a subset of @code{TESTS}) that are expected to fail; this will
  7233. effectively reverse the result of those tests (with the provision that
  7234. skips and hard errors remain untouched). You may also instruct the
  7235. testsuite harness to treat hard errors like simple failures, by defining
  7236. the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
  7237. Note however that, for tests based on more complex test protocols,
  7238. the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
  7239. might change, or they might even have no effect at all (for example,
  7240. @c Keep this in sync with tap-no-disable-hard-errors.sh
  7241. in tests using TAP, there is not way to disable hard errors, and the
  7242. @code{DISABLE_HARD_ERRORS} variable has no effect on them).
  7243. @anchor{Testsuite progress on console}
  7244. @cindex Testsuite progress on console
  7245. The result of each test case run by the scripts in @code{TESTS} will be
  7246. printed on standard output, along with the test name. For test protocols
  7247. that allow more test cases per test script (such as TAP), a number,
  7248. identifier and/or brief description specific for the single test case is
  7249. expected to be printed in addition to the name of the test script. The
  7250. possible results (whose meanings should be clear from the previous
  7251. @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
  7252. @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
  7253. example of output from an hypothetical testsuite that uses both plain
  7254. and TAP tests:
  7255. @c Keep in sync with tap-doc.sh
  7256. @example
  7257. PASS: foo.sh
  7258. PASS: zardoz.tap 1 - Daemon started
  7259. PASS: zardoz.tap 2 - Daemon responding
  7260. SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
  7261. PASS: zardoz.tap 4 - Daemon stopped
  7262. SKIP: bar.sh
  7263. PASS: mu.tap 1
  7264. XFAIL: mu.tap 2 # TODO frobnication not yet implemented
  7265. @end example
  7266. @noindent
  7267. A testsuite summary (expected to report at least the number of run,
  7268. skipped and failed tests) will be printed at the end of the testsuite
  7269. run.
  7270. @anchor{Simple tests and color-tests}
  7271. @vindex AM_COLOR_TESTS
  7272. @cindex Colorized testsuite output
  7273. If the standard output is connected to a capable terminal, then the test
  7274. results and the summary are colored appropriately. The developer and the
  7275. user can disable colored output by setting the @command{make} variable
  7276. @samp{AM_COLOR_TESTS=no}; the user can in addition force colored output
  7277. even without a connecting terminal with @samp{AM_COLOR_TESTS=always}.
  7278. It's also worth noting that some @command{make} implementations,
  7279. when used in parallel mode, have slightly different semantics
  7280. (@pxref{Parallel make,,, autoconf, The Autoconf Manual}), which can
  7281. break the automatic detection of a connection to a capable terminal.
  7282. If this is the case, the user will have to resort to the use of
  7283. @samp{AM_COLOR_TESTS=always} in order to have the testsuite output
  7284. colorized.
  7285. Test programs that need data files should look for them in @code{srcdir}
  7286. (which is both a make variable and an environment variable made available
  7287. to the tests), so that they work when building in a separate directory
  7288. (@pxref{Build Directories, , Build Directories , autoconf,
  7289. The Autoconf Manual}), and in particular for the @code{distcheck} rule
  7290. (@pxref{Checking the Distribution}).
  7291. @vindex TESTS
  7292. @vindex TESTS_ENVIRONMENT
  7293. @vindex AM_TESTS_ENVIRONMENT
  7294. The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
  7295. be used to run initialization code and set environment variables for the
  7296. test scripts. The former variable is developer-reserved, and can be
  7297. defined in the @file{Makefile.am}, while the latter is reserved for the
  7298. user, which can employ it to extend or override the settings in the
  7299. former; for this to work portably, however, the contents of a non-empty
  7300. @code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
  7301. @vindex AM_TESTS_FD_REDIRECT
  7302. The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
  7303. descriptor redirections for the test scripts. One might think that
  7304. @code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
  7305. has shown that doing so portably is practically impossible. The main
  7306. hurdle is constituted by Korn shells, which usually set the close-on-exec
  7307. flag on file descriptors opened with the @command{exec} builtin, thus
  7308. rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
  7309. ineffectual. This issue also affects some Bourne shells, such as the
  7310. HP-UX's @command{/bin/sh},
  7311. @c Keep in sync with tests-environment-backcompat.sh
  7312. @example
  7313. AM_TESTS_ENVIRONMENT = \
  7314. ## Some environment initializations are kept in a separate shell
  7315. ## file 'tests-env.sh', which can make it easier to also run tests
  7316. ## from the command line.
  7317. . $(srcdir)/tests-env.sh; \
  7318. ## On Solaris, prefer more POSIX-compliant versions of the standard
  7319. ## tools by default.
  7320. if test -d /usr/xpg4/bin; then \
  7321. PATH=/usr/xpg4/bin:$$PATH; export PATH; \
  7322. fi;
  7323. @c $$ restore font-lock
  7324. ## With this, the test scripts will be able to print diagnostic
  7325. ## messages to the original standard error stream, even if the test
  7326. ## driver redirects the stderr of the test scripts to a log file
  7327. ## before executing them.
  7328. AM_TESTS_FD_REDIRECT = 9>&2
  7329. @end example
  7330. @noindent
  7331. Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
  7332. implementation reasons, @emph{not} supported by the serial harness
  7333. (@pxref{Serial Test Harness}).
  7334. Automake ensures that each file listed in @code{TESTS} is built before
  7335. it is run; you can list both source and derived programs (or scripts)
  7336. in @code{TESTS}; the generated rule will look both in @code{srcdir} and
  7337. @file{.}. For instance, you might want to run a C program as a test.
  7338. To do this you would list its name in @code{TESTS} and also in
  7339. @code{check_PROGRAMS}, and then specify it as you would any other
  7340. program.
  7341. Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
  7342. @code{check_LTLIBRARIES}...) are only built during @code{make check},
  7343. not during @code{make all}. You should list there any program needed
  7344. by your tests that does not need to be built by @code{make all}. Note
  7345. that @code{check_PROGRAMS} are @emph{not} automatically added to
  7346. @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
  7347. by the tests, not the tests themselves. Of course you can set
  7348. @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
  7349. @node Serial Test Harness
  7350. @subsection Older (and discouraged) serial test harness
  7351. @cindex @option{serial-tests}, Using
  7352. First, note that today the use of this harness is strongly discouraged in
  7353. favour of the parallel test harness (@pxref{Parallel Test Harness}).
  7354. Still, there are @emph{few} situations when the advantages offered by
  7355. the parallel harness are irrelevant, and when test concurrency can
  7356. even cause tricky problems. In those cases, it might make sense to
  7357. still use the serial harness, for simplicity and reliability (we still
  7358. suggest trying to give the parallel harness a shot though).
  7359. The serial test harness is enabled by the Automake option
  7360. @option{serial-tests}. It operates by simply running the tests serially,
  7361. one at the time, without any I/O redirection. It's up to the user to
  7362. implement logging of tests' output, if that's required or desired.
  7363. For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
  7364. variable is @emph{not} supported by this harness (it will be silently
  7365. ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
  7366. considered a developer-reserved variable. This is done so that, when
  7367. using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
  7368. invocation of an interpreter through which the tests are to be run.
  7369. For instance, the following setup may be used to run tests with Perl:
  7370. @example
  7371. TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
  7372. TESTS = foo.pl bar.pl baz.pl
  7373. @end example
  7374. @noindent
  7375. It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
  7376. here would be @emph{invalid} with the parallel harness. That harness
  7377. provides a more elegant way to achieve the same effect, with the further
  7378. benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
  7379. (@pxref{Parallel Test Harness}).
  7380. Another, less serious limit of the serial harness is that it doesn't
  7381. really distinguish between simple failures and hard errors; this is
  7382. due to historical reasons only, and might be fixed in future Automake
  7383. versions.
  7384. @node Parallel Test Harness
  7385. @subsection Parallel Test Harness
  7386. By default, Automake generated a parallel (concurrent) test harness. It
  7387. features automatic collection of the test scripts output in @file{.log}
  7388. files, concurrent execution of tests with @code{make -j}, specification
  7389. of inter-test dependencies, lazy reruns of tests that have not completed
  7390. in a prior run, and hard errors for exceptional failures.
  7391. @anchor{Basics of test metadata}
  7392. @vindex TEST_SUITE_LOG
  7393. @vindex TESTS
  7394. @cindex @file{.log} files
  7395. @cindex @file{.trs} files
  7396. @cindex test metadata
  7397. The parallel test harness operates by defining a set of @command{make}
  7398. rules that run the test scripts listed in @code{TESTS}, and, for each
  7399. such script, save its output in a corresponding @file{.log} file and
  7400. its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
  7401. in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
  7402. @c We choose the '.trs' extension also because, at the time of writing,
  7403. @c it isn't already used for other significant purposes; see e.g.:
  7404. @c - http://filext.com/file-extension/trs
  7405. @c - http://www.file-extensions.org/search/?searchstring=trs
  7406. The @file{.log} file will contain all the output emitted by the test on
  7407. its standard output and its standard error. The @file{.trs} file will
  7408. contain, among the other things, the results of the test cases run by
  7409. the script.
  7410. The parallel test harness will also create a summary log file,
  7411. @code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
  7412. a @file{.log} suffix. This file depends upon all the @file{.log} and
  7413. @file{.trs} files created for the test scripts listed in @code{TESTS}.
  7414. @vindex VERBOSE
  7415. As with the serial harness above, by default one status line is printed
  7416. per completed test, and a short summary after the suite has completed.
  7417. However, standard output and standard error of the test are redirected
  7418. to a per-test log file, so that parallel execution does not produce
  7419. intermingled output. The output from failed tests is collected in the
  7420. @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
  7421. file is output after the summary.
  7422. @vindex TEST_EXTENSIONS
  7423. @vindex TEST_LOGS
  7424. Each couple of @file{.log} and @file{.trs} files is created when the
  7425. corresponding test has completed. The set of log files is listed in
  7426. the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
  7427. with the executable extension if any (@pxref{EXEEXT}), as well as any
  7428. suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
  7429. Results are undefined if a test file name ends in several concatenated
  7430. suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
  7431. overridden by the user, in which case any extension listed in it must be
  7432. constituted by a dot, followed by a non-digit alphabetic character,
  7433. followed by any number of alphabetic characters.
  7434. @c Keep in sync with test-extensions.sh
  7435. For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
  7436. while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
  7437. @cindex Configure substitutions in @code{TESTS}
  7438. It is important to note that, due to current limitations (unlikely to be
  7439. lifted), configure substitutions in the definition of @code{TESTS} can
  7440. only work if they will expand to a list of tests that have a suffix listed
  7441. in @code{TEST_EXTENSIONS}.
  7442. @vindex _LOG_COMPILE
  7443. @vindex _LOG_COMPILER
  7444. @vindex _LOG_FLAGS
  7445. @vindex LOG_COMPILE
  7446. @vindex LOG_COMPILER
  7447. @vindex LOG_FLAGS
  7448. @vindex @var{ext}_LOG_COMPILE
  7449. @vindex @var{ext}_LOG_COMPILER
  7450. @vindex @var{ext}_LOG_FLAGS
  7451. @vindex AM_@var{ext}_LOG_FLAGS
  7452. @vindex AM_LOG_FLAGS
  7453. For tests that match an extension @code{.@var{ext}} listed in
  7454. @code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
  7455. the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
  7456. extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow
  7457. the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
  7458. all tests with this extension to be called with this runner. For all
  7459. tests without a registered extension, the variables @code{LOG_COMPILER},
  7460. @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
  7461. @c Keep in sync with parallel-tests-log-compiler-example.sh
  7462. @example
  7463. TESTS = foo.pl bar.py baz
  7464. TEST_EXTENSIONS = .pl .py
  7465. PL_LOG_COMPILER = $(PERL)
  7466. AM_PL_LOG_FLAGS = -w
  7467. PY_LOG_COMPILER = $(PYTHON)
  7468. AM_PY_LOG_FLAGS = -v
  7469. LOG_COMPILER = ./wrapper-script
  7470. AM_LOG_FLAGS = -d
  7471. @end example
  7472. @noindent
  7473. will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
  7474. and @samp{./wrapper-script -d baz} to produce @file{foo.log},
  7475. @file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
  7476. @file{bar.trs} and @file{baz.trs} files will be automatically produced
  7477. as a side-effect.
  7478. It's important to note that, differently from what we've seen for the
  7479. serial test harness (@pxref{Serial Test Harness}), the
  7480. @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
  7481. @emph{cannot} be use to define a custom test runner; the
  7482. @code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
  7483. counterparts) should be used instead:
  7484. @example
  7485. ## This is WRONG!
  7486. AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
  7487. @end example
  7488. @example
  7489. ## Do this instead.
  7490. AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
  7491. LOG_COMPILER = $(PERL)
  7492. AM_LOG_FLAGS = -Mstrict -w
  7493. @end example
  7494. By default, the test suite harness will run all tests, but there are
  7495. several ways to limit the set of tests that are run:
  7496. @itemize @bullet
  7497. @item
  7498. You can set the @code{TESTS} variable. For example, you can use a
  7499. command like this to run only a subset of the tests:
  7500. @example
  7501. env TESTS="foo.test bar.test" make -e check
  7502. @end example
  7503. Note however that the command above will unconditionally overwrite the
  7504. @file{test-suite.log} file, thus clobbering the recorded results
  7505. of any previous testsuite run. This might be undesirable for packages
  7506. whose testsuite takes long time to execute. Luckily, this problem can
  7507. easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
  7508. for example,
  7509. @c Keep in sync with parallel-tests-log-override-2.sh
  7510. @example
  7511. env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
  7512. @end example
  7513. will write the result of the partial testsuite runs to the
  7514. @file{partial.log}, without touching @file{test-suite.log}.
  7515. @item
  7516. You can set the @code{TEST_LOGS} variable. By default, this variable is
  7517. computed at @command{make} run time from the value of @code{TESTS} as
  7518. described above. For example, you can use the following:
  7519. @example
  7520. set x subset*.log; shift
  7521. env TEST_LOGS="foo.log $*" make -e check
  7522. @end example
  7523. The comments made above about @code{TEST_SUITE_LOG} overriding applies
  7524. here too.
  7525. @item
  7526. @vindex RECHECK_LOGS
  7527. @cindex lazy test execution
  7528. By default, the test harness removes all old per-test @file{.log} and
  7529. @file{.trs} files before it starts running tests to regenerate them. The
  7530. variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
  7531. implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
  7532. defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
  7533. By overriding this variable, you can choose which tests need to be
  7534. reconsidered. For example, you can lazily rerun only those tests which
  7535. are outdated, i.e., older than their prerequisite test files, by setting
  7536. this variable to the empty value:
  7537. @example
  7538. env RECHECK_LOGS= make -e check
  7539. @end example
  7540. @item
  7541. @trindex recheck
  7542. You can ensure that all tests are rerun which have failed or passed
  7543. unexpectedly, by running @code{make recheck} in the test directory.
  7544. This convenience target will set @code{RECHECK_LOGS} appropriately
  7545. before invoking the main test harness.
  7546. @end itemize
  7547. @noindent
  7548. In order to guarantee an ordering between tests even with @code{make
  7549. -j@var{N}}, dependencies between the corresponding @file{.log} files
  7550. may be specified through usual @command{make} dependencies. For example,
  7551. the following snippet lets the test named @file{foo-execute.test} depend
  7552. upon completion of the test @file{foo-compile.test}:
  7553. @example
  7554. TESTS = foo-compile.test foo-execute.test
  7555. foo-execute.log: foo-compile.log
  7556. @end example
  7557. @noindent
  7558. Please note that this ordering ignores the @emph{results} of required
  7559. tests, thus the test @file{foo-execute.test} is run even if the test
  7560. @file{foo-compile.test} failed or was skipped beforehand. Further,
  7561. please note that specifying such dependencies currently works only for
  7562. tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
  7563. Tests without such specified dependencies may be run concurrently with
  7564. parallel @command{make -j@var{N}}, so be sure they are prepared for
  7565. concurrent execution.
  7566. @cindex Unit tests
  7567. @c Keep in sync with 'parallel-tests-extra-programs.sh'.
  7568. The combination of lazy test execution and correct dependencies between
  7569. tests and their sources may be exploited for efficient unit testing
  7570. during development. To further speed up the edit-compile-test cycle, it
  7571. may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
  7572. instead of with @code{check_PROGRAMS}, as the former allows intertwined
  7573. compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
  7574. not cleaned automatically, @pxref{Uniform}).
  7575. The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
  7576. conditional parts as well as configure substitutions. In the latter
  7577. case, however, certain restrictions apply: substituted test names
  7578. must end with a nonempty test suffix like @file{.test}, so that one of
  7579. the inference rules generated by @command{automake} can apply. For
  7580. literal test names, @command{automake} can generate per-target rules
  7581. to avoid this limitation.
  7582. Please note that it is currently not possible to use @code{$(srcdir)/}
  7583. or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
  7584. limitation is necessary to avoid generating test logs in the source tree
  7585. and has the unfortunate consequence that it is not possible to specify
  7586. distributed tests that are themselves generated by means of explicit
  7587. rules, in a way that is portable to all @command{make} implementations
  7588. (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
  7589. semantics of FreeBSD and OpenBSD @command{make} conflict with this).
  7590. In case of doubt you may want to require to use GNU @command{make},
  7591. or work around the issue with inference rules to generate the tests.
  7592. @node Custom Test Drivers
  7593. @section Custom Test Drivers
  7594. @menu
  7595. * Overview of Custom Test Drivers Support::
  7596. * Declaring Custom Test Drivers::
  7597. * API for Custom Test Drivers::
  7598. @end menu
  7599. @node Overview of Custom Test Drivers Support
  7600. @subsection Overview of Custom Test Drivers Support
  7601. Starting from Automake version 1.12, the parallel test harness allows
  7602. the package authors to use third-party custom test drivers, in case the
  7603. default ones are inadequate for their purposes, or do not support their
  7604. testing protocol of choice.
  7605. A custom test driver is expected to properly run the test programs passed
  7606. to it (including the command-line arguments passed to those programs, if
  7607. any), to analyze their execution and outcome, to create the @file{.log}
  7608. and @file{.trs} files associated to these test runs, and to display the test
  7609. results on the console. It is responsibility of the author of the test
  7610. driver to ensure that it implements all the above steps meaningfully and
  7611. correctly; Automake isn't and can't be of any help here. On the other
  7612. hand, the Automake-provided code for testsuite summary generation offers
  7613. support for test drivers allowing several test results per test script,
  7614. if they take care to register such results properly (@pxref{Log files
  7615. generation and test results recording}).
  7616. The exact details of how test scripts' results are to be determined and
  7617. analyzed is left to the individual drivers. Some drivers might only
  7618. consider the test script exit status (this is done for example by the
  7619. default test driver used by the parallel test harness, described
  7620. in the previous section). Other drivers might implement more complex and
  7621. advanced test protocols, which might require them to parse and interpreter
  7622. the output emitted by the test script they're running (examples of such
  7623. protocols are TAP and SubUnit).
  7624. It's very important to note that, even when using custom test drivers,
  7625. most of the infrastructure described in the previous section about the
  7626. parallel harness remains in place; this includes:
  7627. @itemize
  7628. @item
  7629. list of test scripts defined in @code{TESTS}, and overridable at
  7630. runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
  7631. @item
  7632. concurrency through the use of @command{make}'s option @option{-j};
  7633. @item
  7634. per-test @file{.log} and @file{.trs} files, and generation of a summary
  7635. @file{.log} file from them;
  7636. @item
  7637. @code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
  7638. of tests;
  7639. @item
  7640. inter-test dependencies;
  7641. @item
  7642. support for @code{check_*} variables (@code{check_PROGRAMS},
  7643. @code{check_LIBRARIES}, ...);
  7644. @item
  7645. use of @code{VERBOSE} environment variable to get verbose output on
  7646. testsuite failures;
  7647. @item
  7648. definition and honoring of @code{TESTS_ENVIRONMENT},
  7649. @code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
  7650. variables;
  7651. @item
  7652. definition of generic and extension-specific @code{LOG_COMPILER} and
  7653. @code{LOG_FLAGS} variables.
  7654. @end itemize
  7655. @noindent
  7656. On the other hand, the exact semantics of how (and if) testsuite output
  7657. colorization, @code{XFAIL_TESTS}, and hard errors are supported and
  7658. handled is left to the individual test drivers.
  7659. @c TODO: We should really add a working example in the doc/ directory,
  7660. @c TODO: and reference if from here.
  7661. @node Declaring Custom Test Drivers
  7662. @subsection Declaring Custom Test Drivers
  7663. @vindex _LOG_DRIVER
  7664. @vindex _LOG_DRIVER_FLAGS
  7665. @vindex LOG_DRIVER
  7666. @vindex LOG_DRIVER_FLAGS
  7667. @vindex @var{ext}_LOG_DRIVER
  7668. @vindex @var{ext}_LOG_DRIVER_FLAGS
  7669. @vindex AM_@var{ext}_LOG_DRIVER_FLAGS
  7670. @vindex AM_LOG_DRIVER_FLAGS
  7671. Custom testsuite drivers are declared by defining the make variables
  7672. @code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
  7673. be declared in @code{TEST_EXTENSIONS}). They must be defined to
  7674. programs or scripts that will be used to drive the execution, logging,
  7675. and outcome report of the tests with corresponding extensions (or of
  7676. those with no registered extension in the case of @code{LOG_DRIVER}).
  7677. Clearly, multiple distinct test drivers can be declared in the same
  7678. @file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
  7679. are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
  7680. two sets of variables can, and often do, usefully and legitimately
  7681. coexist.
  7682. @c TODO: We should really be able to point to a clarifying example here!
  7683. The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
  7684. user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
  7685. flags that will be passed to each invocation of @code{LOG_DRIVER},
  7686. with the user-defined flags obviously taking precedence over the
  7687. developer-reserved ones. Similarly, for each extension @var{ext}
  7688. declared in @code{TEST_EXTENSIONS}, flags listed in
  7689. @code{AM_@var{ext}_LOG_DRIVER_FLAGS} and
  7690. @code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
  7691. invocations of @code{@var{ext}_LOG_DRIVER}.
  7692. @node API for Custom Test Drivers
  7693. @subsection API for Custom Test Drivers
  7694. Note that @emph{the APIs described here are still highly experimental},
  7695. and will very likely undergo tightenings and likely also extensive changes
  7696. in the future, to accommodate for new features or to satisfy additional
  7697. portability requirements.
  7698. The main characteristic of these APIs is that they are designed to share
  7699. as much infrastructure, semantics, and implementation details as possible
  7700. with the parallel test harness and its default driver.
  7701. @menu
  7702. * Command-line arguments for test drivers::
  7703. * Log files generation and test results recording::
  7704. * Testsuite progress output::
  7705. @end menu
  7706. @node Command-line arguments for test drivers
  7707. @subsubsection Command-line arguments for test drivers
  7708. A custom driver can rely on various command-line options and arguments
  7709. being passed to it automatically by the Automake-generated test harness.
  7710. It is @emph{mandatory} that it understands all of them (even if the exact
  7711. interpretation of the associated semantics can legitimately change
  7712. between a test driver and another, and even be a no-op in some drivers).
  7713. @noindent
  7714. Here is the list of options:
  7715. @table @option
  7716. @item --test-name=@var{NAME}
  7717. The name of the test, with VPATH prefix (if any) removed. This can have a
  7718. suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
  7719. mostly meant to be used in console reports about testsuite advancements and
  7720. results (@pxref{Testsuite progress output}).
  7721. @item --log-file=@file{@var{PATH}.log}
  7722. The @file{.log} file the test driver must create (@pxref{Basics of
  7723. test metadata}). If it has a directory component (as in e.g.,
  7724. @file{sub/foo.log}), the test harness will ensure that such directory
  7725. exists @emph{before} the test driver is called.
  7726. @item --trs-file=@file{@var{PATH}.trs}
  7727. The @file{.trs} file the test driver must create (@pxref{Basics of
  7728. test metadata}). If it has a directory component (as in e.g.,
  7729. @file{sub/foo.trs}), the test harness will ensure that such directory
  7730. exists @emph{before} the test driver is called.
  7731. @item --color-tests=@{yes|no@}
  7732. Whether the console output should be colorized or not (@pxref{Simple
  7733. tests and color-tests}, to learn when this option gets activated and
  7734. when it doesn't).
  7735. @item --expect-failure=@{yes|no@}
  7736. Whether the tested program is expected to fail.
  7737. @item --enable-hard-errors=@{yes|no@}
  7738. Whether ``hard errors'' in the tested program should be treated differently
  7739. from normal failures or not (the default should be @code{yes}). The exact
  7740. meaning of ``hard error'' is highly dependent from the test protocols or
  7741. conventions in use.
  7742. @item --
  7743. Explicitly terminate the list of options.
  7744. @end table
  7745. @noindent
  7746. The first non-option argument passed to the test driver is the program to
  7747. be run, and all the following ones are command-line options and arguments
  7748. for this program.
  7749. Note that the exact semantics attached to the @option{--color-tests},
  7750. @option{--expect-failure} and @option{--enable-hard-errors} options are
  7751. left up to the individual test drivers. Still, having a behaviour
  7752. compatible or at least similar to that provided by the default driver
  7753. is advised, as that would offer a better consistency and a more pleasant
  7754. user experience.
  7755. @node Log files generation and test results recording
  7756. @subsubsection Log files generation and test results recording
  7757. The test driver must correctly generate the files specified by the
  7758. @option{--log-file} and @option{--trs-file} option (even when the tested
  7759. program fails or crashes).
  7760. The @file{.log} file should ideally contain all the output produced by the
  7761. tested program, plus optionally other information that might facilitate
  7762. debugging or analysis of bug reports. Apart from that, its format is
  7763. basically free.
  7764. The @file{.trs} file is used to register some metadata through the use
  7765. of custom reStructuredText fields. This metadata is expected to be
  7766. employed in various ways by the parallel test harness; for example, to
  7767. count the test results when printing the testsuite summary, or to decide
  7768. which tests to re-run upon @command{make recheck}. Unrecognized metadata
  7769. in a @file{.trs} file is currently ignored by the harness, but this might
  7770. change in the future. The list of currently recognized metadata follows.
  7771. @table @code
  7772. @item :test-result:
  7773. @cindex Register test result
  7774. @cindex Register test case result
  7775. @cindex Test result, registering
  7776. @cindex Test case result, registering
  7777. @cindex @code{:test-result:}
  7778. @cindex reStructuredText field, @code{:test-result:}
  7779. The test driver must use this field to register the results of @emph{each}
  7780. test case run by a test script file. Several @code{:test-result:} fields
  7781. can be present in the same @file{.trs} file; this is done in order to
  7782. support test protocols that allow a single test script to run more test
  7783. cases.
  7784. @c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
  7785. The only recognized test results are currently @code{PASS}, @code{XFAIL},
  7786. @code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
  7787. when declared with @code{:test-result:}, can be optionally followed by
  7788. text holding the name and/or a brief description of the corresponding
  7789. test; the harness will ignore such extra text when generating
  7790. @file{test-suite.log} and preparing the testsuite summary.
  7791. @c Keep in sync with 'test-metadata-recheck.sh'.
  7792. @item @code{:recheck:}
  7793. @cindex :recheck:
  7794. @cindex reStructuredText field, @code{:recheck:}
  7795. If this field is present and defined to @code{no}, then the corresponding
  7796. test script will @emph{not} be run upon a @command{make recheck}. What
  7797. happens when two or more @code{:recheck:} fields are present in the same
  7798. @file{.trs} file is undefined behaviour.
  7799. @c Keep in sync with 'test-metadata-global-log.sh'.
  7800. @item @code{:copy-in-global-log:}
  7801. @cindex :copy-in-global-log:
  7802. @cindex reStructuredText field, @code{:copy-in-global-log:}
  7803. If this field is present and defined to @code{no}, then the content
  7804. of the @file{.log} file will @emph{not} be copied into the global
  7805. @file{test-suite.log}. We allow to forsake such copying because, while
  7806. it can be useful in debugging and analysis of bug report, it can also be
  7807. just a waste of space in normal situations, e.g., when a test script is
  7808. successful. What happens when two or more @code{:copy-in-global-log:}
  7809. fields are present in the same @file{.trs} file is undefined behaviour.
  7810. @c Keep in sync with 'test-metadata-global-result.sh'.
  7811. @item @code{:test-global-result:}
  7812. @cindex :test-global-result:
  7813. @cindex reStructuredText field, @code{:test-global-result:}
  7814. This is used to declare the "global result" of the script. Currently,
  7815. the value of this field is needed only to be reported (more or less
  7816. verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
  7817. so it's quite free-form. For example, a test script which run 10 test
  7818. cases, 6 of which pass and 4 of which are skipped, could reasonably have
  7819. a @code{PASS/SKIP} value for this field, while a test script which run
  7820. 19 successful tests and one failed test could have an @code{ALMOST
  7821. PASSED} value. What happens when two or more @code{:test-global-result:}
  7822. fields are present in the same @file{.trs} file is undefined behaviour.
  7823. @end table
  7824. @noindent
  7825. Let's see a small example. Assume a @file{.trs} file contains the
  7826. following lines:
  7827. @example
  7828. :test-result: PASS server starts
  7829. :global-log-copy: no
  7830. :test-result: PASS HTTP/1.1 request
  7831. :test-result: FAIL HTTP/1.0 request
  7832. :recheck: yes
  7833. :test-result: SKIP HTTPS request (TLS library wasn't available)
  7834. :test-result: PASS server stops
  7835. @end example
  7836. @noindent
  7837. Then the corresponding test script will be re-run by @command{make check},
  7838. will contribute with @emph{five} test results to the testsuite summary
  7839. (three of these tests being successful, one failed, and one skipped), and
  7840. the content of the corresponding @file{.log} file will @emph{not} be
  7841. copied in the global log file @file{test-suite.log}.
  7842. @node Testsuite progress output
  7843. @subsubsection Testsuite progress output
  7844. A custom test driver also has the task of displaying, on the standard
  7845. output, the test results as soon as they become available. Depending on
  7846. the protocol in use, it can also display the reasons for failures and
  7847. skips, and, more generally, any useful diagnostic output (but remember
  7848. that each line on the screen is precious, so that cluttering the screen
  7849. with overly verbose information is bad idea). The exact format of this
  7850. progress output is left up to the test driver; in fact, a custom test
  7851. driver might @emph{theoretically} even decide not to do any such report,
  7852. leaving it all to the testsuite summary (that would be a very lousy idea,
  7853. of course, and serves only to illustrate the flexibility that is
  7854. granted here).
  7855. Remember that consistency is good; so, if possible, try to be consistent
  7856. with the output of the built-in Automake test drivers, providing a similar
  7857. ``look & feel''. In particular, the testsuite progress output should be
  7858. colorized when the @option{--color-tests} is passed to the driver. On the
  7859. other end, if you are using a known and widespread test protocol with
  7860. well-established implementations, being consistent with those
  7861. implementations' output might be a good idea too.
  7862. @node Using the TAP test protocol
  7863. @section Using the TAP test protocol
  7864. @menu
  7865. * Introduction to TAP::
  7866. * Use TAP with the Automake test harness::
  7867. * Incompatibilities with other TAP parsers and drivers::
  7868. * Links and external resources on TAP::
  7869. @end menu
  7870. @node Introduction to TAP
  7871. @subsection Introduction to TAP
  7872. TAP, the Test Anything Protocol, is a simple text-based interface between
  7873. testing modules or programs and a test harness. The tests (also called
  7874. ``TAP producers'' in this context) write test results in a simple format
  7875. on standard output; a test harness (also called ``TAP consumer'') will
  7876. parse and interpret these results, and properly present them to the user,
  7877. and/or register them for later analysis. The exact details of how this
  7878. is accomplished can vary among different test harnesses. The Automake
  7879. harness will present the results on the console in the usual
  7880. fashion (@pxref{Testsuite progress on console}), and will use the
  7881. @file{.trs} files (@pxref{Basics of test metadata}) to store the test
  7882. results and related metadata. Apart from that, it will try to remain
  7883. as much compatible as possible with pre-existing and widespread utilities,
  7884. such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
  7885. @command{prove} utility}, at least for the simpler usages.
  7886. TAP started its life as part of the test harness for Perl, but today
  7887. it has been (mostly) standardized, and has various independent
  7888. implementations in different languages; among them, C, C++, Perl,
  7889. Python, PHP, and Java. For a semi-official specification of the
  7890. TAP protocol, please refer to the documentation of
  7891. @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
  7892. @samp{Test::Harness::TAP}}.
  7893. The most relevant real-world usages of TAP are obviously in the testsuites
  7894. of @command{perl} and of many perl modules. Still, also other important
  7895. third-party packages, such as @uref{http://git-scm.com/, @command{git}},
  7896. use TAP in their testsuite.
  7897. @node Use TAP with the Automake test harness
  7898. @subsection Use TAP with the Automake test harness
  7899. Currently, the TAP driver that comes with Automake requires some by-hand
  7900. steps on the developer's part (this situation should hopefully be improved
  7901. in future Automake versions). You'll have to grab the @file{tap-driver.sh}
  7902. script from the Automake distribution by hand, copy it in your source tree,
  7903. and use the Automake support for third-party test drivers to instruct the
  7904. harness to use the @file{tap-driver.sh} script and the awk program found
  7905. by @code{AM_INIT_AUTOMAKE} to run your TAP-producing tests. See the example
  7906. below for clarification.
  7907. Apart from the options common to all the Automake test drivers
  7908. (@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh}
  7909. supports the following options, whose names are chosen for enhanced
  7910. compatibility with the @command{prove} utility.
  7911. @table @option
  7912. @c Keep in sync with 'tap-exit.sh' and 'tap-signal.tap'.
  7913. @item --ignore-exit
  7914. Causes the test driver to ignore the exit status of the test scripts;
  7915. by default, the driver will report an error if the script exits with a
  7916. non-zero status. This option has effect also on non-zero exit statuses
  7917. due to termination by a signal.
  7918. @item --comments
  7919. Instruct the test driver to display TAP diagnostic (i.e., lines beginning
  7920. with the @samp{#} character) in the testsuite progress output too; by
  7921. default, TAP diagnostic is only copied to the @file{.log} file.
  7922. @item --no-comments
  7923. Revert the effects of @option{--comments}.
  7924. @item --merge
  7925. Instruct the test driver to merge the test scripts' standard error into
  7926. their standard output. This is necessary if you want to ensure that
  7927. diagnostics from the test scripts are displayed in the correct order
  7928. relative to test results; this can be of great help in debugging
  7929. (especially if your test scripts are shell scripts run with shell
  7930. tracing active). As a downside, this option might cause the test
  7931. harness to get confused if anything that appears on standard error
  7932. looks like a test result.
  7933. @item --no-merge
  7934. Revert the effects of @option{--merge}.
  7935. @item --diagnostic-string=@var{STRING}
  7936. Change the string that introduces TAP diagnostic from the default value
  7937. of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
  7938. TAP-based test scripts produce verbose output on which they have limited
  7939. control (because, say, the output comes from other tools invoked in the
  7940. scripts), and it might contain text that gets spuriously interpreted as
  7941. TAP diagnostic: such an issue can be solved by redefining the string that
  7942. activates TAP diagnostic to a value you know won't appear by chance in
  7943. the tests' output. Note however that this feature is non-standard, as
  7944. the ``official'' TAP protocol does not allow for such a customization; so
  7945. don't use it if you can avoid it.
  7946. @end table
  7947. @noindent
  7948. Here is an example of how the TAP driver can be set up and used.
  7949. @c Keep in sync with tap-doc2.sh
  7950. @example
  7951. % @kbd{cat configure.ac}
  7952. AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
  7953. AC_CONFIG_AUX_DIR([build-aux])
  7954. AM_INIT_AUTOMAKE([foreign -Wall -Werror])
  7955. AC_CONFIG_FILES([Makefile])
  7956. AC_REQUIRE_AUX_FILE([tap-driver.sh])
  7957. AC_OUTPUT
  7958. % @kbd{cat Makefile.am}
  7959. TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
  7960. $(top_srcdir)/build-aux/tap-driver.sh
  7961. TESTS = foo.test bar.test baz.test
  7962. EXTRA_DIST = $(TESTS)
  7963. % @kbd{cat foo.test}
  7964. #!/bin/sh
  7965. echo 1..4 # Number of tests to be executed.
  7966. echo 'ok 1 - Swallows fly'
  7967. echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
  7968. echo 'ok 3 - Pigs fly # SKIP not enough acid'
  7969. echo '# I just love word plays ...'
  7970. echo 'ok 4 - Flies fly too :-)'
  7971. % @kbd{cat bar.test}
  7972. #!/bin/sh
  7973. echo 1..3
  7974. echo 'not ok 1 - Bummer, this test has failed.'
  7975. echo 'ok 2 - This passed though.'
  7976. echo 'Bail out! Ennui kicking in, sorry...'
  7977. echo 'ok 3 - This will not be seen.'
  7978. % @kbd{cat baz.test}
  7979. #!/bin/sh
  7980. echo 1..1
  7981. echo ok 1
  7982. # Exit with error, even if all the tests have been successful.
  7983. exit 7
  7984. % @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.sh .}
  7985. % @kbd{autoreconf -vi && ./configure && make check}
  7986. ...
  7987. PASS: foo.test 1 - Swallows fly
  7988. XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
  7989. SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
  7990. PASS: foo.test 4 - Flies fly too :-)
  7991. FAIL: bar.test 1 - Bummer, this test has failed.
  7992. PASS: bar.test 2 - This passed though.
  7993. ERROR: bar.test - Bail out! Ennui kicking in, sorry...
  7994. PASS: baz.test 1
  7995. ERROR: baz.test - exited with status 7
  7996. ...
  7997. Please report to bug-automake@@gnu.org
  7998. ...
  7999. % @kbd{echo exit status: $?}
  8000. exit status: 1
  8001. @c Keep the "skewed" indentation below, it produces pretty PDF output.
  8002. % @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
  8003. TESTS='foo.test baz.test' make -e check}
  8004. ...
  8005. PASS: foo.test 1 - Swallows fly
  8006. XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
  8007. SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
  8008. # foo.test: I just love word plays...
  8009. PASS: foo.test 4 - Flies fly too :-)
  8010. PASS: baz.test 1
  8011. ...
  8012. % @kbd{echo exit status: $?}
  8013. exit status: 0
  8014. @end example
  8015. @node Incompatibilities with other TAP parsers and drivers
  8016. @subsection Incompatibilities with other TAP parsers and drivers
  8017. For implementation or historical reasons, the TAP driver and harness as
  8018. implemented by Automake have some minors incompatibilities with the
  8019. mainstream versions, which you should be aware of.
  8020. @itemize @bullet
  8021. @item
  8022. A @code{Bail out!} directive doesn't stop the whole testsuite, but only
  8023. the test script it occurs in. This doesn't follow TAP specifications,
  8024. but on the other hand it maximizes compatibility (and code sharing) with
  8025. the ``hard error'' concept of the default testsuite driver.
  8026. @item
  8027. The @code{version} and @code{pragma} directives are not supported.
  8028. @item
  8029. The @option{--diagnostic-string} option of our driver allows to modify
  8030. the string that introduces TAP diagnostic from the default value
  8031. of ``@code{#}''. The standard TAP protocol has currently no way to
  8032. allow this, so if you use it your diagnostic will be lost to more
  8033. compliant tools like @command{prove} and @code{Test::Harness}
  8034. @item
  8035. And there are probably some other small and yet undiscovered
  8036. incompatibilities, especially in corner cases or with rare usages.
  8037. @end itemize
  8038. @node Links and external resources on TAP
  8039. @subsection Links and external resources on TAP
  8040. @noindent
  8041. Here are some links to more extensive official or third-party
  8042. documentation and resources about the TAP protocol and related
  8043. tools and libraries.
  8044. @itemize @bullet
  8045. @item
  8046. @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
  8047. @samp{Test::Harness::TAP}},
  8048. the (mostly) official documentation about the TAP format and protocol.
  8049. @item
  8050. @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
  8051. @command{prove}},
  8052. the most famous command-line TAP test driver, included in the distribution
  8053. of @command{perl} and
  8054. @uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
  8055. @samp{Test::Harness}}.
  8056. @item
  8057. The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
  8058. @item
  8059. A ``gentle introduction'' to testing for perl coders:
  8060. @uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
  8061. @samp{Test::Tutorial}}.
  8062. @item
  8063. @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
  8064. @samp{Test::Simple}}
  8065. and
  8066. @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
  8067. @samp{Test::More}},
  8068. the standard perl testing libraries, which are based on TAP.
  8069. @item
  8070. @uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
  8071. a C-based project implementing both a TAP producer and a TAP consumer.
  8072. @item
  8073. @uref{http://www.tap4j.org/,tap4j},
  8074. a Java-based project implementing both a TAP producer and a TAP consumer.
  8075. @end itemize
  8076. @node DejaGnu Tests
  8077. @section DejaGnu Tests
  8078. If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
  8079. @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
  8080. assumed. The variable @code{DEJATOOL} is a list of names that are
  8081. passed, one at a time, as the @option{--tool} argument to
  8082. @command{runtest} invocations; it defaults to the name of the package.
  8083. The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
  8084. @option{--srcdir} flags that are passed to dejagnu by default; this can be
  8085. overridden if necessary.
  8086. @vindex RUNTESTDEFAULTFLAGS
  8087. The variables @code{EXPECT} and @code{RUNTEST} can
  8088. also be overridden to provide project-specific values. For instance,
  8089. you will need to do this if you are testing a compiler toolchain,
  8090. because the default values do not take into account host and target
  8091. names.
  8092. @opindex dejagnu
  8093. @vindex DEJATOOL
  8094. @vindex EXPECT
  8095. @vindex RUNTEST
  8096. The contents of the variable @code{RUNTESTFLAGS} are passed to the
  8097. @code{runtest} invocation. This is considered a ``user variable''
  8098. (@pxref{User Variables}). If you need to set @command{runtest} flags in
  8099. @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
  8100. @vindex RUNTESTFLAGS
  8101. @vindex AM_RUNTESTFLAGS
  8102. @cindex @file{site.exp}
  8103. Automake will generate rules to create a local @file{site.exp} file,
  8104. defining various variables detected by @command{configure}. This file
  8105. is automatically read by DejaGnu. It is OK for the user of a package
  8106. to edit this file in order to tune the test suite. However this is
  8107. not the place where the test suite author should define new variables:
  8108. this should be done elsewhere in the real test suite code.
  8109. Especially, @file{site.exp} should not be distributed.
  8110. Still, if the package author has legitimate reasons to extend
  8111. @file{site.exp} at @command{make} time, he can do so by defining
  8112. the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
  8113. there will be considered @file{site.exp} prerequisites, and their
  8114. content will be appended to it (in the same order in which they
  8115. appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
  8116. @emph{not} distributed by default.
  8117. For more information regarding DejaGnu test suites, see @ref{Top, , ,
  8118. dejagnu, The DejaGnu Manual}.
  8119. @node Install Tests
  8120. @section Install Tests
  8121. The @code{installcheck} target is available to the user as a way to
  8122. run any tests after the package has been installed. You can add tests
  8123. to this by writing an @code{installcheck-local} rule.
  8124. @node Rebuilding
  8125. @chapter Rebuilding Makefiles
  8126. @cindex rebuild rules
  8127. Automake generates rules to automatically rebuild @file{Makefile}s,
  8128. @file{configure}, and other derived files like @file{Makefile.in}.
  8129. @acindex AM_MAINTAINER_MODE
  8130. If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
  8131. these automatic rebuilding rules are only enabled in maintainer mode.
  8132. @vindex CONFIG_STATUS_DEPENDENCIES
  8133. @vindex CONFIGURE_DEPENDENCIES
  8134. @cindex @file{version.sh}, example
  8135. @cindex @file{version.m4}, example
  8136. Sometimes it is convenient to supplement the rebuild rules for
  8137. @file{configure} or @file{config.status} with additional dependencies.
  8138. The variables @code{CONFIGURE_DEPENDENCIES} and
  8139. @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
  8140. dependencies. These variables should be defined in all
  8141. @file{Makefile}s of the tree (because these two rebuild rules are
  8142. output in all them), so it is safer and easier to @code{AC_SUBST} them
  8143. from @file{configure.ac}. For instance, the following statement will
  8144. cause @file{configure} to be rerun each time @file{version.sh} is
  8145. changed.
  8146. @c Keep in sync with remake-config-status-dependencies.sh
  8147. @example
  8148. AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
  8149. @end example
  8150. @noindent
  8151. Note the @samp{$(top_srcdir)/} in the file name. Since this variable
  8152. is to be used in all @file{Makefile}s, its value must be sensible at
  8153. any level in the build hierarchy.
  8154. Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
  8155. @code{CONFIG_STATUS_DEPENDENCIES}.
  8156. @c Keep in sync with remake-configure-dependencies.sh
  8157. @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
  8158. @file{configure} rule, whose effect is to run @command{autoconf}. This
  8159. variable should be seldom used, because @command{automake} already tracks
  8160. @code{m4_include}d files. However it can be useful when playing
  8161. tricky games with @code{m4_esyscmd} or similar non-recommendable
  8162. macros with side effects. Be also aware that interactions of this
  8163. variable with the @ref{Autom4te Cache, , autom4te cache, autoconf,
  8164. The Autoconf Manual} are quite problematic and can cause subtle
  8165. breakage, so you might want to disable the cache if you want to use
  8166. @code{CONFIGURE_DEPENDENCIES}.
  8167. @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
  8168. @file{config.status} rule, whose effect is to run @file{configure}.
  8169. This variable should therefore carry any non-standard source that may
  8170. be read as a side effect of running @command{configure}, like @file{version.sh}
  8171. in the example above.
  8172. Speaking of @file{version.sh} scripts, we recommend against them
  8173. today. They are mainly used when the version of a package is updated
  8174. automatically by a script (e.g., in daily builds). Here is what some
  8175. old-style @file{configure.ac}s may look like:
  8176. @example
  8177. AC_INIT
  8178. . $srcdir/version.sh
  8179. AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
  8180. @dots{}
  8181. @end example
  8182. @noindent
  8183. Here, @file{version.sh} is a shell fragment that sets
  8184. @code{VERSION_NUMBER}. The problem with this example is that
  8185. @command{automake} cannot track dependencies (listing @file{version.sh}
  8186. in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
  8187. to the user), and that it uses the obsolete form of @code{AC_INIT} and
  8188. @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
  8189. straightforward, because shell variables are not allowed in
  8190. @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
  8191. replaced by an M4 file that is included by @file{configure.ac}:
  8192. @example
  8193. m4_include([version.m4])
  8194. AC_INIT([name], VERSION_NUMBER)
  8195. AM_INIT_AUTOMAKE
  8196. @dots{}
  8197. @end example
  8198. @noindent
  8199. Here @file{version.m4} could contain something like
  8200. @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
  8201. second form is that @command{automake} will take care of the
  8202. dependencies when defining the rebuild rule, and will also distribute
  8203. the file automatically. An inconvenience is that @command{autoconf}
  8204. will now be rerun each time the version number is bumped, when only
  8205. @file{configure} had to be rerun in the previous setup.
  8206. @node Options
  8207. @chapter Changing Automake's Behavior
  8208. @menu
  8209. * Options generalities:: Semantics of Automake option
  8210. * List of Automake options:: A comprehensive list of Automake options
  8211. @end menu
  8212. @node Options generalities
  8213. @section Options generalities
  8214. Various features of Automake can be controlled by options. Except where
  8215. noted otherwise, options can be specified in one of several ways. Most
  8216. options can be applied on a per-@file{Makefile} basis when listed in a
  8217. special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
  8218. of these options only make sense when specified in the toplevel
  8219. @file{Makefile.am} file. Options are applied globally to all processed
  8220. @file{Makefile} files when listed in the first argument of
  8221. @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
  8222. require changes to the @command{configure} script can only be specified
  8223. there. These are annotated below.
  8224. As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
  8225. precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
  8226. turn take precedence over those specified on the command line.
  8227. Also, some care must be taken about the interactions among strictness
  8228. level and warning categories. As a general rule, strictness-implied
  8229. warnings are overridden by those specified by explicit options. For
  8230. example, even if @samp{portability} warnings are disabled by default
  8231. in @option{foreign} strictness, an usage like this will end up enabling
  8232. them:
  8233. @example
  8234. AUTOMAKE_OPTIONS = -Wportability foreign
  8235. @end example
  8236. However, a strictness level specified in a higher-priority context
  8237. will override all the explicit warnings specified in a lower-priority
  8238. context. For example, if @file{configure.ac} contains:
  8239. @example
  8240. AM_INIT_AUTOMAKE([-Wportability])
  8241. @end example
  8242. @noindent
  8243. and @file{Makefile.am} contains:
  8244. @example
  8245. AUTOMAKE_OPTIONS = foreign
  8246. @end example
  8247. @noindent
  8248. then @samp{portability} warnings will be @emph{disabled} in
  8249. @file{Makefile.am}.
  8250. @node List of Automake options
  8251. @section List of Automake options
  8252. @vindex AUTOMAKE_OPTIONS
  8253. @table @asis
  8254. @item @option{gnits}
  8255. @itemx @option{gnu}
  8256. @itemx @option{foreign}
  8257. @cindex Option, @option{gnits}
  8258. @cindex Option, @option{gnu}
  8259. @cindex Option, @option{foreign}
  8260. @opindex gnits
  8261. @opindex gnu
  8262. @opindex foreign
  8263. Set the strictness as appropriate. The @option{gnits} option also
  8264. implies options @option{readme-alpha} and @option{check-news}.
  8265. @item @option{check-news}
  8266. @cindex Option, @option{check-news}
  8267. @opindex check-news
  8268. Cause @samp{make dist} to fail unless the current version number appears
  8269. in the first few lines of the @file{NEWS} file.
  8270. @item @option{dejagnu}
  8271. @cindex Option, @option{dejagnu}
  8272. @opindex dejagnu
  8273. Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
  8274. @item @option{dist-bzip2}
  8275. @cindex Option, @option{dist-bzip2}
  8276. @opindex dist-bzip2
  8277. Hook @code{dist-bzip2} to @code{dist}.
  8278. @trindex dist-bzip2
  8279. @item @option{dist-lzip}
  8280. @cindex Option, @option{dist-lzip}
  8281. @opindex dist-lzip
  8282. Hook @code{dist-lzip} to @code{dist}.
  8283. @trindex dist-lzip
  8284. @item @option{dist-xz}
  8285. @cindex Option, @option{dist-xz}
  8286. @opindex dist-xz
  8287. Hook @code{dist-xz} to @code{dist}.
  8288. @trindex dist-xz
  8289. @item @option{dist-zip}
  8290. @cindex Option, @option{dist-zip}
  8291. @opindex dist-zip
  8292. Hook @code{dist-zip} to @code{dist}.
  8293. @trindex dist-zip
  8294. @item @option{dist-shar}
  8295. @cindex Option, @option{dist-shar}
  8296. @opindex dist-shar
  8297. Hook @code{dist-shar} to @code{dist}. Use of this option
  8298. is deprecated, as the @samp{shar} format is obsolescent and
  8299. problematic. Support for it will be removed altogether in
  8300. Automake 2.0.
  8301. @trindex dist-shar
  8302. @item @option{dist-tarZ}
  8303. @cindex Option, @option{dist-tarZ}
  8304. @opindex dist-tarZ
  8305. Hook @code{dist-tarZ} to @code{dist}. Use of this option
  8306. is deprecated, as the @samp{compress} program is obsolete.
  8307. Support for it will be removed altogether in Automake 2.0.
  8308. @trindex dist-tarZ
  8309. @item @option{filename-length-max=99}
  8310. @cindex Option, @option{filename-length-max=99}
  8311. @opindex filename-length-max=99
  8312. Abort if file names longer than 99 characters are found during
  8313. @samp{make dist}. Such long file names are generally considered not to
  8314. be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
  8315. options below. This option should be used in the top-level
  8316. @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
  8317. @file{configure.ac}, it will be ignored otherwise. It will also be
  8318. ignored in sub-packages of nested packages (@pxref{Subpackages}).
  8319. @item @option{info-in-builddir}
  8320. @cindex Option, @option{info-in-builddir}
  8321. @opindex info-in-builddir
  8322. Instruct Automake to place the generated @file{.info} files in the
  8323. @code{builddir} rather than in the @code{srcdir}. Note that this
  8324. might make VPATH builds with some non-GNU make implementations more
  8325. brittle.
  8326. @item @option{no-define}
  8327. @cindex Option, @option{no-define}
  8328. @opindex no-define
  8329. This option is meaningful only when passed as an argument to
  8330. @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
  8331. @code{VERSION} variables from being @code{AC_DEFINE}d. But notice
  8332. that they will remain defined as shell variables in the generated
  8333. @code{configure}, and as make variables in the generated
  8334. @code{Makefile}; this is deliberate, and required for backward
  8335. compatibility.
  8336. @item @option{no-dependencies}
  8337. @cindex Option, @option{no-dependencies}
  8338. @opindex no-dependencies
  8339. This is similar to using @option{--ignore-deps} on the command line,
  8340. but is useful for those situations where you don't have the necessary
  8341. bits to make automatic dependency tracking work
  8342. (@pxref{Dependencies}). In this case the effect is to effectively
  8343. disable automatic dependency tracking.
  8344. @item @option{no-dist}
  8345. @cindex Option, @option{no-dist}
  8346. @opindex no-dist
  8347. Don't emit any code related to @code{dist} target. This is useful
  8348. when a package has its own method for making distributions.
  8349. @item @option{no-dist-gzip}
  8350. @cindex Option, @option{no-dist-gzip}
  8351. @opindex no-dist-gzip
  8352. Do not hook @code{dist-gzip} to @code{dist}.
  8353. @trindex no-dist-gzip
  8354. @item @option{no-exeext}
  8355. @cindex Option, @option{no-exeext}
  8356. @opindex no-exeext
  8357. If your @file{Makefile.am} defines a rule for target @code{foo}, it
  8358. will override a rule for a target named @samp{foo$(EXEEXT)}. This is
  8359. necessary when @code{EXEEXT} is found to be empty. However, by
  8360. default @command{automake} will generate an error for this use. The
  8361. @option{no-exeext} option will disable this error. This is intended for
  8362. use only where it is known in advance that the package will not be
  8363. ported to Windows, or any other operating system using extensions on
  8364. executables.
  8365. @item @option{no-installinfo}
  8366. @cindex Option, @option{no-installinfo}
  8367. @opindex no-installinfo
  8368. The generated @file{Makefile.in} will not cause info pages to be built
  8369. or installed by default. However, @code{info} and @code{install-info}
  8370. targets will still be available. This option is disallowed at
  8371. @option{gnu} strictness and above.
  8372. @trindex info
  8373. @trindex install-info
  8374. @item @option{no-installman}
  8375. @cindex Option, @option{no-installman}
  8376. @opindex no-installman
  8377. The generated @file{Makefile.in} will not cause man pages to be
  8378. installed by default. However, an @code{install-man} target will still
  8379. be available for optional installation. This option is disallowed at
  8380. @option{gnu} strictness and above.
  8381. @trindex install-man
  8382. @item @option{nostdinc}
  8383. @cindex Option, @option{nostdinc}
  8384. @opindex nostdinc
  8385. This option can be used to disable the standard @option{-I} options that
  8386. are ordinarily automatically provided by Automake.
  8387. @item @option{no-texinfo.tex}
  8388. @cindex Option, @option{no-texinfo.tex}
  8389. @opindex no-texinfo.tex
  8390. Don't require @file{texinfo.tex}, even if there are texinfo files in
  8391. this directory.
  8392. @item @option{serial-tests}
  8393. @cindex Option, @option{serial-tests}
  8394. @opindex serial-tests
  8395. Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
  8396. Test Harness}, for more information).
  8397. @item @option{parallel-tests}
  8398. @cindex Option, @option{parallel-tests}
  8399. @opindex parallel-tests
  8400. Enable test suite harness for @code{TESTS} that can run tests in parallel
  8401. (@pxref{Parallel Test Harness}, for more information). This option is
  8402. only kept for backward-compatibility, since the parallel test harness is
  8403. the default now.
  8404. @item @option{readme-alpha}
  8405. @cindex Option, @option{readme-alpha}
  8406. @opindex readme-alpha
  8407. If this release is an alpha release, and the file @file{README-alpha}
  8408. exists, then it will be added to the distribution. If this option is
  8409. given, version numbers are expected to follow one of two forms. The
  8410. first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
  8411. element is a number; the final period and number should be left off for
  8412. non-alpha releases. The second form is
  8413. @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
  8414. letter; it should be omitted for non-alpha releases.
  8415. @item @option{std-options}
  8416. @cindex Options, @option{std-options}
  8417. @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
  8418. @cindex @option{--help} check
  8419. @cindex @option{--version} check
  8420. @opindex std-options
  8421. Make the @code{installcheck} rule check that installed scripts and
  8422. programs support the @option{--help} and @option{--version} options.
  8423. This also provides a basic check that the program's
  8424. run-time dependencies are satisfied after installation.
  8425. @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
  8426. In a few situations, programs (or scripts) have to be exempted from this
  8427. test. For instance, @command{false} (from GNU coreutils) is never
  8428. successful, even for @option{--help} or @option{--version}. You can list
  8429. such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
  8430. Programs (not scripts) listed in this variable should be suffixed by
  8431. @samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
  8432. build @file{false} as a program but @file{true.sh} as a script, and that
  8433. neither of them support @option{--help} or @option{--version}:
  8434. @example
  8435. AUTOMAKE_OPTIONS = std-options
  8436. bin_PROGRAMS = false ...
  8437. bin_SCRIPTS = true.sh ...
  8438. AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
  8439. @end example
  8440. @item @option{subdir-objects}
  8441. @cindex Options, @option{subdir-objects}
  8442. @opindex subdir-objects
  8443. If this option is specified, then objects are placed into the
  8444. subdirectory of the build directory corresponding to the subdirectory of
  8445. the source file. For instance, if the source file is
  8446. @file{subdir/file.cxx}, then the output file would be
  8447. @file{subdir/file.o}.
  8448. @anchor{tar-formats}
  8449. @item @option{tar-v7}
  8450. @itemx @option{tar-ustar}
  8451. @itemx @option{tar-pax}
  8452. @cindex Option, @option{tar-v7}
  8453. @cindex Option, @option{tar-ustar}
  8454. @cindex Option, @option{tar-pax}
  8455. @cindex @command{tar} formats
  8456. @cindex v7 @command{tar} format
  8457. @cindex ustar format
  8458. @cindex pax format
  8459. @opindex tar-v7
  8460. @opindex tar-ustar
  8461. @opindex tar-pax
  8462. These three mutually exclusive options select the tar format to use
  8463. when generating tarballs with @samp{make dist}. (The tar file created
  8464. is then compressed according to the set of @option{no-dist-gzip},
  8465. @option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
  8466. @option{dist-tarZ} options in use.)
  8467. These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
  8468. (@pxref{Macros}) because they can require additional configure checks.
  8469. Automake will complain if it sees such options in an
  8470. @code{AUTOMAKE_OPTIONS} variable.
  8471. @option{tar-v7} selects the old V7 tar format. This is the historical
  8472. default. This antiquated format is understood by all tar
  8473. implementations and supports file names with up to 99 characters. When
  8474. given longer file names some tar implementations will diagnose the
  8475. problem while other will generate broken tarballs or use non-portable
  8476. extensions. Furthermore, the V7 format cannot store empty
  8477. directories. When using this format, consider using the
  8478. @option{filename-length-max=99} option to catch file names too long.
  8479. @option{tar-ustar} selects the ustar format defined by POSIX
  8480. 1003.1-1988. This format is believed to be old enough to be portable.
  8481. It fully supports empty directories. It can store file names with up
  8482. to 256 characters, provided that the file name can be split at
  8483. directory separator in two parts, first of them being at most 155
  8484. bytes long. So, in most cases the maximum file name length will be
  8485. shorter than 256 characters. However you may run against broken tar
  8486. implementations that incorrectly handle file names longer than 99
  8487. characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
  8488. can document this accurately).
  8489. @option{tar-pax} selects the new pax interchange format defined by POSIX
  8490. 1003.1-2001. It does not limit the length of file names. However,
  8491. this format is very young and should probably be restricted to
  8492. packages that target only very modern platforms. There are moves to
  8493. change the pax format in an upward-compatible way, so this option may
  8494. refer to a more recent version in the future.
  8495. @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
  8496. further discussion about tar formats.
  8497. @command{configure} knows several ways to construct these formats. It
  8498. will not abort if it cannot find a tool up to the task (so that the
  8499. package can still be built), but @samp{make dist} will fail.
  8500. @item @var{version}
  8501. @cindex Option, @var{version}
  8502. A version number (e.g., @samp{0.30}) can be specified. If Automake is not
  8503. newer than the version specified, creation of the @file{Makefile.in}
  8504. will be suppressed.
  8505. @item @option{-W@var{category}} or @option{--warnings=@var{category}}
  8506. @cindex Option, warnings
  8507. @cindex Option, @option{-W@var{category}}
  8508. @cindex Option, @option{--warnings=@var{category}}
  8509. These options behave exactly like their command-line counterpart
  8510. (@pxref{automake Invocation}). This allows you to enable or disable some
  8511. warning categories on a per-file basis. You can also setup some warnings
  8512. for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
  8513. in your @file{configure.ac}.
  8514. @end table
  8515. Unrecognized options are diagnosed by @command{automake}.
  8516. If you want an option to apply to all the files in the tree, you can use
  8517. the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
  8518. @xref{Macros}.
  8519. @node Miscellaneous
  8520. @chapter Miscellaneous Rules
  8521. There are a few rules and variables that didn't fit anywhere else.
  8522. @menu
  8523. * Tags:: Interfacing to cscope, etags and mkid
  8524. * Suffixes:: Handling new file extensions
  8525. @end menu
  8526. @node Tags
  8527. @section Interfacing to @command{etags}
  8528. @cindex @file{TAGS} support
  8529. Automake will generate rules to generate @file{TAGS} files for use with
  8530. GNU Emacs under some circumstances.
  8531. @trindex tags
  8532. If any C, C++ or Fortran 77 source code or headers are present, then
  8533. @code{tags} and @code{TAGS} rules will be generated for the directory.
  8534. All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
  8535. @code{_LISP} primaries will be used to generate tags. Note that
  8536. generated source files that are not distributed must be declared in
  8537. variables like @code{nodist_noinst_HEADERS} or
  8538. @code{nodist_@var{prog}_SOURCES} or they will be ignored.
  8539. A @code{tags} rule will be output at the topmost directory of a
  8540. multi-directory package. When run from this topmost directory,
  8541. @samp{make tags} will generate a @file{TAGS} file that includes by
  8542. reference all @file{TAGS} files from subdirectories.
  8543. The @code{tags} rule will also be generated if the variable
  8544. @code{ETAGS_ARGS} is defined. This variable is intended for use in
  8545. directories that contain taggable source that @command{etags} does
  8546. not understand. The user can use the @code{ETAGSFLAGS} to pass
  8547. additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
  8548. available for use in @file{Makefile.am}.
  8549. @vindex ETAGS_ARGS
  8550. @vindex ETAGSFLAGS
  8551. @vindex AM_ETAGSFLAGS
  8552. Here is how Automake generates tags for its source, and for nodes in its
  8553. Texinfo file:
  8554. @example
  8555. ETAGS_ARGS = automake.in --lang=none \
  8556. --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
  8557. @end example
  8558. If you add file names to @code{ETAGS_ARGS}, you will probably also
  8559. want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
  8560. are added directly to the dependencies for the @code{tags} rule.
  8561. @vindex TAGS_DEPENDENCIES
  8562. Automake also generates a @code{ctags} rule that can be used to
  8563. build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
  8564. is the name of the program to invoke (by default @command{ctags});
  8565. @code{CTAGSFLAGS} can be used by the user to pass additional flags,
  8566. and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
  8567. @trindex id
  8568. Automake will also generate an @code{ID} rule that will run
  8569. @command{mkid} on the source. This is only supported on a
  8570. directory-by-directory basis.
  8571. Similarly, the @code{cscope} rule will create a list of all the source
  8572. files in the tree and run @command{cscope} to build an inverted index
  8573. database. The variable @code{CSCOPE} is the name of the program to invoke
  8574. (by default @command{cscope}); @code{CSCOPEFLAGS} and
  8575. @code{CSCOPE_ARGS} can be used by the user to pass additional flags and
  8576. file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
  8577. @file{Makefile.am}. Note that, currently, the Automake-provided
  8578. @code{cscope} support, when used in a VPATH build, might not work well
  8579. with non-GNU make implementations (especially with make implementations
  8580. performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
  8581. The Autoconf Manual}).
  8582. Finally, Automake also emits rules to support the
  8583. @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
  8584. The @code{GTAGS} rule runs Global Tags and puts the
  8585. result in the top build directory. The variable @code{GTAGS_ARGS}
  8586. holds arguments that are passed to @command{gtags}.
  8587. @vindex GTAGS_ARGS
  8588. @node Suffixes
  8589. @section Handling new file extensions
  8590. @cindex Adding new @code{SUFFIXES}
  8591. @cindex @code{SUFFIXES}, adding
  8592. @vindex SUFFIXES
  8593. It is sometimes useful to introduce a new implicit rule to handle a file
  8594. type that Automake does not know about.
  8595. For instance, suppose you had a compiler that could compile @file{.foo}
  8596. files to @file{.o} files. You would simply define a suffix rule for
  8597. your language:
  8598. @example
  8599. .foo.o:
  8600. foocc -c -o $@@ $<
  8601. @end example
  8602. Then you could directly use a @file{.foo} file in a @code{_SOURCES}
  8603. variable and expect the correct results:
  8604. @example
  8605. bin_PROGRAMS = doit
  8606. doit_SOURCES = doit.foo
  8607. @end example
  8608. This was the simpler and more common case. In other cases, you will
  8609. have to help Automake to figure out which extensions you are defining your
  8610. suffix rule for. This usually happens when your extension does not
  8611. start with a dot. Then, all you have to do is to put a list of new
  8612. suffixes in the @code{SUFFIXES} variable @strong{before} you define your
  8613. implicit rule.
  8614. For instance, the following definition prevents Automake from misinterpreting
  8615. the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
  8616. @file{.cpp} files.
  8617. @c Keep in sync with suffix7.sh
  8618. @example
  8619. SUFFIXES = .idl C.cpp
  8620. .idlC.cpp:
  8621. # whatever
  8622. @end example
  8623. As you may have noted, the @code{SUFFIXES} variable behaves like the
  8624. @code{.SUFFIXES} special target of @command{make}. You should not touch
  8625. @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
  8626. Automake generate the suffix list for @code{.SUFFIXES}. Any given
  8627. @code{SUFFIXES} go at the start of the generated suffixes list, followed
  8628. by Automake generated suffixes not already in the list.
  8629. @node Include
  8630. @chapter Include
  8631. @cmindex include
  8632. @cindex Including @file{Makefile} fragment
  8633. @cindex @file{Makefile} fragment, including
  8634. Automake supports an @code{include} directive that can be used to
  8635. include other @file{Makefile} fragments when @command{automake} is run.
  8636. Note that these fragments are read and interpreted by @command{automake},
  8637. not by @command{make}. As with conditionals, @command{make} has no idea that
  8638. @code{include} is in use.
  8639. There are two forms of @code{include}:
  8640. @table @code
  8641. @item include $(srcdir)/file
  8642. Include a fragment that is found relative to the current source
  8643. directory.
  8644. @item include $(top_srcdir)/file
  8645. Include a fragment that is found relative to the top source directory.
  8646. @end table
  8647. Note that if a fragment is included inside a conditional, then the
  8648. condition applies to the entire contents of that fragment.
  8649. Makefile fragments included this way are always distributed because
  8650. they are needed to rebuild @file{Makefile.in}.
  8651. Inside a fragment, the construct @code{%reldir%} is replaced with the
  8652. directory of the fragment relative to the base @file{Makefile.am}.
  8653. Similarly, @code{%canon_reldir%} is replaced with the canonicalized
  8654. (@pxref{Canonicalization}) form of @code{%reldir%}. As a convenience,
  8655. @code{%D%} is a synonym for @code{%reldir%}, and @code{%C%}
  8656. is a synonym for @code{%canon_reldir%}.
  8657. A special feature is that if the fragment is in the same directory as
  8658. the base @file{Makefile.am} (i.e., @code{%reldir%} is @code{.}), then
  8659. @code{%reldir%} and @code{%canon_reldir%} will expand to the empty
  8660. string as well as eat, if present, a following slash or underscore
  8661. respectively.
  8662. Thus, a makefile fragment might look like this:
  8663. @example
  8664. bin_PROGRAMS += %reldir%/mumble
  8665. %canon_reldir%_mumble_SOURCES = %reldir%/one.c
  8666. @end example
  8667. @node Conditionals
  8668. @chapter Conditionals
  8669. @cindex Conditionals
  8670. Automake supports a simple type of conditionals.
  8671. These conditionals are not the same as conditionals in
  8672. GNU Make. Automake conditionals are checked at configure time by the
  8673. @file{configure} script, and affect the translation from
  8674. @file{Makefile.in} to @file{Makefile}. They are based on options passed
  8675. to @file{configure} and on results that @file{configure} has discovered
  8676. about the host system. GNU Make conditionals are checked at @command{make}
  8677. time, and are based on variables passed to the make program or defined
  8678. in the @file{Makefile}.
  8679. Automake conditionals will work with any make program.
  8680. @menu
  8681. * Usage of Conditionals:: Declaring conditional content
  8682. * Limits of Conditionals:: Enclosing complete statements
  8683. @end menu
  8684. @node Usage of Conditionals
  8685. @section Usage of Conditionals
  8686. @acindex AM_CONDITIONAL
  8687. Before using a conditional, you must define it by using
  8688. @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
  8689. @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
  8690. The conditional name, @var{conditional}, should be a simple string
  8691. starting with a letter and containing only letters, digits, and
  8692. underscores. It must be different from @samp{TRUE} and @samp{FALSE}
  8693. that are reserved by Automake.
  8694. The shell @var{condition} (suitable for use in a shell @code{if}
  8695. statement) is evaluated when @command{configure} is run. Note that you
  8696. must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
  8697. time @command{configure} is run. If @code{AM_CONDITIONAL} is run
  8698. conditionally (e.g., in a shell @code{if} statement), then the result
  8699. will confuse @command{automake}.
  8700. @end defmac
  8701. @cindex @option{--enable-debug}, example
  8702. @cindex Example conditional @option{--enable-debug}
  8703. @cindex Conditional example, @option{--enable-debug}
  8704. Conditionals typically depend upon options that the user provides to
  8705. the @command{configure} script. Here is an example of how to write a
  8706. conditional that is true if the user uses the @option{--enable-debug}
  8707. option.
  8708. @example
  8709. AC_ARG_ENABLE([debug],
  8710. [ --enable-debug Turn on debugging],
  8711. [case "$@{enableval@}" in
  8712. yes) debug=true ;;
  8713. no) debug=false ;;
  8714. *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
  8715. esac],[debug=false])
  8716. AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
  8717. @end example
  8718. Here is an example of how to use that conditional in @file{Makefile.am}:
  8719. @cmindex if
  8720. @cmindex endif
  8721. @cmindex else
  8722. @example
  8723. if DEBUG
  8724. DBG = debug
  8725. else
  8726. DBG =
  8727. endif
  8728. noinst_PROGRAMS = $(DBG)
  8729. @end example
  8730. This trivial example could also be handled using @code{EXTRA_PROGRAMS}
  8731. (@pxref{Conditional Programs}).
  8732. You may only test a single variable in an @code{if} statement, possibly
  8733. negated using @samp{!}. The @code{else} statement may be omitted.
  8734. Conditionals may be nested to any depth. You may specify an argument to
  8735. @code{else} in which case it must be the negation of the condition used
  8736. for the current @code{if}. Similarly you may specify the condition
  8737. that is closed on the @code{endif} line:
  8738. @example
  8739. if DEBUG
  8740. DBG = debug
  8741. else !DEBUG
  8742. DBG =
  8743. endif !DEBUG
  8744. @end example
  8745. @noindent
  8746. Unbalanced conditions are errors. The @code{if}, @code{else}, and
  8747. @code{endif} statements should not be indented, i.e., start on column
  8748. one.
  8749. The @code{else} branch of the above two examples could be omitted,
  8750. since assigning the empty string to an otherwise undefined variable
  8751. makes no difference.
  8752. @acindex AM_COND_IF
  8753. In order to allow access to the condition registered by
  8754. @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
  8755. conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
  8756. @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
  8757. If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
  8758. execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
  8759. it will cause @command{automake} to output the rules for the respective
  8760. files only for the given condition.
  8761. @end defmac
  8762. @code{AM_COND_IF} macros may be nested when m4 quotation is used
  8763. properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
  8764. @cindex Example conditional @code{AC_CONFIG_FILES}
  8765. @cindex @code{AC_CONFIG_FILES}, conditional
  8766. Here is an example of how to define a conditional config file:
  8767. @example
  8768. AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
  8769. AM_COND_IF([SHELL_WRAPPER],
  8770. [AC_CONFIG_FILES([wrapper:wrapper.in])])
  8771. @end example
  8772. @node Limits of Conditionals
  8773. @section Limits of Conditionals
  8774. Conditionals should enclose complete statements like variables or
  8775. rules definitions. Automake cannot deal with conditionals used inside
  8776. a variable definition, for instance, and is not even able to diagnose
  8777. this situation. The following example would not work:
  8778. @example
  8779. # This syntax is not understood by Automake
  8780. AM_CPPFLAGS = \
  8781. -DFEATURE_A \
  8782. if WANT_DEBUG
  8783. -DDEBUG \
  8784. endif
  8785. -DFEATURE_B
  8786. @end example
  8787. However the intended definition of @code{AM_CPPFLAGS} can be achieved
  8788. with
  8789. @example
  8790. if WANT_DEBUG
  8791. DEBUGFLAGS = -DDEBUG
  8792. endif
  8793. AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
  8794. @end example
  8795. @noindent
  8796. or
  8797. @example
  8798. AM_CPPFLAGS = -DFEATURE_A
  8799. if WANT_DEBUG
  8800. AM_CPPFLAGS += -DDEBUG
  8801. endif
  8802. AM_CPPFLAGS += -DFEATURE_B
  8803. @end example
  8804. More details and examples of conditionals are described alongside
  8805. various Automake features in this manual (@pxref{Conditional
  8806. Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
  8807. Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
  8808. Libtool Sources}).
  8809. @node Silencing Make
  8810. @chapter Silencing @command{make}
  8811. @cindex Silent @command{make}
  8812. @cindex Silencing @command{make}
  8813. @cindex Silent rules
  8814. @cindex Silent @command{make} rules
  8815. @menu
  8816. * Make verbosity:: Make is verbose by default
  8817. * Tricks For Silencing Make:: Standard and generic ways to silence make
  8818. * Automake Silent Rules:: How Automake can help in silencing make
  8819. @end menu
  8820. @node Make verbosity
  8821. @section Make is verbose by default
  8822. Normally, when executing the set of rules associated with a target,
  8823. @command{make} prints each rule before it is executed. This behaviour,
  8824. while having been in place for a long time, and being even mandated by
  8825. the POSIX standard, starkly violates the ``silence is golden'' UNIX
  8826. principle@footnote{See also
  8827. @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
  8828. @quotation
  8829. When a program has nothing interesting or surprising to say, it should
  8830. say nothing. Well-behaved Unix programs do their jobs unobtrusively,
  8831. with a minimum of fuss and bother. Silence is golden.
  8832. @end quotation
  8833. In fact, while such verbosity of @command{make} can theoretically be
  8834. useful to track bugs and understand reasons of failures right away, it
  8835. can also hide warning and error messages from @command{make}-invoked
  8836. tools, drowning them in a flood of uninteresting and seldom useful
  8837. messages, and thus allowing them to go easily undetected.
  8838. This problem can be very annoying, especially for developers, who usually
  8839. know quite well what's going on behind the scenes, and for whom the
  8840. verbose output from @command{make} ends up being mostly noise that hampers
  8841. the easy detection of potentially important warning messages.
  8842. @node Tricks For Silencing Make
  8843. @section Standard and generic ways to silence make
  8844. Here we describe some common idioms/tricks to obtain a quieter make
  8845. output, with their relative advantages and drawbacks. In the next
  8846. section (@ref{Automake Silent Rules}) we'll see how Automake can help
  8847. in this respect, providing more elaborate and flexible idioms.
  8848. @itemize @bullet
  8849. @item @command{make -s}
  8850. This simply causes @command{make} not to print @emph{any} rule before
  8851. executing it.
  8852. The @option{-s} flag is mandated by POSIX, universally supported, and
  8853. its purpose and function are easy to understand.
  8854. But it also has its serious limitations too. First of all, it embodies
  8855. an ``all or nothing'' strategy, i.e., either everything is silenced, or
  8856. nothing is; this lack of granularity can sometimes be a fatal flaw.
  8857. Moreover, when the @option{-s} flag is used, the @command{make} output
  8858. might turn out to be too much terse; in case of errors, the user won't
  8859. be able to easily see what rule or command have caused them, or even,
  8860. in case of tools with poor error reporting, what the errors were!
  8861. @item @command{make >/dev/null || make}
  8862. Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
  8863. from stderr are passed through, output reporting is done only in case of
  8864. error, and in that case it should provide a verbose-enough report to allow
  8865. an easy determination of the error location and causes.
  8866. However, calling @command{make} two times in a row might hide errors
  8867. (especially intermittent ones), or subtly change the expected semantic
  8868. of the @command{make} calls --- things these which can clearly make
  8869. debugging and error assessment very difficult.
  8870. @item @command{make --no-print-directory}
  8871. This is GNU @command{make} specific. When called with the
  8872. @option{--no-print-directory} option, GNU @command{make} will disable
  8873. printing of the working directory by invoked sub-@command{make}s (the
  8874. well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
  8875. to decrease the verbosity of the output, but experience has shown that
  8876. it can also often render debugging considerably harder in projects using
  8877. deeply-nested @command{make} recursion.
  8878. As an aside, notice that the @option{--no-print-directory} option is
  8879. automatically activated if the @option{-s} flag is used.
  8880. @c TODO: Other tricks?
  8881. @c TODO: Maybe speak about the @code{.SILENT} target?
  8882. @c TODO: - Pros: More granularity on what to silence.
  8883. @c TODO: - Cons: No easy way to temporarily override.
  8884. @end itemize
  8885. @node Automake Silent Rules
  8886. @section How Automake can help in silencing make
  8887. The tricks and idioms for silencing @command{make} described in the
  8888. previous section can be useful from time to time, but we've seen that
  8889. they all have their serious drawbacks and limitations. That's why
  8890. automake provides support for a more advanced and flexible way of
  8891. obtaining quieter output from @command{make} (for most rules at least).
  8892. To give the gist of what Automake can do in this respect, here is a simple
  8893. comparison between a typical @command{make} output (where silent rules
  8894. are disabled) and one with silent rules enabled:
  8895. @example
  8896. % @kbd{cat Makefile.am}
  8897. bin_PROGRAMS = foo
  8898. foo_SOURCES = main.c func.c
  8899. % @kbd{cat main.c}
  8900. int main (void) @{ return func (); @} /* func used undeclared */
  8901. % @kbd{cat func.c}
  8902. int func (void) @{ int i; return i; @} /* i used uninitialized */
  8903. @i{The make output is by default very verbose. This causes warnings
  8904. from the compiler to be somewhat hidden, and not immediate to spot.}
  8905. % @kbd{make CFLAGS=-Wall}
  8906. gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
  8907. -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
  8908. -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
  8909. -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
  8910. main.c: In function ‘main’:
  8911. main.c:3:3: warning: implicit declaration of function ‘func’
  8912. mv -f .deps/main.Tpo .deps/main.Po
  8913. gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
  8914. -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
  8915. -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
  8916. -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
  8917. func.c: In function ‘func’:
  8918. func.c:4:3: warning: ‘i’ used uninitialized in this function
  8919. mv -f .deps/func.Tpo .deps/func.Po
  8920. gcc -Wall -o foo main.o func.o
  8921. @i{Clean up, so that we we can rebuild everything from scratch.}
  8922. % @kbd{make clean}
  8923. test -z "foo" || rm -f foo
  8924. rm -f *.o
  8925. @i{Silent rules enabled: the output is minimal but informative. In
  8926. particular, the warnings from the compiler stick out very clearly.}
  8927. % @kbd{make V=0 CFLAGS=-Wall}
  8928. CC main.o
  8929. main.c: In function ‘main’:
  8930. main.c:3:3: warning: implicit declaration of function ‘func’
  8931. CC func.o
  8932. func.c: In function ‘func’:
  8933. func.c:4:3: warning: ‘i’ used uninitialized in this function
  8934. CCLD foo
  8935. @end example
  8936. @cindex silent rules and libtool
  8937. Also, in projects using @command{libtool}, the use of silent rules can
  8938. automatically enable the @command{libtool}'s @option{--silent} option:
  8939. @example
  8940. % @kbd{cat Makefile.am}
  8941. lib_LTLIBRARIES = libx.la
  8942. % @kbd{make # Both make and libtool are verbose by default.}
  8943. ...
  8944. libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
  8945. -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
  8946. -DPIC -o .libs/libx.o
  8947. mv -f .deps/libx.Tpo .deps/libx.Plo
  8948. /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
  8949. /usr/local/lib libx.lo
  8950. libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
  8951. -o .libs/libx.so.0.0.0
  8952. libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
  8953. ...
  8954. % @kbd{make V=0}
  8955. CC libx.lo
  8956. CCLD libx.la
  8957. @end example
  8958. For Automake-generated @file{Makefile}s, the user may influence the
  8959. verbosity at @command{configure} run time as well as at @command{make}
  8960. run time:
  8961. @itemize @bullet
  8962. @item
  8963. @opindex --enable-silent-rules
  8964. @opindex --disable-silent-rules
  8965. Passing @option{--enable-silent-rules} to @command{configure} will cause
  8966. build rules to be less verbose; the option @option{--disable-silent-rules}
  8967. will cause normal verbose output.
  8968. @item
  8969. @vindex @code{V}
  8970. At @command{make} run time, the default chosen at @command{configure}
  8971. time may be overridden: @code{make V=1} will produce verbose output,
  8972. @code{make V=0} less verbose output.
  8973. @end itemize
  8974. @cindex default verbosity for silent rules
  8975. Note that silent rules are @emph{disabled} by default; the user must
  8976. enable them explicitly at either @command{configure} run time or at
  8977. @command{make} run time. We think that this is a good policy, since
  8978. it provides the casual user with enough information to prepare a good
  8979. bug report in case anything breaks.
  8980. Still, notwithstanding the rationales above, a developer who really
  8981. wants to make silent rules enabled by default in his own package can
  8982. do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
  8983. @c Keep in sync with silent-configsite.sh
  8984. Users who prefer to have silent rules enabled by default can edit their
  8985. @file{config.site} file to make the variable @code{enable_silent_rules}
  8986. default to @samp{yes}. This should still allow disabling silent rules
  8987. at @command{configure} time and at @command{make} time.
  8988. @c FIXME: there's really a need to specify this explicitly?
  8989. For portability to different @command{make} implementations, package authors
  8990. are advised to not set the variable @code{V} inside the @file{Makefile.am}
  8991. file, to allow the user to override the value for subdirectories as well.
  8992. To work at its best, the current implementation of this feature normally
  8993. uses nested variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile}
  8994. feature that is not required by POSIX 2008 but is widely supported in
  8995. practice. On the rare @command{make} implementations that do not support
  8996. nested variable expansion, whether rules are silent is always determined at
  8997. configure time, and cannot be overridden at make time. Future versions of
  8998. POSIX are likely to require nested variable expansion, so this minor
  8999. limitation should go away with time.
  9000. @vindex @code{AM_V_GEN}
  9001. @vindex @code{AM_V_at}
  9002. @vindex @code{AM_DEFAULT_VERBOSITY}
  9003. @vindex @code{AM_V}
  9004. @vindex @code{AM_DEFAULT_V}
  9005. To extend the silent mode to your own rules, you have few choices:
  9006. @itemize @bullet
  9007. @item
  9008. You can use the predefined variable @code{AM_V_GEN} as a prefix to
  9009. commands that should output a status line in silent mode, and
  9010. @code{AM_V_at} as a prefix to commands that should not output anything
  9011. in silent mode. When output is to be verbose, both of these variables
  9012. will expand to the empty string.
  9013. @item
  9014. You can silence a recipe unconditionally with @code{@@}, and then use
  9015. the predefined variable @code{AM_V_P} to know whether make is being run
  9016. in silent or verbose mode, adjust the verbose information your recipe
  9017. displays accordingly:
  9018. @example
  9019. generate-headers:
  9020. @set -e; \
  9021. ... [commands defining a shell variable '$headers'] ...; \
  9022. if $(AM_V_P); then set -x; else echo " GEN [headers]"; fi; \
  9023. rm -f $$headers && generate-header --flags $$headers
  9024. @end example
  9025. @item
  9026. You can add your own variables, so strings of your own choice are shown.
  9027. The following snippet shows how you would define your own equivalent of
  9028. @code{AM_V_GEN}:
  9029. @example
  9030. pkg_verbose = $(pkg_verbose_@@AM_V@@)
  9031. pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
  9032. pkg_verbose_0 = @@echo PKG-GEN $@@;
  9033. foo: foo.in
  9034. $(pkg_verbose)cp $(srcdir)/foo.in $@@
  9035. @end example
  9036. @end itemize
  9037. As a final note, observe that, even when silent rules are enabled,
  9038. the @option{--no-print-directory} option is still required with GNU
  9039. @command{make} if the ``@i{Entering/Leaving directory ...}'' messages
  9040. are to be disabled.
  9041. @node Gnits
  9042. @chapter The effect of @option{--gnu} and @option{--gnits}
  9043. @cindex @option{--gnu}, required files
  9044. @cindex @option{--gnu}, complete description
  9045. The @option{--gnu} option (or @option{gnu} in the
  9046. @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
  9047. the following:
  9048. @itemize @bullet
  9049. @item
  9050. The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
  9051. and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
  9052. or @file{COPYING}, are required at the topmost directory of the package.
  9053. If the @option{--add-missing} option is given, @command{automake} will
  9054. add a generic version of the @file{INSTALL} file as well as the
  9055. @file{COPYING} file containing the text of the current version of the
  9056. GNU General Public License existing at the time of this Automake release
  9057. (version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
  9058. However, an existing @file{COPYING} file will never be overwritten by
  9059. @command{automake}.
  9060. @item
  9061. The options @option{no-installman} and @option{no-installinfo} are
  9062. prohibited.
  9063. @end itemize
  9064. Note that this option will be extended in the future to do even more
  9065. checking; it is advisable to be familiar with the precise requirements
  9066. of the GNU standards. Also, @option{--gnu} can require certain
  9067. non-standard GNU programs to exist for use by various maintainer-only
  9068. rules; for instance, in the future @command{pathchk} might be required for
  9069. @samp{make dist}.
  9070. @cindex @option{--gnits}, complete description
  9071. The @option{--gnits} option does everything that @option{--gnu} does, and
  9072. checks the following as well:
  9073. @itemize @bullet
  9074. @item
  9075. @samp{make installcheck} will check to make sure that the @option{--help}
  9076. and @option{--version} really print a usage message and a version string,
  9077. respectively. This is the @option{std-options} option (@pxref{Options}).
  9078. @item
  9079. @samp{make dist} will check to make sure the @file{NEWS} file has been
  9080. updated to the current version.
  9081. @item
  9082. @code{VERSION} is checked to make sure its format complies with Gnits
  9083. standards.
  9084. @c FIXME xref when standards are finished
  9085. @item
  9086. @cindex @file{README-alpha}
  9087. If @code{VERSION} indicates that this is an alpha release, and the file
  9088. @file{README-alpha} appears in the topmost directory of a package, then
  9089. it is included in the distribution. This is done in @option{--gnits}
  9090. mode, and no other, because this mode is the only one where version
  9091. number formats are constrained, and hence the only mode where Automake
  9092. can automatically determine whether @file{README-alpha} should be
  9093. included.
  9094. @item
  9095. The file @file{THANKS} is required.
  9096. @end itemize
  9097. @node Not Enough
  9098. @chapter When Automake Isn't Enough
  9099. In some situations, where Automake is not up to one task, one has to
  9100. resort to handwritten rules or even handwritten @file{Makefile}s.
  9101. @menu
  9102. * Extending:: Adding new rules or overriding existing ones.
  9103. * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
  9104. @end menu
  9105. @node Extending
  9106. @section Extending Automake Rules
  9107. With some minor exceptions (for example @code{_PROGRAMS} variables,
  9108. @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
  9109. @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
  9110. @file{Makefile.in} verbatim.
  9111. @cindex copying semantics
  9112. These copying semantics mean that many problems can be worked around
  9113. by simply adding some @command{make} variables and rules to
  9114. @file{Makefile.am}. Automake will ignore these additions.
  9115. @cindex conflicting definitions
  9116. @cindex rules, conflicting
  9117. @cindex variables, conflicting
  9118. @cindex definitions, conflicts
  9119. Since a @file{Makefile.in} is built from data gathered from three
  9120. different places (@file{Makefile.am}, @file{configure.ac}, and
  9121. @command{automake} itself), it is possible to have conflicting
  9122. definitions of rules or variables. When building @file{Makefile.in}
  9123. the following priorities are respected by @command{automake} to ensure
  9124. the user always has the last word:
  9125. @itemize
  9126. @item
  9127. User defined variables in @file{Makefile.am} have priority over
  9128. variables @code{AC_SUBST}ed from @file{configure.ac}, and
  9129. @code{AC_SUBST}ed variables have priority over
  9130. @command{automake}-defined variables.
  9131. @item
  9132. As far as rules are concerned, a user-defined rule overrides any
  9133. @command{automake}-defined rule for the same target.
  9134. @end itemize
  9135. @cindex overriding rules
  9136. @cindex overriding semantics
  9137. @cindex rules, overriding
  9138. These overriding semantics make it possible to fine tune some default
  9139. settings of Automake, or replace some of its rules. Overriding
  9140. Automake rules is often inadvisable, particularly in the topmost
  9141. directory of a package with subdirectories. The @option{-Woverride}
  9142. option (@pxref{automake Invocation}) comes in handy to catch overridden
  9143. definitions.
  9144. Note that Automake does not make any distinction between rules with
  9145. commands and rules that only specify dependencies. So it is not
  9146. possible to append new dependencies to an @command{automake}-defined
  9147. target without redefining the entire rule.
  9148. @cindex @option{-local} targets
  9149. @cindex local targets
  9150. However, various useful targets have a @samp{-local} version you can
  9151. specify in your @file{Makefile.am}. Automake will supplement the
  9152. standard target with these user-supplied targets.
  9153. @trindex all
  9154. @trindex all-local
  9155. @trindex info
  9156. @trindex info-local
  9157. @trindex dvi
  9158. @trindex dvi-local
  9159. @trindex ps
  9160. @trindex ps-local
  9161. @trindex pdf
  9162. @trindex pdf-local
  9163. @trindex html
  9164. @trindex html-local
  9165. @trindex check
  9166. @trindex check-local
  9167. @trindex install
  9168. @trindex install-data
  9169. @trindex install-data-local
  9170. @trindex install-dvi
  9171. @trindex install-dvi-local
  9172. @trindex install-exec
  9173. @trindex install-exec-local
  9174. @trindex install-html
  9175. @trindex install-html-local
  9176. @trindex install-info
  9177. @trindex install-info-local
  9178. @trindex install-pdf
  9179. @trindex install-pdf-local
  9180. @trindex install-ps
  9181. @trindex install-ps-local
  9182. @trindex uninstall
  9183. @trindex uninstall-local
  9184. @trindex mostlyclean
  9185. @trindex mostlyclean-local
  9186. @trindex clean
  9187. @trindex clean-local
  9188. @trindex distclean
  9189. @trindex distclean-local
  9190. @trindex installdirs
  9191. @trindex installdirs-local
  9192. @trindex installcheck
  9193. @trindex installcheck-local
  9194. The targets that support a local version are @code{all}, @code{info},
  9195. @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
  9196. @code{install-data}, @code{install-dvi}, @code{install-exec},
  9197. @code{install-html}, @code{install-info}, @code{install-pdf},
  9198. @code{install-ps}, @code{uninstall}, @code{installdirs},
  9199. @code{installcheck} and the various @code{clean} targets
  9200. (@code{mostlyclean}, @code{clean}, @code{distclean}, and
  9201. @code{maintainer-clean}).
  9202. Note that there are no @code{uninstall-exec-local} or
  9203. @code{uninstall-data-local} targets; just use @code{uninstall-local}.
  9204. It doesn't make sense to uninstall just data or just executables.
  9205. For instance, here is one way to erase a subdirectory during
  9206. @samp{make clean} (@pxref{Clean}).
  9207. @example
  9208. clean-local:
  9209. -rm -rf testSubDir
  9210. @end example
  9211. You may be tempted to use @code{install-data-local} to install a file
  9212. to some hard-coded location, but you should avoid this
  9213. (@pxref{Hard-Coded Install Paths}).
  9214. With the @code{-local} targets, there is no particular guarantee of
  9215. execution order; typically, they are run early, but with parallel
  9216. make, there is no way to be sure of that.
  9217. @cindex @option{-hook} targets
  9218. @cindex hook targets
  9219. @trindex install-data-hook
  9220. @trindex install-exec-hook
  9221. @trindex uninstall-hook
  9222. @trindex dist-hook
  9223. In contrast, some rules also have a way to run another rule, called a
  9224. @dfn{hook}; hooks are always executed after the main rule's work is done.
  9225. The hook is named after the principal target, with @samp{-hook} appended.
  9226. The targets allowing hooks are @code{install-data},
  9227. @code{install-exec}, @code{uninstall}, @code{dist}, and
  9228. @code{distcheck}.
  9229. For instance, here is how to create a hard link to an installed program:
  9230. @example
  9231. install-exec-hook:
  9232. ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
  9233. $(DESTDIR)$(bindir)/proglink$(EXEEXT)
  9234. @end example
  9235. Although cheaper and more portable than symbolic links, hard links
  9236. will not work everywhere (for instance, OS/2 does not have
  9237. @command{ln}). Ideally you should fall back to @samp{cp -p} when
  9238. @command{ln} does not work. An easy way, if symbolic links are
  9239. acceptable to you, is to add @code{AC_PROG_LN_S} to
  9240. @file{configure.ac} (@pxref{Particular Programs, , Particular Program
  9241. Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
  9242. @file{Makefile.am}.
  9243. @cindex versioned binaries, installing
  9244. @cindex installing versioned binaries
  9245. @cindex @code{LN_S} example
  9246. For instance, here is how you could install a versioned copy of a
  9247. program using @samp{$(LN_S)}:
  9248. @c Keep in sync with insthook.sh
  9249. @example
  9250. install-exec-hook:
  9251. cd $(DESTDIR)$(bindir) && \
  9252. mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
  9253. $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
  9254. @end example
  9255. Note that we rename the program so that a new version will erase the
  9256. symbolic link, not the real binary. Also we @command{cd} into the
  9257. destination directory in order to create relative links.
  9258. When writing @code{install-exec-hook} or @code{install-data-hook},
  9259. please bear in mind that the exec/data distinction is based on the
  9260. installation directory, not on the primary used (@pxref{The Two Parts of
  9261. Install}).
  9262. @c Keep in sync with primary-prefix-couples-documented-valid.sh
  9263. So a @code{foo_SCRIPTS} will be installed by
  9264. @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
  9265. @code{install-exec}. You should define your hooks consequently.
  9266. @c FIXME should include discussion of variables you can use in these
  9267. @c rules
  9268. @node Third-Party Makefiles
  9269. @section Third-Party @file{Makefile}s
  9270. @cindex Third-party packages, interfacing with
  9271. @cindex Interfacing with third-party packages
  9272. In most projects all @file{Makefile}s are generated by Automake. In
  9273. some cases, however, projects need to embed subdirectories with
  9274. handwritten @file{Makefile}s. For instance, one subdirectory could be
  9275. a third-party project with its own build system, not using Automake.
  9276. It is possible to list arbitrary directories in @code{SUBDIRS} or
  9277. @code{DIST_SUBDIRS} provided each of these directories has a
  9278. @file{Makefile} that recognizes all the following recursive targets.
  9279. @cindex recursive targets and third-party @file{Makefile}s
  9280. When a user runs one of these targets, that target is run recursively
  9281. in all subdirectories. This is why it is important that even
  9282. third-party @file{Makefile}s support them.
  9283. @table @code
  9284. @item all
  9285. Compile the entire package. This is the default target in
  9286. Automake-generated @file{Makefile}s, but it does not need to be the
  9287. default in third-party @file{Makefile}s.
  9288. @item distdir
  9289. @trindex distdir
  9290. @vindex distdir
  9291. @vindex top_distdir
  9292. Copy files to distribute into @samp{$(distdir)}, before a tarball is
  9293. constructed. Of course this target is not required if the
  9294. @option{no-dist} option (@pxref{Options}) is used.
  9295. The variables @samp{$(top_distdir)} and @samp{$(distdir)}
  9296. (@pxref{The dist Hook}) will be passed from the outer package to the subpackage
  9297. when the @code{distdir} target is invoked. These two variables have
  9298. been adjusted for the directory that is being recursed into, so they
  9299. are ready to use.
  9300. @item install
  9301. @itemx install-data
  9302. @itemx install-exec
  9303. @itemx uninstall
  9304. Install or uninstall files (@pxref{Install}).
  9305. @item install-dvi
  9306. @itemx install-html
  9307. @itemx install-info
  9308. @itemx install-ps
  9309. @itemx install-pdf
  9310. Install only some specific documentation format (@pxref{Texinfo}).
  9311. @item installdirs
  9312. Create install directories, but do not install any files.
  9313. @item check
  9314. @itemx installcheck
  9315. Check the package (@pxref{Tests}).
  9316. @item mostlyclean
  9317. @itemx clean
  9318. @itemx distclean
  9319. @itemx maintainer-clean
  9320. Cleaning rules (@pxref{Clean}).
  9321. @item dvi
  9322. @itemx pdf
  9323. @itemx ps
  9324. @itemx info
  9325. @itemx html
  9326. Build the documentation in various formats (@pxref{Texinfo}).
  9327. @item tags
  9328. @itemx ctags
  9329. Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
  9330. @end table
  9331. If you have ever used Gettext in a project, this is a good example of
  9332. how third-party @file{Makefile}s can be used with Automake. The
  9333. @file{Makefile}s @command{gettextize} puts in the @file{po/} and
  9334. @file{intl/} directories are handwritten @file{Makefile}s that
  9335. implement all of these targets. That way they can be added to
  9336. @code{SUBDIRS} in Automake packages.
  9337. Directories that are only listed in @code{DIST_SUBDIRS} but not in
  9338. @code{SUBDIRS} need only the @code{distclean},
  9339. @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
  9340. Subdirectories}).
  9341. Usually, many of these rules are irrelevant to the third-party
  9342. subproject, but they are required for the whole package to work. It's
  9343. OK to have a rule that does nothing, so if you are integrating a
  9344. third-party project with no documentation or tag support, you could
  9345. simply augment its @file{Makefile} as follows:
  9346. @example
  9347. EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
  9348. .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
  9349. $(EMPTY_AUTOMAKE_TARGETS):
  9350. @end example
  9351. Another aspect of integrating third-party build systems is whether
  9352. they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
  9353. subpackage does not support VPATH builds the whole package will not
  9354. support VPATH builds. This in turns means that @samp{make distcheck}
  9355. will not work, because it relies on VPATH builds. Some people can
  9356. live without this (actually, many Automake users have never heard of
  9357. @samp{make distcheck}). Other people may prefer to revamp the
  9358. existing @file{Makefile}s to support VPATH@. Doing so does not
  9359. necessarily require Automake, only Autoconf is needed (@pxref{Build
  9360. Directories, , Build Directories, autoconf, The Autoconf Manual}).
  9361. The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
  9362. and @samp{@@top_builddir@@} are defined by @file{configure} when it
  9363. processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
  9364. Output Variables, autoconf, The Autoconf Manual}), they are not
  9365. computed by the Makefile like the aforementioned @samp{$(distdir)} and
  9366. @samp{$(top_distdir)} variables.
  9367. It is sometimes inconvenient to modify a third-party @file{Makefile}
  9368. to introduce the above required targets. For instance, one may want to
  9369. keep the third-party sources untouched to ease upgrades to new
  9370. versions.
  9371. @cindex @file{GNUmakefile} including @file{Makefile}
  9372. Here are two other ideas. If GNU make is assumed, one possibility is
  9373. to add to that subdirectory a @file{GNUmakefile} that defines the
  9374. required targets and includes the third-party @file{Makefile}. For
  9375. this to work in VPATH builds, @file{GNUmakefile} must lie in the build
  9376. directory; the easiest way to do this is to write a
  9377. @file{GNUmakefile.in} instead, and have it processed with
  9378. @code{AC_CONFIG_FILES} from the outer package. For example if we
  9379. assume @file{Makefile} defines all targets except the documentation
  9380. targets, and that the @code{check} target is actually called
  9381. @code{test}, we could write @file{GNUmakefile} (or
  9382. @file{GNUmakefile.in}) like this:
  9383. @example
  9384. # First, include the real Makefile
  9385. include Makefile
  9386. # Then, define the other targets needed by Automake Makefiles.
  9387. .PHONY: dvi pdf ps info html check
  9388. dvi pdf ps info html:
  9389. check: test
  9390. @end example
  9391. @cindex Proxy @file{Makefile} for third-party packages
  9392. A similar idea that does not use @code{include} is to write a proxy
  9393. @file{Makefile} that dispatches rules to the real @file{Makefile},
  9394. either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
  9395. it's OK to rename the original @file{Makefile}) or with @samp{cd
  9396. subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
  9397. subdirectory project one directory deeper). The good news is that
  9398. this proxy @file{Makefile} can be generated with Automake. All we
  9399. need are @option{-local} targets (@pxref{Extending}) that perform the
  9400. dispatch. Of course the other Automake features are available, so you
  9401. could decide to let Automake perform distribution or installation.
  9402. Here is a possible @file{Makefile.am}:
  9403. @example
  9404. all-local:
  9405. cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
  9406. check-local:
  9407. cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
  9408. clean-local:
  9409. cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
  9410. # Assuming the package knows how to install itself
  9411. install-data-local:
  9412. cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
  9413. install-exec-local:
  9414. cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
  9415. uninstall-local:
  9416. cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
  9417. # Distribute files from here.
  9418. EXTRA_DIST = subdir/Makefile subdir/program.c ...
  9419. @end example
  9420. Pushing this idea to the extreme, it is also possible to ignore the
  9421. subproject build system and build everything from this proxy
  9422. @file{Makefile.am}. This might sound very sensible if you need VPATH
  9423. builds but the subproject does not support them.
  9424. @node Distributing
  9425. @chapter Distributing @file{Makefile.in}s
  9426. Automake places no restrictions on the distribution of the resulting
  9427. @file{Makefile.in}s. We still encourage software authors to
  9428. distribute their work under terms like those of the GPL, but doing so
  9429. is not required to use Automake.
  9430. Some of the files that can be automatically installed via the
  9431. @option{--add-missing} switch do fall under the GPL@. However, these also
  9432. have a special exception allowing you to distribute them with your
  9433. package, regardless of the licensing you choose.
  9434. @node API Versioning
  9435. @chapter Automake API Versioning
  9436. New Automake releases usually include bug fixes and new features.
  9437. Unfortunately they may also introduce new bugs and incompatibilities.
  9438. This makes four reasons why a package may require a particular Automake
  9439. version.
  9440. Things get worse when maintaining a large tree of packages, each one
  9441. requiring a different version of Automake. In the past, this meant that
  9442. any developer (and sometimes users) had to install several versions of
  9443. Automake in different places, and switch @samp{$PATH} appropriately for
  9444. each package.
  9445. Starting with version 1.6, Automake installs versioned binaries. This
  9446. means you can install several versions of Automake in the same
  9447. @samp{$prefix}, and can select an arbitrary Automake version by running
  9448. @command{automake-1.6} or @command{automake-1.7} without juggling with
  9449. @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
  9450. will use @command{automake-1.6} explicitly in their rebuild rules.
  9451. The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
  9452. not Automake's version. If a bug fix release is made, for instance
  9453. Automake 1.6.1, the API version will remain 1.6. This means that a
  9454. package that works with Automake 1.6 should also work with 1.6.1; after
  9455. all, this is what people expect from bug fix releases.
  9456. If your package relies on a feature or a bug fix introduced in
  9457. a release, you can pass this version as an option to Automake to ensure
  9458. older releases will not be used. For instance, use this in your
  9459. @file{configure.ac}:
  9460. @example
  9461. AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
  9462. @end example
  9463. @noindent
  9464. or, in a particular @file{Makefile.am}:
  9465. @example
  9466. AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
  9467. @end example
  9468. @noindent
  9469. Automake will print an error message if its version is
  9470. older than the requested version.
  9471. @heading What is in the API
  9472. Automake's programming interface is not easy to define. Basically it
  9473. should include at least all @strong{documented} variables and targets
  9474. that a @file{Makefile.am} author can use, any behavior associated with
  9475. them (e.g., the places where @samp{-hook}'s are run), the command line
  9476. interface of @command{automake} and @command{aclocal}, @dots{}
  9477. @heading What is not in the API
  9478. Every undocumented variable, target, or command line option, is not part
  9479. of the API@. You should avoid using them, as they could change from one
  9480. version to the other (even in bug fix releases, if this helps to fix a
  9481. bug).
  9482. If it turns out you need to use such an undocumented feature, contact
  9483. @email{automake@@gnu.org} and try to get it documented and exercised by
  9484. the test-suite.
  9485. @node Upgrading
  9486. @chapter Upgrading a Package to a Newer Automake Version
  9487. Automake maintains three kind of files in a package.
  9488. @itemize
  9489. @item @file{aclocal.m4}
  9490. @item @file{Makefile.in}s
  9491. @item auxiliary tools like @file{install-sh} or @file{py-compile}
  9492. @end itemize
  9493. @file{aclocal.m4} is generated by @command{aclocal} and contains some
  9494. Automake-supplied M4 macros. Auxiliary tools are installed by
  9495. @samp{automake --add-missing} when needed. @file{Makefile.in}s are
  9496. built from @file{Makefile.am} by @command{automake}, and rely on the
  9497. definitions of the M4 macros put in @file{aclocal.m4} as well as the
  9498. behavior of the auxiliary tools installed.
  9499. Because all of these files are closely related, it is important to
  9500. regenerate all of them when upgrading to a newer Automake release.
  9501. The usual way to do that is
  9502. @example
  9503. aclocal # with any option needed (such a -I m4)
  9504. autoconf
  9505. automake --add-missing --force-missing
  9506. @end example
  9507. @noindent
  9508. or more conveniently:
  9509. @example
  9510. autoreconf -vfi
  9511. @end example
  9512. The use of @option{--force-missing} ensures that auxiliary tools will be
  9513. overridden by new versions (@pxref{automake Invocation}).
  9514. It is important to regenerate all of these files each time Automake is
  9515. upgraded, even between bug fixes releases. For instance, it is not
  9516. unusual for a bug fix to involve changes to both the rules generated
  9517. in @file{Makefile.in} and the supporting M4 macros copied to
  9518. @file{aclocal.m4}.
  9519. Presently @command{automake} is able to diagnose situations where
  9520. @file{aclocal.m4} has been generated with another version of
  9521. @command{aclocal}. However it never checks whether auxiliary scripts
  9522. are up-to-date. In other words, @command{automake} will tell you when
  9523. @command{aclocal} needs to be rerun, but it will never diagnose a
  9524. missing @option{--force-missing}.
  9525. Before upgrading to a new major release, it is a good idea to read the
  9526. file @file{NEWS}. This file lists all changes between releases: new
  9527. features, obsolete constructs, known incompatibilities, and
  9528. workarounds.
  9529. @node FAQ
  9530. @chapter Frequently Asked Questions about Automake
  9531. This chapter covers some questions that often come up on the mailing
  9532. lists.
  9533. @menu
  9534. * CVS:: CVS and generated files
  9535. * maintainer-mode:: missing and AM_MAINTAINER_MODE
  9536. * Wildcards:: Why doesn't Automake support wildcards?
  9537. * Limitations on File Names:: Limitations on source and installed file names
  9538. * Errors with distclean:: Files left in build directory after distclean
  9539. * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
  9540. * Renamed Objects:: Why are object files sometimes renamed?
  9541. * Per-Object Flags:: How to simulate per-object flags?
  9542. * Multiple Outputs:: Writing rules for tools with many output files
  9543. * Hard-Coded Install Paths:: Installing to hard-coded locations
  9544. * Debugging Make Rules:: Strategies when things don't work as expected
  9545. * Reporting Bugs:: Feedback on bugs and feature requests
  9546. @end menu
  9547. @node CVS
  9548. @section CVS and generated files
  9549. @subheading Background: distributed generated Files
  9550. @cindex generated files, distributed
  9551. @cindex rebuild rules
  9552. Packages made with Autoconf and Automake ship with some generated
  9553. files like @file{configure} or @file{Makefile.in}. These files were
  9554. generated on the developer's machine and are distributed so that
  9555. end-users do not have to install the maintainer tools required to
  9556. rebuild them. Other generated files like Lex scanners, Yacc parsers,
  9557. or Info documentation, are usually distributed on similar grounds.
  9558. Automake output rules in @file{Makefile}s to rebuild these files. For
  9559. instance, @command{make} will run @command{autoconf} to rebuild
  9560. @file{configure} whenever @file{configure.ac} is changed. This makes
  9561. development safer by ensuring a @file{configure} is never out-of-date
  9562. with respect to @file{configure.ac}.
  9563. As generated files shipped in packages are up-to-date, and because
  9564. @command{tar} preserves times-tamps, these rebuild rules are not
  9565. triggered when a user unpacks and builds a package.
  9566. @subheading Background: CVS and Timestamps
  9567. @cindex timestamps and CVS
  9568. @cindex CVS and timestamps
  9569. Unless you use CVS keywords (in which case files must be updated at
  9570. commit time), CVS preserves timestamp during @samp{cvs commit} and
  9571. @samp{cvs import -d} operations.
  9572. When you check out a file using @samp{cvs checkout} its timestamp is
  9573. set to that of the revision that is being checked out.
  9574. However, during @command{cvs update}, files will have the date of the
  9575. update, not the original timestamp of this revision. This is meant to
  9576. make sure that @command{make} notices sources files have been updated.
  9577. This timestamp shift is troublesome when both sources and generated
  9578. files are kept under CVS@. Because CVS processes files in lexical
  9579. order, @file{configure.ac} will appear newer than @file{configure}
  9580. after a @command{cvs update} that updates both files, even if
  9581. @file{configure} was newer than @file{configure.ac} when it was
  9582. checked in. Calling @command{make} will then trigger a spurious rebuild
  9583. of @file{configure}.
  9584. @subheading Living with CVS in Autoconfiscated Projects
  9585. @cindex CVS and generated files
  9586. @cindex generated files and CVS
  9587. There are basically two clans amongst maintainers: those who keep all
  9588. distributed files under CVS, including generated files, and those who
  9589. keep generated files @emph{out} of CVS.
  9590. @subsubheading All Files in CVS
  9591. @itemize @bullet
  9592. @item
  9593. The CVS repository contains all distributed files so you know exactly
  9594. what is distributed, and you can checkout any prior version entirely.
  9595. @item
  9596. Maintainers can see how generated files evolve (for instance, you can
  9597. see what happens to your @file{Makefile.in}s when you upgrade Automake
  9598. and make sure they look OK).
  9599. @item
  9600. Users do not need the autotools to build a checkout of the project, it
  9601. works just like a released tarball.
  9602. @item
  9603. If users use @command{cvs update} to update their copy, instead of
  9604. @command{cvs checkout} to fetch a fresh one, timestamps will be
  9605. inaccurate. Some rebuild rules will be triggered and attempt to
  9606. run developer tools such as @command{autoconf} or @command{automake}.
  9607. Calls to such tools are all wrapped into a call to the @command{missing}
  9608. script discussed later (@pxref{maintainer-mode}), so that the user will
  9609. see more descriptive warnings about missing or out-of-date tools, and
  9610. possible suggestions about how to obtain them, rather than just some
  9611. ``command not found'' error, or (worse) some obscure message from some
  9612. older version of the required tool they happen to have installed.
  9613. Maintainers interested in keeping their package buildable from a CVS
  9614. checkout even for those users that lack maintainer-specific tools might
  9615. want to provide an helper script (or to enhance their existing bootstrap
  9616. script) to fix the timestamps after a
  9617. @command{cvs update} or a @command{git checkout}, to prevent spurious
  9618. rebuilds. In case of a project committing the Autotools-generated
  9619. files, as well as the generated @file{.info} files, such script might
  9620. look something like this:
  9621. @smallexample
  9622. #!/bin/sh
  9623. # fix-timestamp.sh: prevents useless rebuilds after "cvs update"
  9624. sleep 1
  9625. # aclocal-generated aclocal.m4 depends on locally-installed
  9626. # '.m4' macro files, as well as on 'configure.ac'
  9627. touch aclocal.m4
  9628. sleep 1
  9629. # autoconf-generated configure depends on aclocal.m4 and on
  9630. # configure.ac
  9631. touch configure
  9632. # so does autoheader-generated config.h.in
  9633. touch config.h.in
  9634. # and all the automake-generated Makefile.in files
  9635. touch `find . -name Makefile.in -print`
  9636. # finally, the makeinfo-generated '.info' files depend on the
  9637. # corresponding '.texi' files
  9638. touch doc/*.info
  9639. @end smallexample
  9640. @item
  9641. In distributed development, developers are likely to have different
  9642. version of the maintainer tools installed. In this case rebuilds
  9643. triggered by timestamp lossage will lead to spurious changes
  9644. to generated files. There are several solutions to this:
  9645. @itemize
  9646. @item
  9647. All developers should use the same versions, so that the rebuilt files
  9648. are identical to files in CVS@. (This starts to be difficult when each
  9649. project you work on uses different versions.)
  9650. @item
  9651. Or people use a script to fix the timestamp after a checkout (the GCC
  9652. folks have such a script).
  9653. @item
  9654. Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
  9655. disable all of these rebuild rules by default. This is further discussed
  9656. in @ref{maintainer-mode}.
  9657. @end itemize
  9658. @item
  9659. Although we focused on spurious rebuilds, the converse can also
  9660. happen. CVS's timestamp handling can also let you think an
  9661. out-of-date file is up-to-date.
  9662. For instance, suppose a developer has modified @file{Makefile.am} and
  9663. has rebuilt @file{Makefile.in}, and then decides to do a last-minute
  9664. change to @file{Makefile.am} right before checking in both files
  9665. (without rebuilding @file{Makefile.in} to account for the change).
  9666. This last change to @file{Makefile.am} makes the copy of
  9667. @file{Makefile.in} out-of-date. Since CVS processes files
  9668. alphabetically, when another developer @samp{cvs update}s his or her
  9669. tree, @file{Makefile.in} will happen to be newer than
  9670. @file{Makefile.am}. This other developer will not see that
  9671. @file{Makefile.in} is out-of-date.
  9672. @end itemize
  9673. @subsubheading Generated Files out of CVS
  9674. One way to get CVS and @command{make} working peacefully is to never
  9675. store generated files in CVS, i.e., do not CVS-control files that
  9676. are @file{Makefile} targets (also called @emph{derived} files).
  9677. This way developers are not annoyed by changes to generated files. It
  9678. does not matter if they all have different versions (assuming they are
  9679. compatible, of course). And finally, timestamps are not lost, changes
  9680. to sources files can't be missed as in the
  9681. @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
  9682. The drawback is that the CVS repository is not an exact copy of what
  9683. is distributed and that users now need to install various development
  9684. tools (maybe even specific versions) before they can build a checkout.
  9685. But, after all, CVS's job is versioning, not distribution.
  9686. Allowing developers to use different versions of their tools can also
  9687. hide bugs during distributed development. Indeed, developers will be
  9688. using (hence testing) their own generated files, instead of the
  9689. generated files that will be released actually. The developer who
  9690. prepares the tarball might be using a version of the tool that
  9691. produces bogus output (for instance a non-portable C file), something
  9692. other developers could have noticed if they weren't using their own
  9693. versions of this tool.
  9694. @subheading Third-party Files
  9695. @cindex CVS and third-party files
  9696. @cindex third-party files and CVS
  9697. Another class of files not discussed here (because they do not cause
  9698. timestamp issues) are files that are shipped with a package, but
  9699. maintained elsewhere. For instance, tools like @command{gettextize}
  9700. and @command{autopoint} (from Gettext) or @command{libtoolize} (from
  9701. Libtool), will install or update files in your package.
  9702. These files, whether they are kept under CVS or not, raise similar
  9703. concerns about version mismatch between developers' tools. The
  9704. Gettext manual has a section about this, see @ref{CVS Issues, CVS
  9705. Issues, Integrating with CVS, gettext, GNU gettext tools}.
  9706. @node maintainer-mode
  9707. @section @command{missing} and @code{AM_MAINTAINER_MODE}
  9708. @subheading @command{missing}
  9709. @cindex @command{missing}, purpose
  9710. The @command{missing} script is a wrapper around several maintainer
  9711. tools, designed to warn users if a maintainer tool is required but
  9712. missing. Typical maintainer tools are @command{autoconf},
  9713. @command{automake}, @command{bison}, etc. Because file generated by
  9714. these tools are shipped with the other sources of a package, these
  9715. tools shouldn't be required during a user build and they are not
  9716. checked for in @file{configure}.
  9717. However, if for some reason a rebuild rule is triggered and involves a
  9718. missing tool, @command{missing} will notice it and warn the user, even
  9719. suggesting how to obtain such a tool (at least in case it is a well-known
  9720. one, like @command{makeinfo} or @command{bison}). This is more helpful
  9721. and user-friendly than just having the rebuild rules spewing out a terse
  9722. error message like @samp{sh: @var{tool}: command not found}. Similarly,
  9723. @command{missing} will warn the user if it detects that a maintainer
  9724. tool it attempted to use seems too old (be warned that diagnosing this
  9725. correctly is typically more difficult that detecting missing tools, and
  9726. requires cooperation from the tool itself, so it won't always work).
  9727. If the required tool is installed, @command{missing} will run it and
  9728. won't attempt to continue after failures. This is correct during
  9729. development: developers love fixing failures. However, users with
  9730. missing or too old maintainer tools may get an error when the rebuild
  9731. rule is spuriously triggered, halting the build. This failure to let
  9732. the build continue is one of the arguments of the
  9733. @code{AM_MAINTAINER_MODE} advocates.
  9734. @subheading @code{AM_MAINTAINER_MODE}
  9735. @cindex @code{AM_MAINTAINER_MODE}, purpose
  9736. @acindex AM_MAINTAINER_MODE
  9737. @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
  9738. "rebuild rules" should be enabled or disabled. With
  9739. @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
  9740. otherwise they are disabled by default. In the latter case, if
  9741. you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
  9742. @samp{./configure && make}, then @command{make} will *never* attempt to
  9743. rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
  9744. I.e., this disables build rules for files that are usually distributed
  9745. and that users should normally not have to update.
  9746. The user can override the default setting by passing either
  9747. @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
  9748. to @command{configure}.
  9749. People use @code{AM_MAINTAINER_MODE} either because they do not want their
  9750. users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
  9751. because they simply can't stand the rebuild rules and prefer running
  9752. maintainer tools explicitly.
  9753. @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
  9754. rules conditionally. Some developers use this feature to disable
  9755. rules that need exotic tools that users may not have available.
  9756. Several years ago Fran@,{c}ois Pinard pointed out several arguments
  9757. against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
  9758. insecurity. By removing dependencies you get non-dependable builds:
  9759. changes to sources files can have no effect on generated files and this
  9760. can be very confusing when unnoticed. He adds that security shouldn't
  9761. be reserved to maintainers (what @option{--enable-maintainer-mode}
  9762. suggests), on the contrary. If one user has to modify a
  9763. @file{Makefile.am}, then either @file{Makefile.in} should be updated
  9764. or a warning should be output (this is what Automake uses
  9765. @command{missing} for) but the last thing you want is that nothing
  9766. happens and the user doesn't notice it (this is what happens when
  9767. rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
  9768. Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
  9769. swayed by Fran@,{c}ois's arguments, and got rid of
  9770. @code{AM_MAINTAINER_MODE} in all of his packages.
  9771. Still many people continue to use @code{AM_MAINTAINER_MODE}, because
  9772. it helps them working on projects where all files are kept under version
  9773. control, and because @command{missing} isn't enough if you have the
  9774. wrong version of the tools.
  9775. @node Wildcards
  9776. @section Why doesn't Automake support wildcards?
  9777. @cindex wildcards
  9778. Developers are lazy. They would often like to use wildcards in
  9779. @file{Makefile.am}s, so that they would not need to remember to
  9780. update @file{Makefile.am}s every time they add, delete, or rename
  9781. a file.
  9782. There are several objections to this:
  9783. @itemize
  9784. @item
  9785. When using CVS (or similar) developers need to remember they have to
  9786. run @samp{cvs add} or @samp{cvs rm} anyway. Updating
  9787. @file{Makefile.am} accordingly quickly becomes a reflex.
  9788. Conversely, if your application doesn't compile
  9789. because you forgot to add a file in @file{Makefile.am}, it will help
  9790. you remember to @samp{cvs add} it.
  9791. @item
  9792. Using wildcards makes it easy to distribute files by mistake. For
  9793. instance, some code a developer is experimenting with (a test case,
  9794. say) that should not be part of the distribution.
  9795. @item
  9796. Using wildcards it's easy to omit some files by mistake. For
  9797. instance, one developer creates a new file, uses it in many places,
  9798. but forgets to commit it. Another developer then checks out the
  9799. incomplete project and is able to run @samp{make dist} successfully,
  9800. even though a file is missing. By listing files, @samp{make dist}
  9801. @emph{will} complain.
  9802. @item
  9803. Wildcards are not portable to some non-GNU @command{make} implementations,
  9804. e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
  9805. prerequisites of a target.
  9806. @item
  9807. Finally, it's really hard to @emph{forget} to add a file to
  9808. @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
  9809. not compiled or installed, so you can't even test them.
  9810. @end itemize
  9811. Still, these are philosophical objections, and as such you may disagree,
  9812. or find enough value in wildcards to dismiss all of them. Before you
  9813. start writing a patch against Automake to teach it about wildcards,
  9814. let's see the main technical issue: portability.
  9815. Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
  9816. not portable to other @command{make} implementations.
  9817. The only way Automake could support @command{$(wildcard ...)} is by
  9818. expanding @command{$(wildcard ...)} when @command{automake} is run.
  9819. The resulting @file{Makefile.in}s would be portable since they would
  9820. list all files and not use @samp{$(wildcard ...)}. However that
  9821. means developers would need to remember to run @command{automake} each
  9822. time they add, delete, or rename files.
  9823. Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
  9824. it's easier and faster to type @samp{automake; make} than to type
  9825. @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
  9826. patch to add support for this syntax. Some people use scripts to
  9827. generate file lists in @file{Makefile.am} or in separate
  9828. @file{Makefile} fragments.
  9829. Even if you don't care about portability, and are tempted to use
  9830. @samp{$(wildcard ...)} anyway because you target only GNU Make, you
  9831. should know there are many places where Automake needs to know exactly
  9832. which files should be processed. As Automake doesn't know how to
  9833. expand @samp{$(wildcard ...)}, you cannot use it in these places.
  9834. @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
  9835. variables as far Automake is concerned.
  9836. You can get warnings about @samp{$(wildcard ...}) constructs using the
  9837. @option{-Wportability} flag.
  9838. @node Limitations on File Names
  9839. @section Limitations on File Names
  9840. @cindex file names, limitations on
  9841. Automake attempts to support all kinds of file names, even those that
  9842. contain unusual characters or are unusually long. However, some
  9843. limitations are imposed by the underlying operating system and tools.
  9844. Most operating systems prohibit the use of the null byte in file
  9845. names, and reserve @samp{/} as a directory separator. Also, they
  9846. require that file names are properly encoded for the user's locale.
  9847. Automake is subject to these limits.
  9848. Portable packages should limit themselves to POSIX file
  9849. names. These can contain ASCII letters and digits,
  9850. @samp{_}, @samp{.}, and @samp{-}. File names consist of components
  9851. separated by @samp{/}. File name components cannot begin with
  9852. @samp{-}.
  9853. Portable POSIX file names cannot contain components that exceed a
  9854. 14-byte limit, but nowadays it's normally safe to assume the
  9855. more-generous XOPEN limit of 255 bytes. POSIX
  9856. limits file names to 255 bytes (XOPEN allows 1023 bytes),
  9857. but you may want to limit a source tarball to file names of 99 bytes
  9858. to avoid interoperability problems with old versions of @command{tar}.
  9859. If you depart from these rules (e.g., by using non-ASCII
  9860. characters in file names, or by using lengthy file names), your
  9861. installers may have problems for reasons unrelated to Automake.
  9862. However, if this does not concern you, you should know about the
  9863. limitations imposed by Automake itself. These limitations are
  9864. undesirable, but some of them seem to be inherent to underlying tools
  9865. like Autoconf, Make, M4, and the shell. They fall into three
  9866. categories: install directories, build directories, and file names.
  9867. The following characters:
  9868. @example
  9869. @r{newline} " # $ ' `
  9870. @end example
  9871. should not appear in the names of install directories. For example,
  9872. the operand of @command{configure}'s @option{--prefix} option should
  9873. not contain these characters.
  9874. Build directories suffer the same limitations as install directories,
  9875. and in addition should not contain the following characters:
  9876. @example
  9877. & @@ \
  9878. @end example
  9879. For example, the full name of the directory containing the source
  9880. files should not contain these characters.
  9881. Source and installation file names like @file{main.c} are limited even
  9882. further: they should conform to the POSIX/XOPEN
  9883. rules described above. In addition, if you plan to port to
  9884. non-POSIX environments, you should avoid file names that
  9885. differ only in case (e.g., @file{makefile} and @file{Makefile}).
  9886. Nowadays it is no longer worth worrying about the 8.3 limits of
  9887. DOS file systems.
  9888. @c FIXME This should probably be moved in the "Checking the Distribution"
  9889. @c FIXME section...
  9890. @node Errors with distclean
  9891. @section Errors with distclean
  9892. @cindex @code{distclean}, diagnostic
  9893. @cindex @samp{make distclean}, diagnostic
  9894. @cindex dependencies and distributed files
  9895. @trindex distclean
  9896. This is a diagnostic you might encounter while running @samp{make
  9897. distcheck}.
  9898. As explained in @ref{Checking the Distribution}, @samp{make distcheck}
  9899. attempts to build and check your package for errors like this one.
  9900. @samp{make distcheck} will perform a @code{VPATH} build of your
  9901. package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
  9902. Files left in the build directory after @samp{make distclean} has run
  9903. are listed after this error.
  9904. This diagnostic really covers two kinds of errors:
  9905. @itemize @bullet
  9906. @item
  9907. files that are forgotten by distclean;
  9908. @item
  9909. distributed files that are erroneously rebuilt.
  9910. @end itemize
  9911. The former left-over files are not distributed, so the fix is to mark
  9912. them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
  9913. more explanations.
  9914. The latter bug is not always easy to understand and fix, so let's
  9915. proceed with an example. Suppose our package contains a program for
  9916. which we want to build a man page using @command{help2man}. GNU
  9917. @command{help2man} produces simple manual pages from the @option{--help}
  9918. and @option{--version} output of other commands (@pxref{Top, , Overview,
  9919. help2man, The Help2man Manual}). Because we don't want to force our
  9920. users to install @command{help2man}, we decide to distribute the
  9921. generated man page using the following setup.
  9922. @example
  9923. # This Makefile.am is bogus.
  9924. bin_PROGRAMS = foo
  9925. foo_SOURCES = foo.c
  9926. dist_man_MANS = foo.1
  9927. foo.1: foo$(EXEEXT)
  9928. help2man --output=foo.1 ./foo$(EXEEXT)
  9929. @end example
  9930. This will effectively distribute the man page. However,
  9931. @samp{make distcheck} will fail with:
  9932. @example
  9933. ERROR: files left in build directory after distclean:
  9934. ./foo.1
  9935. @end example
  9936. Why was @file{foo.1} rebuilt? Because although distributed,
  9937. @file{foo.1} depends on a non-distributed built file:
  9938. @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
  9939. will always appear to be newer than the distributed @file{foo.1}.
  9940. @samp{make distcheck} caught an inconsistency in our package. Our
  9941. intent was to distribute @file{foo.1} so users do not need to install
  9942. @command{help2man}, however since this rule causes this file to be
  9943. always rebuilt, users @emph{do} need @command{help2man}. Either we
  9944. should ensure that @file{foo.1} is not rebuilt by users, or there is
  9945. no point in distributing @file{foo.1}.
  9946. More generally, the rule is that distributed files should never depend
  9947. on non-distributed built files. If you distribute something
  9948. generated, distribute its sources.
  9949. One way to fix the above example, while still distributing
  9950. @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
  9951. assuming @command{foo --version} and @command{foo --help} do not
  9952. change unless @file{foo.c} or @file{configure.ac} change, we could
  9953. write the following @file{Makefile.am}:
  9954. @example
  9955. bin_PROGRAMS = foo
  9956. foo_SOURCES = foo.c
  9957. dist_man_MANS = foo.1
  9958. foo.1: foo.c $(top_srcdir)/configure.ac
  9959. $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
  9960. help2man --output=foo.1 ./foo$(EXEEXT)
  9961. @end example
  9962. This way, @file{foo.1} will not get rebuilt every time
  9963. @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
  9964. @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
  9965. way to ensure this would be to use separate directories for binaries
  9966. and man pages, and set @code{SUBDIRS} so that binaries are built
  9967. before man pages.
  9968. We could also decide not to distribute @file{foo.1}. In
  9969. this case it's fine to have @file{foo.1} dependent upon
  9970. @file{foo$(EXEEXT)}, since both will have to be rebuilt.
  9971. However it would be impossible to build the package in a
  9972. cross-compilation, because building @file{foo.1} involves
  9973. an @emph{execution} of @file{foo$(EXEEXT)}.
  9974. Another context where such errors are common is when distributed files
  9975. are built by tools that are built by the package. The pattern is
  9976. similar:
  9977. @example
  9978. distributed-file: built-tools distributed-sources
  9979. build-command
  9980. @end example
  9981. @noindent
  9982. should be changed to
  9983. @example
  9984. distributed-file: distributed-sources
  9985. $(MAKE) $(AM_MAKEFLAGS) built-tools
  9986. build-command
  9987. @end example
  9988. @noindent
  9989. or you could choose not to distribute @file{distributed-file}, if
  9990. cross-compilation does not matter.
  9991. The points made through these examples are worth a summary:
  9992. @cartouche
  9993. @itemize
  9994. @item
  9995. Distributed files should never depend upon non-distributed built
  9996. files.
  9997. @item
  9998. Distributed files should be distributed with all their dependencies.
  9999. @item
  10000. If a file is @emph{intended} to be rebuilt by users, then there is no point
  10001. in distributing it.
  10002. @end itemize
  10003. @end cartouche
  10004. @vrindex distcleancheck_listfiles
  10005. For desperate cases, it's always possible to disable this check by
  10006. setting @code{distcleancheck_listfiles} as documented in @ref{Checking
  10007. the Distribution}.
  10008. Make sure you do understand the reason why @samp{make distcheck}
  10009. complains before you do this. @code{distcleancheck_listfiles} is a
  10010. way to @emph{hide} errors, not to fix them. You can always do better.
  10011. @node Flag Variables Ordering
  10012. @section Flag Variables Ordering
  10013. @cindex Ordering flag variables
  10014. @cindex Flag variables, ordering
  10015. @display
  10016. What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
  10017. @code{mumble_CFLAGS}?
  10018. @end display
  10019. @display
  10020. Why does @command{automake} output @code{CPPFLAGS} after
  10021. @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
  10022. @end display
  10023. @display
  10024. My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
  10025. one @file{Makefile.am} I would like to append a new flag, however if I
  10026. put the flag into @code{AM_CXXFLAGS} it is prepended to the other
  10027. flags, not appended.
  10028. @end display
  10029. @subheading Compile Flag Variables
  10030. @cindex Flag Variables, Ordering
  10031. @cindex Compile Flag Variables
  10032. @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
  10033. @cindex @code{AM_CFLAGS} and @code{CFLAGS}
  10034. @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
  10035. @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
  10036. @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
  10037. @cindex @code{AM_FFLAGS} and @code{FFLAGS}
  10038. @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
  10039. @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
  10040. @cindex @code{AM_LFLAGS} and @code{LFLAGS}
  10041. @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
  10042. @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
  10043. @cindex @code{AM_OBJCXXFLAGS} and @code{OBJXXCFLAGS}
  10044. @cindex @code{AM_RFLAGS} and @code{RFLAGS}
  10045. @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
  10046. @cindex @code{AM_YFLAGS} and @code{YFLAGS}
  10047. @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
  10048. @cindex @code{CFLAGS} and @code{AM_CFLAGS}
  10049. @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
  10050. @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
  10051. @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
  10052. @cindex @code{FFLAGS} and @code{AM_FFLAGS}
  10053. @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
  10054. @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
  10055. @cindex @code{LFLAGS} and @code{AM_LFLAGS}
  10056. @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
  10057. @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
  10058. @cindex @code{OBJCXXFLAGS} and @code{AM_OBJCXXFLAGS}
  10059. @cindex @code{RFLAGS} and @code{AM_RFLAGS}
  10060. @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
  10061. @cindex @code{YFLAGS} and @code{AM_YFLAGS}
  10062. This section attempts to answer all the above questions. We will
  10063. mostly discuss @code{CPPFLAGS} in our examples, but actually the
  10064. answer holds for all the compile flags used in Automake:
  10065. @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
  10066. @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
  10067. @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
  10068. @code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}.
  10069. @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
  10070. three variables that can be used to pass flags to the C preprocessor
  10071. (actually these variables are also used for other languages like C++
  10072. or preprocessed Fortran). @code{CPPFLAGS} is the user variable
  10073. (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
  10074. and @code{mumble_CPPFLAGS} is the variable specific to the
  10075. @code{mumble} target (we call this a per-target variable,
  10076. @pxref{Program and Library Variables}).
  10077. Automake always uses two of these variables when compiling C sources
  10078. files. When compiling an object file for the @code{mumble} target,
  10079. the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
  10080. @code{AM_CPPFLAGS} otherwise. The second variable is always
  10081. @code{CPPFLAGS}.
  10082. In the following example,
  10083. @example
  10084. bin_PROGRAMS = foo bar
  10085. foo_SOURCES = xyz.c
  10086. bar_SOURCES = main.c
  10087. foo_CPPFLAGS = -DFOO
  10088. AM_CPPFLAGS = -DBAZ
  10089. @end example
  10090. @noindent
  10091. @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
  10092. (because @file{xyz.o} is part of the @code{foo} target), while
  10093. @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
  10094. (because there is no per-target variable for target @code{bar}).
  10095. The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
  10096. being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
  10097. is a user variable, i.e., a variable that users are entitled to modify
  10098. in order to compile the package. This variable, like many others,
  10099. is documented at the end of the output of @samp{configure --help}.
  10100. For instance, someone who needs to add @file{/home/my/usr/include} to
  10101. the C compiler's search path would configure a package with
  10102. @example
  10103. ./configure CPPFLAGS='-I /home/my/usr/include'
  10104. @end example
  10105. @noindent
  10106. and this flag would be propagated to the compile rules of all
  10107. @file{Makefile}s.
  10108. It is also not uncommon to override a user variable at
  10109. @command{make}-time. Many installers do this with @code{prefix}, but
  10110. this can be useful with compiler flags too. For instance, if, while
  10111. debugging a C++ project, you need to disable optimization in one
  10112. specific object file, you can run something like
  10113. @example
  10114. rm file.o
  10115. make CXXFLAGS=-O0 file.o
  10116. make
  10117. @end example
  10118. The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
  10119. @samp{$(mumble_CPPFLAGS)} in the compile command is that users
  10120. should always have the last say. It probably makes more sense if you
  10121. think about it while looking at the @samp{CXXFLAGS=-O0} above, which
  10122. should supersede any other switch from @code{AM_CXXFLAGS} or
  10123. @code{mumble_CXXFLAGS} (and this of course replaces the previous value
  10124. of @code{CXXFLAGS}).
  10125. You should never redefine a user variable such as @code{CPPFLAGS} in
  10126. @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
  10127. mistakes. Even something like
  10128. @example
  10129. CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
  10130. @end example
  10131. @noindent
  10132. is erroneous. Although this preserves @file{configure}'s value of
  10133. @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
  10134. user attempts to override @code{CPPFLAGS} from the @command{make}
  10135. command line.
  10136. @example
  10137. AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
  10138. @end example
  10139. @noindent
  10140. is all that is needed here if no per-target flags are used.
  10141. You should not add options to these user variables within
  10142. @file{configure} either, for the same reason. Occasionally you need
  10143. to modify these variables to perform a test, but you should reset
  10144. their values afterwards. In contrast, it is OK to modify the
  10145. @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
  10146. them, but it is rather rare that you need to do this, unless you
  10147. really want to change the default definitions of the @samp{AM_}
  10148. variables in all @file{Makefile}s.
  10149. What we recommend is that you define extra flags in separate
  10150. variables. For instance, you may write an Autoconf macro that computes
  10151. a set of warning options for the C compiler, and @code{AC_SUBST} them
  10152. in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
  10153. determines which compiler and which linker flags should be used to
  10154. link with library @file{libfoo}, and @code{AC_SUBST} these in
  10155. @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
  10156. @file{Makefile.am} could use these variables as follows:
  10157. @example
  10158. AM_CFLAGS = $(WARNINGCFLAGS)
  10159. bin_PROGRAMS = prog1 prog2
  10160. prog1_SOURCES = @dots{}
  10161. prog2_SOURCES = @dots{}
  10162. prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
  10163. prog2_LDFLAGS = $(LIBFOOLDFLAGS)
  10164. @end example
  10165. In this example both programs will be compiled with the flags
  10166. substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
  10167. additionally be compiled with the flags required to link with
  10168. @file{libfoo}.
  10169. Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
  10170. variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
  10171. every target in a @file{Makefile.in}.
  10172. Using variables like this gives you full control over the ordering of
  10173. the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
  10174. you want to negate for a particular target, you can use something like
  10175. @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all of these flags had
  10176. been forcefully appended to @code{CFLAGS}, there would be no way to
  10177. disable one flag. Yet another reason to leave user variables to
  10178. users.
  10179. Finally, we have avoided naming the variable of the example
  10180. @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
  10181. Automake to think that this is actually a per-target variable (like
  10182. @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
  10183. @subheading Other Variables
  10184. There are other variables in Automake that follow similar principles
  10185. to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
  10186. use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
  10187. DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
  10188. @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
  10189. (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
  10190. @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
  10191. (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
  10192. of these rules support per-target flags (yet).
  10193. To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
  10194. obeys this naming scheme. The slight difference is that
  10195. @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
  10196. @command{make} itself.
  10197. @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
  10198. has neither @code{AM_} nor per-target cousin.
  10199. Finally you should not think that the existence of a per-target
  10200. variable implies the existence of an @code{AM_} variable or of a user
  10201. variable. For instance, the @code{mumble_LDADD} per-target variable
  10202. overrides the makefile-wide @code{LDADD} variable (which is not a user
  10203. variable), and @code{mumble_LIBADD} exists only as a per-target
  10204. variable. @xref{Program and Library Variables}.
  10205. @node Renamed Objects
  10206. @section Why are object files sometimes renamed?
  10207. This happens when per-target compilation flags are used. Object
  10208. files need to be renamed just in case they would clash with object
  10209. files compiled from the same sources, but with different flags.
  10210. Consider the following example.
  10211. @example
  10212. bin_PROGRAMS = true false
  10213. true_SOURCES = generic.c
  10214. true_CPPFLAGS = -DEXIT_CODE=0
  10215. false_SOURCES = generic.c
  10216. false_CPPFLAGS = -DEXIT_CODE=1
  10217. @end example
  10218. @noindent
  10219. Obviously the two programs are built from the same source, but it
  10220. would be bad if they shared the same object, because @file{generic.o}
  10221. cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
  10222. @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
  10223. build two different objects: @file{true-generic.o} and
  10224. @file{false-generic.o}.
  10225. @command{automake} doesn't actually look whether source files are
  10226. shared to decide if it must rename objects. It will just rename all
  10227. objects of a target as soon as it sees per-target compilation flags
  10228. used.
  10229. It's OK to share object files when per-target compilation flags are not
  10230. used. For instance, @file{true} and @file{false} will both use
  10231. @file{version.o} in the following example.
  10232. @example
  10233. AM_CPPFLAGS = -DVERSION=1.0
  10234. bin_PROGRAMS = true false
  10235. true_SOURCES = true.c version.c
  10236. false_SOURCES = false.c version.c
  10237. @end example
  10238. Note that the renaming of objects is also affected by the
  10239. @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
  10240. @node Per-Object Flags
  10241. @section Per-Object Flags Emulation
  10242. @cindex Per-object flags, emulated
  10243. @display
  10244. One of my source files needs to be compiled with different flags. How
  10245. do I do?
  10246. @end display
  10247. Automake supports per-program and per-library compilation flags (see
  10248. @ref{Program and Library Variables} and @ref{Flag Variables
  10249. Ordering}). With this you can define compilation flags that apply to
  10250. all files compiled for a target. For instance, in
  10251. @example
  10252. bin_PROGRAMS = foo
  10253. foo_SOURCES = foo.c foo.h bar.c bar.h main.c
  10254. foo_CFLAGS = -some -flags
  10255. @end example
  10256. @noindent
  10257. @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
  10258. compiled with @samp{-some -flags}. (If you wonder about the names of
  10259. these object files, see @ref{Renamed Objects}.) Note that
  10260. @code{foo_CFLAGS} gives the flags to use when compiling all the C
  10261. sources of the @emph{program} @code{foo}, it has nothing to do with
  10262. @file{foo.c} or @file{foo-foo.o} specifically.
  10263. What if @file{foo.c} needs to be compiled into @file{foo.o} using some
  10264. specific flags, that none of the other files requires? Obviously
  10265. per-program flags are not directly applicable here. Something like
  10266. per-object flags are expected, i.e., flags that would be used only
  10267. when creating @file{foo-foo.o}. Automake does not support that,
  10268. however this is easy to simulate using a library that contains only
  10269. that object, and compiling this library with per-library flags.
  10270. @example
  10271. bin_PROGRAMS = foo
  10272. foo_SOURCES = bar.c bar.h main.c
  10273. foo_CFLAGS = -some -flags
  10274. foo_LDADD = libfoo.a
  10275. noinst_LIBRARIES = libfoo.a
  10276. libfoo_a_SOURCES = foo.c foo.h
  10277. libfoo_a_CFLAGS = -some -other -flags
  10278. @end example
  10279. Here @file{foo-bar.o} and @file{foo-main.o} will all be
  10280. compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
  10281. be compiled using @samp{-some -other -flags}. Eventually, all
  10282. three objects will be linked to form @file{foo}.
  10283. This trick can also be achieved using Libtool convenience libraries,
  10284. for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
  10285. Convenience Libraries}).
  10286. Another tempting idea to implement per-object flags is to override the
  10287. compile rules @command{automake} would output for these files.
  10288. Automake will not define a rule for a target you have defined, so you
  10289. could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
  10290. We recommend against this, because this is error prone. For instance,
  10291. if you add such a rule to the first example, it will break the day you
  10292. decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
  10293. compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
  10294. Objects}). Also in order to support dependency tracking, the two
  10295. @file{.o}/@file{.obj} extensions, and all the other flags variables
  10296. involved in a compilation, you will end up modifying a copy of the
  10297. rule previously output by @command{automake} for this file. If a new
  10298. release of Automake generates a different rule, your copy will need to
  10299. be updated by hand.
  10300. @node Multiple Outputs
  10301. @section Handling Tools that Produce Many Outputs
  10302. @cindex multiple outputs, rules with
  10303. @cindex many outputs, rules with
  10304. @cindex rules with multiple outputs
  10305. This section describes a @command{make} idiom that can be used when a
  10306. tool produces multiple output files. It is not specific to Automake
  10307. and can be used in ordinary @file{Makefile}s.
  10308. Suppose we have a program called @command{foo} that will read one file
  10309. called @file{data.foo} and produce two files named @file{data.c} and
  10310. @file{data.h}. We want to write a @file{Makefile} rule that captures
  10311. this one-to-two dependency.
  10312. The naive rule is incorrect:
  10313. @example
  10314. # This is incorrect.
  10315. data.c data.h: data.foo
  10316. foo data.foo
  10317. @end example
  10318. @noindent
  10319. What the above rule really says is that @file{data.c} and
  10320. @file{data.h} each depend on @file{data.foo}, and can each be built by
  10321. running @samp{foo data.foo}. In other words it is equivalent to:
  10322. @example
  10323. # We do not want this.
  10324. data.c: data.foo
  10325. foo data.foo
  10326. data.h: data.foo
  10327. foo data.foo
  10328. @end example
  10329. @noindent
  10330. which means that @command{foo} can be run twice. Usually it will not
  10331. be run twice, because @command{make} implementations are smart enough
  10332. to check for the existence of the second file after the first one has
  10333. been built; they will therefore detect that it already exists.
  10334. However there are a few situations where it can run twice anyway:
  10335. @itemize
  10336. @item
  10337. The most worrying case is when running a parallel @command{make}. If
  10338. @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
  10339. data.foo} commands will run concurrently. This is harmful.
  10340. @item
  10341. Another case is when the dependency (here @file{data.foo}) is
  10342. (or depends upon) a phony target.
  10343. @end itemize
  10344. A solution that works with parallel @command{make} but not with
  10345. phony dependencies is the following:
  10346. @example
  10347. data.c data.h: data.foo
  10348. foo data.foo
  10349. data.h: data.c
  10350. @end example
  10351. @noindent
  10352. The above rules are equivalent to
  10353. @example
  10354. data.c: data.foo
  10355. foo data.foo
  10356. data.h: data.foo data.c
  10357. foo data.foo
  10358. @end example
  10359. @noindent
  10360. therefore a parallel @command{make} will have to serialize the builds
  10361. of @file{data.c} and @file{data.h}, and will detect that the second is
  10362. no longer needed once the first is over.
  10363. Using this pattern is probably enough for most cases. However it does
  10364. not scale easily to more output files (in this scheme all output files
  10365. must be totally ordered by the dependency relation), so we will
  10366. explore a more complicated solution.
  10367. Another idea is to write the following:
  10368. @example
  10369. # There is still a problem with this one.
  10370. data.c: data.foo
  10371. foo data.foo
  10372. data.h: data.c
  10373. @end example
  10374. @noindent
  10375. The idea is that @samp{foo data.foo} is run only when @file{data.c}
  10376. needs to be updated, but we further state that @file{data.h} depends
  10377. upon @file{data.c}. That way, if @file{data.h} is required and
  10378. @file{data.foo} is out of date, the dependency on @file{data.c} will
  10379. trigger the build.
  10380. This is almost perfect, but suppose we have built @file{data.h} and
  10381. @file{data.c}, and then we erase @file{data.h}. Then, running
  10382. @samp{make data.h} will not rebuild @file{data.h}. The above rules
  10383. just state that @file{data.c} must be up-to-date with respect to
  10384. @file{data.foo}, and this is already the case.
  10385. What we need is a rule that forces a rebuild when @file{data.h} is
  10386. missing. Here it is:
  10387. @example
  10388. data.c: data.foo
  10389. foo data.foo
  10390. data.h: data.c
  10391. ## Recover from the removal of $@@
  10392. @@if test -f $@@; then :; else \
  10393. rm -f data.c; \
  10394. $(MAKE) $(AM_MAKEFLAGS) data.c; \
  10395. fi
  10396. @end example
  10397. The above scheme can be extended to handle more outputs and more
  10398. inputs. One of the outputs is selected to serve as a witness to the
  10399. successful completion of the command, it depends upon all inputs, and
  10400. all other outputs depend upon it. For instance, if @command{foo}
  10401. should additionally read @file{data.bar} and also produce
  10402. @file{data.w} and @file{data.x}, we would write:
  10403. @example
  10404. data.c: data.foo data.bar
  10405. foo data.foo data.bar
  10406. data.h data.w data.x: data.c
  10407. ## Recover from the removal of $@@
  10408. @@if test -f $@@; then :; else \
  10409. rm -f data.c; \
  10410. $(MAKE) $(AM_MAKEFLAGS) data.c; \
  10411. fi
  10412. @end example
  10413. However there are now three minor problems in this setup. One is related
  10414. to the timestamp ordering of @file{data.h}, @file{data.w},
  10415. @file{data.x}, and @file{data.c}. Another one is a race condition
  10416. if a parallel @command{make} attempts to run multiple instances of the
  10417. recover block at once. Finally, the recursive rule breaks @samp{make -n}
  10418. when run with GNU @command{make} (as well as some other @command{make}
  10419. implementations), as it may remove @file{data.h} even when it should not
  10420. (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
  10421. The GNU Make Manual}).
  10422. Let us deal with the first problem. @command{foo} outputs four files,
  10423. but we do not know in which order these files are created. Suppose
  10424. that @file{data.h} is created before @file{data.c}. Then we have a
  10425. weird situation. The next time @command{make} is run, @file{data.h}
  10426. will appear older than @file{data.c}, the second rule will be
  10427. triggered, a shell will be started to execute the @samp{if@dots{}fi}
  10428. command, but actually it will just execute the @code{then} branch,
  10429. that is: nothing. In other words, because the witness we selected is
  10430. not the first file created by @command{foo}, @command{make} will start
  10431. a shell to do nothing each time it is run.
  10432. A simple riposte is to fix the timestamps when this happens.
  10433. @example
  10434. data.c: data.foo data.bar
  10435. foo data.foo data.bar
  10436. data.h data.w data.x: data.c
  10437. @@if test -f $@@; then \
  10438. touch $@@; \
  10439. else \
  10440. ## Recover from the removal of $@@
  10441. rm -f data.c; \
  10442. $(MAKE) $(AM_MAKEFLAGS) data.c; \
  10443. fi
  10444. @end example
  10445. Another solution is to use a different and dedicated file as witness,
  10446. rather than using any of @command{foo}'s outputs.
  10447. @example
  10448. data.stamp: data.foo data.bar
  10449. @@rm -f data.tmp
  10450. @@touch data.tmp
  10451. foo data.foo data.bar
  10452. @@mv -f data.tmp $@@
  10453. data.c data.h data.w data.x: data.stamp
  10454. ## Recover from the removal of $@@
  10455. @@if test -f $@@; then :; else \
  10456. rm -f data.stamp; \
  10457. $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
  10458. fi
  10459. @end example
  10460. @file{data.tmp} is created before @command{foo} is run, so it has a
  10461. timestamp older than output files output by @command{foo}. It is then
  10462. renamed to @file{data.stamp} after @command{foo} has run, because we
  10463. do not want to update @file{data.stamp} if @command{foo} fails.
  10464. This solution still suffers from the second problem: the race
  10465. condition in the recover rule. If, after a successful build, a user
  10466. erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
  10467. @command{make} may start both recover rules in parallel. If the two
  10468. instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
  10469. data.stamp} concurrently the build is likely to fail (for instance, the
  10470. two rules will create @file{data.tmp}, but only one can rename it).
  10471. Admittedly, such a weird situation does not arise during ordinary
  10472. builds. It occurs only when the build tree is mutilated. Here
  10473. @file{data.c} and @file{data.h} have been explicitly removed without
  10474. also removing @file{data.stamp} and the other output files.
  10475. @code{make clean; make} will always recover from these situations even
  10476. with parallel makes, so you may decide that the recover rule is solely
  10477. to help non-parallel make users and leave things as-is. Fixing this
  10478. requires some locking mechanism to ensure only one instance of the
  10479. recover rule rebuilds @file{data.stamp}. One could imagine something
  10480. along the following lines.
  10481. @example
  10482. data.c data.h data.w data.x: data.stamp
  10483. ## Recover from the removal of $@@
  10484. @@if test -f $@@; then :; else \
  10485. trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
  10486. ## mkdir is a portable test-and-set
  10487. if mkdir data.lock 2>/dev/null; then \
  10488. ## This code is being executed by the first process.
  10489. rm -f data.stamp; \
  10490. $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
  10491. result=$$?; rm -rf data.lock; exit $$result; \
  10492. else \
  10493. ## This code is being executed by the follower processes.
  10494. ## Wait until the first process is done.
  10495. while test -d data.lock; do sleep 1; done; \
  10496. ## Succeed if and only if the first process succeeded.
  10497. test -f data.stamp; \
  10498. fi; \
  10499. fi
  10500. @end example
  10501. Using a dedicated witness, like @file{data.stamp}, is very handy when
  10502. the list of output files is not known beforehand. As an illustration,
  10503. consider the following rules to compile many @file{*.el} files into
  10504. @file{*.elc} files in a single command. It does not matter how
  10505. @code{ELFILES} is defined (as long as it is not empty: empty targets
  10506. are not accepted by POSIX).
  10507. @example
  10508. ELFILES = one.el two.el three.el @dots{}
  10509. ELCFILES = $(ELFILES:=c)
  10510. elc-stamp: $(ELFILES)
  10511. @@rm -f elc-temp
  10512. @@touch elc-temp
  10513. $(elisp_comp) $(ELFILES)
  10514. @@mv -f elc-temp $@@
  10515. $(ELCFILES): elc-stamp
  10516. @@if test -f $@@; then :; else \
  10517. ## Recover from the removal of $@@
  10518. trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
  10519. if mkdir elc-lock 2>/dev/null; then \
  10520. ## This code is being executed by the first process.
  10521. rm -f elc-stamp; \
  10522. $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
  10523. rmdir elc-lock; \
  10524. else \
  10525. ## This code is being executed by the follower processes.
  10526. ## Wait until the first process is done.
  10527. while test -d elc-lock; do sleep 1; done; \
  10528. ## Succeed if and only if the first process succeeded.
  10529. test -f elc-stamp; exit $$?; \
  10530. @c $$
  10531. fi; \
  10532. fi
  10533. @end example
  10534. These solutions all still suffer from the third problem, namely that
  10535. they break the promise that @samp{make -n} should not cause any actual
  10536. changes to the tree. For those solutions that do not create lock files,
  10537. it is possible to split the recover rules into two separate recipe
  10538. commands, one of which does all work but the recursion, and the
  10539. other invokes the recursive @samp{$(MAKE)}. The solutions involving
  10540. locking could act upon the contents of the @samp{MAKEFLAGS} variable,
  10541. but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
  10542. autoconf, The Autoconf Manual}). Here is an example:
  10543. @example
  10544. ELFILES = one.el two.el three.el @dots{}
  10545. ELCFILES = $(ELFILES:=c)
  10546. elc-stamp: $(ELFILES)
  10547. @@rm -f elc-temp
  10548. @@touch elc-temp
  10549. $(elisp_comp) $(ELFILES)
  10550. @@mv -f elc-temp $@@
  10551. $(ELCFILES): elc-stamp
  10552. ## Recover from the removal of $@@
  10553. @@dry=; for f in x $$MAKEFLAGS; do \
  10554. case $$f in \
  10555. *=*|--*);; \
  10556. *n*) dry=:;; \
  10557. esac; \
  10558. done; \
  10559. if test -f $@@; then :; else \
  10560. $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
  10561. if $$dry mkdir elc-lock 2>/dev/null; then \
  10562. ## This code is being executed by the first process.
  10563. $$dry rm -f elc-stamp; \
  10564. $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
  10565. $$dry rmdir elc-lock; \
  10566. else \
  10567. ## This code is being executed by the follower processes.
  10568. ## Wait until the first process is done.
  10569. while test -d elc-lock && test -z "$$dry"; do \
  10570. @c $$
  10571. sleep 1; \
  10572. done; \
  10573. ## Succeed if and only if the first process succeeded.
  10574. $$dry test -f elc-stamp; exit $$?; \
  10575. fi; \
  10576. fi
  10577. @end example
  10578. For completeness it should be noted that GNU @command{make} is able to
  10579. express rules with multiple output files using pattern rules
  10580. (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
  10581. Manual}). We do not discuss pattern rules here because they are not
  10582. portable, but they can be convenient in packages that assume GNU
  10583. @command{make}.
  10584. @node Hard-Coded Install Paths
  10585. @section Installing to Hard-Coded Locations
  10586. @display
  10587. My package needs to install some configuration file. I tried to use
  10588. the following rule, but @samp{make distcheck} fails. Why?
  10589. @example
  10590. # Do not do this.
  10591. install-data-local:
  10592. $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
  10593. @end example
  10594. @end display
  10595. @display
  10596. My package needs to populate the installation directory of another
  10597. package at install-time. I can easily compute that installation
  10598. directory in @file{configure}, but if I install files therein,
  10599. @samp{make distcheck} fails. How else should I do?
  10600. @end display
  10601. These two setups share their symptoms: @samp{make distcheck} fails
  10602. because they are installing files to hard-coded paths. In the later
  10603. case the path is not really hard-coded in the package, but we can
  10604. consider it to be hard-coded in the system (or in whichever tool that
  10605. supplies the path). As long as the path does not use any of the
  10606. standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
  10607. @samp{$(datadir)}, etc.), the effect will be the same:
  10608. user-installations are impossible.
  10609. As a (non-root) user who wants to install a package, you usually have no
  10610. right to install anything in @file{/usr} or @file{/usr/local}. So you
  10611. do something like @samp{./configure --prefix ~/usr} to install a
  10612. package in your own @file{~/usr} tree.
  10613. If a package attempts to install something to some hard-coded path
  10614. (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
  10615. then the installation will fail. @samp{make distcheck} performs such
  10616. a @option{--prefix} installation, hence it will fail too.
  10617. Now, there are some easy solutions.
  10618. The above @code{install-data-local} example for installing
  10619. @file{/etc/afile} would be better replaced by
  10620. @example
  10621. sysconf_DATA = afile
  10622. @end example
  10623. @noindent
  10624. by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
  10625. this is what the GNU Standards require. When such a package is
  10626. installed on an FHS compliant system, the installer will have to set
  10627. @samp{--sysconfdir=/etc}. As the maintainer of the package you
  10628. should not be concerned by such site policies: use the appropriate
  10629. standard directory variable to install your files so that the installer
  10630. can easily redefine these variables to match their site conventions.
  10631. Installing files that should be used by another package is slightly
  10632. more involved. Let's take an example and assume you want to install
  10633. a shared library that is a Python extension module. If you ask Python
  10634. where to install the library, it will answer something like this:
  10635. @example
  10636. % @kbd{python -c 'from distutils import sysconfig;
  10637. print sysconfig.get_python_lib(1,0)'}
  10638. /usr/lib/python2.5/site-packages
  10639. @end example
  10640. If you indeed use this absolute path to install your shared library,
  10641. non-root users will not be able to install the package, hence
  10642. distcheck fails.
  10643. Let's do better. The @samp{sysconfig.get_python_lib()} function
  10644. actually accepts a third argument that will replace Python's
  10645. installation prefix.
  10646. @example
  10647. % @kbd{python -c 'from distutils import sysconfig;
  10648. print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
  10649. $@{exec_prefix@}/lib/python2.5/site-packages
  10650. @end example
  10651. You can also use this new path. If you do
  10652. @itemize @bullet
  10653. @item
  10654. root users can install your package with the same @option{--prefix}
  10655. as Python (you get the behavior of the previous attempt)
  10656. @item
  10657. non-root users can install your package too, they will have the
  10658. extension module in a place that is not searched by Python but they
  10659. can work around this using environment variables (and if you installed
  10660. scripts that use this shared library, it's easy to tell Python were to
  10661. look in the beginning of your script, so the script works in both
  10662. cases).
  10663. @end itemize
  10664. The @code{AM_PATH_PYTHON} macro uses similar commands to define
  10665. @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
  10666. Of course not all tools are as advanced as Python regarding that
  10667. substitution of @var{prefix}. So another strategy is to figure the
  10668. part of the installation directory that must be preserved. For
  10669. instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
  10670. computes @samp{$(lispdir)}:
  10671. @example
  10672. $EMACS -batch -Q -eval '(while load-path
  10673. (princ (concat (car load-path) "\n"))
  10674. (setq load-path (cdr load-path)))' >conftest.out
  10675. lispdir=`sed -n
  10676. -e 's,/$,,'
  10677. -e '/.*\/lib\/x*emacs\/site-lisp$/@{
  10678. s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
  10679. @}'
  10680. -e '/.*\/share\/x*emacs\/site-lisp$/@{
  10681. s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
  10682. @}'
  10683. conftest.out`
  10684. @end example
  10685. I.e., it just picks the first directory that looks like
  10686. @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
  10687. the search path of emacs, and then substitutes @samp{$@{libdir@}} or
  10688. @samp{$@{datadir@}} appropriately.
  10689. The emacs case looks complicated because it processes a list and
  10690. expects two possible layouts, otherwise it's easy, and the benefits for
  10691. non-root users are really worth the extra @command{sed} invocation.
  10692. @node Debugging Make Rules
  10693. @section Debugging Make Rules
  10694. @cindex debugging rules
  10695. @cindex rules, debugging
  10696. The rules and dependency trees generated by @command{automake} can get
  10697. rather complex, and leave the developer head-scratching when things
  10698. don't work as expected. Besides the debug options provided by the
  10699. @command{make} command (@pxref{Options Summary,,, make, The GNU Make
  10700. Manual}), here's a couple of further hints for debugging makefiles
  10701. generated by @command{automake} effectively:
  10702. @itemize
  10703. @item
  10704. If less verbose output has been enabled in the package with the use
  10705. of silent rules (@pxref{Automake Silent Rules}), you can use
  10706. @code{make V=1} to see the commands being executed.
  10707. @item
  10708. @code{make -n} can help show what would be done without actually doing
  10709. it. Note however, that this will @emph{still execute} commands prefixed
  10710. with @samp{+}, and, when using GNU @command{make}, commands that contain
  10711. the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
  10712. Execution,,, make, The GNU Make Manual}).
  10713. Typically, this is helpful to show what recursive rules would do, but it
  10714. means that, in your own rules, you should not mix such recursion with
  10715. actions that change any files.@footnote{Automake's @samp{dist} and
  10716. @samp{distcheck} rules had a bug in this regard in that they created
  10717. directories even with @option{-n}, but this has been fixed in Automake
  10718. 1.11.} Furthermore, note that GNU @command{make} will update
  10719. prerequisites for the @file{Makefile} file itself even with @option{-n}
  10720. (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
  10721. @item
  10722. @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
  10723. @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
  10724. portability quirks associated with this construct.
  10725. @item
  10726. @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
  10727. can be handy to examine the expanded value of variables. You may need
  10728. to use a target other than @samp{print} if that is already used or a
  10729. file with that name exists.
  10730. @item
  10731. @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
  10732. GNU @command{make} command called @command{remake} that copes with
  10733. complex GNU @command{make}-specific Makefiles and allows to trace
  10734. execution, examine variables, and call rules interactively, much like
  10735. a debugger.
  10736. @end itemize
  10737. @node Reporting Bugs
  10738. @section Reporting Bugs
  10739. Most nontrivial software has bugs. Automake is no exception. Although
  10740. we cannot promise we can or will fix a bug, and we might not even agree
  10741. that it is a bug, we want to hear about problems you encounter. Often we
  10742. agree they are bugs and want to fix them.
  10743. To make it possible for us to fix a bug, please report it. In order to
  10744. do so effectively, it helps to know when and how to do it.
  10745. Before reporting a bug, it is a good idea to see if it is already known.
  10746. You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
  10747. and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
  10748. bug-automake mailing list archives} for previous bug reports. We
  10749. previously used a
  10750. @uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
  10751. Gnats database} for bug tracking, so some bugs might have been reported
  10752. there already. Please do not use it for new bug reports, however.
  10753. If the bug is not already known, it should be reported. It is very
  10754. important to report bugs in a way that is useful and efficient. For
  10755. this, please familiarize yourself with
  10756. @uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
  10757. Report Bugs Effectively} and
  10758. @uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
  10759. Questions the Smart Way}. This helps you and developers to save time
  10760. which can then be spent on fixing more bugs and implementing more
  10761. features.
  10762. For a bug report, a feature request or other suggestions, please send
  10763. email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
  10764. bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
  10765. sure to include the versions of Autoconf and Automake that you use.
  10766. Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
  10767. reproduces the problem you encounter. If you have encountered test
  10768. suite failures, please attach the @file{test-suite.log} file.
  10769. @c ========================================================== Appendices
  10770. @page
  10771. @node Copying This Manual
  10772. @appendix Copying This Manual
  10773. @menu
  10774. * GNU Free Documentation License:: License for copying this manual
  10775. @end menu
  10776. @node GNU Free Documentation License
  10777. @appendixsec GNU Free Documentation License
  10778. @include fdl.texi
  10779. @page
  10780. @node Indices
  10781. @appendix Indices
  10782. @menu
  10783. * Macro Index:: Index of Autoconf macros
  10784. * Variable Index:: Index of Makefile variables
  10785. * General Index:: General index
  10786. @end menu
  10787. @node Macro Index
  10788. @appendixsec Macro Index
  10789. @printindex fn
  10790. @node Variable Index
  10791. @appendixsec Variable Index
  10792. @printindex vr
  10793. @node General Index
  10794. @appendixsec General Index
  10795. @printindex cp
  10796. @bye
  10797. @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
  10798. @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
  10799. @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
  10800. @c LocalWords: dir Automake's ac Dist Gnits gnits dfn Autoconf's pxref
  10801. @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
  10802. @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
  10803. @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
  10804. @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
  10805. @c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
  10806. @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
  10807. @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
  10808. @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
  10809. @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
  10810. @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
  10811. @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
  10812. @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
  10813. @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
  10814. @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
  10815. @c LocalWords: dirlist noindent usr TIOCGWINSZ sc
  10816. @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
  10817. @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
  10818. @c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
  10819. @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
  10820. @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
  10821. @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
  10822. @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
  10823. @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
  10824. @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
  10825. @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
  10826. @c LocalWords: OBJCXXFLAGS
  10827. @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
  10828. @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
  10829. @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
  10830. @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
  10831. @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
  10832. @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
  10833. @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
  10834. @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
  10835. @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
  10836. @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
  10837. @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
  10838. @c LocalWords: depfile tmpdepfile depmode const interoperate
  10839. @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
  10840. @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
  10841. @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
  10842. @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
  10843. @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
  10844. @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
  10845. @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
  10846. @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
  10847. @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
  10848. @c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
  10849. @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
  10850. @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
  10851. @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
  10852. @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
  10853. @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
  10854. @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
  10855. @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
  10856. @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
  10857. @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
  10858. @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
  10859. @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
  10860. @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
  10861. @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
  10862. @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
  10863. @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
  10864. @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
  10865. @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
  10866. @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
  10867. @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
  10868. @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
  10869. @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
  10870. @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
  10871. @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
  10872. @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
  10873. @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
  10874. @c LocalWords: barexec Pinard's automatize initialize lzip xz cscope