[{"data":1,"prerenderedAt":714},["ShallowReactive",2],{"doc:\u002Fguides\u002Fmigration":3,"nav:guides":669},{"doc":4,"source":668},{"id":5,"title":6,"body":7,"description":660,"extension":661,"meta":662,"navigation":663,"path":664,"seo":665,"stem":666,"__hash__":667},"guides\u002Fguides\u002Fmigration.md","Migrating from pkl-zig",{"type":8,"value":9,"toc":652},"minimark",[10,14,30,35,99,204,208,223,365,386,393,397,525,539,543,577,581,616,620,648],[11,12,6],"h1",{"id":13},"migrating-from-pkl-zig",[15,16,17,24,25,29],"p",{},[18,19,23],"a",{"href":20,"rel":21},"https:\u002F\u002Fgithub.com\u002Fburakssen\u002Fpkl-zig",[22],"nofollow","pkl-zig"," and zig-pkl both talk to ",[26,27,28],"code",{},"pkl server",", so the concepts carry over. The names and ownership rules differ. This page maps the API documented in pkl-zig's README to zig-pkl.",[31,32,34],"h2",{"id":33},"toolchain-and-package","Toolchain and package",[36,37,38,52],"table",{},[39,40,41],"thead",{},[42,43,44,47,49],"tr",{},[45,46],"th",{},[45,48,23],{},[45,50,51],{},"zig-pkl",[53,54,55,67,78],"tbody",{},[42,56,57,61,64],{},[58,59,60],"td",{},"Zig",[58,62,63],{},"0.16.0",[58,65,66],{},"0.17.0",[42,68,69,72,75],{},[58,70,71],{},"Pkl",[58,73,74],{},"0.32.1",[58,76,77],{},"0.25.3 and newer; 0.32.2 for code generation",[42,79,80,83,92],{},[58,81,82],{},"Dependency",[58,84,85,88,89],{},[26,86,87],{},"pkl_zig",", module ",[26,90,91],{},"pkl",[58,93,94,88,97],{},[26,95,96],{},"zig_pkl",[26,98,96],{},[100,101,106],"pre",{"className":102,"code":103,"language":104,"meta":105,"style":105},"language-zig shiki shiki-themes github-light github-dark","const zig_pkl = b.dependency(\"zig_pkl\", .{ .target = target, .optimize = optimize });\nexe.root_module.addImport(\"zig_pkl\", zig_pkl.module(\"zig_pkl\"));\n","zig","",[26,107,108,167],{"__ignoreMap":105},[109,110,113,117,121,124,127,131,135,138,142,145,148,150,153,156,159,161,164],"span",{"class":111,"line":112},"line",1,[109,114,116],{"class":115},"szBVR","const",[109,118,120],{"class":119},"s4XuR"," zig_pkl",[109,122,123],{"class":115}," =",[109,125,126],{"class":119}," b",[109,128,130],{"class":129},"sVt8B",".",[109,132,134],{"class":133},"sScJk","dependency",[109,136,137],{"class":129},"(",[109,139,141],{"class":140},"sZZnC","\"zig_pkl\"",[109,143,144],{"class":129},", .{ .",[109,146,147],{"class":119},"target",[109,149,123],{"class":115},[109,151,152],{"class":119}," target",[109,154,155],{"class":129},", .",[109,157,158],{"class":119},"optimize",[109,160,123],{"class":115},[109,162,163],{"class":119}," optimize",[109,165,166],{"class":129}," });\n",[109,168,170,173,175,178,180,183,185,187,190,192,194,197,199,201],{"class":111,"line":169},2,[109,171,172],{"class":119},"exe",[109,174,130],{"class":129},[109,176,177],{"class":119},"root_module",[109,179,130],{"class":129},[109,181,182],{"class":133},"addImport",[109,184,137],{"class":129},[109,186,141],{"class":140},[109,188,189],{"class":129},", ",[109,191,96],{"class":119},[109,193,130],{"class":129},[109,195,196],{"class":133},"module",[109,198,137],{"class":129},[109,200,141],{"class":140},[109,202,203],{"class":129},"));\n",[31,205,207],{"id":206},"evaluators","Evaluators",[15,209,210,211,214,215,218,219,222],{},"pkl-zig's ",[26,212,213],{},"Evaluator.init"," starts a server per evaluator unless you use ",[26,216,217],{},"EvaluatorManager",". In zig-pkl every evaluator belongs to a ",[26,220,221],{},"Manager",", which owns the server:",[36,224,225,233],{},[39,226,227],{},[42,228,229,231],{},[45,230,23],{},[45,232,51],{},[53,234,235,251,269,286,299,319,341,353],{},[42,236,237,242],{},[58,238,239],{},[26,240,241],{},"pkl.Evaluator.init(io, gpa, .{ .pkl_argv = argv, ... })",[58,243,244,247,248],{},[26,245,246],{},"Manager.init(gpa, io, argv, log)",", then ",[26,249,250],{},"manager.createEvaluator(options, &rejected)",[42,252,253,262],{},[58,254,255,258,259],{},[26,256,257],{},"pkl.EvaluatorManager.init"," and ",[26,260,261],{},"manager.newEvaluator(options)",[58,263,264,258,267],{},[26,265,266],{},"Manager.init",[26,268,250],{},[42,270,271,277],{},[58,272,273,276],{},[26,274,275],{},"InitResult.failed"," with a diagnostic",[58,278,279,282,283],{},[26,280,281],{},"error.Rejected",", with the diagnostic in ",[26,284,285],{},"rejected",[42,287,288,293],{},[58,289,290],{},[26,291,292],{},"evaluator.deinit()",[58,294,295,298],{},[26,296,297],{},"evaluator.close()","; the manager frees it",[42,300,301,306],{},[58,302,303],{},[26,304,305],{},"Evaluator.initPreconfigured(io, gpa, environ_map)",[58,307,308,311,312,258,315,318],{},[26,309,310],{},"Options.preconfigured()","; set ",[26,313,314],{},"env",[26,316,317],{},"cache_dir"," yourself",[42,320,321,329],{},[58,322,323,258,326],{},[26,324,325],{},"EvaluatorOptionsBuilder",[26,327,328],{},"addModuleReader",[58,330,331,334,335,247,338],{},[26,332,333],{},"Builder.restricted(allocator)"," or ",[26,336,337],{},"Builder.preconfigured(allocator)",[26,339,340],{},"moduleReaders(&readers)",[42,342,343,348],{},[58,344,345],{},[26,346,347],{},"ModuleSource.fromText(text)",[58,349,350],{},[26,351,352],{},"Source.text(text)",[42,354,355,360],{},[58,356,357],{},[26,358,359],{},"ModuleSource.fromUri(uri)",[58,361,362],{},[26,363,364],{},"Source.uri(uri)",[15,366,210,367,370,371,374,375,377,378,381,382,130],{},[26,368,369],{},"initPreconfigured"," forwards the process environment and reads ",[26,372,373],{},"PKL_EXEC",". zig-pkl does neither on its own: pass the server command to ",[26,376,266],{},", and copy any environment variables a module needs into ",[26,379,380],{},"Options.env",". See ",[18,383,385],{"href":384},"security","Security",[15,387,388,389,130],{},"Calls on one pkl-zig evaluator are serialized. A zig-pkl evaluator accepts concurrent calls from any thread; see ",[18,390,392],{"href":391},"concurrency","Concurrency",[31,394,396],{"id":395},"loading-values","Loading values",[36,398,399,407],{},[39,400,401],{},[42,402,403,405],{},[45,404,23],{},[45,406,51],{},[53,408,409,421,433,445,457,469,481,493,505],{},[42,410,411,416],{},[58,412,413],{},[26,414,415],{},"evaluator.loadFromPath(T, path)",[58,417,418],{},[26,419,420],{},"evaluator.evaluateInto(T, allocator, .uri(try zig_pkl.uri.fromFile(allocator, io, path)), null, &failure)",[42,422,423,428],{},[58,424,425],{},[26,426,427],{},"evaluator.evaluateModule(T, source)",[58,429,430],{},[26,431,432],{},"evaluator.evaluateInto(T, allocator, source, null, &failure)",[42,434,435,440],{},[58,436,437],{},[26,438,439],{},"evaluator.evaluateExpression",[58,441,442],{},[26,443,444],{},"evaluator.evaluateInto(T, allocator, source, expression, &failure)",[42,446,447,452],{},[58,448,449],{},[26,450,451],{},"evaluator.evaluateOutputText(source)",[58,453,454],{},[26,455,456],{},"evaluator.evaluateSource(source, \"output.text\", &failure)",[42,458,459,464],{},[58,460,461],{},[26,462,463],{},"evaluator.evaluateOutputBytes(source)",[58,465,466],{},[26,467,468],{},"evaluator.evaluateSource(source, \"output.bytes\", &failure)",[42,470,471,476],{},[58,472,473],{},[26,474,475],{},"evaluator.evaluateOutputValue(T, source)",[58,477,478],{},[26,479,480],{},"evaluator.evaluateInto(T, allocator, source, \"output.value\", &failure)",[42,482,483,488],{},[58,484,485],{},[26,486,487],{},"evaluator.evaluateOutputFiles(source)",[58,489,490],{},[26,491,492],{},"evaluator.evaluateSource(source, \"output.files.toMap().mapValues((_, f) -> f.text)\", &failure)",[42,494,495,500],{},[58,496,497],{},[26,498,499],{},"pkl.deinit(T, allocator, &value)",[58,501,502],{},[26,503,504],{},"zig_pkl.convert.freeInto(T, allocator, value)",[42,506,507,512],{},[58,508,509],{},[26,510,511],{},"pkl.Value",[58,513,514,517,518,521,522],{},[26,515,516],{},"zig_pkl.Value"," inside a ",[26,519,520],{},"value.Tree","; free with ",[26,523,524],{},"tree.deinit()",[15,526,527,528,531,532,381,535,130],{},"Evaluation errors return ",[26,529,530],{},"error.EvaluationFailed"," with Pkl's message in ",[26,533,534],{},"failure",[18,536,538],{"href":537},"errors","Errors",[31,540,542],{"id":541},"readers-and-logging","Readers and logging",[15,544,545,546,549,550,553,554,258,556,558,559,563,564,567,568,572,573,130],{},"Both libraries take module and resource readers with a scheme, ",[26,547,548],{},"read",", and ",[26,551,552],{},"list",". In zig-pkl, ",[26,555,548],{},[26,557,552],{}," return memory allocated with the allocator they receive, and the manager frees it after replying. See ",[18,560,562],{"href":561},"readers","Readers",". Loggers are set per evaluator through ",[26,565,566],{},"Options.logger","; see ",[18,569,571],{"href":570},"logging","Logging",". zig-pkl adds a client for ",[18,574,576],{"href":575},"external-readers","external readers",[31,578,580],{"id":579},"code-generation","Code generation",[15,582,583,584,334,587,590,591,594,595,598,599,602,603,189,606,549,609,612,613,130],{},"pkl-zig generates with ",[26,585,586],{},"pkl run codegen\u002Fsrc\u002Fgen.pkl",[26,588,589],{},"pkl_zig.addCodegen"," in ",[26,592,593],{},"build.zig",". zig-pkl ships the ",[26,596,597],{},"zig-pkl-gen"," executable and its own ",[26,600,601],{},"@zig"," annotation package; generated modules have ",[26,604,605],{},"decode",[26,607,608],{},"deinit",[26,610,611],{},"load(allocator, evaluator, source, &failure)",". Heterogeneous unions and unions across packages become tagged unions instead of falling back to a dynamic value. See ",[18,614,580],{"href":615},"..\u002Fcodegen",[31,617,619],{"id":618},"low-level-protocol","Low-level protocol",[15,621,210,622,625,626,258,629,632,633,636,637,640,641,644,645,130],{},[26,623,624],{},"Transport"," corresponds to ",[26,627,628],{},"zig_pkl.Backend",[26,630,631],{},"zig_pkl.Subprocess",", with messages in ",[26,634,635],{},"zig_pkl.protocol"," and MessagePack in ",[26,638,639],{},"zig_pkl.msgpack",". ",[26,642,643],{},"Manager.initWithBackend"," runs the manager over any ",[26,646,647],{},"Backend",[649,650,651],"style",{},"html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .s4XuR, html code.shiki .s4XuR{--shiki-default:#E36209;--shiki-dark:#FFAB70}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":105,"searchDepth":169,"depth":169,"links":653},[654,655,656,657,658,659],{"id":33,"depth":169,"text":34},{"id":206,"depth":169,"text":207},{"id":395,"depth":169,"text":396},{"id":541,"depth":169,"text":542},{"id":579,"depth":169,"text":580},{"id":618,"depth":169,"text":619},"pkl-zig and zig-pkl both talk to pkl server, so the concepts carry over. The names and ownership rules differ. This page maps the API documented in pkl-zig's README to zig-pkl.","md",{},true,"\u002Fguides\u002Fmigration",{"title":6,"description":660},"guides\u002Fmigration","vAGS80tCb7kRuqqJp47vBe_NHG5C0HSs3QXU-YkbzJc","docs\u002Fguides\u002Fmigration.md",[670,674,677,680,684,688,692,695,696,700,704,708,711],{"title":671,"path":672,"stem":673},"Version compatibility","\u002Fguides\u002Fcompatibility","guides\u002Fcompatibility",{"title":392,"path":675,"stem":676},"\u002Fguides\u002Fconcurrency","guides\u002Fconcurrency",{"title":538,"path":678,"stem":679},"\u002Fguides\u002Ferrors","guides\u002Ferrors",{"title":681,"path":682,"stem":683},"Evaluation","\u002Fguides\u002Fevaluation","guides\u002Fevaluation",{"title":685,"path":686,"stem":687},"External readers","\u002Fguides\u002Fexternal-readers","guides\u002Fexternal-readers",{"title":689,"path":690,"stem":691},"Installation","\u002Fguides\u002Finstallation","guides\u002Finstallation",{"title":571,"path":693,"stem":694},"\u002Fguides\u002Flogging","guides\u002Flogging",{"title":6,"path":664,"stem":666},{"title":697,"path":698,"stem":699},"Ownership","\u002Fguides\u002Fownership","guides\u002Fownership",{"title":701,"path":702,"stem":703},"Projects","\u002Fguides\u002Fprojects","guides\u002Fprojects",{"title":705,"path":706,"stem":707},"Quick start","\u002Fguides\u002Fquickstart","guides\u002Fquickstart",{"title":562,"path":709,"stem":710},"\u002Fguides\u002Freaders","guides\u002Freaders",{"title":385,"path":712,"stem":713},"\u002Fguides\u002Fsecurity","guides\u002Fsecurity",1792908673088]