@fraczak/k 7.0.1 → 7.1.0

package/backend-api.mjs

@@ -27,3 +27,21 @@ export {
   isIdentityIntrinsic,
   unsupportedIntrinsic
 } from "./intrinsics.mjs";
+export { buildAccessTable, AccessTable } from "./access-table.mjs";
+export {
+  PKIR_FORMAT,
+  PKIR_VERSION,
+  compileRelationToPKIR,
+  executePKIR,
+  specializePKIR,
+  valueToKVal,
+  kvalToValue,
+  lowerPKIRToKVM
+} from "./pkir.mjs";
+export {
+  compileWasmArtifactFromPKIR
+} from "./backends/wasm/src/wasm.mjs";
+export {
+  compileLLVMArtifactFromPKIR
+} from "./backends/llvm/src/llvm.mjs";
+

package/backends/llvm/README.md

@@ -46,34 +46,33 @@ status in `k_result`. These operations can compose through KIR `comp`.
 ```sh
 k-llvm-build [options] [source-snippet | input-file [output-exe]]
 k-llvm-compile [options] [source-snippet | input-file [output.ll]]
-k-llvm-jit [options] object.ko
-k-llvm-run [options] object.ko [input.kv]
+k-llvm [options] ( source-snippet | input-file ) [ input-wire-file ]
 ```
 
 Options:
 
 - `-o, --output path`: specify output file path explicitly.
 - `--lib file`: load one `.klib` or `.k` dependency before compiling.
-- `--export spec`: export a library alias into source scope (`name` or `libname:localname`). May be repeated.
-- `--input-pattern json-or-file`: for `k-llvm-run`, KIR property-list input pattern.
-- `--retype rel`: for `k-llvm-run`, relation to specialize (defaults to object main).
-- `--expect value-or-file`: for `k-llvm-run`, compare the output value against expected value text.
-- `-h`, `--help`: show usage.
-
-The compile commands follow the unified k CLI input convention: pass inline
-source, an existing `.k` source file, or a `.ko`/`.klib` object. Reads UTF-8
-source from stdin when input is omitted. Output paths can be specified as a
-positional argument or explicitly with `-o, --output`.
-Without `--expect`, `k-llvm-run` prints the result value as compact JSON.
+- `--export spec`: export a library alias into scope. Repeatable.
+- `--pkir`: lower via Polymorphic K IR (PKIR).
+- `--retype rel`: relation to specialize (defaults to object main).
+- `--opt flag`: Clang optimization flag (-O0, -O1, -O2, -O3).
+- `-h, --help`: show usage.
+
+The compile commands follow the unified k CLI input convention: pass
+inline source, an existing `.k` source file, or a `.ko`/`.klib` object.
+Reads UTF-8 source from stdin when input is omitted. Output paths can be
+specified as a positional argument or explicitly with `-o, --output`.
 `k-llvm-build` emits a native executable that reads and writes the binary
-k pattern+value envelope used by `codecs/k-parse.mjs` and `codecs/k-print.mjs`.
-The executable checks the stdin envelope pattern against the compiled input
-pattern and encodes stdout with the compiled output pattern.
-`k-llvm-jit` reads the stdin binary envelope first, specializes the object with
-that input pattern, caches the native executable, and writes the compiled
-output envelope to stdout.
-The native envelope codec supports the k Unicode string encoding used for
-labels and tags.
+k pattern+value envelope used by `codecs/k-parse.mjs` and
+`codecs/k-print.mjs`. The executable checks the stdin envelope pattern
+against the compiled input pattern and encodes stdout with the compiled
+output pattern.
+`k-llvm` reads the binary wire envelope, specializes the relation to
+that input pattern, caches the compiled native executable, and writes
+the compiled output envelope to stdout.
+The native envelope codec supports the k Unicode string encoding used
+for labels and tags.
 
 ## Tests
 

package/backends/llvm/bin/k-llvm-build.mjs

@@ -9,35 +9,61 @@ import {
 } from "../src/cli.mjs";
 import {
   compileKVMToExecutable,
-  compileObjectToExecutable
+  compileObjectToExecutable,
+  compilePKIRToExecutable
 } from "../src/executable.mjs";
 
