ref-variables.xml 849 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638663966406641664266436644664566466647664866496650665166526653665466556656665766586659666066616662666366646665666666676668666966706671667266736674667566766677667866796680668166826683668466856686668766886689669066916692669366946695669666976698669967006701670267036704670567066707670867096710671167126713671467156716671767186719672067216722672367246725672667276728672967306731673267336734673567366737673867396740674167426743674467456746674767486749675067516752675367546755675667576758675967606761676267636764676567666767676867696770677167726773677467756776677767786779678067816782678367846785678667876788678967906791679267936794679567966797679867996800680168026803680468056806680768086809681068116812681368146815681668176818681968206821682268236824682568266827682868296830683168326833683468356836683768386839684068416842684368446845684668476848684968506851685268536854685568566857685868596860686168626863686468656866686768686869687068716872687368746875687668776878687968806881688268836884688568866887688868896890689168926893689468956896689768986899690069016902690369046905690669076908690969106911691269136914691569166917691869196920692169226923692469256926692769286929693069316932693369346935693669376938693969406941694269436944694569466947694869496950695169526953695469556956695769586959696069616962696369646965696669676968696969706971697269736974697569766977697869796980698169826983698469856986698769886989699069916992699369946995699669976998699970007001700270037004700570067007700870097010701170127013701470157016701770187019702070217022702370247025702670277028702970307031703270337034703570367037703870397040704170427043704470457046704770487049705070517052705370547055705670577058705970607061706270637064706570667067706870697070707170727073707470757076707770787079708070817082708370847085708670877088708970907091709270937094709570967097709870997100710171027103710471057106710771087109711071117112711371147115711671177118711971207121712271237124712571267127712871297130713171327133713471357136713771387139714071417142714371447145714671477148714971507151715271537154715571567157715871597160716171627163716471657166716771687169717071717172717371747175717671777178717971807181718271837184718571867187718871897190719171927193719471957196719771987199720072017202720372047205720672077208720972107211721272137214721572167217721872197220722172227223722472257226722772287229723072317232723372347235723672377238723972407241724272437244724572467247724872497250725172527253725472557256725772587259726072617262726372647265726672677268726972707271727272737274727572767277727872797280728172827283728472857286728772887289729072917292729372947295729672977298729973007301730273037304730573067307730873097310731173127313731473157316731773187319732073217322732373247325732673277328732973307331733273337334733573367337733873397340734173427343734473457346734773487349735073517352735373547355735673577358735973607361736273637364736573667367736873697370737173727373737473757376737773787379738073817382738373847385738673877388738973907391739273937394739573967397739873997400740174027403740474057406740774087409741074117412741374147415741674177418741974207421742274237424742574267427742874297430743174327433743474357436743774387439744074417442744374447445744674477448744974507451745274537454745574567457745874597460746174627463746474657466746774687469747074717472747374747475747674777478747974807481748274837484748574867487748874897490749174927493749474957496749774987499750075017502750375047505750675077508750975107511751275137514751575167517751875197520752175227523752475257526752775287529753075317532753375347535753675377538753975407541754275437544754575467547754875497550755175527553755475557556755775587559756075617562756375647565756675677568756975707571757275737574757575767577757875797580758175827583758475857586758775887589759075917592759375947595759675977598759976007601760276037604760576067607760876097610761176127613761476157616761776187619762076217622762376247625762676277628762976307631763276337634763576367637763876397640764176427643764476457646764776487649765076517652765376547655765676577658765976607661766276637664766576667667766876697670767176727673767476757676767776787679768076817682768376847685768676877688768976907691769276937694769576967697769876997700770177027703770477057706770777087709771077117712771377147715771677177718771977207721772277237724772577267727772877297730773177327733773477357736773777387739774077417742774377447745774677477748774977507751775277537754775577567757775877597760776177627763776477657766776777687769777077717772777377747775777677777778777977807781778277837784778577867787778877897790779177927793779477957796779777987799780078017802780378047805780678077808780978107811781278137814781578167817781878197820782178227823782478257826782778287829783078317832783378347835783678377838783978407841784278437844784578467847784878497850785178527853785478557856785778587859786078617862786378647865786678677868786978707871787278737874787578767877787878797880788178827883788478857886788778887889789078917892789378947895789678977898789979007901790279037904790579067907790879097910791179127913791479157916791779187919792079217922792379247925792679277928792979307931793279337934793579367937793879397940794179427943794479457946794779487949795079517952795379547955795679577958795979607961796279637964796579667967796879697970797179727973797479757976797779787979798079817982798379847985798679877988798979907991799279937994799579967997799879998000800180028003800480058006800780088009801080118012801380148015801680178018801980208021802280238024802580268027802880298030803180328033803480358036803780388039804080418042804380448045804680478048804980508051805280538054805580568057805880598060806180628063806480658066806780688069807080718072807380748075807680778078807980808081808280838084808580868087808880898090809180928093809480958096809780988099810081018102810381048105810681078108810981108111811281138114811581168117811881198120812181228123812481258126812781288129813081318132813381348135813681378138813981408141814281438144814581468147814881498150815181528153815481558156815781588159816081618162816381648165816681678168816981708171817281738174817581768177817881798180818181828183818481858186818781888189819081918192819381948195819681978198819982008201820282038204820582068207820882098210821182128213821482158216821782188219822082218222822382248225822682278228822982308231823282338234823582368237823882398240824182428243824482458246824782488249825082518252825382548255825682578258825982608261826282638264826582668267826882698270827182728273827482758276827782788279828082818282828382848285828682878288828982908291829282938294829582968297829882998300830183028303830483058306830783088309831083118312831383148315831683178318831983208321832283238324832583268327832883298330833183328333833483358336833783388339834083418342834383448345834683478348834983508351835283538354835583568357835883598360836183628363836483658366836783688369837083718372837383748375837683778378837983808381838283838384838583868387838883898390839183928393839483958396839783988399840084018402840384048405840684078408840984108411841284138414841584168417841884198420842184228423842484258426842784288429843084318432843384348435843684378438843984408441844284438444844584468447844884498450845184528453845484558456845784588459846084618462846384648465846684678468846984708471847284738474847584768477847884798480848184828483848484858486848784888489849084918492849384948495849684978498849985008501850285038504850585068507850885098510851185128513851485158516851785188519852085218522852385248525852685278528852985308531853285338534853585368537853885398540854185428543854485458546854785488549855085518552855385548555855685578558855985608561856285638564856585668567856885698570857185728573857485758576857785788579858085818582858385848585858685878588858985908591859285938594859585968597859885998600860186028603860486058606860786088609861086118612861386148615861686178618861986208621862286238624862586268627862886298630863186328633863486358636863786388639864086418642864386448645864686478648864986508651865286538654865586568657865886598660866186628663866486658666866786688669867086718672867386748675867686778678867986808681868286838684868586868687868886898690869186928693869486958696869786988699870087018702870387048705870687078708870987108711871287138714871587168717871887198720872187228723872487258726872787288729873087318732873387348735873687378738873987408741874287438744874587468747874887498750875187528753875487558756875787588759876087618762876387648765876687678768876987708771877287738774877587768777877887798780878187828783878487858786878787888789879087918792879387948795879687978798879988008801880288038804880588068807880888098810881188128813881488158816881788188819882088218822882388248825882688278828882988308831883288338834883588368837883888398840884188428843884488458846884788488849885088518852885388548855885688578858885988608861886288638864886588668867886888698870887188728873887488758876887788788879888088818882888388848885888688878888888988908891889288938894889588968897889888998900890189028903890489058906890789088909891089118912891389148915891689178918891989208921892289238924892589268927892889298930893189328933893489358936893789388939894089418942894389448945894689478948894989508951895289538954895589568957895889598960896189628963896489658966896789688969897089718972897389748975897689778978897989808981898289838984898589868987898889898990899189928993899489958996899789988999900090019002900390049005900690079008900990109011901290139014901590169017901890199020902190229023902490259026902790289029903090319032903390349035903690379038903990409041904290439044904590469047904890499050905190529053905490559056905790589059906090619062906390649065906690679068906990709071907290739074907590769077907890799080908190829083908490859086908790889089909090919092909390949095909690979098909991009101910291039104910591069107910891099110911191129113911491159116911791189119912091219122912391249125912691279128912991309131913291339134913591369137913891399140914191429143914491459146914791489149915091519152915391549155915691579158915991609161916291639164916591669167916891699170917191729173917491759176917791789179918091819182918391849185918691879188918991909191919291939194919591969197919891999200920192029203920492059206920792089209921092119212921392149215921692179218921992209221922292239224922592269227922892299230923192329233923492359236923792389239924092419242924392449245924692479248924992509251925292539254925592569257925892599260926192629263926492659266926792689269927092719272927392749275927692779278927992809281928292839284928592869287928892899290929192929293929492959296929792989299930093019302930393049305930693079308930993109311931293139314931593169317931893199320932193229323932493259326932793289329933093319332933393349335933693379338933993409341934293439344934593469347934893499350935193529353935493559356935793589359936093619362936393649365936693679368936993709371937293739374937593769377937893799380938193829383938493859386938793889389939093919392939393949395939693979398939994009401940294039404940594069407940894099410941194129413941494159416941794189419942094219422942394249425942694279428942994309431943294339434943594369437943894399440944194429443944494459446944794489449945094519452945394549455945694579458945994609461946294639464946594669467946894699470947194729473947494759476947794789479948094819482948394849485948694879488948994909491949294939494949594969497949894999500950195029503950495059506950795089509951095119512951395149515951695179518951995209521952295239524952595269527952895299530953195329533953495359536953795389539954095419542954395449545954695479548954995509551955295539554955595569557955895599560956195629563956495659566956795689569957095719572957395749575957695779578957995809581958295839584958595869587958895899590959195929593959495959596959795989599960096019602960396049605960696079608960996109611961296139614961596169617961896199620962196229623962496259626962796289629963096319632963396349635963696379638963996409641964296439644964596469647964896499650965196529653965496559656965796589659966096619662966396649665966696679668966996709671967296739674967596769677967896799680968196829683968496859686968796889689969096919692969396949695969696979698969997009701970297039704970597069707970897099710971197129713971497159716971797189719972097219722972397249725972697279728972997309731973297339734973597369737973897399740974197429743974497459746974797489749975097519752975397549755975697579758975997609761976297639764976597669767976897699770977197729773977497759776977797789779978097819782978397849785978697879788978997909791979297939794979597969797979897999800980198029803980498059806980798089809981098119812981398149815981698179818981998209821982298239824982598269827982898299830983198329833983498359836983798389839984098419842984398449845984698479848984998509851985298539854985598569857985898599860986198629863986498659866986798689869987098719872987398749875987698779878987998809881988298839884988598869887988898899890989198929893989498959896989798989899990099019902990399049905990699079908990999109911991299139914991599169917991899199920992199229923992499259926992799289929993099319932993399349935993699379938993999409941994299439944994599469947994899499950995199529953995499559956995799589959996099619962996399649965996699679968996999709971997299739974997599769977997899799980998199829983998499859986998799889989999099919992999399949995999699979998999910000100011000210003100041000510006100071000810009100101001110012100131001410015100161001710018100191002010021100221002310024100251002610027100281002910030100311003210033100341003510036100371003810039100401004110042100431004410045100461004710048100491005010051100521005310054100551005610057100581005910060100611006210063100641006510066100671006810069100701007110072100731007410075100761007710078100791008010081100821008310084100851008610087100881008910090100911009210093100941009510096100971009810099101001010110102101031010410105101061010710108101091011010111101121011310114101151011610117101181011910120101211012210123101241012510126101271012810129101301013110132101331013410135101361013710138101391014010141101421014310144101451014610147101481014910150101511015210153101541015510156101571015810159101601016110162101631016410165101661016710168101691017010171101721017310174101751017610177101781017910180101811018210183101841018510186101871018810189101901019110192101931019410195101961019710198101991020010201102021020310204102051020610207102081020910210102111021210213102141021510216102171021810219102201022110222102231022410225102261022710228102291023010231102321023310234102351023610237102381023910240102411024210243102441024510246102471024810249102501025110252102531025410255102561025710258102591026010261102621026310264102651026610267102681026910270102711027210273102741027510276102771027810279102801028110282102831028410285102861028710288102891029010291102921029310294102951029610297102981029910300103011030210303103041030510306103071030810309103101031110312103131031410315103161031710318103191032010321103221032310324103251032610327103281032910330103311033210333103341033510336103371033810339103401034110342103431034410345103461034710348103491035010351103521035310354103551035610357103581035910360103611036210363103641036510366103671036810369103701037110372103731037410375103761037710378103791038010381103821038310384103851038610387103881038910390103911039210393103941039510396103971039810399104001040110402104031040410405104061040710408104091041010411104121041310414104151041610417104181041910420104211042210423104241042510426104271042810429104301043110432104331043410435104361043710438104391044010441104421044310444104451044610447104481044910450104511045210453104541045510456104571045810459104601046110462104631046410465104661046710468104691047010471104721047310474104751047610477104781047910480104811048210483104841048510486104871048810489104901049110492104931049410495104961049710498104991050010501105021050310504105051050610507105081050910510105111051210513105141051510516105171051810519105201052110522105231052410525105261052710528105291053010531105321053310534105351053610537105381053910540105411054210543105441054510546105471054810549105501055110552105531055410555105561055710558105591056010561105621056310564105651056610567105681056910570105711057210573105741057510576105771057810579105801058110582105831058410585105861058710588105891059010591105921059310594105951059610597105981059910600106011060210603106041060510606106071060810609106101061110612106131061410615106161061710618106191062010621106221062310624106251062610627106281062910630106311063210633106341063510636106371063810639106401064110642106431064410645106461064710648106491065010651106521065310654106551065610657106581065910660106611066210663106641066510666106671066810669106701067110672106731067410675106761067710678106791068010681106821068310684106851068610687106881068910690106911069210693106941069510696106971069810699107001070110702107031070410705107061070710708107091071010711107121071310714107151071610717107181071910720107211072210723107241072510726107271072810729107301073110732107331073410735107361073710738107391074010741107421074310744107451074610747107481074910750107511075210753107541075510756107571075810759107601076110762107631076410765107661076710768107691077010771107721077310774107751077610777107781077910780107811078210783107841078510786107871078810789107901079110792107931079410795107961079710798107991080010801108021080310804108051080610807108081080910810108111081210813108141081510816108171081810819108201082110822108231082410825108261082710828108291083010831108321083310834108351083610837108381083910840108411084210843108441084510846108471084810849108501085110852108531085410855108561085710858108591086010861108621086310864108651086610867108681086910870108711087210873108741087510876108771087810879108801088110882108831088410885108861088710888108891089010891108921089310894108951089610897108981089910900109011090210903109041090510906109071090810909109101091110912109131091410915109161091710918109191092010921109221092310924109251092610927109281092910930109311093210933109341093510936109371093810939109401094110942109431094410945109461094710948109491095010951109521095310954109551095610957109581095910960109611096210963109641096510966109671096810969109701097110972109731097410975109761097710978109791098010981109821098310984109851098610987109881098910990109911099210993109941099510996109971099810999110001100111002110031100411005110061100711008110091101011011110121101311014110151101611017110181101911020110211102211023110241102511026110271102811029110301103111032110331103411035110361103711038110391104011041110421104311044110451104611047110481104911050110511105211053110541105511056110571105811059110601106111062110631106411065110661106711068110691107011071110721107311074110751107611077110781107911080110811108211083110841108511086110871108811089110901109111092110931109411095110961109711098110991110011101111021110311104111051110611107111081110911110111111111211113111141111511116111171111811119111201112111122111231112411125111261112711128111291113011131111321113311134111351113611137111381113911140111411114211143111441114511146111471114811149111501115111152111531115411155111561115711158111591116011161111621116311164111651116611167111681116911170111711117211173111741117511176111771117811179111801118111182111831118411185111861118711188111891119011191111921119311194111951119611197111981119911200112011120211203112041120511206112071120811209112101121111212112131121411215112161121711218112191122011221112221122311224112251122611227112281122911230112311123211233112341123511236112371123811239112401124111242112431124411245112461124711248112491125011251112521125311254112551125611257112581125911260112611126211263112641126511266112671126811269112701127111272112731127411275112761127711278112791128011281112821128311284112851128611287112881128911290112911129211293112941129511296112971129811299113001130111302113031130411305113061130711308113091131011311113121131311314113151131611317113181131911320113211132211323113241132511326113271132811329113301133111332113331133411335113361133711338113391134011341113421134311344113451134611347113481134911350113511135211353113541135511356113571135811359113601136111362113631136411365113661136711368113691137011371113721137311374113751137611377113781137911380113811138211383113841138511386113871138811389113901139111392113931139411395113961139711398113991140011401114021140311404114051140611407114081140911410114111141211413114141141511416114171141811419114201142111422114231142411425114261142711428114291143011431114321143311434114351143611437114381143911440114411144211443114441144511446114471144811449114501145111452114531145411455114561145711458114591146011461114621146311464114651146611467114681146911470114711147211473114741147511476114771147811479114801148111482114831148411485114861148711488114891149011491114921149311494114951149611497114981149911500115011150211503115041150511506115071150811509115101151111512115131151411515115161151711518115191152011521115221152311524115251152611527115281152911530115311153211533115341153511536115371153811539115401154111542115431154411545115461154711548115491155011551115521155311554115551155611557115581155911560115611156211563115641156511566115671156811569115701157111572115731157411575115761157711578115791158011581115821158311584115851158611587115881158911590115911159211593115941159511596115971159811599116001160111602116031160411605116061160711608116091161011611116121161311614116151161611617116181161911620116211162211623116241162511626116271162811629116301163111632116331163411635116361163711638116391164011641116421164311644116451164611647116481164911650116511165211653116541165511656116571165811659116601166111662116631166411665116661166711668116691167011671116721167311674116751167611677116781167911680116811168211683116841168511686116871168811689116901169111692116931169411695116961169711698116991170011701117021170311704117051170611707117081170911710117111171211713117141171511716117171171811719117201172111722117231172411725117261172711728117291173011731117321173311734117351173611737117381173911740117411174211743117441174511746117471174811749117501175111752117531175411755117561175711758117591176011761117621176311764117651176611767117681176911770117711177211773117741177511776117771177811779117801178111782117831178411785117861178711788117891179011791117921179311794117951179611797117981179911800118011180211803118041180511806118071180811809118101181111812118131181411815118161181711818118191182011821118221182311824118251182611827118281182911830118311183211833118341183511836118371183811839118401184111842118431184411845118461184711848118491185011851118521185311854118551185611857118581185911860118611186211863118641186511866118671186811869118701187111872118731187411875118761187711878118791188011881118821188311884118851188611887118881188911890118911189211893118941189511896118971189811899119001190111902119031190411905119061190711908119091191011911119121191311914119151191611917119181191911920119211192211923119241192511926119271192811929119301193111932119331193411935119361193711938119391194011941119421194311944119451194611947119481194911950119511195211953119541195511956119571195811959119601196111962119631196411965119661196711968119691197011971119721197311974119751197611977119781197911980119811198211983119841198511986119871198811989119901199111992119931199411995119961199711998119991200012001120021200312004120051200612007120081200912010120111201212013120141201512016120171201812019120201202112022120231202412025120261202712028120291203012031120321203312034120351203612037120381203912040120411204212043120441204512046120471204812049120501205112052120531205412055120561205712058120591206012061120621206312064120651206612067120681206912070120711207212073120741207512076120771207812079120801208112082120831208412085120861208712088120891209012091120921209312094120951209612097120981209912100121011210212103121041210512106121071210812109121101211112112121131211412115121161211712118121191212012121121221212312124121251212612127121281212912130121311213212133121341213512136121371213812139121401214112142121431214412145121461214712148121491215012151121521215312154121551215612157121581215912160121611216212163121641216512166121671216812169121701217112172121731217412175121761217712178121791218012181121821218312184121851218612187121881218912190121911219212193121941219512196121971219812199122001220112202122031220412205122061220712208122091221012211122121221312214122151221612217122181221912220122211222212223122241222512226122271222812229122301223112232122331223412235122361223712238122391224012241122421224312244122451224612247122481224912250122511225212253122541225512256122571225812259122601226112262122631226412265122661226712268122691227012271122721227312274122751227612277122781227912280122811228212283122841228512286122871228812289122901229112292122931229412295122961229712298122991230012301123021230312304123051230612307123081230912310123111231212313123141231512316123171231812319123201232112322123231232412325123261232712328123291233012331123321233312334123351233612337123381233912340123411234212343123441234512346123471234812349123501235112352123531235412355123561235712358123591236012361123621236312364123651236612367123681236912370123711237212373123741237512376123771237812379123801238112382123831238412385123861238712388123891239012391123921239312394123951239612397123981239912400124011240212403124041240512406124071240812409124101241112412124131241412415124161241712418124191242012421124221242312424124251242612427124281242912430124311243212433124341243512436124371243812439124401244112442124431244412445124461244712448124491245012451124521245312454124551245612457124581245912460124611246212463124641246512466124671246812469124701247112472124731247412475124761247712478124791248012481124821248312484124851248612487124881248912490124911249212493124941249512496124971249812499125001250112502125031250412505125061250712508125091251012511125121251312514125151251612517125181251912520125211252212523125241252512526125271252812529125301253112532125331253412535125361253712538125391254012541125421254312544125451254612547125481254912550125511255212553125541255512556125571255812559125601256112562125631256412565125661256712568125691257012571125721257312574125751257612577125781257912580125811258212583125841258512586125871258812589125901259112592125931259412595125961259712598125991260012601126021260312604126051260612607126081260912610126111261212613126141261512616126171261812619126201262112622126231262412625126261262712628126291263012631126321263312634126351263612637126381263912640126411264212643126441264512646126471264812649126501265112652126531265412655126561265712658126591266012661126621266312664126651266612667126681266912670126711267212673126741267512676126771267812679126801268112682126831268412685126861268712688126891269012691126921269312694126951269612697126981269912700127011270212703127041270512706127071270812709127101271112712127131271412715127161271712718127191272012721127221272312724127251272612727127281272912730127311273212733127341273512736127371273812739127401274112742127431274412745127461274712748127491275012751127521275312754127551275612757127581275912760127611276212763127641276512766127671276812769127701277112772127731277412775127761277712778127791278012781127821278312784127851278612787127881278912790127911279212793127941279512796127971279812799128001280112802128031280412805128061280712808128091281012811128121281312814128151281612817128181281912820128211282212823128241282512826128271282812829128301283112832128331283412835128361283712838128391284012841128421284312844128451284612847128481284912850128511285212853128541285512856128571285812859128601286112862128631286412865128661286712868128691287012871128721287312874128751287612877128781287912880128811288212883128841288512886128871288812889128901289112892128931289412895128961289712898128991290012901129021290312904129051290612907129081290912910129111291212913129141291512916129171291812919129201292112922129231292412925129261292712928129291293012931129321293312934129351293612937129381293912940129411294212943129441294512946129471294812949129501295112952129531295412955129561295712958129591296012961129621296312964129651296612967129681296912970129711297212973129741297512976129771297812979129801298112982129831298412985129861298712988129891299012991129921299312994129951299612997129981299913000130011300213003130041300513006130071300813009130101301113012130131301413015130161301713018130191302013021130221302313024130251302613027130281302913030130311303213033130341303513036130371303813039130401304113042130431304413045130461304713048130491305013051130521305313054130551305613057130581305913060130611306213063130641306513066130671306813069130701307113072130731307413075130761307713078130791308013081130821308313084130851308613087130881308913090130911309213093130941309513096130971309813099131001310113102131031310413105131061310713108131091311013111131121311313114131151311613117131181311913120131211312213123131241312513126131271312813129131301313113132131331313413135131361313713138131391314013141131421314313144131451314613147131481314913150131511315213153131541315513156131571315813159131601316113162131631316413165131661316713168131691317013171131721317313174131751317613177131781317913180131811318213183131841318513186131871318813189131901319113192131931319413195131961319713198131991320013201132021320313204132051320613207132081320913210132111321213213132141321513216132171321813219132201322113222132231322413225132261322713228132291323013231132321323313234132351323613237132381323913240132411324213243132441324513246132471324813249132501325113252132531325413255132561325713258132591326013261132621326313264132651326613267132681326913270132711327213273132741327513276132771327813279132801328113282132831328413285132861328713288132891329013291132921329313294132951329613297132981329913300133011330213303133041330513306133071330813309133101331113312133131331413315133161331713318133191332013321133221332313324133251332613327133281332913330133311333213333133341333513336133371333813339133401334113342133431334413345133461334713348133491335013351133521335313354133551335613357133581335913360133611336213363133641336513366133671336813369133701337113372133731337413375133761337713378133791338013381133821338313384133851338613387133881338913390133911339213393133941339513396133971339813399134001340113402134031340413405134061340713408134091341013411134121341313414134151341613417134181341913420134211342213423134241342513426134271342813429134301343113432134331343413435134361343713438134391344013441134421344313444134451344613447134481344913450134511345213453134541345513456134571345813459134601346113462134631346413465134661346713468134691347013471134721347313474134751347613477134781347913480134811348213483134841348513486134871348813489134901349113492134931349413495134961349713498134991350013501135021350313504135051350613507135081350913510135111351213513135141351513516135171351813519135201352113522135231352413525135261352713528135291353013531135321353313534135351353613537135381353913540135411354213543135441354513546135471354813549135501355113552135531355413555135561355713558135591356013561135621356313564135651356613567135681356913570135711357213573135741357513576135771357813579135801358113582135831358413585135861358713588135891359013591135921359313594135951359613597135981359913600136011360213603136041360513606136071360813609136101361113612136131361413615136161361713618136191362013621136221362313624136251362613627136281362913630136311363213633136341363513636136371363813639136401364113642136431364413645136461364713648136491365013651136521365313654136551365613657136581365913660136611366213663136641366513666136671366813669136701367113672136731367413675136761367713678136791368013681136821368313684136851368613687136881368913690136911369213693136941369513696136971369813699137001370113702137031370413705137061370713708137091371013711137121371313714137151371613717137181371913720137211372213723137241372513726137271372813729137301373113732137331373413735137361373713738137391374013741137421374313744137451374613747137481374913750137511375213753137541375513756137571375813759137601376113762137631376413765137661376713768137691377013771137721377313774137751377613777137781377913780137811378213783137841378513786137871378813789137901379113792137931379413795137961379713798137991380013801138021380313804138051380613807138081380913810138111381213813138141381513816138171381813819138201382113822138231382413825138261382713828138291383013831138321383313834138351383613837138381383913840138411384213843138441384513846138471384813849138501385113852138531385413855138561385713858138591386013861138621386313864138651386613867138681386913870138711387213873138741387513876138771387813879138801388113882138831388413885138861388713888138891389013891138921389313894138951389613897138981389913900139011390213903139041390513906139071390813909139101391113912139131391413915139161391713918139191392013921139221392313924139251392613927139281392913930139311393213933139341393513936139371393813939139401394113942139431394413945139461394713948139491395013951139521395313954139551395613957139581395913960139611396213963139641396513966139671396813969139701397113972139731397413975139761397713978139791398013981139821398313984139851398613987139881398913990139911399213993139941399513996139971399813999140001400114002140031400414005140061400714008140091401014011140121401314014140151401614017140181401914020140211402214023140241402514026140271402814029140301403114032140331403414035140361403714038140391404014041140421404314044140451404614047140481404914050140511405214053140541405514056140571405814059140601406114062140631406414065140661406714068140691407014071140721407314074140751407614077140781407914080140811408214083140841408514086140871408814089140901409114092140931409414095140961409714098140991410014101141021410314104141051410614107141081410914110141111411214113141141411514116141171411814119141201412114122141231412414125141261412714128141291413014131141321413314134141351413614137141381413914140141411414214143141441414514146141471414814149141501415114152141531415414155141561415714158141591416014161141621416314164141651416614167141681416914170141711417214173141741417514176141771417814179141801418114182141831418414185141861418714188141891419014191141921419314194141951419614197141981419914200142011420214203142041420514206142071420814209142101421114212142131421414215142161421714218142191422014221142221422314224142251422614227142281422914230142311423214233142341423514236142371423814239142401424114242142431424414245142461424714248142491425014251142521425314254142551425614257142581425914260142611426214263142641426514266142671426814269142701427114272142731427414275142761427714278142791428014281142821428314284142851428614287142881428914290142911429214293142941429514296142971429814299143001430114302143031430414305143061430714308143091431014311143121431314314143151431614317143181431914320143211432214323143241432514326143271432814329143301433114332143331433414335143361433714338143391434014341143421434314344143451434614347143481434914350143511435214353143541435514356143571435814359143601436114362143631436414365143661436714368143691437014371143721437314374143751437614377143781437914380143811438214383143841438514386143871438814389143901439114392143931439414395143961439714398143991440014401144021440314404144051440614407144081440914410144111441214413144141441514416144171441814419144201442114422144231442414425144261442714428144291443014431144321443314434144351443614437144381443914440144411444214443144441444514446144471444814449144501445114452144531445414455144561445714458144591446014461144621446314464144651446614467144681446914470144711447214473144741447514476144771447814479144801448114482144831448414485144861448714488144891449014491144921449314494144951449614497144981449914500145011450214503145041450514506145071450814509145101451114512145131451414515145161451714518145191452014521145221452314524145251452614527145281452914530145311453214533145341453514536145371453814539145401454114542145431454414545145461454714548145491455014551145521455314554145551455614557145581455914560145611456214563145641456514566145671456814569145701457114572145731457414575145761457714578145791458014581145821458314584145851458614587145881458914590145911459214593145941459514596145971459814599146001460114602146031460414605146061460714608146091461014611146121461314614146151461614617146181461914620146211462214623146241462514626146271462814629146301463114632146331463414635146361463714638146391464014641146421464314644146451464614647146481464914650146511465214653146541465514656146571465814659146601466114662146631466414665146661466714668146691467014671146721467314674146751467614677146781467914680146811468214683146841468514686146871468814689146901469114692146931469414695146961469714698146991470014701147021470314704147051470614707147081470914710147111471214713147141471514716147171471814719147201472114722147231472414725147261472714728147291473014731147321473314734147351473614737147381473914740147411474214743147441474514746147471474814749147501475114752147531475414755147561475714758147591476014761147621476314764147651476614767147681476914770147711477214773147741477514776147771477814779147801478114782147831478414785147861478714788147891479014791147921479314794147951479614797147981479914800148011480214803148041480514806148071480814809148101481114812148131481414815148161481714818148191482014821148221482314824148251482614827148281482914830148311483214833148341483514836148371483814839148401484114842148431484414845148461484714848148491485014851148521485314854148551485614857148581485914860148611486214863148641486514866148671486814869148701487114872148731487414875148761487714878148791488014881148821488314884148851488614887148881488914890148911489214893148941489514896148971489814899149001490114902149031490414905149061490714908149091491014911149121491314914149151491614917149181491914920149211492214923149241492514926149271492814929149301493114932149331493414935149361493714938149391494014941149421494314944149451494614947149481494914950149511495214953149541495514956149571495814959149601496114962149631496414965149661496714968149691497014971149721497314974149751497614977149781497914980149811498214983149841498514986149871498814989149901499114992149931499414995149961499714998149991500015001150021500315004150051500615007150081500915010150111501215013150141501515016150171501815019150201502115022150231502415025150261502715028150291503015031150321503315034150351503615037150381503915040150411504215043150441504515046150471504815049150501505115052150531505415055150561505715058150591506015061150621506315064150651506615067150681506915070150711507215073150741507515076150771507815079150801508115082150831508415085150861508715088150891509015091150921509315094150951509615097150981509915100151011510215103151041510515106151071510815109151101511115112151131511415115151161511715118151191512015121151221512315124151251512615127151281512915130151311513215133151341513515136151371513815139151401514115142151431514415145151461514715148151491515015151151521515315154151551515615157151581515915160151611516215163151641516515166151671516815169151701517115172151731517415175151761517715178151791518015181151821518315184151851518615187151881518915190151911519215193151941519515196151971519815199152001520115202152031520415205152061520715208152091521015211152121521315214152151521615217152181521915220152211522215223152241522515226152271522815229152301523115232152331523415235152361523715238152391524015241152421524315244152451524615247152481524915250152511525215253152541525515256152571525815259152601526115262152631526415265152661526715268152691527015271152721527315274152751527615277152781527915280152811528215283152841528515286152871528815289152901529115292152931529415295152961529715298152991530015301153021530315304153051530615307153081530915310153111531215313153141531515316153171531815319153201532115322153231532415325153261532715328153291533015331153321533315334153351533615337153381533915340153411534215343153441534515346153471534815349153501535115352153531535415355153561535715358153591536015361153621536315364153651536615367153681536915370153711537215373153741537515376153771537815379153801538115382153831538415385153861538715388153891539015391153921539315394153951539615397153981539915400154011540215403154041540515406154071540815409154101541115412154131541415415154161541715418154191542015421154221542315424154251542615427154281542915430154311543215433154341543515436154371543815439154401544115442154431544415445154461544715448154491545015451154521545315454154551545615457154581545915460154611546215463154641546515466154671546815469154701547115472154731547415475154761547715478154791548015481154821548315484154851548615487154881548915490154911549215493154941549515496154971549815499155001550115502155031550415505155061550715508155091551015511155121551315514155151551615517155181551915520155211552215523155241552515526155271552815529155301553115532155331553415535155361553715538155391554015541155421554315544155451554615547155481554915550155511555215553155541555515556155571555815559155601556115562155631556415565155661556715568155691557015571155721557315574155751557615577155781557915580155811558215583155841558515586155871558815589155901559115592155931559415595155961559715598155991560015601156021560315604156051560615607156081560915610156111561215613156141561515616156171561815619156201562115622156231562415625156261562715628156291563015631156321563315634156351563615637156381563915640156411564215643156441564515646156471564815649156501565115652156531565415655156561565715658156591566015661156621566315664156651566615667156681566915670156711567215673156741567515676156771567815679156801568115682156831568415685156861568715688156891569015691156921569315694156951569615697156981569915700157011570215703157041570515706157071570815709157101571115712157131571415715157161571715718157191572015721157221572315724157251572615727157281572915730157311573215733157341573515736157371573815739157401574115742157431574415745157461574715748157491575015751157521575315754157551575615757157581575915760157611576215763157641576515766157671576815769157701577115772157731577415775157761577715778157791578015781157821578315784157851578615787157881578915790157911579215793157941579515796157971579815799158001580115802158031580415805158061580715808158091581015811158121581315814158151581615817158181581915820158211582215823158241582515826158271582815829158301583115832158331583415835158361583715838158391584015841158421584315844158451584615847158481584915850158511585215853158541585515856158571585815859158601586115862158631586415865158661586715868158691587015871158721587315874158751587615877158781587915880158811588215883158841588515886158871588815889158901589115892158931589415895158961589715898158991590015901159021590315904159051590615907159081590915910159111591215913159141591515916159171591815919159201592115922159231592415925159261592715928159291593015931159321593315934159351593615937159381593915940159411594215943159441594515946159471594815949159501595115952159531595415955159561595715958159591596015961159621596315964159651596615967159681596915970159711597215973159741597515976159771597815979159801598115982159831598415985159861598715988159891599015991159921599315994159951599615997159981599916000160011600216003160041600516006160071600816009160101601116012160131601416015160161601716018160191602016021160221602316024160251602616027160281602916030160311603216033160341603516036160371603816039160401604116042160431604416045160461604716048160491605016051160521605316054160551605616057160581605916060160611606216063160641606516066160671606816069160701607116072160731607416075160761607716078160791608016081160821608316084160851608616087160881608916090160911609216093160941609516096160971609816099161001610116102161031610416105161061610716108161091611016111161121611316114161151611616117161181611916120161211612216123161241612516126161271612816129161301613116132161331613416135161361613716138161391614016141161421614316144161451614616147161481614916150161511615216153161541615516156161571615816159161601616116162161631616416165161661616716168161691617016171161721617316174161751617616177161781617916180161811618216183161841618516186161871618816189161901619116192161931619416195161961619716198161991620016201162021620316204162051620616207162081620916210162111621216213162141621516216162171621816219162201622116222162231622416225162261622716228162291623016231162321623316234162351623616237162381623916240162411624216243162441624516246162471624816249162501625116252162531625416255162561625716258162591626016261162621626316264162651626616267162681626916270162711627216273162741627516276162771627816279162801628116282162831628416285162861628716288162891629016291162921629316294162951629616297162981629916300163011630216303163041630516306163071630816309163101631116312163131631416315163161631716318163191632016321163221632316324163251632616327163281632916330163311633216333163341633516336163371633816339163401634116342163431634416345163461634716348163491635016351163521635316354163551635616357163581635916360163611636216363163641636516366163671636816369163701637116372163731637416375163761637716378163791638016381163821638316384163851638616387163881638916390163911639216393163941639516396163971639816399164001640116402164031640416405164061640716408164091641016411164121641316414164151641616417164181641916420164211642216423164241642516426164271642816429164301643116432164331643416435164361643716438164391644016441164421644316444164451644616447164481644916450164511645216453164541645516456164571645816459164601646116462164631646416465164661646716468164691647016471164721647316474164751647616477164781647916480164811648216483164841648516486164871648816489164901649116492164931649416495164961649716498164991650016501165021650316504165051650616507165081650916510165111651216513165141651516516165171651816519165201652116522165231652416525165261652716528165291653016531165321653316534165351653616537165381653916540165411654216543165441654516546165471654816549165501655116552165531655416555165561655716558165591656016561165621656316564165651656616567165681656916570165711657216573165741657516576165771657816579165801658116582165831658416585165861658716588165891659016591165921659316594165951659616597165981659916600166011660216603166041660516606166071660816609166101661116612166131661416615166161661716618166191662016621166221662316624166251662616627166281662916630
  1. <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  2. "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
  3. [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
  4. <!-- Dummy chapter -->
  5. <chapter id='ref-variables-glos'>
  6. <title>Variables Glossary</title>
  7. <para>
  8. This chapter lists common variables used in the OpenEmbedded build system and gives an overview
  9. of their function and contents.
  10. </para>
  11. <glossary id='ref-variables-glossary'>
  12. <para>
  13. <link linkend='var-ABIEXTENSION'>A</link>
  14. <link linkend='var-B'>B</link>
  15. <link linkend='var-CACHE'>C</link>
  16. <link linkend='var-D'>D</link>
  17. <link linkend='var-EFI_PROVIDER'>E</link>
  18. <link linkend='var-FEATURE_PACKAGES'>F</link>
  19. <link linkend='var-GCCPIE'>G</link>
  20. <link linkend='var-HOMEPAGE'>H</link>
  21. <link linkend='var-ICECC_DISABLED'>I</link>
  22. <!-- <link linkend='var-glossary-j'>J</link> -->
  23. <link linkend='var-KARCH'>K</link>
  24. <link linkend='var-LABELS'>L</link>
  25. <link linkend='var-MACHINE'>M</link>
  26. <link linkend='var-NATIVELSBSTRING'>N</link>
  27. <link linkend='var-OBJCOPY'>O</link>
  28. <link linkend='var-P'>P</link>
  29. <!-- <link linkend='var-glossary-q'>Q</link> -->
  30. <link linkend='var-RANLIB'>R</link>
  31. <link linkend='var-S'>S</link>
  32. <link linkend='var-T'>T</link>
  33. <link linkend='var-UBOOT_CONFIG'>U</link>
  34. <link linkend='var-VOLATILE_LOG_DIR'>V</link>
  35. <link linkend='var-WARN_QA'>W</link>
  36. <link linkend='var-XSERVER'>X</link>
  37. <!-- <link linkend='var-glossary-y'>Y</link> -->
  38. <!-- <link linkend='var-glossary-z'>Z</link>-->
  39. </para>
  40. <glossdiv id='var-glossary-a'><title>A</title>
  41. <glossentry id='var-ABIEXTENSION'><glossterm>ABIEXTENSION</glossterm>
  42. <info>
  43. ABIEXTENSION[doc] = "Extension to the Application Binary Interface (ABI) field of the GNU canonical architecture name (e.g. "eabi")."
  44. </info>
  45. <glossdef>
  46. <para role="glossdeffirst">
  47. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  48. Extension to the Application Binary Interface (ABI)
  49. field of the GNU canonical architecture name
  50. (e.g. "eabi").
  51. </para>
  52. <para>
  53. ABI extensions are set in the machine include files.
  54. For example, the
  55. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>
  56. file sets the following extension:
  57. <literallayout class='monospaced'>
  58. ABIEXTENSION = "eabi"
  59. </literallayout>
  60. </para>
  61. </glossdef>
  62. </glossentry>
  63. <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
  64. <info>
  65. ALLOW_EMPTY[doc] = "Specifies whether to produce an output package even if it is empty."
  66. </info>
  67. <glossdef>
  68. <para role="glossdeffirst">
  69. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  70. Specifies whether to produce an output package even if it is
  71. empty.
  72. By default, BitBake does not produce empty packages.
  73. This default behavior can cause issues when there is an
  74. <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
  75. some other hard runtime requirement on the existence of the package.
  76. </para>
  77. <para>
  78. Like all package-controlling variables, you must always use them in
  79. conjunction with a package name override, as in:
  80. <literallayout class='monospaced'>
  81. ALLOW_EMPTY_${PN} = "1"
  82. ALLOW_EMPTY_${PN}-dev = "1"
  83. ALLOW_EMPTY_${PN}-staticdev = "1"
  84. </literallayout>
  85. </para>
  86. </glossdef>
  87. </glossentry>
  88. <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
  89. <info>
  90. ALTERNATIVE[doc] = "Lists commands in a package that need an alternative binary naming scheme."
  91. </info>
  92. <glossdef>
  93. <para role="glossdeffirst">
  94. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  95. Lists commands in a package that need an alternative
  96. binary naming scheme.
  97. Sometimes the same command is provided in multiple packages.
  98. When this occurs, the OpenEmbedded build system needs to
  99. use the alternatives system to create a different binary
  100. naming scheme so the commands can co-exist.
  101. </para>
  102. <para>
  103. To use the variable, list out the package's commands
  104. that also exist as part of another package.
  105. For example, if the <filename>busybox</filename> package
  106. has four commands that also exist as part of another
  107. package, you identify them as follows:
  108. <literallayout class='monospaced'>
  109. ALTERNATIVE_busybox = "sh sed test bracket"
  110. </literallayout>
  111. For more information on the alternatives system, see the
  112. "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
  113. section.
  114. </para>
  115. </glossdef>
  116. </glossentry>
  117. <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
  118. <info>
  119. ALTERNATIVE_LINK_NAME[doc] = "Used by the alternatives system to map duplicated commands to actual locations."
  120. </info>
  121. <glossdef>
  122. <para role="glossdeffirst">
  123. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  124. Used by the alternatives system to map duplicated commands
  125. to actual locations.
  126. For example, if the <filename>bracket</filename> command
  127. provided by the <filename>busybox</filename> package is
  128. duplicated through another package, you must use the
  129. <filename>ALTERNATIVE_LINK_NAME</filename> variable to
  130. specify the actual location:
  131. <literallayout class='monospaced'>
  132. ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
  133. </literallayout>
  134. </para>
  135. <para>
  136. In this example, the binary for the
  137. <filename>bracket</filename> command (i.e.
  138. <filename>[</filename>) from the
  139. <filename>busybox</filename> package resides in
  140. <filename>/usr/bin/</filename>.
  141. <note>
  142. If <filename>ALTERNATIVE_LINK_NAME</filename> is not
  143. defined, it defaults to
  144. <filename>${bindir}/<replaceable>name</replaceable></filename>.
  145. </note>
  146. </para>
  147. <para>
  148. For more information on the alternatives system, see the
  149. "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
  150. section.
  151. </para>
  152. </glossdef>
  153. </glossentry>
  154. <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
  155. <info>
  156. ALTERNATIVE_PRIORITY[doc] = "Used by the alternatives system to create default priorities for duplicated commands."
  157. </info>
  158. <glossdef>
  159. <para role="glossdeffirst">
  160. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  161. Used by the alternatives system to create default
  162. priorities for duplicated commands.
  163. You can use the variable to create a single default
  164. regardless of the command name or package, a default for
  165. specific duplicated commands regardless of the package, or
  166. a default for specific commands tied to particular packages.
  167. Here are the available syntax forms:
  168. <literallayout class='monospaced'>
  169. ALTERNATIVE_PRIORITY = "<replaceable>priority</replaceable>"
  170. ALTERNATIVE_PRIORITY[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
  171. ALTERNATIVE_PRIORITY_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
  172. </literallayout>
  173. </para>
  174. <para>
  175. For more information on the alternatives system, see the
  176. "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
  177. section.
  178. </para>
  179. </glossdef>
  180. </glossentry>
  181. <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
  182. <info>
  183. ALTERNATIVE_TARGET[doc] = "Used by the alternatives system to create default link locations for duplicated commands."
  184. </info>
  185. <glossdef>
  186. <para role="glossdeffirst">
  187. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  188. Used by the alternatives system to create default link
  189. locations for duplicated commands.
  190. You can use the variable to create a single default
  191. location for all duplicated commands regardless of the
  192. command name or package, a default for
  193. specific duplicated commands regardless of the package, or
  194. a default for specific commands tied to particular packages.
  195. Here are the available syntax forms:
  196. <literallayout class='monospaced'>
  197. ALTERNATIVE_TARGET = "<replaceable>target</replaceable>"
  198. ALTERNATIVE_TARGET[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
  199. ALTERNATIVE_TARGET_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
  200. </literallayout>
  201. <note>
  202. <para>
  203. If <filename>ALTERNATIVE_TARGET</filename> is not
  204. defined, it inherits the value from the
  205. <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
  206. variable.
  207. </para>
  208. <para>
  209. If <filename>ALTERNATIVE_LINK_NAME</filename> and
  210. <filename>ALTERNATIVE_TARGET</filename> are the
  211. same, the target for
  212. <filename>ALTERNATIVE_TARGET</filename>
  213. has "<filename>.{BPN}</filename>" appended to it.
  214. </para>
  215. <para>
  216. Finally, if the file referenced has not been
  217. renamed, the alternatives system will rename it to
  218. avoid the need to rename alternative files in the
  219. <link linkend='ref-tasks-install'><filename>do_install</filename></link>
  220. task while
  221. retaining support for the command if necessary.
  222. </para>
  223. </note>
  224. </para>
  225. <para>
  226. For more information on the alternatives system, see the
  227. "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
  228. section.
  229. </para>
  230. </glossdef>
  231. </glossentry>
  232. <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
  233. <info>
  234. APPEND[doc] = "An override list of append strings for each LABEL."
  235. </info>
  236. <glossdef>
  237. <para role="glossdeffirst">
  238. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  239. An override list of append strings for each
  240. <link linkend='var-LABELS'><filename>LABEL</filename></link>.
  241. </para>
  242. <para>
  243. See the
  244. <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
  245. class for more information on how this variable is used.
  246. </para>
  247. </glossdef>
  248. </glossentry>
  249. <glossentry id='var-AR'><glossterm>AR</glossterm>
  250. <info>
  251. AR[doc] = "Minimal command and arguments to run 'ar'."
  252. </info>
  253. <glossdef>
  254. <para role="glossdeffirst">
  255. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  256. The minimal command and arguments used to run
  257. <filename>ar</filename>.
  258. </para>
  259. </glossdef>
  260. </glossentry>
  261. <glossentry id='var-ARCHIVER_MODE'><glossterm>ARCHIVER_MODE</glossterm>
  262. <info>
  263. ARCHIVER_MODE[doc] = "Controls archive creation used when releasing source files."
  264. </info>
  265. <glossdef>
  266. <para role="glossdeffirst">
  267. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  268. When used with the
  269. <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
  270. class, determines the type of information used to create
  271. a released archive.
  272. You can use this variable to create archives of patched
  273. source, original source, configured source, and so forth
  274. by employing the following variable flags (varflags):
  275. <literallayout class='monospaced'>
  276. ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source
  277. # files.
  278. ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is
  279. # the default.
  280. ARCHIVER_MODE[src] = "configured" # Uses configured source files.
  281. ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and
  282. # do_patch.
  283. ARCHIVER_MODE[diff-exclude] ?= "<replaceable>file</replaceable> <replaceable>file</replaceable> ..." # Lists files and directories to
  284. # exclude from diff.
  285. ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
  286. ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
  287. ARCHIVER_MODE[srpm] = "1" # Uses RPM package files.
  288. </literallayout>
  289. For information on how the variable works, see the
  290. <filename>meta/classes/archiver.bbclass</filename> file
  291. in the
  292. <link linkend='source-directory'>Source Directory</link>.
  293. </para>
  294. </glossdef>
  295. </glossentry>
  296. <glossentry id='var-AS'><glossterm>AS</glossterm>
  297. <info>
  298. AS[doc] = "Minimal command and arguments to run the assembler."
  299. </info>
  300. <glossdef>
  301. <para role="glossdeffirst">
  302. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  303. The minimal command and arguments used to run the
  304. assembler.
  305. </para>
  306. </glossdef>
  307. </glossentry>
  308. <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
  309. <info>
  310. ASSUME_PROVIDED[doc] = "Lists recipe names (PN values) BitBake does not attempt to build."
  311. </info>
  312. <glossdef>
  313. <para role="glossdeffirst">
  314. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  315. Lists recipe names
  316. (<link linkend='var-PN'><filename>PN</filename></link>
  317. values) BitBake does not attempt to build.
  318. Instead, BitBake assumes these recipes have already been
  319. built.
  320. </para>
  321. <para>
  322. In OpenEmbedded-Core, <filename>ASSUME_PROVIDED</filename>
  323. mostly specifies native tools that should not be built.
  324. An example is <filename>git-native</filename>, which when
  325. specified, allows for the Git binary from the host to be
  326. used rather than building <filename>git-native</filename>.
  327. </para>
  328. </glossdef>
  329. </glossentry>
  330. <glossentry id='var-ASSUME_SHLIBS'><glossterm>ASSUME_SHLIBS</glossterm>
  331. <info>
  332. ASSUME_SHLIBS[doc] = Provides additional shlibs provider mapping information, which adds to or overwrites the information provided automatically by the system."
  333. </info>
  334. <glossdef>
  335. <para role="glossdeffirst">
  336. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  337. Provides additional <filename>shlibs</filename> provider
  338. mapping information, which adds to or overwrites the
  339. information provided automatically by the system.
  340. Separate multiple entries using spaces.
  341. </para>
  342. <para>
  343. As an example, use the following form to add an
  344. <filename>shlib</filename> provider of
  345. <replaceable>shlibname</replaceable> in
  346. <replaceable>packagename</replaceable> with the optional
  347. <replaceable>version</replaceable>:
  348. <literallayout class='monospaced'>
  349. <replaceable>shlibname:packagename</replaceable>[_<replaceable>version</replaceable>]
  350. </literallayout>
  351. </para>
  352. <para>
  353. Here is an example that adds a shared library named
  354. <filename>libEGL.so.1</filename> as being provided by
  355. the <filename>libegl-implementation</filename> package:
  356. <literallayout class='monospaced'>
  357. ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
  358. </literallayout>
  359. </para>
  360. </glossdef>
  361. </glossentry>
  362. <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
  363. <info>
  364. AUTHOR[doc] = "Email address used to contact the original author or authors in order to send patches and forward bugs."
  365. </info>
  366. <glossdef>
  367. <para role="glossdeffirst">
  368. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  369. The email address used to contact the original author
  370. or authors in order to send patches and forward bugs.
  371. </para>
  372. </glossdef>
  373. </glossentry>
  374. <glossentry id='var-AUTO_LIBNAME_PKGS'><glossterm>AUTO_LIBNAME_PKGS</glossterm>
  375. <info>
  376. AUTO_LIBNAME_PKGS[doc] = "Specifies which packages should be checked for libraries and renamed according to Debian library package naming."
  377. </info>
  378. <glossdef>
  379. <para role="glossdeffirst">
  380. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  381. When the
  382. <link linkend='ref-classes-debian'><filename>debian</filename></link>
  383. class is inherited, which is the default behavior,
  384. <filename>AUTO_LIBNAME_PKGS</filename> specifies which
  385. packages should be checked for libraries and renamed
  386. according to Debian library package naming.
  387. </para>
  388. <para>
  389. The default value is "${PACKAGES}", which causes the
  390. debian class to act on all packages that are
  391. explicitly generated by the recipe.
  392. </para>
  393. </glossdef>
  394. </glossentry>
  395. <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>
  396. <info>
  397. AUTO_SYSLINUXMENU[doc] = "Enables creating an automatic menu for the syslinux bootloader."
  398. </info>
  399. <glossdef>
  400. <para role="glossdeffirst">
  401. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  402. Enables creating an automatic menu for the syslinux
  403. bootloader.
  404. You must set this variable in your recipe.
  405. The
  406. <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
  407. class checks this variable.
  408. </para>
  409. </glossdef>
  410. </glossentry>
  411. <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
  412. <info>
  413. AUTOREV[doc] = "When SRCREV is set to the value of this variable, it specifies to use the latest source revision in the repository."
  414. </info>
  415. <glossdef>
  416. <para role="glossdeffirst">
  417. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  418. When
  419. <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
  420. is set to the value of this variable, it specifies to use
  421. the latest source revision in the repository.
  422. Here is an example:
  423. <literallayout class='monospaced'>
  424. SRCREV = "${AUTOREV}"
  425. </literallayout>
  426. </para>
  427. <para>
  428. If you use the previous statement to retrieve the latest
  429. version of software, you need to be sure
  430. <link linkend='var-PV'><filename>PV</filename></link>
  431. contains
  432. <filename>${</filename><link linkend='var-SRCPV'><filename>SRCPV</filename></link><filename>}</filename>.
  433. For example, suppose you have a kernel recipe that
  434. inherits the
  435. <link linkend='ref-classes-kernel'>kernel</link> class
  436. and you use the previous statement.
  437. In this example, <filename>${SRCPV}</filename> does not
  438. automatically get into <filename>PV</filename>.
  439. Consequently, you need to change <filename>PV</filename>
  440. in your recipe so that it does contain
  441. <filename>${SRCPV}</filename>.
  442. </para>
  443. <para>
  444. For more information see the
  445. "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
  446. section in the Yocto Project Development Tasks Manual.
  447. </para>
  448. </glossdef>
  449. </glossentry>
  450. <glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm>
  451. <info>
  452. AVAILTUNES[doc] = "The list of defined CPU and Application Binary Interface (ABI) tunings (i.e. "tunes") available for use by the OpenEmbedded build system."
  453. </info>
  454. <glossdef>
  455. <para role="glossdeffirst">
  456. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  457. The list of defined CPU and Application Binary Interface
  458. (ABI) tunings (i.e. "tunes") available for use by the
  459. OpenEmbedded build system.
  460. </para>
  461. <para>
  462. The list simply presents the tunes that are available.
  463. Not all tunes may be compatible with a particular
  464. machine configuration, or with each other in a
  465. <ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Multilib</ulink>
  466. configuration.
  467. </para>
  468. <para>
  469. To add a tune to the list, be sure to append it with
  470. spaces using the "+=" BitBake operator.
  471. Do not simply replace the list by using the "=" operator.
  472. See the
  473. "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
  474. section in the BitBake User Manual for more information.
  475. </para>
  476. </glossdef>
  477. </glossentry>
  478. </glossdiv>
  479. <glossdiv id='var-glossary-b'><title>B</title>
  480. <glossentry id='var-B'><glossterm>B</glossterm>
  481. <info>
  482. B[doc] = "The Build Directory. The OpenEmbedded build system places generated objects into the Build Directory during a recipe's build process."
  483. </info>
  484. <glossdef>
  485. <para role="glossdeffirst">
  486. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  487. The directory within the
  488. <link linkend='build-directory'>Build Directory</link>
  489. in which the OpenEmbedded build system places generated
  490. objects during a recipe's build process.
  491. By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
  492. directory, which is defined as:
  493. <literallayout class='monospaced'>
  494. S = "${WORKDIR}/${BP}"
  495. </literallayout>
  496. </para>
  497. <para>
  498. You can separate the (<filename>S</filename>) directory
  499. and the directory pointed to by the <filename>B</filename>
  500. variable.
  501. Most Autotools-based recipes support separating these
  502. directories.
  503. The build system defaults to using separate directories for
  504. <filename>gcc</filename> and some kernel recipes.
  505. </para>
  506. </glossdef>
  507. </glossentry>
  508. <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
  509. <info>
  510. BAD_RECOMMENDATIONS[doc] = "A list of packages not to install despite being recommended by a recipe. Support for this variable exists only when using the IPK packaging backend."
  511. </info>
  512. <glossdef>
  513. <para role="glossdeffirst">
  514. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  515. Lists "recommended-only" packages to not install.
  516. Recommended-only packages are packages installed only
  517. through the
  518. <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
  519. variable.
  520. You can prevent any of these "recommended" packages from
  521. being installed by listing them with the
  522. <filename>BAD_RECOMMENDATIONS</filename> variable:
  523. <literallayout class='monospaced'>
  524. BAD_RECOMMENDATIONS = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
  525. </literallayout>
  526. </para>
  527. <para>
  528. You can set this variable globally in your
  529. <filename>local.conf</filename> file or you can attach it to
  530. a specific image recipe by using the recipe name override:
  531. <literallayout class='monospaced'>
  532. BAD_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
  533. </literallayout>
  534. </para>
  535. <para>
  536. It is important to realize that if you choose to not install
  537. packages using this variable and some other packages are
  538. dependent on them (i.e. listed in a recipe's
  539. <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
  540. variable), the OpenEmbedded build system ignores your
  541. request and will install the packages to avoid dependency
  542. errors.
  543. </para>
  544. <para>
  545. Support for this variable exists only when using the
  546. IPK and RPM packaging backend.
  547. Support does not exist for DEB.
  548. </para>
  549. <para>
  550. See the
  551. <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
  552. and the
  553. <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
  554. variables for related information.
  555. </para>
  556. </glossdef>
  557. </glossentry>
  558. <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm>
  559. <info>
  560. BASE_LIB[doc] = "The library directory name for the CPU or Application Binary Interface (ABI) tune."
  561. </info>
  562. <glossdef>
  563. <para role="glossdeffirst">
  564. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  565. The library directory name for the CPU or Application
  566. Binary Interface (ABI) tune.
  567. The <filename>BASE_LIB</filename> applies only in the
  568. Multilib context.
  569. See the
  570. "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
  571. section in the Yocto Project Development Tasks Manual for
  572. information on Multilib.
  573. </para>
  574. <para>
  575. The <filename>BASE_LIB</filename> variable is defined in
  576. the machine include files in the
  577. <link linkend='source-directory'>Source Directory</link>.
  578. If Multilib is not being used, the value defaults to "lib".
  579. </para>
  580. </glossdef>
  581. </glossentry>
  582. <glossentry id='var-BASE_WORKDIR'><glossterm>BASE_WORKDIR</glossterm>
  583. <info>
  584. BASE_WORKDIR[doc] = "Points to the base of the work directory for all recipes."
  585. </info>
  586. <glossdef>
  587. <para role="glossdeffirst">
  588. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  589. Points to the base of the work directory for all recipes.
  590. The default value is "${TMPDIR}/work".
  591. </para>
  592. </glossdef>
  593. </glossentry>
  594. <glossentry id='var-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm>
  595. <info>
  596. BB_ALLOWED_NETWORKS[doc] = "A list of hosts that the fetcher is allowed to use to obtain the required source code."
  597. </info>
  598. <glossdef>
  599. <para>
  600. Specifies a space-delimited list of hosts that the fetcher
  601. is allowed to use to obtain the required source code.
  602. Following are considerations surrounding this variable:
  603. <itemizedlist>
  604. <listitem><para>
  605. This host list is only used if
  606. <filename>BB_NO_NETWORK</filename> is either not
  607. set or set to "0".
  608. </para></listitem>
  609. <listitem><para>
  610. Limited support for wildcard matching against the
  611. beginning of host names exists.
  612. For example, the following setting matches
  613. <filename>git.gnu.org</filename>,
  614. <filename>ftp.gnu.org</filename>, and
  615. <filename>foo.git.gnu.org</filename>.
  616. <literallayout class='monospaced'>
  617. BB_ALLOWED_NETWORKS = "*.gnu.org"
  618. </literallayout>
  619. </para></listitem>
  620. <listitem><para>
  621. Mirrors not in the host list are skipped and
  622. logged in debug.
  623. </para></listitem>
  624. <listitem><para>
  625. Attempts to access networks not in the host list
  626. cause a failure.
  627. </para></listitem>
  628. </itemizedlist>
  629. Using <filename>BB_ALLOWED_NETWORKS</filename> in
  630. conjunction with
  631. <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
  632. is very useful.
  633. Adding the host you want to use to
  634. <filename>PREMIRRORS</filename> results in the source code
  635. being fetched from an allowed location and avoids raising
  636. an error when a host that is not allowed is in a
  637. <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
  638. statement.
  639. This is because the fetcher does not attempt to use the
  640. host listed in <filename>SRC_URI</filename> after a
  641. successful fetch from the
  642. <filename>PREMIRRORS</filename> occurs.
  643. </para>
  644. </glossdef>
  645. </glossentry>
  646. <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
  647. <info>
  648. BB_DANGLINGAPPENDS_WARNONLY[doc] = "Defines how BitBake handles situations where an append file (.bbappend) has no corresponding recipe file (.bb)."
  649. </info>
  650. <glossdef>
  651. <para role="glossdeffirst">
  652. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  653. Defines how BitBake handles situations where an append
  654. file (<filename>.bbappend</filename>) has no
  655. corresponding recipe file (<filename>.bb</filename>).
  656. This condition often occurs when layers get out of sync
  657. (e.g. <filename>oe-core</filename> bumps a
  658. recipe version and the old recipe no longer exists and the
  659. other layer has not been updated to the new version
  660. of the recipe yet).
  661. </para>
  662. <para>
  663. The default fatal behavior is safest because it is
  664. the sane reaction given something is out of sync.
  665. It is important to realize when your changes are no longer
  666. being applied.
  667. </para>
  668. <para>
  669. You can change the default behavior by setting this
  670. variable to "1", "yes", or "true"
  671. in your <filename>local.conf</filename> file, which is
  672. located in the
  673. <link linkend='build-directory'>Build Directory</link>:
  674. Here is an example:
  675. <literallayout class='monospaced'>
  676. BB_DANGLINGAPPENDS_WARNONLY = "1"
  677. </literallayout>
  678. </para>
  679. </glossdef>
  680. </glossentry>
  681. <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
  682. <info>
  683. BB_DISKMON_DIRS[doc] = "Monitors disk space and available inodes during the build and allows you to control the build based on these parameters."
  684. </info>
  685. <glossdef>
  686. <para role="glossdeffirst">
  687. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  688. Monitors disk space and available inodes during the build
  689. and allows you to control the build based on these
  690. parameters.
  691. </para>
  692. <para>
  693. Disk space monitoring is disabled by default.
  694. To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
  695. variable to your <filename>conf/local.conf</filename> file found in the
  696. <link linkend='build-directory'>Build Directory</link>.
  697. Use the following form:
  698. <literallayout class='monospaced'>
  699. BB_DISKMON_DIRS = "<replaceable>action</replaceable>,<replaceable>dir</replaceable>,<replaceable>threshold</replaceable> [...]"
  700. where:
  701. <replaceable>action</replaceable> is:
  702. ABORT: Immediately abort the build when
  703. a threshold is broken.
  704. STOPTASKS: Stop the build after the currently
  705. executing tasks have finished when
  706. a threshold is broken.
  707. WARN: Issue a warning but continue the
  708. build when a threshold is broken.
  709. Subsequent warnings are issued as
  710. defined by the
  711. <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
  712. which must be defined in the
  713. conf/local.conf file.
  714. <replaceable>dir</replaceable> is:
  715. Any directory you choose. You can specify one or
  716. more directories to monitor by separating the
  717. groupings with a space. If two directories are
  718. on the same device, only the first directory
  719. is monitored.
  720. <replaceable>threshold</replaceable> is:
  721. Either the minimum available disk space,
  722. the minimum number of free inodes, or
  723. both. You must specify at least one. To
  724. omit one or the other, simply omit the value.
  725. Specify the threshold using G, M, K for Gbytes,
  726. Mbytes, and Kbytes, respectively. If you do
  727. not specify G, M, or K, Kbytes is assumed by
  728. default. Do not use GB, MB, or KB.
  729. </literallayout>
  730. </para>
  731. <para>
  732. Here are some examples:
  733. <literallayout class='monospaced'>
  734. BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
  735. BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
  736. BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
  737. </literallayout>
  738. The first example works only if you also provide
  739. the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
  740. in the <filename>conf/local.conf</filename>.
  741. This example causes the build system to immediately
  742. abort when either the disk space in <filename>${TMPDIR}</filename> drops
  743. below 1 Gbyte or the available free inodes drops below
  744. 100 Kbytes.
  745. Because two directories are provided with the variable, the
  746. build system also issue a
  747. warning when the disk space in the
  748. <filename>${SSTATE_DIR}</filename> directory drops
  749. below 1 Gbyte or the number of free inodes drops
  750. below 100 Kbytes.
  751. Subsequent warnings are issued during intervals as
  752. defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
  753. variable.
  754. </para>
  755. <para>
  756. The second example stops the build after all currently
  757. executing tasks complete when the minimum disk space
  758. in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
  759. directory drops below 1 Gbyte.
  760. No disk monitoring occurs for the free inodes in this case.
  761. </para>
  762. <para>
  763. The final example immediately aborts the build when the
  764. number of free inodes in the <filename>${TMPDIR}</filename> directory
  765. drops below 100 Kbytes.
  766. No disk space monitoring for the directory itself occurs
  767. in this case.
  768. </para>
  769. </glossdef>
  770. </glossentry>
  771. <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
  772. <info>
  773. BB_DISKMON_WARNINTERVAL[doc] = "Defines the disk space and free inode warning intervals. To set these intervals, define the variable in the conf/local.conf file in the Build Directory."
  774. </info>
  775. <glossdef>
  776. <para role="glossdeffirst">
  777. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  778. Defines the disk space and free inode warning intervals.
  779. To set these intervals, define the variable in your
  780. <filename>conf/local.conf</filename> file in the
  781. <link linkend='build-directory'>Build Directory</link>.
  782. </para>
  783. <para>
  784. If you are going to use the
  785. <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
  786. also use the
  787. <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
  788. and define its action as "WARN".
  789. During the build, subsequent warnings are issued each time
  790. disk space or number of free inodes further reduces by
  791. the respective interval.
  792. </para>
  793. <para>
  794. If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
  795. variable and you do use <filename>BB_DISKMON_DIRS</filename> with
  796. the "WARN" action, the disk monitoring interval defaults to
  797. the following:
  798. <literallayout class='monospaced'>
  799. BB_DISKMON_WARNINTERVAL = "50M,5K"
  800. </literallayout>
  801. </para>
  802. <para>
  803. When specifying the variable in your configuration file,
  804. use the following form:
  805. <literallayout class='monospaced'>
  806. BB_DISKMON_WARNINTERVAL = "<replaceable>disk_space_interval</replaceable>,<replaceable>disk_inode_interval</replaceable>"
  807. where:
  808. <replaceable>disk_space_interval</replaceable> is:
  809. An interval of memory expressed in either
  810. G, M, or K for Gbytes, Mbytes, or Kbytes,
  811. respectively. You cannot use GB, MB, or KB.
  812. <replaceable>disk_inode_interval</replaceable> is:
  813. An interval of free inodes expressed in either
  814. G, M, or K for Gbytes, Mbytes, or Kbytes,
  815. respectively. You cannot use GB, MB, or KB.
  816. </literallayout>
  817. </para>
  818. <para>
  819. Here is an example:
  820. <literallayout class='monospaced'>
  821. BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
  822. BB_DISKMON_WARNINTERVAL = "50M,5K"
  823. </literallayout>
  824. These variables cause the OpenEmbedded build system to
  825. issue subsequent warnings each time the available
  826. disk space further reduces by 50 Mbytes or the number
  827. of free inodes further reduces by 5 Kbytes in the
  828. <filename>${SSTATE_DIR}</filename> directory.
  829. Subsequent warnings based on the interval occur each time
  830. a respective interval is reached beyond the initial warning
  831. (i.e. 1 Gbytes and 100 Kbytes).
  832. </para>
  833. </glossdef>
  834. </glossentry>
  835. <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
  836. <info>
  837. BB_GENERATE_MIRROR_TARBALLS[doc] = "Causes tarballs of the Git repositories to be placed in the DL_DIR directory."
  838. </info>
  839. <glossdef>
  840. <para role="glossdeffirst">
  841. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  842. Causes tarballs of the Git repositories, including the
  843. Git metadata, to be placed in the
  844. <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
  845. directory.
  846. </para>
  847. <para>
  848. For performance reasons, creating and placing tarballs of
  849. the Git repositories is not the default action by the
  850. OpenEmbedded build system.
  851. <literallayout class='monospaced'>
  852. BB_GENERATE_MIRROR_TARBALLS = "1"
  853. </literallayout>
  854. Set this variable in your <filename>local.conf</filename>
  855. file in the
  856. <link linkend='build-directory'>Build Directory</link>.
  857. </para>
  858. </glossdef>
  859. </glossentry>
  860. <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
  861. <info>
  862. BB_NUMBER_THREADS[doc] = "The maximum number of tasks BitBake should run in parallel at any one time. This variable is automatically configured to be equal to the number of build system cores."
  863. </info>
  864. <glossdef>
  865. <para role="glossdeffirst">
  866. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  867. The maximum number of tasks BitBake should run in parallel
  868. at any one time.
  869. The OpenEmbedded build system automatically configures
  870. this variable to be equal to the number of cores on the
  871. build system.
  872. For example, a system with a dual core processor that
  873. also uses hyper-threading causes the
  874. <filename>BB_NUMBER_THREADS</filename> variable to default
  875. to "4".
  876. </para>
  877. <para>
  878. For single socket systems (i.e. one CPU), you should not
  879. have to override this variable to gain optimal parallelism
  880. during builds.
  881. However, if you have very large systems that employ
  882. multiple physical CPUs, you might want to make sure the
  883. <filename>BB_NUMBER_THREADS</filename> variable is not
  884. set higher than "20".
  885. </para>
  886. <para>
  887. For more information on speeding up builds, see the
  888. "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-the-build'>Speeding Up the Build</ulink>"
  889. section in the Yocto Project Development Tasks Manual.
  890. </para>
  891. </glossdef>
  892. </glossentry>
  893. <glossentry id='var-BB_SERVER_TIMEOUT'><glossterm>BB_SERVER_TIMEOUT</glossterm>
  894. <info>
  895. BB_SERVER_TIMEOUT [doc] = "Specifies the time (in seconds) after which to unload the BitBake server due to inactivity."
  896. </info>
  897. <glossdef>
  898. <para role="glossdeffirst">
  899. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  900. Specifies the time (in seconds) after which to unload the
  901. BitBake server due to inactivity.
  902. Set <filename>BB_SERVER_TIMEOUT</filename> to determine how
  903. long the BitBake server stays resident between invocations.
  904. </para>
  905. <para>
  906. For example, the following statement in your
  907. <filename>local.conf</filename> file instructs the server
  908. to be unloaded after 20 seconds of inactivity:
  909. <literallayout class='monospaced'>
  910. BB_SERVER_TIMEOUT = "20"
  911. </literallayout>
  912. If you want the server to never be unloaded, set
  913. <filename>BB_SERVER_TIMEOUT</filename> to "-1".
  914. </para>
  915. </glossdef>
  916. </glossentry>
  917. <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
  918. <info>
  919. BBCLASSEXTEND[doc] = "Allows you to extend a recipe so that it builds variants of the software. Common variants for recipes are 'native', 'cross', 'nativesdk', and multilibs."
  920. </info>
  921. <glossdef>
  922. <para role="glossdeffirst">
  923. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  924. Allows you to extend a recipe so that it builds variants of the software.
  925. Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
  926. which is a copy of Quilt built to run on the build system;
  927. "crosses" such as <filename>gcc-cross</filename>,
  928. which is a compiler built to run on the build machine but produces binaries
  929. that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
  930. "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
  931. and "mulitlibs" in the form "<filename>multilib:</filename><replaceable>multilib_name</replaceable>".
  932. </para>
  933. <para>
  934. To build a different variant of the recipe with a minimal amount of code, it usually
  935. is as simple as adding the following to your recipe:
  936. <literallayout class='monospaced'>
  937. BBCLASSEXTEND =+ "native nativesdk"
  938. BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>"
  939. </literallayout>
  940. <note>
  941. <para>
  942. Internally, the <filename>BBCLASSEXTEND</filename>
  943. mechanism generates recipe variants by rewriting
  944. variable values and applying overrides such as
  945. <filename>_class-native</filename>.
  946. For example, to generate a native version of a recipe,
  947. a
  948. <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
  949. on "foo" is rewritten to a <filename>DEPENDS</filename>
  950. on "foo-native".
  951. </para>
  952. <para>
  953. Even when using <filename>BBCLASSEXTEND</filename>, the
  954. recipe is only parsed once.
  955. Parsing once adds some limitations.
  956. For example, it is not possible to
  957. include a different file depending on the variant,
  958. since <filename>include</filename> statements are
  959. processed when the recipe is parsed.
  960. </para>
  961. </note>
  962. </para>
  963. </glossdef>
  964. </glossentry>
  965. <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
  966. <info>
  967. BBFILE_COLLECTIONS[doc] = "Lists the names of configured layers. These names are used to find the other BBFILE_* variables."
  968. </info>
  969. <glossdef>
  970. <para role="glossdeffirst">
  971. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  972. Lists the names of configured layers.
  973. These names are used to find the other <filename>BBFILE_*</filename>
  974. variables.
  975. Typically, each layer will append its name to this variable in its
  976. <filename>conf/layer.conf</filename> file.
  977. </para>
  978. </glossdef>
  979. </glossentry>
  980. <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
  981. <info>
  982. BBFILE_PATTERN[doc] = "Variable that expands to match files from BBFILES in a particular layer. This variable is used in the layer.conf file and must be suffixed with the name of a layer."
  983. </info>
  984. <glossdef>
  985. <para role="glossdeffirst">
  986. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  987. Variable that expands to match files from
  988. <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
  989. in a particular layer.
  990. This variable is used in the <filename>conf/layer.conf</filename> file and must
  991. be suffixed with the name of the specific layer (e.g.
  992. <filename>BBFILE_PATTERN_emenlow</filename>).
  993. </para>
  994. </glossdef>
  995. </glossentry>
  996. <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
  997. <info>
  998. BBFILE_PRIORITY[doc] = "Assigns the priority for recipe files in each layer. Setting this variable allows you to prioritize a layer against other layers that contain the same recipe."
  999. </info>
  1000. <glossdef>
  1001. <para role="glossdeffirst">
  1002. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1003. Assigns the priority for recipe files in each layer.
  1004. </para>
  1005. <para>
  1006. This variable is useful in situations where the same recipe appears in
  1007. more than one layer.
  1008. Setting this variable allows you to prioritize a
  1009. layer against other layers that contain the same recipe - effectively
  1010. letting you control the precedence for the multiple layers.
  1011. The precedence established through this variable stands regardless of a
  1012. recipe's version
  1013. (<link linkend='var-PV'><filename>PV</filename></link> variable).
  1014. For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
  1015. which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
  1016. lower precedence.
  1017. </para>
  1018. <para>
  1019. A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
  1020. precedence.
  1021. For example, the value 6 has a higher precedence than the value 5.
  1022. If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
  1023. dependencies (see the
  1024. <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
  1025. more information.
  1026. The default priority, if unspecified
  1027. for a layer with no dependencies, is the lowest defined priority + 1
  1028. (or 1 if no priorities are defined).
  1029. </para>
  1030. <tip>
  1031. You can use the command <filename>bitbake-layers show-layers</filename> to list
  1032. all configured layers along with their priorities.
  1033. </tip>
  1034. </glossdef>
  1035. </glossentry>
  1036. <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
  1037. <info>
  1038. BBFILES[doc] = "List of recipe files used by BitBake to build software."
  1039. </info>
  1040. <glossdef>
  1041. <para role="glossdeffirst">
  1042. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1043. List of recipe files used by BitBake to build software.
  1044. </para>
  1045. </glossdef>
  1046. </glossentry>
  1047. <glossentry id='var-BBFILES_DYNAMIC'><glossterm>BBFILES_DYNAMIC</glossterm>
  1048. <info>
  1049. BBFILES_DYNAMIC[doc] = "Activates content when identified layers are present."
  1050. </info>
  1051. <glossdef>
  1052. <para role="glossdeffirst">
  1053. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1054. Activates content when identified layers are present.
  1055. You identify the layers by the collections that the layers
  1056. define.
  1057. </para>
  1058. <para>
  1059. Use the <filename>BBFILES_DYNAMIC</filename> variable to
  1060. avoid <filename>.bbappend</filename> files whose
  1061. corresponding <filename>.bb</filename> file is in a layer
  1062. that attempts to modify other layers through
  1063. <filename>.bbappend</filename> but does not want to
  1064. introduce a hard dependency on those other layers.
  1065. </para>
  1066. <para>
  1067. Use the following form for
  1068. <filename>BBFILES_DYNAMIC</filename>:
  1069. <literallayout class='monospaced'>
  1070. <replaceable>collection_name</replaceable>:<replaceable>filename_pattern</replaceable>
  1071. </literallayout>
  1072. The following example identifies two collection names and
  1073. two filename patterns:
  1074. <literallayout class='monospaced'>
  1075. BBFILES_DYNAMIC += " \
  1076. clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
  1077. core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
  1078. "
  1079. </literallayout>
  1080. This next example shows an error message that occurs
  1081. because invalid entries are found, which cause parsing to
  1082. abort:
  1083. <literallayout class='monospaced'>
  1084. ERROR: BBFILES_DYNAMIC entries must be of the form &lt;collection name&gt;:&lt;filename pattern&gt;, not:
  1085. /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
  1086. /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
  1087. </literallayout>
  1088. </para>
  1089. </glossdef>
  1090. </glossentry>
  1091. <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
  1092. <info>
  1093. BBINCLUDELOGS[doc] = "Variable that controls how BitBake displays logs on build failure."
  1094. </info>
  1095. <glossdef>
  1096. <para role="glossdeffirst">
  1097. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1098. Variable that controls how BitBake displays logs on build failure.
  1099. </para>
  1100. </glossdef>
  1101. </glossentry>
  1102. <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
  1103. <info>
  1104. BBINCLUDELOGS_LINES[doc] = "Amount of log lines printed on failure."
  1105. </info>
  1106. <glossdef>
  1107. <para role="glossdeffirst">
  1108. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1109. If
  1110. <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
  1111. is set, specifies the maximum number of lines from the
  1112. task log file to print when reporting a failed task.
  1113. If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
  1114. the entire log is printed.
  1115. </para>
  1116. </glossdef>
  1117. </glossentry>
  1118. <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
  1119. <info>
  1120. BBLAYERS[doc] = "Lists the layers to enable during the build. This variable is defined in the bblayers.conf configuration file."
  1121. </info>
  1122. <glossdef>
  1123. <para role="glossdeffirst">
  1124. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1125. Lists the layers to enable during the build.
  1126. This variable is defined in the <filename>bblayers.conf</filename> configuration
  1127. file in the
  1128. <link linkend='build-directory'>Build Directory</link>.
  1129. Here is an example:
  1130. <literallayout class='monospaced'>
  1131. BBLAYERS = " \
  1132. /home/scottrif/poky/meta \
  1133. /home/scottrif/poky/meta-poky \
  1134. /home/scottrif/poky/meta-yocto-bsp \
  1135. /home/scottrif/poky/meta-mykernel \
  1136. "
  1137. </literallayout>
  1138. </para>
  1139. <para>
  1140. This example enables four layers, one of which is a custom, user-defined layer
  1141. named <filename>meta-mykernel</filename>.
  1142. </para>
  1143. </glossdef>
  1144. </glossentry>
  1145. <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
  1146. <info>
  1147. BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files."
  1148. </info>
  1149. <glossdef>
  1150. <para role="glossdeffirst">
  1151. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1152. Prevents BitBake from processing recipes and recipe
  1153. append files.
  1154. </para>
  1155. <para>
  1156. You can use the <filename>BBMASK</filename> variable
  1157. to "hide" these <filename>.bb</filename> and
  1158. <filename>.bbappend</filename> files.
  1159. BitBake ignores any recipe or recipe append files that
  1160. match any of the expressions.
  1161. It is as if BitBake does not see them at all.
  1162. Consequently, matching files are not parsed or otherwise
  1163. used by BitBake.</para>
  1164. <para>
  1165. The values you provide are passed to Python's regular
  1166. expression compiler.
  1167. The expressions are compared against the full paths to
  1168. the files.
  1169. For complete syntax information, see Python's
  1170. documentation at
  1171. <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
  1172. </para>
  1173. <para>
  1174. The following example uses a complete regular expression
  1175. to tell BitBake to ignore all recipe and recipe append
  1176. files in the <filename>meta-ti/recipes-misc/</filename>
  1177. directory:
  1178. <literallayout class='monospaced'>
  1179. BBMASK = "meta-ti/recipes-misc/"
  1180. </literallayout>
  1181. If you want to mask out multiple directories or recipes,
  1182. you can specify multiple regular expression fragments.
  1183. This next example masks out multiple directories and
  1184. individual recipes:
  1185. <literallayout class='monospaced'>
  1186. BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
  1187. BBMASK += "/meta-oe/recipes-support/"
  1188. BBMASK += "/meta-foo/.*/openldap"
  1189. BBMASK += "opencv.*\.bbappend"
  1190. BBMASK += "lzma"
  1191. </literallayout>
  1192. <note>
  1193. When specifying a directory name, use the trailing
  1194. slash character to ensure you match just that directory
  1195. name.
  1196. </note>
  1197. </para>
  1198. </glossdef>
  1199. </glossentry>
  1200. <glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm>
  1201. <info>
  1202. BBMULTICONFIG[doc] = "Specifies each separate configuration when you are building targets with multiple configurations."
  1203. </info>
  1204. <glossdef>
  1205. <para role="glossdeffirst">
  1206. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1207. Specifies each separate configuration when you are
  1208. building targets with multiple configurations.
  1209. Use this variable in your
  1210. <filename>conf/local.conf</filename> configuration file.
  1211. Specify a <replaceable>multiconfigname</replaceable> for
  1212. each configuration file you are using.
  1213. For example, the following line specifies three
  1214. configuration files:
  1215. <literallayout class='monospaced'>
  1216. BBMULTIFONFIG = "configA configB configC"
  1217. </literallayout>
  1218. Each configuration file you use must reside in the
  1219. <link linkend='build-directory'>Build Directory</link>
  1220. <filename>conf/multiconfig</filename> directory
  1221. (e.g.
  1222. <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>).
  1223. </para>
  1224. <para>
  1225. For information on how to use
  1226. <filename>BBMULTICONFIG</filename> in an environment that
  1227. supports building targets with multiple configurations,
  1228. see the
  1229. "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-building-targets-with-multiple-configurations'>Building Targets with Multiple Configurations</ulink>"
  1230. section in the Yocto Project Development Tasks Manual.
  1231. </para>
  1232. </glossdef>
  1233. </glossentry>
  1234. <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
  1235. <info>
  1236. BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable."
  1237. </info>
  1238. <glossdef>
  1239. <para role="glossdeffirst">
  1240. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1241. Used by BitBake to locate
  1242. <filename>.bbclass</filename> and configuration files.
  1243. This variable is analogous to the
  1244. <filename>PATH</filename> variable.
  1245. <note>
  1246. If you run BitBake from a directory outside of the
  1247. <link linkend='build-directory'>Build Directory</link>,
  1248. you must be sure to set
  1249. <filename>BBPATH</filename> to point to the
  1250. Build Directory.
  1251. Set the variable as you would any environment variable
  1252. and then run BitBake:
  1253. <literallayout class='monospaced'>
  1254. $ BBPATH = "<replaceable>build_directory</replaceable>"
  1255. $ export BBPATH
  1256. $ bitbake <replaceable>target</replaceable>
  1257. </literallayout>
  1258. </note>
  1259. </para>
  1260. </glossdef>
  1261. </glossentry>
  1262. <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
  1263. <info>
  1264. BBSERVER[doc] = "Points to the BitBake remote server."
  1265. </info>
  1266. <glossdef>
  1267. <para role="glossdeffirst">
  1268. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1269. If defined in the BitBake environment,
  1270. <filename>BBSERVER</filename> points to the BitBake
  1271. remote server.
  1272. </para>
  1273. <para>
  1274. Use the following format to export the variable to the
  1275. BitBake environment:
  1276. <literallayout class='monospaced'>
  1277. export BBSERVER=localhost:$port"
  1278. </literallayout>
  1279. </para>
  1280. <para>
  1281. By default, <filename>BBSERVER</filename> also appears in
  1282. <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>.
  1283. Consequently, <filename>BBSERVER</filename> is excluded
  1284. from checksum and dependency data.
  1285. </para>
  1286. </glossdef>
  1287. </glossentry>
  1288. <glossentry id='var-BINCONFIG'><glossterm>BINCONFIG</glossterm>
  1289. <info>
  1290. BINCONFIG[doc] = "When inheriting the binconfig-disabled class, this variable specifies binary configuration scripts to disable in favor of using pkg-config to query the information."
  1291. </info>
  1292. <glossdef>
  1293. <para role="glossdeffirst">
  1294. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1295. When inheriting the
  1296. <link linkend='ref-classes-binconfig-disabled'><filename>binconfig-disabled</filename></link>
  1297. class, this variable specifies binary configuration
  1298. scripts to disable in favor of using
  1299. <filename>pkg-config</filename> to query the information.
  1300. The <filename>binconfig-disabled</filename> class will
  1301. modify the specified scripts to return an error so that
  1302. calls to them can be easily found and replaced.
  1303. </para>
  1304. <para>
  1305. To add multiple scripts, separate them by spaces.
  1306. Here is an example from the <filename>libpng</filename>
  1307. recipe:
  1308. <literallayout class='monospaced'>
  1309. BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
  1310. </literallayout>
  1311. </para>
  1312. </glossdef>
  1313. </glossentry>
  1314. <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
  1315. <info>
  1316. BINCONFIG_GLOB[doc] = "When inheriting binconfig.bbclass from a recipe, this variable specifies a wildcard for configuration scripts that need editing."
  1317. </info>
  1318. <glossdef>
  1319. <para role="glossdeffirst">
  1320. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1321. When inheriting the
  1322. <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
  1323. class, this variable specifies a wildcard for
  1324. configuration scripts that need editing.
  1325. The scripts are edited to correct any paths that have been
  1326. set up during compilation so that they are correct for
  1327. use when installed into the sysroot and called by the
  1328. build processes of other recipes.
  1329. </para>
  1330. <para>
  1331. For more information on how this variable works, see
  1332. <filename>meta/classes/binconfig.bbclass</filename> in the
  1333. <link linkend='source-directory'>Source Directory</link>.
  1334. You can also find general information on the class in the
  1335. "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
  1336. section.
  1337. </para>
  1338. </glossdef>
  1339. </glossentry>
  1340. <glossentry id='var-BP'><glossterm>BP</glossterm>
  1341. <info>
  1342. BP[doc] = "The base recipe name and version but without any special recipe name suffix (i.e. -native, lib64-, and so forth). BP is comprised of ${BPN}-${PV}"
  1343. </info>
  1344. <glossdef>
  1345. <para role="glossdeffirst">
  1346. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1347. The base recipe name and version but without any special
  1348. recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
  1349. and so forth).
  1350. <filename>BP</filename> is comprised of the following:
  1351. <literallayout class="monospaced">
  1352. ${BPN}-${PV}
  1353. </literallayout>
  1354. </para>
  1355. </glossdef>
  1356. </glossentry>
  1357. <glossentry id='var-BPN'><glossterm>BPN</glossterm>
  1358. <info>
  1359. BPN[doc] = "This variable is a version of the PN variable but removes common suffixes and prefixes."
  1360. </info>
  1361. <glossdef>
  1362. <para role="glossdeffirst">
  1363. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1364. This variable is a version of the
  1365. <link linkend='var-PN'><filename>PN</filename></link>
  1366. variable with common prefixes and suffixes
  1367. removed, such as <filename>nativesdk-</filename>,
  1368. <filename>-cross</filename>,
  1369. <filename>-native</filename>, and multilib's
  1370. <filename>lib64-</filename> and
  1371. <filename>lib32-</filename>.
  1372. The exact lists of prefixes and suffixes removed are
  1373. specified by the
  1374. <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link>
  1375. and
  1376. <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link>
  1377. variables, respectively.
  1378. </para>
  1379. </glossdef>
  1380. </glossentry>
  1381. <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
  1382. <info>
  1383. BUGTRACKER[doc] = "Specifies a URL for an upstream bug tracking website for a recipe."
  1384. </info>
  1385. <glossdef>
  1386. <para role="glossdeffirst">
  1387. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1388. Specifies a URL for an upstream bug tracking website for
  1389. a recipe.
  1390. The OpenEmbedded build system does not use this variable.
  1391. Rather, the variable is a useful pointer in case a bug
  1392. in the software being built needs to be manually reported.
  1393. </para>
  1394. </glossdef>
  1395. </glossentry>
  1396. <glossentry id='var-BUILD_ARCH'><glossterm>BUILD_ARCH</glossterm>
  1397. <info>
  1398. BUILD_ARCH[doc] = "The name of the building architecture (e.g. i686)."
  1399. </info>
  1400. <glossdef>
  1401. <para role="glossdeffirst">
  1402. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1403. Specifies the architecture of the build host
  1404. (e.g. <filename>i686</filename>).
  1405. The OpenEmbedded build system sets the value of
  1406. <filename>BUILD_ARCH</filename> from the machine name
  1407. reported by the <filename>uname</filename> command.
  1408. </para>
  1409. </glossdef>
  1410. </glossentry>
  1411. <glossentry id='var-BUILD_AS_ARCH'><glossterm>BUILD_AS_ARCH</glossterm>
  1412. <info>
  1413. BUILD_AS_ARCH[doc] = "Specifies the architecture-specific assembler flags for the build host."
  1414. </info>
  1415. <glossdef>
  1416. <para role="glossdeffirst">
  1417. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1418. Specifies the architecture-specific assembler flags for
  1419. the build host. By default, the value of
  1420. <filename>BUILD_AS_ARCH</filename> is empty.
  1421. </para>
  1422. </glossdef>
  1423. </glossentry>
  1424. <glossentry id='var-BUILD_CC_ARCH'><glossterm>BUILD_CC_ARCH</glossterm>
  1425. <info>
  1426. BUILD_CC_ARCH[doc] = "Specifies the architecture-specific C compiler flags for the build host."
  1427. </info>
  1428. <glossdef>
  1429. <para role="glossdeffirst">
  1430. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1431. Specifies the architecture-specific C compiler flags for
  1432. the build host. By default, the value of
  1433. <filename>BUILD_CC_ARCH</filename> is empty.
  1434. </para>
  1435. </glossdef>
  1436. </glossentry>
  1437. <glossentry id='var-BUILD_CCLD'><glossterm>BUILD_CCLD</glossterm>
  1438. <info>
  1439. BUILD_CCLD[doc] = "Specifies the linker command to be used for the build host when the C compiler is being used as the linker."
  1440. </info>
  1441. <glossdef>
  1442. <para role="glossdeffirst">
  1443. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1444. Specifies the linker command to be used for the build host
  1445. when the C compiler is being used as the linker. By default,
  1446. <filename>BUILD_CCLD</filename> points to GCC and passes as
  1447. arguments the value of
  1448. <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
  1449. assuming <filename>BUILD_CC_ARCH</filename> is set.
  1450. </para>
  1451. </glossdef>
  1452. </glossentry>
  1453. <glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm>
  1454. <info>
  1455. BUILD_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the build host."
  1456. </info>
  1457. <glossdef>
  1458. <para role="glossdeffirst">
  1459. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1460. Specifies the flags to pass to the C compiler when building
  1461. for the build host.
  1462. When building in the <filename>-native</filename> context,
  1463. <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
  1464. is set to the value of this variable by default.
  1465. </para>
  1466. </glossdef>
  1467. </glossentry>
  1468. <glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm>
  1469. <info>
  1470. BUILD_CPPFLAGS[doc] = "Specifies the flags to pass to the C preprocessor (i.e. to both the C and the C++ compilers) when building for the build host."
  1471. </info>
  1472. <glossdef>
  1473. <para role="glossdeffirst">
  1474. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1475. Specifies the flags to pass to the C preprocessor
  1476. (i.e. to both the C and the C++ compilers) when building
  1477. for the build host.
  1478. When building in the <filename>-native</filename> context,
  1479. <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
  1480. is set to the value of this variable by default.
  1481. </para>
  1482. </glossdef>
  1483. </glossentry>
  1484. <glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm>
  1485. <info>
  1486. BUILD_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the build host."
  1487. </info>
  1488. <glossdef>
  1489. <para role="glossdeffirst">
  1490. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1491. Specifies the flags to pass to the C++ compiler when
  1492. building for the build host.
  1493. When building in the <filename>-native</filename> context,
  1494. <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
  1495. is set to the value of this variable by default.
  1496. </para>
  1497. </glossdef>
  1498. </glossentry>
  1499. <glossentry id='var-BUILD_FC'><glossterm>BUILD_FC</glossterm>
  1500. <info>
  1501. BUILD_FC[doc] = "Specifies the Fortran compiler command for the build host."
  1502. </info>
  1503. <glossdef>
  1504. <para role="glossdeffirst">
  1505. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1506. Specifies the Fortran compiler command for the build host.
  1507. By default, <filename>BUILD_FC</filename> points to
  1508. Gfortran and passes as arguments the value of
  1509. <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
  1510. assuming <filename>BUILD_CC_ARCH</filename> is set.
  1511. </para>
  1512. </glossdef>
  1513. </glossentry>
  1514. <glossentry id='var-BUILD_LD'><glossterm>BUILD_LD</glossterm>
  1515. <info>
  1516. BUILD_LD[doc] = "Specifies the linker command for the build host."
  1517. </info>
  1518. <glossdef>
  1519. <para role="glossdeffirst">
  1520. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1521. Specifies the linker command for the build host. By default,
  1522. <filename>BUILD_LD</filename> points to the GNU linker (ld)
  1523. and passes as arguments the value of
  1524. <link linkend='var-BUILD_LD_ARCH'><filename>BUILD_LD_ARCH</filename></link>,
  1525. assuming <filename>BUILD_LD_ARCH</filename> is set.
  1526. </para>
  1527. </glossdef>
  1528. </glossentry>
  1529. <glossentry id='var-BUILD_LD_ARCH'><glossterm>BUILD_LD_ARCH</glossterm>
  1530. <info>
  1531. BUILD_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the build."
  1532. </info>
  1533. <glossdef>
  1534. <para role="glossdeffirst">
  1535. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1536. Specifies architecture-specific linker flags for the build
  1537. host. By default, the value of
  1538. <filename>BUILD_LD_ARCH</filename> is empty.
  1539. </para>
  1540. </glossdef>
  1541. </glossentry>
  1542. <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm>
  1543. <info>
  1544. BUILD_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the build host."
  1545. </info>
  1546. <glossdef>
  1547. <para role="glossdeffirst">
  1548. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1549. Specifies the flags to pass to the linker when building
  1550. for the build host.
  1551. When building in the <filename>-native</filename> context,
  1552. <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
  1553. is set to the value of this variable by default.
  1554. </para>
  1555. </glossdef>
  1556. </glossentry>
  1557. <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm>
  1558. <info>
  1559. BUILD_OPTIMIZATION[doc] = "Specifies the optimization flags passed to the C compiler when building for the build host or the SDK."
  1560. </info>
  1561. <glossdef>
  1562. <para role="glossdeffirst">
  1563. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1564. Specifies the optimization flags passed to the C compiler
  1565. when building for the build host or the SDK.
  1566. The flags are passed through the
  1567. <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
  1568. and
  1569. <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
  1570. default values.
  1571. </para>
  1572. <para>
  1573. The default value of the
  1574. <filename>BUILD_OPTIMIZATION</filename> variable is
  1575. "-O2 -pipe".
  1576. </para>
  1577. </glossdef>
  1578. </glossentry>
  1579. <glossentry id='var-BUILD_OS'><glossterm>BUILD_OS</glossterm>
  1580. <info>
  1581. BUILD_OS[doc] = "The operating system (in lower case) of the building architecture (e.g. Linux)."
  1582. </info>
  1583. <glossdef>
  1584. <para role="glossdeffirst">
  1585. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1586. Specifies the operating system in use on the build
  1587. host (e.g. "linux").
  1588. The OpenEmbedded build system sets the value of
  1589. <filename>BUILD_OS</filename> from the OS reported by
  1590. the <filename>uname</filename> command - the first word,
  1591. converted to lower-case characters.
  1592. </para>
  1593. </glossdef>
  1594. </glossentry>
  1595. <glossentry id='var-BUILD_PREFIX'><glossterm>BUILD_PREFIX</glossterm>
  1596. <info>
  1597. BUILD_PREFIX[doc] = "The toolchain binary prefix used for native recipes."
  1598. </info>
  1599. <glossdef>
  1600. <para role="glossdeffirst">
  1601. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1602. The toolchain binary prefix used for native recipes.
  1603. The OpenEmbedded build system uses the
  1604. <filename>BUILD_PREFIX</filename> value to set the
  1605. <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
  1606. when building for <filename>native</filename> recipes.
  1607. </para>
  1608. </glossdef>
  1609. </glossentry>
  1610. <glossentry id='var-BUILD_STRIP'><glossterm>BUILD_STRIP</glossterm>
  1611. <info>
  1612. BUILD_STRIP[doc] = "Specifies the command to be used to strip debugging symbols from binaries produced for the build host."
  1613. </info>
  1614. <glossdef>
  1615. <para role="glossdeffirst">
  1616. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1617. Specifies the command to be used to strip debugging symbols
  1618. from binaries produced for the build host. By default,
  1619. <filename>BUILD_STRIP</filename> points to
  1620. <filename>${</filename><link linkend='var-BUILD_PREFIX'><filename>BUILD_PREFIX</filename></link><filename>}strip</filename>.
  1621. </para>
  1622. </glossdef>
  1623. </glossentry>
  1624. <glossentry id='var-BUILD_SYS'><glossterm>BUILD_SYS</glossterm>
  1625. <info>
  1626. BUILD_SYS[doc] = "The toolchain binary prefix used for native recipes."
  1627. </info>
  1628. <glossdef>
  1629. <para role="glossdeffirst">
  1630. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1631. Specifies the system, including the architecture and
  1632. the operating system, to use when building for the build
  1633. host (i.e. when building <filename>native</filename>
  1634. recipes).
  1635. </para>
  1636. <para>
  1637. The OpenEmbedded build system automatically sets this
  1638. variable based on
  1639. <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>,
  1640. <link linkend='var-BUILD_VENDOR'><filename>BUILD_VENDOR</filename></link>,
  1641. and
  1642. <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
  1643. You do not need to set the <filename>BUILD_SYS</filename>
  1644. variable yourself.
  1645. </para>
  1646. </glossdef>
  1647. </glossentry>
  1648. <glossentry id='var-BUILD_VENDOR'><glossterm>BUILD_VENDOR</glossterm>
  1649. <info>
  1650. BUILD_VENDOR[doc] = "The vendor name to use when building for the build host."
  1651. </info>
  1652. <glossdef>
  1653. <para role="glossdeffirst">
  1654. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1655. Specifies the vendor name to use when building for the
  1656. build host.
  1657. The default value is an empty string ("").
  1658. </para>
  1659. </glossdef>
  1660. </glossentry>
  1661. <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
  1662. <info>
  1663. BUILDDIR[doc] = "Points to the location of the Build Directory."
  1664. </info>
  1665. <glossdef>
  1666. <para role="glossdeffirst">
  1667. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1668. Points to the location of the
  1669. <link linkend='build-directory'>Build Directory</link>.
  1670. You can define this directory indirectly through the
  1671. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
  1672. script by passing in a Build Directory path when you run
  1673. the script.
  1674. If you run the script and do not provide a Build Directory
  1675. path, the <filename>BUILDDIR</filename> defaults to
  1676. <filename>build</filename> in the current directory.
  1677. </para>
  1678. </glossdef>
  1679. </glossentry>
  1680. <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
  1681. <info>
  1682. BUILDHISTORY_COMMIT[doc] = "When inheriting the buildhistory class, this variable specifies whether or not to commit the build history output in a local Git repository."
  1683. </info>
  1684. <glossdef>
  1685. <para role="glossdeffirst">
  1686. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1687. When inheriting the
  1688. <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
  1689. class, this variable specifies whether or not to commit the
  1690. build history output in a local Git repository.
  1691. If set to "1", this local repository will be maintained
  1692. automatically by the
  1693. <filename>buildhistory</filename>
  1694. class and a commit will be created on every
  1695. build for changes to each top-level subdirectory of the
  1696. build history output (images, packages, and sdk).
  1697. If you want to track changes to build history over
  1698. time, you should set this value to "1".
  1699. </para>
  1700. <para>
  1701. By default, the <filename>buildhistory</filename> class
  1702. does not commit the build history output in a local
  1703. Git repository:
  1704. <literallayout class='monospaced'>
  1705. BUILDHISTORY_COMMIT ?= "0"
  1706. </literallayout>
  1707. </para>
  1708. </glossdef>
  1709. </glossentry>
  1710. <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
  1711. <info>
  1712. BUILDHISTORY_COMMIT_AUTHOR[doc] = "When inheriting the buildhistory class, this variable specifies the author to use for each Git commit."
  1713. </info>
  1714. <glossdef>
  1715. <para role="glossdeffirst">
  1716. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1717. When inheriting the
  1718. <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
  1719. class, this variable specifies the author to use for each
  1720. Git commit.
  1721. In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
  1722. variable to work, the
  1723. <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
  1724. variable must be set to "1".
  1725. </para>
  1726. <para>
  1727. Git requires that the value you provide for the
  1728. <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
  1729. takes the form of "name &lt;email@host&gt;".
  1730. Providing an email address or host that is not valid does
  1731. not produce an error.
  1732. </para>
  1733. <para>
  1734. By default, the <filename>buildhistory</filename> class
  1735. sets the variable as follows:
  1736. <literallayout class='monospaced'>
  1737. BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
  1738. </literallayout>
  1739. </para>
  1740. </glossdef>
  1741. </glossentry>
  1742. <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
  1743. <info>
  1744. BUILDHISTORY_DIR[doc] = "When inheriting the buildhistory class, this variable specifies the directory in which build history information is kept."
  1745. </info>
  1746. <glossdef>
  1747. <para role="glossdeffirst">
  1748. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1749. When inheriting the
  1750. <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
  1751. class, this variable specifies the directory in which
  1752. build history information is kept.
  1753. For more information on how the variable works, see the
  1754. <filename>buildhistory.class</filename>.
  1755. </para>
  1756. <para>
  1757. By default, the <filename>buildhistory</filename> class
  1758. sets the directory as follows:
  1759. <literallayout class='monospaced'>
  1760. BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
  1761. </literallayout>
  1762. </para>
  1763. </glossdef>
  1764. </glossentry>
  1765. <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
  1766. <info>
  1767. BUILDHISTORY_FEATURES[doc] = "When inheriting the buildhistory class, this variable specifies the build history features to be enabled."
  1768. </info>
  1769. <glossdef>
  1770. <para role="glossdeffirst">
  1771. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1772. When inheriting the
  1773. <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
  1774. class, this variable specifies the build history features
  1775. to be enabled.
  1776. For more information on how build history works, see the
  1777. "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
  1778. section in the Yocto Project Development Tasks Manual.
  1779. </para>
  1780. <para>
  1781. You can specify three features in the form of a
  1782. space-separated list:
  1783. <itemizedlist>
  1784. <listitem><para><emphasis>image:</emphasis>
  1785. Analysis of the contents of images, which
  1786. includes the list of installed packages among other
  1787. things.
  1788. </para></listitem>
  1789. <listitem><para><emphasis>package:</emphasis>
  1790. Analysis of the contents of individual packages.
  1791. </para></listitem>
  1792. <listitem><para><emphasis>sdk:</emphasis>
  1793. Analysis of the contents of the software
  1794. development kit (SDK).
  1795. </para></listitem>
  1796. </itemizedlist>
  1797. </para>
  1798. <para>
  1799. By default, the <filename>buildhistory</filename> class
  1800. enables all three features:
  1801. <literallayout class='monospaced'>
  1802. BUILDHISTORY_FEATURES ?= "image package sdk"
  1803. </literallayout>
  1804. </para>
  1805. </glossdef>
  1806. </glossentry>
  1807. <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
  1808. <info>
  1809. BUILDHISTORY_IMAGE_FILES[doc] = "When inheriting the buildhistory class, this variable specifies a list of paths to files copied from the image contents into the build history directory under an "image-files" directory in the directory for the image, so that you can track the contents of each file."
  1810. </info>
  1811. <glossdef>
  1812. <para role="glossdeffirst">
  1813. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1814. When inheriting the
  1815. <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
  1816. class, this variable specifies a list of paths to files
  1817. copied from the
  1818. image contents into the build history directory under
  1819. an "image-files" directory in the directory for
  1820. the image, so that you can track the contents of each file.
  1821. The default is to copy <filename>/etc/passwd</filename>
  1822. and <filename>/etc/group</filename>, which allows you to
  1823. monitor for changes in user and group entries.
  1824. You can modify the list to include any file.
  1825. Specifying an invalid path does not produce an error.
  1826. Consequently, you can include files that might
  1827. not always be present.
  1828. </para>
  1829. <para>
  1830. By default, the <filename>buildhistory</filename> class
  1831. provides paths to the following files:
  1832. <literallayout class='monospaced'>
  1833. BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
  1834. </literallayout>
  1835. </para>
  1836. </glossdef>
  1837. </glossentry>
  1838. <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
  1839. <info>
  1840. BUILDHISTORY_PUSH_REPO[doc] = "When inheriting the buildhistory class, this variable optionally specifies a remote repository to which build history pushes Git changes."
  1841. </info>
  1842. <glossdef>
  1843. <para role="glossdeffirst">
  1844. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1845. When inheriting the
  1846. <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
  1847. class, this variable optionally specifies a remote
  1848. repository to which build history pushes Git changes.
  1849. In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
  1850. to work,
  1851. <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
  1852. must be set to "1".
  1853. </para>
  1854. <para>
  1855. The repository should correspond to a remote
  1856. address that specifies a repository as understood by
  1857. Git, or alternatively to a remote name that you have
  1858. set up manually using <filename>git remote</filename>
  1859. within the local repository.
  1860. </para>
  1861. <para>
  1862. By default, the <filename>buildhistory</filename> class
  1863. sets the variable as follows:
  1864. <literallayout class='monospaced'>
  1865. BUILDHISTORY_PUSH_REPO ?= ""
  1866. </literallayout>
  1867. </para>
  1868. </glossdef>
  1869. </glossentry>
  1870. <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm>
  1871. <info>
  1872. BUILDSDK_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the SDK."
  1873. </info>
  1874. <glossdef>
  1875. <para role="glossdeffirst">
  1876. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1877. Specifies the flags to pass to the C compiler when building
  1878. for the SDK.
  1879. When building in the <filename>nativesdk-</filename>
  1880. context,
  1881. <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
  1882. is set to the value of this variable by default.
  1883. </para>
  1884. </glossdef>
  1885. </glossentry>
  1886. <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm>
  1887. <info>
  1888. BUILDSDK_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the SDK."
  1889. </info>
  1890. <glossdef>
  1891. <para role="glossdeffirst">
  1892. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1893. Specifies the flags to pass to the C pre-processor
  1894. (i.e. to both the C and the C++ compilers) when building
  1895. for the SDK.
  1896. When building in the <filename>nativesdk-</filename>
  1897. context,
  1898. <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
  1899. is set to the value of this variable by default.
  1900. </para>
  1901. </glossdef>
  1902. </glossentry>
  1903. <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm>
  1904. <info>
  1905. BUILDSDK_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the SDK."
  1906. </info>
  1907. <glossdef>
  1908. <para role="glossdeffirst">
  1909. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1910. Specifies the flags to pass to the C++ compiler when
  1911. building for the SDK.
  1912. When building in the <filename>nativesdk-</filename>
  1913. context,
  1914. <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
  1915. is set to the value of this variable by default.
  1916. </para>
  1917. </glossdef>
  1918. </glossentry>
  1919. <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm>
  1920. <info>
  1921. BUILDSDK_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the SDK."
  1922. </info>
  1923. <glossdef>
  1924. <para role="glossdeffirst">
  1925. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1926. Specifies the flags to pass to the linker when building
  1927. for the SDK.
  1928. When building in the <filename>nativesdk-</filename>
  1929. context,
  1930. <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
  1931. is set to the value of this variable by default.
  1932. </para>
  1933. </glossdef>
  1934. </glossentry>
  1935. <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
  1936. <info>
  1937. BUILDSTATS_BASE[doc] = "Points to the location of the directory that holds build statistics when you use and enable the buildstats class."
  1938. </info>
  1939. <glossdef>
  1940. <para role="glossdeffirst">
  1941. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1942. Points to the location of the directory that holds build
  1943. statistics when you use and enable the
  1944. <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
  1945. class.
  1946. The <filename>BUILDSTATS_BASE</filename> directory defaults
  1947. to
  1948. <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
  1949. </para>
  1950. </glossdef>
  1951. </glossentry>
  1952. <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
  1953. <info>
  1954. BUSYBOX_SPLIT_SUID[doc] = "For the BusyBox recipe, specifies whether to split the output executable file into two parts: one for features that require setuid root, and one for the remaining features."
  1955. </info>
  1956. <glossdef>
  1957. <para role="glossdeffirst">
  1958. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1959. For the BusyBox recipe, specifies whether to split the
  1960. output executable file into two parts: one for features
  1961. that require <filename>setuid root</filename>, and one for
  1962. the remaining features (i.e. those that do not require
  1963. <filename>setuid root</filename>).
  1964. </para>
  1965. <para>
  1966. The <filename>BUSYBOX_SPLIT_SUID</filename> variable
  1967. defaults to "1", which results in a single output
  1968. executable file.
  1969. Set the variable to "0" to split the output file.
  1970. </para>
  1971. </glossdef>
  1972. </glossentry>
  1973. </glossdiv>
  1974. <glossdiv id='var-glossary-c'><title>C</title>
  1975. <glossentry id='var-CACHE'><glossterm>CACHE</glossterm>
  1976. <info>
  1977. CACHE[doc] = "The directory BitBake uses to store a cache of the metadata."
  1978. </info>
  1979. <glossdef>
  1980. <para role="glossdeffirst">
  1981. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1982. Specifies the directory BitBake uses to store a cache
  1983. of the
  1984. <link linkend='metadata'>Metadata</link>
  1985. so it does not need to be parsed every time BitBake is
  1986. started.
  1987. </para>
  1988. </glossdef>
  1989. </glossentry>
  1990. <glossentry id='var-CC'><glossterm>CC</glossterm>
  1991. <info>
  1992. CC[doc] = "Minimum command and arguments to run the C compiler."
  1993. </info>
  1994. <glossdef>
  1995. <para role="glossdeffirst">
  1996. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  1997. The minimal command and arguments used to run the C
  1998. compiler.
  1999. </para>
  2000. </glossdef>
  2001. </glossentry>
  2002. <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
  2003. <info>
  2004. CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as TARGET_CFLAGS."
  2005. </info>
  2006. <glossdef>
  2007. <para role="glossdeffirst">
  2008. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2009. Specifies the flags to pass to the C compiler.
  2010. This variable is exported to an environment
  2011. variable and thus made visible to the software being
  2012. built during the compilation step.
  2013. </para>
  2014. <para>
  2015. Default initialization for <filename>CFLAGS</filename>
  2016. varies depending on what is being built:
  2017. <itemizedlist>
  2018. <listitem><para>
  2019. <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
  2020. when building for the target
  2021. </para></listitem>
  2022. <listitem><para>
  2023. <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
  2024. when building for the build host (i.e.
  2025. <filename>-native</filename>)
  2026. </para></listitem>
  2027. <listitem><para>
  2028. <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
  2029. when building for an SDK (i.e.
  2030. <filename>nativesdk-</filename>)
  2031. </para></listitem>
  2032. </itemizedlist>
  2033. </para>
  2034. </glossdef>
  2035. </glossentry>
  2036. <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
  2037. <info>
  2038. CLASSOVERRIDE[doc] = "An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth)."
  2039. </info>
  2040. <glossdef>
  2041. <para role="glossdeffirst">
  2042. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2043. An internal variable specifying the special class override
  2044. that should currently apply (e.g. "class-target",
  2045. "class-native", and so forth).
  2046. The classes that use this variable (e.g.
  2047. <link linkend='ref-classes-native'><filename>native</filename></link>,
  2048. <link linkend='ref-classes-nativesdk'><filename>nativesdk</filename></link>,
  2049. and so forth) set the variable to appropriate values.
  2050. <note>
  2051. <filename>CLASSOVERRIDE</filename> gets its default
  2052. "class-target" value from the
  2053. <filename>bitbake.conf</filename> file.
  2054. </note>
  2055. </para>
  2056. <para>
  2057. As an example, the following override allows you to install
  2058. extra files, but only when building for the target:
  2059. <literallayout class='monospaced'>
  2060. do_install_append_class-target() {
  2061. install my-extra-file ${D}${sysconfdir}
  2062. }
  2063. </literallayout>
  2064. Here is an example where <filename>FOO</filename>
  2065. is set to "native" when building for the build host, and
  2066. to "other" when not building for the build host:
  2067. <literallayout class='monospaced'>
  2068. FOO_class-native = "native"
  2069. FOO = "other"
  2070. </literallayout>
  2071. The underlying mechanism behind
  2072. <filename>CLASSOVERRIDE</filename> is simply that it is
  2073. included in the default value of
  2074. <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
  2075. </para>
  2076. </glossdef>
  2077. </glossentry>
  2078. <glossentry id='var-CLEANBROKEN'><glossterm>CLEANBROKEN</glossterm>
  2079. <info>
  2080. CLEANBROKEN[doc] = "Prevents the build system from running 'make clean' during the do_configure task."
  2081. </info>
  2082. <glossdef>
  2083. <para role="glossdeffirst">
  2084. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2085. If set to "1" within a recipe,
  2086. <filename>CLEANBROKEN</filename> specifies that
  2087. the <filename>make clean</filename> command does
  2088. not work for the software being built.
  2089. Consequently, the OpenEmbedded build system will not try
  2090. to run <filename>make clean</filename> during the
  2091. <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
  2092. task, which is the default behavior.
  2093. </para>
  2094. </glossdef>
  2095. </glossentry>
  2096. <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
  2097. <info>
  2098. COMBINED_FEATURES[doc] = "A set of features common between MACHINE_FEATURES and DISTRO_FEATURES."
  2099. </info>
  2100. <glossdef>
  2101. <para role="glossdeffirst">
  2102. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2103. Provides a list of hardware features that are enabled in
  2104. both
  2105. <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
  2106. and
  2107. <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
  2108. This select list of features contains features that make
  2109. sense to be controlled both at the machine and distribution
  2110. configuration level.
  2111. For example, the "bluetooth" feature requires hardware
  2112. support but should also be optional at the distribution
  2113. level, in case the hardware supports Bluetooth but you
  2114. do not ever intend to use it.
  2115. </para>
  2116. <para>
  2117. For more information, see the
  2118. <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
  2119. and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
  2120. variables.
  2121. </para>
  2122. </glossdef>
  2123. </glossentry>
  2124. <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
  2125. <info>
  2126. COMMON_LICENSE_DIR[doc] = "Points to meta/files/common-licenses in the Source Directory, which is where generic license files reside."
  2127. </info>
  2128. <glossdef>
  2129. <para role="glossdeffirst">
  2130. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2131. Points to <filename>meta/files/common-licenses</filename>
  2132. in the
  2133. <link linkend='source-directory'>Source Directory</link>,
  2134. which is where generic license files reside.
  2135. </para>
  2136. </glossdef>
  2137. </glossentry>
  2138. <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
  2139. <info>
  2140. COMPATIBLE_HOST[doc] = "A regular expression that resolves to one or more hosts (when the recipe is native) or one or more targets (when the recipe is non-native) with which a recipe is compatible."
  2141. </info>
  2142. <glossdef>
  2143. <para role="glossdeffirst">
  2144. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2145. A regular expression that resolves to one or more hosts
  2146. (when the recipe is native) or one or more targets (when
  2147. the recipe is non-native) with which a recipe is compatible.
  2148. The regular expression is matched against
  2149. <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
  2150. You can use the variable to stop recipes from being built
  2151. for classes of systems with which the recipes are not
  2152. compatible.
  2153. Stopping these builds is particularly useful with kernels.
  2154. The variable also helps to increase parsing speed
  2155. since the build system skips parsing recipes not
  2156. compatible with the current system.
  2157. </para>
  2158. </glossdef>
  2159. </glossentry>
  2160. <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
  2161. <info>
  2162. COMPATIBLE_MACHINE[doc] = "A regular expression that resolves to one or more target machines with which a recipe is compatible."
  2163. </info>
  2164. <glossdef>
  2165. <para role="glossdeffirst">
  2166. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2167. A regular expression that resolves to one or more
  2168. target machines with which a recipe is compatible.
  2169. The regular expression is matched against
  2170. <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
  2171. You can use the variable to stop recipes from being built
  2172. for machines with which the recipes are not compatible.
  2173. Stopping these builds is particularly useful with kernels.
  2174. The variable also helps to increase parsing speed
  2175. since the build system skips parsing recipes not
  2176. compatible with the current machine.
  2177. </para>
  2178. </glossdef>
  2179. </glossentry>
  2180. <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
  2181. <info>
  2182. COMPLEMENTARY_GLOB[doc] = "Defines wildcards to match when installing a list of complementary packages for all the packages installed in an image."
  2183. </info>
  2184. <glossdef>
  2185. <para role="glossdeffirst">
  2186. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2187. Defines wildcards to match when installing a list of
  2188. complementary packages for all the packages explicitly
  2189. (or implicitly) installed in an image.
  2190. The resulting list of complementary packages is associated
  2191. with an item that can be added to
  2192. <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
  2193. An example usage of this is the "dev-pkgs" item that when
  2194. added to <filename>IMAGE_FEATURES</filename> will
  2195. install -dev packages (containing headers and other
  2196. development files) for every package in the image.
  2197. </para>
  2198. <para>
  2199. To add a new feature item pointing to a wildcard, use a
  2200. variable flag to specify the feature item name and
  2201. use the value to specify the wildcard.
  2202. Here is an example:
  2203. <literallayout class='monospaced'>
  2204. COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
  2205. </literallayout>
  2206. </para>
  2207. </glossdef>
  2208. </glossentry>
  2209. <glossentry id='var-COMPONENTS_DIR'><glossterm>COMPONENTS_DIR</glossterm>
  2210. <info>
  2211. COMPONENTS_DIR[doc] = "Stores sysroot components for each recipe."
  2212. </info>
  2213. <glossdef>
  2214. <para role="glossdeffirst">
  2215. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2216. Stores sysroot components for each recipe.
  2217. The OpenEmbedded build system uses
  2218. <filename>COMPONENTS_DIR</filename> when constructing
  2219. recipe-specific sysroots for other recipes.
  2220. </para>
  2221. <para>
  2222. The default is
  2223. "<filename>${</filename><link linkend='var-STAGING_DIR'><filename>STAGING_DIR</filename></link><filename>}-components</filename>."
  2224. (i.e. "<filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots-components</filename>").
  2225. </para>
  2226. </glossdef>
  2227. </glossentry>
  2228. <glossentry id='var-CONF_VERSION'><glossterm>CONF_VERSION</glossterm>
  2229. <info>
  2230. CONF_VERSION[doc] = "Tracks the version of local.conf. Increased each time build/conf/ changes incompatibly."
  2231. </info>
  2232. <glossdef>
  2233. <para role="glossdeffirst">
  2234. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2235. Tracks the version of the local configuration file
  2236. (i.e. <filename>local.conf</filename>).
  2237. The value for <filename>CONF_VERSION</filename>
  2238. increments each time <filename>build/conf/</filename>
  2239. compatibility changes.
  2240. </para>
  2241. </glossdef>
  2242. </glossentry>
  2243. <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
  2244. <info>
  2245. CONFFILES[doc] = "Identifies editable or configurable files that are part of a package."
  2246. </info>
  2247. <glossdef>
  2248. <para role="glossdeffirst">
  2249. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2250. Identifies editable or configurable files that are part of a package.
  2251. If the Package Management System (PMS) is being used to update
  2252. packages on the target system, it is possible that
  2253. configuration files you have changed after the original installation
  2254. and that you now want to remain unchanged are overwritten.
  2255. In other words, editable files might exist in the package that you do not
  2256. want reset as part of the package update process.
  2257. You can use the <filename>CONFFILES</filename> variable to list the files in the
  2258. package that you wish to prevent the PMS from overwriting during this update process.
  2259. </para>
  2260. <para>
  2261. To use the <filename>CONFFILES</filename> variable, provide a package name
  2262. override that identifies the resulting package.
  2263. Then, provide a space-separated list of files.
  2264. Here is an example:
  2265. <literallayout class='monospaced'>
  2266. CONFFILES_${PN} += "${sysconfdir}/file1 \
  2267. ${sysconfdir}/file2 ${sysconfdir}/file3"
  2268. </literallayout>
  2269. </para>
  2270. <para>
  2271. A relationship exists between the <filename>CONFFILES</filename> and
  2272. <filename><link linkend='var-FILES'>FILES</link></filename> variables.
  2273. The files listed within <filename>CONFFILES</filename> must be a subset of
  2274. the files listed within <filename>FILES</filename>.
  2275. Because the configuration files you provide with <filename>CONFFILES</filename>
  2276. are simply being identified so that the PMS will not overwrite them,
  2277. it makes sense that
  2278. the files must already be included as part of the package through the
  2279. <filename>FILES</filename> variable.
  2280. </para>
  2281. <note>
  2282. When specifying paths as part of the <filename>CONFFILES</filename> variable,
  2283. it is good practice to use appropriate path variables.
  2284. For example, <filename>${sysconfdir}</filename> rather than
  2285. <filename>/etc</filename> or <filename>${bindir}</filename> rather
  2286. than <filename>/usr/bin</filename>.
  2287. You can find a list of these variables at the top of the
  2288. <filename>meta/conf/bitbake.conf</filename> file in the
  2289. <link linkend='source-directory'>Source Directory</link>.
  2290. </note>
  2291. </glossdef>
  2292. </glossentry>
  2293. <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
  2294. <info>
  2295. CONFIG_INITRAMFS_SOURCE[doc] = "Identifies the initial RAM filesystem (initramfs) source files. The OpenEmbedded build system receives and uses this kernel Kconfig variable as an environment variable."
  2296. </info>
  2297. <glossdef>
  2298. <para role="glossdeffirst">
  2299. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2300. Identifies the initial RAM filesystem (initramfs) source
  2301. files.
  2302. The OpenEmbedded build system receives and uses
  2303. this kernel Kconfig variable as an environment variable.
  2304. By default, the variable is set to null ("").
  2305. </para>
  2306. <para>
  2307. The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
  2308. either a single cpio archive with a
  2309. <filename>.cpio</filename> suffix or a
  2310. space-separated list of directories and files for building
  2311. the initramfs image.
  2312. A cpio archive should contain a filesystem archive
  2313. to be used as an initramfs image.
  2314. Directories should contain a filesystem layout to be
  2315. included in the initramfs image.
  2316. Files should contain entries according to the format
  2317. described by the
  2318. <filename>usr/gen_init_cpio</filename> program in the
  2319. kernel tree.
  2320. </para>
  2321. <para>
  2322. If you specify multiple directories and files, the
  2323. initramfs image will be the aggregate of all of them.
  2324. </para>
  2325. <para>
  2326. For information on creating an initramfs, see the
  2327. "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
  2328. section in the Yocto Project Development Tasks Manual.
  2329. </para>
  2330. </glossdef>
  2331. </glossentry>
  2332. <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
  2333. <info>
  2334. CONFIG_SITE[doc] = "A list of files that contains autoconf test results relevant to the current build. This variable is used by the Autotools utilities when running configure."
  2335. </info>
  2336. <glossdef>
  2337. <para role="glossdeffirst">
  2338. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2339. A list of files that contains <filename>autoconf</filename> test results relevant
  2340. to the current build.
  2341. This variable is used by the Autotools utilities when running
  2342. <filename>configure</filename>.
  2343. </para>
  2344. </glossdef>
  2345. </glossentry>
  2346. <glossentry id='var-CONFIGURE_FLAGS'><glossterm>CONFIGURE_FLAGS</glossterm>
  2347. <info>
  2348. CONFIGURE_FLAGS[doc] = "The minimal arguments for GNU configure."
  2349. </info>
  2350. <glossdef>
  2351. <para role="glossdeffirst">
  2352. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2353. The minimal arguments for GNU configure.
  2354. </para>
  2355. </glossdef>
  2356. </glossentry>
  2357. <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
  2358. <info>
  2359. CONFLICT_DISTRO_FEATURES[doc] = "When a recipe inherits the distro_features_check class, this variable identifies distribution features that would be in conflict should the recipe be built."
  2360. </info>
  2361. <glossdef>
  2362. <para role="glossdeffirst">
  2363. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2364. When inheriting the
  2365. <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
  2366. class, this
  2367. variable identifies distribution features that would
  2368. be in conflict should the recipe
  2369. be built.
  2370. In other words, if the
  2371. <filename>CONFLICT_DISTRO_FEATURES</filename> variable
  2372. lists a feature that also appears in
  2373. <filename>DISTRO_FEATURES</filename> within the
  2374. current configuration, an error occurs and the
  2375. build stops.
  2376. </para>
  2377. </glossdef>
  2378. </glossentry>
  2379. <glossentry id='var-COPYLEFT_LICENSE_EXCLUDE'><glossterm>COPYLEFT_LICENSE_EXCLUDE</glossterm>
  2380. <info>
  2381. COPYLEFT_LICENSE_EXCLUDE[doc] = "Licenses to exclude in the source archived by the archiver class."
  2382. </info>
  2383. <glossdef>
  2384. <para role="glossdeffirst">
  2385. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2386. A space-separated list of licenses to exclude from the
  2387. source archived by the
  2388. <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
  2389. class.
  2390. In other words, if a license in a recipe's
  2391. <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
  2392. value is in the value of
  2393. <filename>COPYLEFT_LICENSE_EXCLUDE</filename>, then its
  2394. source is not archived by the class.
  2395. <note>
  2396. The <filename>COPYLEFT_LICENSE_EXCLUDE</filename>
  2397. variable takes precedence over the
  2398. <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
  2399. variable.
  2400. </note>
  2401. The default value, which is "CLOSED Proprietary", for
  2402. <filename>COPYLEFT_LICENSE_EXCLUDE</filename> is set
  2403. by the
  2404. <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
  2405. class, which is inherited by the
  2406. <filename>archiver</filename> class.
  2407. </para>
  2408. </glossdef>
  2409. </glossentry>
  2410. <glossentry id='var-COPYLEFT_LICENSE_INCLUDE'><glossterm>COPYLEFT_LICENSE_INCLUDE</glossterm>
  2411. <info>
  2412. COPYLEFT_LICENSE_INCLUDE[doc] = "Licenses to include in the source archived by the archiver class."
  2413. </info>
  2414. <glossdef>
  2415. <para role="glossdeffirst">
  2416. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2417. A space-separated list of licenses to include in the
  2418. source archived by the
  2419. <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
  2420. class.
  2421. In other words, if a license in a recipe's
  2422. <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
  2423. value is in the value of
  2424. <filename>COPYLEFT_LICENSE_INCLUDE</filename>, then its
  2425. source is archived by the class.
  2426. </para>
  2427. <para>
  2428. The default value is set by the
  2429. <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
  2430. class, which is inherited by the
  2431. <filename>archiver</filename> class.
  2432. The default value includes "GPL*", "LGPL*", and "AGPL*".
  2433. </para>
  2434. </glossdef>
  2435. </glossentry>
  2436. <glossentry id='var-COPYLEFT_PN_EXCLUDE'><glossterm>COPYLEFT_PN_EXCLUDE</glossterm>
  2437. <info>
  2438. COPYLEFT_PN_EXCLUDE[doc] = "Recipes to exclude in the source archived by the archiver class."
  2439. </info>
  2440. <glossdef>
  2441. <para role="glossdeffirst">
  2442. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2443. A list of recipes to exclude in the source archived
  2444. by the
  2445. <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
  2446. class.
  2447. The <filename>COPYLEFT_PN_EXCLUDE</filename> variable
  2448. overrides the license inclusion and exclusion caused
  2449. through the
  2450. <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
  2451. and
  2452. <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
  2453. variables, respectively.
  2454. </para>
  2455. <para>
  2456. The default value, which is "" indicating to not explicitly
  2457. exclude any recipes by name, for
  2458. <filename>COPYLEFT_PN_EXCLUDE</filename> is set
  2459. by the
  2460. <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
  2461. class, which is inherited by the
  2462. <filename>archiver</filename> class.
  2463. </para>
  2464. </glossdef>
  2465. </glossentry>
  2466. <glossentry id='var-COPYLEFT_PN_INCLUDE'><glossterm>COPYLEFT_PN_INCLUDE</glossterm>
  2467. <info>
  2468. COPYLEFT_PN_INCLUDE[doc] = "Recipes to include in the source archived by the archiver class."
  2469. </info>
  2470. <glossdef>
  2471. <para role="glossdeffirst">
  2472. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2473. A list of recipes to include in the source archived
  2474. by the
  2475. <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
  2476. class.
  2477. The <filename>COPYLEFT_PN_INCLUDE</filename> variable
  2478. overrides the license inclusion and exclusion caused
  2479. through the
  2480. <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
  2481. and
  2482. <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
  2483. variables, respectively.
  2484. </para>
  2485. <para>
  2486. The default value, which is "" indicating to not explicitly
  2487. include any recipes by name, for
  2488. <filename>COPYLEFT_PN_INCLUDE</filename> is set
  2489. by the
  2490. <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
  2491. class, which is inherited by the
  2492. <filename>archiver</filename> class.
  2493. </para>
  2494. </glossdef>
  2495. </glossentry>
  2496. <glossentry id='var-COPYLEFT_RECIPE_TYPES'><glossterm>COPYLEFT_RECIPE_TYPES</glossterm>
  2497. <info>
  2498. COPYLEFT_RECIPE_TYPES[doc] = "Recipe types to include in the source archived by the archiver class."
  2499. </info>
  2500. <glossdef>
  2501. <para role="glossdeffirst">
  2502. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2503. A space-separated list of recipe types to include
  2504. in the source archived by the
  2505. <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
  2506. class.
  2507. Recipe types are <filename>target</filename>,
  2508. <filename>native</filename>,
  2509. <filename>nativesdk</filename>,
  2510. <filename>cross</filename>,
  2511. <filename>crosssdk</filename>, and
  2512. <filename>cross-canadian</filename>.
  2513. </para>
  2514. <para>
  2515. The default value, which is "target*", for
  2516. <filename>COPYLEFT_RECIPE_TYPES</filename> is set
  2517. by the
  2518. <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
  2519. class, which is inherited by the
  2520. <filename>archiver</filename> class.
  2521. </para>
  2522. </glossdef>
  2523. </glossentry>
  2524. <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
  2525. <info>
  2526. COPY_LIC_DIRS[doc] = "If set to "1" along with the COPY_LIC_MANIFEST variable, the OpenEmbedded build system copies into the image the license files, which are located in /usr/share/common-licenses, for each package."
  2527. </info>
  2528. <glossdef>
  2529. <para role="glossdeffirst">
  2530. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2531. If set to "1" along with the
  2532. <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
  2533. variable, the OpenEmbedded build system copies
  2534. into the image the license files, which are located in
  2535. <filename>/usr/share/common-licenses</filename>,
  2536. for each package.
  2537. The license files are placed
  2538. in directories within the image itself during build time.
  2539. <note>
  2540. The <filename>COPY_LIC_DIRS</filename> does not
  2541. offer a path for adding licenses for newly installed
  2542. packages to an image, which might be most suitable
  2543. for read-only filesystems that cannot be upgraded.
  2544. See the
  2545. <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
  2546. variable for additional information.
  2547. You can also reference the
  2548. "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
  2549. section in the Yocto Project Development Tasks Manual
  2550. for information on providing license text.
  2551. </note>
  2552. </para>
  2553. </glossdef>
  2554. </glossentry>
  2555. <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
  2556. <info>
  2557. COPY_LIC_MANIFEST[doc] = "If set to "1", the OpenEmbedded build system copies the license manifest for the image to /usr/share/common-licenses/license.manifest within the image itself."
  2558. </info>
  2559. <glossdef>
  2560. <para role="glossdeffirst">
  2561. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2562. If set to "1", the OpenEmbedded build system copies
  2563. the license manifest for the image to
  2564. <filename>/usr/share/common-licenses/license.manifest</filename>
  2565. within the image itself during build time.
  2566. <note>
  2567. The <filename>COPY_LIC_MANIFEST</filename> does not
  2568. offer a path for adding licenses for newly installed
  2569. packages to an image, which might be most suitable
  2570. for read-only filesystems that cannot be upgraded.
  2571. See the
  2572. <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
  2573. variable for additional information.
  2574. You can also reference the
  2575. "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
  2576. section in the Yocto Project Development Tasks Manual
  2577. for information on providing license text.
  2578. </note>
  2579. </para>
  2580. </glossdef>
  2581. </glossentry>
  2582. <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
  2583. <info>
  2584. CORE_IMAGE_EXTRA_INSTALL[doc] = "Specifies the list of packages to be added to the image. You should only set this variable in the conf/local.conf file in the Build Directory."
  2585. </info>
  2586. <glossdef>
  2587. <para role="glossdeffirst">
  2588. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2589. Specifies the list of packages to be added to the image.
  2590. You should only set this variable in the
  2591. <filename>local.conf</filename> configuration file found
  2592. in the
  2593. <link linkend='build-directory'>Build Directory</link>.
  2594. </para>
  2595. <para>
  2596. This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
  2597. </para>
  2598. </glossdef>
  2599. </glossentry>
  2600. <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
  2601. <info>
  2602. COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded-Core Metadata layer (i.e. meta)."
  2603. </info>
  2604. <glossdef>
  2605. <para role="glossdeffirst">
  2606. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2607. Specifies the parent directory of the OpenEmbedded-Core
  2608. Metadata layer (i.e. <filename>meta</filename>).
  2609. </para>
  2610. <para>
  2611. It is an important distinction that
  2612. <filename>COREBASE</filename> points to the parent of this
  2613. layer and not the layer itself.
  2614. Consider an example where you have cloned the Poky Git
  2615. repository and retained the <filename>poky</filename>
  2616. name for your local copy of the repository.
  2617. In this case, <filename>COREBASE</filename> points to
  2618. the <filename>poky</filename> folder because it is the
  2619. parent directory of the <filename>poky/meta</filename>
  2620. layer.
  2621. </para>
  2622. </glossdef>
  2623. </glossentry>
  2624. <glossentry id='var-COREBASE_FILES'><glossterm>COREBASE_FILES</glossterm>
  2625. <info>
  2626. COREBASE_FILES[doc] = "Lists files from the COREBASE directory that should be copied other than the layers listed in the bblayers.conf file."
  2627. </info>
  2628. <glossdef>
  2629. <para role="glossdeffirst">
  2630. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2631. Lists files from the
  2632. <link linkend='var-COREBASE'><filename>COREBASE</filename></link>
  2633. directory that should be copied other than the layers
  2634. listed in the <filename>bblayers.conf</filename> file.
  2635. The <filename>COREBASE_FILES</filename> variable exists
  2636. for the purpose of copying metadata from the
  2637. OpenEmbedded build system into the extensible
  2638. SDK.
  2639. </para>
  2640. <para>
  2641. Explicitly listing files in <filename>COREBASE</filename>
  2642. is needed because it typically contains build
  2643. directories and other files that should not normally
  2644. be copied into the extensible SDK.
  2645. Consequently, the value of
  2646. <filename>COREBASE_FILES</filename> is used in order to
  2647. only copy the files that are actually needed.
  2648. </para>
  2649. </glossdef>
  2650. </glossentry>
  2651. <glossentry id='var-CPP'><glossterm>CPP</glossterm>
  2652. <info>
  2653. CPP[doc] = "Minimum command and arguments to run the C preprocessor."
  2654. </info>
  2655. <glossdef>
  2656. <para role="glossdeffirst">
  2657. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2658. The minimal command and arguments used to run the C
  2659. preprocessor.
  2660. </para>
  2661. </glossdef>
  2662. </glossentry>
  2663. <glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm>
  2664. <info>
  2665. CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers)."
  2666. </info>
  2667. <glossdef>
  2668. <para role="glossdeffirst">
  2669. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2670. Specifies the flags to pass to the C pre-processor
  2671. (i.e. to both the C and the C++ compilers).
  2672. This variable is exported to an environment
  2673. variable and thus made visible to the software being
  2674. built during the compilation step.
  2675. </para>
  2676. <para>
  2677. Default initialization for <filename>CPPFLAGS</filename>
  2678. varies depending on what is being built:
  2679. <itemizedlist>
  2680. <listitem><para>
  2681. <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>
  2682. when building for the target
  2683. </para></listitem>
  2684. <listitem><para>
  2685. <link linkend='var-BUILD_CPPFLAGS'><filename>BUILD_CPPFLAGS</filename></link>
  2686. when building for the build host (i.e.
  2687. <filename>-native</filename>)
  2688. </para></listitem>
  2689. <listitem><para>
  2690. <link linkend='var-BUILDSDK_CPPFLAGS'><filename>BUILDSDK_CPPFLAGS</filename></link>
  2691. when building for an SDK (i.e.
  2692. <filename>nativesdk-</filename>)
  2693. </para></listitem>
  2694. </itemizedlist>
  2695. </para>
  2696. </glossdef>
  2697. </glossentry>
  2698. <glossentry id='var-CROSS_COMPILE'><glossterm>CROSS_COMPILE</glossterm>
  2699. <info>
  2700. CROSS_COMPILE[doc] = "The toolchain binary prefix for the target tools."
  2701. </info>
  2702. <glossdef>
  2703. <para role="glossdeffirst">
  2704. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2705. The toolchain binary prefix for the target tools.
  2706. The <filename>CROSS_COMPILE</filename> variable is the
  2707. same as the
  2708. <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
  2709. variable.
  2710. <note>
  2711. The OpenEmbedded build system sets the
  2712. <filename>CROSS_COMPILE</filename> variable only in
  2713. certain contexts (e.g. when building for kernel
  2714. and kernel module recipes).
  2715. </note>
  2716. </para>
  2717. </glossdef>
  2718. </glossentry>
  2719. <glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm>
  2720. <info>
  2721. CVSDIR[doc] = "The directory where cvs checkouts will be stored in."
  2722. </info>
  2723. <glossdef>
  2724. <para role="glossdeffirst">
  2725. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2726. The directory in which files checked out under the
  2727. CVS system are stored.
  2728. </para>
  2729. </glossdef>
  2730. </glossentry>
  2731. <glossentry id='var-CXX'><glossterm>CXX</glossterm>
  2732. <info>
  2733. CXX[doc] = "Minimum command and arguments to run the C++ compiler."
  2734. </info>
  2735. <glossdef>
  2736. <para role="glossdeffirst">
  2737. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2738. The minimal command and arguments used to run the C++
  2739. compiler.
  2740. </para>
  2741. </glossdef>
  2742. </glossentry>
  2743. <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm>
  2744. <info>
  2745. CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler."
  2746. </info>
  2747. <glossdef>
  2748. <para role="glossdeffirst">
  2749. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2750. Specifies the flags to pass to the C++ compiler.
  2751. This variable is exported to an environment
  2752. variable and thus made visible to the software being
  2753. built during the compilation step.
  2754. </para>
  2755. <para>
  2756. Default initialization for <filename>CXXFLAGS</filename>
  2757. varies depending on what is being built:
  2758. <itemizedlist>
  2759. <listitem><para>
  2760. <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>
  2761. when building for the target
  2762. </para></listitem>
  2763. <listitem><para>
  2764. <link linkend='var-BUILD_CXXFLAGS'><filename>BUILD_CXXFLAGS</filename></link>
  2765. when building for the build host (i.e.
  2766. <filename>-native</filename>)
  2767. </para></listitem>
  2768. <listitem><para>
  2769. <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link>
  2770. when building for an SDK (i.e.
  2771. <filename>nativesdk-</filename>)
  2772. </para></listitem>
  2773. </itemizedlist>
  2774. </para>
  2775. </glossdef>
  2776. </glossentry>
  2777. </glossdiv>
  2778. <glossdiv id='var-glossary-d'><title>D</title>
  2779. <glossentry id='var-D'><glossterm>D</glossterm>
  2780. <info>
  2781. D[doc] = "The destination directory."
  2782. </info>
  2783. <glossdef>
  2784. <para role="glossdeffirst">
  2785. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2786. The destination directory.
  2787. The location in the
  2788. <link linkend='build-directory'>Build Directory</link>
  2789. where components are installed by the
  2790. <link linkend='ref-tasks-install'><filename>do_install</filename></link>
  2791. task.
  2792. This location defaults to:
  2793. <literallayout class='monospaced'>
  2794. ${<link linkend='var-WORKDIR'>WORKDIR</link>}/image
  2795. </literallayout>
  2796. <note><title>Caution</title>
  2797. Tasks that read from or write to this directory should
  2798. run under
  2799. <ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.
  2800. </note>
  2801. </para>
  2802. </glossdef>
  2803. </glossentry>
  2804. <glossentry id='var-DATE'><glossterm>DATE</glossterm>
  2805. <info>
  2806. DATE[doc] = "The date the build was started using YMD format."
  2807. </info>
  2808. <glossdef>
  2809. <para role="glossdeffirst">
  2810. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2811. The date the build was started.
  2812. Dates appear using the year, month, and day (YMD) format
  2813. (e.g. "20150209" for February 9th, 2015).
  2814. </para>
  2815. </glossdef>
  2816. </glossentry>
  2817. <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
  2818. <info>
  2819. DATETIME[doc] = "The date and time the build was started."
  2820. </info>
  2821. <glossdef>
  2822. <para role="glossdeffirst">
  2823. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2824. The date and time on which the current build started.
  2825. The format is suitable for timestamps.
  2826. </para>
  2827. </glossdef>
  2828. </glossentry>
  2829. <glossentry id='var-DEBIAN_NOAUTONAME'><glossterm>DEBIAN_NOAUTONAME</glossterm>
  2830. <info>
  2831. DEBIAN_NOAUTONAME[doc] = "Prevents a particular package from being renamed according to Debian package naming."
  2832. </info>
  2833. <glossdef>
  2834. <para role="glossdeffirst">
  2835. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2836. When the
  2837. <link linkend='ref-classes-debian'><filename>debian</filename></link>
  2838. class is inherited, which is the default behavior,
  2839. <filename>DEBIAN_NOAUTONAME</filename> specifies a
  2840. particular package should not be renamed according to
  2841. Debian library package naming.
  2842. You must use the package name as an override when you
  2843. set this variable.
  2844. Here is an example from the <filename>fontconfig</filename>
  2845. recipe:
  2846. <literallayout class='monospaced'>
  2847. DEBIAN_NOAUTONAME_fontconfig-utils = "1"
  2848. </literallayout>
  2849. </para>
  2850. </glossdef>
  2851. </glossentry>
  2852. <glossentry id='var-DEBIANNAME'><glossterm>DEBIANNAME</glossterm>
  2853. <info>
  2854. DEBIANNAME[doc] = "Allows you to override the library name for an individual package for Debian library package renaming."
  2855. </info>
  2856. <glossdef>
  2857. <para role="glossdeffirst">
  2858. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2859. When the
  2860. <link linkend='ref-classes-debian'><filename>debian</filename></link>
  2861. class is inherited, which is the default behavior,
  2862. <filename>DEBIANNAME</filename> allows you to override the
  2863. library name for an individual package.
  2864. Overriding the library name in these cases is rare.
  2865. You must use the package name as an override when you
  2866. set this variable.
  2867. Here is an example from the <filename>dbus</filename>
  2868. recipe:
  2869. <literallayout class='monospaced'>
  2870. DEBIANNAME_${PN} = "dbus-1"
  2871. </literallayout>
  2872. </para>
  2873. </glossdef>
  2874. </glossentry>
  2875. <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
  2876. <info>
  2877. DEBUG_BUILD[doc] = "Specifies to build packages with debugging information. This influences the value of the SELECTED_OPTIMIZATION variable."
  2878. </info>
  2879. <glossdef>
  2880. <para role="glossdeffirst">
  2881. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2882. Specifies to build packages with debugging information.
  2883. This influences the value of the
  2884. <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
  2885. variable.
  2886. </para>
  2887. </glossdef>
  2888. </glossentry>
  2889. <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
  2890. <info>
  2891. DEBUG_OPTIMIZATION[doc] = "The options to pass in TARGET_CFLAGS and CFLAGS when compiling a system for debugging. This variable defaults to '-O -fno-omit-frame-pointer -g'."
  2892. </info>
  2893. <glossdef>
  2894. <para role="glossdeffirst">
  2895. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2896. The options to pass in
  2897. <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
  2898. and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
  2899. a system for debugging.
  2900. This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
  2901. </para>
  2902. </glossdef>
  2903. </glossentry>
  2904. <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
  2905. <info>
  2906. DEFAULT_PREFERENCE[doc] = "Specifies a weak bias for recipe selection priority."
  2907. </info>
  2908. <glossdef>
  2909. <para role="glossdeffirst">
  2910. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2911. Specifies a weak bias for recipe selection priority.
  2912. </para>
  2913. <para>
  2914. The most common usage of this is variable is to set
  2915. it to "-1" within a recipe for a development version of a
  2916. piece of software.
  2917. Using the variable in this way causes the stable version
  2918. of the recipe to build by default in the absence of
  2919. <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
  2920. being used to build the development version.
  2921. </para>
  2922. <note>
  2923. The bias provided by <filename>DEFAULT_PREFERENCE</filename>
  2924. is weak and is overridden by
  2925. <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
  2926. if that variable is different between two layers
  2927. that contain different versions of the same recipe.
  2928. </note>
  2929. </glossdef>
  2930. </glossentry>
  2931. <glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm>
  2932. <info>
  2933. DEFAULTTUNE[doc] = "The default CPU and Application Binary Interface (ABI) tunings (i.e. the "tune") used by the OpenEmbedded build system."
  2934. </info>
  2935. <glossdef>
  2936. <para role="glossdeffirst">
  2937. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2938. The default CPU and Application Binary Interface (ABI)
  2939. tunings (i.e. the "tune") used by the OpenEmbedded build
  2940. system.
  2941. The <filename>DEFAULTTUNE</filename> helps define
  2942. <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
  2943. </para>
  2944. <para>
  2945. The default tune is either implicitly or explicitly set
  2946. by the machine
  2947. (<link linkend='var-MACHINE'><filename>MACHINE</filename></link>).
  2948. However, you can override the setting using available tunes
  2949. as defined with
  2950. <link linkend='var-AVAILTUNES'><filename>AVAILTUNES</filename></link>.
  2951. </para>
  2952. </glossdef>
  2953. </glossentry>
  2954. <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
  2955. <info>
  2956. DEPENDS[doc] = "Lists a recipe's build-time dependencies (i.e. other recipe files)."
  2957. </info>
  2958. <glossdef>
  2959. <para role="glossdeffirst">
  2960. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  2961. Lists a recipe's build-time dependencies.
  2962. These are dependencies on other recipes whose
  2963. contents (e.g. headers and shared libraries) are needed
  2964. by the recipe at build time.
  2965. </para>
  2966. <para>
  2967. As an example, consider a recipe <filename>foo</filename>
  2968. that contains the following assignment:
  2969. <literallayout class='monospaced'>
  2970. DEPENDS = "bar"
  2971. </literallayout>
  2972. The practical effect of the previous assignment is that
  2973. all files installed by bar will be available in the
  2974. appropriate staging sysroot, given by the
  2975. <link linkend='var-STAGING_DIR'><filename>STAGING_DIR*</filename></link>
  2976. variables, by the time the
  2977. <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
  2978. task for <filename>foo</filename> runs.
  2979. This mechanism is implemented by having
  2980. <filename>do_configure</filename> depend on the
  2981. <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
  2982. task of each recipe listed in <filename>DEPENDS</filename>,
  2983. through a
  2984. <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
  2985. declaration in the
  2986. <link linkend='ref-classes-base'><filename>base</filename></link>
  2987. class.
  2988. <note>
  2989. It seldom is necessary to reference, for example,
  2990. <filename>STAGING_DIR_HOST</filename> explicitly.
  2991. The standard classes and build-related variables are
  2992. configured to automatically use the appropriate staging
  2993. sysroots.
  2994. </note>
  2995. As another example, <filename>DEPENDS</filename> can also
  2996. be used to add utilities that run on the build machine
  2997. during the build.
  2998. For example, a recipe that makes use of a code generator
  2999. built by the recipe <filename>codegen</filename> might have
  3000. the following:
  3001. <literallayout class='monospaced'>
  3002. DEPENDS = "codegen-native"
  3003. </literallayout>
  3004. For more information, see the
  3005. <link linkend='ref-classes-native'><filename>native</filename></link>
  3006. class and the
  3007. <link linkend='var-EXTRANATIVEPATH'><filename>EXTRANATIVEPATH</filename></link>
  3008. variable.
  3009. <note>
  3010. <title>Notes</title>
  3011. <itemizedlist>
  3012. <listitem><para>
  3013. <filename>DEPENDS</filename> is a list of
  3014. recipe names.
  3015. Or, to be more precise, it is a list of
  3016. <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
  3017. names, which usually match recipe names.
  3018. Putting a package name such as "foo-dev" in
  3019. <filename>DEPENDS</filename> does not make
  3020. sense.
  3021. Use "foo" instead, as this will put files
  3022. from all the packages that make up
  3023. <filename>foo</filename>, which includes
  3024. those from <filename>foo-dev</filename>, into
  3025. the sysroot.
  3026. </para></listitem>
  3027. <listitem><para>
  3028. One recipe having another recipe in
  3029. <filename>DEPENDS</filename> does not by itself
  3030. add any runtime dependencies between the
  3031. packages produced by the two recipes.
  3032. However, as explained in the
  3033. "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
  3034. section in the Yocto Project Overview and
  3035. Concepts Manual, runtime dependencies will
  3036. often be added automatically, meaning
  3037. <filename>DEPENDS</filename> alone is
  3038. sufficient for most recipes.
  3039. </para></listitem>
  3040. <listitem><para>
  3041. Counterintuitively,
  3042. <filename>DEPENDS</filename> is often necessary
  3043. even for recipes that install precompiled
  3044. components.
  3045. For example, if <filename>libfoo</filename>
  3046. is a precompiled library that links against
  3047. <filename>libbar</filename>, then
  3048. linking against <filename>libfoo</filename>
  3049. requires both <filename>libfoo</filename>
  3050. and <filename>libbar</filename> to be available
  3051. in the sysroot.
  3052. Without a <filename>DEPENDS</filename> from the
  3053. recipe that installs <filename>libfoo</filename>
  3054. to the recipe that installs
  3055. <filename>libbar</filename>, other recipes might
  3056. fail to link against
  3057. <filename>libfoo</filename>.
  3058. </para></listitem>
  3059. </itemizedlist>
  3060. </note>
  3061. </para>
  3062. <para>
  3063. For information on runtime dependencies, see the
  3064. <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
  3065. variable.
  3066. You can also see the
  3067. "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
  3068. "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
  3069. sections in the BitBake User Manual for additional
  3070. information on tasks and dependencies.
  3071. </para>
  3072. </glossdef>
  3073. </glossentry>
  3074. <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
  3075. <info>
  3076. DEPLOY_DIR[doc] = "Points to the general area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
  3077. </info>
  3078. <glossdef>
  3079. <para role="glossdeffirst">
  3080. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3081. Points to the general area that the OpenEmbedded build
  3082. system uses to place images, packages, SDKs, and other output
  3083. files that are ready to be used outside of the build system.
  3084. By default, this directory resides within the
  3085. <link linkend='build-directory'>Build Directory</link>
  3086. as <filename>${TMPDIR}/deploy</filename>.
  3087. </para>
  3088. <para>
  3089. For more information on the structure of the Build
  3090. Directory, see
  3091. "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
  3092. section.
  3093. For more detail on the contents of the
  3094. <filename>deploy</filename> directory, see the
  3095. "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>",
  3096. "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>",
  3097. and
  3098. "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
  3099. sections all in the Yocto Project Overview and Concepts
  3100. Manual.
  3101. </para>
  3102. </glossdef>
  3103. </glossentry>
  3104. <glossentry id='var-DEPLOY_DIR_DEB'><glossterm>DEPLOY_DIR_DEB</glossterm>
  3105. <info>
  3106. DEPLOY_DIR_DEB[doc] = "Points to a Debian-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
  3107. </info>
  3108. <glossdef>
  3109. <para role="glossdeffirst">
  3110. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3111. Points to the area that the OpenEmbedded build system uses
  3112. to place Debian packages that are ready to be used outside
  3113. of the build system.
  3114. This variable applies only when
  3115. <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
  3116. contains "package_deb".
  3117. </para>
  3118. <para>
  3119. The BitBake configuration file initially defines the
  3120. <filename>DEPLOY_DIR_DEB</filename> variable as a
  3121. sub-folder of
  3122. <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
  3123. <literallayout class='monospaced'>
  3124. DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
  3125. </literallayout>
  3126. </para>
  3127. <para>
  3128. The
  3129. <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>
  3130. class uses the
  3131. <filename>DEPLOY_DIR_DEB</filename> variable to make sure
  3132. the
  3133. <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>
  3134. task writes Debian packages into the appropriate folder.
  3135. For more information on how packaging works, see the
  3136. "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
  3137. section in the Yocto Project Overview and Concepts Manual.
  3138. </para>
  3139. </glossdef>
  3140. </glossentry>
  3141. <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
  3142. <info>
  3143. DEPLOY_DIR_IMAGE[doc] = "Points to the area that the OpenEmbedded build system uses to place images and other associated output files that are ready to be deployed onto the target machine."
  3144. </info>
  3145. <glossdef>
  3146. <para role="glossdeffirst">
  3147. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3148. Points to the area that the OpenEmbedded build system uses
  3149. to place images and other associated output files that are
  3150. ready to be deployed onto the target machine.
  3151. The directory is machine-specific as it contains the
  3152. <filename>${MACHINE}</filename> name.
  3153. By default, this directory resides within the
  3154. <link linkend='build-directory'>Build Directory</link>
  3155. as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
  3156. </para>
  3157. <para>
  3158. For more information on the structure of the Build
  3159. Directory, see
  3160. "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
  3161. section.
  3162. For more detail on the contents of the
  3163. <filename>deploy</filename> directory, see the
  3164. "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
  3165. and
  3166. "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
  3167. sections both in the Yocto Project Overview and Concepts
  3168. Manual.
  3169. </para>
  3170. </glossdef>
  3171. </glossentry>
  3172. <glossentry id='var-DEPLOY_DIR_IPK'><glossterm>DEPLOY_DIR_IPK</glossterm>
  3173. <info>
  3174. DEPLOY_DIR_IPK[doc] = "Points to a IPK-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
  3175. </info>
  3176. <glossdef>
  3177. <para role="glossdeffirst">
  3178. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3179. Points to the area that the OpenEmbedded build system uses
  3180. to place IPK packages that are ready to be used outside of
  3181. the build system.
  3182. This variable applies only when
  3183. <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
  3184. contains "package_ipk".
  3185. </para>
  3186. <para>
  3187. The BitBake configuration file initially defines this
  3188. variable as a sub-folder of
  3189. <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
  3190. <literallayout class='monospaced'>
  3191. DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
  3192. </literallayout>
  3193. </para>
  3194. <para>
  3195. The
  3196. <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>
  3197. class uses the
  3198. <filename>DEPLOY_DIR_IPK</filename> variable to make sure
  3199. the
  3200. <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
  3201. task writes IPK packages into the appropriate folder.
  3202. For more information on how packaging works, see the
  3203. "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
  3204. section in the Yocto Project Overview and Concepts Manual.
  3205. </para>
  3206. </glossdef>
  3207. </glossentry>
  3208. <glossentry id='var-DEPLOY_DIR_RPM'><glossterm>DEPLOY_DIR_RPM</glossterm>
  3209. <info>
  3210. DEPLOY_DIR_RPM[doc] = "Points to a RPM-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
  3211. </info>
  3212. <glossdef>
  3213. <para role="glossdeffirst">
  3214. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3215. Points to the area that the OpenEmbedded build system uses
  3216. to place RPM packages that are ready to be used outside
  3217. of the build system.
  3218. This variable applies only when
  3219. <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
  3220. contains "package_rpm".
  3221. </para>
  3222. <para>
  3223. The BitBake configuration file initially defines this
  3224. variable as a sub-folder of
  3225. <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
  3226. <literallayout class='monospaced'>
  3227. DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
  3228. </literallayout>
  3229. </para>
  3230. <para>
  3231. The
  3232. <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>
  3233. class uses the
  3234. <filename>DEPLOY_DIR_RPM</filename> variable to make sure
  3235. the
  3236. <link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>
  3237. task writes RPM packages into the appropriate folder.
  3238. For more information on how packaging works, see the
  3239. "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
  3240. section in the Yocto Project Overview and Concepts Manual.
  3241. </para>
  3242. </glossdef>
  3243. </glossentry>
  3244. <glossentry id='var-DEPLOY_DIR_TAR'><glossterm>DEPLOY_DIR_TAR</glossterm>
  3245. <info>
  3246. DEPLOY_DIR_TAR[doc] = "Points to a tarball area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
  3247. </info>
  3248. <glossdef>
  3249. <para role="glossdeffirst">
  3250. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3251. Points to the area that the OpenEmbedded build system uses
  3252. to place tarballs that are ready to be used outside of
  3253. the build system.
  3254. This variable applies only when
  3255. <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
  3256. contains "package_tar".
  3257. </para>
  3258. <para>
  3259. The BitBake configuration file initially defines this
  3260. variable as a sub-folder of
  3261. <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
  3262. <literallayout class='monospaced'>
  3263. DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
  3264. </literallayout>
  3265. </para>
  3266. <para>
  3267. The
  3268. <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
  3269. class uses the
  3270. <filename>DEPLOY_DIR_TAR</filename> variable to make sure
  3271. the
  3272. <link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>
  3273. task writes TAR packages into the appropriate folder.
  3274. For more information on how packaging works, see the
  3275. "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
  3276. section in the Yocto Project Overview and Concepts Manual.
  3277. </para>
  3278. </glossdef>
  3279. </glossentry>
  3280. <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
  3281. <info>
  3282. DEPLOYDIR[doc] = "For recipes that inherit the deploy class, the DEPLOYDIR points to a temporary work area for deployed files."
  3283. </info>
  3284. <glossdef>
  3285. <para role="glossdeffirst">
  3286. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3287. When inheriting the
  3288. <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
  3289. class, the <filename>DEPLOYDIR</filename> points to a
  3290. temporary work area for deployed files that is set in the
  3291. <filename>deploy</filename> class as follows:
  3292. <literallayout class='monospaced'>
  3293. DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
  3294. </literallayout>
  3295. </para>
  3296. <para>
  3297. Recipes inheriting the <filename>deploy</filename> class
  3298. should copy files to be deployed into
  3299. <filename>DEPLOYDIR</filename>, and the class will take
  3300. care of copying them into
  3301. <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
  3302. afterwards.
  3303. </para>
  3304. </glossdef>
  3305. </glossentry>
  3306. <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
  3307. <info>
  3308. DESCRIPTION[doc] = "The package description used by package managers. If not set, DESCRIPTION takes the value of the SUMMARY variable."
  3309. </info>
  3310. <glossdef>
  3311. <para role="glossdeffirst">
  3312. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3313. The package description used by package managers.
  3314. If not set, <filename>DESCRIPTION</filename> takes
  3315. the value of the
  3316. <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
  3317. variable.
  3318. </para>
  3319. </glossdef>
  3320. </glossentry>
  3321. <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm>
  3322. <info>
  3323. DISK_SIGNATURE[doc] = "A 32-bit MBR disk signature used by directdisk images."
  3324. </info>
  3325. <glossdef>
  3326. <para role="glossdeffirst">
  3327. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3328. A 32-bit MBR disk signature used by
  3329. <filename>directdisk</filename> images.
  3330. </para>
  3331. <para>
  3332. By default, the signature is set to an automatically
  3333. generated random value that allows the OpenEmbedded
  3334. build system to create a boot loader.
  3335. You can override the signature in the image recipe
  3336. by setting <filename>DISK_SIGNATURE</filename> to an
  3337. 8-digit hex string.
  3338. You might want to override
  3339. <filename>DISK_SIGNATURE</filename> if you want the disk
  3340. signature to remain constant between image builds.
  3341. </para>
  3342. <para>
  3343. When using Linux 3.8 or later, you can use
  3344. <filename>DISK_SIGNATURE</filename> to specify the root
  3345. by UUID to allow the kernel to locate the root device
  3346. even if the device name changes due to differences in
  3347. hardware configuration.
  3348. By default, <filename>ROOT_VM</filename> is set
  3349. as follows:
  3350. <literallayout class='monospaced'>
  3351. ROOT_VM ?= "root=/dev/sda2"
  3352. </literallayout>
  3353. However, you can change this to locate the root device
  3354. using the disk signature instead:
  3355. <literallayout class='monospaced'>
  3356. ROOT_VM = "root=PARTUUID=${DISK_SIGNATURE}-02"
  3357. </literallayout>
  3358. </para>
  3359. <para>
  3360. As previously mentioned, it is possible to set the
  3361. <filename>DISK_SIGNATURE</filename> variable in your
  3362. <filename>local.conf</filename> file to a fixed
  3363. value if you do not want <filename>syslinux.cfg</filename>
  3364. changing for each build.
  3365. You might find this useful when you want to upgrade the
  3366. root filesystem on a device without having to recreate or
  3367. modify the master boot record.
  3368. </para>
  3369. </glossdef>
  3370. </glossentry>
  3371. <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
  3372. <info>
  3373. DISTRO[doc] = "The short name of the distribution. If the variable is blank, meta/conf/distro/defaultsetup.conf will be used."
  3374. </info>
  3375. <glossdef>
  3376. <para role="glossdeffirst">
  3377. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3378. The short name of the distribution.
  3379. This variable corresponds to a distribution
  3380. configuration file whose root name is the same as the
  3381. variable's argument and whose filename extension is
  3382. <filename>.conf</filename>.
  3383. For example, the distribution configuration file for the
  3384. Poky distribution is named <filename>poky.conf</filename>
  3385. and resides in the
  3386. <filename>meta-poky/conf/distro</filename> directory of
  3387. the
  3388. <link linkend='source-directory'>Source Directory</link>.
  3389. </para>
  3390. <para>
  3391. Within that <filename>poky.conf</filename> file, the
  3392. <filename>DISTRO</filename> variable is set as follows:
  3393. <literallayout class='monospaced'>
  3394. DISTRO = "poky"
  3395. </literallayout>
  3396. </para>
  3397. <para>
  3398. Distribution configuration files are located in a
  3399. <filename>conf/distro</filename> directory within the
  3400. <link linkend='metadata'>Metadata</link>
  3401. that contains the distribution configuration.
  3402. The value for <filename>DISTRO</filename> must not contain
  3403. spaces, and is typically all lower-case.
  3404. <note>
  3405. If the <filename>DISTRO</filename> variable is blank, a set
  3406. of default configurations are used, which are specified
  3407. within
  3408. <filename>meta/conf/distro/defaultsetup.conf</filename>
  3409. also in the Source Directory.
  3410. </note>
  3411. </para>
  3412. </glossdef>
  3413. </glossentry>
  3414. <glossentry id='var-DISTRO_CODENAME'><glossterm>DISTRO_CODENAME</glossterm>
  3415. <info>
  3416. DISTRO_CODENAME[doc] = "Specifies a codename for the distribution being built."
  3417. </info>
  3418. <glossdef>
  3419. <para role="glossdeffirst">
  3420. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3421. Specifies a codename for the distribution being built.
  3422. </para>
  3423. </glossdef>
  3424. </glossentry>
  3425. <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
  3426. <info>
  3427. DISTRO_EXTRA_RDEPENDS[doc] = "Specifies a list of distro-specific packages to add to all images. The variable only applies to the images that include packagegroup-base."
  3428. </info>
  3429. <glossdef>
  3430. <para role="glossdeffirst">
  3431. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3432. Specifies a list of distro-specific packages to add to all images.
  3433. This variable takes affect through
  3434. <filename>packagegroup-base</filename> so the
  3435. variable only really applies to the more full-featured
  3436. images that include <filename>packagegroup-base</filename>.
  3437. You can use this variable to keep distro policy out of
  3438. generic images.
  3439. As with all other distro variables, you set this variable
  3440. in the distro <filename>.conf</filename> file.
  3441. </para>
  3442. </glossdef>
  3443. </glossentry>
  3444. <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
  3445. <info>
  3446. DISTRO_EXTRA_RRECOMMENDS[doc] = "Specifies a list of distro-specific packages to add to all images if the packages exist. The list of packages are automatically installed but you can remove them."
  3447. </info>
  3448. <glossdef>
  3449. <para role="glossdeffirst">
  3450. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3451. Specifies a list of distro-specific packages to add to all images
  3452. if the packages exist.
  3453. The packages might not exist or be empty (e.g. kernel modules).
  3454. The list of packages are automatically installed but you can
  3455. remove them.
  3456. </para>
  3457. </glossdef>
  3458. </glossentry>
  3459. <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
  3460. <info>
  3461. DISTRO_FEATURES[doc] = "The features enabled for the distribution."
  3462. </info>
  3463. <glossdef>
  3464. <para role="glossdeffirst">
  3465. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3466. The software support you want in your distribution for
  3467. various features.
  3468. You define your distribution features in the distribution
  3469. configuration file.
  3470. </para>
  3471. <para>
  3472. In most cases, the presence or absence of a feature in
  3473. <filename>DISTRO_FEATURES</filename> is translated to the
  3474. appropriate option supplied to the configure script
  3475. during the
  3476. <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
  3477. task for recipes that optionally support the feature.
  3478. For example, specifying "x11" in
  3479. <filename>DISTRO_FEATURES</filename>, causes
  3480. every piece of software built for the target that can
  3481. optionally support X11 to have its X11 support enabled.
  3482. </para>
  3483. <para>
  3484. Two more examples are Bluetooth and NFS support.
  3485. For a more complete list of features that ships with the
  3486. Yocto Project and that you can provide with this variable,
  3487. see the
  3488. "<link linkend='ref-features-distro'>Distro Features</link>"
  3489. section.
  3490. </para>
  3491. </glossdef>
  3492. </glossentry>
  3493. <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
  3494. <info>
  3495. DISTRO_FEATURES_BACKFILL[doc] = "Features to be added to DISTRO_FEATURES if not also present in DISTRO_FEATURES_BACKFILL_CONSIDERED. This variable is set in the meta/conf/bitbake.conf file and it is not intended to be user-configurable."
  3496. </info>
  3497. <glossdef>
  3498. <para role="glossdeffirst">
  3499. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3500. Features to be added to
  3501. <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
  3502. if not also present in
  3503. <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
  3504. </para>
  3505. <para>
  3506. This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
  3507. It is not intended to be user-configurable.
  3508. It is best to just reference the variable to see which distro features are
  3509. being backfilled for all distro configurations.
  3510. See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
  3511. more information.
  3512. </para>
  3513. </glossdef>
  3514. </glossentry>
  3515. <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
  3516. <info>
  3517. DISTRO_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from DISTRO_FEATURES_BACKFILL that should not be backfilled (i.e. added to DISTRO_FEATURES) during the build."
  3518. </info>
  3519. <glossdef>
  3520. <para role="glossdeffirst">
  3521. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3522. Features from
  3523. <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
  3524. that should not be backfilled (i.e. added to
  3525. <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
  3526. during the build.
  3527. See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
  3528. more information.
  3529. </para>
  3530. </glossdef>
  3531. </glossentry>
  3532. <glossentry id='var-DISTRO_FEATURES_DEFAULT'><glossterm>DISTRO_FEATURES_DEFAULT</glossterm>
  3533. <info>
  3534. DISTRO_FEATURES_DEFAULT[doc] = "Provides the default list of distro features with the exception of any libc-specific features."
  3535. </info>
  3536. <glossdef>
  3537. <para role="glossdeffirst">
  3538. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3539. A convenience variable that gives you the default
  3540. list of distro features with the exception of any
  3541. features specific to the C library
  3542. (<filename>libc</filename>).
  3543. </para>
  3544. <para>
  3545. When creating a custom distribution, you might find it
  3546. useful to be able to reuse the default
  3547. <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
  3548. options without the need to write out the full set.
  3549. Here is an example that uses
  3550. <filename>DISTRO_FEATURES_DEFAULT</filename> from a
  3551. custom distro configuration file:
  3552. <literallayout class='monospaced'>
  3553. DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} ${DISTRO_FEATURES_LIBC} myfeature"
  3554. </literallayout>
  3555. </para>
  3556. </glossdef>
  3557. </glossentry>
  3558. <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVE'><glossterm>DISTRO_FEATURES_FILTER_NATIVE</glossterm>
  3559. <info>
  3560. DISTRO_FEATURES_FILTER_NATIVE[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building native recipes."
  3561. </info>
  3562. <glossdef>
  3563. <para role="glossdeffirst">
  3564. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3565. Specifies a list of features that if present in
  3566. the target
  3567. <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
  3568. value should be included in
  3569. <filename>DISTRO_FEATURES</filename> when building native
  3570. recipes.
  3571. This variable is used in addition to the features
  3572. filtered using the
  3573. <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link>
  3574. variable.
  3575. </para>
  3576. </glossdef>
  3577. </glossentry>
  3578. <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVESDK'><glossterm>DISTRO_FEATURES_FILTER_NATIVESDK</glossterm>
  3579. <info>
  3580. DISTRO_FEATURES_FILTER_NATIVESDK[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building nativesdk recipes."
  3581. </info>
  3582. <glossdef>
  3583. <para role="glossdeffirst">
  3584. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3585. Specifies a list of features that if present in the target
  3586. <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
  3587. value should be included in
  3588. <filename>DISTRO_FEATURES</filename> when building
  3589. nativesdk recipes.
  3590. This variable is used in addition to the features
  3591. filtered using the
  3592. <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link>
  3593. variable.
  3594. </para>
  3595. </glossdef>
  3596. </glossentry>
  3597. <glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm>DISTRO_FEATURES_LIBC</glossterm>
  3598. <info>
  3599. DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)."
  3600. </info>
  3601. <glossdef>
  3602. <para role="glossdeffirst">
  3603. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3604. A convenience variable that specifies the list of distro
  3605. features that are specific to the C library
  3606. (<filename>libc</filename>).
  3607. Typically, these features are prefixed with "libc-" and
  3608. control which features are enabled at during the build
  3609. within the C library itself.
  3610. </para>
  3611. </glossdef>
  3612. </glossentry>
  3613. <glossentry id='var-DISTRO_FEATURES_NATIVE'><glossterm>DISTRO_FEATURES_NATIVE</glossterm>
  3614. <info>
  3615. DISTRO_FEATURES_NATIVE[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building native recipes."
  3616. </info>
  3617. <glossdef>
  3618. <para role="glossdeffirst">
  3619. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3620. Specifies a list of features that should be included in
  3621. <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
  3622. when building native recipes.
  3623. This variable is used in addition to the features
  3624. filtered using the
  3625. <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>
  3626. variable.
  3627. </para>
  3628. </glossdef>
  3629. </glossentry>
  3630. <glossentry id='var-DISTRO_FEATURES_NATIVESDK'><glossterm>DISTRO_FEATURES_NATIVESDK</glossterm>
  3631. <info>
  3632. DISTRO_FEATURES_NATIVESDK[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building nativesdk recipes."
  3633. </info>
  3634. <glossdef>
  3635. <para role="glossdeffirst">
  3636. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3637. Specifies a list of features that should be included in
  3638. <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
  3639. when building nativesdk recipes.
  3640. This variable is used in addition to the features
  3641. filtered using the
  3642. <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>
  3643. variable.
  3644. </para>
  3645. </glossdef>
  3646. </glossentry>
  3647. <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
  3648. <info>
  3649. DISTRO_NAME[doc] = "The long name of the distribution."
  3650. </info>
  3651. <glossdef>
  3652. <para role="glossdeffirst">
  3653. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3654. The long name of the distribution.
  3655. </para>
  3656. </glossdef>
  3657. </glossentry>
  3658. <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
  3659. <info>
  3660. DISTRO_VERSION[doc] = "The version of the distribution."
  3661. </info>
  3662. <glossdef>
  3663. <para role="glossdeffirst">
  3664. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3665. The version of the distribution.
  3666. </para>
  3667. </glossdef>
  3668. </glossentry>
  3669. <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
  3670. <info>
  3671. DISTROOVERRIDES[doc] = "A colon-separated list of overrides specific to the current distribution."
  3672. </info>
  3673. <glossdef>
  3674. <para role="glossdeffirst">
  3675. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3676. A colon-separated list of overrides specific to the
  3677. current distribution.
  3678. By default, this list includes the value of
  3679. <link linkend='var-DISTRO'><filename>DISTRO</filename></link>.
  3680. </para>
  3681. <para>
  3682. You can extend <filename>DISTROOVERRIDES</filename>
  3683. to add extra overrides that should apply to
  3684. the distribution.
  3685. </para>
  3686. <para>
  3687. The underlying mechanism behind
  3688. <filename>DISTROOVERRIDES</filename> is simply that it
  3689. is included in the default value of
  3690. <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
  3691. </para>
  3692. </glossdef>
  3693. </glossentry>
  3694. <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
  3695. <info>
  3696. DL_DIR[doc] = "The central download directory used by the build process to store downloads. By default, the directory is 'downloads' in the Build Directory."
  3697. </info>
  3698. <glossdef>
  3699. <para role="glossdeffirst">
  3700. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3701. The central download directory used by the build process to
  3702. store downloads.
  3703. By default, <filename>DL_DIR</filename> gets files
  3704. suitable for mirroring for everything except Git
  3705. repositories.
  3706. If you want tarballs of Git repositories, use the
  3707. <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
  3708. variable.
  3709. </para>
  3710. <para>
  3711. You can set this directory by defining the
  3712. <filename>DL_DIR</filename> variable in the
  3713. <filename>conf/local.conf</filename> file.
  3714. This directory is self-maintaining and you should not have
  3715. to touch it.
  3716. By default, the directory is <filename>downloads</filename>
  3717. in the
  3718. <link linkend='build-directory'>Build Directory</link>.
  3719. <literallayout class='monospaced'>
  3720. #DL_DIR ?= "${TOPDIR}/downloads"
  3721. </literallayout>
  3722. To specify a different download directory, simply remove
  3723. the comment from the line and provide your directory.
  3724. </para>
  3725. <para>
  3726. During a first build, the system downloads many different
  3727. source code tarballs from various upstream projects.
  3728. Downloading can take a while, particularly if your network
  3729. connection is slow.
  3730. Tarballs are all stored in the directory defined by
  3731. <filename>DL_DIR</filename> and the build system looks there
  3732. first to find source tarballs.
  3733. <note>
  3734. When wiping and rebuilding, you can preserve this
  3735. directory to speed up this part of subsequent
  3736. builds.
  3737. </note>
  3738. </para>
  3739. <para>
  3740. You can safely share this directory between multiple builds
  3741. on the same development machine.
  3742. For additional information on how the build process gets
  3743. source files when working behind a firewall or proxy server,
  3744. see this specific question in the
  3745. "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
  3746. chapter.
  3747. You can also refer to the
  3748. "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
  3749. Wiki page.
  3750. </para>
  3751. </glossdef>
  3752. </glossentry>
  3753. <glossentry id='var-DOC_COMPRESS'><glossterm>DOC_COMPRESS</glossterm>
  3754. <info>
  3755. DOC_COMPRESS[doc] = "When inheriting the compress_doc class, this variable sets the compression policy used when the OpenEmbedded build system compresses man pages and info pages."
  3756. </info>
  3757. <glossdef>
  3758. <para role="glossdeffirst">
  3759. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3760. When inheriting the
  3761. <link linkend='ref-classes-compress_doc'><filename>compress_doc</filename></link>
  3762. class, this variable sets the compression policy used when
  3763. the OpenEmbedded build system compresses man pages and info
  3764. pages.
  3765. By default, the compression method used is gz (gzip).
  3766. Other policies available are xz and bz2.
  3767. </para>
  3768. <para>
  3769. For information on policies and on how to use this
  3770. variable, see the comments in the
  3771. <filename>meta/classes/compress_doc.bbclass</filename> file.
  3772. </para>
  3773. </glossdef>
  3774. </glossentry>
  3775. </glossdiv>
  3776. <glossdiv id='var-glossary-e'><title>E</title>
  3777. <glossentry id='var-EFI_PROVIDER'><glossterm>EFI_PROVIDER</glossterm>
  3778. <info>
  3779. EFI_PROVIDER[doc] = "When building bootable images (i.e. where hddimg, iso, or wic.vmdk is in IMAGE_FSTYPES), the EFI_PROVIDER variable specifies the EFI bootloader to use."
  3780. </info>
  3781. <glossdef>
  3782. <para role="glossdeffirst">
  3783. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3784. When building bootable images (i.e. where
  3785. <filename>hddimg</filename>, <filename>iso</filename>,
  3786. or <filename>wic.vmdk</filename> is in
  3787. <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>),
  3788. the <filename>EFI_PROVIDER</filename> variable specifies
  3789. the EFI bootloader to use.
  3790. The default is "grub-efi", but "systemd-boot" can be used
  3791. instead.
  3792. </para>
  3793. <para>
  3794. See the
  3795. <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
  3796. and
  3797. <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
  3798. classes for more information.
  3799. </para>
  3800. </glossdef>
  3801. </glossentry>
  3802. <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
  3803. <info>
  3804. ENABLE_BINARY_LOCALE_GENERATION[doc] = "Controls which locales for glibc are generated during the build. The variable is useful if the target device has 64Mbytes of RAM or less."
  3805. </info>
  3806. <glossdef>
  3807. <para role="glossdeffirst">
  3808. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3809. Variable that controls which locales for
  3810. <filename>glibc</filename> are generated during the
  3811. build (useful if the target device has 64Mbytes
  3812. of RAM or less).
  3813. </para>
  3814. </glossdef>
  3815. </glossentry>
  3816. <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
  3817. <info>
  3818. ERR_REPORT_DIR[doc] = "When used with the report-error class, specifies the path used for storing the debug files created by the error reporting tool, which allows you to submit build errors you encounter to a central database."
  3819. </info>
  3820. <glossdef>
  3821. <para role="glossdeffirst">
  3822. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3823. When used with the
  3824. <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
  3825. class, specifies the path used for storing the debug files
  3826. created by the
  3827. <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
  3828. which allows you to submit build errors you encounter to a
  3829. central database.
  3830. By default, the value of this variable is
  3831. <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
  3832. </para>
  3833. <para>
  3834. You can set <filename>ERR_REPORT_DIR</filename> to the path
  3835. you want the error reporting tool to store the debug files
  3836. as follows in your <filename>local.conf</filename> file:
  3837. <literallayout class='monospaced'>
  3838. ERR_REPORT_DIR = "<replaceable>path</replaceable>"
  3839. </literallayout>
  3840. </para>
  3841. </glossdef>
  3842. </glossentry>
  3843. <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
  3844. <info>
  3845. ERROR_QA[doc] = "Specifies the quality assurance checks whose failures are reported as errors by the OpenEmbedded build system."
  3846. </info>
  3847. <glossdef>
  3848. <para role="glossdeffirst">
  3849. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3850. Specifies the quality assurance checks whose failures are
  3851. reported as errors by the OpenEmbedded build system.
  3852. You set this variable in your distribution configuration
  3853. file.
  3854. For a list of the checks you can control with this variable,
  3855. see the
  3856. "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
  3857. section.
  3858. </para>
  3859. </glossdef>
  3860. </glossentry>
  3861. <glossentry id='var-EXCLUDE_FROM_SHLIBS'><glossterm>EXCLUDE_FROM_SHLIBS</glossterm>
  3862. <info>
  3863. EXCLUDE_FROM_SHLIBS[doc] = "Causes the OpenEmbedded build system's shared libraries resolver to exclude an entire package when scanning for shared libraries."
  3864. </info>
  3865. <glossdef>
  3866. <para role="glossdeffirst">
  3867. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3868. Triggers the OpenEmbedded build system's shared libraries
  3869. resolver to exclude an entire package when scanning for
  3870. shared libraries.
  3871. <note>
  3872. The shared libraries resolver's functionality results
  3873. in part from the internal function
  3874. <filename>package_do_shlibs</filename>, which is part of
  3875. the
  3876. <link linkend='ref-tasks-package'><filename>do_package</filename></link>
  3877. task.
  3878. You should be aware that the shared libraries resolver
  3879. might implicitly define some dependencies between
  3880. packages.
  3881. </note>
  3882. The <filename>EXCLUDE_FROM_SHLIBS</filename> variable is
  3883. similar to the
  3884. <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
  3885. variable, which excludes a package's particular libraries
  3886. only and not the whole package.
  3887. </para>
  3888. <para>
  3889. Use the
  3890. <filename>EXCLUDE_FROM_SHLIBS</filename> variable by
  3891. setting it to "1" for a particular package:
  3892. <literallayout class='monospaced'>
  3893. EXCLUDE_FROM_SHLIBS = "1"
  3894. </literallayout>
  3895. </para>
  3896. </glossdef>
  3897. </glossentry>
  3898. <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
  3899. <info>
  3900. EXCLUDE_FROM_WORLD[doc] = "Directs BitBake to exclude a recipe from world builds (i.e. bitbake world)."
  3901. </info>
  3902. <glossdef>
  3903. <para role="glossdeffirst">
  3904. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3905. Directs BitBake to exclude a recipe from world builds (i.e.
  3906. <filename>bitbake world</filename>).
  3907. During world builds, BitBake locates, parses and builds all
  3908. recipes found in every layer exposed in the
  3909. <filename>bblayers.conf</filename> configuration file.
  3910. </para>
  3911. <para>
  3912. To exclude a recipe from a world build using this variable,
  3913. set the variable to "1" in the recipe.
  3914. </para>
  3915. <note>
  3916. Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
  3917. may still be built during a world build in order to satisfy
  3918. dependencies of other recipes.
  3919. Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
  3920. only ensures that the recipe is not explicitly added
  3921. to the list of build targets in a world build.
  3922. </note>
  3923. </glossdef>
  3924. </glossentry>
  3925. <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
  3926. <info>
  3927. EXTENDPE[doc] = "Used with file and pathnames to create a prefix for a recipe's version based on the recipe's PE value. If PE is set and greater than zero for a recipe, EXTENDPE becomes that value."
  3928. </info>
  3929. <glossdef>
  3930. <para role="glossdeffirst">
  3931. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3932. Used with file and pathnames to create a prefix for a recipe's
  3933. version based on the recipe's
  3934. <link linkend='var-PE'><filename>PE</filename></link> value.
  3935. If <filename>PE</filename> is set and greater than zero for a recipe,
  3936. <filename>EXTENDPE</filename> becomes that value (e.g if
  3937. <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
  3938. becomes "1_").
  3939. If a recipe's <filename>PE</filename> is not set (the default) or is equal to
  3940. zero, <filename>EXTENDPE</filename> becomes "".</para>
  3941. <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
  3942. variable for an example.
  3943. </para>
  3944. </glossdef>
  3945. </glossentry>
  3946. <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
  3947. <info>
  3948. EXTENDPKGV[doc] = "The full package version specification as it appears on the final packages produced by a recipe."
  3949. </info>
  3950. <glossdef>
  3951. <para role="glossdeffirst">
  3952. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3953. The full package version specification as it appears on the
  3954. final packages produced by a recipe.
  3955. The variable's value is normally used to fix a runtime
  3956. dependency to the exact same version of another package
  3957. in the same recipe:
  3958. <literallayout class='monospaced'>
  3959. RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
  3960. </literallayout>
  3961. </para>
  3962. <para>
  3963. The dependency relationships are intended to force the
  3964. package manager to upgrade these types of packages in
  3965. lock-step.
  3966. </para>
  3967. </glossdef>
  3968. </glossentry>
  3969. <glossentry id='var-EXTERNAL_KERNEL_TOOLS'><glossterm>EXTERNAL_KERNEL_TOOLS</glossterm>
  3970. <info>
  3971. EXTERNAL_KERNEL_TOOLS[doc] = "Indicates kernel tools are external to the source tree."
  3972. </info>
  3973. <glossdef>
  3974. <para role="glossdeffirst">
  3975. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  3976. When set, the <filename>EXTERNAL_KERNEL_TOOLS</filename>
  3977. variable indicates that these tools are not in the
  3978. source tree.
  3979. </para>
  3980. <para>
  3981. When kernel tools are available in the tree, they are
  3982. preferred over any externally installed tools.
  3983. Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename>
  3984. variable tells the OpenEmbedded build system to prefer
  3985. the installed external tools.
  3986. See the
  3987. <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
  3988. class in <filename>meta/classes</filename> to see how
  3989. the variable is used.
  3990. </para>
  3991. </glossdef>
  3992. </glossentry>
  3993. <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
  3994. <info>
  3995. EXTERNALSRC[doc] = "If externalsrc.bbclass is inherited, this variable points to the source tree, which is outside of the OpenEmbedded build system."
  3996. </info>
  3997. <glossdef>
  3998. <para role="glossdeffirst">
  3999. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4000. When inheriting the
  4001. <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
  4002. class, this variable points to the source tree, which is
  4003. outside of the OpenEmbedded build system.
  4004. When set, this variable sets the
  4005. <link linkend='var-S'><filename>S</filename></link>
  4006. variable, which is what the OpenEmbedded build system uses
  4007. to locate unpacked recipe source code.
  4008. </para>
  4009. <para>
  4010. For more information on
  4011. <filename>externalsrc.bbclass</filename>, see the
  4012. "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
  4013. section.
  4014. You can also find information on how to use this variable
  4015. in the
  4016. "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
  4017. section in the Yocto Project Development Tasks Manual.
  4018. </para>
  4019. </glossdef>
  4020. </glossentry>
  4021. <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
  4022. <info>
  4023. EXTERNALSRC_BUILD[doc] = "If externalsrc.bbclass is inherited, this variable points to the directory in which the recipe's source code is built, which is outside of the OpenEmbedded build system."
  4024. </info>
  4025. <glossdef>
  4026. <para role="glossdeffirst">
  4027. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4028. When inheriting the
  4029. <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
  4030. class, this variable points to the directory in which the
  4031. recipe's source code is built, which is outside of the
  4032. OpenEmbedded build system.
  4033. When set, this variable sets the
  4034. <link linkend='var-B'><filename>B</filename></link>
  4035. variable, which is what the OpenEmbedded build system uses
  4036. to locate the Build Directory.
  4037. </para>
  4038. <para>
  4039. For more information on
  4040. <filename>externalsrc.bbclass</filename>, see the
  4041. "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
  4042. section.
  4043. You can also find information on how to use this variable
  4044. in the
  4045. "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
  4046. section in the Yocto Project Development Tasks Manual.
  4047. </para>
  4048. </glossdef>
  4049. </glossentry>
  4050. <glossentry id='var-EXTRA_AUTORECONF'><glossterm>EXTRA_AUTORECONF</glossterm>
  4051. <info>
  4052. EXTRA_AUTORECONF[doc] = "Extra options passed to the autoreconf command, which is executed during do_configure."
  4053. </info>
  4054. <glossdef>
  4055. <para role="glossdeffirst">
  4056. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4057. For recipes inheriting the
  4058. <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
  4059. class, you can use <filename>EXTRA_AUTORECONF</filename> to
  4060. specify extra options to pass to the
  4061. <filename>autoreconf</filename> command that is
  4062. executed during the
  4063. <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
  4064. task.
  4065. </para>
  4066. <para>
  4067. The default value is "--exclude=autopoint".
  4068. </para>
  4069. </glossdef>
  4070. </glossentry>
  4071. <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
  4072. <info>
  4073. EXTRA_IMAGE_FEATURES[doc] = "The list of additional features to include in an image. Configure this variable in the conf/local.conf file in the Build Directory."
  4074. </info>
  4075. <glossdef>
  4076. <para role="glossdeffirst">
  4077. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4078. A list of additional features to include in an image.
  4079. When listing more than one feature, separate them with
  4080. a space.
  4081. </para>
  4082. <para>
  4083. Typically, you configure this variable in your
  4084. <filename>local.conf</filename> file, which is found in the
  4085. <link linkend='build-directory'>Build Directory</link>.
  4086. Although you can use this variable from within a recipe,
  4087. best practices dictate that you do not.
  4088. <note>
  4089. To enable primary features from within the image
  4090. recipe, use the
  4091. <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
  4092. variable.
  4093. </note>
  4094. </para>
  4095. <para>
  4096. Here are some examples of features you can add:
  4097. <literallayout class='monospaced'>
  4098. "dbg-pkgs" - Adds -dbg packages for all installed packages
  4099. including symbol information for debugging and
  4100. profiling.
  4101. "debug-tweaks" - Makes an image suitable for debugging.
  4102. For example, allows root logins without
  4103. passwords and enables post-installation
  4104. logging. See the 'allow-empty-password'
  4105. and 'post-install-logging' features in
  4106. the "<link linkend='ref-features-image'>Image Features</link>" section for
  4107. more information.
  4108. "dev-pkgs" - Adds -dev packages for all installed packages.
  4109. This is useful if you want to develop against
  4110. the libraries in the image.
  4111. "read-only-rootfs" - Creates an image whose root
  4112. filesystem is read-only. See the
  4113. "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
  4114. section in the Yocto Project
  4115. Development Tasks Manual for
  4116. more information
  4117. "tools-debug" - Adds debugging tools such as gdb and
  4118. strace.
  4119. "tools-sdk" - Adds development tools such as gcc, make,
  4120. pkgconfig and so forth.
  4121. "tools-testapps" - Adds useful testing tools such as
  4122. ts_print, aplay, arecord and so
  4123. forth.
  4124. </literallayout>
  4125. </para>
  4126. <para>
  4127. For a complete list of image features that ships with the
  4128. Yocto Project, see the
  4129. "<link linkend="ref-features-image">Image Features</link>"
  4130. section.
  4131. </para>
  4132. <para>
  4133. For an example that shows how to customize your image by
  4134. using this variable, see the
  4135. "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
  4136. section in the Yocto Project Development Tasks Manual.
  4137. </para>
  4138. </glossdef>
  4139. </glossentry>
  4140. <glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm>
  4141. <info>
  4142. EXTRA_IMAGECMD[doc] = "Specifies additional options for the image creation command that has been specified in IMAGE_CMD. When setting this variable, you should use an override for the associated image type."
  4143. </info>
  4144. <glossdef>
  4145. <para role="glossdeffirst">
  4146. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4147. Specifies additional options for the image
  4148. creation command that has been specified in
  4149. <link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>.
  4150. When setting this variable, use an override for the
  4151. associated image type.
  4152. Here is an example:
  4153. <literallayout class='monospaced'>
  4154. EXTRA_IMAGECMD_ext3 ?= "-i 4096"
  4155. </literallayout>
  4156. </para>
  4157. </glossdef>
  4158. </glossentry>
  4159. <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
  4160. <info>
  4161. EXTRA_IMAGEDEPENDS[doc] = "A list of recipes to build that do not provide packages for installing into the root filesystem. Use this variable to list recipes that are required to build the final image, but not needed in the root filesystem."
  4162. </info>
  4163. <glossdef>
  4164. <para role="glossdeffirst">
  4165. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4166. A list of recipes to build that do not provide packages
  4167. for installing into the root filesystem.
  4168. </para>
  4169. <para>
  4170. Sometimes a recipe is required to build the final image but is not
  4171. needed in the root filesystem.
  4172. You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
  4173. list these recipes and thus specify the dependencies.
  4174. A typical example is a required bootloader in a machine configuration.
  4175. </para>
  4176. <note>
  4177. To add packages to the root filesystem, see the various
  4178. <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
  4179. and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
  4180. variables.
  4181. </note>
  4182. </glossdef>
  4183. </glossentry>
  4184. <glossentry id='var-EXTRANATIVEPATH'><glossterm>EXTRANATIVEPATH</glossterm>
  4185. <info>
  4186. EXTRANATIVEPATH[doc] = "A list of subdirectories of ${STAGING_BINDIR_NATIVE} added to the beginning of the environment variable PATH."
  4187. </info>
  4188. <glossdef>
  4189. <para role="glossdeffirst">
  4190. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4191. A list of subdirectories of
  4192. <filename>${</filename><link linkend='var-STAGING_BINDIR_NATIVE'><filename>STAGING_BINDIR_NATIVE</filename></link><filename>}</filename>
  4193. added to the beginning of the environment variable
  4194. <filename>PATH</filename>.
  4195. As an example, the following prepends
  4196. "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:"
  4197. to <filename>PATH</filename>:
  4198. <literallayout class='monospaced'>
  4199. EXTRANATIVEPATH = "foo bar"
  4200. </literallayout>
  4201. </para>
  4202. </glossdef>
  4203. </glossentry>
  4204. <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
  4205. <info>
  4206. EXTRA_OECMAKE[doc] = "Additional cmake options."
  4207. </info>
  4208. <glossdef>
  4209. <para role="glossdeffirst">
  4210. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4211. Additional <filename>cmake</filename> options.
  4212. </para>
  4213. </glossdef>
  4214. </glossentry>
  4215. <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
  4216. <info>
  4217. EXTRA_OECONF[doc] = "Additional configure script options."
  4218. </info>
  4219. <glossdef>
  4220. <para role="glossdeffirst">
  4221. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4222. Additional <filename>configure</filename> script options.
  4223. See
  4224. <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
  4225. for additional information on passing configure script
  4226. options.
  4227. </para>
  4228. </glossdef>
  4229. </glossentry>
  4230. <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
  4231. <info>
  4232. EXTRA_OEMAKE[doc] = "Additional GNU make options."
  4233. </info>
  4234. <glossdef>
  4235. <para role="glossdeffirst">
  4236. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4237. Additional GNU <filename>make</filename> options.
  4238. </para>
  4239. <para>
  4240. Because the <filename>EXTRA_OEMAKE</filename> defaults to
  4241. "", you need to set the variable to specify any required
  4242. GNU options.
  4243. </para>
  4244. <para>
  4245. <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
  4246. and
  4247. <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></link>
  4248. also make use of
  4249. <filename>EXTRA_OEMAKE</filename> to pass the required
  4250. flags.
  4251. </para>
  4252. </glossdef>
  4253. </glossentry>
  4254. <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
  4255. <info>
  4256. EXTRA_OESCONS[doc] = "When a recipe inherits the scons class, this variable specifies additional configuration options you want to pass to the scons command line."
  4257. </info>
  4258. <glossdef>
  4259. <para role="glossdeffirst">
  4260. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4261. When inheriting the
  4262. <link linkend='ref-classes-scons'><filename>scons</filename></link>
  4263. class, this variable specifies additional configuration
  4264. options you want to pass to the
  4265. <filename>scons</filename> command line.
  4266. </para>
  4267. </glossdef>
  4268. </glossentry>
  4269. <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
  4270. <info>
  4271. EXTRA_USERS_PARAMS[doc] = "When a recipe inherits the extrausers class, this variable provides image level user and group operations."
  4272. </info>
  4273. <glossdef>
  4274. <para role="glossdeffirst">
  4275. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4276. When inheriting the
  4277. <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
  4278. class, this variable provides image level user and group
  4279. operations.
  4280. This is a more global method of providing user and group
  4281. configuration as compared to using the
  4282. <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
  4283. class, which ties user and group configurations to a
  4284. specific recipe.
  4285. </para>
  4286. <para>
  4287. The set list of commands you can configure using the
  4288. <filename>EXTRA_USERS_PARAMS</filename> is shown in the
  4289. <filename>extrausers</filename> class.
  4290. These commands map to the normal Unix commands of the same
  4291. names:
  4292. <literallayout class='monospaced'>
  4293. # EXTRA_USERS_PARAMS = "\
  4294. # useradd -p '' tester; \
  4295. # groupadd developers; \
  4296. # userdel nobody; \
  4297. # groupdel -g video; \
  4298. # groupmod -g 1020 developers; \
  4299. # usermod -s /bin/sh tester; \
  4300. # "
  4301. </literallayout>
  4302. </para>
  4303. </glossdef>
  4304. </glossentry>
  4305. </glossdiv>
  4306. <glossdiv id='var-glossary-f'><title>F</title>
  4307. <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
  4308. <info>
  4309. FEATURE_PACKAGES[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES. When setting the value, FEATURE_PACKAGES should have the name of the feature item as an override."
  4310. </info>
  4311. <glossdef>
  4312. <para role="glossdeffirst">
  4313. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4314. Defines one or more packages to include in an image when
  4315. a specific item is included in
  4316. <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
  4317. When setting the value, <filename>FEATURE_PACKAGES</filename>
  4318. should have the name of the feature item as an override.
  4319. Here is an example:
  4320. <literallayout class='monospaced'>
  4321. FEATURE_PACKAGES_widget = "<replaceable>package1</replaceable> <replaceable>package2</replaceable>"
  4322. </literallayout>
  4323. </para>
  4324. <para>
  4325. In this example, if "widget" were added to
  4326. <filename>IMAGE_FEATURES</filename>, <replaceable>package1</replaceable> and
  4327. <replaceable>package2</replaceable> would be included in the image.
  4328. <note>
  4329. Packages installed by features defined through
  4330. <filename>FEATURE_PACKAGES</filename> are often package
  4331. groups.
  4332. While similarly named, you should not confuse the
  4333. <filename>FEATURE_PACKAGES</filename> variable with
  4334. package groups, which are discussed elsewhere in the
  4335. documentation.
  4336. </note>
  4337. </para>
  4338. </glossdef>
  4339. </glossentry>
  4340. <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
  4341. <info>
  4342. FEED_DEPLOYDIR_BASE_URI[doc] = "Allow to serve ipk deploy directory as an ad hoc feed (bogofeed). Set to base URL of the directory as exported by HTTP. Set of ad hoc feed configs will be generated in the image."
  4343. </info>
  4344. <glossdef>
  4345. <para role="glossdeffirst">
  4346. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4347. Points to the base URL of the server and location within
  4348. the document-root that provides the metadata and
  4349. packages required by OPKG to support runtime package
  4350. management of IPK packages.
  4351. You set this variable in your
  4352. <filename>local.conf</filename> file.
  4353. </para>
  4354. <para>
  4355. Consider the following example:
  4356. <literallayout class='monospaced'>
  4357. FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
  4358. </literallayout>
  4359. This example assumes you are serving your packages over
  4360. HTTP and your databases are located in a directory
  4361. named <filename>BOARD-dir</filename>, which is underneath
  4362. your HTTP server's document-root.
  4363. In this case, the OpenEmbedded build system generates a set
  4364. of configuration files for you in your target that work
  4365. with the feed.
  4366. </para>
  4367. </glossdef>
  4368. </glossentry>
  4369. <glossentry id='var-FILES'><glossterm>FILES</glossterm>
  4370. <info>
  4371. FILES[doc] = "The list of directories or files that are placed in a package."
  4372. </info>
  4373. <glossdef>
  4374. <para role="glossdeffirst">
  4375. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4376. The list of files and directories that are placed in a
  4377. package.
  4378. The
  4379. <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
  4380. variable lists the packages generated by a recipe.
  4381. </para>
  4382. <para>
  4383. To use the <filename>FILES</filename> variable, provide a
  4384. package name override that identifies the resulting package.
  4385. Then, provide a space-separated list of files or paths
  4386. that identify the files you want included as part of the
  4387. resulting package.
  4388. Here is an example:
  4389. <literallayout class='monospaced'>
  4390. FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
  4391. </literallayout>
  4392. </para>
  4393. <note>
  4394. When specifying paths as part of the
  4395. <filename>FILES</filename> variable, it is good practice
  4396. to use appropriate path variables.
  4397. For example, use <filename>${sysconfdir}</filename> rather
  4398. than <filename>/etc</filename>, or
  4399. <filename>${bindir}</filename> rather than
  4400. <filename>/usr/bin</filename>.
  4401. You can find a list of these variables at the top of the
  4402. <filename>meta/conf/bitbake.conf</filename> file in the
  4403. <link linkend='source-directory'>Source Directory</link>.
  4404. You will also find the default values of the various
  4405. <filename>FILES_*</filename> variables in this file.
  4406. </note>
  4407. <para>
  4408. If some of the files you provide with the
  4409. <filename>FILES</filename> variable are editable and you
  4410. know they should not be overwritten during the package
  4411. update process by the Package Management System (PMS), you
  4412. can identify these files so that the PMS will not
  4413. overwrite them.
  4414. See the
  4415. <link linkend='var-CONFFILES'><filename>CONFFILES</filename></link>
  4416. variable for information on how to identify these files to
  4417. the PMS.
  4418. </para>
  4419. </glossdef>
  4420. </glossentry>
  4421. <glossentry id='var-FILES_SOLIBSDEV'><glossterm>FILES_SOLIBSDEV</glossterm>
  4422. <info>
  4423. FILES_SOLIBSDEV[doc] = "Defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform."
  4424. </info>
  4425. <glossdef>
  4426. <para role="glossdeffirst">
  4427. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4428. Defines the file specification to match
  4429. <link linkend='var-SOLIBSDEV'><filename>SOLIBSDEV</filename></link>.
  4430. In other words, <filename>FILES_SOLIBSDEV</filename>
  4431. defines the full path name of the development symbolic link
  4432. (symlink) for shared libraries on the target platform.
  4433. </para>
  4434. <para>
  4435. The following statement from the
  4436. <filename>bitbake.conf</filename> shows how it is set:
  4437. <literallayout class='monospaced'>
  4438. FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
  4439. </literallayout>
  4440. </para>
  4441. </glossdef>
  4442. </glossentry>
  4443. <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
  4444. <info>
  4445. FILESEXTRAPATHS[doc] = "Extends the search path the OpenEmbedded build system uses when looking for files and patches as it processes recipes and append files."
  4446. </info>
  4447. <glossdef>
  4448. <para role="glossdeffirst">
  4449. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4450. Extends the search path the OpenEmbedded build system uses
  4451. when looking for files and patches as it processes recipes
  4452. and append files.
  4453. The default directories BitBake uses when it processes
  4454. recipes are initially defined by the
  4455. <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
  4456. variable.
  4457. You can extend <filename>FILESPATH</filename> variable
  4458. by using <filename>FILESEXTRAPATHS</filename>.
  4459. </para>
  4460. <para>
  4461. Best practices dictate that you accomplish this by using
  4462. <filename>FILESEXTRAPATHS</filename> from within a
  4463. <filename>.bbappend</filename> file and that you prepend
  4464. paths as follows:
  4465. <literallayout class='monospaced'>
  4466. FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
  4467. </literallayout>
  4468. In the above example, the build system first looks for files
  4469. in a directory that has the same name as the corresponding
  4470. append file.
  4471. <note>
  4472. <para>When extending
  4473. <filename>FILESEXTRAPATHS</filename>,
  4474. be sure to use the immediate expansion
  4475. (<filename>:=</filename>) operator.
  4476. Immediate expansion makes sure that BitBake evaluates
  4477. <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
  4478. at the time the directive is encountered rather than at
  4479. some later time when expansion might result in a
  4480. directory that does not contain the files you need.
  4481. </para>
  4482. <para>Also, include the trailing separating colon
  4483. character if you are prepending.
  4484. The trailing colon character is necessary because you
  4485. are directing BitBake to extend the path by prepending
  4486. directories to the search path.</para>
  4487. </note>
  4488. Here is another common use:
  4489. <literallayout class='monospaced'>
  4490. FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
  4491. </literallayout>
  4492. In this example, the build system extends the
  4493. <filename>FILESPATH</filename> variable to include a
  4494. directory named <filename>files</filename> that is in the
  4495. same directory as the corresponding append file.
  4496. </para>
  4497. <para>
  4498. This next example specifically adds three paths:
  4499. <literallayout class='monospaced'>
  4500. FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
  4501. </literallayout>
  4502. </para>
  4503. <para>
  4504. A final example shows how you can extend the search path
  4505. and include a
  4506. <link linkend='var-MACHINE'><filename>MACHINE</filename></link>-specific
  4507. override, which is useful in a BSP layer:
  4508. <literallayout class='monospaced'>
  4509. FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:"
  4510. </literallayout>
  4511. The previous statement appears in the
  4512. <filename>linux-yocto-dev.bbappend</filename> file, which
  4513. is found in the Yocto Project
  4514. <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
  4515. in
  4516. <filename>meta-intel/common/recipes-kernel/linux</filename>.
  4517. Here, the machine override is a special
  4518. <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
  4519. definition for multiple <filename>meta-intel</filename>
  4520. machines.
  4521. <note>
  4522. For a layer that supports a single BSP, the override
  4523. could just be the value of <filename>MACHINE</filename>.
  4524. </note>
  4525. </para>
  4526. <para>
  4527. By prepending paths in <filename>.bbappend</filename>
  4528. files, you allow multiple append files that reside in
  4529. different layers but are used for the same recipe to
  4530. correctly extend the path.
  4531. </para>
  4532. </glossdef>
  4533. </glossentry>
  4534. <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
  4535. <info>
  4536. FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH."
  4537. </info>
  4538. <glossdef>
  4539. <para role="glossdeffirst">
  4540. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4541. A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
  4542. used by the OpenEmbedded build system for creating
  4543. <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
  4544. You can find more information on how overrides are handled
  4545. in the
  4546. <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake Manual</ulink>.
  4547. </para>
  4548. <para>
  4549. By default, the <filename>FILESOVERRIDES</filename>
  4550. variable is defined as:
  4551. <literallayout class='monospaced'>
  4552. FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
  4553. </literallayout>
  4554. <note>
  4555. Do not hand-edit the <filename>FILESOVERRIDES</filename>
  4556. variable.
  4557. The values match up with expected overrides and are
  4558. used in an expected manner by the build system.
  4559. </note>
  4560. </para>
  4561. </glossdef>
  4562. </glossentry>
  4563. <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
  4564. <info>
  4565. FILESPATH[doc] = "The default set of directories the OpenEmbedded build system uses when searching for patches and files. It is defined in the base.bbclass class found in meta/classes in the Source Directory. Do not hand-edit the FILESPATH variable."
  4566. </info>
  4567. <glossdef>
  4568. <para role="glossdeffirst">
  4569. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4570. The default set of directories the OpenEmbedded build system
  4571. uses when searching for patches and files.
  4572. During the build process, BitBake searches each directory in
  4573. <filename>FILESPATH</filename> in the specified order when
  4574. looking for files and patches specified by each
  4575. <filename>file://</filename> URI in a recipe.
  4576. </para>
  4577. <para>
  4578. The default value for the <filename>FILESPATH</filename>
  4579. variable is defined in the <filename>base.bbclass</filename>
  4580. class found in <filename>meta/classes</filename> in the
  4581. <link linkend='source-directory'>Source Directory</link>:
  4582. <literallayout class='monospaced'>
  4583. FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
  4584. "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
  4585. </literallayout>
  4586. <note>
  4587. Do not hand-edit the <filename>FILESPATH</filename>
  4588. variable.
  4589. If you want the build system to look in directories
  4590. other than the defaults, extend the
  4591. <filename>FILESPATH</filename> variable by using the
  4592. <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
  4593. variable.
  4594. </note>
  4595. Be aware that the default <filename>FILESPATH</filename>
  4596. directories do not map to directories in custom layers
  4597. where append files (<filename>.bbappend</filename>)
  4598. are used.
  4599. If you want the build system to find patches or files
  4600. that reside with your append files, you need to extend
  4601. the <filename>FILESPATH</filename> variable by using
  4602. the
  4603. <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
  4604. variable.
  4605. </para>
  4606. </glossdef>
  4607. </glossentry>
  4608. <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
  4609. <info>
  4610. FILESYSTEM_PERMS_TABLES[doc] = "Allows you to define your own file permissions settings table as part of your configuration for the packaging process."
  4611. </info>
  4612. <glossdef>
  4613. <para role="glossdeffirst">
  4614. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4615. Allows you to define your own file permissions settings table as part of
  4616. your configuration for the packaging process.
  4617. For example, suppose you need a consistent set of custom permissions for
  4618. a set of groups and users across an entire work project.
  4619. It is best to do this in the packages themselves but this is not always
  4620. possible.
  4621. </para>
  4622. <para>
  4623. By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
  4624. is located in the <filename>meta/files</filename> folder in the
  4625. <link linkend='source-directory'>Source Directory</link>.
  4626. If you create your own file permissions setting table, you should place it in your
  4627. layer or the distro's layer.
  4628. </para>
  4629. <para>
  4630. You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
  4631. <filename>conf/local.conf</filename> file, which is found in the
  4632. <link linkend='build-directory'>Build Directory</link>, to
  4633. point to your custom <filename>fs-perms.txt</filename>.
  4634. You can specify more than a single file permissions setting table.
  4635. The paths you specify to these files must be defined within the
  4636. <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
  4637. </para>
  4638. <para>
  4639. For guidance on how to create your own file permissions settings table file,
  4640. examine the existing <filename>fs-perms.txt</filename>.
  4641. </para>
  4642. </glossdef>
  4643. </glossentry>
  4644. <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm>
  4645. <info>
  4646. FONT_EXTRA_RDEPENDS[doc] = "When a recipe inherits the fontcache class, this variable specifies runtime dependencies for font packages. This variable defaults to 'fontconfig-utils'."
  4647. </info>
  4648. <glossdef>
  4649. <para role="glossdeffirst">
  4650. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4651. When inheriting the
  4652. <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
  4653. class, this variable specifies the runtime dependencies
  4654. for font packages.
  4655. By default, the <filename>FONT_EXTRA_RDEPENDS</filename>
  4656. is set to "fontconfig-utils".
  4657. </para>
  4658. </glossdef>
  4659. </glossentry>
  4660. <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
  4661. <info>
  4662. FONT_PACKAGES[doc] = "When a recipe inherits the fontcache class, this variable identifies packages containing font files that need to be cached by Fontconfig."
  4663. </info>
  4664. <glossdef>
  4665. <para role="glossdeffirst">
  4666. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4667. When inheriting the
  4668. <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
  4669. class, this variable identifies packages containing font
  4670. files that need to be cached by Fontconfig.
  4671. By default, the <filename>fontcache</filename> class assumes
  4672. that fonts are in the recipe's main package
  4673. (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
  4674. Use this variable if fonts you need are in a package
  4675. other than that main package.
  4676. </para>
  4677. </glossdef>
  4678. </glossentry>
  4679. <glossentry id='var-FORCE_RO_REMOVE'><glossterm>FORCE_RO_REMOVE</glossterm>
  4680. <info>
  4681. FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem."
  4682. </info>
  4683. <glossdef>
  4684. <para role="glossdeffirst">
  4685. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4686. Forces the removal of the packages listed in
  4687. <filename>ROOTFS_RO_UNNEEDED</filename> during the
  4688. generation of the root filesystem.
  4689. </para>
  4690. <para>
  4691. Set the variable to "1" to force the removal of these
  4692. packages.
  4693. </para>
  4694. </glossdef>
  4695. </glossentry>
  4696. <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
  4697. <info>
  4698. FULL_OPTIMIZATION[doc]= "The options to pass in TARGET_CFLAGS and CFLAGS when compiling an optimized system. This variable defaults to '-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2'."
  4699. </info>
  4700. <glossdef>
  4701. <para role="glossdeffirst">
  4702. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4703. The options to pass in
  4704. <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
  4705. and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
  4706. when compiling an optimized system.
  4707. This variable defaults to
  4708. "-O2 -pipe ${DEBUG_FLAGS}".
  4709. </para>
  4710. </glossdef>
  4711. </glossentry>
  4712. </glossdiv>
  4713. <glossdiv id='var-glossary-g'><title>G</title>
  4714. <glossentry id='var-GCCPIE'><glossterm>GCCPIE</glossterm>
  4715. <info>
  4716. GCCPIE[doc] = "Enables Position Independent Executables (PIE) within the GNU C Compiler (GCC)."
  4717. </info>
  4718. <glossdef>
  4719. <para role="glossdeffirst">
  4720. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4721. Enables Position Independent Executables (PIE) within the
  4722. GNU C Compiler (GCC).
  4723. Enabling PIE in the GCC makes Return Oriented Programming
  4724. (ROP) attacks much more difficult to
  4725. execute.
  4726. </para>
  4727. <para>
  4728. By default the <filename>security_flags.inc</filename>
  4729. file enables PIE by setting the variable as follows:
  4730. <literallayout class='monospaced'>
  4731. GCCPIE ?= "--enable-default-pie"
  4732. </literallayout>
  4733. </para>
  4734. </glossdef>
  4735. </glossentry>
  4736. <glossentry id='var-GDB'><glossterm>GDB</glossterm>
  4737. <info>
  4738. GDB[doc] = "The minimal command and arguments to run the GNU Debugger."
  4739. </info>
  4740. <glossdef>
  4741. <para role="glossdeffirst">
  4742. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4743. The minimal command and arguments to run the GNU Debugger.
  4744. </para>
  4745. </glossdef>
  4746. </glossentry>
  4747. <glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm>
  4748. <info>
  4749. GITDIR[doc] = "The directory where Git clones will be stored."
  4750. </info>
  4751. <glossdef>
  4752. <para role="glossdeffirst">
  4753. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4754. The directory in which a local copy of a Git repository
  4755. is stored when it is cloned.
  4756. </para>
  4757. </glossdef>
  4758. </glossentry>
  4759. <glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm>GLIBC_GENERATE_LOCALES</glossterm>
  4760. <info>
  4761. GLIBC_GENERATE_LOCALES[doc]= "Specifies the list of GLIBC locales to generate should you not wish to generate all LIBC locals, which can be time consuming."
  4762. </info>
  4763. <glossdef>
  4764. <para role="glossdeffirst">
  4765. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4766. Specifies the list of GLIBC locales to generate should you
  4767. not wish to generate all LIBC locals, which can be time
  4768. consuming.
  4769. <note>
  4770. If you specifically remove the locale
  4771. <filename>en_US.UTF-8</filename>, you must set
  4772. <link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>
  4773. appropriately.
  4774. </note>
  4775. </para>
  4776. <para>
  4777. You can set <filename>GLIBC_GENERATE_LOCALES</filename>
  4778. in your <filename>local.conf</filename> file.
  4779. By default, all locales are generated.
  4780. <literallayout class='monospaced'>
  4781. GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
  4782. </literallayout>
  4783. </para>
  4784. </glossdef>
  4785. </glossentry>
  4786. <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
  4787. <info>
  4788. GROUPADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the groupadd command if you wish to add a group to the system when the package is installed."
  4789. </info>
  4790. <glossdef>
  4791. <para role="glossdeffirst">
  4792. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4793. When inheriting the
  4794. <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
  4795. class, this variable
  4796. specifies for a package what parameters should be passed
  4797. to the <filename>groupadd</filename> command
  4798. if you wish to add a group to the system when the package
  4799. is installed.
  4800. </para>
  4801. <para>
  4802. Here is an example from the <filename>dbus</filename>
  4803. recipe:
  4804. <literallayout class='monospaced'>
  4805. GROUPADD_PARAM_${PN} = "-r netdev"
  4806. </literallayout>
  4807. For information on the standard Linux shell command
  4808. <filename>groupadd</filename>, see
  4809. <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
  4810. </para>
  4811. </glossdef>
  4812. </glossentry>
  4813. <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
  4814. <info>
  4815. GROUPMEMS_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the groupmems command if you wish to modify the members of a group when the package is installed."
  4816. </info>
  4817. <glossdef>
  4818. <para role="glossdeffirst">
  4819. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4820. When inheriting the
  4821. <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
  4822. class, this variable
  4823. specifies for a package what parameters should be passed
  4824. to the <filename>groupmems</filename> command
  4825. if you wish to modify the members of a group when the
  4826. package is installed.
  4827. </para>
  4828. <para>
  4829. For information on the standard Linux shell command
  4830. <filename>groupmems</filename>, see
  4831. <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
  4832. </para>
  4833. </glossdef>
  4834. </glossentry>
  4835. <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
  4836. <info>
  4837. GRUB_GFXSERIAL[doc] = "Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu."
  4838. </info>
  4839. <glossdef>
  4840. <para role="glossdeffirst">
  4841. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4842. Configures the GNU GRand Unified Bootloader (GRUB) to have
  4843. graphics and serial in the boot menu.
  4844. Set this variable to "1" in your
  4845. <filename>local.conf</filename> or distribution
  4846. configuration file to enable graphics and serial
  4847. in the menu.
  4848. </para>
  4849. <para>
  4850. See the
  4851. <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
  4852. class for more information on how this variable is used.
  4853. </para>
  4854. </glossdef>
  4855. </glossentry>
  4856. <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
  4857. <info>
  4858. GRUB_OPTS[doc] = "Additional options to add to the GNU GRand Unified Bootloader (GRUB) configuration."
  4859. </info>
  4860. <glossdef>
  4861. <para role="glossdeffirst">
  4862. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4863. Additional options to add to the GNU GRand Unified
  4864. Bootloader (GRUB) configuration.
  4865. Use a semi-colon character (<filename>;</filename>) to
  4866. separate multiple options.
  4867. </para>
  4868. <para>
  4869. The <filename>GRUB_OPTS</filename> variable is optional.
  4870. See the
  4871. <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
  4872. class for more information on how this variable is used.
  4873. </para>
  4874. </glossdef>
  4875. </glossentry>
  4876. <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
  4877. <info>
  4878. GRUB_TIMEOUT[doc] = "Specifies the timeout before executing the default LABEL in the GNU GRand Unified Bootloader (GRUB)."
  4879. </info>
  4880. <glossdef>
  4881. <para role="glossdeffirst">
  4882. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4883. Specifies the timeout before executing the default
  4884. <filename>LABEL</filename> in the GNU GRand Unified
  4885. Bootloader (GRUB).
  4886. </para>
  4887. <para>
  4888. The <filename>GRUB_TIMEOUT</filename> variable is optional.
  4889. See the
  4890. <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
  4891. class for more information on how this variable is used.
  4892. </para>
  4893. </glossdef>
  4894. </glossentry>
  4895. <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
  4896. <info>
  4897. GTKIMMODULES_PACKAGES[doc] = "For recipes that inherit the gtk-immodules-cache class, this variable specifies the packages that contain the GTK+ input method modules being installed when the modules are in packages other than the main package."
  4898. </info>
  4899. <glossdef>
  4900. <para role="glossdeffirst">
  4901. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4902. When inheriting the
  4903. <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
  4904. class, this variable specifies the packages that contain the
  4905. GTK+ input method modules being installed when the modules
  4906. are in packages other than the main package.
  4907. </para>
  4908. </glossdef>
  4909. </glossentry>
  4910. </glossdiv>
  4911. <glossdiv id='var-glossary-h'><title>H</title>
  4912. <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
  4913. <info>
  4914. HOMEPAGE[doc] = "Website where more information about the software the recipe is building can be found."
  4915. </info>
  4916. <glossdef>
  4917. <para role="glossdeffirst">
  4918. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4919. Website where more information about the software the recipe is building
  4920. can be found.
  4921. </para>
  4922. </glossdef>
  4923. </glossentry>
  4924. <glossentry id='var-HOST_ARCH'><glossterm>HOST_ARCH</glossterm>
  4925. <info>
  4926. HOST_ARCH[doc] = "The name of the target architecture. Normally same as the TARGET_ARCH."
  4927. </info>
  4928. <glossdef>
  4929. <para role="glossdeffirst">
  4930. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4931. The name of the target architecture, which is normally
  4932. the same as
  4933. <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
  4934. The OpenEmbedded build system supports many
  4935. architectures.
  4936. Here is an example list of architectures supported.
  4937. This list is by no means complete as the architecture
  4938. is configurable:
  4939. <literallayout class='monospaced'>
  4940. arm
  4941. i586
  4942. x86_64
  4943. powerpc
  4944. powerpc64
  4945. mips
  4946. mipsel
  4947. </literallayout>
  4948. </para>
  4949. </glossdef>
  4950. </glossentry>
  4951. <glossentry id='var-HOST_CC_ARCH'><glossterm>HOST_CC_ARCH</glossterm>
  4952. <info>
  4953. HOST_CC_ARCH[doc] = "The name of the host architecture. Normally same as the TARGET_CC_ARCH."
  4954. </info>
  4955. <glossdef>
  4956. <para role="glossdeffirst">
  4957. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4958. Specifies architecture-specific compiler flags that are
  4959. passed to the C compiler.
  4960. </para>
  4961. <para>
  4962. Default initialization for <filename>HOST_CC_ARCH</filename>
  4963. varies depending on what is being built:
  4964. <itemizedlist>
  4965. <listitem><para>
  4966. <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
  4967. when building for the target
  4968. </para></listitem>
  4969. <listitem><para>
  4970. <filename>BUILD_CC_ARCH</filename>
  4971. when building for the build host (i.e.
  4972. <filename>-native</filename>)
  4973. </para></listitem>
  4974. <listitem><para>
  4975. <filename>BUILDSDK_CC_ARCH</filename>
  4976. when building for an SDK (i.e.
  4977. <filename>nativesdk-</filename>)
  4978. </para></listitem>
  4979. </itemizedlist>
  4980. </para>
  4981. </glossdef>
  4982. </glossentry>
  4983. <glossentry id='var-HOST_OS'><glossterm>HOST_OS</glossterm>
  4984. <info>
  4985. HOST_OS[doc] = "The name of the target operating system. Normally the same as the TARGET_OS."
  4986. </info>
  4987. <glossdef>
  4988. <para role="glossdeffirst">
  4989. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  4990. Specifies the name of the target operating system, which
  4991. is normally the same as the
  4992. <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>.
  4993. The variable can be set to "linux" for <filename>glibc</filename>-based systems and
  4994. to "linux-musl" for <filename>musl</filename>.
  4995. For ARM/EABI targets, there are also "linux-gnueabi" and
  4996. "linux-musleabi" values possible.
  4997. </para>
  4998. </glossdef>
  4999. </glossentry>
  5000. <glossentry id='var-HOST_PREFIX'><glossterm>HOST_PREFIX</glossterm>
  5001. <info>
  5002. HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX."
  5003. </info>
  5004. <glossdef>
  5005. <para role="glossdeffirst">
  5006. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5007. Specifies the prefix for the cross-compile toolchain.
  5008. <filename>HOST_PREFIX</filename> is normally the same as
  5009. <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>.
  5010. </para>
  5011. </glossdef>
  5012. </glossentry>
  5013. <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
  5014. <info>
  5015. HOST_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the build is occurring in the context of the current recipe."
  5016. </info>
  5017. <glossdef>
  5018. <para role="glossdeffirst">
  5019. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5020. Specifies the system, including the architecture and the
  5021. operating system, for which the build is occurring
  5022. in the context of the current recipe.
  5023. </para>
  5024. <para>
  5025. The OpenEmbedded build system automatically sets this
  5026. variable based on
  5027. <link linkend='var-HOST_ARCH'><filename>HOST_ARCH</filename></link>,
  5028. <link linkend='var-HOST_VENDOR'><filename>HOST_VENDOR</filename></link>,
  5029. and
  5030. <link linkend='var-HOST_OS'><filename>HOST_OS</filename></link>
  5031. variables.
  5032. <note>
  5033. You do not need to set the variable yourself.
  5034. </note>
  5035. </para>
  5036. <para>
  5037. Consider these two examples:
  5038. <itemizedlist>
  5039. <listitem><para>Given a native recipe on a 32-bit
  5040. x86 machine running Linux, the value is
  5041. "i686-linux".
  5042. </para></listitem>
  5043. <listitem><para>Given a recipe being built for a
  5044. little-endian MIPS target running Linux,
  5045. the value might be "mipsel-linux".
  5046. </para></listitem>
  5047. </itemizedlist>
  5048. </para>
  5049. </glossdef>
  5050. </glossentry>
  5051. <glossentry id='var-HOSTTOOLS'><glossterm>HOSTTOOLS</glossterm>
  5052. <info>
  5053. HOSTTOOLS[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."
  5054. </info>
  5055. <glossdef>
  5056. <para role="glossdeffirst">
  5057. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5058. A space-separated list (filter) of tools on the build host
  5059. that should be allowed to be called from within build tasks.
  5060. Using this filter helps reduce the possibility of host
  5061. contamination.
  5062. If a tool specified in the value of
  5063. <filename>HOSTTOOLS</filename> is not found on the
  5064. build host, the OpenEmbedded build system produces
  5065. an error and the build is not started.
  5066. </para>
  5067. <para>
  5068. For additional information, see
  5069. <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>.
  5070. </para>
  5071. </glossdef>
  5072. </glossentry>
  5073. <glossentry id='var-HOSTTOOLS_NONFATAL'><glossterm>HOSTTOOLS_NONFATAL</glossterm>
  5074. <info>
  5075. HOSTTOOLS_NONFATAL[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."
  5076. </info>
  5077. <glossdef>
  5078. <para role="glossdeffirst">
  5079. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5080. A space-separated list (filter) of tools on the build host
  5081. that should be allowed to be called from within build tasks.
  5082. Using this filter helps reduce the possibility of host
  5083. contamination.
  5084. Unlike
  5085. <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>,
  5086. the OpenEmbedded build system does not produce an error
  5087. if a tool specified in the value of
  5088. <filename>HOSTTOOLS_NONFATAL</filename> is not found on the
  5089. build host.
  5090. Thus, you can use <filename>HOSTTOOLS_NONFATAL</filename>
  5091. to filter optional host tools.
  5092. </para>
  5093. </glossdef>
  5094. </glossentry>
  5095. <glossentry id='var-HOST_VENDOR'><glossterm>HOST_VENDOR</glossterm>
  5096. <info>
  5097. HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR."
  5098. </info>
  5099. <glossdef>
  5100. <para role="glossdeffirst">
  5101. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5102. Specifies the name of the vendor.
  5103. <filename>HOST_VENDOR</filename> is normally the same as
  5104. <link linkend='var-TARGET_PREFIX'><filename>TARGET_VENDOR</filename></link>.
  5105. </para>
  5106. </glossdef>
  5107. </glossentry>
  5108. </glossdiv>
  5109. <glossdiv id='var-glossary-i'><title>I</title>
  5110. <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
  5111. <info>
  5112. ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function."
  5113. </info>
  5114. <glossdef>
  5115. <para role="glossdeffirst">
  5116. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5117. Disables or enables the <filename>icecc</filename>
  5118. (Icecream) function.
  5119. For more information on this function and best practices
  5120. for using this variable, see the
  5121. "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
  5122. section.
  5123. </para>
  5124. <para>
  5125. Setting this variable to "1" in your
  5126. <filename>local.conf</filename> disables the function:
  5127. <literallayout class='monospaced'>
  5128. ICECC_DISABLED ??= "1"
  5129. </literallayout>
  5130. To enable the function, set the variable as follows:
  5131. <literallayout class='monospaced'>
  5132. ICECC_DISABLED = ""
  5133. </literallayout>
  5134. </para>
  5135. </glossdef>
  5136. </glossentry>
  5137. <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
  5138. <info>
  5139. ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide."
  5140. </info>
  5141. <glossdef>
  5142. <para role="glossdeffirst">
  5143. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5144. Points to the <filename>icecc-create-env</filename> script
  5145. that you provide.
  5146. This variable is used by the
  5147. <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
  5148. class.
  5149. You set this variable in your
  5150. <filename>local.conf</filename> file.
  5151. </para>
  5152. <para>
  5153. If you do not point to a script that you provide, the
  5154. OpenEmbedded build system uses the default script provided
  5155. by the <filename>icecc-create-env.bb</filename> recipe,
  5156. which is a modified version and not the one that comes with
  5157. <filename>icecc</filename>.
  5158. </para>
  5159. </glossdef>
  5160. </glossentry>
  5161. <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
  5162. <info>
  5163. ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation."
  5164. </info>
  5165. <glossdef>
  5166. <para role="glossdeffirst">
  5167. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5168. Extra options passed to the <filename>make</filename>
  5169. command during the
  5170. <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
  5171. task that specify parallel compilation.
  5172. This variable usually takes the form of
  5173. "-j <replaceable>x</replaceable>", where
  5174. <replaceable>x</replaceable> represents the maximum
  5175. number of parallel threads <filename>make</filename> can
  5176. run.
  5177. <note>
  5178. The options passed affect builds on all enabled
  5179. machines on the network, which are machines running the
  5180. <filename>iceccd</filename> daemon.
  5181. </note>
  5182. </para>
  5183. <para>
  5184. If your enabled machines support multiple cores,
  5185. coming up with the maximum number of parallel threads
  5186. that gives you the best performance could take some
  5187. experimentation since machine speed, network lag,
  5188. available memory, and existing machine loads can all
  5189. affect build time.
  5190. Consequently, unlike the
  5191. <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
  5192. variable, there is no rule-of-thumb for setting
  5193. <filename>ICECC_PARALLEL_MAKE</filename> to achieve
  5194. optimal performance.
  5195. </para>
  5196. <para>
  5197. If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
  5198. the build system does not use it (i.e. the system does
  5199. not detect and assign the number of cores as is done with
  5200. <filename>PARALLEL_MAKE</filename>).
  5201. </para>
  5202. </glossdef>
  5203. </glossentry>
  5204. <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
  5205. <info>
  5206. ICECC_PATH[doc] = "The location of the icecc binary."
  5207. </info>
  5208. <glossdef>
  5209. <para role="glossdeffirst">
  5210. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5211. The location of the <filename>icecc</filename> binary.
  5212. You can set this variable in your
  5213. <filename>local.conf</filename> file.
  5214. If your <filename>local.conf</filename> file does not define
  5215. this variable, the
  5216. <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
  5217. class attempts to define it by locating
  5218. <filename>icecc</filename> using <filename>which</filename>.
  5219. </para>
  5220. </glossdef>
  5221. </glossentry>
  5222. <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
  5223. <info>
  5224. ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider."
  5225. </info>
  5226. <glossdef>
  5227. <para role="glossdeffirst">
  5228. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5229. Identifies user classes that you do not want the
  5230. Icecream distributed compile support to consider.
  5231. This variable is used by the
  5232. <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
  5233. class.
  5234. You set this variable in your
  5235. <filename>local.conf</filename> file.
  5236. </para>
  5237. <para>
  5238. When you list classes using this variable, you are
  5239. "blacklisting" them from distributed compilation across
  5240. remote hosts.
  5241. Any classes you list will be distributed and compiled
  5242. locally.
  5243. </para>
  5244. </glossdef>
  5245. </glossentry>
  5246. <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
  5247. <info>
  5248. ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider."
  5249. </info>
  5250. <glossdef>
  5251. <para role="glossdeffirst">
  5252. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5253. Identifies user recipes that you do not want the
  5254. Icecream distributed compile support to consider.
  5255. This variable is used by the
  5256. <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
  5257. class.
  5258. You set this variable in your
  5259. <filename>local.conf</filename> file.
  5260. </para>
  5261. <para>
  5262. When you list packages using this variable, you are
  5263. "blacklisting" them from distributed compilation across
  5264. remote hosts.
  5265. Any packages you list will be distributed and compiled
  5266. locally.
  5267. </para>
  5268. </glossdef>
  5269. </glossentry>
  5270. <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
  5271. <info>
  5272. ICECC_USER_PACKAGE_WL[doc] = "Identifies user recipes that use an empty PARALLEL_MAKE variable that you want to force remote distributed compilation on using the Icecream distributed compile support."
  5273. </info>
  5274. <glossdef>
  5275. <para role="glossdeffirst">
  5276. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5277. Identifies user recipes that use an empty
  5278. <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
  5279. variable that you want to force remote distributed
  5280. compilation on using the Icecream distributed compile
  5281. support.
  5282. This variable is used by the
  5283. <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
  5284. class.
  5285. You set this variable in your
  5286. <filename>local.conf</filename> file.
  5287. </para>
  5288. </glossdef>
  5289. </glossentry>
  5290. <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
  5291. <info>
  5292. IMAGE_BASENAME[doc] = "The base name of image output files."
  5293. </info>
  5294. <glossdef>
  5295. <para role="glossdeffirst">
  5296. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5297. The base name of image output files.
  5298. This variable defaults to the recipe name
  5299. (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
  5300. </para>
  5301. </glossdef>
  5302. </glossentry>
  5303. <glossentry id='var-IMAGE_BOOT_FILES'><glossterm>IMAGE_BOOT_FILES</glossterm>
  5304. <info>
  5305. IMAGE_BOOT_FILES[doc] = "A space-separated list of files from ${DEPLOY_DIR_IMAGE} to place in boot partition."
  5306. </info>
  5307. <glossdef>
  5308. <para role="glossdeffirst">
  5309. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5310. A space-separated list of files installed into the
  5311. boot partition when preparing an image using the Wic tool
  5312. with the <filename>bootimg-partition</filename> source
  5313. plugin.
  5314. By default, the files are installed under the same name as
  5315. the source files.
  5316. To change the installed name, separate it from the
  5317. original name with a semi-colon (;).
  5318. Source files need to be located in
  5319. <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>.
  5320. Here are two examples:
  5321. <literallayout class="monospaced">
  5322. IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
  5323. IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
  5324. </literallayout>
  5325. </para>
  5326. <para>
  5327. Alternatively, source files can be picked up using
  5328. a glob pattern.
  5329. In this case, the destination file must have the same name
  5330. as the base name of the source file path.
  5331. To install files into a directory within the
  5332. target location, pass its name after a semi-colon
  5333. (;).
  5334. Here are two examples:
  5335. <literallayout class="monospaced">
  5336. IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
  5337. IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
  5338. </literallayout>
  5339. The first example installs all files from
  5340. <filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename>
  5341. into the root of the target partition.
  5342. The second example installs the same files into a
  5343. <filename>boot</filename> directory within the
  5344. target partition.
  5345. </para>
  5346. <para>
  5347. You can find information on how to use the Wic tool in the
  5348. "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
  5349. section of the Yocto Project Development Tasks Manual.
  5350. Reference material for Wic is located in the
  5351. "<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (.wks) Reference</ulink>"
  5352. chapter in the Yocto Project Reference Manual.
  5353. </para>
  5354. </glossdef>
  5355. </glossentry>
  5356. <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
  5357. <info>
  5358. IMAGE_CLASSES[doc] = "A list of classes that all images should inherit."
  5359. </info>
  5360. <glossdef>
  5361. <para role="glossdeffirst">
  5362. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5363. A list of classes that all images should inherit.
  5364. You typically use this variable to specify the list of
  5365. classes that register the different types of images
  5366. the OpenEmbedded build system creates.
  5367. </para>
  5368. <para>
  5369. The default value for <filename>IMAGE_CLASSES</filename> is
  5370. <filename>image_types</filename>.
  5371. You can set this variable in your
  5372. <filename>local.conf</filename> or in a distribution
  5373. configuration file.
  5374. </para>
  5375. <para>
  5376. For more information, see
  5377. <filename>meta/classes/image_types.bbclass</filename> in the
  5378. <link linkend='source-directory'>Source Directory</link>.
  5379. </para>
  5380. </glossdef>
  5381. </glossentry>
  5382. <glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm>
  5383. <info>
  5384. IMAGE_CMD[doc] = "Specifies the command to create the image file for a specific image type, which corresponds to the value set set in IMAGE_FSTYPES, (e.g. ext3, btrfs, and so forth)."
  5385. </info>
  5386. <glossdef>
  5387. <para role="glossdeffirst">
  5388. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5389. Specifies the command to create the image file for a
  5390. specific image type, which corresponds to the value set
  5391. set in
  5392. <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
  5393. (e.g. <filename>ext3</filename>,
  5394. <filename>btrfs</filename>, and so forth).
  5395. When setting this variable, you should use
  5396. an override for the associated type.
  5397. Here is an example:
  5398. <literallayout class='monospaced'>
  5399. IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \
  5400. --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
  5401. ${EXTRA_IMAGECMD}"
  5402. </literallayout>
  5403. </para>
  5404. <para>
  5405. You typically do not need to set this variable unless
  5406. you are adding support for a new image type.
  5407. For more examples on how to set this variable, see the
  5408. <link linkend='ref-classes-image_types'><filename>image_types</filename></link>
  5409. class file, which is
  5410. <filename>meta/classes/image_types.bbclass</filename>.
  5411. </para>
  5412. </glossdef>
  5413. </glossentry>
  5414. <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm>
  5415. <info>
  5416. IMAGE_DEVICE_TABLES[doc] = "Specifies one or more files that contain custom device tables that are passed to the makedevs command as part of creating an image."
  5417. </info>
  5418. <glossdef>
  5419. <para role="glossdeffirst">
  5420. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5421. Specifies one or more files that contain custom device
  5422. tables that are passed to the
  5423. <filename>makedevs</filename> command as part of creating
  5424. an image.
  5425. These files list basic device nodes that should be
  5426. created under <filename>/dev</filename> within the image.
  5427. If <filename>IMAGE_DEVICE_TABLES</filename> is not set,
  5428. <filename>files/device_table-minimal.txt</filename> is
  5429. used, which is located by
  5430. <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
  5431. For details on how you should write device table files,
  5432. see <filename>meta/files/device_table-minimal.txt</filename>
  5433. as an example.
  5434. </para>
  5435. </glossdef>
  5436. </glossentry>
  5437. <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
  5438. <info>
  5439. IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe."
  5440. </info>
  5441. <glossdef>
  5442. <para role="glossdeffirst">
  5443. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5444. The primary list of features to include in an image.
  5445. Typically, you configure this variable in an image recipe.
  5446. Although you can use this variable from your
  5447. <filename>local.conf</filename> file, which is found in the
  5448. <link linkend='build-directory'>Build Directory</link>,
  5449. best practices dictate that you do not.
  5450. <note>
  5451. To enable extra features from outside the image recipe,
  5452. use the
  5453. <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
  5454. </note>
  5455. </para>
  5456. <para>
  5457. For a list of image features that ships with the Yocto
  5458. Project, see the
  5459. "<link linkend="ref-features-image">Image Features</link>"
  5460. section.
  5461. </para>
  5462. <para>
  5463. For an example that shows how to customize your image by
  5464. using this variable, see the
  5465. "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
  5466. section in the Yocto Project Development Tasks Manual.
  5467. </para>
  5468. </glossdef>
  5469. </glossentry>
  5470. <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
  5471. <info>
  5472. IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created."
  5473. </info>
  5474. <glossdef>
  5475. <para role="glossdeffirst">
  5476. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5477. Specifies the formats the OpenEmbedded build system uses
  5478. during the build when creating the root filesystem.
  5479. For example, setting <filename>IMAGE_FSTYPES</filename>
  5480. as follows causes the build system to create root
  5481. filesystems using two formats: <filename>.ext3</filename>
  5482. and <filename>.tar.bz2</filename>:
  5483. <literallayout class='monospaced'>
  5484. IMAGE_FSTYPES = "ext3 tar.bz2"
  5485. </literallayout>
  5486. </para>
  5487. <para>
  5488. For the complete list of supported image formats from which
  5489. you can choose, see
  5490. <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
  5491. </para>
  5492. <note><title>Notes</title>
  5493. <itemizedlist>
  5494. <listitem><para>
  5495. If you add "live" to
  5496. <filename>IMAGE_FSTYPES</filename> inside an image
  5497. recipe, be sure that you do so prior to the
  5498. "inherit image" line of the recipe or the live
  5499. image will not build.
  5500. </para></listitem>
  5501. <listitem><para>
  5502. Due to the way the OpenEmbedded build system
  5503. processes this variable, you cannot update its
  5504. contents by using <filename>_append</filename> or
  5505. <filename>_prepend</filename>.
  5506. You must use the <filename>+=</filename>
  5507. operator to add one or more options to the
  5508. <filename>IMAGE_FSTYPES</filename> variable.
  5509. </para></listitem>
  5510. </itemizedlist>
  5511. </note>
  5512. </glossdef>
  5513. </glossentry>
  5514. <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
  5515. <info>
  5516. IMAGE_INSTALL[doc] = "Used by recipes to specify the packages to install into an image through image.bbclass."
  5517. </info>
  5518. <glossdef>
  5519. <para role="glossdeffirst">
  5520. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5521. Used by recipes to specify the packages to install into an
  5522. image through the
  5523. <link linkend='ref-classes-image'><filename>image</filename></link>
  5524. class.
  5525. Use the <filename>IMAGE_INSTALL</filename> variable with
  5526. care to avoid ordering issues.
  5527. </para>
  5528. <para>
  5529. Image recipes set <filename>IMAGE_INSTALL</filename>
  5530. to specify the packages to install into an image through
  5531. <filename>image.bbclass</filename>.
  5532. Additionally, "helper" classes such as the
  5533. <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
  5534. class exist that can take lists used with
  5535. <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
  5536. and turn them into auto-generated entries in
  5537. <filename>IMAGE_INSTALL</filename> in addition to its
  5538. default contents.
  5539. </para>
  5540. <para>
  5541. When you use this variable, it is best to use it as follows:
  5542. <literallayout class='monospaced'>
  5543. IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"
  5544. </literallayout>
  5545. Be sure to include the space between the quotation character
  5546. and the start of the package name or names.
  5547. <note><title>Caution</title>
  5548. <itemizedlist>
  5549. <listitem><para>
  5550. When working with a
  5551. <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
  5552. image, do not use the
  5553. <filename>IMAGE_INSTALL</filename> variable to
  5554. specify packages for installation.
  5555. Instead, use the
  5556. <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
  5557. variable, which allows the initial RAM
  5558. filesystem (initramfs) recipe to use a fixed
  5559. set of packages and not be affected by
  5560. <filename>IMAGE_INSTALL</filename>.
  5561. For information on creating an initramfs, see
  5562. the
  5563. "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
  5564. section in the Yocto Project Development Tasks
  5565. Manual.
  5566. </para></listitem>
  5567. <listitem><para>
  5568. Using <filename>IMAGE_INSTALL</filename> with
  5569. the
  5570. <ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending'><filename>+=</filename></ulink>
  5571. BitBake operator within the
  5572. <filename>/conf/local.conf</filename> file or
  5573. from within an image recipe is not recommended.
  5574. Use of this operator in these ways can cause
  5575. ordering issues.
  5576. Since <filename>core-image.bbclass</filename>
  5577. sets <filename>IMAGE_INSTALL</filename> to a
  5578. default value using the
  5579. <ulink url='&YOCTO_DOCS_BB_URL;#setting-a-default-value'><filename>?=</filename></ulink>
  5580. operator, using a <filename>+=</filename>
  5581. operation against
  5582. <filename>IMAGE_INSTALL</filename> results in
  5583. unexpected behavior when used within
  5584. <filename>conf/local.conf</filename>.
  5585. Furthermore, the same operation from within
  5586. an image recipe may or may not succeed
  5587. depending on the specific situation.
  5588. In both these cases, the behavior is contrary
  5589. to how most users expect the
  5590. <filename>+=</filename> operator to work.
  5591. </para></listitem>
  5592. </itemizedlist>
  5593. </note>
  5594. </para>
  5595. </glossdef>
  5596. </glossentry>
  5597. <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
  5598. <info>
  5599. IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process."
  5600. </info>
  5601. <glossdef>
  5602. <para role="glossdeffirst">
  5603. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5604. Specifies the list of locales to install into the image
  5605. during the root filesystem construction process.
  5606. The OpenEmbedded build system automatically splits locale
  5607. files, which are used for localization, into separate
  5608. packages.
  5609. Setting the <filename>IMAGE_LINGUAS</filename> variable
  5610. ensures that any locale packages that correspond to packages
  5611. already selected for installation into the image are also
  5612. installed.
  5613. Here is an example:
  5614. <literallayout class='monospaced'>
  5615. IMAGE_LINGUAS = "pt-br de-de"
  5616. </literallayout>
  5617. </para>
  5618. <para>
  5619. In this example, the build system ensures any Brazilian
  5620. Portuguese and German locale files that correspond to
  5621. packages in the image are installed (i.e.
  5622. <filename>*-locale-pt-br</filename>
  5623. and <filename>*-locale-de-de</filename> as well as
  5624. <filename>*-locale-pt</filename>
  5625. and <filename>*-locale-de</filename>, since some software
  5626. packages only provide locale files by language and not by
  5627. country-specific language).
  5628. </para>
  5629. <para>
  5630. See the
  5631. <link linkend='var-GLIBC_GENERATE_LOCALES'><filename>GLIBC_GENERATE_LOCALES</filename></link>
  5632. variable for information on generating GLIBC locales.
  5633. </para>
  5634. </glossdef>
  5635. </glossentry>
  5636. <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
  5637. <info>
  5638. IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image."
  5639. </info>
  5640. <glossdef>
  5641. <para role="glossdeffirst">
  5642. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5643. The manifest file for the image.
  5644. This file lists all the installed packages that make up
  5645. the image.
  5646. The file contains package information on a line-per-package
  5647. basis as follows:
  5648. <literallayout class='monospaced'>
  5649. <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
  5650. </literallayout>
  5651. </para>
  5652. <para>
  5653. The
  5654. <link linkend='ref-classes-image'><filename>image</filename></link>
  5655. class defines the manifest file as follows:
  5656. <literallayout class='monospaced'>
  5657. IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
  5658. </literallayout>
  5659. The location is derived using the
  5660. <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
  5661. and
  5662. <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
  5663. variables.
  5664. You can find information on how the image
  5665. is created in the
  5666. "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
  5667. section in the Yocto Project Overview and Concepts Manual.
  5668. </para>
  5669. </glossdef>
  5670. </glossentry>
  5671. <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
  5672. <info>
  5673. IMAGE_NAME[doc] = "The name of the output image files minus the extension."
  5674. </info>
  5675. <glossdef>
  5676. <para role="glossdeffirst">
  5677. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5678. The name of the output image files minus the extension.
  5679. This variable is derived using the
  5680. <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
  5681. <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
  5682. and
  5683. <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
  5684. variables:
  5685. <literallayout class='monospaced'>
  5686. IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
  5687. </literallayout>
  5688. </para>
  5689. </glossdef>
  5690. </glossentry>
  5691. <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
  5692. <info>
  5693. IMAGE_OVERHEAD_FACTOR[doc] = "Defines a multiplier that the build system applies to the initial image size for cases when the multiplier times the returned disk usage value for the image is greater than the sum of IMAGE_ROOTFS_SIZE and IMAGE_ROOTFS_EXTRA_SPACE."
  5694. </info>
  5695. <glossdef>
  5696. <para role="glossdeffirst">
  5697. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5698. Defines a multiplier that the build system applies to the initial image
  5699. size for cases when the multiplier times the returned disk usage value
  5700. for the image is greater than the sum of
  5701. <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
  5702. and
  5703. <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
  5704. The result of the multiplier applied to the initial image size creates
  5705. free disk space in the image as overhead.
  5706. By default, the build process uses a multiplier of 1.3 for this variable.
  5707. This default value results in 30% free disk space added to the image when this
  5708. method is used to determine the final generated image size.
  5709. You should be aware that post install scripts and the package management
  5710. system uses disk space inside this overhead area.
  5711. Consequently, the multiplier does not produce an image with
  5712. all the theoretical free disk space.
  5713. See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
  5714. for information on how the build system determines the overall image size.
  5715. </para>
  5716. <para>
  5717. The default 30% free disk space typically gives the image enough room to boot
  5718. and allows for basic post installs while still leaving a small amount of
  5719. free disk space.
  5720. If 30% free space is inadequate, you can increase the default value.
  5721. For example, the following setting gives you 50% free space added to the image:
  5722. <literallayout class='monospaced'>
  5723. IMAGE_OVERHEAD_FACTOR = "1.5"
  5724. </literallayout>
  5725. </para>
  5726. <para>
  5727. Alternatively, you can ensure a specific amount of free disk space is added
  5728. to the image by using the
  5729. <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
  5730. variable.
  5731. </para>
  5732. </glossdef>
  5733. </glossentry>
  5734. <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
  5735. <info>
  5736. IMAGE_PKGTYPE[doc] = "Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system."
  5737. </info>
  5738. <glossdef>
  5739. <para role="glossdeffirst">
  5740. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5741. Defines the package type (i.e. DEB, RPM, IPK, or TAR) used
  5742. by the OpenEmbedded build system.
  5743. The variable is defined appropriately by the
  5744. <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
  5745. <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
  5746. <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
  5747. or
  5748. <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
  5749. class.
  5750. <note><title>Warning</title>
  5751. The <filename>package_tar</filename> class is broken
  5752. and is not supported.
  5753. It is recommended that you do not use it.
  5754. </note>
  5755. </para>
  5756. <para>
  5757. The
  5758. <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_*</filename></link>
  5759. and
  5760. <link linkend='ref-classes-image'><filename>image</filename></link>
  5761. classes use the <filename>IMAGE_PKGTYPE</filename> for
  5762. packaging up images and SDKs.
  5763. </para>
  5764. <para>
  5765. You should not set the <filename>IMAGE_PKGTYPE</filename>
  5766. manually.
  5767. Rather, the variable is set indirectly through the
  5768. appropriate
  5769. <link linkend='ref-classes-package'><filename>package_*</filename></link>
  5770. class using the
  5771. <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
  5772. variable.
  5773. The OpenEmbedded build system uses the first package type
  5774. (e.g. DEB, RPM, or IPK) that appears with the variable
  5775. <note>
  5776. Files using the <filename>.tar</filename> format are
  5777. never used as a substitute packaging format for DEB,
  5778. RPM, and IPK formatted files for your image or SDK.
  5779. </note>
  5780. </para>
  5781. </glossdef>
  5782. </glossentry>
  5783. <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
  5784. <info>
  5785. IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the final image output files."
  5786. </info>
  5787. <glossdef>
  5788. <para role="glossdeffirst">
  5789. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5790. Specifies a list of functions to call once the
  5791. OpenEmbedded build system creates the final image
  5792. output files.
  5793. You can specify functions separated by semicolons:
  5794. <literallayout class='monospaced'>
  5795. IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
  5796. </literallayout>
  5797. </para>
  5798. <para>
  5799. If you need to pass the root filesystem path to a command
  5800. within the function, you can use
  5801. <filename>${IMAGE_ROOTFS}</filename>, which points to
  5802. the directory that becomes the root filesystem image.
  5803. See the
  5804. <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
  5805. variable for more information.
  5806. </para>
  5807. </glossdef>
  5808. </glossentry>
  5809. <glossentry id='var-IMAGE_PREPROCESS_COMMAND'><glossterm>IMAGE_PREPROCESS_COMMAND</glossterm>
  5810. <info>
  5811. IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system creates the final image output files."
  5812. </info>
  5813. <glossdef>
  5814. <para role="glossdeffirst">
  5815. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5816. Specifies a list of functions to call before the
  5817. OpenEmbedded build system creates the final image
  5818. output files.
  5819. You can specify functions separated by semicolons:
  5820. <literallayout class='monospaced'>
  5821. IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
  5822. </literallayout>
  5823. </para>
  5824. <para>
  5825. If you need to pass the root filesystem path to a command
  5826. within the function, you can use
  5827. <filename>${IMAGE_ROOTFS}</filename>, which points to
  5828. the directory that becomes the root filesystem image.
  5829. See the
  5830. <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
  5831. variable for more information.
  5832. </para>
  5833. </glossdef>
  5834. </glossentry>
  5835. <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
  5836. <info>
  5837. IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)."
  5838. </info>
  5839. <glossdef>
  5840. <para role="glossdeffirst">
  5841. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5842. The location of the root filesystem while it is under
  5843. construction (i.e. during the
  5844. <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
  5845. task).
  5846. This variable is not configurable.
  5847. Do not change it.
  5848. </para>
  5849. </glossdef>
  5850. </glossentry>
  5851. <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm>
  5852. <info>
  5853. IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes."
  5854. </info>
  5855. <glossdef>
  5856. <para role="glossdeffirst">
  5857. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5858. Specifies the alignment for the output image file in
  5859. Kbytes.
  5860. If the size of the image is not a multiple of
  5861. this value, then the size is rounded up to the nearest
  5862. multiple of the value.
  5863. The default value is "1".
  5864. See
  5865. <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
  5866. for additional information.
  5867. </para>
  5868. </glossdef>
  5869. </glossentry>
  5870. <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
  5871. <info>
  5872. IMAGE_ROOTFS_EXTRA_SPACE[doc] = "Defines additional free disk space created in the image in Kbytes. By default, this variable is set to '0'."
  5873. </info>
  5874. <glossdef>
  5875. <para role="glossdeffirst">
  5876. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5877. Defines additional free disk space created in the image in Kbytes.
  5878. By default, this variable is set to "0".
  5879. This free disk space is added to the image after the build system determines
  5880. the image size as described in
  5881. <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
  5882. </para>
  5883. <para>
  5884. This variable is particularly useful when you want to ensure that a
  5885. specific amount of free disk space is available on a device after an image
  5886. is installed and running.
  5887. For example, to be sure 5 Gbytes of free disk space is available, set the
  5888. variable as follows:
  5889. <literallayout class='monospaced'>
  5890. IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
  5891. </literallayout>
  5892. </para>
  5893. <para>
  5894. For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
  5895. of extra space with the line:
  5896. <literallayout class='monospaced'>
  5897. IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
  5898. </literallayout>
  5899. </para>
  5900. </glossdef>
  5901. </glossentry>
  5902. <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
  5903. <info>
  5904. IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image."
  5905. </info>
  5906. <glossdef>
  5907. <para role="glossdeffirst">
  5908. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5909. Defines the size in Kbytes for the generated image.
  5910. The OpenEmbedded build system determines the final size for the generated
  5911. image using an algorithm that takes into account the initial disk space used
  5912. for the generated image, a requested size for the image, and requested
  5913. additional free disk space to be added to the image.
  5914. Programatically, the build system determines the final size of the
  5915. generated image as follows:
  5916. <literallayout class='monospaced'>
  5917. if (image-du * overhead) &lt; rootfs-size:
  5918. internal-rootfs-size = rootfs-size + xspace
  5919. else:
  5920. internal-rootfs-size = (image-du * overhead) + xspace
  5921. where:
  5922. image-du = Returned value of the du command on
  5923. the image.
  5924. overhead = IMAGE_OVERHEAD_FACTOR
  5925. rootfs-size = IMAGE_ROOTFS_SIZE
  5926. internal-rootfs-size = Initial root filesystem
  5927. size before any modifications.
  5928. xspace = IMAGE_ROOTFS_EXTRA_SPACE
  5929. </literallayout>
  5930. </para>
  5931. <para>
  5932. See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
  5933. and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
  5934. variables for related information.
  5935. <!-- In the above example, <filename>overhead</filename> is defined by the
  5936. <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
  5937. variable, <filename>xspace</filename> is defined by the
  5938. <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
  5939. variable, and <filename>du</filename> is the results of the disk usage command
  5940. on the initially generated image. -->
  5941. </para>
  5942. </glossdef>
  5943. </glossentry>
  5944. <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
  5945. <info>
  5946. IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another."
  5947. </info>
  5948. <glossdef>
  5949. <para role="glossdeffirst">
  5950. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5951. Specifies a dependency from one image type on another.
  5952. Here is an example from the
  5953. <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
  5954. class:
  5955. <literallayout class='monospaced'>
  5956. IMAGE_TYPEDEP_live = "ext3"
  5957. </literallayout>
  5958. </para>
  5959. <para>
  5960. In the previous example, the variable ensures that when
  5961. "live" is listed with the
  5962. <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
  5963. variable, the OpenEmbedded build system produces an
  5964. <filename>ext3</filename> image first since one of the
  5965. components of the live
  5966. image is an <filename>ext3</filename>
  5967. formatted partition containing the root
  5968. filesystem.
  5969. </para>
  5970. </glossdef>
  5971. </glossentry>
  5972. <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
  5973. <info>
  5974. IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default."
  5975. </info>
  5976. <glossdef>
  5977. <para role="glossdeffirst">
  5978. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  5979. Specifies the complete list of supported image types
  5980. by default:
  5981. <literallayout class='monospaced'>
  5982. btrfs
  5983. cpio
  5984. cpio.gz
  5985. cpio.lz4
  5986. cpio.lzma
  5987. cpio.xz
  5988. cramfs
  5989. elf
  5990. ext2
  5991. ext2.bz2
  5992. ext2.gz
  5993. ext2.lzma
  5994. ext3
  5995. ext3.gz
  5996. ext4
  5997. ext4.gz
  5998. hdddirect
  5999. hddimg
  6000. iso
  6001. jffs2
  6002. jffs2.sum
  6003. multiubi
  6004. squashfs
  6005. squashfs-lzo
  6006. squashfs-xz
  6007. tar
  6008. tar.bz2
  6009. tar.gz
  6010. tar.lz4
  6011. tar.xz
  6012. ubi
  6013. ubifs
  6014. wic
  6015. wic.bz2
  6016. wic.gz
  6017. wic.lzma
  6018. </literallayout>
  6019. </para>
  6020. <para>
  6021. For more information about these types of images, see
  6022. <filename>meta/classes/image_types*.bbclass</filename>
  6023. in the
  6024. <link linkend='source-directory'>Source Directory</link>.
  6025. </para>
  6026. </glossdef>
  6027. </glossentry>
  6028. <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
  6029. <info>
  6030. INC_PR[doc] = "Helps define the recipe revision for recipes that share a common include file."
  6031. </info>
  6032. <glossdef>
  6033. <para role="glossdeffirst">
  6034. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6035. Helps define the recipe revision for recipes that share
  6036. a common <filename>include</filename> file.
  6037. You can think of this variable as part of the recipe revision
  6038. as set from within an include file.
  6039. </para>
  6040. <para>
  6041. Suppose, for example, you have a set of recipes that
  6042. are used across several projects.
  6043. And, within each of those recipes the revision
  6044. (its <link linkend='var-PR'><filename>PR</filename></link>
  6045. value) is set accordingly.
  6046. In this case, when the revision of those recipes changes,
  6047. the burden is on you to find all those recipes and
  6048. be sure that they get changed to reflect the updated
  6049. version of the recipe.
  6050. In this scenario, it can get complicated when recipes
  6051. that are used in many places and provide common functionality
  6052. are upgraded to a new revision.
  6053. </para>
  6054. <para>
  6055. A more efficient way of dealing with this situation is
  6056. to set the <filename>INC_PR</filename> variable inside
  6057. the <filename>include</filename> files that the recipes
  6058. share and then expand the <filename>INC_PR</filename>
  6059. variable within the recipes to help
  6060. define the recipe revision.
  6061. </para>
  6062. <para>
  6063. The following provides an example that shows how to use
  6064. the <filename>INC_PR</filename> variable
  6065. given a common <filename>include</filename> file that
  6066. defines the variable.
  6067. Once the variable is defined in the
  6068. <filename>include</filename> file, you can use the
  6069. variable to set the <filename>PR</filename> values in
  6070. each recipe.
  6071. You will notice that when you set a recipe's
  6072. <filename>PR</filename> you can provide more granular
  6073. revisioning by appending values to the
  6074. <filename>INC_PR</filename> variable:
  6075. <literallayout class='monospaced'>
  6076. recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
  6077. recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
  6078. recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
  6079. recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
  6080. </literallayout>
  6081. The first line of the example establishes the baseline
  6082. revision to be used for all recipes that use the
  6083. <filename>include</filename> file.
  6084. The remaining lines in the example are from individual
  6085. recipes and show how the <filename>PR</filename> value
  6086. is set.
  6087. </para>
  6088. </glossdef>
  6089. </glossentry>
  6090. <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
  6091. <info>
  6092. INCOMPATIBLE_LICENSE[doc] = "Specifies a space-separated list of license names (as they would appear in LICENSE) that should be excluded from the build."
  6093. </info>
  6094. <glossdef>
  6095. <para role="glossdeffirst">
  6096. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6097. Specifies a space-separated list of license names
  6098. (as they would appear in
  6099. <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
  6100. that should be excluded from the build.
  6101. Recipes that provide no alternatives to listed incompatible
  6102. licenses are not built.
  6103. Packages that are individually licensed with the specified
  6104. incompatible licenses will be deleted.
  6105. </para>
  6106. <note>
  6107. This functionality is only regularly tested using
  6108. the following setting:
  6109. <literallayout class='monospaced'>
  6110. INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
  6111. </literallayout>
  6112. Although you can use other settings, you might be required
  6113. to remove dependencies on or provide alternatives to
  6114. components that are required to produce a functional system
  6115. image.
  6116. </note>
  6117. </glossdef>
  6118. </glossentry>
  6119. <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
  6120. <info>
  6121. INHERIT[doc] = "Causes the named class or classes to be inherited globally."
  6122. </info>
  6123. <glossdef>
  6124. <para role="glossdeffirst">
  6125. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6126. Causes the named class or classes to be inherited globally.
  6127. Anonymous functions in the class or classes
  6128. are not executed for the
  6129. base configuration and in each individual recipe.
  6130. The OpenEmbedded build system ignores changes to
  6131. <filename>INHERIT</filename> in individual recipes.
  6132. </para>
  6133. <para>
  6134. For more information on <filename>INHERIT</filename>, see
  6135. the
  6136. "<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>"
  6137. section in the Yocto Project Bitbake User Manual.
  6138. </para>
  6139. </glossdef>
  6140. </glossentry>
  6141. <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
  6142. <info>
  6143. INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."
  6144. </info>
  6145. <glossdef>
  6146. <para role="glossdeffirst">
  6147. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6148. Lists classes that will be inherited at the
  6149. distribution level.
  6150. It is unlikely that you want to edit this variable.
  6151. </para>
  6152. <para>
  6153. The default value of the variable is set as follows in the
  6154. <filename>meta/conf/distro/defaultsetup.conf</filename>
  6155. file:
  6156. <literallayout class='monospaced'>
  6157. INHERIT_DISTRO ?= "debian devshell sstate license"
  6158. </literallayout>
  6159. </para>
  6160. </glossdef>
  6161. </glossentry>
  6162. <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
  6163. <info>
  6164. INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."
  6165. </info>
  6166. <glossdef>
  6167. <para role="glossdeffirst">
  6168. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6169. Prevents the default dependencies, namely the C compiler
  6170. and standard C library (libc), from being added to
  6171. <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
  6172. This variable is usually used within recipes that do not
  6173. require any compilation using the C compiler.
  6174. </para>
  6175. <para>
  6176. Set the variable to "1" to prevent the default dependencies
  6177. from being added.
  6178. </para>
  6179. </glossdef>
  6180. </glossentry>
  6181. <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm>
  6182. <info>
  6183. INHIBIT_PACKAGE_DEBUG_SPLIT[doc] = "If set to "1", prevents the OpenEmbedded build system from splitting out debug information during packaging"
  6184. </info>
  6185. <glossdef>
  6186. <para role="glossdeffirst">
  6187. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6188. Prevents the OpenEmbedded build system from splitting
  6189. out debug information during packaging.
  6190. By default, the build system splits out debugging
  6191. information during the
  6192. <link linkend='ref-tasks-package'><filename>do_package</filename></link>
  6193. task.
  6194. For more information on how debug information is split out,
  6195. see the
  6196. <link linkend='var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></link>
  6197. variable.
  6198. </para>
  6199. <para>
  6200. To prevent the build system from splitting out
  6201. debug information during packaging, set the
  6202. <filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable
  6203. as follows:
  6204. <literallayout class='monospaced'>
  6205. INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
  6206. </literallayout>
  6207. </para>
  6208. </glossdef>
  6209. </glossentry>
  6210. <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
  6211. <info>
  6212. INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages."
  6213. </info>
  6214. <glossdef>
  6215. <para role="glossdeffirst">
  6216. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6217. If set to "1", causes the build to not strip binaries in
  6218. resulting packages and prevents the
  6219. <filename>-dbg</filename> package from containing the
  6220. source files.
  6221. </para>
  6222. <para>
  6223. By default, the OpenEmbedded build system strips
  6224. binaries and puts the debugging symbols into
  6225. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>.
  6226. Consequently, you should not set
  6227. <filename>INHIBIT_PACKAGE_STRIP</filename> when you plan
  6228. to debug in general.
  6229. </para>
  6230. </glossdef>
  6231. </glossentry>
  6232. <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
  6233. <info>
  6234. INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM filesystem (initramfs), which is used during boot."
  6235. </info>
  6236. <glossdef>
  6237. <para role="glossdeffirst">
  6238. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6239. Defines the format for the output image of an initial
  6240. RAM filesystem (initramfs), which is used during boot.
  6241. Supported formats are the same as those supported by the
  6242. <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
  6243. variable.
  6244. </para>
  6245. <para>
  6246. The default value of this variable, which is set in the
  6247. <filename>meta/conf/bitbake.conf</filename> configuration
  6248. file in the
  6249. <link linkend='source-directory'>Source Directory</link>,
  6250. is "cpio.gz".
  6251. The Linux kernel's initramfs mechanism, as opposed to the
  6252. initial RAM filesystem
  6253. <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>
  6254. mechanism, expects an optionally compressed cpio
  6255. archive.
  6256. </para>
  6257. </glossdef>
  6258. </glossentry>
  6259. <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
  6260. <info>
  6261. INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM filesystem (initramfs) image."
  6262. </info>
  6263. <glossdef>
  6264. <para role="glossdeffirst">
  6265. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6266. Specifies the
  6267. <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
  6268. name of an image recipe that is used to build an initial
  6269. RAM filesystem (initramfs) image.
  6270. In other words, the <filename>INITRAMFS_IMAGE</filename>
  6271. variable causes an additional recipe to be built as
  6272. a dependency to whatever root filesystem recipe you
  6273. might be using (e.g. <filename>core-image-sato</filename>).
  6274. The initramfs image recipe you provide should set
  6275. <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
  6276. to
  6277. <link linkend='var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></link>.
  6278. </para>
  6279. <para>
  6280. An initramfs image provides a temporary root filesystem
  6281. used for early system initialization (e.g. loading of
  6282. modules needed to locate and mount the "real" root
  6283. filesystem).
  6284. <note>
  6285. See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>
  6286. recipe in the
  6287. <link linkend='source-directory'>Source Directory</link>
  6288. for an example initramfs recipe.
  6289. To select this sample recipe as the one built
  6290. to provide the initramfs image,
  6291. set <filename>INITRAMFS_IMAGE</filename> to
  6292. "core-image-minimal-initramfs".
  6293. </note>
  6294. </para>
  6295. <para>
  6296. You can also find more information by referencing the
  6297. <filename>meta-poky/conf/local.conf.sample.extended</filename>
  6298. configuration file in the
  6299. <link linkend='source-directory'>Source Directory</link>,
  6300. the
  6301. <link linkend='ref-classes-image'><filename>image</filename></link>
  6302. class, and the
  6303. <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
  6304. class to see how to use the
  6305. <filename>INITRAMFS_IMAGE</filename> variable.
  6306. </para>
  6307. <para>
  6308. If <filename>INITRAMFS_IMAGE</filename> is empty, which is
  6309. the default, then no initramfs image is built.
  6310. </para>
  6311. <para>
  6312. For more information, you can also see the
  6313. <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link>
  6314. variable, which allows the generated image to be bundled
  6315. inside the kernel image.
  6316. Additionally, for information on creating an initramfs
  6317. image, see the
  6318. "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
  6319. section in the Yocto Project Development Tasks Manual.
  6320. </para>
  6321. </glossdef>
  6322. </glossentry>
  6323. <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
  6324. <info>
  6325. INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass (do_bundle_initramfs) during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM filesystem (initramfs)."
  6326. </info>
  6327. <glossdef>
  6328. <para role="glossdeffirst">
  6329. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6330. Controls whether or not the image recipe specified by
  6331. <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
  6332. is run through an extra pass
  6333. (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)
  6334. during kernel compilation in order to build a single binary
  6335. that contains both the kernel image and the initial RAM
  6336. filesystem (initramfs) image.
  6337. This makes use of the
  6338. <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
  6339. kernel feature.
  6340. <note>
  6341. Using an extra compilation pass to bundle the initramfs
  6342. avoids a circular dependency between the kernel recipe and
  6343. the initramfs recipe should the initramfs include kernel
  6344. modules.
  6345. Should that be the case, the initramfs recipe depends on
  6346. the kernel for the kernel modules, and the kernel depends
  6347. on the initramfs recipe since the initramfs is bundled
  6348. inside the kernel image.
  6349. </note>
  6350. </para>
  6351. <para>
  6352. The combined binary is deposited into the
  6353. <filename>tmp/deploy</filename> directory, which is part
  6354. of the
  6355. <link linkend='build-directory'>Build Directory</link>.
  6356. </para>
  6357. <para>
  6358. Setting the variable to "1" in a configuration file causes the
  6359. OpenEmbedded build system to generate a kernel image with the
  6360. initramfs specified in
  6361. <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
  6362. bundled within:
  6363. <literallayout class='monospaced'>
  6364. INITRAMFS_IMAGE_BUNDLE = "1"
  6365. </literallayout>
  6366. By default, the
  6367. <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
  6368. class sets this variable to a null string as follows:
  6369. <literallayout class='monospaced'>
  6370. INITRAMFS_IMAGE_BUNDLE ?= ""
  6371. </literallayout>
  6372. <note>
  6373. You must set the
  6374. <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
  6375. a configuration file.
  6376. You cannot set the variable in a recipe file.
  6377. </note>
  6378. See the
  6379. <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
  6380. file for additional information.
  6381. Also, for information on creating an initramfs, see the
  6382. "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
  6383. section in the Yocto Project Development Tasks Manual.
  6384. </para>
  6385. </glossdef>
  6386. </glossentry>
  6387. <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
  6388. <info>
  6389. INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."
  6390. </info>
  6391. <glossdef>
  6392. <para role="glossdeffirst">
  6393. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6394. Indicates list of filesystem images to concatenate and use
  6395. as an initial RAM disk (<filename>initrd</filename>).
  6396. </para>
  6397. <para>
  6398. The <filename>INITRD</filename> variable is an optional
  6399. variable used with the
  6400. <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
  6401. class.
  6402. </para>
  6403. </glossdef>
  6404. </glossentry>
  6405. <glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm>
  6406. <info>
  6407. INITRD_IMAGE[doc] = "When building a "live" bootable image (i.e. when IMAGE_FSTYPES contains "live"), INITRD_IMAGE specifies the image recipe that should be built to provide the initial RAM disk image."
  6408. </info>
  6409. <glossdef>
  6410. <para role="glossdeffirst">
  6411. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6412. When building a "live" bootable image (i.e. when
  6413. <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
  6414. contains "live"), <filename>INITRD_IMAGE</filename>
  6415. specifies the image recipe that should be built
  6416. to provide the initial RAM disk image.
  6417. The default value is "core-image-minimal-initramfs".
  6418. </para>
  6419. <para>
  6420. See the
  6421. <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
  6422. class for more information.
  6423. </para>
  6424. </glossdef>
  6425. </glossentry>
  6426. <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
  6427. <info>
  6428. INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."
  6429. </info>
  6430. <glossdef>
  6431. <para role="glossdeffirst">
  6432. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6433. The filename of the initialization script as installed to
  6434. <filename>${sysconfdir}/init.d</filename>.
  6435. </para>
  6436. <para>
  6437. This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
  6438. The variable is mandatory.
  6439. </para>
  6440. </glossdef>
  6441. </glossentry>
  6442. <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
  6443. <info>
  6444. INITSCRIPT_PACKAGES[doc] = "A list of the packages that contain initscripts. This variable is used in recipes when using update-rc.d.bbclass. The variable is optional and defaults to the PN variable."
  6445. </info>
  6446. <glossdef>
  6447. <para role="glossdeffirst">
  6448. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6449. A list of the packages that contain initscripts.
  6450. If multiple packages are specified, you need to append the package name
  6451. to the other <filename>INITSCRIPT_*</filename> as an override.
  6452. </para>
  6453. <para>
  6454. This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
  6455. The variable is optional and defaults to the
  6456. <link linkend='var-PN'><filename>PN</filename></link> variable.
  6457. </para>
  6458. </glossdef>
  6459. </glossentry>
  6460. <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
  6461. <info>
  6462. INITSCRIPT_PARAMS[doc] = "Specifies the options to pass to update-rc.d. The variable is mandatory and is used in recipes when using update-rc.d.bbclass."
  6463. </info>
  6464. <glossdef>
  6465. <para role="glossdeffirst">
  6466. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6467. Specifies the options to pass to <filename>update-rc.d</filename>.
  6468. Here is an example:
  6469. <literallayout class='monospaced'>
  6470. INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
  6471. </literallayout>
  6472. </para>
  6473. <para>
  6474. In this example, the script has a runlevel of 99,
  6475. starts the script in initlevels 2 and 5, and
  6476. stops the script in levels 0, 1 and 6.
  6477. </para>
  6478. <para>
  6479. The variable's default value is "defaults", which is
  6480. set in the
  6481. <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
  6482. class.
  6483. </para>
  6484. <para>
  6485. The value in
  6486. <filename>INITSCRIPT_PARAMS</filename> is passed through
  6487. to the <filename>update-rc.d</filename> command.
  6488. For more information on valid parameters, please see the
  6489. <filename>update-rc.d</filename> manual page at
  6490. <ulink url='http://www.tin.org/bin/man.cgi?section=8&amp;topic=update-rc.d'></ulink>.
  6491. </para>
  6492. </glossdef>
  6493. </glossentry>
  6494. <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
  6495. <info>
  6496. INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."
  6497. </info>
  6498. <glossdef>
  6499. <para role="glossdeffirst">
  6500. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6501. Specifies the QA checks to skip for a specific package
  6502. within a recipe.
  6503. For example, to skip the check for symbolic link
  6504. <filename>.so</filename> files in the main package of a
  6505. recipe, add the following to the recipe.
  6506. The package name override must be used, which in this
  6507. example is <filename>${PN}</filename>:
  6508. <literallayout class='monospaced'>
  6509. INSANE_SKIP_${PN} += "dev-so"
  6510. </literallayout>
  6511. </para>
  6512. <para>
  6513. See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
  6514. section for a list of the valid QA checks you can
  6515. specify using this variable.
  6516. </para>
  6517. </glossdef>
  6518. </glossentry>
  6519. <glossentry id='var-INSTALL_TIMEZONE_FILE'><glossterm>INSTALL_TIMEZONE_FILE</glossterm>
  6520. <info>
  6521. INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."
  6522. </info>
  6523. <glossdef>
  6524. <para role="glossdeffirst">
  6525. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6526. By default, the <filename>tzdata</filename> recipe packages
  6527. an <filename>/etc/timezone</filename> file.
  6528. Set the <filename>INSTALL_TIMEZONE_FILE</filename>
  6529. variable to "0" at the configuration level to disable this
  6530. behavior.
  6531. </para>
  6532. </glossdef>
  6533. </glossentry>
  6534. <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
  6535. <info>
  6536. IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."
  6537. </info>
  6538. <glossdef>
  6539. <para role="glossdeffirst">
  6540. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6541. When the IPK backend is in use and package management
  6542. is enabled on the target, you can use this variable to
  6543. set up <filename>opkg</filename> in the target image
  6544. to point to package feeds on a nominated server.
  6545. Once the feed is established, you can perform
  6546. installations or upgrades using the package manager
  6547. at runtime.
  6548. </para>
  6549. </glossdef>
  6550. </glossentry>
  6551. <!--
  6552. <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
  6553. <glossdef>
  6554. <para>
  6555. An environment variable that defines the directory where
  6556. post installation hooks are installed for the
  6557. post install environment.
  6558. This variable is fixed as follows:
  6559. <literallayout class='monospaced'>
  6560. ${WORKDIR}/intercept_scripts
  6561. </literallayout>
  6562. </para>
  6563. <para>
  6564. After installation of a target's root filesystem,
  6565. post installation scripts, which are essentially bash scripts,
  6566. are all executed just a single time.
  6567. Limiting execution of these scripts minimizes installation
  6568. time that would be lengthened due to certain packages
  6569. triggering redundant operations.
  6570. For example, consider the installation of font packages
  6571. as a common example.
  6572. Without limiting the execution of post installation scripts,
  6573. all font directories would be rescanned to create the
  6574. cache after each individual font package was installed.
  6575. </para>
  6576. <para>
  6577. Do not edit the <filename>INTERCEPT_DIR</filename>
  6578. variable.
  6579. </para>
  6580. </glossdef>
  6581. </glossentry>
  6582. -->
  6583. </glossdiv>
  6584. <!-- <glossdiv id='var-glossary-j'><title>J</title>-->
  6585. <!-- </glossdiv>-->
  6586. <glossdiv id='var-glossary-k'><title>K</title>
  6587. <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
  6588. <info>
  6589. KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."
  6590. </info>
  6591. <glossdef>
  6592. <para role="glossdeffirst">
  6593. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6594. Defines the kernel architecture used when assembling
  6595. the configuration.
  6596. Architectures supported for this release are:
  6597. <literallayout class='monospaced'>
  6598. powerpc
  6599. i386
  6600. x86_64
  6601. arm
  6602. qemu
  6603. mips
  6604. </literallayout>
  6605. </para>
  6606. <para>
  6607. You define the <filename>KARCH</filename> variable in the
  6608. <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
  6609. </para>
  6610. </glossdef>
  6611. </glossentry>
  6612. <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
  6613. <info>
  6614. KBRANCH[doc] = "A regular expression used by the build process to explicitly identify the kernel branch that is validated, patched, and configured during a build."
  6615. </info>
  6616. <glossdef>
  6617. <para role="glossdeffirst">
  6618. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6619. A regular expression used by the build process to explicitly
  6620. identify the kernel branch that is validated, patched,
  6621. and configured during a build.
  6622. You must set this variable to ensure the exact kernel
  6623. branch you want is being used by the build process.
  6624. </para>
  6625. <para>
  6626. Values for this variable are set in the kernel's recipe
  6627. file and the kernel's append file.
  6628. For example, if you are using the
  6629. <filename>linux-yocto_4.12</filename> kernel, the kernel
  6630. recipe file is the
  6631. <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>
  6632. file.
  6633. <filename>KBRANCH</filename> is set as follows in that
  6634. kernel recipe file:
  6635. <literallayout class='monospaced'>
  6636. KBRANCH ?= "standard/base"
  6637. </literallayout>
  6638. </para>
  6639. <para>
  6640. This variable is also used from the kernel's append file
  6641. to identify the kernel branch specific to a particular
  6642. machine or target hardware.
  6643. Continuing with the previous kernel example, the kernel's
  6644. append file (i.e.
  6645. <filename>linux-yocto_4.12.bbappend</filename>) is located
  6646. in the BSP layer for a given machine.
  6647. For example, the append file for the Beaglebone,
  6648. EdgeRouter, and generic versions of both 32 and 64-bit IA
  6649. machines (<filename>meta-yocto-bsp</filename>) is named
  6650. <filename>meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend</filename>.
  6651. Here are the related statements from that append file:
  6652. <literallayout class='monospaced'>
  6653. KBRANCH_genericx86 = "standard/base"
  6654. KBRANCH_genericx86-64 = "standard/base"
  6655. KBRANCH_edgerouter = "standard/edgerouter"
  6656. KBRANCH_beaglebone = "standard/beaglebone"
  6657. KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
  6658. </literallayout>
  6659. The <filename>KBRANCH</filename> statements identify
  6660. the kernel branch to use when building for each
  6661. supported BSP.
  6662. </para>
  6663. </glossdef>
  6664. </glossentry>
  6665. <glossentry id='var-KBUILD_DEFCONFIG'><glossterm>KBUILD_DEFCONFIG</glossterm>
  6666. <info>
  6667. KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."
  6668. </info>
  6669. <glossdef>
  6670. <para role="glossdeffirst">
  6671. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6672. When used with the
  6673. <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
  6674. class, specifies an "in-tree" kernel configuration file
  6675. for use during a kernel build.
  6676. </para>
  6677. <para>
  6678. Typically, when using a <filename>defconfig</filename> to
  6679. configure a kernel during a build, you place the
  6680. file in your layer in the same manner as you would
  6681. place patch files and configuration fragment files (i.e.
  6682. "out-of-tree").
  6683. However, if you want to use a <filename>defconfig</filename>
  6684. file that is part of the kernel tree (i.e. "in-tree"),
  6685. you can use the
  6686. <filename>KBUILD_DEFCONFIG</filename> variable and append
  6687. the
  6688. <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
  6689. variable to point to the <filename>defconfig</filename>
  6690. file.
  6691. </para>
  6692. <para>
  6693. To use the variable, set it in the append file for your
  6694. kernel recipe using the following form:
  6695. <literallayout class='monospaced'>
  6696. KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
  6697. </literallayout>
  6698. Here is an example from a "raspberrypi2"
  6699. <filename>KMACHINE</filename> build that uses a
  6700. <filename>defconfig</filename> file named
  6701. "bcm2709_defconfig":
  6702. <literallayout class='monospaced'>
  6703. KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"
  6704. </literallayout>
  6705. As an alternative, you can use the following within your
  6706. append file:
  6707. <literallayout class='monospaced'>
  6708. KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>
  6709. </literallayout>
  6710. For more information on how to use the
  6711. <filename>KBUILD_DEFCONFIG</filename> variable, see the
  6712. "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-an-in-tree-defconfig-file'>Using an "In-Tree" <filename>defconfig</filename> File</ulink>"
  6713. section.
  6714. </para>
  6715. </glossdef>
  6716. </glossentry>
  6717. <glossentry id='var-KERNEL_ALT_IMAGETYPE'><glossterm>KERNEL_ALT_IMAGETYPE</glossterm>
  6718. <info>
  6719. KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."
  6720. </info>
  6721. <glossdef>
  6722. <para role="glossdeffirst">
  6723. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6724. Specifies an alternate kernel image type for creation in
  6725. addition to the kernel image type specified using the
  6726. <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
  6727. variable.
  6728. </para>
  6729. </glossdef>
  6730. </glossentry>
  6731. <glossentry id='var-KERNEL_CLASSES'><glossterm>KERNEL_CLASSES</glossterm>
  6732. <info>
  6733. KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."
  6734. </info>
  6735. <glossdef>
  6736. <para role="glossdeffirst">
  6737. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6738. A list of classes defining kernel image types that the
  6739. <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
  6740. class should inherit.
  6741. You typically append this variable to enable extended image
  6742. types.
  6743. An example is the "kernel-fitimage", which enables
  6744. fitImage support and resides in
  6745. <filename>meta/classes/kernel-fitimage.bbclass</filename>.
  6746. You can register custom kernel image types with the
  6747. <filename>kernel</filename> class using this variable.
  6748. </para>
  6749. </glossdef>
  6750. </glossentry>
  6751. <glossentry id='var-KERNEL_DEVICETREE'><glossterm>KERNEL_DEVICETREE</glossterm>
  6752. <info>
  6753. KERNEL_DEVICETREE[doc] = "Specifies the name of the generated Linux kernel device tree (i.e. the .dtb) file."
  6754. </info>
  6755. <glossdef>
  6756. <para role="glossdeffirst">
  6757. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6758. Specifies the name of the generated Linux kernel device tree
  6759. (i.e. the <filename>.dtb</filename>) file.
  6760. <note>
  6761. Legacy support exists for specifying the full path
  6762. to the device tree.
  6763. However, providing just the <filename>.dtb</filename>
  6764. file is preferred.
  6765. </note>
  6766. In order to use this variable, you must have the include
  6767. files in your kernel recipe:
  6768. <literallayout class='monospaced'>
  6769. require recipes-kernel/linux/linux-dtb.inc
  6770. </literallayout>
  6771. or
  6772. <literallayout class='monospaced'>
  6773. require recipes-kernel/linux/linux-yocto.inc
  6774. </literallayout>
  6775. </para>
  6776. </glossdef>
  6777. </glossentry>
  6778. <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
  6779. <info>
  6780. KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."
  6781. </info>
  6782. <glossdef>
  6783. <para role="glossdeffirst">
  6784. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6785. Specifies additional <filename>make</filename>
  6786. command-line arguments the OpenEmbedded build system
  6787. passes on when compiling the kernel.
  6788. </para>
  6789. </glossdef>
  6790. </glossentry>
  6791. <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
  6792. <info>
  6793. KERNEL_FEATURES[doc] = "Includes additional kernel metadata. The metadata you add through this variable includes config fragments and features descriptions."
  6794. </info>
  6795. <glossdef>
  6796. <para role="glossdeffirst">
  6797. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6798. Includes additional kernel metadata.
  6799. In the OpenEmbedded build system, the default Board Support
  6800. Packages (BSPs)
  6801. <link linkend='metadata'>Metadata</link>
  6802. is provided through
  6803. the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
  6804. and
  6805. <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>
  6806. variables.
  6807. You can use the <filename>KERNEL_FEATURES</filename>
  6808. variable from within the kernel recipe or kernel append
  6809. file to further add metadata for all BSPs or specific
  6810. BSPs.
  6811. </para>
  6812. <para>
  6813. The metadata you add through this variable includes config
  6814. fragments and features descriptions,
  6815. which usually includes patches as well as config fragments.
  6816. You typically override the
  6817. <filename>KERNEL_FEATURES</filename> variable for a
  6818. specific machine.
  6819. In this way, you can provide validated, but optional,
  6820. sets of kernel configurations and features.
  6821. </para>
  6822. <para>
  6823. For example, the following example from the
  6824. <filename>linux-yocto-rt_4.12</filename> kernel recipe
  6825. adds "netfilter" and "taskstats" features to all BSPs
  6826. as well as "virtio" configurations to all QEMU machines.
  6827. The last two statements add specific configurations to
  6828. targeted machine types:
  6829. <literallayout class='monospaced'>
  6830. KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
  6831. KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
  6832. KERNEL_FEATURES_append_qemuall=" cfg/virtio.scc"
  6833. KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
  6834. KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc"
  6835. </literallayout></para>
  6836. </glossdef>
  6837. </glossentry>
  6838. <glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm>KERNEL_IMAGE_BASE_NAME</glossterm>
  6839. <info>
  6840. KERNEL_IMAGE_BASE_NAME[doc] = "The base name of the kernel image."
  6841. </info>
  6842. <glossdef>
  6843. <para role="glossdeffirst">
  6844. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6845. The base name of the kernel image.
  6846. This variable is set in the
  6847. <link linkend='ref-classes-kernel'>kernel</link> class
  6848. as follows:
  6849. <literallayout class='monospaced'>
  6850. KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
  6851. </literallayout>
  6852. </para>
  6853. <para>
  6854. See the
  6855. <link linkend='var-PKGE'><filename>PKGE</filename></link>,
  6856. <link linkend='var-PKGV'><filename>PKGV</filename></link>,
  6857. <link linkend='var-PKGR'><filename>PKGR</filename></link>,
  6858. <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
  6859. and
  6860. <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
  6861. variables for additional information.
  6862. </para>
  6863. </glossdef>
  6864. </glossentry>
  6865. <glossentry id='var-KERNEL_IMAGE_MAXSIZE'><glossterm>KERNEL_IMAGE_MAXSIZE</glossterm>
  6866. <info>
  6867. KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."
  6868. </info>
  6869. <glossdef>
  6870. <para role="glossdeffirst">
  6871. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6872. Specifies the maximum size of the kernel image file in
  6873. kilobytes.
  6874. If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,
  6875. the size of the kernel image file is checked against
  6876. the set value during the
  6877. <link linkend='ref-tasks-sizecheck'><filename>do_sizecheck</filename></link>
  6878. task.
  6879. The task fails if the kernel image file is larger than
  6880. the setting.
  6881. </para>
  6882. <para>
  6883. <filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for
  6884. target devices that have a limited amount of space in
  6885. which the kernel image must be stored.
  6886. </para>
  6887. <para>
  6888. By default, this variable is not set, which means the
  6889. size of the kernel image is not checked.
  6890. </para>
  6891. </glossdef>
  6892. </glossentry>
  6893. <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
  6894. <info>
  6895. KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."
  6896. </info>
  6897. <glossdef>
  6898. <para role="glossdeffirst">
  6899. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6900. The type of kernel to build for a device, usually set by the
  6901. machine configuration files and defaults to "zImage".
  6902. This variable is used
  6903. when building the kernel and is passed to <filename>make</filename> as the target to
  6904. build.
  6905. </para>
  6906. <para>
  6907. If you want to build an alternate kernel image type, use the
  6908. <link linkend='var-KERNEL_ALT_IMAGETYPE'><filename>KERNEL_ALT_IMAGETYPE</filename></link>
  6909. variable.
  6910. </para>
  6911. </glossdef>
  6912. </glossentry>
  6913. <glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm>KERNEL_MODULE_AUTOLOAD</glossterm>
  6914. <info>
  6915. KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"
  6916. </info>
  6917. <glossdef>
  6918. <para role="glossdeffirst">
  6919. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6920. Lists kernel modules that need to be auto-loaded during
  6921. boot.
  6922. <note>
  6923. This variable replaces the deprecated
  6924. <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
  6925. variable.
  6926. </note>
  6927. </para>
  6928. <para>
  6929. You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>
  6930. variable anywhere that it can be
  6931. recognized by the kernel recipe or by an out-of-tree kernel
  6932. module recipe (e.g. a machine configuration file, a
  6933. distribution configuration file, an append file for the
  6934. recipe, or the recipe itself).
  6935. </para>
  6936. <para>
  6937. Specify it as follows:
  6938. <literallayout class='monospaced'>
  6939. KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name1</replaceable> <replaceable>module_name2</replaceable> <replaceable>module_name3</replaceable>"
  6940. </literallayout>
  6941. </para>
  6942. <para>
  6943. Including <filename>KERNEL_MODULE_AUTOLOAD</filename> causes
  6944. the OpenEmbedded build system to populate the
  6945. <filename>/etc/modules-load.d/modname.conf</filename>
  6946. file with the list of modules to be auto-loaded on boot.
  6947. The modules appear one-per-line in the file.
  6948. Here is an example of the most common use case:
  6949. <literallayout class='monospaced'>
  6950. KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"
  6951. </literallayout>
  6952. </para>
  6953. <para>
  6954. For information on how to populate the
  6955. <filename>modname.conf</filename> file with
  6956. <filename>modprobe.d</filename> syntax lines, see the
  6957. <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
  6958. variable.
  6959. </para>
  6960. </glossdef>
  6961. </glossentry>
  6962. <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>
  6963. <info>
  6964. KERNEL_MODULE_PROBECONF[doc] = "Lists kernel modules for which the build system expects to find module_conf_* values that specify configuration for each of the modules."
  6965. </info>
  6966. <glossdef>
  6967. <para role="glossdeffirst">
  6968. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6969. Provides a list of modules for which the OpenEmbedded
  6970. build system expects to find
  6971. <filename>module_conf_</filename><replaceable>modname</replaceable>
  6972. values that specify configuration for each of the modules.
  6973. For information on how to provide those module
  6974. configurations, see the
  6975. <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
  6976. variable.
  6977. </para>
  6978. </glossdef>
  6979. </glossentry>
  6980. <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
  6981. <info>
  6982. KERNEL_PATH[doc] = "The location of the kernel sources. This variable is set to the value of the STAGING_KERNEL_DIR within the module class (module.bbclass)."
  6983. </info>
  6984. <glossdef>
  6985. <para role="glossdeffirst">
  6986. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  6987. The location of the kernel sources.
  6988. This variable is set to the value of the
  6989. <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
  6990. within the
  6991. <link linkend='ref-classes-module'><filename>module</filename></link>
  6992. class.
  6993. For information on how this variable is used, see the
  6994. "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
  6995. section.
  6996. </para>
  6997. <para>
  6998. To help maximize compatibility with out-of-tree drivers
  6999. used to build modules, the OpenEmbedded build system also
  7000. recognizes and uses the
  7001. <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
  7002. variable, which is identical to the
  7003. <filename>KERNEL_PATH</filename> variable.
  7004. Both variables are common variables used by external
  7005. Makefiles to point to the kernel source directory.
  7006. </para>
  7007. </glossdef>
  7008. </glossentry>
  7009. <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
  7010. <info>
  7011. KERNEL_SRC[doc] = "The location of the kernel sources. This variable is set to the value of the STAGING_KERNEL_DIR within the module class (module.bbclass)."
  7012. </info>
  7013. <glossdef>
  7014. <para role="glossdeffirst">
  7015. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7016. The location of the kernel sources.
  7017. This variable is set to the value of the
  7018. <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
  7019. within the
  7020. <link linkend='ref-classes-module'><filename>module</filename></link>
  7021. class.
  7022. For information on how this variable is used, see the
  7023. "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
  7024. section.
  7025. </para>
  7026. <para>
  7027. To help maximize compatibility with out-of-tree drivers
  7028. used to build modules, the OpenEmbedded build system also
  7029. recognizes and uses the
  7030. <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
  7031. variable, which is identical to the
  7032. <filename>KERNEL_SRC</filename> variable.
  7033. Both variables are common variables used by external
  7034. Makefiles to point to the kernel source directory.
  7035. </para>
  7036. </glossdef>
  7037. </glossentry>
  7038. <glossentry id='var-KERNEL_VERSION'><glossterm>KERNEL_VERSION</glossterm>
  7039. <info>
  7040. KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."
  7041. </info>
  7042. <glossdef>
  7043. <para role="glossdeffirst">
  7044. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7045. Specifies the version of the kernel as extracted from
  7046. <filename>version.h</filename> or
  7047. <filename>utsrelease.h</filename> within the kernel sources.
  7048. Effects of setting this variable do not take affect until
  7049. the kernel has been configured.
  7050. Consequently, attempting to refer to this variable in
  7051. contexts prior to configuration will not work.
  7052. </para>
  7053. </glossdef>
  7054. </glossentry>
  7055. <glossentry id='var-KERNELDEPMODDEPEND'><glossterm>KERNELDEPMODDEPEND</glossterm>
  7056. <info>
  7057. KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."
  7058. </info>
  7059. <glossdef>
  7060. <para role="glossdeffirst">
  7061. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7062. Specifies whether the data referenced through
  7063. <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
  7064. is needed or not.
  7065. The <filename>KERNELDEPMODDEPEND</filename> does not
  7066. control whether or not that data exists,
  7067. but simply whether or not it is used.
  7068. If you do not need to use the data, set the
  7069. <filename>KERNELDEPMODDEPEND</filename> variable in your
  7070. <filename>initramfs</filename> recipe.
  7071. Setting the variable there when the data is not needed
  7072. avoids a potential dependency loop.
  7073. </para>
  7074. </glossdef>
  7075. </glossentry>
  7076. <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
  7077. <info>
  7078. KFEATURE_DESCRIPTION[doc] = "Provides a short description of a configuration fragment. You use this variable in the .scc file that describes a configuration fragment file."
  7079. </info>
  7080. <glossdef>
  7081. <para role="glossdeffirst">
  7082. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7083. Provides a short description of a configuration fragment.
  7084. You use this variable in the <filename>.scc</filename>
  7085. file that describes a configuration fragment file.
  7086. Here is the variable used in a file named
  7087. <filename>smp.scc</filename> to describe SMP being
  7088. enabled:
  7089. <literallayout class='monospaced'>
  7090. define KFEATURE_DESCRIPTION "Enable SMP"
  7091. </literallayout>
  7092. </para>
  7093. </glossdef>
  7094. </glossentry>
  7095. <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
  7096. <info>
  7097. KMACHINE[doc] = "The machine as known by the kernel."
  7098. </info>
  7099. <glossdef>
  7100. <para role="glossdeffirst">
  7101. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7102. The machine as known by the kernel.
  7103. Sometimes the machine name used by the kernel does not
  7104. match the machine name used by the OpenEmbedded build
  7105. system.
  7106. For example, the machine name that the OpenEmbedded build
  7107. system understands as
  7108. <filename>core2-32-intel-common</filename> goes by a
  7109. different name in the Linux Yocto kernel.
  7110. The kernel understands that machine as
  7111. <filename>intel-core2-32</filename>.
  7112. For cases like these, the <filename>KMACHINE</filename>
  7113. variable maps the kernel machine name to the OpenEmbedded
  7114. build system machine name.
  7115. </para>
  7116. <para>
  7117. These mappings between different names occur in the
  7118. Yocto Linux Kernel's <filename>meta</filename> branch.
  7119. As an example take a look in the
  7120. <filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>
  7121. file:
  7122. <literallayout class='monospaced'>
  7123. LINUX_VERSION_core2-32-intel-common = "3.19.0"
  7124. COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"
  7125. SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
  7126. SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
  7127. KMACHINE_core2-32-intel-common = "intel-core2-32"
  7128. KBRANCH_core2-32-intel-common = "standard/base"
  7129. KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
  7130. </literallayout>
  7131. The <filename>KMACHINE</filename> statement says that
  7132. the kernel understands the machine name as
  7133. "intel-core2-32".
  7134. However, the OpenEmbedded build system understands the
  7135. machine as "core2-32-intel-common".
  7136. </para>
  7137. </glossdef>
  7138. </glossentry>
  7139. <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
  7140. <info>
  7141. KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
  7142. </info>
  7143. <glossdef>
  7144. <para role="glossdeffirst">
  7145. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7146. Defines the kernel type to be used in assembling the
  7147. configuration.
  7148. The linux-yocto recipes define "standard", "tiny",
  7149. and "preempt-rt" kernel types.
  7150. See the
  7151. "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
  7152. section in the Yocto Project Linux Kernel Development
  7153. Manual for more information on kernel types.
  7154. </para>
  7155. <para>
  7156. You define the <filename>KTYPE</filename> variable in the
  7157. <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
  7158. The value you use must match the value used for the
  7159. <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
  7160. value used by the kernel recipe.
  7161. </para>
  7162. </glossdef>
  7163. </glossentry>
  7164. </glossdiv>
  7165. <glossdiv id='var-glossary-l'><title>L</title>
  7166. <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
  7167. <info>
  7168. LABELS[doc] = "Provides a list of targets for automatic configuration."
  7169. </info>
  7170. <glossdef>
  7171. <para role="glossdeffirst">
  7172. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7173. Provides a list of targets for automatic configuration.
  7174. </para>
  7175. <para>
  7176. See the
  7177. <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
  7178. class for more information on how this variable is used.
  7179. </para>
  7180. </glossdef>
  7181. </glossentry>
  7182. <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
  7183. <info>
  7184. LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, on which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer."
  7185. </info>
  7186. <glossdef>
  7187. <para role="glossdeffirst">
  7188. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7189. Lists the layers, separated by spaces, on which this
  7190. recipe depends.
  7191. Optionally, you can specify a specific layer version for a
  7192. dependency by adding it to the end of the layer name.
  7193. Here is an example:
  7194. <literallayout class='monospaced'>
  7195. LAYERDEPENDS_mylayer = "anotherlayer (=3)"
  7196. </literallayout>
  7197. In this previous example, version 3 of "anotherlayer"
  7198. is compared against
  7199. <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>.
  7200. </para>
  7201. <para>
  7202. An error is produced if any dependency is missing or
  7203. the version numbers (if specified) do not match exactly.
  7204. This variable is used in the
  7205. <filename>conf/layer.conf</filename> file and must be
  7206. suffixed with the name of the specific layer (e.g.
  7207. <filename>LAYERDEPENDS_mylayer</filename>).
  7208. </para>
  7209. </glossdef>
  7210. </glossentry>
  7211. <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
  7212. <info>
  7213. LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."
  7214. </info>
  7215. <glossdef>
  7216. <para role="glossdeffirst">
  7217. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7218. When used inside the <filename>layer.conf</filename> configuration
  7219. file, this variable provides the path of the current layer.
  7220. This variable is not available outside of <filename>layer.conf</filename>
  7221. and references are expanded immediately when parsing of the file completes.
  7222. </para>
  7223. </glossdef>
  7224. </glossentry>
  7225. <glossentry id='var-LAYERRECOMMENDS'><glossterm>LAYERRECOMMENDS</glossterm>
  7226. <info>
  7227. LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer."
  7228. </info>
  7229. <glossdef>
  7230. <para role="glossdeffirst">
  7231. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7232. Lists the layers, separated by spaces, recommended for
  7233. use with this layer.
  7234. </para>
  7235. <para>
  7236. Optionally, you can specify a specific layer version for a
  7237. recommendation by adding the version to the end of the
  7238. layer name.
  7239. Here is an example:
  7240. <literallayout class='monospaced'>
  7241. LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
  7242. </literallayout>
  7243. In this previous example, version 3 of "anotherlayer" is
  7244. compared against
  7245. <filename>LAYERVERSION_anotherlayer</filename>.
  7246. </para>
  7247. <para>
  7248. This variable is used in the
  7249. <filename>conf/layer.conf</filename> file and must be
  7250. suffixed with the name of the specific layer (e.g.
  7251. <filename>LAYERRECOMMENDS_mylayer</filename>).
  7252. </para>
  7253. </glossdef>
  7254. </glossentry>
  7255. <glossentry id='var-LAYERSERIES_COMPAT'><glossterm>LAYERSERIES_COMPAT</glossterm>
  7256. <info>
  7257. LAYERSERIES_COMPAT[doc] = "Lists the OpenEmbedded-Core versions for which a layer is compatible."
  7258. </info>
  7259. <glossdef>
  7260. <para role="glossdeffirst">
  7261. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7262. Lists the versions of the
  7263. <link linkend='oe-core'>OpenEmbedded-Core</link> for which
  7264. a layer is compatible.
  7265. Using the <filename>LAYERSERIES_COMPAT</filename> variable
  7266. allows the layer maintainer to indicate which combinations
  7267. of the layer and OE-Core can be expected to work.
  7268. The variable gives the system a way to detect when a layer
  7269. has not been tested with new releases of OE-Core (e.g.
  7270. the layer is not maintained).
  7271. </para>
  7272. <para>
  7273. To specify the OE-Core versions for which a layer is
  7274. compatible, use this variable in your layer's
  7275. <filename>conf/layer.conf</filename> configuration file.
  7276. For the list, use the Yocto Project
  7277. <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Release Name</ulink>
  7278. (e.g. &DISTRO_NAME_NO_CAP;).
  7279. To specify multiple OE-Core versions for the layer,
  7280. use a space-separated list:
  7281. <literallayout class='monospaced'>
  7282. LAYERSERIES_COMPAT_<replaceable>layer_root_name</replaceable> = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
  7283. </literallayout>
  7284. <note>
  7285. Setting <filename>LAYERSERIES_COMPAT</filename> is
  7286. required by the Yocto Project Compatible version 2
  7287. standard.
  7288. The OpenEmbedded build system produces a warning if
  7289. the variable is not set for any given layer.
  7290. </note>
  7291. </para>
  7292. <para>
  7293. See the
  7294. "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-layer'>Creating Your Own Layer</ulink>"
  7295. section in the Yocto Project Development Tasks Manual.
  7296. </para>
  7297. </glossdef>
  7298. </glossentry>
  7299. <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
  7300. <info>
  7301. LAYERVERSION[doc] = "Optionally specifies the version of a layer as a single number. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer."
  7302. </info>
  7303. <glossdef>
  7304. <para role="glossdeffirst">
  7305. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7306. Optionally specifies the version of a layer as a single number.
  7307. You can use this within
  7308. <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
  7309. for another layer in order to depend on a specific version
  7310. of the layer.
  7311. This variable is used in the <filename>conf/layer.conf</filename> file
  7312. and must be suffixed with the name of the specific layer (e.g.
  7313. <filename>LAYERVERSION_mylayer</filename>).
  7314. </para>
  7315. </glossdef>
  7316. </glossentry>
  7317. <glossentry id='var-LD'><glossterm>LD</glossterm>
  7318. <info>
  7319. LD[doc] = "Minimal command and arguments to run the linker."
  7320. </info>
  7321. <glossdef>
  7322. <para role="glossdeffirst">
  7323. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7324. The minimal command and arguments used to run the
  7325. linker.
  7326. </para>
  7327. </glossdef>
  7328. </glossentry>
  7329. <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>
  7330. <info>
  7331. LDFLAGS[doc] = "Specifies the flags to pass to the linker."
  7332. </info>
  7333. <glossdef>
  7334. <para role="glossdeffirst">
  7335. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7336. Specifies the flags to pass to the linker.
  7337. This variable is exported to an environment
  7338. variable and thus made visible to the software being
  7339. built during the compilation step.
  7340. </para>
  7341. <para>
  7342. Default initialization for <filename>LDFLAGS</filename>
  7343. varies depending on what is being built:
  7344. <itemizedlist>
  7345. <listitem><para>
  7346. <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
  7347. when building for the target
  7348. </para></listitem>
  7349. <listitem><para>
  7350. <link linkend='var-BUILD_LDFLAGS'><filename>BUILD_LDFLAGS</filename></link>
  7351. when building for the build host (i.e.
  7352. <filename>-native</filename>)
  7353. </para></listitem>
  7354. <listitem><para>
  7355. <link linkend='var-BUILDSDK_LDFLAGS'><filename>BUILDSDK_LDFLAGS</filename></link>
  7356. when building for an SDK (i.e.
  7357. <filename>nativesdk-</filename>)
  7358. </para></listitem>
  7359. </itemizedlist>
  7360. </para>
  7361. </glossdef>
  7362. </glossentry>
  7363. <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
  7364. <info>
  7365. LEAD_SONAME[doc] = "Specifies the lead (or primary) compiled library file (i.e. .so) that the debian class applies its naming policy to given a recipe that packages multiple libraries."
  7366. </info>
  7367. <glossdef>
  7368. <para role="glossdeffirst">
  7369. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7370. Specifies the lead (or primary) compiled library file
  7371. (i.e. <filename>.so</filename>) that the
  7372. <link linkend='ref-classes-debian'><filename>debian</filename></link>
  7373. class applies its naming policy to given a recipe that
  7374. packages multiple libraries.
  7375. </para>
  7376. <para>
  7377. This variable works in conjunction with the
  7378. <filename>debian</filename> class.
  7379. </para>
  7380. </glossdef>
  7381. </glossentry>
  7382. <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
  7383. <info>
  7384. LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."
  7385. </info>
  7386. <glossdef>
  7387. <para role="glossdeffirst">
  7388. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7389. Checksums of the license text in the recipe source code.
  7390. </para>
  7391. <para>
  7392. This variable tracks changes in license text of the source
  7393. code files.
  7394. If the license text is changed, it will trigger a build
  7395. failure, which gives the developer an opportunity to review any
  7396. license change.
  7397. </para>
  7398. <para>
  7399. This variable must be defined for all recipes (unless
  7400. <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
  7401. is set to "CLOSED").</para>
  7402. <para>For more information, see the
  7403. "<ulink url='&YOCTO_DOCS_OM_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
  7404. section in the Yocto Project Overview and Concepts Manual.
  7405. </para>
  7406. </glossdef>
  7407. </glossentry>
  7408. <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
  7409. <info>
  7410. LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &amp;, '|', and parentheses can be used."
  7411. </info>
  7412. <glossdef>
  7413. <para role="glossdeffirst">
  7414. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7415. The list of source licenses for the recipe.
  7416. Follow these rules:
  7417. <itemizedlist>
  7418. <listitem><para>Do not use spaces within individual
  7419. license names.</para></listitem>
  7420. <listitem><para>Separate license names using
  7421. | (pipe) when there is a choice between licenses.
  7422. </para></listitem>
  7423. <listitem><para>Separate license names using
  7424. &amp; (ampersand) when multiple licenses exist
  7425. that cover different parts of the source.
  7426. </para></listitem>
  7427. <listitem><para>You can use spaces between license
  7428. names.</para></listitem>
  7429. <listitem><para>For standard licenses, use the names
  7430. of the files in
  7431. <filename>meta/files/common-licenses/</filename>
  7432. or the
  7433. <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
  7434. flag names defined in
  7435. <filename>meta/conf/licenses.conf</filename>.
  7436. </para></listitem>
  7437. </itemizedlist>
  7438. </para>
  7439. <para>
  7440. Here are some examples:
  7441. <literallayout class='monospaced'>
  7442. LICENSE = "LGPLv2.1 | GPLv3"
  7443. LICENSE = "MPL-1 &amp; LGPLv2.1"
  7444. LICENSE = "GPLv2+"
  7445. </literallayout>
  7446. The first example is from the recipes for Qt, which the user
  7447. may choose to distribute under either the LGPL version
  7448. 2.1 or GPL version 3.
  7449. The second example is from Cairo where two licenses cover
  7450. different parts of the source code.
  7451. The final example is from <filename>sysstat</filename>,
  7452. which presents a single license.
  7453. </para>
  7454. <para>
  7455. You can also specify licenses on a per-package basis to
  7456. handle situations where components of the output have
  7457. different licenses.
  7458. For example, a piece of software whose code is
  7459. licensed under GPLv2 but has accompanying documentation
  7460. licensed under the GNU Free Documentation License 1.2 could
  7461. be specified as follows:
  7462. <literallayout class='monospaced'>
  7463. LICENSE = "GFDL-1.2 &amp; GPLv2"
  7464. LICENSE_${PN} = "GPLv2"
  7465. LICENSE_${PN}-doc = "GFDL-1.2"
  7466. </literallayout>
  7467. </para>
  7468. </glossdef>
  7469. </glossentry>
  7470. <glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm>
  7471. <info>
  7472. LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."
  7473. </info>
  7474. <glossdef>
  7475. <para role="glossdeffirst">
  7476. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7477. Setting <filename>LICENSE_CREATE_PACKAGE</filename>
  7478. to "1" causes the OpenEmbedded build system to create
  7479. an extra package (i.e.
  7480. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)
  7481. for each recipe and to add those packages to the
  7482. <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link><filename>_${PN}</filename>.
  7483. </para>
  7484. <para>
  7485. The <filename>${PN}-lic</filename> package installs a
  7486. directory in <filename>/usr/share/licenses</filename>
  7487. named <filename>${PN}</filename>, which is the recipe's
  7488. base name, and installs files in that directory that
  7489. contain license and copyright information (i.e. copies of
  7490. the appropriate license files from
  7491. <filename>meta/common-licenses</filename> that match the
  7492. licenses specified in the
  7493. <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
  7494. variable of the recipe metadata and copies of files marked
  7495. in
  7496. <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
  7497. as containing license text).
  7498. </para>
  7499. <para>
  7500. For related information on providing license text, see the
  7501. <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
  7502. variable, the
  7503. <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
  7504. variable, and the
  7505. "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
  7506. section in the Yocto Project Development Tasks Manual.
  7507. </para>
  7508. </glossdef>
  7509. </glossentry>
  7510. <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm>
  7511. <info>
  7512. LICENSE_FLAGS[doc] = "Specifies additional flags for a recipe you must whitelist through LICENSE_FLAGS_WHITELIST in order to allow the recipe to be built."
  7513. </info>
  7514. <glossdef>
  7515. <para role="glossdeffirst">
  7516. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7517. Specifies additional flags for a recipe you must
  7518. whitelist through
  7519. <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
  7520. in order to allow the recipe to be built.
  7521. When providing multiple flags, separate them with
  7522. spaces.
  7523. </para>
  7524. <para>
  7525. This value is independent of
  7526. <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
  7527. and is typically used to mark recipes that might
  7528. require additional licenses in order to be used in a
  7529. commercial product.
  7530. For more information, see the
  7531. "<ulink url='&YOCTO_DOCS_OM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
  7532. section in the Yocto Project Overview and Concepts Manual.
  7533. </para>
  7534. </glossdef>
  7535. </glossentry>
  7536. <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>LICENSE_FLAGS_WHITELIST</glossterm>
  7537. <info>
  7538. LICENSE_FLAGS_WHITELIST[doc] = "Lists license flags that when specified in LICENSE_FLAGS within a recipe should not prevent that recipe from being built."
  7539. </info>
  7540. <glossdef>
  7541. <para role="glossdeffirst">
  7542. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7543. Lists license flags that when specified in
  7544. <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
  7545. within a recipe should not prevent that recipe from being
  7546. built.
  7547. This practice is otherwise known as "whitelisting"
  7548. license flags.
  7549. For more information, see the
  7550. <ulink url='&YOCTO_DOCS_OM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
  7551. section in the Yocto Project Overview and Concepts Manual.
  7552. </para>
  7553. </glossdef>
  7554. </glossentry>
  7555. <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
  7556. <info>
  7557. LICENSE_PATH[doc] = "Path to additional licenses used during the build."
  7558. </info>
  7559. <glossdef>
  7560. <para role="glossdeffirst">
  7561. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7562. Path to additional licenses used during the build.
  7563. By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
  7564. to define the directory that holds common license text used during the build.
  7565. The <filename>LICENSE_PATH</filename> variable allows you to extend that
  7566. location to other areas that have additional licenses:
  7567. <literallayout class='monospaced'>
  7568. LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"
  7569. </literallayout>
  7570. </para>
  7571. </glossdef>
  7572. </glossentry>
  7573. <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
  7574. <info>
  7575. LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
  7576. </info>
  7577. <glossdef>
  7578. <para role="glossdeffirst">
  7579. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7580. Defines the kernel type to be used in assembling the
  7581. configuration.
  7582. The linux-yocto recipes define "standard", "tiny", and
  7583. "preempt-rt" kernel types.
  7584. See the
  7585. "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
  7586. section in the Yocto Project Linux Kernel Development
  7587. Manual for more information on kernel types.
  7588. </para>
  7589. <para>
  7590. If you do not specify a
  7591. <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
  7592. "standard".
  7593. Together with
  7594. <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
  7595. the <filename>LINUX_KERNEL_TYPE</filename> variable
  7596. defines the search
  7597. arguments used by the kernel tools to find the appropriate
  7598. description within the kernel
  7599. <link linkend='metadata'>Metadata</link>
  7600. with which to build out the sources and configuration.
  7601. </para>
  7602. </glossdef>
  7603. </glossentry>
  7604. <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
  7605. <info>
  7606. LINUX_VERSION[doc] = "The Linux version from kernel.org on which the Linux kernel image being built using the OpenEmbedded build system is based. You define this variable in the kernel recipe."
  7607. </info>
  7608. <glossdef>
  7609. <para role="glossdeffirst">
  7610. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7611. The Linux version from <filename>kernel.org</filename>
  7612. on which the Linux kernel image being built using the
  7613. OpenEmbedded build system is based.
  7614. You define this variable in the kernel recipe.
  7615. For example, the <filename>linux-yocto-3.4.bb</filename>
  7616. kernel recipe found in
  7617. <filename>meta/recipes-kernel/linux</filename>
  7618. defines the variables as follows:
  7619. <literallayout class='monospaced'>
  7620. LINUX_VERSION ?= "3.4.24"
  7621. </literallayout>
  7622. </para>
  7623. <para>
  7624. The <filename>LINUX_VERSION</filename> variable is used to
  7625. define <link linkend='var-PV'><filename>PV</filename></link>
  7626. for the recipe:
  7627. <literallayout class='monospaced'>
  7628. PV = "${LINUX_VERSION}+git${SRCPV}"
  7629. </literallayout>
  7630. </para>
  7631. </glossdef>
  7632. </glossentry>
  7633. <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
  7634. <info>
  7635. LINUX_VERSION_EXTENSION[doc] = "A string extension compiled into the version string of the Linux kernel built with the OpenEmbedded build system. You define this variable in the kernel recipe."
  7636. </info>
  7637. <glossdef>
  7638. <para role="glossdeffirst">
  7639. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7640. A string extension compiled into the version
  7641. string of the Linux kernel built with the OpenEmbedded
  7642. build system.
  7643. You define this variable in the kernel recipe.
  7644. For example, the linux-yocto kernel recipes all define
  7645. the variable as follows:
  7646. <literallayout class='monospaced'>
  7647. LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
  7648. </literallayout>
  7649. </para>
  7650. <para>
  7651. Defining this variable essentially sets the
  7652. Linux kernel configuration item
  7653. <filename>CONFIG_LOCALVERSION</filename>, which is visible
  7654. through the <filename>uname</filename> command.
  7655. Here is an example that shows the extension assuming it
  7656. was set as previously shown:
  7657. <literallayout class='monospaced'>
  7658. $ uname -r
  7659. 3.7.0-rc8-custom
  7660. </literallayout>
  7661. </para>
  7662. </glossdef>
  7663. </glossentry>
  7664. <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
  7665. <info>
  7666. LOG_DIR[doc] = "Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is ${TMPDIR}/log"
  7667. </info>
  7668. <glossdef>
  7669. <para role="glossdeffirst">
  7670. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7671. Specifies the directory to which the OpenEmbedded build
  7672. system writes overall log files.
  7673. The default directory is <filename>${TMPDIR}/log</filename>.
  7674. </para>
  7675. <para>
  7676. For the directory containing logs specific to each task,
  7677. see the <link linkend='var-T'><filename>T</filename></link>
  7678. variable.
  7679. </para>
  7680. </glossdef>
  7681. </glossentry>
  7682. </glossdiv>
  7683. <glossdiv id='var-glossary-m'><title>M</title>
  7684. <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
  7685. <info>
  7686. MACHINE[doc] = "Specifies the target device for which the image is built. You define MACHINE in the conf/local.conf file in the Build Directory."
  7687. </info>
  7688. <glossdef>
  7689. <para role="glossdeffirst">
  7690. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7691. Specifies the target device for which the image is built.
  7692. You define <filename>MACHINE</filename> in the
  7693. <filename>local.conf</filename> file found in the
  7694. <link linkend='build-directory'>Build Directory</link>.
  7695. By default, <filename>MACHINE</filename> is set to
  7696. "qemux86", which is an x86-based architecture machine to
  7697. be emulated using QEMU:
  7698. <literallayout class='monospaced'>
  7699. MACHINE ?= "qemux86"
  7700. </literallayout>
  7701. </para>
  7702. <para>
  7703. The variable corresponds to a machine configuration file of the
  7704. same name, through which machine-specific configurations are set.
  7705. Thus, when <filename>MACHINE</filename> is set to "qemux86" there
  7706. exists the corresponding <filename>qemux86.conf</filename> machine
  7707. configuration file, which can be found in the
  7708. <link linkend='source-directory'>Source Directory</link>
  7709. in <filename>meta/conf/machine</filename>.
  7710. </para>
  7711. <para>
  7712. The list of machines supported by the Yocto Project as
  7713. shipped include the following:
  7714. <literallayout class='monospaced'>
  7715. MACHINE ?= "qemuarm"
  7716. MACHINE ?= "qemuarm64"
  7717. MACHINE ?= "qemumips"
  7718. MACHINE ?= "qemumips64"
  7719. MACHINE ?= "qemuppc"
  7720. MACHINE ?= "qemux86"
  7721. MACHINE ?= "qemux86-64"
  7722. MACHINE ?= "genericx86"
  7723. MACHINE ?= "genericx86-64"
  7724. MACHINE ?= "beaglebone"
  7725. MACHINE ?= "mpc8315e-rdb"
  7726. MACHINE ?= "edgerouter"
  7727. </literallayout>
  7728. The last five are Yocto Project reference hardware boards, which
  7729. are provided in the <filename>meta-yocto-bsp</filename> layer.
  7730. <note>Adding additional Board Support Package (BSP) layers
  7731. to your configuration adds new possible settings for
  7732. <filename>MACHINE</filename>.
  7733. </note>
  7734. </para>
  7735. </glossdef>
  7736. </glossentry>
  7737. <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>
  7738. <info>
  7739. MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."
  7740. </info>
  7741. <glossdef>
  7742. <para role="glossdeffirst">
  7743. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7744. Specifies the name of the machine-specific architecture.
  7745. This variable is set automatically from
  7746. <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
  7747. or
  7748. <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
  7749. You should not hand-edit the
  7750. <filename>MACHINE_ARCH</filename> variable.
  7751. </para>
  7752. </glossdef>
  7753. </glossentry>
  7754. <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
  7755. <info>
  7756. MACHINE_ESSENTIAL_EXTRA_RDEPENDS[doc] = "A list of required machine-specific packages to install as part of the image being built. Because this is a 'machine-essential' variable, the list of packages are essential for the machine to boot."
  7757. </info>
  7758. <glossdef>
  7759. <para role="glossdeffirst">
  7760. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7761. A list of required machine-specific packages to install as part of
  7762. the image being built.
  7763. The build process depends on these packages being present.
  7764. Furthermore, because this is a "machine-essential" variable, the list of
  7765. packages are essential for the machine to boot.
  7766. The impact of this variable affects images based on
  7767. <filename>packagegroup-core-boot</filename>,
  7768. including the <filename>core-image-minimal</filename> image.
  7769. </para>
  7770. <para>
  7771. This variable is similar to the
  7772. <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
  7773. variable with the exception that the image being built has a build
  7774. dependency on the variable's list of packages.
  7775. In other words, the image will not build if a file in this list is not found.
  7776. </para>
  7777. <para>
  7778. As an example, suppose the machine for which you are building requires
  7779. <filename>example-init</filename> to be run during boot to initialize the hardware.
  7780. In this case, you would use the following in the machine's
  7781. <filename>.conf</filename> configuration file:
  7782. <literallayout class='monospaced'>
  7783. MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
  7784. </literallayout>
  7785. </para>
  7786. </glossdef>
  7787. </glossentry>
  7788. <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
  7789. <info>
  7790. MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS[doc] = "A list of recommended machine-specific packages to install as part of the image being built. Because this is a 'machine-essential' variable, the list of packages are essential for the machine to boot."
  7791. </info>
  7792. <glossdef>
  7793. <para role="glossdeffirst">
  7794. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7795. A list of recommended machine-specific packages to install as part of
  7796. the image being built.
  7797. The build process does not depend on these packages being present.
  7798. However, because this is a "machine-essential" variable, the list of
  7799. packages are essential for the machine to boot.
  7800. The impact of this variable affects images based on
  7801. <filename>packagegroup-core-boot</filename>,
  7802. including the <filename>core-image-minimal</filename> image.
  7803. </para>
  7804. <para>
  7805. This variable is similar to the
  7806. <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
  7807. variable with the exception that the image being built does not have a build
  7808. dependency on the variable's list of packages.
  7809. In other words, the image will still build if a package in this list is not found.
  7810. Typically, this variable is used to handle essential kernel modules, whose
  7811. functionality may be selected to be built into the kernel rather than as a module,
  7812. in which case a package will not be produced.
  7813. </para>
  7814. <para>
  7815. Consider an example where you have a custom kernel where a specific touchscreen
  7816. driver is required for the machine to be usable.
  7817. However, the driver can be built as a module or
  7818. into the kernel depending on the kernel configuration.
  7819. If the driver is built as a module, you want it to be installed.
  7820. But, when the driver is built into the kernel, you still want the
  7821. build to succeed.
  7822. This variable sets up a "recommends" relationship so that in the latter case,
  7823. the build will not fail due to the missing package.
  7824. To accomplish this, assuming the package for the module was called
  7825. <filename>kernel-module-ab123</filename>, you would use the
  7826. following in the machine's <filename>.conf</filename> configuration
  7827. file:
  7828. <literallayout class='monospaced'>
  7829. MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
  7830. </literallayout>
  7831. <note>
  7832. In this example, the
  7833. <filename>kernel-module-ab123</filename> recipe
  7834. needs to explicitly set its
  7835. <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
  7836. variable to ensure that BitBake does not use the
  7837. kernel recipe's
  7838. <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
  7839. variable to satisfy the dependency.
  7840. </note>
  7841. </para>
  7842. <para>
  7843. Some examples of these machine essentials are flash, screen, keyboard, mouse,
  7844. or touchscreen drivers (depending on the machine).
  7845. </para>
  7846. </glossdef>
  7847. </glossentry>
  7848. <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
  7849. <info>
  7850. MACHINE_EXTRA_RDEPENDS[doc] = "A list of machine-specific packages to install as part of the image being built that are not essential for the machine to boot. However, the build process for more fully-featured images depends on the packages being present."
  7851. </info>
  7852. <glossdef>
  7853. <para role="glossdeffirst">
  7854. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7855. A list of machine-specific packages to install as part of the
  7856. image being built that are not essential for the machine to boot.
  7857. However, the build process for more fully-featured images
  7858. depends on the packages being present.
  7859. </para>
  7860. <para>
  7861. This variable affects all images based on
  7862. <filename>packagegroup-base</filename>, which does not include the
  7863. <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
  7864. images.
  7865. </para>
  7866. <para>
  7867. The variable is similar to the
  7868. <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
  7869. variable with the exception that the image being built has a build
  7870. dependency on the variable's list of packages.
  7871. In other words, the image will not build if a file in this list is not found.
  7872. </para>
  7873. <para>
  7874. An example is a machine that has WiFi capability but is not
  7875. essential for the machine to boot the image.
  7876. However, if you are building a more fully-featured image, you want to enable
  7877. the WiFi.
  7878. The package containing the firmware for the WiFi hardware is always
  7879. expected to exist, so it is acceptable for the build process to depend upon
  7880. finding the package.
  7881. In this case, assuming the package for the firmware was called
  7882. <filename>wifidriver-firmware</filename>, you would use the following in the
  7883. <filename>.conf</filename> file for the machine:
  7884. <literallayout class='monospaced'>
  7885. MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
  7886. </literallayout>
  7887. </para>
  7888. </glossdef>
  7889. </glossentry>
  7890. <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
  7891. <info>
  7892. MACHINE_EXTRA_RRECOMMENDS[doc] = "A list of machine-specific packages to install as part of the image being built that are not essential for booting the machine. The image being built has no build dependencies on the packages in this list."
  7893. </info>
  7894. <glossdef>
  7895. <para role="glossdeffirst">
  7896. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7897. A list of machine-specific packages to install as part of the
  7898. image being built that are not essential for booting the machine.
  7899. The image being built has no build dependency on this list of packages.
  7900. </para>
  7901. <para>
  7902. This variable affects only images based on
  7903. <filename>packagegroup-base</filename>, which does not include the
  7904. <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
  7905. images.
  7906. </para>
  7907. <para>
  7908. This variable is similar to the
  7909. <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
  7910. variable with the exception that the image being built does not have a build
  7911. dependency on the variable's list of packages.
  7912. In other words, the image will build if a file in this list is not found.
  7913. </para>
  7914. <para>
  7915. An example is a machine that has WiFi capability but is not essential
  7916. For the machine to boot the image.
  7917. However, if you are building a more fully-featured image, you want to enable
  7918. WiFi.
  7919. In this case, the package containing the WiFi kernel module will not be produced
  7920. if the WiFi driver is built into the kernel, in which case you still want the
  7921. build to succeed instead of failing as a result of the package not being found.
  7922. To accomplish this, assuming the package for the module was called
  7923. <filename>kernel-module-examplewifi</filename>, you would use the
  7924. following in the <filename>.conf</filename> file for the machine:
  7925. <literallayout class='monospaced'>
  7926. MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
  7927. </literallayout>
  7928. </para>
  7929. </glossdef>
  7930. </glossentry>
  7931. <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
  7932. <info>
  7933. MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."
  7934. </info>
  7935. <glossdef>
  7936. <para role="glossdeffirst">
  7937. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7938. Specifies the list of hardware features the
  7939. <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
  7940. of supporting.
  7941. For related information on enabling features, see the
  7942. <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
  7943. <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
  7944. and
  7945. <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
  7946. variables.
  7947. </para>
  7948. <para>
  7949. For a list of hardware features supported by the Yocto
  7950. Project as shipped, see the
  7951. "<link linkend='ref-features-machine'>Machine Features</link>"
  7952. section.
  7953. </para>
  7954. </glossdef>
  7955. </glossentry>
  7956. <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
  7957. <info>
  7958. MACHINE_FEATURES_BACKFILL[doc] = "Features to be added to MACHINE_FEATURES if not also present in MACHINE_FEATURES_BACKFILL_CONSIDERED. This variable is set in the meta/conf/bitbake.conf file and is not intended to be user-configurable."
  7959. </info>
  7960. <glossdef>
  7961. <para role="glossdeffirst">
  7962. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7963. Features to be added to
  7964. <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
  7965. if not also present in
  7966. <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
  7967. </para>
  7968. <para>
  7969. This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
  7970. It is not intended to be user-configurable.
  7971. It is best to just reference the variable to see which machine features are
  7972. being backfilled for all machine configurations.
  7973. See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
  7974. more information.
  7975. </para>
  7976. </glossdef>
  7977. </glossentry>
  7978. <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
  7979. <info>
  7980. MACHINE_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from MACHINE_FEATURES_BACKFILL that should not be backfilled (i.e. added to MACHINE_FEATURES) during the build."
  7981. </info>
  7982. <glossdef>
  7983. <para role="glossdeffirst">
  7984. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  7985. Features from
  7986. <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
  7987. that should not be backfilled (i.e. added to
  7988. <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
  7989. during the build.
  7990. See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
  7991. more information.
  7992. </para>
  7993. </glossdef>
  7994. </glossentry>
  7995. <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
  7996. <info>
  7997. MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine."
  7998. </info>
  7999. <glossdef>
  8000. <para role="glossdeffirst">
  8001. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8002. A colon-separated list of overrides that apply to the
  8003. current machine.
  8004. By default, this list includes the value of
  8005. <link linkend='var-MACHINE'><filename>MACHINE</filename></link>.
  8006. </para>
  8007. <para>
  8008. You can extend <filename>MACHINEOVERRIDES</filename>
  8009. to add extra overrides that should apply to a machine.
  8010. For example, all machines emulated in QEMU (e.g.
  8011. <filename>qemuarm</filename>, <filename>qemux86</filename>,
  8012. and so forth) include a file named
  8013. <filename>meta/conf/machine/include/qemu.inc</filename>
  8014. that prepends the following override to
  8015. <filename>MACHINEOVERRIDES</filename>:
  8016. <literallayout class='monospaced'>
  8017. MACHINEOVERRIDES =. "qemuall:"
  8018. </literallayout>
  8019. This override allows variables to be overriden for all
  8020. machines emulated in QEMU, like in the following example
  8021. from the <filename>connman-conf</filename> recipe:
  8022. <literallayout class='monospaced'>
  8023. SRC_URI_append_qemuall = "file://wired.config \
  8024. file://wired-setup \
  8025. "
  8026. </literallayout>
  8027. The underlying mechanism behind
  8028. <filename>MACHINEOVERRIDES</filename> is simply that it is
  8029. included in the default value of
  8030. <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
  8031. </para>
  8032. </glossdef>
  8033. </glossentry>
  8034. <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
  8035. <info>
  8036. MAINTAINER[doc] = "The email address of the distribution maintainer."
  8037. </info>
  8038. <glossdef>
  8039. <para role="glossdeffirst">
  8040. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8041. The email address of the distribution maintainer.
  8042. </para>
  8043. </glossdef>
  8044. </glossentry>
  8045. <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
  8046. <info>
  8047. MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
  8048. </info>
  8049. <glossdef>
  8050. <para role="glossdeffirst">
  8051. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8052. Specifies additional paths from which the OpenEmbedded
  8053. build system gets source code.
  8054. When the build system searches for source code, it first
  8055. tries the local download directory.
  8056. If that location fails, the build system tries locations
  8057. defined by
  8058. <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
  8059. the upstream source, and then locations specified by
  8060. <filename>MIRRORS</filename> in that order.
  8061. </para>
  8062. <para>
  8063. Assuming your distribution
  8064. (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
  8065. is "poky", the default value for
  8066. <filename>MIRRORS</filename> is defined in the
  8067. <filename>conf/distro/poky.conf</filename> file in the
  8068. <filename>meta-poky</filename> Git repository.
  8069. </para>
  8070. </glossdef>
  8071. </glossentry>
  8072. <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
  8073. <info>
  8074. MLPREFIX[doc] = "Specifies a prefix has been added to PN to create a special version of a recipe or package (i.e. a Multilib version)."
  8075. </info>
  8076. <glossdef>
  8077. <para role="glossdeffirst">
  8078. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8079. Specifies a prefix has been added to
  8080. <link linkend='var-PN'><filename>PN</filename></link> to create a special version
  8081. of a recipe or package (i.e. a Multilib version).
  8082. The variable is used in places where the prefix needs to be
  8083. added to or removed from a the name (e.g. the
  8084. <link linkend='var-BPN'><filename>BPN</filename></link> variable).
  8085. <filename>MLPREFIX</filename> gets set when a prefix has been
  8086. added to <filename>PN</filename>.
  8087. <note>
  8088. The "ML" in <filename>MLPREFIX</filename> stands for
  8089. "MultiLib".
  8090. This representation is historical and comes from
  8091. a time when <filename>nativesdk</filename> was a suffix
  8092. rather than a prefix on the recipe name.
  8093. When <filename>nativesdk</filename> was turned into a
  8094. prefix, it made sense to set
  8095. <filename>MLPREFIX</filename> for it as well.
  8096. </note>
  8097. </para>
  8098. <para>
  8099. To help understand when <filename>MLPREFIX</filename>
  8100. might be needed, consider when
  8101. <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
  8102. is used to provide a <filename>nativesdk</filename> version
  8103. of a recipe in addition to the target version.
  8104. If that recipe declares build-time dependencies on tasks in
  8105. other recipes by using
  8106. <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
  8107. then a dependency on "foo" will automatically get rewritten
  8108. to a dependency on "nativesdk-foo".
  8109. However, dependencies like the following will not get
  8110. rewritten automatically:
  8111. <literallayout class='monospaced'>
  8112. do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"
  8113. </literallayout>
  8114. If you want such a dependency to also get transformed,
  8115. you can do the following:
  8116. <literallayout class='monospaced'>
  8117. do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"
  8118. </literallayout>
  8119. </para>
  8120. </glossdef>
  8121. </glossentry>
  8122. <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
  8123. <info>
  8124. module_autoload[doc] = "This variable has been replaced by the KERNEL_MODULE_AUTOLOAD variable. You should replace all occurrences of module_autoload with additions to KERNEL_MODULE_AUTOLOAD."
  8125. </info>
  8126. <glossdef>
  8127. <para role="glossdeffirst">
  8128. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8129. This variable has been replaced by the
  8130. <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
  8131. You should replace all occurrences of
  8132. <filename>module_autoload</filename> with additions to
  8133. <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:
  8134. <literallayout class='monospaced'>
  8135. module_autoload_rfcomm = "rfcomm"
  8136. </literallayout>
  8137. </para>
  8138. <para>
  8139. should now be replaced with:
  8140. <literallayout class='monospaced'>
  8141. KERNEL_MODULE_AUTOLOAD += "rfcomm"
  8142. </literallayout>
  8143. See the
  8144. <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
  8145. variable for more information.
  8146. </para>
  8147. </glossdef>
  8148. </glossentry>
  8149. <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
  8150. <info>
  8151. module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."
  8152. </info>
  8153. <glossdef>
  8154. <para role="glossdeffirst">
  8155. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8156. Specifies
  8157. <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>
  8158. syntax lines for inclusion in the
  8159. <filename>/etc/modprobe.d/modname.conf</filename> file.
  8160. </para>
  8161. <para>
  8162. You can use this variable anywhere that it can be
  8163. recognized by the kernel recipe or out-of-tree kernel
  8164. module recipe (e.g. a machine configuration file, a
  8165. distribution configuration file, an append file for the
  8166. recipe, or the recipe itself).
  8167. If you use this variable, you must also be sure to list
  8168. the module name in the
  8169. <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
  8170. variable.
  8171. </para>
  8172. <para>
  8173. Here is the general syntax:
  8174. <literallayout class='monospaced'>
  8175. module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"
  8176. </literallayout>
  8177. You must use the kernel module name override.
  8178. </para>
  8179. <para>
  8180. Run <filename>man modprobe.d</filename> in the shell to
  8181. find out more information on the exact syntax
  8182. you want to provide with <filename>module_conf</filename>.
  8183. </para>
  8184. <para>
  8185. Including <filename>module_conf</filename> causes the
  8186. OpenEmbedded build system to populate the
  8187. <filename>/etc/modprobe.d/modname.conf</filename>
  8188. file with <filename>modprobe.d</filename> syntax lines.
  8189. Here is an example that adds the options
  8190. <filename>arg1</filename> and <filename>arg2</filename>
  8191. to a module named <filename>mymodule</filename>:
  8192. <literallayout class='monospaced'>
  8193. module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
  8194. </literallayout>
  8195. </para>
  8196. <para>
  8197. For information on how to specify kernel modules to
  8198. auto-load on boot, see the
  8199. <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
  8200. variable.
  8201. </para>
  8202. </glossdef>
  8203. </glossentry>
  8204. <glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm>MODULE_IMAGE_BASE_NAME</glossterm>
  8205. <info>
  8206. MODULE_IMAGE_BASE_NAME[doc] = "The base name of the kernel modules tarball."
  8207. </info>
  8208. <glossdef>
  8209. <para role="glossdeffirst">
  8210. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8211. The base name of the kernel modules tarball.
  8212. This variable is set in the
  8213. <link linkend='ref-classes-kernel'>kernel</link> class
  8214. as follows:
  8215. <literallayout class='monospaced'>
  8216. MODULE_IMAGE_BASE_NAME ?= "modules-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
  8217. </literallayout>
  8218. </para>
  8219. <para>
  8220. See the
  8221. <link linkend='var-PKGE'><filename>PKGE</filename></link>,
  8222. <link linkend='var-PKGV'><filename>PKGV</filename></link>,
  8223. <link linkend='var-PKGR'><filename>PKGR</filename></link>,
  8224. <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
  8225. and
  8226. <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
  8227. variables for additional information.
  8228. </para>
  8229. </glossdef>
  8230. </glossentry>
  8231. <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
  8232. <info>
  8233. MODULE_TARBALL_DEPLOY[doc] = "Controls creation of the modules-*.tgz file. Set this variable to "0" to disable creation of this file, which contains all of the kernel modules resulting from a kernel build."
  8234. </info>
  8235. <glossdef>
  8236. <para role="glossdeffirst">
  8237. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8238. Controls creation of the <filename>modules-*.tgz</filename>
  8239. file.
  8240. Set this variable to "0" to disable creation of this
  8241. file, which contains all of the kernel modules resulting
  8242. from a kernel build.
  8243. </para>
  8244. </glossdef>
  8245. </glossentry>
  8246. <!--
  8247. <glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm>
  8248. <info>
  8249. MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."
  8250. </info>
  8251. <glossdef>
  8252. <para role="glossdeffirst">
  8253. -->
  8254. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8255. <!--
  8256. Serves the same purpose as
  8257. <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
  8258. but for the "HOST" system, in situations that involve a
  8259. "HOST" and a "TARGET" system.
  8260. See the
  8261. <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
  8262. variable for more information.
  8263. </para>
  8264. <para>
  8265. The default value of this variable is:
  8266. <literallayout class='monospaced'>
  8267. ${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}
  8268. </literallayout>
  8269. </para>
  8270. </glossdef>
  8271. </glossentry>
  8272. -->
  8273. <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
  8274. <info>
  8275. MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories."
  8276. </info>
  8277. <glossdef>
  8278. <para role="glossdeffirst">
  8279. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8280. Uniquely identifies the type of the target system for
  8281. which packages are being built.
  8282. This variable allows output for different types of target
  8283. systems to be put into different subdirectories of the same
  8284. output directory.
  8285. </para>
  8286. <para>
  8287. The default value of this variable is:
  8288. <literallayout class='monospaced'>
  8289. ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
  8290. </literallayout>
  8291. Some classes (e.g.
  8292. <link linkend='ref-classes-cross-canadian'><filename>cross-canadian</filename></link>)
  8293. modify the <filename>MULTIMACH_TARGET_SYS</filename> value.
  8294. </para>
  8295. <para>
  8296. See the
  8297. <link linkend='var-STAMP'><filename>STAMP</filename></link>
  8298. variable for an example.
  8299. See the
  8300. <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
  8301. variable for more information.
  8302. </para>
  8303. </glossdef>
  8304. </glossentry>
  8305. </glossdiv>
  8306. <glossdiv id='var-glossary-n'><title>N</title>
  8307. <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
  8308. <info>
  8309. NATIVELSBSTRING[doc] = "A string identifying the host distribution."
  8310. </info>
  8311. <glossdef>
  8312. <para role="glossdeffirst">
  8313. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8314. A string identifying the host distribution.
  8315. Strings consist of the host distributor ID
  8316. followed by the release, as reported by the
  8317. <filename>lsb_release</filename> tool
  8318. or as read from <filename>/etc/lsb-release</filename>.
  8319. For example, when running a build on Ubuntu 12.10, the value
  8320. is "Ubuntu-12.10".
  8321. If this information is unable to be determined, the value
  8322. resolves to "Unknown".
  8323. </para>
  8324. <para>
  8325. This variable is used by default to isolate native shared
  8326. state packages for different distributions (e.g. to avoid
  8327. problems with <filename>glibc</filename> version
  8328. incompatibilities).
  8329. Additionally, the variable is checked against
  8330. <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
  8331. if that variable is set.
  8332. </para>
  8333. </glossdef>
  8334. </glossentry>
  8335. <glossentry id='var-NM'><glossterm>NM</glossterm>
  8336. <info>
  8337. NM[doc] = "Minimal command and arguments to run 'nm'."
  8338. </info>
  8339. <glossdef>
  8340. <para role="glossdeffirst">
  8341. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8342. The minimal command and arguments to run
  8343. <filename>nm</filename>.
  8344. </para>
  8345. </glossdef>
  8346. </glossentry>
  8347. <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
  8348. <info>
  8349. NO_RECOMMENDATIONS[doc] = "When set to '1', no recommended packages will be installed. Some recommended packages might be required for certain system functionality, such as kernel-modules. It is up to the user to add packages to IMAGE_INSTALL as needed."
  8350. </info>
  8351. <glossdef>
  8352. <para role="glossdeffirst">
  8353. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8354. Prevents installation of all "recommended-only" packages.
  8355. Recommended-only packages are packages installed only
  8356. through the
  8357. <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
  8358. variable).
  8359. Setting the <filename>NO_RECOMMENDATIONS</filename> variable
  8360. to "1" turns this feature on:
  8361. <literallayout class='monospaced'>
  8362. NO_RECOMMENDATIONS = "1"
  8363. </literallayout>
  8364. </para>
  8365. <para>
  8366. You can set this variable globally in your
  8367. <filename>local.conf</filename> file or you can attach it to
  8368. a specific image recipe by using the recipe name override:
  8369. <literallayout class='monospaced'>
  8370. NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1"
  8371. </literallayout>
  8372. </para>
  8373. <para>
  8374. It is important to realize that if you choose to not install
  8375. packages using this variable and some other packages are
  8376. dependent on them (i.e. listed in a recipe's
  8377. <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
  8378. variable), the OpenEmbedded build system ignores your
  8379. request and will install the packages to avoid dependency
  8380. errors.
  8381. <note>
  8382. Some recommended packages might be required for certain
  8383. system functionality, such as kernel modules.
  8384. It is up to you to add packages with the
  8385. <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
  8386. variable.
  8387. </note>
  8388. </para>
  8389. <para>
  8390. Support for this variable exists only when using the
  8391. IPK and RPM packaging backend.
  8392. Support does not exist for DEB.
  8393. </para>
  8394. <para>
  8395. See the
  8396. <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
  8397. and the
  8398. <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
  8399. variables for related information.
  8400. </para>
  8401. </glossdef>
  8402. </glossentry>
  8403. <glossentry id='var-NOAUTOPACKAGEDEBUG'><glossterm>NOAUTOPACKAGEDEBUG</glossterm>
  8404. <info>
  8405. NOAUTOPACKAGEDEBUG[doc] = "Disables auto package from splitting .debug files."
  8406. </info>
  8407. <glossdef>
  8408. <para role="glossdeffirst">
  8409. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8410. Disables auto package from splitting
  8411. <filename>.debug</filename> files. If a recipe requires
  8412. <filename>FILES_${PN}-dbg</filename> to be set manually,
  8413. the <filename>NOAUTOPACKAGEDEBUG</filename> can be defined
  8414. allowing you to define the content of the debug package.
  8415. For example:
  8416. <literallayout class='monospaced'>
  8417. NOAUTOPACKAGEDEBUG = "1"
  8418. FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
  8419. FILES_${PN}-dbg = "/usr/src/debug/"
  8420. FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
  8421. </literallayout>
  8422. </para>
  8423. </glossdef>
  8424. </glossentry>
  8425. <glossentry id='var-NOHDD'><glossterm>NOHDD</glossterm>
  8426. <info>
  8427. NOHDD[doc] = "Causes the OpenEmbedded build system to skip building the .hddimg image."
  8428. </info>
  8429. <glossdef>
  8430. <para role="glossdeffirst">
  8431. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8432. Causes the OpenEmbedded build system to skip building the
  8433. <filename>.hddimg</filename> image.
  8434. The <filename>NOHDD</filename> variable is used with the
  8435. <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
  8436. class.
  8437. Set the variable to "1" to prevent the
  8438. <filename>.hddimg</filename> image from being built.
  8439. </para>
  8440. </glossdef>
  8441. </glossentry>
  8442. <glossentry id='var-NOISO'><glossterm>NOISO</glossterm>
  8443. <info>
  8444. NOISO[doc] = "Causes the OpenEmbedded build system to skip building the ISO image."
  8445. </info>
  8446. <glossdef>
  8447. <para role="glossdeffirst">
  8448. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8449. Causes the OpenEmbedded build system to skip building the
  8450. ISO image.
  8451. The <filename>NOISO</filename> variable is used with the
  8452. <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
  8453. class.
  8454. Set the variable to "1" to prevent the ISO image from
  8455. being built.
  8456. To enable building an ISO image, set the variable to "0".
  8457. </para>
  8458. </glossdef>
  8459. </glossentry>
  8460. </glossdiv>
  8461. <glossdiv id='var-glossary-o'><title>O</title>
  8462. <glossentry id='var-OBJCOPY'><glossterm>OBJCOPY</glossterm>
  8463. <info>
  8464. OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."
  8465. </info>
  8466. <glossdef>
  8467. <para role="glossdeffirst">
  8468. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8469. The minimal command and arguments to run
  8470. <filename>objcopy</filename>.
  8471. </para>
  8472. </glossdef>
  8473. </glossentry>
  8474. <glossentry id='var-OBJDUMP'><glossterm>OBJDUMP</glossterm>
  8475. <info>
  8476. OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."
  8477. </info>
  8478. <glossdef>
  8479. <para role="glossdeffirst">
  8480. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8481. The minimal command and arguments to run
  8482. <filename>objdump</filename>.
  8483. </para>
  8484. </glossdef>
  8485. </glossentry>
  8486. <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
  8487. <info>
  8488. OE_BINCONFIG_EXTRA_MANGLE[doc] = "When a recipe inherits the binconfig.bbclass class, this variable specifies additional arguments passed to the "sed" command."
  8489. </info>
  8490. <glossdef>
  8491. <para role="glossdeffirst">
  8492. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8493. When inheriting the
  8494. <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
  8495. class, this variable
  8496. specifies additional arguments passed to the "sed" command.
  8497. The sed command alters any paths in configuration scripts
  8498. that have been set up during compilation.
  8499. Inheriting this class results in all paths in these scripts
  8500. being changed to point into the
  8501. <filename>sysroots/</filename> directory so that all builds
  8502. that use the script will use the correct directories
  8503. for the cross compiling layout.
  8504. </para>
  8505. <para>
  8506. See the <filename>meta/classes/binconfig.bbclass</filename>
  8507. in the
  8508. <link linkend='source-directory'>Source Directory</link>
  8509. for details on how this class applies these additional
  8510. sed command arguments.
  8511. For general information on the
  8512. <filename>binconfig.bbclass</filename> class, see the
  8513. "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
  8514. section.
  8515. </para>
  8516. </glossdef>
  8517. </glossentry>
  8518. <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
  8519. <info>
  8520. OE_IMPORTS[doc] = "An internal variable used to tell the OpenEmbedded build system what Python modules to import for every Python function run by the system."
  8521. </info>
  8522. <glossdef>
  8523. <para role="glossdeffirst">
  8524. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8525. An internal variable used to tell the OpenEmbedded build
  8526. system what Python modules to import for every Python
  8527. function run by the system.
  8528. </para>
  8529. <note>
  8530. Do not set this variable.
  8531. It is for internal use only.
  8532. </note>
  8533. </glossdef>
  8534. </glossentry>
  8535. <glossentry id='var-OE_INIT_ENV_SCRIPT'><glossterm>OE_INIT_ENV_SCRIPT</glossterm>
  8536. <info>
  8537. OE_INIT_ENV_SCRIPT[doc] = "The name of the build environment setup script for the purposes of setting up the environment within the extensible SDK."
  8538. </info>
  8539. <glossdef>
  8540. <para role="glossdeffirst">
  8541. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8542. The name of the build environment setup script for the
  8543. purposes of setting up the environment within the
  8544. extensible SDK.
  8545. The default value is "oe-init-build-env".
  8546. </para>
  8547. <para>
  8548. If you use a custom script to set up your build
  8549. environment, set the
  8550. <filename>OE_INIT_ENV_SCRIPT</filename> variable to its
  8551. name.
  8552. </para>
  8553. </glossdef>
  8554. </glossentry>
  8555. <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
  8556. <info>
  8557. OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."
  8558. </info>
  8559. <glossdef>
  8560. <para role="glossdeffirst">
  8561. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8562. Controls how the OpenEmbedded build system spawns
  8563. interactive terminals on the host development system
  8564. (e.g. using the BitBake command with the
  8565. <filename>-c devshell</filename> command-line option).
  8566. For more information, see the
  8567. "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
  8568. in the Yocto Project Development Tasks Manual.
  8569. </para>
  8570. <para>
  8571. You can use the following values for the
  8572. <filename>OE_TERMINAL</filename> variable:
  8573. <literallayout class='monospaced'>
  8574. auto
  8575. gnome
  8576. xfce
  8577. rxvt
  8578. screen
  8579. konsole
  8580. none
  8581. </literallayout>
  8582. </para>
  8583. </glossdef>
  8584. </glossentry>
  8585. <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
  8586. <info>
  8587. OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."
  8588. </info>
  8589. <glossdef>
  8590. <para role="glossdeffirst">
  8591. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8592. The directory from which the top-level build environment
  8593. setup script is sourced.
  8594. The Yocto Project provides a top-level build environment
  8595. setup script:
  8596. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
  8597. When you run this script, the
  8598. <filename>OEROOT</filename> variable resolves to the
  8599. directory that contains the script.
  8600. </para>
  8601. <para>
  8602. For additional information on how this variable is used,
  8603. see the initialization script.
  8604. </para>
  8605. </glossdef>
  8606. </glossentry>
  8607. <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
  8608. <info>
  8609. OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."
  8610. </info>
  8611. <glossdef>
  8612. <para role="glossdeffirst">
  8613. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8614. Declares the oldest version of the Linux kernel that the
  8615. produced binaries must support.
  8616. This variable is passed into the build of the Embedded
  8617. GNU C Library (<filename>glibc</filename>).
  8618. </para>
  8619. <para>
  8620. The default for this variable comes from the
  8621. <filename>meta/conf/bitbake.conf</filename> configuration
  8622. file.
  8623. You can override this default by setting the variable
  8624. in a custom distribution configuration file.
  8625. </para>
  8626. </glossdef>
  8627. </glossentry>
  8628. <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
  8629. <info>
  8630. OVERRIDES[doc] = "A colon-separated list of overrides that currently apply."
  8631. </info>
  8632. <glossdef>
  8633. <para role="glossdeffirst">
  8634. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8635. A colon-separated list of overrides that currently apply.
  8636. Overrides are a BitBake mechanism that allows variables to
  8637. be selectively overridden at the end of parsing.
  8638. The set of overrides in <filename>OVERRIDES</filename>
  8639. represents the "state" during building, which includes
  8640. the current recipe being built, the machine for which
  8641. it is being built, and so forth.
  8642. </para>
  8643. <para>
  8644. As an example, if the string "an-override" appears as an
  8645. element in the colon-separated list in
  8646. <filename>OVERRIDES</filename>, then the following
  8647. assignment will override <filename>FOO</filename> with the
  8648. value "overridden" at the end of parsing:
  8649. <literallayout class='monospaced'>
  8650. FOO_an-override = "overridden"
  8651. </literallayout>
  8652. See the
  8653. "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
  8654. section in the BitBake User Manual for more information on
  8655. the overrides mechanism.
  8656. </para>
  8657. <para>
  8658. The default value of <filename>OVERRIDES</filename>
  8659. includes the values of the
  8660. <link linkend='var-CLASSOVERRIDE'><filename>CLASSOVERRIDE</filename></link>,
  8661. <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>,
  8662. and
  8663. <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
  8664. variables.
  8665. Another important override included by default is
  8666. <filename>pn-${PN}</filename>.
  8667. This override allows variables to be set for a single
  8668. recipe within configuration (<filename>.conf</filename>)
  8669. files.
  8670. Here is an example:
  8671. <literallayout class='monospaced'>
  8672. FOO_pn-myrecipe = "myrecipe-specific value"
  8673. </literallayout>
  8674. <note><title>Tip</title>
  8675. An easy way to see what overrides apply is to search for
  8676. <filename>OVERRIDES</filename> in the output of the
  8677. <filename>bitbake -e</filename> command.
  8678. See the
  8679. "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"
  8680. section in the Yocto Project Development Tasks
  8681. Manual for more information.
  8682. </note>
  8683. </para>
  8684. </glossdef>
  8685. </glossentry>
  8686. </glossdiv>
  8687. <glossdiv id='var-glossary-p'><title>P</title>
  8688. <glossentry id='var-P'><glossterm>P</glossterm>
  8689. <info>
  8690. P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}."
  8691. </info>
  8692. <glossdef>
  8693. <para role="glossdeffirst">
  8694. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8695. The recipe name and version.
  8696. <filename>P</filename> is comprised of the following:
  8697. <literallayout class='monospaced'>
  8698. ${PN}-${PV}
  8699. </literallayout>
  8700. </para>
  8701. </glossdef>
  8702. </glossentry>
  8703. <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
  8704. <info>
  8705. PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."
  8706. </info>
  8707. <glossdef>
  8708. <para role="glossdeffirst">
  8709. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8710. The architecture of the resulting package or packages.
  8711. </para>
  8712. <para>
  8713. By default, the value of this variable is set to
  8714. <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
  8715. when building for the target,
  8716. <filename>BUILD_ARCH</filename> when building for the
  8717. build host and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
  8718. for the SDK.
  8719. However, if your recipe's output packages are built
  8720. specific to the target machine rather than general for
  8721. the architecture of the machine, you should set
  8722. <filename>PACKAGE_ARCH</filename> to the value of
  8723. <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>
  8724. in the recipe as follows:
  8725. <literallayout class='monospaced'>
  8726. PACKAGE_ARCH = "${MACHINE_ARCH}"
  8727. </literallayout>
  8728. </para>
  8729. </glossdef>
  8730. </glossentry>
  8731. <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>
  8732. <info>
  8733. PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."
  8734. </info>
  8735. <glossdef>
  8736. <para role="glossdeffirst">
  8737. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8738. Specifies a list of architectures compatible with
  8739. the target machine.
  8740. This variable is set automatically and should not
  8741. normally be hand-edited.
  8742. Entries are separated using spaces and listed in order
  8743. of priority.
  8744. The default value for
  8745. <filename>PACKAGE_ARCHS</filename> is "all any noarch
  8746. ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
  8747. </para>
  8748. </glossdef>
  8749. </glossentry>
  8750. <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
  8751. <info>
  8752. PACKAGE_BEFORE_PN[doc] = "Enables easily adding packages to PACKAGES before ${PN} so that the packages can pick up files that would normally be included in the default package."
  8753. </info>
  8754. <glossdef>
  8755. <para role="glossdeffirst">
  8756. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8757. Enables easily adding packages to
  8758. <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
  8759. before <filename>${<link linkend='var-PN'>PN</link>}</filename>
  8760. so that those added packages can pick up files that would normally be
  8761. included in the default package.
  8762. </para>
  8763. </glossdef>
  8764. </glossentry>
  8765. <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
  8766. <info>
  8767. PACKAGE_CLASSES[doc] = "This variable specifies the package manager to use when packaging data. It is set in the conf/local.conf file in the Build Directory."
  8768. </info>
  8769. <glossdef>
  8770. <para role="glossdeffirst">
  8771. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8772. This variable, which is set in the
  8773. <filename>local.conf</filename> configuration file found in
  8774. the <filename>conf</filename> folder of the
  8775. <link linkend='build-directory'>Build Directory</link>,
  8776. specifies the package manager the OpenEmbedded build system
  8777. uses when packaging data.
  8778. </para>
  8779. <para>
  8780. You can provide one or more of the following arguments for
  8781. the variable:
  8782. <literallayout class='monospaced'>
  8783. PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
  8784. </literallayout>
  8785. <note><title>Warning</title>
  8786. While it is a legal option, the
  8787. <filename>package_tar</filename> class is broken
  8788. and is not supported.
  8789. It is recommended that you do not use it.
  8790. </note>
  8791. The build system uses only the first argument in the list
  8792. as the package manager when creating your image or SDK.
  8793. However, packages will be created using any additional
  8794. packaging classes you specify.
  8795. For example, if you use the following in your
  8796. <filename>local.conf</filename> file:
  8797. <literallayout class='monospaced'>
  8798. PACKAGE_CLASSES ?= "package_ipk"
  8799. </literallayout>
  8800. The OpenEmbedded build system uses the IPK package manager
  8801. to create your image or SDK.
  8802. </para>
  8803. <para>
  8804. For information on packaging and build performance effects
  8805. as a result of the package manager in use, see the
  8806. "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
  8807. section.
  8808. </para>
  8809. </glossdef>
  8810. </glossentry>
  8811. <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>PACKAGE_DEBUG_SPLIT_STYLE</glossterm>
  8812. <info>
  8813. PACKAGE_DEBUG_SPLIT_STYLE[doc] = "Determines how to split up the binary and debug information when creating *-dbg packages to be used with the GNU Project Debugger (GDB)."
  8814. </info>
  8815. <glossdef>
  8816. <para role="glossdeffirst">
  8817. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8818. Determines how to split up the binary and debug information
  8819. when creating <filename>*-dbg</filename> packages to be
  8820. used with the GNU Project Debugger (GDB).
  8821. </para>
  8822. <para>
  8823. With the
  8824. <filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,
  8825. you can control where debug information, which can include
  8826. or exclude source files, is stored:
  8827. <itemizedlist>
  8828. <listitem><para>
  8829. ".debug": Debug symbol files are placed next
  8830. to the binary in a <filename>.debug</filename>
  8831. directory on the target.
  8832. For example, if a binary is installed into
  8833. <filename>/bin</filename>, the corresponding debug
  8834. symbol files are installed in
  8835. <filename>/bin/.debug</filename>.
  8836. Source files are placed in
  8837. <filename>/usr/src/debug</filename>.
  8838. This is the default behavior.
  8839. </para></listitem>
  8840. <listitem><para>
  8841. "debug-file-directory": Debug symbol files are
  8842. placed under <filename>/usr/lib/debug</filename>
  8843. on the target, and separated by the path from where
  8844. the binary is installed.
  8845. For example, if a binary is installed in
  8846. <filename>/bin</filename>, the corresponding debug
  8847. symbols are installed in
  8848. <filename>/usr/lib/debug/bin</filename>.
  8849. Source files are placed in
  8850. <filename>/usr/src/debug</filename>.
  8851. </para></listitem>
  8852. <listitem><para>
  8853. "debug-without-src": The same behavior as
  8854. ".debug" previously described with the exception
  8855. that no source files are installed.
  8856. </para></listitem>.
  8857. </itemizedlist>
  8858. </para>
  8859. <para>
  8860. You can find out more about debugging using GDB by reading
  8861. the
  8862. "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
  8863. section in the Yocto Project Development Tasks Manual.
  8864. </para>
  8865. </glossdef>
  8866. </glossentry>
  8867. <glossentry id='var-PACKAGE_EXCLUDE_COMPLEMENTARY'><glossterm>PACKAGE_EXCLUDE_COMPLEMENTARY</glossterm>
  8868. <info>
  8869. PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."
  8870. </info>
  8871. <glossdef>
  8872. <para role="glossdeffirst">
  8873. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8874. Prevents specific packages from being installed when
  8875. you are installing complementary packages.
  8876. </para>
  8877. <para>
  8878. You might find that you want to prevent installing certain
  8879. packages when you are installing complementary packages.
  8880. For example, if you are using
  8881. <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
  8882. to install <filename>dev-pkgs</filename>, you might not want
  8883. to install all packages from a particular multilib.
  8884. If you find yourself in this situation, you can use the
  8885. <filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable
  8886. to specify regular expressions to match the packages you
  8887. want to exclude.
  8888. </para>
  8889. </glossdef>
  8890. </glossentry>
  8891. <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
  8892. <info>
  8893. PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."
  8894. </info>
  8895. <glossdef>
  8896. <para role="glossdeffirst">
  8897. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8898. Lists packages that should not be installed into an image.
  8899. For example:
  8900. <literallayout class='monospaced'>
  8901. PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
  8902. </literallayout>
  8903. </para>
  8904. <para>
  8905. You can set this variable globally in your
  8906. <filename>local.conf</filename> file or you can attach it to
  8907. a specific image recipe by using the recipe name override:
  8908. <literallayout class='monospaced'>
  8909. PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
  8910. </literallayout>
  8911. </para>
  8912. <para>
  8913. If you choose to not install
  8914. a package using this variable and some other package is
  8915. dependent on it (i.e. listed in a recipe's
  8916. <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
  8917. variable), the OpenEmbedded build system generates a fatal
  8918. installation error.
  8919. Because the build system halts the process with a fatal
  8920. error, you can use the variable with an iterative
  8921. development process to remove specific components from a
  8922. system.
  8923. </para>
  8924. <para>
  8925. Support for this variable exists only when using the
  8926. IPK and RPM packaging backend.
  8927. Support does not exist for DEB.
  8928. </para>
  8929. <para>
  8930. See the
  8931. <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
  8932. and the
  8933. <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
  8934. variables for related information.
  8935. </para>
  8936. </glossdef>
  8937. </glossentry>
  8938. <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
  8939. <info>
  8940. PACKAGE_EXTRA_ARCHS[doc] = "Specifies the list of architectures compatible with the device CPU. This variable is useful when you build for several different devices that use miscellaneous processors."
  8941. </info>
  8942. <glossdef>
  8943. <para role="glossdeffirst">
  8944. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8945. Specifies the list of architectures compatible with the device CPU.
  8946. This variable is useful when you build for several different devices that use
  8947. miscellaneous processors such as XScale and ARM926-EJS.
  8948. </para>
  8949. </glossdef>
  8950. </glossentry>
  8951. <glossentry id='var-PACKAGE_FEED_ARCHS'><glossterm>PACKAGE_FEED_ARCHS</glossterm>
  8952. <info>
  8953. PACKAGE_FEED_ARCHS[doc] = "Optionally specifies user-defined package architectures when constructing package feed URIs."
  8954. </info>
  8955. <glossdef>
  8956. <para role="glossdeffirst">
  8957. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  8958. Optionally specifies the package architectures used as
  8959. part of the package feed URIs during the build.
  8960. When used, the <filename>PACKAGE_FEED_ARCHS</filename>
  8961. variable is appended to the final package feed URI, which
  8962. is constructed using the
  8963. <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
  8964. and
  8965. <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>
  8966. variables.
  8967. <note><title>Tip</title>
  8968. You can use the <filename>PACKAGE_FEEDS_ARCHS</filename>
  8969. variable to whitelist specific package architectures.
  8970. If you do not need to whitelist specific architectures,
  8971. which is a common case, you can omit this variable.
  8972. Omitting the variable results in all available
  8973. architectures for the current machine being included
  8974. into remote package feeds.
  8975. </note>
  8976. </para>
  8977. <para>
  8978. Consider the following example where the
  8979. <filename>PACKAGE_FEED_URIS</filename>,
  8980. <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
  8981. <filename>PACKAGE_FEED_ARCHS</filename> variables are
  8982. defined in your <filename>local.conf</filename> file:
  8983. <literallayout class='monospaced'>
  8984. PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
  8985. https://example.com/packagerepos/updates"
  8986. PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
  8987. PACKAGE_FEED_ARCHS = "all core2-64"
  8988. </literallayout>
  8989. Given these settings, the resulting package feeds are
  8990. as follows:
  8991. <literallayout class='monospaced'>
  8992. https://example.com/packagerepos/release/rpm/all
  8993. https://example.com/packagerepos/release/rpm/core2-64
  8994. https://example.com/packagerepos/release/rpm-dev/all
  8995. https://example.com/packagerepos/release/rpm-dev/core2-64
  8996. https://example.com/packagerepos/updates/rpm/all
  8997. https://example.com/packagerepos/updates/rpm/core2-64
  8998. https://example.com/packagerepos/updates/rpm-dev/all
  8999. https://example.com/packagerepos/updates/rpm-dev/core2-64
  9000. </literallayout>
  9001. </para>
  9002. </glossdef>
  9003. </glossentry>
  9004. <glossentry id='var-PACKAGE_FEED_BASE_PATHS'><glossterm>PACKAGE_FEED_BASE_PATHS</glossterm>
  9005. <info>
  9006. PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."
  9007. </info>
  9008. <glossdef>
  9009. <para role="glossdeffirst">
  9010. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9011. Specifies the base path used when constructing package feed
  9012. URIs.
  9013. The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable
  9014. makes up the middle portion of a package feed URI used
  9015. by the OpenEmbedded build system.
  9016. The base path lies between the
  9017. <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
  9018. and
  9019. <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
  9020. variables.
  9021. </para>
  9022. <para>
  9023. Consider the following example where the
  9024. <filename>PACKAGE_FEED_URIS</filename>,
  9025. <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
  9026. <filename>PACKAGE_FEED_ARCHS</filename> variables are
  9027. defined in your <filename>local.conf</filename> file:
  9028. <literallayout class='monospaced'>
  9029. PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
  9030. https://example.com/packagerepos/updates"
  9031. PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
  9032. PACKAGE_FEED_ARCHS = "all core2-64"
  9033. </literallayout>
  9034. Given these settings, the resulting package feeds are
  9035. as follows:
  9036. <literallayout class='monospaced'>
  9037. https://example.com/packagerepos/release/rpm/all
  9038. https://example.com/packagerepos/release/rpm/core2-64
  9039. https://example.com/packagerepos/release/rpm-dev/all
  9040. https://example.com/packagerepos/release/rpm-dev/core2-64
  9041. https://example.com/packagerepos/updates/rpm/all
  9042. https://example.com/packagerepos/updates/rpm/core2-64
  9043. https://example.com/packagerepos/updates/rpm-dev/all
  9044. https://example.com/packagerepos/updates/rpm-dev/core2-64
  9045. </literallayout>
  9046. </para>
  9047. </glossdef>
  9048. </glossentry>
  9049. <glossentry id='var-PACKAGE_FEED_URIS'><glossterm>PACKAGE_FEED_URIS</glossterm>
  9050. <info>
  9051. PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."
  9052. </info>
  9053. <glossdef>
  9054. <para role="glossdeffirst">
  9055. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9056. Specifies the front portion of the package feed URI
  9057. used by the OpenEmbedded build system.
  9058. Each final package feed URI is comprised of
  9059. <filename>PACKAGE_FEED_URIS</filename>,
  9060. <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>,
  9061. and
  9062. <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
  9063. variables.
  9064. </para>
  9065. <para>
  9066. Consider the following example where the
  9067. <filename>PACKAGE_FEED_URIS</filename>,
  9068. <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
  9069. <filename>PACKAGE_FEED_ARCHS</filename> variables are
  9070. defined in your <filename>local.conf</filename> file:
  9071. <literallayout class='monospaced'>
  9072. PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
  9073. https://example.com/packagerepos/updates"
  9074. PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
  9075. PACKAGE_FEED_ARCHS = "all core2-64"
  9076. </literallayout>
  9077. Given these settings, the resulting package feeds are
  9078. as follows:
  9079. <literallayout class='monospaced'>
  9080. https://example.com/packagerepos/release/rpm/all
  9081. https://example.com/packagerepos/release/rpm/core2-64
  9082. https://example.com/packagerepos/release/rpm-dev/all
  9083. https://example.com/packagerepos/release/rpm-dev/core2-64
  9084. https://example.com/packagerepos/updates/rpm/all
  9085. https://example.com/packagerepos/updates/rpm/core2-64
  9086. https://example.com/packagerepos/updates/rpm-dev/all
  9087. https://example.com/packagerepos/updates/rpm-dev/core2-64
  9088. </literallayout>
  9089. </para>
  9090. </glossdef>
  9091. </glossentry>
  9092. <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
  9093. <info>
  9094. PACKAGE_GROUP[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES."
  9095. </info>
  9096. <glossdef>
  9097. <para role="glossdeffirst">
  9098. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9099. The <filename>PACKAGE_GROUP</filename> variable has been
  9100. renamed to
  9101. <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>.
  9102. See the variable description for
  9103. <filename>FEATURE_PACKAGES</filename> for information.
  9104. </para>
  9105. <para>
  9106. If if you use the <filename>PACKAGE_GROUP</filename>
  9107. variable, the OpenEmbedded build system issues a warning
  9108. message.
  9109. </para>
  9110. </glossdef>
  9111. </glossentry>
  9112. <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
  9113. <info>
  9114. PACKAGE_INSTALL[doc] = "List of the packages to be installed into the image. The variable is generally not user-defined and uses IMAGE_INSTALL as part of the list."
  9115. </info>
  9116. <glossdef>
  9117. <para role="glossdeffirst">
  9118. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9119. The final list of packages passed to the package manager
  9120. for installation into the image.
  9121. </para>
  9122. <para>
  9123. Because the package manager controls actual installation
  9124. of all packages, the list of packages passed using
  9125. <filename>PACKAGE_INSTALL</filename> is not the final list
  9126. of packages that are actually installed.
  9127. This variable is internal to the image construction
  9128. code.
  9129. Consequently, in general, you should use the
  9130. <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
  9131. variable to specify packages for installation.
  9132. The exception to this is when working with
  9133. the
  9134. <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
  9135. image.
  9136. When working with an initial RAM filesystem (initramfs)
  9137. image, use the <filename>PACKAGE_INSTALL</filename>
  9138. variable.
  9139. For information on creating an initramfs, see the
  9140. "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
  9141. section in the Yocto Project Development Tasks Manual.
  9142. </para>
  9143. </glossdef>
  9144. </glossentry>
  9145. <glossentry id='var-PACKAGE_INSTALL_ATTEMPTONLY'><glossterm>PACKAGE_INSTALL_ATTEMPTONLY</glossterm>
  9146. <info>
  9147. PACKAGE_INSTALL_ATTEMPTONLY[doc] = "List of packages attempted to be installed when creating an image. If a listed package fails to install, the build system does not generate an error. This variable is generally not user-defined."
  9148. </info>
  9149. <glossdef>
  9150. <para role="glossdeffirst">
  9151. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9152. Specifies a list of packages the OpenEmbedded build
  9153. system attempts to install when creating an image.
  9154. If a listed package fails to install, the build system
  9155. does not generate an error.
  9156. This variable is generally not user-defined.
  9157. </para>
  9158. </glossdef>
  9159. </glossentry>
  9160. <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>
  9161. <info>
  9162. PACKAGE_PREPROCESS_FUNCS[doc] = "Specifies a list of functions run to pre-process the PKGD directory prior to splitting the files out to individual packages."
  9163. </info>
  9164. <glossdef>
  9165. <para role="glossdeffirst">
  9166. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9167. Specifies a list of functions run to pre-process the
  9168. <link linkend='var-PKGD'><filename>PKGD</filename></link>
  9169. directory prior to splitting the files out to individual
  9170. packages.
  9171. </para>
  9172. </glossdef>
  9173. </glossentry>
  9174. <glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm>
  9175. <info>
  9176. PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools."
  9177. </info>
  9178. <glossdef>
  9179. <para role="glossdeffirst">
  9180. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9181. Specifies a list of dependencies for post-installation and
  9182. pre-installation scripts on native/cross tools.
  9183. If your post-installation or pre-installation script can
  9184. execute at rootfs creation time rather than on the
  9185. target but depends on a native tool in order to execute,
  9186. you need to list the tools in
  9187. <filename>PACKAGE_WRITE_DEPENDS</filename>.
  9188. </para>
  9189. <para>
  9190. For information on running post-installation scripts, see
  9191. the
  9192. "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
  9193. section in the Yocto Project Development Tasks Manual.
  9194. </para>
  9195. </glossdef>
  9196. </glossentry>
  9197. <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
  9198. <info>
  9199. PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."
  9200. </info>
  9201. <glossdef>
  9202. <para role="glossdeffirst">
  9203. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9204. This variable provides a means of enabling or disabling
  9205. features of a recipe on a per-recipe basis.
  9206. <filename>PACKAGECONFIG</filename> blocks are defined
  9207. in recipes when you specify features and then arguments
  9208. that define feature behaviors.
  9209. Here is the basic block structure:
  9210. <literallayout class='monospaced'>
  9211. PACKAGECONFIG ??= "f1 f2 f3 ..."
  9212. PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"
  9213. PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"
  9214. PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"
  9215. </literallayout>
  9216. </para>
  9217. <para>
  9218. The <filename>PACKAGECONFIG</filename>
  9219. variable itself specifies a space-separated list of the
  9220. features to enable.
  9221. Following the features, you can determine the behavior of
  9222. each feature by providing up to four order-dependent
  9223. arguments, which are separated by commas.
  9224. You can omit any argument you like but must retain the
  9225. separating commas.
  9226. The order is important and specifies the following:
  9227. <orderedlist>
  9228. <listitem><para>Extra arguments
  9229. that should be added to the configure script
  9230. argument list
  9231. (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
  9232. or
  9233. <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>)
  9234. if the feature is enabled.</para></listitem>
  9235. <listitem><para>Extra arguments
  9236. that should be added to <filename>EXTRA_OECONF</filename>
  9237. or <filename>PACKAGECONFIG_CONFARGS</filename>
  9238. if the feature is disabled.
  9239. </para></listitem>
  9240. <listitem><para>Additional build dependencies
  9241. (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
  9242. that should be added if the feature is enabled.
  9243. </para></listitem>
  9244. <listitem><para>Additional runtime dependencies
  9245. (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
  9246. that should be added if the feature is enabled.
  9247. </para></listitem>
  9248. </orderedlist>
  9249. </para>
  9250. <para>
  9251. Consider the following
  9252. <filename>PACKAGECONFIG</filename> block taken from the
  9253. <filename>librsvg</filename> recipe.
  9254. In this example the feature is <filename>croco</filename>,
  9255. which has three arguments that determine the feature's
  9256. behavior.
  9257. <literallayout class='monospaced'>
  9258. PACKAGECONFIG ??= "croco"
  9259. PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
  9260. </literallayout>
  9261. The <filename>--with-croco</filename> and
  9262. <filename>libcroco</filename> arguments apply only if
  9263. the feature is enabled.
  9264. In this case, <filename>--with-croco</filename> is
  9265. added to the configure script argument list and
  9266. <filename>libcroco</filename> is added to
  9267. <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
  9268. On the other hand, if the feature is disabled say through
  9269. a <filename>.bbappend</filename> file in another layer, then
  9270. the second argument <filename>--without-croco</filename> is
  9271. added to the configure script rather than
  9272. <filename>--with-croco</filename>.
  9273. </para>
  9274. <para>
  9275. The basic <filename>PACKAGECONFIG</filename> structure
  9276. previously described holds true regardless of whether you
  9277. are creating a block or changing a block.
  9278. When creating a block, use the structure inside your
  9279. recipe.
  9280. </para>
  9281. <para>
  9282. If you want to change an existing
  9283. <filename>PACKAGECONFIG</filename> block, you can do so
  9284. one of two ways:
  9285. <itemizedlist>
  9286. <listitem><para><emphasis>Append file:</emphasis>
  9287. Create an append file named
  9288. <replaceable>recipename</replaceable><filename>.bbappend</filename>
  9289. in your layer and override the value of
  9290. <filename>PACKAGECONFIG</filename>.
  9291. You can either completely override the variable:
  9292. <literallayout class='monospaced'>
  9293. PACKAGECONFIG="f4 f5"
  9294. </literallayout>
  9295. Or, you can just append the variable:
  9296. <literallayout class='monospaced'>
  9297. PACKAGECONFIG_append = " f4"
  9298. </literallayout></para></listitem>
  9299. <listitem><para><emphasis>Configuration file:</emphasis>
  9300. This method is identical to changing the block
  9301. through an append file except you edit your
  9302. <filename>local.conf</filename> or
  9303. <filename><replaceable>mydistro</replaceable>.conf</filename> file.
  9304. As with append files previously described,
  9305. you can either completely override the variable:
  9306. <literallayout class='monospaced'>
  9307. PACKAGECONFIG_pn-<replaceable>recipename</replaceable>="f4 f5"
  9308. </literallayout>
  9309. Or, you can just amend the variable:
  9310. <literallayout class='monospaced'>
  9311. PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"
  9312. </literallayout></para></listitem>
  9313. </itemizedlist>
  9314. </para>
  9315. </glossdef>
  9316. </glossentry>
  9317. <glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm>
  9318. <info>
  9319. PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from the PACKAGECONFIG setting."
  9320. </info>
  9321. <glossdef>
  9322. <para role="glossdeffirst">
  9323. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9324. A space-separated list of configuration options generated
  9325. from the
  9326. <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
  9327. setting.
  9328. </para>
  9329. <para>
  9330. Classes such as
  9331. <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
  9332. and
  9333. <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
  9334. use <filename>PACKAGECONFIG_CONFARGS</filename> to pass
  9335. <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
  9336. options to <filename>configure</filename> and
  9337. <filename>cmake</filename>, respectively.
  9338. If you are using
  9339. <filename>PACKAGECONFIG</filename> but not a class that
  9340. handles the <filename>do_configure</filename> task, then
  9341. you need to use
  9342. <filename>PACKAGECONFIG_CONFARGS</filename> appropriately.
  9343. </para>
  9344. <para>
  9345. For additional information, see the
  9346. <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
  9347. variable.
  9348. </para>
  9349. </glossdef>
  9350. </glossentry>
  9351. <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm>
  9352. <info>
  9353. PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."
  9354. </info>
  9355. <glossdef>
  9356. <para role="glossdeffirst">
  9357. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9358. For recipes inheriting the
  9359. <link linkend='ref-classes-packagegroup'><filename>packagegroup</filename></link>
  9360. class, setting
  9361. <filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to
  9362. "1" specifies that the normal complementary packages
  9363. (i.e. <filename>-dev</filename>,
  9364. <filename>-dbg</filename>, and so forth) should not be
  9365. automatically created by the
  9366. <filename>packagegroup</filename> recipe, which is the
  9367. default behavior.
  9368. </para>
  9369. </glossdef>
  9370. </glossentry>
  9371. <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
  9372. <info>
  9373. PACKAGES[doc] = "The list of packages the recipe creates."
  9374. </info>
  9375. <glossdef>
  9376. <para role="glossdeffirst">
  9377. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9378. The list of packages the recipe creates.
  9379. The default value is the following:
  9380. <literallayout class='monospaced'>
  9381. ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
  9382. </literallayout>
  9383. </para>
  9384. <para>
  9385. During packaging, the
  9386. <link linkend='ref-tasks-package'><filename>do_package</filename></link>
  9387. task goes through <filename>PACKAGES</filename> and uses
  9388. the
  9389. <link linkend='var-FILES'><filename>FILES</filename></link>
  9390. variable corresponding to each package to assign files to
  9391. the package.
  9392. If a file matches the <filename>FILES</filename> variable
  9393. for more than one package in <filename>PACKAGES</filename>,
  9394. it will be assigned to the earliest (leftmost) package.
  9395. </para>
  9396. <para>
  9397. Packages in the variable's list that are empty (i.e. where
  9398. none of the patterns in
  9399. <filename>FILES_</filename><replaceable>pkg</replaceable>
  9400. match any files installed by the
  9401. <link linkend='ref-tasks-install'><filename>do_install</filename></link>
  9402. task) are not generated, unless generation is forced through
  9403. the
  9404. <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>
  9405. variable.
  9406. </para>
  9407. </glossdef>
  9408. </glossentry>
  9409. <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
  9410. <info>
  9411. PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."
  9412. </info>
  9413. <glossdef>
  9414. <para role="glossdeffirst">
  9415. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9416. A promise that your recipe satisfies runtime dependencies
  9417. for optional modules that are found in other recipes.
  9418. <filename>PACKAGES_DYNAMIC</filename>
  9419. does not actually satisfy the dependencies, it only states that
  9420. they should be satisfied.
  9421. For example, if a hard, runtime dependency
  9422. (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
  9423. of another package is satisfied
  9424. at build time through the <filename>PACKAGES_DYNAMIC</filename>
  9425. variable, but a package with the module name is never actually
  9426. produced, then the other package will be broken.
  9427. Thus, if you attempt to include that package in an image,
  9428. you will get a dependency failure from the packaging system
  9429. during the
  9430. <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
  9431. task.
  9432. </para>
  9433. <para>
  9434. Typically, if there is a chance that such a situation can
  9435. occur and the package that is not created is valid
  9436. without the dependency being satisfied, then you should use
  9437. <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
  9438. (a soft runtime dependency) instead of
  9439. <filename>RDEPENDS</filename>.
  9440. </para>
  9441. <para>
  9442. For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
  9443. variable when you are splitting packages, see the
  9444. "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
  9445. in the Yocto Project Development Tasks Manual.
  9446. </para>
  9447. </glossdef>
  9448. </glossentry>
  9449. <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>
  9450. <info>
  9451. PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."
  9452. </info>
  9453. <glossdef>
  9454. <para role="glossdeffirst">
  9455. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9456. Specifies a list of functions run to perform additional
  9457. splitting of files into individual packages.
  9458. Recipes can either prepend to this variable or prepend
  9459. to the <filename>populate_packages</filename> function
  9460. in order to perform additional package splitting.
  9461. In either case, the function should set
  9462. <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
  9463. <link linkend='var-FILES'><filename>FILES</filename></link>,
  9464. <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
  9465. and other packaging variables appropriately in order to
  9466. perform the desired splitting.
  9467. </para>
  9468. </glossdef>
  9469. </glossentry>
  9470. <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
  9471. <info>
  9472. PARALLEL_MAKE[doc] = "Specifies extra options that are passed to the make command during the compile tasks. This variable is usually in the form -j x, where x represents the maximum number of parallel threads make can run."
  9473. </info>
  9474. <glossdef>
  9475. <para role="glossdeffirst">
  9476. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9477. Extra options passed to the <filename>make</filename>
  9478. command during the
  9479. <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
  9480. task in order to specify parallel compilation on the local
  9481. build host.
  9482. This variable is usually in the form "-j <replaceable>x</replaceable>",
  9483. where <replaceable>x</replaceable> represents the maximum
  9484. number of parallel threads <filename>make</filename> can
  9485. run.
  9486. <note><title>Caution</title>
  9487. In order for <filename>PARALLEL_MAKE</filename> to be
  9488. effective, <filename>make</filename> must be called
  9489. with
  9490. <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
  9491. An easy way to ensure this is to use the
  9492. <filename>oe_runmake</filename> function.
  9493. </note>
  9494. </para>
  9495. <para>
  9496. By default, the OpenEmbedded build system automatically
  9497. sets this variable to be equal to the number of cores the
  9498. build system uses.
  9499. <note>
  9500. If the software being built experiences dependency
  9501. issues during the <filename>do_compile</filename>
  9502. task that result in race conditions, you can clear
  9503. the <filename>PARALLEL_MAKE</filename> variable within
  9504. the recipe as a workaround.
  9505. For information on addressing race conditions, see the
  9506. "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
  9507. section in the Yocto Project Development Tasks Manual.
  9508. </note>
  9509. For single socket systems (i.e. one CPU), you should not
  9510. have to override this variable to gain optimal parallelism
  9511. during builds.
  9512. However, if you have very large systems that employ
  9513. multiple physical CPUs, you might want to make sure the
  9514. <filename>PARALLEL_MAKE</filename> variable is not
  9515. set higher than "-j 20".
  9516. </para>
  9517. <para>
  9518. For more information on speeding up builds, see the
  9519. "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-the-build'>Speeding Up the Build</ulink>"
  9520. section in the Yocto Project Development Tasks Manual.
  9521. </para>
  9522. </glossdef>
  9523. </glossentry>
  9524. <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
  9525. <info>
  9526. PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."
  9527. </info>
  9528. <glossdef>
  9529. <para role="glossdeffirst">
  9530. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9531. Extra options passed to the
  9532. <filename>make install</filename> command during the
  9533. <link linkend='ref-tasks-install'><filename>do_install</filename></link>
  9534. task in order to specify parallel installation.
  9535. This variable defaults to the value of
  9536. <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
  9537. <note><title>Notes and Cautions</title>
  9538. <para>In order for <filename>PARALLEL_MAKEINST</filename>
  9539. to be
  9540. effective, <filename>make</filename> must be called
  9541. with
  9542. <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
  9543. An easy way to ensure this is to use the
  9544. <filename>oe_runmake</filename> function.</para>
  9545. <para>If the software being built experiences
  9546. dependency issues during the
  9547. <filename>do_install</filename> task that result in
  9548. race conditions, you can clear the
  9549. <filename>PARALLEL_MAKEINST</filename> variable within
  9550. the recipe as a workaround.
  9551. For information on addressing race conditions, see the
  9552. "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
  9553. section in the Yocto Project Development Tasks Manual.
  9554. </para>
  9555. </note>
  9556. </para>
  9557. </glossdef>
  9558. </glossentry>
  9559. <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
  9560. <info>
  9561. PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."
  9562. </info>
  9563. <glossdef>
  9564. <para role="glossdeffirst">
  9565. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9566. Determines the action to take when a patch fails.
  9567. You can set this variable to one of two values: "noop" and
  9568. "user".
  9569. </para>
  9570. <para>
  9571. The default value of "noop" causes the build to simply fail
  9572. when the OpenEmbedded build system cannot successfully
  9573. apply a patch.
  9574. Setting the value to "user" causes the build system to
  9575. launch a shell and places you in the right location so that
  9576. you can manually resolve the conflicts.
  9577. </para>
  9578. <para>
  9579. Set this variable in your
  9580. <filename>local.conf</filename> file.
  9581. </para>
  9582. </glossdef>
  9583. </glossentry>
  9584. <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
  9585. <info>
  9586. PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."
  9587. </info>
  9588. <glossdef>
  9589. <para role="glossdeffirst">
  9590. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9591. Specifies the utility used to apply patches for a recipe
  9592. during the
  9593. <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
  9594. task.
  9595. You can specify one of three utilities: "patch", "quilt", or
  9596. "git".
  9597. The default utility used is "quilt" except for the
  9598. quilt-native recipe itself.
  9599. Because the quilt tool is not available at the
  9600. time quilt-native is being patched, it uses "patch".
  9601. </para>
  9602. <para>
  9603. If you wish to use an alternative patching tool, set the
  9604. variable in the recipe using one of the following:
  9605. <literallayout class='monospaced'>
  9606. PATCHTOOL = "patch"
  9607. PATCHTOOL = "quilt"
  9608. PATCHTOOL = "git"
  9609. </literallayout>
  9610. </para>
  9611. </glossdef>
  9612. </glossentry>
  9613. <glossentry id='var-PE'><glossterm>PE</glossterm>
  9614. <info>
  9615. PE[doc] = "The epoch of the recipe. The default value is '0'. The field is used to make upgrades possible when the versioning scheme changes in some backwards incompatible way."
  9616. </info>
  9617. <glossdef>
  9618. <para role="glossdeffirst">
  9619. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9620. The epoch of the recipe.
  9621. By default, this variable is unset.
  9622. The variable is used to make upgrades possible when the
  9623. versioning scheme changes in some backwards incompatible
  9624. way.
  9625. </para>
  9626. <para>
  9627. <filename>PE</filename> is the default value of the
  9628. <link linkend='var-PKGE'><filename>PKGE</filename></link>
  9629. variable.
  9630. </para>
  9631. </glossdef>
  9632. </glossentry>
  9633. <glossentry id='var-PF'><glossterm>PF</glossterm>
  9634. <info>
  9635. PF[doc] = "Specifies the recipe or package name and includes all version and revision numbers. This variable is comprised of ${PN}-${EXTENDPE}${PV}-${PR}."
  9636. </info>
  9637. <glossdef>
  9638. <para role="glossdeffirst">
  9639. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9640. Specifies the recipe or package name and includes all version and revision
  9641. numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and
  9642. <filename>bash-4.2-r1/</filename>).
  9643. This variable is comprised of the following:
  9644. <literallayout class='monospaced'>
  9645. ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
  9646. </literallayout>
  9647. </para>
  9648. </glossdef>
  9649. </glossentry>
  9650. <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
  9651. <info>
  9652. PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."
  9653. </info>
  9654. <glossdef>
  9655. <para role="glossdeffirst">
  9656. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9657. When inheriting the
  9658. <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
  9659. class, this variable identifies packages that contain
  9660. the pixbuf loaders used with
  9661. <filename>gdk-pixbuf</filename>.
  9662. By default, the <filename>pixbufcache</filename> class
  9663. assumes that the loaders are in the recipe's main package
  9664. (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
  9665. Use this variable if the loaders you need are in a package
  9666. other than that main package.
  9667. </para>
  9668. </glossdef>
  9669. </glossentry>
  9670. <glossentry id='var-PKG'><glossterm>PKG</glossterm>
  9671. <info>
  9672. PKG[doc] = "The name of the resulting package created by the OpenEmbedded build system. When you use this variable, you must use a package name override."
  9673. </info>
  9674. <glossdef>
  9675. <para role="glossdeffirst">
  9676. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9677. The name of the resulting package created by the
  9678. OpenEmbedded build system.
  9679. <note>
  9680. When using the <filename>PKG</filename> variable, you
  9681. must use a package name override.
  9682. </note>
  9683. </para>
  9684. <para>
  9685. For example, when the
  9686. <link linkend='ref-classes-debian'><filename>debian</filename></link>
  9687. class renames the output package, it does so by setting
  9688. <filename>PKG_<replaceable>packagename</replaceable></filename>.
  9689. </para>
  9690. </glossdef>
  9691. </glossentry>
  9692. <glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm>
  9693. <info>
  9694. PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."
  9695. </info>
  9696. <glossdef>
  9697. <para role="glossdeffirst">
  9698. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9699. The path to <filename>pkg-config</filename> files for the
  9700. current build context.
  9701. <filename>pkg-config</filename> reads this variable
  9702. from the environment.
  9703. </para>
  9704. </glossdef>
  9705. </glossentry>
  9706. <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
  9707. <info>
  9708. PKGD[doc] = "Points to the destination directory for files to be packaged before they are split into individual packages."
  9709. </info>
  9710. <glossdef>
  9711. <para role="glossdeffirst">
  9712. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9713. Points to the destination directory for files to be
  9714. packaged before they are split into individual packages.
  9715. This directory defaults to the following:
  9716. <literallayout class='monospaced'>
  9717. ${WORKDIR}/package
  9718. </literallayout>
  9719. </para>
  9720. <para>
  9721. Do not change this default.
  9722. </para>
  9723. </glossdef>
  9724. </glossentry>
  9725. <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
  9726. <info>
  9727. PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."
  9728. </info>
  9729. <glossdef>
  9730. <para role="glossdeffirst">
  9731. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9732. Points to a shared, global-state directory that holds data
  9733. generated during the packaging process.
  9734. During the packaging process, the
  9735. <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
  9736. task packages data for each recipe and installs it into
  9737. this temporary, shared area.
  9738. This directory defaults to the following, which you should
  9739. not change:
  9740. <literallayout class='monospaced'>
  9741. ${STAGING_DIR_HOST}/pkgdata
  9742. </literallayout>
  9743. For examples of how this data is used, see the
  9744. "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
  9745. section in the Yocto Project Overview and Concepts Manual
  9746. and the
  9747. "<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"
  9748. section in the Yocto Project Development Tasks Manual.
  9749. </para>
  9750. </glossdef>
  9751. </glossentry>
  9752. <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
  9753. <info>
  9754. PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."
  9755. </info>
  9756. <glossdef>
  9757. <para role="glossdeffirst">
  9758. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9759. Points to the parent directory for files to be packaged
  9760. after they have been split into individual packages.
  9761. This directory defaults to the following:
  9762. <literallayout class='monospaced'>
  9763. ${WORKDIR}/packages-split
  9764. </literallayout>
  9765. </para>
  9766. <para>
  9767. Under this directory, the build system creates
  9768. directories for each package specified in
  9769. <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
  9770. Do not change this default.
  9771. </para>
  9772. </glossdef>
  9773. </glossentry>
  9774. <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
  9775. <info>
  9776. PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata."
  9777. </info>
  9778. <glossdef>
  9779. <para role="glossdeffirst">
  9780. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9781. Points to a temporary work area where the
  9782. <link linkend='ref-tasks-package'><filename>do_package</filename></link>
  9783. task saves package metadata.
  9784. The <filename>PKGDESTWORK</filename> location defaults to
  9785. the following:
  9786. <literallayout class='monospaced'>
  9787. ${WORKDIR}/pkgdata
  9788. </literallayout>
  9789. Do not change this default.
  9790. </para>
  9791. <para>
  9792. The
  9793. <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
  9794. task copies the package metadata from
  9795. <filename>PKGDESTWORK</filename> to
  9796. <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
  9797. to make it available globally.
  9798. </para>
  9799. </glossdef>
  9800. </glossentry>
  9801. <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
  9802. <info>
  9803. PKGE[doc] = "The epoch of the package(s) built by the recipe."
  9804. </info>
  9805. <glossdef>
  9806. <para role="glossdeffirst">
  9807. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9808. The epoch of the package(s) built by the recipe.
  9809. By default, <filename>PKGE</filename> is set to
  9810. <link linkend='var-PE'><filename>PE</filename></link>.
  9811. </para>
  9812. </glossdef>
  9813. </glossentry>
  9814. <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
  9815. <info>
  9816. PKGR[doc] = "The revision of the package(s) built by the recipe."
  9817. </info>
  9818. <glossdef>
  9819. <para role="glossdeffirst">
  9820. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9821. The revision of the package(s) built by the recipe.
  9822. By default, <filename>PKGR</filename> is set to
  9823. <link linkend='var-PR'><filename>PR</filename></link>.
  9824. </para>
  9825. </glossdef>
  9826. </glossentry>
  9827. <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
  9828. <info>
  9829. PKGV[doc] = "The version of the package(s) built by the recipe."
  9830. </info>
  9831. <glossdef>
  9832. <para role="glossdeffirst">
  9833. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9834. The version of the package(s) built by the
  9835. recipe.
  9836. By default, <filename>PKGV</filename> is set to
  9837. <link linkend='var-PV'><filename>PV</filename></link>.
  9838. </para>
  9839. </glossdef>
  9840. </glossentry>
  9841. <glossentry id='var-PN'><glossterm>PN</glossterm>
  9842. <info>
  9843. PN[doc] = "PN refers to a recipe name in the context of a file used by the OpenEmbedded build system as input to create a package.
  9844. </info>
  9845. <glossdef>
  9846. <para role="glossdeffirst">
  9847. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9848. This variable can have two separate functions depending on the context: a recipe
  9849. name or a resulting package name.
  9850. </para>
  9851. <para>
  9852. <filename>PN</filename> refers to a recipe name in the context of a file used
  9853. by the OpenEmbedded build system as input to create a package.
  9854. The name is normally extracted from the recipe file name.
  9855. For example, if the recipe is named
  9856. <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
  9857. will be "expat".
  9858. </para>
  9859. <para>
  9860. The variable refers to a package name in the context of a file created or produced by the
  9861. OpenEmbedded build system.
  9862. </para>
  9863. <para>
  9864. If applicable, the <filename>PN</filename> variable also contains any special
  9865. suffix or prefix.
  9866. For example, using <filename>bash</filename> to build packages for the native
  9867. machine, <filename>PN</filename> is <filename>bash-native</filename>.
  9868. Using <filename>bash</filename> to build packages for the target and for Multilib,
  9869. <filename>PN</filename> would be <filename>bash</filename> and
  9870. <filename>lib64-bash</filename>, respectively.
  9871. </para>
  9872. </glossdef>
  9873. </glossentry>
  9874. <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
  9875. <info>
  9876. PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."
  9877. </info>
  9878. <glossdef>
  9879. <para role="glossdeffirst">
  9880. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9881. Lists recipes you do not want the OpenEmbedded build system
  9882. to build.
  9883. This variable works in conjunction with the
  9884. <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
  9885. class, which the recipe must inherit globally.
  9886. </para>
  9887. <para>
  9888. To prevent a recipe from being built, inherit the class
  9889. globally and use the variable in your
  9890. <filename>local.conf</filename> file.
  9891. Here is an example that prevents
  9892. <filename>myrecipe</filename> from being built:
  9893. <literallayout class='monospaced'>
  9894. INHERIT += "blacklist"
  9895. PNBLACKLIST[myrecipe] = "Not supported by our organization."
  9896. </literallayout>
  9897. </para>
  9898. </glossdef>
  9899. </glossentry>
  9900. <glossentry id='var-POPULATE_SDK_POST_HOST_COMMAND'><glossterm>POPULATE_SDK_POST_HOST_COMMAND</glossterm>
  9901. <info>
  9902. POPULATE_SDK_POST_HOST_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created host part of the SDK."
  9903. </info>
  9904. <glossdef>
  9905. <para role="glossdeffirst">
  9906. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9907. Specifies a list of functions to call once the
  9908. OpenEmbedded build system has created the host part of
  9909. the SDK.
  9910. You can specify functions separated by semicolons:
  9911. <literallayout class='monospaced'>
  9912. POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "
  9913. </literallayout>
  9914. </para>
  9915. <para>
  9916. If you need to pass the SDK path to a command
  9917. within a function, you can use
  9918. <filename>${SDK_DIR}</filename>, which points to
  9919. the parent directory used by the OpenEmbedded build
  9920. system when creating SDK output.
  9921. See the
  9922. <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
  9923. variable for more information.
  9924. </para>
  9925. </glossdef>
  9926. </glossentry>
  9927. <glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>
  9928. <info>
  9929. POPULATE_SDK_POST_TARGET_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created target part of the SDK."
  9930. </info>
  9931. <glossdef>
  9932. <para role="glossdeffirst">
  9933. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9934. Specifies a list of functions to call once the
  9935. OpenEmbedded build system has created the target part of
  9936. the SDK.
  9937. You can specify functions separated by semicolons:
  9938. <literallayout class='monospaced'>
  9939. POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "
  9940. </literallayout>
  9941. </para>
  9942. <para>
  9943. If you need to pass the SDK path to a command
  9944. within a function, you can use
  9945. <filename>${SDK_DIR}</filename>, which points to
  9946. the parent directory used by the OpenEmbedded build
  9947. system when creating SDK output.
  9948. See the
  9949. <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
  9950. variable for more information.
  9951. </para>
  9952. </glossdef>
  9953. </glossentry>
  9954. <glossentry id='var-PR'><glossterm>PR</glossterm>
  9955. <info>
  9956. PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'."
  9957. </info>
  9958. <glossdef>
  9959. <para role="glossdeffirst">
  9960. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  9961. The revision of the recipe. The default value for this
  9962. variable is "r0".
  9963. Subsequent revisions of the recipe conventionally have the
  9964. values "r1", "r2", and so forth.
  9965. When
  9966. <link linkend='var-PV'><filename>PV</filename></link>
  9967. increases, <filename>PR</filename> is conventionally reset
  9968. to "r0".
  9969. <note>
  9970. The OpenEmbedded build system does not need the aid of
  9971. <filename>PR</filename> to know when to rebuild a
  9972. recipe.
  9973. The build system uses the task
  9974. <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>input checksums</ulink>
  9975. along with the
  9976. <link linkend='structure-build-tmp-stamps'>stamp</link>
  9977. and
  9978. <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state cache</ulink>
  9979. mechanisms.
  9980. </note>
  9981. The <filename>PR</filename> variable primarily becomes
  9982. significant when a package manager dynamically installs
  9983. packages on an already built image.
  9984. In this case, <filename>PR</filename>, which is the default
  9985. value of
  9986. <link linkend='var-PKGR'><filename>PKGR</filename></link>,
  9987. helps the package manager distinguish which package is the
  9988. most recent one in cases where many packages have the same
  9989. <filename>PV</filename> (i.e. <filename>PKGV</filename>).
  9990. A component having many packages with the same
  9991. <filename>PV</filename> usually means that the packages all
  9992. install the same upstream version, but with later
  9993. (<filename>PR</filename>) version packages including
  9994. packaging fixes.
  9995. <note>
  9996. <filename>PR</filename> does not need to be increased
  9997. for changes that do not change the package contents or
  9998. metadata.
  9999. </note>
  10000. Because manually managing <filename>PR</filename> can be
  10001. cumbersome and error-prone, an automated solution exists.
  10002. See the
  10003. "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
  10004. section in the Yocto Project Development Tasks Manual
  10005. for more information.
  10006. </para>
  10007. </glossdef>
  10008. </glossentry>
  10009. <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
  10010. <info>
  10011. PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."
  10012. </info>
  10013. <glossdef>
  10014. <para role="glossdeffirst">
  10015. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10016. If multiple recipes provide the same item, this variable
  10017. determines which recipe is preferred and thus provides
  10018. the item (i.e. the preferred provider).
  10019. You should always suffix this variable with the name of the
  10020. provided item.
  10021. And, you should define the variable using the preferred
  10022. recipe's name
  10023. (<link linkend='var-PN'><filename>PN</filename></link>).
  10024. Here is a common example:
  10025. <literallayout class='monospaced'>
  10026. PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
  10027. </literallayout>
  10028. In the previous example, multiple recipes are providing
  10029. "virtual/kernel".
  10030. The <filename>PREFERRED_PROVIDER</filename> variable is
  10031. set with the name (<filename>PN</filename>) of the recipe
  10032. you prefer to provide "virtual/kernel".
  10033. </para>
  10034. <para>
  10035. Following are more examples:
  10036. <literallayout class='monospaced'>
  10037. PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
  10038. PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
  10039. </literallayout>
  10040. For more information, see the
  10041. "<ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>Using Virtual Providers</ulink>"
  10042. section in the Yocto Project Development Tasks Manual.
  10043. <note>
  10044. If you use a <filename>virtual/*</filename> item
  10045. with <filename>PREFERRED_PROVIDER</filename>, then any
  10046. recipe that
  10047. <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
  10048. that item but is not selected (defined) by
  10049. <filename>PREFERRED_PROVIDER</filename> is prevented
  10050. from building, which is usually desirable since this
  10051. mechanism is designed to select between mutually
  10052. exclusive alternative providers.
  10053. </note>
  10054. </para>
  10055. </glossdef>
  10056. </glossentry>
  10057. <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
  10058. <info>
  10059. PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."
  10060. </info>
  10061. <glossdef>
  10062. <para role="glossdeffirst">
  10063. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10064. If there are multiple versions of recipes available, this
  10065. variable determines which recipe should be given preference.
  10066. You must always suffix the variable with the
  10067. <link linkend='var-PN'><filename>PN</filename></link>
  10068. you want to select, and you should set the
  10069. <link linkend='var-PV'><filename>PV</filename></link>
  10070. accordingly for precedence.
  10071. You can use the "<filename>%</filename>" character as a
  10072. wildcard to match any number of characters, which can be
  10073. useful when specifying versions that contain long revision
  10074. numbers that could potentially change.
  10075. Here are two examples:
  10076. <literallayout class='monospaced'>
  10077. PREFERRED_VERSION_python = "3.4.0"
  10078. PREFERRED_VERSION_linux-yocto = "4.12%"
  10079. </literallayout>
  10080. <note>
  10081. The specified version is matched against
  10082. <link linkend='var-PV'><filename>PV</filename></link>,
  10083. which does not necessarily match the version part of
  10084. the recipe's filename.
  10085. For example, consider two recipes
  10086. <filename>foo_1.2.bb</filename> and
  10087. <filename>foo_git.bb</filename> where
  10088. <filename>foo_git.bb</filename> contains the following
  10089. assignment:
  10090. <literallayout class='monospaced'>
  10091. PV = "1.1+git${SRCPV}"
  10092. </literallayout>
  10093. In this case, the correct way to select
  10094. <filename>foo_git.bb</filename> is by using an
  10095. assignment such as the following:
  10096. <literallayout class='monospaced'>
  10097. PREFERRED_VERSION_foo = "1.1+git%"
  10098. </literallayout>
  10099. Compare that previous example against the following
  10100. incorrect example, which does not work:
  10101. <literallayout class='monospaced'>
  10102. PREFERRED_VERSION_foo = "git"
  10103. </literallayout>
  10104. </note>
  10105. Sometimes the <filename>PREFERRED_VERSION</filename>
  10106. variable can be set by configuration files in a way that
  10107. is hard to change.
  10108. You can use
  10109. <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
  10110. to set a machine-specific override.
  10111. Here is an example:
  10112. <literallayout class='monospaced'>
  10113. PREFERRED_VERSION_linux-yocto_qemux86 = "4.12%"
  10114. </literallayout>
  10115. Although not recommended, worst case, you can also use the
  10116. "forcevariable" override, which is the strongest override
  10117. possible.
  10118. Here is an example:
  10119. <literallayout class='monospaced'>
  10120. PREFERRED_VERSION_linux-yocto_forcevariable = "4.12%"
  10121. </literallayout>
  10122. <note>
  10123. The <filename>_forcevariable</filename> override is
  10124. not handled specially.
  10125. This override only works because the default value of
  10126. <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
  10127. includes "forcevariable".
  10128. </note>
  10129. </para>
  10130. </glossdef>
  10131. </glossentry>
  10132. <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
  10133. <info>
  10134. PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
  10135. </info>
  10136. <glossdef>
  10137. <para role="glossdeffirst">
  10138. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10139. Specifies additional paths from which the OpenEmbedded
  10140. build system gets source code.
  10141. When the build system searches for source code, it first
  10142. tries the local download directory.
  10143. If that location fails, the build system tries locations
  10144. defined by <filename>PREMIRRORS</filename>, the upstream
  10145. source, and then locations specified by
  10146. <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
  10147. in that order.
  10148. </para>
  10149. <para>
  10150. Assuming your distribution
  10151. (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
  10152. is "poky", the default value for
  10153. <filename>PREMIRRORS</filename> is defined in the
  10154. <filename>conf/distro/poky.conf</filename> file in the
  10155. <filename>meta-poky</filename> Git repository.
  10156. </para>
  10157. <para>
  10158. Typically, you could add a specific server for the
  10159. build system to attempt before any others by adding
  10160. something like the following to the
  10161. <filename>local.conf</filename> configuration file in the
  10162. <link linkend='build-directory'>Build Directory</link>:
  10163. <literallayout class='monospaced'>
  10164. PREMIRRORS_prepend = "\
  10165. git://.*/.* http://www.yoctoproject.org/sources/ \n \
  10166. ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
  10167. http://.*/.* http://www.yoctoproject.org/sources/ \n \
  10168. https://.*/.* http://www.yoctoproject.org/sources/ \n"
  10169. </literallayout>
  10170. These changes cause the build system to intercept
  10171. Git, FTP, HTTP, and HTTPS requests and direct them to
  10172. the <filename>http://</filename> sources mirror.
  10173. You can use <filename>file://</filename> URLs to point
  10174. to local directories or network shares as well.
  10175. </para>
  10176. </glossdef>
  10177. </glossentry>
  10178. <glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>
  10179. <info>
  10180. PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard', and 'extra'."
  10181. </info>
  10182. <glossdef>
  10183. <para role="glossdeffirst">
  10184. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10185. Indicates the importance of a package.
  10186. </para>
  10187. <para>
  10188. <filename>PRIORITY</filename> is considered to be part of
  10189. the distribution policy because the importance of any given
  10190. recipe depends on the purpose for which the distribution
  10191. is being produced.
  10192. Thus, <filename>PRIORITY</filename> is not normally set
  10193. within recipes.
  10194. </para>
  10195. <para>
  10196. You can set <filename>PRIORITY</filename> to "required",
  10197. "standard", "extra", and "optional", which is the default.
  10198. </para>
  10199. </glossdef>
  10200. </glossentry>
  10201. <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>
  10202. <info>
  10203. PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."
  10204. </info>
  10205. <glossdef>
  10206. <para role="glossdeffirst">
  10207. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10208. Specifies libraries installed within a recipe that
  10209. should be ignored by the OpenEmbedded build system's
  10210. shared library resolver.
  10211. This variable is typically used when software being
  10212. built by a recipe has its own private versions of a
  10213. library normally provided by another recipe.
  10214. In this case, you would not want the package containing
  10215. the private libraries to be set as a dependency on other
  10216. unrelated packages that should instead depend on the
  10217. package providing the standard version of the library.
  10218. </para>
  10219. <para>
  10220. Libraries specified in this variable should be specified
  10221. by their file name.
  10222. For example, from the Firefox recipe in meta-browser:
  10223. <literallayout class='monospaced'>
  10224. PRIVATE_LIBS = "libmozjs.so \
  10225. libxpcom.so \
  10226. libnspr4.so \
  10227. libxul.so \
  10228. libmozalloc.so \
  10229. libplc4.so \
  10230. libplds4.so"
  10231. </literallayout>
  10232. </para>
  10233. <para>
  10234. For more information, see the
  10235. "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
  10236. section in the Yocto Project Overview and Concepts Manual.
  10237. </para>
  10238. </glossdef>
  10239. </glossentry>
  10240. <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
  10241. <info>
  10242. PROVIDES[doc] = "A list of aliases that a recipe also provides. These aliases are useful for satisfying dependencies of other recipes during the build as specified by DEPENDS."
  10243. </info>
  10244. <glossdef>
  10245. <para role="glossdeffirst">
  10246. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10247. A list of aliases by which a particular recipe can be
  10248. known.
  10249. By default, a recipe's own
  10250. <filename><link linkend='var-PN'>PN</link></filename>
  10251. is implicitly already in its <filename>PROVIDES</filename>
  10252. list.
  10253. If a recipe uses <filename>PROVIDES</filename>, the
  10254. additional aliases are synonyms for the recipe and can
  10255. be useful satisfying dependencies of other recipes during
  10256. the build as specified by
  10257. <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
  10258. </para>
  10259. <para>
  10260. Consider the following example
  10261. <filename>PROVIDES</filename> statement from a recipe
  10262. file <filename>libav_0.8.11.bb</filename>:
  10263. <literallayout class='monospaced'>
  10264. PROVIDES += "libpostproc"
  10265. </literallayout>
  10266. The <filename>PROVIDES</filename> statement results in
  10267. the "libav" recipe also being known as "libpostproc".
  10268. </para>
  10269. <para>
  10270. In addition to providing recipes under alternate names,
  10271. the <filename>PROVIDES</filename> mechanism is also used
  10272. to implement virtual targets.
  10273. A virtual target is a name that corresponds to some
  10274. particular functionality (e.g. a Linux kernel).
  10275. Recipes that provide the functionality in question list the
  10276. virtual target in <filename>PROVIDES</filename>.
  10277. Recipes that depend on the functionality in question can
  10278. include the virtual target in
  10279. <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
  10280. to leave the choice of provider open.
  10281. </para>
  10282. <para>
  10283. Conventionally, virtual targets have names on the form
  10284. "virtual/function" (e.g. "virtual/kernel").
  10285. The slash is simply part of the name and has no
  10286. syntactical significance.
  10287. </para>
  10288. <para>
  10289. The
  10290. <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
  10291. variable is used to select which particular recipe
  10292. provides a virtual target.
  10293. <note>
  10294. <para>A corresponding mechanism for virtual runtime
  10295. dependencies (packages) exists.
  10296. However, the mechanism does not depend on any special
  10297. functionality beyond ordinary variable assignments.
  10298. For example,
  10299. <filename>VIRTUAL-RUNTIME_dev_manager</filename>
  10300. refers to the package of the component that manages
  10301. the <filename>/dev</filename> directory.</para>
  10302. <para>Setting the "preferred provider" for runtime
  10303. dependencies is as simple as using the following
  10304. assignment in a configuration file:</para>
  10305. <literallayout class='monospaced'>
  10306. VIRTUAL-RUNTIME_dev_manager = "udev"
  10307. </literallayout>
  10308. </note>
  10309. </para>
  10310. </glossdef>
  10311. </glossentry>
  10312. <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
  10313. <info>
  10314. PRSERV_HOST[doc] = "The network based PR service host and port."
  10315. </info>
  10316. <glossdef>
  10317. <para role="glossdeffirst">
  10318. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10319. The network based
  10320. <link linkend='var-PR'><filename>PR</filename></link>
  10321. service host and port.
  10322. </para>
  10323. <para>
  10324. The <filename>conf/local.conf.sample.extended</filename>
  10325. configuration file in the
  10326. <link linkend='source-directory'>Source Directory</link>
  10327. shows how the <filename>PRSERV_HOST</filename> variable is
  10328. set:
  10329. <literallayout class='monospaced'>
  10330. PRSERV_HOST = "localhost:0"
  10331. </literallayout>
  10332. You must set the variable if you want to automatically
  10333. start a local
  10334. <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
  10335. You can set <filename>PRSERV_HOST</filename> to other
  10336. values to use a remote PR service.
  10337. </para>
  10338. </glossdef>
  10339. </glossentry>
  10340. <glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm>
  10341. <info>
  10342. PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."
  10343. </info>
  10344. <glossdef>
  10345. <para role="glossdeffirst">
  10346. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10347. Specifies whether or not
  10348. <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>
  10349. (ptest) functionality is enabled when building a recipe.
  10350. You should not set this variable directly.
  10351. Enabling and disabling building Package Tests
  10352. at build time should be done by adding "ptest" to (or
  10353. removing it from)
  10354. <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
  10355. </para>
  10356. </glossdef>
  10357. </glossentry>
  10358. <glossentry id='var-PV'><glossterm>PV</glossterm>
  10359. <info>
  10360. PV[doc] = "The version of the recipe. The version is normally extracted from the recipe filename."
  10361. </info>
  10362. <glossdef>
  10363. <para role="glossdeffirst">
  10364. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10365. The version of the recipe.
  10366. The version is normally extracted from the recipe filename.
  10367. For example, if the recipe is named
  10368. <filename>expat_2.0.1.bb</filename>, then the default value
  10369. of <filename>PV</filename> will be "2.0.1".
  10370. <filename>PV</filename> is generally not overridden within
  10371. a recipe unless it is building an unstable (i.e.
  10372. development) version from a source code repository
  10373. (e.g. Git or Subversion).
  10374. </para>
  10375. <para>
  10376. <filename>PV</filename> is the default value of the
  10377. <link linkend='var-PKGV'><filename>PKGV</filename></link>
  10378. variable.
  10379. </para>
  10380. </glossdef>
  10381. </glossentry>
  10382. <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
  10383. <info>
  10384. PYTHON_ABI[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, denotes the Application Binary Interface (ABI) currently in use for Python."
  10385. </info>
  10386. <glossdef>
  10387. <para role="glossdeffirst">
  10388. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10389. When used by recipes that inherit the
  10390. <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
  10391. <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
  10392. <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
  10393. or
  10394. <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
  10395. classes, denotes the Application Binary Interface (ABI)
  10396. currently in use for Python.
  10397. By default, the ABI is "m".
  10398. You do not have to set this variable as the OpenEmbedded
  10399. build system sets it for you.
  10400. </para>
  10401. <para>
  10402. The OpenEmbedded build system uses the ABI to construct
  10403. directory names used when installing the Python headers
  10404. and libraries in sysroot
  10405. (e.g. <filename>.../python3.3m/...</filename>).
  10406. </para>
  10407. <para>
  10408. Recipes that inherit the
  10409. <link linkend='ref-classes-distutils'><filename>distutils</filename></link>
  10410. class during cross-builds also use this variable to
  10411. locate the headers and libraries of the appropriate Python
  10412. that the extension is targeting.
  10413. </para>
  10414. </glossdef>
  10415. </glossentry>
  10416. <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
  10417. <info>
  10418. PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."
  10419. </info>
  10420. <glossdef>
  10421. <para role="glossdeffirst">
  10422. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10423. When used by recipes that inherit the
  10424. <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
  10425. <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
  10426. <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
  10427. or
  10428. <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
  10429. classes, specifies the major Python version being built.
  10430. For Python 2.x, <filename>PYTHON_PN</filename> would
  10431. be "python2". For Python 3.x, the variable would be
  10432. "python3".
  10433. You do not have to set this variable as the
  10434. OpenEmbedded build system automatically sets it for you.
  10435. </para>
  10436. <para>
  10437. The variable allows recipes to use common infrastructure
  10438. such as the following:
  10439. <literallayout class='monospaced'>
  10440. DEPENDS += "${PYTHON_PN}-native"
  10441. </literallayout>
  10442. In the previous example, the version of the dependency
  10443. is <filename>PYTHON_PN</filename>.
  10444. </para>
  10445. </glossdef>
  10446. </glossentry>
  10447. </glossdiv>
  10448. <glossdiv id='var-glossary-r'><title>R</title>
  10449. <glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm>
  10450. <info>
  10451. RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."
  10452. </info>
  10453. <glossdef>
  10454. <para role="glossdeffirst">
  10455. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10456. The minimal command and arguments to run
  10457. <filename>ranlib</filename>.
  10458. </para>
  10459. </glossdef>
  10460. </glossentry>
  10461. <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
  10462. <info>
  10463. RCONFLICTS[doc] = "The list of packages that conflict with another package. Note that the package will not be installed if the conflicting packages are not first removed."
  10464. </info>
  10465. <glossdef>
  10466. <para role="glossdeffirst">
  10467. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10468. The list of packages that conflict with packages.
  10469. Note that packages will not be installed if conflicting
  10470. packages are not first removed.
  10471. </para>
  10472. <para>
  10473. Like all package-controlling variables, you must always use
  10474. them in conjunction with a package name override.
  10475. Here is an example:
  10476. <literallayout class='monospaced'>
  10477. RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"
  10478. </literallayout>
  10479. </para>
  10480. <para>
  10481. BitBake, which the OpenEmbedded build system uses, supports
  10482. specifying versioned dependencies.
  10483. Although the syntax varies depending on the packaging
  10484. format, BitBake hides these differences from you.
  10485. Here is the general syntax to specify versions with
  10486. the <filename>RCONFLICTS</filename> variable:
  10487. <literallayout class='monospaced'>
  10488. RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
  10489. </literallayout>
  10490. For <filename>operator</filename>, you can specify the
  10491. following:
  10492. <literallayout class='monospaced'>
  10493. =
  10494. &lt;
  10495. &gt;
  10496. &lt;=
  10497. &gt;=
  10498. </literallayout>
  10499. For example, the following sets up a dependency on version
  10500. 1.2 or greater of the package <filename>foo</filename>:
  10501. <literallayout class='monospaced'>
  10502. RCONFLICTS_${PN} = "foo (>= 1.2)"
  10503. </literallayout>
  10504. </para>
  10505. </glossdef>
  10506. </glossentry>
  10507. <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
  10508. <info>
  10509. RDEPENDS[doc] = "Lists runtime dependencies of a package."
  10510. </info>
  10511. <glossdef>
  10512. <para role="glossdeffirst">
  10513. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10514. Lists runtime dependencies of a package.
  10515. These dependencies are other packages that must be
  10516. installed in order for the package to function correctly.
  10517. As an example, the following assignment declares that the
  10518. package <filename>foo</filename> needs the packages
  10519. <filename>bar</filename> and <filename>baz</filename> to
  10520. be installed:
  10521. <literallayout class='monospaced'>
  10522. RDEPENDS_foo = "bar baz"
  10523. </literallayout>
  10524. The most common types of package runtime dependencies are
  10525. automatically detected and added.
  10526. Therefore, most recipes do not need to set
  10527. <filename>RDEPENDS</filename>.
  10528. For more information, see the
  10529. "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
  10530. section in the Yocto Project Overview and Concepts Manual.
  10531. </para>
  10532. <para>
  10533. The practical effect of the above
  10534. <filename>RDEPENDS</filename> assignment is that
  10535. <filename>bar</filename> and <filename>baz</filename>
  10536. will be declared as dependencies inside the package
  10537. <filename>foo</filename> when it is written out by one of
  10538. the
  10539. <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
  10540. tasks.
  10541. Exactly how this is done depends on which package format
  10542. is used, which is determined by
  10543. <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>.
  10544. When the corresponding package manager installs the
  10545. package, it will know to also install the packages on
  10546. which it depends.
  10547. </para>
  10548. <para>
  10549. To ensure that the packages <filename>bar</filename> and
  10550. <filename>baz</filename> get built, the previous
  10551. <filename>RDEPENDS</filename> assignment also causes a task
  10552. dependency to be added.
  10553. This dependency is from the recipe's
  10554. <link linkend='ref-tasks-build'><filename>do_build</filename></link>
  10555. (not to be confused with
  10556. <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>)
  10557. task to the <filename>do_package_write_*</filename>
  10558. task of the recipes that build <filename>bar</filename> and
  10559. <filename>baz</filename>.
  10560. </para>
  10561. <para>
  10562. The names of the packages you list within
  10563. <filename>RDEPENDS</filename> must be the names of other
  10564. packages - they cannot be recipe names.
  10565. Although package names and recipe names usually match,
  10566. the important point here is that you are
  10567. providing package names within the
  10568. <filename>RDEPENDS</filename> variable.
  10569. For an example of the default list of packages created from
  10570. a recipe, see the
  10571. <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
  10572. variable.
  10573. </para>
  10574. <para>
  10575. Because the <filename>RDEPENDS</filename> variable applies
  10576. to packages being built, you should always use the variable
  10577. in a form with an attached package name (remember that a
  10578. single recipe can build multiple packages).
  10579. For example, suppose you are building a development package
  10580. that depends on the <filename>perl</filename> package.
  10581. In this case, you would use the following
  10582. <filename>RDEPENDS</filename> statement:
  10583. <literallayout class='monospaced'>
  10584. RDEPENDS_${PN}-dev += "perl"
  10585. </literallayout>
  10586. In the example, the development package depends on
  10587. the <filename>perl</filename> package.
  10588. Thus, the <filename>RDEPENDS</filename> variable has the
  10589. <filename>${PN}-dev</filename> package name as part of the
  10590. variable.
  10591. <note>
  10592. <title>Caution</title>
  10593. <filename>RDEPENDS_${PN}-dev</filename> includes
  10594. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>
  10595. by default.
  10596. This default is set in the BitBake configuration file
  10597. (<filename>meta/conf/bitbake.conf</filename>).
  10598. Be careful not to accidentally remove
  10599. <filename>${PN}</filename> when modifying
  10600. <filename>RDEPENDS_${PN}-dev</filename>.
  10601. Use the "+=" operator rather than the "=" operator.
  10602. </note>
  10603. </para>
  10604. <para>
  10605. The package names you use with
  10606. <filename>RDEPENDS</filename> must appear as they would in
  10607. the <filename>PACKAGES</filename> variable.
  10608. The
  10609. <link linkend='var-PKG'><filename>PKG</filename></link>
  10610. variable allows a different name to be used for
  10611. the final package (e.g. the
  10612. <link linkend='ref-classes-debian'><filename>debian</filename></link>
  10613. class uses this to rename packages), but this final package
  10614. name cannot be used with <filename>RDEPENDS</filename>,
  10615. which makes sense as <filename>RDEPENDS</filename> is meant
  10616. to be independent of the package format used.
  10617. </para>
  10618. <para>
  10619. BitBake, which the OpenEmbedded build system uses, supports
  10620. specifying versioned dependencies.
  10621. Although the syntax varies depending on the packaging
  10622. format, BitBake hides these differences from you.
  10623. Here is the general syntax to specify versions with
  10624. the <filename>RDEPENDS</filename> variable:
  10625. <literallayout class='monospaced'>
  10626. RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
  10627. </literallayout>
  10628. For <replaceable>operator</replaceable>, you can specify the
  10629. following:
  10630. <literallayout class='monospaced'>
  10631. =
  10632. &lt;
  10633. &gt;
  10634. &lt;=
  10635. &gt;=
  10636. </literallayout>
  10637. For <replaceable>version</replaceable>, provide the version
  10638. number.
  10639. <note><title>Tip</title>
  10640. You can use
  10641. <link linkend='var-EXTENDPKGV'><filename>EXTENDPKGV</filename></link>
  10642. to provide a full package version specification.
  10643. </note>
  10644. For example, the following sets up a dependency on version
  10645. 1.2 or greater of the package <filename>foo</filename>:
  10646. <literallayout class='monospaced'>
  10647. RDEPENDS_${PN} = "foo (>= 1.2)"
  10648. </literallayout>
  10649. </para>
  10650. <para>
  10651. For information on build-time dependencies, see the
  10652. <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
  10653. variable.
  10654. You can also see the
  10655. "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
  10656. "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
  10657. sections in the BitBake User Manual for additional
  10658. information on tasks and dependencies.
  10659. </para>
  10660. </glossdef>
  10661. </glossentry>
  10662. <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
  10663. <info>
  10664. REQUIRED_DISTRO_FEATURES[doc] = "When a recipe inherits the distro_features_check class, this variable identifies distribution features that must exist in the current configuration in order for the OpenEmbedded build system to build the recipe."
  10665. </info>
  10666. <glossdef>
  10667. <para role="glossdeffirst">
  10668. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10669. When inheriting the
  10670. <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
  10671. class, this
  10672. variable identifies distribution features that must
  10673. exist in the current configuration in order for the
  10674. OpenEmbedded build system to build the recipe.
  10675. In other words, if the
  10676. <filename>REQUIRED_DISTRO_FEATURES</filename> variable
  10677. lists a feature that does not appear in
  10678. <filename>DISTRO_FEATURES</filename> within the
  10679. current configuration, an error occurs and the
  10680. build stops.
  10681. </para>
  10682. </glossdef>
  10683. </glossentry>
  10684. <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
  10685. <info>
  10686. RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."
  10687. </info>
  10688. <glossdef>
  10689. <para role="glossdeffirst">
  10690. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10691. With <filename>rm_work</filename> enabled, this
  10692. variable specifies a list of recipes whose work directories
  10693. should not be removed.
  10694. See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
  10695. section for more details.
  10696. </para>
  10697. </glossdef>
  10698. </glossentry>
  10699. <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
  10700. <info>
  10701. ROOT_HOME[doc] = "Defines the root home directory."
  10702. </info>
  10703. <glossdef>
  10704. <para role="glossdeffirst">
  10705. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10706. Defines the root home directory.
  10707. By default, this directory is set as follows in the
  10708. BitBake configuration file:
  10709. <literallayout class='monospaced'>
  10710. ROOT_HOME ??= "/home/root"
  10711. </literallayout>
  10712. <note>
  10713. This default value is likely used because some
  10714. embedded solutions prefer to have a read-only root
  10715. filesystem and prefer to keep writeable data in one
  10716. place.
  10717. </note>
  10718. </para>
  10719. <para>
  10720. You can override the default by setting the variable
  10721. in any layer or in the <filename>local.conf</filename> file.
  10722. Because the default is set using a "weak" assignment
  10723. (i.e. "??="), you can use either of the following forms
  10724. to define your override:
  10725. <literallayout class='monospaced'>
  10726. ROOT_HOME = "/root"
  10727. ROOT_HOME ?= "/root"
  10728. </literallayout>
  10729. These override examples use <filename>/root</filename>,
  10730. which is probably the most commonly used override.
  10731. </para>
  10732. </glossdef>
  10733. </glossentry>
  10734. <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
  10735. <info>
  10736. ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."
  10737. </info>
  10738. <glossdef>
  10739. <para role="glossdeffirst">
  10740. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10741. Indicates a filesystem image to include as the root
  10742. filesystem.
  10743. </para>
  10744. <para>
  10745. The <filename>ROOTFS</filename> variable is an optional
  10746. variable used with the
  10747. <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
  10748. class.
  10749. </para>
  10750. </glossdef>
  10751. </glossentry>
  10752. <glossentry id='var-ROOTFS_POSTINSTALL_COMMAND'><glossterm>ROOTFS_POSTINSTALL_COMMAND</glossterm>
  10753. <info>
  10754. ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."
  10755. </info>
  10756. <glossdef>
  10757. <para role="glossdeffirst">
  10758. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10759. Specifies a list of functions to call after the
  10760. OpenEmbedded build system has installed packages.
  10761. You can specify functions separated by semicolons:
  10762. <literallayout class='monospaced'>
  10763. ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
  10764. </literallayout>
  10765. </para>
  10766. <para>
  10767. If you need to pass the root filesystem path to a command
  10768. within a function, you can use
  10769. <filename>${IMAGE_ROOTFS}</filename>, which points to
  10770. the directory that becomes the root filesystem image.
  10771. See the
  10772. <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
  10773. variable for more information.
  10774. </para>
  10775. </glossdef>
  10776. </glossentry>
  10777. <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
  10778. <info>
  10779. ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."
  10780. </info>
  10781. <glossdef>
  10782. <para role="glossdeffirst">
  10783. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10784. Specifies a list of functions to call once the
  10785. OpenEmbedded build system has created the root filesystem.
  10786. You can specify functions separated by semicolons:
  10787. <literallayout class='monospaced'>
  10788. ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
  10789. </literallayout>
  10790. </para>
  10791. <para>
  10792. If you need to pass the root filesystem path to a command
  10793. within a function, you can use
  10794. <filename>${IMAGE_ROOTFS}</filename>, which points to
  10795. the directory that becomes the root filesystem image.
  10796. See the
  10797. <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
  10798. variable for more information.
  10799. </para>
  10800. </glossdef>
  10801. </glossentry>
  10802. <glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>
  10803. <info>
  10804. ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."
  10805. </info>
  10806. <glossdef>
  10807. <para role="glossdeffirst">
  10808. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10809. Specifies a list of functions to call after the
  10810. OpenEmbedded build system has removed unnecessary
  10811. packages.
  10812. When runtime package management is disabled in the
  10813. image, several packages are removed including
  10814. <filename>base-passwd</filename>,
  10815. <filename>shadow</filename>, and
  10816. <filename>update-alternatives</filename>.
  10817. You can specify functions separated by semicolons:
  10818. <literallayout class='monospaced'>
  10819. ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
  10820. </literallayout>
  10821. </para>
  10822. <para>
  10823. If you need to pass the root filesystem path to a command
  10824. within a function, you can use
  10825. <filename>${IMAGE_ROOTFS}</filename>, which points to
  10826. the directory that becomes the root filesystem image.
  10827. See the
  10828. <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
  10829. variable for more information.
  10830. </para>
  10831. </glossdef>
  10832. </glossentry>
  10833. <glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>
  10834. <info>
  10835. ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."
  10836. </info>
  10837. <glossdef>
  10838. <para role="glossdeffirst">
  10839. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10840. Specifies a list of functions to call before the
  10841. OpenEmbedded build system has created the root filesystem.
  10842. You can specify functions separated by semicolons:
  10843. <literallayout class='monospaced'>
  10844. ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
  10845. </literallayout>
  10846. </para>
  10847. <para>
  10848. If you need to pass the root filesystem path to a command
  10849. within a function, you can use
  10850. <filename>${IMAGE_ROOTFS}</filename>, which points to
  10851. the directory that becomes the root filesystem image.
  10852. See the
  10853. <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
  10854. variable for more information.
  10855. </para>
  10856. </glossdef>
  10857. </glossentry>
  10858. <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
  10859. <info>
  10860. RPROVIDES[doc] = "A list of package name aliases that a package also provides. These aliases are useful for satisfying runtime dependencies of other packages both during the build and on the target."
  10861. </info>
  10862. <glossdef>
  10863. <para role="glossdeffirst">
  10864. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10865. A list of package name aliases that a package also provides.
  10866. These aliases are useful for satisfying runtime dependencies
  10867. of other packages both during the build and on the target
  10868. (as specified by
  10869. <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
  10870. <note>
  10871. A package's own name is implicitly already in its
  10872. <filename>RPROVIDES</filename> list.
  10873. </note>
  10874. </para>
  10875. <para>
  10876. As with all package-controlling variables, you must always
  10877. use the variable in conjunction with a package name override.
  10878. Here is an example:
  10879. <literallayout class='monospaced'>
  10880. RPROVIDES_${PN} = "widget-abi-2"
  10881. </literallayout>
  10882. </para>
  10883. </glossdef>
  10884. </glossentry>
  10885. <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
  10886. <info>
  10887. RRECOMMENDS[doc] = "A list of packages that extends the usability of a package being built. The package being built does not depend on this list of packages in order to successfully build, but needs them for the extended usability."
  10888. </info>
  10889. <glossdef>
  10890. <para role="glossdeffirst">
  10891. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10892. A list of packages that extends the usability of a package
  10893. being built.
  10894. The package being built does not depend on this list of
  10895. packages in order to successfully build, but rather
  10896. uses them for extended usability.
  10897. To specify runtime dependencies for packages, see the
  10898. <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
  10899. variable.
  10900. </para>
  10901. <para>
  10902. The package manager will automatically install the
  10903. <filename>RRECOMMENDS</filename> list of packages when
  10904. installing the built package.
  10905. However, you can prevent listed packages from being
  10906. installed by using the
  10907. <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
  10908. <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
  10909. and
  10910. <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
  10911. variables.
  10912. </para>
  10913. <para>
  10914. Packages specified in
  10915. <filename>RRECOMMENDS</filename> need not actually be
  10916. produced.
  10917. However, a recipe must exist that provides each package,
  10918. either through the
  10919. <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
  10920. or
  10921. <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
  10922. variables or the
  10923. <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>
  10924. variable, or an error will occur during the build.
  10925. If such a recipe does exist and the package is not produced,
  10926. the build continues without error.
  10927. </para>
  10928. <para>
  10929. Because the <filename>RRECOMMENDS</filename> variable
  10930. applies to packages being built, you should always attach
  10931. an override to the variable to specify the particular
  10932. package whose usability is being extended.
  10933. For example, suppose you are building a development package
  10934. that is extended to support wireless functionality.
  10935. In this case, you would use the following:
  10936. <literallayout class='monospaced'>
  10937. RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"
  10938. </literallayout>
  10939. In the example, the package name
  10940. (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
  10941. must appear as it would in the
  10942. <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
  10943. namespace before any renaming of the output package by
  10944. classes such as <filename>debian.bbclass</filename>.
  10945. </para>
  10946. <para>
  10947. BitBake, which the OpenEmbedded build system uses, supports
  10948. specifying versioned recommends.
  10949. Although the syntax varies depending on the packaging
  10950. format, BitBake hides these differences from you.
  10951. Here is the general syntax to specify versions with
  10952. the <filename>RRECOMMENDS</filename> variable:
  10953. <literallayout class='monospaced'>
  10954. RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
  10955. </literallayout>
  10956. For <filename>operator</filename>, you can specify the
  10957. following:
  10958. <literallayout class='monospaced'>
  10959. =
  10960. &lt;
  10961. &gt;
  10962. &lt;=
  10963. &gt;=
  10964. </literallayout>
  10965. For example, the following sets up a recommend on version
  10966. 1.2 or greater of the package <filename>foo</filename>:
  10967. <literallayout class='monospaced'>
  10968. RRECOMMENDS_${PN} = "foo (>= 1.2)"
  10969. </literallayout>
  10970. </para>
  10971. </glossdef>
  10972. </glossentry>
  10973. <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
  10974. <info>
  10975. RREPLACES[doc] = "A list of packages replaced by a package. The package manager uses this variable to determine which package should be installed to replace other package(s) during an upgrade."
  10976. </info>
  10977. <glossdef>
  10978. <para role="glossdeffirst">
  10979. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  10980. A list of packages replaced by a package.
  10981. The package manager uses this variable to determine which
  10982. package should be installed to replace other package(s)
  10983. during an upgrade.
  10984. In order to also have the other package(s) removed at the
  10985. same time, you must add the name of the other
  10986. package to the
  10987. <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
  10988. </para>
  10989. <para>
  10990. As with all package-controlling variables, you must use
  10991. this variable in conjunction with a package name
  10992. override.
  10993. Here is an example:
  10994. <literallayout class='monospaced'>
  10995. RREPLACES_${PN} = "<replaceable>other_package_being_replaced</replaceable>"
  10996. </literallayout>
  10997. </para>
  10998. <para>
  10999. BitBake, which the OpenEmbedded build system uses, supports
  11000. specifying versioned replacements.
  11001. Although the syntax varies depending on the packaging
  11002. format, BitBake hides these differences from you.
  11003. Here is the general syntax to specify versions with
  11004. the <filename>RREPLACES</filename> variable:
  11005. <literallayout class='monospaced'>
  11006. RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
  11007. </literallayout>
  11008. For <filename>operator</filename>, you can specify the
  11009. following:
  11010. <literallayout class='monospaced'>
  11011. =
  11012. &lt;
  11013. &gt;
  11014. &lt;=
  11015. &gt;=
  11016. </literallayout>
  11017. For example, the following sets up a replacement using
  11018. version 1.2 or greater of the package
  11019. <filename>foo</filename>:
  11020. <literallayout class='monospaced'>
  11021. RREPLACES_${PN} = "foo (>= 1.2)"
  11022. </literallayout>
  11023. </para>
  11024. </glossdef>
  11025. </glossentry>
  11026. <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
  11027. <info>
  11028. RSUGGESTS[doc] = "A list of additional packages that you can suggest for installation by the package manager at the time a package is installed. Not all package managers support this functionality."
  11029. </info>
  11030. <glossdef>
  11031. <para role="glossdeffirst">
  11032. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11033. A list of additional packages that you can suggest for
  11034. installation by the package manager at the time a package
  11035. is installed.
  11036. Not all package managers support this functionality.
  11037. </para>
  11038. <para>
  11039. As with all package-controlling variables, you must always
  11040. use this variable in conjunction with a package name
  11041. override.
  11042. Here is an example:
  11043. <literallayout class='monospaced'>
  11044. RSUGGESTS_${PN} = "<replaceable>useful_package</replaceable> <replaceable>another_package</replaceable>"
  11045. </literallayout>
  11046. </para>
  11047. </glossdef>
  11048. </glossentry>
  11049. </glossdiv>
  11050. <glossdiv id='var-glossary-s'><title>S</title>
  11051. <glossentry id='var-S'><glossterm>S</glossterm>
  11052. <info>
  11053. S[doc] = "The location in the Build Directory where unpacked package source code resides."
  11054. </info>
  11055. <glossdef>
  11056. <para role="glossdeffirst">
  11057. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11058. The location in the
  11059. <link linkend='build-directory'>Build Directory</link>
  11060. where unpacked recipe source code resides.
  11061. By default, this directory is
  11062. <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/${</filename><link linkend='var-BPN'><filename>BPN</filename></link><filename>}-${</filename><link linkend='var-PV'><filename>PV</filename></link><filename>}</filename>,
  11063. where <filename>${BPN}</filename> is the base recipe name
  11064. and <filename>${PV}</filename> is the recipe version.
  11065. If the source tarball extracts the code to a directory
  11066. named anything other than <filename>${BPN}-${PV}</filename>,
  11067. or if the source code is fetched from an SCM such as
  11068. Git or Subversion, then you must set <filename>S</filename>
  11069. in the recipe so that the OpenEmbedded build system
  11070. knows where to find the unpacked source.
  11071. </para>
  11072. <para>
  11073. As an example, assume a
  11074. <link linkend='source-directory'>Source Directory</link>
  11075. top-level folder named <filename>poky</filename> and a
  11076. default Build Directory at <filename>poky/build</filename>.
  11077. In this case, the work directory the build system uses
  11078. to keep the unpacked recipe for <filename>db</filename>
  11079. is the following:
  11080. <literallayout class='monospaced'>
  11081. poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
  11082. </literallayout>
  11083. The unpacked source code resides in the
  11084. <filename>db-5.1.19</filename> folder.
  11085. </para>
  11086. <para>
  11087. This next example assumes a Git repository.
  11088. By default, Git repositories are cloned to
  11089. <filename>${WORKDIR}/git</filename> during
  11090. <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>.
  11091. Since this path is different from the default value of
  11092. <filename>S</filename>, you must set it specifically
  11093. so the source can be located:
  11094. <literallayout class='monospaced'>
  11095. SRC_URI = "git://path/to/repo.git"
  11096. S = "${WORKDIR}/git"
  11097. </literallayout>
  11098. </para>
  11099. </glossdef>
  11100. </glossentry>
  11101. <glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>SANITY_REQUIRED_UTILITIES</glossterm>
  11102. <info>
  11103. SANITY_REQUIRED_UTILITIES[doc] = "Specifies a list of command-line utilities that should be checked for during the initial sanity checking process when running BitBake."
  11104. </info>
  11105. <glossdef>
  11106. <para role="glossdeffirst">
  11107. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11108. Specifies a list of command-line utilities that should be
  11109. checked for during the initial sanity checking process when
  11110. running BitBake.
  11111. If any of the utilities are not installed on the build host,
  11112. then BitBake immediately exits with an error.
  11113. </para>
  11114. </glossdef>
  11115. </glossentry>
  11116. <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
  11117. <info>
  11118. SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."
  11119. </info>
  11120. <glossdef>
  11121. <para role="glossdeffirst">
  11122. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11123. A list of the host distribution identifiers that the
  11124. build system has been tested against.
  11125. Identifiers consist of the host distributor ID
  11126. followed by the release,
  11127. as reported by the <filename>lsb_release</filename> tool
  11128. or as read from <filename>/etc/lsb-release</filename>.
  11129. Separate the list items with explicit newline
  11130. characters (<filename>\n</filename>).
  11131. If <filename>SANITY_TESTED_DISTROS</filename> is not empty
  11132. and the current value of
  11133. <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
  11134. does not appear in the list, then the build system reports
  11135. a warning that indicates the current host distribution has
  11136. not been tested as a build host.
  11137. </para>
  11138. </glossdef>
  11139. </glossentry>
  11140. <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
  11141. <info>
  11142. SDK_ARCH[doc] = "The target architecture for the SDK."
  11143. </info>
  11144. <glossdef>
  11145. <para role="glossdeffirst">
  11146. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11147. The target architecture for the SDK.
  11148. Typically, you do not directly set this variable.
  11149. Instead, use
  11150. <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
  11151. </para>
  11152. </glossdef>
  11153. </glossentry>
  11154. <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
  11155. <info>
  11156. SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."
  11157. </info>
  11158. <glossdef>
  11159. <para role="glossdeffirst">
  11160. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11161. The directory set up and used by the
  11162. <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
  11163. to which the SDK is deployed.
  11164. The <filename>populate_sdk_base</filename> class defines
  11165. <filename>SDK_DEPLOY</filename> as follows:
  11166. <literallayout class='monospaced'>
  11167. SDK_DEPLOY = "${<link linkend='var-TMPDIR'>TMPDIR</link>}/deploy/sdk"
  11168. </literallayout>
  11169. </para>
  11170. </glossdef>
  11171. </glossentry>
  11172. <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
  11173. <info>
  11174. SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output."
  11175. </info>
  11176. <glossdef>
  11177. <para role="glossdeffirst">
  11178. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11179. The parent directory used by the OpenEmbedded build system
  11180. when creating SDK output.
  11181. The
  11182. <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
  11183. class defines the variable as follows:
  11184. <literallayout class='monospaced'>
  11185. SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk"
  11186. </literallayout>
  11187. <note>
  11188. The <filename>SDK_DIR</filename> directory is a
  11189. temporary directory as it is part of
  11190. <filename>WORKDIR</filename>.
  11191. The final output directory is
  11192. <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
  11193. </note>
  11194. </para>
  11195. </glossdef>
  11196. </glossentry>
  11197. <glossentry id='var-SDK_EXT_TYPE'><glossterm>SDK_EXT_TYPE</glossterm>
  11198. <info>
  11199. SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."
  11200. </info>
  11201. <glossdef>
  11202. <para role="glossdeffirst">
  11203. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11204. Controls whether or not shared state artifacts are copied
  11205. into the extensible SDK.
  11206. The default value of "full" copies all of the required
  11207. shared state artifacts into the extensible SDK.
  11208. The value "minimal" leaves these artifacts out of the
  11209. SDK.
  11210. <note>
  11211. If you set the variable to "minimal", you need to
  11212. ensure
  11213. <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
  11214. is set in the SDK's configuration to enable the
  11215. artifacts to be fetched as needed.
  11216. </note>
  11217. </para>
  11218. </glossdef>
  11219. </glossentry>
  11220. <glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>
  11221. <info>
  11222. SDK_HOST_MANIFEST[doc] = "The manifest file for the host part of the SDK. This file lists all the installed packages that make up the host part of the SDK."
  11223. </info>
  11224. <glossdef>
  11225. <para role="glossdeffirst">
  11226. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11227. The manifest file for the host part of the SDK.
  11228. This file lists all the installed packages that make up
  11229. the host part of SDK.
  11230. The file contains package information on a line-per-package
  11231. basis as follows:
  11232. <literallayout class='monospaced'>
  11233. <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
  11234. </literallayout>
  11235. </para>
  11236. <para>
  11237. The
  11238. <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
  11239. class defines the manifest file as follows:
  11240. <literallayout class='monospaced'>
  11241. SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
  11242. </literallayout>
  11243. The location is derived using the
  11244. <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
  11245. and
  11246. <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
  11247. variables.
  11248. </para>
  11249. </glossdef>
  11250. </glossentry>
  11251. <glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>
  11252. <info>
  11253. SDK_INCLUDE_PKGDATA[doc] = "When set to "1", specifies to include the packagedata for all recipes in the "world" target in the extensible SDK."
  11254. </info>
  11255. <glossdef>
  11256. <para role="glossdeffirst">
  11257. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11258. When set to "1", specifies to include the packagedata for
  11259. all recipes in the "world" target in the extensible SDK.
  11260. Including this data allows the
  11261. <filename>devtool search</filename> command to find these
  11262. recipes in search results, as well as allows the
  11263. <filename>devtool add</filename> command to map
  11264. dependencies more effectively.
  11265. <note>
  11266. Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>
  11267. variable significantly increases build time because
  11268. all of world needs to be built.
  11269. Enabling the variable also slightly increases the size
  11270. of the extensible SDK.
  11271. </note>
  11272. </para>
  11273. </glossdef>
  11274. </glossentry>
  11275. <glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>
  11276. <info>
  11277. SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."
  11278. </info>
  11279. <glossdef>
  11280. <para role="glossdeffirst">
  11281. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11282. When set to "1", specifies to include the toolchain in the
  11283. extensible SDK.
  11284. Including the toolchain is useful particularly when
  11285. <link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link>
  11286. is set to "minimal" to keep the SDK reasonably small
  11287. but you still want to provide a usable toolchain.
  11288. For example, suppose you want to use the toolchain from an
  11289. IDE (e.g. Eclipse) or from other tools and you do not
  11290. want to perform additional steps to install the toolchain.
  11291. </para>
  11292. <para>
  11293. The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable
  11294. defaults to "0" if <filename>SDK_EXT_TYPE</filename>
  11295. is set to "minimal", and defaults to "1" if
  11296. <filename>SDK_EXT_TYPE</filename> is set to "full".
  11297. </para>
  11298. </glossdef>
  11299. </glossentry>
  11300. <glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>
  11301. <info>
  11302. SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."
  11303. </info>
  11304. <glossdef>
  11305. <para role="glossdeffirst">
  11306. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11307. A list of classes to remove from the
  11308. <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
  11309. value globally within the extensible SDK configuration.
  11310. The default value is "buildhistory icecc".
  11311. </para>
  11312. <para>
  11313. Some classes are not generally applicable within
  11314. the extensible SDK context and you can use this variable
  11315. to disable them.
  11316. </para>
  11317. </glossdef>
  11318. </glossentry>
  11319. <glossentry id='var-SDK_LOCAL_CONF_BLACKLIST'><glossterm>SDK_LOCAL_CONF_BLACKLIST</glossterm>
  11320. <info>
  11321. SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."
  11322. </info>
  11323. <glossdef>
  11324. <para role="glossdeffirst">
  11325. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11326. A list of variables not allowed through from the build
  11327. system configuration into the extensible SDK configuration.
  11328. Usually, these are variables that are specific to the
  11329. machine on which the build system is running and thus
  11330. would be potentially problematic within the extensible SDK.
  11331. </para>
  11332. </glossdef>
  11333. </glossentry>
  11334. <glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>
  11335. <info>
  11336. SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."
  11337. </info>
  11338. <glossdef>
  11339. <para role="glossdeffirst">
  11340. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11341. A list of variables allowed through from the build system
  11342. configuration into the extensible SDK configuration.
  11343. This list overrides the variables specified using the
  11344. <link linkend='var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></link>
  11345. variable as well as any variables identified by automatic
  11346. blacklisting due to the "/" character being found at the
  11347. start of the value, which is usually indicative of being a
  11348. path and thus might not be valid on the system where the
  11349. SDK is installed.
  11350. </para>
  11351. </glossdef>
  11352. </glossentry>
  11353. <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
  11354. <info>
  11355. SDK_NAME[doc] = "The base name for SDK output files."
  11356. </info>
  11357. <glossdef>
  11358. <para role="glossdeffirst">
  11359. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11360. The base name for SDK output files.
  11361. The name is derived from the
  11362. <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
  11363. <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
  11364. <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
  11365. <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
  11366. and
  11367. <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
  11368. variables:
  11369. <literallayout class='monospaced'>
  11370. SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
  11371. </literallayout>
  11372. </para>
  11373. </glossdef>
  11374. </glossentry>
  11375. <glossentry id='var-SDK_OS'><glossterm>SDK_OS</glossterm>
  11376. <info>
  11377. SDK_OS[doc] = "The operating system for which the SDK will be built."
  11378. </info>
  11379. <glossdef>
  11380. <para role="glossdeffirst">
  11381. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11382. Specifies the operating system for which the SDK
  11383. will be built.
  11384. The default value is the value of
  11385. <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
  11386. </para>
  11387. </glossdef>
  11388. </glossentry>
  11389. <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
  11390. <info>
  11391. SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."
  11392. </info>
  11393. <glossdef>
  11394. <para role="glossdeffirst">
  11395. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11396. The location used by the OpenEmbedded build system when
  11397. creating SDK output.
  11398. The
  11399. <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
  11400. class defines the variable as follows:
  11401. <literallayout class='monospaced'>
  11402. SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image"
  11403. </literallayout>
  11404. <note>
  11405. The <filename>SDK_OUTPUT</filename> directory is a
  11406. temporary directory as it is part of
  11407. <filename>WORKDIR</filename> by way of
  11408. <filename>SDK_DIR</filename>.
  11409. The final output directory is
  11410. <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
  11411. </note>
  11412. </para>
  11413. </glossdef>
  11414. </glossentry>
  11415. <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>
  11416. <info>
  11417. SDK_PACKAGE_ARCHS[doc] = "Specifies a list of architectures compatible with the SDK machine. This variable is set automatically and should not normally be hand-edited."
  11418. </info>
  11419. <glossdef>
  11420. <para role="glossdeffirst">
  11421. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11422. Specifies a list of architectures compatible with
  11423. the SDK machine.
  11424. This variable is set automatically and should not
  11425. normally be hand-edited.
  11426. Entries are separated using spaces and listed in order
  11427. of priority.
  11428. The default value for
  11429. <filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch
  11430. ${SDK_ARCH}-${SDKPKGSUFFIX}".
  11431. </para>
  11432. </glossdef>
  11433. </glossentry>
  11434. <glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>
  11435. <info>
  11436. SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the SDK."
  11437. </info>
  11438. <glossdef>
  11439. <para role="glossdeffirst">
  11440. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11441. Specifies a list of functions to call once the
  11442. OpenEmbedded build system creates the SDK.
  11443. You can specify functions separated by semicolons:
  11444. <literallayout class='monospaced'>
  11445. SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
  11446. </literallayout>
  11447. </para>
  11448. <para>
  11449. If you need to pass an SDK path to a command within a
  11450. function, you can use
  11451. <filename>${SDK_DIR}</filename>, which points to
  11452. the parent directory used by the OpenEmbedded build system
  11453. when creating SDK output.
  11454. See the
  11455. <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
  11456. variable for more information.
  11457. </para>
  11458. </glossdef>
  11459. </glossentry>
  11460. <glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>
  11461. <info>
  11462. SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."
  11463. </info>
  11464. <glossdef>
  11465. <para role="glossdeffirst">
  11466. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11467. The toolchain binary prefix used for
  11468. <filename>nativesdk</filename> recipes.
  11469. The OpenEmbedded build system uses the
  11470. <filename>SDK_PREFIX</filename> value to set the
  11471. <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
  11472. when building <filename>nativesdk</filename> recipes.
  11473. The default value is "${SDK_SYS}-".
  11474. </para>
  11475. </glossdef>
  11476. </glossentry>
  11477. <glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>
  11478. <info>
  11479. SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."
  11480. </info>
  11481. <glossdef>
  11482. <para role="glossdeffirst">
  11483. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11484. A list of shared state tasks added to the extensible SDK.
  11485. By default, the following tasks are added:
  11486. <literallayout class='monospaced'>
  11487. do_populate_lic
  11488. do_package_qa
  11489. do_populate_sysroot
  11490. do_deploy
  11491. </literallayout>
  11492. Despite the default value of "" for the
  11493. <filename>SDK_RECRDEP_TASKS</filename> variable, the
  11494. above four tasks are always added to the SDK.
  11495. To specify tasks beyond these four, you need to use
  11496. the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.
  11497. you are defining additional tasks that are needed in
  11498. order to build
  11499. <link linkend='var-SDK_TARGETS'><filename>SDK_TARGETS</filename></link>).
  11500. </para>
  11501. </glossdef>
  11502. </glossentry>
  11503. <glossentry id='var-SDK_SYS'><glossterm>SDK_SYS</glossterm>
  11504. <info>
  11505. SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."
  11506. </info>
  11507. <glossdef>
  11508. <para role="glossdeffirst">
  11509. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11510. Specifies the system, including the architecture and the
  11511. operating system, for which the SDK will be built.
  11512. </para>
  11513. <para>
  11514. The OpenEmbedded build system automatically sets this
  11515. variable based on
  11516. <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
  11517. <link linkend='var-SDK_VENDOR'><filename>SDK_VENDOR</filename></link>,
  11518. and
  11519. <link linkend='var-SDK_OS'><filename>SDK_OS</filename></link>.
  11520. You do not need to set the <filename>SDK_SYS</filename>
  11521. variable yourself.
  11522. </para>
  11523. </glossdef>
  11524. </glossentry>
  11525. <glossentry id='var-SDK_TARGET_MANIFEST'><glossterm>SDK_TARGET_MANIFEST</glossterm>
  11526. <info>
  11527. SDK_TARGET_MANIFEST[doc] = "The manifest file for the target part of the SDK. This file lists all the installed packages that make up the target part of the SDK."
  11528. </info>
  11529. <glossdef>
  11530. <para role="glossdeffirst">
  11531. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11532. The manifest file for the target part of the SDK.
  11533. This file lists all the installed packages that make up
  11534. the target part of the SDK.
  11535. The file contains package information on a line-per-package
  11536. basis as follows:
  11537. <literallayout class='monospaced'>
  11538. <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
  11539. </literallayout>
  11540. </para>
  11541. <para>
  11542. The
  11543. <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
  11544. class defines the manifest file as follows:
  11545. <literallayout class='monospaced'>
  11546. SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
  11547. </literallayout>
  11548. The location is derived using the
  11549. <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
  11550. and
  11551. <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
  11552. variables.
  11553. </para>
  11554. </glossdef>
  11555. </glossentry>
  11556. <glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>
  11557. <info>
  11558. SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."
  11559. </info>
  11560. <glossdef>
  11561. <para role="glossdeffirst">
  11562. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11563. A list of targets to install from shared state as part of
  11564. the standard or extensible SDK installation.
  11565. The default value is "${PN}" (i.e. the image from which
  11566. the SDK is built).
  11567. </para>
  11568. <para>
  11569. The <filename>SDK_TARGETS</filename> variable is an
  11570. internal variable and typically would not be changed.
  11571. </para>
  11572. </glossdef>
  11573. </glossentry>
  11574. <glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>
  11575. <info>
  11576. SDK_TITLE[doc] = "Specifies a title to be printed when running the SDK installer."
  11577. </info>
  11578. <glossdef>
  11579. <para role="glossdeffirst">
  11580. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11581. Specifies a title to be printed when running the SDK
  11582. installer.
  11583. The <filename>SDK_TITLE</filename> variable defaults to
  11584. "<replaceable>distro</replaceable> SDK" for the standard
  11585. SDK and "<replaceable>distro</replaceable> Extensible SDK"
  11586. for the extensible SDK, where
  11587. <replaceable>distro</replaceable> is the first one of
  11588. <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
  11589. or
  11590. <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
  11591. that is set in your configuration.
  11592. </para>
  11593. </glossdef>
  11594. </glossentry>
  11595. <glossentry id='var-SDK_UPDATE_URL'><glossterm>SDK_UPDATE_URL</glossterm>
  11596. <info>
  11597. SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."
  11598. </info>
  11599. <glossdef>
  11600. <para role="glossdeffirst">
  11601. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11602. An optional URL for an update server for the extensible
  11603. SDK.
  11604. If set, the value is used as the default update server when
  11605. running <filename>devtool sdk-update</filename> within the
  11606. extensible SDK.
  11607. </para>
  11608. </glossdef>
  11609. </glossentry>
  11610. <glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>
  11611. <info>
  11612. SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."
  11613. </info>
  11614. <glossdef>
  11615. <para role="glossdeffirst">
  11616. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11617. Specifies the name of the SDK vendor.
  11618. </para>
  11619. </glossdef>
  11620. </glossentry>
  11621. <glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>
  11622. <info>
  11623. SDK_VERSION[doc] = "Specifies the version for the SDK."
  11624. </info>
  11625. <glossdef>
  11626. <para role="glossdeffirst">
  11627. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11628. Specifies the version of the SDK.
  11629. The distribution configuration file (e.g.
  11630. <filename>/meta-poky/conf/distro/poky.conf</filename>)
  11631. defines the <filename>SDK_VERSION</filename> as follows:
  11632. <literallayout class='monospaced'>
  11633. SDK_VERSION := "${@'${DISTRO_VERSION}'.replace('snapshot-${DATE}','snapshot')}"
  11634. </literallayout>
  11635. </para>
  11636. <para>
  11637. For additional information, see the
  11638. <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link>
  11639. and
  11640. <link linkend='var-DATE'><filename>DATE</filename></link>
  11641. variables.
  11642. </para>
  11643. </glossdef>
  11644. </glossentry>
  11645. <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
  11646. <info>
  11647. SDKIMAGE_FEATURES[doc] = "Equivalent to IMAGE_FEATURES. However, this variable applies to the SDK generated from an image using the command 'bitbake -c populate_sdk imagename'."
  11648. </info>
  11649. <glossdef>
  11650. <para role="glossdeffirst">
  11651. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11652. Equivalent to
  11653. <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
  11654. However, this variable applies to the SDK generated from an
  11655. image using the following command:
  11656. <literallayout class='monospaced'>
  11657. $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
  11658. </literallayout>
  11659. </para>
  11660. </glossdef>
  11661. </glossentry>
  11662. <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
  11663. <info>
  11664. SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK items."
  11665. </info>
  11666. <glossdef>
  11667. <para role="glossdeffirst">
  11668. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11669. The machine for which the SDK is built.
  11670. In other words, the SDK is built such that it
  11671. runs on the target you specify with the
  11672. <filename>SDKMACHINE</filename> value.
  11673. The value points to a corresponding
  11674. <filename>.conf</filename> file under
  11675. <filename>conf/machine-sdk/</filename>.
  11676. </para>
  11677. <para>
  11678. You can use "i686" and "x86_64" as possible values
  11679. for this variable. The variable defaults to "i686"
  11680. and is set in the local.conf file in the Build Directory.
  11681. <literallayout class='monospaced'>
  11682. SDKMACHINE ?= "i686"
  11683. </literallayout>
  11684. <note>
  11685. You cannot set the <filename>SDKMACHINE</filename>
  11686. variable in your distribution configuration file.
  11687. If you do, the configuration will not take affect.
  11688. </note>
  11689. </para>
  11690. </glossdef>
  11691. </glossentry>
  11692. <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
  11693. <info>
  11694. SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."
  11695. </info>
  11696. <glossdef>
  11697. <para role="glossdeffirst">
  11698. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11699. Defines the path offered to the user for installation
  11700. of the SDK that is generated by the OpenEmbedded build
  11701. system.
  11702. The path appears as the default location for installing
  11703. the SDK when you run the SDK's installation script.
  11704. You can override the offered path when you run the
  11705. script.
  11706. </para>
  11707. </glossdef>
  11708. </glossentry>
  11709. <glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>
  11710. <info>
  11711. SDKTARGETSYSROOT[doc] = "Full path to the sysroot used for cross-compilation within an SDK as it will be when installed into the default SDKPATH."
  11712. </info>
  11713. <glossdef>
  11714. <para role="glossdeffirst">
  11715. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11716. The full path to the sysroot used for cross-compilation
  11717. within an SDK as it will be when installed into the
  11718. default
  11719. <link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>.
  11720. </para>
  11721. </glossdef>
  11722. </glossentry>
  11723. <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
  11724. <info>
  11725. SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."
  11726. </info>
  11727. <glossdef>
  11728. <para role="glossdeffirst">
  11729. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11730. The section in which packages should be categorized.
  11731. Package management utilities can make use of this variable.
  11732. </para>
  11733. </glossdef>
  11734. </glossentry>
  11735. <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
  11736. <info>
  11737. SELECTED_OPTIMIZATION[doc] = "The variable takes the value of FULL_OPTIMIZATION unless DEBUG_BUILD = '1'. In this case, the value of DEBUG_OPTIMIZATION is used."
  11738. </info>
  11739. <glossdef>
  11740. <para role="glossdeffirst">
  11741. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11742. Specifies the optimization flags passed to the C compiler
  11743. when building for the target.
  11744. The flags are passed through the default value of the
  11745. <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
  11746. variable.
  11747. </para>
  11748. <para>
  11749. The <filename>SELECTED_OPTIMIZATION</filename> variable
  11750. takes the value of
  11751. <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
  11752. unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
  11753. If that is the case, the value of
  11754. <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
  11755. </para>
  11756. </glossdef>
  11757. </glossentry>
  11758. <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
  11759. <info>
  11760. SERIAL_CONSOLE[doc] = "Defines the serial consoles (TTYs) to enable using getty."
  11761. </info>
  11762. <glossdef>
  11763. <para role="glossdeffirst">
  11764. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11765. Defines a serial console (TTY) to enable using
  11766. <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
  11767. Provide a value that specifies the baud rate followed by
  11768. the TTY device name separated by a space.
  11769. You cannot specify more than one TTY device:
  11770. <literallayout class='monospaced'>
  11771. SERIAL_CONSOLE = "115200 ttyS0"
  11772. </literallayout>
  11773. <note>
  11774. The <filename>SERIAL_CONSOLE</filename> variable
  11775. is deprecated.
  11776. Please use the
  11777. <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
  11778. variable.
  11779. </note>
  11780. </para>
  11781. </glossdef>
  11782. </glossentry>
  11783. <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
  11784. <info>
  11785. SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."
  11786. </info>
  11787. <glossdef>
  11788. <para role="glossdeffirst">
  11789. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11790. Defines a serial console (TTY) to enable using
  11791. <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
  11792. Provide a value that specifies the baud rate followed by
  11793. the TTY device name separated by a semicolon.
  11794. Use spaces to separate multiple devices:
  11795. <literallayout class='monospaced'>
  11796. SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
  11797. </literallayout>
  11798. </para>
  11799. </glossdef>
  11800. </glossentry>
  11801. <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
  11802. <info>
  11803. SERIAL_CONSOLES_CHECK[doc] = "Selected SERIAL_CONSOLES to check against /proc/console before enabling using getty. Supported only by SysVinit."
  11804. </info>
  11805. <glossdef>
  11806. <para role="glossdeffirst">
  11807. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11808. Specifies serial consoles, which must be listed in
  11809. <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>,
  11810. to check against <filename>/proc/console</filename>
  11811. before enabling them using getty.
  11812. This variable allows aliasing in the format:
  11813. &lt;device&gt;:&lt;alias&gt;.
  11814. If a device was listed as "sclp_line0"
  11815. in <filename>/dev/</filename> and "ttyS0" was listed
  11816. in <filename>/proc/console</filename>, you would do the
  11817. following:
  11818. <literallayout class='monospaced'>
  11819. SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"
  11820. </literallayout>
  11821. This variable is currently only supported with SysVinit
  11822. (i.e. not with systemd).
  11823. </para>
  11824. </glossdef>
  11825. </glossentry>
  11826. <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
  11827. <info>
  11828. SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS[doc] = "A list of recipe dependencies that should not be used to determine signatures of tasks from one recipe when they depend on tasks from another recipe."
  11829. </info>
  11830. <glossdef>
  11831. <para role="glossdeffirst">
  11832. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11833. A list of recipe dependencies that should not be used to
  11834. determine signatures of tasks from one recipe when they
  11835. depend on tasks from another recipe.
  11836. For example:
  11837. <literallayout class='monospaced'>
  11838. SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
  11839. </literallayout>
  11840. </para>
  11841. <para>
  11842. In the previous example, <filename>intone</filename>
  11843. depends on <filename>mplayer2</filename>.
  11844. </para>
  11845. <para>
  11846. You can use the special token <filename>"*"</filename> on
  11847. the left-hand side of the dependency to match all
  11848. recipes except the one on the right-hand side.
  11849. Here is an example:
  11850. <literallayout class='monospaced'>
  11851. SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
  11852. </literallayout>
  11853. </para>
  11854. <para>
  11855. In the previous example, all recipes except
  11856. <filename>quilt-native</filename> ignore task
  11857. signatures from the <filename>quilt-native</filename>
  11858. recipe when determining their task signatures.
  11859. </para>
  11860. <para>
  11861. Use of this variable is one mechanism to remove dependencies
  11862. that affect task signatures and thus force rebuilds when a
  11863. recipe changes.
  11864. <note><title>Caution</title>
  11865. If you add an inappropriate dependency for a recipe
  11866. relationship, the software might break during
  11867. runtime if the interface of the second recipe was
  11868. changed after the first recipe had been built.
  11869. </note>
  11870. </para>
  11871. </glossdef>
  11872. </glossentry>
  11873. <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
  11874. <info>
  11875. SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."
  11876. </info>
  11877. <glossdef>
  11878. <para role="glossdeffirst">
  11879. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11880. A list of recipes that are completely stable and will
  11881. never change.
  11882. The ABI for the recipes in the list are presented by
  11883. output from the tasks run to build the recipe.
  11884. Use of this variable is one way to remove dependencies from
  11885. one recipe on another that affect task signatures and
  11886. thus force rebuilds when the recipe changes.
  11887. <note><title>Caution</title>
  11888. If you add an inappropriate variable to this list,
  11889. the software might break at runtime if the
  11890. interface of the recipe was changed after the other
  11891. had been built.
  11892. </note>
  11893. </para>
  11894. </glossdef>
  11895. </glossentry>
  11896. <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
  11897. <info>
  11898. SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."
  11899. </info>
  11900. <glossdef>
  11901. <para role="glossdeffirst">
  11902. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11903. Specifies the number of bits for the target system CPU.
  11904. The value should be either "32" or "64".
  11905. </para>
  11906. </glossdef>
  11907. </glossentry>
  11908. <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
  11909. <info>
  11910. SITEINFO_ENDIANNESS[doc] = "Specifies the endian byte order of the target system. The value should be either 'le' for 'little-endian' or 'be' for 'big-endian'."
  11911. </info>
  11912. <glossdef>
  11913. <para role="glossdeffirst">
  11914. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11915. Specifies the endian byte order of the target system.
  11916. The value should be either "le" for little-endian or "be" for big-endian.
  11917. </para>
  11918. </glossdef>
  11919. </glossentry>
  11920. <glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>
  11921. <info>
  11922. SKIP_FILEDEPS[doc] = "Enables you to remove all files from
  11923. the "Provides" section of an RPM package."
  11924. </info>
  11925. <glossdef>
  11926. <para role="glossdeffirst">
  11927. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11928. Enables removal of all files from the "Provides" section of
  11929. an RPM package.
  11930. Removal of these files is required for packages containing
  11931. prebuilt binaries and libraries such as
  11932. <filename>libstdc++</filename> and
  11933. <filename>glibc</filename>.
  11934. </para>
  11935. <para>
  11936. To enable file removal, set the variable to "1" in your
  11937. <filename>conf/local.conf</filename> configuration file
  11938. in your:
  11939. <link linkend='build-directory'>Build Directory</link>.
  11940. <literallayout class='monospaced'>
  11941. SKIP_FILEDEPS = "1"
  11942. </literallayout>
  11943. </para>
  11944. </glossdef>
  11945. </glossentry>
  11946. <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
  11947. <info>
  11948. SOC_FAMILY[doc] = "Groups together machines based upon the same family of SOC (System On Chip). You typically set this variable in a common .inc file that you include in the configuration files of all the machines."
  11949. </info>
  11950. <glossdef>
  11951. <para role="glossdeffirst">
  11952. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11953. Groups together machines based upon the same family
  11954. of SOC (System On Chip).
  11955. You typically set this variable in a common
  11956. <filename>.inc</filename> file that you include in the
  11957. configuration files of all the machines.
  11958. <note>
  11959. You must include
  11960. <filename>conf/machine/include/soc-family.inc</filename>
  11961. for this variable to appear in
  11962. <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
  11963. </note>
  11964. </para>
  11965. </glossdef>
  11966. </glossentry>
  11967. <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
  11968. <info>
  11969. SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."
  11970. </info>
  11971. <glossdef>
  11972. <para role="glossdeffirst">
  11973. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11974. Defines the suffix for shared libraries used on the
  11975. target platform.
  11976. By default, this suffix is ".so.*" for all Linux-based
  11977. systems and is defined in the
  11978. <filename>meta/conf/bitbake.conf</filename> configuration
  11979. file.
  11980. </para>
  11981. <para>
  11982. You will see this variable referenced in the default values
  11983. of <filename>FILES_${PN}</filename>.
  11984. </para>
  11985. </glossdef>
  11986. </glossentry>
  11987. <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
  11988. <info>
  11989. SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."
  11990. </info>
  11991. <glossdef>
  11992. <para role="glossdeffirst">
  11993. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  11994. Defines the suffix for the development symbolic link
  11995. (symlink) for shared libraries on the target platform.
  11996. By default, this suffix is ".so" for Linux-based
  11997. systems and is defined in the
  11998. <filename>meta/conf/bitbake.conf</filename> configuration
  11999. file.
  12000. </para>
  12001. <para>
  12002. You will see this variable referenced in the default values
  12003. of <filename>FILES_${PN}-dev</filename>.
  12004. </para>
  12005. </glossdef>
  12006. </glossentry>
  12007. <glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>
  12008. <info>
  12009. SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."
  12010. </info>
  12011. <glossdef>
  12012. <para role="glossdeffirst">
  12013. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12014. When you are fetching files to create a mirror of sources
  12015. (i.e. creating a source mirror), setting
  12016. <filename>SOURCE_MIRROR_FETCH</filename> to "1" in your
  12017. <filename>local.conf</filename> configuration file ensures
  12018. the source for all recipes are fetched regardless of
  12019. whether or not a recipe is compatible with the
  12020. configuration.
  12021. A recipe is considered incompatible with the currently
  12022. configured machine when either or both the
  12023. <link linkend='var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></link>
  12024. variable and
  12025. <link linkend='var-COMPATIBLE_HOST'><filename>COMPATIBLE_HOST</filename></link>
  12026. variables specify compatibility with a machine other
  12027. than that of the current machine or host.
  12028. <note><title>Warning</title>
  12029. Do not set the
  12030. <filename>SOURCE_MIRROR_FETCH</filename> variable
  12031. unless you are creating a source mirror.
  12032. In other words, do not set the variable during a
  12033. normal build.
  12034. </note>
  12035. </para>
  12036. </glossdef>
  12037. </glossentry>
  12038. <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
  12039. <info>
  12040. SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."
  12041. </info>
  12042. <glossdef>
  12043. <para role="glossdeffirst">
  12044. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12045. Defines your own
  12046. <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
  12047. from which to first fetch source before attempting to fetch
  12048. from the upstream specified in
  12049. <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
  12050. </para>
  12051. <para>
  12052. To use this variable, you must globally inherit the
  12053. <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
  12054. class and then provide the URL to your mirrors.
  12055. Here is the general syntax:
  12056. <literallayout class='monospaced'>
  12057. INHERIT += "own-mirrors"
  12058. SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"
  12059. </literallayout>
  12060. <note>
  12061. You can specify only a single URL in
  12062. <filename>SOURCE_MIRROR_URL</filename>.
  12063. </note>
  12064. </para>
  12065. </glossdef>
  12066. </glossentry>
  12067. <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
  12068. <info>
  12069. SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."
  12070. </info>
  12071. <glossdef>
  12072. <para role="glossdeffirst">
  12073. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12074. Maps commonly used license names to their SPDX counterparts
  12075. found in <filename>meta/files/common-licenses/</filename>.
  12076. For the default <filename>SPDXLICENSEMAP</filename>
  12077. mappings, see the
  12078. <filename>meta/conf/licenses.conf</filename> file.
  12079. </para>
  12080. <para>
  12081. For additional information, see the
  12082. <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
  12083. variable.
  12084. </para>
  12085. </glossdef>
  12086. </glossentry>
  12087. <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
  12088. <info>
  12089. SPECIAL_PKGSUFFIX[doc] = "A list of prefixes for PN used by the OpenEmbedded build system to create variants of recipes or packages. The list specifies the prefixes to strip off during certain circumstances such as the generation of the BPN variable."
  12090. </info>
  12091. <glossdef>
  12092. <para role="glossdeffirst">
  12093. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12094. A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
  12095. OpenEmbedded build system to create variants of recipes or packages.
  12096. The list specifies the prefixes to strip off during certain circumstances
  12097. such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
  12098. </para>
  12099. </glossdef>
  12100. </glossentry>
  12101. <glossentry id='var-SPL_BINARY'><glossterm>SPL_BINARY</glossterm>
  12102. <info>
  12103. SPL_BINARY[doc] = "The file type of the Secondary Program Loader (SPL)."
  12104. </info>
  12105. <glossdef>
  12106. <para role="glossdeffirst">
  12107. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12108. The file type for the Secondary Program Loader (SPL).
  12109. Some devices use an SPL from which to boot (e.g. the
  12110. BeagleBone development board).
  12111. For such cases, you can declare the file type of the
  12112. SPL binary in the <filename>u-boot.inc</filename> include
  12113. file, which is used in the U-Boot recipe.
  12114. </para>
  12115. <para>
  12116. The SPL file type is set to "null" by default in the
  12117. <filename>u-boot.inc</filename> file as follows:
  12118. <literallayout class='monospaced'>
  12119. # Some versions of u-boot build an SPL (Second Program Loader) image that
  12120. # should be packaged along with the u-boot binary as well as placed in the
  12121. # deploy directory. For those versions they can set the following variables
  12122. # to allow packaging the SPL.
  12123. SPL_BINARY ?= ""
  12124. SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
  12125. SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
  12126. SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
  12127. </literallayout>
  12128. The <filename>SPL_BINARY</filename> variable helps form
  12129. various <filename>SPL_*</filename> variables used by
  12130. the OpenEmbedded build system.
  12131. </para>
  12132. <para>
  12133. See the BeagleBone machine configuration example in the
  12134. "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
  12135. section in the Yocto Project Board Support Package
  12136. Developer's Guide for additional information.
  12137. </para>
  12138. </glossdef>
  12139. </glossentry>
  12140. <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
  12141. <info>
  12142. SRC_URI[doc] = "The list of source files - local or remote. This variable tells the OpenEmbedded build system what bits to pull in for the build and how to pull them in."
  12143. </info>
  12144. <glossdef>
  12145. <para role="glossdeffirst">
  12146. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12147. The list of source files - local or remote.
  12148. This variable tells the OpenEmbedded build system which bits
  12149. to pull in for the build and how to pull them in.
  12150. For example, if the recipe or append file only needs to
  12151. fetch a tarball from the Internet, the recipe or
  12152. append file uses a single <filename>SRC_URI</filename>
  12153. entry.
  12154. On the other hand, if the recipe or append file needs to
  12155. fetch a tarball, apply two patches, and include a custom
  12156. file, the recipe or append file would include four
  12157. instances of the variable.
  12158. </para>
  12159. <para>
  12160. The following list explains the available URI protocols.
  12161. URI protocols are highly dependent on particular BitBake
  12162. Fetcher submodules.
  12163. Depending on the fetcher BitBake uses, various URL
  12164. parameters are employed.
  12165. For specifics on the supported Fetchers, see the
  12166. "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
  12167. section in the BitBake User Manual.
  12168. <itemizedlist>
  12169. <listitem><para><emphasis><filename>file://</filename> -</emphasis>
  12170. Fetches files, which are usually files shipped with
  12171. the
  12172. <link linkend='metadata'>Metadata</link>,
  12173. from the local machine.
  12174. The path is relative to the
  12175. <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
  12176. variable.
  12177. Thus, the build system searches, in order, from the
  12178. following directories, which are assumed to be a
  12179. subdirectories of the directory in which the
  12180. recipe file (<filename>.bb</filename>) or
  12181. append file (<filename>.bbappend</filename>)
  12182. resides:
  12183. <itemizedlist>
  12184. <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
  12185. The base recipe name without any special
  12186. suffix or version numbers.
  12187. </para></listitem>
  12188. <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
  12189. <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
  12190. The base recipe name and version but without
  12191. any special package name suffix.
  12192. </para></listitem>
  12193. <listitem><para><emphasis>files -</emphasis>
  12194. Files within a directory, which is named
  12195. <filename>files</filename> and is also
  12196. alongside the recipe or append file.
  12197. </para></listitem>
  12198. </itemizedlist>
  12199. <note>
  12200. If you want the build system to pick up files
  12201. specified through a
  12202. <filename>SRC_URI</filename>
  12203. statement from your append file, you need to be
  12204. sure to extend the
  12205. <filename>FILESPATH</filename>
  12206. variable by also using the
  12207. <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
  12208. variable from within your append file.
  12209. </note>
  12210. </para></listitem>
  12211. <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
  12212. Bazaar revision control repository.</para></listitem>
  12213. <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
  12214. Git revision control repository.</para></listitem>
  12215. <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
  12216. an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
  12217. <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
  12218. a repo (Git) repository.</para></listitem>
  12219. <listitem><para><emphasis><filename>ccrc://</filename> -</emphasis>
  12220. Fetches files from a ClearCase repository.
  12221. </para></listitem>
  12222. <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
  12223. the Internet using <filename>http</filename>.</para></listitem>
  12224. <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
  12225. from the Internet using <filename>https</filename>.</para></listitem>
  12226. <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
  12227. from the Internet using <filename>ftp</filename>.</para></listitem>
  12228. <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
  12229. a CVS revision control repository.</para></listitem>
  12230. <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
  12231. a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
  12232. <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
  12233. a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
  12234. <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
  12235. a secure shell.</para></listitem>
  12236. <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
  12237. a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
  12238. </itemizedlist>
  12239. </para>
  12240. <para>
  12241. Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
  12242. Here are standard options:
  12243. <itemizedlist>
  12244. <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
  12245. the patch or not.
  12246. The default action is to apply the patch.</para></listitem>
  12247. <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
  12248. striplevel to use when applying the patch.
  12249. The default level is 1.</para></listitem>
  12250. <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
  12251. the directory in which the patch should be applied.
  12252. The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
  12253. </para></listitem>
  12254. </itemizedlist>
  12255. </para>
  12256. <para>
  12257. Here are options specific to recipes building code from a revision control system:
  12258. <itemizedlist>
  12259. <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
  12260. Apply the patch only if
  12261. <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
  12262. is equal to or greater than <filename>mindate</filename>.
  12263. </para></listitem>
  12264. <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
  12265. Apply the patch only if <filename>SRCDATE</filename>
  12266. is not later than <filename>mindate</filename>.
  12267. </para></listitem>
  12268. <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
  12269. Apply the patch only if <filename>SRCREV</filename>
  12270. is equal to or greater than <filename>minrev</filename>.
  12271. </para></listitem>
  12272. <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
  12273. Apply the patch only if <filename>SRCREV</filename>
  12274. is not later than <filename>maxrev</filename>.
  12275. </para></listitem>
  12276. <listitem><para><emphasis><filename>rev</filename> -</emphasis>
  12277. Apply the patch only if <filename>SRCREV</filename>
  12278. is equal to <filename>rev</filename>.
  12279. </para></listitem>
  12280. <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
  12281. Apply the patch only if <filename>SRCREV</filename>
  12282. is not equal to <filename>rev</filename>.
  12283. </para></listitem>
  12284. </itemizedlist>
  12285. </para>
  12286. <para>
  12287. Here are some additional options worth mentioning:
  12288. <itemizedlist>
  12289. <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
  12290. whether or not to unpack the file if it is an archive.
  12291. The default action is to unpack the file.</para></listitem>
  12292. <listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file
  12293. (or extracts its contents) into the specified
  12294. subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
  12295. when the Git fetcher is used.
  12296. </para></listitem>
  12297. <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
  12298. (or extracts its contents) into the specified
  12299. subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
  12300. when the local (<filename>file://</filename>)
  12301. fetcher is used.
  12302. </para></listitem>
  12303. <listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file
  12304. (or extracts its contents) into the specified
  12305. subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
  12306. when the CVS fetcher is used.
  12307. </para></listitem>
  12308. <listitem><para><emphasis><filename>subpath</filename> -</emphasis>
  12309. Limits the checkout to a specific subpath of the
  12310. tree when using the Git fetcher is used.
  12311. </para></listitem>
  12312. <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
  12313. name to be used for association with <filename>SRC_URI</filename> checksums
  12314. when you have more than one file specified in <filename>SRC_URI</filename>.
  12315. </para></listitem>
  12316. <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
  12317. the filename used when storing the downloaded file.</para></listitem>
  12318. </itemizedlist>
  12319. </para>
  12320. </glossdef>
  12321. </glossentry>
  12322. <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
  12323. <info>
  12324. SRC_URI_OVERRIDES_PACKAGE_ARCH[doc] = "By default, the OpenEmbedded build system automatically detects whether SRC_URI contains files that are machine-specific. If so, the build system automatically changes PACKAGE_ARCH. Setting this variable to '0' disables this behavior."
  12325. </info>
  12326. <glossdef>
  12327. <para role="glossdeffirst">
  12328. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12329. By default, the OpenEmbedded build system automatically detects whether
  12330. <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
  12331. contains files that are machine-specific.
  12332. If so, the build system automatically changes
  12333. <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
  12334. Setting this variable to "0" disables this behavior.
  12335. </para>
  12336. </glossdef>
  12337. </glossentry>
  12338. <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
  12339. <info>
  12340. SRCDATE[doc] = "The date of the source code used to build the package. This variable applies only if the source was fetched from a Source Code Manager (SCM)."
  12341. </info>
  12342. <glossdef>
  12343. <para role="glossdeffirst">
  12344. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12345. The date of the source code used to build the package.
  12346. This variable applies only if the source was fetched from a Source Code Manager (SCM).
  12347. </para>
  12348. </glossdef>
  12349. </glossentry>
  12350. <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
  12351. <info>
  12352. SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."
  12353. </info>
  12354. <glossdef>
  12355. <para role="glossdeffirst">
  12356. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12357. Returns the version string of the current package.
  12358. This string is used to help define the value of
  12359. <link linkend='var-PV'><filename>PV</filename></link>.
  12360. </para>
  12361. <para>
  12362. The <filename>SRCPV</filename> variable is defined in the
  12363. <filename>meta/conf/bitbake.conf</filename> configuration
  12364. file in the
  12365. <link linkend='source-directory'>Source Directory</link>
  12366. as follows:
  12367. <literallayout class='monospaced'>
  12368. SRCPV = "${@bb.fetch2.get_srcrev(d)}"
  12369. </literallayout>
  12370. </para>
  12371. <para>
  12372. Recipes that need to define <filename>PV</filename> do so
  12373. with the help of the <filename>SRCPV</filename>.
  12374. For example, the <filename>ofono</filename> recipe
  12375. (<filename>ofono_git.bb</filename>) located in
  12376. <filename>meta/recipes-connectivity</filename> in the
  12377. Source Directory defines <filename>PV</filename> as
  12378. follows:
  12379. <literallayout class='monospaced'>
  12380. PV = "0.12-git${SRCPV}"
  12381. </literallayout>
  12382. </para>
  12383. </glossdef>
  12384. </glossentry>
  12385. <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
  12386. <info>
  12387. SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial, and Bazaar only."
  12388. </info>
  12389. <glossdef>
  12390. <para role="glossdeffirst">
  12391. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12392. The revision of the source code used to build the package.
  12393. This variable applies to Subversion, Git, Mercurial, and
  12394. Bazaar only.
  12395. Note that if you want to build a fixed revision and you
  12396. want to avoid performing a query on the remote repository
  12397. every time BitBake parses your recipe, you should specify
  12398. a <filename>SRCREV</filename> that is a
  12399. full revision identifier and not just a tag.
  12400. <note>
  12401. For information on limitations when inheriting the
  12402. latest revision of software using
  12403. <filename>SRCREV</filename>, see the
  12404. <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
  12405. variable description and the
  12406. "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
  12407. section, which is in the Yocto Project Development
  12408. Tasks Manual.
  12409. </note>
  12410. </para>
  12411. </glossdef>
  12412. </glossentry>
  12413. <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
  12414. <info>
  12415. SSTATE_DIR[doc] = "The directory for the shared state cache."
  12416. </info>
  12417. <glossdef>
  12418. <para role="glossdeffirst">
  12419. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12420. The directory for the shared state cache.
  12421. </para>
  12422. </glossdef>
  12423. </glossentry>
  12424. <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>
  12425. <info>
  12426. SSTATE_MIRROR_ALLOW_NETWORK[doc] = "If set to "1", allows fetches from mirrors that are specified in SSTATE_MIRRORS to work even when fetching from the network is disabled by setting BB_NO_NETWORK to "1"."
  12427. </info>
  12428. <glossdef>
  12429. <para role="glossdeffirst">
  12430. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12431. If set to "1", allows fetches from
  12432. mirrors that are specified in
  12433. <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
  12434. to work even when fetching from the network is
  12435. disabled by setting <filename>BB_NO_NETWORK</filename>
  12436. to "1".
  12437. Using the
  12438. <filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>
  12439. variable is useful if you have set
  12440. <filename>SSTATE_MIRRORS</filename> to point to an
  12441. internal server for your shared state cache, but
  12442. you want to disable any other fetching from the network.
  12443. </para>
  12444. </glossdef>
  12445. </glossentry>
  12446. <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
  12447. <info>
  12448. SSTATE_MIRRORS[doc] = "Configures the OpenEmbedded build system to search other mirror locations for prebuilt cache data objects before building out the data. You can specify a filesystem directory or a remote URL such as HTTP or FTP."
  12449. </info>
  12450. <glossdef>
  12451. <para role="glossdeffirst">
  12452. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12453. Configures the OpenEmbedded build system to search other
  12454. mirror locations for prebuilt cache data objects before
  12455. building out the data.
  12456. This variable works like fetcher
  12457. <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
  12458. and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
  12459. and points to the cache locations to check for the shared
  12460. objects.
  12461. </para>
  12462. <para>
  12463. You can specify a filesystem directory or a remote URL such
  12464. as HTTP or FTP.
  12465. The locations you specify need to contain the shared state
  12466. cache (sstate-cache) results from previous builds.
  12467. The sstate-cache you point to can also be from builds on
  12468. other machines.
  12469. </para>
  12470. <para>
  12471. If a mirror uses the same structure as
  12472. <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
  12473. you need to add
  12474. "PATH" at the end as shown in the examples below.
  12475. The build system substitutes the correct path within the
  12476. directory structure.
  12477. <literallayout class='monospaced'>
  12478. SSTATE_MIRRORS ?= "\
  12479. file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \
  12480. file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH"
  12481. </literallayout>
  12482. </para>
  12483. </glossdef>
  12484. </glossentry>
  12485. <glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm>
  12486. <info>
  12487. SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths."
  12488. </info>
  12489. <glossdef>
  12490. <para role="glossdeffirst">
  12491. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12492. Controls the list of files the OpenEmbedded build system
  12493. scans for hardcoded installation paths. The variable uses a
  12494. space-separated list of filenames (not paths) with standard
  12495. wildcard characters allowed.
  12496. </para>
  12497. <para>
  12498. During a build, the OpenEmbedded build system creates a
  12499. shared state (sstate) object during the first stage of
  12500. preparing the sysroots. That object is scanned for
  12501. hardcoded paths for original installation locations.
  12502. The list of files that are scanned for paths is controlled
  12503. by the <filename>SSTATE_SCAN_FILES</filename> variable.
  12504. Typically, recipes add files they want to be scanned to the
  12505. value of <filename>SSTATE_SCAN_FILES</filename> rather than
  12506. the variable being comprehensively set. The
  12507. <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
  12508. class specifies the default list of files.
  12509. </para>
  12510. <para>
  12511. For details on the process, see the
  12512. <link linkend='ref-classes-staging'><filename>staging</filename></link>
  12513. class.
  12514. </para>
  12515. </glossdef>
  12516. </glossentry>
  12517. <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>
  12518. <info>
  12519. STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."
  12520. </info>
  12521. <glossdef>
  12522. <para role="glossdeffirst">
  12523. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12524. Specifies the path to the <filename>/lib</filename>
  12525. subdirectory of the sysroot directory for the
  12526. build host.
  12527. </para>
  12528. </glossdef>
  12529. </glossentry>
  12530. <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>
  12531. <info>
  12532. STAGING_BASELIBDIR[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
  12533. </info>
  12534. <glossdef>
  12535. <para role="glossdeffirst">
  12536. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12537. Specifies the path to the <filename>/lib</filename>
  12538. subdirectory of the sysroot directory for the target
  12539. for which the current recipe is being built
  12540. (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
  12541. </para>
  12542. </glossdef>
  12543. </glossentry>
  12544. <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>
  12545. <info>
  12546. STAGING_BINDIR[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
  12547. </info>
  12548. <glossdef>
  12549. <para role="glossdeffirst">
  12550. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12551. Specifies the path to the
  12552. <filename>/usr/bin</filename> subdirectory of the
  12553. sysroot directory for the target for which the current
  12554. recipe is being built
  12555. (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
  12556. </para>
  12557. </glossdef>
  12558. </glossentry>
  12559. <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm>
  12560. <info>
  12561. STAGING_BINDIR_CROSS[doc] = "Specifies the path to the directory containing binary configuration scripts. These scripts provide configuration information for other software that wants to make use of libraries or include files provided by the software associated with the script."
  12562. </info>
  12563. <glossdef>
  12564. <para role="glossdeffirst">
  12565. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12566. Specifies the path to the directory containing binary
  12567. configuration scripts.
  12568. These scripts provide configuration information for
  12569. other software that wants to make use of libraries or
  12570. include files provided by the software associated with
  12571. the script.
  12572. <note>
  12573. This style of build configuration has been largely
  12574. replaced by <filename>pkg-config</filename>.
  12575. Consequently, if <filename>pkg-config</filename>
  12576. is supported by the library to which you are linking,
  12577. it is recommended you use
  12578. <filename>pkg-config</filename> instead of a
  12579. provided configuration script.
  12580. </note>
  12581. </para>
  12582. </glossdef>
  12583. </glossentry>
  12584. <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>
  12585. <info>
  12586. STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."
  12587. </info>
  12588. <glossdef>
  12589. <para role="glossdeffirst">
  12590. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12591. Specifies the path to the
  12592. <filename>/usr/bin</filename> subdirectory of the
  12593. sysroot directory for the build host.
  12594. </para>
  12595. </glossdef>
  12596. </glossentry>
  12597. <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>
  12598. <info>
  12599. STAGING_DATADIR[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
  12600. </info>
  12601. <glossdef>
  12602. <para role="glossdeffirst">
  12603. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12604. Specifies the path to the <filename>/usr/share</filename>
  12605. subdirectory of the sysroot directory for the target
  12606. for which the current recipe is being built
  12607. (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
  12608. </para>
  12609. </glossdef>
  12610. </glossentry>
  12611. <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm>
  12612. <info>
  12613. STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."
  12614. </info>
  12615. <glossdef>
  12616. <para role="glossdeffirst">
  12617. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12618. Specifies the path to the <filename>/usr/share</filename>
  12619. subdirectory of the sysroot directory for the build host.
  12620. </para>
  12621. </glossdef>
  12622. </glossentry>
  12623. <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>
  12624. <info>
  12625. STAGING_DIR[doc] = "Specifies the path to the top-level sysroots directory (i.e. ${TMPDIR}/sysroots)."
  12626. </info>
  12627. <glossdef>
  12628. <para role="glossdeffirst">
  12629. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12630. Specifies the path to the top-level sysroots directory
  12631. (i.e.
  12632. <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots</filename>).
  12633. </para>
  12634. <para>
  12635. <filename>STAGING_DIR</filename> contains the directories
  12636. that are staged into the sysroot by the
  12637. <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
  12638. task.
  12639. See the
  12640. <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
  12641. variable and the
  12642. "<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files Between Recipes</ulink>"
  12643. section in the Yocto Project Development Tasks Manual
  12644. for more information.
  12645. <note>
  12646. Recipes should never write files directly under
  12647. the <filename>STAGING_DIR</filename> directory because
  12648. the OpenEmbedded build system
  12649. manages the directory automatically.
  12650. Instead, files should be installed to
  12651. <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
  12652. within your recipe's
  12653. <link linkend='ref-tasks-install'><filename>do_install</filename></link>
  12654. task and then the OpenEmbedded build system will
  12655. stage a subset of those files into the sysroot.
  12656. </note>
  12657. </para>
  12658. </glossdef>
  12659. </glossentry>
  12660. <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>
  12661. <info>
  12662. STAGING_DIR_HOST[doc] = "Specifies the path to the sysroot directory for the system that the component is built to run on."
  12663. </info>
  12664. <glossdef>
  12665. <para role="glossdeffirst">
  12666. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12667. Specifies the path to the sysroot directory for the system
  12668. that the component is built to run on (the system that hosts
  12669. the component).
  12670. For most recipes, this sysroot is the one that the recipe's
  12671. <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
  12672. task copies files into.
  12673. Exceptions include <filename>-native</filename> recipes,
  12674. where the <filename>do_populate_sysroot</filename> task
  12675. instead uses
  12676. <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>.
  12677. Depending on the type of recipe and the build target,
  12678. <filename>STAGING_DIR_HOST</filename> can have the
  12679. following values:
  12680. <itemizedlist>
  12681. <listitem><para>For recipes building for the target
  12682. machine, the value is
  12683. "${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".
  12684. </para></listitem>
  12685. <listitem><para>For native recipes building
  12686. for the build host, the value is empty given the
  12687. assumption that when building for the build host,
  12688. the build host's own directories should be used.
  12689. <note><para>
  12690. <filename>-native</filename> recipes are not
  12691. installed into host paths like such as
  12692. <filename>/usr</filename>.
  12693. Rather, these recipes are installed into
  12694. <filename>STAGING_DIR_NATIVE</filename>.
  12695. When compiling <filename>-native</filename>
  12696. recipes, standard build environment variables
  12697. such as
  12698. <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
  12699. and
  12700. <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
  12701. are set up so that both host paths and
  12702. <filename>STAGING_DIR_NATIVE</filename> are
  12703. searched for libraries and headers using, for
  12704. example, GCC's <filename>-isystem</filename>
  12705. option.</para>
  12706. <para>This emphasizes that the
  12707. <filename>STAGING_DIR*</filename> variables
  12708. should be viewed as input variables by tasks
  12709. such as
  12710. <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
  12711. <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
  12712. and
  12713. <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
  12714. Having the real system root correspond to
  12715. <filename>STAGING_DIR_HOST</filename> makes
  12716. conceptual sense for
  12717. <filename>-native</filename> recipes, as
  12718. they make use of host headers and libraries.
  12719. </para>
  12720. </note>
  12721. </para></listitem>
  12722. </itemizedlist>
  12723. </para>
  12724. </glossdef>
  12725. </glossentry>
  12726. <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>
  12727. <info>
  12728. STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory used when building components that run on the build host itself."
  12729. </info>
  12730. <glossdef>
  12731. <para role="glossdeffirst">
  12732. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12733. Specifies the path to the sysroot directory used when
  12734. building components that run on the build host itself.
  12735. </para>
  12736. </glossdef>
  12737. </glossentry>
  12738. <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>
  12739. <info>
  12740. STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot used for the system for which the component generates code."
  12741. </info>
  12742. <glossdef>
  12743. <para role="glossdeffirst">
  12744. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12745. Specifies the path to the sysroot used for the system for
  12746. which the component generates code.
  12747. For components that do not generate code, which is the
  12748. majority, <filename>STAGING_DIR_TARGET</filename> is set
  12749. to match
  12750. <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
  12751. </para>
  12752. <para>
  12753. Some recipes build binaries that can run on the target
  12754. system but those binaries in turn generate code for
  12755. another different system (e.g. cross-canadian recipes).
  12756. Using terminology from GNU, the primary system is referred
  12757. to as the "HOST" and the secondary, or different, system is
  12758. referred to as the "TARGET".
  12759. Thus, the binaries run on the "HOST" system
  12760. and generate binaries for the "TARGET" system.
  12761. The <filename>STAGING_DIR_HOST</filename> variable points
  12762. to the sysroot used for the "HOST" system, while
  12763. <filename>STAGING_DIR_TARGET</filename>
  12764. points to the sysroot used for the "TARGET" system.
  12765. </para>
  12766. </glossdef>
  12767. </glossentry>
  12768. <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>
  12769. <info>
  12770. STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."
  12771. </info>
  12772. <glossdef>
  12773. <para role="glossdeffirst">
  12774. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12775. Specifies the path to the <filename>/etc</filename>
  12776. subdirectory of the sysroot directory for the
  12777. build host.
  12778. </para>
  12779. </glossdef>
  12780. </glossentry>
  12781. <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>
  12782. <info>
  12783. STAGING_EXECPREFIXDIR[doc] = "Specifies the path to the /usr subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
  12784. </info>
  12785. <glossdef>
  12786. <para role="glossdeffirst">
  12787. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12788. Specifies the path to the <filename>/usr</filename>
  12789. subdirectory of the sysroot directory for the target
  12790. for which the current recipe is being built
  12791. (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
  12792. </para>
  12793. </glossdef>
  12794. </glossentry>
  12795. <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>
  12796. <info>
  12797. STAGING_INCDIR[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the target for which the current recipe being built (STAGING_DIR_HOST)."
  12798. </info>
  12799. <glossdef>
  12800. <para role="glossdeffirst">
  12801. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12802. Specifies the path to the
  12803. <filename>/usr/include</filename> subdirectory of the
  12804. sysroot directory for the target for which the current
  12805. recipe being built
  12806. (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
  12807. </para>
  12808. </glossdef>
  12809. </glossentry>
  12810. <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm>
  12811. <info>
  12812. STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."
  12813. </info>
  12814. <glossdef>
  12815. <para role="glossdeffirst">
  12816. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12817. Specifies the path to the <filename>/usr/include</filename>
  12818. subdirectory of the sysroot directory for the build host.
  12819. </para>
  12820. </glossdef>
  12821. </glossentry>
  12822. <glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>
  12823. <info>
  12824. STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."
  12825. </info>
  12826. <glossdef>
  12827. <para role="glossdeffirst">
  12828. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12829. Points to the directory containing the kernel build
  12830. artifacts.
  12831. Recipes building software that needs to access kernel
  12832. build artifacts
  12833. (e.g. <filename>systemtap-uprobes</filename>) can look in
  12834. the directory specified with the
  12835. <filename>STAGING_KERNEL_BUILDDIR</filename> variable to
  12836. find these artifacts after the kernel has been built.
  12837. </para>
  12838. </glossdef>
  12839. </glossentry>
  12840. <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
  12841. <info>
  12842. STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."
  12843. </info>
  12844. <glossdef>
  12845. <para role="glossdeffirst">
  12846. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12847. The directory with kernel headers that are required to build out-of-tree
  12848. modules.
  12849. </para>
  12850. </glossdef>
  12851. </glossentry>
  12852. <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm>
  12853. <info>
  12854. STAGING_LIBDIR[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
  12855. </info>
  12856. <glossdef>
  12857. <para role="glossdeffirst">
  12858. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12859. Specifies the path to the <filename>/usr/lib</filename>
  12860. subdirectory of the sysroot directory for the target for
  12861. which the current recipe is being built
  12862. (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
  12863. </para>
  12864. </glossdef>
  12865. </glossentry>
  12866. <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm>
  12867. <info>
  12868. STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."
  12869. </info>
  12870. <glossdef>
  12871. <para role="glossdeffirst">
  12872. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12873. Specifies the path to the <filename>/usr/lib</filename>
  12874. subdirectory of the sysroot directory for the build host.
  12875. </para>
  12876. </glossdef>
  12877. </glossentry>
  12878. <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
  12879. <info>
  12880. STAMP[doc] = "Specifies the base path used to create recipe stamp files. The path to an actual stamp file is constructed by evaluating this string and then appending additional information."
  12881. </info>
  12882. <glossdef>
  12883. <para role="glossdeffirst">
  12884. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12885. Specifies the base path used to create recipe stamp files.
  12886. The path to an actual stamp file is constructed by evaluating this
  12887. string and then appending additional information.
  12888. Currently, the default assignment for <filename>STAMP</filename>
  12889. as set in the <filename>meta/conf/bitbake.conf</filename> file
  12890. is:
  12891. <literallayout class='monospaced'>
  12892. STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
  12893. </literallayout>
  12894. </para>
  12895. <para>
  12896. For information on how BitBake uses stamp files to determine
  12897. if a task should be rerun, see the
  12898. "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
  12899. section in the Yocto Project Overview and Concepts Manual.
  12900. </para>
  12901. <para>
  12902. See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
  12903. <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
  12904. <link linkend='var-PN'><filename>PN</filename></link>,
  12905. <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
  12906. <link linkend='var-PV'><filename>PV</filename></link>, and
  12907. <link linkend='var-PR'><filename>PR</filename></link> for related variable
  12908. information.
  12909. </para>
  12910. </glossdef>
  12911. </glossentry>
  12912. <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
  12913. <info>
  12914. STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."
  12915. </info>
  12916. <glossdef>
  12917. <para role="glossdeffirst">
  12918. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12919. Specifies the base directory in which the OpenEmbedded
  12920. build system places stamps.
  12921. The default directory is
  12922. <filename>${TMPDIR}/stamps</filename>.
  12923. </para>
  12924. </glossdef>
  12925. </glossentry>
  12926. <glossentry id='var-STRIP'><glossterm>STRIP</glossterm>
  12927. <info>
  12928. STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."
  12929. </info>
  12930. <glossdef>
  12931. <para role="glossdeffirst">
  12932. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12933. The minimal command and arguments to run
  12934. <filename>strip</filename>, which is used to strip
  12935. symbols.
  12936. </para>
  12937. </glossdef>
  12938. </glossentry>
  12939. <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
  12940. <info>
  12941. SUMMARY[doc] = "The short (80 characters or less) summary of the binary package for packaging systems such as opkg, rpm, or dpkg. By default, SUMMARY is used to define the DESCRIPTION variable if DESCRIPTION is not set in the recipe."
  12942. </info>
  12943. <glossdef>
  12944. <para role="glossdeffirst">
  12945. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12946. The short (72 characters or less) summary of the binary package for packaging
  12947. systems such as <filename>opkg</filename>, <filename>rpm</filename>, or
  12948. <filename>dpkg</filename>.
  12949. By default, <filename>SUMMARY</filename> is used to define
  12950. the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
  12951. variable if <filename>DESCRIPTION</filename> is not set
  12952. in the recipe.
  12953. </para>
  12954. </glossdef>
  12955. </glossentry>
  12956. <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>
  12957. <info>
  12958. SVNDIR[doc] = "The directory where Subversion checkouts are stored."
  12959. </info>
  12960. <glossdef>
  12961. <para role="glossdeffirst">
  12962. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12963. The directory in which files checked out of a Subversion
  12964. system are stored.
  12965. </para>
  12966. </glossdef>
  12967. </glossentry>
  12968. <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
  12969. <info>
  12970. SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."
  12971. </info>
  12972. <glossdef>
  12973. <para role="glossdeffirst">
  12974. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12975. Specifies the kernel boot default console.
  12976. If you want to use a console other than the default,
  12977. set this variable in your recipe as follows where "X" is
  12978. the console number you want to use:
  12979. <literallayout class='monospaced'>
  12980. SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
  12981. </literallayout>
  12982. </para>
  12983. <para>
  12984. The
  12985. <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
  12986. class initially sets this variable to null but then checks
  12987. for a value later.
  12988. </para>
  12989. </glossdef>
  12990. </glossentry>
  12991. <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
  12992. <info>
  12993. SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."
  12994. </info>
  12995. <glossdef>
  12996. <para role="glossdeffirst">
  12997. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  12998. Lists additional options to add to the syslinux file.
  12999. You need to set this variable in your recipe.
  13000. If you want to list multiple options, separate the options
  13001. with a semicolon character (<filename>;</filename>).
  13002. </para>
  13003. <para>
  13004. The
  13005. <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
  13006. class uses this variable to create a set of options.
  13007. </para>
  13008. </glossdef>
  13009. </glossentry>
  13010. <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
  13011. <info>
  13012. SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."
  13013. </info>
  13014. <glossdef>
  13015. <para role="glossdeffirst">
  13016. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13017. Specifies the alternate serial port or turns it off.
  13018. To turn off serial, set this variable to an empty string
  13019. in your recipe.
  13020. The variable's default value is set in the
  13021. <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
  13022. as follows:
  13023. <literallayout class='monospaced'>
  13024. SYSLINUX_SERIAL ?= "0 115200"
  13025. </literallayout>
  13026. </para>
  13027. <para>
  13028. The class checks for and uses the variable as needed.
  13029. </para>
  13030. </glossdef>
  13031. </glossentry>
  13032. <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
  13033. <info>
  13034. SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you use the boot menu."
  13035. </info>
  13036. <glossdef>
  13037. <para role="glossdeffirst">
  13038. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13039. An <filename>.LSS</filename> file used as the background
  13040. for the VGA boot menu when you use the boot menu.
  13041. You need to set this variable in your recipe.
  13042. </para>
  13043. <para>
  13044. The
  13045. <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
  13046. class checks for this variable and if found, the
  13047. OpenEmbedded build system installs the splash screen.
  13048. </para>
  13049. </glossdef>
  13050. </glossentry>
  13051. <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
  13052. <info>
  13053. SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."
  13054. </info>
  13055. <glossdef>
  13056. <para role="glossdeffirst">
  13057. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13058. Specifies the alternate console=tty... kernel boot argument.
  13059. The variable's default value is set in the
  13060. <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
  13061. as follows:
  13062. <literallayout class='monospaced'>
  13063. SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
  13064. </literallayout>
  13065. </para>
  13066. <para>
  13067. The class checks for and uses the variable as needed.
  13068. </para>
  13069. </glossdef>
  13070. </glossentry>
  13071. <glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm>
  13072. <info>
  13073. SYSROOT_DESTDIR[doc] = "Points to the temporary work directory (default ${WORKDIR}/sysroot-destdir) where the files populated into the sysroot are assembled during the do_populate_sysroot task."
  13074. </info>
  13075. <glossdef>
  13076. <para role="glossdeffirst">
  13077. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13078. Points to the temporary directory under the work directory
  13079. (default
  13080. "<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destdir</filename>")
  13081. where the files populated into the sysroot are assembled
  13082. during the
  13083. <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
  13084. task.
  13085. </para>
  13086. </glossdef>
  13087. </glossentry>
  13088. <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>
  13089. <info>
  13090. SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."
  13091. </info>
  13092. <glossdef>
  13093. <para role="glossdeffirst">
  13094. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13095. Directories that are staged into the sysroot by the
  13096. <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
  13097. task.
  13098. By default, the following directories are staged:
  13099. <literallayout class='monospaced'>
  13100. SYSROOT_DIRS = " \
  13101. ${includedir} \
  13102. ${libdir} \
  13103. ${base_libdir} \
  13104. ${nonarch_base_libdir} \
  13105. ${datadir} \
  13106. "
  13107. </literallayout>
  13108. </para>
  13109. </glossdef>
  13110. </glossentry>
  13111. <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm>
  13112. <info>
  13113. SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."
  13114. </info>
  13115. <glossdef>
  13116. <para role="glossdeffirst">
  13117. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13118. Directories that are not staged into the sysroot by the
  13119. <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
  13120. task.
  13121. You can use this variable to exclude certain subdirectories
  13122. of directories listed in
  13123. <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
  13124. from staging.
  13125. By default, the following directories are not staged:
  13126. <literallayout class='monospaced'>
  13127. SYSROOT_DIRS_BLACKLIST = " \
  13128. ${mandir} \
  13129. ${docdir} \
  13130. ${infodir} \
  13131. ${datadir}/locale \
  13132. ${datadir}/applications \
  13133. ${datadir}/fonts \
  13134. ${datadir}/pixmaps \
  13135. "
  13136. </literallayout>
  13137. </para>
  13138. </glossdef>
  13139. </glossentry>
  13140. <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm>
  13141. <info>
  13142. SYSROOT_DIRS_NATIVE[doc] = "Extra directories staged into the sysroot by the do_populate_sysroot task for -native recipes, in addition to those specified in SYSROOT_DIRS."
  13143. </info>
  13144. <glossdef>
  13145. <para role="glossdeffirst">
  13146. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13147. Extra directories staged into the sysroot by the
  13148. <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
  13149. task for <filename>-native</filename> recipes, in addition
  13150. to those specified in
  13151. <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>.
  13152. By default, the following extra directories are staged:
  13153. <literallayout class='monospaced'>
  13154. SYSROOT_DIRS_NATIVE = " \
  13155. ${bindir} \
  13156. ${sbindir} \
  13157. ${base_bindir} \
  13158. ${base_sbindir} \
  13159. ${libexecdir} \
  13160. ${sysconfdir} \
  13161. ${localstatedir} \
  13162. "
  13163. </literallayout>
  13164. <note>
  13165. Programs built by <filename>-native</filename> recipes
  13166. run directly from the sysroot
  13167. (<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),
  13168. which is why additional directories containing program
  13169. executables and supporting files need to be staged.
  13170. </note>
  13171. </para>
  13172. </glossdef>
  13173. </glossentry>
  13174. <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
  13175. <info>
  13176. SYSROOT_PREPROCESS_FUNCS[doc] = "A list of functions to execute after files are staged into the sysroot. These functions are usually used to apply additional processing on the staged files, or to stage additional files."
  13177. </info>
  13178. <glossdef>
  13179. <para role="glossdeffirst">
  13180. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13181. A list of functions to execute after files are staged into
  13182. the sysroot.
  13183. These functions are usually used to apply additional
  13184. processing on the staged files, or to stage additional
  13185. files.
  13186. </para>
  13187. </glossdef>
  13188. </glossentry>
  13189. <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
  13190. <info>
  13191. SYSTEMD_AUTO_ENABLE[doc] = "For recipes that inherit the systemd class, this variable specifies whether the specified service in SYSTEMD_SERVICE should start automatically or not."
  13192. </info>
  13193. <glossdef>
  13194. <para role="glossdeffirst">
  13195. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13196. When inheriting the
  13197. <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
  13198. class, this variable specifies whether the specified service
  13199. in
  13200. <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
  13201. should start automatically or not.
  13202. By default, the service is enabled to automatically start
  13203. at boot time.
  13204. The default setting is in the
  13205. <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
  13206. class as follows:
  13207. <literallayout class='monospaced'>
  13208. SYSTEMD_AUTO_ENABLE ??= "enable"
  13209. </literallayout>
  13210. </para>
  13211. <para>
  13212. You can disable the service by setting the variable to
  13213. "disable".
  13214. </para>
  13215. </glossdef>
  13216. </glossentry>
  13217. <glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>
  13218. <info>
  13219. SYSTEMD_BOOT_CFG[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_CFG variable specifies the configuration file that should be used."
  13220. </info>
  13221. <glossdef>
  13222. <para role="glossdeffirst">
  13223. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13224. When
  13225. <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
  13226. is set to "systemd-boot", the
  13227. <filename>SYSTEMD_BOOT_CFG</filename> variable specifies the
  13228. configuration file that should be used.
  13229. By default, the
  13230. <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
  13231. class sets the <filename>SYSTEMD_BOOT_CFG</filename> as
  13232. follows:
  13233. <literallayout class='monospaced'>
  13234. SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"
  13235. </literallayout>
  13236. </para>
  13237. <para>
  13238. For information on Systemd-boot, see the
  13239. <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
  13240. </para>
  13241. </glossdef>
  13242. </glossentry>
  13243. <glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm>
  13244. <info>
  13245. SYSTEMD_BOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_ENTRIES variable specifies a list of entry files (*.conf) to install that contain one boot entry per file."
  13246. </info>
  13247. <glossdef>
  13248. <para role="glossdeffirst">
  13249. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13250. When
  13251. <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
  13252. is set to "systemd-boot", the
  13253. <filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies
  13254. a list of entry files
  13255. (<filename>*.conf</filename>) to install that contain
  13256. one boot entry per file.
  13257. By default, the
  13258. <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
  13259. class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as
  13260. follows:
  13261. <literallayout class='monospaced'>
  13262. SYSTEMD_BOOT_ENTRIES ?= ""
  13263. </literallayout>
  13264. </para>
  13265. <para>
  13266. For information on Systemd-boot, see the
  13267. <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
  13268. </para>
  13269. </glossdef>
  13270. </glossentry>
  13271. <glossentry id='var-SYSTEMD_BOOT_TIMEOUT'><glossterm>SYSTEMD_BOOT_TIMEOUT</glossterm>
  13272. <info>
  13273. SYSTEMD_BOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_TIMEOUT variable specifies the boot menu timeout in seconds."
  13274. </info>
  13275. <glossdef>
  13276. <para role="glossdeffirst">
  13277. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13278. When
  13279. <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
  13280. is set to "systemd-boot", the
  13281. <filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies
  13282. the boot menu timeout in seconds.
  13283. By default, the
  13284. <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
  13285. class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as
  13286. follows:
  13287. <literallayout class='monospaced'>
  13288. SYSTEMD_BOOT_TIMEOUT ?= "10"
  13289. </literallayout>
  13290. </para>
  13291. <para>
  13292. For information on Systemd-boot, see the
  13293. <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
  13294. </para>
  13295. </glossdef>
  13296. </glossentry>
  13297. <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
  13298. <info>
  13299. SYSTEMD_PACKAGES[doc] = "For recipes that inherit the systemd class, this variable locates the systemd unit files when they are not found in the main recipe's package."
  13300. </info>
  13301. <glossdef>
  13302. <para role="glossdeffirst">
  13303. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13304. When inheriting the
  13305. <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
  13306. class, this variable locates the systemd unit files when
  13307. they are not found in the main recipe's package.
  13308. By default, the
  13309. <filename>SYSTEMD_PACKAGES</filename> variable is set
  13310. such that the systemd unit files are assumed to reside in
  13311. the recipes main package:
  13312. <literallayout class='monospaced'>
  13313. SYSTEMD_PACKAGES ?= "${PN}"
  13314. </literallayout>
  13315. </para>
  13316. <para>
  13317. If these unit files are not in this recipe's main
  13318. package, you need to use
  13319. <filename>SYSTEMD_PACKAGES</filename> to list the package
  13320. or packages in which the build system can find the systemd
  13321. unit files.
  13322. </para>
  13323. </glossdef>
  13324. </glossentry>
  13325. <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
  13326. <info>
  13327. SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."
  13328. </info>
  13329. <glossdef>
  13330. <para role="glossdeffirst">
  13331. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13332. When inheriting the
  13333. <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
  13334. class, this variable specifies the systemd service name for
  13335. a package.
  13336. </para>
  13337. <para>
  13338. When you specify this file in your recipe, use a package
  13339. name override to indicate the package to which the value
  13340. applies.
  13341. Here is an example from the connman recipe:
  13342. <literallayout class='monospaced'>
  13343. SYSTEMD_SERVICE_${PN} = "connman.service"
  13344. </literallayout>
  13345. </para>
  13346. </glossdef>
  13347. </glossentry>
  13348. <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>
  13349. <info>
  13350. SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should run a getty, the default is '1'."
  13351. </info>
  13352. <glossdef>
  13353. <para role="glossdeffirst">
  13354. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13355. When using
  13356. <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
  13357. specifies a space-separated list of the virtual terminals
  13358. that should run a
  13359. <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
  13360. (allowing login), assuming
  13361. <link linkend='var-USE_VT'><filename>USE_VT</filename></link>
  13362. is not set to "0".
  13363. </para>
  13364. <para>
  13365. The default value for
  13366. <filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"
  13367. (i.e. only run a getty on the first virtual terminal).
  13368. </para>
  13369. </glossdef>
  13370. </glossentry>
  13371. </glossdiv>
  13372. <glossdiv id='var-glossary-t'><title>T</title>
  13373. <glossentry id='var-T'><glossterm>T</glossterm>
  13374. <info>
  13375. T[doc] = "This variable points to a directory were BitBake places temporary files, which consist mostly of task logs and scripts, when building a particular recipe."
  13376. </info>
  13377. <glossdef>
  13378. <para role="glossdeffirst">
  13379. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13380. This variable points to a directory were BitBake places
  13381. temporary files, which consist mostly of task logs and
  13382. scripts, when building a particular recipe.
  13383. The variable is typically set as follows:
  13384. <literallayout class='monospaced'>
  13385. T = "${WORKDIR}/temp"
  13386. </literallayout>
  13387. </para>
  13388. <para>
  13389. The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
  13390. is the directory into which BitBake unpacks and builds the
  13391. recipe.
  13392. The default <filename>bitbake.conf</filename> file sets this variable.</para>
  13393. <para>The <filename>T</filename> variable is not to be confused with
  13394. the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
  13395. which points to the root of the directory tree where BitBake
  13396. places the output of an entire build.
  13397. </para>
  13398. </glossdef>
  13399. </glossentry>
  13400. <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
  13401. <info>
  13402. TARGET_ARCH[doc] = "The architecture of the device being built. The OpenEmbedded build system supports the following architectures: arm, mips, ppc, x86, x86-64."
  13403. </info>
  13404. <glossdef>
  13405. <para role="glossdeffirst">
  13406. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13407. The target machine's architecture.
  13408. The OpenEmbedded build system supports many
  13409. architectures.
  13410. Here is an example list of architectures supported.
  13411. This list is by no means complete as the architecture
  13412. is configurable:
  13413. <literallayout class='monospaced'>
  13414. arm
  13415. i586
  13416. x86_64
  13417. powerpc
  13418. powerpc64
  13419. mips
  13420. mipsel
  13421. </literallayout>
  13422. </para>
  13423. <para>
  13424. For additional information on machine architectures, see
  13425. the
  13426. <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link>
  13427. variable.
  13428. </para>
  13429. </glossdef>
  13430. </glossentry>
  13431. <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm>
  13432. <info>
  13433. TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."
  13434. </info>
  13435. <glossdef>
  13436. <para role="glossdeffirst">
  13437. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13438. Specifies architecture-specific assembler flags for the
  13439. target system.
  13440. <filename>TARGET_AS_ARCH</filename> is initialized from
  13441. <link linkend='var-TUNE_ASARGS'><filename>TUNE_ASARGS</filename></link>
  13442. by default in the BitBake configuration file
  13443. (<filename>meta/conf/bitbake.conf</filename>):
  13444. <literallayout class='monospaced'>
  13445. TARGET_AS_ARCH = "${TUNE_ASARGS}"
  13446. </literallayout>
  13447. </para>
  13448. </glossdef>
  13449. </glossentry>
  13450. <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>
  13451. <info>
  13452. TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."
  13453. </info>
  13454. <glossdef>
  13455. <para role="glossdeffirst">
  13456. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13457. Specifies architecture-specific C compiler flags for the
  13458. target system.
  13459. <filename>TARGET_CC_ARCH</filename> is initialized from
  13460. <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
  13461. by default.
  13462. <note>
  13463. It is a common workaround to append
  13464. <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
  13465. to <filename>TARGET_CC_ARCH</filename>
  13466. in recipes that build software for the target that
  13467. would not otherwise respect the exported
  13468. <filename>LDFLAGS</filename> variable.
  13469. </note>
  13470. </para>
  13471. </glossdef>
  13472. </glossentry>
  13473. <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>
  13474. <info>
  13475. TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."
  13476. </info>
  13477. <glossdef>
  13478. <para role="glossdeffirst">
  13479. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13480. This is a specific kernel compiler flag for a CPU or
  13481. Application Binary Interface (ABI) tune.
  13482. The flag is used rarely and only for cases where a
  13483. userspace
  13484. <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
  13485. is not compatible with the kernel compilation.
  13486. The <filename>TARGET_CC_KERNEL_ARCH</filename> variable
  13487. allows the kernel (and associated modules) to use a
  13488. different configuration.
  13489. See the
  13490. <filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>
  13491. file in the
  13492. <link linkend='source-directory'>Source Directory</link>
  13493. for an example.
  13494. </para>
  13495. </glossdef>
  13496. </glossentry>
  13497. <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
  13498. <info>
  13499. TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."
  13500. </info>
  13501. <glossdef>
  13502. <para role="glossdeffirst">
  13503. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13504. Specifies the flags to pass to the C compiler when building
  13505. for the target.
  13506. When building in the target context,
  13507. <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
  13508. is set to the value of this variable by default.
  13509. </para>
  13510. <para>
  13511. Additionally, the SDK's environment setup script sets
  13512. the
  13513. <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
  13514. variable in the environment to the
  13515. <filename>TARGET_CFLAGS</filename> value so that
  13516. executables built using the SDK also have the flags
  13517. applied.
  13518. </para>
  13519. </glossdef>
  13520. </glossentry>
  13521. <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>
  13522. <info>
  13523. TARGET_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the target."
  13524. </info>
  13525. <glossdef>
  13526. <para role="glossdeffirst">
  13527. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13528. Specifies the flags to pass to the C pre-processor
  13529. (i.e. to both the C and the C++ compilers) when building
  13530. for the target.
  13531. When building in the target context,
  13532. <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
  13533. is set to the value of this variable by default.
  13534. </para>
  13535. <para>
  13536. Additionally, the SDK's environment setup script sets
  13537. the
  13538. <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
  13539. variable in the environment to the
  13540. <filename>TARGET_CPPFLAGS</filename> value so that
  13541. executables built using the SDK also have the flags
  13542. applied.
  13543. </para>
  13544. </glossdef>
  13545. </glossentry>
  13546. <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>
  13547. <info>
  13548. TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."
  13549. </info>
  13550. <glossdef>
  13551. <para role="glossdeffirst">
  13552. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13553. Specifies the flags to pass to the C++ compiler when
  13554. building for the target.
  13555. When building in the target context,
  13556. <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
  13557. is set to the value of this variable by default.
  13558. </para>
  13559. <para>
  13560. Additionally, the SDK's environment setup script sets
  13561. the
  13562. <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
  13563. variable in the environment to the
  13564. <filename>TARGET_CXXFLAGS</filename> value so that
  13565. executables built using the SDK also have the flags
  13566. applied.
  13567. </para>
  13568. </glossdef>
  13569. </glossentry>
  13570. <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
  13571. <info>
  13572. TARGET_FPU[doc] = "Specifies the method for handling FPU code. For FPU-less targets, which include most ARM CPUs, the variable must be set to 'soft'. If not, the kernel emulation gets used, which results in a performance penalty."
  13573. </info>
  13574. <glossdef>
  13575. <para role="glossdeffirst">
  13576. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13577. Specifies the method for handling FPU code.
  13578. For FPU-less targets, which include most ARM CPUs, the variable must be
  13579. set to "soft".
  13580. If not, the kernel emulation gets used, which results in a performance penalty.
  13581. </para>
  13582. </glossdef>
  13583. </glossentry>
  13584. <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm>
  13585. <info>
  13586. TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."
  13587. </info>
  13588. <glossdef>
  13589. <para role="glossdeffirst">
  13590. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13591. Specifies architecture-specific linker flags for the
  13592. target system.
  13593. <filename>TARGET_LD_ARCH</filename> is initialized from
  13594. <link linkend='var-TUNE_LDARGS'><filename>TUNE_LDARGS</filename></link>
  13595. by default in the BitBake configuration file
  13596. (<filename>meta/conf/bitbake.conf</filename>):
  13597. <literallayout class='monospaced'>
  13598. TARGET_LD_ARCH = "${TUNE_LDARGS}"
  13599. </literallayout>
  13600. </para>
  13601. </glossdef>
  13602. </glossentry>
  13603. <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>
  13604. <info>
  13605. TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."
  13606. </info>
  13607. <glossdef>
  13608. <para role="glossdeffirst">
  13609. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13610. Specifies the flags to pass to the linker when building
  13611. for the target.
  13612. When building in the target context,
  13613. <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
  13614. is set to the value of this variable by default.
  13615. </para>
  13616. <para>
  13617. Additionally, the SDK's environment setup script sets
  13618. the
  13619. <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
  13620. variable in the environment to the
  13621. <filename>TARGET_LDFLAGS</filename> value so that
  13622. executables built using the SDK also have the flags
  13623. applied.
  13624. </para>
  13625. </glossdef>
  13626. </glossentry>
  13627. <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
  13628. <info>
  13629. TARGET_OS[doc] = "Specifies the target's operating system."
  13630. </info>
  13631. <glossdef>
  13632. <para role="glossdeffirst">
  13633. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13634. Specifies the target's operating system.
  13635. The variable can be set to "linux" for <filename>glibc</filename>-based systems and
  13636. to "linux-musl" for <filename>musl</filename>.
  13637. For ARM/EABI targets, there are also "linux-gnueabi" and
  13638. "linux-musleabi" values possible.
  13639. </para>
  13640. </glossdef>
  13641. </glossentry>
  13642. <glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm>
  13643. <info>
  13644. TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."
  13645. </info>
  13646. <glossdef>
  13647. <para role="glossdeffirst">
  13648. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13649. Specifies the prefix used for the toolchain binary target
  13650. tools.
  13651. </para>
  13652. <para>
  13653. Depending on the type of recipe and the build target,
  13654. <filename>TARGET_PREFIX</filename> is set as follows:
  13655. <itemizedlist>
  13656. <listitem><para>
  13657. For recipes building for the target machine,
  13658. the value is
  13659. "${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".
  13660. </para></listitem>
  13661. <listitem><para>
  13662. For native recipes, the build system sets the
  13663. variable to the value of
  13664. <filename>BUILD_PREFIX</filename>.
  13665. </para></listitem>
  13666. <listitem><para>
  13667. For native SDK recipes
  13668. (<filename>nativesdk</filename>), the
  13669. build system sets the variable to the value of
  13670. <filename>SDK_PREFIX</filename>.
  13671. </para></listitem>
  13672. </itemizedlist>
  13673. </para>
  13674. </glossdef>
  13675. </glossentry>
  13676. <glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>
  13677. <info>
  13678. TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."
  13679. </info>
  13680. <glossdef>
  13681. <para role="glossdeffirst">
  13682. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13683. Specifies the system, including the architecture and the
  13684. operating system, for which the build is occurring in
  13685. the context of the current recipe.
  13686. </para>
  13687. <para>
  13688. The OpenEmbedded build system automatically sets this
  13689. variable based on
  13690. <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
  13691. <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>,
  13692. and
  13693. <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
  13694. variables.
  13695. <note>
  13696. You do not need to set the
  13697. <filename>TARGET_SYS</filename> variable yourself.
  13698. </note>
  13699. </para>
  13700. <para>
  13701. Consider these two examples:
  13702. <itemizedlist>
  13703. <listitem><para>
  13704. Given a native recipe on a 32-bit, x86 machine
  13705. running Linux, the value is "i686-linux".
  13706. </para></listitem>
  13707. <listitem><para>
  13708. Given a recipe being built for a little-endian,
  13709. MIPS target running Linux, the value might be
  13710. "mipsel-linux".
  13711. </para></listitem>
  13712. </itemizedlist>
  13713. </para>
  13714. </glossdef>
  13715. </glossentry>
  13716. <glossentry id='var-TARGET_VENDOR'><glossterm>TARGET_VENDOR</glossterm>
  13717. <info>
  13718. TARGET_VENDOR[doc] = "The name of the target vendor."
  13719. </info>
  13720. <glossdef>
  13721. <para role="glossdeffirst">
  13722. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13723. Specifies the name of the target vendor.
  13724. </para>
  13725. </glossdef>
  13726. </glossentry>
  13727. <glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>
  13728. <info>
  13729. TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."
  13730. </info>
  13731. <glossdef>
  13732. <para role="glossdeffirst">
  13733. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13734. Specifies a suffix to be appended onto the
  13735. <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
  13736. value.
  13737. The suffix identifies the <filename>libc</filename> variant
  13738. for building.
  13739. When you are building for multiple variants with the same
  13740. <link linkend='build-directory'>Build Directory</link>,
  13741. this mechanism ensures that output for different
  13742. <filename>libc</filename> variants is kept separate to
  13743. avoid potential conflicts.
  13744. </para>
  13745. <para>
  13746. In the <filename>defaultsetup.conf</filename> file, the
  13747. default value of <filename>TCLIBCAPPEND</filename> is
  13748. "-${TCLIBC}".
  13749. However, distros such as poky, which normally only support
  13750. one <filename>libc</filename> variant, set
  13751. <filename>TCLIBCAPPEND</filename> to "" in their distro
  13752. configuration file resulting in no suffix being applied.
  13753. </para>
  13754. </glossdef>
  13755. </glossentry>
  13756. <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
  13757. <info>
  13758. TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc' or 'musl'."
  13759. </info>
  13760. <glossdef>
  13761. <para role="glossdeffirst">
  13762. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13763. Specifies the GNU standard C library (<filename>libc</filename>)
  13764. variant to use during the build process.
  13765. This variable replaces <filename>POKYLIBC</filename>, which is no longer
  13766. supported.
  13767. </para>
  13768. <para>
  13769. You can select "glibc" or "musl".
  13770. </para>
  13771. </glossdef>
  13772. </glossentry>
  13773. <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
  13774. <info>
  13775. TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."
  13776. </info>
  13777. <glossdef>
  13778. <para role="glossdeffirst">
  13779. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13780. Specifies the toolchain selector.
  13781. <filename>TCMODE</filename> controls the characteristics
  13782. of the generated packages and images by telling the
  13783. OpenEmbedded build system which toolchain profile to use.
  13784. By default, the OpenEmbedded build system builds its own
  13785. internal toolchain.
  13786. The variable's default value is "default", which uses
  13787. that internal toolchain.
  13788. <note>
  13789. If <filename>TCMODE</filename> is set to a value
  13790. other than "default", then it is your responsibility
  13791. to ensure that the toolchain is compatible with the
  13792. default toolchain.
  13793. Using older or newer versions of these components
  13794. might cause build problems.
  13795. See the
  13796. <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
  13797. for the specific components with which the toolchain
  13798. must be compatible.
  13799. </note>
  13800. </para>
  13801. <para>
  13802. The <filename>TCMODE</filename> variable is similar to
  13803. <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
  13804. which controls the variant of the GNU standard C library
  13805. (<filename>libc</filename>) used during the build process:
  13806. <filename>glibc</filename> or <filename>musl</filename>.
  13807. </para>
  13808. <para>
  13809. With additional layers, it is possible to use a pre-compiled
  13810. external toolchain.
  13811. One example is the Sourcery G++ Toolchain.
  13812. The support for this toolchain resides in the separate
  13813. <trademark class='registered'>Mentor Graphics</trademark>
  13814. <filename>meta-sourcery</filename> layer at
  13815. <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
  13816. </para>
  13817. <para>
  13818. The layer's <filename>README</filename> file contains
  13819. information on how to use the Sourcery G++ Toolchain as
  13820. an external toolchain.
  13821. In summary, you must be sure to add the layer to your
  13822. <filename>bblayers.conf</filename> file in front of the
  13823. <filename>meta</filename> layer and then set the
  13824. <filename>EXTERNAL_TOOLCHAIN</filename>
  13825. variable in your <filename>local.conf</filename> file
  13826. to the location in which you installed the toolchain.
  13827. </para>
  13828. <para>
  13829. The fundamentals used for this example apply to any
  13830. external toolchain.
  13831. You can use <filename>meta-sourcery</filename> as a
  13832. template for adding support for other external toolchains.
  13833. </para>
  13834. </glossdef>
  13835. </glossentry>
  13836. <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
  13837. <info>
  13838. TEST_EXPORT_DIR[doc] = "The location the OpenEmbedded build system uses to export tests when the TEST_EXPORT_ONLY variable is set to "1"."
  13839. </info>
  13840. <glossdef>
  13841. <para role="glossdeffirst">
  13842. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13843. The location the OpenEmbedded build system uses to export
  13844. tests when the
  13845. <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
  13846. variable is set to "1".
  13847. </para>
  13848. <para>
  13849. The <filename>TEST_EXPORT_DIR</filename> variable defaults
  13850. to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
  13851. </para>
  13852. </glossdef>
  13853. </glossentry>
  13854. <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
  13855. <info>
  13856. TEST_EXPORT_ONLY[doc] = "Specifies to export the tests only. Set this variable to "1" if you do not want to run the tests but you want them to be exported in a manner that you to run them outside of the build system."
  13857. </info>
  13858. <glossdef>
  13859. <para role="glossdeffirst">
  13860. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13861. Specifies to export the tests only.
  13862. Set this variable to "1" if you do not want to run the
  13863. tests but you want them to be exported in a manner that
  13864. you to run them outside of the build system.
  13865. </para>
  13866. </glossdef>
  13867. </glossentry>
  13868. <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>
  13869. <info>
  13870. TEST_IMAGE[doc] = "Enables test booting of virtual machine images under the QEMU emulator after any root filesystems are created and runs tests against those images."
  13871. </info>
  13872. <glossdef>
  13873. <para role="glossdeffirst">
  13874. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13875. Automatically runs the series of automated tests for
  13876. images when an image is successfully built.
  13877. </para>
  13878. <para>
  13879. These tests are written in Python making use of the
  13880. <filename>unittest</filename> module, and the majority of
  13881. them run commands on the target system over
  13882. <filename>ssh</filename>.
  13883. You can set this variable to "1" in your
  13884. <filename>local.conf</filename> file in the
  13885. <link linkend='build-directory'>Build Directory</link>
  13886. to have the OpenEmbedded build system automatically run
  13887. these tests after an image successfully builds:
  13888. <literallayout class='monospaced'>
  13889. TEST_IMAGE = "1"
  13890. </literallayout>
  13891. For more information on enabling, running, and writing
  13892. these tests, see the
  13893. "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
  13894. section in the Yocto Project Development Tasks Manual and
  13895. the
  13896. "<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"
  13897. section.
  13898. </para>
  13899. </glossdef>
  13900. </glossentry>
  13901. <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
  13902. <info>
  13903. TEST_LOG_DIR[doc] = "Holds the SSH log and the boot log for QEMU machines. The TEST_LOG_DIR variable defaults to "${WORKDIR}/testimage"."
  13904. </info>
  13905. <glossdef>
  13906. <para role="glossdeffirst">
  13907. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13908. Holds the SSH log and the boot log for QEMU machines.
  13909. The <filename>TEST_LOG_DIR</filename> variable defaults
  13910. to <filename>"${WORKDIR}/testimage"</filename>.
  13911. <note>
  13912. Actual test results reside in the task log
  13913. (<filename>log.do_testimage</filename>), which is in
  13914. the <filename>${WORKDIR}/temp/</filename> directory.
  13915. </note>
  13916. </para>
  13917. </glossdef>
  13918. </glossentry>
  13919. <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>
  13920. <info>
  13921. TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"
  13922. </info>
  13923. <glossdef>
  13924. <para role="glossdeffirst">
  13925. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13926. For automated hardware testing, specifies the command to
  13927. use to control the power of the target machine under test.
  13928. Typically, this command would point to a script that
  13929. performs the appropriate action (e.g. interacting
  13930. with a web-enabled power strip).
  13931. The specified command should expect to receive as the last
  13932. argument "off", "on" or "cycle" specifying to power off,
  13933. on, or cycle (power off and then power on) the device,
  13934. respectively.
  13935. </para>
  13936. </glossdef>
  13937. </glossentry>
  13938. <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>TEST_POWERCONTROL_EXTRA_ARGS</glossterm>
  13939. <info>
  13940. TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"
  13941. </info>
  13942. <glossdef>
  13943. <para role="glossdeffirst">
  13944. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13945. For automated hardware testing, specifies additional
  13946. arguments to pass through to the command specified in
  13947. <link linkend='var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></link>.
  13948. Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
  13949. is optional.
  13950. You can use it if you wish, for example, to separate the
  13951. machine-specific and non-machine-specific parts of the
  13952. arguments.
  13953. </para>
  13954. </glossdef>
  13955. </glossentry>
  13956. <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
  13957. <info>
  13958. TEST_QEMUBOOT_TIMEOUT[doc] = "The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image."
  13959. </info>
  13960. <glossdef>
  13961. <para role="glossdeffirst">
  13962. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13963. The time in seconds allowed for an image to boot before
  13964. automated runtime tests begin to run against an
  13965. image.
  13966. The default timeout period to allow the boot process to
  13967. reach the login prompt is 500 seconds.
  13968. You can specify a different value in the
  13969. <filename>local.conf</filename> file.
  13970. </para>
  13971. <para>
  13972. For more information on testing images, see the
  13973. "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
  13974. section in the Yocto Project Development Tasks Manual.
  13975. </para>
  13976. </glossdef>
  13977. </glossentry>
  13978. <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>
  13979. <info>
  13980. TEST_SERIALCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to connect to the serial console of the target machine under test."
  13981. </info>
  13982. <glossdef>
  13983. <para role="glossdeffirst">
  13984. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  13985. For automated hardware testing, specifies the command
  13986. to use to connect to the serial console of the target
  13987. machine under test.
  13988. This command simply needs to connect to the serial console
  13989. and forward that connection to standard input and output
  13990. as any normal terminal program does.
  13991. </para>
  13992. <para>
  13993. For example, to use the Picocom terminal program on
  13994. serial device <filename>/dev/ttyUSB0</filename> at
  13995. 115200bps, you would set the variable as follows:
  13996. <literallayout class='monospaced'>
  13997. TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
  13998. </literallayout>
  13999. </para>
  14000. </glossdef>
  14001. </glossentry>
  14002. <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>TEST_SERIALCONTROL_EXTRA_ARGS</glossterm>
  14003. <info>
  14004. TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."
  14005. </info>
  14006. <glossdef>
  14007. <para role="glossdeffirst">
  14008. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14009. For automated hardware testing, specifies additional
  14010. arguments to pass through to the command specified in
  14011. <link linkend='var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></link>.
  14012. Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>
  14013. is optional.
  14014. You can use it if you wish, for example, to separate the
  14015. machine-specific and non-machine-specific parts of the
  14016. command.
  14017. </para>
  14018. </glossdef>
  14019. </glossentry>
  14020. <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
  14021. <info>
  14022. TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."
  14023. </info>
  14024. <glossdef>
  14025. <para role="glossdeffirst">
  14026. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14027. The IP address of the build machine (host machine).
  14028. This IP address is usually automatically detected.
  14029. However, if detection fails, this variable needs to be set
  14030. to the IP address of the build machine (i.e. where
  14031. the build is taking place).
  14032. <note>
  14033. The <filename>TEST_SERVER_IP</filename> variable
  14034. is only used for a small number of tests such as
  14035. the "dnf" test suite, which needs to download
  14036. packages from
  14037. <filename>WORKDIR/oe-rootfs-repo</filename>.
  14038. </note>
  14039. </para>
  14040. </glossdef>
  14041. </glossentry>
  14042. <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
  14043. <info>
  14044. TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."
  14045. </info>
  14046. <glossdef>
  14047. <para role="glossdeffirst">
  14048. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14049. Specifies the target controller to use when running tests
  14050. against a test image.
  14051. The default controller to use is "qemu":
  14052. <literallayout class='monospaced'>
  14053. TEST_TARGET = "qemu"
  14054. </literallayout>
  14055. </para>
  14056. <para>
  14057. A target controller is a class that defines how an
  14058. image gets deployed on a target and how a target is started.
  14059. A layer can extend the controllers by adding a module
  14060. in the layer's <filename>/lib/oeqa/controllers</filename>
  14061. directory and by inheriting the
  14062. <filename>BaseTarget</filename> class, which is an abstract
  14063. class that cannot be used as a value of
  14064. <filename>TEST_TARGET</filename>.
  14065. </para>
  14066. <para>
  14067. You can provide the following arguments with
  14068. <filename>TEST_TARGET</filename>:
  14069. <itemizedlist>
  14070. <listitem><para><emphasis>"qemu" and "QemuTarget":</emphasis>
  14071. Boots a QEMU image and runs the tests.
  14072. See the
  14073. "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
  14074. section in the Yocto Project Development Tasks
  14075. Manual for more information.
  14076. </para></listitem>
  14077. <listitem><para><emphasis>"simpleremote" and "SimpleRemoteTarget":</emphasis>
  14078. Runs the tests on target hardware that is already
  14079. up and running.
  14080. The hardware can be on the network or it can be
  14081. a device running an image on QEMU.
  14082. You must also set
  14083. <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
  14084. when you use "simpleremote" or "SimpleRemoteTarget".
  14085. <note>
  14086. This argument is defined in
  14087. <filename>meta/lib/oeqa/targetcontrol.py</filename>.
  14088. The small caps names are kept for compatibility
  14089. reasons.
  14090. </note>
  14091. </para></listitem>
  14092. <listitem><para><emphasis>"GummibootTarget":</emphasis>
  14093. Automatically deploys and runs tests on an
  14094. EFI-enabled machine that has a master image
  14095. installed.
  14096. <note>
  14097. This argument is defined in
  14098. <filename>meta/lib/oeqa/controllers/masterimage.py</filename>.
  14099. </note>
  14100. </para></listitem>
  14101. </itemizedlist>
  14102. </para>
  14103. <para>
  14104. For information on running tests on hardware, see the
  14105. "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
  14106. section in the Yocto Project Development Tasks Manual.
  14107. </para>
  14108. </glossdef>
  14109. </glossentry>
  14110. <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
  14111. <info>
  14112. TEST_TARGET_IP[doc] = "The IP address of your hardware under test."
  14113. </info>
  14114. <glossdef>
  14115. <para role="glossdeffirst">
  14116. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14117. The IP address of your hardware under test.
  14118. The <filename>TEST_TARGET_IP</filename> variable has no
  14119. effect when
  14120. <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
  14121. is set to "qemu".
  14122. </para>
  14123. <para>
  14124. When you specify the IP address, you can also include a
  14125. port.
  14126. Here is an example:
  14127. <literallayout class='monospaced'>
  14128. TEST_TARGET_IP = "192.168.1.4:2201"
  14129. </literallayout>
  14130. Specifying a port is useful when SSH is started on a
  14131. non-standard port or in cases when your hardware under test
  14132. is behind a firewall or network that is not directly
  14133. accessible from your host and you need to do port address
  14134. translation.
  14135. </para>
  14136. </glossdef>
  14137. </glossentry>
  14138. <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
  14139. <info>
  14140. TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."
  14141. </info>
  14142. <glossdef>
  14143. <para role="glossdeffirst">
  14144. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14145. An ordered list of tests (modules) to run against
  14146. an image when performing automated runtime testing.
  14147. </para>
  14148. <para>
  14149. The OpenEmbedded build system provides a core set of tests
  14150. that can be used against images.
  14151. <note>
  14152. Currently, there is only support for running these tests
  14153. under QEMU.
  14154. </note>
  14155. Tests include <filename>ping</filename>,
  14156. <filename>ssh</filename>, <filename>df</filename> among
  14157. others.
  14158. You can add your own tests to the list of tests by
  14159. appending <filename>TEST_SUITES</filename> as follows:
  14160. <literallayout class='monospaced'>
  14161. TEST_SUITES_append = " <replaceable>mytest</replaceable>"
  14162. </literallayout>
  14163. Alternatively, you can provide the "auto" option to
  14164. have all applicable tests run against the image.
  14165. <literallayout class='monospaced'>
  14166. TEST_SUITES_append = " auto"
  14167. </literallayout>
  14168. Using this option causes the build system to automatically
  14169. run tests that are applicable to the image.
  14170. Tests that are not applicable are skipped.
  14171. </para>
  14172. <para>
  14173. The order in which tests are run is important.
  14174. Tests that depend on another test must appear later in the
  14175. list than the test on which they depend.
  14176. For example, if you append the list of tests with two
  14177. tests (<filename>test_A</filename> and
  14178. <filename>test_B</filename>) where
  14179. <filename>test_B</filename> is dependent on
  14180. <filename>test_A</filename>, then you must order the tests
  14181. as follows:
  14182. <literallayout class='monospaced'>
  14183. TEST_SUITES = " test_A test_B"
  14184. </literallayout>
  14185. </para>
  14186. <para>
  14187. For more information on testing images, see the
  14188. "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
  14189. section in the Yocto Project Development Tasks Manual.
  14190. </para>
  14191. </glossdef>
  14192. </glossentry>
  14193. <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
  14194. <info>
  14195. THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."
  14196. </info>
  14197. <glossdef>
  14198. <para role="glossdeffirst">
  14199. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14200. The directory in which the file BitBake is currently
  14201. parsing is located.
  14202. Do not manually set this variable.
  14203. </para>
  14204. </glossdef>
  14205. </glossentry>
  14206. <glossentry id='var-TIME'><glossterm>TIME</glossterm>
  14207. <info>
  14208. TIME[doc] = "The time the build was started using HMS format."
  14209. </info>
  14210. <glossdef>
  14211. <para role="glossdeffirst">
  14212. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14213. The time the build was started.
  14214. Times appear using the hour, minute, and second (HMS)
  14215. format (e.g. "140159" for one minute and fifty-nine
  14216. seconds past 1400 hours).
  14217. </para>
  14218. </glossdef>
  14219. </glossentry>
  14220. <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
  14221. <info>
  14222. TMPDIR[doc] = "The temporary directory the OpenEmbedded build system uses when it does its work building images. By default, the TMPDIR variable is named tmp within the Build Directory."
  14223. </info>
  14224. <glossdef>
  14225. <para role="glossdeffirst">
  14226. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14227. This variable is the base directory the OpenEmbedded
  14228. build system uses for all build output and intermediate
  14229. files (other than the shared state cache).
  14230. By default, the <filename>TMPDIR</filename> variable points
  14231. to <filename>tmp</filename> within the
  14232. <link linkend='build-directory'>Build Directory</link>.
  14233. </para>
  14234. <para>
  14235. If you want to establish this directory in a location other
  14236. than the default, you can uncomment and edit the following
  14237. statement in the
  14238. <filename>conf/local.conf</filename> file in the
  14239. <link linkend='source-directory'>Source Directory</link>:
  14240. <literallayout class='monospaced'>
  14241. #TMPDIR = "${TOPDIR}/tmp"
  14242. </literallayout>
  14243. An example use for this scenario is to set
  14244. <filename>TMPDIR</filename> to a local disk, which does
  14245. not use NFS, while having the Build Directory use NFS.
  14246. </para>
  14247. <para>
  14248. The filesystem used by <filename>TMPDIR</filename> must
  14249. have standard filesystem semantics (i.e. mixed-case files
  14250. are unique, POSIX file locking, and persistent inodes).
  14251. Due to various issues with NFS and bugs in some
  14252. implementations, NFS does not meet this minimum
  14253. requirement.
  14254. Consequently, <filename>TMPDIR</filename> cannot be on
  14255. NFS.
  14256. </para>
  14257. </glossdef>
  14258. </glossentry>
  14259. <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
  14260. <info>
  14261. TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."
  14262. </info>
  14263. <glossdef>
  14264. <para role="glossdeffirst">
  14265. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14266. This variable lists packages the OpenEmbedded build system
  14267. uses when building an SDK, which contains a
  14268. cross-development environment.
  14269. The packages specified by this variable are part of the
  14270. toolchain set that runs on the
  14271. <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
  14272. and each package should usually have the prefix
  14273. <filename>nativesdk-</filename>.
  14274. For example, consider the following command when
  14275. building an SDK:
  14276. <literallayout class='monospaced'>
  14277. $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
  14278. </literallayout>
  14279. In this case, a default list of packages is set in this
  14280. variable, but you can add additional packages to the list.
  14281. See the
  14282. "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"
  14283. section in the Yocto Project Application Development and
  14284. the Extensible Software Development Kit (eSDK) manual
  14285. for more information.
  14286. </para>
  14287. <para>
  14288. For background information on cross-development toolchains
  14289. in the Yocto Project development environment, see the
  14290. "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
  14291. section in the Yocto Project Overview and Concepts Manual.
  14292. For information on setting up a cross-development
  14293. environment, see the
  14294. <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
  14295. manual.
  14296. </para>
  14297. </glossdef>
  14298. </glossentry>
  14299. <glossentry id='var-TOOLCHAIN_OUTPUTNAME'><glossterm>TOOLCHAIN_OUTPUTNAME</glossterm>
  14300. <info>
  14301. TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."
  14302. </info>
  14303. <glossdef>
  14304. <para role="glossdeffirst">
  14305. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14306. This variable defines the name used for the toolchain
  14307. output.
  14308. The
  14309. <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
  14310. class sets the
  14311. <filename>TOOLCHAIN_OUTPUTNAME</filename> variable as
  14312. follows:
  14313. <literallayout class='monospaced'>
  14314. TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
  14315. </literallayout>
  14316. See the
  14317. <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
  14318. and
  14319. <link linkend='var-SDK_VERSION'><filename>SDK_VERSION</filename></link>
  14320. variables for additional information.
  14321. </para>
  14322. </glossdef>
  14323. </glossentry>
  14324. <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
  14325. <info>
  14326. TOOLCHAIN_TARGET_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when it creates the target part of an SDK, which includes libraries and headers."
  14327. </info>
  14328. <glossdef>
  14329. <para role="glossdeffirst">
  14330. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14331. This variable lists packages the OpenEmbedded build system
  14332. uses when it creates the target part of an SDK
  14333. (i.e. the part built for the target hardware), which
  14334. includes libraries and headers.
  14335. Use this variable to add individual packages to the
  14336. part of the SDK that runs on the target.
  14337. See the
  14338. "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"
  14339. section in the Yocto Project Application Development and
  14340. the Extensible Software Development Kit (eSDK) manual for
  14341. more information.
  14342. </para>
  14343. <para>
  14344. For background information on cross-development toolchains
  14345. in the Yocto Project development environment, see the
  14346. "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
  14347. section in the Yocto Project Overview and Concepts Manual.
  14348. For information on setting up a cross-development
  14349. environment, see the
  14350. <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
  14351. manual.
  14352. </para>
  14353. </glossdef>
  14354. </glossentry>
  14355. <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
  14356. <info>
  14357. TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."
  14358. </info>
  14359. <glossdef>
  14360. <para role="glossdeffirst">
  14361. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14362. The top-level
  14363. <link linkend='build-directory'>Build Directory</link>.
  14364. BitBake automatically sets this variable when you
  14365. initialize your build environment using
  14366. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
  14367. </para>
  14368. </glossdef>
  14369. </glossentry>
  14370. <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
  14371. <info>
  14372. TRANSLATED_TARGET_ARCH[doc] = "A sanitized version of TARGET_ARCH. This variable is used where the architecture is needed in a value where underscores are not allowed."
  14373. </info>
  14374. <glossdef>
  14375. <para role="glossdeffirst">
  14376. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14377. A sanitized version of
  14378. <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
  14379. This variable is used where the architecture is needed in
  14380. a value where underscores are not allowed, for example
  14381. within package filenames.
  14382. In this case, dash characters replace any underscore
  14383. characters used in TARGET_ARCH.
  14384. </para>
  14385. <para>
  14386. Do not edit this variable.
  14387. </para>
  14388. </glossdef>
  14389. </glossentry>
  14390. <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm>
  14391. <info>
  14392. TUNE_ARCH[doc] = "The GNU canonical architecture for a specific architecture (i.e. arm, armeb, mips, mips64, and so forth)."
  14393. </info>
  14394. <glossdef>
  14395. <para role="glossdeffirst">
  14396. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14397. The GNU canonical architecture for a specific architecture
  14398. (i.e. <filename>arm</filename>,
  14399. <filename>armeb</filename>,
  14400. <filename>mips</filename>,
  14401. <filename>mips64</filename>, and so forth).
  14402. BitBake uses this value to setup configuration.
  14403. </para>
  14404. <para>
  14405. <filename>TUNE_ARCH</filename> definitions are specific to
  14406. a given architecture.
  14407. The definitions can be a single static definition, or
  14408. can be dynamically adjusted.
  14409. You can see details for a given CPU family by looking at
  14410. the architecture's <filename>README</filename> file.
  14411. For example, the
  14412. <filename>meta/conf/machine/include/mips/README</filename>
  14413. file in the
  14414. <link linkend='source-directory'>Source Directory</link>
  14415. provides information for <filename>TUNE_ARCH</filename>
  14416. specific to the <filename>mips</filename> architecture.
  14417. </para>
  14418. <para>
  14419. <filename>TUNE_ARCH</filename> is tied closely to
  14420. <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
  14421. which defines the target machine's architecture.
  14422. The BitBake configuration file
  14423. (<filename>meta/conf/bitbake.conf</filename>) sets
  14424. <filename>TARGET_ARCH</filename> as follows:
  14425. <literallayout class='monospaced'>
  14426. TARGET_ARCH = "${TUNE_ARCH}"
  14427. </literallayout>
  14428. </para>
  14429. <para>
  14430. The following list, which is by no means complete since
  14431. architectures are configurable, shows supported machine
  14432. architectures:
  14433. <literallayout class='monospaced'>
  14434. arm
  14435. i586
  14436. x86_64
  14437. powerpc
  14438. powerpc64
  14439. mips
  14440. mipsel
  14441. </literallayout>
  14442. </para>
  14443. </glossdef>
  14444. </glossentry>
  14445. <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm>
  14446. <info>
  14447. TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."
  14448. </info>
  14449. <glossdef>
  14450. <para role="glossdeffirst">
  14451. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14452. Specifies architecture-specific assembler flags for
  14453. the target system.
  14454. The set of flags is based on the selected tune features.
  14455. <filename>TUNE_ASARGS</filename> is set using
  14456. the tune include files, which are typically under
  14457. <filename>meta/conf/machine/include/</filename> and are
  14458. influenced through
  14459. <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
  14460. For example, the
  14461. <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
  14462. file defines the flags for the x86 architecture as follows:
  14463. <literallayout class='monospaced'>
  14464. TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
  14465. </literallayout>
  14466. <note>
  14467. Board Support Packages (BSPs) select the tune.
  14468. The selected tune, in turn, affects the tune variables
  14469. themselves (i.e. the tune can supply its own
  14470. set of flags).
  14471. </note>
  14472. </para>
  14473. </glossdef>
  14474. </glossentry>
  14475. <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm>
  14476. <info>
  14477. TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."
  14478. </info>
  14479. <glossdef>
  14480. <para role="glossdeffirst">
  14481. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14482. Specifies architecture-specific C compiler flags for
  14483. the target system.
  14484. The set of flags is based on the selected tune features.
  14485. <filename>TUNE_CCARGS</filename> is set using
  14486. the tune include files, which are typically under
  14487. <filename>meta/conf/machine/include/</filename> and are
  14488. influenced through
  14489. <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
  14490. <note>
  14491. Board Support Packages (BSPs) select the tune.
  14492. The selected tune, in turn, affects the tune variables
  14493. themselves (i.e. the tune can supply its own
  14494. set of flags).
  14495. </note>
  14496. </para>
  14497. </glossdef>
  14498. </glossentry>
  14499. <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm>
  14500. <info>
  14501. TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."
  14502. </info>
  14503. <glossdef>
  14504. <para role="glossdeffirst">
  14505. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14506. Specifies architecture-specific linker flags for
  14507. the target system.
  14508. The set of flags is based on the selected tune features.
  14509. <filename>TUNE_LDARGS</filename> is set using
  14510. the tune include files, which are typically under
  14511. <filename>meta/conf/machine/include/</filename> and are
  14512. influenced through
  14513. <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
  14514. For example, the
  14515. <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
  14516. file defines the flags for the x86 architecture as follows:
  14517. <literallayout class='monospaced'>
  14518. TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
  14519. </literallayout>
  14520. <note>
  14521. Board Support Packages (BSPs) select the tune.
  14522. The selected tune, in turn, affects the tune variables
  14523. themselves (i.e. the tune can supply its own
  14524. set of flags).
  14525. </note>
  14526. </para>
  14527. </glossdef>
  14528. </glossentry>
  14529. <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm>
  14530. <info>
  14531. TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."
  14532. </info>
  14533. <glossdef>
  14534. <para role="glossdeffirst">
  14535. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14536. Features used to "tune" a compiler for optimal use
  14537. given a specific processor.
  14538. The features are defined within the tune files and allow
  14539. arguments (i.e. <filename>TUNE_*ARGS</filename>) to be
  14540. dynamically generated based on the features.
  14541. </para>
  14542. <para>
  14543. The OpenEmbedded build system verifies the features
  14544. to be sure they are not conflicting and that they are
  14545. supported.
  14546. </para>
  14547. <para>
  14548. The BitBake configuration file
  14549. (<filename>meta/conf/bitbake.conf</filename>) defines
  14550. <filename>TUNE_FEATURES</filename> as follows:
  14551. <literallayout class='monospaced'>
  14552. TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"
  14553. </literallayout>
  14554. See the
  14555. <link linkend='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></link>
  14556. variable for more information.
  14557. </para>
  14558. </glossdef>
  14559. </glossentry>
  14560. <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
  14561. <info>
  14562. TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."
  14563. </info>
  14564. <glossdef>
  14565. <para role="glossdeffirst">
  14566. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14567. The package architecture understood by the packaging
  14568. system to define the architecture, ABI, and tuning of
  14569. output packages.
  14570. The specific tune is defined using the "_tune" override
  14571. as follows:
  14572. <literallayout class='monospaced'>
  14573. TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"
  14574. </literallayout>
  14575. </para>
  14576. <para>
  14577. These tune-specific package architectures are defined in
  14578. the machine include files.
  14579. Here is an example of the "core2-32" tuning as used
  14580. in the
  14581. <filename>meta/conf/machine/include/tune-core2.inc</filename>
  14582. file:
  14583. <literallayout class='monospaced'>
  14584. TUNE_PKGARCH_tune-core2-32 = "core2-32"
  14585. </literallayout>
  14586. </para>
  14587. </glossdef>
  14588. </glossentry>
  14589. <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>
  14590. <info>
  14591. TUNEABI[doc] = "An underlying ABI used by a particular tuning in a given toolchain layer. This feature allows providers using prebuilt libraries to check compatibility of a tuning against their selection of libraries."
  14592. </info>
  14593. <glossdef>
  14594. <para role="glossdeffirst">
  14595. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14596. An underlying Application Binary Interface (ABI) used by
  14597. a particular tuning in a given toolchain layer.
  14598. Providers that use prebuilt libraries can use the
  14599. <filename>TUNEABI</filename>,
  14600. <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
  14601. and
  14602. <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
  14603. variables to check compatibility of tunings against their
  14604. selection of libraries.
  14605. </para>
  14606. <para>
  14607. If <filename>TUNEABI</filename> is undefined, then every
  14608. tuning is allowed.
  14609. See the
  14610. <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
  14611. class to see how the variable is used.
  14612. </para>
  14613. </glossdef>
  14614. </glossentry>
  14615. <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm>
  14616. <info>
  14617. TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."
  14618. </info>
  14619. <glossdef>
  14620. <para role="glossdeffirst">
  14621. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14622. If set, the OpenEmbedded system ignores the
  14623. <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
  14624. variable.
  14625. Providers that use prebuilt libraries can use the
  14626. <filename>TUNEABI_OVERRIDE</filename>,
  14627. <filename>TUNEABI_WHITELIST</filename>,
  14628. and
  14629. <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
  14630. variables to check compatibility of a tuning against their
  14631. selection of libraries.
  14632. </para>
  14633. <para>
  14634. See the
  14635. <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
  14636. class to see how the variable is used.
  14637. </para>
  14638. </glossdef>
  14639. </glossentry>
  14640. <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm>
  14641. <info>
  14642. TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."
  14643. </info>
  14644. <glossdef>
  14645. <para role="glossdeffirst">
  14646. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14647. A whitelist of permissible
  14648. <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
  14649. values.
  14650. If <filename>TUNEABI_WHITELIST</filename> is not set,
  14651. all tunes are allowed.
  14652. Providers that use prebuilt libraries can use the
  14653. <filename>TUNEABI_WHITELIST</filename>,
  14654. <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
  14655. and <filename>TUNEABI</filename> variables to check
  14656. compatibility of a tuning against their selection of
  14657. libraries.
  14658. </para>
  14659. <para>
  14660. See the
  14661. <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
  14662. class to see how the variable is used.
  14663. </para>
  14664. </glossdef>
  14665. </glossentry>
  14666. <glossentry id='var-TUNECONFLICTS'><glossterm>TUNECONFLICTS[<replaceable>feature</replaceable>]</glossterm>
  14667. <info>
  14668. TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."
  14669. </info>
  14670. <glossdef>
  14671. <para role="glossdeffirst">
  14672. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14673. Specifies CPU or Application Binary Interface (ABI)
  14674. tuning features that conflict with <replaceable>feature</replaceable>.
  14675. </para>
  14676. <para>
  14677. Known tuning conflicts are specified in the machine include
  14678. files in the
  14679. <link linkend='source-directory'>Source Directory</link>.
  14680. Here is an example from the
  14681. <filename>meta/conf/machine/include/mips/arch-mips.inc</filename>
  14682. include file that lists the "o32" and "n64" features as
  14683. conflicting with the "n32" feature:
  14684. <literallayout class='monospaced'>
  14685. TUNECONFLICTS[n32] = "o32 n64"
  14686. </literallayout>
  14687. </para>
  14688. </glossdef>
  14689. </glossentry>
  14690. <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>
  14691. <info>
  14692. TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."
  14693. </info>
  14694. <glossdef>
  14695. <para role="glossdeffirst">
  14696. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14697. Specifies a valid CPU or Application Binary Interface (ABI)
  14698. tuning feature.
  14699. The specified feature is stored as a flag.
  14700. Valid features are specified in the machine include files
  14701. (e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).
  14702. Here is an example from that file:
  14703. <literallayout class='monospaced'>
  14704. TUNEVALID[bigendian] = "Enable big-endian mode."
  14705. </literallayout>
  14706. </para>
  14707. <para>
  14708. See the machine include files in the
  14709. <link linkend='source-directory'>Source Directory</link>
  14710. for these features.
  14711. </para>
  14712. </glossdef>
  14713. </glossentry>
  14714. </glossdiv>
  14715. <glossdiv id='var-glossary-u'><title>U</title>
  14716. <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
  14717. <info>
  14718. UBOOT_CONFIG[doc] = "Configures the UBOOT_MACHINE and can also define IMAGE_FSTYPES for individual cases."
  14719. </info>
  14720. <glossdef>
  14721. <para role="glossdeffirst">
  14722. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14723. Configures the
  14724. <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
  14725. and can also define
  14726. <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
  14727. for individual cases.
  14728. </para>
  14729. <para>
  14730. Following is an example from the
  14731. <filename>meta-fsl-arm</filename> layer.
  14732. <literallayout class='monospaced'>
  14733. UBOOT_CONFIG ??= "sd"
  14734. UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
  14735. UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
  14736. UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
  14737. UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
  14738. </literallayout>
  14739. In this example, "sd" is selected as the configuration
  14740. of the possible four for the
  14741. <filename>UBOOT_MACHINE</filename>.
  14742. The "sd" configuration defines "mx6qsabreauto_config"
  14743. as the value for <filename>UBOOT_MACHINE</filename>, while
  14744. the "sdcard" specifies the
  14745. <filename>IMAGE_FSTYPES</filename> to use for the U-boot
  14746. image.
  14747. </para>
  14748. <para>
  14749. For more information on how the
  14750. <filename>UBOOT_CONFIG</filename> is handled, see the
  14751. <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
  14752. class.
  14753. </para>
  14754. </glossdef>
  14755. </glossentry>
  14756. <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
  14757. <info>
  14758. UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."
  14759. </info>
  14760. <glossdef>
  14761. <para role="glossdeffirst">
  14762. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14763. Specifies the entry point for the U-Boot image.
  14764. During U-Boot image creation, the
  14765. <filename>UBOOT_ENTRYPOINT</filename> variable is passed
  14766. as a command-line parameter to the
  14767. <filename>uboot-mkimage</filename> utility.
  14768. </para>
  14769. </glossdef>
  14770. </glossentry>
  14771. <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
  14772. <info>
  14773. UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."
  14774. </info>
  14775. <glossdef>
  14776. <para role="glossdeffirst">
  14777. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14778. Specifies the load address for the U-Boot image.
  14779. During U-Boot image creation, the
  14780. <filename>UBOOT_LOADADDRESS</filename> variable is passed
  14781. as a command-line parameter to the
  14782. <filename>uboot-mkimage</filename> utility.
  14783. </para>
  14784. </glossdef>
  14785. </glossentry>
  14786. <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
  14787. <info>
  14788. UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."
  14789. </info>
  14790. <glossdef>
  14791. <para role="glossdeffirst">
  14792. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14793. Appends a string to the name of the local version of the
  14794. U-Boot image.
  14795. For example, assuming the version of the U-Boot image
  14796. built was "2013.10, the full version string reported by
  14797. U-Boot would be "2013.10-yocto" given the following
  14798. statement:
  14799. <literallayout class='monospaced'>
  14800. UBOOT_LOCALVERSION = "-yocto"
  14801. </literallayout>
  14802. </para>
  14803. </glossdef>
  14804. </glossentry>
  14805. <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
  14806. <info>
  14807. UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."
  14808. </info>
  14809. <glossdef>
  14810. <para role="glossdeffirst">
  14811. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14812. Specifies the value passed on the
  14813. <filename>make</filename> command line when building
  14814. a U-Boot image.
  14815. The value indicates the target platform configuration.
  14816. You typically set this variable from the machine
  14817. configuration file (i.e.
  14818. <filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).
  14819. </para>
  14820. <para>
  14821. Please see the "Selection of Processor Architecture and
  14822. Board Type" section in the U-Boot README for valid values
  14823. for this variable.
  14824. </para>
  14825. </glossdef>
  14826. </glossentry>
  14827. <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
  14828. <info>
  14829. UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."
  14830. </info>
  14831. <glossdef>
  14832. <para role="glossdeffirst">
  14833. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14834. Specifies the target called in the
  14835. <filename>Makefile</filename>.
  14836. The default target is "all".
  14837. </para>
  14838. </glossdef>
  14839. </glossentry>
  14840. <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
  14841. <info>
  14842. UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."
  14843. </info>
  14844. <glossdef>
  14845. <para role="glossdeffirst">
  14846. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14847. Points to the generated U-Boot extension.
  14848. For example, <filename>u-boot.sb</filename> has a
  14849. <filename>.sb</filename> extension.
  14850. </para>
  14851. <para>
  14852. The default U-Boot extension is
  14853. <filename>.bin</filename>
  14854. </para>
  14855. </glossdef>
  14856. </glossentry>
  14857. <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
  14858. <info>
  14859. UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."
  14860. </info>
  14861. <glossdef>
  14862. <para role="glossdeffirst">
  14863. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14864. Specifies the target used for building U-Boot.
  14865. The target is passed directly as part of the "make" command
  14866. (e.g. SPL and AIS).
  14867. If you do not specifically set this variable, the
  14868. OpenEmbedded build process passes and uses "all" for the
  14869. target during the U-Boot building process.
  14870. </para>
  14871. </glossdef>
  14872. </glossentry>
  14873. <glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>
  14874. <info>
  14875. UNKNOWN_CONFIGURE_WHITELIST[doc] = "Specifies a list of options that, if reported by the configure script as being invalid, should not generate a warning during the do_configure task."
  14876. </info>
  14877. <glossdef>
  14878. <para role="glossdeffirst">
  14879. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14880. Specifies a list of options that, if reported by the
  14881. configure script as being invalid, should not generate a
  14882. warning during the
  14883. <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
  14884. task.
  14885. Normally, invalid configure options are simply not passed
  14886. to the configure script (e.g. should be removed from
  14887. <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
  14888. or
  14889. <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>).
  14890. However, common options, for example, exist that are passed
  14891. to all configure scripts at a class level that might not
  14892. be valid for some configure scripts.
  14893. It follows that no benefit exists in seeing a warning about
  14894. these options.
  14895. For these cases, the options are added to
  14896. <filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.
  14897. </para>
  14898. <para>
  14899. The configure arguments check that uses
  14900. <filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part
  14901. of the
  14902. <link linkend='ref-classes-insane'><filename>insane</filename></link>
  14903. class and is only enabled if the recipe inherits the
  14904. <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
  14905. class.
  14906. </para>
  14907. </glossdef>
  14908. </glossentry>
  14909. <glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>
  14910. <info>
  14911. UPDATERCPN[doc] = "Specifies the package that contains the initscript that is enabled."
  14912. </info>
  14913. <glossdef>
  14914. <para role="glossdeffirst">
  14915. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14916. For recipes inheriting the
  14917. <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
  14918. class, <filename>UPDATERCPN</filename> specifies
  14919. the package that contains the initscript that is
  14920. enabled.
  14921. </para>
  14922. <para>
  14923. The default value is "${PN}".
  14924. Given that almost all recipes that install initscripts
  14925. package them in the main package for the recipe, you
  14926. rarely need to set this variable in individual recipes.
  14927. </para>
  14928. </glossdef>
  14929. </glossentry>
  14930. <glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>
  14931. <info>
  14932. UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."
  14933. </info>
  14934. <glossdef>
  14935. <para role="glossdeffirst">
  14936. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14937. When the
  14938. <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link>
  14939. class is enabled globally, you can perform a per-recipe
  14940. check for what the latest upstream source code version is
  14941. by calling
  14942. <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
  14943. If the recipe source code is provided from Git
  14944. repositories, the OpenEmbedded build system determines the
  14945. latest upstream version by picking the latest tag from the
  14946. list of all repository tags.
  14947. You can use the
  14948. <filename>UPSTREAM_CHECK_GITTAGREGEX</filename>
  14949. variable to provide a regular expression to filter only the
  14950. relevant tags should the default filter not work
  14951. correctly.
  14952. <literallayout class='monospaced'>
  14953. UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
  14954. </literallayout>
  14955. </para>
  14956. </glossdef>
  14957. </glossentry>
  14958. <glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>
  14959. <info>
  14960. UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."
  14961. </info>
  14962. <glossdef>
  14963. <para role="glossdeffirst">
  14964. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14965. When the
  14966. <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link>
  14967. class is enabled globally, use the
  14968. <filename>UPSTREAM_CHECK_REGEX</filename> variable to
  14969. specify a different regular expression instead of the
  14970. default one when the package checking system is parsing
  14971. the page found using
  14972. <link linkend='var-UPSTREAM_CHECK_URI'><filename>UPSTREAM_CHECK_URI</filename></link>.
  14973. <literallayout class='monospaced'>
  14974. UPSTREAM_CHECK_REGEX = "package_regex"
  14975. </literallayout>
  14976. </para>
  14977. </glossdef>
  14978. </glossentry>
  14979. <glossentry id='var-UPSTREAM_CHECK_URI'><glossterm>UPSTREAM_CHECK_URI</glossterm>
  14980. <info>
  14981. UPSTREAM_CHECK_URI[doc] = "The URL used by the package checking system to get the latest version of the package when source files are fetched from an upstream Git repository."
  14982. </info>
  14983. <glossdef>
  14984. <para role="glossdeffirst">
  14985. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  14986. When the
  14987. <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link>
  14988. class is enabled globally, you can perform a per-recipe
  14989. check for what the latest upstream source code version is
  14990. by calling <filename>bitbake -c checkpkg</filename>
  14991. <replaceable>recipe</replaceable>.
  14992. If the source code is provided from tarballs, the latest
  14993. version is determined by fetching the directory listing
  14994. where the tarball is and attempting to find a later tarball.
  14995. When this approach does not work, you can use
  14996. <filename>UPSTREAM_CHECK_URI</filename> to
  14997. provide a different URI that contains the link to the
  14998. latest tarball.
  14999. <literallayout class='monospaced'>
  15000. UPSTREAM_CHECK_URI = "recipe_url"
  15001. </literallayout>
  15002. </para>
  15003. </glossdef>
  15004. </glossentry>
  15005. <glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>
  15006. <info>
  15007. USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."
  15008. </info>
  15009. <glossdef>
  15010. <para role="glossdeffirst">
  15011. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15012. Determines if <filename>devtmpfs</filename> is used for
  15013. <filename>/dev</filename> population.
  15014. The default value used for <filename>USE_DEVFS</filename>
  15015. is "1" when no value is specifically set.
  15016. Typically, you would set <filename>USE_DEVFS</filename>
  15017. to "0" for a statically populated <filename>/dev</filename>
  15018. directory.
  15019. </para>
  15020. <para>
  15021. See the
  15022. "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-dev-manager'>Selecting a Device Manager</ulink>"
  15023. section in the Yocto Project Development Tasks Manual for
  15024. information on how to use this variable.
  15025. </para>
  15026. </glossdef>
  15027. </glossentry>
  15028. <glossentry id='var-USE_VT'><glossterm>USE_VT</glossterm>
  15029. <info>
  15030. USE_VT[doc] = "When using SysVinit, determines whether or not to run a getty on any virtual terminals in order to enable logging in through those terminals."
  15031. </info>
  15032. <glossdef>
  15033. <para role="glossdeffirst">
  15034. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15035. When using
  15036. <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
  15037. determines whether or not to run a
  15038. <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
  15039. on any virtual terminals in order to enable logging in
  15040. through those terminals.
  15041. </para>
  15042. <para>
  15043. The default value used for <filename>USE_VT</filename>
  15044. is "1" when no default value is specifically set.
  15045. Typically, you would set <filename>USE_VT</filename>
  15046. to "0" in the machine configuration file for machines
  15047. that do not have a graphical display attached and
  15048. therefore do not need virtual terminal functionality.
  15049. </para>
  15050. </glossdef>
  15051. </glossentry>
  15052. <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
  15053. <info>
  15054. USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."
  15055. </info>
  15056. <glossdef>
  15057. <para role="glossdeffirst">
  15058. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15059. A list of classes to globally inherit.
  15060. These classes are used by the OpenEmbedded build system
  15061. to enable extra features (e.g.
  15062. <filename>buildstats</filename>,
  15063. <filename>image-mklibs</filename>, and so forth).
  15064. </para>
  15065. <para>
  15066. The default list is set in your
  15067. <filename>local.conf</filename> file:
  15068. <literallayout class='monospaced'>
  15069. USER_CLASSES ?= "buildstats image-mklibs image-prelink"
  15070. </literallayout>
  15071. For more information, see
  15072. <filename>meta-poky/conf/local.conf.sample</filename> in
  15073. the
  15074. <link linkend='source-directory'>Source Directory</link>.
  15075. </para>
  15076. </glossdef>
  15077. </glossentry>
  15078. <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
  15079. <info>
  15080. USERADD_ERROR_DYNAMIC[doc] = "If set to 'error', forces the OpenEmbedded build system to produce an error if the user identification (uid) and group identification (gid) values are not defined in files/passwd and files/group files. If set to 'warn', a warning will be issued instead."
  15081. </info>
  15082. <glossdef>
  15083. <para role="glossdeffirst">
  15084. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15085. If set to "error", forces the OpenEmbedded build system to
  15086. produce an error if the user identification
  15087. (<filename>uid</filename>) and group identification
  15088. (<filename>gid</filename>) values are not defined
  15089. in <filename>files/passwd</filename>
  15090. and <filename>files/group</filename> files.
  15091. If set to "warn", a warning will be issued instead.
  15092. </para>
  15093. <para>
  15094. The default behavior for the build system is to dynamically
  15095. apply <filename>uid</filename> and
  15096. <filename>gid</filename> values.
  15097. Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
  15098. variable is by default not set.
  15099. If you plan on using statically assigned
  15100. <filename>gid</filename> and <filename>uid</filename>
  15101. values, you should set
  15102. the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
  15103. your <filename>local.conf</filename> file as
  15104. follows:
  15105. <literallayout class='monospaced'>
  15106. USERADD_ERROR_DYNAMIC = "error"
  15107. </literallayout>
  15108. Overriding the default behavior implies you are going to
  15109. also take steps to set static <filename>uid</filename> and
  15110. <filename>gid</filename> values through use of the
  15111. <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
  15112. <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
  15113. and
  15114. <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
  15115. variables.
  15116. </para>
  15117. </glossdef>
  15118. </glossentry>
  15119. <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
  15120. <info>
  15121. USERADD_GID_TABLES[doc] = "Specifies a password file to use for obtaining static group identification (gid) values when the OpenEmbedded build system adds a group to the system during package installation."
  15122. </info>
  15123. <glossdef>
  15124. <para role="glossdeffirst">
  15125. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15126. Specifies a password file to use for obtaining static
  15127. group identification (<filename>gid</filename>) values
  15128. when the OpenEmbedded build system adds a group to the
  15129. system during package installation.
  15130. </para>
  15131. <para>
  15132. When applying static group identification
  15133. (<filename>gid</filename>) values, the OpenEmbedded build
  15134. system looks in
  15135. <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
  15136. for a <filename>files/group</filename> file and then applies
  15137. those <filename>uid</filename> values.
  15138. Set the variable as follows in your
  15139. <filename>local.conf</filename> file:
  15140. <literallayout class='monospaced'>
  15141. USERADD_GID_TABLES = "files/group"
  15142. </literallayout>
  15143. </para>
  15144. <note>
  15145. Setting the
  15146. <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
  15147. variable to "useradd-staticids" causes the build system
  15148. to use static <filename>gid</filename> values.
  15149. </note>
  15150. </glossdef>
  15151. </glossentry>
  15152. <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
  15153. <info>
  15154. USERADD_PACKAGES[doc] = "When a recipe inherits the useradd class, this variable specifies the individual packages within the recipe that require users and/or groups to be added."
  15155. </info>
  15156. <glossdef>
  15157. <para role="glossdeffirst">
  15158. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15159. When inheriting the
  15160. <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
  15161. class, this variable
  15162. specifies the individual packages within the recipe that
  15163. require users and/or groups to be added.
  15164. </para>
  15165. <para>
  15166. You must set this variable if the recipe inherits the
  15167. class.
  15168. For example, the following enables adding a user for the
  15169. main package in a recipe:
  15170. <literallayout class='monospaced'>
  15171. USERADD_PACKAGES = "${PN}"
  15172. </literallayout>
  15173. <note>
  15174. If follows that if you are going to use the
  15175. <filename>USERADD_PACKAGES</filename> variable,
  15176. you need to set one or more of the
  15177. <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
  15178. <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
  15179. or
  15180. <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
  15181. variables.
  15182. </note>
  15183. </para>
  15184. </glossdef>
  15185. </glossentry>
  15186. <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
  15187. <info>
  15188. USERADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should pass to the useradd command if you add a user to the system when the package is installed."
  15189. </info>
  15190. <glossdef>
  15191. <para role="glossdeffirst">
  15192. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15193. When inheriting the
  15194. <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
  15195. class, this variable
  15196. specifies for a package what parameters should pass
  15197. to the <filename>useradd</filename> command
  15198. if you add a user to the system when the package
  15199. is installed.
  15200. </para>
  15201. <para>
  15202. Here is an example from the <filename>dbus</filename>
  15203. recipe:
  15204. <literallayout class='monospaced'>
  15205. USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
  15206. --no-create-home --shell /bin/false \
  15207. --user-group messagebus"
  15208. </literallayout>
  15209. For information on the standard Linux shell command
  15210. <filename>useradd</filename>, see
  15211. <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
  15212. </para>
  15213. </glossdef>
  15214. </glossentry>
  15215. <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
  15216. <info>
  15217. USERADD_UID_TABLES[doc] = "Specifies a password file to use for obtaining static user identification (uid) values when the OpenEmbedded build system adds a user to the system during package installation."
  15218. </info>
  15219. <glossdef>
  15220. <para role="glossdeffirst">
  15221. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15222. Specifies a password file to use for obtaining static
  15223. user identification (<filename>uid</filename>) values
  15224. when the OpenEmbedded build system adds a user to the
  15225. system during package installation.
  15226. </para>
  15227. <para>
  15228. When applying static user identification
  15229. (<filename>uid</filename>) values, the OpenEmbedded build
  15230. system looks in
  15231. <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
  15232. for a <filename>files/passwd</filename> file and then applies
  15233. those <filename>uid</filename> values.
  15234. Set the variable as follows in your
  15235. <filename>local.conf</filename> file:
  15236. <literallayout class='monospaced'>
  15237. USERADD_UID_TABLES = "files/passwd"
  15238. </literallayout>
  15239. </para>
  15240. <note>
  15241. Setting the
  15242. <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
  15243. variable to "useradd-staticids" causes the build system
  15244. to use static <filename>uid</filename> values.
  15245. </note>
  15246. </glossdef>
  15247. </glossentry>
  15248. <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
  15249. <info>
  15250. USERADDEXTENSION[doc] = "When set to 'useradd-staticids', causes the OpenEmbedded build system to base all user and group additions on a static passwd and group files found in BBPATH."
  15251. </info>
  15252. <glossdef>
  15253. <para role="glossdeffirst">
  15254. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15255. When set to "useradd-staticids", causes the
  15256. OpenEmbedded build system to base all user and group
  15257. additions on a static
  15258. <filename>passwd</filename> and
  15259. <filename>group</filename> files found in
  15260. <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
  15261. </para>
  15262. <para>
  15263. To use static user identification (<filename>uid</filename>)
  15264. and group identification (<filename>gid</filename>)
  15265. values, set the variable
  15266. as follows in your <filename>local.conf</filename> file:
  15267. <literallayout class='monospaced'>
  15268. USERADDEXTENSION = "useradd-staticids"
  15269. </literallayout>
  15270. <note>
  15271. Setting this variable to use static
  15272. <filename>uid</filename> and <filename>gid</filename>
  15273. values causes the OpenEmbedded build system to employ
  15274. the
  15275. <link linkend='ref-classes-useradd'><filename>useradd-staticids</filename></link>
  15276. class.
  15277. </note>
  15278. </para>
  15279. <para>
  15280. If you use static <filename>uid</filename> and
  15281. <filename>gid</filename> information, you must also
  15282. specify the <filename>files/passwd</filename> and
  15283. <filename>files/group</filename> files by setting the
  15284. <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
  15285. and
  15286. <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
  15287. variables.
  15288. Additionally, you should also set the
  15289. <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
  15290. variable.
  15291. </para>
  15292. </glossdef>
  15293. </glossentry>
  15294. </glossdiv>
  15295. <glossdiv id='var-glossary-v'><title>V</title>
  15296. <glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm>
  15297. <info>
  15298. VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files."
  15299. </info>
  15300. <glossdef>
  15301. <para role="glossdeffirst">
  15302. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15303. Specifies the persistence of the target's
  15304. <filename>/var/log</filename> directory, which is used to
  15305. house postinstall target log files.
  15306. </para>
  15307. <para>
  15308. By default, <filename>VOLATILE_LOG_DIR</filename> is set
  15309. to "yes", which means the file is not persistent.
  15310. You can override this setting by setting the
  15311. variable to "no" to make the log directory persistent.
  15312. </para>
  15313. </glossdef>
  15314. </glossentry>
  15315. </glossdiv>
  15316. <glossdiv id='var-glossary-w'><title>W</title>
  15317. <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
  15318. <info>
  15319. WARN_QA[doc] = "Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system."
  15320. </info>
  15321. <glossdef>
  15322. <para role="glossdeffirst">
  15323. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15324. Specifies the quality assurance checks whose failures are
  15325. reported as warnings by the OpenEmbedded build system.
  15326. You set this variable in your distribution configuration
  15327. file.
  15328. For a list of the checks you can control with this variable,
  15329. see the
  15330. "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
  15331. section.
  15332. </para>
  15333. </glossdef>
  15334. </glossentry>
  15335. <glossentry id='var-WKS_FILE_DEPENDS'><glossterm>WKS_FILE_DEPENDS</glossterm>
  15336. <info>
  15337. WKS_FILE_DEPENDS[doc] = "Lists a recipe's build-time dependencies specific to Wic."
  15338. </info>
  15339. <glossdef>
  15340. <para role="glossdeffirst">
  15341. When placed in the recipe that builds your image, this
  15342. variable lists build-time dependencies.
  15343. The <filename>WKS_FILE_DEPENDS</filename> variable is only
  15344. applicable when Wic images are active (i.e. when
  15345. <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
  15346. contains entries related to Wic).
  15347. If your recipe does not create Wic images, the variable
  15348. has no effect.
  15349. </para>
  15350. <para>
  15351. The <filename>WKS_FILE_DEPENDS</filename> variable is
  15352. similar to the
  15353. <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
  15354. variable.
  15355. When you use the variable in your recipe that builds the
  15356. Wic image, dependencies you list in the
  15357. <filename>WIC_FILE_DEPENDS</filename> variable are added to
  15358. the <filename>DEPENDS</filename> variable.
  15359. </para>
  15360. <para>
  15361. With the <filename>WKS_FILE_DEPENDS</filename> variable,
  15362. you have the possibility to specify a list of additional
  15363. dependencies (e.g. native tools, bootloaders, and so forth),
  15364. that are required to build Wic images.
  15365. Following is an example:
  15366. <literallayout class='monospaced'>
  15367. WKS_FILE_DEPENDS = "<replaceable>some-native-tool</replaceable>"
  15368. </literallayout>
  15369. In the previous example,
  15370. <replaceable>some-native-tool</replaceable> would be
  15371. replaced with an actual native tool on which the build
  15372. would depend.
  15373. </para>
  15374. </glossdef>
  15375. </glossentry>
  15376. <glossentry id='var-WKS_FILE'><glossterm>WKS_FILE</glossterm>
  15377. <info>
  15378. WKS_FILE[doc] = "Specifies the name of the wic kickstart file."
  15379. </info>
  15380. <glossdef>
  15381. <para role="glossdeffirst">
  15382. Specifies the location of the Wic
  15383. kickstart file that is used by the OpenEmbedded build
  15384. system to create a partitioned image
  15385. (<replaceable>image</replaceable><filename>.wic</filename>).
  15386. For information on how to create a partitioned image, see
  15387. the
  15388. "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
  15389. section in the Yocto Project Development Tasks Manual.
  15390. For details on the kickstart file format, see the
  15391. "<link linkend='openembedded-kickstart-wks-reference'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>
  15392. Chapter.
  15393. </para>
  15394. </glossdef>
  15395. </glossentry>
  15396. <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
  15397. <info>
  15398. WORKDIR[doc] = "The pathname of the working directory in which the OpenEmbedded build system builds a recipe. This directory is located within the TMPDIR directory structure and changes as different packages are built."
  15399. </info>
  15400. <glossdef>
  15401. <para role="glossdeffirst">
  15402. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15403. The pathname of the work directory in which the OpenEmbedded
  15404. build system builds a recipe.
  15405. This directory is located within the
  15406. <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
  15407. directory structure and is specific to the recipe being
  15408. built and the system for which it is being built.
  15409. </para>
  15410. <para>
  15411. The <filename>WORKDIR</filename> directory is defined as
  15412. follows:
  15413. <literallayout class='monospaced'>
  15414. ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
  15415. </literallayout>
  15416. The actual directory depends on several things:
  15417. <itemizedlist>
  15418. <listitem><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>:
  15419. The top-level build output directory</listitem>
  15420. <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
  15421. The target system identifier</listitem>
  15422. <listitem><link linkend='var-PN'><filename>PN</filename></link>:
  15423. The recipe name</listitem>
  15424. <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
  15425. The epoch - (if
  15426. <link linkend='var-PE'><filename>PE</filename></link>
  15427. is not specified, which is usually the case for most
  15428. recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
  15429. <listitem><link linkend='var-PV'><filename>PV</filename></link>:
  15430. The recipe version</listitem>
  15431. <listitem><link linkend='var-PR'><filename>PR</filename></link>:
  15432. The recipe revision</listitem>
  15433. </itemizedlist>
  15434. </para>
  15435. <para>
  15436. As an example, assume a Source Directory top-level folder
  15437. name <filename>poky</filename>, a default Build Directory at
  15438. <filename>poky/build</filename>, and a
  15439. <filename>qemux86-poky-linux</filename> machine target
  15440. system.
  15441. Furthermore, suppose your recipe is named
  15442. <filename>foo_1.3.0-r0.bb</filename>.
  15443. In this case, the work directory the build system uses to
  15444. build the package would be as follows:
  15445. <literallayout class='monospaced'>
  15446. poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
  15447. </literallayout>
  15448. </para>
  15449. </glossdef>
  15450. </glossentry>
  15451. </glossdiv>
  15452. <glossdiv id='var-glossary-x'><title>X</title>
  15453. <glossentry id='var-XSERVER'><glossterm>XSERVER</glossterm>
  15454. <info>
  15455. XSERVER[doc] = "Specifies the packages that should be installed
  15456. to provide an X server and drivers for the current machine."
  15457. </info>
  15458. <glossdef>
  15459. <para role="glossdeffirst">
  15460. <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
  15461. Specifies the packages that should be installed to
  15462. provide an X server and drivers for the current machine,
  15463. assuming your image directly includes
  15464. <filename>packagegroup-core-x11-xserver</filename> or,
  15465. perhaps indirectly, includes "x11-base" in
  15466. <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
  15467. </para>
  15468. <para>
  15469. The default value of <filename>XSERVER</filename>, if not
  15470. specified in the machine configuration, is
  15471. "xserver-xorg xf86-video-fbdev xf86-input-evdev".
  15472. </para>
  15473. </glossdef>
  15474. </glossentry>
  15475. </glossdiv>
  15476. <!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
  15477. <!-- </glossdiv>-->
  15478. <!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
  15479. <!-- </glossdiv>-->
  15480. </glossary>
  15481. </chapter>
  15482. <!--
  15483. vim: expandtab tw=80 ts=4
  15484. -->