12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807 |
- <?xml version="1.0" encoding="UTF-8"?>
- <!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 & 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="#idm3189">Config script: <span class="emphasis"><em>divine</em></span> package</a></dt><dt>18.2. <a href="#idm3196">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 2020.11.1 manual generated on 2020-12-27
- 14:25:12 UTC from git revision 804a9e1865</p><p>The Buildroot manual is written by the Buildroot developers.
- It is licensed under the GNU General Public License, version 2. Refer to the
- <a class="ulink" href="http://git.buildroot.org/buildroot/tree/COPYING?id=804a9e18656c1584b059129e0b5cebe2a2405fac" target="_top">COPYING</a>
- 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
- building a complete Linux system for an embedded system, using
- cross-compilation.</p><p>In order to achieve this, Buildroot is able to generate a
- cross-compilation toolchain, a root filesystem, a Linux kernel image
- and a bootloader for your target. Buildroot can be used for any
- combination of these options, independently (you can for example use
- an existing cross-compilation toolchain, and build only your root
- filesystem with Buildroot).</p><p>Buildroot is useful mainly for people working with embedded systems.
- Embedded systems often use processors that are not the regular x86
- processors everyone is used to having in his PC. They can be PowerPC
- processors, MIPS processors, ARM processors, etc.</p><p>Buildroot supports numerous processors and their variants; it also
- comes with default configurations for several boards available
- off-the-shelf. Besides this, a number of third-party projects are based on,
- or develop their BSP <a href="#ftn.idm24" class="footnote" id="idm24"><sup class="footnote">[1]</sup></a> or
- 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
- compilation, certain standard Linux utilities are expected to be
- already installed on the host system. Below you will find an overview of
- the mandatory and optional packages (note that package names may vary
- 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">
- Build tools:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <code class="literal">which</code>
- </li><li class="listitem">
- <code class="literal">sed</code>
- </li><li class="listitem">
- <code class="literal">make</code> (version 3.81 or any later)
- </li><li class="listitem">
- <code class="literal">binutils</code>
- </li><li class="listitem">
- <code class="literal">build-essential</code> (only for Debian based systems)
- </li><li class="listitem">
- <code class="literal">gcc</code> (version 4.8 or any later)
- </li><li class="listitem">
- <code class="literal">g++</code> (version 4.8 or any later)
- </li><li class="listitem">
- <code class="literal">bash</code>
- </li><li class="listitem">
- <code class="literal">patch</code>
- </li><li class="listitem">
- <code class="literal">gzip</code>
- </li><li class="listitem">
- <code class="literal">bzip2</code>
- </li><li class="listitem">
- <code class="literal">perl</code> (version 5.8.7 or any later)
- </li><li class="listitem">
- <code class="literal">tar</code>
- </li><li class="listitem">
- <code class="literal">cpio</code>
- </li><li class="listitem">
- <code class="literal">unzip</code>
- </li><li class="listitem">
- <code class="literal">rsync</code>
- </li><li class="listitem">
- <code class="literal">file</code> (must be in <code class="literal">/usr/bin/file</code>)
- </li><li class="listitem">
- <code class="literal">bc</code>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Source fetching tools:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <code class="literal">wget</code>
- </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">
- Recommended dependencies:
- </p><p class="simpara">Some features or utilities in Buildroot, like the legal-info, or the
- graph generation tools, have additional dependencies. Although they
- 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">
- <code class="literal">python</code> (version 2.7 or any later)
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Configuration interface dependencies:
- </p><p class="simpara">For these libraries, you need to install both runtime and development
- data, which in many distributions are packaged separately. The
- 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">
- <code class="literal">ncurses5</code> to use the <span class="emphasis"><em>menuconfig</em></span> interface
- </li><li class="listitem">
- <code class="literal">qt5</code> to use the <span class="emphasis"><em>xconfig</em></span> interface
- </li><li class="listitem">
- <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
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Source fetching tools:
- </p><p class="simpara">In the official tree, most of the package sources are retrieved using
- <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
- available through a version control system. Moreover, Buildroot is
- capable of downloading sources via other tools, like <code class="literal">rsync</code> or <code class="literal">scp</code>
- (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
- packages using any of these methods, you will need to install the
- corresponding tool on the host system:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <code class="literal">bazaar</code>
- </li><li class="listitem">
- <code class="literal">cvs</code>
- </li><li class="listitem">
- <code class="literal">git</code>
- </li><li class="listitem">
- <code class="literal">mercurial</code>
- </li><li class="listitem">
- <code class="literal">rsync</code>
- </li><li class="listitem">
- <code class="literal">scp</code>
- </li><li class="listitem">
- <code class="literal">subversion</code>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Java-related packages, if the Java Classpath needs to be built for
- the target system:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- The <code class="literal">javac</code> compiler
- </li><li class="listitem">
- The <code class="literal">jar</code> tool
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Documentation generation tools:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <code class="literal">asciidoc</code>, version 8.6.3 or higher
- </li><li class="listitem">
- <code class="literal">w3m</code>
- </li><li class="listitem">
- <code class="literal">python</code> with the <code class="literal">argparse</code> module (automatically present in 2.7+ and 3.2+)
- </li><li class="listitem">
- <code class="literal">dblatex</code> (required for the pdf manual only)
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Graph generation tools:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <code class="literal">graphviz</code> to use <span class="emphasis"><em>graph-depends</em></span> and <span class="emphasis"><em><pkg>-graph-depends</em></span>
- </li><li class="listitem">
- <code class="literal">python-matplotlib</code> to use <span class="emphasis"><em>graph-build</em></span>
- </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
- November. Release numbers are in the format YYYY.MM, so for example
- 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
- available in <code class="literal">support/misc/Vagrantfile</code> in the Buildroot source tree
- to quickly set up a virtual machine with the needed dependencies to
- get started.</p><p>If you want to setup an isolated buildroot environment on Linux or Mac
- 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(
- "https://buildroot.org/downloads/Vagrantfile","Vagrantfile");
- vagrant up</pre><p>If you want to follow development, you can use the daily snapshots or
- make a clone of the Git repository. Refer to the
- <a class="ulink" href="http://buildroot.org/download" target="_top">Download page</a> of the Buildroot website
- 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
- is no need to be root to configure and use Buildroot. By running all
- commands as a regular user, you protect your system against packages
- behaving badly during compilation and installation.</p><p>The first step when using Buildroot is to create a configuration.
- Buildroot has a nice configuration tool similar to the one you can
- find in the <a class="ulink" href="http://www.kernel.org/" target="_top">Linux kernel</a> or in
- <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
- utility (including the interface), so you may need to install
- "development" packages for relevant libraries used by the
- configuration utilities. Refer to <a class="xref" href="#requirement" title="Chapter 2. System requirements">Chapter 2, <em>System requirements</em></a> for more details,
- specifically the <a class="link" href="#requirement-optional" title="2.2. Optional packages">optional requirements</a>
- to get the dependencies of your favorite interface.</p><p>For each menu entry in the configuration tool, you can find associated
- 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>
- for details on some specific configuration aspects.</p><p>Once everything is configured, the configuration tool generates a
- <code class="literal">.config</code> file that contains the entire configuration. This file will be
- 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
- running <code class="literal">make -jN</code> is not necessary. There is however experimental
- support for top-level parallel build, see
- <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">
- download source files (as required);
- </li><li class="listitem">
- configure, build and install the cross-compilation toolchain, or
- simply import an external toolchain;
- </li><li class="listitem">
- configure, build and install selected target packages;
- </li><li class="listitem">
- build a kernel image, if selected;
- </li><li class="listitem">
- build a bootloader image, if selected;
- </li><li class="listitem">
- create a root filesystem in selected formats.
- </li></ul></div><p>Buildroot output is stored in a single directory, <code class="literal">output/</code>.
- This directory contains several subdirectories:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">images/</code> where all the images (kernel image, bootloader and root
- filesystem images) are stored. These are the files you need to put
- on your target system.
- </li><li class="listitem">
- <code class="literal">build/</code> where all the components are built (this includes tools
- needed by Buildroot on the host and packages compiled for the
- target). This directory contains one subdirectory for each of these
- components.
- </li><li class="listitem">
- <code class="literal">host/</code> contains both the tools built for the host, and the sysroot
- of the target toolchain. The former is an installation of tools
- compiled for the host that are needed for the proper execution of
- Buildroot, including the cross-compilation toolchain. The latter
- is a hierarchy similar to a root filesystem hierarchy. It contains
- the headers and libraries of all user-space packages that provide
- and install libraries used by other packages. However, this
- directory is <span class="emphasis"><em>not</em></span> intended to be the root filesystem for the target:
- it contains a lot of development files, unstripped binaries and
- libraries that make it far too big for an embedded system. These
- development files are used to compile libraries and applications for
- the target that depend on other libraries.
- </li><li class="listitem">
- <code class="literal">staging/</code> is a symlink to the target toolchain sysroot inside
- <code class="literal">host/</code>, which exists for backwards compatibility.
- </li><li class="listitem">
- <code class="literal">target/</code> which contains <span class="emphasis"><em>almost</em></span> the complete root filesystem for
- the target: everything needed is present except the device files in
- <code class="literal">/dev/</code> (Buildroot can’t create them because Buildroot doesn’t run
- as root and doesn’t want to run as root). Also, it doesn’t have the correct
- permissions (e.g. setuid for the busybox binary). Therefore, this directory
- <span class="strong"><strong>should not be used on your target</strong></span>. Instead, you should use one of
- the images built in the <code class="literal">images/</code> directory. If you need an
- extracted image of the root filesystem for booting over NFS, then
- use the tarball image generated in <code class="literal">images/</code> and extract it as
- root. Compared to <code class="literal">staging/</code>, <code class="literal">target/</code> contains only the files and
- libraries needed to run the selected target applications: the
- development files (headers, etc.) are not present, the binaries are
- stripped.
- </li></ul></div><p>These commands, <code class="literal">make menuconfig|nconfig|gconfig|xconfig</code> and <code class="literal">make</code>, are the
- basic ones that allow to easily and quickly generate images fitting
- your needs, with all the features and applications you enabled.</p><p>More details about the "make" command usage are given in
- <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
- information in its community and outside.</p><p>Each of those ways may interest you if you are looking for some help,
- want to understand Buildroot or contribute to the project.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
- Mailing List
- </span></dt><dd><p class="simpara">Buildroot has a mailing list for discussion and development. It is the
- 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
- this list. You can subscribe via the
- <a class="ulink" href="http://lists.buildroot.org/mailman/listinfo/buildroot" target="_top">mailing list info
- page</a>.</p><p class="simpara">Mails that are sent to the mailing list are also available in the
- <a class="ulink" href="http://lists.buildroot.org/pipermail/buildroot" target="_top">mailing list archives</a> and
- via <a class="ulink" href="http://gmane.org" target="_top">Gmane</a>, at
- <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>.
- Please search the mailing list archives before asking questions, since
- there is a good chance someone else has asked the same question before.</p></dd><dt><span class="term">
- IRC
- </span></dt><dd><p class="simpara">The Buildroot IRC channel <a class="ulink" href="irc://freenode.net/#buildroot" target="_top">#buildroot</a> is
- hosted on <a class="ulink" href="http://webchat.freenode.net" target="_top">Freenode</a>. It is a useful place to
- 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
- 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
- better as it will reach more people, both developers and users.</p></dd><dt><span class="term">
- Bug tracker
- </span></dt><dd>Bugs in Buildroot can be reported via the mailing list or alternatively
- via the <a class="ulink" href="https://bugs.buildroot.org/buglist.cgi?product=buildroot" target="_top">Buildroot
- 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
- report.</dd><dt><span class="term">
- Wiki
- </span></dt><dd><a class="ulink" href="http://elinux.org/Buildroot" target="_top">The Buildroot wiki page</a> is hosted on
- the <a class="ulink" href="http://elinux.org" target="_top">eLinux</a> wiki. It contains some useful links, an
- overview of past and upcoming events, and a TODO list.</dd><dt><span class="term">
- Patchwork
- </span></dt><dd><p class="simpara">Patchwork is a web-based patch tracking system designed to facilitate
- the contribution and management of contributions to an open-source
- project. Patches that have been sent to a mailing list are 'caught' by
- the system, and appear on a web page. Any comments posted that
- reference the patch are appended to the patch page too. For more
- information on Patchwork see
- <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
- maintainer to ensure patches aren’t missed. It is also used by Buildroot
- 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>).
- However, since the website exposes patches and their corresponding
- review comments in a clean and concise web interface, it can be useful
- for all Buildroot developers.</p><p class="simpara">The Buildroot patch management interface is available at
- <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
- providing details about the option.</p><p>The <code class="literal">make *config</code> commands also offer a search tool. Read the help
- 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">
- in <span class="emphasis"><em>menuconfig</em></span>, the search tool is called by pressing <code class="literal">/</code>;
- </li><li class="listitem">
- 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>.
- </li></ul></div><p>The result of the search shows the help message of the matching items.
- In <span class="emphasis"><em>menuconfig</em></span>, numbers in the left column provide a shortcut to the
- corresponding entry. Just type this number to directly jump to the
- entry, or to the containing menu in case the entry is not selectable due
- to a missing dependency.</p><p>Although the menu structure and the help text of the entries should be
- sufficiently self-explanatory, a number of topics require additional
- explanation that cannot easily be covered in the help text and are
- 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
- code for your system. It consists of a compiler (in our case, <code class="literal">gcc</code>),
- binary utils like assembler and linker (in our case, <code class="literal">binutils</code>) and a
- C standard library (for example
- <a class="ulink" href="http://www.gnu.org/software/libc/libc.html" target="_top">GNU Libc</a>,
- <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
- a compilation toolchain that you can use to compile an application
- that runs on your system. If you’re using a PC, your compilation
- toolchain runs on an x86 processor and generates code for an x86
- processor. Under most Linux systems, the compilation toolchain uses
- the GNU libc (glibc) as the C standard library. This compilation
- toolchain is called the "host compilation toolchain". The machine on
- which it is running, and on which you’re working, is called the "host
- 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
- Buildroot has nothing to do with it (other than using it to build a
- cross-compilation toolchain and other tools that are run on the
- development host).</p><p>As said above, the compilation toolchain that comes with your system
- runs on and generates code for the processor in your host system. As
- your embedded system has a different processor, you need a
- cross-compilation toolchain - a compilation toolchain that runs on
- your <span class="emphasis"><em>host system</em></span> but generates code for your <span class="emphasis"><em>target system</em></span> (and
- target processor). For example, if your host system uses x86 and your
- target system uses ARM, the regular compilation toolchain on your host
- runs on x86 and generates code for x86, while the cross-compilation
- 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">
- The <span class="strong"><strong>internal toolchain backend</strong></span>, called <code class="literal">Buildroot toolchain</code> in
- the configuration interface.
- </li><li class="listitem">
- The <span class="strong"><strong>external toolchain backend</strong></span>, called <code class="literal">External toolchain</code> in
- the configuration interface.
- </li></ul></div><p>The choice between these two solutions is done using the <code class="literal">Toolchain
- Type</code> option in the <code class="literal">Toolchain</code> menu. Once one solution has been
- chosen, a number of configuration options appear, they are detailed in
- 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
- by itself a cross-compilation toolchain, before building the userspace
- applications and libraries for your target embedded system.</p><p>This backend supports several C libraries:
- <a class="ulink" href="http://www.uclibc-ng.org" target="_top">uClibc-ng</a>,
- <a class="ulink" href="http://www.gnu.org/software/libc/libc.html" target="_top">glibc</a> and
- <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
- most important ones allow to:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Change the version of the Linux kernel headers used to build the
- toolchain. This item deserves a few explanations. In the process of
- building a cross-compilation toolchain, the C library is being
- built. This library provides the interface between userspace
- applications and the Linux kernel. In order to know how to "talk"
- to the Linux kernel, the C library needs to have access to the
- <span class="emphasis"><em>Linux kernel headers</em></span> (i.e. the <code class="literal">.h</code> files from the kernel), which
- define the interface between userspace and the kernel (system
- calls, data structures, etc.). Since this interface is backward
- compatible, the version of the Linux kernel headers used to build
- your toolchain do not need to match <span class="emphasis"><em>exactly</em></span> the version of the
- Linux kernel you intend to run on your embedded system. They only
- need to have a version equal or older to the version of the Linux
- kernel you intend to run. If you use kernel headers that are more
- recent than the Linux kernel you run on your embedded system, then
- the C library might be using interfaces that are not provided by
- your Linux kernel.
- </li><li class="listitem">
- Change the version of the GCC compiler, binutils and the C library.
- </li><li class="listitem">
- Select a number of toolchain options (uClibc only): whether the
- toolchain should have RPC support (used mainly for NFS),
- wide-char support, locale support (for internationalization),
- C++ support or thread support. Depending on which options you choose,
- the number of userspace applications and libraries visible in
- Buildroot menus will change: many applications and libraries require
- certain toolchain options to be enabled. Most packages show a comment
- when a certain toolchain option is required to be able to enable
- those packages. If needed, you can further refine the uClibc
- configuration by running <code class="literal">make uclibc-menuconfig</code>. Note however that
- all packages in Buildroot are tested against the default uClibc
- configuration bundled in Buildroot: if you deviate from this
- configuration by removing features from uClibc, some packages may no
- longer build.
- </li></ul></div><p>It is worth noting that whenever one of those options is modified,
- then the entire toolchain and system must be rebuilt. 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>.</p><p>Advantages of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Well integrated with Buildroot
- </li><li class="listitem">
- Fast, only builds what’s necessary
- </li></ul></div><p>Drawbacks of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Rebuilding the toolchain is needed when doing <code class="literal">make clean</code>, which
- takes time. If you’re trying to reduce your build time, consider
- using the <span class="emphasis"><em>External toolchain backend</em></span>.
- </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
- cross-compilation toolchains. Buildroot knows about a number of
- well-known cross-compilation toolchains (from
- <a class="ulink" href="http://www.linaro.org" target="_top">Linaro</a> for ARM,
- <a class="ulink" href="http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/" target="_top">Sourcery
- CodeBench</a> for ARM, x86-64, PowerPC, and MIPS, and is capable of
- downloading them automatically, or it can be pointed to a custom
- 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">
- Use a predefined external toolchain profile, and let Buildroot
- download, extract and install the toolchain. Buildroot already knows
- about a few CodeSourcery and Linaro toolchains. Just select the
- toolchain profile in <code class="literal">Toolchain</code> from the available ones. This is
- definitely the easiest solution.
- </li><li class="listitem">
- Use a predefined external toolchain profile, but instead of having
- Buildroot download and extract the toolchain, you can tell Buildroot
- where your toolchain is already installed on your system. Just
- select the toolchain profile in <code class="literal">Toolchain</code> through the available
- ones, unselect <code class="literal">Download toolchain automatically</code>, and fill the
- <code class="literal">Toolchain path</code> text entry with the path to your cross-compiling
- toolchain.
- </li><li class="listitem">
- Use a completely custom external toolchain. This is particularly
- useful for toolchains generated using crosstool-NG or with Buildroot
- itself. To do this, select the <code class="literal">Custom toolchain</code> solution in the
- <code class="literal">Toolchain</code> list. You need to fill the <code class="literal">Toolchain path</code>, <code class="literal">Toolchain
- prefix</code> and <code class="literal">External toolchain C library</code> options. Then, you have
- to tell Buildroot what your external toolchain supports. If your
- external toolchain uses the <span class="emphasis"><em>glibc</em></span> library, you only have to tell
- whether your toolchain supports C++ or not and whether it has
- built-in RPC support. If your external toolchain uses the <span class="emphasis"><em>uClibc</em></span>
- library, then you have to tell Buildroot if it supports RPC,
- wide-char, locale, program invocation, threads and C++.
- At the beginning of the execution, Buildroot will tell you if
- the selected options do not match the toolchain configuration.
- </li></ul></div><p>Our external toolchain support has been tested with toolchains from
- CodeSourcery and Linaro, toolchains generated by
- <a class="ulink" href="http://crosstool-ng.org" target="_top">crosstool-NG</a>, and toolchains generated by
- Buildroot itself. In general, all toolchains that support the
- <span class="emphasis"><em>sysroot</em></span> feature should work. If not, do not hesitate to contact the
- developers.</p><p>We do not support toolchains or SDK generated by OpenEmbedded or
- Yocto, because these toolchains are not pure toolchains (i.e. just the
- compiler, binutils, the C and C++ libraries). Instead these toolchains
- come with a very large set of pre-compiled libraries and
- programs. Therefore, Buildroot cannot import the <span class="emphasis"><em>sysroot</em></span> of the
- toolchain, as it would contain hundreds of megabytes of pre-compiled
- libraries that are normally built by Buildroot.</p><p>We also do not support using the distribution toolchain (i.e. the
- gcc/binutils/C library installed by your distribution) as the
- toolchain to build software for the target. This is because your
- distribution toolchain is not a "pure" toolchain (i.e. only with the
- C/C++ library), so we cannot import it properly into the Buildroot
- build environment. So even if you are building a system for a x86 or
- x86_64 target, you have to generate a cross-compilation toolchain with
- Buildroot or crosstool-NG.</p><p>If you want to generate a custom toolchain for your project, that can
- be used as an external toolchain in Buildroot, our recommendation is
- to build it either with Buildroot itself (see
- <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
- <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">
- Allows to use well-known and well-tested cross-compilation
- toolchains.
- </li><li class="listitem">
- Avoids the build time of the cross-compilation toolchain, which is
- often very significant in the overall build time of an embedded
- Linux system.
- </li></ul></div><p>Drawbacks of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- If your pre-built external toolchain has a bug, may be hard to get a
- fix from the toolchain vendor, unless you build your external
- toolchain by yourself using Buildroot or Crosstool-NG.
- </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
- external toolchain. Here are a series of steps to build an internal
- toolchain and package it up for reuse by Buildroot itself (or other
- 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">
- Select the appropriate <span class="strong"><strong>Target options</strong></span> for your target CPU
- architecture
- </li><li class="listitem">
- In the <span class="strong"><strong>Toolchain</strong></span> menu, keep the default of <span class="strong"><strong>Buildroot toolchain</strong></span>
- for <span class="strong"><strong>Toolchain type</strong></span>, and configure your toolchain as desired
- </li><li class="listitem">
- 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
- system</strong></span> and <span class="strong"><strong>none</strong></span> as <span class="strong"><strong>/bin/sh</strong></span>
- </li><li class="listitem">
- In the <span class="strong"><strong>Target packages</strong></span> menu, disable <span class="strong"><strong>BusyBox</strong></span>
- </li><li class="listitem">
- In the <span class="strong"><strong>Filesystem images</strong></span> menu, disable <span class="strong"><strong>tar the root filesystem</strong></span>
- </li></ul></div><p>Then, we can trigger the build, and also ask Buildroot to generate a
- SDK. This will conveniently generate for us a tarball which contains
- 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
- <code class="literal">arm-buildroot-linux-uclibcgnueabi_sdk-buildroot.tar.gz</code>. Save this
- tarball, as it is now the toolchain that you can re-use as an external
- 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">
- Set <span class="strong"><strong>Toolchain type</strong></span> to <span class="strong"><strong>External toolchain</strong></span>
- </li><li class="listitem">
- Set <span class="strong"><strong>Toolchain</strong></span> to <span class="strong"><strong>Custom toolchain</strong></span>
- </li><li class="listitem">
- Set <span class="strong"><strong>Toolchain origin</strong></span> to <span class="strong"><strong>Toolchain to be downloaded and installed</strong></span>
- </li><li class="listitem">
- Set <span class="strong"><strong>Toolchain URL</strong></span> to <code class="literal">file:///path/to/your/sdk/tarball.tar.gz</code>
- </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,
- that transparently passes the appropriate options (according to the
- configuration) to the external toolchain programs. In case you need to
- debug this wrapper to check exactly what arguments are passed, you can
- 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">
- <code class="literal">0</code>, empty or not set: no debug
- </li><li class="listitem">
- <code class="literal">1</code>: trace all arguments on a single line
- </li><li class="listitem">
- <code class="literal">2</code>: trace one argument per line
- </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
- <span class="emphasis"><em>device files</em></span>, that allow userspace applications to access the
- hardware devices managed by the Linux kernel. Without these <span class="emphasis"><em>device
- files</em></span>, your userspace applications would not be able to use the
- hardware devices, even if they are properly recognized by the Linux
- kernel.</p><p>Under <code class="literal">System configuration</code>, <code class="literal">/dev management</code>, Buildroot offers four
- 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">
- The first solution is <span class="strong"><strong>Static using device table</strong></span>. This is the old
- classical way of handling device files in Linux. With this method,
- the device files are persistently stored in the root filesystem
- (i.e. they persist across reboots), and there is nothing that will
- automatically create and remove those device files when hardware
- devices are added or removed from the system. Buildroot therefore
- creates a standard set of device files using a <span class="emphasis"><em>device table</em></span>, the
- default one being stored in <code class="literal">system/device_table_dev.txt</code> in the
- Buildroot source code. This file is processed when Buildroot
- generates the final root filesystem image, and the <span class="emphasis"><em>device files</em></span>
- are therefore not visible in the <code class="literal">output/target</code> directory. The
- <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code> option allows to change the
- default device table used by Buildroot, or to add an additional
- device table, so that additional <span class="emphasis"><em>device files</em></span> are created by
- Buildroot during the build. So, if you use this method, and a
- <span class="emphasis"><em>device file</em></span> is missing in your system, you can for example create
- a <code class="literal">board/<yourcompany>/<yourproject>/device_table_dev.txt</code> file
- that contains the description of your additional <span class="emphasis"><em>device files</em></span>,
- and then you can set <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code> to
- <code class="literal">system/device_table_dev.txt
- board/<yourcompany>/<yourproject>/device_table_dev.txt</code>. For more
- details about the format of the device table file, see
- <a class="xref" href="#makedev-syntax" title="Chapter 25. Makedev syntax documentation">Chapter 25, <em>Makedev syntax documentation</em></a>.
- </li><li class="listitem">
- The second solution is <span class="strong"><strong>Dynamic using devtmpfs only</strong></span>. <span class="emphasis"><em>devtmpfs</em></span> is
- a virtual filesystem inside the Linux kernel that has been
- introduced in kernel 2.6.32 (if you use an older kernel, it is not
- possible to use this option). When mounted in <code class="literal">/dev</code>, this virtual
- filesystem will automatically make <span class="emphasis"><em>device files</em></span> appear and
- disappear as hardware devices are added and removed from the
- system. This filesystem is not persistent across reboots: it is
- filled dynamically by the kernel. Using <span class="emphasis"><em>devtmpfs</em></span> requires the
- following kernel configuration options to be enabled:
- <code class="literal">CONFIG_DEVTMPFS</code> and <code class="literal">CONFIG_DEVTMPFS_MOUNT</code>. When Buildroot is in
- charge of building the Linux kernel for your embedded device, it
- makes sure that those two options are enabled. However, if you
- build your Linux kernel outside of Buildroot, then it is your
- responsibility to enable those two options (if you fail to do so,
- your Buildroot system will not boot).
- </li><li class="listitem">
- The third solution is <span class="strong"><strong>Dynamic using devtmpfs + mdev</strong></span>. This method
- also relies on the <span class="emphasis"><em>devtmpfs</em></span> virtual filesystem detailed above (so
- the requirement to have <code class="literal">CONFIG_DEVTMPFS</code> and
- <code class="literal">CONFIG_DEVTMPFS_MOUNT</code> enabled in the kernel configuration still
- apply), but adds the <code class="literal">mdev</code> userspace utility on top of it. <code class="literal">mdev</code>
- is a program part of BusyBox that the kernel will call every time a
- device is added or removed. Thanks to the <code class="literal">/etc/mdev.conf</code>
- configuration file, <code class="literal">mdev</code> can be configured to for example, set
- specific permissions or ownership on a device file, call a script
- or application whenever a device appears or disappear,
- etc. Basically, it allows <span class="emphasis"><em>userspace</em></span> to react on device addition
- and removal events. <code class="literal">mdev</code> can for example be used to automatically
- load kernel modules when devices appear on the system. <code class="literal">mdev</code> is
- also important if you have devices that require a firmware, as it
- will be responsible for pushing the firmware contents to the
- kernel. <code class="literal">mdev</code> is a lightweight implementation (with fewer
- features) of <code class="literal">udev</code>. For more details about <code class="literal">mdev</code> and the syntax
- of its configuration file, see
- <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>.
- </li><li class="listitem">
- The fourth solution is <span class="strong"><strong>Dynamic using devtmpfs + eudev</strong></span>. This
- method also relies on the <span class="emphasis"><em>devtmpfs</em></span> virtual filesystem detailed
- above, but adds the <code class="literal">eudev</code> userspace daemon on top of it. <code class="literal">eudev</code>
- is a daemon that runs in the background, and gets called by the
- kernel when a device gets added or removed from the system. It is a
- more heavyweight solution than <code class="literal">mdev</code>, but provides higher
- flexibility. <code class="literal">eudev</code> is a standalone version of <code class="literal">udev</code>, the
- original userspace daemon used in most desktop Linux distributions,
- which is now part of Systemd. For more details, see
- <a class="ulink" href="http://en.wikipedia.org/wiki/Udev" target="_top">http://en.wikipedia.org/wiki/Udev</a>.
- </li></ul></div><p>The Buildroot developers recommendation is to start with the <span class="strong"><strong>Dynamic
- using devtmpfs only</strong></span> solution, until you have the need for userspace
- to be notified when devices are added/removed, or if firmwares are
- needed, in which case <span class="strong"><strong>Dynamic using devtmpfs + mdev</strong></span> is usually a
- good solution.</p><p>Note that if <code class="literal">systemd</code> is chosen as init system, /dev management will
- 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
- kernel (it carries the PID number 1), and is responsible for starting
- the userspace services and programs (for example: web server,
- graphical applications, other network servers, etc.).</p><p>Buildroot allows to use three different types of init systems, which
- 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">
- The first solution is <span class="strong"><strong>BusyBox</strong></span>. Amongst many programs, BusyBox has
- an implementation of a basic <code class="literal">init</code> program, which is sufficient
- for most embedded systems. Enabling the <code class="literal">BR2_INIT_BUSYBOX</code> will
- ensure BusyBox will build and install its <code class="literal">init</code> program. This is
- the default solution in Buildroot. The BusyBox <code class="literal">init</code> program will
- read the <code class="literal">/etc/inittab</code> file at boot to know what to do. The syntax
- of this file can be found in
- <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
- BusyBox <code class="literal">inittab</code> syntax is special: do not use a random <code class="literal">inittab</code>
- documentation from the Internet to learn about BusyBox
- <code class="literal">inittab</code>). The default <code class="literal">inittab</code> in Buildroot is stored in
- <code class="literal">system/skeleton/etc/inittab</code>. Apart from mounting a few important
- filesystems, the main job the default inittab does is to start the
- <code class="literal">/etc/init.d/rcS</code> shell script, and start a <code class="literal">getty</code> program (which
- provides a login prompt).
- </li><li class="listitem">
- The second solution is <span class="strong"><strong>systemV</strong></span>. This solution uses the old
- traditional <span class="emphasis"><em>sysvinit</em></span> program, packed in Buildroot in
- <code class="literal">package/sysvinit</code>. This was the solution used in most desktop
- Linux distributions, until they switched to more recent
- alternatives such as Upstart or Systemd. <code class="literal">sysvinit</code> also works with
- an <code class="literal">inittab</code> file (which has a slightly different syntax than the
- one from BusyBox). The default <code class="literal">inittab</code> installed with this init
- solution is located in <code class="literal">package/sysvinit/inittab</code>.
- </li><li class="listitem">
- The third solution is <span class="strong"><strong>systemd</strong></span>. <code class="literal">systemd</code> is the new generation
- init system for Linux. It does far more than traditional <span class="emphasis"><em>init</em></span>
- programs: aggressive parallelization capabilities, uses socket and
- D-Bus activation for starting services, offers on-demand starting
- of daemons, keeps track of processes using Linux control groups,
- supports snapshotting and restoring of the system state,
- etc. <code class="literal">systemd</code> will be useful on relatively complex embedded
- systems, for example the ones requiring D-Bus and services
- communicating between each other. It is worth noting that <code class="literal">systemd</code>
- brings a fairly big number of large dependencies: <code class="literal">dbus</code>, <code class="literal">udev</code>
- and more. For more details about <code class="literal">systemd</code>, see
- <a class="ulink" href="http://www.freedesktop.org/wiki/Software/systemd" target="_top">http://www.freedesktop.org/wiki/Software/systemd</a>.
- </li></ul></div><p>The solution recommended by Buildroot developers is to use the
- <span class="strong"><strong>BusyBox init</strong></span> as it is sufficient for most embedded
- 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
- configure, where the host is the machine on which the application will
- 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
- have already configured Buildroot itself, and have enabled the
- corresponding package.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
- BusyBox
- </span></dt><dd><p class="simpara">If you already have a BusyBox configuration file, you can directly
- specify this file in the Buildroot configuration, using
- <code class="literal">BR2_PACKAGE_BUSYBOX_CONFIG</code>. Otherwise, Buildroot will start from a
- default BusyBox configuration file.</p><p class="simpara">To make subsequent changes to the configuration, use <code class="literal">make
- 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
- environment variable, although this is not recommended. Refer to
- <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">
- uClibc
- </span></dt><dd>Configuration of uClibc is done in the same way as for BusyBox. The
- configuration variable to specify an existing configuration file is
- <code class="literal">BR2_UCLIBC_CONFIG</code>. The command to make subsequent changes is <code class="literal">make
- uclibc-menuconfig</code>.</dd><dt><span class="term">
- Linux kernel
- </span></dt><dd><p class="simpara">If you already have a kernel configuration file, you can directly
- specify this file in the Buildroot configuration, using
- <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
- by specifying a defconfig in the Buildroot configuration, using
- <code class="literal">BR2_LINUX_KERNEL_USE_DEFCONFIG</code>, or start by creating an empty file and
- specifying it as custom configuration file, using
- <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
- linux-menuconfig</code> to open the Linux configuration editor.</p></dd><dt><span class="term">
- Barebox
- </span></dt><dd>Configuration of Barebox is done in the same way as for the Linux
- kernel. The corresponding configuration variables are
- <code class="literal">BR2_TARGET_BAREBOX_USE_CUSTOM_CONFIG</code> and
- <code class="literal">BR2_TARGET_BAREBOX_USE_DEFCONFIG</code>. To open the configuration editor,
- use <code class="literal">make barebox-menuconfig</code>.</dd><dt><span class="term">
- U-Boot
- </span></dt><dd>Configuration of U-Boot (version 2015.04 or newer) is done in the same
- way as for the Linux kernel. The corresponding configuration variables
- are <code class="literal">BR2_TARGET_UBOOT_USE_CUSTOM_CONFIG</code> and
- <code class="literal">BR2_TARGET_UBOOT_USE_DEFCONFIG</code>. To open the configuration editor,
- 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>
- </p><pre class="screen"> $ make V=1 <target></pre><p>
- </p><p><strong>Display the list of boards with a defconfig: </strong>
- </p><pre class="screen"> $ make list-defconfigs</pre><p>
- </p><p><strong>Display all available targets: </strong>
- </p><pre class="screen"> $ make help</pre><p>
- </p><p>Not all targets are always available,
- 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">
- <code class="literal">busybox-menuconfig</code> only works when <code class="literal">busybox</code> is enabled;
- </li><li class="listitem">
- <code class="literal">linux-menuconfig</code> and <code class="literal">linux-savedefconfig</code> only work when
- <code class="literal">linux</code> is enabled;
- </li><li class="listitem">
- <code class="literal">uclibc-menuconfig</code> is only available when the uClibc C library is
- selected in the internal toolchain backend;
- </li><li class="listitem">
- <code class="literal">barebox-menuconfig</code> and <code class="literal">barebox-savedefconfig</code> only work when the
- <code class="literal">barebox</code> bootloader is enabled.
- </li><li class="listitem">
- <code class="literal">uboot-menuconfig</code> and <code class="literal">uboot-savedefconfig</code> only work when the
- <code class="literal">U-Boot</code> bootloader is enabled.
- </li></ul></div><p><strong>Cleaning: </strong>Explicit cleaning is required when any of the architecture or toolchain
- configuration options are changed.</p><p>To delete all build products (including build directories, host, staging
- 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.
- To generate the manual:</p><pre class="screen"> $ make manual-clean
- $ 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">
- A few tools are required to build the documentation (see:
- <a class="xref" href="#requirement-optional" title="2.2. Optional packages">Section 2.2, “Optional packages”</a>).
- </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
- not empty the compiler cache used by Buildroot. To delete it, refer
- 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'
- VARIABLE1=value_of_variable
- 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">
- <code class="literal">VARS</code> will limit the listing to variables which names match the
- specified make-patterns - this must be set else nothing is printed
- </li><li class="listitem">
- <code class="literal">QUOTED_VARS</code>, if set to <code class="literal">YES</code>, will single-quote the value
- </li><li class="listitem">
- <code class="literal">RAW_VARS</code>, if set to <code class="literal">YES</code>, will print the unexpanded value
- </li></ul></div><p>For example:</p><pre class="screen"> $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES
- BUSYBOX_DEPENDENCIES=skeleton toolchain
- BUSYBOX_FINAL_ALL_DEPENDENCIES=skeleton toolchain
- BUSYBOX_FINAL_DEPENDENCIES=skeleton toolchain
- BUSYBOX_FINAL_PATCH_DEPENDENCIES=
- BUSYBOX_RDEPENDENCIES=ncurses util-linux</pre><pre class="screen"> $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES QUOTED_VARS=YES
- BUSYBOX_DEPENDENCIES='skeleton toolchain'
- BUSYBOX_FINAL_ALL_DEPENDENCIES='skeleton toolchain'
- BUSYBOX_FINAL_DEPENDENCIES='skeleton toolchain'
- BUSYBOX_FINAL_PATCH_DEPENDENCIES=''
- BUSYBOX_RDEPENDENCIES='ncurses util-linux'</pre><pre class="screen"> $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES RAW_VARS=YES
- BUSYBOX_DEPENDENCIES=skeleton toolchain
- BUSYBOX_FINAL_ALL_DEPENDENCIES=$(sort $(BUSYBOX_FINAL_DEPENDENCIES) $(BUSYBOX_FINAL_PATCH_DEPENDENCIES))
- BUSYBOX_FINAL_DEPENDENCIES=$(sort $(BUSYBOX_DEPENDENCIES))
- BUSYBOX_FINAL_PATCH_DEPENDENCIES=$(sort $(BUSYBOX_PATCH_DEPENDENCIES))
- 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)
- $ echo $BUSYBOX_DEPENDENCIES
- 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
- be rebuilt when the system configuration is changed through <code class="literal">make
- menuconfig</code>, <code class="literal">make xconfig</code> or one of the other configuration
- tools. In some cases, Buildroot should rebuild the entire system, in
- some cases, only a specific subset of packages. But detecting this in
- a completely reliable manner is very difficult, and therefore the
- 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
- rebuild is necessary. As a hint, here are a few rules of thumb that
- can help you understand how to work with Buildroot:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- When the target architecture configuration is changed, a complete
- rebuild is needed. Changing the architecture variant, the binary
- format or the floating point strategy for example has an impact on
- the entire system.
- </li><li class="listitem">
- When the toolchain configuration is changed, a complete rebuild
- generally is needed. Changing the toolchain configuration often
- involves changing the compiler version, the type of C library or
- its configuration, or some other fundamental configuration item,
- and these changes have an impact on the entire system.
- </li><li class="listitem">
- When an additional package is added to the configuration, a full
- rebuild is not necessarily needed. Buildroot will detect that this
- package has never been built, and will build it. However, if this
- package is a library that can optionally be used by packages that
- have already been built, Buildroot will not automatically rebuild
- those. Either you know which packages should be rebuilt, and you
- can rebuild them manually, or you should do a full rebuild. For
- example, let’s suppose you have built a system with the <code class="literal">ctorrent</code>
- package, but without <code class="literal">openssl</code>. Your system works, but you realize
- you would like to have SSL support in <code class="literal">ctorrent</code>, so you enable the
- <code class="literal">openssl</code> package in Buildroot configuration and restart the
- build. Buildroot will detect that <code class="literal">openssl</code> should be built and
- will be build it, but it will not detect that <code class="literal">ctorrent</code> should be
- rebuilt to benefit from <code class="literal">openssl</code> to add OpenSSL support. You will
- either have to do a full rebuild, or rebuild <code class="literal">ctorrent</code> itself.
- </li><li class="listitem">
- When a package is removed from the configuration, Buildroot does
- not do anything special. It does not remove the files installed by
- this package from the target root filesystem or from the toolchain
- <span class="emphasis"><em>sysroot</em></span>. A full rebuild is needed to get rid of this
- package. However, generally you don’t necessarily need this package
- to be removed right now: you can wait for the next lunch break to
- restart the build from scratch.
- </li><li class="listitem">
- When the sub-options of a package are changed, the package is not
- automatically rebuilt. After making such changes, rebuilding only
- this package is often sufficient, unless enabling the package
- sub-option adds some features to the package that are useful for
- another package which has already been built. Again, Buildroot does
- not track when a package should be rebuilt: once a package has been
- built, it is never rebuilt unless explicitly told to do so.
- </li><li class="listitem">
- When a change to the root filesystem skeleton is made, a full
- rebuild is needed. However, when changes to the root filesystem
- overlay, a post-build script or a post-image script are made,
- there is no need for a full rebuild: a simple <code class="literal">make</code> invocation
- will take the changes into account.
- </li><li class="listitem">
- When a package listed in <code class="literal">FOO_DEPENDENCIES</code> is rebuilt or removed,
- the package <code class="literal">foo</code> is not automatically rebuilt. For example, if a
- package <code class="literal">bar</code> is listed in <code class="literal">FOO_DEPENDENCIES</code> with <code class="literal">FOO_DEPENDENCIES
- = bar</code> and the configuration of the <code class="literal">bar</code> package is changed, the
- configuration change would not result in a rebuild of package <code class="literal">foo</code>
- automatically. In this scenario, you may need to either rebuild any
- packages in your build which reference <code class="literal">bar</code> in their <code class="literal">DEPENDENCIES</code>,
- or perform a full rebuild to ensure any <code class="literal">bar</code> dependent packages are
- up to date.
- </li></ul></div><p>Generally speaking, when you’re facing a build error and you’re unsure
- of the potential consequences of the configuration changes you’ve
- made, do a full rebuild. If you get the same build error, then you are
- sure that the error is not related to partial rebuilds of packages,
- and if this error occurs with packages from the official Buildroot, do
- not hesitate to report the problem! As your experience with Buildroot
- progresses, you will progressively learn when a full rebuild is really
- 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
- rebuild a given package or how to remove a package without rebuilding
- everything from scratch.</p><p>Removing a package is unsupported by Buildroot without
- rebuilding from scratch. This is because Buildroot doesn’t keep track
- of which package installs what files in the <code class="literal">output/staging</code> and
- <code class="literal">output/target</code> directories, or which package would be compiled differently
- depending on the availability of another package.</p><p>The easiest way to rebuild a single package from scratch is to remove
- its build directory in <code class="literal">output/build</code>. Buildroot will then re-extract,
- re-configure, re-compile and re-install this package from scratch. You
- can ask buildroot to do this with the <code class="literal">make <package>-dirclean</code> command.</p><p>On the other hand, if you only want to restart the build process of a
- package from its compilation step, you can run <code class="literal">make <package>-rebuild</code>. It
- will restart the compilation and installation of the package, but not from
- scratch: it basically re-executes <code class="literal">make</code> and <code class="literal">make install</code> inside the package,
- so it will only rebuild files that changed.</p><p>If you want to restart the build process of a package from its configuration
- step, you can run <code class="literal">make <package>-reconfigure</code>. It will restart the
- configuration, compilation and installation of the package.</p><p>While <code class="literal"><package>-rebuild</code> implies <code class="literal"><package>-reinstall</code> and
- <code class="literal"><package>-reconfigure</code> implies <code class="literal"><package>-rebuild</code>, these targets as well
- as <code class="literal"><package></code> only act on the said package, and do not trigger re-creating
- the root filesystem image. If re-creating the root filesystem in necessary,
- 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
- which build steps have been completed for each package. They are
- stored in the package build directory,
- <code class="literal">output/build/<package>-<version>/</code> and are named
- <code class="literal">.stamp_<step-name></code>. The commands detailed above simply manipulate
- these stamp files to force Buildroot to restart a specific set of
- steps of a package build process.</p><p>Further details about package special make targets are explained in
- <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
- all sources that you previously selected in the configurator
- (<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>
- 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
- <code class="literal">output</code> in the Buildroot tree.</p><p>Buildroot also supports building out of tree with a syntax similar to
- the Linux kernel. To use it, add <code class="literal">O=<directory></code> to the make command
- 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>
- 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
- passed as a relative path, it is important to note that it is interpreted
- relative to the main Buildroot source directory, <span class="strong"><strong>not</strong></span> the current working
- directory.</p><p>When using out-of-tree builds, the Buildroot <code class="literal">.config</code> and temporary
- files are also stored in the output directory. This means that you can
- safely run multiple builds in parallel using the same source tree as
- long as they use unique output directories.</p><p>For ease of use, Buildroot generates a Makefile wrapper in the output
- directory - so after the first run, you no longer need to pass <code class="literal">O=<…></code>
- and <code class="literal">-C <…></code>, simply run (in the output directory):</p><pre class="screen"> $ make <target></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
- 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">
- <code class="literal">HOSTCXX</code>, the host C++ compiler to use
- </li><li class="listitem">
- <code class="literal">HOSTCC</code>, the host C compiler to use
- </li><li class="listitem">
- <code class="literal">UCLIBC_CONFIG_FILE=<path/to/.config></code>, path to
- the uClibc configuration file, used to compile uClibc, if an
- internal toolchain is being built.
-
- Note that the uClibc configuration file can also be set from the
- configuration interface, so through the Buildroot <code class="literal">.config</code> file; this
- is the recommended way of setting it.
-
- </li><li class="listitem">
- <code class="literal">BUSYBOX_CONFIG_FILE=<path/to/.config></code>, path to
- the BusyBox configuration file.
-
- Note that the BusyBox configuration file can also be set from the
- configuration interface, so through the Buildroot <code class="literal">.config</code> file; this
- is the recommended way of setting it.
-
- </li><li class="listitem">
- <code class="literal">BR2_CCACHE_DIR</code> to override the directory where
- Buildroot stores the cached files when using ccache.
-
- </li><li class="listitem">
- <code class="literal">BR2_DL_DIR</code> to override the directory in which
- Buildroot stores/retrieves downloaded files.
-
- Note that the Buildroot download directory can also be set from the
- configuration interface, so through the Buildroot <code class="literal">.config</code> file. See
- <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
- directory.
- </li><li class="listitem">
- <code class="literal">BR2_GRAPH_ALT</code>, if set and non-empty, to use an alternate color-scheme in
- build-time graphs
- </li><li class="listitem">
- <code class="literal">BR2_GRAPH_OUT</code> to set the filetype of generated graphs, either <code class="literal">pdf</code> (the
- default), or <code class="literal">png</code>.
- </li><li class="listitem">
- <code class="literal">BR2_GRAPH_DEPS_OPTS</code> to pass extra options to the dependency graph; see
- <a class="xref" href="#graph-depends">Section 8.9, “Graphing the dependencies between packages”</a> for the accepted options
- </li><li class="listitem">
- <code class="literal">BR2_GRAPH_DOT_OPTS</code> is passed verbatim as options to the <code class="literal">dot</code> utility to
- draw the dependency graph.
- </li><li class="listitem">
- <code class="literal">BR2_GRAPH_SIZE_OPTS</code> to pass extra options to the size graph; see
- <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
- </li></ul></div><p>An example that uses config files located in the toplevel directory and
- 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>
- 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,
- the number of packages, whether you provisioned free space… Yet, some
- locations in the filesystems images may just be <span class="emphasis"><em>empty</em></span> (e.g. a long run of
- <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
- 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">
- <code class="literal">tar</code> accepts the <code class="literal">-S</code> option to tell it to only store non-zero blocks
- of sparse files:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <code class="literal">tar cf archive.tar -S [files…]</code> will efficiently store sparse files
- in a tarball
- </li><li class="listitem">
- <code class="literal">tar xf archive.tar -S</code> will efficiently store sparse files extracted
- from a tarball
- </li></ul></div></li><li class="listitem"><p class="simpara">
- <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>,
- <code class="literal">never</code> or <code class="literal">always</code>):
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <code class="literal">cp --sparse=always source.file dest.file</code> will make <code class="literal">dest.file</code> a
- sparse file if <code class="literal">source.file</code> has long runs of zeroes
- </li></ul></div></li></ul></div><p>Other tools may have similar options. Please consult their respective man
- pages.</p><p>You can use sparse files if you need to store the filesystem images (e.g.
- to transfer from one machine to another), or if you need to send them (e.g.
- to the Q&A team).</p><p>Note however that flashing a filesystem image to a device while using the
- sparse mode of <code class="literal">dd</code> may result in a broken filesystem (e.g. the block bitmap
- of an ext2 filesystem may be corrupted; or, if you have sparse files in
- your filesystem, those parts may not be all-zeroes when read back). You
- should only use sparse files when handling files on the build machine, not
- 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
- packages in the current configuration, together with their
- dependencies, licenses and other metadata. This JSON blurb is produced
- 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
- output using the <code class="literal">pkg-stats</code> make target. Amongst other things, these
- details include whether known CVEs (security vulnerabilities) affect
- the packages in your current configuration. It also shows if there is
- 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,
- and make sure they are built in the right order. These dependencies
- can sometimes be quite complicated, and for a given system, it is
- often not easy to understand why such or such package was brought into
- the build by Buildroot.</p><p>In order to help understanding the dependencies, and therefore better
- understand what is the role of the different components in your
- embedded Linux system, Buildroot is capable of generating dependency
- graphs.</p><p>To generate a dependency graph of the full system you have compiled,
- simply run:</p><pre class="screen">make graph-depends</pre><p>You will find the generated graph in
- <code class="literal">output/graphs/graph-depends.pdf</code>.</p><p>If your system is quite large, the dependency graph may be too complex
- and difficult to read. It is therefore possible to generate the
- dependency graph just for a given package:</p><pre class="screen">make <pkg>-graph-depends</pre><p>You will find the generated graph in
- <code class="literal">output/graph/<pkg>-graph-depends.pdf</code>.</p><p>Note that the dependency graphs are generated using the <code class="literal">dot</code> tool
- from the <span class="emphasis"><em>Graphviz</em></span> project, which you must have installed on your
- system to use this feature. In most distributions, it is available as
- the <code class="literal">graphviz</code> package.</p><p>By default, the dependency graphs are generated in the PDF
- format. However, by passing the <code class="literal">BR2_GRAPH_OUT</code> environment variable, you
- can switch to other output formats, such as PNG, PostScript or
- SVG. All formats supported by the <code class="literal">-T</code> option of the <code class="literal">dot</code> tool are
- 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
- <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">
- <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
- default, <code class="literal">0</code>, means no limit.
- </li><li class="listitem">
- <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>.
- <code class="literal">PKG</code> can be an actual package name, a glob, the keyword <span class="emphasis"><em>virtual</em></span>
- (to stop on virtual packages), or the keyword <span class="emphasis"><em>host</em></span> (to stop on
- host packages). The package is still present on the graph, but its
- dependencies are not.
- </li><li class="listitem">
- <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
- the graph.
- </li><li class="listitem">
- <code class="literal">--transitive</code>, <code class="literal">--no-transitive</code>, to draw (or not) the transitive
- dependencies. The default is to not draw transitive dependencies.
- </li><li class="listitem">
- <code class="literal">--colors R,T,H</code>, the comma-separated list of colors to draw the
- root package (<code class="literal">R</code>), the target packages (<code class="literal">T</code>) and the host packages
- (<code class="literal">H</code>). Defaults to: <code class="literal">lightblue,grey,gainsboro</code>
- </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
- to be able to understand which packages are the longest to build, to
- see if anything can be done to speed up the build. In order to help
- such build time analysis, Buildroot collects the build time of each
- 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">
- <code class="literal">build.hist-build.pdf</code>, a histogram of the build time for each
- package, ordered in the build order.
- </li><li class="listitem">
- <code class="literal">build.hist-duration.pdf</code>, a histogram of the build time for each
- package, ordered by duration (longest first)
- </li><li class="listitem">
- <code class="literal">build.hist-name.pdf</code>, a histogram of the build time for each
- package, order by package name.
- </li><li class="listitem">
- <code class="literal">build.pie-packages.pdf</code>, a pie chart of the build time per package
- </li><li class="listitem">
- <code class="literal">build.pie-steps.pdf</code>, a pie chart of the global time spent in each
- step of the packages build process.
- </li></ul></div><p>This <code class="literal">graph-build</code> target requires the Python Matplotlib and Numpy
- libraries to be installed (<code class="literal">python-matplotlib</code> and <code class="literal">python-numpy</code> on
- most distributions), and also the <code class="literal">argparse</code> module if you’re using a
- Python version older than 2.7 (<code class="literal">python-argparse</code> on most
- distributions).</p><p>By default, the output format for the graph is PDF, but a different
- format can be selected using the <code class="literal">BR2_GRAPH_OUT</code> environment variable. The
- 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
- how much each Buildroot package is contributing to the overall root
- filesystem size. To help with such an analysis, Buildroot collects
- data about files installed by each package and using this data,
- generates a graph and CSV files detailing the size contribution of
- 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">
- <code class="literal">output/graphs/graph-size.pdf</code>, a pie chart of the contribution of
- each package to the overall root filesystem size
- </li><li class="listitem">
- <code class="literal">output/graphs/package-size-stats.csv</code>, a CSV file giving the size
- contribution of each package to the overall root filesystem size
- </li><li class="listitem">
- <code class="literal">output/graphs/file-size-stats.csv</code>, a CSV file giving the size
- contribution of each installed file to the package it belongs, and
- to the overall filesystem size.
- </li></ul></div><p>This <code class="literal">graph-size</code> target requires the Python Matplotlib library to be
- installed (<code class="literal">python-matplotlib</code> on most distributions), and also the
- <code class="literal">argparse</code> module if you’re using a Python version older than 2.7
- (<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
- is supported to adjust the output file format. See <a class="xref" href="#graph-depends">Section 8.9, “Graphing the dependencies between packages”</a>
- for details about this environment variable.</p><p>Additionally, one may set the environment variable <code class="literal">BR2_GRAPH_SIZE_OPTS</code>
- to further control the generated graph. Accepted options are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">--size-limit X</code>, <code class="literal">-l X</code>, will group all packages which individual
- contribution is below <code class="literal">X</code> percent, to a single entry labelled <span class="emphasis"><em>Others</em></span>
- in the graph. By default, <code class="literal">X=0.01</code>, which means packages each
- contributing less than 1% are grouped under <span class="emphasis"><em>Others</em></span>. Accepted values
- are in the range <code class="literal">[0.0..1.0]</code>.
- </li><li class="listitem">
- <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
- of 1024) or SI (decimal, powers of 1000; the default) prefixes.
- </li><li class="listitem">
- <code class="literal">--biggest-first</code>, to sort packages in decreasing size order, rather
- than in increasing size order.
- </li></ul></div><p><strong>Note. </strong>The collected filesystem size data is only meaningful after a complete
- clean rebuild. Be sure to run <code class="literal">make clean all</code> before using <code class="literal">make
- graph-size</code>.</p><p>To compare the root filesystem size of two different Buildroot compilations,
- for example after adjusting the configuration or when switching to another
- Buildroot release, use the <code class="literal">size-stats-compare</code> script. It takes two
- <code class="literal">file-size-stats.csv</code> files (produced by <code class="literal">make graph-size</code>) as input.
- 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
- 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
- package basis: each package is built by Buildroot using <code class="literal">make -jN</code> (or
- the equivalent invocation for non-make-based build systems). The level
- of parallelism is by default number of CPUs + 1, but it can be
- adjusted using the <code class="literal">BR2_JLEVEL</code> configuration option.</p><p>Until 2020.02, Buildroot was however building packages in a serial
- fashion: each package was built one after the other, without
- parallelization of the build between packages. As of 2020.02,
- Buildroot has experimental support for <span class="strong"><strong>top-level parallel build</strong></span>,
- which allows some signicant build time savings by building packages
- that have no dependency relationship in parallel. This feature is
- 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">
- Enable the option <code class="literal">BR2_PER_PACKAGE_DIRECTORIES</code> in the Buildroot
- configuration
- </li><li class="listitem">
- Use <code class="literal">make -jN</code> when starting the Buildroot build
- </li></ol></div><p>Internally, the <code class="literal">BR2_PER_PACKAGE_DIRECTORIES</code> will enable a mechanism
- called <span class="strong"><strong>per-package directories</strong></span>, which will have the following
- effects:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Instead of a global <span class="emphasis"><em>target</em></span> directory and a global <span class="emphasis"><em>host</em></span> directory
- common to all packages, per-package <span class="emphasis"><em>target</em></span> and <span class="emphasis"><em>host</em></span> directories
- will be used, in <code class="literal">$(O)/per-package/<pkg>/target/</code> and
- <code class="literal">$(O)/per-package/<pkg>/host/</code> respectively. Those folders will be
- populated from the corresponding folders of the package dependencies
- at the beginning of <code class="literal"><pkg></code> build. The compiler and all other tools
- will therefore only be able to see and access files installed by
- dependencies explicitly listed by <code class="literal"><pkg></code>.
- </li><li class="listitem">
- At the end of the build, the global <span class="emphasis"><em>target</em></span> and <span class="emphasis"><em>host</em></span> directories
- will be populated, located in <code class="literal">$(O)/target</code> and <code class="literal">$(O)/host</code>
- respectively. This means that during the build, those folders will
- be empty and it’s only at the very end of the build that they will
- be populated.
- </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
- editors like Vim or Emacs, and command-line based interfaces, a number
- of other embedded Linux developers like richer graphical interfaces to
- do their development work. Eclipse being one of the most popular
- Integrated Development Environment, Buildroot integrates with Eclipse
- in order to ease the development work of Eclipse users.</p><p>Our integration with Eclipse simplifies the compilation, remote
- execution and remote debugging of applications and libraries that are
- built on top of a Buildroot system. It does not integrate the
- Buildroot configuration and build processes themselves with
- Eclipse. Therefore, the typical usage model of our Eclipse integration
- would be:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Configure your Buildroot system with <code class="literal">make menuconfig</code>, <code class="literal">make
- xconfig</code> or any other configuration interface provided with
- Buildroot.
- </li><li class="listitem">
- Build your Buildroot system by running <code class="literal">make</code>.
- </li><li class="listitem">
- Start Eclipse to develop, execute and debug your own custom
- applications and libraries, that will rely on the libraries built
- and installed by Buildroot.
- </li></ul></div><p>The Buildroot Eclipse integration installation process and usage is
- described in detail at
- <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
- software that are not packaged in Buildroot. In order to do this you
- can use the toolchain that was generated by Buildroot.</p><p>The toolchain generated by Buildroot is located by default in
- <code class="literal">output/host/</code>. The simplest way to use it is to add
- <code class="literal">output/host/bin/</code> to your PATH environment variable and then to
- 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
- files of all selected packages, as an SDK, by running the command
- <code class="literal">make sdk</code>. This generates a tarball of the content of the host directory
- <code class="literal">output/host/</code>, named <code class="literal"><TARGET-TUPLE>_sdk-buildroot.tar.gz</code> (which can be
- overriden by setting the environment variable <code class="literal">BR2_SDK_PREFIX</code>) and
- located in the output directory <code class="literal">output/images/</code>.</p><p>This tarball can then be distributed to application developers, when
- they want to develop their applications that are not (yet) packaged as
- a Buildroot package.</p><p>Upon extracting the SDK tarball, the user must run the script
- <code class="literal">relocate-sdk.sh</code> (located at the top directory of the SDK), to make
- sure all paths are updated with the new location.</p><p>Alternatively, if you just want to prepare the SDK without generating
- the tarball (e.g. because you will just be moving the <code class="literal">host</code> directory,
- or will be generating the tarball on your own), Buildroot also allows
- you to just prepare the SDK with <code class="literal">make prepare-sdk</code> without actually
- generating a tarball.</p><p>For your convenience, by selecting the option
- <code class="literal">BR2_PACKAGE_HOST_ENVIRONMENT_SETUP</code>, you can get a
- <code class="literal">setup-environment</code> script installed in <code class="literal">output/host/</code> and therefore
- in your SDK. This script can be sourced with
- <code class="literal">. your/sdk/path/environment-setup</code> to export a number of environment
- variables that will help cross-compile your projects using the
- Buildroot SDK: the <code class="literal">PATH</code> will contain the SDK binaries, standard
- <span class="emphasis"><em>autotools</em></span> variables will be defined with the appropriate values, and
- <code class="literal">CONFIGURE_FLAGS</code> will contain basic <code class="literal">./configure</code> options to
- cross-compile <span class="emphasis"><em>autotools</em></span> projects. It also provides some useful
- commands. Note however that once this script is sourced, the
- environment is setup only for cross-compilation, and no longer for
- 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
- build machine and communicates with <code class="literal">gdbserver</code> on the target to
- 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">
- If you are using an <span class="emphasis"><em>internal toolchain</em></span> (built by Buildroot), you
- must enable <code class="literal">BR2_PACKAGE_HOST_GDB</code>, <code class="literal">BR2_PACKAGE_GDB</code> and
- <code class="literal">BR2_PACKAGE_GDB_SERVER</code>. This ensures that both the cross gdb and
- gdbserver get built, and that gdbserver gets installed to your target.
- </li><li class="listitem">
- If you are using an <span class="emphasis"><em>external toolchain</em></span>, you should enable
- <code class="literal">BR2_TOOLCHAIN_EXTERNAL_GDB_SERVER_COPY</code>, which will copy the
- gdbserver included with the external toolchain to the target. If your
- external toolchain does not have a cross gdb or gdbserver, it is also
- possible to let Buildroot build them, by enabling the same options as
- for the <span class="emphasis"><em>internal toolchain backend</em></span>.
- </li></ul></div><p>Now, to start debugging a program called <code class="literal">foo</code>, you should run on the
- 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
- from the cross gdb.</p><p>Then, on the host, you should start the cross gdb using the following
- command line:</p><pre class="screen"><buildroot>/output/host/bin/<tuple>-gdb -x <buildroot>/output/staging/usr/share/buildroot/gdbinit foo</pre><p>Of course, <code class="literal">foo</code> must be available in the current directory, built
- with debugging symbols. Typically you start this command from the
- directory where <code class="literal">foo</code> is built (and not from <code class="literal">output/target/</code> as the
- binaries in that directory are stripped).</p><p>The <code class="literal"><buildroot>/output/staging/usr/share/buildroot/gdbinit</code> file will tell the
- 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 <target ip address>: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
- object files resulting from each compilation process, and is able to
- skip future compilation of the same source file (with same compiler
- and same arguments) by using the pre-existing object files. When doing
- almost identical builds from scratch a number of times, it can nicely
- speed up the build process.</p><p><code class="literal">ccache</code> support is integrated in Buildroot. You just have to enable
- <code class="literal">Enable compiler cache</code> in <code class="literal">Build options</code>. This will automatically
- 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
- outside of Buildroot output directory so that it can be shared by
- separate Buildroot builds. If you want to get rid of the cache, simply
- remove this directory.</p><p>You can get statistics on the cache (its size, number of hits,
- 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
- provide more generic access to the ccache. For example</p><pre class="screen"># set cache limit size
- make CCACHE_OPTIONS="--max-size=5G" ccache-options
- # zero statistics counters
- 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.
- If a compiler option is different, the cached object file will not be
- used. Many compiler options, however, contain an absolute path to the
- staging directory. Because of this, building in a different output
- directory would lead to many cache misses.</p><p>To avoid this issue, buildroot has the <code class="literal">Use relative paths</code> option
- (<code class="literal">BR2_CCACHE_USE_BASEDIR</code>). This will rewrite all absolute paths that
- point inside the output directory into relative paths. Thus, changing
- 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
- relative paths in the object file. Therefore, for example, the debugger
- will no longer find the file, unless you cd to the output directory
- first.</p><p>See <a class="ulink" href="https://ccache.samba.org/manual.html#_compiling_in_different_directories" target="_top">the
- ccache manual’s section on "Compiling in different directories"</a> for
- 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
- in <code class="literal">BR2_DL_DIR</code>, which by default is the <code class="literal">dl</code> directory. If you want
- to keep a complete version of Buildroot which is known to be working
- with the associated tarballs, you can make a copy of this directory.
- This will allow you to regenerate the toolchain and the target
- filesystem with exactly the same versions.</p><p>If you maintain several Buildroot trees, it might be better to have a
- shared download location. This can be achieved by pointing the
- <code class="literal">BR2_DL_DIR</code> environment variable to a directory. If this is
- set, then the value of <code class="literal">BR2_DL_DIR</code> in the Buildroot configuration is
- overridden. The following line should be added to <code class="literal"><~/.bashrc></code>.</p><pre class="screen"> export BR2_DL_DIR=<shared download location></pre><p>The download location can also be set in the <code class="literal">.config</code> file, with the
- <code class="literal">BR2_DL_DIR</code> option. Unlike most options in the .config file, this value
- 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 <package></code> builds and installs that particular package
- and its dependencies.</p><p>For packages relying on the Buildroot infrastructure, there are
- numerous special make targets that can be called independently like
- this:</p><pre class="screen">make <package>-<target></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
- 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
- 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
- (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
- 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
- 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>
- <p><span class="strong"><strong>host package:</strong></span> Run the installation of the package in the host
- 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
- 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
- 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
- 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
- dependencies of the package (i.e the packages that depend on it,
- 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
- context of the current Buildroot configuration. See
- <a class="link" href="#graph-depends">this section</a> for more details about dependency
- 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
- dependencies (i.e the packages that depend on it, 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">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
- sense when using the <code class="literal">OVERRIDE_SRCDIR</code> feature or when you modified a file
- 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
- makes sense when using the <code class="literal">OVERRIDE_SRCDIR</code> feature or when you modified a
- 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
- it, configure, compile and install the software component found inside
- this tarball. The source code is extracted in
- <code class="literal">output/build/<package>-<version></code>, which is a temporary directory:
- whenever <code class="literal">make clean</code> is used, this directory is entirely removed, and
- re-created at the next <code class="literal">make</code> invocation. Even when a Git or
- Subversion repository is used as the input for the package source
- code, Buildroot creates a tarball out of it, and then behaves as it
- normally does with tarballs.</p><p>This behavior is well-suited when Buildroot is used mainly as an
- integration tool, to build and integrate all the components of an
- embedded Linux system. However, if one uses Buildroot during the
- development of certain components of the system, this behavior is not
- very convenient: one would instead like to make a small change to the
- source code of one package, and be able to quickly rebuild the system
- with Buildroot.</p><p>Making changes directly in <code class="literal">output/build/<package>-<version></code> is not
- an appropriate solution, because this directory is removed on <code class="literal">make
- clean</code>.</p><p>Therefore, Buildroot provides a specific mechanism for this use case:
- the <code class="literal"><pkg>_OVERRIDE_SRCDIR</code> mechanism. Buildroot reads an <span class="emphasis"><em>override</em></span>
- file, which allows the user to tell Buildroot the location of the
- source for certain packages.</p><p>The default location of the override file is <code class="literal">$(CONFIG_DIR)/local.mk</code>,
- as defined by the <code class="literal">BR2_PACKAGE_OVERRIDE_FILE</code> configuration option.
- <code class="literal">$(CONFIG_DIR)</code> is the location of the Buildroot <code class="literal">.config</code> file, so
- <code class="literal">local.mk</code> by default lives side-by-side with the <code class="literal">.config</code> file,
- which means:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- In the top-level Buildroot source directory for in-tree builds
- (i.e., when <code class="literal">O=</code> is not used)
- </li><li class="listitem">
- In the out-of-tree directory for out-of-tree builds (i.e., when
- <code class="literal">O=</code> is used)
- </li></ul></div><p>If a different location than these defaults is required, it can be
- specified through the <code class="literal">BR2_PACKAGE_OVERRIDE_FILE</code> configuration
- 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"><pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources
- <pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources</pre><p>For example:</p><pre class="screen">LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
- BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/</pre><p>When Buildroot finds that for a given package, an
- <code class="literal"><pkg>_OVERRIDE_SRCDIR</code> has been defined, it will no longer attempt to
- download, extract and patch the package. Instead, it will directly use
- the source code available in the specified directory and <code class="literal">make clean</code>
- will not touch this directory. This allows to point Buildroot to your
- own directories, that can be managed by Git, Subversion, or any other
- version control system. To achieve this, Buildroot will use <span class="emphasis"><em>rsync</em></span> to
- copy the source code of the component from the specified
- <code class="literal"><pkg>_OVERRIDE_SRCDIR</code> to <code class="literal">output/build/<package>-custom/</code>.</p><p>This mechanism is best used in conjunction with the <code class="literal">make
- <pkg>-rebuild</code> and <code class="literal">make <pkg>-reconfigure</code> targets. A <code class="literal">make
- <pkg>-rebuild all</code> sequence will <span class="emphasis"><em>rsync</em></span> the source code from
- <code class="literal"><pkg>_OVERRIDE_SRCDIR</code> to <code class="literal">output/build/<package>-custom</code> (thanks to
- <span class="emphasis"><em>rsync</em></span>, only the modified files are copied), and restart the build
- process of just this package.</p><p>In the example of the <code class="literal">linux</code> package above, the developer can then
- 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
- <code class="literal">output/images</code>. Similarly, a change can be made to the BusyBox source
- 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
- BusyBox.</p><p>Source trees for big projects often contain hundreds or thousands of
- files which are not needed for building, but will slow down the process
- of copying the sources with <span class="emphasis"><em>rsync</em></span>. Optionally, it is possible define
- <code class="literal"><pkg>_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS</code> to skip syncing certain files
- from the source tree. For example, when working on the <code class="literal">webkitgtk</code>
- package, the following will exclude the tests and in-tree builds from
- a local WebKit source tree:</p><pre class="screen">WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit
- WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \
- --exclude JSTests --exclude ManualTests --exclude PerformanceTests \
- --exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \
- --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
- <span class="strong"><strong>.svn</strong></span> directories). Some packages prefer to have these VCS directories
- available during build, for example for automatically determining a precise
- commit reference for version information. To undo this built-in filtering at a
- 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">
- configuring Buildroot (including build options and toolchain,
- bootloader, kernel, package and filesystem image type selection)
- </li><li class="listitem">
- configuring other components, like the Linux kernel and BusyBox
- </li><li class="listitem"><p class="simpara">
- customizing the generated target filesystem
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- adding or overwriting files on the target filesystem (using
- <code class="literal">BR2_ROOTFS_OVERLAY</code>)
- </li><li class="listitem">
- modifying or deleting files on the target filesystem (using
- <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code>)
- </li><li class="listitem">
- running arbitrary commands prior to generating the filesystem image
- (using <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code>)
- </li><li class="listitem">
- setting file permissions and ownership (using
- <code class="literal">BR2_ROOTFS_DEVICE_TABLE</code>)
- </li><li class="listitem">
- adding custom devices nodes (using
- <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code>)
- </li></ul></div></li><li class="listitem">
- adding custom user accounts (using <code class="literal">BR2_ROOTFS_USERS_TABLES</code>)
- </li><li class="listitem">
- running arbitrary commands after generating the filesystem image
- (using <code class="literal">BR2_ROOTFS_POST_IMAGE_SCRIPT</code>)
- </li><li class="listitem">
- adding project-specific patches to some packages (using
- <code class="literal">BR2_GLOBAL_PATCH_DIR</code>)
- </li><li class="listitem">
- adding project-specific packages
- </li></ul></div><p>An important note regarding such <span class="emphasis"><em>project-specific</em></span> customizations:
- please carefully consider which changes are indeed project-specific and
- which changes are also useful to developers outside your project. The
- Buildroot community highly recommends and encourages the upstreaming of
- improvements, packages and board support to the official Buildroot
- project. Of course, it is sometimes not possible or desirable to
- upstream because the changes are highly specific or proprietary.</p><p>This chapter describes how to make such project-specific customizations
- in Buildroot and how to store them in a way that you can build the same
- image in a reproducible way, even after running <span class="emphasis"><em>make clean</em></span>. By
- following the recommended strategy, you can even use the same Buildroot
- 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
- more project-specific files that need to be stored somewhere. While most
- of these files could be placed in <span class="emphasis"><em>any</em></span> location as their path is to be
- specified in the Buildroot configuration, the Buildroot developers
- recommend a specific directory structure which is described in this
- section.</p><p>Orthogonal to this directory structure, you can choose <span class="emphasis"><em>where</em></span> you place
- this structure itself: either inside the Buildroot tree, or outside of
- it using a br2-external tree. Both options are valid, the choice is up
- to you.</p><pre class="screen">+-- board/
- | +-- <company>/
- | +-- <boardname>/
- | +-- linux.config
- | +-- busybox.config
- | +-- <other configuration files>
- | +-- post_build.sh
- | +-- post_image.sh
- | +-- rootfs_overlay/
- | | +-- etc/
- | | +-- <some file>
- | +-- patches/
- | +-- foo/
- | | +-- <some patch>
- | +-- libbar/
- | +-- <some other patches>
- |
- +-- configs/
- | +-- <boardname>_defconfig
- |
- +-- package/
- | +-- <company>/
- | +-- Config.in (if not using a br2-external tree)
- | +-- <company>.mk (if not using a br2-external tree)
- | +-- package1/
- | | +-- Config.in
- | | +-- package1.mk
- | +-- package2/
- | +-- Config.in
- | +-- package2.mk
- |
- +-- Config.in (if using a br2-external tree)
- +-- external.mk (if using a br2-external tree)
- +-- 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
- tree but in a br2-external tree, the <company> and possibly <boardname>
- 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
- need the same customizations. Instead of duplicating these
- customizations for each project, it is recommended to use a layered
- customization approach, as explained in this section.</p><p>Almost all of the customization methods available in Buildroot, like
- post-build scripts and root filesystem overlays, accept a
- space-separated list of items. The specified items are always treated in
- order, from left to right. By creating more than one such item, one for
- the common customizations and another one for the really
- project-specific customizations, you can avoid unnecessary duplication.
- Each layer is typically embodied by a separate directory inside
- <code class="literal">board/<company>/</code>. Depending on your projects, you could even introduce
- more than two layers.</p><p>An example directory structure for where a user has two customization
- layers <span class="emphasis"><em>common</em></span> and <span class="emphasis"><em>fooboard</em></span> is:</p><pre class="screen">+-- board/
- +-- <company>/
- +-- common/
- | +-- post_build.sh
- | +-- rootfs_overlay/
- | | +-- ...
- | +-- patches/
- | +-- ...
- |
- +-- fooboard/
- +-- linux.config
- +-- busybox.config
- +-- <other configuration files>
- +-- post_build.sh
- +-- rootfs_overlay/
- | +-- ...
- +-- patches/
- +-- ...</pre><p>For example, if the user has the <code class="literal">BR2_GLOBAL_PATCH_DIR</code> configuration
- option set as:</p><pre class="screen">BR2_GLOBAL_PATCH_DIR="board/<company>/common/patches board/<company>/fooboard/patches"</pre><p>then first the patches from the <span class="emphasis"><em>common</em></span> layer would be applied,
- 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
- place project-specific customizations in two locations:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- directly within the Buildroot tree, typically maintaining them using
- branches in a version control system so that upgrading to a newer
- Buildroot release is easy.
- </li><li class="listitem">
- outside of the Buildroot tree, using the <span class="emphasis"><em>br2-external</em></span> mechanism.
- This mechanism allows to keep package recipes, board support and
- configuration files outside of the Buildroot tree, while still
- having them nicely integrated in the build logic. We call this
- location a <span class="emphasis"><em>br2-external tree</em></span>. This section explains how to use
- the br2-external mechanism and what to provide in a br2-external
- tree.
- </li></ul></div><p>One can tell Buildroot to use one or more br2-external trees by setting
- the <code class="literal">BR2_EXTERNAL</code> make variable set to the path(s) of the br2-external
- tree(s) to use. It can be passed to any Buildroot <code class="literal">make</code> invocation. It
- is automatically saved in the hidden <code class="literal">.br2-external.mk</code> file in the output
- directory. Thanks to this, there is no need to pass <code class="literal">BR2_EXTERNAL</code> at
- every <code class="literal">make</code> invocation. It can however be changed at any time by
- 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.
- If it is passed as a relative path, it is important to note that it is
- interpreted relative to the main Buildroot source directory, <span class="strong"><strong>not</strong></span> to
- the Buildroot output directory.</p><p><strong>Note: </strong>If using an br2-external tree from before Buildroot 2016.11, you need to
- convert it before you can use it with Buildroot 2016.11 onward. See
- <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
- will be used:</p><pre class="screen">buildroot/ $ make
- 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
- in the following chapters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">external.desc</code>
- </li><li class="listitem">
- <code class="literal">external.mk</code>
- </li><li class="listitem">
- <code class="literal">Config.in</code>
- </li></ul></div><p>Apart from those mandatory files, there may be additional and optional
- content that may be present in a br2-external tree, like the <code class="literal">configs/</code>
- or <code class="literal">provides/</code> directories. They are described in the following chapters
- 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>
- for that br2-external tree.</p><p>The format for this file is line based, with each line starting by a
- keyword, followed by a colon and one or more spaces, followed by the
- value assigned to that keyword. There are two keywords currently
- recognised:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
- <code class="literal">name</code>, mandatory, defines the name for that br2-external tree. That
- name must only use ASCII characters in the set <code class="literal">[A-Za-z0-9_]</code>; any
- other character is forbidden. Buildroot sets the variable
- <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code> to the absolute path of the br2-external
- tree, so that you can use it to refer to your br2-external tree. This
- variable is available both in Kconfig, so you can use it to source your
- Kconfig files (see below) and in the Makefile, so that you can use it
- to include other Makefiles (see below) or refer to other files (like
- data files) from your br2-external tree.
- </p><p><strong>Note: </strong>Since it is possible to use multiple br2-external trees at once, this
- name is used by Buildroot to generate variables for each of those trees.
- That name is used to identify your br2-external tree, so try to come up
- with a name that really describes your br2-external tree, in order for
- it to be relatively unique, so that it does not clash with another name
- from another br2-external tree, especially if you are planning on
- somehow sharing your br2-external tree with third parties or using
- br2-external trees from third parties.</p></li><li class="listitem">
- <code class="literal">desc</code>, optional, provides a short description for that br2-external
- tree. It shall fit on a single line, is mostly free-form (see below),
- and is used when displaying information about a br2-external tree (e.g.
- above the list of defconfig files, or as the prompt in the menuconfig);
- as such, it should relatively brief (40 chars is probably a good upper
- limit). The description is available in the <code class="literal">BR2_EXTERNAL_$(NAME)_DESC</code>
- variable.
- </li></ul></div><p>Examples of names and the corresponding <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code>
- variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">FOO</code> → <code class="literal">BR2_EXTERNAL_FOO_PATH</code>
- </li><li class="listitem">
- <code class="literal">BAR_42</code> → <code class="literal">BR2_EXTERNAL_BAR_42_PATH</code>
- </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
- available in the Kconfig files and the Makefiles. They are also
- exported in the environment so are available in post-build, post-image
- 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
- recipes (i.e. <code class="literal">foo/Config.in</code> and <code class="literal">foo/foo.mk</code> like for packages bundled
- 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
- tree to make it appear in the top-level configuration menu, and includes
- the <code class="literal">external.mk</code> from each br2-external tree with the rest of the
- makefile logic.</p><p>The main usage of this is to store package recipes. The recommended way
- 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"
- 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
- <code class="literal">$(BR2_EXTERNAL_BAR_42_PATH)/package/package2</code> create normal
- 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>.
- If you prefer, you can also group the packages in subdirectories
- called <boardname> and adapt the above paths accordingly.</p><p>You can also define custom configuration options in <code class="literal">Config.in</code> and
- 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
- the br2-external tree. Buildroot will automatically show them in the
- output of <code class="literal">make list-defconfigs</code> and allow them to be loaded with the
- normal <code class="literal">make <name>_defconfig</code> command. They will be visible in the
- <span class="emphasis"><em>make list-defconfigs</em></span> output, below an <code class="literal">External configs</code> label that
- 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
- the one from the last br2-external tree is used. It is thus possible
- to override a defconfig bundled in Buildroot or another br2-external
- 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)
- implementations of API-compatible such packages. For example, there is
- a choice to choose either libjpeg ot jpeg-turbo; there is one between
- openssl or libressl; there is one to select one of the known,
- pre-configured toolchains…</p><p>It is possible for a br2-external to extend those choices, by providing
- a set of files that define those alternatives:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">provides/toolchains.in</code> defines the pre-configured toolchains, which
- will then be listed in the toolchain selection;
- </li><li class="listitem">
- <code class="literal">provides/jpeg.in</code> defines the alternative libjpeg implementations;
- </li><li class="listitem">
- <code class="literal">provides/openssl.in</code> defines the alternative openssl implementations;
- </li><li class="listitem">
- <code class="literal">provides/skeleton.in</code> defines the alternative skeleton implementations;
- </li><li class="listitem">
- <code class="literal">provides/init.in</code> defines the alternative init system implementations, this
- can be used to select a default skeleton for your init.
- </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
- as the kernel configuration, the root filesystem overlay, or any other
- configuration file for which Buildroot allows to set the location (by
- using the <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code> variable). For example, you
- could set the paths to a global patch directory, to a rootfs overlay
- and to the kernel configuration file as follows (e.g. by running
- <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/
- BR2_ROOTFS_OVERLAY=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/overlay/
- BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/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
- be added by storing them in the <code class="literal">linux/</code> directory at the root of a
- 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
- content is shown for the file above it, when it is relevant to explain
- the br2-external tree; this is all entirely made up just for the sake of
- illustration, of course):</p><pre class="screen">/path/to/br2-ext-tree/
- |- external.desc
- | |name: BAR_42
- | |desc: Example br2-external tree
- | `----
- |
- |- Config.in
- | |source "$BR2_EXTERNAL_BAR_42_PATH/toolchain/toolchain-external-mine/Config.in.options"
- | |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-1/Config.in"
- | |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-2/Config.in"
- | |source "$BR2_EXTERNAL_BAR_42_PATH/package/my-jpeg/Config.in"
- | |
- | |config BAR_42_FLASH_ADDR
- | | hex "my-board flash address"
- | | default 0x10AD
- | `----
- |
- |- external.mk
- | |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
- | |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/toolchain/*/*.mk))
- | |
- | |flash-my-board:
- | | $(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/flash-image \
- | | --image $(BINARIES_DIR)/image.bin \
- | | --address $(BAR_42_FLASH_ADDR)
- | `----
- |
- |- package/pkg-1/Config.in
- | |config BR2_PACKAGE_PKG_1
- | | bool "pkg-1"
- | | help
- | | Some help about pkg-1
- | `----
- |- package/pkg-1/pkg-1.hash
- |- package/pkg-1/pkg-1.mk
- | |PKG_1_VERSION = 1.2.3
- | |PKG_1_SITE = /some/where/to/get/pkg-1
- | |PKG_1_LICENSE = blabla
- | |
- | |define PKG_1_INSTALL_INIT_SYSV
- | | $(INSTALL) -D -m 0755 $(PKG_1_PKGDIR)/S99my-daemon \
- | | $(TARGET_DIR)/etc/init.d/S99my-daemon
- | |endef
- | |
- | |$(eval $(autotools-package))
- | `----
- |- package/pkg-1/S99my-daemon
- |
- |- package/pkg-2/Config.in
- |- package/pkg-2/pkg-2.hash
- |- package/pkg-2/pkg-2.mk
- |
- |- provides/jpeg.in
- | |config BR2_PACKAGE_MY_JPEG
- | | bool "my-jpeg"
- | `----
- |- package/my-jpeg/Config.in
- | |config BR2_PACKAGE_PROVIDES_JPEG
- | | default "my-jpeg" if BR2_PACKAGE_MY_JPEG
- | `----
- |- package/my-jpeg/my-jpeg.mk
- | |# This is a normal package .mk file
- | |MY_JPEG_VERSION = 1.2.3
- | |MY_JPEG_SITE = https://example.net/some/place
- | |MY_JPEG_PROVIDES = jpeg
- | |$(eval $(autotools-package))
- | `----
- |
- |- provides/init.in
- | |config BR2_INIT_MINE
- | | bool "my custom init"
- | | select BR2_PACKAGE_MY_INIT
- | | select BR2_PACKAGE_SKELETON_INIT_MINE if BR2_ROOTFS_SKELETON_DEFAULT
- | `----
- |
- |- provides/skeleton.in
- | |config BR2_ROOTFS_SKELETON_MINE
- | | bool "my custom skeleton"
- | | select BR2_PACKAGE_SKELETON_MINE
- | `----
- |- package/skeleton-mine/Config.in
- | |config BR2_PACKAGE_SKELETON_MINE
- | | bool
- | | select BR2_PACKAGE_HAS_SKELETON
- | |
- | |config BR2_PACKAGE_PROVIDES_SKELETON
- | | default "skeleton-mine" if BR2_PACKAGE_SKELETON_MINE
- | `----
- |- package/skeleton-mine/skeleton-mine.mk
- | |SKELETON_MINE_ADD_TOOLCHAIN_DEPENDENCY = NO
- | |SKELETON_MINE_ADD_SKELETON_DEPENDENCY = NO
- | |SKELETON_MINE_PROVIDES = skeleton
- | |SKELETON_MINE_INSTALL_STAGING = YES
- | |$(eval $(generic-package))
- | `----
- |
- |- provides/toolchains.in
- | |config BR2_TOOLCHAIN_EXTERNAL_MINE
- | | bool "my custom toolchain"
- | | depends on BR2_some_arch
- | | select BR2_INSTALL_LIBSTDCPP
- | `----
- |- toolchain/toolchain-external-mine/Config.in.options
- | |if BR2_TOOLCHAIN_EXTERNAL_MINE
- | |config BR2_TOOLCHAIN_EXTERNAL_PREFIX
- | | default "arch-mine-linux-gnu"
- | |config BR2_PACKAGE_PROVIDES_TOOLCHAIN_EXTERNAL
- | | default "toolchain-external-mine"
- | |endif
- | `----
- |- toolchain/toolchain-external-mine/toolchain-external-mine.mk
- | |TOOLCHAIN_EXTERNAL_MINE_SITE = https://example.net/some/place
- | |TOOLCHAIN_EXTERNAL_MINE_SOURCE = my-toolchain.tar.gz
- | |$(eval $(toolchain-external-package))
- | `----
- |
- |- linux/Config.ext.in
- | |config BR2_LINUX_KERNEL_EXT_EXAMPLE_DRIVER
- | | bool "example-external-driver"
- | | help
- | | Example external driver
- | |---
- |- linux/linux-ext-example-driver.mk
- |
- |- configs/my-board_defconfig
- | |BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_BAR_42_PATH)/patches/"
- | |BR2_ROOTFS_OVERLAY="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/overlay/"
- | |BR2_ROOTFS_POST_IMAGE_SCRIPT="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/post-image.sh"
- | |BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/kernel.config"
- | `----
- |
- |- patches/linux/0001-some-change.patch
- |- patches/linux/0002-some-other-change.patch
- |- patches/busybox/0001-fix-something.patch
- |
- |- board/my-board/kernel.config
- |- board/my-board/overlay/var/www/index.html
- |- board/my-board/overlay/var/www/my.css
- |- board/my-board/flash-image
- `- board/my-board/post-image.sh
- |#!/bin/sh
- |generate-my-binary-image \
- | --root ${BINARIES_DIR}/rootfs.tar \
- | --kernel ${BINARIES_DIR}/zImage \
- | --dtb ${BINARIES_DIR}/my-board.dtb \
- | --output ${BINARIES_DIR}/image.bin
- `----</pre><p>The br2-external tree will then be visible in the menuconfig (with
- the layout expanded):</p><pre class="screen">External options --->
- *** Example br2-external tree (in /path/to/br2-ext-tree/)
- [ ] pkg-1
- [ ] pkg-2
- (0x10AD) my-board flash address</pre><p>If you are using more than one br2-external tree, it would look like
- (with the layout expanded and the second one with name <code class="literal">FOO_27</code> but no
- <code class="literal">desc:</code> field in <code class="literal">external.desc</code>):</p><pre class="screen">External options --->
- Example br2-external tree --->
- *** Example br2-external tree (in /path/to/br2-ext-tree)
- [ ] pkg-1
- [ ] pkg-2
- (0x10AD) my-board flash address
- FOO_27 --->
- *** FOO_27 (in /path/to/another-br2-ext)
- [ ] foo
- [ ] bar</pre><p>Additionally, the jpeg provider will be visible in the jpeg choice:</p><pre class="screen">Target packages --->
- Libraries --->
- Graphics --->
- [*] jpeg support
- jpeg variant () --->
- ( ) jpeg
- ( ) jpeg-turbo
- *** jpeg from: Example br2-external tree ***
- (X) my-jpeg
- *** jpeg from: FOO_27 ***
- ( ) another-jpeg</pre><p>And similarly for the toolchains:</p><pre class="screen">Toolchain --->
- Toolchain () --->
- ( ) Custom toolchain
- *** Toolchains from: Example br2-external tree ***
- (X) my custom toolchain</pre><p><strong>Note. </strong>The toolchain options in <code class="literal">toolchain/toolchain-external-mine/Config.in.options</code>
- will not appear in the <code class="literal">Toolchain</code> menu. They must be explicitly included
- from within the br2-external’s top-level <code class="literal">Config.in</code> and will thus appear
- 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
- <code class="literal">make savedefconfig</code>.</p><p>This strips the Buildroot configuration down by removing configuration
- options that are at their default value. The result is stored in a file
- called <code class="literal">defconfig</code>. If you want to save it in another place, change the
- <code class="literal">BR2_DEFCONFIG</code> option in the Buildroot configuration itself, or call
- make with <code class="literal">make savedefconfig BR2_DEFCONFIG=<path-to-defconfig></code>.</p><p>The recommended place to store this defconfig is
- <code class="literal">configs/<boardname>_defconfig</code>. If you follow this recommendation, the
- configuration will be listed in <code class="literal">make help</code> and can be set again by
- running <code class="literal">make <boardname>_defconfig</code>.</p><p>Alternatively, you can copy the file to any other place and rebuild with
- <code class="literal">make defconfig BR2_DEFCONFIG=<path-to-defconfig-file></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
- and uClibc should be stored as well if changed. For each of these
- components, a Buildroot configuration option exists to point to an input
- configuration file, e.g. <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code>. To store
- their configuration, set these configuration options to a path where you
- want to save the configuration files, and then use the helper targets
- 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
- store these configuration files is
- <code class="literal">board/<company>/<boardname>/foo.config</code>.</p><p>Make sure that you create a configuration file <span class="emphasis"><em>before</em></span> changing
- the <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code> etc. options. Otherwise,
- Buildroot will try to access this config file, which doesn’t exist
- yet, and will fail. You can create the configuration file by running
- <code class="literal">make linux-menuconfig</code> etc.</p><p>Buildroot provides a few helper targets to make the saving of
- configuration files easier.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">make linux-update-defconfig</code> saves the linux configuration to the
- path specified by <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code>. It
- simplifies the config file by removing default values. However,
- this only works with kernels starting from 2.6.33. For earlier
- kernels, use <code class="literal">make linux-update-config</code>.
- </li><li class="listitem">
- <code class="literal">make busybox-update-config</code> saves the busybox configuration to the
- path specified by <code class="literal">BR2_PACKAGE_BUSYBOX_CONFIG</code>.
- </li><li class="listitem">
- <code class="literal">make uclibc-update-config</code> saves the uClibc configuration to the
- path specified by <code class="literal">BR2_UCLIBC_CONFIG</code>.
- </li><li class="listitem">
- <code class="literal">make barebox-update-defconfig</code> saves the barebox configuration to the
- path specified by <code class="literal">BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE</code>.
- </li><li class="listitem">
- <code class="literal">make uboot-update-defconfig</code> saves the U-Boot configuration to the
- path specified by <code class="literal">BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE</code>.
- </li><li class="listitem">
- For at91bootstrap3, no helper exists so you have to copy the config
- file manually to <code class="literal">BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE</code>.
- </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>,
- 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
- overlay(s) and post build script(s).</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
- Root filesystem overlays (<code class="literal">BR2_ROOTFS_OVERLAY</code>)
- </span></dt><dd><p class="simpara">A filesystem overlay is a tree of files that is copied directly
- over the target filesystem after it has been built. To enable this
- feature, set config option <code class="literal">BR2_ROOTFS_OVERLAY</code> (in the <code class="literal">System
- configuration</code> menu) to the root of the overlay. You can even specify
- multiple overlays, space-separated. If you specify a relative path,
- it will be relative to the root of the Buildroot tree. Hidden
- directories of version control systems, like <code class="literal">.git</code>, <code class="literal">.svn</code>, <code class="literal">.hg</code>,
- etc., files called <code class="literal">.empty</code> and files ending in <code class="literal">~</code> are excluded from
- the copy.</p><p class="simpara">When <code class="literal">BR2_ROOTFS_MERGED_USR</code> is enabled, then the overlay must 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 will
- create them as symbolic links to the relevant folders in <span class="emphasis"><em>/usr</em></span>. In
- such a situation, should the overlay have any programs or libraries,
- 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
- this overlay is <code class="literal">board/<company>/<boardname>/rootfs-overlay</code>.</p></dd><dt><span class="term">
- Post-build scripts (<code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code>)
- </span></dt><dd><p class="simpara">Post-build scripts are shell scripts called <span class="emphasis"><em>after</em></span> Buildroot builds
- all the selected software, but <span class="emphasis"><em>before</em></span> the rootfs images are
- assembled. To enable this feature, specify a space-separated list of
- post-build scripts in config option <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code> (in
- the <code class="literal">System configuration</code> menu). If you specify a relative path, it
- 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
- target filesystem. You should, however, use this feature with care.
- Whenever you find that a certain package generates wrong or unneeded
- files, you should fix that package rather than work around it with some
- 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
- this script is <code class="literal">board/<company>/<boardname>/post_build.sh</code>.</p><p class="simpara">The post-build scripts are run with the main Buildroot tree as current
- working directory. The path to the target filesystem is passed as the
- first argument to each script. If the config option
- <code class="literal">BR2_ROOTFS_POST_SCRIPT_ARGS</code> is not empty, these arguments will be
- passed to the script too. All the scripts will be passed the exact
- same set of arguments, it is not possible to pass different sets of
- 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">
- <code class="literal">BR2_CONFIG</code>: the path to the Buildroot .config file
- </li><li class="listitem">
- <code class="literal">HOST_DIR</code>, <code class="literal">STAGING_DIR</code>, <code class="literal">TARGET_DIR</code>: 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>
- </li><li class="listitem">
- <code class="literal">BUILD_DIR</code>: the directory where packages are extracted and built
- </li><li class="listitem">
- <code class="literal">BINARIES_DIR</code>: the place where all binary files (aka images) are
- stored
- </li><li class="listitem">
- <code class="literal">BASE_DIR</code>: the base output directory
- </li></ul></div></dd></dl></div><p>Below three more methods of customizing the target filesystem are
- described, but they are not recommended.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
- Direct modification of the target filesystem
- </span></dt><dd><p class="simpara">For temporary modifications, you can modify the target filesystem
- directly and rebuild the image. The target filesystem is available
- under <code class="literal">output/target/</code>. After making your changes, run <code class="literal">make</code> to
- rebuild the target filesystem image.</p><p class="simpara">This method allows you to do anything to the target filesystem, but if
- you need to clean your Buildroot tree using <code class="literal">make clean</code>, these
- changes will be lost. Such cleaning is necessary in several cases,
- 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
- only useful for quick tests: <span class="emphasis"><em>changes do not survive the <code class="literal">make clean</code>
- command</em></span>. Once you have validated your changes, you should make sure
- that they will persist after a <code class="literal">make clean</code>, using a root filesystem
- overlay or a post-build script.</p></dd><dt><span class="term">
- Custom target skeleton (<code class="literal">BR2_ROOTFS_SKELETON_CUSTOM</code>)
- </span></dt><dd><p class="simpara">The root filesystem image is created from a target skeleton, on top of
- which all packages install their files. The skeleton is copied to the
- target directory <code class="literal">output/target</code> before any package is built and
- installed. The default target skeleton provides the standard Unix
- 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
- match your needs, you would typically use a root filesystem overlay or
- post-build script to adapt it. However, if the default skeleton is
- entirely different than what you need, using a custom skeleton may be
- more suitable.</p><p class="simpara">To enable this feature, enable config option
- <code class="literal">BR2_ROOTFS_SKELETON_CUSTOM</code> and set <code class="literal">BR2_ROOTFS_SKELETON_CUSTOM_PATH</code>
- to the path of your custom skeleton. Both options are available in the
- <code class="literal">System configuration</code> menu. If you specify a relative path, it will
- 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>
- directories, since they are created automatically during the build.
- When <code class="literal">BR2_ROOTFS_MERGED_USR</code> is enabled, then the custom skeleton must
- 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
- will create them as symbolic links to the relevant folders in <span class="emphasis"><em>/usr</em></span>.
- In such a situation, should the skeleton have any programs or
- libraries, 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">This method is not recommended because it duplicates the entire
- skeleton, which prevents taking advantage of the fixes or improvements
- brought to the default skeleton in later Buildroot releases.</p></dd><dt><span class="term">
- Post-fakeroot scripts (<code class="literal">BR2_ROOTFS_POST_FAKEROOT_SCRIPT</code>)
- </span></dt><dd><p class="simpara">When aggregating the final images, some parts of the process requires
- root rights: creating device nodes in <code class="literal">/dev</code>, setting permissions or
- ownership to files and directories… To avoid requiring actual root
- rights, Buildroot uses <code class="literal">fakeroot</code> to simulate root rights. This is not
- a complete substitute for actually being root, but is enough for what
- 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
- the fakeroot phase, <span class="emphasis"><em>right before</em></span> the filesystem image generator is
- 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
- filesystem to do modifications that are usually only available to the
- root user.</p><p><strong>Note: </strong>It is recommended to use the existing mechanisms to set file permissions
- 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
- 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,
- 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.
- <code class="literal">fakeroot</code> only ever fakes the file access rights and types (regular,
- 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
- or device nodes. For example, certain files may need to be owned by
- root. Since the post-build scripts are not run as root, you cannot do
- such changes from there unless you use an explicit fakeroot from the
- post-build script.</p><p>Instead, Buildroot provides support for so-called <span class="emphasis"><em>permission tables</em></span>.
- To use this feature, set config option <code class="literal">BR2_ROOTFS_DEVICE_TABLE</code> to a
- space-separated list of permission tables, regular text files following
- 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>,
- <code class="literal">mdev</code>, or <code class="literal">(e)udev</code>) then you can add device nodes using the same
- syntax, in so-called <span class="emphasis"><em>device tables</em></span>. To use this feature, set config
- option <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code> to a space-separated list of
- 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
- such files is <code class="literal">board/<company>/<boardname>/</code>.</p><p>It should be noted that if the specific permissions or device nodes are
- related to a specific application, you should set variables
- <code class="literal">FOO_PERMISSIONS</code> and <code class="literal">FOO_DEVICES</code> in the package’s <code class="literal">.mk</code> 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><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.
- To cover this requirement, Buildroot provides support for so-called
- <span class="emphasis"><em>users tables</em></span>. To use this feature, set config option
- <code class="literal">BR2_ROOTFS_USERS_TABLES</code> to a space-separated list of users tables,
- 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
- such files is <code class="literal">board/<company>/<boardname>/</code>.</p><p>It should be noted that if the custom users are related to a specific
- application, you should set variable <code class="literal">FOO_USERS</code> in the package’s <code class="literal">.mk</code>
- 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>
- building the filesystem image, kernel and bootloader, <span class="strong"><strong>post-image
- scripts</strong></span> can be used to perform some specific actions <span class="emphasis"><em>after</em></span> all images
- have been created.</p><p>Post-image scripts can for example be used to automatically extract your
- root filesystem tarball in a location exported by your NFS server, or
- to create a special firmware image that bundles your root filesystem and
- 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
- scripts in config option <code class="literal">BR2_ROOTFS_POST_IMAGE_SCRIPT</code> (in the <code class="literal">System
- configuration</code> menu). If you specify a relative path, it will be
- relative to the root of the Buildroot tree.</p><p>Just like post-build scripts, post-image scripts are run with the main
- Buildroot tree as current working directory. The path to the <code class="literal">images</code>
- output directory is passed as the first argument to each script. If the
- config option <code class="literal">BR2_ROOTFS_POST_SCRIPT_ARGS</code> is not empty, these
- arguments will be passed to the script too. All the scripts will be
- passed the exact same set of arguments, it is not possible to pass
- different sets of arguments to each script.</p><p>Again just like for the post-build scripts, the scripts have access to
- the environment variables <code class="literal">BR2_CONFIG</code>, <code class="literal">HOST_DIR</code>, <code class="literal">STAGING_DIR</code>,
- <code class="literal">TARGET_DIR</code>, <code class="literal">BUILD_DIR</code>, <code class="literal">BINARIES_DIR</code> and <code class="literal">BASE_DIR</code>.</p><p>The post-image scripts will be executed as the user that executes
- Buildroot, which should normally <span class="emphasis"><em>not</em></span> be the root user. Therefore, any
- action requiring root permissions in one of these scripts will require
- special handling (usage of fakeroot or sudo), which is left to the
- 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
- those provided in Buildroot. This might be used to support custom
- features in a project, for example, or when working on a new
- architecture.</p><p>The <code class="literal">BR2_GLOBAL_PATCH_DIR</code> configuration option can be used to specify
- a space separated list of one or more directories containing package
- patches.</p><p>For a specific version <code class="literal"><packageversion></code> of a specific package
- <code class="literal"><packagename></code>, patches are applied from <code class="literal">BR2_GLOBAL_PATCH_DIR</code> as
- follows:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p class="simpara">
- For every directory - <code class="literal"><global-patch-dir></code> - that exists in
- <code class="literal">BR2_GLOBAL_PATCH_DIR</code>, a <code class="literal"><package-patch-dir></code> will be determined as
- follows:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal"><global-patch-dir>/<packagename>/<packageversion>/</code> if the
- directory exists.
- </li><li class="listitem">
- Otherwise, <code class="literal"><global-patch-dir>/<packagename></code> if the directory
- exists.
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Patches will then be applied from a <code class="literal"><package-patch-dir></code> as
- follows:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- If a <code class="literal">series</code> file exists in the package directory, then patches are
- applied according to the <code class="literal">series</code> file;
- </li><li class="listitem">
- Otherwise, patch files matching <code class="literal">*.patch</code> are applied in
- alphabetical order. So, to ensure they are applied in the right
- order, it is highly recommended to name the patch files like this:
- <code class="literal"><number>-<description>.patch</code>, where <code class="literal"><number></code> refers to the
- <span class="emphasis"><em>apply order</em></span>.
- </li></ul></div></li></ol></div><p>For information about how patches are applied for a package, see
- <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
- specifying a custom patch directory for packages. It can be used to
- specify a patch directory for any package in buildroot. It should also
- be used in place of the custom patch directory options that are
- available for packages such as U-Boot and Barebox. By doing this, it
- will allow a user to manage their patches from one top-level
- directory.</p><p>The exception to <code class="literal">BR2_GLOBAL_PATCH_DIR</code> being the preferred method for
- specifying custom patches is <code class="literal">BR2_LINUX_KERNEL_PATCH</code>.
- <code class="literal">BR2_LINUX_KERNEL_PATCH</code> should be used to specify kernel patches that
- are available at a URL. <span class="strong"><strong>Note:</strong></span> <code class="literal">BR2_LINUX_KERNEL_PATCH</code> specifies kernel
- patches that are applied after patches available in <code class="literal">BR2_GLOBAL_PATCH_DIR</code>,
- 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>
- directory and submitted to the Buildroot upstream project. How to add
- packages to Buildroot in general is explained in full detail 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> and will not be repeated here. However, your
- project may need some proprietary packages that cannot be upstreamed.
- This section will explain how you can keep such project-specific
- 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
- project-specific packages is <code class="literal">package/<company>/</code>. If you are using the
- 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
- location is to put them in a sub-directory named <code class="literal">package/</code> in your
- br2-external tree.</p><p>However, Buildroot will not be aware of the packages in this location,
- unless we perform some additional steps. 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>, a package in Buildroot basically consists of two
- files: a <code class="literal">.mk</code> file (describing how to build the package) and a
- <code class="literal">Config.in</code> file (describing the configuration options for this
- package).</p><p>Buildroot will automatically include the <code class="literal">.mk</code> files in first-level
- subdirectories of the <code class="literal">package</code> directory (using the pattern
- <code class="literal">package/*/*.mk</code>). If we want Buildroot to include <code class="literal">.mk</code> files from
- deeper subdirectories (like <code class="literal">package/<company>/package1/</code>) then we
- simply have to add a <code class="literal">.mk</code> file in a first-level subdirectory that
- includes these additional <code class="literal">.mk</code> files. Therefore, create a file
- <code class="literal">package/<company>/<company>.mk</code> with following contents (assuming you
- have only one extra directory level below <code class="literal">package/<company>/</code>):</p><pre class="screen">include $(sort $(wildcard package/<company>/*/*.mk))</pre><p>For the <code class="literal">Config.in</code> files, create a file <code class="literal">package/<company>/Config.in</code>
- that includes the <code class="literal">Config.in</code> files of all your packages. An exhaustive
- list has to be provided since wildcards are not supported in the source command of kconfig.
- For example:</p><pre class="screen">source "package/<company>/package1/Config.in"
- source "package/<company>/package2/Config.in"</pre><p>Include this new file <code class="literal">package/<company>/Config.in</code> from
- <code class="literal">package/Config.in</code>, preferably in a company-specific menu to make
- 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
- 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
- project-specific customizations have been described. This section will
- now summarize all this by providing step-by-step instructions to storing your
- project-specific customizations. Clearly, the steps that are not relevant to
- your project can be skipped.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
- <code class="literal">make menuconfig</code> to configure toolchain, packages and kernel.
- </li><li class="listitem">
- <code class="literal">make linux-menuconfig</code> to update the kernel config, similar for
- other configuration like busybox, uclibc, …
- </li><li class="listitem">
- <code class="literal">mkdir -p board/<manufacturer>/<boardname></code>
- </li><li class="listitem"><p class="simpara">
- Set the following options to <code class="literal">board/<manufacturer>/<boardname>/<package>.config</code>
- (as far as they are relevant):
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code>
- </li><li class="listitem">
- <code class="literal">BR2_PACKAGE_BUSYBOX_CONFIG</code>
- </li><li class="listitem">
- <code class="literal">BR2_UCLIBC_CONFIG</code>
- </li><li class="listitem">
- <code class="literal">BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE</code>
- </li><li class="listitem">
- <code class="literal">BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE</code>
- </li><li class="listitem">
- <code class="literal">BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE</code>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Write the configuration files:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">make linux-update-defconfig</code>
- </li><li class="listitem">
- <code class="literal">make busybox-update-config</code>
- </li><li class="listitem">
- <code class="literal">make uclibc-update-config</code>
- </li><li class="listitem">
- <code class="literal">cp <output>/build/at91bootstrap3-*/.config
- board/<manufacturer>/<boardname>/at91bootstrap3.config</code>
- </li><li class="listitem">
- <code class="literal">make barebox-update-defconfig</code>
- </li><li class="listitem">
- <code class="literal">make uboot-update-defconfig</code>
- </li></ul></div></li><li class="listitem">
- Create <code class="literal">board/<manufacturer>/<boardname>/rootfs-overlay/</code> and fill it
- with additional files you need on your rootfs, e.g.
- <code class="literal">board/<manufacturer>/<boardname>/rootfs-overlay/etc/inittab</code>.
- Set <code class="literal">BR2_ROOTFS_OVERLAY</code>
- to <code class="literal">board/<manufacturer>/<boardname>/rootfs-overlay</code>.
- </li><li class="listitem">
- Create a post-build script
- <code class="literal">board/<manufacturer>/<boardname>/post_build.sh</code>. Set
- <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code> to
- <code class="literal">board/<manufacturer>/<boardname>/post_build.sh</code>
- </li><li class="listitem">
- If additional setuid permissions have to be set or device nodes have
- to be created, create <code class="literal">board/<manufacturer>/<boardname>/device_table.txt</code>
- and add that path to <code class="literal">BR2_ROOTFS_DEVICE_TABLE</code>.
- </li><li class="listitem">
- If additional user accounts have to be created, create
- <code class="literal">board/<manufacturer>/<boardname>/users_table.txt</code> and add that path
- to <code class="literal">BR2_ROOTFS_USERS_TABLES</code>.
- </li><li class="listitem">
- To add custom patches to certain packages, set <code class="literal">BR2_GLOBAL_PATCH_DIR</code>
- to <code class="literal">board/<manufacturer>/<boardname>/patches/</code> and add your patches
- for each package in a subdirectory named after the package. Each
- patch should be called <code class="literal"><packagename>-<num>-<description>.patch</code>.
- </li><li class="listitem">
- Specifically for the Linux kernel, there also exists the option
- <code class="literal">BR2_LINUX_KERNEL_PATCH</code> with as main advantage that it can also
- download patches from a URL. If you do not need this,
- <code class="literal">BR2_GLOBAL_PATCH_DIR</code> is preferred. U-Boot, Barebox, at91bootstrap
- and at91bootstrap3 also have separate options, but these do not
- provide any advantage over <code class="literal">BR2_GLOBAL_PATCH_DIR</code> and will likely be
- removed in the future.
- </li><li class="listitem">
- If you need to add project-specific packages, create
- <code class="literal">package/<manufacturer>/</code> and place your packages in that
- directory. Create an overall <code class="literal"><manufacturer>.mk</code> file that
- includes the <code class="literal">.mk</code> files of all your packages. Create an overall
- <code class="literal">Config.in</code> file that sources the <code class="literal">Config.in</code> files of all your
- packages. Include this <code class="literal">Config.in</code> file from Buildroot’s
- <code class="literal">package/Config.in</code> file.
- </li><li class="listitem">
- <code class="literal">make savedefconfig</code> to save the buildroot configuration.
- </li><li class="listitem">
- <code class="literal">cp defconfig configs/<boardname>_defconfig</code>
- </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
- enforcing access control policies. In addition to the traditional file
- permissions and access control lists, <code class="literal">SELinux</code> allows to write rules
- for users or processes to access specific functions of resources
- (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">
- <span class="emphasis"><em>Disabled</em></span>: the policy is not applied
- </li><li class="listitem">
- <span class="emphasis"><em>Permissive</em></span>: the policy is applied, and non-authorized actions are
- simply logged. This mode is often used for troubleshooting SELinux
- issues.
- </li><li class="listitem">
- <span class="emphasis"><em>Enforcing</em></span>: the policy is applied, and non-authorized actions are
- denied
- </li></ul></div><p>In Buildroot the mode of operation is controlled by the
- <code class="literal">BR2_PACKAGE_REFPOLICY_POLICY_STATE_*</code> configuration options. The
- Linux kernel also has various configuration options that affect how
- <code class="literal">SELinux</code> is enabled (see <code class="literal">security/selinux/Kconfig</code> in the Linux
- kernel sources).</p><p>By default in Buildroot the <code class="literal">SELinux</code> policy is provided by the
- upstream <a class="ulink" href="https://github.com/SELinuxProject/refpolicy" target="_top">refpolicy</a>
- 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,
- the following configuration options must be enabled:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">BR2_PACKAGE_LIBSELINUX</code>
- </li><li class="listitem">
- <code class="literal">BR2_PACKAGE_REFPOLICY</code>
- </li></ul></div><p>In addition, your filesystem image format must support extended
- 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
- disabled when being built. Each module provide a number of <code class="literal">SELinux</code>
- rules. In Buildroot the non-base modules are disabled by default and
- several ways to enable such modules are provided:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Packages can enable a list of <code class="literal">SELinux</code> modules within the <code class="literal">refpolicy</code> using
- the <code class="literal"><packagename>_SELINUX_MODULES</code> variable.
- </li><li class="listitem">
- Packages can provide additional <code class="literal">SELinux</code> modules by putting them (.fc, .if
- and .te files) in <code class="literal">package/<packagename>/selinux/</code>.
- </li><li class="listitem">
- Extra <code class="literal">SELinux</code> modules can be added in directories pointed by the
- <code class="literal">BR2_REFPOLICY_EXTRA_MODULES_DIRS</code> configuration option.
- </li><li class="listitem">
- Additional modules in the <code class="literal">refpolicy</code> can be enabled if listed in the
- <code class="literal">BR2_REFPOLICY_EXTRA_MODULES_DEPENDENCIES</code> configuration option.
- </li></ul></div><p>Buildroot also allows to completely override the <code class="literal">refpolicy</code>. This
- allows to provide a full custom policy designed specifically for a
- given system. When going this way, all of the above mechanisms are
- disabled: no extra <code class="literal">SElinux</code> module is added to the policy, and all
- the available modules within the custom policy are enabled and built
- into the final binary policy. The custom policy must be a fork of the
- 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
- variables have to be set:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">BR2_PACKAGE_REFPOLICY_CUSTOM_GIT</code>
- </li><li class="listitem">
- <code class="literal">BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_URL</code>
- </li><li class="listitem">
- <code class="literal">BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_VERSION</code>
- </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 & 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
- (messages not necessarily exactly similar, depending on the list of
- packages selected):</p><pre class="screen">Freeing init memory: 3972K
- Initializing random number generator... done.
- Starting network...
- 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
- the serial console. In order to have the system start a shell on your
- serial console, you have to go into the Buildroot configuration, in
- <code class="literal">System configuration</code>, modify <code class="literal">Run a getty (login prompt) after boot</code>
- and set the appropriate port and baud rate in the <code class="literal">getty options</code>
- submenu. This will automatically tune the <code class="literal">/etc/inittab</code> file of the
- 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
- 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">
- this feature was neither maintained nor tested, and often broken;
- </li><li class="listitem">
- this feature was only available for Buildroot toolchains;
- </li><li class="listitem">
- Buildroot mostly targets <span class="emphasis"><em>small</em></span> or <span class="emphasis"><em>very small</em></span> target hardware
- with limited resource onboard (CPU, ram, mass-storage), for which
- compiling on the target does not make much sense;
- </li><li class="listitem">
- Buildroot aims at easing the cross-compilation, making native
- compilation on the target unnecessary.
- </li></ul></div><p>If you need a compiler on your target anyway, then Buildroot is not
- suitable for your purpose. In such case, you need a <span class="emphasis"><em>real
- 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">
- <a class="ulink" href="http://www.openembedded.org" target="_top">openembedded</a>
- </li><li class="listitem">
- <a class="ulink" href="https://www.yoctoproject.org" target="_top">yocto</a>
- </li><li class="listitem">
- <a class="ulink" href="http://www.emdebian.org" target="_top">emdebian</a>
- </li><li class="listitem">
- <a class="ulink" href="https://fedoraproject.org/wiki/Architectures" target="_top">Fedora</a>
- </li><li class="listitem">
- <a class="ulink" href="http://en.opensuse.org/Portal:ARM" target="_top">openSUSE ARM</a>
- </li><li class="listitem">
- <a class="ulink" href="http://archlinuxarm.org" target="_top">Arch Linux ARM</a>
- </li><li class="listitem">
- …
- </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
- <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
- space with headers or static libraries.</p><p>Therefore, those files are always removed from the target since the
- 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
- hardware with limited resource onboard (CPU, ram, mass-storage), it
- does not make sense to waste space with the documentation data.</p><p>If you need documentation data on your target anyway, then Buildroot
- is not suitable for your purpose, and you should look for a <span class="emphasis"><em>real
- 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
- config menu, this most likely means that some of the package’s
- dependencies are not met.</p><p>To know more about the dependencies of a package, search for the
- 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
- correspond to the unmet dependencies) to finally be able to select
- the package.</p><p>If the package is not visible due to some unmet toolchain options,
- 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
- 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
- one, among these:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- file ownerships, modes and permissions are not correctly set in the
- target directory;
- </li><li class="listitem">
- device nodes are not created in the target directory.
- </li></ul></div><p>For these reasons, commands run through chroot, using the target
- 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
- root, then use the tarball image generated in <code class="literal">images/</code> and extract it
- 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
- general topic of "package management". To summarize, the idea
- would be to add some tracking of which Buildroot package installs
- what files, with the goals of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- being able to remove files installed by a package when this package
- gets unselected from the menuconfig;
- </li><li class="listitem">
- being able to generate binary packages (ipk or other format) that
- can be installed on the target without re-generating a new root
- filesystem image.
- </li></ul></div><p>In general, most people think it is easy to do: just track which package
- installed what and remove it when the package is unselected. However, it
- is much more complicated than that:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- It is not only about the <code class="literal">target/</code> directory, but also the sysroot in
- <code class="literal">host/<tuple>/sysroot</code> and the <code class="literal">host/</code> directory itself. All files
- installed in those directories by various packages must be tracked.
- </li><li class="listitem">
- When a package is unselected from the configuration, it is not
- sufficient to remove just the files it installed. One must also
- remove all its reverse dependencies (i.e. packages relying on it)
- and rebuild all those packages. For example, package A depends
- optionally on the OpenSSL library. Both are selected, and Buildroot
- is built. Package A is built with crypto support using OpenSSL.
- Later on, OpenSSL gets unselected from the configuration, but
- package A remains (since OpenSSL is an optional dependency, this
- is possible.) If only OpenSSL files are removed, then the files
- installed by package A are broken: they use a library that is no
- longer present on the target. Although this is technically doable,
- it adds a lot of complexity to Buildroot, which goes against the
- simplicity we try to stick to.
- </li><li class="listitem">
- In addition to the previous problem, there is the case where the
- optional dependency is not even known to Buildroot. For example,
- package A in version 1.0 never used OpenSSL, but in version 2.0 it
- automatically uses OpenSSL if available. If the Buildroot .mk file
- hasn’t been updated to take this into account, then package A will
- not be part of the reverse dependencies of OpenSSL and will not be
- removed and rebuilt when OpenSSL is removed. For sure, the .mk file
- of package A should be fixed to mention this optional dependency,
- but in the mean time, you can have non-reproducible behaviors.
- </li><li class="listitem">
- The request is to also allow changes in the menuconfig to be
- applied on the output directory without having to rebuild
- everything from scratch. However, this is very difficult to achieve
- in a reliable way: what happens when the suboptions of a package
- are changed (we would have to detect this, and rebuild the package
- from scratch and potentially all its reverse dependencies), what
- happens if toolchain options are changed, etc. At the moment, what
- Buildroot does is clear and simple so its behaviour is very
- reliable and it is easy to support users. If configuration changes
- done in menuconfig are applied after the next make, then it has to
- work correctly and properly in all situations, and not have some
- bizarre corner cases. The risk is to get bug reports like "I have
- enabled package A, B and C, then ran make, then disabled package
- C and enabled package D and ran make, then re-enabled package C
- and enabled package E and then there is a build failure". Or worse
- "I did some configuration, then built, then did some changes,
- built, some more changes, built, some more changes, built, and now
- it fails, but I don’t remember all the changes I did and in which
- order". This will be impossible to support.
- </li></ul></div><p>For all these reasons, the conclusion is that adding tracking of
- installed files to remove them when the package is unselected, or to
- generate a repository of binary packages, is something that is very
- 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">
- Buildroot strives to make it easy to generate a root filesystem (hence
- the name, by the way.) That is what we want to make Buildroot good at:
- building root filesystems.
- </li><li class="listitem">
- Buildroot is not meant to be a distribution (or rather, a distribution
- generator.) It is the opinion of most Buildroot developers that this
- is not a goal we should pursue. We believe that there are other tools
- better suited to generate a distro than Buildroot is. For example,
- <a class="ulink" href="http://openembedded.org/" target="_top">Open Embedded</a>, or <a class="ulink" href="https://openwrt.org/" target="_top">openWRT</a>,
- are such tools.
- </li><li class="listitem">
- We prefer to push Buildroot in a direction that makes it easy (or even
- easier) to generate complete root filesystems. This is what makes
- Buildroot stands out in the crowd (among other things, of course!)
- </li><li class="listitem">
- We believe that for most embedded Linux systems, binary packages are
- not necessary, and potentially harmful. When binary packages are
- used, it means that the system can be partially upgraded, which
- creates an enormous number of possible combinations of package
- versions that should be tested before doing the upgrade on the
- embedded device. On the other hand, by doing complete system
- upgrades by upgrading the entire root filesystem image at once,
- the image deployed to the embedded system is guaranteed to really
- be the one that has been tested and validated.
- </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
- system that can be quite long, we provide below a number of tips to
- help reduce the build time:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Use a pre-built external toolchain instead of the default Buildroot
- internal toolchain. By using a pre-built Linaro toolchain (on ARM)
- or a Sourcery CodeBench toolchain (for ARM, x86, x86-64, MIPS,
- etc.), you will save the build time of the toolchain at each
- complete rebuild, approximately 15 to 20 minutes. Note that
- temporarily using an external toolchain does not prevent you to
- switch back to an internal toolchain (that may provide a higher
- level of customization) once the rest of your system is working;
- </li><li class="listitem">
- 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>);
- </li><li class="listitem">
- Learn about rebuilding only the few packages you actually care
- 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
- 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>);
- </li><li class="listitem">
- Make sure you are not using a virtual machine for the Linux system
- used to run Buildroot. Most of the virtual machine technologies are
- known to cause a significant performance impact on I/O, which is
- really important for building source code;
- </li><li class="listitem">
- Make sure that you’re using only local files: do not attempt to do
- a build over NFS, which significantly slows down the build. Having
- the Buildroot download folder available locally also helps a bit.
- </li><li class="listitem">
- Buy new hardware. SSDs and lots of RAM are key to speeding up the
- builds.
- </li><li class="listitem">
- Experiment with top-level parallel build, see
- <a class="xref" href="#top-level-parallel-build" title="8.12. Top-level parallel build">Section 8.12, “Top-level parallel build”</a>.
- </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">
- It is not possible to pass extra linker options via <code class="literal">BR2_TARGET_LDFLAGS</code>
- if such options contain a <code class="literal">$</code> sign. For example, the following is known
- to break: <code class="literal">BR2_TARGET_LDFLAGS="-Wl,-rpath='$ORIGIN/../lib'"</code>
- </li><li class="listitem">
- The <code class="literal">libffi</code> package is not supported on the SuperH 2 and ARC
- architectures.
- </li><li class="listitem">
- The <code class="literal">prboom</code> package triggers a compiler failure with the SuperH 4
- compiler from Sourcery CodeBench, version 2012.09.
- </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,
- bootloaders) contain open source software, released under various licenses.</p><p>Using open source software gives you the freedom to build rich embedded
- systems, choosing from a wide range of packages, but also imposes some
- obligations that you must know and honour.
- Some licenses require you to publish the license text in the documentation of
- your product. Others require you to redistribute the source code of the
- software to those that receive your product.</p><p>The exact requirements of each license are documented in each package, and
- it is your responsibility (or that of your legal office) to comply with those
- requirements.
- To make this easier for you, Buildroot can collect for you some material you
- will probably need. To produce this material, after you have configured
- 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,
- under the <code class="literal">legal-info/</code> subdirectory.
- There you will find:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- A <code class="literal">README</code> file, that summarizes the produced material and contains warnings
- about material that Buildroot could not produce.
- </li><li class="listitem">
- <code class="literal">buildroot.config</code>: this is the Buildroot configuration file that is usually
- produced with <code class="literal">make menuconfig</code>, and which is necessary to reproduce the
- build.
- </li><li class="listitem">
- The source code for all packages; this is saved in the <code class="literal">sources/</code> and
- <code class="literal">host-sources/</code> subdirectories for target and host packages respectively.
- The source code for packages that set <code class="literal"><PKG>_REDISTRIBUTE = NO</code> will not be
- saved.
- Patches that were applied are also saved, along with a file named <code class="literal">series</code>
- that lists the patches in the order they were applied. Patches are under the
- same license as the files that they modify.
- Note: Buildroot applies additional patches to Libtool scripts of
- autotools-based packages. These patches can be found under
- <code class="literal">support/libtool</code> in the Buildroot source and, due to technical
- limitations, are not saved with the package sources. You may need to
- collect them manually.
- </li><li class="listitem">
- A manifest file (one for host and one for target packages) listing the
- configured packages, their version, license and related information.
- Some of this information might not be defined in Buildroot; such items are
- marked as "unknown".
- </li><li class="listitem">
- The license texts of all packages, in the <code class="literal">licenses/</code> and <code class="literal">host-licenses/</code>
- subdirectories for target and host packages respectively.
- If the license file(s) are not defined in Buildroot, the file is not produced
- and a warning in the <code class="literal">README</code> indicates this.
- </li></ul></div><p>Please note that the aim of the <code class="literal">legal-info</code> feature of Buildroot is to
- produce all the material that is somehow relevant for legal compliance with the
- package licenses. Buildroot does not try to produce the exact material that
- you must somehow make public. Certainly, more material is produced than is
- needed for a strict legal compliance. For example, it produces the source code
- for packages released under BSD-like licenses, that you are not required to
- redistribute in source form.</p><p>Moreover, due to technical limitations, Buildroot does not produce some
- material that you will or may need, such as the toolchain source code for
- some of the external toolchains and the Buildroot source code itself.
- When you run <code class="literal">make legal-info</code>, Buildroot produces warnings in the <code class="literal">README</code>
- 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
- declarative statements in each of the packages recipes. The Buildroot
- developers try to do their best to keep those declarative statements as
- accurate as possible, to the best of their knowledge. However, it is very
- well possible that those declarative statements are not all fully accurate
- nor exhaustive. You (or your legal department) <span class="emphasis"><em>have</em></span> to check the output
- of <code class="literal">make legal-info</code> before using it as your own compliance delivery. See
- the <span class="emphasis"><em>NO WARRANTY</em></span> clauses (clauses 11 and 12) in the <code class="literal">COPYING</code> file at the
- 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
- <a class="ulink" href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" target="_top">GNU General
- Public License, version 2</a> or (at your option) any later version, with
- the exception of the package patches detailed below.
- However, being a build system, it is not normally part of the end product:
- if you develop the root filesystem, kernel, bootloader or toolchain for a
- device, the code of Buildroot is only present on the development machine, not
- in the device storage.</p><p>Nevertheless, the general view of the Buildroot developers is that you should
- release the Buildroot source code along with the source code of other packages
- when releasing a product that contains GPL-licensed software.
- This is because the
- <a class="ulink" href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" target="_top">GNU GPL</a>
- defines the "<span class="emphasis"><em>complete source code</em></span>" for an executable work as "<span class="emphasis"><em>all the
- source code for all modules it contains, plus any associated interface
- definition files, plus the scripts used to control compilation and installation
- of the executable</em></span>".
- Buildroot is part of the <span class="emphasis"><em>scripts used to control compilation and
- installation of the executable</em></span>, and as such it is considered part of the
- material that must be redistributed.</p><p>Keep in mind that this is only the Buildroot developers' opinion, and you
- 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
- of the various packages. Those patches are not covered by the license
- of Buildroot. Instead, they are covered by the license of the software
- to which the patches are applied. When said software is available
- under multiple licenses, the Buildroot patches are only provided under
- 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
- images</em></span> menu.</p><p>After a complete build, just run the following commands to setup the
- 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
- <span class="emphasis"><em>Filesystem images</em></span> menu. Note that this option is only available on
- the x86 and x86-64 architectures, and if you are building your kernel
- with Buildroot.</p><p>You can build a live CD image with either IsoLinux, Grub or Grub 2 as
- a bootloader, but only Isolinux supports making this image usable both
- 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
- you should be aware of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- you should setup the new root from the <span class="emphasis"><em>tar root filesystem</em></span> image;
- </li><li class="listitem">
- either the selected target architecture is compatible with your host
- machine, or you should use some <code class="literal">qemu-*</code> binary and correctly set it
- within the <code class="literal">binfmt</code> properties to be able to run the binaries built
- for the target on your host machine;
- </li><li class="listitem">
- Buildroot does not currently provide <code class="literal">host-qemu</code> and <code class="literal">binfmt</code>
- correctly built and set for that kind of use.
- </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
- download, configure, and compile software with the correct options. It
- also includes patches for various software packages - mainly the ones
- involved in the cross-compilation toolchain (<code class="literal">gcc</code>, <code class="literal">binutils</code> and
- <code class="literal">uClibc</code>).</p><p>There is basically one Makefile per software package, and they are
- named with the <code class="literal">.mk</code> extension. Makefiles are split into many different
- parts.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- The <code class="literal">toolchain/</code> directory contains the Makefiles
- and associated files for all software related to the
- cross-compilation toolchain: <code class="literal">binutils</code>, <code class="literal">gcc</code>, <code class="literal">gdb</code>,
- <code class="literal">kernel-headers</code> and <code class="literal">uClibc</code>.
- </li><li class="listitem">
- The <code class="literal">arch/</code> directory contains the definitions for all the processor
- architectures that are supported by Buildroot.
- </li><li class="listitem">
- The <code class="literal">package/</code> directory contains the Makefiles and
- associated files for all user-space tools and libraries that Buildroot
- can compile and add to the target root filesystem. There is one
- sub-directory per package.
- </li><li class="listitem">
- The <code class="literal">linux/</code> directory contains the Makefiles and associated files for
- the Linux kernel.
- </li><li class="listitem">
- The <code class="literal">boot/</code> directory contains the Makefiles and associated files for
- the bootloaders supported by Buildroot.
- </li><li class="listitem">
- The <code class="literal">system/</code> directory contains support for system integration, e.g.
- the target filesystem skeleton and the selection of an init system.
- </li><li class="listitem">
- The <code class="literal">fs/</code> directory contains the Makefiles and
- associated files for software related to the generation of the
- target root filesystem image.
- </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">
- <code class="literal">something.mk</code> is the Makefile that downloads, configures,
- compiles and installs the package <code class="literal">something</code>.
- </li><li class="listitem">
- <code class="literal">Config.in</code> is a part of the configuration tool
- description file. It describes the options related to the
- package.
- </li></ul></div><p>The main Makefile performs the following steps (once the
- configuration is done):</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Create all the output directories: <code class="literal">staging</code>, <code class="literal">target</code>, <code class="literal">build</code>,
- etc. in the output directory (<code class="literal">output/</code> by default,
- another value can be specified using <code class="literal">O=</code>)
- </li><li class="listitem">
- Generate the toolchain target. When an internal toolchain is used, this
- means generating the cross-compilation toolchain. When an external
- toolchain is used, this means checking the features of the external
- toolchain and importing it into the Buildroot environment.
- </li><li class="listitem">
- Generate all the targets listed in the <code class="literal">TARGETS</code> variable. This
- variable is filled by all the individual components'
- Makefiles. Generating these targets will trigger the compilation of
- the userspace packages (libraries, programs), the kernel, the
- bootloader and the generation of the root filesystem images,
- depending on the configuration.
- </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
- Buildroot or refactor existing ones.</p><p>If you slightly modify some existing file, the important thing is
- 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">
- either follow the potentially deprecated coding style used in this
- file,
- </li><li class="listitem">
- or entirely rework it in order to make it comply with these rules.
- </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
- Buildroot.</p><p>An entry has the following pattern:</p><pre class="screen">config BR2_PACKAGE_LIBFOO
- bool "libfoo"
- depends on BR2_PACKAGE_LIBBAZ
- select BR2_PACKAGE_LIBBAR
- help
- This is a comment that explains what libfoo is. The help text
- should be wrapped.
- http://foosoftware.org/libfoo/</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- 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
- with one tab.
- </li><li class="listitem">
- The help text itself should be indented with one tab and two
- spaces.
- </li><li class="listitem">
- The help text should be wrapped to fit 72 columns, where tab counts
- for 8, so 62 characters in the text itself.
- </li></ul></div><p>The <code class="literal">Config.in</code> files are the input for the configuration tool
- used in Buildroot, which is the regular <span class="emphasis"><em>Kconfig</em></span>. For further
- details about the <span class="emphasis"><em>Kconfig</em></span> language, refer to
- <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">
- Header: The file starts with a header. It contains the module name,
- preferably in lowercase, enclosed between separators made of 80 hashes. A
- blank line is mandatory after the header:
- </p><pre class="screen">################################################################################
- #
- # libfoo
- #
- ################################################################################</pre></li><li class="listitem"><p class="simpara">
- Assignment: use <code class="literal">=</code> preceded and followed by one space:
- </p><pre class="screen">LIBFOO_VERSION = 1.0
- 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">
- Indentation: use tab only:
- </p><pre class="screen">define LIBFOO_REMOVE_DOC
- $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
- $(TARGET_DIR)/usr/share/man/man3/libfoo*
- endef</pre><p class="simpara">Note that commands inside a <code class="literal">define</code> block should always start with a tab,
- so <span class="emphasis"><em>make</em></span> recognizes them as commands.</p></li><li class="listitem"><p class="simpara">
- Optional dependency:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p class="simpara">
- Prefer multi-line syntax.
- </p><p class="simpara">YES:</p><pre class="screen">ifeq ($(BR2_PACKAGE_PYTHON),y)
- LIBFOO_CONF_OPTS += --with-python-support
- LIBFOO_DEPENDENCIES += python
- else
- LIBFOO_CONF_OPTS += --without-python-support
- endif</pre><p class="simpara">NO:</p><pre class="screen">LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
- LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)</pre></li><li class="listitem">
- Keep configure options and dependencies close together.
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Optional hooks: keep hook definition and assignment together in one
- if block.
- </p><p class="simpara">YES:</p><pre class="screen">ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
- define LIBFOO_REMOVE_DATA
- $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
- endef
- LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
- endif</pre><p class="simpara">NO:</p><pre class="screen">define LIBFOO_REMOVE_DATA
- $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
- endef
- ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
- LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
- 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
- <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
- <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
- Python and should follow the
- <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
- hardware boards, so that users of such a board can easily build a system
- that is known to work. You are welcome to add support for other boards
- to Buildroot too.</p><p>To do so, you need to create a normal Buildroot configuration that
- builds a basic system for the hardware: (internal) toolchain, kernel,
- bootloader, filesystem and a simple BusyBox-only userspace. No specific
- package should be selected: the configuration should be as minimal as
- possible, and should only build a working basic BusyBox system for the
- target platform. You can of course use more complicated configurations
- for your internal projects, but the Buildroot project will only
- integrate basic board configurations. This is because package
- selections are highly application-specific.</p><p>Once you have a known working configuration, run <code class="literal">make
- savedefconfig</code>. This will generate a minimal <code class="literal">defconfig</code> file at the
- root of the Buildroot source tree. Move this file into the <code class="literal">configs/</code>
- directory, and rename it <code class="literal"><boardname>_defconfig</code>. If the configuration
- is a bit more complicated, it is nice to manually reformat it and
- separate it into sections, with a comment before each section. Typical
- sections are <span class="emphasis"><em>Architecture</em></span>, <span class="emphasis"><em>Toolchain options</em></span> (typically just linux
- 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
- components, not the "latest" version. For example, set
- <code class="literal">BR2_LINUX_KERNEL_CUSTOM_VERSION=y</code> and
- <code class="literal">BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE</code> to the kernel version you tested
- with.</p><p>It is recommended to use as much as possible upstream versions of the
- Linux kernel and bootloaders, and to use as much as possible default
- kernel and bootloader configurations. If they are incorrect for your
- board, or no default exists, we encourage you to send fixes to the
- corresponding upstream projects.</p><p>However, in the mean time, you may want to store kernel or bootloader
- configuration or patches specific to your target platform. To do so,
- create a directory <code class="literal">board/<manufacturer></code> and a subdirectory
- <code class="literal">board/<manufacturer>/<boardname></code>. You can then store your patches
- and configurations in these directories, and reference them from the main
- 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
- applications) can be integrated into Buildroot. It also shows how
- existing packages are integrated, which is needed for fixing issues or
- tuning their configuration.</p><p>When you add a new package, be sure to test it in various conditions
- (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
- <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
- your software, for example <code class="literal">libfoo</code>.</p><p>Some packages have been grouped by topic in a sub-directory:
- <code class="literal">x11r7</code>, <code class="literal">qt5</code> and <code class="literal">gstreamer</code>. If your package fits in
- one of these categories, then create your package directory in these.
- 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
- create a Config file in your package directory. There are two types:
- <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
- file will contain the option descriptions related to our <code class="literal">libfoo</code> software
- that will be used and displayed in the configuration tool. It should basically
- contain:</p><pre class="screen">config BR2_PACKAGE_LIBFOO
- bool "libfoo"
- help
- This is a comment that explains what libfoo is. The help text
- should be wrapped.
- 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
- configuration option must be indented with one tab. The help text
- itself should be indented with one tab and two spaces, lines should
- be wrapped to fit 72 columns, where tab counts for 8, so 62 characters
- in the text itself. The help text must mention the upstream URL of the
- project after an empty line.</p><p>As a convention specific to Buildroot, the ordering of the attributes
- is as follows:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
- The type of option: <code class="literal">bool</code>, <code class="literal">string</code>… with the prompt
- </li><li class="listitem">
- If needed, the <code class="literal">default</code> value(s)
- </li><li class="listitem">
- Any dependencies on the target in <code class="literal">depends on</code> form
- </li><li class="listitem">
- Any dependencies on the toolchain in <code class="literal">depends on</code> form
- </li><li class="listitem">
- Any dependencies on other packages in <code class="literal">depends on</code> form
- </li><li class="listitem">
- Any dependency of the <code class="literal">select</code> form
- </li><li class="listitem">
- The help keyword and help text.
- </li></ol></div><p>You can add other sub-options into a <code class="literal">if BR2_PACKAGE_LIBFOO…endif</code>
- statement to configure particular things in your software. You can look at
- examples in other packages. The syntax of the <code class="literal">Config.in</code> file is the same
- as the one for the kernel Kconfig file. The documentation for this syntax is
- 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
- <code class="literal">package/Config.in</code> (or in a category subdirectory if you decided to
- put your package in one of the existing categories). The files
- included there are <span class="emphasis"><em>sorted alphabetically</em></span> per category 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/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
- options here:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- The host package is only required to satisfy build-time
- dependencies of one or more target packages. In this case, add
- <code class="literal">host-foo</code> to the target package’s <code class="literal">BAR_DEPENDENCIES</code> variable. No
- <code class="literal">Config.in.host</code> file should be created.
- </li><li class="listitem"><p class="simpara">
- The host package should be explicitly selectable by the user from
- the configuration menu. In this case, create a <code class="literal">Config.in.host</code> file
- for that host package:
- </p><pre class="screen">config BR2_PACKAGE_HOST_FOO
- bool "host foo"
- help
- This is a comment that explains what foo for the host is.
- 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
- <code class="literal">package/Config.in.host</code>. The files included there are <span class="emphasis"><em>sorted alphabetically</em></span>
- 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
- dependencies are enabled. Typically, Buildroot uses the following
- rules:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Use a <code class="literal">select</code> type of dependency for dependencies on
- libraries. These dependencies are generally not obvious and it
- therefore make sense to have the kconfig system ensure that the
- dependencies are selected. For example, the <span class="emphasis"><em>libgtk2</em></span> package uses
- <code class="literal">select BR2_PACKAGE_LIBGLIB2</code> to make sure this library is also
- enabled.
- The <code class="literal">select</code> keyword expresses the dependency with a backward
- semantic.
- </li><li class="listitem">
- Use a <code class="literal">depends on</code> type of dependency when the user really needs to
- be aware of the dependency. Typically, Buildroot uses this type of
- dependency for dependencies on target architecture, MMU support and
- 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>),
- or for dependencies on "big" things, such as the X.org system.
- The <code class="literal">depends on</code> keyword expresses the dependency with a forward
- semantic.
- </li></ul></div><p><strong>Note. </strong>The current problem with the <span class="emphasis"><em>kconfig</em></span> language is that these two
- dependency semantics are not internally linked. Therefore, it may be
- possible to select a package, whom one of its dependencies/requirement
- 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
- bool "rrdtool"
- depends on BR2_USE_WCHAR
- select BR2_PACKAGE_FREETYPE
- select BR2_PACKAGE_LIBART
- select BR2_PACKAGE_LIBPNG
- select BR2_PACKAGE_ZLIB
- help
- RRDtool is the OpenSource industry standard, high performance
- data logging and graphing system for time series data.
- http://oss.oetiker.ch/rrdtool/
- comment "rrdtool needs a toolchain w/ wchar"
- depends on !BR2_USE_WCHAR</pre><p>Note that these two dependency types are only transitive with the
- dependencies of the same kind.</p><p>This means, in the following example:</p><pre class="screen">config BR2_PACKAGE_A
- bool "Package A"
- config BR2_PACKAGE_B
- bool "Package B"
- depends on BR2_PACKAGE_A
- config BR2_PACKAGE_C
- bool "Package C"
- depends on BR2_PACKAGE_B
- config BR2_PACKAGE_D
- bool "Package D"
- select BR2_PACKAGE_B
- config BR2_PACKAGE_E
- bool "Package E"
- select BR2_PACKAGE_D</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Selecting <code class="literal">Package C</code> will be visible if <code class="literal">Package B</code> has been
- selected, which in turn is only visible if <code class="literal">Package A</code> has been
- selected.
- </li><li class="listitem">
- Selecting <code class="literal">Package E</code> will select <code class="literal">Package D</code>, which will select
- <code class="literal">Package B</code>, it will not check for the dependencies of <code class="literal">Package B</code>,
- so it will not select <code class="literal">Package A</code>.
- </li><li class="listitem">
- Since <code class="literal">Package B</code> is selected but <code class="literal">Package A</code> is not, this violates
- the dependency of <code class="literal">Package B</code> on <code class="literal">Package A</code>. Therefore, in such a
- situation, the transitive dependency has to be added explicitly:
- </li></ul></div><pre class="screen">config BR2_PACKAGE_D
- bool "Package D"
- select BR2_PACKAGE_B
- depends on BR2_PACKAGE_A
- config BR2_PACKAGE_E
- bool "Package E"
- select BR2_PACKAGE_D
- depends on BR2_PACKAGE_A</pre><p>Overall, for package library dependencies, <code class="literal">select</code> should be
- preferred.</p><p>Note that such dependencies will ensure that the dependency option
- is also enabled, but not necessarily built before your package. To do
- so, the dependency also needs to be expressed in the <code class="literal">.mk</code> file of the
- package.</p><p>Further formatting details: see <a class="link" href="#writing-rules-config-in" title="16.1. Config.in file">the
- 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
- C library, C++ support, thread support, RPC support, wchar support,
- or dynamic library support. Some packages can only be built on certain
- 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
- on</em></span> statements in the Config.in file. Additionally, for dependencies on
- toolchain options, a <code class="literal">comment</code> should be displayed when the option is
- not enabled, so that the user knows why the package is not available.
- Dependencies on target architecture or MMU support should not be
- made visible in a comment: since it is unlikely that the user can
- freely choose another target, it makes little sense to show these
- dependencies explicitly.</p><p>The <code class="literal">comment</code> should only be visible if the <code class="literal">config</code> option itself would
- be visible when the toolchain option dependencies are met. This means
- that all other dependencies of the package (including dependencies on
- target architecture and MMU support) have to be repeated on the
- <code class="literal">comment</code> definition. To keep it clear, the <code class="literal">depends on</code> statement for
- these non-toolchain option should be kept separate from the <code class="literal">depends on</code>
- statement for the toolchain options.
- If there is a dependency on a config option in that same file (typically
- the main package) it is preferable to have a global <code class="literal">if … endif</code>
- construct rather than repeating the <code class="literal">depends on</code> statement on the
- 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
- 80-character terminal.</p><p>The rest of this section enumerates the different target and toolchain
- options, the corresponding config symbols to depend on, and the text to
- use in the comment.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
- Target architecture
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_powerpc</code>, <code class="literal">BR2_mips</code>, … (see <code class="literal">arch/Config.in</code>)
- </li><li class="listitem">
- Comment string: no comment to be added
- </li></ul></div></li><li class="listitem"><p class="simpara">
- MMU support
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_USE_MMU</code>
- </li><li class="listitem">
- Comment string: no comment to be added
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Gcc <code class="literal"><span class="emphasis"><em>_sync</em></span>*</code> built-ins used for atomic operations. They are
- available in variants operating on 1 byte, 2 bytes, 4 bytes and 8
- bytes. Since different architectures support atomic operations on
- different sizes, one dependency symbol is available for each size:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_1</code> for 1 byte,
- <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_2</code> for 2 bytes,
- <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_4</code> for 4 bytes, <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_8</code>
- for 8 bytes.
- </li><li class="listitem">
- Comment string: no comment to be added
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Gcc <code class="literal"><span class="emphasis"><em>_atomic</em></span>*</code> built-ins used for atomic operations.
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_ATOMIC</code>.
- </li><li class="listitem">
- Comment string: no comment to be added
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Kernel headers
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y</code>, (replace
- <code class="literal">X_Y</code> with the proper version, see <code class="literal">toolchain/Config.in</code>)
- </li><li class="listitem">
- Comment string: <code class="literal">headers >= X.Y</code> and/or <code class="literal">headers <= X.Y</code> (replace
- <code class="literal">X.Y</code> with the proper version)
- </li></ul></div></li><li class="listitem"><p class="simpara">
- GCC version
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_TOOLCHAIN_GCC_AT_LEAST_X_Y</code>, (replace
- <code class="literal">X_Y</code> with the proper version, see <code class="literal">toolchain/Config.in</code>)
- </li><li class="listitem">
- Comment string: <code class="literal">gcc >= X.Y</code> and/or <code class="literal">gcc <= X.Y</code> (replace
- <code class="literal">X.Y</code> with the proper version)
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Host GCC version
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_HOST_GCC_AT_LEAST_X_Y</code>, (replace
- <code class="literal">X_Y</code> with the proper version, see <code class="literal">Config.in</code>)
- </li><li class="listitem">
- Comment string: no comment to be added
- </li><li class="listitem">
- Note that it is usually not the package itself that has a minimum
- host GCC version, but rather a host-package on which it depends.
- </li></ul></div></li><li class="listitem"><p class="simpara">
- C library
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_TOOLCHAIN_USES_GLIBC</code>,
- <code class="literal">BR2_TOOLCHAIN_USES_MUSL</code>, <code class="literal">BR2_TOOLCHAIN_USES_UCLIBC</code>
- </li><li class="listitem">
- Comment string: for the C library, a slightly different comment text
- is used: <code class="literal">foo needs a glibc toolchain</code>, or <code class="literal">foo needs a glibc
- toolchain w/ C++</code>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- C++ support
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_INSTALL_LIBSTDCPP</code>
- </li><li class="listitem">
- Comment string: <code class="literal">C++</code>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- D support
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_DLANG</code>
- </li><li class="listitem">
- Comment string: <code class="literal">Dlang</code>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- Fortran support
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_FORTRAN</code>
- </li><li class="listitem">
- Comment string: <code class="literal">fortran</code>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- thread support
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_THREADS</code>
- </li><li class="listitem">
- Comment string: <code class="literal">threads</code> (unless <code class="literal">BR2_TOOLCHAIN_HAS_THREADS_NPTL</code>
- is also needed, in which case, specifying only <code class="literal">NPTL</code> is sufficient)
- </li></ul></div></li><li class="listitem"><p class="simpara">
- NPTL thread support
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_THREADS_NPTL</code>
- </li><li class="listitem">
- Comment string: <code class="literal">NPTL</code>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- RPC support
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_NATIVE_RPC</code>
- </li><li class="listitem">
- Comment string: <code class="literal">RPC</code>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- wchar support
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">BR2_USE_WCHAR</code>
- </li><li class="listitem">
- Comment string: <code class="literal">wchar</code>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- dynamic library
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- Dependency symbol: <code class="literal">!BR2_STATIC_LIBS</code>
- </li><li class="listitem">
- Comment string: <code class="literal">dynamic library</code>
- </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
- typically kernel modules or firmware. A comment should be added in the
- Config.in file to express this dependency, similar to dependencies on
- 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
- 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
- <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
- 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
- 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
- describes how the package should be downloaded, configured, built,
- installed, etc.</p><p>Depending on the package type, the <code class="literal">.mk</code> file must be written in a
- different way, using different infrastructures:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <span class="strong"><strong>Makefiles for generic packages</strong></span> (not using autotools or CMake):
- These are based on an infrastructure similar to the one used for
- autotools-based packages, but require a little more work from the
- developer. They specify what should be done for the configuration,
- compilation and installation of the package. This
- infrastructure must be used for all packages that do not use the
- autotools as their build system. In the future, other specialized
- infrastructures might be written for other build systems. We cover
- them through in a <a class="link" href="#generic-package-tutorial" title="18.5.1. generic-package tutorial">tutorial</a> and a
- <a class="link" href="#generic-package-reference" title="18.5.2. generic-package reference">reference</a>.
- </li><li class="listitem">
- <span class="strong"><strong>Makefiles for autotools-based software</strong></span> (autoconf, automake, etc.):
- We provide a dedicated infrastructure for such packages, since
- autotools is a very common build system. This infrastructure <span class="emphasis"><em>must</em></span>
- be used for new packages that rely on the autotools as their build
- system. We cover them through a <a class="link" href="#autotools-package-tutorial" title="18.6.1. autotools-package tutorial">tutorial</a>
- and <a class="link" href="#autotools-package-reference" title="18.6.2. autotools-package reference">reference</a>.
- </li><li class="listitem">
- <span class="strong"><strong>Makefiles for cmake-based software</strong></span>: We provide a dedicated
- infrastructure for such packages, as CMake is a more and more
- commonly used build system and has a standardized behaviour. This
- infrastructure <span class="emphasis"><em>must</em></span> be used for new packages that rely on
- CMake. We cover them through a <a class="link" href="#cmake-package-tutorial" title="18.7.1. cmake-package tutorial">tutorial</a>
- and <a class="link" href="#cmake-package-reference" title="18.7.2. cmake-package reference">reference</a>.
- </li><li class="listitem">
- <span class="strong"><strong>Makefiles for Python modules</strong></span>: We have a dedicated infrastructure
- for Python modules that use either the <code class="literal">distutils</code> or the
- <code class="literal">setuptools</code> mechanism. We cover them through a
- <a class="link" href="#python-package-tutorial" title="18.8.1. python-package tutorial">tutorial</a> and a
- <a class="link" href="#python-package-reference" title="18.8.2. python-package reference">reference</a>.
- </li><li class="listitem">
- <span class="strong"><strong>Makefiles for Lua modules</strong></span>: We have a dedicated infrastructure for
- Lua modules available through the LuaRocks web site. We cover them
- through a <a class="link" href="#luarocks-package-tutorial" title="18.9.1. luarocks-package tutorial">tutorial</a> and a
- <a class="link" href="#luarocks-package-reference" title="18.9.2. luarocks-package reference">reference</a>.
- </li></ul></div><p>Further formatting details: see <a class="link" href="#writing-rules-mk" title="16.2. The .mk file">the writing
- 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
- contains the hashes of the downloaded files for the <code class="literal">libfoo</code>
- package. The only reason for not adding a <code class="literal">.hash</code> file is when hash
- 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
- stored in a subdirectory named after the version, e.g.
- <code class="literal">package/libfoo/1.2.3/libfoo.hash</code>. This is especially important if the
- different versions have different licensing terms, but they are stored
- in the same file. Otherwise, the hash file should stay in the package’s
- directory.</p><p>The hashes stored in that file are used to validate the integrity of the
- 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
- 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">
- the type of hash, one of:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <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>
- </li></ul></div></li><li class="listitem"><p class="simpara">
- the hash of the file:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- for <code class="literal">none</code>, one or more non-space chars, usually just the string <code class="literal">xxx</code>
- </li><li class="listitem">
- for <code class="literal">md5</code>, 32 hexadecimal characters
- </li><li class="listitem">
- for <code class="literal">sha1</code>, 40 hexadecimal characters
- </li><li class="listitem">
- for <code class="literal">sha224</code>, 56 hexadecimal characters
- </li><li class="listitem">
- for <code class="literal">sha256</code>, 64 hexadecimal characters
- </li><li class="listitem">
- for <code class="literal">sha384</code>, 96 hexadecimal characters
- </li><li class="listitem">
- for <code class="literal">sha512</code>, 128 hexadecimal characters
- </li></ul></div></li><li class="listitem"><p class="simpara">
- the name of the file:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- for a source archive: the basename of the file, without any directory
- component,
- </li><li class="listitem">
- for a license file: the path as it appears in <code class="literal">FOO_LICENSE_FILES</code>.
- </li></ul></div></li></ul></div><p>Lines starting with a <code class="literal">#</code> sign are considered comments, and ignored. Empty
- lines are ignored.</p><p>There can be more than one hash for a single file, each on its own line. In
- this case, all hashes must match.</p><p><strong>Note. </strong>Ideally, the hashes stored in this file should match the hashes published by
- upstream, e.g. on their website, in the e-mail announcement… If upstream
- provides more than one type of hash (e.g. <code class="literal">sha1</code> and <code class="literal">sha512</code>), then it is
- best to add all those hashes in the <code class="literal">.hash</code> file. If upstream does not
- provide any hash, or only provides an <code class="literal">md5</code> hash, then compute at least one
- strong hash yourself (preferably <code class="literal">sha256</code>, but not <code class="literal">md5</code>), and mention
- 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
- package version is bumped. The hashes are checked during the make legal-info
- target run. For a package with multiple versions (like Qt5),
- create the hash file in a subdirectory <code class="literal"><packageversion></code> of that package
- (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
- 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
- the main <code class="literal">libfoo-1.2.3.tar.bz2</code> tarball, an <code class="literal">md5</code> from upstream and a
- locally-computed <code class="literal">sha256</code> hashes for a binary blob, a <code class="literal">sha256</code> for a
- 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}:
- sha1 486fb55c3efa71148fe07895fd713ea3a5ae343a libfoo-1.2.3.tar.bz2
- sha256 efc8103cc3bcb06bda6a781532d12701eb081ad83e8f90004b39ab81b65d4369 libfoo-1.2.3.tar.bz2
- # md5 from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.md5, sha256 locally computed:
- md5 2d608f3c318c6b7557d551a5a09314f03452f1a1 libfoo-data.bin
- sha256 01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b libfoo-data.bin
- # Locally computed:
- sha256 ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9 libfoo-fix-blabla.patch
- # No hash for 1234:
- none xxx libfoo-1234.tar.gz
- # Hash for license files:
- sha256 a45a845012742796534f7e91fe623262ccfb99460a2bd04015bd28d66fba95b8 COPYING
- 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
- downloaded file, the hash(es) computed by Buildroot (after download) must
- match the hash(es) stored in the <code class="literal">.hash</code> file. If one or more hashes do
- not match, Buildroot considers this an error, deletes the downloaded file,
- and aborts.</p><p>If the <code class="literal">.hash</code> file is present, but it does not contain a hash for a
- downloaded file, Buildroot considers this an error and aborts. However,
- the downloaded file is left in the download directory since this
- typically indicates that the <code class="literal">.hash</code> file is wrong but the downloaded
- file is probably OK.</p><p>Hashes are currently checked for files fetched from http/ftp servers,
- Git repositories, files copied using scp and local files. Hashes are
- not checked for other version control systems (such as Subversion,
- CVS, etc.) because Buildroot currently does not generate reproducible
- tarballs when source code is fetched from such version control
- systems.</p><p>Hashes should only be added in <code class="literal">.hash</code> files for files that are
- guaranteed to be stable. For example, patches auto-generated by Github
- are not guaranteed to be stable, and therefore their hashes can change
- over time. Such patches should not be downloaded, and instead be added
- 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
- whose build system is not one of the standard ones, such as
- <span class="emphasis"><em>autotools</em></span> or <span class="emphasis"><em>CMake</em></span>. This typically includes packages whose build
- 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: ################################################################################
- 02: #
- 03: # libfoo
- 04: #
- 05: ################################################################################
- 06:
- 07: LIBFOO_VERSION = 1.0
- 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
- 09: LIBFOO_SITE = http://www.foosoftware.org/download
- 10: LIBFOO_LICENSE = GPL-3.0+
- 11: LIBFOO_LICENSE_FILES = COPYING
- 12: LIBFOO_INSTALL_STAGING = YES
- 13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
- 14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
- 15:
- 16: define LIBFOO_BUILD_CMDS
- 17: $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
- 18: endef
- 19:
- 20: define LIBFOO_INSTALL_STAGING_CMDS
- 21: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
- 22: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
- 23: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
- 24: endef
- 25:
- 26: define LIBFOO_INSTALL_TARGET_CMDS
- 27: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
- 28: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
- 29: endef
- 30:
- 31: define LIBFOO_USERS
- 32: foo -1 libfoo -1 * - - - LibFoo daemon
- 33: endef
- 34:
- 35: define LIBFOO_DEVICES
- 36: /dev/foo c 666 0 0 42 0 - - -
- 37: endef
- 38:
- 39: define LIBFOO_PERMISSIONS
- 40: /bin/foo f 4755 foo libfoo - - - - -
- 41: endef
- 42:
- 43: $(eval $(generic-package))</pre><p>The Makefile begins on line 7 to 11 with metadata information: the
- version of the package (<code class="literal">LIBFOO_VERSION</code>), the name of the
- tarball containing the package (<code class="literal">LIBFOO_SOURCE</code>) (xz-ed tarball recommended)
- the Internet location at which the tarball can be downloaded from
- (<code class="literal">LIBFOO_SITE</code>), the license (<code class="literal">LIBFOO_LICENSE</code>) and file with the
- license text (<code class="literal">LIBFOO_LICENSE_FILES</code>). All variables must start with
- the same prefix, <code class="literal">LIBFOO_</code> in this case. This prefix is always the
- uppercased version of the package name (see below to understand where
- the package name is defined).</p><p>On line 12, we specify that this package wants to install something to
- the staging space. This is often needed for libraries, since they must
- install header files and other development files in the staging space.
- This will ensure that the commands listed in the
- <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
- of the <span class="emphasis"><em>libfoo-config</em></span> files that were installed during
- <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code> phase.
- These *-config files are executable shell script files that are
- located in <span class="emphasis"><em>$(STAGING_DIR)/usr/bin</em></span> directory and are executed
- by other 3rd party packages to find out the location and the linking
- flags of this particular package.</p><p>The problem is that all these *-config files by default give wrong,
- 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>
- 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
- flags.
- The argument to be given to <code class="literal">LIBFOO_CONFIG_SCRIPTS</code> is the file name(s)
- of the shell script(s) needing fixing. All these names are relative to
- <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
- from <code class="literal">$(TARGET_DIR)/usr/bin</code>, since they are not needed on the target.</p><div class="example"><a id="idm3189"></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="idm3196"></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:
- <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 = \
- Magick-config Magick++-config \
- 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
- on. These dependencies are listed in terms of lower-case package names,
- which can be packages for the target (without the <code class="literal">host-</code>
- prefix) or packages for the host (with the <code class="literal">host-</code>) prefix).
- Buildroot will ensure that all these packages are built and installed
- <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
- at the different steps of the package configuration, compilation and
- installation.
- <code class="literal">LIBFOO_BUILD_CMDS</code> tells what steps should be performed to
- build the package. <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code> tells what
- steps should be performed to install the package in the staging space.
- <code class="literal">LIBFOO_INSTALL_TARGET_CMDS</code> tells what steps should be
- performed to install the package in the target space.</p><p>All these steps rely on the <code class="literal">$(@D)</code> variable, which
- contains the directory where the source code of the package has been
- extracted.</p><p>On lines 31..33, we define a user that is used by this package (e.g.
- 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
- (<code class="literal">LIBFOO_DEVICES</code>).</p><p>On line 39..41, we define the permissions to set to specific files
- 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
- generates, according to the variables defined previously, all the
- 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
- used for packages to be cross-compiled for the target. The
- <code class="literal">host-generic-package</code> macro is used for host packages, natively compiled
- for the host. It is possible to call both of them in a single <code class="literal">.mk</code>
- file: once to create the rules to generate a target
- package and once to create the rules to generate a host package:</p><pre class="screen">$(eval $(generic-package))
- $(eval $(host-generic-package))</pre><p>This might be useful if the compilation of the target package requires
- some tools to be installed on the host. If the package name is
- <code class="literal">libfoo</code>, then the name of the package for the target is also
- <code class="literal">libfoo</code>, while the name of the package for the host is
- <code class="literal">host-libfoo</code>. These names should be used in the DEPENDENCIES
- variables of other packages, if they depend on <code class="literal">libfoo</code> or
- <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
- <span class="strong"><strong>must</strong></span> be at the end of the <code class="literal">.mk</code> file, after all variable definitions.
- The call to <code class="literal">host-generic-package</code> <span class="strong"><strong>must</strong></span> be after the call to
- <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
- the .mk file and prefixed by the uppercased package name:
- <code class="literal">LIBFOO_*</code>. <code class="literal">host-generic-package</code> uses the <code class="literal">HOST_LIBFOO_*</code> variables. For
- <span class="emphasis"><em>some</em></span> variables, if the <code class="literal">HOST_LIBFOO_</code> prefixed variable doesn’t
- exist, the package infrastructure uses the corresponding variable
- prefixed by <code class="literal">LIBFOO_</code>. This is done for variables that are likely to
- have the same value for both the target and host packages. See below
- for details.</p><p>The list of variables that can be set in a <code class="literal">.mk</code> file to give metadata
- 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">
- <code class="literal">LIBFOO_VERSION</code>, mandatory, must contain the version of the
- package. Note that if <code class="literal">HOST_LIBFOO_VERSION</code> doesn’t exist, it is
- assumed to be the same as <code class="literal">LIBFOO_VERSION</code>. It can also be a
- revision number or a tag for packages that are fetched directly
- from their version control system. Examples:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- a version for a release tarball: <code class="literal">LIBFOO_VERSION = 0.1.2</code>
- </li><li class="listitem">
- a sha1 for a git tree: <code class="literal">LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057</code>
- </li><li class="listitem"><p class="simpara">
- a tag for a git tree <code class="literal">LIBFOO_VERSION = v0.1.2</code>
- </p><p><strong>Note: </strong>Using a branch name as <code class="literal">FOO_VERSION</code> is not supported, because it does
- not and can not work as people would expect it should:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
- due to local caching, Buildroot will not re-fetch the repository,
- so people who expect to be able to follow the remote repository
- would be quite surprised and disappointed;
- </li><li class="listitem">
- because two builds can never be perfectly simultaneous, and because
- the remote repository may get new commits on the branch anytime,
- two users, using the same Buildroot tree and building the same
- configuration, may get different source, thus rendering the build
- non reproducible, and people would be quite surprised and
- disappointed.
- </li></ol></div></li></ul></div></li><li class="listitem">
- <code class="literal">LIBFOO_SOURCE</code> may contain the name of the tarball of the package,
- which Buildroot will use to download the tarball from
- <code class="literal">LIBFOO_SITE</code>. If <code class="literal">HOST_LIBFOO_SOURCE</code> is not specified, it defaults
- to <code class="literal">LIBFOO_SOURCE</code>. If none are specified, then the value is assumed
- to be <code class="literal">libfoo-$(LIBFOO_VERSION).tar.gz</code>.
- Example: <code class="literal">LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_PATCH</code> may contain a space-separated list of patch file
- names, that Buildroot will download and apply to the package source
- code. If an entry contains <code class="literal">://</code>, then Buildroot will assume it is a
- full URL and download the patch from this location. Otherwise,
- Buildroot will assume that the patch should be downloaded from
- <code class="literal">LIBFOO_SITE</code>. If <code class="literal">HOST_LIBFOO_PATCH</code> is not specified, it defaults
- to <code class="literal">LIBFOO_PATCH</code>. Note that patches that are included in Buildroot
- itself use a different mechanism: all files of the form
- <code class="literal">*.patch</code> present in the package directory inside
- Buildroot will be applied to the package after extraction (see
- <a class="link" href="#patch-policy" title="Chapter 19. Patching a package">patching a package</a>). Finally, patches listed in
- the <code class="literal">LIBFOO_PATCH</code> variable are applied <span class="emphasis"><em>before</em></span> the patches stored
- in the Buildroot package directory.
- </li><li class="listitem">
- <code class="literal">LIBFOO_SITE</code> provides the location of the package, which can be a
- URL or a local filesystem path. HTTP, FTP and SCP are supported URL
- types for retrieving package tarballs. In these cases don’t include a
- trailing slash: it will be added by Buildroot between the directory
- and the filename as appropriate. Git, Subversion, Mercurial,
- and Bazaar are supported URL types for retrieving packages directly
- from source code management systems. There is a helper function to make
- it easier to download source tarballs from GitHub (refer to
- <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
- to specify either a tarball or a directory containing the package
- source code. See <code class="literal">LIBFOO_SITE_METHOD</code> below for more details on how
- retrieval works.
- Note that SCP URLs should be of the form
- <code class="literal">scp://[user@]host:filepath</code>, and that filepath is relative to the
- user’s home directory, so you may want to prepend the path with a
- slash for absolute paths:
- <code class="literal">scp://[user@]host:/absolutepath</code>.
- If <code class="literal">HOST_LIBFOO_SITE</code> is not specified, it defaults to
- <code class="literal">LIBFOO_SITE</code>.
- Examples:
- <code class="literal">LIBFOO_SITE=http://www.libfoosoftware.org/libfoo</code>
- <code class="literal">LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor</code>
- <code class="literal">LIBFOO_SITE=/opt/software/libfoo.tar.gz</code>
- <code class="literal">LIBFOO_SITE=$(TOPDIR)/../src/libfoo</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_DL_OPTS</code> is a space-separated list of additional options to
- pass to the downloader. Useful for retrieving documents with
- server-side checking for user logins and passwords, or to use a proxy.
- All download methods valid for <code class="literal">LIBFOO_SITE_METHOD</code> are supported;
- valid options depend on the download method (consult the man page
- for the respective download utilities).
- </li><li class="listitem">
- <code class="literal">LIBFOO_EXTRA_DOWNLOADS</code> is a space-separated list of additional
- files that Buildroot should download. If an entry contains <code class="literal">://</code>
- then Buildroot will assume it is a complete URL and will download
- the file using this URL. Otherwise, Buildroot will assume the file
- to be downloaded is located at <code class="literal">LIBFOO_SITE</code>. Buildroot will not do
- anything with those additional files, except download them: it will
- be up to the package recipe to use them from <code class="literal">$(LIBFOO_DL_DIR)</code>.
- </li><li class="listitem"><p class="simpara">
- <code class="literal">LIBFOO_SITE_METHOD</code> determines the method used to fetch or copy the
- package source code. In many cases, Buildroot guesses the method
- from the contents of <code class="literal">LIBFOO_SITE</code> and setting <code class="literal">LIBFOO_SITE_METHOD</code>
- is unnecessary. When <code class="literal">HOST_LIBFOO_SITE_METHOD</code> is not specified, it
- defaults to the value of <code class="literal">LIBFOO_SITE_METHOD</code>.
- The possible values of <code class="literal">LIBFOO_SITE_METHOD</code> are:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <code class="literal">wget</code> for normal FTP/HTTP downloads of tarballs. Used by
- default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">http://</code>, <code class="literal">https://</code> or
- <code class="literal">ftp://</code>.
- </li><li class="listitem">
- <code class="literal">scp</code> for downloads of tarballs over SSH with scp. Used by
- default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">scp://</code>.
- </li><li class="listitem">
- <code class="literal">svn</code> for retrieving source code from a Subversion repository.
- Used by default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">svn://</code>. When a
- <code class="literal">http://</code> Subversion repository URL is specified in
- <code class="literal">LIBFOO_SITE</code>, one <span class="emphasis"><em>must</em></span> specify <code class="literal">LIBFOO_SITE_METHOD=svn</code>.
- Buildroot performs a checkout which is preserved as a tarball in
- the download cache; subsequent builds use the tarball instead of
- performing another checkout.
- </li><li class="listitem">
- <code class="literal">cvs</code> for retrieving source code from a CVS repository.
- Used by default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">cvs://</code>.
- The downloaded source code is cached as with the <code class="literal">svn</code> method.
- Anonymous pserver mode is assumed otherwise explicitly defined
- on <code class="literal">LIBFOO_SITE</code>. Both
- <code class="literal">LIBFOO_SITE=cvs://libfoo.net:/cvsroot/libfoo</code> and
- <code class="literal">LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo</code>
- are accepted, on the former anonymous pserver access mode is
- assumed.
- <code class="literal">LIBFOO_SITE</code> <span class="emphasis"><em>must</em></span> contain the source URL as well as the remote
- repository directory. The module is the package name.
- <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
- a date (e.g. "2014-10-20", "2014-10-20 13:45", "2014-10-20
- 13:45+01" see "man cvs" for further details).
- </li><li class="listitem">
- <code class="literal">git</code> for retrieving source code from a Git repository. Used by
- default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">git://</code>. The downloaded
- source code is cached as with the <code class="literal">svn</code>
- method.
- </li><li class="listitem">
- <code class="literal">hg</code> for retrieving source code from a Mercurial repository. One
- <span class="emphasis"><em>must</em></span> specify <code class="literal">LIBFOO_SITE_METHOD=hg</code> when <code class="literal">LIBFOO_SITE</code>
- contains a Mercurial repository URL. The downloaded source code
- is cached as with the <code class="literal">svn</code> method.
- </li><li class="listitem">
- <code class="literal">bzr</code> for retrieving source code from a Bazaar repository. Used
- by default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">bzr://</code>. The
- downloaded source code is cached as with the <code class="literal">svn</code> method.
- </li><li class="listitem">
- <code class="literal">file</code> for a local tarball. One should use this when
- <code class="literal">LIBFOO_SITE</code> specifies a package tarball as a local filename.
- Useful for software that isn’t available publicly or in version
- control.
- </li><li class="listitem">
- <code class="literal">local</code> for a local source code directory. One should use this
- when <code class="literal">LIBFOO_SITE</code> specifies a local directory path containing
- the package source code. Buildroot copies the contents of the
- source directory into the package’s build directory. Note that
- for <code class="literal">local</code> packages, no patches are applied. If you need to
- still patch the source code, use <code class="literal">LIBFOO_POST_RSYNC_HOOKS</code>, see
- <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>.
- </li></ul></div></li><li class="listitem">
- <code class="literal">LIBFOO_GIT_SUBMODULES</code> can be set to <code class="literal">YES</code> to create an archive
- with the git submodules in the repository. This is only available
- for packages downloaded with git (i.e. when
- <code class="literal">LIBFOO_SITE_METHOD=git</code>). Note that we try not to use such git
- submodules when they contain bundled libraries, in which case we
- prefer to use those libraries from their own package.
- </li><li class="listitem">
- <code class="literal">LIBFOO_STRIP_COMPONENTS</code> is the number of leading components
- (directories) that tar must strip from file names on extraction.
- The tarball for most packages has one leading component named
- "<pkg-name>-<pkg-version>", thus Buildroot passes
- --strip-components=1 to tar to remove it.
- For non-standard packages that don’t have this component, or
- that have more than one leading component to strip, set this
- variable with the value to be passed to tar. Default: 1.
- </li><li class="listitem">
- <code class="literal">LIBFOO_EXCLUDES</code> is a space-separated list of patterns to exclude
- when extracting the archive. Each item from that list is passed as
- a tar’s <code class="literal">--exclude</code> option. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_DEPENDENCIES</code> lists the dependencies (in terms of package
- name) that are required for the current target package to
- compile. These dependencies are guaranteed to be compiled and
- installed before the configuration of the current package starts.
- However, modifications to configuration of these dependencies will
- not force a rebuild of the current package. In a similar way,
- <code class="literal">HOST_LIBFOO_DEPENDENCIES</code> lists the dependencies for the current
- host package.
- </li><li class="listitem">
- <code class="literal">LIBFOO_EXTRACT_DEPENDENCIES</code> lists the dependencies (in terms of
- package name) that are required for the current target package to be
- extracted. These dependencies are guaranteed to be compiled and
- installed before the extract step of the current package
- starts. This is only used internally by the package infrastructure,
- and should typically not be used directly by packages.
- </li><li class="listitem">
- <code class="literal">LIBFOO_PATCH_DEPENDENCIES</code> lists the dependencies (in terms of
- package name) that are required for the current package to be
- patched. These dependencies are guaranteed to be extracted and
- patched (but not necessarily built) before the current package is
- patched. In a similar way, <code class="literal">HOST_LIBFOO_PATCH_DEPENDENCIES</code> lists
- the dependencies for the current host package.
- This is seldom used; usually, <code class="literal">LIBFOO_DEPENDENCIES</code> is what you
- really want to use.
- </li><li class="listitem">
- <code class="literal">LIBFOO_PROVIDES</code> lists all the virtual packages <code class="literal">libfoo</code> is an
- implementation of. See <a class="xref" href="#virtual-package-tutorial">Section 18.11, “Infrastructure for virtual packages”</a>.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_STAGING</code> can be set to <code class="literal">YES</code> or <code class="literal">NO</code> (default). If
- set to <code class="literal">YES</code>, then the commands in the <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code>
- variables are executed to install the package into the staging
- directory.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_TARGET</code> can be set to <code class="literal">YES</code> (default) or <code class="literal">NO</code>. If
- set to <code class="literal">YES</code>, then the commands in the <code class="literal">LIBFOO_INSTALL_TARGET_CMDS</code>
- variables are executed to install the package into the target
- directory.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_IMAGES</code> can be set to <code class="literal">YES</code> or <code class="literal">NO</code> (default). If
- set to <code class="literal">YES</code>, then the commands in the <code class="literal">LIBFOO_INSTALL_IMAGES_CMDS</code>
- variable are executed to install the package into the images
- directory.
- </li><li class="listitem">
- <code class="literal">LIBFOO_CONFIG_SCRIPTS</code> lists the names of the files in
- <span class="emphasis"><em>$(STAGING_DIR)/usr/bin</em></span> that need some special fixing to make them
- cross-compiling friendly. Multiple file names separated by space can
- be given and all are relative to <span class="emphasis"><em>$(STAGING_DIR)/usr/bin</em></span>. The files
- listed in <code class="literal">LIBFOO_CONFIG_SCRIPTS</code> are also removed from
- <code class="literal">$(TARGET_DIR)/usr/bin</code> since they are not needed on the target.
- </li><li class="listitem">
- <code class="literal">LIBFOO_DEVICES</code> lists the device files to be created by Buildroot
- when using the static device table. The syntax to use is the
- makedevs one. 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>. This variable is optional.
- </li><li class="listitem">
- <code class="literal">LIBFOO_PERMISSIONS</code> lists the changes of permissions to be done at
- the end of the build process. The syntax is once again the makedevs one.
- 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>.
- This variable is optional.
- </li><li class="listitem">
- <code class="literal">LIBFOO_USERS</code> lists the users to create for this package, if it installs
- a program you want to run as a specific user (e.g. as a daemon, or as a
- cron-job). The syntax is similar in spirit to the makedevs one, and is
- 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.
- </li><li class="listitem"><p class="simpara">
- <code class="literal">LIBFOO_LICENSE</code> defines the license (or licenses) under which the package
- is released.
- This name will appear in the manifest file produced by <code class="literal">make legal-info</code>.
- If the license appears in <a class="ulink" href="https://spdx.org/licenses/" target="_top">the SPDX License List</a>,
- use the SPDX short identifier to make the manifest file uniform.
- Otherwise, describe the license in a precise and concise way, avoiding
- ambiguous names such as <code class="literal">BSD</code> which actually name a family of licenses.
- This variable is optional. If it is not defined, <code class="literal">unknown</code> will appear in
- the <code class="literal">license</code> field of the manifest file for this package.
- The expected format for this variable must comply with the following rules:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- If different parts of the package are released under different
- licenses, then <code class="literal">comma</code> separate licenses (e.g. <code class="literal"><code class="literal">LIBFOO_LICENSE =
- GPL-2.0+, LGPL-2.1+</code></code>). If there is clear distinction between which
- component is licensed under what license, then annotate the license
- with that component, between parenthesis (e.g. <code class="literal"><code class="literal">LIBFOO_LICENSE =
- GPL-2.0+ (programs), LGPL-2.1+ (libraries)</code></code>).
- </li><li class="listitem">
- If some licenses are conditioned on a sub-option being enabled, append
- the conditional licenses with a comma (e.g.: <code class="literal">FOO_LICENSE += , GPL-2.0+
- (programs)</code>); the infrastructure will internally remove the space before
- the comma.
- </li><li class="listitem">
- If the package is dual licensed, then separate licenses with the
- <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>).
- </li></ul></div></li><li class="listitem">
- <code class="literal">LIBFOO_LICENSE_FILES</code> is a space-separated list of files in the package
- tarball that contain the license(s) under which the package is released.
- <code class="literal">make legal-info</code> copies all of these files in the <code class="literal">legal-info</code> directory.
- 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.
- This variable is optional. If it is not defined, a warning will be produced
- to let you know, and <code class="literal">not saved</code> will appear in the <code class="literal">license files</code> field
- of the manifest file for this package.
- </li><li class="listitem">
- <code class="literal">LIBFOO_ACTUAL_SOURCE_TARBALL</code> only applies to packages whose
- <code class="literal">LIBFOO_SITE</code> / <code class="literal">LIBFOO_SOURCE</code> pair points to an archive that does
- not actually contain source code, but binary code. This a very
- uncommon case, only known to apply to external toolchains which come
- already compiled, although theoretically it might apply to other
- packages. In such cases a separate tarball is usually available with
- the actual source code. Set <code class="literal">LIBFOO_ACTUAL_SOURCE_TARBALL</code> to the
- name of the actual source code archive and Buildroot will download
- it and use it when you run <code class="literal">make legal-info</code> to collect
- legally-relevant material. Note this file will not be downloaded
- during regular builds nor by <code class="literal">make source</code>.
- </li><li class="listitem">
- <code class="literal">LIBFOO_ACTUAL_SOURCE_SITE</code> provides the location of the actual
- source tarball. The default value is <code class="literal">LIBFOO_SITE</code>, so you don’t
- need to set this variable if the binary and source archives are
- hosted on the same directory. If <code class="literal">LIBFOO_ACTUAL_SOURCE_TARBALL</code> is
- not set, it doesn’t make sense to define
- <code class="literal">LIBFOO_ACTUAL_SOURCE_SITE</code>.
- </li><li class="listitem">
- <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
- the package source code is allowed to be redistributed. Set it to <code class="literal">NO</code> for
- non-opensource packages: Buildroot will not save the source code for this
- package when collecting the <code class="literal">legal-info</code>.
- </li><li class="listitem">
- <code class="literal">LIBFOO_FLAT_STACKSIZE</code> defines the stack size of an application built into
- the FLAT binary format. The application stack size on the NOMMU architecture
- processors can’t be enlarged at run time. The default stack size for the
- FLAT binary format is only 4k bytes. If the application consumes more stack,
- append the required number here.
- </li><li class="listitem">
- <code class="literal">LIBFOO_BIN_ARCH_EXCLUDE</code> is a space-separated list of paths (relative
- to the target directory) to ignore when checking that the package
- installs correctly cross-compiled binaries. You seldom need to set this
- variable, unless the package installs binary blobs outside the default
- locations, <code class="literal">/lib/firmware</code>, <code class="literal">/usr/lib/firmware</code>, <code class="literal">/lib/modules</code>,
- <code class="literal">/usr/lib/modules</code>, and <code class="literal">/usr/share</code>, which are automatically excluded.
- </li><li class="listitem">
- <code class="literal">LIBFOO_IGNORE_CVES</code> is a space-separated list of CVEs that tells
- Buildroot CVE tracking tools which CVEs should be ignored for this
- package. This is typically used when the CVE is fixed by a patch in
- the package, or when the CVE for some reason does not affect the
- Buildroot package. A Makefile comment must always precede the
- addition of a CVE to this variable. Example:
- </li></ul></div><pre class="screen"># 0001-fix-cve-2020-12345.patch
- LIBFOO_IGNORE_CVES += CVE-2020-12345
- # only when built with libbaz, which Buildroot doesn't support
- LIBFOO_IGNORE_CVES += CVE-2020-54321</pre><p>The recommended way to define these variables is to use the following
- syntax:</p><pre class="screen">LIBFOO_VERSION = 2.32</pre><p>Now, the variables that define what should be performed at the
- different steps of the build process.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">LIBFOO_EXTRACT_CMDS</code> lists the actions to be performed to extract
- the package. This is generally not needed as tarballs are
- automatically handled by Buildroot. However, if the package uses a
- non-standard archive format, such as a ZIP or RAR file, or has a
- tarball with a non-standard organization, this variable allows to
- override the package infrastructure default behavior.
- </li><li class="listitem">
- <code class="literal">LIBFOO_CONFIGURE_CMDS</code> lists the actions to be performed to
- configure the package before its compilation.
- </li><li class="listitem">
- <code class="literal">LIBFOO_BUILD_CMDS</code> lists the actions to be performed to
- compile the package.
- </li><li class="listitem">
- <code class="literal">HOST_LIBFOO_INSTALL_CMDS</code> lists the actions to be performed
- to install the package, when the package is a host package. The
- package must install its files to the directory given by
- <code class="literal">$(HOST_DIR)</code>. All files, including development files such as
- headers should be installed, since other packages might be compiled
- on top of this package.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_TARGET_CMDS</code> lists the actions to be
- performed to install the package to the target directory, when the
- package is a target package. The package must install its files to
- the directory given by <code class="literal">$(TARGET_DIR)</code>. Only the files required for
- <span class="emphasis"><em>execution</em></span> of the package have to be
- installed. Header files, static libraries and documentation will be
- removed again when the target filesystem is finalized.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code> lists the actions to be
- performed to install the package to the staging directory, when the
- package is a target package. The package must install its files to
- the directory given by <code class="literal">$(STAGING_DIR)</code>. All development files
- should be installed, since they might be needed to compile other
- packages.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_IMAGES_CMDS</code> lists the actions to be performed to
- install the package to the images directory, when the package is a
- target package. The package must install its files to the directory
- given by <code class="literal">$(BINARIES_DIR)</code>. Only files that are binary images (aka
- images) that do not belong in the <code class="literal">TARGET_DIR</code> but are necessary
- for booting the board should be placed here. For example, a package
- should utilize this step if it has binaries which would be similar
- to the kernel image, bootloader or root filesystem images.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_INIT_SYSV</code>, <code class="literal">LIBFOO_INSTALL_INIT_OPENRC</code> and
- <code class="literal">LIBFOO_INSTALL_INIT_SYSTEMD</code> list the actions to install init
- scripts either for the systemV-like init systems (busybox,
- sysvinit, etc.), openrc or for the systemd units. These commands
- will be run only when the relevant init system is installed (i.e.
- if systemd is selected as the init system in the configuration,
- only <code class="literal">LIBFOO_INSTALL_INIT_SYSTEMD</code> will be run). The only exception
- is when openrc is chosen as init system and <code class="literal">LIBFOO_INSTALL_INIT_OPENRC</code>
- has not been set, in such situation <code class="literal">LIBFOO_INSTALL_INIT_SYSV</code> will
- be called, since openrc supports sysv init scripts.
- When systemd is used as the init system, buildroot will automatically enable
- all services using the <code class="literal">systemctl preset-all</code> command in the final phase of
- image building. You can add preset files to prevent a particular unit from
- being automatically enabled by buildroot.
- </li><li class="listitem">
- <code class="literal">LIBFOO_HELP_CMDS</code> lists the actions to print the package help, which
- is included to the main <code class="literal">make help</code> output. These commands can print
- anything in any format.
- This is seldom used, as packages rarely have custom rules. <span class="strong"><strong>Do not use
- this variable</strong></span>, unless you really know that you need to print help.
- </li><li class="listitem">
- <code class="literal">LIBFOO_LINUX_CONFIG_FIXUPS</code> lists the Linux kernel configuration
- options that are needed to build and use this package, and without
- which the package is fundamentally broken. This shall be a set of
- calls to one of the kconfig tweaking option: <code class="literal">KCONFIG_ENABLE_OPT</code>,
- <code class="literal">KCONFIG_DISABLE_OPT</code>, or <code class="literal">KCONFIG_SET_OPT</code>.
- This is seldom used, as package usually have no strict requirements on
- the kernel options.
- </li></ul></div><p>The preferred way to define these variables is:</p><pre class="screen">define LIBFOO_CONFIGURE_CMDS
- action 1
- action 2
- action 3
- 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">
- <code class="literal">$(LIBFOO_PKGDIR)</code> contains the path to the directory containing the
- <code class="literal">libfoo.mk</code> and <code class="literal">Config.in</code> files. This variable is useful when it is
- necessary to install a file bundled in Buildroot, like a runtime
- configuration file, a splashscreen image…
- </li><li class="listitem">
- <code class="literal">$(@D)</code>, which contains the directory in which the package source
- code has been uncompressed.
- </li><li class="listitem">
- <code class="literal">$(LIBFOO_DL_DIR)</code> contains the path to the directory where all the downloads
- made by Buildroot for <code class="literal">libfoo</code> are stored in.
- </li><li class="listitem">
- <code class="literal">$(TARGET_CC)</code>, <code class="literal">$(TARGET_LD)</code>, etc. to get the target
- cross-compilation utilities
- </li><li class="listitem">
- <code class="literal">$(TARGET_CROSS)</code> to get the cross-compilation toolchain prefix
- </li><li class="listitem">
- Of course the <code class="literal">$(HOST_DIR)</code>, <code class="literal">$(STAGING_DIR)</code> and <code class="literal">$(TARGET_DIR)</code>
- variables to install the packages properly. Those variables point to
- 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
- <span class="emphasis"><em>per-package directory</em></span> support is used, in which case they point to
- 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
- both cases, it doesn’t make any difference from the package point of
- view: it should simply use <code class="literal">HOST_DIR</code>, <code class="literal">STAGING_DIR</code> and
- <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
- about <span class="emphasis"><em>per-package directory</em></span> support.
- </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
- package, with an example :</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # libfoo
- 04: #
- 05: ################################################################################
- 06:
- 07: LIBFOO_VERSION = 1.0
- 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
- 09: LIBFOO_SITE = http://www.foosoftware.org/download
- 10: LIBFOO_INSTALL_STAGING = YES
- 11: LIBFOO_INSTALL_TARGET = NO
- 12: LIBFOO_CONF_OPTS = --disable-shared
- 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
- 14:
- 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)
- and the location of the tarball on the Web. Buildroot will automatically
- download the tarball from this location.</p><p>On line 10, we tell Buildroot to install the package to the staging
- directory. The staging directory, located in <code class="literal">output/staging/</code>
- is the directory where all the packages are installed, including their
- development files, etc. By default, packages are not installed to the
- staging directory, since usually, only libraries need to be installed in
- the staging directory: their development files are needed to compile
- other libraries or applications depending on them. Also by default, when
- staging installation is enabled, packages are installed in this location
- using the <code class="literal">make install</code> command.</p><p>On line 11, we tell Buildroot to not install the package to the
- target directory. This directory contains what will become the root
- filesystem running on the target. For purely static libraries, it is
- not necessary to install them in the target directory because they will
- not be used at runtime. By default, target installation is enabled; setting
- this variable to NO is almost never needed. Also by default, packages are
- 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
- will be passed to the <code class="literal">./configure</code> script before configuring
- and building the package.</p><p>On line 13, we declare our dependencies, so that they are built
- before the build process of our package starts.</p><p>Finally, on line line 15, we invoke the <code class="literal">autotools-package</code>
- macro that generates all the Makefile rules that actually allows the
- 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
- <code class="literal">autotools-package</code>. It is similar to the <code class="literal">generic-package</code> macro. The ability to
- have target and host packages is also available, with the
- <code class="literal">host-autotools-package</code> macro.</p><p>Just like the generic infrastructure, the autotools infrastructure
- works by defining a number of variables before calling the
- <code class="literal">autotools-package</code> macro.</p><p>First, all the package metadata information variables that exist in the
- generic infrastructure also exist in the autotools infrastructure:
- <code class="literal">LIBFOO_VERSION</code>, <code class="literal">LIBFOO_SOURCE</code>,
- <code class="literal">LIBFOO_PATCH</code>, <code class="literal">LIBFOO_SITE</code>,
- <code class="literal">LIBFOO_SUBDIR</code>, <code class="literal">LIBFOO_DEPENDENCIES</code>,
- <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,
- can also be defined. Many of them are only useful in very specific
- 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">
- <code class="literal">LIBFOO_SUBDIR</code> may contain the name of a subdirectory
- inside the package that contains the configure script. This is useful,
- if for example, the main configure script is not at the root of the
- tree extracted by the tarball. If <code class="literal">HOST_LIBFOO_SUBDIR</code> is
- not specified, it defaults to <code class="literal">LIBFOO_SUBDIR</code>.
- </li><li class="listitem">
- <code class="literal">LIBFOO_CONF_ENV</code>, to specify additional environment
- variables to pass to the configure script. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_CONF_OPTS</code>, to specify additional configure
- options to pass to the configure script. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_MAKE</code>, to specify an alternate <code class="literal">make</code>
- command. This is typically useful when parallel make is enabled in
- the configuration (using <code class="literal">BR2_JLEVEL</code>) but that this
- feature should be disabled for the given package, for one reason or
- another. By default, set to <code class="literal">$(MAKE)</code>. If parallel building
- is not supported by the package, then it should be set to
- <code class="literal">LIBFOO_MAKE=$(MAKE1)</code>.
- </li><li class="listitem">
- <code class="literal">LIBFOO_MAKE_ENV</code>, to specify additional environment
- variables to pass to make in the build step. These are passed before
- the <code class="literal">make</code> command. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_MAKE_OPTS</code>, to specify additional variables to
- pass to make in the build step. These are passed after the
- <code class="literal">make</code> command. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_AUTORECONF</code>, tells whether the package should
- be autoreconfigured or not (i.e. if the configure script and
- Makefile.in files should be re-generated by re-running autoconf,
- automake, libtool, etc.). Valid values are <code class="literal">YES</code> and
- <code class="literal">NO</code>. By default, the value is <code class="literal">NO</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_AUTORECONF_ENV</code>, to specify additional environment
- variables to pass to the <span class="emphasis"><em>autoreconf</em></span> program if
- <code class="literal">LIBFOO_AUTORECONF=YES</code>. These are passed in the environment of
- the <span class="emphasis"><em>autoreconf</em></span> command. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_AUTORECONF_OPTS</code> to specify additional options
- passed to the <span class="emphasis"><em>autoreconf</em></span> program if
- <code class="literal">LIBFOO_AUTORECONF=YES</code>. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_GETTEXTIZE</code>, tells whether the package should be
- gettextized or not (i.e. if the package uses a different gettext
- version than Buildroot provides, and it is needed to run
- <span class="emphasis"><em>gettextize</em></span>.) Only valid when <code class="literal">LIBFOO_AUTORECONF=YES</code>. Valid
- values are <code class="literal">YES</code> and <code class="literal">NO</code>. The default is <code class="literal">NO</code>.
- </li><li class="listitem">
- <code class="literal">LIBFOO_GETTEXTIZE_OPTS</code>, to specify additional options passed to
- the <span class="emphasis"><em>gettextize</em></span> program, if <code class="literal">LIBFOO_GETTEXTIZE=YES</code>. You may
- use that if, for example, the <code class="literal">.po</code> files are not located in the
- standard place (i.e. in <code class="literal">po/</code> at the root of the package.) By
- default, <span class="emphasis"><em>-f</em></span>.
- </li><li class="listitem">
- <code class="literal">LIBFOO_LIBTOOL_PATCH</code> tells whether the Buildroot
- patch to fix libtool cross-compilation issues should be applied or
- not. Valid values are <code class="literal">YES</code> and <code class="literal">NO</code>. By
- default, the value is <code class="literal">YES</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_STAGING_OPTS</code> contains the make options
- used to install the package to the staging directory. By default, the
- value is <code class="literal">DESTDIR=$(STAGING_DIR) install</code>, which is
- correct for most autotools packages. It is still possible to override
- it.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_TARGET_OPTS</code> contains the make options
- used to install the package to the target directory. By default, the
- value is <code class="literal">DESTDIR=$(TARGET_DIR) install</code>. The default
- value is correct for most autotools packages, but it is still possible
- to override it if needed.
- </li></ul></div><p>With the autotools infrastructure, all the steps required to build
- and install the packages are already defined, and they generally work
- well for most autotools-based packages. However, when required, it is
- 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">
- By adding a post-operation hook (after extract, patch, configure,
- 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.
- </li><li class="listitem">
- By overriding one of the steps. For example, even if the autotools
- infrastructure is used, if the package <code class="literal">.mk</code> file defines its
- own <code class="literal">LIBFOO_CONFIGURE_CMDS</code> variable, it will be used
- instead of the default autotools one. However, using this method
- should be restricted to very specific cases. Do not use it in the
- general case.
- </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,
- with an example :</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # libfoo
- 04: #
- 05: ################################################################################
- 06:
- 07: LIBFOO_VERSION = 1.0
- 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
- 09: LIBFOO_SITE = http://www.foosoftware.org/download
- 10: LIBFOO_INSTALL_STAGING = YES
- 11: LIBFOO_INSTALL_TARGET = NO
- 12: LIBFOO_CONF_OPTS = -DBUILD_DEMOS=ON
- 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
- 14:
- 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)
- and the location of the tarball on the Web. Buildroot will automatically
- download the tarball from this location.</p><p>On line 10, we tell Buildroot to install the package to the staging
- directory. The staging directory, located in <code class="literal">output/staging/</code>
- is the directory where all the packages are installed, including their
- development files, etc. By default, packages are not installed to the
- staging directory, since usually, only libraries need to be installed in
- the staging directory: their development files are needed to compile
- other libraries or applications depending on them. Also by default, when
- staging installation is enabled, packages are installed in this location
- using the <code class="literal">make install</code> command.</p><p>On line 11, we tell Buildroot to not install the package to the
- target directory. This directory contains what will become the root
- filesystem running on the target. For purely static libraries, it is
- not necessary to install them in the target directory because they will
- not be used at runtime. By default, target installation is enabled; setting
- this variable to NO is almost never needed. Also by default, packages are
- 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
- configuring the package.</p><p>On line 13, we declare our dependencies, so that they are built
- before the build process of our package starts.</p><p>Finally, on line line 15, we invoke the <code class="literal">cmake-package</code>
- macro that generates all the Makefile rules that actually allows the
- 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
- <code class="literal">cmake-package</code>. It is similar to the <code class="literal">generic-package</code> macro. The ability to
- have target and host packages is also available, with the
- <code class="literal">host-cmake-package</code> macro.</p><p>Just like the generic infrastructure, the CMake infrastructure works
- by defining a number of variables before calling the <code class="literal">cmake-package</code>
- macro.</p><p>First, all the package metadata information variables that exist in
- the generic infrastructure also exist in the CMake infrastructure:
- <code class="literal">LIBFOO_VERSION</code>, <code class="literal">LIBFOO_SOURCE</code>, <code class="literal">LIBFOO_PATCH</code>, <code class="literal">LIBFOO_SITE</code>,
- <code class="literal">LIBFOO_SUBDIR</code>, <code class="literal">LIBFOO_DEPENDENCIES</code>, <code class="literal">LIBFOO_INSTALL_STAGING</code>,
- <code class="literal">LIBFOO_INSTALL_TARGET</code>.</p><p>A few additional variables, specific to the CMake infrastructure, can
- also be defined. Many of them are only useful in very specific 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">
- <code class="literal">LIBFOO_SUBDIR</code> may contain the name of a subdirectory inside the
- package that contains the main CMakeLists.txt file. This is useful,
- if for example, the main CMakeLists.txt file is not at the root of
- the tree extracted by the tarball. If <code class="literal">HOST_LIBFOO_SUBDIR</code> is not
- specified, it defaults to <code class="literal">LIBFOO_SUBDIR</code>.
- </li><li class="listitem">
- <code class="literal">LIBFOO_CONF_ENV</code>, to specify additional environment variables to
- pass to CMake. By default, empty.
- </li><li class="listitem"><p class="simpara">
- <code class="literal">LIBFOO_CONF_OPTS</code>, to specify additional configure options to pass
- to CMake. By default, empty. A number of common CMake options are
- set by the <code class="literal">cmake-package</code> infrastructure; so it is normally not
- necessary to set them in the package’s <code class="literal">*.mk</code> file unless you want
- to override them:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <code class="literal">CMAKE_BUILD_TYPE</code> is driven by <code class="literal">BR2_ENABLE_DEBUG</code>;
- </li><li class="listitem">
- <code class="literal">CMAKE_INSTALL_PREFIX</code>;
- </li><li class="listitem">
- <code class="literal">BUILD_SHARED_LIBS</code> is driven by <code class="literal">BR2_STATIC_LIBS</code>;
- </li><li class="listitem">
- <code class="literal">BUILD_DOC</code>, <code class="literal">BUILD_DOCS</code> are disabled;
- </li><li class="listitem">
- <code class="literal">BUILD_EXAMPLE</code>, <code class="literal">BUILD_EXAMPLES</code> are disabled;
- </li><li class="listitem">
- <code class="literal">BUILD_TEST</code>, <code class="literal">BUILD_TESTS</code>, <code class="literal">BUILD_TESTING</code> are disabled.
- </li></ul></div></li><li class="listitem">
- <code class="literal">LIBFOO_SUPPORTS_IN_SOURCE_BUILD = NO</code> should be set when the package
- cannot be built inside the source tree but needs a separate build
- directory.
- </li><li class="listitem">
- <code class="literal">LIBFOO_MAKE</code>, to specify an alternate <code class="literal">make</code> command. This is
- typically useful when parallel make is enabled in the configuration
- (using <code class="literal">BR2_JLEVEL</code>) but that this feature should be disabled for
- the given package, for one reason or another. By default, set to
- <code class="literal">$(MAKE)</code>. If parallel building is not supported by the package,
- then it should be set to <code class="literal">LIBFOO_MAKE=$(MAKE1)</code>.
- </li><li class="listitem">
- <code class="literal">LIBFOO_MAKE_ENV</code>, to specify additional environment variables to
- pass to make in the build step. These are passed before the <code class="literal">make</code>
- command. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_MAKE_OPTS</code>, to specify additional variables to pass to make
- in the build step. These are passed after the <code class="literal">make</code> command. By
- default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_STAGING_OPTS</code> contains the make options used to
- install the package to the staging directory. By default, the value
- is <code class="literal">DESTDIR=$(STAGING_DIR) install</code>, which is correct for most
- CMake packages. It is still possible to override it.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_TARGET_OPTS</code> contains the make options used to
- install the package to the target directory. By default, the value
- is <code class="literal">DESTDIR=$(TARGET_DIR) install</code>. The default value is correct
- for most CMake packages, but it is still possible to override it if
- needed.
- </li></ul></div><p>With the CMake infrastructure, all the steps required to build and
- install the packages are already defined, and they generally work well
- for most CMake-based packages. However, when required, it is 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">
- By adding a post-operation hook (after extract, patch, configure,
- 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.
- </li><li class="listitem">
- By overriding one of the steps. For example, even if the CMake
- infrastructure is used, if the package <code class="literal">.mk</code> file defines its own
- <code class="literal">LIBFOO_CONFIGURE_CMDS</code> variable, it will be used instead of the
- default CMake one. However, using this method should be restricted
- to very specific cases. Do not use it in the general case.
- </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
- Python setuptools mechanism as their build system, generally
- 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,
- with an example :</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # python-foo
- 04: #
- 05: ################################################################################
- 06:
- 07: PYTHON_FOO_VERSION = 1.0
- 08: PYTHON_FOO_SOURCE = python-foo-$(PYTHON_FOO_VERSION).tar.xz
- 09: PYTHON_FOO_SITE = http://www.foosoftware.org/download
- 10: PYTHON_FOO_LICENSE = BSD-3-Clause
- 11: PYTHON_FOO_LICENSE_FILES = LICENSE
- 12: PYTHON_FOO_ENV = SOME_VAR=1
- 13: PYTHON_FOO_DEPENDENCIES = libmad
- 14: PYTHON_FOO_SETUP_TYPE = distutils
- 15:
- 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
- recommended) and the location of the tarball on the Web. Buildroot
- will automatically download the tarball from this location.</p><p>On line 10 and 11, we give licensing details about the package (its
- license on line 10, and the file containing the license text on line
- 11).</p><p>On line 12, we tell Buildroot to pass custom options to the Python
- <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
- before the build process of our package starts.</p><p>On line 14, we declare the specific Python build system being used. In
- this case the <code class="literal">distutils</code> Python build system is used. The two
- 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
- generates all the Makefile rules that actually allow the package to be
- 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
- named <code class="literal">python-<something></code> in Buildroot. Other packages that use the
- Python build system, but are not Python modules, can freely choose
- their name (existing examples in Buildroot are <code class="literal">scons</code> and
- <code class="literal">supervisor</code>).</p><p>Packages that are only compatible with one version of Python (as in:
- Python 2 or Python 3) should depend on that version explicitely in
- their <code class="literal">Config.in</code> file (<code class="literal">BR2_PACKAGE_PYTHON</code> for Python 2,
- <code class="literal">BR2_PACKAGE_PYTHON3</code> for Python 3). Packages that are compatible
- with both versions should not explicitely depend on them in their
- <code class="literal">Config.in</code> file, since that condition is already expressed for the
- whole "External python modules" menu.</p><p>The main macro of the Python package infrastructure is
- <code class="literal">python-package</code>. It is similar to the <code class="literal">generic-package</code> macro. It is
- also possible to create Python host packages with the
- <code class="literal">host-python-package</code> macro.</p><p>Just like the generic infrastructure, the Python infrastructure works
- by defining a number of variables before calling the <code class="literal">python-package</code>
- or <code class="literal">host-python-package</code> macros.</p><p>All the package metadata information variables that exist in the
- <a class="link" href="#generic-package-reference" title="18.5.2. generic-package reference">generic package infrastructure</a> also
- exist in the Python infrastructure: <code class="literal">PYTHON_FOO_VERSION</code>,
- <code class="literal">PYTHON_FOO_SOURCE</code>, <code class="literal">PYTHON_FOO_PATCH</code>, <code class="literal">PYTHON_FOO_SITE</code>,
- <code class="literal">PYTHON_FOO_SUBDIR</code>, <code class="literal">PYTHON_FOO_DEPENDENCIES</code>, <code class="literal">PYTHON_FOO_LICENSE</code>,
- <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">
- It is not necessary to add <code class="literal">python</code> or <code class="literal">host-python</code> in the
- <code class="literal">PYTHON_FOO_DEPENDENCIES</code> variable of a package, since these basic
- dependencies are automatically added as needed by the Python
- package infrastructure.
- </li><li class="listitem">
- Similarly, it is not needed to add <code class="literal">host-setuptools</code> to
- <code class="literal">PYTHON_FOO_DEPENDENCIES</code> for setuptools-based packages, since it’s
- automatically added by the Python infrastructure as needed.
- </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">
- <code class="literal">PYTHON_FOO_SETUP_TYPE</code>, to define which Python build system is used
- by the package. The two supported values are <code class="literal">distutils</code> and
- <code class="literal">setuptools</code>. If you don’t know which one is used in your package,
- look at the <code class="literal">setup.py</code> file in your package source code, and see
- whether it imports things from the <code class="literal">distutils</code> module or the
- <code class="literal">setuptools</code> module.
- </li></ul></div><p>A few additional variables, specific to the Python infrastructure, can
- optionally be defined, depending on the package’s needs. Many of them
- are only useful in very specific cases, typical packages will
- therefore only use a few of them, or none.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">PYTHON_FOO_SUBDIR</code> may contain the name of a subdirectory inside the
- package that contains the main <code class="literal">setup.py</code> file. This is useful,
- if for example, the main <code class="literal">setup.py</code> file is not at the root of
- the tree extracted by the tarball. If <code class="literal">HOST_PYTHON_FOO_SUBDIR</code> is not
- specified, it defaults to <code class="literal">PYTHON_FOO_SUBDIR</code>.
- </li><li class="listitem">
- <code class="literal">PYTHON_FOO_ENV</code>, to specify additional environment variables to
- pass to the Python <code class="literal">setup.py</code> script (for both the build and install
- steps). Note that the infrastructure is automatically passing
- several standard variables, defined in <code class="literal">PKG_PYTHON_DISTUTILS_ENV</code>
- (for distutils target packages), <code class="literal">HOST_PKG_PYTHON_DISTUTILS_ENV</code>
- (for distutils host packages), <code class="literal">PKG_PYTHON_SETUPTOOLS_ENV</code> (for
- setuptools target packages) and <code class="literal">HOST_PKG_PYTHON_SETUPTOOLS_ENV</code>
- (for setuptools host packages).
- </li><li class="listitem">
- <code class="literal">PYTHON_FOO_BUILD_OPTS</code>, to specify additional options to pass to the
- Python <code class="literal">setup.py</code> script during the build step. For target distutils
- packages, the <code class="literal">PKG_PYTHON_DISTUTILS_BUILD_OPTS</code> options are already
- passed automatically by the infrastructure.
- </li><li class="listitem">
- <code class="literal">PYTHON_FOO_INSTALL_TARGET_OPTS</code>, <code class="literal">PYTHON_FOO_INSTALL_STAGING_OPTS</code>,
- <code class="literal">HOST_PYTHON_FOO_INSTALL_OPTS</code> to specify additional options to pass
- to the Python <code class="literal">setup.py</code> script during the target installation step,
- the staging installation step or the host installation,
- respectively. Note that the infrastructure is automatically passing
- some options, defined in <code class="literal">PKG_PYTHON_DISTUTILS_INSTALL_TARGET_OPTS</code>
- or <code class="literal">PKG_PYTHON_DISTUTILS_INSTALL_STAGING_OPTS</code> (for target distutils
- packages), <code class="literal">HOST_PKG_PYTHON_DISTUTILS_INSTALL_OPTS</code> (for host
- distutils packages), <code class="literal">PKG_PYTHON_SETUPTOOLS_INSTALL_TARGET_OPTS</code> or
- <code class="literal">PKG_PYTHON_SETUPTOOLS_INSTALL_STAGING_OPTS</code> (for target setuptools
- packages) and <code class="literal">HOST_PKG_PYTHON_SETUPTOOLS_INSTALL_OPTS</code> (for host
- setuptools packages).
- </li><li class="listitem">
- <code class="literal">HOST_PYTHON_FOO_NEEDS_HOST_PYTHON</code>, to define the host python
- interpreter. The usage of this variable is limited to host
- packages. The two supported value are <code class="literal">python2</code> and <code class="literal">python3</code>. It
- will ensure the right host python package is available and will
- invoke it for the build. If some build steps are overloaded, the
- right python interpreter must be explicitly called in the commands.
- </li></ul></div><p>With the Python infrastructure, all the steps required to build and
- install the packages are already defined, and they generally work well
- for most Python-based packages. However, when required, it is 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">
- By adding a post-operation hook (after extract, patch, configure,
- 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.
- </li><li class="listitem">
- By overriding one of the steps. For example, even if the Python
- infrastructure is used, if the package <code class="literal">.mk</code> file defines its own
- <code class="literal">PYTHON_FOO_BUILD_CMDS</code> variable, it will be used instead of the
- default Python one. However, using this method should be restricted
- to very specific cases. Do not use it in the general case.
- </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
- package is available on PyPI, you may want to use the <code class="literal">scanpypi</code> tool
- located in <code class="literal">utils/</code> to automate the process.</p><p>You can find the list of existing PyPI packages
- <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
- 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
- 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.
- 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
- package for any mistakes as there are things that cannot be guessed by
- the generator (e.g. dependencies on any of the python core modules
- such as BR2_PACKAGE_PYTHON_ZLIB). Also, please take note that the
- license and license files are guessed and must be checked. You also
- 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
- 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
- <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
- and reliable way to call compiled C code from Python using interface
- declarations written in C. Python packages relying on this backend can
- be identified by the appearance of a <code class="literal">cffi</code> dependency in the
- <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">
- add <code class="literal">python-cffi</code> as a runtime dependency in order to install the
- compiled C library wrapper on the target. This is achieved by adding
- <code class="literal">select BR2_PACKAGE_PYTHON_CFFI</code> to the package <code class="literal">Config.in</code>.
- </li></ul></div><pre class="screen">config BR2_PACKAGE_PYTHON_FOO
- bool "python-foo"
- select BR2_PACKAGE_PYTHON_CFFI # runtime</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- add <code class="literal">host-python-cffi</code> as a build-time dependency in order to
- cross-compile the C wrapper. This is achieved by adding
- <code class="literal">host-python-cffi</code> to the <code class="literal">PYTHON_FOO_DEPENDENCIES</code> variable.
- </li></ul></div><pre class="screen">################################################################################
- #
- # python-foo
- #
- ################################################################################
- ...
- PYTHON_FOO_DEPENDENCIES = host-python-cffi
- $(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,
- with an example :</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # lua-foo
- 04: #
- 05: ################################################################################
- 06:
- 07: LUA_FOO_VERSION = 1.0.2-1
- 08: LUA_FOO_NAME_UPSTREAM = foo
- 09: LUA_FOO_DEPENDENCIES = bar
- 10:
- 11: LUA_FOO_BUILD_OPTS += BAR_INCDIR=$(STAGING_DIR)/usr/include
- 12: LUA_FOO_BUILD_OPTS += BAR_LIBDIR=$(STAGING_DIR)/usr/lib
- 13: LUA_FOO_LICENSE = luaFoo license
- 14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING
- 15:
- 16: $(eval $(luarocks-package))</pre><p>On line 7, we declare the version of the package (the same as in the rockspec,
- which is the concatenation of the upstream version and the rockspec revision,
- 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
- Buildroot, we give Lua-related packages a name that starts with "lua", so the
- Buildroot name is different from the upstream name. <code class="literal">LUA_FOO_NAME_UPSTREAM</code>
- makes the link between the two names.</p><p>On line 9, we declare our dependencies against native libraries, so that they
- 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
- 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>
- macro that generates all the Makefile rules that actually allows the
- 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>.
- So, this file and the Config.in file can be generated by running the
- command <code class="literal">luarocks buildroot foo lua-foo</code> in the Buildroot
- directory. This command runs a specific Buildroot addon of <code class="literal">luarocks</code>
- that will automatically generate a Buildroot package. The result must
- still be manually inspected and possibly modified.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- The <code class="literal">package/Config.in</code> file has to be updated manually to include the
- generated Config.in files.
- </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
- 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
- Buildroot, the <code class="literal">luarocks-package</code> infrastructure only supports the <code class="literal">builtin</code>
- mode. LuaRocks packages that use the <code class="literal">make</code> or <code class="literal">cmake</code> build mechanisms
- should instead be packaged using the <code class="literal">generic-package</code> and <code class="literal">cmake-package</code>
- infrastructures in Buildroot, respectively.</p><p>The main macro of the LuaRocks package infrastructure is <code class="literal">luarocks-package</code>:
- like <code class="literal">generic-package</code> it works by defining a number of variables providing
- 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
- by defining a number of variables before calling the <code class="literal">luarocks-package</code>
- macro.</p><p>First, all the package metadata information variables that exist in
- the generic infrastructure also exist in the LuaRocks infrastructure:
- <code class="literal">LUA_FOO_VERSION</code>, <code class="literal">LUA_FOO_SOURCE</code>, <code class="literal">LUA_FOO_SITE</code>,
- <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
- <code class="literal">download</code> step). If your package is not hosted on the LuaRocks mirror
- <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">
- <code class="literal">LUA_FOO_SITE</code>, which defaults to <code class="literal">$(BR2_LUAROCKS_MIRROR)</code>
- </li><li class="listitem">
- <code class="literal">LUA_FOO_SOURCE</code>, which defaults to
- <code class="literal">$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).src.rock</code>
- </li></ul></div><p>A few additional variables, specific to the LuaRocks infrastructure, are
- also defined. They can be overridden in specific cases.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">LUA_FOO_NAME_UPSTREAM</code>, which defaults to <code class="literal">lua-foo</code>, i.e. the Buildroot
- package name
- </li><li class="listitem">
- <code class="literal">LUA_FOO_ROCKSPEC</code>, which defaults to
- <code class="literal">$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).rockspec</code>
- </li><li class="listitem">
- <code class="literal">LUA_FOO_SUBDIR</code>, which defaults to
- <code class="literal">$(LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION_WITHOUT_ROCKSPEC_REVISION)</code>
- </li><li class="listitem">
- <code class="literal">LUA_FOO_BUILD_OPTS</code> contains additional build options for the
- <code class="literal">luarocks build</code> call.
- </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,
- with an example :</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # perl-foo-bar
- 04: #
- 05: ################################################################################
- 06:
- 07: PERL_FOO_BAR_VERSION = 0.02
- 08: PERL_FOO_BAR_SOURCE = Foo-Bar-$(PERL_FOO_BAR_VERSION).tar.gz
- 09: PERL_FOO_BAR_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER
- 10: PERL_FOO_BAR_DEPENDENCIES = perl-strictures
- 11: PERL_FOO_BAR_LICENSE = Artistic or GPL-1.0+
- 12: PERL_FOO_BAR_LICENSE_FILES = LICENSE
- 13: PERL_FOO_BAR_DISTNAME = Foo-Bar
- 14:
- 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
- of the tarball on a CPAN server. Buildroot will automatically download
- the tarball from this location.</p><p>On line 10, we declare our dependencies, so that they are built
- before the build process of our package starts.</p><p>On line 11 and 12, we give licensing details about the package (its
- license on line 11, and the file containing the license text on line
- 12).</p><p>On line 13, the name of the distribution as needed by the script
- <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
- generates all the Makefile rules that actually allow the package to be
- built.</p><p>Most of these data can be retrieved from <a class="ulink" href="https://metacpan.org/" target="_top">https://metacpan.org/</a>.
- So, this file and the Config.in can be generated by running
- the script <code class="literal">utils/scancpan Foo-Bar</code> in the Buildroot directory
- (or in a br2-external tree).
- This script creates a Config.in file and foo-bar.mk file for the
- requested package, and also recursively for all dependencies specified by
- CPAN. You should still manually edit the result. In particular, the
- following things should be checked.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- If the perl module links with a shared library that is provided by
- another (non-perl) package, this dependency is not added automatically.
- It has to be added manually to <code class="literal">PERL_FOO_BAR_DEPENDENCIES</code>.
- </li><li class="listitem">
- The <code class="literal">package/Config.in</code> file has to be updated manually to include the
- generated Config.in files. As a hint, the <code class="literal">scancpan</code> script prints out
- the required <code class="literal">source "…"</code> statements, sorted alphabetically.
- </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
- named <code class="literal">perl-<something></code> in Buildroot.</p><p>This infrastructure handles various Perl build systems :
- <code class="literal">ExtUtils-MakeMaker</code> (EUMM), <code class="literal">Module-Build</code> (MB) and <code class="literal">Module-Build-Tiny</code>.
- <code class="literal">Build.PL</code> is preferred by default when a package provides a <code class="literal">Makefile.PL</code>
- and a <code class="literal">Build.PL</code>.</p><p>The main macro of the Perl/CPAN package infrastructure is
- <code class="literal">perl-package</code>. It is similar to the <code class="literal">generic-package</code> macro. The ability to
- have target and host packages is also available, with the
- <code class="literal">host-perl-package</code> macro.</p><p>Just like the generic infrastructure, the Perl/CPAN infrastructure
- works by defining a number of variables before calling the
- <code class="literal">perl-package</code> macro.</p><p>First, all the package metadata information variables that exist in the
- generic infrastructure also exist in the Perl/CPAN infrastructure:
- <code class="literal">PERL_FOO_VERSION</code>, <code class="literal">PERL_FOO_SOURCE</code>,
- <code class="literal">PERL_FOO_PATCH</code>, <code class="literal">PERL_FOO_SITE</code>,
- <code class="literal">PERL_FOO_SUBDIR</code>, <code class="literal">PERL_FOO_DEPENDENCIES</code>,
- <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
- unless a <code class="literal">PERL_FOO_INSTALL_STAGING_CMDS</code> variable is defined. The perl
- infrastructure doesn’t define these commands since Perl modules generally
- 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,
- can also be defined. Many of them are only useful in very specific
- 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">
- <code class="literal">PERL_FOO_PREFER_INSTALLER</code>/<code class="literal">HOST_PERL_FOO_PREFER_INSTALLER</code>,
- specifies the preferred installation method. Possible values are
- <code class="literal">EUMM</code> (for <code class="literal">Makefile.PL</code> based installation using
- <code class="literal">ExtUtils-MakeMaker</code>) and <code class="literal">MB</code> (for <code class="literal">Build.PL</code> based installation
- using <code class="literal">Module-Build</code>). This variable is only used when the package
- provides both installation methods.
- </li><li class="listitem">
- <code class="literal">PERL_FOO_CONF_ENV</code>/<code class="literal">HOST_PERL_FOO_CONF_ENV</code>, to specify additional
- environment variables to pass to the <code class="literal">perl Makefile.PL</code> or <code class="literal">perl Build.PL</code>.
- By default, empty.
- </li><li class="listitem">
- <code class="literal">PERL_FOO_CONF_OPTS</code>/<code class="literal">HOST_PERL_FOO_CONF_OPTS</code>, to specify additional
- configure options to pass to the <code class="literal">perl Makefile.PL</code> or <code class="literal">perl Build.PL</code>.
- By default, empty.
- </li><li class="listitem">
- <code class="literal">PERL_FOO_BUILD_OPTS</code>/<code class="literal">HOST_PERL_FOO_BUILD_OPTS</code>, to specify additional
- options to pass to <code class="literal">make pure_all</code> or <code class="literal">perl Build build</code> in the build step.
- By default, empty.
- </li><li class="listitem">
- <code class="literal">PERL_FOO_INSTALL_TARGET_OPTS</code>, to specify additional options to
- pass to <code class="literal">make pure_install</code> or <code class="literal">perl Build install</code> in the install step.
- By default, empty.
- </li><li class="listitem">
- <code class="literal">HOST_PERL_FOO_INSTALL_OPTS</code>, to specify additional options to
- pass to <code class="literal">make pure_install</code> or <code class="literal">perl Build install</code> in the install step.
- By default, empty.
- </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
- provided by one or more packages, referred to as <span class="emphasis"><em>providers</em></span>. The virtual
- package management is an extensible mechanism allowing the user to choose
- 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.
- The implementation of this API is different for the <span class="emphasis"><em>Allwinner Tech Sunxi</em></span> and
- the <span class="emphasis"><em>Texas Instruments OMAP35xx</em></span> platforms. So <code class="literal">libgles</code> will be a virtual
- 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
- (<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
- 02: bool
- 03:
- 04: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
- 05: depends on BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
- 06: string</pre><p>In this file, we declare two options, <code class="literal">BR2_PACKAGE_HAS_SOMETHING_VIRTUAL</code> and
- <code class="literal">BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL</code>, whose values will be used by the
- 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: ################################################################################
- 02: #
- 03: # something-virtual
- 04: #
- 05: ################################################################################
- 06:
- 07: $(eval $(virtual-package))</pre><p>The ability to have target and host packages is also available, with the
- <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
- 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
- functionalities of <span class="emphasis"><em>something-virtual</em></span>, should contain:</p><pre class="screen">01: config BR2_PACKAGE_SOME_PROVIDER
- 02: bool "some-provider"
- 03: select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
- 04: help
- 05: This is a comment that explains what some-provider is.
- 06:
- 07: http://foosoftware.org/some-provider/
- 08:
- 09: if BR2_PACKAGE_SOME_PROVIDER
- 10: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
- 11: default "some-provider"
- 12: endif</pre><p>On line 3, we select <code class="literal">BR2_PACKAGE_HAS_SOMETHING_VIRTUAL</code>, and on line 11, we
- set the value of <code class="literal">BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL</code> to the name of the
- 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
- <code class="literal">SOME_PROVIDER_PROVIDES</code> to contain the names of all the virtual
- 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
- 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
- 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
- bool
- config BR2_PACKAGE_FOO
- bool "foo"
- 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
- 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
- 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
- bool
- config BR2_PACKAGE_FOO
- bool "foo"
- select BR2_PACKAGE_HAS_FEATURE
- config BR2_PACKAGE_BAR
- bool "bar"
- 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>,
- 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
- be able to select <code class="literal">BR2_PACKAGE_BAR</code> in the menuconfig. This would create
- a configuration inconsistency, whereby two providers of the same <code class="literal">FEATURE</code>
- would be enabled at once, one explicitly set by the user, the other
- 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
- 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
- configuration is <code class="literal">kconfig</code>. Among others, it is used by the Linux
- kernel, Busybox, and Buildroot itself. The presence of a .config file
- and a <code class="literal">menuconfig</code> target are two well-known symptoms of kconfig being
- used.</p><p>Buildroot features an infrastructure for packages that use kconfig for
- their configuration. This infrastructure provides the necessary logic to
- expose the package’s <code class="literal">menuconfig</code> target as <code class="literal">foo-menuconfig</code> in
- Buildroot, and to handle the copying back and forth of the configuration
- 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>
- infrastructure. All variables supported by <code class="literal">generic-package</code> are
- available in <code class="literal">kconfig-package</code> as well. 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> for more details.</p><p>In order to use the <code class="literal">kconfig-package</code> infrastructure for a Buildroot
- package, the minimally required lines in the <code class="literal">.mk</code> file, in addition to
- 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
- $(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">
- <code class="literal">foo-menuconfig</code>, which calls the package’s <code class="literal">menuconfig</code> target
- </li><li class="listitem">
- <code class="literal">foo-update-config</code>, which copies the configuration back to the
- source configuration file. It is not possible to use this target
- when fragment files are set.
- </li><li class="listitem">
- <code class="literal">foo-update-defconfig</code>, which copies the configuration back to the
- source configuration file. The configuration file will only list the
- options that differ from the default values. It is not possible to
- use this target when fragment files are set.
- </li><li class="listitem">
- <code class="literal">foo-diff-config</code>, which outputs the differences between the current
- configuration and the one defined in the Buildroot configuration for
- this kconfig package. The output is useful to identify the
- configuration changes that may have to be propagated to
- configuration fragments for example.
- </li></ul></div><p>and ensures that the source configuration file is copied to the build
- directory at the right moment.</p><p>There are two options to specify a configuration file to use, either
- <code class="literal">FOO_KCONFIG_FILE</code> (as in the example, above) or <code class="literal">FOO_KCONFIG_DEFCONFIG</code>.
- It is mandatory to provide either, but not both:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">FOO_KCONFIG_FILE</code> specifies the path to a defconfig or full-config file
- to be used to configure the package.
- </li><li class="listitem">
- <code class="literal">FOO_KCONFIG_DEFCONFIG</code> specifies the defconfig <span class="emphasis"><em>make</em></span> rule to call to
- configure the package.
- </li></ul></div><p>In addition to these minimally required lines, several optional variables can
- 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">
- <code class="literal">FOO_KCONFIG_EDITORS</code>: a space-separated list of kconfig editors to
- support, for example <span class="emphasis"><em>menuconfig xconfig</em></span>. By default, <span class="emphasis"><em>menuconfig</em></span>.
- </li><li class="listitem">
- <code class="literal">FOO_KCONFIG_FRAGMENT_FILES</code>: a space-separated list of configuration
- fragment files that are merged to the main configuration file.
- Fragment files are typically used when there is a desire to stay in sync
- with an upstream (def)config file, with some minor modifications.
- </li><li class="listitem">
- <code class="literal">FOO_KCONFIG_OPTS</code>: extra options to pass when calling the kconfig
- editors. This may need to include <span class="emphasis"><em>$(FOO_MAKE_OPTS)</em></span>, for example. By
- default, empty.
- </li><li class="listitem">
- <code class="literal">FOO_KCONFIG_FIXUP_CMDS</code>: a list of shell commands needed to fixup the
- configuration file after copying it or running a kconfig editor. Such
- commands may be needed to ensure a configuration consistent with other
- configuration of Buildroot, for example. By default, empty.
- </li><li class="listitem">
- <code class="literal">FOO_KCONFIG_DOTCONFIG</code>: path (with filename) of the <code class="literal">.config</code> file,
- relative to the package source tree. The default, <code class="literal">.config</code>, should
- be well suited for all packages that use the standard kconfig
- infrastructure as inherited from the Linux kernel; some packages use
- a derivative of kconfig that use a different location.
- </li><li class="listitem">
- <code class="literal">FOO_KCONFIG_DEPENDENCIES</code>: the list of packages (most probably, host
- packages) that need to be built before this package’s kconfig is
- interpreted. Seldom used. By default, empty.
- </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,
- with an example :</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # erlang-foobar
- 04: #
- 05: ################################################################################
- 06:
- 07: ERLANG_FOOBAR_VERSION = 1.0
- 08: ERLANG_FOOBAR_SOURCE = erlang-foobar-$(ERLANG_FOOBAR_VERSION).tar.xz
- 09: ERLANG_FOOBAR_SITE = http://www.foosoftware.org/download
- 10: ERLANG_FOOBAR_DEPENDENCIES = host-libaaa libbbb
- 11:
- 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
- recommended) and the location of the tarball on the Web. Buildroot
- will automatically download the tarball from this location.</p><p>On line 10, we declare our dependencies, so that they are built
- 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
- generates all the Makefile rules that actually allows the package to
- 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
- <code class="literal">rebar-package</code>. It is similar to the <code class="literal">generic-package</code> macro. The
- ability to have host packages is also available, with the
- <code class="literal">host-rebar-package</code> macro.</p><p>Just like the generic infrastructure, the <code class="literal">rebar</code> infrastructure works
- by defining a number of variables before calling the <code class="literal">rebar-package</code>
- macro.</p><p>First, all the package metadata information variables that exist in
- the generic infrastructure also exist in the <code class="literal">rebar</code> infrastructure:
- <code class="literal">ERLANG_FOOBAR_VERSION</code>, <code class="literal">ERLANG_FOOBAR_SOURCE</code>,
- <code class="literal">ERLANG_FOOBAR_PATCH</code>, <code class="literal">ERLANG_FOOBAR_SITE</code>,
- <code class="literal">ERLANG_FOOBAR_SUBDIR</code>, <code class="literal">ERLANG_FOOBAR_DEPENDENCIES</code>,
- <code class="literal">ERLANG_FOOBAR_INSTALL_STAGING</code>, <code class="literal">ERLANG_FOOBAR_INSTALL_TARGET</code>,
- <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,
- can also be defined. Many of them are only useful in very specific
- 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">
- <code class="literal">ERLANG_FOOBAR_USE_AUTOCONF</code>, to specify that the package uses
- <span class="emphasis"><em>autoconf</em></span> at the configuration step. When a package sets this
- variable to <code class="literal">YES</code>, the <code class="literal">autotools</code> infrastructure is used.
- </p><p><strong>Note. </strong>You can also use some of the variables from the <code class="literal">autotools</code>
- infrastructure: <code class="literal">ERLANG_FOOBAR_CONF_ENV</code>, <code class="literal">ERLANG_FOOBAR_CONF_OPTS</code>,
- <code class="literal">ERLANG_FOOBAR_AUTORECONF</code>, <code class="literal">ERLANG_FOOBAR_AUTORECONF_ENV</code> and
- <code class="literal">ERLANG_FOOBAR_AUTORECONF_OPTS</code>.</p></li><li class="listitem"><p class="simpara">
- <code class="literal">ERLANG_FOOBAR_USE_BUNDLED_REBAR</code>, to specify that the package has
- a bundled version of <span class="emphasis"><em>rebar</em></span> <span class="strong"><strong>and</strong></span> that it shall be used. Valid
- values are <code class="literal">YES</code> or <code class="literal">NO</code> (the default).
- </p><p><strong>Note. </strong>If the package bundles a <span class="emphasis"><em>rebar</em></span> utility, but can use the generic
- one that Buildroot provides, just say <code class="literal">NO</code> (i.e., do not specify
- this variable). Only set if it is mandatory to use the <span class="emphasis"><em>rebar</em></span>
- utility bundled in this package.</p></li><li class="listitem">
- <code class="literal">ERLANG_FOOBAR_REBAR_ENV</code>, to specify additional environment
- variables to pass to the <span class="emphasis"><em>rebar</em></span> utility.
- </li><li class="listitem">
- <code class="literal">ERLANG_FOOBAR_KEEP_DEPENDENCIES</code>, to keep the dependencies
- described in the rebar.config file. Valid values are <code class="literal">YES</code> or <code class="literal">NO</code>
- (the default). Unless this variable is set to <code class="literal">YES</code>, the <span class="emphasis"><em>rebar</em></span>
- infrastructure removes such dependencies in a post-patch hook to
- ensure rebar does not download nor compile them.
- </li></ul></div><p>With the rebar infrastructure, all the steps required to build
- and install the packages are already defined, and they generally work
- well for most rebar-based packages. However, when required, it is
- 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">
- By adding a post-operation hook (after extract, patch, configure,
- 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.
- </li><li class="listitem">
- By overriding one of the steps. For example, even if the rebar
- infrastructure is used, if the package <code class="literal">.mk</code> file defines its
- own <code class="literal">ERLANG_FOOBAR_BUILD_CMDS</code> variable, it will be used instead
- of the default rebar one. However, using this method should be
- restricted to very specific cases. Do not use it in the general
- case.
- </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
- an example :</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # libfoo
- 04: #
- 05: ################################################################################
- 06:
- 07: LIBFOO_VERSION = 1.0
- 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
- 09: LIBFOO_SITE = http://www.foosoftware.org/download
- 10: LIBFOO_CONF_OPTS = --enable-bar --disable-baz
- 11: LIBFOO_DEPENDENCIES = bar
- 12:
- 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
- recommended) and the location of the tarball on the Web. Buildroot
- 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>
- macro that generates all the Makefile rules that actually allows the
- 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>.
- It is similar to the <code class="literal">generic-package</code> macro.</p><p>Just like the generic infrastructure, the Waf infrastructure works
- by defining a number of variables before calling the <code class="literal">waf-package</code>
- macro.</p><p>First, all the package metadata information variables that exist in
- the generic infrastructure also exist in the Waf infrastructure:
- <code class="literal">LIBFOO_VERSION</code>, <code class="literal">LIBFOO_SOURCE</code>, <code class="literal">LIBFOO_PATCH</code>, <code class="literal">LIBFOO_SITE</code>,
- <code class="literal">LIBFOO_SUBDIR</code>, <code class="literal">LIBFOO_DEPENDENCIES</code>, <code class="literal">LIBFOO_INSTALL_STAGING</code>,
- <code class="literal">LIBFOO_INSTALL_TARGET</code>.</p><p>An additional variable, specific to the Waf infrastructure, can
- also be defined.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">LIBFOO_SUBDIR</code> may contain the name of a subdirectory inside the
- package that contains the main wscript file. This is useful,
- if for example, the main wscript file is not at the root of
- the tree extracted by the tarball. If <code class="literal">HOST_LIBFOO_SUBDIR</code> is not
- specified, it defaults to <code class="literal">LIBFOO_SUBDIR</code>.
- </li><li class="listitem">
- <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
- Buildroot to use the bundled <code class="literal">waf</code> executable. If set to <code class="literal">NO</code>, the
- default, then Buildroot will use the waf executable provided in the
- package source tree; if set to <code class="literal">YES</code>, then Buildroot will download,
- install waf as a host tool and use it to build the package.
- </li><li class="listitem">
- <code class="literal">LIBFOO_WAF_OPTS</code>, to specify additional options to pass to the
- <code class="literal">waf</code> script at every step of the package build process: configure,
- build and installation. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_CONF_OPTS</code>, to specify additional options to pass to the
- <code class="literal">waf</code> script for the configuration step. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_BUILD_OPTS</code>, to specify additional options to pass to the
- <code class="literal">waf</code> script during the build step. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_STAGING_OPTS</code>, to specify additional options to pass
- to the <code class="literal">waf</code> script during the staging installation step. By default,
- empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_TARGET_OPTS</code>, to specify additional options to pass
- to the <code class="literal">waf</code> script during the target installation step. By default,
- empty.
- </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
- extremely fast, and, even more importantly, as user friendly as possible. It
- uses <a class="ulink" href="https://ninja-build.org" target="_top">Ninja</a> as a companion tool to perform the actual
- 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: ################################################################################
- 02: #
- 03: # foo
- 04: #
- 05: ################################################################################
- 06:
- 07: FOO_VERSION = 1.0
- 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
- 09: FOO_SITE = http://www.foosoftware.org/download
- 10: FOO_LICENSE = GPL-3.0+
- 11: FOO_LICENSE_FILES = COPYING
- 12: FOO_INSTALL_STAGING = YES
- 13:
- 14: FOO_DEPENDENCIES = host-pkgconf bar
- 15:
- 16: ifeq ($(BR2_PACKAGE_BAZ),y)
- 17: FOO_CONF_OPTS += -Dbaz=true
- 18: FOO_DEPENDENCIES += baz
- 19: else
- 20: FOO_CONF_OPTS += -Dbaz=false
- 21: endif
- 22:
- 23: $(eval $(meson-package))</pre><p>The Makefile starts with the definition of the standard variables for package
- 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
- 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
- <code class="literal">FOO_DEPENDENCIES</code> at line 14 because the Meson build file of <code class="literal">foo</code> uses
- <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>
- variable of a package, since this basic dependency is automatically added as
- needed by the Meson package infrastructure.</p><p>If the "baz" package is selected, then support for the "baz" feature in "foo" is
- activated by adding <code class="literal">-Dbaz=true</code> to <code class="literal">FOO_CONF_OPTS</code> at line 17, as specified in
- the <code class="literal">meson_options.txt</code> file in "foo" source tree. The "baz" package is also
- added to <code class="literal">FOO_DEPENDENCIES</code>. Note that the support for <code class="literal">baz</code> is explicitly
- 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
- copied verbatim then edited to replace all occurences of <code class="literal">FOO</code> with the
- uppercase name of the new package and update the values of the standard
- 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
- similar to the <code class="literal">generic-package</code> macro. The ability to have target and host
- 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
- 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
- infrastructure also exist in the Meson infrastructure: <code class="literal">FOO_VERSION</code>,
- <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>,
- <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
- defined. Many of them are only useful in very specific 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">
- <code class="literal">FOO_SUBDIR</code> may contain the name of a subdirectory inside the
- package that contains the main meson.build file. This is useful,
- if for example, the main meson.build file is not at the root of
- the tree extracted by the tarball. If <code class="literal">HOST_FOO_SUBDIR</code> is not
- specified, it defaults to <code class="literal">FOO_SUBDIR</code>.
- </li><li class="listitem">
- <code class="literal">FOO_CONF_ENV</code>, to specify additional environment variables to pass to
- <code class="literal">meson</code> for the configuration step. By default, empty.
- </li><li class="listitem">
- <code class="literal">FOO_CONF_OPTS</code>, to specify additional options to pass to <code class="literal">meson</code> for the
- configuration step. By default, empty.
- </li><li class="listitem">
- <code class="literal">FOO_CFLAGS</code>, to specify compiler arguments added to the package specific
- <code class="literal">cross-compile.conf</code> file <code class="literal">c_args</code> property. By default, the value of
- <code class="literal">TARGET_CFLAGS</code>.
- </li><li class="listitem">
- <code class="literal">FOO_CXXFLAGS</code>, to specify compiler arguments added to the package specific
- <code class="literal">cross-compile.conf</code> file <code class="literal">cpp_args</code> property. By default, the value of
- <code class="literal">TARGET_CXXFLAGS</code>.
- </li><li class="listitem">
- <code class="literal">FOO_LDFLAGS</code>, to specify compiler arguments added to the package specific
- <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
- default, the value of <code class="literal">TARGET_LDFLAGS</code>.
- </li><li class="listitem">
- <code class="literal">FOO_MESON_EXTRA_BINARIES</code>, to specify a space-separated list of programs
- to add to the <code class="literal">[binaries]</code> section of the meson <code class="literal">cross-compilation.conf</code>
- configuration file. The format is <code class="literal">program-name='/path/to/program'</code>, with
- no space around the <code class="literal">=</code> sign, and with the path of the program between
- single quotes. By default, empty. Note that Buildroot already sets the
- 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>.
- </li><li class="listitem">
- <code class="literal">FOO_MESON_EXTRA_PROPERTIES</code>, to specify a space-separated list of
- properties to add to the <code class="literal">[properties]</code> section of the meson
- <code class="literal">cross-compilation.conf</code> configuration file. The format is
- <code class="literal">property-name=<value></code> with no space around the <code class="literal">=</code> sign, and with
- single quotes around string values. By default, empty. Note that
- Buildroot already sets values for <code class="literal">needs_exe_wrapper</code>, <code class="literal">c_args</code>,
- <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
- <code class="literal">pkg_config_libdir</code>.
- </li><li class="listitem">
- <code class="literal">FOO_NINJA_ENV</code>, to specify additional environment variables to pass to
- <code class="literal">ninja</code>, meson companion tool in charge of the build operations. By default,
- empty.
- </li><li class="listitem">
- <code class="literal">FOO_NINJA_OPTS</code>, to specify a space-separated list of targets to build. By
- default, empty, to build the default target(s).
- </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
- user to build programs or libraries written in Rust, but it also downloads and
- manages their dependencies, to ensure repeatable builds. Cargo packages are
- 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
- 02: bool "foo"
- 03: depends on BR2_PACKAGE_HOST_RUSTC_TARGET_ARCH_SUPPORTS
- 04: select BR2_PACKAGE_HOST_RUSTC
- 05: help
- 06: This is a comment that explains what foo is.
- 07:
- 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
- Cargo-based packages. So, we will explain how to write a <code class="literal">.mk</code> file for such a
- package. Let’s start with an example:</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # foo
- 04: #
- 05: ################################################################################
- 06:
- 07: FOO_VERSION = 1.0
- 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
- 09: FOO_SITE = http://www.foosoftware.org/download
- 10: FOO_LICENSE = GPL-3.0+
- 11: FOO_LICENSE_FILES = COPYING
- 12:
- 13: FOO_DEPENDENCIES = host-rustc
- 14:
- 15: FOO_CARGO_ENV = CARGO_HOME=$(HOST_DIR)/share/cargo
- 16:
- 17: FOO_BIN_DIR = target/$(RUSTC_TARGET_NAME)/$(FOO_CARGO_MODE)
- 18:
- 19: FOO_CARGO_OPTS = \
- 20: $(if $(BR2_ENABLE_DEBUG),,--release) \
- 21: --target=$(RUSTC_TARGET_NAME) \
- 22: --manifest-path=$(@D)/Cargo.toml
- 23:
- 24: define FOO_BUILD_CMDS
- 25: $(TARGET_MAKE_ENV) $(FOO_CARGO_ENV) \
- 26: cargo build $(FOO_CARGO_OPTS)
- 27: endef
- 28:
- 29: define FOO_INSTALL_TARGET_CMDS
- 30: $(INSTALL) -D -m 0755 $(@D)/$(FOO_BIN_DIR)/foo \
- 31: $(TARGET_DIR)/usr/bin/foo
- 32: endef
- 33:
- 34: $(eval $(generic-package))</pre><p>The Makefile starts with the definition of the standard variables for package
- declaration (lines 7 to 11).</p><p>As seen in line 34, it is based on the
- <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
- the variables required by this particular infrastructure, where Cargo is
- invoked:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">FOO_BUILD_CMDS</code>: Cargo is invoked to perform the build. The options required
- to configure the cross-compilation of the package are passed via
- <code class="literal">FOO_CONF_OPTS</code>.
- </li><li class="listitem">
- <code class="literal">FOO_INSTALL_TARGET_CMDS</code>: The binary executable generated is installed on
- the target.
- </li></ul></div><p>In order to have Cargo available for the build, <code class="literal">FOO_DEPENDENCIES</code> needs to
- 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
- copied verbatim then edited to replace all occurences of <code class="literal">FOO</code> with the
- uppercase name of the new package and update the values of the standard
- 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
- in its Cargo.toml file. Before starting a build, Cargo usually downloads
- automatically them. This step can also be performed independently, via the
- <code class="literal">cargo fetch</code> command.</p><p>Cargo maintains a local cache of the registry index and of git checkouts of the
- crates, whose location is given by <code class="literal">$CARGO_HOME</code>. As seen in the package
- Makefile example at line 15, this environment variable is set to
- <code class="literal">$(HOST_DIR)/share/cargo</code>.</p><p>This dependency download mechanism is not convenient when performing an offline
- build, as Cargo will fail to fetch the dependencies. In that case, it is advised
- to generate a tarball of the dependencies using the <code class="literal">cargo vendor</code> and add it to
- <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
- 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,
- with an example :</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # foo
- 04: #
- 05: ################################################################################
- 06:
- 07: FOO_VERSION = 1.0
- 08: FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))
- 09: FOO_LICENSE = BSD-3-Clause
- 10: FOO_LICENSE_FILES = LICENSE
- 11:
- 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
- fetched from Github, since a large number of Go packages are hosted on
- 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
- generates all the Makefile rules that actually allow the package to be
- 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>
- infrastructure should depend on <code class="literal">BR2_PACKAGE_HOST_GO_TARGET_ARCH_SUPPORTS</code>
- because Buildroot will automatically add a dependency on <code class="literal">host-go</code>
- to such packages.
- If you need CGO support in your package, you must add a dependency on
- <code class="literal">BR2_PACKAGE_HOST_GO_TARGET_CGO_LINKING_SUPPORTS</code>.</p><p>The main macro of the Go package infrastructure is
- <code class="literal">golang-package</code>. It is similar to the <code class="literal">generic-package</code> macro. The
- ability to build host packages is also available, with the
- <code class="literal">host-golang-package</code> macro.
- Host packages built by <code class="literal">host-golang-package</code> macro should depend on
- BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.</p><p>Just like the generic infrastructure, the Go infrastructure works
- 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
- <a class="link" href="#generic-package-reference" title="18.5.2. generic-package reference">generic package infrastructure</a> also
- exist in the Go infrastructure: <code class="literal">FOO_VERSION</code>, <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>,
- <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
- <code class="literal">FOO_DEPENDENCIES</code> variable of a package, since this basic dependency
- is automatically added as needed by the Go package infrastructure.</p><p>A few additional variables, specific to the Go infrastructure, can
- optionally be defined, depending on the package’s needs. Many of them
- are only useful in very specific cases, typical packages will
- therefore only use a few of them, or none.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- The package must specify its Go module name in the <code class="literal">FOO_GOMOD</code>
- variable. If not specified, it defaults to
- <code class="literal">URL-domain/1st-part-of-URL/2nd-part-of-URL</code>, e.g <code class="literal">FOO_GOMOD</code> will
- take the value <code class="literal">github.com/bar/foo</code> for a package that specifies
- <code class="literal">FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))</code>. The Go package
- infrastructure will automatically generate a minimal <code class="literal">go.mod</code> file
- in the package source tree if it doesn’t exist.
- </li><li class="listitem">
- <code class="literal">FOO_LDFLAGS</code> and <code class="literal">FOO_TAGS</code> can be used to pass respectively the
- <code class="literal">LDFLAGS</code> or the <code class="literal">TAGS</code> to the <code class="literal">go</code> build command.
- </li><li class="listitem"><p class="simpara">
- <code class="literal">FOO_BUILD_TARGETS</code> can be used to pass the list of targets that
- should be built. If <code class="literal">FOO_BUILD_TARGETS</code> is not specified, it
- defaults to <code class="literal">.</code>. We then have two cases:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- <code class="literal">FOO_BUILD_TARGETS</code> is <code class="literal">.</code>. In this case, we assume only one binary
- will be produced, and that by default we name it after the package
- name. If that is not appropriate, the name of the produced binary
- can be overridden using <code class="literal">FOO_BIN_NAME</code>.
- </li><li class="listitem">
- <code class="literal">FOO_BUILD_TARGETS</code> is not <code class="literal">.</code>. In this case, we iterate over the
- values to build each target, and for each produced a binary that is
- the non-directory component of the target. For example if
- <code class="literal">FOO_BUILD_TARGETS = cmd/docker cmd/dockerd</code> the binaries produced
- are <code class="literal">docker</code> and <code class="literal">dockerd</code>.
- </li></ul></div></li><li class="listitem">
- <code class="literal">FOO_INSTALL_BINS</code> can be used to pass the list of binaries that
- should be installed in <code class="literal">/usr/bin</code> on the target. If
- <code class="literal">FOO_INSTALL_BINS</code> is not specified, it defaults to the lower-case
- name of package.
- </li></ul></div><p>With the Go infrastructure, all the steps required to build and
- install the packages are already defined, and they generally work well
- for most Go-based packages. However, when required, it is 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">
- By adding a post-operation hook (after extract, patch, configure,
- 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.
- </li><li class="listitem">
- By overriding one of the steps. For example, even if the Go
- infrastructure is used, if the package <code class="literal">.mk</code> file defines its own
- <code class="literal">FOO_BUILD_CMDS</code> variable, it will be used instead of the default Go
- one. However, using this method should be restricted to very
- specific cases. Do not use it in the general case.
- </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
- an example :</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # libfoo
- 04: #
- 05: ################################################################################
- 06:
- 07: LIBFOO_VERSION = 1.0
- 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
- 09: LIBFOO_SITE = http://www.foosoftware.org/download
- 10: LIBFOO_CONF_OPTS = QT_CONFIG+=bar QT_CONFIG-=baz
- 11: LIBFOO_DEPENDENCIES = bar
- 12:
- 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
- recommended) and the location of the tarball on the Web. Buildroot
- 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>
- macro that generates all the Makefile rules that actually allows the
- 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>.
- It is similar to the <code class="literal">generic-package</code> macro.</p><p>Just like the generic infrastructure, the QMake infrastructure works
- by defining a number of variables before calling the <code class="literal">qmake-package</code>
- macro.</p><p>First, all the package metadata information variables that exist in
- the generic infrastructure also exist in the QMake infrastructure:
- <code class="literal">LIBFOO_VERSION</code>, <code class="literal">LIBFOO_SOURCE</code>, <code class="literal">LIBFOO_PATCH</code>, <code class="literal">LIBFOO_SITE</code>,
- <code class="literal">LIBFOO_SUBDIR</code>, <code class="literal">LIBFOO_DEPENDENCIES</code>, <code class="literal">LIBFOO_INSTALL_STAGING</code>,
- <code class="literal">LIBFOO_INSTALL_TARGET</code>.</p><p>An additional variable, specific to the QMake infrastructure, can
- also be defined.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">LIBFOO_CONF_ENV</code>, to specify additional environment variables to
- pass to the <code class="literal">qmake</code> script for the configuration step. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_CONF_OPTS</code>, to specify additional options to pass to the
- <code class="literal">qmake</code> script for the configuration step. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_MAKE_ENV</code>, to specify additional environment variables to the
- <code class="literal">make</code> command during the build and install steps. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_MAKE_OPTS</code>, to specify additional targets to pass to the
- <code class="literal">make</code> command during the build step. By default, empty.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_STAGING_OPTS</code>, to specify additional targets to pass
- to the <code class="literal">make</code> command during the staging installation step. By default,
- <code class="literal">install</code>.
- </li><li class="listitem">
- <code class="literal">LIBFOO_INSTALL_TARGET_OPTS</code>, to specify additional targets to pass
- to the <code class="literal">make</code> command during the target installation step. By default,
- <code class="literal">install</code>.
- </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
- build and install Linux kernel modules. Some packages only contain a kernel
- module, other packages contain programs and libraries in addition to kernel
- 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
- builds a kernel module, and no other component:</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # foo
- 04: #
- 05: ################################################################################
- 06:
- 07: FOO_VERSION = 1.2.3
- 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
- 09: FOO_SITE = http://www.foosoftware.org/download
- 10: FOO_LICENSE = GPL-2.0
- 11: FOO_LICENSE_FILES = COPYING
- 12:
- 13: $(eval $(kernel-module))
- 14: $(eval $(generic-package))</pre><p>Lines 7-11 define the usual meta-data to specify the version, archive name,
- 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
- generates all the appropriate Makefile rules and variables to build
- that kernel module.</p><p>Finally, on line 14, we invoke the
- <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
- specify it in <code class="literal">FOO_DEPENDENCIES</code>.</p><p>What you may have noticed is that, unlike other package infrastructures,
- we explicitly invoke a second infrastructure. This allows a package to
- build a kernel module, but also, if needed, use any one of other package
- infrastructures to build normal userland components (libraries,
- executables…). Using the <code class="literal">kernel-module</code> infrastructure on its own is
- 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: ################################################################################
- 02: #
- 03: # foo
- 04: #
- 05: ################################################################################
- 06:
- 07: FOO_VERSION = 1.2.3
- 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
- 09: FOO_SITE = http://www.foosoftware.org/download
- 10: FOO_LICENSE = GPL-2.0
- 11: FOO_LICENSE_FILES = COPYING
- 12:
- 13: FOO_MODULE_SUBDIRS = driver/base
- 14: FOO_MODULE_MAKE_OPTS = KVERSION=$(LINUX_VERSION_PROBED)
- 15:
- 16: ifeq ($(BR2_PACKAGE_LIBBAR),y)
- 17: FOO_DEPENDENCIES = libbar
- 18: FOO_CONF_OPTS = --enable-bar
- 19: FOO_MODULE_SUBDIRS += driver/bar
- 20: else
- 21: FOO_CONF_OPTS = --disable-bar
- 22: endif
- 23:
- 24: $(eval $(kernel-module))
- 26: $(eval $(autotools-package))</pre><p>Here, we see that we have an autotools-based package, that also builds
- the kernel module located in sub-directory <code class="literal">driver/base</code> and, if libbar
- is enabled, the kernel module located in sub-directory <code class="literal">driver/bar</code>, and
- defines the variable <code class="literal">KVERSION</code> to be passed to the Linux buildsystem
- 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>.
- Unlike other package infrastructures, it is not stand-alone, and requires
- 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
- hooks to build the kernel modules. If the package’s <code class="literal">.mk</code> needs access
- to the built kernel modules, it should do so in a post-build hook,
- <span class="strong"><strong>registered after</strong></span> the call to <code class="literal">kernel-module</code>. Similarly, if the
- package’s <code class="literal">.mk</code> needs access to the kernel module after it has been
- installed, it should do so in a post-install hook, <span class="strong"><strong>registered after</strong></span>
- the call to <code class="literal">kernel-module</code>. Here’s an example:</p><pre class="screen">$(eval $(kernel-module))
- define FOO_DO_STUFF_WITH_KERNEL_MODULE
- # Do something with it...
- endef
- FOO_POST_BUILD_HOOKS += FOO_DO_STUFF_WITH_KERNEL_MODULE
- $(eval $(generic-package))</pre><p>Finally, unlike the other package infrastructures, there is no
- <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
- configure the build of the kernel module:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">FOO_MODULE_SUBDIRS</code> may be set to one or more sub-directories (relative
- to the package source top-directory) where the kernel module sources are.
- If empty or not set, the sources for the kernel module(s) are considered
- to be located at the top of the package source tree.
- </li><li class="listitem">
- <code class="literal">FOO_MODULE_MAKE_OPTS</code> may be set to contain extra variable definitions
- to pass to the Linux buildsystem.
- </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">
- <code class="literal">LINUX_DIR</code> contains the path to where the Linux kernel has been
- extracted and built.
- </li><li class="listitem">
- <code class="literal">LINUX_VERSION</code> contains the version string as configured by the user.
- </li><li class="listitem">
- <code class="literal">LINUX_VERSION_PROBED</code> contains the real version string of the kernel,
- retrieved with running <code class="literal">make -C $(LINUX_DIR) kernelrelease</code>
- </li><li class="listitem">
- <code class="literal">KERNEL_ARCH</code> contains the name of the current architecture, like <code class="literal">arm</code>,
- <code class="literal">mips</code>…
- </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
- using the <a class="ulink" href="http://asciidoc.org/" target="_top">AsciiDoc</a> mark-up syntax. The manual is then
- rendered to many formats:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- html
- </li><li class="listitem">
- split-html
- </li><li class="listitem">
- pdf
- </li><li class="listitem">
- epub
- </li><li class="listitem">
- text
- </li></ul></div><p>Although Buildroot only contains one document written in AsciiDoc, there
- is, as for packages, an infrastructure for rendering documents using the
- AsciiDoc syntax.</p><p>Also as for packages, the AsciiDoc infrastructure is available from a
- <a class="link" href="#outside-br-custom" title="9.2. Keeping customizations outside of Buildroot">br2-external tree</a>. This allows documentation for
- a br2-external tree to match the Buildroot documentation, as it will be
- 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
- infrastructures are suffixed with <code class="literal">-document</code>. So, the AsciiDoc infrastructure
- 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: ################################################################################
- 02: #
- 03: # foo-document
- 04: #
- 05: ################################################################################
- 06:
- 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
- 08: $(eval $(call asciidoc-document))</pre><p>On line 7, the Makefile declares what the sources of the document are.
- Currently, it is expected that the document’s sources are only local;
- Buildroot will not attempt to download anything to render a document.
- Thus, you must indicate where the sources are. Usually, the string
- 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
- 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
- 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">
- <code class="literal">FOO_SOURCES</code>, mandatory, defines the source files for the document.
- </li><li class="listitem">
- <code class="literal">FOO_RESOURCES</code>, optional, may contain a space-separated list of paths
- to one or more directories containing so-called resources (like CSS or
- images). By default, empty.
- </li><li class="listitem">
- <code class="literal">FOO_DEPENDENCIES</code>, optional, the list of packages (most probably,
- host-packages) that must be built before building this document.
- </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
- on hooks), that a document may set to define extra actions to be done at
- various steps:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">FOO_POST_RSYNC_HOOKS</code> to run additional commands after the sources
- have been copied by Buildroot. This can for example be used to
- generate part of the manual with information extracted from the
- tree. As an example, Buildroot uses this hook to generate the tables
- in the appendices.
- </li><li class="listitem">
- <code class="literal">FOO_CHECK_DEPENDENCIES_HOOKS</code> to run additional tests on required
- components to generate the document. In AsciiDoc, it is possible to
- call filters, that is, programs that will parse an AsciiDoc block and
- render it appropriately (e.g. <a class="ulink" href="http://ditaa.sourceforge.net/" target="_top">ditaa</a> or
- <a class="ulink" href="https://pythonhosted.org/aafigure/" target="_top">aafigure</a>).
- </li><li class="listitem">
- <code class="literal">FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS</code>, to run additional tests for
- the specified format <code class="literal"><FMT></code> (see the list of rendered formats, above).
- </li></ul></div><p>Here is a complete example that uses all variables and all hooks:</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # foo-document
- 04: #
- 05: ################################################################################
- 06:
- 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
- 08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
- 09:
- 10: define FOO_GEN_EXTRA_DOC
- 11: /path/to/generate-script --outdir=$(@D)
- 12: endef
- 13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
- 14:
- 15: define FOO_CHECK_MY_PROG
- 16: if ! which my-prog >/dev/null 2>&1; then \
- 17: echo "You need my-prog to generate the foo document"; \
- 18: exit 1; \
- 19: fi
- 20: endef
- 21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
- 22:
- 23: define FOO_CHECK_MY_OTHER_PROG
- 24: if ! which my-other-prog >/dev/null 2>&1; then \
- 25: echo "You need my-other-prog to generate the foo document as PDF"; \
- 26: exit 1; \
- 27: fi
- 28: endef
- 29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
- 30:
- 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
- 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
- for the target available within the Linux kernel sources. Since their
- source code is part of the kernel source code, a special package,
- <code class="literal">linux-tools</code>, exists and re-uses the sources of the Linux kernel that
- runs on the target.</p><p>Let’s look at an example of a Linux tool. For a new Linux tool named
- <code class="literal">foo</code>, create a new menu entry in the existing
- <code class="literal">package/linux-tools/Config.in</code>. This file will contain the option
- descriptions related to each kernel tool that will be used and
- displayed in the configuration tool. It would basically look like:</p><pre class="screen">01: config BR2_PACKAGE_LINUX_TOOLS_FOO
- 02: bool "foo"
- 03: select BR2_PACKAGE_LINUX_TOOLS
- 04: help
- 05: This is a comment that explains what foo kernel tool is.
- 06:
- 07: http://foosoftware.org/foo/</pre><p>The name of the option starts with the prefix <code class="literal">BR2_PACKAGE_LINUX_TOOLS_</code>,
- 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
- <code class="literal">linux</code> kernel menu, under the <code class="literal">Linux Kernel Tools</code> sub-menu, not under
- 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
- <code class="literal">package/linux-tools/linux-tool-foo.mk.in</code>. It would basically look like:</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # foo
- 04: #
- 05: ################################################################################
- 06:
- 07: LINUX_TOOLS += foo
- 08:
- 09: FOO_DEPENDENCIES = libbbb
- 10:
- 11: define FOO_BUILD_CMDS
- 12: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools foo
- 13: endef
- 14:
- 15: define FOO_INSTALL_STAGING_CMDS
- 16: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
- 17: DESTDIR=$(STAGING_DIR) \
- 18: foo_install
- 19: endef
- 20:
- 21: define FOO_INSTALL_TARGET_CMDS
- 22: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
- 23: DESTDIR=$(TARGET_DIR) \
- 24: foo_install
- 25: endef</pre><p>On line 7, we register the Linux tool <code class="literal">foo</code> to the list of available
- Linux tools.</p><p>On line 9, we specify the list of dependencies this tool relies on. These
- dependencies are added to the Linux package dependencies list only when the
- <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
- different steps of the Linux tool build process like for a
- <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
- used only when the <code class="literal">foo</code> tool is selected. The only supported commands are
- <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
- package infrastructure! Linux tools are not packages by themselves,
- 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
- to be modified. This can be in the form of patches to be applied on
- the kernel tree, or in the form of new files to be added to the
- tree. The Buildroot’s Linux kernel extensions infrastructure provides
- a simple solution to automatically do this, just after the kernel
- sources are extracted and before the kernel patches are
- applied. Examples of extensions packaged using this mechanism are the
- real-time extensions Xenomai and RTAI, as well as the set of
- 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
- package is a standard package; see the previous chapters on how to
- create such a package. This package is in charge of downloading the
- sources archive, checking the hash, defining the licence informations
- 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
- the existing <code class="literal">linux/Config.ext.in</code>. This file contains the option
- descriptions related to each kernel extension that will be used and
- displayed in the configuration tool. It would basically look like:</p><pre class="screen">01: config BR2_LINUX_KERNEL_EXT_FOO
- 02: bool "foo"
- 03: help
- 04: This is a comment that explains what foo kernel extension is.
- 05:
- 06: http://foosoftware.org/foo/</pre><p>Then for each linux extension, add a new <code class="literal">.mk</code> file named
- <code class="literal">linux/linux-ext-foo.mk</code>. It should basically contain:</p><pre class="screen">01: ################################################################################
- 02: #
- 03: # foo
- 04: #
- 05: ################################################################################
- 06:
- 07: LINUX_EXTENSIONS += foo
- 08:
- 09: define FOO_PREPARE_KERNEL
- 10: $(FOO_DIR)/prepare-kernel-tree.sh --linux-dir=$(@D)
- 11: endef</pre><p>On line 7, we add the Linux extension <code class="literal">foo</code> to the list of available
- Linux extensions.</p><p>On line 9-11, we define what should be done by the extension to modify
- the Linux kernel tree; this is specific to the linux extension and can
- use the variables defined by the <code class="literal">foo</code> package, like: <code class="literal">$(FOO_DIR)</code> or
- <code class="literal">$(FOO_VERSION)</code>… as well as all the Linux variables, like:
- <code class="literal">$(LINUX_VERSION)</code> or <code class="literal">$(LINUX_VERSION_PROBED)</code>, <code class="literal">$(KERNEL_ARCH)</code>…
- 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
- and cmake infrastructures) allow packages to specify hooks.
- These define further actions to perform after existing steps.
- Most hooks aren’t really useful for generic packages, since the <code class="literal">.mk</code>
- file already has full control over the actions performed in each step
- 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">
- <code class="literal">LIBFOO_PRE_DOWNLOAD_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_DOWNLOAD_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_PRE_EXTRACT_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_EXTRACT_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_PRE_RSYNC_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_RSYNC_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_PRE_PATCH_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_PATCH_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_PRE_CONFIGURE_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_CONFIGURE_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_PRE_BUILD_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_BUILD_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_PRE_INSTALL_HOOKS</code> (for host packages only)
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_INSTALL_HOOKS</code> (for host packages only)
- </li><li class="listitem">
- <code class="literal">LIBFOO_PRE_INSTALL_STAGING_HOOKS</code> (for target packages only)
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_INSTALL_STAGING_HOOKS</code> (for target packages only)
- </li><li class="listitem">
- <code class="literal">LIBFOO_PRE_INSTALL_TARGET_HOOKS</code> (for target packages only)
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_INSTALL_TARGET_HOOKS</code> (for target packages only)
- </li><li class="listitem">
- <code class="literal">LIBFOO_PRE_INSTALL_IMAGES_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_INSTALL_IMAGES_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_PRE_LEGAL_INFO_HOOKS</code>
- </li><li class="listitem">
- <code class="literal">LIBFOO_POST_LEGAL_INFO_HOOKS</code>
- </li></ul></div><p>These variables are <span class="emphasis"><em>lists</em></span> of variable names containing actions to be
- performed at this hook point. This allows several hooks to be
- registered at a given hook point. Here is an example:</p><pre class="screen">define LIBFOO_POST_PATCH_FIXUP
- action1
- action2
- endef
- 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,
- either through the <code class="literal">local</code> site method or the <code class="literal">OVERRIDE_SRCDIR</code>
- mechanism. In this case, package sources are copied using <code class="literal">rsync</code> from
- the local location into the buildroot build directory. The <code class="literal">rsync</code>
- command does not copy all files from the source directory, though.
- Files belonging to a version control system, like the directories
- <code class="literal">.git</code>, <code class="literal">.hg</code>, etc. are not copied. For most packages this is
- sufficient, but a given package can perform additional actions using
- the <code class="literal">POST_RSYNC</code> hook.</p><p>In principle, the hook can contain any command you want. One specific
- use case, though, is the intentional copying of the version control
- directory using <code class="literal">rsync</code>. The <code class="literal">rsync</code> command you use in the hook can, among
- others, use the following variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">$(SRCDIR)</code>: the path to the overridden source directory
- </li><li class="listitem">
- <code class="literal">$(@D)</code>: the path to the build directory
- </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>.
- These hooks are run after all packages are built, but before the
- filesystem images are generated. They are seldom used, and your
- 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
- library. Dependencies for this library are fairly complicated and
- therefore, deserve some explanation.</p><p>The <span class="emphasis"><em>glibc</em></span> C library integrates a full-blown implementation of
- <span class="emphasis"><em>gettext</em></span>, supporting translation. Native Language Support is
- 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
- stub implementation of the gettext functionality, which allows to
- compile libraries and programs using gettext functions, but without
- providing the translation capabilities of a full-blown gettext
- implementation. With such C libraries, if real Native Language Support
- is necessary, it can be provided by the <code class="literal">libintl</code> library of the
- <code class="literal">gettext</code> package.</p><p>Due to this, and in order to make sure that Native Language Support is
- properly handled, packages in Buildroot that can use NLS support
- should:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
- Ensure NLS support is enabled when <code class="literal">BR2_SYSTEM_ENABLE_NLS=y</code>. This
- is done automatically for <span class="emphasis"><em>autotools</em></span> packages and therefore should
- only be done for packages using other package infrastructures.
- </li><li class="listitem">
- Add <code class="literal">$(TARGET_NLS_DEPENDENCIES)</code> to the package
- <code class="literal"><pkg>_DEPENDENCIES</code> variable. This addition should be done
- unconditionally: the value of this variable is automatically
- adjusted by the core infrastructure to contain the relevant list of
- packages. If NLS support is disabled, this variable is empty. If
- NLS support is enabled, this variable contains <code class="literal">host-gettext</code> so
- that tools needed to compile translation files are available on the
- host. In addition, if <span class="emphasis"><em>uClibc</em></span> or <span class="emphasis"><em>musl</em></span> are used, this variable
- also contains <code class="literal">gettext</code> in order to get the full-blown <span class="emphasis"><em>gettext</em></span>
- implementation.
- </li><li class="listitem">
- If needed, add <code class="literal">$(TARGET_NLS_LIBS)</code> to the linker flags, so that
- the package gets linked with <code class="literal">libintl</code>. This is generally not
- needed with <span class="emphasis"><em>autotools</em></span> packages as they usually detect
- automatically that they should link with <code class="literal">libintl</code>. However,
- packages using other build systems, or problematic autotools-based
- packages may need this. <code class="literal">$(TARGET_NLS_LIBS)</code> should be added
- unconditionally to the linker flags, as the core automatically
- makes it empty or defined to <code class="literal">-lintl</code> depending on the
- configuration.
- </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,
- such as the <code class="literal">gettext</code> program itself, which allows to retrieve
- translated strings, from the command line. In such a case, the package
- should:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- use <code class="literal">select BR2_PACKAGE_GETTEXT</code> in their <code class="literal">Config.in</code> file,
- indicating in a comment above that it’s a runtime dependency only.
- </li><li class="listitem">
- not add any <code class="literal">gettext</code> dependency in the <code class="literal">DEPENDENCIES</code> variable of
- their <code class="literal">.mk</code> file.
- </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">
- the <span class="emphasis"><em>package name</em></span>, which is the package directory name (and the
- name of the <code class="literal">*.mk</code> file);
- </li><li class="listitem">
- the config entry name that is declared in the <code class="literal">Config.in</code> file;
- </li><li class="listitem">
- the makefile variable prefix.
- </li></ul></div><p>It is mandatory to maintain consistency between these elements,
- using the following rules:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- the package directory and the <code class="literal">*.mk</code> name are the <span class="emphasis"><em>package name</em></span>
- itself (e.g.: <code class="literal">package/foo-bar_boo/foo-bar_boo.mk</code>);
- </li><li class="listitem">
- the <span class="emphasis"><em>make</em></span> target name is the <span class="emphasis"><em>package name</em></span> itself (e.g.:
- <code class="literal">foo-bar_boo</code>);
- </li><li class="listitem">
- 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>
- characters substituted with <code class="literal">_</code>, prefixed with <code class="literal">BR2_PACKAGE_</code> (e.g.:
- <code class="literal">BR2_PACKAGE_FOO_BAR_BOO</code>);
- </li><li class="listitem">
- the <code class="literal">*.mk</code> file variable prefix is the upper case <span class="emphasis"><em>package name</em></span>
- with <code class="literal">.</code> and <code class="literal">-</code> characters substituted with <code class="literal">_</code> (e.g.:
- <code class="literal">FOO_BAR_BOO_VERSION</code>).
- </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
- changed files for coding style. It is not a complete language validator,
- but it catches many common mistakes. It is meant to run in the actual
- files you created or modified, before creating the patch for submission.</p><p>This script can be used for packages, filesystem makefiles, Config.in
- files, etc. It does not check the files defining the package
- 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
- 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/
- $ 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
- under various conditions: does it build for all architectures? Does it
- build with the different C libraries? Does it need threads, NPTL? And
- so on…</p><p>Buildroot runs <a class="ulink" href="http://autobuild.buildroot.org/" target="_top">autobuilders</a> which
- continuously test random configurations. However, these only build the
- <code class="literal">master</code> branch of the git tree, and your new fancy package is not yet
- there.</p><p>Buildroot provides a script in <code class="literal">utils/test-pkg</code> that uses the same base
- configurations as used by the autobuilders so you can test your package
- in the same conditions.</p><p>First, create a config snippet that contains all the necessary options
- needed to enable your package, but without any architecture or toolchain
- option. For example, let’s create a config snippet that just enables
- <code class="literal">libcurl</code>, without any TLS backend:</p><pre class="screen">$ cat libcurl.config
- BR2_PACKAGE_LIBCURL=y</pre><p>If your package needs more configuration options, you can add them to the
- config snippet. For example, here’s how you would test <code class="literal">libcurl</code> with
- <code class="literal">openssl</code> as a TLS backend and the <code class="literal">curl</code> program:</p><pre class="screen">$ cat libcurl.config
- BR2_PACKAGE_LIBCURL=y
- BR2_PACKAGE_LIBCURL_CURL=y
- BR2_PACKAGE_OPENSSL=y</pre><p>Then run the <code class="literal">test-pkg</code> script, by telling it what config snippet to use
- 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
- toolchains used by the autobuilders, which has been selected by the
- Buildroot developers as being the most useful and representative
- subset. If you want to test all toolchains, pass the <code class="literal">-a</code> option. Note
- that in any case, internal toolchains are excluded as they take too
- long to build.</p><p>The output lists all toolchains that are tested and the corresponding
- result (excerpt, results are fake):</p><pre class="screen">$ ./utils/test-pkg -c libcurl.config -p libcurl
- armv5-ctng-linux-gnueabi [ 1/11]: OK
- armv7-ctng-linux-gnueabihf [ 2/11]: OK
- br-aarch64-glibc [ 3/11]: SKIPPED
- br-arcle-hs38 [ 4/11]: SKIPPED
- br-arm-basic [ 5/11]: FAILED
- br-arm-cortex-a9-glibc [ 6/11]: OK
- br-arm-cortex-a9-musl [ 7/11]: FAILED
- br-arm-cortex-m4-full [ 8/11]: OK
- br-arm-full [ 9/11]: OK
- br-arm-full-nothread [10/11]: FAILED
- br-arm-full-static [11/11]: OK
- 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">
- <code class="literal">OK</code>: the build was successful.
- </li><li class="listitem">
- <code class="literal">SKIPPED</code>: one or more configuration options listed in the config
- snippet were not present in the final configuration. This is due to
- options having dependencies not satisfied by the toolchain, such as
- for example a package that <code class="literal">depends on BR2_USE_MMU</code> with a noMMU
- toolchain. The missing options are reported in <code class="literal">missing.config</code> in
- the output build directory (<code class="literal">~/br-test-pkg/TOOLCHAIN_NAME/</code> by
- default).
- </li><li class="listitem"><p class="simpara">
- <code class="literal">FAILED</code>: the build failed. Inspect the <code class="literal">logfile</code> file in the output
- build directory to see what went wrong:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- the actual build failed,
- </li><li class="listitem">
- the legal-info failed,
- </li><li class="listitem">
- one of the preliminary steps (downloading the config file, applying
- the configuration, running <code class="literal">dirclean</code> for the package) failed.
- </li></ul></div></li></ul></div><p>When there are failures, you can just re-run the script with the same
- options (after you fixed your package); the script will attempt to
- re-build the package specified with <code class="literal">-p</code> for all toolchains, without
- 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
- 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.
- However, it is possible to download tarballs directly from the repository
- on GitHub. As GitHub is known to have changed download mechanisms in the
- 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
- FOO_VERSION = v1.0
- FOO_SITE = $(call github,<user>,<package>,$(FOO_VERSION))</pre><div class="itemizedlist"><p class="title"><strong>Notes</strong></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- The FOO_VERSION can either be a tag or a commit ID.
- </li><li class="listitem">
- The tarball name generated by github matches the default one from
- Buildroot (e.g.: <code class="literal">foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz</code>),
- so it is not necessary to specify it in the <code class="literal">.mk</code> file.
- </li><li class="listitem">
- When using a commit ID as version, you should use the full 40 hex characters.
- </li></ul></div><p>If the package you wish to add does have a release section on GitHub, the
- maintainer may have uploaded a release tarball, or the release may just point
- to the automatically generated tarball from the git tag. If there is a
- release tarball uploaded by the maintainer, we prefer to use that since it
- may be slightly different (e.g. it contains a configure script so we don’t
- 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">
- If it looks like the image above then it was uploaded by the
- maintainer and you should use that link (in that example:
- <span class="emphasis"><em>mongrel2-v1.9.2.tar.bz2</em></span>) to specify <code class="literal">FOO_SITE</code>, and not use the
- <span class="emphasis"><em>github</em></span> helper.
- </li><li class="listitem">
- On the other hand, if there’s is <span class="strong"><strong>only</strong></span> the "Source code" link, then
- it’s an automatically generated tarball and you should use the
- <span class="emphasis"><em>github</em></span> helper function.
- </li></ul></div></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
- matter of writing a Makefile using an existing example and modifying it
- according to the compilation process required by the package.</p><p>If you package software that might be useful for other people, don’t
- forget to send a patch to the Buildroot mailing list (see
- <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
- necessary to patch the source of the software to get it cross-built within
- Buildroot.</p><p>Buildroot offers an infrastructure to automatically handle this during
- the builds. It supports three ways of applying patch sets: downloaded patches,
- patches supplied within buildroot and patches located in a user-defined
- 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
- to the <code class="literal"><packagename>_PATCH</code> variable. If an entry contains <code class="literal">://</code>,
- then Buildroot will assume it is a full URL and download the patch
- from this location. Otherwise, Buildroot will assume that the patch should be
- downloaded from <code class="literal"><packagename>_SITE</code>. It can be a single patch,
- or a tarball containing a patch series.</p><p>Like for all downloads, a hash should be added to the <code class="literal"><packagename>.hash</code>
- 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
- directory; these typically aim to fix cross-compilation, libc support,
- or other such issues.</p><p>These patch files should be named <code class="literal"><number>-<description>.patch</code>.</p><div class="itemizedlist"><p class="title"><strong>Notes</strong></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- The patch files coming with Buildroot should not contain any package version
- reference in their filename.
- </li><li class="listitem">
- The field <code class="literal"><number></code> in the patch file name refers to the <span class="emphasis"><em>apply order</em></span>,
- and shall start at 1; It is preferred to pad the number with zeros up to 4
- digits, like <span class="emphasis"><em>git-format-patch</em></span> does. E.g.: <code class="literal">0001-foobar-the-buz.patch</code>
- </li><li class="listitem">
- Previously, it was mandatory for patches to be prefixed with the name of
- the package, like <code class="literal"><package>-<number>-<description>.patch</code>, but that is
- no longer the case. Existing packages will be fixed as time passes. <span class="emphasis"><em>Do
- not prefix patches with the package name.</em></span>
- </li><li class="listitem">
- Previously, a <code class="literal">series</code> file, as used by <code class="literal">quilt</code>, could also be added in
- the package directory. In that case, the <code class="literal">series</code> file defines the patch
- application order. This is deprecated, and will be removed in the future.
- <span class="emphasis"><em>Do not use a series file.</em></span>
- </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
- used to specify a space separated list of one or more directories
- 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
- 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">
- Run the <code class="literal"><packagename>_PRE_PATCH_HOOKS</code> commands if defined;
- </li><li class="listitem">
- Cleanup the build directory, removing any existing <code class="literal">*.rej</code> files;
- </li><li class="listitem">
- If <code class="literal"><packagename>_PATCH</code> is defined, then patches from these
- tarballs are applied;
- </li><li class="listitem"><p class="simpara">
- If there are some <code class="literal">*.patch</code> files in the package’s Buildroot
- directory or in a package subdirectory named <code class="literal"><packageversion></code>,
- then:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- If a <code class="literal">series</code> file exists in the package directory, then patches are
- applied according to the <code class="literal">series</code> file;
- </li><li class="listitem">
- Otherwise, patch files matching <code class="literal">*.patch</code> are applied in alphabetical
- order.
- So, to ensure they are applied in the right order, it is highly
- recommended to name the patch files like this:
- <code class="literal"><number>-<description>.patch</code>, where <code class="literal"><number></code> refers to the
- <span class="emphasis"><em>apply order</em></span>.
- </li></ul></div></li><li class="listitem">
- If <code class="literal">BR2_GLOBAL_PATCH_DIR</code> is defined, the directories will be
- enumerated in the order they are specified. The patches are applied
- as described in the previous step.
- </li><li class="listitem">
- Run the <code class="literal"><packagename>_POST_PATCH_HOOKS</code> commands if defined.
- </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
- 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
- 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
- patch to help with keeping track of the changes and to certify that the
- 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
- upstream SCM software to generate the patch set.</p><p>Otherwise, concatenate the header with the output of the
- <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),
- make sure the existing From header and Signed-off-by tags are not
- 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
- Signed-off-by: John Doe <john.doe@noname.org>
- --- configure.ac.orig
- +++ configure.ac
- @@ -40,2 +40,12 @@
- AC_PROG_MAKE_SET
- +
- +AC_CACHE_CHECK([whether the C++ compiler works],
- + [rw_cv_prog_cxx_works],
- + [AC_LANG_PUSH([C++])
- + AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
- + [rw_cv_prog_cxx_works=yes],
- + [rw_cv_prog_cxx_works=no])
- + AC_LANG_POP([C++])])
- +
- +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
- add a few things in the header of the patch itself.</p><p>Depending on whether the patch has been obtained from the project
- repository itself, or from somewhere on the web, add one of the
- following tags:</p><pre class="screen">Backported from: <some commit id></pre><p>or</p><pre class="screen">Fetch from: <some url></pre><p>It is also sensible to add a few words about any changes to the patch
- 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
- packages. Define the variable <code class="literal">BR2_INSTRUMENTATION_SCRIPTS</code> to contain
- the path of one or more scripts (or other executables), in a
- space-separated list, you want called before and after each step. The
- scripts are called in sequence, with three parameters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">start</code> or <code class="literal">end</code> to denote the start (resp. the end) of a step;
- </li><li class="listitem">
- the name of the step about to be started, or which just ended;
- </li><li class="listitem">
- the name of the package.
- </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">
- <code class="literal">extract</code>
- </li><li class="listitem">
- <code class="literal">patch</code>
- </li><li class="listitem">
- <code class="literal">configure</code>
- </li><li class="listitem">
- <code class="literal">build</code>
- </li><li class="listitem">
- <code class="literal">install-host</code>, when a host-package is installed in <code class="literal">$(HOST_DIR)</code>
- </li><li class="listitem">
- <code class="literal">install-target</code>, when a target-package is installed in <code class="literal">$(TARGET_DIR)</code>
- </li><li class="listitem">
- <code class="literal">install-staging</code>, when a target-package is installed in <code class="literal">$(STAGING_DIR)</code>
- </li><li class="listitem">
- <code class="literal">install-image</code>, when a target-package installs files in <code class="literal">$(BINARIES_DIR)</code>
- </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">
- <code class="literal">BR2_CONFIG</code>: the path to the Buildroot .config file
- </li><li class="listitem">
- <code class="literal">HOST_DIR</code>, <code class="literal">STAGING_DIR</code>, <code class="literal">TARGET_DIR</code>: 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>
- </li><li class="listitem">
- <code class="literal">BUILD_DIR</code>: the directory where packages are extracted and built
- </li><li class="listitem">
- <code class="literal">BINARIES_DIR</code>: the place where all binary files (aka images) are
- stored
- </li><li class="listitem">
- <code class="literal">BASE_DIR</code>: the base output directory
- </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
- and fixing bugs, analyzing and fixing package build failures detected by
- the autobuilders, testing and reviewing patches sent by other
- developers, working on the items in our TODO list and sending your own
- improvements to Buildroot or its manual. The following sections give a
- little more detail on each of these items.</p><p>If you are interested in contributing to Buildroot, the first thing you
- should do is to subscribe to the Buildroot mailing list. This list is
- the main way of interacting with other Buildroot developers and to send
- contributions to. If you aren’t subscribed yet, then refer to
- <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
- git repository of Buildroot, rather than starting from an extracted
- source code tarball. Git is the easiest way to develop from and directly
- 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>
- 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
- the <a class="ulink" href="https://bugs.buildroot.org/buglist.cgi?product=buildroot" target="_top">Buildroot bug
- tracker</a>. As we strive to keep the bug count as small as possible, all
- help in reproducing, analyzing and fixing reported bugs is more than
- welcome. Don’t hesitate to add a comment to bug reports reporting your
- 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
- run Buildroot builds based on random configurations. This is done for
- all architectures supported by Buildroot, with various toolchains, and
- with a random selection of packages. With the large commit activity on
- Buildroot, these autobuilders are a great help in detecting problems
- 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>,
- statistics are at <a class="ulink" href="http://autobuild.buildroot.org/stats.php" target="_top">http://autobuild.buildroot.org/stats.php</a>. Every day,
- 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
- fixed as well. Your contribution is very welcome here! There are
- basically two things that can be done:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Analyzing the problems. The daily summary mails do not contain details
- about the actual failures: in order to see what’s going on you have to
- open the build log and check the last output. Having someone doing
- this for all packages in the mail is very useful for other developers,
- as they can make a quick initial analysis based on this output alone.
- </li><li class="listitem"><p class="simpara">
- Fixing a problem. When fixing autobuild failures, you should follow
- these steps:
- </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
- Check if you can reproduce the problem by building with the same
- configuration. You can do this manually, or use the
- <a class="ulink" href="http://git.buildroot.org/buildroot-test/tree/utils/br-reproduce-build" target="_top">br-reproduce-build</a>
- script that will automatically clone a Buildroot git repository,
- checkout the correct revision, download and set the right
- configuration, and start the build.
- </li><li class="listitem">
- Analyze the problem and create a fix.
- </li><li class="listitem">
- Verify that the problem is really fixed by starting from a clean
- Buildroot tree and only applying your fix.
- </li><li class="listitem">
- Send the fix to the Buildroot mailing list (see
- <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
- package sources, you should also send the patch upstream so that the
- problem will be fixed in a later release, and the patch in Buildroot
- can be removed.
- In the commit message of a patch fixing an autobuild failure, add a
- reference to the build result directory, as follows:
- </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
- maintainer has a very hard job to judge which patches are ready to apply
- and which ones aren’t. Contributors can greatly help here by reviewing
- and testing these patches.</p><p>In the review process, do not hesitate to respond to patch submissions
- for remarks, suggestions or anything that will help everyone to
- understand the patches and make them better. Please use internet
- style replies in plain text emails when responding to patch
- submissions.</p><p>To indicate approval of a patch, there are three formal tags that keep
- track of this approval. To add your tag to a patch, reply to it with the
- approval tag below the original author’s Signed-off-by line. These tags
- will be picked up automatically by patchwork (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>) and will be part of the commit log when
- the patch is accepted.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
- Tested-by
- </span></dt><dd>
- Indicates that the patch has been tested successfully.
- You are encouraged to specify what kind of testing you performed
- (compile-test on architecture X and Y, runtime test on target A,
- …). This additional information helps other testers and the
- maintainer.
- </dd><dt><span class="term">
- Reviewed-by
- </span></dt><dd>
- Indicates that you code-reviewed the patch and did your
- best in spotting problems, but you are not sufficiently familiar with
- the area touched to provide an Acked-by tag. This means that there
- may be remaining problems in the patch that would be spotted by
- someone with more experience in that area. Should such problems be
- detected, your Reviewed-by tag remains appropriate and you cannot
- be blamed.
- </dd><dt><span class="term">
- Acked-by
- </span></dt><dd>
- Indicates that you code-reviewed the patch and you are
- familiar enough with the area touched to feel that the patch can be
- committed as-is (no additional changes required). In case it later
- turns out that something is wrong with the patch, your Acked-by could
- be considered inappropriate. The difference between Acked-by and
- Reviewed-by is thus mainly that you are prepared to take the blame on
- Acked patches, but not on Reviewed ones.
- </dd></dl></div><p>If you reviewed a patch and have comments on it, you should simply reply
- to the patch stating these comments, without providing a Reviewed-by or
- Acked-by tag. These tags should only be provided if you judge the patch
- to be good as it is.</p><p>It is important to note that neither Reviewed-by nor Acked-by imply
- that testing has been performed. To indicate that you both reviewed and
- tested the patch, provide two separate tags (Reviewed/Acked-by and
- Tested-by).</p><p>Note also that <span class="emphasis"><em>any developer</em></span> can provide Tested/Reviewed/Acked-by
- tags, without exception, and we encourage everyone to do this. Buildroot
- does not have a defined group of <span class="emphasis"><em>core</em></span> developers, it just so happens
- that some developers are more active than others. The maintainer will
- value tags according to the track record of their submitter. Tags
- provided by a regular contributor will naturally be trusted more than
- tags provided by a newcomer. As you provide tags more regularly, your
- <span class="emphasis"><em>trustworthiness</em></span> (in the eyes of the maintainer) will go up, but <span class="emphasis"><em>any</em></span>
- tag provided is valuable.</p><p>Buildroot’s Patchwork website can be used to pull in patches for testing
- 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
- 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
- pulling in patches into their local git repository for testing
- purposes.</p><p>When browsing patches in the patchwork management interface, an <code class="literal">mbox</code>
- link is provided at the top of the page. Copy this link address and
- run the following commands:</p><pre class="screen">$ git checkout -b <test-branch-name>
- $ wget -O - <mbox-url> | git am</pre><p>Another option for applying patches is to create a bundle. A bundle is
- a set of patches that you can group together using the patchwork
- interface. Once the bundle is created and the bundle is made public,
- you can copy the <code class="literal">mbox</code> link for the bundle and apply the bundle
- 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,
- and you don’t like any of the above topics, you can always work on items
- from the <a class="ulink" href="http://elinux.org/Buildroot#Todo_list" target="_top">Buildroot TODO list</a>.
- Don’t hesitate to discuss an item first on the mailing list or on IRC.
- Do edit the wiki to indicate when you start working on an item, so we
- 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
- instead</em></span>.</p></div><p>If you made some changes to Buildroot and you would like to contribute
- 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
- to make it easy to review patches, to be able to apply them easily to
- the git repository, to make it easy to find back in the history how
- and why things have changed, and to make it possible to use <code class="literal">git
- bisect</code> to locate the origin of a problem.</p><p>First of all, it is essential that the patch has a good commit
- message. The commit message should start with a separate line with a
- brief summary of the change, prefixed by the area touched by the
- patch. A few examples of good commit titles:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- <code class="literal">package/linuxptp: bump version to 2.0</code>
- </li><li class="listitem">
- <code class="literal">configs/imx23evk: bump Linux version to 4.19</code>
- </li><li class="listitem">
- <code class="literal">package/pkg-generic: postpone evaluation of dependency conditions</code>
- </li><li class="listitem">
- <code class="literal">boot/uboot: needs host-{flex,bison}</code>
- </li><li class="listitem">
- <code class="literal">support/testing: add python-ubjson tests</code>
- </li></ul></div><p>The description that follows the prefix should start with a lower case
- 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
- change is needed, and if necessary also give details about <span class="emphasis"><em>how</em></span> it
- was done. When writing the commit message, think of how the reviewers
- will read it, but also think about how you will read it when you look
- at this change again a few years down the line.</p><p>Third, the patch itself should do only one change, but do it
- completely. Two unrelated or weakly related changes should usually be
- done in two separate patches. This usually means that a patch affects
- only a single package. If several changes are related, it is often
- still possible to split them up in small patches and apply them in a
- specific order. Small patches make it easier to review, and often
- make it easier to understand afterwards why a change was done.
- However, each patch must be complete. It is not allowed that the
- build is broken when only the first but not the second patch is
- 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
- back and forth between packages, and certainly not committing things
- immediately in a way that is clean enough for submission. So most
- developers rewrite the history of commits to produce a clean set of
- commits that is appropriate for submission. To do this, you need to
- use <span class="emphasis"><em>interactive rebasing</em></span>. You can learn about it
- <a class="ulink" href="https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History" target="_top">in the Pro
- Git book</a>. Sometimes, it is even easier to discard you history with
- <code class="literal">git reset --soft origin/master</code> and select individual changes with
- <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
- <code class="literal">Signed-off-by: Your Real Name <<a class="ulink" href="mailto:your@email.address" target="_top">your@email.address</a>></code> at the end of the
- commit message. <code class="literal">git commit -s</code> does that for you, if configured
- properly. The <code class="literal">Signed-off-by</code> tag means that you publish the patch
- under the Buildroot license (i.e. GPL-2.0+, except for package patches,
- which have the upstream license), and that you are allowed to do so.
- See <a class="ulink" href="http://developercertificate.org/" target="_top">the Developer Certificate of
- Origin</a> for details.</p><p>When adding new packages, you should submit every package in a
- separate patch. This patch should have the update to
- <code class="literal">package/Config.in</code>, the package <code class="literal">Config.in</code> file, the <code class="literal">.mk</code> file, the
- <code class="literal">.hash</code> file, any init script, and all package patches. If the package
- has many sub-options, these are sometimes better added as separate
- follow-up patches. The summary line should be something like
- <code class="literal"><packagename>: new package</code>. The body of the commit message can be
- empty for simple packages, or it can contain the description of the
- package (like the Config.in help text). If anything special has to be
- done to build the package, this should also be explained explicitly in
- the commit message body.</p><p>When you bump a package to a new version, you should also submit a
- separate patch for each package. Don’t forget to update the <code class="literal">.hash</code>
- file, or add it if it doesn’t exist yet. Also don’t forget to check if
- the <code class="literal">_LICENSE</code> and <code class="literal">_LICENSE_FILES</code> are still valid. The summary line
- should be something like <code class="literal"><packagename>: bump to version <new
- version></code>. If the new version only contains security updates compared
- to the existing one, the summary should be <code class="literal"><packagename>: security
- bump to version <new version></code> and the commit message body should show
- the CVE numbers that are fixed. If some package patches can be removed
- in the new version, it should be explained explicitly why they can be
- removed, preferably with the upstream commit ID. Also any other
- required changes should be explained explicitly, like configure
- options that no longer exist or are no longer needed.</p><p>If you are interested in getting notified of build failures and of
- further changes in the packages you added or modified, please add
- yourself to the DEVELOPERS file. This should be done in the same patch
- creating or modifying the package. See <a class="link" href="#DEVELOPERS" title="Chapter 23. DEVELOPERS file and get-developers">the DEVELOPERS file</a>
- for more information.</p><p>Buildroot provides a handy tool to check for common coding style
- mistakes on files you created or modified, called <code class="literal">check-package</code> (see
- <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>
- your development branch on top of the upstream tree before generating
- a patch set. To do so, run:</p><pre class="screen">$ git fetch --all --tags
- $ 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,
- 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
- before submitting them, using your favorite text editor.</p><p>Buildroot provides a handy tool to know to whom your patches should be
- 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
- information). This tool reads your patches and outputs the appropriate
- <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
- <code class="literal">--cc-cmd</code> argument to <code class="literal">git send-email</code> to automatically CC the
- affected developers:</p><pre class="screen">$ git send-email --to buildroot@buildroot.org \
- --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
- $ 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.
- 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
- line-wrapped</strong></span>, otherwise they cannot easily be applied. In such a case,
- 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
- <code class="literal">--cover-letter</code> to the <code class="literal">git format-patch</code> command (see <code class="literal">man
- git-format-patch</code> for further information). This will generate a
- 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
- in the following cases:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- large number of commits in the series;
- </li><li class="listitem">
- deep impact of the changes in the rest of the project;
- </li><li class="listitem">
- RFC <a href="#ftn.idm5691" class="footnote" id="idm5691"><sup class="footnote">[4]</sup></a>;
- </li><li class="listitem">
- whenever you feel it will help presenting your work, your choices,
- the review process, etc.
- </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
- master branch first. The commit log for such a patch may then contain a
- post-commit note specifying what branches are affected:</p><pre class="screen">package/foo: fix stuff
- Signed-off-by: Your Real Name <your@email.address>
- ---
- Backport to: 2020.02.x, 2020.05.x
- (2020.08.x not affected as the version was bumped)</pre><p>Those changes will then be backported by a maintainer to the affected
- branches.</p><p>However, some bugs may apply only to a specific release, for example
- because it is using an older version of a package. In that case, patches
- should be based off the maintenance branch, and the patch subject prefix
- must include the maintenance branch name (for example "[PATCH 2020.02.x]").
- 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" \
- -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
- should include a changelog of the modifications between each
- submission. Note that when your patch series is introduced by a cover
- letter, an overall changelog may be added to the cover letter in
- addition to the changelog in the individual commits.
- The best thing to rework a patch series is by interactive rebasing:
- <code class="literal">git rebase -i origin/master</code>. Consult the git manual for more
- information.</p><p>When added to the individual commits, this changelog is added when
- editing the commit message. Below the <code class="literal">Signed-off-by</code> section, add
- <code class="literal">---</code> and your changelog.</p><p>Although the changelog will be visible for the reviewers in the mail
- thread, as well as in <a class="ulink" href="http://patchwork.buildroot.org" target="_top">patchwork</a>, <code class="literal">git</code>
- will automatically ignores lines below <code class="literal">---</code> when the patch will be
- merged. This is the intended behavior: the changelog is not meant to
- 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
- A paragraph that explains the problem, and how it manifests itself. If
- the problem is complex, it is OK to add more paragraphs. All paragraphs
- should be wrapped at 72 characters.
- A paragraph that explains the root cause of the problem. Again, more
- than one paragraph is OK.
- Finally, one or more paragraphs that explain how the problem is solved.
- Don't hesitate to explain complex solutions in detail.
- Signed-off-by: John DOE <john.doe@example.net>
- ---
- Changes v2 -> v3:
- - foo bar (suggested by Jane)
- - bar buz
- Changes v1 -> v2:
- - alpha bravo (suggested by John)
- - charly delta</pre><p>Any patch revision should include the version number. The version number
- is simply composed of the letter <code class="literal">v</code> followed by an <code class="literal">integer</code> greater or
- 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
- <code class="literal">--subject-prefix</code>:</p><pre class="screen">$ git format-patch --subject-prefix "PATCH v4" \
- -M -s -o outgoing origin/master</pre><p>Since git version 1.8.1, you can also use <code class="literal">-v <n></code> (where <n> is the
- 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
- superseded in <a class="ulink" href="http://patchwork.buildroot.org" target="_top">patchwork</a>. You need to
- create an account on <a class="ulink" href="http://patchwork.buildroot.org" target="_top">patchwork</a> to be
- able to modify the status of your patches. Note that you can only change
- the status of patches you submitted yourself, which means the email
- address you register in <a class="ulink" href="http://patchwork.buildroot.org" target="_top">patchwork</a> should
- 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 <message-id></code> option when
- submitting a patch to the mailing list. The id of the mail to reply to
- can be found under the "Message Id" tag on
- <a class="ulink" href="http://patchwork.buildroot.org" target="_top">patchwork</a>. The advantage of
- <span class="strong"><strong>in-reply-to</strong></span> is that patchwork will automatically mark the previous
- 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
- <a class="link" href="#community-resources" title="Chapter 5. Community resources">the mailing list archive</a> whether someone has
- already reported and/or fixed a similar problem.</p><p>However you choose to report bugs or get help, either by
- opening a bug in the <a class="link" href="#community-resources" title="Chapter 5. Community resources">bug tracker</a> or by
- <a class="link" href="#community-resources" title="Chapter 5. Community resources">sending a mail to the mailing list</a>, there are
- a number of details to provide in order to help people reproduce and
- find a solution to the issue.</p><p>Try to think as if you were trying to help someone else; in
- 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">
- host machine (OS/release)
- </li><li class="listitem">
- version of Buildroot
- </li><li class="listitem">
- target for which the build fails
- </li><li class="listitem">
- package(s) for which the build fails
- </li><li class="listitem">
- the command that fails and its output
- </li><li class="listitem">
- any information you think that may be relevant
- </li></ul></div><p>Additionally, you should add the <code class="literal">.config</code> file (or if you know how, a
- <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
- pastebin service. Note that not all available pastebin services will
- preserve Unix-style line terminators when downloading raw pastes.
- Following pastebin services are known to work correctly:
- - <a class="ulink" href="https://gist.github.com/" target="_top">https://gist.github.com/</a>
- - <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
- upon Python scripting and QEMU runtime execution. There are two types of
- test cases within the framework, one for build time tests and another for
- run-time tests that have a QEMU dependency. The goals of the framework are
- the following:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- build a well defined configuration
- </li><li class="listitem">
- optionally, verify some properties of the build output
- </li><li class="listitem"><p class="simpara">
- if it is a run-time test:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- boot it under QEMU
- </li><li class="listitem">
- run some test condition to verify that a given feature is working
- </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>
- description. Some common options include setting the download folder, the
- output folder, keeping build output, and for multiple test cases, you can set
- 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">
- For a first step, let us see what all the test case options are. The test
- cases can be listed by executing <code class="literal">support/testing/run-tests -l</code>. These tests
- can all be run individually during test development from the console. Both
- one at a time and selectively as a group of a subset of tests.
- </li></ul></div><pre class="screen">$ support/testing/run-tests -l
- List of tests
- test_run (tests.utils.test_check_package.TestCheckPackage)
- Test the various ways the script can be called in a simple top to ... ok
- test_run (tests.toolchain.test_external.TestExternalToolchainBuildrootMusl) ... ok
- test_run (tests.toolchain.test_external.TestExternalToolchainBuildrootuClibc) ... ok
- test_run (tests.toolchain.test_external.TestExternalToolchainCCache) ... ok
- test_run (tests.toolchain.test_external.TestExternalToolchainCtngMusl) ... ok
- test_run (tests.toolchain.test_external.TestExternalToolchainLinaroArm) ... ok
- test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv4) ... ok
- test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv5) ... ok
- test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv7) ... ok
- [snip]
- test_run (tests.init.test_systemd.TestInitSystemSystemdRoFull) ... ok
- test_run (tests.init.test_systemd.TestInitSystemSystemdRoIfupdown) ... ok
- test_run (tests.init.test_systemd.TestInitSystemSystemdRoNetworkd) ... ok
- test_run (tests.init.test_systemd.TestInitSystemSystemdRwFull) ... ok
- test_run (tests.init.test_systemd.TestInitSystemSystemdRwIfupdown) ... ok
- test_run (tests.init.test_systemd.TestInitSystemSystemdRwNetworkd) ... ok
- test_run (tests.init.test_busybox.TestInitSystemBusyboxRo) ... ok
- test_run (tests.init.test_busybox.TestInitSystemBusyboxRoNet) ... ok
- test_run (tests.init.test_busybox.TestInitSystemBusyboxRw) ... ok
- test_run (tests.init.test_busybox.TestInitSystemBusyboxRwNet) ... ok
- Ran 157 tests in 0.021s
- OK</pre><p>Those runtime tests are regularly executed by Buildroot Gitlab CI
- 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
- few of the basic file system <code class="literal">support/testing/tests/fs/</code> and init
- <code class="literal">support/testing/tests/init/</code> test scripts. Those tests give good examples
- of a basic build and build with run type of tests. There are other more
- advanced cases that use things like nested <code class="literal">br2-external</code> folders to provide
- skeletons and additional packages.</p><p>The test cases by default use a br-arm-full-* uClibc-ng toolchain and the
- prebuild kernel for a armv5/7 cpu. It is recommended to use the default
- defconfig test configuration except when Glibc/musl or a newer kernel are
- necessary. By using the default it saves build time and the test would
- automatically inherit a kernel/std library upgrade when the default is
- updated.</p><p>The basic test case definition involves</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Creation of a new test file
- </li><li class="listitem">
- Defining a unique test class
- </li><li class="listitem">
- Determining if the default defconfig plus test options can be used
- </li><li class="listitem">
- Implementing a <code class="literal">def test_run(self):</code> function to optionally startup the
- emulator and provide test case conditions.
- </li></ul></div><p>After creating the test script, add yourself to the <code class="literal">DEVELOPERS</code> file to
- 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
- 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>.
- All the test cases live under the <code class="literal">test</code> folder and are organized in various
- 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">
- Using the Busybox Init system test case with a read/write rootfs
- <code class="literal">tests.init.test_busybox.TestInitSystemBusyboxRw</code>
- </li><li class="listitem">
- A minimal set of command line arguments when debugging a test case would
- 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
- <span class="emphasis"><em>-k</em></span> to keep any output on both pass/fail. With those options, the test will
- retain logging and build artifacts providing status of the build and
- execution of the test case.
- </li></ul></div><pre class="screen">$ support/testing/run-tests -d dl -o output_folder -k tests.init.test_busybox.TestInitSystemBusyboxRw
- 15:03:26 TestInitSystemBusyboxRw Starting
- 15:03:28 TestInitSystemBusyboxRw Building
- 15:08:18 TestInitSystemBusyboxRw Building done
- 15:08:27 TestInitSystemBusyboxRw Cleaning up
- .
- Ran 1 test in 301.140s
- OK</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- For the case of a successful build, the <code class="literal">output_folder</code> would contain a
- <test name> folder with the Buildroot build, build log and run-time log. If
- the build failed, the console output would show the stage at which it failed
- (setup / build / run). Depending on the failure stage, the build/run logs
- and/or Buildroot build artifacts can be inspected and instrumented. If the
- QEMU instance needs to be launched for additional testing, the first few
- lines of the run-time log capture it and it would allow some incremental
- testing without re-running <code class="literal">support/testing/run-tests</code>.
- </li><li class="listitem">
- You can also make modifications to the current sources inside the
- <code class="literal">output_folder</code> (e.g. for debug purposes) and rerun the standard
- Buildroot make targets (in order to regenerate the complete image with
- the new modifications) and then rerun the test. Modifying the sources
- directly can speed up debugging compared to adding patch files, wiping the
- output directoy, and starting the test again.
- </li></ul></div><pre class="screen">$ ls output_folder/
- TestInitSystemBusyboxRw/
- TestInitSystemBusyboxRw-build.log
- TestInitSystemBusyboxRw-run.log</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- The source file used to implement this example test is found under
- <code class="literal">support/testing/tests/init/test_busybox.py</code>. This file outlines the
- minimal defconfig that creates the build, QEMU configuration to launch
- the built images and the test case assertions.
- </li></ul></div><p>To test an existing or new test case within Gitlab CI, there is a method of
- invoking a specific test by creating a Buildroot fork in Gitlab under your
- account. This can be handy when adding/changing a run-time test or fixing a
- bug on a use case tested by a run-time test case.</p><p>In the examples below, the <name> component of the branch name is a unique
- 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">
- to trigger all run-test test case jobs:
- </li></ul></div><pre class="screen"> $ git push gitlab HEAD:<name>-runtime-tests</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- to trigger one test case job, a specific branch naming string is used that
- includes the full test case name.
- </li></ul></div><pre class="screen"> $ git push gitlab HEAD:<name>-<test case name></pre></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm5691" class="footnote"><p><a href="#idm5691" 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
- lists the developers involved with various areas of Buildroot. Thanks
- 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">
- Calculate the list of developers to whom patches should be sent, by
- parsing the patches and matching the modified files with the
- relevant developers. See <a class="xref" href="#submitting-patches" title="22.5. Submitting patches">Section 22.5, “Submitting patches”</a> for details.
- </li><li class="listitem">
- Find which developers are taking care of a given architecture or
- package, so that they can be notified when a build failure occurs on
- this architecture or package. This is done in interaction with
- Buildroot’s autobuild infrastructure.
- </li></ul></div><p>We ask developers adding new packages, new boards, or generally new
- functionality in Buildroot, to register themselves in the <code class="literal">DEVELOPERS</code>
- file. As an example, we expect a developer contributing a new package
- to include in his patch the appropriate modification to the
- <code class="literal">DEVELOPERS</code> file.</p><p>The <code class="literal">DEVELOPERS</code> file format is documented in detail inside the file
- itself.</p><p>The <code class="literal">get-developers</code> tool, located in <code class="literal">utils/</code> allows to use
- 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">
- When passing one or several patches as command line argument,
- <code class="literal">get-developers</code> will return the appropriate <code class="literal">git send-email</code>
- command. If the <code class="literal">-e</code> option is passed, only the email addresses are
- printed in a format suitable for <code class="literal">git send-email --cc-cmd</code>.
- </li><li class="listitem">
- When using the <code class="literal">-a <arch></code> command line option, <code class="literal">get-developers</code> will
- return the list of developers in charge of the given architecture.
- </li><li class="listitem">
- When using the <code class="literal">-p <package></code> command line option, <code class="literal">get-developers</code>
- will return the list of developers in charge of the given package.
- </li><li class="listitem">
- When using the <code class="literal">-c</code> command line option, <code class="literal">get-developers</code> will look
- at all files under version control in the Buildroot repository, and
- list the ones that are not handled by any developer. The purpose of
- this option is to help completing the <code class="literal">DEVELOPERS</code> file.
- </li><li class="listitem">
- When using without any arguments, it validates the integrity of the
- DEVELOPERS file and will note WARNINGS for items that don’t match.
- </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
- releases. The first release of each year is a long term support
- release, LTS.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
- Quarterly releases: 2020.02, 2020.05, 2020.08, and 2020.11
- </li><li class="listitem">
- Bugfix releases: 2020.02.1, 2020.02.2, …
- </li><li class="listitem">
- LTS releases: 2020.02, 2021.02, …
- </li></ul></div><p>Releases are supported until the first bugfix release of the next
- 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
- 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>
- branch and one month stabilization before the release is made. During
- 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
- the release, another release candidate is tagged.</p><p>To handle new features and version bumps during the stabilization phase,
- a <code class="literal">next</code> branch may be created for these features. Once the current
- release has been made, the <code class="literal">next</code> branch is merged into <code class="literal">master</code> and
- 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
- define changes to be made for permissions, or which device files to
- 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
- 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
- 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">
- <code class="literal">name</code> is the path to the file you want to create/modify
- </li><li class="listitem"><p class="simpara">
- <code class="literal">type</code> is the type of the file, being one of:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
- f: a regular file
- </li><li class="listitem">
- d: a directory
- </li><li class="listitem">
- r: a directory recursively
- </li><li class="listitem">
- c: a character device file
- </li><li class="listitem">
- b: a block device file
- </li><li class="listitem">
- p: a named pipe
- </li></ul></div></li><li class="listitem">
- <code class="literal">mode</code> are the usual permissions settings (only numerical values
- are allowed)
- </li><li class="listitem">
- <code class="literal">uid</code> and <code class="literal">gid</code> are the UID and GID to set on this file; can be
- either numerical values or actual names
- </li><li class="listitem">
- <code class="literal">major</code> and <code class="literal">minor</code> are here for device files, set to <code class="literal">-</code> for other
- files
- </li><li class="listitem">
- <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
- of files, and can be reduced to a loop, beginning at <code class="literal">start</code>,
- incrementing its counter by <code class="literal">inc</code> until it reaches <code class="literal">count</code>
- </li></ul></div><p>Let’s say you want to change the permissions of a given file; using
- this syntax, you will need to write:</p><pre class="screen">/usr/bin/foo f 755 0 0 - - - - -
- /usr/bin/bar f 755 root root - - - - -
- /data/buz f 644 buz-user buz-group - - - - -</pre><p>Alternatively, if you want to change owner/permission of a directory
- recursively, you can write (to set UID to foo, GID to bar and access
- rights to rwxr-x--- for the directory /usr/share/myapp and all files
- 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>
- and the corresponding 15 files for the partitions, you will need for
- <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
- <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
- <code class="literal">BR2_ROOTFS_DEVICE_TABLE_SUPPORTS_EXTENDED_ATTRIBUTES</code> is enabled.
- This is done by adding a line starting with <code class="literal">|xattr</code> after
- the line describing the file. Right now, only capability
- 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">
- <code class="literal">|xattr</code> is a "flag" that indicate an extended attribute
- </li><li class="listitem">
- <code class="literal">capability</code> is a capability to add to the previous file
- </li></ul></div><p>If you want to add the capability cap_sys_admin to the binary foo,
- you will write :</p><pre class="screen">/usr/bin/foo f 755 root root - - - - -
- |xattr cap_sys_admin+eip</pre><p>You can add several capabilities to a file by using several <code class="literal">|xattr</code> lines.
- If you want to add the capability cap_sys_admin and cap_net_admin to the
- binary foo, you will write :</p><pre class="screen">/usr/bin/foo f 755 root root - - - - -
- |xattr cap_sys_admin+eip
- |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
- is specific to Buildroot.</p><p>The syntax for adding a user is a space-separated list of fields, one
- 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">
- <code class="literal">username</code> is the desired user name (aka login name) for the user.
- It can not be <code class="literal">root</code>, and must be unique. If set to <code class="literal">-</code>, then just a
- group will be created.
- </li><li class="listitem">
- <code class="literal">uid</code> is the desired UID for the user. It must be unique, and not
- <code class="literal">0</code>. If set to <code class="literal">-1</code>, then a unique UID will be computed by Buildroot
- in the range [1000…1999]
- </li><li class="listitem">
- <code class="literal">group</code> is the desired name for the user’s main group. It can not
- be <code class="literal">root</code>. If the group does not exist, it will be created.
- </li><li class="listitem">
- <code class="literal">gid</code> is the desired GID for the user’s main group. It must be unique,
- and not <code class="literal">0</code>. If set to <code class="literal">-1</code>, and the group does not already exist, then
- a unique GID will be computed by Buildroot in the range [1000..1999]
- </li><li class="listitem">
- <code class="literal">password</code> is the crypt(3)-encoded password. If prefixed with <code class="literal">!</code>,
- then login is disabled. If prefixed with <code class="literal">=</code>, then it is interpreted
- as clear-text, and will be crypt-encoded (using MD5). If prefixed with
- <code class="literal">!=</code>, then the password will be crypt-encoded (using MD5) and login
- will be disabled. If set to <code class="literal">*</code>, then login is not allowed. If set to
- <code class="literal">-</code>, then no password value will be set.
- </li><li class="listitem">
- <code class="literal">home</code> is the desired home directory for the user. If set to <span class="emphasis"><em>-</em></span>, no
- home directory will be created, and the user’s home will be <code class="literal">/</code>.
- Explicitly setting <code class="literal">home</code> to <code class="literal">/</code> is not allowed.
- </li><li class="listitem">
- <code class="literal">shell</code> is the desired shell for the user. If set to <code class="literal">-</code>, then
- <code class="literal">/bin/false</code> is set as the user’s shell.
- </li><li class="listitem">
- <code class="literal">groups</code> is the comma-separated list of additional groups the user
- should be part of. If set to <code class="literal">-</code>, then the user will be a member of
- no additional group. Missing groups will be created with an arbitrary
- <code class="literal">gid</code>.
- </li><li class="listitem">
- <code class="literal">comment</code> (aka <a class="ulink" href="https://en.wikipedia.org/wiki/Gecos_field" target="_top">GECOS</a>
- field) is an almost-free-form text.
- </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">
- except for <code class="literal">comment</code>, all fields are mandatory.
- </li><li class="listitem">
- except for <code class="literal">comment</code>, fields may not contain spaces.
- </li><li class="listitem">
- no field may contain a colon (<code class="literal">:</code>).
- </li></ul></div><p>If <code class="literal">home</code> is not <code class="literal">-</code>, then the home directory, and all files below,
- 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">
- <code class="literal">username</code> (aka login name) is: <code class="literal">foo</code>
- </li><li class="listitem">
- <code class="literal">uid</code> is computed by Buildroot
- </li><li class="listitem">
- main <code class="literal">group</code> is: <code class="literal">bar</code>
- </li><li class="listitem">
- main group <code class="literal">gid</code> is computed by Buildroot
- </li><li class="listitem">
- clear-text <code class="literal">password</code> is: <code class="literal">blabla</code>, will be crypt(3)-encoded, and login is disabled.
- </li><li class="listitem">
- <code class="literal">home</code> is: <code class="literal">/home/foo</code>
- </li><li class="listitem">
- <code class="literal">shell</code> is: <code class="literal">/bin/sh</code>
- </li><li class="listitem">
- <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>
- </li><li class="listitem">
- <code class="literal">comment</code> is: <code class="literal">Foo user</code>
- </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">
- <code class="literal">username</code> (aka login name) is: <code class="literal">test</code>
- </li><li class="listitem">
- <code class="literal">uid</code> is : <code class="literal">8000</code>
- </li><li class="listitem">
- main <code class="literal">group</code> is: <code class="literal">wheel</code>
- </li><li class="listitem">
- main group <code class="literal">gid</code> is computed by Buildroot, and will use the value defined in the rootfs skeleton
- </li><li class="listitem">
- <code class="literal">password</code> is empty (aka no password).
- </li><li class="listitem">
- <code class="literal">home</code> is <code class="literal">/</code> but will not belong to <code class="literal">test</code>
- </li><li class="listitem">
- <code class="literal">shell</code> is: <code class="literal">/bin/sh</code>
- </li><li class="listitem">
- <code class="literal">test</code> is not a member of any additional <code class="literal">groups</code>
- </li><li class="listitem">
- <code class="literal">comment</code> is: <code class="literal">Test user</code>
- </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
- explains those incompatibilities, and for each explains what to do to
- 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
- tree at once. With Buildroot 2016.11 came the possibility to use more
- 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.
- 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">
- First, create a new file named <code class="literal">external.desc</code>, at the root of your
- br2-external tree, with a single line defining the name of your
- br2-external tree:
- </p><pre class="screen">$ echo 'name: NAME_OF_YOUR_TREE' >external.desc</pre><p><strong>Note. </strong>Be careful when choosing a name: It has to be unique and be made
- with only ASCII characters from the set <code class="literal">[A-Za-z0-9_]</code>.</p></li><li class="listitem"><p class="simpara">
- Then, change every occurence of <code class="literal">BR2_EXTERNAL</code> in your br2-external
- tree with the new variable:
- </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
- 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>
- (with e.g. the autotools' <code class="literal">--prefix=$(HOST_DIR)/usr</code>). With Buildroot
- 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
- 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>
|