-function usage(stream = console.error) {
+function helpText() {
   const prog = argv[1] || "k-llvm-build.mjs";
-  stream(`Usage: node ${prog} [options] [source-snippet | input-file [output-exe]]`);
-  stream("Compile k source, .ko, .klib, or .kvm input into a native executable.");
-  stream("");
-  stream("Arguments:");
-  stream("  source-snippet  Inline k source, in the same style as k.mjs.");
-  stream("  input-file      Source .k, .ko, .klib, or .kvm file. Reads UTF-8 source from stdin when omitted.");
-  stream("  output-exe      Output executable path.");
-  stream("");
-  stream("The executable reads a binary k pattern+value envelope from stdin and");
-  stream("writes a binary k pattern+value envelope to stdout.");
-  stream("The stdin envelope pattern must match the compiled input pattern;");
-  stream("stdout is encoded with the compiled output pattern.");
-  stream("");
-  stream("Options:");
-  stream("  -o, --output path        Specify output file path explicitly.");
-  stream("  --input-pattern pattern  Input pattern JSON or file path for specialization.");
-  stream("  --lib file               Load one .klib dependency before compiling.");
-  stream("  --export spec            Export a library alias into source scope. May be repeated.");
-  stream("                           spec is 'name' or 'libname:localname'.");
-  stream("  -h, --help               Show this help.");
+  return [
+    "Compile k source, .ko, .klib, .kvm, or .pkir into a native",
+    "standalone executable.",
+    "",
+    `Usage: ${prog} [options]`,
+    "       [source-snippet | input-file [output-exe]]",
+    "",
+    "Arguments:",
+    "  source-snippet   Inline k source snippet (in the style of k.mjs).",
+    "  input-file       Source .k, .ko, .klib, .kvm, or .pkir file.",
+    "                   Reads UTF-8 source from stdin when omitted.",
+    "  output-exe       Output executable path.",
+    "",
+    "The executable reads a binary k pattern+value envelope from stdin",
+    "and writes a binary k pattern+value envelope to stdout.",
+    "The stdin envelope pattern must match the compiled input pattern;",
+    "stdout is encoded with the compiled output pattern.",
+    "",
+    "Options:",
+    "  -o, --output path        Specify output file path explicitly.",
+    "  --pkir                   Lower via Polymorphic K IR (PKIR).",
+    "  --input-pattern pattern  Input pattern JSON or file for spec.",
+    "  --retype rel             Relation to specialize (default: main).",
+    "  --lib file               Load .klib or .k library before build.",
+    "  --export spec     Export library alias into scope. Repeatable.",
+    "                    spec is 'name' or 'libname:localname'.",
+    "  --opt flag               Clang optimization flag (default: -O3).",
+    "  -h, --help               Show this help.",
+    "",
+    "Environment Variables:",
+    "  CLANG, CC            Path to Clang compiler (default: clang).",
+    "  K_LLVM_CLANG_OPT     Clang optimization flag (default: -O3).",
+    "  K_LLVM_RUNTIME_MODE  Runtime mode: fast, compact (default: fast).",
+    "",
+    "Examples:",
+    `  ${prog} 'x = |x; x x' -o program.exe`,
+    `  ${prog} program.k program.exe`,
+    `  ${prog} --lib Examples/poly.k --export concat 's' -o s.exe`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 function readMaybeFile(textOrPath) {
-  return fs.existsSync(textOrPath) ? fs.readFileSync(textOrPath, "utf8") : textOrPath;
+  return fs.existsSync(textOrPath)
+    ? fs.readFileSync(textOrPath, "utf8")
+    : textOrPath;
 }
 
 function readPattern(inputPattern) {
@@ -54,17 +80,38 @@ try {
 
   let explicitOutput = null;
   let rawInputPattern = null;
+  let relation = null;
+  let clangOpt = process.env.K_LLVM_CLANG_OPT || "-O3";
+  let runtimeMode = process.env.K_LLVM_RUNTIME_MODE || "fast";
   const remainingArgs = [];
   while (args.length > 0) {
     const arg = args[0];
     if (arg === "-o" || arg === "--output") {
       args.shift();
       explicitOutput = args.shift();
-      if (!explicitOutput) throw new Error("-o/--output requires a file argument");
+      if (!explicitOutput) {
+        throw new Error("-o/--output requires a file argument");
+      }
     } else if (arg === "--input-pattern") {
       args.shift();
       rawInputPattern = args.shift();
-      if (!rawInputPattern) throw new Error("--input-pattern requires a JSON or file argument");
+      if (!rawInputPattern) {
+        throw new Error(
+          "--input-pattern requires a JSON or file argument"
+        );
+      }
+    } else if (arg === "--retype") {
+      args.shift();
+      relation = args.shift();
+      if (!relation) {
+        throw new Error("--retype requires a relation name");
+      }
+    } else if (arg === "--opt") {
+      args.shift();
+      clangOpt = args.shift();
+      if (!clangOpt) {
+        throw new Error("--opt requires a flag (e.g. -O3)");
+      }
     } else {
       remainingArgs.push(args.shift());
     }
@@ -72,17 +119,38 @@ try {
 
   const inputPattern = readPattern(rawInputPattern);
 
-  const { libraries, exportSpecs } = parseCompileOptions(remainingArgs);
-  const input = resolveProgramInput(remainingArgs, { allowStdinSource: true });
+  const { libraries, exportSpecs, usePKIR } =
+    parseCompileOptions(remainingArgs);
+  const input = resolveProgramInput(remainingArgs, {
+    allowStdinSource: true
+  });
   const positionalOutput = remainingArgs.shift();
   if (remainingArgs.length > 0) throw new Error("Too many arguments");
 
   const outputPath = explicitOutput || positionalOutput || null;
-  if (outputPath == null) throw new Error("Output executable path is required (pass output-exe or -o/--output)");
+  if (outputPath == null) {
+    throw new Error(
+      "Output executable path required (pass output-exe or -o/--output)"
+    );
+  }
 
-  if (input.kind === "kvm") {
+  if (input.kind === "pkir") {
+    const pkir = JSON.parse(fs.readFileSync(input.path, "utf8"));
+    compilePKIRToExecutable(pkir, outputPath, {
+      entry: relation,
+      inputPattern,
+      clangOpt,
+      runtimeMode
+    });
+  } else if (input.kind === "kvm") {
     const kvm = JSON.parse(fs.readFileSync(input.path, "utf8"));
-    compileKVMToExecutable(kvm, outputPath, { inputPattern });
+    compileKVMToExecutable(kvm, outputPath, {
+      entry: relation,
+      inputPattern,
+      clangOpt,
+      runtimeMode,
+      usePKIR
+    });
   } else {
     const object = await compileProgramInputToObject(input, {
       libraries,
@@ -90,10 +158,15 @@ try {
       stdin
     });
 
-    compileObjectToExecutable(object, outputPath, { inputPattern });
+    compileObjectToExecutable(object, outputPath, {
+      relation: relation || object.main,
+      inputPattern,
+      clangOpt,
+      runtimeMode,
+      usePKIR
+    });
   }
 } catch (error) {
   console.error(error.stack || error.message || String(error));
-  usage();
   exit(1);
 }

package/backends/llvm/bin/k-llvm-compile.mjs

@@ -9,26 +9,44 @@ import {
 } from "../src/cli.mjs";
 import {
   compileObjectToLLVM,
-  compileLLVMArtifactFromKVM
+  compileLLVMArtifactFromKVM,
+  compileLLVMArtifactFromPKIR
 } from "../src/llvm.mjs";
 import { inputPatternForObjectRelation } from "../src/executable.mjs";
 
-function usage(stream = console.error) {
+function helpText() {
   const prog = argv[1] || "k-llvm-compile.mjs";
-  stream(`Usage: node ${prog} [options] [source-snippet | input-file [output.ll]]`);
-  stream("Compile a k .ko/.klib object, source, or .kvm input into prototype LLVM IR.");
-  stream("");
-  stream("Arguments:");
-  stream("  source-snippet  Inline k source, in the same style as k.mjs.");
-  stream("  input-file      Source .k, .ko, .klib, or .kvm file. Reads UTF-8 source from stdin when omitted.");
-  stream("  output.ll       Output LLVM IR path. Writes to stdout when omitted.");
-  stream("");
-  stream("Options:");
-  stream("  -o, --output path  Specify output file path explicitly.");
-  stream("  --lib file         Load one .klib dependency before compiling.");
-  stream("  --export spec      Export a library alias into source scope. May be repeated.");
-  stream("                     spec is 'name' or 'libname:localname'.");
-  stream("  -h, --help         Show this help.");
+  return [
+    "Compile a k .ko/.klib object, source, .kvm, or .pkir into LLVM IR.",
+    "",
+    `Usage: ${prog} [options]`,
+    "       [source-snippet | input-file [output.ll]]",
+    "",
+    "Arguments:",
+    "  source-snippet   Inline k source snippet (in the style of k.mjs).",
+    "  input-file       Source .k, .ko, .klib, .kvm, or .pkir file.",
+    "                   Reads UTF-8 source from stdin when omitted.",
+    "  output.ll        Output LLVM IR path (default: stdout).",
+    "",
+    "Options:",
+    "  -o, --output path  Specify output file path explicitly.",
+    "  --pkir             Lower via Polymorphic K IR (PKIR).",
+    "  --retype rel       Relation to compile (default: object main).",
+    "  --lib file         Load one .klib or .k library before compiling.",
+    "  --export spec      Export library alias into scope. Repeatable.",
+    "                     spec is 'name' or 'libname:localname'.",
+    "  -h, --help         Show this help.",
+    "",
+    "Examples:",
+    `  ${prog} 'x = |x; x x' program.ll`,
+    `  ${prog} program.k -o program.ll`,
+    `  ${prog} --pkir program.k -o program.ll`,
+    `  ${prog} --lib core.klib --export add program.k program.ll`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 try {
@@ -39,29 +57,49 @@ try {
   }
 
   let explicitOutput = null;
+  let relation = null;
   const remainingArgs = [];
   while (args.length > 0) {
     const arg = args[0];
     if (arg === "-o" || arg === "--output") {
       args.shift();
       explicitOutput = args.shift();
-      if (!explicitOutput) throw new Error("-o/--output requires a file argument");
+      if (!explicitOutput) {
+        throw new Error("-o/--output requires a file argument");
+      }
+    } else if (arg === "--retype") {
+      args.shift();
+      relation = args.shift();
+      if (!relation) {
+        throw new Error("--retype requires a relation name");
+      }
     } else {
       remainingArgs.push(args.shift());
     }
   }
 
-  const { libraries, exportSpecs } = parseCompileOptions(remainingArgs);
-  const input = resolveProgramInput(remainingArgs, { allowStdinSource: true });
+  const { libraries, exportSpecs, usePKIR } =
+    parseCompileOptions(remainingArgs);
+  const input = resolveProgramInput(remainingArgs, {
+    allowStdinSource: true
+  });
   const positionalOutput = remainingArgs.shift();
   if (remainingArgs.length > 0) throw new Error("Too many arguments");
 
   const outputPath = explicitOutput || positionalOutput || null;
 
   let llvm;
-  if (input.kind === "kvm") {
+  if (input.kind === "pkir") {
+    const pkir = JSON.parse(fs.readFileSync(input.path, "utf8"));
+    const entry = relation || pkir.entry || pkir.name || "__main__";
+    llvm = compileLLVMArtifactFromPKIR(pkir, {
+      relation: entry,
+      inputPattern: pkir.inputPattern,
+      outputPattern: pkir.outputPattern
+    });
+  } else if (input.kind === "kvm") {
     const kvm = JSON.parse(fs.readFileSync(input.path, "utf8"));
-    const entry = kvm.entry || kvm.relation || "__main__";
+    const entry = relation || kvm.entry || kvm.relation || "__main__";
     const mainFunc = kvm.functions?.[entry];
     const artifact = compileLLVMArtifactFromKVM(kvm, {
       relation: entry,
@@ -76,9 +114,11 @@ try {
       stdin
     });
 
+    const targetRel = relation || object.main;
     const res = compileObjectToLLVM(object, {
-      relation: object.main,
-      inputPattern: inputPatternForObjectRelation(object, object.main)
+      relation: targetRel,
+      inputPattern: inputPatternForObjectRelation(object, targetRel),
+      usePKIR
     });
     llvm = res.llvm;
   }
@@ -90,6 +130,5 @@ try {
   }
 } catch (error) {
   console.error(error.stack || error.message || String(error));
-  usage();
   exit(1);
 }