manual.text 349 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355
  1. ---------------------------------------------------------------------
  2. The Buildroot user manual
  3. ---------------------------------------------------------------------
  4. ---------------------------------------------------------------------
  5. Table of Contents
  6. I. Getting started
  7. 1. About Buildroot
  8. 2. System requirements
  9. 2.1. Mandatory packages
  10. 2.2. Optional packages
  11. 3. Getting Buildroot
  12. 4. Buildroot quick start
  13. 5. Community resources
  14. II. User guide
  15. 6. Buildroot configuration
  16. 6.1. Cross-compilation toolchain
  17. 6.2. /dev management
  18. 6.3. init system
  19. 7. Configuration of other components
  20. 8. General Buildroot usage
  21. 8.1. make tips
  22. 8.2. Understanding when a full rebuild is necessary
  23. 8.3. Understanding how to rebuild packages
  24. 8.4. Offline builds
  25. 8.5. Building out-of-tree
  26. 8.6. Environment variables
  27. 8.7. Dealing efficiently with filesystem images
  28. 8.8. Details about packages
  29. 8.9. Graphing the dependencies between packages
  30. 8.10. Graphing the build duration
  31. 8.11. Graphing the filesystem size contribution of packages
  32. 8.12. Top-level parallel build
  33. 8.13. Integration with Eclipse
  34. 8.14. Advanced usage
  35. 9. Project-specific customization
  36. 9.1. Recommended directory structure
  37. 9.2. Keeping customizations outside of Buildroot
  38. 9.3. Storing the Buildroot configuration
  39. 9.4. Storing the configuration of other components
  40. 9.5. Customizing the generated target filesystem
  41. 9.6. Adding custom user accounts
  42. 9.7. Customization after the images have been created
  43. 9.8. Adding project-specific patches
  44. 9.9. Adding project-specific packages
  45. 9.10. Quick guide to storing your project-specific
  46. customizations
  47. 10. Using SELinux in Buildroot
  48. 10.1. Enabling SELinux support
  49. 10.2. SELinux policy tweaking
  50. 11. Frequently Asked Questions & Troubleshooting
  51. 11.1. The boot hangs after Starting network…
  52. 11.2. Why is there no compiler on the target?
  53. 11.3. Why are there no development files on the target?
  54. 11.4. Why is there no documentation on the target?
  55. 11.5. Why are some packages not visible in the Buildroot
  56. config menu?
  57. 11.6. Why not use the target directory as a chroot directory?
  58. 11.7. Why doesn’t Buildroot generate binary packages (.deb,
  59. .ipkg…)?
  60. 11.8. How to speed-up the build process?
  61. 12. Known issues
  62. 13. Legal notice and licensing
  63. 13.1. Complying with open source licenses
  64. 13.2. Complying with the Buildroot license
  65. 14. Beyond Buildroot
  66. 14.1. Boot the generated images
  67. 14.2. Chroot
  68. III. Developer guide
  69. 15. How Buildroot works
  70. 16. Coding style
  71. 16.1. Config.in file
  72. 16.2. The .mk file
  73. 16.3. The documentation
  74. 16.4. Support scripts
  75. 17. Adding support for a particular board
  76. 18. Adding new packages to Buildroot
  77. 18.1. Package directory
  78. 18.2. Config files
  79. 18.3. The .mk file
  80. 18.4. The .hash file
  81. 18.5. Infrastructure for packages with specific build systems
  82. 18.6. Infrastructure for autotools-based packages
  83. 18.7. Infrastructure for CMake-based packages
  84. 18.8. Infrastructure for Python packages
  85. 18.9. Infrastructure for LuaRocks-based packages
  86. 18.10. Infrastructure for Perl/CPAN packages
  87. 18.11. Infrastructure for virtual packages
  88. 18.12. Infrastructure for packages using kconfig for
  89. configuration files
  90. 18.13. Infrastructure for rebar-based packages
  91. 18.14. Infrastructure for Waf-based packages
  92. 18.15. Infrastructure for Meson-based packages
  93. 18.16. Integration of Cargo-based packages
  94. 18.17. Infrastructure for Go packages
  95. 18.18. Infrastructure for QMake-based packages
  96. 18.19. Infrastructure for packages building kernel modules
  97. 18.20. Infrastructure for asciidoc documents
  98. 18.21. Infrastructure specific to the Linux kernel package
  99. 18.22. Hooks available in the various build steps
  100. 18.23. Gettext integration and interaction with packages
  101. 18.24. Tips and tricks
  102. 18.25. Conclusion
  103. 19. Patching a package
  104. 19.1. Providing patches
  105. 19.2. How patches are applied
  106. 19.3. Format and licensing of the package patches
  107. 19.4. Integrating patches found on the Web
  108. 20. Download infrastructure
  109. 21. Debugging Buildroot
  110. 22. Contributing to Buildroot
  111. 22.1. Reproducing, analyzing and fixing bugs
  112. 22.2. Analyzing and fixing autobuild failures
  113. 22.3. Reviewing and testing patches
  114. 22.4. Work on items from the TODO list
  115. 22.5. Submitting patches
  116. 22.6. Reporting issues/bugs or getting help
  117. 22.7. Using the run-tests framework
  118. 23. DEVELOPERS file and get-developers
  119. 24. Release Engineering
  120. 24.1. Releases
  121. 24.2. Development
  122. IV. Appendix
  123. 25. Makedev syntax documentation
  124. 26. Makeusers syntax documentation
  125. 27. Migrating from older Buildroot versions
  126. 27.1. Migrating to 2016.11
  127. 27.2. Migrating to 2017.08
  128. List of Examples
  129. 18.1. Config script: divine package
  130. 18.2. Config script: imagemagick package:
  131. ---------------------------------------------------------------------
  132. ---------------------------------------------------------------------
  133. Buildroot 2020.11.1 manual generated on 2020-12-27 14:25:17 UTC from
  134. git revision 804a9e1865
  135. The Buildroot manual is written by the Buildroot developers. It is
  136. licensed under the GNU General Public License, version 2. Refer to
  137. the COPYING [http://git.buildroot.org/buildroot/tree/COPYING?id=
  138. 804a9e18656c1584b059129e0b5cebe2a2405fac] file in the Buildroot
  139. sources for the full text of this license.
  140. Copyright © 2004-2020 The Buildroot developers
  141. Part I. Getting started
  142. Table of Contents
  143. 1. About Buildroot
  144. 2. System requirements
  145. 2.1. Mandatory packages
  146. 2.2. Optional packages
  147. 3. Getting Buildroot
  148. 4. Buildroot quick start
  149. 5. Community resources
  150. Chapter 1. About Buildroot
  151. Buildroot is a tool that simplifies and automates the process of
  152. building a complete Linux system for an embedded system, using
  153. cross-compilation.
  154. In order to achieve this, Buildroot is able to generate a
  155. cross-compilation toolchain, a root filesystem, a Linux kernel image
  156. and a bootloader for your target. Buildroot can be used for any
  157. combination of these options, independently (you can for example use
  158. an existing cross-compilation toolchain, and build only your root
  159. filesystem with Buildroot).
  160. Buildroot is useful mainly for people working with embedded systems.
  161. Embedded systems often use processors that are not the regular x86
  162. processors everyone is used to having in his PC. They can be PowerPC
  163. processors, MIPS processors, ARM processors, etc.
  164. Buildroot supports numerous processors and their variants; it also
  165. comes with default configurations for several boards available
  166. off-the-shelf. Besides this, a number of third-party projects are
  167. based on, or develop their BSP ^[1] or SDK ^[2] on top of Buildroot.
  168. ---------------------------------------------------------------------
  169. ^[1] BSP: Board Support Package
  170. ^[2] SDK: Software Development Kit
  171. Chapter 2. System requirements
  172. Buildroot is designed to run on Linux systems.
  173. While Buildroot itself will build most host packages it needs for the
  174. compilation, certain standard Linux utilities are expected to be
  175. already installed on the host system. Below you will find an overview
  176. of the mandatory and optional packages (note that package names may
  177. vary between distributions).
  178. 2.1. Mandatory packages
  179. * Build tools:
  180. + which
  181. + sed
  182. + make (version 3.81 or any later)
  183. + binutils
  184. + build-essential (only for Debian based systems)
  185. + gcc (version 4.8 or any later)
  186. + g++ (version 4.8 or any later)
  187. + bash
  188. + patch
  189. + gzip
  190. + bzip2
  191. + perl (version 5.8.7 or any later)
  192. + tar
  193. + cpio
  194. + unzip
  195. + rsync
  196. + file (must be in /usr/bin/file)
  197. + bc
  198. * Source fetching tools:
  199. + wget
  200. 2.2. Optional packages
  201. * Recommended dependencies:
  202. Some features or utilities in Buildroot, like the legal-info, or
  203. the graph generation tools, have additional dependencies.
  204. Although they are not mandatory for a simple build, they are
  205. still highly recommended:
  206. + python (version 2.7 or any later)
  207. * Configuration interface dependencies:
  208. For these libraries, you need to install both runtime and
  209. development data, which in many distributions are packaged
  210. separately. The development packages typically have a -dev or
  211. -devel suffix.
  212. + ncurses5 to use the menuconfig interface
  213. + qt5 to use the xconfig interface
  214. + glib2, gtk2 and glade2 to use the gconfig interface
  215. * Source fetching tools:
  216. In the official tree, most of the package sources are retrieved
  217. using wget from ftp, http or https locations. A few packages are
  218. only available through a version control system. Moreover,
  219. Buildroot is capable of downloading sources via other tools, like
  220. rsync or scp (refer to Chapter 20, Download infrastructure for
  221. more details). If you enable packages using any of these methods,
  222. you will need to install the corresponding tool on the host
  223. system:
  224. + bazaar
  225. + cvs
  226. + git
  227. + mercurial
  228. + rsync
  229. + scp
  230. + subversion
  231. * Java-related packages, if the Java Classpath needs to be built
  232. for the target system:
  233. + The javac compiler
  234. + The jar tool
  235. * Documentation generation tools:
  236. + asciidoc, version 8.6.3 or higher
  237. + w3m
  238. + python with the argparse module (automatically present in
  239. 2.7+ and 3.2+)
  240. + dblatex (required for the pdf manual only)
  241. * Graph generation tools:
  242. + graphviz to use graph-depends and <pkg>-graph-depends
  243. + python-matplotlib to use graph-build
  244. Chapter 3. Getting Buildroot
  245. Buildroot releases are made every 3 months, in February, May, August
  246. and November. Release numbers are in the format YYYY.MM, so for
  247. example 2013.02, 2014.08.
  248. Release tarballs are available at http://buildroot.org/downloads/.
  249. For your convenience, a Vagrantfile [https://www.vagrantup.com/] is
  250. available in support/misc/Vagrantfile in the Buildroot source tree to
  251. quickly set up a virtual machine with the needed dependencies to get
  252. started.
  253. If you want to setup an isolated buildroot environment on Linux or
  254. Mac Os X, paste this line onto your terminal:
  255. curl -O https://buildroot.org/downloads/Vagrantfile; vagrant up
  256. If you are on Windows, paste this into your powershell:
  257. (new-object System.Net.WebClient).DownloadFile(
  258. "https://buildroot.org/downloads/Vagrantfile","Vagrantfile");
  259. vagrant up
  260. If you want to follow development, you can use the daily snapshots or
  261. make a clone of the Git repository. Refer to the Download page [http:
  262. //buildroot.org/download] of the Buildroot website for more details.
  263. Chapter 4. Buildroot quick start
  264. Important: you can and should build everything as a normal user.
  265. There is no need to be root to configure and use Buildroot. By
  266. running all commands as a regular user, you protect your system
  267. against packages behaving badly during compilation and installation.
  268. The first step when using Buildroot is to create a configuration.
  269. Buildroot has a nice configuration tool similar to the one you can
  270. find in the Linux kernel [http://www.kernel.org/] or in BusyBox
  271. [http://www.busybox.net/].
  272. From the buildroot directory, run
  273. $ make menuconfig
  274. for the original curses-based configurator, or
  275. $ make nconfig
  276. for the new curses-based configurator, or
  277. $ make xconfig
  278. for the Qt-based configurator, or
  279. $ make gconfig
  280. for the GTK-based configurator.
  281. All of these "make" commands will need to build a configuration
  282. utility (including the interface), so you may need to install
  283. "development" packages for relevant libraries used by the
  284. configuration utilities. Refer to Chapter 2, System requirements for
  285. more details, specifically the optional requirements to get the
  286. dependencies of your favorite interface.
  287. For each menu entry in the configuration tool, you can find
  288. associated help that describes the purpose of the entry. Refer to
  289. Chapter 6, Buildroot configuration for details on some specific
  290. configuration aspects.
  291. Once everything is configured, the configuration tool generates a
  292. .config file that contains the entire configuration. This file will
  293. be read by the top-level Makefile.
  294. To start the build process, simply run:
  295. $ make
  296. By default, Buildroot does not support top-level parallel build, so
  297. running make -jN is not necessary. There is however experimental
  298. support for top-level parallel build, see Section 8.12, “Top-level
  299. parallel build”.
  300. The make command will generally perform the following steps:
  301. * download source files (as required);
  302. * configure, build and install the cross-compilation toolchain, or
  303. simply import an external toolchain;
  304. * configure, build and install selected target packages;
  305. * build a kernel image, if selected;
  306. * build a bootloader image, if selected;
  307. * create a root filesystem in selected formats.
  308. Buildroot output is stored in a single directory, output/. This
  309. directory contains several subdirectories:
  310. * images/ where all the images (kernel image, bootloader and root
  311. filesystem images) are stored. These are the files you need to
  312. put on your target system.
  313. * build/ where all the components are built (this includes tools
  314. needed by Buildroot on the host and packages compiled for the
  315. target). This directory contains one subdirectory for each of
  316. these components.
  317. * host/ contains both the tools built for the host, and the sysroot
  318. of the target toolchain. The former is an installation of tools
  319. compiled for the host that are needed for the proper execution of
  320. Buildroot, including the cross-compilation toolchain. The latter
  321. is a hierarchy similar to a root filesystem hierarchy. It
  322. contains the headers and libraries of all user-space packages
  323. that provide and install libraries used by other packages.
  324. However, this directory is not intended to be the root filesystem
  325. for the target: it contains a lot of development files,
  326. unstripped binaries and libraries that make it far too big for an
  327. embedded system. These development files are used to compile
  328. libraries and applications for the target that depend on other
  329. libraries.
  330. * staging/ is a symlink to the target toolchain sysroot inside host
  331. /, which exists for backwards compatibility.
  332. * target/ which contains almost the complete root filesystem for
  333. the target: everything needed is present except the device files
  334. in /dev/ (Buildroot can’t create them because Buildroot doesn’t
  335. run as root and doesn’t want to run as root). Also, it doesn’t
  336. have the correct permissions (e.g. setuid for the busybox
  337. binary). Therefore, this directory should not be used on your
  338. target. Instead, you should use one of the images built in the
  339. images/ directory. If you need an extracted image of the root
  340. filesystem for booting over NFS, then use the tarball image
  341. generated in images/ and extract it as root. Compared to staging
  342. /, target/ contains only the files and libraries needed to run
  343. the selected target applications: the development files (headers,
  344. etc.) are not present, the binaries are stripped.
  345. These commands, make menuconfig|nconfig|gconfig|xconfig and make, are
  346. the basic ones that allow to easily and quickly generate images
  347. fitting your needs, with all the features and applications you
  348. enabled.
  349. More details about the "make" command usage are given in Section 8.1,
  350. “make tips”.
  351. Chapter 5. Community resources
  352. Like any open source project, Buildroot has different ways to share
  353. information in its community and outside.
  354. Each of those ways may interest you if you are looking for some help,
  355. want to understand Buildroot or contribute to the project.
  356. Mailing List
  357. Buildroot has a mailing list for discussion and development. It
  358. is the main method of interaction for Buildroot users and
  359. developers.
  360. Only subscribers to the Buildroot mailing list are allowed to
  361. post to this list. You can subscribe via the mailing list info
  362. page [http://lists.buildroot.org/mailman/listinfo/buildroot].
  363. Mails that are sent to the mailing list are also available in the
  364. mailing list archives [http://lists.buildroot.org/pipermail/
  365. buildroot] and via Gmane [http://gmane.org], at
  366. gmane.comp.lib.uclibc.buildroot [http://dir.gmane.org/
  367. gmane.comp.lib.uclibc.buildroot]. Please search the mailing list
  368. archives before asking questions, since there is a good chance
  369. someone else has asked the same question before.
  370. IRC
  371. The Buildroot IRC channel #buildroot [irc://freenode.net/#
  372. buildroot] is hosted on Freenode [http://webchat.freenode.net].
  373. It is a useful place to ask quick questions or discuss on certain
  374. topics.
  375. When asking for help on IRC, share relevant logs or pieces of
  376. code using a code sharing website, such as http://code.bulix.org.
  377. Note that for certain questions, posting to the mailing list may
  378. be better as it will reach more people, both developers and
  379. users.
  380. Bug tracker
  381. Bugs in Buildroot can be reported via the mailing list or
  382. alternatively via the Buildroot bugtracker [https://
  383. bugs.buildroot.org/buglist.cgi?product=buildroot]. Please refer
  384. to Section 22.6, “Reporting issues/bugs or getting help” before
  385. creating a bug report.
  386. Wiki
  387. The Buildroot wiki page [http://elinux.org/Buildroot] is hosted
  388. on the eLinux [http://elinux.org] wiki. It contains some useful
  389. links, an overview of past and upcoming events, and a TODO list.
  390. Patchwork
  391. Patchwork is a web-based patch tracking system designed to
  392. facilitate the contribution and management of contributions to an
  393. open-source project. Patches that have been sent to a mailing
  394. list are 'caught' by the system, and appear on a web page. Any
  395. comments posted that reference the patch are appended to the
  396. patch page too. For more information on Patchwork see http://
  397. jk.ozlabs.org/projects/patchwork/.
  398. Buildroot’s Patchwork website is mainly for use by Buildroot’s
  399. maintainer to ensure patches aren’t missed. It is also used by
  400. Buildroot patch reviewers (see also Section 22.3.1, “Applying
  401. Patches from Patchwork”). However, since the website exposes
  402. patches and their corresponding review comments in a clean and
  403. concise web interface, it can be useful for all Buildroot
  404. developers.
  405. The Buildroot patch management interface is available at http://
  406. patchwork.buildroot.org.
  407. Part II. User guide
  408. Table of Contents
  409. 6. Buildroot configuration
  410. 6.1. Cross-compilation toolchain
  411. 6.2. /dev management
  412. 6.3. init system
  413. 7. Configuration of other components
  414. 8. General Buildroot usage
  415. 8.1. make tips
  416. 8.2. Understanding when a full rebuild is necessary
  417. 8.3. Understanding how to rebuild packages
  418. 8.4. Offline builds
  419. 8.5. Building out-of-tree
  420. 8.6. Environment variables
  421. 8.7. Dealing efficiently with filesystem images
  422. 8.8. Details about packages
  423. 8.9. Graphing the dependencies between packages
  424. 8.10. Graphing the build duration
  425. 8.11. Graphing the filesystem size contribution of packages
  426. 8.12. Top-level parallel build
  427. 8.13. Integration with Eclipse
  428. 8.14. Advanced usage
  429. 9. Project-specific customization
  430. 9.1. Recommended directory structure
  431. 9.2. Keeping customizations outside of Buildroot
  432. 9.3. Storing the Buildroot configuration
  433. 9.4. Storing the configuration of other components
  434. 9.5. Customizing the generated target filesystem
  435. 9.6. Adding custom user accounts
  436. 9.7. Customization after the images have been created
  437. 9.8. Adding project-specific patches
  438. 9.9. Adding project-specific packages
  439. 9.10. Quick guide to storing your project-specific customizations
  440. 10. Using SELinux in Buildroot
  441. 10.1. Enabling SELinux support
  442. 10.2. SELinux policy tweaking
  443. 11. Frequently Asked Questions & Troubleshooting
  444. 11.1. The boot hangs after Starting network…
  445. 11.2. Why is there no compiler on the target?
  446. 11.3. Why are there no development files on the target?
  447. 11.4. Why is there no documentation on the target?
  448. 11.5. Why are some packages not visible in the Buildroot config
  449. menu?
  450. 11.6. Why not use the target directory as a chroot directory?
  451. 11.7. Why doesn’t Buildroot generate binary packages (.deb,
  452. .ipkg…)?
  453. 11.8. How to speed-up the build process?
  454. 12. Known issues
  455. 13. Legal notice and licensing
  456. 13.1. Complying with open source licenses
  457. 13.2. Complying with the Buildroot license
  458. 14. Beyond Buildroot
  459. 14.1. Boot the generated images
  460. 14.2. Chroot
  461. Chapter 6. Buildroot configuration
  462. All the configuration options in make *config have a help text
  463. providing details about the option.
  464. The make *config commands also offer a search tool. Read the help
  465. message in the different frontend menus to know how to use it:
  466. * in menuconfig, the search tool is called by pressing /;
  467. * in xconfig, the search tool is called by pressing Ctrl + f.
  468. The result of the search shows the help message of the matching
  469. items. In menuconfig, numbers in the left column provide a shortcut
  470. to the corresponding entry. Just type this number to directly jump to
  471. the entry, or to the containing menu in case the entry is not
  472. selectable due to a missing dependency.
  473. Although the menu structure and the help text of the entries should
  474. be sufficiently self-explanatory, a number of topics require
  475. additional explanation that cannot easily be covered in the help text
  476. and are therefore covered in the following sections.
  477. 6.1. Cross-compilation toolchain
  478. A compilation toolchain is the set of tools that allows you to
  479. compile code for your system. It consists of a compiler (in our case,
  480. gcc), binary utils like assembler and linker (in our case, binutils)
  481. and a C standard library (for example GNU Libc [http://www.gnu.org/
  482. software/libc/libc.html], uClibc-ng [http://www.uclibc-ng.org/]).
  483. The system installed on your development station certainly already
  484. has a compilation toolchain that you can use to compile an
  485. application that runs on your system. If you’re using a PC, your
  486. compilation toolchain runs on an x86 processor and generates code for
  487. an x86 processor. Under most Linux systems, the compilation toolchain
  488. uses the GNU libc (glibc) as the C standard library. This compilation
  489. toolchain is called the "host compilation toolchain". The machine on
  490. which it is running, and on which you’re working, is called the "host
  491. system" ^[3].
  492. The compilation toolchain is provided by your distribution, and
  493. Buildroot has nothing to do with it (other than using it to build a
  494. cross-compilation toolchain and other tools that are run on the
  495. development host).
  496. As said above, the compilation toolchain that comes with your system
  497. runs on and generates code for the processor in your host system. As
  498. your embedded system has a different processor, you need a
  499. cross-compilation toolchain - a compilation toolchain that runs on
  500. your host system but generates code for your target system (and
  501. target processor). For example, if your host system uses x86 and your
  502. target system uses ARM, the regular compilation toolchain on your
  503. host runs on x86 and generates code for x86, while the
  504. cross-compilation toolchain runs on x86 and generates code for ARM.
  505. Buildroot provides two solutions for the cross-compilation toolchain:
  506. * The internal toolchain backend, called Buildroot toolchain in the
  507. configuration interface.
  508. * The external toolchain backend, called External toolchain in the
  509. configuration interface.
  510. The choice between these two solutions is done using the Toolchain
  511. Type option in the Toolchain menu. Once one solution has been chosen,
  512. a number of configuration options appear, they are detailed in the
  513. following sections.
  514. 6.1.1. Internal toolchain backend
  515. The internal toolchain backend is the backend where Buildroot builds
  516. by itself a cross-compilation toolchain, before building the
  517. userspace applications and libraries for your target embedded system.
  518. This backend supports several C libraries: uClibc-ng [http://
  519. www.uclibc-ng.org], glibc [http://www.gnu.org/software/libc/
  520. libc.html] and musl [http://www.musl-libc.org].
  521. Once you have selected this backend, a number of options appear. The
  522. most important ones allow to:
  523. * Change the version of the Linux kernel headers used to build the
  524. toolchain. This item deserves a few explanations. In the process
  525. of building a cross-compilation toolchain, the C library is being
  526. built. This library provides the interface between userspace
  527. applications and the Linux kernel. In order to know how to "talk"
  528. to the Linux kernel, the C library needs to have access to the
  529. Linux kernel headers (i.e. the .h files from the kernel), which
  530. define the interface between userspace and the kernel (system
  531. calls, data structures, etc.). Since this interface is backward
  532. compatible, the version of the Linux kernel headers used to build
  533. your toolchain do not need to match exactly the version of the
  534. Linux kernel you intend to run on your embedded system. They only
  535. need to have a version equal or older to the version of the Linux
  536. kernel you intend to run. If you use kernel headers that are more
  537. recent than the Linux kernel you run on your embedded system,
  538. then the C library might be using interfaces that are not
  539. provided by your Linux kernel.
  540. * Change the version of the GCC compiler, binutils and the C
  541. library.
  542. * Select a number of toolchain options (uClibc only): whether the
  543. toolchain should have RPC support (used mainly for NFS),
  544. wide-char support, locale support (for internationalization), C++
  545. support or thread support. Depending on which options you choose,
  546. the number of userspace applications and libraries visible in
  547. Buildroot menus will change: many applications and libraries
  548. require certain toolchain options to be enabled. Most packages
  549. show a comment when a certain toolchain option is required to be
  550. able to enable those packages. If needed, you can further refine
  551. the uClibc configuration by running make uclibc-menuconfig. Note
  552. however that all packages in Buildroot are tested against the
  553. default uClibc configuration bundled in Buildroot: if you deviate
  554. from this configuration by removing features from uClibc, some
  555. packages may no longer build.
  556. It is worth noting that whenever one of those options is modified,
  557. then the entire toolchain and system must be rebuilt. See
  558. Section 8.2, “Understanding when a full rebuild is necessary”.
  559. Advantages of this backend:
  560. * Well integrated with Buildroot
  561. * Fast, only builds what’s necessary
  562. Drawbacks of this backend:
  563. * Rebuilding the toolchain is needed when doing make clean, which
  564. takes time. If you’re trying to reduce your build time, consider
  565. using the External toolchain backend.
  566. 6.1.2. External toolchain backend
  567. The external toolchain backend allows to use existing pre-built
  568. cross-compilation toolchains. Buildroot knows about a number of
  569. well-known cross-compilation toolchains (from Linaro [http://
  570. www.linaro.org] for ARM, Sourcery CodeBench [http://www.mentor.com/
  571. embedded-software/sourcery-tools/sourcery-codebench/editions/
  572. lite-edition/] for ARM, x86-64, PowerPC, and MIPS, and is capable of
  573. downloading them automatically, or it can be pointed to a custom
  574. toolchain, either available for download or installed locally.
  575. Then, you have three solutions to use an external toolchain:
  576. * Use a predefined external toolchain profile, and let Buildroot
  577. download, extract and install the toolchain. Buildroot already
  578. knows about a few CodeSourcery and Linaro toolchains. Just select
  579. the toolchain profile in Toolchain from the available ones. This
  580. is definitely the easiest solution.
  581. * Use a predefined external toolchain profile, but instead of
  582. having Buildroot download and extract the toolchain, you can tell
  583. Buildroot where your toolchain is already installed on your
  584. system. Just select the toolchain profile in Toolchain through
  585. the available ones, unselect Download toolchain automatically,
  586. and fill the Toolchain path text entry with the path to your
  587. cross-compiling toolchain.
  588. * Use a completely custom external toolchain. This is particularly
  589. useful for toolchains generated using crosstool-NG or with
  590. Buildroot itself. To do this, select the Custom toolchain
  591. solution in the Toolchain list. You need to fill the Toolchain
  592. path, Toolchain prefix and External toolchain C library options.
  593. Then, you have to tell Buildroot what your external toolchain
  594. supports. If your external toolchain uses the glibc library, you
  595. only have to tell whether your toolchain supports C++ or not and
  596. whether it has built-in RPC support. If your external toolchain
  597. uses the uClibc library, then you have to tell Buildroot if it
  598. supports RPC, wide-char, locale, program invocation, threads and
  599. C++. At the beginning of the execution, Buildroot will tell you
  600. if the selected options do not match the toolchain configuration.
  601. Our external toolchain support has been tested with toolchains from
  602. CodeSourcery and Linaro, toolchains generated by crosstool-NG [http:/
  603. /crosstool-ng.org], and toolchains generated by Buildroot itself. In
  604. general, all toolchains that support the sysroot feature should work.
  605. If not, do not hesitate to contact the developers.
  606. We do not support toolchains or SDK generated by OpenEmbedded or
  607. Yocto, because these toolchains are not pure toolchains (i.e. just
  608. the compiler, binutils, the C and C++ libraries). Instead these
  609. toolchains come with a very large set of pre-compiled libraries and
  610. programs. Therefore, Buildroot cannot import the sysroot of the
  611. toolchain, as it would contain hundreds of megabytes of pre-compiled
  612. libraries that are normally built by Buildroot.
  613. We also do not support using the distribution toolchain (i.e. the gcc
  614. /binutils/C library installed by your distribution) as the toolchain
  615. to build software for the target. This is because your distribution
  616. toolchain is not a "pure" toolchain (i.e. only with the C/C++
  617. library), so we cannot import it properly into the Buildroot build
  618. environment. So even if you are building a system for a x86 or x86_64
  619. target, you have to generate a cross-compilation toolchain with
  620. Buildroot or crosstool-NG.
  621. If you want to generate a custom toolchain for your project, that can
  622. be used as an external toolchain in Buildroot, our recommendation is
  623. to build it either with Buildroot itself (see Section 6.1.3, “Build
  624. an external toolchain with Buildroot”) or with crosstool-NG [http://
  625. crosstool-ng.org].
  626. Advantages of this backend:
  627. * Allows to use well-known and well-tested cross-compilation
  628. toolchains.
  629. * Avoids the build time of the cross-compilation toolchain, which
  630. is often very significant in the overall build time of an
  631. embedded Linux system.
  632. Drawbacks of this backend:
  633. * If your pre-built external toolchain has a bug, may be hard to
  634. get a fix from the toolchain vendor, unless you build your
  635. external toolchain by yourself using Buildroot or Crosstool-NG.
  636. 6.1.3. Build an external toolchain with Buildroot
  637. The Buildroot internal toolchain option can be used to create an
  638. external toolchain. Here are a series of steps to build an internal
  639. toolchain and package it up for reuse by Buildroot itself (or other
  640. projects).
  641. Create a new Buildroot configuration, with the following details:
  642. * Select the appropriate Target options for your target CPU
  643. architecture
  644. * In the Toolchain menu, keep the default of Buildroot toolchain
  645. for Toolchain type, and configure your toolchain as desired
  646. * In the System configuration menu, select None as the Init system
  647. and none as /bin/sh
  648. * In the Target packages menu, disable BusyBox
  649. * In the Filesystem images menu, disable tar the root filesystem
  650. Then, we can trigger the build, and also ask Buildroot to generate a
  651. SDK. This will conveniently generate for us a tarball which contains
  652. our toolchain:
  653. make sdk
  654. This produces the SDK tarball in $(O)/images, with a name similar to
  655. arm-buildroot-linux-uclibcgnueabi_sdk-buildroot.tar.gz. Save this
  656. tarball, as it is now the toolchain that you can re-use as an
  657. external toolchain in other Buildroot projects.
  658. In those other Buildroot projects, in the Toolchain menu:
  659. * Set Toolchain type to External toolchain
  660. * Set Toolchain to Custom toolchain
  661. * Set Toolchain origin to Toolchain to be downloaded and installed
  662. * Set Toolchain URL to file:///path/to/your/sdk/tarball.tar.gz
  663. 6.1.3.1. External toolchain wrapper
  664. When using an external toolchain, Buildroot generates a wrapper
  665. program, that transparently passes the appropriate options (according
  666. to the configuration) to the external toolchain programs. In case you
  667. need to debug this wrapper to check exactly what arguments are
  668. passed, you can set the environment variable BR2_DEBUG_WRAPPER to
  669. either one of:
  670. * 0, empty or not set: no debug
  671. * 1: trace all arguments on a single line
  672. * 2: trace one argument per line
  673. 6.2. /dev management
  674. On a Linux system, the /dev directory contains special files, called
  675. device files, that allow userspace applications to access the
  676. hardware devices managed by the Linux kernel. Without these device
  677. files, your userspace applications would not be able to use the
  678. hardware devices, even if they are properly recognized by the Linux
  679. kernel.
  680. Under System configuration, /dev management, Buildroot offers four
  681. different solutions to handle the /dev directory :
  682. * The first solution is Static using device table. This is the old
  683. classical way of handling device files in Linux. With this
  684. method, the device files are persistently stored in the root
  685. filesystem (i.e. they persist across reboots), and there is
  686. nothing that will automatically create and remove those device
  687. files when hardware devices are added or removed from the system.
  688. Buildroot therefore creates a standard set of device files using
  689. a device table, the default one being stored in system/
  690. device_table_dev.txt in the Buildroot source code. This file is
  691. processed when Buildroot generates the final root filesystem
  692. image, and the device files are therefore not visible in the
  693. output/target directory. The BR2_ROOTFS_STATIC_DEVICE_TABLE
  694. option allows to change the default device table used by
  695. Buildroot, or to add an additional device table, so that
  696. additional device files are created by Buildroot during the
  697. build. So, if you use this method, and a device file is missing
  698. in your system, you can for example create a board/<yourcompany>/
  699. <yourproject>/device_table_dev.txt file that contains the
  700. description of your additional device files, and then you can set
  701. BR2_ROOTFS_STATIC_DEVICE_TABLE to system/device_table_dev.txt
  702. board/<yourcompany>/<yourproject>/device_table_dev.txt. For more
  703. details about the format of the device table file, see
  704. Chapter 25, Makedev syntax documentation.
  705. * The second solution is Dynamic using devtmpfs only. devtmpfs is a
  706. virtual filesystem inside the Linux kernel that has been
  707. introduced in kernel 2.6.32 (if you use an older kernel, it is
  708. not possible to use this option). When mounted in /dev, this
  709. virtual filesystem will automatically make device files appear
  710. and disappear as hardware devices are added and removed from the
  711. system. This filesystem is not persistent across reboots: it is
  712. filled dynamically by the kernel. Using devtmpfs requires the
  713. following kernel configuration options to be enabled:
  714. CONFIG_DEVTMPFS and CONFIG_DEVTMPFS_MOUNT. When Buildroot is in
  715. charge of building the Linux kernel for your embedded device, it
  716. makes sure that those two options are enabled. However, if you
  717. build your Linux kernel outside of Buildroot, then it is your
  718. responsibility to enable those two options (if you fail to do so,
  719. your Buildroot system will not boot).
  720. * The third solution is Dynamic using devtmpfs + mdev. This method
  721. also relies on the devtmpfs virtual filesystem detailed above (so
  722. the requirement to have CONFIG_DEVTMPFS and CONFIG_DEVTMPFS_MOUNT
  723. enabled in the kernel configuration still apply), but adds the
  724. mdev userspace utility on top of it. mdev is a program part of
  725. BusyBox that the kernel will call every time a device is added or
  726. removed. Thanks to the /etc/mdev.conf configuration file, mdev
  727. can be configured to for example, set specific permissions or
  728. ownership on a device file, call a script or application whenever
  729. a device appears or disappear, etc. Basically, it allows
  730. userspace to react on device addition and removal events. mdev
  731. can for example be used to automatically load kernel modules when
  732. devices appear on the system. mdev is also important if you have
  733. devices that require a firmware, as it will be responsible for
  734. pushing the firmware contents to the kernel. mdev is a
  735. lightweight implementation (with fewer features) of udev. For
  736. more details about mdev and the syntax of its configuration file,
  737. see http://git.busybox.net/busybox/tree/docs/mdev.txt.
  738. * The fourth solution is Dynamic using devtmpfs + eudev. This
  739. method also relies on the devtmpfs virtual filesystem detailed
  740. above, but adds the eudev userspace daemon on top of it. eudev is
  741. a daemon that runs in the background, and gets called by the
  742. kernel when a device gets added or removed from the system. It is
  743. a more heavyweight solution than mdev, but provides higher
  744. flexibility. eudev is a standalone version of udev, the original
  745. userspace daemon used in most desktop Linux distributions, which
  746. is now part of Systemd. For more details, see http://
  747. en.wikipedia.org/wiki/Udev.
  748. The Buildroot developers recommendation is to start with the Dynamic
  749. using devtmpfs only solution, until you have the need for userspace
  750. to be notified when devices are added/removed, or if firmwares are
  751. needed, in which case Dynamic using devtmpfs + mdev is usually a good
  752. solution.
  753. Note that if systemd is chosen as init system, /dev management will
  754. be performed by the udev program provided by systemd.
  755. 6.3. init system
  756. The init program is the first userspace program started by the kernel
  757. (it carries the PID number 1), and is responsible for starting the
  758. userspace services and programs (for example: web server, graphical
  759. applications, other network servers, etc.).
  760. Buildroot allows to use three different types of init systems, which
  761. can be chosen from System configuration, Init system:
  762. * The first solution is BusyBox. Amongst many programs, BusyBox has
  763. an implementation of a basic init program, which is sufficient
  764. for most embedded systems. Enabling the BR2_INIT_BUSYBOX will
  765. ensure BusyBox will build and install its init program. This is
  766. the default solution in Buildroot. The BusyBox init program will
  767. read the /etc/inittab file at boot to know what to do. The syntax
  768. of this file can be found in http://git.busybox.net/busybox/tree/
  769. examples/inittab (note that BusyBox inittab syntax is special: do
  770. not use a random inittab documentation from the Internet to learn
  771. about BusyBox inittab). The default inittab in Buildroot is
  772. stored in system/skeleton/etc/inittab. Apart from mounting a few
  773. important filesystems, the main job the default inittab does is
  774. to start the /etc/init.d/rcS shell script, and start a getty
  775. program (which provides a login prompt).
  776. * The second solution is systemV. This solution uses the old
  777. traditional sysvinit program, packed in Buildroot in package/
  778. sysvinit. This was the solution used in most desktop Linux
  779. distributions, until they switched to more recent alternatives
  780. such as Upstart or Systemd. sysvinit also works with an inittab
  781. file (which has a slightly different syntax than the one from
  782. BusyBox). The default inittab installed with this init solution
  783. is located in package/sysvinit/inittab.
  784. * The third solution is systemd. systemd is the new generation init
  785. system for Linux. It does far more than traditional init
  786. programs: aggressive parallelization capabilities, uses socket
  787. and D-Bus activation for starting services, offers on-demand
  788. starting of daemons, keeps track of processes using Linux control
  789. groups, supports snapshotting and restoring of the system state,
  790. etc. systemd will be useful on relatively complex embedded
  791. systems, for example the ones requiring D-Bus and services
  792. communicating between each other. It is worth noting that systemd
  793. brings a fairly big number of large dependencies: dbus, udev and
  794. more. For more details about systemd, see http://
  795. www.freedesktop.org/wiki/Software/systemd.
  796. The solution recommended by Buildroot developers is to use the
  797. BusyBox init as it is sufficient for most embedded systems. systemd
  798. can be used for more complex situations.
  799. ---------------------------------------------------------------------
  800. ^[3] This terminology differs from what is used by GNU configure,
  801. where the host is the machine on which the application will run
  802. (which is usually the same as target)
  803. Chapter 7. Configuration of other components
  804. Before attempting to modify any of the components below, make sure
  805. you have already configured Buildroot itself, and have enabled the
  806. corresponding package.
  807. BusyBox
  808. If you already have a BusyBox configuration file, you can
  809. directly specify this file in the Buildroot configuration, using
  810. BR2_PACKAGE_BUSYBOX_CONFIG. Otherwise, Buildroot will start from
  811. a default BusyBox configuration file.
  812. To make subsequent changes to the configuration, use make
  813. busybox-menuconfig to open the BusyBox configuration editor.
  814. It is also possible to specify a BusyBox configuration file
  815. through an environment variable, although this is not
  816. recommended. Refer to Section 8.6, “Environment variables” for
  817. more details.
  818. uClibc
  819. Configuration of uClibc is done in the same way as for BusyBox.
  820. The configuration variable to specify an existing configuration
  821. file is BR2_UCLIBC_CONFIG. The command to make subsequent changes
  822. is make uclibc-menuconfig.
  823. Linux kernel
  824. If you already have a kernel configuration file, you can directly
  825. specify this file in the Buildroot configuration, using
  826. BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG.
  827. If you do not yet have a kernel configuration file, you can
  828. either start by specifying a defconfig in the Buildroot
  829. configuration, using BR2_LINUX_KERNEL_USE_DEFCONFIG, or start by
  830. creating an empty file and specifying it as custom configuration
  831. file, using BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG.
  832. To make subsequent changes to the configuration, use make
  833. linux-menuconfig to open the Linux configuration editor.
  834. Barebox
  835. Configuration of Barebox is done in the same way as for the Linux
  836. kernel. The corresponding configuration variables are
  837. BR2_TARGET_BAREBOX_USE_CUSTOM_CONFIG and
  838. BR2_TARGET_BAREBOX_USE_DEFCONFIG. To open the configuration
  839. editor, use make barebox-menuconfig.
  840. U-Boot
  841. Configuration of U-Boot (version 2015.04 or newer) is done in the
  842. same way as for the Linux kernel. The corresponding configuration
  843. variables are BR2_TARGET_UBOOT_USE_CUSTOM_CONFIG and
  844. BR2_TARGET_UBOOT_USE_DEFCONFIG. To open the configuration editor,
  845. use make uboot-menuconfig.
  846. Chapter 8. General Buildroot usage
  847. 8.1. make tips
  848. This is a collection of tips that help you make the most of
  849. Buildroot.
  850. Display all commands executed by make: 
  851. $ make V=1 <target>
  852. Display the list of boards with a defconfig: 
  853. $ make list-defconfigs
  854. Display all available targets: 
  855. $ make help
  856. Not all targets are always available, some settings in the .config
  857. file may hide some targets:
  858. * busybox-menuconfig only works when busybox is enabled;
  859. * linux-menuconfig and linux-savedefconfig only work when linux is
  860. enabled;
  861. * uclibc-menuconfig is only available when the uClibc C library is
  862. selected in the internal toolchain backend;
  863. * barebox-menuconfig and barebox-savedefconfig only work when the
  864. barebox bootloader is enabled.
  865. * uboot-menuconfig and uboot-savedefconfig only work when the
  866. U-Boot bootloader is enabled.
  867. Cleaning: Explicit cleaning is required when any of the architecture
  868. or toolchain configuration options are changed.
  869. To delete all build products (including build directories, host,
  870. staging and target trees, the images and the toolchain):
  871. $ make clean
  872. Generating the manual: The present manual sources are located in the
  873. docs/manual directory. To generate the manual:
  874. $ make manual-clean
  875. $ make manual
  876. The manual outputs will be generated in output/docs/manual.
  877. Notes
  878. * A few tools are required to build the documentation (see:
  879. Section 2.2, “Optional packages”).
  880. Resetting Buildroot for a new target: To delete all build products as
  881. well as the configuration:
  882. $ make distclean
  883. Notes. If ccache is enabled, running make clean or distclean does not
  884. empty the compiler cache used by Buildroot. To delete it, refer to
  885. Section 8.14.3, “Using ccache in Buildroot”.
  886. Dumping the internal make variables: One can dump the variables known
  887. to make, along with their values:
  888. $ make -s printvars VARS='VARIABLE1 VARIABLE2'
  889. VARIABLE1=value_of_variable
  890. VARIABLE2=value_of_variable
  891. It is possible to tweak the output using some variables:
  892. * VARS will limit the listing to variables which names match the
  893. specified make-patterns - this must be set else nothing is
  894. printed
  895. * QUOTED_VARS, if set to YES, will single-quote the value
  896. * RAW_VARS, if set to YES, will print the unexpanded value
  897. For example:
  898. $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES
  899. BUSYBOX_DEPENDENCIES=skeleton toolchain
  900. BUSYBOX_FINAL_ALL_DEPENDENCIES=skeleton toolchain
  901. BUSYBOX_FINAL_DEPENDENCIES=skeleton toolchain
  902. BUSYBOX_FINAL_PATCH_DEPENDENCIES=
  903. BUSYBOX_RDEPENDENCIES=ncurses util-linux
  904. $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES QUOTED_VARS=YES
  905. BUSYBOX_DEPENDENCIES='skeleton toolchain'
  906. BUSYBOX_FINAL_ALL_DEPENDENCIES='skeleton toolchain'
  907. BUSYBOX_FINAL_DEPENDENCIES='skeleton toolchain'
  908. BUSYBOX_FINAL_PATCH_DEPENDENCIES=''
  909. BUSYBOX_RDEPENDENCIES='ncurses util-linux'
  910. $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES RAW_VARS=YES
  911. BUSYBOX_DEPENDENCIES=skeleton toolchain
  912. BUSYBOX_FINAL_ALL_DEPENDENCIES=$(sort $(BUSYBOX_FINAL_DEPENDENCIES) $(BUSYBOX_FINAL_PATCH_DEPENDENCIES))
  913. BUSYBOX_FINAL_DEPENDENCIES=$(sort $(BUSYBOX_DEPENDENCIES))
  914. BUSYBOX_FINAL_PATCH_DEPENDENCIES=$(sort $(BUSYBOX_PATCH_DEPENDENCIES))
  915. BUSYBOX_RDEPENDENCIES=ncurses util-linux
  916. The output of quoted variables can be reused in shell scripts, for
  917. example:
  918. $ eval $(make -s printvars VARS=BUSYBOX_DEPENDENCIES QUOTED_VARS=YES)
  919. $ echo $BUSYBOX_DEPENDENCIES
  920. skeleton toolchain
  921. 8.2. Understanding when a full rebuild is necessary
  922. Buildroot does not attempt to detect what parts of the system should
  923. be rebuilt when the system configuration is changed through make
  924. menuconfig, make xconfig or one of the other configuration tools. In
  925. some cases, Buildroot should rebuild the entire system, in some
  926. cases, only a specific subset of packages. But detecting this in a
  927. completely reliable manner is very difficult, and therefore the
  928. Buildroot developers have decided to simply not attempt to do this.
  929. Instead, it is the responsibility of the user to know when a full
  930. rebuild is necessary. As a hint, here are a few rules of thumb that
  931. can help you understand how to work with Buildroot:
  932. * When the target architecture configuration is changed, a complete
  933. rebuild is needed. Changing the architecture variant, the binary
  934. format or the floating point strategy for example has an impact
  935. on the entire system.
  936. * When the toolchain configuration is changed, a complete rebuild
  937. generally is needed. Changing the toolchain configuration often
  938. involves changing the compiler version, the type of C library or
  939. its configuration, or some other fundamental configuration item,
  940. and these changes have an impact on the entire system.
  941. * When an additional package is added to the configuration, a full
  942. rebuild is not necessarily needed. Buildroot will detect that
  943. this package has never been built, and will build it. However, if
  944. this package is a library that can optionally be used by packages
  945. that have already been built, Buildroot will not automatically
  946. rebuild those. Either you know which packages should be rebuilt,
  947. and you can rebuild them manually, or you should do a full
  948. rebuild. For example, let’s suppose you have built a system with
  949. the ctorrent package, but without openssl. Your system works, but
  950. you realize you would like to have SSL support in ctorrent, so
  951. you enable the openssl package in Buildroot configuration and
  952. restart the build. Buildroot will detect that openssl should be
  953. built and will be build it, but it will not detect that ctorrent
  954. should be rebuilt to benefit from openssl to add OpenSSL support.
  955. You will either have to do a full rebuild, or rebuild ctorrent
  956. itself.
  957. * When a package is removed from the configuration, Buildroot does
  958. not do anything special. It does not remove the files installed
  959. by this package from the target root filesystem or from the
  960. toolchain sysroot. A full rebuild is needed to get rid of this
  961. package. However, generally you don’t necessarily need this
  962. package to be removed right now: you can wait for the next lunch
  963. break to restart the build from scratch.
  964. * When the sub-options of a package are changed, the package is not
  965. automatically rebuilt. After making such changes, rebuilding only
  966. this package is often sufficient, unless enabling the package
  967. sub-option adds some features to the package that are useful for
  968. another package which has already been built. Again, Buildroot
  969. does not track when a package should be rebuilt: once a package
  970. has been built, it is never rebuilt unless explicitly told to do
  971. so.
  972. * When a change to the root filesystem skeleton is made, a full
  973. rebuild is needed. However, when changes to the root filesystem
  974. overlay, a post-build script or a post-image script are made,
  975. there is no need for a full rebuild: a simple make invocation
  976. will take the changes into account.
  977. * When a package listed in FOO_DEPENDENCIES is rebuilt or removed,
  978. the package foo is not automatically rebuilt. For example, if a
  979. package bar is listed in FOO_DEPENDENCIES with FOO_DEPENDENCIES =
  980. bar and the configuration of the bar package is changed, the
  981. configuration change would not result in a rebuild of package foo
  982. automatically. In this scenario, you may need to either rebuild
  983. any packages in your build which reference bar in their
  984. DEPENDENCIES, or perform a full rebuild to ensure any bar
  985. dependent packages are up to date.
  986. Generally speaking, when you’re facing a build error and you’re
  987. unsure of the potential consequences of the configuration changes
  988. you’ve made, do a full rebuild. If you get the same build error, then
  989. you are sure that the error is not related to partial rebuilds of
  990. packages, and if this error occurs with packages from the official
  991. Buildroot, do not hesitate to report the problem! As your experience
  992. with Buildroot progresses, you will progressively learn when a full
  993. rebuild is really necessary, and you will save more and more time.
  994. For reference, a full rebuild is achieved by running:
  995. $ make clean all
  996. 8.3. Understanding how to rebuild packages
  997. One of the most common questions asked by Buildroot users is how to
  998. rebuild a given package or how to remove a package without rebuilding
  999. everything from scratch.
  1000. Removing a package is unsupported by Buildroot without rebuilding
  1001. from scratch. This is because Buildroot doesn’t keep track of which
  1002. package installs what files in the output/staging and output/target
  1003. directories, or which package would be compiled differently depending
  1004. on the availability of another package.
  1005. The easiest way to rebuild a single package from scratch is to remove
  1006. its build directory in output/build. Buildroot will then re-extract,
  1007. re-configure, re-compile and re-install this package from scratch.
  1008. You can ask buildroot to do this with the make <package>-dirclean
  1009. command.
  1010. On the other hand, if you only want to restart the build process of a
  1011. package from its compilation step, you can run make <package>
  1012. -rebuild. It will restart the compilation and installation of the
  1013. package, but not from scratch: it basically re-executes make and make
  1014. install inside the package, so it will only rebuild files that
  1015. changed.
  1016. If you want to restart the build process of a package from its
  1017. configuration step, you can run make <package>-reconfigure. It will
  1018. restart the configuration, compilation and installation of the
  1019. package.
  1020. While <package>-rebuild implies <package>-reinstall and <package>
  1021. -reconfigure implies <package>-rebuild, these targets as well as
  1022. <package> only act on the said package, and do not trigger
  1023. re-creating the root filesystem image. If re-creating the root
  1024. filesystem in necessary, one should in addition run make or make all.
  1025. Internally, Buildroot creates so-called stamp files to keep track of
  1026. which build steps have been completed for each package. They are
  1027. stored in the package build directory, output/build/<package>-
  1028. <version>/ and are named .stamp_<step-name>. The commands detailed
  1029. above simply manipulate these stamp files to force Buildroot to
  1030. restart a specific set of steps of a package build process.
  1031. Further details about package special make targets are explained in
  1032. Section 8.14.5, “Package-specific make targets”.
  1033. 8.4. Offline builds
  1034. If you intend to do an offline build and just want to download all
  1035. sources that you previously selected in the configurator (menuconfig,
  1036. nconfig, xconfig or gconfig), then issue:
  1037. $ make source
  1038. You can now disconnect or copy the content of your dl directory to
  1039. the build-host.
  1040. 8.5. Building out-of-tree
  1041. As default, everything built by Buildroot is stored in the directory
  1042. output in the Buildroot tree.
  1043. Buildroot also supports building out of tree with a syntax similar to
  1044. the Linux kernel. To use it, add O=<directory> to the make command
  1045. line:
  1046. $ make O=/tmp/build
  1047. Or:
  1048. $ cd /tmp/build; make O=$PWD -C path/to/buildroot
  1049. All the output files will be located under /tmp/build. If the O path
  1050. does not exist, Buildroot will create it.
  1051. Note: the O path can be either an absolute or a relative path, but if
  1052. it’s passed as a relative path, it is important to note that it is
  1053. interpreted relative to the main Buildroot source directory, not the
  1054. current working directory.
  1055. When using out-of-tree builds, the Buildroot .config and temporary
  1056. files are also stored in the output directory. This means that you
  1057. can safely run multiple builds in parallel using the same source tree
  1058. as long as they use unique output directories.
  1059. For ease of use, Buildroot generates a Makefile wrapper in the output
  1060. directory - so after the first run, you no longer need to pass O=<…>
  1061. and -C <…>, simply run (in the output directory):
  1062. $ make <target>
  1063. 8.6. Environment variables
  1064. Buildroot also honors some environment variables, when they are
  1065. passed to make or set in the environment:
  1066. * HOSTCXX, the host C++ compiler to use
  1067. * HOSTCC, the host C compiler to use
  1068. * UCLIBC_CONFIG_FILE=<path/to/.config>, path to the uClibc
  1069. configuration file, used to compile uClibc, if an internal
  1070. toolchain is being built. Note that the uClibc configuration file
  1071. can also be set from the configuration interface, so through the
  1072. Buildroot .config file; this is the recommended way of setting
  1073. it.
  1074. * BUSYBOX_CONFIG_FILE=<path/to/.config>, path to the BusyBox
  1075. configuration file. Note that the BusyBox configuration file can
  1076. also be set from the configuration interface, so through the
  1077. Buildroot .config file; this is the recommended way of setting
  1078. it.
  1079. * BR2_CCACHE_DIR to override the directory where Buildroot stores
  1080. the cached files when using ccache.
  1081. * BR2_DL_DIR to override the directory in which Buildroot stores/
  1082. retrieves downloaded files. Note that the Buildroot download
  1083. directory can also be set from the configuration interface, so
  1084. through the Buildroot .config file. See Section 8.14.4, “Location
  1085. of downloaded packages” for more details on how you can set the
  1086. download directory.
  1087. * BR2_GRAPH_ALT, if set and non-empty, to use an alternate
  1088. color-scheme in build-time graphs
  1089. * BR2_GRAPH_OUT to set the filetype of generated graphs, either pdf
  1090. (the default), or png.
  1091. * BR2_GRAPH_DEPS_OPTS to pass extra options to the dependency
  1092. graph; see Section 8.9, “Graphing the dependencies between
  1093. packages” for the accepted options
  1094. * BR2_GRAPH_DOT_OPTS is passed verbatim as options to the dot
  1095. utility to draw the dependency graph.
  1096. * BR2_GRAPH_SIZE_OPTS to pass extra options to the size graph; see
  1097. Section 8.11, “Graphing the filesystem size contribution of
  1098. packages” for the acepted options
  1099. An example that uses config files located in the toplevel directory
  1100. and in your $HOME:
  1101. $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
  1102. If you want to use a compiler other than the default gcc or g++ for
  1103. building helper-binaries on your host, then do
  1104. $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
  1105. 8.7. Dealing efficiently with filesystem images
  1106. Filesystem images can get pretty big, depending on the filesystem you
  1107. choose, the number of packages, whether you provisioned free space…
  1108. Yet, some locations in the filesystems images may just be empty (e.g.
  1109. a long run of zeroes); such a file is called a sparse file.
  1110. Most tools can handle sparse files efficiently, and will only store
  1111. or write those parts of a sparse file that are not empty.
  1112. For example:
  1113. * tar accepts the -S option to tell it to only store non-zero
  1114. blocks of sparse files:
  1115. + tar cf archive.tar -S [files…] will efficiently store sparse
  1116. files in a tarball
  1117. + tar xf archive.tar -S will efficiently store sparse files
  1118. extracted from a tarball
  1119. * cp accepts the --sparse=WHEN option (WHEN is one of auto, never
  1120. or always):
  1121. + cp --sparse=always source.file dest.file will make dest.file
  1122. a sparse file if source.file has long runs of zeroes
  1123. Other tools may have similar options. Please consult their respective
  1124. man pages.
  1125. You can use sparse files if you need to store the filesystem images
  1126. (e.g. to transfer from one machine to another), or if you need to
  1127. send them (e.g. to the Q&A team).
  1128. Note however that flashing a filesystem image to a device while using
  1129. the sparse mode of dd may result in a broken filesystem (e.g. the
  1130. block bitmap of an ext2 filesystem may be corrupted; or, if you have
  1131. sparse files in your filesystem, those parts may not be all-zeroes
  1132. when read back). You should only use sparse files when handling files
  1133. on the build machine, not when transferring them to an actual device
  1134. that will be used on the target.
  1135. 8.8. Details about packages
  1136. Buildroot can produce a JSON blurb that describes the set of enabled
  1137. packages in the current configuration, together with their
  1138. dependencies, licenses and other metadata. This JSON blurb is
  1139. produced by using the show-info make target:
  1140. make show-info
  1141. Buildroot can also produce details about packages as HTML and JSON
  1142. output using the pkg-stats make target. Amongst other things, these
  1143. details include whether known CVEs (security vulnerabilities) affect
  1144. the packages in your current configuration. It also shows if there is
  1145. a newer upstream version for those packages.
  1146. make pkg-stats
  1147. 8.9. Graphing the dependencies between packages
  1148. One of Buildroot’s jobs is to know the dependencies between packages,
  1149. and make sure they are built in the right order. These dependencies
  1150. can sometimes be quite complicated, and for a given system, it is
  1151. often not easy to understand why such or such package was brought
  1152. into the build by Buildroot.
  1153. In order to help understanding the dependencies, and therefore better
  1154. understand what is the role of the different components in your
  1155. embedded Linux system, Buildroot is capable of generating dependency
  1156. graphs.
  1157. To generate a dependency graph of the full system you have compiled,
  1158. simply run:
  1159. make graph-depends
  1160. You will find the generated graph in output/graphs/graph-depends.pdf.
  1161. If your system is quite large, the dependency graph may be too
  1162. complex and difficult to read. It is therefore possible to generate
  1163. the dependency graph just for a given package:
  1164. make <pkg>-graph-depends
  1165. You will find the generated graph in output/graph/<pkg>
  1166. -graph-depends.pdf.
  1167. Note that the dependency graphs are generated using the dot tool from
  1168. the Graphviz project, which you must have installed on your system to
  1169. use this feature. In most distributions, it is available as the
  1170. graphviz package.
  1171. By default, the dependency graphs are generated in the PDF format.
  1172. However, by passing the BR2_GRAPH_OUT environment variable, you can
  1173. switch to other output formats, such as PNG, PostScript or SVG. All
  1174. formats supported by the -T option of the dot tool are supported.
  1175. BR2_GRAPH_OUT=svg make graph-depends
  1176. The graph-depends behaviour can be controlled by setting options in
  1177. the BR2_GRAPH_DEPS_OPTS environment variable. The accepted options
  1178. are:
  1179. * --depth N, -d N, to limit the dependency depth to N levels. The
  1180. default, 0, means no limit.
  1181. * --stop-on PKG, -s PKG, to stop the graph on the package PKG. PKG
  1182. can be an actual package name, a glob, the keyword virtual (to
  1183. stop on virtual packages), or the keyword host (to stop on host
  1184. packages). The package is still present on the graph, but its
  1185. dependencies are not.
  1186. * --exclude PKG, -x PKG, like --stop-on, but also omits PKG from
  1187. the graph.
  1188. * --transitive, --no-transitive, to draw (or not) the transitive
  1189. dependencies. The default is to not draw transitive dependencies.
  1190. * --colors R,T,H, the comma-separated list of colors to draw the
  1191. root package (R), the target packages (T) and the host packages
  1192. (H). Defaults to: lightblue,grey,gainsboro
  1193. BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colors=red,green,blue' make graph-depends
  1194. 8.10. Graphing the build duration
  1195. When the build of a system takes a long time, it is sometimes useful
  1196. to be able to understand which packages are the longest to build, to
  1197. see if anything can be done to speed up the build. In order to help
  1198. such build time analysis, Buildroot collects the build time of each
  1199. step of each package, and allows to generate graphs from this data.
  1200. To generate the build time graph after a build, run:
  1201. make graph-build
  1202. This will generate a set of files in output/graphs :
  1203. * build.hist-build.pdf, a histogram of the build time for each
  1204. package, ordered in the build order.
  1205. * build.hist-duration.pdf, a histogram of the build time for each
  1206. package, ordered by duration (longest first)
  1207. * build.hist-name.pdf, a histogram of the build time for each
  1208. package, order by package name.
  1209. * build.pie-packages.pdf, a pie chart of the build time per package
  1210. * build.pie-steps.pdf, a pie chart of the global time spent in each
  1211. step of the packages build process.
  1212. This graph-build target requires the Python Matplotlib and Numpy
  1213. libraries to be installed (python-matplotlib and python-numpy on most
  1214. distributions), and also the argparse module if you’re using a Python
  1215. version older than 2.7 (python-argparse on most distributions).
  1216. By default, the output format for the graph is PDF, but a different
  1217. format can be selected using the BR2_GRAPH_OUT environment variable.
  1218. The only other format supported is PNG:
  1219. BR2_GRAPH_OUT=png make graph-build
  1220. 8.11. Graphing the filesystem size contribution of packages
  1221. When your target system grows, it is sometimes useful to understand
  1222. how much each Buildroot package is contributing to the overall root
  1223. filesystem size. To help with such an analysis, Buildroot collects
  1224. data about files installed by each package and using this data,
  1225. generates a graph and CSV files detailing the size contribution of
  1226. the different packages.
  1227. To generate these data after a build, run:
  1228. make graph-size
  1229. This will generate:
  1230. * output/graphs/graph-size.pdf, a pie chart of the contribution of
  1231. each package to the overall root filesystem size
  1232. * output/graphs/package-size-stats.csv, a CSV file giving the size
  1233. contribution of each package to the overall root filesystem size
  1234. * output/graphs/file-size-stats.csv, a CSV file giving the size
  1235. contribution of each installed file to the package it belongs,
  1236. and to the overall filesystem size.
  1237. This graph-size target requires the Python Matplotlib library to be
  1238. installed (python-matplotlib on most distributions), and also the
  1239. argparse module if you’re using a Python version older than 2.7
  1240. (python-argparse on most distributions).
  1241. Just like for the duration graph, a BR2_GRAPH_OUT environment
  1242. variable is supported to adjust the output file format. See
  1243. Section 8.9, “Graphing the dependencies between packages” for details
  1244. about this environment variable.
  1245. Additionally, one may set the environment variable
  1246. BR2_GRAPH_SIZE_OPTS to further control the generated graph. Accepted
  1247. options are:
  1248. * --size-limit X, -l X, will group all packages which individual
  1249. contribution is below X percent, to a single entry labelled
  1250. Others in the graph. By default, X=0.01, which means packages
  1251. each contributing less than 1% are grouped under Others. Accepted
  1252. values are in the range [0.0..1.0].
  1253. * --iec, --binary, --si, --decimal, to use IEC (binary, powers of
  1254. 1024) or SI (decimal, powers of 1000; the default) prefixes.
  1255. * --biggest-first, to sort packages in decreasing size order,
  1256. rather than in increasing size order.
  1257. Note. The collected filesystem size data is only meaningful after a
  1258. complete clean rebuild. Be sure to run make clean all before using
  1259. make graph-size.
  1260. To compare the root filesystem size of two different Buildroot
  1261. compilations, for example after adjusting the configuration or when
  1262. switching to another Buildroot release, use the size-stats-compare
  1263. script. It takes two file-size-stats.csv files (produced by make
  1264. graph-size) as input. Refer to the help text of this script for more
  1265. details:
  1266. utils/size-stats-compare -h
  1267. 8.12. Top-level parallel build
  1268. Note. This section deals with a very experimental feature, which is
  1269. known to break even in some non-unusual situations. Use at your own
  1270. risk.
  1271. Buildroot has always been capable of using parallel build on a per
  1272. package basis: each package is built by Buildroot using make -jN (or
  1273. the equivalent invocation for non-make-based build systems). The
  1274. level of parallelism is by default number of CPUs + 1, but it can be
  1275. adjusted using the BR2_JLEVEL configuration option.
  1276. Until 2020.02, Buildroot was however building packages in a serial
  1277. fashion: each package was built one after the other, without
  1278. parallelization of the build between packages. As of 2020.02,
  1279. Buildroot has experimental support for top-level parallel build,
  1280. which allows some signicant build time savings by building packages
  1281. that have no dependency relationship in parallel. This feature is
  1282. however marked as experimental and is known not to work in some
  1283. cases.
  1284. In order to use top-level parallel build, one must:
  1285. 1. Enable the option BR2_PER_PACKAGE_DIRECTORIES in the Buildroot
  1286. configuration
  1287. 2. Use make -jN when starting the Buildroot build
  1288. Internally, the BR2_PER_PACKAGE_DIRECTORIES will enable a mechanism
  1289. called per-package directories, which will have the following
  1290. effects:
  1291. * Instead of a global target directory and a global host directory
  1292. common to all packages, per-package target and host directories
  1293. will be used, in $(O)/per-package/<pkg>/target/ and $(O)/
  1294. per-package/<pkg>/host/ respectively. Those folders will be
  1295. populated from the corresponding folders of the package
  1296. dependencies at the beginning of <pkg> build. The compiler and
  1297. all other tools will therefore only be able to see and access
  1298. files installed by dependencies explicitly listed by <pkg>.
  1299. * At the end of the build, the global target and host directories
  1300. will be populated, located in $(O)/target and $(O)/host
  1301. respectively. This means that during the build, those folders
  1302. will be empty and it’s only at the very end of the build that
  1303. they will be populated.
  1304. 8.13. Integration with Eclipse
  1305. While a part of the embedded Linux developers like classical text
  1306. editors like Vim or Emacs, and command-line based interfaces, a
  1307. number of other embedded Linux developers like richer graphical
  1308. interfaces to do their development work. Eclipse being one of the
  1309. most popular Integrated Development Environment, Buildroot integrates
  1310. with Eclipse in order to ease the development work of Eclipse users.
  1311. Our integration with Eclipse simplifies the compilation, remote
  1312. execution and remote debugging of applications and libraries that are
  1313. built on top of a Buildroot system. It does not integrate the
  1314. Buildroot configuration and build processes themselves with Eclipse.
  1315. Therefore, the typical usage model of our Eclipse integration would
  1316. be:
  1317. * Configure your Buildroot system with make menuconfig, make
  1318. xconfig or any other configuration interface provided with
  1319. Buildroot.
  1320. * Build your Buildroot system by running make.
  1321. * Start Eclipse to develop, execute and debug your own custom
  1322. applications and libraries, that will rely on the libraries built
  1323. and installed by Buildroot.
  1324. The Buildroot Eclipse integration installation process and usage is
  1325. described in detail at https://github.com/mbats/
  1326. eclipse-buildroot-bundle/wiki.
  1327. 8.14. Advanced usage
  1328. 8.14.1. Using the generated toolchain outside Buildroot
  1329. You may want to compile, for your target, your own programs or other
  1330. software that are not packaged in Buildroot. In order to do this you
  1331. can use the toolchain that was generated by Buildroot.
  1332. The toolchain generated by Buildroot is located by default in output/
  1333. host/. The simplest way to use it is to add output/host/bin/ to your
  1334. PATH environment variable and then to use ARCH-linux-gcc,
  1335. ARCH-linux-objdump, ARCH-linux-ld, etc.
  1336. Alternatively, Buildroot can also export the toolchain and the
  1337. development files of all selected packages, as an SDK, by running the
  1338. command make sdk. This generates a tarball of the content of the host
  1339. directory output/host/, named <TARGET-TUPLE>_sdk-buildroot.tar.gz
  1340. (which can be overriden by setting the environment variable
  1341. BR2_SDK_PREFIX) and located in the output directory output/images/.
  1342. This tarball can then be distributed to application developers, when
  1343. they want to develop their applications that are not (yet) packaged
  1344. as a Buildroot package.
  1345. Upon extracting the SDK tarball, the user must run the script
  1346. relocate-sdk.sh (located at the top directory of the SDK), to make
  1347. sure all paths are updated with the new location.
  1348. Alternatively, if you just want to prepare the SDK without generating
  1349. the tarball (e.g. because you will just be moving the host directory,
  1350. or will be generating the tarball on your own), Buildroot also allows
  1351. you to just prepare the SDK with make prepare-sdk without actually
  1352. generating a tarball.
  1353. For your convenience, by selecting the option
  1354. BR2_PACKAGE_HOST_ENVIRONMENT_SETUP, you can get a setup-environment
  1355. script installed in output/host/ and therefore in your SDK. This
  1356. script can be sourced with . your/sdk/path/environment-setup to
  1357. export a number of environment variables that will help cross-compile
  1358. your projects using the Buildroot SDK: the PATH will contain the SDK
  1359. binaries, standard autotools variables will be defined with the
  1360. appropriate values, and CONFIGURE_FLAGS will contain basic ./
  1361. configure options to cross-compile autotools projects. It also
  1362. provides some useful commands. Note however that once this script is
  1363. sourced, the environment is setup only for cross-compilation, and no
  1364. longer for native compilation.
  1365. 8.14.2. Using gdb in Buildroot
  1366. Buildroot allows to do cross-debugging, where the debugger runs on
  1367. the build machine and communicates with gdbserver on the target to
  1368. control the execution of the program.
  1369. To achieve this:
  1370. * If you are using an internal toolchain (built by Buildroot), you
  1371. must enable BR2_PACKAGE_HOST_GDB, BR2_PACKAGE_GDB and
  1372. BR2_PACKAGE_GDB_SERVER. This ensures that both the cross gdb and
  1373. gdbserver get built, and that gdbserver gets installed to your
  1374. target.
  1375. * If you are using an external toolchain, you should enable
  1376. BR2_TOOLCHAIN_EXTERNAL_GDB_SERVER_COPY, which will copy the
  1377. gdbserver included with the external toolchain to the target. If
  1378. your external toolchain does not have a cross gdb or gdbserver,
  1379. it is also possible to let Buildroot build them, by enabling the
  1380. same options as for the internal toolchain backend.
  1381. Now, to start debugging a program called foo, you should run on the
  1382. target:
  1383. gdbserver :2345 foo
  1384. This will cause gdbserver to listen on TCP port 2345 for a connection
  1385. from the cross gdb.
  1386. Then, on the host, you should start the cross gdb using the following
  1387. command line:
  1388. <buildroot>/output/host/bin/<tuple>-gdb -x <buildroot>/output/staging/usr/share/buildroot/gdbinit foo
  1389. Of course, foo must be available in the current directory, built with
  1390. debugging symbols. Typically you start this command from the
  1391. directory where foo is built (and not from output/target/ as the
  1392. binaries in that directory are stripped).
  1393. The <buildroot>/output/staging/usr/share/buildroot/gdbinit file will
  1394. tell the cross gdb where to find the libraries of the target.
  1395. Finally, to connect to the target from the cross gdb:
  1396. (gdb) target remote <target ip address>:2345
  1397. 8.14.3. Using ccache in Buildroot
  1398. ccache [http://ccache.samba.org] is a compiler cache. It stores the
  1399. object files resulting from each compilation process, and is able to
  1400. skip future compilation of the same source file (with same compiler
  1401. and same arguments) by using the pre-existing object files. When
  1402. doing almost identical builds from scratch a number of times, it can
  1403. nicely speed up the build process.
  1404. ccache support is integrated in Buildroot. You just have to enable
  1405. Enable compiler cache in Build options. This will automatically build
  1406. ccache and use it for every host and target compilation.
  1407. The cache is located in $HOME/.buildroot-ccache. It is stored outside
  1408. of Buildroot output directory so that it can be shared by separate
  1409. Buildroot builds. If you want to get rid of the cache, simply remove
  1410. this directory.
  1411. You can get statistics on the cache (its size, number of hits,
  1412. misses, etc.) by running make ccache-stats.
  1413. The make target ccache-options and the CCACHE_OPTIONS variable
  1414. provide more generic access to the ccache. For example
  1415. # set cache limit size
  1416. make CCACHE_OPTIONS="--max-size=5G" ccache-options
  1417. # zero statistics counters
  1418. make CCACHE_OPTIONS="--zero-stats" ccache-options
  1419. ccache makes a hash of the source files and of the compiler options.
  1420. If a compiler option is different, the cached object file will not be
  1421. used. Many compiler options, however, contain an absolute path to the
  1422. staging directory. Because of this, building in a different output
  1423. directory would lead to many cache misses.
  1424. To avoid this issue, buildroot has the Use relative paths option
  1425. (BR2_CCACHE_USE_BASEDIR). This will rewrite all absolute paths that
  1426. point inside the output directory into relative paths. Thus, changing
  1427. the output directory no longer leads to cache misses.
  1428. A disadvantage of the relative paths is that they also end up to be
  1429. relative paths in the object file. Therefore, for example, the
  1430. debugger will no longer find the file, unless you cd to the output
  1431. directory first.
  1432. See the ccache manual’s section on "Compiling in different
  1433. directories" [https://ccache.samba.org/manual.html#
  1434. _compiling_in_different_directories] for more details about this
  1435. rewriting of absolute paths.
  1436. 8.14.4. Location of downloaded packages
  1437. The various tarballs that are downloaded by Buildroot are all stored
  1438. in BR2_DL_DIR, which by default is the dl directory. If you want to
  1439. keep a complete version of Buildroot which is known to be working
  1440. with the associated tarballs, you can make a copy of this directory.
  1441. This will allow you to regenerate the toolchain and the target
  1442. filesystem with exactly the same versions.
  1443. If you maintain several Buildroot trees, it might be better to have a
  1444. shared download location. This can be achieved by pointing the
  1445. BR2_DL_DIR environment variable to a directory. If this is set, then
  1446. the value of BR2_DL_DIR in the Buildroot configuration is overridden.
  1447. The following line should be added to <~/.bashrc>.
  1448. export BR2_DL_DIR=<shared download location>
  1449. The download location can also be set in the .config file, with the
  1450. BR2_DL_DIR option. Unlike most options in the .config file, this
  1451. value is overridden by the BR2_DL_DIR environment variable.
  1452. 8.14.5. Package-specific make targets
  1453. Running make <package> builds and installs that particular package
  1454. and its dependencies.
  1455. For packages relying on the Buildroot infrastructure, there are
  1456. numerous special make targets that can be called independently like
  1457. this:
  1458. make <package>-<target>
  1459. The package build targets are (in the order they are executed):
  1460. +------------------------------------------------------------+
  1461. |command/target |Description |
  1462. |---------------+--------------------------------------------|
  1463. | source |Fetch the source (download the tarball, |
  1464. | |clone the source repository, etc) |
  1465. |---------------+--------------------------------------------|
  1466. | depends |Build and install all dependencies required |
  1467. | |to build the package |
  1468. |---------------+--------------------------------------------|
  1469. | extract |Put the source in the package build |
  1470. | |directory (extract the tarball, copy the |
  1471. | |source, etc) |
  1472. |---------------+--------------------------------------------|
  1473. | patch |Apply the patches, if any |
  1474. |---------------+--------------------------------------------|
  1475. | configure |Run the configure commands, if any |
  1476. |---------------+--------------------------------------------|
  1477. | build |Run the compilation commands |
  1478. |---------------+--------------------------------------------|
  1479. |install-staging|target package: Run the installation of the |
  1480. | |package in the staging directory, if |
  1481. | |necessary |
  1482. |---------------+--------------------------------------------|
  1483. |install-target |target package: Run the installation of the |
  1484. | |package in the target directory, if |
  1485. | |necessary |
  1486. |---------------+--------------------------------------------|
  1487. | install |target package: Run the 2 previous |
  1488. | |installation commands |
  1489. | | |
  1490. | |host package: Run the installation of the |
  1491. | |package in the host directory |
  1492. +------------------------------------------------------------+
  1493. Additionally, there are some other useful make targets:
  1494. +------------------------------------------------------------+
  1495. | command/target |Description |
  1496. |-----------------------+------------------------------------|
  1497. | show-depends |Displays the first-order |
  1498. | |dependencies required to build the |
  1499. | |package |
  1500. |-----------------------+------------------------------------|
  1501. |show-recursive-depends |Recursively displays the |
  1502. | |dependencies required to build the |
  1503. | |package |
  1504. |-----------------------+------------------------------------|
  1505. | show-rdepends |Displays the first-order reverse |
  1506. | |dependencies of the package (i.e |
  1507. | |packages that directly depend on it)|
  1508. |-----------------------+------------------------------------|
  1509. |show-recursive-rdepends|Recursively displays the reverse |
  1510. | |dependencies of the package (i.e the|
  1511. | |packages that depend on it, directly|
  1512. | |or indirectly) |
  1513. |-----------------------+------------------------------------|
  1514. | graph-depends |Generate a dependency graph of the |
  1515. | |package, in the context of the |
  1516. | |current Buildroot configuration. See|
  1517. | |this section for more details about |
  1518. | |dependency graphs. |
  1519. |-----------------------+------------------------------------|
  1520. | graph-rdepends |Generate a graph of this package |
  1521. | |reverse dependencies (i.e the |
  1522. | |packages that depend on it, directly|
  1523. | |or indirectly) |
  1524. |-----------------------+------------------------------------|
  1525. | dirclean |Remove the whole package build |
  1526. | |directory |
  1527. |-----------------------+------------------------------------|
  1528. | reinstall |Re-run the install commands |
  1529. |-----------------------+------------------------------------|
  1530. | rebuild |Re-run the compilation commands - |
  1531. | |this only makes sense when using the|
  1532. | |OVERRIDE_SRCDIR feature or when you |
  1533. | |modified a file directly in the |
  1534. | |build directory |
  1535. |-----------------------+------------------------------------|
  1536. | reconfigure |Re-run the configure commands, then |
  1537. | |rebuild - this only makes sense when|
  1538. | |using the OVERRIDE_SRCDIR feature or|
  1539. | |when you modified a file directly in|
  1540. | |the build directory |
  1541. +------------------------------------------------------------+
  1542. 8.14.6. Using Buildroot during development
  1543. The normal operation of Buildroot is to download a tarball, extract
  1544. it, configure, compile and install the software component found
  1545. inside this tarball. The source code is extracted in output/build/
  1546. <package>-<version>, which is a temporary directory: whenever make
  1547. clean is used, this directory is entirely removed, and re-created at
  1548. the next make invocation. Even when a Git or Subversion repository is
  1549. used as the input for the package source code, Buildroot creates a
  1550. tarball out of it, and then behaves as it normally does with
  1551. tarballs.
  1552. This behavior is well-suited when Buildroot is used mainly as an
  1553. integration tool, to build and integrate all the components of an
  1554. embedded Linux system. However, if one uses Buildroot during the
  1555. development of certain components of the system, this behavior is not
  1556. very convenient: one would instead like to make a small change to the
  1557. source code of one package, and be able to quickly rebuild the system
  1558. with Buildroot.
  1559. Making changes directly in output/build/<package>-<version> is not an
  1560. appropriate solution, because this directory is removed on make
  1561. clean.
  1562. Therefore, Buildroot provides a specific mechanism for this use case:
  1563. the <pkg>_OVERRIDE_SRCDIR mechanism. Buildroot reads an override
  1564. file, which allows the user to tell Buildroot the location of the
  1565. source for certain packages.
  1566. The default location of the override file is $(CONFIG_DIR)/local.mk,
  1567. as defined by the BR2_PACKAGE_OVERRIDE_FILE configuration option. $
  1568. (CONFIG_DIR) is the location of the Buildroot .config file, so
  1569. local.mk by default lives side-by-side with the .config file, which
  1570. means:
  1571. * In the top-level Buildroot source directory for in-tree builds
  1572. (i.e., when O= is not used)
  1573. * In the out-of-tree directory for out-of-tree builds (i.e., when O
  1574. = is used)
  1575. If a different location than these defaults is required, it can be
  1576. specified through the BR2_PACKAGE_OVERRIDE_FILE configuration option.
  1577. In this override file, Buildroot expects to find lines of the form:
  1578. <pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources
  1579. <pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources
  1580. For example:
  1581. LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
  1582. BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/
  1583. When Buildroot finds that for a given package, an <pkg>
  1584. _OVERRIDE_SRCDIR has been defined, it will no longer attempt to
  1585. download, extract and patch the package. Instead, it will directly
  1586. use the source code available in the specified directory and make
  1587. clean will not touch this directory. This allows to point Buildroot
  1588. to your own directories, that can be managed by Git, Subversion, or
  1589. any other version control system. To achieve this, Buildroot will use
  1590. rsync to copy the source code of the component from the specified
  1591. <pkg>_OVERRIDE_SRCDIR to output/build/<package>-custom/.
  1592. This mechanism is best used in conjunction with the make <pkg>
  1593. -rebuild and make <pkg>-reconfigure targets. A make <pkg>-rebuild all
  1594. sequence will rsync the source code from <pkg>_OVERRIDE_SRCDIR to
  1595. output/build/<package>-custom (thanks to rsync, only the modified
  1596. files are copied), and restart the build process of just this
  1597. package.
  1598. In the example of the linux package above, the developer can then
  1599. make a source code change in /home/bob/linux and then run:
  1600. make linux-rebuild all
  1601. and in a matter of seconds gets the updated Linux kernel image in
  1602. output/images. Similarly, a change can be made to the BusyBox source
  1603. code in /home/bob/busybox, and after:
  1604. make busybox-rebuild all
  1605. the root filesystem image in output/images contains the updated
  1606. BusyBox.
  1607. Source trees for big projects often contain hundreds or thousands of
  1608. files which are not needed for building, but will slow down the
  1609. process of copying the sources with rsync. Optionally, it is possible
  1610. define <pkg>_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS to skip syncing certain
  1611. files from the source tree. For example, when working on the
  1612. webkitgtk package, the following will exclude the tests and in-tree
  1613. builds from a local WebKit source tree:
  1614. WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit
  1615. WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \
  1616. --exclude JSTests --exclude ManualTests --exclude PerformanceTests \
  1617. --exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \
  1618. --exclude WebKit.xcworkspace --exclude Websites --exclude Examples
  1619. By default, Buildroot skips syncing of VCS artifacts (e.g., the .git
  1620. and .svn directories). Some packages prefer to have these VCS
  1621. directories available during build, for example for automatically
  1622. determining a precise commit reference for version information. To
  1623. undo this built-in filtering at a cost of a slower speed, add these
  1624. directories back:
  1625. LINUX_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = --include .git
  1626. Chapter 9. Project-specific customization
  1627. Typical actions you may need to perform for a given project are:
  1628. * configuring Buildroot (including build options and toolchain,
  1629. bootloader, kernel, package and filesystem image type selection)
  1630. * configuring other components, like the Linux kernel and BusyBox
  1631. * customizing the generated target filesystem
  1632. + adding or overwriting files on the target filesystem (using
  1633. BR2_ROOTFS_OVERLAY)
  1634. + modifying or deleting files on the target filesystem (using
  1635. BR2_ROOTFS_POST_BUILD_SCRIPT)
  1636. + running arbitrary commands prior to generating the filesystem
  1637. image (using BR2_ROOTFS_POST_BUILD_SCRIPT)
  1638. + setting file permissions and ownership (using
  1639. BR2_ROOTFS_DEVICE_TABLE)
  1640. + adding custom devices nodes (using
  1641. BR2_ROOTFS_STATIC_DEVICE_TABLE)
  1642. * adding custom user accounts (using BR2_ROOTFS_USERS_TABLES)
  1643. * running arbitrary commands after generating the filesystem image
  1644. (using BR2_ROOTFS_POST_IMAGE_SCRIPT)
  1645. * adding project-specific patches to some packages (using
  1646. BR2_GLOBAL_PATCH_DIR)
  1647. * adding project-specific packages
  1648. An important note regarding such project-specific customizations:
  1649. please carefully consider which changes are indeed project-specific
  1650. and which changes are also useful to developers outside your project.
  1651. The Buildroot community highly recommends and encourages the
  1652. upstreaming of improvements, packages and board support to the
  1653. official Buildroot project. Of course, it is sometimes not possible
  1654. or desirable to upstream because the changes are highly specific or
  1655. proprietary.
  1656. This chapter describes how to make such project-specific
  1657. customizations in Buildroot and how to store them in a way that you
  1658. can build the same image in a reproducible way, even after running
  1659. make clean. By following the recommended strategy, you can even use
  1660. the same Buildroot tree to build multiple distinct projects!
  1661. 9.1. Recommended directory structure
  1662. When customizing Buildroot for your project, you will be creating one
  1663. or more project-specific files that need to be stored somewhere.
  1664. While most of these files could be placed in any location as their
  1665. path is to be specified in the Buildroot configuration, the Buildroot
  1666. developers recommend a specific directory structure which is
  1667. described in this section.
  1668. Orthogonal to this directory structure, you can choose where you
  1669. place this structure itself: either inside the Buildroot tree, or
  1670. outside of it using a br2-external tree. Both options are valid, the
  1671. choice is up to you.
  1672. +-- board/
  1673. | +-- <company>/
  1674. | +-- <boardname>/
  1675. | +-- linux.config
  1676. | +-- busybox.config
  1677. | +-- <other configuration files>
  1678. | +-- post_build.sh
  1679. | +-- post_image.sh
  1680. | +-- rootfs_overlay/
  1681. | | +-- etc/
  1682. | | +-- <some file>
  1683. | +-- patches/
  1684. | +-- foo/
  1685. | | +-- <some patch>
  1686. | +-- libbar/
  1687. | +-- <some other patches>
  1688. |
  1689. +-- configs/
  1690. | +-- <boardname>_defconfig
  1691. |
  1692. +-- package/
  1693. | +-- <company>/
  1694. | +-- Config.in (if not using a br2-external tree)
  1695. | +-- <company>.mk (if not using a br2-external tree)
  1696. | +-- package1/
  1697. | | +-- Config.in
  1698. | | +-- package1.mk
  1699. | +-- package2/
  1700. | +-- Config.in
  1701. | +-- package2.mk
  1702. |
  1703. +-- Config.in (if using a br2-external tree)
  1704. +-- external.mk (if using a br2-external tree)
  1705. +-- external.desc (if using a br2-external tree)
  1706. Details on the files shown above are given further in this chapter.
  1707. Note: if you choose to place this structure outside of the Buildroot
  1708. tree but in a br2-external tree, the <company> and possibly
  1709. <boardname> components may be superfluous and can be left out.
  1710. 9.1.1. Implementing layered customizations
  1711. It is quite common for a user to have several related projects that
  1712. partly need the same customizations. Instead of duplicating these
  1713. customizations for each project, it is recommended to use a layered
  1714. customization approach, as explained in this section.
  1715. Almost all of the customization methods available in Buildroot, like
  1716. post-build scripts and root filesystem overlays, accept a
  1717. space-separated list of items. The specified items are always treated
  1718. in order, from left to right. By creating more than one such item,
  1719. one for the common customizations and another one for the really
  1720. project-specific customizations, you can avoid unnecessary
  1721. duplication. Each layer is typically embodied by a separate directory
  1722. inside board/<company>/. Depending on your projects, you could even
  1723. introduce more than two layers.
  1724. An example directory structure for where a user has two customization
  1725. layers common and fooboard is:
  1726. +-- board/
  1727. +-- <company>/
  1728. +-- common/
  1729. | +-- post_build.sh
  1730. | +-- rootfs_overlay/
  1731. | | +-- ...
  1732. | +-- patches/
  1733. | +-- ...
  1734. |
  1735. +-- fooboard/
  1736. +-- linux.config
  1737. +-- busybox.config
  1738. +-- <other configuration files>
  1739. +-- post_build.sh
  1740. +-- rootfs_overlay/
  1741. | +-- ...
  1742. +-- patches/
  1743. +-- ...
  1744. For example, if the user has the BR2_GLOBAL_PATCH_DIR configuration
  1745. option set as:
  1746. BR2_GLOBAL_PATCH_DIR="board/<company>/common/patches board/<company>/fooboard/patches"
  1747. then first the patches from the common layer would be applied,
  1748. followed by the patches from the fooboard layer.
  1749. 9.2. Keeping customizations outside of Buildroot
  1750. As already briefly mentioned in Section 9.1, “Recommended directory
  1751. structure”, you can place project-specific customizations in two
  1752. locations:
  1753. * directly within the Buildroot tree, typically maintaining them
  1754. using branches in a version control system so that upgrading to a
  1755. newer Buildroot release is easy.
  1756. * outside of the Buildroot tree, using the br2-external mechanism.
  1757. This mechanism allows to keep package recipes, board support and
  1758. configuration files outside of the Buildroot tree, while still
  1759. having them nicely integrated in the build logic. We call this
  1760. location a br2-external tree. This section explains how to use
  1761. the br2-external mechanism and what to provide in a br2-external
  1762. tree.
  1763. One can tell Buildroot to use one or more br2-external trees by
  1764. setting the BR2_EXTERNAL make variable set to the path(s) of the
  1765. br2-external tree(s) to use. It can be passed to any Buildroot make
  1766. invocation. It is automatically saved in the hidden .br2-external.mk
  1767. file in the output directory. Thanks to this, there is no need to
  1768. pass BR2_EXTERNAL at every make invocation. It can however be changed
  1769. at any time by passing a new value, and can be removed by passing an
  1770. empty value.
  1771. Note. The path to a br2-external tree can be either absolute or
  1772. relative. If it is passed as a relative path, it is important to note
  1773. that it is interpreted relative to the main Buildroot source
  1774. directory, not to the Buildroot output directory.
  1775. Note: If using an br2-external tree from before Buildroot 2016.11,
  1776. you need to convert it before you can use it with Buildroot 2016.11
  1777. onward. See Section 27.1, “Migrating to 2016.11” for help on doing
  1778. so.
  1779. Some examples:
  1780. buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig
  1781. From now on, definitions from the /path/to/foo br2-external tree will
  1782. be used:
  1783. buildroot/ $ make
  1784. buildroot/ $ make legal-info
  1785. We can switch to another br2-external tree at any time:
  1786. buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig
  1787. We can also use multiple br2-external trees:
  1788. buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/where/we/have/bar menuconfig
  1789. Or disable the usage of any br2-external tree:
  1790. buildroot/ $ make BR2_EXTERNAL= xconfig
  1791. 9.2.1. Layout of a br2-external tree
  1792. A br2-external tree must contain at least those three files,
  1793. described in the following chapters:
  1794. * external.desc
  1795. * external.mk
  1796. * Config.in
  1797. Apart from those mandatory files, there may be additional and
  1798. optional content that may be present in a br2-external tree, like the
  1799. configs/ or provides/ directories. They are described in the
  1800. following chapters as well.
  1801. A complete example br2-external tree layout is also described later.
  1802. 9.2.1.1. The external.desc file
  1803. That file describes the br2-external tree: the name and description
  1804. for that br2-external tree.
  1805. The format for this file is line based, with each line starting by a
  1806. keyword, followed by a colon and one or more spaces, followed by the
  1807. value assigned to that keyword. There are two keywords currently
  1808. recognised:
  1809. * name, mandatory, defines the name for that br2-external tree.
  1810. That name must only use ASCII characters in the set [A-Za-z0-9_];
  1811. any other character is forbidden. Buildroot sets the variable
  1812. BR2_EXTERNAL_$(NAME)_PATH to the absolute path of the
  1813. br2-external tree, so that you can use it to refer to your
  1814. br2-external tree. This variable is available both in Kconfig, so
  1815. you can use it to source your Kconfig files (see below) and in
  1816. the Makefile, so that you can use it to include other Makefiles
  1817. (see below) or refer to other files (like data files) from your
  1818. br2-external tree.
  1819. Note: Since it is possible to use multiple br2-external trees at
  1820. once, this name is used by Buildroot to generate variables for
  1821. each of those trees. That name is used to identify your
  1822. br2-external tree, so try to come up with a name that really
  1823. describes your br2-external tree, in order for it to be
  1824. relatively unique, so that it does not clash with another name
  1825. from another br2-external tree, especially if you are planning on
  1826. somehow sharing your br2-external tree with third parties or
  1827. using br2-external trees from third parties.
  1828. * desc, optional, provides a short description for that
  1829. br2-external tree. It shall fit on a single line, is mostly
  1830. free-form (see below), and is used when displaying information
  1831. about a br2-external tree (e.g. above the list of defconfig
  1832. files, or as the prompt in the menuconfig); as such, it should
  1833. relatively brief (40 chars is probably a good upper limit). The
  1834. description is available in the BR2_EXTERNAL_$(NAME)_DESC
  1835. variable.
  1836. Examples of names and the corresponding BR2_EXTERNAL_$(NAME)_PATH
  1837. variables:
  1838. * FOO → BR2_EXTERNAL_FOO_PATH
  1839. * BAR_42 → BR2_EXTERNAL_BAR_42_PATH
  1840. In the following examples, it is assumed the name to be set to
  1841. BAR_42.
  1842. Note: Both BR2_EXTERNAL_$(NAME)_PATH and BR2_EXTERNAL_$(NAME)_DESC
  1843. are available in the Kconfig files and the Makefiles. They are also
  1844. exported in the environment so are available in post-build,
  1845. post-image and in-fakeroot scripts.
  1846. 9.2.1.2. The Config.in and external.mk files
  1847. Those files (which may each be empty) can be used to define package
  1848. recipes (i.e. foo/Config.in and foo/foo.mk like for packages bundled
  1849. in Buildroot itself) or other custom configuration options or make
  1850. logic.
  1851. Buildroot automatically includes the Config.in from each br2-external
  1852. tree to make it appear in the top-level configuration menu, and
  1853. includes the external.mk from each br2-external tree with the rest of
  1854. the makefile logic.
  1855. The main usage of this is to store package recipes. The recommended
  1856. way to do this is to write a Config.in file that looks like:
  1857. source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in"
  1858. source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in"
  1859. Then, have an external.mk file that looks like:
  1860. include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
  1861. And then in $(BR2_EXTERNAL_BAR_42_PATH)/package/package1 and $
  1862. (BR2_EXTERNAL_BAR_42_PATH)/package/package2 create normal Buildroot
  1863. package recipes, as explained in Chapter 18, Adding new packages to
  1864. Buildroot. If you prefer, you can also group the packages in
  1865. subdirectories called <boardname> and adapt the above paths
  1866. accordingly.
  1867. You can also define custom configuration options in Config.in and
  1868. custom make logic in external.mk.
  1869. 9.2.1.3. The configs/ directory
  1870. One can store Buildroot defconfigs in the configs subdirectory of the
  1871. br2-external tree. Buildroot will automatically show them in the
  1872. output of make list-defconfigs and allow them to be loaded with the
  1873. normal make <name>_defconfig command. They will be visible in the
  1874. make list-defconfigs output, below an External configs label that
  1875. contains the name of the br2-external tree they are defined in.
  1876. Note: If a defconfig file is present in more than one br2-external
  1877. tree, then the one from the last br2-external tree is used. It is
  1878. thus possible to override a defconfig bundled in Buildroot or another
  1879. br2-external tree.
  1880. 9.2.1.4. The provides/ directory
  1881. For some packages, Buildroot provides a choice between two (or more)
  1882. implementations of API-compatible such packages. For example, there
  1883. is a choice to choose either libjpeg ot jpeg-turbo; there is one
  1884. between openssl or libressl; there is one to select one of the known,
  1885. pre-configured toolchains…
  1886. It is possible for a br2-external to extend those choices, by
  1887. providing a set of files that define those alternatives:
  1888. * provides/toolchains.in defines the pre-configured toolchains,
  1889. which will then be listed in the toolchain selection;
  1890. * provides/jpeg.in defines the alternative libjpeg implementations;
  1891. * provides/openssl.in defines the alternative openssl
  1892. implementations;
  1893. * provides/skeleton.in defines the alternative skeleton
  1894. implementations;
  1895. * provides/init.in defines the alternative init system
  1896. implementations, this can be used to select a default skeleton
  1897. for your init.
  1898. 9.2.1.5. Free-form content
  1899. One can store all the board-specific configuration files there, such
  1900. as the kernel configuration, the root filesystem overlay, or any
  1901. other configuration file for which Buildroot allows to set the
  1902. location (by using the BR2_EXTERNAL_$(NAME)_PATH variable). For
  1903. example, you could set the paths to a global patch directory, to a
  1904. rootfs overlay and to the kernel configuration file as follows (e.g.
  1905. by running make menuconfig and filling in these options):
  1906. BR2_GLOBAL_PATCH_DIR=$(BR2_EXTERNAL_BAR_42_PATH)/patches/
  1907. BR2_ROOTFS_OVERLAY=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/overlay/
  1908. BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/kernel.config
  1909. 9.2.1.6. Additional Linux kernel extensions
  1910. Additional Linux kernel extensions (see Section 18.21.2,
  1911. “linux-kernel-extensions”) can be added by storing them in the linux/
  1912. directory at the root of a br2-external tree.
  1913. 9.2.1.7. Example layout
  1914. Here is an example layout using all features of br2-external (the
  1915. sample content is shown for the file above it, when it is relevant to
  1916. explain the br2-external tree; this is all entirely made up just for
  1917. the sake of illustration, of course):
  1918. /path/to/br2-ext-tree/
  1919. |- external.desc
  1920. | |name: BAR_42
  1921. | |desc: Example br2-external tree
  1922. | `----
  1923. |
  1924. |- Config.in
  1925. | |source "$BR2_EXTERNAL_BAR_42_PATH/toolchain/toolchain-external-mine/Config.in.options"
  1926. | |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-1/Config.in"
  1927. | |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-2/Config.in"
  1928. | |source "$BR2_EXTERNAL_BAR_42_PATH/package/my-jpeg/Config.in"
  1929. | |
  1930. | |config BAR_42_FLASH_ADDR
  1931. | | hex "my-board flash address"
  1932. | | default 0x10AD
  1933. | `----
  1934. |
  1935. |- external.mk
  1936. | |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
  1937. | |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/toolchain/*/*.mk))
  1938. | |
  1939. | |flash-my-board:
  1940. | | $(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/flash-image \
  1941. | | --image $(BINARIES_DIR)/image.bin \
  1942. | | --address $(BAR_42_FLASH_ADDR)
  1943. | `----
  1944. |
  1945. |- package/pkg-1/Config.in
  1946. | |config BR2_PACKAGE_PKG_1
  1947. | | bool "pkg-1"
  1948. | | help
  1949. | | Some help about pkg-1
  1950. | `----
  1951. |- package/pkg-1/pkg-1.hash
  1952. |- package/pkg-1/pkg-1.mk
  1953. | |PKG_1_VERSION = 1.2.3
  1954. | |PKG_1_SITE = /some/where/to/get/pkg-1
  1955. | |PKG_1_LICENSE = blabla
  1956. | |
  1957. | |define PKG_1_INSTALL_INIT_SYSV
  1958. | | $(INSTALL) -D -m 0755 $(PKG_1_PKGDIR)/S99my-daemon \
  1959. | | $(TARGET_DIR)/etc/init.d/S99my-daemon
  1960. | |endef
  1961. | |
  1962. | |$(eval $(autotools-package))
  1963. | `----
  1964. |- package/pkg-1/S99my-daemon
  1965. |
  1966. |- package/pkg-2/Config.in
  1967. |- package/pkg-2/pkg-2.hash
  1968. |- package/pkg-2/pkg-2.mk
  1969. |
  1970. |- provides/jpeg.in
  1971. | |config BR2_PACKAGE_MY_JPEG
  1972. | | bool "my-jpeg"
  1973. | `----
  1974. |- package/my-jpeg/Config.in
  1975. | |config BR2_PACKAGE_PROVIDES_JPEG
  1976. | | default "my-jpeg" if BR2_PACKAGE_MY_JPEG
  1977. | `----
  1978. |- package/my-jpeg/my-jpeg.mk
  1979. | |# This is a normal package .mk file
  1980. | |MY_JPEG_VERSION = 1.2.3
  1981. | |MY_JPEG_SITE = https://example.net/some/place
  1982. | |MY_JPEG_PROVIDES = jpeg
  1983. | |$(eval $(autotools-package))
  1984. | `----
  1985. |
  1986. |- provides/init.in
  1987. | |config BR2_INIT_MINE
  1988. | | bool "my custom init"
  1989. | | select BR2_PACKAGE_MY_INIT
  1990. | | select BR2_PACKAGE_SKELETON_INIT_MINE if BR2_ROOTFS_SKELETON_DEFAULT
  1991. | `----
  1992. |
  1993. |- provides/skeleton.in
  1994. | |config BR2_ROOTFS_SKELETON_MINE
  1995. | | bool "my custom skeleton"
  1996. | | select BR2_PACKAGE_SKELETON_MINE
  1997. | `----
  1998. |- package/skeleton-mine/Config.in
  1999. | |config BR2_PACKAGE_SKELETON_MINE
  2000. | | bool
  2001. | | select BR2_PACKAGE_HAS_SKELETON
  2002. | |
  2003. | |config BR2_PACKAGE_PROVIDES_SKELETON
  2004. | | default "skeleton-mine" if BR2_PACKAGE_SKELETON_MINE
  2005. | `----
  2006. |- package/skeleton-mine/skeleton-mine.mk
  2007. | |SKELETON_MINE_ADD_TOOLCHAIN_DEPENDENCY = NO
  2008. | |SKELETON_MINE_ADD_SKELETON_DEPENDENCY = NO
  2009. | |SKELETON_MINE_PROVIDES = skeleton
  2010. | |SKELETON_MINE_INSTALL_STAGING = YES
  2011. | |$(eval $(generic-package))
  2012. | `----
  2013. |
  2014. |- provides/toolchains.in
  2015. | |config BR2_TOOLCHAIN_EXTERNAL_MINE
  2016. | | bool "my custom toolchain"
  2017. | | depends on BR2_some_arch
  2018. | | select BR2_INSTALL_LIBSTDCPP
  2019. | `----
  2020. |- toolchain/toolchain-external-mine/Config.in.options
  2021. | |if BR2_TOOLCHAIN_EXTERNAL_MINE
  2022. | |config BR2_TOOLCHAIN_EXTERNAL_PREFIX
  2023. | | default "arch-mine-linux-gnu"
  2024. | |config BR2_PACKAGE_PROVIDES_TOOLCHAIN_EXTERNAL
  2025. | | default "toolchain-external-mine"
  2026. | |endif
  2027. | `----
  2028. |- toolchain/toolchain-external-mine/toolchain-external-mine.mk
  2029. | |TOOLCHAIN_EXTERNAL_MINE_SITE = https://example.net/some/place
  2030. | |TOOLCHAIN_EXTERNAL_MINE_SOURCE = my-toolchain.tar.gz
  2031. | |$(eval $(toolchain-external-package))
  2032. | `----
  2033. |
  2034. |- linux/Config.ext.in
  2035. | |config BR2_LINUX_KERNEL_EXT_EXAMPLE_DRIVER
  2036. | | bool "example-external-driver"
  2037. | | help
  2038. | | Example external driver
  2039. | |---
  2040. |- linux/linux-ext-example-driver.mk
  2041. |
  2042. |- configs/my-board_defconfig
  2043. | |BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_BAR_42_PATH)/patches/"
  2044. | |BR2_ROOTFS_OVERLAY="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/overlay/"
  2045. | |BR2_ROOTFS_POST_IMAGE_SCRIPT="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/post-image.sh"
  2046. | |BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/kernel.config"
  2047. | `----
  2048. |
  2049. |- patches/linux/0001-some-change.patch
  2050. |- patches/linux/0002-some-other-change.patch
  2051. |- patches/busybox/0001-fix-something.patch
  2052. |
  2053. |- board/my-board/kernel.config
  2054. |- board/my-board/overlay/var/www/index.html
  2055. |- board/my-board/overlay/var/www/my.css
  2056. |- board/my-board/flash-image
  2057. `- board/my-board/post-image.sh
  2058. |#!/bin/sh
  2059. |generate-my-binary-image \
  2060. | --root ${BINARIES_DIR}/rootfs.tar \
  2061. | --kernel ${BINARIES_DIR}/zImage \
  2062. | --dtb ${BINARIES_DIR}/my-board.dtb \
  2063. | --output ${BINARIES_DIR}/image.bin
  2064. `----
  2065. The br2-external tree will then be visible in the menuconfig (with
  2066. the layout expanded):
  2067. External options --->
  2068. *** Example br2-external tree (in /path/to/br2-ext-tree/)
  2069. [ ] pkg-1
  2070. [ ] pkg-2
  2071. (0x10AD) my-board flash address
  2072. If you are using more than one br2-external tree, it would look like
  2073. (with the layout expanded and the second one with name FOO_27 but no
  2074. desc: field in external.desc):
  2075. External options --->
  2076. Example br2-external tree --->
  2077. *** Example br2-external tree (in /path/to/br2-ext-tree)
  2078. [ ] pkg-1
  2079. [ ] pkg-2
  2080. (0x10AD) my-board flash address
  2081. FOO_27 --->
  2082. *** FOO_27 (in /path/to/another-br2-ext)
  2083. [ ] foo
  2084. [ ] bar
  2085. Additionally, the jpeg provider will be visible in the jpeg choice:
  2086. Target packages --->
  2087. Libraries --->
  2088. Graphics --->
  2089. [*] jpeg support
  2090. jpeg variant () --->
  2091. ( ) jpeg
  2092. ( ) jpeg-turbo
  2093. *** jpeg from: Example br2-external tree ***
  2094. (X) my-jpeg
  2095. *** jpeg from: FOO_27 ***
  2096. ( ) another-jpeg
  2097. And similarly for the toolchains:
  2098. Toolchain --->
  2099. Toolchain () --->
  2100. ( ) Custom toolchain
  2101. *** Toolchains from: Example br2-external tree ***
  2102. (X) my custom toolchain
  2103. Note. The toolchain options in toolchain/toolchain-external-mine/
  2104. Config.in.options will not appear in the Toolchain menu. They must be
  2105. explicitly included from within the br2-external’s top-level
  2106. Config.in and will thus appear in the External options menu.
  2107. 9.3. Storing the Buildroot configuration
  2108. The Buildroot configuration can be stored using the command make
  2109. savedefconfig.
  2110. This strips the Buildroot configuration down by removing
  2111. configuration options that are at their default value. The result is
  2112. stored in a file called defconfig. If you want to save it in another
  2113. place, change the BR2_DEFCONFIG option in the Buildroot configuration
  2114. itself, or call make with make savedefconfig BR2_DEFCONFIG=
  2115. <path-to-defconfig>.
  2116. The recommended place to store this defconfig is configs/<boardname>
  2117. _defconfig. If you follow this recommendation, the configuration will
  2118. be listed in make help and can be set again by running make
  2119. <boardname>_defconfig.
  2120. Alternatively, you can copy the file to any other place and rebuild
  2121. with make defconfig BR2_DEFCONFIG=<path-to-defconfig-file>.
  2122. 9.4. Storing the configuration of other components
  2123. The configuration files for BusyBox, the Linux kernel, Barebox,
  2124. U-Boot and uClibc should be stored as well if changed. For each of
  2125. these components, a Buildroot configuration option exists to point to
  2126. an input configuration file, e.g.
  2127. BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE. To store their configuration,
  2128. set these configuration options to a path where you want to save the
  2129. configuration files, and then use the helper targets described below
  2130. to actually store the configuration.
  2131. As explained in Section 9.1, “Recommended directory structure”, the
  2132. recommended path to store these configuration files is board/
  2133. <company>/<boardname>/foo.config.
  2134. Make sure that you create a configuration file before changing the
  2135. BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE etc. options. Otherwise,
  2136. Buildroot will try to access this config file, which doesn’t exist
  2137. yet, and will fail. You can create the configuration file by running
  2138. make linux-menuconfig etc.
  2139. Buildroot provides a few helper targets to make the saving of
  2140. configuration files easier.
  2141. * make linux-update-defconfig saves the linux configuration to the
  2142. path specified by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE. It
  2143. simplifies the config file by removing default values. However,
  2144. this only works with kernels starting from 2.6.33. For earlier
  2145. kernels, use make linux-update-config.
  2146. * make busybox-update-config saves the busybox configuration to the
  2147. path specified by BR2_PACKAGE_BUSYBOX_CONFIG.
  2148. * make uclibc-update-config saves the uClibc configuration to the
  2149. path specified by BR2_UCLIBC_CONFIG.
  2150. * make barebox-update-defconfig saves the barebox configuration to
  2151. the path specified by BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE.
  2152. * make uboot-update-defconfig saves the U-Boot configuration to the
  2153. path specified by BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE.
  2154. * For at91bootstrap3, no helper exists so you have to copy the
  2155. config file manually to
  2156. BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE.
  2157. 9.5. Customizing the generated target filesystem
  2158. Besides changing the configuration through make *config, there are a
  2159. few other ways to customize the resulting target filesystem.
  2160. The two recommended methods, which can co-exist, are root filesystem
  2161. overlay(s) and post build script(s).
  2162. Root filesystem overlays (BR2_ROOTFS_OVERLAY)
  2163. A filesystem overlay is a tree of files that is copied directly
  2164. over the target filesystem after it has been built. To enable
  2165. this feature, set config option BR2_ROOTFS_OVERLAY (in the System
  2166. configuration menu) to the root of the overlay. You can even
  2167. specify multiple overlays, space-separated. If you specify a
  2168. relative path, it will be relative to the root of the Buildroot
  2169. tree. Hidden directories of version control systems, like .git,
  2170. .svn, .hg, etc., files called .empty and files ending in ~ are
  2171. excluded from the copy.
  2172. When BR2_ROOTFS_MERGED_USR is enabled, then the overlay must not
  2173. contain the /bin, /lib or /sbin directories, as Buildroot will
  2174. create them as symbolic links to the relevant folders in /usr. In
  2175. such a situation, should the overlay have any programs or
  2176. libraries, they should be placed in /usr/bin, /usr/sbin and /usr/
  2177. lib.
  2178. As shown in Section 9.1, “Recommended directory structure”, the
  2179. recommended path for this overlay is board/<company>/<boardname>/
  2180. rootfs-overlay.
  2181. Post-build scripts (BR2_ROOTFS_POST_BUILD_SCRIPT)
  2182. Post-build scripts are shell scripts called after Buildroot
  2183. builds all the selected software, but before the rootfs images
  2184. are assembled. To enable this feature, specify a space-separated
  2185. list of post-build scripts in config option
  2186. BR2_ROOTFS_POST_BUILD_SCRIPT (in the System configuration menu).
  2187. If you specify a relative path, it will be relative to the root
  2188. of the Buildroot tree.
  2189. Using post-build scripts, you can remove or modify any file in
  2190. your target filesystem. You should, however, use this feature
  2191. with care. Whenever you find that a certain package generates
  2192. wrong or unneeded files, you should fix that package rather than
  2193. work around it with some post-build cleanup scripts.
  2194. As shown in Section 9.1, “Recommended directory structure”, the
  2195. recommended path for this script is board/<company>/<boardname>/
  2196. post_build.sh.
  2197. The post-build scripts are run with the main Buildroot tree as
  2198. current working directory. The path to the target filesystem is
  2199. passed as the first argument to each script. If the config option
  2200. BR2_ROOTFS_POST_SCRIPT_ARGS is not empty, these arguments will be
  2201. passed to the script too. All the scripts will be passed the
  2202. exact same set of arguments, it is not possible to pass different
  2203. sets of arguments to each script.
  2204. In addition, you may also use these environment variables:
  2205. + BR2_CONFIG: the path to the Buildroot .config file
  2206. + HOST_DIR, STAGING_DIR, TARGET_DIR: see Section 18.5.2,
  2207. “generic-package reference”
  2208. + BUILD_DIR: the directory where packages are extracted and
  2209. built
  2210. + BINARIES_DIR: the place where all binary files (aka images)
  2211. are stored
  2212. + BASE_DIR: the base output directory
  2213. Below three more methods of customizing the target filesystem are
  2214. described, but they are not recommended.
  2215. Direct modification of the target filesystem
  2216. For temporary modifications, you can modify the target filesystem
  2217. directly and rebuild the image. The target filesystem is
  2218. available under output/target/. After making your changes, run
  2219. make to rebuild the target filesystem image.
  2220. This method allows you to do anything to the target filesystem,
  2221. but if you need to clean your Buildroot tree using make clean,
  2222. these changes will be lost. Such cleaning is necessary in several
  2223. cases, refer to Section 8.2, “Understanding when a full rebuild
  2224. is necessary” for details. This solution is therefore only useful
  2225. for quick tests: changes do not survive the make clean command.
  2226. Once you have validated your changes, you should make sure that
  2227. they will persist after a make clean, using a root filesystem
  2228. overlay or a post-build script.
  2229. Custom target skeleton (BR2_ROOTFS_SKELETON_CUSTOM)
  2230. The root filesystem image is created from a target skeleton, on
  2231. top of which all packages install their files. The skeleton is
  2232. copied to the target directory output/target before any package
  2233. is built and installed. The default target skeleton provides the
  2234. standard Unix filesystem layout and some basic init scripts and
  2235. configuration files.
  2236. If the default skeleton (available under system/skeleton) does
  2237. not match your needs, you would typically use a root filesystem
  2238. overlay or post-build script to adapt it. However, if the default
  2239. skeleton is entirely different than what you need, using a custom
  2240. skeleton may be more suitable.
  2241. To enable this feature, enable config option
  2242. BR2_ROOTFS_SKELETON_CUSTOM and set
  2243. BR2_ROOTFS_SKELETON_CUSTOM_PATH to the path of your custom
  2244. skeleton. Both options are available in the System configuration
  2245. menu. If you specify a relative path, it will be relative to the
  2246. root of the Buildroot tree.
  2247. Custom skeletons don’t need to contain the /bin, /lib or /sbin
  2248. directories, since they are created automatically during the
  2249. build. When BR2_ROOTFS_MERGED_USR is enabled, then the custom
  2250. skeleton must not contain the /bin, /lib or /sbin directories, as
  2251. Buildroot will create them as symbolic links to the relevant
  2252. folders in /usr. In such a situation, should the skeleton have
  2253. any programs or libraries, they should be placed in /usr/bin, /
  2254. usr/sbin and /usr/lib.
  2255. This method is not recommended because it duplicates the entire
  2256. skeleton, which prevents taking advantage of the fixes or
  2257. improvements brought to the default skeleton in later Buildroot
  2258. releases.
  2259. Post-fakeroot scripts (BR2_ROOTFS_POST_FAKEROOT_SCRIPT)
  2260. When aggregating the final images, some parts of the process
  2261. requires root rights: creating device nodes in /dev, setting
  2262. permissions or ownership to files and directories… To avoid
  2263. requiring actual root rights, Buildroot uses fakeroot to simulate
  2264. root rights. This is not a complete substitute for actually being
  2265. root, but is enough for what Buildroot needs.
  2266. Post-fakeroot scripts are shell scripts that are called at the
  2267. end of the fakeroot phase, right before the filesystem image
  2268. generator is called. As such, they are called in the fakeroot
  2269. context.
  2270. Post-fakeroot scripts can be useful in case you need to tweak the
  2271. filesystem to do modifications that are usually only available to
  2272. the root user.
  2273. Note: It is recommended to use the existing mechanisms to set
  2274. file permissions or create entries in /dev (see Section 9.5.1,
  2275. “Setting file permissions and ownership and adding custom devices
  2276. nodes”) or to create users (see Section 9.6, “Adding custom user
  2277. accounts”)
  2278. Note: The difference between post-build scripts (above) and
  2279. fakeroot scripts, is that post-build scripts are not called in
  2280. the fakeroot context.
  2281. Note: Using fakeroot is not an absolute substitute for actually
  2282. being root. fakeroot only ever fakes the file access rights and
  2283. types (regular, block-or-char device…) and uid/gid; these are
  2284. emulated in-memory.
  2285. 9.5.1. Setting file permissions and ownership and adding custom
  2286. devices nodes
  2287. Sometimes it is needed to set specific permissions or ownership on
  2288. files or device nodes. For example, certain files may need to be
  2289. owned by root. Since the post-build scripts are not run as root, you
  2290. cannot do such changes from there unless you use an explicit fakeroot
  2291. from the post-build script.
  2292. Instead, Buildroot provides support for so-called permission tables.
  2293. To use this feature, set config option BR2_ROOTFS_DEVICE_TABLE to a
  2294. space-separated list of permission tables, regular text files
  2295. following the makedev syntax.
  2296. If you are using a static device table (i.e. not using devtmpfs,
  2297. mdev, or (e)udev) then you can add device nodes using the same
  2298. syntax, in so-called device tables. To use this feature, set config
  2299. option BR2_ROOTFS_STATIC_DEVICE_TABLE to a space-separated list of
  2300. device tables.
  2301. As shown in Section 9.1, “Recommended directory structure”, the
  2302. recommended location for such files is board/<company>/<boardname>/.
  2303. It should be noted that if the specific permissions or device nodes
  2304. are related to a specific application, you should set variables
  2305. FOO_PERMISSIONS and FOO_DEVICES in the package’s .mk file instead
  2306. (see Section 18.5.2, “generic-package reference”).
  2307. 9.6. Adding custom user accounts
  2308. Sometimes it is needed to add specific users in the target system. To
  2309. cover this requirement, Buildroot provides support for so-called
  2310. users tables. To use this feature, set config option
  2311. BR2_ROOTFS_USERS_TABLES to a space-separated list of users tables,
  2312. regular text files following the makeusers syntax.
  2313. As shown in Section 9.1, “Recommended directory structure”, the
  2314. recommended location for such files is board/<company>/<boardname>/.
  2315. It should be noted that if the custom users are related to a specific
  2316. application, you should set variable FOO_USERS in the package’s .mk
  2317. file instead (see Section 18.5.2, “generic-package reference”).
  2318. 9.7. Customization after the images have been created
  2319. While post-build scripts (Section 9.5, “Customizing the generated
  2320. target filesystem”) are run before building the filesystem image,
  2321. kernel and bootloader, post-image scripts can be used to perform some
  2322. specific actions after all images have been created.
  2323. Post-image scripts can for example be used to automatically extract
  2324. your root filesystem tarball in a location exported by your NFS
  2325. server, or to create a special firmware image that bundles your root
  2326. filesystem and kernel image, or any other custom action required for
  2327. your project.
  2328. To enable this feature, specify a space-separated list of post-image
  2329. scripts in config option BR2_ROOTFS_POST_IMAGE_SCRIPT (in the System
  2330. configuration menu). If you specify a relative path, it will be
  2331. relative to the root of the Buildroot tree.
  2332. Just like post-build scripts, post-image scripts are run with the
  2333. main Buildroot tree as current working directory. The path to the
  2334. images output directory is passed as the first argument to each
  2335. script. If the config option BR2_ROOTFS_POST_SCRIPT_ARGS is not
  2336. empty, these arguments will be passed to the script too. All the
  2337. scripts will be passed the exact same set of arguments, it is not
  2338. possible to pass different sets of arguments to each script.
  2339. Again just like for the post-build scripts, the scripts have access
  2340. to the environment variables BR2_CONFIG, HOST_DIR, STAGING_DIR,
  2341. TARGET_DIR, BUILD_DIR, BINARIES_DIR and BASE_DIR.
  2342. The post-image scripts will be executed as the user that executes
  2343. Buildroot, which should normally not be the root user. Therefore, any
  2344. action requiring root permissions in one of these scripts will
  2345. require special handling (usage of fakeroot or sudo), which is left
  2346. to the script developer.
  2347. 9.8. Adding project-specific patches
  2348. It is sometimes useful to apply extra patches to packages - on top of
  2349. those provided in Buildroot. This might be used to support custom
  2350. features in a project, for example, or when working on a new
  2351. architecture.
  2352. The BR2_GLOBAL_PATCH_DIR configuration option can be used to specify
  2353. a space separated list of one or more directories containing package
  2354. patches.
  2355. For a specific version <packageversion> of a specific package
  2356. <packagename>, patches are applied from BR2_GLOBAL_PATCH_DIR as
  2357. follows:
  2358. 1. For every directory - <global-patch-dir> - that exists in
  2359. BR2_GLOBAL_PATCH_DIR, a <package-patch-dir> will be determined as
  2360. follows:
  2361. + <global-patch-dir>/<packagename>/<packageversion>/ if the
  2362. directory exists.
  2363. + Otherwise, <global-patch-dir>/<packagename> if the directory
  2364. exists.
  2365. 2. Patches will then be applied from a <package-patch-dir> as
  2366. follows:
  2367. + If a series file exists in the package directory, then
  2368. patches are applied according to the series file;
  2369. + Otherwise, patch files matching *.patch are applied in
  2370. alphabetical order. So, to ensure they are applied in the
  2371. right order, it is highly recommended to name the patch files
  2372. like this: <number>-<description>.patch, where <number>
  2373. refers to the apply order.
  2374. For information about how patches are applied for a package, see
  2375. Section 19.2, “How patches are applied”
  2376. The BR2_GLOBAL_PATCH_DIR option is the preferred method for
  2377. specifying a custom patch directory for packages. It can be used to
  2378. specify a patch directory for any package in buildroot. It should
  2379. also be used in place of the custom patch directory options that are
  2380. available for packages such as U-Boot and Barebox. By doing this, it
  2381. will allow a user to manage their patches from one top-level
  2382. directory.
  2383. The exception to BR2_GLOBAL_PATCH_DIR being the preferred method for
  2384. specifying custom patches is BR2_LINUX_KERNEL_PATCH.
  2385. BR2_LINUX_KERNEL_PATCH should be used to specify kernel patches that
  2386. are available at a URL. Note: BR2_LINUX_KERNEL_PATCH specifies kernel
  2387. patches that are applied after patches available in
  2388. BR2_GLOBAL_PATCH_DIR, as it is done from a post-patch hook of the
  2389. Linux package.
  2390. 9.9. Adding project-specific packages
  2391. In general, any new package should be added directly in the package
  2392. directory and submitted to the Buildroot upstream project. How to add
  2393. packages to Buildroot in general is explained in full detail in
  2394. Chapter 18, Adding new packages to Buildroot and will not be repeated
  2395. here. However, your project may need some proprietary packages that
  2396. cannot be upstreamed. This section will explain how you can keep such
  2397. project-specific packages in a project-specific directory.
  2398. As shown in Section 9.1, “Recommended directory structure”, the
  2399. recommended location for project-specific packages is package/
  2400. <company>/. If you are using the br2-external tree feature (see
  2401. Section 9.2, “Keeping customizations outside of Buildroot”) the
  2402. recommended location is to put them in a sub-directory named package/
  2403. in your br2-external tree.
  2404. However, Buildroot will not be aware of the packages in this
  2405. location, unless we perform some additional steps. As explained in
  2406. Chapter 18, Adding new packages to Buildroot, a package in Buildroot
  2407. basically consists of two files: a .mk file (describing how to build
  2408. the package) and a Config.in file (describing the configuration
  2409. options for this package).
  2410. Buildroot will automatically include the .mk files in first-level
  2411. subdirectories of the package directory (using the pattern package/*/
  2412. *.mk). If we want Buildroot to include .mk files from deeper
  2413. subdirectories (like package/<company>/package1/) then we simply have
  2414. to add a .mk file in a first-level subdirectory that includes these
  2415. additional .mk files. Therefore, create a file package/<company>/
  2416. <company>.mk with following contents (assuming you have only one
  2417. extra directory level below package/<company>/):
  2418. include $(sort $(wildcard package/<company>/*/*.mk))
  2419. For the Config.in files, create a file package/<company>/Config.in
  2420. that includes the Config.in files of all your packages. An exhaustive
  2421. list has to be provided since wildcards are not supported in the
  2422. source command of kconfig. For example:
  2423. source "package/<company>/package1/Config.in"
  2424. source "package/<company>/package2/Config.in"
  2425. Include this new file package/<company>/Config.in from package/
  2426. Config.in, preferably in a company-specific menu to make merges with
  2427. future Buildroot versions easier.
  2428. If using a br2-external tree, refer to Section 9.2, “Keeping
  2429. customizations outside of Buildroot” for how to fill in those files.
  2430. 9.10. Quick guide to storing your project-specific customizations
  2431. Earlier in this chapter, the different methods for making
  2432. project-specific customizations have been described. This section
  2433. will now summarize all this by providing step-by-step instructions to
  2434. storing your project-specific customizations. Clearly, the steps that
  2435. are not relevant to your project can be skipped.
  2436. 1. make menuconfig to configure toolchain, packages and kernel.
  2437. 2. make linux-menuconfig to update the kernel config, similar for
  2438. other configuration like busybox, uclibc, …
  2439. 3. mkdir -p board/<manufacturer>/<boardname>
  2440. 4. Set the following options to board/<manufacturer>/<boardname>/
  2441. <package>.config (as far as they are relevant):
  2442. + BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE
  2443. + BR2_PACKAGE_BUSYBOX_CONFIG
  2444. + BR2_UCLIBC_CONFIG
  2445. + BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE
  2446. + BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE
  2447. + BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE
  2448. 5. Write the configuration files:
  2449. + make linux-update-defconfig
  2450. + make busybox-update-config
  2451. + make uclibc-update-config
  2452. + cp <output>/build/at91bootstrap3-*/.config board/
  2453. <manufacturer>/<boardname>/at91bootstrap3.config
  2454. + make barebox-update-defconfig
  2455. + make uboot-update-defconfig
  2456. 6. Create board/<manufacturer>/<boardname>/rootfs-overlay/ and fill
  2457. it with additional files you need on your rootfs, e.g. board/
  2458. <manufacturer>/<boardname>/rootfs-overlay/etc/inittab. Set
  2459. BR2_ROOTFS_OVERLAY to board/<manufacturer>/<boardname>/
  2460. rootfs-overlay.
  2461. 7. Create a post-build script board/<manufacturer>/<boardname>/
  2462. post_build.sh. Set BR2_ROOTFS_POST_BUILD_SCRIPT to board/
  2463. <manufacturer>/<boardname>/post_build.sh
  2464. 8. If additional setuid permissions have to be set or device nodes
  2465. have to be created, create board/<manufacturer>/<boardname>/
  2466. device_table.txt and add that path to BR2_ROOTFS_DEVICE_TABLE.
  2467. 9. If additional user accounts have to be created, create board/
  2468. <manufacturer>/<boardname>/users_table.txt and add that path to
  2469. BR2_ROOTFS_USERS_TABLES.
  2470. 10. To add custom patches to certain packages, set
  2471. BR2_GLOBAL_PATCH_DIR to board/<manufacturer>/<boardname>/patches/
  2472. and add your patches for each package in a subdirectory named
  2473. after the package. Each patch should be called <packagename>-
  2474. <num>-<description>.patch.
  2475. 11. Specifically for the Linux kernel, there also exists the option
  2476. BR2_LINUX_KERNEL_PATCH with as main advantage that it can also
  2477. download patches from a URL. If you do not need this,
  2478. BR2_GLOBAL_PATCH_DIR is preferred. U-Boot, Barebox, at91bootstrap
  2479. and at91bootstrap3 also have separate options, but these do not
  2480. provide any advantage over BR2_GLOBAL_PATCH_DIR and will likely
  2481. be removed in the future.
  2482. 12. If you need to add project-specific packages, create package/
  2483. <manufacturer>/ and place your packages in that directory. Create
  2484. an overall <manufacturer>.mk file that includes the .mk files of
  2485. all your packages. Create an overall Config.in file that sources
  2486. the Config.in files of all your packages. Include this Config.in
  2487. file from Buildroot’s package/Config.in file.
  2488. 13. make savedefconfig to save the buildroot configuration.
  2489. 14. cp defconfig configs/<boardname>_defconfig
  2490. Chapter 10. Using SELinux in Buildroot
  2491. SELinux [https://selinuxproject.org] is a Linux kernel security
  2492. module enforcing access control policies. In addition to the
  2493. traditional file permissions and access control lists, SELinux allows
  2494. to write rules for users or processes to access specific functions of
  2495. resources (files, sockets…).
  2496. SELinux has three modes of operation:
  2497. * Disabled: the policy is not applied
  2498. * Permissive: the policy is applied, and non-authorized actions are
  2499. simply logged. This mode is often used for troubleshooting
  2500. SELinux issues.
  2501. * Enforcing: the policy is applied, and non-authorized actions are
  2502. denied
  2503. In Buildroot the mode of operation is controlled by the
  2504. BR2_PACKAGE_REFPOLICY_POLICY_STATE_* configuration options. The Linux
  2505. kernel also has various configuration options that affect how SELinux
  2506. is enabled (see security/selinux/Kconfig in the Linux kernel
  2507. sources).
  2508. By default in Buildroot the SELinux policy is provided by the
  2509. upstream refpolicy [https://github.com/SELinuxProject/refpolicy]
  2510. project, enabled with BR2_PACKAGE_REFPOLICY.
  2511. 10.1. Enabling SELinux support
  2512. To have proper support for SELinux in a Buildroot generated system,
  2513. the following configuration options must be enabled:
  2514. * BR2_PACKAGE_LIBSELINUX
  2515. * BR2_PACKAGE_REFPOLICY
  2516. In addition, your filesystem image format must support extended
  2517. attributes.
  2518. 10.2. SELinux policy tweaking
  2519. The SELinux refpolicy contains modules that can be enabled or
  2520. disabled when being built. Each module provide a number of SELinux
  2521. rules. In Buildroot the non-base modules are disabled by default and
  2522. several ways to enable such modules are provided:
  2523. * Packages can enable a list of SELinux modules within the
  2524. refpolicy using the <packagename>_SELINUX_MODULES variable.
  2525. * Packages can provide additional SELinux modules by putting them
  2526. (.fc, .if and .te files) in package/<packagename>/selinux/.
  2527. * Extra SELinux modules can be added in directories pointed by the
  2528. BR2_REFPOLICY_EXTRA_MODULES_DIRS configuration option.
  2529. * Additional modules in the refpolicy can be enabled if listed in
  2530. the BR2_REFPOLICY_EXTRA_MODULES_DEPENDENCIES configuration
  2531. option.
  2532. Buildroot also allows to completely override the refpolicy. This
  2533. allows to provide a full custom policy designed specifically for a
  2534. given system. When going this way, all of the above mechanisms are
  2535. disabled: no extra SElinux module is added to the policy, and all the
  2536. available modules within the custom policy are enabled and built into
  2537. the final binary policy. The custom policy must be a fork of the
  2538. official refpolicy [https://github.com/SELinuxProject/refpolicy].
  2539. In order to fully override the refpolicy the following configuration
  2540. variables have to be set:
  2541. * BR2_PACKAGE_REFPOLICY_CUSTOM_GIT
  2542. * BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_URL
  2543. * BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_VERSION
  2544. Chapter 11. Frequently Asked Questions & Troubleshooting
  2545. 11.1. The boot hangs after Starting network…
  2546. If the boot process seems to hang after the following messages
  2547. (messages not necessarily exactly similar, depending on the list of
  2548. packages selected):
  2549. Freeing init memory: 3972K
  2550. Initializing random number generator... done.
  2551. Starting network...
  2552. Starting dropbear sshd: generating rsa key... generating dsa key... OK
  2553. then it means that your system is running, but didn’t start a shell
  2554. on the serial console. In order to have the system start a shell on
  2555. your serial console, you have to go into the Buildroot configuration,
  2556. in System configuration, modify Run a getty (login prompt) after boot
  2557. and set the appropriate port and baud rate in the getty options
  2558. submenu. This will automatically tune the /etc/inittab file of the
  2559. generated system so that a shell starts on the correct serial port.
  2560. 11.2. Why is there no compiler on the target?
  2561. It has been decided that support for the native compiler on the
  2562. target would be stopped from the Buildroot-2012.11 release because:
  2563. * this feature was neither maintained nor tested, and often broken;
  2564. * this feature was only available for Buildroot toolchains;
  2565. * Buildroot mostly targets small or very small target hardware with
  2566. limited resource onboard (CPU, ram, mass-storage), for which
  2567. compiling on the target does not make much sense;
  2568. * Buildroot aims at easing the cross-compilation, making native
  2569. compilation on the target unnecessary.
  2570. If you need a compiler on your target anyway, then Buildroot is not
  2571. suitable for your purpose. In such case, you need a real distribution
  2572. and you should opt for something like:
  2573. * openembedded [http://www.openembedded.org]
  2574. * yocto [https://www.yoctoproject.org]
  2575. * emdebian [http://www.emdebian.org]
  2576. * Fedora [https://fedoraproject.org/wiki/Architectures]
  2577. * openSUSE ARM [http://en.opensuse.org/Portal:ARM]
  2578. * Arch Linux ARM [http://archlinuxarm.org]
  2579. * …
  2580. 11.3. Why are there no development files on the target?
  2581. Since there is no compiler available on the target (see Section 11.2,
  2582. “Why is there no compiler on the target?”), it does not make sense to
  2583. waste space with headers or static libraries.
  2584. Therefore, those files are always removed from the target since the
  2585. Buildroot-2012.11 release.
  2586. 11.4. Why is there no documentation on the target?
  2587. Because Buildroot mostly targets small or very small target hardware
  2588. with limited resource onboard (CPU, ram, mass-storage), it does not
  2589. make sense to waste space with the documentation data.
  2590. If you need documentation data on your target anyway, then Buildroot
  2591. is not suitable for your purpose, and you should look for a real
  2592. distribution (see: Section 11.2, “Why is there no compiler on the
  2593. target?”).
  2594. 11.5. Why are some packages not visible in the Buildroot config menu?
  2595. If a package exists in the Buildroot tree and does not appear in the
  2596. config menu, this most likely means that some of the package’s
  2597. dependencies are not met.
  2598. To know more about the dependencies of a package, search for the
  2599. package symbol in the config menu (see Section 8.1, “make tips”).
  2600. Then, you may have to recursively enable several options (which
  2601. correspond to the unmet dependencies) to finally be able to select
  2602. the package.
  2603. If the package is not visible due to some unmet toolchain options,
  2604. then you should certainly run a full rebuild (see Section 8.1, “make
  2605. tips” for more explanations).
  2606. 11.6. Why not use the target directory as a chroot directory?
  2607. There are plenty of reasons to not use the target directory a chroot
  2608. one, among these:
  2609. * file ownerships, modes and permissions are not correctly set in
  2610. the target directory;
  2611. * device nodes are not created in the target directory.
  2612. For these reasons, commands run through chroot, using the target
  2613. directory as the new root, will most likely fail.
  2614. If you want to run the target filesystem inside a chroot, or as an
  2615. NFS root, then use the tarball image generated in images/ and extract
  2616. it as root.
  2617. 11.7. Why doesn’t Buildroot generate binary packages (.deb, .ipkg…)?
  2618. One feature that is often discussed on the Buildroot list is the
  2619. general topic of "package management". To summarize, the idea would
  2620. be to add some tracking of which Buildroot package installs what
  2621. files, with the goals of:
  2622. * being able to remove files installed by a package when this
  2623. package gets unselected from the menuconfig;
  2624. * being able to generate binary packages (ipk or other format) that
  2625. can be installed on the target without re-generating a new root
  2626. filesystem image.
  2627. In general, most people think it is easy to do: just track which
  2628. package installed what and remove it when the package is unselected.
  2629. However, it is much more complicated than that:
  2630. * It is not only about the target/ directory, but also the sysroot
  2631. in host/<tuple>/sysroot and the host/ directory itself. All files
  2632. installed in those directories by various packages must be
  2633. tracked.
  2634. * When a package is unselected from the configuration, it is not
  2635. sufficient to remove just the files it installed. One must also
  2636. remove all its reverse dependencies (i.e. packages relying on it)
  2637. and rebuild all those packages. For example, package A depends
  2638. optionally on the OpenSSL library. Both are selected, and
  2639. Buildroot is built. Package A is built with crypto support using
  2640. OpenSSL. Later on, OpenSSL gets unselected from the
  2641. configuration, but package A remains (since OpenSSL is an
  2642. optional dependency, this is possible.) If only OpenSSL files are
  2643. removed, then the files installed by package A are broken: they
  2644. use a library that is no longer present on the target. Although
  2645. this is technically doable, it adds a lot of complexity to
  2646. Buildroot, which goes against the simplicity we try to stick to.
  2647. * In addition to the previous problem, there is the case where the
  2648. optional dependency is not even known to Buildroot. For example,
  2649. package A in version 1.0 never used OpenSSL, but in version 2.0
  2650. it automatically uses OpenSSL if available. If the Buildroot .mk
  2651. file hasn’t been updated to take this into account, then package
  2652. A will not be part of the reverse dependencies of OpenSSL and
  2653. will not be removed and rebuilt when OpenSSL is removed. For
  2654. sure, the .mk file of package A should be fixed to mention this
  2655. optional dependency, but in the mean time, you can have
  2656. non-reproducible behaviors.
  2657. * The request is to also allow changes in the menuconfig to be
  2658. applied on the output directory without having to rebuild
  2659. everything from scratch. However, this is very difficult to
  2660. achieve in a reliable way: what happens when the suboptions of a
  2661. package are changed (we would have to detect this, and rebuild
  2662. the package from scratch and potentially all its reverse
  2663. dependencies), what happens if toolchain options are changed,
  2664. etc. At the moment, what Buildroot does is clear and simple so
  2665. its behaviour is very reliable and it is easy to support users.
  2666. If configuration changes done in menuconfig are applied after the
  2667. next make, then it has to work correctly and properly in all
  2668. situations, and not have some bizarre corner cases. The risk is
  2669. to get bug reports like "I have enabled package A, B and C, then
  2670. ran make, then disabled package C and enabled package D and ran
  2671. make, then re-enabled package C and enabled package E and then
  2672. there is a build failure". Or worse "I did some configuration,
  2673. then built, then did some changes, built, some more changes,
  2674. built, some more changes, built, and now it fails, but I don’t
  2675. remember all the changes I did and in which order". This will be
  2676. impossible to support.
  2677. For all these reasons, the conclusion is that adding tracking of
  2678. installed files to remove them when the package is unselected, or to
  2679. generate a repository of binary packages, is something that is very
  2680. hard to achieve reliably and will add a lot of complexity.
  2681. On this matter, the Buildroot developers make this position
  2682. statement:
  2683. * Buildroot strives to make it easy to generate a root filesystem
  2684. (hence the name, by the way.) That is what we want to make
  2685. Buildroot good at: building root filesystems.
  2686. * Buildroot is not meant to be a distribution (or rather, a
  2687. distribution generator.) It is the opinion of most Buildroot
  2688. developers that this is not a goal we should pursue. We believe
  2689. that there are other tools better suited to generate a distro
  2690. than Buildroot is. For example, Open Embedded [http://
  2691. openembedded.org/], or openWRT [https://openwrt.org/], are such
  2692. tools.
  2693. * We prefer to push Buildroot in a direction that makes it easy (or
  2694. even easier) to generate complete root filesystems. This is what
  2695. makes Buildroot stands out in the crowd (among other things, of
  2696. course!)
  2697. * We believe that for most embedded Linux systems, binary packages
  2698. are not necessary, and potentially harmful. When binary packages
  2699. are used, it means that the system can be partially upgraded,
  2700. which creates an enormous number of possible combinations of
  2701. package versions that should be tested before doing the upgrade
  2702. on the embedded device. On the other hand, by doing complete
  2703. system upgrades by upgrading the entire root filesystem image at
  2704. once, the image deployed to the embedded system is guaranteed to
  2705. really be the one that has been tested and validated.
  2706. 11.8. How to speed-up the build process?
  2707. Since Buildroot often involves doing full rebuilds of the entire
  2708. system that can be quite long, we provide below a number of tips to
  2709. help reduce the build time:
  2710. * Use a pre-built external toolchain instead of the default
  2711. Buildroot internal toolchain. By using a pre-built Linaro
  2712. toolchain (on ARM) or a Sourcery CodeBench toolchain (for ARM,
  2713. x86, x86-64, MIPS, etc.), you will save the build time of the
  2714. toolchain at each complete rebuild, approximately 15 to 20
  2715. minutes. Note that temporarily using an external toolchain does
  2716. not prevent you to switch back to an internal toolchain (that may
  2717. provide a higher level of customization) once the rest of your
  2718. system is working;
  2719. * Use the ccache compiler cache (see: Section 8.14.3, “Using ccache
  2720. in Buildroot”);
  2721. * Learn about rebuilding only the few packages you actually care
  2722. about (see Section 8.3, “Understanding how to rebuild packages”),
  2723. but beware that sometimes full rebuilds are anyway necessary (see
  2724. Section 8.2, “Understanding when a full rebuild is necessary”);
  2725. * Make sure you are not using a virtual machine for the Linux
  2726. system used to run Buildroot. Most of the virtual machine
  2727. technologies are known to cause a significant performance impact
  2728. on I/O, which is really important for building source code;
  2729. * Make sure that you’re using only local files: do not attempt to
  2730. do a build over NFS, which significantly slows down the build.
  2731. Having the Buildroot download folder available locally also helps
  2732. a bit.
  2733. * Buy new hardware. SSDs and lots of RAM are key to speeding up the
  2734. builds.
  2735. * Experiment with top-level parallel build, see Section 8.12,
  2736. “Top-level parallel build”.
  2737. Chapter 12. Known issues
  2738. * It is not possible to pass extra linker options via
  2739. BR2_TARGET_LDFLAGS if such options contain a $ sign. For example,
  2740. the following is known to break: BR2_TARGET_LDFLAGS="-Wl,-rpath=
  2741. '$ORIGIN/../lib'"
  2742. * The libffi package is not supported on the SuperH 2 and ARC
  2743. architectures.
  2744. * The prboom package triggers a compiler failure with the SuperH 4
  2745. compiler from Sourcery CodeBench, version 2012.09.
  2746. Chapter 13. Legal notice and licensing
  2747. 13.1. Complying with open source licenses
  2748. All of the end products of Buildroot (toolchain, root filesystem,
  2749. kernel, bootloaders) contain open source software, released under
  2750. various licenses.
  2751. Using open source software gives you the freedom to build rich
  2752. embedded systems, choosing from a wide range of packages, but also
  2753. imposes some obligations that you must know and honour. Some licenses
  2754. require you to publish the license text in the documentation of your
  2755. product. Others require you to redistribute the source code of the
  2756. software to those that receive your product.
  2757. The exact requirements of each license are documented in each
  2758. package, and it is your responsibility (or that of your legal office)
  2759. to comply with those requirements. To make this easier for you,
  2760. Buildroot can collect for you some material you will probably need.
  2761. To produce this material, after you have configured Buildroot with
  2762. make menuconfig, make xconfig or make gconfig, run:
  2763. make legal-info
  2764. Buildroot will collect legally-relevant material in your output
  2765. directory, under the legal-info/ subdirectory. There you will find:
  2766. * A README file, that summarizes the produced material and contains
  2767. warnings about material that Buildroot could not produce.
  2768. * buildroot.config: this is the Buildroot configuration file that
  2769. is usually produced with make menuconfig, and which is necessary
  2770. to reproduce the build.
  2771. * The source code for all packages; this is saved in the sources/
  2772. and host-sources/ subdirectories for target and host packages
  2773. respectively. The source code for packages that set <PKG>
  2774. _REDISTRIBUTE = NO will not be saved. Patches that were applied
  2775. are also saved, along with a file named series that lists the
  2776. patches in the order they were applied. Patches are under the
  2777. same license as the files that they modify. Note: Buildroot
  2778. applies additional patches to Libtool scripts of autotools-based
  2779. packages. These patches can be found under support/libtool in the
  2780. Buildroot source and, due to technical limitations, are not saved
  2781. with the package sources. You may need to collect them manually.
  2782. * A manifest file (one for host and one for target packages)
  2783. listing the configured packages, their version, license and
  2784. related information. Some of this information might not be
  2785. defined in Buildroot; such items are marked as "unknown".
  2786. * The license texts of all packages, in the licenses/ and
  2787. host-licenses/ subdirectories for target and host packages
  2788. respectively. If the license file(s) are not defined in
  2789. Buildroot, the file is not produced and a warning in the README
  2790. indicates this.
  2791. Please note that the aim of the legal-info feature of Buildroot is to
  2792. produce all the material that is somehow relevant for legal
  2793. compliance with the package licenses. Buildroot does not try to
  2794. produce the exact material that you must somehow make public.
  2795. Certainly, more material is produced than is needed for a strict
  2796. legal compliance. For example, it produces the source code for
  2797. packages released under BSD-like licenses, that you are not required
  2798. to redistribute in source form.
  2799. Moreover, due to technical limitations, Buildroot does not produce
  2800. some material that you will or may need, such as the toolchain source
  2801. code for some of the external toolchains and the Buildroot source
  2802. code itself. When you run make legal-info, Buildroot produces
  2803. warnings in the README file to inform you of relevant material that
  2804. could not be saved.
  2805. Finally, keep in mind that the output of make legal-info is based on
  2806. declarative statements in each of the packages recipes. The Buildroot
  2807. developers try to do their best to keep those declarative statements
  2808. as accurate as possible, to the best of their knowledge. However, it
  2809. is very well possible that those declarative statements are not all
  2810. fully accurate nor exhaustive. You (or your legal department) have to
  2811. check the output of make legal-info before using it as your own
  2812. compliance delivery. See the NO WARRANTY clauses (clauses 11 and 12)
  2813. in the COPYING file at the root of the Buildroot distribution.
  2814. 13.2. Complying with the Buildroot license
  2815. Buildroot itself is an open source software, released under the GNU
  2816. General Public License, version 2 [http://www.gnu.org/licenses/
  2817. old-licenses/gpl-2.0.html] or (at your option) any later version,
  2818. with the exception of the package patches detailed below. However,
  2819. being a build system, it is not normally part of the end product: if
  2820. you develop the root filesystem, kernel, bootloader or toolchain for
  2821. a device, the code of Buildroot is only present on the development
  2822. machine, not in the device storage.
  2823. Nevertheless, the general view of the Buildroot developers is that
  2824. you should release the Buildroot source code along with the source
  2825. code of other packages when releasing a product that contains
  2826. GPL-licensed software. This is because the GNU GPL [http://
  2827. www.gnu.org/licenses/old-licenses/gpl-2.0.html] defines the "complete
  2828. source code" for an executable work as "all the source code for all
  2829. modules it contains, plus any associated interface definition files,
  2830. plus the scripts used to control compilation and installation of the
  2831. executable". Buildroot is part of the scripts used to control
  2832. compilation and installation of the executable, and as such it is
  2833. considered part of the material that must be redistributed.
  2834. Keep in mind that this is only the Buildroot developers' opinion, and
  2835. you should consult your legal department or lawyer in case of any
  2836. doubt.
  2837. 13.2.1. Patches to packages
  2838. Buildroot also bundles patch files, which are applied to the sources
  2839. of the various packages. Those patches are not covered by the license
  2840. of Buildroot. Instead, they are covered by the license of the
  2841. software to which the patches are applied. When said software is
  2842. available under multiple licenses, the Buildroot patches are only
  2843. provided under the publicly accessible licenses.
  2844. See Chapter 19, Patching a package for the technical details.
  2845. Chapter 14. Beyond Buildroot
  2846. 14.1. Boot the generated images
  2847. 14.1.1. NFS boot
  2848. To achieve NFS-boot, enable tar root filesystem in the Filesystem
  2849. images menu.
  2850. After a complete build, just run the following commands to setup the
  2851. NFS-root directory:
  2852. sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir
  2853. Remember to add this path to /etc/exports.
  2854. Then, you can execute a NFS-boot from your target.
  2855. 14.1.2. Live CD
  2856. To build a live CD image, enable the iso image option in the
  2857. Filesystem images menu. Note that this option is only available on
  2858. the x86 and x86-64 architectures, and if you are building your kernel
  2859. with Buildroot.
  2860. You can build a live CD image with either IsoLinux, Grub or Grub 2 as
  2861. a bootloader, but only Isolinux supports making this image usable
  2862. both as a live CD and live USB (through the Build hybrid image
  2863. option).
  2864. You can test your live CD image using QEMU:
  2865. qemu-system-i386 -cdrom output/images/rootfs.iso9660
  2866. Or use it as a hard-drive image if it is a hybrid ISO:
  2867. qemu-system-i386 -hda output/images/rootfs.iso9660
  2868. It can be easily flashed to a USB drive with dd:
  2869. dd if=output/images/rootfs.iso9660 of=/dev/sdb
  2870. 14.2. Chroot
  2871. If you want to chroot in a generated image, then there are few thing
  2872. you should be aware of:
  2873. * you should setup the new root from the tar root filesystem image;
  2874. * either the selected target architecture is compatible with your
  2875. host machine, or you should use some qemu-* binary and correctly
  2876. set it within the binfmt properties to be able to run the
  2877. binaries built for the target on your host machine;
  2878. * Buildroot does not currently provide host-qemu and binfmt
  2879. correctly built and set for that kind of use.
  2880. Part III. Developer guide
  2881. Table of Contents
  2882. 15. How Buildroot works
  2883. 16. Coding style
  2884. 16.1. Config.in file
  2885. 16.2. The .mk file
  2886. 16.3. The documentation
  2887. 16.4. Support scripts
  2888. 17. Adding support for a particular board
  2889. 18. Adding new packages to Buildroot
  2890. 18.1. Package directory
  2891. 18.2. Config files
  2892. 18.3. The .mk file
  2893. 18.4. The .hash file
  2894. 18.5. Infrastructure for packages with specific build systems
  2895. 18.6. Infrastructure for autotools-based packages
  2896. 18.7. Infrastructure for CMake-based packages
  2897. 18.8. Infrastructure for Python packages
  2898. 18.9. Infrastructure for LuaRocks-based packages
  2899. 18.10. Infrastructure for Perl/CPAN packages
  2900. 18.11. Infrastructure for virtual packages
  2901. 18.12. Infrastructure for packages using kconfig for
  2902. configuration files
  2903. 18.13. Infrastructure for rebar-based packages
  2904. 18.14. Infrastructure for Waf-based packages
  2905. 18.15. Infrastructure for Meson-based packages
  2906. 18.16. Integration of Cargo-based packages
  2907. 18.17. Infrastructure for Go packages
  2908. 18.18. Infrastructure for QMake-based packages
  2909. 18.19. Infrastructure for packages building kernel modules
  2910. 18.20. Infrastructure for asciidoc documents
  2911. 18.21. Infrastructure specific to the Linux kernel package
  2912. 18.22. Hooks available in the various build steps
  2913. 18.23. Gettext integration and interaction with packages
  2914. 18.24. Tips and tricks
  2915. 18.25. Conclusion
  2916. 19. Patching a package
  2917. 19.1. Providing patches
  2918. 19.2. How patches are applied
  2919. 19.3. Format and licensing of the package patches
  2920. 19.4. Integrating patches found on the Web
  2921. 20. Download infrastructure
  2922. 21. Debugging Buildroot
  2923. 22. Contributing to Buildroot
  2924. 22.1. Reproducing, analyzing and fixing bugs
  2925. 22.2. Analyzing and fixing autobuild failures
  2926. 22.3. Reviewing and testing patches
  2927. 22.4. Work on items from the TODO list
  2928. 22.5. Submitting patches
  2929. 22.6. Reporting issues/bugs or getting help
  2930. 22.7. Using the run-tests framework
  2931. 23. DEVELOPERS file and get-developers
  2932. 24. Release Engineering
  2933. 24.1. Releases
  2934. 24.2. Development
  2935. Chapter 15. How Buildroot works
  2936. As mentioned above, Buildroot is basically a set of Makefiles that
  2937. download, configure, and compile software with the correct options.
  2938. It also includes patches for various software packages - mainly the
  2939. ones involved in the cross-compilation toolchain (gcc, binutils and
  2940. uClibc).
  2941. There is basically one Makefile per software package, and they are
  2942. named with the .mk extension. Makefiles are split into many different
  2943. parts.
  2944. * The toolchain/ directory contains the Makefiles and associated
  2945. files for all software related to the cross-compilation
  2946. toolchain: binutils, gcc, gdb, kernel-headers and uClibc.
  2947. * The arch/ directory contains the definitions for all the
  2948. processor architectures that are supported by Buildroot.
  2949. * The package/ directory contains the Makefiles and associated
  2950. files for all user-space tools and libraries that Buildroot can
  2951. compile and add to the target root filesystem. There is one
  2952. sub-directory per package.
  2953. * The linux/ directory contains the Makefiles and associated files
  2954. for the Linux kernel.
  2955. * The boot/ directory contains the Makefiles and associated files
  2956. for the bootloaders supported by Buildroot.
  2957. * The system/ directory contains support for system integration,
  2958. e.g. the target filesystem skeleton and the selection of an init
  2959. system.
  2960. * The fs/ directory contains the Makefiles and associated files for
  2961. software related to the generation of the target root filesystem
  2962. image.
  2963. Each directory contains at least 2 files:
  2964. * something.mk is the Makefile that downloads, configures, compiles
  2965. and installs the package something.
  2966. * Config.in is a part of the configuration tool description file.
  2967. It describes the options related to the package.
  2968. The main Makefile performs the following steps (once the
  2969. configuration is done):
  2970. * Create all the output directories: staging, target, build, etc.
  2971. in the output directory (output/ by default, another value can be
  2972. specified using O=)
  2973. * Generate the toolchain target. When an internal toolchain is
  2974. used, this means generating the cross-compilation toolchain. When
  2975. an external toolchain is used, this means checking the features
  2976. of the external toolchain and importing it into the Buildroot
  2977. environment.
  2978. * Generate all the targets listed in the TARGETS variable. This
  2979. variable is filled by all the individual components' Makefiles.
  2980. Generating these targets will trigger the compilation of the
  2981. userspace packages (libraries, programs), the kernel, the
  2982. bootloader and the generation of the root filesystem images,
  2983. depending on the configuration.
  2984. Chapter 16. Coding style
  2985. Overall, these coding style rules are here to help you to add new
  2986. files in Buildroot or refactor existing ones.
  2987. If you slightly modify some existing file, the important thing is to
  2988. keep the consistency of the whole file, so you can:
  2989. * either follow the potentially deprecated coding style used in
  2990. this file,
  2991. * or entirely rework it in order to make it comply with these
  2992. rules.
  2993. 16.1. Config.in file
  2994. Config.in files contain entries for almost anything configurable in
  2995. Buildroot.
  2996. An entry has the following pattern:
  2997. config BR2_PACKAGE_LIBFOO
  2998. bool "libfoo"
  2999. depends on BR2_PACKAGE_LIBBAZ
  3000. select BR2_PACKAGE_LIBBAR
  3001. help
  3002. This is a comment that explains what libfoo is. The help text
  3003. should be wrapped.
  3004. http://foosoftware.org/libfoo/
  3005. * The bool, depends on, select and help lines are indented with one
  3006. tab.
  3007. * The help text itself should be indented with one tab and two
  3008. spaces.
  3009. * The help text should be wrapped to fit 72 columns, where tab
  3010. counts for 8, so 62 characters in the text itself.
  3011. The Config.in files are the input for the configuration tool used in
  3012. Buildroot, which is the regular Kconfig. For further details about
  3013. the Kconfig language, refer to http://kernel.org/doc/Documentation/
  3014. kbuild/kconfig-language.txt.
  3015. 16.2. The .mk file
  3016. * Header: The file starts with a header. It contains the module
  3017. name, preferably in lowercase, enclosed between separators made
  3018. of 80 hashes. A blank line is mandatory after the header:
  3019. ################################################################################
  3020. #
  3021. # libfoo
  3022. #
  3023. ################################################################################
  3024. * Assignment: use = preceded and followed by one space:
  3025. LIBFOO_VERSION = 1.0
  3026. LIBFOO_CONF_OPTS += --without-python-support
  3027. Do not align the = signs.
  3028. * Indentation: use tab only:
  3029. define LIBFOO_REMOVE_DOC
  3030. $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
  3031. $(TARGET_DIR)/usr/share/man/man3/libfoo*
  3032. endef
  3033. Note that commands inside a define block should always start with
  3034. a tab, so make recognizes them as commands.
  3035. * Optional dependency:
  3036. + Prefer multi-line syntax.
  3037. YES:
  3038. ifeq ($(BR2_PACKAGE_PYTHON),y)
  3039. LIBFOO_CONF_OPTS += --with-python-support
  3040. LIBFOO_DEPENDENCIES += python
  3041. else
  3042. LIBFOO_CONF_OPTS += --without-python-support
  3043. endif
  3044. NO:
  3045. LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
  3046. LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)
  3047. + Keep configure options and dependencies close together.
  3048. * Optional hooks: keep hook definition and assignment together in
  3049. one if block.
  3050. YES:
  3051. ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
  3052. define LIBFOO_REMOVE_DATA
  3053. $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
  3054. endef
  3055. LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
  3056. endif
  3057. NO:
  3058. define LIBFOO_REMOVE_DATA
  3059. $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
  3060. endef
  3061. ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
  3062. LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
  3063. endif
  3064. 16.3. The documentation
  3065. The documentation uses the asciidoc [http://www.methods.co.nz/
  3066. asciidoc/] format.
  3067. For further details about the asciidoc syntax, refer to http://
  3068. www.methods.co.nz/asciidoc/userguide.html.
  3069. 16.4. Support scripts
  3070. Some scripts in the support/ and utils/ directories are written in
  3071. Python and should follow the PEP8 Style Guide for Python Code [https:
  3072. //www.python.org/dev/peps/pep-0008/].
  3073. Chapter 17. Adding support for a particular board
  3074. Buildroot contains basic configurations for several publicly
  3075. available hardware boards, so that users of such a board can easily
  3076. build a system that is known to work. You are welcome to add support
  3077. for other boards to Buildroot too.
  3078. To do so, you need to create a normal Buildroot configuration that
  3079. builds a basic system for the hardware: (internal) toolchain, kernel,
  3080. bootloader, filesystem and a simple BusyBox-only userspace. No
  3081. specific package should be selected: the configuration should be as
  3082. minimal as possible, and should only build a working basic BusyBox
  3083. system for the target platform. You can of course use more
  3084. complicated configurations for your internal projects, but the
  3085. Buildroot project will only integrate basic board configurations.
  3086. This is because package selections are highly application-specific.
  3087. Once you have a known working configuration, run make savedefconfig.
  3088. This will generate a minimal defconfig file at the root of the
  3089. Buildroot source tree. Move this file into the configs/ directory,
  3090. and rename it <boardname>_defconfig. If the configuration is a bit
  3091. more complicated, it is nice to manually reformat it and separate it
  3092. into sections, with a comment before each section. Typical sections
  3093. are Architecture, Toolchain options (typically just linux headers
  3094. version), Firmware, Bootloader, Kernel, and Filesystem.
  3095. Always use fixed versions or commit hashes for the different
  3096. components, not the "latest" version. For example, set
  3097. BR2_LINUX_KERNEL_CUSTOM_VERSION=y and
  3098. BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE to the kernel version you
  3099. tested with.
  3100. It is recommended to use as much as possible upstream versions of the
  3101. Linux kernel and bootloaders, and to use as much as possible default
  3102. kernel and bootloader configurations. If they are incorrect for your
  3103. board, or no default exists, we encourage you to send fixes to the
  3104. corresponding upstream projects.
  3105. However, in the mean time, you may want to store kernel or bootloader
  3106. configuration or patches specific to your target platform. To do so,
  3107. create a directory board/<manufacturer> and a subdirectory board/
  3108. <manufacturer>/<boardname>. You can then store your patches and
  3109. configurations in these directories, and reference them from the main
  3110. Buildroot configuration. Refer to Chapter 9, Project-specific
  3111. customization for more details.
  3112. Chapter 18. Adding new packages to Buildroot
  3113. This section covers how new packages (userspace libraries or
  3114. applications) can be integrated into Buildroot. It also shows how
  3115. existing packages are integrated, which is needed for fixing issues
  3116. or tuning their configuration.
  3117. When you add a new package, be sure to test it in various conditions
  3118. (see Section 18.24.3, “How to test your package”) and also check it
  3119. for coding style (see Section 18.24.2, “How to check the coding
  3120. style”).
  3121. 18.1. Package directory
  3122. First of all, create a directory under the package directory for your
  3123. software, for example libfoo.
  3124. Some packages have been grouped by topic in a sub-directory: x11r7,
  3125. qt5 and gstreamer. If your package fits in one of these categories,
  3126. then create your package directory in these. New subdirectories are
  3127. discouraged, however.
  3128. 18.2. Config files
  3129. For the package to be displayed in the configuration tool, you need
  3130. to create a Config file in your package directory. There are two
  3131. types: Config.in and Config.in.host.
  3132. 18.2.1. Config.in file
  3133. For packages used on the target, create a file named Config.in. This
  3134. file will contain the option descriptions related to our libfoo
  3135. software that will be used and displayed in the configuration tool.
  3136. It should basically contain:
  3137. config BR2_PACKAGE_LIBFOO
  3138. bool "libfoo"
  3139. help
  3140. This is a comment that explains what libfoo is. The help text
  3141. should be wrapped.
  3142. http://foosoftware.org/libfoo/
  3143. The bool line, help line and other metadata information about the
  3144. configuration option must be indented with one tab. The help text
  3145. itself should be indented with one tab and two spaces, lines should
  3146. be wrapped to fit 72 columns, where tab counts for 8, so 62
  3147. characters in the text itself. The help text must mention the
  3148. upstream URL of the project after an empty line.
  3149. As a convention specific to Buildroot, the ordering of the attributes
  3150. is as follows:
  3151. 1. The type of option: bool, string… with the prompt
  3152. 2. If needed, the default value(s)
  3153. 3. Any dependencies on the target in depends on form
  3154. 4. Any dependencies on the toolchain in depends on form
  3155. 5. Any dependencies on other packages in depends on form
  3156. 6. Any dependency of the select form
  3157. 7. The help keyword and help text.
  3158. You can add other sub-options into a if BR2_PACKAGE_LIBFOO…endif
  3159. statement to configure particular things in your software. You can
  3160. look at examples in other packages. The syntax of the Config.in file
  3161. is the same as the one for the kernel Kconfig file. The documentation
  3162. for this syntax is available at http://kernel.org/doc/Documentation/
  3163. kbuild/kconfig-language.txt
  3164. Finally you have to add your new libfoo/Config.in to package/
  3165. Config.in (or in a category subdirectory if you decided to put your
  3166. package in one of the existing categories). The files included there
  3167. are sorted alphabetically per category and are NOT supposed to
  3168. contain anything but the bare name of the package.
  3169. source "package/libfoo/Config.in"
  3170. 18.2.2. Config.in.host file
  3171. Some packages also need to be built for the host system. There are
  3172. two options here:
  3173. * The host package is only required to satisfy build-time
  3174. dependencies of one or more target packages. In this case, add
  3175. host-foo to the target package’s BAR_DEPENDENCIES variable. No
  3176. Config.in.host file should be created.
  3177. * The host package should be explicitly selectable by the user from
  3178. the configuration menu. In this case, create a Config.in.host
  3179. file for that host package:
  3180. config BR2_PACKAGE_HOST_FOO
  3181. bool "host foo"
  3182. help
  3183. This is a comment that explains what foo for the host is.
  3184. http://foosoftware.org/foo/
  3185. The same coding style and options as for the Config.in file are
  3186. valid.
  3187. Finally you have to add your new libfoo/Config.in.host to package
  3188. /Config.in.host. The files included there are sorted
  3189. alphabetically and are NOT supposed to contain anything but the
  3190. bare name of the package.
  3191. source "package/foo/Config.in.host"
  3192. The host package will then be available from the Host utilities
  3193. menu.
  3194. 18.2.3. Choosing depends on or select
  3195. The Config.in file of your package must also ensure that dependencies
  3196. are enabled. Typically, Buildroot uses the following rules:
  3197. * Use a select type of dependency for dependencies on libraries.
  3198. These dependencies are generally not obvious and it therefore
  3199. make sense to have the kconfig system ensure that the
  3200. dependencies are selected. For example, the libgtk2 package uses
  3201. select BR2_PACKAGE_LIBGLIB2 to make sure this library is also
  3202. enabled. The select keyword expresses the dependency with a
  3203. backward semantic.
  3204. * Use a depends on type of dependency when the user really needs to
  3205. be aware of the dependency. Typically, Buildroot uses this type
  3206. of dependency for dependencies on target architecture, MMU
  3207. support and toolchain options (see Section 18.2.4, “Dependencies
  3208. on target and toolchain options”), or for dependencies on "big"
  3209. things, such as the X.org system. The depends on keyword
  3210. expresses the dependency with a forward semantic.
  3211. Note. The current problem with the kconfig language is that these two
  3212. dependency semantics are not internally linked. Therefore, it may be
  3213. possible to select a package, whom one of its dependencies/
  3214. requirement is not met.
  3215. An example illustrates both the usage of select and depends on.
  3216. config BR2_PACKAGE_RRDTOOL
  3217. bool "rrdtool"
  3218. depends on BR2_USE_WCHAR
  3219. select BR2_PACKAGE_FREETYPE
  3220. select BR2_PACKAGE_LIBART
  3221. select BR2_PACKAGE_LIBPNG
  3222. select BR2_PACKAGE_ZLIB
  3223. help
  3224. RRDtool is the OpenSource industry standard, high performance
  3225. data logging and graphing system for time series data.
  3226. http://oss.oetiker.ch/rrdtool/
  3227. comment "rrdtool needs a toolchain w/ wchar"
  3228. depends on !BR2_USE_WCHAR
  3229. Note that these two dependency types are only transitive with the
  3230. dependencies of the same kind.
  3231. This means, in the following example:
  3232. config BR2_PACKAGE_A
  3233. bool "Package A"
  3234. config BR2_PACKAGE_B
  3235. bool "Package B"
  3236. depends on BR2_PACKAGE_A
  3237. config BR2_PACKAGE_C
  3238. bool "Package C"
  3239. depends on BR2_PACKAGE_B
  3240. config BR2_PACKAGE_D
  3241. bool "Package D"
  3242. select BR2_PACKAGE_B
  3243. config BR2_PACKAGE_E
  3244. bool "Package E"
  3245. select BR2_PACKAGE_D
  3246. * Selecting Package C will be visible if Package B has been
  3247. selected, which in turn is only visible if Package A has been
  3248. selected.
  3249. * Selecting Package E will select Package D, which will select
  3250. Package B, it will not check for the dependencies of Package B,
  3251. so it will not select Package A.
  3252. * Since Package B is selected but Package A is not, this violates
  3253. the dependency of Package B on Package A. Therefore, in such a
  3254. situation, the transitive dependency has to be added explicitly:
  3255. config BR2_PACKAGE_D
  3256. bool "Package D"
  3257. select BR2_PACKAGE_B
  3258. depends on BR2_PACKAGE_A
  3259. config BR2_PACKAGE_E
  3260. bool "Package E"
  3261. select BR2_PACKAGE_D
  3262. depends on BR2_PACKAGE_A
  3263. Overall, for package library dependencies, select should be
  3264. preferred.
  3265. Note that such dependencies will ensure that the dependency option is
  3266. also enabled, but not necessarily built before your package. To do
  3267. so, the dependency also needs to be expressed in the .mk file of the
  3268. package.
  3269. Further formatting details: see the coding style.
  3270. 18.2.4. Dependencies on target and toolchain options
  3271. Many packages depend on certain options of the toolchain: the choice
  3272. of C library, C++ support, thread support, RPC support, wchar
  3273. support, or dynamic library support. Some packages can only be built
  3274. on certain target architectures, or if an MMU is available in the
  3275. processor.
  3276. These dependencies have to be expressed with the appropriate depends
  3277. on statements in the Config.in file. Additionally, for dependencies
  3278. on toolchain options, a comment should be displayed when the option
  3279. is not enabled, so that the user knows why the package is not
  3280. available. Dependencies on target architecture or MMU support should
  3281. not be made visible in a comment: since it is unlikely that the user
  3282. can freely choose another target, it makes little sense to show these
  3283. dependencies explicitly.
  3284. The comment should only be visible if the config option itself would
  3285. be visible when the toolchain option dependencies are met. This means
  3286. that all other dependencies of the package (including dependencies on
  3287. target architecture and MMU support) have to be repeated on the
  3288. comment definition. To keep it clear, the depends on statement for
  3289. these non-toolchain option should be kept separate from the depends
  3290. on statement for the toolchain options. If there is a dependency on a
  3291. config option in that same file (typically the main package) it is
  3292. preferable to have a global if … endif construct rather than
  3293. repeating the depends on statement on the comment and other config
  3294. options.
  3295. The general format of a dependency comment for package foo is:
  3296. foo needs a toolchain w/ featA, featB, featC
  3297. for example:
  3298. mpd needs a toolchain w/ C++, threads, wchar
  3299. or
  3300. crda needs a toolchain w/ threads
  3301. Note that this text is kept brief on purpose, so that it will fit on
  3302. a 80-character terminal.
  3303. The rest of this section enumerates the different target and
  3304. toolchain options, the corresponding config symbols to depend on, and
  3305. the text to use in the comment.
  3306. * Target architecture
  3307. + Dependency symbol: BR2_powerpc, BR2_mips, … (see arch/
  3308. Config.in)
  3309. + Comment string: no comment to be added
  3310. * MMU support
  3311. + Dependency symbol: BR2_USE_MMU
  3312. + Comment string: no comment to be added
  3313. * Gcc _sync* built-ins used for atomic operations. They are
  3314. available in variants operating on 1 byte, 2 bytes, 4 bytes and 8
  3315. bytes. Since different architectures support atomic operations on
  3316. different sizes, one dependency symbol is available for each
  3317. size:
  3318. + Dependency symbol: BR2_TOOLCHAIN_HAS_SYNC_1 for 1 byte,
  3319. BR2_TOOLCHAIN_HAS_SYNC_2 for 2 bytes,
  3320. BR2_TOOLCHAIN_HAS_SYNC_4 for 4 bytes,
  3321. BR2_TOOLCHAIN_HAS_SYNC_8 for 8 bytes.
  3322. + Comment string: no comment to be added
  3323. * Gcc _atomic* built-ins used for atomic operations.
  3324. + Dependency symbol: BR2_TOOLCHAIN_HAS_ATOMIC.
  3325. + Comment string: no comment to be added
  3326. * Kernel headers
  3327. + Dependency symbol: BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y,
  3328. (replace X_Y with the proper version, see toolchain/
  3329. Config.in)
  3330. + Comment string: headers >= X.Y and/or headers <= X.Y (replace
  3331. X.Y with the proper version)
  3332. * GCC version
  3333. + Dependency symbol: BR2_TOOLCHAIN_GCC_AT_LEAST_X_Y, (replace
  3334. X_Y with the proper version, see toolchain/Config.in)
  3335. + Comment string: gcc >= X.Y and/or gcc <= X.Y (replace X.Y
  3336. with the proper version)
  3337. * Host GCC version
  3338. + Dependency symbol: BR2_HOST_GCC_AT_LEAST_X_Y, (replace X_Y
  3339. with the proper version, see Config.in)
  3340. + Comment string: no comment to be added
  3341. + Note that it is usually not the package itself that has a
  3342. minimum host GCC version, but rather a host-package on which
  3343. it depends.
  3344. * C library
  3345. + Dependency symbol: BR2_TOOLCHAIN_USES_GLIBC,
  3346. BR2_TOOLCHAIN_USES_MUSL, BR2_TOOLCHAIN_USES_UCLIBC
  3347. + Comment string: for the C library, a slightly different
  3348. comment text is used: foo needs a glibc toolchain, or foo
  3349. needs a glibc toolchain w/ C++
  3350. * C++ support
  3351. + Dependency symbol: BR2_INSTALL_LIBSTDCPP
  3352. + Comment string: C++
  3353. * D support
  3354. + Dependency symbol: BR2_TOOLCHAIN_HAS_DLANG
  3355. + Comment string: Dlang
  3356. * Fortran support
  3357. + Dependency symbol: BR2_TOOLCHAIN_HAS_FORTRAN
  3358. + Comment string: fortran
  3359. * thread support
  3360. + Dependency symbol: BR2_TOOLCHAIN_HAS_THREADS
  3361. + Comment string: threads (unless
  3362. BR2_TOOLCHAIN_HAS_THREADS_NPTL is also needed, in which case,
  3363. specifying only NPTL is sufficient)
  3364. * NPTL thread support
  3365. + Dependency symbol: BR2_TOOLCHAIN_HAS_THREADS_NPTL
  3366. + Comment string: NPTL
  3367. * RPC support
  3368. + Dependency symbol: BR2_TOOLCHAIN_HAS_NATIVE_RPC
  3369. + Comment string: RPC
  3370. * wchar support
  3371. + Dependency symbol: BR2_USE_WCHAR
  3372. + Comment string: wchar
  3373. * dynamic library
  3374. + Dependency symbol: !BR2_STATIC_LIBS
  3375. + Comment string: dynamic library
  3376. 18.2.5. Dependencies on a Linux kernel built by buildroot
  3377. Some packages need a Linux kernel to be built by buildroot. These are
  3378. typically kernel modules or firmware. A comment should be added in
  3379. the Config.in file to express this dependency, similar to
  3380. dependencies on toolchain options. The general format is:
  3381. foo needs a Linux kernel to be built
  3382. If there is a dependency on both toolchain options and the Linux
  3383. kernel, use this format:
  3384. foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built
  3385. 18.2.6. Dependencies on udev /dev management
  3386. If a package needs udev /dev management, it should depend on symbol
  3387. BR2_PACKAGE_HAS_UDEV, and the following comment should be added:
  3388. foo needs udev /dev management
  3389. If there is a dependency on both toolchain options and udev /dev
  3390. management, use this format:
  3391. foo needs udev /dev management and a toolchain w/ featA, featB, featC
  3392. 18.2.7. Dependencies on features provided by virtual packages
  3393. Some features can be provided by more than one package, such as the
  3394. openGL libraries.
  3395. See Section 18.11, “Infrastructure for virtual packages” for more on
  3396. the virtual packages.
  3397. 18.3. The .mk file
  3398. Finally, here’s the hardest part. Create a file named libfoo.mk. It
  3399. describes how the package should be downloaded, configured, built,
  3400. installed, etc.
  3401. Depending on the package type, the .mk file must be written in a
  3402. different way, using different infrastructures:
  3403. * Makefiles for generic packages (not using autotools or CMake):
  3404. These are based on an infrastructure similar to the one used for
  3405. autotools-based packages, but require a little more work from the
  3406. developer. They specify what should be done for the
  3407. configuration, compilation and installation of the package. This
  3408. infrastructure must be used for all packages that do not use the
  3409. autotools as their build system. In the future, other specialized
  3410. infrastructures might be written for other build systems. We
  3411. cover them through in a tutorial and a reference.
  3412. * Makefiles for autotools-based software (autoconf, automake,
  3413. etc.): We provide a dedicated infrastructure for such packages,
  3414. since autotools is a very common build system. This
  3415. infrastructure must be used for new packages that rely on the
  3416. autotools as their build system. We cover them through a tutorial
  3417. and reference.
  3418. * Makefiles for cmake-based software: We provide a dedicated
  3419. infrastructure for such packages, as CMake is a more and more
  3420. commonly used build system and has a standardized behaviour. This
  3421. infrastructure must be used for new packages that rely on CMake.
  3422. We cover them through a tutorial and reference.
  3423. * Makefiles for Python modules: We have a dedicated infrastructure
  3424. for Python modules that use either the distutils or the
  3425. setuptools mechanism. We cover them through a tutorial and a
  3426. reference.
  3427. * Makefiles for Lua modules: We have a dedicated infrastructure for
  3428. Lua modules available through the LuaRocks web site. We cover
  3429. them through a tutorial and a reference.
  3430. Further formatting details: see the writing rules.
  3431. 18.4. The .hash file
  3432. When possible, you must add a third file, named libfoo.hash, that
  3433. contains the hashes of the downloaded files for the libfoo package.
  3434. The only reason for not adding a .hash file is when hash checking is
  3435. not possible due to how the package is downloaded.
  3436. When a package has a version selection choice, then the hash file may
  3437. be stored in a subdirectory named after the version, e.g. package/
  3438. libfoo/1.2.3/libfoo.hash. This is especially important if the
  3439. different versions have different licensing terms, but they are
  3440. stored in the same file. Otherwise, the hash file should stay in the
  3441. package’s directory.
  3442. The hashes stored in that file are used to validate the integrity of
  3443. the downloaded files and of the license files.
  3444. The format of this file is one line for each file for which to check
  3445. the hash, each line with the following three fields separated by two
  3446. spaces:
  3447. * the type of hash, one of:
  3448. + md5, sha1, sha224, sha256, sha384, sha512, none
  3449. * the hash of the file:
  3450. + for none, one or more non-space chars, usually just the
  3451. string xxx
  3452. + for md5, 32 hexadecimal characters
  3453. + for sha1, 40 hexadecimal characters
  3454. + for sha224, 56 hexadecimal characters
  3455. + for sha256, 64 hexadecimal characters
  3456. + for sha384, 96 hexadecimal characters
  3457. + for sha512, 128 hexadecimal characters
  3458. * the name of the file:
  3459. + for a source archive: the basename of the file, without any
  3460. directory component,
  3461. + for a license file: the path as it appears in
  3462. FOO_LICENSE_FILES.
  3463. Lines starting with a # sign are considered comments, and ignored.
  3464. Empty lines are ignored.
  3465. There can be more than one hash for a single file, each on its own
  3466. line. In this case, all hashes must match.
  3467. Note. Ideally, the hashes stored in this file should match the hashes
  3468. published by upstream, e.g. on their website, in the e-mail
  3469. announcement… If upstream provides more than one type of hash (e.g.
  3470. sha1 and sha512), then it is best to add all those hashes in the
  3471. .hash file. If upstream does not provide any hash, or only provides
  3472. an md5 hash, then compute at least one strong hash yourself
  3473. (preferably sha256, but not md5), and mention this in a comment line
  3474. above the hashes.
  3475. Note. The hashes for license files are used to detect a license
  3476. change when a package version is bumped. The hashes are checked
  3477. during the make legal-info target run. For a package with multiple
  3478. versions (like Qt5), create the hash file in a subdirectory
  3479. <packageversion> of that package (see also Section 19.2, “How patches
  3480. are applied”).
  3481. The none hash type is reserved to those archives downloaded from a
  3482. repository, like a git clone, a subversion checkout…
  3483. The example below defines a sha1 and a sha256 published by upstream
  3484. for the main libfoo-1.2.3.tar.bz2 tarball, an md5 from upstream and a
  3485. locally-computed sha256 hashes for a binary blob, a sha256 for a
  3486. downloaded patch, and an archive with no hash:
  3487. # Hashes from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.{sha1,sha256}:
  3488. sha1 486fb55c3efa71148fe07895fd713ea3a5ae343a libfoo-1.2.3.tar.bz2
  3489. sha256 efc8103cc3bcb06bda6a781532d12701eb081ad83e8f90004b39ab81b65d4369 libfoo-1.2.3.tar.bz2
  3490. # md5 from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.md5, sha256 locally computed:
  3491. md5 2d608f3c318c6b7557d551a5a09314f03452f1a1 libfoo-data.bin
  3492. sha256 01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b libfoo-data.bin
  3493. # Locally computed:
  3494. sha256 ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9 libfoo-fix-blabla.patch
  3495. # No hash for 1234:
  3496. none xxx libfoo-1234.tar.gz
  3497. # Hash for license files:
  3498. sha256 a45a845012742796534f7e91fe623262ccfb99460a2bd04015bd28d66fba95b8 COPYING
  3499. sha256 01b1f9f2c8ee648a7a596a1abe8aa4ed7899b1c9e5551bda06da6e422b04aa55 doc/COPYING.LGPL
  3500. If the .hash file is present, and it contains one or more hashes for
  3501. a downloaded file, the hash(es) computed by Buildroot (after
  3502. download) must match the hash(es) stored in the .hash file. If one or
  3503. more hashes do not match, Buildroot considers this an error, deletes
  3504. the downloaded file, and aborts.
  3505. If the .hash file is present, but it does not contain a hash for a
  3506. downloaded file, Buildroot considers this an error and aborts.
  3507. However, the downloaded file is left in the download directory since
  3508. this typically indicates that the .hash file is wrong but the
  3509. downloaded file is probably OK.
  3510. Hashes are currently checked for files fetched from http/ftp servers,
  3511. Git repositories, files copied using scp and local files. Hashes are
  3512. not checked for other version control systems (such as Subversion,
  3513. CVS, etc.) because Buildroot currently does not generate reproducible
  3514. tarballs when source code is fetched from such version control
  3515. systems.
  3516. Hashes should only be added in .hash files for files that are
  3517. guaranteed to be stable. For example, patches auto-generated by
  3518. Github are not guaranteed to be stable, and therefore their hashes
  3519. can change over time. Such patches should not be downloaded, and
  3520. instead be added locally to the package folder.
  3521. If the .hash file is missing, then no check is done at all.
  3522. 18.5. Infrastructure for packages with specific build systems
  3523. By packages with specific build systems we mean all the packages
  3524. whose build system is not one of the standard ones, such as autotools
  3525. or CMake. This typically includes packages whose build system is
  3526. based on hand-written Makefiles or shell scripts.
  3527. 18.5.1. generic-package tutorial
  3528. 01: ################################################################################
  3529. 02: #
  3530. 03: # libfoo
  3531. 04: #
  3532. 05: ################################################################################
  3533. 06:
  3534. 07: LIBFOO_VERSION = 1.0
  3535. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  3536. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  3537. 10: LIBFOO_LICENSE = GPL-3.0+
  3538. 11: LIBFOO_LICENSE_FILES = COPYING
  3539. 12: LIBFOO_INSTALL_STAGING = YES
  3540. 13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
  3541. 14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
  3542. 15:
  3543. 16: define LIBFOO_BUILD_CMDS
  3544. 17: $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
  3545. 18: endef
  3546. 19:
  3547. 20: define LIBFOO_INSTALL_STAGING_CMDS
  3548. 21: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
  3549. 22: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
  3550. 23: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
  3551. 24: endef
  3552. 25:
  3553. 26: define LIBFOO_INSTALL_TARGET_CMDS
  3554. 27: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
  3555. 28: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
  3556. 29: endef
  3557. 30:
  3558. 31: define LIBFOO_USERS
  3559. 32: foo -1 libfoo -1 * - - - LibFoo daemon
  3560. 33: endef
  3561. 34:
  3562. 35: define LIBFOO_DEVICES
  3563. 36: /dev/foo c 666 0 0 42 0 - - -
  3564. 37: endef
  3565. 38:
  3566. 39: define LIBFOO_PERMISSIONS
  3567. 40: /bin/foo f 4755 foo libfoo - - - - -
  3568. 41: endef
  3569. 42:
  3570. 43: $(eval $(generic-package))
  3571. The Makefile begins on line 7 to 11 with metadata information: the
  3572. version of the package (LIBFOO_VERSION), the name of the tarball
  3573. containing the package (LIBFOO_SOURCE) (xz-ed tarball recommended)
  3574. the Internet location at which the tarball can be downloaded from
  3575. (LIBFOO_SITE), the license (LIBFOO_LICENSE) and file with the license
  3576. text (LIBFOO_LICENSE_FILES). All variables must start with the same
  3577. prefix, LIBFOO_ in this case. This prefix is always the uppercased
  3578. version of the package name (see below to understand where the
  3579. package name is defined).
  3580. On line 12, we specify that this package wants to install something
  3581. to the staging space. This is often needed for libraries, since they
  3582. must install header files and other development files in the staging
  3583. space. This will ensure that the commands listed in the
  3584. LIBFOO_INSTALL_STAGING_CMDS variable will be executed.
  3585. On line 13, we specify that there is some fixing to be done to some
  3586. of the libfoo-config files that were installed during
  3587. LIBFOO_INSTALL_STAGING_CMDS phase. These *-config files are
  3588. executable shell script files that are located in $(STAGING_DIR)/usr/
  3589. bin directory and are executed by other 3rd party packages to find
  3590. out the location and the linking flags of this particular package.
  3591. The problem is that all these *-config files by default give wrong,
  3592. host system linking flags that are unsuitable for cross-compiling.
  3593. For example: -I/usr/include instead of -I$(STAGING_DIR)/usr/include
  3594. or: -L/usr/lib instead of -L$(STAGING_DIR)/usr/lib
  3595. So some sed magic is done to these scripts to make them give correct
  3596. flags. The argument to be given to LIBFOO_CONFIG_SCRIPTS is the file
  3597. name(s) of the shell script(s) needing fixing. All these names are
  3598. relative to $(STAGING_DIR)/usr/bin and if needed multiple names can
  3599. be given.
  3600. In addition, the scripts listed in LIBFOO_CONFIG_SCRIPTS are removed
  3601. from $(TARGET_DIR)/usr/bin, since they are not needed on the target.
  3602. Example 18.1. Config script: divine package
  3603. Package divine installs shell script $(STAGING_DIR)/usr/bin/
  3604. divine-config.
  3605. So its fixup would be:
  3606. DIVINE_CONFIG_SCRIPTS = divine-config
  3607. Example 18.2. Config script: imagemagick package:
  3608. Package imagemagick installs the following scripts: $(STAGING_DIR)/
  3609. usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config
  3610. So it’s fixup would be:
  3611. IMAGEMAGICK_CONFIG_SCRIPTS = \
  3612. Magick-config Magick++-config \
  3613. MagickCore-config MagickWand-config Wand-config
  3614. On line 14, we specify the list of dependencies this package relies
  3615. on. These dependencies are listed in terms of lower-case package
  3616. names, which can be packages for the target (without the host-
  3617. prefix) or packages for the host (with the host-) prefix). Buildroot
  3618. will ensure that all these packages are built and installed before
  3619. the current package starts its configuration.
  3620. The rest of the Makefile, lines 16..29, defines what should be done
  3621. at the different steps of the package configuration, compilation and
  3622. installation. LIBFOO_BUILD_CMDS tells what steps should be performed
  3623. to build the package. LIBFOO_INSTALL_STAGING_CMDS tells what steps
  3624. should be performed to install the package in the staging space.
  3625. LIBFOO_INSTALL_TARGET_CMDS tells what steps should be performed to
  3626. install the package in the target space.
  3627. All these steps rely on the $(@D) variable, which contains the
  3628. directory where the source code of the package has been extracted.
  3629. On lines 31..33, we define a user that is used by this package (e.g.
  3630. to run a daemon as non-root) (LIBFOO_USERS).
  3631. On line 35..37, we define a device-node file used by this package
  3632. (LIBFOO_DEVICES).
  3633. On line 39..41, we define the permissions to set to specific files
  3634. installed by this package (LIBFOO_PERMISSIONS).
  3635. Finally, on line 43, we call the generic-package function, which
  3636. generates, according to the variables defined previously, all the
  3637. Makefile code necessary to make your package working.
  3638. 18.5.2. generic-package reference
  3639. There are two variants of the generic target. The generic-package
  3640. macro is used for packages to be cross-compiled for the target. The
  3641. host-generic-package macro is used for host packages, natively
  3642. compiled for the host. It is possible to call both of them in a
  3643. single .mk file: once to create the rules to generate a target
  3644. package and once to create the rules to generate a host package:
  3645. $(eval $(generic-package))
  3646. $(eval $(host-generic-package))
  3647. This might be useful if the compilation of the target package
  3648. requires some tools to be installed on the host. If the package name
  3649. is libfoo, then the name of the package for the target is also
  3650. libfoo, while the name of the package for the host is host-libfoo.
  3651. These names should be used in the DEPENDENCIES variables of other
  3652. packages, if they depend on libfoo or host-libfoo.
  3653. The call to the generic-package and/or host-generic-package macro
  3654. must be at the end of the .mk file, after all variable definitions.
  3655. The call to host-generic-package must be after the call to
  3656. generic-package, if any.
  3657. For the target package, the generic-package uses the variables
  3658. defined by the .mk file and prefixed by the uppercased package name:
  3659. LIBFOO_*. host-generic-package uses the HOST_LIBFOO_* variables. For
  3660. some variables, if the HOST_LIBFOO_ prefixed variable doesn’t exist,
  3661. the package infrastructure uses the corresponding variable prefixed
  3662. by LIBFOO_. This is done for variables that are likely to have the
  3663. same value for both the target and host packages. See below for
  3664. details.
  3665. The list of variables that can be set in a .mk file to give metadata
  3666. information is (assuming the package name is libfoo) :
  3667. * LIBFOO_VERSION, mandatory, must contain the version of the
  3668. package. Note that if HOST_LIBFOO_VERSION doesn’t exist, it is
  3669. assumed to be the same as LIBFOO_VERSION. It can also be a
  3670. revision number or a tag for packages that are fetched directly
  3671. from their version control system. Examples:
  3672. + a version for a release tarball: LIBFOO_VERSION = 0.1.2
  3673. + a sha1 for a git tree: LIBFOO_VERSION =
  3674. cb9d6aa9429e838f0e54faa3d455bcbab5eef057
  3675. + a tag for a git tree LIBFOO_VERSION = v0.1.2
  3676. Note: Using a branch name as FOO_VERSION is not supported,
  3677. because it does not and can not work as people would expect
  3678. it should:
  3679. 1. due to local caching, Buildroot will not re-fetch the
  3680. repository, so people who expect to be able to follow the
  3681. remote repository would be quite surprised and
  3682. disappointed;
  3683. 2. because two builds can never be perfectly simultaneous,
  3684. and because the remote repository may get new commits on
  3685. the branch anytime, two users, using the same Buildroot
  3686. tree and building the same configuration, may get
  3687. different source, thus rendering the build non
  3688. reproducible, and people would be quite surprised and
  3689. disappointed.
  3690. * LIBFOO_SOURCE may contain the name of the tarball of the package,
  3691. which Buildroot will use to download the tarball from
  3692. LIBFOO_SITE. If HOST_LIBFOO_SOURCE is not specified, it defaults
  3693. to LIBFOO_SOURCE. If none are specified, then the value is
  3694. assumed to be libfoo-$(LIBFOO_VERSION).tar.gz. Example:
  3695. LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2
  3696. * LIBFOO_PATCH may contain a space-separated list of patch file
  3697. names, that Buildroot will download and apply to the package
  3698. source code. If an entry contains ://, then Buildroot will assume
  3699. it is a full URL and download the patch from this location.
  3700. Otherwise, Buildroot will assume that the patch should be
  3701. downloaded from LIBFOO_SITE. If HOST_LIBFOO_PATCH is not
  3702. specified, it defaults to LIBFOO_PATCH. Note that patches that
  3703. are included in Buildroot itself use a different mechanism: all
  3704. files of the form *.patch present in the package directory inside
  3705. Buildroot will be applied to the package after extraction (see
  3706. patching a package). Finally, patches listed in the LIBFOO_PATCH
  3707. variable are applied before the patches stored in the Buildroot
  3708. package directory.
  3709. * LIBFOO_SITE provides the location of the package, which can be a
  3710. URL or a local filesystem path. HTTP, FTP and SCP are supported
  3711. URL types for retrieving package tarballs. In these cases don’t
  3712. include a trailing slash: it will be added by Buildroot between
  3713. the directory and the filename as appropriate. Git, Subversion,
  3714. Mercurial, and Bazaar are supported URL types for retrieving
  3715. packages directly from source code management systems. There is a
  3716. helper function to make it easier to download source tarballs
  3717. from GitHub (refer to Section 18.24.4, “How to add a package from
  3718. GitHub” for details). A filesystem path may be used to specify
  3719. either a tarball or a directory containing the package source
  3720. code. See LIBFOO_SITE_METHOD below for more details on how
  3721. retrieval works. Note that SCP URLs should be of the form scp://
  3722. [user@]host:filepath, and that filepath is relative to the user’s
  3723. home directory, so you may want to prepend the path with a slash
  3724. for absolute paths: scp://[user@]host:/absolutepath. If
  3725. HOST_LIBFOO_SITE is not specified, it defaults to LIBFOO_SITE.
  3726. Examples: LIBFOO_SITE=http://www.libfoosoftware.org/libfoo
  3727. LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor LIBFOO_SITE=/opt/
  3728. software/libfoo.tar.gz LIBFOO_SITE=$(TOPDIR)/../src/libfoo
  3729. * LIBFOO_DL_OPTS is a space-separated list of additional options to
  3730. pass to the downloader. Useful for retrieving documents with
  3731. server-side checking for user logins and passwords, or to use a
  3732. proxy. All download methods valid for LIBFOO_SITE_METHOD are
  3733. supported; valid options depend on the download method (consult
  3734. the man page for the respective download utilities).
  3735. * LIBFOO_EXTRA_DOWNLOADS is a space-separated list of additional
  3736. files that Buildroot should download. If an entry contains ://
  3737. then Buildroot will assume it is a complete URL and will download
  3738. the file using this URL. Otherwise, Buildroot will assume the
  3739. file to be downloaded is located at LIBFOO_SITE. Buildroot will
  3740. not do anything with those additional files, except download
  3741. them: it will be up to the package recipe to use them from $
  3742. (LIBFOO_DL_DIR).
  3743. * LIBFOO_SITE_METHOD determines the method used to fetch or copy
  3744. the package source code. In many cases, Buildroot guesses the
  3745. method from the contents of LIBFOO_SITE and setting
  3746. LIBFOO_SITE_METHOD is unnecessary. When HOST_LIBFOO_SITE_METHOD
  3747. is not specified, it defaults to the value of LIBFOO_SITE_METHOD.
  3748. The possible values of LIBFOO_SITE_METHOD are:
  3749. + wget for normal FTP/HTTP downloads of tarballs. Used by
  3750. default when LIBFOO_SITE begins with http://, https:// or
  3751. ftp://.
  3752. + scp for downloads of tarballs over SSH with scp. Used by
  3753. default when LIBFOO_SITE begins with scp://.
  3754. + svn for retrieving source code from a Subversion repository.
  3755. Used by default when LIBFOO_SITE begins with svn://. When a
  3756. http:// Subversion repository URL is specified in
  3757. LIBFOO_SITE, one must specify LIBFOO_SITE_METHOD=svn.
  3758. Buildroot performs a checkout which is preserved as a tarball
  3759. in the download cache; subsequent builds use the tarball
  3760. instead of performing another checkout.
  3761. + cvs for retrieving source code from a CVS repository. Used by
  3762. default when LIBFOO_SITE begins with cvs://. The downloaded
  3763. source code is cached as with the svn method. Anonymous
  3764. pserver mode is assumed otherwise explicitly defined on
  3765. LIBFOO_SITE. Both LIBFOO_SITE=cvs://libfoo.net:/cvsroot/
  3766. libfoo and LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo
  3767. are accepted, on the former anonymous pserver access mode is
  3768. assumed. LIBFOO_SITE must contain the source URL as well as
  3769. the remote repository directory. The module is the package
  3770. name. LIBFOO_VERSION is mandatory and must be a tag, a
  3771. branch, or a date (e.g. "2014-10-20", "2014-10-20 13:45",
  3772. "2014-10-20 13:45+01" see "man cvs" for further details).
  3773. + git for retrieving source code from a Git repository. Used by
  3774. default when LIBFOO_SITE begins with git://. The downloaded
  3775. source code is cached as with the svn method.
  3776. + hg for retrieving source code from a Mercurial repository.
  3777. One must specify LIBFOO_SITE_METHOD=hg when LIBFOO_SITE
  3778. contains a Mercurial repository URL. The downloaded source
  3779. code is cached as with the svn method.
  3780. + bzr for retrieving source code from a Bazaar repository. Used
  3781. by default when LIBFOO_SITE begins with bzr://. The
  3782. downloaded source code is cached as with the svn method.
  3783. + file for a local tarball. One should use this when
  3784. LIBFOO_SITE specifies a package tarball as a local filename.
  3785. Useful for software that isn’t available publicly or in
  3786. version control.
  3787. + local for a local source code directory. One should use this
  3788. when LIBFOO_SITE specifies a local directory path containing
  3789. the package source code. Buildroot copies the contents of the
  3790. source directory into the package’s build directory. Note
  3791. that for local packages, no patches are applied. If you need
  3792. to still patch the source code, use LIBFOO_POST_RSYNC_HOOKS,
  3793. see Section 18.22.1, “Using the POST_RSYNC hook”.
  3794. * LIBFOO_GIT_SUBMODULES can be set to YES to create an archive with
  3795. the git submodules in the repository. This is only available for
  3796. packages downloaded with git (i.e. when LIBFOO_SITE_METHOD=git).
  3797. Note that we try not to use such git submodules when they contain
  3798. bundled libraries, in which case we prefer to use those libraries
  3799. from their own package.
  3800. * LIBFOO_STRIP_COMPONENTS is the number of leading components
  3801. (directories) that tar must strip from file names on extraction.
  3802. The tarball for most packages has one leading component named "
  3803. <pkg-name>-<pkg-version>", thus Buildroot passes
  3804. --strip-components=1 to tar to remove it. For non-standard
  3805. packages that don’t have this component, or that have more than
  3806. one leading component to strip, set this variable with the value
  3807. to be passed to tar. Default: 1.
  3808. * LIBFOO_EXCLUDES is a space-separated list of patterns to exclude
  3809. when extracting the archive. Each item from that list is passed
  3810. as a tar’s --exclude option. By default, empty.
  3811. * LIBFOO_DEPENDENCIES lists the dependencies (in terms of package
  3812. name) that are required for the current target package to
  3813. compile. These dependencies are guaranteed to be compiled and
  3814. installed before the configuration of the current package starts.
  3815. However, modifications to configuration of these dependencies
  3816. will not force a rebuild of the current package. In a similar
  3817. way, HOST_LIBFOO_DEPENDENCIES lists the dependencies for the
  3818. current host package.
  3819. * LIBFOO_EXTRACT_DEPENDENCIES lists the dependencies (in terms of
  3820. package name) that are required for the current target package to
  3821. be extracted. These dependencies are guaranteed to be compiled
  3822. and installed before the extract step of the current package
  3823. starts. This is only used internally by the package
  3824. infrastructure, and should typically not be used directly by
  3825. packages.
  3826. * LIBFOO_PATCH_DEPENDENCIES lists the dependencies (in terms of
  3827. package name) that are required for the current package to be
  3828. patched. These dependencies are guaranteed to be extracted and
  3829. patched (but not necessarily built) before the current package is
  3830. patched. In a similar way, HOST_LIBFOO_PATCH_DEPENDENCIES lists
  3831. the dependencies for the current host package. This is seldom
  3832. used; usually, LIBFOO_DEPENDENCIES is what you really want to
  3833. use.
  3834. * LIBFOO_PROVIDES lists all the virtual packages libfoo is an
  3835. implementation of. See Section 18.11, “Infrastructure for virtual
  3836. packages”.
  3837. * LIBFOO_INSTALL_STAGING can be set to YES or NO (default). If set
  3838. to YES, then the commands in the LIBFOO_INSTALL_STAGING_CMDS
  3839. variables are executed to install the package into the staging
  3840. directory.
  3841. * LIBFOO_INSTALL_TARGET can be set to YES (default) or NO. If set
  3842. to YES, then the commands in the LIBFOO_INSTALL_TARGET_CMDS
  3843. variables are executed to install the package into the target
  3844. directory.
  3845. * LIBFOO_INSTALL_IMAGES can be set to YES or NO (default). If set
  3846. to YES, then the commands in the LIBFOO_INSTALL_IMAGES_CMDS
  3847. variable are executed to install the package into the images
  3848. directory.
  3849. * LIBFOO_CONFIG_SCRIPTS lists the names of the files in $
  3850. (STAGING_DIR)/usr/bin that need some special fixing to make them
  3851. cross-compiling friendly. Multiple file names separated by space
  3852. can be given and all are relative to $(STAGING_DIR)/usr/bin. The
  3853. files listed in LIBFOO_CONFIG_SCRIPTS are also removed from $
  3854. (TARGET_DIR)/usr/bin since they are not needed on the target.
  3855. * LIBFOO_DEVICES lists the device files to be created by Buildroot
  3856. when using the static device table. The syntax to use is the
  3857. makedevs one. You can find some documentation for this syntax in
  3858. the Chapter 25, Makedev syntax documentation. This variable is
  3859. optional.
  3860. * LIBFOO_PERMISSIONS lists the changes of permissions to be done at
  3861. the end of the build process. The syntax is once again the
  3862. makedevs one. You can find some documentation for this syntax in
  3863. the Chapter 25, Makedev syntax documentation. This variable is
  3864. optional.
  3865. * LIBFOO_USERS lists the users to create for this package, if it
  3866. installs a program you want to run as a specific user (e.g. as a
  3867. daemon, or as a cron-job). The syntax is similar in spirit to the
  3868. makedevs one, and is described in the Chapter 26, Makeusers
  3869. syntax documentation. This variable is optional.
  3870. * LIBFOO_LICENSE defines the license (or licenses) under which the
  3871. package is released. This name will appear in the manifest file
  3872. produced by make legal-info. If the license appears in the SPDX
  3873. License List [https://spdx.org/licenses/], use the SPDX short
  3874. identifier to make the manifest file uniform. Otherwise, describe
  3875. the license in a precise and concise way, avoiding ambiguous
  3876. names such as BSD which actually name a family of licenses. This
  3877. variable is optional. If it is not defined, unknown will appear
  3878. in the license field of the manifest file for this package. The
  3879. expected format for this variable must comply with the following
  3880. rules:
  3881. + If different parts of the package are released under
  3882. different licenses, then comma separate licenses (e.g.
  3883. LIBFOO_LICENSE = GPL-2.0+, LGPL-2.1+). If there is clear
  3884. distinction between which component is licensed under what
  3885. license, then annotate the license with that component,
  3886. between parenthesis (e.g. LIBFOO_LICENSE = GPL-2.0+
  3887. (programs), LGPL-2.1+ (libraries)).
  3888. + If some licenses are conditioned on a sub-option being
  3889. enabled, append the conditional licenses with a comma (e.g.:
  3890. FOO_LICENSE += , GPL-2.0+ (programs)); the infrastructure
  3891. will internally remove the space before the comma.
  3892. + If the package is dual licensed, then separate licenses with
  3893. the or keyword (e.g. LIBFOO_LICENSE = AFL-2.1 or GPL-2.0+).
  3894. * LIBFOO_LICENSE_FILES is a space-separated list of files in the
  3895. package tarball that contain the license(s) under which the
  3896. package is released. make legal-info copies all of these files in
  3897. the legal-info directory. See Chapter 13, Legal notice and
  3898. licensing for more information. This variable is optional. If it
  3899. is not defined, a warning will be produced to let you know, and
  3900. not saved will appear in the license files field of the manifest
  3901. file for this package.
  3902. * LIBFOO_ACTUAL_SOURCE_TARBALL only applies to packages whose
  3903. LIBFOO_SITE / LIBFOO_SOURCE pair points to an archive that does
  3904. not actually contain source code, but binary code. This a very
  3905. uncommon case, only known to apply to external toolchains which
  3906. come already compiled, although theoretically it might apply to
  3907. other packages. In such cases a separate tarball is usually
  3908. available with the actual source code. Set
  3909. LIBFOO_ACTUAL_SOURCE_TARBALL to the name of the actual source
  3910. code archive and Buildroot will download it and use it when you
  3911. run make legal-info to collect legally-relevant material. Note
  3912. this file will not be downloaded during regular builds nor by
  3913. make source.
  3914. * LIBFOO_ACTUAL_SOURCE_SITE provides the location of the actual
  3915. source tarball. The default value is LIBFOO_SITE, so you don’t
  3916. need to set this variable if the binary and source archives are
  3917. hosted on the same directory. If LIBFOO_ACTUAL_SOURCE_TARBALL is
  3918. not set, it doesn’t make sense to define
  3919. LIBFOO_ACTUAL_SOURCE_SITE.
  3920. * LIBFOO_REDISTRIBUTE can be set to YES (default) or NO to indicate
  3921. if the package source code is allowed to be redistributed. Set it
  3922. to NO for non-opensource packages: Buildroot will not save the
  3923. source code for this package when collecting the legal-info.
  3924. * LIBFOO_FLAT_STACKSIZE defines the stack size of an application
  3925. built into the FLAT binary format. The application stack size on
  3926. the NOMMU architecture processors can’t be enlarged at run time.
  3927. The default stack size for the FLAT binary format is only 4k
  3928. bytes. If the application consumes more stack, append the
  3929. required number here.
  3930. * LIBFOO_BIN_ARCH_EXCLUDE is a space-separated list of paths
  3931. (relative to the target directory) to ignore when checking that
  3932. the package installs correctly cross-compiled binaries. You
  3933. seldom need to set this variable, unless the package installs
  3934. binary blobs outside the default locations, /lib/firmware, /usr/
  3935. lib/firmware, /lib/modules, /usr/lib/modules, and /usr/share,
  3936. which are automatically excluded.
  3937. * LIBFOO_IGNORE_CVES is a space-separated list of CVEs that tells
  3938. Buildroot CVE tracking tools which CVEs should be ignored for
  3939. this package. This is typically used when the CVE is fixed by a
  3940. patch in the package, or when the CVE for some reason does not
  3941. affect the Buildroot package. A Makefile comment must always
  3942. precede the addition of a CVE to this variable. Example:
  3943. # 0001-fix-cve-2020-12345.patch
  3944. LIBFOO_IGNORE_CVES += CVE-2020-12345
  3945. # only when built with libbaz, which Buildroot doesn't support
  3946. LIBFOO_IGNORE_CVES += CVE-2020-54321
  3947. The recommended way to define these variables is to use the following
  3948. syntax:
  3949. LIBFOO_VERSION = 2.32
  3950. Now, the variables that define what should be performed at the
  3951. different steps of the build process.
  3952. * LIBFOO_EXTRACT_CMDS lists the actions to be performed to extract
  3953. the package. This is generally not needed as tarballs are
  3954. automatically handled by Buildroot. However, if the package uses
  3955. a non-standard archive format, such as a ZIP or RAR file, or has
  3956. a tarball with a non-standard organization, this variable allows
  3957. to override the package infrastructure default behavior.
  3958. * LIBFOO_CONFIGURE_CMDS lists the actions to be performed to
  3959. configure the package before its compilation.
  3960. * LIBFOO_BUILD_CMDS lists the actions to be performed to compile
  3961. the package.
  3962. * HOST_LIBFOO_INSTALL_CMDS lists the actions to be performed to
  3963. install the package, when the package is a host package. The
  3964. package must install its files to the directory given by $
  3965. (HOST_DIR). All files, including development files such as
  3966. headers should be installed, since other packages might be
  3967. compiled on top of this package.
  3968. * LIBFOO_INSTALL_TARGET_CMDS lists the actions to be performed to
  3969. install the package to the target directory, when the package is
  3970. a target package. The package must install its files to the
  3971. directory given by $(TARGET_DIR). Only the files required for
  3972. execution of the package have to be installed. Header files,
  3973. static libraries and documentation will be removed again when the
  3974. target filesystem is finalized.
  3975. * LIBFOO_INSTALL_STAGING_CMDS lists the actions to be performed to
  3976. install the package to the staging directory, when the package is
  3977. a target package. The package must install its files to the
  3978. directory given by $(STAGING_DIR). All development files should
  3979. be installed, since they might be needed to compile other
  3980. packages.
  3981. * LIBFOO_INSTALL_IMAGES_CMDS lists the actions to be performed to
  3982. install the package to the images directory, when the package is
  3983. a target package. The package must install its files to the
  3984. directory given by $(BINARIES_DIR). Only files that are binary
  3985. images (aka images) that do not belong in the TARGET_DIR but are
  3986. necessary for booting the board should be placed here. For
  3987. example, a package should utilize this step if it has binaries
  3988. which would be similar to the kernel image, bootloader or root
  3989. filesystem images.
  3990. * LIBFOO_INSTALL_INIT_SYSV, LIBFOO_INSTALL_INIT_OPENRC and
  3991. LIBFOO_INSTALL_INIT_SYSTEMD list the actions to install init
  3992. scripts either for the systemV-like init systems (busybox,
  3993. sysvinit, etc.), openrc or for the systemd units. These commands
  3994. will be run only when the relevant init system is installed (i.e.
  3995. if systemd is selected as the init system in the configuration,
  3996. only LIBFOO_INSTALL_INIT_SYSTEMD will be run). The only exception
  3997. is when openrc is chosen as init system and
  3998. LIBFOO_INSTALL_INIT_OPENRC has not been set, in such situation
  3999. LIBFOO_INSTALL_INIT_SYSV will be called, since openrc supports
  4000. sysv init scripts. When systemd is used as the init system,
  4001. buildroot will automatically enable all services using the
  4002. systemctl preset-all command in the final phase of image
  4003. building. You can add preset files to prevent a particular unit
  4004. from being automatically enabled by buildroot.
  4005. * LIBFOO_HELP_CMDS lists the actions to print the package help,
  4006. which is included to the main make help output. These commands
  4007. can print anything in any format. This is seldom used, as
  4008. packages rarely have custom rules. Do not use this variable,
  4009. unless you really know that you need to print help.
  4010. * LIBFOO_LINUX_CONFIG_FIXUPS lists the Linux kernel configuration
  4011. options that are needed to build and use this package, and
  4012. without which the package is fundamentally broken. This shall be
  4013. a set of calls to one of the kconfig tweaking option:
  4014. KCONFIG_ENABLE_OPT, KCONFIG_DISABLE_OPT, or KCONFIG_SET_OPT. This
  4015. is seldom used, as package usually have no strict requirements on
  4016. the kernel options.
  4017. The preferred way to define these variables is:
  4018. define LIBFOO_CONFIGURE_CMDS
  4019. action 1
  4020. action 2
  4021. action 3
  4022. endef
  4023. In the action definitions, you can use the following variables:
  4024. * $(LIBFOO_PKGDIR) contains the path to the directory containing
  4025. the libfoo.mk and Config.in files. This variable is useful when
  4026. it is necessary to install a file bundled in Buildroot, like a
  4027. runtime configuration file, a splashscreen image…
  4028. * $(@D), which contains the directory in which the package source
  4029. code has been uncompressed.
  4030. * $(LIBFOO_DL_DIR) contains the path to the directory where all the
  4031. downloads made by Buildroot for libfoo are stored in.
  4032. * $(TARGET_CC), $(TARGET_LD), etc. to get the target
  4033. cross-compilation utilities
  4034. * $(TARGET_CROSS) to get the cross-compilation toolchain prefix
  4035. * Of course the $(HOST_DIR), $(STAGING_DIR) and $(TARGET_DIR)
  4036. variables to install the packages properly. Those variables point
  4037. to the global host, staging and target directories, unless
  4038. per-package directory support is used, in which case they point
  4039. to the current package host, staging and target directories. In
  4040. both cases, it doesn’t make any difference from the package point
  4041. of view: it should simply use HOST_DIR, STAGING_DIR and
  4042. TARGET_DIR. See Section 8.12, “Top-level parallel build” for more
  4043. details about per-package directory support.
  4044. Finally, you can also use hooks. See Section 18.22, “Hooks available
  4045. in the various build steps” for more information.
  4046. 18.6. Infrastructure for autotools-based packages
  4047. 18.6.1. autotools-package tutorial
  4048. First, let’s see how to write a .mk file for an autotools-based
  4049. package, with an example :
  4050. 01: ################################################################################
  4051. 02: #
  4052. 03: # libfoo
  4053. 04: #
  4054. 05: ################################################################################
  4055. 06:
  4056. 07: LIBFOO_VERSION = 1.0
  4057. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  4058. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  4059. 10: LIBFOO_INSTALL_STAGING = YES
  4060. 11: LIBFOO_INSTALL_TARGET = NO
  4061. 12: LIBFOO_CONF_OPTS = --disable-shared
  4062. 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
  4063. 14:
  4064. 15: $(eval $(autotools-package))
  4065. On line 7, we declare the version of the package.
  4066. On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  4067. recommended) and the location of the tarball on the Web. Buildroot
  4068. will automatically download the tarball from this location.
  4069. On line 10, we tell Buildroot to install the package to the staging
  4070. directory. The staging directory, located in output/staging/ is the
  4071. directory where all the packages are installed, including their
  4072. development files, etc. By default, packages are not installed to the
  4073. staging directory, since usually, only libraries need to be installed
  4074. in the staging directory: their development files are needed to
  4075. compile other libraries or applications depending on them. Also by
  4076. default, when staging installation is enabled, packages are installed
  4077. in this location using the make install command.
  4078. On line 11, we tell Buildroot to not install the package to the
  4079. target directory. This directory contains what will become the root
  4080. filesystem running on the target. For purely static libraries, it is
  4081. not necessary to install them in the target directory because they
  4082. will not be used at runtime. By default, target installation is
  4083. enabled; setting this variable to NO is almost never needed. Also by
  4084. default, packages are installed in this location using the make
  4085. install command.
  4086. On line 12, we tell Buildroot to pass a custom configure option, that
  4087. will be passed to the ./configure script before configuring and
  4088. building the package.
  4089. On line 13, we declare our dependencies, so that they are built
  4090. before the build process of our package starts.
  4091. Finally, on line line 15, we invoke the autotools-package macro that
  4092. generates all the Makefile rules that actually allows the package to
  4093. be built.
  4094. 18.6.2. autotools-package reference
  4095. The main macro of the autotools package infrastructure is
  4096. autotools-package. It is similar to the generic-package macro. The
  4097. ability to have target and host packages is also available, with the
  4098. host-autotools-package macro.
  4099. Just like the generic infrastructure, the autotools infrastructure
  4100. works by defining a number of variables before calling the
  4101. autotools-package macro.
  4102. First, all the package metadata information variables that exist in
  4103. the generic infrastructure also exist in the autotools
  4104. infrastructure: LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH,
  4105. LIBFOO_SITE, LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES,
  4106. LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.
  4107. A few additional variables, specific to the autotools infrastructure,
  4108. can also be defined. Many of them are only useful in very specific
  4109. cases, typical packages will therefore only use a few of them.
  4110. * LIBFOO_SUBDIR may contain the name of a subdirectory inside the
  4111. package that contains the configure script. This is useful, if
  4112. for example, the main configure script is not at the root of the
  4113. tree extracted by the tarball. If HOST_LIBFOO_SUBDIR is not
  4114. specified, it defaults to LIBFOO_SUBDIR.
  4115. * LIBFOO_CONF_ENV, to specify additional environment variables to
  4116. pass to the configure script. By default, empty.
  4117. * LIBFOO_CONF_OPTS, to specify additional configure options to pass
  4118. to the configure script. By default, empty.
  4119. * LIBFOO_MAKE, to specify an alternate make command. This is
  4120. typically useful when parallel make is enabled in the
  4121. configuration (using BR2_JLEVEL) but that this feature should be
  4122. disabled for the given package, for one reason or another. By
  4123. default, set to $(MAKE). If parallel building is not supported by
  4124. the package, then it should be set to LIBFOO_MAKE=$(MAKE1).
  4125. * LIBFOO_MAKE_ENV, to specify additional environment variables to
  4126. pass to make in the build step. These are passed before the make
  4127. command. By default, empty.
  4128. * LIBFOO_MAKE_OPTS, to specify additional variables to pass to make
  4129. in the build step. These are passed after the make command. By
  4130. default, empty.
  4131. * LIBFOO_AUTORECONF, tells whether the package should be
  4132. autoreconfigured or not (i.e. if the configure script and
  4133. Makefile.in files should be re-generated by re-running autoconf,
  4134. automake, libtool, etc.). Valid values are YES and NO. By
  4135. default, the value is NO
  4136. * LIBFOO_AUTORECONF_ENV, to specify additional environment
  4137. variables to pass to the autoreconf program if LIBFOO_AUTORECONF=
  4138. YES. These are passed in the environment of the autoreconf
  4139. command. By default, empty.
  4140. * LIBFOO_AUTORECONF_OPTS to specify additional options passed to
  4141. the autoreconf program if LIBFOO_AUTORECONF=YES. By default,
  4142. empty.
  4143. * LIBFOO_GETTEXTIZE, tells whether the package should be
  4144. gettextized or not (i.e. if the package uses a different gettext
  4145. version than Buildroot provides, and it is needed to run
  4146. gettextize.) Only valid when LIBFOO_AUTORECONF=YES. Valid values
  4147. are YES and NO. The default is NO.
  4148. * LIBFOO_GETTEXTIZE_OPTS, to specify additional options passed to
  4149. the gettextize program, if LIBFOO_GETTEXTIZE=YES. You may use
  4150. that if, for example, the .po files are not located in the
  4151. standard place (i.e. in po/ at the root of the package.) By
  4152. default, -f.
  4153. * LIBFOO_LIBTOOL_PATCH tells whether the Buildroot patch to fix
  4154. libtool cross-compilation issues should be applied or not. Valid
  4155. values are YES and NO. By default, the value is YES
  4156. * LIBFOO_INSTALL_STAGING_OPTS contains the make options used to
  4157. install the package to the staging directory. By default, the
  4158. value is DESTDIR=$(STAGING_DIR) install, which is correct for
  4159. most autotools packages. It is still possible to override it.
  4160. * LIBFOO_INSTALL_TARGET_OPTS contains the make options used to
  4161. install the package to the target directory. By default, the
  4162. value is DESTDIR=$(TARGET_DIR) install. The default value is
  4163. correct for most autotools packages, but it is still possible to
  4164. override it if needed.
  4165. With the autotools infrastructure, all the steps required to build
  4166. and install the packages are already defined, and they generally work
  4167. well for most autotools-based packages. However, when required, it is
  4168. still possible to customize what is done in any particular step:
  4169. * By adding a post-operation hook (after extract, patch, configure,
  4170. build or install). See Section 18.22, “Hooks available in the
  4171. various build steps” for details.
  4172. * By overriding one of the steps. For example, even if the
  4173. autotools infrastructure is used, if the package .mk file defines
  4174. its own LIBFOO_CONFIGURE_CMDS variable, it will be used instead
  4175. of the default autotools one. However, using this method should
  4176. be restricted to very specific cases. Do not use it in the
  4177. general case.
  4178. 18.7. Infrastructure for CMake-based packages
  4179. 18.7.1. cmake-package tutorial
  4180. First, let’s see how to write a .mk file for a CMake-based package,
  4181. with an example :
  4182. 01: ################################################################################
  4183. 02: #
  4184. 03: # libfoo
  4185. 04: #
  4186. 05: ################################################################################
  4187. 06:
  4188. 07: LIBFOO_VERSION = 1.0
  4189. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  4190. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  4191. 10: LIBFOO_INSTALL_STAGING = YES
  4192. 11: LIBFOO_INSTALL_TARGET = NO
  4193. 12: LIBFOO_CONF_OPTS = -DBUILD_DEMOS=ON
  4194. 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
  4195. 14:
  4196. 15: $(eval $(cmake-package))
  4197. On line 7, we declare the version of the package.
  4198. On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  4199. recommended) and the location of the tarball on the Web. Buildroot
  4200. will automatically download the tarball from this location.
  4201. On line 10, we tell Buildroot to install the package to the staging
  4202. directory. The staging directory, located in output/staging/ is the
  4203. directory where all the packages are installed, including their
  4204. development files, etc. By default, packages are not installed to the
  4205. staging directory, since usually, only libraries need to be installed
  4206. in the staging directory: their development files are needed to
  4207. compile other libraries or applications depending on them. Also by
  4208. default, when staging installation is enabled, packages are installed
  4209. in this location using the make install command.
  4210. On line 11, we tell Buildroot to not install the package to the
  4211. target directory. This directory contains what will become the root
  4212. filesystem running on the target. For purely static libraries, it is
  4213. not necessary to install them in the target directory because they
  4214. will not be used at runtime. By default, target installation is
  4215. enabled; setting this variable to NO is almost never needed. Also by
  4216. default, packages are installed in this location using the make
  4217. install command.
  4218. On line 12, we tell Buildroot to pass custom options to CMake when it
  4219. is configuring the package.
  4220. On line 13, we declare our dependencies, so that they are built
  4221. before the build process of our package starts.
  4222. Finally, on line line 15, we invoke the cmake-package macro that
  4223. generates all the Makefile rules that actually allows the package to
  4224. be built.
  4225. 18.7.2. cmake-package reference
  4226. The main macro of the CMake package infrastructure is cmake-package.
  4227. It is similar to the generic-package macro. The ability to have
  4228. target and host packages is also available, with the
  4229. host-cmake-package macro.
  4230. Just like the generic infrastructure, the CMake infrastructure works
  4231. by defining a number of variables before calling the cmake-package
  4232. macro.
  4233. First, all the package metadata information variables that exist in
  4234. the generic infrastructure also exist in the CMake infrastructure:
  4235. LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE,
  4236. LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING,
  4237. LIBFOO_INSTALL_TARGET.
  4238. A few additional variables, specific to the CMake infrastructure, can
  4239. also be defined. Many of them are only useful in very specific cases,
  4240. typical packages will therefore only use a few of them.
  4241. * LIBFOO_SUBDIR may contain the name of a subdirectory inside the
  4242. package that contains the main CMakeLists.txt file. This is
  4243. useful, if for example, the main CMakeLists.txt file is not at
  4244. the root of the tree extracted by the tarball. If
  4245. HOST_LIBFOO_SUBDIR is not specified, it defaults to
  4246. LIBFOO_SUBDIR.
  4247. * LIBFOO_CONF_ENV, to specify additional environment variables to
  4248. pass to CMake. By default, empty.
  4249. * LIBFOO_CONF_OPTS, to specify additional configure options to pass
  4250. to CMake. By default, empty. A number of common CMake options are
  4251. set by the cmake-package infrastructure; so it is normally not
  4252. necessary to set them in the package’s *.mk file unless you want
  4253. to override them:
  4254. + CMAKE_BUILD_TYPE is driven by BR2_ENABLE_DEBUG;
  4255. + CMAKE_INSTALL_PREFIX;
  4256. + BUILD_SHARED_LIBS is driven by BR2_STATIC_LIBS;
  4257. + BUILD_DOC, BUILD_DOCS are disabled;
  4258. + BUILD_EXAMPLE, BUILD_EXAMPLES are disabled;
  4259. + BUILD_TEST, BUILD_TESTS, BUILD_TESTING are disabled.
  4260. * LIBFOO_SUPPORTS_IN_SOURCE_BUILD = NO should be set when the
  4261. package cannot be built inside the source tree but needs a
  4262. separate build directory.
  4263. * LIBFOO_MAKE, to specify an alternate make command. This is
  4264. typically useful when parallel make is enabled in the
  4265. configuration (using BR2_JLEVEL) but that this feature should be
  4266. disabled for the given package, for one reason or another. By
  4267. default, set to $(MAKE). If parallel building is not supported by
  4268. the package, then it should be set to LIBFOO_MAKE=$(MAKE1).
  4269. * LIBFOO_MAKE_ENV, to specify additional environment variables to
  4270. pass to make in the build step. These are passed before the make
  4271. command. By default, empty.
  4272. * LIBFOO_MAKE_OPTS, to specify additional variables to pass to make
  4273. in the build step. These are passed after the make command. By
  4274. default, empty.
  4275. * LIBFOO_INSTALL_STAGING_OPTS contains the make options used to
  4276. install the package to the staging directory. By default, the
  4277. value is DESTDIR=$(STAGING_DIR) install, which is correct for
  4278. most CMake packages. It is still possible to override it.
  4279. * LIBFOO_INSTALL_TARGET_OPTS contains the make options used to
  4280. install the package to the target directory. By default, the
  4281. value is DESTDIR=$(TARGET_DIR) install. The default value is
  4282. correct for most CMake packages, but it is still possible to
  4283. override it if needed.
  4284. With the CMake infrastructure, all the steps required to build and
  4285. install the packages are already defined, and they generally work
  4286. well for most CMake-based packages. However, when required, it is
  4287. still possible to customize what is done in any particular step:
  4288. * By adding a post-operation hook (after extract, patch, configure,
  4289. build or install). See Section 18.22, “Hooks available in the
  4290. various build steps” for details.
  4291. * By overriding one of the steps. For example, even if the CMake
  4292. infrastructure is used, if the package .mk file defines its own
  4293. LIBFOO_CONFIGURE_CMDS variable, it will be used instead of the
  4294. default CMake one. However, using this method should be
  4295. restricted to very specific cases. Do not use it in the general
  4296. case.
  4297. 18.8. Infrastructure for Python packages
  4298. This infrastructure applies to Python packages that use the standard
  4299. Python setuptools mechanism as their build system, generally
  4300. recognizable by the usage of a setup.py script.
  4301. 18.8.1. python-package tutorial
  4302. First, let’s see how to write a .mk file for a Python package, with
  4303. an example :
  4304. 01: ################################################################################
  4305. 02: #
  4306. 03: # python-foo
  4307. 04: #
  4308. 05: ################################################################################
  4309. 06:
  4310. 07: PYTHON_FOO_VERSION = 1.0
  4311. 08: PYTHON_FOO_SOURCE = python-foo-$(PYTHON_FOO_VERSION).tar.xz
  4312. 09: PYTHON_FOO_SITE = http://www.foosoftware.org/download
  4313. 10: PYTHON_FOO_LICENSE = BSD-3-Clause
  4314. 11: PYTHON_FOO_LICENSE_FILES = LICENSE
  4315. 12: PYTHON_FOO_ENV = SOME_VAR=1
  4316. 13: PYTHON_FOO_DEPENDENCIES = libmad
  4317. 14: PYTHON_FOO_SETUP_TYPE = distutils
  4318. 15:
  4319. 16: $(eval $(python-package))
  4320. On line 7, we declare the version of the package.
  4321. On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  4322. recommended) and the location of the tarball on the Web. Buildroot
  4323. will automatically download the tarball from this location.
  4324. On line 10 and 11, we give licensing details about the package (its
  4325. license on line 10, and the file containing the license text on line
  4326. 11).
  4327. On line 12, we tell Buildroot to pass custom options to the Python
  4328. setup.py script when it is configuring the package.
  4329. On line 13, we declare our dependencies, so that they are built
  4330. before the build process of our package starts.
  4331. On line 14, we declare the specific Python build system being used.
  4332. In this case the distutils Python build system is used. The two
  4333. supported ones are distutils and setuptools.
  4334. Finally, on line 16, we invoke the python-package macro that
  4335. generates all the Makefile rules that actually allow the package to
  4336. be built.
  4337. 18.8.2. python-package reference
  4338. As a policy, packages that merely provide Python modules should all
  4339. be named python-<something> in Buildroot. Other packages that use the
  4340. Python build system, but are not Python modules, can freely choose
  4341. their name (existing examples in Buildroot are scons and supervisor).
  4342. Packages that are only compatible with one version of Python (as in:
  4343. Python 2 or Python 3) should depend on that version explicitely in
  4344. their Config.in file (BR2_PACKAGE_PYTHON for Python 2,
  4345. BR2_PACKAGE_PYTHON3 for Python 3). Packages that are compatible with
  4346. both versions should not explicitely depend on them in their
  4347. Config.in file, since that condition is already expressed for the
  4348. whole "External python modules" menu.
  4349. The main macro of the Python package infrastructure is
  4350. python-package. It is similar to the generic-package macro. It is
  4351. also possible to create Python host packages with the
  4352. host-python-package macro.
  4353. Just like the generic infrastructure, the Python infrastructure works
  4354. by defining a number of variables before calling the python-package
  4355. or host-python-package macros.
  4356. All the package metadata information variables that exist in the
  4357. generic package infrastructure also exist in the Python
  4358. infrastructure: PYTHON_FOO_VERSION, PYTHON_FOO_SOURCE,
  4359. PYTHON_FOO_PATCH, PYTHON_FOO_SITE, PYTHON_FOO_SUBDIR,
  4360. PYTHON_FOO_DEPENDENCIES, PYTHON_FOO_LICENSE,
  4361. PYTHON_FOO_LICENSE_FILES, PYTHON_FOO_INSTALL_STAGING, etc.
  4362. Note that:
  4363. * It is not necessary to add python or host-python in the
  4364. PYTHON_FOO_DEPENDENCIES variable of a package, since these basic
  4365. dependencies are automatically added as needed by the Python
  4366. package infrastructure.
  4367. * Similarly, it is not needed to add host-setuptools to
  4368. PYTHON_FOO_DEPENDENCIES for setuptools-based packages, since it’s
  4369. automatically added by the Python infrastructure as needed.
  4370. One variable specific to the Python infrastructure is mandatory:
  4371. * PYTHON_FOO_SETUP_TYPE, to define which Python build system is
  4372. used by the package. The two supported values are distutils and
  4373. setuptools. If you don’t know which one is used in your package,
  4374. look at the setup.py file in your package source code, and see
  4375. whether it imports things from the distutils module or the
  4376. setuptools module.
  4377. A few additional variables, specific to the Python infrastructure,
  4378. can optionally be defined, depending on the package’s needs. Many of
  4379. them are only useful in very specific cases, typical packages will
  4380. therefore only use a few of them, or none.
  4381. * PYTHON_FOO_SUBDIR may contain the name of a subdirectory inside
  4382. the package that contains the main setup.py file. This is useful,
  4383. if for example, the main setup.py file is not at the root of the
  4384. tree extracted by the tarball. If HOST_PYTHON_FOO_SUBDIR is not
  4385. specified, it defaults to PYTHON_FOO_SUBDIR.
  4386. * PYTHON_FOO_ENV, to specify additional environment variables to
  4387. pass to the Python setup.py script (for both the build and
  4388. install steps). Note that the infrastructure is automatically
  4389. passing several standard variables, defined in
  4390. PKG_PYTHON_DISTUTILS_ENV (for distutils target packages),
  4391. HOST_PKG_PYTHON_DISTUTILS_ENV (for distutils host packages),
  4392. PKG_PYTHON_SETUPTOOLS_ENV (for setuptools target packages) and
  4393. HOST_PKG_PYTHON_SETUPTOOLS_ENV (for setuptools host packages).
  4394. * PYTHON_FOO_BUILD_OPTS, to specify additional options to pass to
  4395. the Python setup.py script during the build step. For target
  4396. distutils packages, the PKG_PYTHON_DISTUTILS_BUILD_OPTS options
  4397. are already passed automatically by the infrastructure.
  4398. * PYTHON_FOO_INSTALL_TARGET_OPTS, PYTHON_FOO_INSTALL_STAGING_OPTS,
  4399. HOST_PYTHON_FOO_INSTALL_OPTS to specify additional options to
  4400. pass to the Python setup.py script during the target installation
  4401. step, the staging installation step or the host installation,
  4402. respectively. Note that the infrastructure is automatically
  4403. passing some options, defined in
  4404. PKG_PYTHON_DISTUTILS_INSTALL_TARGET_OPTS or
  4405. PKG_PYTHON_DISTUTILS_INSTALL_STAGING_OPTS (for target distutils
  4406. packages), HOST_PKG_PYTHON_DISTUTILS_INSTALL_OPTS (for host
  4407. distutils packages), PKG_PYTHON_SETUPTOOLS_INSTALL_TARGET_OPTS or
  4408. PKG_PYTHON_SETUPTOOLS_INSTALL_STAGING_OPTS (for target setuptools
  4409. packages) and HOST_PKG_PYTHON_SETUPTOOLS_INSTALL_OPTS (for host
  4410. setuptools packages).
  4411. * HOST_PYTHON_FOO_NEEDS_HOST_PYTHON, to define the host python
  4412. interpreter. The usage of this variable is limited to host
  4413. packages. The two supported value are python2 and python3. It
  4414. will ensure the right host python package is available and will
  4415. invoke it for the build. If some build steps are overloaded, the
  4416. right python interpreter must be explicitly called in the
  4417. commands.
  4418. With the Python infrastructure, all the steps required to build and
  4419. install the packages are already defined, and they generally work
  4420. well for most Python-based packages. However, when required, it is
  4421. still possible to customize what is done in any particular step:
  4422. * By adding a post-operation hook (after extract, patch, configure,
  4423. build or install). See Section 18.22, “Hooks available in the
  4424. various build steps” for details.
  4425. * By overriding one of the steps. For example, even if the Python
  4426. infrastructure is used, if the package .mk file defines its own
  4427. PYTHON_FOO_BUILD_CMDS variable, it will be used instead of the
  4428. default Python one. However, using this method should be
  4429. restricted to very specific cases. Do not use it in the general
  4430. case.
  4431. 18.8.3. Generating a python-package from a PyPI repository
  4432. If the Python package for which you would like to create a Buildroot
  4433. package is available on PyPI, you may want to use the scanpypi tool
  4434. located in utils/ to automate the process.
  4435. You can find the list of existing PyPI packages here [https://
  4436. pypi.python.org].
  4437. scanpypi requires Python’s setuptools package to be installed on your
  4438. host.
  4439. When at the root of your buildroot directory just do :
  4440. utils/scanpypi foo bar -o package
  4441. This will generate packages python-foo and python-bar in the package
  4442. folder if they exist on https://pypi.python.org.
  4443. Find the external python modules menu and insert your package inside.
  4444. Keep in mind that the items inside a menu should be in alphabetical
  4445. order.
  4446. Please keep in mind that you’ll most likely have to manually check
  4447. the package for any mistakes as there are things that cannot be
  4448. guessed by the generator (e.g. dependencies on any of the python core
  4449. modules such as BR2_PACKAGE_PYTHON_ZLIB). Also, please take note that
  4450. the license and license files are guessed and must be checked. You
  4451. also need to manually add the package to the package/Config.in file.
  4452. If your Buildroot package is not in the official Buildroot tree but
  4453. in a br2-external tree, use the -o flag as follows:
  4454. utils/scanpypi foo bar -o other_package_dir
  4455. This will generate packages python-foo and python-bar in the
  4456. other_package_directory instead of package.
  4457. Option -h will list the available options:
  4458. utils/scanpypi -h
  4459. 18.8.4. python-package CFFI backend
  4460. C Foreign Function Interface for Python (CFFI) provides a convenient
  4461. and reliable way to call compiled C code from Python using interface
  4462. declarations written in C. Python packages relying on this backend
  4463. can be identified by the appearance of a cffi dependency in the
  4464. install_requires field of their setup.py file.
  4465. Such a package should:
  4466. * add python-cffi as a runtime dependency in order to install the
  4467. compiled C library wrapper on the target. This is achieved by
  4468. adding select BR2_PACKAGE_PYTHON_CFFI to the package Config.in.
  4469. config BR2_PACKAGE_PYTHON_FOO
  4470. bool "python-foo"
  4471. select BR2_PACKAGE_PYTHON_CFFI # runtime
  4472. * add host-python-cffi as a build-time dependency in order to
  4473. cross-compile the C wrapper. This is achieved by adding
  4474. host-python-cffi to the PYTHON_FOO_DEPENDENCIES variable.
  4475. ################################################################################
  4476. #
  4477. # python-foo
  4478. #
  4479. ################################################################################
  4480. ...
  4481. PYTHON_FOO_DEPENDENCIES = host-python-cffi
  4482. $(eval $(python-package))
  4483. 18.9. Infrastructure for LuaRocks-based packages
  4484. 18.9.1. luarocks-package tutorial
  4485. First, let’s see how to write a .mk file for a LuaRocks-based
  4486. package, with an example :
  4487. 01: ################################################################################
  4488. 02: #
  4489. 03: # lua-foo
  4490. 04: #
  4491. 05: ################################################################################
  4492. 06:
  4493. 07: LUA_FOO_VERSION = 1.0.2-1
  4494. 08: LUA_FOO_NAME_UPSTREAM = foo
  4495. 09: LUA_FOO_DEPENDENCIES = bar
  4496. 10:
  4497. 11: LUA_FOO_BUILD_OPTS += BAR_INCDIR=$(STAGING_DIR)/usr/include
  4498. 12: LUA_FOO_BUILD_OPTS += BAR_LIBDIR=$(STAGING_DIR)/usr/lib
  4499. 13: LUA_FOO_LICENSE = luaFoo license
  4500. 14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING
  4501. 15:
  4502. 16: $(eval $(luarocks-package))
  4503. On line 7, we declare the version of the package (the same as in the
  4504. rockspec, which is the concatenation of the upstream version and the
  4505. rockspec revision, separated by a hyphen -).
  4506. On line 8, we declare that the package is called "foo" on LuaRocks.
  4507. In Buildroot, we give Lua-related packages a name that starts with
  4508. "lua", so the Buildroot name is different from the upstream name.
  4509. LUA_FOO_NAME_UPSTREAM makes the link between the two names.
  4510. On line 9, we declare our dependencies against native libraries, so
  4511. that they are built before the build process of our package starts.
  4512. On lines 11-12, we tell Buildroot to pass custom options to LuaRocks
  4513. when it is building the package.
  4514. On lines 13-14, we specify the licensing terms for the package.
  4515. Finally, on line 16, we invoke the luarocks-package macro that
  4516. generates all the Makefile rules that actually allows the package to
  4517. be built.
  4518. Most of these details can be retrieved from the rock and rockspec.
  4519. So, this file and the Config.in file can be generated by running the
  4520. command luarocks buildroot foo lua-foo in the Buildroot directory.
  4521. This command runs a specific Buildroot addon of luarocks that will
  4522. automatically generate a Buildroot package. The result must still be
  4523. manually inspected and possibly modified.
  4524. * The package/Config.in file has to be updated manually to include
  4525. the generated Config.in files.
  4526. 18.9.2. luarocks-package reference
  4527. LuaRocks is a deployment and management system for Lua modules, and
  4528. supports various build.type: builtin, make and cmake. In the context
  4529. of Buildroot, the luarocks-package infrastructure only supports the
  4530. builtin mode. LuaRocks packages that use the make or cmake build
  4531. mechanisms should instead be packaged using the generic-package and
  4532. cmake-package infrastructures in Buildroot, respectively.
  4533. The main macro of the LuaRocks package infrastructure is
  4534. luarocks-package: like generic-package it works by defining a number
  4535. of variables providing metadata information about the package, and
  4536. then calling luarocks-package.
  4537. Just like the generic infrastructure, the LuaRocks infrastructure
  4538. works by defining a number of variables before calling the
  4539. luarocks-package macro.
  4540. First, all the package metadata information variables that exist in
  4541. the generic infrastructure also exist in the LuaRocks infrastructure:
  4542. LUA_FOO_VERSION, LUA_FOO_SOURCE, LUA_FOO_SITE, LUA_FOO_DEPENDENCIES,
  4543. LUA_FOO_LICENSE, LUA_FOO_LICENSE_FILES.
  4544. Two of them are populated by the LuaRocks infrastructure (for the
  4545. download step). If your package is not hosted on the LuaRocks mirror
  4546. $(BR2_LUAROCKS_MIRROR), you can override them:
  4547. * LUA_FOO_SITE, which defaults to $(BR2_LUAROCKS_MIRROR)
  4548. * LUA_FOO_SOURCE, which defaults to $(lowercase
  4549. LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).src.rock
  4550. A few additional variables, specific to the LuaRocks infrastructure,
  4551. are also defined. They can be overridden in specific cases.
  4552. * LUA_FOO_NAME_UPSTREAM, which defaults to lua-foo, i.e. the
  4553. Buildroot package name
  4554. * LUA_FOO_ROCKSPEC, which defaults to $(lowercase
  4555. LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).rockspec
  4556. * LUA_FOO_SUBDIR, which defaults to $(LUA_FOO_NAME_UPSTREAM)-$
  4557. (LUA_FOO_VERSION_WITHOUT_ROCKSPEC_REVISION)
  4558. * LUA_FOO_BUILD_OPTS contains additional build options for the
  4559. luarocks build call.
  4560. 18.10. Infrastructure for Perl/CPAN packages
  4561. 18.10.1. perl-package tutorial
  4562. First, let’s see how to write a .mk file for a Perl/CPAN package,
  4563. with an example :
  4564. 01: ################################################################################
  4565. 02: #
  4566. 03: # perl-foo-bar
  4567. 04: #
  4568. 05: ################################################################################
  4569. 06:
  4570. 07: PERL_FOO_BAR_VERSION = 0.02
  4571. 08: PERL_FOO_BAR_SOURCE = Foo-Bar-$(PERL_FOO_BAR_VERSION).tar.gz
  4572. 09: PERL_FOO_BAR_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER
  4573. 10: PERL_FOO_BAR_DEPENDENCIES = perl-strictures
  4574. 11: PERL_FOO_BAR_LICENSE = Artistic or GPL-1.0+
  4575. 12: PERL_FOO_BAR_LICENSE_FILES = LICENSE
  4576. 13: PERL_FOO_BAR_DISTNAME = Foo-Bar
  4577. 14:
  4578. 15: $(eval $(perl-package))
  4579. On line 7, we declare the version of the package.
  4580. On line 8 and 9, we declare the name of the tarball and the location
  4581. of the tarball on a CPAN server. Buildroot will automatically
  4582. download the tarball from this location.
  4583. On line 10, we declare our dependencies, so that they are built
  4584. before the build process of our package starts.
  4585. On line 11 and 12, we give licensing details about the package (its
  4586. license on line 11, and the file containing the license text on line
  4587. 12).
  4588. On line 13, the name of the distribution as needed by the script
  4589. utils/scancpan (in order to regenerate/upgrade these package files).
  4590. Finally, on line 15, we invoke the perl-package macro that generates
  4591. all the Makefile rules that actually allow the package to be built.
  4592. Most of these data can be retrieved from https://metacpan.org/. So,
  4593. this file and the Config.in can be generated by running the script
  4594. utils/scancpan Foo-Bar in the Buildroot directory (or in a
  4595. br2-external tree). This script creates a Config.in file and
  4596. foo-bar.mk file for the requested package, and also recursively for
  4597. all dependencies specified by CPAN. You should still manually edit
  4598. the result. In particular, the following things should be checked.
  4599. * If the perl module links with a shared library that is provided
  4600. by another (non-perl) package, this dependency is not added
  4601. automatically. It has to be added manually to
  4602. PERL_FOO_BAR_DEPENDENCIES.
  4603. * The package/Config.in file has to be updated manually to include
  4604. the generated Config.in files. As a hint, the scancpan script
  4605. prints out the required source "…" statements, sorted
  4606. alphabetically.
  4607. 18.10.2. perl-package reference
  4608. As a policy, packages that provide Perl/CPAN modules should all be
  4609. named perl-<something> in Buildroot.
  4610. This infrastructure handles various Perl build systems :
  4611. ExtUtils-MakeMaker (EUMM), Module-Build (MB) and Module-Build-Tiny.
  4612. Build.PL is preferred by default when a package provides a
  4613. Makefile.PL and a Build.PL.
  4614. The main macro of the Perl/CPAN package infrastructure is
  4615. perl-package. It is similar to the generic-package macro. The ability
  4616. to have target and host packages is also available, with the
  4617. host-perl-package macro.
  4618. Just like the generic infrastructure, the Perl/CPAN infrastructure
  4619. works by defining a number of variables before calling the
  4620. perl-package macro.
  4621. First, all the package metadata information variables that exist in
  4622. the generic infrastructure also exist in the Perl/CPAN
  4623. infrastructure: PERL_FOO_VERSION, PERL_FOO_SOURCE, PERL_FOO_PATCH,
  4624. PERL_FOO_SITE, PERL_FOO_SUBDIR, PERL_FOO_DEPENDENCIES,
  4625. PERL_FOO_INSTALL_TARGET.
  4626. Note that setting PERL_FOO_INSTALL_STAGING to YES has no effect
  4627. unless a PERL_FOO_INSTALL_STAGING_CMDS variable is defined. The perl
  4628. infrastructure doesn’t define these commands since Perl modules
  4629. generally don’t need to be installed to the staging directory.
  4630. A few additional variables, specific to the Perl/CPAN infrastructure,
  4631. can also be defined. Many of them are only useful in very specific
  4632. cases, typical packages will therefore only use a few of them.
  4633. * PERL_FOO_PREFER_INSTALLER/HOST_PERL_FOO_PREFER_INSTALLER,
  4634. specifies the preferred installation method. Possible values are
  4635. EUMM (for Makefile.PL based installation using
  4636. ExtUtils-MakeMaker) and MB (for Build.PL based installation using
  4637. Module-Build). This variable is only used when the package
  4638. provides both installation methods.
  4639. * PERL_FOO_CONF_ENV/HOST_PERL_FOO_CONF_ENV, to specify additional
  4640. environment variables to pass to the perl Makefile.PL or perl
  4641. Build.PL. By default, empty.
  4642. * PERL_FOO_CONF_OPTS/HOST_PERL_FOO_CONF_OPTS, to specify additional
  4643. configure options to pass to the perl Makefile.PL or perl
  4644. Build.PL. By default, empty.
  4645. * PERL_FOO_BUILD_OPTS/HOST_PERL_FOO_BUILD_OPTS, to specify
  4646. additional options to pass to make pure_all or perl Build build
  4647. in the build step. By default, empty.
  4648. * PERL_FOO_INSTALL_TARGET_OPTS, to specify additional options to
  4649. pass to make pure_install or perl Build install in the install
  4650. step. By default, empty.
  4651. * HOST_PERL_FOO_INSTALL_OPTS, to specify additional options to pass
  4652. to make pure_install or perl Build install in the install step.
  4653. By default, empty.
  4654. 18.11. Infrastructure for virtual packages
  4655. In Buildroot, a virtual package is a package whose functionalities
  4656. are provided by one or more packages, referred to as providers. The
  4657. virtual package management is an extensible mechanism allowing the
  4658. user to choose the provider used in the rootfs.
  4659. For example, OpenGL ES is an API for 2D and 3D graphics on embedded
  4660. systems. The implementation of this API is different for the
  4661. Allwinner Tech Sunxi and the Texas Instruments OMAP35xx platforms. So
  4662. libgles will be a virtual package and sunxi-mali and ti-gfx will be
  4663. the providers.
  4664. 18.11.1. virtual-package tutorial
  4665. In the following example, we will explain how to add a new virtual
  4666. package (something-virtual) and a provider for it (some-provider).
  4667. First, let’s create the virtual package.
  4668. 18.11.2. Virtual package’s Config.in file
  4669. The Config.in file of virtual package something-virtual should
  4670. contain:
  4671. 01: config BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  4672. 02: bool
  4673. 03:
  4674. 04: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
  4675. 05: depends on BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  4676. 06: string
  4677. In this file, we declare two options,
  4678. BR2_PACKAGE_HAS_SOMETHING_VIRTUAL and
  4679. BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL, whose values will be used by
  4680. the providers.
  4681. 18.11.3. Virtual package’s .mk file
  4682. The .mk for the virtual package should just evaluate the
  4683. virtual-package macro:
  4684. 01: ################################################################################
  4685. 02: #
  4686. 03: # something-virtual
  4687. 04: #
  4688. 05: ################################################################################
  4689. 06:
  4690. 07: $(eval $(virtual-package))
  4691. The ability to have target and host packages is also available, with
  4692. the host-virtual-package macro.
  4693. 18.11.4. Provider’s Config.in file
  4694. When adding a package as a provider, only the Config.in file requires
  4695. some modifications.
  4696. The Config.in file of the package some-provider, which provides the
  4697. functionalities of something-virtual, should contain:
  4698. 01: config BR2_PACKAGE_SOME_PROVIDER
  4699. 02: bool "some-provider"
  4700. 03: select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  4701. 04: help
  4702. 05: This is a comment that explains what some-provider is.
  4703. 06:
  4704. 07: http://foosoftware.org/some-provider/
  4705. 08:
  4706. 09: if BR2_PACKAGE_SOME_PROVIDER
  4707. 10: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
  4708. 11: default "some-provider"
  4709. 12: endif
  4710. On line 3, we select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL, and on line
  4711. 11, we set the value of BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL to the
  4712. name of the provider, but only if it is selected.
  4713. 18.11.5. Provider’s .mk file
  4714. The .mk file should also declare an additional variable
  4715. SOME_PROVIDER_PROVIDES to contain the names of all the virtual
  4716. packages it is an implementation of:
  4717. 01: SOME_PROVIDER_PROVIDES = something-virtual
  4718. Of course, do not forget to add the proper build and runtime
  4719. dependencies for this package!
  4720. 18.11.6. Notes on depending on a virtual package
  4721. When adding a package that requires a certain FEATURE provided by a
  4722. virtual package, you have to use depends on BR2_PACKAGE_HAS_FEATURE,
  4723. like so:
  4724. config BR2_PACKAGE_HAS_FEATURE
  4725. bool
  4726. config BR2_PACKAGE_FOO
  4727. bool "foo"
  4728. depends on BR2_PACKAGE_HAS_FEATURE
  4729. 18.11.7. Notes on depending on a specific provider
  4730. If your package really requires a specific provider, then you’ll have
  4731. to make your package depends on this provider; you can not select a
  4732. provider.
  4733. Let’s take an example with two providers for a FEATURE:
  4734. config BR2_PACKAGE_HAS_FEATURE
  4735. bool
  4736. config BR2_PACKAGE_FOO
  4737. bool "foo"
  4738. select BR2_PACKAGE_HAS_FEATURE
  4739. config BR2_PACKAGE_BAR
  4740. bool "bar"
  4741. select BR2_PACKAGE_HAS_FEATURE
  4742. And you are adding a package that needs FEATURE as provided by foo,
  4743. but not as provided by bar.
  4744. If you were to use select BR2_PACKAGE_FOO, then the user would still
  4745. be able to select BR2_PACKAGE_BAR in the menuconfig. This would
  4746. create a configuration inconsistency, whereby two providers of the
  4747. same FEATURE would be enabled at once, one explicitly set by the
  4748. user, the other implicitly by your select.
  4749. Instead, you have to use depends on BR2_PACKAGE_FOO, which avoids any
  4750. implicit configuration inconsistency.
  4751. 18.12. Infrastructure for packages using kconfig for configuration
  4752. files
  4753. A popular way for a software package to handle user-specified
  4754. configuration is kconfig. Among others, it is used by the Linux
  4755. kernel, Busybox, and Buildroot itself. The presence of a .config file
  4756. and a menuconfig target are two well-known symptoms of kconfig being
  4757. used.
  4758. Buildroot features an infrastructure for packages that use kconfig
  4759. for their configuration. This infrastructure provides the necessary
  4760. logic to expose the package’s menuconfig target as foo-menuconfig in
  4761. Buildroot, and to handle the copying back and forth of the
  4762. configuration file in a correct way.
  4763. The kconfig-package infrastructure is based on the generic-package
  4764. infrastructure. All variables supported by generic-package are
  4765. available in kconfig-package as well. See Section 18.5.2,
  4766. “generic-package reference” for more details.
  4767. In order to use the kconfig-package infrastructure for a Buildroot
  4768. package, the minimally required lines in the .mk file, in addition to
  4769. the variables required by the generic-package infrastructure, are:
  4770. FOO_KCONFIG_FILE = reference-to-source-configuration-file
  4771. $(eval $(kconfig-package))
  4772. This snippet creates the following make targets:
  4773. * foo-menuconfig, which calls the package’s menuconfig target
  4774. * foo-update-config, which copies the configuration back to the
  4775. source configuration file. It is not possible to use this target
  4776. when fragment files are set.
  4777. * foo-update-defconfig, which copies the configuration back to the
  4778. source configuration file. The configuration file will only list
  4779. the options that differ from the default values. It is not
  4780. possible to use this target when fragment files are set.
  4781. * foo-diff-config, which outputs the differences between the
  4782. current configuration and the one defined in the Buildroot
  4783. configuration for this kconfig package. The output is useful to
  4784. identify the configuration changes that may have to be propagated
  4785. to configuration fragments for example.
  4786. and ensures that the source configuration file is copied to the build
  4787. directory at the right moment.
  4788. There are two options to specify a configuration file to use, either
  4789. FOO_KCONFIG_FILE (as in the example, above) or FOO_KCONFIG_DEFCONFIG.
  4790. It is mandatory to provide either, but not both:
  4791. * FOO_KCONFIG_FILE specifies the path to a defconfig or full-config
  4792. file to be used to configure the package.
  4793. * FOO_KCONFIG_DEFCONFIG specifies the defconfig make rule to call
  4794. to configure the package.
  4795. In addition to these minimally required lines, several optional
  4796. variables can be set to suit the needs of the package under
  4797. consideration:
  4798. * FOO_KCONFIG_EDITORS: a space-separated list of kconfig editors to
  4799. support, for example menuconfig xconfig. By default, menuconfig.
  4800. * FOO_KCONFIG_FRAGMENT_FILES: a space-separated list of
  4801. configuration fragment files that are merged to the main
  4802. configuration file. Fragment files are typically used when there
  4803. is a desire to stay in sync with an upstream (def)config file,
  4804. with some minor modifications.
  4805. * FOO_KCONFIG_OPTS: extra options to pass when calling the kconfig
  4806. editors. This may need to include $(FOO_MAKE_OPTS), for example.
  4807. By default, empty.
  4808. * FOO_KCONFIG_FIXUP_CMDS: a list of shell commands needed to fixup
  4809. the configuration file after copying it or running a kconfig
  4810. editor. Such commands may be needed to ensure a configuration
  4811. consistent with other configuration of Buildroot, for example. By
  4812. default, empty.
  4813. * FOO_KCONFIG_DOTCONFIG: path (with filename) of the .config file,
  4814. relative to the package source tree. The default, .config, should
  4815. be well suited for all packages that use the standard kconfig
  4816. infrastructure as inherited from the Linux kernel; some packages
  4817. use a derivative of kconfig that use a different location.
  4818. * FOO_KCONFIG_DEPENDENCIES: the list of packages (most probably,
  4819. host packages) that need to be built before this package’s
  4820. kconfig is interpreted. Seldom used. By default, empty.
  4821. 18.13. Infrastructure for rebar-based packages
  4822. 18.13.1. rebar-package tutorial
  4823. First, let’s see how to write a .mk file for a rebar-based package,
  4824. with an example :
  4825. 01: ################################################################################
  4826. 02: #
  4827. 03: # erlang-foobar
  4828. 04: #
  4829. 05: ################################################################################
  4830. 06:
  4831. 07: ERLANG_FOOBAR_VERSION = 1.0
  4832. 08: ERLANG_FOOBAR_SOURCE = erlang-foobar-$(ERLANG_FOOBAR_VERSION).tar.xz
  4833. 09: ERLANG_FOOBAR_SITE = http://www.foosoftware.org/download
  4834. 10: ERLANG_FOOBAR_DEPENDENCIES = host-libaaa libbbb
  4835. 11:
  4836. 12: $(eval $(rebar-package))
  4837. On line 7, we declare the version of the package.
  4838. On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  4839. recommended) and the location of the tarball on the Web. Buildroot
  4840. will automatically download the tarball from this location.
  4841. On line 10, we declare our dependencies, so that they are built
  4842. before the build process of our package starts.
  4843. Finally, on line 12, we invoke the rebar-package macro that generates
  4844. all the Makefile rules that actually allows the package to be built.
  4845. 18.13.2. rebar-package reference
  4846. The main macro of the rebar package infrastructure is rebar-package.
  4847. It is similar to the generic-package macro. The ability to have host
  4848. packages is also available, with the host-rebar-package macro.
  4849. Just like the generic infrastructure, the rebar infrastructure works
  4850. by defining a number of variables before calling the rebar-package
  4851. macro.
  4852. First, all the package metadata information variables that exist in
  4853. the generic infrastructure also exist in the rebar infrastructure:
  4854. ERLANG_FOOBAR_VERSION, ERLANG_FOOBAR_SOURCE, ERLANG_FOOBAR_PATCH,
  4855. ERLANG_FOOBAR_SITE, ERLANG_FOOBAR_SUBDIR, ERLANG_FOOBAR_DEPENDENCIES,
  4856. ERLANG_FOOBAR_INSTALL_STAGING, ERLANG_FOOBAR_INSTALL_TARGET,
  4857. ERLANG_FOOBAR_LICENSE and ERLANG_FOOBAR_LICENSE_FILES.
  4858. A few additional variables, specific to the rebar infrastructure, can
  4859. also be defined. Many of them are only useful in very specific cases,
  4860. typical packages will therefore only use a few of them.
  4861. * ERLANG_FOOBAR_USE_AUTOCONF, to specify that the package uses
  4862. autoconf at the configuration step. When a package sets this
  4863. variable to YES, the autotools infrastructure is used.
  4864. Note. You can also use some of the variables from the autotools
  4865. infrastructure: ERLANG_FOOBAR_CONF_ENV, ERLANG_FOOBAR_CONF_OPTS,
  4866. ERLANG_FOOBAR_AUTORECONF, ERLANG_FOOBAR_AUTORECONF_ENV and
  4867. ERLANG_FOOBAR_AUTORECONF_OPTS.
  4868. * ERLANG_FOOBAR_USE_BUNDLED_REBAR, to specify that the package has
  4869. a bundled version of rebar and that it shall be used. Valid
  4870. values are YES or NO (the default).
  4871. Note. If the package bundles a rebar utility, but can use the
  4872. generic one that Buildroot provides, just say NO (i.e., do not
  4873. specify this variable). Only set if it is mandatory to use the
  4874. rebar utility bundled in this package.
  4875. * ERLANG_FOOBAR_REBAR_ENV, to specify additional environment
  4876. variables to pass to the rebar utility.
  4877. * ERLANG_FOOBAR_KEEP_DEPENDENCIES, to keep the dependencies
  4878. described in the rebar.config file. Valid values are YES or NO
  4879. (the default). Unless this variable is set to YES, the rebar
  4880. infrastructure removes such dependencies in a post-patch hook to
  4881. ensure rebar does not download nor compile them.
  4882. With the rebar infrastructure, all the steps required to build and
  4883. install the packages are already defined, and they generally work
  4884. well for most rebar-based packages. However, when required, it is
  4885. still possible to customize what is done in any particular step:
  4886. * By adding a post-operation hook (after extract, patch, configure,
  4887. build or install). See Section 18.22, “Hooks available in the
  4888. various build steps” for details.
  4889. * By overriding one of the steps. For example, even if the rebar
  4890. infrastructure is used, if the package .mk file defines its own
  4891. ERLANG_FOOBAR_BUILD_CMDS variable, it will be used instead of the
  4892. default rebar one. However, using this method should be
  4893. restricted to very specific cases. Do not use it in the general
  4894. case.
  4895. 18.14. Infrastructure for Waf-based packages
  4896. 18.14.1. waf-package tutorial
  4897. First, let’s see how to write a .mk file for a Waf-based package,
  4898. with an example :
  4899. 01: ################################################################################
  4900. 02: #
  4901. 03: # libfoo
  4902. 04: #
  4903. 05: ################################################################################
  4904. 06:
  4905. 07: LIBFOO_VERSION = 1.0
  4906. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  4907. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  4908. 10: LIBFOO_CONF_OPTS = --enable-bar --disable-baz
  4909. 11: LIBFOO_DEPENDENCIES = bar
  4910. 12:
  4911. 13: $(eval $(waf-package))
  4912. On line 7, we declare the version of the package.
  4913. On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  4914. recommended) and the location of the tarball on the Web. Buildroot
  4915. will automatically download the tarball from this location.
  4916. On line 10, we tell Buildroot what options to enable for libfoo.
  4917. On line 11, we tell Buildroot the dependencies of libfoo.
  4918. Finally, on line line 13, we invoke the waf-package macro that
  4919. generates all the Makefile rules that actually allows the package to
  4920. be built.
  4921. 18.14.2. waf-package reference
  4922. The main macro of the Waf package infrastructure is waf-package. It
  4923. is similar to the generic-package macro.
  4924. Just like the generic infrastructure, the Waf infrastructure works by
  4925. defining a number of variables before calling the waf-package macro.
  4926. First, all the package metadata information variables that exist in
  4927. the generic infrastructure also exist in the Waf infrastructure:
  4928. LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE,
  4929. LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING,
  4930. LIBFOO_INSTALL_TARGET.
  4931. An additional variable, specific to the Waf infrastructure, can also
  4932. be defined.
  4933. * LIBFOO_SUBDIR may contain the name of a subdirectory inside the
  4934. package that contains the main wscript file. This is useful, if
  4935. for example, the main wscript file is not at the root of the tree
  4936. extracted by the tarball. If HOST_LIBFOO_SUBDIR is not specified,
  4937. it defaults to LIBFOO_SUBDIR.
  4938. * LIBFOO_NEEDS_EXTERNAL_WAF can be set to YES or NO to tell
  4939. Buildroot to use the bundled waf executable. If set to NO, the
  4940. default, then Buildroot will use the waf executable provided in
  4941. the package source tree; if set to YES, then Buildroot will
  4942. download, install waf as a host tool and use it to build the
  4943. package.
  4944. * LIBFOO_WAF_OPTS, to specify additional options to pass to the waf
  4945. script at every step of the package build process: configure,
  4946. build and installation. By default, empty.
  4947. * LIBFOO_CONF_OPTS, to specify additional options to pass to the
  4948. waf script for the configuration step. By default, empty.
  4949. * LIBFOO_BUILD_OPTS, to specify additional options to pass to the
  4950. waf script during the build step. By default, empty.
  4951. * LIBFOO_INSTALL_STAGING_OPTS, to specify additional options to
  4952. pass to the waf script during the staging installation step. By
  4953. default, empty.
  4954. * LIBFOO_INSTALL_TARGET_OPTS, to specify additional options to pass
  4955. to the waf script during the target installation step. By
  4956. default, empty.
  4957. 18.15. Infrastructure for Meson-based packages
  4958. 18.15.1. meson-package tutorial
  4959. Meson [http://mesonbuild.com] is an open source build system meant to
  4960. be both extremely fast, and, even more importantly, as user friendly
  4961. as possible. It uses Ninja [https://ninja-build.org] as a companion
  4962. tool to perform the actual build operations.
  4963. Let’s see how to write a .mk file for a Meson-based package, with an
  4964. example:
  4965. 01: ################################################################################
  4966. 02: #
  4967. 03: # foo
  4968. 04: #
  4969. 05: ################################################################################
  4970. 06:
  4971. 07: FOO_VERSION = 1.0
  4972. 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
  4973. 09: FOO_SITE = http://www.foosoftware.org/download
  4974. 10: FOO_LICENSE = GPL-3.0+
  4975. 11: FOO_LICENSE_FILES = COPYING
  4976. 12: FOO_INSTALL_STAGING = YES
  4977. 13:
  4978. 14: FOO_DEPENDENCIES = host-pkgconf bar
  4979. 15:
  4980. 16: ifeq ($(BR2_PACKAGE_BAZ),y)
  4981. 17: FOO_CONF_OPTS += -Dbaz=true
  4982. 18: FOO_DEPENDENCIES += baz
  4983. 19: else
  4984. 20: FOO_CONF_OPTS += -Dbaz=false
  4985. 21: endif
  4986. 22:
  4987. 23: $(eval $(meson-package))
  4988. The Makefile starts with the definition of the standard variables for
  4989. package declaration (lines 7 to 11).
  4990. On line line 23, we invoke the meson-package macro that generates all
  4991. the Makefile rules that actually allows the package to be built.
  4992. In the example, host-pkgconf and bar are declared as dependencies in
  4993. FOO_DEPENDENCIES at line 14 because the Meson build file of foo uses
  4994. pkg-config to determine the compilation flags and libraries of
  4995. package bar.
  4996. Note that it is not necessary to add host-meson in the
  4997. FOO_DEPENDENCIES variable of a package, since this basic dependency
  4998. is automatically added as needed by the Meson package infrastructure.
  4999. If the "baz" package is selected, then support for the "baz" feature
  5000. in "foo" is activated by adding -Dbaz=true to FOO_CONF_OPTS at line
  5001. 17, as specified in the meson_options.txt file in "foo" source tree.
  5002. The "baz" package is also added to FOO_DEPENDENCIES. Note that the
  5003. support for baz is explicitly disabled at line 20, if the package is
  5004. not selected.
  5005. To sum it up, to add a new meson-based package, the Makefile example
  5006. can be copied verbatim then edited to replace all occurences of FOO
  5007. with the uppercase name of the new package and update the values of
  5008. the standard variables.
  5009. 18.15.2. meson-package reference
  5010. The main macro of the Meson package infrastructure is meson-package.
  5011. It is similar to the generic-package macro. The ability to have
  5012. target and host packages is also available, with the
  5013. host-meson-package macro.
  5014. Just like the generic infrastructure, the Meson infrastructure works
  5015. by defining a number of variables before calling the meson-package
  5016. macro.
  5017. First, all the package metadata information variables that exist in
  5018. the generic infrastructure also exist in the Meson infrastructure:
  5019. FOO_VERSION, FOO_SOURCE, FOO_PATCH, FOO_SITE, FOO_SUBDIR,
  5020. FOO_DEPENDENCIES, FOO_INSTALL_STAGING, FOO_INSTALL_TARGET.
  5021. A few additional variables, specific to the Meson infrastructure, can
  5022. also be defined. Many of them are only useful in very specific cases,
  5023. typical packages will therefore only use a few of them.
  5024. * FOO_SUBDIR may contain the name of a subdirectory inside the
  5025. package that contains the main meson.build file. This is useful,
  5026. if for example, the main meson.build file is not at the root of
  5027. the tree extracted by the tarball. If HOST_FOO_SUBDIR is not
  5028. specified, it defaults to FOO_SUBDIR.
  5029. * FOO_CONF_ENV, to specify additional environment variables to pass
  5030. to meson for the configuration step. By default, empty.
  5031. * FOO_CONF_OPTS, to specify additional options to pass to meson for
  5032. the configuration step. By default, empty.
  5033. * FOO_CFLAGS, to specify compiler arguments added to the package
  5034. specific cross-compile.conf file c_args property. By default, the
  5035. value of TARGET_CFLAGS.
  5036. * FOO_CXXFLAGS, to specify compiler arguments added to the package
  5037. specific cross-compile.conf file cpp_args property. By default,
  5038. the value of TARGET_CXXFLAGS.
  5039. * FOO_LDFLAGS, to specify compiler arguments added to the package
  5040. specific cross-compile.conf file c_link_args and cpp_link_args
  5041. properties. By default, the value of TARGET_LDFLAGS.
  5042. * FOO_MESON_EXTRA_BINARIES, to specify a space-separated list of
  5043. programs to add to the [binaries] section of the meson
  5044. cross-compilation.conf configuration file. The format is
  5045. program-name='/path/to/program', with no space around the = sign,
  5046. and with the path of the program between single quotes. By
  5047. default, empty. Note that Buildroot already sets the correct
  5048. values for c, cpp, ar, strip, and pkgconfig.
  5049. * FOO_MESON_EXTRA_PROPERTIES, to specify a space-separated list of
  5050. properties to add to the [properties] section of the meson
  5051. cross-compilation.conf configuration file. The format is
  5052. property-name=<value> with no space around the = sign, and with
  5053. single quotes around string values. By default, empty. Note that
  5054. Buildroot already sets values for needs_exe_wrapper, c_args,
  5055. c_link_args, cpp_args, cpp_link_args, sys_root, and
  5056. pkg_config_libdir.
  5057. * FOO_NINJA_ENV, to specify additional environment variables to
  5058. pass to ninja, meson companion tool in charge of the build
  5059. operations. By default, empty.
  5060. * FOO_NINJA_OPTS, to specify a space-separated list of targets to
  5061. build. By default, empty, to build the default target(s).
  5062. 18.16. Integration of Cargo-based packages
  5063. Cargo is the package manager for the Rust programming language. It
  5064. allows the user to build programs or libraries written in Rust, but
  5065. it also downloads and manages their dependencies, to ensure
  5066. repeatable builds. Cargo packages are called "crates".
  5067. 18.16.1. Cargo-based package’s Config.in file
  5068. The Config.in file of Cargo-based package foo should contain:
  5069. 01: config BR2_PACKAGE_FOO
  5070. 02: bool "foo"
  5071. 03: depends on BR2_PACKAGE_HOST_RUSTC_TARGET_ARCH_SUPPORTS
  5072. 04: select BR2_PACKAGE_HOST_RUSTC
  5073. 05: help
  5074. 06: This is a comment that explains what foo is.
  5075. 07:
  5076. 08: http://foosoftware.org/foo/
  5077. 18.16.2. Cargo-based package’s .mk file
  5078. Buildroot does not (yet) provide a dedicated package infrastructure
  5079. for Cargo-based packages. So, we will explain how to write a .mk file
  5080. for such a package. Let’s start with an example:
  5081. 01: ################################################################################
  5082. 02: #
  5083. 03: # foo
  5084. 04: #
  5085. 05: ################################################################################
  5086. 06:
  5087. 07: FOO_VERSION = 1.0
  5088. 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
  5089. 09: FOO_SITE = http://www.foosoftware.org/download
  5090. 10: FOO_LICENSE = GPL-3.0+
  5091. 11: FOO_LICENSE_FILES = COPYING
  5092. 12:
  5093. 13: FOO_DEPENDENCIES = host-rustc
  5094. 14:
  5095. 15: FOO_CARGO_ENV = CARGO_HOME=$(HOST_DIR)/share/cargo
  5096. 16:
  5097. 17: FOO_BIN_DIR = target/$(RUSTC_TARGET_NAME)/$(FOO_CARGO_MODE)
  5098. 18:
  5099. 19: FOO_CARGO_OPTS = \
  5100. 20: $(if $(BR2_ENABLE_DEBUG),,--release) \
  5101. 21: --target=$(RUSTC_TARGET_NAME) \
  5102. 22: --manifest-path=$(@D)/Cargo.toml
  5103. 23:
  5104. 24: define FOO_BUILD_CMDS
  5105. 25: $(TARGET_MAKE_ENV) $(FOO_CARGO_ENV) \
  5106. 26: cargo build $(FOO_CARGO_OPTS)
  5107. 27: endef
  5108. 28:
  5109. 29: define FOO_INSTALL_TARGET_CMDS
  5110. 30: $(INSTALL) -D -m 0755 $(@D)/$(FOO_BIN_DIR)/foo \
  5111. 31: $(TARGET_DIR)/usr/bin/foo
  5112. 32: endef
  5113. 33:
  5114. 34: $(eval $(generic-package))
  5115. The Makefile starts with the definition of the standard variables for
  5116. package declaration (lines 7 to 11).
  5117. As seen in line 34, it is based on the generic-package infrastructure
  5118. . So, it defines the variables required by this particular
  5119. infrastructure, where Cargo is invoked:
  5120. * FOO_BUILD_CMDS: Cargo is invoked to perform the build. The
  5121. options required to configure the cross-compilation of the
  5122. package are passed via FOO_CONF_OPTS.
  5123. * FOO_INSTALL_TARGET_CMDS: The binary executable generated is
  5124. installed on the target.
  5125. In order to have Cargo available for the build, FOO_DEPENDENCIES
  5126. needs to contain host-cargo.
  5127. To sum it up, to add a new Cargo-based package, the Makefile example
  5128. can be copied verbatim then edited to replace all occurences of FOO
  5129. with the uppercase name of the new package and update the values of
  5130. the standard variables.
  5131. 18.16.3. About Dependencies Management
  5132. A crate can depend on other libraries from crates.io or git
  5133. repositories, listed in its Cargo.toml file. Before starting a build,
  5134. Cargo usually downloads automatically them. This step can also be
  5135. performed independently, via the cargo fetch command.
  5136. Cargo maintains a local cache of the registry index and of git
  5137. checkouts of the crates, whose location is given by $CARGO_HOME. As
  5138. seen in the package Makefile example at line 15, this environment
  5139. variable is set to $(HOST_DIR)/share/cargo.
  5140. This dependency download mechanism is not convenient when performing
  5141. an offline build, as Cargo will fail to fetch the dependencies. In
  5142. that case, it is advised to generate a tarball of the dependencies
  5143. using the cargo vendor and add it to FOO_EXTRA_DOWNLOADS.
  5144. 18.17. Infrastructure for Go packages
  5145. This infrastructure applies to Go packages that use the standard
  5146. build system and use bundled dependencies.
  5147. 18.17.1. golang-package tutorial
  5148. First, let’s see how to write a .mk file for a go package, with an
  5149. example :
  5150. 01: ################################################################################
  5151. 02: #
  5152. 03: # foo
  5153. 04: #
  5154. 05: ################################################################################
  5155. 06:
  5156. 07: FOO_VERSION = 1.0
  5157. 08: FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))
  5158. 09: FOO_LICENSE = BSD-3-Clause
  5159. 10: FOO_LICENSE_FILES = LICENSE
  5160. 11:
  5161. 12: $(eval $(golang-package))
  5162. On line 7, we declare the version of the package.
  5163. On line 8, we declare the upstream location of the package, here
  5164. fetched from Github, since a large number of Go packages are hosted
  5165. on Github.
  5166. On line 9 and 10, we give licensing details about the package.
  5167. Finally, on line 12, we invoke the golang-package macro that
  5168. generates all the Makefile rules that actually allow the package to
  5169. be built.
  5170. 18.17.2. golang-package reference
  5171. In their Config.in file, packages using the golang-package
  5172. infrastructure should depend on
  5173. BR2_PACKAGE_HOST_GO_TARGET_ARCH_SUPPORTS because Buildroot will
  5174. automatically add a dependency on host-go to such packages. If you
  5175. need CGO support in your package, you must add a dependency on
  5176. BR2_PACKAGE_HOST_GO_TARGET_CGO_LINKING_SUPPORTS.
  5177. The main macro of the Go package infrastructure is golang-package. It
  5178. is similar to the generic-package macro. The ability to build host
  5179. packages is also available, with the host-golang-package macro. Host
  5180. packages built by host-golang-package macro should depend on
  5181. BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.
  5182. Just like the generic infrastructure, the Go infrastructure works by
  5183. defining a number of variables before calling the golang-package.
  5184. All the package metadata information variables that exist in the
  5185. generic package infrastructure also exist in the Go infrastructure:
  5186. FOO_VERSION, FOO_SOURCE, FOO_PATCH, FOO_SITE, FOO_SUBDIR,
  5187. FOO_DEPENDENCIES, FOO_LICENSE, FOO_LICENSE_FILES,
  5188. FOO_INSTALL_STAGING, etc.
  5189. Note that it is not necessary to add host-go in the FOO_DEPENDENCIES
  5190. variable of a package, since this basic dependency is automatically
  5191. added as needed by the Go package infrastructure.
  5192. A few additional variables, specific to the Go infrastructure, can
  5193. optionally be defined, depending on the package’s needs. Many of them
  5194. are only useful in very specific cases, typical packages will
  5195. therefore only use a few of them, or none.
  5196. * The package must specify its Go module name in the FOO_GOMOD
  5197. variable. If not specified, it defaults to URL-domain/
  5198. 1st-part-of-URL/2nd-part-of-URL, e.g FOO_GOMOD will take the
  5199. value github.com/bar/foo for a package that specifies FOO_SITE =
  5200. $(call github,bar,foo,$(FOO_VERSION)). The Go package
  5201. infrastructure will automatically generate a minimal go.mod file
  5202. in the package source tree if it doesn’t exist.
  5203. * FOO_LDFLAGS and FOO_TAGS can be used to pass respectively the
  5204. LDFLAGS or the TAGS to the go build command.
  5205. * FOO_BUILD_TARGETS can be used to pass the list of targets that
  5206. should be built. If FOO_BUILD_TARGETS is not specified, it
  5207. defaults to .. We then have two cases:
  5208. + FOO_BUILD_TARGETS is .. In this case, we assume only one
  5209. binary will be produced, and that by default we name it after
  5210. the package name. If that is not appropriate, the name of the
  5211. produced binary can be overridden using FOO_BIN_NAME.
  5212. + FOO_BUILD_TARGETS is not .. In this case, we iterate over the
  5213. values to build each target, and for each produced a binary
  5214. that is the non-directory component of the target. For
  5215. example if FOO_BUILD_TARGETS = cmd/docker cmd/dockerd the
  5216. binaries produced are docker and dockerd.
  5217. * FOO_INSTALL_BINS can be used to pass the list of binaries that
  5218. should be installed in /usr/bin on the target. If
  5219. FOO_INSTALL_BINS is not specified, it defaults to the lower-case
  5220. name of package.
  5221. With the Go infrastructure, all the steps required to build and
  5222. install the packages are already defined, and they generally work
  5223. well for most Go-based packages. However, when required, it is still
  5224. possible to customize what is done in any particular step:
  5225. * By adding a post-operation hook (after extract, patch, configure,
  5226. build or install). See Section 18.22, “Hooks available in the
  5227. various build steps” for details.
  5228. * By overriding one of the steps. For example, even if the Go
  5229. infrastructure is used, if the package .mk file defines its own
  5230. FOO_BUILD_CMDS variable, it will be used instead of the default
  5231. Go one. However, using this method should be restricted to very
  5232. specific cases. Do not use it in the general case.
  5233. 18.18. Infrastructure for QMake-based packages
  5234. 18.18.1. qmake-package tutorial
  5235. First, let’s see how to write a .mk file for a QMake-based package,
  5236. with an example :
  5237. 01: ################################################################################
  5238. 02: #
  5239. 03: # libfoo
  5240. 04: #
  5241. 05: ################################################################################
  5242. 06:
  5243. 07: LIBFOO_VERSION = 1.0
  5244. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  5245. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  5246. 10: LIBFOO_CONF_OPTS = QT_CONFIG+=bar QT_CONFIG-=baz
  5247. 11: LIBFOO_DEPENDENCIES = bar
  5248. 12:
  5249. 13: $(eval $(qmake-package))
  5250. On line 7, we declare the version of the package.
  5251. On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  5252. recommended) and the location of the tarball on the Web. Buildroot
  5253. will automatically download the tarball from this location.
  5254. On line 10, we tell Buildroot what options to enable for libfoo.
  5255. On line 11, we tell Buildroot the dependencies of libfoo.
  5256. Finally, on line line 13, we invoke the qmake-package macro that
  5257. generates all the Makefile rules that actually allows the package to
  5258. be built.
  5259. 18.18.2. qmake-package reference
  5260. The main macro of the QMake package infrastructure is qmake-package.
  5261. It is similar to the generic-package macro.
  5262. Just like the generic infrastructure, the QMake infrastructure works
  5263. by defining a number of variables before calling the qmake-package
  5264. macro.
  5265. First, all the package metadata information variables that exist in
  5266. the generic infrastructure also exist in the QMake infrastructure:
  5267. LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE,
  5268. LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING,
  5269. LIBFOO_INSTALL_TARGET.
  5270. An additional variable, specific to the QMake infrastructure, can
  5271. also be defined.
  5272. * LIBFOO_CONF_ENV, to specify additional environment variables to
  5273. pass to the qmake script for the configuration step. By default,
  5274. empty.
  5275. * LIBFOO_CONF_OPTS, to specify additional options to pass to the
  5276. qmake script for the configuration step. By default, empty.
  5277. * LIBFOO_MAKE_ENV, to specify additional environment variables to
  5278. the make command during the build and install steps. By default,
  5279. empty.
  5280. * LIBFOO_MAKE_OPTS, to specify additional targets to pass to the
  5281. make command during the build step. By default, empty.
  5282. * LIBFOO_INSTALL_STAGING_OPTS, to specify additional targets to
  5283. pass to the make command during the staging installation step. By
  5284. default, install.
  5285. * LIBFOO_INSTALL_TARGET_OPTS, to specify additional targets to pass
  5286. to the make command during the target installation step. By
  5287. default, install.
  5288. 18.19. Infrastructure for packages building kernel modules
  5289. Buildroot offers a helper infrastructure to make it easy to write
  5290. packages that build and install Linux kernel modules. Some packages
  5291. only contain a kernel module, other packages contain programs and
  5292. libraries in addition to kernel modules. Buildroot’s helper
  5293. infrastructure supports either case.
  5294. 18.19.1. kernel-module tutorial
  5295. Let’s start with an example on how to prepare a simple package that
  5296. only builds a kernel module, and no other component:
  5297. 01: ################################################################################
  5298. 02: #
  5299. 03: # foo
  5300. 04: #
  5301. 05: ################################################################################
  5302. 06:
  5303. 07: FOO_VERSION = 1.2.3
  5304. 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
  5305. 09: FOO_SITE = http://www.foosoftware.org/download
  5306. 10: FOO_LICENSE = GPL-2.0
  5307. 11: FOO_LICENSE_FILES = COPYING
  5308. 12:
  5309. 13: $(eval $(kernel-module))
  5310. 14: $(eval $(generic-package))
  5311. Lines 7-11 define the usual meta-data to specify the version, archive
  5312. name, remote URI where to find the package source, licensing
  5313. information.
  5314. On line 13, we invoke the kernel-module helper infrastructure, that
  5315. generates all the appropriate Makefile rules and variables to build
  5316. that kernel module.
  5317. Finally, on line 14, we invoke the generic-package infrastructure.
  5318. The dependency on linux is automatically added, so it is not needed
  5319. to specify it in FOO_DEPENDENCIES.
  5320. What you may have noticed is that, unlike other package
  5321. infrastructures, we explicitly invoke a second infrastructure. This
  5322. allows a package to build a kernel module, but also, if needed, use
  5323. any one of other package infrastructures to build normal userland
  5324. components (libraries, executables…). Using the kernel-module
  5325. infrastructure on its own is not sufficient; another package
  5326. infrastructure must be used.
  5327. Let’s look at a more complex example:
  5328. 01: ################################################################################
  5329. 02: #
  5330. 03: # foo
  5331. 04: #
  5332. 05: ################################################################################
  5333. 06:
  5334. 07: FOO_VERSION = 1.2.3
  5335. 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
  5336. 09: FOO_SITE = http://www.foosoftware.org/download
  5337. 10: FOO_LICENSE = GPL-2.0
  5338. 11: FOO_LICENSE_FILES = COPYING
  5339. 12:
  5340. 13: FOO_MODULE_SUBDIRS = driver/base
  5341. 14: FOO_MODULE_MAKE_OPTS = KVERSION=$(LINUX_VERSION_PROBED)
  5342. 15:
  5343. 16: ifeq ($(BR2_PACKAGE_LIBBAR),y)
  5344. 17: FOO_DEPENDENCIES = libbar
  5345. 18: FOO_CONF_OPTS = --enable-bar
  5346. 19: FOO_MODULE_SUBDIRS += driver/bar
  5347. 20: else
  5348. 21: FOO_CONF_OPTS = --disable-bar
  5349. 22: endif
  5350. 23:
  5351. 24: $(eval $(kernel-module))
  5352. 26: $(eval $(autotools-package))
  5353. Here, we see that we have an autotools-based package, that also
  5354. builds the kernel module located in sub-directory driver/base and, if
  5355. libbar is enabled, the kernel module located in sub-directory driver/
  5356. bar, and defines the variable KVERSION to be passed to the Linux
  5357. buildsystem when building the module(s).
  5358. 18.19.2. kernel-module reference
  5359. The main macro for the kernel module infrastructure is kernel-module.
  5360. Unlike other package infrastructures, it is not stand-alone, and
  5361. requires any of the other *-package macros be called after it.
  5362. The kernel-module macro defines post-build and post-target-install
  5363. hooks to build the kernel modules. If the package’s .mk needs access
  5364. to the built kernel modules, it should do so in a post-build hook,
  5365. registered after the call to kernel-module. Similarly, if the
  5366. package’s .mk needs access to the kernel module after it has been
  5367. installed, it should do so in a post-install hook, registered after
  5368. the call to kernel-module. Here’s an example:
  5369. $(eval $(kernel-module))
  5370. define FOO_DO_STUFF_WITH_KERNEL_MODULE
  5371. # Do something with it...
  5372. endef
  5373. FOO_POST_BUILD_HOOKS += FOO_DO_STUFF_WITH_KERNEL_MODULE
  5374. $(eval $(generic-package))
  5375. Finally, unlike the other package infrastructures, there is no
  5376. host-kernel-module variant to build a host kernel module.
  5377. The following additional variables can optionally be defined to
  5378. further configure the build of the kernel module:
  5379. * FOO_MODULE_SUBDIRS may be set to one or more sub-directories
  5380. (relative to the package source top-directory) where the kernel
  5381. module sources are. If empty or not set, the sources for the
  5382. kernel module(s) are considered to be located at the top of the
  5383. package source tree.
  5384. * FOO_MODULE_MAKE_OPTS may be set to contain extra variable
  5385. definitions to pass to the Linux buildsystem.
  5386. You may also reference (but you may not set!) those variables:
  5387. * LINUX_DIR contains the path to where the Linux kernel has been
  5388. extracted and built.
  5389. * LINUX_VERSION contains the version string as configured by the
  5390. user.
  5391. * LINUX_VERSION_PROBED contains the real version string of the
  5392. kernel, retrieved with running make -C $(LINUX_DIR) kernelrelease
  5393. * KERNEL_ARCH contains the name of the current architecture, like
  5394. arm, mips…
  5395. 18.20. Infrastructure for asciidoc documents
  5396. The Buildroot manual, which you are currently reading, is entirely
  5397. written using the AsciiDoc [http://asciidoc.org/] mark-up syntax. The
  5398. manual is then rendered to many formats:
  5399. * html
  5400. * split-html
  5401. * pdf
  5402. * epub
  5403. * text
  5404. Although Buildroot only contains one document written in AsciiDoc,
  5405. there is, as for packages, an infrastructure for rendering documents
  5406. using the AsciiDoc syntax.
  5407. Also as for packages, the AsciiDoc infrastructure is available from a
  5408. br2-external tree. This allows documentation for a br2-external tree
  5409. to match the Buildroot documentation, as it will be rendered to the
  5410. same formats and use the same layout and theme.
  5411. 18.20.1. asciidoc-document tutorial
  5412. Whereas package infrastructures are suffixed with -package, the
  5413. document infrastructures are suffixed with -document. So, the
  5414. AsciiDoc infrastructure is named asciidoc-document.
  5415. Here is an example to render a simple AsciiDoc document.
  5416. 01: ################################################################################
  5417. 02: #
  5418. 03: # foo-document
  5419. 04: #
  5420. 05: ################################################################################
  5421. 06:
  5422. 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
  5423. 08: $(eval $(call asciidoc-document))
  5424. On line 7, the Makefile declares what the sources of the document
  5425. are. Currently, it is expected that the document’s sources are only
  5426. local; Buildroot will not attempt to download anything to render a
  5427. document. Thus, you must indicate where the sources are. Usually, the
  5428. string above is sufficient for a document with no sub-directory
  5429. structure.
  5430. On line 8, we call the asciidoc-document function, which generates
  5431. all the Makefile code necessary to render the document.
  5432. 18.20.2. asciidoc-document reference
  5433. The list of variables that can be set in a .mk file to give metadata
  5434. information is (assuming the document name is foo) :
  5435. * FOO_SOURCES, mandatory, defines the source files for the
  5436. document.
  5437. * FOO_RESOURCES, optional, may contain a space-separated list of
  5438. paths to one or more directories containing so-called resources
  5439. (like CSS or images). By default, empty.
  5440. * FOO_DEPENDENCIES, optional, the list of packages (most probably,
  5441. host-packages) that must be built before building this document.
  5442. There are also additional hooks (see Section 18.22, “Hooks available
  5443. in the various build steps” for general information on hooks), that a
  5444. document may set to define extra actions to be done at various steps:
  5445. * FOO_POST_RSYNC_HOOKS to run additional commands after the sources
  5446. have been copied by Buildroot. This can for example be used to
  5447. generate part of the manual with information extracted from the
  5448. tree. As an example, Buildroot uses this hook to generate the
  5449. tables in the appendices.
  5450. * FOO_CHECK_DEPENDENCIES_HOOKS to run additional tests on required
  5451. components to generate the document. In AsciiDoc, it is possible
  5452. to call filters, that is, programs that will parse an AsciiDoc
  5453. block and render it appropriately (e.g. ditaa [http://
  5454. ditaa.sourceforge.net/] or aafigure [https://pythonhosted.org/
  5455. aafigure/]).
  5456. * FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS, to run additional tests for
  5457. the specified format <FMT> (see the list of rendered formats,
  5458. above).
  5459. Here is a complete example that uses all variables and all hooks:
  5460. 01: ################################################################################
  5461. 02: #
  5462. 03: # foo-document
  5463. 04: #
  5464. 05: ################################################################################
  5465. 06:
  5466. 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
  5467. 08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
  5468. 09:
  5469. 10: define FOO_GEN_EXTRA_DOC
  5470. 11: /path/to/generate-script --outdir=$(@D)
  5471. 12: endef
  5472. 13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
  5473. 14:
  5474. 15: define FOO_CHECK_MY_PROG
  5475. 16: if ! which my-prog >/dev/null 2>&1; then \
  5476. 17: echo "You need my-prog to generate the foo document"; \
  5477. 18: exit 1; \
  5478. 19: fi
  5479. 20: endef
  5480. 21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
  5481. 22:
  5482. 23: define FOO_CHECK_MY_OTHER_PROG
  5483. 24: if ! which my-other-prog >/dev/null 2>&1; then \
  5484. 25: echo "You need my-other-prog to generate the foo document as PDF"; \
  5485. 26: exit 1; \
  5486. 27: fi
  5487. 28: endef
  5488. 29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
  5489. 30:
  5490. 31: $(eval $(call asciidoc-document))
  5491. 18.21. Infrastructure specific to the Linux kernel package
  5492. The Linux kernel package can use some specific infrastructures based
  5493. on package hooks for building Linux kernel tools or/and building
  5494. Linux kernel extensions.
  5495. 18.21.1. linux-kernel-tools
  5496. Buildroot offers a helper infrastructure to build some userspace
  5497. tools for the target available within the Linux kernel sources. Since
  5498. their source code is part of the kernel source code, a special
  5499. package, linux-tools, exists and re-uses the sources of the Linux
  5500. kernel that runs on the target.
  5501. Let’s look at an example of a Linux tool. For a new Linux tool named
  5502. foo, create a new menu entry in the existing package/linux-tools/
  5503. Config.in. This file will contain the option descriptions related to
  5504. each kernel tool that will be used and displayed in the configuration
  5505. tool. It would basically look like:
  5506. 01: config BR2_PACKAGE_LINUX_TOOLS_FOO
  5507. 02: bool "foo"
  5508. 03: select BR2_PACKAGE_LINUX_TOOLS
  5509. 04: help
  5510. 05: This is a comment that explains what foo kernel tool is.
  5511. 06:
  5512. 07: http://foosoftware.org/foo/
  5513. The name of the option starts with the prefix
  5514. BR2_PACKAGE_LINUX_TOOLS_, followed by the uppercase name of the tool
  5515. (like is done for packages).
  5516. Note. Unlike other packages, the linux-tools package options appear
  5517. in the linux kernel menu, under the Linux Kernel Tools sub-menu, not
  5518. under the Target packages main menu.
  5519. Then for each linux tool, add a new .mk.in file named package/
  5520. linux-tools/linux-tool-foo.mk.in. It would basically look like:
  5521. 01: ################################################################################
  5522. 02: #
  5523. 03: # foo
  5524. 04: #
  5525. 05: ################################################################################
  5526. 06:
  5527. 07: LINUX_TOOLS += foo
  5528. 08:
  5529. 09: FOO_DEPENDENCIES = libbbb
  5530. 10:
  5531. 11: define FOO_BUILD_CMDS
  5532. 12: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools foo
  5533. 13: endef
  5534. 14:
  5535. 15: define FOO_INSTALL_STAGING_CMDS
  5536. 16: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
  5537. 17: DESTDIR=$(STAGING_DIR) \
  5538. 18: foo_install
  5539. 19: endef
  5540. 20:
  5541. 21: define FOO_INSTALL_TARGET_CMDS
  5542. 22: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
  5543. 23: DESTDIR=$(TARGET_DIR) \
  5544. 24: foo_install
  5545. 25: endef
  5546. On line 7, we register the Linux tool foo to the list of available
  5547. Linux tools.
  5548. On line 9, we specify the list of dependencies this tool relies on.
  5549. These dependencies are added to the Linux package dependencies list
  5550. only when the foo tool is selected.
  5551. The rest of the Makefile, lines 11-25 defines what should be done at
  5552. the different steps of the Linux tool build process like for a
  5553. generic package. They will actually be used only when the foo tool is
  5554. selected. The only supported commands are _BUILD_CMDS,
  5555. _INSTALL_STAGING_CMDS and _INSTALL_TARGET_CMDS.
  5556. Note. One must not call $(eval $(generic-package)) or any other
  5557. package infrastructure! Linux tools are not packages by themselves,
  5558. they are part of the linux-tools package.
  5559. 18.21.2. linux-kernel-extensions
  5560. Some packages provide new features that require the Linux kernel tree
  5561. to be modified. This can be in the form of patches to be applied on
  5562. the kernel tree, or in the form of new files to be added to the tree.
  5563. The Buildroot’s Linux kernel extensions infrastructure provides a
  5564. simple solution to automatically do this, just after the kernel
  5565. sources are extracted and before the kernel patches are applied.
  5566. Examples of extensions packaged using this mechanism are the
  5567. real-time extensions Xenomai and RTAI, as well as the set of
  5568. out-of-tree LCD screens drivers fbtft.
  5569. Let’s look at an example on how to add a new Linux extension foo.
  5570. First, create the package foo that provides the extension: this
  5571. package is a standard package; see the previous chapters on how to
  5572. create such a package. This package is in charge of downloading the
  5573. sources archive, checking the hash, defining the licence informations
  5574. and building user space tools if any.
  5575. Then create the Linux extension proper: create a new menu entry in
  5576. the existing linux/Config.ext.in. This file contains the option
  5577. descriptions related to each kernel extension that will be used and
  5578. displayed in the configuration tool. It would basically look like:
  5579. 01: config BR2_LINUX_KERNEL_EXT_FOO
  5580. 02: bool "foo"
  5581. 03: help
  5582. 04: This is a comment that explains what foo kernel extension is.
  5583. 05:
  5584. 06: http://foosoftware.org/foo/
  5585. Then for each linux extension, add a new .mk file named linux/
  5586. linux-ext-foo.mk. It should basically contain:
  5587. 01: ################################################################################
  5588. 02: #
  5589. 03: # foo
  5590. 04: #
  5591. 05: ################################################################################
  5592. 06:
  5593. 07: LINUX_EXTENSIONS += foo
  5594. 08:
  5595. 09: define FOO_PREPARE_KERNEL
  5596. 10: $(FOO_DIR)/prepare-kernel-tree.sh --linux-dir=$(@D)
  5597. 11: endef
  5598. On line 7, we add the Linux extension foo to the list of available
  5599. Linux extensions.
  5600. On line 9-11, we define what should be done by the extension to
  5601. modify the Linux kernel tree; this is specific to the linux extension
  5602. and can use the variables defined by the foo package, like: $
  5603. (FOO_DIR) or $(FOO_VERSION)… as well as all the Linux variables,
  5604. like: $(LINUX_VERSION) or $(LINUX_VERSION_PROBED), $(KERNEL_ARCH)…
  5605. See the definition of those kernel variables.
  5606. 18.22. Hooks available in the various build steps
  5607. The generic infrastructure (and as a result also the derived
  5608. autotools and cmake infrastructures) allow packages to specify hooks.
  5609. These define further actions to perform after existing steps. Most
  5610. hooks aren’t really useful for generic packages, since the .mk file
  5611. already has full control over the actions performed in each step of
  5612. the package construction.
  5613. The following hook points are available:
  5614. * LIBFOO_PRE_DOWNLOAD_HOOKS
  5615. * LIBFOO_POST_DOWNLOAD_HOOKS
  5616. * LIBFOO_PRE_EXTRACT_HOOKS
  5617. * LIBFOO_POST_EXTRACT_HOOKS
  5618. * LIBFOO_PRE_RSYNC_HOOKS
  5619. * LIBFOO_POST_RSYNC_HOOKS
  5620. * LIBFOO_PRE_PATCH_HOOKS
  5621. * LIBFOO_POST_PATCH_HOOKS
  5622. * LIBFOO_PRE_CONFIGURE_HOOKS
  5623. * LIBFOO_POST_CONFIGURE_HOOKS
  5624. * LIBFOO_PRE_BUILD_HOOKS
  5625. * LIBFOO_POST_BUILD_HOOKS
  5626. * LIBFOO_PRE_INSTALL_HOOKS (for host packages only)
  5627. * LIBFOO_POST_INSTALL_HOOKS (for host packages only)
  5628. * LIBFOO_PRE_INSTALL_STAGING_HOOKS (for target packages only)
  5629. * LIBFOO_POST_INSTALL_STAGING_HOOKS (for target packages only)
  5630. * LIBFOO_PRE_INSTALL_TARGET_HOOKS (for target packages only)
  5631. * LIBFOO_POST_INSTALL_TARGET_HOOKS (for target packages only)
  5632. * LIBFOO_PRE_INSTALL_IMAGES_HOOKS
  5633. * LIBFOO_POST_INSTALL_IMAGES_HOOKS
  5634. * LIBFOO_PRE_LEGAL_INFO_HOOKS
  5635. * LIBFOO_POST_LEGAL_INFO_HOOKS
  5636. These variables are lists of variable names containing actions to be
  5637. performed at this hook point. This allows several hooks to be
  5638. registered at a given hook point. Here is an example:
  5639. define LIBFOO_POST_PATCH_FIXUP
  5640. action1
  5641. action2
  5642. endef
  5643. LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
  5644. 18.22.1. Using the POST_RSYNC hook
  5645. The POST_RSYNC hook is run only for packages that use a local source,
  5646. either through the local site method or the OVERRIDE_SRCDIR
  5647. mechanism. In this case, package sources are copied using rsync from
  5648. the local location into the buildroot build directory. The rsync
  5649. command does not copy all files from the source directory, though.
  5650. Files belonging to a version control system, like the directories
  5651. .git, .hg, etc. are not copied. For most packages this is sufficient,
  5652. but a given package can perform additional actions using the
  5653. POST_RSYNC hook.
  5654. In principle, the hook can contain any command you want. One specific
  5655. use case, though, is the intentional copying of the version control
  5656. directory using rsync. The rsync command you use in the hook can,
  5657. among others, use the following variables:
  5658. * $(SRCDIR): the path to the overridden source directory
  5659. * $(@D): the path to the build directory
  5660. 18.22.2. Target-finalize hook
  5661. Packages may also register hooks in LIBFOO_TARGET_FINALIZE_HOOKS.
  5662. These hooks are run after all packages are built, but before the
  5663. filesystem images are generated. They are seldom used, and your
  5664. package probably do not need them.
  5665. 18.23. Gettext integration and interaction with packages
  5666. Many packages that support internationalization use the gettext
  5667. library. Dependencies for this library are fairly complicated and
  5668. therefore, deserve some explanation.
  5669. The glibc C library integrates a full-blown implementation of gettext
  5670. , supporting translation. Native Language Support is therefore
  5671. built-in in glibc.
  5672. On the other hand, the uClibc and musl C libraries only provide a
  5673. stub implementation of the gettext functionality, which allows to
  5674. compile libraries and programs using gettext functions, but without
  5675. providing the translation capabilities of a full-blown gettext
  5676. implementation. With such C libraries, if real Native Language
  5677. Support is necessary, it can be provided by the libintl library of
  5678. the gettext package.
  5679. Due to this, and in order to make sure that Native Language Support
  5680. is properly handled, packages in Buildroot that can use NLS support
  5681. should:
  5682. 1. Ensure NLS support is enabled when BR2_SYSTEM_ENABLE_NLS=y. This
  5683. is done automatically for autotools packages and therefore should
  5684. only be done for packages using other package infrastructures.
  5685. 2. Add $(TARGET_NLS_DEPENDENCIES) to the package <pkg>_DEPENDENCIES
  5686. variable. This addition should be done unconditionally: the value
  5687. of this variable is automatically adjusted by the core
  5688. infrastructure to contain the relevant list of packages. If NLS
  5689. support is disabled, this variable is empty. If NLS support is
  5690. enabled, this variable contains host-gettext so that tools needed
  5691. to compile translation files are available on the host. In
  5692. addition, if uClibc or musl are used, this variable also contains
  5693. gettext in order to get the full-blown gettext implementation.
  5694. 3. If needed, add $(TARGET_NLS_LIBS) to the linker flags, so that
  5695. the package gets linked with libintl. This is generally not
  5696. needed with autotools packages as they usually detect
  5697. automatically that they should link with libintl. However,
  5698. packages using other build systems, or problematic
  5699. autotools-based packages may need this. $(TARGET_NLS_LIBS) should
  5700. be added unconditionally to the linker flags, as the core
  5701. automatically makes it empty or defined to -lintl depending on
  5702. the configuration.
  5703. No changes should be made to the Config.in file to support NLS.
  5704. Finally, certain packages need some gettext utilities on the target,
  5705. such as the gettext program itself, which allows to retrieve
  5706. translated strings, from the command line. In such a case, the
  5707. package should:
  5708. * use select BR2_PACKAGE_GETTEXT in their Config.in file,
  5709. indicating in a comment above that it’s a runtime dependency
  5710. only.
  5711. * not add any gettext dependency in the DEPENDENCIES variable of
  5712. their .mk file.
  5713. 18.24. Tips and tricks
  5714. 18.24.1. Package name, config entry name and makefile variable
  5715. relationship
  5716. In Buildroot, there is some relationship between:
  5717. * the package name, which is the package directory name (and the
  5718. name of the *.mk file);
  5719. * the config entry name that is declared in the Config.in file;
  5720. * the makefile variable prefix.
  5721. It is mandatory to maintain consistency between these elements, using
  5722. the following rules:
  5723. * the package directory and the *.mk name are the package name
  5724. itself (e.g.: package/foo-bar_boo/foo-bar_boo.mk);
  5725. * the make target name is the package name itself (e.g.:
  5726. foo-bar_boo);
  5727. * the config entry is the upper case package name with . and -
  5728. characters substituted with _, prefixed with BR2_PACKAGE_ (e.g.:
  5729. BR2_PACKAGE_FOO_BAR_BOO);
  5730. * the *.mk file variable prefix is the upper case package name with
  5731. . and - characters substituted with _ (e.g.:
  5732. FOO_BAR_BOO_VERSION).
  5733. 18.24.2. How to check the coding style
  5734. Buildroot provides a script in utils/check-package that checks new or
  5735. changed files for coding style. It is not a complete language
  5736. validator, but it catches many common mistakes. It is meant to run in
  5737. the actual files you created or modified, before creating the patch
  5738. for submission.
  5739. This script can be used for packages, filesystem makefiles, Config.in
  5740. files, etc. It does not check the files defining the package
  5741. infrastructures and some other files containing similar common code.
  5742. To use it, run the check-package script, by telling which files you
  5743. created or changed:
  5744. $ ./utils/check-package package/new-package/*
  5745. If you have the utils directory in your path you can also run:
  5746. $ cd package/new-package/
  5747. $ check-package *
  5748. The tool can also be used for packages in a br2-external:
  5749. $ check-package -b /path/to/br2-ext-tree/package/my-package/*
  5750. 18.24.3. How to test your package
  5751. Once you have added your new package, it is important that you test
  5752. it under various conditions: does it build for all architectures?
  5753. Does it build with the different C libraries? Does it need threads,
  5754. NPTL? And so on…
  5755. Buildroot runs autobuilders [http://autobuild.buildroot.org/] which
  5756. continuously test random configurations. However, these only build
  5757. the master branch of the git tree, and your new fancy package is not
  5758. yet there.
  5759. Buildroot provides a script in utils/test-pkg that uses the same base
  5760. configurations as used by the autobuilders so you can test your
  5761. package in the same conditions.
  5762. First, create a config snippet that contains all the necessary
  5763. options needed to enable your package, but without any architecture
  5764. or toolchain option. For example, let’s create a config snippet that
  5765. just enables libcurl, without any TLS backend:
  5766. $ cat libcurl.config
  5767. BR2_PACKAGE_LIBCURL=y
  5768. If your package needs more configuration options, you can add them to
  5769. the config snippet. For example, here’s how you would test libcurl
  5770. with openssl as a TLS backend and the curl program:
  5771. $ cat libcurl.config
  5772. BR2_PACKAGE_LIBCURL=y
  5773. BR2_PACKAGE_LIBCURL_CURL=y
  5774. BR2_PACKAGE_OPENSSL=y
  5775. Then run the test-pkg script, by telling it what config snippet to
  5776. use and what package to test:
  5777. $ ./utils/test-pkg -c libcurl.config -p libcurl
  5778. By default, test-pkg will build your package against a subset of the
  5779. toolchains used by the autobuilders, which has been selected by the
  5780. Buildroot developers as being the most useful and representative
  5781. subset. If you want to test all toolchains, pass the -a option. Note
  5782. that in any case, internal toolchains are excluded as they take too
  5783. long to build.
  5784. The output lists all toolchains that are tested and the corresponding
  5785. result (excerpt, results are fake):
  5786. $ ./utils/test-pkg -c libcurl.config -p libcurl
  5787. armv5-ctng-linux-gnueabi [ 1/11]: OK
  5788. armv7-ctng-linux-gnueabihf [ 2/11]: OK
  5789. br-aarch64-glibc [ 3/11]: SKIPPED
  5790. br-arcle-hs38 [ 4/11]: SKIPPED
  5791. br-arm-basic [ 5/11]: FAILED
  5792. br-arm-cortex-a9-glibc [ 6/11]: OK
  5793. br-arm-cortex-a9-musl [ 7/11]: FAILED
  5794. br-arm-cortex-m4-full [ 8/11]: OK
  5795. br-arm-full [ 9/11]: OK
  5796. br-arm-full-nothread [10/11]: FAILED
  5797. br-arm-full-static [11/11]: OK
  5798. 11 builds, 2 skipped, 2 build failed, 1 legal-info failed
  5799. The results mean:
  5800. * OK: the build was successful.
  5801. * SKIPPED: one or more configuration options listed in the config
  5802. snippet were not present in the final configuration. This is due
  5803. to options having dependencies not satisfied by the toolchain,
  5804. such as for example a package that depends on BR2_USE_MMU with a
  5805. noMMU toolchain. The missing options are reported in
  5806. missing.config in the output build directory (~/br-test-pkg/
  5807. TOOLCHAIN_NAME/ by default).
  5808. * FAILED: the build failed. Inspect the logfile file in the output
  5809. build directory to see what went wrong:
  5810. + the actual build failed,
  5811. + the legal-info failed,
  5812. + one of the preliminary steps (downloading the config file,
  5813. applying the configuration, running dirclean for the package)
  5814. failed.
  5815. When there are failures, you can just re-run the script with the same
  5816. options (after you fixed your package); the script will attempt to
  5817. re-build the package specified with -p for all toolchains, without
  5818. the need to re-build all the dependencies of that package.
  5819. The test-pkg script accepts a few options, for which you can get some
  5820. help by running:
  5821. $ ./utils/test-pkg -h
  5822. 18.24.4. How to add a package from GitHub
  5823. Packages on GitHub often don’t have a download area with release
  5824. tarballs. However, it is possible to download tarballs directly from
  5825. the repository on GitHub. As GitHub is known to have changed download
  5826. mechanisms in the past, the github helper function should be used as
  5827. shown below.
  5828. # Use a tag or a full commit ID
  5829. FOO_VERSION = v1.0
  5830. FOO_SITE = $(call github,<user>,<package>,$(FOO_VERSION))
  5831. Notes
  5832. * The FOO_VERSION can either be a tag or a commit ID.
  5833. * The tarball name generated by github matches the default one from
  5834. Buildroot (e.g.:
  5835. foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz), so it is
  5836. not necessary to specify it in the .mk file.
  5837. * When using a commit ID as version, you should use the full 40 hex
  5838. characters.
  5839. If the package you wish to add does have a release section on GitHub,
  5840. the maintainer may have uploaded a release tarball, or the release
  5841. may just point to the automatically generated tarball from the git
  5842. tag. If there is a release tarball uploaded by the maintainer, we
  5843. prefer to use that since it may be slightly different (e.g. it
  5844. contains a configure script so we don’t need to do AUTORECONF).
  5845. You can see on the release page if it’s an uploaded tarball or a git
  5846. tag:
  5847. * If it looks like the image above then it was uploaded by the
  5848. maintainer and you should use that link (in that example:
  5849. mongrel2-v1.9.2.tar.bz2) to specify FOO_SITE, and not use the
  5850. github helper.
  5851. * On the other hand, if there’s is only the "Source code" link,
  5852. then it’s an automatically generated tarball and you should use
  5853. the github helper function.
  5854. 18.25. Conclusion
  5855. As you can see, adding a software package to Buildroot is simply a
  5856. matter of writing a Makefile using an existing example and modifying
  5857. it according to the compilation process required by the package.
  5858. If you package software that might be useful for other people, don’t
  5859. forget to send a patch to the Buildroot mailing list (see
  5860. Section 22.5, “Submitting patches”)!
  5861. Chapter 19. Patching a package
  5862. While integrating a new package or updating an existing one, it may
  5863. be necessary to patch the source of the software to get it
  5864. cross-built within Buildroot.
  5865. Buildroot offers an infrastructure to automatically handle this
  5866. during the builds. It supports three ways of applying patch sets:
  5867. downloaded patches, patches supplied within buildroot and patches
  5868. located in a user-defined global patch directory.
  5869. 19.1. Providing patches
  5870. 19.1.1. Downloaded
  5871. If it is necessary to apply a patch that is available for download,
  5872. then add it to the <packagename>_PATCH variable. If an entry contains
  5873. ://, then Buildroot will assume it is a full URL and download the
  5874. patch from this location. Otherwise, Buildroot will assume that the
  5875. patch should be downloaded from <packagename>_SITE. It can be a
  5876. single patch, or a tarball containing a patch series.
  5877. Like for all downloads, a hash should be added to the
  5878. <packagename>.hash file.
  5879. This method is typically used for packages from Debian.
  5880. 19.1.2. Within Buildroot
  5881. Most patches are provided within Buildroot, in the package directory;
  5882. these typically aim to fix cross-compilation, libc support, or other
  5883. such issues.
  5884. These patch files should be named <number>-<description>.patch.
  5885. Notes
  5886. * The patch files coming with Buildroot should not contain any
  5887. package version reference in their filename.
  5888. * The field <number> in the patch file name refers to the apply
  5889. order, and shall start at 1; It is preferred to pad the number
  5890. with zeros up to 4 digits, like git-format-patch does. E.g.:
  5891. 0001-foobar-the-buz.patch
  5892. * Previously, it was mandatory for patches to be prefixed with the
  5893. name of the package, like <package>-<number>-<description>.patch,
  5894. but that is no longer the case. Existing packages will be fixed
  5895. as time passes. Do not prefix patches with the package name.
  5896. * Previously, a series file, as used by quilt, could also be added
  5897. in the package directory. In that case, the series file defines
  5898. the patch application order. This is deprecated, and will be
  5899. removed in the future. Do not use a series file.
  5900. 19.1.3. Global patch directory
  5901. The BR2_GLOBAL_PATCH_DIR configuration file option can be used to
  5902. specify a space separated list of one or more directories containing
  5903. global package patches. See Section 9.8, “Adding project-specific
  5904. patches” for details.
  5905. 19.2. How patches are applied
  5906. 1. Run the <packagename>_PRE_PATCH_HOOKS commands if defined;
  5907. 2. Cleanup the build directory, removing any existing *.rej files;
  5908. 3. If <packagename>_PATCH is defined, then patches from these
  5909. tarballs are applied;
  5910. 4. If there are some *.patch files in the package’s Buildroot
  5911. directory or in a package subdirectory named <packageversion>,
  5912. then:
  5913. + If a series file exists in the package directory, then
  5914. patches are applied according to the series file;
  5915. + Otherwise, patch files matching *.patch are applied in
  5916. alphabetical order. So, to ensure they are applied in the
  5917. right order, it is highly recommended to name the patch files
  5918. like this: <number>-<description>.patch, where <number>
  5919. refers to the apply order.
  5920. 5. If BR2_GLOBAL_PATCH_DIR is defined, the directories will be
  5921. enumerated in the order they are specified. The patches are
  5922. applied as described in the previous step.
  5923. 6. Run the <packagename>_POST_PATCH_HOOKS commands if defined.
  5924. If something goes wrong in the steps 3 or 4, then the build fails.
  5925. 19.3. Format and licensing of the package patches
  5926. Patches are released under the same license as the software they
  5927. apply to (see Section 13.2, “Complying with the Buildroot license”).
  5928. A message explaining what the patch does, and why it is needed,
  5929. should be added in the header commentary of the patch.
  5930. You should add a Signed-off-by statement in the header of the each
  5931. patch to help with keeping track of the changes and to certify that
  5932. the patch is released under the same license as the software that is
  5933. modified.
  5934. If the software is under version control, it is recommended to use
  5935. the upstream SCM software to generate the patch set.
  5936. Otherwise, concatenate the header with the output of the diff -purN
  5937. package-version.orig/ package-version/ command.
  5938. If you update an existing patch (e.g. when bumping the package
  5939. version), make sure the existing From header and Signed-off-by tags
  5940. are not removed, but do update the rest of the patch comment when
  5941. appropriate.
  5942. At the end, the patch should look like:
  5943. configure.ac: add C++ support test
  5944. Signed-off-by: John Doe <john.doe@noname.org>
  5945. --- configure.ac.orig
  5946. +++ configure.ac
  5947. @@ -40,2 +40,12 @@
  5948. AC_PROG_MAKE_SET
  5949. +
  5950. +AC_CACHE_CHECK([whether the C++ compiler works],
  5951. + [rw_cv_prog_cxx_works],
  5952. + [AC_LANG_PUSH([C++])
  5953. + AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
  5954. + [rw_cv_prog_cxx_works=yes],
  5955. + [rw_cv_prog_cxx_works=no])
  5956. + AC_LANG_POP([C++])])
  5957. +
  5958. +AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
  5959. 19.4. Integrating patches found on the Web
  5960. When integrating a patch of which you are not the author, you have to
  5961. add a few things in the header of the patch itself.
  5962. Depending on whether the patch has been obtained from the project
  5963. repository itself, or from somewhere on the web, add one of the
  5964. following tags:
  5965. Backported from: <some commit id>
  5966. or
  5967. Fetch from: <some url>
  5968. It is also sensible to add a few words about any changes to the patch
  5969. that may have been necessary.
  5970. Chapter 20. Download infrastructure
  5971. TODO
  5972. Chapter 21. Debugging Buildroot
  5973. It is possible to instrument the steps Buildroot does when building
  5974. packages. Define the variable BR2_INSTRUMENTATION_SCRIPTS to contain
  5975. the path of one or more scripts (or other executables), in a
  5976. space-separated list, you want called before and after each step. The
  5977. scripts are called in sequence, with three parameters:
  5978. * start or end to denote the start (resp. the end) of a step;
  5979. * the name of the step about to be started, or which just ended;
  5980. * the name of the package.
  5981. For example :
  5982. make BR2_INSTRUMENTATION_SCRIPTS="/path/to/my/script1 /path/to/my/script2"
  5983. The list of steps is:
  5984. * extract
  5985. * patch
  5986. * configure
  5987. * build
  5988. * install-host, when a host-package is installed in $(HOST_DIR)
  5989. * install-target, when a target-package is installed in $
  5990. (TARGET_DIR)
  5991. * install-staging, when a target-package is installed in $
  5992. (STAGING_DIR)
  5993. * install-image, when a target-package installs files in $
  5994. (BINARIES_DIR)
  5995. The script has access to the following variables:
  5996. * BR2_CONFIG: the path to the Buildroot .config file
  5997. * HOST_DIR, STAGING_DIR, TARGET_DIR: see Section 18.5.2,
  5998. “generic-package reference”
  5999. * BUILD_DIR: the directory where packages are extracted and built
  6000. * BINARIES_DIR: the place where all binary files (aka images) are
  6001. stored
  6002. * BASE_DIR: the base output directory
  6003. Chapter 22. Contributing to Buildroot
  6004. There are many ways in which you can contribute to Buildroot:
  6005. analyzing and fixing bugs, analyzing and fixing package build
  6006. failures detected by the autobuilders, testing and reviewing patches
  6007. sent by other developers, working on the items in our TODO list and
  6008. sending your own improvements to Buildroot or its manual. The
  6009. following sections give a little more detail on each of these items.
  6010. If you are interested in contributing to Buildroot, the first thing
  6011. you should do is to subscribe to the Buildroot mailing list. This
  6012. list is the main way of interacting with other Buildroot developers
  6013. and to send contributions to. If you aren’t subscribed yet, then
  6014. refer to Chapter 5, Community resources for the subscription link.
  6015. If you are going to touch the code, it is highly recommended to use a
  6016. git repository of Buildroot, rather than starting from an extracted
  6017. source code tarball. Git is the easiest way to develop from and
  6018. directly send your patches to the mailing list. Refer to Chapter 3,
  6019. Getting Buildroot for more information on obtaining a Buildroot git
  6020. tree.
  6021. 22.1. Reproducing, analyzing and fixing bugs
  6022. A first way of contributing is to have a look at the open bug reports
  6023. in the Buildroot bug tracker [https://bugs.buildroot.org/buglist.cgi?
  6024. product=buildroot]. As we strive to keep the bug count as small as
  6025. possible, all help in reproducing, analyzing and fixing reported bugs
  6026. is more than welcome. Don’t hesitate to add a comment to bug reports
  6027. reporting your findings, even if you don’t yet see the full picture.
  6028. 22.2. Analyzing and fixing autobuild failures
  6029. The Buildroot autobuilders are a set of build machines that
  6030. continuously run Buildroot builds based on random configurations.
  6031. This is done for all architectures supported by Buildroot, with
  6032. various toolchains, and with a random selection of packages. With the
  6033. large commit activity on Buildroot, these autobuilders are a great
  6034. help in detecting problems very early after commit.
  6035. All build results are available at http://autobuild.buildroot.org,
  6036. statistics are at http://autobuild.buildroot.org/stats.php. Every
  6037. day, an overview of all failed packages is sent to the mailing list.
  6038. Detecting problems is great, but obviously these problems have to be
  6039. fixed as well. Your contribution is very welcome here! There are
  6040. basically two things that can be done:
  6041. * Analyzing the problems. The daily summary mails do not contain
  6042. details about the actual failures: in order to see what’s going
  6043. on you have to open the build log and check the last output.
  6044. Having someone doing this for all packages in the mail is very
  6045. useful for other developers, as they can make a quick initial
  6046. analysis based on this output alone.
  6047. * Fixing a problem. When fixing autobuild failures, you should
  6048. follow these steps:
  6049. 1. Check if you can reproduce the problem by building with the
  6050. same configuration. You can do this manually, or use the
  6051. br-reproduce-build [http://git.buildroot.org/buildroot-test/
  6052. tree/utils/br-reproduce-build] script that will automatically
  6053. clone a Buildroot git repository, checkout the correct
  6054. revision, download and set the right configuration, and start
  6055. the build.
  6056. 2. Analyze the problem and create a fix.
  6057. 3. Verify that the problem is really fixed by starting from a
  6058. clean Buildroot tree and only applying your fix.
  6059. 4. Send the fix to the Buildroot mailing list (see Section 22.5,
  6060. “Submitting patches”). In case you created a patch against
  6061. the package sources, you should also send the patch upstream
  6062. so that the problem will be fixed in a later release, and the
  6063. patch in Buildroot can be removed. In the commit message of a
  6064. patch fixing an autobuild failure, add a reference to the
  6065. build result directory, as follows:
  6066. Fixes: http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
  6067. 22.3. Reviewing and testing patches
  6068. With the amount of patches sent to the mailing list each day, the
  6069. maintainer has a very hard job to judge which patches are ready to
  6070. apply and which ones aren’t. Contributors can greatly help here by
  6071. reviewing and testing these patches.
  6072. In the review process, do not hesitate to respond to patch
  6073. submissions for remarks, suggestions or anything that will help
  6074. everyone to understand the patches and make them better. Please use
  6075. internet style replies in plain text emails when responding to patch
  6076. submissions.
  6077. To indicate approval of a patch, there are three formal tags that
  6078. keep track of this approval. To add your tag to a patch, reply to it
  6079. with the approval tag below the original author’s Signed-off-by line.
  6080. These tags will be picked up automatically by patchwork (see
  6081. Section 22.3.1, “Applying Patches from Patchwork”) and will be part
  6082. of the commit log when the patch is accepted.
  6083. Tested-by
  6084. Indicates that the patch has been tested successfully. You are
  6085. encouraged to specify what kind of testing you performed
  6086. (compile-test on architecture X and Y, runtime test on target A,
  6087. …). This additional information helps other testers and the
  6088. maintainer.
  6089. Reviewed-by
  6090. Indicates that you code-reviewed the patch and did your best in
  6091. spotting problems, but you are not sufficiently familiar with the
  6092. area touched to provide an Acked-by tag. This means that there
  6093. may be remaining problems in the patch that would be spotted by
  6094. someone with more experience in that area. Should such problems
  6095. be detected, your Reviewed-by tag remains appropriate and you
  6096. cannot be blamed.
  6097. Acked-by
  6098. Indicates that you code-reviewed the patch and you are familiar
  6099. enough with the area touched to feel that the patch can be
  6100. committed as-is (no additional changes required). In case it
  6101. later turns out that something is wrong with the patch, your
  6102. Acked-by could be considered inappropriate. The difference
  6103. between Acked-by and Reviewed-by is thus mainly that you are
  6104. prepared to take the blame on Acked patches, but not on Reviewed
  6105. ones.
  6106. If you reviewed a patch and have comments on it, you should simply
  6107. reply to the patch stating these comments, without providing a
  6108. Reviewed-by or Acked-by tag. These tags should only be provided if
  6109. you judge the patch to be good as it is.
  6110. It is important to note that neither Reviewed-by nor Acked-by imply
  6111. that testing has been performed. To indicate that you both reviewed
  6112. and tested the patch, provide two separate tags (Reviewed/Acked-by
  6113. and Tested-by).
  6114. Note also that any developer can provide Tested/Reviewed/Acked-by
  6115. tags, without exception, and we encourage everyone to do this.
  6116. Buildroot does not have a defined group of core developers, it just
  6117. so happens that some developers are more active than others. The
  6118. maintainer will value tags according to the track record of their
  6119. submitter. Tags provided by a regular contributor will naturally be
  6120. trusted more than tags provided by a newcomer. As you provide tags
  6121. more regularly, your trustworthiness (in the eyes of the maintainer)
  6122. will go up, but any tag provided is valuable.
  6123. Buildroot’s Patchwork website can be used to pull in patches for
  6124. testing purposes. Please see Section 22.3.1, “Applying Patches from
  6125. Patchwork” for more information on using Buildroot’s Patchwork
  6126. website to apply patches.
  6127. 22.3.1. Applying Patches from Patchwork
  6128. The main use of Buildroot’s Patchwork website for a developer is for
  6129. pulling in patches into their local git repository for testing
  6130. purposes.
  6131. When browsing patches in the patchwork management interface, an mbox
  6132. link is provided at the top of the page. Copy this link address and
  6133. run the following commands:
  6134. $ git checkout -b <test-branch-name>
  6135. $ wget -O - <mbox-url> | git am
  6136. Another option for applying patches is to create a bundle. A bundle
  6137. is a set of patches that you can group together using the patchwork
  6138. interface. Once the bundle is created and the bundle is made public,
  6139. you can copy the mbox link for the bundle and apply the bundle using
  6140. the above commands.
  6141. 22.4. Work on items from the TODO list
  6142. If you want to contribute to Buildroot but don’t know where to start,
  6143. and you don’t like any of the above topics, you can always work on
  6144. items from the Buildroot TODO list [http://elinux.org/Buildroot#
  6145. Todo_list]. Don’t hesitate to discuss an item first on the mailing
  6146. list or on IRC. Do edit the wiki to indicate when you start working
  6147. on an item, so we avoid duplicate efforts.
  6148. 22.5. Submitting patches
  6149. Note
  6150. Please, do not attach patches to bugs, send them to the mailing list
  6151. instead.
  6152. If you made some changes to Buildroot and you would like to
  6153. contribute them to the Buildroot project, proceed as follows.
  6154. 22.5.1. The formatting of a patch
  6155. We expect patches to be formatted in a specific way. This is
  6156. necessary to make it easy to review patches, to be able to apply them
  6157. easily to the git repository, to make it easy to find back in the
  6158. history how and why things have changed, and to make it possible to
  6159. use git bisect to locate the origin of a problem.
  6160. First of all, it is essential that the patch has a good commit
  6161. message. The commit message should start with a separate line with a
  6162. brief summary of the change, prefixed by the area touched by the
  6163. patch. A few examples of good commit titles:
  6164. * package/linuxptp: bump version to 2.0
  6165. * configs/imx23evk: bump Linux version to 4.19
  6166. * package/pkg-generic: postpone evaluation of dependency conditions
  6167. * boot/uboot: needs host-{flex,bison}
  6168. * support/testing: add python-ubjson tests
  6169. The description that follows the prefix should start with a lower
  6170. case letter (i.e "bump", "needs", "postpone", "add" in the above
  6171. examples).
  6172. Second, the body of the commit message should describe why this
  6173. change is needed, and if necessary also give details about how it was
  6174. done. When writing the commit message, think of how the reviewers
  6175. will read it, but also think about how you will read it when you look
  6176. at this change again a few years down the line.
  6177. Third, the patch itself should do only one change, but do it
  6178. completely. Two unrelated or weakly related changes should usually be
  6179. done in two separate patches. This usually means that a patch affects
  6180. only a single package. If several changes are related, it is often
  6181. still possible to split them up in small patches and apply them in a
  6182. specific order. Small patches make it easier to review, and often
  6183. make it easier to understand afterwards why a change was done.
  6184. However, each patch must be complete. It is not allowed that the
  6185. build is broken when only the first but not the second patch is
  6186. applied. This is necessary to be able to use git bisect afterwards.
  6187. Of course, while you’re doing your development, you’re probably going
  6188. back and forth between packages, and certainly not committing things
  6189. immediately in a way that is clean enough for submission. So most
  6190. developers rewrite the history of commits to produce a clean set of
  6191. commits that is appropriate for submission. To do this, you need to
  6192. use interactive rebasing. You can learn about it in the Pro Git book
  6193. [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History].
  6194. Sometimes, it is even easier to discard you history with git reset
  6195. --soft origin/master and select individual changes with git add -i or
  6196. git add -p.
  6197. Finally, the patch should be signed off. This is done by adding
  6198. Signed-off-by: Your Real Name <> at the end of the commit message.
  6199. git commit -s does that for you, if configured properly. The
  6200. Signed-off-by tag means that you publish the patch under the
  6201. Buildroot license (i.e. GPL-2.0+, except for package patches, which
  6202. have the upstream license), and that you are allowed to do so. See
  6203. the Developer Certificate of Origin [http://developercertificate.org
  6204. /] for details.
  6205. When adding new packages, you should submit every package in a
  6206. separate patch. This patch should have the update to package/
  6207. Config.in, the package Config.in file, the .mk file, the .hash file,
  6208. any init script, and all package patches. If the package has many
  6209. sub-options, these are sometimes better added as separate follow-up
  6210. patches. The summary line should be something like <packagename>: new
  6211. package. The body of the commit message can be empty for simple
  6212. packages, or it can contain the description of the package (like the
  6213. Config.in help text). If anything special has to be done to build the
  6214. package, this should also be explained explicitly in the commit
  6215. message body.
  6216. When you bump a package to a new version, you should also submit a
  6217. separate patch for each package. Don’t forget to update the .hash
  6218. file, or add it if it doesn’t exist yet. Also don’t forget to check
  6219. if the _LICENSE and _LICENSE_FILES are still valid. The summary line
  6220. should be something like <packagename>: bump to version <new
  6221. version>. If the new version only contains security updates compared
  6222. to the existing one, the summary should be <packagename>: security
  6223. bump to version <new version> and the commit message body should show
  6224. the CVE numbers that are fixed. If some package patches can be
  6225. removed in the new version, it should be explained explicitly why
  6226. they can be removed, preferably with the upstream commit ID. Also any
  6227. other required changes should be explained explicitly, like configure
  6228. options that no longer exist or are no longer needed.
  6229. If you are interested in getting notified of build failures and of
  6230. further changes in the packages you added or modified, please add
  6231. yourself to the DEVELOPERS file. This should be done in the same
  6232. patch creating or modifying the package. See the DEVELOPERS file for
  6233. more information.
  6234. Buildroot provides a handy tool to check for common coding style
  6235. mistakes on files you created or modified, called check-package (see
  6236. Section 18.24.2, “How to check the coding style” for more
  6237. information).
  6238. 22.5.2. Preparing a patch series
  6239. Starting from the changes committed in your local git view, rebase
  6240. your development branch on top of the upstream tree before generating
  6241. a patch set. To do so, run:
  6242. $ git fetch --all --tags
  6243. $ git rebase origin/master
  6244. Now, you are ready to generate then submit your patch set.
  6245. To generate it, run:
  6246. $ git format-patch -M -n -s -o outgoing origin/master
  6247. This will generate patch files in the outgoing subdirectory,
  6248. automatically adding the Signed-off-by line.
  6249. Once patch files are generated, you can review/edit the commit
  6250. message before submitting them, using your favorite text editor.
  6251. Buildroot provides a handy tool to know to whom your patches should
  6252. be sent, called get-developers (see Chapter 23, DEVELOPERS file and
  6253. get-developers for more information). This tool reads your patches
  6254. and outputs the appropriate git send-email command to use:
  6255. $ ./utils/get-developers outgoing/*
  6256. Use the output of get-developers to send your patches:
  6257. $ git send-email --to buildroot@buildroot.org --cc bob --cc alice outgoing/*
  6258. Alternatively, get-developers -e can be used directly with the
  6259. --cc-cmd argument to git send-email to automatically CC the affected
  6260. developers:
  6261. $ git send-email --to buildroot@buildroot.org \
  6262. --cc-cmd './utils/get-developers -e' origin/master
  6263. git can be configured to automatically do this out of the box with:
  6264. $ git config sendemail.to buildroot@buildroot.org
  6265. $ git config sendemail.ccCmd "$(pwd)/utils/get-developers -e"
  6266. And then just do:
  6267. $ git send-email origin/master
  6268. Note that git should be configured to use your mail account. To
  6269. configure git, see man git-send-email or google it.
  6270. If you do not use git send-email, make sure posted patches are not
  6271. line-wrapped, otherwise they cannot easily be applied. In such a
  6272. case, fix your e-mail client, or better yet, learn to use git
  6273. send-email.
  6274. 22.5.3. Cover letter
  6275. If you want to present the whole patch set in a separate mail, add
  6276. --cover-letter to the git format-patch command (see man
  6277. git-format-patch for further information). This will generate a
  6278. template for an introduction e-mail to your patch series.
  6279. A cover letter may be useful to introduce the changes you propose in
  6280. the following cases:
  6281. * large number of commits in the series;
  6282. * deep impact of the changes in the rest of the project;
  6283. * RFC ^[4];
  6284. * whenever you feel it will help presenting your work, your
  6285. choices, the review process, etc.
  6286. 22.5.4. Patches for maintenance branches
  6287. When fixing bugs on a maintenance branch, bugs should be fixed on the
  6288. master branch first. The commit log for such a patch may then contain
  6289. a post-commit note specifying what branches are affected:
  6290. package/foo: fix stuff
  6291. Signed-off-by: Your Real Name <your@email.address>
  6292. ---
  6293. Backport to: 2020.02.x, 2020.05.x
  6294. (2020.08.x not affected as the version was bumped)
  6295. Those changes will then be backported by a maintainer to the affected
  6296. branches.
  6297. However, some bugs may apply only to a specific release, for example
  6298. because it is using an older version of a package. In that case,
  6299. patches should be based off the maintenance branch, and the patch
  6300. subject prefix must include the maintenance branch name (for example
  6301. "[PATCH 2020.02.x]"). This can be done with the git format-patch flag
  6302. --subject-prefix:
  6303. $ git format-patch --subject-prefix "PATCH 2020.02.x" \
  6304. -M -s -o outgoing origin/2020.02.x
  6305. Then send the patches with git send-email, as described above.
  6306. 22.5.5. Patch revision changelog
  6307. When improvements are requested, the new revision of each commit
  6308. should include a changelog of the modifications between each
  6309. submission. Note that when your patch series is introduced by a cover
  6310. letter, an overall changelog may be added to the cover letter in
  6311. addition to the changelog in the individual commits. The best thing
  6312. to rework a patch series is by interactive rebasing: git rebase -i
  6313. origin/master. Consult the git manual for more information.
  6314. When added to the individual commits, this changelog is added when
  6315. editing the commit message. Below the Signed-off-by section, add ---
  6316. and your changelog.
  6317. Although the changelog will be visible for the reviewers in the mail
  6318. thread, as well as in patchwork [http://patchwork.buildroot.org], git
  6319. will automatically ignores lines below --- when the patch will be
  6320. merged. This is the intended behavior: the changelog is not meant to
  6321. be preserved forever in the git history of the project.
  6322. Hereafter the recommended layout:
  6323. Patch title: short explanation, max 72 chars
  6324. A paragraph that explains the problem, and how it manifests itself. If
  6325. the problem is complex, it is OK to add more paragraphs. All paragraphs
  6326. should be wrapped at 72 characters.
  6327. A paragraph that explains the root cause of the problem. Again, more
  6328. than one paragraph is OK.
  6329. Finally, one or more paragraphs that explain how the problem is solved.
  6330. Don't hesitate to explain complex solutions in detail.
  6331. Signed-off-by: John DOE <john.doe@example.net>
  6332. ---
  6333. Changes v2 -> v3:
  6334. - foo bar (suggested by Jane)
  6335. - bar buz
  6336. Changes v1 -> v2:
  6337. - alpha bravo (suggested by John)
  6338. - charly delta
  6339. Any patch revision should include the version number. The version
  6340. number is simply composed of the letter v followed by an integer
  6341. greater or equal to two (i.e. "PATCH v2", "PATCH v3" …).
  6342. This can be easily handled with git format-patch by using the option
  6343. --subject-prefix:
  6344. $ git format-patch --subject-prefix "PATCH v4" \
  6345. -M -s -o outgoing origin/master
  6346. Since git version 1.8.1, you can also use -v <n> (where <n> is the
  6347. version number):
  6348. $ git format-patch -v4 -M -s -o outgoing origin/master
  6349. When you provide a new version of a patch, please mark the old one as
  6350. superseded in patchwork [http://patchwork.buildroot.org]. You need to
  6351. create an account on patchwork [http://patchwork.buildroot.org] to be
  6352. able to modify the status of your patches. Note that you can only
  6353. change the status of patches you submitted yourself, which means the
  6354. email address you register in patchwork [http://
  6355. patchwork.buildroot.org] should match the one you use for sending
  6356. patches to the mailing list.
  6357. You can also add the --in-reply-to <message-id> option when
  6358. submitting a patch to the mailing list. The id of the mail to reply
  6359. to can be found under the "Message Id" tag on patchwork [http://
  6360. patchwork.buildroot.org]. The advantage of in-reply-to is that
  6361. patchwork will automatically mark the previous version of the patch
  6362. as superseded.
  6363. 22.6. Reporting issues/bugs or getting help
  6364. Before reporting any issue, please check in the mailing list archive
  6365. whether someone has already reported and/or fixed a similar problem.
  6366. However you choose to report bugs or get help, either by opening a
  6367. bug in the bug tracker or by sending a mail to the mailing list,
  6368. there are a number of details to provide in order to help people
  6369. reproduce and find a solution to the issue.
  6370. Try to think as if you were trying to help someone else; in that
  6371. case, what would you need?
  6372. Here is a short list of details to provide in such case:
  6373. * host machine (OS/release)
  6374. * version of Buildroot
  6375. * target for which the build fails
  6376. * package(s) for which the build fails
  6377. * the command that fails and its output
  6378. * any information you think that may be relevant
  6379. Additionally, you should add the .config file (or if you know how, a
  6380. defconfig; see Section 9.3, “Storing the Buildroot configuration”).
  6381. If some of these details are too large, do not hesitate to use a
  6382. pastebin service. Note that not all available pastebin services will
  6383. preserve Unix-style line terminators when downloading raw pastes.
  6384. Following pastebin services are known to work correctly: - https://
  6385. gist.github.com/ - http://code.bulix.org/
  6386. 22.7. Using the run-tests framework
  6387. Buildroot includes a run-time testing framework called run-tests
  6388. built upon Python scripting and QEMU runtime execution. There are two
  6389. types of test cases within the framework, one for build time tests
  6390. and another for run-time tests that have a QEMU dependency. The goals
  6391. of the framework are the following:
  6392. * build a well defined configuration
  6393. * optionally, verify some properties of the build output
  6394. * if it is a run-time test:
  6395. + boot it under QEMU
  6396. + run some test condition to verify that a given feature is
  6397. working
  6398. The run-tests tool has a series of options documented in the tool’s
  6399. help -h description. Some common options include setting the download
  6400. folder, the output folder, keeping build output, and for multiple
  6401. test cases, you can set the JLEVEL for each.
  6402. Here is an example walk through of running a test case.
  6403. * For a first step, let us see what all the test case options are.
  6404. The test cases can be listed by executing support/testing/
  6405. run-tests -l. These tests can all be run individually during test
  6406. development from the console. Both one at a time and selectively
  6407. as a group of a subset of tests.
  6408. $ support/testing/run-tests -l
  6409. List of tests
  6410. test_run (tests.utils.test_check_package.TestCheckPackage)
  6411. Test the various ways the script can be called in a simple top to ... ok
  6412. test_run (tests.toolchain.test_external.TestExternalToolchainBuildrootMusl) ... ok
  6413. test_run (tests.toolchain.test_external.TestExternalToolchainBuildrootuClibc) ... ok
  6414. test_run (tests.toolchain.test_external.TestExternalToolchainCCache) ... ok
  6415. test_run (tests.toolchain.test_external.TestExternalToolchainCtngMusl) ... ok
  6416. test_run (tests.toolchain.test_external.TestExternalToolchainLinaroArm) ... ok
  6417. test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv4) ... ok
  6418. test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv5) ... ok
  6419. test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv7) ... ok
  6420. [snip]
  6421. test_run (tests.init.test_systemd.TestInitSystemSystemdRoFull) ... ok
  6422. test_run (tests.init.test_systemd.TestInitSystemSystemdRoIfupdown) ... ok
  6423. test_run (tests.init.test_systemd.TestInitSystemSystemdRoNetworkd) ... ok
  6424. test_run (tests.init.test_systemd.TestInitSystemSystemdRwFull) ... ok
  6425. test_run (tests.init.test_systemd.TestInitSystemSystemdRwIfupdown) ... ok
  6426. test_run (tests.init.test_systemd.TestInitSystemSystemdRwNetworkd) ... ok
  6427. test_run (tests.init.test_busybox.TestInitSystemBusyboxRo) ... ok
  6428. test_run (tests.init.test_busybox.TestInitSystemBusyboxRoNet) ... ok
  6429. test_run (tests.init.test_busybox.TestInitSystemBusyboxRw) ... ok
  6430. test_run (tests.init.test_busybox.TestInitSystemBusyboxRwNet) ... ok
  6431. Ran 157 tests in 0.021s
  6432. OK
  6433. Those runtime tests are regularly executed by Buildroot Gitlab CI
  6434. infrastructure, see .gitlab.yml and https://gitlab.com/buildroot.org/
  6435. buildroot/-/jobs.
  6436. 22.7.1. Creating a test case
  6437. The best way to get familiar with how to create a test case is to
  6438. look at a few of the basic file system support/testing/tests/fs/ and
  6439. init support/testing/tests/init/ test scripts. Those tests give good
  6440. examples of a basic build and build with run type of tests. There are
  6441. other more advanced cases that use things like nested br2-external
  6442. folders to provide skeletons and additional packages.
  6443. The test cases by default use a br-arm-full-* uClibc-ng toolchain and
  6444. the prebuild kernel for a armv5/7 cpu. It is recommended to use the
  6445. default defconfig test configuration except when Glibc/musl or a
  6446. newer kernel are necessary. By using the default it saves build time
  6447. and the test would automatically inherit a kernel/std library upgrade
  6448. when the default is updated.
  6449. The basic test case definition involves
  6450. * Creation of a new test file
  6451. * Defining a unique test class
  6452. * Determining if the default defconfig plus test options can be
  6453. used
  6454. * Implementing a def test_run(self): function to optionally startup
  6455. the emulator and provide test case conditions.
  6456. After creating the test script, add yourself to the DEVELOPERS file
  6457. to be the maintainer of that test case.
  6458. 22.7.2. Debugging a test case
  6459. Within the Buildroot repository, the testing framework is organized
  6460. at the top level in support/testing/ by folders of conf, infra and
  6461. tests. All the test cases live under the test folder and are
  6462. organized in various folders representing the catagory of test.
  6463. Lets walk through an example.
  6464. * Using the Busybox Init system test case with a read/write rootfs
  6465. tests.init.test_busybox.TestInitSystemBusyboxRw
  6466. * A minimal set of command line arguments when debugging a test
  6467. case would include -d which points to your dl folder, -o to an
  6468. output folder, and -k to keep any output on both pass/fail. With
  6469. those options, the test will retain logging and build artifacts
  6470. providing status of the build and execution of the test case.
  6471. $ support/testing/run-tests -d dl -o output_folder -k tests.init.test_busybox.TestInitSystemBusyboxRw
  6472. 15:03:26 TestInitSystemBusyboxRw Starting
  6473. 15:03:28 TestInitSystemBusyboxRw Building
  6474. 15:08:18 TestInitSystemBusyboxRw Building done
  6475. 15:08:27 TestInitSystemBusyboxRw Cleaning up
  6476. .
  6477. Ran 1 test in 301.140s
  6478. OK
  6479. * For the case of a successful build, the output_folder would
  6480. contain a <test name> folder with the Buildroot build, build log
  6481. and run-time log. If the build failed, the console output would
  6482. show the stage at which it failed (setup / build / run).
  6483. Depending on the failure stage, the build/run logs and/or
  6484. Buildroot build artifacts can be inspected and instrumented. If
  6485. the QEMU instance needs to be launched for additional testing,
  6486. the first few lines of the run-time log capture it and it would
  6487. allow some incremental testing without re-running support/testing
  6488. /run-tests.
  6489. * You can also make modifications to the current sources inside the
  6490. output_folder (e.g. for debug purposes) and rerun the standard
  6491. Buildroot make targets (in order to regenerate the complete image
  6492. with the new modifications) and then rerun the test. Modifying
  6493. the sources directly can speed up debugging compared to adding
  6494. patch files, wiping the output directoy, and starting the test
  6495. again.
  6496. $ ls output_folder/
  6497. TestInitSystemBusyboxRw/
  6498. TestInitSystemBusyboxRw-build.log
  6499. TestInitSystemBusyboxRw-run.log
  6500. * The source file used to implement this example test is found
  6501. under support/testing/tests/init/test_busybox.py. This file
  6502. outlines the minimal defconfig that creates the build, QEMU
  6503. configuration to launch the built images and the test case
  6504. assertions.
  6505. To test an existing or new test case within Gitlab CI, there is a
  6506. method of invoking a specific test by creating a Buildroot fork in
  6507. Gitlab under your account. This can be handy when adding/changing a
  6508. run-time test or fixing a bug on a use case tested by a run-time test
  6509. case.
  6510. In the examples below, the <name> component of the branch name is a
  6511. unique string you choose to identify this specific job being created.
  6512. * to trigger all run-test test case jobs:
  6513. $ git push gitlab HEAD:<name>-runtime-tests
  6514. * to trigger one test case job, a specific branch naming string is
  6515. used that includes the full test case name.
  6516. $ git push gitlab HEAD:<name>-<test case name>
  6517. ---------------------------------------------------------------------
  6518. ^[4] RFC: (Request for comments) change proposal
  6519. Chapter 23. DEVELOPERS file and get-developers
  6520. The main Buildroot directory contains a file named DEVELOPERS that
  6521. lists the developers involved with various areas of Buildroot. Thanks
  6522. to this file, the get-developers tool allows to:
  6523. * Calculate the list of developers to whom patches should be sent,
  6524. by parsing the patches and matching the modified files with the
  6525. relevant developers. See Section 22.5, “Submitting patches” for
  6526. details.
  6527. * Find which developers are taking care of a given architecture or
  6528. package, so that they can be notified when a build failure occurs
  6529. on this architecture or package. This is done in interaction with
  6530. Buildroot’s autobuild infrastructure.
  6531. We ask developers adding new packages, new boards, or generally new
  6532. functionality in Buildroot, to register themselves in the DEVELOPERS
  6533. file. As an example, we expect a developer contributing a new package
  6534. to include in his patch the appropriate modification to the
  6535. DEVELOPERS file.
  6536. The DEVELOPERS file format is documented in detail inside the file
  6537. itself.
  6538. The get-developers tool, located in utils/ allows to use the
  6539. DEVELOPERS file for various tasks:
  6540. * When passing one or several patches as command line argument,
  6541. get-developers will return the appropriate git send-email
  6542. command. If the -e option is passed, only the email addresses are
  6543. printed in a format suitable for git send-email --cc-cmd.
  6544. * When using the -a <arch> command line option, get-developers will
  6545. return the list of developers in charge of the given
  6546. architecture.
  6547. * When using the -p <package> command line option, get-developers
  6548. will return the list of developers in charge of the given
  6549. package.
  6550. * When using the -c command line option, get-developers will look
  6551. at all files under version control in the Buildroot repository,
  6552. and list the ones that are not handled by any developer. The
  6553. purpose of this option is to help completing the DEVELOPERS file.
  6554. * When using without any arguments, it validates the integrity of
  6555. the DEVELOPERS file and will note WARNINGS for items that don’t
  6556. match.
  6557. Chapter 24. Release Engineering
  6558. 24.1. Releases
  6559. The Buildroot project makes quarterly releases with monthly bugfix
  6560. releases. The first release of each year is a long term support
  6561. release, LTS.
  6562. * Quarterly releases: 2020.02, 2020.05, 2020.08, and 2020.11
  6563. * Bugfix releases: 2020.02.1, 2020.02.2, …
  6564. * LTS releases: 2020.02, 2021.02, …
  6565. Releases are supported until the first bugfix release of the next
  6566. release, e.g., 2020.05.x is EOL when 2020.08.1 is released.
  6567. LTS releases are supported until the first bugfix release of the next
  6568. LTS, e.g., 2020.02.x is supported until 2021.02.1 is released.
  6569. 24.2. Development
  6570. Each release cycle consist of two months of development on the master
  6571. branch and one month stabilization before the release is made. During
  6572. this phase no new features are added to master, only bugfixes.
  6573. The stabilization phase starts with tagging -rc1, and every week
  6574. until the release, another release candidate is tagged.
  6575. To handle new features and version bumps during the stabilization
  6576. phase, a next branch may be created for these features. Once the
  6577. current release has been made, the next branch is merged into master
  6578. and the development cycle for the next release continues there.
  6579. Part IV. Appendix
  6580. Table of Contents
  6581. 25. Makedev syntax documentation
  6582. 26. Makeusers syntax documentation
  6583. 27. Migrating from older Buildroot versions
  6584. 27.1. Migrating to 2016.11
  6585. 27.2. Migrating to 2017.08
  6586. Chapter 25. Makedev syntax documentation
  6587. The makedev syntax is used in several places in Buildroot to define
  6588. changes to be made for permissions, or which device files to create
  6589. and how to create them, in order to avoid calls to mknod.
  6590. This syntax is derived from the makedev utility, and more complete
  6591. documentation can be found in the package/makedevs/README file.
  6592. It takes the form of a space separated list of fields, one file per
  6593. line; the fields are:
  6594. +--------------------------------------------------+
  6595. |name|type|mode|uid|gid|major|minor|start|inc|count|
  6596. +--------------------------------------------------+
  6597. There are a few non-trivial blocks:
  6598. * name is the path to the file you want to create/modify
  6599. * type is the type of the file, being one of:
  6600. + f: a regular file
  6601. + d: a directory
  6602. + r: a directory recursively
  6603. + c: a character device file
  6604. + b: a block device file
  6605. + p: a named pipe
  6606. * mode are the usual permissions settings (only numerical values
  6607. are allowed)
  6608. * uid and gid are the UID and GID to set on this file; can be
  6609. either numerical values or actual names
  6610. * major and minor are here for device files, set to - for other
  6611. files
  6612. * start, inc and count are for when you want to create a batch of
  6613. files, and can be reduced to a loop, beginning at start,
  6614. incrementing its counter by inc until it reaches count
  6615. Let’s say you want to change the permissions of a given file; using
  6616. this syntax, you will need to write:
  6617. /usr/bin/foo f 755 0 0 - - - - -
  6618. /usr/bin/bar f 755 root root - - - - -
  6619. /data/buz f 644 buz-user buz-group - - - - -
  6620. Alternatively, if you want to change owner/permission of a directory
  6621. recursively, you can write (to set UID to foo, GID to bar and access
  6622. rights to rwxr-x--- for the directory /usr/share/myapp and all files
  6623. and directories below it):
  6624. /usr/share/myapp r 750 foo bar - - - - -
  6625. On the other hand, if you want to create the device file /dev/hda and
  6626. the corresponding 15 files for the partitions, you will need for /dev
  6627. /hda:
  6628. /dev/hda b 640 root root 3 0 0 0 -
  6629. and then for device files corresponding to the partitions of /dev/
  6630. hda, /dev/hdaX, X ranging from 1 to 15:
  6631. /dev/hda b 640 root root 3 1 1 1 15
  6632. Extended attributes are supported if
  6633. BR2_ROOTFS_DEVICE_TABLE_SUPPORTS_EXTENDED_ATTRIBUTES is enabled. This
  6634. is done by adding a line starting with |xattr after the line
  6635. describing the file. Right now, only capability is supported as
  6636. extended attribute.
  6637. +------------------+
  6638. ||xattr|capability |
  6639. +------------------+
  6640. * |xattr is a "flag" that indicate an extended attribute
  6641. * capability is a capability to add to the previous file
  6642. If you want to add the capability cap_sys_admin to the binary foo,
  6643. you will write :
  6644. /usr/bin/foo f 755 root root - - - - -
  6645. |xattr cap_sys_admin+eip
  6646. You can add several capabilities to a file by using several |xattr
  6647. lines. If you want to add the capability cap_sys_admin and
  6648. cap_net_admin to the binary foo, you will write :
  6649. /usr/bin/foo f 755 root root - - - - -
  6650. |xattr cap_sys_admin+eip
  6651. |xattr cap_net_admin+eip
  6652. Chapter 26. Makeusers syntax documentation
  6653. The syntax to create users is inspired by the makedev syntax, above,
  6654. but is specific to Buildroot.
  6655. The syntax for adding a user is a space-separated list of fields, one
  6656. user per line; the fields are:
  6657. +---------------------------------------------------------+
  6658. |username|uid|group|gid|password|home|shell|groups|comment|
  6659. +---------------------------------------------------------+
  6660. Where:
  6661. * username is the desired user name (aka login name) for the user.
  6662. It can not be root, and must be unique. If set to -, then just a
  6663. group will be created.
  6664. * uid is the desired UID for the user. It must be unique, and not
  6665. 0. If set to -1, then a unique UID will be computed by Buildroot
  6666. in the range [1000…1999]
  6667. * group is the desired name for the user’s main group. It can not
  6668. be root. If the group does not exist, it will be created.
  6669. * gid is the desired GID for the user’s main group. It must be
  6670. unique, and not 0. If set to -1, and the group does not already
  6671. exist, then a unique GID will be computed by Buildroot in the
  6672. range [1000..1999]
  6673. * password is the crypt(3)-encoded password. If prefixed with !,
  6674. then login is disabled. If prefixed with =, then it is
  6675. interpreted as clear-text, and will be crypt-encoded (using MD5).
  6676. If prefixed with !=, then the password will be crypt-encoded
  6677. (using MD5) and login will be disabled. If set to *, then login
  6678. is not allowed. If set to -, then no password value will be set.
  6679. * home is the desired home directory for the user. If set to -, no
  6680. home directory will be created, and the user’s home will be /.
  6681. Explicitly setting home to / is not allowed.
  6682. * shell is the desired shell for the user. If set to -, then /bin/
  6683. false is set as the user’s shell.
  6684. * groups is the comma-separated list of additional groups the user
  6685. should be part of. If set to -, then the user will be a member of
  6686. no additional group. Missing groups will be created with an
  6687. arbitrary gid.
  6688. * comment (aka GECOS [https://en.wikipedia.org/wiki/Gecos_field]
  6689. field) is an almost-free-form text.
  6690. There are a few restrictions on the content of each field:
  6691. * except for comment, all fields are mandatory.
  6692. * except for comment, fields may not contain spaces.
  6693. * no field may contain a colon (:).
  6694. If home is not -, then the home directory, and all files below, will
  6695. belong to the user and its main group.
  6696. Examples:
  6697. foo -1 bar -1 !=blabla /home/foo /bin/sh alpha,bravo Foo user
  6698. This will create this user:
  6699. * username (aka login name) is: foo
  6700. * uid is computed by Buildroot
  6701. * main group is: bar
  6702. * main group gid is computed by Buildroot
  6703. * clear-text password is: blabla, will be crypt(3)-encoded, and
  6704. login is disabled.
  6705. * home is: /home/foo
  6706. * shell is: /bin/sh
  6707. * foo is also a member of groups: alpha and bravo
  6708. * comment is: Foo user
  6709. test 8000 wheel -1 = - /bin/sh - Test user
  6710. This will create this user:
  6711. * username (aka login name) is: test
  6712. * uid is : 8000
  6713. * main group is: wheel
  6714. * main group gid is computed by Buildroot, and will use the value
  6715. defined in the rootfs skeleton
  6716. * password is empty (aka no password).
  6717. * home is / but will not belong to test
  6718. * shell is: /bin/sh
  6719. * test is not a member of any additional groups
  6720. * comment is: Test user
  6721. Chapter 27. Migrating from older Buildroot versions
  6722. Some versions have introduced backward incompatibilities. This
  6723. section explains those incompatibilities, and for each explains what
  6724. to do to complete the migration.
  6725. 27.1. Migrating to 2016.11
  6726. Before Buildroot 2016.11, it was possible to use only one
  6727. br2-external tree at once. With Buildroot 2016.11 came the
  6728. possibility to use more than one simultaneously (for details, see
  6729. Section 9.2, “Keeping customizations outside of Buildroot”).
  6730. This however means that older br2-external trees are not usable
  6731. as-is. A minor change has to be made: adding a name to your
  6732. br2-external tree.
  6733. This can be done very easily in just a few steps:
  6734. * First, create a new file named external.desc, at the root of your
  6735. br2-external tree, with a single line defining the name of your
  6736. br2-external tree:
  6737. $ echo 'name: NAME_OF_YOUR_TREE' >external.desc
  6738. Note. Be careful when choosing a name: It has to be unique and be
  6739. made with only ASCII characters from the set [A-Za-z0-9_].
  6740. * Then, change every occurence of BR2_EXTERNAL in your br2-external
  6741. tree with the new variable:
  6742. $ find . -type f | xargs sed -i 's/BR2_EXTERNAL/BR2_EXTERNAL_NAME_OF_YOUR_TREE_PATH/g'
  6743. Now, your br2-external tree can be used with Buildroot 2016.11
  6744. onward.
  6745. Note: This change makes your br2-external tree incompatible with
  6746. Buildroot before 2016.11.
  6747. 27.2. Migrating to 2017.08
  6748. Before Buildroot 2017.08, host packages were installed in $(HOST_DIR)
  6749. /usr (with e.g. the autotools' --prefix=$(HOST_DIR)/usr). With
  6750. Buildroot 2017.08, they are now installed directly in $(HOST_DIR).
  6751. Whenever a package installs an executable that is linked with a
  6752. library in $(HOST_DIR)/lib, it must have an RPATH pointing to that
  6753. directory.
  6754. An RPATH pointing to $(HOST_DIR)/usr/lib is no longer accepted.