manual.html 527 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Buildroot user manual</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /></head><body><div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="idm1"></a>The Buildroot user manual</h1></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="preface"><a href="#idm4"></a></span></dt><dt><span class="part"><a href="#_getting_started">I. Getting started</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_about_buildroot">1. About Buildroot</a></span></dt><dt><span class="chapter"><a href="#requirement">2. System requirements</a></span></dt><dd><dl><dt><span class="section"><a href="#requirement-mandatory">2.1. Mandatory packages</a></span></dt><dt><span class="section"><a href="#requirement-optional">2.2. Optional packages</a></span></dt></dl></dd><dt><span class="chapter"><a href="#getting-buildroot">3. Getting Buildroot</a></span></dt><dt><span class="chapter"><a href="#_buildroot_quick_start">4. Buildroot quick start</a></span></dt><dt><span class="chapter"><a href="#community-resources">5. Community resources</a></span></dt></dl></dd><dt><span class="part"><a href="#_user_guide">II. User guide</a></span></dt><dd><dl><dt><span class="chapter"><a href="#configure">6. Buildroot configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#_cross_compilation_toolchain">6.1. Cross-compilation toolchain</a></span></dt><dt><span class="section"><a href="#_dev_management">6.2. /dev management</a></span></dt><dt><span class="section"><a href="#_init_system">6.3. init system</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_configuration_of_other_components">7. Configuration of other components</a></span></dt><dt><span class="chapter"><a href="#_general_buildroot_usage">8. General Buildroot usage</a></span></dt><dd><dl><dt><span class="section"><a href="#make-tips">8.1. <span class="emphasis"><em>make</em></span> tips</a></span></dt><dt><span class="section"><a href="#full-rebuild">8.2. Understanding when a full rebuild is necessary</a></span></dt><dt><span class="section"><a href="#rebuild-pkg">8.3. Understanding how to rebuild packages</a></span></dt><dt><span class="section"><a href="#_offline_builds">8.4. Offline builds</a></span></dt><dt><span class="section"><a href="#_building_out_of_tree">8.5. Building out-of-tree</a></span></dt><dt><span class="section"><a href="#env-vars">8.6. Environment variables</a></span></dt><dt><span class="section"><a href="#_dealing_efficiently_with_filesystem_images">8.7. Dealing efficiently with filesystem images</a></span></dt><dt><span class="section"><a href="#_details_about_packages">8.8. Details about packages</a></span></dt><dt><span class="section"><a href="#_graphing_the_dependencies_between_packages">8.9. Graphing the dependencies between packages</a></span></dt><dt><span class="section"><a href="#_graphing_the_build_duration">8.10. Graphing the build duration</a></span></dt><dt><span class="section"><a href="#graph-size">8.11. Graphing the filesystem size contribution of packages</a></span></dt><dt><span class="section"><a href="#top-level-parallel-build">8.12. Top-level parallel build</a></span></dt><dt><span class="section"><a href="#_integration_with_eclipse">8.13. Integration with Eclipse</a></span></dt><dt><span class="section"><a href="#_advanced_usage">8.14. Advanced usage</a></span></dt></dl></dd><dt><span class="chapter"><a href="#customize">9. Project-specific customization</a></span></dt><dd><dl><dt><span class="section"><a href="#customize-dir-structure">9.1. Recommended directory structure</a></span></dt><dt><span class="section"><a href="#outside-br-custom">9.2. Keeping customizations outside of Buildroot</a></span></dt><dt><span class="section"><a href="#customize-store-buildroot-config">9.3. Storing the Buildroot configuration</a></span></dt><dt><span class="section"><a href="#customize-store-package-config">9.4. Storing the configuration of other components</a></span></dt><dt><span class="section"><a href="#rootfs-custom">9.5. Customizing the generated target filesystem</a></span></dt><dt><span class="section"><a href="#customize-users">9.6. Adding custom user accounts</a></span></dt><dt><span class="section"><a href="#_customization_emphasis_after_emphasis_the_images_have_been_created">9.7. Customization <span class="emphasis"><em>after</em></span> the images have been created</a></span></dt><dt><span class="section"><a href="#customize-patches">9.8. Adding project-specific patches</a></span></dt><dt><span class="section"><a href="#customize-packages">9.9. Adding project-specific packages</a></span></dt><dt><span class="section"><a href="#_quick_guide_to_storing_your_project_specific_customizations">9.10. Quick guide to storing your project-specific customizations</a></span></dt></dl></dd><dt><span class="chapter"><a href="#selinux">10. Using SELinux in Buildroot</a></span></dt><dd><dl><dt><span class="section"><a href="#enabling-selinux">10.1. Enabling SELinux support</a></span></dt><dt><span class="section"><a href="#selinux-policy-tweaking">10.2. SELinux policy tweaking</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_frequently_asked_questions_amp_troubleshooting">11. Frequently Asked Questions &amp; Troubleshooting</a></span></dt><dd><dl><dt><span class="section"><a href="#faq-boot-hang-after-starting">11.1. The boot hangs after <span class="emphasis"><em>Starting network…</em></span></a></span></dt><dt><span class="section"><a href="#faq-no-compiler-on-target">11.2. Why is there no compiler on the target?</a></span></dt><dt><span class="section"><a href="#faq-no-dev-files-on-target">11.3. Why are there no development files on the target?</a></span></dt><dt><span class="section"><a href="#faq-no-doc-on-target">11.4. Why is there no documentation on the target?</a></span></dt><dt><span class="section"><a href="#faq-why-not-visible-package">11.5. Why are some packages not visible in the Buildroot config menu?</a></span></dt><dt><span class="section"><a href="#faq-why-not-use-target-as-chroot">11.6. Why not use the target directory as a chroot directory?</a></span></dt><dt><span class="section"><a href="#faq-no-binary-packages">11.7. Why doesn’t Buildroot generate binary packages (.deb, .ipkg…)?</a></span></dt><dt><span class="section"><a href="#faq-speeding-up-build">11.8. How to speed-up the build process?</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_known_issues">12. Known issues</a></span></dt><dt><span class="chapter"><a href="#legal-info">13. Legal notice and licensing</a></span></dt><dd><dl><dt><span class="section"><a href="#_complying_with_open_source_licenses">13.1. Complying with open source licenses</a></span></dt><dt><span class="section"><a href="#legal-info-buildroot">13.2. Complying with the Buildroot license</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_beyond_buildroot">14. Beyond Buildroot</a></span></dt><dd><dl><dt><span class="section"><a href="#_boot_the_generated_images">14.1. Boot the generated images</a></span></dt><dt><span class="section"><a href="#_chroot">14.2. Chroot</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#_developer_guide">III. Developer guide</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_how_buildroot_works">15. How Buildroot works</a></span></dt><dt><span class="chapter"><a href="#_coding_style">16. Coding style</a></span></dt><dd><dl><dt><span class="section"><a href="#writing-rules-config-in">16.1. <code class="literal">Config.in</code> file</a></span></dt><dt><span class="section"><a href="#writing-rules-mk">16.2. The <code class="literal">.mk</code> file</a></span></dt><dt><span class="section"><a href="#_the_documentation">16.3. The documentation</a></span></dt><dt><span class="section"><a href="#_support_scripts">16.4. Support scripts</a></span></dt></dl></dd><dt><span class="chapter"><a href="#adding-board-support">17. Adding support for a particular board</a></span></dt><dt><span class="chapter"><a href="#adding-packages">18. Adding new packages to Buildroot</a></span></dt><dd><dl><dt><span class="section"><a href="#_package_directory">18.1. Package directory</a></span></dt><dt><span class="section"><a href="#_config_files">18.2. Config files</a></span></dt><dt><span class="section"><a href="#_the_literal_mk_literal_file">18.3. The <code class="literal">.mk</code> file</a></span></dt><dt><span class="section"><a href="#adding-packages-hash">18.4. The <code class="literal">.hash</code> file</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_packages_with_specific_build_systems">18.5. Infrastructure for packages with specific build systems</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_autotools_based_packages">18.6. Infrastructure for autotools-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_cmake_based_packages">18.7. Infrastructure for CMake-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_python_packages">18.8. Infrastructure for Python packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_luarocks_based_packages">18.9. Infrastructure for LuaRocks-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_perl_cpan_packages">18.10. Infrastructure for Perl/CPAN packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_virtual_packages">18.11. Infrastructure for virtual packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_packages_using_kconfig_for_configuration_files">18.12. Infrastructure for packages using kconfig for configuration files</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_rebar_based_packages">18.13. Infrastructure for rebar-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_waf_based_packages">18.14. Infrastructure for Waf-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_meson_based_packages">18.15. Infrastructure for Meson-based packages</a></span></dt><dt><span class="section"><a href="#_integration_of_cargo_based_packages">18.16. Integration of Cargo-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_go_packages">18.17. Infrastructure for Go packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_qmake_based_packages">18.18. Infrastructure for QMake-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_packages_building_kernel_modules">18.19. Infrastructure for packages building kernel modules</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_asciidoc_documents">18.20. Infrastructure for asciidoc documents</a></span></dt><dt><span class="section"><a href="#linux-kernel-specific-infra">18.21. Infrastructure specific to the Linux kernel package</a></span></dt><dt><span class="section"><a href="#hooks">18.22. Hooks available in the various build steps</a></span></dt><dt><span class="section"><a href="#_gettext_integration_and_interaction_with_packages">18.23. Gettext integration and interaction with packages</a></span></dt><dt><span class="section"><a href="#_tips_and_tricks">18.24. Tips and tricks</a></span></dt><dt><span class="section"><a href="#_conclusion">18.25. Conclusion</a></span></dt></dl></dd><dt><span class="chapter"><a href="#patch-policy">19. Patching a package</a></span></dt><dd><dl><dt><span class="section"><a href="#_providing_patches">19.1. Providing patches</a></span></dt><dt><span class="section"><a href="#patch-apply-order">19.2. How patches are applied</a></span></dt><dt><span class="section"><a href="#_format_and_licensing_of_the_package_patches">19.3. Format and licensing of the package patches</a></span></dt><dt><span class="section"><a href="#_integrating_patches_found_on_the_web">19.4. Integrating patches found on the Web</a></span></dt></dl></dd><dt><span class="chapter"><a href="#download-infra">20. Download infrastructure</a></span></dt><dt><span class="chapter"><a href="#debugging-buildroot">21. Debugging Buildroot</a></span></dt><dt><span class="chapter"><a href="#_contributing_to_buildroot">22. Contributing to Buildroot</a></span></dt><dd><dl><dt><span class="section"><a href="#_reproducing_analyzing_and_fixing_bugs">22.1. Reproducing, analyzing and fixing bugs</a></span></dt><dt><span class="section"><a href="#_analyzing_and_fixing_autobuild_failures">22.2. Analyzing and fixing autobuild failures</a></span></dt><dt><span class="section"><a href="#_reviewing_and_testing_patches">22.3. Reviewing and testing patches</a></span></dt><dt><span class="section"><a href="#_work_on_items_from_the_todo_list">22.4. Work on items from the TODO list</a></span></dt><dt><span class="section"><a href="#submitting-patches">22.5. Submitting patches</a></span></dt><dt><span class="section"><a href="#reporting-bugs">22.6. Reporting issues/bugs or getting help</a></span></dt><dt><span class="section"><a href="#_using_the_run_tests_framework">22.7. Using the run-tests framework</a></span></dt></dl></dd><dt><span class="chapter"><a href="#DEVELOPERS">23. DEVELOPERS file and get-developers</a></span></dt><dt><span class="chapter"><a href="#RELENG">24. Release Engineering</a></span></dt><dd><dl><dt><span class="section"><a href="#_releases">24.1. Releases</a></span></dt><dt><span class="section"><a href="#_development">24.2. Development</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#_appendix">IV. Appendix</a></span></dt><dd><dl><dt><span class="chapter"><a href="#makedev-syntax">25. Makedev syntax documentation</a></span></dt><dt><span class="chapter"><a href="#makeuser-syntax">26. Makeusers syntax documentation</a></span></dt><dt><span class="chapter"><a href="#migrating-from-ol-versions">27. Migrating from older Buildroot versions</a></span></dt><dd><dl><dt><span class="section"><a href="#br2-external-converting">27.1. Migrating to 2016.11</a></span></dt><dt><span class="section"><a href="#migrating-host-usr">27.2. Migrating to 2017.08</a></span></dt></dl></dd></dl></dd></dl></div><div class="list-of-examples"><p><strong>List of Examples</strong></p><dl><dt>18.1. <a href="#idm3193">Config script: <span class="emphasis"><em>divine</em></span> package</a></dt><dt>18.2. <a href="#idm3200">Config script: <span class="emphasis"><em>imagemagick</em></span> package:</a></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a id="idm4"></a></h1></div></div></div><p>Buildroot 2021.02.2 manual generated on 2021-05-12
  3. 09:07:43 UTC from git revision 76b4f9e9b6</p><p>The Buildroot manual is written by the Buildroot developers.
  4. It is licensed under the GNU General Public License, version 2. Refer to the
  5. <a class="ulink" href="http://git.buildroot.org/buildroot/tree/COPYING?id=76b4f9e9b658d3a4a72266e4aa2e63aa7a3f54f9" target="_top">COPYING</a>
  6. file in the Buildroot sources for the full text of this license.</p><p>Copyright © 2004-2020 The Buildroot developers</p><div class="informalfigure"><div class="mediaobject"><img src="logo.png" alt="logo.png" /></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="_getting_started"></a>Part I. Getting started</h1></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_about_buildroot"></a>Chapter 1. About Buildroot</h2></div></div></div><p>Buildroot is a tool that simplifies and automates the process of
  7. building a complete Linux system for an embedded system, using
  8. cross-compilation.</p><p>In order to achieve this, Buildroot is able to generate a
  9. cross-compilation toolchain, a root filesystem, a Linux kernel image
  10. and a bootloader for your target. Buildroot can be used for any
  11. combination of these options, independently (you can for example use
  12. an existing cross-compilation toolchain, and build only your root
  13. filesystem with Buildroot).</p><p>Buildroot is useful mainly for people working with embedded systems.
  14. Embedded systems often use processors that are not the regular x86
  15. processors everyone is used to having in his PC. They can be PowerPC
  16. processors, MIPS processors, ARM processors, etc.</p><p>Buildroot supports numerous processors and their variants; it also
  17. comes with default configurations for several boards available
  18. off-the-shelf. Besides this, a number of third-party projects are based on,
  19. or develop their BSP <a href="#ftn.idm24" class="footnote" id="idm24"><sup class="footnote">[1]</sup></a> or
  20. SDK <a href="#ftn.idm26" class="footnote" id="idm26"><sup class="footnote">[2]</sup></a> on top of Buildroot.</p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm24" class="footnote"><p><a href="#idm24" class="simpara"><sup class="simpara">[1] </sup></a>BSP: Board Support Package</p></div><div id="ftn.idm26" class="footnote"><p><a href="#idm26" class="simpara"><sup class="simpara">[2] </sup></a>SDK: Software Development Kit</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="requirement"></a>Chapter 2. System requirements</h2></div></div></div><p>Buildroot is designed to run on Linux systems.</p><p>While Buildroot itself will build most host packages it needs for the
  21. compilation, certain standard Linux utilities are expected to be
  22. already installed on the host system. Below you will find an overview of
  23. the mandatory and optional packages (note that package names may vary
  24. between distributions).</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="requirement-mandatory"></a>2.1. Mandatory packages</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  25. Build tools:
  26. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  27. <code class="literal">which</code>
  28. </li><li class="listitem">
  29. <code class="literal">sed</code>
  30. </li><li class="listitem">
  31. <code class="literal">make</code> (version 3.81 or any later)
  32. </li><li class="listitem">
  33. <code class="literal">binutils</code>
  34. </li><li class="listitem">
  35. <code class="literal">build-essential</code> (only for Debian based systems)
  36. </li><li class="listitem">
  37. <code class="literal">gcc</code> (version 4.8 or any later)
  38. </li><li class="listitem">
  39. <code class="literal">g++</code> (version 4.8 or any later)
  40. </li><li class="listitem">
  41. <code class="literal">bash</code>
  42. </li><li class="listitem">
  43. <code class="literal">patch</code>
  44. </li><li class="listitem">
  45. <code class="literal">gzip</code>
  46. </li><li class="listitem">
  47. <code class="literal">bzip2</code>
  48. </li><li class="listitem">
  49. <code class="literal">perl</code> (version 5.8.7 or any later)
  50. </li><li class="listitem">
  51. <code class="literal">tar</code>
  52. </li><li class="listitem">
  53. <code class="literal">cpio</code>
  54. </li><li class="listitem">
  55. <code class="literal">unzip</code>
  56. </li><li class="listitem">
  57. <code class="literal">rsync</code>
  58. </li><li class="listitem">
  59. <code class="literal">file</code> (must be in <code class="literal">/usr/bin/file</code>)
  60. </li><li class="listitem">
  61. <code class="literal">bc</code>
  62. </li></ul></div></li><li class="listitem"><p class="simpara">
  63. Source fetching tools:
  64. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  65. <code class="literal">wget</code>
  66. </li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="requirement-optional"></a>2.2. Optional packages</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  67. Recommended dependencies:
  68. </p><p class="simpara">Some features or utilities in Buildroot, like the legal-info, or the
  69. graph generation tools, have additional dependencies. Although they
  70. are not mandatory for a simple build, they are still highly recommended:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  71. <code class="literal">python</code> (version 2.7 or any later)
  72. </li></ul></div></li><li class="listitem"><p class="simpara">
  73. Configuration interface dependencies:
  74. </p><p class="simpara">For these libraries, you need to install both runtime and development
  75. data, which in many distributions are packaged separately. The
  76. development packages typically have a <span class="emphasis"><em>-dev</em></span> or <span class="emphasis"><em>-devel</em></span> suffix.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  77. <code class="literal">ncurses5</code> to use the <span class="emphasis"><em>menuconfig</em></span> interface
  78. </li><li class="listitem">
  79. <code class="literal">qt5</code> to use the <span class="emphasis"><em>xconfig</em></span> interface
  80. </li><li class="listitem">
  81. <code class="literal">glib2</code>, <code class="literal">gtk2</code> and <code class="literal">glade2</code> to use the <span class="emphasis"><em>gconfig</em></span> interface
  82. </li></ul></div></li><li class="listitem"><p class="simpara">
  83. Source fetching tools:
  84. </p><p class="simpara">In the official tree, most of the package sources are retrieved using
  85. <code class="literal">wget</code> from <span class="emphasis"><em>ftp</em></span>, <span class="emphasis"><em>http</em></span> or <span class="emphasis"><em>https</em></span> locations. A few packages are only
  86. available through a version control system. Moreover, Buildroot is
  87. capable of downloading sources via other tools, like <code class="literal">rsync</code> or <code class="literal">scp</code>
  88. (refer to <a class="xref" href="#download-infra" title="Chapter 20. Download infrastructure">Chapter 20, <em>Download infrastructure</em></a> for more details). If you enable
  89. packages using any of these methods, you will need to install the
  90. corresponding tool on the host system:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  91. <code class="literal">bazaar</code>
  92. </li><li class="listitem">
  93. <code class="literal">cvs</code>
  94. </li><li class="listitem">
  95. <code class="literal">git</code>
  96. </li><li class="listitem">
  97. <code class="literal">mercurial</code>
  98. </li><li class="listitem">
  99. <code class="literal">rsync</code>
  100. </li><li class="listitem">
  101. <code class="literal">scp</code>
  102. </li><li class="listitem">
  103. <code class="literal">subversion</code>
  104. </li></ul></div></li><li class="listitem"><p class="simpara">
  105. Java-related packages, if the Java Classpath needs to be built for
  106. the target system:
  107. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  108. The <code class="literal">javac</code> compiler
  109. </li><li class="listitem">
  110. The <code class="literal">jar</code> tool
  111. </li></ul></div></li><li class="listitem"><p class="simpara">
  112. Documentation generation tools:
  113. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  114. <code class="literal">asciidoc</code>, version 8.6.3 or higher
  115. </li><li class="listitem">
  116. <code class="literal">w3m</code>
  117. </li><li class="listitem">
  118. <code class="literal">python</code> with the <code class="literal">argparse</code> module (automatically present in 2.7+ and 3.2+)
  119. </li><li class="listitem">
  120. <code class="literal">dblatex</code> (required for the pdf manual only)
  121. </li></ul></div></li><li class="listitem"><p class="simpara">
  122. Graph generation tools:
  123. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  124. <code class="literal">graphviz</code> to use <span class="emphasis"><em>graph-depends</em></span> and <span class="emphasis"><em>&lt;pkg&gt;-graph-depends</em></span>
  125. </li><li class="listitem">
  126. <code class="literal">python-matplotlib</code> to use <span class="emphasis"><em>graph-build</em></span>
  127. </li></ul></div></li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="getting-buildroot"></a>Chapter 3. Getting Buildroot</h2></div></div></div><p>Buildroot releases are made every 3 months, in February, May, August and
  128. November. Release numbers are in the format YYYY.MM, so for example
  129. 2013.02, 2014.08.</p><p>Release tarballs are available at <a class="ulink" href="http://buildroot.org/downloads/" target="_top">http://buildroot.org/downloads/</a>.</p><p>For your convenience, a <a class="ulink" href="https://www.vagrantup.com/" target="_top">Vagrantfile</a> is
  130. available in <code class="literal">support/misc/Vagrantfile</code> in the Buildroot source tree
  131. to quickly set up a virtual machine with the needed dependencies to
  132. get started.</p><p>If you want to setup an isolated buildroot environment on Linux or Mac
  133. Os X, paste this line onto your terminal:</p><pre class="screen">curl -O https://buildroot.org/downloads/Vagrantfile; vagrant up</pre><p>If you are on Windows, paste this into your powershell:</p><pre class="screen">(new-object System.Net.WebClient).DownloadFile(
  134. "https://buildroot.org/downloads/Vagrantfile","Vagrantfile");
  135. vagrant up</pre><p>If you want to follow development, you can use the daily snapshots or
  136. make a clone of the Git repository. Refer to the
  137. <a class="ulink" href="http://buildroot.org/download" target="_top">Download page</a> of the Buildroot website
  138. for more details.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_buildroot_quick_start"></a>Chapter 4. Buildroot quick start</h2></div></div></div><p><span class="strong"><strong>Important</strong></span>: you can and should <span class="strong"><strong>build everything as a normal user</strong></span>. There
  139. is no need to be root to configure and use Buildroot. By running all
  140. commands as a regular user, you protect your system against packages
  141. behaving badly during compilation and installation.</p><p>The first step when using Buildroot is to create a configuration.
  142. Buildroot has a nice configuration tool similar to the one you can
  143. find in the <a class="ulink" href="http://www.kernel.org/" target="_top">Linux kernel</a> or in
  144. <a class="ulink" href="http://www.busybox.net/" target="_top">BusyBox</a>.</p><p>From the buildroot directory, run</p><pre class="screen"> $ make menuconfig</pre><p>for the original curses-based configurator, or</p><pre class="screen"> $ make nconfig</pre><p>for the new curses-based configurator, or</p><pre class="screen"> $ make xconfig</pre><p>for the Qt-based configurator, or</p><pre class="screen"> $ make gconfig</pre><p>for the GTK-based configurator.</p><p>All of these "make" commands will need to build a configuration
  145. utility (including the interface), so you may need to install
  146. "development" packages for relevant libraries used by the
  147. configuration utilities. Refer to <a class="xref" href="#requirement" title="Chapter 2. System requirements">Chapter 2, <em>System requirements</em></a> for more details,
  148. specifically the <a class="link" href="#requirement-optional" title="2.2. Optional packages">optional requirements</a>
  149. to get the dependencies of your favorite interface.</p><p>For each menu entry in the configuration tool, you can find associated
  150. help that describes the purpose of the entry. Refer to <a class="xref" href="#configure" title="Chapter 6. Buildroot configuration">Chapter 6, <em>Buildroot configuration</em></a>
  151. for details on some specific configuration aspects.</p><p>Once everything is configured, the configuration tool generates a
  152. <code class="literal">.config</code> file that contains the entire configuration. This file will be
  153. read by the top-level Makefile.</p><p>To start the build process, simply run:</p><pre class="screen"> $ make</pre><p>By default, Buildroot does not support top-level parallel build, so
  154. running <code class="literal">make -jN</code> is not necessary. There is however experimental
  155. support for top-level parallel build, see
  156. <a class="xref" href="#top-level-parallel-build" title="8.12. Top-level parallel build">Section 8.12, “Top-level parallel build”</a>.</p><p>The <code class="literal">make</code> command will generally perform the following steps:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  157. download source files (as required);
  158. </li><li class="listitem">
  159. configure, build and install the cross-compilation toolchain, or
  160. simply import an external toolchain;
  161. </li><li class="listitem">
  162. configure, build and install selected target packages;
  163. </li><li class="listitem">
  164. build a kernel image, if selected;
  165. </li><li class="listitem">
  166. build a bootloader image, if selected;
  167. </li><li class="listitem">
  168. create a root filesystem in selected formats.
  169. </li></ul></div><p>Buildroot output is stored in a single directory, <code class="literal">output/</code>.
  170. This directory contains several subdirectories:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  171. <code class="literal">images/</code> where all the images (kernel image, bootloader and root
  172. filesystem images) are stored. These are the files you need to put
  173. on your target system.
  174. </li><li class="listitem">
  175. <code class="literal">build/</code> where all the components are built (this includes tools
  176. needed by Buildroot on the host and packages compiled for the
  177. target). This directory contains one subdirectory for each of these
  178. components.
  179. </li><li class="listitem">
  180. <code class="literal">host/</code> contains both the tools built for the host, and the sysroot
  181. of the target toolchain. The former is an installation of tools
  182. compiled for the host that are needed for the proper execution of
  183. Buildroot, including the cross-compilation toolchain. The latter
  184. is a hierarchy similar to a root filesystem hierarchy. It contains
  185. the headers and libraries of all user-space packages that provide
  186. and install libraries used by other packages. However, this
  187. directory is <span class="emphasis"><em>not</em></span> intended to be the root filesystem for the target:
  188. it contains a lot of development files, unstripped binaries and
  189. libraries that make it far too big for an embedded system. These
  190. development files are used to compile libraries and applications for
  191. the target that depend on other libraries.
  192. </li><li class="listitem">
  193. <code class="literal">staging/</code> is a symlink to the target toolchain sysroot inside
  194. <code class="literal">host/</code>, which exists for backwards compatibility.
  195. </li><li class="listitem">
  196. <code class="literal">target/</code> which contains <span class="emphasis"><em>almost</em></span> the complete root filesystem for
  197. the target: everything needed is present except the device files in
  198. <code class="literal">/dev/</code> (Buildroot can’t create them because Buildroot doesn’t run
  199. as root and doesn’t want to run as root). Also, it doesn’t have the correct
  200. permissions (e.g. setuid for the busybox binary). Therefore, this directory
  201. <span class="strong"><strong>should not be used on your target</strong></span>. Instead, you should use one of
  202. the images built in the <code class="literal">images/</code> directory. If you need an
  203. extracted image of the root filesystem for booting over NFS, then
  204. use the tarball image generated in <code class="literal">images/</code> and extract it as
  205. root. Compared to <code class="literal">staging/</code>, <code class="literal">target/</code> contains only the files and
  206. libraries needed to run the selected target applications: the
  207. development files (headers, etc.) are not present, the binaries are
  208. stripped.
  209. </li></ul></div><p>These commands, <code class="literal">make menuconfig|nconfig|gconfig|xconfig</code> and <code class="literal">make</code>, are the
  210. basic ones that allow to easily and quickly generate images fitting
  211. your needs, with all the features and applications you enabled.</p><p>More details about the "make" command usage are given in
  212. <a class="xref" href="#make-tips" title="8.1. make tips">Section 8.1, “<span class="emphasis"><em>make</em></span> tips”</a>.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="community-resources"></a>Chapter 5. Community resources</h2></div></div></div><p>Like any open source project, Buildroot has different ways to share
  213. information in its community and outside.</p><p>Each of those ways may interest you if you are looking for some help,
  214. want to understand Buildroot or contribute to the project.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
  215. Mailing List
  216. </span></dt><dd><p class="simpara">Buildroot has a mailing list for discussion and development. It is the
  217. main method of interaction for Buildroot users and developers.</p><p class="simpara">Only subscribers to the Buildroot mailing list are allowed to post to
  218. this list. You can subscribe via the
  219. <a class="ulink" href="http://lists.buildroot.org/mailman/listinfo/buildroot" target="_top">mailing list info
  220. page</a>.</p><p class="simpara">Mails that are sent to the mailing list are also available in the
  221. <a class="ulink" href="http://lists.buildroot.org/pipermail/buildroot" target="_top">mailing list archives</a> and
  222. via <a class="ulink" href="http://gmane.org" target="_top">Gmane</a>, at
  223. <a class="ulink" href="http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot" target="_top"><code class="literal">gmane.comp.lib.uclibc.buildroot</code></a>.
  224. Please search the mailing list archives before asking questions, since
  225. there is a good chance someone else has asked the same question before.</p></dd><dt><span class="term">
  226. IRC
  227. </span></dt><dd><p class="simpara">The Buildroot IRC channel <a class="ulink" href="irc://freenode.net/#buildroot" target="_top">#buildroot</a> is
  228. hosted on <a class="ulink" href="http://webchat.freenode.net" target="_top">Freenode</a>. It is a useful place to
  229. ask quick questions or discuss on certain topics.</p><p class="simpara">When asking for help on IRC, share relevant logs or pieces of code
  230. using a code sharing website, such as <a class="ulink" href="http://code.bulix.org" target="_top">http://code.bulix.org</a>.</p><p class="simpara">Note that for certain questions, posting to the mailing list may be
  231. better as it will reach more people, both developers and users.</p></dd><dt><span class="term">
  232. Bug tracker
  233. </span></dt><dd>Bugs in Buildroot can be reported via the mailing list or alternatively
  234. via the <a class="ulink" href="https://bugs.buildroot.org/buglist.cgi?product=buildroot" target="_top">Buildroot
  235. bugtracker</a>. Please refer to <a class="xref" href="#reporting-bugs" title="22.6. Reporting issues/bugs or getting help">Section 22.6, “Reporting issues/bugs or getting help”</a> before creating a bug
  236. report.</dd><dt><span class="term">
  237. Wiki
  238. </span></dt><dd><a class="ulink" href="http://elinux.org/Buildroot" target="_top">The Buildroot wiki page</a> is hosted on
  239. the <a class="ulink" href="http://elinux.org" target="_top">eLinux</a> wiki. It contains some useful links, an
  240. overview of past and upcoming events, and a TODO list.</dd><dt><span class="term">
  241. Patchwork
  242. </span></dt><dd><p class="simpara">Patchwork is a web-based patch tracking system designed to facilitate
  243. the contribution and management of contributions to an open-source
  244. project. Patches that have been sent to a mailing list are 'caught' by
  245. the system, and appear on a web page. Any comments posted that
  246. reference the patch are appended to the patch page too. For more
  247. information on Patchwork see
  248. <a class="ulink" href="http://jk.ozlabs.org/projects/patchwork/" target="_top">http://jk.ozlabs.org/projects/patchwork/</a>.</p><p class="simpara">Buildroot’s Patchwork website is mainly for use by Buildroot’s
  249. maintainer to ensure patches aren’t missed. It is also used by Buildroot
  250. patch reviewers (see also <a class="xref" href="#apply-patches-patchwork" title="22.3.1. Applying Patches from Patchwork">Section 22.3.1, “Applying Patches from Patchwork”</a>).
  251. However, since the website exposes patches and their corresponding
  252. review comments in a clean and concise web interface, it can be useful
  253. for all Buildroot developers.</p><p class="simpara">The Buildroot patch management interface is available at
  254. <a class="ulink" href="http://patchwork.buildroot.org" target="_top">http://patchwork.buildroot.org</a>.</p></dd></dl></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="_user_guide"></a>Part II. User guide</h1></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="configure"></a>Chapter 6. Buildroot configuration</h2></div></div></div><p>All the configuration options in <code class="literal">make *config</code> have a help text
  255. providing details about the option.</p><p>The <code class="literal">make *config</code> commands also offer a search tool. Read the help
  256. message in the different frontend menus to know how to use it:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  257. in <span class="emphasis"><em>menuconfig</em></span>, the search tool is called by pressing <code class="literal">/</code>;
  258. </li><li class="listitem">
  259. in <span class="emphasis"><em>xconfig</em></span>, the search tool is called by pressing <code class="literal">Ctrl</code> + <code class="literal">f</code>.
  260. </li></ul></div><p>The result of the search shows the help message of the matching items.
  261. In <span class="emphasis"><em>menuconfig</em></span>, numbers in the left column provide a shortcut to the
  262. corresponding entry. Just type this number to directly jump to the
  263. entry, or to the containing menu in case the entry is not selectable due
  264. to a missing dependency.</p><p>Although the menu structure and the help text of the entries should be
  265. sufficiently self-explanatory, a number of topics require additional
  266. explanation that cannot easily be covered in the help text and are
  267. therefore covered in the following sections.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_cross_compilation_toolchain"></a>6.1. Cross-compilation toolchain</h2></div></div></div><p>A compilation toolchain is the set of tools that allows you to compile
  268. code for your system. It consists of a compiler (in our case, <code class="literal">gcc</code>),
  269. binary utils like assembler and linker (in our case, <code class="literal">binutils</code>) and a
  270. C standard library (for example
  271. <a class="ulink" href="http://www.gnu.org/software/libc/libc.html" target="_top">GNU Libc</a>,
  272. <a class="ulink" href="http://www.uclibc-ng.org/" target="_top">uClibc-ng</a>).</p><p>The system installed on your development station certainly already has
  273. a compilation toolchain that you can use to compile an application
  274. that runs on your system. If you’re using a PC, your compilation
  275. toolchain runs on an x86 processor and generates code for an x86
  276. processor. Under most Linux systems, the compilation toolchain uses
  277. the GNU libc (glibc) as the C standard library. This compilation
  278. toolchain is called the "host compilation toolchain". The machine on
  279. which it is running, and on which you’re working, is called the "host
  280. system" <a href="#ftn.idm363" class="footnote" id="idm363"><sup class="footnote">[3]</sup></a>.</p><p>The compilation toolchain is provided by your distribution, and
  281. Buildroot has nothing to do with it (other than using it to build a
  282. cross-compilation toolchain and other tools that are run on the
  283. development host).</p><p>As said above, the compilation toolchain that comes with your system
  284. runs on and generates code for the processor in your host system. As
  285. your embedded system has a different processor, you need a
  286. cross-compilation toolchain - a compilation toolchain that runs on
  287. your <span class="emphasis"><em>host system</em></span> but generates code for your <span class="emphasis"><em>target system</em></span> (and
  288. target processor). For example, if your host system uses x86 and your
  289. target system uses ARM, the regular compilation toolchain on your host
  290. runs on x86 and generates code for x86, while the cross-compilation
  291. toolchain runs on x86 and generates code for ARM.</p><p>Buildroot provides two solutions for the cross-compilation toolchain:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  292. The <span class="strong"><strong>internal toolchain backend</strong></span>, called <code class="literal">Buildroot toolchain</code> in
  293. the configuration interface.
  294. </li><li class="listitem">
  295. The <span class="strong"><strong>external toolchain backend</strong></span>, called <code class="literal">External toolchain</code> in
  296. the configuration interface.
  297. </li></ul></div><p>The choice between these two solutions is done using the <code class="literal">Toolchain
  298. Type</code> option in the <code class="literal">Toolchain</code> menu. Once one solution has been
  299. chosen, a number of configuration options appear, they are detailed in
  300. the following sections.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="internal-toolchain-backend"></a>6.1.1. Internal toolchain backend</h3></div></div></div><p>The <span class="emphasis"><em>internal toolchain backend</em></span> is the backend where Buildroot builds
  301. by itself a cross-compilation toolchain, before building the userspace
  302. applications and libraries for your target embedded system.</p><p>This backend supports several C libraries:
  303. <a class="ulink" href="http://www.uclibc-ng.org" target="_top">uClibc-ng</a>,
  304. <a class="ulink" href="http://www.gnu.org/software/libc/libc.html" target="_top">glibc</a> and
  305. <a class="ulink" href="http://www.musl-libc.org" target="_top">musl</a>.</p><p>Once you have selected this backend, a number of options appear. The
  306. most important ones allow to:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  307. Change the version of the Linux kernel headers used to build the
  308. toolchain. This item deserves a few explanations. In the process of
  309. building a cross-compilation toolchain, the C library is being
  310. built. This library provides the interface between userspace
  311. applications and the Linux kernel. In order to know how to "talk"
  312. to the Linux kernel, the C library needs to have access to the
  313. <span class="emphasis"><em>Linux kernel headers</em></span> (i.e. the <code class="literal">.h</code> files from the kernel), which
  314. define the interface between userspace and the kernel (system
  315. calls, data structures, etc.). Since this interface is backward
  316. compatible, the version of the Linux kernel headers used to build
  317. your toolchain do not need to match <span class="emphasis"><em>exactly</em></span> the version of the
  318. Linux kernel you intend to run on your embedded system. They only
  319. need to have a version equal or older to the version of the Linux
  320. kernel you intend to run. If you use kernel headers that are more
  321. recent than the Linux kernel you run on your embedded system, then
  322. the C library might be using interfaces that are not provided by
  323. your Linux kernel.
  324. </li><li class="listitem">
  325. Change the version of the GCC compiler, binutils and the C library.
  326. </li><li class="listitem">
  327. Select a number of toolchain options (uClibc only): whether the
  328. toolchain should have RPC support (used mainly for NFS),
  329. wide-char support, locale support (for internationalization),
  330. C++ support or thread support. Depending on which options you choose,
  331. the number of userspace applications and libraries visible in
  332. Buildroot menus will change: many applications and libraries require
  333. certain toolchain options to be enabled. Most packages show a comment
  334. when a certain toolchain option is required to be able to enable
  335. those packages. If needed, you can further refine the uClibc
  336. configuration by running <code class="literal">make uclibc-menuconfig</code>. Note however that
  337. all packages in Buildroot are tested against the default uClibc
  338. configuration bundled in Buildroot: if you deviate from this
  339. configuration by removing features from uClibc, some packages may no
  340. longer build.
  341. </li></ul></div><p>It is worth noting that whenever one of those options is modified,
  342. then the entire toolchain and system must be rebuilt. See
  343. <a class="xref" href="#full-rebuild" title="8.2. Understanding when a full rebuild is necessary">Section 8.2, “Understanding when a full rebuild is necessary”</a>.</p><p>Advantages of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  344. Well integrated with Buildroot
  345. </li><li class="listitem">
  346. Fast, only builds what’s necessary
  347. </li></ul></div><p>Drawbacks of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  348. Rebuilding the toolchain is needed when doing <code class="literal">make clean</code>, which
  349. takes time. If you’re trying to reduce your build time, consider
  350. using the <span class="emphasis"><em>External toolchain backend</em></span>.
  351. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="external-toolchain-backend"></a>6.1.2. External toolchain backend</h3></div></div></div><p>The <span class="emphasis"><em>external toolchain backend</em></span> allows to use existing pre-built
  352. cross-compilation toolchains. Buildroot knows about a number of
  353. well-known cross-compilation toolchains (from
  354. <a class="ulink" href="http://www.linaro.org" target="_top">Linaro</a> for ARM,
  355. <a class="ulink" href="http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/" target="_top">Sourcery
  356. CodeBench</a> for ARM, x86-64, PowerPC, and MIPS, and is capable of
  357. downloading them automatically, or it can be pointed to a custom
  358. toolchain, either available for download or installed locally.</p><p>Then, you have three solutions to use an external toolchain:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  359. Use a predefined external toolchain profile, and let Buildroot
  360. download, extract and install the toolchain. Buildroot already knows
  361. about a few CodeSourcery and Linaro toolchains. Just select the
  362. toolchain profile in <code class="literal">Toolchain</code> from the available ones. This is
  363. definitely the easiest solution.
  364. </li><li class="listitem">
  365. Use a predefined external toolchain profile, but instead of having
  366. Buildroot download and extract the toolchain, you can tell Buildroot
  367. where your toolchain is already installed on your system. Just
  368. select the toolchain profile in <code class="literal">Toolchain</code> through the available
  369. ones, unselect <code class="literal">Download toolchain automatically</code>, and fill the
  370. <code class="literal">Toolchain path</code> text entry with the path to your cross-compiling
  371. toolchain.
  372. </li><li class="listitem">
  373. Use a completely custom external toolchain. This is particularly
  374. useful for toolchains generated using crosstool-NG or with Buildroot
  375. itself. To do this, select the <code class="literal">Custom toolchain</code> solution in the
  376. <code class="literal">Toolchain</code> list. You need to fill the <code class="literal">Toolchain path</code>, <code class="literal">Toolchain
  377. prefix</code> and <code class="literal">External toolchain C library</code> options. Then, you have
  378. to tell Buildroot what your external toolchain supports. If your
  379. external toolchain uses the <span class="emphasis"><em>glibc</em></span> library, you only have to tell
  380. whether your toolchain supports C++ or not and whether it has
  381. built-in RPC support. If your external toolchain uses the <span class="emphasis"><em>uClibc</em></span>
  382. library, then you have to tell Buildroot if it supports RPC,
  383. wide-char, locale, program invocation, threads and C++.
  384. At the beginning of the execution, Buildroot will tell you if
  385. the selected options do not match the toolchain configuration.
  386. </li></ul></div><p>Our external toolchain support has been tested with toolchains from
  387. CodeSourcery and Linaro, toolchains generated by
  388. <a class="ulink" href="http://crosstool-ng.org" target="_top">crosstool-NG</a>, and toolchains generated by
  389. Buildroot itself. In general, all toolchains that support the
  390. <span class="emphasis"><em>sysroot</em></span> feature should work. If not, do not hesitate to contact the
  391. developers.</p><p>We do not support toolchains or SDK generated by OpenEmbedded or
  392. Yocto, because these toolchains are not pure toolchains (i.e. just the
  393. compiler, binutils, the C and C++ libraries). Instead these toolchains
  394. come with a very large set of pre-compiled libraries and
  395. programs. Therefore, Buildroot cannot import the <span class="emphasis"><em>sysroot</em></span> of the
  396. toolchain, as it would contain hundreds of megabytes of pre-compiled
  397. libraries that are normally built by Buildroot.</p><p>We also do not support using the distribution toolchain (i.e. the
  398. gcc/binutils/C library installed by your distribution) as the
  399. toolchain to build software for the target. This is because your
  400. distribution toolchain is not a "pure" toolchain (i.e. only with the
  401. C/C++ library), so we cannot import it properly into the Buildroot
  402. build environment. So even if you are building a system for a x86 or
  403. x86_64 target, you have to generate a cross-compilation toolchain with
  404. Buildroot or crosstool-NG.</p><p>If you want to generate a custom toolchain for your project, that can
  405. be used as an external toolchain in Buildroot, our recommendation is
  406. to build it either with Buildroot itself (see
  407. <a class="xref" href="#build-toolchain-with-buildroot" title="6.1.3. Build an external toolchain with Buildroot">Section 6.1.3, “Build an external toolchain with Buildroot”</a>) or with
  408. <a class="ulink" href="http://crosstool-ng.org" target="_top">crosstool-NG</a>.</p><p>Advantages of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  409. Allows to use well-known and well-tested cross-compilation
  410. toolchains.
  411. </li><li class="listitem">
  412. Avoids the build time of the cross-compilation toolchain, which is
  413. often very significant in the overall build time of an embedded
  414. Linux system.
  415. </li></ul></div><p>Drawbacks of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  416. If your pre-built external toolchain has a bug, may be hard to get a
  417. fix from the toolchain vendor, unless you build your external
  418. toolchain by yourself using Buildroot or Crosstool-NG.
  419. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build-toolchain-with-buildroot"></a>6.1.3. Build an external toolchain with Buildroot</h3></div></div></div><p>The Buildroot internal toolchain option can be used to create an
  420. external toolchain. Here are a series of steps to build an internal
  421. toolchain and package it up for reuse by Buildroot itself (or other
  422. projects).</p><p>Create a new Buildroot configuration, with the following details:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  423. Select the appropriate <span class="strong"><strong>Target options</strong></span> for your target CPU
  424. architecture
  425. </li><li class="listitem">
  426. In the <span class="strong"><strong>Toolchain</strong></span> menu, keep the default of <span class="strong"><strong>Buildroot toolchain</strong></span>
  427. for <span class="strong"><strong>Toolchain type</strong></span>, and configure your toolchain as desired
  428. </li><li class="listitem">
  429. In the <span class="strong"><strong>System configuration</strong></span> menu, select <span class="strong"><strong>None</strong></span> as the <span class="strong"><strong>Init
  430. system</strong></span> and <span class="strong"><strong>none</strong></span> as <span class="strong"><strong>/bin/sh</strong></span>
  431. </li><li class="listitem">
  432. In the <span class="strong"><strong>Target packages</strong></span> menu, disable <span class="strong"><strong>BusyBox</strong></span>
  433. </li><li class="listitem">
  434. In the <span class="strong"><strong>Filesystem images</strong></span> menu, disable <span class="strong"><strong>tar the root filesystem</strong></span>
  435. </li></ul></div><p>Then, we can trigger the build, and also ask Buildroot to generate a
  436. SDK. This will conveniently generate for us a tarball which contains
  437. our toolchain:</p><pre class="screen">make sdk</pre><p>This produces the SDK tarball in <code class="literal">$(O)/images</code>, with a name similar to
  438. <code class="literal">arm-buildroot-linux-uclibcgnueabi_sdk-buildroot.tar.gz</code>. Save this
  439. tarball, as it is now the toolchain that you can re-use as an external
  440. toolchain in other Buildroot projects.</p><p>In those other Buildroot projects, in the <span class="strong"><strong>Toolchain</strong></span> menu:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  441. Set <span class="strong"><strong>Toolchain type</strong></span> to <span class="strong"><strong>External toolchain</strong></span>
  442. </li><li class="listitem">
  443. Set <span class="strong"><strong>Toolchain</strong></span> to <span class="strong"><strong>Custom toolchain</strong></span>
  444. </li><li class="listitem">
  445. Set <span class="strong"><strong>Toolchain origin</strong></span> to <span class="strong"><strong>Toolchain to be downloaded and installed</strong></span>
  446. </li><li class="listitem">
  447. Set <span class="strong"><strong>Toolchain URL</strong></span> to <code class="literal">file:///path/to/your/sdk/tarball.tar.gz</code>
  448. </li></ul></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_external_toolchain_wrapper"></a>External toolchain wrapper</h4></div></div></div><p>When using an external toolchain, Buildroot generates a wrapper program,
  449. that transparently passes the appropriate options (according to the
  450. configuration) to the external toolchain programs. In case you need to
  451. debug this wrapper to check exactly what arguments are passed, you can
  452. set the environment variable <code class="literal">BR2_DEBUG_WRAPPER</code> to either one of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  453. <code class="literal">0</code>, empty or not set: no debug
  454. </li><li class="listitem">
  455. <code class="literal">1</code>: trace all arguments on a single line
  456. </li><li class="listitem">
  457. <code class="literal">2</code>: trace one argument per line
  458. </li></ul></div></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_dev_management"></a>6.2. /dev management</h2></div></div></div><p>On a Linux system, the <code class="literal">/dev</code> directory contains special files, called
  459. <span class="emphasis"><em>device files</em></span>, that allow userspace applications to access the
  460. hardware devices managed by the Linux kernel. Without these <span class="emphasis"><em>device
  461. files</em></span>, your userspace applications would not be able to use the
  462. hardware devices, even if they are properly recognized by the Linux
  463. kernel.</p><p>Under <code class="literal">System configuration</code>, <code class="literal">/dev management</code>, Buildroot offers four
  464. different solutions to handle the <code class="literal">/dev</code> directory :</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  465. The first solution is <span class="strong"><strong>Static using device table</strong></span>. This is the old
  466. classical way of handling device files in Linux. With this method,
  467. the device files are persistently stored in the root filesystem
  468. (i.e. they persist across reboots), and there is nothing that will
  469. automatically create and remove those device files when hardware
  470. devices are added or removed from the system. Buildroot therefore
  471. creates a standard set of device files using a <span class="emphasis"><em>device table</em></span>, the
  472. default one being stored in <code class="literal">system/device_table_dev.txt</code> in the
  473. Buildroot source code. This file is processed when Buildroot
  474. generates the final root filesystem image, and the <span class="emphasis"><em>device files</em></span>
  475. are therefore not visible in the <code class="literal">output/target</code> directory. The
  476. <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code> option allows to change the
  477. default device table used by Buildroot, or to add an additional
  478. device table, so that additional <span class="emphasis"><em>device files</em></span> are created by
  479. Buildroot during the build. So, if you use this method, and a
  480. <span class="emphasis"><em>device file</em></span> is missing in your system, you can for example create
  481. a <code class="literal">board/&lt;yourcompany&gt;/&lt;yourproject&gt;/device_table_dev.txt</code> file
  482. that contains the description of your additional <span class="emphasis"><em>device files</em></span>,
  483. and then you can set <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code> to
  484. <code class="literal">system/device_table_dev.txt
  485. board/&lt;yourcompany&gt;/&lt;yourproject&gt;/device_table_dev.txt</code>. For more
  486. details about the format of the device table file, see
  487. <a class="xref" href="#makedev-syntax" title="Chapter 25. Makedev syntax documentation">Chapter 25, <em>Makedev syntax documentation</em></a>.
  488. </li><li class="listitem">
  489. The second solution is <span class="strong"><strong>Dynamic using devtmpfs only</strong></span>. <span class="emphasis"><em>devtmpfs</em></span> is
  490. a virtual filesystem inside the Linux kernel that has been
  491. introduced in kernel 2.6.32 (if you use an older kernel, it is not
  492. possible to use this option). When mounted in <code class="literal">/dev</code>, this virtual
  493. filesystem will automatically make <span class="emphasis"><em>device files</em></span> appear and
  494. disappear as hardware devices are added and removed from the
  495. system. This filesystem is not persistent across reboots: it is
  496. filled dynamically by the kernel. Using <span class="emphasis"><em>devtmpfs</em></span> requires the
  497. following kernel configuration options to be enabled:
  498. <code class="literal">CONFIG_DEVTMPFS</code> and <code class="literal">CONFIG_DEVTMPFS_MOUNT</code>. When Buildroot is in
  499. charge of building the Linux kernel for your embedded device, it
  500. makes sure that those two options are enabled. However, if you
  501. build your Linux kernel outside of Buildroot, then it is your
  502. responsibility to enable those two options (if you fail to do so,
  503. your Buildroot system will not boot).
  504. </li><li class="listitem">
  505. The third solution is <span class="strong"><strong>Dynamic using devtmpfs + mdev</strong></span>. This method
  506. also relies on the <span class="emphasis"><em>devtmpfs</em></span> virtual filesystem detailed above (so
  507. the requirement to have <code class="literal">CONFIG_DEVTMPFS</code> and
  508. <code class="literal">CONFIG_DEVTMPFS_MOUNT</code> enabled in the kernel configuration still
  509. apply), but adds the <code class="literal">mdev</code> userspace utility on top of it. <code class="literal">mdev</code>
  510. is a program part of BusyBox that the kernel will call every time a
  511. device is added or removed. Thanks to the <code class="literal">/etc/mdev.conf</code>
  512. configuration file, <code class="literal">mdev</code> can be configured to for example, set
  513. specific permissions or ownership on a device file, call a script
  514. or application whenever a device appears or disappear,
  515. etc. Basically, it allows <span class="emphasis"><em>userspace</em></span> to react on device addition
  516. and removal events. <code class="literal">mdev</code> can for example be used to automatically
  517. load kernel modules when devices appear on the system. <code class="literal">mdev</code> is
  518. also important if you have devices that require a firmware, as it
  519. will be responsible for pushing the firmware contents to the
  520. kernel. <code class="literal">mdev</code> is a lightweight implementation (with fewer
  521. features) of <code class="literal">udev</code>. For more details about <code class="literal">mdev</code> and the syntax
  522. of its configuration file, see
  523. <a class="ulink" href="http://git.busybox.net/busybox/tree/docs/mdev.txt" target="_top">http://git.busybox.net/busybox/tree/docs/mdev.txt</a>.
  524. </li><li class="listitem">
  525. The fourth solution is <span class="strong"><strong>Dynamic using devtmpfs + eudev</strong></span>. This
  526. method also relies on the <span class="emphasis"><em>devtmpfs</em></span> virtual filesystem detailed
  527. above, but adds the <code class="literal">eudev</code> userspace daemon on top of it. <code class="literal">eudev</code>
  528. is a daemon that runs in the background, and gets called by the
  529. kernel when a device gets added or removed from the system. It is a
  530. more heavyweight solution than <code class="literal">mdev</code>, but provides higher
  531. flexibility. <code class="literal">eudev</code> is a standalone version of <code class="literal">udev</code>, the
  532. original userspace daemon used in most desktop Linux distributions,
  533. which is now part of Systemd. For more details, see
  534. <a class="ulink" href="http://en.wikipedia.org/wiki/Udev" target="_top">http://en.wikipedia.org/wiki/Udev</a>.
  535. </li></ul></div><p>The Buildroot developers recommendation is to start with the <span class="strong"><strong>Dynamic
  536. using devtmpfs only</strong></span> solution, until you have the need for userspace
  537. to be notified when devices are added/removed, or if firmwares are
  538. needed, in which case <span class="strong"><strong>Dynamic using devtmpfs + mdev</strong></span> is usually a
  539. good solution.</p><p>Note that if <code class="literal">systemd</code> is chosen as init system, /dev management will
  540. be performed by the <code class="literal">udev</code> program provided by <code class="literal">systemd</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_init_system"></a>6.3. init system</h2></div></div></div><p>The <span class="emphasis"><em>init</em></span> program is the first userspace program started by the
  541. kernel (it carries the PID number 1), and is responsible for starting
  542. the userspace services and programs (for example: web server,
  543. graphical applications, other network servers, etc.).</p><p>Buildroot allows to use three different types of init systems, which
  544. can be chosen from <code class="literal">System configuration</code>, <code class="literal">Init system</code>:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  545. The first solution is <span class="strong"><strong>BusyBox</strong></span>. Amongst many programs, BusyBox has
  546. an implementation of a basic <code class="literal">init</code> program, which is sufficient
  547. for most embedded systems. Enabling the <code class="literal">BR2_INIT_BUSYBOX</code> will
  548. ensure BusyBox will build and install its <code class="literal">init</code> program. This is
  549. the default solution in Buildroot. The BusyBox <code class="literal">init</code> program will
  550. read the <code class="literal">/etc/inittab</code> file at boot to know what to do. The syntax
  551. of this file can be found in
  552. <a class="ulink" href="http://git.busybox.net/busybox/tree/examples/inittab" target="_top">http://git.busybox.net/busybox/tree/examples/inittab</a> (note that
  553. BusyBox <code class="literal">inittab</code> syntax is special: do not use a random <code class="literal">inittab</code>
  554. documentation from the Internet to learn about BusyBox
  555. <code class="literal">inittab</code>). The default <code class="literal">inittab</code> in Buildroot is stored in
  556. <code class="literal">system/skeleton/etc/inittab</code>. Apart from mounting a few important
  557. filesystems, the main job the default inittab does is to start the
  558. <code class="literal">/etc/init.d/rcS</code> shell script, and start a <code class="literal">getty</code> program (which
  559. provides a login prompt).
  560. </li><li class="listitem">
  561. The second solution is <span class="strong"><strong>systemV</strong></span>. This solution uses the old
  562. traditional <span class="emphasis"><em>sysvinit</em></span> program, packed in Buildroot in
  563. <code class="literal">package/sysvinit</code>. This was the solution used in most desktop
  564. Linux distributions, until they switched to more recent
  565. alternatives such as Upstart or Systemd. <code class="literal">sysvinit</code> also works with
  566. an <code class="literal">inittab</code> file (which has a slightly different syntax than the
  567. one from BusyBox). The default <code class="literal">inittab</code> installed with this init
  568. solution is located in <code class="literal">package/sysvinit/inittab</code>.
  569. </li><li class="listitem">
  570. The third solution is <span class="strong"><strong>systemd</strong></span>. <code class="literal">systemd</code> is the new generation
  571. init system for Linux. It does far more than traditional <span class="emphasis"><em>init</em></span>
  572. programs: aggressive parallelization capabilities, uses socket and
  573. D-Bus activation for starting services, offers on-demand starting
  574. of daemons, keeps track of processes using Linux control groups,
  575. supports snapshotting and restoring of the system state,
  576. etc. <code class="literal">systemd</code> will be useful on relatively complex embedded
  577. systems, for example the ones requiring D-Bus and services
  578. communicating between each other. It is worth noting that <code class="literal">systemd</code>
  579. brings a fairly big number of large dependencies: <code class="literal">dbus</code>, <code class="literal">udev</code>
  580. and more. For more details about <code class="literal">systemd</code>, see
  581. <a class="ulink" href="http://www.freedesktop.org/wiki/Software/systemd" target="_top">http://www.freedesktop.org/wiki/Software/systemd</a>.
  582. </li></ul></div><p>The solution recommended by Buildroot developers is to use the
  583. <span class="strong"><strong>BusyBox init</strong></span> as it is sufficient for most embedded
  584. systems. <span class="strong"><strong>systemd</strong></span> can be used for more complex situations.</p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm363" class="footnote"><p><a href="#idm363" class="simpara"><sup class="simpara">[3] </sup></a>This terminology differs from what is used by GNU
  585. configure, where the host is the machine on which the application will
  586. run (which is usually the same as target)</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_configuration_of_other_components"></a>Chapter 7. Configuration of other components</h2></div></div></div><p>Before attempting to modify any of the components below, make sure you
  587. have already configured Buildroot itself, and have enabled the
  588. corresponding package.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
  589. BusyBox
  590. </span></dt><dd><p class="simpara">If you already have a BusyBox configuration file, you can directly
  591. specify this file in the Buildroot configuration, using
  592. <code class="literal">BR2_PACKAGE_BUSYBOX_CONFIG</code>. Otherwise, Buildroot will start from a
  593. default BusyBox configuration file.</p><p class="simpara">To make subsequent changes to the configuration, use <code class="literal">make
  594. busybox-menuconfig</code> to open the BusyBox configuration editor.</p><p class="simpara">It is also possible to specify a BusyBox configuration file through an
  595. environment variable, although this is not recommended. Refer to
  596. <a class="xref" href="#env-vars" title="8.6. Environment variables">Section 8.6, “Environment variables”</a> for more details.</p></dd><dt><span class="term">
  597. uClibc
  598. </span></dt><dd>Configuration of uClibc is done in the same way as for BusyBox. The
  599. configuration variable to specify an existing configuration file is
  600. <code class="literal">BR2_UCLIBC_CONFIG</code>. The command to make subsequent changes is <code class="literal">make
  601. uclibc-menuconfig</code>.</dd><dt><span class="term">
  602. Linux kernel
  603. </span></dt><dd><p class="simpara">If you already have a kernel configuration file, you can directly
  604. specify this file in the Buildroot configuration, using
  605. <code class="literal">BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG</code>.</p><p class="simpara">If you do not yet have a kernel configuration file, you can either start
  606. by specifying a defconfig in the Buildroot configuration, using
  607. <code class="literal">BR2_LINUX_KERNEL_USE_DEFCONFIG</code>, or start by creating an empty file and
  608. specifying it as custom configuration file, using
  609. <code class="literal">BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG</code>.</p><p class="simpara">To make subsequent changes to the configuration, use <code class="literal">make
  610. linux-menuconfig</code> to open the Linux configuration editor.</p></dd><dt><span class="term">
  611. Barebox
  612. </span></dt><dd>Configuration of Barebox is done in the same way as for the Linux
  613. kernel. The corresponding configuration variables are
  614. <code class="literal">BR2_TARGET_BAREBOX_USE_CUSTOM_CONFIG</code> and
  615. <code class="literal">BR2_TARGET_BAREBOX_USE_DEFCONFIG</code>. To open the configuration editor,
  616. use <code class="literal">make barebox-menuconfig</code>.</dd><dt><span class="term">
  617. U-Boot
  618. </span></dt><dd>Configuration of U-Boot (version 2015.04 or newer) is done in the same
  619. way as for the Linux kernel. The corresponding configuration variables
  620. are <code class="literal">BR2_TARGET_UBOOT_USE_CUSTOM_CONFIG</code> and
  621. <code class="literal">BR2_TARGET_UBOOT_USE_DEFCONFIG</code>. To open the configuration editor,
  622. use <code class="literal">make uboot-menuconfig</code>.</dd></dl></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_general_buildroot_usage"></a>Chapter 8. General Buildroot usage</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="make-tips"></a>8.1. <span class="emphasis"><em>make</em></span> tips</h2></div></div></div><p>This is a collection of tips that help you make the most of Buildroot.</p><p><strong>Display all commands executed by make: </strong>
  623. </p><pre class="screen"> $ make V=1 &lt;target&gt;</pre><p>
  624. </p><p><strong>Display the list of boards with a defconfig: </strong>
  625. </p><pre class="screen"> $ make list-defconfigs</pre><p>
  626. </p><p><strong>Display all available targets: </strong>
  627. </p><pre class="screen"> $ make help</pre><p>
  628. </p><p>Not all targets are always available,
  629. some settings in the <code class="literal">.config</code> file may hide some targets:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  630. <code class="literal">busybox-menuconfig</code> only works when <code class="literal">busybox</code> is enabled;
  631. </li><li class="listitem">
  632. <code class="literal">linux-menuconfig</code> and <code class="literal">linux-savedefconfig</code> only work when
  633. <code class="literal">linux</code> is enabled;
  634. </li><li class="listitem">
  635. <code class="literal">uclibc-menuconfig</code> is only available when the uClibc C library is
  636. selected in the internal toolchain backend;
  637. </li><li class="listitem">
  638. <code class="literal">barebox-menuconfig</code> and <code class="literal">barebox-savedefconfig</code> only work when the
  639. <code class="literal">barebox</code> bootloader is enabled.
  640. </li><li class="listitem">
  641. <code class="literal">uboot-menuconfig</code> and <code class="literal">uboot-savedefconfig</code> only work when the
  642. <code class="literal">U-Boot</code> bootloader is enabled.
  643. </li></ul></div><p><strong>Cleaning: </strong>Explicit cleaning is required when any of the architecture or toolchain
  644. configuration options are changed.</p><p>To delete all build products (including build directories, host, staging
  645. and target trees, the images and the toolchain):</p><pre class="screen"> $ make clean</pre><p><strong>Generating the manual: </strong>The present manual sources are located in the <span class="emphasis"><em>docs/manual</em></span> directory.
  646. To generate the manual:</p><pre class="screen"> $ make manual-clean
  647. $ make manual</pre><p>The manual outputs will be generated in <span class="emphasis"><em>output/docs/manual</em></span>.</p><div class="itemizedlist"><p class="title"><strong>Notes</strong></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  648. A few tools are required to build the documentation (see:
  649. <a class="xref" href="#requirement-optional" title="2.2. Optional packages">Section 2.2, “Optional packages”</a>).
  650. </li></ul></div><p><strong>Resetting Buildroot for a new target: </strong>To delete all build products as well as the configuration:</p><pre class="screen"> $ make distclean</pre><p><strong>Notes. </strong>If <code class="literal">ccache</code> is enabled, running <code class="literal">make clean</code> or <code class="literal">distclean</code> does
  651. not empty the compiler cache used by Buildroot. To delete it, refer
  652. to <a class="xref" href="#ccache" title="8.14.3. Using ccache in Buildroot">Section 8.14.3, “Using <code class="literal">ccache</code> in Buildroot”</a>.</p><p><strong>Dumping the internal make variables: </strong>One can dump the variables known to make, along with their values:</p><pre class="screen"> $ make -s printvars VARS='VARIABLE1 VARIABLE2'
  653. VARIABLE1=value_of_variable
  654. VARIABLE2=value_of_variable</pre><p>It is possible to tweak the output using some variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  655. <code class="literal">VARS</code> will limit the listing to variables which names match the
  656. specified make-patterns - this must be set else nothing is printed
  657. </li><li class="listitem">
  658. <code class="literal">QUOTED_VARS</code>, if set to <code class="literal">YES</code>, will single-quote the value
  659. </li><li class="listitem">
  660. <code class="literal">RAW_VARS</code>, if set to <code class="literal">YES</code>, will print the unexpanded value
  661. </li></ul></div><p>For example:</p><pre class="screen"> $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES
  662. BUSYBOX_DEPENDENCIES=skeleton toolchain
  663. BUSYBOX_FINAL_ALL_DEPENDENCIES=skeleton toolchain
  664. BUSYBOX_FINAL_DEPENDENCIES=skeleton toolchain
  665. BUSYBOX_FINAL_PATCH_DEPENDENCIES=
  666. BUSYBOX_RDEPENDENCIES=ncurses util-linux</pre><pre class="screen"> $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES QUOTED_VARS=YES
  667. BUSYBOX_DEPENDENCIES='skeleton toolchain'
  668. BUSYBOX_FINAL_ALL_DEPENDENCIES='skeleton toolchain'
  669. BUSYBOX_FINAL_DEPENDENCIES='skeleton toolchain'
  670. BUSYBOX_FINAL_PATCH_DEPENDENCIES=''
  671. BUSYBOX_RDEPENDENCIES='ncurses util-linux'</pre><pre class="screen"> $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES RAW_VARS=YES
  672. BUSYBOX_DEPENDENCIES=skeleton toolchain
  673. BUSYBOX_FINAL_ALL_DEPENDENCIES=$(sort $(BUSYBOX_FINAL_DEPENDENCIES) $(BUSYBOX_FINAL_PATCH_DEPENDENCIES))
  674. BUSYBOX_FINAL_DEPENDENCIES=$(sort $(BUSYBOX_DEPENDENCIES))
  675. BUSYBOX_FINAL_PATCH_DEPENDENCIES=$(sort $(BUSYBOX_PATCH_DEPENDENCIES))
  676. BUSYBOX_RDEPENDENCIES=ncurses util-linux</pre><p>The output of quoted variables can be reused in shell scripts, for example:</p><pre class="screen"> $ eval $(make -s printvars VARS=BUSYBOX_DEPENDENCIES QUOTED_VARS=YES)
  677. $ echo $BUSYBOX_DEPENDENCIES
  678. skeleton toolchain</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="full-rebuild"></a>8.2. Understanding when a full rebuild is necessary</h2></div></div></div><p>Buildroot does not attempt to detect what parts of the system should
  679. be rebuilt when the system configuration is changed through <code class="literal">make
  680. menuconfig</code>, <code class="literal">make xconfig</code> or one of the other configuration
  681. tools. In some cases, Buildroot should rebuild the entire system, in
  682. some cases, only a specific subset of packages. But detecting this in
  683. a completely reliable manner is very difficult, and therefore the
  684. Buildroot developers have decided to simply not attempt to do this.</p><p>Instead, it is the responsibility of the user to know when a full
  685. rebuild is necessary. As a hint, here are a few rules of thumb that
  686. can help you understand how to work with Buildroot:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  687. When the target architecture configuration is changed, a complete
  688. rebuild is needed. Changing the architecture variant, the binary
  689. format or the floating point strategy for example has an impact on
  690. the entire system.
  691. </li><li class="listitem">
  692. When the toolchain configuration is changed, a complete rebuild
  693. generally is needed. Changing the toolchain configuration often
  694. involves changing the compiler version, the type of C library or
  695. its configuration, or some other fundamental configuration item,
  696. and these changes have an impact on the entire system.
  697. </li><li class="listitem">
  698. When an additional package is added to the configuration, a full
  699. rebuild is not necessarily needed. Buildroot will detect that this
  700. package has never been built, and will build it. However, if this
  701. package is a library that can optionally be used by packages that
  702. have already been built, Buildroot will not automatically rebuild
  703. those. Either you know which packages should be rebuilt, and you
  704. can rebuild them manually, or you should do a full rebuild. For
  705. example, let’s suppose you have built a system with the <code class="literal">ctorrent</code>
  706. package, but without <code class="literal">openssl</code>. Your system works, but you realize
  707. you would like to have SSL support in <code class="literal">ctorrent</code>, so you enable the
  708. <code class="literal">openssl</code> package in Buildroot configuration and restart the
  709. build. Buildroot will detect that <code class="literal">openssl</code> should be built and
  710. will be build it, but it will not detect that <code class="literal">ctorrent</code> should be
  711. rebuilt to benefit from <code class="literal">openssl</code> to add OpenSSL support. You will
  712. either have to do a full rebuild, or rebuild <code class="literal">ctorrent</code> itself.
  713. </li><li class="listitem">
  714. When a package is removed from the configuration, Buildroot does
  715. not do anything special. It does not remove the files installed by
  716. this package from the target root filesystem or from the toolchain
  717. <span class="emphasis"><em>sysroot</em></span>. A full rebuild is needed to get rid of this
  718. package. However, generally you don’t necessarily need this package
  719. to be removed right now: you can wait for the next lunch break to
  720. restart the build from scratch.
  721. </li><li class="listitem">
  722. When the sub-options of a package are changed, the package is not
  723. automatically rebuilt. After making such changes, rebuilding only
  724. this package is often sufficient, unless enabling the package
  725. sub-option adds some features to the package that are useful for
  726. another package which has already been built. Again, Buildroot does
  727. not track when a package should be rebuilt: once a package has been
  728. built, it is never rebuilt unless explicitly told to do so.
  729. </li><li class="listitem">
  730. When a change to the root filesystem skeleton is made, a full
  731. rebuild is needed. However, when changes to the root filesystem
  732. overlay, a post-build script or a post-image script are made,
  733. there is no need for a full rebuild: a simple <code class="literal">make</code> invocation
  734. will take the changes into account.
  735. </li><li class="listitem">
  736. When a package listed in <code class="literal">FOO_DEPENDENCIES</code> is rebuilt or removed,
  737. the package <code class="literal">foo</code> is not automatically rebuilt. For example, if a
  738. package <code class="literal">bar</code> is listed in <code class="literal">FOO_DEPENDENCIES</code> with <code class="literal">FOO_DEPENDENCIES
  739. = bar</code> and the configuration of the <code class="literal">bar</code> package is changed, the
  740. configuration change would not result in a rebuild of package <code class="literal">foo</code>
  741. automatically. In this scenario, you may need to either rebuild any
  742. packages in your build which reference <code class="literal">bar</code> in their <code class="literal">DEPENDENCIES</code>,
  743. or perform a full rebuild to ensure any <code class="literal">bar</code> dependent packages are
  744. up to date.
  745. </li></ul></div><p>Generally speaking, when you’re facing a build error and you’re unsure
  746. of the potential consequences of the configuration changes you’ve
  747. made, do a full rebuild. If you get the same build error, then you are
  748. sure that the error is not related to partial rebuilds of packages,
  749. and if this error occurs with packages from the official Buildroot, do
  750. not hesitate to report the problem! As your experience with Buildroot
  751. progresses, you will progressively learn when a full rebuild is really
  752. necessary, and you will save more and more time.</p><p>For reference, a full rebuild is achieved by running:</p><pre class="screen">$ make clean all</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="rebuild-pkg"></a>8.3. Understanding how to rebuild packages</h2></div></div></div><p>One of the most common questions asked by Buildroot users is how to
  753. rebuild a given package or how to remove a package without rebuilding
  754. everything from scratch.</p><p>Removing a package is unsupported by Buildroot without
  755. rebuilding from scratch. This is because Buildroot doesn’t keep track
  756. of which package installs what files in the <code class="literal">output/staging</code> and
  757. <code class="literal">output/target</code> directories, or which package would be compiled differently
  758. depending on the availability of another package.</p><p>The easiest way to rebuild a single package from scratch is to remove
  759. its build directory in <code class="literal">output/build</code>. Buildroot will then re-extract,
  760. re-configure, re-compile and re-install this package from scratch. You
  761. can ask buildroot to do this with the <code class="literal">make &lt;package&gt;-dirclean</code> command.</p><p>On the other hand, if you only want to restart the build process of a
  762. package from its compilation step, you can run <code class="literal">make &lt;package&gt;-rebuild</code>. It
  763. will restart the compilation and installation of the package, but not from
  764. scratch: it basically re-executes <code class="literal">make</code> and <code class="literal">make install</code> inside the package,
  765. so it will only rebuild files that changed.</p><p>If you want to restart the build process of a package from its configuration
  766. step, you can run <code class="literal">make &lt;package&gt;-reconfigure</code>. It will restart the
  767. configuration, compilation and installation of the package.</p><p>While <code class="literal">&lt;package&gt;-rebuild</code> implies <code class="literal">&lt;package&gt;-reinstall</code> and
  768. <code class="literal">&lt;package&gt;-reconfigure</code> implies <code class="literal">&lt;package&gt;-rebuild</code>, these targets as well
  769. as <code class="literal">&lt;package&gt;</code> only act on the said package, and do not trigger re-creating
  770. the root filesystem image. If re-creating the root filesystem in necessary,
  771. one should in addition run <code class="literal">make</code> or <code class="literal">make all</code>.</p><p>Internally, Buildroot creates so-called <span class="emphasis"><em>stamp files</em></span> to keep track of
  772. which build steps have been completed for each package. They are
  773. stored in the package build directory,
  774. <code class="literal">output/build/&lt;package&gt;-&lt;version&gt;/</code> and are named
  775. <code class="literal">.stamp_&lt;step-name&gt;</code>. The commands detailed above simply manipulate
  776. these stamp files to force Buildroot to restart a specific set of
  777. steps of a package build process.</p><p>Further details about package special make targets are explained in
  778. <a class="xref" href="#pkg-build-steps" title="8.14.5. Package-specific make targets">Section 8.14.5, “Package-specific <span class="emphasis"><em>make</em></span> targets”</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_offline_builds"></a>8.4. Offline builds</h2></div></div></div><p>If you intend to do an offline build and just want to download
  779. all sources that you previously selected in the configurator
  780. (<span class="emphasis"><em>menuconfig</em></span>, <span class="emphasis"><em>nconfig</em></span>, <span class="emphasis"><em>xconfig</em></span> or <span class="emphasis"><em>gconfig</em></span>), then issue:</p><pre class="screen"> $ make source</pre><p>You can now disconnect or copy the content of your <code class="literal">dl</code>
  781. directory to the build-host.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_building_out_of_tree"></a>8.5. Building out-of-tree</h2></div></div></div><p>As default, everything built by Buildroot is stored in the directory
  782. <code class="literal">output</code> in the Buildroot tree.</p><p>Buildroot also supports building out of tree with a syntax similar to
  783. the Linux kernel. To use it, add <code class="literal">O=&lt;directory&gt;</code> to the make command
  784. line:</p><pre class="screen"> $ make O=/tmp/build</pre><p>Or:</p><pre class="screen"> $ cd /tmp/build; make O=$PWD -C path/to/buildroot</pre><p>All the output files will be located under <code class="literal">/tmp/build</code>. If the <code class="literal">O</code>
  785. path does not exist, Buildroot will create it.</p><p><span class="strong"><strong>Note:</strong></span> the <code class="literal">O</code> path can be either an absolute or a relative path, but if it’s
  786. passed as a relative path, it is important to note that it is interpreted
  787. relative to the main Buildroot source directory, <span class="strong"><strong>not</strong></span> the current working
  788. directory.</p><p>When using out-of-tree builds, the Buildroot <code class="literal">.config</code> and temporary
  789. files are also stored in the output directory. This means that you can
  790. safely run multiple builds in parallel using the same source tree as
  791. long as they use unique output directories.</p><p>For ease of use, Buildroot generates a Makefile wrapper in the output
  792. directory - so after the first run, you no longer need to pass <code class="literal">O=&lt;…&gt;</code>
  793. and <code class="literal">-C &lt;…&gt;</code>, simply run (in the output directory):</p><pre class="screen"> $ make &lt;target&gt;</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="env-vars"></a>8.6. Environment variables</h2></div></div></div><p>Buildroot also honors some environment variables, when they are passed
  794. to <code class="literal">make</code> or set in the environment:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  795. <code class="literal">HOSTCXX</code>, the host C++ compiler to use
  796. </li><li class="listitem">
  797. <code class="literal">HOSTCC</code>, the host C compiler to use
  798. </li><li class="listitem">
  799. <code class="literal">UCLIBC_CONFIG_FILE=&lt;path/to/.config&gt;</code>, path to
  800. the uClibc configuration file, used to compile uClibc, if an
  801. internal toolchain is being built.
  802. Note that the uClibc configuration file can also be set from the
  803. configuration interface, so through the Buildroot <code class="literal">.config</code> file; this
  804. is the recommended way of setting it.
  805. </li><li class="listitem">
  806. <code class="literal">BUSYBOX_CONFIG_FILE=&lt;path/to/.config&gt;</code>, path to
  807. the BusyBox configuration file.
  808. Note that the BusyBox configuration file can also be set from the
  809. configuration interface, so through the Buildroot <code class="literal">.config</code> file; this
  810. is the recommended way of setting it.
  811. </li><li class="listitem">
  812. <code class="literal">BR2_CCACHE_DIR</code> to override the directory where
  813. Buildroot stores the cached files when using ccache.
  814. </li><li class="listitem">
  815. <code class="literal">BR2_DL_DIR</code> to override the directory in which
  816. Buildroot stores/retrieves downloaded files.
  817. Note that the Buildroot download directory can also be set from the
  818. configuration interface, so through the Buildroot <code class="literal">.config</code> file. See
  819. <a class="xref" href="#download-location" title="8.14.4. Location of downloaded packages">Section 8.14.4, “Location of downloaded packages”</a> for more details on how you can set the download
  820. directory.
  821. </li><li class="listitem">
  822. <code class="literal">BR2_GRAPH_ALT</code>, if set and non-empty, to use an alternate color-scheme in
  823. build-time graphs
  824. </li><li class="listitem">
  825. <code class="literal">BR2_GRAPH_OUT</code> to set the filetype of generated graphs, either <code class="literal">pdf</code> (the
  826. default), or <code class="literal">png</code>.
  827. </li><li class="listitem">
  828. <code class="literal">BR2_GRAPH_DEPS_OPTS</code> to pass extra options to the dependency graph; see
  829. <a class="xref" href="#graph-depends">Section 8.9, “Graphing the dependencies between packages”</a> for the accepted options
  830. </li><li class="listitem">
  831. <code class="literal">BR2_GRAPH_DOT_OPTS</code> is passed verbatim as options to the <code class="literal">dot</code> utility to
  832. draw the dependency graph.
  833. </li><li class="listitem">
  834. <code class="literal">BR2_GRAPH_SIZE_OPTS</code> to pass extra options to the size graph; see
  835. <a class="xref" href="#graph-size" title="8.11. Graphing the filesystem size contribution of packages">Section 8.11, “Graphing the filesystem size contribution of packages”</a> for the acepted options
  836. </li></ul></div><p>An example that uses config files located in the toplevel directory and
  837. in your $HOME:</p><pre class="screen"> $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config</pre><p>If you want to use a compiler other than the default <code class="literal">gcc</code>
  838. or <code class="literal">g</code>++ for building helper-binaries on your host, then do</p><pre class="screen"> $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_dealing_efficiently_with_filesystem_images"></a>8.7. Dealing efficiently with filesystem images</h2></div></div></div><p>Filesystem images can get pretty big, depending on the filesystem you choose,
  839. the number of packages, whether you provisioned free space… Yet, some
  840. locations in the filesystems images may just be <span class="emphasis"><em>empty</em></span> (e.g. a long run of
  841. <span class="emphasis"><em>zeroes</em></span>); such a file is called a <span class="emphasis"><em>sparse</em></span> file.</p><p>Most tools can handle sparse files efficiently, and will only store or write
  842. those parts of a sparse file that are not empty.</p><p>For example:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  843. <code class="literal">tar</code> accepts the <code class="literal">-S</code> option to tell it to only store non-zero blocks
  844. of sparse files:
  845. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  846. <code class="literal">tar cf archive.tar -S [files…]</code> will efficiently store sparse files
  847. in a tarball
  848. </li><li class="listitem">
  849. <code class="literal">tar xf archive.tar -S</code> will efficiently store sparse files extracted
  850. from a tarball
  851. </li></ul></div></li><li class="listitem"><p class="simpara">
  852. <code class="literal">cp</code> accepts the <code class="literal">--sparse=WHEN</code> option (<code class="literal">WHEN</code> is one of <code class="literal">auto</code>,
  853. <code class="literal">never</code> or <code class="literal">always</code>):
  854. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  855. <code class="literal">cp --sparse=always source.file dest.file</code> will make <code class="literal">dest.file</code> a
  856. sparse file if <code class="literal">source.file</code> has long runs of zeroes
  857. </li></ul></div></li></ul></div><p>Other tools may have similar options. Please consult their respective man
  858. pages.</p><p>You can use sparse files if you need to store the filesystem images (e.g.
  859. to transfer from one machine to another), or if you need to send them (e.g.
  860. to the Q&amp;A team).</p><p>Note however that flashing a filesystem image to a device while using the
  861. sparse mode of <code class="literal">dd</code> may result in a broken filesystem (e.g. the block bitmap
  862. of an ext2 filesystem may be corrupted; or, if you have sparse files in
  863. your filesystem, those parts may not be all-zeroes when read back). You
  864. should only use sparse files when handling files on the build machine, not
  865. when transferring them to an actual device that will be used on the target.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_details_about_packages"></a>8.8. Details about packages</h2></div></div></div><p><a id="package-details"></a>Buildroot can produce a JSON blurb that describes the set of enabled
  866. packages in the current configuration, together with their
  867. dependencies, licenses and other metadata. This JSON blurb is produced
  868. by using the <code class="literal">show-info</code> make target:</p><pre class="screen">make show-info</pre><p>Buildroot can also produce details about packages as HTML and JSON
  869. output using the <code class="literal">pkg-stats</code> make target. Amongst other things, these
  870. details include whether known CVEs (security vulnerabilities) affect
  871. the packages in your current configuration. It also shows if there is
  872. a newer upstream version for those packages.</p><pre class="screen">make pkg-stats</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_graphing_the_dependencies_between_packages"></a>8.9. Graphing the dependencies between packages</h2></div></div></div><p><a id="graph-depends"></a>One of Buildroot’s jobs is to know the dependencies between packages,
  873. and make sure they are built in the right order. These dependencies
  874. can sometimes be quite complicated, and for a given system, it is
  875. often not easy to understand why such or such package was brought into
  876. the build by Buildroot.</p><p>In order to help understanding the dependencies, and therefore better
  877. understand what is the role of the different components in your
  878. embedded Linux system, Buildroot is capable of generating dependency
  879. graphs.</p><p>To generate a dependency graph of the full system you have compiled,
  880. simply run:</p><pre class="screen">make graph-depends</pre><p>You will find the generated graph in
  881. <code class="literal">output/graphs/graph-depends.pdf</code>.</p><p>If your system is quite large, the dependency graph may be too complex
  882. and difficult to read. It is therefore possible to generate the
  883. dependency graph just for a given package:</p><pre class="screen">make &lt;pkg&gt;-graph-depends</pre><p>You will find the generated graph in
  884. <code class="literal">output/graph/&lt;pkg&gt;-graph-depends.pdf</code>.</p><p>Note that the dependency graphs are generated using the <code class="literal">dot</code> tool
  885. from the <span class="emphasis"><em>Graphviz</em></span> project, which you must have installed on your
  886. system to use this feature. In most distributions, it is available as
  887. the <code class="literal">graphviz</code> package.</p><p>By default, the dependency graphs are generated in the PDF
  888. format. However, by passing the <code class="literal">BR2_GRAPH_OUT</code> environment variable, you
  889. can switch to other output formats, such as PNG, PostScript or
  890. SVG. All formats supported by the <code class="literal">-T</code> option of the <code class="literal">dot</code> tool are
  891. supported.</p><pre class="screen">BR2_GRAPH_OUT=svg make graph-depends</pre><p>The <code class="literal">graph-depends</code> behaviour can be controlled by setting options in the
  892. <code class="literal">BR2_GRAPH_DEPS_OPTS</code> environment variable. The accepted options are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  893. <code class="literal">--depth N</code>, <code class="literal">-d N</code>, to limit the dependency depth to <code class="literal">N</code> levels. The
  894. default, <code class="literal">0</code>, means no limit.
  895. </li><li class="listitem">
  896. <code class="literal">--stop-on PKG</code>, <code class="literal">-s PKG</code>, to stop the graph on the package <code class="literal">PKG</code>.
  897. <code class="literal">PKG</code> can be an actual package name, a glob, the keyword <span class="emphasis"><em>virtual</em></span>
  898. (to stop on virtual packages), or the keyword <span class="emphasis"><em>host</em></span> (to stop on
  899. host packages). The package is still present on the graph, but its
  900. dependencies are not.
  901. </li><li class="listitem">
  902. <code class="literal">--exclude PKG</code>, <code class="literal">-x PKG</code>, like <code class="literal">--stop-on</code>, but also omits <code class="literal">PKG</code> from
  903. the graph.
  904. </li><li class="listitem">
  905. <code class="literal">--transitive</code>, <code class="literal">--no-transitive</code>, to draw (or not) the transitive
  906. dependencies. The default is to not draw transitive dependencies.
  907. </li><li class="listitem">
  908. <code class="literal">--colors R,T,H</code>, the comma-separated list of colors to draw the
  909. root package (<code class="literal">R</code>), the target packages (<code class="literal">T</code>) and the host packages
  910. (<code class="literal">H</code>). Defaults to: <code class="literal">lightblue,grey,gainsboro</code>
  911. </li></ul></div><pre class="screen">BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colors=red,green,blue' make graph-depends</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_graphing_the_build_duration"></a>8.10. Graphing the build duration</h2></div></div></div><p><a id="graph-duration"></a>When the build of a system takes a long time, it is sometimes useful
  912. to be able to understand which packages are the longest to build, to
  913. see if anything can be done to speed up the build. In order to help
  914. such build time analysis, Buildroot collects the build time of each
  915. step of each package, and allows to generate graphs from this data.</p><p>To generate the build time graph after a build, run:</p><pre class="screen">make graph-build</pre><p>This will generate a set of files in <code class="literal">output/graphs</code> :</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  916. <code class="literal">build.hist-build.pdf</code>, a histogram of the build time for each
  917. package, ordered in the build order.
  918. </li><li class="listitem">
  919. <code class="literal">build.hist-duration.pdf</code>, a histogram of the build time for each
  920. package, ordered by duration (longest first)
  921. </li><li class="listitem">
  922. <code class="literal">build.hist-name.pdf</code>, a histogram of the build time for each
  923. package, order by package name.
  924. </li><li class="listitem">
  925. <code class="literal">build.pie-packages.pdf</code>, a pie chart of the build time per package
  926. </li><li class="listitem">
  927. <code class="literal">build.pie-steps.pdf</code>, a pie chart of the global time spent in each
  928. step of the packages build process.
  929. </li></ul></div><p>This <code class="literal">graph-build</code> target requires the Python Matplotlib and Numpy
  930. libraries to be installed (<code class="literal">python-matplotlib</code> and <code class="literal">python-numpy</code> on
  931. most distributions), and also the <code class="literal">argparse</code> module if you’re using a
  932. Python version older than 2.7 (<code class="literal">python-argparse</code> on most
  933. distributions).</p><p>By default, the output format for the graph is PDF, but a different
  934. format can be selected using the <code class="literal">BR2_GRAPH_OUT</code> environment variable. The
  935. only other format supported is PNG:</p><pre class="screen">BR2_GRAPH_OUT=png make graph-build</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="graph-size"></a>8.11. Graphing the filesystem size contribution of packages</h2></div></div></div><p>When your target system grows, it is sometimes useful to understand
  936. how much each Buildroot package is contributing to the overall root
  937. filesystem size. To help with such an analysis, Buildroot collects
  938. data about files installed by each package and using this data,
  939. generates a graph and CSV files detailing the size contribution of
  940. the different packages.</p><p>To generate these data after a build, run:</p><pre class="screen">make graph-size</pre><p>This will generate:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  941. <code class="literal">output/graphs/graph-size.pdf</code>, a pie chart of the contribution of
  942. each package to the overall root filesystem size
  943. </li><li class="listitem">
  944. <code class="literal">output/graphs/package-size-stats.csv</code>, a CSV file giving the size
  945. contribution of each package to the overall root filesystem size
  946. </li><li class="listitem">
  947. <code class="literal">output/graphs/file-size-stats.csv</code>, a CSV file giving the size
  948. contribution of each installed file to the package it belongs, and
  949. to the overall filesystem size.
  950. </li></ul></div><p>This <code class="literal">graph-size</code> target requires the Python Matplotlib library to be
  951. installed (<code class="literal">python-matplotlib</code> on most distributions), and also the
  952. <code class="literal">argparse</code> module if you’re using a Python version older than 2.7
  953. (<code class="literal">python-argparse</code> on most distributions).</p><p>Just like for the duration graph, a <code class="literal">BR2_GRAPH_OUT</code> environment variable
  954. is supported to adjust the output file format. See <a class="xref" href="#graph-depends">Section 8.9, “Graphing the dependencies between packages”</a>
  955. for details about this environment variable.</p><p>Additionally, one may set the environment variable <code class="literal">BR2_GRAPH_SIZE_OPTS</code>
  956. to further control the generated graph. Accepted options are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  957. <code class="literal">--size-limit X</code>, <code class="literal">-l X</code>, will group all packages which individual
  958. contribution is below <code class="literal">X</code> percent, to a single entry labelled <span class="emphasis"><em>Others</em></span>
  959. in the graph. By default, <code class="literal">X=0.01</code>, which means packages each
  960. contributing less than 1% are grouped under <span class="emphasis"><em>Others</em></span>. Accepted values
  961. are in the range <code class="literal">[0.0..1.0]</code>.
  962. </li><li class="listitem">
  963. <code class="literal">--iec</code>, <code class="literal">--binary</code>, <code class="literal">--si</code>, <code class="literal">--decimal</code>, to use IEC (binary, powers
  964. of 1024) or SI (decimal, powers of 1000; the default) prefixes.
  965. </li><li class="listitem">
  966. <code class="literal">--biggest-first</code>, to sort packages in decreasing size order, rather
  967. than in increasing size order.
  968. </li></ul></div><p><strong>Note. </strong>The collected filesystem size data is only meaningful after a complete
  969. clean rebuild. Be sure to run <code class="literal">make clean all</code> before using <code class="literal">make
  970. graph-size</code>.</p><p>To compare the root filesystem size of two different Buildroot compilations,
  971. for example after adjusting the configuration or when switching to another
  972. Buildroot release, use the <code class="literal">size-stats-compare</code> script. It takes two
  973. <code class="literal">file-size-stats.csv</code> files (produced by <code class="literal">make graph-size</code>) as input.
  974. Refer to the help text of this script for more details:</p><pre class="screen">utils/size-stats-compare -h</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="top-level-parallel-build"></a>8.12. Top-level parallel build</h2></div></div></div><p><strong>Note. </strong>This section deals with a very experimental feature, which is known to
  975. break even in some non-unusual situations. Use at your own risk.</p><p>Buildroot has always been capable of using parallel build on a per
  976. package basis: each package is built by Buildroot using <code class="literal">make -jN</code> (or
  977. the equivalent invocation for non-make-based build systems). The level
  978. of parallelism is by default number of CPUs + 1, but it can be
  979. adjusted using the <code class="literal">BR2_JLEVEL</code> configuration option.</p><p>Until 2020.02, Buildroot was however building packages in a serial
  980. fashion: each package was built one after the other, without
  981. parallelization of the build between packages. As of 2020.02,
  982. Buildroot has experimental support for <span class="strong"><strong>top-level parallel build</strong></span>,
  983. which allows some signicant build time savings by building packages
  984. that have no dependency relationship in parallel. This feature is
  985. however marked as experimental and is known not to work in some cases.</p><p>In order to use top-level parallel build, one must:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
  986. Enable the option <code class="literal">BR2_PER_PACKAGE_DIRECTORIES</code> in the Buildroot
  987. configuration
  988. </li><li class="listitem">
  989. Use <code class="literal">make -jN</code> when starting the Buildroot build
  990. </li></ol></div><p>Internally, the <code class="literal">BR2_PER_PACKAGE_DIRECTORIES</code> will enable a mechanism
  991. called <span class="strong"><strong>per-package directories</strong></span>, which will have the following
  992. effects:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  993. Instead of a global <span class="emphasis"><em>target</em></span> directory and a global <span class="emphasis"><em>host</em></span> directory
  994. common to all packages, per-package <span class="emphasis"><em>target</em></span> and <span class="emphasis"><em>host</em></span> directories
  995. will be used, in <code class="literal">$(O)/per-package/&lt;pkg&gt;/target/</code> and
  996. <code class="literal">$(O)/per-package/&lt;pkg&gt;/host/</code> respectively. Those folders will be
  997. populated from the corresponding folders of the package dependencies
  998. at the beginning of <code class="literal">&lt;pkg&gt;</code> build. The compiler and all other tools
  999. will therefore only be able to see and access files installed by
  1000. dependencies explicitly listed by <code class="literal">&lt;pkg&gt;</code>.
  1001. </li><li class="listitem">
  1002. At the end of the build, the global <span class="emphasis"><em>target</em></span> and <span class="emphasis"><em>host</em></span> directories
  1003. will be populated, located in <code class="literal">$(O)/target</code> and <code class="literal">$(O)/host</code>
  1004. respectively. This means that during the build, those folders will
  1005. be empty and it’s only at the very end of the build that they will
  1006. be populated.
  1007. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_integration_with_eclipse"></a>8.13. Integration with Eclipse</h2></div></div></div><p>While a part of the embedded Linux developers like classical text
  1008. editors like Vim or Emacs, and command-line based interfaces, a number
  1009. of other embedded Linux developers like richer graphical interfaces to
  1010. do their development work. Eclipse being one of the most popular
  1011. Integrated Development Environment, Buildroot integrates with Eclipse
  1012. in order to ease the development work of Eclipse users.</p><p>Our integration with Eclipse simplifies the compilation, remote
  1013. execution and remote debugging of applications and libraries that are
  1014. built on top of a Buildroot system. It does not integrate the
  1015. Buildroot configuration and build processes themselves with
  1016. Eclipse. Therefore, the typical usage model of our Eclipse integration
  1017. would be:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1018. Configure your Buildroot system with <code class="literal">make menuconfig</code>, <code class="literal">make
  1019. xconfig</code> or any other configuration interface provided with
  1020. Buildroot.
  1021. </li><li class="listitem">
  1022. Build your Buildroot system by running <code class="literal">make</code>.
  1023. </li><li class="listitem">
  1024. Start Eclipse to develop, execute and debug your own custom
  1025. applications and libraries, that will rely on the libraries built
  1026. and installed by Buildroot.
  1027. </li></ul></div><p>The Buildroot Eclipse integration installation process and usage is
  1028. described in detail at
  1029. <a class="ulink" href="https://github.com/mbats/eclipse-buildroot-bundle/wiki" target="_top">https://github.com/mbats/eclipse-buildroot-bundle/wiki</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_advanced_usage"></a>8.14. Advanced usage</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_using_the_generated_toolchain_outside_buildroot"></a>8.14.1. Using the generated toolchain outside Buildroot</h3></div></div></div><p>You may want to compile, for your target, your own programs or other
  1030. software that are not packaged in Buildroot. In order to do this you
  1031. can use the toolchain that was generated by Buildroot.</p><p>The toolchain generated by Buildroot is located by default in
  1032. <code class="literal">output/host/</code>. The simplest way to use it is to add
  1033. <code class="literal">output/host/bin/</code> to your PATH environment variable and then to
  1034. use <code class="literal">ARCH-linux-gcc</code>, <code class="literal">ARCH-linux-objdump</code>, <code class="literal">ARCH-linux-ld</code>, etc.</p><p>Alternatively, Buildroot can also export the toolchain and the development
  1035. files of all selected packages, as an SDK, by running the command
  1036. <code class="literal">make sdk</code>. This generates a tarball of the content of the host directory
  1037. <code class="literal">output/host/</code>, named <code class="literal">&lt;TARGET-TUPLE&gt;_sdk-buildroot.tar.gz</code> (which can be
  1038. overriden by setting the environment variable <code class="literal">BR2_SDK_PREFIX</code>) and
  1039. located in the output directory <code class="literal">output/images/</code>.</p><p>This tarball can then be distributed to application developers, when
  1040. they want to develop their applications that are not (yet) packaged as
  1041. a Buildroot package.</p><p>Upon extracting the SDK tarball, the user must run the script
  1042. <code class="literal">relocate-sdk.sh</code> (located at the top directory of the SDK), to make
  1043. sure all paths are updated with the new location.</p><p>Alternatively, if you just want to prepare the SDK without generating
  1044. the tarball (e.g. because you will just be moving the <code class="literal">host</code> directory,
  1045. or will be generating the tarball on your own), Buildroot also allows
  1046. you to just prepare the SDK with <code class="literal">make prepare-sdk</code> without actually
  1047. generating a tarball.</p><p>For your convenience, by selecting the option
  1048. <code class="literal">BR2_PACKAGE_HOST_ENVIRONMENT_SETUP</code>, you can get a
  1049. <code class="literal">environment-setup</code> script installed in <code class="literal">output/host/</code> and therefore
  1050. in your SDK. This script can be sourced with
  1051. <code class="literal">. your/sdk/path/environment-setup</code> to export a number of environment
  1052. variables that will help cross-compile your projects using the
  1053. Buildroot SDK: the <code class="literal">PATH</code> will contain the SDK binaries, standard
  1054. <span class="emphasis"><em>autotools</em></span> variables will be defined with the appropriate values, and
  1055. <code class="literal">CONFIGURE_FLAGS</code> will contain basic <code class="literal">./configure</code> options to
  1056. cross-compile <span class="emphasis"><em>autotools</em></span> projects. It also provides some useful
  1057. commands. Note however that once this script is sourced, the
  1058. environment is setup only for cross-compilation, and no longer for
  1059. native compilation.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_using_literal_gdb_literal_in_buildroot"></a>8.14.2. Using <code class="literal">gdb</code> in Buildroot</h3></div></div></div><p>Buildroot allows to do cross-debugging, where the debugger runs on the
  1060. build machine and communicates with <code class="literal">gdbserver</code> on the target to
  1061. control the execution of the program.</p><p>To achieve this:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1062. If you are using an <span class="emphasis"><em>internal toolchain</em></span> (built by Buildroot), you
  1063. must enable <code class="literal">BR2_PACKAGE_HOST_GDB</code>, <code class="literal">BR2_PACKAGE_GDB</code> and
  1064. <code class="literal">BR2_PACKAGE_GDB_SERVER</code>. This ensures that both the cross gdb and
  1065. gdbserver get built, and that gdbserver gets installed to your target.
  1066. </li><li class="listitem">
  1067. If you are using an <span class="emphasis"><em>external toolchain</em></span>, you should enable
  1068. <code class="literal">BR2_TOOLCHAIN_EXTERNAL_GDB_SERVER_COPY</code>, which will copy the
  1069. gdbserver included with the external toolchain to the target. If your
  1070. external toolchain does not have a cross gdb or gdbserver, it is also
  1071. possible to let Buildroot build them, by enabling the same options as
  1072. for the <span class="emphasis"><em>internal toolchain backend</em></span>.
  1073. </li></ul></div><p>Now, to start debugging a program called <code class="literal">foo</code>, you should run on the
  1074. target:</p><pre class="screen">gdbserver :2345 foo</pre><p>This will cause <code class="literal">gdbserver</code> to listen on TCP port 2345 for a connection
  1075. from the cross gdb.</p><p>Then, on the host, you should start the cross gdb using the following
  1076. command line:</p><pre class="screen">&lt;buildroot&gt;/output/host/bin/&lt;tuple&gt;-gdb -x &lt;buildroot&gt;/output/staging/usr/share/buildroot/gdbinit foo</pre><p>Of course, <code class="literal">foo</code> must be available in the current directory, built
  1077. with debugging symbols. Typically you start this command from the
  1078. directory where <code class="literal">foo</code> is built (and not from <code class="literal">output/target/</code> as the
  1079. binaries in that directory are stripped).</p><p>The <code class="literal">&lt;buildroot&gt;/output/staging/usr/share/buildroot/gdbinit</code> file will tell the
  1080. cross gdb where to find the libraries of the target.</p><p>Finally, to connect to the target from the cross gdb:</p><pre class="screen">(gdb) target remote &lt;target ip address&gt;:2345</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="ccache"></a>8.14.3. Using <code class="literal">ccache</code> in Buildroot</h3></div></div></div><p><a class="ulink" href="http://ccache.samba.org" target="_top">ccache</a> is a compiler cache. It stores the
  1081. object files resulting from each compilation process, and is able to
  1082. skip future compilation of the same source file (with same compiler
  1083. and same arguments) by using the pre-existing object files. When doing
  1084. almost identical builds from scratch a number of times, it can nicely
  1085. speed up the build process.</p><p><code class="literal">ccache</code> support is integrated in Buildroot. You just have to enable
  1086. <code class="literal">Enable compiler cache</code> in <code class="literal">Build options</code>. This will automatically
  1087. build <code class="literal">ccache</code> and use it for every host and target compilation.</p><p>The cache is located in <code class="literal">$HOME/.buildroot-ccache</code>. It is stored
  1088. outside of Buildroot output directory so that it can be shared by
  1089. separate Buildroot builds. If you want to get rid of the cache, simply
  1090. remove this directory.</p><p>You can get statistics on the cache (its size, number of hits,
  1091. misses, etc.) by running <code class="literal">make ccache-stats</code>.</p><p>The make target <code class="literal">ccache-options</code> and the <code class="literal">CCACHE_OPTIONS</code> variable
  1092. provide more generic access to the ccache. For example</p><pre class="screen"># set cache limit size
  1093. make CCACHE_OPTIONS="--max-size=5G" ccache-options
  1094. # zero statistics counters
  1095. make CCACHE_OPTIONS="--zero-stats" ccache-options</pre><p><code class="literal">ccache</code> makes a hash of the source files and of the compiler options.
  1096. If a compiler option is different, the cached object file will not be
  1097. used. Many compiler options, however, contain an absolute path to the
  1098. staging directory. Because of this, building in a different output
  1099. directory would lead to many cache misses.</p><p>To avoid this issue, buildroot has the <code class="literal">Use relative paths</code> option
  1100. (<code class="literal">BR2_CCACHE_USE_BASEDIR</code>). This will rewrite all absolute paths that
  1101. point inside the output directory into relative paths. Thus, changing
  1102. the output directory no longer leads to cache misses.</p><p>A disadvantage of the relative paths is that they also end up to be
  1103. relative paths in the object file. Therefore, for example, the debugger
  1104. will no longer find the file, unless you cd to the output directory
  1105. first.</p><p>See <a class="ulink" href="https://ccache.samba.org/manual.html#_compiling_in_different_directories" target="_top">the
  1106. ccache manual’s section on "Compiling in different directories"</a> for
  1107. more details about this rewriting of absolute paths.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="download-location"></a>8.14.4. Location of downloaded packages</h3></div></div></div><p>The various tarballs that are downloaded by Buildroot are all stored
  1108. in <code class="literal">BR2_DL_DIR</code>, which by default is the <code class="literal">dl</code> directory. If you want
  1109. to keep a complete version of Buildroot which is known to be working
  1110. with the associated tarballs, you can make a copy of this directory.
  1111. This will allow you to regenerate the toolchain and the target
  1112. filesystem with exactly the same versions.</p><p>If you maintain several Buildroot trees, it might be better to have a
  1113. shared download location. This can be achieved by pointing the
  1114. <code class="literal">BR2_DL_DIR</code> environment variable to a directory. If this is
  1115. set, then the value of <code class="literal">BR2_DL_DIR</code> in the Buildroot configuration is
  1116. overridden. The following line should be added to <code class="literal">&lt;~/.bashrc&gt;</code>.</p><pre class="screen"> export BR2_DL_DIR=&lt;shared download location&gt;</pre><p>The download location can also be set in the <code class="literal">.config</code> file, with the
  1117. <code class="literal">BR2_DL_DIR</code> option. Unlike most options in the .config file, this value
  1118. is overridden by the <code class="literal">BR2_DL_DIR</code> environment variable.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="pkg-build-steps"></a>8.14.5. Package-specific <span class="emphasis"><em>make</em></span> targets</h3></div></div></div><p>Running <code class="literal">make &lt;package&gt;</code> builds and installs that particular package
  1119. and its dependencies.</p><p>For packages relying on the Buildroot infrastructure, there are
  1120. numerous special make targets that can be called independently like
  1121. this:</p><pre class="screen">make &lt;package&gt;-&lt;target&gt;</pre><p>The package build targets are (in the order they are executed):</p><div class="informaltable"><table class="informaltable" cellpadding="4px" style="border-collapse: collapse;border-top: 3px solid #527bbd; border-bottom: 3px solid #527bbd; border-left: 3px solid #527bbd; border-right: 3px solid #527bbd; " width="90%"><colgroup><col class="col_1" /><col class="col_2" /></colgroup><thead><tr><th style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"> command/target </th><th style="border-bottom: 1px solid #527bbd; " align="left" valign="top"> Description</th></tr></thead><tbody><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">source</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Fetch the source (download the tarball, clone
  1122. the source repository, etc)</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">depends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Build and install all dependencies required to
  1123. build the package</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">extract</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Put the source in the package build directory
  1124. (extract the tarball, copy the source, etc)</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">patch</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Apply the patches, if any</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">configure</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Run the configure commands, if any</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">build</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Run the compilation commands</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">install-staging</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p><span class="strong"><strong>target package:</strong></span> Run the installation of the package in the
  1125. staging directory, if necessary</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">install-target</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p><span class="strong"><strong>target package:</strong></span> Run the installation of the package in the
  1126. target directory, if necessary</p></td></tr><tr><td style="border-right: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">install</code></p></td><td style="" align="left" valign="top"><p><span class="strong"><strong>target package:</strong></span> Run the 2 previous installation commands</p>
  1127. <p><span class="strong"><strong>host package:</strong></span> Run the installation of the package in the host
  1128. directory</p></td></tr></tbody></table></div><p>Additionally, there are some other useful make targets:</p><div class="informaltable"><table class="informaltable" cellpadding="4px" style="border-collapse: collapse;border-top: 3px solid #527bbd; border-bottom: 3px solid #527bbd; border-left: 3px solid #527bbd; border-right: 3px solid #527bbd; " width="90%"><colgroup><col class="col_1" /><col class="col_2" /></colgroup><thead><tr><th style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"> command/target </th><th style="border-bottom: 1px solid #527bbd; " align="left" valign="top"> Description</th></tr></thead><tbody><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">show-depends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Displays the first-order dependencies required to build the
  1129. package</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">show-recursive-depends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Recursively displays the dependencies
  1130. required to build the package</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">show-rdepends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Displays the first-order reverse dependencies of
  1131. the package (i.e packages that directly depend on it)</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">show-recursive-rdepends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Recursively displays the reverse
  1132. dependencies of the package (i.e the packages that depend on it,
  1133. directly or indirectly)</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">graph-depends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Generate a dependency graph of the package, in the
  1134. context of the current Buildroot configuration. See
  1135. <a class="link" href="#graph-depends">this section</a> for more details about dependency
  1136. graphs.</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">graph-rdepends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Generate a graph of this package reverse
  1137. dependencies (i.e the packages that depend on it, directly or
  1138. indirectly)</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">dirclean</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Remove the whole package build directory</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">reinstall</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Re-run the install commands</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">rebuild</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Re-run the compilation commands - this only makes
  1139. sense when using the <code class="literal">OVERRIDE_SRCDIR</code> feature or when you modified a file
  1140. directly in the build directory</p></td></tr><tr><td style="border-right: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">reconfigure</code></p></td><td style="" align="left" valign="top"><p>Re-run the configure commands, then rebuild - this only
  1141. makes sense when using the <code class="literal">OVERRIDE_SRCDIR</code> feature or when you modified a
  1142. file directly in the build directory</p></td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_using_buildroot_during_development"></a>8.14.6. Using Buildroot during development</h3></div></div></div><p>The normal operation of Buildroot is to download a tarball, extract
  1143. it, configure, compile and install the software component found inside
  1144. this tarball. The source code is extracted in
  1145. <code class="literal">output/build/&lt;package&gt;-&lt;version&gt;</code>, which is a temporary directory:
  1146. whenever <code class="literal">make clean</code> is used, this directory is entirely removed, and
  1147. re-created at the next <code class="literal">make</code> invocation. Even when a Git or
  1148. Subversion repository is used as the input for the package source
  1149. code, Buildroot creates a tarball out of it, and then behaves as it
  1150. normally does with tarballs.</p><p>This behavior is well-suited when Buildroot is used mainly as an
  1151. integration tool, to build and integrate all the components of an
  1152. embedded Linux system. However, if one uses Buildroot during the
  1153. development of certain components of the system, this behavior is not
  1154. very convenient: one would instead like to make a small change to the
  1155. source code of one package, and be able to quickly rebuild the system
  1156. with Buildroot.</p><p>Making changes directly in <code class="literal">output/build/&lt;package&gt;-&lt;version&gt;</code> is not
  1157. an appropriate solution, because this directory is removed on <code class="literal">make
  1158. clean</code>.</p><p>Therefore, Buildroot provides a specific mechanism for this use case:
  1159. the <code class="literal">&lt;pkg&gt;_OVERRIDE_SRCDIR</code> mechanism. Buildroot reads an <span class="emphasis"><em>override</em></span>
  1160. file, which allows the user to tell Buildroot the location of the
  1161. source for certain packages.</p><p>The default location of the override file is <code class="literal">$(CONFIG_DIR)/local.mk</code>,
  1162. as defined by the <code class="literal">BR2_PACKAGE_OVERRIDE_FILE</code> configuration option.
  1163. <code class="literal">$(CONFIG_DIR)</code> is the location of the Buildroot <code class="literal">.config</code> file, so
  1164. <code class="literal">local.mk</code> by default lives side-by-side with the <code class="literal">.config</code> file,
  1165. which means:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1166. In the top-level Buildroot source directory for in-tree builds
  1167. (i.e., when <code class="literal">O=</code> is not used)
  1168. </li><li class="listitem">
  1169. In the out-of-tree directory for out-of-tree builds (i.e., when
  1170. <code class="literal">O=</code> is used)
  1171. </li></ul></div><p>If a different location than these defaults is required, it can be
  1172. specified through the <code class="literal">BR2_PACKAGE_OVERRIDE_FILE</code> configuration
  1173. option.</p><p>In this <span class="emphasis"><em>override</em></span> file, Buildroot expects to find lines of the form:</p><pre class="screen">&lt;pkg1&gt;_OVERRIDE_SRCDIR = /path/to/pkg1/sources
  1174. &lt;pkg2&gt;_OVERRIDE_SRCDIR = /path/to/pkg2/sources</pre><p>For example:</p><pre class="screen">LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
  1175. BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/</pre><p>When Buildroot finds that for a given package, an
  1176. <code class="literal">&lt;pkg&gt;_OVERRIDE_SRCDIR</code> has been defined, it will no longer attempt to
  1177. download, extract and patch the package. Instead, it will directly use
  1178. the source code available in the specified directory and <code class="literal">make clean</code>
  1179. will not touch this directory. This allows to point Buildroot to your
  1180. own directories, that can be managed by Git, Subversion, or any other
  1181. version control system. To achieve this, Buildroot will use <span class="emphasis"><em>rsync</em></span> to
  1182. copy the source code of the component from the specified
  1183. <code class="literal">&lt;pkg&gt;_OVERRIDE_SRCDIR</code> to <code class="literal">output/build/&lt;package&gt;-custom/</code>.</p><p>This mechanism is best used in conjunction with the <code class="literal">make
  1184. &lt;pkg&gt;-rebuild</code> and <code class="literal">make &lt;pkg&gt;-reconfigure</code> targets. A <code class="literal">make
  1185. &lt;pkg&gt;-rebuild all</code> sequence will <span class="emphasis"><em>rsync</em></span> the source code from
  1186. <code class="literal">&lt;pkg&gt;_OVERRIDE_SRCDIR</code> to <code class="literal">output/build/&lt;package&gt;-custom</code> (thanks to
  1187. <span class="emphasis"><em>rsync</em></span>, only the modified files are copied), and restart the build
  1188. process of just this package.</p><p>In the example of the <code class="literal">linux</code> package above, the developer can then
  1189. make a source code change in <code class="literal">/home/bob/linux</code> and then run:</p><pre class="screen">make linux-rebuild all</pre><p>and in a matter of seconds gets the updated Linux kernel image in
  1190. <code class="literal">output/images</code>. Similarly, a change can be made to the BusyBox source
  1191. code in <code class="literal">/home/bob/busybox</code>, and after:</p><pre class="screen">make busybox-rebuild all</pre><p>the root filesystem image in <code class="literal">output/images</code> contains the updated
  1192. BusyBox.</p><p>Source trees for big projects often contain hundreds or thousands of
  1193. files which are not needed for building, but will slow down the process
  1194. of copying the sources with <span class="emphasis"><em>rsync</em></span>. Optionally, it is possible define
  1195. <code class="literal">&lt;pkg&gt;_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS</code> to skip syncing certain files
  1196. from the source tree. For example, when working on the <code class="literal">webkitgtk</code>
  1197. package, the following will exclude the tests and in-tree builds from
  1198. a local WebKit source tree:</p><pre class="screen">WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit
  1199. WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \
  1200. --exclude JSTests --exclude ManualTests --exclude PerformanceTests \
  1201. --exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \
  1202. --exclude WebKit.xcworkspace --exclude Websites --exclude Examples</pre><p>By default, Buildroot skips syncing of VCS artifacts (e.g., the <span class="strong"><strong>.git</strong></span> and
  1203. <span class="strong"><strong>.svn</strong></span> directories). Some packages prefer to have these VCS directories
  1204. available during build, for example for automatically determining a precise
  1205. commit reference for version information. To undo this built-in filtering at a
  1206. cost of a slower speed, add these directories back:</p><pre class="screen">LINUX_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = --include .git</pre></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="customize"></a>Chapter 9. Project-specific customization</h2></div></div></div><p>Typical actions you may need to perform for a given project are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1207. configuring Buildroot (including build options and toolchain,
  1208. bootloader, kernel, package and filesystem image type selection)
  1209. </li><li class="listitem">
  1210. configuring other components, like the Linux kernel and BusyBox
  1211. </li><li class="listitem"><p class="simpara">
  1212. customizing the generated target filesystem
  1213. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  1214. adding or overwriting files on the target filesystem (using
  1215. <code class="literal">BR2_ROOTFS_OVERLAY</code>)
  1216. </li><li class="listitem">
  1217. modifying or deleting files on the target filesystem (using
  1218. <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code>)
  1219. </li><li class="listitem">
  1220. running arbitrary commands prior to generating the filesystem image
  1221. (using <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code>)
  1222. </li><li class="listitem">
  1223. setting file permissions and ownership (using
  1224. <code class="literal">BR2_ROOTFS_DEVICE_TABLE</code>)
  1225. </li><li class="listitem">
  1226. adding custom devices nodes (using
  1227. <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code>)
  1228. </li></ul></div></li><li class="listitem">
  1229. adding custom user accounts (using <code class="literal">BR2_ROOTFS_USERS_TABLES</code>)
  1230. </li><li class="listitem">
  1231. running arbitrary commands after generating the filesystem image
  1232. (using <code class="literal">BR2_ROOTFS_POST_IMAGE_SCRIPT</code>)
  1233. </li><li class="listitem">
  1234. adding project-specific patches to some packages (using
  1235. <code class="literal">BR2_GLOBAL_PATCH_DIR</code>)
  1236. </li><li class="listitem">
  1237. adding project-specific packages
  1238. </li></ul></div><p>An important note regarding such <span class="emphasis"><em>project-specific</em></span> customizations:
  1239. please carefully consider which changes are indeed project-specific and
  1240. which changes are also useful to developers outside your project. The
  1241. Buildroot community highly recommends and encourages the upstreaming of
  1242. improvements, packages and board support to the official Buildroot
  1243. project. Of course, it is sometimes not possible or desirable to
  1244. upstream because the changes are highly specific or proprietary.</p><p>This chapter describes how to make such project-specific customizations
  1245. in Buildroot and how to store them in a way that you can build the same
  1246. image in a reproducible way, even after running <span class="emphasis"><em>make clean</em></span>. By
  1247. following the recommended strategy, you can even use the same Buildroot
  1248. tree to build multiple distinct projects!</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-dir-structure"></a>9.1. Recommended directory structure</h2></div></div></div><p>When customizing Buildroot for your project, you will be creating one or
  1249. more project-specific files that need to be stored somewhere. While most
  1250. of these files could be placed in <span class="emphasis"><em>any</em></span> location as their path is to be
  1251. specified in the Buildroot configuration, the Buildroot developers
  1252. recommend a specific directory structure which is described in this
  1253. section.</p><p>Orthogonal to this directory structure, you can choose <span class="emphasis"><em>where</em></span> you place
  1254. this structure itself: either inside the Buildroot tree, or outside of
  1255. it using a br2-external tree. Both options are valid, the choice is up
  1256. to you.</p><pre class="screen">+-- board/
  1257. | +-- &lt;company&gt;/
  1258. | +-- &lt;boardname&gt;/
  1259. | +-- linux.config
  1260. | +-- busybox.config
  1261. | +-- &lt;other configuration files&gt;
  1262. | +-- post_build.sh
  1263. | +-- post_image.sh
  1264. | +-- rootfs_overlay/
  1265. | | +-- etc/
  1266. | | +-- &lt;some file&gt;
  1267. | +-- patches/
  1268. | +-- foo/
  1269. | | +-- &lt;some patch&gt;
  1270. | +-- libbar/
  1271. | +-- &lt;some other patches&gt;
  1272. |
  1273. +-- configs/
  1274. | +-- &lt;boardname&gt;_defconfig
  1275. |
  1276. +-- package/
  1277. | +-- &lt;company&gt;/
  1278. | +-- Config.in (if not using a br2-external tree)
  1279. | +-- &lt;company&gt;.mk (if not using a br2-external tree)
  1280. | +-- package1/
  1281. | | +-- Config.in
  1282. | | +-- package1.mk
  1283. | +-- package2/
  1284. | +-- Config.in
  1285. | +-- package2.mk
  1286. |
  1287. +-- Config.in (if using a br2-external tree)
  1288. +-- external.mk (if using a br2-external tree)
  1289. +-- external.desc (if using a br2-external tree)</pre><p>Details on the files shown above are given further in this chapter.</p><p>Note: if you choose to place this structure outside of the Buildroot
  1290. tree but in a br2-external tree, the &lt;company&gt; and possibly &lt;boardname&gt;
  1291. components may be superfluous and can be left out.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_implementing_layered_customizations"></a>9.1.1. Implementing layered customizations</h3></div></div></div><p>It is quite common for a user to have several related projects that partly
  1292. need the same customizations. Instead of duplicating these
  1293. customizations for each project, it is recommended to use a layered
  1294. customization approach, as explained in this section.</p><p>Almost all of the customization methods available in Buildroot, like
  1295. post-build scripts and root filesystem overlays, accept a
  1296. space-separated list of items. The specified items are always treated in
  1297. order, from left to right. By creating more than one such item, one for
  1298. the common customizations and another one for the really
  1299. project-specific customizations, you can avoid unnecessary duplication.
  1300. Each layer is typically embodied by a separate directory inside
  1301. <code class="literal">board/&lt;company&gt;/</code>. Depending on your projects, you could even introduce
  1302. more than two layers.</p><p>An example directory structure for where a user has two customization
  1303. layers <span class="emphasis"><em>common</em></span> and <span class="emphasis"><em>fooboard</em></span> is:</p><pre class="screen">+-- board/
  1304. +-- &lt;company&gt;/
  1305. +-- common/
  1306. | +-- post_build.sh
  1307. | +-- rootfs_overlay/
  1308. | | +-- ...
  1309. | +-- patches/
  1310. | +-- ...
  1311. |
  1312. +-- fooboard/
  1313. +-- linux.config
  1314. +-- busybox.config
  1315. +-- &lt;other configuration files&gt;
  1316. +-- post_build.sh
  1317. +-- rootfs_overlay/
  1318. | +-- ...
  1319. +-- patches/
  1320. +-- ...</pre><p>For example, if the user has the <code class="literal">BR2_GLOBAL_PATCH_DIR</code> configuration
  1321. option set as:</p><pre class="screen">BR2_GLOBAL_PATCH_DIR="board/&lt;company&gt;/common/patches board/&lt;company&gt;/fooboard/patches"</pre><p>then first the patches from the <span class="emphasis"><em>common</em></span> layer would be applied,
  1322. followed by the patches from the <span class="emphasis"><em>fooboard</em></span> layer.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="outside-br-custom"></a>9.2. Keeping customizations outside of Buildroot</h2></div></div></div><p>As already briefly mentioned in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, you can
  1323. place project-specific customizations in two locations:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1324. directly within the Buildroot tree, typically maintaining them using
  1325. branches in a version control system so that upgrading to a newer
  1326. Buildroot release is easy.
  1327. </li><li class="listitem">
  1328. outside of the Buildroot tree, using the <span class="emphasis"><em>br2-external</em></span> mechanism.
  1329. This mechanism allows to keep package recipes, board support and
  1330. configuration files outside of the Buildroot tree, while still
  1331. having them nicely integrated in the build logic. We call this
  1332. location a <span class="emphasis"><em>br2-external tree</em></span>. This section explains how to use
  1333. the br2-external mechanism and what to provide in a br2-external
  1334. tree.
  1335. </li></ul></div><p>One can tell Buildroot to use one or more br2-external trees by setting
  1336. the <code class="literal">BR2_EXTERNAL</code> make variable set to the path(s) of the br2-external
  1337. tree(s) to use. It can be passed to any Buildroot <code class="literal">make</code> invocation. It
  1338. is automatically saved in the hidden <code class="literal">.br2-external.mk</code> file in the output
  1339. directory. Thanks to this, there is no need to pass <code class="literal">BR2_EXTERNAL</code> at
  1340. every <code class="literal">make</code> invocation. It can however be changed at any time by
  1341. passing a new value, and can be removed by passing an empty value.</p><p><strong>Note. </strong>The path to a br2-external tree can be either absolute or relative.
  1342. If it is passed as a relative path, it is important to note that it is
  1343. interpreted relative to the main Buildroot source directory, <span class="strong"><strong>not</strong></span> to
  1344. the Buildroot output directory.</p><p><strong>Note: </strong>If using an br2-external tree from before Buildroot 2016.11, you need to
  1345. convert it before you can use it with Buildroot 2016.11 onward. See
  1346. <a class="xref" href="#br2-external-converting" title="27.1. Migrating to 2016.11">Section 27.1, “Migrating to 2016.11”</a> for help on doing so.</p><p>Some examples:</p><pre class="screen">buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig</pre><p>From now on, definitions from the <code class="literal">/path/to/foo</code> br2-external tree
  1347. will be used:</p><pre class="screen">buildroot/ $ make
  1348. buildroot/ $ make legal-info</pre><p>We can switch to another br2-external tree at any time:</p><pre class="screen">buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig</pre><p>We can also use multiple br2-external trees:</p><pre class="screen">buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/where/we/have/bar menuconfig</pre><p>Or disable the usage of any br2-external tree:</p><pre class="screen">buildroot/ $ make BR2_EXTERNAL= xconfig</pre><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_layout_of_a_br2_external_tree"></a>9.2.1. Layout of a br2-external tree</h3></div></div></div><p>A br2-external tree must contain at least those three files, described
  1349. in the following chapters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1350. <code class="literal">external.desc</code>
  1351. </li><li class="listitem">
  1352. <code class="literal">external.mk</code>
  1353. </li><li class="listitem">
  1354. <code class="literal">Config.in</code>
  1355. </li></ul></div><p>Apart from those mandatory files, there may be additional and optional
  1356. content that may be present in a br2-external tree, like the <code class="literal">configs/</code>
  1357. or <code class="literal">provides/</code> directories. They are described in the following chapters
  1358. as well.</p><p>A complete example br2-external tree layout is also described later.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_the_literal_external_desc_literal_file"></a>The <code class="literal">external.desc</code> file</h4></div></div></div><p>That file describes the br2-external tree: the <span class="emphasis"><em>name</em></span> and <span class="emphasis"><em>description</em></span>
  1359. for that br2-external tree.</p><p>The format for this file is line based, with each line starting by a
  1360. keyword, followed by a colon and one or more spaces, followed by the
  1361. value assigned to that keyword. There are two keywords currently
  1362. recognised:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  1363. <code class="literal">name</code>, mandatory, defines the name for that br2-external tree. That
  1364. name must only use ASCII characters in the set <code class="literal">[A-Za-z0-9_]</code>; any
  1365. other character is forbidden. Buildroot sets the variable
  1366. <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code> to the absolute path of the br2-external
  1367. tree, so that you can use it to refer to your br2-external tree. This
  1368. variable is available both in Kconfig, so you can use it to source your
  1369. Kconfig files (see below) and in the Makefile, so that you can use it
  1370. to include other Makefiles (see below) or refer to other files (like
  1371. data files) from your br2-external tree.
  1372. </p><p><strong>Note: </strong>Since it is possible to use multiple br2-external trees at once, this
  1373. name is used by Buildroot to generate variables for each of those trees.
  1374. That name is used to identify your br2-external tree, so try to come up
  1375. with a name that really describes your br2-external tree, in order for
  1376. it to be relatively unique, so that it does not clash with another name
  1377. from another br2-external tree, especially if you are planning on
  1378. somehow sharing your br2-external tree with third parties or using
  1379. br2-external trees from third parties.</p></li><li class="listitem">
  1380. <code class="literal">desc</code>, optional, provides a short description for that br2-external
  1381. tree. It shall fit on a single line, is mostly free-form (see below),
  1382. and is used when displaying information about a br2-external tree (e.g.
  1383. above the list of defconfig files, or as the prompt in the menuconfig);
  1384. as such, it should relatively brief (40 chars is probably a good upper
  1385. limit). The description is available in the <code class="literal">BR2_EXTERNAL_$(NAME)_DESC</code>
  1386. variable.
  1387. </li></ul></div><p>Examples of names and the corresponding <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code>
  1388. variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1389. <code class="literal">FOO</code> → <code class="literal">BR2_EXTERNAL_FOO_PATH</code>
  1390. </li><li class="listitem">
  1391. <code class="literal">BAR_42</code> → <code class="literal">BR2_EXTERNAL_BAR_42_PATH</code>
  1392. </li></ul></div><p>In the following examples, it is assumed the name to be set to <code class="literal">BAR_42</code>.</p><p><strong>Note: </strong>Both <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code> and <code class="literal">BR2_EXTERNAL_$(NAME)_DESC</code> are
  1393. available in the Kconfig files and the Makefiles. They are also
  1394. exported in the environment so are available in post-build, post-image
  1395. and in-fakeroot scripts.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_the_literal_config_in_literal_and_literal_external_mk_literal_files"></a>The <code class="literal">Config.in</code> and <code class="literal">external.mk</code> files</h4></div></div></div><p>Those files (which may each be empty) can be used to define package
  1396. recipes (i.e. <code class="literal">foo/Config.in</code> and <code class="literal">foo/foo.mk</code> like for packages bundled
  1397. in Buildroot itself) or other custom configuration options or make logic.</p><p>Buildroot automatically includes the <code class="literal">Config.in</code> from each br2-external
  1398. tree to make it appear in the top-level configuration menu, and includes
  1399. the <code class="literal">external.mk</code> from each br2-external tree with the rest of the
  1400. makefile logic.</p><p>The main usage of this is to store package recipes. The recommended way
  1401. to do this is to write a <code class="literal">Config.in</code> file that looks like:</p><pre class="screen">source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in"
  1402. source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in"</pre><p>Then, have an <code class="literal">external.mk</code> file that looks like:</p><pre class="screen">include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))</pre><p>And then in <code class="literal">$(BR2_EXTERNAL_BAR_42_PATH)/package/package1</code> and
  1403. <code class="literal">$(BR2_EXTERNAL_BAR_42_PATH)/package/package2</code> create normal
  1404. Buildroot package recipes, as explained in <a class="xref" href="#adding-packages" title="Chapter 18. Adding new packages to Buildroot">Chapter 18, <em>Adding new packages to Buildroot</em></a>.
  1405. If you prefer, you can also group the packages in subdirectories
  1406. called &lt;boardname&gt; and adapt the above paths accordingly.</p><p>You can also define custom configuration options in <code class="literal">Config.in</code> and
  1407. custom make logic in <code class="literal">external.mk</code>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_the_literal_configs_literal_directory"></a>The <code class="literal">configs/</code> directory</h4></div></div></div><p>One can store Buildroot defconfigs in the <code class="literal">configs</code> subdirectory of
  1408. the br2-external tree. Buildroot will automatically show them in the
  1409. output of <code class="literal">make list-defconfigs</code> and allow them to be loaded with the
  1410. normal <code class="literal">make &lt;name&gt;_defconfig</code> command. They will be visible in the
  1411. <span class="emphasis"><em>make list-defconfigs</em></span> output, below an <code class="literal">External configs</code> label that
  1412. contains the name of the br2-external tree they are defined in.</p><p><strong>Note: </strong>If a defconfig file is present in more than one br2-external tree, then
  1413. the one from the last br2-external tree is used. It is thus possible
  1414. to override a defconfig bundled in Buildroot or another br2-external
  1415. tree.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_the_literal_provides_literal_directory"></a>The <code class="literal">provides/</code> directory</h4></div></div></div><p>For some packages, Buildroot provides a choice between two (or more)
  1416. implementations of API-compatible such packages. For example, there is
  1417. a choice to choose either libjpeg ot jpeg-turbo; there is one between
  1418. openssl or libressl; there is one to select one of the known,
  1419. pre-configured toolchains…</p><p>It is possible for a br2-external to extend those choices, by providing
  1420. a set of files that define those alternatives:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1421. <code class="literal">provides/toolchains.in</code> defines the pre-configured toolchains, which
  1422. will then be listed in the toolchain selection;
  1423. </li><li class="listitem">
  1424. <code class="literal">provides/jpeg.in</code> defines the alternative libjpeg implementations;
  1425. </li><li class="listitem">
  1426. <code class="literal">provides/openssl.in</code> defines the alternative openssl implementations;
  1427. </li><li class="listitem">
  1428. <code class="literal">provides/skeleton.in</code> defines the alternative skeleton implementations;
  1429. </li><li class="listitem">
  1430. <code class="literal">provides/init.in</code> defines the alternative init system implementations, this
  1431. can be used to select a default skeleton for your init.
  1432. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_free_form_content"></a>Free-form content</h4></div></div></div><p>One can store all the board-specific configuration files there, such
  1433. as the kernel configuration, the root filesystem overlay, or any other
  1434. configuration file for which Buildroot allows to set the location (by
  1435. using the <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code> variable). For example, you
  1436. could set the paths to a global patch directory, to a rootfs overlay
  1437. and to the kernel configuration file as follows (e.g. by running
  1438. <code class="literal">make menuconfig</code> and filling in these options):</p><pre class="screen">BR2_GLOBAL_PATCH_DIR=$(BR2_EXTERNAL_BAR_42_PATH)/patches/
  1439. BR2_ROOTFS_OVERLAY=$(BR2_EXTERNAL_BAR_42_PATH)/board/&lt;boardname&gt;/overlay/
  1440. BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_PATH)/board/&lt;boardname&gt;/kernel.config</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_additional_linux_kernel_extensions"></a>Additional Linux kernel extensions</h4></div></div></div><p>Additional Linux kernel extensions (see <a class="xref" href="#linux-kernel-ext" title="18.21.2. linux-kernel-extensions">Section 18.21.2, “linux-kernel-extensions”</a>) can
  1441. be added by storing them in the <code class="literal">linux/</code> directory at the root of a
  1442. br2-external tree.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_example_layout"></a>Example layout</h4></div></div></div><p>Here is an example layout using all features of br2-external (the sample
  1443. content is shown for the file above it, when it is relevant to explain
  1444. the br2-external tree; this is all entirely made up just for the sake of
  1445. illustration, of course):</p><pre class="screen">/path/to/br2-ext-tree/
  1446. |- external.desc
  1447. | |name: BAR_42
  1448. | |desc: Example br2-external tree
  1449. | `----
  1450. |
  1451. |- Config.in
  1452. | |source "$BR2_EXTERNAL_BAR_42_PATH/toolchain/toolchain-external-mine/Config.in.options"
  1453. | |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-1/Config.in"
  1454. | |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-2/Config.in"
  1455. | |source "$BR2_EXTERNAL_BAR_42_PATH/package/my-jpeg/Config.in"
  1456. | |
  1457. | |config BAR_42_FLASH_ADDR
  1458. | | hex "my-board flash address"
  1459. | | default 0x10AD
  1460. | `----
  1461. |
  1462. |- external.mk
  1463. | |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
  1464. | |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/toolchain/*/*.mk))
  1465. | |
  1466. | |flash-my-board:
  1467. | | $(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/flash-image \
  1468. | | --image $(BINARIES_DIR)/image.bin \
  1469. | | --address $(BAR_42_FLASH_ADDR)
  1470. | `----
  1471. |
  1472. |- package/pkg-1/Config.in
  1473. | |config BR2_PACKAGE_PKG_1
  1474. | | bool "pkg-1"
  1475. | | help
  1476. | | Some help about pkg-1
  1477. | `----
  1478. |- package/pkg-1/pkg-1.hash
  1479. |- package/pkg-1/pkg-1.mk
  1480. | |PKG_1_VERSION = 1.2.3
  1481. | |PKG_1_SITE = /some/where/to/get/pkg-1
  1482. | |PKG_1_LICENSE = blabla
  1483. | |
  1484. | |define PKG_1_INSTALL_INIT_SYSV
  1485. | | $(INSTALL) -D -m 0755 $(PKG_1_PKGDIR)/S99my-daemon \
  1486. | | $(TARGET_DIR)/etc/init.d/S99my-daemon
  1487. | |endef
  1488. | |
  1489. | |$(eval $(autotools-package))
  1490. | `----
  1491. |- package/pkg-1/S99my-daemon
  1492. |
  1493. |- package/pkg-2/Config.in
  1494. |- package/pkg-2/pkg-2.hash
  1495. |- package/pkg-2/pkg-2.mk
  1496. |
  1497. |- provides/jpeg.in
  1498. | |config BR2_PACKAGE_MY_JPEG
  1499. | | bool "my-jpeg"
  1500. | `----
  1501. |- package/my-jpeg/Config.in
  1502. | |config BR2_PACKAGE_PROVIDES_JPEG
  1503. | | default "my-jpeg" if BR2_PACKAGE_MY_JPEG
  1504. | `----
  1505. |- package/my-jpeg/my-jpeg.mk
  1506. | |# This is a normal package .mk file
  1507. | |MY_JPEG_VERSION = 1.2.3
  1508. | |MY_JPEG_SITE = https://example.net/some/place
  1509. | |MY_JPEG_PROVIDES = jpeg
  1510. | |$(eval $(autotools-package))
  1511. | `----
  1512. |
  1513. |- provides/init.in
  1514. | |config BR2_INIT_MINE
  1515. | | bool "my custom init"
  1516. | | select BR2_PACKAGE_MY_INIT
  1517. | | select BR2_PACKAGE_SKELETON_INIT_MINE if BR2_ROOTFS_SKELETON_DEFAULT
  1518. | `----
  1519. |
  1520. |- provides/skeleton.in
  1521. | |config BR2_ROOTFS_SKELETON_MINE
  1522. | | bool "my custom skeleton"
  1523. | | select BR2_PACKAGE_SKELETON_MINE
  1524. | `----
  1525. |- package/skeleton-mine/Config.in
  1526. | |config BR2_PACKAGE_SKELETON_MINE
  1527. | | bool
  1528. | | select BR2_PACKAGE_HAS_SKELETON
  1529. | |
  1530. | |config BR2_PACKAGE_PROVIDES_SKELETON
  1531. | | default "skeleton-mine" if BR2_PACKAGE_SKELETON_MINE
  1532. | `----
  1533. |- package/skeleton-mine/skeleton-mine.mk
  1534. | |SKELETON_MINE_ADD_TOOLCHAIN_DEPENDENCY = NO
  1535. | |SKELETON_MINE_ADD_SKELETON_DEPENDENCY = NO
  1536. | |SKELETON_MINE_PROVIDES = skeleton
  1537. | |SKELETON_MINE_INSTALL_STAGING = YES
  1538. | |$(eval $(generic-package))
  1539. | `----
  1540. |
  1541. |- provides/toolchains.in
  1542. | |config BR2_TOOLCHAIN_EXTERNAL_MINE
  1543. | | bool "my custom toolchain"
  1544. | | depends on BR2_some_arch
  1545. | | select BR2_INSTALL_LIBSTDCPP
  1546. | `----
  1547. |- toolchain/toolchain-external-mine/Config.in.options
  1548. | |if BR2_TOOLCHAIN_EXTERNAL_MINE
  1549. | |config BR2_TOOLCHAIN_EXTERNAL_PREFIX
  1550. | | default "arch-mine-linux-gnu"
  1551. | |config BR2_PACKAGE_PROVIDES_TOOLCHAIN_EXTERNAL
  1552. | | default "toolchain-external-mine"
  1553. | |endif
  1554. | `----
  1555. |- toolchain/toolchain-external-mine/toolchain-external-mine.mk
  1556. | |TOOLCHAIN_EXTERNAL_MINE_SITE = https://example.net/some/place
  1557. | |TOOLCHAIN_EXTERNAL_MINE_SOURCE = my-toolchain.tar.gz
  1558. | |$(eval $(toolchain-external-package))
  1559. | `----
  1560. |
  1561. |- linux/Config.ext.in
  1562. | |config BR2_LINUX_KERNEL_EXT_EXAMPLE_DRIVER
  1563. | | bool "example-external-driver"
  1564. | | help
  1565. | | Example external driver
  1566. | |---
  1567. |- linux/linux-ext-example-driver.mk
  1568. |
  1569. |- configs/my-board_defconfig
  1570. | |BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_BAR_42_PATH)/patches/"
  1571. | |BR2_ROOTFS_OVERLAY="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/overlay/"
  1572. | |BR2_ROOTFS_POST_IMAGE_SCRIPT="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/post-image.sh"
  1573. | |BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/kernel.config"
  1574. | `----
  1575. |
  1576. |- patches/linux/0001-some-change.patch
  1577. |- patches/linux/0002-some-other-change.patch
  1578. |- patches/busybox/0001-fix-something.patch
  1579. |
  1580. |- board/my-board/kernel.config
  1581. |- board/my-board/overlay/var/www/index.html
  1582. |- board/my-board/overlay/var/www/my.css
  1583. |- board/my-board/flash-image
  1584. `- board/my-board/post-image.sh
  1585. |#!/bin/sh
  1586. |generate-my-binary-image \
  1587. | --root ${BINARIES_DIR}/rootfs.tar \
  1588. | --kernel ${BINARIES_DIR}/zImage \
  1589. | --dtb ${BINARIES_DIR}/my-board.dtb \
  1590. | --output ${BINARIES_DIR}/image.bin
  1591. `----</pre><p>The br2-external tree will then be visible in the menuconfig (with
  1592. the layout expanded):</p><pre class="screen">External options ---&gt;
  1593. *** Example br2-external tree (in /path/to/br2-ext-tree/)
  1594. [ ] pkg-1
  1595. [ ] pkg-2
  1596. (0x10AD) my-board flash address</pre><p>If you are using more than one br2-external tree, it would look like
  1597. (with the layout expanded and the second one with name <code class="literal">FOO_27</code> but no
  1598. <code class="literal">desc:</code> field in <code class="literal">external.desc</code>):</p><pre class="screen">External options ---&gt;
  1599. Example br2-external tree ---&gt;
  1600. *** Example br2-external tree (in /path/to/br2-ext-tree)
  1601. [ ] pkg-1
  1602. [ ] pkg-2
  1603. (0x10AD) my-board flash address
  1604. FOO_27 ---&gt;
  1605. *** FOO_27 (in /path/to/another-br2-ext)
  1606. [ ] foo
  1607. [ ] bar</pre><p>Additionally, the jpeg provider will be visible in the jpeg choice:</p><pre class="screen">Target packages ---&gt;
  1608. Libraries ---&gt;
  1609. Graphics ---&gt;
  1610. [*] jpeg support
  1611. jpeg variant () ---&gt;
  1612. ( ) jpeg
  1613. ( ) jpeg-turbo
  1614. *** jpeg from: Example br2-external tree ***
  1615. (X) my-jpeg
  1616. *** jpeg from: FOO_27 ***
  1617. ( ) another-jpeg</pre><p>And similarly for the toolchains:</p><pre class="screen">Toolchain ---&gt;
  1618. Toolchain () ---&gt;
  1619. ( ) Custom toolchain
  1620. *** Toolchains from: Example br2-external tree ***
  1621. (X) my custom toolchain</pre><p><strong>Note. </strong>The toolchain options in <code class="literal">toolchain/toolchain-external-mine/Config.in.options</code>
  1622. will not appear in the <code class="literal">Toolchain</code> menu. They must be explicitly included
  1623. from within the br2-external’s top-level <code class="literal">Config.in</code> and will thus appear
  1624. in the <code class="literal">External options</code> menu.</p></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-store-buildroot-config"></a>9.3. Storing the Buildroot configuration</h2></div></div></div><p>The Buildroot configuration can be stored using the command
  1625. <code class="literal">make savedefconfig</code>.</p><p>This strips the Buildroot configuration down by removing configuration
  1626. options that are at their default value. The result is stored in a file
  1627. called <code class="literal">defconfig</code>. If you want to save it in another place, change the
  1628. <code class="literal">BR2_DEFCONFIG</code> option in the Buildroot configuration itself, or call
  1629. make with <code class="literal">make savedefconfig BR2_DEFCONFIG=&lt;path-to-defconfig&gt;</code>.</p><p>The recommended place to store this defconfig is
  1630. <code class="literal">configs/&lt;boardname&gt;_defconfig</code>. If you follow this recommendation, the
  1631. configuration will be listed in <code class="literal">make help</code> and can be set again by
  1632. running <code class="literal">make &lt;boardname&gt;_defconfig</code>.</p><p>Alternatively, you can copy the file to any other place and rebuild with
  1633. <code class="literal">make defconfig BR2_DEFCONFIG=&lt;path-to-defconfig-file&gt;</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-store-package-config"></a>9.4. Storing the configuration of other components</h2></div></div></div><p>The configuration files for BusyBox, the Linux kernel, Barebox, U-Boot
  1634. and uClibc should be stored as well if changed. For each of these
  1635. components, a Buildroot configuration option exists to point to an input
  1636. configuration file, e.g. <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code>. To store
  1637. their configuration, set these configuration options to a path where you
  1638. want to save the configuration files, and then use the helper targets
  1639. described below to actually store the configuration.</p><p>As explained in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended path to
  1640. store these configuration files is
  1641. <code class="literal">board/&lt;company&gt;/&lt;boardname&gt;/foo.config</code>.</p><p>Make sure that you create a configuration file <span class="emphasis"><em>before</em></span> changing
  1642. the <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code> etc. options. Otherwise,
  1643. Buildroot will try to access this config file, which doesn’t exist
  1644. yet, and will fail. You can create the configuration file by running
  1645. <code class="literal">make linux-menuconfig</code> etc.</p><p>Buildroot provides a few helper targets to make the saving of
  1646. configuration files easier.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1647. <code class="literal">make linux-update-defconfig</code> saves the linux configuration to the
  1648. path specified by <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code>. It
  1649. simplifies the config file by removing default values. However,
  1650. this only works with kernels starting from 2.6.33. For earlier
  1651. kernels, use <code class="literal">make linux-update-config</code>.
  1652. </li><li class="listitem">
  1653. <code class="literal">make busybox-update-config</code> saves the busybox configuration to the
  1654. path specified by <code class="literal">BR2_PACKAGE_BUSYBOX_CONFIG</code>.
  1655. </li><li class="listitem">
  1656. <code class="literal">make uclibc-update-config</code> saves the uClibc configuration to the
  1657. path specified by <code class="literal">BR2_UCLIBC_CONFIG</code>.
  1658. </li><li class="listitem">
  1659. <code class="literal">make barebox-update-defconfig</code> saves the barebox configuration to the
  1660. path specified by <code class="literal">BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE</code>.
  1661. </li><li class="listitem">
  1662. <code class="literal">make uboot-update-defconfig</code> saves the U-Boot configuration to the
  1663. path specified by <code class="literal">BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE</code>.
  1664. </li><li class="listitem">
  1665. For at91bootstrap3, no helper exists so you have to copy the config
  1666. file manually to <code class="literal">BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE</code>.
  1667. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="rootfs-custom"></a>9.5. Customizing the generated target filesystem</h2></div></div></div><p>Besides changing the configuration through <code class="literal">make *config</code>,
  1668. there are a few other ways to customize the resulting target filesystem.</p><p>The two recommended methods, which can co-exist, are root filesystem
  1669. overlay(s) and post build script(s).</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
  1670. Root filesystem overlays (<code class="literal">BR2_ROOTFS_OVERLAY</code>)
  1671. </span></dt><dd><p class="simpara">A filesystem overlay is a tree of files that is copied directly
  1672. over the target filesystem after it has been built. To enable this
  1673. feature, set config option <code class="literal">BR2_ROOTFS_OVERLAY</code> (in the <code class="literal">System
  1674. configuration</code> menu) to the root of the overlay. You can even specify
  1675. multiple overlays, space-separated. If you specify a relative path,
  1676. it will be relative to the root of the Buildroot tree. Hidden
  1677. directories of version control systems, like <code class="literal">.git</code>, <code class="literal">.svn</code>, <code class="literal">.hg</code>,
  1678. etc., files called <code class="literal">.empty</code> and files ending in <code class="literal">~</code> are excluded from
  1679. the copy.</p><p class="simpara">When <code class="literal">BR2_ROOTFS_MERGED_USR</code> is enabled, then the overlay must not
  1680. contain the <span class="emphasis"><em>/bin</em></span>, <span class="emphasis"><em>/lib</em></span> or <span class="emphasis"><em>/sbin</em></span> directories, as Buildroot will
  1681. create them as symbolic links to the relevant folders in <span class="emphasis"><em>/usr</em></span>. In
  1682. such a situation, should the overlay have any programs or libraries,
  1683. they should be placed in <span class="emphasis"><em>/usr/bin</em></span>, <span class="emphasis"><em>/usr/sbin</em></span> and <span class="emphasis"><em>/usr/lib</em></span>.</p><p class="simpara">As shown in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended path for
  1684. this overlay is <code class="literal">board/&lt;company&gt;/&lt;boardname&gt;/rootfs-overlay</code>.</p></dd><dt><span class="term">
  1685. Post-build scripts (<code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code>)
  1686. </span></dt><dd><p class="simpara">Post-build scripts are shell scripts called <span class="emphasis"><em>after</em></span> Buildroot builds
  1687. all the selected software, but <span class="emphasis"><em>before</em></span> the rootfs images are
  1688. assembled. To enable this feature, specify a space-separated list of
  1689. post-build scripts in config option <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code> (in
  1690. the <code class="literal">System configuration</code> menu). If you specify a relative path, it
  1691. will be relative to the root of the Buildroot tree.</p><p class="simpara">Using post-build scripts, you can remove or modify any file in your
  1692. target filesystem. You should, however, use this feature with care.
  1693. Whenever you find that a certain package generates wrong or unneeded
  1694. files, you should fix that package rather than work around it with some
  1695. post-build cleanup scripts.</p><p class="simpara">As shown in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended path for
  1696. this script is <code class="literal">board/&lt;company&gt;/&lt;boardname&gt;/post_build.sh</code>.</p><p class="simpara">The post-build scripts are run with the main Buildroot tree as current
  1697. working directory. The path to the target filesystem is passed as the
  1698. first argument to each script. If the config option
  1699. <code class="literal">BR2_ROOTFS_POST_SCRIPT_ARGS</code> is not empty, these arguments will be
  1700. passed to the script too. All the scripts will be passed the exact
  1701. same set of arguments, it is not possible to pass different sets of
  1702. arguments to each script.</p><p class="simpara">In addition, you may also use these environment variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1703. <code class="literal">BR2_CONFIG</code>: the path to the Buildroot .config file
  1704. </li><li class="listitem">
  1705. <code class="literal">CONFIG_DIR</code>: the directory containing the .config file, and
  1706. therefore the top-level Buildroot Makefile to use (which is
  1707. correct for both in-tree and out-of-tree builds)
  1708. </li><li class="listitem">
  1709. <code class="literal">HOST_DIR</code>, <code class="literal">STAGING_DIR</code>, <code class="literal">TARGET_DIR</code>: see
  1710. <a class="xref" href="#generic-package-reference" title="18.5.2. generic-package reference">Section 18.5.2, “<code class="literal">generic-package</code> reference”</a>
  1711. </li><li class="listitem">
  1712. <code class="literal">BUILD_DIR</code>: the directory where packages are extracted and built
  1713. </li><li class="listitem">
  1714. <code class="literal">BINARIES_DIR</code>: the place where all binary files (aka images) are
  1715. stored
  1716. </li><li class="listitem">
  1717. <code class="literal">BASE_DIR</code>: the base output directory
  1718. </li></ul></div></dd></dl></div><p>Below three more methods of customizing the target filesystem are
  1719. described, but they are not recommended.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
  1720. Direct modification of the target filesystem
  1721. </span></dt><dd><p class="simpara">For temporary modifications, you can modify the target filesystem
  1722. directly and rebuild the image. The target filesystem is available
  1723. under <code class="literal">output/target/</code>. After making your changes, run <code class="literal">make</code> to
  1724. rebuild the target filesystem image.</p><p class="simpara">This method allows you to do anything to the target filesystem, but if
  1725. you need to clean your Buildroot tree using <code class="literal">make clean</code>, these
  1726. changes will be lost. Such cleaning is necessary in several cases,
  1727. refer to <a class="xref" href="#full-rebuild" title="8.2. Understanding when a full rebuild is necessary">Section 8.2, “Understanding when a full rebuild is necessary”</a> for details. This solution is therefore
  1728. only useful for quick tests: <span class="emphasis"><em>changes do not survive the <code class="literal">make clean</code>
  1729. command</em></span>. Once you have validated your changes, you should make sure
  1730. that they will persist after a <code class="literal">make clean</code>, using a root filesystem
  1731. overlay or a post-build script.</p></dd><dt><span class="term">
  1732. Custom target skeleton (<code class="literal">BR2_ROOTFS_SKELETON_CUSTOM</code>)
  1733. </span></dt><dd><p class="simpara">The root filesystem image is created from a target skeleton, on top of
  1734. which all packages install their files. The skeleton is copied to the
  1735. target directory <code class="literal">output/target</code> before any package is built and
  1736. installed. The default target skeleton provides the standard Unix
  1737. filesystem layout and some basic init scripts and configuration files.</p><p class="simpara">If the default skeleton (available under <code class="literal">system/skeleton</code>) does not
  1738. match your needs, you would typically use a root filesystem overlay or
  1739. post-build script to adapt it. However, if the default skeleton is
  1740. entirely different than what you need, using a custom skeleton may be
  1741. more suitable.</p><p class="simpara">To enable this feature, enable config option
  1742. <code class="literal">BR2_ROOTFS_SKELETON_CUSTOM</code> and set <code class="literal">BR2_ROOTFS_SKELETON_CUSTOM_PATH</code>
  1743. to the path of your custom skeleton. Both options are available in the
  1744. <code class="literal">System configuration</code> menu. If you specify a relative path, it will
  1745. be relative to the root of the Buildroot tree.</p><p class="simpara">Custom skeletons don’t need to contain the <span class="emphasis"><em>/bin</em></span>, <span class="emphasis"><em>/lib</em></span> or <span class="emphasis"><em>/sbin</em></span>
  1746. directories, since they are created automatically during the build.
  1747. When <code class="literal">BR2_ROOTFS_MERGED_USR</code> is enabled, then the custom skeleton must
  1748. not contain the <span class="emphasis"><em>/bin</em></span>, <span class="emphasis"><em>/lib</em></span> or <span class="emphasis"><em>/sbin</em></span> directories, as Buildroot
  1749. will create them as symbolic links to the relevant folders in <span class="emphasis"><em>/usr</em></span>.
  1750. In such a situation, should the skeleton have any programs or
  1751. libraries, they should be placed in <span class="emphasis"><em>/usr/bin</em></span>, <span class="emphasis"><em>/usr/sbin</em></span> and
  1752. <span class="emphasis"><em>/usr/lib</em></span>.</p><p class="simpara">This method is not recommended because it duplicates the entire
  1753. skeleton, which prevents taking advantage of the fixes or improvements
  1754. brought to the default skeleton in later Buildroot releases.</p></dd><dt><span class="term">
  1755. Post-fakeroot scripts (<code class="literal">BR2_ROOTFS_POST_FAKEROOT_SCRIPT</code>)
  1756. </span></dt><dd><p class="simpara">When aggregating the final images, some parts of the process requires
  1757. root rights: creating device nodes in <code class="literal">/dev</code>, setting permissions or
  1758. ownership to files and directories… To avoid requiring actual root
  1759. rights, Buildroot uses <code class="literal">fakeroot</code> to simulate root rights. This is not
  1760. a complete substitute for actually being root, but is enough for what
  1761. Buildroot needs.</p><p class="simpara">Post-fakeroot scripts are shell scripts that are called at the <span class="emphasis"><em>end</em></span> of
  1762. the fakeroot phase, <span class="emphasis"><em>right before</em></span> the filesystem image generator is
  1763. called. As such, they are called in the fakeroot context.</p><p class="simpara">Post-fakeroot scripts can be useful in case you need to tweak the
  1764. filesystem to do modifications that are usually only available to the
  1765. root user.</p><p><strong>Note: </strong>It is recommended to use the existing mechanisms to set file permissions
  1766. or create entries in <code class="literal">/dev</code> (see <a class="xref" href="#customize-device-permission" title="9.5.1. Setting file permissions and ownership and adding custom devices nodes">Section 9.5.1, “Setting file permissions and ownership and adding custom devices nodes”</a>) or
  1767. to create users (see <a class="xref" href="#customize-users" title="9.6. Adding custom user accounts">Section 9.6, “Adding custom user accounts”</a>)</p><p><strong>Note: </strong>The difference between post-build scripts (above) and fakeroot scripts,
  1768. is that post-build scripts are not called in the fakeroot context.</p><p><strong>Note: </strong>Using <code class="literal">fakeroot</code> is not an absolute substitute for actually being root.
  1769. <code class="literal">fakeroot</code> only ever fakes the file access rights and types (regular,
  1770. block-or-char device…) and uid/gid; these are emulated in-memory.</p></dd></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="customize-device-permission"></a>9.5.1. Setting file permissions and ownership and adding custom devices nodes</h3></div></div></div><p>Sometimes it is needed to set specific permissions or ownership on files
  1771. or device nodes. For example, certain files may need to be owned by
  1772. root. Since the post-build scripts are not run as root, you cannot do
  1773. such changes from there unless you use an explicit fakeroot from the
  1774. post-build script.</p><p>Instead, Buildroot provides support for so-called <span class="emphasis"><em>permission tables</em></span>.
  1775. To use this feature, set config option <code class="literal">BR2_ROOTFS_DEVICE_TABLE</code> to a
  1776. space-separated list of permission tables, regular text files following
  1777. the <a class="link" href="#makedev-syntax" title="Chapter 25. Makedev syntax documentation">makedev syntax</a>.</p><p>If you are using a static device table (i.e. not using <code class="literal">devtmpfs</code>,
  1778. <code class="literal">mdev</code>, or <code class="literal">(e)udev</code>) then you can add device nodes using the same
  1779. syntax, in so-called <span class="emphasis"><em>device tables</em></span>. To use this feature, set config
  1780. option <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code> to a space-separated list of
  1781. device tables.</p><p>As shown in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended location for
  1782. such files is <code class="literal">board/&lt;company&gt;/&lt;boardname&gt;/</code>.</p><p>It should be noted that if the specific permissions or device nodes are
  1783. related to a specific application, you should set variables
  1784. <code class="literal">FOO_PERMISSIONS</code> and <code class="literal">FOO_DEVICES</code> in the package’s <code class="literal">.mk</code> file instead
  1785. (see <a class="xref" href="#generic-package-reference" title="18.5.2. generic-package reference">Section 18.5.2, “<code class="literal">generic-package</code> reference”</a>).</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-users"></a>9.6. Adding custom user accounts</h2></div></div></div><p>Sometimes it is needed to add specific users in the target system.
  1786. To cover this requirement, Buildroot provides support for so-called
  1787. <span class="emphasis"><em>users tables</em></span>. To use this feature, set config option
  1788. <code class="literal">BR2_ROOTFS_USERS_TABLES</code> to a space-separated list of users tables,
  1789. regular text files following the <a class="link" href="#makeuser-syntax" title="Chapter 26. Makeusers syntax documentation">makeusers syntax</a>.</p><p>As shown in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended location for
  1790. such files is <code class="literal">board/&lt;company&gt;/&lt;boardname&gt;/</code>.</p><p>It should be noted that if the custom users are related to a specific
  1791. application, you should set variable <code class="literal">FOO_USERS</code> in the package’s <code class="literal">.mk</code>
  1792. file instead (see <a class="xref" href="#generic-package-reference" title="18.5.2. generic-package reference">Section 18.5.2, “<code class="literal">generic-package</code> reference”</a>).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_customization_emphasis_after_emphasis_the_images_have_been_created"></a>9.7. Customization <span class="emphasis"><em>after</em></span> the images have been created</h2></div></div></div><p>While post-build scripts (<a class="xref" href="#rootfs-custom" title="9.5. Customizing the generated target filesystem">Section 9.5, “Customizing the generated target filesystem”</a>) are run <span class="emphasis"><em>before</em></span>
  1793. building the filesystem image, kernel and bootloader, <span class="strong"><strong>post-image
  1794. scripts</strong></span> can be used to perform some specific actions <span class="emphasis"><em>after</em></span> all images
  1795. have been created.</p><p>Post-image scripts can for example be used to automatically extract your
  1796. root filesystem tarball in a location exported by your NFS server, or
  1797. to create a special firmware image that bundles your root filesystem and
  1798. kernel image, or any other custom action required for your project.</p><p>To enable this feature, specify a space-separated list of post-image
  1799. scripts in config option <code class="literal">BR2_ROOTFS_POST_IMAGE_SCRIPT</code> (in the <code class="literal">System
  1800. configuration</code> menu). If you specify a relative path, it will be
  1801. relative to the root of the Buildroot tree.</p><p>Just like post-build scripts, post-image scripts are run with the main
  1802. Buildroot tree as current working directory. The path to the <code class="literal">images</code>
  1803. output directory is passed as the first argument to each script. If the
  1804. config option <code class="literal">BR2_ROOTFS_POST_SCRIPT_ARGS</code> is not empty, these
  1805. arguments will be passed to the script too. All the scripts will be
  1806. passed the exact same set of arguments, it is not possible to pass
  1807. different sets of arguments to each script.</p><p>Again just like for the post-build scripts, the scripts have access to
  1808. the environment variables <code class="literal">BR2_CONFIG</code>, <code class="literal">HOST_DIR</code>, <code class="literal">STAGING_DIR</code>,
  1809. <code class="literal">TARGET_DIR</code>, <code class="literal">BUILD_DIR</code>, <code class="literal">BINARIES_DIR</code>, <code class="literal">CONFIG_DIR</code> and
  1810. <code class="literal">BASE_DIR</code>.</p><p>The post-image scripts will be executed as the user that executes
  1811. Buildroot, which should normally <span class="emphasis"><em>not</em></span> be the root user. Therefore, any
  1812. action requiring root permissions in one of these scripts will require
  1813. special handling (usage of fakeroot or sudo), which is left to the
  1814. script developer.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-patches"></a>9.8. Adding project-specific patches</h2></div></div></div><p>It is sometimes useful to apply <span class="emphasis"><em>extra</em></span> patches to packages - on top of
  1815. those provided in Buildroot. This might be used to support custom
  1816. features in a project, for example, or when working on a new
  1817. architecture.</p><p>The <code class="literal">BR2_GLOBAL_PATCH_DIR</code> configuration option can be used to specify
  1818. a space separated list of one or more directories containing package
  1819. patches.</p><p>For a specific version <code class="literal">&lt;packageversion&gt;</code> of a specific package
  1820. <code class="literal">&lt;packagename&gt;</code>, patches are applied from <code class="literal">BR2_GLOBAL_PATCH_DIR</code> as
  1821. follows:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p class="simpara">
  1822. For every directory - <code class="literal">&lt;global-patch-dir&gt;</code> - that exists in
  1823. <code class="literal">BR2_GLOBAL_PATCH_DIR</code>, a <code class="literal">&lt;package-patch-dir&gt;</code> will be determined as
  1824. follows:
  1825. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1826. <code class="literal">&lt;global-patch-dir&gt;/&lt;packagename&gt;/&lt;packageversion&gt;/</code> if the
  1827. directory exists.
  1828. </li><li class="listitem">
  1829. Otherwise, <code class="literal">&lt;global-patch-dir&gt;/&lt;packagename&gt;</code> if the directory
  1830. exists.
  1831. </li></ul></div></li><li class="listitem"><p class="simpara">
  1832. Patches will then be applied from a <code class="literal">&lt;package-patch-dir&gt;</code> as
  1833. follows:
  1834. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1835. If a <code class="literal">series</code> file exists in the package directory, then patches are
  1836. applied according to the <code class="literal">series</code> file;
  1837. </li><li class="listitem">
  1838. Otherwise, patch files matching <code class="literal">*.patch</code> are applied in
  1839. alphabetical order. So, to ensure they are applied in the right
  1840. order, it is highly recommended to name the patch files like this:
  1841. <code class="literal">&lt;number&gt;-&lt;description&gt;.patch</code>, where <code class="literal">&lt;number&gt;</code> refers to the
  1842. <span class="emphasis"><em>apply order</em></span>.
  1843. </li></ul></div></li></ol></div><p>For information about how patches are applied for a package, see
  1844. <a class="xref" href="#patch-apply-order" title="19.2. How patches are applied">Section 19.2, “How patches are applied”</a></p><p>The <code class="literal">BR2_GLOBAL_PATCH_DIR</code> option is the preferred method for
  1845. specifying a custom patch directory for packages. It can be used to
  1846. specify a patch directory for any package in buildroot. It should also
  1847. be used in place of the custom patch directory options that are
  1848. available for packages such as U-Boot and Barebox. By doing this, it
  1849. will allow a user to manage their patches from one top-level
  1850. directory.</p><p>The exception to <code class="literal">BR2_GLOBAL_PATCH_DIR</code> being the preferred method for
  1851. specifying custom patches is <code class="literal">BR2_LINUX_KERNEL_PATCH</code>.
  1852. <code class="literal">BR2_LINUX_KERNEL_PATCH</code> should be used to specify kernel patches that
  1853. are available at a URL. <span class="strong"><strong>Note:</strong></span> <code class="literal">BR2_LINUX_KERNEL_PATCH</code> specifies kernel
  1854. patches that are applied after patches available in <code class="literal">BR2_GLOBAL_PATCH_DIR</code>,
  1855. as it is done from a post-patch hook of the Linux package.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-packages"></a>9.9. Adding project-specific packages</h2></div></div></div><p>In general, any new package should be added directly in the <code class="literal">package</code>
  1856. directory and submitted to the Buildroot upstream project. How to add
  1857. packages to Buildroot in general is explained in full detail in
  1858. <a class="xref" href="#adding-packages" title="Chapter 18. Adding new packages to Buildroot">Chapter 18, <em>Adding new packages to Buildroot</em></a> and will not be repeated here. However, your
  1859. project may need some proprietary packages that cannot be upstreamed.
  1860. This section will explain how you can keep such project-specific
  1861. packages in a project-specific directory.</p><p>As shown in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended location for
  1862. project-specific packages is <code class="literal">package/&lt;company&gt;/</code>. If you are using the
  1863. br2-external tree feature (see <a class="xref" href="#outside-br-custom" title="9.2. Keeping customizations outside of Buildroot">Section 9.2, “Keeping customizations outside of Buildroot”</a>) the recommended
  1864. location is to put them in a sub-directory named <code class="literal">package/</code> in your
  1865. br2-external tree.</p><p>However, Buildroot will not be aware of the packages in this location,
  1866. unless we perform some additional steps. As explained in
  1867. <a class="xref" href="#adding-packages" title="Chapter 18. Adding new packages to Buildroot">Chapter 18, <em>Adding new packages to Buildroot</em></a>, a package in Buildroot basically consists of two
  1868. files: a <code class="literal">.mk</code> file (describing how to build the package) and a
  1869. <code class="literal">Config.in</code> file (describing the configuration options for this
  1870. package).</p><p>Buildroot will automatically include the <code class="literal">.mk</code> files in first-level
  1871. subdirectories of the <code class="literal">package</code> directory (using the pattern
  1872. <code class="literal">package/*/*.mk</code>). If we want Buildroot to include <code class="literal">.mk</code> files from
  1873. deeper subdirectories (like <code class="literal">package/&lt;company&gt;/package1/</code>) then we
  1874. simply have to add a <code class="literal">.mk</code> file in a first-level subdirectory that
  1875. includes these additional <code class="literal">.mk</code> files. Therefore, create a file
  1876. <code class="literal">package/&lt;company&gt;/&lt;company&gt;.mk</code> with following contents (assuming you
  1877. have only one extra directory level below <code class="literal">package/&lt;company&gt;/</code>):</p><pre class="screen">include $(sort $(wildcard package/&lt;company&gt;/*/*.mk))</pre><p>For the <code class="literal">Config.in</code> files, create a file <code class="literal">package/&lt;company&gt;/Config.in</code>
  1878. that includes the <code class="literal">Config.in</code> files of all your packages. An exhaustive
  1879. list has to be provided since wildcards are not supported in the source command of kconfig.
  1880. For example:</p><pre class="screen">source "package/&lt;company&gt;/package1/Config.in"
  1881. source "package/&lt;company&gt;/package2/Config.in"</pre><p>Include this new file <code class="literal">package/&lt;company&gt;/Config.in</code> from
  1882. <code class="literal">package/Config.in</code>, preferably in a company-specific menu to make
  1883. merges with future Buildroot versions easier.</p><p>If using a br2-external tree, refer to <a class="xref" href="#outside-br-custom" title="9.2. Keeping customizations outside of Buildroot">Section 9.2, “Keeping customizations outside of Buildroot”</a> for how
  1884. to fill in those files.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_quick_guide_to_storing_your_project_specific_customizations"></a>9.10. Quick guide to storing your project-specific customizations</h2></div></div></div><p>Earlier in this chapter, the different methods for making
  1885. project-specific customizations have been described. This section will
  1886. now summarize all this by providing step-by-step instructions to storing your
  1887. project-specific customizations. Clearly, the steps that are not relevant to
  1888. your project can be skipped.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
  1889. <code class="literal">make menuconfig</code> to configure toolchain, packages and kernel.
  1890. </li><li class="listitem">
  1891. <code class="literal">make linux-menuconfig</code> to update the kernel config, similar for
  1892. other configuration like busybox, uclibc, …
  1893. </li><li class="listitem">
  1894. <code class="literal">mkdir -p board/&lt;manufacturer&gt;/&lt;boardname&gt;</code>
  1895. </li><li class="listitem"><p class="simpara">
  1896. Set the following options to <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/&lt;package&gt;.config</code>
  1897. (as far as they are relevant):
  1898. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1899. <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code>
  1900. </li><li class="listitem">
  1901. <code class="literal">BR2_PACKAGE_BUSYBOX_CONFIG</code>
  1902. </li><li class="listitem">
  1903. <code class="literal">BR2_UCLIBC_CONFIG</code>
  1904. </li><li class="listitem">
  1905. <code class="literal">BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE</code>
  1906. </li><li class="listitem">
  1907. <code class="literal">BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE</code>
  1908. </li><li class="listitem">
  1909. <code class="literal">BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE</code>
  1910. </li></ul></div></li><li class="listitem"><p class="simpara">
  1911. Write the configuration files:
  1912. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1913. <code class="literal">make linux-update-defconfig</code>
  1914. </li><li class="listitem">
  1915. <code class="literal">make busybox-update-config</code>
  1916. </li><li class="listitem">
  1917. <code class="literal">make uclibc-update-config</code>
  1918. </li><li class="listitem">
  1919. <code class="literal">cp &lt;output&gt;/build/at91bootstrap3-*/.config
  1920. board/&lt;manufacturer&gt;/&lt;boardname&gt;/at91bootstrap3.config</code>
  1921. </li><li class="listitem">
  1922. <code class="literal">make barebox-update-defconfig</code>
  1923. </li><li class="listitem">
  1924. <code class="literal">make uboot-update-defconfig</code>
  1925. </li></ul></div></li><li class="listitem">
  1926. Create <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/rootfs-overlay/</code> and fill it
  1927. with additional files you need on your rootfs, e.g.
  1928. <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/rootfs-overlay/etc/inittab</code>.
  1929. Set <code class="literal">BR2_ROOTFS_OVERLAY</code>
  1930. to <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/rootfs-overlay</code>.
  1931. </li><li class="listitem">
  1932. Create a post-build script
  1933. <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/post_build.sh</code>. Set
  1934. <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code> to
  1935. <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/post_build.sh</code>
  1936. </li><li class="listitem">
  1937. If additional setuid permissions have to be set or device nodes have
  1938. to be created, create <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/device_table.txt</code>
  1939. and add that path to <code class="literal">BR2_ROOTFS_DEVICE_TABLE</code>.
  1940. </li><li class="listitem">
  1941. If additional user accounts have to be created, create
  1942. <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/users_table.txt</code> and add that path
  1943. to <code class="literal">BR2_ROOTFS_USERS_TABLES</code>.
  1944. </li><li class="listitem">
  1945. To add custom patches to certain packages, set <code class="literal">BR2_GLOBAL_PATCH_DIR</code>
  1946. to <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/patches/</code> and add your patches
  1947. for each package in a subdirectory named after the package. Each
  1948. patch should be called <code class="literal">&lt;packagename&gt;-&lt;num&gt;-&lt;description&gt;.patch</code>.
  1949. </li><li class="listitem">
  1950. Specifically for the Linux kernel, there also exists the option
  1951. <code class="literal">BR2_LINUX_KERNEL_PATCH</code> with as main advantage that it can also
  1952. download patches from a URL. If you do not need this,
  1953. <code class="literal">BR2_GLOBAL_PATCH_DIR</code> is preferred. U-Boot, Barebox, at91bootstrap
  1954. and at91bootstrap3 also have separate options, but these do not
  1955. provide any advantage over <code class="literal">BR2_GLOBAL_PATCH_DIR</code> and will likely be
  1956. removed in the future.
  1957. </li><li class="listitem">
  1958. If you need to add project-specific packages, create
  1959. <code class="literal">package/&lt;manufacturer&gt;/</code> and place your packages in that
  1960. directory. Create an overall <code class="literal">&lt;manufacturer&gt;.mk</code> file that
  1961. includes the <code class="literal">.mk</code> files of all your packages. Create an overall
  1962. <code class="literal">Config.in</code> file that sources the <code class="literal">Config.in</code> files of all your
  1963. packages. Include this <code class="literal">Config.in</code> file from Buildroot’s
  1964. <code class="literal">package/Config.in</code> file.
  1965. </li><li class="listitem">
  1966. <code class="literal">make savedefconfig</code> to save the buildroot configuration.
  1967. </li><li class="listitem">
  1968. <code class="literal">cp defconfig configs/&lt;boardname&gt;_defconfig</code>
  1969. </li></ol></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="selinux"></a>Chapter 10. Using SELinux in Buildroot</h2></div></div></div><p><a class="ulink" href="https://selinuxproject.org" target="_top">SELinux</a> is a Linux kernel security module
  1970. enforcing access control policies. In addition to the traditional file
  1971. permissions and access control lists, <code class="literal">SELinux</code> allows to write rules
  1972. for users or processes to access specific functions of resources
  1973. (files, sockets…).</p><p><span class="emphasis"><em>SELinux</em></span> has three modes of operation:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1974. <span class="emphasis"><em>Disabled</em></span>: the policy is not applied
  1975. </li><li class="listitem">
  1976. <span class="emphasis"><em>Permissive</em></span>: the policy is applied, and non-authorized actions are
  1977. simply logged. This mode is often used for troubleshooting SELinux
  1978. issues.
  1979. </li><li class="listitem">
  1980. <span class="emphasis"><em>Enforcing</em></span>: the policy is applied, and non-authorized actions are
  1981. denied
  1982. </li></ul></div><p>In Buildroot the mode of operation is controlled by the
  1983. <code class="literal">BR2_PACKAGE_REFPOLICY_POLICY_STATE_*</code> configuration options. The
  1984. Linux kernel also has various configuration options that affect how
  1985. <code class="literal">SELinux</code> is enabled (see <code class="literal">security/selinux/Kconfig</code> in the Linux
  1986. kernel sources).</p><p>By default in Buildroot the <code class="literal">SELinux</code> policy is provided by the
  1987. upstream <a class="ulink" href="https://github.com/SELinuxProject/refpolicy" target="_top">refpolicy</a>
  1988. project, enabled with <code class="literal">BR2_PACKAGE_REFPOLICY</code>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="enabling-selinux"></a>10.1. Enabling SELinux support</h2></div></div></div><p>To have proper support for <code class="literal">SELinux</code> in a Buildroot generated system,
  1989. the following configuration options must be enabled:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1990. <code class="literal">BR2_PACKAGE_LIBSELINUX</code>
  1991. </li><li class="listitem">
  1992. <code class="literal">BR2_PACKAGE_REFPOLICY</code>
  1993. </li></ul></div><p>In addition, your filesystem image format must support extended
  1994. attributes.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="selinux-policy-tweaking"></a>10.2. SELinux policy tweaking</h2></div></div></div><p>The <code class="literal">SELinux refpolicy</code> contains modules that can be enabled or
  1995. disabled when being built. Each module provide a number of <code class="literal">SELinux</code>
  1996. rules. In Buildroot the non-base modules are disabled by default and
  1997. several ways to enable such modules are provided:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  1998. Packages can enable a list of <code class="literal">SELinux</code> modules within the <code class="literal">refpolicy</code> using
  1999. the <code class="literal">&lt;packagename&gt;_SELINUX_MODULES</code> variable.
  2000. </li><li class="listitem">
  2001. Packages can provide additional <code class="literal">SELinux</code> modules by putting them (.fc, .if
  2002. and .te files) in <code class="literal">package/&lt;packagename&gt;/selinux/</code>.
  2003. </li><li class="listitem">
  2004. Extra <code class="literal">SELinux</code> modules can be added in directories pointed by the
  2005. <code class="literal">BR2_REFPOLICY_EXTRA_MODULES_DIRS</code> configuration option.
  2006. </li><li class="listitem">
  2007. Additional modules in the <code class="literal">refpolicy</code> can be enabled if listed in the
  2008. <code class="literal">BR2_REFPOLICY_EXTRA_MODULES_DEPENDENCIES</code> configuration option.
  2009. </li></ul></div><p>Buildroot also allows to completely override the <code class="literal">refpolicy</code>. This
  2010. allows to provide a full custom policy designed specifically for a
  2011. given system. When going this way, all of the above mechanisms are
  2012. disabled: no extra <code class="literal">SElinux</code> module is added to the policy, and all
  2013. the available modules within the custom policy are enabled and built
  2014. into the final binary policy. The custom policy must be a fork of the
  2015. official <a class="ulink" href="https://github.com/SELinuxProject/refpolicy" target="_top">refpolicy</a>.</p><p>In order to fully override the <code class="literal">refpolicy</code> the following configuration
  2016. variables have to be set:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2017. <code class="literal">BR2_PACKAGE_REFPOLICY_CUSTOM_GIT</code>
  2018. </li><li class="listitem">
  2019. <code class="literal">BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_URL</code>
  2020. </li><li class="listitem">
  2021. <code class="literal">BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_VERSION</code>
  2022. </li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_frequently_asked_questions_amp_troubleshooting"></a>Chapter 11. Frequently Asked Questions &amp; Troubleshooting</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-boot-hang-after-starting"></a>11.1. The boot hangs after <span class="emphasis"><em>Starting network…</em></span></h2></div></div></div><p>If the boot process seems to hang after the following messages
  2023. (messages not necessarily exactly similar, depending on the list of
  2024. packages selected):</p><pre class="screen">Freeing init memory: 3972K
  2025. Initializing random number generator... done.
  2026. Starting network...
  2027. Starting dropbear sshd: generating rsa key... generating dsa key... OK</pre><p>then it means that your system is running, but didn’t start a shell on
  2028. the serial console. In order to have the system start a shell on your
  2029. serial console, you have to go into the Buildroot configuration, in
  2030. <code class="literal">System configuration</code>, modify <code class="literal">Run a getty (login prompt) after boot</code>
  2031. and set the appropriate port and baud rate in the <code class="literal">getty options</code>
  2032. submenu. This will automatically tune the <code class="literal">/etc/inittab</code> file of the
  2033. generated system so that a shell starts on the correct serial port.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-no-compiler-on-target"></a>11.2. Why is there no compiler on the target?</h2></div></div></div><p>It has been decided that support for the <span class="emphasis"><em>native compiler on the
  2034. target</em></span> would be stopped from the Buildroot-2012.11 release because:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2035. this feature was neither maintained nor tested, and often broken;
  2036. </li><li class="listitem">
  2037. this feature was only available for Buildroot toolchains;
  2038. </li><li class="listitem">
  2039. Buildroot mostly targets <span class="emphasis"><em>small</em></span> or <span class="emphasis"><em>very small</em></span> target hardware
  2040. with limited resource onboard (CPU, ram, mass-storage), for which
  2041. compiling on the target does not make much sense;
  2042. </li><li class="listitem">
  2043. Buildroot aims at easing the cross-compilation, making native
  2044. compilation on the target unnecessary.
  2045. </li></ul></div><p>If you need a compiler on your target anyway, then Buildroot is not
  2046. suitable for your purpose. In such case, you need a <span class="emphasis"><em>real
  2047. distribution</em></span> and you should opt for something like:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2048. <a class="ulink" href="http://www.openembedded.org" target="_top">openembedded</a>
  2049. </li><li class="listitem">
  2050. <a class="ulink" href="https://www.yoctoproject.org" target="_top">yocto</a>
  2051. </li><li class="listitem">
  2052. <a class="ulink" href="http://www.emdebian.org" target="_top">emdebian</a>
  2053. </li><li class="listitem">
  2054. <a class="ulink" href="https://fedoraproject.org/wiki/Architectures" target="_top">Fedora</a>
  2055. </li><li class="listitem">
  2056. <a class="ulink" href="http://en.opensuse.org/Portal:ARM" target="_top">openSUSE ARM</a>
  2057. </li><li class="listitem">
  2058. <a class="ulink" href="http://archlinuxarm.org" target="_top">Arch Linux ARM</a>
  2059. </li><li class="listitem">
  2060. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-no-dev-files-on-target"></a>11.3. Why are there no development files on the target?</h2></div></div></div><p>Since there is no compiler available on the target (see
  2061. <a class="xref" href="#faq-no-compiler-on-target" title="11.2. Why is there no compiler on the target?">Section 11.2, “Why is there no compiler on the target?”</a>), it does not make sense to waste
  2062. space with headers or static libraries.</p><p>Therefore, those files are always removed from the target since the
  2063. Buildroot-2012.11 release.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-no-doc-on-target"></a>11.4. Why is there no documentation on the target?</h2></div></div></div><p>Because Buildroot mostly targets <span class="emphasis"><em>small</em></span> or <span class="emphasis"><em>very small</em></span> target
  2064. hardware with limited resource onboard (CPU, ram, mass-storage), it
  2065. does not make sense to waste space with the documentation data.</p><p>If you need documentation data on your target anyway, then Buildroot
  2066. is not suitable for your purpose, and you should look for a <span class="emphasis"><em>real
  2067. distribution</em></span> (see: <a class="xref" href="#faq-no-compiler-on-target" title="11.2. Why is there no compiler on the target?">Section 11.2, “Why is there no compiler on the target?”</a>).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-why-not-visible-package"></a>11.5. Why are some packages not visible in the Buildroot config menu?</h2></div></div></div><p>If a package exists in the Buildroot tree and does not appear in the
  2068. config menu, this most likely means that some of the package’s
  2069. dependencies are not met.</p><p>To know more about the dependencies of a package, search for the
  2070. package symbol in the config menu (see <a class="xref" href="#make-tips" title="8.1. make tips">Section 8.1, “<span class="emphasis"><em>make</em></span> tips”</a>).</p><p>Then, you may have to recursively enable several options (which
  2071. correspond to the unmet dependencies) to finally be able to select
  2072. the package.</p><p>If the package is not visible due to some unmet toolchain options,
  2073. then you should certainly run a full rebuild (see <a class="xref" href="#make-tips" title="8.1. make tips">Section 8.1, “<span class="emphasis"><em>make</em></span> tips”</a> for
  2074. more explanations).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-why-not-use-target-as-chroot"></a>11.6. Why not use the target directory as a chroot directory?</h2></div></div></div><p>There are plenty of reasons to <span class="strong"><strong>not</strong></span> use the target directory a chroot
  2075. one, among these:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2076. file ownerships, modes and permissions are not correctly set in the
  2077. target directory;
  2078. </li><li class="listitem">
  2079. device nodes are not created in the target directory.
  2080. </li></ul></div><p>For these reasons, commands run through chroot, using the target
  2081. directory as the new root, will most likely fail.</p><p>If you want to run the target filesystem inside a chroot, or as an NFS
  2082. root, then use the tarball image generated in <code class="literal">images/</code> and extract it
  2083. as root.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-no-binary-packages"></a>11.7. Why doesn’t Buildroot generate binary packages (.deb, .ipkg…)?</h2></div></div></div><p>One feature that is often discussed on the Buildroot list is the
  2084. general topic of "package management". To summarize, the idea
  2085. would be to add some tracking of which Buildroot package installs
  2086. what files, with the goals of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2087. being able to remove files installed by a package when this package
  2088. gets unselected from the menuconfig;
  2089. </li><li class="listitem">
  2090. being able to generate binary packages (ipk or other format) that
  2091. can be installed on the target without re-generating a new root
  2092. filesystem image.
  2093. </li></ul></div><p>In general, most people think it is easy to do: just track which package
  2094. installed what and remove it when the package is unselected. However, it
  2095. is much more complicated than that:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2096. It is not only about the <code class="literal">target/</code> directory, but also the sysroot in
  2097. <code class="literal">host/&lt;tuple&gt;/sysroot</code> and the <code class="literal">host/</code> directory itself. All files
  2098. installed in those directories by various packages must be tracked.
  2099. </li><li class="listitem">
  2100. When a package is unselected from the configuration, it is not
  2101. sufficient to remove just the files it installed. One must also
  2102. remove all its reverse dependencies (i.e. packages relying on it)
  2103. and rebuild all those packages. For example, package A depends
  2104. optionally on the OpenSSL library. Both are selected, and Buildroot
  2105. is built. Package A is built with crypto support using OpenSSL.
  2106. Later on, OpenSSL gets unselected from the configuration, but
  2107. package A remains (since OpenSSL is an optional dependency, this
  2108. is possible.) If only OpenSSL files are removed, then the files
  2109. installed by package A are broken: they use a library that is no
  2110. longer present on the target. Although this is technically doable,
  2111. it adds a lot of complexity to Buildroot, which goes against the
  2112. simplicity we try to stick to.
  2113. </li><li class="listitem">
  2114. In addition to the previous problem, there is the case where the
  2115. optional dependency is not even known to Buildroot. For example,
  2116. package A in version 1.0 never used OpenSSL, but in version 2.0 it
  2117. automatically uses OpenSSL if available. If the Buildroot .mk file
  2118. hasn’t been updated to take this into account, then package A will
  2119. not be part of the reverse dependencies of OpenSSL and will not be
  2120. removed and rebuilt when OpenSSL is removed. For sure, the .mk file
  2121. of package A should be fixed to mention this optional dependency,
  2122. but in the mean time, you can have non-reproducible behaviors.
  2123. </li><li class="listitem">
  2124. The request is to also allow changes in the menuconfig to be
  2125. applied on the output directory without having to rebuild
  2126. everything from scratch. However, this is very difficult to achieve
  2127. in a reliable way: what happens when the suboptions of a package
  2128. are changed (we would have to detect this, and rebuild the package
  2129. from scratch and potentially all its reverse dependencies), what
  2130. happens if toolchain options are changed, etc. At the moment, what
  2131. Buildroot does is clear and simple so its behaviour is very
  2132. reliable and it is easy to support users. If configuration changes
  2133. done in menuconfig are applied after the next make, then it has to
  2134. work correctly and properly in all situations, and not have some
  2135. bizarre corner cases. The risk is to get bug reports like "I have
  2136. enabled package A, B and C, then ran make, then disabled package
  2137. C and enabled package D and ran make, then re-enabled package C
  2138. and enabled package E and then there is a build failure". Or worse
  2139. "I did some configuration, then built, then did some changes,
  2140. built, some more changes, built, some more changes, built, and now
  2141. it fails, but I don’t remember all the changes I did and in which
  2142. order". This will be impossible to support.
  2143. </li></ul></div><p>For all these reasons, the conclusion is that adding tracking of
  2144. installed files to remove them when the package is unselected, or to
  2145. generate a repository of binary packages, is something that is very
  2146. hard to achieve reliably and will add a lot of complexity.</p><p>On this matter, the Buildroot developers make this position statement:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2147. Buildroot strives to make it easy to generate a root filesystem (hence
  2148. the name, by the way.) That is what we want to make Buildroot good at:
  2149. building root filesystems.
  2150. </li><li class="listitem">
  2151. Buildroot is not meant to be a distribution (or rather, a distribution
  2152. generator.) It is the opinion of most Buildroot developers that this
  2153. is not a goal we should pursue. We believe that there are other tools
  2154. better suited to generate a distro than Buildroot is. For example,
  2155. <a class="ulink" href="http://openembedded.org/" target="_top">Open Embedded</a>, or <a class="ulink" href="https://openwrt.org/" target="_top">openWRT</a>,
  2156. are such tools.
  2157. </li><li class="listitem">
  2158. We prefer to push Buildroot in a direction that makes it easy (or even
  2159. easier) to generate complete root filesystems. This is what makes
  2160. Buildroot stands out in the crowd (among other things, of course!)
  2161. </li><li class="listitem">
  2162. We believe that for most embedded Linux systems, binary packages are
  2163. not necessary, and potentially harmful. When binary packages are
  2164. used, it means that the system can be partially upgraded, which
  2165. creates an enormous number of possible combinations of package
  2166. versions that should be tested before doing the upgrade on the
  2167. embedded device. On the other hand, by doing complete system
  2168. upgrades by upgrading the entire root filesystem image at once,
  2169. the image deployed to the embedded system is guaranteed to really
  2170. be the one that has been tested and validated.
  2171. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-speeding-up-build"></a>11.8. How to speed-up the build process?</h2></div></div></div><p>Since Buildroot often involves doing full rebuilds of the entire
  2172. system that can be quite long, we provide below a number of tips to
  2173. help reduce the build time:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2174. Use a pre-built external toolchain instead of the default Buildroot
  2175. internal toolchain. By using a pre-built Linaro toolchain (on ARM)
  2176. or a Sourcery CodeBench toolchain (for ARM, x86, x86-64, MIPS,
  2177. etc.), you will save the build time of the toolchain at each
  2178. complete rebuild, approximately 15 to 20 minutes. Note that
  2179. temporarily using an external toolchain does not prevent you to
  2180. switch back to an internal toolchain (that may provide a higher
  2181. level of customization) once the rest of your system is working;
  2182. </li><li class="listitem">
  2183. Use the <code class="literal">ccache</code> compiler cache (see: <a class="xref" href="#ccache" title="8.14.3. Using ccache in Buildroot">Section 8.14.3, “Using <code class="literal">ccache</code> in Buildroot”</a>);
  2184. </li><li class="listitem">
  2185. Learn about rebuilding only the few packages you actually care
  2186. about (see <a class="xref" href="#rebuild-pkg" title="8.3. Understanding how to rebuild packages">Section 8.3, “Understanding how to rebuild packages”</a>), but beware that sometimes full
  2187. rebuilds are anyway necessary (see <a class="xref" href="#full-rebuild" title="8.2. Understanding when a full rebuild is necessary">Section 8.2, “Understanding when a full rebuild is necessary”</a>);
  2188. </li><li class="listitem">
  2189. Make sure you are not using a virtual machine for the Linux system
  2190. used to run Buildroot. Most of the virtual machine technologies are
  2191. known to cause a significant performance impact on I/O, which is
  2192. really important for building source code;
  2193. </li><li class="listitem">
  2194. Make sure that you’re using only local files: do not attempt to do
  2195. a build over NFS, which significantly slows down the build. Having
  2196. the Buildroot download folder available locally also helps a bit.
  2197. </li><li class="listitem">
  2198. Buy new hardware. SSDs and lots of RAM are key to speeding up the
  2199. builds.
  2200. </li><li class="listitem">
  2201. Experiment with top-level parallel build, see
  2202. <a class="xref" href="#top-level-parallel-build" title="8.12. Top-level parallel build">Section 8.12, “Top-level parallel build”</a>.
  2203. </li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_known_issues"></a>Chapter 12. Known issues</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2204. It is not possible to pass extra linker options via <code class="literal">BR2_TARGET_LDFLAGS</code>
  2205. if such options contain a <code class="literal">$</code> sign. For example, the following is known
  2206. to break: <code class="literal">BR2_TARGET_LDFLAGS="-Wl,-rpath='$ORIGIN/../lib'"</code>
  2207. </li><li class="listitem">
  2208. The <code class="literal">libffi</code> package is not supported on the SuperH 2 and ARC
  2209. architectures.
  2210. </li><li class="listitem">
  2211. The <code class="literal">prboom</code> package triggers a compiler failure with the SuperH 4
  2212. compiler from Sourcery CodeBench, version 2012.09.
  2213. </li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="legal-info"></a>Chapter 13. Legal notice and licensing</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_complying_with_open_source_licenses"></a>13.1. Complying with open source licenses</h2></div></div></div><p>All of the end products of Buildroot (toolchain, root filesystem, kernel,
  2214. bootloaders) contain open source software, released under various licenses.</p><p>Using open source software gives you the freedom to build rich embedded
  2215. systems, choosing from a wide range of packages, but also imposes some
  2216. obligations that you must know and honour.
  2217. Some licenses require you to publish the license text in the documentation of
  2218. your product. Others require you to redistribute the source code of the
  2219. software to those that receive your product.</p><p>The exact requirements of each license are documented in each package, and
  2220. it is your responsibility (or that of your legal office) to comply with those
  2221. requirements.
  2222. To make this easier for you, Buildroot can collect for you some material you
  2223. will probably need. To produce this material, after you have configured
  2224. Buildroot with <code class="literal">make menuconfig</code>, <code class="literal">make xconfig</code> or <code class="literal">make gconfig</code>, run:</p><pre class="screen">make legal-info</pre><p>Buildroot will collect legally-relevant material in your output directory,
  2225. under the <code class="literal">legal-info/</code> subdirectory.
  2226. There you will find:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2227. A <code class="literal">README</code> file, that summarizes the produced material and contains warnings
  2228. about material that Buildroot could not produce.
  2229. </li><li class="listitem">
  2230. <code class="literal">buildroot.config</code>: this is the Buildroot configuration file that is usually
  2231. produced with <code class="literal">make menuconfig</code>, and which is necessary to reproduce the
  2232. build.
  2233. </li><li class="listitem">
  2234. The source code for all packages; this is saved in the <code class="literal">sources/</code> and
  2235. <code class="literal">host-sources/</code> subdirectories for target and host packages respectively.
  2236. The source code for packages that set <code class="literal">&lt;PKG&gt;_REDISTRIBUTE = NO</code> will not be
  2237. saved.
  2238. Patches that were applied are also saved, along with a file named <code class="literal">series</code>
  2239. that lists the patches in the order they were applied. Patches are under the
  2240. same license as the files that they modify.
  2241. Note: Buildroot applies additional patches to Libtool scripts of
  2242. autotools-based packages. These patches can be found under
  2243. <code class="literal">support/libtool</code> in the Buildroot source and, due to technical
  2244. limitations, are not saved with the package sources. You may need to
  2245. collect them manually.
  2246. </li><li class="listitem">
  2247. A manifest file (one for host and one for target packages) listing the
  2248. configured packages, their version, license and related information.
  2249. Some of this information might not be defined in Buildroot; such items are
  2250. marked as "unknown".
  2251. </li><li class="listitem">
  2252. The license texts of all packages, in the <code class="literal">licenses/</code> and <code class="literal">host-licenses/</code>
  2253. subdirectories for target and host packages respectively.
  2254. If the license file(s) are not defined in Buildroot, the file is not produced
  2255. and a warning in the <code class="literal">README</code> indicates this.
  2256. </li></ul></div><p>Please note that the aim of the <code class="literal">legal-info</code> feature of Buildroot is to
  2257. produce all the material that is somehow relevant for legal compliance with the
  2258. package licenses. Buildroot does not try to produce the exact material that
  2259. you must somehow make public. Certainly, more material is produced than is
  2260. needed for a strict legal compliance. For example, it produces the source code
  2261. for packages released under BSD-like licenses, that you are not required to
  2262. redistribute in source form.</p><p>Moreover, due to technical limitations, Buildroot does not produce some
  2263. material that you will or may need, such as the toolchain source code for
  2264. some of the external toolchains and the Buildroot source code itself.
  2265. When you run <code class="literal">make legal-info</code>, Buildroot produces warnings in the <code class="literal">README</code>
  2266. file to inform you of relevant material that could not be saved.</p><p>Finally, keep in mind that the output of <code class="literal">make legal-info</code> is based on
  2267. declarative statements in each of the packages recipes. The Buildroot
  2268. developers try to do their best to keep those declarative statements as
  2269. accurate as possible, to the best of their knowledge. However, it is very
  2270. well possible that those declarative statements are not all fully accurate
  2271. nor exhaustive. You (or your legal department) <span class="emphasis"><em>have</em></span> to check the output
  2272. of <code class="literal">make legal-info</code> before using it as your own compliance delivery. See
  2273. the <span class="emphasis"><em>NO WARRANTY</em></span> clauses (clauses 11 and 12) in the <code class="literal">COPYING</code> file at the
  2274. root of the Buildroot distribution.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="legal-info-buildroot"></a>13.2. Complying with the Buildroot license</h2></div></div></div><p>Buildroot itself is an open source software, released under the
  2275. <a class="ulink" href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" target="_top">GNU General
  2276. Public License, version 2</a> or (at your option) any later version, with
  2277. the exception of the package patches detailed below.
  2278. However, being a build system, it is not normally part of the end product:
  2279. if you develop the root filesystem, kernel, bootloader or toolchain for a
  2280. device, the code of Buildroot is only present on the development machine, not
  2281. in the device storage.</p><p>Nevertheless, the general view of the Buildroot developers is that you should
  2282. release the Buildroot source code along with the source code of other packages
  2283. when releasing a product that contains GPL-licensed software.
  2284. This is because the
  2285. <a class="ulink" href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" target="_top">GNU GPL</a>
  2286. defines the "<span class="emphasis"><em>complete source code</em></span>" for an executable work as "<span class="emphasis"><em>all the
  2287. source code for all modules it contains, plus any associated interface
  2288. definition files, plus the scripts used to control compilation and installation
  2289. of the executable</em></span>".
  2290. Buildroot is part of the <span class="emphasis"><em>scripts used to control compilation and
  2291. installation of the executable</em></span>, and as such it is considered part of the
  2292. material that must be redistributed.</p><p>Keep in mind that this is only the Buildroot developers' opinion, and you
  2293. should consult your legal department or lawyer in case of any doubt.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_patches_to_packages"></a>13.2.1. Patches to packages</h3></div></div></div><p>Buildroot also bundles patch files, which are applied to the sources
  2294. of the various packages. Those patches are not covered by the license
  2295. of Buildroot. Instead, they are covered by the license of the software
  2296. to which the patches are applied. When said software is available
  2297. under multiple licenses, the Buildroot patches are only provided under
  2298. the publicly accessible licenses.</p><p>See <a class="xref" href="#patch-policy" title="Chapter 19. Patching a package">Chapter 19, <em>Patching a package</em></a> for the technical details.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_beyond_buildroot"></a>Chapter 14. Beyond Buildroot</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_boot_the_generated_images"></a>14.1. Boot the generated images</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_nfs_boot"></a>14.1.1. NFS boot</h3></div></div></div><p>To achieve NFS-boot, enable <span class="emphasis"><em>tar root filesystem</em></span> in the <span class="emphasis"><em>Filesystem
  2299. images</em></span> menu.</p><p>After a complete build, just run the following commands to setup the
  2300. NFS-root directory:</p><pre class="screen">sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir</pre><p>Remember to add this path to <code class="literal">/etc/exports</code>.</p><p>Then, you can execute a NFS-boot from your target.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_live_cd"></a>14.1.2. Live CD</h3></div></div></div><p>To build a live CD image, enable the <span class="emphasis"><em>iso image</em></span> option in the
  2301. <span class="emphasis"><em>Filesystem images</em></span> menu. Note that this option is only available on
  2302. the x86 and x86-64 architectures, and if you are building your kernel
  2303. with Buildroot.</p><p>You can build a live CD image with either IsoLinux, Grub or Grub 2 as
  2304. a bootloader, but only Isolinux supports making this image usable both
  2305. as a live CD and live USB (through the <span class="emphasis"><em>Build hybrid image</em></span> option).</p><p>You can test your live CD image using QEMU:</p><pre class="screen">qemu-system-i386 -cdrom output/images/rootfs.iso9660</pre><p>Or use it as a hard-drive image if it is a hybrid ISO:</p><pre class="screen">qemu-system-i386 -hda output/images/rootfs.iso9660</pre><p>It can be easily flashed to a USB drive with <code class="literal">dd</code>:</p><pre class="screen">dd if=output/images/rootfs.iso9660 of=/dev/sdb</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_chroot"></a>14.2. Chroot</h2></div></div></div><p>If you want to chroot in a generated image, then there are few thing
  2306. you should be aware of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2307. you should setup the new root from the <span class="emphasis"><em>tar root filesystem</em></span> image;
  2308. </li><li class="listitem">
  2309. either the selected target architecture is compatible with your host
  2310. machine, or you should use some <code class="literal">qemu-*</code> binary and correctly set it
  2311. within the <code class="literal">binfmt</code> properties to be able to run the binaries built
  2312. for the target on your host machine;
  2313. </li><li class="listitem">
  2314. Buildroot does not currently provide <code class="literal">host-qemu</code> and <code class="literal">binfmt</code>
  2315. correctly built and set for that kind of use.
  2316. </li></ul></div></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="_developer_guide"></a>Part III. Developer guide</h1></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_how_buildroot_works"></a>Chapter 15. How Buildroot works</h2></div></div></div><p>As mentioned above, Buildroot is basically a set of Makefiles that
  2317. download, configure, and compile software with the correct options. It
  2318. also includes patches for various software packages - mainly the ones
  2319. involved in the cross-compilation toolchain (<code class="literal">gcc</code>, <code class="literal">binutils</code> and
  2320. <code class="literal">uClibc</code>).</p><p>There is basically one Makefile per software package, and they are
  2321. named with the <code class="literal">.mk</code> extension. Makefiles are split into many different
  2322. parts.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2323. The <code class="literal">toolchain/</code> directory contains the Makefiles
  2324. and associated files for all software related to the
  2325. cross-compilation toolchain: <code class="literal">binutils</code>, <code class="literal">gcc</code>, <code class="literal">gdb</code>,
  2326. <code class="literal">kernel-headers</code> and <code class="literal">uClibc</code>.
  2327. </li><li class="listitem">
  2328. The <code class="literal">arch/</code> directory contains the definitions for all the processor
  2329. architectures that are supported by Buildroot.
  2330. </li><li class="listitem">
  2331. The <code class="literal">package/</code> directory contains the Makefiles and
  2332. associated files for all user-space tools and libraries that Buildroot
  2333. can compile and add to the target root filesystem. There is one
  2334. sub-directory per package.
  2335. </li><li class="listitem">
  2336. The <code class="literal">linux/</code> directory contains the Makefiles and associated files for
  2337. the Linux kernel.
  2338. </li><li class="listitem">
  2339. The <code class="literal">boot/</code> directory contains the Makefiles and associated files for
  2340. the bootloaders supported by Buildroot.
  2341. </li><li class="listitem">
  2342. The <code class="literal">system/</code> directory contains support for system integration, e.g.
  2343. the target filesystem skeleton and the selection of an init system.
  2344. </li><li class="listitem">
  2345. The <code class="literal">fs/</code> directory contains the Makefiles and
  2346. associated files for software related to the generation of the
  2347. target root filesystem image.
  2348. </li></ul></div><p>Each directory contains at least 2 files:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2349. <code class="literal">something.mk</code> is the Makefile that downloads, configures,
  2350. compiles and installs the package <code class="literal">something</code>.
  2351. </li><li class="listitem">
  2352. <code class="literal">Config.in</code> is a part of the configuration tool
  2353. description file. It describes the options related to the
  2354. package.
  2355. </li></ul></div><p>The main Makefile performs the following steps (once the
  2356. configuration is done):</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2357. Create all the output directories: <code class="literal">staging</code>, <code class="literal">target</code>, <code class="literal">build</code>,
  2358. etc. in the output directory (<code class="literal">output/</code> by default,
  2359. another value can be specified using <code class="literal">O=</code>)
  2360. </li><li class="listitem">
  2361. Generate the toolchain target. When an internal toolchain is used, this
  2362. means generating the cross-compilation toolchain. When an external
  2363. toolchain is used, this means checking the features of the external
  2364. toolchain and importing it into the Buildroot environment.
  2365. </li><li class="listitem">
  2366. Generate all the targets listed in the <code class="literal">TARGETS</code> variable. This
  2367. variable is filled by all the individual components'
  2368. Makefiles. Generating these targets will trigger the compilation of
  2369. the userspace packages (libraries, programs), the kernel, the
  2370. bootloader and the generation of the root filesystem images,
  2371. depending on the configuration.
  2372. </li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_coding_style"></a>Chapter 16. Coding style</h2></div></div></div><p>Overall, these coding style rules are here to help you to add new files in
  2373. Buildroot or refactor existing ones.</p><p>If you slightly modify some existing file, the important thing is
  2374. to keep the consistency of the whole file, so you can:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2375. either follow the potentially deprecated coding style used in this
  2376. file,
  2377. </li><li class="listitem">
  2378. or entirely rework it in order to make it comply with these rules.
  2379. </li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="writing-rules-config-in"></a>16.1. <code class="literal">Config.in</code> file</h2></div></div></div><p><code class="literal">Config.in</code> files contain entries for almost anything configurable in
  2380. Buildroot.</p><p>An entry has the following pattern:</p><pre class="screen">config BR2_PACKAGE_LIBFOO
  2381. bool "libfoo"
  2382. depends on BR2_PACKAGE_LIBBAZ
  2383. select BR2_PACKAGE_LIBBAR
  2384. help
  2385. This is a comment that explains what libfoo is. The help text
  2386. should be wrapped.
  2387. http://foosoftware.org/libfoo/</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2388. The <code class="literal">bool</code>, <code class="literal">depends on</code>, <code class="literal">select</code> and <code class="literal">help</code> lines are indented
  2389. with one tab.
  2390. </li><li class="listitem">
  2391. The help text itself should be indented with one tab and two
  2392. spaces.
  2393. </li><li class="listitem">
  2394. The help text should be wrapped to fit 72 columns, where tab counts
  2395. for 8, so 62 characters in the text itself.
  2396. </li></ul></div><p>The <code class="literal">Config.in</code> files are the input for the configuration tool
  2397. used in Buildroot, which is the regular <span class="emphasis"><em>Kconfig</em></span>. For further
  2398. details about the <span class="emphasis"><em>Kconfig</em></span> language, refer to
  2399. <a class="ulink" href="http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt" target="_top">http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="writing-rules-mk"></a>16.2. The <code class="literal">.mk</code> file</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  2400. Header: The file starts with a header. It contains the module name,
  2401. preferably in lowercase, enclosed between separators made of 80 hashes. A
  2402. blank line is mandatory after the header:
  2403. </p><pre class="screen">################################################################################
  2404. #
  2405. # libfoo
  2406. #
  2407. ################################################################################</pre></li><li class="listitem"><p class="simpara">
  2408. Assignment: use <code class="literal">=</code> preceded and followed by one space:
  2409. </p><pre class="screen">LIBFOO_VERSION = 1.0
  2410. LIBFOO_CONF_OPTS += --without-python-support</pre><p class="simpara">Do not align the <code class="literal">=</code> signs.</p></li><li class="listitem"><p class="simpara">
  2411. Indentation: use tab only:
  2412. </p><pre class="screen">define LIBFOO_REMOVE_DOC
  2413. $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
  2414. $(TARGET_DIR)/usr/share/man/man3/libfoo*
  2415. endef</pre><p class="simpara">Note that commands inside a <code class="literal">define</code> block should always start with a tab,
  2416. so <span class="emphasis"><em>make</em></span> recognizes them as commands.</p></li><li class="listitem"><p class="simpara">
  2417. Optional dependency:
  2418. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p class="simpara">
  2419. Prefer multi-line syntax.
  2420. </p><p class="simpara">YES:</p><pre class="screen">ifeq ($(BR2_PACKAGE_PYTHON),y)
  2421. LIBFOO_CONF_OPTS += --with-python-support
  2422. LIBFOO_DEPENDENCIES += python
  2423. else
  2424. LIBFOO_CONF_OPTS += --without-python-support
  2425. endif</pre><p class="simpara">NO:</p><pre class="screen">LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
  2426. LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)</pre></li><li class="listitem">
  2427. Keep configure options and dependencies close together.
  2428. </li></ul></div></li><li class="listitem"><p class="simpara">
  2429. Optional hooks: keep hook definition and assignment together in one
  2430. if block.
  2431. </p><p class="simpara">YES:</p><pre class="screen">ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
  2432. define LIBFOO_REMOVE_DATA
  2433. $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
  2434. endef
  2435. LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
  2436. endif</pre><p class="simpara">NO:</p><pre class="screen">define LIBFOO_REMOVE_DATA
  2437. $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
  2438. endef
  2439. ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
  2440. LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
  2441. endif</pre></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_the_documentation"></a>16.3. The documentation</h2></div></div></div><p>The documentation uses the
  2442. <a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top">asciidoc</a> format.</p><p>For further details about the asciidoc syntax, refer to
  2443. <a class="ulink" href="http://www.methods.co.nz/asciidoc/userguide.html" target="_top">http://www.methods.co.nz/asciidoc/userguide.html</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_support_scripts"></a>16.4. Support scripts</h2></div></div></div><p>Some scripts in the <code class="literal">support/</code> and <code class="literal">utils/</code> directories are written in
  2444. Python and should follow the
  2445. <a class="ulink" href="https://www.python.org/dev/peps/pep-0008/" target="_top">PEP8 Style Guide for Python Code</a>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="adding-board-support"></a>Chapter 17. Adding support for a particular board</h2></div></div></div><p>Buildroot contains basic configurations for several publicly available
  2446. hardware boards, so that users of such a board can easily build a system
  2447. that is known to work. You are welcome to add support for other boards
  2448. to Buildroot too.</p><p>To do so, you need to create a normal Buildroot configuration that
  2449. builds a basic system for the hardware: (internal) toolchain, kernel,
  2450. bootloader, filesystem and a simple BusyBox-only userspace. No specific
  2451. package should be selected: the configuration should be as minimal as
  2452. possible, and should only build a working basic BusyBox system for the
  2453. target platform. You can of course use more complicated configurations
  2454. for your internal projects, but the Buildroot project will only
  2455. integrate basic board configurations. This is because package
  2456. selections are highly application-specific.</p><p>Once you have a known working configuration, run <code class="literal">make
  2457. savedefconfig</code>. This will generate a minimal <code class="literal">defconfig</code> file at the
  2458. root of the Buildroot source tree. Move this file into the <code class="literal">configs/</code>
  2459. directory, and rename it <code class="literal">&lt;boardname&gt;_defconfig</code>. If the configuration
  2460. is a bit more complicated, it is nice to manually reformat it and
  2461. separate it into sections, with a comment before each section. Typical
  2462. sections are <span class="emphasis"><em>Architecture</em></span>, <span class="emphasis"><em>Toolchain options</em></span> (typically just linux
  2463. headers version), <span class="emphasis"><em>Firmware</em></span>, <span class="emphasis"><em>Bootloader</em></span>, <span class="emphasis"><em>Kernel</em></span>, and <span class="emphasis"><em>Filesystem</em></span>.</p><p>Always use fixed versions or commit hashes for the different
  2464. components, not the "latest" version. For example, set
  2465. <code class="literal">BR2_LINUX_KERNEL_CUSTOM_VERSION=y</code> and
  2466. <code class="literal">BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE</code> to the kernel version you tested
  2467. with.</p><p>It is recommended to use as much as possible upstream versions of the
  2468. Linux kernel and bootloaders, and to use as much as possible default
  2469. kernel and bootloader configurations. If they are incorrect for your
  2470. board, or no default exists, we encourage you to send fixes to the
  2471. corresponding upstream projects.</p><p>However, in the mean time, you may want to store kernel or bootloader
  2472. configuration or patches specific to your target platform. To do so,
  2473. create a directory <code class="literal">board/&lt;manufacturer&gt;</code> and a subdirectory
  2474. <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;</code>. You can then store your patches
  2475. and configurations in these directories, and reference them from the main
  2476. Buildroot configuration. Refer to <a class="xref" href="#customize" title="Chapter 9. Project-specific customization">Chapter 9, <em>Project-specific customization</em></a> for more details.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="adding-packages"></a>Chapter 18. Adding new packages to Buildroot</h2></div></div></div><p>This section covers how new packages (userspace libraries or
  2477. applications) can be integrated into Buildroot. It also shows how
  2478. existing packages are integrated, which is needed for fixing issues or
  2479. tuning their configuration.</p><p>When you add a new package, be sure to test it in various conditions
  2480. (see <a class="xref" href="#testing-package" title="18.24.3. How to test your package">Section 18.24.3, “How to test your package”</a>) and also check it for coding style (see
  2481. <a class="xref" href="#check-package" title="18.24.2. How to check the coding style">Section 18.24.2, “How to check the coding style”</a>).</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_package_directory"></a>18.1. Package directory</h2></div></div></div><p>First of all, create a directory under the <code class="literal">package</code> directory for
  2482. your software, for example <code class="literal">libfoo</code>.</p><p>Some packages have been grouped by topic in a sub-directory:
  2483. <code class="literal">x11r7</code>, <code class="literal">qt5</code> and <code class="literal">gstreamer</code>. If your package fits in
  2484. one of these categories, then create your package directory in these.
  2485. New subdirectories are discouraged, however.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_config_files"></a>18.2. Config files</h2></div></div></div><p>For the package to be displayed in the configuration tool, you need to
  2486. create a Config file in your package directory. There are two types:
  2487. <code class="literal">Config.in</code> and <code class="literal">Config.in.host</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_literal_config_in_literal_file"></a>18.2.1. <code class="literal">Config.in</code> file</h3></div></div></div><p>For packages used on the target, create a file named <code class="literal">Config.in</code>. This
  2488. file will contain the option descriptions related to our <code class="literal">libfoo</code> software
  2489. that will be used and displayed in the configuration tool. It should basically
  2490. contain:</p><pre class="screen">config BR2_PACKAGE_LIBFOO
  2491. bool "libfoo"
  2492. help
  2493. This is a comment that explains what libfoo is. The help text
  2494. should be wrapped.
  2495. http://foosoftware.org/libfoo/</pre><p>The <code class="literal">bool</code> line, <code class="literal">help</code> line and other metadata information about the
  2496. configuration option must be indented with one tab. The help text
  2497. itself should be indented with one tab and two spaces, lines should
  2498. be wrapped to fit 72 columns, where tab counts for 8, so 62 characters
  2499. in the text itself. The help text must mention the upstream URL of the
  2500. project after an empty line.</p><p>As a convention specific to Buildroot, the ordering of the attributes
  2501. is as follows:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
  2502. The type of option: <code class="literal">bool</code>, <code class="literal">string</code>… with the prompt
  2503. </li><li class="listitem">
  2504. If needed, the <code class="literal">default</code> value(s)
  2505. </li><li class="listitem">
  2506. Any dependencies on the target in <code class="literal">depends on</code> form
  2507. </li><li class="listitem">
  2508. Any dependencies on the toolchain in <code class="literal">depends on</code> form
  2509. </li><li class="listitem">
  2510. Any dependencies on other packages in <code class="literal">depends on</code> form
  2511. </li><li class="listitem">
  2512. Any dependency of the <code class="literal">select</code> form
  2513. </li><li class="listitem">
  2514. The help keyword and help text.
  2515. </li></ol></div><p>You can add other sub-options into a <code class="literal">if BR2_PACKAGE_LIBFOO…endif</code>
  2516. statement to configure particular things in your software. You can look at
  2517. examples in other packages. The syntax of the <code class="literal">Config.in</code> file is the same
  2518. as the one for the kernel Kconfig file. The documentation for this syntax is
  2519. available at <a class="ulink" href="http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt" target="_top">http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt</a></p><p>Finally you have to add your new <code class="literal">libfoo/Config.in</code> to
  2520. <code class="literal">package/Config.in</code> (or in a category subdirectory if you decided to
  2521. put your package in one of the existing categories). The files
  2522. included there are <span class="emphasis"><em>sorted alphabetically</em></span> per category and are <span class="emphasis"><em>NOT</em></span>
  2523. supposed to contain anything but the <span class="emphasis"><em>bare</em></span> name of the package.</p><pre class="screen">source "package/libfoo/Config.in"</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_literal_config_in_host_literal_file"></a>18.2.2. <code class="literal">Config.in.host</code> file</h3></div></div></div><p>Some packages also need to be built for the host system. There are two
  2524. options here:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2525. The host package is only required to satisfy build-time
  2526. dependencies of one or more target packages. In this case, add
  2527. <code class="literal">host-foo</code> to the target package’s <code class="literal">BAR_DEPENDENCIES</code> variable. No
  2528. <code class="literal">Config.in.host</code> file should be created.
  2529. </li><li class="listitem"><p class="simpara">
  2530. The host package should be explicitly selectable by the user from
  2531. the configuration menu. In this case, create a <code class="literal">Config.in.host</code> file
  2532. for that host package:
  2533. </p><pre class="screen">config BR2_PACKAGE_HOST_FOO
  2534. bool "host foo"
  2535. help
  2536. This is a comment that explains what foo for the host is.
  2537. http://foosoftware.org/foo/</pre><p class="simpara">The same coding style and options as for the <code class="literal">Config.in</code> file are valid.</p><p class="simpara">Finally you have to add your new <code class="literal">libfoo/Config.in.host</code> to
  2538. <code class="literal">package/Config.in.host</code>. The files included there are <span class="emphasis"><em>sorted alphabetically</em></span>
  2539. and are <span class="emphasis"><em>NOT</em></span> supposed to contain anything but the <span class="emphasis"><em>bare</em></span> name of the package.</p><pre class="screen">source "package/foo/Config.in.host"</pre><p class="simpara">The host package will then be available from the <code class="literal">Host utilities</code> menu.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="depends-on-vs-select"></a>18.2.3. Choosing <code class="literal">depends on</code> or <code class="literal">select</code></h3></div></div></div><p>The <code class="literal">Config.in</code> file of your package must also ensure that
  2540. dependencies are enabled. Typically, Buildroot uses the following
  2541. rules:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2542. Use a <code class="literal">select</code> type of dependency for dependencies on
  2543. libraries. These dependencies are generally not obvious and it
  2544. therefore make sense to have the kconfig system ensure that the
  2545. dependencies are selected. For example, the <span class="emphasis"><em>libgtk2</em></span> package uses
  2546. <code class="literal">select BR2_PACKAGE_LIBGLIB2</code> to make sure this library is also
  2547. enabled.
  2548. The <code class="literal">select</code> keyword expresses the dependency with a backward
  2549. semantic.
  2550. </li><li class="listitem">
  2551. Use a <code class="literal">depends on</code> type of dependency when the user really needs to
  2552. be aware of the dependency. Typically, Buildroot uses this type of
  2553. dependency for dependencies on target architecture, MMU support and
  2554. toolchain options (see <a class="xref" href="#dependencies-target-toolchain-options" title="18.2.4. Dependencies on target and toolchain options">Section 18.2.4, “Dependencies on target and toolchain options”</a>),
  2555. or for dependencies on "big" things, such as the X.org system.
  2556. The <code class="literal">depends on</code> keyword expresses the dependency with a forward
  2557. semantic.
  2558. </li></ul></div><p><strong>Note. </strong>The current problem with the <span class="emphasis"><em>kconfig</em></span> language is that these two
  2559. dependency semantics are not internally linked. Therefore, it may be
  2560. possible to select a package, whom one of its dependencies/requirement
  2561. is not met.</p><p>An example illustrates both the usage of <code class="literal">select</code> and <code class="literal">depends on</code>.</p><pre class="screen">config BR2_PACKAGE_RRDTOOL
  2562. bool "rrdtool"
  2563. depends on BR2_USE_WCHAR
  2564. select BR2_PACKAGE_FREETYPE
  2565. select BR2_PACKAGE_LIBART
  2566. select BR2_PACKAGE_LIBPNG
  2567. select BR2_PACKAGE_ZLIB
  2568. help
  2569. RRDtool is the OpenSource industry standard, high performance
  2570. data logging and graphing system for time series data.
  2571. http://oss.oetiker.ch/rrdtool/
  2572. comment "rrdtool needs a toolchain w/ wchar"
  2573. depends on !BR2_USE_WCHAR</pre><p>Note that these two dependency types are only transitive with the
  2574. dependencies of the same kind.</p><p>This means, in the following example:</p><pre class="screen">config BR2_PACKAGE_A
  2575. bool "Package A"
  2576. config BR2_PACKAGE_B
  2577. bool "Package B"
  2578. depends on BR2_PACKAGE_A
  2579. config BR2_PACKAGE_C
  2580. bool "Package C"
  2581. depends on BR2_PACKAGE_B
  2582. config BR2_PACKAGE_D
  2583. bool "Package D"
  2584. select BR2_PACKAGE_B
  2585. config BR2_PACKAGE_E
  2586. bool "Package E"
  2587. select BR2_PACKAGE_D</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2588. Selecting <code class="literal">Package C</code> will be visible if <code class="literal">Package B</code> has been
  2589. selected, which in turn is only visible if <code class="literal">Package A</code> has been
  2590. selected.
  2591. </li><li class="listitem">
  2592. Selecting <code class="literal">Package E</code> will select <code class="literal">Package D</code>, which will select
  2593. <code class="literal">Package B</code>, it will not check for the dependencies of <code class="literal">Package B</code>,
  2594. so it will not select <code class="literal">Package A</code>.
  2595. </li><li class="listitem">
  2596. Since <code class="literal">Package B</code> is selected but <code class="literal">Package A</code> is not, this violates
  2597. the dependency of <code class="literal">Package B</code> on <code class="literal">Package A</code>. Therefore, in such a
  2598. situation, the transitive dependency has to be added explicitly:
  2599. </li></ul></div><pre class="screen">config BR2_PACKAGE_D
  2600. bool "Package D"
  2601. select BR2_PACKAGE_B
  2602. depends on BR2_PACKAGE_A
  2603. config BR2_PACKAGE_E
  2604. bool "Package E"
  2605. select BR2_PACKAGE_D
  2606. depends on BR2_PACKAGE_A</pre><p>Overall, for package library dependencies, <code class="literal">select</code> should be
  2607. preferred.</p><p>Note that such dependencies will ensure that the dependency option
  2608. is also enabled, but not necessarily built before your package. To do
  2609. so, the dependency also needs to be expressed in the <code class="literal">.mk</code> file of the
  2610. package.</p><p>Further formatting details: see <a class="link" href="#writing-rules-config-in" title="16.1. Config.in file">the
  2611. coding style</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="dependencies-target-toolchain-options"></a>18.2.4. Dependencies on target and toolchain options</h3></div></div></div><p>Many packages depend on certain options of the toolchain: the choice of
  2612. C library, C++ support, thread support, RPC support, wchar support,
  2613. or dynamic library support. Some packages can only be built on certain
  2614. target architectures, or if an MMU is available in the processor.</p><p>These dependencies have to be expressed with the appropriate <span class="emphasis"><em>depends
  2615. on</em></span> statements in the Config.in file. Additionally, for dependencies on
  2616. toolchain options, a <code class="literal">comment</code> should be displayed when the option is
  2617. not enabled, so that the user knows why the package is not available.
  2618. Dependencies on target architecture or MMU support should not be
  2619. made visible in a comment: since it is unlikely that the user can
  2620. freely choose another target, it makes little sense to show these
  2621. dependencies explicitly.</p><p>The <code class="literal">comment</code> should only be visible if the <code class="literal">config</code> option itself would
  2622. be visible when the toolchain option dependencies are met. This means
  2623. that all other dependencies of the package (including dependencies on
  2624. target architecture and MMU support) have to be repeated on the
  2625. <code class="literal">comment</code> definition. To keep it clear, the <code class="literal">depends on</code> statement for
  2626. these non-toolchain option should be kept separate from the <code class="literal">depends on</code>
  2627. statement for the toolchain options.
  2628. If there is a dependency on a config option in that same file (typically
  2629. the main package) it is preferable to have a global <code class="literal">if … endif</code>
  2630. construct rather than repeating the <code class="literal">depends on</code> statement on the
  2631. comment and other config options.</p><p>The general format of a dependency <code class="literal">comment</code> for package foo is:</p><pre class="screen">foo needs a toolchain w/ featA, featB, featC</pre><p>for example:</p><pre class="screen">mpd needs a toolchain w/ C++, threads, wchar</pre><p>or</p><pre class="screen">crda needs a toolchain w/ threads</pre><p>Note that this text is kept brief on purpose, so that it will fit on a
  2632. 80-character terminal.</p><p>The rest of this section enumerates the different target and toolchain
  2633. options, the corresponding config symbols to depend on, and the text to
  2634. use in the comment.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  2635. Target architecture
  2636. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2637. Dependency symbol: <code class="literal">BR2_powerpc</code>, <code class="literal">BR2_mips</code>, … (see <code class="literal">arch/Config.in</code>)
  2638. </li><li class="listitem">
  2639. Comment string: no comment to be added
  2640. </li></ul></div></li><li class="listitem"><p class="simpara">
  2641. MMU support
  2642. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2643. Dependency symbol: <code class="literal">BR2_USE_MMU</code>
  2644. </li><li class="listitem">
  2645. Comment string: no comment to be added
  2646. </li></ul></div></li><li class="listitem"><p class="simpara">
  2647. Gcc <code class="literal"><span class="emphasis"><em>_sync</em></span>*</code> built-ins used for atomic operations. They are
  2648. available in variants operating on 1 byte, 2 bytes, 4 bytes and 8
  2649. bytes. Since different architectures support atomic operations on
  2650. different sizes, one dependency symbol is available for each size:
  2651. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2652. Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_1</code> for 1 byte,
  2653. <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_2</code> for 2 bytes,
  2654. <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_4</code> for 4 bytes, <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_8</code>
  2655. for 8 bytes.
  2656. </li><li class="listitem">
  2657. Comment string: no comment to be added
  2658. </li></ul></div></li><li class="listitem"><p class="simpara">
  2659. Gcc <code class="literal"><span class="emphasis"><em>_atomic</em></span>*</code> built-ins used for atomic operations.
  2660. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2661. Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_ATOMIC</code>.
  2662. </li><li class="listitem">
  2663. Comment string: no comment to be added
  2664. </li></ul></div></li><li class="listitem"><p class="simpara">
  2665. Kernel headers
  2666. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2667. Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y</code>, (replace
  2668. <code class="literal">X_Y</code> with the proper version, see <code class="literal">toolchain/Config.in</code>)
  2669. </li><li class="listitem">
  2670. Comment string: <code class="literal">headers &gt;= X.Y</code> and/or <code class="literal">headers &lt;= X.Y</code> (replace
  2671. <code class="literal">X.Y</code> with the proper version)
  2672. </li></ul></div></li><li class="listitem"><p class="simpara">
  2673. GCC version
  2674. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2675. Dependency symbol: <code class="literal">BR2_TOOLCHAIN_GCC_AT_LEAST_X_Y</code>, (replace
  2676. <code class="literal">X_Y</code> with the proper version, see <code class="literal">toolchain/Config.in</code>)
  2677. </li><li class="listitem">
  2678. Comment string: <code class="literal">gcc &gt;= X.Y</code> and/or <code class="literal">gcc &lt;= X.Y</code> (replace
  2679. <code class="literal">X.Y</code> with the proper version)
  2680. </li></ul></div></li><li class="listitem"><p class="simpara">
  2681. Host GCC version
  2682. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2683. Dependency symbol: <code class="literal">BR2_HOST_GCC_AT_LEAST_X_Y</code>, (replace
  2684. <code class="literal">X_Y</code> with the proper version, see <code class="literal">Config.in</code>)
  2685. </li><li class="listitem">
  2686. Comment string: no comment to be added
  2687. </li><li class="listitem">
  2688. Note that it is usually not the package itself that has a minimum
  2689. host GCC version, but rather a host-package on which it depends.
  2690. </li></ul></div></li><li class="listitem"><p class="simpara">
  2691. C library
  2692. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2693. Dependency symbol: <code class="literal">BR2_TOOLCHAIN_USES_GLIBC</code>,
  2694. <code class="literal">BR2_TOOLCHAIN_USES_MUSL</code>, <code class="literal">BR2_TOOLCHAIN_USES_UCLIBC</code>
  2695. </li><li class="listitem">
  2696. Comment string: for the C library, a slightly different comment text
  2697. is used: <code class="literal">foo needs a glibc toolchain</code>, or <code class="literal">foo needs a glibc
  2698. toolchain w/ C++</code>
  2699. </li></ul></div></li><li class="listitem"><p class="simpara">
  2700. C++ support
  2701. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2702. Dependency symbol: <code class="literal">BR2_INSTALL_LIBSTDCPP</code>
  2703. </li><li class="listitem">
  2704. Comment string: <code class="literal">C++</code>
  2705. </li></ul></div></li><li class="listitem"><p class="simpara">
  2706. D support
  2707. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2708. Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_DLANG</code>
  2709. </li><li class="listitem">
  2710. Comment string: <code class="literal">Dlang</code>
  2711. </li></ul></div></li><li class="listitem"><p class="simpara">
  2712. Fortran support
  2713. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2714. Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_FORTRAN</code>
  2715. </li><li class="listitem">
  2716. Comment string: <code class="literal">fortran</code>
  2717. </li></ul></div></li><li class="listitem"><p class="simpara">
  2718. thread support
  2719. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2720. Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_THREADS</code>
  2721. </li><li class="listitem">
  2722. Comment string: <code class="literal">threads</code> (unless <code class="literal">BR2_TOOLCHAIN_HAS_THREADS_NPTL</code>
  2723. is also needed, in which case, specifying only <code class="literal">NPTL</code> is sufficient)
  2724. </li></ul></div></li><li class="listitem"><p class="simpara">
  2725. NPTL thread support
  2726. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2727. Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_THREADS_NPTL</code>
  2728. </li><li class="listitem">
  2729. Comment string: <code class="literal">NPTL</code>
  2730. </li></ul></div></li><li class="listitem"><p class="simpara">
  2731. RPC support
  2732. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2733. Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_NATIVE_RPC</code>
  2734. </li><li class="listitem">
  2735. Comment string: <code class="literal">RPC</code>
  2736. </li></ul></div></li><li class="listitem"><p class="simpara">
  2737. wchar support
  2738. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2739. Dependency symbol: <code class="literal">BR2_USE_WCHAR</code>
  2740. </li><li class="listitem">
  2741. Comment string: <code class="literal">wchar</code>
  2742. </li></ul></div></li><li class="listitem"><p class="simpara">
  2743. dynamic library
  2744. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2745. Dependency symbol: <code class="literal">!BR2_STATIC_LIBS</code>
  2746. </li><li class="listitem">
  2747. Comment string: <code class="literal">dynamic library</code>
  2748. </li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_dependencies_on_a_linux_kernel_built_by_buildroot"></a>18.2.5. Dependencies on a Linux kernel built by buildroot</h3></div></div></div><p>Some packages need a Linux kernel to be built by buildroot. These are
  2749. typically kernel modules or firmware. A comment should be added in the
  2750. Config.in file to express this dependency, similar to dependencies on
  2751. toolchain options. The general format is:</p><pre class="screen">foo needs a Linux kernel to be built</pre><p>If there is a dependency on both toolchain options and the Linux
  2752. kernel, use this format:</p><pre class="screen">foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_dependencies_on_udev_dev_management"></a>18.2.6. Dependencies on udev /dev management</h3></div></div></div><p>If a package needs udev /dev management, it should depend on symbol
  2753. <code class="literal">BR2_PACKAGE_HAS_UDEV</code>, and the following comment should be added:</p><pre class="screen">foo needs udev /dev management</pre><p>If there is a dependency on both toolchain options and udev /dev
  2754. management, use this format:</p><pre class="screen">foo needs udev /dev management and a toolchain w/ featA, featB, featC</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_dependencies_on_features_provided_by_virtual_packages"></a>18.2.7. Dependencies on features provided by virtual packages</h3></div></div></div><p>Some features can be provided by more than one package, such as the
  2755. openGL libraries.</p><p>See <a class="xref" href="#virtual-package-tutorial">Section 18.11, “Infrastructure for virtual packages”</a> for more on the virtual packages.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_the_literal_mk_literal_file"></a>18.3. The <code class="literal">.mk</code> file</h2></div></div></div><p><a id="adding-packages-mk"></a>Finally, here’s the hardest part. Create a file named <code class="literal">libfoo.mk</code>. It
  2756. describes how the package should be downloaded, configured, built,
  2757. installed, etc.</p><p>Depending on the package type, the <code class="literal">.mk</code> file must be written in a
  2758. different way, using different infrastructures:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  2759. <span class="strong"><strong>Makefiles for generic packages</strong></span> (not using autotools or CMake):
  2760. These are based on an infrastructure similar to the one used for
  2761. autotools-based packages, but require a little more work from the
  2762. developer. They specify what should be done for the configuration,
  2763. compilation and installation of the package. This
  2764. infrastructure must be used for all packages that do not use the
  2765. autotools as their build system. In the future, other specialized
  2766. infrastructures might be written for other build systems. We cover
  2767. them through in a <a class="link" href="#generic-package-tutorial" title="18.5.1. generic-package tutorial">tutorial</a> and a
  2768. <a class="link" href="#generic-package-reference" title="18.5.2. generic-package reference">reference</a>.
  2769. </li><li class="listitem">
  2770. <span class="strong"><strong>Makefiles for autotools-based software</strong></span> (autoconf, automake, etc.):
  2771. We provide a dedicated infrastructure for such packages, since
  2772. autotools is a very common build system. This infrastructure <span class="emphasis"><em>must</em></span>
  2773. be used for new packages that rely on the autotools as their build
  2774. system. We cover them through a <a class="link" href="#autotools-package-tutorial" title="18.6.1. autotools-package tutorial">tutorial</a>
  2775. and <a class="link" href="#autotools-package-reference" title="18.6.2. autotools-package reference">reference</a>.
  2776. </li><li class="listitem">
  2777. <span class="strong"><strong>Makefiles for cmake-based software</strong></span>: We provide a dedicated
  2778. infrastructure for such packages, as CMake is a more and more
  2779. commonly used build system and has a standardized behaviour. This
  2780. infrastructure <span class="emphasis"><em>must</em></span> be used for new packages that rely on
  2781. CMake. We cover them through a <a class="link" href="#cmake-package-tutorial" title="18.7.1. cmake-package tutorial">tutorial</a>
  2782. and <a class="link" href="#cmake-package-reference" title="18.7.2. cmake-package reference">reference</a>.
  2783. </li><li class="listitem">
  2784. <span class="strong"><strong>Makefiles for Python modules</strong></span>: We have a dedicated infrastructure
  2785. for Python modules that use either the <code class="literal">distutils</code> or the
  2786. <code class="literal">setuptools</code> mechanism. We cover them through a
  2787. <a class="link" href="#python-package-tutorial" title="18.8.1. python-package tutorial">tutorial</a> and a
  2788. <a class="link" href="#python-package-reference" title="18.8.2. python-package reference">reference</a>.
  2789. </li><li class="listitem">
  2790. <span class="strong"><strong>Makefiles for Lua modules</strong></span>: We have a dedicated infrastructure for
  2791. Lua modules available through the LuaRocks web site. We cover them
  2792. through a <a class="link" href="#luarocks-package-tutorial" title="18.9.1. luarocks-package tutorial">tutorial</a> and a
  2793. <a class="link" href="#luarocks-package-reference" title="18.9.2. luarocks-package reference">reference</a>.
  2794. </li></ul></div><p>Further formatting details: see <a class="link" href="#writing-rules-mk" title="16.2. The .mk file">the writing
  2795. rules</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="adding-packages-hash"></a>18.4. The <code class="literal">.hash</code> file</h2></div></div></div><p>When possible, you must add a third file, named <code class="literal">libfoo.hash</code>, that
  2796. contains the hashes of the downloaded files for the <code class="literal">libfoo</code>
  2797. package. The only reason for not adding a <code class="literal">.hash</code> file is when hash
  2798. checking is not possible due to how the package is downloaded.</p><p>When a package has a version selection choice, then the hash file may be
  2799. stored in a subdirectory named after the version, e.g.
  2800. <code class="literal">package/libfoo/1.2.3/libfoo.hash</code>. This is especially important if the
  2801. different versions have different licensing terms, but they are stored
  2802. in the same file. Otherwise, the hash file should stay in the package’s
  2803. directory.</p><p>The hashes stored in that file are used to validate the integrity of the
  2804. downloaded files and of the license files.</p><p>The format of this file is one line for each file for which to check the
  2805. hash, each line with the following three fields separated by two spaces:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  2806. the type of hash, one of:
  2807. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2808. <code class="literal">md5</code>, <code class="literal">sha1</code>, <code class="literal">sha224</code>, <code class="literal">sha256</code>, <code class="literal">sha384</code>, <code class="literal">sha512</code>, <code class="literal">none</code>
  2809. </li></ul></div></li><li class="listitem"><p class="simpara">
  2810. the hash of the file:
  2811. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2812. for <code class="literal">none</code>, one or more non-space chars, usually just the string <code class="literal">xxx</code>
  2813. </li><li class="listitem">
  2814. for <code class="literal">md5</code>, 32 hexadecimal characters
  2815. </li><li class="listitem">
  2816. for <code class="literal">sha1</code>, 40 hexadecimal characters
  2817. </li><li class="listitem">
  2818. for <code class="literal">sha224</code>, 56 hexadecimal characters
  2819. </li><li class="listitem">
  2820. for <code class="literal">sha256</code>, 64 hexadecimal characters
  2821. </li><li class="listitem">
  2822. for <code class="literal">sha384</code>, 96 hexadecimal characters
  2823. </li><li class="listitem">
  2824. for <code class="literal">sha512</code>, 128 hexadecimal characters
  2825. </li></ul></div></li><li class="listitem"><p class="simpara">
  2826. the name of the file:
  2827. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2828. for a source archive: the basename of the file, without any directory
  2829. component,
  2830. </li><li class="listitem">
  2831. for a license file: the path as it appears in <code class="literal">FOO_LICENSE_FILES</code>.
  2832. </li></ul></div></li></ul></div><p>Lines starting with a <code class="literal">#</code> sign are considered comments, and ignored. Empty
  2833. lines are ignored.</p><p>There can be more than one hash for a single file, each on its own line. In
  2834. this case, all hashes must match.</p><p><strong>Note. </strong>Ideally, the hashes stored in this file should match the hashes published by
  2835. upstream, e.g. on their website, in the e-mail announcement… If upstream
  2836. provides more than one type of hash (e.g. <code class="literal">sha1</code> and <code class="literal">sha512</code>), then it is
  2837. best to add all those hashes in the <code class="literal">.hash</code> file. If upstream does not
  2838. provide any hash, or only provides an <code class="literal">md5</code> hash, then compute at least one
  2839. strong hash yourself (preferably <code class="literal">sha256</code>, but not <code class="literal">md5</code>), and mention
  2840. this in a comment line above the hashes.</p><p><strong>Note. </strong>The hashes for license files are used to detect a license change when a
  2841. package version is bumped. The hashes are checked during the make legal-info
  2842. target run. For a package with multiple versions (like Qt5),
  2843. create the hash file in a subdirectory <code class="literal">&lt;packageversion&gt;</code> of that package
  2844. (see also <a class="xref" href="#patch-apply-order" title="19.2. How patches are applied">Section 19.2, “How patches are applied”</a>).</p><p>The <code class="literal">none</code> hash type is reserved to those archives downloaded from a
  2845. repository, like a <span class="emphasis"><em>git clone</em></span>, a <span class="emphasis"><em>subversion checkout</em></span>…</p><p>The example below defines a <code class="literal">sha1</code> and a <code class="literal">sha256</code> published by upstream for
  2846. the main <code class="literal">libfoo-1.2.3.tar.bz2</code> tarball, an <code class="literal">md5</code> from upstream and a
  2847. locally-computed <code class="literal">sha256</code> hashes for a binary blob, a <code class="literal">sha256</code> for a
  2848. downloaded patch, and an archive with no hash:</p><pre class="screen"># Hashes from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.{sha1,sha256}:
  2849. sha1 486fb55c3efa71148fe07895fd713ea3a5ae343a libfoo-1.2.3.tar.bz2
  2850. sha256 efc8103cc3bcb06bda6a781532d12701eb081ad83e8f90004b39ab81b65d4369 libfoo-1.2.3.tar.bz2
  2851. # md5 from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.md5, sha256 locally computed:
  2852. md5 2d608f3c318c6b7557d551a5a09314f03452f1a1 libfoo-data.bin
  2853. sha256 01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b libfoo-data.bin
  2854. # Locally computed:
  2855. sha256 ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9 libfoo-fix-blabla.patch
  2856. # No hash for 1234:
  2857. none xxx libfoo-1234.tar.gz
  2858. # Hash for license files:
  2859. sha256 a45a845012742796534f7e91fe623262ccfb99460a2bd04015bd28d66fba95b8 COPYING
  2860. sha256 01b1f9f2c8ee648a7a596a1abe8aa4ed7899b1c9e5551bda06da6e422b04aa55 doc/COPYING.LGPL</pre><p>If the <code class="literal">.hash</code> file is present, and it contains one or more hashes for a
  2861. downloaded file, the hash(es) computed by Buildroot (after download) must
  2862. match the hash(es) stored in the <code class="literal">.hash</code> file. If one or more hashes do
  2863. not match, Buildroot considers this an error, deletes the downloaded file,
  2864. and aborts.</p><p>If the <code class="literal">.hash</code> file is present, but it does not contain a hash for a
  2865. downloaded file, Buildroot considers this an error and aborts. However,
  2866. the downloaded file is left in the download directory since this
  2867. typically indicates that the <code class="literal">.hash</code> file is wrong but the downloaded
  2868. file is probably OK.</p><p>Hashes are currently checked for files fetched from http/ftp servers,
  2869. Git repositories, files copied using scp and local files. Hashes are
  2870. not checked for other version control systems (such as Subversion,
  2871. CVS, etc.) because Buildroot currently does not generate reproducible
  2872. tarballs when source code is fetched from such version control
  2873. systems.</p><p>Hashes should only be added in <code class="literal">.hash</code> files for files that are
  2874. guaranteed to be stable. For example, patches auto-generated by Github
  2875. are not guaranteed to be stable, and therefore their hashes can change
  2876. over time. Such patches should not be downloaded, and instead be added
  2877. locally to the package folder.</p><p>If the <code class="literal">.hash</code> file is missing, then no check is done at all.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_packages_with_specific_build_systems"></a>18.5. Infrastructure for packages with specific build systems</h2></div></div></div><p>By <span class="emphasis"><em>packages with specific build systems</em></span> we mean all the packages
  2878. whose build system is not one of the standard ones, such as
  2879. <span class="emphasis"><em>autotools</em></span> or <span class="emphasis"><em>CMake</em></span>. This typically includes packages whose build
  2880. system is based on hand-written Makefiles or shell scripts.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="generic-package-tutorial"></a>18.5.1. <code class="literal">generic-package</code> tutorial</h3></div></div></div><pre class="screen">01: ################################################################################
  2881. 02: #
  2882. 03: # libfoo
  2883. 04: #
  2884. 05: ################################################################################
  2885. 06:
  2886. 07: LIBFOO_VERSION = 1.0
  2887. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  2888. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  2889. 10: LIBFOO_LICENSE = GPL-3.0+
  2890. 11: LIBFOO_LICENSE_FILES = COPYING
  2891. 12: LIBFOO_INSTALL_STAGING = YES
  2892. 13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
  2893. 14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
  2894. 15:
  2895. 16: define LIBFOO_BUILD_CMDS
  2896. 17: $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
  2897. 18: endef
  2898. 19:
  2899. 20: define LIBFOO_INSTALL_STAGING_CMDS
  2900. 21: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
  2901. 22: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
  2902. 23: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
  2903. 24: endef
  2904. 25:
  2905. 26: define LIBFOO_INSTALL_TARGET_CMDS
  2906. 27: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
  2907. 28: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
  2908. 29: endef
  2909. 30:
  2910. 31: define LIBFOO_USERS
  2911. 32: foo -1 libfoo -1 * - - - LibFoo daemon
  2912. 33: endef
  2913. 34:
  2914. 35: define LIBFOO_DEVICES
  2915. 36: /dev/foo c 666 0 0 42 0 - - -
  2916. 37: endef
  2917. 38:
  2918. 39: define LIBFOO_PERMISSIONS
  2919. 40: /bin/foo f 4755 foo libfoo - - - - -
  2920. 41: endef
  2921. 42:
  2922. 43: $(eval $(generic-package))</pre><p>The Makefile begins on line 7 to 11 with metadata information: the
  2923. version of the package (<code class="literal">LIBFOO_VERSION</code>), the name of the
  2924. tarball containing the package (<code class="literal">LIBFOO_SOURCE</code>) (xz-ed tarball recommended)
  2925. the Internet location at which the tarball can be downloaded from
  2926. (<code class="literal">LIBFOO_SITE</code>), the license (<code class="literal">LIBFOO_LICENSE</code>) and file with the
  2927. license text (<code class="literal">LIBFOO_LICENSE_FILES</code>). All variables must start with
  2928. the same prefix, <code class="literal">LIBFOO_</code> in this case. This prefix is always the
  2929. uppercased version of the package name (see below to understand where
  2930. the package name is defined).</p><p>On line 12, we specify that this package wants to install something to
  2931. the staging space. This is often needed for libraries, since they must
  2932. install header files and other development files in the staging space.
  2933. This will ensure that the commands listed in the
  2934. <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code> variable will be executed.</p><p>On line 13, we specify that there is some fixing to be done to some
  2935. of the <span class="emphasis"><em>libfoo-config</em></span> files that were installed during
  2936. <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code> phase.
  2937. These *-config files are executable shell script files that are
  2938. located in <span class="emphasis"><em>$(STAGING_DIR)/usr/bin</em></span> directory and are executed
  2939. by other 3rd party packages to find out the location and the linking
  2940. flags of this particular package.</p><p>The problem is that all these *-config files by default give wrong,
  2941. host system linking flags that are unsuitable for cross-compiling.</p><p>For example: <span class="emphasis"><em>-I/usr/include</em></span> instead of <span class="emphasis"><em>-I$(STAGING_DIR)/usr/include</em></span>
  2942. or: <span class="emphasis"><em>-L/usr/lib</em></span> instead of <span class="emphasis"><em>-L$(STAGING_DIR)/usr/lib</em></span></p><p>So some sed magic is done to these scripts to make them give correct
  2943. flags.
  2944. The argument to be given to <code class="literal">LIBFOO_CONFIG_SCRIPTS</code> is the file name(s)
  2945. of the shell script(s) needing fixing. All these names are relative to
  2946. <span class="emphasis"><em>$(STAGING_DIR)/usr/bin</em></span> and if needed multiple names can be given.</p><p>In addition, the scripts listed in <code class="literal">LIBFOO_CONFIG_SCRIPTS</code> are removed
  2947. from <code class="literal">$(TARGET_DIR)/usr/bin</code>, since they are not needed on the target.</p><div class="example"><a id="idm3193"></a><p class="title"><strong>Example 18.1. Config script: <span class="emphasis"><em>divine</em></span> package</strong></p><div class="example-contents"><p>Package divine installs shell script <span class="emphasis"><em>$(STAGING_DIR)/usr/bin/divine-config</em></span>.</p><p>So its fixup would be:</p><pre class="screen">DIVINE_CONFIG_SCRIPTS = divine-config</pre></div></div><br class="example-break" /><div class="example"><a id="idm3200"></a><p class="title"><strong>Example 18.2. Config script: <span class="emphasis"><em>imagemagick</em></span> package:</strong></p><div class="example-contents"><p>Package imagemagick installs the following scripts:
  2948. <span class="emphasis"><em>$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config</em></span></p><p>So it’s fixup would be:</p><pre class="screen">IMAGEMAGICK_CONFIG_SCRIPTS = \
  2949. Magick-config Magick++-config \
  2950. MagickCore-config MagickWand-config Wand-config</pre></div></div><br class="example-break" /><p>On line 14, we specify the list of dependencies this package relies
  2951. on. These dependencies are listed in terms of lower-case package names,
  2952. which can be packages for the target (without the <code class="literal">host-</code>
  2953. prefix) or packages for the host (with the <code class="literal">host-</code>) prefix).
  2954. Buildroot will ensure that all these packages are built and installed
  2955. <span class="emphasis"><em>before</em></span> the current package starts its configuration.</p><p>The rest of the Makefile, lines 16..29, defines what should be done
  2956. at the different steps of the package configuration, compilation and
  2957. installation.
  2958. <code class="literal">LIBFOO_BUILD_CMDS</code> tells what steps should be performed to
  2959. build the package. <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code> tells what
  2960. steps should be performed to install the package in the staging space.
  2961. <code class="literal">LIBFOO_INSTALL_TARGET_CMDS</code> tells what steps should be
  2962. performed to install the package in the target space.</p><p>All these steps rely on the <code class="literal">$(@D)</code> variable, which
  2963. contains the directory where the source code of the package has been
  2964. extracted.</p><p>On lines 31..33, we define a user that is used by this package (e.g.
  2965. to run a daemon as non-root) (<code class="literal">LIBFOO_USERS</code>).</p><p>On line 35..37, we define a device-node file used by this package
  2966. (<code class="literal">LIBFOO_DEVICES</code>).</p><p>On line 39..41, we define the permissions to set to specific files
  2967. installed by this package (<code class="literal">LIBFOO_PERMISSIONS</code>).</p><p>Finally, on line 43, we call the <code class="literal">generic-package</code> function, which
  2968. generates, according to the variables defined previously, all the
  2969. Makefile code necessary to make your package working.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="generic-package-reference"></a>18.5.2. <code class="literal">generic-package</code> reference</h3></div></div></div><p>There are two variants of the generic target. The <code class="literal">generic-package</code> macro is
  2970. used for packages to be cross-compiled for the target. The
  2971. <code class="literal">host-generic-package</code> macro is used for host packages, natively compiled
  2972. for the host. It is possible to call both of them in a single <code class="literal">.mk</code>
  2973. file: once to create the rules to generate a target
  2974. package and once to create the rules to generate a host package:</p><pre class="screen">$(eval $(generic-package))
  2975. $(eval $(host-generic-package))</pre><p>This might be useful if the compilation of the target package requires
  2976. some tools to be installed on the host. If the package name is
  2977. <code class="literal">libfoo</code>, then the name of the package for the target is also
  2978. <code class="literal">libfoo</code>, while the name of the package for the host is
  2979. <code class="literal">host-libfoo</code>. These names should be used in the DEPENDENCIES
  2980. variables of other packages, if they depend on <code class="literal">libfoo</code> or
  2981. <code class="literal">host-libfoo</code>.</p><p>The call to the <code class="literal">generic-package</code> and/or <code class="literal">host-generic-package</code> macro
  2982. <span class="strong"><strong>must</strong></span> be at the end of the <code class="literal">.mk</code> file, after all variable definitions.
  2983. The call to <code class="literal">host-generic-package</code> <span class="strong"><strong>must</strong></span> be after the call to
  2984. <code class="literal">generic-package</code>, if any.</p><p>For the target package, the <code class="literal">generic-package</code> uses the variables defined by
  2985. the .mk file and prefixed by the uppercased package name:
  2986. <code class="literal">LIBFOO_*</code>. <code class="literal">host-generic-package</code> uses the <code class="literal">HOST_LIBFOO_*</code> variables. For
  2987. <span class="emphasis"><em>some</em></span> variables, if the <code class="literal">HOST_LIBFOO_</code> prefixed variable doesn’t
  2988. exist, the package infrastructure uses the corresponding variable
  2989. prefixed by <code class="literal">LIBFOO_</code>. This is done for variables that are likely to
  2990. have the same value for both the target and host packages. See below
  2991. for details.</p><p>The list of variables that can be set in a <code class="literal">.mk</code> file to give metadata
  2992. information is (assuming the package name is <code class="literal">libfoo</code>) :</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  2993. <code class="literal">LIBFOO_VERSION</code>, mandatory, must contain the version of the
  2994. package. Note that if <code class="literal">HOST_LIBFOO_VERSION</code> doesn’t exist, it is
  2995. assumed to be the same as <code class="literal">LIBFOO_VERSION</code>. It can also be a
  2996. revision number or a tag for packages that are fetched directly
  2997. from their version control system. Examples:
  2998. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  2999. a version for a release tarball: <code class="literal">LIBFOO_VERSION = 0.1.2</code>
  3000. </li><li class="listitem">
  3001. a sha1 for a git tree: <code class="literal">LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057</code>
  3002. </li><li class="listitem"><p class="simpara">
  3003. a tag for a git tree <code class="literal">LIBFOO_VERSION = v0.1.2</code>
  3004. </p><p><strong>Note: </strong>Using a branch name as <code class="literal">FOO_VERSION</code> is not supported, because it does
  3005. not and can not work as people would expect it should:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
  3006. due to local caching, Buildroot will not re-fetch the repository,
  3007. so people who expect to be able to follow the remote repository
  3008. would be quite surprised and disappointed;
  3009. </li><li class="listitem">
  3010. because two builds can never be perfectly simultaneous, and because
  3011. the remote repository may get new commits on the branch anytime,
  3012. two users, using the same Buildroot tree and building the same
  3013. configuration, may get different source, thus rendering the build
  3014. non reproducible, and people would be quite surprised and
  3015. disappointed.
  3016. </li></ol></div></li></ul></div></li><li class="listitem">
  3017. <code class="literal">LIBFOO_SOURCE</code> may contain the name of the tarball of the package,
  3018. which Buildroot will use to download the tarball from
  3019. <code class="literal">LIBFOO_SITE</code>. If <code class="literal">HOST_LIBFOO_SOURCE</code> is not specified, it defaults
  3020. to <code class="literal">LIBFOO_SOURCE</code>. If none are specified, then the value is assumed
  3021. to be <code class="literal">libfoo-$(LIBFOO_VERSION).tar.gz</code>.
  3022. Example: <code class="literal">LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2</code>
  3023. </li><li class="listitem">
  3024. <code class="literal">LIBFOO_PATCH</code> may contain a space-separated list of patch file
  3025. names, that Buildroot will download and apply to the package source
  3026. code. If an entry contains <code class="literal">://</code>, then Buildroot will assume it is a
  3027. full URL and download the patch from this location. Otherwise,
  3028. Buildroot will assume that the patch should be downloaded from
  3029. <code class="literal">LIBFOO_SITE</code>. If <code class="literal">HOST_LIBFOO_PATCH</code> is not specified, it defaults
  3030. to <code class="literal">LIBFOO_PATCH</code>. Note that patches that are included in Buildroot
  3031. itself use a different mechanism: all files of the form
  3032. <code class="literal">*.patch</code> present in the package directory inside
  3033. Buildroot will be applied to the package after extraction (see
  3034. <a class="link" href="#patch-policy" title="Chapter 19. Patching a package">patching a package</a>). Finally, patches listed in
  3035. the <code class="literal">LIBFOO_PATCH</code> variable are applied <span class="emphasis"><em>before</em></span> the patches stored
  3036. in the Buildroot package directory.
  3037. </li><li class="listitem">
  3038. <code class="literal">LIBFOO_SITE</code> provides the location of the package, which can be a
  3039. URL or a local filesystem path. HTTP, FTP and SCP are supported URL
  3040. types for retrieving package tarballs. In these cases don’t include a
  3041. trailing slash: it will be added by Buildroot between the directory
  3042. and the filename as appropriate. Git, Subversion, Mercurial,
  3043. and Bazaar are supported URL types for retrieving packages directly
  3044. from source code management systems. There is a helper function to make
  3045. it easier to download source tarballs from GitHub (refer to
  3046. <a class="xref" href="#github-download-url" title="18.24.4. How to add a package from GitHub">Section 18.24.4, “How to add a package from GitHub”</a> for details). A filesystem path may be used
  3047. to specify either a tarball or a directory containing the package
  3048. source code. See <code class="literal">LIBFOO_SITE_METHOD</code> below for more details on how
  3049. retrieval works.
  3050. Note that SCP URLs should be of the form
  3051. <code class="literal">scp://[user@]host:filepath</code>, and that filepath is relative to the
  3052. user’s home directory, so you may want to prepend the path with a
  3053. slash for absolute paths:
  3054. <code class="literal">scp://[user@]host:/absolutepath</code>.
  3055. If <code class="literal">HOST_LIBFOO_SITE</code> is not specified, it defaults to
  3056. <code class="literal">LIBFOO_SITE</code>.
  3057. Examples:
  3058. <code class="literal">LIBFOO_SITE=http://www.libfoosoftware.org/libfoo</code>
  3059. <code class="literal">LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor</code>
  3060. <code class="literal">LIBFOO_SITE=/opt/software/libfoo.tar.gz</code>
  3061. <code class="literal">LIBFOO_SITE=$(TOPDIR)/../src/libfoo</code>
  3062. </li><li class="listitem">
  3063. <code class="literal">LIBFOO_DL_OPTS</code> is a space-separated list of additional options to
  3064. pass to the downloader. Useful for retrieving documents with
  3065. server-side checking for user logins and passwords, or to use a proxy.
  3066. All download methods valid for <code class="literal">LIBFOO_SITE_METHOD</code> are supported;
  3067. valid options depend on the download method (consult the man page
  3068. for the respective download utilities).
  3069. </li><li class="listitem">
  3070. <code class="literal">LIBFOO_EXTRA_DOWNLOADS</code> is a space-separated list of additional
  3071. files that Buildroot should download. If an entry contains <code class="literal">://</code>
  3072. then Buildroot will assume it is a complete URL and will download
  3073. the file using this URL. Otherwise, Buildroot will assume the file
  3074. to be downloaded is located at <code class="literal">LIBFOO_SITE</code>. Buildroot will not do
  3075. anything with those additional files, except download them: it will
  3076. be up to the package recipe to use them from <code class="literal">$(LIBFOO_DL_DIR)</code>.
  3077. </li><li class="listitem"><p class="simpara">
  3078. <code class="literal">LIBFOO_SITE_METHOD</code> determines the method used to fetch or copy the
  3079. package source code. In many cases, Buildroot guesses the method
  3080. from the contents of <code class="literal">LIBFOO_SITE</code> and setting <code class="literal">LIBFOO_SITE_METHOD</code>
  3081. is unnecessary. When <code class="literal">HOST_LIBFOO_SITE_METHOD</code> is not specified, it
  3082. defaults to the value of <code class="literal">LIBFOO_SITE_METHOD</code>.
  3083. The possible values of <code class="literal">LIBFOO_SITE_METHOD</code> are:
  3084. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  3085. <code class="literal">wget</code> for normal FTP/HTTP downloads of tarballs. Used by
  3086. default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">http://</code>, <code class="literal">https://</code> or
  3087. <code class="literal">ftp://</code>.
  3088. </li><li class="listitem">
  3089. <code class="literal">scp</code> for downloads of tarballs over SSH with scp. Used by
  3090. default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">scp://</code>.
  3091. </li><li class="listitem">
  3092. <code class="literal">svn</code> for retrieving source code from a Subversion repository.
  3093. Used by default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">svn://</code>. When a
  3094. <code class="literal">http://</code> Subversion repository URL is specified in
  3095. <code class="literal">LIBFOO_SITE</code>, one <span class="emphasis"><em>must</em></span> specify <code class="literal">LIBFOO_SITE_METHOD=svn</code>.
  3096. Buildroot performs a checkout which is preserved as a tarball in
  3097. the download cache; subsequent builds use the tarball instead of
  3098. performing another checkout.
  3099. </li><li class="listitem">
  3100. <code class="literal">cvs</code> for retrieving source code from a CVS repository.
  3101. Used by default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">cvs://</code>.
  3102. The downloaded source code is cached as with the <code class="literal">svn</code> method.
  3103. Anonymous pserver mode is assumed otherwise explicitly defined
  3104. on <code class="literal">LIBFOO_SITE</code>. Both
  3105. <code class="literal">LIBFOO_SITE=cvs://libfoo.net:/cvsroot/libfoo</code> and
  3106. <code class="literal">LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo</code>
  3107. are accepted, on the former anonymous pserver access mode is
  3108. assumed.
  3109. <code class="literal">LIBFOO_SITE</code> <span class="emphasis"><em>must</em></span> contain the source URL as well as the remote
  3110. repository directory. The module is the package name.
  3111. <code class="literal">LIBFOO_VERSION</code> is <span class="emphasis"><em>mandatory</em></span> and <span class="emphasis"><em>must</em></span> be a tag, a branch, or
  3112. a date (e.g. "2014-10-20", "2014-10-20 13:45", "2014-10-20
  3113. 13:45+01" see "man cvs" for further details).
  3114. </li><li class="listitem">
  3115. <code class="literal">git</code> for retrieving source code from a Git repository. Used by
  3116. default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">git://</code>. The downloaded
  3117. source code is cached as with the <code class="literal">svn</code>
  3118. method.
  3119. </li><li class="listitem">
  3120. <code class="literal">hg</code> for retrieving source code from a Mercurial repository. One
  3121. <span class="emphasis"><em>must</em></span> specify <code class="literal">LIBFOO_SITE_METHOD=hg</code> when <code class="literal">LIBFOO_SITE</code>
  3122. contains a Mercurial repository URL. The downloaded source code
  3123. is cached as with the <code class="literal">svn</code> method.
  3124. </li><li class="listitem">
  3125. <code class="literal">bzr</code> for retrieving source code from a Bazaar repository. Used
  3126. by default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">bzr://</code>. The
  3127. downloaded source code is cached as with the <code class="literal">svn</code> method.
  3128. </li><li class="listitem">
  3129. <code class="literal">file</code> for a local tarball. One should use this when
  3130. <code class="literal">LIBFOO_SITE</code> specifies a package tarball as a local filename.
  3131. Useful for software that isn’t available publicly or in version
  3132. control.
  3133. </li><li class="listitem">
  3134. <code class="literal">local</code> for a local source code directory. One should use this
  3135. when <code class="literal">LIBFOO_SITE</code> specifies a local directory path containing
  3136. the package source code. Buildroot copies the contents of the
  3137. source directory into the package’s build directory. Note that
  3138. for <code class="literal">local</code> packages, no patches are applied. If you need to
  3139. still patch the source code, use <code class="literal">LIBFOO_POST_RSYNC_HOOKS</code>, see
  3140. <a class="xref" href="#hooks-rsync" title="18.22.1. Using the POST_RSYNC hook">Section 18.22.1, “Using the <code class="literal">POST_RSYNC</code> hook”</a>.
  3141. </li></ul></div></li><li class="listitem">
  3142. <code class="literal">LIBFOO_GIT_SUBMODULES</code> can be set to <code class="literal">YES</code> to create an archive
  3143. with the git submodules in the repository. This is only available
  3144. for packages downloaded with git (i.e. when
  3145. <code class="literal">LIBFOO_SITE_METHOD=git</code>). Note that we try not to use such git
  3146. submodules when they contain bundled libraries, in which case we
  3147. prefer to use those libraries from their own package.
  3148. </li><li class="listitem">
  3149. <code class="literal">LIBFOO_STRIP_COMPONENTS</code> is the number of leading components
  3150. (directories) that tar must strip from file names on extraction.
  3151. The tarball for most packages has one leading component named
  3152. "&lt;pkg-name&gt;-&lt;pkg-version&gt;", thus Buildroot passes
  3153. --strip-components=1 to tar to remove it.
  3154. For non-standard packages that don’t have this component, or
  3155. that have more than one leading component to strip, set this
  3156. variable with the value to be passed to tar. Default: 1.
  3157. </li><li class="listitem">
  3158. <code class="literal">LIBFOO_EXCLUDES</code> is a space-separated list of patterns to exclude
  3159. when extracting the archive. Each item from that list is passed as
  3160. a tar’s <code class="literal">--exclude</code> option. By default, empty.
  3161. </li><li class="listitem">
  3162. <code class="literal">LIBFOO_DEPENDENCIES</code> lists the dependencies (in terms of package
  3163. name) that are required for the current target package to
  3164. compile. These dependencies are guaranteed to be compiled and
  3165. installed before the configuration of the current package starts.
  3166. However, modifications to configuration of these dependencies will
  3167. not force a rebuild of the current package. In a similar way,
  3168. <code class="literal">HOST_LIBFOO_DEPENDENCIES</code> lists the dependencies for the current
  3169. host package.
  3170. </li><li class="listitem">
  3171. <code class="literal">LIBFOO_EXTRACT_DEPENDENCIES</code> lists the dependencies (in terms of
  3172. package name) that are required for the current target package to be
  3173. extracted. These dependencies are guaranteed to be compiled and
  3174. installed before the extract step of the current package
  3175. starts. This is only used internally by the package infrastructure,
  3176. and should typically not be used directly by packages.
  3177. </li><li class="listitem">
  3178. <code class="literal">LIBFOO_PATCH_DEPENDENCIES</code> lists the dependencies (in terms of
  3179. package name) that are required for the current package to be
  3180. patched. These dependencies are guaranteed to be extracted and
  3181. patched (but not necessarily built) before the current package is
  3182. patched. In a similar way, <code class="literal">HOST_LIBFOO_PATCH_DEPENDENCIES</code> lists
  3183. the dependencies for the current host package.
  3184. This is seldom used; usually, <code class="literal">LIBFOO_DEPENDENCIES</code> is what you
  3185. really want to use.
  3186. </li><li class="listitem">
  3187. <code class="literal">LIBFOO_PROVIDES</code> lists all the virtual packages <code class="literal">libfoo</code> is an
  3188. implementation of. See <a class="xref" href="#virtual-package-tutorial">Section 18.11, “Infrastructure for virtual packages”</a>.
  3189. </li><li class="listitem">
  3190. <code class="literal">LIBFOO_INSTALL_STAGING</code> can be set to <code class="literal">YES</code> or <code class="literal">NO</code> (default). If
  3191. set to <code class="literal">YES</code>, then the commands in the <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code>
  3192. variables are executed to install the package into the staging
  3193. directory.
  3194. </li><li class="listitem">
  3195. <code class="literal">LIBFOO_INSTALL_TARGET</code> can be set to <code class="literal">YES</code> (default) or <code class="literal">NO</code>. If
  3196. set to <code class="literal">YES</code>, then the commands in the <code class="literal">LIBFOO_INSTALL_TARGET_CMDS</code>
  3197. variables are executed to install the package into the target
  3198. directory.
  3199. </li><li class="listitem">
  3200. <code class="literal">LIBFOO_INSTALL_IMAGES</code> can be set to <code class="literal">YES</code> or <code class="literal">NO</code> (default). If
  3201. set to <code class="literal">YES</code>, then the commands in the <code class="literal">LIBFOO_INSTALL_IMAGES_CMDS</code>
  3202. variable are executed to install the package into the images
  3203. directory.
  3204. </li><li class="listitem">
  3205. <code class="literal">LIBFOO_CONFIG_SCRIPTS</code> lists the names of the files in
  3206. <span class="emphasis"><em>$(STAGING_DIR)/usr/bin</em></span> that need some special fixing to make them
  3207. cross-compiling friendly. Multiple file names separated by space can
  3208. be given and all are relative to <span class="emphasis"><em>$(STAGING_DIR)/usr/bin</em></span>. The files
  3209. listed in <code class="literal">LIBFOO_CONFIG_SCRIPTS</code> are also removed from
  3210. <code class="literal">$(TARGET_DIR)/usr/bin</code> since they are not needed on the target.
  3211. </li><li class="listitem">
  3212. <code class="literal">LIBFOO_DEVICES</code> lists the device files to be created by Buildroot
  3213. when using the static device table. The syntax to use is the
  3214. makedevs one. You can find some documentation for this syntax in the
  3215. <a class="xref" href="#makedev-syntax" title="Chapter 25. Makedev syntax documentation">Chapter 25, <em>Makedev syntax documentation</em></a>. This variable is optional.
  3216. </li><li class="listitem">
  3217. <code class="literal">LIBFOO_PERMISSIONS</code> lists the changes of permissions to be done at
  3218. the end of the build process. The syntax is once again the makedevs one.
  3219. You can find some documentation for this syntax in the <a class="xref" href="#makedev-syntax" title="Chapter 25. Makedev syntax documentation">Chapter 25, <em>Makedev syntax documentation</em></a>.
  3220. This variable is optional.
  3221. </li><li class="listitem">
  3222. <code class="literal">LIBFOO_USERS</code> lists the users to create for this package, if it installs
  3223. a program you want to run as a specific user (e.g. as a daemon, or as a
  3224. cron-job). The syntax is similar in spirit to the makedevs one, and is
  3225. described in the <a class="xref" href="#makeuser-syntax" title="Chapter 26. Makeusers syntax documentation">Chapter 26, <em>Makeusers syntax documentation</em></a>. This variable is optional.
  3226. </li><li class="listitem"><p class="simpara">
  3227. <code class="literal">LIBFOO_LICENSE</code> defines the license (or licenses) under which the package
  3228. is released.
  3229. This name will appear in the manifest file produced by <code class="literal">make legal-info</code>.
  3230. If the license appears in <a class="ulink" href="https://spdx.org/licenses/" target="_top">the SPDX License List</a>,
  3231. use the SPDX short identifier to make the manifest file uniform.
  3232. Otherwise, describe the license in a precise and concise way, avoiding
  3233. ambiguous names such as <code class="literal">BSD</code> which actually name a family of licenses.
  3234. This variable is optional. If it is not defined, <code class="literal">unknown</code> will appear in
  3235. the <code class="literal">license</code> field of the manifest file for this package.
  3236. The expected format for this variable must comply with the following rules:
  3237. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  3238. If different parts of the package are released under different
  3239. licenses, then <code class="literal">comma</code> separate licenses (e.g. <code class="literal"><code class="literal">LIBFOO_LICENSE =
  3240. GPL-2.0+, LGPL-2.1+</code></code>). If there is clear distinction between which
  3241. component is licensed under what license, then annotate the license
  3242. with that component, between parenthesis (e.g. <code class="literal"><code class="literal">LIBFOO_LICENSE =
  3243. GPL-2.0+ (programs), LGPL-2.1+ (libraries)</code></code>).
  3244. </li><li class="listitem">
  3245. If some licenses are conditioned on a sub-option being enabled, append
  3246. the conditional licenses with a comma (e.g.: <code class="literal">FOO_LICENSE += , GPL-2.0+
  3247. (programs)</code>); the infrastructure will internally remove the space before
  3248. the comma.
  3249. </li><li class="listitem">
  3250. If the package is dual licensed, then separate licenses with the
  3251. <code class="literal">or</code> keyword (e.g. <code class="literal"><code class="literal">LIBFOO_LICENSE = AFL-2.1 or GPL-2.0+</code></code>).
  3252. </li></ul></div></li><li class="listitem">
  3253. <code class="literal">LIBFOO_LICENSE_FILES</code> is a space-separated list of files in the package
  3254. tarball that contain the license(s) under which the package is released.
  3255. <code class="literal">make legal-info</code> copies all of these files in the <code class="literal">legal-info</code> directory.
  3256. See <a class="xref" href="#legal-info" title="Chapter 13. Legal notice and licensing">Chapter 13, <em>Legal notice and licensing</em></a> for more information.
  3257. This variable is optional. If it is not defined, a warning will be produced
  3258. to let you know, and <code class="literal">not saved</code> will appear in the <code class="literal">license files</code> field
  3259. of the manifest file for this package.
  3260. </li><li class="listitem">
  3261. <code class="literal">LIBFOO_ACTUAL_SOURCE_TARBALL</code> only applies to packages whose
  3262. <code class="literal">LIBFOO_SITE</code> / <code class="literal">LIBFOO_SOURCE</code> pair points to an archive that does
  3263. not actually contain source code, but binary code. This a very
  3264. uncommon case, only known to apply to external toolchains which come
  3265. already compiled, although theoretically it might apply to other
  3266. packages. In such cases a separate tarball is usually available with
  3267. the actual source code. Set <code class="literal">LIBFOO_ACTUAL_SOURCE_TARBALL</code> to the
  3268. name of the actual source code archive and Buildroot will download
  3269. it and use it when you run <code class="literal">make legal-info</code> to collect
  3270. legally-relevant material. Note this file will not be downloaded
  3271. during regular builds nor by <code class="literal">make source</code>.
  3272. </li><li class="listitem">
  3273. <code class="literal">LIBFOO_ACTUAL_SOURCE_SITE</code> provides the location of the actual
  3274. source tarball. The default value is <code class="literal">LIBFOO_SITE</code>, so you don’t
  3275. need to set this variable if the binary and source archives are
  3276. hosted on the same directory. If <code class="literal">LIBFOO_ACTUAL_SOURCE_TARBALL</code> is
  3277. not set, it doesn’t make sense to define
  3278. <code class="literal">LIBFOO_ACTUAL_SOURCE_SITE</code>.
  3279. </li><li class="listitem">
  3280. <code class="literal">LIBFOO_REDISTRIBUTE</code> can be set to <code class="literal">YES</code> (default) or <code class="literal">NO</code> to indicate if
  3281. the package source code is allowed to be redistributed. Set it to <code class="literal">NO</code> for
  3282. non-opensource packages: Buildroot will not save the source code for this
  3283. package when collecting the <code class="literal">legal-info</code>.
  3284. </li><li class="listitem">
  3285. <code class="literal">LIBFOO_FLAT_STACKSIZE</code> defines the stack size of an application built into
  3286. the FLAT binary format. The application stack size on the NOMMU architecture
  3287. processors can’t be enlarged at run time. The default stack size for the
  3288. FLAT binary format is only 4k bytes. If the application consumes more stack,
  3289. append the required number here.
  3290. </li><li class="listitem">
  3291. <code class="literal">LIBFOO_BIN_ARCH_EXCLUDE</code> is a space-separated list of paths (relative
  3292. to the target directory) to ignore when checking that the package
  3293. installs correctly cross-compiled binaries. You seldom need to set this
  3294. variable, unless the package installs binary blobs outside the default
  3295. locations, <code class="literal">/lib/firmware</code>, <code class="literal">/usr/lib/firmware</code>, <code class="literal">/lib/modules</code>,
  3296. <code class="literal">/usr/lib/modules</code>, and <code class="literal">/usr/share</code>, which are automatically excluded.
  3297. </li><li class="listitem">
  3298. <code class="literal">LIBFOO_IGNORE_CVES</code> is a space-separated list of CVEs that tells
  3299. Buildroot CVE tracking tools which CVEs should be ignored for this
  3300. package. This is typically used when the CVE is fixed by a patch in
  3301. the package, or when the CVE for some reason does not affect the
  3302. Buildroot package. A Makefile comment must always precede the
  3303. addition of a CVE to this variable. Example:
  3304. </li></ul></div><pre class="screen"># 0001-fix-cve-2020-12345.patch
  3305. LIBFOO_IGNORE_CVES += CVE-2020-12345
  3306. # only when built with libbaz, which Buildroot doesn't support
  3307. LIBFOO_IGNORE_CVES += CVE-2020-54321</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  3308. <code class="literal">LIBFOO_CPE_ID_*</code> variables is a set of variables that allows the
  3309. package to define its <a class="ulink" href="https://nvd.nist.gov/products/cpe" target="_top">CPE
  3310. identifier</a>. The available variables are:
  3311. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  3312. <code class="literal">LIBFOO_CPE_ID_PREFIX</code>, specifies the prefix of the CPE identifier,
  3313. i.e the first three fields. When not defined, the default value is
  3314. <code class="literal">cpe:2.3:a</code>.
  3315. </li><li class="listitem">
  3316. <code class="literal">LIBFOO_CPE_ID_VENDOR</code>, specifies the vendor part of the CPE
  3317. identifier. When not defined, the default value is
  3318. <code class="literal">&lt;pkgname&gt;_project</code>.
  3319. </li><li class="listitem">
  3320. <code class="literal">LIBFOO_CPE_ID_PRODUCT</code>, specifies the product part of the CPE
  3321. identifier. When not defined, the default value is <code class="literal">&lt;pkgname&gt;</code>.
  3322. </li><li class="listitem">
  3323. <code class="literal">LIBFOO_CPE_ID_VERSION</code>, specifies the version part of the CPE
  3324. identifier. When not defined the default value is
  3325. <code class="literal">$(LIBFOO_VERSION)</code>.
  3326. </li><li class="listitem">
  3327. <code class="literal">LIBFOO_CPE_ID_UPDATE</code> specifies the <span class="emphasis"><em>update</em></span> part of the CPE
  3328. identifier. When not defined the default value is <code class="literal">*</code>.
  3329. </li></ul></div><p class="simpara">If any of those variables is defined, then the generic package
  3330. infrastructure assumes the package provides valid CPE information. In
  3331. this case, the generic package infrastructure will define
  3332. <code class="literal">LIBFOO_CPE_ID</code>.</p><p class="simpara">For a host package, if its <code class="literal">LIBFOO_CPE_ID_*</code> variables are not
  3333. defined, it inherits the value of those variables from the
  3334. corresponding target package.</p></li></ul></div><p>The recommended way to define these variables is to use the following
  3335. syntax:</p><pre class="screen">LIBFOO_VERSION = 2.32</pre><p>Now, the variables that define what should be performed at the
  3336. different steps of the build process.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3337. <code class="literal">LIBFOO_EXTRACT_CMDS</code> lists the actions to be performed to extract
  3338. the package. This is generally not needed as tarballs are
  3339. automatically handled by Buildroot. However, if the package uses a
  3340. non-standard archive format, such as a ZIP or RAR file, or has a
  3341. tarball with a non-standard organization, this variable allows to
  3342. override the package infrastructure default behavior.
  3343. </li><li class="listitem">
  3344. <code class="literal">LIBFOO_CONFIGURE_CMDS</code> lists the actions to be performed to
  3345. configure the package before its compilation.
  3346. </li><li class="listitem">
  3347. <code class="literal">LIBFOO_BUILD_CMDS</code> lists the actions to be performed to
  3348. compile the package.
  3349. </li><li class="listitem">
  3350. <code class="literal">HOST_LIBFOO_INSTALL_CMDS</code> lists the actions to be performed
  3351. to install the package, when the package is a host package. The
  3352. package must install its files to the directory given by
  3353. <code class="literal">$(HOST_DIR)</code>. All files, including development files such as
  3354. headers should be installed, since other packages might be compiled
  3355. on top of this package.
  3356. </li><li class="listitem">
  3357. <code class="literal">LIBFOO_INSTALL_TARGET_CMDS</code> lists the actions to be
  3358. performed to install the package to the target directory, when the
  3359. package is a target package. The package must install its files to
  3360. the directory given by <code class="literal">$(TARGET_DIR)</code>. Only the files required for
  3361. <span class="emphasis"><em>execution</em></span> of the package have to be
  3362. installed. Header files, static libraries and documentation will be
  3363. removed again when the target filesystem is finalized.
  3364. </li><li class="listitem">
  3365. <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code> lists the actions to be
  3366. performed to install the package to the staging directory, when the
  3367. package is a target package. The package must install its files to
  3368. the directory given by <code class="literal">$(STAGING_DIR)</code>. All development files
  3369. should be installed, since they might be needed to compile other
  3370. packages.
  3371. </li><li class="listitem">
  3372. <code class="literal">LIBFOO_INSTALL_IMAGES_CMDS</code> lists the actions to be performed to
  3373. install the package to the images directory, when the package is a
  3374. target package. The package must install its files to the directory
  3375. given by <code class="literal">$(BINARIES_DIR)</code>. Only files that are binary images (aka
  3376. images) that do not belong in the <code class="literal">TARGET_DIR</code> but are necessary
  3377. for booting the board should be placed here. For example, a package
  3378. should utilize this step if it has binaries which would be similar
  3379. to the kernel image, bootloader or root filesystem images.
  3380. </li><li class="listitem">
  3381. <code class="literal">LIBFOO_INSTALL_INIT_SYSV</code>, <code class="literal">LIBFOO_INSTALL_INIT_OPENRC</code> and
  3382. <code class="literal">LIBFOO_INSTALL_INIT_SYSTEMD</code> list the actions to install init
  3383. scripts either for the systemV-like init systems (busybox,
  3384. sysvinit, etc.), openrc or for the systemd units. These commands
  3385. will be run only when the relevant init system is installed (i.e.
  3386. if systemd is selected as the init system in the configuration,
  3387. only <code class="literal">LIBFOO_INSTALL_INIT_SYSTEMD</code> will be run). The only exception
  3388. is when openrc is chosen as init system and <code class="literal">LIBFOO_INSTALL_INIT_OPENRC</code>
  3389. has not been set, in such situation <code class="literal">LIBFOO_INSTALL_INIT_SYSV</code> will
  3390. be called, since openrc supports sysv init scripts.
  3391. When systemd is used as the init system, buildroot will automatically enable
  3392. all services using the <code class="literal">systemctl preset-all</code> command in the final phase of
  3393. image building. You can add preset files to prevent a particular unit from
  3394. being automatically enabled by buildroot.
  3395. </li><li class="listitem">
  3396. <code class="literal">LIBFOO_HELP_CMDS</code> lists the actions to print the package help, which
  3397. is included to the main <code class="literal">make help</code> output. These commands can print
  3398. anything in any format.
  3399. This is seldom used, as packages rarely have custom rules. <span class="strong"><strong>Do not use
  3400. this variable</strong></span>, unless you really know that you need to print help.
  3401. </li><li class="listitem">
  3402. <code class="literal">LIBFOO_LINUX_CONFIG_FIXUPS</code> lists the Linux kernel configuration
  3403. options that are needed to build and use this package, and without
  3404. which the package is fundamentally broken. This shall be a set of
  3405. calls to one of the kconfig tweaking option: <code class="literal">KCONFIG_ENABLE_OPT</code>,
  3406. <code class="literal">KCONFIG_DISABLE_OPT</code>, or <code class="literal">KCONFIG_SET_OPT</code>.
  3407. This is seldom used, as package usually have no strict requirements on
  3408. the kernel options.
  3409. </li></ul></div><p>The preferred way to define these variables is:</p><pre class="screen">define LIBFOO_CONFIGURE_CMDS
  3410. action 1
  3411. action 2
  3412. action 3
  3413. endef</pre><p>In the action definitions, you can use the following variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3414. <code class="literal">$(LIBFOO_PKGDIR)</code> contains the path to the directory containing the
  3415. <code class="literal">libfoo.mk</code> and <code class="literal">Config.in</code> files. This variable is useful when it is
  3416. necessary to install a file bundled in Buildroot, like a runtime
  3417. configuration file, a splashscreen image…
  3418. </li><li class="listitem">
  3419. <code class="literal">$(@D)</code>, which contains the directory in which the package source
  3420. code has been uncompressed.
  3421. </li><li class="listitem">
  3422. <code class="literal">$(LIBFOO_DL_DIR)</code> contains the path to the directory where all the downloads
  3423. made by Buildroot for <code class="literal">libfoo</code> are stored in.
  3424. </li><li class="listitem">
  3425. <code class="literal">$(TARGET_CC)</code>, <code class="literal">$(TARGET_LD)</code>, etc. to get the target
  3426. cross-compilation utilities
  3427. </li><li class="listitem">
  3428. <code class="literal">$(TARGET_CROSS)</code> to get the cross-compilation toolchain prefix
  3429. </li><li class="listitem">
  3430. Of course the <code class="literal">$(HOST_DIR)</code>, <code class="literal">$(STAGING_DIR)</code> and <code class="literal">$(TARGET_DIR)</code>
  3431. variables to install the packages properly. Those variables point to
  3432. the global <span class="emphasis"><em>host</em></span>, <span class="emphasis"><em>staging</em></span> and <span class="emphasis"><em>target</em></span> directories, unless
  3433. <span class="emphasis"><em>per-package directory</em></span> support is used, in which case they point to
  3434. the current package <span class="emphasis"><em>host</em></span>, <span class="emphasis"><em>staging</em></span> and <span class="emphasis"><em>target</em></span> directories. In
  3435. both cases, it doesn’t make any difference from the package point of
  3436. view: it should simply use <code class="literal">HOST_DIR</code>, <code class="literal">STAGING_DIR</code> and
  3437. <code class="literal">TARGET_DIR</code>. See <a class="xref" href="#top-level-parallel-build" title="8.12. Top-level parallel build">Section 8.12, “Top-level parallel build”</a> for more details
  3438. about <span class="emphasis"><em>per-package directory</em></span> support.
  3439. </li></ul></div><p>Finally, you can also use hooks. See <a class="xref" href="#hooks" title="18.22. Hooks available in the various build steps">Section 18.22, “Hooks available in the various build steps”</a> for more information.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_autotools_based_packages"></a>18.6. Infrastructure for autotools-based packages</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="autotools-package-tutorial"></a>18.6.1. <code class="literal">autotools-package</code> tutorial</h3></div></div></div><p>First, let’s see how to write a <code class="literal">.mk</code> file for an autotools-based
  3440. package, with an example :</p><pre class="screen">01: ################################################################################
  3441. 02: #
  3442. 03: # libfoo
  3443. 04: #
  3444. 05: ################################################################################
  3445. 06:
  3446. 07: LIBFOO_VERSION = 1.0
  3447. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  3448. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  3449. 10: LIBFOO_INSTALL_STAGING = YES
  3450. 11: LIBFOO_INSTALL_TARGET = NO
  3451. 12: LIBFOO_CONF_OPTS = --disable-shared
  3452. 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
  3453. 14:
  3454. 15: $(eval $(autotools-package))</pre><p>On line 7, we declare the version of the package.</p><p>On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended)
  3455. and the location of the tarball on the Web. Buildroot will automatically
  3456. download the tarball from this location.</p><p>On line 10, we tell Buildroot to install the package to the staging
  3457. directory. The staging directory, located in <code class="literal">output/staging/</code>
  3458. is the directory where all the packages are installed, including their
  3459. development files, etc. By default, packages are not installed to the
  3460. staging directory, since usually, only libraries need to be installed in
  3461. the staging directory: their development files are needed to compile
  3462. other libraries or applications depending on them. Also by default, when
  3463. staging installation is enabled, packages are installed in this location
  3464. using the <code class="literal">make install</code> command.</p><p>On line 11, we tell Buildroot to not install the package to the
  3465. target directory. This directory contains what will become the root
  3466. filesystem running on the target. For purely static libraries, it is
  3467. not necessary to install them in the target directory because they will
  3468. not be used at runtime. By default, target installation is enabled; setting
  3469. this variable to NO is almost never needed. Also by default, packages are
  3470. installed in this location using the <code class="literal">make install</code> command.</p><p>On line 12, we tell Buildroot to pass a custom configure option, that
  3471. will be passed to the <code class="literal">./configure</code> script before configuring
  3472. and building the package.</p><p>On line 13, we declare our dependencies, so that they are built
  3473. before the build process of our package starts.</p><p>Finally, on line line 15, we invoke the <code class="literal">autotools-package</code>
  3474. macro that generates all the Makefile rules that actually allows the
  3475. package to be built.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="autotools-package-reference"></a>18.6.2. <code class="literal">autotools-package</code> reference</h3></div></div></div><p>The main macro of the autotools package infrastructure is
  3476. <code class="literal">autotools-package</code>. It is similar to the <code class="literal">generic-package</code> macro. The ability to
  3477. have target and host packages is also available, with the
  3478. <code class="literal">host-autotools-package</code> macro.</p><p>Just like the generic infrastructure, the autotools infrastructure
  3479. works by defining a number of variables before calling the
  3480. <code class="literal">autotools-package</code> macro.</p><p>First, all the package metadata information variables that exist in the
  3481. generic infrastructure also exist in the autotools infrastructure:
  3482. <code class="literal">LIBFOO_VERSION</code>, <code class="literal">LIBFOO_SOURCE</code>,
  3483. <code class="literal">LIBFOO_PATCH</code>, <code class="literal">LIBFOO_SITE</code>,
  3484. <code class="literal">LIBFOO_SUBDIR</code>, <code class="literal">LIBFOO_DEPENDENCIES</code>,
  3485. <code class="literal">LIBFOO_INSTALL_STAGING</code>, <code class="literal">LIBFOO_INSTALL_TARGET</code>.</p><p>A few additional variables, specific to the autotools infrastructure,
  3486. can also be defined. Many of them are only useful in very specific
  3487. cases, typical packages will therefore only use a few of them.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3488. <code class="literal">LIBFOO_SUBDIR</code> may contain the name of a subdirectory
  3489. inside the package that contains the configure script. This is useful,
  3490. if for example, the main configure script is not at the root of the
  3491. tree extracted by the tarball. If <code class="literal">HOST_LIBFOO_SUBDIR</code> is
  3492. not specified, it defaults to <code class="literal">LIBFOO_SUBDIR</code>.
  3493. </li><li class="listitem">
  3494. <code class="literal">LIBFOO_CONF_ENV</code>, to specify additional environment
  3495. variables to pass to the configure script. By default, empty.
  3496. </li><li class="listitem">
  3497. <code class="literal">LIBFOO_CONF_OPTS</code>, to specify additional configure
  3498. options to pass to the configure script. By default, empty.
  3499. </li><li class="listitem">
  3500. <code class="literal">LIBFOO_MAKE</code>, to specify an alternate <code class="literal">make</code>
  3501. command. This is typically useful when parallel make is enabled in
  3502. the configuration (using <code class="literal">BR2_JLEVEL</code>) but that this
  3503. feature should be disabled for the given package, for one reason or
  3504. another. By default, set to <code class="literal">$(MAKE)</code>. If parallel building
  3505. is not supported by the package, then it should be set to
  3506. <code class="literal">LIBFOO_MAKE=$(MAKE1)</code>.
  3507. </li><li class="listitem">
  3508. <code class="literal">LIBFOO_MAKE_ENV</code>, to specify additional environment
  3509. variables to pass to make in the build step. These are passed before
  3510. the <code class="literal">make</code> command. By default, empty.
  3511. </li><li class="listitem">
  3512. <code class="literal">LIBFOO_MAKE_OPTS</code>, to specify additional variables to
  3513. pass to make in the build step. These are passed after the
  3514. <code class="literal">make</code> command. By default, empty.
  3515. </li><li class="listitem">
  3516. <code class="literal">LIBFOO_AUTORECONF</code>, tells whether the package should
  3517. be autoreconfigured or not (i.e. if the configure script and
  3518. Makefile.in files should be re-generated by re-running autoconf,
  3519. automake, libtool, etc.). Valid values are <code class="literal">YES</code> and
  3520. <code class="literal">NO</code>. By default, the value is <code class="literal">NO</code>
  3521. </li><li class="listitem">
  3522. <code class="literal">LIBFOO_AUTORECONF_ENV</code>, to specify additional environment
  3523. variables to pass to the <span class="emphasis"><em>autoreconf</em></span> program if
  3524. <code class="literal">LIBFOO_AUTORECONF=YES</code>. These are passed in the environment of
  3525. the <span class="emphasis"><em>autoreconf</em></span> command. By default, empty.
  3526. </li><li class="listitem">
  3527. <code class="literal">LIBFOO_AUTORECONF_OPTS</code> to specify additional options
  3528. passed to the <span class="emphasis"><em>autoreconf</em></span> program if
  3529. <code class="literal">LIBFOO_AUTORECONF=YES</code>. By default, empty.
  3530. </li><li class="listitem">
  3531. <code class="literal">LIBFOO_GETTEXTIZE</code>, tells whether the package should be
  3532. gettextized or not (i.e. if the package uses a different gettext
  3533. version than Buildroot provides, and it is needed to run
  3534. <span class="emphasis"><em>gettextize</em></span>.) Only valid when <code class="literal">LIBFOO_AUTORECONF=YES</code>. Valid
  3535. values are <code class="literal">YES</code> and <code class="literal">NO</code>. The default is <code class="literal">NO</code>.
  3536. </li><li class="listitem">
  3537. <code class="literal">LIBFOO_GETTEXTIZE_OPTS</code>, to specify additional options passed to
  3538. the <span class="emphasis"><em>gettextize</em></span> program, if <code class="literal">LIBFOO_GETTEXTIZE=YES</code>. You may
  3539. use that if, for example, the <code class="literal">.po</code> files are not located in the
  3540. standard place (i.e. in <code class="literal">po/</code> at the root of the package.) By
  3541. default, <span class="emphasis"><em>-f</em></span>.
  3542. </li><li class="listitem">
  3543. <code class="literal">LIBFOO_LIBTOOL_PATCH</code> tells whether the Buildroot
  3544. patch to fix libtool cross-compilation issues should be applied or
  3545. not. Valid values are <code class="literal">YES</code> and <code class="literal">NO</code>. By
  3546. default, the value is <code class="literal">YES</code>
  3547. </li><li class="listitem">
  3548. <code class="literal">LIBFOO_INSTALL_STAGING_OPTS</code> contains the make options
  3549. used to install the package to the staging directory. By default, the
  3550. value is <code class="literal">DESTDIR=$(STAGING_DIR) install</code>, which is
  3551. correct for most autotools packages. It is still possible to override
  3552. it.
  3553. </li><li class="listitem">
  3554. <code class="literal">LIBFOO_INSTALL_TARGET_OPTS</code> contains the make options
  3555. used to install the package to the target directory. By default, the
  3556. value is <code class="literal">DESTDIR=$(TARGET_DIR) install</code>. The default
  3557. value is correct for most autotools packages, but it is still possible
  3558. to override it if needed.
  3559. </li></ul></div><p>With the autotools infrastructure, all the steps required to build
  3560. and install the packages are already defined, and they generally work
  3561. well for most autotools-based packages. However, when required, it is
  3562. still possible to customize what is done in any particular step:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3563. By adding a post-operation hook (after extract, patch, configure,
  3564. build or install). See <a class="xref" href="#hooks" title="18.22. Hooks available in the various build steps">Section 18.22, “Hooks available in the various build steps”</a> for details.
  3565. </li><li class="listitem">
  3566. By overriding one of the steps. For example, even if the autotools
  3567. infrastructure is used, if the package <code class="literal">.mk</code> file defines its
  3568. own <code class="literal">LIBFOO_CONFIGURE_CMDS</code> variable, it will be used
  3569. instead of the default autotools one. However, using this method
  3570. should be restricted to very specific cases. Do not use it in the
  3571. general case.
  3572. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_cmake_based_packages"></a>18.7. Infrastructure for CMake-based packages</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="cmake-package-tutorial"></a>18.7.1. <code class="literal">cmake-package</code> tutorial</h3></div></div></div><p>First, let’s see how to write a <code class="literal">.mk</code> file for a CMake-based package,
  3573. with an example :</p><pre class="screen">01: ################################################################################
  3574. 02: #
  3575. 03: # libfoo
  3576. 04: #
  3577. 05: ################################################################################
  3578. 06:
  3579. 07: LIBFOO_VERSION = 1.0
  3580. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  3581. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  3582. 10: LIBFOO_INSTALL_STAGING = YES
  3583. 11: LIBFOO_INSTALL_TARGET = NO
  3584. 12: LIBFOO_CONF_OPTS = -DBUILD_DEMOS=ON
  3585. 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
  3586. 14:
  3587. 15: $(eval $(cmake-package))</pre><p>On line 7, we declare the version of the package.</p><p>On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended)
  3588. and the location of the tarball on the Web. Buildroot will automatically
  3589. download the tarball from this location.</p><p>On line 10, we tell Buildroot to install the package to the staging
  3590. directory. The staging directory, located in <code class="literal">output/staging/</code>
  3591. is the directory where all the packages are installed, including their
  3592. development files, etc. By default, packages are not installed to the
  3593. staging directory, since usually, only libraries need to be installed in
  3594. the staging directory: their development files are needed to compile
  3595. other libraries or applications depending on them. Also by default, when
  3596. staging installation is enabled, packages are installed in this location
  3597. using the <code class="literal">make install</code> command.</p><p>On line 11, we tell Buildroot to not install the package to the
  3598. target directory. This directory contains what will become the root
  3599. filesystem running on the target. For purely static libraries, it is
  3600. not necessary to install them in the target directory because they will
  3601. not be used at runtime. By default, target installation is enabled; setting
  3602. this variable to NO is almost never needed. Also by default, packages are
  3603. installed in this location using the <code class="literal">make install</code> command.</p><p>On line 12, we tell Buildroot to pass custom options to CMake when it is
  3604. configuring the package.</p><p>On line 13, we declare our dependencies, so that they are built
  3605. before the build process of our package starts.</p><p>Finally, on line line 15, we invoke the <code class="literal">cmake-package</code>
  3606. macro that generates all the Makefile rules that actually allows the
  3607. package to be built.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="cmake-package-reference"></a>18.7.2. <code class="literal">cmake-package</code> reference</h3></div></div></div><p>The main macro of the CMake package infrastructure is
  3608. <code class="literal">cmake-package</code>. It is similar to the <code class="literal">generic-package</code> macro. The ability to
  3609. have target and host packages is also available, with the
  3610. <code class="literal">host-cmake-package</code> macro.</p><p>Just like the generic infrastructure, the CMake infrastructure works
  3611. by defining a number of variables before calling the <code class="literal">cmake-package</code>
  3612. macro.</p><p>First, all the package metadata information variables that exist in
  3613. the generic infrastructure also exist in the CMake infrastructure:
  3614. <code class="literal">LIBFOO_VERSION</code>, <code class="literal">LIBFOO_SOURCE</code>, <code class="literal">LIBFOO_PATCH</code>, <code class="literal">LIBFOO_SITE</code>,
  3615. <code class="literal">LIBFOO_SUBDIR</code>, <code class="literal">LIBFOO_DEPENDENCIES</code>, <code class="literal">LIBFOO_INSTALL_STAGING</code>,
  3616. <code class="literal">LIBFOO_INSTALL_TARGET</code>.</p><p>A few additional variables, specific to the CMake infrastructure, can
  3617. also be defined. Many of them are only useful in very specific cases,
  3618. typical packages will therefore only use a few of them.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3619. <code class="literal">LIBFOO_SUBDIR</code> may contain the name of a subdirectory inside the
  3620. package that contains the main CMakeLists.txt file. This is useful,
  3621. if for example, the main CMakeLists.txt file is not at the root of
  3622. the tree extracted by the tarball. If <code class="literal">HOST_LIBFOO_SUBDIR</code> is not
  3623. specified, it defaults to <code class="literal">LIBFOO_SUBDIR</code>.
  3624. </li><li class="listitem">
  3625. <code class="literal">LIBFOO_CONF_ENV</code>, to specify additional environment variables to
  3626. pass to CMake. By default, empty.
  3627. </li><li class="listitem"><p class="simpara">
  3628. <code class="literal">LIBFOO_CONF_OPTS</code>, to specify additional configure options to pass
  3629. to CMake. By default, empty. A number of common CMake options are
  3630. set by the <code class="literal">cmake-package</code> infrastructure; so it is normally not
  3631. necessary to set them in the package’s <code class="literal">*.mk</code> file unless you want
  3632. to override them:
  3633. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  3634. <code class="literal">CMAKE_BUILD_TYPE</code> is driven by <code class="literal">BR2_ENABLE_DEBUG</code>;
  3635. </li><li class="listitem">
  3636. <code class="literal">CMAKE_INSTALL_PREFIX</code>;
  3637. </li><li class="listitem">
  3638. <code class="literal">BUILD_SHARED_LIBS</code> is driven by <code class="literal">BR2_STATIC_LIBS</code>;
  3639. </li><li class="listitem">
  3640. <code class="literal">BUILD_DOC</code>, <code class="literal">BUILD_DOCS</code> are disabled;
  3641. </li><li class="listitem">
  3642. <code class="literal">BUILD_EXAMPLE</code>, <code class="literal">BUILD_EXAMPLES</code> are disabled;
  3643. </li><li class="listitem">
  3644. <code class="literal">BUILD_TEST</code>, <code class="literal">BUILD_TESTS</code>, <code class="literal">BUILD_TESTING</code> are disabled.
  3645. </li></ul></div></li><li class="listitem">
  3646. <code class="literal">LIBFOO_SUPPORTS_IN_SOURCE_BUILD = NO</code> should be set when the package
  3647. cannot be built inside the source tree but needs a separate build
  3648. directory.
  3649. </li><li class="listitem">
  3650. <code class="literal">LIBFOO_MAKE</code>, to specify an alternate <code class="literal">make</code> command. This is
  3651. typically useful when parallel make is enabled in the configuration
  3652. (using <code class="literal">BR2_JLEVEL</code>) but that this feature should be disabled for
  3653. the given package, for one reason or another. By default, set to
  3654. <code class="literal">$(MAKE)</code>. If parallel building is not supported by the package,
  3655. then it should be set to <code class="literal">LIBFOO_MAKE=$(MAKE1)</code>.
  3656. </li><li class="listitem">
  3657. <code class="literal">LIBFOO_MAKE_ENV</code>, to specify additional environment variables to
  3658. pass to make in the build step. These are passed before the <code class="literal">make</code>
  3659. command. By default, empty.
  3660. </li><li class="listitem">
  3661. <code class="literal">LIBFOO_MAKE_OPTS</code>, to specify additional variables to pass to make
  3662. in the build step. These are passed after the <code class="literal">make</code> command. By
  3663. default, empty.
  3664. </li><li class="listitem">
  3665. <code class="literal">LIBFOO_INSTALL_OPTS</code> contains the make options used to
  3666. install the package to the host directory. By default, the value
  3667. is <code class="literal">install</code>, which is correct for most CMake packages. It is still
  3668. possible to override it.
  3669. </li><li class="listitem">
  3670. <code class="literal">LIBFOO_INSTALL_STAGING_OPTS</code> contains the make options used to
  3671. install the package to the staging directory. By default, the value
  3672. is <code class="literal">DESTDIR=$(STAGING_DIR) install/fast</code>, which is correct for most
  3673. CMake packages. It is still possible to override it.
  3674. </li><li class="listitem">
  3675. <code class="literal">LIBFOO_INSTALL_TARGET_OPTS</code> contains the make options used to
  3676. install the package to the target directory. By default, the value
  3677. is <code class="literal">DESTDIR=$(TARGET_DIR) install/fast</code>. The default value is correct
  3678. for most CMake packages, but it is still possible to override it if
  3679. needed.
  3680. </li></ul></div><p>With the CMake infrastructure, all the steps required to build and
  3681. install the packages are already defined, and they generally work well
  3682. for most CMake-based packages. However, when required, it is still
  3683. possible to customize what is done in any particular step:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3684. By adding a post-operation hook (after extract, patch, configure,
  3685. build or install). See <a class="xref" href="#hooks" title="18.22. Hooks available in the various build steps">Section 18.22, “Hooks available in the various build steps”</a> for details.
  3686. </li><li class="listitem">
  3687. By overriding one of the steps. For example, even if the CMake
  3688. infrastructure is used, if the package <code class="literal">.mk</code> file defines its own
  3689. <code class="literal">LIBFOO_CONFIGURE_CMDS</code> variable, it will be used instead of the
  3690. default CMake one. However, using this method should be restricted
  3691. to very specific cases. Do not use it in the general case.
  3692. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_python_packages"></a>18.8. Infrastructure for Python packages</h2></div></div></div><p>This infrastructure applies to Python packages that use the standard
  3693. Python setuptools mechanism as their build system, generally
  3694. recognizable by the usage of a <code class="literal">setup.py</code> script.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="python-package-tutorial"></a>18.8.1. <code class="literal">python-package</code> tutorial</h3></div></div></div><p>First, let’s see how to write a <code class="literal">.mk</code> file for a Python package,
  3695. with an example :</p><pre class="screen">01: ################################################################################
  3696. 02: #
  3697. 03: # python-foo
  3698. 04: #
  3699. 05: ################################################################################
  3700. 06:
  3701. 07: PYTHON_FOO_VERSION = 1.0
  3702. 08: PYTHON_FOO_SOURCE = python-foo-$(PYTHON_FOO_VERSION).tar.xz
  3703. 09: PYTHON_FOO_SITE = http://www.foosoftware.org/download
  3704. 10: PYTHON_FOO_LICENSE = BSD-3-Clause
  3705. 11: PYTHON_FOO_LICENSE_FILES = LICENSE
  3706. 12: PYTHON_FOO_ENV = SOME_VAR=1
  3707. 13: PYTHON_FOO_DEPENDENCIES = libmad
  3708. 14: PYTHON_FOO_SETUP_TYPE = distutils
  3709. 15:
  3710. 16: $(eval $(python-package))</pre><p>On line 7, we declare the version of the package.</p><p>On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  3711. recommended) and the location of the tarball on the Web. Buildroot
  3712. will automatically download the tarball from this location.</p><p>On line 10 and 11, we give licensing details about the package (its
  3713. license on line 10, and the file containing the license text on line
  3714. 11).</p><p>On line 12, we tell Buildroot to pass custom options to the Python
  3715. <code class="literal">setup.py</code> script when it is configuring the package.</p><p>On line 13, we declare our dependencies, so that they are built
  3716. before the build process of our package starts.</p><p>On line 14, we declare the specific Python build system being used. In
  3717. this case the <code class="literal">distutils</code> Python build system is used. The two
  3718. supported ones are <code class="literal">distutils</code> and <code class="literal">setuptools</code>.</p><p>Finally, on line 16, we invoke the <code class="literal">python-package</code> macro that
  3719. generates all the Makefile rules that actually allow the package to be
  3720. built.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="python-package-reference"></a>18.8.2. <code class="literal">python-package</code> reference</h3></div></div></div><p>As a policy, packages that merely provide Python modules should all be
  3721. named <code class="literal">python-&lt;something&gt;</code> in Buildroot. Other packages that use the
  3722. Python build system, but are not Python modules, can freely choose
  3723. their name (existing examples in Buildroot are <code class="literal">scons</code> and
  3724. <code class="literal">supervisor</code>).</p><p>Packages that are only compatible with one version of Python (as in:
  3725. Python 2 or Python 3) should depend on that version explicitely in
  3726. their <code class="literal">Config.in</code> file (<code class="literal">BR2_PACKAGE_PYTHON</code> for Python 2,
  3727. <code class="literal">BR2_PACKAGE_PYTHON3</code> for Python 3). Packages that are compatible
  3728. with both versions should not explicitely depend on them in their
  3729. <code class="literal">Config.in</code> file, since that condition is already expressed for the
  3730. whole "External python modules" menu.</p><p>The main macro of the Python package infrastructure is
  3731. <code class="literal">python-package</code>. It is similar to the <code class="literal">generic-package</code> macro. It is
  3732. also possible to create Python host packages with the
  3733. <code class="literal">host-python-package</code> macro.</p><p>Just like the generic infrastructure, the Python infrastructure works
  3734. by defining a number of variables before calling the <code class="literal">python-package</code>
  3735. or <code class="literal">host-python-package</code> macros.</p><p>All the package metadata information variables that exist in the
  3736. <a class="link" href="#generic-package-reference" title="18.5.2. generic-package reference">generic package infrastructure</a> also
  3737. exist in the Python infrastructure: <code class="literal">PYTHON_FOO_VERSION</code>,
  3738. <code class="literal">PYTHON_FOO_SOURCE</code>, <code class="literal">PYTHON_FOO_PATCH</code>, <code class="literal">PYTHON_FOO_SITE</code>,
  3739. <code class="literal">PYTHON_FOO_SUBDIR</code>, <code class="literal">PYTHON_FOO_DEPENDENCIES</code>, <code class="literal">PYTHON_FOO_LICENSE</code>,
  3740. <code class="literal">PYTHON_FOO_LICENSE_FILES</code>, <code class="literal">PYTHON_FOO_INSTALL_STAGING</code>, etc.</p><p>Note that:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3741. It is not necessary to add <code class="literal">python</code> or <code class="literal">host-python</code> in the
  3742. <code class="literal">PYTHON_FOO_DEPENDENCIES</code> variable of a package, since these basic
  3743. dependencies are automatically added as needed by the Python
  3744. package infrastructure.
  3745. </li><li class="listitem">
  3746. Similarly, it is not needed to add <code class="literal">host-setuptools</code> to
  3747. <code class="literal">PYTHON_FOO_DEPENDENCIES</code> for setuptools-based packages, since it’s
  3748. automatically added by the Python infrastructure as needed.
  3749. </li></ul></div><p>One variable specific to the Python infrastructure is mandatory:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3750. <code class="literal">PYTHON_FOO_SETUP_TYPE</code>, to define which Python build system is used
  3751. by the package. The two supported values are <code class="literal">distutils</code> and
  3752. <code class="literal">setuptools</code>. If you don’t know which one is used in your package,
  3753. look at the <code class="literal">setup.py</code> file in your package source code, and see
  3754. whether it imports things from the <code class="literal">distutils</code> module or the
  3755. <code class="literal">setuptools</code> module.
  3756. </li></ul></div><p>A few additional variables, specific to the Python infrastructure, can
  3757. optionally be defined, depending on the package’s needs. Many of them
  3758. are only useful in very specific cases, typical packages will
  3759. therefore only use a few of them, or none.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3760. <code class="literal">PYTHON_FOO_SUBDIR</code> may contain the name of a subdirectory inside the
  3761. package that contains the main <code class="literal">setup.py</code> file. This is useful,
  3762. if for example, the main <code class="literal">setup.py</code> file is not at the root of
  3763. the tree extracted by the tarball. If <code class="literal">HOST_PYTHON_FOO_SUBDIR</code> is not
  3764. specified, it defaults to <code class="literal">PYTHON_FOO_SUBDIR</code>.
  3765. </li><li class="listitem">
  3766. <code class="literal">PYTHON_FOO_ENV</code>, to specify additional environment variables to
  3767. pass to the Python <code class="literal">setup.py</code> script (for both the build and install
  3768. steps). Note that the infrastructure is automatically passing
  3769. several standard variables, defined in <code class="literal">PKG_PYTHON_DISTUTILS_ENV</code>
  3770. (for distutils target packages), <code class="literal">HOST_PKG_PYTHON_DISTUTILS_ENV</code>
  3771. (for distutils host packages), <code class="literal">PKG_PYTHON_SETUPTOOLS_ENV</code> (for
  3772. setuptools target packages) and <code class="literal">HOST_PKG_PYTHON_SETUPTOOLS_ENV</code>
  3773. (for setuptools host packages).
  3774. </li><li class="listitem">
  3775. <code class="literal">PYTHON_FOO_BUILD_OPTS</code>, to specify additional options to pass to the
  3776. Python <code class="literal">setup.py</code> script during the build step. For target distutils
  3777. packages, the <code class="literal">PKG_PYTHON_DISTUTILS_BUILD_OPTS</code> options are already
  3778. passed automatically by the infrastructure.
  3779. </li><li class="listitem">
  3780. <code class="literal">PYTHON_FOO_INSTALL_TARGET_OPTS</code>, <code class="literal">PYTHON_FOO_INSTALL_STAGING_OPTS</code>,
  3781. <code class="literal">HOST_PYTHON_FOO_INSTALL_OPTS</code> to specify additional options to pass
  3782. to the Python <code class="literal">setup.py</code> script during the target installation step,
  3783. the staging installation step or the host installation,
  3784. respectively. Note that the infrastructure is automatically passing
  3785. some options, defined in <code class="literal">PKG_PYTHON_DISTUTILS_INSTALL_TARGET_OPTS</code>
  3786. or <code class="literal">PKG_PYTHON_DISTUTILS_INSTALL_STAGING_OPTS</code> (for target distutils
  3787. packages), <code class="literal">HOST_PKG_PYTHON_DISTUTILS_INSTALL_OPTS</code> (for host
  3788. distutils packages), <code class="literal">PKG_PYTHON_SETUPTOOLS_INSTALL_TARGET_OPTS</code> or
  3789. <code class="literal">PKG_PYTHON_SETUPTOOLS_INSTALL_STAGING_OPTS</code> (for target setuptools
  3790. packages) and <code class="literal">HOST_PKG_PYTHON_SETUPTOOLS_INSTALL_OPTS</code> (for host
  3791. setuptools packages).
  3792. </li><li class="listitem">
  3793. <code class="literal">HOST_PYTHON_FOO_NEEDS_HOST_PYTHON</code>, to define the host python
  3794. interpreter. The usage of this variable is limited to host
  3795. packages. The two supported value are <code class="literal">python2</code> and <code class="literal">python3</code>. It
  3796. will ensure the right host python package is available and will
  3797. invoke it for the build. If some build steps are overloaded, the
  3798. right python interpreter must be explicitly called in the commands.
  3799. </li></ul></div><p>With the Python infrastructure, all the steps required to build and
  3800. install the packages are already defined, and they generally work well
  3801. for most Python-based packages. However, when required, it is still
  3802. possible to customize what is done in any particular step:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3803. By adding a post-operation hook (after extract, patch, configure,
  3804. build or install). See <a class="xref" href="#hooks" title="18.22. Hooks available in the various build steps">Section 18.22, “Hooks available in the various build steps”</a> for details.
  3805. </li><li class="listitem">
  3806. By overriding one of the steps. For example, even if the Python
  3807. infrastructure is used, if the package <code class="literal">.mk</code> file defines its own
  3808. <code class="literal">PYTHON_FOO_BUILD_CMDS</code> variable, it will be used instead of the
  3809. default Python one. However, using this method should be restricted
  3810. to very specific cases. Do not use it in the general case.
  3811. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="scanpypi"></a>18.8.3. Generating a <code class="literal">python-package</code> from a PyPI repository</h3></div></div></div><p>If the Python package for which you would like to create a Buildroot
  3812. package is available on PyPI, you may want to use the <code class="literal">scanpypi</code> tool
  3813. located in <code class="literal">utils/</code> to automate the process.</p><p>You can find the list of existing PyPI packages
  3814. <a class="ulink" href="https://pypi.python.org" target="_top">here</a>.</p><p><code class="literal">scanpypi</code> requires Python’s <code class="literal">setuptools</code> package to be installed on
  3815. your host.</p><p>When at the root of your buildroot directory just do :</p><pre class="screen">utils/scanpypi foo bar -o package</pre><p>This will generate packages <code class="literal">python-foo</code> and <code class="literal">python-bar</code> in the package
  3816. folder if they exist on <a class="ulink" href="https://pypi.python.org" target="_top">https://pypi.python.org</a>.</p><p>Find the <code class="literal">external python modules</code> menu and insert your package inside.
  3817. Keep in mind that the items inside a menu should be in alphabetical order.</p><p>Please keep in mind that you’ll most likely have to manually check the
  3818. package for any mistakes as there are things that cannot be guessed by
  3819. the generator (e.g. dependencies on any of the python core modules
  3820. such as BR2_PACKAGE_PYTHON_ZLIB). Also, please take note that the
  3821. license and license files are guessed and must be checked. You also
  3822. need to manually add the package to the <code class="literal">package/Config.in</code> file.</p><p>If your Buildroot package is not in the official Buildroot tree but in
  3823. a br2-external tree, use the -o flag as follows:</p><pre class="screen">utils/scanpypi foo bar -o other_package_dir</pre><p>This will generate packages <code class="literal">python-foo</code> and <code class="literal">python-bar</code> in the
  3824. <code class="literal">other_package_directory</code> instead of <code class="literal">package</code>.</p><p>Option <code class="literal">-h</code> will list the available options:</p><pre class="screen">utils/scanpypi -h</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="python-package-cffi-backend"></a>18.8.4. <code class="literal">python-package</code> CFFI backend</h3></div></div></div><p>C Foreign Function Interface for Python (CFFI) provides a convenient
  3825. and reliable way to call compiled C code from Python using interface
  3826. declarations written in C. Python packages relying on this backend can
  3827. be identified by the appearance of a <code class="literal">cffi</code> dependency in the
  3828. <code class="literal">install_requires</code> field of their <code class="literal">setup.py</code> file.</p><p>Such a package should:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3829. add <code class="literal">python-cffi</code> as a runtime dependency in order to install the
  3830. compiled C library wrapper on the target. This is achieved by adding
  3831. <code class="literal">select BR2_PACKAGE_PYTHON_CFFI</code> to the package <code class="literal">Config.in</code>.
  3832. </li></ul></div><pre class="screen">config BR2_PACKAGE_PYTHON_FOO
  3833. bool "python-foo"
  3834. select BR2_PACKAGE_PYTHON_CFFI # runtime</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3835. add <code class="literal">host-python-cffi</code> as a build-time dependency in order to
  3836. cross-compile the C wrapper. This is achieved by adding
  3837. <code class="literal">host-python-cffi</code> to the <code class="literal">PYTHON_FOO_DEPENDENCIES</code> variable.
  3838. </li></ul></div><pre class="screen">################################################################################
  3839. #
  3840. # python-foo
  3841. #
  3842. ################################################################################
  3843. ...
  3844. PYTHON_FOO_DEPENDENCIES = host-python-cffi
  3845. $(eval $(python-package))</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_luarocks_based_packages"></a>18.9. Infrastructure for LuaRocks-based packages</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="luarocks-package-tutorial"></a>18.9.1. <code class="literal">luarocks-package</code> tutorial</h3></div></div></div><p>First, let’s see how to write a <code class="literal">.mk</code> file for a LuaRocks-based package,
  3846. with an example :</p><pre class="screen">01: ################################################################################
  3847. 02: #
  3848. 03: # lua-foo
  3849. 04: #
  3850. 05: ################################################################################
  3851. 06:
  3852. 07: LUA_FOO_VERSION = 1.0.2-1
  3853. 08: LUA_FOO_NAME_UPSTREAM = foo
  3854. 09: LUA_FOO_DEPENDENCIES = bar
  3855. 10:
  3856. 11: LUA_FOO_BUILD_OPTS += BAR_INCDIR=$(STAGING_DIR)/usr/include
  3857. 12: LUA_FOO_BUILD_OPTS += BAR_LIBDIR=$(STAGING_DIR)/usr/lib
  3858. 13: LUA_FOO_LICENSE = luaFoo license
  3859. 14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING
  3860. 15:
  3861. 16: $(eval $(luarocks-package))</pre><p>On line 7, we declare the version of the package (the same as in the rockspec,
  3862. which is the concatenation of the upstream version and the rockspec revision,
  3863. separated by a hyphen <span class="emphasis"><em>-</em></span>).</p><p>On line 8, we declare that the package is called "foo" on LuaRocks. In
  3864. Buildroot, we give Lua-related packages a name that starts with "lua", so the
  3865. Buildroot name is different from the upstream name. <code class="literal">LUA_FOO_NAME_UPSTREAM</code>
  3866. makes the link between the two names.</p><p>On line 9, we declare our dependencies against native libraries, so that they
  3867. are built before the build process of our package starts.</p><p>On lines 11-12, we tell Buildroot to pass custom options to LuaRocks when it is
  3868. building the package.</p><p>On lines 13-14, we specify the licensing terms for the package.</p><p>Finally, on line 16, we invoke the <code class="literal">luarocks-package</code>
  3869. macro that generates all the Makefile rules that actually allows the
  3870. package to be built.</p><p>Most of these details can be retrieved from the <code class="literal">rock</code> and <code class="literal">rockspec</code>.
  3871. So, this file and the Config.in file can be generated by running the
  3872. command <code class="literal">luarocks buildroot foo lua-foo</code> in the Buildroot
  3873. directory. This command runs a specific Buildroot addon of <code class="literal">luarocks</code>
  3874. that will automatically generate a Buildroot package. The result must
  3875. still be manually inspected and possibly modified.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3876. The <code class="literal">package/Config.in</code> file has to be updated manually to include the
  3877. generated Config.in files.
  3878. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="luarocks-package-reference"></a>18.9.2. <code class="literal">luarocks-package</code> reference</h3></div></div></div><p>LuaRocks is a deployment and management system for Lua modules, and supports
  3879. various <code class="literal">build.type</code>: <code class="literal">builtin</code>, <code class="literal">make</code> and <code class="literal">cmake</code>. In the context of
  3880. Buildroot, the <code class="literal">luarocks-package</code> infrastructure only supports the <code class="literal">builtin</code>
  3881. mode. LuaRocks packages that use the <code class="literal">make</code> or <code class="literal">cmake</code> build mechanisms
  3882. should instead be packaged using the <code class="literal">generic-package</code> and <code class="literal">cmake-package</code>
  3883. infrastructures in Buildroot, respectively.</p><p>The main macro of the LuaRocks package infrastructure is <code class="literal">luarocks-package</code>:
  3884. like <code class="literal">generic-package</code> it works by defining a number of variables providing
  3885. metadata information about the package, and then calling <code class="literal">luarocks-package</code>.</p><p>Just like the generic infrastructure, the LuaRocks infrastructure works
  3886. by defining a number of variables before calling the <code class="literal">luarocks-package</code>
  3887. macro.</p><p>First, all the package metadata information variables that exist in
  3888. the generic infrastructure also exist in the LuaRocks infrastructure:
  3889. <code class="literal">LUA_FOO_VERSION</code>, <code class="literal">LUA_FOO_SOURCE</code>, <code class="literal">LUA_FOO_SITE</code>,
  3890. <code class="literal">LUA_FOO_DEPENDENCIES</code>, <code class="literal">LUA_FOO_LICENSE</code>, <code class="literal">LUA_FOO_LICENSE_FILES</code>.</p><p>Two of them are populated by the LuaRocks infrastructure (for the
  3891. <code class="literal">download</code> step). If your package is not hosted on the LuaRocks mirror
  3892. <code class="literal">$(BR2_LUAROCKS_MIRROR)</code>, you can override them:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3893. <code class="literal">LUA_FOO_SITE</code>, which defaults to <code class="literal">$(BR2_LUAROCKS_MIRROR)</code>
  3894. </li><li class="listitem">
  3895. <code class="literal">LUA_FOO_SOURCE</code>, which defaults to
  3896. <code class="literal">$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).src.rock</code>
  3897. </li></ul></div><p>A few additional variables, specific to the LuaRocks infrastructure, are
  3898. also defined. They can be overridden in specific cases.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3899. <code class="literal">LUA_FOO_NAME_UPSTREAM</code>, which defaults to <code class="literal">lua-foo</code>, i.e. the Buildroot
  3900. package name
  3901. </li><li class="listitem">
  3902. <code class="literal">LUA_FOO_ROCKSPEC</code>, which defaults to
  3903. <code class="literal">$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).rockspec</code>
  3904. </li><li class="listitem">
  3905. <code class="literal">LUA_FOO_SUBDIR</code>, which defaults to
  3906. <code class="literal">$(LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION_WITHOUT_ROCKSPEC_REVISION)</code>
  3907. </li><li class="listitem">
  3908. <code class="literal">LUA_FOO_BUILD_OPTS</code> contains additional build options for the
  3909. <code class="literal">luarocks build</code> call.
  3910. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_perl_cpan_packages"></a>18.10. Infrastructure for Perl/CPAN packages</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="perl-package-tutorial"></a>18.10.1. <code class="literal">perl-package</code> tutorial</h3></div></div></div><p>First, let’s see how to write a <code class="literal">.mk</code> file for a Perl/CPAN package,
  3911. with an example :</p><pre class="screen">01: ################################################################################
  3912. 02: #
  3913. 03: # perl-foo-bar
  3914. 04: #
  3915. 05: ################################################################################
  3916. 06:
  3917. 07: PERL_FOO_BAR_VERSION = 0.02
  3918. 08: PERL_FOO_BAR_SOURCE = Foo-Bar-$(PERL_FOO_BAR_VERSION).tar.gz
  3919. 09: PERL_FOO_BAR_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER
  3920. 10: PERL_FOO_BAR_DEPENDENCIES = perl-strictures
  3921. 11: PERL_FOO_BAR_LICENSE = Artistic or GPL-1.0+
  3922. 12: PERL_FOO_BAR_LICENSE_FILES = LICENSE
  3923. 13: PERL_FOO_BAR_DISTNAME = Foo-Bar
  3924. 14:
  3925. 15: $(eval $(perl-package))</pre><p>On line 7, we declare the version of the package.</p><p>On line 8 and 9, we declare the name of the tarball and the location
  3926. of the tarball on a CPAN server. Buildroot will automatically download
  3927. the tarball from this location.</p><p>On line 10, we declare our dependencies, so that they are built
  3928. before the build process of our package starts.</p><p>On line 11 and 12, we give licensing details about the package (its
  3929. license on line 11, and the file containing the license text on line
  3930. 12).</p><p>On line 13, the name of the distribution as needed by the script
  3931. <code class="literal">utils/scancpan</code> (in order to regenerate/upgrade these package files).</p><p>Finally, on line 15, we invoke the <code class="literal">perl-package</code> macro that
  3932. generates all the Makefile rules that actually allow the package to be
  3933. built.</p><p>Most of these data can be retrieved from <a class="ulink" href="https://metacpan.org/" target="_top">https://metacpan.org/</a>.
  3934. So, this file and the Config.in can be generated by running
  3935. the script <code class="literal">utils/scancpan Foo-Bar</code> in the Buildroot directory
  3936. (or in a br2-external tree).
  3937. This script creates a Config.in file and foo-bar.mk file for the
  3938. requested package, and also recursively for all dependencies specified by
  3939. CPAN. You should still manually edit the result. In particular, the
  3940. following things should be checked.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3941. If the perl module links with a shared library that is provided by
  3942. another (non-perl) package, this dependency is not added automatically.
  3943. It has to be added manually to <code class="literal">PERL_FOO_BAR_DEPENDENCIES</code>.
  3944. </li><li class="listitem">
  3945. The <code class="literal">package/Config.in</code> file has to be updated manually to include the
  3946. generated Config.in files. As a hint, the <code class="literal">scancpan</code> script prints out
  3947. the required <code class="literal">source "…"</code> statements, sorted alphabetically.
  3948. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="perl-package-reference"></a>18.10.2. <code class="literal">perl-package</code> reference</h3></div></div></div><p>As a policy, packages that provide Perl/CPAN modules should all be
  3949. named <code class="literal">perl-&lt;something&gt;</code> in Buildroot.</p><p>This infrastructure handles various Perl build systems :
  3950. <code class="literal">ExtUtils-MakeMaker</code> (EUMM), <code class="literal">Module-Build</code> (MB) and <code class="literal">Module-Build-Tiny</code>.
  3951. <code class="literal">Build.PL</code> is preferred by default when a package provides a <code class="literal">Makefile.PL</code>
  3952. and a <code class="literal">Build.PL</code>.</p><p>The main macro of the Perl/CPAN package infrastructure is
  3953. <code class="literal">perl-package</code>. It is similar to the <code class="literal">generic-package</code> macro. The ability to
  3954. have target and host packages is also available, with the
  3955. <code class="literal">host-perl-package</code> macro.</p><p>Just like the generic infrastructure, the Perl/CPAN infrastructure
  3956. works by defining a number of variables before calling the
  3957. <code class="literal">perl-package</code> macro.</p><p>First, all the package metadata information variables that exist in the
  3958. generic infrastructure also exist in the Perl/CPAN infrastructure:
  3959. <code class="literal">PERL_FOO_VERSION</code>, <code class="literal">PERL_FOO_SOURCE</code>,
  3960. <code class="literal">PERL_FOO_PATCH</code>, <code class="literal">PERL_FOO_SITE</code>,
  3961. <code class="literal">PERL_FOO_SUBDIR</code>, <code class="literal">PERL_FOO_DEPENDENCIES</code>,
  3962. <code class="literal">PERL_FOO_INSTALL_TARGET</code>.</p><p>Note that setting <code class="literal">PERL_FOO_INSTALL_STAGING</code> to <code class="literal">YES</code> has no effect
  3963. unless a <code class="literal">PERL_FOO_INSTALL_STAGING_CMDS</code> variable is defined. The perl
  3964. infrastructure doesn’t define these commands since Perl modules generally
  3965. don’t need to be installed to the <code class="literal">staging</code> directory.</p><p>A few additional variables, specific to the Perl/CPAN infrastructure,
  3966. can also be defined. Many of them are only useful in very specific
  3967. cases, typical packages will therefore only use a few of them.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  3968. <code class="literal">PERL_FOO_PREFER_INSTALLER</code>/<code class="literal">HOST_PERL_FOO_PREFER_INSTALLER</code>,
  3969. specifies the preferred installation method. Possible values are
  3970. <code class="literal">EUMM</code> (for <code class="literal">Makefile.PL</code> based installation using
  3971. <code class="literal">ExtUtils-MakeMaker</code>) and <code class="literal">MB</code> (for <code class="literal">Build.PL</code> based installation
  3972. using <code class="literal">Module-Build</code>). This variable is only used when the package
  3973. provides both installation methods.
  3974. </li><li class="listitem">
  3975. <code class="literal">PERL_FOO_CONF_ENV</code>/<code class="literal">HOST_PERL_FOO_CONF_ENV</code>, to specify additional
  3976. environment variables to pass to the <code class="literal">perl Makefile.PL</code> or <code class="literal">perl Build.PL</code>.
  3977. By default, empty.
  3978. </li><li class="listitem">
  3979. <code class="literal">PERL_FOO_CONF_OPTS</code>/<code class="literal">HOST_PERL_FOO_CONF_OPTS</code>, to specify additional
  3980. configure options to pass to the <code class="literal">perl Makefile.PL</code> or <code class="literal">perl Build.PL</code>.
  3981. By default, empty.
  3982. </li><li class="listitem">
  3983. <code class="literal">PERL_FOO_BUILD_OPTS</code>/<code class="literal">HOST_PERL_FOO_BUILD_OPTS</code>, to specify additional
  3984. options to pass to <code class="literal">make pure_all</code> or <code class="literal">perl Build build</code> in the build step.
  3985. By default, empty.
  3986. </li><li class="listitem">
  3987. <code class="literal">PERL_FOO_INSTALL_TARGET_OPTS</code>, to specify additional options to
  3988. pass to <code class="literal">make pure_install</code> or <code class="literal">perl Build install</code> in the install step.
  3989. By default, empty.
  3990. </li><li class="listitem">
  3991. <code class="literal">HOST_PERL_FOO_INSTALL_OPTS</code>, to specify additional options to
  3992. pass to <code class="literal">make pure_install</code> or <code class="literal">perl Build install</code> in the install step.
  3993. By default, empty.
  3994. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_virtual_packages"></a>18.11. Infrastructure for virtual packages</h2></div></div></div><p><a id="virtual-package-tutorial"></a>In Buildroot, a virtual package is a package whose functionalities are
  3995. provided by one or more packages, referred to as <span class="emphasis"><em>providers</em></span>. The virtual
  3996. package management is an extensible mechanism allowing the user to choose
  3997. the provider used in the rootfs.</p><p>For example, <span class="emphasis"><em>OpenGL ES</em></span> is an API for 2D and 3D graphics on embedded systems.
  3998. The implementation of this API is different for the <span class="emphasis"><em>Allwinner Tech Sunxi</em></span> and
  3999. the <span class="emphasis"><em>Texas Instruments OMAP35xx</em></span> platforms. So <code class="literal">libgles</code> will be a virtual
  4000. package and <code class="literal">sunxi-mali</code> and <code class="literal">ti-gfx</code> will be the providers.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_literal_virtual_package_literal_tutorial"></a>18.11.1. <code class="literal">virtual-package</code> tutorial</h3></div></div></div><p>In the following example, we will explain how to add a new virtual package
  4001. (<span class="emphasis"><em>something-virtual</em></span>) and a provider for it (<span class="emphasis"><em>some-provider</em></span>).</p><p>First, let’s create the virtual package.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_virtual_package_8217_s_literal_config_in_literal_file"></a>18.11.2. Virtual package’s <code class="literal">Config.in</code> file</h3></div></div></div><p>The <code class="literal">Config.in</code> file of virtual package <span class="emphasis"><em>something-virtual</em></span> should contain:</p><pre class="screen">01: config BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  4002. 02: bool
  4003. 03:
  4004. 04: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
  4005. 05: depends on BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  4006. 06: string</pre><p>In this file, we declare two options, <code class="literal">BR2_PACKAGE_HAS_SOMETHING_VIRTUAL</code> and
  4007. <code class="literal">BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL</code>, whose values will be used by the
  4008. providers.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_virtual_package_8217_s_literal_mk_literal_file"></a>18.11.3. Virtual package’s <code class="literal">.mk</code> file</h3></div></div></div><p>The <code class="literal">.mk</code> for the virtual package should just evaluate the <code class="literal">virtual-package</code> macro:</p><pre class="screen">01: ################################################################################
  4009. 02: #
  4010. 03: # something-virtual
  4011. 04: #
  4012. 05: ################################################################################
  4013. 06:
  4014. 07: $(eval $(virtual-package))</pre><p>The ability to have target and host packages is also available, with the
  4015. <code class="literal">host-virtual-package</code> macro.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_provider_8217_s_literal_config_in_literal_file"></a>18.11.4. Provider’s <code class="literal">Config.in</code> file</h3></div></div></div><p>When adding a package as a provider, only the <code class="literal">Config.in</code> file requires some
  4016. modifications.</p><p>The <code class="literal">Config.in</code> file of the package <span class="emphasis"><em>some-provider</em></span>, which provides the
  4017. functionalities of <span class="emphasis"><em>something-virtual</em></span>, should contain:</p><pre class="screen">01: config BR2_PACKAGE_SOME_PROVIDER
  4018. 02: bool "some-provider"
  4019. 03: select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  4020. 04: help
  4021. 05: This is a comment that explains what some-provider is.
  4022. 06:
  4023. 07: http://foosoftware.org/some-provider/
  4024. 08:
  4025. 09: if BR2_PACKAGE_SOME_PROVIDER
  4026. 10: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
  4027. 11: default "some-provider"
  4028. 12: endif</pre><p>On line 3, we select <code class="literal">BR2_PACKAGE_HAS_SOMETHING_VIRTUAL</code>, and on line 11, we
  4029. set the value of <code class="literal">BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL</code> to the name of the
  4030. provider, but only if it is selected.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_provider_8217_s_literal_mk_literal_file"></a>18.11.5. Provider’s <code class="literal">.mk</code> file</h3></div></div></div><p>The <code class="literal">.mk</code> file should also declare an additional variable
  4031. <code class="literal">SOME_PROVIDER_PROVIDES</code> to contain the names of all the virtual
  4032. packages it is an implementation of:</p><pre class="screen">01: SOME_PROVIDER_PROVIDES = something-virtual</pre><p>Of course, do not forget to add the proper build and runtime dependencies for
  4033. this package!</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_notes_on_depending_on_a_virtual_package"></a>18.11.6. Notes on depending on a virtual package</h3></div></div></div><p>When adding a package that requires a certain <code class="literal">FEATURE</code> provided by a virtual
  4034. package, you have to use <code class="literal">depends on BR2_PACKAGE_HAS_FEATURE</code>, like so:</p><pre class="screen">config BR2_PACKAGE_HAS_FEATURE
  4035. bool
  4036. config BR2_PACKAGE_FOO
  4037. bool "foo"
  4038. depends on BR2_PACKAGE_HAS_FEATURE</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_notes_on_depending_on_a_specific_provider"></a>18.11.7. Notes on depending on a specific provider</h3></div></div></div><p>If your package really requires a specific provider, then you’ll have to
  4039. make your package <code class="literal">depends on</code> this provider; you can <span class="emphasis"><em>not</em></span> <code class="literal">select</code> a
  4040. provider.</p><p>Let’s take an example with two providers for a <code class="literal">FEATURE</code>:</p><pre class="screen">config BR2_PACKAGE_HAS_FEATURE
  4041. bool
  4042. config BR2_PACKAGE_FOO
  4043. bool "foo"
  4044. select BR2_PACKAGE_HAS_FEATURE
  4045. config BR2_PACKAGE_BAR
  4046. bool "bar"
  4047. select BR2_PACKAGE_HAS_FEATURE</pre><p>And you are adding a package that needs <code class="literal">FEATURE</code> as provided by <code class="literal">foo</code>,
  4048. but not as provided by <code class="literal">bar</code>.</p><p>If you were to use <code class="literal">select BR2_PACKAGE_FOO</code>, then the user would still
  4049. be able to select <code class="literal">BR2_PACKAGE_BAR</code> in the menuconfig. This would create
  4050. a configuration inconsistency, whereby two providers of the same <code class="literal">FEATURE</code>
  4051. would be enabled at once, one explicitly set by the user, the other
  4052. implicitly by your <code class="literal">select</code>.</p><p>Instead, you have to use <code class="literal">depends on BR2_PACKAGE_FOO</code>, which avoids any
  4053. implicit configuration inconsistency.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_packages_using_kconfig_for_configuration_files"></a>18.12. Infrastructure for packages using kconfig for configuration files</h2></div></div></div><p>A popular way for a software package to handle user-specified
  4054. configuration is <code class="literal">kconfig</code>. Among others, it is used by the Linux
  4055. kernel, Busybox, and Buildroot itself. The presence of a .config file
  4056. and a <code class="literal">menuconfig</code> target are two well-known symptoms of kconfig being
  4057. used.</p><p>Buildroot features an infrastructure for packages that use kconfig for
  4058. their configuration. This infrastructure provides the necessary logic to
  4059. expose the package’s <code class="literal">menuconfig</code> target as <code class="literal">foo-menuconfig</code> in
  4060. Buildroot, and to handle the copying back and forth of the configuration
  4061. file in a correct way.</p><p>The <code class="literal">kconfig-package</code> infrastructure is based on the <code class="literal">generic-package</code>
  4062. infrastructure. All variables supported by <code class="literal">generic-package</code> are
  4063. available in <code class="literal">kconfig-package</code> as well. See
  4064. <a class="xref" href="#generic-package-reference" title="18.5.2. generic-package reference">Section 18.5.2, “<code class="literal">generic-package</code> reference”</a> for more details.</p><p>In order to use the <code class="literal">kconfig-package</code> infrastructure for a Buildroot
  4065. package, the minimally required lines in the <code class="literal">.mk</code> file, in addition to
  4066. the variables required by the <code class="literal">generic-package</code> infrastructure, are:</p><pre class="screen">FOO_KCONFIG_FILE = reference-to-source-configuration-file
  4067. $(eval $(kconfig-package))</pre><p>This snippet creates the following make targets:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4068. <code class="literal">foo-menuconfig</code>, which calls the package’s <code class="literal">menuconfig</code> target
  4069. </li><li class="listitem">
  4070. <code class="literal">foo-update-config</code>, which copies the configuration back to the
  4071. source configuration file. It is not possible to use this target
  4072. when fragment files are set.
  4073. </li><li class="listitem">
  4074. <code class="literal">foo-update-defconfig</code>, which copies the configuration back to the
  4075. source configuration file. The configuration file will only list the
  4076. options that differ from the default values. It is not possible to
  4077. use this target when fragment files are set.
  4078. </li><li class="listitem">
  4079. <code class="literal">foo-diff-config</code>, which outputs the differences between the current
  4080. configuration and the one defined in the Buildroot configuration for
  4081. this kconfig package. The output is useful to identify the
  4082. configuration changes that may have to be propagated to
  4083. configuration fragments for example.
  4084. </li></ul></div><p>and ensures that the source configuration file is copied to the build
  4085. directory at the right moment.</p><p>There are two options to specify a configuration file to use, either
  4086. <code class="literal">FOO_KCONFIG_FILE</code> (as in the example, above) or <code class="literal">FOO_KCONFIG_DEFCONFIG</code>.
  4087. It is mandatory to provide either, but not both:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4088. <code class="literal">FOO_KCONFIG_FILE</code> specifies the path to a defconfig or full-config file
  4089. to be used to configure the package.
  4090. </li><li class="listitem">
  4091. <code class="literal">FOO_KCONFIG_DEFCONFIG</code> specifies the defconfig <span class="emphasis"><em>make</em></span> rule to call to
  4092. configure the package.
  4093. </li></ul></div><p>In addition to these minimally required lines, several optional variables can
  4094. be set to suit the needs of the package under consideration:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4095. <code class="literal">FOO_KCONFIG_EDITORS</code>: a space-separated list of kconfig editors to
  4096. support, for example <span class="emphasis"><em>menuconfig xconfig</em></span>. By default, <span class="emphasis"><em>menuconfig</em></span>.
  4097. </li><li class="listitem">
  4098. <code class="literal">FOO_KCONFIG_FRAGMENT_FILES</code>: a space-separated list of configuration
  4099. fragment files that are merged to the main configuration file.
  4100. Fragment files are typically used when there is a desire to stay in sync
  4101. with an upstream (def)config file, with some minor modifications.
  4102. </li><li class="listitem">
  4103. <code class="literal">FOO_KCONFIG_OPTS</code>: extra options to pass when calling the kconfig
  4104. editors. This may need to include <span class="emphasis"><em>$(FOO_MAKE_OPTS)</em></span>, for example. By
  4105. default, empty.
  4106. </li><li class="listitem">
  4107. <code class="literal">FOO_KCONFIG_FIXUP_CMDS</code>: a list of shell commands needed to fixup the
  4108. configuration file after copying it or running a kconfig editor. Such
  4109. commands may be needed to ensure a configuration consistent with other
  4110. configuration of Buildroot, for example. By default, empty.
  4111. </li><li class="listitem">
  4112. <code class="literal">FOO_KCONFIG_DOTCONFIG</code>: path (with filename) of the <code class="literal">.config</code> file,
  4113. relative to the package source tree. The default, <code class="literal">.config</code>, should
  4114. be well suited for all packages that use the standard kconfig
  4115. infrastructure as inherited from the Linux kernel; some packages use
  4116. a derivative of kconfig that use a different location.
  4117. </li><li class="listitem">
  4118. <code class="literal">FOO_KCONFIG_DEPENDENCIES</code>: the list of packages (most probably, host
  4119. packages) that need to be built before this package’s kconfig is
  4120. interpreted. Seldom used. By default, empty.
  4121. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_rebar_based_packages"></a>18.13. Infrastructure for rebar-based packages</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="rebar-package-tutorial"></a>18.13.1. <code class="literal">rebar-package</code> tutorial</h3></div></div></div><p>First, let’s see how to write a <code class="literal">.mk</code> file for a rebar-based package,
  4122. with an example :</p><pre class="screen">01: ################################################################################
  4123. 02: #
  4124. 03: # erlang-foobar
  4125. 04: #
  4126. 05: ################################################################################
  4127. 06:
  4128. 07: ERLANG_FOOBAR_VERSION = 1.0
  4129. 08: ERLANG_FOOBAR_SOURCE = erlang-foobar-$(ERLANG_FOOBAR_VERSION).tar.xz
  4130. 09: ERLANG_FOOBAR_SITE = http://www.foosoftware.org/download
  4131. 10: ERLANG_FOOBAR_DEPENDENCIES = host-libaaa libbbb
  4132. 11:
  4133. 12: $(eval $(rebar-package))</pre><p>On line 7, we declare the version of the package.</p><p>On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  4134. recommended) and the location of the tarball on the Web. Buildroot
  4135. will automatically download the tarball from this location.</p><p>On line 10, we declare our dependencies, so that they are built
  4136. before the build process of our package starts.</p><p>Finally, on line 12, we invoke the <code class="literal">rebar-package</code> macro that
  4137. generates all the Makefile rules that actually allows the package to
  4138. be built.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="rebar-package-reference"></a>18.13.2. <code class="literal">rebar-package</code> reference</h3></div></div></div><p>The main macro of the <code class="literal">rebar</code> package infrastructure is
  4139. <code class="literal">rebar-package</code>. It is similar to the <code class="literal">generic-package</code> macro. The
  4140. ability to have host packages is also available, with the
  4141. <code class="literal">host-rebar-package</code> macro.</p><p>Just like the generic infrastructure, the <code class="literal">rebar</code> infrastructure works
  4142. by defining a number of variables before calling the <code class="literal">rebar-package</code>
  4143. macro.</p><p>First, all the package metadata information variables that exist in
  4144. the generic infrastructure also exist in the <code class="literal">rebar</code> infrastructure:
  4145. <code class="literal">ERLANG_FOOBAR_VERSION</code>, <code class="literal">ERLANG_FOOBAR_SOURCE</code>,
  4146. <code class="literal">ERLANG_FOOBAR_PATCH</code>, <code class="literal">ERLANG_FOOBAR_SITE</code>,
  4147. <code class="literal">ERLANG_FOOBAR_SUBDIR</code>, <code class="literal">ERLANG_FOOBAR_DEPENDENCIES</code>,
  4148. <code class="literal">ERLANG_FOOBAR_INSTALL_STAGING</code>, <code class="literal">ERLANG_FOOBAR_INSTALL_TARGET</code>,
  4149. <code class="literal">ERLANG_FOOBAR_LICENSE</code> and <code class="literal">ERLANG_FOOBAR_LICENSE_FILES</code>.</p><p>A few additional variables, specific to the <code class="literal">rebar</code> infrastructure,
  4150. can also be defined. Many of them are only useful in very specific
  4151. cases, typical packages will therefore only use a few of them.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  4152. <code class="literal">ERLANG_FOOBAR_USE_AUTOCONF</code>, to specify that the package uses
  4153. <span class="emphasis"><em>autoconf</em></span> at the configuration step. When a package sets this
  4154. variable to <code class="literal">YES</code>, the <code class="literal">autotools</code> infrastructure is used.
  4155. </p><p><strong>Note. </strong>You can also use some of the variables from the <code class="literal">autotools</code>
  4156. infrastructure: <code class="literal">ERLANG_FOOBAR_CONF_ENV</code>, <code class="literal">ERLANG_FOOBAR_CONF_OPTS</code>,
  4157. <code class="literal">ERLANG_FOOBAR_AUTORECONF</code>, <code class="literal">ERLANG_FOOBAR_AUTORECONF_ENV</code> and
  4158. <code class="literal">ERLANG_FOOBAR_AUTORECONF_OPTS</code>.</p></li><li class="listitem"><p class="simpara">
  4159. <code class="literal">ERLANG_FOOBAR_USE_BUNDLED_REBAR</code>, to specify that the package has
  4160. a bundled version of <span class="emphasis"><em>rebar</em></span> <span class="strong"><strong>and</strong></span> that it shall be used. Valid
  4161. values are <code class="literal">YES</code> or <code class="literal">NO</code> (the default).
  4162. </p><p><strong>Note. </strong>If the package bundles a <span class="emphasis"><em>rebar</em></span> utility, but can use the generic
  4163. one that Buildroot provides, just say <code class="literal">NO</code> (i.e., do not specify
  4164. this variable). Only set if it is mandatory to use the <span class="emphasis"><em>rebar</em></span>
  4165. utility bundled in this package.</p></li><li class="listitem">
  4166. <code class="literal">ERLANG_FOOBAR_REBAR_ENV</code>, to specify additional environment
  4167. variables to pass to the <span class="emphasis"><em>rebar</em></span> utility.
  4168. </li><li class="listitem">
  4169. <code class="literal">ERLANG_FOOBAR_KEEP_DEPENDENCIES</code>, to keep the dependencies
  4170. described in the rebar.config file. Valid values are <code class="literal">YES</code> or <code class="literal">NO</code>
  4171. (the default). Unless this variable is set to <code class="literal">YES</code>, the <span class="emphasis"><em>rebar</em></span>
  4172. infrastructure removes such dependencies in a post-patch hook to
  4173. ensure rebar does not download nor compile them.
  4174. </li></ul></div><p>With the rebar infrastructure, all the steps required to build
  4175. and install the packages are already defined, and they generally work
  4176. well for most rebar-based packages. However, when required, it is
  4177. still possible to customize what is done in any particular step:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4178. By adding a post-operation hook (after extract, patch, configure,
  4179. build or install). See <a class="xref" href="#hooks" title="18.22. Hooks available in the various build steps">Section 18.22, “Hooks available in the various build steps”</a> for details.
  4180. </li><li class="listitem">
  4181. By overriding one of the steps. For example, even if the rebar
  4182. infrastructure is used, if the package <code class="literal">.mk</code> file defines its
  4183. own <code class="literal">ERLANG_FOOBAR_BUILD_CMDS</code> variable, it will be used instead
  4184. of the default rebar one. However, using this method should be
  4185. restricted to very specific cases. Do not use it in the general
  4186. case.
  4187. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_waf_based_packages"></a>18.14. Infrastructure for Waf-based packages</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="waf-package-tutorial"></a>18.14.1. <code class="literal">waf-package</code> tutorial</h3></div></div></div><p>First, let’s see how to write a <code class="literal">.mk</code> file for a Waf-based package, with
  4188. an example :</p><pre class="screen">01: ################################################################################
  4189. 02: #
  4190. 03: # libfoo
  4191. 04: #
  4192. 05: ################################################################################
  4193. 06:
  4194. 07: LIBFOO_VERSION = 1.0
  4195. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  4196. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  4197. 10: LIBFOO_CONF_OPTS = --enable-bar --disable-baz
  4198. 11: LIBFOO_DEPENDENCIES = bar
  4199. 12:
  4200. 13: $(eval $(waf-package))</pre><p>On line 7, we declare the version of the package.</p><p>On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  4201. recommended) and the location of the tarball on the Web. Buildroot
  4202. will automatically download the tarball from this location.</p><p>On line 10, we tell Buildroot what options to enable for libfoo.</p><p>On line 11, we tell Buildroot the dependencies of libfoo.</p><p>Finally, on line line 13, we invoke the <code class="literal">waf-package</code>
  4203. macro that generates all the Makefile rules that actually allows the
  4204. package to be built.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="waf-package-reference"></a>18.14.2. <code class="literal">waf-package</code> reference</h3></div></div></div><p>The main macro of the Waf package infrastructure is <code class="literal">waf-package</code>.
  4205. It is similar to the <code class="literal">generic-package</code> macro.</p><p>Just like the generic infrastructure, the Waf infrastructure works
  4206. by defining a number of variables before calling the <code class="literal">waf-package</code>
  4207. macro.</p><p>First, all the package metadata information variables that exist in
  4208. the generic infrastructure also exist in the Waf infrastructure:
  4209. <code class="literal">LIBFOO_VERSION</code>, <code class="literal">LIBFOO_SOURCE</code>, <code class="literal">LIBFOO_PATCH</code>, <code class="literal">LIBFOO_SITE</code>,
  4210. <code class="literal">LIBFOO_SUBDIR</code>, <code class="literal">LIBFOO_DEPENDENCIES</code>, <code class="literal">LIBFOO_INSTALL_STAGING</code>,
  4211. <code class="literal">LIBFOO_INSTALL_TARGET</code>.</p><p>An additional variable, specific to the Waf infrastructure, can
  4212. also be defined.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4213. <code class="literal">LIBFOO_SUBDIR</code> may contain the name of a subdirectory inside the
  4214. package that contains the main wscript file. This is useful,
  4215. if for example, the main wscript file is not at the root of
  4216. the tree extracted by the tarball. If <code class="literal">HOST_LIBFOO_SUBDIR</code> is not
  4217. specified, it defaults to <code class="literal">LIBFOO_SUBDIR</code>.
  4218. </li><li class="listitem">
  4219. <code class="literal">LIBFOO_NEEDS_EXTERNAL_WAF</code> can be set to <code class="literal">YES</code> or <code class="literal">NO</code> to tell
  4220. Buildroot to use the bundled <code class="literal">waf</code> executable. If set to <code class="literal">NO</code>, the
  4221. default, then Buildroot will use the waf executable provided in the
  4222. package source tree; if set to <code class="literal">YES</code>, then Buildroot will download,
  4223. install waf as a host tool and use it to build the package.
  4224. </li><li class="listitem">
  4225. <code class="literal">LIBFOO_WAF_OPTS</code>, to specify additional options to pass to the
  4226. <code class="literal">waf</code> script at every step of the package build process: configure,
  4227. build and installation. By default, empty.
  4228. </li><li class="listitem">
  4229. <code class="literal">LIBFOO_CONF_OPTS</code>, to specify additional options to pass to the
  4230. <code class="literal">waf</code> script for the configuration step. By default, empty.
  4231. </li><li class="listitem">
  4232. <code class="literal">LIBFOO_BUILD_OPTS</code>, to specify additional options to pass to the
  4233. <code class="literal">waf</code> script during the build step. By default, empty.
  4234. </li><li class="listitem">
  4235. <code class="literal">LIBFOO_INSTALL_STAGING_OPTS</code>, to specify additional options to pass
  4236. to the <code class="literal">waf</code> script during the staging installation step. By default,
  4237. empty.
  4238. </li><li class="listitem">
  4239. <code class="literal">LIBFOO_INSTALL_TARGET_OPTS</code>, to specify additional options to pass
  4240. to the <code class="literal">waf</code> script during the target installation step. By default,
  4241. empty.
  4242. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_meson_based_packages"></a>18.15. Infrastructure for Meson-based packages</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="meson-package-tutorial"></a>18.15.1. <code class="literal">meson-package</code> tutorial</h3></div></div></div><p><a class="ulink" href="http://mesonbuild.com" target="_top">Meson</a> is an open source build system meant to be both
  4243. extremely fast, and, even more importantly, as user friendly as possible. It
  4244. uses <a class="ulink" href="https://ninja-build.org" target="_top">Ninja</a> as a companion tool to perform the actual
  4245. build operations.</p><p>Let’s see how to write a <code class="literal">.mk</code> file for a Meson-based package, with an example:</p><pre class="screen">01: ################################################################################
  4246. 02: #
  4247. 03: # foo
  4248. 04: #
  4249. 05: ################################################################################
  4250. 06:
  4251. 07: FOO_VERSION = 1.0
  4252. 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
  4253. 09: FOO_SITE = http://www.foosoftware.org/download
  4254. 10: FOO_LICENSE = GPL-3.0+
  4255. 11: FOO_LICENSE_FILES = COPYING
  4256. 12: FOO_INSTALL_STAGING = YES
  4257. 13:
  4258. 14: FOO_DEPENDENCIES = host-pkgconf bar
  4259. 15:
  4260. 16: ifeq ($(BR2_PACKAGE_BAZ),y)
  4261. 17: FOO_CONF_OPTS += -Dbaz=true
  4262. 18: FOO_DEPENDENCIES += baz
  4263. 19: else
  4264. 20: FOO_CONF_OPTS += -Dbaz=false
  4265. 21: endif
  4266. 22:
  4267. 23: $(eval $(meson-package))</pre><p>The Makefile starts with the definition of the standard variables for package
  4268. declaration (lines 7 to 11).</p><p>On line line 23, we invoke the <code class="literal">meson-package</code> macro that generates all the
  4269. Makefile rules that actually allows the package to be built.</p><p>In the example, <code class="literal">host-pkgconf</code> and <code class="literal">bar</code> are declared as dependencies in
  4270. <code class="literal">FOO_DEPENDENCIES</code> at line 14 because the Meson build file of <code class="literal">foo</code> uses
  4271. <code class="literal">pkg-config</code> to determine the compilation flags and libraries of package <code class="literal">bar</code>.</p><p>Note that it is not necessary to add <code class="literal">host-meson</code> in the <code class="literal">FOO_DEPENDENCIES</code>
  4272. variable of a package, since this basic dependency is automatically added as
  4273. needed by the Meson package infrastructure.</p><p>If the "baz" package is selected, then support for the "baz" feature in "foo" is
  4274. activated by adding <code class="literal">-Dbaz=true</code> to <code class="literal">FOO_CONF_OPTS</code> at line 17, as specified in
  4275. the <code class="literal">meson_options.txt</code> file in "foo" source tree. The "baz" package is also
  4276. added to <code class="literal">FOO_DEPENDENCIES</code>. Note that the support for <code class="literal">baz</code> is explicitly
  4277. disabled at line 20, if the package is not selected.</p><p>To sum it up, to add a new meson-based package, the Makefile example can be
  4278. copied verbatim then edited to replace all occurences of <code class="literal">FOO</code> with the
  4279. uppercase name of the new package and update the values of the standard
  4280. variables.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="meson-package-reference"></a>18.15.2. <code class="literal">meson-package</code> reference</h3></div></div></div><p>The main macro of the Meson package infrastructure is <code class="literal">meson-package</code>. It is
  4281. similar to the <code class="literal">generic-package</code> macro. The ability to have target and host
  4282. packages is also available, with the <code class="literal">host-meson-package</code> macro.</p><p>Just like the generic infrastructure, the Meson infrastructure works by defining
  4283. a number of variables before calling the <code class="literal">meson-package</code> macro.</p><p>First, all the package metadata information variables that exist in the generic
  4284. infrastructure also exist in the Meson infrastructure: <code class="literal">FOO_VERSION</code>,
  4285. <code class="literal">FOO_SOURCE</code>, <code class="literal">FOO_PATCH</code>, <code class="literal">FOO_SITE</code>, <code class="literal">FOO_SUBDIR</code>, <code class="literal">FOO_DEPENDENCIES</code>,
  4286. <code class="literal">FOO_INSTALL_STAGING</code>, <code class="literal">FOO_INSTALL_TARGET</code>.</p><p>A few additional variables, specific to the Meson infrastructure, can also be
  4287. defined. Many of them are only useful in very specific cases, typical packages
  4288. will therefore only use a few of them.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4289. <code class="literal">FOO_SUBDIR</code> may contain the name of a subdirectory inside the
  4290. package that contains the main meson.build file. This is useful,
  4291. if for example, the main meson.build file is not at the root of
  4292. the tree extracted by the tarball. If <code class="literal">HOST_FOO_SUBDIR</code> is not
  4293. specified, it defaults to <code class="literal">FOO_SUBDIR</code>.
  4294. </li><li class="listitem">
  4295. <code class="literal">FOO_CONF_ENV</code>, to specify additional environment variables to pass to
  4296. <code class="literal">meson</code> for the configuration step. By default, empty.
  4297. </li><li class="listitem">
  4298. <code class="literal">FOO_CONF_OPTS</code>, to specify additional options to pass to <code class="literal">meson</code> for the
  4299. configuration step. By default, empty.
  4300. </li><li class="listitem">
  4301. <code class="literal">FOO_CFLAGS</code>, to specify compiler arguments added to the package specific
  4302. <code class="literal">cross-compile.conf</code> file <code class="literal">c_args</code> property. By default, the value of
  4303. <code class="literal">TARGET_CFLAGS</code>.
  4304. </li><li class="listitem">
  4305. <code class="literal">FOO_CXXFLAGS</code>, to specify compiler arguments added to the package specific
  4306. <code class="literal">cross-compile.conf</code> file <code class="literal">cpp_args</code> property. By default, the value of
  4307. <code class="literal">TARGET_CXXFLAGS</code>.
  4308. </li><li class="listitem">
  4309. <code class="literal">FOO_LDFLAGS</code>, to specify compiler arguments added to the package specific
  4310. <code class="literal">cross-compile.conf</code> file <code class="literal">c_link_args</code> and <code class="literal">cpp_link_args</code> properties. By
  4311. default, the value of <code class="literal">TARGET_LDFLAGS</code>.
  4312. </li><li class="listitem">
  4313. <code class="literal">FOO_MESON_EXTRA_BINARIES</code>, to specify a space-separated list of programs
  4314. to add to the <code class="literal">[binaries]</code> section of the meson <code class="literal">cross-compilation.conf</code>
  4315. configuration file. The format is <code class="literal">program-name='/path/to/program'</code>, with
  4316. no space around the <code class="literal">=</code> sign, and with the path of the program between
  4317. single quotes. By default, empty. Note that Buildroot already sets the
  4318. correct values for <code class="literal">c</code>, <code class="literal">cpp</code>, <code class="literal">ar</code>, <code class="literal">strip</code>, and <code class="literal">pkgconfig</code>.
  4319. </li><li class="listitem">
  4320. <code class="literal">FOO_MESON_EXTRA_PROPERTIES</code>, to specify a space-separated list of
  4321. properties to add to the <code class="literal">[properties]</code> section of the meson
  4322. <code class="literal">cross-compilation.conf</code> configuration file. The format is
  4323. <code class="literal">property-name=&lt;value&gt;</code> with no space around the <code class="literal">=</code> sign, and with
  4324. single quotes around string values. By default, empty. Note that
  4325. Buildroot already sets values for <code class="literal">needs_exe_wrapper</code>, <code class="literal">c_args</code>,
  4326. <code class="literal">c_link_args</code>, <code class="literal">cpp_args</code>, <code class="literal">cpp_link_args</code>, <code class="literal">sys_root</code>, and
  4327. <code class="literal">pkg_config_libdir</code>.
  4328. </li><li class="listitem">
  4329. <code class="literal">FOO_NINJA_ENV</code>, to specify additional environment variables to pass to
  4330. <code class="literal">ninja</code>, meson companion tool in charge of the build operations. By default,
  4331. empty.
  4332. </li><li class="listitem">
  4333. <code class="literal">FOO_NINJA_OPTS</code>, to specify a space-separated list of targets to build. By
  4334. default, empty, to build the default target(s).
  4335. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_integration_of_cargo_based_packages"></a>18.16. Integration of Cargo-based packages</h2></div></div></div><p>Cargo is the package manager for the Rust programming language. It allows the
  4336. user to build programs or libraries written in Rust, but it also downloads and
  4337. manages their dependencies, to ensure repeatable builds. Cargo packages are
  4338. called "crates".</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="cargo-package-tutorial"></a>18.16.1. Cargo-based package’s <code class="literal">Config.in</code> file</h3></div></div></div><p>The <code class="literal">Config.in</code> file of Cargo-based package <span class="emphasis"><em>foo</em></span> should contain:</p><pre class="screen">01: config BR2_PACKAGE_FOO
  4339. 02: bool "foo"
  4340. 03: depends on BR2_PACKAGE_HOST_RUSTC_TARGET_ARCH_SUPPORTS
  4341. 04: select BR2_PACKAGE_HOST_RUSTC
  4342. 05: help
  4343. 06: This is a comment that explains what foo is.
  4344. 07:
  4345. 08: http://foosoftware.org/foo/</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_cargo_based_package_8217_s_literal_mk_literal_file"></a>18.16.2. Cargo-based package’s <code class="literal">.mk</code> file</h3></div></div></div><p>Buildroot does not (yet) provide a dedicated package infrastructure for
  4346. Cargo-based packages. So, we will explain how to write a <code class="literal">.mk</code> file for such a
  4347. package. Let’s start with an example:</p><pre class="screen">01: ################################################################################
  4348. 02: #
  4349. 03: # foo
  4350. 04: #
  4351. 05: ################################################################################
  4352. 06:
  4353. 07: FOO_VERSION = 1.0
  4354. 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
  4355. 09: FOO_SITE = http://www.foosoftware.org/download
  4356. 10: FOO_LICENSE = GPL-3.0+
  4357. 11: FOO_LICENSE_FILES = COPYING
  4358. 12:
  4359. 13: FOO_DEPENDENCIES = host-rustc
  4360. 14:
  4361. 15: FOO_CARGO_ENV = CARGO_HOME=$(HOST_DIR)/share/cargo
  4362. 16:
  4363. 17: FOO_BIN_DIR = target/$(RUSTC_TARGET_NAME)/$(FOO_CARGO_MODE)
  4364. 18:
  4365. 19: FOO_CARGO_OPTS = \
  4366. 20: $(if $(BR2_ENABLE_DEBUG),,--release) \
  4367. 21: --target=$(RUSTC_TARGET_NAME) \
  4368. 22: --manifest-path=$(@D)/Cargo.toml
  4369. 23:
  4370. 24: define FOO_BUILD_CMDS
  4371. 25: $(TARGET_MAKE_ENV) $(FOO_CARGO_ENV) \
  4372. 26: cargo build $(FOO_CARGO_OPTS)
  4373. 27: endef
  4374. 28:
  4375. 29: define FOO_INSTALL_TARGET_CMDS
  4376. 30: $(INSTALL) -D -m 0755 $(@D)/$(FOO_BIN_DIR)/foo \
  4377. 31: $(TARGET_DIR)/usr/bin/foo
  4378. 32: endef
  4379. 33:
  4380. 34: $(eval $(generic-package))</pre><p>The Makefile starts with the definition of the standard variables for package
  4381. declaration (lines 7 to 11).</p><p>As seen in line 34, it is based on the
  4382. <a class="link" href="#generic-package-tutorial" title="18.5.1. generic-package tutorial"><code class="literal">generic-package</code> infrastructure</a>. So, it defines
  4383. the variables required by this particular infrastructure, where Cargo is
  4384. invoked:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4385. <code class="literal">FOO_BUILD_CMDS</code>: Cargo is invoked to perform the build. The options required
  4386. to configure the cross-compilation of the package are passed via
  4387. <code class="literal">FOO_CONF_OPTS</code>.
  4388. </li><li class="listitem">
  4389. <code class="literal">FOO_INSTALL_TARGET_CMDS</code>: The binary executable generated is installed on
  4390. the target.
  4391. </li></ul></div><p>In order to have Cargo available for the build, <code class="literal">FOO_DEPENDENCIES</code> needs to
  4392. contain <code class="literal">host-cargo</code>.</p><p>To sum it up, to add a new Cargo-based package, the Makefile example can be
  4393. copied verbatim then edited to replace all occurences of <code class="literal">FOO</code> with the
  4394. uppercase name of the new package and update the values of the standard
  4395. variables.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_about_dependencies_management"></a>18.16.3. About Dependencies Management</h3></div></div></div><p>A crate can depend on other libraries from crates.io or git repositories, listed
  4396. in its Cargo.toml file. Before starting a build, Cargo usually downloads
  4397. automatically them. This step can also be performed independently, via the
  4398. <code class="literal">cargo fetch</code> command.</p><p>Cargo maintains a local cache of the registry index and of git checkouts of the
  4399. crates, whose location is given by <code class="literal">$CARGO_HOME</code>. As seen in the package
  4400. Makefile example at line 15, this environment variable is set to
  4401. <code class="literal">$(HOST_DIR)/share/cargo</code>.</p><p>This dependency download mechanism is not convenient when performing an offline
  4402. build, as Cargo will fail to fetch the dependencies. In that case, it is advised
  4403. to generate a tarball of the dependencies using the <code class="literal">cargo vendor</code> and add it to
  4404. <code class="literal">FOO_EXTRA_DOWNLOADS</code>.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_go_packages"></a>18.17. Infrastructure for Go packages</h2></div></div></div><p>This infrastructure applies to Go packages that use the standard
  4405. build system and use bundled dependencies.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="golang-package-tutorial"></a>18.17.1. <code class="literal">golang-package</code> tutorial</h3></div></div></div><p>First, let’s see how to write a <code class="literal">.mk</code> file for a go package,
  4406. with an example :</p><pre class="screen">01: ################################################################################
  4407. 02: #
  4408. 03: # foo
  4409. 04: #
  4410. 05: ################################################################################
  4411. 06:
  4412. 07: FOO_VERSION = 1.0
  4413. 08: FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))
  4414. 09: FOO_LICENSE = BSD-3-Clause
  4415. 10: FOO_LICENSE_FILES = LICENSE
  4416. 11:
  4417. 12: $(eval $(golang-package))</pre><p>On line 7, we declare the version of the package.</p><p>On line 8, we declare the upstream location of the package, here
  4418. fetched from Github, since a large number of Go packages are hosted on
  4419. Github.</p><p>On line 9 and 10, we give licensing details about the package.</p><p>Finally, on line 12, we invoke the <code class="literal">golang-package</code> macro that
  4420. generates all the Makefile rules that actually allow the package to be
  4421. built.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="golang-package-reference"></a>18.17.2. <code class="literal">golang-package</code> reference</h3></div></div></div><p>In their <code class="literal">Config.in</code> file, packages using the <code class="literal">golang-package</code>
  4422. infrastructure should depend on <code class="literal">BR2_PACKAGE_HOST_GO_TARGET_ARCH_SUPPORTS</code>
  4423. because Buildroot will automatically add a dependency on <code class="literal">host-go</code>
  4424. to such packages.
  4425. If you need CGO support in your package, you must add a dependency on
  4426. <code class="literal">BR2_PACKAGE_HOST_GO_TARGET_CGO_LINKING_SUPPORTS</code>.</p><p>The main macro of the Go package infrastructure is
  4427. <code class="literal">golang-package</code>. It is similar to the <code class="literal">generic-package</code> macro. The
  4428. ability to build host packages is also available, with the
  4429. <code class="literal">host-golang-package</code> macro.
  4430. Host packages built by <code class="literal">host-golang-package</code> macro should depend on
  4431. BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.</p><p>Just like the generic infrastructure, the Go infrastructure works
  4432. by defining a number of variables before calling the <code class="literal">golang-package</code>.</p><p>All the package metadata information variables that exist in the
  4433. <a class="link" href="#generic-package-reference" title="18.5.2. generic-package reference">generic package infrastructure</a> also
  4434. exist in the Go infrastructure: <code class="literal">FOO_VERSION</code>, <code class="literal">FOO_SOURCE</code>,
  4435. <code class="literal">FOO_PATCH</code>, <code class="literal">FOO_SITE</code>, <code class="literal">FOO_SUBDIR</code>, <code class="literal">FOO_DEPENDENCIES</code>,
  4436. <code class="literal">FOO_LICENSE</code>, <code class="literal">FOO_LICENSE_FILES</code>, <code class="literal">FOO_INSTALL_STAGING</code>, etc.</p><p>Note that it is not necessary to add <code class="literal">host-go</code> in the
  4437. <code class="literal">FOO_DEPENDENCIES</code> variable of a package, since this basic dependency
  4438. is automatically added as needed by the Go package infrastructure.</p><p>A few additional variables, specific to the Go infrastructure, can
  4439. optionally be defined, depending on the package’s needs. Many of them
  4440. are only useful in very specific cases, typical packages will
  4441. therefore only use a few of them, or none.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4442. The package must specify its Go module name in the <code class="literal">FOO_GOMOD</code>
  4443. variable. If not specified, it defaults to
  4444. <code class="literal">URL-domain/1st-part-of-URL/2nd-part-of-URL</code>, e.g <code class="literal">FOO_GOMOD</code> will
  4445. take the value <code class="literal">github.com/bar/foo</code> for a package that specifies
  4446. <code class="literal">FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))</code>. The Go package
  4447. infrastructure will automatically generate a minimal <code class="literal">go.mod</code> file
  4448. in the package source tree if it doesn’t exist.
  4449. </li><li class="listitem">
  4450. <code class="literal">FOO_LDFLAGS</code> and <code class="literal">FOO_TAGS</code> can be used to pass respectively the
  4451. <code class="literal">LDFLAGS</code> or the <code class="literal">TAGS</code> to the <code class="literal">go</code> build command.
  4452. </li><li class="listitem"><p class="simpara">
  4453. <code class="literal">FOO_BUILD_TARGETS</code> can be used to pass the list of targets that
  4454. should be built. If <code class="literal">FOO_BUILD_TARGETS</code> is not specified, it
  4455. defaults to <code class="literal">.</code>. We then have two cases:
  4456. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  4457. <code class="literal">FOO_BUILD_TARGETS</code> is <code class="literal">.</code>. In this case, we assume only one binary
  4458. will be produced, and that by default we name it after the package
  4459. name. If that is not appropriate, the name of the produced binary
  4460. can be overridden using <code class="literal">FOO_BIN_NAME</code>.
  4461. </li><li class="listitem">
  4462. <code class="literal">FOO_BUILD_TARGETS</code> is not <code class="literal">.</code>. In this case, we iterate over the
  4463. values to build each target, and for each produced a binary that is
  4464. the non-directory component of the target. For example if
  4465. <code class="literal">FOO_BUILD_TARGETS = cmd/docker cmd/dockerd</code> the binaries produced
  4466. are <code class="literal">docker</code> and <code class="literal">dockerd</code>.
  4467. </li></ul></div></li><li class="listitem">
  4468. <code class="literal">FOO_INSTALL_BINS</code> can be used to pass the list of binaries that
  4469. should be installed in <code class="literal">/usr/bin</code> on the target. If
  4470. <code class="literal">FOO_INSTALL_BINS</code> is not specified, it defaults to the lower-case
  4471. name of package.
  4472. </li></ul></div><p>With the Go infrastructure, all the steps required to build and
  4473. install the packages are already defined, and they generally work well
  4474. for most Go-based packages. However, when required, it is still
  4475. possible to customize what is done in any particular step:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4476. By adding a post-operation hook (after extract, patch, configure,
  4477. build or install). See <a class="xref" href="#hooks" title="18.22. Hooks available in the various build steps">Section 18.22, “Hooks available in the various build steps”</a> for details.
  4478. </li><li class="listitem">
  4479. By overriding one of the steps. For example, even if the Go
  4480. infrastructure is used, if the package <code class="literal">.mk</code> file defines its own
  4481. <code class="literal">FOO_BUILD_CMDS</code> variable, it will be used instead of the default Go
  4482. one. However, using this method should be restricted to very
  4483. specific cases. Do not use it in the general case.
  4484. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_qmake_based_packages"></a>18.18. Infrastructure for QMake-based packages</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="qmake-package-tutorial"></a>18.18.1. <code class="literal">qmake-package</code> tutorial</h3></div></div></div><p>First, let’s see how to write a <code class="literal">.mk</code> file for a QMake-based package, with
  4485. an example :</p><pre class="screen">01: ################################################################################
  4486. 02: #
  4487. 03: # libfoo
  4488. 04: #
  4489. 05: ################################################################################
  4490. 06:
  4491. 07: LIBFOO_VERSION = 1.0
  4492. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  4493. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  4494. 10: LIBFOO_CONF_OPTS = QT_CONFIG+=bar QT_CONFIG-=baz
  4495. 11: LIBFOO_DEPENDENCIES = bar
  4496. 12:
  4497. 13: $(eval $(qmake-package))</pre><p>On line 7, we declare the version of the package.</p><p>On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  4498. recommended) and the location of the tarball on the Web. Buildroot
  4499. will automatically download the tarball from this location.</p><p>On line 10, we tell Buildroot what options to enable for libfoo.</p><p>On line 11, we tell Buildroot the dependencies of libfoo.</p><p>Finally, on line line 13, we invoke the <code class="literal">qmake-package</code>
  4500. macro that generates all the Makefile rules that actually allows the
  4501. package to be built.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="qmake-package-reference"></a>18.18.2. <code class="literal">qmake-package</code> reference</h3></div></div></div><p>The main macro of the QMake package infrastructure is <code class="literal">qmake-package</code>.
  4502. It is similar to the <code class="literal">generic-package</code> macro.</p><p>Just like the generic infrastructure, the QMake infrastructure works
  4503. by defining a number of variables before calling the <code class="literal">qmake-package</code>
  4504. macro.</p><p>First, all the package metadata information variables that exist in
  4505. the generic infrastructure also exist in the QMake infrastructure:
  4506. <code class="literal">LIBFOO_VERSION</code>, <code class="literal">LIBFOO_SOURCE</code>, <code class="literal">LIBFOO_PATCH</code>, <code class="literal">LIBFOO_SITE</code>,
  4507. <code class="literal">LIBFOO_SUBDIR</code>, <code class="literal">LIBFOO_DEPENDENCIES</code>, <code class="literal">LIBFOO_INSTALL_STAGING</code>,
  4508. <code class="literal">LIBFOO_INSTALL_TARGET</code>.</p><p>An additional variable, specific to the QMake infrastructure, can
  4509. also be defined.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4510. <code class="literal">LIBFOO_CONF_ENV</code>, to specify additional environment variables to
  4511. pass to the <code class="literal">qmake</code> script for the configuration step. By default, empty.
  4512. </li><li class="listitem">
  4513. <code class="literal">LIBFOO_CONF_OPTS</code>, to specify additional options to pass to the
  4514. <code class="literal">qmake</code> script for the configuration step. By default, empty.
  4515. </li><li class="listitem">
  4516. <code class="literal">LIBFOO_MAKE_ENV</code>, to specify additional environment variables to the
  4517. <code class="literal">make</code> command during the build and install steps. By default, empty.
  4518. </li><li class="listitem">
  4519. <code class="literal">LIBFOO_MAKE_OPTS</code>, to specify additional targets to pass to the
  4520. <code class="literal">make</code> command during the build step. By default, empty.
  4521. </li><li class="listitem">
  4522. <code class="literal">LIBFOO_INSTALL_STAGING_OPTS</code>, to specify additional targets to pass
  4523. to the <code class="literal">make</code> command during the staging installation step. By default,
  4524. <code class="literal">install</code>.
  4525. </li><li class="listitem">
  4526. <code class="literal">LIBFOO_INSTALL_TARGET_OPTS</code>, to specify additional targets to pass
  4527. to the <code class="literal">make</code> command during the target installation step. By default,
  4528. <code class="literal">install</code>.
  4529. </li><li class="listitem">
  4530. <code class="literal">LIBFOO_SYNC_HEADERS</code>, to run syncqt.pl before qmake. Some packages
  4531. need this to have a properly populated include directory before
  4532. running the build.
  4533. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_packages_building_kernel_modules"></a>18.19. Infrastructure for packages building kernel modules</h2></div></div></div><p>Buildroot offers a helper infrastructure to make it easy to write packages that
  4534. build and install Linux kernel modules. Some packages only contain a kernel
  4535. module, other packages contain programs and libraries in addition to kernel
  4536. modules. Buildroot’s helper infrastructure supports either case.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="kernel-module-tutorial"></a>18.19.1. <code class="literal">kernel-module</code> tutorial</h3></div></div></div><p>Let’s start with an example on how to prepare a simple package that only
  4537. builds a kernel module, and no other component:</p><pre class="screen">01: ################################################################################
  4538. 02: #
  4539. 03: # foo
  4540. 04: #
  4541. 05: ################################################################################
  4542. 06:
  4543. 07: FOO_VERSION = 1.2.3
  4544. 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
  4545. 09: FOO_SITE = http://www.foosoftware.org/download
  4546. 10: FOO_LICENSE = GPL-2.0
  4547. 11: FOO_LICENSE_FILES = COPYING
  4548. 12:
  4549. 13: $(eval $(kernel-module))
  4550. 14: $(eval $(generic-package))</pre><p>Lines 7-11 define the usual meta-data to specify the version, archive name,
  4551. remote URI where to find the package source, licensing information.</p><p>On line 13, we invoke the <code class="literal">kernel-module</code> helper infrastructure, that
  4552. generates all the appropriate Makefile rules and variables to build
  4553. that kernel module.</p><p>Finally, on line 14, we invoke the
  4554. <a class="link" href="#generic-package-tutorial" title="18.5.1. generic-package tutorial"><code class="literal">generic-package</code> infrastructure</a>.</p><p>The dependency on <code class="literal">linux</code> is automatically added, so it is not needed to
  4555. specify it in <code class="literal">FOO_DEPENDENCIES</code>.</p><p>What you may have noticed is that, unlike other package infrastructures,
  4556. we explicitly invoke a second infrastructure. This allows a package to
  4557. build a kernel module, but also, if needed, use any one of other package
  4558. infrastructures to build normal userland components (libraries,
  4559. executables…). Using the <code class="literal">kernel-module</code> infrastructure on its own is
  4560. not sufficient; another package infrastructure <span class="strong"><strong>must</strong></span> be used.</p><p>Let’s look at a more complex example:</p><pre class="screen">01: ################################################################################
  4561. 02: #
  4562. 03: # foo
  4563. 04: #
  4564. 05: ################################################################################
  4565. 06:
  4566. 07: FOO_VERSION = 1.2.3
  4567. 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
  4568. 09: FOO_SITE = http://www.foosoftware.org/download
  4569. 10: FOO_LICENSE = GPL-2.0
  4570. 11: FOO_LICENSE_FILES = COPYING
  4571. 12:
  4572. 13: FOO_MODULE_SUBDIRS = driver/base
  4573. 14: FOO_MODULE_MAKE_OPTS = KVERSION=$(LINUX_VERSION_PROBED)
  4574. 15:
  4575. 16: ifeq ($(BR2_PACKAGE_LIBBAR),y)
  4576. 17: FOO_DEPENDENCIES = libbar
  4577. 18: FOO_CONF_OPTS = --enable-bar
  4578. 19: FOO_MODULE_SUBDIRS += driver/bar
  4579. 20: else
  4580. 21: FOO_CONF_OPTS = --disable-bar
  4581. 22: endif
  4582. 23:
  4583. 24: $(eval $(kernel-module))
  4584. 26: $(eval $(autotools-package))</pre><p>Here, we see that we have an autotools-based package, that also builds
  4585. the kernel module located in sub-directory <code class="literal">driver/base</code> and, if libbar
  4586. is enabled, the kernel module located in sub-directory <code class="literal">driver/bar</code>, and
  4587. defines the variable <code class="literal">KVERSION</code> to be passed to the Linux buildsystem
  4588. when building the module(s).</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="kernel-module-reference"></a>18.19.2. <code class="literal">kernel-module</code> reference</h3></div></div></div><p>The main macro for the kernel module infrastructure is <code class="literal">kernel-module</code>.
  4589. Unlike other package infrastructures, it is not stand-alone, and requires
  4590. any of the other <code class="literal">*-package</code> macros be called after it.</p><p>The <code class="literal">kernel-module</code> macro defines post-build and post-target-install
  4591. hooks to build the kernel modules. If the package’s <code class="literal">.mk</code> needs access
  4592. to the built kernel modules, it should do so in a post-build hook,
  4593. <span class="strong"><strong>registered after</strong></span> the call to <code class="literal">kernel-module</code>. Similarly, if the
  4594. package’s <code class="literal">.mk</code> needs access to the kernel module after it has been
  4595. installed, it should do so in a post-install hook, <span class="strong"><strong>registered after</strong></span>
  4596. the call to <code class="literal">kernel-module</code>. Here’s an example:</p><pre class="screen">$(eval $(kernel-module))
  4597. define FOO_DO_STUFF_WITH_KERNEL_MODULE
  4598. # Do something with it...
  4599. endef
  4600. FOO_POST_BUILD_HOOKS += FOO_DO_STUFF_WITH_KERNEL_MODULE
  4601. $(eval $(generic-package))</pre><p>Finally, unlike the other package infrastructures, there is no
  4602. <code class="literal">host-kernel-module</code> variant to build a host kernel module.</p><p>The following additional variables can optionally be defined to further
  4603. configure the build of the kernel module:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4604. <code class="literal">FOO_MODULE_SUBDIRS</code> may be set to one or more sub-directories (relative
  4605. to the package source top-directory) where the kernel module sources are.
  4606. If empty or not set, the sources for the kernel module(s) are considered
  4607. to be located at the top of the package source tree.
  4608. </li><li class="listitem">
  4609. <code class="literal">FOO_MODULE_MAKE_OPTS</code> may be set to contain extra variable definitions
  4610. to pass to the Linux buildsystem.
  4611. </li></ul></div><p><a id="kernel-variables"></a>You may also reference (but you may <span class="strong"><strong>not</strong></span> set!) those variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4612. <code class="literal">LINUX_DIR</code> contains the path to where the Linux kernel has been
  4613. extracted and built.
  4614. </li><li class="listitem">
  4615. <code class="literal">LINUX_VERSION</code> contains the version string as configured by the user.
  4616. </li><li class="listitem">
  4617. <code class="literal">LINUX_VERSION_PROBED</code> contains the real version string of the kernel,
  4618. retrieved with running <code class="literal">make -C $(LINUX_DIR) kernelrelease</code>
  4619. </li><li class="listitem">
  4620. <code class="literal">KERNEL_ARCH</code> contains the name of the current architecture, like <code class="literal">arm</code>,
  4621. <code class="literal">mips</code>…
  4622. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_asciidoc_documents"></a>18.20. Infrastructure for asciidoc documents</h2></div></div></div><p><a id="asciidoc-documents-tutorial"></a>The Buildroot manual, which you are currently reading, is entirely written
  4623. using the <a class="ulink" href="http://asciidoc.org/" target="_top">AsciiDoc</a> mark-up syntax. The manual is then
  4624. rendered to many formats:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4625. html
  4626. </li><li class="listitem">
  4627. split-html
  4628. </li><li class="listitem">
  4629. pdf
  4630. </li><li class="listitem">
  4631. epub
  4632. </li><li class="listitem">
  4633. text
  4634. </li></ul></div><p>Although Buildroot only contains one document written in AsciiDoc, there
  4635. is, as for packages, an infrastructure for rendering documents using the
  4636. AsciiDoc syntax.</p><p>Also as for packages, the AsciiDoc infrastructure is available from a
  4637. <a class="link" href="#outside-br-custom" title="9.2. Keeping customizations outside of Buildroot">br2-external tree</a>. This allows documentation for
  4638. a br2-external tree to match the Buildroot documentation, as it will be
  4639. rendered to the same formats and use the same layout and theme.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_literal_asciidoc_document_literal_tutorial"></a>18.20.1. <code class="literal">asciidoc-document</code> tutorial</h3></div></div></div><p>Whereas package infrastructures are suffixed with <code class="literal">-package</code>, the document
  4640. infrastructures are suffixed with <code class="literal">-document</code>. So, the AsciiDoc infrastructure
  4641. is named <code class="literal">asciidoc-document</code>.</p><p>Here is an example to render a simple AsciiDoc document.</p><pre class="screen">01: ################################################################################
  4642. 02: #
  4643. 03: # foo-document
  4644. 04: #
  4645. 05: ################################################################################
  4646. 06:
  4647. 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
  4648. 08: $(eval $(call asciidoc-document))</pre><p>On line 7, the Makefile declares what the sources of the document are.
  4649. Currently, it is expected that the document’s sources are only local;
  4650. Buildroot will not attempt to download anything to render a document.
  4651. Thus, you must indicate where the sources are. Usually, the string
  4652. above is sufficient for a document with no sub-directory structure.</p><p>On line 8, we call the <code class="literal">asciidoc-document</code> function, which generates all
  4653. the Makefile code necessary to render the document.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_literal_asciidoc_document_literal_reference"></a>18.20.2. <code class="literal">asciidoc-document</code> reference</h3></div></div></div><p>The list of variables that can be set in a <code class="literal">.mk</code> file to give metadata
  4654. information is (assuming the document name is <code class="literal">foo</code>) :</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4655. <code class="literal">FOO_SOURCES</code>, mandatory, defines the source files for the document.
  4656. </li><li class="listitem">
  4657. <code class="literal">FOO_RESOURCES</code>, optional, may contain a space-separated list of paths
  4658. to one or more directories containing so-called resources (like CSS or
  4659. images). By default, empty.
  4660. </li><li class="listitem">
  4661. <code class="literal">FOO_DEPENDENCIES</code>, optional, the list of packages (most probably,
  4662. host-packages) that must be built before building this document.
  4663. </li></ul></div><p>There are also additional hooks (see <a class="xref" href="#hooks" title="18.22. Hooks available in the various build steps">Section 18.22, “Hooks available in the various build steps”</a> for general information
  4664. on hooks), that a document may set to define extra actions to be done at
  4665. various steps:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4666. <code class="literal">FOO_POST_RSYNC_HOOKS</code> to run additional commands after the sources
  4667. have been copied by Buildroot. This can for example be used to
  4668. generate part of the manual with information extracted from the
  4669. tree. As an example, Buildroot uses this hook to generate the tables
  4670. in the appendices.
  4671. </li><li class="listitem">
  4672. <code class="literal">FOO_CHECK_DEPENDENCIES_HOOKS</code> to run additional tests on required
  4673. components to generate the document. In AsciiDoc, it is possible to
  4674. call filters, that is, programs that will parse an AsciiDoc block and
  4675. render it appropriately (e.g. <a class="ulink" href="http://ditaa.sourceforge.net/" target="_top">ditaa</a> or
  4676. <a class="ulink" href="https://pythonhosted.org/aafigure/" target="_top">aafigure</a>).
  4677. </li><li class="listitem">
  4678. <code class="literal">FOO_CHECK_DEPENDENCIES_&lt;FMT&gt;_HOOKS</code>, to run additional tests for
  4679. the specified format <code class="literal">&lt;FMT&gt;</code> (see the list of rendered formats, above).
  4680. </li></ul></div><p>Here is a complete example that uses all variables and all hooks:</p><pre class="screen">01: ################################################################################
  4681. 02: #
  4682. 03: # foo-document
  4683. 04: #
  4684. 05: ################################################################################
  4685. 06:
  4686. 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
  4687. 08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
  4688. 09:
  4689. 10: define FOO_GEN_EXTRA_DOC
  4690. 11: /path/to/generate-script --outdir=$(@D)
  4691. 12: endef
  4692. 13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
  4693. 14:
  4694. 15: define FOO_CHECK_MY_PROG
  4695. 16: if ! which my-prog &gt;/dev/null 2&gt;&amp;1; then \
  4696. 17: echo "You need my-prog to generate the foo document"; \
  4697. 18: exit 1; \
  4698. 19: fi
  4699. 20: endef
  4700. 21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
  4701. 22:
  4702. 23: define FOO_CHECK_MY_OTHER_PROG
  4703. 24: if ! which my-other-prog &gt;/dev/null 2&gt;&amp;1; then \
  4704. 25: echo "You need my-other-prog to generate the foo document as PDF"; \
  4705. 26: exit 1; \
  4706. 27: fi
  4707. 28: endef
  4708. 29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
  4709. 30:
  4710. 31: $(eval $(call asciidoc-document))</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="linux-kernel-specific-infra"></a>18.21. Infrastructure specific to the Linux kernel package</h2></div></div></div><p>The Linux kernel package can use some specific infrastructures based on package
  4711. hooks for building Linux kernel tools or/and building Linux kernel extensions.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="linux-kernel-tools"></a>18.21.1. linux-kernel-tools</h3></div></div></div><p>Buildroot offers a helper infrastructure to build some userspace tools
  4712. for the target available within the Linux kernel sources. Since their
  4713. source code is part of the kernel source code, a special package,
  4714. <code class="literal">linux-tools</code>, exists and re-uses the sources of the Linux kernel that
  4715. runs on the target.</p><p>Let’s look at an example of a Linux tool. For a new Linux tool named
  4716. <code class="literal">foo</code>, create a new menu entry in the existing
  4717. <code class="literal">package/linux-tools/Config.in</code>. This file will contain the option
  4718. descriptions related to each kernel tool that will be used and
  4719. displayed in the configuration tool. It would basically look like:</p><pre class="screen">01: config BR2_PACKAGE_LINUX_TOOLS_FOO
  4720. 02: bool "foo"
  4721. 03: select BR2_PACKAGE_LINUX_TOOLS
  4722. 04: help
  4723. 05: This is a comment that explains what foo kernel tool is.
  4724. 06:
  4725. 07: http://foosoftware.org/foo/</pre><p>The name of the option starts with the prefix <code class="literal">BR2_PACKAGE_LINUX_TOOLS_</code>,
  4726. followed by the uppercase name of the tool (like is done for packages).</p><p><strong>Note. </strong>Unlike other packages, the <code class="literal">linux-tools</code> package options appear in the
  4727. <code class="literal">linux</code> kernel menu, under the <code class="literal">Linux Kernel Tools</code> sub-menu, not under
  4728. the <code class="literal">Target packages</code> main menu.</p><p>Then for each linux tool, add a new <code class="literal">.mk.in</code> file named
  4729. <code class="literal">package/linux-tools/linux-tool-foo.mk.in</code>. It would basically look like:</p><pre class="screen">01: ################################################################################
  4730. 02: #
  4731. 03: # foo
  4732. 04: #
  4733. 05: ################################################################################
  4734. 06:
  4735. 07: LINUX_TOOLS += foo
  4736. 08:
  4737. 09: FOO_DEPENDENCIES = libbbb
  4738. 10:
  4739. 11: define FOO_BUILD_CMDS
  4740. 12: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools foo
  4741. 13: endef
  4742. 14:
  4743. 15: define FOO_INSTALL_STAGING_CMDS
  4744. 16: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
  4745. 17: DESTDIR=$(STAGING_DIR) \
  4746. 18: foo_install
  4747. 19: endef
  4748. 20:
  4749. 21: define FOO_INSTALL_TARGET_CMDS
  4750. 22: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
  4751. 23: DESTDIR=$(TARGET_DIR) \
  4752. 24: foo_install
  4753. 25: endef</pre><p>On line 7, we register the Linux tool <code class="literal">foo</code> to the list of available
  4754. Linux tools.</p><p>On line 9, we specify the list of dependencies this tool relies on. These
  4755. dependencies are added to the Linux package dependencies list only when the
  4756. <code class="literal">foo</code> tool is selected.</p><p>The rest of the Makefile, lines 11-25 defines what should be done at the
  4757. different steps of the Linux tool build process like for a
  4758. <a class="link" href="#generic-package-tutorial" title="18.5.1. generic-package tutorial"><code class="literal">generic package</code></a>. They will actually be
  4759. used only when the <code class="literal">foo</code> tool is selected. The only supported commands are
  4760. <code class="literal">_BUILD_CMDS</code>, <code class="literal">_INSTALL_STAGING_CMDS</code> and <code class="literal">_INSTALL_TARGET_CMDS</code>.</p><p><strong>Note. </strong>One <span class="strong"><strong>must not</strong></span> call <code class="literal">$(eval $(generic-package))</code> or any other
  4761. package infrastructure! Linux tools are not packages by themselves,
  4762. they are part of the <code class="literal">linux-tools</code> package.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="linux-kernel-ext"></a>18.21.2. linux-kernel-extensions</h3></div></div></div><p>Some packages provide new features that require the Linux kernel tree
  4763. to be modified. This can be in the form of patches to be applied on
  4764. the kernel tree, or in the form of new files to be added to the
  4765. tree. The Buildroot’s Linux kernel extensions infrastructure provides
  4766. a simple solution to automatically do this, just after the kernel
  4767. sources are extracted and before the kernel patches are
  4768. applied. Examples of extensions packaged using this mechanism are the
  4769. real-time extensions Xenomai and RTAI, as well as the set of
  4770. out-of-tree LCD screens drivers <code class="literal">fbtft</code>.</p><p>Let’s look at an example on how to add a new Linux extension <code class="literal">foo</code>.</p><p>First, create the package <code class="literal">foo</code> that provides the extension: this
  4771. package is a standard package; see the previous chapters on how to
  4772. create such a package. This package is in charge of downloading the
  4773. sources archive, checking the hash, defining the licence informations
  4774. and building user space tools if any.</p><p>Then create the <span class="emphasis"><em>Linux extension</em></span> proper: create a new menu entry in
  4775. the existing <code class="literal">linux/Config.ext.in</code>. This file contains the option
  4776. descriptions related to each kernel extension that will be used and
  4777. displayed in the configuration tool. It would basically look like:</p><pre class="screen">01: config BR2_LINUX_KERNEL_EXT_FOO
  4778. 02: bool "foo"
  4779. 03: help
  4780. 04: This is a comment that explains what foo kernel extension is.
  4781. 05:
  4782. 06: http://foosoftware.org/foo/</pre><p>Then for each linux extension, add a new <code class="literal">.mk</code> file named
  4783. <code class="literal">linux/linux-ext-foo.mk</code>. It should basically contain:</p><pre class="screen">01: ################################################################################
  4784. 02: #
  4785. 03: # foo
  4786. 04: #
  4787. 05: ################################################################################
  4788. 06:
  4789. 07: LINUX_EXTENSIONS += foo
  4790. 08:
  4791. 09: define FOO_PREPARE_KERNEL
  4792. 10: $(FOO_DIR)/prepare-kernel-tree.sh --linux-dir=$(@D)
  4793. 11: endef</pre><p>On line 7, we add the Linux extension <code class="literal">foo</code> to the list of available
  4794. Linux extensions.</p><p>On line 9-11, we define what should be done by the extension to modify
  4795. the Linux kernel tree; this is specific to the linux extension and can
  4796. use the variables defined by the <code class="literal">foo</code> package, like: <code class="literal">$(FOO_DIR)</code> or
  4797. <code class="literal">$(FOO_VERSION)</code>… as well as all the Linux variables, like:
  4798. <code class="literal">$(LINUX_VERSION)</code> or <code class="literal">$(LINUX_VERSION_PROBED)</code>, <code class="literal">$(KERNEL_ARCH)</code>…
  4799. See the <a class="link" href="#kernel-variables">definition of those kernel variables</a>.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="hooks"></a>18.22. Hooks available in the various build steps</h2></div></div></div><p>The generic infrastructure (and as a result also the derived autotools
  4800. and cmake infrastructures) allow packages to specify hooks.
  4801. These define further actions to perform after existing steps.
  4802. Most hooks aren’t really useful for generic packages, since the <code class="literal">.mk</code>
  4803. file already has full control over the actions performed in each step
  4804. of the package construction.</p><p>The following hook points are available:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4805. <code class="literal">LIBFOO_PRE_DOWNLOAD_HOOKS</code>
  4806. </li><li class="listitem">
  4807. <code class="literal">LIBFOO_POST_DOWNLOAD_HOOKS</code>
  4808. </li><li class="listitem">
  4809. <code class="literal">LIBFOO_PRE_EXTRACT_HOOKS</code>
  4810. </li><li class="listitem">
  4811. <code class="literal">LIBFOO_POST_EXTRACT_HOOKS</code>
  4812. </li><li class="listitem">
  4813. <code class="literal">LIBFOO_PRE_RSYNC_HOOKS</code>
  4814. </li><li class="listitem">
  4815. <code class="literal">LIBFOO_POST_RSYNC_HOOKS</code>
  4816. </li><li class="listitem">
  4817. <code class="literal">LIBFOO_PRE_PATCH_HOOKS</code>
  4818. </li><li class="listitem">
  4819. <code class="literal">LIBFOO_POST_PATCH_HOOKS</code>
  4820. </li><li class="listitem">
  4821. <code class="literal">LIBFOO_PRE_CONFIGURE_HOOKS</code>
  4822. </li><li class="listitem">
  4823. <code class="literal">LIBFOO_POST_CONFIGURE_HOOKS</code>
  4824. </li><li class="listitem">
  4825. <code class="literal">LIBFOO_PRE_BUILD_HOOKS</code>
  4826. </li><li class="listitem">
  4827. <code class="literal">LIBFOO_POST_BUILD_HOOKS</code>
  4828. </li><li class="listitem">
  4829. <code class="literal">LIBFOO_PRE_INSTALL_HOOKS</code> (for host packages only)
  4830. </li><li class="listitem">
  4831. <code class="literal">LIBFOO_POST_INSTALL_HOOKS</code> (for host packages only)
  4832. </li><li class="listitem">
  4833. <code class="literal">LIBFOO_PRE_INSTALL_STAGING_HOOKS</code> (for target packages only)
  4834. </li><li class="listitem">
  4835. <code class="literal">LIBFOO_POST_INSTALL_STAGING_HOOKS</code> (for target packages only)
  4836. </li><li class="listitem">
  4837. <code class="literal">LIBFOO_PRE_INSTALL_TARGET_HOOKS</code> (for target packages only)
  4838. </li><li class="listitem">
  4839. <code class="literal">LIBFOO_POST_INSTALL_TARGET_HOOKS</code> (for target packages only)
  4840. </li><li class="listitem">
  4841. <code class="literal">LIBFOO_PRE_INSTALL_IMAGES_HOOKS</code>
  4842. </li><li class="listitem">
  4843. <code class="literal">LIBFOO_POST_INSTALL_IMAGES_HOOKS</code>
  4844. </li><li class="listitem">
  4845. <code class="literal">LIBFOO_PRE_LEGAL_INFO_HOOKS</code>
  4846. </li><li class="listitem">
  4847. <code class="literal">LIBFOO_POST_LEGAL_INFO_HOOKS</code>
  4848. </li></ul></div><p>These variables are <span class="emphasis"><em>lists</em></span> of variable names containing actions to be
  4849. performed at this hook point. This allows several hooks to be
  4850. registered at a given hook point. Here is an example:</p><pre class="screen">define LIBFOO_POST_PATCH_FIXUP
  4851. action1
  4852. action2
  4853. endef
  4854. LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP</pre><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="hooks-rsync"></a>18.22.1. Using the <code class="literal">POST_RSYNC</code> hook</h3></div></div></div><p>The <code class="literal">POST_RSYNC</code> hook is run only for packages that use a local source,
  4855. either through the <code class="literal">local</code> site method or the <code class="literal">OVERRIDE_SRCDIR</code>
  4856. mechanism. In this case, package sources are copied using <code class="literal">rsync</code> from
  4857. the local location into the buildroot build directory. The <code class="literal">rsync</code>
  4858. command does not copy all files from the source directory, though.
  4859. Files belonging to a version control system, like the directories
  4860. <code class="literal">.git</code>, <code class="literal">.hg</code>, etc. are not copied. For most packages this is
  4861. sufficient, but a given package can perform additional actions using
  4862. the <code class="literal">POST_RSYNC</code> hook.</p><p>In principle, the hook can contain any command you want. One specific
  4863. use case, though, is the intentional copying of the version control
  4864. directory using <code class="literal">rsync</code>. The <code class="literal">rsync</code> command you use in the hook can, among
  4865. others, use the following variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4866. <code class="literal">$(SRCDIR)</code>: the path to the overridden source directory
  4867. </li><li class="listitem">
  4868. <code class="literal">$(@D)</code>: the path to the build directory
  4869. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_target_finalize_hook"></a>18.22.2. Target-finalize hook</h3></div></div></div><p>Packages may also register hooks in <code class="literal">LIBFOO_TARGET_FINALIZE_HOOKS</code>.
  4870. These hooks are run after all packages are built, but before the
  4871. filesystem images are generated. They are seldom used, and your
  4872. package probably do not need them.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_gettext_integration_and_interaction_with_packages"></a>18.23. Gettext integration and interaction with packages</h2></div></div></div><p>Many packages that support internationalization use the gettext
  4873. library. Dependencies for this library are fairly complicated and
  4874. therefore, deserve some explanation.</p><p>The <span class="emphasis"><em>glibc</em></span> C library integrates a full-blown implementation of
  4875. <span class="emphasis"><em>gettext</em></span>, supporting translation. Native Language Support is
  4876. therefore built-in in <span class="emphasis"><em>glibc</em></span>.</p><p>On the other hand, the <span class="emphasis"><em>uClibc</em></span> and <span class="emphasis"><em>musl</em></span> C libraries only provide a
  4877. stub implementation of the gettext functionality, which allows to
  4878. compile libraries and programs using gettext functions, but without
  4879. providing the translation capabilities of a full-blown gettext
  4880. implementation. With such C libraries, if real Native Language Support
  4881. is necessary, it can be provided by the <code class="literal">libintl</code> library of the
  4882. <code class="literal">gettext</code> package.</p><p>Due to this, and in order to make sure that Native Language Support is
  4883. properly handled, packages in Buildroot that can use NLS support
  4884. should:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
  4885. Ensure NLS support is enabled when <code class="literal">BR2_SYSTEM_ENABLE_NLS=y</code>. This
  4886. is done automatically for <span class="emphasis"><em>autotools</em></span> packages and therefore should
  4887. only be done for packages using other package infrastructures.
  4888. </li><li class="listitem">
  4889. Add <code class="literal">$(TARGET_NLS_DEPENDENCIES)</code> to the package
  4890. <code class="literal">&lt;pkg&gt;_DEPENDENCIES</code> variable. This addition should be done
  4891. unconditionally: the value of this variable is automatically
  4892. adjusted by the core infrastructure to contain the relevant list of
  4893. packages. If NLS support is disabled, this variable is empty. If
  4894. NLS support is enabled, this variable contains <code class="literal">host-gettext</code> so
  4895. that tools needed to compile translation files are available on the
  4896. host. In addition, if <span class="emphasis"><em>uClibc</em></span> or <span class="emphasis"><em>musl</em></span> are used, this variable
  4897. also contains <code class="literal">gettext</code> in order to get the full-blown <span class="emphasis"><em>gettext</em></span>
  4898. implementation.
  4899. </li><li class="listitem">
  4900. If needed, add <code class="literal">$(TARGET_NLS_LIBS)</code> to the linker flags, so that
  4901. the package gets linked with <code class="literal">libintl</code>. This is generally not
  4902. needed with <span class="emphasis"><em>autotools</em></span> packages as they usually detect
  4903. automatically that they should link with <code class="literal">libintl</code>. However,
  4904. packages using other build systems, or problematic autotools-based
  4905. packages may need this. <code class="literal">$(TARGET_NLS_LIBS)</code> should be added
  4906. unconditionally to the linker flags, as the core automatically
  4907. makes it empty or defined to <code class="literal">-lintl</code> depending on the
  4908. configuration.
  4909. </li></ol></div><p>No changes should be made to the <code class="literal">Config.in</code> file to support NLS.</p><p>Finally, certain packages need some gettext utilities on the target,
  4910. such as the <code class="literal">gettext</code> program itself, which allows to retrieve
  4911. translated strings, from the command line. In such a case, the package
  4912. should:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4913. use <code class="literal">select BR2_PACKAGE_GETTEXT</code> in their <code class="literal">Config.in</code> file,
  4914. indicating in a comment above that it’s a runtime dependency only.
  4915. </li><li class="listitem">
  4916. not add any <code class="literal">gettext</code> dependency in the <code class="literal">DEPENDENCIES</code> variable of
  4917. their <code class="literal">.mk</code> file.
  4918. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_tips_and_tricks"></a>18.24. Tips and tricks</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="package-name-variable-relation"></a>18.24.1. Package name, config entry name and makefile variable relationship</h3></div></div></div><p>In Buildroot, there is some relationship between:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4919. the <span class="emphasis"><em>package name</em></span>, which is the package directory name (and the
  4920. name of the <code class="literal">*.mk</code> file);
  4921. </li><li class="listitem">
  4922. the config entry name that is declared in the <code class="literal">Config.in</code> file;
  4923. </li><li class="listitem">
  4924. the makefile variable prefix.
  4925. </li></ul></div><p>It is mandatory to maintain consistency between these elements,
  4926. using the following rules:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4927. the package directory and the <code class="literal">*.mk</code> name are the <span class="emphasis"><em>package name</em></span>
  4928. itself (e.g.: <code class="literal">package/foo-bar_boo/foo-bar_boo.mk</code>);
  4929. </li><li class="listitem">
  4930. the <span class="emphasis"><em>make</em></span> target name is the <span class="emphasis"><em>package name</em></span> itself (e.g.:
  4931. <code class="literal">foo-bar_boo</code>);
  4932. </li><li class="listitem">
  4933. the config entry is the upper case <span class="emphasis"><em>package name</em></span> with <code class="literal">.</code> and <code class="literal">-</code>
  4934. characters substituted with <code class="literal">_</code>, prefixed with <code class="literal">BR2_PACKAGE_</code> (e.g.:
  4935. <code class="literal">BR2_PACKAGE_FOO_BAR_BOO</code>);
  4936. </li><li class="listitem">
  4937. the <code class="literal">*.mk</code> file variable prefix is the upper case <span class="emphasis"><em>package name</em></span>
  4938. with <code class="literal">.</code> and <code class="literal">-</code> characters substituted with <code class="literal">_</code> (e.g.:
  4939. <code class="literal">FOO_BAR_BOO_VERSION</code>).
  4940. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="check-package"></a>18.24.2. How to check the coding style</h3></div></div></div><p>Buildroot provides a script in <code class="literal">utils/check-package</code> that checks new or
  4941. changed files for coding style. It is not a complete language validator,
  4942. but it catches many common mistakes. It is meant to run in the actual
  4943. files you created or modified, before creating the patch for submission.</p><p>This script can be used for packages, filesystem makefiles, Config.in
  4944. files, etc. It does not check the files defining the package
  4945. infrastructures and some other files containing similar common code.</p><p>To use it, run the <code class="literal">check-package</code> script, by telling which files you
  4946. created or changed:</p><pre class="screen">$ ./utils/check-package package/new-package/*</pre><p>If you have the <code class="literal">utils</code> directory in your path you can also run:</p><pre class="screen">$ cd package/new-package/
  4947. $ check-package *</pre><p>The tool can also be used for packages in a br2-external:</p><pre class="screen">$ check-package -b /path/to/br2-ext-tree/package/my-package/*</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="testing-package"></a>18.24.3. How to test your package</h3></div></div></div><p>Once you have added your new package, it is important that you test it
  4948. under various conditions: does it build for all architectures? Does it
  4949. build with the different C libraries? Does it need threads, NPTL? And
  4950. so on…</p><p>Buildroot runs <a class="ulink" href="http://autobuild.buildroot.org/" target="_top">autobuilders</a> which
  4951. continuously test random configurations. However, these only build the
  4952. <code class="literal">master</code> branch of the git tree, and your new fancy package is not yet
  4953. there.</p><p>Buildroot provides a script in <code class="literal">utils/test-pkg</code> that uses the same base
  4954. configurations as used by the autobuilders so you can test your package
  4955. in the same conditions.</p><p>First, create a config snippet that contains all the necessary options
  4956. needed to enable your package, but without any architecture or toolchain
  4957. option. For example, let’s create a config snippet that just enables
  4958. <code class="literal">libcurl</code>, without any TLS backend:</p><pre class="screen">$ cat libcurl.config
  4959. BR2_PACKAGE_LIBCURL=y</pre><p>If your package needs more configuration options, you can add them to the
  4960. config snippet. For example, here’s how you would test <code class="literal">libcurl</code> with
  4961. <code class="literal">openssl</code> as a TLS backend and the <code class="literal">curl</code> program:</p><pre class="screen">$ cat libcurl.config
  4962. BR2_PACKAGE_LIBCURL=y
  4963. BR2_PACKAGE_LIBCURL_CURL=y
  4964. BR2_PACKAGE_OPENSSL=y</pre><p>Then run the <code class="literal">test-pkg</code> script, by telling it what config snippet to use
  4965. and what package to test:</p><pre class="screen">$ ./utils/test-pkg -c libcurl.config -p libcurl</pre><p>By default, <code class="literal">test-pkg</code> will build your package against a subset of the
  4966. toolchains used by the autobuilders, which has been selected by the
  4967. Buildroot developers as being the most useful and representative
  4968. subset. If you want to test all toolchains, pass the <code class="literal">-a</code> option. Note
  4969. that in any case, internal toolchains are excluded as they take too
  4970. long to build.</p><p>The output lists all toolchains that are tested and the corresponding
  4971. result (excerpt, results are fake):</p><pre class="screen">$ ./utils/test-pkg -c libcurl.config -p libcurl
  4972. armv5-ctng-linux-gnueabi [ 1/11]: OK
  4973. armv7-ctng-linux-gnueabihf [ 2/11]: OK
  4974. br-aarch64-glibc [ 3/11]: SKIPPED
  4975. br-arcle-hs38 [ 4/11]: SKIPPED
  4976. br-arm-basic [ 5/11]: FAILED
  4977. br-arm-cortex-a9-glibc [ 6/11]: OK
  4978. br-arm-cortex-a9-musl [ 7/11]: FAILED
  4979. br-arm-cortex-m4-full [ 8/11]: OK
  4980. br-arm-full [ 9/11]: OK
  4981. br-arm-full-nothread [10/11]: FAILED
  4982. br-arm-full-static [11/11]: OK
  4983. 11 builds, 2 skipped, 2 build failed, 1 legal-info failed</pre><p>The results mean:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  4984. <code class="literal">OK</code>: the build was successful.
  4985. </li><li class="listitem">
  4986. <code class="literal">SKIPPED</code>: one or more configuration options listed in the config
  4987. snippet were not present in the final configuration. This is due to
  4988. options having dependencies not satisfied by the toolchain, such as
  4989. for example a package that <code class="literal">depends on BR2_USE_MMU</code> with a noMMU
  4990. toolchain. The missing options are reported in <code class="literal">missing.config</code> in
  4991. the output build directory (<code class="literal">~/br-test-pkg/TOOLCHAIN_NAME/</code> by
  4992. default).
  4993. </li><li class="listitem"><p class="simpara">
  4994. <code class="literal">FAILED</code>: the build failed. Inspect the <code class="literal">logfile</code> file in the output
  4995. build directory to see what went wrong:
  4996. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  4997. the actual build failed,
  4998. </li><li class="listitem">
  4999. the legal-info failed,
  5000. </li><li class="listitem">
  5001. one of the preliminary steps (downloading the config file, applying
  5002. the configuration, running <code class="literal">dirclean</code> for the package) failed.
  5003. </li></ul></div></li></ul></div><p>When there are failures, you can just re-run the script with the same
  5004. options (after you fixed your package); the script will attempt to
  5005. re-build the package specified with <code class="literal">-p</code> for all toolchains, without
  5006. the need to re-build all the dependencies of that package.</p><p>The <code class="literal">test-pkg</code> script accepts a few options, for which you can get some
  5007. help by running:</p><pre class="screen">$ ./utils/test-pkg -h</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="github-download-url"></a>18.24.4. How to add a package from GitHub</h3></div></div></div><p>Packages on GitHub often don’t have a download area with release tarballs.
  5008. However, it is possible to download tarballs directly from the repository
  5009. on GitHub. As GitHub is known to have changed download mechanisms in the
  5010. past, the <span class="emphasis"><em>github</em></span> helper function should be used as shown below.</p><pre class="screen"># Use a tag or a full commit ID
  5011. FOO_VERSION = 1.0
  5012. FOO_SITE = $(call github,&lt;user&gt;,&lt;package&gt;,v$(FOO_VERSION))</pre><div class="itemizedlist"><p class="title"><strong>Notes</strong></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5013. The FOO_VERSION can either be a tag or a commit ID.
  5014. </li><li class="listitem">
  5015. The tarball name generated by github matches the default one from
  5016. Buildroot (e.g.: <code class="literal">foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz</code>),
  5017. so it is not necessary to specify it in the <code class="literal">.mk</code> file.
  5018. </li><li class="listitem">
  5019. When using a commit ID as version, you should use the full 40 hex characters.
  5020. </li><li class="listitem">
  5021. When the tag contains a prefix such as <code class="literal">v</code> in <code class="literal">v1.0</code>, then the
  5022. <code class="literal">VERSION</code> variable should contain just <code class="literal">1.0</code>, and the <code class="literal">v</code> should be
  5023. added directly in the <code class="literal">SITE</code> variable, as illustrated above. This
  5024. ensures that the <code class="literal">VERSION</code> variable value can be used to match
  5025. against <a class="ulink" href="http://www.release-monitoring.org/" target="_top">release-monitoring.org</a>
  5026. results.
  5027. </li></ul></div><p>If the package you wish to add does have a release section on GitHub, the
  5028. maintainer may have uploaded a release tarball, or the release may just point
  5029. to the automatically generated tarball from the git tag. If there is a
  5030. release tarball uploaded by the maintainer, we prefer to use that since it
  5031. may be slightly different (e.g. it contains a configure script so we don’t
  5032. need to do AUTORECONF).</p><p>You can see on the release page if it’s an uploaded tarball or a git tag:</p><div class="informalfigure"><div class="mediaobject"><img src="github_hash_mongrel2.png" alt="github_hash_mongrel2.png" /></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5033. If it looks like the image above then it was uploaded by the
  5034. maintainer and you should use that link (in that example:
  5035. <span class="emphasis"><em>mongrel2-v1.9.2.tar.bz2</em></span>) to specify <code class="literal">FOO_SITE</code>, and not use the
  5036. <span class="emphasis"><em>github</em></span> helper.
  5037. </li><li class="listitem">
  5038. On the other hand, if there’s is <span class="strong"><strong>only</strong></span> the "Source code" link, then
  5039. it’s an automatically generated tarball and you should use the
  5040. <span class="emphasis"><em>github</em></span> helper function.
  5041. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="gitlab-download-url"></a>18.24.5. How to add a package from Gitlab</h3></div></div></div><p>In a similar way to the <code class="literal">github</code> macro described in
  5042. <a class="xref" href="#github-download-url" title="18.24.4. How to add a package from GitHub">Section 18.24.4, “How to add a package from GitHub”</a>, Buildroot also provides the <code class="literal">gitlab</code> macro
  5043. to download from Gitlab repositories. It can be used to download
  5044. auto-generated tarballs produced by Gitlab, either for specific tags
  5045. or commits:</p><pre class="screen"># Use a tag or a full commit ID
  5046. FOO_VERSION = 1.0
  5047. FOO_SITE = $(call gitlab,&lt;user&gt;,&lt;package&gt;,v$(FOO_VERSION))</pre><p>By default, it will use a <code class="literal">.tar.gz</code> tarball, but Gitlab also provides
  5048. <code class="literal">.tar.bz2</code> tarballs, so by adding a <code class="literal">&lt;pkg&gt;_SOURCE</code> variable, this
  5049. <code class="literal">.tar.bz2</code> tarball can be used:</p><pre class="screen"># Use a tag or a full commit ID
  5050. FOO_VERSION = 1.0
  5051. FOO_SITE = $(call gitlab,&lt;user&gt;,&lt;package&gt;,v$(FOO_VERSION))
  5052. FOO_SOURCE = foo-$(FOO_VERSION).tar.bz2</pre><p>If there is a specific tarball uploaded by the upstream developers in
  5053. <code class="literal">https://gitlab.com/&lt;project&gt;/releases/</code>, do not use this macro, but
  5054. rather use directly the link to the tarball.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_conclusion"></a>18.25. Conclusion</h2></div></div></div><p>As you can see, adding a software package to Buildroot is simply a
  5055. matter of writing a Makefile using an existing example and modifying it
  5056. according to the compilation process required by the package.</p><p>If you package software that might be useful for other people, don’t
  5057. forget to send a patch to the Buildroot mailing list (see
  5058. <a class="xref" href="#submitting-patches" title="22.5. Submitting patches">Section 22.5, “Submitting patches”</a>)!</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="patch-policy"></a>Chapter 19. Patching a package</h2></div></div></div><p>While integrating a new package or updating an existing one, it may be
  5059. necessary to patch the source of the software to get it cross-built within
  5060. Buildroot.</p><p>Buildroot offers an infrastructure to automatically handle this during
  5061. the builds. It supports three ways of applying patch sets: downloaded patches,
  5062. patches supplied within buildroot and patches located in a user-defined
  5063. global patch directory.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_providing_patches"></a>19.1. Providing patches</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_downloaded"></a>19.1.1. Downloaded</h3></div></div></div><p>If it is necessary to apply a patch that is available for download, then add it
  5064. to the <code class="literal">&lt;packagename&gt;_PATCH</code> variable. If an entry contains <code class="literal">://</code>,
  5065. then Buildroot will assume it is a full URL and download the patch
  5066. from this location. Otherwise, Buildroot will assume that the patch should be
  5067. downloaded from <code class="literal">&lt;packagename&gt;_SITE</code>. It can be a single patch,
  5068. or a tarball containing a patch series.</p><p>Like for all downloads, a hash should be added to the <code class="literal">&lt;packagename&gt;.hash</code>
  5069. file.</p><p>This method is typically used for packages from Debian.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_within_buildroot"></a>19.1.2. Within Buildroot</h3></div></div></div><p>Most patches are provided within Buildroot, in the package
  5070. directory; these typically aim to fix cross-compilation, libc support,
  5071. or other such issues.</p><p>These patch files should be named <code class="literal">&lt;number&gt;-&lt;description&gt;.patch</code>.</p><div class="itemizedlist"><p class="title"><strong>Notes</strong></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5072. The patch files coming with Buildroot should not contain any package version
  5073. reference in their filename.
  5074. </li><li class="listitem">
  5075. The field <code class="literal">&lt;number&gt;</code> in the patch file name refers to the <span class="emphasis"><em>apply order</em></span>,
  5076. and shall start at 1; It is preferred to pad the number with zeros up to 4
  5077. digits, like <span class="emphasis"><em>git-format-patch</em></span> does. E.g.: <code class="literal">0001-foobar-the-buz.patch</code>
  5078. </li><li class="listitem">
  5079. Previously, it was mandatory for patches to be prefixed with the name of
  5080. the package, like <code class="literal">&lt;package&gt;-&lt;number&gt;-&lt;description&gt;.patch</code>, but that is
  5081. no longer the case. Existing packages will be fixed as time passes. <span class="emphasis"><em>Do
  5082. not prefix patches with the package name.</em></span>
  5083. </li><li class="listitem">
  5084. Previously, a <code class="literal">series</code> file, as used by <code class="literal">quilt</code>, could also be added in
  5085. the package directory. In that case, the <code class="literal">series</code> file defines the patch
  5086. application order. This is deprecated, and will be removed in the future.
  5087. <span class="emphasis"><em>Do not use a series file.</em></span>
  5088. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_global_patch_directory"></a>19.1.3. Global patch directory</h3></div></div></div><p>The <code class="literal">BR2_GLOBAL_PATCH_DIR</code> configuration file option can be
  5089. used to specify a space separated list of one or more directories
  5090. containing global package patches. See <a class="xref" href="#customize-patches" title="9.8. Adding project-specific patches">Section 9.8, “Adding project-specific patches”</a> for
  5091. details.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="patch-apply-order"></a>19.2. How patches are applied</h2></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
  5092. Run the <code class="literal">&lt;packagename&gt;_PRE_PATCH_HOOKS</code> commands if defined;
  5093. </li><li class="listitem">
  5094. Cleanup the build directory, removing any existing <code class="literal">*.rej</code> files;
  5095. </li><li class="listitem">
  5096. If <code class="literal">&lt;packagename&gt;_PATCH</code> is defined, then patches from these
  5097. tarballs are applied;
  5098. </li><li class="listitem"><p class="simpara">
  5099. If there are some <code class="literal">*.patch</code> files in the package’s Buildroot
  5100. directory or in a package subdirectory named <code class="literal">&lt;packageversion&gt;</code>,
  5101. then:
  5102. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5103. If a <code class="literal">series</code> file exists in the package directory, then patches are
  5104. applied according to the <code class="literal">series</code> file;
  5105. </li><li class="listitem">
  5106. Otherwise, patch files matching <code class="literal">*.patch</code> are applied in alphabetical
  5107. order.
  5108. So, to ensure they are applied in the right order, it is highly
  5109. recommended to name the patch files like this:
  5110. <code class="literal">&lt;number&gt;-&lt;description&gt;.patch</code>, where <code class="literal">&lt;number&gt;</code> refers to the
  5111. <span class="emphasis"><em>apply order</em></span>.
  5112. </li></ul></div></li><li class="listitem">
  5113. If <code class="literal">BR2_GLOBAL_PATCH_DIR</code> is defined, the directories will be
  5114. enumerated in the order they are specified. The patches are applied
  5115. as described in the previous step.
  5116. </li><li class="listitem">
  5117. Run the <code class="literal">&lt;packagename&gt;_POST_PATCH_HOOKS</code> commands if defined.
  5118. </li></ol></div><p>If something goes wrong in the steps <span class="emphasis"><em>3</em></span> or <span class="emphasis"><em>4</em></span>, then the build fails.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_format_and_licensing_of_the_package_patches"></a>19.3. Format and licensing of the package patches</h2></div></div></div><p>Patches are released under the same license as the software they apply
  5119. to (see <a class="xref" href="#legal-info-buildroot" title="13.2. Complying with the Buildroot license">Section 13.2, “Complying with the Buildroot license”</a>).</p><p>A message explaining what the patch does, and why it is needed, should
  5120. be added in the header commentary of the patch.</p><p>You should add a <code class="literal">Signed-off-by</code> statement in the header of the each
  5121. patch to help with keeping track of the changes and to certify that the
  5122. patch is released under the same license as the software that is modified.</p><p>If the software is under version control, it is recommended to use the
  5123. upstream SCM software to generate the patch set.</p><p>Otherwise, concatenate the header with the output of the
  5124. <code class="literal">diff -purN package-version.orig/ package-version/</code> command.</p><p>If you update an existing patch (e.g. when bumping the package version),
  5125. make sure the existing From header and Signed-off-by tags are not
  5126. removed, but do update the rest of the patch comment when appropriate.</p><p>At the end, the patch should look like:</p><pre class="screen">configure.ac: add C++ support test
  5127. Signed-off-by: John Doe &lt;john.doe@noname.org&gt;
  5128. --- configure.ac.orig
  5129. +++ configure.ac
  5130. @@ -40,2 +40,12 @@
  5131. AC_PROG_MAKE_SET
  5132. +
  5133. +AC_CACHE_CHECK([whether the C++ compiler works],
  5134. + [rw_cv_prog_cxx_works],
  5135. + [AC_LANG_PUSH([C++])
  5136. + AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
  5137. + [rw_cv_prog_cxx_works=yes],
  5138. + [rw_cv_prog_cxx_works=no])
  5139. + AC_LANG_POP([C++])])
  5140. +
  5141. +AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_integrating_patches_found_on_the_web"></a>19.4. Integrating patches found on the Web</h2></div></div></div><p>When integrating a patch of which you are not the author, you have to
  5142. add a few things in the header of the patch itself.</p><p>Depending on whether the patch has been obtained from the project
  5143. repository itself, or from somewhere on the web, add one of the
  5144. following tags:</p><pre class="screen">Backported from: &lt;some commit id&gt;</pre><p>or</p><pre class="screen">Fetch from: &lt;some url&gt;</pre><p>It is also sensible to add a few words about any changes to the patch
  5145. that may have been necessary.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="download-infra"></a>Chapter 20. Download infrastructure</h2></div></div></div><p>TODO</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="debugging-buildroot"></a>Chapter 21. Debugging Buildroot</h2></div></div></div><p>It is possible to instrument the steps <code class="literal">Buildroot</code> does when building
  5146. packages. Define the variable <code class="literal">BR2_INSTRUMENTATION_SCRIPTS</code> to contain
  5147. the path of one or more scripts (or other executables), in a
  5148. space-separated list, you want called before and after each step. The
  5149. scripts are called in sequence, with three parameters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5150. <code class="literal">start</code> or <code class="literal">end</code> to denote the start (resp. the end) of a step;
  5151. </li><li class="listitem">
  5152. the name of the step about to be started, or which just ended;
  5153. </li><li class="listitem">
  5154. the name of the package.
  5155. </li></ul></div><p>For example :</p><pre class="screen">make BR2_INSTRUMENTATION_SCRIPTS="/path/to/my/script1 /path/to/my/script2"</pre><p>The list of steps is:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5156. <code class="literal">extract</code>
  5157. </li><li class="listitem">
  5158. <code class="literal">patch</code>
  5159. </li><li class="listitem">
  5160. <code class="literal">configure</code>
  5161. </li><li class="listitem">
  5162. <code class="literal">build</code>
  5163. </li><li class="listitem">
  5164. <code class="literal">install-host</code>, when a host-package is installed in <code class="literal">$(HOST_DIR)</code>
  5165. </li><li class="listitem">
  5166. <code class="literal">install-target</code>, when a target-package is installed in <code class="literal">$(TARGET_DIR)</code>
  5167. </li><li class="listitem">
  5168. <code class="literal">install-staging</code>, when a target-package is installed in <code class="literal">$(STAGING_DIR)</code>
  5169. </li><li class="listitem">
  5170. <code class="literal">install-image</code>, when a target-package installs files in <code class="literal">$(BINARIES_DIR)</code>
  5171. </li></ul></div><p>The script has access to the following variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5172. <code class="literal">BR2_CONFIG</code>: the path to the Buildroot .config file
  5173. </li><li class="listitem">
  5174. <code class="literal">HOST_DIR</code>, <code class="literal">STAGING_DIR</code>, <code class="literal">TARGET_DIR</code>: see
  5175. <a class="xref" href="#generic-package-reference" title="18.5.2. generic-package reference">Section 18.5.2, “<code class="literal">generic-package</code> reference”</a>
  5176. </li><li class="listitem">
  5177. <code class="literal">BUILD_DIR</code>: the directory where packages are extracted and built
  5178. </li><li class="listitem">
  5179. <code class="literal">BINARIES_DIR</code>: the place where all binary files (aka images) are
  5180. stored
  5181. </li><li class="listitem">
  5182. <code class="literal">BASE_DIR</code>: the base output directory
  5183. </li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_contributing_to_buildroot"></a>Chapter 22. Contributing to Buildroot</h2></div></div></div><p>There are many ways in which you can contribute to Buildroot: analyzing
  5184. and fixing bugs, analyzing and fixing package build failures detected by
  5185. the autobuilders, testing and reviewing patches sent by other
  5186. developers, working on the items in our TODO list and sending your own
  5187. improvements to Buildroot or its manual. The following sections give a
  5188. little more detail on each of these items.</p><p>If you are interested in contributing to Buildroot, the first thing you
  5189. should do is to subscribe to the Buildroot mailing list. This list is
  5190. the main way of interacting with other Buildroot developers and to send
  5191. contributions to. If you aren’t subscribed yet, then refer to
  5192. <a class="xref" href="#community-resources" title="Chapter 5. Community resources">Chapter 5, <em>Community resources</em></a> for the subscription link.</p><p>If you are going to touch the code, it is highly recommended to use a
  5193. git repository of Buildroot, rather than starting from an extracted
  5194. source code tarball. Git is the easiest way to develop from and directly
  5195. send your patches to the mailing list. Refer to <a class="xref" href="#getting-buildroot" title="Chapter 3. Getting Buildroot">Chapter 3, <em>Getting Buildroot</em></a>
  5196. for more information on obtaining a Buildroot git tree.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_reproducing_analyzing_and_fixing_bugs"></a>22.1. Reproducing, analyzing and fixing bugs</h2></div></div></div><p>A first way of contributing is to have a look at the open bug reports in
  5197. the <a class="ulink" href="https://bugs.buildroot.org/buglist.cgi?product=buildroot" target="_top">Buildroot bug
  5198. tracker</a>. As we strive to keep the bug count as small as possible, all
  5199. help in reproducing, analyzing and fixing reported bugs is more than
  5200. welcome. Don’t hesitate to add a comment to bug reports reporting your
  5201. findings, even if you don’t yet see the full picture.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_analyzing_and_fixing_autobuild_failures"></a>22.2. Analyzing and fixing autobuild failures</h2></div></div></div><p>The Buildroot autobuilders are a set of build machines that continuously
  5202. run Buildroot builds based on random configurations. This is done for
  5203. all architectures supported by Buildroot, with various toolchains, and
  5204. with a random selection of packages. With the large commit activity on
  5205. Buildroot, these autobuilders are a great help in detecting problems
  5206. very early after commit.</p><p>All build results are available at <a class="ulink" href="http://autobuild.buildroot.org" target="_top">http://autobuild.buildroot.org</a>,
  5207. statistics are at <a class="ulink" href="http://autobuild.buildroot.org/stats.php" target="_top">http://autobuild.buildroot.org/stats.php</a>. Every day,
  5208. an overview of all failed packages is sent to the mailing list.</p><p>Detecting problems is great, but obviously these problems have to be
  5209. fixed as well. Your contribution is very welcome here! There are
  5210. basically two things that can be done:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5211. Analyzing the problems. The daily summary mails do not contain details
  5212. about the actual failures: in order to see what’s going on you have to
  5213. open the build log and check the last output. Having someone doing
  5214. this for all packages in the mail is very useful for other developers,
  5215. as they can make a quick initial analysis based on this output alone.
  5216. </li><li class="listitem"><p class="simpara">
  5217. Fixing a problem. When fixing autobuild failures, you should follow
  5218. these steps:
  5219. </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
  5220. Check if you can reproduce the problem by building with the same
  5221. configuration. You can do this manually, or use the
  5222. <a class="ulink" href="http://git.buildroot.org/buildroot-test/tree/utils/br-reproduce-build" target="_top">br-reproduce-build</a>
  5223. script that will automatically clone a Buildroot git repository,
  5224. checkout the correct revision, download and set the right
  5225. configuration, and start the build.
  5226. </li><li class="listitem">
  5227. Analyze the problem and create a fix.
  5228. </li><li class="listitem">
  5229. Verify that the problem is really fixed by starting from a clean
  5230. Buildroot tree and only applying your fix.
  5231. </li><li class="listitem">
  5232. Send the fix to the Buildroot mailing list (see
  5233. <a class="xref" href="#submitting-patches" title="22.5. Submitting patches">Section 22.5, “Submitting patches”</a>). In case you created a patch against the
  5234. package sources, you should also send the patch upstream so that the
  5235. problem will be fixed in a later release, and the patch in Buildroot
  5236. can be removed.
  5237. In the commit message of a patch fixing an autobuild failure, add a
  5238. reference to the build result directory, as follows:
  5239. </li></ol></div></li></ul></div><pre class="screen">Fixes: http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_reviewing_and_testing_patches"></a>22.3. Reviewing and testing patches</h2></div></div></div><p>With the amount of patches sent to the mailing list each day, the
  5240. maintainer has a very hard job to judge which patches are ready to apply
  5241. and which ones aren’t. Contributors can greatly help here by reviewing
  5242. and testing these patches.</p><p>In the review process, do not hesitate to respond to patch submissions
  5243. for remarks, suggestions or anything that will help everyone to
  5244. understand the patches and make them better. Please use internet
  5245. style replies in plain text emails when responding to patch
  5246. submissions.</p><p>To indicate approval of a patch, there are three formal tags that keep
  5247. track of this approval. To add your tag to a patch, reply to it with the
  5248. approval tag below the original author’s Signed-off-by line. These tags
  5249. will be picked up automatically by patchwork (see
  5250. <a class="xref" href="#apply-patches-patchwork" title="22.3.1. Applying Patches from Patchwork">Section 22.3.1, “Applying Patches from Patchwork”</a>) and will be part of the commit log when
  5251. the patch is accepted.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
  5252. Tested-by
  5253. </span></dt><dd>
  5254. Indicates that the patch has been tested successfully.
  5255. You are encouraged to specify what kind of testing you performed
  5256. (compile-test on architecture X and Y, runtime test on target A,
  5257. …). This additional information helps other testers and the
  5258. maintainer.
  5259. </dd><dt><span class="term">
  5260. Reviewed-by
  5261. </span></dt><dd>
  5262. Indicates that you code-reviewed the patch and did your
  5263. best in spotting problems, but you are not sufficiently familiar with
  5264. the area touched to provide an Acked-by tag. This means that there
  5265. may be remaining problems in the patch that would be spotted by
  5266. someone with more experience in that area. Should such problems be
  5267. detected, your Reviewed-by tag remains appropriate and you cannot
  5268. be blamed.
  5269. </dd><dt><span class="term">
  5270. Acked-by
  5271. </span></dt><dd>
  5272. Indicates that you code-reviewed the patch and you are
  5273. familiar enough with the area touched to feel that the patch can be
  5274. committed as-is (no additional changes required). In case it later
  5275. turns out that something is wrong with the patch, your Acked-by could
  5276. be considered inappropriate. The difference between Acked-by and
  5277. Reviewed-by is thus mainly that you are prepared to take the blame on
  5278. Acked patches, but not on Reviewed ones.
  5279. </dd></dl></div><p>If you reviewed a patch and have comments on it, you should simply reply
  5280. to the patch stating these comments, without providing a Reviewed-by or
  5281. Acked-by tag. These tags should only be provided if you judge the patch
  5282. to be good as it is.</p><p>It is important to note that neither Reviewed-by nor Acked-by imply
  5283. that testing has been performed. To indicate that you both reviewed and
  5284. tested the patch, provide two separate tags (Reviewed/Acked-by and
  5285. Tested-by).</p><p>Note also that <span class="emphasis"><em>any developer</em></span> can provide Tested/Reviewed/Acked-by
  5286. tags, without exception, and we encourage everyone to do this. Buildroot
  5287. does not have a defined group of <span class="emphasis"><em>core</em></span> developers, it just so happens
  5288. that some developers are more active than others. The maintainer will
  5289. value tags according to the track record of their submitter. Tags
  5290. provided by a regular contributor will naturally be trusted more than
  5291. tags provided by a newcomer. As you provide tags more regularly, your
  5292. <span class="emphasis"><em>trustworthiness</em></span> (in the eyes of the maintainer) will go up, but <span class="emphasis"><em>any</em></span>
  5293. tag provided is valuable.</p><p>Buildroot’s Patchwork website can be used to pull in patches for testing
  5294. purposes. Please see <a class="xref" href="#apply-patches-patchwork" title="22.3.1. Applying Patches from Patchwork">Section 22.3.1, “Applying Patches from Patchwork”</a> for more
  5295. information on using Buildroot’s Patchwork website to apply patches.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="apply-patches-patchwork"></a>22.3.1. Applying Patches from Patchwork</h3></div></div></div><p>The main use of Buildroot’s Patchwork website for a developer is for
  5296. pulling in patches into their local git repository for testing
  5297. purposes.</p><p>When browsing patches in the patchwork management interface, an <code class="literal">mbox</code>
  5298. link is provided at the top of the page. Copy this link address and
  5299. run the following commands:</p><pre class="screen">$ git checkout -b &lt;test-branch-name&gt;
  5300. $ wget -O - &lt;mbox-url&gt; | git am</pre><p>Another option for applying patches is to create a bundle. A bundle is
  5301. a set of patches that you can group together using the patchwork
  5302. interface. Once the bundle is created and the bundle is made public,
  5303. you can copy the <code class="literal">mbox</code> link for the bundle and apply the bundle
  5304. using the above commands.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_work_on_items_from_the_todo_list"></a>22.4. Work on items from the TODO list</h2></div></div></div><p>If you want to contribute to Buildroot but don’t know where to start,
  5305. and you don’t like any of the above topics, you can always work on items
  5306. from the <a class="ulink" href="http://elinux.org/Buildroot#Todo_list" target="_top">Buildroot TODO list</a>.
  5307. Don’t hesitate to discuss an item first on the mailing list or on IRC.
  5308. Do edit the wiki to indicate when you start working on an item, so we
  5309. avoid duplicate efforts.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="submitting-patches"></a>22.5. Submitting patches</h2></div></div></div><div class="note" style="margin-left: 0; margin-right: 10%;"><h3 class="title">Note</h3><p><span class="emphasis"><em>Please, do not attach patches to bugs, send them to the mailing list
  5310. instead</em></span>.</p></div><p>If you made some changes to Buildroot and you would like to contribute
  5311. them to the Buildroot project, proceed as follows.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_the_formatting_of_a_patch"></a>22.5.1. The formatting of a patch</h3></div></div></div><p>We expect patches to be formatted in a specific way. This is necessary
  5312. to make it easy to review patches, to be able to apply them easily to
  5313. the git repository, to make it easy to find back in the history how
  5314. and why things have changed, and to make it possible to use <code class="literal">git
  5315. bisect</code> to locate the origin of a problem.</p><p>First of all, it is essential that the patch has a good commit
  5316. message. The commit message should start with a separate line with a
  5317. brief summary of the change, prefixed by the area touched by the
  5318. patch. A few examples of good commit titles:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5319. <code class="literal">package/linuxptp: bump version to 2.0</code>
  5320. </li><li class="listitem">
  5321. <code class="literal">configs/imx23evk: bump Linux version to 4.19</code>
  5322. </li><li class="listitem">
  5323. <code class="literal">package/pkg-generic: postpone evaluation of dependency conditions</code>
  5324. </li><li class="listitem">
  5325. <code class="literal">boot/uboot: needs host-{flex,bison}</code>
  5326. </li><li class="listitem">
  5327. <code class="literal">support/testing: add python-ubjson tests</code>
  5328. </li></ul></div><p>The description that follows the prefix should start with a lower case
  5329. letter (i.e "bump", "needs", "postpone", "add" in the above examples).</p><p>Second, the body of the commit message should describe <span class="emphasis"><em>why</em></span> this
  5330. change is needed, and if necessary also give details about <span class="emphasis"><em>how</em></span> it
  5331. was done. When writing the commit message, think of how the reviewers
  5332. will read it, but also think about how you will read it when you look
  5333. at this change again a few years down the line.</p><p>Third, the patch itself should do only one change, but do it
  5334. completely. Two unrelated or weakly related changes should usually be
  5335. done in two separate patches. This usually means that a patch affects
  5336. only a single package. If several changes are related, it is often
  5337. still possible to split them up in small patches and apply them in a
  5338. specific order. Small patches make it easier to review, and often
  5339. make it easier to understand afterwards why a change was done.
  5340. However, each patch must be complete. It is not allowed that the
  5341. build is broken when only the first but not the second patch is
  5342. applied. This is necessary to be able to use <code class="literal">git bisect</code> afterwards.</p><p>Of course, while you’re doing your development, you’re probably going
  5343. back and forth between packages, and certainly not committing things
  5344. immediately in a way that is clean enough for submission. So most
  5345. developers rewrite the history of commits to produce a clean set of
  5346. commits that is appropriate for submission. To do this, you need to
  5347. use <span class="emphasis"><em>interactive rebasing</em></span>. You can learn about it
  5348. <a class="ulink" href="https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History" target="_top">in the Pro
  5349. Git book</a>. Sometimes, it is even easier to discard you history with
  5350. <code class="literal">git reset --soft origin/master</code> and select individual changes with
  5351. <code class="literal">git add -i</code> or <code class="literal">git add -p</code>.</p><p>Finally, the patch should be signed off. This is done by adding
  5352. <code class="literal">Signed-off-by: Your Real Name &lt;<a class="ulink" href="mailto:your@email.address" target="_top">your@email.address</a>&gt;</code> at the end of the
  5353. commit message. <code class="literal">git commit -s</code> does that for you, if configured
  5354. properly. The <code class="literal">Signed-off-by</code> tag means that you publish the patch
  5355. under the Buildroot license (i.e. GPL-2.0+, except for package patches,
  5356. which have the upstream license), and that you are allowed to do so.
  5357. See <a class="ulink" href="http://developercertificate.org/" target="_top">the Developer Certificate of
  5358. Origin</a> for details.</p><p>When adding new packages, you should submit every package in a
  5359. separate patch. This patch should have the update to
  5360. <code class="literal">package/Config.in</code>, the package <code class="literal">Config.in</code> file, the <code class="literal">.mk</code> file, the
  5361. <code class="literal">.hash</code> file, any init script, and all package patches. If the package
  5362. has many sub-options, these are sometimes better added as separate
  5363. follow-up patches. The summary line should be something like
  5364. <code class="literal">&lt;packagename&gt;: new package</code>. The body of the commit message can be
  5365. empty for simple packages, or it can contain the description of the
  5366. package (like the Config.in help text). If anything special has to be
  5367. done to build the package, this should also be explained explicitly in
  5368. the commit message body.</p><p>When you bump a package to a new version, you should also submit a
  5369. separate patch for each package. Don’t forget to update the <code class="literal">.hash</code>
  5370. file, or add it if it doesn’t exist yet. Also don’t forget to check if
  5371. the <code class="literal">_LICENSE</code> and <code class="literal">_LICENSE_FILES</code> are still valid. The summary line
  5372. should be something like <code class="literal">&lt;packagename&gt;: bump to version &lt;new
  5373. version&gt;</code>. If the new version only contains security updates compared
  5374. to the existing one, the summary should be <code class="literal">&lt;packagename&gt;: security
  5375. bump to version &lt;new version&gt;</code> and the commit message body should show
  5376. the CVE numbers that are fixed. If some package patches can be removed
  5377. in the new version, it should be explained explicitly why they can be
  5378. removed, preferably with the upstream commit ID. Also any other
  5379. required changes should be explained explicitly, like configure
  5380. options that no longer exist or are no longer needed.</p><p>If you are interested in getting notified of build failures and of
  5381. further changes in the packages you added or modified, please add
  5382. yourself to the DEVELOPERS file. This should be done in the same patch
  5383. creating or modifying the package. See <a class="link" href="#DEVELOPERS" title="Chapter 23. DEVELOPERS file and get-developers">the DEVELOPERS file</a>
  5384. for more information.</p><p>Buildroot provides a handy tool to check for common coding style
  5385. mistakes on files you created or modified, called <code class="literal">check-package</code> (see
  5386. <a class="xref" href="#check-package" title="18.24.2. How to check the coding style">Section 18.24.2, “How to check the coding style”</a> for more information).</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_preparing_a_patch_series"></a>22.5.2. Preparing a patch series</h3></div></div></div><p>Starting from the changes committed in your local git view, <span class="emphasis"><em>rebase</em></span>
  5387. your development branch on top of the upstream tree before generating
  5388. a patch set. To do so, run:</p><pre class="screen">$ git fetch --all --tags
  5389. $ git rebase origin/master</pre><p>Now, you are ready to generate then submit your patch set.</p><p>To generate it, run:</p><pre class="screen">$ git format-patch -M -n -s -o outgoing origin/master</pre><p>This will generate patch files in the <code class="literal">outgoing</code> subdirectory,
  5390. automatically adding the <code class="literal">Signed-off-by</code> line.</p><p>Once patch files are generated, you can review/edit the commit message
  5391. before submitting them, using your favorite text editor.</p><p>Buildroot provides a handy tool to know to whom your patches should be
  5392. sent, called <code class="literal">get-developers</code> (see <a class="xref" href="#DEVELOPERS" title="Chapter 23. DEVELOPERS file and get-developers">Chapter 23, <em>DEVELOPERS file and get-developers</em></a> for more
  5393. information). This tool reads your patches and outputs the appropriate
  5394. <code class="literal">git send-email</code> command to use:</p><pre class="screen">$ ./utils/get-developers outgoing/*</pre><p>Use the output of <code class="literal">get-developers</code> to send your patches:</p><pre class="screen">$ git send-email --to buildroot@buildroot.org --cc bob --cc alice outgoing/*</pre><p>Alternatively, <code class="literal">get-developers -e</code> can be used directly with the
  5395. <code class="literal">--cc-cmd</code> argument to <code class="literal">git send-email</code> to automatically CC the
  5396. affected developers:</p><pre class="screen">$ git send-email --to buildroot@buildroot.org \
  5397. --cc-cmd './utils/get-developers -e' origin/master</pre><p><code class="literal">git</code> can be configured to automatically do this out of the box with:</p><pre class="screen">$ git config sendemail.to buildroot@buildroot.org
  5398. $ git config sendemail.ccCmd "$(pwd)/utils/get-developers -e"</pre><p>And then just do:</p><pre class="screen">$ git send-email origin/master</pre><p>Note that <code class="literal">git</code> should be configured to use your mail account.
  5399. To configure <code class="literal">git</code>, see <code class="literal">man git-send-email</code> or google it.</p><p>If you do not use <code class="literal">git send-email</code>, make sure posted <span class="strong"><strong>patches are not
  5400. line-wrapped</strong></span>, otherwise they cannot easily be applied. In such a case,
  5401. fix your e-mail client, or better yet, learn to use <code class="literal">git send-email</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_cover_letter"></a>22.5.3. Cover letter</h3></div></div></div><p>If you want to present the whole patch set in a separate mail, add
  5402. <code class="literal">--cover-letter</code> to the <code class="literal">git format-patch</code> command (see <code class="literal">man
  5403. git-format-patch</code> for further information). This will generate a
  5404. template for an introduction e-mail to your patch series.</p><p>A <span class="emphasis"><em>cover letter</em></span> may be useful to introduce the changes you propose
  5405. in the following cases:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5406. large number of commits in the series;
  5407. </li><li class="listitem">
  5408. deep impact of the changes in the rest of the project;
  5409. </li><li class="listitem">
  5410. RFC <a href="#ftn.idm5758" class="footnote" id="idm5758"><sup class="footnote">[4]</sup></a>;
  5411. </li><li class="listitem">
  5412. whenever you feel it will help presenting your work, your choices,
  5413. the review process, etc.
  5414. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_patches_for_maintenance_branches"></a>22.5.4. Patches for maintenance branches</h3></div></div></div><p>When fixing bugs on a maintenance branch, bugs should be fixed on the
  5415. master branch first. The commit log for such a patch may then contain a
  5416. post-commit note specifying what branches are affected:</p><pre class="screen">package/foo: fix stuff
  5417. Signed-off-by: Your Real Name &lt;your@email.address&gt;
  5418. ---
  5419. Backport to: 2020.02.x, 2020.05.x
  5420. (2020.08.x not affected as the version was bumped)</pre><p>Those changes will then be backported by a maintainer to the affected
  5421. branches.</p><p>However, some bugs may apply only to a specific release, for example
  5422. because it is using an older version of a package. In that case, patches
  5423. should be based off the maintenance branch, and the patch subject prefix
  5424. must include the maintenance branch name (for example "[PATCH 2020.02.x]").
  5425. This can be done with the <code class="literal">git format-patch</code> flag <code class="literal">--subject-prefix</code>:</p><pre class="screen">$ git format-patch --subject-prefix "PATCH 2020.02.x" \
  5426. -M -s -o outgoing origin/2020.02.x</pre><p>Then send the patches with <code class="literal">git send-email</code>, as described above.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_patch_revision_changelog"></a>22.5.5. Patch revision changelog</h3></div></div></div><p>When improvements are requested, the new revision of each commit
  5427. should include a changelog of the modifications between each
  5428. submission. Note that when your patch series is introduced by a cover
  5429. letter, an overall changelog may be added to the cover letter in
  5430. addition to the changelog in the individual commits.
  5431. The best thing to rework a patch series is by interactive rebasing:
  5432. <code class="literal">git rebase -i origin/master</code>. Consult the git manual for more
  5433. information.</p><p>When added to the individual commits, this changelog is added when
  5434. editing the commit message. Below the <code class="literal">Signed-off-by</code> section, add
  5435. <code class="literal">---</code> and your changelog.</p><p>Although the changelog will be visible for the reviewers in the mail
  5436. thread, as well as in <a class="ulink" href="http://patchwork.buildroot.org" target="_top">patchwork</a>, <code class="literal">git</code>
  5437. will automatically ignores lines below <code class="literal">---</code> when the patch will be
  5438. merged. This is the intended behavior: the changelog is not meant to
  5439. be preserved forever in the <code class="literal">git</code> history of the project.</p><p>Hereafter the recommended layout:</p><pre class="screen">Patch title: short explanation, max 72 chars
  5440. A paragraph that explains the problem, and how it manifests itself. If
  5441. the problem is complex, it is OK to add more paragraphs. All paragraphs
  5442. should be wrapped at 72 characters.
  5443. A paragraph that explains the root cause of the problem. Again, more
  5444. than one paragraph is OK.
  5445. Finally, one or more paragraphs that explain how the problem is solved.
  5446. Don't hesitate to explain complex solutions in detail.
  5447. Signed-off-by: John DOE &lt;john.doe@example.net&gt;
  5448. ---
  5449. Changes v2 -&gt; v3:
  5450. - foo bar (suggested by Jane)
  5451. - bar buz
  5452. Changes v1 -&gt; v2:
  5453. - alpha bravo (suggested by John)
  5454. - charly delta</pre><p>Any patch revision should include the version number. The version number
  5455. is simply composed of the letter <code class="literal">v</code> followed by an <code class="literal">integer</code> greater or
  5456. equal to two (i.e. "PATCH v2", "PATCH v3" …).</p><p>This can be easily handled with <code class="literal">git format-patch</code> by using the option
  5457. <code class="literal">--subject-prefix</code>:</p><pre class="screen">$ git format-patch --subject-prefix "PATCH v4" \
  5458. -M -s -o outgoing origin/master</pre><p>Since git version 1.8.1, you can also use <code class="literal">-v &lt;n&gt;</code> (where &lt;n&gt; is the
  5459. version number):</p><pre class="screen">$ git format-patch -v4 -M -s -o outgoing origin/master</pre><p>When you provide a new version of a patch, please mark the old one as
  5460. superseded in <a class="ulink" href="http://patchwork.buildroot.org" target="_top">patchwork</a>. You need to
  5461. create an account on <a class="ulink" href="http://patchwork.buildroot.org" target="_top">patchwork</a> to be
  5462. able to modify the status of your patches. Note that you can only change
  5463. the status of patches you submitted yourself, which means the email
  5464. address you register in <a class="ulink" href="http://patchwork.buildroot.org" target="_top">patchwork</a> should
  5465. match the one you use for sending patches to the mailing list.</p><p>You can also add the <code class="literal">--in-reply-to &lt;message-id&gt;</code> option when
  5466. submitting a patch to the mailing list. The id of the mail to reply to
  5467. can be found under the "Message Id" tag on
  5468. <a class="ulink" href="http://patchwork.buildroot.org" target="_top">patchwork</a>. The advantage of
  5469. <span class="strong"><strong>in-reply-to</strong></span> is that patchwork will automatically mark the previous
  5470. version of the patch as superseded.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="reporting-bugs"></a>22.6. Reporting issues/bugs or getting help</h2></div></div></div><p>Before reporting any issue, please check in
  5471. <a class="link" href="#community-resources" title="Chapter 5. Community resources">the mailing list archive</a> whether someone has
  5472. already reported and/or fixed a similar problem.</p><p>However you choose to report bugs or get help, either by
  5473. opening a bug in the <a class="link" href="#community-resources" title="Chapter 5. Community resources">bug tracker</a> or by
  5474. <a class="link" href="#community-resources" title="Chapter 5. Community resources">sending a mail to the mailing list</a>, there are
  5475. a number of details to provide in order to help people reproduce and
  5476. find a solution to the issue.</p><p>Try to think as if you were trying to help someone else; in
  5477. that case, what would you need?</p><p>Here is a short list of details to provide in such case:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5478. host machine (OS/release)
  5479. </li><li class="listitem">
  5480. version of Buildroot
  5481. </li><li class="listitem">
  5482. target for which the build fails
  5483. </li><li class="listitem">
  5484. package(s) for which the build fails
  5485. </li><li class="listitem">
  5486. the command that fails and its output
  5487. </li><li class="listitem">
  5488. any information you think that may be relevant
  5489. </li></ul></div><p>Additionally, you should add the <code class="literal">.config</code> file (or if you know how, a
  5490. <code class="literal">defconfig</code>; see <a class="xref" href="#customize-store-buildroot-config" title="9.3. Storing the Buildroot configuration">Section 9.3, “Storing the Buildroot configuration”</a>).</p><p>If some of these details are too large, do not hesitate to use a
  5491. pastebin service. Note that not all available pastebin services will
  5492. preserve Unix-style line terminators when downloading raw pastes.
  5493. Following pastebin services are known to work correctly:
  5494. - <a class="ulink" href="https://gist.github.com/" target="_top">https://gist.github.com/</a>
  5495. - <a class="ulink" href="http://code.bulix.org/" target="_top">http://code.bulix.org/</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_using_the_run_tests_framework"></a>22.7. Using the run-tests framework</h2></div></div></div><p>Buildroot includes a run-time testing framework called run-tests built
  5496. upon Python scripting and QEMU runtime execution. There are two types of
  5497. test cases within the framework, one for build time tests and another for
  5498. run-time tests that have a QEMU dependency. The goals of the framework are
  5499. the following:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5500. build a well defined configuration
  5501. </li><li class="listitem">
  5502. optionally, verify some properties of the build output
  5503. </li><li class="listitem"><p class="simpara">
  5504. if it is a run-time test:
  5505. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  5506. boot it under QEMU
  5507. </li><li class="listitem">
  5508. run some test condition to verify that a given feature is working
  5509. </li></ul></div></li></ul></div><p>The run-tests tool has a series of options documented in the tool’s help <span class="emphasis"><em>-h</em></span>
  5510. description. Some common options include setting the download folder, the
  5511. output folder, keeping build output, and for multiple test cases, you can set
  5512. the JLEVEL for each.</p><p>Here is an example walk through of running a test case.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5513. For a first step, let us see what all the test case options are. The test
  5514. cases can be listed by executing <code class="literal">support/testing/run-tests -l</code>. These tests
  5515. can all be run individually during test development from the console. Both
  5516. one at a time and selectively as a group of a subset of tests.
  5517. </li></ul></div><pre class="screen">$ support/testing/run-tests -l
  5518. List of tests
  5519. test_run (tests.utils.test_check_package.TestCheckPackage)
  5520. Test the various ways the script can be called in a simple top to ... ok
  5521. test_run (tests.toolchain.test_external.TestExternalToolchainBuildrootMusl) ... ok
  5522. test_run (tests.toolchain.test_external.TestExternalToolchainBuildrootuClibc) ... ok
  5523. test_run (tests.toolchain.test_external.TestExternalToolchainCCache) ... ok
  5524. test_run (tests.toolchain.test_external.TestExternalToolchainCtngMusl) ... ok
  5525. test_run (tests.toolchain.test_external.TestExternalToolchainLinaroArm) ... ok
  5526. test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv4) ... ok
  5527. test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv5) ... ok
  5528. test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv7) ... ok
  5529. [snip]
  5530. test_run (tests.init.test_systemd.TestInitSystemSystemdRoFull) ... ok
  5531. test_run (tests.init.test_systemd.TestInitSystemSystemdRoIfupdown) ... ok
  5532. test_run (tests.init.test_systemd.TestInitSystemSystemdRoNetworkd) ... ok
  5533. test_run (tests.init.test_systemd.TestInitSystemSystemdRwFull) ... ok
  5534. test_run (tests.init.test_systemd.TestInitSystemSystemdRwIfupdown) ... ok
  5535. test_run (tests.init.test_systemd.TestInitSystemSystemdRwNetworkd) ... ok
  5536. test_run (tests.init.test_busybox.TestInitSystemBusyboxRo) ... ok
  5537. test_run (tests.init.test_busybox.TestInitSystemBusyboxRoNet) ... ok
  5538. test_run (tests.init.test_busybox.TestInitSystemBusyboxRw) ... ok
  5539. test_run (tests.init.test_busybox.TestInitSystemBusyboxRwNet) ... ok
  5540. Ran 157 tests in 0.021s
  5541. OK</pre><p>Those runtime tests are regularly executed by Buildroot Gitlab CI
  5542. infrastructure, see .gitlab.yml and <a class="ulink" href="https://gitlab.com/buildroot.org/buildroot/-/jobs" target="_top">https://gitlab.com/buildroot.org/buildroot/-/jobs</a>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_creating_a_test_case"></a>22.7.1. Creating a test case</h3></div></div></div><p>The best way to get familiar with how to create a test case is to look at a
  5543. few of the basic file system <code class="literal">support/testing/tests/fs/</code> and init
  5544. <code class="literal">support/testing/tests/init/</code> test scripts. Those tests give good examples
  5545. of a basic build and build with run type of tests. There are other more
  5546. advanced cases that use things like nested <code class="literal">br2-external</code> folders to provide
  5547. skeletons and additional packages.</p><p>The test cases by default use a br-arm-full-* uClibc-ng toolchain and the
  5548. prebuild kernel for a armv5/7 cpu. It is recommended to use the default
  5549. defconfig test configuration except when Glibc/musl or a newer kernel are
  5550. necessary. By using the default it saves build time and the test would
  5551. automatically inherit a kernel/std library upgrade when the default is
  5552. updated.</p><p>The basic test case definition involves</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5553. Creation of a new test file
  5554. </li><li class="listitem">
  5555. Defining a unique test class
  5556. </li><li class="listitem">
  5557. Determining if the default defconfig plus test options can be used
  5558. </li><li class="listitem">
  5559. Implementing a <code class="literal">def test_run(self):</code> function to optionally startup the
  5560. emulator and provide test case conditions.
  5561. </li></ul></div><p>After creating the test script, add yourself to the <code class="literal">DEVELOPERS</code> file to
  5562. be the maintainer of that test case.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_debugging_a_test_case"></a>22.7.2. Debugging a test case</h3></div></div></div><p>Within the Buildroot repository, the testing framework is organized at the
  5563. top level in <code class="literal">support/testing/</code> by folders of <code class="literal">conf</code>, <code class="literal">infra</code> and <code class="literal">tests</code>.
  5564. All the test cases live under the <code class="literal">test</code> folder and are organized in various
  5565. folders representing the catagory of test.</p><p>Lets walk through an example.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5566. Using the Busybox Init system test case with a read/write rootfs
  5567. <code class="literal">tests.init.test_busybox.TestInitSystemBusyboxRw</code>
  5568. </li><li class="listitem">
  5569. A minimal set of command line arguments when debugging a test case would
  5570. include <span class="emphasis"><em>-d</em></span> which points to your dl folder, <span class="emphasis"><em>-o</em></span> to an output folder, and
  5571. <span class="emphasis"><em>-k</em></span> to keep any output on both pass/fail. With those options, the test will
  5572. retain logging and build artifacts providing status of the build and
  5573. execution of the test case.
  5574. </li></ul></div><pre class="screen">$ support/testing/run-tests -d dl -o output_folder -k tests.init.test_busybox.TestInitSystemBusyboxRw
  5575. 15:03:26 TestInitSystemBusyboxRw Starting
  5576. 15:03:28 TestInitSystemBusyboxRw Building
  5577. 15:08:18 TestInitSystemBusyboxRw Building done
  5578. 15:08:27 TestInitSystemBusyboxRw Cleaning up
  5579. .
  5580. Ran 1 test in 301.140s
  5581. OK</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5582. For the case of a successful build, the <code class="literal">output_folder</code> would contain a
  5583. &lt;test name&gt; folder with the Buildroot build, build log and run-time log. If
  5584. the build failed, the console output would show the stage at which it failed
  5585. (setup / build / run). Depending on the failure stage, the build/run logs
  5586. and/or Buildroot build artifacts can be inspected and instrumented. If the
  5587. QEMU instance needs to be launched for additional testing, the first few
  5588. lines of the run-time log capture it and it would allow some incremental
  5589. testing without re-running <code class="literal">support/testing/run-tests</code>.
  5590. </li><li class="listitem">
  5591. You can also make modifications to the current sources inside the
  5592. <code class="literal">output_folder</code> (e.g. for debug purposes) and rerun the standard
  5593. Buildroot make targets (in order to regenerate the complete image with
  5594. the new modifications) and then rerun the test. Modifying the sources
  5595. directly can speed up debugging compared to adding patch files, wiping the
  5596. output directoy, and starting the test again.
  5597. </li></ul></div><pre class="screen">$ ls output_folder/
  5598. TestInitSystemBusyboxRw/
  5599. TestInitSystemBusyboxRw-build.log
  5600. TestInitSystemBusyboxRw-run.log</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5601. The source file used to implement this example test is found under
  5602. <code class="literal">support/testing/tests/init/test_busybox.py</code>. This file outlines the
  5603. minimal defconfig that creates the build, QEMU configuration to launch
  5604. the built images and the test case assertions.
  5605. </li></ul></div><p>To test an existing or new test case within Gitlab CI, there is a method of
  5606. invoking a specific test by creating a Buildroot fork in Gitlab under your
  5607. account. This can be handy when adding/changing a run-time test or fixing a
  5608. bug on a use case tested by a run-time test case.</p><p>In the examples below, the &lt;name&gt; component of the branch name is a unique
  5609. string you choose to identify this specific job being created.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5610. to trigger all run-test test case jobs:
  5611. </li></ul></div><pre class="screen"> $ git push gitlab HEAD:&lt;name&gt;-runtime-tests</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5612. to trigger one test case job, a specific branch naming string is used that
  5613. includes the full test case name.
  5614. </li></ul></div><pre class="screen"> $ git push gitlab HEAD:&lt;name&gt;-&lt;test case name&gt;</pre></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm5758" class="footnote"><p><a href="#idm5758" class="simpara"><sup class="simpara">[4] </sup></a>RFC: (Request for comments) change proposal</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="DEVELOPERS"></a>Chapter 23. DEVELOPERS file and get-developers</h2></div></div></div><p>The main Buildroot directory contains a file named <code class="literal">DEVELOPERS</code> that
  5615. lists the developers involved with various areas of Buildroot. Thanks
  5616. to this file, the <code class="literal">get-developers</code> tool allows to:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5617. Calculate the list of developers to whom patches should be sent, by
  5618. parsing the patches and matching the modified files with the
  5619. relevant developers. See <a class="xref" href="#submitting-patches" title="22.5. Submitting patches">Section 22.5, “Submitting patches”</a> for details.
  5620. </li><li class="listitem">
  5621. Find which developers are taking care of a given architecture or
  5622. package, so that they can be notified when a build failure occurs on
  5623. this architecture or package. This is done in interaction with
  5624. Buildroot’s autobuild infrastructure.
  5625. </li></ul></div><p>We ask developers adding new packages, new boards, or generally new
  5626. functionality in Buildroot, to register themselves in the <code class="literal">DEVELOPERS</code>
  5627. file. As an example, we expect a developer contributing a new package
  5628. to include in his patch the appropriate modification to the
  5629. <code class="literal">DEVELOPERS</code> file.</p><p>The <code class="literal">DEVELOPERS</code> file format is documented in detail inside the file
  5630. itself.</p><p>The <code class="literal">get-developers</code> tool, located in <code class="literal">utils/</code> allows to use
  5631. the <code class="literal">DEVELOPERS</code> file for various tasks:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5632. When passing one or several patches as command line argument,
  5633. <code class="literal">get-developers</code> will return the appropriate <code class="literal">git send-email</code>
  5634. command. If the <code class="literal">-e</code> option is passed, only the email addresses are
  5635. printed in a format suitable for <code class="literal">git send-email --cc-cmd</code>.
  5636. </li><li class="listitem">
  5637. When using the <code class="literal">-a &lt;arch&gt;</code> command line option, <code class="literal">get-developers</code> will
  5638. return the list of developers in charge of the given architecture.
  5639. </li><li class="listitem">
  5640. When using the <code class="literal">-p &lt;package&gt;</code> command line option, <code class="literal">get-developers</code>
  5641. will return the list of developers in charge of the given package.
  5642. </li><li class="listitem">
  5643. When using the <code class="literal">-c</code> command line option, <code class="literal">get-developers</code> will look
  5644. at all files under version control in the Buildroot repository, and
  5645. list the ones that are not handled by any developer. The purpose of
  5646. this option is to help completing the <code class="literal">DEVELOPERS</code> file.
  5647. </li><li class="listitem">
  5648. When using without any arguments, it validates the integrity of the
  5649. DEVELOPERS file and will note WARNINGS for items that don’t match.
  5650. </li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="RELENG"></a>Chapter 24. Release Engineering</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_releases"></a>24.1. Releases</h2></div></div></div><p>The Buildroot project makes quarterly releases with monthly bugfix
  5651. releases. The first release of each year is a long term support
  5652. release, LTS.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5653. Quarterly releases: 2020.02, 2020.05, 2020.08, and 2020.11
  5654. </li><li class="listitem">
  5655. Bugfix releases: 2020.02.1, 2020.02.2, …
  5656. </li><li class="listitem">
  5657. LTS releases: 2020.02, 2021.02, …
  5658. </li></ul></div><p>Releases are supported until the first bugfix release of the next
  5659. release, e.g., 2020.05.x is EOL when 2020.08.1 is released.</p><p>LTS releases are supported until the first bugfix release of the next
  5660. LTS, e.g., 2020.02.x is supported until 2021.02.1 is released.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_development"></a>24.2. Development</h2></div></div></div><p>Each release cycle consist of two months of development on the <code class="literal">master</code>
  5661. branch and one month stabilization before the release is made. During
  5662. this phase no new features are added to <code class="literal">master</code>, only bugfixes.</p><p>The stabilization phase starts with tagging <code class="literal">-rc1</code>, and every week until
  5663. the release, another release candidate is tagged.</p><p>To handle new features and version bumps during the stabilization phase,
  5664. a <code class="literal">next</code> branch may be created for these features. Once the current
  5665. release has been made, the <code class="literal">next</code> branch is merged into <code class="literal">master</code> and
  5666. the development cycle for the next release continues there.</p></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="_appendix"></a>Part IV. Appendix</h1></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="makedev-syntax"></a>Chapter 25. Makedev syntax documentation</h2></div></div></div><p>The makedev syntax is used in several places in Buildroot to
  5667. define changes to be made for permissions, or which device files to
  5668. create and how to create them, in order to avoid calls to mknod.</p><p>This syntax is derived from the makedev utility, and more complete
  5669. documentation can be found in the <code class="literal">package/makedevs/README</code> file.</p><p>It takes the form of a space separated list of fields, one file per
  5670. line; the fields are:</p><div class="informaltable"><table class="informaltable" cellpadding="4px" style="border-collapse: collapse;border-top: 3px solid #527bbd; border-bottom: 3px solid #527bbd; border-left: 3px solid #527bbd; border-right: 3px solid #527bbd; "><colgroup><col class="col_1" /><col class="col_2" /><col class="col_3" /><col class="col_4" /><col class="col_5" /><col class="col_6" /><col class="col_7" /><col class="col_8" /><col class="col_9" /><col class="col_10" /></colgroup><tbody><tr><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>name</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>type</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>mode</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>uid</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>gid</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>major</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>minor</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>start</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>inc</p></td><td style="" align="left" valign="top"><p>count</p></td></tr></tbody></table></div><p>There are a few non-trivial blocks:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5671. <code class="literal">name</code> is the path to the file you want to create/modify
  5672. </li><li class="listitem"><p class="simpara">
  5673. <code class="literal">type</code> is the type of the file, being one of:
  5674. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  5675. f: a regular file
  5676. </li><li class="listitem">
  5677. d: a directory
  5678. </li><li class="listitem">
  5679. r: a directory recursively
  5680. </li><li class="listitem">
  5681. c: a character device file
  5682. </li><li class="listitem">
  5683. b: a block device file
  5684. </li><li class="listitem">
  5685. p: a named pipe
  5686. </li></ul></div></li><li class="listitem">
  5687. <code class="literal">mode</code> are the usual permissions settings (only numerical values
  5688. are allowed)
  5689. </li><li class="listitem">
  5690. <code class="literal">uid</code> and <code class="literal">gid</code> are the UID and GID to set on this file; can be
  5691. either numerical values or actual names
  5692. </li><li class="listitem">
  5693. <code class="literal">major</code> and <code class="literal">minor</code> are here for device files, set to <code class="literal">-</code> for other
  5694. files
  5695. </li><li class="listitem">
  5696. <code class="literal">start</code>, <code class="literal">inc</code> and <code class="literal">count</code> are for when you want to create a batch
  5697. of files, and can be reduced to a loop, beginning at <code class="literal">start</code>,
  5698. incrementing its counter by <code class="literal">inc</code> until it reaches <code class="literal">count</code>
  5699. </li></ul></div><p>Let’s say you want to change the permissions of a given file; using
  5700. this syntax, you will need to write:</p><pre class="screen">/usr/bin/foo f 755 0 0 - - - - -
  5701. /usr/bin/bar f 755 root root - - - - -
  5702. /data/buz f 644 buz-user buz-group - - - - -</pre><p>Alternatively, if you want to change owner/permission of a directory
  5703. recursively, you can write (to set UID to foo, GID to bar and access
  5704. rights to rwxr-x--- for the directory /usr/share/myapp and all files
  5705. and directories below it):</p><pre class="screen">/usr/share/myapp r 750 foo bar - - - - -</pre><p>On the other hand, if you want to create the device file <code class="literal">/dev/hda</code>
  5706. and the corresponding 15 files for the partitions, you will need for
  5707. <code class="literal">/dev/hda</code>:</p><pre class="screen">/dev/hda b 640 root root 3 0 0 0 -</pre><p>and then for device files corresponding to the partitions of
  5708. <code class="literal">/dev/hda</code>, <code class="literal">/dev/hdaX</code>, <code class="literal">X</code> ranging from 1 to 15:</p><pre class="screen">/dev/hda b 640 root root 3 1 1 1 15</pre><p>Extended attributes are supported if
  5709. <code class="literal">BR2_ROOTFS_DEVICE_TABLE_SUPPORTS_EXTENDED_ATTRIBUTES</code> is enabled.
  5710. This is done by adding a line starting with <code class="literal">|xattr</code> after
  5711. the line describing the file. Right now, only capability
  5712. is supported as extended attribute.</p><div class="informaltable"><table class="informaltable" cellpadding="4px" style="border-collapse: collapse;border-top: 3px solid #527bbd; border-bottom: 3px solid #527bbd; border-left: 3px solid #527bbd; border-right: 3px solid #527bbd; "><colgroup><col class="col_1" /><col class="col_2" /></colgroup><tbody><tr><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>|xattr</p></td><td style="" align="left" valign="top"><p>capability</p></td></tr></tbody></table></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5713. <code class="literal">|xattr</code> is a "flag" that indicate an extended attribute
  5714. </li><li class="listitem">
  5715. <code class="literal">capability</code> is a capability to add to the previous file
  5716. </li></ul></div><p>If you want to add the capability cap_sys_admin to the binary foo,
  5717. you will write :</p><pre class="screen">/usr/bin/foo f 755 root root - - - - -
  5718. |xattr cap_sys_admin+eip</pre><p>You can add several capabilities to a file by using several <code class="literal">|xattr</code> lines.
  5719. If you want to add the capability cap_sys_admin and cap_net_admin to the
  5720. binary foo, you will write :</p><pre class="screen">/usr/bin/foo f 755 root root - - - - -
  5721. |xattr cap_sys_admin+eip
  5722. |xattr cap_net_admin+eip</pre></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="makeuser-syntax"></a>Chapter 26. Makeusers syntax documentation</h2></div></div></div><p>The syntax to create users is inspired by the makedev syntax, above, but
  5723. is specific to Buildroot.</p><p>The syntax for adding a user is a space-separated list of fields, one
  5724. user per line; the fields are:</p><div class="informaltable"><table class="informaltable" cellpadding="4px" style="border-collapse: collapse;border-top: 3px solid #527bbd; border-bottom: 3px solid #527bbd; border-left: 3px solid #527bbd; border-right: 3px solid #527bbd; "><colgroup><col class="col_1" /><col class="col_2" /><col class="col_3" /><col class="col_4" /><col class="col_5" /><col class="col_6" /><col class="col_7" /><col class="col_8" /><col class="col_9" /></colgroup><tbody><tr><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>username</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>uid</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>group</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>gid</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>password</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>home</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>shell</p></td><td style="border-right: 1px solid #527bbd; " align="left" valign="top"><p>groups</p></td><td style="" align="left" valign="top"><p>comment</p></td></tr></tbody></table></div><p>Where:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5725. <code class="literal">username</code> is the desired user name (aka login name) for the user.
  5726. It can not be <code class="literal">root</code>, and must be unique. If set to <code class="literal">-</code>, then just a
  5727. group will be created.
  5728. </li><li class="listitem">
  5729. <code class="literal">uid</code> is the desired UID for the user. It must be unique, and not
  5730. <code class="literal">0</code>. If set to <code class="literal">-1</code>, then a unique UID will be computed by Buildroot
  5731. in the range [1000…1999]
  5732. </li><li class="listitem">
  5733. <code class="literal">group</code> is the desired name for the user’s main group. It can not
  5734. be <code class="literal">root</code>. If the group does not exist, it will be created.
  5735. </li><li class="listitem">
  5736. <code class="literal">gid</code> is the desired GID for the user’s main group. It must be unique,
  5737. and not <code class="literal">0</code>. If set to <code class="literal">-1</code>, and the group does not already exist, then
  5738. a unique GID will be computed by Buildroot in the range [1000..1999]
  5739. </li><li class="listitem">
  5740. <code class="literal">password</code> is the crypt(3)-encoded password. If prefixed with <code class="literal">!</code>,
  5741. then login is disabled. If prefixed with <code class="literal">=</code>, then it is interpreted
  5742. as clear-text, and will be crypt-encoded (using MD5). If prefixed with
  5743. <code class="literal">!=</code>, then the password will be crypt-encoded (using MD5) and login
  5744. will be disabled. If set to <code class="literal">*</code>, then login is not allowed. If set to
  5745. <code class="literal">-</code>, then no password value will be set.
  5746. </li><li class="listitem">
  5747. <code class="literal">home</code> is the desired home directory for the user. If set to <span class="emphasis"><em>-</em></span>, no
  5748. home directory will be created, and the user’s home will be <code class="literal">/</code>.
  5749. Explicitly setting <code class="literal">home</code> to <code class="literal">/</code> is not allowed.
  5750. </li><li class="listitem">
  5751. <code class="literal">shell</code> is the desired shell for the user. If set to <code class="literal">-</code>, then
  5752. <code class="literal">/bin/false</code> is set as the user’s shell.
  5753. </li><li class="listitem">
  5754. <code class="literal">groups</code> is the comma-separated list of additional groups the user
  5755. should be part of. If set to <code class="literal">-</code>, then the user will be a member of
  5756. no additional group. Missing groups will be created with an arbitrary
  5757. <code class="literal">gid</code>.
  5758. </li><li class="listitem">
  5759. <code class="literal">comment</code> (aka <a class="ulink" href="https://en.wikipedia.org/wiki/Gecos_field" target="_top">GECOS</a>
  5760. field) is an almost-free-form text.
  5761. </li></ul></div><p>There are a few restrictions on the content of each field:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5762. except for <code class="literal">comment</code>, all fields are mandatory.
  5763. </li><li class="listitem">
  5764. except for <code class="literal">comment</code>, fields may not contain spaces.
  5765. </li><li class="listitem">
  5766. no field may contain a colon (<code class="literal">:</code>).
  5767. </li></ul></div><p>If <code class="literal">home</code> is not <code class="literal">-</code>, then the home directory, and all files below,
  5768. will belong to the user and its main group.</p><p>Examples:</p><pre class="screen">foo -1 bar -1 !=blabla /home/foo /bin/sh alpha,bravo Foo user</pre><p>This will create this user:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5769. <code class="literal">username</code> (aka login name) is: <code class="literal">foo</code>
  5770. </li><li class="listitem">
  5771. <code class="literal">uid</code> is computed by Buildroot
  5772. </li><li class="listitem">
  5773. main <code class="literal">group</code> is: <code class="literal">bar</code>
  5774. </li><li class="listitem">
  5775. main group <code class="literal">gid</code> is computed by Buildroot
  5776. </li><li class="listitem">
  5777. clear-text <code class="literal">password</code> is: <code class="literal">blabla</code>, will be crypt(3)-encoded, and login is disabled.
  5778. </li><li class="listitem">
  5779. <code class="literal">home</code> is: <code class="literal">/home/foo</code>
  5780. </li><li class="listitem">
  5781. <code class="literal">shell</code> is: <code class="literal">/bin/sh</code>
  5782. </li><li class="listitem">
  5783. <code class="literal">foo</code> is also a member of <code class="literal">groups</code>: <code class="literal">alpha</code> and <code class="literal">bravo</code>
  5784. </li><li class="listitem">
  5785. <code class="literal">comment</code> is: <code class="literal">Foo user</code>
  5786. </li></ul></div><pre class="screen">test 8000 wheel -1 = - /bin/sh - Test user</pre><p>This will create this user:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  5787. <code class="literal">username</code> (aka login name) is: <code class="literal">test</code>
  5788. </li><li class="listitem">
  5789. <code class="literal">uid</code> is : <code class="literal">8000</code>
  5790. </li><li class="listitem">
  5791. main <code class="literal">group</code> is: <code class="literal">wheel</code>
  5792. </li><li class="listitem">
  5793. main group <code class="literal">gid</code> is computed by Buildroot, and will use the value defined in the rootfs skeleton
  5794. </li><li class="listitem">
  5795. <code class="literal">password</code> is empty (aka no password).
  5796. </li><li class="listitem">
  5797. <code class="literal">home</code> is <code class="literal">/</code> but will not belong to <code class="literal">test</code>
  5798. </li><li class="listitem">
  5799. <code class="literal">shell</code> is: <code class="literal">/bin/sh</code>
  5800. </li><li class="listitem">
  5801. <code class="literal">test</code> is not a member of any additional <code class="literal">groups</code>
  5802. </li><li class="listitem">
  5803. <code class="literal">comment</code> is: <code class="literal">Test user</code>
  5804. </li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="migrating-from-ol-versions"></a>Chapter 27. Migrating from older Buildroot versions</h2></div></div></div><p>Some versions have introduced backward incompatibilities. This section
  5805. explains those incompatibilities, and for each explains what to do to
  5806. complete the migration.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="br2-external-converting"></a>27.1. Migrating to 2016.11</h2></div></div></div><p>Before Buildroot 2016.11, it was possible to use only one br2-external
  5807. tree at once. With Buildroot 2016.11 came the possibility to use more
  5808. than one simultaneously (for details, see <a class="xref" href="#outside-br-custom" title="9.2. Keeping customizations outside of Buildroot">Section 9.2, “Keeping customizations outside of Buildroot”</a>).</p><p>This however means that older br2-external trees are not usable as-is.
  5809. A minor change has to be made: adding a name to your br2-external tree.</p><p>This can be done very easily in just a few steps:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  5810. First, create a new file named <code class="literal">external.desc</code>, at the root of your
  5811. br2-external tree, with a single line defining the name of your
  5812. br2-external tree:
  5813. </p><pre class="screen">$ echo 'name: NAME_OF_YOUR_TREE' &gt;external.desc</pre><p><strong>Note. </strong>Be careful when choosing a name: It has to be unique and be made
  5814. with only ASCII characters from the set <code class="literal">[A-Za-z0-9_]</code>.</p></li><li class="listitem"><p class="simpara">
  5815. Then, change every occurence of <code class="literal">BR2_EXTERNAL</code> in your br2-external
  5816. tree with the new variable:
  5817. </p><pre class="screen">$ find . -type f | xargs sed -i 's/BR2_EXTERNAL/BR2_EXTERNAL_NAME_OF_YOUR_TREE_PATH/g'</pre></li></ul></div><p>Now, your br2-external tree can be used with Buildroot 2016.11 onward.</p><p><strong>Note: </strong>This change makes your br2-external tree incompatible with Buildroot
  5818. before 2016.11.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="migrating-host-usr"></a>27.2. Migrating to 2017.08</h2></div></div></div><p>Before Buildroot 2017.08, host packages were installed in <code class="literal">$(HOST_DIR)/usr</code>
  5819. (with e.g. the autotools' <code class="literal">--prefix=$(HOST_DIR)/usr</code>). With Buildroot
  5820. 2017.08, they are now installed directly in <code class="literal">$(HOST_DIR)</code>.</p><p>Whenever a package installs an executable that is linked with a library
  5821. in <code class="literal">$(HOST_DIR)/lib</code>, it must have an RPATH pointing to that directory.</p><p>An RPATH pointing to <code class="literal">$(HOST_DIR)/usr/lib</code> is no longer accepted.</p></div></div></div></div></body></html>