guix-cookbook.fa.po 155 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436
  1. # SOME DESCRIPTIVE TITLE
  2. # Copyright (C) YEAR the authors of Guix (msgids)
  3. # This file is distributed under the same license as the guix manual package.
  4. # Soheil Khanalipur <soheil@disroot.org>, 2021.
  5. msgid ""
  6. msgstr ""
  7. "Project-Id-Version: guix manual checkout\n"
  8. "Report-Msgid-Bugs-To: bug-guix@gnu.org\n"
  9. "POT-Creation-Date: 2021-01-25 00:00+0100\n"
  10. "PO-Revision-Date: 2021-05-03 02:58+0000\n"
  11. "Last-Translator: Soheil Khanalipur <soheil@disroot.org>\n"
  12. "Language-Team: Persian <https://translate.fedoraproject.org/projects/guix/documentation-cookbook/fa/>\n"
  13. "Language: fa\n"
  14. "MIME-Version: 1.0\n"
  15. "Content-Type: text/plain; charset=UTF-8\n"
  16. "Content-Transfer-Encoding: 8bit\n"
  17. "Plural-Forms: nplurals=2; plural=n > 1;\n"
  18. "X-Generator: Weblate 4.6.1\n"
  19. #. type: Plain text
  20. #: guix-git/doc/guix-cookbook.texi:7
  21. msgid "@documentencoding UTF-8"
  22. msgstr ""
  23. #. type: top
  24. #: guix-git/doc/guix-cookbook.texi:7 guix-git/doc/guix-cookbook.texi:35
  25. #: guix-git/doc/guix-cookbook.texi:49
  26. #, no-wrap
  27. msgid "GNU Guix Cookbook"
  28. msgstr ""
  29. #. type: copying
  30. #: guix-git/doc/guix-cookbook.texi:20
  31. msgid "Copyright @copyright{} 2019 Ricardo Wurmus@* Copyright @copyright{} 2019 Efraim Flashner@* Copyright @copyright{} 2019 Pierre Neidhardt@* Copyright @copyright{} 2020 Oleg Pykhalov@* Copyright @copyright{} 2020 Matthew Brooks@* Copyright @copyright{} 2020 Marcin Karpezo@* Copyright @copyright{} 2020 Brice Waegeneire@* Copyright @copyright{} 2020 André Batista@* Copyright @copyright{} 2020 Christopher Lemmer Webber"
  32. msgstr ""
  33. #. type: copying
  34. #: guix-git/doc/guix-cookbook.texi:27
  35. msgid "Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''."
  36. msgstr ""
  37. #. type: dircategory
  38. #: guix-git/doc/guix-cookbook.texi:29
  39. #, no-wrap
  40. msgid "System administration"
  41. msgstr ""
  42. #. type: menuentry
  43. #: guix-git/doc/guix-cookbook.texi:32
  44. msgid "Guix cookbook: (guix-cookbook)"
  45. msgstr ""
  46. #. type: menuentry
  47. #: guix-git/doc/guix-cookbook.texi:32
  48. msgid "Tutorials and examples for GNU Guix."
  49. msgstr ""
  50. #. type: subtitle
  51. #: guix-git/doc/guix-cookbook.texi:36
  52. #, no-wrap
  53. msgid "Tutorials and examples for using the GNU Guix Functional Package Manager"
  54. msgstr ""
  55. #. type: author
  56. #: guix-git/doc/guix-cookbook.texi:37
  57. #, no-wrap
  58. msgid "The GNU Guix Developers"
  59. msgstr ""
  60. #. type: node
  61. #: guix-git/doc/guix-cookbook.texi:48
  62. #, no-wrap
  63. msgid "Top"
  64. msgstr ""
  65. #. type: Plain text
  66. #: guix-git/doc/guix-cookbook.texi:55
  67. msgid "This document presents tutorials and detailed examples for GNU@tie{}Guix, a functional package management tool written for the GNU system. Please @pxref{Top,,, guix, GNU Guix reference manual} for details about the system, its API, and related concepts."
  68. msgstr ""
  69. #. You can replace the following paragraph with information on
  70. #. type: Plain text
  71. #: guix-git/doc/guix-cookbook.texi:63
  72. msgid "If you would like to translate this document in your native language, consider joining @uref{https://translate.fedoraproject.org/projects/guix/documentation-cookbook, Weblate}."
  73. msgstr ""
  74. #. type: chapter
  75. #: guix-git/doc/guix-cookbook.texi:70 guix-git/doc/guix-cookbook.texi:79
  76. #: guix-git/doc/guix-cookbook.texi:95 guix-git/doc/guix-cookbook.texi:96
  77. #, no-wrap
  78. msgid "Scheme tutorials"
  79. msgstr ""
  80. #. type: menuentry
  81. #: guix-git/doc/guix-cookbook.texi:70
  82. msgid "Meet your new favorite language!"
  83. msgstr ""
  84. #. type: chapter
  85. #: guix-git/doc/guix-cookbook.texi:70 guix-git/doc/guix-cookbook.texi:83
  86. #: guix-git/doc/guix-cookbook.texi:302 guix-git/doc/guix-cookbook.texi:303
  87. #, no-wrap
  88. msgid "Packaging"
  89. msgstr ""
  90. #. type: menuentry
  91. #: guix-git/doc/guix-cookbook.texi:70
  92. msgid "Packaging tutorials"
  93. msgstr ""
  94. #. type: chapter
  95. #: guix-git/doc/guix-cookbook.texi:70 guix-git/doc/guix-cookbook.texi:87
  96. #: guix-git/doc/guix-cookbook.texi:1345 guix-git/doc/guix-cookbook.texi:1346
  97. #, no-wrap
  98. msgid "System Configuration"
  99. msgstr ""
  100. #. type: menuentry
  101. #: guix-git/doc/guix-cookbook.texi:70
  102. msgid "Customizing the GNU System"
  103. msgstr ""
  104. #. type: chapter
  105. #: guix-git/doc/guix-cookbook.texi:70 guix-git/doc/guix-cookbook.texi:2394
  106. #: guix-git/doc/guix-cookbook.texi:2395
  107. #, no-wrap
  108. msgid "Advanced package management"
  109. msgstr ""
  110. #. type: menuentry
  111. #: guix-git/doc/guix-cookbook.texi:70
  112. msgid "Power to the users!"
  113. msgstr ""
  114. #. type: chapter
  115. #: guix-git/doc/guix-cookbook.texi:70 guix-git/doc/guix-cookbook.texi:2792
  116. #: guix-git/doc/guix-cookbook.texi:2793
  117. #, no-wrap
  118. msgid "Environment management"
  119. msgstr ""
  120. #. type: menuentry
  121. #: guix-git/doc/guix-cookbook.texi:70
  122. msgid "Control environment"
  123. msgstr ""
  124. #. type: chapter
  125. #: guix-git/doc/guix-cookbook.texi:74 guix-git/doc/guix-cookbook.texi:2916
  126. #: guix-git/doc/guix-cookbook.texi:2917
  127. #, no-wrap
  128. msgid "Acknowledgments"
  129. msgstr ""
  130. #. type: menuentry
  131. #: guix-git/doc/guix-cookbook.texi:74
  132. msgid "Thanks!"
  133. msgstr "سِپاس!"
  134. #. type: appendix
  135. #: guix-git/doc/guix-cookbook.texi:74 guix-git/doc/guix-cookbook.texi:2941
  136. #: guix-git/doc/guix-cookbook.texi:2942
  137. #, no-wrap
  138. msgid "GNU Free Documentation License"
  139. msgstr ""
  140. #. type: menuentry
  141. #: guix-git/doc/guix-cookbook.texi:74
  142. msgid "The license of this document."
  143. msgstr ""
  144. #. type: unnumbered
  145. #: guix-git/doc/guix-cookbook.texi:74 guix-git/doc/guix-cookbook.texi:2947
  146. #: guix-git/doc/guix-cookbook.texi:2948
  147. #, no-wrap
  148. msgid "Concept Index"
  149. msgstr ""
  150. #. type: menuentry
  151. #: guix-git/doc/guix-cookbook.texi:74
  152. msgid "Concepts."
  153. msgstr ""
  154. #. type: menuentry
  155. #: guix-git/doc/guix-cookbook.texi:77
  156. msgid "--- The Detailed Node Listing ---"
  157. msgstr ""
  158. #. type: section
  159. #: guix-git/doc/guix-cookbook.texi:81 guix-git/doc/guix-cookbook.texi:109
  160. #: guix-git/doc/guix-cookbook.texi:110
  161. #, no-wrap
  162. msgid "A Scheme Crash Course"
  163. msgstr ""
  164. #. type: menuentry
  165. #: guix-git/doc/guix-cookbook.texi:81
  166. msgid "Learn the basics of Scheme"
  167. msgstr ""
  168. #. type: section
  169. #: guix-git/doc/guix-cookbook.texi:85 guix-git/doc/guix-cookbook.texi:314
  170. #: guix-git/doc/guix-cookbook.texi:316 guix-git/doc/guix-cookbook.texi:317
  171. #, no-wrap
  172. msgid "Packaging Tutorial"
  173. msgstr ""
  174. #. type: menuentry
  175. #: guix-git/doc/guix-cookbook.texi:85
  176. msgid "Let's add a package to Guix!"
  177. msgstr ""
  178. #. type: section
  179. #: guix-git/doc/guix-cookbook.texi:89 guix-git/doc/guix-cookbook.texi:1364
  180. #: guix-git/doc/guix-cookbook.texi:1366 guix-git/doc/guix-cookbook.texi:1367
  181. #, no-wrap
  182. msgid "Customizing the Kernel"
  183. msgstr ""
  184. #. type: menuentry
  185. #: guix-git/doc/guix-cookbook.texi:89
  186. msgid "Creating and using a custom Linux kernel"
  187. msgstr ""
  188. #. type: Plain text
  189. #: guix-git/doc/guix-cookbook.texi:102
  190. msgid "GNU@tie{}Guix is written in the general purpose programming language Scheme, and many of its features can be accessed and manipulated programmatically. You can use Scheme to generate package definitions, to modify them, to build them, to deploy whole operating systems, etc."
  191. msgstr ""
  192. #. type: Plain text
  193. #: guix-git/doc/guix-cookbook.texi:106
  194. msgid "Knowing the basics of how to program in Scheme will unlock many of the advanced features Guix provides --- and you don't even need to be an experienced programmer to use them!"
  195. msgstr ""
  196. #. type: Plain text
  197. #: guix-git/doc/guix-cookbook.texi:108
  198. msgid "Let's get started!"
  199. msgstr ""
  200. #. type: cindex
  201. #: guix-git/doc/guix-cookbook.texi:112
  202. #, no-wrap
  203. msgid "Scheme, crash course"
  204. msgstr ""
  205. #. type: Plain text
  206. #: guix-git/doc/guix-cookbook.texi:118
  207. msgid "Guix uses the Guile implementation of Scheme. To start playing with the language, install it with @code{guix install guile} and start a @dfn{REPL}---short for @uref{https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop, @dfn{read-eval-print loop}}---by running @code{guile} from the command line."
  208. msgstr ""
  209. #. type: Plain text
  210. #: guix-git/doc/guix-cookbook.texi:121
  211. msgid "Alternatively you can also run @code{guix environment --ad-hoc guile -- guile} if you'd rather not have Guile installed in your user profile."
  212. msgstr ""
  213. #. type: Plain text
  214. #: guix-git/doc/guix-cookbook.texi:127
  215. msgid "In the following examples, lines show what you would type at the REPL; lines starting with ``@result{}'' show evaluation results, while lines starting with ``@print{}'' show things that get printed. @xref{Using Guile Interactively,,, guile, GNU Guile Reference Manual}, for more details on the REPL."
  216. msgstr ""
  217. #. type: itemize
  218. #: guix-git/doc/guix-cookbook.texi:135
  219. msgid "Scheme syntax boils down to a tree of expressions (or @emph{s-expression} in Lisp lingo). An expression can be a literal such as numbers and strings, or a compound which is a parenthesized list of compounds and literals. @code{#true} and @code{#false} (abbreviated @code{#t} and @code{#f}) stand for the Booleans ``true'' and ``false'', respectively."
  220. msgstr ""
  221. #. type: itemize
  222. #: guix-git/doc/guix-cookbook.texi:137
  223. msgid "Examples of valid expressions:"
  224. msgstr ""
  225. #. type: lisp
  226. #: guix-git/doc/guix-cookbook.texi:141
  227. #, no-wrap
  228. msgid ""
  229. "\"Hello World!\"\n"
  230. "@result{} \"Hello World!\"\n"
  231. "\n"
  232. msgstr ""
  233. #. type: lisp
  234. #: guix-git/doc/guix-cookbook.texi:144
  235. #, no-wrap
  236. msgid ""
  237. "17\n"
  238. "@result{} 17\n"
  239. "\n"
  240. msgstr ""
  241. #. type: lisp
  242. #: guix-git/doc/guix-cookbook.texi:148
  243. #, no-wrap
  244. msgid ""
  245. "(display (string-append \"Hello \" \"Guix\" \"\\n\"))\n"
  246. "@print{} Hello Guix!\n"
  247. "@result{} #<unspecified>\n"
  248. msgstr ""
  249. #. type: itemize
  250. #: guix-git/doc/guix-cookbook.texi:155
  251. msgid "This last example is a function call nested in another function call. When a parenthesized expression is evaluated, the first term is the function and the rest are the arguments passed to the function. Every function returns the last evaluated expression as its return value."
  252. msgstr ""
  253. #. type: itemize
  254. #: guix-git/doc/guix-cookbook.texi:158
  255. msgid "Anonymous functions are declared with the @code{lambda} term:"
  256. msgstr ""
  257. #. type: lisp
  258. #: guix-git/doc/guix-cookbook.texi:162
  259. #, no-wrap
  260. msgid ""
  261. "(lambda (x) (* x x))\n"
  262. "@result{} #<procedure 120e348 at <unknown port>:24:0 (x)>\n"
  263. msgstr ""
  264. #. type: itemize
  265. #: guix-git/doc/guix-cookbook.texi:167
  266. msgid "The above procedure returns the square of its argument. Since everything is an expression, the @code{lambda} expression returns an anonymous procedure, which can in turn be applied to an argument:"
  267. msgstr ""
  268. #. type: lisp
  269. #: guix-git/doc/guix-cookbook.texi:171
  270. #, no-wrap
  271. msgid ""
  272. "((lambda (x) (* x x)) 3)\n"
  273. "@result{} 9\n"
  274. msgstr ""
  275. #. type: itemize
  276. #: guix-git/doc/guix-cookbook.texi:175
  277. msgid "Anything can be assigned a global name with @code{define}:"
  278. msgstr ""
  279. #. type: lisp
  280. #: guix-git/doc/guix-cookbook.texi:181
  281. #, no-wrap
  282. msgid ""
  283. "(define a 3)\n"
  284. "(define square (lambda (x) (* x x)))\n"
  285. "(square a)\n"
  286. "@result{} 9\n"
  287. msgstr ""
  288. #. type: itemize
  289. #: guix-git/doc/guix-cookbook.texi:185
  290. msgid "Procedures can be defined more concisely with the following syntax:"
  291. msgstr ""
  292. #. type: lisp
  293. #: guix-git/doc/guix-cookbook.texi:188
  294. #, no-wrap
  295. msgid "(define (square x) (* x x))\n"
  296. msgstr ""
  297. #. type: itemize
  298. #: guix-git/doc/guix-cookbook.texi:192
  299. msgid "A list structure can be created with the @code{list} procedure:"
  300. msgstr ""
  301. #. type: lisp
  302. #: guix-git/doc/guix-cookbook.texi:196
  303. #, no-wrap
  304. msgid ""
  305. "(list 2 a 5 7)\n"
  306. "@result{} (2 3 5 7)\n"
  307. msgstr ""
  308. #. type: itemize
  309. #: guix-git/doc/guix-cookbook.texi:203
  310. msgid "The @dfn{quote} disables evaluation of a parenthesized expression: the first term is not called over the other terms (@pxref{Expression Syntax, quote,, guile, GNU Guile Reference Manual}). Thus it effectively returns a list of terms."
  311. msgstr ""
  312. #. type: lisp
  313. #: guix-git/doc/guix-cookbook.texi:207
  314. #, no-wrap
  315. msgid ""
  316. "'(display (string-append \"Hello \" \"Guix\" \"\\n\"))\n"
  317. "@result{} (display (string-append \"Hello \" \"Guix\" \"\\n\"))\n"
  318. "\n"
  319. msgstr ""
  320. #. type: lisp
  321. #: guix-git/doc/guix-cookbook.texi:210
  322. #, no-wrap
  323. msgid ""
  324. "'(2 a 5 7)\n"
  325. "@result{} (2 a 5 7)\n"
  326. msgstr ""
  327. #. type: itemize
  328. #: guix-git/doc/guix-cookbook.texi:216
  329. msgid "The @dfn{quasiquote} disables evaluation of a parenthesized expression until @dfn{unquote} (a comma) re-enables it. Thus it provides us with fine-grained control over what is evaluated and what is not."
  330. msgstr ""
  331. #. type: lisp
  332. #: guix-git/doc/guix-cookbook.texi:220
  333. #, no-wrap
  334. msgid ""
  335. "`(2 a 5 7 (2 ,a 5 ,(+ a 4)))\n"
  336. "@result{} (2 a 5 7 (2 3 5 7))\n"
  337. msgstr ""
  338. #. type: itemize
  339. #: guix-git/doc/guix-cookbook.texi:224
  340. msgid "Note that the above result is a list of mixed elements: numbers, symbols (here @code{a}) and the last element is a list itself."
  341. msgstr ""
  342. #. type: itemize
  343. #: guix-git/doc/guix-cookbook.texi:228
  344. msgid "Multiple variables can be named locally with @code{let} (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}):"
  345. msgstr ""
  346. #. type: lisp
  347. #: guix-git/doc/guix-cookbook.texi:235
  348. #, no-wrap
  349. msgid ""
  350. "(define x 10)\n"
  351. "(let ((x 2)\n"
  352. " (y 3))\n"
  353. " (list x y))\n"
  354. "@result{} (2 3)\n"
  355. "\n"
  356. msgstr ""
  357. #. type: lisp
  358. #: guix-git/doc/guix-cookbook.texi:238
  359. #, no-wrap
  360. msgid ""
  361. "x\n"
  362. "@result{} 10\n"
  363. "\n"
  364. msgstr ""
  365. #. type: lisp
  366. #: guix-git/doc/guix-cookbook.texi:241
  367. #, no-wrap
  368. msgid ""
  369. "y\n"
  370. "@error{} In procedure module-lookup: Unbound variable: y\n"
  371. msgstr ""
  372. #. type: itemize
  373. #: guix-git/doc/guix-cookbook.texi:245
  374. msgid "Use @code{let*} to allow later variable declarations to refer to earlier definitions."
  375. msgstr ""
  376. #. type: lisp
  377. #: guix-git/doc/guix-cookbook.texi:251
  378. #, no-wrap
  379. msgid ""
  380. "(let* ((x 2)\n"
  381. " (y (* x 3)))\n"
  382. " (list x y))\n"
  383. "@result{} (2 6)\n"
  384. msgstr ""
  385. #. type: itemize
  386. #: guix-git/doc/guix-cookbook.texi:258
  387. msgid "@dfn{Keywords} are typically used to identify the named parameters of a procedure. They are prefixed by @code{#:} (hash, colon) followed by alphanumeric characters: @code{#:like-this}. @xref{Keywords,,, guile, GNU Guile Reference Manual}."
  388. msgstr ""
  389. #. type: itemize
  390. #: guix-git/doc/guix-cookbook.texi:263
  391. msgid "The percentage @code{%} is typically used for read-only global variables in the build stage. Note that it is merely a convention, like @code{_} in C. Scheme treats @code{%} exactly the same as any other letter."
  392. msgstr ""
  393. #. type: itemize
  394. #: guix-git/doc/guix-cookbook.texi:267
  395. msgid "Modules are created with @code{define-module} (@pxref{Creating Guile Modules,,, guile, GNU Guile Reference Manual}). For instance"
  396. msgstr ""
  397. #. type: lisp
  398. #: guix-git/doc/guix-cookbook.texi:273
  399. #, no-wrap
  400. msgid ""
  401. "(define-module (guix build-system ruby)\n"
  402. " #:use-module (guix store)\n"
  403. " #:export (ruby-build\n"
  404. " ruby-build-system))\n"
  405. msgstr ""
  406. #. type: itemize
  407. #: guix-git/doc/guix-cookbook.texi:279
  408. msgid "defines the module @code{guix build-system ruby} which must be located in @file{guix/build-system/ruby.scm} somewhere in the Guile load path. It depends on the @code{(guix store)} module and it exports two variables, @code{ruby-build} and @code{ruby-build-system}."
  409. msgstr ""
  410. #. type: Plain text
  411. #: guix-git/doc/guix-cookbook.texi:284
  412. msgid "For a more detailed introduction, check out @uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm, Scheme at a Glance}, by Steve Litt."
  413. msgstr ""
  414. #. type: Plain text
  415. #: guix-git/doc/guix-cookbook.texi:296
  416. msgid "One of the reference Scheme books is the seminal ``Structure and Interpretation of Computer Programs'', by Harold Abelson and Gerald Jay Sussman, with Julie Sussman. You'll find a @uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html, free copy online}, together with @uref{https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-001-structure-and-interpretation-of-computer-programs-spring-2005/video-lectures/, videos of the lectures by the authors}. The book is available in Texinfo format as the @code{sicp} Guix package. Go ahead, run @code{guix install sicp} and start reading with @code{info sicp} (@pxref{,,, sicp, Structure and Interpretation of Computer Programs}). An @uref{https://sarabander.github.io/sicp/, unofficial ebook is also available}."
  417. msgstr ""
  418. #. type: Plain text
  419. #: guix-git/doc/guix-cookbook.texi:299
  420. msgid "You'll find more books, tutorials and other resources at @url{https://schemers.org/}."
  421. msgstr ""
  422. #. type: cindex
  423. #: guix-git/doc/guix-cookbook.texi:305
  424. #, no-wrap
  425. msgid "packaging"
  426. msgstr ""
  427. #. type: Plain text
  428. #: guix-git/doc/guix-cookbook.texi:311
  429. msgid "This chapter is dedicated to teaching you how to add packages to the collection of packages that come with GNU Guix. This involves writing package definitions in Guile Scheme, organizing them in package modules, and building them."
  430. msgstr ""
  431. #. type: menuentry
  432. #: guix-git/doc/guix-cookbook.texi:314
  433. msgid "A tutorial on how to add packages to Guix."
  434. msgstr ""
  435. #. type: Plain text
  436. #: guix-git/doc/guix-cookbook.texi:325
  437. msgid "GNU Guix stands out as the @emph{hackable} package manager, mostly because it uses @uref{https://www.gnu.org/software/guile/, GNU Guile}, a powerful high-level programming language, one of the @uref{https://en.wikipedia.org/wiki/Scheme_%28programming_language%29, Scheme} dialects from the @uref{https://en.wikipedia.org/wiki/Lisp_%28programming_language%29, Lisp family}."
  438. msgstr ""
  439. #. type: Plain text
  440. #: guix-git/doc/guix-cookbook.texi:329
  441. msgid "Package definitions are also written in Scheme, which empowers Guix in some very unique ways, unlike most other package managers that use shell scripts or simple languages."
  442. msgstr ""
  443. #. type: itemize
  444. #: guix-git/doc/guix-cookbook.texi:334
  445. msgid "Use functions, structures, macros and all of Scheme expressiveness for your package definitions."
  446. msgstr ""
  447. #. type: itemize
  448. #: guix-git/doc/guix-cookbook.texi:338
  449. msgid "Inheritance makes it easy to customize a package by inheriting from it and modifying only what is needed."
  450. msgstr ""
  451. #. type: itemize
  452. #: guix-git/doc/guix-cookbook.texi:348
  453. msgid "Batch processing: the whole package collection can be parsed, filtered and processed. Building a headless server with all graphical interfaces stripped out? It's possible. Want to rebuild everything from source using specific compiler optimization flags? Pass the @code{#:make-flags \"...\"} argument to the list of packages. It wouldn't be a stretch to think @uref{https://wiki.gentoo.org/wiki/USE_flag, Gentoo USE flags} here, but this goes even further: the changes don't have to be thought out beforehand by the packager, they can be @emph{programmed} by the user!"
  454. msgstr ""
  455. #. type: Plain text
  456. #: guix-git/doc/guix-cookbook.texi:354
  457. msgid "The following tutorial covers all the basics around package creation with Guix. It does not assume much knowledge of the Guix system nor of the Lisp language. The reader is only expected to be familiar with the command line and to have some basic programming knowledge."
  458. msgstr ""
  459. #. type: subsection
  460. #: guix-git/doc/guix-cookbook.texi:355 guix-git/doc/guix-cookbook.texi:356
  461. #, no-wrap
  462. msgid "A ``Hello World'' package"
  463. msgstr ""
  464. #. type: Plain text
  465. #: guix-git/doc/guix-cookbook.texi:361
  466. msgid "The ``Defining Packages'' section of the manual introduces the basics of Guix packaging (@pxref{Defining Packages,,, guix, GNU Guix Reference Manual}). In the following section, we will partly go over those basics again."
  467. msgstr ""
  468. #. type: Plain text
  469. #: guix-git/doc/guix-cookbook.texi:367
  470. msgid "GNU@tie{}Hello is a dummy project that serves as an idiomatic example for packaging. It uses the GNU build system (@code{./configure && make && make install}). Guix already provides a package definition which is a perfect example to start with. You can look up its declaration with @code{guix edit hello} from the command line. Let's see how it looks:"
  471. msgstr ""
  472. #. type: lisp
  473. #: guix-git/doc/guix-cookbook.texi:388
  474. #, no-wrap
  475. msgid ""
  476. "(define-public hello\n"
  477. " (package\n"
  478. " (name \"hello\")\n"
  479. " (version \"2.10\")\n"
  480. " (source (origin\n"
  481. " (method url-fetch)\n"
  482. " (uri (string-append \"mirror://gnu/hello/hello-\" version\n"
  483. " \".tar.gz\"))\n"
  484. " (sha256\n"
  485. " (base32\n"
  486. " \"0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i\"))))\n"
  487. " (build-system gnu-build-system)\n"
  488. " (synopsis \"Hello, GNU world: An example GNU package\")\n"
  489. " (description\n"
  490. " \"GNU Hello prints the message \\\"Hello, world!\\\" and then exits. It\n"
  491. "serves as an example of standard GNU coding practices. As such, it supports\n"
  492. "command-line arguments, multiple languages, and so on.\")\n"
  493. " (home-page \"https://www.gnu.org/software/hello/\")\n"
  494. " (license gpl3+)))\n"
  495. msgstr ""
  496. #. type: Plain text
  497. #: guix-git/doc/guix-cookbook.texi:392
  498. msgid "As you can see, most of it is rather straightforward. But let's review the fields together:"
  499. msgstr ""
  500. #. type: item
  501. #: guix-git/doc/guix-cookbook.texi:394
  502. #, no-wrap
  503. msgid "name"
  504. msgstr "نام"
  505. #. type: table
  506. #: guix-git/doc/guix-cookbook.texi:397
  507. msgid "The project name. Using Scheme conventions, we prefer to keep it lower case, without underscore and using dash-separated words."
  508. msgstr ""
  509. #. type: item
  510. #: guix-git/doc/guix-cookbook.texi:398
  511. #, no-wrap
  512. msgid "source"
  513. msgstr ""
  514. #. type: table
  515. #: guix-git/doc/guix-cookbook.texi:401
  516. msgid "This field contains a description of the source code origin. The @code{origin} record contains these fields:"
  517. msgstr ""
  518. #. type: item
  519. #: guix-git/doc/guix-cookbook.texi:403
  520. #, no-wrap
  521. msgid "The method, here @code{url-fetch} to download via HTTP/FTP, but other methods"
  522. msgstr ""
  523. #. type: enumerate
  524. #: guix-git/doc/guix-cookbook.texi:405
  525. msgid "exist, such as @code{git-fetch} for Git repositories."
  526. msgstr ""
  527. #. type: item
  528. #: guix-git/doc/guix-cookbook.texi:405
  529. #, no-wrap
  530. msgid "The URI, which is typically some @code{https://} location for @code{url-fetch}. Here"
  531. msgstr ""
  532. #. type: enumerate
  533. #: guix-git/doc/guix-cookbook.texi:408
  534. msgid "the special `mirror://gnu` refers to a set of well known locations, all of which can be used by Guix to fetch the source, should some of them fail."
  535. msgstr ""
  536. #. type: item
  537. #: guix-git/doc/guix-cookbook.texi:408
  538. #, no-wrap
  539. msgid "The @code{sha256} checksum of the requested file. This is essential to ensure"
  540. msgstr ""
  541. #. type: enumerate
  542. #: guix-git/doc/guix-cookbook.texi:411
  543. msgid "the source is not corrupted. Note that Guix works with base32 strings, hence the call to the @code{base32} function."
  544. msgstr ""
  545. #. type: item
  546. #: guix-git/doc/guix-cookbook.texi:413
  547. #, no-wrap
  548. msgid "build-system"
  549. msgstr ""
  550. #. type: table
  551. #: guix-git/doc/guix-cookbook.texi:422
  552. msgid "This is where the power of abstraction provided by the Scheme language really shines: in this case, the @code{gnu-build-system} abstracts away the famous @code{./configure && make && make install} shell invocations. Other build systems include the @code{trivial-build-system} which does not do anything and requires from the packager to program all the build steps, the @code{python-build-system}, the @code{emacs-build-system}, and many more (@pxref{Build Systems,,, guix, GNU Guix Reference Manual})."
  553. msgstr ""
  554. #. type: item
  555. #: guix-git/doc/guix-cookbook.texi:423
  556. #, no-wrap
  557. msgid "synopsis"
  558. msgstr ""
  559. #. type: table
  560. #: guix-git/doc/guix-cookbook.texi:426
  561. msgid "It should be a concise summary of what the package does. For many packages a tagline from the project's home page can be used as the synopsis."
  562. msgstr ""
  563. #. type: item
  564. #: guix-git/doc/guix-cookbook.texi:427
  565. #, no-wrap
  566. msgid "description"
  567. msgstr ""
  568. #. type: table
  569. #: guix-git/doc/guix-cookbook.texi:430
  570. msgid "Same as for the synopsis, it's fine to re-use the project description from the homepage. Note that Guix uses Texinfo syntax."
  571. msgstr ""
  572. #. type: item
  573. #: guix-git/doc/guix-cookbook.texi:431
  574. #, no-wrap
  575. msgid "home-page"
  576. msgstr ""
  577. #. type: table
  578. #: guix-git/doc/guix-cookbook.texi:433
  579. msgid "Use HTTPS if available."
  580. msgstr ""
  581. #. type: item
  582. #: guix-git/doc/guix-cookbook.texi:434
  583. #, no-wrap
  584. msgid "license"
  585. msgstr ""
  586. #. type: table
  587. #: guix-git/doc/guix-cookbook.texi:437
  588. msgid "See @code{guix/licenses.scm} in the project source for a full list of available licenses."
  589. msgstr ""
  590. #. type: Plain text
  591. #: guix-git/doc/guix-cookbook.texi:441
  592. msgid "Time to build our first package! Nothing fancy here for now: we will stick to a dummy @code{my-hello}, a copy of the above declaration."
  593. msgstr ""
  594. #. type: Plain text
  595. #: guix-git/doc/guix-cookbook.texi:445
  596. msgid "As with the ritualistic ``Hello World'' taught with most programming languages, this will possibly be the most ``manual'' approach. We will work out an ideal setup later; for now we will go the simplest route."
  597. msgstr ""
  598. #. type: Plain text
  599. #: guix-git/doc/guix-cookbook.texi:447
  600. msgid "Save the following to a file @file{my-hello.scm}."
  601. msgstr ""
  602. #. type: lisp
  603. #: guix-git/doc/guix-cookbook.texi:453
  604. #, no-wrap
  605. msgid ""
  606. "(use-modules (guix packages)\n"
  607. " (guix download)\n"
  608. " (guix build-system gnu)\n"
  609. " (guix licenses))\n"
  610. "\n"
  611. msgstr ""
  612. #. type: lisp
  613. #: guix-git/doc/guix-cookbook.texi:472
  614. #, no-wrap
  615. msgid ""
  616. "(package\n"
  617. " (name \"my-hello\")\n"
  618. " (version \"2.10\")\n"
  619. " (source (origin\n"
  620. " (method url-fetch)\n"
  621. " (uri (string-append \"mirror://gnu/hello/hello-\" version\n"
  622. " \".tar.gz\"))\n"
  623. " (sha256\n"
  624. " (base32\n"
  625. " \"0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i\"))))\n"
  626. " (build-system gnu-build-system)\n"
  627. " (synopsis \"Hello, Guix world: An example custom Guix package\")\n"
  628. " (description\n"
  629. " \"GNU Hello prints the message \\\"Hello, world!\\\" and then exits. It\n"
  630. "serves as an example of standard GNU coding practices. As such, it supports\n"
  631. "command-line arguments, multiple languages, and so on.\")\n"
  632. " (home-page \"https://www.gnu.org/software/hello/\")\n"
  633. " (license gpl3+))\n"
  634. msgstr ""
  635. #. type: Plain text
  636. #: guix-git/doc/guix-cookbook.texi:475
  637. msgid "We will explain the extra code in a moment."
  638. msgstr ""
  639. #. type: Plain text
  640. #: guix-git/doc/guix-cookbook.texi:482
  641. msgid "Feel free to play with the different values of the various fields. If you change the source, you'll need to update the checksum. Indeed, Guix refuses to build anything if the given checksum does not match the computed checksum of the source code. To obtain the correct checksum of the package declaration, we need to download the source, compute the sha256 checksum and convert it to base32."
  642. msgstr ""
  643. #. type: Plain text
  644. #: guix-git/doc/guix-cookbook.texi:485
  645. msgid "Thankfully, Guix can automate this task for us; all we need is to provide the URI:"
  646. msgstr ""
  647. #. This is example shell output.
  648. #. type: example
  649. #: guix-git/doc/guix-cookbook.texi:489
  650. #, no-wrap
  651. msgid ""
  652. "$ guix download mirror://gnu/hello/hello-2.10.tar.gz\n"
  653. "\n"
  654. msgstr ""
  655. #. type: example
  656. #: guix-git/doc/guix-cookbook.texi:496
  657. #, no-wrap
  658. msgid ""
  659. "Starting download of /tmp/guix-file.JLYgL7\n"
  660. "From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz...\n"
  661. "following redirection to `https://mirror.ibcp.fr/pub/gnu/hello/hello-2.10.tar.gz'...\n"
  662. " …10.tar.gz 709KiB 2.5MiB/s 00:00 [##################] 100.0%\n"
  663. "/gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz\n"
  664. "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i\n"
  665. msgstr ""
  666. #. type: Plain text
  667. #: guix-git/doc/guix-cookbook.texi:501
  668. msgid "In this specific case the output tells us which mirror was chosen. If the result of the above command is not the same as in the above snippet, update your @code{my-hello} declaration accordingly."
  669. msgstr ""
  670. #. type: Plain text
  671. #: guix-git/doc/guix-cookbook.texi:505
  672. msgid "Note that GNU package tarballs come with an OpenPGP signature, so you should definitely check the signature of this tarball with `gpg` to authenticate it before going further:"
  673. msgstr ""
  674. #. This is example shell output.
  675. #. type: example
  676. #: guix-git/doc/guix-cookbook.texi:509
  677. #, no-wrap
  678. msgid ""
  679. "$ guix download mirror://gnu/hello/hello-2.10.tar.gz.sig\n"
  680. "\n"
  681. msgstr ""
  682. #. type: example
  683. #: guix-git/doc/guix-cookbook.texi:524
  684. #, no-wrap
  685. msgid ""
  686. "Starting download of /tmp/guix-file.03tFfb\n"
  687. "From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz.sig...\n"
  688. "following redirection to `https://ftp.igh.cnrs.fr/pub/gnu/hello/hello-2.10.tar.gz.sig'...\n"
  689. " ….tar.gz.sig 819B 1.2MiB/s 00:00 [##################] 100.0%\n"
  690. "/gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig\n"
  691. "0q0v86n3y38z17rl146gdakw9xc4mcscpk8dscs412j22glrv9jf\n"
  692. "$ gpg --verify /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz\n"
  693. "gpg: Signature made Sun 16 Nov 2014 01:08:37 PM CET\n"
  694. "gpg: using RSA key A9553245FDE9B739\n"
  695. "gpg: Good signature from \"Sami Kerola <kerolasa@@iki.fi>\" [unknown]\n"
  696. "gpg: aka \"Sami Kerola (http://www.iki.fi/kerolasa/) <kerolasa@@iki.fi>\" [unknown]\n"
  697. "gpg: WARNING: This key is not certified with a trusted signature!\n"
  698. "gpg: There is no indication that the signature belongs to the owner.\n"
  699. "Primary key fingerprint: 8ED3 96E3 7E38 D471 A005 30D3 A955 3245 FDE9 B739\n"
  700. msgstr ""
  701. #. type: Plain text
  702. #: guix-git/doc/guix-cookbook.texi:527
  703. msgid "You can then happily run"
  704. msgstr ""
  705. #. Do not translate this command
  706. #. type: example
  707. #: guix-git/doc/guix-cookbook.texi:531
  708. #, no-wrap
  709. msgid "$ guix package --install-from-file=my-hello.scm\n"
  710. msgstr ""
  711. #. type: Plain text
  712. #: guix-git/doc/guix-cookbook.texi:534
  713. msgid "You should now have @code{my-hello} in your profile!"
  714. msgstr ""
  715. #. Do not translate this command
  716. #. type: example
  717. #: guix-git/doc/guix-cookbook.texi:540
  718. #, no-wrap
  719. msgid ""
  720. "$ guix package --list-installed=my-hello\n"
  721. "my-hello\t2.10\tout\n"
  722. "/gnu/store/f1db2mfm8syb8qvc357c53slbvf1g9m9-my-hello-2.10\n"
  723. msgstr ""
  724. #. type: Plain text
  725. #: guix-git/doc/guix-cookbook.texi:545
  726. msgid "We've gone as far as we could without any knowledge of Scheme. Before moving on to more complex packages, now is the right time to brush up on your Scheme knowledge. @pxref{A Scheme Crash Course} to get up to speed."
  727. msgstr ""
  728. #. type: subsection
  729. #: guix-git/doc/guix-cookbook.texi:546 guix-git/doc/guix-cookbook.texi:547
  730. #, no-wrap
  731. msgid "Setup"
  732. msgstr ""
  733. #. type: Plain text
  734. #: guix-git/doc/guix-cookbook.texi:552
  735. msgid "In the rest of this chapter we will rely on some basic Scheme programming knowledge. Now let's detail the different possible setups for working on Guix packages."
  736. msgstr ""
  737. #. type: Plain text
  738. #: guix-git/doc/guix-cookbook.texi:554
  739. msgid "There are several ways to set up a Guix packaging environment."
  740. msgstr ""
  741. #. type: Plain text
  742. #: guix-git/doc/guix-cookbook.texi:557
  743. msgid "We recommend you work directly on the Guix source checkout since it makes it easier for everyone to contribute to the project."
  744. msgstr ""
  745. #. type: Plain text
  746. #: guix-git/doc/guix-cookbook.texi:559
  747. msgid "But first, let's look at other possibilities."
  748. msgstr ""
  749. #. type: subsubsection
  750. #: guix-git/doc/guix-cookbook.texi:560 guix-git/doc/guix-cookbook.texi:561
  751. #, no-wrap
  752. msgid "Local file"
  753. msgstr ""
  754. #. type: Plain text
  755. #: guix-git/doc/guix-cookbook.texi:566
  756. msgid "This is what we previously did with @samp{my-hello}. With the Scheme basics we've covered, we are now able to explain the leading chunks. As stated in @code{guix package --help}:"
  757. msgstr ""
  758. #. type: example
  759. #: guix-git/doc/guix-cookbook.texi:571
  760. #, no-wrap
  761. msgid ""
  762. " -f, --install-from-file=FILE\n"
  763. " install the package that the code within FILE\n"
  764. " evaluates to\n"
  765. msgstr ""
  766. #. type: Plain text
  767. #: guix-git/doc/guix-cookbook.texi:575
  768. msgid "Thus the last expression @emph{must} return a package, which is the case in our earlier example."
  769. msgstr ""
  770. #. type: Plain text
  771. #: guix-git/doc/guix-cookbook.texi:579
  772. msgid "The @code{use-modules} expression tells which of the modules we need in the file. Modules are a collection of values and procedures. They are commonly called ``libraries'' or ``packages'' in other programming languages."
  773. msgstr ""
  774. #. type: node
  775. #: guix-git/doc/guix-cookbook.texi:580
  776. #, no-wrap
  777. msgid "@samp{GUIX_PACKAGE_PATH}"
  778. msgstr ""
  779. #. type: samp{#1}
  780. #: guix-git/doc/guix-cookbook.texi:581
  781. #, no-wrap
  782. msgid "GUIX_PACKAGE_PATH"
  783. msgstr ""
  784. #. type: emph{#1}
  785. #: guix-git/doc/guix-cookbook.texi:585
  786. msgid "Note: Starting from Guix 0.16, the more flexible Guix @dfn{channels} are the preferred way and supersede @samp{GUIX_PACKAGE_PATH}. See next section."
  787. msgstr ""
  788. #. type: Plain text
  789. #: guix-git/doc/guix-cookbook.texi:589
  790. msgid "It can be tedious to specify the file from the command line instead of simply calling @code{guix package --install my-hello} as you would do with the official packages."
  791. msgstr ""
  792. #. type: Plain text
  793. #: guix-git/doc/guix-cookbook.texi:592
  794. msgid "Guix makes it possible to streamline the process by adding as many ``package declaration directories'' as you want."
  795. msgstr ""
  796. #. type: Plain text
  797. #: guix-git/doc/guix-cookbook.texi:595
  798. msgid "Create a directory, say @file{~./guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH} environment variable:"
  799. msgstr ""
  800. #. type: example
  801. #: guix-git/doc/guix-cookbook.texi:599
  802. #, no-wrap
  803. msgid ""
  804. "$ mkdir ~/guix-packages\n"
  805. "$ export GUIX_PACKAGE_PATH=~/guix-packages\n"
  806. msgstr ""
  807. #. type: Plain text
  808. #: guix-git/doc/guix-cookbook.texi:602
  809. msgid "To add several directories, separate them with a colon (@code{:})."
  810. msgstr ""
  811. #. type: Plain text
  812. #: guix-git/doc/guix-cookbook.texi:604
  813. msgid "Our previous @samp{my-hello} needs some adjustments though:"
  814. msgstr ""
  815. #. type: lisp
  816. #: guix-git/doc/guix-cookbook.texi:611
  817. #, no-wrap
  818. msgid ""
  819. "(define-module (my-hello)\n"
  820. " #:use-module (guix licenses)\n"
  821. " #:use-module (guix packages)\n"
  822. " #:use-module (guix build-system gnu)\n"
  823. " #:use-module (guix download))\n"
  824. "\n"
  825. msgstr ""
  826. #. type: lisp
  827. #: guix-git/doc/guix-cookbook.texi:631
  828. #, no-wrap
  829. msgid ""
  830. "(define-public my-hello\n"
  831. " (package\n"
  832. " (name \"my-hello\")\n"
  833. " (version \"2.10\")\n"
  834. " (source (origin\n"
  835. " (method url-fetch)\n"
  836. " (uri (string-append \"mirror://gnu/hello/hello-\" version\n"
  837. " \".tar.gz\"))\n"
  838. " (sha256\n"
  839. " (base32\n"
  840. " \"0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i\"))))\n"
  841. " (build-system gnu-build-system)\n"
  842. " (synopsis \"Hello, Guix world: An example custom Guix package\")\n"
  843. " (description\n"
  844. " \"GNU Hello prints the message \\\"Hello, world!\\\" and then exits. It\n"
  845. "serves as an example of standard GNU coding practices. As such, it supports\n"
  846. "command-line arguments, multiple languages, and so on.\")\n"
  847. " (home-page \"https://www.gnu.org/software/hello/\")\n"
  848. " (license gpl3+)))\n"
  849. msgstr ""
  850. #. type: Plain text
  851. #: guix-git/doc/guix-cookbook.texi:637
  852. msgid "Note that we have assigned the package value to an exported variable name with @code{define-public}. This is effectively assigning the package to the @code{my-hello} variable so that it can be referenced, among other as dependency of other packages."
  853. msgstr ""
  854. #. type: Plain text
  855. #: guix-git/doc/guix-cookbook.texi:642
  856. msgid "If you use @code{guix package --install-from-file=my-hello.scm} on the above file, it will fail because the last expression, @code{define-public}, does not return a package. If you want to use @code{define-public} in this use-case nonetheless, make sure the file ends with an evaluation of @code{my-hello}:"
  857. msgstr ""
  858. #. type: lisp
  859. #: guix-git/doc/guix-cookbook.texi:648
  860. #, no-wrap
  861. msgid ""
  862. "; ...\n"
  863. "(define-public my-hello\n"
  864. " ; ...\n"
  865. " )\n"
  866. "\n"
  867. msgstr ""
  868. #. type: lisp
  869. #: guix-git/doc/guix-cookbook.texi:650
  870. #, no-wrap
  871. msgid "my-hello\n"
  872. msgstr ""
  873. #. type: Plain text
  874. #: guix-git/doc/guix-cookbook.texi:653
  875. msgid "This last example is not very typical."
  876. msgstr ""
  877. #. type: Plain text
  878. #: guix-git/doc/guix-cookbook.texi:656
  879. msgid "Now @samp{my-hello} should be part of the package collection like all other official packages. You can verify this with:"
  880. msgstr ""
  881. #. type: example
  882. #: guix-git/doc/guix-cookbook.texi:659
  883. #, no-wrap
  884. msgid "$ guix package --show=my-hello\n"
  885. msgstr ""
  886. #. type: subsubsection
  887. #: guix-git/doc/guix-cookbook.texi:661 guix-git/doc/guix-cookbook.texi:662
  888. #, no-wrap
  889. msgid "Guix channels"
  890. msgstr ""
  891. #. type: Plain text
  892. #: guix-git/doc/guix-cookbook.texi:668
  893. msgid "Guix 0.16 features channels, which is very similar to @samp{GUIX_PACKAGE_PATH} but provides better integration and provenance tracking. Channels are not necessarily local, they can be maintained as a public Git repository for instance. Of course, several channels can be used at the same time."
  894. msgstr ""
  895. #. type: Plain text
  896. #: guix-git/doc/guix-cookbook.texi:670
  897. msgid "@xref{Channels,,, guix, GNU Guix Reference Manual} for setup details."
  898. msgstr ""
  899. #. type: subsubsection
  900. #: guix-git/doc/guix-cookbook.texi:671 guix-git/doc/guix-cookbook.texi:672
  901. #, no-wrap
  902. msgid "Direct checkout hacking"
  903. msgstr ""
  904. #. type: Plain text
  905. #: guix-git/doc/guix-cookbook.texi:677
  906. msgid "Working directly on the Guix project is recommended: it reduces the friction when the time comes to submit your changes upstream to let the community benefit from your hard work!"
  907. msgstr ""
  908. #. type: Plain text
  909. #: guix-git/doc/guix-cookbook.texi:683
  910. msgid "Unlike most software distributions, the Guix repository holds in one place both the tooling (including the package manager) and the package definitions. This choice was made so that it would give developers the flexibility to modify the API without breakage by updating all packages at the same time. This reduces development inertia."
  911. msgstr ""
  912. #. type: Plain text
  913. #: guix-git/doc/guix-cookbook.texi:685
  914. msgid "Check out the official @uref{https://git-scm.com/, Git} repository:"
  915. msgstr ""
  916. #. type: example
  917. #: guix-git/doc/guix-cookbook.texi:688
  918. #, no-wrap
  919. msgid "$ git clone https://git.savannah.gnu.org/git/guix.git\n"
  920. msgstr ""
  921. #. type: Plain text
  922. #: guix-git/doc/guix-cookbook.texi:692
  923. msgid "In the rest of this article, we use @samp{$GUIX_CHECKOUT} to refer to the location of the checkout."
  924. msgstr ""
  925. #. type: Plain text
  926. #: guix-git/doc/guix-cookbook.texi:696
  927. msgid "Follow the instructions in the manual (@pxref{Contributing,,, guix, GNU Guix Reference Manual}) to set up the repository environment."
  928. msgstr ""
  929. #. type: Plain text
  930. #: guix-git/doc/guix-cookbook.texi:699
  931. msgid "Once ready, you should be able to use the package definitions from the repository environment."
  932. msgstr ""
  933. #. type: Plain text
  934. #: guix-git/doc/guix-cookbook.texi:701
  935. msgid "Feel free to edit package definitions found in @samp{$GUIX_CHECKOUT/gnu/packages}."
  936. msgstr ""
  937. #. type: Plain text
  938. #: guix-git/doc/guix-cookbook.texi:705
  939. msgid "The @samp{$GUIX_CHECKOUT/pre-inst-env} script lets you use @samp{guix} over the package collection of the repository (@pxref{Running Guix Before It Is Installed,,, guix, GNU Guix Reference Manual})."
  940. msgstr ""
  941. #. type: itemize
  942. #: guix-git/doc/guix-cookbook.texi:709
  943. msgid "Search packages, such as Ruby:"
  944. msgstr ""
  945. #. type: example
  946. #: guix-git/doc/guix-cookbook.texi:716
  947. #, no-wrap
  948. msgid ""
  949. " $ cd $GUIX_CHECKOUT\n"
  950. " $ ./pre-inst-env guix package --list-available=ruby\n"
  951. " ruby 1.8.7-p374 out gnu/packages/ruby.scm:119:2\n"
  952. " ruby 2.1.6 out gnu/packages/ruby.scm:91:2\n"
  953. " ruby 2.2.2 out gnu/packages/ruby.scm:39:2\n"
  954. msgstr ""
  955. #. type: itemize
  956. #: guix-git/doc/guix-cookbook.texi:720
  957. msgid "Build a package, here Ruby version 2.1:"
  958. msgstr ""
  959. #. type: example
  960. #: guix-git/doc/guix-cookbook.texi:724
  961. #, no-wrap
  962. msgid ""
  963. " $ ./pre-inst-env guix build --keep-failed ruby@@2.1\n"
  964. " /gnu/store/c13v73jxmj2nir2xjqaz5259zywsa9zi-ruby-2.1.6\n"
  965. msgstr ""
  966. #. type: itemize
  967. #: guix-git/doc/guix-cookbook.texi:728
  968. msgid "Install it to your user profile:"
  969. msgstr ""
  970. #. type: example
  971. #: guix-git/doc/guix-cookbook.texi:731
  972. #, no-wrap
  973. msgid " $ ./pre-inst-env guix package --install ruby@@2.1\n"
  974. msgstr ""
  975. #. type: itemize
  976. #: guix-git/doc/guix-cookbook.texi:735
  977. msgid "Check for common mistakes:"
  978. msgstr ""
  979. #. type: example
  980. #: guix-git/doc/guix-cookbook.texi:738
  981. #, no-wrap
  982. msgid " $ ./pre-inst-env guix lint ruby@@2.1\n"
  983. msgstr ""
  984. #. type: Plain text
  985. #: guix-git/doc/guix-cookbook.texi:743
  986. msgid "Guix strives at maintaining a high packaging standard; when contributing to the Guix project, remember to"
  987. msgstr ""
  988. #. type: itemize
  989. #: guix-git/doc/guix-cookbook.texi:747
  990. msgid "follow the coding style (@pxref{Coding Style,,, guix, GNU Guix Reference Manual}),"
  991. msgstr ""
  992. #. type: itemize
  993. #: guix-git/doc/guix-cookbook.texi:749
  994. msgid "and review the check list from the manual (@pxref{Submitting Patches,,, guix, GNU Guix Reference Manual})."
  995. msgstr ""
  996. #. type: Plain text
  997. #: guix-git/doc/guix-cookbook.texi:753
  998. msgid "Once you are happy with the result, you are welcome to send your contribution to make it part of Guix. This process is also detailed in the manual. (@pxref{Contributing,,, guix, GNU Guix Reference Manual})"
  999. msgstr ""
  1000. #. type: Plain text
  1001. #: guix-git/doc/guix-cookbook.texi:756
  1002. msgid "It's a community effort so the more join in, the better Guix becomes!"
  1003. msgstr ""
  1004. #. type: subsection
  1005. #: guix-git/doc/guix-cookbook.texi:757 guix-git/doc/guix-cookbook.texi:758
  1006. #, no-wrap
  1007. msgid "Extended example"
  1008. msgstr ""
  1009. #. type: Plain text
  1010. #: guix-git/doc/guix-cookbook.texi:763
  1011. msgid "The above ``Hello World'' example is as simple as it goes. Packages can be more complex than that and Guix can handle more advanced scenarios. Let's look at another, more sophisticated package (slightly modified from the source):"
  1012. msgstr ""
  1013. #. type: lisp
  1014. #: guix-git/doc/guix-cookbook.texi:777
  1015. #, no-wrap
  1016. msgid ""
  1017. "(define-module (gnu packages version-control)\n"
  1018. " #:use-module ((guix licenses) #:prefix license:)\n"
  1019. " #:use-module (guix utils)\n"
  1020. " #:use-module (guix packages)\n"
  1021. " #:use-module (guix git-download)\n"
  1022. " #:use-module (guix build-system cmake)\n"
  1023. " #:use-module (gnu packages ssh)\n"
  1024. " #:use-module (gnu packages web)\n"
  1025. " #:use-module (gnu packages pkg-config)\n"
  1026. " #:use-module (gnu packages python)\n"
  1027. " #:use-module (gnu packages compression)\n"
  1028. " #:use-module (gnu packages tls))\n"
  1029. "\n"
  1030. msgstr ""
  1031. #. type: lisp
  1032. #: guix-git/doc/guix-cookbook.texi:837
  1033. #, no-wrap
  1034. msgid ""
  1035. "(define-public my-libgit2\n"
  1036. " (let ((commit \"e98d0a37c93574d2c6107bf7f31140b548c6a7bf\")\n"
  1037. " (revision \"1\"))\n"
  1038. " (package\n"
  1039. " (name \"my-libgit2\")\n"
  1040. " (version (git-version \"0.26.6\" revision commit))\n"
  1041. " (source (origin\n"
  1042. " (method git-fetch)\n"
  1043. " (uri (git-reference\n"
  1044. " (url \"https://github.com/libgit2/libgit2/\")\n"
  1045. " (commit commit)))\n"
  1046. " (file-name (git-file-name name version))\n"
  1047. " (sha256\n"
  1048. " (base32\n"
  1049. " \"17pjvprmdrx4h6bb1hhc98w9qi6ki7yl57f090n9kbhswxqfs7s3\"))\n"
  1050. " (patches (search-patches \"libgit2-mtime-0.patch\"))\n"
  1051. " (modules '((guix build utils)))\n"
  1052. " (snippet '(begin\n"
  1053. " ;; Remove bundled software.\n"
  1054. " (delete-file-recursively \"deps\")\n"
  1055. " #true))))\n"
  1056. " (build-system cmake-build-system)\n"
  1057. " (outputs '(\"out\" \"debug\"))\n"
  1058. " (arguments\n"
  1059. " `(#:tests? #true ; Run the test suite (this is the default)\n"
  1060. " #:configure-flags '(\"-DUSE_SHA1DC=ON\") ; SHA-1 collision detection\n"
  1061. " #:phases\n"
  1062. " (modify-phases %standard-phases\n"
  1063. " (add-after 'unpack 'fix-hardcoded-paths\n"
  1064. " (lambda _\n"
  1065. " (substitute* \"tests/repo/init.c\"\n"
  1066. " ((\"#!/bin/sh\") (string-append \"#!\" (which \"sh\"))))\n"
  1067. " (substitute* \"tests/clar/fs.h\"\n"
  1068. " ((\"/bin/cp\") (which \"cp\"))\n"
  1069. " ((\"/bin/rm\") (which \"rm\")))\n"
  1070. " #true))\n"
  1071. " ;; Run checks more verbosely.\n"
  1072. " (replace 'check\n"
  1073. " (lambda _ (invoke \"./libgit2_clar\" \"-v\" \"-Q\")))\n"
  1074. " (add-after 'unpack 'make-files-writable-for-tests\n"
  1075. " (lambda _ (for-each make-file-writable (find-files \".\" \".*\")))))))\n"
  1076. " (inputs\n"
  1077. " `((\"libssh2\" ,libssh2)\n"
  1078. " (\"http-parser\" ,http-parser)\n"
  1079. " (\"python\" ,python-wrapper)))\n"
  1080. " (native-inputs\n"
  1081. " `((\"pkg-config\" ,pkg-config)))\n"
  1082. " (propagated-inputs\n"
  1083. " ;; These two libraries are in 'Requires.private' in libgit2.pc.\n"
  1084. " `((\"openssl\" ,openssl)\n"
  1085. " (\"zlib\" ,zlib)))\n"
  1086. " (home-page \"https://libgit2.github.com/\")\n"
  1087. " (synopsis \"Library providing Git core methods\")\n"
  1088. " (description\n"
  1089. " \"Libgit2 is a portable, pure C implementation of the Git core methods\n"
  1090. "provided as a re-entrant linkable library with a solid API, allowing you to\n"
  1091. "write native speed custom Git applications in any language with bindings.\")\n"
  1092. " ;; GPLv2 with linking exception\n"
  1093. " (license license:gpl2))))\n"
  1094. msgstr ""
  1095. #. type: Plain text
  1096. #: guix-git/doc/guix-cookbook.texi:842
  1097. msgid "(In those cases were you only want to tweak a few fields from a package definition, you should rely on inheritance instead of copy-pasting everything. See below.)"
  1098. msgstr ""
  1099. #. type: Plain text
  1100. #: guix-git/doc/guix-cookbook.texi:844
  1101. msgid "Let's discuss those fields in depth."
  1102. msgstr ""
  1103. #. type: subsubsection
  1104. #: guix-git/doc/guix-cookbook.texi:845
  1105. #, no-wrap
  1106. msgid "@code{git-fetch} method"
  1107. msgstr ""
  1108. #. type: Plain text
  1109. #: guix-git/doc/guix-cookbook.texi:852
  1110. msgid "Unlike the @code{url-fetch} method, @code{git-fetch} expects a @code{git-reference} which takes a Git repository and a commit. The commit can be any Git reference such as tags, so if the @code{version} is tagged, then it can be used directly. Sometimes the tag is prefixed with a @code{v}, in which case you'd use @code{(commit (string-append \"v\" version))}."
  1111. msgstr ""
  1112. #. type: Plain text
  1113. #: guix-git/doc/guix-cookbook.texi:856
  1114. msgid "To ensure that the source code from the Git repository is stored in a directory with a descriptive name, we use @code{(file-name (git-file-name name version))}."
  1115. msgstr ""
  1116. #. type: Plain text
  1117. #: guix-git/doc/guix-cookbook.texi:861
  1118. msgid "The @code{git-version} procedure can be used to derive the version when packaging programs for a specific commit, following the Guix contributor guidelines (@pxref{Version Numbers,,, guix, GNU Guix Reference Manual})."
  1119. msgstr ""
  1120. #. type: Plain text
  1121. #: guix-git/doc/guix-cookbook.texi:865
  1122. msgid "How does one obtain the @code{sha256} hash that's in there, you ask? By invoking @command{guix hash} on a checkout of the desired commit, along these lines:"
  1123. msgstr ""
  1124. #. type: example
  1125. #: guix-git/doc/guix-cookbook.texi:871
  1126. #, no-wrap
  1127. msgid ""
  1128. "git clone https://github.com/libgit2/libgit2/\n"
  1129. "cd libgit2\n"
  1130. "git checkout v0.26.6\n"
  1131. "guix hash -rx .\n"
  1132. msgstr ""
  1133. #. type: Plain text
  1134. #: guix-git/doc/guix-cookbook.texi:876
  1135. msgid "@command{guix hash -rx} computes a SHA256 hash over the whole directory, excluding the @file{.git} sub-directory (@pxref{Invoking guix hash,,, guix, GNU Guix Reference Manual})."
  1136. msgstr ""
  1137. #. type: Plain text
  1138. #: guix-git/doc/guix-cookbook.texi:879
  1139. msgid "In the future, @command{guix download} will hopefully be able to do these steps for you, just like it does for regular downloads."
  1140. msgstr ""
  1141. #. type: subsubsection
  1142. #: guix-git/doc/guix-cookbook.texi:880
  1143. #, no-wrap
  1144. msgid "Snippets"
  1145. msgstr ""
  1146. #. type: Plain text
  1147. #: guix-git/doc/guix-cookbook.texi:886
  1148. msgid "Snippets are quoted (i.e. non-evaluated) Scheme code that are a means of patching the source. They are a Guix-y alternative to the traditional @file{.patch} files. Because of the quote, the code in only evaluated when passed to the Guix daemon for building. There can be as many snippets as needed."
  1149. msgstr ""
  1150. #. type: Plain text
  1151. #: guix-git/doc/guix-cookbook.texi:889
  1152. msgid "Snippets might need additional Guile modules which can be imported from the @code{modules} field."
  1153. msgstr ""
  1154. #. type: subsubsection
  1155. #: guix-git/doc/guix-cookbook.texi:890
  1156. #, no-wrap
  1157. msgid "Inputs"
  1158. msgstr ""
  1159. #. type: Plain text
  1160. #: guix-git/doc/guix-cookbook.texi:893
  1161. msgid "First, a syntactic comment: See the quasi-quote / comma syntax?"
  1162. msgstr ""
  1163. #. type: lisp
  1164. #: guix-git/doc/guix-cookbook.texi:897
  1165. #, no-wrap
  1166. msgid ""
  1167. " (native-inputs\n"
  1168. " `((\"pkg-config\" ,pkg-config)))\n"
  1169. msgstr ""
  1170. #. type: Plain text
  1171. #: guix-git/doc/guix-cookbook.texi:900
  1172. msgid "is equivalent to"
  1173. msgstr ""
  1174. #. type: lisp
  1175. #: guix-git/doc/guix-cookbook.texi:904
  1176. #, no-wrap
  1177. msgid ""
  1178. " (native-inputs\n"
  1179. " (list (list \"pkg-config\" pkg-config)))\n"
  1180. msgstr ""
  1181. #. type: Plain text
  1182. #: guix-git/doc/guix-cookbook.texi:907
  1183. msgid "You'll mostly see the former because it's shorter."
  1184. msgstr ""
  1185. #. type: Plain text
  1186. #: guix-git/doc/guix-cookbook.texi:909
  1187. msgid "There are 3 different input types. In short:"
  1188. msgstr ""
  1189. #. type: item
  1190. #: guix-git/doc/guix-cookbook.texi:911
  1191. #, no-wrap
  1192. msgid "native-inputs"
  1193. msgstr ""
  1194. #. type: table
  1195. #: guix-git/doc/guix-cookbook.texi:914
  1196. msgid "Required for building but not runtime -- installing a package through a substitute won't install these inputs."
  1197. msgstr ""
  1198. #. type: item
  1199. #: guix-git/doc/guix-cookbook.texi:914
  1200. #, no-wrap
  1201. msgid "inputs"
  1202. msgstr ""
  1203. #. type: table
  1204. #: guix-git/doc/guix-cookbook.texi:917
  1205. msgid "Installed in the store but not in the profile, as well as being present at build time."
  1206. msgstr ""
  1207. #. type: item
  1208. #: guix-git/doc/guix-cookbook.texi:917
  1209. #, no-wrap
  1210. msgid "propagated-inputs"
  1211. msgstr ""
  1212. #. type: table
  1213. #: guix-git/doc/guix-cookbook.texi:920
  1214. msgid "Installed in the store and in the profile, as well as being present at build time."
  1215. msgstr ""
  1216. #. type: Plain text
  1217. #: guix-git/doc/guix-cookbook.texi:923
  1218. msgid "@xref{Package Reference,,, guix, GNU Guix Reference Manual} for more details."
  1219. msgstr ""
  1220. #. type: Plain text
  1221. #: guix-git/doc/guix-cookbook.texi:927
  1222. msgid "The distinction between the various inputs is important: if a dependency can be handled as an @emph{input} instead of a @emph{propagated input}, it should be done so, or else it ``pollutes'' the user profile for no good reason."
  1223. msgstr ""
  1224. #. type: Plain text
  1225. #: guix-git/doc/guix-cookbook.texi:934
  1226. msgid "For instance, a user installing a graphical program that depends on a command line tool might only be interested in the graphical part, so there is no need to force the command line tool into the user profile. The dependency is a concern to the package, not to the user. @emph{Inputs} make it possible to handle dependencies without bugging the user by adding undesired executable files (or libraries) to their profile."
  1227. msgstr ""
  1228. #. type: Plain text
  1229. #: guix-git/doc/guix-cookbook.texi:940
  1230. msgid "Same goes for @emph{native-inputs}: once the program is installed, build-time dependencies can be safely garbage-collected. It also matters when a substitute is available, in which case only the @emph{inputs} and @emph{propagated inputs} will be fetched: the @emph{native inputs} are not required to install a package from a substitute."
  1231. msgstr ""
  1232. #. type: subsubsection
  1233. #: guix-git/doc/guix-cookbook.texi:941
  1234. #, no-wrap
  1235. msgid "Outputs"
  1236. msgstr ""
  1237. #. type: Plain text
  1238. #: guix-git/doc/guix-cookbook.texi:945
  1239. msgid "Just like how a package can have multiple inputs, it can also produce multiple outputs."
  1240. msgstr ""
  1241. #. type: Plain text
  1242. #: guix-git/doc/guix-cookbook.texi:947
  1243. msgid "Each output corresponds to a separate directory in the store."
  1244. msgstr ""
  1245. #. type: Plain text
  1246. #: guix-git/doc/guix-cookbook.texi:950
  1247. msgid "The user can choose which output to install; this is useful to save space or to avoid polluting the user profile with unwanted executables or libraries."
  1248. msgstr ""
  1249. #. type: Plain text
  1250. #: guix-git/doc/guix-cookbook.texi:953
  1251. msgid "Output separation is optional. When the @code{outputs} field is left out, the default and only output (the complete package) is referred to as @code{\"out\"}."
  1252. msgstr ""
  1253. #. type: Plain text
  1254. #: guix-git/doc/guix-cookbook.texi:955
  1255. msgid "Typical separate output names include @code{debug} and @code{doc}."
  1256. msgstr ""
  1257. #. type: Plain text
  1258. #: guix-git/doc/guix-cookbook.texi:959
  1259. msgid "It's advised to separate outputs only when you've shown it's worth it: if the output size is significant (compare with @code{guix size}) or in case the package is modular."
  1260. msgstr ""
  1261. #. type: subsubsection
  1262. #: guix-git/doc/guix-cookbook.texi:960
  1263. #, no-wrap
  1264. msgid "Build system arguments"
  1265. msgstr ""
  1266. #. type: Plain text
  1267. #: guix-git/doc/guix-cookbook.texi:963
  1268. msgid "The @code{arguments} is a keyword-value list used to configure the build process."
  1269. msgstr ""
  1270. #. type: Plain text
  1271. #: guix-git/doc/guix-cookbook.texi:968
  1272. msgid "The simplest argument @code{#:tests?} can be used to disable the test suite when building the package. This is mostly useful when the package does not feature any test suite. It's strongly recommended to keep the test suite on if there is one."
  1273. msgstr ""
  1274. #. type: Plain text
  1275. #: guix-git/doc/guix-cookbook.texi:972
  1276. msgid "Another common argument is @code{:make-flags}, which specifies a list of flags to append when running make, as you would from the command line. For instance, the following flags"
  1277. msgstr ""
  1278. #. type: lisp
  1279. #: guix-git/doc/guix-cookbook.texi:976
  1280. #, no-wrap
  1281. msgid ""
  1282. "#:make-flags (list (string-append \"prefix=\" (assoc-ref %outputs \"out\"))\n"
  1283. " \"CC=gcc\")\n"
  1284. msgstr ""
  1285. #. type: Plain text
  1286. #: guix-git/doc/guix-cookbook.texi:979
  1287. msgid "translate into"
  1288. msgstr ""
  1289. #. type: example
  1290. #: guix-git/doc/guix-cookbook.texi:982
  1291. #, no-wrap
  1292. msgid "$ make CC=gcc prefix=/gnu/store/...-<out>\n"
  1293. msgstr ""
  1294. #. type: Plain text
  1295. #: guix-git/doc/guix-cookbook.texi:988
  1296. msgid "This sets the C compiler to @code{gcc} and the @code{prefix} variable (the installation directory in Make parlance) to @code{(assoc-ref %outputs \"out\")}, which is a build-stage global variable pointing to the destination directory in the store (something like @file{/gnu/store/...-my-libgit2-20180408})."
  1297. msgstr ""
  1298. #. type: Plain text
  1299. #: guix-git/doc/guix-cookbook.texi:990
  1300. msgid "Similarly, it's possible to set the configure flags:"
  1301. msgstr ""
  1302. #. type: lisp
  1303. #: guix-git/doc/guix-cookbook.texi:993
  1304. #, no-wrap
  1305. msgid "#:configure-flags '(\"-DUSE_SHA1DC=ON\")\n"
  1306. msgstr ""
  1307. #. type: Plain text
  1308. #: guix-git/doc/guix-cookbook.texi:997
  1309. msgid "The @code{%build-inputs} variable is also generated in scope. It's an association table that maps the input names to their store directories."
  1310. msgstr ""
  1311. #. type: Plain text
  1312. #: guix-git/doc/guix-cookbook.texi:1002
  1313. msgid "The @code{phases} keyword lists the sequential steps of the build system. Typically phases include @code{unpack}, @code{configure}, @code{build}, @code{install} and @code{check}. To know more about those phases, you need to work out the appropriate build system definition in @samp{$GUIX_CHECKOUT/guix/build/gnu-build-system.scm}:"
  1314. msgstr ""
  1315. #. type: lisp
  1316. #: guix-git/doc/guix-cookbook.texi:1021
  1317. #, no-wrap
  1318. msgid ""
  1319. "(define %standard-phases\n"
  1320. " ;; Standard build phases, as a list of symbol/procedure pairs.\n"
  1321. " (let-syntax ((phases (syntax-rules ()\n"
  1322. " ((_ p ...) `((p . ,p) ...)))))\n"
  1323. " (phases set-SOURCE-DATE-EPOCH set-paths install-locale unpack\n"
  1324. " bootstrap\n"
  1325. " patch-usr-bin-file\n"
  1326. " patch-source-shebangs configure patch-generated-file-shebangs\n"
  1327. " build check install\n"
  1328. " patch-shebangs strip\n"
  1329. " validate-runpath\n"
  1330. " validate-documentation-location\n"
  1331. " delete-info-dir-file\n"
  1332. " patch-dot-desktop-files\n"
  1333. " install-license-files\n"
  1334. " reset-gzip-timestamps\n"
  1335. " compress-documentation)))\n"
  1336. msgstr ""
  1337. #. type: Plain text
  1338. #: guix-git/doc/guix-cookbook.texi:1024
  1339. msgid "Or from the REPL:"
  1340. msgstr ""
  1341. #. type: lisp
  1342. #: guix-git/doc/guix-cookbook.texi:1030
  1343. #, no-wrap
  1344. msgid ""
  1345. "(add-to-load-path \"/path/to/guix/checkout\")\n"
  1346. ",use (guix build gnu-build-system)\n"
  1347. "(map first %standard-phases)\n"
  1348. "@result{} (set-SOURCE-DATE-EPOCH set-paths install-locale unpack bootstrap patch-usr-bin-file patch-source-shebangs configure patch-generated-file-shebangs build check install patch-shebangs strip validate-runpath validate-documentation-location delete-info-dir-file patch-dot-desktop-files install-license-files reset-gzip-timestamps compress-documentation)\n"
  1349. msgstr ""
  1350. #. type: Plain text
  1351. #: guix-git/doc/guix-cookbook.texi:1034
  1352. msgid "If you want to know more about what happens during those phases, consult the associated procedures."
  1353. msgstr ""
  1354. #. type: Plain text
  1355. #: guix-git/doc/guix-cookbook.texi:1037
  1356. msgid "For instance, as of this writing the definition of @code{unpack} for the GNU build system is:"
  1357. msgstr ""
  1358. #. type: lisp
  1359. #: guix-git/doc/guix-cookbook.texi:1047
  1360. #, no-wrap
  1361. msgid ""
  1362. "(define* (unpack #:key source #:allow-other-keys)\n"
  1363. " \"Unpack SOURCE in the working directory, and change directory within the\n"
  1364. "source. When SOURCE is a directory, copy it in a sub-directory of the current\n"
  1365. "working directory.\"\n"
  1366. " (if (file-is-directory? source)\n"
  1367. " (begin\n"
  1368. " (mkdir \"source\")\n"
  1369. " (chdir \"source\")\n"
  1370. "\n"
  1371. msgstr ""
  1372. #. type: lisp
  1373. #: guix-git/doc/guix-cookbook.texi:1058
  1374. #, no-wrap
  1375. msgid ""
  1376. " ;; Preserve timestamps (set to the Epoch) on the copied tree so that\n"
  1377. " ;; things work deterministically.\n"
  1378. " (copy-recursively source \".\"\n"
  1379. " #:keep-mtime? #true))\n"
  1380. " (begin\n"
  1381. " (if (string-suffix? \".zip\" source)\n"
  1382. " (invoke \"unzip\" source)\n"
  1383. " (invoke \"tar\" \"xvf\" source))\n"
  1384. " (chdir (first-subdirectory \".\"))))\n"
  1385. " #true)\n"
  1386. msgstr ""
  1387. #. type: Plain text
  1388. #: guix-git/doc/guix-cookbook.texi:1066
  1389. msgid "Note the @code{chdir} call: it changes the working directory to where the source was unpacked. Thus every phase following the @code{unpack} will use the source as a working directory, which is why we can directly work on the source files. That is to say, unless a later phase changes the working directory to something else."
  1390. msgstr ""
  1391. #. type: Plain text
  1392. #: guix-git/doc/guix-cookbook.texi:1070
  1393. msgid "We modify the list of @code{%standard-phases} of the build system with the @code{modify-phases} macro as per the list of specified modifications, which may have the following forms:"
  1394. msgstr ""
  1395. #. type: itemize
  1396. #: guix-git/doc/guix-cookbook.texi:1074
  1397. msgid "@code{(add-before @var{phase} @var{new-phase} @var{procedure})}: Run @var{procedure} named @var{new-phase} before @var{phase}."
  1398. msgstr ""
  1399. #. type: itemize
  1400. #: guix-git/doc/guix-cookbook.texi:1076
  1401. msgid "@code{(add-after @var{phase} @var{new-phase} @var{procedure})}: Same, but afterwards."
  1402. msgstr ""
  1403. #. type: itemize
  1404. #: guix-git/doc/guix-cookbook.texi:1078
  1405. msgid "@code{(replace @var{phase} @var{procedure})}."
  1406. msgstr ""
  1407. #. type: itemize
  1408. #: guix-git/doc/guix-cookbook.texi:1080
  1409. msgid "@code{(delete @var{phase})}."
  1410. msgstr ""
  1411. #. type: Plain text
  1412. #: guix-git/doc/guix-cookbook.texi:1087
  1413. msgid "The @var{procedure} supports the keyword arguments @code{inputs} and @code{outputs}. Each input (whether @emph{native}, @emph{propagated} or not) and output directory is referenced by their name in those variables. Thus @code{(assoc-ref outputs \"out\")} is the store directory of the main output of the package. A phase procedure may look like this:"
  1414. msgstr ""
  1415. #. type: lisp
  1416. #: guix-git/doc/guix-cookbook.texi:1095
  1417. #, no-wrap
  1418. msgid ""
  1419. "(lambda* (#:key inputs outputs #:allow-other-keys)\n"
  1420. " (let ((bash-directory (assoc-ref inputs \"bash\"))\n"
  1421. " (output-directory (assoc-ref outputs \"out\"))\n"
  1422. " (doc-directory (assoc-ref outputs \"doc\")))\n"
  1423. " ;; ...\n"
  1424. " #true))\n"
  1425. msgstr ""
  1426. #. type: Plain text
  1427. #: guix-git/doc/guix-cookbook.texi:1101
  1428. msgid "The procedure must return @code{#true} on success. It's brittle to rely on the return value of the last expression used to tweak the phase because there is no guarantee it would be a @code{#true}. Hence the trailing @code{#true} to ensure the right value is returned on success."
  1429. msgstr ""
  1430. #. type: subsubsection
  1431. #: guix-git/doc/guix-cookbook.texi:1102
  1432. #, no-wrap
  1433. msgid "Code staging"
  1434. msgstr ""
  1435. #. type: Plain text
  1436. #: guix-git/doc/guix-cookbook.texi:1108
  1437. msgid "The astute reader may have noticed the quasi-quote and comma syntax in the argument field. Indeed, the build code in the package declaration should not be evaluated on the client side, but only when passed to the Guix daemon. This mechanism of passing code around two running processes is called @uref{https://arxiv.org/abs/1709.00833, code staging}."
  1438. msgstr ""
  1439. #. type: subsubsection
  1440. #: guix-git/doc/guix-cookbook.texi:1109
  1441. #, no-wrap
  1442. msgid "Utility functions"
  1443. msgstr ""
  1444. #. type: Plain text
  1445. #: guix-git/doc/guix-cookbook.texi:1114
  1446. msgid "When customizing @code{phases}, we often need to write code that mimics the equivalent system invocations (@code{make}, @code{mkdir}, @code{cp}, etc.)@: commonly used during regular ``Unix-style'' installations."
  1447. msgstr ""
  1448. #. type: Plain text
  1449. #: guix-git/doc/guix-cookbook.texi:1117
  1450. msgid "Some like @code{chmod} are native to Guile. @xref{,,, guile, Guile reference manual} for a complete list."
  1451. msgstr ""
  1452. #. type: Plain text
  1453. #: guix-git/doc/guix-cookbook.texi:1120
  1454. msgid "Guix provides additional helper functions which prove especially handy in the context of package management."
  1455. msgstr ""
  1456. #. type: Plain text
  1457. #: guix-git/doc/guix-cookbook.texi:1124
  1458. msgid "Some of those functions can be found in @samp{$GUIX_CHECKOUT/guix/guix/build/utils.scm}. Most of them mirror the behaviour of the traditional Unix system commands:"
  1459. msgstr ""
  1460. #. type: item
  1461. #: guix-git/doc/guix-cookbook.texi:1126
  1462. #, no-wrap
  1463. msgid "which"
  1464. msgstr ""
  1465. #. type: table
  1466. #: guix-git/doc/guix-cookbook.texi:1128
  1467. msgid "Like the @samp{which} system command."
  1468. msgstr ""
  1469. #. type: item
  1470. #: guix-git/doc/guix-cookbook.texi:1128
  1471. #, no-wrap
  1472. msgid "find-files"
  1473. msgstr ""
  1474. #. type: table
  1475. #: guix-git/doc/guix-cookbook.texi:1130
  1476. msgid "Akin to the @samp{find} system command."
  1477. msgstr ""
  1478. #. type: item
  1479. #: guix-git/doc/guix-cookbook.texi:1130
  1480. #, no-wrap
  1481. msgid "mkdir-p"
  1482. msgstr ""
  1483. #. type: table
  1484. #: guix-git/doc/guix-cookbook.texi:1132
  1485. msgid "Like @samp{mkdir -p}, which creates all parents as needed."
  1486. msgstr ""
  1487. #. type: item
  1488. #: guix-git/doc/guix-cookbook.texi:1132
  1489. #, no-wrap
  1490. msgid "install-file"
  1491. msgstr ""
  1492. #. type: table
  1493. #: guix-git/doc/guix-cookbook.texi:1136
  1494. msgid "Similar to @samp{install} when installing a file to a (possibly non-existing) directory. Guile has @code{copy-file} which works like @samp{cp}."
  1495. msgstr ""
  1496. #. type: item
  1497. #: guix-git/doc/guix-cookbook.texi:1136
  1498. #, no-wrap
  1499. msgid "copy-recursively"
  1500. msgstr ""
  1501. #. type: table
  1502. #: guix-git/doc/guix-cookbook.texi:1138
  1503. msgid "Like @samp{cp -r}."
  1504. msgstr ""
  1505. #. type: item
  1506. #: guix-git/doc/guix-cookbook.texi:1138
  1507. #, no-wrap
  1508. msgid "delete-file-recursively"
  1509. msgstr ""
  1510. #. type: table
  1511. #: guix-git/doc/guix-cookbook.texi:1140
  1512. msgid "Like @samp{rm -rf}."
  1513. msgstr ""
  1514. #. type: item
  1515. #: guix-git/doc/guix-cookbook.texi:1140
  1516. #, no-wrap
  1517. msgid "invoke"
  1518. msgstr ""
  1519. #. type: table
  1520. #: guix-git/doc/guix-cookbook.texi:1142
  1521. msgid "Run an executable. This should be used instead of @code{system*}."
  1522. msgstr ""
  1523. #. type: item
  1524. #: guix-git/doc/guix-cookbook.texi:1142
  1525. #, no-wrap
  1526. msgid "with-directory-excursion"
  1527. msgstr ""
  1528. #. type: table
  1529. #: guix-git/doc/guix-cookbook.texi:1145
  1530. msgid "Run the body in a different working directory, then restore the previous working directory."
  1531. msgstr ""
  1532. #. type: item
  1533. #: guix-git/doc/guix-cookbook.texi:1145
  1534. #, no-wrap
  1535. msgid "substitute*"
  1536. msgstr ""
  1537. #. type: table
  1538. #: guix-git/doc/guix-cookbook.texi:1147
  1539. msgid "A ``@command{sed}-like'' function."
  1540. msgstr ""
  1541. #. type: Plain text
  1542. #: guix-git/doc/guix-cookbook.texi:1151
  1543. msgid "@xref{Build Utilities,,, guix, GNU Guix Reference Manual}, for more information on these utilities."
  1544. msgstr ""
  1545. #. type: subsubsection
  1546. #: guix-git/doc/guix-cookbook.texi:1152
  1547. #, no-wrap
  1548. msgid "Module prefix"
  1549. msgstr ""
  1550. #. type: Plain text
  1551. #: guix-git/doc/guix-cookbook.texi:1162
  1552. msgid "The license in our last example needs a prefix: this is because of how the @code{license} module was imported in the package, as @code{#:use-module ((guix licenses) #:prefix license:)}. The Guile module import mechanism (@pxref{Using Guile Modules,,, guile, Guile reference manual}) gives the user full control over namespacing: this is needed to avoid clashes between, say, the @samp{zlib} variable from @samp{licenses.scm} (a @emph{license} value) and the @samp{zlib} variable from @samp{compression.scm} (a @emph{package} value)."
  1553. msgstr ""
  1554. #. type: subsection
  1555. #: guix-git/doc/guix-cookbook.texi:1163 guix-git/doc/guix-cookbook.texi:1164
  1556. #, no-wrap
  1557. msgid "Other build systems"
  1558. msgstr ""
  1559. #. type: Plain text
  1560. #: guix-git/doc/guix-cookbook.texi:1171
  1561. msgid "What we've seen so far covers the majority of packages using a build system other than the @code{trivial-build-system}. The latter does not automate anything and leaves you to build everything manually. This can be more demanding and we won't cover it here for now, but thankfully it is rarely necessary to fall back on this system."
  1562. msgstr ""
  1563. #. type: Plain text
  1564. #: guix-git/doc/guix-cookbook.texi:1175
  1565. msgid "For the other build systems, such as ASDF, Emacs, Perl, Ruby and many more, the process is very similar to the GNU build system except for a few specialized arguments."
  1566. msgstr ""
  1567. #. type: Plain text
  1568. #: guix-git/doc/guix-cookbook.texi:1180
  1569. msgid "@xref{Build Systems,,, guix, GNU Guix Reference Manual}, for more information on build systems, or check the source code in the @samp{$GUIX_CHECKOUT/guix/build} and @samp{$GUIX_CHECKOUT/guix/build-system} directories."
  1570. msgstr ""
  1571. #. type: subsection
  1572. #: guix-git/doc/guix-cookbook.texi:1181 guix-git/doc/guix-cookbook.texi:1182
  1573. #, no-wrap
  1574. msgid "Programmable and automated package definition"
  1575. msgstr ""
  1576. #. type: Plain text
  1577. #: guix-git/doc/guix-cookbook.texi:1186
  1578. msgid "We can't repeat it enough: having a full-fledged programming language at hand empowers us in ways that reach far beyond traditional package management."
  1579. msgstr ""
  1580. #. type: Plain text
  1581. #: guix-git/doc/guix-cookbook.texi:1188
  1582. msgid "Let's illustrate this with some awesome features of Guix!"
  1583. msgstr ""
  1584. #. type: subsubsection
  1585. #: guix-git/doc/guix-cookbook.texi:1189 guix-git/doc/guix-cookbook.texi:1190
  1586. #, no-wrap
  1587. msgid "Recursive importers"
  1588. msgstr ""
  1589. #. type: Plain text
  1590. #: guix-git/doc/guix-cookbook.texi:1197
  1591. msgid "You might find some build systems good enough that there is little to do at all to write a package, to the point that it becomes repetitive and tedious after a while. A @emph{raison d'être} of computers is to replace human beings at those boring tasks. So let's tell Guix to do this for us and create the package definition of an R package from CRAN (the output is trimmed for conciseness):"
  1592. msgstr ""
  1593. #. type: example
  1594. #: guix-git/doc/guix-cookbook.texi:1200
  1595. #, no-wrap
  1596. msgid ""
  1597. "$ guix import cran --recursive walrus\n"
  1598. "\n"
  1599. msgstr ""
  1600. #. type: example
  1601. #: guix-git/doc/guix-cookbook.texi:1204
  1602. #, no-wrap
  1603. msgid ""
  1604. "(define-public r-mc2d\n"
  1605. " ; ...\n"
  1606. " (license gpl2+)))\n"
  1607. "\n"
  1608. msgstr ""
  1609. #. type: example
  1610. #: guix-git/doc/guix-cookbook.texi:1208
  1611. #, no-wrap
  1612. msgid ""
  1613. "(define-public r-jmvcore\n"
  1614. " ; ...\n"
  1615. " (license gpl2+)))\n"
  1616. "\n"
  1617. msgstr ""
  1618. #. type: example
  1619. #: guix-git/doc/guix-cookbook.texi:1212
  1620. #, no-wrap
  1621. msgid ""
  1622. "(define-public r-wrs2\n"
  1623. " ; ...\n"
  1624. " (license gpl3)))\n"
  1625. "\n"
  1626. msgstr ""
  1627. #. type: example
  1628. #: guix-git/doc/guix-cookbook.texi:1241
  1629. #, no-wrap
  1630. msgid ""
  1631. "(define-public r-walrus\n"
  1632. " (package\n"
  1633. " (name \"r-walrus\")\n"
  1634. " (version \"1.0.3\")\n"
  1635. " (source\n"
  1636. " (origin\n"
  1637. " (method url-fetch)\n"
  1638. " (uri (cran-uri \"walrus\" version))\n"
  1639. " (sha256\n"
  1640. " (base32\n"
  1641. " \"1nk2glcvy4hyksl5ipq2mz8jy4fss90hx6cq98m3w96kzjni6jjj\"))))\n"
  1642. " (build-system r-build-system)\n"
  1643. " (propagated-inputs\n"
  1644. " `((\"r-ggplot2\" ,r-ggplot2)\n"
  1645. " (\"r-jmvcore\" ,r-jmvcore)\n"
  1646. " (\"r-r6\" ,r-r6)\n"
  1647. " (\"r-wrs2\" ,r-wrs2)))\n"
  1648. " (home-page \"https://github.com/jamovi/walrus\")\n"
  1649. " (synopsis \"Robust Statistical Methods\")\n"
  1650. " (description\n"
  1651. " \"This package provides a toolbox of common robust statistical\n"
  1652. "tests, including robust descriptives, robust t-tests, and robust ANOVA.\n"
  1653. "It is also available as a module for 'jamovi' (see\n"
  1654. "<https://www.jamovi.org> for more information). Walrus is based on the\n"
  1655. "WRS2 package by Patrick Mair, which is in turn based on the scripts and\n"
  1656. "work of Rand Wilcox. These analyses are described in depth in the book\n"
  1657. "'Introduction to Robust Estimation & Hypothesis Testing'.\")\n"
  1658. " (license gpl3)))\n"
  1659. msgstr ""
  1660. #. type: Plain text
  1661. #: guix-git/doc/guix-cookbook.texi:1245
  1662. msgid "The recursive importer won't import packages for which Guix already has package definitions, except for the very first."
  1663. msgstr ""
  1664. #. type: Plain text
  1665. #: guix-git/doc/guix-cookbook.texi:1250
  1666. msgid "Not all applications can be packaged this way, only those relying on a select number of supported systems. Read about the full list of importers in the guix import section of the manual (@pxref{Invoking guix import,,, guix, GNU Guix Reference Manual})."
  1667. msgstr ""
  1668. #. type: subsubsection
  1669. #: guix-git/doc/guix-cookbook.texi:1251 guix-git/doc/guix-cookbook.texi:1252
  1670. #, no-wrap
  1671. msgid "Automatic update"
  1672. msgstr ""
  1673. #. type: Plain text
  1674. #: guix-git/doc/guix-cookbook.texi:1256
  1675. msgid "Guix can be smart enough to check for updates on systems it knows. It can report outdated package definitions with"
  1676. msgstr ""
  1677. #. type: example
  1678. #: guix-git/doc/guix-cookbook.texi:1259
  1679. #, no-wrap
  1680. msgid "$ guix refresh hello\n"
  1681. msgstr ""
  1682. #. type: Plain text
  1683. #: guix-git/doc/guix-cookbook.texi:1264
  1684. msgid "In most cases, updating a package to a newer version requires little more than changing the version number and the checksum. Guix can do that automatically as well:"
  1685. msgstr ""
  1686. #. type: example
  1687. #: guix-git/doc/guix-cookbook.texi:1267
  1688. #, no-wrap
  1689. msgid "$ guix refresh hello --update\n"
  1690. msgstr ""
  1691. #. type: subsubsection
  1692. #: guix-git/doc/guix-cookbook.texi:1269 guix-git/doc/guix-cookbook.texi:1270
  1693. #, no-wrap
  1694. msgid "Inheritance"
  1695. msgstr ""
  1696. #. type: Plain text
  1697. #: guix-git/doc/guix-cookbook.texi:1274
  1698. msgid "If you've started browsing the existing package definitions, you might have noticed that a significant number of them have a @code{inherit} field:"
  1699. msgstr ""
  1700. #. type: lisp
  1701. #: guix-git/doc/guix-cookbook.texi:1290
  1702. #, no-wrap
  1703. msgid ""
  1704. "(define-public adwaita-icon-theme\n"
  1705. " (package (inherit gnome-icon-theme)\n"
  1706. " (name \"adwaita-icon-theme\")\n"
  1707. " (version \"3.26.1\")\n"
  1708. " (source (origin\n"
  1709. " (method url-fetch)\n"
  1710. " (uri (string-append \"mirror://gnome/sources/\" name \"/\"\n"
  1711. " (version-major+minor version) \"/\"\n"
  1712. " name \"-\" version \".tar.xz\"))\n"
  1713. " (sha256\n"
  1714. " (base32\n"
  1715. " \"17fpahgh5dyckgz7rwqvzgnhx53cx9kr2xw0szprc6bnqy977fi8\"))))\n"
  1716. " (native-inputs\n"
  1717. " `((\"gtk-encode-symbolic-svg\" ,gtk+ \"bin\")))))\n"
  1718. msgstr ""
  1719. #. type: Plain text
  1720. #: guix-git/doc/guix-cookbook.texi:1295
  1721. msgid "All unspecified fields are inherited from the parent package. This is very convenient to create alternative packages, for instance with different source, version or compilation options."
  1722. msgstr ""
  1723. #. type: subsection
  1724. #: guix-git/doc/guix-cookbook.texi:1296 guix-git/doc/guix-cookbook.texi:1297
  1725. #, no-wrap
  1726. msgid "Getting help"
  1727. msgstr ""
  1728. #. type: Plain text
  1729. #: guix-git/doc/guix-cookbook.texi:1303
  1730. msgid "Sadly, some applications can be tough to package. Sometimes they need a patch to work with the non-standard file system hierarchy enforced by the store. Sometimes the tests won't run properly. (They can be skipped but this is not recommended.) Other times the resulting package won't be reproducible."
  1731. msgstr ""
  1732. #. type: Plain text
  1733. #: guix-git/doc/guix-cookbook.texi:1306
  1734. msgid "Should you be stuck, unable to figure out how to fix any sort of packaging issue, don't hesitate to ask the community for help."
  1735. msgstr ""
  1736. #. type: Plain text
  1737. #: guix-git/doc/guix-cookbook.texi:1308
  1738. msgid "See the @uref{https://www.gnu.org/software/guix/contact/, Guix homepage} for information on the mailing lists, IRC, etc."
  1739. msgstr ""
  1740. #. type: subsection
  1741. #: guix-git/doc/guix-cookbook.texi:1309 guix-git/doc/guix-cookbook.texi:1310
  1742. #, no-wrap
  1743. msgid "Conclusion"
  1744. msgstr ""
  1745. #. type: Plain text
  1746. #: guix-git/doc/guix-cookbook.texi:1316
  1747. msgid "This tutorial was a showcase of the sophisticated package management that Guix boasts. At this point we have mostly restricted this introduction to the @code{gnu-build-system} which is a core abstraction layer on which more advanced abstractions are based."
  1748. msgstr ""
  1749. #. type: Plain text
  1750. #: guix-git/doc/guix-cookbook.texi:1321
  1751. msgid "Where do we go from here? Next we ought to dissect the innards of the build system by removing all abstractions, using the @code{trivial-build-system}: this should give us a thorough understanding of the process before investigating some more advanced packaging techniques and edge cases."
  1752. msgstr ""
  1753. #. type: Plain text
  1754. #: guix-git/doc/guix-cookbook.texi:1324
  1755. msgid "Other features worth exploring are the interactive editing and debugging capabilities of Guix provided by the Guile REPL@."
  1756. msgstr ""
  1757. #. type: Plain text
  1758. #: guix-git/doc/guix-cookbook.texi:1329
  1759. msgid "Those fancy features are completely optional and can wait; now is a good time to take a well-deserved break. With what we've introduced here you should be well armed to package lots of programs. You can get started right away and hopefully we will see your contributions soon!"
  1760. msgstr ""
  1761. #. type: subsection
  1762. #: guix-git/doc/guix-cookbook.texi:1330 guix-git/doc/guix-cookbook.texi:1331
  1763. #, no-wrap
  1764. msgid "References"
  1765. msgstr ""
  1766. #. type: itemize
  1767. #: guix-git/doc/guix-cookbook.texi:1336
  1768. msgid "The @uref{https://www.gnu.org/software/guix/manual/en/html_node/Defining-Packages.html, package reference in the manual}"
  1769. msgstr ""
  1770. #. type: itemize
  1771. #: guix-git/doc/guix-cookbook.texi:1339
  1772. msgid "@uref{https://gitlab.com/pjotrp/guix-notes/blob/master/HACKING.org, Pjotr’s hacking guide to GNU Guix}"
  1773. msgstr ""
  1774. #. type: itemize
  1775. #: guix-git/doc/guix-cookbook.texi:1342
  1776. msgid "@uref{https://www.gnu.org/software/guix/guix-ghm-andreas-20130823.pdf, ``GNU Guix: Package without a scheme!''}, by Andreas Enge"
  1777. msgstr ""
  1778. #. type: Plain text
  1779. #: guix-git/doc/guix-cookbook.texi:1351
  1780. msgid "Guix offers a flexible language for declaratively configuring your Guix System. This flexibility can at times be overwhelming. The purpose of this chapter is to demonstrate some advanced configuration concepts."
  1781. msgstr ""
  1782. #. type: Plain text
  1783. #: guix-git/doc/guix-cookbook.texi:1354
  1784. msgid "@pxref{System Configuration,,, guix, GNU Guix Reference Manual} for a complete reference."
  1785. msgstr ""
  1786. #. type: menuentry
  1787. #: guix-git/doc/guix-cookbook.texi:1364
  1788. msgid "Creating and using a custom Linux kernel on Guix System."
  1789. msgstr ""
  1790. #. type: section
  1791. #: guix-git/doc/guix-cookbook.texi:1364 guix-git/doc/guix-cookbook.texi:1606
  1792. #: guix-git/doc/guix-cookbook.texi:1607
  1793. #, no-wrap
  1794. msgid "Guix System Image API"
  1795. msgstr ""
  1796. #. type: menuentry
  1797. #: guix-git/doc/guix-cookbook.texi:1364
  1798. msgid "Customizing images to target specific platforms."
  1799. msgstr ""
  1800. #. type: section
  1801. #: guix-git/doc/guix-cookbook.texi:1364 guix-git/doc/guix-cookbook.texi:1817
  1802. #: guix-git/doc/guix-cookbook.texi:1818
  1803. #, no-wrap
  1804. msgid "Connecting to Wireguard VPN"
  1805. msgstr ""
  1806. #. type: menuentry
  1807. #: guix-git/doc/guix-cookbook.texi:1364
  1808. msgid "Connecting to a Wireguard VPN."
  1809. msgstr ""
  1810. #. type: section
  1811. #: guix-git/doc/guix-cookbook.texi:1364 guix-git/doc/guix-cookbook.texi:1894
  1812. #: guix-git/doc/guix-cookbook.texi:1895
  1813. #, no-wrap
  1814. msgid "Customizing a Window Manager"
  1815. msgstr ""
  1816. #. type: menuentry
  1817. #: guix-git/doc/guix-cookbook.texi:1364
  1818. msgid "Handle customization of a Window manager on Guix System."
  1819. msgstr ""
  1820. #. type: section
  1821. #: guix-git/doc/guix-cookbook.texi:1364 guix-git/doc/guix-cookbook.texi:1985
  1822. #: guix-git/doc/guix-cookbook.texi:1986
  1823. #, no-wrap
  1824. msgid "Running Guix on a Linode Server"
  1825. msgstr ""
  1826. #. type: section
  1827. #: guix-git/doc/guix-cookbook.texi:1364 guix-git/doc/guix-cookbook.texi:2225
  1828. #: guix-git/doc/guix-cookbook.texi:2226
  1829. #, no-wrap
  1830. msgid "Setting up a bind mount"
  1831. msgstr ""
  1832. #. type: menuentry
  1833. #: guix-git/doc/guix-cookbook.texi:1364
  1834. msgid "Setting up a bind mount in the file-systems definition."
  1835. msgstr ""
  1836. #. type: section
  1837. #: guix-git/doc/guix-cookbook.texi:1364 guix-git/doc/guix-cookbook.texi:2274
  1838. #: guix-git/doc/guix-cookbook.texi:2275
  1839. #, no-wrap
  1840. msgid "Getting substitutes from Tor"
  1841. msgstr ""
  1842. #. type: menuentry
  1843. #: guix-git/doc/guix-cookbook.texi:1364
  1844. msgid "Configuring Guix daemon to get substitutes through Tor."
  1845. msgstr ""
  1846. #. type: section
  1847. #: guix-git/doc/guix-cookbook.texi:1364 guix-git/doc/guix-cookbook.texi:2336
  1848. #: guix-git/doc/guix-cookbook.texi:2337
  1849. #, no-wrap
  1850. msgid "Setting up NGINX with Lua"
  1851. msgstr ""
  1852. #. type: menuentry
  1853. #: guix-git/doc/guix-cookbook.texi:1364
  1854. msgid "Configuring NGINX web-server to load Lua modules."
  1855. msgstr ""
  1856. #. type: Plain text
  1857. #: guix-git/doc/guix-cookbook.texi:1376
  1858. msgid "Guix is, at its core, a source based distribution with substitutes (@pxref{Substitutes,,, guix, GNU Guix Reference Manual}), and as such building packages from their source code is an expected part of regular package installations and upgrades. Given this starting point, it makes sense that efforts are made to reduce the amount of time spent compiling packages, and recent changes and upgrades to the building and distribution of substitutes continues to be a topic of discussion within Guix."
  1859. msgstr ""
  1860. #. type: Plain text
  1861. #: guix-git/doc/guix-cookbook.texi:1382
  1862. msgid "The kernel, while not requiring an overabundance of RAM to build, does take a rather long time on an average machine. The official kernel configuration, as is the case with many GNU/Linux distributions, errs on the side of inclusiveness, and this is really what causes the build to take such a long time when the kernel is built from source."
  1863. msgstr ""
  1864. #. type: Plain text
  1865. #: guix-git/doc/guix-cookbook.texi:1387
  1866. msgid "The Linux kernel, however, can also just be described as a regular old package, and as such can be customized just like any other package. The procedure is a little bit different, although this is primarily due to the nature of how the package definition is written."
  1867. msgstr ""
  1868. #. type: Plain text
  1869. #: guix-git/doc/guix-cookbook.texi:1390
  1870. msgid "The @code{linux-libre} kernel package definition is actually a procedure which creates a package."
  1871. msgstr ""
  1872. #. type: lisp
  1873. #: guix-git/doc/guix-cookbook.texi:1402
  1874. #, no-wrap
  1875. msgid ""
  1876. "(define* (make-linux-libre version hash supported-systems\n"
  1877. " #:key\n"
  1878. " ;; A function that takes an arch and a variant.\n"
  1879. " ;; See kernel-config for an example.\n"
  1880. " (extra-version #false)\n"
  1881. " (configuration-file #false)\n"
  1882. " (defconfig \"defconfig\")\n"
  1883. " (extra-options %default-extra-linux-options)\n"
  1884. " (patches (list %boot-logo-patch)))\n"
  1885. " ...)\n"
  1886. msgstr ""
  1887. #. type: Plain text
  1888. #: guix-git/doc/guix-cookbook.texi:1406
  1889. msgid "The current @code{linux-libre} package is for the 5.1.x series, and is declared like this:"
  1890. msgstr ""
  1891. #. type: lisp
  1892. #: guix-git/doc/guix-cookbook.texi:1414
  1893. #, no-wrap
  1894. msgid ""
  1895. "(define-public linux-libre\n"
  1896. " (make-linux-libre %linux-libre-version\n"
  1897. " %linux-libre-hash\n"
  1898. " '(\"x86_64-linux\" \"i686-linux\" \"armhf-linux\" \"aarch64-linux\")\n"
  1899. " #:patches %linux-libre-5.1-patches\n"
  1900. " #:configuration-file kernel-config))\n"
  1901. msgstr ""
  1902. #. type: Plain text
  1903. #: guix-git/doc/guix-cookbook.texi:1423
  1904. msgid "Any keys which are not assigned values inherit their default value from the @code{make-linux-libre} definition. When comparing the two snippets above, you may notice that the code comment in the first doesn't actually refer to the @code{#:extra-version} keyword; it is actually for @code{#:configuration-file}. Because of this, it is not actually easy to include a custom kernel configuration from the definition, but don't worry, there are other ways to work with what we do have."
  1905. msgstr ""
  1906. #. type: Plain text
  1907. #: guix-git/doc/guix-cookbook.texi:1429
  1908. msgid "There are two ways to create a kernel with a custom kernel configuration. The first is to provide a standard @file{.config} file during the build process by including an actual @file{.config} file as a native input to our custom kernel. The following is a snippet from the custom @code{'configure} phase of the @code{make-linux-libre} package definition:"
  1909. msgstr ""
  1910. #. type: lisp
  1911. #: guix-git/doc/guix-cookbook.texi:1433
  1912. #, no-wrap
  1913. msgid ""
  1914. "(let ((build (assoc-ref %standard-phases 'build))\n"
  1915. " (config (assoc-ref (or native-inputs inputs) \"kconfig\")))\n"
  1916. "\n"
  1917. msgstr ""
  1918. #. type: lisp
  1919. #: guix-git/doc/guix-cookbook.texi:1441
  1920. #, no-wrap
  1921. msgid ""
  1922. " ;; Use a custom kernel configuration file or a default\n"
  1923. " ;; configuration file.\n"
  1924. " (if config\n"
  1925. " (begin\n"
  1926. " (copy-file config \".config\")\n"
  1927. " (chmod \".config\" #o666))\n"
  1928. " (invoke \"make\" ,defconfig)))\n"
  1929. msgstr ""
  1930. #. type: Plain text
  1931. #: guix-git/doc/guix-cookbook.texi:1446
  1932. msgid "Below is a sample kernel package. The @code{linux-libre} package is nothing special and can be inherited from and have its fields overridden like any other package:"
  1933. msgstr ""
  1934. #. type: lisp
  1935. #: guix-git/doc/guix-cookbook.texi:1455
  1936. #, no-wrap
  1937. msgid ""
  1938. "(define-public linux-libre/E2140\n"
  1939. " (package\n"
  1940. " (inherit linux-libre)\n"
  1941. " (native-inputs\n"
  1942. " `((\"kconfig\" ,(local-file \"E2140.config\"))\n"
  1943. " ,@@(alist-delete \"kconfig\"\n"
  1944. " (package-native-inputs linux-libre))))))\n"
  1945. msgstr ""
  1946. #. type: Plain text
  1947. #: guix-git/doc/guix-cookbook.texi:1462
  1948. msgid "In the same directory as the file defining @code{linux-libre-E2140} is a file named @file{E2140.config}, which is an actual kernel configuration file. The @code{defconfig} keyword of @code{make-linux-libre} is left blank here, so the only kernel configuration in the package is the one which was included in the @code{native-inputs} field."
  1949. msgstr ""
  1950. #. type: Plain text
  1951. #: guix-git/doc/guix-cookbook.texi:1467
  1952. msgid "The second way to create a custom kernel is to pass a new value to the @code{extra-options} keyword of the @code{make-linux-libre} procedure. The @code{extra-options} keyword works with another function defined right below it:"
  1953. msgstr ""
  1954. #. type: lisp
  1955. #: guix-git/doc/guix-cookbook.texi:1483
  1956. #, no-wrap
  1957. msgid ""
  1958. "(define %default-extra-linux-options\n"
  1959. " `(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html\n"
  1960. " (\"CONFIG_DEVPTS_MULTIPLE_INSTANCES\" . #true)\n"
  1961. " ;; Modules required for initrd:\n"
  1962. " (\"CONFIG_NET_9P\" . m)\n"
  1963. " (\"CONFIG_NET_9P_VIRTIO\" . m)\n"
  1964. " (\"CONFIG_VIRTIO_BLK\" . m)\n"
  1965. " (\"CONFIG_VIRTIO_NET\" . m)\n"
  1966. " (\"CONFIG_VIRTIO_PCI\" . m)\n"
  1967. " (\"CONFIG_VIRTIO_BALLOON\" . m)\n"
  1968. " (\"CONFIG_VIRTIO_MMIO\" . m)\n"
  1969. " (\"CONFIG_FUSE_FS\" . m)\n"
  1970. " (\"CONFIG_CIFS\" . m)\n"
  1971. " (\"CONFIG_9P_FS\" . m)))\n"
  1972. "\n"
  1973. msgstr ""
  1974. #. type: lisp
  1975. #: guix-git/doc/guix-cookbook.texi:1494
  1976. #, no-wrap
  1977. msgid ""
  1978. "(define (config->string options)\n"
  1979. " (string-join (map (match-lambda\n"
  1980. " ((option . 'm)\n"
  1981. " (string-append option \"=m\"))\n"
  1982. " ((option . #true)\n"
  1983. " (string-append option \"=y\"))\n"
  1984. " ((option . #false)\n"
  1985. " (string-append option \"=n\")))\n"
  1986. " options)\n"
  1987. " \"\\n\"))\n"
  1988. msgstr ""
  1989. #. type: Plain text
  1990. #: guix-git/doc/guix-cookbook.texi:1497
  1991. msgid "And in the custom configure script from the `make-linux-libre` package:"
  1992. msgstr ""
  1993. #. type: lisp
  1994. #: guix-git/doc/guix-cookbook.texi:1505
  1995. #, no-wrap
  1996. msgid ""
  1997. ";; Appending works even when the option wasn't in the\n"
  1998. ";; file. The last one prevails if duplicated.\n"
  1999. "(let ((port (open-file \".config\" \"a\"))\n"
  2000. " (extra-configuration ,(config->string extra-options)))\n"
  2001. " (display extra-configuration port)\n"
  2002. " (close-port port))\n"
  2003. "\n"
  2004. msgstr ""
  2005. #. type: lisp
  2006. #: guix-git/doc/guix-cookbook.texi:1507
  2007. #, no-wrap
  2008. msgid "(invoke \"make\" \"oldconfig\")\n"
  2009. msgstr ""
  2010. #. type: Plain text
  2011. #: guix-git/doc/guix-cookbook.texi:1512
  2012. msgid "So by not providing a configuration-file the @file{.config} starts blank, and then we write into it the collection of flags that we want. Here's another custom kernel:"
  2013. msgstr ""
  2014. #. type: lisp
  2015. #: guix-git/doc/guix-cookbook.texi:1520
  2016. #, no-wrap
  2017. msgid ""
  2018. "(define %macbook41-full-config\n"
  2019. " (append %macbook41-config-options\n"
  2020. " %file-systems\n"
  2021. " %efi-support\n"
  2022. " %emulation\n"
  2023. " (@@@@ (gnu packages linux) %default-extra-linux-options)))\n"
  2024. "\n"
  2025. msgstr ""
  2026. #. type: lisp
  2027. #: guix-git/doc/guix-cookbook.texi:1530
  2028. #, no-wrap
  2029. msgid ""
  2030. "(define-public linux-libre-macbook41\n"
  2031. " ;; XXX: Access the internal 'make-linux-libre' procedure, which is\n"
  2032. " ;; private and unexported, and is liable to change in the future.\n"
  2033. " ((@@@@ (gnu packages linux) make-linux-libre) (@@@@ (gnu packages linux) %linux-libre-version)\n"
  2034. " (@@@@ (gnu packages linux) %linux-libre-hash)\n"
  2035. " '(\"x86_64-linux\")\n"
  2036. " #:extra-version \"macbook41\"\n"
  2037. " #:patches (@@@@ (gnu packages linux) %linux-libre-5.1-patches)\n"
  2038. " #:extra-options %macbook41-config-options))\n"
  2039. msgstr ""
  2040. #. type: Plain text
  2041. #: guix-git/doc/guix-cookbook.texi:1537
  2042. msgid "In the above example @code{%file-systems} is a collection of flags enabling different file system support, @code{%efi-support} enables EFI support and @code{%emulation} enables a x86_64-linux machine to act in 32-bit mode also. @code{%default-extra-linux-options} are the ones quoted above, which had to be added in since they were replaced in the @code{extra-options} keyword."
  2043. msgstr ""
  2044. #. type: Plain text
  2045. #: guix-git/doc/guix-cookbook.texi:1546
  2046. msgid "This all sounds like it should be doable, but how does one even know which modules are required for a particular system? Two places that can be helpful in trying to answer this question is the @uref{https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Kernel, Gentoo Handbook} and the @uref{https://www.kernel.org/doc/html/latest/admin-guide/README.html?highlight=localmodconfig, documentation from the kernel itself}. From the kernel documentation, it seems that @code{make localmodconfig} is the command we want."
  2047. msgstr ""
  2048. #. type: Plain text
  2049. #: guix-git/doc/guix-cookbook.texi:1549
  2050. msgid "In order to actually run @code{make localmodconfig} we first need to get and unpack the kernel source code:"
  2051. msgstr ""
  2052. #. type: example
  2053. #: guix-git/doc/guix-cookbook.texi:1552
  2054. #, no-wrap
  2055. msgid "tar xf $(guix build linux-libre --source)\n"
  2056. msgstr ""
  2057. #. type: Plain text
  2058. #: guix-git/doc/guix-cookbook.texi:1559
  2059. msgid "Once inside the directory containing the source code run @code{touch .config} to create an initial, empty @file{.config} to start with. @code{make localmodconfig} works by seeing what you already have in @file{.config} and letting you know what you're missing. If the file is blank then you're missing everything. The next step is to run:"
  2060. msgstr ""
  2061. #. type: example
  2062. #: guix-git/doc/guix-cookbook.texi:1562
  2063. #, no-wrap
  2064. msgid "guix environment linux-libre -- make localmodconfig\n"
  2065. msgstr ""
  2066. #. type: Plain text
  2067. #: guix-git/doc/guix-cookbook.texi:1567
  2068. msgid "and note the output. Do note that the @file{.config} file is still empty. The output generally contains two types of warnings. The first start with \"WARNING\" and can actually be ignored in our case. The second read:"
  2069. msgstr ""
  2070. #. type: example
  2071. #: guix-git/doc/guix-cookbook.texi:1570
  2072. #, no-wrap
  2073. msgid "module pcspkr did not have configs CONFIG_INPUT_PCSPKR\n"
  2074. msgstr ""
  2075. #. type: Plain text
  2076. #: guix-git/doc/guix-cookbook.texi:1575
  2077. msgid "For each of these lines, copy the @code{CONFIG_XXXX_XXXX} portion into the @file{.config} in the directory, and append @code{=m}, so in the end it looks like this:"
  2078. msgstr ""
  2079. #. type: example
  2080. #: guix-git/doc/guix-cookbook.texi:1579
  2081. #, no-wrap
  2082. msgid ""
  2083. "CONFIG_INPUT_PCSPKR=m\n"
  2084. "CONFIG_VIRTIO=m\n"
  2085. msgstr ""
  2086. #. type: Plain text
  2087. #: guix-git/doc/guix-cookbook.texi:1588
  2088. msgid "After copying all the configuration options, run @code{make localmodconfig} again to make sure that you don't have any output starting with ``module''. After all of these machine specific modules there are a couple more left that are also needed. @code{CONFIG_MODULES} is necessary so that you can build and load modules separately and not have everything built into the kernel. @code{CONFIG_BLK_DEV_SD} is required for reading from hard drives. It is possible that there are other modules which you will need."
  2089. msgstr ""
  2090. #. type: Plain text
  2091. #: guix-git/doc/guix-cookbook.texi:1592
  2092. msgid "This post does not aim to be a guide to configuring your own kernel however, so if you do decide to build a custom kernel you'll have to seek out other guides to create a kernel which is just right for your needs."
  2093. msgstr ""
  2094. #. type: Plain text
  2095. #: guix-git/doc/guix-cookbook.texi:1600
  2096. msgid "The second way to setup the kernel configuration makes more use of Guix's features and allows you to share configuration segments between different kernels. For example, all machines using EFI to boot have a number of EFI configuration flags that they need. It is likely that all the kernels will share a list of file systems to support. By using variables it is easier to see at a glance what features are enabled and to make sure you don't have features in one kernel but missing in another."
  2097. msgstr ""
  2098. #. type: Plain text
  2099. #: guix-git/doc/guix-cookbook.texi:1605
  2100. msgid "Left undiscussed however, is Guix's initrd and its customization. It is likely that you'll need to modify the initrd on a machine using a custom kernel, since certain modules which are expected to be built may not be available for inclusion into the initrd."
  2101. msgstr ""
  2102. #. type: Plain text
  2103. #: guix-git/doc/guix-cookbook.texi:1612
  2104. msgid "Historically, Guix System is centered around an @code{operating-system} structure. This structure contains various fields ranging from the bootloader and kernel declaration to the services to install."
  2105. msgstr ""
  2106. #. type: Plain text
  2107. #: guix-git/doc/guix-cookbook.texi:1618
  2108. msgid "Depending on the target machine, that can go from a standard @code{x86_64} machine to a small ARM single board computer such as the Pine64, the image constraints can vary a lot. The hardware manufacturers will impose different image formats with various partition sizes and offsets."
  2109. msgstr ""
  2110. #. type: Plain text
  2111. #: guix-git/doc/guix-cookbook.texi:1623
  2112. msgid "To create images suitable for all those machines, a new abstraction is necessary: that's the goal of the @code{image} record. This record contains all the required information to be transformed into a standalone image, that can be directly booted on any target machine."
  2113. msgstr ""
  2114. #. type: lisp
  2115. #: guix-git/doc/guix-cookbook.texi:1645
  2116. #, no-wrap
  2117. msgid ""
  2118. "(define-record-type* <image>\n"
  2119. " image make-image\n"
  2120. " image?\n"
  2121. " (name image-name ;symbol\n"
  2122. " (default #f))\n"
  2123. " (format image-format) ;symbol\n"
  2124. " (target image-target\n"
  2125. " (default #f))\n"
  2126. " (size image-size ;size in bytes as integer\n"
  2127. " (default 'guess))\n"
  2128. " (operating-system image-operating-system ;<operating-system>\n"
  2129. " (default #f))\n"
  2130. " (partitions image-partitions ;list of <partition>\n"
  2131. " (default '()))\n"
  2132. " (compression? image-compression? ;boolean\n"
  2133. " (default #t))\n"
  2134. " (volatile-root? image-volatile-root? ;boolean\n"
  2135. " (default #t))\n"
  2136. " (substitutable? image-substitutable? ;boolean\n"
  2137. " (default #t)))\n"
  2138. msgstr ""
  2139. #. type: Plain text
  2140. #: guix-git/doc/guix-cookbook.texi:1651
  2141. msgid "This record contains the operating-system to instantiate. The @code{format} field defines the image type and can be @code{efi-raw}, @code{qcow2} or @code{iso9660} for instance. In the future, it could be extended to @code{docker} or other image types."
  2142. msgstr ""
  2143. #. type: Plain text
  2144. #: guix-git/doc/guix-cookbook.texi:1654
  2145. msgid "A new directory in the Guix sources is dedicated to images definition. For now there are four files:"
  2146. msgstr ""
  2147. #. type: file{#1}
  2148. #: guix-git/doc/guix-cookbook.texi:1656
  2149. #, no-wrap
  2150. msgid "gnu/system/images/hurd.scm"
  2151. msgstr ""
  2152. #. type: file{#1}
  2153. #: guix-git/doc/guix-cookbook.texi:1657
  2154. #, no-wrap
  2155. msgid "gnu/system/images/pine64.scm"
  2156. msgstr ""
  2157. #. type: file{#1}
  2158. #: guix-git/doc/guix-cookbook.texi:1658
  2159. #, no-wrap
  2160. msgid "gnu/system/images/novena.scm"
  2161. msgstr ""
  2162. #. type: file{#1}
  2163. #: guix-git/doc/guix-cookbook.texi:1659
  2164. #, no-wrap
  2165. msgid "gnu/system/images/pinebook-pro.scm"
  2166. msgstr ""
  2167. #. type: Plain text
  2168. #: guix-git/doc/guix-cookbook.texi:1665
  2169. msgid "Let's have a look to @file{pine64.scm}. It contains the @code{pine64-barebones-os} variable which is a minimal definition of an operating-system dedicated to the @b{Pine A64 LTS} board."
  2170. msgstr ""
  2171. #. type: lisp
  2172. #: guix-git/doc/guix-cookbook.texi:1689
  2173. #, no-wrap
  2174. msgid ""
  2175. "(define pine64-barebones-os\n"
  2176. " (operating-system\n"
  2177. " (host-name \"vignemale\")\n"
  2178. " (timezone \"Europe/Paris\")\n"
  2179. " (locale \"en_US.utf8\")\n"
  2180. " (bootloader (bootloader-configuration\n"
  2181. " (bootloader u-boot-pine64-lts-bootloader)\n"
  2182. " (target \"/dev/vda\")))\n"
  2183. " (initrd-modules '())\n"
  2184. " (kernel linux-libre-arm64-generic)\n"
  2185. " (file-systems (cons (file-system\n"
  2186. " (device (file-system-label \"my-root\"))\n"
  2187. " (mount-point \"/\")\n"
  2188. " (type \"ext4\"))\n"
  2189. " %base-file-systems))\n"
  2190. " (services (cons (service agetty-service-type\n"
  2191. " (agetty-configuration\n"
  2192. " (extra-options '(\"-L\")) ; no carrier detect\n"
  2193. " (baud-rate \"115200\")\n"
  2194. " (term \"vt100\")\n"
  2195. " (tty \"ttyS0\")))\n"
  2196. " %base-services))))\n"
  2197. msgstr ""
  2198. #. type: Plain text
  2199. #: guix-git/doc/guix-cookbook.texi:1693
  2200. msgid "The @code{kernel} and @code{bootloader} fields are pointing to packages dedicated to this board."
  2201. msgstr ""
  2202. #. type: Plain text
  2203. #: guix-git/doc/guix-cookbook.texi:1695
  2204. msgid "Right below, the @code{pine64-image-type} variable is also defined."
  2205. msgstr ""
  2206. #. type: lisp
  2207. #: guix-git/doc/guix-cookbook.texi:1701
  2208. #, no-wrap
  2209. msgid ""
  2210. "(define pine64-image-type\n"
  2211. " (image-type\n"
  2212. " (name 'pine64-raw)\n"
  2213. " (constructor (cut image-with-os arm64-disk-image <>))))\n"
  2214. msgstr ""
  2215. #. type: Plain text
  2216. #: guix-git/doc/guix-cookbook.texi:1705
  2217. msgid "It's using a record we haven't talked about yet, the @code{image-type} record, defined this way:"
  2218. msgstr ""
  2219. #. type: lisp
  2220. #: guix-git/doc/guix-cookbook.texi:1712
  2221. #, no-wrap
  2222. msgid ""
  2223. "(define-record-type* <image-type>\n"
  2224. " image-type make-image-type\n"
  2225. " image-type?\n"
  2226. " (name image-type-name) ;symbol\n"
  2227. " (constructor image-type-constructor)) ;<operating-system> -> <image>\n"
  2228. msgstr ""
  2229. #. type: Plain text
  2230. #: guix-git/doc/guix-cookbook.texi:1718
  2231. msgid "The main purpose of this record is to associate a name to a procedure transforming an @code{operating-system} to an image. To understand why it is necessary, let's have a look to the command producing an image from an @code{operating-system} configuration file:"
  2232. msgstr ""
  2233. #. type: example
  2234. #: guix-git/doc/guix-cookbook.texi:1721
  2235. #, no-wrap
  2236. msgid "guix system image my-os.scm\n"
  2237. msgstr ""
  2238. #. type: Plain text
  2239. #: guix-git/doc/guix-cookbook.texi:1727
  2240. msgid "This command expects an @code{operating-system} configuration but how should we indicate that we want an image targeting a Pine64 board? We need to provide an extra information, the @code{image-type}, by passing the @code{--image-type} or @code{-t} flag, this way:"
  2241. msgstr ""
  2242. #. type: example
  2243. #: guix-git/doc/guix-cookbook.texi:1730
  2244. #, no-wrap
  2245. msgid "guix system image --image-type=pine64-raw my-os.scm\n"
  2246. msgstr ""
  2247. #. type: Plain text
  2248. #: guix-git/doc/guix-cookbook.texi:1736
  2249. msgid "This @code{image-type} parameter points to the @code{pine64-image-type} defined above. Hence, the @code{operating-system} declared in @code{my-os.scm} will be applied the @code{(cut image-with-os arm64-disk-image <>)} procedure to turn it into an image."
  2250. msgstr ""
  2251. #. type: Plain text
  2252. #: guix-git/doc/guix-cookbook.texi:1738
  2253. msgid "The resulting image looks like:"
  2254. msgstr ""
  2255. #. type: lisp
  2256. #: guix-git/doc/guix-cookbook.texi:1748
  2257. #, no-wrap
  2258. msgid ""
  2259. "(image\n"
  2260. " (format 'disk-image)\n"
  2261. " (target \"aarch64-linux-gnu\")\n"
  2262. " (operating-system my-os)\n"
  2263. " (partitions\n"
  2264. " (list (partition\n"
  2265. " (inherit root-partition)\n"
  2266. " (offset root-offset)))))\n"
  2267. msgstr ""
  2268. #. type: Plain text
  2269. #: guix-git/doc/guix-cookbook.texi:1752
  2270. msgid "which is the aggregation of the @code{operating-system} defined in @code{my-os.scm} to the @code{arm64-disk-image} record."
  2271. msgstr ""
  2272. #. type: Plain text
  2273. #: guix-git/doc/guix-cookbook.texi:1754
  2274. msgid "But enough Scheme madness. What does this image API bring to the Guix user?"
  2275. msgstr ""
  2276. #. type: Plain text
  2277. #: guix-git/doc/guix-cookbook.texi:1756
  2278. msgid "One can run:"
  2279. msgstr ""
  2280. #. type: example
  2281. #: guix-git/doc/guix-cookbook.texi:1760
  2282. #, no-wrap
  2283. msgid ""
  2284. "mathieu@@cervin:~$ guix system --list-image-types\n"
  2285. "The available image types are:\n"
  2286. "\n"
  2287. msgstr ""
  2288. #. type: example
  2289. #: guix-git/doc/guix-cookbook.texi:1772
  2290. #, no-wrap
  2291. msgid ""
  2292. " - pinebook-pro-raw\n"
  2293. " - pine64-raw\n"
  2294. " - novena-raw\n"
  2295. " - hurd-raw\n"
  2296. " - hurd-qcow2\n"
  2297. " - qcow2\n"
  2298. " - uncompressed-iso9660\n"
  2299. " - efi-raw\n"
  2300. " - arm64-raw\n"
  2301. " - arm32-raw\n"
  2302. " - iso9660\n"
  2303. msgstr ""
  2304. #. type: Plain text
  2305. #: guix-git/doc/guix-cookbook.texi:1777
  2306. msgid "and by writing an @code{operating-system} file based on @code{pine64-barebones-os}, you can customize your image to your preferences in a file (@file{my-pine-os.scm}) like this:"
  2307. msgstr ""
  2308. #. type: lisp
  2309. #: guix-git/doc/guix-cookbook.texi:1781
  2310. #, no-wrap
  2311. msgid ""
  2312. "(use-modules (gnu services linux)\n"
  2313. " (gnu system images pine64))\n"
  2314. "\n"
  2315. msgstr ""
  2316. #. type: lisp
  2317. #: guix-git/doc/guix-cookbook.texi:1792
  2318. #, no-wrap
  2319. msgid ""
  2320. "(let ((base-os pine64-barebones-os))\n"
  2321. " (operating-system\n"
  2322. " (inherit base-os)\n"
  2323. " (timezone \"America/Indiana/Indianapolis\")\n"
  2324. " (services\n"
  2325. " (cons\n"
  2326. " (service earlyoom-service-type\n"
  2327. " (earlyoom-configuration\n"
  2328. " (prefer-regexp \"icecat|chromium\")))\n"
  2329. " (operating-system-user-services base-os)))))\n"
  2330. msgstr ""
  2331. #. type: Plain text
  2332. #: guix-git/doc/guix-cookbook.texi:1795
  2333. msgid "run:"
  2334. msgstr ""
  2335. #. type: example
  2336. #: guix-git/doc/guix-cookbook.texi:1798
  2337. #, no-wrap
  2338. msgid "guix system image --image-type=pine64-raw my-pine-os.scm\n"
  2339. msgstr ""
  2340. #. type: Plain text
  2341. #: guix-git/doc/guix-cookbook.texi:1801
  2342. msgid "or,"
  2343. msgstr ""
  2344. #. type: example
  2345. #: guix-git/doc/guix-cookbook.texi:1804
  2346. #, no-wrap
  2347. msgid "guix system image --image-type=hurd-raw my-hurd-os.scm\n"
  2348. msgstr ""
  2349. #. type: Plain text
  2350. #: guix-git/doc/guix-cookbook.texi:1808
  2351. msgid "to get an image that can be written directly to a hard drive and booted from."
  2352. msgstr ""
  2353. #. type: Plain text
  2354. #: guix-git/doc/guix-cookbook.texi:1810
  2355. msgid "Without changing anything to @code{my-hurd-os.scm}, calling:"
  2356. msgstr ""
  2357. #. type: example
  2358. #: guix-git/doc/guix-cookbook.texi:1813
  2359. #, no-wrap
  2360. msgid "guix system image --image-type=hurd-qcow2 my-hurd-os.scm\n"
  2361. msgstr ""
  2362. #. type: Plain text
  2363. #: guix-git/doc/guix-cookbook.texi:1816
  2364. msgid "will instead produce a Hurd QEMU image."
  2365. msgstr ""
  2366. #. type: Plain text
  2367. #: guix-git/doc/guix-cookbook.texi:1823
  2368. msgid "To connect to a Wireguard VPN server you need the kernel module to be loaded in memory and a package providing networking tools that support it (e.g. @code{wireguard-tools} or @code{network-manager})."
  2369. msgstr ""
  2370. #. type: Plain text
  2371. #: guix-git/doc/guix-cookbook.texi:1827
  2372. msgid "Here is a configuration example for Linux-Libre < 5.6, where the module is out of tree and need to be loaded manually---following revisions of the kernel have it built-in and so don't need such configuration:"
  2373. msgstr ""
  2374. #. type: lisp
  2375. #: guix-git/doc/guix-cookbook.texi:1832
  2376. #, no-wrap
  2377. msgid ""
  2378. "(use-modules (gnu))\n"
  2379. "(use-service-modules desktop)\n"
  2380. "(use-package-modules vpn)\n"
  2381. "\n"
  2382. msgstr ""
  2383. #. type: lisp
  2384. #: guix-git/doc/guix-cookbook.texi:1841
  2385. #, no-wrap
  2386. msgid ""
  2387. "(operating-system\n"
  2388. " ;; …\n"
  2389. " (services (cons (simple-service 'wireguard-module\n"
  2390. " kernel-module-loader-service-type\n"
  2391. " '(\"wireguard\"))\n"
  2392. " %desktop-services))\n"
  2393. " (packages (cons wireguard-tools %base-packages))\n"
  2394. " (kernel-loadable-modules (list wireguard-linux-compat)))\n"
  2395. msgstr ""
  2396. #. type: Plain text
  2397. #: guix-git/doc/guix-cookbook.texi:1845
  2398. msgid "After reconfiguring and restarting your system you can either use Wireguard tools or NetworkManager to connect to a VPN server."
  2399. msgstr ""
  2400. #. type: subsection
  2401. #: guix-git/doc/guix-cookbook.texi:1846
  2402. #, no-wrap
  2403. msgid "Using Wireguard tools"
  2404. msgstr ""
  2405. #. type: Plain text
  2406. #: guix-git/doc/guix-cookbook.texi:1852
  2407. msgid "To test your Wireguard setup it is convenient to use @command{wg-quick}. Just give it a configuration file @command{wg-quick up ./wg0.conf}; or put that file in @file{/etc/wireguard} and run @command{wg-quick up wg0} instead."
  2408. msgstr ""
  2409. #. type: quotation
  2410. #: guix-git/doc/guix-cookbook.texi:1853
  2411. #, no-wrap
  2412. msgid "Note"
  2413. msgstr ""
  2414. #. type: quotation
  2415. #: guix-git/doc/guix-cookbook.texi:1856
  2416. msgid "Be warned that the author described this command as a: “[…] very quick and dirty bash script […]”."
  2417. msgstr ""
  2418. #. type: subsection
  2419. #: guix-git/doc/guix-cookbook.texi:1858
  2420. #, no-wrap
  2421. msgid "Using NetworkManager"
  2422. msgstr ""
  2423. #. type: Plain text
  2424. #: guix-git/doc/guix-cookbook.texi:1866
  2425. msgid "Thanks to NetworkManager support for Wireguard we can connect to our VPN using @command{nmcli} command. Up to this point this guide assumes that you're using Network Manager service provided by @code{%desktop-services}. Ortherwise you need to adjust your services list to load @code{network-manager-service-type} and reconfigure your Guix system."
  2426. msgstr ""
  2427. #. type: Plain text
  2428. #: guix-git/doc/guix-cookbook.texi:1868
  2429. msgid "To import your VPN configuration execute nmcli import command:"
  2430. msgstr ""
  2431. #. type: example
  2432. #: guix-git/doc/guix-cookbook.texi:1872
  2433. #, no-wrap
  2434. msgid ""
  2435. "# nmcli connection import type wireguard file wg0.conf\n"
  2436. "Connection 'wg0' (edbee261-aa5a-42db-b032-6c7757c60fde) successfully added\n"
  2437. msgstr ""
  2438. #. type: Plain text
  2439. #: guix-git/doc/guix-cookbook.texi:1877
  2440. msgid "This will create a configuration file in @file{/etc/NetworkManager/wg0.nmconnection}. Next connect to the Wireguard server:"
  2441. msgstr ""
  2442. #. type: example
  2443. #: guix-git/doc/guix-cookbook.texi:1881
  2444. #, no-wrap
  2445. msgid ""
  2446. "$ nmcli connection up wg0\n"
  2447. "Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/6)\n"
  2448. msgstr ""
  2449. #. type: Plain text
  2450. #: guix-git/doc/guix-cookbook.texi:1885
  2451. msgid "By default NetworkManager will connect automatically on system boot. To change that behaviour you need to edit your config:"
  2452. msgstr ""
  2453. #. type: example
  2454. #: guix-git/doc/guix-cookbook.texi:1888
  2455. #, no-wrap
  2456. msgid "# nmcli connection modify wg0 connection.autoconnect no\n"
  2457. msgstr ""
  2458. #. type: Plain text
  2459. #: guix-git/doc/guix-cookbook.texi:1893
  2460. msgid "For more specific information about NetworkManager and wireguard @uref{https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/,see this post by thaller}."
  2461. msgstr ""
  2462. #. type: cindex
  2463. #: guix-git/doc/guix-cookbook.texi:1896
  2464. #, no-wrap
  2465. msgid "wm"
  2466. msgstr ""
  2467. #. type: subsection
  2468. #: guix-git/doc/guix-cookbook.texi:1898 guix-git/doc/guix-cookbook.texi:1899
  2469. #, no-wrap
  2470. msgid "StumpWM"
  2471. msgstr ""
  2472. #. type: cindex
  2473. #: guix-git/doc/guix-cookbook.texi:1900
  2474. #, no-wrap
  2475. msgid "stumpwm"
  2476. msgstr ""
  2477. #. type: Plain text
  2478. #: guix-git/doc/guix-cookbook.texi:1905
  2479. msgid "You could install StumpWM with a Guix system by adding @code{stumpwm} and optionally @code{`(,stumpwm \"lib\")} packages to a system configuration file, e.g.@: @file{/etc/config.scm}."
  2480. msgstr ""
  2481. #. type: Plain text
  2482. #: guix-git/doc/guix-cookbook.texi:1907
  2483. msgid "An example configuration can look like this:"
  2484. msgstr ""
  2485. #. type: lisp
  2486. #: guix-git/doc/guix-cookbook.texi:1911
  2487. #, no-wrap
  2488. msgid ""
  2489. "(use-modules (gnu))\n"
  2490. "(use-package-modules wm)\n"
  2491. "\n"
  2492. msgstr ""
  2493. #. type: lisp
  2494. #: guix-git/doc/guix-cookbook.texi:1916
  2495. #, no-wrap
  2496. msgid ""
  2497. "(operating-system\n"
  2498. " ;; …\n"
  2499. " (packages (append (list sbcl stumpwm `(,stumpwm \"lib\"))\n"
  2500. " %base-packages)))\n"
  2501. msgstr ""
  2502. #. type: cindex
  2503. #: guix-git/doc/guix-cookbook.texi:1918
  2504. #, no-wrap
  2505. msgid "stumpwm fonts"
  2506. msgstr ""
  2507. #. type: Plain text
  2508. #: guix-git/doc/guix-cookbook.texi:1922
  2509. msgid "By default StumpWM uses X11 fonts, which could be small or pixelated on your system. You could fix this by installing StumpWM contrib Lisp module @code{sbcl-ttf-fonts}, adding it to Guix system packages:"
  2510. msgstr ""
  2511. #. type: lisp
  2512. #: guix-git/doc/guix-cookbook.texi:1926
  2513. #, no-wrap
  2514. msgid ""
  2515. "(use-modules (gnu))\n"
  2516. "(use-package-modules fonts wm)\n"
  2517. "\n"
  2518. msgstr ""
  2519. #. type: lisp
  2520. #: guix-git/doc/guix-cookbook.texi:1931
  2521. #, no-wrap
  2522. msgid ""
  2523. "(operating-system\n"
  2524. " ;; …\n"
  2525. " (packages (append (list sbcl stumpwm `(,stumpwm \"lib\"))\n"
  2526. " sbcl-ttf-fonts font-dejavu %base-packages)))\n"
  2527. msgstr ""
  2528. #. type: Plain text
  2529. #: guix-git/doc/guix-cookbook.texi:1935
  2530. msgid "Then you need to add the following code to a StumpWM configuration file @file{~/.stumpwm.d/init.lisp}:"
  2531. msgstr ""
  2532. #. type: lisp
  2533. #: guix-git/doc/guix-cookbook.texi:1942
  2534. #, no-wrap
  2535. msgid ""
  2536. "(require :ttf-fonts)\n"
  2537. "(setf xft:*font-dirs* '(\"/run/current-system/profile/share/fonts/\"))\n"
  2538. "(setf clx-truetype:+font-cache-filename+ (concat (getenv \"HOME\") \"/.fonts/font-cache.sexp\"))\n"
  2539. "(xft:cache-fonts)\n"
  2540. "(set-font (make-instance 'xft:font :family \"DejaVu Sans Mono\" :subfamily \"Book\" :size 11))\n"
  2541. msgstr ""
  2542. #. type: subsection
  2543. #: guix-git/doc/guix-cookbook.texi:1944 guix-git/doc/guix-cookbook.texi:1945
  2544. #, no-wrap
  2545. msgid "Session lock"
  2546. msgstr ""
  2547. #. type: cindex
  2548. #: guix-git/doc/guix-cookbook.texi:1946
  2549. #, no-wrap
  2550. msgid "sessionlock"
  2551. msgstr ""
  2552. #. type: Plain text
  2553. #: guix-git/doc/guix-cookbook.texi:1952
  2554. msgid "Depending on your environment, locking the screen of your session might come built in or it might be something you have to set up yourself. If you use a desktop environment like GNOME or KDE, it's usually built in. If you use a plain window manager like StumpWM or EXWM, you might have to set it up yourself."
  2555. msgstr ""
  2556. #. type: subsubsection
  2557. #: guix-git/doc/guix-cookbook.texi:1953 guix-git/doc/guix-cookbook.texi:1954
  2558. #, no-wrap
  2559. msgid "Xorg"
  2560. msgstr ""
  2561. #. type: Plain text
  2562. #: guix-git/doc/guix-cookbook.texi:1960
  2563. msgid "If you use Xorg, you can use the utility @uref{https://www.mankier.com/1/xss-lock, xss-lock} to lock the screen of your session. xss-lock is triggered by DPMS which since Xorg 1.8 is auto-detected and enabled if ACPI is also enabled at kernel runtime."
  2564. msgstr ""
  2565. #. type: Plain text
  2566. #: guix-git/doc/guix-cookbook.texi:1963
  2567. msgid "To use xss-lock, you can simple execute it and put it into the background before you start your window manager from e.g. your @file{~/.xsession}:"
  2568. msgstr ""
  2569. #. type: example
  2570. #: guix-git/doc/guix-cookbook.texi:1967
  2571. #, no-wrap
  2572. msgid ""
  2573. "xss-lock -- slock &\n"
  2574. "exec stumpwm\n"
  2575. msgstr ""
  2576. #. type: Plain text
  2577. #: guix-git/doc/guix-cookbook.texi:1971
  2578. msgid "In this example, xss-lock uses @code{slock} to do the actual locking of the screen when it determines it's appropriate, like when you suspend your device."
  2579. msgstr ""
  2580. #. type: Plain text
  2581. #: guix-git/doc/guix-cookbook.texi:1975
  2582. msgid "For slock to be allowed to be a screen locker for the graphical session, it needs to be made setuid-root so it can authenticate users, and it needs a PAM service. This can be achieved by adding the following service to your @file{config.scm}:"
  2583. msgstr ""
  2584. #. type: lisp
  2585. #: guix-git/doc/guix-cookbook.texi:1978
  2586. #, no-wrap
  2587. msgid "(screen-locker-service slock)\n"
  2588. msgstr ""
  2589. #. type: Plain text
  2590. #: guix-git/doc/guix-cookbook.texi:1984
  2591. msgid "If you manually lock your screen, e.g. by directly calling slock when you want to lock your screen but not suspend it, it's a good idea to notify xss-lock about this so no confusion occurs. This can be done by executing @code{xset s activate} immediately before you execute slock."
  2592. msgstr ""
  2593. #. type: cindex
  2594. #: guix-git/doc/guix-cookbook.texi:1987
  2595. #, no-wrap
  2596. msgid "linode, Linode"
  2597. msgstr ""
  2598. #. type: Plain text
  2599. #: guix-git/doc/guix-cookbook.texi:1992
  2600. msgid "To run Guix on a server hosted by @uref{https://www.linode.com, Linode}, start with a recommended Debian server. We recommend using the default distro as a way to bootstrap Guix. Create your SSH keys."
  2601. msgstr ""
  2602. #. type: example
  2603. #: guix-git/doc/guix-cookbook.texi:1995
  2604. #, no-wrap
  2605. msgid "ssh-keygen\n"
  2606. msgstr ""
  2607. #. type: Plain text
  2608. #: guix-git/doc/guix-cookbook.texi:2001
  2609. msgid "Be sure to add your SSH key for easy login to the remote server. This is trivially done via Linode's graphical interface for adding SSH keys. Go to your profile and click add SSH Key. Copy into it the output of:"
  2610. msgstr ""
  2611. #. type: example
  2612. #: guix-git/doc/guix-cookbook.texi:2004
  2613. #, no-wrap
  2614. msgid "cat ~/.ssh/<username>_rsa.pub\n"
  2615. msgstr ""
  2616. #. type: Plain text
  2617. #: guix-git/doc/guix-cookbook.texi:2008
  2618. msgid "Power the Linode down. In the Linode's Disks/Configurations tab, resize the Debian disk to be smaller. 30 GB is recommended."
  2619. msgstr ""
  2620. #. type: Plain text
  2621. #: guix-git/doc/guix-cookbook.texi:2010
  2622. msgid "In the Linode settings, \"Add a disk\", with the following:"
  2623. msgstr ""
  2624. #. type: itemize
  2625. #: guix-git/doc/guix-cookbook.texi:2013
  2626. msgid "Label: \"Guix\""
  2627. msgstr ""
  2628. #. type: itemize
  2629. #: guix-git/doc/guix-cookbook.texi:2016
  2630. msgid "Filesystem: ext4"
  2631. msgstr ""
  2632. #. type: itemize
  2633. #: guix-git/doc/guix-cookbook.texi:2019
  2634. msgid "Set it to the remaining size"
  2635. msgstr ""
  2636. #. type: Plain text
  2637. #: guix-git/doc/guix-cookbook.texi:2024
  2638. msgid "On the \"configuration\" field that comes with the default image, press \"...\" and select \"Edit\", then on that menu add to @file{/dev/sdc} the \"Guix\" label."
  2639. msgstr ""
  2640. #. type: Plain text
  2641. #: guix-git/doc/guix-cookbook.texi:2026
  2642. msgid "Now \"Add a Configuration\", with the following:"
  2643. msgstr ""
  2644. #. type: itemize
  2645. #: guix-git/doc/guix-cookbook.texi:2029
  2646. msgid "Label: Guix"
  2647. msgstr ""
  2648. #. type: itemize
  2649. #: guix-git/doc/guix-cookbook.texi:2032
  2650. msgid "Kernel:GRUB 2 (it's at the bottom! This step is @b{IMPORTANT!})"
  2651. msgstr ""
  2652. #. type: itemize
  2653. #: guix-git/doc/guix-cookbook.texi:2035
  2654. msgid "Block device assignment:"
  2655. msgstr ""
  2656. #. type: itemize
  2657. #: guix-git/doc/guix-cookbook.texi:2038
  2658. msgid "@file{/dev/sda}: Guix"
  2659. msgstr ""
  2660. #. type: itemize
  2661. #: guix-git/doc/guix-cookbook.texi:2041
  2662. msgid "@file{/dev/sdb}: swap"
  2663. msgstr ""
  2664. #. type: itemize
  2665. #: guix-git/doc/guix-cookbook.texi:2044
  2666. msgid "Root device: @file{/dev/sda}"
  2667. msgstr ""
  2668. #. type: itemize
  2669. #: guix-git/doc/guix-cookbook.texi:2047
  2670. msgid "Turn off all the filesystem/boot helpers"
  2671. msgstr ""
  2672. #. type: Plain text
  2673. #: guix-git/doc/guix-cookbook.texi:2054
  2674. msgid "Now power it back up, picking the Debian configuration. Once it's booted up, ssh in your server via @code{ssh root@@@var{<your-server-IP-here>}}. (You can find your server IP address in your Linode Summary section.) Now you can run the \"install guix from @pxref{Binary Installation,,, guix, GNU Guix}\" steps:"
  2675. msgstr ""
  2676. #. type: example
  2677. #: guix-git/doc/guix-cookbook.texi:2062
  2678. #, no-wrap
  2679. msgid ""
  2680. "sudo apt-get install gpg\n"
  2681. "wget https://sv.gnu.org/people/viewgpg.php?user_id=15145 -qO - | gpg --import -\n"
  2682. "wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh\n"
  2683. "chmod +x guix-install.sh\n"
  2684. "./guix-install.sh\n"
  2685. "guix pull\n"
  2686. msgstr ""
  2687. #. type: Plain text
  2688. #: guix-git/doc/guix-cookbook.texi:2066
  2689. msgid "Now it's time to write out a config for the server. The key information is below. Save the resulting file as @file{guix-config.scm}."
  2690. msgstr ""
  2691. #. type: lisp
  2692. #: guix-git/doc/guix-cookbook.texi:2077
  2693. #, no-wrap
  2694. msgid ""
  2695. "(use-modules (gnu)\n"
  2696. " (guix modules))\n"
  2697. "(use-service-modules networking\n"
  2698. " ssh)\n"
  2699. "(use-package-modules admin\n"
  2700. " certs\n"
  2701. " package-management\n"
  2702. " ssh\n"
  2703. " tls)\n"
  2704. "\n"
  2705. msgstr ""
  2706. #. type: lisp
  2707. #: guix-git/doc/guix-cookbook.texi:2094
  2708. #, no-wrap
  2709. msgid ""
  2710. "(operating-system\n"
  2711. " (host-name \"my-server\")\n"
  2712. " (timezone \"America/New_York\")\n"
  2713. " (locale \"en_US.UTF-8\")\n"
  2714. " ;; This goofy code will generate the grub.cfg\n"
  2715. " ;; without installing the grub bootloader on disk.\n"
  2716. " (bootloader (bootloader-configuration\n"
  2717. " (bootloader\n"
  2718. " (bootloader\n"
  2719. " (inherit grub-bootloader)\n"
  2720. " (installer #~(const #true))))))\n"
  2721. " (file-systems (cons (file-system\n"
  2722. " (device \"/dev/sda\")\n"
  2723. " (mount-point \"/\")\n"
  2724. " (type \"ext4\"))\n"
  2725. " %base-file-systems))\n"
  2726. "\n"
  2727. msgstr ""
  2728. #. type: lisp
  2729. #: guix-git/doc/guix-cookbook.texi:2097
  2730. #, no-wrap
  2731. msgid ""
  2732. " (swap-devices (list \"/dev/sdb\"))\n"
  2733. "\n"
  2734. msgstr ""
  2735. #. type: lisp
  2736. #: guix-git/doc/guix-cookbook.texi:2101
  2737. #, no-wrap
  2738. msgid ""
  2739. " (initrd-modules (cons \"virtio_scsi\" ; Needed to find the disk\n"
  2740. " %base-initrd-modules))\n"
  2741. "\n"
  2742. msgstr ""
  2743. #. type: lisp
  2744. #: guix-git/doc/guix-cookbook.texi:2110
  2745. #, no-wrap
  2746. msgid ""
  2747. " (users (cons (user-account\n"
  2748. " (name \"janedoe\")\n"
  2749. " (group \"users\")\n"
  2750. " ;; Adding the account to the \"wheel\" group\n"
  2751. " ;; makes it a sudoer.\n"
  2752. " (supplementary-groups '(\"wheel\"))\n"
  2753. " (home-directory \"/home/janedoe\"))\n"
  2754. " %base-user-accounts))\n"
  2755. "\n"
  2756. msgstr ""
  2757. #. type: lisp
  2758. #: guix-git/doc/guix-cookbook.texi:2114
  2759. #, no-wrap
  2760. msgid ""
  2761. " (packages (cons* nss-certs ;for HTTPS access\n"
  2762. " openssh-sans-x\n"
  2763. " %base-packages))\n"
  2764. "\n"
  2765. msgstr ""
  2766. #. type: lisp
  2767. #: guix-git/doc/guix-cookbook.texi:2125
  2768. #, no-wrap
  2769. msgid ""
  2770. " (services (cons*\n"
  2771. " (service dhcp-client-service-type)\n"
  2772. " (service openssh-service-type\n"
  2773. " (openssh-configuration\n"
  2774. " (openssh openssh-sans-x)\n"
  2775. " (password-authentication? #false)\n"
  2776. " (authorized-keys\n"
  2777. " `((\"janedoe\" ,(local-file \"janedoe_rsa.pub\"))\n"
  2778. " (\"root\" ,(local-file \"janedoe_rsa.pub\"))))))\n"
  2779. " %base-services)))\n"
  2780. msgstr ""
  2781. #. type: Plain text
  2782. #: guix-git/doc/guix-cookbook.texi:2128
  2783. msgid "Replace the following fields in the above configuration:"
  2784. msgstr ""
  2785. #. type: lisp
  2786. #: guix-git/doc/guix-cookbook.texi:2136
  2787. #, no-wrap
  2788. msgid ""
  2789. "(host-name \"my-server\") ; replace with your server name\n"
  2790. "; if you chose a linode server outside the U.S., then\n"
  2791. "; use tzselect to find a correct timezone string\n"
  2792. "(timezone \"America/New_York\") ; if needed replace timezone\n"
  2793. "(name \"janedoe\") ; replace with your username\n"
  2794. "(\"janedoe\" ,(local-file \"janedoe_rsa.pub\")) ; replace with your ssh key\n"
  2795. "(\"root\" ,(local-file \"janedoe_rsa.pub\")) ; replace with your ssh key\n"
  2796. msgstr ""
  2797. #. type: Plain text
  2798. #: guix-git/doc/guix-cookbook.texi:2142
  2799. msgid "The last line in the above example lets you log into the server as root and set the initial root password. After you have done this, you may delete that line from your configuration and reconfigure to prevent root login."
  2800. msgstr ""
  2801. #. type: Plain text
  2802. #: guix-git/doc/guix-cookbook.texi:2147
  2803. msgid "Save your ssh public key (eg: @file{~/.ssh/id_rsa.pub}) as @file{@var{<your-username-here>}_rsa.pub} and your @file{guix-config.scm} in the same directory. In a new terminal run these commands."
  2804. msgstr ""
  2805. #. type: example
  2806. #: guix-git/doc/guix-cookbook.texi:2152
  2807. #, no-wrap
  2808. msgid ""
  2809. "sftp root@@<remote server ip address>\n"
  2810. "put /home/<username>/ssh/id_rsa.pub .\n"
  2811. "put /path/to/linode/guix-config.scm .\n"
  2812. msgstr ""
  2813. #. type: Plain text
  2814. #: guix-git/doc/guix-cookbook.texi:2155
  2815. msgid "In your first terminal, mount the guix drive:"
  2816. msgstr ""
  2817. #. type: example
  2818. #: guix-git/doc/guix-cookbook.texi:2159
  2819. #, no-wrap
  2820. msgid ""
  2821. "mkdir /mnt/guix\n"
  2822. "mount /dev/sdc /mnt/guix\n"
  2823. msgstr ""
  2824. #. type: Plain text
  2825. #: guix-git/doc/guix-cookbook.texi:2164
  2826. msgid "Due to the way we set things up above, we do not install GRUB completely. Instead we install only our grub configuration file. So we need to copy over some of the other GRUB stuff that is already there:"
  2827. msgstr ""
  2828. #. type: example
  2829. #: guix-git/doc/guix-cookbook.texi:2168
  2830. #, no-wrap
  2831. msgid ""
  2832. "mkdir -p /mnt/guix/boot/grub\n"
  2833. "cp -r /boot/grub/* /mnt/guix/boot/grub/\n"
  2834. msgstr ""
  2835. #. type: Plain text
  2836. #: guix-git/doc/guix-cookbook.texi:2171
  2837. msgid "Now initialize the Guix installation:"
  2838. msgstr ""
  2839. #. type: example
  2840. #: guix-git/doc/guix-cookbook.texi:2174
  2841. #, no-wrap
  2842. msgid "guix system init guix-config.scm /mnt/guix\n"
  2843. msgstr ""
  2844. #. type: Plain text
  2845. #: guix-git/doc/guix-cookbook.texi:2178
  2846. msgid "Ok, power it down! Now from the Linode console, select boot and select \"Guix\"."
  2847. msgstr ""
  2848. #. type: Plain text
  2849. #: guix-git/doc/guix-cookbook.texi:2181
  2850. msgid "Once it boots, you should be able to log in via SSH! (The server config will have changed though.) You may encounter an error like:"
  2851. msgstr ""
  2852. #. type: example
  2853. #: guix-git/doc/guix-cookbook.texi:2197
  2854. #, no-wrap
  2855. msgid ""
  2856. "$ ssh root@@<server ip address>\n"
  2857. "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\n"
  2858. "@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @\n"
  2859. "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\n"
  2860. "IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!\n"
  2861. "Someone could be eavesdropping on you right now (man-in-the-middle attack)!\n"
  2862. "It is also possible that a host key has just been changed.\n"
  2863. "The fingerprint for the ECDSA key sent by the remote host is\n"
  2864. "SHA256:0B+wp33w57AnKQuHCvQP0+ZdKaqYrI/kyU7CfVbS7R4.\n"
  2865. "Please contact your system administrator.\n"
  2866. "Add correct host key in /home/joshua/.ssh/known_hosts to get rid of this message.\n"
  2867. "Offending ECDSA key in /home/joshua/.ssh/known_hosts:3\n"
  2868. "ECDSA host key for 198.58.98.76 has changed and you have requested strict checking.\n"
  2869. "Host key verification failed.\n"
  2870. msgstr ""
  2871. #. type: Plain text
  2872. #: guix-git/doc/guix-cookbook.texi:2201
  2873. msgid "Either delete @file{~/.ssh/known_hosts} file, or delete the offending line starting with your server IP address."
  2874. msgstr ""
  2875. #. type: Plain text
  2876. #: guix-git/doc/guix-cookbook.texi:2203
  2877. msgid "Be sure to set your password and root's password."
  2878. msgstr ""
  2879. #. type: example
  2880. #: guix-git/doc/guix-cookbook.texi:2208
  2881. #, no-wrap
  2882. msgid ""
  2883. "ssh root@@<remote ip address>\n"
  2884. "passwd ; for the root password\n"
  2885. "passwd <username> ; for the user password\n"
  2886. msgstr ""
  2887. #. type: Plain text
  2888. #: guix-git/doc/guix-cookbook.texi:2215
  2889. msgid "You may not be able to run the above commands at this point. If you have issues remotely logging into your linode box via SSH, then you may still need to set your root and user password initially by clicking on the ``Launch Console'' option in your linode. Choose the ``Glish'' instead of ``Weblish''. Now you should be able to ssh into the machine."
  2890. msgstr ""
  2891. #. type: Plain text
  2892. #: guix-git/doc/guix-cookbook.texi:2219
  2893. msgid "Horray! At this point you can shut down the server, delete the Debian disk, and resize the Guix to the rest of the size. Congratulations!"
  2894. msgstr ""
  2895. #. type: Plain text
  2896. #: guix-git/doc/guix-cookbook.texi:2224
  2897. msgid "By the way, if you save it as a disk image right at this point, you'll have an easy time spinning up new Guix images! You may need to down-size the Guix image to 6144MB, to save it as an image. Then you can resize it again to the max size."
  2898. msgstr ""
  2899. #. type: Plain text
  2900. #: guix-git/doc/guix-cookbook.texi:2233
  2901. msgid "To bind mount a file system, one must first set up some definitions before the @code{operating-system} section of the system definition. In this example we will bind mount a folder from a spinning disk drive to @file{/tmp}, to save wear and tear on the primary SSD, without dedicating an entire partition to be mounted as @file{/tmp}."
  2902. msgstr ""
  2903. #. type: Plain text
  2904. #: guix-git/doc/guix-cookbook.texi:2236
  2905. msgid "First, the source drive that hosts the folder we wish to bind mount should be defined, so that the bind mount can depend on it."
  2906. msgstr ""
  2907. #. type: lisp
  2908. #: guix-git/doc/guix-cookbook.texi:2243
  2909. #, no-wrap
  2910. msgid ""
  2911. "(define source-drive ;; \"source-drive\" can be named anything you want.\n"
  2912. " (file-system\n"
  2913. " (device (uuid \"UUID goes here\"))\n"
  2914. " (mount-point \"/path-to-spinning-disk-goes-here\")\n"
  2915. " (type \"ext4\"))) ;; Make sure to set this to the appropriate type for your drive.\n"
  2916. msgstr ""
  2917. #. type: Plain text
  2918. #: guix-git/doc/guix-cookbook.texi:2247
  2919. msgid "The source folder must also be defined, so that guix will know it's not a regular block device, but a folder."
  2920. msgstr ""
  2921. #. type: lisp
  2922. #: guix-git/doc/guix-cookbook.texi:2249
  2923. #, no-wrap
  2924. msgid "(define (%source-directory) \"/path-to-spinning-disk-goes-here/tmp\") ;; \"source-directory\" can be named any valid variable name.\n"
  2925. msgstr ""
  2926. #. type: Plain text
  2927. #: guix-git/doc/guix-cookbook.texi:2253
  2928. msgid "Finally, inside the @code{file-systems} definition, we must add the mount itself."
  2929. msgstr ""
  2930. #. type: lisp
  2931. #: guix-git/doc/guix-cookbook.texi:2256
  2932. #, no-wrap
  2933. msgid ""
  2934. "(file-systems (cons*\n"
  2935. "\n"
  2936. msgstr ""
  2937. #. type: lisp
  2938. #: guix-git/doc/guix-cookbook.texi:2258
  2939. #, no-wrap
  2940. msgid ""
  2941. " ...<other drives omitted for clarity>...\n"
  2942. "\n"
  2943. msgstr ""
  2944. #. type: lisp
  2945. #: guix-git/doc/guix-cookbook.texi:2260
  2946. #, no-wrap
  2947. msgid ""
  2948. " source-drive ;; Must match the name you gave the source drive in the earlier definition.\n"
  2949. "\n"
  2950. msgstr ""
  2951. #. type: lisp
  2952. #: guix-git/doc/guix-cookbook.texi:2268
  2953. #, no-wrap
  2954. msgid ""
  2955. " (file-system\n"
  2956. " (device (%source-directory)) ;; Make sure \"source-directory\" matches your earlier definition.\n"
  2957. " (mount-point \"/tmp\")\n"
  2958. " (type \"none\") ;; We are mounting a folder, not a partition, so this type needs to be \"none\"\n"
  2959. " (flags '(bind-mount))\n"
  2960. " (dependencies (list source-drive)) ;; Ensure \"source-drive\" matches what you've named the variable for the drive.\n"
  2961. " )\n"
  2962. "\n"
  2963. msgstr ""
  2964. #. type: lisp
  2965. #: guix-git/doc/guix-cookbook.texi:2270
  2966. #, no-wrap
  2967. msgid ""
  2968. " ...<other drives omitted for clarity>...\n"
  2969. "\n"
  2970. msgstr ""
  2971. #. type: lisp
  2972. #: guix-git/doc/guix-cookbook.texi:2272
  2973. #, no-wrap
  2974. msgid " ))\n"
  2975. msgstr ""
  2976. #. type: Plain text
  2977. #: guix-git/doc/guix-cookbook.texi:2279
  2978. msgid "Guix daemon can use a HTTP proxy to get substitutes, here we are configuring it to get them via Tor."
  2979. msgstr ""
  2980. #. type: quotation
  2981. #: guix-git/doc/guix-cookbook.texi:2280
  2982. #, no-wrap
  2983. msgid "Warning"
  2984. msgstr ""
  2985. #. type: quotation
  2986. #: guix-git/doc/guix-cookbook.texi:2286
  2987. msgid "@emph{Not all} Guix daemon's traffic will go through Tor! Only HTTP/HTTPS will get proxied; FTP, Git protocol, SSH, etc connections will still go through the clearnet. Again, this configuration isn't foolproof some of your traffic won't get routed by Tor at all. Use it at your own risk."
  2988. msgstr ""
  2989. #. type: quotation
  2990. #: guix-git/doc/guix-cookbook.texi:2292
  2991. msgid "Also note that the procedure described here applies only to package substitution. When you update your guix distribution with @command{guix pull}, you still need to use @command{torsocks} if you want to route the connection to guix's git repository servers through Tor."
  2992. msgstr ""
  2993. #. type: Plain text
  2994. #: guix-git/doc/guix-cookbook.texi:2297
  2995. msgid "Guix's substitute server is available as a Onion service, if you want to use it to get your substitutes through Tor configure your system as follow:"
  2996. msgstr ""
  2997. #. type: lisp
  2998. #: guix-git/doc/guix-cookbook.texi:2301
  2999. #, no-wrap
  3000. msgid ""
  3001. "(use-modules (gnu))\n"
  3002. "(use-service-module base networking)\n"
  3003. "\n"
  3004. msgstr ""
  3005. #. type: lisp
  3006. #: guix-git/doc/guix-cookbook.texi:2317
  3007. #, no-wrap
  3008. msgid ""
  3009. "(operating-system\n"
  3010. " …\n"
  3011. " (services\n"
  3012. " (cons\n"
  3013. " (service tor-service-type\n"
  3014. " (tor-configuration\n"
  3015. " (config-file (plain-file \"tor-config\"\n"
  3016. " \"HTTPTunnelPort 127.0.0.1:9250\"))))\n"
  3017. " (modify-services %base-services\n"
  3018. " (guix-service-type\n"
  3019. " config => (guix-configuration\n"
  3020. " (inherit config)\n"
  3021. " ;; ci.guix.gnu.org's Onion service\n"
  3022. " (substitute-urls \"https://bp7o7ckwlewr4slm.onion\")\n"
  3023. " (http-proxy \"http://localhost:9250\")))))))\n"
  3024. msgstr ""
  3025. #. type: Plain text
  3026. #: guix-git/doc/guix-cookbook.texi:2326
  3027. msgid "This will keep a tor process running that provides a HTTP CONNECT tunnel which will be used by @command{guix-daemon}. The daemon can use other protocols than HTTP(S) to get remote resources, request using those protocols won't go through Tor since we are only setting a HTTP tunnel here. Note that @code{substitutes-urls} is using HTTPS and not HTTP or it won't work, that's a limitation of Tor's tunnel; you may want to use @command{privoxy} instead to avoid such limitations."
  3028. msgstr ""
  3029. #. type: Plain text
  3030. #: guix-git/doc/guix-cookbook.texi:2330
  3031. msgid "If you don't want to always get substitutes through Tor but using it just some of the times, then skip the @code{guix-configuration}. When you want to get a substitute from the Tor tunnel run:"
  3032. msgstr ""
  3033. #. type: example
  3034. #: guix-git/doc/guix-cookbook.texi:2334
  3035. #, no-wrap
  3036. msgid ""
  3037. "sudo herd set-http-proxy guix-daemon http://localhost:9250\n"
  3038. "guix build --substitute-urls=https://bp7o7ckwlewr4slm.onion …\n"
  3039. msgstr ""
  3040. #. type: cindex
  3041. #: guix-git/doc/guix-cookbook.texi:2338
  3042. #, no-wrap
  3043. msgid "nginx, lua, openresty, resty"
  3044. msgstr ""
  3045. #. type: Plain text
  3046. #: guix-git/doc/guix-cookbook.texi:2341
  3047. msgid "NGINX could be extended with Lua scripts."
  3048. msgstr ""
  3049. #. type: Plain text
  3050. #: guix-git/doc/guix-cookbook.texi:2344
  3051. msgid "Guix provides NGINX service with ability to load Lua module and specific Lua packages, and reply to requests by evaluating Lua scripts."
  3052. msgstr ""
  3053. #. type: Plain text
  3054. #: guix-git/doc/guix-cookbook.texi:2348
  3055. msgid "The following example demonstrates system definition with configuration to evaluate @file{index.lua} Lua script on HTTP request to @uref{http://localhost/hello} endpoint:"
  3056. msgstr ""
  3057. #. type: example
  3058. #: guix-git/doc/guix-cookbook.texi:2351
  3059. #, no-wrap
  3060. msgid ""
  3061. "local shell = require \"resty.shell\"\n"
  3062. "\n"
  3063. msgstr ""
  3064. #. type: example
  3065. #: guix-git/doc/guix-cookbook.texi:2355
  3066. #, no-wrap
  3067. msgid ""
  3068. "local stdin = \"\"\n"
  3069. "local timeout = 1000 -- ms\n"
  3070. "local max_size = 4096 -- byte\n"
  3071. "\n"
  3072. msgstr ""
  3073. #. type: example
  3074. #: guix-git/doc/guix-cookbook.texi:2358
  3075. #, no-wrap
  3076. msgid ""
  3077. "local ok, stdout, stderr, reason, status =\n"
  3078. " shell.run([[/run/current-system/profile/bin/ls /tmp]], stdin, timeout, max_size)\n"
  3079. "\n"
  3080. msgstr ""
  3081. #. type: example
  3082. #: guix-git/doc/guix-cookbook.texi:2360
  3083. #, no-wrap
  3084. msgid "ngx.say(stdout)\n"
  3085. msgstr ""
  3086. #. type: lisp
  3087. #: guix-git/doc/guix-cookbook.texi:2391
  3088. #, no-wrap
  3089. msgid ""
  3090. "(use-modules (gnu))\n"
  3091. "(use-service-modules #;… web)\n"
  3092. "(use-package-modules #;… lua)\n"
  3093. "(operating-system\n"
  3094. " ;; …\n"
  3095. " (services\n"
  3096. " ;; …\n"
  3097. " (service nginx-service-type\n"
  3098. " (nginx-configuration\n"
  3099. " (modules\n"
  3100. " (list\n"
  3101. " (file-append nginx-lua-module \"/etc/nginx/modules/ngx_http_lua_module.so\")))\n"
  3102. " (lua-package-path (list lua-resty-core\n"
  3103. " lua-resty-lrucache\n"
  3104. " lua-resty-signal\n"
  3105. " lua-tablepool\n"
  3106. " lua-resty-shell))\n"
  3107. " (lua-package-cpath (list lua-resty-signal))\n"
  3108. " (server-blocks\n"
  3109. " (list (nginx-server-configuration\n"
  3110. " (server-name '(\"localhost\"))\n"
  3111. " (listen '(\"80\"))\n"
  3112. " (root \"/etc\")\n"
  3113. " (locations (list\n"
  3114. " (nginx-location-configuration\n"
  3115. " (uri \"/hello\")\n"
  3116. " (body (list #~(format #f \"content_by_lua_file ~s;\"\n"
  3117. " #$(local-file \"index.lua\"))))))))))))))\n"
  3118. msgstr ""
  3119. #. type: Plain text
  3120. #: guix-git/doc/guix-cookbook.texi:2402
  3121. msgid "Guix is a functional package manager that offers many features beyond what more traditional package managers can do. To the uninitiated, those features might not have obvious use cases at first. The purpose of this chapter is to demonstrate some advanced package management concepts."
  3122. msgstr ""
  3123. #. type: Plain text
  3124. #: guix-git/doc/guix-cookbook.texi:2405
  3125. msgid "@pxref{Package Management,,, guix, GNU Guix Reference Manual} for a complete reference."
  3126. msgstr ""
  3127. #. type: section
  3128. #: guix-git/doc/guix-cookbook.texi:2408 guix-git/doc/guix-cookbook.texi:2410
  3129. #: guix-git/doc/guix-cookbook.texi:2411
  3130. #, no-wrap
  3131. msgid "Guix Profiles in Practice"
  3132. msgstr ""
  3133. #. type: menuentry
  3134. #: guix-git/doc/guix-cookbook.texi:2408
  3135. msgid "Strategies for multiple profiles and manifests."
  3136. msgstr ""
  3137. #. type: Plain text
  3138. #: guix-git/doc/guix-cookbook.texi:2416
  3139. msgid "Guix provides a very useful feature that may be quite foreign to newcomers: @emph{profiles}. They are a way to group package installations together and all users on the same system are free to use as many profiles as they want."
  3140. msgstr ""
  3141. #. type: Plain text
  3142. #: guix-git/doc/guix-cookbook.texi:2421
  3143. msgid "Whether you're a developer or not, you may find that multiple profiles bring you great power and flexibility. While they shift the paradigm somewhat compared to @emph{traditional package managers}, they are very convenient to use once you've understood how to set them up."
  3144. msgstr ""
  3145. #. type: Plain text
  3146. #: guix-git/doc/guix-cookbook.texi:2427
  3147. msgid "If you are familiar with Python's @samp{virtualenv}, you can think of a profile as a kind of universal @samp{virtualenv} that can hold any kind of software whatsoever, not just Python software. Furthermore, profiles are self-sufficient: they capture all the runtime dependencies which guarantees that all programs within a profile will always work at any point in time."
  3148. msgstr ""
  3149. #. type: Plain text
  3150. #: guix-git/doc/guix-cookbook.texi:2429
  3151. msgid "Multiple profiles have many benefits:"
  3152. msgstr ""
  3153. #. type: itemize
  3154. #: guix-git/doc/guix-cookbook.texi:2433
  3155. msgid "Clean semantic separation of the various packages a user needs for different contexts."
  3156. msgstr ""
  3157. #. type: itemize
  3158. #: guix-git/doc/guix-cookbook.texi:2437
  3159. msgid "Multiple profiles can be made available into the environment either on login or within a dedicated shell."
  3160. msgstr ""
  3161. #. type: itemize
  3162. #: guix-git/doc/guix-cookbook.texi:2441
  3163. msgid "Profiles can be loaded on demand. For instance, the user can use multiple shells, each of them running different profiles."
  3164. msgstr ""
  3165. #. type: itemize
  3166. #: guix-git/doc/guix-cookbook.texi:2446
  3167. msgid "Isolation: Programs from one profile will not use programs from the other, and the user can even install different versions of the same programs to the two profiles without conflict."
  3168. msgstr ""
  3169. #. type: itemize
  3170. #: guix-git/doc/guix-cookbook.texi:2450
  3171. msgid "Deduplication: Profiles share dependencies that happens to be the exact same. This makes multiple profiles storage-efficient."
  3172. msgstr ""
  3173. #. type: itemize
  3174. #: guix-git/doc/guix-cookbook.texi:2458
  3175. msgid "Reproducible: when used with declarative manifests, a profile can be fully specified by the Guix commit that was active when it was set up. This means that the exact same profile can be @uref{https://guix.gnu.org/blog/2018/multi-dimensional-transactions-and-rollbacks-oh-my/, set up anywhere and anytime}, with just the commit information. See the section on @ref{Reproducible profiles}."
  3176. msgstr ""
  3177. #. type: itemize
  3178. #: guix-git/doc/guix-cookbook.texi:2462
  3179. msgid "Easier upgrades and maintenance: Multiple profiles make it easy to keep package listings at hand and make upgrades completely frictionless."
  3180. msgstr ""
  3181. #. type: Plain text
  3182. #: guix-git/doc/guix-cookbook.texi:2465
  3183. msgid "Concretely, here follows some typical profiles:"
  3184. msgstr ""
  3185. #. type: itemize
  3186. #: guix-git/doc/guix-cookbook.texi:2469
  3187. msgid "The dependencies of a project you are working on."
  3188. msgstr ""
  3189. #. type: itemize
  3190. #: guix-git/doc/guix-cookbook.texi:2472
  3191. msgid "Your favourite programming language libraries."
  3192. msgstr ""
  3193. #. type: itemize
  3194. #: guix-git/doc/guix-cookbook.texi:2475
  3195. msgid "Laptop-specific programs (like @samp{powertop}) that you don't need on a desktop."
  3196. msgstr ""
  3197. #. type: itemize
  3198. #: guix-git/doc/guix-cookbook.texi:2479
  3199. msgid "@TeX{}live (this one can be really useful when you need to install just one package for this one document you've just received over email)."
  3200. msgstr ""
  3201. #. type: itemize
  3202. #: guix-git/doc/guix-cookbook.texi:2482
  3203. msgid "Games."
  3204. msgstr ""
  3205. #. type: Plain text
  3206. #: guix-git/doc/guix-cookbook.texi:2485
  3207. msgid "Let's dive in the set up!"
  3208. msgstr ""
  3209. #. type: subsection
  3210. #: guix-git/doc/guix-cookbook.texi:2486 guix-git/doc/guix-cookbook.texi:2487
  3211. #, no-wrap
  3212. msgid "Basic setup with manifests"
  3213. msgstr ""
  3214. #. type: Plain text
  3215. #: guix-git/doc/guix-cookbook.texi:2491
  3216. msgid "A Guix profile can be set up @emph{via} a so-called @emph{manifest specification} that looks like this:"
  3217. msgstr ""
  3218. #. type: lisp
  3219. #: guix-git/doc/guix-cookbook.texi:2501
  3220. #, no-wrap
  3221. msgid ""
  3222. "(specifications->manifest\n"
  3223. " '(\"package-1\"\n"
  3224. " ;; Version 1.3 of package-2.\n"
  3225. " \"package-2@@1.3\"\n"
  3226. " ;; The \"lib\" output of package-3.\n"
  3227. " \"package-3:lib\"\n"
  3228. " ; ...\n"
  3229. " \"package-N\"))\n"
  3230. msgstr ""
  3231. #. type: Plain text
  3232. #: guix-git/doc/guix-cookbook.texi:2505
  3233. msgid "@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}, for the syntax details."
  3234. msgstr ""
  3235. #. type: Plain text
  3236. #: guix-git/doc/guix-cookbook.texi:2507
  3237. msgid "We can create a manifest specification per profile and install them this way:"
  3238. msgstr ""
  3239. #. type: example
  3240. #: guix-git/doc/guix-cookbook.texi:2512
  3241. #, no-wrap
  3242. msgid ""
  3243. "GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles\n"
  3244. "mkdir -p \"$GUIX_EXTRA_PROFILES\"/my-project # if it does not exist yet\n"
  3245. "guix package --manifest=/path/to/guix-my-project-manifest.scm --profile=\"$GUIX_EXTRA_PROFILES\"/my-project/my-project\n"
  3246. msgstr ""
  3247. #. type: Plain text
  3248. #: guix-git/doc/guix-cookbook.texi:2516
  3249. msgid "Here we set an arbitrary variable @samp{GUIX_EXTRA_PROFILES} to point to the directory where we will store our profiles in the rest of this article."
  3250. msgstr ""
  3251. #. type: Plain text
  3252. #: guix-git/doc/guix-cookbook.texi:2522
  3253. msgid "Placing all your profiles in a single directory, with each profile getting its own sub-directory, is somewhat cleaner. This way, each sub-directory will contain all the symlinks for precisely one profile. Besides, ``looping over profiles'' becomes obvious from any programming language (e.g.@: a shell script) by simply looping over the sub-directories of @samp{$GUIX_EXTRA_PROFILES}."
  3254. msgstr ""
  3255. #. type: Plain text
  3256. #: guix-git/doc/guix-cookbook.texi:2524
  3257. msgid "Note that it's also possible to loop over the output of"
  3258. msgstr ""
  3259. #. type: example
  3260. #: guix-git/doc/guix-cookbook.texi:2527
  3261. #, no-wrap
  3262. msgid "guix package --list-profiles\n"
  3263. msgstr ""
  3264. #. type: Plain text
  3265. #: guix-git/doc/guix-cookbook.texi:2530
  3266. msgid "although you'll probably have to filter out @file{~/.config/guix/current}."
  3267. msgstr ""
  3268. #. type: Plain text
  3269. #: guix-git/doc/guix-cookbook.texi:2532
  3270. msgid "To enable all profiles on login, add this to your @file{~/.bash_profile} (or similar):"
  3271. msgstr ""
  3272. #. type: example
  3273. #: guix-git/doc/guix-cookbook.texi:2542
  3274. #, no-wrap
  3275. msgid ""
  3276. "for i in $GUIX_EXTRA_PROFILES/*; do\n"
  3277. " profile=$i/$(basename \"$i\")\n"
  3278. " if [ -f \"$profile\"/etc/profile ]; then\n"
  3279. " GUIX_PROFILE=\"$profile\"\n"
  3280. " . \"$GUIX_PROFILE\"/etc/profile\n"
  3281. " fi\n"
  3282. " unset profile\n"
  3283. "done\n"
  3284. msgstr ""
  3285. #. type: Plain text
  3286. #: guix-git/doc/guix-cookbook.texi:2547
  3287. msgid "Note to Guix System users: the above reflects how your default profile @file{~/.guix-profile} is activated from @file{/etc/profile}, that latter being loaded by @file{~/.bashrc} by default."
  3288. msgstr ""
  3289. #. type: Plain text
  3290. #: guix-git/doc/guix-cookbook.texi:2549
  3291. msgid "You can obviously choose to only enable a subset of them:"
  3292. msgstr ""
  3293. #. type: example
  3294. #: guix-git/doc/guix-cookbook.texi:2559
  3295. #, no-wrap
  3296. msgid ""
  3297. "for i in \"$GUIX_EXTRA_PROFILES\"/my-project-1 \"$GUIX_EXTRA_PROFILES\"/my-project-2; do\n"
  3298. " profile=$i/$(basename \"$i\")\n"
  3299. " if [ -f \"$profile\"/etc/profile ]; then\n"
  3300. " GUIX_PROFILE=\"$profile\"\n"
  3301. " . \"$GUIX_PROFILE\"/etc/profile\n"
  3302. " fi\n"
  3303. " unset profile\n"
  3304. "done\n"
  3305. msgstr ""
  3306. #. type: Plain text
  3307. #: guix-git/doc/guix-cookbook.texi:2563
  3308. msgid "When a profile is off, it's straightforward to enable it for an individual shell without \"polluting\" the rest of the user session:"
  3309. msgstr ""
  3310. #. type: example
  3311. #: guix-git/doc/guix-cookbook.texi:2566
  3312. #, no-wrap
  3313. msgid "GUIX_PROFILE=\"path/to/my-project\" ; . \"$GUIX_PROFILE\"/etc/profile\n"
  3314. msgstr ""
  3315. #. type: Plain text
  3316. #: guix-git/doc/guix-cookbook.texi:2573
  3317. msgid "The key to enabling a profile is to @emph{source} its @samp{etc/profile} file. This file contains shell code that exports the right environment variables necessary to activate the software contained in the profile. It is built automatically by Guix and meant to be sourced. It contains the same variables you would get if you ran:"
  3318. msgstr ""
  3319. #. type: example
  3320. #: guix-git/doc/guix-cookbook.texi:2576
  3321. #, no-wrap
  3322. msgid "guix package --search-paths=prefix --profile=$my_profile\"\n"
  3323. msgstr ""
  3324. #. type: Plain text
  3325. #: guix-git/doc/guix-cookbook.texi:2580
  3326. msgid "Once again, see (@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}) for the command line options."
  3327. msgstr ""
  3328. #. type: Plain text
  3329. #: guix-git/doc/guix-cookbook.texi:2582
  3330. msgid "To upgrade a profile, simply install the manifest again:"
  3331. msgstr ""
  3332. #. type: example
  3333. #: guix-git/doc/guix-cookbook.texi:2585
  3334. #, no-wrap
  3335. msgid "guix package -m /path/to/guix-my-project-manifest.scm -p \"$GUIX_EXTRA_PROFILES\"/my-project/my-project\n"
  3336. msgstr ""
  3337. #. type: Plain text
  3338. #: guix-git/doc/guix-cookbook.texi:2591
  3339. msgid "To upgrade all profiles, it's easy enough to loop over them. For instance, assuming your manifest specifications are stored in @file{~/.guix-manifests/guix-$profile-manifest.scm}, with @samp{$profile} being the name of the profile (e.g.@: \"project1\"), you could do the following in Bourne shell:"
  3340. msgstr ""
  3341. #. type: example
  3342. #: guix-git/doc/guix-cookbook.texi:2596
  3343. #, no-wrap
  3344. msgid ""
  3345. "for profile in \"$GUIX_EXTRA_PROFILES\"/*; do\n"
  3346. " guix package --profile=\"$profile\" --manifest=\"$HOME/.guix-manifests/guix-$profile-manifest.scm\"\n"
  3347. "done\n"
  3348. msgstr ""
  3349. #. type: Plain text
  3350. #: guix-git/doc/guix-cookbook.texi:2599
  3351. msgid "Each profile has its own generations:"
  3352. msgstr ""
  3353. #. type: example
  3354. #: guix-git/doc/guix-cookbook.texi:2602
  3355. #, no-wrap
  3356. msgid "guix package -p \"$GUIX_EXTRA_PROFILES\"/my-project/my-project --list-generations\n"
  3357. msgstr ""
  3358. #. type: Plain text
  3359. #: guix-git/doc/guix-cookbook.texi:2605
  3360. msgid "You can roll-back to any generation of a given profile:"
  3361. msgstr ""
  3362. #. type: example
  3363. #: guix-git/doc/guix-cookbook.texi:2608
  3364. #, no-wrap
  3365. msgid "guix package -p \"$GUIX_EXTRA_PROFILES\"/my-project/my-project --switch-generations=17\n"
  3366. msgstr ""
  3367. #. type: Plain text
  3368. #: guix-git/doc/guix-cookbook.texi:2612
  3369. msgid "Finally, if you want to switch to a profile without inheriting from the current environment, you can activate it from an empty shell:"
  3370. msgstr ""
  3371. #. type: example
  3372. #: guix-git/doc/guix-cookbook.texi:2616
  3373. #, no-wrap
  3374. msgid ""
  3375. "env -i $(which bash) --login --noprofile --norc\n"
  3376. ". my-project/etc/profile\n"
  3377. msgstr ""
  3378. #. type: subsection
  3379. #: guix-git/doc/guix-cookbook.texi:2618 guix-git/doc/guix-cookbook.texi:2619
  3380. #, no-wrap
  3381. msgid "Required packages"
  3382. msgstr ""
  3383. #. type: Plain text
  3384. #: guix-git/doc/guix-cookbook.texi:2624
  3385. msgid "Activating a profile essentially boils down to exporting a bunch of environmental variables. This is the role of the @samp{etc/profile} within the profile."
  3386. msgstr ""
  3387. #. type: emph{#1}
  3388. #: guix-git/doc/guix-cookbook.texi:2627
  3389. msgid "Note: Only the environmental variables of the packages that consume them will be set."
  3390. msgstr ""
  3391. #. type: Plain text
  3392. #: guix-git/doc/guix-cookbook.texi:2631
  3393. msgid "For instance, @samp{MANPATH} won't be set if there is no consumer application for man pages within the profile. So if you need to transparently access man pages once the profile is loaded, you've got two options:"
  3394. msgstr ""
  3395. #. type: itemize
  3396. #: guix-git/doc/guix-cookbook.texi:2635
  3397. msgid "Either export the variable manually, e.g."
  3398. msgstr ""
  3399. #. type: example
  3400. #: guix-git/doc/guix-cookbook.texi:2637
  3401. #, no-wrap
  3402. msgid "export MANPATH=/path/to/profile$@{MANPATH:+:@}$MANPATH\n"
  3403. msgstr ""
  3404. #. type: itemize
  3405. #: guix-git/doc/guix-cookbook.texi:2641
  3406. msgid "Or include @samp{man-db} to the profile manifest."
  3407. msgstr ""
  3408. #. type: Plain text
  3409. #: guix-git/doc/guix-cookbook.texi:2645
  3410. msgid "The same is true for @samp{INFOPATH} (you can install @samp{info-reader}), @samp{PKG_CONFIG_PATH} (install @samp{pkg-config}), etc."
  3411. msgstr ""
  3412. #. type: subsection
  3413. #: guix-git/doc/guix-cookbook.texi:2646 guix-git/doc/guix-cookbook.texi:2647
  3414. #, no-wrap
  3415. msgid "Default profile"
  3416. msgstr ""
  3417. #. type: Plain text
  3418. #: guix-git/doc/guix-cookbook.texi:2650
  3419. msgid "What about the default profile that Guix keeps in @file{~/.guix-profile}?"
  3420. msgstr ""
  3421. #. type: Plain text
  3422. #: guix-git/doc/guix-cookbook.texi:2653
  3423. msgid "You can assign it the role you want. Typically you would install the manifest of the packages you want to use all the time."
  3424. msgstr ""
  3425. #. type: Plain text
  3426. #: guix-git/doc/guix-cookbook.texi:2657
  3427. msgid "Alternatively, you could keep it ``manifest-less'' for throw-away packages that you would just use for a couple of days. This way makes it convenient to run"
  3428. msgstr ""
  3429. #. type: example
  3430. #: guix-git/doc/guix-cookbook.texi:2661
  3431. #, no-wrap
  3432. msgid ""
  3433. "guix install package-foo\n"
  3434. "guix upgrade package-bar\n"
  3435. msgstr ""
  3436. #. type: Plain text
  3437. #: guix-git/doc/guix-cookbook.texi:2664
  3438. msgid "without having to specify the path to a profile."
  3439. msgstr ""
  3440. #. type: subsection
  3441. #: guix-git/doc/guix-cookbook.texi:2665 guix-git/doc/guix-cookbook.texi:2666
  3442. #, no-wrap
  3443. msgid "The benefits of manifests"
  3444. msgstr ""
  3445. #. type: Plain text
  3446. #: guix-git/doc/guix-cookbook.texi:2670
  3447. msgid "Manifests are a convenient way to keep your package lists around and, say, to synchronize them across multiple machines using a version control system."
  3448. msgstr ""
  3449. #. type: Plain text
  3450. #: guix-git/doc/guix-cookbook.texi:2674
  3451. msgid "A common complaint about manifests is that they can be slow to install when they contain large number of packages. This is especially cumbersome when you just want get an upgrade for one package within a big manifest."
  3452. msgstr ""
  3453. #. type: Plain text
  3454. #: guix-git/doc/guix-cookbook.texi:2679
  3455. msgid "This is one more reason to use multiple profiles, which happen to be just perfect to break down manifests into multiple sets of semantically connected packages. Using multiple, small profiles provides more flexibility and usability."
  3456. msgstr ""
  3457. #. type: Plain text
  3458. #: guix-git/doc/guix-cookbook.texi:2681
  3459. msgid "Manifests come with multiple benefits. In particular, they ease maintenance:"
  3460. msgstr ""
  3461. #. type: itemize
  3462. #: guix-git/doc/guix-cookbook.texi:2689
  3463. msgid "When a profile is set up from a manifest, the manifest itself is self-sufficient to keep a ``package listing'' around and reinstall the profile later or on a different system. For ad-hoc profiles, we would need to generate a manifest specification manually and maintain the package versions for the packages that don't use the default version."
  3464. msgstr ""
  3465. #. type: itemize
  3466. #: guix-git/doc/guix-cookbook.texi:2694
  3467. msgid "@code{guix package --upgrade} always tries to update the packages that have propagated inputs, even if there is nothing to do. Guix manifests remove this problem."
  3468. msgstr ""
  3469. #. type: itemize
  3470. #: guix-git/doc/guix-cookbook.texi:2700
  3471. msgid "When partially upgrading a profile, conflicts may arise (due to diverging dependencies between the updated and the non-updated packages) and they can be annoying to resolve manually. Manifests remove this problem altogether since all packages are always upgraded at once."
  3472. msgstr ""
  3473. #. type: itemize
  3474. #: guix-git/doc/guix-cookbook.texi:2706
  3475. msgid "As mentioned above, manifests allow for reproducible profiles, while the imperative @code{guix install}, @code{guix upgrade}, etc. do not, since they produce different profiles every time even when they hold the same packages. See @uref{https://issues.guix.gnu.org/issue/33285, the related discussion on the matter}."
  3476. msgstr ""
  3477. #. type: itemize
  3478. #: guix-git/doc/guix-cookbook.texi:2714
  3479. msgid "Manifest specifications are usable by other @samp{guix} commands. For example, you can run @code{guix weather -m manifest.scm} to see how many substitutes are available, which can help you decide whether you want to try upgrading today or wait a while. Another example: you can run @code{guix pack -m manifest.scm} to create a pack containing all the packages in the manifest (and their transitive references)."
  3480. msgstr ""
  3481. #. type: itemize
  3482. #: guix-git/doc/guix-cookbook.texi:2718
  3483. msgid "Finally, manifests have a Scheme representation, the @samp{<manifest>} record type. They can be manipulated in Scheme and passed to the various Guix @uref{https://en.wikipedia.org/wiki/Api, APIs}."
  3484. msgstr ""
  3485. #. type: Plain text
  3486. #: guix-git/doc/guix-cookbook.texi:2726
  3487. msgid "It's important to understand that while manifests can be used to declare profiles, they are not strictly equivalent: profiles have the side effect that they ``pin'' packages in the store, which prevents them from being garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual}) and ensures that they will still be available at any point in the future."
  3488. msgstr ""
  3489. #. type: Plain text
  3490. #: guix-git/doc/guix-cookbook.texi:2728
  3491. msgid "Let's take an example:"
  3492. msgstr ""
  3493. #. type: enumerate
  3494. #: guix-git/doc/guix-cookbook.texi:2734
  3495. msgid "We have an environment for hacking on a project for which there isn't a Guix package yet. We build the environment using a manifest, and then run @code{guix environment -m manifest.scm}. So far so good."
  3496. msgstr ""
  3497. #. type: enumerate
  3498. #: guix-git/doc/guix-cookbook.texi:2740
  3499. msgid "Many weeks pass and we have run a couple of @code{guix pull} in the mean time. Maybe a dependency from our manifest has been updated; or we may have run @code{guix gc} and some packages needed by our manifest have been garbage-collected."
  3500. msgstr ""
  3501. #. type: enumerate
  3502. #: guix-git/doc/guix-cookbook.texi:2745
  3503. msgid "Eventually, we set to work on that project again, so we run @code{guix environment -m manifest.scm}. But now we have to wait for Guix to build and install stuff!"
  3504. msgstr ""
  3505. #. type: Plain text
  3506. #: guix-git/doc/guix-cookbook.texi:2751
  3507. msgid "Ideally, we could spare the rebuild time. And indeed we can, all we need is to install the manifest to a profile and use @code{GUIX_PROFILE=/the/profile; . \"$GUIX_PROFILE\"/etc/profile} as explained above: this guarantees that our hacking environment will be available at all times."
  3508. msgstr ""
  3509. #. type: Plain text
  3510. #: guix-git/doc/guix-cookbook.texi:2754
  3511. msgid "@emph{Security warning:} While keeping old profiles around can be convenient, keep in mind that outdated packages may not have received the latest security fixes."
  3512. msgstr ""
  3513. #. type: subsection
  3514. #: guix-git/doc/guix-cookbook.texi:2755 guix-git/doc/guix-cookbook.texi:2756
  3515. #, no-wrap
  3516. msgid "Reproducible profiles"
  3517. msgstr ""
  3518. #. type: Plain text
  3519. #: guix-git/doc/guix-cookbook.texi:2759
  3520. msgid "To reproduce a profile bit-for-bit, we need two pieces of information:"
  3521. msgstr ""
  3522. #. type: itemize
  3523. #: guix-git/doc/guix-cookbook.texi:2763
  3524. msgid "a manifest,"
  3525. msgstr ""
  3526. #. type: itemize
  3527. #: guix-git/doc/guix-cookbook.texi:2765
  3528. msgid "a Guix channel specification."
  3529. msgstr ""
  3530. #. type: Plain text
  3531. #: guix-git/doc/guix-cookbook.texi:2769
  3532. msgid "Indeed, manifests alone might not be enough: different Guix versions (or different channels) can produce different outputs for a given manifest."
  3533. msgstr ""
  3534. #. type: Plain text
  3535. #: guix-git/doc/guix-cookbook.texi:2773
  3536. msgid "You can output the Guix channel specification with @samp{guix describe --format=channels}. Save this to a file, say @samp{channel-specs.scm}."
  3537. msgstr ""
  3538. #. type: Plain text
  3539. #: guix-git/doc/guix-cookbook.texi:2776
  3540. msgid "On another computer, you can use the channel specification file and the manifest to reproduce the exact same profile:"
  3541. msgstr ""
  3542. #. type: example
  3543. #: guix-git/doc/guix-cookbook.texi:2780
  3544. #, no-wrap
  3545. msgid ""
  3546. "GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles\n"
  3547. "GUIX_EXTRA=$HOME/.guix-extra\n"
  3548. "\n"
  3549. msgstr ""
  3550. #. type: example
  3551. #: guix-git/doc/guix-cookbook.texi:2783
  3552. #, no-wrap
  3553. msgid ""
  3554. "mkdir \"$GUIX_EXTRA\"/my-project\n"
  3555. "guix pull --channels=channel-specs.scm --profile \"$GUIX_EXTRA/my-project/guix\"\n"
  3556. "\n"
  3557. msgstr ""
  3558. #. type: example
  3559. #: guix-git/doc/guix-cookbook.texi:2786
  3560. #, no-wrap
  3561. msgid ""
  3562. "mkdir -p \"$GUIX_EXTRA_PROFILES/my-project\"\n"
  3563. "\"$GUIX_EXTRA\"/my-project/guix/bin/guix package --manifest=/path/to/guix-my-project-manifest.scm --profile=\"$GUIX_EXTRA_PROFILES\"/my-project/my-project\n"
  3564. msgstr ""
  3565. #. type: Plain text
  3566. #: guix-git/doc/guix-cookbook.texi:2790
  3567. msgid "It's safe to delete the Guix channel profile you've just installed with the channel specification, the project profile does not depend on it."
  3568. msgstr ""
  3569. #. type: Plain text
  3570. #: guix-git/doc/guix-cookbook.texi:2797
  3571. msgid "Guix provides multiple tools to manage environment. This chapter demonstrate such utilities."
  3572. msgstr ""
  3573. #. type: section
  3574. #: guix-git/doc/guix-cookbook.texi:2800 guix-git/doc/guix-cookbook.texi:2802
  3575. #: guix-git/doc/guix-cookbook.texi:2803
  3576. #, no-wrap
  3577. msgid "Guix environment via direnv"
  3578. msgstr ""
  3579. #. type: menuentry
  3580. #: guix-git/doc/guix-cookbook.texi:2800
  3581. msgid "Setup Guix environment with direnv"
  3582. msgstr ""
  3583. #. type: Plain text
  3584. #: guix-git/doc/guix-cookbook.texi:2808
  3585. msgid "Guix provides a @samp{direnv} package, which could extend shell after directory change. This tool could be used to prepare a pure Guix environment."
  3586. msgstr ""
  3587. #. type: Plain text
  3588. #: guix-git/doc/guix-cookbook.texi:2814
  3589. msgid "The following example provides a shell function for @file{~/.direnvrc} file, which could be used from Guix Git repository in @file{~/src/guix/.envrc} file to setup a build environment similar to described in @pxref{Building from Git,,, guix, GNU Guix Reference Manual}."
  3590. msgstr ""
  3591. #. type: Plain text
  3592. #: guix-git/doc/guix-cookbook.texi:2816
  3593. msgid "Create a @file{~/.direnvrc} with a Bash code:"
  3594. msgstr ""
  3595. #. type: example
  3596. #: guix-git/doc/guix-cookbook.texi:2834
  3597. #, no-wrap
  3598. msgid ""
  3599. "# Thanks <https://github.com/direnv/direnv/issues/73#issuecomment-152284914>\n"
  3600. "export_function()\n"
  3601. "@{\n"
  3602. " local name=$1\n"
  3603. " local alias_dir=$PWD/.direnv/aliases\n"
  3604. " mkdir -p \"$alias_dir\"\n"
  3605. " PATH_add \"$alias_dir\"\n"
  3606. " local target=\"$alias_dir/$name\"\n"
  3607. " if declare -f \"$name\" >/dev/null; then\n"
  3608. " echo \"#!$SHELL\" > \"$target\"\n"
  3609. " declare -f \"$name\" >> \"$target\" 2>/dev/null\n"
  3610. " # Notice that we add shell variables to the function trigger.\n"
  3611. " echo \"$name \\$*\" >> \"$target\"\n"
  3612. " chmod +x \"$target\"\n"
  3613. " fi\n"
  3614. "@}\n"
  3615. "\n"
  3616. msgstr ""
  3617. #. type: example
  3618. #: guix-git/doc/guix-cookbook.texi:2839
  3619. #, no-wrap
  3620. msgid ""
  3621. "use_guix()\n"
  3622. "@{\n"
  3623. " # Set GitHub token.\n"
  3624. " export GUIX_GITHUB_TOKEN=\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n"
  3625. "\n"
  3626. msgstr ""
  3627. #. type: example
  3628. #: guix-git/doc/guix-cookbook.texi:2842
  3629. #, no-wrap
  3630. msgid ""
  3631. " # Unset 'GUIX_PACKAGE_PATH'.\n"
  3632. " export GUIX_PACKAGE_PATH=\"\"\n"
  3633. "\n"
  3634. msgstr ""
  3635. #. type: example
  3636. #: guix-git/doc/guix-cookbook.texi:2851
  3637. #, no-wrap
  3638. msgid ""
  3639. " # Recreate a garbage collector root.\n"
  3640. " gcroots=\"$HOME/.config/guix/gcroots\"\n"
  3641. " mkdir -p \"$gcroots\"\n"
  3642. " gcroot=\"$gcroots/guix\"\n"
  3643. " if [ -L \"$gcroot\" ]\n"
  3644. " then\n"
  3645. " rm -v \"$gcroot\"\n"
  3646. " fi\n"
  3647. "\n"
  3648. msgstr ""
  3649. #. type: example
  3650. #: guix-git/doc/guix-cookbook.texi:2866
  3651. #, no-wrap
  3652. msgid ""
  3653. " # Miscellaneous packages.\n"
  3654. " PACKAGES_MAINTENANCE=(\n"
  3655. " direnv\n"
  3656. " git\n"
  3657. " git:send-email\n"
  3658. " git-cal\n"
  3659. " gnupg\n"
  3660. " guile-colorized\n"
  3661. " guile-readline\n"
  3662. " less\n"
  3663. " ncurses\n"
  3664. " openssh\n"
  3665. " xdot\n"
  3666. " )\n"
  3667. "\n"
  3668. msgstr ""
  3669. #. type: example
  3670. #: guix-git/doc/guix-cookbook.texi:2869
  3671. #, no-wrap
  3672. msgid ""
  3673. " # Environment packages.\n"
  3674. " PACKAGES=(help2man guile-sqlite3 guile-gcrypt)\n"
  3675. "\n"
  3676. msgstr ""
  3677. #. type: example
  3678. #: guix-git/doc/guix-cookbook.texi:2872
  3679. #, no-wrap
  3680. msgid ""
  3681. " # Thanks <https://lists.gnu.org/archive/html/guix-devel/2016-09/msg00859.html>\n"
  3682. " eval \"$(guix environment --search-paths --root=\"$gcroot\" --pure guix --ad-hoc $@{PACKAGES[@@]@} $@{PACKAGES_MAINTENANCE[@@]@} \"$@@\")\"\n"
  3683. "\n"
  3684. msgstr ""
  3685. #. type: example
  3686. #: guix-git/doc/guix-cookbook.texi:2879
  3687. #, no-wrap
  3688. msgid ""
  3689. " # Predefine configure flags.\n"
  3690. " configure()\n"
  3691. " @{\n"
  3692. " ./configure --localstatedir=/var --prefix=\n"
  3693. " @}\n"
  3694. " export_function configure\n"
  3695. "\n"
  3696. msgstr ""
  3697. #. type: example
  3698. #: guix-git/doc/guix-cookbook.texi:2890
  3699. #, no-wrap
  3700. msgid ""
  3701. " # Run make and optionally build something.\n"
  3702. " build()\n"
  3703. " @{\n"
  3704. " make -j 2\n"
  3705. " if [ $# -gt 0 ]\n"
  3706. " then\n"
  3707. " ./pre-inst-env guix build \"$@@\"\n"
  3708. " fi\n"
  3709. " @}\n"
  3710. " export_function build\n"
  3711. "\n"
  3712. msgstr ""
  3713. #. type: example
  3714. #: guix-git/doc/guix-cookbook.texi:2897
  3715. #, no-wrap
  3716. msgid ""
  3717. " # Predefine push Git command.\n"
  3718. " push()\n"
  3719. " @{\n"
  3720. " git push --set-upstream origin\n"
  3721. " @}\n"
  3722. " export_function push\n"
  3723. "\n"
  3724. msgstr ""
  3725. #. type: example
  3726. #: guix-git/doc/guix-cookbook.texi:2900
  3727. #, no-wrap
  3728. msgid ""
  3729. " clear # Clean up the screen.\n"
  3730. " git-cal --author='Your Name' # Show contributions calendar.\n"
  3731. "\n"
  3732. msgstr ""
  3733. #. type: example
  3734. #: guix-git/doc/guix-cookbook.texi:2908
  3735. #, no-wrap
  3736. msgid ""
  3737. " # Show commands help.\n"
  3738. " echo \"\n"
  3739. "build build a package or just a project if no argument provided\n"
  3740. "configure run ./configure with predefined parameters\n"
  3741. "push push to upstream Git repository\n"
  3742. "\"\n"
  3743. "@}\n"
  3744. msgstr ""
  3745. #. type: Plain text
  3746. #: guix-git/doc/guix-cookbook.texi:2912
  3747. msgid "Every project containing @file{.envrc} with a string @code{use guix} will have predefined environment variables and procedures."
  3748. msgstr ""
  3749. #. type: Plain text
  3750. #: guix-git/doc/guix-cookbook.texi:2914
  3751. msgid "Run @command{direnv allow} to setup the environment for the first time."
  3752. msgstr ""
  3753. #. type: Plain text
  3754. #: guix-git/doc/guix-cookbook.texi:2926
  3755. msgid "Guix is based on the @uref{https://nixos.org/nix/, Nix package manager}, which was designed and implemented by Eelco Dolstra, with contributions from other people (see the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package management, and promoted unprecedented features, such as transactional package upgrades and rollbacks, per-user profiles, and referentially transparent build processes. Without this work, Guix would not exist."
  3756. msgstr ""
  3757. #. type: Plain text
  3758. #: guix-git/doc/guix-cookbook.texi:2929
  3759. msgid "The Nix-based software distributions, Nixpkgs and NixOS, have also been an inspiration for Guix."
  3760. msgstr ""
  3761. #. type: Plain text
  3762. #: guix-git/doc/guix-cookbook.texi:2935
  3763. msgid "GNU@tie{}Guix itself is a collective work with contributions from a number of people. See the @file{AUTHORS} file in Guix for more information on these fine people. The @file{THANKS} file lists people who have helped by reporting bugs, taking care of the infrastructure, providing artwork and themes, making suggestions, and more---thank you!"
  3764. msgstr ""
  3765. #. type: Plain text
  3766. #: guix-git/doc/guix-cookbook.texi:2938
  3767. msgid "This document includes adapted sections from articles that have previously been published on the Guix blog at @uref{https://guix.gnu.org/blog}."
  3768. msgstr ""
  3769. #. type: cindex
  3770. #: guix-git/doc/guix-cookbook.texi:2943
  3771. #, no-wrap
  3772. msgid "license, GNU Free Documentation License"
  3773. msgstr ""
  3774. #. type: include
  3775. #: guix-git/doc/guix-cookbook.texi:2944
  3776. #, no-wrap
  3777. msgid "fdl-1.3.texi"
  3778. msgstr ""