automake.info-1 293 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844684568466847684868496850685168526853685468556856685768586859686068616862686368646865686668676868686968706871687268736874687568766877687868796880688168826883688468856886688768886889689068916892689368946895689668976898689969006901690269036904690569066907690869096910691169126913691469156916
  1. This is automake.info, produced by makeinfo version 6.1 from
  2. automake.texi.
  3. This manual is for GNU Automake (version 1.15.1, 17 June 2017), a
  4. program that creates GNU standards-compliant Makefiles from template
  5. files.
  6. Copyright © 1995-2017 Free Software Foundation, Inc.
  7. Permission is granted to copy, distribute and/or modify this
  8. document under the terms of the GNU Free Documentation License,
  9. Version 1.3 or any later version published by the Free Software
  10. Foundation; with no Invariant Sections, with no Front-Cover texts,
  11. and with no Back-Cover Texts. A copy of the license is included in
  12. the section entitled “GNU Free Documentation License.”
  13. INFO-DIR-SECTION Software development
  14. START-INFO-DIR-ENTRY
  15. * Automake: (automake). Making GNU standards-compliant Makefiles.
  16. END-INFO-DIR-ENTRY
  17. INFO-DIR-SECTION Individual utilities
  18. START-INFO-DIR-ENTRY
  19. * aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4.
  20. * automake-invocation: (automake)automake Invocation. Generating Makefile.in.
  21. END-INFO-DIR-ENTRY
  22. 
  23. File: automake.info, Node: Top, Next: Introduction, Up: (dir)
  24. GNU Automake
  25. ************
  26. This manual is for GNU Automake (version 1.15.1, 17 June 2017), a
  27. program that creates GNU standards-compliant Makefiles from template
  28. files.
  29. Copyright © 1995-2017 Free Software Foundation, Inc.
  30. Permission is granted to copy, distribute and/or modify this
  31. document under the terms of the GNU Free Documentation License,
  32. Version 1.3 or any later version published by the Free Software
  33. Foundation; with no Invariant Sections, with no Front-Cover texts,
  34. and with no Back-Cover Texts. A copy of the license is included in
  35. the section entitled “GNU Free Documentation License.”
  36. * Menu:
  37. * Introduction:: Automake’s purpose
  38. * Autotools Introduction:: An Introduction to the Autotools
  39. * Generalities:: General ideas
  40. * Examples:: Some example packages
  41. * automake Invocation:: Creating a Makefile.in
  42. * configure:: Scanning configure.ac, using aclocal
  43. * Directories:: Declaring subdirectories
  44. * Programs:: Building programs and libraries
  45. * Other Objects:: Other derived objects
  46. * Other GNU Tools:: Other GNU Tools
  47. * Documentation:: Building documentation
  48. * Install:: What gets installed
  49. * Clean:: What gets cleaned
  50. * Dist:: What goes in a distribution
  51. * Tests:: Support for test suites
  52. * Rebuilding:: Automatic rebuilding of Makefile
  53. * Options:: Changing Automake’s behavior
  54. * Miscellaneous:: Miscellaneous rules
  55. * Include:: Including extra files in an Automake template
  56. * Conditionals:: Conditionals
  57. * Silencing Make:: Obtain less verbose output from ‘make’
  58. * Gnits:: The effect of ‘--gnu’ and ‘--gnits’
  59. * Not Enough:: When Automake is not Enough
  60. * Distributing:: Distributing the Makefile.in
  61. * API Versioning:: About compatibility between Automake versions
  62. * Upgrading:: Upgrading to a Newer Automake Version
  63. * FAQ:: Frequently Asked Questions
  64. * Copying This Manual:: How to make copies of this manual
  65. * Indices:: Indices of variables, macros, and concepts
  66. — The Detailed Node Listing —
  67. An Introduction to the Autotools
  68. * GNU Build System:: Introducing the GNU Build System
  69. * Use Cases:: Use Cases for the GNU Build System
  70. * Why Autotools:: How Autotools Help
  71. * Hello World:: A Small Hello World Package
  72. Use Cases for the GNU Build System
  73. * Basic Installation:: Common installation procedure
  74. * Standard Targets:: A list of standard Makefile targets
  75. * Standard Directory Variables:: A list of standard directory variables
  76. * Standard Configuration Variables:: Using configuration variables
  77. * config.site:: Using a config.site file
  78. * VPATH Builds:: Parallel build trees
  79. * Two-Part Install:: Installing data and programs separately
  80. * Cross-Compilation:: Building for other architectures
  81. * Renaming:: Renaming programs at install time
  82. * DESTDIR:: Building binary packages with DESTDIR
  83. * Preparing Distributions:: Rolling out tarballs
  84. * Dependency Tracking:: Automatic dependency tracking
  85. * Nested Packages:: The GNU Build Systems can be nested
  86. A Small Hello World
  87. * Creating amhello:: Create ‘amhello-1.0.tar.gz’ from scratch
  88. * amhello's configure.ac Setup Explained::
  89. * amhello's Makefile.am Setup Explained::
  90. General ideas
  91. * General Operation:: General operation of Automake
  92. * Strictness:: Standards conformance checking
  93. * Uniform:: The Uniform Naming Scheme
  94. * Length Limitations:: Staying below the command line length limit
  95. * Canonicalization:: How derived variables are named
  96. * User Variables:: Variables reserved for the user
  97. * Auxiliary Programs:: Programs automake might require
  98. Some example packages
  99. * Complete:: A simple example, start to finish
  100. * true:: Building true and false
  101. Scanning ‘configure.ac’, using ‘aclocal’
  102. * Requirements:: Configuration requirements
  103. * Optional:: Other things Automake recognizes
  104. * aclocal Invocation:: Auto-generating aclocal.m4
  105. * Macros:: Autoconf macros supplied with Automake
  106. Auto-generating aclocal.m4
  107. * aclocal Options:: Options supported by aclocal
  108. * Macro Search Path:: How aclocal finds .m4 files
  109. * Extending aclocal:: Writing your own aclocal macros
  110. * Local Macros:: Organizing local macros
  111. * Serials:: Serial lines in Autoconf macros
  112. * Future of aclocal:: aclocal’s scheduled death
  113. Autoconf macros supplied with Automake
  114. * Public Macros:: Macros that you can use.
  115. * Private Macros:: Macros that you should not use.
  116. Directories
  117. * Subdirectories:: Building subdirectories recursively
  118. * Conditional Subdirectories:: Conditionally not building directories
  119. * Alternative:: Subdirectories without recursion
  120. * Subpackages:: Nesting packages
  121. Conditional Subdirectories
  122. * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
  123. * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
  124. * Subdirectories with AC_SUBST:: Another way for conditional recursion
  125. * Unconfigured Subdirectories:: Not even creating a ‘Makefile’
  126. Building Programs and Libraries
  127. * A Program:: Building a program
  128. * A Library:: Building a library
  129. * A Shared Library:: Building a Libtool library
  130. * Program and Library Variables:: Variables controlling program and
  131. library builds
  132. * Default _SOURCES:: Default source files
  133. * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
  134. * Program Variables:: Variables used when building a program
  135. * Yacc and Lex:: Yacc and Lex support
  136. * C++ Support:: Compiling C++ sources
  137. * Objective C Support:: Compiling Objective C sources
  138. * Objective C++ Support:: Compiling Objective C++ sources
  139. * Unified Parallel C Support:: Compiling Unified Parallel C sources
  140. * Assembly Support:: Compiling assembly sources
  141. * Fortran 77 Support:: Compiling Fortran 77 sources
  142. * Fortran 9x Support:: Compiling Fortran 9x sources
  143. * Java Support with gcj:: Compiling Java sources using gcj
  144. * Vala Support:: Compiling Vala sources
  145. * Support for Other Languages:: Compiling other languages
  146. * Dependencies:: Automatic dependency tracking
  147. * EXEEXT:: Support for executable extensions
  148. Building a program
  149. * Program Sources:: Defining program sources
  150. * Linking:: Linking with libraries or extra objects
  151. * Conditional Sources:: Handling conditional sources
  152. * Conditional Programs:: Building a program conditionally
  153. Building a Shared Library
  154. * Libtool Concept:: Introducing Libtool
  155. * Libtool Libraries:: Declaring Libtool Libraries
  156. * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
  157. * Conditional Libtool Sources:: Choosing Library Sources Conditionally
  158. * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
  159. * Libtool Modules:: Building Libtool Modules
  160. * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
  161. * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
  162. * Libtool Issues:: Common Issues Related to Libtool’s Use
  163. Common Issues Related to Libtool’s Use
  164. * Error required file ltmain.sh not found:: The need to run libtoolize
  165. * Objects created both with libtool and without:: Avoid a specific build race
  166. Fortran 77 Support
  167. * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
  168. * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
  169. * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
  170. Mixing Fortran 77 With C and C++
  171. * How the Linker is Chosen:: Automatic linker selection
  172. Fortran 9x Support
  173. * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
  174. Other Derived Objects
  175. * Scripts:: Executable scripts
  176. * Headers:: Header files
  177. * Data:: Architecture-independent data files
  178. * Sources:: Derived sources
  179. Built Sources
  180. * Built Sources Example:: Several ways to handle built sources.
  181. Other GNU Tools
  182. * Emacs Lisp:: Emacs Lisp
  183. * gettext:: Gettext
  184. * Libtool:: Libtool
  185. * Java:: Java bytecode compilation (deprecated)
  186. * Python:: Python
  187. Building documentation
  188. * Texinfo:: Texinfo
  189. * Man Pages:: Man pages
  190. What Gets Installed
  191. * Basics of Installation:: What gets installed where
  192. * The Two Parts of Install:: Installing data and programs separately
  193. * Extending Installation:: Adding your own rules for installation
  194. * Staged Installs:: Installation in a temporary location
  195. * Install Rules for the User:: Useful additional rules
  196. What Goes in a Distribution
  197. * Basics of Distribution:: Files distributed by default
  198. * Fine-grained Distribution Control:: ‘dist_’ and ‘nodist_’ prefixes
  199. * The dist Hook:: A target for last-minute distribution changes
  200. * Checking the Distribution:: ‘make distcheck’ explained
  201. * The Types of Distributions:: A variety of formats and compression methods
  202. Support for test suites
  203. * Generalities about Testing:: Generic concepts and terminology about testing
  204. * Simple Tests:: Listing test scripts in ‘TESTS’
  205. * Custom Test Drivers:: Writing and using custom test drivers
  206. * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
  207. * DejaGnu Tests:: Interfacing with the ‘dejagnu’ testing framework
  208. * Install Tests:: Running tests on installed packages
  209. Simple Tests
  210. * Scripts-based Testsuites:: Automake-specific concepts and terminology
  211. * Serial Test Harness:: Older (and discouraged) serial test harness
  212. * Parallel Test Harness:: Generic concurrent test harness
  213. Using the TAP test protocol
  214. * Introduction to TAP::
  215. * Use TAP with the Automake test harness::
  216. * Incompatibilities with other TAP parsers and drivers::
  217. * Links and external resources on TAP::
  218. Custom Test Drivers
  219. * Overview of Custom Test Drivers Support::
  220. * Declaring Custom Test Drivers::
  221. * API for Custom Test Drivers::
  222. API for Custom Test Drivers
  223. * Command-line arguments for test drivers::
  224. * Log files generation and test results recording::
  225. * Testsuite progress output::
  226. Changing Automake’s Behavior
  227. * Options generalities:: Semantics of Automake option
  228. * List of Automake options:: A comprehensive list of Automake options
  229. Miscellaneous Rules
  230. * Tags:: Interfacing to cscope, etags and mkid
  231. * Suffixes:: Handling new file extensions
  232. Conditionals
  233. * Usage of Conditionals:: Declaring conditional content
  234. * Limits of Conditionals:: Enclosing complete statements
  235. Silencing Make
  236. * Make verbosity:: Make is verbose by default
  237. * Tricks For Silencing Make:: Standard and generic ways to silence make
  238. * Automake Silent Rules:: How Automake can help in silencing make
  239. When Automake Isn’t Enough
  240. * Extending:: Adding new rules or overriding existing ones.
  241. * Third-Party Makefiles:: Integrating Non-Automake ‘Makefile’s.
  242. Frequently Asked Questions about Automake
  243. * CVS:: CVS and generated files
  244. * maintainer-mode:: missing and AM_MAINTAINER_MODE
  245. * Wildcards:: Why doesn’t Automake support wildcards?
  246. * Limitations on File Names:: Limitations on source and installed file names
  247. * Errors with distclean:: Files left in build directory after distclean
  248. * Flag Variables Ordering:: CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS
  249. * Renamed Objects:: Why are object files sometimes renamed?
  250. * Per-Object Flags:: How to simulate per-object flags?
  251. * Multiple Outputs:: Writing rules for tools with many output files
  252. * Hard-Coded Install Paths:: Installing to hard-coded locations
  253. * Debugging Make Rules:: Strategies when things don’t work as expected
  254. * Reporting Bugs:: Feedback on bugs and feature requests
  255. Copying This Manual
  256. * GNU Free Documentation License:: License for copying this manual
  257. Indices
  258. * Macro Index:: Index of Autoconf macros
  259. * Variable Index:: Index of Makefile variables
  260. * General Index:: General index
  261. 
  262. File: automake.info, Node: Introduction, Next: Autotools Introduction, Prev: Top, Up: Top
  263. 1 Introduction
  264. **************
  265. Automake is a tool for automatically generating ‘Makefile.in’s from
  266. files called ‘Makefile.am’. Each ‘Makefile.am’ is basically a series of
  267. ‘make’ variable definitions(1), with rules being thrown in occasionally.
  268. The generated ‘Makefile.in’s are compliant with the GNU Makefile
  269. standards.
  270. The GNU Makefile Standards Document (*note (standards)Makefile
  271. Conventions::) is long, complicated, and subject to change. The goal of
  272. Automake is to remove the burden of Makefile maintenance from the back
  273. of the individual GNU maintainer (and put it on the back of the Automake
  274. maintainers).
  275. The typical Automake input file is simply a series of variable
  276. definitions. Each such file is processed to create a ‘Makefile.in’.
  277. Automake does constrain a project in certain ways; for instance, it
  278. assumes that the project uses Autoconf (*note Introduction:
  279. (autoconf)Top.), and enforces certain restrictions on the ‘configure.ac’
  280. contents.
  281. Automake requires ‘perl’ in order to generate the ‘Makefile.in’s.
  282. However, the distributions created by Automake are fully GNU
  283. standards-compliant, and do not require ‘perl’ in order to be built.
  284. For more information on bug reports, *Note Reporting Bugs::.
  285. ---------- Footnotes ----------
  286. (1) These variables are also called “make macros” in Make
  287. terminology, however in this manual we reserve the term “macro” for
  288. Autoconf’s macros.
  289. 
  290. File: automake.info, Node: Autotools Introduction, Next: Generalities, Prev: Introduction, Up: Top
  291. 2 An Introduction to the Autotools
  292. **********************************
  293. If you are new to Automake, maybe you know that it is part of a set of
  294. tools called _The Autotools_. Maybe you’ve already delved into a
  295. package full of files named ‘configure’, ‘configure.ac’, ‘Makefile.in’,
  296. ‘Makefile.am’, ‘aclocal.m4’, ..., some of them claiming to be _generated
  297. by_ Autoconf or Automake. But the exact purpose of these files and
  298. their relations is probably fuzzy. The goal of this chapter is to
  299. introduce you to this machinery, to show you how it works and how
  300. powerful it is. If you’ve never installed or seen such a package, do
  301. not worry: this chapter will walk you through it.
  302. If you need some teaching material, more illustrations, or a less
  303. ‘automake’-centered continuation, some slides for this introduction are
  304. available in Alexandre Duret-Lutz’s Autotools Tutorial
  305. (http://www.lrde.epita.fr/~adl/autotools.html). This chapter is the
  306. written version of the first part of his tutorial.
  307. * Menu:
  308. * GNU Build System:: Introducing the GNU Build System
  309. * Use Cases:: Use Cases for the GNU Build System
  310. * Why Autotools:: How Autotools Help
  311. * Hello World:: A Small Hello World Package
  312. 
  313. File: automake.info, Node: GNU Build System, Next: Use Cases, Up: Autotools Introduction
  314. 2.1 Introducing the GNU Build System
  315. ====================================
  316. It is a truth universally acknowledged, that as a developer in
  317. possession of a new package, you must be in want of a build system.
  318. In the Unix world, such a build system is traditionally achieved
  319. using the command ‘make’ (*note Overview: (make)Top.). You express the
  320. recipe to build your package in a ‘Makefile’. This file is a set of
  321. rules to build the files in the package. For instance the program
  322. ‘prog’ may be built by running the linker on the files ‘main.o’,
  323. ‘foo.o’, and ‘bar.o’; the file ‘main.o’ may be built by running the
  324. compiler on ‘main.c’; etc. Each time ‘make’ is run, it reads
  325. ‘Makefile’, checks the existence and modification time of the files
  326. mentioned, decides what files need to be built (or rebuilt), and runs
  327. the associated commands.
  328. When a package needs to be built on a different platform than the one
  329. it was developed on, its ‘Makefile’ usually needs to be adjusted. For
  330. instance the compiler may have another name or require more options. In
  331. 1991, David J. MacKenzie got tired of customizing ‘Makefile’ for the 20
  332. platforms he had to deal with. Instead, he handcrafted a little shell
  333. script called ‘configure’ to automatically adjust the ‘Makefile’ (*note
  334. Genesis: (autoconf)Genesis.). Compiling his package was now as simple
  335. as running ‘./configure && make’.
  336. Today this process has been standardized in the GNU project. The GNU
  337. Coding Standards (*note The Release Process: (standards)Managing
  338. Releases.) explains how each package of the GNU project should have a
  339. ‘configure’ script, and the minimal interface it should have. The
  340. ‘Makefile’ too should follow some established conventions. The result?
  341. A unified build system that makes all packages almost indistinguishable
  342. by the installer. In its simplest scenario, all the installer has to do
  343. is to unpack the package, run ‘./configure && make && make install’, and
  344. repeat with the next package to install.
  345. We call this build system the “GNU Build System”, since it was grown
  346. out of the GNU project. However it is used by a vast number of other
  347. packages: following any existing convention has its advantages.
  348. The Autotools are tools that will create a GNU Build System for your
  349. package. Autoconf mostly focuses on ‘configure’ and Automake on
  350. ‘Makefile’s. It is entirely possible to create a GNU Build System
  351. without the help of these tools. However it is rather burdensome and
  352. error-prone. We will discuss this again after some illustration of the
  353. GNU Build System in action.
  354. 
  355. File: automake.info, Node: Use Cases, Next: Why Autotools, Prev: GNU Build System, Up: Autotools Introduction
  356. 2.2 Use Cases for the GNU Build System
  357. ======================================
  358. In this section we explore several use cases for the GNU Build System.
  359. You can replay all of these examples on the ‘amhello-1.0.tar.gz’ package
  360. distributed with Automake. If Automake is installed on your system, you
  361. should find a copy of this file in
  362. ‘PREFIX/share/doc/automake/amhello-1.0.tar.gz’, where PREFIX is the
  363. installation prefix specified during configuration (PREFIX defaults to
  364. ‘/usr/local’, however if Automake was installed by some GNU/Linux
  365. distribution it most likely has been set to ‘/usr’). If you do not have
  366. a copy of Automake installed, you can find a copy of this file inside
  367. the ‘doc/’ directory of the Automake package.
  368. Some of the following use cases present features that are in fact
  369. extensions to the GNU Build System. Read: they are not specified by the
  370. GNU Coding Standards, but they are nonetheless part of the build system
  371. created by the Autotools. To keep things simple, we do not point out
  372. the difference. Our objective is to show you many of the features that
  373. the build system created by the Autotools will offer to you.
  374. * Menu:
  375. * Basic Installation:: Common installation procedure
  376. * Standard Targets:: A list of standard Makefile targets
  377. * Standard Directory Variables:: A list of standard directory variables
  378. * Standard Configuration Variables:: Using configuration variables
  379. * config.site:: Using a config.site file
  380. * VPATH Builds:: Parallel build trees
  381. * Two-Part Install:: Installing data and programs separately
  382. * Cross-Compilation:: Building for other architectures
  383. * Renaming:: Renaming programs at install time
  384. * DESTDIR:: Building binary packages with DESTDIR
  385. * Preparing Distributions:: Rolling out tarballs
  386. * Dependency Tracking:: Automatic dependency tracking
  387. * Nested Packages:: The GNU Build Systems can be nested
  388. 
  389. File: automake.info, Node: Basic Installation, Next: Standard Targets, Up: Use Cases
  390. 2.2.1 Basic Installation
  391. ------------------------
  392. The most common installation procedure looks as follows.
  393. ~ % tar zxf amhello-1.0.tar.gz
  394. ~ % cd amhello-1.0
  395. ~/amhello-1.0 % ./configure
  396. ...
  397. config.status: creating Makefile
  398. config.status: creating src/Makefile
  399. ...
  400. ~/amhello-1.0 % make
  401. ...
  402. ~/amhello-1.0 % make check
  403. ...
  404. ~/amhello-1.0 % su
  405. Password:
  406. /home/adl/amhello-1.0 # make install
  407. ...
  408. /home/adl/amhello-1.0 # exit
  409. ~/amhello-1.0 % make installcheck
  410. ...
  411. The user first unpacks the package. Here, and in the following
  412. examples, we will use the non-portable ‘tar zxf’ command for simplicity.
  413. On a system without GNU ‘tar’ installed, this command should read
  414. ‘gunzip -c amhello-1.0.tar.gz | tar xf -’.
  415. The user then enters the newly created directory to run the
  416. ‘configure’ script. This script probes the system for various features,
  417. and finally creates the ‘Makefile’s. In this toy example there are only
  418. two ‘Makefile’s, but in real-world projects, there may be many more,
  419. usually one ‘Makefile’ per directory.
  420. It is now possible to run ‘make’. This will construct all the
  421. programs, libraries, and scripts that need to be constructed for the
  422. package. In our example, this compiles the ‘hello’ program. All files
  423. are constructed in place, in the source tree; we will see later how this
  424. can be changed.
  425. ‘make check’ causes the package’s tests to be run. This step is not
  426. mandatory, but it is often good to make sure the programs that have been
  427. built behave as they should, before you decide to install them. Our
  428. example does not contain any tests, so running ‘make check’ is a no-op.
  429. After everything has been built, and maybe tested, it is time to
  430. install it on the system. That means copying the programs, libraries,
  431. header files, scripts, and other data files from the source directory to
  432. their final destination on the system. The command ‘make install’ will
  433. do that. However, by default everything will be installed in
  434. subdirectories of ‘/usr/local’: binaries will go into ‘/usr/local/bin’,
  435. libraries will end up in ‘/usr/local/lib’, etc. This destination is
  436. usually not writable by any user, so we assume that we have to become
  437. root before we can run ‘make install’. In our example, running ‘make
  438. install’ will copy the program ‘hello’ into ‘/usr/local/bin’ and
  439. ‘README’ into ‘/usr/local/share/doc/amhello’.
  440. A last and optional step is to run ‘make installcheck’. This command
  441. may run tests on the installed files. ‘make check’ tests the files in
  442. the source tree, while ‘make installcheck’ tests their installed copies.
  443. The tests run by the latter can be different from those run by the
  444. former. For instance, there are tests that cannot be run in the source
  445. tree. Conversely, some packages are set up so that ‘make installcheck’
  446. will run the very same tests as ‘make check’, only on different files
  447. (non-installed vs. installed). It can make a difference, for instance
  448. when the source tree’s layout is different from that of the
  449. installation. Furthermore it may help to diagnose an incomplete
  450. installation.
  451. Presently most packages do not have any ‘installcheck’ tests because
  452. the existence of ‘installcheck’ is little known, and its usefulness is
  453. neglected. Our little toy package is no better: ‘make installcheck’
  454. does nothing.
  455. 
  456. File: automake.info, Node: Standard Targets, Next: Standard Directory Variables, Prev: Basic Installation, Up: Use Cases
  457. 2.2.2 Standard ‘Makefile’ Targets
  458. ---------------------------------
  459. So far we have come across four ways to run ‘make’ in the GNU Build
  460. System: ‘make’, ‘make check’, ‘make install’, and ‘make installcheck’.
  461. The words ‘check’, ‘install’, and ‘installcheck’, passed as arguments to
  462. ‘make’, are called “targets”. ‘make’ is a shorthand for ‘make all’,
  463. ‘all’ being the default target in the GNU Build System.
  464. Here is a list of the most useful targets that the GNU Coding
  465. Standards specify.
  466. ‘make all’
  467. Build programs, libraries, documentation, etc. (same as ‘make’).
  468. ‘make install’
  469. Install what needs to be installed, copying the files from the
  470. package’s tree to system-wide directories.
  471. ‘make install-strip’
  472. Same as ‘make install’, then strip debugging symbols. Some users
  473. like to trade space for useful bug reports...
  474. ‘make uninstall’
  475. The opposite of ‘make install’: erase the installed files. (This
  476. needs to be run from the same build tree that was installed.)
  477. ‘make clean’
  478. Erase from the build tree the files built by ‘make all’.
  479. ‘make distclean’
  480. Additionally erase anything ‘./configure’ created.
  481. ‘make check’
  482. Run the test suite, if any.
  483. ‘make installcheck’
  484. Check the installed programs or libraries, if supported.
  485. ‘make dist’
  486. Recreate ‘PACKAGE-VERSION.tar.gz’ from all the source files.
  487. 
  488. File: automake.info, Node: Standard Directory Variables, Next: Standard Configuration Variables, Prev: Standard Targets, Up: Use Cases
  489. 2.2.3 Standard Directory Variables
  490. ----------------------------------
  491. The GNU Coding Standards also specify a hierarchy of variables to denote
  492. installation directories. Some of these are:
  493. Directory variable Default value
  494. -------------------------------------------------------
  495. ‘prefix’ ‘/usr/local’
  496. ‘exec_prefix’ ‘${prefix}’
  497. ‘bindir’ ‘${exec_prefix}/bin’
  498. ‘libdir’ ‘${exec_prefix}/lib’
  499. ...
  500. ‘includedir’ ‘${prefix}/include’
  501. ‘datarootdir’ ‘${prefix}/share’
  502. ‘datadir’ ‘${datarootdir}’
  503. ‘mandir’ ‘${datarootdir}/man’
  504. ‘infodir’ ‘${datarootdir}/info’
  505. ‘docdir’ ‘${datarootdir}/doc/${PACKAGE}’
  506. ...
  507. Each of these directories has a role which is often obvious from its
  508. name. In a package, any installable file will be installed in one of
  509. these directories. For instance in ‘amhello-1.0’, the program ‘hello’
  510. is to be installed in BINDIR, the directory for binaries. The default
  511. value for this directory is ‘/usr/local/bin’, but the user can supply a
  512. different value when calling ‘configure’. Also the file ‘README’ will
  513. be installed into DOCDIR, which defaults to
  514. ‘/usr/local/share/doc/amhello’.
  515. As a user, if you wish to install a package on your own account, you
  516. could proceed as follows:
  517. ~/amhello-1.0 % ./configure --prefix ~/usr
  518. ...
  519. ~/amhello-1.0 % make
  520. ...
  521. ~/amhello-1.0 % make install
  522. ...
  523. This would install ‘~/usr/bin/hello’ and
  524. ‘~/usr/share/doc/amhello/README’.
  525. The list of all such directory options is shown by ‘./configure
  526. --help’.
  527. 
  528. File: automake.info, Node: Standard Configuration Variables, Next: config.site, Prev: Standard Directory Variables, Up: Use Cases
  529. 2.2.4 Standard Configuration Variables
  530. --------------------------------------
  531. The GNU Coding Standards also define a set of standard configuration
  532. variables used during the build. Here are some:
  533. ‘CC’
  534. C compiler command
  535. ‘CFLAGS’
  536. C compiler flags
  537. ‘CXX’
  538. C++ compiler command
  539. ‘CXXFLAGS’
  540. C++ compiler flags
  541. ‘LDFLAGS’
  542. linker flags
  543. ‘CPPFLAGS’
  544. C/C++ preprocessor flags
  545. ...
  546. ‘configure’ usually does a good job at setting appropriate values for
  547. these variables, but there are cases where you may want to override
  548. them. For instance you may have several versions of a compiler
  549. installed and would like to use another one, you may have header files
  550. installed outside the default search path of the compiler, or even
  551. libraries out of the way of the linker.
  552. Here is how one would call ‘configure’ to force it to use ‘gcc-3’ as
  553. C compiler, use header files from ‘~/usr/include’ when compiling, and
  554. libraries from ‘~/usr/lib’ when linking.
  555. ~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \
  556. CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib
  557. Again, a full list of these variables appears in the output of
  558. ‘./configure --help’.
  559. 
  560. File: automake.info, Node: config.site, Next: VPATH Builds, Prev: Standard Configuration Variables, Up: Use Cases
  561. 2.2.5 Overriding Default Configuration Setting with ‘config.site’
  562. -----------------------------------------------------------------
  563. When installing several packages using the same setup, it can be
  564. convenient to create a file to capture common settings. If a file named
  565. ‘PREFIX/share/config.site’ exists, ‘configure’ will source it at the
  566. beginning of its execution.
  567. Recall the command from the previous section:
  568. ~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \
  569. CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib
  570. Assuming we are installing many package in ‘~/usr’, and will always
  571. want to use these definitions of ‘CC’, ‘CPPFLAGS’, and ‘LDFLAGS’, we can
  572. automate this by creating the following ‘~/usr/share/config.site’ file:
  573. test -z "$CC" && CC=gcc-3
  574. test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
  575. test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
  576. Now, any time a ‘configure’ script is using the ‘~/usr’ prefix, it
  577. will execute the above ‘config.site’ and define these three variables.
  578. ~/amhello-1.0 % ./configure --prefix ~/usr
  579. configure: loading site script /home/adl/usr/share/config.site
  580. ...
  581. *Note Setting Site Defaults: (autoconf)Site Defaults, for more
  582. information about this feature.
  583. 
  584. File: automake.info, Node: VPATH Builds, Next: Two-Part Install, Prev: config.site, Up: Use Cases
  585. 2.2.6 Parallel Build Trees (a.k.a. VPATH Builds)
  586. ------------------------------------------------
  587. The GNU Build System distinguishes two trees: the source tree, and the
  588. build tree.
  589. The source tree is rooted in the directory containing ‘configure’.
  590. It contains all the sources files (those that are distributed), and may
  591. be arranged using several subdirectories.
  592. The build tree is rooted in the directory in which ‘configure’ was
  593. run, and is populated with all object files, programs, libraries, and
  594. other derived files built from the sources (and hence not distributed).
  595. The build tree usually has the same subdirectory layout as the source
  596. tree; its subdirectories are created automatically by the build system.
  597. If ‘configure’ is executed in its own directory, the source and build
  598. trees are combined: derived files are constructed in the same
  599. directories as their sources. This was the case in our first
  600. installation example (*note Basic Installation::).
  601. A common request from users is that they want to confine all derived
  602. files to a single directory, to keep their source directories
  603. uncluttered. Here is how we could run ‘configure’ to build everything
  604. in a subdirectory called ‘build/’.
  605. ~ % tar zxf ~/amhello-1.0.tar.gz
  606. ~ % cd amhello-1.0
  607. ~/amhello-1.0 % mkdir build && cd build
  608. ~/amhello-1.0/build % ../configure
  609. ...
  610. ~/amhello-1.0/build % make
  611. ...
  612. These setups, where source and build trees are different, are often
  613. called “parallel builds” or “VPATH builds”. The expression _parallel
  614. build_ is misleading: the word _parallel_ is a reference to the way the
  615. build tree shadows the source tree, it is not about some concurrency in
  616. the way build commands are run. For this reason we refer to such setups
  617. using the name _VPATH builds_ in the following. _VPATH_ is the name of
  618. the ‘make’ feature used by the ‘Makefile’s to allow these builds (*note
  619. ‘VPATH’ Search Path for All Prerequisites: (make)General Search.).
  620. VPATH builds have other interesting uses. One is to build the same
  621. sources with multiple configurations. For instance:
  622. ~ % tar zxf ~/amhello-1.0.tar.gz
  623. ~ % cd amhello-1.0
  624. ~/amhello-1.0 % mkdir debug optim && cd debug
  625. ~/amhello-1.0/debug % ../configure CFLAGS='-g -O0'
  626. ...
  627. ~/amhello-1.0/debug % make
  628. ...
  629. ~/amhello-1.0/debug % cd ../optim
  630. ~/amhello-1.0/optim % ../configure CFLAGS='-O3 -fomit-frame-pointer'
  631. ...
  632. ~/amhello-1.0/optim % make
  633. ...
  634. With network file systems, a similar approach can be used to build
  635. the same sources on different machines. For instance, suppose that the
  636. sources are installed on a directory shared by two hosts: ‘HOST1’ and
  637. ‘HOST2’, which may be different platforms.
  638. ~ % cd /nfs/src
  639. /nfs/src % tar zxf ~/amhello-1.0.tar.gz
  640. On the first host, you could create a local build directory:
  641. [HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh
  642. [HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure
  643. ...
  644. [HOST1] /tmp/amh % make && sudo make install
  645. ...
  646. (Here we assume that the installer has configured ‘sudo’ so it can
  647. execute ‘make install’ with root privileges; it is more convenient than
  648. using ‘su’ like in *note Basic Installation::).
  649. On the second host, you would do exactly the same, possibly at the
  650. same time:
  651. [HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh
  652. [HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure
  653. ...
  654. [HOST2] /tmp/amh % make && sudo make install
  655. ...
  656. In this scenario, nothing forbids the ‘/nfs/src/amhello-1.0’
  657. directory from being read-only. In fact VPATH builds are also a means
  658. of building packages from a read-only medium such as a CD-ROM. (The FSF
  659. used to sell CD-ROM with unpacked source code, before the GNU project
  660. grew so big.)
  661. 
  662. File: automake.info, Node: Two-Part Install, Next: Cross-Compilation, Prev: VPATH Builds, Up: Use Cases
  663. 2.2.7 Two-Part Installation
  664. ---------------------------
  665. In our last example (*note VPATH Builds::), a source tree was shared by
  666. two hosts, but compilation and installation were done separately on each
  667. host.
  668. The GNU Build System also supports networked setups where part of the
  669. installed files should be shared amongst multiple hosts. It does so by
  670. distinguishing architecture-dependent files from
  671. architecture-independent files, and providing two ‘Makefile’ targets to
  672. install each of these classes of files.
  673. These targets are ‘install-exec’ for architecture-dependent files and
  674. ‘install-data’ for architecture-independent files. The command we used
  675. up to now, ‘make install’, can be thought of as a shorthand for ‘make
  676. install-exec install-data’.
  677. From the GNU Build System point of view, the distinction between
  678. architecture-dependent files and architecture-independent files is based
  679. exclusively on the directory variable used to specify their installation
  680. destination. In the list of directory variables we provided earlier
  681. (*note Standard Directory Variables::), all the variables based on
  682. EXEC-PREFIX designate architecture-dependent directories whose files
  683. will be installed by ‘make install-exec’. The others designate
  684. architecture-independent directories and will serve files installed by
  685. ‘make install-data’. *Note The Two Parts of Install::, for more
  686. details.
  687. Here is how we could revisit our two-host installation example,
  688. assuming that (1) we want to install the package directly in ‘/usr’, and
  689. (2) the directory ‘/usr/share’ is shared by the two hosts.
  690. On the first host we would run
  691. [HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh
  692. [HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure --prefix /usr
  693. ...
  694. [HOST1] /tmp/amh % make && sudo make install
  695. ...
  696. On the second host, however, we need only install the
  697. architecture-specific files.
  698. [HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh
  699. [HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure --prefix /usr
  700. ...
  701. [HOST2] /tmp/amh % make && sudo make install-exec
  702. ...
  703. In packages that have installation checks, it would make sense to run
  704. ‘make installcheck’ (*note Basic Installation::) to verify that the
  705. package works correctly despite the apparent partial installation.
  706. 
  707. File: automake.info, Node: Cross-Compilation, Next: Renaming, Prev: Two-Part Install, Up: Use Cases
  708. 2.2.8 Cross-Compilation
  709. -----------------------
  710. To “cross-compile” is to build on one platform a binary that will run on
  711. another platform. When speaking of cross-compilation, it is important
  712. to distinguish between the “build platform” on which the compilation is
  713. performed, and the “host platform” on which the resulting executable is
  714. expected to run. The following ‘configure’ options are used to specify
  715. each of them:
  716. ‘--build=BUILD’
  717. The system on which the package is built.
  718. ‘--host=HOST’
  719. The system where built programs and libraries will run.
  720. When the ‘--host’ is used, ‘configure’ will search for the
  721. cross-compiling suite for this platform. Cross-compilation tools
  722. commonly have their target architecture as prefix of their name. For
  723. instance my cross-compiler for MinGW32 has its binaries called
  724. ‘i586-mingw32msvc-gcc’, ‘i586-mingw32msvc-ld’, ‘i586-mingw32msvc-as’,
  725. etc.
  726. Here is how we could build ‘amhello-1.0’ for ‘i586-mingw32msvc’ on a
  727. GNU/Linux PC.
  728. ~/amhello-1.0 % ./configure --build i686-pc-linux-gnu --host i586-mingw32msvc
  729. checking for a BSD-compatible install... /usr/bin/install -c
  730. checking whether build environment is sane... yes
  731. checking for gawk... gawk
  732. checking whether make sets $(MAKE)... yes
  733. checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
  734. checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
  735. checking for C compiler default output file name... a.exe
  736. checking whether the C compiler works... yes
  737. checking whether we are cross compiling... yes
  738. checking for suffix of executables... .exe
  739. checking for suffix of object files... o
  740. checking whether we are using the GNU C compiler... yes
  741. checking whether i586-mingw32msvc-gcc accepts -g... yes
  742. checking for i586-mingw32msvc-gcc option to accept ANSI C...
  743. ...
  744. ~/amhello-1.0 % make
  745. ...
  746. ~/amhello-1.0 % cd src; file hello.exe
  747. hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
  748. The ‘--host’ and ‘--build’ options are usually all we need for
  749. cross-compiling. The only exception is if the package being built is
  750. itself a cross-compiler: we need a third option to specify its target
  751. architecture.
  752. ‘--target=TARGET’
  753. When building compiler tools: the system for which the tools will
  754. create output.
  755. For instance when installing GCC, the GNU Compiler Collection, we can
  756. use ‘--target=TARGET’ to specify that we want to build GCC as a
  757. cross-compiler for TARGET. Mixing ‘--build’ and ‘--target’, we can
  758. actually cross-compile a cross-compiler; such a three-way
  759. cross-compilation is known as a “Canadian cross”.
  760. *Note Specifying the System Type: (autoconf)Specifying Names, for
  761. more information about these ‘configure’ options.
  762. 
  763. File: automake.info, Node: Renaming, Next: DESTDIR, Prev: Cross-Compilation, Up: Use Cases
  764. 2.2.9 Renaming Programs at Install Time
  765. ---------------------------------------
  766. The GNU Build System provides means to automatically rename executables
  767. and manpages before they are installed (*note Man Pages::). This is
  768. especially convenient when installing a GNU package on a system that
  769. already has a proprietary implementation you do not want to overwrite.
  770. For instance, you may want to install GNU ‘tar’ as ‘gtar’ so you can
  771. distinguish it from your vendor’s ‘tar’.
  772. This can be done using one of these three ‘configure’ options.
  773. ‘--program-prefix=PREFIX’
  774. Prepend PREFIX to installed program names.
  775. ‘--program-suffix=SUFFIX’
  776. Append SUFFIX to installed program names.
  777. ‘--program-transform-name=PROGRAM’
  778. Run ‘sed PROGRAM’ on installed program names.
  779. The following commands would install ‘hello’ as
  780. ‘/usr/local/bin/test-hello’, for instance.
  781. ~/amhello-1.0 % ./configure --program-prefix test-
  782. ...
  783. ~/amhello-1.0 % make
  784. ...
  785. ~/amhello-1.0 % sudo make install
  786. ...
  787. 
  788. File: automake.info, Node: DESTDIR, Next: Preparing Distributions, Prev: Renaming, Up: Use Cases
  789. 2.2.10 Building Binary Packages Using DESTDIR
  790. ---------------------------------------------
  791. The GNU Build System’s ‘make install’ and ‘make uninstall’ interface
  792. does not exactly fit the needs of a system administrator who has to
  793. deploy and upgrade packages on lots of hosts. In other words, the GNU
  794. Build System does not replace a package manager.
  795. Such package managers usually need to know which files have been
  796. installed by a package, so a mere ‘make install’ is inappropriate.
  797. The ‘DESTDIR’ variable can be used to perform a staged installation.
  798. The package should be configured as if it was going to be installed in
  799. its final location (e.g., ‘--prefix /usr’), but when running ‘make
  800. install’, the ‘DESTDIR’ should be set to the absolute name of a
  801. directory into which the installation will be diverted. From this
  802. directory it is easy to review which files are being installed where,
  803. and finally copy them to their final location by some means.
  804. For instance here is how we could create a binary package containing
  805. a snapshot of all the files to be installed.
  806. ~/amhello-1.0 % ./configure --prefix /usr
  807. ...
  808. ~/amhello-1.0 % make
  809. ...
  810. ~/amhello-1.0 % make DESTDIR=$HOME/inst install
  811. ...
  812. ~/amhello-1.0 % cd ~/inst
  813. ~/inst % find . -type f -print > ../files.lst
  814. ~/inst % tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`
  815. ./usr/bin/hello
  816. ./usr/share/doc/amhello/README
  817. After this example, ‘amhello-1.0-i686.tar.gz’ is ready to be
  818. uncompressed in ‘/’ on many hosts. (Using ‘`cat ../files.lst`’ instead
  819. of ‘.’ as argument for ‘tar’ avoids entries for each subdirectory in the
  820. archive: we would not like ‘tar’ to restore the modification time of
  821. ‘/’, ‘/usr/’, etc.)
  822. Note that when building packages for several architectures, it might
  823. be convenient to use ‘make install-data’ and ‘make install-exec’ (*note
  824. Two-Part Install::) to gather architecture-independent files in a single
  825. package.
  826. *Note Install::, for more information.
  827. 
  828. File: automake.info, Node: Preparing Distributions, Next: Dependency Tracking, Prev: DESTDIR, Up: Use Cases
  829. 2.2.11 Preparing Distributions
  830. ------------------------------
  831. We have already mentioned ‘make dist’. This target collects all your
  832. source files and the necessary parts of the build system to create a
  833. tarball named ‘PACKAGE-VERSION.tar.gz’.
  834. Another, more useful command is ‘make distcheck’. The ‘distcheck’
  835. target constructs ‘PACKAGE-VERSION.tar.gz’ just as well as ‘dist’, but
  836. it additionally ensures most of the use cases presented so far work:
  837. • It attempts a full compilation of the package (*note Basic
  838. Installation::), unpacking the newly constructed tarball, running
  839. ‘make’, ‘make check’, ‘make install’, as well as ‘make
  840. installcheck’, and even ‘make dist’,
  841. • it tests VPATH builds with read-only source tree (*note VPATH
  842. Builds::),
  843. • it makes sure ‘make clean’, ‘make distclean’, and ‘make uninstall’
  844. do not omit any file (*note Standard Targets::),
  845. • and it checks that ‘DESTDIR’ installations work (*note DESTDIR::).
  846. All of these actions are performed in a temporary directory, so that
  847. no root privileges are required. Please note that the exact location
  848. and the exact structure of such a subdirectory (where the extracted
  849. sources are placed, how the temporary build and install directories are
  850. named and how deeply they are nested, etc.) is to be considered an
  851. implementation detail, which can change at any time; so do not rely on
  852. it.
  853. Releasing a package that fails ‘make distcheck’ means that one of the
  854. scenarios we presented will not work and some users will be
  855. disappointed. Therefore it is a good practice to release a package only
  856. after a successful ‘make distcheck’. This of course does not imply that
  857. the package will be flawless, but at least it will prevent some of the
  858. embarrassing errors you may find in packages released by people who have
  859. never heard about ‘distcheck’ (like ‘DESTDIR’ not working because of a
  860. typo, or a distributed file being erased by ‘make clean’, or even
  861. ‘VPATH’ builds not working).
  862. *Note Creating amhello::, to recreate ‘amhello-1.0.tar.gz’ using
  863. ‘make distcheck’. *Note Checking the Distribution::, for more
  864. information about ‘distcheck’.
  865. 
  866. File: automake.info, Node: Dependency Tracking, Next: Nested Packages, Prev: Preparing Distributions, Up: Use Cases
  867. 2.2.12 Automatic Dependency Tracking
  868. ------------------------------------
  869. Dependency tracking is performed as a side-effect of compilation. Each
  870. time the build system compiles a source file, it computes its list of
  871. dependencies (in C these are the header files included by the source
  872. being compiled). Later, any time ‘make’ is run and a dependency appears
  873. to have changed, the dependent files will be rebuilt.
  874. Automake generates code for automatic dependency tracking by default,
  875. unless the developer chooses to override it; for more information, *note
  876. Dependencies::.
  877. When ‘configure’ is executed, you can see it probing each compiler
  878. for the dependency mechanism it supports (several mechanisms can be
  879. used):
  880. ~/amhello-1.0 % ./configure --prefix /usr
  881. ...
  882. checking dependency style of gcc... gcc3
  883. ...
  884. Because dependencies are only computed as a side-effect of the
  885. compilation, no dependency information exists the first time a package
  886. is built. This is OK because all the files need to be built anyway:
  887. ‘make’ does not have to decide which files need to be rebuilt. In fact,
  888. dependency tracking is completely useless for one-time builds and there
  889. is a ‘configure’ option to disable this:
  890. ‘--disable-dependency-tracking’
  891. Speed up one-time builds.
  892. Some compilers do not offer any practical way to derive the list of
  893. dependencies as a side-effect of the compilation, requiring a separate
  894. run (maybe of another tool) to compute these dependencies. The
  895. performance penalty implied by these methods is important enough to
  896. disable them by default. The option ‘--enable-dependency-tracking’ must
  897. be passed to ‘configure’ to activate them.
  898. ‘--enable-dependency-tracking’
  899. Do not reject slow dependency extractors.
  900. *Note Dependency Tracking Evolution: (automake-history)Dependency
  901. Tracking Evolution, for some discussion about the different dependency
  902. tracking schemes used by Automake over the years.
  903. 
  904. File: automake.info, Node: Nested Packages, Prev: Dependency Tracking, Up: Use Cases
  905. 2.2.13 Nested Packages
  906. ----------------------
  907. Although nesting packages isn’t something we would recommend to someone
  908. who is discovering the Autotools, it is a nice feature worthy of mention
  909. in this small advertising tour.
  910. Autoconfiscated packages (that means packages whose build system have
  911. been created by Autoconf and friends) can be nested to arbitrary depth.
  912. A typical setup is that package A will distribute one of the
  913. libraries it needs in a subdirectory. This library B is a complete
  914. package with its own GNU Build System. The ‘configure’ script of A will
  915. run the ‘configure’ script of B as part of its execution, building and
  916. installing A will also build and install B. Generating a distribution
  917. for A will also include B.
  918. It is possible to gather several packages like this. GCC is a heavy
  919. user of this feature. This gives installers a single package to
  920. configure, build and install, while it allows developers to work on
  921. subpackages independently.
  922. When configuring nested packages, the ‘configure’ options given to
  923. the top-level ‘configure’ are passed recursively to nested ‘configure’s.
  924. A package that does not understand an option will ignore it, assuming it
  925. is meaningful to some other package.
  926. The command ‘configure --help=recursive’ can be used to display the
  927. options supported by all the included packages.
  928. *Note Subpackages::, for an example setup.
  929. 
  930. File: automake.info, Node: Why Autotools, Next: Hello World, Prev: Use Cases, Up: Autotools Introduction
  931. 2.3 How Autotools Help
  932. ======================
  933. There are several reasons why you may not want to implement the GNU
  934. Build System yourself (read: write a ‘configure’ script and ‘Makefile’s
  935. yourself).
  936. • As we have seen, the GNU Build System has a lot of features (*note
  937. Use Cases::). Some users may expect features you have not
  938. implemented because you did not need them.
  939. • Implementing these features portably is difficult and exhausting.
  940. Think of writing portable shell scripts, and portable ‘Makefile’s,
  941. for systems you may not have handy. *Note Portable Shell
  942. Programming: (autoconf)Portable Shell, to convince yourself.
  943. • You will have to upgrade your setup to follow changes to the GNU
  944. Coding Standards.
  945. The GNU Autotools take all this burden off your back and provide:
  946. • Tools to create a portable, complete, and self-contained GNU Build
  947. System, from simple instructions. _Self-contained_ meaning the
  948. resulting build system does not require the GNU Autotools.
  949. • A central place where fixes and improvements are made: a bug-fix
  950. for a portability issue will benefit every package.
  951. Yet there also exist reasons why you may want NOT to use the
  952. Autotools... For instance you may be already using (or used to) another
  953. incompatible build system. Autotools will only be useful if you do
  954. accept the concepts of the GNU Build System. People who have their own
  955. idea of how a build system should work will feel frustrated by the
  956. Autotools.
  957. 
  958. File: automake.info, Node: Hello World, Prev: Why Autotools, Up: Autotools Introduction
  959. 2.4 A Small Hello World
  960. =======================
  961. In this section we recreate the ‘amhello-1.0’ package from scratch. The
  962. first subsection shows how to call the Autotools to instantiate the GNU
  963. Build System, while the second explains the meaning of the
  964. ‘configure.ac’ and ‘Makefile.am’ files read by the Autotools.
  965. * Menu:
  966. * Creating amhello:: Create ‘amhello-1.0.tar.gz’ from scratch
  967. * amhello's configure.ac Setup Explained::
  968. * amhello's Makefile.am Setup Explained::
  969. 
  970. File: automake.info, Node: Creating amhello, Next: amhello's configure.ac Setup Explained, Up: Hello World
  971. 2.4.1 Creating ‘amhello-1.0.tar.gz’
  972. -----------------------------------
  973. Here is how we can recreate ‘amhello-1.0.tar.gz’ from scratch. The
  974. package is simple enough so that we will only need to write 5 files.
  975. (You may copy them from the final ‘amhello-1.0.tar.gz’ that is
  976. distributed with Automake if you do not want to write them.)
  977. Create the following files in an empty directory.
  978. • ‘src/main.c’ is the source file for the ‘hello’ program. We store
  979. it in the ‘src/’ subdirectory, because later, when the package
  980. evolves, it will ease the addition of a ‘man/’ directory for man
  981. pages, a ‘data/’ directory for data files, etc.
  982. ~/amhello % cat src/main.c
  983. #include <config.h>
  984. #include <stdio.h>
  985. int
  986. main (void)
  987. {
  988. puts ("Hello World!");
  989. puts ("This is " PACKAGE_STRING ".");
  990. return 0;
  991. }
  992. • ‘README’ contains some very limited documentation for our little
  993. package.
  994. ~/amhello % cat README
  995. This is a demonstration package for GNU Automake.
  996. Type 'info Automake' to read the Automake manual.
  997. • ‘Makefile.am’ and ‘src/Makefile.am’ contain Automake instructions
  998. for these two directories.
  999. ~/amhello % cat src/Makefile.am
  1000. bin_PROGRAMS = hello
  1001. hello_SOURCES = main.c
  1002. ~/amhello % cat Makefile.am
  1003. SUBDIRS = src
  1004. dist_doc_DATA = README
  1005. • Finally, ‘configure.ac’ contains Autoconf instructions to create
  1006. the ‘configure’ script.
  1007. ~/amhello % cat configure.ac
  1008. AC_INIT([amhello], [1.0], [bug-automake@gnu.org])
  1009. AM_INIT_AUTOMAKE([-Wall -Werror foreign])
  1010. AC_PROG_CC
  1011. AC_CONFIG_HEADERS([config.h])
  1012. AC_CONFIG_FILES([
  1013. Makefile
  1014. src/Makefile
  1015. ])
  1016. AC_OUTPUT
  1017. Once you have these five files, it is time to run the Autotools to
  1018. instantiate the build system. Do this using the ‘autoreconf’ command as
  1019. follows:
  1020. ~/amhello % autoreconf --install
  1021. configure.ac: installing './install-sh'
  1022. configure.ac: installing './missing'
  1023. configure.ac: installing './compile'
  1024. src/Makefile.am: installing './depcomp'
  1025. At this point the build system is complete.
  1026. In addition to the three scripts mentioned in its output, you can see
  1027. that ‘autoreconf’ created four other files: ‘configure’, ‘config.h.in’,
  1028. ‘Makefile.in’, and ‘src/Makefile.in’. The latter three files are
  1029. templates that will be adapted to the system by ‘configure’ under the
  1030. names ‘config.h’, ‘Makefile’, and ‘src/Makefile’. Let’s do this:
  1031. ~/amhello % ./configure
  1032. checking for a BSD-compatible install... /usr/bin/install -c
  1033. checking whether build environment is sane... yes
  1034. checking for gawk... no
  1035. checking for mawk... mawk
  1036. checking whether make sets $(MAKE)... yes
  1037. checking for gcc... gcc
  1038. checking for C compiler default output file name... a.out
  1039. checking whether the C compiler works... yes
  1040. checking whether we are cross compiling... no
  1041. checking for suffix of executables...
  1042. checking for suffix of object files... o
  1043. checking whether we are using the GNU C compiler... yes
  1044. checking whether gcc accepts -g... yes
  1045. checking for gcc option to accept ISO C89... none needed
  1046. checking for style of include used by make... GNU
  1047. checking dependency style of gcc... gcc3
  1048. configure: creating ./config.status
  1049. config.status: creating Makefile
  1050. config.status: creating src/Makefile
  1051. config.status: creating config.h
  1052. config.status: executing depfiles commands
  1053. You can see ‘Makefile’, ‘src/Makefile’, and ‘config.h’ being created
  1054. at the end after ‘configure’ has probed the system. It is now possible
  1055. to run all the targets we wish (*note Standard Targets::). For
  1056. instance:
  1057. ~/amhello % make
  1058. ...
  1059. ~/amhello % src/hello
  1060. Hello World!
  1061. This is amhello 1.0.
  1062. ~/amhello % make distcheck
  1063. ...
  1064. =============================================
  1065. amhello-1.0 archives ready for distribution:
  1066. amhello-1.0.tar.gz
  1067. =============================================
  1068. Note that running ‘autoreconf’ is only needed initially when the GNU
  1069. Build System does not exist. When you later change some instructions in
  1070. a ‘Makefile.am’ or ‘configure.ac’, the relevant part of the build system
  1071. will be regenerated automatically when you execute ‘make’.
  1072. ‘autoreconf’ is a script that calls ‘autoconf’, ‘automake’, and a
  1073. bunch of other commands in the right order. If you are beginning with
  1074. these tools, it is not important to figure out in which order all of
  1075. these tools should be invoked and why. However, because Autoconf and
  1076. Automake have separate manuals, the important point to understand is
  1077. that ‘autoconf’ is in charge of creating ‘configure’ from
  1078. ‘configure.ac’, while ‘automake’ is in charge of creating ‘Makefile.in’s
  1079. from ‘Makefile.am’s and ‘configure.ac’. This should at least direct you
  1080. to the right manual when seeking answers.
  1081. 
  1082. File: automake.info, Node: amhello's configure.ac Setup Explained, Next: amhello's Makefile.am Setup Explained, Prev: Creating amhello, Up: Hello World
  1083. 2.4.2 ‘amhello’’s ‘configure.ac’ Setup Explained
  1084. ------------------------------------------------
  1085. Let us begin with the contents of ‘configure.ac’.
  1086. AC_INIT([amhello], [1.0], [bug-automake@gnu.org])
  1087. AM_INIT_AUTOMAKE([-Wall -Werror foreign])
  1088. AC_PROG_CC
  1089. AC_CONFIG_HEADERS([config.h])
  1090. AC_CONFIG_FILES([
  1091. Makefile
  1092. src/Makefile
  1093. ])
  1094. AC_OUTPUT
  1095. This file is read by both ‘autoconf’ (to create ‘configure’) and
  1096. ‘automake’ (to create the various ‘Makefile.in’s). It contains a series
  1097. of M4 macros that will be expanded as shell code to finally form the
  1098. ‘configure’ script. We will not elaborate on the syntax of this file,
  1099. because the Autoconf manual has a whole section about it (*note Writing
  1100. ‘configure.ac’: (autoconf)Writing Autoconf Input.).
  1101. The macros prefixed with ‘AC_’ are Autoconf macros, documented in the
  1102. Autoconf manual (*note Autoconf Macro Index: (autoconf)Autoconf Macro
  1103. Index.). The macros that start with ‘AM_’ are Automake macros,
  1104. documented later in this manual (*note Macro Index::).
  1105. The first two lines of ‘configure.ac’ initialize Autoconf and
  1106. Automake. ‘AC_INIT’ takes in as parameters the name of the package, its
  1107. version number, and a contact address for bug-reports about the package
  1108. (this address is output at the end of ‘./configure --help’, for
  1109. instance). When adapting this setup to your own package, by all means
  1110. please do not blindly copy Automake’s address: use the mailing list of
  1111. your package, or your own mail address.
  1112. The argument to ‘AM_INIT_AUTOMAKE’ is a list of options for
  1113. ‘automake’ (*note Options::). ‘-Wall’ and ‘-Werror’ ask ‘automake’ to
  1114. turn on all warnings and report them as errors. We are speaking of
  1115. *Automake* warnings here, such as dubious instructions in ‘Makefile.am’.
  1116. This has absolutely nothing to do with how the compiler will be called,
  1117. even though it may support options with similar names. Using ‘-Wall
  1118. -Werror’ is a safe setting when starting to work on a package: you do
  1119. not want to miss any issues. Later you may decide to relax things a
  1120. bit. The ‘foreign’ option tells Automake that this package will not
  1121. follow the GNU Standards. GNU packages should always distribute
  1122. additional files such as ‘ChangeLog’, ‘AUTHORS’, etc. We do not want
  1123. ‘automake’ to complain about these missing files in our small example.
  1124. The ‘AC_PROG_CC’ line causes the ‘configure’ script to search for a C
  1125. compiler and define the variable ‘CC’ with its name. The
  1126. ‘src/Makefile.in’ file generated by Automake uses the variable ‘CC’ to
  1127. build ‘hello’, so when ‘configure’ creates ‘src/Makefile’ from
  1128. ‘src/Makefile.in’, it will define ‘CC’ with the value it has found. If
  1129. Automake is asked to create a ‘Makefile.in’ that uses ‘CC’ but
  1130. ‘configure.ac’ does not define it, it will suggest you add a call to
  1131. ‘AC_PROG_CC’.
  1132. The ‘AC_CONFIG_HEADERS([config.h])’ invocation causes the ‘configure’
  1133. script to create a ‘config.h’ file gathering ‘#define’s defined by other
  1134. macros in ‘configure.ac’. In our case, the ‘AC_INIT’ macro already
  1135. defined a few of them. Here is an excerpt of ‘config.h’ after
  1136. ‘configure’ has run:
  1137. ...
  1138. /* Define to the address where bug reports for this package should be sent. */
  1139. #define PACKAGE_BUGREPORT "bug-automake@gnu.org"
  1140. /* Define to the full name and version of this package. */
  1141. #define PACKAGE_STRING "amhello 1.0"
  1142. ...
  1143. As you probably noticed, ‘src/main.c’ includes ‘config.h’ so it can
  1144. use ‘PACKAGE_STRING’. In a real-world project, ‘config.h’ can grow
  1145. really big, with one ‘#define’ per feature probed on the system.
  1146. The ‘AC_CONFIG_FILES’ macro declares the list of files that
  1147. ‘configure’ should create from their ‘*.in’ templates. Automake also
  1148. scans this list to find the ‘Makefile.am’ files it must process. (This
  1149. is important to remember: when adding a new directory to your project,
  1150. you should add its ‘Makefile’ to this list, otherwise Automake will
  1151. never process the new ‘Makefile.am’ you wrote in that directory.)
  1152. Finally, the ‘AC_OUTPUT’ line is a closing command that actually
  1153. produces the part of the script in charge of creating the files
  1154. registered with ‘AC_CONFIG_HEADERS’ and ‘AC_CONFIG_FILES’.
  1155. When starting a new project, we suggest you start with such a simple
  1156. ‘configure.ac’, and gradually add the other tests it requires. The
  1157. command ‘autoscan’ can also suggest a few of the tests your package may
  1158. need (*note Using ‘autoscan’ to Create ‘configure.ac’:
  1159. (autoconf)autoscan Invocation.).
  1160. 
  1161. File: automake.info, Node: amhello's Makefile.am Setup Explained, Prev: amhello's configure.ac Setup Explained, Up: Hello World
  1162. 2.4.3 ‘amhello’’s ‘Makefile.am’ Setup Explained
  1163. -----------------------------------------------
  1164. We now turn to ‘src/Makefile.am’. This file contains Automake
  1165. instructions to build and install ‘hello’.
  1166. bin_PROGRAMS = hello
  1167. hello_SOURCES = main.c
  1168. A ‘Makefile.am’ has the same syntax as an ordinary ‘Makefile’. When
  1169. ‘automake’ processes a ‘Makefile.am’ it copies the entire file into the
  1170. output ‘Makefile.in’ (that will be later turned into ‘Makefile’ by
  1171. ‘configure’) but will react to certain variable definitions by
  1172. generating some build rules and other variables. Often ‘Makefile.am’s
  1173. contain only a list of variable definitions as above, but they can also
  1174. contain other variable and rule definitions that ‘automake’ will pass
  1175. along without interpretation.
  1176. Variables that end with ‘_PROGRAMS’ are special variables that list
  1177. programs that the resulting ‘Makefile’ should build. In Automake speak,
  1178. this ‘_PROGRAMS’ suffix is called a “primary”; Automake recognizes other
  1179. primaries such as ‘_SCRIPTS’, ‘_DATA’, ‘_LIBRARIES’, etc. corresponding
  1180. to different types of files.
  1181. The ‘bin’ part of the ‘bin_PROGRAMS’ tells ‘automake’ that the
  1182. resulting programs should be installed in BINDIR. Recall that the GNU
  1183. Build System uses a set of variables to denote destination directories
  1184. and allow users to customize these locations (*note Standard Directory
  1185. Variables::). Any such directory variable can be put in front of a
  1186. primary (omitting the ‘dir’ suffix) to tell ‘automake’ where to install
  1187. the listed files.
  1188. Programs need to be built from source files, so for each program
  1189. ‘PROG’ listed in a ‘_PROGRAMS’ variable, ‘automake’ will look for
  1190. another variable named ‘PROG_SOURCES’ listing its source files. There
  1191. may be more than one source file: they will all be compiled and linked
  1192. together.
  1193. Automake also knows that source files need to be distributed when
  1194. creating a tarball (unlike built programs). So a side-effect of this
  1195. ‘hello_SOURCES’ declaration is that ‘main.c’ will be part of the tarball
  1196. created by ‘make dist’.
  1197. Finally here are some explanations regarding the top-level
  1198. ‘Makefile.am’.
  1199. SUBDIRS = src
  1200. dist_doc_DATA = README
  1201. ‘SUBDIRS’ is a special variable listing all directories that ‘make’
  1202. should recurse into before processing the current directory. So this
  1203. line is responsible for ‘make’ building ‘src/hello’ even though we run
  1204. it from the top-level. This line also causes ‘make install’ to install
  1205. ‘src/hello’ before installing ‘README’ (not that this order matters).
  1206. The line ‘dist_doc_DATA = README’ causes ‘README’ to be distributed
  1207. and installed in DOCDIR. Files listed with the ‘_DATA’ primary are not
  1208. automatically part of the tarball built with ‘make dist’, so we add the
  1209. ‘dist_’ prefix so they get distributed. However, for ‘README’ it would
  1210. not have been necessary: ‘automake’ automatically distributes any
  1211. ‘README’ file it encounters (the list of other files automatically
  1212. distributed is presented by ‘automake --help’). The only important
  1213. effect of this second line is therefore to install ‘README’ during ‘make
  1214. install’.
  1215. One thing not covered in this example is accessing the installation
  1216. directory values (*note Standard Directory Variables::) from your
  1217. program code, that is, converting them into defined macros. For this,
  1218. *note (autoconf)Defining Directories::.
  1219. 
  1220. File: automake.info, Node: Generalities, Next: Examples, Prev: Autotools Introduction, Up: Top
  1221. 3 General ideas
  1222. ***************
  1223. The following sections cover a few basic ideas that will help you
  1224. understand how Automake works.
  1225. * Menu:
  1226. * General Operation:: General operation of Automake
  1227. * Strictness:: Standards conformance checking
  1228. * Uniform:: The Uniform Naming Scheme
  1229. * Length Limitations:: Staying below the command line length limit
  1230. * Canonicalization:: How derived variables are named
  1231. * User Variables:: Variables reserved for the user
  1232. * Auxiliary Programs:: Programs automake might require
  1233. 
  1234. File: automake.info, Node: General Operation, Next: Strictness, Up: Generalities
  1235. 3.1 General Operation
  1236. =====================
  1237. Automake works by reading a ‘Makefile.am’ and generating a
  1238. ‘Makefile.in’. Certain variables and rules defined in the ‘Makefile.am’
  1239. instruct Automake to generate more specialized code; for instance, a
  1240. ‘bin_PROGRAMS’ variable definition will cause rules for compiling and
  1241. linking programs to be generated.
  1242. The variable definitions and rules in the ‘Makefile.am’ are copied
  1243. mostly verbatim into the generated file, with all variable definitions
  1244. preceding all rules. This allows you to add almost arbitrary code into
  1245. the generated ‘Makefile.in’. For instance, the Automake distribution
  1246. includes a non-standard rule for the ‘git-dist’ target, which the
  1247. Automake maintainer uses to make distributions from the source control
  1248. system.
  1249. Note that most GNU make extensions are not recognized by Automake.
  1250. Using such extensions in a ‘Makefile.am’ will lead to errors or
  1251. confusing behavior.
  1252. A special exception is that the GNU make append operator, ‘+=’, is
  1253. supported. This operator appends its right hand argument to the
  1254. variable specified on the left. Automake will translate the operator
  1255. into an ordinary ‘=’ operator; ‘+=’ will thus work with any make
  1256. program.
  1257. Automake tries to keep comments grouped with any adjoining rules or
  1258. variable definitions.
  1259. Generally, Automake is not particularly smart in the parsing of
  1260. unusual Makefile constructs, so you’re advised to avoid fancy constructs
  1261. or “creative” use of whitespace. For example, <TAB> characters cannot
  1262. be used between a target name and the following “‘:’” character, and
  1263. variable assignments shouldn’t be indented with <TAB> characters. Also,
  1264. using more complex macro in target names can cause trouble:
  1265. % cat Makefile.am
  1266. $(FOO:=x): bar
  1267. % automake
  1268. Makefile.am:1: bad characters in variable name '$(FOO'
  1269. Makefile.am:1: ':='-style assignments are not portable
  1270. A rule defined in ‘Makefile.am’ generally overrides any such rule of
  1271. a similar name that would be automatically generated by ‘automake’.
  1272. Although this is a supported feature, it is generally best to avoid
  1273. making use of it, as sometimes the generated rules are very particular.
  1274. Similarly, a variable defined in ‘Makefile.am’ or ‘AC_SUBST’ed from
  1275. ‘configure.ac’ will override any definition of the variable that
  1276. ‘automake’ would ordinarily create. This feature is more often useful
  1277. than the ability to override a rule. Be warned that many of the
  1278. variables generated by ‘automake’ are considered to be for internal use
  1279. only, and their names might change in future releases.
  1280. When examining a variable definition, Automake will recursively
  1281. examine variables referenced in the definition. For example, if
  1282. Automake is looking at the content of ‘foo_SOURCES’ in this snippet
  1283. xs = a.c b.c
  1284. foo_SOURCES = c.c $(xs)
  1285. it would use the files ‘a.c’, ‘b.c’, and ‘c.c’ as the contents of
  1286. ‘foo_SOURCES’.
  1287. Automake also allows a form of comment that is _not_ copied into the
  1288. output; all lines beginning with ‘##’ (leading spaces allowed) are
  1289. completely ignored by Automake.
  1290. It is customary to make the first line of ‘Makefile.am’ read:
  1291. ## Process this file with automake to produce Makefile.in
  1292. 
  1293. File: automake.info, Node: Strictness, Next: Uniform, Prev: General Operation, Up: Generalities
  1294. 3.2 Strictness
  1295. ==============
  1296. While Automake is intended to be used by maintainers of GNU packages, it
  1297. does make some effort to accommodate those who wish to use it, but do
  1298. not want to use all the GNU conventions.
  1299. To this end, Automake supports three levels of “strictness”—the
  1300. strictness indicating how stringently Automake should check standards
  1301. conformance.
  1302. The valid strictness levels are:
  1303. ‘foreign’
  1304. Automake will check for only those things that are absolutely
  1305. required for proper operations. For instance, whereas GNU
  1306. standards dictate the existence of a ‘NEWS’ file, it will not be
  1307. required in this mode. This strictness will also turn off some
  1308. warnings by default (among them, portability warnings). The name
  1309. comes from the fact that Automake is intended to be used for GNU
  1310. programs; these relaxed rules are not the standard mode of
  1311. operation.
  1312. ‘gnu’
  1313. Automake will check—as much as possible—for compliance to the GNU
  1314. standards for packages. This is the default.
  1315. ‘gnits’
  1316. Automake will check for compliance to the as-yet-unwritten “Gnits
  1317. standards”. These are based on the GNU standards, but are even
  1318. more detailed. Unless you are a Gnits standards contributor, it is
  1319. recommended that you avoid this option until such time as the Gnits
  1320. standard is actually published (which may never happen).
  1321. *Note Gnits::, for more information on the precise implications of
  1322. the strictness level.
  1323. 
  1324. File: automake.info, Node: Uniform, Next: Length Limitations, Prev: Strictness, Up: Generalities
  1325. 3.3 The Uniform Naming Scheme
  1326. =============================
  1327. Automake variables generally follow a “uniform naming scheme” that makes
  1328. it easy to decide how programs (and other derived objects) are built,
  1329. and how they are installed. This scheme also supports ‘configure’ time
  1330. determination of what should be built.
  1331. At ‘make’ time, certain variables are used to determine which objects
  1332. are to be built. The variable names are made of several pieces that are
  1333. concatenated together.
  1334. The piece that tells ‘automake’ what is being built is commonly
  1335. called the “primary”. For instance, the primary ‘PROGRAMS’ holds a list
  1336. of programs that are to be compiled and linked.
  1337. A different set of names is used to decide where the built objects
  1338. should be installed. These names are prefixes to the primary, and they
  1339. indicate which standard directory should be used as the installation
  1340. directory. The standard directory names are given in the GNU standards
  1341. (*note (standards)Directory Variables::). Automake extends this list
  1342. with ‘pkgdatadir’, ‘pkgincludedir’, ‘pkglibdir’, and ‘pkglibexecdir’;
  1343. these are the same as the non-‘pkg’ versions, but with ‘$(PACKAGE)’
  1344. appended. For instance, ‘pkglibdir’ is defined as
  1345. ‘$(libdir)/$(PACKAGE)’.
  1346. For each primary, there is one additional variable named by
  1347. prepending ‘EXTRA_’ to the primary name. This variable is used to list
  1348. objects that may or may not be built, depending on what ‘configure’
  1349. decides. This variable is required because Automake must statically
  1350. know the entire list of objects that may be built in order to generate a
  1351. ‘Makefile.in’ that will work in all cases.
  1352. For instance, ‘cpio’ decides at configure time which programs should
  1353. be built. Some of the programs are installed in ‘bindir’, and some are
  1354. installed in ‘sbindir’:
  1355. EXTRA_PROGRAMS = mt rmt
  1356. bin_PROGRAMS = cpio pax
  1357. sbin_PROGRAMS = $(MORE_PROGRAMS)
  1358. Defining a primary without a prefix as a variable, e.g., ‘PROGRAMS’,
  1359. is an error.
  1360. Note that the common ‘dir’ suffix is left off when constructing the
  1361. variable names; thus one writes ‘bin_PROGRAMS’ and not
  1362. ‘bindir_PROGRAMS’.
  1363. Not every sort of object can be installed in every directory.
  1364. Automake will flag those attempts it finds in error (but see below how
  1365. to override the check if you really need to). Automake will also
  1366. diagnose obvious misspellings in directory names.
  1367. Sometimes the standard directories—even as augmented by Automake—are
  1368. not enough. In particular it is sometimes useful, for clarity, to
  1369. install objects in a subdirectory of some predefined directory. To this
  1370. end, Automake allows you to extend the list of possible installation
  1371. directories. A given prefix (e.g., ‘zar’) is valid if a variable of the
  1372. same name with ‘dir’ appended is defined (e.g., ‘zardir’).
  1373. For instance, the following snippet will install ‘file.xml’ into
  1374. ‘$(datadir)/xml’.
  1375. xmldir = $(datadir)/xml
  1376. xml_DATA = file.xml
  1377. This feature can also be used to override the sanity checks Automake
  1378. performs to diagnose suspicious directory/primary couples (in the
  1379. unlikely case these checks are undesirable, and you really know what
  1380. you’re doing). For example, Automake would error out on this input:
  1381. # Forbidden directory combinations, automake will error out on this.
  1382. pkglib_PROGRAMS = foo
  1383. doc_LIBRARIES = libquux.a
  1384. but it will succeed with this:
  1385. # Work around forbidden directory combinations. Do not use this
  1386. # without a very good reason!
  1387. my_execbindir = $(pkglibdir)
  1388. my_doclibdir = $(docdir)
  1389. my_execbin_PROGRAMS = foo
  1390. my_doclib_LIBRARIES = libquux.a
  1391. The ‘exec’ substring of the ‘my_execbindir’ variable lets the files
  1392. be installed at the right time (*note The Two Parts of Install::).
  1393. The special prefix ‘noinst_’ indicates that the objects in question
  1394. should be built but not installed at all. This is usually used for
  1395. objects required to build the rest of your package, for instance static
  1396. libraries (*note A Library::), or helper scripts.
  1397. The special prefix ‘check_’ indicates that the objects in question
  1398. should not be built until the ‘make check’ command is run. Those
  1399. objects are not installed either.
  1400. The current primary names are ‘PROGRAMS’, ‘LIBRARIES’, ‘LTLIBRARIES’,
  1401. ‘LISP’, ‘PYTHON’, ‘JAVA’, ‘SCRIPTS’, ‘DATA’, ‘HEADERS’, ‘MANS’, and
  1402. ‘TEXINFOS’.
  1403. Some primaries also allow additional prefixes that control other
  1404. aspects of ‘automake’’s behavior. The currently defined prefixes are
  1405. ‘dist_’, ‘nodist_’, ‘nobase_’, and ‘notrans_’. These prefixes are
  1406. explained later (*note Program and Library Variables::) (*note Man
  1407. Pages::).
  1408. 
  1409. File: automake.info, Node: Length Limitations, Next: Canonicalization, Prev: Uniform, Up: Generalities
  1410. 3.4 Staying below the command line length limit
  1411. ===============================================
  1412. Traditionally, most unix-like systems have a length limitation for the
  1413. command line arguments and environment contents when creating new
  1414. processes (see for example
  1415. <http://www.in-ulm.de/~mascheck/various/argmax/> for an overview on this
  1416. issue), which of course also applies to commands spawned by ‘make’.
  1417. POSIX requires this limit to be at least 4096 bytes, and most modern
  1418. systems have quite high limits (or are unlimited).
  1419. In order to create portable Makefiles that do not trip over these
  1420. limits, it is necessary to keep the length of file lists bounded.
  1421. Unfortunately, it is not possible to do so fully transparently within
  1422. Automake, so your help may be needed. Typically, you can split long
  1423. file lists manually and use different installation directory names for
  1424. each list. For example,
  1425. data_DATA = file1 ... fileN fileN+1 ... file2N
  1426. may also be written as
  1427. data_DATA = file1 ... fileN
  1428. data2dir = $(datadir)
  1429. data2_DATA = fileN+1 ... file2N
  1430. and will cause Automake to treat the two lists separately during ‘make
  1431. install’. See *note The Two Parts of Install:: for choosing directory
  1432. names that will keep the ordering of the two parts of installation Note
  1433. that ‘make dist’ may still only work on a host with a higher length
  1434. limit in this example.
  1435. Automake itself employs a couple of strategies to avoid long command
  1436. lines. For example, when ‘${srcdir}/’ is prepended to file names, as
  1437. can happen with above ‘$(data_DATA)’ lists, it limits the amount of
  1438. arguments passed to external commands.
  1439. Unfortunately, some system’s ‘make’ commands may prepend ‘VPATH’
  1440. prefixes like ‘${srcdir}/’ to file names from the source tree
  1441. automatically (*note Automatic Rule Rewriting: (autoconf)Automatic Rule
  1442. Rewriting.). In this case, the user may have to switch to use GNU Make,
  1443. or refrain from using VPATH builds, in order to stay below the length
  1444. limit.
  1445. For libraries and programs built from many sources, convenience
  1446. archives may be used as intermediates in order to limit the object list
  1447. length (*note Libtool Convenience Libraries::).
  1448. 
  1449. File: automake.info, Node: Canonicalization, Next: User Variables, Prev: Length Limitations, Up: Generalities
  1450. 3.5 How derived variables are named
  1451. ===================================
  1452. Sometimes a Makefile variable name is derived from some text the
  1453. maintainer supplies. For instance, a program name listed in ‘_PROGRAMS’
  1454. is rewritten into the name of a ‘_SOURCES’ variable. In cases like
  1455. this, Automake canonicalizes the text, so that program names and the
  1456. like do not have to follow Makefile variable naming rules. All
  1457. characters in the name except for letters, numbers, the strudel (@), and
  1458. the underscore are turned into underscores when making variable
  1459. references.
  1460. For example, if your program is named ‘sniff-glue’, the derived
  1461. variable name would be ‘sniff_glue_SOURCES’, not ‘sniff-glue_SOURCES’.
  1462. Similarly the sources for a library named ‘libmumble++.a’ should be
  1463. listed in the ‘libmumble___a_SOURCES’ variable.
  1464. The strudel is an addition, to make the use of Autoconf substitutions
  1465. in variable names less obfuscating.
  1466. 
  1467. File: automake.info, Node: User Variables, Next: Auxiliary Programs, Prev: Canonicalization, Up: Generalities
  1468. 3.6 Variables reserved for the user
  1469. ===================================
  1470. Some ‘Makefile’ variables are reserved by the GNU Coding Standards for
  1471. the use of the “user”—the person building the package. For instance,
  1472. ‘CFLAGS’ is one such variable.
  1473. Sometimes package developers are tempted to set user variables such
  1474. as ‘CFLAGS’ because it appears to make their job easier. However, the
  1475. package itself should never set a user variable, particularly not to
  1476. include switches that are required for proper compilation of the
  1477. package. Since these variables are documented as being for the package
  1478. builder, that person rightfully expects to be able to override any of
  1479. these variables at build time.
  1480. To get around this problem, Automake introduces an automake-specific
  1481. shadow variable for each user flag variable. (Shadow variables are not
  1482. introduced for variables like ‘CC’, where they would make no sense.)
  1483. The shadow variable is named by prepending ‘AM_’ to the user variable’s
  1484. name. For instance, the shadow variable for ‘YFLAGS’ is ‘AM_YFLAGS’.
  1485. The package maintainer—that is, the author(s) of the ‘Makefile.am’ and
  1486. ‘configure.ac’ files—may adjust these shadow variables however
  1487. necessary.
  1488. *Note Flag Variables Ordering::, for more discussion about these
  1489. variables and how they interact with per-target variables.
  1490. 
  1491. File: automake.info, Node: Auxiliary Programs, Prev: User Variables, Up: Generalities
  1492. 3.7 Programs automake might require
  1493. ===================================
  1494. Automake sometimes requires helper programs so that the generated
  1495. ‘Makefile’ can do its work properly. There are a fairly large number of
  1496. them, and we list them here.
  1497. Although all of these files are distributed and installed with
  1498. Automake, a couple of them are maintained separately. The Automake
  1499. copies are updated before each release, but we mention the original
  1500. source in case you need more recent versions.
  1501. ‘ar-lib’
  1502. This is a wrapper primarily for the Microsoft lib archiver, to make
  1503. it more POSIX-like.
  1504. ‘compile’
  1505. This is a wrapper for compilers that do not accept options ‘-c’ and
  1506. ‘-o’ at the same time. It is only used when absolutely required.
  1507. Such compilers are rare, with the Microsoft C/C++ Compiler as the
  1508. most notable exception. This wrapper also makes the following
  1509. common options available for that compiler, while performing file
  1510. name translation where needed: ‘-I’, ‘-L’, ‘-l’, ‘-Wl,’ and
  1511. ‘-Xlinker’.
  1512. ‘config.guess’
  1513. ‘config.sub’
  1514. These two programs compute the canonical triplets for the given
  1515. build, host, or target architecture. These programs are updated
  1516. regularly to support new architectures and fix probes broken by
  1517. changes in new kernel versions. Each new release of Automake comes
  1518. with up-to-date copies of these programs. If your copy of Automake
  1519. is getting old, you are encouraged to fetch the latest versions of
  1520. these files from <http://savannah.gnu.org/git/?group=config> before
  1521. making a release.
  1522. ‘depcomp’
  1523. This program understands how to run a compiler so that it will
  1524. generate not only the desired output but also dependency
  1525. information that is then used by the automatic dependency tracking
  1526. feature (*note Dependencies::).
  1527. ‘install-sh’
  1528. This is a replacement for the ‘install’ program that works on
  1529. platforms where ‘install’ is unavailable or unusable.
  1530. ‘mdate-sh’
  1531. This script is used to generate a ‘version.texi’ file. It examines
  1532. a file and prints some date information about it.
  1533. ‘missing’
  1534. This wraps a number of programs that are typically only required by
  1535. maintainers. If the program in question doesn’t exist, or seems to
  1536. old, ‘missing’ will print an informative warning before failing
  1537. out, to provide the user with more context and information.
  1538. ‘mkinstalldirs’
  1539. This script used to be a wrapper around ‘mkdir -p’, which is not
  1540. portable. Now we prefer to use ‘install-sh -d’ when ‘configure’
  1541. finds that ‘mkdir -p’ does not work, this makes one less script to
  1542. distribute.
  1543. For backward compatibility ‘mkinstalldirs’ is still used and
  1544. distributed when ‘automake’ finds it in a package. But it is no
  1545. longer installed automatically, and it should be safe to remove it.
  1546. ‘py-compile’
  1547. This is used to byte-compile Python scripts.
  1548. ‘test-driver’
  1549. This implements the default test driver offered by the parallel
  1550. testsuite harness.
  1551. ‘texinfo.tex’
  1552. Not a program, this file is required for ‘make dvi’, ‘make ps’ and
  1553. ‘make pdf’ to work when Texinfo sources are in the package. The
  1554. latest version can be downloaded from
  1555. <http://www.gnu.org/software/texinfo/>.
  1556. ‘ylwrap’
  1557. This program wraps ‘lex’ and ‘yacc’ to rename their output files.
  1558. It also ensures that, for instance, multiple ‘yacc’ instances can
  1559. be invoked in a single directory in parallel.
  1560. 
  1561. File: automake.info, Node: Examples, Next: automake Invocation, Prev: Generalities, Up: Top
  1562. 4 Some example packages
  1563. ***********************
  1564. This section contains two small examples.
  1565. The first example (*note Complete::) assumes you have an existing
  1566. project already using Autoconf, with handcrafted ‘Makefile’s, and that
  1567. you want to convert it to using Automake. If you are discovering both
  1568. tools, it is probably better that you look at the Hello World example
  1569. presented earlier (*note Hello World::).
  1570. The second example (*note true::) shows how two programs can be built
  1571. from the same file, using different compilation parameters. It contains
  1572. some technical digressions that are probably best skipped on first read.
  1573. * Menu:
  1574. * Complete:: A simple example, start to finish
  1575. * true:: Building true and false
  1576. 
  1577. File: automake.info, Node: Complete, Next: true, Up: Examples
  1578. 4.1 A simple example, start to finish
  1579. =====================================
  1580. Let’s suppose you just finished writing ‘zardoz’, a program to make your
  1581. head float from vortex to vortex. You’ve been using Autoconf to provide
  1582. a portability framework, but your ‘Makefile.in’s have been ad-hoc. You
  1583. want to make them bulletproof, so you turn to Automake.
  1584. The first step is to update your ‘configure.ac’ to include the
  1585. commands that ‘automake’ needs. The way to do this is to add an
  1586. ‘AM_INIT_AUTOMAKE’ call just after ‘AC_INIT’:
  1587. AC_INIT([zardoz], [1.0])
  1588. AM_INIT_AUTOMAKE
  1589. ...
  1590. Since your program doesn’t have any complicating factors (e.g., it
  1591. doesn’t use ‘gettext’, it doesn’t want to build a shared library),
  1592. you’re done with this part. That was easy!
  1593. Now you must regenerate ‘configure’. But to do that, you’ll need to
  1594. tell ‘autoconf’ how to find the new macro you’ve used. The easiest way
  1595. to do this is to use the ‘aclocal’ program to generate your ‘aclocal.m4’
  1596. for you. But wait... maybe you already have an ‘aclocal.m4’, because
  1597. you had to write some hairy macros for your program. The ‘aclocal’
  1598. program lets you put your own macros into ‘acinclude.m4’, so simply
  1599. rename and then run:
  1600. mv aclocal.m4 acinclude.m4
  1601. aclocal
  1602. autoconf
  1603. Now it is time to write your ‘Makefile.am’ for ‘zardoz’. Since
  1604. ‘zardoz’ is a user program, you want to install it where the rest of the
  1605. user programs go: ‘bindir’. Additionally, ‘zardoz’ has some Texinfo
  1606. documentation. Your ‘configure.ac’ script uses ‘AC_REPLACE_FUNCS’, so
  1607. you need to link against ‘$(LIBOBJS)’. So here’s what you’d write:
  1608. bin_PROGRAMS = zardoz
  1609. zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
  1610. zardoz_LDADD = $(LIBOBJS)
  1611. info_TEXINFOS = zardoz.texi
  1612. Now you can run ‘automake --add-missing’ to generate your
  1613. ‘Makefile.in’ and grab any auxiliary files you might need, and you’re
  1614. done!
  1615. 
  1616. File: automake.info, Node: true, Prev: Complete, Up: Examples
  1617. 4.2 Building true and false
  1618. ===========================
  1619. Here is another, trickier example. It shows how to generate two
  1620. programs (‘true’ and ‘false’) from the same source file (‘true.c’). The
  1621. difficult part is that each compilation of ‘true.c’ requires different
  1622. ‘cpp’ flags.
  1623. bin_PROGRAMS = true false
  1624. false_SOURCES =
  1625. false_LDADD = false.o
  1626. true.o: true.c
  1627. $(COMPILE) -DEXIT_CODE=0 -c true.c
  1628. false.o: true.c
  1629. $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
  1630. Note that there is no ‘true_SOURCES’ definition. Automake will
  1631. implicitly assume that there is a source file named ‘true.c’ (*note
  1632. Default _SOURCES::), and define rules to compile ‘true.o’ and link
  1633. ‘true’. The ‘true.o: true.c’ rule supplied by the above ‘Makefile.am’,
  1634. will override the Automake generated rule to build ‘true.o’.
  1635. ‘false_SOURCES’ is defined to be empty—that way no implicit value is
  1636. substituted. Because we have not listed the source of ‘false’, we have
  1637. to tell Automake how to link the program. This is the purpose of the
  1638. ‘false_LDADD’ line. A ‘false_DEPENDENCIES’ variable, holding the
  1639. dependencies of the ‘false’ target will be automatically generated by
  1640. Automake from the content of ‘false_LDADD’.
  1641. The above rules won’t work if your compiler doesn’t accept both ‘-c’
  1642. and ‘-o’. The simplest fix for this is to introduce a bogus dependency
  1643. (to avoid problems with a parallel ‘make’):
  1644. true.o: true.c false.o
  1645. $(COMPILE) -DEXIT_CODE=0 -c true.c
  1646. false.o: true.c
  1647. $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
  1648. As it turns out, there is also a much easier way to do this same
  1649. task. Some of the above technique is useful enough that we’ve kept the
  1650. example in the manual. However if you were to build ‘true’ and ‘false’
  1651. in real life, you would probably use per-program compilation flags, like
  1652. so:
  1653. bin_PROGRAMS = false true
  1654. false_SOURCES = true.c
  1655. false_CPPFLAGS = -DEXIT_CODE=1
  1656. true_SOURCES = true.c
  1657. true_CPPFLAGS = -DEXIT_CODE=0
  1658. In this case Automake will cause ‘true.c’ to be compiled twice, with
  1659. different flags. In this instance, the names of the object files would
  1660. be chosen by automake; they would be ‘false-true.o’ and ‘true-true.o’.
  1661. (The name of the object files rarely matters.)
  1662. 
  1663. File: automake.info, Node: automake Invocation, Next: configure, Prev: Examples, Up: Top
  1664. 5 Creating a ‘Makefile.in’
  1665. **************************
  1666. To create all the ‘Makefile.in’s for a package, run the ‘automake’
  1667. program in the top level directory, with no arguments. ‘automake’ will
  1668. automatically find each appropriate ‘Makefile.am’ (by scanning
  1669. ‘configure.ac’; *note configure::) and generate the corresponding
  1670. ‘Makefile.in’. Note that ‘automake’ has a rather simplistic view of
  1671. what constitutes a package; it assumes that a package has only one
  1672. ‘configure.ac’, at the top. If your package has multiple
  1673. ‘configure.ac’s, then you must run ‘automake’ in each directory holding
  1674. a ‘configure.ac’. (Alternatively, you may rely on Autoconf’s
  1675. ‘autoreconf’, which is able to recurse your package tree and run
  1676. ‘automake’ where appropriate.)
  1677. You can optionally give ‘automake’ an argument; ‘.am’ is appended to
  1678. the argument and the result is used as the name of the input file. This
  1679. feature is generally only used to automatically rebuild an out-of-date
  1680. ‘Makefile.in’. Note that ‘automake’ must always be run from the topmost
  1681. directory of a project, even if being used to regenerate the
  1682. ‘Makefile.in’ in some subdirectory. This is necessary because
  1683. ‘automake’ must scan ‘configure.ac’, and because ‘automake’ uses the
  1684. knowledge that a ‘Makefile.in’ is in a subdirectory to change its
  1685. behavior in some cases.
  1686. Automake will run ‘autoconf’ to scan ‘configure.ac’ and its
  1687. dependencies (i.e., ‘aclocal.m4’ and any included file), therefore
  1688. ‘autoconf’ must be in your ‘PATH’. If there is an ‘AUTOCONF’ variable
  1689. in your environment it will be used instead of ‘autoconf’, this allows
  1690. you to select a particular version of Autoconf. By the way, don’t
  1691. misunderstand this paragraph: ‘automake’ runs ‘autoconf’ to *scan* your
  1692. ‘configure.ac’, this won’t build ‘configure’ and you still have to run
  1693. ‘autoconf’ yourself for this purpose.
  1694. ‘automake’ accepts the following options:
  1695. ‘-a’
  1696. ‘--add-missing’
  1697. Automake requires certain common files to exist in certain
  1698. situations; for instance, ‘config.guess’ is required if
  1699. ‘configure.ac’ invokes ‘AC_CANONICAL_HOST’. Automake is
  1700. distributed with several of these files (*note Auxiliary
  1701. Programs::); this option will cause the missing ones to be
  1702. automatically added to the package, whenever possible. In general
  1703. if Automake tells you a file is missing, try using this option. By
  1704. default Automake tries to make a symbolic link pointing to its own
  1705. copy of the missing file; this can be changed with ‘--copy’.
  1706. Many of the potentially-missing files are common scripts whose
  1707. location may be specified via the ‘AC_CONFIG_AUX_DIR’ macro.
  1708. Therefore, ‘AC_CONFIG_AUX_DIR’’s setting affects whether a file is
  1709. considered missing, and where the missing file is added (*note
  1710. Optional::).
  1711. In some strictness modes, additional files are installed, see *note
  1712. Gnits:: for more information.
  1713. ‘--libdir=DIR’
  1714. Look for Automake data files in directory DIR instead of in the
  1715. installation directory. This is typically used for debugging.
  1716. ‘--print-libdir’
  1717. Print the path of the installation directory containing
  1718. Automake-provided scripts and data files (like e.g., ‘texinfo.texi’
  1719. and ‘install-sh’).
  1720. ‘-c’
  1721. ‘--copy’
  1722. When used with ‘--add-missing’, causes installed files to be
  1723. copied. The default is to make a symbolic link.
  1724. ‘-f’
  1725. ‘--force-missing’
  1726. When used with ‘--add-missing’, causes standard files to be
  1727. reinstalled even if they already exist in the source tree. This
  1728. involves removing the file from the source tree before creating the
  1729. new symlink (or, with ‘--copy’, copying the new file).
  1730. ‘--foreign’
  1731. Set the global strictness to ‘foreign’. For more information, see
  1732. *note Strictness::.
  1733. ‘--gnits’
  1734. Set the global strictness to ‘gnits’. For more information, see
  1735. *note Gnits::.
  1736. ‘--gnu’
  1737. Set the global strictness to ‘gnu’. For more information, see
  1738. *note Gnits::. This is the default strictness.
  1739. ‘--help’
  1740. Print a summary of the command line options and exit.
  1741. ‘-i’
  1742. ‘--ignore-deps’
  1743. This disables the dependency tracking feature in generated
  1744. ‘Makefile’s; see *note Dependencies::.
  1745. ‘--include-deps’
  1746. This enables the dependency tracking feature. This feature is
  1747. enabled by default. This option is provided for historical reasons
  1748. only and probably should not be used.
  1749. ‘--no-force’
  1750. Ordinarily ‘automake’ creates all ‘Makefile.in’s mentioned in
  1751. ‘configure.ac’. This option causes it to only update those
  1752. ‘Makefile.in’s that are out of date with respect to one of their
  1753. dependents.
  1754. ‘-o DIR’
  1755. ‘--output-dir=DIR’
  1756. Put the generated ‘Makefile.in’ in the directory DIR. Ordinarily
  1757. each ‘Makefile.in’ is created in the directory of the corresponding
  1758. ‘Makefile.am’. This option is deprecated and will be removed in a
  1759. future release.
  1760. ‘-v’
  1761. ‘--verbose’
  1762. Cause Automake to print information about which files are being
  1763. read or created.
  1764. ‘--version’
  1765. Print the version number of Automake and exit.
  1766. ‘-W CATEGORY’
  1767. ‘--warnings=CATEGORY’
  1768. Output warnings falling in CATEGORY. CATEGORY can be one of:
  1769. ‘gnu’
  1770. warnings related to the GNU Coding Standards (*note
  1771. (standards)Top::).
  1772. ‘obsolete’
  1773. obsolete features or constructions
  1774. ‘override’
  1775. user redefinitions of Automake rules or variables
  1776. ‘portability’
  1777. portability issues (e.g., use of ‘make’ features that are
  1778. known to be not portable)
  1779. ‘extra-portability’
  1780. extra portability issues related to obscure tools. One
  1781. example of such a tool is the Microsoft ‘lib’ archiver.
  1782. ‘syntax’
  1783. weird syntax, unused variables, typos
  1784. ‘unsupported’
  1785. unsupported or incomplete features
  1786. ‘all’
  1787. all the warnings
  1788. ‘none’
  1789. turn off all the warnings
  1790. ‘error’
  1791. treat warnings as errors
  1792. A category can be turned off by prefixing its name with ‘no-’. For
  1793. instance, ‘-Wno-syntax’ will hide the warnings about unused
  1794. variables.
  1795. The categories output by default are ‘obsolete’, ‘syntax’ and
  1796. ‘unsupported’. Additionally, ‘gnu’ and ‘portability’ are enabled
  1797. in ‘--gnu’ and ‘--gnits’ strictness.
  1798. Turning off ‘portability’ will also turn off ‘extra-portability’,
  1799. and similarly turning on ‘extra-portability’ will also turn on
  1800. ‘portability’. However, turning on ‘portability’ or turning off
  1801. ‘extra-portability’ will not affect the other category.
  1802. The environment variable ‘WARNINGS’ can contain a comma separated
  1803. list of categories to enable. It will be taken into account before
  1804. the command-line switches, this way ‘-Wnone’ will also ignore any
  1805. warning category enabled by ‘WARNINGS’. This variable is also used
  1806. by other tools like ‘autoconf’; unknown categories are ignored for
  1807. this reason.
  1808. If the environment variable ‘AUTOMAKE_JOBS’ contains a positive
  1809. number, it is taken as the maximum number of Perl threads to use in
  1810. ‘automake’ for generating multiple ‘Makefile.in’ files concurrently.
  1811. This is an experimental feature.
  1812. 
  1813. File: automake.info, Node: configure, Next: Directories, Prev: automake Invocation, Up: Top
  1814. 6 Scanning ‘configure.ac’, using ‘aclocal’
  1815. ******************************************
  1816. Automake scans the package’s ‘configure.ac’ to determine certain
  1817. information about the package. Some ‘autoconf’ macros are required and
  1818. some variables must be defined in ‘configure.ac’. Automake will also
  1819. use information from ‘configure.ac’ to further tailor its output.
  1820. Automake also supplies some Autoconf macros to make the maintenance
  1821. easier. These macros can automatically be put into your ‘aclocal.m4’
  1822. using the ‘aclocal’ program.
  1823. * Menu:
  1824. * Requirements:: Configuration requirements
  1825. * Optional:: Other things Automake recognizes
  1826. * aclocal Invocation:: Auto-generating aclocal.m4
  1827. * Macros:: Autoconf macros supplied with Automake
  1828. 
  1829. File: automake.info, Node: Requirements, Next: Optional, Up: configure
  1830. 6.1 Configuration requirements
  1831. ==============================
  1832. The one real requirement of Automake is that your ‘configure.ac’ call
  1833. ‘AM_INIT_AUTOMAKE’. This macro does several things that are required
  1834. for proper Automake operation (*note Macros::).
  1835. Here are the other macros that Automake requires but which are not
  1836. run by ‘AM_INIT_AUTOMAKE’:
  1837. ‘AC_CONFIG_FILES’
  1838. ‘AC_OUTPUT’
  1839. These two macros are usually invoked as follows near the end of
  1840. ‘configure.ac’.
  1841. ...
  1842. AC_CONFIG_FILES([
  1843. Makefile
  1844. doc/Makefile
  1845. src/Makefile
  1846. src/lib/Makefile
  1847. ...
  1848. ])
  1849. AC_OUTPUT
  1850. Automake uses these to determine which files to create (*note
  1851. Creating Output Files: (autoconf)Output.). A listed file is
  1852. considered to be an Automake generated ‘Makefile’ if there exists a
  1853. file with the same name and the ‘.am’ extension appended.
  1854. Typically, ‘AC_CONFIG_FILES([foo/Makefile])’ will cause Automake to
  1855. generate ‘foo/Makefile.in’ if ‘foo/Makefile.am’ exists.
  1856. When using ‘AC_CONFIG_FILES’ with multiple input files, as in
  1857. AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
  1858. ‘automake’ will generate the first ‘.in’ input file for which a
  1859. ‘.am’ file exists. If no such file exists the output file is not
  1860. considered to be generated by Automake.
  1861. Files created by ‘AC_CONFIG_FILES’, be they Automake ‘Makefile’s or
  1862. not, are all removed by ‘make distclean’. Their inputs are
  1863. automatically distributed, unless they are the output of prior
  1864. ‘AC_CONFIG_FILES’ commands. Finally, rebuild rules are generated
  1865. in the Automake ‘Makefile’ existing in the subdirectory of the
  1866. output file, if there is one, or in the top-level ‘Makefile’
  1867. otherwise.
  1868. The above machinery (cleaning, distributing, and rebuilding) works
  1869. fine if the ‘AC_CONFIG_FILES’ specifications contain only literals.
  1870. If part of the specification uses shell variables, ‘automake’ will
  1871. not be able to fulfill this setup, and you will have to complete
  1872. the missing bits by hand. For instance, on
  1873. file=input
  1874. ...
  1875. AC_CONFIG_FILES([output:$file],, [file=$file])
  1876. ‘automake’ will output rules to clean ‘output’, and rebuild it.
  1877. However the rebuild rule will not depend on ‘input’, and this file
  1878. will not be distributed either. (You must add ‘EXTRA_DIST = input’
  1879. to your ‘Makefile.am’ if ‘input’ is a source file.)
  1880. Similarly
  1881. file=output
  1882. file2=out:in
  1883. ...
  1884. AC_CONFIG_FILES([$file:input],, [file=$file])
  1885. AC_CONFIG_FILES([$file2],, [file2=$file2])
  1886. will only cause ‘input’ to be distributed. No file will be cleaned
  1887. automatically (add ‘DISTCLEANFILES = output out’ yourself), and no
  1888. rebuild rule will be output.
  1889. Obviously ‘automake’ cannot guess what value ‘$file’ is going to
  1890. hold later when ‘configure’ is run, and it cannot use the shell
  1891. variable ‘$file’ in a ‘Makefile’. However, if you make reference
  1892. to ‘$file’ as ‘${file}’ (i.e., in a way that is compatible with
  1893. ‘make’’s syntax) and furthermore use ‘AC_SUBST’ to ensure that
  1894. ‘${file}’ is meaningful in a ‘Makefile’, then ‘automake’ will be
  1895. able to use ‘${file}’ to generate all of these rules. For
  1896. instance, here is how the Automake package itself generates
  1897. versioned scripts for its test suite:
  1898. AC_SUBST([APIVERSION], ...)
  1899. ...
  1900. AC_CONFIG_FILES(
  1901. [tests/aclocal-${APIVERSION}:tests/aclocal.in],
  1902. [chmod +x tests/aclocal-${APIVERSION}],
  1903. [APIVERSION=$APIVERSION])
  1904. AC_CONFIG_FILES(
  1905. [tests/automake-${APIVERSION}:tests/automake.in],
  1906. [chmod +x tests/automake-${APIVERSION}])
  1907. Here cleaning, distributing, and rebuilding are done automatically,
  1908. because ‘${APIVERSION}’ is known at ‘make’-time.
  1909. Note that you should not use shell variables to declare ‘Makefile’
  1910. files for which ‘automake’ must create ‘Makefile.in’. Even
  1911. ‘AC_SUBST’ does not help here, because ‘automake’ needs to know the
  1912. file name when it runs in order to check whether ‘Makefile.am’
  1913. exists. (In the very hairy case that your setup requires such use
  1914. of variables, you will have to tell Automake which ‘Makefile.in’s
  1915. to generate on the command-line.)
  1916. It is possible to let ‘automake’ emit conditional rules for
  1917. ‘AC_CONFIG_FILES’ with the help of ‘AM_COND_IF’ (*note Optional::).
  1918. To summarize:
  1919. • Use literals for ‘Makefile’s, and for other files whenever
  1920. possible.
  1921. • Use ‘$file’ (or ‘${file}’ without ‘AC_SUBST([file])’) for
  1922. files that ‘automake’ should ignore.
  1923. • Use ‘${file}’ and ‘AC_SUBST([file])’ for files that ‘automake’
  1924. should not ignore.
  1925. 
  1926. File: automake.info, Node: Optional, Next: aclocal Invocation, Prev: Requirements, Up: configure
  1927. 6.2 Other things Automake recognizes
  1928. ====================================
  1929. Every time Automake is run it calls Autoconf to trace ‘configure.ac’.
  1930. This way it can recognize the use of certain macros and tailor the
  1931. generated ‘Makefile.in’ appropriately. Currently recognized macros and
  1932. their effects are:
  1933. ‘AC_CANONICAL_BUILD’
  1934. ‘AC_CANONICAL_HOST’
  1935. ‘AC_CANONICAL_TARGET’
  1936. Automake will ensure that ‘config.guess’ and ‘config.sub’ exist.
  1937. Also, the ‘Makefile’ variables ‘build_triplet’, ‘host_triplet’ and
  1938. ‘target_triplet’ are introduced. See *note Getting the Canonical
  1939. System Type: (autoconf)Canonicalizing.
  1940. ‘AC_CONFIG_AUX_DIR’
  1941. Automake will look for various helper scripts, such as
  1942. ‘install-sh’, in the directory named in this macro invocation.
  1943. (The full list of scripts is: ‘ar-lib’, ‘config.guess’,
  1944. ‘config.sub’, ‘depcomp’, ‘compile’, ‘install-sh’, ‘ltmain.sh’,
  1945. ‘mdate-sh’, ‘missing’, ‘mkinstalldirs’, ‘py-compile’,
  1946. ‘test-driver’, ‘texinfo.tex’, ‘ylwrap’.) Not all scripts are
  1947. always searched for; some scripts will only be sought if the
  1948. generated ‘Makefile.in’ requires them.
  1949. If ‘AC_CONFIG_AUX_DIR’ is not given, the scripts are looked for in
  1950. their standard locations. For ‘mdate-sh’, ‘texinfo.tex’, and
  1951. ‘ylwrap’, the standard location is the source directory
  1952. corresponding to the current ‘Makefile.am’. For the rest, the
  1953. standard location is the first one of ‘.’, ‘..’, or ‘../..’
  1954. (relative to the top source directory) that provides any one of the
  1955. helper scripts. *Note Finding ‘configure’ Input: (autoconf)Input.
  1956. Required files from ‘AC_CONFIG_AUX_DIR’ are automatically
  1957. distributed, even if there is no ‘Makefile.am’ in this directory.
  1958. ‘AC_CONFIG_LIBOBJ_DIR’
  1959. Automake will require the sources file declared with ‘AC_LIBSOURCE’
  1960. (see below) in the directory specified by this macro.
  1961. ‘AC_CONFIG_HEADERS’
  1962. Automake will generate rules to rebuild these headers from the
  1963. corresponding templates (usually, the template for a ‘foo.h’ header
  1964. being ‘foo.h.in’). Older versions of Automake required the use of
  1965. ‘AM_CONFIG_HEADER’; this is no longer the case, and that macro has
  1966. indeed been removed.
  1967. As with ‘AC_CONFIG_FILES’ (*note Requirements::), parts of the
  1968. specification using shell variables will be ignored as far as
  1969. cleaning, distributing, and rebuilding is concerned.
  1970. ‘AC_CONFIG_LINKS’
  1971. Automake will generate rules to remove ‘configure’ generated links
  1972. on ‘make distclean’ and to distribute named source files as part of
  1973. ‘make dist’.
  1974. As for ‘AC_CONFIG_FILES’ (*note Requirements::), parts of the
  1975. specification using shell variables will be ignored as far as
  1976. cleaning and distributing is concerned. (There are no rebuild
  1977. rules for links.)
  1978. ‘AC_LIBOBJ’
  1979. ‘AC_LIBSOURCE’
  1980. ‘AC_LIBSOURCES’
  1981. Automake will automatically distribute any file listed in
  1982. ‘AC_LIBSOURCE’ or ‘AC_LIBSOURCES’.
  1983. Note that the ‘AC_LIBOBJ’ macro calls ‘AC_LIBSOURCE’. So if an
  1984. Autoconf macro is documented to call ‘AC_LIBOBJ([file])’, then
  1985. ‘file.c’ will be distributed automatically by Automake. This
  1986. encompasses many macros like ‘AC_FUNC_ALLOCA’, ‘AC_FUNC_MEMCMP’,
  1987. ‘AC_REPLACE_FUNCS’, and others.
  1988. By the way, direct assignments to ‘LIBOBJS’ are no longer
  1989. supported. You should always use ‘AC_LIBOBJ’ for this purpose.
  1990. *Note ‘AC_LIBOBJ’ vs. ‘LIBOBJS’: (autoconf)AC_LIBOBJ vs LIBOBJS.
  1991. ‘AC_PROG_RANLIB’
  1992. This is required if any libraries are built in the package. *Note
  1993. Particular Program Checks: (autoconf)Particular Programs.
  1994. ‘AC_PROG_CXX’
  1995. This is required if any C++ source is included. *Note Particular
  1996. Program Checks: (autoconf)Particular Programs.
  1997. ‘AC_PROG_OBJC’
  1998. This is required if any Objective C source is included. *Note
  1999. Particular Program Checks: (autoconf)Particular Programs.
  2000. ‘AC_PROG_OBJCXX’
  2001. This is required if any Objective C++ source is included. *Note
  2002. Particular Program Checks: (autoconf)Particular Programs.
  2003. ‘AC_PROG_F77’
  2004. This is required if any Fortran 77 source is included. *Note
  2005. Particular Program Checks: (autoconf)Particular Programs.
  2006. ‘AC_F77_LIBRARY_LDFLAGS’
  2007. This is required for programs and shared libraries that are a
  2008. mixture of languages that include Fortran 77 (*note Mixing Fortran
  2009. 77 With C and C++::). *Note Autoconf macros supplied with
  2010. Automake: Macros.
  2011. ‘AC_FC_SRCEXT’
  2012. Automake will add the flags computed by ‘AC_FC_SRCEXT’ to
  2013. compilation of files with the respective source extension (*note
  2014. Fortran Compiler Characteristics: (autoconf)Fortran Compiler.).
  2015. ‘AC_PROG_FC’
  2016. This is required if any Fortran 90/95 source is included. This
  2017. macro is distributed with Autoconf version 2.58 and later. *Note
  2018. Particular Program Checks: (autoconf)Particular Programs.
  2019. ‘AC_PROG_LIBTOOL’
  2020. Automake will turn on processing for ‘libtool’ (*note Introduction:
  2021. (libtool)Top.).
  2022. ‘AC_PROG_YACC’
  2023. If a Yacc source file is seen, then you must either use this macro
  2024. or define the variable ‘YACC’ in ‘configure.ac’. The former is
  2025. preferred (*note Particular Program Checks: (autoconf)Particular
  2026. Programs.).
  2027. ‘AC_PROG_LEX’
  2028. If a Lex source file is seen, then this macro must be used. *Note
  2029. Particular Program Checks: (autoconf)Particular Programs.
  2030. ‘AC_REQUIRE_AUX_FILE’
  2031. For each ‘AC_REQUIRE_AUX_FILE([FILE])’, ‘automake’ will ensure that
  2032. ‘FILE’ exists in the aux directory, and will complain otherwise.
  2033. It will also automatically distribute the file. This macro should
  2034. be used by third-party Autoconf macros that require some supporting
  2035. files in the aux directory specified with ‘AC_CONFIG_AUX_DIR’
  2036. above. *Note Finding ‘configure’ Input: (autoconf)Input.
  2037. ‘AC_SUBST’
  2038. The first argument is automatically defined as a variable in each
  2039. generated ‘Makefile.in’, unless ‘AM_SUBST_NOTMAKE’ is also used for
  2040. this variable. *Note Setting Output Variables: (autoconf)Setting
  2041. Output Variables.
  2042. For every substituted variable VAR, ‘automake’ will add a line ‘VAR
  2043. = VALUE’ to each ‘Makefile.in’ file. Many Autoconf macros invoke
  2044. ‘AC_SUBST’ to set output variables this way, e.g., ‘AC_PATH_XTRA’
  2045. defines ‘X_CFLAGS’ and ‘X_LIBS’. Thus, you can access these
  2046. variables as ‘$(X_CFLAGS)’ and ‘$(X_LIBS)’ in any ‘Makefile.am’ if
  2047. ‘AC_PATH_XTRA’ is called.
  2048. ‘AM_CONDITIONAL’
  2049. This introduces an Automake conditional (*note Conditionals::).
  2050. ‘AM_COND_IF’
  2051. This macro allows ‘automake’ to detect subsequent access within
  2052. ‘configure.ac’ to a conditional previously introduced with
  2053. ‘AM_CONDITIONAL’, thus enabling conditional ‘AC_CONFIG_FILES’
  2054. (*note Usage of Conditionals::).
  2055. ‘AM_GNU_GETTEXT’
  2056. This macro is required for packages that use GNU gettext (*note
  2057. gettext::). It is distributed with gettext. If Automake sees this
  2058. macro it ensures that the package meets some of gettext’s
  2059. requirements.
  2060. ‘AM_GNU_GETTEXT_INTL_SUBDIR’
  2061. This macro specifies that the ‘intl/’ subdirectory is to be built,
  2062. even if the ‘AM_GNU_GETTEXT’ macro was invoked with a first
  2063. argument of ‘external’.
  2064. ‘AM_MAINTAINER_MODE([DEFAULT-MODE])’
  2065. This macro adds an ‘--enable-maintainer-mode’ option to
  2066. ‘configure’. If this is used, ‘automake’ will cause
  2067. “maintainer-only” rules to be turned off by default in the
  2068. generated ‘Makefile.in’s, unless DEFAULT-MODE is ‘enable’. This
  2069. macro defines the ‘MAINTAINER_MODE’ conditional, which you can use
  2070. in your own ‘Makefile.am’. *Note maintainer-mode::.
  2071. ‘AM_SUBST_NOTMAKE(VAR)’
  2072. Prevent Automake from defining a variable VAR, even if it is
  2073. substituted by ‘config.status’. Normally, Automake defines a
  2074. ‘make’ variable for each ‘configure’ substitution, i.e., for each
  2075. ‘AC_SUBST([VAR])’. This macro prevents that definition from
  2076. Automake. If ‘AC_SUBST’ has not been called for this variable,
  2077. then ‘AM_SUBST_NOTMAKE’ has no effects. Preventing variable
  2078. definitions may be useful for substitution of multi-line values,
  2079. where ‘VAR = @VALUE@’ might yield unintended results.
  2080. ‘m4_include’
  2081. Files included by ‘configure.ac’ using this macro will be detected
  2082. by Automake and automatically distributed. They will also appear
  2083. as dependencies in ‘Makefile’ rules.
  2084. ‘m4_include’ is seldom used by ‘configure.ac’ authors, but can
  2085. appear in ‘aclocal.m4’ when ‘aclocal’ detects that some required
  2086. macros come from files local to your package (as opposed to macros
  2087. installed in a system-wide directory, *note aclocal Invocation::).
  2088. 
  2089. File: automake.info, Node: aclocal Invocation, Next: Macros, Prev: Optional, Up: configure
  2090. 6.3 Auto-generating aclocal.m4
  2091. ==============================
  2092. Automake includes a number of Autoconf macros that can be used in your
  2093. package (*note Macros::); some of them are actually required by Automake
  2094. in certain situations. These macros must be defined in your
  2095. ‘aclocal.m4’; otherwise they will not be seen by ‘autoconf’.
  2096. The ‘aclocal’ program will automatically generate ‘aclocal.m4’ files
  2097. based on the contents of ‘configure.ac’. This provides a convenient way
  2098. to get Automake-provided macros, without having to search around. The
  2099. ‘aclocal’ mechanism allows other packages to supply their own macros
  2100. (*note Extending aclocal::). You can also use it to maintain your own
  2101. set of custom macros (*note Local Macros::).
  2102. At startup, ‘aclocal’ scans all the ‘.m4’ files it can find, looking
  2103. for macro definitions (*note Macro Search Path::). Then it scans
  2104. ‘configure.ac’. Any mention of one of the macros found in the first
  2105. step causes that macro, and any macros it in turn requires, to be put
  2106. into ‘aclocal.m4’.
  2107. _Putting_ the file that contains the macro definition into
  2108. ‘aclocal.m4’ is usually done by copying the entire text of this file,
  2109. including unused macro definitions as well as both ‘#’ and ‘dnl’
  2110. comments. If you want to make a comment that will be completely ignored
  2111. by ‘aclocal’, use ‘##’ as the comment leader.
  2112. When a file selected by ‘aclocal’ is located in a subdirectory
  2113. specified as a relative search path with ‘aclocal’’s ‘-I’ argument,
  2114. ‘aclocal’ assumes the file belongs to the package and uses ‘m4_include’
  2115. instead of copying it into ‘aclocal.m4’. This makes the package
  2116. smaller, eases dependency tracking, and cause the file to be distributed
  2117. automatically. (*Note Local Macros::, for an example.) Any macro that
  2118. is found in a system-wide directory, or via an absolute search path will
  2119. be copied. So use ‘-I `pwd`/reldir’ instead of ‘-I reldir’ whenever
  2120. some relative directory should be considered outside the package.
  2121. The contents of ‘acinclude.m4’, if this file exists, are also
  2122. automatically included in ‘aclocal.m4’. We recommend against using
  2123. ‘acinclude.m4’ in new packages (*note Local Macros::).
  2124. While computing ‘aclocal.m4’, ‘aclocal’ runs ‘autom4te’ (*note Using
  2125. ‘Autom4te’: (autoconf)Using autom4te.) in order to trace the macros that
  2126. are really used, and omit from ‘aclocal.m4’ all macros that are
  2127. mentioned but otherwise unexpanded (this can happen when a macro is
  2128. called conditionally). ‘autom4te’ is expected to be in the ‘PATH’, just
  2129. as ‘autoconf’. Its location can be overridden using the ‘AUTOM4TE’
  2130. environment variable.
  2131. * Menu:
  2132. * aclocal Options:: Options supported by aclocal
  2133. * Macro Search Path:: How aclocal finds .m4 files
  2134. * Extending aclocal:: Writing your own aclocal macros
  2135. * Local Macros:: Organizing local macros
  2136. * Serials:: Serial lines in Autoconf macros
  2137. * Future of aclocal:: aclocal’s scheduled death
  2138. 
  2139. File: automake.info, Node: aclocal Options, Next: Macro Search Path, Up: aclocal Invocation
  2140. 6.3.1 aclocal Options
  2141. ---------------------
  2142. ‘aclocal’ accepts the following options:
  2143. ‘--automake-acdir=DIR’
  2144. Look for the automake-provided macro files in DIR instead of in the
  2145. installation directory. This is typically used for debugging.
  2146. ‘--system-acdir=DIR’
  2147. Look for the system-wide third-party macro files (and the special
  2148. ‘dirlist’ file) in DIR instead of in the installation directory.
  2149. This is typically used for debugging.
  2150. ‘--diff[=COMMAND]’
  2151. Run COMMAND on M4 file that would be installed or overwritten by
  2152. ‘--install’. The default COMMAND is ‘diff -u’. This option
  2153. implies ‘--install’ and ‘--dry-run’.
  2154. ‘--dry-run’
  2155. Do not actually overwrite (or create) ‘aclocal.m4’ and M4 files
  2156. installed by ‘--install’.
  2157. ‘--help’
  2158. Print a summary of the command line options and exit.
  2159. ‘-I DIR’
  2160. Add the directory DIR to the list of directories searched for ‘.m4’
  2161. files.
  2162. ‘--install’
  2163. Install system-wide third-party macros into the first directory
  2164. specified with ‘-I DIR’ instead of copying them in the output file.
  2165. Note that this will happen also if DIR is an absolute path.
  2166. When this option is used, and only when this option is used,
  2167. ‘aclocal’ will also honor ‘#serial NUMBER’ lines that appear in
  2168. macros: an M4 file is ignored if there exists another M4 file with
  2169. the same basename and a greater serial number in the search path
  2170. (*note Serials::).
  2171. ‘--force’
  2172. Always overwrite the output file. The default is to overwrite the
  2173. output file only when really needed, i.e., when its contents
  2174. changes or if one of its dependencies is younger.
  2175. This option forces the update of ‘aclocal.m4’ (or the file
  2176. specified with ‘--output’ below) and only this file, it has
  2177. absolutely no influence on files that may need to be installed by
  2178. ‘--install’.
  2179. ‘--output=FILE’
  2180. Cause the output to be put into FILE instead of ‘aclocal.m4’.
  2181. ‘--print-ac-dir’
  2182. Prints the name of the directory that ‘aclocal’ will search to find
  2183. third-party ‘.m4’ files. When this option is given, normal
  2184. processing is suppressed. This option was used _in the past_ by
  2185. third-party packages to determine where to install ‘.m4’ macro
  2186. files, but _this usage is today discouraged_, since it causes
  2187. ‘$(prefix)’ not to be thoroughly honored (which violates the GNU
  2188. Coding Standards), and a similar semantics can be better obtained
  2189. with the ‘ACLOCAL_PATH’ environment variable; *note Extending
  2190. aclocal::.
  2191. ‘--verbose’
  2192. Print the names of the files it examines.
  2193. ‘--version’
  2194. Print the version number of Automake and exit.
  2195. ‘-W CATEGORY’
  2196. ‘--warnings=CATEGORY’
  2197. Output warnings falling in CATEGORY. CATEGORY can be one of:
  2198. ‘syntax’
  2199. dubious syntactic constructs, underquoted macros, unused
  2200. macros, etc.
  2201. ‘unsupported’
  2202. unknown macros
  2203. ‘all’
  2204. all the warnings, this is the default
  2205. ‘none’
  2206. turn off all the warnings
  2207. ‘error’
  2208. treat warnings as errors
  2209. All warnings are output by default.
  2210. The environment variable ‘WARNINGS’ is honored in the same way as
  2211. it is for ‘automake’ (*note automake Invocation::).
  2212. 
  2213. File: automake.info, Node: Macro Search Path, Next: Extending aclocal, Prev: aclocal Options, Up: aclocal Invocation
  2214. 6.3.2 Macro Search Path
  2215. -----------------------
  2216. By default, ‘aclocal’ searches for ‘.m4’ files in the following
  2217. directories, in this order:
  2218. ‘ACDIR-APIVERSION’
  2219. This is where the ‘.m4’ macros distributed with Automake itself are
  2220. stored. APIVERSION depends on the Automake release used; for
  2221. example, for Automake 1.11.x, APIVERSION = ‘1.11’.
  2222. ‘ACDIR’
  2223. This directory is intended for third party ‘.m4’ files, and is
  2224. configured when ‘automake’ itself is built. This is
  2225. ‘@datadir@/aclocal/’, which typically expands to
  2226. ‘${prefix}/share/aclocal/’. To find the compiled-in value of
  2227. ACDIR, use the ‘--print-ac-dir’ option (*note aclocal Options::).
  2228. As an example, suppose that ‘automake-1.11.2’ was configured with
  2229. ‘--prefix=/usr/local’. Then, the search path would be:
  2230. 1. ‘/usr/local/share/aclocal-1.11.2/’
  2231. 2. ‘/usr/local/share/aclocal/’
  2232. The paths for the ACDIR and ACDIR-APIVERSION directories can be
  2233. changed respectively through aclocal options ‘--system-acdir’ and
  2234. ‘--automake-acdir’ (*note aclocal Options::). Note however that these
  2235. options are only intended for use by the internal Automake test suite,
  2236. or for debugging under highly unusual situations; they are not
  2237. ordinarily needed by end-users.
  2238. As explained in (*note aclocal Options::), there are several options
  2239. that can be used to change or extend this search path.
  2240. Modifying the Macro Search Path: ‘-I DIR’
  2241. .........................................
  2242. Any extra directories specified using ‘-I’ options (*note aclocal
  2243. Options::) are _prepended_ to this search list. Thus, ‘aclocal -I /foo
  2244. -I /bar’ results in the following search path:
  2245. 1. ‘/foo’
  2246. 2. ‘/bar’
  2247. 3. ACDIR-APIVERSION
  2248. 4. ACDIR
  2249. Modifying the Macro Search Path: ‘dirlist’
  2250. ..........................................
  2251. There is a third mechanism for customizing the search path. If a
  2252. ‘dirlist’ file exists in ACDIR, then that file is assumed to contain a
  2253. list of directory patterns, one per line. ‘aclocal’ expands these
  2254. patterns to directory names, and adds them to the search list _after_
  2255. all other directories. ‘dirlist’ entries may use shell wildcards such
  2256. as ‘*’, ‘?’, or ‘[...]’.
  2257. For example, suppose ‘ACDIR/dirlist’ contains the following:
  2258. /test1
  2259. /test2
  2260. /test3*
  2261. and that ‘aclocal’ was called with the ‘-I /foo -I /bar’ options. Then,
  2262. the search path would be
  2263. 1. ‘/foo’
  2264. 2. ‘/bar’
  2265. 3. ACDIR-APIVERSION
  2266. 4. ACDIR
  2267. 5. ‘/test1’
  2268. 6. ‘/test2’
  2269. and all directories with path names starting with ‘/test3’.
  2270. If the ‘--system-acdir=DIR’ option is used, then ‘aclocal’ will
  2271. search for the ‘dirlist’ file in DIR; but remember the warnings above
  2272. against the use of ‘--system-acdir’.
  2273. ‘dirlist’ is useful in the following situation: suppose that
  2274. ‘automake’ version ‘1.11.2’ is installed with ‘--prefix=/usr’ by the
  2275. system vendor. Thus, the default search directories are
  2276. 1. ‘/usr/share/aclocal-1.11/’
  2277. 2. ‘/usr/share/aclocal/’
  2278. However, suppose further that many packages have been manually
  2279. installed on the system, with $prefix=/usr/local, as is typical. In
  2280. that case, many of these “extra” ‘.m4’ files are in
  2281. ‘/usr/local/share/aclocal’. The only way to force ‘/usr/bin/aclocal’ to
  2282. find these “extra” ‘.m4’ files is to always call ‘aclocal -I
  2283. /usr/local/share/aclocal’. This is inconvenient. With ‘dirlist’, one
  2284. may create a file ‘/usr/share/aclocal/dirlist’ containing only the
  2285. single line
  2286. /usr/local/share/aclocal
  2287. Now, the “default” search path on the affected system is
  2288. 1. ‘/usr/share/aclocal-1.11/’
  2289. 2. ‘/usr/share/aclocal/’
  2290. 3. ‘/usr/local/share/aclocal/’
  2291. without the need for ‘-I’ options; ‘-I’ options can be reserved for
  2292. project-specific needs (‘my-source-dir/m4/’), rather than using it to
  2293. work around local system-dependent tool installation directories.
  2294. Similarly, ‘dirlist’ can be handy if you have installed a local copy
  2295. of Automake in your account and want ‘aclocal’ to look for macros
  2296. installed at other places on the system.
  2297. Modifying the Macro Search Path: ‘ACLOCAL_PATH’
  2298. ...............................................
  2299. The fourth and last mechanism to customize the macro search path is also
  2300. the simplest. Any directory included in the colon-separated environment
  2301. variable ‘ACLOCAL_PATH’ is added to the search path and takes precedence
  2302. over system directories (including those found via ‘dirlist’), with the
  2303. exception of the versioned directory ACDIR-APIVERSION (*note Macro
  2304. Search Path::). However, directories passed via ‘-I’ will take
  2305. precedence over directories in ‘ACLOCAL_PATH’.
  2306. Also note that, if the ‘--install’ option is used, any ‘.m4’ file
  2307. containing a required macro that is found in a directory listed in
  2308. ‘ACLOCAL_PATH’ will be installed locally. In this case, serial numbers
  2309. in ‘.m4’ are honored too, *note Serials::.
  2310. Conversely to ‘dirlist’, ‘ACLOCAL_PATH’ is useful if you are using a
  2311. global copy of Automake and want ‘aclocal’ to look for macros somewhere
  2312. under your home directory.
  2313. Planned future incompatibilities
  2314. ................................
  2315. The order in which the directories in the macro search path are
  2316. currently looked up is confusing and/or suboptimal in various aspects,
  2317. and is probably going to be changed in the future Automake release. In
  2318. particular, directories in ‘ACLOCAL_PATH’ and ‘ACDIR’ might end up
  2319. taking precedence over ‘ACDIR-APIVERSION’, and directories in
  2320. ‘ACDIR/dirlist’ might end up taking precedence over ‘ACDIR’. _This is a
  2321. possible future incompatibility!_
  2322. 
  2323. File: automake.info, Node: Extending aclocal, Next: Local Macros, Prev: Macro Search Path, Up: aclocal Invocation
  2324. 6.3.3 Writing your own aclocal macros
  2325. -------------------------------------
  2326. The ‘aclocal’ program doesn’t have any built-in knowledge of any macros,
  2327. so it is easy to extend it with your own macros.
  2328. This can be used by libraries that want to supply their own Autoconf
  2329. macros for use by other programs. For instance, the ‘gettext’ library
  2330. supplies a macro ‘AM_GNU_GETTEXT’ that should be used by any package
  2331. using ‘gettext’. When the library is installed, it installs this macro
  2332. so that ‘aclocal’ will find it.
  2333. A macro file’s name should end in ‘.m4’. Such files should be
  2334. installed in ‘$(datadir)/aclocal’. This is as simple as writing:
  2335. aclocaldir = $(datadir)/aclocal
  2336. aclocal_DATA = mymacro.m4 myothermacro.m4
  2337. Please do use ‘$(datadir)/aclocal’, and not something based on the
  2338. result of ‘aclocal --print-ac-dir’ (*note Hard-Coded Install Paths::,
  2339. for arguments). It might also be helpful to suggest to the user to add
  2340. the ‘$(datadir)/aclocal’ directory to his ‘ACLOCAL_PATH’ variable (*note
  2341. ACLOCAL_PATH::) so that ‘aclocal’ will find the ‘.m4’ files installed by
  2342. your package automatically.
  2343. A file of macros should be a series of properly quoted ‘AC_DEFUN’’s
  2344. (*note (autoconf)Macro Definitions::). The ‘aclocal’ programs also
  2345. understands ‘AC_REQUIRE’ (*note (autoconf)Prerequisite Macros::), so it
  2346. is safe to put each macro in a separate file. Each file should have no
  2347. side effects but macro definitions. Especially, any call to ‘AC_PREREQ’
  2348. should be done inside the defined macro, not at the beginning of the
  2349. file.
  2350. Starting with Automake 1.8, ‘aclocal’ will warn about all underquoted
  2351. calls to ‘AC_DEFUN’. We realize this will annoy a lot of people,
  2352. because ‘aclocal’ was not so strict in the past and many third party
  2353. macros are underquoted; and we have to apologize for this temporary
  2354. inconvenience. The reason we have to be stricter is that a future
  2355. implementation of ‘aclocal’ (*note Future of aclocal::) will have to
  2356. temporarily include all of these third party ‘.m4’ files, maybe several
  2357. times, including even files that are not actually needed. Doing so
  2358. should alleviate many problems of the current implementation, however it
  2359. requires a stricter style from the macro authors. Hopefully it is easy
  2360. to revise the existing macros. For instance,
  2361. # bad style
  2362. AC_PREREQ(2.68)
  2363. AC_DEFUN(AX_FOOBAR,
  2364. [AC_REQUIRE([AX_SOMETHING])dnl
  2365. AX_FOO
  2366. AX_BAR
  2367. ])
  2368. should be rewritten as
  2369. AC_DEFUN([AX_FOOBAR],
  2370. [AC_PREREQ([2.68])dnl
  2371. AC_REQUIRE([AX_SOMETHING])dnl
  2372. AX_FOO
  2373. AX_BAR
  2374. ])
  2375. Wrapping the ‘AC_PREREQ’ call inside the macro ensures that Autoconf
  2376. 2.68 will not be required if ‘AX_FOOBAR’ is not actually used. Most
  2377. importantly, quoting the first argument of ‘AC_DEFUN’ allows the macro
  2378. to be redefined or included twice (otherwise this first argument would
  2379. be expanded during the second definition). For consistency we like to
  2380. quote even arguments such as ‘2.68’ that do not require it.
  2381. If you have been directed here by the ‘aclocal’ diagnostic but are
  2382. not the maintainer of the implicated macro, you will want to contact the
  2383. maintainer of that macro. Please make sure you have the latest version
  2384. of the macro and that the problem hasn’t already been reported before
  2385. doing so: people tend to work faster when they aren’t flooded by mails.
  2386. Another situation where ‘aclocal’ is commonly used is to manage
  2387. macros that are used locally by the package, *note Local Macros::.
  2388. 
  2389. File: automake.info, Node: Local Macros, Next: Serials, Prev: Extending aclocal, Up: aclocal Invocation
  2390. 6.3.4 Handling Local Macros
  2391. ---------------------------
  2392. Feature tests offered by Autoconf do not cover all needs. People often
  2393. have to supplement existing tests with their own macros, or with
  2394. third-party macros.
  2395. There are two ways to organize custom macros in a package.
  2396. The first possibility (the historical practice) is to list all your
  2397. macros in ‘acinclude.m4’. This file will be included in ‘aclocal.m4’
  2398. when you run ‘aclocal’, and its macro(s) will henceforth be visible to
  2399. ‘autoconf’. However if it contains numerous macros, it will rapidly
  2400. become difficult to maintain, and it will be almost impossible to share
  2401. macros between packages.
  2402. The second possibility, which we do recommend, is to write each macro
  2403. in its own file and gather all these files in a directory. This
  2404. directory is usually called ‘m4/’. Then it’s enough to update
  2405. ‘configure.ac’ by adding a proper call to ‘AC_CONFIG_MACRO_DIRS’:
  2406. AC_CONFIG_MACRO_DIRS([m4])
  2407. ‘aclocal’ will then take care of automatically adding ‘m4/’ to its
  2408. search path for m4 files.
  2409. When ‘aclocal’ is run, it will build an ‘aclocal.m4’ that
  2410. ‘m4_include’s any file from ‘m4/’ that defines a required macro. Macros
  2411. not found locally will still be searched in system-wide directories, as
  2412. explained in *note Macro Search Path::.
  2413. Custom macros should be distributed for the same reason that
  2414. ‘configure.ac’ is: so that other people have all the sources of your
  2415. package if they want to work on it. Actually, this distribution happens
  2416. automatically because all ‘m4_include’d files are distributed.
  2417. However there is no consensus on the distribution of third-party
  2418. macros that your package may use. Many libraries install their own
  2419. macro in the system-wide ‘aclocal’ directory (*note Extending
  2420. aclocal::). For instance, Guile ships with a file called ‘guile.m4’
  2421. that contains the macro ‘GUILE_FLAGS’ that can be used to define setup
  2422. compiler and linker flags appropriate for using Guile. Using
  2423. ‘GUILE_FLAGS’ in ‘configure.ac’ will cause ‘aclocal’ to copy ‘guile.m4’
  2424. into ‘aclocal.m4’, but as ‘guile.m4’ is not part of the project, it will
  2425. not be distributed. Technically, that means a user who needs to rebuild
  2426. ‘aclocal.m4’ will have to install Guile first. This is probably OK, if
  2427. Guile already is a requirement to build the package. However, if Guile
  2428. is only an optional feature, or if your package might run on
  2429. architectures where Guile cannot be installed, this requirement will
  2430. hinder development. An easy solution is to copy such third-party macros
  2431. in your local ‘m4/’ directory so they get distributed.
  2432. Since Automake 1.10, ‘aclocal’ offers the option ‘--install’ to copy
  2433. these system-wide third-party macros in your local macro directory,
  2434. helping to solve the above problem.
  2435. With this setup, system-wide macros will be copied to ‘m4/’ the first
  2436. time you run ‘aclocal’. Then the locally installed macros will have
  2437. precedence over the system-wide installed macros each time ‘aclocal’ is
  2438. run again.
  2439. One reason why you should keep ‘--install’ in the flags even after
  2440. the first run is that when you later edit ‘configure.ac’ and depend on a
  2441. new macro, this macro will be installed in your ‘m4/’ automatically.
  2442. Another one is that serial numbers (*note Serials::) can be used to
  2443. update the macros in your source tree automatically when new system-wide
  2444. versions are installed. A serial number should be a single line of the
  2445. form
  2446. #serial NNN
  2447. where NNN contains only digits and dots. It should appear in the M4
  2448. file before any macro definition. It is a good practice to maintain a
  2449. serial number for each macro you distribute, even if you do not use the
  2450. ‘--install’ option of ‘aclocal’: this allows other people to use it.
  2451. 
  2452. File: automake.info, Node: Serials, Next: Future of aclocal, Prev: Local Macros, Up: aclocal Invocation
  2453. 6.3.5 Serial Numbers
  2454. --------------------
  2455. Because third-party macros defined in ‘*.m4’ files are naturally shared
  2456. between multiple projects, some people like to version them. This makes
  2457. it easier to tell which of two M4 files is newer. Since at least 1996,
  2458. the tradition is to use a ‘#serial’ line for this.
  2459. A serial number should be a single line of the form
  2460. # serial VERSION
  2461. where VERSION is a version number containing only digits and dots.
  2462. Usually people use a single integer, and they increment it each time
  2463. they change the macro (hence the name of “serial”). Such a line should
  2464. appear in the M4 file before any macro definition.
  2465. The ‘#’ must be the first character on the line, and it is OK to have
  2466. extra words after the version, as in
  2467. #serial VERSION GARBAGE
  2468. Normally these serial numbers are completely ignored by ‘aclocal’ and
  2469. ‘autoconf’, like any genuine comment. However when using ‘aclocal’’s
  2470. ‘--install’ feature, these serial numbers will modify the way ‘aclocal’
  2471. selects the macros to install in the package: if two files with the same
  2472. basename exist in your search path, and if at least one of them uses a
  2473. ‘#serial’ line, ‘aclocal’ will ignore the file that has the older
  2474. ‘#serial’ line (or the file that has none).
  2475. Note that a serial number applies to a whole M4 file, not to any
  2476. macro it contains. A file can contains multiple macros, but only one
  2477. serial.
  2478. Here is a use case that illustrates the use of ‘--install’ and its
  2479. interaction with serial numbers. Let’s assume we maintain a package
  2480. called MyPackage, the ‘configure.ac’ of which requires a third-party
  2481. macro ‘AX_THIRD_PARTY’ defined in ‘/usr/share/aclocal/thirdparty.m4’ as
  2482. follows:
  2483. # serial 1
  2484. AC_DEFUN([AX_THIRD_PARTY], [...])
  2485. MyPackage uses an ‘m4/’ directory to store local macros as explained
  2486. in *note Local Macros::, and has
  2487. AC_CONFIG_MACRO_DIRS([m4])
  2488. in its ‘configure.ac’.
  2489. Initially the ‘m4/’ directory is empty. The first time we run
  2490. ‘aclocal --install’, it will notice that
  2491. • ‘configure.ac’ uses ‘AX_THIRD_PARTY’
  2492. • No local macros define ‘AX_THIRD_PARTY’
  2493. • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with
  2494. serial 1.
  2495. Because ‘/usr/share/aclocal/thirdparty.m4’ is a system-wide macro and
  2496. ‘aclocal’ was given the ‘--install’ option, it will copy this file in
  2497. ‘m4/thirdparty.m4’, and output an ‘aclocal.m4’ that contains
  2498. ‘m4_include([m4/thirdparty.m4])’.
  2499. The next time ‘aclocal --install’ is run, something different
  2500. happens. ‘aclocal’ notices that
  2501. • ‘configure.ac’ uses ‘AX_THIRD_PARTY’
  2502. • ‘m4/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with serial 1.
  2503. • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with
  2504. serial 1.
  2505. Because both files have the same serial number, ‘aclocal’ uses the first
  2506. it found in its search path order (*note Macro Search Path::).
  2507. ‘aclocal’ therefore ignores ‘/usr/share/aclocal/thirdparty.m4’ and
  2508. outputs an ‘aclocal.m4’ that contains ‘m4_include([m4/thirdparty.m4])’.
  2509. Local directories specified with ‘-I’ are always searched before
  2510. system-wide directories, so a local file will always be preferred to the
  2511. system-wide file in case of equal serial numbers.
  2512. Now suppose the system-wide third-party macro is changed. This can
  2513. happen if the package installing this macro is updated. Let’s suppose
  2514. the new macro has serial number 2. The next time ‘aclocal --install’ is
  2515. run the situation is the following:
  2516. • ‘configure.ac’ uses ‘AX_THIRD_PARTY’
  2517. • ‘m4/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with serial 1.
  2518. • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with
  2519. serial 2.
  2520. When ‘aclocal’ sees a greater serial number, it immediately forgets
  2521. anything it knows from files that have the same basename and a smaller
  2522. serial number. So after it has found ‘/usr/share/aclocal/thirdparty.m4’
  2523. with serial 2, ‘aclocal’ will proceed as if it had never seen
  2524. ‘m4/thirdparty.m4’. This brings us back to a situation similar to that
  2525. at the beginning of our example, where no local file defined the macro.
  2526. ‘aclocal’ will install the new version of the macro in
  2527. ‘m4/thirdparty.m4’, in this case overriding the old version. MyPackage
  2528. just had its macro updated as a side effect of running ‘aclocal’.
  2529. If you are leery of letting ‘aclocal’ update your local macro, you
  2530. can run ‘aclocal --diff’ to review the changes ‘aclocal --install’ would
  2531. perform on these macros.
  2532. Finally, note that the ‘--force’ option of ‘aclocal’ has absolutely
  2533. no effect on the files installed by ‘--install’. For instance, if you
  2534. have modified your local macros, do not expect ‘--install --force’ to
  2535. replace the local macros by their system-wide versions. If you want to
  2536. do so, simply erase the local macros you want to revert, and run
  2537. ‘aclocal --install’.
  2538. 
  2539. File: automake.info, Node: Future of aclocal, Prev: Serials, Up: aclocal Invocation
  2540. 6.3.6 The Future of ‘aclocal’
  2541. -----------------------------
  2542. ‘aclocal’ is expected to disappear. This feature really should not be
  2543. offered by Automake. Automake should focus on generating ‘Makefile’s;
  2544. dealing with M4 macros really is Autoconf’s job. The fact that some
  2545. people install Automake just to use ‘aclocal’, but do not use ‘automake’
  2546. otherwise is an indication of how that feature is misplaced.
  2547. The new implementation will probably be done slightly differently.
  2548. For instance, it could enforce the ‘m4/’-style layout discussed in *note
  2549. Local Macros::.
  2550. We have no idea when and how this will happen. This has been
  2551. discussed several times in the past, but someone still has to commit to
  2552. that non-trivial task.
  2553. From the user point of view, ‘aclocal’’s removal might turn out to be
  2554. painful. There is a simple precaution that you may take to make that
  2555. switch more seamless: never call ‘aclocal’ yourself. Keep this guy
  2556. under the exclusive control of ‘autoreconf’ and Automake’s rebuild
  2557. rules. Hopefully you won’t need to worry about things breaking, when
  2558. ‘aclocal’ disappears, because everything will have been taken care of.
  2559. If otherwise you used to call ‘aclocal’ directly yourself or from some
  2560. script, you will quickly notice the change.
  2561. Many packages come with a script called ‘bootstrap’ or ‘autogen.sh’,
  2562. that will just call ‘aclocal’, ‘libtoolize’, ‘gettextize’ or
  2563. ‘autopoint’, ‘autoconf’, ‘autoheader’, and ‘automake’ in the right
  2564. order. Actually this is precisely what ‘autoreconf’ can do for you. If
  2565. your package has such a ‘bootstrap’ or ‘autogen.sh’ script, consider
  2566. using ‘autoreconf’. That should simplify its logic a lot (less things
  2567. to maintain, yum!), it’s even likely you will not need the script
  2568. anymore, and more to the point you will not call ‘aclocal’ directly
  2569. anymore.
  2570. For the time being, third-party packages should continue to install
  2571. public macros into ‘/usr/share/aclocal/’. If ‘aclocal’ is replaced by
  2572. another tool it might make sense to rename the directory, but supporting
  2573. ‘/usr/share/aclocal/’ for backward compatibility should be really easy
  2574. provided all macros are properly written (*note Extending aclocal::).
  2575. 
  2576. File: automake.info, Node: Macros, Prev: aclocal Invocation, Up: configure
  2577. 6.4 Autoconf macros supplied with Automake
  2578. ==========================================
  2579. Automake ships with several Autoconf macros that you can use from your
  2580. ‘configure.ac’. When you use one of them it will be included by
  2581. ‘aclocal’ in ‘aclocal.m4’.
  2582. * Menu:
  2583. * Public Macros:: Macros that you can use.
  2584. * Obsolete Macros:: Macros that will soon be removed.
  2585. * Private Macros:: Macros that you should not use.
  2586. 
  2587. File: automake.info, Node: Public Macros, Next: Obsolete Macros, Up: Macros
  2588. 6.4.1 Public Macros
  2589. -------------------
  2590. ‘AM_INIT_AUTOMAKE([OPTIONS])’
  2591. Runs many macros required for proper operation of the generated
  2592. Makefiles.
  2593. Today, ‘AM_INIT_AUTOMAKE’ is called with a single argument: a
  2594. space-separated list of Automake options that should be applied to
  2595. every ‘Makefile.am’ in the tree. The effect is as if each option
  2596. were listed in ‘AUTOMAKE_OPTIONS’ (*note Options::).
  2597. This macro can also be called in another, _deprecated_ form:
  2598. ‘AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])’. In this form,
  2599. there are two required arguments: the package and the version
  2600. number. This usage is mostly obsolete because the PACKAGE and
  2601. VERSION can be obtained from Autoconf’s ‘AC_INIT’ macro. However,
  2602. differently from what happens for ‘AC_INIT’ invocations, this
  2603. ‘AM_INIT_AUTOMAKE’ invocation supports shell variables’ expansions
  2604. in the ‘PACKAGE’ and ‘VERSION’ arguments (which otherwise defaults,
  2605. respectively, to the ‘PACKAGE_TARNAME’ and ‘PACKAGE_VERSION’
  2606. defined via the ‘AC_INIT’ invocation; *note The ‘AC_INIT’ macro:
  2607. (autoconf)AC_INIT.); and this can be still be useful in some
  2608. selected situations. Our hope is that future Autoconf versions
  2609. will improve their support for package versions defined dynamically
  2610. at configure runtime; when (and if) this happens, support for the
  2611. two-args ‘AM_INIT_AUTOMAKE’ invocation will likely be removed from
  2612. Automake.
  2613. If your ‘configure.ac’ has:
  2614. AC_INIT([src/foo.c])
  2615. AM_INIT_AUTOMAKE([mumble], [1.5])
  2616. you should modernize it as follows:
  2617. AC_INIT([mumble], [1.5])
  2618. AC_CONFIG_SRCDIR([src/foo.c])
  2619. AM_INIT_AUTOMAKE
  2620. Note that if you’re upgrading your ‘configure.ac’ from an earlier
  2621. version of Automake, it is not always correct to simply move the
  2622. package and version arguments from ‘AM_INIT_AUTOMAKE’ directly to
  2623. ‘AC_INIT’, as in the example above. The first argument to
  2624. ‘AC_INIT’ should be the name of your package (e.g., ‘GNU
  2625. Automake’), not the tarball name (e.g., ‘automake’) that you used
  2626. to pass to ‘AM_INIT_AUTOMAKE’. Autoconf tries to derive a tarball
  2627. name from the package name, which should work for most but not all
  2628. package names. (If it doesn’t work for yours, you can use the
  2629. four-argument form of ‘AC_INIT’ to provide the tarball name
  2630. explicitly).
  2631. By default this macro ‘AC_DEFINE’’s ‘PACKAGE’ and ‘VERSION’. This
  2632. can be avoided by passing the ‘no-define’ option (*note List of
  2633. Automake options::):
  2634. AM_INIT_AUTOMAKE([no-define ...])
  2635. ‘AM_PATH_LISPDIR’
  2636. Searches for the program ‘emacs’, and, if found, sets the output
  2637. variable ‘lispdir’ to the full path to Emacs’ site-lisp directory.
  2638. Note that this test assumes the ‘emacs’ found to be a version that
  2639. supports Emacs Lisp (such as GNU Emacs or XEmacs). Other emacsen
  2640. can cause this test to hang (some, like old versions of MicroEmacs,
  2641. start up in interactive mode, requiring ‘C-x C-c’ to exit, which is
  2642. hardly obvious for a non-emacs user). In most cases, however, you
  2643. should be able to use ‘C-c’ to kill the test. In order to avoid
  2644. problems, you can set ‘EMACS’ to “no” in the environment, or use
  2645. the ‘--with-lispdir’ option to ‘configure’ to explicitly set the
  2646. correct path (if you’re sure you have an ‘emacs’ that supports
  2647. Emacs Lisp).
  2648. ‘AM_PROG_AR([ACT-IF-FAIL])’
  2649. You must use this macro when you use the archiver in your project,
  2650. if you want support for unusual archivers such as Microsoft ‘lib’.
  2651. The content of the optional argument is executed if the archiver
  2652. interface is not recognized; the default action is to abort
  2653. configure with an error message.
  2654. ‘AM_PROG_AS’
  2655. Use this macro when you have assembly code in your project. This
  2656. will choose the assembler for you (by default the C compiler) and
  2657. set ‘CCAS’, and will also set ‘CCASFLAGS’ if required.
  2658. ‘AM_PROG_CC_C_O’
  2659. This is an obsolescent macro that checks that the C compiler
  2660. supports the ‘-c’ and ‘-o’ options together. Note that, since
  2661. Automake 1.14, the ‘AC_PROG_CC’ is rewritten to implement such
  2662. checks itself, and thus the explicit use of ‘AM_PROG_CC_C_O’ should
  2663. no longer be required.
  2664. ‘AM_PROG_LEX’
  2665. Like ‘AC_PROG_LEX’ (*note Particular Program Checks:
  2666. (autoconf)Particular Programs.), but uses the ‘missing’ script on
  2667. systems that do not have ‘lex’. HP-UX 10 is one such system.
  2668. ‘AM_PROG_GCJ’
  2669. This macro finds the ‘gcj’ program or causes an error. It sets
  2670. ‘GCJ’ and ‘GCJFLAGS’. ‘gcj’ is the Java front-end to the GNU
  2671. Compiler Collection.
  2672. ‘AM_PROG_UPC([COMPILER-SEARCH-LIST])’
  2673. Find a compiler for Unified Parallel C and define the ‘UPC’
  2674. variable. The default COMPILER-SEARCH-LIST is ‘upcc upc’. This
  2675. macro will abort ‘configure’ if no Unified Parallel C compiler is
  2676. found.
  2677. ‘AM_MISSING_PROG(NAME, PROGRAM)’
  2678. Find a maintainer tool PROGRAM and define the NAME environment
  2679. variable with its location. If PROGRAM is not detected, then NAME
  2680. will instead invoke the ‘missing’ script, in order to give useful
  2681. advice to the user about the missing maintainer tool. *Note
  2682. maintainer-mode::, for more information on when the ‘missing’
  2683. script is appropriate.
  2684. ‘AM_SILENT_RULES’
  2685. Control the machinery for less verbose build output (*note Automake
  2686. Silent Rules::).
  2687. ‘AM_WITH_DMALLOC’
  2688. Add support for the Dmalloc package (http://dmalloc.com/). If the
  2689. user runs ‘configure’ with ‘--with-dmalloc’, then define
  2690. ‘WITH_DMALLOC’ and add ‘-ldmalloc’ to ‘LIBS’.
  2691. 
  2692. File: automake.info, Node: Obsolete Macros, Next: Private Macros, Prev: Public Macros, Up: Macros
  2693. 6.4.2 Obsolete Macros
  2694. ---------------------
  2695. Although using some of the following macros was required in past
  2696. releases, you should not use any of them in new code. _All these macros
  2697. will be removed in the next major Automake version_; if you are still
  2698. using them, running ‘autoupdate’ should adjust your ‘configure.ac’
  2699. automatically (*note Using ‘autoupdate’ to Modernize ‘configure.ac’:
  2700. (autoconf)autoupdate Invocation.). _Do it NOW!_
  2701. ‘AM_PROG_MKDIR_P’
  2702. From Automake 1.8 to 1.9.6 this macro used to define the output
  2703. variable ‘mkdir_p’ to one of ‘mkdir -p’, ‘install-sh -d’, or
  2704. ‘mkinstalldirs’.
  2705. Nowadays Autoconf provides a similar functionality with
  2706. ‘AC_PROG_MKDIR_P’ (*note Particular Program Checks:
  2707. (autoconf)Particular Programs.), however this defines the output
  2708. variable ‘MKDIR_P’ instead. In case you are still using the
  2709. ‘AM_PROG_MKDIR_P’ macro in your ‘configure.ac’, or its provided
  2710. variable ‘$(mkdir_p)’ in your ‘Makefile.am’, you are advised to
  2711. switch ASAP to the more modern Autoconf-provided interface instead;
  2712. both the macro and the variable might be removed in a future major
  2713. Automake release.
  2714. 
  2715. File: automake.info, Node: Private Macros, Prev: Obsolete Macros, Up: Macros
  2716. 6.4.3 Private Macros
  2717. --------------------
  2718. The following macros are private macros you should not call directly.
  2719. They are called by the other public macros when appropriate. Do not
  2720. rely on them, as they might be changed in a future version. Consider
  2721. them as implementation details; or better, do not consider them at all:
  2722. skip this section!
  2723. ‘_AM_DEPENDENCIES’
  2724. ‘AM_SET_DEPDIR’
  2725. ‘AM_DEP_TRACK’
  2726. ‘AM_OUTPUT_DEPENDENCY_COMMANDS’
  2727. These macros are used to implement Automake’s automatic dependency
  2728. tracking scheme. They are called automatically by Automake when
  2729. required, and there should be no need to invoke them manually.
  2730. ‘AM_MAKE_INCLUDE’
  2731. This macro is used to discover how the user’s ‘make’ handles
  2732. ‘include’ statements. This macro is automatically invoked when
  2733. needed; there should be no need to invoke it manually.
  2734. ‘AM_PROG_INSTALL_STRIP’
  2735. This is used to find a version of ‘install’ that can be used to
  2736. strip a program at installation time. This macro is automatically
  2737. included when required.
  2738. ‘AM_SANITY_CHECK’
  2739. This checks to make sure that a file created in the build directory
  2740. is newer than a file in the source directory. This can fail on
  2741. systems where the clock is set incorrectly. This macro is
  2742. automatically run from ‘AM_INIT_AUTOMAKE’.
  2743. 
  2744. File: automake.info, Node: Directories, Next: Programs, Prev: configure, Up: Top
  2745. 7 Directories
  2746. *************
  2747. For simple projects that distribute all files in the same directory it
  2748. is enough to have a single ‘Makefile.am’ that builds everything in
  2749. place.
  2750. In larger projects, it is common to organize files in different
  2751. directories, in a tree. For example, there could be a directory for the
  2752. program’s source, one for the testsuite, and one for the documentation;
  2753. or, for very large projects, there could be one directory per program,
  2754. per library or per module.
  2755. The traditional approach is to build these subdirectories
  2756. recursively, employing _make recursion_: each directory contains its own
  2757. ‘Makefile’, and when ‘make’ is run from the top-level directory, it
  2758. enters each subdirectory in turn, and invokes there a new ‘make’
  2759. instance to build the directory’s contents.
  2760. Because this approach is very widespread, Automake offers built-in
  2761. support for it. However, it is worth nothing that the use of make
  2762. recursion has its own serious issues and drawbacks, and that it’s well
  2763. possible to have packages with a multi directory layout that make little
  2764. or no use of such recursion (examples of such packages are GNU Bison and
  2765. GNU Automake itself); see also the *note Alternative:: section below.
  2766. * Menu:
  2767. * Subdirectories:: Building subdirectories recursively
  2768. * Conditional Subdirectories:: Conditionally not building directories
  2769. * Alternative:: Subdirectories without recursion
  2770. * Subpackages:: Nesting packages
  2771. 
  2772. File: automake.info, Node: Subdirectories, Next: Conditional Subdirectories, Up: Directories
  2773. 7.1 Recursing subdirectories
  2774. ============================
  2775. In packages using make recursion, the top level ‘Makefile.am’ must tell
  2776. Automake which subdirectories are to be built. This is done via the
  2777. ‘SUBDIRS’ variable.
  2778. The ‘SUBDIRS’ variable holds a list of subdirectories in which
  2779. building of various sorts can occur. The rules for many targets (e.g.,
  2780. ‘all’) in the generated ‘Makefile’ will run commands both locally and in
  2781. all specified subdirectories. Note that the directories listed in
  2782. ‘SUBDIRS’ are not required to contain ‘Makefile.am’s; only ‘Makefile’s
  2783. (after configuration). This allows inclusion of libraries from packages
  2784. that do not use Automake (such as ‘gettext’; see also *note Third-Party
  2785. Makefiles::).
  2786. In packages that use subdirectories, the top-level ‘Makefile.am’ is
  2787. often very short. For instance, here is the ‘Makefile.am’ from the GNU
  2788. Hello distribution:
  2789. EXTRA_DIST = BUGS ChangeLog.O README-alpha
  2790. SUBDIRS = doc intl po src tests
  2791. When Automake invokes ‘make’ in a subdirectory, it uses the value of
  2792. the ‘MAKE’ variable. It passes the value of the variable ‘AM_MAKEFLAGS’
  2793. to the ‘make’ invocation; this can be set in ‘Makefile.am’ if there are
  2794. flags you must always pass to ‘make’.
  2795. The directories mentioned in ‘SUBDIRS’ are usually direct children of
  2796. the current directory, each subdirectory containing its own
  2797. ‘Makefile.am’ with a ‘SUBDIRS’ pointing to deeper subdirectories.
  2798. Automake can be used to construct packages of arbitrary depth this way.
  2799. By default, Automake generates ‘Makefiles’ that work depth-first in
  2800. postfix order: the subdirectories are built before the current
  2801. directory. However, it is possible to change this ordering. You can do
  2802. this by putting ‘.’ into ‘SUBDIRS’. For instance, putting ‘.’ first
  2803. will cause a prefix ordering of directories.
  2804. Using
  2805. SUBDIRS = lib src . test
  2806. will cause ‘lib/’ to be built before ‘src/’, then the current directory
  2807. will be built, finally the ‘test/’ directory will be built. It is
  2808. customary to arrange test directories to be built after everything else
  2809. since they are meant to test what has been constructed.
  2810. In addition to the built-in recursive targets defined by Automake
  2811. (‘all’, ‘check’, etc.), the developer can also define his own recursive
  2812. targets. That is done by passing the names of such targets as arguments
  2813. to the m4 macro ‘AM_EXTRA_RECURSIVE_TARGETS’ in ‘configure.ac’.
  2814. Automake generates rules to handle the recursion for such targets; and
  2815. the developer can define real actions for them by defining corresponding
  2816. ‘-local’ targets.
  2817. % cat configure.ac
  2818. AC_INIT([pkg-name], [1.0]
  2819. AM_INIT_AUTOMAKE
  2820. AM_EXTRA_RECURSIVE_TARGETS([foo])
  2821. AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
  2822. AC_OUTPUT
  2823. % cat Makefile.am
  2824. SUBDIRS = sub
  2825. foo-local:
  2826. @echo This will be run by "make foo".
  2827. % cat sub/Makefile.am
  2828. SUBDIRS = src
  2829. % cat sub/src/Makefile.am
  2830. foo-local:
  2831. @echo This too will be run by a "make foo" issued either in
  2832. @echo the 'sub/src/' directory, the 'sub/' directory, or the
  2833. @echo top-level directory.
  2834. 
  2835. File: automake.info, Node: Conditional Subdirectories, Next: Alternative, Prev: Subdirectories, Up: Directories
  2836. 7.2 Conditional Subdirectories
  2837. ==============================
  2838. It is possible to define the ‘SUBDIRS’ variable conditionally if, like
  2839. in the case of GNU Inetutils, you want to only build a subset of the
  2840. entire package.
  2841. To illustrate how this works, let’s assume we have two directories
  2842. ‘src/’ and ‘opt/’. ‘src/’ should always be built, but we want to decide
  2843. in ‘configure’ whether ‘opt/’ will be built or not. (For this example
  2844. we will assume that ‘opt/’ should be built when the variable ‘$want_opt’
  2845. was set to ‘yes’.)
  2846. Running ‘make’ should thus recurse into ‘src/’ always, and then maybe
  2847. in ‘opt/’.
  2848. However ‘make dist’ should always recurse into both ‘src/’ and
  2849. ‘opt/’. Because ‘opt/’ should be distributed even if it is not needed
  2850. in the current configuration. This means ‘opt/Makefile’ should be
  2851. created _unconditionally_.
  2852. There are two ways to setup a project like this. You can use
  2853. Automake conditionals (*note Conditionals::) or use Autoconf ‘AC_SUBST’
  2854. variables (*note Setting Output Variables: (autoconf)Setting Output
  2855. Variables.). Using Automake conditionals is the preferred solution.
  2856. Before we illustrate these two possibilities, let’s introduce
  2857. ‘DIST_SUBDIRS’.
  2858. * Menu:
  2859. * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
  2860. * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
  2861. * Subdirectories with AC_SUBST:: Another way for conditional recursion
  2862. * Unconfigured Subdirectories:: Not even creating a ‘Makefile’
  2863. 
  2864. File: automake.info, Node: SUBDIRS vs DIST_SUBDIRS, Next: Subdirectories with AM_CONDITIONAL, Up: Conditional Subdirectories
  2865. 7.2.1 ‘SUBDIRS’ vs. ‘DIST_SUBDIRS’
  2866. ----------------------------------
  2867. Automake considers two sets of directories, defined by the variables
  2868. ‘SUBDIRS’ and ‘DIST_SUBDIRS’.
  2869. ‘SUBDIRS’ contains the subdirectories of the current directory that
  2870. must be built (*note Subdirectories::). It must be defined manually;
  2871. Automake will never guess a directory is to be built. As we will see in
  2872. the next two sections, it is possible to define it conditionally so that
  2873. some directory will be omitted from the build.
  2874. ‘DIST_SUBDIRS’ is used in rules that need to recurse in all
  2875. directories, even those that have been conditionally left out of the
  2876. build. Recall our example where we may not want to build subdirectory
  2877. ‘opt/’, but yet we want to distribute it? This is where ‘DIST_SUBDIRS’
  2878. comes into play: ‘opt’ may not appear in ‘SUBDIRS’, but it must appear
  2879. in ‘DIST_SUBDIRS’.
  2880. Precisely, ‘DIST_SUBDIRS’ is used by ‘make maintainer-clean’, ‘make
  2881. distclean’ and ‘make dist’. All other recursive rules use ‘SUBDIRS’.
  2882. If ‘SUBDIRS’ is defined conditionally using Automake conditionals,
  2883. Automake will define ‘DIST_SUBDIRS’ automatically from the possible
  2884. values of ‘SUBDIRS’ in all conditions.
  2885. If ‘SUBDIRS’ contains ‘AC_SUBST’ variables, ‘DIST_SUBDIRS’ will not
  2886. be defined correctly because Automake does not know the possible values
  2887. of these variables. In this case ‘DIST_SUBDIRS’ needs to be defined
  2888. manually.
  2889. 
  2890. File: automake.info, Node: Subdirectories with AM_CONDITIONAL, Next: Subdirectories with AC_SUBST, Prev: SUBDIRS vs DIST_SUBDIRS, Up: Conditional Subdirectories
  2891. 7.2.2 Subdirectories with ‘AM_CONDITIONAL’
  2892. ------------------------------------------
  2893. ‘configure’ should output the ‘Makefile’ for each directory and define a
  2894. condition into which ‘opt/’ should be built.
  2895. ...
  2896. AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
  2897. AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
  2898. ...
  2899. Then ‘SUBDIRS’ can be defined in the top-level ‘Makefile.am’ as
  2900. follows.
  2901. if COND_OPT
  2902. MAYBE_OPT = opt
  2903. endif
  2904. SUBDIRS = src $(MAYBE_OPT)
  2905. As you can see, running ‘make’ will rightly recurse into ‘src/’ and
  2906. maybe ‘opt/’.
  2907. As you can’t see, running ‘make dist’ will recurse into both ‘src/’
  2908. and ‘opt/’ directories because ‘make dist’, unlike ‘make all’, doesn’t
  2909. use the ‘SUBDIRS’ variable. It uses the ‘DIST_SUBDIRS’ variable.
  2910. In this case Automake will define ‘DIST_SUBDIRS = src opt’
  2911. automatically because it knows that ‘MAYBE_OPT’ can contain ‘opt’ in
  2912. some condition.
  2913. 
  2914. File: automake.info, Node: Subdirectories with AC_SUBST, Next: Unconfigured Subdirectories, Prev: Subdirectories with AM_CONDITIONAL, Up: Conditional Subdirectories
  2915. 7.2.3 Subdirectories with ‘AC_SUBST’
  2916. ------------------------------------
  2917. Another possibility is to define ‘MAYBE_OPT’ from ‘./configure’ using
  2918. ‘AC_SUBST’:
  2919. ...
  2920. if test "$want_opt" = yes; then
  2921. MAYBE_OPT=opt
  2922. else
  2923. MAYBE_OPT=
  2924. fi
  2925. AC_SUBST([MAYBE_OPT])
  2926. AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
  2927. ...
  2928. In this case the top-level ‘Makefile.am’ should look as follows.
  2929. SUBDIRS = src $(MAYBE_OPT)
  2930. DIST_SUBDIRS = src opt
  2931. The drawback is that since Automake cannot guess what the possible
  2932. values of ‘MAYBE_OPT’ are, it is necessary to define ‘DIST_SUBDIRS’.
  2933. 
  2934. File: automake.info, Node: Unconfigured Subdirectories, Prev: Subdirectories with AC_SUBST, Up: Conditional Subdirectories
  2935. 7.2.4 Unconfigured Subdirectories
  2936. ---------------------------------
  2937. The semantics of ‘DIST_SUBDIRS’ are often misunderstood by some users
  2938. that try to _configure and build_ subdirectories conditionally. Here by
  2939. configuring we mean creating the ‘Makefile’ (it might also involve
  2940. running a nested ‘configure’ script: this is a costly operation that
  2941. explains why people want to do it conditionally, but only the ‘Makefile’
  2942. is relevant to the discussion).
  2943. The above examples all assume that every ‘Makefile’ is created, even
  2944. in directories that are not going to be built. The simple reason is
  2945. that we want ‘make dist’ to distribute even the directories that are not
  2946. being built (e.g., platform-dependent code), hence ‘make dist’ must
  2947. recurse into the subdirectory, hence this directory must be configured
  2948. and appear in ‘DIST_SUBDIRS’.
  2949. Building packages that do not configure every subdirectory is a
  2950. tricky business, and we do not recommend it to the novice as it is easy
  2951. to produce an incomplete tarball by mistake. We will not discuss this
  2952. topic in depth here, yet for the adventurous here are a few rules to
  2953. remember.
  2954. • ‘SUBDIRS’ should always be a subset of ‘DIST_SUBDIRS’.
  2955. It makes little sense to have a directory in ‘SUBDIRS’ that is not
  2956. in ‘DIST_SUBDIRS’. Think of the former as a way to tell which
  2957. directories listed in the latter should be built.
  2958. • Any directory listed in ‘DIST_SUBDIRS’ and ‘SUBDIRS’ must be
  2959. configured.
  2960. I.e., the ‘Makefile’ must exists or the recursive ‘make’ rules will
  2961. not be able to process the directory.
  2962. • Any configured directory must be listed in ‘DIST_SUBDIRS’.
  2963. So that the cleaning rules remove the generated ‘Makefile’s. It
  2964. would be correct to see ‘DIST_SUBDIRS’ as a variable that lists all
  2965. the directories that have been configured.
  2966. In order to prevent recursion in some unconfigured directory you must
  2967. therefore ensure that this directory does not appear in ‘DIST_SUBDIRS’
  2968. (and ‘SUBDIRS’). For instance, if you define ‘SUBDIRS’ conditionally
  2969. using ‘AC_SUBST’ and do not define ‘DIST_SUBDIRS’ explicitly, it will be
  2970. default to ‘$(SUBDIRS)’; another possibility is to force ‘DIST_SUBDIRS =
  2971. $(SUBDIRS)’.
  2972. Of course, directories that are omitted from ‘DIST_SUBDIRS’ will not
  2973. be distributed unless you make other arrangements for this to happen
  2974. (for instance, always running ‘make dist’ in a configuration where all
  2975. directories are known to appear in ‘DIST_SUBDIRS’; or writing a
  2976. ‘dist-hook’ target to distribute these directories).
  2977. In few packages, unconfigured directories are not even expected to be
  2978. distributed. Although these packages do not require the aforementioned
  2979. extra arrangements, there is another pitfall. If the name of a
  2980. directory appears in ‘SUBDIRS’ or ‘DIST_SUBDIRS’, ‘automake’ will make
  2981. sure the directory exists. Consequently ‘automake’ cannot be run on
  2982. such a distribution when one directory has been omitted. One way to
  2983. avoid this check is to use the ‘AC_SUBST’ method to declare conditional
  2984. directories; since ‘automake’ does not know the values of ‘AC_SUBST’
  2985. variables it cannot ensure the corresponding directory exists.
  2986. 
  2987. File: automake.info, Node: Alternative, Next: Subpackages, Prev: Conditional Subdirectories, Up: Directories
  2988. 7.3 An Alternative Approach to Subdirectories
  2989. =============================================
  2990. If you’ve ever read Peter Miller’s excellent paper, Recursive Make
  2991. Considered Harmful (http://miller.emu.id.au/pmiller/books/rmch/), the
  2992. preceding sections on the use of make recursion will probably come as
  2993. unwelcome advice. For those who haven’t read the paper, Miller’s main
  2994. thesis is that recursive ‘make’ invocations are both slow and
  2995. error-prone.
  2996. Automake provides sufficient cross-directory support (1) to enable
  2997. you to write a single ‘Makefile.am’ for a complex multi-directory
  2998. package.
  2999. By default an installable file specified in a subdirectory will have
  3000. its directory name stripped before installation. For instance, in this
  3001. example, the header file will be installed as ‘$(includedir)/stdio.h’:
  3002. include_HEADERS = inc/stdio.h
  3003. However, the ‘nobase_’ prefix can be used to circumvent this path
  3004. stripping. In this example, the header file will be installed as
  3005. ‘$(includedir)/sys/types.h’:
  3006. nobase_include_HEADERS = sys/types.h
  3007. ‘nobase_’ should be specified first when used in conjunction with
  3008. either ‘dist_’ or ‘nodist_’ (*note Fine-grained Distribution Control::).
  3009. For instance:
  3010. nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
  3011. Finally, note that a variable using the ‘nobase_’ prefix can often be
  3012. replaced by several variables, one for each destination directory (*note
  3013. Uniform::). For instance, the last example could be rewritten as
  3014. follows:
  3015. imagesdir = $(pkgdatadir)/images
  3016. soundsdir = $(pkgdatadir)/sounds
  3017. dist_images_DATA = images/vortex.pgm
  3018. dist_sounds_DATA = sounds/whirl.ogg
  3019. This latter syntax makes it possible to change one destination directory
  3020. without changing the layout of the source tree.
  3021. Currently, ‘nobase_*_LTLIBRARIES’ are the only exception to this
  3022. rule, in that there is no particular installation order guarantee for an
  3023. otherwise equivalent set of variables without ‘nobase_’ prefix.
  3024. ---------- Footnotes ----------
  3025. (1) We believe. This work is new and there are probably warts.
  3026. *Note Introduction::, for information on reporting bugs.
  3027. 
  3028. File: automake.info, Node: Subpackages, Prev: Alternative, Up: Directories
  3029. 7.4 Nesting Packages
  3030. ====================
  3031. In the GNU Build System, packages can be nested to arbitrary depth.
  3032. This means that a package can embed other packages with their own
  3033. ‘configure’, ‘Makefile’s, etc.
  3034. These other packages should just appear as subdirectories of their
  3035. parent package. They must be listed in ‘SUBDIRS’ like other ordinary
  3036. directories. However the subpackage’s ‘Makefile’s should be output by
  3037. its own ‘configure’ script, not by the parent’s ‘configure’. This is
  3038. achieved using the ‘AC_CONFIG_SUBDIRS’ Autoconf macro (*note
  3039. AC_CONFIG_SUBDIRS: (autoconf)Subdirectories.).
  3040. Here is an example package for an ‘arm’ program that links with a
  3041. ‘hand’ library that is a nested package in subdirectory ‘hand/’.
  3042. ‘arm’’s ‘configure.ac’:
  3043. AC_INIT([arm], [1.0])
  3044. AC_CONFIG_AUX_DIR([.])
  3045. AM_INIT_AUTOMAKE
  3046. AC_PROG_CC
  3047. AC_CONFIG_FILES([Makefile])
  3048. # Call hand's ./configure script recursively.
  3049. AC_CONFIG_SUBDIRS([hand])
  3050. AC_OUTPUT
  3051. ‘arm’’s ‘Makefile.am’:
  3052. # Build the library in the hand subdirectory first.
  3053. SUBDIRS = hand
  3054. # Include hand's header when compiling this directory.
  3055. AM_CPPFLAGS = -I$(srcdir)/hand
  3056. bin_PROGRAMS = arm
  3057. arm_SOURCES = arm.c
  3058. # link with the hand library.
  3059. arm_LDADD = hand/libhand.a
  3060. Now here is ‘hand’’s ‘hand/configure.ac’:
  3061. AC_INIT([hand], [1.2])
  3062. AC_CONFIG_AUX_DIR([.])
  3063. AM_INIT_AUTOMAKE
  3064. AC_PROG_CC
  3065. AM_PROG_AR
  3066. AC_PROG_RANLIB
  3067. AC_CONFIG_FILES([Makefile])
  3068. AC_OUTPUT
  3069. and its ‘hand/Makefile.am’:
  3070. lib_LIBRARIES = libhand.a
  3071. libhand_a_SOURCES = hand.c
  3072. When ‘make dist’ is run from the top-level directory it will create
  3073. an archive ‘arm-1.0.tar.gz’ that contains the ‘arm’ code as well as the
  3074. ‘hand’ subdirectory. This package can be built and installed like any
  3075. ordinary package, with the usual ‘./configure && make && make install’
  3076. sequence (the ‘hand’ subpackage will be built and installed by the
  3077. process).
  3078. When ‘make dist’ is run from the hand directory, it will create a
  3079. self-contained ‘hand-1.2.tar.gz’ archive. So although it appears to be
  3080. embedded in another package, it can still be used separately.
  3081. The purpose of the ‘AC_CONFIG_AUX_DIR([.])’ instruction is to force
  3082. Automake and Autoconf to search for auxiliary scripts in the current
  3083. directory. For instance, this means that there will be two copies of
  3084. ‘install-sh’: one in the top-level of the ‘arm’ package, and another one
  3085. in the ‘hand/’ subdirectory for the ‘hand’ package.
  3086. The historical default is to search for these auxiliary scripts in
  3087. the parent directory and the grandparent directory. So if the
  3088. ‘AC_CONFIG_AUX_DIR([.])’ line was removed from ‘hand/configure.ac’, that
  3089. subpackage would share the auxiliary script of the ‘arm’ package. This
  3090. may looks like a gain in size (a few kilobytes), but it is actually a
  3091. loss of modularity as the ‘hand’ subpackage is no longer self-contained
  3092. (‘make dist’ in the subdirectory will not work anymore).
  3093. Packages that do not use Automake need more work to be integrated
  3094. this way. *Note Third-Party Makefiles::.
  3095. 
  3096. File: automake.info, Node: Programs, Next: Other Objects, Prev: Directories, Up: Top
  3097. 8 Building Programs and Libraries
  3098. *********************************
  3099. A large part of Automake’s functionality is dedicated to making it easy
  3100. to build programs and libraries.
  3101. * Menu:
  3102. * A Program:: Building a program
  3103. * A Library:: Building a library
  3104. * A Shared Library:: Building a Libtool library
  3105. * Program and Library Variables:: Variables controlling program and
  3106. library builds
  3107. * Default _SOURCES:: Default source files
  3108. * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
  3109. * Program Variables:: Variables used when building a program
  3110. * Yacc and Lex:: Yacc and Lex support
  3111. * C++ Support:: Compiling C++ sources
  3112. * Objective C Support:: Compiling Objective C sources
  3113. * Objective C++ Support:: Compiling Objective C++ sources
  3114. * Unified Parallel C Support:: Compiling Unified Parallel C sources
  3115. * Assembly Support:: Compiling assembly sources
  3116. * Fortran 77 Support:: Compiling Fortran 77 sources
  3117. * Fortran 9x Support:: Compiling Fortran 9x sources
  3118. * Java Support with gcj:: Compiling Java sources using gcj
  3119. * Vala Support:: Compiling Vala sources
  3120. * Support for Other Languages:: Compiling other languages
  3121. * Dependencies:: Automatic dependency tracking
  3122. * EXEEXT:: Support for executable extensions
  3123. 
  3124. File: automake.info, Node: A Program, Next: A Library, Up: Programs
  3125. 8.1 Building a program
  3126. ======================
  3127. In order to build a program, you need to tell Automake which sources are
  3128. part of it, and which libraries it should be linked with.
  3129. This section also covers conditional compilation of sources or
  3130. programs. Most of the comments about these also apply to libraries
  3131. (*note A Library::) and libtool libraries (*note A Shared Library::).
  3132. * Menu:
  3133. * Program Sources:: Defining program sources
  3134. * Linking:: Linking with libraries or extra objects
  3135. * Conditional Sources:: Handling conditional sources
  3136. * Conditional Programs:: Building a program conditionally
  3137. 
  3138. File: automake.info, Node: Program Sources, Next: Linking, Up: A Program
  3139. 8.1.1 Defining program sources
  3140. ------------------------------
  3141. In a directory containing source that gets built into a program (as
  3142. opposed to a library or a script), the ‘PROGRAMS’ primary is used.
  3143. Programs can be installed in ‘bindir’, ‘sbindir’, ‘libexecdir’,
  3144. ‘pkglibexecdir’, or not at all (‘noinst_’). They can also be built only
  3145. for ‘make check’, in which case the prefix is ‘check_’.
  3146. For instance:
  3147. bin_PROGRAMS = hello
  3148. In this simple case, the resulting ‘Makefile.in’ will contain code to
  3149. generate a program named ‘hello’.
  3150. Associated with each program are several assisting variables that are
  3151. named after the program. These variables are all optional, and have
  3152. reasonable defaults. Each variable, its use, and default is spelled out
  3153. below; we use the “hello” example throughout.
  3154. The variable ‘hello_SOURCES’ is used to specify which source files
  3155. get built into an executable:
  3156. hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
  3157. This causes each mentioned ‘.c’ file to be compiled into the
  3158. corresponding ‘.o’. Then all are linked to produce ‘hello’.
  3159. If ‘hello_SOURCES’ is not specified, then it defaults to the single
  3160. file ‘hello.c’ (*note Default _SOURCES::).
  3161. Multiple programs can be built in a single directory. Multiple
  3162. programs can share a single source file, which must be listed in each
  3163. ‘_SOURCES’ definition.
  3164. Header files listed in a ‘_SOURCES’ definition will be included in
  3165. the distribution but otherwise ignored. In case it isn’t obvious, you
  3166. should not include the header file generated by ‘configure’ in a
  3167. ‘_SOURCES’ variable; this file should not be distributed. Lex (‘.l’)
  3168. and Yacc (‘.y’) files can also be listed; see *note Yacc and Lex::.
  3169. 
  3170. File: automake.info, Node: Linking, Next: Conditional Sources, Prev: Program Sources, Up: A Program
  3171. 8.1.2 Linking the program
  3172. -------------------------
  3173. If you need to link against libraries that are not found by ‘configure’,
  3174. you can use ‘LDADD’ to do so. This variable is used to specify
  3175. additional objects or libraries to link with; it is inappropriate for
  3176. specifying specific linker flags, you should use ‘AM_LDFLAGS’ for this
  3177. purpose.
  3178. Sometimes, multiple programs are built in one directory but do not
  3179. share the same link-time requirements. In this case, you can use the
  3180. ‘PROG_LDADD’ variable (where PROG is the name of the program as it
  3181. appears in some ‘_PROGRAMS’ variable, and usually written in lowercase)
  3182. to override ‘LDADD’. If this variable exists for a given program, then
  3183. that program is not linked using ‘LDADD’.
  3184. For instance, in GNU cpio, ‘pax’, ‘cpio’ and ‘mt’ are linked against
  3185. the library ‘libcpio.a’. However, ‘rmt’ is built in the same directory,
  3186. and has no such link requirement. Also, ‘mt’ and ‘rmt’ are only built
  3187. on certain architectures. Here is what cpio’s ‘src/Makefile.am’ looks
  3188. like (abridged):
  3189. bin_PROGRAMS = cpio pax $(MT)
  3190. libexec_PROGRAMS = $(RMT)
  3191. EXTRA_PROGRAMS = mt rmt
  3192. LDADD = ../lib/libcpio.a $(INTLLIBS)
  3193. rmt_LDADD =
  3194. cpio_SOURCES = ...
  3195. pax_SOURCES = ...
  3196. mt_SOURCES = ...
  3197. rmt_SOURCES = ...
  3198. ‘PROG_LDADD’ is inappropriate for passing program-specific linker
  3199. flags (except for ‘-l’, ‘-L’, ‘-dlopen’ and ‘-dlpreopen’). So, use the
  3200. ‘PROG_LDFLAGS’ variable for this purpose.
  3201. It is also occasionally useful to have a program depend on some other
  3202. target that is not actually part of that program. This can be done
  3203. using either the ‘PROG_DEPENDENCIES’ or the ‘EXTRA_PROG_DEPENDENCIES’
  3204. variable. Each program depends on the contents both variables, but no
  3205. further interpretation is done.
  3206. Since these dependencies are associated to the link rule used to
  3207. create the programs they should normally list files used by the link
  3208. command. That is ‘*.$(OBJEXT)’, ‘*.a’, or ‘*.la’ files. In rare cases
  3209. you may need to add other kinds of files such as linker scripts, but
  3210. _listing a source file in ‘_DEPENDENCIES’ is wrong_. If some source
  3211. file needs to be built before all the components of a program are built,
  3212. consider using the ‘BUILT_SOURCES’ variable instead (*note Sources::).
  3213. If ‘PROG_DEPENDENCIES’ is not supplied, it is computed by Automake.
  3214. The automatically-assigned value is the contents of ‘PROG_LDADD’, with
  3215. most configure substitutions, ‘-l’, ‘-L’, ‘-dlopen’ and ‘-dlpreopen’
  3216. options removed. The configure substitutions that are left in are only
  3217. ‘$(LIBOBJS)’ and ‘$(ALLOCA)’; these are left because it is known that
  3218. they will not cause an invalid value for ‘PROG_DEPENDENCIES’ to be
  3219. generated.
  3220. *note Conditional Sources:: shows a situation where ‘_DEPENDENCIES’
  3221. may be used.
  3222. The ‘EXTRA_PROG_DEPENDENCIES’ may be useful for cases where you
  3223. merely want to augment the ‘automake’-generated ‘PROG_DEPENDENCIES’
  3224. rather than replacing it.
  3225. We recommend that you avoid using ‘-l’ options in ‘LDADD’ or
  3226. ‘PROG_LDADD’ when referring to libraries built by your package.
  3227. Instead, write the file name of the library explicitly as in the above
  3228. ‘cpio’ example. Use ‘-l’ only to list third-party libraries. If you
  3229. follow this rule, the default value of ‘PROG_DEPENDENCIES’ will list all
  3230. your local libraries and omit the other ones.
  3231. 
  3232. File: automake.info, Node: Conditional Sources, Next: Conditional Programs, Prev: Linking, Up: A Program
  3233. 8.1.3 Conditional compilation of sources
  3234. ----------------------------------------
  3235. You can’t put a configure substitution (e.g., ‘@FOO@’ or ‘$(FOO)’ where
  3236. ‘FOO’ is defined via ‘AC_SUBST’) into a ‘_SOURCES’ variable. The reason
  3237. for this is a bit hard to explain, but suffice to say that it simply
  3238. won’t work. Automake will give an error if you try to do this.
  3239. Fortunately there are two other ways to achieve the same result. One
  3240. is to use configure substitutions in ‘_LDADD’ variables, the other is to
  3241. use an Automake conditional.
  3242. Conditional Compilation using ‘_LDADD’ Substitutions
  3243. ....................................................
  3244. Automake must know all the source files that could possibly go into a
  3245. program, even if not all the files are built in every circumstance. Any
  3246. files that are only conditionally built should be listed in the
  3247. appropriate ‘EXTRA_’ variable. For instance, if ‘hello-linux.c’ or
  3248. ‘hello-generic.c’ were conditionally included in ‘hello’, the
  3249. ‘Makefile.am’ would contain:
  3250. bin_PROGRAMS = hello
  3251. hello_SOURCES = hello-common.c
  3252. EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
  3253. hello_LDADD = $(HELLO_SYSTEM)
  3254. hello_DEPENDENCIES = $(HELLO_SYSTEM)
  3255. You can then setup the ‘$(HELLO_SYSTEM)’ substitution from
  3256. ‘configure.ac’:
  3257. ...
  3258. case $host in
  3259. *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
  3260. *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
  3261. esac
  3262. AC_SUBST([HELLO_SYSTEM])
  3263. ...
  3264. In this case, the variable ‘HELLO_SYSTEM’ should be replaced by
  3265. either ‘hello-linux.o’ or ‘hello-generic.o’, and added to both
  3266. ‘hello_DEPENDENCIES’ and ‘hello_LDADD’ in order to be built and linked
  3267. in.
  3268. Conditional Compilation using Automake Conditionals
  3269. ...................................................
  3270. An often simpler way to compile source files conditionally is to use
  3271. Automake conditionals. For instance, you could use this ‘Makefile.am’
  3272. construct to build the same ‘hello’ example:
  3273. bin_PROGRAMS = hello
  3274. if LINUX
  3275. hello_SOURCES = hello-linux.c hello-common.c
  3276. else
  3277. hello_SOURCES = hello-generic.c hello-common.c
  3278. endif
  3279. In this case, ‘configure.ac’ should setup the ‘LINUX’ conditional
  3280. using ‘AM_CONDITIONAL’ (*note Conditionals::).
  3281. When using conditionals like this you don’t need to use the ‘EXTRA_’
  3282. variable, because Automake will examine the contents of each variable to
  3283. construct the complete list of source files.
  3284. If your program uses a lot of files, you will probably prefer a
  3285. conditional ‘+=’.
  3286. bin_PROGRAMS = hello
  3287. hello_SOURCES = hello-common.c
  3288. if LINUX
  3289. hello_SOURCES += hello-linux.c
  3290. else
  3291. hello_SOURCES += hello-generic.c
  3292. endif
  3293. 
  3294. File: automake.info, Node: Conditional Programs, Prev: Conditional Sources, Up: A Program
  3295. 8.1.4 Conditional compilation of programs
  3296. -----------------------------------------
  3297. Sometimes it is useful to determine the programs that are to be built at
  3298. configure time. For instance, GNU ‘cpio’ only builds ‘mt’ and ‘rmt’
  3299. under special circumstances. The means to achieve conditional
  3300. compilation of programs are the same you can use to compile source files
  3301. conditionally: substitutions or conditionals.
  3302. Conditional Programs using ‘configure’ Substitutions
  3303. ....................................................
  3304. In this case, you must notify Automake of all the programs that can
  3305. possibly be built, but at the same time cause the generated
  3306. ‘Makefile.in’ to use the programs specified by ‘configure’. This is
  3307. done by having ‘configure’ substitute values into each ‘_PROGRAMS’
  3308. definition, while listing all optionally built programs in
  3309. ‘EXTRA_PROGRAMS’.
  3310. bin_PROGRAMS = cpio pax $(MT)
  3311. libexec_PROGRAMS = $(RMT)
  3312. EXTRA_PROGRAMS = mt rmt
  3313. As explained in *note EXEEXT::, Automake will rewrite ‘bin_PROGRAMS’,
  3314. ‘libexec_PROGRAMS’, and ‘EXTRA_PROGRAMS’, appending ‘$(EXEEXT)’ to each
  3315. binary. Obviously it cannot rewrite values obtained at run-time through
  3316. ‘configure’ substitutions, therefore you should take care of appending
  3317. ‘$(EXEEXT)’ yourself, as in ‘AC_SUBST([MT], ['mt${EXEEXT}'])’.
  3318. Conditional Programs using Automake Conditionals
  3319. ................................................
  3320. You can also use Automake conditionals (*note Conditionals::) to select
  3321. programs to be built. In this case you don’t have to worry about
  3322. ‘$(EXEEXT)’ or ‘EXTRA_PROGRAMS’.
  3323. bin_PROGRAMS = cpio pax
  3324. if WANT_MT
  3325. bin_PROGRAMS += mt
  3326. endif
  3327. if WANT_RMT
  3328. libexec_PROGRAMS = rmt
  3329. endif
  3330. 
  3331. File: automake.info, Node: A Library, Next: A Shared Library, Prev: A Program, Up: Programs
  3332. 8.2 Building a library
  3333. ======================
  3334. Building a library is much like building a program. In this case, the
  3335. name of the primary is ‘LIBRARIES’. Libraries can be installed in
  3336. ‘libdir’ or ‘pkglibdir’.
  3337. *Note A Shared Library::, for information on how to build shared
  3338. libraries using libtool and the ‘LTLIBRARIES’ primary.
  3339. Each ‘_LIBRARIES’ variable is a list of the libraries to be built.
  3340. For instance, to create a library named ‘libcpio.a’, but not install it,
  3341. you would write:
  3342. noinst_LIBRARIES = libcpio.a
  3343. libcpio_a_SOURCES = ...
  3344. The sources that go into a library are determined exactly as they are
  3345. for programs, via the ‘_SOURCES’ variables. Note that the library name
  3346. is canonicalized (*note Canonicalization::), so the ‘_SOURCES’ variable
  3347. corresponding to ‘libcpio.a’ is ‘libcpio_a_SOURCES’, not
  3348. ‘libcpio.a_SOURCES’.
  3349. Extra objects can be added to a library using the ‘LIBRARY_LIBADD’
  3350. variable. This should be used for objects determined by ‘configure’.
  3351. Again from ‘cpio’:
  3352. libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
  3353. In addition, sources for extra objects that will not exist until
  3354. configure-time must be added to the ‘BUILT_SOURCES’ variable (*note
  3355. Sources::).
  3356. Building a static library is done by compiling all object files, then
  3357. by invoking ‘$(AR) $(ARFLAGS)’ followed by the name of the library and
  3358. the list of objects, and finally by calling ‘$(RANLIB)’ on that library.
  3359. You should call ‘AC_PROG_RANLIB’ from your ‘configure.ac’ to define
  3360. ‘RANLIB’ (Automake will complain otherwise). You should also call
  3361. ‘AM_PROG_AR’ to define ‘AR’, in order to support unusual archivers such
  3362. as Microsoft lib. ‘ARFLAGS’ will default to ‘cru’; you can override
  3363. this variable by setting it in your ‘Makefile.am’ or by ‘AC_SUBST’ing it
  3364. from your ‘configure.ac’. You can override the ‘AR’ variable by
  3365. defining a per-library ‘maude_AR’ variable (*note Program and Library
  3366. Variables::).
  3367. Be careful when selecting library components conditionally. Because
  3368. building an empty library is not portable, you should ensure that any
  3369. library always contains at least one object.
  3370. To use a static library when building a program, add it to ‘LDADD’
  3371. for this program. In the following example, the program ‘cpio’ is
  3372. statically linked with the library ‘libcpio.a’.
  3373. noinst_LIBRARIES = libcpio.a
  3374. libcpio_a_SOURCES = ...
  3375. bin_PROGRAMS = cpio
  3376. cpio_SOURCES = cpio.c ...
  3377. cpio_LDADD = libcpio.a
  3378. 
  3379. File: automake.info, Node: A Shared Library, Next: Program and Library Variables, Prev: A Library, Up: Programs
  3380. 8.3 Building a Shared Library
  3381. =============================
  3382. Building shared libraries portably is a relatively complex matter. For
  3383. this reason, GNU Libtool (*note Introduction: (libtool)Top.) was created
  3384. to help build shared libraries in a platform-independent way.
  3385. * Menu:
  3386. * Libtool Concept:: Introducing Libtool
  3387. * Libtool Libraries:: Declaring Libtool Libraries
  3388. * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
  3389. * Conditional Libtool Sources:: Choosing Library Sources Conditionally
  3390. * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
  3391. * Libtool Modules:: Building Libtool Modules
  3392. * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
  3393. * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
  3394. * Libtool Issues:: Common Issues Related to Libtool’s Use
  3395. 
  3396. File: automake.info, Node: Libtool Concept, Next: Libtool Libraries, Up: A Shared Library
  3397. 8.3.1 The Libtool Concept
  3398. -------------------------
  3399. Libtool abstracts shared and static libraries into a unified concept
  3400. henceforth called “libtool libraries”. Libtool libraries are files
  3401. using the ‘.la’ suffix, and can designate a static library, a shared
  3402. library, or maybe both. Their exact nature cannot be determined until
  3403. ‘./configure’ is run: not all platforms support all kinds of libraries,
  3404. and users can explicitly select which libraries should be built.
  3405. (However the package’s maintainers can tune the default, *note The
  3406. ‘AC_PROG_LIBTOOL’ macro: (libtool)AC_PROG_LIBTOOL.)
  3407. Because object files for shared and static libraries must be compiled
  3408. differently, libtool is also used during compilation. Object files
  3409. built by libtool are called “libtool objects”: these are files using the
  3410. ‘.lo’ suffix. Libtool libraries are built from these libtool objects.
  3411. You should not assume anything about the structure of ‘.la’ or ‘.lo’
  3412. files and how libtool constructs them: this is libtool’s concern, and
  3413. the last thing one wants is to learn about libtool’s guts. However the
  3414. existence of these files matters, because they are used as targets and
  3415. dependencies in ‘Makefile’s rules when building libtool libraries.
  3416. There are situations where you may have to refer to these, for instance
  3417. when expressing dependencies for building source files conditionally
  3418. (*note Conditional Libtool Sources::).
  3419. People considering writing a plug-in system, with dynamically loaded
  3420. modules, should look into ‘libltdl’: libtool’s dlopening library (*note
  3421. Using libltdl: (libtool)Using libltdl.). This offers a portable
  3422. dlopening facility to load libtool libraries dynamically, and can also
  3423. achieve static linking where unavoidable.
  3424. Before we discuss how to use libtool with Automake in details, it
  3425. should be noted that the libtool manual also has a section about how to
  3426. use Automake with libtool (*note Using Automake with Libtool:
  3427. (libtool)Using Automake.).
  3428. 
  3429. File: automake.info, Node: Libtool Libraries, Next: Conditional Libtool Libraries, Prev: Libtool Concept, Up: A Shared Library
  3430. 8.3.2 Building Libtool Libraries
  3431. --------------------------------
  3432. Automake uses libtool to build libraries declared with the ‘LTLIBRARIES’
  3433. primary. Each ‘_LTLIBRARIES’ variable is a list of libtool libraries to
  3434. build. For instance, to create a libtool library named ‘libgettext.la’,
  3435. and install it in ‘libdir’, write:
  3436. lib_LTLIBRARIES = libgettext.la
  3437. libgettext_la_SOURCES = gettext.c gettext.h ...
  3438. Automake predefines the variable ‘pkglibdir’, so you can use
  3439. ‘pkglib_LTLIBRARIES’ to install libraries in ‘$(libdir)/@PACKAGE@/’.
  3440. If ‘gettext.h’ is a public header file that needs to be installed in
  3441. order for people to use the library, it should be declared using a
  3442. ‘_HEADERS’ variable, not in ‘libgettext_la_SOURCES’. Headers listed in
  3443. the latter should be internal headers that are not part of the public
  3444. interface.
  3445. lib_LTLIBRARIES = libgettext.la
  3446. libgettext_la_SOURCES = gettext.c ...
  3447. include_HEADERS = gettext.h ...
  3448. A package can build and install such a library along with other
  3449. programs that use it. This dependency should be specified using
  3450. ‘LDADD’. The following example builds a program named ‘hello’ that is
  3451. linked with ‘libgettext.la’.
  3452. lib_LTLIBRARIES = libgettext.la
  3453. libgettext_la_SOURCES = gettext.c ...
  3454. bin_PROGRAMS = hello
  3455. hello_SOURCES = hello.c ...
  3456. hello_LDADD = libgettext.la
  3457. Whether ‘hello’ is statically or dynamically linked with ‘libgettext.la’
  3458. is not yet known: this will depend on the configuration of libtool and
  3459. the capabilities of the host.
  3460. 
  3461. File: automake.info, Node: Conditional Libtool Libraries, Next: Conditional Libtool Sources, Prev: Libtool Libraries, Up: A Shared Library
  3462. 8.3.3 Building Libtool Libraries Conditionally
  3463. ----------------------------------------------
  3464. Like conditional programs (*note Conditional Programs::), there are two
  3465. main ways to build conditional libraries: using Automake conditionals or
  3466. using Autoconf ‘AC_SUBST’itutions.
  3467. The important implementation detail you have to be aware of is that
  3468. the place where a library will be installed matters to libtool: it needs
  3469. to be indicated _at link-time_ using the ‘-rpath’ option.
  3470. For libraries whose destination directory is known when Automake
  3471. runs, Automake will automatically supply the appropriate ‘-rpath’ option
  3472. to libtool. This is the case for libraries listed explicitly in some
  3473. installable ‘_LTLIBRARIES’ variables such as ‘lib_LTLIBRARIES’.
  3474. However, for libraries determined at configure time (and thus
  3475. mentioned in ‘EXTRA_LTLIBRARIES’), Automake does not know the final
  3476. installation directory. For such libraries you must add the ‘-rpath’
  3477. option to the appropriate ‘_LDFLAGS’ variable by hand.
  3478. The examples below illustrate the differences between these two
  3479. methods.
  3480. Here is an example where ‘WANTEDLIBS’ is an ‘AC_SUBST’ed variable set
  3481. at ‘./configure’-time to either ‘libfoo.la’, ‘libbar.la’, both, or none.
  3482. Although ‘$(WANTEDLIBS)’ appears in the ‘lib_LTLIBRARIES’, Automake
  3483. cannot guess it relates to ‘libfoo.la’ or ‘libbar.la’ at the time it
  3484. creates the link rule for these two libraries. Therefore the ‘-rpath’
  3485. argument must be explicitly supplied.
  3486. EXTRA_LTLIBRARIES = libfoo.la libbar.la
  3487. lib_LTLIBRARIES = $(WANTEDLIBS)
  3488. libfoo_la_SOURCES = foo.c ...
  3489. libfoo_la_LDFLAGS = -rpath '$(libdir)'
  3490. libbar_la_SOURCES = bar.c ...
  3491. libbar_la_LDFLAGS = -rpath '$(libdir)'
  3492. Here is how the same ‘Makefile.am’ would look using Automake
  3493. conditionals named ‘WANT_LIBFOO’ and ‘WANT_LIBBAR’. Now Automake is
  3494. able to compute the ‘-rpath’ setting itself, because it’s clear that
  3495. both libraries will end up in ‘$(libdir)’ if they are installed.
  3496. lib_LTLIBRARIES =
  3497. if WANT_LIBFOO
  3498. lib_LTLIBRARIES += libfoo.la
  3499. endif
  3500. if WANT_LIBBAR
  3501. lib_LTLIBRARIES += libbar.la
  3502. endif
  3503. libfoo_la_SOURCES = foo.c ...
  3504. libbar_la_SOURCES = bar.c ...
  3505. 
  3506. File: automake.info, Node: Conditional Libtool Sources, Next: Libtool Convenience Libraries, Prev: Conditional Libtool Libraries, Up: A Shared Library
  3507. 8.3.4 Libtool Libraries with Conditional Sources
  3508. ------------------------------------------------
  3509. Conditional compilation of sources in a library can be achieved in the
  3510. same way as conditional compilation of sources in a program (*note
  3511. Conditional Sources::). The only difference is that ‘_LIBADD’ should be
  3512. used instead of ‘_LDADD’ and that it should mention libtool objects
  3513. (‘.lo’ files).
  3514. So, to mimic the ‘hello’ example from *note Conditional Sources::, we
  3515. could build a ‘libhello.la’ library using either ‘hello-linux.c’ or
  3516. ‘hello-generic.c’ with the following ‘Makefile.am’.
  3517. lib_LTLIBRARIES = libhello.la
  3518. libhello_la_SOURCES = hello-common.c
  3519. EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
  3520. libhello_la_LIBADD = $(HELLO_SYSTEM)
  3521. libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
  3522. And make sure ‘configure’ defines ‘HELLO_SYSTEM’ as either
  3523. ‘hello-linux.lo’ or ‘hello-generic.lo’.
  3524. Or we could simply use an Automake conditional as follows.
  3525. lib_LTLIBRARIES = libhello.la
  3526. libhello_la_SOURCES = hello-common.c
  3527. if LINUX
  3528. libhello_la_SOURCES += hello-linux.c
  3529. else
  3530. libhello_la_SOURCES += hello-generic.c
  3531. endif
  3532. 
  3533. File: automake.info, Node: Libtool Convenience Libraries, Next: Libtool Modules, Prev: Conditional Libtool Sources, Up: A Shared Library
  3534. 8.3.5 Libtool Convenience Libraries
  3535. -----------------------------------
  3536. Sometimes you want to build libtool libraries that should not be
  3537. installed. These are called “libtool convenience libraries” and are
  3538. typically used to encapsulate many sublibraries, later gathered into one
  3539. big installed library.
  3540. Libtool convenience libraries are declared by directory-less
  3541. variables such as ‘noinst_LTLIBRARIES’, ‘check_LTLIBRARIES’, or even
  3542. ‘EXTRA_LTLIBRARIES’. Unlike installed libtool libraries they do not
  3543. need an ‘-rpath’ flag at link time (actually this is the only
  3544. difference).
  3545. Convenience libraries listed in ‘noinst_LTLIBRARIES’ are always
  3546. built. Those listed in ‘check_LTLIBRARIES’ are built only upon ‘make
  3547. check’. Finally, libraries listed in ‘EXTRA_LTLIBRARIES’ are never
  3548. built explicitly: Automake outputs rules to build them, but if the
  3549. library does not appear as a Makefile dependency anywhere it won’t be
  3550. built (this is why ‘EXTRA_LTLIBRARIES’ is used for conditional
  3551. compilation).
  3552. Here is a sample setup merging libtool convenience libraries from
  3553. subdirectories into one main ‘libtop.la’ library.
  3554. # -- Top-level Makefile.am --
  3555. SUBDIRS = sub1 sub2 ...
  3556. lib_LTLIBRARIES = libtop.la
  3557. libtop_la_SOURCES =
  3558. libtop_la_LIBADD = \
  3559. sub1/libsub1.la \
  3560. sub2/libsub2.la \
  3561. ...
  3562. # -- sub1/Makefile.am --
  3563. noinst_LTLIBRARIES = libsub1.la
  3564. libsub1_la_SOURCES = ...
  3565. # -- sub2/Makefile.am --
  3566. # showing nested convenience libraries
  3567. SUBDIRS = sub2.1 sub2.2 ...
  3568. noinst_LTLIBRARIES = libsub2.la
  3569. libsub2_la_SOURCES =
  3570. libsub2_la_LIBADD = \
  3571. sub21/libsub21.la \
  3572. sub22/libsub22.la \
  3573. ...
  3574. When using such setup, beware that ‘automake’ will assume ‘libtop.la’
  3575. is to be linked with the C linker. This is because ‘libtop_la_SOURCES’
  3576. is empty, so ‘automake’ picks C as default language. If
  3577. ‘libtop_la_SOURCES’ was not empty, ‘automake’ would select the linker as
  3578. explained in *note How the Linker is Chosen::.
  3579. If one of the sublibraries contains non-C source, it is important
  3580. that the appropriate linker be chosen. One way to achieve this is to
  3581. pretend that there is such a non-C file among the sources of the
  3582. library, thus forcing ‘automake’ to select the appropriate linker. Here
  3583. is the top-level ‘Makefile’ of our example updated to force C++ linking.
  3584. SUBDIRS = sub1 sub2 ...
  3585. lib_LTLIBRARIES = libtop.la
  3586. libtop_la_SOURCES =
  3587. # Dummy C++ source to cause C++ linking.
  3588. nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
  3589. libtop_la_LIBADD = \
  3590. sub1/libsub1.la \
  3591. sub2/libsub2.la \
  3592. ...
  3593. ‘EXTRA_*_SOURCES’ variables are used to keep track of source files
  3594. that might be compiled (this is mostly useful when doing conditional
  3595. compilation using ‘AC_SUBST’, *note Conditional Libtool Sources::), and
  3596. the ‘nodist_’ prefix means the listed sources are not to be distributed
  3597. (*note Program and Library Variables::). In effect the file ‘dummy.cxx’
  3598. does not need to exist in the source tree. Of course if you have some
  3599. real source file to list in ‘libtop_la_SOURCES’ there is no point in
  3600. cheating with ‘nodist_EXTRA_libtop_la_SOURCES’.
  3601. 
  3602. File: automake.info, Node: Libtool Modules, Next: Libtool Flags, Prev: Libtool Convenience Libraries, Up: A Shared Library
  3603. 8.3.6 Libtool Modules
  3604. ---------------------
  3605. These are libtool libraries meant to be dlopened. They are indicated to
  3606. libtool by passing ‘-module’ at link-time.
  3607. pkglib_LTLIBRARIES = mymodule.la
  3608. mymodule_la_SOURCES = doit.c
  3609. mymodule_la_LDFLAGS = -module
  3610. Ordinarily, Automake requires that a library’s name start with ‘lib’.
  3611. However, when building a dynamically loadable module you might wish to
  3612. use a "nonstandard" name. Automake will not complain about such
  3613. nonstandard names if it knows the library being built is a libtool
  3614. module, i.e., if ‘-module’ explicitly appears in the library’s
  3615. ‘_LDFLAGS’ variable (or in the common ‘AM_LDFLAGS’ variable when no
  3616. per-library ‘_LDFLAGS’ variable is defined).
  3617. As always, ‘AC_SUBST’ variables are black boxes to Automake since
  3618. their values are not yet known when ‘automake’ is run. Therefore if
  3619. ‘-module’ is set via such a variable, Automake cannot notice it and will
  3620. proceed as if the library was an ordinary libtool library, with strict
  3621. naming.
  3622. If ‘mymodule_la_SOURCES’ is not specified, then it defaults to the
  3623. single file ‘mymodule.c’ (*note Default _SOURCES::).
  3624. 
  3625. File: automake.info, Node: Libtool Flags, Next: LTLIBOBJS, Prev: Libtool Modules, Up: A Shared Library
  3626. 8.3.7 ‘_LIBADD’, ‘_LDFLAGS’, and ‘_LIBTOOLFLAGS’
  3627. ------------------------------------------------
  3628. As shown in previous sections, the ‘LIBRARY_LIBADD’ variable should be
  3629. used to list extra libtool objects (‘.lo’ files) or libtool libraries
  3630. (‘.la’) to add to LIBRARY.
  3631. The ‘LIBRARY_LDFLAGS’ variable is the place to list additional
  3632. libtool linking flags, such as ‘-version-info’, ‘-static’, and a lot
  3633. more. *Note Link mode: (libtool)Link mode.
  3634. The ‘libtool’ command has two kinds of options: mode-specific options
  3635. and generic options. Mode-specific options such as the aforementioned
  3636. linking flags should be lumped with the other flags passed to the tool
  3637. invoked by ‘libtool’ (hence the use of ‘LIBRARY_LDFLAGS’ for libtool
  3638. linking flags). Generic options include ‘--tag=TAG’ and ‘--silent’
  3639. (*note Invoking ‘libtool’: (libtool)Invoking libtool. for more options)
  3640. should appear before the mode selection on the command line; in
  3641. ‘Makefile.am’s they should be listed in the ‘LIBRARY_LIBTOOLFLAGS’
  3642. variable.
  3643. If ‘LIBRARY_LIBTOOLFLAGS’ is not defined, then the variable
  3644. ‘AM_LIBTOOLFLAGS’ is used instead.
  3645. These flags are passed to libtool after the ‘--tag=TAG’ option
  3646. computed by Automake (if any), so ‘LIBRARY_LIBTOOLFLAGS’ (or
  3647. ‘AM_LIBTOOLFLAGS’) is a good place to override or supplement the
  3648. ‘--tag=TAG’ setting.
  3649. The libtool rules also use a ‘LIBTOOLFLAGS’ variable that should not
  3650. be set in ‘Makefile.am’: this is a user variable (*note Flag Variables
  3651. Ordering::. It allows users to run ‘make LIBTOOLFLAGS=--silent’, for
  3652. instance. Note that the verbosity of ‘libtool’ can also be influenced
  3653. by the Automake support for silent rules (*note Automake Silent
  3654. Rules::).
  3655. 
  3656. File: automake.info, Node: LTLIBOBJS, Next: Libtool Issues, Prev: Libtool Flags, Up: A Shared Library
  3657. 8.3.8 ‘LTLIBOBJS’ and ‘LTALLOCA’
  3658. --------------------------------
  3659. Where an ordinary library might include ‘$(LIBOBJS)’ or ‘$(ALLOCA)’
  3660. (*note LIBOBJS::), a libtool library must use ‘$(LTLIBOBJS)’ or
  3661. ‘$(LTALLOCA)’. This is required because the object files that libtool
  3662. operates on do not necessarily end in ‘.o’.
  3663. Nowadays, the computation of ‘LTLIBOBJS’ from ‘LIBOBJS’ is performed
  3664. automatically by Autoconf (*note ‘AC_LIBOBJ’ vs. ‘LIBOBJS’:
  3665. (autoconf)AC_LIBOBJ vs LIBOBJS.).
  3666. 
  3667. File: automake.info, Node: Libtool Issues, Prev: LTLIBOBJS, Up: A Shared Library
  3668. 8.3.9 Common Issues Related to Libtool’s Use
  3669. --------------------------------------------
  3670. * Menu:
  3671. * Error required file ltmain.sh not found:: The need to run libtoolize
  3672. * Objects created both with libtool and without:: Avoid a specific build race
  3673. 
  3674. File: automake.info, Node: Error required file ltmain.sh not found, Next: Objects created both with libtool and without, Up: Libtool Issues
  3675. 8.3.9.1 Error: ‘required file `./ltmain.sh' not found’
  3676. ......................................................
  3677. Libtool comes with a tool called ‘libtoolize’ that will install
  3678. libtool’s supporting files into a package. Running this command will
  3679. install ‘ltmain.sh’. You should execute it before ‘aclocal’ and
  3680. ‘automake’.
  3681. People upgrading old packages to newer autotools are likely to face
  3682. this issue because older Automake versions used to call ‘libtoolize’.
  3683. Therefore old build scripts do not call ‘libtoolize’.
  3684. Since Automake 1.6, it has been decided that running ‘libtoolize’ was
  3685. none of Automake’s business. Instead, that functionality has been moved
  3686. into the ‘autoreconf’ command (*note Using ‘autoreconf’:
  3687. (autoconf)autoreconf Invocation.). If you do not want to remember what
  3688. to run and when, just learn the ‘autoreconf’ command. Hopefully,
  3689. replacing existing ‘bootstrap’ or ‘autogen.sh’ scripts by a call to
  3690. ‘autoreconf’ should also free you from any similar incompatible change
  3691. in the future.
  3692. 
  3693. File: automake.info, Node: Objects created both with libtool and without, Prev: Error required file ltmain.sh not found, Up: Libtool Issues
  3694. 8.3.9.2 Objects ‘created with both libtool and without’
  3695. .......................................................
  3696. Sometimes, the same source file is used both to build a libtool library
  3697. and to build another non-libtool target (be it a program or another
  3698. library).
  3699. Let’s consider the following ‘Makefile.am’.
  3700. bin_PROGRAMS = prog
  3701. prog_SOURCES = prog.c foo.c ...
  3702. lib_LTLIBRARIES = libfoo.la
  3703. libfoo_la_SOURCES = foo.c ...
  3704. (In this trivial case the issue could be avoided by linking ‘libfoo.la’
  3705. with ‘prog’ instead of listing ‘foo.c’ in ‘prog_SOURCES’. But let’s
  3706. assume we really want to keep ‘prog’ and ‘libfoo.la’ separate.)
  3707. Technically, it means that we should build ‘foo.$(OBJEXT)’ for
  3708. ‘prog’, and ‘foo.lo’ for ‘libfoo.la’. The problem is that in the course
  3709. of creating ‘foo.lo’, libtool may erase (or replace) ‘foo.$(OBJEXT)’,
  3710. and this cannot be avoided.
  3711. Therefore, when Automake detects this situation it will complain with
  3712. a message such as
  3713. object 'foo.$(OBJEXT)' created both with libtool and without
  3714. A workaround for this issue is to ensure that these two objects get
  3715. different basenames. As explained in *note Renamed Objects::, this
  3716. happens automatically when per-targets flags are used.
  3717. bin_PROGRAMS = prog
  3718. prog_SOURCES = prog.c foo.c ...
  3719. prog_CFLAGS = $(AM_CFLAGS)
  3720. lib_LTLIBRARIES = libfoo.la
  3721. libfoo_la_SOURCES = foo.c ...
  3722. Adding ‘prog_CFLAGS = $(AM_CFLAGS)’ is almost a no-op, because when the
  3723. ‘prog_CFLAGS’ is defined, it is used instead of ‘AM_CFLAGS’. However as
  3724. a side effect it will cause ‘prog.c’ and ‘foo.c’ to be compiled as
  3725. ‘prog-prog.$(OBJEXT)’ and ‘prog-foo.$(OBJEXT)’, which solves the issue.
  3726. 
  3727. File: automake.info, Node: Program and Library Variables, Next: Default _SOURCES, Prev: A Shared Library, Up: Programs
  3728. 8.4 Program and Library Variables
  3729. =================================
  3730. Associated with each program is a collection of variables that can be
  3731. used to modify how that program is built. There is a similar list of
  3732. such variables for each library. The canonical name of the program (or
  3733. library) is used as a base for naming these variables.
  3734. In the list below, we use the name “maude” to refer to the program or
  3735. library. In your ‘Makefile.am’ you would replace this with the
  3736. canonical name of your program. This list also refers to “maude” as a
  3737. program, but in general the same rules apply for both static and dynamic
  3738. libraries; the documentation below notes situations where programs and
  3739. libraries differ.
  3740. ‘maude_SOURCES’
  3741. This variable, if it exists, lists all the source files that are
  3742. compiled to build the program. These files are added to the
  3743. distribution by default. When building the program, Automake will
  3744. cause each source file to be compiled to a single ‘.o’ file (or
  3745. ‘.lo’ when using libtool). Normally these object files are named
  3746. after the source file, but other factors can change this. If a
  3747. file in the ‘_SOURCES’ variable has an unrecognized extension,
  3748. Automake will do one of two things with it. If a suffix rule
  3749. exists for turning files with the unrecognized extension into ‘.o’
  3750. files, then ‘automake’ will treat this file as it will any other
  3751. source file (*note Support for Other Languages::). Otherwise, the
  3752. file will be ignored as though it were a header file.
  3753. The prefixes ‘dist_’ and ‘nodist_’ can be used to control whether
  3754. files listed in a ‘_SOURCES’ variable are distributed. ‘dist_’ is
  3755. redundant, as sources are distributed by default, but it can be
  3756. specified for clarity if desired.
  3757. It is possible to have both ‘dist_’ and ‘nodist_’ variants of a
  3758. given ‘_SOURCES’ variable at once; this lets you easily distribute
  3759. some files and not others, for instance:
  3760. nodist_maude_SOURCES = nodist.c
  3761. dist_maude_SOURCES = dist-me.c
  3762. By default the output file (on Unix systems, the ‘.o’ file) will be
  3763. put into the current build directory. However, if the option
  3764. ‘subdir-objects’ is in effect in the current directory then the
  3765. ‘.o’ file will be put into the subdirectory named after the source
  3766. file. For instance, with ‘subdir-objects’ enabled,
  3767. ‘sub/dir/file.c’ will be compiled to ‘sub/dir/file.o’. Some people
  3768. prefer this mode of operation. You can specify ‘subdir-objects’ in
  3769. ‘AUTOMAKE_OPTIONS’ (*note Options::).
  3770. ‘EXTRA_maude_SOURCES’
  3771. Automake needs to know the list of files you intend to compile
  3772. _statically_. For one thing, this is the only way Automake has of
  3773. knowing what sort of language support a given ‘Makefile.in’
  3774. requires. (1) This means that, for example, you can’t put a
  3775. configure substitution like ‘@my_sources@’ into a ‘_SOURCES’
  3776. variable. If you intend to conditionally compile source files and
  3777. use ‘configure’ to substitute the appropriate object names into,
  3778. e.g., ‘_LDADD’ (see below), then you should list the corresponding
  3779. source files in the ‘EXTRA_’ variable.
  3780. This variable also supports ‘dist_’ and ‘nodist_’ prefixes. For
  3781. instance, ‘nodist_EXTRA_maude_SOURCES’ would list extra sources
  3782. that may need to be built, but should not be distributed.
  3783. ‘maude_AR’
  3784. A static library is created by default by invoking ‘$(AR)
  3785. $(ARFLAGS)’ followed by the name of the library and then the
  3786. objects being put into the library. You can override this by
  3787. setting the ‘_AR’ variable. This is usually used with C++; some
  3788. C++ compilers require a special invocation in order to instantiate
  3789. all the templates that should go into a library. For instance, the
  3790. SGI C++ compiler likes this variable set like so:
  3791. libmaude_a_AR = $(CXX) -ar -o
  3792. ‘maude_LIBADD’
  3793. Extra objects can be added to a _library_ using the ‘_LIBADD’
  3794. variable. For instance, this should be used for objects determined
  3795. by ‘configure’ (*note A Library::).
  3796. In the case of libtool libraries, ‘maude_LIBADD’ can also refer to
  3797. other libtool libraries.
  3798. ‘maude_LDADD’
  3799. Extra objects (‘*.$(OBJEXT)’) and libraries (‘*.a’, ‘*.la’) can be
  3800. added to a _program_ by listing them in the ‘_LDADD’ variable. For
  3801. instance, this should be used for objects determined by ‘configure’
  3802. (*note Linking::).
  3803. ‘_LDADD’ and ‘_LIBADD’ are inappropriate for passing
  3804. program-specific linker flags (except for ‘-l’, ‘-L’, ‘-dlopen’ and
  3805. ‘-dlpreopen’). Use the ‘_LDFLAGS’ variable for this purpose.
  3806. For instance, if your ‘configure.ac’ uses ‘AC_PATH_XTRA’, you could
  3807. link your program against the X libraries like so:
  3808. maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
  3809. We recommend that you use ‘-l’ and ‘-L’ only when referring to
  3810. third-party libraries, and give the explicit file names of any
  3811. library built by your package. Doing so will ensure that
  3812. ‘maude_DEPENDENCIES’ (see below) is correctly defined by default.
  3813. ‘maude_LDFLAGS’
  3814. This variable is used to pass extra flags to the link step of a
  3815. program or a shared library. It overrides the ‘AM_LDFLAGS’
  3816. variable.
  3817. ‘maude_LIBTOOLFLAGS’
  3818. This variable is used to pass extra options to ‘libtool’. It
  3819. overrides the ‘AM_LIBTOOLFLAGS’ variable. These options are output
  3820. before ‘libtool’’s ‘--mode=MODE’ option, so they should not be
  3821. mode-specific options (those belong to the compiler or linker
  3822. flags). *Note Libtool Flags::.
  3823. ‘maude_DEPENDENCIES’
  3824. ‘EXTRA_maude_DEPENDENCIES’
  3825. It is also occasionally useful to have a target (program or
  3826. library) depend on some other file that is not actually part of
  3827. that target. This can be done using the ‘_DEPENDENCIES’ variable.
  3828. Each target depends on the contents of such a variable, but no
  3829. further interpretation is done.
  3830. Since these dependencies are associated to the link rule used to
  3831. create the programs they should normally list files used by the
  3832. link command. That is ‘*.$(OBJEXT)’, ‘*.a’, or ‘*.la’ files for
  3833. programs; ‘*.lo’ and ‘*.la’ files for Libtool libraries; and
  3834. ‘*.$(OBJEXT)’ files for static libraries. In rare cases you may
  3835. need to add other kinds of files such as linker scripts, but
  3836. _listing a source file in ‘_DEPENDENCIES’ is wrong_. If some
  3837. source file needs to be built before all the components of a
  3838. program are built, consider using the ‘BUILT_SOURCES’ variable
  3839. (*note Sources::).
  3840. If ‘_DEPENDENCIES’ is not supplied, it is computed by Automake.
  3841. The automatically-assigned value is the contents of ‘_LDADD’ or
  3842. ‘_LIBADD’, with most configure substitutions, ‘-l’, ‘-L’, ‘-dlopen’
  3843. and ‘-dlpreopen’ options removed. The configure substitutions that
  3844. are left in are only ‘$(LIBOBJS)’ and ‘$(ALLOCA)’; these are left
  3845. because it is known that they will not cause an invalid value for
  3846. ‘_DEPENDENCIES’ to be generated.
  3847. ‘_DEPENDENCIES’ is more likely used to perform conditional
  3848. compilation using an ‘AC_SUBST’ variable that contains a list of
  3849. objects. *Note Conditional Sources::, and *note Conditional
  3850. Libtool Sources::.
  3851. The ‘EXTRA_*_DEPENDENCIES’ variable may be useful for cases where
  3852. you merely want to augment the ‘automake’-generated ‘_DEPENDENCIES’
  3853. variable rather than replacing it.
  3854. ‘maude_LINK’
  3855. You can override the linker on a per-program basis. By default the
  3856. linker is chosen according to the languages used by the program.
  3857. For instance, a program that includes C++ source code would use the
  3858. C++ compiler to link. The ‘_LINK’ variable must hold the name of a
  3859. command that can be passed all the ‘.o’ file names and libraries to
  3860. link against as arguments. Note that the name of the underlying
  3861. program is _not_ passed to ‘_LINK’; typically one uses ‘$@’:
  3862. maude_LINK = $(CCLD) -magic -o $@
  3863. If a ‘_LINK’ variable is not supplied, it may still be generated
  3864. and used by Automake due to the use of per-target link flags such
  3865. as ‘_CFLAGS’, ‘_LDFLAGS’ or ‘_LIBTOOLFLAGS’, in cases where they
  3866. apply.
  3867. ‘maude_CCASFLAGS’
  3868. ‘maude_CFLAGS’
  3869. ‘maude_CPPFLAGS’
  3870. ‘maude_CXXFLAGS’
  3871. ‘maude_FFLAGS’
  3872. ‘maude_GCJFLAGS’
  3873. ‘maude_LFLAGS’
  3874. ‘maude_OBJCFLAGS’
  3875. ‘maude_OBJCXXFLAGS’
  3876. ‘maude_RFLAGS’
  3877. ‘maude_UPCFLAGS’
  3878. ‘maude_YFLAGS’
  3879. Automake allows you to set compilation flags on a per-program (or
  3880. per-library) basis. A single source file can be included in
  3881. several programs, and it will potentially be compiled with
  3882. different flags for each program. This works for any language
  3883. directly supported by Automake. These “per-target compilation
  3884. flags” are ‘_CCASFLAGS’, ‘_CFLAGS’, ‘_CPPFLAGS’, ‘_CXXFLAGS’,
  3885. ‘_FFLAGS’, ‘_GCJFLAGS’, ‘_LFLAGS’, ‘_OBJCFLAGS’, ‘_OBJCXXFLAGS’,
  3886. ‘_RFLAGS’, ‘_UPCFLAGS’, and ‘_YFLAGS’.
  3887. When using a per-target compilation flag, Automake will choose a
  3888. different name for the intermediate object files. Ordinarily a
  3889. file like ‘sample.c’ will be compiled to produce ‘sample.o’.
  3890. However, if the program’s ‘_CFLAGS’ variable is set, then the
  3891. object file will be named, for instance, ‘maude-sample.o’. (See
  3892. also *note Renamed Objects::).
  3893. In compilations with per-target flags, the ordinary ‘AM_’ form of
  3894. the flags variable is _not_ automatically included in the
  3895. compilation (however, the user form of the variable _is_ included).
  3896. So for instance, if you want the hypothetical ‘maude’ compilations
  3897. to also use the value of ‘AM_CFLAGS’, you would need to write:
  3898. maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
  3899. *Note Flag Variables Ordering::, for more discussion about the
  3900. interaction between user variables, ‘AM_’ shadow variables, and
  3901. per-target variables.
  3902. ‘maude_SHORTNAME’
  3903. On some platforms the allowable file names are very short. In
  3904. order to support these systems and per-target compilation flags at
  3905. the same time, Automake allows you to set a “short name” that will
  3906. influence how intermediate object files are named. For instance,
  3907. in the following example,
  3908. bin_PROGRAMS = maude
  3909. maude_CPPFLAGS = -DSOMEFLAG
  3910. maude_SHORTNAME = m
  3911. maude_SOURCES = sample.c ...
  3912. the object file would be named ‘m-sample.o’ rather than
  3913. ‘maude-sample.o’.
  3914. This facility is rarely needed in practice, and we recommend
  3915. avoiding it until you find it is required.
  3916. ---------- Footnotes ----------
  3917. (1) There are other, more obscure reasons for this limitation as
  3918. well.
  3919. 
  3920. File: automake.info, Node: Default _SOURCES, Next: LIBOBJS, Prev: Program and Library Variables, Up: Programs
  3921. 8.5 Default ‘_SOURCES’
  3922. ======================
  3923. ‘_SOURCES’ variables are used to specify source files of programs (*note
  3924. A Program::), libraries (*note A Library::), and Libtool libraries
  3925. (*note A Shared Library::).
  3926. When no such variable is specified for a target, Automake will define
  3927. one itself. The default is to compile a single C file whose base name
  3928. is the name of the target itself, with any extension replaced by
  3929. ‘AM_DEFAULT_SOURCE_EXT’, which defaults to ‘.c’.
  3930. For example if you have the following somewhere in your ‘Makefile.am’
  3931. with no corresponding ‘libfoo_a_SOURCES’:
  3932. lib_LIBRARIES = libfoo.a sub/libc++.a
  3933. ‘libfoo.a’ will be built using a default source file named ‘libfoo.c’,
  3934. and ‘sub/libc++.a’ will be built from ‘sub/libc++.c’. (In older
  3935. versions ‘sub/libc++.a’ would be built from ‘sub_libc___a.c’, i.e., the
  3936. default source was the canonized name of the target, with ‘.c’ appended.
  3937. We believe the new behavior is more sensible, but for backward
  3938. compatibility ‘automake’ will use the old name if a file or a rule with
  3939. that name exists and ‘AM_DEFAULT_SOURCE_EXT’ is not used.)
  3940. Default sources are mainly useful in test suites, when building many
  3941. test programs each from a single source. For instance, in
  3942. check_PROGRAMS = test1 test2 test3
  3943. AM_DEFAULT_SOURCE_EXT = .cpp
  3944. ‘test1’, ‘test2’, and ‘test3’ will be built from ‘test1.cpp’,
  3945. ‘test2.cpp’, and ‘test3.cpp’. Without the last line, they will be built
  3946. from ‘test1.c’, ‘test2.c’, and ‘test3.c’.
  3947. Another case where this is convenient is building many Libtool
  3948. modules (‘moduleN.la’), each defined in its own file (‘moduleN.c’).
  3949. AM_LDFLAGS = -module
  3950. lib_LTLIBRARIES = module1.la module2.la module3.la
  3951. Finally, there is one situation where this default source computation
  3952. needs to be avoided: when a target should not be built from sources. We
  3953. already saw such an example in *note true::; this happens when all the
  3954. constituents of a target have already been compiled and just need to be
  3955. combined using a ‘_LDADD’ variable. Then it is necessary to define an
  3956. empty ‘_SOURCES’ variable, so that ‘automake’ does not compute a
  3957. default.
  3958. bin_PROGRAMS = target
  3959. target_SOURCES =
  3960. target_LDADD = libmain.a libmisc.a
  3961. 
  3962. File: automake.info, Node: LIBOBJS, Next: Program Variables, Prev: Default _SOURCES, Up: Programs
  3963. 8.6 Special handling for ‘LIBOBJS’ and ‘ALLOCA’
  3964. ===============================================
  3965. The ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables list object files that should
  3966. be compiled into the project to provide an implementation for functions
  3967. that are missing or broken on the host system. They are substituted by
  3968. ‘configure’.
  3969. These variables are defined by Autoconf macros such as ‘AC_LIBOBJ’,
  3970. ‘AC_REPLACE_FUNCS’ (*note Generic Function Checks: (autoconf)Generic
  3971. Functions.), or ‘AC_FUNC_ALLOCA’ (*note Particular Function Checks:
  3972. (autoconf)Particular Functions.). Many other Autoconf macros call
  3973. ‘AC_LIBOBJ’ or ‘AC_REPLACE_FUNCS’ to populate ‘$(LIBOBJS)’.
  3974. Using these variables is very similar to doing conditional
  3975. compilation using ‘AC_SUBST’ variables, as described in *note
  3976. Conditional Sources::. That is, when building a program, ‘$(LIBOBJS)’
  3977. and ‘$(ALLOCA)’ should be added to the associated ‘*_LDADD’ variable, or
  3978. to the ‘*_LIBADD’ variable when building a library. However there is no
  3979. need to list the corresponding sources in ‘EXTRA_*_SOURCES’ nor to
  3980. define ‘*_DEPENDENCIES’. Automake automatically adds ‘$(LIBOBJS)’ and
  3981. ‘$(ALLOCA)’ to the dependencies, and it will discover the list of
  3982. corresponding source files automatically (by tracing the invocations of
  3983. the ‘AC_LIBSOURCE’ Autoconf macros). If you have already defined
  3984. ‘*_DEPENDENCIES’ explicitly for an unrelated reason, then you either
  3985. need to add these variables manually, or use ‘EXTRA_*_DEPENDENCIES’
  3986. instead of ‘*_DEPENDENCIES’.
  3987. These variables are usually used to build a portability library that
  3988. is linked with all the programs of the project. We now review a sample
  3989. setup. First, ‘configure.ac’ contains some checks that affect either
  3990. ‘LIBOBJS’ or ‘ALLOCA’.
  3991. # configure.ac
  3992. ...
  3993. AC_CONFIG_LIBOBJ_DIR([lib])
  3994. ...
  3995. AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
  3996. AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
  3997. AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
  3998. AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
  3999. ...
  4000. AC_CONFIG_FILES([
  4001. lib/Makefile
  4002. src/Makefile
  4003. ])
  4004. AC_OUTPUT
  4005. The ‘AC_CONFIG_LIBOBJ_DIR’ tells Autoconf that the source files of
  4006. these object files are to be found in the ‘lib/’ directory. Automake
  4007. can also use this information, otherwise it expects the source files are
  4008. to be in the directory where the ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables
  4009. are used.
  4010. The ‘lib/’ directory should therefore contain ‘malloc.c’, ‘memcmp.c’,
  4011. ‘strdup.c’, ‘alloca.c’. Here is its ‘Makefile.am’:
  4012. # lib/Makefile.am
  4013. noinst_LIBRARIES = libcompat.a
  4014. libcompat_a_SOURCES =
  4015. libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
  4016. The library can have any name, of course, and anyway it is not going
  4017. to be installed: it just holds the replacement versions of the missing
  4018. or broken functions so we can later link them in. Many projects also
  4019. include extra functions, specific to the project, in that library: they
  4020. are simply added on the ‘_SOURCES’ line.
  4021. There is a small trap here, though: ‘$(LIBOBJS)’ and ‘$(ALLOCA)’
  4022. might be empty, and building an empty library is not portable. You
  4023. should ensure that there is always something to put in ‘libcompat.a’.
  4024. Most projects will also add some utility functions in that directory,
  4025. and list them in ‘libcompat_a_SOURCES’, so in practice ‘libcompat.a’
  4026. cannot be empty.
  4027. Finally here is how this library could be used from the ‘src/’
  4028. directory.
  4029. # src/Makefile.am
  4030. # Link all programs in this directory with libcompat.a
  4031. LDADD = ../lib/libcompat.a
  4032. bin_PROGRAMS = tool1 tool2 ...
  4033. tool1_SOURCES = ...
  4034. tool2_SOURCES = ...
  4035. When option ‘subdir-objects’ is not used, as in the above example,
  4036. the variables ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ can only be used in the
  4037. directory where their sources lie. E.g., here it would be wrong to use
  4038. ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ in ‘src/Makefile.am’. However if both
  4039. ‘subdir-objects’ and ‘AC_CONFIG_LIBOBJ_DIR’ are used, it is OK to use
  4040. these variables in other directories. For instance ‘src/Makefile.am’
  4041. could be changed as follows.
  4042. # src/Makefile.am
  4043. AUTOMAKE_OPTIONS = subdir-objects
  4044. LDADD = $(LIBOBJS) $(ALLOCA)
  4045. bin_PROGRAMS = tool1 tool2 ...
  4046. tool1_SOURCES = ...
  4047. tool2_SOURCES = ...
  4048. Because ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ contain object file names that
  4049. end with ‘.$(OBJEXT)’, they are not suitable for Libtool libraries
  4050. (where the expected object extension is ‘.lo’): ‘LTLIBOBJS’ and
  4051. ‘LTALLOCA’ should be used instead.
  4052. ‘LTLIBOBJS’ is defined automatically by Autoconf and should not be
  4053. defined by hand (as in the past), however at the time of writing
  4054. ‘LTALLOCA’ still needs to be defined from ‘ALLOCA’ manually. *Note
  4055. ‘AC_LIBOBJ’ vs. ‘LIBOBJS’: (autoconf)AC_LIBOBJ vs LIBOBJS.
  4056. 
  4057. File: automake.info, Node: Program Variables, Next: Yacc and Lex, Prev: LIBOBJS, Up: Programs
  4058. 8.7 Variables used when building a program
  4059. ==========================================
  4060. Occasionally it is useful to know which ‘Makefile’ variables Automake
  4061. uses for compilations, and in which order (*note Flag Variables
  4062. Ordering::); for instance, you might need to do your own compilation in
  4063. some special cases.
  4064. Some variables are inherited from Autoconf; these are ‘CC’, ‘CFLAGS’,
  4065. ‘CPPFLAGS’, ‘DEFS’, ‘LDFLAGS’, and ‘LIBS’.
  4066. There are some additional variables that Automake defines on its own:
  4067. ‘AM_CPPFLAGS’
  4068. The contents of this variable are passed to every compilation that
  4069. invokes the C preprocessor; it is a list of arguments to the
  4070. preprocessor. For instance, ‘-I’ and ‘-D’ options should be listed
  4071. here.
  4072. Automake already provides some ‘-I’ options automatically, in a
  4073. separate variable that is also passed to every compilation that
  4074. invokes the C preprocessor. In particular it generates ‘-I.’,
  4075. ‘-I$(srcdir)’, and a ‘-I’ pointing to the directory holding
  4076. ‘config.h’ (if you’ve used ‘AC_CONFIG_HEADERS’). You can disable
  4077. the default ‘-I’ options using the ‘nostdinc’ option.
  4078. When a file to be included is generated during the build and not
  4079. part of a distribution tarball, its location is under
  4080. ‘$(builddir)’, not under ‘$(srcdir)’. This matters especially for
  4081. packages that use header files placed in sub-directories and want
  4082. to allow builds outside the source tree (*note VPATH Builds::). In
  4083. that case we recommend to use a pair of ‘-I’ options, such as,
  4084. e.g., ‘-Isome/subdir -I$(srcdir)/some/subdir’ or
  4085. ‘-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir’. Note
  4086. that the reference to the build tree should come before the
  4087. reference to the source tree, so that accidentally leftover
  4088. generated files in the source directory are ignored.
  4089. ‘AM_CPPFLAGS’ is ignored in preference to a per-executable (or
  4090. per-library) ‘_CPPFLAGS’ variable if it is defined.
  4091. ‘INCLUDES’
  4092. This does the same job as ‘AM_CPPFLAGS’ (or any per-target
  4093. ‘_CPPFLAGS’ variable if it is used). It is an older name for the
  4094. same functionality. This variable is deprecated; we suggest using
  4095. ‘AM_CPPFLAGS’ and per-target ‘_CPPFLAGS’ instead.
  4096. ‘AM_CFLAGS’
  4097. This is the variable the ‘Makefile.am’ author can use to pass in
  4098. additional C compiler flags. In some situations, this is not used,
  4099. in preference to the per-executable (or per-library) ‘_CFLAGS’.
  4100. ‘COMPILE’
  4101. This is the command used to actually compile a C source file. The
  4102. file name is appended to form the complete command line.
  4103. ‘AM_LDFLAGS’
  4104. This is the variable the ‘Makefile.am’ author can use to pass in
  4105. additional linker flags. In some situations, this is not used, in
  4106. preference to the per-executable (or per-library) ‘_LDFLAGS’.
  4107. ‘LINK’
  4108. This is the command used to actually link a C program. It already
  4109. includes ‘-o $@’ and the usual variable references (for instance,
  4110. ‘CFLAGS’); it takes as “arguments” the names of the object files
  4111. and libraries to link in. This variable is not used when the
  4112. linker is overridden with a per-target ‘_LINK’ variable or
  4113. per-target flags cause Automake to define such a ‘_LINK’ variable.
  4114. 
  4115. File: automake.info, Node: Yacc and Lex, Next: C++ Support, Prev: Program Variables, Up: Programs
  4116. 8.8 Yacc and Lex support
  4117. ========================
  4118. Automake has somewhat idiosyncratic support for Yacc and Lex.
  4119. Automake assumes that the ‘.c’ file generated by ‘yacc’ (or ‘lex’)
  4120. should be named using the basename of the input file. That is, for a
  4121. yacc source file ‘foo.y’, Automake will cause the intermediate file to
  4122. be named ‘foo.c’ (as opposed to ‘y.tab.c’, which is more traditional).
  4123. The extension of a yacc source file is used to determine the
  4124. extension of the resulting C or C++ source and header files. Note that
  4125. header files are generated only when the ‘-d’ Yacc option is used; see
  4126. below for more information about this flag, and how to specify it.
  4127. Files with the extension ‘.y’ will thus be turned into ‘.c’ sources and
  4128. ‘.h’ headers; likewise, ‘.yy’ will become ‘.cc’ and ‘.hh’, ‘.y++’ will
  4129. become ‘c++’ and ‘h++’, ‘.yxx’ will become ‘.cxx’ and ‘.hxx’, and ‘.ypp’
  4130. will become ‘.cpp’ and ‘.hpp’.
  4131. Similarly, lex source files can be used to generate C or C++; the
  4132. extensions ‘.l’, ‘.ll’, ‘.l++’, ‘.lxx’, and ‘.lpp’ are recognized.
  4133. You should never explicitly mention the intermediate (C or C++) file
  4134. in any ‘SOURCES’ variable; only list the source file.
  4135. The intermediate files generated by ‘yacc’ (or ‘lex’) will be
  4136. included in any distribution that is made. That way the user doesn’t
  4137. need to have ‘yacc’ or ‘lex’.
  4138. If a ‘yacc’ source file is seen, then your ‘configure.ac’ must define
  4139. the variable ‘YACC’. This is most easily done by invoking the macro
  4140. ‘AC_PROG_YACC’ (*note Particular Program Checks: (autoconf)Particular
  4141. Programs.).
  4142. When ‘yacc’ is invoked, it is passed ‘AM_YFLAGS’ and ‘YFLAGS’. The
  4143. latter is a user variable and the former is intended for the
  4144. ‘Makefile.am’ author.
  4145. ‘AM_YFLAGS’ is usually used to pass the ‘-d’ option to ‘yacc’.
  4146. Automake knows what this means and will automatically adjust its rules
  4147. to update and distribute the header file built by ‘yacc -d’(1). What
  4148. Automake cannot guess, though, is where this header will be used: it is
  4149. up to you to ensure the header gets built before it is first used.
  4150. Typically this is necessary in order for dependency tracking to work
  4151. when the header is included by another file. The common solution is
  4152. listing the header file in ‘BUILT_SOURCES’ (*note Sources::) as follows.
  4153. BUILT_SOURCES = parser.h
  4154. AM_YFLAGS = -d
  4155. bin_PROGRAMS = foo
  4156. foo_SOURCES = ... parser.y ...
  4157. If a ‘lex’ source file is seen, then your ‘configure.ac’ must define
  4158. the variable ‘LEX’. You can use ‘AC_PROG_LEX’ to do this (*note
  4159. Particular Program Checks: (autoconf)Particular Programs.), but using
  4160. ‘AM_PROG_LEX’ macro (*note Macros::) is recommended.
  4161. When ‘lex’ is invoked, it is passed ‘AM_LFLAGS’ and ‘LFLAGS’. The
  4162. latter is a user variable and the former is intended for the
  4163. ‘Makefile.am’ author.
  4164. When ‘AM_MAINTAINER_MODE’ (*note maintainer-mode::) is used, the
  4165. rebuild rule for distributed Yacc and Lex sources are only used when
  4166. ‘maintainer-mode’ is enabled, or when the files have been erased.
  4167. When ‘lex’ or ‘yacc’ sources are used, ‘automake -a’ automatically
  4168. installs an auxiliary program called ‘ylwrap’ in your package (*note
  4169. Auxiliary Programs::). This program is used by the build rules to
  4170. rename the output of these tools, and makes it possible to include
  4171. multiple ‘yacc’ (or ‘lex’) source files in a single directory. (This is
  4172. necessary because yacc’s output file name is fixed, and a parallel make
  4173. could conceivably invoke more than one instance of ‘yacc’
  4174. simultaneously.)
  4175. For ‘yacc’, simply managing locking is insufficient. The output of
  4176. ‘yacc’ always uses the same symbol names internally, so it isn’t
  4177. possible to link two ‘yacc’ parsers into the same executable.
  4178. We recommend using the following renaming hack used in ‘gdb’:
  4179. #define yymaxdepth c_maxdepth
  4180. #define yyparse c_parse
  4181. #define yylex c_lex
  4182. #define yyerror c_error
  4183. #define yylval c_lval
  4184. #define yychar c_char
  4185. #define yydebug c_debug
  4186. #define yypact c_pact
  4187. #define yyr1 c_r1
  4188. #define yyr2 c_r2
  4189. #define yydef c_def
  4190. #define yychk c_chk
  4191. #define yypgo c_pgo
  4192. #define yyact c_act
  4193. #define yyexca c_exca
  4194. #define yyerrflag c_errflag
  4195. #define yynerrs c_nerrs
  4196. #define yyps c_ps
  4197. #define yypv c_pv
  4198. #define yys c_s
  4199. #define yy_yys c_yys
  4200. #define yystate c_state
  4201. #define yytmp c_tmp
  4202. #define yyv c_v
  4203. #define yy_yyv c_yyv
  4204. #define yyval c_val
  4205. #define yylloc c_lloc
  4206. #define yyreds c_reds
  4207. #define yytoks c_toks
  4208. #define yylhs c_yylhs
  4209. #define yylen c_yylen
  4210. #define yydefred c_yydefred
  4211. #define yydgoto c_yydgoto
  4212. #define yysindex c_yysindex
  4213. #define yyrindex c_yyrindex
  4214. #define yygindex c_yygindex
  4215. #define yytable c_yytable
  4216. #define yycheck c_yycheck
  4217. #define yyname c_yyname
  4218. #define yyrule c_yyrule
  4219. For each define, replace the ‘c_’ prefix with whatever you like.
  4220. These defines work for ‘bison’, ‘byacc’, and traditional ‘yacc’s. If
  4221. you find a parser generator that uses a symbol not covered here, please
  4222. report the new name so it can be added to the list.
  4223. ---------- Footnotes ----------
  4224. (1) Please note that ‘automake’ recognizes ‘-d’ in ‘AM_YFLAGS’ only
  4225. if it is not clustered with other options; for example, it won’t be
  4226. recognized if ‘AM_YFLAGS’ is ‘-dt’, but it will be if ‘AM_YFLAGS’ is ‘-d
  4227. -t’ or ‘-t -d’.
  4228. 
  4229. File: automake.info, Node: C++ Support, Next: Objective C Support, Prev: Yacc and Lex, Up: Programs
  4230. 8.9 C++ Support
  4231. ===============
  4232. Automake includes full support for C++.
  4233. Any package including C++ code must define the output variable ‘CXX’
  4234. in ‘configure.ac’; the simplest way to do this is to use the
  4235. ‘AC_PROG_CXX’ macro (*note Particular Program Checks:
  4236. (autoconf)Particular Programs.).
  4237. A few additional variables are defined when a C++ source file is
  4238. seen:
  4239. ‘CXX’
  4240. The name of the C++ compiler.
  4241. ‘CXXFLAGS’
  4242. Any flags to pass to the C++ compiler.
  4243. ‘AM_CXXFLAGS’
  4244. The maintainer’s variant of ‘CXXFLAGS’.
  4245. ‘CXXCOMPILE’
  4246. The command used to actually compile a C++ source file. The file
  4247. name is appended to form the complete command line.
  4248. ‘CXXLINK’
  4249. The command used to actually link a C++ program.
  4250. 
  4251. File: automake.info, Node: Objective C Support, Next: Objective C++ Support, Prev: C++ Support, Up: Programs
  4252. 8.10 Objective C Support
  4253. ========================
  4254. Automake includes some support for Objective C.
  4255. Any package including Objective C code must define the output
  4256. variable ‘OBJC’ in ‘configure.ac’; the simplest way to do this is to use
  4257. the ‘AC_PROG_OBJC’ macro (*note Particular Program Checks:
  4258. (autoconf)Particular Programs.).
  4259. A few additional variables are defined when an Objective C source
  4260. file is seen:
  4261. ‘OBJC’
  4262. The name of the Objective C compiler.
  4263. ‘OBJCFLAGS’
  4264. Any flags to pass to the Objective C compiler.
  4265. ‘AM_OBJCFLAGS’
  4266. The maintainer’s variant of ‘OBJCFLAGS’.
  4267. ‘OBJCCOMPILE’
  4268. The command used to actually compile an Objective C source file.
  4269. The file name is appended to form the complete command line.
  4270. ‘OBJCLINK’
  4271. The command used to actually link an Objective C program.
  4272. 
  4273. File: automake.info, Node: Objective C++ Support, Next: Unified Parallel C Support, Prev: Objective C Support, Up: Programs
  4274. 8.11 Objective C++ Support
  4275. ==========================
  4276. Automake includes some support for Objective C++.
  4277. Any package including Objective C++ code must define the output
  4278. variable ‘OBJCXX’ in ‘configure.ac’; the simplest way to do this is to
  4279. use the ‘AC_PROG_OBJCXX’ macro (*note Particular Program Checks:
  4280. (autoconf)Particular Programs.).
  4281. A few additional variables are defined when an Objective C++ source
  4282. file is seen:
  4283. ‘OBJCXX’
  4284. The name of the Objective C++ compiler.
  4285. ‘OBJCXXFLAGS’
  4286. Any flags to pass to the Objective C++ compiler.
  4287. ‘AM_OBJCXXFLAGS’
  4288. The maintainer’s variant of ‘OBJCXXFLAGS’.
  4289. ‘OBJCXXCOMPILE’
  4290. The command used to actually compile an Objective C++ source file.
  4291. The file name is appended to form the complete command line.
  4292. ‘OBJCXXLINK’
  4293. The command used to actually link an Objective C++ program.
  4294. 
  4295. File: automake.info, Node: Unified Parallel C Support, Next: Assembly Support, Prev: Objective C++ Support, Up: Programs
  4296. 8.12 Unified Parallel C Support
  4297. ===============================
  4298. Automake includes some support for Unified Parallel C.
  4299. Any package including Unified Parallel C code must define the output
  4300. variable ‘UPC’ in ‘configure.ac’; the simplest way to do this is to use
  4301. the ‘AM_PROG_UPC’ macro (*note Public Macros::).
  4302. A few additional variables are defined when a Unified Parallel C
  4303. source file is seen:
  4304. ‘UPC’
  4305. The name of the Unified Parallel C compiler.
  4306. ‘UPCFLAGS’
  4307. Any flags to pass to the Unified Parallel C compiler.
  4308. ‘AM_UPCFLAGS’
  4309. The maintainer’s variant of ‘UPCFLAGS’.
  4310. ‘UPCCOMPILE’
  4311. The command used to actually compile a Unified Parallel C source
  4312. file. The file name is appended to form the complete command line.
  4313. ‘UPCLINK’
  4314. The command used to actually link a Unified Parallel C program.
  4315. 
  4316. File: automake.info, Node: Assembly Support, Next: Fortran 77 Support, Prev: Unified Parallel C Support, Up: Programs
  4317. 8.13 Assembly Support
  4318. =====================
  4319. Automake includes some support for assembly code. There are two forms
  4320. of assembler files: normal (‘*.s’) and preprocessed by ‘CPP’ (‘*.S’ or
  4321. ‘*.sx’).
  4322. The variable ‘CCAS’ holds the name of the compiler used to build
  4323. assembly code. This compiler must work a bit like a C compiler; in
  4324. particular it must accept ‘-c’ and ‘-o’. The values of ‘CCASFLAGS’ and
  4325. ‘AM_CCASFLAGS’ (or its per-target definition) is passed to the
  4326. compilation. For preprocessed files, ‘DEFS’, ‘DEFAULT_INCLUDES’,
  4327. ‘INCLUDES’, ‘CPPFLAGS’ and ‘AM_CPPFLAGS’ are also used.
  4328. The autoconf macro ‘AM_PROG_AS’ will define ‘CCAS’ and ‘CCASFLAGS’
  4329. for you (unless they are already set, it simply sets ‘CCAS’ to the C
  4330. compiler and ‘CCASFLAGS’ to the C compiler flags), but you are free to
  4331. define these variables by other means.
  4332. Only the suffixes ‘.s’, ‘.S’, and ‘.sx’ are recognized by ‘automake’
  4333. as being files containing assembly code.
  4334. 
  4335. File: automake.info, Node: Fortran 77 Support, Next: Fortran 9x Support, Prev: Assembly Support, Up: Programs
  4336. 8.14 Fortran 77 Support
  4337. =======================
  4338. Automake includes full support for Fortran 77.
  4339. Any package including Fortran 77 code must define the output variable
  4340. ‘F77’ in ‘configure.ac’; the simplest way to do this is to use the
  4341. ‘AC_PROG_F77’ macro (*note Particular Program Checks:
  4342. (autoconf)Particular Programs.).
  4343. A few additional variables are defined when a Fortran 77 source file
  4344. is seen:
  4345. ‘F77’
  4346. The name of the Fortran 77 compiler.
  4347. ‘FFLAGS’
  4348. Any flags to pass to the Fortran 77 compiler.
  4349. ‘AM_FFLAGS’
  4350. The maintainer’s variant of ‘FFLAGS’.
  4351. ‘RFLAGS’
  4352. Any flags to pass to the Ratfor compiler.
  4353. ‘AM_RFLAGS’
  4354. The maintainer’s variant of ‘RFLAGS’.
  4355. ‘F77COMPILE’
  4356. The command used to actually compile a Fortran 77 source file. The
  4357. file name is appended to form the complete command line.
  4358. ‘FLINK’
  4359. The command used to actually link a pure Fortran 77 program or
  4360. shared library.
  4361. Automake can handle preprocessing Fortran 77 and Ratfor source files
  4362. in addition to compiling them(1). Automake also contains some support
  4363. for creating programs and shared libraries that are a mixture of Fortran
  4364. 77 and other languages (*note Mixing Fortran 77 With C and C++::).
  4365. These issues are covered in the following sections.
  4366. * Menu:
  4367. * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
  4368. * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
  4369. * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
  4370. ---------- Footnotes ----------
  4371. (1) Much, if not most, of the information in the following sections
  4372. pertaining to preprocessing Fortran 77 programs was taken almost
  4373. verbatim from *note Catalogue of Rules: (make)Catalogue of Rules.
  4374. 
  4375. File: automake.info, Node: Preprocessing Fortran 77, Next: Compiling Fortran 77 Files, Up: Fortran 77 Support
  4376. 8.14.1 Preprocessing Fortran 77
  4377. -------------------------------
  4378. ‘N.f’ is made automatically from ‘N.F’ or ‘N.r’. This rule runs just
  4379. the preprocessor to convert a preprocessable Fortran 77 or Ratfor source
  4380. file into a strict Fortran 77 source file. The precise command used is
  4381. as follows:
  4382. ‘.F’
  4383. ‘$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
  4384. $(AM_FFLAGS) $(FFLAGS)’
  4385. ‘.r’
  4386. ‘$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)’
  4387. 
  4388. File: automake.info, Node: Compiling Fortran 77 Files, Next: Mixing Fortran 77 With C and C++, Prev: Preprocessing Fortran 77, Up: Fortran 77 Support
  4389. 8.14.2 Compiling Fortran 77 Files
  4390. ---------------------------------
  4391. ‘N.o’ is made automatically from ‘N.f’, ‘N.F’ or ‘N.r’ by running the
  4392. Fortran 77 compiler. The precise command used is as follows:
  4393. ‘.f’
  4394. ‘$(F77) -c $(AM_FFLAGS) $(FFLAGS)’
  4395. ‘.F’
  4396. ‘$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
  4397. $(AM_FFLAGS) $(FFLAGS)’
  4398. ‘.r’
  4399. ‘$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)’
  4400. 
  4401. File: automake.info, Node: Mixing Fortran 77 With C and C++, Prev: Compiling Fortran 77 Files, Up: Fortran 77 Support
  4402. 8.14.3 Mixing Fortran 77 With C and C++
  4403. ---------------------------------------
  4404. Automake currently provides _limited_ support for creating programs and
  4405. shared libraries that are a mixture of Fortran 77 and C and/or C++.
  4406. However, there are many other issues related to mixing Fortran 77 with
  4407. other languages that are _not_ (currently) handled by Automake, but that
  4408. are handled by other packages(1).
  4409. Automake can help in two ways:
  4410. 1. Automatic selection of the linker depending on which combinations
  4411. of source code.
  4412. 2. Automatic selection of the appropriate linker flags (e.g., ‘-L’ and
  4413. ‘-l’) to pass to the automatically selected linker in order to link
  4414. in the appropriate Fortran 77 intrinsic and run-time libraries.
  4415. These extra Fortran 77 linker flags are supplied in the output
  4416. variable ‘FLIBS’ by the ‘AC_F77_LIBRARY_LDFLAGS’ Autoconf macro.
  4417. *Note Fortran Compiler Characteristics: (autoconf)Fortran Compiler.
  4418. If Automake detects that a program or shared library (as mentioned in
  4419. some ‘_PROGRAMS’ or ‘_LTLIBRARIES’ primary) contains source code that is
  4420. a mixture of Fortran 77 and C and/or C++, then it requires that the
  4421. macro ‘AC_F77_LIBRARY_LDFLAGS’ be called in ‘configure.ac’, and that
  4422. either ‘$(FLIBS)’ appear in the appropriate ‘_LDADD’ (for programs) or
  4423. ‘_LIBADD’ (for shared libraries) variables. It is the responsibility of
  4424. the person writing the ‘Makefile.am’ to make sure that ‘$(FLIBS)’
  4425. appears in the appropriate ‘_LDADD’ or ‘_LIBADD’ variable.
  4426. For example, consider the following ‘Makefile.am’:
  4427. bin_PROGRAMS = foo
  4428. foo_SOURCES = main.cc foo.f
  4429. foo_LDADD = libfoo.la $(FLIBS)
  4430. pkglib_LTLIBRARIES = libfoo.la
  4431. libfoo_la_SOURCES = bar.f baz.c zardoz.cc
  4432. libfoo_la_LIBADD = $(FLIBS)
  4433. In this case, Automake will insist that ‘AC_F77_LIBRARY_LDFLAGS’ is
  4434. mentioned in ‘configure.ac’. Also, if ‘$(FLIBS)’ hadn’t been mentioned
  4435. in ‘foo_LDADD’ and ‘libfoo_la_LIBADD’, then Automake would have issued a
  4436. warning.
  4437. * Menu:
  4438. * How the Linker is Chosen:: Automatic linker selection
  4439. ---------- Footnotes ----------
  4440. (1) For example, the cfortran package
  4441. (http://www-zeus.desy.de/~burow/cfortran/) addresses all of these
  4442. inter-language issues, and runs under nearly all Fortran 77, C and C++
  4443. compilers on nearly all platforms. However, ‘cfortran’ is not yet Free
  4444. Software, but it will be in the next major release.
  4445. 
  4446. File: automake.info, Node: How the Linker is Chosen, Up: Mixing Fortran 77 With C and C++
  4447. 8.14.3.1 How the Linker is Chosen
  4448. .................................
  4449. When a program or library mixes several languages, Automake choose the
  4450. linker according to the following priorities. (The names in parentheses
  4451. are the variables containing the link command.)
  4452. 1. Native Java (‘GCJLINK’)
  4453. 2. Objective C++ (‘OBJCXXLINK’)
  4454. 3. C++ (‘CXXLINK’)
  4455. 4. Fortran 77 (‘F77LINK’)
  4456. 5. Fortran (‘FCLINK’)
  4457. 6. Objective C (‘OBJCLINK’)
  4458. 7. Unified Parallel C (‘UPCLINK’)
  4459. 8. C (‘LINK’)
  4460. For example, if Fortran 77, C and C++ source code is compiled into a
  4461. program, then the C++ linker will be used. In this case, if the C or
  4462. Fortran 77 linkers required any special libraries that weren’t included
  4463. by the C++ linker, then they must be manually added to an ‘_LDADD’ or
  4464. ‘_LIBADD’ variable by the user writing the ‘Makefile.am’.
  4465. Automake only looks at the file names listed in ‘_SOURCES’ variables
  4466. to choose the linker, and defaults to the C linker. Sometimes this is
  4467. inconvenient because you are linking against a library written in
  4468. another language and would like to set the linker more appropriately.
  4469. *Note Libtool Convenience Libraries::, for a trick with
  4470. ‘nodist_EXTRA_..._SOURCES’.
  4471. A per-target ‘_LINK’ variable will override the above selection.
  4472. Per-target link flags will cause Automake to write a per-target ‘_LINK’
  4473. variable according to the language chosen as above.
  4474. 
  4475. File: automake.info, Node: Fortran 9x Support, Next: Java Support with gcj, Prev: Fortran 77 Support, Up: Programs
  4476. 8.15 Fortran 9x Support
  4477. =======================
  4478. Automake includes support for Fortran 9x.
  4479. Any package including Fortran 9x code must define the output variable
  4480. ‘FC’ in ‘configure.ac’; the simplest way to do this is to use the
  4481. ‘AC_PROG_FC’ macro (*note Particular Program Checks:
  4482. (autoconf)Particular Programs.).
  4483. A few additional variables are defined when a Fortran 9x source file
  4484. is seen:
  4485. ‘FC’
  4486. The name of the Fortran 9x compiler.
  4487. ‘FCFLAGS’
  4488. Any flags to pass to the Fortran 9x compiler.
  4489. ‘AM_FCFLAGS’
  4490. The maintainer’s variant of ‘FCFLAGS’.
  4491. ‘FCCOMPILE’
  4492. The command used to actually compile a Fortran 9x source file. The
  4493. file name is appended to form the complete command line.
  4494. ‘FCLINK’
  4495. The command used to actually link a pure Fortran 9x program or
  4496. shared library.
  4497. * Menu:
  4498. * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
  4499. 
  4500. File: automake.info, Node: Compiling Fortran 9x Files, Up: Fortran 9x Support
  4501. 8.15.1 Compiling Fortran 9x Files
  4502. ---------------------------------
  4503. ‘FILE.o’ is made automatically from ‘FILE.f90’, ‘FILE.f95’, ‘FILE.f03’,
  4504. or ‘FILE.f08’ by running the Fortran 9x compiler. The precise command
  4505. used is as follows:
  4506. ‘.f90’
  4507. ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<’
  4508. ‘.f95’
  4509. ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<’
  4510. ‘.f03’
  4511. ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<’
  4512. ‘.f08’
  4513. ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<’
  4514. 
  4515. File: automake.info, Node: Java Support with gcj, Next: Vala Support, Prev: Fortran 9x Support, Up: Programs
  4516. 8.16 Compiling Java sources using gcj
  4517. =====================================
  4518. Automake includes support for natively compiled Java, using ‘gcj’, the
  4519. Java front end to the GNU Compiler Collection (rudimentary support for
  4520. compiling Java to bytecode using the ‘javac’ compiler is also present,
  4521. _albeit deprecated_; *note Java::).
  4522. Any package including Java code to be compiled must define the output
  4523. variable ‘GCJ’ in ‘configure.ac’; the variable ‘GCJFLAGS’ must also be
  4524. defined somehow (either in ‘configure.ac’ or ‘Makefile.am’). The
  4525. simplest way to do this is to use the ‘AM_PROG_GCJ’ macro.
  4526. By default, programs including Java source files are linked with
  4527. ‘gcj’.
  4528. As always, the contents of ‘AM_GCJFLAGS’ are passed to every
  4529. compilation invoking ‘gcj’ (in its role as an ahead-of-time compiler,
  4530. when invoking it to create ‘.class’ files, ‘AM_JAVACFLAGS’ is used
  4531. instead). If it is necessary to pass options to ‘gcj’ from
  4532. ‘Makefile.am’, this variable, and not the user variable ‘GCJFLAGS’,
  4533. should be used.
  4534. ‘gcj’ can be used to compile ‘.java’, ‘.class’, ‘.zip’, or ‘.jar’
  4535. files.
  4536. When linking, ‘gcj’ requires that the main class be specified using
  4537. the ‘--main=’ option. The easiest way to do this is to use the
  4538. ‘_LDFLAGS’ variable for the program.
  4539. 
  4540. File: automake.info, Node: Vala Support, Next: Support for Other Languages, Prev: Java Support with gcj, Up: Programs
  4541. 8.17 Vala Support
  4542. =================
  4543. Automake provides initial support for Vala
  4544. (<http://www.vala-project.org/>). This requires valac version 0.7.0 or
  4545. later, and currently requires the user to use GNU ‘make’.
  4546. foo_SOURCES = foo.vala bar.vala zardoc.c
  4547. Any ‘.vala’ file listed in a ‘_SOURCES’ variable will be compiled
  4548. into C code by the Vala compiler. The generated ‘.c’ files are
  4549. distributed. The end user does not need to have a Vala compiler
  4550. installed.
  4551. Automake ships with an Autoconf macro called ‘AM_PROG_VALAC’ that
  4552. will locate the Vala compiler and optionally check its version number.
  4553. -- Macro: AM_PROG_VALAC ([MINIMUM-VERSION], [ACTION-IF-FOUND],
  4554. [ACTION-IF-NOT-FOUND]) Search for a Vala compiler in ‘PATH’. If it
  4555. is found, the variable ‘VALAC’ is set to point to it (see below for
  4556. more details). This macro takes three optional arguments. The
  4557. first argument, if present, is the minimum version of the Vala
  4558. compiler required to compile this package. If a compiler is found
  4559. and satisfies MINIMUM-VERSION, then ACTION-IF-FOUND is run (this
  4560. defaults to do nothing). Otherwise, ACTION-IF-NOT-FOUND is run.
  4561. If ACTION-IF-NOT-FOUND is not specified, the default value is to
  4562. print a warning in case no compiler is found, or if a too-old
  4563. version of the compiler is found.
  4564. There are a few variables that are used when compiling Vala sources:
  4565. ‘VALAC’
  4566. Absolute path to the Vala compiler, or simply ‘valac’ if no
  4567. suitable compiler Vala could be found at configure runtime.
  4568. ‘VALAFLAGS’
  4569. Additional arguments for the Vala compiler.
  4570. ‘AM_VALAFLAGS’
  4571. The maintainer’s variant of ‘VALAFLAGS’.
  4572. lib_LTLIBRARIES = libfoo.la
  4573. libfoo_la_SOURCES = foo.vala
  4574. Note that currently, you cannot use per-target ‘*_VALAFLAGS’ (*note
  4575. Renamed Objects::) to produce different C files from one Vala source
  4576. file.
  4577. 
  4578. File: automake.info, Node: Support for Other Languages, Next: Dependencies, Prev: Vala Support, Up: Programs
  4579. 8.18 Support for Other Languages
  4580. ================================
  4581. Automake currently only includes full support for C, C++ (*note C++
  4582. Support::), Objective C (*note Objective C Support::), Objective C++
  4583. (*note Objective C++ Support::), Fortran 77 (*note Fortran 77
  4584. Support::), Fortran 9x (*note Fortran 9x Support::), and Java (*note
  4585. Java Support with gcj::). There is only rudimentary support for other
  4586. languages, support for which will be improved based on user demand.
  4587. Some limited support for adding your own languages is available via
  4588. the suffix rule handling (*note Suffixes::).
  4589. 
  4590. File: automake.info, Node: Dependencies, Next: EXEEXT, Prev: Support for Other Languages, Up: Programs
  4591. 8.19 Automatic dependency tracking
  4592. ==================================
  4593. As a developer it is often painful to continually update the
  4594. ‘Makefile.am’ whenever the include-file dependencies change in a
  4595. project. Automake supplies a way to automatically track dependency
  4596. changes (*note Dependency Tracking::).
  4597. Automake always uses complete dependencies for a compilation,
  4598. including system headers. Automake’s model is that dependency
  4599. computation should be a side effect of the build. To this end,
  4600. dependencies are computed by running all compilations through a special
  4601. wrapper program called ‘depcomp’. ‘depcomp’ understands how to coax
  4602. many different C and C++ compilers into generating dependency
  4603. information in the format it requires. ‘automake -a’ will install
  4604. ‘depcomp’ into your source tree for you. If ‘depcomp’ can’t figure out
  4605. how to properly invoke your compiler, dependency tracking will simply be
  4606. disabled for your build.
  4607. Experience with earlier versions of Automake (*note Dependency
  4608. Tracking Evolution: (automake-history)Dependency Tracking Evolution.)
  4609. taught us that it is not reliable to generate dependencies only on the
  4610. maintainer’s system, as configurations vary too much. So instead
  4611. Automake implements dependency tracking at build time.
  4612. Automatic dependency tracking can be suppressed by putting
  4613. ‘no-dependencies’ in the variable ‘AUTOMAKE_OPTIONS’, or passing
  4614. ‘no-dependencies’ as an argument to ‘AM_INIT_AUTOMAKE’ (this should be
  4615. the preferred way). Or, you can invoke ‘automake’ with the ‘-i’ option.
  4616. Dependency tracking is enabled by default.
  4617. The person building your package also can choose to disable
  4618. dependency tracking by configuring with ‘--disable-dependency-tracking’.
  4619. 
  4620. File: automake.info, Node: EXEEXT, Prev: Dependencies, Up: Programs
  4621. 8.20 Support for executable extensions
  4622. ======================================
  4623. On some platforms, such as Windows, executables are expected to have an
  4624. extension such as ‘.exe’. On these platforms, some compilers (GCC among
  4625. them) will automatically generate ‘foo.exe’ when asked to generate
  4626. ‘foo’.
  4627. Automake provides mostly-transparent support for this. Unfortunately
  4628. _mostly_ doesn’t yet mean _fully_. Until the English dictionary is
  4629. revised, you will have to assist Automake if your package must support
  4630. those platforms.
  4631. One thing you must be aware of is that, internally, Automake rewrites
  4632. something like this:
  4633. bin_PROGRAMS = liver
  4634. to this:
  4635. bin_PROGRAMS = liver$(EXEEXT)
  4636. The targets Automake generates are likewise given the ‘$(EXEEXT)’
  4637. extension.
  4638. The variables ‘TESTS’ and ‘XFAIL_TESTS’ (*note Simple Tests::) are
  4639. also rewritten if they contain filenames that have been declared as
  4640. programs in the same ‘Makefile’. (This is mostly useful when some
  4641. programs from ‘check_PROGRAMS’ are listed in ‘TESTS’.)
  4642. However, Automake cannot apply this rewriting to ‘configure’
  4643. substitutions. This means that if you are conditionally building a
  4644. program using such a substitution, then your ‘configure.ac’ must take
  4645. care to add ‘$(EXEEXT)’ when constructing the output variable.
  4646. Sometimes maintainers like to write an explicit link rule for their
  4647. program. Without executable extension support, this is easy—you simply
  4648. write a rule whose target is the name of the program. However, when
  4649. executable extension support is enabled, you must instead add the
  4650. ‘$(EXEEXT)’ suffix.
  4651. This might be a nuisance for maintainers who know their package will
  4652. never run on a platform that has executable extensions. For those
  4653. maintainers, the ‘no-exeext’ option (*note Options::) will disable this
  4654. feature. This works in a fairly ugly way; if ‘no-exeext’ is seen, then
  4655. the presence of a rule for a target named ‘foo’ in ‘Makefile.am’ will
  4656. override an ‘automake’-generated rule for ‘foo$(EXEEXT)’. Without the
  4657. ‘no-exeext’ option, this use will give a diagnostic.
  4658. 
  4659. File: automake.info, Node: Other Objects, Next: Other GNU Tools, Prev: Programs, Up: Top
  4660. 9 Other Derived Objects
  4661. ***********************
  4662. Automake can handle derived objects that are not C programs. Sometimes
  4663. the support for actually building such objects must be explicitly
  4664. supplied, but Automake will still automatically handle installation and
  4665. distribution.
  4666. * Menu:
  4667. * Scripts:: Executable scripts
  4668. * Headers:: Header files
  4669. * Data:: Architecture-independent data files
  4670. * Sources:: Derived sources
  4671. 
  4672. File: automake.info, Node: Scripts, Next: Headers, Up: Other Objects
  4673. 9.1 Executable Scripts
  4674. ======================
  4675. It is possible to define and install programs that are scripts. Such
  4676. programs are listed using the ‘SCRIPTS’ primary name. When the script
  4677. is distributed in its final, installable form, the ‘Makefile’ usually
  4678. looks as follows:
  4679. # Install my_script in $(bindir) and distribute it.
  4680. dist_bin_SCRIPTS = my_script
  4681. Scripts are not distributed by default; as we have just seen, those
  4682. that should be distributed can be specified using a ‘dist_’ prefix as
  4683. with other primaries.
  4684. Scripts can be installed in ‘bindir’, ‘sbindir’, ‘libexecdir’,
  4685. ‘pkglibexecdir’, or ‘pkgdatadir’.
  4686. Scripts that need not be installed can be listed in ‘noinst_SCRIPTS’,
  4687. and among them, those which are needed only by ‘make check’ should go in
  4688. ‘check_SCRIPTS’.
  4689. When a script needs to be built, the ‘Makefile.am’ should include the
  4690. appropriate rules. For instance the ‘automake’ program itself is a Perl
  4691. script that is generated from ‘automake.in’. Here is how this is
  4692. handled:
  4693. bin_SCRIPTS = automake
  4694. CLEANFILES = $(bin_SCRIPTS)
  4695. EXTRA_DIST = automake.in
  4696. do_subst = sed -e 's,[@]datadir[@],$(datadir),g' \
  4697. -e 's,[@]PERL[@],$(PERL),g' \
  4698. -e 's,[@]PACKAGE[@],$(PACKAGE),g' \
  4699. -e 's,[@]VERSION[@],$(VERSION),g' \
  4700. ...
  4701. automake: automake.in Makefile
  4702. $(do_subst) < $(srcdir)/automake.in > automake
  4703. chmod +x automake
  4704. Such scripts for which a build rule has been supplied need to be
  4705. deleted explicitly using ‘CLEANFILES’ (*note Clean::), and their sources
  4706. have to be distributed, usually with ‘EXTRA_DIST’ (*note Basics of
  4707. Distribution::).
  4708. Another common way to build scripts is to process them from
  4709. ‘configure’ with ‘AC_CONFIG_FILES’. In this situation Automake knows
  4710. which files should be cleaned and distributed, and what the rebuild
  4711. rules should look like.
  4712. For instance if ‘configure.ac’ contains
  4713. AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
  4714. to build ‘src/my_script’ from ‘src/my_script.in’, then a
  4715. ‘src/Makefile.am’ to install this script in ‘$(bindir)’ can be as simple
  4716. as
  4717. bin_SCRIPTS = my_script
  4718. CLEANFILES = $(bin_SCRIPTS)
  4719. There is no need for ‘EXTRA_DIST’ or any build rule: Automake infers
  4720. them from ‘AC_CONFIG_FILES’ (*note Requirements::). ‘CLEANFILES’ is
  4721. still useful, because by default Automake will clean targets of
  4722. ‘AC_CONFIG_FILES’ in ‘distclean’, not ‘clean’.
  4723. Although this looks simpler, building scripts this way has one
  4724. drawback: directory variables such as ‘$(datadir)’ are not fully
  4725. expanded and may refer to other directory variables.
  4726. 
  4727. File: automake.info, Node: Headers, Next: Data, Prev: Scripts, Up: Other Objects
  4728. 9.2 Header files
  4729. ================
  4730. Header files that must be installed are specified by the ‘HEADERS’
  4731. family of variables. Headers can be installed in ‘includedir’,
  4732. ‘oldincludedir’, ‘pkgincludedir’ or any other directory you may have
  4733. defined (*note Uniform::). For instance,
  4734. include_HEADERS = foo.h bar/bar.h
  4735. will install the two files as ‘$(includedir)/foo.h’ and
  4736. ‘$(includedir)/bar.h’.
  4737. The ‘nobase_’ prefix is also supported,
  4738. nobase_include_HEADERS = foo.h bar/bar.h
  4739. will install the two files as ‘$(includedir)/foo.h’ and
  4740. ‘$(includedir)/bar/bar.h’ (*note Alternative::).
  4741. Usually, only header files that accompany installed libraries need to
  4742. be installed. Headers used by programs or convenience libraries are not
  4743. installed. The ‘noinst_HEADERS’ variable can be used for such headers.
  4744. However when the header actually belongs to a single convenience library
  4745. or program, we recommend listing it in the program’s or library’s
  4746. ‘_SOURCES’ variable (*note Program Sources::) instead of in
  4747. ‘noinst_HEADERS’. This is clearer for the ‘Makefile.am’ reader.
  4748. ‘noinst_HEADERS’ would be the right variable to use in a directory
  4749. containing only headers and no associated library or program.
  4750. All header files must be listed somewhere; in a ‘_SOURCES’ variable
  4751. or in a ‘_HEADERS’ variable. Missing ones will not appear in the
  4752. distribution.
  4753. For header files that are built and must not be distributed, use the
  4754. ‘nodist_’ prefix as in ‘nodist_include_HEADERS’ or
  4755. ‘nodist_prog_SOURCES’. If these generated headers are needed during the
  4756. build, you must also ensure they exist before they are used (*note
  4757. Sources::).
  4758. 
  4759. File: automake.info, Node: Data, Next: Sources, Prev: Headers, Up: Other Objects
  4760. 9.3 Architecture-independent data files
  4761. =======================================
  4762. Automake supports the installation of miscellaneous data files using the
  4763. ‘DATA’ family of variables.
  4764. Such data can be installed in the directories ‘datadir’,
  4765. ‘sysconfdir’, ‘sharedstatedir’, ‘localstatedir’, or ‘pkgdatadir’.
  4766. By default, data files are _not_ included in a distribution. Of
  4767. course, you can use the ‘dist_’ prefix to change this on a per-variable
  4768. basis.
  4769. Here is how Automake declares its auxiliary data files:
  4770. dist_pkgdata_DATA = clean-kr.am clean.am ...
  4771. 
  4772. File: automake.info, Node: Sources, Prev: Data, Up: Other Objects
  4773. 9.4 Built Sources
  4774. =================
  4775. Because Automake’s automatic dependency tracking works as a side-effect
  4776. of compilation (*note Dependencies::) there is a bootstrap issue: a
  4777. target should not be compiled before its dependencies are made, but
  4778. these dependencies are unknown until the target is first compiled.
  4779. Ordinarily this is not a problem, because dependencies are
  4780. distributed sources: they preexist and do not need to be built. Suppose
  4781. that ‘foo.c’ includes ‘foo.h’. When it first compiles ‘foo.o’, ‘make’
  4782. only knows that ‘foo.o’ depends on ‘foo.c’. As a side-effect of this
  4783. compilation ‘depcomp’ records the ‘foo.h’ dependency so that following
  4784. invocations of ‘make’ will honor it. In these conditions, it’s clear
  4785. there is no problem: either ‘foo.o’ doesn’t exist and has to be built
  4786. (regardless of the dependencies), or accurate dependencies exist and
  4787. they can be used to decide whether ‘foo.o’ should be rebuilt.
  4788. It’s a different story if ‘foo.h’ doesn’t exist by the first ‘make’
  4789. run. For instance, there might be a rule to build ‘foo.h’. This time
  4790. ‘file.o’’s build will fail because the compiler can’t find ‘foo.h’.
  4791. ‘make’ failed to trigger the rule to build ‘foo.h’ first by lack of
  4792. dependency information.
  4793. The ‘BUILT_SOURCES’ variable is a workaround for this problem. A
  4794. source file listed in ‘BUILT_SOURCES’ is made on ‘make all’ or ‘make
  4795. check’ (or even ‘make install’) before other targets are processed.
  4796. However, such a source file is not _compiled_ unless explicitly
  4797. requested by mentioning it in some other ‘_SOURCES’ variable.
  4798. So, to conclude our introductory example, we could use ‘BUILT_SOURCES
  4799. = foo.h’ to ensure ‘foo.h’ gets built before any other target (including
  4800. ‘foo.o’) during ‘make all’ or ‘make check’.
  4801. ‘BUILT_SOURCES’ is actually a bit of a misnomer, as any file which
  4802. must be created early in the build process can be listed in this
  4803. variable. Moreover, all built sources do not necessarily have to be
  4804. listed in ‘BUILT_SOURCES’. For instance, a generated ‘.c’ file doesn’t
  4805. need to appear in ‘BUILT_SOURCES’ (unless it is included by another
  4806. source), because it’s a known dependency of the associated object.
  4807. It might be important to emphasize that ‘BUILT_SOURCES’ is honored
  4808. only by ‘make all’, ‘make check’ and ‘make install’. This means you
  4809. cannot build a specific target (e.g., ‘make foo’) in a clean tree if it
  4810. depends on a built source. However it will succeed if you have run
  4811. ‘make all’ earlier, because accurate dependencies are already available.
  4812. The next section illustrates and discusses the handling of built
  4813. sources on a toy example.
  4814. * Menu:
  4815. * Built Sources Example:: Several ways to handle built sources.
  4816. 
  4817. File: automake.info, Node: Built Sources Example, Up: Sources
  4818. 9.4.1 Built Sources Example
  4819. ---------------------------
  4820. Suppose that ‘foo.c’ includes ‘bindir.h’, which is
  4821. installation-dependent and not distributed: it needs to be built. Here
  4822. ‘bindir.h’ defines the preprocessor macro ‘bindir’ to the value of the
  4823. ‘make’ variable ‘bindir’ (inherited from ‘configure’).
  4824. We suggest several implementations below. It’s not meant to be an
  4825. exhaustive listing of all ways to handle built sources, but it will give
  4826. you a few ideas if you encounter this issue.
  4827. First Try
  4828. .........
  4829. This first implementation will illustrate the bootstrap issue mentioned
  4830. in the previous section (*note Sources::).
  4831. Here is a tentative ‘Makefile.am’.
  4832. # This won't work.
  4833. bin_PROGRAMS = foo
  4834. foo_SOURCES = foo.c
  4835. nodist_foo_SOURCES = bindir.h
  4836. CLEANFILES = bindir.h
  4837. bindir.h: Makefile
  4838. echo '#define bindir "$(bindir)"' >$@
  4839. This setup doesn’t work, because Automake doesn’t know that ‘foo.c’
  4840. includes ‘bindir.h’. Remember, automatic dependency tracking works as a
  4841. side-effect of compilation, so the dependencies of ‘foo.o’ will be known
  4842. only after ‘foo.o’ has been compiled (*note Dependencies::). The
  4843. symptom is as follows.
  4844. % make
  4845. source='foo.c' object='foo.o' libtool=no \
  4846. depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
  4847. depmode=gcc /bin/sh ./depcomp \
  4848. gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
  4849. foo.c:2: bindir.h: No such file or directory
  4850. make: *** [foo.o] Error 1
  4851. In this example ‘bindir.h’ is not distributed nor installed, and it
  4852. is not even being built on-time. One may wonder if the
  4853. ‘nodist_foo_SOURCES = bindir.h’ line has any use at all. This line
  4854. simply states that ‘bindir.h’ is a source of ‘foo’, so for instance, it
  4855. should be inspected while generating tags (*note Tags::). In other
  4856. words, it does not help our present problem, and the build would fail
  4857. identically without it.
  4858. Using ‘BUILT_SOURCES’
  4859. .....................
  4860. A solution is to require ‘bindir.h’ to be built before anything else.
  4861. This is what ‘BUILT_SOURCES’ is meant for (*note Sources::).
  4862. bin_PROGRAMS = foo
  4863. foo_SOURCES = foo.c
  4864. nodist_foo_SOURCES = bindir.h
  4865. BUILT_SOURCES = bindir.h
  4866. CLEANFILES = bindir.h
  4867. bindir.h: Makefile
  4868. echo '#define bindir "$(bindir)"' >$@
  4869. See how ‘bindir.h’ gets built first:
  4870. % make
  4871. echo '#define bindir "/usr/local/bin"' >bindir.h
  4872. make all-am
  4873. make[1]: Entering directory `/home/adl/tmp'
  4874. source='foo.c' object='foo.o' libtool=no \
  4875. depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
  4876. depmode=gcc /bin/sh ./depcomp \
  4877. gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
  4878. gcc -g -O2 -o foo foo.o
  4879. make[1]: Leaving directory `/home/adl/tmp'
  4880. However, as said earlier, ‘BUILT_SOURCES’ applies only to the ‘all’,
  4881. ‘check’, and ‘install’ targets. It still fails if you try to run ‘make
  4882. foo’ explicitly:
  4883. % make clean
  4884. test -z "bindir.h" || rm -f bindir.h
  4885. test -z "foo" || rm -f foo
  4886. rm -f *.o
  4887. % : > .deps/foo.Po # Suppress previously recorded dependencies
  4888. % make foo
  4889. source='foo.c' object='foo.o' libtool=no \
  4890. depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
  4891. depmode=gcc /bin/sh ./depcomp \
  4892. gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
  4893. foo.c:2: bindir.h: No such file or directory
  4894. make: *** [foo.o] Error 1
  4895. Recording Dependencies manually
  4896. ...............................
  4897. Usually people are happy enough with ‘BUILT_SOURCES’ because they never
  4898. build targets such as ‘make foo’ before ‘make all’, as in the previous
  4899. example. However if this matters to you, you can avoid ‘BUILT_SOURCES’
  4900. and record such dependencies explicitly in the ‘Makefile.am’.
  4901. bin_PROGRAMS = foo
  4902. foo_SOURCES = foo.c
  4903. nodist_foo_SOURCES = bindir.h
  4904. foo.$(OBJEXT): bindir.h
  4905. CLEANFILES = bindir.h
  4906. bindir.h: Makefile
  4907. echo '#define bindir "$(bindir)"' >$@
  4908. You don’t have to list _all_ the dependencies of ‘foo.o’ explicitly,
  4909. only those that might need to be built. If a dependency already exists,
  4910. it will not hinder the first compilation and will be recorded by the
  4911. normal dependency tracking code. (Note that after this first
  4912. compilation the dependency tracking code will also have recorded the
  4913. dependency between ‘foo.o’ and ‘bindir.h’; so our explicit dependency is
  4914. really useful to the first build only.)
  4915. Adding explicit dependencies like this can be a bit dangerous if you
  4916. are not careful enough. This is due to the way Automake tries not to
  4917. overwrite your rules (it assumes you know better than it).
  4918. ‘foo.$(OBJEXT): bindir.h’ supersedes any rule Automake may want to
  4919. output to build ‘foo.$(OBJEXT)’. It happens to work in this case
  4920. because Automake doesn’t have to output any ‘foo.$(OBJEXT):’ target: it
  4921. relies on a suffix rule instead (i.e., ‘.c.$(OBJEXT):’). Always check
  4922. the generated ‘Makefile.in’ if you do this.
  4923. Build ‘bindir.h’ from ‘configure’
  4924. .................................
  4925. It’s possible to define this preprocessor macro from ‘configure’, either
  4926. in ‘config.h’ (*note Defining Directories: (autoconf)Defining
  4927. Directories.), or by processing a ‘bindir.h.in’ file using
  4928. ‘AC_CONFIG_FILES’ (*note Configuration Actions: (autoconf)Configuration
  4929. Actions.).
  4930. At this point it should be clear that building ‘bindir.h’ from
  4931. ‘configure’ works well for this example. ‘bindir.h’ will exist before
  4932. you build any target, hence will not cause any dependency issue.
  4933. The Makefile can be shrunk as follows. We do not even have to
  4934. mention ‘bindir.h’.
  4935. bin_PROGRAMS = foo
  4936. foo_SOURCES = foo.c
  4937. However, it’s not always possible to build sources from ‘configure’,
  4938. especially when these sources are generated by a tool that needs to be
  4939. built first.
  4940. Build ‘bindir.c’, not ‘bindir.h’.
  4941. .................................
  4942. Another attractive idea is to define ‘bindir’ as a variable or function
  4943. exported from ‘bindir.o’, and build ‘bindir.c’ instead of ‘bindir.h’.
  4944. noinst_PROGRAMS = foo
  4945. foo_SOURCES = foo.c bindir.h
  4946. nodist_foo_SOURCES = bindir.c
  4947. CLEANFILES = bindir.c
  4948. bindir.c: Makefile
  4949. echo 'const char bindir[] = "$(bindir)";' >$@
  4950. ‘bindir.h’ contains just the variable’s declaration and doesn’t need
  4951. to be built, so it won’t cause any trouble. ‘bindir.o’ is always
  4952. dependent on ‘bindir.c’, so ‘bindir.c’ will get built first.
  4953. Which is best?
  4954. ..............
  4955. There is no panacea, of course. Each solution has its merits and
  4956. drawbacks.
  4957. You cannot use ‘BUILT_SOURCES’ if the ability to run ‘make foo’ on a
  4958. clean tree is important to you.
  4959. You won’t add explicit dependencies if you are leery of overriding an
  4960. Automake rule by mistake.
  4961. Building files from ‘./configure’ is not always possible, neither is
  4962. converting ‘.h’ files into ‘.c’ files.
  4963. 
  4964. File: automake.info, Node: Other GNU Tools, Next: Documentation, Prev: Other Objects, Up: Top
  4965. 10 Other GNU Tools
  4966. ******************
  4967. Since Automake is primarily intended to generate ‘Makefile.in’s for use
  4968. in GNU programs, it tries hard to interoperate with other GNU tools.
  4969. * Menu:
  4970. * Emacs Lisp:: Emacs Lisp
  4971. * gettext:: Gettext
  4972. * Libtool:: Libtool
  4973. * Java:: Java bytecode compilation (deprecated)
  4974. * Python:: Python
  4975. 
  4976. File: automake.info, Node: Emacs Lisp, Next: gettext, Up: Other GNU Tools
  4977. 10.1 Emacs Lisp
  4978. ===============
  4979. Automake provides some support for Emacs Lisp. The ‘LISP’ primary is
  4980. used to hold a list of ‘.el’ files. Possible prefixes for this primary
  4981. are ‘lisp_’ and ‘noinst_’. Note that if ‘lisp_LISP’ is defined, then
  4982. ‘configure.ac’ must run ‘AM_PATH_LISPDIR’ (*note Macros::).
  4983. Lisp sources are not distributed by default. You can prefix the
  4984. ‘LISP’ primary with ‘dist_’, as in ‘dist_lisp_LISP’ or
  4985. ‘dist_noinst_LISP’, to indicate that these files should be distributed.
  4986. Automake will byte-compile all Emacs Lisp source files using the
  4987. Emacs found by ‘AM_PATH_LISPDIR’, if any was found. When performing
  4988. such byte-compilation, the flags specified in the (developer-reserved)
  4989. ‘AM_ELCFLAGS’ and (user-reserved) ‘ELCFLAGS’ make variables will be
  4990. passed to the Emacs invocation.
  4991. Byte-compiled Emacs Lisp files are not portable among all versions of
  4992. Emacs, so it makes sense to turn this off if you expect sites to have
  4993. more than one version of Emacs installed. Furthermore, many packages
  4994. don’t actually benefit from byte-compilation. Still, we recommend that
  4995. you byte-compile your Emacs Lisp sources. It is probably better for
  4996. sites with strange setups to cope for themselves than to make the
  4997. installation less nice for everybody else.
  4998. There are two ways to avoid byte-compiling. Historically, we have
  4999. recommended the following construct.
  5000. lisp_LISP = file1.el file2.el
  5001. ELCFILES =
  5002. ‘ELCFILES’ is an internal Automake variable that normally lists all
  5003. ‘.elc’ files that must be byte-compiled. Automake defines ‘ELCFILES’
  5004. automatically from ‘lisp_LISP’. Emptying this variable explicitly
  5005. prevents byte-compilation.
  5006. Since Automake 1.8, we now recommend using ‘lisp_DATA’ instead:
  5007. lisp_DATA = file1.el file2.el
  5008. Note that these two constructs are not equivalent. ‘_LISP’ will not
  5009. install a file if Emacs is not installed, while ‘_DATA’ will always
  5010. install its files.
  5011. 
  5012. File: automake.info, Node: gettext, Next: Libtool, Prev: Emacs Lisp, Up: Other GNU Tools
  5013. 10.2 Gettext
  5014. ============
  5015. If ‘AM_GNU_GETTEXT’ is seen in ‘configure.ac’, then Automake turns on
  5016. support for GNU gettext, a message catalog system for
  5017. internationalization (*note Introduction: (gettext)Top.).
  5018. The ‘gettext’ support in Automake requires the addition of one or two
  5019. subdirectories to the package: ‘po’ and possibly also ‘intl’. The
  5020. latter is needed if ‘AM_GNU_GETTEXT’ is not invoked with the ‘external’
  5021. argument, or if ‘AM_GNU_GETTEXT_INTL_SUBDIR’ is used. Automake ensures
  5022. that these directories exist and are mentioned in ‘SUBDIRS’.
  5023. 
  5024. File: automake.info, Node: Libtool, Next: Java, Prev: gettext, Up: Other GNU Tools
  5025. 10.3 Libtool
  5026. ============
  5027. Automake provides support for GNU Libtool (*note Introduction:
  5028. (libtool)Top.) with the ‘LTLIBRARIES’ primary. *Note A Shared
  5029. Library::.
  5030. 
  5031. File: automake.info, Node: Java, Next: Python, Prev: Libtool, Up: Other GNU Tools
  5032. 10.4 Java bytecode compilation (deprecated)
  5033. ===========================================
  5034. Automake provides some minimal support for Java bytecode compilation
  5035. with the ‘JAVA’ primary (in addition to the support for compiling Java
  5036. to native machine code; *note Java Support with gcj::). Note however
  5037. that _the interface and most features described here are deprecated_.
  5038. Future Automake releases will strive to provide a better and cleaner
  5039. interface, which however _won’t be backward-compatible_; the present
  5040. interface will probably be removed altogether some time after the
  5041. introduction of the new interface (if that ever materializes). In any
  5042. case, the current ‘JAVA’ primary features are frozen and will no longer
  5043. be developed, not even to take bug fixes.
  5044. Any ‘.java’ files listed in a ‘_JAVA’ variable will be compiled with
  5045. ‘JAVAC’ at build time. By default, ‘.java’ files are not included in
  5046. the distribution, you should use the ‘dist_’ prefix to distribute them.
  5047. Here is a typical setup for distributing ‘.java’ files and installing
  5048. the ‘.class’ files resulting from their compilation.
  5049. javadir = $(datadir)/java
  5050. dist_java_JAVA = a.java b.java ...
  5051. Currently Automake enforces the restriction that only one ‘_JAVA’
  5052. primary can be used in a given ‘Makefile.am’. The reason for this
  5053. restriction is that, in general, it isn’t possible to know which
  5054. ‘.class’ files were generated from which ‘.java’ files, so it would be
  5055. impossible to know which files to install where. For instance, a
  5056. ‘.java’ file can define multiple classes; the resulting ‘.class’ file
  5057. names cannot be predicted without parsing the ‘.java’ file.
  5058. There are a few variables that are used when compiling Java sources:
  5059. ‘JAVAC’
  5060. The name of the Java compiler. This defaults to ‘javac’.
  5061. ‘JAVACFLAGS’
  5062. The flags to pass to the compiler. This is considered to be a user
  5063. variable (*note User Variables::).
  5064. ‘AM_JAVACFLAGS’
  5065. More flags to pass to the Java compiler. This, and not
  5066. ‘JAVACFLAGS’, should be used when it is necessary to put Java
  5067. compiler flags into ‘Makefile.am’.
  5068. ‘JAVAROOT’
  5069. The value of this variable is passed to the ‘-d’ option to ‘javac’.
  5070. It defaults to ‘$(top_builddir)’.
  5071. ‘CLASSPATH_ENV’
  5072. This variable is a shell expression that is used to set the
  5073. ‘CLASSPATH’ environment variable on the ‘javac’ command line. (In
  5074. the future we will probably handle class path setting differently.)
  5075. 
  5076. File: automake.info, Node: Python, Prev: Java, Up: Other GNU Tools
  5077. 10.5 Python
  5078. ===========
  5079. Automake provides support for Python compilation with the ‘PYTHON’
  5080. primary. A typical setup is to call ‘AM_PATH_PYTHON’ in ‘configure.ac’
  5081. and use a line like the following in ‘Makefile.am’:
  5082. python_PYTHON = tree.py leave.py
  5083. Any files listed in a ‘_PYTHON’ variable will be byte-compiled with
  5084. ‘py-compile’ at install time. ‘py-compile’ actually creates both
  5085. standard (‘.pyc’) and optimized (‘.pyo’) byte-compiled versions of the
  5086. source files. Note that because byte-compilation occurs at install
  5087. time, any files listed in ‘noinst_PYTHON’ will not be compiled. Python
  5088. source files are included in the distribution by default, prepend
  5089. ‘nodist_’ (as in ‘nodist_python_PYTHON’) to omit them.
  5090. Automake ships with an Autoconf macro called ‘AM_PATH_PYTHON’ that
  5091. will determine some Python-related directory variables (see below). If
  5092. you have called ‘AM_PATH_PYTHON’ from ‘configure.ac’, then you may use
  5093. the variables ‘python_PYTHON’ or ‘pkgpython_PYTHON’ to list Python
  5094. source files in your ‘Makefile.am’, depending on where you want your
  5095. files installed (see the definitions of ‘pythondir’ and ‘pkgpythondir’
  5096. below).
  5097. -- Macro: AM_PATH_PYTHON ([VERSION], [ACTION-IF-FOUND],
  5098. [ACTION-IF-NOT-FOUND])
  5099. Search for a Python interpreter on the system. This macro takes
  5100. three optional arguments. The first argument, if present, is the
  5101. minimum version of Python required for this package:
  5102. ‘AM_PATH_PYTHON’ will skip any Python interpreter that is older
  5103. than VERSION. If an interpreter is found and satisfies VERSION,
  5104. then ACTION-IF-FOUND is run. Otherwise, ACTION-IF-NOT-FOUND is
  5105. run.
  5106. If ACTION-IF-NOT-FOUND is not specified, as in the following
  5107. example, the default is to abort ‘configure’.
  5108. AM_PATH_PYTHON([2.2])
  5109. This is fine when Python is an absolute requirement for the
  5110. package. If Python >= 2.5 was only _optional_ to the package,
  5111. ‘AM_PATH_PYTHON’ could be called as follows.
  5112. AM_PATH_PYTHON([2.5],, [:])
  5113. If the ‘PYTHON’ variable is set when ‘AM_PATH_PYTHON’ is called,
  5114. then that will be the only Python interpreter that is tried.
  5115. ‘AM_PATH_PYTHON’ creates the following output variables based on
  5116. the Python installation found during configuration.
  5117. ‘PYTHON’
  5118. The name of the Python executable, or ‘:’ if no suitable
  5119. interpreter could be found.
  5120. Assuming ACTION-IF-NOT-FOUND is used (otherwise ‘./configure’ will
  5121. abort if Python is absent), the value of ‘PYTHON’ can be used to
  5122. setup a conditional in order to disable the relevant part of a
  5123. build as follows.
  5124. AM_PATH_PYTHON(,, [:])
  5125. AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
  5126. ‘PYTHON_VERSION’
  5127. The Python version number, in the form MAJOR.MINOR (e.g., ‘2.5’).
  5128. This is currently the value of ‘sys.version[:3]’.
  5129. ‘PYTHON_PREFIX’
  5130. The string ‘${prefix}’. This term may be used in future work that
  5131. needs the contents of Python’s ‘sys.prefix’, but general consensus
  5132. is to always use the value from ‘configure’.
  5133. ‘PYTHON_EXEC_PREFIX’
  5134. The string ‘${exec_prefix}’. This term may be used in future work
  5135. that needs the contents of Python’s ‘sys.exec_prefix’, but general
  5136. consensus is to always use the value from ‘configure’.
  5137. ‘PYTHON_PLATFORM’
  5138. The canonical name used by Python to describe the operating system,
  5139. as given by ‘sys.platform’. This value is sometimes needed when
  5140. building Python extensions.
  5141. ‘pythondir’
  5142. The directory name for the ‘site-packages’ subdirectory of the
  5143. standard Python install tree.
  5144. ‘pkgpythondir’
  5145. This is the directory under ‘pythondir’ that is named after the
  5146. package. That is, it is ‘$(pythondir)/$(PACKAGE)’. It is provided
  5147. as a convenience.
  5148. ‘pyexecdir’
  5149. This is the directory where Python extension modules (shared
  5150. libraries) should be installed. An extension module written in C
  5151. could be declared as follows to Automake:
  5152. pyexec_LTLIBRARIES = quaternion.la
  5153. quaternion_la_SOURCES = quaternion.c support.c support.h
  5154. quaternion_la_LDFLAGS = -avoid-version -module
  5155. ‘pkgpyexecdir’
  5156. This is a convenience variable that is defined as
  5157. ‘$(pyexecdir)/$(PACKAGE)’.
  5158. All of these directory variables have values that start with either
  5159. ‘${prefix}’ or ‘${exec_prefix}’ unexpanded. This works fine in
  5160. ‘Makefiles’, but it makes these variables hard to use in ‘configure’.
  5161. This is mandated by the GNU coding standards, so that the user can run
  5162. ‘make prefix=/foo install’. The Autoconf manual has a section with more
  5163. details on this topic (*note Installation Directory Variables:
  5164. (autoconf)Installation Directory Variables.). See also *note Hard-Coded
  5165. Install Paths::.
  5166. 
  5167. File: automake.info, Node: Documentation, Next: Install, Prev: Other GNU Tools, Up: Top
  5168. 11 Building documentation
  5169. *************************
  5170. Currently Automake provides support for Texinfo and man pages.
  5171. * Menu:
  5172. * Texinfo:: Texinfo
  5173. * Man Pages:: Man pages
  5174. 
  5175. File: automake.info, Node: Texinfo, Next: Man Pages, Up: Documentation
  5176. 11.1 Texinfo
  5177. ============
  5178. If the current directory contains Texinfo source, you must declare it
  5179. with the ‘TEXINFOS’ primary. Generally Texinfo files are converted into
  5180. info, and thus the ‘info_TEXINFOS’ variable is most commonly used here.
  5181. Any Texinfo source file should have the ‘.texi’ extension. Automake
  5182. also accepts ‘.txi’ or ‘.texinfo’ extensions, but their use is
  5183. discouraged now, and will elicit runtime warnings.
  5184. Automake generates rules to build ‘.info’, ‘.dvi’, ‘.ps’, ‘.pdf’ and
  5185. ‘.html’ files from your Texinfo sources. Following the GNU Coding
  5186. Standards, only the ‘.info’ files are built by ‘make all’ and installed
  5187. by ‘make install’ (unless you use ‘no-installinfo’, see below).
  5188. Furthermore, ‘.info’ files are automatically distributed so that Texinfo
  5189. is not a prerequisite for installing your package.
  5190. It is worth noting that, contrary to what happens with the other
  5191. formats, the generated ‘.info’ files are by default placed in ‘srcdir’
  5192. rather than in the ‘builddir’. This can be changed with the
  5193. ‘info-in-builddir’ option.
  5194. Other documentation formats can be built on request by ‘make dvi’,
  5195. ‘make ps’, ‘make pdf’ and ‘make html’, and they can be installed with
  5196. ‘make install-dvi’, ‘make install-ps’, ‘make install-pdf’ and ‘make
  5197. install-html’ explicitly. ‘make uninstall’ will remove everything: the
  5198. Texinfo documentation installed by default as well as all the above
  5199. optional formats.
  5200. All of these targets can be extended using ‘-local’ rules (*note
  5201. Extending::).
  5202. If the ‘.texi’ file ‘@include’s ‘version.texi’, then that file will
  5203. be automatically generated. The file ‘version.texi’ defines four
  5204. Texinfo flags you can reference using ‘@value{EDITION}’,
  5205. ‘@value{VERSION}’, ‘@value{UPDATED}’, and ‘@value{UPDATED-MONTH}’.
  5206. ‘EDITION’
  5207. ‘VERSION’
  5208. Both of these flags hold the version number of your program. They
  5209. are kept separate for clarity.
  5210. ‘UPDATED’
  5211. This holds the date the primary ‘.texi’ file was last modified.
  5212. ‘UPDATED-MONTH’
  5213. This holds the name of the month in which the primary ‘.texi’ file
  5214. was last modified.
  5215. The ‘version.texi’ support requires the ‘mdate-sh’ script; this
  5216. script is supplied with Automake and automatically included when
  5217. ‘automake’ is invoked with the ‘--add-missing’ option.
  5218. If you have multiple Texinfo files, and you want to use the
  5219. ‘version.texi’ feature, then you have to have a separate version file
  5220. for each Texinfo file. Automake will treat any include in a Texinfo
  5221. file that matches ‘vers*.texi’ just as an automatically generated
  5222. version file.
  5223. Sometimes an info file actually depends on more than one ‘.texi’
  5224. file. For instance, in GNU Hello, ‘hello.texi’ includes the file
  5225. ‘fdl.texi’. You can tell Automake about these dependencies using the
  5226. ‘TEXI_TEXINFOS’ variable. Here is how GNU Hello does it:
  5227. info_TEXINFOS = hello.texi
  5228. hello_TEXINFOS = fdl.texi
  5229. By default, Automake requires the file ‘texinfo.tex’ to appear in the
  5230. same directory as the ‘Makefile.am’ file that lists the ‘.texi’ files.
  5231. If you used ‘AC_CONFIG_AUX_DIR’ in ‘configure.ac’ (*note Finding
  5232. ‘configure’ Input: (autoconf)Input.), then ‘texinfo.tex’ is looked for
  5233. there. In both cases, ‘automake’ then supplies ‘texinfo.tex’ if
  5234. ‘--add-missing’ is given, and takes care of its distribution. However,
  5235. if you set the ‘TEXINFO_TEX’ variable (see below), it overrides the
  5236. location of the file and turns off its installation into the source as
  5237. well as its distribution.
  5238. The option ‘no-texinfo.tex’ can be used to eliminate the requirement
  5239. for the file ‘texinfo.tex’. Use of the variable ‘TEXINFO_TEX’ is
  5240. preferable, however, because that allows the ‘dvi’, ‘ps’, and ‘pdf’
  5241. targets to still work.
  5242. Automake generates an ‘install-info’ rule; some people apparently use
  5243. this. By default, info pages are installed by ‘make install’, so
  5244. running ‘make install-info’ is pointless. This can be prevented via the
  5245. ‘no-installinfo’ option. In this case, ‘.info’ files are not installed
  5246. by default, and user must request this explicitly using ‘make
  5247. install-info’.
  5248. By default, ‘make install-info’ and ‘make uninstall-info’ will try to
  5249. run the ‘install-info’ program (if available) to update (or
  5250. create/remove) the ‘${infodir}/dir’ index. If this is undesired, it can
  5251. be prevented by exporting the ‘AM_UPDATE_INFO_DIR’ variable to "‘no’".
  5252. The following variables are used by the Texinfo build rules.
  5253. ‘MAKEINFO’
  5254. The name of the program invoked to build ‘.info’ files. This
  5255. variable is defined by Automake. If the ‘makeinfo’ program is
  5256. found on the system then it will be used by default; otherwise
  5257. ‘missing’ will be used instead.
  5258. ‘MAKEINFOHTML’
  5259. The command invoked to build ‘.html’ files. Automake defines this
  5260. to ‘$(MAKEINFO) --html’.
  5261. ‘MAKEINFOFLAGS’
  5262. User flags passed to each invocation of ‘$(MAKEINFO)’ and
  5263. ‘$(MAKEINFOHTML)’. This user variable (*note User Variables::) is
  5264. not expected to be defined in any ‘Makefile’; it can be used by
  5265. users to pass extra flags to suit their needs.
  5266. ‘AM_MAKEINFOFLAGS’
  5267. ‘AM_MAKEINFOHTMLFLAGS’
  5268. Maintainer flags passed to each ‘makeinfo’ invocation. Unlike
  5269. ‘MAKEINFOFLAGS’, these variables are meant to be defined by
  5270. maintainers in ‘Makefile.am’. ‘$(AM_MAKEINFOFLAGS)’ is passed to
  5271. ‘makeinfo’ when building ‘.info’ files; and
  5272. ‘$(AM_MAKEINFOHTMLFLAGS)’ is used when building ‘.html’ files.
  5273. For instance, the following setting can be used to obtain one
  5274. single ‘.html’ file per manual, without node separators.
  5275. AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
  5276. ‘AM_MAKEINFOHTMLFLAGS’ defaults to ‘$(AM_MAKEINFOFLAGS)’. This
  5277. means that defining ‘AM_MAKEINFOFLAGS’ without defining
  5278. ‘AM_MAKEINFOHTMLFLAGS’ will impact builds of both ‘.info’ and
  5279. ‘.html’ files.
  5280. ‘TEXI2DVI’
  5281. The name of the command that converts a ‘.texi’ file into a ‘.dvi’
  5282. file. This defaults to ‘texi2dvi’, a script that ships with the
  5283. Texinfo package.
  5284. ‘TEXI2PDF’
  5285. The name of the command that translates a ‘.texi’ file into a
  5286. ‘.pdf’ file. This defaults to ‘$(TEXI2DVI) --pdf --batch’.
  5287. ‘DVIPS’
  5288. The name of the command that builds a ‘.ps’ file out of a ‘.dvi’
  5289. file. This defaults to ‘dvips’.
  5290. ‘TEXINFO_TEX’
  5291. If your package has Texinfo files in many directories, you can use
  5292. the variable ‘TEXINFO_TEX’ to tell Automake where to find the
  5293. canonical ‘texinfo.tex’ for your package. The value of this
  5294. variable should be the relative path from the current ‘Makefile.am’
  5295. to ‘texinfo.tex’:
  5296. TEXINFO_TEX = ../doc/texinfo.tex
  5297. 
  5298. File: automake.info, Node: Man Pages, Prev: Texinfo, Up: Documentation
  5299. 11.2 Man Pages
  5300. ==============
  5301. A package can also include man pages (but see the GNU standards on this
  5302. matter, *note (standards)Man Pages::.) Man pages are declared using the
  5303. ‘MANS’ primary. Generally the ‘man_MANS’ variable is used. Man pages
  5304. are automatically installed in the correct subdirectory of ‘mandir’,
  5305. based on the file extension.
  5306. File extensions such as ‘.1c’ are handled by looking for the valid
  5307. part of the extension and using that to determine the correct
  5308. subdirectory of ‘mandir’. Valid section names are the digits ‘0’
  5309. through ‘9’, and the letters ‘l’ and ‘n’.
  5310. Sometimes developers prefer to name a man page something like
  5311. ‘foo.man’ in the source, and then rename it to have the correct suffix,
  5312. for example ‘foo.1’, when installing the file. Automake also supports
  5313. this mode. For a valid section named SECTION, there is a corresponding
  5314. directory named ‘manSECTIONdir’, and a corresponding ‘_MANS’ variable.
  5315. Files listed in such a variable are installed in the indicated section.
  5316. If the file already has a valid suffix, then it is installed as-is;
  5317. otherwise the file suffix is changed to match the section.
  5318. For instance, consider this example:
  5319. man1_MANS = rename.man thesame.1 alsothesame.1c
  5320. In this case, ‘rename.man’ will be renamed to ‘rename.1’ when installed,
  5321. but the other files will keep their names.
  5322. By default, man pages are installed by ‘make install’. However,
  5323. since the GNU project does not require man pages, many maintainers do
  5324. not expend effort to keep the man pages up to date. In these cases, the
  5325. ‘no-installman’ option will prevent the man pages from being installed
  5326. by default. The user can still explicitly install them via ‘make
  5327. install-man’.
  5328. For fast installation, with many files it is preferable to use
  5329. ‘manSECTION_MANS’ over ‘man_MANS’ as well as files that do not need to
  5330. be renamed.
  5331. Man pages are not currently considered to be source, because it is
  5332. not uncommon for man pages to be automatically generated. Therefore
  5333. they are not automatically included in the distribution. However, this
  5334. can be changed by use of the ‘dist_’ prefix. For instance here is how
  5335. to distribute and install the two man pages of GNU ‘cpio’ (which
  5336. includes both Texinfo documentation and man pages):
  5337. dist_man_MANS = cpio.1 mt.1
  5338. The ‘nobase_’ prefix is meaningless for man pages and is disallowed.
  5339. Executables and manpages may be renamed upon installation (*note
  5340. Renaming::). For manpages this can be avoided by use of the ‘notrans_’
  5341. prefix. For instance, suppose an executable ‘foo’ allowing to access a
  5342. library function ‘foo’ from the command line. The way to avoid renaming
  5343. of the ‘foo.3’ manpage is:
  5344. man_MANS = foo.1
  5345. notrans_man_MANS = foo.3
  5346. ‘notrans_’ must be specified first when used in conjunction with
  5347. either ‘dist_’ or ‘nodist_’ (*note Fine-grained Distribution Control::).
  5348. For instance:
  5349. notrans_dist_man3_MANS = bar.3
  5350. 
  5351. File: automake.info, Node: Install, Next: Clean, Prev: Documentation, Up: Top
  5352. 12 What Gets Installed
  5353. **********************
  5354. Naturally, Automake handles the details of actually installing your
  5355. program once it has been built. All files named by the various
  5356. primaries are automatically installed in the appropriate places when the
  5357. user runs ‘make install’.
  5358. * Menu:
  5359. * Basics of Installation:: What gets installed where
  5360. * The Two Parts of Install:: Installing data and programs separately
  5361. * Extending Installation:: Adding your own rules for installation
  5362. * Staged Installs:: Installation in a temporary location
  5363. * Install Rules for the User:: Useful additional rules
  5364. 
  5365. File: automake.info, Node: Basics of Installation, Next: The Two Parts of Install, Up: Install
  5366. 12.1 Basics of Installation
  5367. ===========================
  5368. A file named in a primary is installed by copying the built file into
  5369. the appropriate directory. The base name of the file is used when
  5370. installing.
  5371. bin_PROGRAMS = hello subdir/goodbye
  5372. In this example, both ‘hello’ and ‘goodbye’ will be installed in
  5373. ‘$(bindir)’.
  5374. Sometimes it is useful to avoid the basename step at install time.
  5375. For instance, you might have a number of header files in subdirectories
  5376. of the source tree that are laid out precisely how you want to install
  5377. them. In this situation you can use the ‘nobase_’ prefix to suppress
  5378. the base name step. For example:
  5379. nobase_include_HEADERS = stdio.h sys/types.h
  5380. will install ‘stdio.h’ in ‘$(includedir)’ and ‘types.h’ in
  5381. ‘$(includedir)/sys’.
  5382. For most file types, Automake will install multiple files at once,
  5383. while avoiding command line length issues (*note Length Limitations::).
  5384. Since some ‘install’ programs will not install the same file twice in
  5385. one invocation, you may need to ensure that file lists are unique within
  5386. one variable such as ‘nobase_include_HEADERS’ above.
  5387. You should not rely on the order in which files listed in one
  5388. variable are installed. Likewise, to cater for parallel make, you
  5389. should not rely on any particular file installation order even among
  5390. different file types (library dependencies are an exception here).
  5391. 
  5392. File: automake.info, Node: The Two Parts of Install, Next: Extending Installation, Prev: Basics of Installation, Up: Install
  5393. 12.2 The Two Parts of Install
  5394. =============================
  5395. Automake generates separate ‘install-data’ and ‘install-exec’ rules, in
  5396. case the installer is installing on multiple machines that share
  5397. directory structure—these targets allow the machine-independent parts to
  5398. be installed only once. ‘install-exec’ installs platform-dependent
  5399. files, and ‘install-data’ installs platform-independent files. The
  5400. ‘install’ target depends on both of these targets. While Automake tries
  5401. to automatically segregate objects into the correct category, the
  5402. ‘Makefile.am’ author is, in the end, responsible for making sure this is
  5403. done correctly.
  5404. Variables using the standard directory prefixes ‘data’, ‘info’,
  5405. ‘man’, ‘include’, ‘oldinclude’, ‘pkgdata’, or ‘pkginclude’ are installed
  5406. by ‘install-data’.
  5407. Variables using the standard directory prefixes ‘bin’, ‘sbin’,
  5408. ‘libexec’, ‘sysconf’, ‘localstate’, ‘lib’, or ‘pkglib’ are installed by
  5409. ‘install-exec’.
  5410. For instance, ‘data_DATA’ files are installed by ‘install-data’,
  5411. while ‘bin_PROGRAMS’ files are installed by ‘install-exec’.
  5412. Any variable using a user-defined directory prefix with ‘exec’ in the
  5413. name (e.g., ‘myexecbin_PROGRAMS’) is installed by ‘install-exec’. All
  5414. other user-defined prefixes are installed by ‘install-data’.
  5415. 
  5416. File: automake.info, Node: Extending Installation, Next: Staged Installs, Prev: The Two Parts of Install, Up: Install
  5417. 12.3 Extending Installation
  5418. ===========================
  5419. It is possible to extend this mechanism by defining an
  5420. ‘install-exec-local’ or ‘install-data-local’ rule. If these rules
  5421. exist, they will be run at ‘make install’ time. These rules can do
  5422. almost anything; care is required.
  5423. Automake also supports two install hooks, ‘install-exec-hook’ and
  5424. ‘install-data-hook’. These hooks are run after all other install rules
  5425. of the appropriate type, exec or data, have completed. So, for
  5426. instance, it is possible to perform post-installation modifications
  5427. using an install hook. *Note Extending::, for some examples.