1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844684568466847684868496850685168526853685468556856685768586859686068616862686368646865686668676868686968706871687268736874687568766877687868796880688168826883688468856886688768886889689068916892689368946895689668976898689969006901690269036904690569066907690869096910691169126913691469156916 |
- This is automake.info, produced by makeinfo version 6.1 from
- automake.texi.
- This manual is for GNU Automake (version 1.15.1, 17 June 2017), a
- program that creates GNU standards-compliant Makefiles from template
- files.
- Copyright © 1995-2017 Free Software Foundation, Inc.
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation License,
- Version 1.3 or any later version published by the Free Software
- Foundation; with no Invariant Sections, with no Front-Cover texts,
- and with no Back-Cover Texts. A copy of the license is included in
- the section entitled “GNU Free Documentation License.”
- INFO-DIR-SECTION Software development
- START-INFO-DIR-ENTRY
- * Automake: (automake). Making GNU standards-compliant Makefiles.
- END-INFO-DIR-ENTRY
- INFO-DIR-SECTION Individual utilities
- START-INFO-DIR-ENTRY
- * aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4.
- * automake-invocation: (automake)automake Invocation. Generating Makefile.in.
- END-INFO-DIR-ENTRY
- File: automake.info, Node: Top, Next: Introduction, Up: (dir)
- GNU Automake
- ************
- This manual is for GNU Automake (version 1.15.1, 17 June 2017), a
- program that creates GNU standards-compliant Makefiles from template
- files.
- Copyright © 1995-2017 Free Software Foundation, Inc.
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation License,
- Version 1.3 or any later version published by the Free Software
- Foundation; with no Invariant Sections, with no Front-Cover texts,
- and with no Back-Cover Texts. A copy of the license is included in
- the section entitled “GNU Free Documentation License.”
- * Menu:
- * Introduction:: Automake’s purpose
- * Autotools Introduction:: An Introduction to the Autotools
- * Generalities:: General ideas
- * Examples:: Some example packages
- * automake Invocation:: Creating a Makefile.in
- * configure:: Scanning configure.ac, using aclocal
- * Directories:: Declaring subdirectories
- * Programs:: Building programs and libraries
- * Other Objects:: Other derived objects
- * Other GNU Tools:: Other GNU Tools
- * Documentation:: Building documentation
- * Install:: What gets installed
- * Clean:: What gets cleaned
- * Dist:: What goes in a distribution
- * Tests:: Support for test suites
- * Rebuilding:: Automatic rebuilding of Makefile
- * Options:: Changing Automake’s behavior
- * Miscellaneous:: Miscellaneous rules
- * Include:: Including extra files in an Automake template
- * Conditionals:: Conditionals
- * Silencing Make:: Obtain less verbose output from ‘make’
- * Gnits:: The effect of ‘--gnu’ and ‘--gnits’
- * Not Enough:: When Automake is not Enough
- * Distributing:: Distributing the Makefile.in
- * API Versioning:: About compatibility between Automake versions
- * Upgrading:: Upgrading to a Newer Automake Version
- * FAQ:: Frequently Asked Questions
- * Copying This Manual:: How to make copies of this manual
- * Indices:: Indices of variables, macros, and concepts
- — The Detailed Node Listing —
- An Introduction to the Autotools
- * GNU Build System:: Introducing the GNU Build System
- * Use Cases:: Use Cases for the GNU Build System
- * Why Autotools:: How Autotools Help
- * Hello World:: A Small Hello World Package
- Use Cases for the GNU Build System
- * Basic Installation:: Common installation procedure
- * Standard Targets:: A list of standard Makefile targets
- * Standard Directory Variables:: A list of standard directory variables
- * Standard Configuration Variables:: Using configuration variables
- * config.site:: Using a config.site file
- * VPATH Builds:: Parallel build trees
- * Two-Part Install:: Installing data and programs separately
- * Cross-Compilation:: Building for other architectures
- * Renaming:: Renaming programs at install time
- * DESTDIR:: Building binary packages with DESTDIR
- * Preparing Distributions:: Rolling out tarballs
- * Dependency Tracking:: Automatic dependency tracking
- * Nested Packages:: The GNU Build Systems can be nested
- A Small Hello World
- * Creating amhello:: Create ‘amhello-1.0.tar.gz’ from scratch
- * amhello's configure.ac Setup Explained::
- * amhello's Makefile.am Setup Explained::
- General ideas
- * General Operation:: General operation of Automake
- * Strictness:: Standards conformance checking
- * Uniform:: The Uniform Naming Scheme
- * Length Limitations:: Staying below the command line length limit
- * Canonicalization:: How derived variables are named
- * User Variables:: Variables reserved for the user
- * Auxiliary Programs:: Programs automake might require
- Some example packages
- * Complete:: A simple example, start to finish
- * true:: Building true and false
- Scanning ‘configure.ac’, using ‘aclocal’
- * Requirements:: Configuration requirements
- * Optional:: Other things Automake recognizes
- * aclocal Invocation:: Auto-generating aclocal.m4
- * Macros:: Autoconf macros supplied with Automake
- Auto-generating aclocal.m4
- * aclocal Options:: Options supported by aclocal
- * Macro Search Path:: How aclocal finds .m4 files
- * Extending aclocal:: Writing your own aclocal macros
- * Local Macros:: Organizing local macros
- * Serials:: Serial lines in Autoconf macros
- * Future of aclocal:: aclocal’s scheduled death
- Autoconf macros supplied with Automake
- * Public Macros:: Macros that you can use.
- * Private Macros:: Macros that you should not use.
- Directories
- * Subdirectories:: Building subdirectories recursively
- * Conditional Subdirectories:: Conditionally not building directories
- * Alternative:: Subdirectories without recursion
- * Subpackages:: Nesting packages
- Conditional Subdirectories
- * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
- * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
- * Subdirectories with AC_SUBST:: Another way for conditional recursion
- * Unconfigured Subdirectories:: Not even creating a ‘Makefile’
- Building Programs and Libraries
- * A Program:: Building a program
- * A Library:: Building a library
- * A Shared Library:: Building a Libtool library
- * Program and Library Variables:: Variables controlling program and
- library builds
- * Default _SOURCES:: Default source files
- * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
- * Program Variables:: Variables used when building a program
- * Yacc and Lex:: Yacc and Lex support
- * C++ Support:: Compiling C++ sources
- * Objective C Support:: Compiling Objective C sources
- * Objective C++ Support:: Compiling Objective C++ sources
- * Unified Parallel C Support:: Compiling Unified Parallel C sources
- * Assembly Support:: Compiling assembly sources
- * Fortran 77 Support:: Compiling Fortran 77 sources
- * Fortran 9x Support:: Compiling Fortran 9x sources
- * Java Support with gcj:: Compiling Java sources using gcj
- * Vala Support:: Compiling Vala sources
- * Support for Other Languages:: Compiling other languages
- * Dependencies:: Automatic dependency tracking
- * EXEEXT:: Support for executable extensions
- Building a program
- * Program Sources:: Defining program sources
- * Linking:: Linking with libraries or extra objects
- * Conditional Sources:: Handling conditional sources
- * Conditional Programs:: Building a program conditionally
- Building a Shared Library
- * Libtool Concept:: Introducing Libtool
- * Libtool Libraries:: Declaring Libtool Libraries
- * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
- * Conditional Libtool Sources:: Choosing Library Sources Conditionally
- * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
- * Libtool Modules:: Building Libtool Modules
- * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
- * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
- * Libtool Issues:: Common Issues Related to Libtool’s Use
- Common Issues Related to Libtool’s Use
- * Error required file ltmain.sh not found:: The need to run libtoolize
- * Objects created both with libtool and without:: Avoid a specific build race
- Fortran 77 Support
- * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
- * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
- * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
- Mixing Fortran 77 With C and C++
- * How the Linker is Chosen:: Automatic linker selection
- Fortran 9x Support
- * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
- Other Derived Objects
- * Scripts:: Executable scripts
- * Headers:: Header files
- * Data:: Architecture-independent data files
- * Sources:: Derived sources
- Built Sources
- * Built Sources Example:: Several ways to handle built sources.
- Other GNU Tools
- * Emacs Lisp:: Emacs Lisp
- * gettext:: Gettext
- * Libtool:: Libtool
- * Java:: Java bytecode compilation (deprecated)
- * Python:: Python
- Building documentation
- * Texinfo:: Texinfo
- * Man Pages:: Man pages
- What Gets Installed
- * Basics of Installation:: What gets installed where
- * The Two Parts of Install:: Installing data and programs separately
- * Extending Installation:: Adding your own rules for installation
- * Staged Installs:: Installation in a temporary location
- * Install Rules for the User:: Useful additional rules
- What Goes in a Distribution
- * Basics of Distribution:: Files distributed by default
- * Fine-grained Distribution Control:: ‘dist_’ and ‘nodist_’ prefixes
- * The dist Hook:: A target for last-minute distribution changes
- * Checking the Distribution:: ‘make distcheck’ explained
- * The Types of Distributions:: A variety of formats and compression methods
- Support for test suites
- * Generalities about Testing:: Generic concepts and terminology about testing
- * Simple Tests:: Listing test scripts in ‘TESTS’
- * Custom Test Drivers:: Writing and using custom test drivers
- * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
- * DejaGnu Tests:: Interfacing with the ‘dejagnu’ testing framework
- * Install Tests:: Running tests on installed packages
- Simple Tests
- * Scripts-based Testsuites:: Automake-specific concepts and terminology
- * Serial Test Harness:: Older (and discouraged) serial test harness
- * Parallel Test Harness:: Generic concurrent test harness
- Using the TAP test protocol
- * Introduction to TAP::
- * Use TAP with the Automake test harness::
- * Incompatibilities with other TAP parsers and drivers::
- * Links and external resources on TAP::
- Custom Test Drivers
- * Overview of Custom Test Drivers Support::
- * Declaring Custom Test Drivers::
- * API for Custom Test Drivers::
- API for Custom Test Drivers
- * Command-line arguments for test drivers::
- * Log files generation and test results recording::
- * Testsuite progress output::
- Changing Automake’s Behavior
- * Options generalities:: Semantics of Automake option
- * List of Automake options:: A comprehensive list of Automake options
- Miscellaneous Rules
- * Tags:: Interfacing to cscope, etags and mkid
- * Suffixes:: Handling new file extensions
- Conditionals
- * Usage of Conditionals:: Declaring conditional content
- * Limits of Conditionals:: Enclosing complete statements
- Silencing Make
- * Make verbosity:: Make is verbose by default
- * Tricks For Silencing Make:: Standard and generic ways to silence make
- * Automake Silent Rules:: How Automake can help in silencing make
- When Automake Isn’t Enough
- * Extending:: Adding new rules or overriding existing ones.
- * Third-Party Makefiles:: Integrating Non-Automake ‘Makefile’s.
- Frequently Asked Questions about Automake
- * CVS:: CVS and generated files
- * maintainer-mode:: missing and AM_MAINTAINER_MODE
- * Wildcards:: Why doesn’t Automake support wildcards?
- * Limitations on File Names:: Limitations on source and installed file names
- * Errors with distclean:: Files left in build directory after distclean
- * Flag Variables Ordering:: CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS
- * Renamed Objects:: Why are object files sometimes renamed?
- * Per-Object Flags:: How to simulate per-object flags?
- * Multiple Outputs:: Writing rules for tools with many output files
- * Hard-Coded Install Paths:: Installing to hard-coded locations
- * Debugging Make Rules:: Strategies when things don’t work as expected
- * Reporting Bugs:: Feedback on bugs and feature requests
- Copying This Manual
- * GNU Free Documentation License:: License for copying this manual
- Indices
- * Macro Index:: Index of Autoconf macros
- * Variable Index:: Index of Makefile variables
- * General Index:: General index
- File: automake.info, Node: Introduction, Next: Autotools Introduction, Prev: Top, Up: Top
- 1 Introduction
- **************
- Automake is a tool for automatically generating ‘Makefile.in’s from
- files called ‘Makefile.am’. Each ‘Makefile.am’ is basically a series of
- ‘make’ variable definitions(1), with rules being thrown in occasionally.
- The generated ‘Makefile.in’s are compliant with the GNU Makefile
- standards.
- The GNU Makefile Standards Document (*note (standards)Makefile
- Conventions::) is long, complicated, and subject to change. The goal of
- Automake is to remove the burden of Makefile maintenance from the back
- of the individual GNU maintainer (and put it on the back of the Automake
- maintainers).
- The typical Automake input file is simply a series of variable
- definitions. Each such file is processed to create a ‘Makefile.in’.
- Automake does constrain a project in certain ways; for instance, it
- assumes that the project uses Autoconf (*note Introduction:
- (autoconf)Top.), and enforces certain restrictions on the ‘configure.ac’
- contents.
- Automake requires ‘perl’ in order to generate the ‘Makefile.in’s.
- However, the distributions created by Automake are fully GNU
- standards-compliant, and do not require ‘perl’ in order to be built.
- For more information on bug reports, *Note Reporting Bugs::.
- ---------- Footnotes ----------
- (1) These variables are also called “make macros” in Make
- terminology, however in this manual we reserve the term “macro” for
- Autoconf’s macros.
- File: automake.info, Node: Autotools Introduction, Next: Generalities, Prev: Introduction, Up: Top
- 2 An Introduction to the Autotools
- **********************************
- If you are new to Automake, maybe you know that it is part of a set of
- tools called _The Autotools_. Maybe you’ve already delved into a
- package full of files named ‘configure’, ‘configure.ac’, ‘Makefile.in’,
- ‘Makefile.am’, ‘aclocal.m4’, ..., some of them claiming to be _generated
- by_ Autoconf or Automake. But the exact purpose of these files and
- their relations is probably fuzzy. The goal of this chapter is to
- introduce you to this machinery, to show you how it works and how
- powerful it is. If you’ve never installed or seen such a package, do
- not worry: this chapter will walk you through it.
- If you need some teaching material, more illustrations, or a less
- ‘automake’-centered continuation, some slides for this introduction are
- available in Alexandre Duret-Lutz’s Autotools Tutorial
- (http://www.lrde.epita.fr/~adl/autotools.html). This chapter is the
- written version of the first part of his tutorial.
- * Menu:
- * GNU Build System:: Introducing the GNU Build System
- * Use Cases:: Use Cases for the GNU Build System
- * Why Autotools:: How Autotools Help
- * Hello World:: A Small Hello World Package
- File: automake.info, Node: GNU Build System, Next: Use Cases, Up: Autotools Introduction
- 2.1 Introducing the GNU Build System
- ====================================
- It is a truth universally acknowledged, that as a developer in
- possession of a new package, you must be in want of a build system.
- In the Unix world, such a build system is traditionally achieved
- using the command ‘make’ (*note Overview: (make)Top.). You express the
- recipe to build your package in a ‘Makefile’. This file is a set of
- rules to build the files in the package. For instance the program
- ‘prog’ may be built by running the linker on the files ‘main.o’,
- ‘foo.o’, and ‘bar.o’; the file ‘main.o’ may be built by running the
- compiler on ‘main.c’; etc. Each time ‘make’ is run, it reads
- ‘Makefile’, checks the existence and modification time of the files
- mentioned, decides what files need to be built (or rebuilt), and runs
- the associated commands.
- When a package needs to be built on a different platform than the one
- it was developed on, its ‘Makefile’ usually needs to be adjusted. For
- instance the compiler may have another name or require more options. In
- 1991, David J. MacKenzie got tired of customizing ‘Makefile’ for the 20
- platforms he had to deal with. Instead, he handcrafted a little shell
- script called ‘configure’ to automatically adjust the ‘Makefile’ (*note
- Genesis: (autoconf)Genesis.). Compiling his package was now as simple
- as running ‘./configure && make’.
- Today this process has been standardized in the GNU project. The GNU
- Coding Standards (*note The Release Process: (standards)Managing
- Releases.) explains how each package of the GNU project should have a
- ‘configure’ script, and the minimal interface it should have. The
- ‘Makefile’ too should follow some established conventions. The result?
- A unified build system that makes all packages almost indistinguishable
- by the installer. In its simplest scenario, all the installer has to do
- is to unpack the package, run ‘./configure && make && make install’, and
- repeat with the next package to install.
- We call this build system the “GNU Build System”, since it was grown
- out of the GNU project. However it is used by a vast number of other
- packages: following any existing convention has its advantages.
- The Autotools are tools that will create a GNU Build System for your
- package. Autoconf mostly focuses on ‘configure’ and Automake on
- ‘Makefile’s. It is entirely possible to create a GNU Build System
- without the help of these tools. However it is rather burdensome and
- error-prone. We will discuss this again after some illustration of the
- GNU Build System in action.
- File: automake.info, Node: Use Cases, Next: Why Autotools, Prev: GNU Build System, Up: Autotools Introduction
- 2.2 Use Cases for the GNU Build System
- ======================================
- In this section we explore several use cases for the GNU Build System.
- You can replay all of these examples on the ‘amhello-1.0.tar.gz’ package
- distributed with Automake. If Automake is installed on your system, you
- should find a copy of this file in
- ‘PREFIX/share/doc/automake/amhello-1.0.tar.gz’, where PREFIX is the
- installation prefix specified during configuration (PREFIX defaults to
- ‘/usr/local’, however if Automake was installed by some GNU/Linux
- distribution it most likely has been set to ‘/usr’). If you do not have
- a copy of Automake installed, you can find a copy of this file inside
- the ‘doc/’ directory of the Automake package.
- Some of the following use cases present features that are in fact
- extensions to the GNU Build System. Read: they are not specified by the
- GNU Coding Standards, but they are nonetheless part of the build system
- created by the Autotools. To keep things simple, we do not point out
- the difference. Our objective is to show you many of the features that
- the build system created by the Autotools will offer to you.
- * Menu:
- * Basic Installation:: Common installation procedure
- * Standard Targets:: A list of standard Makefile targets
- * Standard Directory Variables:: A list of standard directory variables
- * Standard Configuration Variables:: Using configuration variables
- * config.site:: Using a config.site file
- * VPATH Builds:: Parallel build trees
- * Two-Part Install:: Installing data and programs separately
- * Cross-Compilation:: Building for other architectures
- * Renaming:: Renaming programs at install time
- * DESTDIR:: Building binary packages with DESTDIR
- * Preparing Distributions:: Rolling out tarballs
- * Dependency Tracking:: Automatic dependency tracking
- * Nested Packages:: The GNU Build Systems can be nested
- File: automake.info, Node: Basic Installation, Next: Standard Targets, Up: Use Cases
- 2.2.1 Basic Installation
- ------------------------
- The most common installation procedure looks as follows.
- ~ % tar zxf amhello-1.0.tar.gz
- ~ % cd amhello-1.0
- ~/amhello-1.0 % ./configure
- ...
- config.status: creating Makefile
- config.status: creating src/Makefile
- ...
- ~/amhello-1.0 % make
- ...
- ~/amhello-1.0 % make check
- ...
- ~/amhello-1.0 % su
- Password:
- /home/adl/amhello-1.0 # make install
- ...
- /home/adl/amhello-1.0 # exit
- ~/amhello-1.0 % make installcheck
- ...
- The user first unpacks the package. Here, and in the following
- examples, we will use the non-portable ‘tar zxf’ command for simplicity.
- On a system without GNU ‘tar’ installed, this command should read
- ‘gunzip -c amhello-1.0.tar.gz | tar xf -’.
- The user then enters the newly created directory to run the
- ‘configure’ script. This script probes the system for various features,
- and finally creates the ‘Makefile’s. In this toy example there are only
- two ‘Makefile’s, but in real-world projects, there may be many more,
- usually one ‘Makefile’ per directory.
- It is now possible to run ‘make’. This will construct all the
- programs, libraries, and scripts that need to be constructed for the
- package. In our example, this compiles the ‘hello’ program. All files
- are constructed in place, in the source tree; we will see later how this
- can be changed.
- ‘make check’ causes the package’s tests to be run. This step is not
- mandatory, but it is often good to make sure the programs that have been
- built behave as they should, before you decide to install them. Our
- example does not contain any tests, so running ‘make check’ is a no-op.
- After everything has been built, and maybe tested, it is time to
- install it on the system. That means copying the programs, libraries,
- header files, scripts, and other data files from the source directory to
- their final destination on the system. The command ‘make install’ will
- do that. However, by default everything will be installed in
- subdirectories of ‘/usr/local’: binaries will go into ‘/usr/local/bin’,
- libraries will end up in ‘/usr/local/lib’, etc. This destination is
- usually not writable by any user, so we assume that we have to become
- root before we can run ‘make install’. In our example, running ‘make
- install’ will copy the program ‘hello’ into ‘/usr/local/bin’ and
- ‘README’ into ‘/usr/local/share/doc/amhello’.
- A last and optional step is to run ‘make installcheck’. This command
- may run tests on the installed files. ‘make check’ tests the files in
- the source tree, while ‘make installcheck’ tests their installed copies.
- The tests run by the latter can be different from those run by the
- former. For instance, there are tests that cannot be run in the source
- tree. Conversely, some packages are set up so that ‘make installcheck’
- will run the very same tests as ‘make check’, only on different files
- (non-installed vs. installed). It can make a difference, for instance
- when the source tree’s layout is different from that of the
- installation. Furthermore it may help to diagnose an incomplete
- installation.
- Presently most packages do not have any ‘installcheck’ tests because
- the existence of ‘installcheck’ is little known, and its usefulness is
- neglected. Our little toy package is no better: ‘make installcheck’
- does nothing.
- File: automake.info, Node: Standard Targets, Next: Standard Directory Variables, Prev: Basic Installation, Up: Use Cases
- 2.2.2 Standard ‘Makefile’ Targets
- ---------------------------------
- So far we have come across four ways to run ‘make’ in the GNU Build
- System: ‘make’, ‘make check’, ‘make install’, and ‘make installcheck’.
- The words ‘check’, ‘install’, and ‘installcheck’, passed as arguments to
- ‘make’, are called “targets”. ‘make’ is a shorthand for ‘make all’,
- ‘all’ being the default target in the GNU Build System.
- Here is a list of the most useful targets that the GNU Coding
- Standards specify.
- ‘make all’
- Build programs, libraries, documentation, etc. (same as ‘make’).
- ‘make install’
- Install what needs to be installed, copying the files from the
- package’s tree to system-wide directories.
- ‘make install-strip’
- Same as ‘make install’, then strip debugging symbols. Some users
- like to trade space for useful bug reports...
- ‘make uninstall’
- The opposite of ‘make install’: erase the installed files. (This
- needs to be run from the same build tree that was installed.)
- ‘make clean’
- Erase from the build tree the files built by ‘make all’.
- ‘make distclean’
- Additionally erase anything ‘./configure’ created.
- ‘make check’
- Run the test suite, if any.
- ‘make installcheck’
- Check the installed programs or libraries, if supported.
- ‘make dist’
- Recreate ‘PACKAGE-VERSION.tar.gz’ from all the source files.
- File: automake.info, Node: Standard Directory Variables, Next: Standard Configuration Variables, Prev: Standard Targets, Up: Use Cases
- 2.2.3 Standard Directory Variables
- ----------------------------------
- The GNU Coding Standards also specify a hierarchy of variables to denote
- installation directories. Some of these are:
- Directory variable Default value
- -------------------------------------------------------
- ‘prefix’ ‘/usr/local’
- ‘exec_prefix’ ‘${prefix}’
- ‘bindir’ ‘${exec_prefix}/bin’
- ‘libdir’ ‘${exec_prefix}/lib’
- ...
- ‘includedir’ ‘${prefix}/include’
- ‘datarootdir’ ‘${prefix}/share’
- ‘datadir’ ‘${datarootdir}’
- ‘mandir’ ‘${datarootdir}/man’
- ‘infodir’ ‘${datarootdir}/info’
- ‘docdir’ ‘${datarootdir}/doc/${PACKAGE}’
- ...
- Each of these directories has a role which is often obvious from its
- name. In a package, any installable file will be installed in one of
- these directories. For instance in ‘amhello-1.0’, the program ‘hello’
- is to be installed in BINDIR, the directory for binaries. The default
- value for this directory is ‘/usr/local/bin’, but the user can supply a
- different value when calling ‘configure’. Also the file ‘README’ will
- be installed into DOCDIR, which defaults to
- ‘/usr/local/share/doc/amhello’.
- As a user, if you wish to install a package on your own account, you
- could proceed as follows:
- ~/amhello-1.0 % ./configure --prefix ~/usr
- ...
- ~/amhello-1.0 % make
- ...
- ~/amhello-1.0 % make install
- ...
- This would install ‘~/usr/bin/hello’ and
- ‘~/usr/share/doc/amhello/README’.
- The list of all such directory options is shown by ‘./configure
- --help’.
- File: automake.info, Node: Standard Configuration Variables, Next: config.site, Prev: Standard Directory Variables, Up: Use Cases
- 2.2.4 Standard Configuration Variables
- --------------------------------------
- The GNU Coding Standards also define a set of standard configuration
- variables used during the build. Here are some:
- ‘CC’
- C compiler command
- ‘CFLAGS’
- C compiler flags
- ‘CXX’
- C++ compiler command
- ‘CXXFLAGS’
- C++ compiler flags
- ‘LDFLAGS’
- linker flags
- ‘CPPFLAGS’
- C/C++ preprocessor flags
- ...
- ‘configure’ usually does a good job at setting appropriate values for
- these variables, but there are cases where you may want to override
- them. For instance you may have several versions of a compiler
- installed and would like to use another one, you may have header files
- installed outside the default search path of the compiler, or even
- libraries out of the way of the linker.
- Here is how one would call ‘configure’ to force it to use ‘gcc-3’ as
- C compiler, use header files from ‘~/usr/include’ when compiling, and
- libraries from ‘~/usr/lib’ when linking.
- ~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \
- CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib
- Again, a full list of these variables appears in the output of
- ‘./configure --help’.
- File: automake.info, Node: config.site, Next: VPATH Builds, Prev: Standard Configuration Variables, Up: Use Cases
- 2.2.5 Overriding Default Configuration Setting with ‘config.site’
- -----------------------------------------------------------------
- When installing several packages using the same setup, it can be
- convenient to create a file to capture common settings. If a file named
- ‘PREFIX/share/config.site’ exists, ‘configure’ will source it at the
- beginning of its execution.
- Recall the command from the previous section:
- ~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \
- CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib
- Assuming we are installing many package in ‘~/usr’, and will always
- want to use these definitions of ‘CC’, ‘CPPFLAGS’, and ‘LDFLAGS’, we can
- automate this by creating the following ‘~/usr/share/config.site’ file:
- test -z "$CC" && CC=gcc-3
- test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
- test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
- Now, any time a ‘configure’ script is using the ‘~/usr’ prefix, it
- will execute the above ‘config.site’ and define these three variables.
- ~/amhello-1.0 % ./configure --prefix ~/usr
- configure: loading site script /home/adl/usr/share/config.site
- ...
- *Note Setting Site Defaults: (autoconf)Site Defaults, for more
- information about this feature.
- File: automake.info, Node: VPATH Builds, Next: Two-Part Install, Prev: config.site, Up: Use Cases
- 2.2.6 Parallel Build Trees (a.k.a. VPATH Builds)
- ------------------------------------------------
- The GNU Build System distinguishes two trees: the source tree, and the
- build tree.
- The source tree is rooted in the directory containing ‘configure’.
- It contains all the sources files (those that are distributed), and may
- be arranged using several subdirectories.
- The build tree is rooted in the directory in which ‘configure’ was
- run, and is populated with all object files, programs, libraries, and
- other derived files built from the sources (and hence not distributed).
- The build tree usually has the same subdirectory layout as the source
- tree; its subdirectories are created automatically by the build system.
- If ‘configure’ is executed in its own directory, the source and build
- trees are combined: derived files are constructed in the same
- directories as their sources. This was the case in our first
- installation example (*note Basic Installation::).
- A common request from users is that they want to confine all derived
- files to a single directory, to keep their source directories
- uncluttered. Here is how we could run ‘configure’ to build everything
- in a subdirectory called ‘build/’.
- ~ % tar zxf ~/amhello-1.0.tar.gz
- ~ % cd amhello-1.0
- ~/amhello-1.0 % mkdir build && cd build
- ~/amhello-1.0/build % ../configure
- ...
- ~/amhello-1.0/build % make
- ...
- These setups, where source and build trees are different, are often
- called “parallel builds” or “VPATH builds”. The expression _parallel
- build_ is misleading: the word _parallel_ is a reference to the way the
- build tree shadows the source tree, it is not about some concurrency in
- the way build commands are run. For this reason we refer to such setups
- using the name _VPATH builds_ in the following. _VPATH_ is the name of
- the ‘make’ feature used by the ‘Makefile’s to allow these builds (*note
- ‘VPATH’ Search Path for All Prerequisites: (make)General Search.).
- VPATH builds have other interesting uses. One is to build the same
- sources with multiple configurations. For instance:
- ~ % tar zxf ~/amhello-1.0.tar.gz
- ~ % cd amhello-1.0
- ~/amhello-1.0 % mkdir debug optim && cd debug
- ~/amhello-1.0/debug % ../configure CFLAGS='-g -O0'
- ...
- ~/amhello-1.0/debug % make
- ...
- ~/amhello-1.0/debug % cd ../optim
- ~/amhello-1.0/optim % ../configure CFLAGS='-O3 -fomit-frame-pointer'
- ...
- ~/amhello-1.0/optim % make
- ...
- With network file systems, a similar approach can be used to build
- the same sources on different machines. For instance, suppose that the
- sources are installed on a directory shared by two hosts: ‘HOST1’ and
- ‘HOST2’, which may be different platforms.
- ~ % cd /nfs/src
- /nfs/src % tar zxf ~/amhello-1.0.tar.gz
- On the first host, you could create a local build directory:
- [HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh
- [HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure
- ...
- [HOST1] /tmp/amh % make && sudo make install
- ...
- (Here we assume that the installer has configured ‘sudo’ so it can
- execute ‘make install’ with root privileges; it is more convenient than
- using ‘su’ like in *note Basic Installation::).
- On the second host, you would do exactly the same, possibly at the
- same time:
- [HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh
- [HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure
- ...
- [HOST2] /tmp/amh % make && sudo make install
- ...
- In this scenario, nothing forbids the ‘/nfs/src/amhello-1.0’
- directory from being read-only. In fact VPATH builds are also a means
- of building packages from a read-only medium such as a CD-ROM. (The FSF
- used to sell CD-ROM with unpacked source code, before the GNU project
- grew so big.)
- File: automake.info, Node: Two-Part Install, Next: Cross-Compilation, Prev: VPATH Builds, Up: Use Cases
- 2.2.7 Two-Part Installation
- ---------------------------
- In our last example (*note VPATH Builds::), a source tree was shared by
- two hosts, but compilation and installation were done separately on each
- host.
- The GNU Build System also supports networked setups where part of the
- installed files should be shared amongst multiple hosts. It does so by
- distinguishing architecture-dependent files from
- architecture-independent files, and providing two ‘Makefile’ targets to
- install each of these classes of files.
- These targets are ‘install-exec’ for architecture-dependent files and
- ‘install-data’ for architecture-independent files. The command we used
- up to now, ‘make install’, can be thought of as a shorthand for ‘make
- install-exec install-data’.
- From the GNU Build System point of view, the distinction between
- architecture-dependent files and architecture-independent files is based
- exclusively on the directory variable used to specify their installation
- destination. In the list of directory variables we provided earlier
- (*note Standard Directory Variables::), all the variables based on
- EXEC-PREFIX designate architecture-dependent directories whose files
- will be installed by ‘make install-exec’. The others designate
- architecture-independent directories and will serve files installed by
- ‘make install-data’. *Note The Two Parts of Install::, for more
- details.
- Here is how we could revisit our two-host installation example,
- assuming that (1) we want to install the package directly in ‘/usr’, and
- (2) the directory ‘/usr/share’ is shared by the two hosts.
- On the first host we would run
- [HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh
- [HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure --prefix /usr
- ...
- [HOST1] /tmp/amh % make && sudo make install
- ...
- On the second host, however, we need only install the
- architecture-specific files.
- [HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh
- [HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure --prefix /usr
- ...
- [HOST2] /tmp/amh % make && sudo make install-exec
- ...
- In packages that have installation checks, it would make sense to run
- ‘make installcheck’ (*note Basic Installation::) to verify that the
- package works correctly despite the apparent partial installation.
- File: automake.info, Node: Cross-Compilation, Next: Renaming, Prev: Two-Part Install, Up: Use Cases
- 2.2.8 Cross-Compilation
- -----------------------
- To “cross-compile” is to build on one platform a binary that will run on
- another platform. When speaking of cross-compilation, it is important
- to distinguish between the “build platform” on which the compilation is
- performed, and the “host platform” on which the resulting executable is
- expected to run. The following ‘configure’ options are used to specify
- each of them:
- ‘--build=BUILD’
- The system on which the package is built.
- ‘--host=HOST’
- The system where built programs and libraries will run.
- When the ‘--host’ is used, ‘configure’ will search for the
- cross-compiling suite for this platform. Cross-compilation tools
- commonly have their target architecture as prefix of their name. For
- instance my cross-compiler for MinGW32 has its binaries called
- ‘i586-mingw32msvc-gcc’, ‘i586-mingw32msvc-ld’, ‘i586-mingw32msvc-as’,
- etc.
- Here is how we could build ‘amhello-1.0’ for ‘i586-mingw32msvc’ on a
- GNU/Linux PC.
- ~/amhello-1.0 % ./configure --build i686-pc-linux-gnu --host i586-mingw32msvc
- checking for a BSD-compatible install... /usr/bin/install -c
- checking whether build environment is sane... yes
- checking for gawk... gawk
- checking whether make sets $(MAKE)... yes
- checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
- checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
- checking for C compiler default output file name... a.exe
- checking whether the C compiler works... yes
- checking whether we are cross compiling... yes
- checking for suffix of executables... .exe
- checking for suffix of object files... o
- checking whether we are using the GNU C compiler... yes
- checking whether i586-mingw32msvc-gcc accepts -g... yes
- checking for i586-mingw32msvc-gcc option to accept ANSI C...
- ...
- ~/amhello-1.0 % make
- ...
- ~/amhello-1.0 % cd src; file hello.exe
- hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
- The ‘--host’ and ‘--build’ options are usually all we need for
- cross-compiling. The only exception is if the package being built is
- itself a cross-compiler: we need a third option to specify its target
- architecture.
- ‘--target=TARGET’
- When building compiler tools: the system for which the tools will
- create output.
- For instance when installing GCC, the GNU Compiler Collection, we can
- use ‘--target=TARGET’ to specify that we want to build GCC as a
- cross-compiler for TARGET. Mixing ‘--build’ and ‘--target’, we can
- actually cross-compile a cross-compiler; such a three-way
- cross-compilation is known as a “Canadian cross”.
- *Note Specifying the System Type: (autoconf)Specifying Names, for
- more information about these ‘configure’ options.
- File: automake.info, Node: Renaming, Next: DESTDIR, Prev: Cross-Compilation, Up: Use Cases
- 2.2.9 Renaming Programs at Install Time
- ---------------------------------------
- The GNU Build System provides means to automatically rename executables
- and manpages before they are installed (*note Man Pages::). This is
- especially convenient when installing a GNU package on a system that
- already has a proprietary implementation you do not want to overwrite.
- For instance, you may want to install GNU ‘tar’ as ‘gtar’ so you can
- distinguish it from your vendor’s ‘tar’.
- This can be done using one of these three ‘configure’ options.
- ‘--program-prefix=PREFIX’
- Prepend PREFIX to installed program names.
- ‘--program-suffix=SUFFIX’
- Append SUFFIX to installed program names.
- ‘--program-transform-name=PROGRAM’
- Run ‘sed PROGRAM’ on installed program names.
- The following commands would install ‘hello’ as
- ‘/usr/local/bin/test-hello’, for instance.
- ~/amhello-1.0 % ./configure --program-prefix test-
- ...
- ~/amhello-1.0 % make
- ...
- ~/amhello-1.0 % sudo make install
- ...
- File: automake.info, Node: DESTDIR, Next: Preparing Distributions, Prev: Renaming, Up: Use Cases
- 2.2.10 Building Binary Packages Using DESTDIR
- ---------------------------------------------
- The GNU Build System’s ‘make install’ and ‘make uninstall’ interface
- does not exactly fit the needs of a system administrator who has to
- deploy and upgrade packages on lots of hosts. In other words, the GNU
- Build System does not replace a package manager.
- Such package managers usually need to know which files have been
- installed by a package, so a mere ‘make install’ is inappropriate.
- The ‘DESTDIR’ variable can be used to perform a staged installation.
- The package should be configured as if it was going to be installed in
- its final location (e.g., ‘--prefix /usr’), but when running ‘make
- install’, the ‘DESTDIR’ should be set to the absolute name of a
- directory into which the installation will be diverted. From this
- directory it is easy to review which files are being installed where,
- and finally copy them to their final location by some means.
- For instance here is how we could create a binary package containing
- a snapshot of all the files to be installed.
- ~/amhello-1.0 % ./configure --prefix /usr
- ...
- ~/amhello-1.0 % make
- ...
- ~/amhello-1.0 % make DESTDIR=$HOME/inst install
- ...
- ~/amhello-1.0 % cd ~/inst
- ~/inst % find . -type f -print > ../files.lst
- ~/inst % tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`
- ./usr/bin/hello
- ./usr/share/doc/amhello/README
- After this example, ‘amhello-1.0-i686.tar.gz’ is ready to be
- uncompressed in ‘/’ on many hosts. (Using ‘`cat ../files.lst`’ instead
- of ‘.’ as argument for ‘tar’ avoids entries for each subdirectory in the
- archive: we would not like ‘tar’ to restore the modification time of
- ‘/’, ‘/usr/’, etc.)
- Note that when building packages for several architectures, it might
- be convenient to use ‘make install-data’ and ‘make install-exec’ (*note
- Two-Part Install::) to gather architecture-independent files in a single
- package.
- *Note Install::, for more information.
- File: automake.info, Node: Preparing Distributions, Next: Dependency Tracking, Prev: DESTDIR, Up: Use Cases
- 2.2.11 Preparing Distributions
- ------------------------------
- We have already mentioned ‘make dist’. This target collects all your
- source files and the necessary parts of the build system to create a
- tarball named ‘PACKAGE-VERSION.tar.gz’.
- Another, more useful command is ‘make distcheck’. The ‘distcheck’
- target constructs ‘PACKAGE-VERSION.tar.gz’ just as well as ‘dist’, but
- it additionally ensures most of the use cases presented so far work:
- • It attempts a full compilation of the package (*note Basic
- Installation::), unpacking the newly constructed tarball, running
- ‘make’, ‘make check’, ‘make install’, as well as ‘make
- installcheck’, and even ‘make dist’,
- • it tests VPATH builds with read-only source tree (*note VPATH
- Builds::),
- • it makes sure ‘make clean’, ‘make distclean’, and ‘make uninstall’
- do not omit any file (*note Standard Targets::),
- • and it checks that ‘DESTDIR’ installations work (*note DESTDIR::).
- All of these actions are performed in a temporary directory, so that
- no root privileges are required. Please note that the exact location
- and the exact structure of such a subdirectory (where the extracted
- sources are placed, how the temporary build and install directories are
- named and how deeply they are nested, etc.) is to be considered an
- implementation detail, which can change at any time; so do not rely on
- it.
- Releasing a package that fails ‘make distcheck’ means that one of the
- scenarios we presented will not work and some users will be
- disappointed. Therefore it is a good practice to release a package only
- after a successful ‘make distcheck’. This of course does not imply that
- the package will be flawless, but at least it will prevent some of the
- embarrassing errors you may find in packages released by people who have
- never heard about ‘distcheck’ (like ‘DESTDIR’ not working because of a
- typo, or a distributed file being erased by ‘make clean’, or even
- ‘VPATH’ builds not working).
- *Note Creating amhello::, to recreate ‘amhello-1.0.tar.gz’ using
- ‘make distcheck’. *Note Checking the Distribution::, for more
- information about ‘distcheck’.
- File: automake.info, Node: Dependency Tracking, Next: Nested Packages, Prev: Preparing Distributions, Up: Use Cases
- 2.2.12 Automatic Dependency Tracking
- ------------------------------------
- Dependency tracking is performed as a side-effect of compilation. Each
- time the build system compiles a source file, it computes its list of
- dependencies (in C these are the header files included by the source
- being compiled). Later, any time ‘make’ is run and a dependency appears
- to have changed, the dependent files will be rebuilt.
- Automake generates code for automatic dependency tracking by default,
- unless the developer chooses to override it; for more information, *note
- Dependencies::.
- When ‘configure’ is executed, you can see it probing each compiler
- for the dependency mechanism it supports (several mechanisms can be
- used):
- ~/amhello-1.0 % ./configure --prefix /usr
- ...
- checking dependency style of gcc... gcc3
- ...
- Because dependencies are only computed as a side-effect of the
- compilation, no dependency information exists the first time a package
- is built. This is OK because all the files need to be built anyway:
- ‘make’ does not have to decide which files need to be rebuilt. In fact,
- dependency tracking is completely useless for one-time builds and there
- is a ‘configure’ option to disable this:
- ‘--disable-dependency-tracking’
- Speed up one-time builds.
- Some compilers do not offer any practical way to derive the list of
- dependencies as a side-effect of the compilation, requiring a separate
- run (maybe of another tool) to compute these dependencies. The
- performance penalty implied by these methods is important enough to
- disable them by default. The option ‘--enable-dependency-tracking’ must
- be passed to ‘configure’ to activate them.
- ‘--enable-dependency-tracking’
- Do not reject slow dependency extractors.
- *Note Dependency Tracking Evolution: (automake-history)Dependency
- Tracking Evolution, for some discussion about the different dependency
- tracking schemes used by Automake over the years.
- File: automake.info, Node: Nested Packages, Prev: Dependency Tracking, Up: Use Cases
- 2.2.13 Nested Packages
- ----------------------
- Although nesting packages isn’t something we would recommend to someone
- who is discovering the Autotools, it is a nice feature worthy of mention
- in this small advertising tour.
- Autoconfiscated packages (that means packages whose build system have
- been created by Autoconf and friends) can be nested to arbitrary depth.
- A typical setup is that package A will distribute one of the
- libraries it needs in a subdirectory. This library B is a complete
- package with its own GNU Build System. The ‘configure’ script of A will
- run the ‘configure’ script of B as part of its execution, building and
- installing A will also build and install B. Generating a distribution
- for A will also include B.
- It is possible to gather several packages like this. GCC is a heavy
- user of this feature. This gives installers a single package to
- configure, build and install, while it allows developers to work on
- subpackages independently.
- When configuring nested packages, the ‘configure’ options given to
- the top-level ‘configure’ are passed recursively to nested ‘configure’s.
- A package that does not understand an option will ignore it, assuming it
- is meaningful to some other package.
- The command ‘configure --help=recursive’ can be used to display the
- options supported by all the included packages.
- *Note Subpackages::, for an example setup.
- File: automake.info, Node: Why Autotools, Next: Hello World, Prev: Use Cases, Up: Autotools Introduction
- 2.3 How Autotools Help
- ======================
- There are several reasons why you may not want to implement the GNU
- Build System yourself (read: write a ‘configure’ script and ‘Makefile’s
- yourself).
- • As we have seen, the GNU Build System has a lot of features (*note
- Use Cases::). Some users may expect features you have not
- implemented because you did not need them.
- • Implementing these features portably is difficult and exhausting.
- Think of writing portable shell scripts, and portable ‘Makefile’s,
- for systems you may not have handy. *Note Portable Shell
- Programming: (autoconf)Portable Shell, to convince yourself.
- • You will have to upgrade your setup to follow changes to the GNU
- Coding Standards.
- The GNU Autotools take all this burden off your back and provide:
- • Tools to create a portable, complete, and self-contained GNU Build
- System, from simple instructions. _Self-contained_ meaning the
- resulting build system does not require the GNU Autotools.
- • A central place where fixes and improvements are made: a bug-fix
- for a portability issue will benefit every package.
- Yet there also exist reasons why you may want NOT to use the
- Autotools... For instance you may be already using (or used to) another
- incompatible build system. Autotools will only be useful if you do
- accept the concepts of the GNU Build System. People who have their own
- idea of how a build system should work will feel frustrated by the
- Autotools.
- File: automake.info, Node: Hello World, Prev: Why Autotools, Up: Autotools Introduction
- 2.4 A Small Hello World
- =======================
- In this section we recreate the ‘amhello-1.0’ package from scratch. The
- first subsection shows how to call the Autotools to instantiate the GNU
- Build System, while the second explains the meaning of the
- ‘configure.ac’ and ‘Makefile.am’ files read by the Autotools.
- * Menu:
- * Creating amhello:: Create ‘amhello-1.0.tar.gz’ from scratch
- * amhello's configure.ac Setup Explained::
- * amhello's Makefile.am Setup Explained::
- File: automake.info, Node: Creating amhello, Next: amhello's configure.ac Setup Explained, Up: Hello World
- 2.4.1 Creating ‘amhello-1.0.tar.gz’
- -----------------------------------
- Here is how we can recreate ‘amhello-1.0.tar.gz’ from scratch. The
- package is simple enough so that we will only need to write 5 files.
- (You may copy them from the final ‘amhello-1.0.tar.gz’ that is
- distributed with Automake if you do not want to write them.)
- Create the following files in an empty directory.
- • ‘src/main.c’ is the source file for the ‘hello’ program. We store
- it in the ‘src/’ subdirectory, because later, when the package
- evolves, it will ease the addition of a ‘man/’ directory for man
- pages, a ‘data/’ directory for data files, etc.
- ~/amhello % cat src/main.c
- #include <config.h>
- #include <stdio.h>
- int
- main (void)
- {
- puts ("Hello World!");
- puts ("This is " PACKAGE_STRING ".");
- return 0;
- }
- • ‘README’ contains some very limited documentation for our little
- package.
- ~/amhello % cat README
- This is a demonstration package for GNU Automake.
- Type 'info Automake' to read the Automake manual.
- • ‘Makefile.am’ and ‘src/Makefile.am’ contain Automake instructions
- for these two directories.
- ~/amhello % cat src/Makefile.am
- bin_PROGRAMS = hello
- hello_SOURCES = main.c
- ~/amhello % cat Makefile.am
- SUBDIRS = src
- dist_doc_DATA = README
- • Finally, ‘configure.ac’ contains Autoconf instructions to create
- the ‘configure’ script.
- ~/amhello % cat configure.ac
- AC_INIT([amhello], [1.0], [bug-automake@gnu.org])
- AM_INIT_AUTOMAKE([-Wall -Werror foreign])
- AC_PROG_CC
- AC_CONFIG_HEADERS([config.h])
- AC_CONFIG_FILES([
- Makefile
- src/Makefile
- ])
- AC_OUTPUT
- Once you have these five files, it is time to run the Autotools to
- instantiate the build system. Do this using the ‘autoreconf’ command as
- follows:
- ~/amhello % autoreconf --install
- configure.ac: installing './install-sh'
- configure.ac: installing './missing'
- configure.ac: installing './compile'
- src/Makefile.am: installing './depcomp'
- At this point the build system is complete.
- In addition to the three scripts mentioned in its output, you can see
- that ‘autoreconf’ created four other files: ‘configure’, ‘config.h.in’,
- ‘Makefile.in’, and ‘src/Makefile.in’. The latter three files are
- templates that will be adapted to the system by ‘configure’ under the
- names ‘config.h’, ‘Makefile’, and ‘src/Makefile’. Let’s do this:
- ~/amhello % ./configure
- checking for a BSD-compatible install... /usr/bin/install -c
- checking whether build environment is sane... yes
- checking for gawk... no
- checking for mawk... mawk
- checking whether make sets $(MAKE)... yes
- checking for gcc... gcc
- checking for C compiler default output file name... a.out
- checking whether the C compiler works... yes
- checking whether we are cross compiling... no
- checking for suffix of executables...
- checking for suffix of object files... o
- checking whether we are using the GNU C compiler... yes
- checking whether gcc accepts -g... yes
- checking for gcc option to accept ISO C89... none needed
- checking for style of include used by make... GNU
- checking dependency style of gcc... gcc3
- configure: creating ./config.status
- config.status: creating Makefile
- config.status: creating src/Makefile
- config.status: creating config.h
- config.status: executing depfiles commands
- You can see ‘Makefile’, ‘src/Makefile’, and ‘config.h’ being created
- at the end after ‘configure’ has probed the system. It is now possible
- to run all the targets we wish (*note Standard Targets::). For
- instance:
- ~/amhello % make
- ...
- ~/amhello % src/hello
- Hello World!
- This is amhello 1.0.
- ~/amhello % make distcheck
- ...
- =============================================
- amhello-1.0 archives ready for distribution:
- amhello-1.0.tar.gz
- =============================================
- Note that running ‘autoreconf’ is only needed initially when the GNU
- Build System does not exist. When you later change some instructions in
- a ‘Makefile.am’ or ‘configure.ac’, the relevant part of the build system
- will be regenerated automatically when you execute ‘make’.
- ‘autoreconf’ is a script that calls ‘autoconf’, ‘automake’, and a
- bunch of other commands in the right order. If you are beginning with
- these tools, it is not important to figure out in which order all of
- these tools should be invoked and why. However, because Autoconf and
- Automake have separate manuals, the important point to understand is
- that ‘autoconf’ is in charge of creating ‘configure’ from
- ‘configure.ac’, while ‘automake’ is in charge of creating ‘Makefile.in’s
- from ‘Makefile.am’s and ‘configure.ac’. This should at least direct you
- to the right manual when seeking answers.
- File: automake.info, Node: amhello's configure.ac Setup Explained, Next: amhello's Makefile.am Setup Explained, Prev: Creating amhello, Up: Hello World
- 2.4.2 ‘amhello’’s ‘configure.ac’ Setup Explained
- ------------------------------------------------
- Let us begin with the contents of ‘configure.ac’.
- AC_INIT([amhello], [1.0], [bug-automake@gnu.org])
- AM_INIT_AUTOMAKE([-Wall -Werror foreign])
- AC_PROG_CC
- AC_CONFIG_HEADERS([config.h])
- AC_CONFIG_FILES([
- Makefile
- src/Makefile
- ])
- AC_OUTPUT
- This file is read by both ‘autoconf’ (to create ‘configure’) and
- ‘automake’ (to create the various ‘Makefile.in’s). It contains a series
- of M4 macros that will be expanded as shell code to finally form the
- ‘configure’ script. We will not elaborate on the syntax of this file,
- because the Autoconf manual has a whole section about it (*note Writing
- ‘configure.ac’: (autoconf)Writing Autoconf Input.).
- The macros prefixed with ‘AC_’ are Autoconf macros, documented in the
- Autoconf manual (*note Autoconf Macro Index: (autoconf)Autoconf Macro
- Index.). The macros that start with ‘AM_’ are Automake macros,
- documented later in this manual (*note Macro Index::).
- The first two lines of ‘configure.ac’ initialize Autoconf and
- Automake. ‘AC_INIT’ takes in as parameters the name of the package, its
- version number, and a contact address for bug-reports about the package
- (this address is output at the end of ‘./configure --help’, for
- instance). When adapting this setup to your own package, by all means
- please do not blindly copy Automake’s address: use the mailing list of
- your package, or your own mail address.
- The argument to ‘AM_INIT_AUTOMAKE’ is a list of options for
- ‘automake’ (*note Options::). ‘-Wall’ and ‘-Werror’ ask ‘automake’ to
- turn on all warnings and report them as errors. We are speaking of
- *Automake* warnings here, such as dubious instructions in ‘Makefile.am’.
- This has absolutely nothing to do with how the compiler will be called,
- even though it may support options with similar names. Using ‘-Wall
- -Werror’ is a safe setting when starting to work on a package: you do
- not want to miss any issues. Later you may decide to relax things a
- bit. The ‘foreign’ option tells Automake that this package will not
- follow the GNU Standards. GNU packages should always distribute
- additional files such as ‘ChangeLog’, ‘AUTHORS’, etc. We do not want
- ‘automake’ to complain about these missing files in our small example.
- The ‘AC_PROG_CC’ line causes the ‘configure’ script to search for a C
- compiler and define the variable ‘CC’ with its name. The
- ‘src/Makefile.in’ file generated by Automake uses the variable ‘CC’ to
- build ‘hello’, so when ‘configure’ creates ‘src/Makefile’ from
- ‘src/Makefile.in’, it will define ‘CC’ with the value it has found. If
- Automake is asked to create a ‘Makefile.in’ that uses ‘CC’ but
- ‘configure.ac’ does not define it, it will suggest you add a call to
- ‘AC_PROG_CC’.
- The ‘AC_CONFIG_HEADERS([config.h])’ invocation causes the ‘configure’
- script to create a ‘config.h’ file gathering ‘#define’s defined by other
- macros in ‘configure.ac’. In our case, the ‘AC_INIT’ macro already
- defined a few of them. Here is an excerpt of ‘config.h’ after
- ‘configure’ has run:
- ...
- /* Define to the address where bug reports for this package should be sent. */
- #define PACKAGE_BUGREPORT "bug-automake@gnu.org"
- /* Define to the full name and version of this package. */
- #define PACKAGE_STRING "amhello 1.0"
- ...
- As you probably noticed, ‘src/main.c’ includes ‘config.h’ so it can
- use ‘PACKAGE_STRING’. In a real-world project, ‘config.h’ can grow
- really big, with one ‘#define’ per feature probed on the system.
- The ‘AC_CONFIG_FILES’ macro declares the list of files that
- ‘configure’ should create from their ‘*.in’ templates. Automake also
- scans this list to find the ‘Makefile.am’ files it must process. (This
- is important to remember: when adding a new directory to your project,
- you should add its ‘Makefile’ to this list, otherwise Automake will
- never process the new ‘Makefile.am’ you wrote in that directory.)
- Finally, the ‘AC_OUTPUT’ line is a closing command that actually
- produces the part of the script in charge of creating the files
- registered with ‘AC_CONFIG_HEADERS’ and ‘AC_CONFIG_FILES’.
- When starting a new project, we suggest you start with such a simple
- ‘configure.ac’, and gradually add the other tests it requires. The
- command ‘autoscan’ can also suggest a few of the tests your package may
- need (*note Using ‘autoscan’ to Create ‘configure.ac’:
- (autoconf)autoscan Invocation.).
- File: automake.info, Node: amhello's Makefile.am Setup Explained, Prev: amhello's configure.ac Setup Explained, Up: Hello World
- 2.4.3 ‘amhello’’s ‘Makefile.am’ Setup Explained
- -----------------------------------------------
- We now turn to ‘src/Makefile.am’. This file contains Automake
- instructions to build and install ‘hello’.
- bin_PROGRAMS = hello
- hello_SOURCES = main.c
- A ‘Makefile.am’ has the same syntax as an ordinary ‘Makefile’. When
- ‘automake’ processes a ‘Makefile.am’ it copies the entire file into the
- output ‘Makefile.in’ (that will be later turned into ‘Makefile’ by
- ‘configure’) but will react to certain variable definitions by
- generating some build rules and other variables. Often ‘Makefile.am’s
- contain only a list of variable definitions as above, but they can also
- contain other variable and rule definitions that ‘automake’ will pass
- along without interpretation.
- Variables that end with ‘_PROGRAMS’ are special variables that list
- programs that the resulting ‘Makefile’ should build. In Automake speak,
- this ‘_PROGRAMS’ suffix is called a “primary”; Automake recognizes other
- primaries such as ‘_SCRIPTS’, ‘_DATA’, ‘_LIBRARIES’, etc. corresponding
- to different types of files.
- The ‘bin’ part of the ‘bin_PROGRAMS’ tells ‘automake’ that the
- resulting programs should be installed in BINDIR. Recall that the GNU
- Build System uses a set of variables to denote destination directories
- and allow users to customize these locations (*note Standard Directory
- Variables::). Any such directory variable can be put in front of a
- primary (omitting the ‘dir’ suffix) to tell ‘automake’ where to install
- the listed files.
- Programs need to be built from source files, so for each program
- ‘PROG’ listed in a ‘_PROGRAMS’ variable, ‘automake’ will look for
- another variable named ‘PROG_SOURCES’ listing its source files. There
- may be more than one source file: they will all be compiled and linked
- together.
- Automake also knows that source files need to be distributed when
- creating a tarball (unlike built programs). So a side-effect of this
- ‘hello_SOURCES’ declaration is that ‘main.c’ will be part of the tarball
- created by ‘make dist’.
- Finally here are some explanations regarding the top-level
- ‘Makefile.am’.
- SUBDIRS = src
- dist_doc_DATA = README
- ‘SUBDIRS’ is a special variable listing all directories that ‘make’
- should recurse into before processing the current directory. So this
- line is responsible for ‘make’ building ‘src/hello’ even though we run
- it from the top-level. This line also causes ‘make install’ to install
- ‘src/hello’ before installing ‘README’ (not that this order matters).
- The line ‘dist_doc_DATA = README’ causes ‘README’ to be distributed
- and installed in DOCDIR. Files listed with the ‘_DATA’ primary are not
- automatically part of the tarball built with ‘make dist’, so we add the
- ‘dist_’ prefix so they get distributed. However, for ‘README’ it would
- not have been necessary: ‘automake’ automatically distributes any
- ‘README’ file it encounters (the list of other files automatically
- distributed is presented by ‘automake --help’). The only important
- effect of this second line is therefore to install ‘README’ during ‘make
- install’.
- One thing not covered in this example is accessing the installation
- directory values (*note Standard Directory Variables::) from your
- program code, that is, converting them into defined macros. For this,
- *note (autoconf)Defining Directories::.
- File: automake.info, Node: Generalities, Next: Examples, Prev: Autotools Introduction, Up: Top
- 3 General ideas
- ***************
- The following sections cover a few basic ideas that will help you
- understand how Automake works.
- * Menu:
- * General Operation:: General operation of Automake
- * Strictness:: Standards conformance checking
- * Uniform:: The Uniform Naming Scheme
- * Length Limitations:: Staying below the command line length limit
- * Canonicalization:: How derived variables are named
- * User Variables:: Variables reserved for the user
- * Auxiliary Programs:: Programs automake might require
- File: automake.info, Node: General Operation, Next: Strictness, Up: Generalities
- 3.1 General Operation
- =====================
- Automake works by reading a ‘Makefile.am’ and generating a
- ‘Makefile.in’. Certain variables and rules defined in the ‘Makefile.am’
- instruct Automake to generate more specialized code; for instance, a
- ‘bin_PROGRAMS’ variable definition will cause rules for compiling and
- linking programs to be generated.
- The variable definitions and rules in the ‘Makefile.am’ are copied
- mostly verbatim into the generated file, with all variable definitions
- preceding all rules. This allows you to add almost arbitrary code into
- the generated ‘Makefile.in’. For instance, the Automake distribution
- includes a non-standard rule for the ‘git-dist’ target, which the
- Automake maintainer uses to make distributions from the source control
- system.
- Note that most GNU make extensions are not recognized by Automake.
- Using such extensions in a ‘Makefile.am’ will lead to errors or
- confusing behavior.
- A special exception is that the GNU make append operator, ‘+=’, is
- supported. This operator appends its right hand argument to the
- variable specified on the left. Automake will translate the operator
- into an ordinary ‘=’ operator; ‘+=’ will thus work with any make
- program.
- Automake tries to keep comments grouped with any adjoining rules or
- variable definitions.
- Generally, Automake is not particularly smart in the parsing of
- unusual Makefile constructs, so you’re advised to avoid fancy constructs
- or “creative” use of whitespace. For example, <TAB> characters cannot
- be used between a target name and the following “‘:’” character, and
- variable assignments shouldn’t be indented with <TAB> characters. Also,
- using more complex macro in target names can cause trouble:
- % cat Makefile.am
- $(FOO:=x): bar
- % automake
- Makefile.am:1: bad characters in variable name '$(FOO'
- Makefile.am:1: ':='-style assignments are not portable
- A rule defined in ‘Makefile.am’ generally overrides any such rule of
- a similar name that would be automatically generated by ‘automake’.
- Although this is a supported feature, it is generally best to avoid
- making use of it, as sometimes the generated rules are very particular.
- Similarly, a variable defined in ‘Makefile.am’ or ‘AC_SUBST’ed from
- ‘configure.ac’ will override any definition of the variable that
- ‘automake’ would ordinarily create. This feature is more often useful
- than the ability to override a rule. Be warned that many of the
- variables generated by ‘automake’ are considered to be for internal use
- only, and their names might change in future releases.
- When examining a variable definition, Automake will recursively
- examine variables referenced in the definition. For example, if
- Automake is looking at the content of ‘foo_SOURCES’ in this snippet
- xs = a.c b.c
- foo_SOURCES = c.c $(xs)
- it would use the files ‘a.c’, ‘b.c’, and ‘c.c’ as the contents of
- ‘foo_SOURCES’.
- Automake also allows a form of comment that is _not_ copied into the
- output; all lines beginning with ‘##’ (leading spaces allowed) are
- completely ignored by Automake.
- It is customary to make the first line of ‘Makefile.am’ read:
- ## Process this file with automake to produce Makefile.in
- File: automake.info, Node: Strictness, Next: Uniform, Prev: General Operation, Up: Generalities
- 3.2 Strictness
- ==============
- While Automake is intended to be used by maintainers of GNU packages, it
- does make some effort to accommodate those who wish to use it, but do
- not want to use all the GNU conventions.
- To this end, Automake supports three levels of “strictness”—the
- strictness indicating how stringently Automake should check standards
- conformance.
- The valid strictness levels are:
- ‘foreign’
- Automake will check for only those things that are absolutely
- required for proper operations. For instance, whereas GNU
- standards dictate the existence of a ‘NEWS’ file, it will not be
- required in this mode. This strictness will also turn off some
- warnings by default (among them, portability warnings). The name
- comes from the fact that Automake is intended to be used for GNU
- programs; these relaxed rules are not the standard mode of
- operation.
- ‘gnu’
- Automake will check—as much as possible—for compliance to the GNU
- standards for packages. This is the default.
- ‘gnits’
- Automake will check for compliance to the as-yet-unwritten “Gnits
- standards”. These are based on the GNU standards, but are even
- more detailed. Unless you are a Gnits standards contributor, it is
- recommended that you avoid this option until such time as the Gnits
- standard is actually published (which may never happen).
- *Note Gnits::, for more information on the precise implications of
- the strictness level.
- File: automake.info, Node: Uniform, Next: Length Limitations, Prev: Strictness, Up: Generalities
- 3.3 The Uniform Naming Scheme
- =============================
- Automake variables generally follow a “uniform naming scheme” that makes
- it easy to decide how programs (and other derived objects) are built,
- and how they are installed. This scheme also supports ‘configure’ time
- determination of what should be built.
- At ‘make’ time, certain variables are used to determine which objects
- are to be built. The variable names are made of several pieces that are
- concatenated together.
- The piece that tells ‘automake’ what is being built is commonly
- called the “primary”. For instance, the primary ‘PROGRAMS’ holds a list
- of programs that are to be compiled and linked.
- A different set of names is used to decide where the built objects
- should be installed. These names are prefixes to the primary, and they
- indicate which standard directory should be used as the installation
- directory. The standard directory names are given in the GNU standards
- (*note (standards)Directory Variables::). Automake extends this list
- with ‘pkgdatadir’, ‘pkgincludedir’, ‘pkglibdir’, and ‘pkglibexecdir’;
- these are the same as the non-‘pkg’ versions, but with ‘$(PACKAGE)’
- appended. For instance, ‘pkglibdir’ is defined as
- ‘$(libdir)/$(PACKAGE)’.
- For each primary, there is one additional variable named by
- prepending ‘EXTRA_’ to the primary name. This variable is used to list
- objects that may or may not be built, depending on what ‘configure’
- decides. This variable is required because Automake must statically
- know the entire list of objects that may be built in order to generate a
- ‘Makefile.in’ that will work in all cases.
- For instance, ‘cpio’ decides at configure time which programs should
- be built. Some of the programs are installed in ‘bindir’, and some are
- installed in ‘sbindir’:
- EXTRA_PROGRAMS = mt rmt
- bin_PROGRAMS = cpio pax
- sbin_PROGRAMS = $(MORE_PROGRAMS)
- Defining a primary without a prefix as a variable, e.g., ‘PROGRAMS’,
- is an error.
- Note that the common ‘dir’ suffix is left off when constructing the
- variable names; thus one writes ‘bin_PROGRAMS’ and not
- ‘bindir_PROGRAMS’.
- Not every sort of object can be installed in every directory.
- Automake will flag those attempts it finds in error (but see below how
- to override the check if you really need to). Automake will also
- diagnose obvious misspellings in directory names.
- Sometimes the standard directories—even as augmented by Automake—are
- not enough. In particular it is sometimes useful, for clarity, to
- install objects in a subdirectory of some predefined directory. To this
- end, Automake allows you to extend the list of possible installation
- directories. A given prefix (e.g., ‘zar’) is valid if a variable of the
- same name with ‘dir’ appended is defined (e.g., ‘zardir’).
- For instance, the following snippet will install ‘file.xml’ into
- ‘$(datadir)/xml’.
- xmldir = $(datadir)/xml
- xml_DATA = file.xml
- This feature can also be used to override the sanity checks Automake
- performs to diagnose suspicious directory/primary couples (in the
- unlikely case these checks are undesirable, and you really know what
- you’re doing). For example, Automake would error out on this input:
- # Forbidden directory combinations, automake will error out on this.
- pkglib_PROGRAMS = foo
- doc_LIBRARIES = libquux.a
- but it will succeed with this:
- # Work around forbidden directory combinations. Do not use this
- # without a very good reason!
- my_execbindir = $(pkglibdir)
- my_doclibdir = $(docdir)
- my_execbin_PROGRAMS = foo
- my_doclib_LIBRARIES = libquux.a
- The ‘exec’ substring of the ‘my_execbindir’ variable lets the files
- be installed at the right time (*note The Two Parts of Install::).
- The special prefix ‘noinst_’ indicates that the objects in question
- should be built but not installed at all. This is usually used for
- objects required to build the rest of your package, for instance static
- libraries (*note A Library::), or helper scripts.
- The special prefix ‘check_’ indicates that the objects in question
- should not be built until the ‘make check’ command is run. Those
- objects are not installed either.
- The current primary names are ‘PROGRAMS’, ‘LIBRARIES’, ‘LTLIBRARIES’,
- ‘LISP’, ‘PYTHON’, ‘JAVA’, ‘SCRIPTS’, ‘DATA’, ‘HEADERS’, ‘MANS’, and
- ‘TEXINFOS’.
- Some primaries also allow additional prefixes that control other
- aspects of ‘automake’’s behavior. The currently defined prefixes are
- ‘dist_’, ‘nodist_’, ‘nobase_’, and ‘notrans_’. These prefixes are
- explained later (*note Program and Library Variables::) (*note Man
- Pages::).
- File: automake.info, Node: Length Limitations, Next: Canonicalization, Prev: Uniform, Up: Generalities
- 3.4 Staying below the command line length limit
- ===============================================
- Traditionally, most unix-like systems have a length limitation for the
- command line arguments and environment contents when creating new
- processes (see for example
- <http://www.in-ulm.de/~mascheck/various/argmax/> for an overview on this
- issue), which of course also applies to commands spawned by ‘make’.
- POSIX requires this limit to be at least 4096 bytes, and most modern
- systems have quite high limits (or are unlimited).
- In order to create portable Makefiles that do not trip over these
- limits, it is necessary to keep the length of file lists bounded.
- Unfortunately, it is not possible to do so fully transparently within
- Automake, so your help may be needed. Typically, you can split long
- file lists manually and use different installation directory names for
- each list. For example,
- data_DATA = file1 ... fileN fileN+1 ... file2N
- may also be written as
- data_DATA = file1 ... fileN
- data2dir = $(datadir)
- data2_DATA = fileN+1 ... file2N
- and will cause Automake to treat the two lists separately during ‘make
- install’. See *note The Two Parts of Install:: for choosing directory
- names that will keep the ordering of the two parts of installation Note
- that ‘make dist’ may still only work on a host with a higher length
- limit in this example.
- Automake itself employs a couple of strategies to avoid long command
- lines. For example, when ‘${srcdir}/’ is prepended to file names, as
- can happen with above ‘$(data_DATA)’ lists, it limits the amount of
- arguments passed to external commands.
- Unfortunately, some system’s ‘make’ commands may prepend ‘VPATH’
- prefixes like ‘${srcdir}/’ to file names from the source tree
- automatically (*note Automatic Rule Rewriting: (autoconf)Automatic Rule
- Rewriting.). In this case, the user may have to switch to use GNU Make,
- or refrain from using VPATH builds, in order to stay below the length
- limit.
- For libraries and programs built from many sources, convenience
- archives may be used as intermediates in order to limit the object list
- length (*note Libtool Convenience Libraries::).
- File: automake.info, Node: Canonicalization, Next: User Variables, Prev: Length Limitations, Up: Generalities
- 3.5 How derived variables are named
- ===================================
- Sometimes a Makefile variable name is derived from some text the
- maintainer supplies. For instance, a program name listed in ‘_PROGRAMS’
- is rewritten into the name of a ‘_SOURCES’ variable. In cases like
- this, Automake canonicalizes the text, so that program names and the
- like do not have to follow Makefile variable naming rules. All
- characters in the name except for letters, numbers, the strudel (@), and
- the underscore are turned into underscores when making variable
- references.
- For example, if your program is named ‘sniff-glue’, the derived
- variable name would be ‘sniff_glue_SOURCES’, not ‘sniff-glue_SOURCES’.
- Similarly the sources for a library named ‘libmumble++.a’ should be
- listed in the ‘libmumble___a_SOURCES’ variable.
- The strudel is an addition, to make the use of Autoconf substitutions
- in variable names less obfuscating.
- File: automake.info, Node: User Variables, Next: Auxiliary Programs, Prev: Canonicalization, Up: Generalities
- 3.6 Variables reserved for the user
- ===================================
- Some ‘Makefile’ variables are reserved by the GNU Coding Standards for
- the use of the “user”—the person building the package. For instance,
- ‘CFLAGS’ is one such variable.
- Sometimes package developers are tempted to set user variables such
- as ‘CFLAGS’ because it appears to make their job easier. However, the
- package itself should never set a user variable, particularly not to
- include switches that are required for proper compilation of the
- package. Since these variables are documented as being for the package
- builder, that person rightfully expects to be able to override any of
- these variables at build time.
- To get around this problem, Automake introduces an automake-specific
- shadow variable for each user flag variable. (Shadow variables are not
- introduced for variables like ‘CC’, where they would make no sense.)
- The shadow variable is named by prepending ‘AM_’ to the user variable’s
- name. For instance, the shadow variable for ‘YFLAGS’ is ‘AM_YFLAGS’.
- The package maintainer—that is, the author(s) of the ‘Makefile.am’ and
- ‘configure.ac’ files—may adjust these shadow variables however
- necessary.
- *Note Flag Variables Ordering::, for more discussion about these
- variables and how they interact with per-target variables.
- File: automake.info, Node: Auxiliary Programs, Prev: User Variables, Up: Generalities
- 3.7 Programs automake might require
- ===================================
- Automake sometimes requires helper programs so that the generated
- ‘Makefile’ can do its work properly. There are a fairly large number of
- them, and we list them here.
- Although all of these files are distributed and installed with
- Automake, a couple of them are maintained separately. The Automake
- copies are updated before each release, but we mention the original
- source in case you need more recent versions.
- ‘ar-lib’
- This is a wrapper primarily for the Microsoft lib archiver, to make
- it more POSIX-like.
- ‘compile’
- This is a wrapper for compilers that do not accept options ‘-c’ and
- ‘-o’ at the same time. It is only used when absolutely required.
- Such compilers are rare, with the Microsoft C/C++ Compiler as the
- most notable exception. This wrapper also makes the following
- common options available for that compiler, while performing file
- name translation where needed: ‘-I’, ‘-L’, ‘-l’, ‘-Wl,’ and
- ‘-Xlinker’.
- ‘config.guess’
- ‘config.sub’
- These two programs compute the canonical triplets for the given
- build, host, or target architecture. These programs are updated
- regularly to support new architectures and fix probes broken by
- changes in new kernel versions. Each new release of Automake comes
- with up-to-date copies of these programs. If your copy of Automake
- is getting old, you are encouraged to fetch the latest versions of
- these files from <http://savannah.gnu.org/git/?group=config> before
- making a release.
- ‘depcomp’
- This program understands how to run a compiler so that it will
- generate not only the desired output but also dependency
- information that is then used by the automatic dependency tracking
- feature (*note Dependencies::).
- ‘install-sh’
- This is a replacement for the ‘install’ program that works on
- platforms where ‘install’ is unavailable or unusable.
- ‘mdate-sh’
- This script is used to generate a ‘version.texi’ file. It examines
- a file and prints some date information about it.
- ‘missing’
- This wraps a number of programs that are typically only required by
- maintainers. If the program in question doesn’t exist, or seems to
- old, ‘missing’ will print an informative warning before failing
- out, to provide the user with more context and information.
- ‘mkinstalldirs’
- This script used to be a wrapper around ‘mkdir -p’, which is not
- portable. Now we prefer to use ‘install-sh -d’ when ‘configure’
- finds that ‘mkdir -p’ does not work, this makes one less script to
- distribute.
- For backward compatibility ‘mkinstalldirs’ is still used and
- distributed when ‘automake’ finds it in a package. But it is no
- longer installed automatically, and it should be safe to remove it.
- ‘py-compile’
- This is used to byte-compile Python scripts.
- ‘test-driver’
- This implements the default test driver offered by the parallel
- testsuite harness.
- ‘texinfo.tex’
- Not a program, this file is required for ‘make dvi’, ‘make ps’ and
- ‘make pdf’ to work when Texinfo sources are in the package. The
- latest version can be downloaded from
- <http://www.gnu.org/software/texinfo/>.
- ‘ylwrap’
- This program wraps ‘lex’ and ‘yacc’ to rename their output files.
- It also ensures that, for instance, multiple ‘yacc’ instances can
- be invoked in a single directory in parallel.
- File: automake.info, Node: Examples, Next: automake Invocation, Prev: Generalities, Up: Top
- 4 Some example packages
- ***********************
- This section contains two small examples.
- The first example (*note Complete::) assumes you have an existing
- project already using Autoconf, with handcrafted ‘Makefile’s, and that
- you want to convert it to using Automake. If you are discovering both
- tools, it is probably better that you look at the Hello World example
- presented earlier (*note Hello World::).
- The second example (*note true::) shows how two programs can be built
- from the same file, using different compilation parameters. It contains
- some technical digressions that are probably best skipped on first read.
- * Menu:
- * Complete:: A simple example, start to finish
- * true:: Building true and false
- File: automake.info, Node: Complete, Next: true, Up: Examples
- 4.1 A simple example, start to finish
- =====================================
- Let’s suppose you just finished writing ‘zardoz’, a program to make your
- head float from vortex to vortex. You’ve been using Autoconf to provide
- a portability framework, but your ‘Makefile.in’s have been ad-hoc. You
- want to make them bulletproof, so you turn to Automake.
- The first step is to update your ‘configure.ac’ to include the
- commands that ‘automake’ needs. The way to do this is to add an
- ‘AM_INIT_AUTOMAKE’ call just after ‘AC_INIT’:
- AC_INIT([zardoz], [1.0])
- AM_INIT_AUTOMAKE
- ...
- Since your program doesn’t have any complicating factors (e.g., it
- doesn’t use ‘gettext’, it doesn’t want to build a shared library),
- you’re done with this part. That was easy!
- Now you must regenerate ‘configure’. But to do that, you’ll need to
- tell ‘autoconf’ how to find the new macro you’ve used. The easiest way
- to do this is to use the ‘aclocal’ program to generate your ‘aclocal.m4’
- for you. But wait... maybe you already have an ‘aclocal.m4’, because
- you had to write some hairy macros for your program. The ‘aclocal’
- program lets you put your own macros into ‘acinclude.m4’, so simply
- rename and then run:
- mv aclocal.m4 acinclude.m4
- aclocal
- autoconf
- Now it is time to write your ‘Makefile.am’ for ‘zardoz’. Since
- ‘zardoz’ is a user program, you want to install it where the rest of the
- user programs go: ‘bindir’. Additionally, ‘zardoz’ has some Texinfo
- documentation. Your ‘configure.ac’ script uses ‘AC_REPLACE_FUNCS’, so
- you need to link against ‘$(LIBOBJS)’. So here’s what you’d write:
- bin_PROGRAMS = zardoz
- zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
- zardoz_LDADD = $(LIBOBJS)
- info_TEXINFOS = zardoz.texi
- Now you can run ‘automake --add-missing’ to generate your
- ‘Makefile.in’ and grab any auxiliary files you might need, and you’re
- done!
- File: automake.info, Node: true, Prev: Complete, Up: Examples
- 4.2 Building true and false
- ===========================
- Here is another, trickier example. It shows how to generate two
- programs (‘true’ and ‘false’) from the same source file (‘true.c’). The
- difficult part is that each compilation of ‘true.c’ requires different
- ‘cpp’ flags.
- bin_PROGRAMS = true false
- false_SOURCES =
- false_LDADD = false.o
- true.o: true.c
- $(COMPILE) -DEXIT_CODE=0 -c true.c
- false.o: true.c
- $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
- Note that there is no ‘true_SOURCES’ definition. Automake will
- implicitly assume that there is a source file named ‘true.c’ (*note
- Default _SOURCES::), and define rules to compile ‘true.o’ and link
- ‘true’. The ‘true.o: true.c’ rule supplied by the above ‘Makefile.am’,
- will override the Automake generated rule to build ‘true.o’.
- ‘false_SOURCES’ is defined to be empty—that way no implicit value is
- substituted. Because we have not listed the source of ‘false’, we have
- to tell Automake how to link the program. This is the purpose of the
- ‘false_LDADD’ line. A ‘false_DEPENDENCIES’ variable, holding the
- dependencies of the ‘false’ target will be automatically generated by
- Automake from the content of ‘false_LDADD’.
- The above rules won’t work if your compiler doesn’t accept both ‘-c’
- and ‘-o’. The simplest fix for this is to introduce a bogus dependency
- (to avoid problems with a parallel ‘make’):
- true.o: true.c false.o
- $(COMPILE) -DEXIT_CODE=0 -c true.c
- false.o: true.c
- $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
- As it turns out, there is also a much easier way to do this same
- task. Some of the above technique is useful enough that we’ve kept the
- example in the manual. However if you were to build ‘true’ and ‘false’
- in real life, you would probably use per-program compilation flags, like
- so:
- bin_PROGRAMS = false true
- false_SOURCES = true.c
- false_CPPFLAGS = -DEXIT_CODE=1
- true_SOURCES = true.c
- true_CPPFLAGS = -DEXIT_CODE=0
- In this case Automake will cause ‘true.c’ to be compiled twice, with
- different flags. In this instance, the names of the object files would
- be chosen by automake; they would be ‘false-true.o’ and ‘true-true.o’.
- (The name of the object files rarely matters.)
- File: automake.info, Node: automake Invocation, Next: configure, Prev: Examples, Up: Top
- 5 Creating a ‘Makefile.in’
- **************************
- To create all the ‘Makefile.in’s for a package, run the ‘automake’
- program in the top level directory, with no arguments. ‘automake’ will
- automatically find each appropriate ‘Makefile.am’ (by scanning
- ‘configure.ac’; *note configure::) and generate the corresponding
- ‘Makefile.in’. Note that ‘automake’ has a rather simplistic view of
- what constitutes a package; it assumes that a package has only one
- ‘configure.ac’, at the top. If your package has multiple
- ‘configure.ac’s, then you must run ‘automake’ in each directory holding
- a ‘configure.ac’. (Alternatively, you may rely on Autoconf’s
- ‘autoreconf’, which is able to recurse your package tree and run
- ‘automake’ where appropriate.)
- You can optionally give ‘automake’ an argument; ‘.am’ is appended to
- the argument and the result is used as the name of the input file. This
- feature is generally only used to automatically rebuild an out-of-date
- ‘Makefile.in’. Note that ‘automake’ must always be run from the topmost
- directory of a project, even if being used to regenerate the
- ‘Makefile.in’ in some subdirectory. This is necessary because
- ‘automake’ must scan ‘configure.ac’, and because ‘automake’ uses the
- knowledge that a ‘Makefile.in’ is in a subdirectory to change its
- behavior in some cases.
- Automake will run ‘autoconf’ to scan ‘configure.ac’ and its
- dependencies (i.e., ‘aclocal.m4’ and any included file), therefore
- ‘autoconf’ must be in your ‘PATH’. If there is an ‘AUTOCONF’ variable
- in your environment it will be used instead of ‘autoconf’, this allows
- you to select a particular version of Autoconf. By the way, don’t
- misunderstand this paragraph: ‘automake’ runs ‘autoconf’ to *scan* your
- ‘configure.ac’, this won’t build ‘configure’ and you still have to run
- ‘autoconf’ yourself for this purpose.
- ‘automake’ accepts the following options:
- ‘-a’
- ‘--add-missing’
- Automake requires certain common files to exist in certain
- situations; for instance, ‘config.guess’ is required if
- ‘configure.ac’ invokes ‘AC_CANONICAL_HOST’. Automake is
- distributed with several of these files (*note Auxiliary
- Programs::); this option will cause the missing ones to be
- automatically added to the package, whenever possible. In general
- if Automake tells you a file is missing, try using this option. By
- default Automake tries to make a symbolic link pointing to its own
- copy of the missing file; this can be changed with ‘--copy’.
- Many of the potentially-missing files are common scripts whose
- location may be specified via the ‘AC_CONFIG_AUX_DIR’ macro.
- Therefore, ‘AC_CONFIG_AUX_DIR’’s setting affects whether a file is
- considered missing, and where the missing file is added (*note
- Optional::).
- In some strictness modes, additional files are installed, see *note
- Gnits:: for more information.
- ‘--libdir=DIR’
- Look for Automake data files in directory DIR instead of in the
- installation directory. This is typically used for debugging.
- ‘--print-libdir’
- Print the path of the installation directory containing
- Automake-provided scripts and data files (like e.g., ‘texinfo.texi’
- and ‘install-sh’).
- ‘-c’
- ‘--copy’
- When used with ‘--add-missing’, causes installed files to be
- copied. The default is to make a symbolic link.
- ‘-f’
- ‘--force-missing’
- When used with ‘--add-missing’, causes standard files to be
- reinstalled even if they already exist in the source tree. This
- involves removing the file from the source tree before creating the
- new symlink (or, with ‘--copy’, copying the new file).
- ‘--foreign’
- Set the global strictness to ‘foreign’. For more information, see
- *note Strictness::.
- ‘--gnits’
- Set the global strictness to ‘gnits’. For more information, see
- *note Gnits::.
- ‘--gnu’
- Set the global strictness to ‘gnu’. For more information, see
- *note Gnits::. This is the default strictness.
- ‘--help’
- Print a summary of the command line options and exit.
- ‘-i’
- ‘--ignore-deps’
- This disables the dependency tracking feature in generated
- ‘Makefile’s; see *note Dependencies::.
- ‘--include-deps’
- This enables the dependency tracking feature. This feature is
- enabled by default. This option is provided for historical reasons
- only and probably should not be used.
- ‘--no-force’
- Ordinarily ‘automake’ creates all ‘Makefile.in’s mentioned in
- ‘configure.ac’. This option causes it to only update those
- ‘Makefile.in’s that are out of date with respect to one of their
- dependents.
- ‘-o DIR’
- ‘--output-dir=DIR’
- Put the generated ‘Makefile.in’ in the directory DIR. Ordinarily
- each ‘Makefile.in’ is created in the directory of the corresponding
- ‘Makefile.am’. This option is deprecated and will be removed in a
- future release.
- ‘-v’
- ‘--verbose’
- Cause Automake to print information about which files are being
- read or created.
- ‘--version’
- Print the version number of Automake and exit.
- ‘-W CATEGORY’
- ‘--warnings=CATEGORY’
- Output warnings falling in CATEGORY. CATEGORY can be one of:
- ‘gnu’
- warnings related to the GNU Coding Standards (*note
- (standards)Top::).
- ‘obsolete’
- obsolete features or constructions
- ‘override’
- user redefinitions of Automake rules or variables
- ‘portability’
- portability issues (e.g., use of ‘make’ features that are
- known to be not portable)
- ‘extra-portability’
- extra portability issues related to obscure tools. One
- example of such a tool is the Microsoft ‘lib’ archiver.
- ‘syntax’
- weird syntax, unused variables, typos
- ‘unsupported’
- unsupported or incomplete features
- ‘all’
- all the warnings
- ‘none’
- turn off all the warnings
- ‘error’
- treat warnings as errors
- A category can be turned off by prefixing its name with ‘no-’. For
- instance, ‘-Wno-syntax’ will hide the warnings about unused
- variables.
- The categories output by default are ‘obsolete’, ‘syntax’ and
- ‘unsupported’. Additionally, ‘gnu’ and ‘portability’ are enabled
- in ‘--gnu’ and ‘--gnits’ strictness.
- Turning off ‘portability’ will also turn off ‘extra-portability’,
- and similarly turning on ‘extra-portability’ will also turn on
- ‘portability’. However, turning on ‘portability’ or turning off
- ‘extra-portability’ will not affect the other category.
- The environment variable ‘WARNINGS’ can contain a comma separated
- list of categories to enable. It will be taken into account before
- the command-line switches, this way ‘-Wnone’ will also ignore any
- warning category enabled by ‘WARNINGS’. This variable is also used
- by other tools like ‘autoconf’; unknown categories are ignored for
- this reason.
- If the environment variable ‘AUTOMAKE_JOBS’ contains a positive
- number, it is taken as the maximum number of Perl threads to use in
- ‘automake’ for generating multiple ‘Makefile.in’ files concurrently.
- This is an experimental feature.
- File: automake.info, Node: configure, Next: Directories, Prev: automake Invocation, Up: Top
- 6 Scanning ‘configure.ac’, using ‘aclocal’
- ******************************************
- Automake scans the package’s ‘configure.ac’ to determine certain
- information about the package. Some ‘autoconf’ macros are required and
- some variables must be defined in ‘configure.ac’. Automake will also
- use information from ‘configure.ac’ to further tailor its output.
- Automake also supplies some Autoconf macros to make the maintenance
- easier. These macros can automatically be put into your ‘aclocal.m4’
- using the ‘aclocal’ program.
- * Menu:
- * Requirements:: Configuration requirements
- * Optional:: Other things Automake recognizes
- * aclocal Invocation:: Auto-generating aclocal.m4
- * Macros:: Autoconf macros supplied with Automake
- File: automake.info, Node: Requirements, Next: Optional, Up: configure
- 6.1 Configuration requirements
- ==============================
- The one real requirement of Automake is that your ‘configure.ac’ call
- ‘AM_INIT_AUTOMAKE’. This macro does several things that are required
- for proper Automake operation (*note Macros::).
- Here are the other macros that Automake requires but which are not
- run by ‘AM_INIT_AUTOMAKE’:
- ‘AC_CONFIG_FILES’
- ‘AC_OUTPUT’
- These two macros are usually invoked as follows near the end of
- ‘configure.ac’.
- ...
- AC_CONFIG_FILES([
- Makefile
- doc/Makefile
- src/Makefile
- src/lib/Makefile
- ...
- ])
- AC_OUTPUT
- Automake uses these to determine which files to create (*note
- Creating Output Files: (autoconf)Output.). A listed file is
- considered to be an Automake generated ‘Makefile’ if there exists a
- file with the same name and the ‘.am’ extension appended.
- Typically, ‘AC_CONFIG_FILES([foo/Makefile])’ will cause Automake to
- generate ‘foo/Makefile.in’ if ‘foo/Makefile.am’ exists.
- When using ‘AC_CONFIG_FILES’ with multiple input files, as in
- AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
- ‘automake’ will generate the first ‘.in’ input file for which a
- ‘.am’ file exists. If no such file exists the output file is not
- considered to be generated by Automake.
- Files created by ‘AC_CONFIG_FILES’, be they Automake ‘Makefile’s or
- not, are all removed by ‘make distclean’. Their inputs are
- automatically distributed, unless they are the output of prior
- ‘AC_CONFIG_FILES’ commands. Finally, rebuild rules are generated
- in the Automake ‘Makefile’ existing in the subdirectory of the
- output file, if there is one, or in the top-level ‘Makefile’
- otherwise.
- The above machinery (cleaning, distributing, and rebuilding) works
- fine if the ‘AC_CONFIG_FILES’ specifications contain only literals.
- If part of the specification uses shell variables, ‘automake’ will
- not be able to fulfill this setup, and you will have to complete
- the missing bits by hand. For instance, on
- file=input
- ...
- AC_CONFIG_FILES([output:$file],, [file=$file])
- ‘automake’ will output rules to clean ‘output’, and rebuild it.
- However the rebuild rule will not depend on ‘input’, and this file
- will not be distributed either. (You must add ‘EXTRA_DIST = input’
- to your ‘Makefile.am’ if ‘input’ is a source file.)
- Similarly
- file=output
- file2=out:in
- ...
- AC_CONFIG_FILES([$file:input],, [file=$file])
- AC_CONFIG_FILES([$file2],, [file2=$file2])
- will only cause ‘input’ to be distributed. No file will be cleaned
- automatically (add ‘DISTCLEANFILES = output out’ yourself), and no
- rebuild rule will be output.
- Obviously ‘automake’ cannot guess what value ‘$file’ is going to
- hold later when ‘configure’ is run, and it cannot use the shell
- variable ‘$file’ in a ‘Makefile’. However, if you make reference
- to ‘$file’ as ‘${file}’ (i.e., in a way that is compatible with
- ‘make’’s syntax) and furthermore use ‘AC_SUBST’ to ensure that
- ‘${file}’ is meaningful in a ‘Makefile’, then ‘automake’ will be
- able to use ‘${file}’ to generate all of these rules. For
- instance, here is how the Automake package itself generates
- versioned scripts for its test suite:
- AC_SUBST([APIVERSION], ...)
- ...
- AC_CONFIG_FILES(
- [tests/aclocal-${APIVERSION}:tests/aclocal.in],
- [chmod +x tests/aclocal-${APIVERSION}],
- [APIVERSION=$APIVERSION])
- AC_CONFIG_FILES(
- [tests/automake-${APIVERSION}:tests/automake.in],
- [chmod +x tests/automake-${APIVERSION}])
- Here cleaning, distributing, and rebuilding are done automatically,
- because ‘${APIVERSION}’ is known at ‘make’-time.
- Note that you should not use shell variables to declare ‘Makefile’
- files for which ‘automake’ must create ‘Makefile.in’. Even
- ‘AC_SUBST’ does not help here, because ‘automake’ needs to know the
- file name when it runs in order to check whether ‘Makefile.am’
- exists. (In the very hairy case that your setup requires such use
- of variables, you will have to tell Automake which ‘Makefile.in’s
- to generate on the command-line.)
- It is possible to let ‘automake’ emit conditional rules for
- ‘AC_CONFIG_FILES’ with the help of ‘AM_COND_IF’ (*note Optional::).
- To summarize:
- • Use literals for ‘Makefile’s, and for other files whenever
- possible.
- • Use ‘$file’ (or ‘${file}’ without ‘AC_SUBST([file])’) for
- files that ‘automake’ should ignore.
- • Use ‘${file}’ and ‘AC_SUBST([file])’ for files that ‘automake’
- should not ignore.
- File: automake.info, Node: Optional, Next: aclocal Invocation, Prev: Requirements, Up: configure
- 6.2 Other things Automake recognizes
- ====================================
- Every time Automake is run it calls Autoconf to trace ‘configure.ac’.
- This way it can recognize the use of certain macros and tailor the
- generated ‘Makefile.in’ appropriately. Currently recognized macros and
- their effects are:
- ‘AC_CANONICAL_BUILD’
- ‘AC_CANONICAL_HOST’
- ‘AC_CANONICAL_TARGET’
- Automake will ensure that ‘config.guess’ and ‘config.sub’ exist.
- Also, the ‘Makefile’ variables ‘build_triplet’, ‘host_triplet’ and
- ‘target_triplet’ are introduced. See *note Getting the Canonical
- System Type: (autoconf)Canonicalizing.
- ‘AC_CONFIG_AUX_DIR’
- Automake will look for various helper scripts, such as
- ‘install-sh’, in the directory named in this macro invocation.
- (The full list of scripts is: ‘ar-lib’, ‘config.guess’,
- ‘config.sub’, ‘depcomp’, ‘compile’, ‘install-sh’, ‘ltmain.sh’,
- ‘mdate-sh’, ‘missing’, ‘mkinstalldirs’, ‘py-compile’,
- ‘test-driver’, ‘texinfo.tex’, ‘ylwrap’.) Not all scripts are
- always searched for; some scripts will only be sought if the
- generated ‘Makefile.in’ requires them.
- If ‘AC_CONFIG_AUX_DIR’ is not given, the scripts are looked for in
- their standard locations. For ‘mdate-sh’, ‘texinfo.tex’, and
- ‘ylwrap’, the standard location is the source directory
- corresponding to the current ‘Makefile.am’. For the rest, the
- standard location is the first one of ‘.’, ‘..’, or ‘../..’
- (relative to the top source directory) that provides any one of the
- helper scripts. *Note Finding ‘configure’ Input: (autoconf)Input.
- Required files from ‘AC_CONFIG_AUX_DIR’ are automatically
- distributed, even if there is no ‘Makefile.am’ in this directory.
- ‘AC_CONFIG_LIBOBJ_DIR’
- Automake will require the sources file declared with ‘AC_LIBSOURCE’
- (see below) in the directory specified by this macro.
- ‘AC_CONFIG_HEADERS’
- Automake will generate rules to rebuild these headers from the
- corresponding templates (usually, the template for a ‘foo.h’ header
- being ‘foo.h.in’). Older versions of Automake required the use of
- ‘AM_CONFIG_HEADER’; this is no longer the case, and that macro has
- indeed been removed.
- As with ‘AC_CONFIG_FILES’ (*note Requirements::), parts of the
- specification using shell variables will be ignored as far as
- cleaning, distributing, and rebuilding is concerned.
- ‘AC_CONFIG_LINKS’
- Automake will generate rules to remove ‘configure’ generated links
- on ‘make distclean’ and to distribute named source files as part of
- ‘make dist’.
- As for ‘AC_CONFIG_FILES’ (*note Requirements::), parts of the
- specification using shell variables will be ignored as far as
- cleaning and distributing is concerned. (There are no rebuild
- rules for links.)
- ‘AC_LIBOBJ’
- ‘AC_LIBSOURCE’
- ‘AC_LIBSOURCES’
- Automake will automatically distribute any file listed in
- ‘AC_LIBSOURCE’ or ‘AC_LIBSOURCES’.
- Note that the ‘AC_LIBOBJ’ macro calls ‘AC_LIBSOURCE’. So if an
- Autoconf macro is documented to call ‘AC_LIBOBJ([file])’, then
- ‘file.c’ will be distributed automatically by Automake. This
- encompasses many macros like ‘AC_FUNC_ALLOCA’, ‘AC_FUNC_MEMCMP’,
- ‘AC_REPLACE_FUNCS’, and others.
- By the way, direct assignments to ‘LIBOBJS’ are no longer
- supported. You should always use ‘AC_LIBOBJ’ for this purpose.
- *Note ‘AC_LIBOBJ’ vs. ‘LIBOBJS’: (autoconf)AC_LIBOBJ vs LIBOBJS.
- ‘AC_PROG_RANLIB’
- This is required if any libraries are built in the package. *Note
- Particular Program Checks: (autoconf)Particular Programs.
- ‘AC_PROG_CXX’
- This is required if any C++ source is included. *Note Particular
- Program Checks: (autoconf)Particular Programs.
- ‘AC_PROG_OBJC’
- This is required if any Objective C source is included. *Note
- Particular Program Checks: (autoconf)Particular Programs.
- ‘AC_PROG_OBJCXX’
- This is required if any Objective C++ source is included. *Note
- Particular Program Checks: (autoconf)Particular Programs.
- ‘AC_PROG_F77’
- This is required if any Fortran 77 source is included. *Note
- Particular Program Checks: (autoconf)Particular Programs.
- ‘AC_F77_LIBRARY_LDFLAGS’
- This is required for programs and shared libraries that are a
- mixture of languages that include Fortran 77 (*note Mixing Fortran
- 77 With C and C++::). *Note Autoconf macros supplied with
- Automake: Macros.
- ‘AC_FC_SRCEXT’
- Automake will add the flags computed by ‘AC_FC_SRCEXT’ to
- compilation of files with the respective source extension (*note
- Fortran Compiler Characteristics: (autoconf)Fortran Compiler.).
- ‘AC_PROG_FC’
- This is required if any Fortran 90/95 source is included. This
- macro is distributed with Autoconf version 2.58 and later. *Note
- Particular Program Checks: (autoconf)Particular Programs.
- ‘AC_PROG_LIBTOOL’
- Automake will turn on processing for ‘libtool’ (*note Introduction:
- (libtool)Top.).
- ‘AC_PROG_YACC’
- If a Yacc source file is seen, then you must either use this macro
- or define the variable ‘YACC’ in ‘configure.ac’. The former is
- preferred (*note Particular Program Checks: (autoconf)Particular
- Programs.).
- ‘AC_PROG_LEX’
- If a Lex source file is seen, then this macro must be used. *Note
- Particular Program Checks: (autoconf)Particular Programs.
- ‘AC_REQUIRE_AUX_FILE’
- For each ‘AC_REQUIRE_AUX_FILE([FILE])’, ‘automake’ will ensure that
- ‘FILE’ exists in the aux directory, and will complain otherwise.
- It will also automatically distribute the file. This macro should
- be used by third-party Autoconf macros that require some supporting
- files in the aux directory specified with ‘AC_CONFIG_AUX_DIR’
- above. *Note Finding ‘configure’ Input: (autoconf)Input.
- ‘AC_SUBST’
- The first argument is automatically defined as a variable in each
- generated ‘Makefile.in’, unless ‘AM_SUBST_NOTMAKE’ is also used for
- this variable. *Note Setting Output Variables: (autoconf)Setting
- Output Variables.
- For every substituted variable VAR, ‘automake’ will add a line ‘VAR
- = VALUE’ to each ‘Makefile.in’ file. Many Autoconf macros invoke
- ‘AC_SUBST’ to set output variables this way, e.g., ‘AC_PATH_XTRA’
- defines ‘X_CFLAGS’ and ‘X_LIBS’. Thus, you can access these
- variables as ‘$(X_CFLAGS)’ and ‘$(X_LIBS)’ in any ‘Makefile.am’ if
- ‘AC_PATH_XTRA’ is called.
- ‘AM_CONDITIONAL’
- This introduces an Automake conditional (*note Conditionals::).
- ‘AM_COND_IF’
- This macro allows ‘automake’ to detect subsequent access within
- ‘configure.ac’ to a conditional previously introduced with
- ‘AM_CONDITIONAL’, thus enabling conditional ‘AC_CONFIG_FILES’
- (*note Usage of Conditionals::).
- ‘AM_GNU_GETTEXT’
- This macro is required for packages that use GNU gettext (*note
- gettext::). It is distributed with gettext. If Automake sees this
- macro it ensures that the package meets some of gettext’s
- requirements.
- ‘AM_GNU_GETTEXT_INTL_SUBDIR’
- This macro specifies that the ‘intl/’ subdirectory is to be built,
- even if the ‘AM_GNU_GETTEXT’ macro was invoked with a first
- argument of ‘external’.
- ‘AM_MAINTAINER_MODE([DEFAULT-MODE])’
- This macro adds an ‘--enable-maintainer-mode’ option to
- ‘configure’. If this is used, ‘automake’ will cause
- “maintainer-only” rules to be turned off by default in the
- generated ‘Makefile.in’s, unless DEFAULT-MODE is ‘enable’. This
- macro defines the ‘MAINTAINER_MODE’ conditional, which you can use
- in your own ‘Makefile.am’. *Note maintainer-mode::.
- ‘AM_SUBST_NOTMAKE(VAR)’
- Prevent Automake from defining a variable VAR, even if it is
- substituted by ‘config.status’. Normally, Automake defines a
- ‘make’ variable for each ‘configure’ substitution, i.e., for each
- ‘AC_SUBST([VAR])’. This macro prevents that definition from
- Automake. If ‘AC_SUBST’ has not been called for this variable,
- then ‘AM_SUBST_NOTMAKE’ has no effects. Preventing variable
- definitions may be useful for substitution of multi-line values,
- where ‘VAR = @VALUE@’ might yield unintended results.
- ‘m4_include’
- Files included by ‘configure.ac’ using this macro will be detected
- by Automake and automatically distributed. They will also appear
- as dependencies in ‘Makefile’ rules.
- ‘m4_include’ is seldom used by ‘configure.ac’ authors, but can
- appear in ‘aclocal.m4’ when ‘aclocal’ detects that some required
- macros come from files local to your package (as opposed to macros
- installed in a system-wide directory, *note aclocal Invocation::).
- File: automake.info, Node: aclocal Invocation, Next: Macros, Prev: Optional, Up: configure
- 6.3 Auto-generating aclocal.m4
- ==============================
- Automake includes a number of Autoconf macros that can be used in your
- package (*note Macros::); some of them are actually required by Automake
- in certain situations. These macros must be defined in your
- ‘aclocal.m4’; otherwise they will not be seen by ‘autoconf’.
- The ‘aclocal’ program will automatically generate ‘aclocal.m4’ files
- based on the contents of ‘configure.ac’. This provides a convenient way
- to get Automake-provided macros, without having to search around. The
- ‘aclocal’ mechanism allows other packages to supply their own macros
- (*note Extending aclocal::). You can also use it to maintain your own
- set of custom macros (*note Local Macros::).
- At startup, ‘aclocal’ scans all the ‘.m4’ files it can find, looking
- for macro definitions (*note Macro Search Path::). Then it scans
- ‘configure.ac’. Any mention of one of the macros found in the first
- step causes that macro, and any macros it in turn requires, to be put
- into ‘aclocal.m4’.
- _Putting_ the file that contains the macro definition into
- ‘aclocal.m4’ is usually done by copying the entire text of this file,
- including unused macro definitions as well as both ‘#’ and ‘dnl’
- comments. If you want to make a comment that will be completely ignored
- by ‘aclocal’, use ‘##’ as the comment leader.
- When a file selected by ‘aclocal’ is located in a subdirectory
- specified as a relative search path with ‘aclocal’’s ‘-I’ argument,
- ‘aclocal’ assumes the file belongs to the package and uses ‘m4_include’
- instead of copying it into ‘aclocal.m4’. This makes the package
- smaller, eases dependency tracking, and cause the file to be distributed
- automatically. (*Note Local Macros::, for an example.) Any macro that
- is found in a system-wide directory, or via an absolute search path will
- be copied. So use ‘-I `pwd`/reldir’ instead of ‘-I reldir’ whenever
- some relative directory should be considered outside the package.
- The contents of ‘acinclude.m4’, if this file exists, are also
- automatically included in ‘aclocal.m4’. We recommend against using
- ‘acinclude.m4’ in new packages (*note Local Macros::).
- While computing ‘aclocal.m4’, ‘aclocal’ runs ‘autom4te’ (*note Using
- ‘Autom4te’: (autoconf)Using autom4te.) in order to trace the macros that
- are really used, and omit from ‘aclocal.m4’ all macros that are
- mentioned but otherwise unexpanded (this can happen when a macro is
- called conditionally). ‘autom4te’ is expected to be in the ‘PATH’, just
- as ‘autoconf’. Its location can be overridden using the ‘AUTOM4TE’
- environment variable.
- * Menu:
- * aclocal Options:: Options supported by aclocal
- * Macro Search Path:: How aclocal finds .m4 files
- * Extending aclocal:: Writing your own aclocal macros
- * Local Macros:: Organizing local macros
- * Serials:: Serial lines in Autoconf macros
- * Future of aclocal:: aclocal’s scheduled death
- File: automake.info, Node: aclocal Options, Next: Macro Search Path, Up: aclocal Invocation
- 6.3.1 aclocal Options
- ---------------------
- ‘aclocal’ accepts the following options:
- ‘--automake-acdir=DIR’
- Look for the automake-provided macro files in DIR instead of in the
- installation directory. This is typically used for debugging.
- ‘--system-acdir=DIR’
- Look for the system-wide third-party macro files (and the special
- ‘dirlist’ file) in DIR instead of in the installation directory.
- This is typically used for debugging.
- ‘--diff[=COMMAND]’
- Run COMMAND on M4 file that would be installed or overwritten by
- ‘--install’. The default COMMAND is ‘diff -u’. This option
- implies ‘--install’ and ‘--dry-run’.
- ‘--dry-run’
- Do not actually overwrite (or create) ‘aclocal.m4’ and M4 files
- installed by ‘--install’.
- ‘--help’
- Print a summary of the command line options and exit.
- ‘-I DIR’
- Add the directory DIR to the list of directories searched for ‘.m4’
- files.
- ‘--install’
- Install system-wide third-party macros into the first directory
- specified with ‘-I DIR’ instead of copying them in the output file.
- Note that this will happen also if DIR is an absolute path.
- When this option is used, and only when this option is used,
- ‘aclocal’ will also honor ‘#serial NUMBER’ lines that appear in
- macros: an M4 file is ignored if there exists another M4 file with
- the same basename and a greater serial number in the search path
- (*note Serials::).
- ‘--force’
- Always overwrite the output file. The default is to overwrite the
- output file only when really needed, i.e., when its contents
- changes or if one of its dependencies is younger.
- This option forces the update of ‘aclocal.m4’ (or the file
- specified with ‘--output’ below) and only this file, it has
- absolutely no influence on files that may need to be installed by
- ‘--install’.
- ‘--output=FILE’
- Cause the output to be put into FILE instead of ‘aclocal.m4’.
- ‘--print-ac-dir’
- Prints the name of the directory that ‘aclocal’ will search to find
- third-party ‘.m4’ files. When this option is given, normal
- processing is suppressed. This option was used _in the past_ by
- third-party packages to determine where to install ‘.m4’ macro
- files, but _this usage is today discouraged_, since it causes
- ‘$(prefix)’ not to be thoroughly honored (which violates the GNU
- Coding Standards), and a similar semantics can be better obtained
- with the ‘ACLOCAL_PATH’ environment variable; *note Extending
- aclocal::.
- ‘--verbose’
- Print the names of the files it examines.
- ‘--version’
- Print the version number of Automake and exit.
- ‘-W CATEGORY’
- ‘--warnings=CATEGORY’
- Output warnings falling in CATEGORY. CATEGORY can be one of:
- ‘syntax’
- dubious syntactic constructs, underquoted macros, unused
- macros, etc.
- ‘unsupported’
- unknown macros
- ‘all’
- all the warnings, this is the default
- ‘none’
- turn off all the warnings
- ‘error’
- treat warnings as errors
- All warnings are output by default.
- The environment variable ‘WARNINGS’ is honored in the same way as
- it is for ‘automake’ (*note automake Invocation::).
- File: automake.info, Node: Macro Search Path, Next: Extending aclocal, Prev: aclocal Options, Up: aclocal Invocation
- 6.3.2 Macro Search Path
- -----------------------
- By default, ‘aclocal’ searches for ‘.m4’ files in the following
- directories, in this order:
- ‘ACDIR-APIVERSION’
- This is where the ‘.m4’ macros distributed with Automake itself are
- stored. APIVERSION depends on the Automake release used; for
- example, for Automake 1.11.x, APIVERSION = ‘1.11’.
- ‘ACDIR’
- This directory is intended for third party ‘.m4’ files, and is
- configured when ‘automake’ itself is built. This is
- ‘@datadir@/aclocal/’, which typically expands to
- ‘${prefix}/share/aclocal/’. To find the compiled-in value of
- ACDIR, use the ‘--print-ac-dir’ option (*note aclocal Options::).
- As an example, suppose that ‘automake-1.11.2’ was configured with
- ‘--prefix=/usr/local’. Then, the search path would be:
- 1. ‘/usr/local/share/aclocal-1.11.2/’
- 2. ‘/usr/local/share/aclocal/’
- The paths for the ACDIR and ACDIR-APIVERSION directories can be
- changed respectively through aclocal options ‘--system-acdir’ and
- ‘--automake-acdir’ (*note aclocal Options::). Note however that these
- options are only intended for use by the internal Automake test suite,
- or for debugging under highly unusual situations; they are not
- ordinarily needed by end-users.
- As explained in (*note aclocal Options::), there are several options
- that can be used to change or extend this search path.
- Modifying the Macro Search Path: ‘-I DIR’
- .........................................
- Any extra directories specified using ‘-I’ options (*note aclocal
- Options::) are _prepended_ to this search list. Thus, ‘aclocal -I /foo
- -I /bar’ results in the following search path:
- 1. ‘/foo’
- 2. ‘/bar’
- 3. ACDIR-APIVERSION
- 4. ACDIR
- Modifying the Macro Search Path: ‘dirlist’
- ..........................................
- There is a third mechanism for customizing the search path. If a
- ‘dirlist’ file exists in ACDIR, then that file is assumed to contain a
- list of directory patterns, one per line. ‘aclocal’ expands these
- patterns to directory names, and adds them to the search list _after_
- all other directories. ‘dirlist’ entries may use shell wildcards such
- as ‘*’, ‘?’, or ‘[...]’.
- For example, suppose ‘ACDIR/dirlist’ contains the following:
- /test1
- /test2
- /test3*
- and that ‘aclocal’ was called with the ‘-I /foo -I /bar’ options. Then,
- the search path would be
- 1. ‘/foo’
- 2. ‘/bar’
- 3. ACDIR-APIVERSION
- 4. ACDIR
- 5. ‘/test1’
- 6. ‘/test2’
- and all directories with path names starting with ‘/test3’.
- If the ‘--system-acdir=DIR’ option is used, then ‘aclocal’ will
- search for the ‘dirlist’ file in DIR; but remember the warnings above
- against the use of ‘--system-acdir’.
- ‘dirlist’ is useful in the following situation: suppose that
- ‘automake’ version ‘1.11.2’ is installed with ‘--prefix=/usr’ by the
- system vendor. Thus, the default search directories are
- 1. ‘/usr/share/aclocal-1.11/’
- 2. ‘/usr/share/aclocal/’
- However, suppose further that many packages have been manually
- installed on the system, with $prefix=/usr/local, as is typical. In
- that case, many of these “extra” ‘.m4’ files are in
- ‘/usr/local/share/aclocal’. The only way to force ‘/usr/bin/aclocal’ to
- find these “extra” ‘.m4’ files is to always call ‘aclocal -I
- /usr/local/share/aclocal’. This is inconvenient. With ‘dirlist’, one
- may create a file ‘/usr/share/aclocal/dirlist’ containing only the
- single line
- /usr/local/share/aclocal
- Now, the “default” search path on the affected system is
- 1. ‘/usr/share/aclocal-1.11/’
- 2. ‘/usr/share/aclocal/’
- 3. ‘/usr/local/share/aclocal/’
- without the need for ‘-I’ options; ‘-I’ options can be reserved for
- project-specific needs (‘my-source-dir/m4/’), rather than using it to
- work around local system-dependent tool installation directories.
- Similarly, ‘dirlist’ can be handy if you have installed a local copy
- of Automake in your account and want ‘aclocal’ to look for macros
- installed at other places on the system.
- Modifying the Macro Search Path: ‘ACLOCAL_PATH’
- ...............................................
- The fourth and last mechanism to customize the macro search path is also
- the simplest. Any directory included in the colon-separated environment
- variable ‘ACLOCAL_PATH’ is added to the search path and takes precedence
- over system directories (including those found via ‘dirlist’), with the
- exception of the versioned directory ACDIR-APIVERSION (*note Macro
- Search Path::). However, directories passed via ‘-I’ will take
- precedence over directories in ‘ACLOCAL_PATH’.
- Also note that, if the ‘--install’ option is used, any ‘.m4’ file
- containing a required macro that is found in a directory listed in
- ‘ACLOCAL_PATH’ will be installed locally. In this case, serial numbers
- in ‘.m4’ are honored too, *note Serials::.
- Conversely to ‘dirlist’, ‘ACLOCAL_PATH’ is useful if you are using a
- global copy of Automake and want ‘aclocal’ to look for macros somewhere
- under your home directory.
- Planned future incompatibilities
- ................................
- The order in which the directories in the macro search path are
- currently looked up is confusing and/or suboptimal in various aspects,
- and is probably going to be changed in the future Automake release. In
- particular, directories in ‘ACLOCAL_PATH’ and ‘ACDIR’ might end up
- taking precedence over ‘ACDIR-APIVERSION’, and directories in
- ‘ACDIR/dirlist’ might end up taking precedence over ‘ACDIR’. _This is a
- possible future incompatibility!_
- File: automake.info, Node: Extending aclocal, Next: Local Macros, Prev: Macro Search Path, Up: aclocal Invocation
- 6.3.3 Writing your own aclocal macros
- -------------------------------------
- The ‘aclocal’ program doesn’t have any built-in knowledge of any macros,
- so it is easy to extend it with your own macros.
- This can be used by libraries that want to supply their own Autoconf
- macros for use by other programs. For instance, the ‘gettext’ library
- supplies a macro ‘AM_GNU_GETTEXT’ that should be used by any package
- using ‘gettext’. When the library is installed, it installs this macro
- so that ‘aclocal’ will find it.
- A macro file’s name should end in ‘.m4’. Such files should be
- installed in ‘$(datadir)/aclocal’. This is as simple as writing:
- aclocaldir = $(datadir)/aclocal
- aclocal_DATA = mymacro.m4 myothermacro.m4
- Please do use ‘$(datadir)/aclocal’, and not something based on the
- result of ‘aclocal --print-ac-dir’ (*note Hard-Coded Install Paths::,
- for arguments). It might also be helpful to suggest to the user to add
- the ‘$(datadir)/aclocal’ directory to his ‘ACLOCAL_PATH’ variable (*note
- ACLOCAL_PATH::) so that ‘aclocal’ will find the ‘.m4’ files installed by
- your package automatically.
- A file of macros should be a series of properly quoted ‘AC_DEFUN’’s
- (*note (autoconf)Macro Definitions::). The ‘aclocal’ programs also
- understands ‘AC_REQUIRE’ (*note (autoconf)Prerequisite Macros::), so it
- is safe to put each macro in a separate file. Each file should have no
- side effects but macro definitions. Especially, any call to ‘AC_PREREQ’
- should be done inside the defined macro, not at the beginning of the
- file.
- Starting with Automake 1.8, ‘aclocal’ will warn about all underquoted
- calls to ‘AC_DEFUN’. We realize this will annoy a lot of people,
- because ‘aclocal’ was not so strict in the past and many third party
- macros are underquoted; and we have to apologize for this temporary
- inconvenience. The reason we have to be stricter is that a future
- implementation of ‘aclocal’ (*note Future of aclocal::) will have to
- temporarily include all of these third party ‘.m4’ files, maybe several
- times, including even files that are not actually needed. Doing so
- should alleviate many problems of the current implementation, however it
- requires a stricter style from the macro authors. Hopefully it is easy
- to revise the existing macros. For instance,
- # bad style
- AC_PREREQ(2.68)
- AC_DEFUN(AX_FOOBAR,
- [AC_REQUIRE([AX_SOMETHING])dnl
- AX_FOO
- AX_BAR
- ])
- should be rewritten as
- AC_DEFUN([AX_FOOBAR],
- [AC_PREREQ([2.68])dnl
- AC_REQUIRE([AX_SOMETHING])dnl
- AX_FOO
- AX_BAR
- ])
- Wrapping the ‘AC_PREREQ’ call inside the macro ensures that Autoconf
- 2.68 will not be required if ‘AX_FOOBAR’ is not actually used. Most
- importantly, quoting the first argument of ‘AC_DEFUN’ allows the macro
- to be redefined or included twice (otherwise this first argument would
- be expanded during the second definition). For consistency we like to
- quote even arguments such as ‘2.68’ that do not require it.
- If you have been directed here by the ‘aclocal’ diagnostic but are
- not the maintainer of the implicated macro, you will want to contact the
- maintainer of that macro. Please make sure you have the latest version
- of the macro and that the problem hasn’t already been reported before
- doing so: people tend to work faster when they aren’t flooded by mails.
- Another situation where ‘aclocal’ is commonly used is to manage
- macros that are used locally by the package, *note Local Macros::.
- File: automake.info, Node: Local Macros, Next: Serials, Prev: Extending aclocal, Up: aclocal Invocation
- 6.3.4 Handling Local Macros
- ---------------------------
- Feature tests offered by Autoconf do not cover all needs. People often
- have to supplement existing tests with their own macros, or with
- third-party macros.
- There are two ways to organize custom macros in a package.
- The first possibility (the historical practice) is to list all your
- macros in ‘acinclude.m4’. This file will be included in ‘aclocal.m4’
- when you run ‘aclocal’, and its macro(s) will henceforth be visible to
- ‘autoconf’. However if it contains numerous macros, it will rapidly
- become difficult to maintain, and it will be almost impossible to share
- macros between packages.
- The second possibility, which we do recommend, is to write each macro
- in its own file and gather all these files in a directory. This
- directory is usually called ‘m4/’. Then it’s enough to update
- ‘configure.ac’ by adding a proper call to ‘AC_CONFIG_MACRO_DIRS’:
- AC_CONFIG_MACRO_DIRS([m4])
- ‘aclocal’ will then take care of automatically adding ‘m4/’ to its
- search path for m4 files.
- When ‘aclocal’ is run, it will build an ‘aclocal.m4’ that
- ‘m4_include’s any file from ‘m4/’ that defines a required macro. Macros
- not found locally will still be searched in system-wide directories, as
- explained in *note Macro Search Path::.
- Custom macros should be distributed for the same reason that
- ‘configure.ac’ is: so that other people have all the sources of your
- package if they want to work on it. Actually, this distribution happens
- automatically because all ‘m4_include’d files are distributed.
- However there is no consensus on the distribution of third-party
- macros that your package may use. Many libraries install their own
- macro in the system-wide ‘aclocal’ directory (*note Extending
- aclocal::). For instance, Guile ships with a file called ‘guile.m4’
- that contains the macro ‘GUILE_FLAGS’ that can be used to define setup
- compiler and linker flags appropriate for using Guile. Using
- ‘GUILE_FLAGS’ in ‘configure.ac’ will cause ‘aclocal’ to copy ‘guile.m4’
- into ‘aclocal.m4’, but as ‘guile.m4’ is not part of the project, it will
- not be distributed. Technically, that means a user who needs to rebuild
- ‘aclocal.m4’ will have to install Guile first. This is probably OK, if
- Guile already is a requirement to build the package. However, if Guile
- is only an optional feature, or if your package might run on
- architectures where Guile cannot be installed, this requirement will
- hinder development. An easy solution is to copy such third-party macros
- in your local ‘m4/’ directory so they get distributed.
- Since Automake 1.10, ‘aclocal’ offers the option ‘--install’ to copy
- these system-wide third-party macros in your local macro directory,
- helping to solve the above problem.
- With this setup, system-wide macros will be copied to ‘m4/’ the first
- time you run ‘aclocal’. Then the locally installed macros will have
- precedence over the system-wide installed macros each time ‘aclocal’ is
- run again.
- One reason why you should keep ‘--install’ in the flags even after
- the first run is that when you later edit ‘configure.ac’ and depend on a
- new macro, this macro will be installed in your ‘m4/’ automatically.
- Another one is that serial numbers (*note Serials::) can be used to
- update the macros in your source tree automatically when new system-wide
- versions are installed. A serial number should be a single line of the
- form
- #serial NNN
- where NNN contains only digits and dots. It should appear in the M4
- file before any macro definition. It is a good practice to maintain a
- serial number for each macro you distribute, even if you do not use the
- ‘--install’ option of ‘aclocal’: this allows other people to use it.
- File: automake.info, Node: Serials, Next: Future of aclocal, Prev: Local Macros, Up: aclocal Invocation
- 6.3.5 Serial Numbers
- --------------------
- Because third-party macros defined in ‘*.m4’ files are naturally shared
- between multiple projects, some people like to version them. This makes
- it easier to tell which of two M4 files is newer. Since at least 1996,
- the tradition is to use a ‘#serial’ line for this.
- A serial number should be a single line of the form
- # serial VERSION
- where VERSION is a version number containing only digits and dots.
- Usually people use a single integer, and they increment it each time
- they change the macro (hence the name of “serial”). Such a line should
- appear in the M4 file before any macro definition.
- The ‘#’ must be the first character on the line, and it is OK to have
- extra words after the version, as in
- #serial VERSION GARBAGE
- Normally these serial numbers are completely ignored by ‘aclocal’ and
- ‘autoconf’, like any genuine comment. However when using ‘aclocal’’s
- ‘--install’ feature, these serial numbers will modify the way ‘aclocal’
- selects the macros to install in the package: if two files with the same
- basename exist in your search path, and if at least one of them uses a
- ‘#serial’ line, ‘aclocal’ will ignore the file that has the older
- ‘#serial’ line (or the file that has none).
- Note that a serial number applies to a whole M4 file, not to any
- macro it contains. A file can contains multiple macros, but only one
- serial.
- Here is a use case that illustrates the use of ‘--install’ and its
- interaction with serial numbers. Let’s assume we maintain a package
- called MyPackage, the ‘configure.ac’ of which requires a third-party
- macro ‘AX_THIRD_PARTY’ defined in ‘/usr/share/aclocal/thirdparty.m4’ as
- follows:
- # serial 1
- AC_DEFUN([AX_THIRD_PARTY], [...])
- MyPackage uses an ‘m4/’ directory to store local macros as explained
- in *note Local Macros::, and has
- AC_CONFIG_MACRO_DIRS([m4])
- in its ‘configure.ac’.
- Initially the ‘m4/’ directory is empty. The first time we run
- ‘aclocal --install’, it will notice that
- • ‘configure.ac’ uses ‘AX_THIRD_PARTY’
- • No local macros define ‘AX_THIRD_PARTY’
- • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with
- serial 1.
- Because ‘/usr/share/aclocal/thirdparty.m4’ is a system-wide macro and
- ‘aclocal’ was given the ‘--install’ option, it will copy this file in
- ‘m4/thirdparty.m4’, and output an ‘aclocal.m4’ that contains
- ‘m4_include([m4/thirdparty.m4])’.
- The next time ‘aclocal --install’ is run, something different
- happens. ‘aclocal’ notices that
- • ‘configure.ac’ uses ‘AX_THIRD_PARTY’
- • ‘m4/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with serial 1.
- • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with
- serial 1.
- Because both files have the same serial number, ‘aclocal’ uses the first
- it found in its search path order (*note Macro Search Path::).
- ‘aclocal’ therefore ignores ‘/usr/share/aclocal/thirdparty.m4’ and
- outputs an ‘aclocal.m4’ that contains ‘m4_include([m4/thirdparty.m4])’.
- Local directories specified with ‘-I’ are always searched before
- system-wide directories, so a local file will always be preferred to the
- system-wide file in case of equal serial numbers.
- Now suppose the system-wide third-party macro is changed. This can
- happen if the package installing this macro is updated. Let’s suppose
- the new macro has serial number 2. The next time ‘aclocal --install’ is
- run the situation is the following:
- • ‘configure.ac’ uses ‘AX_THIRD_PARTY’
- • ‘m4/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with serial 1.
- • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with
- serial 2.
- When ‘aclocal’ sees a greater serial number, it immediately forgets
- anything it knows from files that have the same basename and a smaller
- serial number. So after it has found ‘/usr/share/aclocal/thirdparty.m4’
- with serial 2, ‘aclocal’ will proceed as if it had never seen
- ‘m4/thirdparty.m4’. This brings us back to a situation similar to that
- at the beginning of our example, where no local file defined the macro.
- ‘aclocal’ will install the new version of the macro in
- ‘m4/thirdparty.m4’, in this case overriding the old version. MyPackage
- just had its macro updated as a side effect of running ‘aclocal’.
- If you are leery of letting ‘aclocal’ update your local macro, you
- can run ‘aclocal --diff’ to review the changes ‘aclocal --install’ would
- perform on these macros.
- Finally, note that the ‘--force’ option of ‘aclocal’ has absolutely
- no effect on the files installed by ‘--install’. For instance, if you
- have modified your local macros, do not expect ‘--install --force’ to
- replace the local macros by their system-wide versions. If you want to
- do so, simply erase the local macros you want to revert, and run
- ‘aclocal --install’.
- File: automake.info, Node: Future of aclocal, Prev: Serials, Up: aclocal Invocation
- 6.3.6 The Future of ‘aclocal’
- -----------------------------
- ‘aclocal’ is expected to disappear. This feature really should not be
- offered by Automake. Automake should focus on generating ‘Makefile’s;
- dealing with M4 macros really is Autoconf’s job. The fact that some
- people install Automake just to use ‘aclocal’, but do not use ‘automake’
- otherwise is an indication of how that feature is misplaced.
- The new implementation will probably be done slightly differently.
- For instance, it could enforce the ‘m4/’-style layout discussed in *note
- Local Macros::.
- We have no idea when and how this will happen. This has been
- discussed several times in the past, but someone still has to commit to
- that non-trivial task.
- From the user point of view, ‘aclocal’’s removal might turn out to be
- painful. There is a simple precaution that you may take to make that
- switch more seamless: never call ‘aclocal’ yourself. Keep this guy
- under the exclusive control of ‘autoreconf’ and Automake’s rebuild
- rules. Hopefully you won’t need to worry about things breaking, when
- ‘aclocal’ disappears, because everything will have been taken care of.
- If otherwise you used to call ‘aclocal’ directly yourself or from some
- script, you will quickly notice the change.
- Many packages come with a script called ‘bootstrap’ or ‘autogen.sh’,
- that will just call ‘aclocal’, ‘libtoolize’, ‘gettextize’ or
- ‘autopoint’, ‘autoconf’, ‘autoheader’, and ‘automake’ in the right
- order. Actually this is precisely what ‘autoreconf’ can do for you. If
- your package has such a ‘bootstrap’ or ‘autogen.sh’ script, consider
- using ‘autoreconf’. That should simplify its logic a lot (less things
- to maintain, yum!), it’s even likely you will not need the script
- anymore, and more to the point you will not call ‘aclocal’ directly
- anymore.
- For the time being, third-party packages should continue to install
- public macros into ‘/usr/share/aclocal/’. If ‘aclocal’ is replaced by
- another tool it might make sense to rename the directory, but supporting
- ‘/usr/share/aclocal/’ for backward compatibility should be really easy
- provided all macros are properly written (*note Extending aclocal::).
- File: automake.info, Node: Macros, Prev: aclocal Invocation, Up: configure
- 6.4 Autoconf macros supplied with Automake
- ==========================================
- Automake ships with several Autoconf macros that you can use from your
- ‘configure.ac’. When you use one of them it will be included by
- ‘aclocal’ in ‘aclocal.m4’.
- * Menu:
- * Public Macros:: Macros that you can use.
- * Obsolete Macros:: Macros that will soon be removed.
- * Private Macros:: Macros that you should not use.
- File: automake.info, Node: Public Macros, Next: Obsolete Macros, Up: Macros
- 6.4.1 Public Macros
- -------------------
- ‘AM_INIT_AUTOMAKE([OPTIONS])’
- Runs many macros required for proper operation of the generated
- Makefiles.
- Today, ‘AM_INIT_AUTOMAKE’ is called with a single argument: a
- space-separated list of Automake options that should be applied to
- every ‘Makefile.am’ in the tree. The effect is as if each option
- were listed in ‘AUTOMAKE_OPTIONS’ (*note Options::).
- This macro can also be called in another, _deprecated_ form:
- ‘AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])’. In this form,
- there are two required arguments: the package and the version
- number. This usage is mostly obsolete because the PACKAGE and
- VERSION can be obtained from Autoconf’s ‘AC_INIT’ macro. However,
- differently from what happens for ‘AC_INIT’ invocations, this
- ‘AM_INIT_AUTOMAKE’ invocation supports shell variables’ expansions
- in the ‘PACKAGE’ and ‘VERSION’ arguments (which otherwise defaults,
- respectively, to the ‘PACKAGE_TARNAME’ and ‘PACKAGE_VERSION’
- defined via the ‘AC_INIT’ invocation; *note The ‘AC_INIT’ macro:
- (autoconf)AC_INIT.); and this can be still be useful in some
- selected situations. Our hope is that future Autoconf versions
- will improve their support for package versions defined dynamically
- at configure runtime; when (and if) this happens, support for the
- two-args ‘AM_INIT_AUTOMAKE’ invocation will likely be removed from
- Automake.
- If your ‘configure.ac’ has:
- AC_INIT([src/foo.c])
- AM_INIT_AUTOMAKE([mumble], [1.5])
- you should modernize it as follows:
- AC_INIT([mumble], [1.5])
- AC_CONFIG_SRCDIR([src/foo.c])
- AM_INIT_AUTOMAKE
- Note that if you’re upgrading your ‘configure.ac’ from an earlier
- version of Automake, it is not always correct to simply move the
- package and version arguments from ‘AM_INIT_AUTOMAKE’ directly to
- ‘AC_INIT’, as in the example above. The first argument to
- ‘AC_INIT’ should be the name of your package (e.g., ‘GNU
- Automake’), not the tarball name (e.g., ‘automake’) that you used
- to pass to ‘AM_INIT_AUTOMAKE’. Autoconf tries to derive a tarball
- name from the package name, which should work for most but not all
- package names. (If it doesn’t work for yours, you can use the
- four-argument form of ‘AC_INIT’ to provide the tarball name
- explicitly).
- By default this macro ‘AC_DEFINE’’s ‘PACKAGE’ and ‘VERSION’. This
- can be avoided by passing the ‘no-define’ option (*note List of
- Automake options::):
- AM_INIT_AUTOMAKE([no-define ...])
- ‘AM_PATH_LISPDIR’
- Searches for the program ‘emacs’, and, if found, sets the output
- variable ‘lispdir’ to the full path to Emacs’ site-lisp directory.
- Note that this test assumes the ‘emacs’ found to be a version that
- supports Emacs Lisp (such as GNU Emacs or XEmacs). Other emacsen
- can cause this test to hang (some, like old versions of MicroEmacs,
- start up in interactive mode, requiring ‘C-x C-c’ to exit, which is
- hardly obvious for a non-emacs user). In most cases, however, you
- should be able to use ‘C-c’ to kill the test. In order to avoid
- problems, you can set ‘EMACS’ to “no” in the environment, or use
- the ‘--with-lispdir’ option to ‘configure’ to explicitly set the
- correct path (if you’re sure you have an ‘emacs’ that supports
- Emacs Lisp).
- ‘AM_PROG_AR([ACT-IF-FAIL])’
- You must use this macro when you use the archiver in your project,
- if you want support for unusual archivers such as Microsoft ‘lib’.
- The content of the optional argument is executed if the archiver
- interface is not recognized; the default action is to abort
- configure with an error message.
- ‘AM_PROG_AS’
- Use this macro when you have assembly code in your project. This
- will choose the assembler for you (by default the C compiler) and
- set ‘CCAS’, and will also set ‘CCASFLAGS’ if required.
- ‘AM_PROG_CC_C_O’
- This is an obsolescent macro that checks that the C compiler
- supports the ‘-c’ and ‘-o’ options together. Note that, since
- Automake 1.14, the ‘AC_PROG_CC’ is rewritten to implement such
- checks itself, and thus the explicit use of ‘AM_PROG_CC_C_O’ should
- no longer be required.
- ‘AM_PROG_LEX’
- Like ‘AC_PROG_LEX’ (*note Particular Program Checks:
- (autoconf)Particular Programs.), but uses the ‘missing’ script on
- systems that do not have ‘lex’. HP-UX 10 is one such system.
- ‘AM_PROG_GCJ’
- This macro finds the ‘gcj’ program or causes an error. It sets
- ‘GCJ’ and ‘GCJFLAGS’. ‘gcj’ is the Java front-end to the GNU
- Compiler Collection.
- ‘AM_PROG_UPC([COMPILER-SEARCH-LIST])’
- Find a compiler for Unified Parallel C and define the ‘UPC’
- variable. The default COMPILER-SEARCH-LIST is ‘upcc upc’. This
- macro will abort ‘configure’ if no Unified Parallel C compiler is
- found.
- ‘AM_MISSING_PROG(NAME, PROGRAM)’
- Find a maintainer tool PROGRAM and define the NAME environment
- variable with its location. If PROGRAM is not detected, then NAME
- will instead invoke the ‘missing’ script, in order to give useful
- advice to the user about the missing maintainer tool. *Note
- maintainer-mode::, for more information on when the ‘missing’
- script is appropriate.
- ‘AM_SILENT_RULES’
- Control the machinery for less verbose build output (*note Automake
- Silent Rules::).
- ‘AM_WITH_DMALLOC’
- Add support for the Dmalloc package (http://dmalloc.com/). If the
- user runs ‘configure’ with ‘--with-dmalloc’, then define
- ‘WITH_DMALLOC’ and add ‘-ldmalloc’ to ‘LIBS’.
- File: automake.info, Node: Obsolete Macros, Next: Private Macros, Prev: Public Macros, Up: Macros
- 6.4.2 Obsolete Macros
- ---------------------
- Although using some of the following macros was required in past
- releases, you should not use any of them in new code. _All these macros
- will be removed in the next major Automake version_; if you are still
- using them, running ‘autoupdate’ should adjust your ‘configure.ac’
- automatically (*note Using ‘autoupdate’ to Modernize ‘configure.ac’:
- (autoconf)autoupdate Invocation.). _Do it NOW!_
- ‘AM_PROG_MKDIR_P’
- From Automake 1.8 to 1.9.6 this macro used to define the output
- variable ‘mkdir_p’ to one of ‘mkdir -p’, ‘install-sh -d’, or
- ‘mkinstalldirs’.
- Nowadays Autoconf provides a similar functionality with
- ‘AC_PROG_MKDIR_P’ (*note Particular Program Checks:
- (autoconf)Particular Programs.), however this defines the output
- variable ‘MKDIR_P’ instead. In case you are still using the
- ‘AM_PROG_MKDIR_P’ macro in your ‘configure.ac’, or its provided
- variable ‘$(mkdir_p)’ in your ‘Makefile.am’, you are advised to
- switch ASAP to the more modern Autoconf-provided interface instead;
- both the macro and the variable might be removed in a future major
- Automake release.
- File: automake.info, Node: Private Macros, Prev: Obsolete Macros, Up: Macros
- 6.4.3 Private Macros
- --------------------
- The following macros are private macros you should not call directly.
- They are called by the other public macros when appropriate. Do not
- rely on them, as they might be changed in a future version. Consider
- them as implementation details; or better, do not consider them at all:
- skip this section!
- ‘_AM_DEPENDENCIES’
- ‘AM_SET_DEPDIR’
- ‘AM_DEP_TRACK’
- ‘AM_OUTPUT_DEPENDENCY_COMMANDS’
- These macros are used to implement Automake’s automatic dependency
- tracking scheme. They are called automatically by Automake when
- required, and there should be no need to invoke them manually.
- ‘AM_MAKE_INCLUDE’
- This macro is used to discover how the user’s ‘make’ handles
- ‘include’ statements. This macro is automatically invoked when
- needed; there should be no need to invoke it manually.
- ‘AM_PROG_INSTALL_STRIP’
- This is used to find a version of ‘install’ that can be used to
- strip a program at installation time. This macro is automatically
- included when required.
- ‘AM_SANITY_CHECK’
- This checks to make sure that a file created in the build directory
- is newer than a file in the source directory. This can fail on
- systems where the clock is set incorrectly. This macro is
- automatically run from ‘AM_INIT_AUTOMAKE’.
- File: automake.info, Node: Directories, Next: Programs, Prev: configure, Up: Top
- 7 Directories
- *************
- For simple projects that distribute all files in the same directory it
- is enough to have a single ‘Makefile.am’ that builds everything in
- place.
- In larger projects, it is common to organize files in different
- directories, in a tree. For example, there could be a directory for the
- program’s source, one for the testsuite, and one for the documentation;
- or, for very large projects, there could be one directory per program,
- per library or per module.
- The traditional approach is to build these subdirectories
- recursively, employing _make recursion_: each directory contains its own
- ‘Makefile’, and when ‘make’ is run from the top-level directory, it
- enters each subdirectory in turn, and invokes there a new ‘make’
- instance to build the directory’s contents.
- Because this approach is very widespread, Automake offers built-in
- support for it. However, it is worth nothing that the use of make
- recursion has its own serious issues and drawbacks, and that it’s well
- possible to have packages with a multi directory layout that make little
- or no use of such recursion (examples of such packages are GNU Bison and
- GNU Automake itself); see also the *note Alternative:: section below.
- * Menu:
- * Subdirectories:: Building subdirectories recursively
- * Conditional Subdirectories:: Conditionally not building directories
- * Alternative:: Subdirectories without recursion
- * Subpackages:: Nesting packages
- File: automake.info, Node: Subdirectories, Next: Conditional Subdirectories, Up: Directories
- 7.1 Recursing subdirectories
- ============================
- In packages using make recursion, the top level ‘Makefile.am’ must tell
- Automake which subdirectories are to be built. This is done via the
- ‘SUBDIRS’ variable.
- The ‘SUBDIRS’ variable holds a list of subdirectories in which
- building of various sorts can occur. The rules for many targets (e.g.,
- ‘all’) in the generated ‘Makefile’ will run commands both locally and in
- all specified subdirectories. Note that the directories listed in
- ‘SUBDIRS’ are not required to contain ‘Makefile.am’s; only ‘Makefile’s
- (after configuration). This allows inclusion of libraries from packages
- that do not use Automake (such as ‘gettext’; see also *note Third-Party
- Makefiles::).
- In packages that use subdirectories, the top-level ‘Makefile.am’ is
- often very short. For instance, here is the ‘Makefile.am’ from the GNU
- Hello distribution:
- EXTRA_DIST = BUGS ChangeLog.O README-alpha
- SUBDIRS = doc intl po src tests
- When Automake invokes ‘make’ in a subdirectory, it uses the value of
- the ‘MAKE’ variable. It passes the value of the variable ‘AM_MAKEFLAGS’
- to the ‘make’ invocation; this can be set in ‘Makefile.am’ if there are
- flags you must always pass to ‘make’.
- The directories mentioned in ‘SUBDIRS’ are usually direct children of
- the current directory, each subdirectory containing its own
- ‘Makefile.am’ with a ‘SUBDIRS’ pointing to deeper subdirectories.
- Automake can be used to construct packages of arbitrary depth this way.
- By default, Automake generates ‘Makefiles’ that work depth-first in
- postfix order: the subdirectories are built before the current
- directory. However, it is possible to change this ordering. You can do
- this by putting ‘.’ into ‘SUBDIRS’. For instance, putting ‘.’ first
- will cause a prefix ordering of directories.
- Using
- SUBDIRS = lib src . test
- will cause ‘lib/’ to be built before ‘src/’, then the current directory
- will be built, finally the ‘test/’ directory will be built. It is
- customary to arrange test directories to be built after everything else
- since they are meant to test what has been constructed.
- In addition to the built-in recursive targets defined by Automake
- (‘all’, ‘check’, etc.), the developer can also define his own recursive
- targets. That is done by passing the names of such targets as arguments
- to the m4 macro ‘AM_EXTRA_RECURSIVE_TARGETS’ in ‘configure.ac’.
- Automake generates rules to handle the recursion for such targets; and
- the developer can define real actions for them by defining corresponding
- ‘-local’ targets.
- % cat configure.ac
- AC_INIT([pkg-name], [1.0]
- AM_INIT_AUTOMAKE
- AM_EXTRA_RECURSIVE_TARGETS([foo])
- AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
- AC_OUTPUT
- % cat Makefile.am
- SUBDIRS = sub
- foo-local:
- @echo This will be run by "make foo".
- % cat sub/Makefile.am
- SUBDIRS = src
- % cat sub/src/Makefile.am
- foo-local:
- @echo This too will be run by a "make foo" issued either in
- @echo the 'sub/src/' directory, the 'sub/' directory, or the
- @echo top-level directory.
- File: automake.info, Node: Conditional Subdirectories, Next: Alternative, Prev: Subdirectories, Up: Directories
- 7.2 Conditional Subdirectories
- ==============================
- It is possible to define the ‘SUBDIRS’ variable conditionally if, like
- in the case of GNU Inetutils, you want to only build a subset of the
- entire package.
- To illustrate how this works, let’s assume we have two directories
- ‘src/’ and ‘opt/’. ‘src/’ should always be built, but we want to decide
- in ‘configure’ whether ‘opt/’ will be built or not. (For this example
- we will assume that ‘opt/’ should be built when the variable ‘$want_opt’
- was set to ‘yes’.)
- Running ‘make’ should thus recurse into ‘src/’ always, and then maybe
- in ‘opt/’.
- However ‘make dist’ should always recurse into both ‘src/’ and
- ‘opt/’. Because ‘opt/’ should be distributed even if it is not needed
- in the current configuration. This means ‘opt/Makefile’ should be
- created _unconditionally_.
- There are two ways to setup a project like this. You can use
- Automake conditionals (*note Conditionals::) or use Autoconf ‘AC_SUBST’
- variables (*note Setting Output Variables: (autoconf)Setting Output
- Variables.). Using Automake conditionals is the preferred solution.
- Before we illustrate these two possibilities, let’s introduce
- ‘DIST_SUBDIRS’.
- * Menu:
- * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
- * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
- * Subdirectories with AC_SUBST:: Another way for conditional recursion
- * Unconfigured Subdirectories:: Not even creating a ‘Makefile’
- File: automake.info, Node: SUBDIRS vs DIST_SUBDIRS, Next: Subdirectories with AM_CONDITIONAL, Up: Conditional Subdirectories
- 7.2.1 ‘SUBDIRS’ vs. ‘DIST_SUBDIRS’
- ----------------------------------
- Automake considers two sets of directories, defined by the variables
- ‘SUBDIRS’ and ‘DIST_SUBDIRS’.
- ‘SUBDIRS’ contains the subdirectories of the current directory that
- must be built (*note Subdirectories::). It must be defined manually;
- Automake will never guess a directory is to be built. As we will see in
- the next two sections, it is possible to define it conditionally so that
- some directory will be omitted from the build.
- ‘DIST_SUBDIRS’ is used in rules that need to recurse in all
- directories, even those that have been conditionally left out of the
- build. Recall our example where we may not want to build subdirectory
- ‘opt/’, but yet we want to distribute it? This is where ‘DIST_SUBDIRS’
- comes into play: ‘opt’ may not appear in ‘SUBDIRS’, but it must appear
- in ‘DIST_SUBDIRS’.
- Precisely, ‘DIST_SUBDIRS’ is used by ‘make maintainer-clean’, ‘make
- distclean’ and ‘make dist’. All other recursive rules use ‘SUBDIRS’.
- If ‘SUBDIRS’ is defined conditionally using Automake conditionals,
- Automake will define ‘DIST_SUBDIRS’ automatically from the possible
- values of ‘SUBDIRS’ in all conditions.
- If ‘SUBDIRS’ contains ‘AC_SUBST’ variables, ‘DIST_SUBDIRS’ will not
- be defined correctly because Automake does not know the possible values
- of these variables. In this case ‘DIST_SUBDIRS’ needs to be defined
- manually.
- File: automake.info, Node: Subdirectories with AM_CONDITIONAL, Next: Subdirectories with AC_SUBST, Prev: SUBDIRS vs DIST_SUBDIRS, Up: Conditional Subdirectories
- 7.2.2 Subdirectories with ‘AM_CONDITIONAL’
- ------------------------------------------
- ‘configure’ should output the ‘Makefile’ for each directory and define a
- condition into which ‘opt/’ should be built.
- ...
- AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
- AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
- ...
- Then ‘SUBDIRS’ can be defined in the top-level ‘Makefile.am’ as
- follows.
- if COND_OPT
- MAYBE_OPT = opt
- endif
- SUBDIRS = src $(MAYBE_OPT)
- As you can see, running ‘make’ will rightly recurse into ‘src/’ and
- maybe ‘opt/’.
- As you can’t see, running ‘make dist’ will recurse into both ‘src/’
- and ‘opt/’ directories because ‘make dist’, unlike ‘make all’, doesn’t
- use the ‘SUBDIRS’ variable. It uses the ‘DIST_SUBDIRS’ variable.
- In this case Automake will define ‘DIST_SUBDIRS = src opt’
- automatically because it knows that ‘MAYBE_OPT’ can contain ‘opt’ in
- some condition.
- File: automake.info, Node: Subdirectories with AC_SUBST, Next: Unconfigured Subdirectories, Prev: Subdirectories with AM_CONDITIONAL, Up: Conditional Subdirectories
- 7.2.3 Subdirectories with ‘AC_SUBST’
- ------------------------------------
- Another possibility is to define ‘MAYBE_OPT’ from ‘./configure’ using
- ‘AC_SUBST’:
- ...
- if test "$want_opt" = yes; then
- MAYBE_OPT=opt
- else
- MAYBE_OPT=
- fi
- AC_SUBST([MAYBE_OPT])
- AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
- ...
- In this case the top-level ‘Makefile.am’ should look as follows.
- SUBDIRS = src $(MAYBE_OPT)
- DIST_SUBDIRS = src opt
- The drawback is that since Automake cannot guess what the possible
- values of ‘MAYBE_OPT’ are, it is necessary to define ‘DIST_SUBDIRS’.
- File: automake.info, Node: Unconfigured Subdirectories, Prev: Subdirectories with AC_SUBST, Up: Conditional Subdirectories
- 7.2.4 Unconfigured Subdirectories
- ---------------------------------
- The semantics of ‘DIST_SUBDIRS’ are often misunderstood by some users
- that try to _configure and build_ subdirectories conditionally. Here by
- configuring we mean creating the ‘Makefile’ (it might also involve
- running a nested ‘configure’ script: this is a costly operation that
- explains why people want to do it conditionally, but only the ‘Makefile’
- is relevant to the discussion).
- The above examples all assume that every ‘Makefile’ is created, even
- in directories that are not going to be built. The simple reason is
- that we want ‘make dist’ to distribute even the directories that are not
- being built (e.g., platform-dependent code), hence ‘make dist’ must
- recurse into the subdirectory, hence this directory must be configured
- and appear in ‘DIST_SUBDIRS’.
- Building packages that do not configure every subdirectory is a
- tricky business, and we do not recommend it to the novice as it is easy
- to produce an incomplete tarball by mistake. We will not discuss this
- topic in depth here, yet for the adventurous here are a few rules to
- remember.
- • ‘SUBDIRS’ should always be a subset of ‘DIST_SUBDIRS’.
- It makes little sense to have a directory in ‘SUBDIRS’ that is not
- in ‘DIST_SUBDIRS’. Think of the former as a way to tell which
- directories listed in the latter should be built.
- • Any directory listed in ‘DIST_SUBDIRS’ and ‘SUBDIRS’ must be
- configured.
- I.e., the ‘Makefile’ must exists or the recursive ‘make’ rules will
- not be able to process the directory.
- • Any configured directory must be listed in ‘DIST_SUBDIRS’.
- So that the cleaning rules remove the generated ‘Makefile’s. It
- would be correct to see ‘DIST_SUBDIRS’ as a variable that lists all
- the directories that have been configured.
- In order to prevent recursion in some unconfigured directory you must
- therefore ensure that this directory does not appear in ‘DIST_SUBDIRS’
- (and ‘SUBDIRS’). For instance, if you define ‘SUBDIRS’ conditionally
- using ‘AC_SUBST’ and do not define ‘DIST_SUBDIRS’ explicitly, it will be
- default to ‘$(SUBDIRS)’; another possibility is to force ‘DIST_SUBDIRS =
- $(SUBDIRS)’.
- Of course, directories that are omitted from ‘DIST_SUBDIRS’ will not
- be distributed unless you make other arrangements for this to happen
- (for instance, always running ‘make dist’ in a configuration where all
- directories are known to appear in ‘DIST_SUBDIRS’; or writing a
- ‘dist-hook’ target to distribute these directories).
- In few packages, unconfigured directories are not even expected to be
- distributed. Although these packages do not require the aforementioned
- extra arrangements, there is another pitfall. If the name of a
- directory appears in ‘SUBDIRS’ or ‘DIST_SUBDIRS’, ‘automake’ will make
- sure the directory exists. Consequently ‘automake’ cannot be run on
- such a distribution when one directory has been omitted. One way to
- avoid this check is to use the ‘AC_SUBST’ method to declare conditional
- directories; since ‘automake’ does not know the values of ‘AC_SUBST’
- variables it cannot ensure the corresponding directory exists.
- File: automake.info, Node: Alternative, Next: Subpackages, Prev: Conditional Subdirectories, Up: Directories
- 7.3 An Alternative Approach to Subdirectories
- =============================================
- If you’ve ever read Peter Miller’s excellent paper, Recursive Make
- Considered Harmful (http://miller.emu.id.au/pmiller/books/rmch/), the
- preceding sections on the use of make recursion will probably come as
- unwelcome advice. For those who haven’t read the paper, Miller’s main
- thesis is that recursive ‘make’ invocations are both slow and
- error-prone.
- Automake provides sufficient cross-directory support (1) to enable
- you to write a single ‘Makefile.am’ for a complex multi-directory
- package.
- By default an installable file specified in a subdirectory will have
- its directory name stripped before installation. For instance, in this
- example, the header file will be installed as ‘$(includedir)/stdio.h’:
- include_HEADERS = inc/stdio.h
- However, the ‘nobase_’ prefix can be used to circumvent this path
- stripping. In this example, the header file will be installed as
- ‘$(includedir)/sys/types.h’:
- nobase_include_HEADERS = sys/types.h
- ‘nobase_’ should be specified first when used in conjunction with
- either ‘dist_’ or ‘nodist_’ (*note Fine-grained Distribution Control::).
- For instance:
- nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
- Finally, note that a variable using the ‘nobase_’ prefix can often be
- replaced by several variables, one for each destination directory (*note
- Uniform::). For instance, the last example could be rewritten as
- follows:
- imagesdir = $(pkgdatadir)/images
- soundsdir = $(pkgdatadir)/sounds
- dist_images_DATA = images/vortex.pgm
- dist_sounds_DATA = sounds/whirl.ogg
- This latter syntax makes it possible to change one destination directory
- without changing the layout of the source tree.
- Currently, ‘nobase_*_LTLIBRARIES’ are the only exception to this
- rule, in that there is no particular installation order guarantee for an
- otherwise equivalent set of variables without ‘nobase_’ prefix.
- ---------- Footnotes ----------
- (1) We believe. This work is new and there are probably warts.
- *Note Introduction::, for information on reporting bugs.
- File: automake.info, Node: Subpackages, Prev: Alternative, Up: Directories
- 7.4 Nesting Packages
- ====================
- In the GNU Build System, packages can be nested to arbitrary depth.
- This means that a package can embed other packages with their own
- ‘configure’, ‘Makefile’s, etc.
- These other packages should just appear as subdirectories of their
- parent package. They must be listed in ‘SUBDIRS’ like other ordinary
- directories. However the subpackage’s ‘Makefile’s should be output by
- its own ‘configure’ script, not by the parent’s ‘configure’. This is
- achieved using the ‘AC_CONFIG_SUBDIRS’ Autoconf macro (*note
- AC_CONFIG_SUBDIRS: (autoconf)Subdirectories.).
- Here is an example package for an ‘arm’ program that links with a
- ‘hand’ library that is a nested package in subdirectory ‘hand/’.
- ‘arm’’s ‘configure.ac’:
- AC_INIT([arm], [1.0])
- AC_CONFIG_AUX_DIR([.])
- AM_INIT_AUTOMAKE
- AC_PROG_CC
- AC_CONFIG_FILES([Makefile])
- # Call hand's ./configure script recursively.
- AC_CONFIG_SUBDIRS([hand])
- AC_OUTPUT
- ‘arm’’s ‘Makefile.am’:
- # Build the library in the hand subdirectory first.
- SUBDIRS = hand
- # Include hand's header when compiling this directory.
- AM_CPPFLAGS = -I$(srcdir)/hand
- bin_PROGRAMS = arm
- arm_SOURCES = arm.c
- # link with the hand library.
- arm_LDADD = hand/libhand.a
- Now here is ‘hand’’s ‘hand/configure.ac’:
- AC_INIT([hand], [1.2])
- AC_CONFIG_AUX_DIR([.])
- AM_INIT_AUTOMAKE
- AC_PROG_CC
- AM_PROG_AR
- AC_PROG_RANLIB
- AC_CONFIG_FILES([Makefile])
- AC_OUTPUT
- and its ‘hand/Makefile.am’:
- lib_LIBRARIES = libhand.a
- libhand_a_SOURCES = hand.c
- When ‘make dist’ is run from the top-level directory it will create
- an archive ‘arm-1.0.tar.gz’ that contains the ‘arm’ code as well as the
- ‘hand’ subdirectory. This package can be built and installed like any
- ordinary package, with the usual ‘./configure && make && make install’
- sequence (the ‘hand’ subpackage will be built and installed by the
- process).
- When ‘make dist’ is run from the hand directory, it will create a
- self-contained ‘hand-1.2.tar.gz’ archive. So although it appears to be
- embedded in another package, it can still be used separately.
- The purpose of the ‘AC_CONFIG_AUX_DIR([.])’ instruction is to force
- Automake and Autoconf to search for auxiliary scripts in the current
- directory. For instance, this means that there will be two copies of
- ‘install-sh’: one in the top-level of the ‘arm’ package, and another one
- in the ‘hand/’ subdirectory for the ‘hand’ package.
- The historical default is to search for these auxiliary scripts in
- the parent directory and the grandparent directory. So if the
- ‘AC_CONFIG_AUX_DIR([.])’ line was removed from ‘hand/configure.ac’, that
- subpackage would share the auxiliary script of the ‘arm’ package. This
- may looks like a gain in size (a few kilobytes), but it is actually a
- loss of modularity as the ‘hand’ subpackage is no longer self-contained
- (‘make dist’ in the subdirectory will not work anymore).
- Packages that do not use Automake need more work to be integrated
- this way. *Note Third-Party Makefiles::.
- File: automake.info, Node: Programs, Next: Other Objects, Prev: Directories, Up: Top
- 8 Building Programs and Libraries
- *********************************
- A large part of Automake’s functionality is dedicated to making it easy
- to build programs and libraries.
- * Menu:
- * A Program:: Building a program
- * A Library:: Building a library
- * A Shared Library:: Building a Libtool library
- * Program and Library Variables:: Variables controlling program and
- library builds
- * Default _SOURCES:: Default source files
- * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
- * Program Variables:: Variables used when building a program
- * Yacc and Lex:: Yacc and Lex support
- * C++ Support:: Compiling C++ sources
- * Objective C Support:: Compiling Objective C sources
- * Objective C++ Support:: Compiling Objective C++ sources
- * Unified Parallel C Support:: Compiling Unified Parallel C sources
- * Assembly Support:: Compiling assembly sources
- * Fortran 77 Support:: Compiling Fortran 77 sources
- * Fortran 9x Support:: Compiling Fortran 9x sources
- * Java Support with gcj:: Compiling Java sources using gcj
- * Vala Support:: Compiling Vala sources
- * Support for Other Languages:: Compiling other languages
- * Dependencies:: Automatic dependency tracking
- * EXEEXT:: Support for executable extensions
- File: automake.info, Node: A Program, Next: A Library, Up: Programs
- 8.1 Building a program
- ======================
- In order to build a program, you need to tell Automake which sources are
- part of it, and which libraries it should be linked with.
- This section also covers conditional compilation of sources or
- programs. Most of the comments about these also apply to libraries
- (*note A Library::) and libtool libraries (*note A Shared Library::).
- * Menu:
- * Program Sources:: Defining program sources
- * Linking:: Linking with libraries or extra objects
- * Conditional Sources:: Handling conditional sources
- * Conditional Programs:: Building a program conditionally
- File: automake.info, Node: Program Sources, Next: Linking, Up: A Program
- 8.1.1 Defining program sources
- ------------------------------
- In a directory containing source that gets built into a program (as
- opposed to a library or a script), the ‘PROGRAMS’ primary is used.
- Programs can be installed in ‘bindir’, ‘sbindir’, ‘libexecdir’,
- ‘pkglibexecdir’, or not at all (‘noinst_’). They can also be built only
- for ‘make check’, in which case the prefix is ‘check_’.
- For instance:
- bin_PROGRAMS = hello
- In this simple case, the resulting ‘Makefile.in’ will contain code to
- generate a program named ‘hello’.
- Associated with each program are several assisting variables that are
- named after the program. These variables are all optional, and have
- reasonable defaults. Each variable, its use, and default is spelled out
- below; we use the “hello” example throughout.
- The variable ‘hello_SOURCES’ is used to specify which source files
- get built into an executable:
- hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
- This causes each mentioned ‘.c’ file to be compiled into the
- corresponding ‘.o’. Then all are linked to produce ‘hello’.
- If ‘hello_SOURCES’ is not specified, then it defaults to the single
- file ‘hello.c’ (*note Default _SOURCES::).
- Multiple programs can be built in a single directory. Multiple
- programs can share a single source file, which must be listed in each
- ‘_SOURCES’ definition.
- Header files listed in a ‘_SOURCES’ definition will be included in
- the distribution but otherwise ignored. In case it isn’t obvious, you
- should not include the header file generated by ‘configure’ in a
- ‘_SOURCES’ variable; this file should not be distributed. Lex (‘.l’)
- and Yacc (‘.y’) files can also be listed; see *note Yacc and Lex::.
- File: automake.info, Node: Linking, Next: Conditional Sources, Prev: Program Sources, Up: A Program
- 8.1.2 Linking the program
- -------------------------
- If you need to link against libraries that are not found by ‘configure’,
- you can use ‘LDADD’ to do so. This variable is used to specify
- additional objects or libraries to link with; it is inappropriate for
- specifying specific linker flags, you should use ‘AM_LDFLAGS’ for this
- purpose.
- Sometimes, multiple programs are built in one directory but do not
- share the same link-time requirements. In this case, you can use the
- ‘PROG_LDADD’ variable (where PROG is the name of the program as it
- appears in some ‘_PROGRAMS’ variable, and usually written in lowercase)
- to override ‘LDADD’. If this variable exists for a given program, then
- that program is not linked using ‘LDADD’.
- For instance, in GNU cpio, ‘pax’, ‘cpio’ and ‘mt’ are linked against
- the library ‘libcpio.a’. However, ‘rmt’ is built in the same directory,
- and has no such link requirement. Also, ‘mt’ and ‘rmt’ are only built
- on certain architectures. Here is what cpio’s ‘src/Makefile.am’ looks
- like (abridged):
- bin_PROGRAMS = cpio pax $(MT)
- libexec_PROGRAMS = $(RMT)
- EXTRA_PROGRAMS = mt rmt
- LDADD = ../lib/libcpio.a $(INTLLIBS)
- rmt_LDADD =
- cpio_SOURCES = ...
- pax_SOURCES = ...
- mt_SOURCES = ...
- rmt_SOURCES = ...
- ‘PROG_LDADD’ is inappropriate for passing program-specific linker
- flags (except for ‘-l’, ‘-L’, ‘-dlopen’ and ‘-dlpreopen’). So, use the
- ‘PROG_LDFLAGS’ variable for this purpose.
- It is also occasionally useful to have a program depend on some other
- target that is not actually part of that program. This can be done
- using either the ‘PROG_DEPENDENCIES’ or the ‘EXTRA_PROG_DEPENDENCIES’
- variable. Each program depends on the contents both variables, but no
- further interpretation is done.
- Since these dependencies are associated to the link rule used to
- create the programs they should normally list files used by the link
- command. That is ‘*.$(OBJEXT)’, ‘*.a’, or ‘*.la’ files. In rare cases
- you may need to add other kinds of files such as linker scripts, but
- _listing a source file in ‘_DEPENDENCIES’ is wrong_. If some source
- file needs to be built before all the components of a program are built,
- consider using the ‘BUILT_SOURCES’ variable instead (*note Sources::).
- If ‘PROG_DEPENDENCIES’ is not supplied, it is computed by Automake.
- The automatically-assigned value is the contents of ‘PROG_LDADD’, with
- most configure substitutions, ‘-l’, ‘-L’, ‘-dlopen’ and ‘-dlpreopen’
- options removed. The configure substitutions that are left in are only
- ‘$(LIBOBJS)’ and ‘$(ALLOCA)’; these are left because it is known that
- they will not cause an invalid value for ‘PROG_DEPENDENCIES’ to be
- generated.
- *note Conditional Sources:: shows a situation where ‘_DEPENDENCIES’
- may be used.
- The ‘EXTRA_PROG_DEPENDENCIES’ may be useful for cases where you
- merely want to augment the ‘automake’-generated ‘PROG_DEPENDENCIES’
- rather than replacing it.
- We recommend that you avoid using ‘-l’ options in ‘LDADD’ or
- ‘PROG_LDADD’ when referring to libraries built by your package.
- Instead, write the file name of the library explicitly as in the above
- ‘cpio’ example. Use ‘-l’ only to list third-party libraries. If you
- follow this rule, the default value of ‘PROG_DEPENDENCIES’ will list all
- your local libraries and omit the other ones.
- File: automake.info, Node: Conditional Sources, Next: Conditional Programs, Prev: Linking, Up: A Program
- 8.1.3 Conditional compilation of sources
- ----------------------------------------
- You can’t put a configure substitution (e.g., ‘@FOO@’ or ‘$(FOO)’ where
- ‘FOO’ is defined via ‘AC_SUBST’) into a ‘_SOURCES’ variable. The reason
- for this is a bit hard to explain, but suffice to say that it simply
- won’t work. Automake will give an error if you try to do this.
- Fortunately there are two other ways to achieve the same result. One
- is to use configure substitutions in ‘_LDADD’ variables, the other is to
- use an Automake conditional.
- Conditional Compilation using ‘_LDADD’ Substitutions
- ....................................................
- Automake must know all the source files that could possibly go into a
- program, even if not all the files are built in every circumstance. Any
- files that are only conditionally built should be listed in the
- appropriate ‘EXTRA_’ variable. For instance, if ‘hello-linux.c’ or
- ‘hello-generic.c’ were conditionally included in ‘hello’, the
- ‘Makefile.am’ would contain:
- bin_PROGRAMS = hello
- hello_SOURCES = hello-common.c
- EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
- hello_LDADD = $(HELLO_SYSTEM)
- hello_DEPENDENCIES = $(HELLO_SYSTEM)
- You can then setup the ‘$(HELLO_SYSTEM)’ substitution from
- ‘configure.ac’:
- ...
- case $host in
- *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
- *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
- esac
- AC_SUBST([HELLO_SYSTEM])
- ...
- In this case, the variable ‘HELLO_SYSTEM’ should be replaced by
- either ‘hello-linux.o’ or ‘hello-generic.o’, and added to both
- ‘hello_DEPENDENCIES’ and ‘hello_LDADD’ in order to be built and linked
- in.
- Conditional Compilation using Automake Conditionals
- ...................................................
- An often simpler way to compile source files conditionally is to use
- Automake conditionals. For instance, you could use this ‘Makefile.am’
- construct to build the same ‘hello’ example:
- bin_PROGRAMS = hello
- if LINUX
- hello_SOURCES = hello-linux.c hello-common.c
- else
- hello_SOURCES = hello-generic.c hello-common.c
- endif
- In this case, ‘configure.ac’ should setup the ‘LINUX’ conditional
- using ‘AM_CONDITIONAL’ (*note Conditionals::).
- When using conditionals like this you don’t need to use the ‘EXTRA_’
- variable, because Automake will examine the contents of each variable to
- construct the complete list of source files.
- If your program uses a lot of files, you will probably prefer a
- conditional ‘+=’.
- bin_PROGRAMS = hello
- hello_SOURCES = hello-common.c
- if LINUX
- hello_SOURCES += hello-linux.c
- else
- hello_SOURCES += hello-generic.c
- endif
- File: automake.info, Node: Conditional Programs, Prev: Conditional Sources, Up: A Program
- 8.1.4 Conditional compilation of programs
- -----------------------------------------
- Sometimes it is useful to determine the programs that are to be built at
- configure time. For instance, GNU ‘cpio’ only builds ‘mt’ and ‘rmt’
- under special circumstances. The means to achieve conditional
- compilation of programs are the same you can use to compile source files
- conditionally: substitutions or conditionals.
- Conditional Programs using ‘configure’ Substitutions
- ....................................................
- In this case, you must notify Automake of all the programs that can
- possibly be built, but at the same time cause the generated
- ‘Makefile.in’ to use the programs specified by ‘configure’. This is
- done by having ‘configure’ substitute values into each ‘_PROGRAMS’
- definition, while listing all optionally built programs in
- ‘EXTRA_PROGRAMS’.
- bin_PROGRAMS = cpio pax $(MT)
- libexec_PROGRAMS = $(RMT)
- EXTRA_PROGRAMS = mt rmt
- As explained in *note EXEEXT::, Automake will rewrite ‘bin_PROGRAMS’,
- ‘libexec_PROGRAMS’, and ‘EXTRA_PROGRAMS’, appending ‘$(EXEEXT)’ to each
- binary. Obviously it cannot rewrite values obtained at run-time through
- ‘configure’ substitutions, therefore you should take care of appending
- ‘$(EXEEXT)’ yourself, as in ‘AC_SUBST([MT], ['mt${EXEEXT}'])’.
- Conditional Programs using Automake Conditionals
- ................................................
- You can also use Automake conditionals (*note Conditionals::) to select
- programs to be built. In this case you don’t have to worry about
- ‘$(EXEEXT)’ or ‘EXTRA_PROGRAMS’.
- bin_PROGRAMS = cpio pax
- if WANT_MT
- bin_PROGRAMS += mt
- endif
- if WANT_RMT
- libexec_PROGRAMS = rmt
- endif
- File: automake.info, Node: A Library, Next: A Shared Library, Prev: A Program, Up: Programs
- 8.2 Building a library
- ======================
- Building a library is much like building a program. In this case, the
- name of the primary is ‘LIBRARIES’. Libraries can be installed in
- ‘libdir’ or ‘pkglibdir’.
- *Note A Shared Library::, for information on how to build shared
- libraries using libtool and the ‘LTLIBRARIES’ primary.
- Each ‘_LIBRARIES’ variable is a list of the libraries to be built.
- For instance, to create a library named ‘libcpio.a’, but not install it,
- you would write:
- noinst_LIBRARIES = libcpio.a
- libcpio_a_SOURCES = ...
- The sources that go into a library are determined exactly as they are
- for programs, via the ‘_SOURCES’ variables. Note that the library name
- is canonicalized (*note Canonicalization::), so the ‘_SOURCES’ variable
- corresponding to ‘libcpio.a’ is ‘libcpio_a_SOURCES’, not
- ‘libcpio.a_SOURCES’.
- Extra objects can be added to a library using the ‘LIBRARY_LIBADD’
- variable. This should be used for objects determined by ‘configure’.
- Again from ‘cpio’:
- libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
- In addition, sources for extra objects that will not exist until
- configure-time must be added to the ‘BUILT_SOURCES’ variable (*note
- Sources::).
- Building a static library is done by compiling all object files, then
- by invoking ‘$(AR) $(ARFLAGS)’ followed by the name of the library and
- the list of objects, and finally by calling ‘$(RANLIB)’ on that library.
- You should call ‘AC_PROG_RANLIB’ from your ‘configure.ac’ to define
- ‘RANLIB’ (Automake will complain otherwise). You should also call
- ‘AM_PROG_AR’ to define ‘AR’, in order to support unusual archivers such
- as Microsoft lib. ‘ARFLAGS’ will default to ‘cru’; you can override
- this variable by setting it in your ‘Makefile.am’ or by ‘AC_SUBST’ing it
- from your ‘configure.ac’. You can override the ‘AR’ variable by
- defining a per-library ‘maude_AR’ variable (*note Program and Library
- Variables::).
- Be careful when selecting library components conditionally. Because
- building an empty library is not portable, you should ensure that any
- library always contains at least one object.
- To use a static library when building a program, add it to ‘LDADD’
- for this program. In the following example, the program ‘cpio’ is
- statically linked with the library ‘libcpio.a’.
- noinst_LIBRARIES = libcpio.a
- libcpio_a_SOURCES = ...
- bin_PROGRAMS = cpio
- cpio_SOURCES = cpio.c ...
- cpio_LDADD = libcpio.a
- File: automake.info, Node: A Shared Library, Next: Program and Library Variables, Prev: A Library, Up: Programs
- 8.3 Building a Shared Library
- =============================
- Building shared libraries portably is a relatively complex matter. For
- this reason, GNU Libtool (*note Introduction: (libtool)Top.) was created
- to help build shared libraries in a platform-independent way.
- * Menu:
- * Libtool Concept:: Introducing Libtool
- * Libtool Libraries:: Declaring Libtool Libraries
- * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
- * Conditional Libtool Sources:: Choosing Library Sources Conditionally
- * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
- * Libtool Modules:: Building Libtool Modules
- * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
- * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
- * Libtool Issues:: Common Issues Related to Libtool’s Use
- File: automake.info, Node: Libtool Concept, Next: Libtool Libraries, Up: A Shared Library
- 8.3.1 The Libtool Concept
- -------------------------
- Libtool abstracts shared and static libraries into a unified concept
- henceforth called “libtool libraries”. Libtool libraries are files
- using the ‘.la’ suffix, and can designate a static library, a shared
- library, or maybe both. Their exact nature cannot be determined until
- ‘./configure’ is run: not all platforms support all kinds of libraries,
- and users can explicitly select which libraries should be built.
- (However the package’s maintainers can tune the default, *note The
- ‘AC_PROG_LIBTOOL’ macro: (libtool)AC_PROG_LIBTOOL.)
- Because object files for shared and static libraries must be compiled
- differently, libtool is also used during compilation. Object files
- built by libtool are called “libtool objects”: these are files using the
- ‘.lo’ suffix. Libtool libraries are built from these libtool objects.
- You should not assume anything about the structure of ‘.la’ or ‘.lo’
- files and how libtool constructs them: this is libtool’s concern, and
- the last thing one wants is to learn about libtool’s guts. However the
- existence of these files matters, because they are used as targets and
- dependencies in ‘Makefile’s rules when building libtool libraries.
- There are situations where you may have to refer to these, for instance
- when expressing dependencies for building source files conditionally
- (*note Conditional Libtool Sources::).
- People considering writing a plug-in system, with dynamically loaded
- modules, should look into ‘libltdl’: libtool’s dlopening library (*note
- Using libltdl: (libtool)Using libltdl.). This offers a portable
- dlopening facility to load libtool libraries dynamically, and can also
- achieve static linking where unavoidable.
- Before we discuss how to use libtool with Automake in details, it
- should be noted that the libtool manual also has a section about how to
- use Automake with libtool (*note Using Automake with Libtool:
- (libtool)Using Automake.).
- File: automake.info, Node: Libtool Libraries, Next: Conditional Libtool Libraries, Prev: Libtool Concept, Up: A Shared Library
- 8.3.2 Building Libtool Libraries
- --------------------------------
- Automake uses libtool to build libraries declared with the ‘LTLIBRARIES’
- primary. Each ‘_LTLIBRARIES’ variable is a list of libtool libraries to
- build. For instance, to create a libtool library named ‘libgettext.la’,
- and install it in ‘libdir’, write:
- lib_LTLIBRARIES = libgettext.la
- libgettext_la_SOURCES = gettext.c gettext.h ...
- Automake predefines the variable ‘pkglibdir’, so you can use
- ‘pkglib_LTLIBRARIES’ to install libraries in ‘$(libdir)/@PACKAGE@/’.
- If ‘gettext.h’ is a public header file that needs to be installed in
- order for people to use the library, it should be declared using a
- ‘_HEADERS’ variable, not in ‘libgettext_la_SOURCES’. Headers listed in
- the latter should be internal headers that are not part of the public
- interface.
- lib_LTLIBRARIES = libgettext.la
- libgettext_la_SOURCES = gettext.c ...
- include_HEADERS = gettext.h ...
- A package can build and install such a library along with other
- programs that use it. This dependency should be specified using
- ‘LDADD’. The following example builds a program named ‘hello’ that is
- linked with ‘libgettext.la’.
- lib_LTLIBRARIES = libgettext.la
- libgettext_la_SOURCES = gettext.c ...
- bin_PROGRAMS = hello
- hello_SOURCES = hello.c ...
- hello_LDADD = libgettext.la
- Whether ‘hello’ is statically or dynamically linked with ‘libgettext.la’
- is not yet known: this will depend on the configuration of libtool and
- the capabilities of the host.
- File: automake.info, Node: Conditional Libtool Libraries, Next: Conditional Libtool Sources, Prev: Libtool Libraries, Up: A Shared Library
- 8.3.3 Building Libtool Libraries Conditionally
- ----------------------------------------------
- Like conditional programs (*note Conditional Programs::), there are two
- main ways to build conditional libraries: using Automake conditionals or
- using Autoconf ‘AC_SUBST’itutions.
- The important implementation detail you have to be aware of is that
- the place where a library will be installed matters to libtool: it needs
- to be indicated _at link-time_ using the ‘-rpath’ option.
- For libraries whose destination directory is known when Automake
- runs, Automake will automatically supply the appropriate ‘-rpath’ option
- to libtool. This is the case for libraries listed explicitly in some
- installable ‘_LTLIBRARIES’ variables such as ‘lib_LTLIBRARIES’.
- However, for libraries determined at configure time (and thus
- mentioned in ‘EXTRA_LTLIBRARIES’), Automake does not know the final
- installation directory. For such libraries you must add the ‘-rpath’
- option to the appropriate ‘_LDFLAGS’ variable by hand.
- The examples below illustrate the differences between these two
- methods.
- Here is an example where ‘WANTEDLIBS’ is an ‘AC_SUBST’ed variable set
- at ‘./configure’-time to either ‘libfoo.la’, ‘libbar.la’, both, or none.
- Although ‘$(WANTEDLIBS)’ appears in the ‘lib_LTLIBRARIES’, Automake
- cannot guess it relates to ‘libfoo.la’ or ‘libbar.la’ at the time it
- creates the link rule for these two libraries. Therefore the ‘-rpath’
- argument must be explicitly supplied.
- EXTRA_LTLIBRARIES = libfoo.la libbar.la
- lib_LTLIBRARIES = $(WANTEDLIBS)
- libfoo_la_SOURCES = foo.c ...
- libfoo_la_LDFLAGS = -rpath '$(libdir)'
- libbar_la_SOURCES = bar.c ...
- libbar_la_LDFLAGS = -rpath '$(libdir)'
- Here is how the same ‘Makefile.am’ would look using Automake
- conditionals named ‘WANT_LIBFOO’ and ‘WANT_LIBBAR’. Now Automake is
- able to compute the ‘-rpath’ setting itself, because it’s clear that
- both libraries will end up in ‘$(libdir)’ if they are installed.
- lib_LTLIBRARIES =
- if WANT_LIBFOO
- lib_LTLIBRARIES += libfoo.la
- endif
- if WANT_LIBBAR
- lib_LTLIBRARIES += libbar.la
- endif
- libfoo_la_SOURCES = foo.c ...
- libbar_la_SOURCES = bar.c ...
- File: automake.info, Node: Conditional Libtool Sources, Next: Libtool Convenience Libraries, Prev: Conditional Libtool Libraries, Up: A Shared Library
- 8.3.4 Libtool Libraries with Conditional Sources
- ------------------------------------------------
- Conditional compilation of sources in a library can be achieved in the
- same way as conditional compilation of sources in a program (*note
- Conditional Sources::). The only difference is that ‘_LIBADD’ should be
- used instead of ‘_LDADD’ and that it should mention libtool objects
- (‘.lo’ files).
- So, to mimic the ‘hello’ example from *note Conditional Sources::, we
- could build a ‘libhello.la’ library using either ‘hello-linux.c’ or
- ‘hello-generic.c’ with the following ‘Makefile.am’.
- lib_LTLIBRARIES = libhello.la
- libhello_la_SOURCES = hello-common.c
- EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
- libhello_la_LIBADD = $(HELLO_SYSTEM)
- libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
- And make sure ‘configure’ defines ‘HELLO_SYSTEM’ as either
- ‘hello-linux.lo’ or ‘hello-generic.lo’.
- Or we could simply use an Automake conditional as follows.
- lib_LTLIBRARIES = libhello.la
- libhello_la_SOURCES = hello-common.c
- if LINUX
- libhello_la_SOURCES += hello-linux.c
- else
- libhello_la_SOURCES += hello-generic.c
- endif
- File: automake.info, Node: Libtool Convenience Libraries, Next: Libtool Modules, Prev: Conditional Libtool Sources, Up: A Shared Library
- 8.3.5 Libtool Convenience Libraries
- -----------------------------------
- Sometimes you want to build libtool libraries that should not be
- installed. These are called “libtool convenience libraries” and are
- typically used to encapsulate many sublibraries, later gathered into one
- big installed library.
- Libtool convenience libraries are declared by directory-less
- variables such as ‘noinst_LTLIBRARIES’, ‘check_LTLIBRARIES’, or even
- ‘EXTRA_LTLIBRARIES’. Unlike installed libtool libraries they do not
- need an ‘-rpath’ flag at link time (actually this is the only
- difference).
- Convenience libraries listed in ‘noinst_LTLIBRARIES’ are always
- built. Those listed in ‘check_LTLIBRARIES’ are built only upon ‘make
- check’. Finally, libraries listed in ‘EXTRA_LTLIBRARIES’ are never
- built explicitly: Automake outputs rules to build them, but if the
- library does not appear as a Makefile dependency anywhere it won’t be
- built (this is why ‘EXTRA_LTLIBRARIES’ is used for conditional
- compilation).
- Here is a sample setup merging libtool convenience libraries from
- subdirectories into one main ‘libtop.la’ library.
- # -- Top-level Makefile.am --
- SUBDIRS = sub1 sub2 ...
- lib_LTLIBRARIES = libtop.la
- libtop_la_SOURCES =
- libtop_la_LIBADD = \
- sub1/libsub1.la \
- sub2/libsub2.la \
- ...
- # -- sub1/Makefile.am --
- noinst_LTLIBRARIES = libsub1.la
- libsub1_la_SOURCES = ...
- # -- sub2/Makefile.am --
- # showing nested convenience libraries
- SUBDIRS = sub2.1 sub2.2 ...
- noinst_LTLIBRARIES = libsub2.la
- libsub2_la_SOURCES =
- libsub2_la_LIBADD = \
- sub21/libsub21.la \
- sub22/libsub22.la \
- ...
- When using such setup, beware that ‘automake’ will assume ‘libtop.la’
- is to be linked with the C linker. This is because ‘libtop_la_SOURCES’
- is empty, so ‘automake’ picks C as default language. If
- ‘libtop_la_SOURCES’ was not empty, ‘automake’ would select the linker as
- explained in *note How the Linker is Chosen::.
- If one of the sublibraries contains non-C source, it is important
- that the appropriate linker be chosen. One way to achieve this is to
- pretend that there is such a non-C file among the sources of the
- library, thus forcing ‘automake’ to select the appropriate linker. Here
- is the top-level ‘Makefile’ of our example updated to force C++ linking.
- SUBDIRS = sub1 sub2 ...
- lib_LTLIBRARIES = libtop.la
- libtop_la_SOURCES =
- # Dummy C++ source to cause C++ linking.
- nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
- libtop_la_LIBADD = \
- sub1/libsub1.la \
- sub2/libsub2.la \
- ...
- ‘EXTRA_*_SOURCES’ variables are used to keep track of source files
- that might be compiled (this is mostly useful when doing conditional
- compilation using ‘AC_SUBST’, *note Conditional Libtool Sources::), and
- the ‘nodist_’ prefix means the listed sources are not to be distributed
- (*note Program and Library Variables::). In effect the file ‘dummy.cxx’
- does not need to exist in the source tree. Of course if you have some
- real source file to list in ‘libtop_la_SOURCES’ there is no point in
- cheating with ‘nodist_EXTRA_libtop_la_SOURCES’.
- File: automake.info, Node: Libtool Modules, Next: Libtool Flags, Prev: Libtool Convenience Libraries, Up: A Shared Library
- 8.3.6 Libtool Modules
- ---------------------
- These are libtool libraries meant to be dlopened. They are indicated to
- libtool by passing ‘-module’ at link-time.
- pkglib_LTLIBRARIES = mymodule.la
- mymodule_la_SOURCES = doit.c
- mymodule_la_LDFLAGS = -module
- Ordinarily, Automake requires that a library’s name start with ‘lib’.
- However, when building a dynamically loadable module you might wish to
- use a "nonstandard" name. Automake will not complain about such
- nonstandard names if it knows the library being built is a libtool
- module, i.e., if ‘-module’ explicitly appears in the library’s
- ‘_LDFLAGS’ variable (or in the common ‘AM_LDFLAGS’ variable when no
- per-library ‘_LDFLAGS’ variable is defined).
- As always, ‘AC_SUBST’ variables are black boxes to Automake since
- their values are not yet known when ‘automake’ is run. Therefore if
- ‘-module’ is set via such a variable, Automake cannot notice it and will
- proceed as if the library was an ordinary libtool library, with strict
- naming.
- If ‘mymodule_la_SOURCES’ is not specified, then it defaults to the
- single file ‘mymodule.c’ (*note Default _SOURCES::).
- File: automake.info, Node: Libtool Flags, Next: LTLIBOBJS, Prev: Libtool Modules, Up: A Shared Library
- 8.3.7 ‘_LIBADD’, ‘_LDFLAGS’, and ‘_LIBTOOLFLAGS’
- ------------------------------------------------
- As shown in previous sections, the ‘LIBRARY_LIBADD’ variable should be
- used to list extra libtool objects (‘.lo’ files) or libtool libraries
- (‘.la’) to add to LIBRARY.
- The ‘LIBRARY_LDFLAGS’ variable is the place to list additional
- libtool linking flags, such as ‘-version-info’, ‘-static’, and a lot
- more. *Note Link mode: (libtool)Link mode.
- The ‘libtool’ command has two kinds of options: mode-specific options
- and generic options. Mode-specific options such as the aforementioned
- linking flags should be lumped with the other flags passed to the tool
- invoked by ‘libtool’ (hence the use of ‘LIBRARY_LDFLAGS’ for libtool
- linking flags). Generic options include ‘--tag=TAG’ and ‘--silent’
- (*note Invoking ‘libtool’: (libtool)Invoking libtool. for more options)
- should appear before the mode selection on the command line; in
- ‘Makefile.am’s they should be listed in the ‘LIBRARY_LIBTOOLFLAGS’
- variable.
- If ‘LIBRARY_LIBTOOLFLAGS’ is not defined, then the variable
- ‘AM_LIBTOOLFLAGS’ is used instead.
- These flags are passed to libtool after the ‘--tag=TAG’ option
- computed by Automake (if any), so ‘LIBRARY_LIBTOOLFLAGS’ (or
- ‘AM_LIBTOOLFLAGS’) is a good place to override or supplement the
- ‘--tag=TAG’ setting.
- The libtool rules also use a ‘LIBTOOLFLAGS’ variable that should not
- be set in ‘Makefile.am’: this is a user variable (*note Flag Variables
- Ordering::. It allows users to run ‘make LIBTOOLFLAGS=--silent’, for
- instance. Note that the verbosity of ‘libtool’ can also be influenced
- by the Automake support for silent rules (*note Automake Silent
- Rules::).
- File: automake.info, Node: LTLIBOBJS, Next: Libtool Issues, Prev: Libtool Flags, Up: A Shared Library
- 8.3.8 ‘LTLIBOBJS’ and ‘LTALLOCA’
- --------------------------------
- Where an ordinary library might include ‘$(LIBOBJS)’ or ‘$(ALLOCA)’
- (*note LIBOBJS::), a libtool library must use ‘$(LTLIBOBJS)’ or
- ‘$(LTALLOCA)’. This is required because the object files that libtool
- operates on do not necessarily end in ‘.o’.
- Nowadays, the computation of ‘LTLIBOBJS’ from ‘LIBOBJS’ is performed
- automatically by Autoconf (*note ‘AC_LIBOBJ’ vs. ‘LIBOBJS’:
- (autoconf)AC_LIBOBJ vs LIBOBJS.).
- File: automake.info, Node: Libtool Issues, Prev: LTLIBOBJS, Up: A Shared Library
- 8.3.9 Common Issues Related to Libtool’s Use
- --------------------------------------------
- * Menu:
- * Error required file ltmain.sh not found:: The need to run libtoolize
- * Objects created both with libtool and without:: Avoid a specific build race
- File: automake.info, Node: Error required file ltmain.sh not found, Next: Objects created both with libtool and without, Up: Libtool Issues
- 8.3.9.1 Error: ‘required file `./ltmain.sh' not found’
- ......................................................
- Libtool comes with a tool called ‘libtoolize’ that will install
- libtool’s supporting files into a package. Running this command will
- install ‘ltmain.sh’. You should execute it before ‘aclocal’ and
- ‘automake’.
- People upgrading old packages to newer autotools are likely to face
- this issue because older Automake versions used to call ‘libtoolize’.
- Therefore old build scripts do not call ‘libtoolize’.
- Since Automake 1.6, it has been decided that running ‘libtoolize’ was
- none of Automake’s business. Instead, that functionality has been moved
- into the ‘autoreconf’ command (*note Using ‘autoreconf’:
- (autoconf)autoreconf Invocation.). If you do not want to remember what
- to run and when, just learn the ‘autoreconf’ command. Hopefully,
- replacing existing ‘bootstrap’ or ‘autogen.sh’ scripts by a call to
- ‘autoreconf’ should also free you from any similar incompatible change
- in the future.
- File: automake.info, Node: Objects created both with libtool and without, Prev: Error required file ltmain.sh not found, Up: Libtool Issues
- 8.3.9.2 Objects ‘created with both libtool and without’
- .......................................................
- Sometimes, the same source file is used both to build a libtool library
- and to build another non-libtool target (be it a program or another
- library).
- Let’s consider the following ‘Makefile.am’.
- bin_PROGRAMS = prog
- prog_SOURCES = prog.c foo.c ...
- lib_LTLIBRARIES = libfoo.la
- libfoo_la_SOURCES = foo.c ...
- (In this trivial case the issue could be avoided by linking ‘libfoo.la’
- with ‘prog’ instead of listing ‘foo.c’ in ‘prog_SOURCES’. But let’s
- assume we really want to keep ‘prog’ and ‘libfoo.la’ separate.)
- Technically, it means that we should build ‘foo.$(OBJEXT)’ for
- ‘prog’, and ‘foo.lo’ for ‘libfoo.la’. The problem is that in the course
- of creating ‘foo.lo’, libtool may erase (or replace) ‘foo.$(OBJEXT)’,
- and this cannot be avoided.
- Therefore, when Automake detects this situation it will complain with
- a message such as
- object 'foo.$(OBJEXT)' created both with libtool and without
- A workaround for this issue is to ensure that these two objects get
- different basenames. As explained in *note Renamed Objects::, this
- happens automatically when per-targets flags are used.
- bin_PROGRAMS = prog
- prog_SOURCES = prog.c foo.c ...
- prog_CFLAGS = $(AM_CFLAGS)
- lib_LTLIBRARIES = libfoo.la
- libfoo_la_SOURCES = foo.c ...
- Adding ‘prog_CFLAGS = $(AM_CFLAGS)’ is almost a no-op, because when the
- ‘prog_CFLAGS’ is defined, it is used instead of ‘AM_CFLAGS’. However as
- a side effect it will cause ‘prog.c’ and ‘foo.c’ to be compiled as
- ‘prog-prog.$(OBJEXT)’ and ‘prog-foo.$(OBJEXT)’, which solves the issue.
- File: automake.info, Node: Program and Library Variables, Next: Default _SOURCES, Prev: A Shared Library, Up: Programs
- 8.4 Program and Library Variables
- =================================
- Associated with each program is a collection of variables that can be
- used to modify how that program is built. There is a similar list of
- such variables for each library. The canonical name of the program (or
- library) is used as a base for naming these variables.
- In the list below, we use the name “maude” to refer to the program or
- library. In your ‘Makefile.am’ you would replace this with the
- canonical name of your program. This list also refers to “maude” as a
- program, but in general the same rules apply for both static and dynamic
- libraries; the documentation below notes situations where programs and
- libraries differ.
- ‘maude_SOURCES’
- This variable, if it exists, lists all the source files that are
- compiled to build the program. These files are added to the
- distribution by default. When building the program, Automake will
- cause each source file to be compiled to a single ‘.o’ file (or
- ‘.lo’ when using libtool). Normally these object files are named
- after the source file, but other factors can change this. If a
- file in the ‘_SOURCES’ variable has an unrecognized extension,
- Automake will do one of two things with it. If a suffix rule
- exists for turning files with the unrecognized extension into ‘.o’
- files, then ‘automake’ will treat this file as it will any other
- source file (*note Support for Other Languages::). Otherwise, the
- file will be ignored as though it were a header file.
- The prefixes ‘dist_’ and ‘nodist_’ can be used to control whether
- files listed in a ‘_SOURCES’ variable are distributed. ‘dist_’ is
- redundant, as sources are distributed by default, but it can be
- specified for clarity if desired.
- It is possible to have both ‘dist_’ and ‘nodist_’ variants of a
- given ‘_SOURCES’ variable at once; this lets you easily distribute
- some files and not others, for instance:
- nodist_maude_SOURCES = nodist.c
- dist_maude_SOURCES = dist-me.c
- By default the output file (on Unix systems, the ‘.o’ file) will be
- put into the current build directory. However, if the option
- ‘subdir-objects’ is in effect in the current directory then the
- ‘.o’ file will be put into the subdirectory named after the source
- file. For instance, with ‘subdir-objects’ enabled,
- ‘sub/dir/file.c’ will be compiled to ‘sub/dir/file.o’. Some people
- prefer this mode of operation. You can specify ‘subdir-objects’ in
- ‘AUTOMAKE_OPTIONS’ (*note Options::).
- ‘EXTRA_maude_SOURCES’
- Automake needs to know the list of files you intend to compile
- _statically_. For one thing, this is the only way Automake has of
- knowing what sort of language support a given ‘Makefile.in’
- requires. (1) This means that, for example, you can’t put a
- configure substitution like ‘@my_sources@’ into a ‘_SOURCES’
- variable. If you intend to conditionally compile source files and
- use ‘configure’ to substitute the appropriate object names into,
- e.g., ‘_LDADD’ (see below), then you should list the corresponding
- source files in the ‘EXTRA_’ variable.
- This variable also supports ‘dist_’ and ‘nodist_’ prefixes. For
- instance, ‘nodist_EXTRA_maude_SOURCES’ would list extra sources
- that may need to be built, but should not be distributed.
- ‘maude_AR’
- A static library is created by default by invoking ‘$(AR)
- $(ARFLAGS)’ followed by the name of the library and then the
- objects being put into the library. You can override this by
- setting the ‘_AR’ variable. This is usually used with C++; some
- C++ compilers require a special invocation in order to instantiate
- all the templates that should go into a library. For instance, the
- SGI C++ compiler likes this variable set like so:
- libmaude_a_AR = $(CXX) -ar -o
- ‘maude_LIBADD’
- Extra objects can be added to a _library_ using the ‘_LIBADD’
- variable. For instance, this should be used for objects determined
- by ‘configure’ (*note A Library::).
- In the case of libtool libraries, ‘maude_LIBADD’ can also refer to
- other libtool libraries.
- ‘maude_LDADD’
- Extra objects (‘*.$(OBJEXT)’) and libraries (‘*.a’, ‘*.la’) can be
- added to a _program_ by listing them in the ‘_LDADD’ variable. For
- instance, this should be used for objects determined by ‘configure’
- (*note Linking::).
- ‘_LDADD’ and ‘_LIBADD’ are inappropriate for passing
- program-specific linker flags (except for ‘-l’, ‘-L’, ‘-dlopen’ and
- ‘-dlpreopen’). Use the ‘_LDFLAGS’ variable for this purpose.
- For instance, if your ‘configure.ac’ uses ‘AC_PATH_XTRA’, you could
- link your program against the X libraries like so:
- maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
- We recommend that you use ‘-l’ and ‘-L’ only when referring to
- third-party libraries, and give the explicit file names of any
- library built by your package. Doing so will ensure that
- ‘maude_DEPENDENCIES’ (see below) is correctly defined by default.
- ‘maude_LDFLAGS’
- This variable is used to pass extra flags to the link step of a
- program or a shared library. It overrides the ‘AM_LDFLAGS’
- variable.
- ‘maude_LIBTOOLFLAGS’
- This variable is used to pass extra options to ‘libtool’. It
- overrides the ‘AM_LIBTOOLFLAGS’ variable. These options are output
- before ‘libtool’’s ‘--mode=MODE’ option, so they should not be
- mode-specific options (those belong to the compiler or linker
- flags). *Note Libtool Flags::.
- ‘maude_DEPENDENCIES’
- ‘EXTRA_maude_DEPENDENCIES’
- It is also occasionally useful to have a target (program or
- library) depend on some other file that is not actually part of
- that target. This can be done using the ‘_DEPENDENCIES’ variable.
- Each target depends on the contents of such a variable, but no
- further interpretation is done.
- Since these dependencies are associated to the link rule used to
- create the programs they should normally list files used by the
- link command. That is ‘*.$(OBJEXT)’, ‘*.a’, or ‘*.la’ files for
- programs; ‘*.lo’ and ‘*.la’ files for Libtool libraries; and
- ‘*.$(OBJEXT)’ files for static libraries. In rare cases you may
- need to add other kinds of files such as linker scripts, but
- _listing a source file in ‘_DEPENDENCIES’ is wrong_. If some
- source file needs to be built before all the components of a
- program are built, consider using the ‘BUILT_SOURCES’ variable
- (*note Sources::).
- If ‘_DEPENDENCIES’ is not supplied, it is computed by Automake.
- The automatically-assigned value is the contents of ‘_LDADD’ or
- ‘_LIBADD’, with most configure substitutions, ‘-l’, ‘-L’, ‘-dlopen’
- and ‘-dlpreopen’ options removed. The configure substitutions that
- are left in are only ‘$(LIBOBJS)’ and ‘$(ALLOCA)’; these are left
- because it is known that they will not cause an invalid value for
- ‘_DEPENDENCIES’ to be generated.
- ‘_DEPENDENCIES’ is more likely used to perform conditional
- compilation using an ‘AC_SUBST’ variable that contains a list of
- objects. *Note Conditional Sources::, and *note Conditional
- Libtool Sources::.
- The ‘EXTRA_*_DEPENDENCIES’ variable may be useful for cases where
- you merely want to augment the ‘automake’-generated ‘_DEPENDENCIES’
- variable rather than replacing it.
- ‘maude_LINK’
- You can override the linker on a per-program basis. By default the
- linker is chosen according to the languages used by the program.
- For instance, a program that includes C++ source code would use the
- C++ compiler to link. The ‘_LINK’ variable must hold the name of a
- command that can be passed all the ‘.o’ file names and libraries to
- link against as arguments. Note that the name of the underlying
- program is _not_ passed to ‘_LINK’; typically one uses ‘$@’:
- maude_LINK = $(CCLD) -magic -o $@
- If a ‘_LINK’ variable is not supplied, it may still be generated
- and used by Automake due to the use of per-target link flags such
- as ‘_CFLAGS’, ‘_LDFLAGS’ or ‘_LIBTOOLFLAGS’, in cases where they
- apply.
- ‘maude_CCASFLAGS’
- ‘maude_CFLAGS’
- ‘maude_CPPFLAGS’
- ‘maude_CXXFLAGS’
- ‘maude_FFLAGS’
- ‘maude_GCJFLAGS’
- ‘maude_LFLAGS’
- ‘maude_OBJCFLAGS’
- ‘maude_OBJCXXFLAGS’
- ‘maude_RFLAGS’
- ‘maude_UPCFLAGS’
- ‘maude_YFLAGS’
- Automake allows you to set compilation flags on a per-program (or
- per-library) basis. A single source file can be included in
- several programs, and it will potentially be compiled with
- different flags for each program. This works for any language
- directly supported by Automake. These “per-target compilation
- flags” are ‘_CCASFLAGS’, ‘_CFLAGS’, ‘_CPPFLAGS’, ‘_CXXFLAGS’,
- ‘_FFLAGS’, ‘_GCJFLAGS’, ‘_LFLAGS’, ‘_OBJCFLAGS’, ‘_OBJCXXFLAGS’,
- ‘_RFLAGS’, ‘_UPCFLAGS’, and ‘_YFLAGS’.
- When using a per-target compilation flag, Automake will choose a
- different name for the intermediate object files. Ordinarily a
- file like ‘sample.c’ will be compiled to produce ‘sample.o’.
- However, if the program’s ‘_CFLAGS’ variable is set, then the
- object file will be named, for instance, ‘maude-sample.o’. (See
- also *note Renamed Objects::).
- In compilations with per-target flags, the ordinary ‘AM_’ form of
- the flags variable is _not_ automatically included in the
- compilation (however, the user form of the variable _is_ included).
- So for instance, if you want the hypothetical ‘maude’ compilations
- to also use the value of ‘AM_CFLAGS’, you would need to write:
- maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
- *Note Flag Variables Ordering::, for more discussion about the
- interaction between user variables, ‘AM_’ shadow variables, and
- per-target variables.
- ‘maude_SHORTNAME’
- On some platforms the allowable file names are very short. In
- order to support these systems and per-target compilation flags at
- the same time, Automake allows you to set a “short name” that will
- influence how intermediate object files are named. For instance,
- in the following example,
- bin_PROGRAMS = maude
- maude_CPPFLAGS = -DSOMEFLAG
- maude_SHORTNAME = m
- maude_SOURCES = sample.c ...
- the object file would be named ‘m-sample.o’ rather than
- ‘maude-sample.o’.
- This facility is rarely needed in practice, and we recommend
- avoiding it until you find it is required.
- ---------- Footnotes ----------
- (1) There are other, more obscure reasons for this limitation as
- well.
- File: automake.info, Node: Default _SOURCES, Next: LIBOBJS, Prev: Program and Library Variables, Up: Programs
- 8.5 Default ‘_SOURCES’
- ======================
- ‘_SOURCES’ variables are used to specify source files of programs (*note
- A Program::), libraries (*note A Library::), and Libtool libraries
- (*note A Shared Library::).
- When no such variable is specified for a target, Automake will define
- one itself. The default is to compile a single C file whose base name
- is the name of the target itself, with any extension replaced by
- ‘AM_DEFAULT_SOURCE_EXT’, which defaults to ‘.c’.
- For example if you have the following somewhere in your ‘Makefile.am’
- with no corresponding ‘libfoo_a_SOURCES’:
- lib_LIBRARIES = libfoo.a sub/libc++.a
- ‘libfoo.a’ will be built using a default source file named ‘libfoo.c’,
- and ‘sub/libc++.a’ will be built from ‘sub/libc++.c’. (In older
- versions ‘sub/libc++.a’ would be built from ‘sub_libc___a.c’, i.e., the
- default source was the canonized name of the target, with ‘.c’ appended.
- We believe the new behavior is more sensible, but for backward
- compatibility ‘automake’ will use the old name if a file or a rule with
- that name exists and ‘AM_DEFAULT_SOURCE_EXT’ is not used.)
- Default sources are mainly useful in test suites, when building many
- test programs each from a single source. For instance, in
- check_PROGRAMS = test1 test2 test3
- AM_DEFAULT_SOURCE_EXT = .cpp
- ‘test1’, ‘test2’, and ‘test3’ will be built from ‘test1.cpp’,
- ‘test2.cpp’, and ‘test3.cpp’. Without the last line, they will be built
- from ‘test1.c’, ‘test2.c’, and ‘test3.c’.
- Another case where this is convenient is building many Libtool
- modules (‘moduleN.la’), each defined in its own file (‘moduleN.c’).
- AM_LDFLAGS = -module
- lib_LTLIBRARIES = module1.la module2.la module3.la
- Finally, there is one situation where this default source computation
- needs to be avoided: when a target should not be built from sources. We
- already saw such an example in *note true::; this happens when all the
- constituents of a target have already been compiled and just need to be
- combined using a ‘_LDADD’ variable. Then it is necessary to define an
- empty ‘_SOURCES’ variable, so that ‘automake’ does not compute a
- default.
- bin_PROGRAMS = target
- target_SOURCES =
- target_LDADD = libmain.a libmisc.a
- File: automake.info, Node: LIBOBJS, Next: Program Variables, Prev: Default _SOURCES, Up: Programs
- 8.6 Special handling for ‘LIBOBJS’ and ‘ALLOCA’
- ===============================================
- The ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables list object files that should
- be compiled into the project to provide an implementation for functions
- that are missing or broken on the host system. They are substituted by
- ‘configure’.
- These variables are defined by Autoconf macros such as ‘AC_LIBOBJ’,
- ‘AC_REPLACE_FUNCS’ (*note Generic Function Checks: (autoconf)Generic
- Functions.), or ‘AC_FUNC_ALLOCA’ (*note Particular Function Checks:
- (autoconf)Particular Functions.). Many other Autoconf macros call
- ‘AC_LIBOBJ’ or ‘AC_REPLACE_FUNCS’ to populate ‘$(LIBOBJS)’.
- Using these variables is very similar to doing conditional
- compilation using ‘AC_SUBST’ variables, as described in *note
- Conditional Sources::. That is, when building a program, ‘$(LIBOBJS)’
- and ‘$(ALLOCA)’ should be added to the associated ‘*_LDADD’ variable, or
- to the ‘*_LIBADD’ variable when building a library. However there is no
- need to list the corresponding sources in ‘EXTRA_*_SOURCES’ nor to
- define ‘*_DEPENDENCIES’. Automake automatically adds ‘$(LIBOBJS)’ and
- ‘$(ALLOCA)’ to the dependencies, and it will discover the list of
- corresponding source files automatically (by tracing the invocations of
- the ‘AC_LIBSOURCE’ Autoconf macros). If you have already defined
- ‘*_DEPENDENCIES’ explicitly for an unrelated reason, then you either
- need to add these variables manually, or use ‘EXTRA_*_DEPENDENCIES’
- instead of ‘*_DEPENDENCIES’.
- These variables are usually used to build a portability library that
- is linked with all the programs of the project. We now review a sample
- setup. First, ‘configure.ac’ contains some checks that affect either
- ‘LIBOBJS’ or ‘ALLOCA’.
- # configure.ac
- ...
- AC_CONFIG_LIBOBJ_DIR([lib])
- ...
- AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
- AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
- AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
- AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
- ...
- AC_CONFIG_FILES([
- lib/Makefile
- src/Makefile
- ])
- AC_OUTPUT
- The ‘AC_CONFIG_LIBOBJ_DIR’ tells Autoconf that the source files of
- these object files are to be found in the ‘lib/’ directory. Automake
- can also use this information, otherwise it expects the source files are
- to be in the directory where the ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables
- are used.
- The ‘lib/’ directory should therefore contain ‘malloc.c’, ‘memcmp.c’,
- ‘strdup.c’, ‘alloca.c’. Here is its ‘Makefile.am’:
- # lib/Makefile.am
- noinst_LIBRARIES = libcompat.a
- libcompat_a_SOURCES =
- libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
- The library can have any name, of course, and anyway it is not going
- to be installed: it just holds the replacement versions of the missing
- or broken functions so we can later link them in. Many projects also
- include extra functions, specific to the project, in that library: they
- are simply added on the ‘_SOURCES’ line.
- There is a small trap here, though: ‘$(LIBOBJS)’ and ‘$(ALLOCA)’
- might be empty, and building an empty library is not portable. You
- should ensure that there is always something to put in ‘libcompat.a’.
- Most projects will also add some utility functions in that directory,
- and list them in ‘libcompat_a_SOURCES’, so in practice ‘libcompat.a’
- cannot be empty.
- Finally here is how this library could be used from the ‘src/’
- directory.
- # src/Makefile.am
- # Link all programs in this directory with libcompat.a
- LDADD = ../lib/libcompat.a
- bin_PROGRAMS = tool1 tool2 ...
- tool1_SOURCES = ...
- tool2_SOURCES = ...
- When option ‘subdir-objects’ is not used, as in the above example,
- the variables ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ can only be used in the
- directory where their sources lie. E.g., here it would be wrong to use
- ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ in ‘src/Makefile.am’. However if both
- ‘subdir-objects’ and ‘AC_CONFIG_LIBOBJ_DIR’ are used, it is OK to use
- these variables in other directories. For instance ‘src/Makefile.am’
- could be changed as follows.
- # src/Makefile.am
- AUTOMAKE_OPTIONS = subdir-objects
- LDADD = $(LIBOBJS) $(ALLOCA)
- bin_PROGRAMS = tool1 tool2 ...
- tool1_SOURCES = ...
- tool2_SOURCES = ...
- Because ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ contain object file names that
- end with ‘.$(OBJEXT)’, they are not suitable for Libtool libraries
- (where the expected object extension is ‘.lo’): ‘LTLIBOBJS’ and
- ‘LTALLOCA’ should be used instead.
- ‘LTLIBOBJS’ is defined automatically by Autoconf and should not be
- defined by hand (as in the past), however at the time of writing
- ‘LTALLOCA’ still needs to be defined from ‘ALLOCA’ manually. *Note
- ‘AC_LIBOBJ’ vs. ‘LIBOBJS’: (autoconf)AC_LIBOBJ vs LIBOBJS.
- File: automake.info, Node: Program Variables, Next: Yacc and Lex, Prev: LIBOBJS, Up: Programs
- 8.7 Variables used when building a program
- ==========================================
- Occasionally it is useful to know which ‘Makefile’ variables Automake
- uses for compilations, and in which order (*note Flag Variables
- Ordering::); for instance, you might need to do your own compilation in
- some special cases.
- Some variables are inherited from Autoconf; these are ‘CC’, ‘CFLAGS’,
- ‘CPPFLAGS’, ‘DEFS’, ‘LDFLAGS’, and ‘LIBS’.
- There are some additional variables that Automake defines on its own:
- ‘AM_CPPFLAGS’
- The contents of this variable are passed to every compilation that
- invokes the C preprocessor; it is a list of arguments to the
- preprocessor. For instance, ‘-I’ and ‘-D’ options should be listed
- here.
- Automake already provides some ‘-I’ options automatically, in a
- separate variable that is also passed to every compilation that
- invokes the C preprocessor. In particular it generates ‘-I.’,
- ‘-I$(srcdir)’, and a ‘-I’ pointing to the directory holding
- ‘config.h’ (if you’ve used ‘AC_CONFIG_HEADERS’). You can disable
- the default ‘-I’ options using the ‘nostdinc’ option.
- When a file to be included is generated during the build and not
- part of a distribution tarball, its location is under
- ‘$(builddir)’, not under ‘$(srcdir)’. This matters especially for
- packages that use header files placed in sub-directories and want
- to allow builds outside the source tree (*note VPATH Builds::). In
- that case we recommend to use a pair of ‘-I’ options, such as,
- e.g., ‘-Isome/subdir -I$(srcdir)/some/subdir’ or
- ‘-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir’. Note
- that the reference to the build tree should come before the
- reference to the source tree, so that accidentally leftover
- generated files in the source directory are ignored.
- ‘AM_CPPFLAGS’ is ignored in preference to a per-executable (or
- per-library) ‘_CPPFLAGS’ variable if it is defined.
- ‘INCLUDES’
- This does the same job as ‘AM_CPPFLAGS’ (or any per-target
- ‘_CPPFLAGS’ variable if it is used). It is an older name for the
- same functionality. This variable is deprecated; we suggest using
- ‘AM_CPPFLAGS’ and per-target ‘_CPPFLAGS’ instead.
- ‘AM_CFLAGS’
- This is the variable the ‘Makefile.am’ author can use to pass in
- additional C compiler flags. In some situations, this is not used,
- in preference to the per-executable (or per-library) ‘_CFLAGS’.
- ‘COMPILE’
- This is the command used to actually compile a C source file. The
- file name is appended to form the complete command line.
- ‘AM_LDFLAGS’
- This is the variable the ‘Makefile.am’ author can use to pass in
- additional linker flags. In some situations, this is not used, in
- preference to the per-executable (or per-library) ‘_LDFLAGS’.
- ‘LINK’
- This is the command used to actually link a C program. It already
- includes ‘-o $@’ and the usual variable references (for instance,
- ‘CFLAGS’); it takes as “arguments” the names of the object files
- and libraries to link in. This variable is not used when the
- linker is overridden with a per-target ‘_LINK’ variable or
- per-target flags cause Automake to define such a ‘_LINK’ variable.
- File: automake.info, Node: Yacc and Lex, Next: C++ Support, Prev: Program Variables, Up: Programs
- 8.8 Yacc and Lex support
- ========================
- Automake has somewhat idiosyncratic support for Yacc and Lex.
- Automake assumes that the ‘.c’ file generated by ‘yacc’ (or ‘lex’)
- should be named using the basename of the input file. That is, for a
- yacc source file ‘foo.y’, Automake will cause the intermediate file to
- be named ‘foo.c’ (as opposed to ‘y.tab.c’, which is more traditional).
- The extension of a yacc source file is used to determine the
- extension of the resulting C or C++ source and header files. Note that
- header files are generated only when the ‘-d’ Yacc option is used; see
- below for more information about this flag, and how to specify it.
- Files with the extension ‘.y’ will thus be turned into ‘.c’ sources and
- ‘.h’ headers; likewise, ‘.yy’ will become ‘.cc’ and ‘.hh’, ‘.y++’ will
- become ‘c++’ and ‘h++’, ‘.yxx’ will become ‘.cxx’ and ‘.hxx’, and ‘.ypp’
- will become ‘.cpp’ and ‘.hpp’.
- Similarly, lex source files can be used to generate C or C++; the
- extensions ‘.l’, ‘.ll’, ‘.l++’, ‘.lxx’, and ‘.lpp’ are recognized.
- You should never explicitly mention the intermediate (C or C++) file
- in any ‘SOURCES’ variable; only list the source file.
- The intermediate files generated by ‘yacc’ (or ‘lex’) will be
- included in any distribution that is made. That way the user doesn’t
- need to have ‘yacc’ or ‘lex’.
- If a ‘yacc’ source file is seen, then your ‘configure.ac’ must define
- the variable ‘YACC’. This is most easily done by invoking the macro
- ‘AC_PROG_YACC’ (*note Particular Program Checks: (autoconf)Particular
- Programs.).
- When ‘yacc’ is invoked, it is passed ‘AM_YFLAGS’ and ‘YFLAGS’. The
- latter is a user variable and the former is intended for the
- ‘Makefile.am’ author.
- ‘AM_YFLAGS’ is usually used to pass the ‘-d’ option to ‘yacc’.
- Automake knows what this means and will automatically adjust its rules
- to update and distribute the header file built by ‘yacc -d’(1). What
- Automake cannot guess, though, is where this header will be used: it is
- up to you to ensure the header gets built before it is first used.
- Typically this is necessary in order for dependency tracking to work
- when the header is included by another file. The common solution is
- listing the header file in ‘BUILT_SOURCES’ (*note Sources::) as follows.
- BUILT_SOURCES = parser.h
- AM_YFLAGS = -d
- bin_PROGRAMS = foo
- foo_SOURCES = ... parser.y ...
- If a ‘lex’ source file is seen, then your ‘configure.ac’ must define
- the variable ‘LEX’. You can use ‘AC_PROG_LEX’ to do this (*note
- Particular Program Checks: (autoconf)Particular Programs.), but using
- ‘AM_PROG_LEX’ macro (*note Macros::) is recommended.
- When ‘lex’ is invoked, it is passed ‘AM_LFLAGS’ and ‘LFLAGS’. The
- latter is a user variable and the former is intended for the
- ‘Makefile.am’ author.
- When ‘AM_MAINTAINER_MODE’ (*note maintainer-mode::) is used, the
- rebuild rule for distributed Yacc and Lex sources are only used when
- ‘maintainer-mode’ is enabled, or when the files have been erased.
- When ‘lex’ or ‘yacc’ sources are used, ‘automake -a’ automatically
- installs an auxiliary program called ‘ylwrap’ in your package (*note
- Auxiliary Programs::). This program is used by the build rules to
- rename the output of these tools, and makes it possible to include
- multiple ‘yacc’ (or ‘lex’) source files in a single directory. (This is
- necessary because yacc’s output file name is fixed, and a parallel make
- could conceivably invoke more than one instance of ‘yacc’
- simultaneously.)
- For ‘yacc’, simply managing locking is insufficient. The output of
- ‘yacc’ always uses the same symbol names internally, so it isn’t
- possible to link two ‘yacc’ parsers into the same executable.
- We recommend using the following renaming hack used in ‘gdb’:
- #define yymaxdepth c_maxdepth
- #define yyparse c_parse
- #define yylex c_lex
- #define yyerror c_error
- #define yylval c_lval
- #define yychar c_char
- #define yydebug c_debug
- #define yypact c_pact
- #define yyr1 c_r1
- #define yyr2 c_r2
- #define yydef c_def
- #define yychk c_chk
- #define yypgo c_pgo
- #define yyact c_act
- #define yyexca c_exca
- #define yyerrflag c_errflag
- #define yynerrs c_nerrs
- #define yyps c_ps
- #define yypv c_pv
- #define yys c_s
- #define yy_yys c_yys
- #define yystate c_state
- #define yytmp c_tmp
- #define yyv c_v
- #define yy_yyv c_yyv
- #define yyval c_val
- #define yylloc c_lloc
- #define yyreds c_reds
- #define yytoks c_toks
- #define yylhs c_yylhs
- #define yylen c_yylen
- #define yydefred c_yydefred
- #define yydgoto c_yydgoto
- #define yysindex c_yysindex
- #define yyrindex c_yyrindex
- #define yygindex c_yygindex
- #define yytable c_yytable
- #define yycheck c_yycheck
- #define yyname c_yyname
- #define yyrule c_yyrule
- For each define, replace the ‘c_’ prefix with whatever you like.
- These defines work for ‘bison’, ‘byacc’, and traditional ‘yacc’s. If
- you find a parser generator that uses a symbol not covered here, please
- report the new name so it can be added to the list.
- ---------- Footnotes ----------
- (1) Please note that ‘automake’ recognizes ‘-d’ in ‘AM_YFLAGS’ only
- if it is not clustered with other options; for example, it won’t be
- recognized if ‘AM_YFLAGS’ is ‘-dt’, but it will be if ‘AM_YFLAGS’ is ‘-d
- -t’ or ‘-t -d’.
- File: automake.info, Node: C++ Support, Next: Objective C Support, Prev: Yacc and Lex, Up: Programs
- 8.9 C++ Support
- ===============
- Automake includes full support for C++.
- Any package including C++ code must define the output variable ‘CXX’
- in ‘configure.ac’; the simplest way to do this is to use the
- ‘AC_PROG_CXX’ macro (*note Particular Program Checks:
- (autoconf)Particular Programs.).
- A few additional variables are defined when a C++ source file is
- seen:
- ‘CXX’
- The name of the C++ compiler.
- ‘CXXFLAGS’
- Any flags to pass to the C++ compiler.
- ‘AM_CXXFLAGS’
- The maintainer’s variant of ‘CXXFLAGS’.
- ‘CXXCOMPILE’
- The command used to actually compile a C++ source file. The file
- name is appended to form the complete command line.
- ‘CXXLINK’
- The command used to actually link a C++ program.
- File: automake.info, Node: Objective C Support, Next: Objective C++ Support, Prev: C++ Support, Up: Programs
- 8.10 Objective C Support
- ========================
- Automake includes some support for Objective C.
- Any package including Objective C code must define the output
- variable ‘OBJC’ in ‘configure.ac’; the simplest way to do this is to use
- the ‘AC_PROG_OBJC’ macro (*note Particular Program Checks:
- (autoconf)Particular Programs.).
- A few additional variables are defined when an Objective C source
- file is seen:
- ‘OBJC’
- The name of the Objective C compiler.
- ‘OBJCFLAGS’
- Any flags to pass to the Objective C compiler.
- ‘AM_OBJCFLAGS’
- The maintainer’s variant of ‘OBJCFLAGS’.
- ‘OBJCCOMPILE’
- The command used to actually compile an Objective C source file.
- The file name is appended to form the complete command line.
- ‘OBJCLINK’
- The command used to actually link an Objective C program.
- File: automake.info, Node: Objective C++ Support, Next: Unified Parallel C Support, Prev: Objective C Support, Up: Programs
- 8.11 Objective C++ Support
- ==========================
- Automake includes some support for Objective C++.
- Any package including Objective C++ code must define the output
- variable ‘OBJCXX’ in ‘configure.ac’; the simplest way to do this is to
- use the ‘AC_PROG_OBJCXX’ macro (*note Particular Program Checks:
- (autoconf)Particular Programs.).
- A few additional variables are defined when an Objective C++ source
- file is seen:
- ‘OBJCXX’
- The name of the Objective C++ compiler.
- ‘OBJCXXFLAGS’
- Any flags to pass to the Objective C++ compiler.
- ‘AM_OBJCXXFLAGS’
- The maintainer’s variant of ‘OBJCXXFLAGS’.
- ‘OBJCXXCOMPILE’
- The command used to actually compile an Objective C++ source file.
- The file name is appended to form the complete command line.
- ‘OBJCXXLINK’
- The command used to actually link an Objective C++ program.
- File: automake.info, Node: Unified Parallel C Support, Next: Assembly Support, Prev: Objective C++ Support, Up: Programs
- 8.12 Unified Parallel C Support
- ===============================
- Automake includes some support for Unified Parallel C.
- Any package including Unified Parallel C code must define the output
- variable ‘UPC’ in ‘configure.ac’; the simplest way to do this is to use
- the ‘AM_PROG_UPC’ macro (*note Public Macros::).
- A few additional variables are defined when a Unified Parallel C
- source file is seen:
- ‘UPC’
- The name of the Unified Parallel C compiler.
- ‘UPCFLAGS’
- Any flags to pass to the Unified Parallel C compiler.
- ‘AM_UPCFLAGS’
- The maintainer’s variant of ‘UPCFLAGS’.
- ‘UPCCOMPILE’
- The command used to actually compile a Unified Parallel C source
- file. The file name is appended to form the complete command line.
- ‘UPCLINK’
- The command used to actually link a Unified Parallel C program.
- File: automake.info, Node: Assembly Support, Next: Fortran 77 Support, Prev: Unified Parallel C Support, Up: Programs
- 8.13 Assembly Support
- =====================
- Automake includes some support for assembly code. There are two forms
- of assembler files: normal (‘*.s’) and preprocessed by ‘CPP’ (‘*.S’ or
- ‘*.sx’).
- The variable ‘CCAS’ holds the name of the compiler used to build
- assembly code. This compiler must work a bit like a C compiler; in
- particular it must accept ‘-c’ and ‘-o’. The values of ‘CCASFLAGS’ and
- ‘AM_CCASFLAGS’ (or its per-target definition) is passed to the
- compilation. For preprocessed files, ‘DEFS’, ‘DEFAULT_INCLUDES’,
- ‘INCLUDES’, ‘CPPFLAGS’ and ‘AM_CPPFLAGS’ are also used.
- The autoconf macro ‘AM_PROG_AS’ will define ‘CCAS’ and ‘CCASFLAGS’
- for you (unless they are already set, it simply sets ‘CCAS’ to the C
- compiler and ‘CCASFLAGS’ to the C compiler flags), but you are free to
- define these variables by other means.
- Only the suffixes ‘.s’, ‘.S’, and ‘.sx’ are recognized by ‘automake’
- as being files containing assembly code.
- File: automake.info, Node: Fortran 77 Support, Next: Fortran 9x Support, Prev: Assembly Support, Up: Programs
- 8.14 Fortran 77 Support
- =======================
- Automake includes full support for Fortran 77.
- Any package including Fortran 77 code must define the output variable
- ‘F77’ in ‘configure.ac’; the simplest way to do this is to use the
- ‘AC_PROG_F77’ macro (*note Particular Program Checks:
- (autoconf)Particular Programs.).
- A few additional variables are defined when a Fortran 77 source file
- is seen:
- ‘F77’
- The name of the Fortran 77 compiler.
- ‘FFLAGS’
- Any flags to pass to the Fortran 77 compiler.
- ‘AM_FFLAGS’
- The maintainer’s variant of ‘FFLAGS’.
- ‘RFLAGS’
- Any flags to pass to the Ratfor compiler.
- ‘AM_RFLAGS’
- The maintainer’s variant of ‘RFLAGS’.
- ‘F77COMPILE’
- The command used to actually compile a Fortran 77 source file. The
- file name is appended to form the complete command line.
- ‘FLINK’
- The command used to actually link a pure Fortran 77 program or
- shared library.
- Automake can handle preprocessing Fortran 77 and Ratfor source files
- in addition to compiling them(1). Automake also contains some support
- for creating programs and shared libraries that are a mixture of Fortran
- 77 and other languages (*note Mixing Fortran 77 With C and C++::).
- These issues are covered in the following sections.
- * Menu:
- * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
- * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
- * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
- ---------- Footnotes ----------
- (1) Much, if not most, of the information in the following sections
- pertaining to preprocessing Fortran 77 programs was taken almost
- verbatim from *note Catalogue of Rules: (make)Catalogue of Rules.
- File: automake.info, Node: Preprocessing Fortran 77, Next: Compiling Fortran 77 Files, Up: Fortran 77 Support
- 8.14.1 Preprocessing Fortran 77
- -------------------------------
- ‘N.f’ is made automatically from ‘N.F’ or ‘N.r’. This rule runs just
- the preprocessor to convert a preprocessable Fortran 77 or Ratfor source
- file into a strict Fortran 77 source file. The precise command used is
- as follows:
- ‘.F’
- ‘$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
- $(AM_FFLAGS) $(FFLAGS)’
- ‘.r’
- ‘$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)’
- File: automake.info, Node: Compiling Fortran 77 Files, Next: Mixing Fortran 77 With C and C++, Prev: Preprocessing Fortran 77, Up: Fortran 77 Support
- 8.14.2 Compiling Fortran 77 Files
- ---------------------------------
- ‘N.o’ is made automatically from ‘N.f’, ‘N.F’ or ‘N.r’ by running the
- Fortran 77 compiler. The precise command used is as follows:
- ‘.f’
- ‘$(F77) -c $(AM_FFLAGS) $(FFLAGS)’
- ‘.F’
- ‘$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
- $(AM_FFLAGS) $(FFLAGS)’
- ‘.r’
- ‘$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)’
- File: automake.info, Node: Mixing Fortran 77 With C and C++, Prev: Compiling Fortran 77 Files, Up: Fortran 77 Support
- 8.14.3 Mixing Fortran 77 With C and C++
- ---------------------------------------
- Automake currently provides _limited_ support for creating programs and
- shared libraries that are a mixture of Fortran 77 and C and/or C++.
- However, there are many other issues related to mixing Fortran 77 with
- other languages that are _not_ (currently) handled by Automake, but that
- are handled by other packages(1).
- Automake can help in two ways:
- 1. Automatic selection of the linker depending on which combinations
- of source code.
- 2. Automatic selection of the appropriate linker flags (e.g., ‘-L’ and
- ‘-l’) to pass to the automatically selected linker in order to link
- in the appropriate Fortran 77 intrinsic and run-time libraries.
- These extra Fortran 77 linker flags are supplied in the output
- variable ‘FLIBS’ by the ‘AC_F77_LIBRARY_LDFLAGS’ Autoconf macro.
- *Note Fortran Compiler Characteristics: (autoconf)Fortran Compiler.
- If Automake detects that a program or shared library (as mentioned in
- some ‘_PROGRAMS’ or ‘_LTLIBRARIES’ primary) contains source code that is
- a mixture of Fortran 77 and C and/or C++, then it requires that the
- macro ‘AC_F77_LIBRARY_LDFLAGS’ be called in ‘configure.ac’, and that
- either ‘$(FLIBS)’ appear in the appropriate ‘_LDADD’ (for programs) or
- ‘_LIBADD’ (for shared libraries) variables. It is the responsibility of
- the person writing the ‘Makefile.am’ to make sure that ‘$(FLIBS)’
- appears in the appropriate ‘_LDADD’ or ‘_LIBADD’ variable.
- For example, consider the following ‘Makefile.am’:
- bin_PROGRAMS = foo
- foo_SOURCES = main.cc foo.f
- foo_LDADD = libfoo.la $(FLIBS)
- pkglib_LTLIBRARIES = libfoo.la
- libfoo_la_SOURCES = bar.f baz.c zardoz.cc
- libfoo_la_LIBADD = $(FLIBS)
- In this case, Automake will insist that ‘AC_F77_LIBRARY_LDFLAGS’ is
- mentioned in ‘configure.ac’. Also, if ‘$(FLIBS)’ hadn’t been mentioned
- in ‘foo_LDADD’ and ‘libfoo_la_LIBADD’, then Automake would have issued a
- warning.
- * Menu:
- * How the Linker is Chosen:: Automatic linker selection
- ---------- Footnotes ----------
- (1) For example, the cfortran package
- (http://www-zeus.desy.de/~burow/cfortran/) addresses all of these
- inter-language issues, and runs under nearly all Fortran 77, C and C++
- compilers on nearly all platforms. However, ‘cfortran’ is not yet Free
- Software, but it will be in the next major release.
- File: automake.info, Node: How the Linker is Chosen, Up: Mixing Fortran 77 With C and C++
- 8.14.3.1 How the Linker is Chosen
- .................................
- When a program or library mixes several languages, Automake choose the
- linker according to the following priorities. (The names in parentheses
- are the variables containing the link command.)
- 1. Native Java (‘GCJLINK’)
- 2. Objective C++ (‘OBJCXXLINK’)
- 3. C++ (‘CXXLINK’)
- 4. Fortran 77 (‘F77LINK’)
- 5. Fortran (‘FCLINK’)
- 6. Objective C (‘OBJCLINK’)
- 7. Unified Parallel C (‘UPCLINK’)
- 8. C (‘LINK’)
- For example, if Fortran 77, C and C++ source code is compiled into a
- program, then the C++ linker will be used. In this case, if the C or
- Fortran 77 linkers required any special libraries that weren’t included
- by the C++ linker, then they must be manually added to an ‘_LDADD’ or
- ‘_LIBADD’ variable by the user writing the ‘Makefile.am’.
- Automake only looks at the file names listed in ‘_SOURCES’ variables
- to choose the linker, and defaults to the C linker. Sometimes this is
- inconvenient because you are linking against a library written in
- another language and would like to set the linker more appropriately.
- *Note Libtool Convenience Libraries::, for a trick with
- ‘nodist_EXTRA_..._SOURCES’.
- A per-target ‘_LINK’ variable will override the above selection.
- Per-target link flags will cause Automake to write a per-target ‘_LINK’
- variable according to the language chosen as above.
- File: automake.info, Node: Fortran 9x Support, Next: Java Support with gcj, Prev: Fortran 77 Support, Up: Programs
- 8.15 Fortran 9x Support
- =======================
- Automake includes support for Fortran 9x.
- Any package including Fortran 9x code must define the output variable
- ‘FC’ in ‘configure.ac’; the simplest way to do this is to use the
- ‘AC_PROG_FC’ macro (*note Particular Program Checks:
- (autoconf)Particular Programs.).
- A few additional variables are defined when a Fortran 9x source file
- is seen:
- ‘FC’
- The name of the Fortran 9x compiler.
- ‘FCFLAGS’
- Any flags to pass to the Fortran 9x compiler.
- ‘AM_FCFLAGS’
- The maintainer’s variant of ‘FCFLAGS’.
- ‘FCCOMPILE’
- The command used to actually compile a Fortran 9x source file. The
- file name is appended to form the complete command line.
- ‘FCLINK’
- The command used to actually link a pure Fortran 9x program or
- shared library.
- * Menu:
- * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
- File: automake.info, Node: Compiling Fortran 9x Files, Up: Fortran 9x Support
- 8.15.1 Compiling Fortran 9x Files
- ---------------------------------
- ‘FILE.o’ is made automatically from ‘FILE.f90’, ‘FILE.f95’, ‘FILE.f03’,
- or ‘FILE.f08’ by running the Fortran 9x compiler. The precise command
- used is as follows:
- ‘.f90’
- ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<’
- ‘.f95’
- ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<’
- ‘.f03’
- ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<’
- ‘.f08’
- ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<’
- File: automake.info, Node: Java Support with gcj, Next: Vala Support, Prev: Fortran 9x Support, Up: Programs
- 8.16 Compiling Java sources using gcj
- =====================================
- Automake includes support for natively compiled Java, using ‘gcj’, the
- Java front end to the GNU Compiler Collection (rudimentary support for
- compiling Java to bytecode using the ‘javac’ compiler is also present,
- _albeit deprecated_; *note Java::).
- Any package including Java code to be compiled must define the output
- variable ‘GCJ’ in ‘configure.ac’; the variable ‘GCJFLAGS’ must also be
- defined somehow (either in ‘configure.ac’ or ‘Makefile.am’). The
- simplest way to do this is to use the ‘AM_PROG_GCJ’ macro.
- By default, programs including Java source files are linked with
- ‘gcj’.
- As always, the contents of ‘AM_GCJFLAGS’ are passed to every
- compilation invoking ‘gcj’ (in its role as an ahead-of-time compiler,
- when invoking it to create ‘.class’ files, ‘AM_JAVACFLAGS’ is used
- instead). If it is necessary to pass options to ‘gcj’ from
- ‘Makefile.am’, this variable, and not the user variable ‘GCJFLAGS’,
- should be used.
- ‘gcj’ can be used to compile ‘.java’, ‘.class’, ‘.zip’, or ‘.jar’
- files.
- When linking, ‘gcj’ requires that the main class be specified using
- the ‘--main=’ option. The easiest way to do this is to use the
- ‘_LDFLAGS’ variable for the program.
- File: automake.info, Node: Vala Support, Next: Support for Other Languages, Prev: Java Support with gcj, Up: Programs
- 8.17 Vala Support
- =================
- Automake provides initial support for Vala
- (<http://www.vala-project.org/>). This requires valac version 0.7.0 or
- later, and currently requires the user to use GNU ‘make’.
- foo_SOURCES = foo.vala bar.vala zardoc.c
- Any ‘.vala’ file listed in a ‘_SOURCES’ variable will be compiled
- into C code by the Vala compiler. The generated ‘.c’ files are
- distributed. The end user does not need to have a Vala compiler
- installed.
- Automake ships with an Autoconf macro called ‘AM_PROG_VALAC’ that
- will locate the Vala compiler and optionally check its version number.
- -- Macro: AM_PROG_VALAC ([MINIMUM-VERSION], [ACTION-IF-FOUND],
- [ACTION-IF-NOT-FOUND]) Search for a Vala compiler in ‘PATH’. If it
- is found, the variable ‘VALAC’ is set to point to it (see below for
- more details). This macro takes three optional arguments. The
- first argument, if present, is the minimum version of the Vala
- compiler required to compile this package. If a compiler is found
- and satisfies MINIMUM-VERSION, then ACTION-IF-FOUND is run (this
- defaults to do nothing). Otherwise, ACTION-IF-NOT-FOUND is run.
- If ACTION-IF-NOT-FOUND is not specified, the default value is to
- print a warning in case no compiler is found, or if a too-old
- version of the compiler is found.
- There are a few variables that are used when compiling Vala sources:
- ‘VALAC’
- Absolute path to the Vala compiler, or simply ‘valac’ if no
- suitable compiler Vala could be found at configure runtime.
- ‘VALAFLAGS’
- Additional arguments for the Vala compiler.
- ‘AM_VALAFLAGS’
- The maintainer’s variant of ‘VALAFLAGS’.
- lib_LTLIBRARIES = libfoo.la
- libfoo_la_SOURCES = foo.vala
- Note that currently, you cannot use per-target ‘*_VALAFLAGS’ (*note
- Renamed Objects::) to produce different C files from one Vala source
- file.
- File: automake.info, Node: Support for Other Languages, Next: Dependencies, Prev: Vala Support, Up: Programs
- 8.18 Support for Other Languages
- ================================
- Automake currently only includes full support for C, C++ (*note C++
- Support::), Objective C (*note Objective C Support::), Objective C++
- (*note Objective C++ Support::), Fortran 77 (*note Fortran 77
- Support::), Fortran 9x (*note Fortran 9x Support::), and Java (*note
- Java Support with gcj::). There is only rudimentary support for other
- languages, support for which will be improved based on user demand.
- Some limited support for adding your own languages is available via
- the suffix rule handling (*note Suffixes::).
- File: automake.info, Node: Dependencies, Next: EXEEXT, Prev: Support for Other Languages, Up: Programs
- 8.19 Automatic dependency tracking
- ==================================
- As a developer it is often painful to continually update the
- ‘Makefile.am’ whenever the include-file dependencies change in a
- project. Automake supplies a way to automatically track dependency
- changes (*note Dependency Tracking::).
- Automake always uses complete dependencies for a compilation,
- including system headers. Automake’s model is that dependency
- computation should be a side effect of the build. To this end,
- dependencies are computed by running all compilations through a special
- wrapper program called ‘depcomp’. ‘depcomp’ understands how to coax
- many different C and C++ compilers into generating dependency
- information in the format it requires. ‘automake -a’ will install
- ‘depcomp’ into your source tree for you. If ‘depcomp’ can’t figure out
- how to properly invoke your compiler, dependency tracking will simply be
- disabled for your build.
- Experience with earlier versions of Automake (*note Dependency
- Tracking Evolution: (automake-history)Dependency Tracking Evolution.)
- taught us that it is not reliable to generate dependencies only on the
- maintainer’s system, as configurations vary too much. So instead
- Automake implements dependency tracking at build time.
- Automatic dependency tracking can be suppressed by putting
- ‘no-dependencies’ in the variable ‘AUTOMAKE_OPTIONS’, or passing
- ‘no-dependencies’ as an argument to ‘AM_INIT_AUTOMAKE’ (this should be
- the preferred way). Or, you can invoke ‘automake’ with the ‘-i’ option.
- Dependency tracking is enabled by default.
- The person building your package also can choose to disable
- dependency tracking by configuring with ‘--disable-dependency-tracking’.
- File: automake.info, Node: EXEEXT, Prev: Dependencies, Up: Programs
- 8.20 Support for executable extensions
- ======================================
- On some platforms, such as Windows, executables are expected to have an
- extension such as ‘.exe’. On these platforms, some compilers (GCC among
- them) will automatically generate ‘foo.exe’ when asked to generate
- ‘foo’.
- Automake provides mostly-transparent support for this. Unfortunately
- _mostly_ doesn’t yet mean _fully_. Until the English dictionary is
- revised, you will have to assist Automake if your package must support
- those platforms.
- One thing you must be aware of is that, internally, Automake rewrites
- something like this:
- bin_PROGRAMS = liver
- to this:
- bin_PROGRAMS = liver$(EXEEXT)
- The targets Automake generates are likewise given the ‘$(EXEEXT)’
- extension.
- The variables ‘TESTS’ and ‘XFAIL_TESTS’ (*note Simple Tests::) are
- also rewritten if they contain filenames that have been declared as
- programs in the same ‘Makefile’. (This is mostly useful when some
- programs from ‘check_PROGRAMS’ are listed in ‘TESTS’.)
- However, Automake cannot apply this rewriting to ‘configure’
- substitutions. This means that if you are conditionally building a
- program using such a substitution, then your ‘configure.ac’ must take
- care to add ‘$(EXEEXT)’ when constructing the output variable.
- Sometimes maintainers like to write an explicit link rule for their
- program. Without executable extension support, this is easy—you simply
- write a rule whose target is the name of the program. However, when
- executable extension support is enabled, you must instead add the
- ‘$(EXEEXT)’ suffix.
- This might be a nuisance for maintainers who know their package will
- never run on a platform that has executable extensions. For those
- maintainers, the ‘no-exeext’ option (*note Options::) will disable this
- feature. This works in a fairly ugly way; if ‘no-exeext’ is seen, then
- the presence of a rule for a target named ‘foo’ in ‘Makefile.am’ will
- override an ‘automake’-generated rule for ‘foo$(EXEEXT)’. Without the
- ‘no-exeext’ option, this use will give a diagnostic.
- File: automake.info, Node: Other Objects, Next: Other GNU Tools, Prev: Programs, Up: Top
- 9 Other Derived Objects
- ***********************
- Automake can handle derived objects that are not C programs. Sometimes
- the support for actually building such objects must be explicitly
- supplied, but Automake will still automatically handle installation and
- distribution.
- * Menu:
- * Scripts:: Executable scripts
- * Headers:: Header files
- * Data:: Architecture-independent data files
- * Sources:: Derived sources
- File: automake.info, Node: Scripts, Next: Headers, Up: Other Objects
- 9.1 Executable Scripts
- ======================
- It is possible to define and install programs that are scripts. Such
- programs are listed using the ‘SCRIPTS’ primary name. When the script
- is distributed in its final, installable form, the ‘Makefile’ usually
- looks as follows:
- # Install my_script in $(bindir) and distribute it.
- dist_bin_SCRIPTS = my_script
- Scripts are not distributed by default; as we have just seen, those
- that should be distributed can be specified using a ‘dist_’ prefix as
- with other primaries.
- Scripts can be installed in ‘bindir’, ‘sbindir’, ‘libexecdir’,
- ‘pkglibexecdir’, or ‘pkgdatadir’.
- Scripts that need not be installed can be listed in ‘noinst_SCRIPTS’,
- and among them, those which are needed only by ‘make check’ should go in
- ‘check_SCRIPTS’.
- When a script needs to be built, the ‘Makefile.am’ should include the
- appropriate rules. For instance the ‘automake’ program itself is a Perl
- script that is generated from ‘automake.in’. Here is how this is
- handled:
- bin_SCRIPTS = automake
- CLEANFILES = $(bin_SCRIPTS)
- EXTRA_DIST = automake.in
- do_subst = sed -e 's,[@]datadir[@],$(datadir),g' \
- -e 's,[@]PERL[@],$(PERL),g' \
- -e 's,[@]PACKAGE[@],$(PACKAGE),g' \
- -e 's,[@]VERSION[@],$(VERSION),g' \
- ...
- automake: automake.in Makefile
- $(do_subst) < $(srcdir)/automake.in > automake
- chmod +x automake
- Such scripts for which a build rule has been supplied need to be
- deleted explicitly using ‘CLEANFILES’ (*note Clean::), and their sources
- have to be distributed, usually with ‘EXTRA_DIST’ (*note Basics of
- Distribution::).
- Another common way to build scripts is to process them from
- ‘configure’ with ‘AC_CONFIG_FILES’. In this situation Automake knows
- which files should be cleaned and distributed, and what the rebuild
- rules should look like.
- For instance if ‘configure.ac’ contains
- AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
- to build ‘src/my_script’ from ‘src/my_script.in’, then a
- ‘src/Makefile.am’ to install this script in ‘$(bindir)’ can be as simple
- as
- bin_SCRIPTS = my_script
- CLEANFILES = $(bin_SCRIPTS)
- There is no need for ‘EXTRA_DIST’ or any build rule: Automake infers
- them from ‘AC_CONFIG_FILES’ (*note Requirements::). ‘CLEANFILES’ is
- still useful, because by default Automake will clean targets of
- ‘AC_CONFIG_FILES’ in ‘distclean’, not ‘clean’.
- Although this looks simpler, building scripts this way has one
- drawback: directory variables such as ‘$(datadir)’ are not fully
- expanded and may refer to other directory variables.
- File: automake.info, Node: Headers, Next: Data, Prev: Scripts, Up: Other Objects
- 9.2 Header files
- ================
- Header files that must be installed are specified by the ‘HEADERS’
- family of variables. Headers can be installed in ‘includedir’,
- ‘oldincludedir’, ‘pkgincludedir’ or any other directory you may have
- defined (*note Uniform::). For instance,
- include_HEADERS = foo.h bar/bar.h
- will install the two files as ‘$(includedir)/foo.h’ and
- ‘$(includedir)/bar.h’.
- The ‘nobase_’ prefix is also supported,
- nobase_include_HEADERS = foo.h bar/bar.h
- will install the two files as ‘$(includedir)/foo.h’ and
- ‘$(includedir)/bar/bar.h’ (*note Alternative::).
- Usually, only header files that accompany installed libraries need to
- be installed. Headers used by programs or convenience libraries are not
- installed. The ‘noinst_HEADERS’ variable can be used for such headers.
- However when the header actually belongs to a single convenience library
- or program, we recommend listing it in the program’s or library’s
- ‘_SOURCES’ variable (*note Program Sources::) instead of in
- ‘noinst_HEADERS’. This is clearer for the ‘Makefile.am’ reader.
- ‘noinst_HEADERS’ would be the right variable to use in a directory
- containing only headers and no associated library or program.
- All header files must be listed somewhere; in a ‘_SOURCES’ variable
- or in a ‘_HEADERS’ variable. Missing ones will not appear in the
- distribution.
- For header files that are built and must not be distributed, use the
- ‘nodist_’ prefix as in ‘nodist_include_HEADERS’ or
- ‘nodist_prog_SOURCES’. If these generated headers are needed during the
- build, you must also ensure they exist before they are used (*note
- Sources::).
- File: automake.info, Node: Data, Next: Sources, Prev: Headers, Up: Other Objects
- 9.3 Architecture-independent data files
- =======================================
- Automake supports the installation of miscellaneous data files using the
- ‘DATA’ family of variables.
- Such data can be installed in the directories ‘datadir’,
- ‘sysconfdir’, ‘sharedstatedir’, ‘localstatedir’, or ‘pkgdatadir’.
- By default, data files are _not_ included in a distribution. Of
- course, you can use the ‘dist_’ prefix to change this on a per-variable
- basis.
- Here is how Automake declares its auxiliary data files:
- dist_pkgdata_DATA = clean-kr.am clean.am ...
- File: automake.info, Node: Sources, Prev: Data, Up: Other Objects
- 9.4 Built Sources
- =================
- Because Automake’s automatic dependency tracking works as a side-effect
- of compilation (*note Dependencies::) there is a bootstrap issue: a
- target should not be compiled before its dependencies are made, but
- these dependencies are unknown until the target is first compiled.
- Ordinarily this is not a problem, because dependencies are
- distributed sources: they preexist and do not need to be built. Suppose
- that ‘foo.c’ includes ‘foo.h’. When it first compiles ‘foo.o’, ‘make’
- only knows that ‘foo.o’ depends on ‘foo.c’. As a side-effect of this
- compilation ‘depcomp’ records the ‘foo.h’ dependency so that following
- invocations of ‘make’ will honor it. In these conditions, it’s clear
- there is no problem: either ‘foo.o’ doesn’t exist and has to be built
- (regardless of the dependencies), or accurate dependencies exist and
- they can be used to decide whether ‘foo.o’ should be rebuilt.
- It’s a different story if ‘foo.h’ doesn’t exist by the first ‘make’
- run. For instance, there might be a rule to build ‘foo.h’. This time
- ‘file.o’’s build will fail because the compiler can’t find ‘foo.h’.
- ‘make’ failed to trigger the rule to build ‘foo.h’ first by lack of
- dependency information.
- The ‘BUILT_SOURCES’ variable is a workaround for this problem. A
- source file listed in ‘BUILT_SOURCES’ is made on ‘make all’ or ‘make
- check’ (or even ‘make install’) before other targets are processed.
- However, such a source file is not _compiled_ unless explicitly
- requested by mentioning it in some other ‘_SOURCES’ variable.
- So, to conclude our introductory example, we could use ‘BUILT_SOURCES
- = foo.h’ to ensure ‘foo.h’ gets built before any other target (including
- ‘foo.o’) during ‘make all’ or ‘make check’.
- ‘BUILT_SOURCES’ is actually a bit of a misnomer, as any file which
- must be created early in the build process can be listed in this
- variable. Moreover, all built sources do not necessarily have to be
- listed in ‘BUILT_SOURCES’. For instance, a generated ‘.c’ file doesn’t
- need to appear in ‘BUILT_SOURCES’ (unless it is included by another
- source), because it’s a known dependency of the associated object.
- It might be important to emphasize that ‘BUILT_SOURCES’ is honored
- only by ‘make all’, ‘make check’ and ‘make install’. This means you
- cannot build a specific target (e.g., ‘make foo’) in a clean tree if it
- depends on a built source. However it will succeed if you have run
- ‘make all’ earlier, because accurate dependencies are already available.
- The next section illustrates and discusses the handling of built
- sources on a toy example.
- * Menu:
- * Built Sources Example:: Several ways to handle built sources.
- File: automake.info, Node: Built Sources Example, Up: Sources
- 9.4.1 Built Sources Example
- ---------------------------
- Suppose that ‘foo.c’ includes ‘bindir.h’, which is
- installation-dependent and not distributed: it needs to be built. Here
- ‘bindir.h’ defines the preprocessor macro ‘bindir’ to the value of the
- ‘make’ variable ‘bindir’ (inherited from ‘configure’).
- We suggest several implementations below. It’s not meant to be an
- exhaustive listing of all ways to handle built sources, but it will give
- you a few ideas if you encounter this issue.
- First Try
- .........
- This first implementation will illustrate the bootstrap issue mentioned
- in the previous section (*note Sources::).
- Here is a tentative ‘Makefile.am’.
- # This won't work.
- bin_PROGRAMS = foo
- foo_SOURCES = foo.c
- nodist_foo_SOURCES = bindir.h
- CLEANFILES = bindir.h
- bindir.h: Makefile
- echo '#define bindir "$(bindir)"' >$@
- This setup doesn’t work, because Automake doesn’t know that ‘foo.c’
- includes ‘bindir.h’. Remember, automatic dependency tracking works as a
- side-effect of compilation, so the dependencies of ‘foo.o’ will be known
- only after ‘foo.o’ has been compiled (*note Dependencies::). The
- symptom is as follows.
- % make
- source='foo.c' object='foo.o' libtool=no \
- depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
- depmode=gcc /bin/sh ./depcomp \
- gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
- foo.c:2: bindir.h: No such file or directory
- make: *** [foo.o] Error 1
- In this example ‘bindir.h’ is not distributed nor installed, and it
- is not even being built on-time. One may wonder if the
- ‘nodist_foo_SOURCES = bindir.h’ line has any use at all. This line
- simply states that ‘bindir.h’ is a source of ‘foo’, so for instance, it
- should be inspected while generating tags (*note Tags::). In other
- words, it does not help our present problem, and the build would fail
- identically without it.
- Using ‘BUILT_SOURCES’
- .....................
- A solution is to require ‘bindir.h’ to be built before anything else.
- This is what ‘BUILT_SOURCES’ is meant for (*note Sources::).
- bin_PROGRAMS = foo
- foo_SOURCES = foo.c
- nodist_foo_SOURCES = bindir.h
- BUILT_SOURCES = bindir.h
- CLEANFILES = bindir.h
- bindir.h: Makefile
- echo '#define bindir "$(bindir)"' >$@
- See how ‘bindir.h’ gets built first:
- % make
- echo '#define bindir "/usr/local/bin"' >bindir.h
- make all-am
- make[1]: Entering directory `/home/adl/tmp'
- source='foo.c' object='foo.o' libtool=no \
- depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
- depmode=gcc /bin/sh ./depcomp \
- gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
- gcc -g -O2 -o foo foo.o
- make[1]: Leaving directory `/home/adl/tmp'
- However, as said earlier, ‘BUILT_SOURCES’ applies only to the ‘all’,
- ‘check’, and ‘install’ targets. It still fails if you try to run ‘make
- foo’ explicitly:
- % make clean
- test -z "bindir.h" || rm -f bindir.h
- test -z "foo" || rm -f foo
- rm -f *.o
- % : > .deps/foo.Po # Suppress previously recorded dependencies
- % make foo
- source='foo.c' object='foo.o' libtool=no \
- depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
- depmode=gcc /bin/sh ./depcomp \
- gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
- foo.c:2: bindir.h: No such file or directory
- make: *** [foo.o] Error 1
- Recording Dependencies manually
- ...............................
- Usually people are happy enough with ‘BUILT_SOURCES’ because they never
- build targets such as ‘make foo’ before ‘make all’, as in the previous
- example. However if this matters to you, you can avoid ‘BUILT_SOURCES’
- and record such dependencies explicitly in the ‘Makefile.am’.
- bin_PROGRAMS = foo
- foo_SOURCES = foo.c
- nodist_foo_SOURCES = bindir.h
- foo.$(OBJEXT): bindir.h
- CLEANFILES = bindir.h
- bindir.h: Makefile
- echo '#define bindir "$(bindir)"' >$@
- You don’t have to list _all_ the dependencies of ‘foo.o’ explicitly,
- only those that might need to be built. If a dependency already exists,
- it will not hinder the first compilation and will be recorded by the
- normal dependency tracking code. (Note that after this first
- compilation the dependency tracking code will also have recorded the
- dependency between ‘foo.o’ and ‘bindir.h’; so our explicit dependency is
- really useful to the first build only.)
- Adding explicit dependencies like this can be a bit dangerous if you
- are not careful enough. This is due to the way Automake tries not to
- overwrite your rules (it assumes you know better than it).
- ‘foo.$(OBJEXT): bindir.h’ supersedes any rule Automake may want to
- output to build ‘foo.$(OBJEXT)’. It happens to work in this case
- because Automake doesn’t have to output any ‘foo.$(OBJEXT):’ target: it
- relies on a suffix rule instead (i.e., ‘.c.$(OBJEXT):’). Always check
- the generated ‘Makefile.in’ if you do this.
- Build ‘bindir.h’ from ‘configure’
- .................................
- It’s possible to define this preprocessor macro from ‘configure’, either
- in ‘config.h’ (*note Defining Directories: (autoconf)Defining
- Directories.), or by processing a ‘bindir.h.in’ file using
- ‘AC_CONFIG_FILES’ (*note Configuration Actions: (autoconf)Configuration
- Actions.).
- At this point it should be clear that building ‘bindir.h’ from
- ‘configure’ works well for this example. ‘bindir.h’ will exist before
- you build any target, hence will not cause any dependency issue.
- The Makefile can be shrunk as follows. We do not even have to
- mention ‘bindir.h’.
- bin_PROGRAMS = foo
- foo_SOURCES = foo.c
- However, it’s not always possible to build sources from ‘configure’,
- especially when these sources are generated by a tool that needs to be
- built first.
- Build ‘bindir.c’, not ‘bindir.h’.
- .................................
- Another attractive idea is to define ‘bindir’ as a variable or function
- exported from ‘bindir.o’, and build ‘bindir.c’ instead of ‘bindir.h’.
- noinst_PROGRAMS = foo
- foo_SOURCES = foo.c bindir.h
- nodist_foo_SOURCES = bindir.c
- CLEANFILES = bindir.c
- bindir.c: Makefile
- echo 'const char bindir[] = "$(bindir)";' >$@
- ‘bindir.h’ contains just the variable’s declaration and doesn’t need
- to be built, so it won’t cause any trouble. ‘bindir.o’ is always
- dependent on ‘bindir.c’, so ‘bindir.c’ will get built first.
- Which is best?
- ..............
- There is no panacea, of course. Each solution has its merits and
- drawbacks.
- You cannot use ‘BUILT_SOURCES’ if the ability to run ‘make foo’ on a
- clean tree is important to you.
- You won’t add explicit dependencies if you are leery of overriding an
- Automake rule by mistake.
- Building files from ‘./configure’ is not always possible, neither is
- converting ‘.h’ files into ‘.c’ files.
- File: automake.info, Node: Other GNU Tools, Next: Documentation, Prev: Other Objects, Up: Top
- 10 Other GNU Tools
- ******************
- Since Automake is primarily intended to generate ‘Makefile.in’s for use
- in GNU programs, it tries hard to interoperate with other GNU tools.
- * Menu:
- * Emacs Lisp:: Emacs Lisp
- * gettext:: Gettext
- * Libtool:: Libtool
- * Java:: Java bytecode compilation (deprecated)
- * Python:: Python
- File: automake.info, Node: Emacs Lisp, Next: gettext, Up: Other GNU Tools
- 10.1 Emacs Lisp
- ===============
- Automake provides some support for Emacs Lisp. The ‘LISP’ primary is
- used to hold a list of ‘.el’ files. Possible prefixes for this primary
- are ‘lisp_’ and ‘noinst_’. Note that if ‘lisp_LISP’ is defined, then
- ‘configure.ac’ must run ‘AM_PATH_LISPDIR’ (*note Macros::).
- Lisp sources are not distributed by default. You can prefix the
- ‘LISP’ primary with ‘dist_’, as in ‘dist_lisp_LISP’ or
- ‘dist_noinst_LISP’, to indicate that these files should be distributed.
- Automake will byte-compile all Emacs Lisp source files using the
- Emacs found by ‘AM_PATH_LISPDIR’, if any was found. When performing
- such byte-compilation, the flags specified in the (developer-reserved)
- ‘AM_ELCFLAGS’ and (user-reserved) ‘ELCFLAGS’ make variables will be
- passed to the Emacs invocation.
- Byte-compiled Emacs Lisp files are not portable among all versions of
- Emacs, so it makes sense to turn this off if you expect sites to have
- more than one version of Emacs installed. Furthermore, many packages
- don’t actually benefit from byte-compilation. Still, we recommend that
- you byte-compile your Emacs Lisp sources. It is probably better for
- sites with strange setups to cope for themselves than to make the
- installation less nice for everybody else.
- There are two ways to avoid byte-compiling. Historically, we have
- recommended the following construct.
- lisp_LISP = file1.el file2.el
- ELCFILES =
- ‘ELCFILES’ is an internal Automake variable that normally lists all
- ‘.elc’ files that must be byte-compiled. Automake defines ‘ELCFILES’
- automatically from ‘lisp_LISP’. Emptying this variable explicitly
- prevents byte-compilation.
- Since Automake 1.8, we now recommend using ‘lisp_DATA’ instead:
- lisp_DATA = file1.el file2.el
- Note that these two constructs are not equivalent. ‘_LISP’ will not
- install a file if Emacs is not installed, while ‘_DATA’ will always
- install its files.
- File: automake.info, Node: gettext, Next: Libtool, Prev: Emacs Lisp, Up: Other GNU Tools
- 10.2 Gettext
- ============
- If ‘AM_GNU_GETTEXT’ is seen in ‘configure.ac’, then Automake turns on
- support for GNU gettext, a message catalog system for
- internationalization (*note Introduction: (gettext)Top.).
- The ‘gettext’ support in Automake requires the addition of one or two
- subdirectories to the package: ‘po’ and possibly also ‘intl’. The
- latter is needed if ‘AM_GNU_GETTEXT’ is not invoked with the ‘external’
- argument, or if ‘AM_GNU_GETTEXT_INTL_SUBDIR’ is used. Automake ensures
- that these directories exist and are mentioned in ‘SUBDIRS’.
- File: automake.info, Node: Libtool, Next: Java, Prev: gettext, Up: Other GNU Tools
- 10.3 Libtool
- ============
- Automake provides support for GNU Libtool (*note Introduction:
- (libtool)Top.) with the ‘LTLIBRARIES’ primary. *Note A Shared
- Library::.
- File: automake.info, Node: Java, Next: Python, Prev: Libtool, Up: Other GNU Tools
- 10.4 Java bytecode compilation (deprecated)
- ===========================================
- Automake provides some minimal support for Java bytecode compilation
- with the ‘JAVA’ primary (in addition to the support for compiling Java
- to native machine code; *note Java Support with gcj::). Note however
- that _the interface and most features described here are deprecated_.
- Future Automake releases will strive to provide a better and cleaner
- interface, which however _won’t be backward-compatible_; the present
- interface will probably be removed altogether some time after the
- introduction of the new interface (if that ever materializes). In any
- case, the current ‘JAVA’ primary features are frozen and will no longer
- be developed, not even to take bug fixes.
- Any ‘.java’ files listed in a ‘_JAVA’ variable will be compiled with
- ‘JAVAC’ at build time. By default, ‘.java’ files are not included in
- the distribution, you should use the ‘dist_’ prefix to distribute them.
- Here is a typical setup for distributing ‘.java’ files and installing
- the ‘.class’ files resulting from their compilation.
- javadir = $(datadir)/java
- dist_java_JAVA = a.java b.java ...
- Currently Automake enforces the restriction that only one ‘_JAVA’
- primary can be used in a given ‘Makefile.am’. The reason for this
- restriction is that, in general, it isn’t possible to know which
- ‘.class’ files were generated from which ‘.java’ files, so it would be
- impossible to know which files to install where. For instance, a
- ‘.java’ file can define multiple classes; the resulting ‘.class’ file
- names cannot be predicted without parsing the ‘.java’ file.
- There are a few variables that are used when compiling Java sources:
- ‘JAVAC’
- The name of the Java compiler. This defaults to ‘javac’.
- ‘JAVACFLAGS’
- The flags to pass to the compiler. This is considered to be a user
- variable (*note User Variables::).
- ‘AM_JAVACFLAGS’
- More flags to pass to the Java compiler. This, and not
- ‘JAVACFLAGS’, should be used when it is necessary to put Java
- compiler flags into ‘Makefile.am’.
- ‘JAVAROOT’
- The value of this variable is passed to the ‘-d’ option to ‘javac’.
- It defaults to ‘$(top_builddir)’.
- ‘CLASSPATH_ENV’
- This variable is a shell expression that is used to set the
- ‘CLASSPATH’ environment variable on the ‘javac’ command line. (In
- the future we will probably handle class path setting differently.)
- File: automake.info, Node: Python, Prev: Java, Up: Other GNU Tools
- 10.5 Python
- ===========
- Automake provides support for Python compilation with the ‘PYTHON’
- primary. A typical setup is to call ‘AM_PATH_PYTHON’ in ‘configure.ac’
- and use a line like the following in ‘Makefile.am’:
- python_PYTHON = tree.py leave.py
- Any files listed in a ‘_PYTHON’ variable will be byte-compiled with
- ‘py-compile’ at install time. ‘py-compile’ actually creates both
- standard (‘.pyc’) and optimized (‘.pyo’) byte-compiled versions of the
- source files. Note that because byte-compilation occurs at install
- time, any files listed in ‘noinst_PYTHON’ will not be compiled. Python
- source files are included in the distribution by default, prepend
- ‘nodist_’ (as in ‘nodist_python_PYTHON’) to omit them.
- Automake ships with an Autoconf macro called ‘AM_PATH_PYTHON’ that
- will determine some Python-related directory variables (see below). If
- you have called ‘AM_PATH_PYTHON’ from ‘configure.ac’, then you may use
- the variables ‘python_PYTHON’ or ‘pkgpython_PYTHON’ to list Python
- source files in your ‘Makefile.am’, depending on where you want your
- files installed (see the definitions of ‘pythondir’ and ‘pkgpythondir’
- below).
- -- Macro: AM_PATH_PYTHON ([VERSION], [ACTION-IF-FOUND],
- [ACTION-IF-NOT-FOUND])
- Search for a Python interpreter on the system. This macro takes
- three optional arguments. The first argument, if present, is the
- minimum version of Python required for this package:
- ‘AM_PATH_PYTHON’ will skip any Python interpreter that is older
- than VERSION. If an interpreter is found and satisfies VERSION,
- then ACTION-IF-FOUND is run. Otherwise, ACTION-IF-NOT-FOUND is
- run.
- If ACTION-IF-NOT-FOUND is not specified, as in the following
- example, the default is to abort ‘configure’.
- AM_PATH_PYTHON([2.2])
- This is fine when Python is an absolute requirement for the
- package. If Python >= 2.5 was only _optional_ to the package,
- ‘AM_PATH_PYTHON’ could be called as follows.
- AM_PATH_PYTHON([2.5],, [:])
- If the ‘PYTHON’ variable is set when ‘AM_PATH_PYTHON’ is called,
- then that will be the only Python interpreter that is tried.
- ‘AM_PATH_PYTHON’ creates the following output variables based on
- the Python installation found during configuration.
- ‘PYTHON’
- The name of the Python executable, or ‘:’ if no suitable
- interpreter could be found.
- Assuming ACTION-IF-NOT-FOUND is used (otherwise ‘./configure’ will
- abort if Python is absent), the value of ‘PYTHON’ can be used to
- setup a conditional in order to disable the relevant part of a
- build as follows.
- AM_PATH_PYTHON(,, [:])
- AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
- ‘PYTHON_VERSION’
- The Python version number, in the form MAJOR.MINOR (e.g., ‘2.5’).
- This is currently the value of ‘sys.version[:3]’.
- ‘PYTHON_PREFIX’
- The string ‘${prefix}’. This term may be used in future work that
- needs the contents of Python’s ‘sys.prefix’, but general consensus
- is to always use the value from ‘configure’.
- ‘PYTHON_EXEC_PREFIX’
- The string ‘${exec_prefix}’. This term may be used in future work
- that needs the contents of Python’s ‘sys.exec_prefix’, but general
- consensus is to always use the value from ‘configure’.
- ‘PYTHON_PLATFORM’
- The canonical name used by Python to describe the operating system,
- as given by ‘sys.platform’. This value is sometimes needed when
- building Python extensions.
- ‘pythondir’
- The directory name for the ‘site-packages’ subdirectory of the
- standard Python install tree.
- ‘pkgpythondir’
- This is the directory under ‘pythondir’ that is named after the
- package. That is, it is ‘$(pythondir)/$(PACKAGE)’. It is provided
- as a convenience.
- ‘pyexecdir’
- This is the directory where Python extension modules (shared
- libraries) should be installed. An extension module written in C
- could be declared as follows to Automake:
- pyexec_LTLIBRARIES = quaternion.la
- quaternion_la_SOURCES = quaternion.c support.c support.h
- quaternion_la_LDFLAGS = -avoid-version -module
- ‘pkgpyexecdir’
- This is a convenience variable that is defined as
- ‘$(pyexecdir)/$(PACKAGE)’.
- All of these directory variables have values that start with either
- ‘${prefix}’ or ‘${exec_prefix}’ unexpanded. This works fine in
- ‘Makefiles’, but it makes these variables hard to use in ‘configure’.
- This is mandated by the GNU coding standards, so that the user can run
- ‘make prefix=/foo install’. The Autoconf manual has a section with more
- details on this topic (*note Installation Directory Variables:
- (autoconf)Installation Directory Variables.). See also *note Hard-Coded
- Install Paths::.
- File: automake.info, Node: Documentation, Next: Install, Prev: Other GNU Tools, Up: Top
- 11 Building documentation
- *************************
- Currently Automake provides support for Texinfo and man pages.
- * Menu:
- * Texinfo:: Texinfo
- * Man Pages:: Man pages
- File: automake.info, Node: Texinfo, Next: Man Pages, Up: Documentation
- 11.1 Texinfo
- ============
- If the current directory contains Texinfo source, you must declare it
- with the ‘TEXINFOS’ primary. Generally Texinfo files are converted into
- info, and thus the ‘info_TEXINFOS’ variable is most commonly used here.
- Any Texinfo source file should have the ‘.texi’ extension. Automake
- also accepts ‘.txi’ or ‘.texinfo’ extensions, but their use is
- discouraged now, and will elicit runtime warnings.
- Automake generates rules to build ‘.info’, ‘.dvi’, ‘.ps’, ‘.pdf’ and
- ‘.html’ files from your Texinfo sources. Following the GNU Coding
- Standards, only the ‘.info’ files are built by ‘make all’ and installed
- by ‘make install’ (unless you use ‘no-installinfo’, see below).
- Furthermore, ‘.info’ files are automatically distributed so that Texinfo
- is not a prerequisite for installing your package.
- It is worth noting that, contrary to what happens with the other
- formats, the generated ‘.info’ files are by default placed in ‘srcdir’
- rather than in the ‘builddir’. This can be changed with the
- ‘info-in-builddir’ option.
- Other documentation formats can be built on request by ‘make dvi’,
- ‘make ps’, ‘make pdf’ and ‘make html’, and they can be installed with
- ‘make install-dvi’, ‘make install-ps’, ‘make install-pdf’ and ‘make
- install-html’ explicitly. ‘make uninstall’ will remove everything: the
- Texinfo documentation installed by default as well as all the above
- optional formats.
- All of these targets can be extended using ‘-local’ rules (*note
- Extending::).
- If the ‘.texi’ file ‘@include’s ‘version.texi’, then that file will
- be automatically generated. The file ‘version.texi’ defines four
- Texinfo flags you can reference using ‘@value{EDITION}’,
- ‘@value{VERSION}’, ‘@value{UPDATED}’, and ‘@value{UPDATED-MONTH}’.
- ‘EDITION’
- ‘VERSION’
- Both of these flags hold the version number of your program. They
- are kept separate for clarity.
- ‘UPDATED’
- This holds the date the primary ‘.texi’ file was last modified.
- ‘UPDATED-MONTH’
- This holds the name of the month in which the primary ‘.texi’ file
- was last modified.
- The ‘version.texi’ support requires the ‘mdate-sh’ script; this
- script is supplied with Automake and automatically included when
- ‘automake’ is invoked with the ‘--add-missing’ option.
- If you have multiple Texinfo files, and you want to use the
- ‘version.texi’ feature, then you have to have a separate version file
- for each Texinfo file. Automake will treat any include in a Texinfo
- file that matches ‘vers*.texi’ just as an automatically generated
- version file.
- Sometimes an info file actually depends on more than one ‘.texi’
- file. For instance, in GNU Hello, ‘hello.texi’ includes the file
- ‘fdl.texi’. You can tell Automake about these dependencies using the
- ‘TEXI_TEXINFOS’ variable. Here is how GNU Hello does it:
- info_TEXINFOS = hello.texi
- hello_TEXINFOS = fdl.texi
- By default, Automake requires the file ‘texinfo.tex’ to appear in the
- same directory as the ‘Makefile.am’ file that lists the ‘.texi’ files.
- If you used ‘AC_CONFIG_AUX_DIR’ in ‘configure.ac’ (*note Finding
- ‘configure’ Input: (autoconf)Input.), then ‘texinfo.tex’ is looked for
- there. In both cases, ‘automake’ then supplies ‘texinfo.tex’ if
- ‘--add-missing’ is given, and takes care of its distribution. However,
- if you set the ‘TEXINFO_TEX’ variable (see below), it overrides the
- location of the file and turns off its installation into the source as
- well as its distribution.
- The option ‘no-texinfo.tex’ can be used to eliminate the requirement
- for the file ‘texinfo.tex’. Use of the variable ‘TEXINFO_TEX’ is
- preferable, however, because that allows the ‘dvi’, ‘ps’, and ‘pdf’
- targets to still work.
- Automake generates an ‘install-info’ rule; some people apparently use
- this. By default, info pages are installed by ‘make install’, so
- running ‘make install-info’ is pointless. This can be prevented via the
- ‘no-installinfo’ option. In this case, ‘.info’ files are not installed
- by default, and user must request this explicitly using ‘make
- install-info’.
- By default, ‘make install-info’ and ‘make uninstall-info’ will try to
- run the ‘install-info’ program (if available) to update (or
- create/remove) the ‘${infodir}/dir’ index. If this is undesired, it can
- be prevented by exporting the ‘AM_UPDATE_INFO_DIR’ variable to "‘no’".
- The following variables are used by the Texinfo build rules.
- ‘MAKEINFO’
- The name of the program invoked to build ‘.info’ files. This
- variable is defined by Automake. If the ‘makeinfo’ program is
- found on the system then it will be used by default; otherwise
- ‘missing’ will be used instead.
- ‘MAKEINFOHTML’
- The command invoked to build ‘.html’ files. Automake defines this
- to ‘$(MAKEINFO) --html’.
- ‘MAKEINFOFLAGS’
- User flags passed to each invocation of ‘$(MAKEINFO)’ and
- ‘$(MAKEINFOHTML)’. This user variable (*note User Variables::) is
- not expected to be defined in any ‘Makefile’; it can be used by
- users to pass extra flags to suit their needs.
- ‘AM_MAKEINFOFLAGS’
- ‘AM_MAKEINFOHTMLFLAGS’
- Maintainer flags passed to each ‘makeinfo’ invocation. Unlike
- ‘MAKEINFOFLAGS’, these variables are meant to be defined by
- maintainers in ‘Makefile.am’. ‘$(AM_MAKEINFOFLAGS)’ is passed to
- ‘makeinfo’ when building ‘.info’ files; and
- ‘$(AM_MAKEINFOHTMLFLAGS)’ is used when building ‘.html’ files.
- For instance, the following setting can be used to obtain one
- single ‘.html’ file per manual, without node separators.
- AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
- ‘AM_MAKEINFOHTMLFLAGS’ defaults to ‘$(AM_MAKEINFOFLAGS)’. This
- means that defining ‘AM_MAKEINFOFLAGS’ without defining
- ‘AM_MAKEINFOHTMLFLAGS’ will impact builds of both ‘.info’ and
- ‘.html’ files.
- ‘TEXI2DVI’
- The name of the command that converts a ‘.texi’ file into a ‘.dvi’
- file. This defaults to ‘texi2dvi’, a script that ships with the
- Texinfo package.
- ‘TEXI2PDF’
- The name of the command that translates a ‘.texi’ file into a
- ‘.pdf’ file. This defaults to ‘$(TEXI2DVI) --pdf --batch’.
- ‘DVIPS’
- The name of the command that builds a ‘.ps’ file out of a ‘.dvi’
- file. This defaults to ‘dvips’.
- ‘TEXINFO_TEX’
- If your package has Texinfo files in many directories, you can use
- the variable ‘TEXINFO_TEX’ to tell Automake where to find the
- canonical ‘texinfo.tex’ for your package. The value of this
- variable should be the relative path from the current ‘Makefile.am’
- to ‘texinfo.tex’:
- TEXINFO_TEX = ../doc/texinfo.tex
- File: automake.info, Node: Man Pages, Prev: Texinfo, Up: Documentation
- 11.2 Man Pages
- ==============
- A package can also include man pages (but see the GNU standards on this
- matter, *note (standards)Man Pages::.) Man pages are declared using the
- ‘MANS’ primary. Generally the ‘man_MANS’ variable is used. Man pages
- are automatically installed in the correct subdirectory of ‘mandir’,
- based on the file extension.
- File extensions such as ‘.1c’ are handled by looking for the valid
- part of the extension and using that to determine the correct
- subdirectory of ‘mandir’. Valid section names are the digits ‘0’
- through ‘9’, and the letters ‘l’ and ‘n’.
- Sometimes developers prefer to name a man page something like
- ‘foo.man’ in the source, and then rename it to have the correct suffix,
- for example ‘foo.1’, when installing the file. Automake also supports
- this mode. For a valid section named SECTION, there is a corresponding
- directory named ‘manSECTIONdir’, and a corresponding ‘_MANS’ variable.
- Files listed in such a variable are installed in the indicated section.
- If the file already has a valid suffix, then it is installed as-is;
- otherwise the file suffix is changed to match the section.
- For instance, consider this example:
- man1_MANS = rename.man thesame.1 alsothesame.1c
- In this case, ‘rename.man’ will be renamed to ‘rename.1’ when installed,
- but the other files will keep their names.
- By default, man pages are installed by ‘make install’. However,
- since the GNU project does not require man pages, many maintainers do
- not expend effort to keep the man pages up to date. In these cases, the
- ‘no-installman’ option will prevent the man pages from being installed
- by default. The user can still explicitly install them via ‘make
- install-man’.
- For fast installation, with many files it is preferable to use
- ‘manSECTION_MANS’ over ‘man_MANS’ as well as files that do not need to
- be renamed.
- Man pages are not currently considered to be source, because it is
- not uncommon for man pages to be automatically generated. Therefore
- they are not automatically included in the distribution. However, this
- can be changed by use of the ‘dist_’ prefix. For instance here is how
- to distribute and install the two man pages of GNU ‘cpio’ (which
- includes both Texinfo documentation and man pages):
- dist_man_MANS = cpio.1 mt.1
- The ‘nobase_’ prefix is meaningless for man pages and is disallowed.
- Executables and manpages may be renamed upon installation (*note
- Renaming::). For manpages this can be avoided by use of the ‘notrans_’
- prefix. For instance, suppose an executable ‘foo’ allowing to access a
- library function ‘foo’ from the command line. The way to avoid renaming
- of the ‘foo.3’ manpage is:
- man_MANS = foo.1
- notrans_man_MANS = foo.3
- ‘notrans_’ must be specified first when used in conjunction with
- either ‘dist_’ or ‘nodist_’ (*note Fine-grained Distribution Control::).
- For instance:
- notrans_dist_man3_MANS = bar.3
- File: automake.info, Node: Install, Next: Clean, Prev: Documentation, Up: Top
- 12 What Gets Installed
- **********************
- Naturally, Automake handles the details of actually installing your
- program once it has been built. All files named by the various
- primaries are automatically installed in the appropriate places when the
- user runs ‘make install’.
- * Menu:
- * Basics of Installation:: What gets installed where
- * The Two Parts of Install:: Installing data and programs separately
- * Extending Installation:: Adding your own rules for installation
- * Staged Installs:: Installation in a temporary location
- * Install Rules for the User:: Useful additional rules
- File: automake.info, Node: Basics of Installation, Next: The Two Parts of Install, Up: Install
- 12.1 Basics of Installation
- ===========================
- A file named in a primary is installed by copying the built file into
- the appropriate directory. The base name of the file is used when
- installing.
- bin_PROGRAMS = hello subdir/goodbye
- In this example, both ‘hello’ and ‘goodbye’ will be installed in
- ‘$(bindir)’.
- Sometimes it is useful to avoid the basename step at install time.
- For instance, you might have a number of header files in subdirectories
- of the source tree that are laid out precisely how you want to install
- them. In this situation you can use the ‘nobase_’ prefix to suppress
- the base name step. For example:
- nobase_include_HEADERS = stdio.h sys/types.h
- will install ‘stdio.h’ in ‘$(includedir)’ and ‘types.h’ in
- ‘$(includedir)/sys’.
- For most file types, Automake will install multiple files at once,
- while avoiding command line length issues (*note Length Limitations::).
- Since some ‘install’ programs will not install the same file twice in
- one invocation, you may need to ensure that file lists are unique within
- one variable such as ‘nobase_include_HEADERS’ above.
- You should not rely on the order in which files listed in one
- variable are installed. Likewise, to cater for parallel make, you
- should not rely on any particular file installation order even among
- different file types (library dependencies are an exception here).
- File: automake.info, Node: The Two Parts of Install, Next: Extending Installation, Prev: Basics of Installation, Up: Install
- 12.2 The Two Parts of Install
- =============================
- Automake generates separate ‘install-data’ and ‘install-exec’ rules, in
- case the installer is installing on multiple machines that share
- directory structure—these targets allow the machine-independent parts to
- be installed only once. ‘install-exec’ installs platform-dependent
- files, and ‘install-data’ installs platform-independent files. The
- ‘install’ target depends on both of these targets. While Automake tries
- to automatically segregate objects into the correct category, the
- ‘Makefile.am’ author is, in the end, responsible for making sure this is
- done correctly.
- Variables using the standard directory prefixes ‘data’, ‘info’,
- ‘man’, ‘include’, ‘oldinclude’, ‘pkgdata’, or ‘pkginclude’ are installed
- by ‘install-data’.
- Variables using the standard directory prefixes ‘bin’, ‘sbin’,
- ‘libexec’, ‘sysconf’, ‘localstate’, ‘lib’, or ‘pkglib’ are installed by
- ‘install-exec’.
- For instance, ‘data_DATA’ files are installed by ‘install-data’,
- while ‘bin_PROGRAMS’ files are installed by ‘install-exec’.
- Any variable using a user-defined directory prefix with ‘exec’ in the
- name (e.g., ‘myexecbin_PROGRAMS’) is installed by ‘install-exec’. All
- other user-defined prefixes are installed by ‘install-data’.
- File: automake.info, Node: Extending Installation, Next: Staged Installs, Prev: The Two Parts of Install, Up: Install
- 12.3 Extending Installation
- ===========================
- It is possible to extend this mechanism by defining an
- ‘install-exec-local’ or ‘install-data-local’ rule. If these rules
- exist, they will be run at ‘make install’ time. These rules can do
- almost anything; care is required.
- Automake also supports two install hooks, ‘install-exec-hook’ and
- ‘install-data-hook’. These hooks are run after all other install rules
- of the appropriate type, exec or data, have completed. So, for
- instance, it is possible to perform post-installation modifications
- using an install hook. *Note Extending::, for some examples.
|