summaryrefslogtreecommitdiff
path: root/src/cli
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:32:21 -0300
committerGabriel Schneider <[email protected]>2026-11-10 12:08:27 -0300
commitb426a8a99bcad81ecbb41d1f2a2e83738c29d8e1 (patch)
tree06e303f1f33ce53cfc2d8a2043e24f032877f9ad /src/cli
parent7f363779cb99b0820cce69c433bcfab87bb3d709 (diff)
downloadcomputeranim-b426a8a99bcad81ecbb41d1f2a2e83738c29d8e1.tar.gz
computeranim-b426a8a99bcad81ecbb41d1f2a2e83738c29d8e1.zip
llvm: a pass that instruments for animation, its runtime, ztrace cc
llvm/pass.cpp is an LLVM pass plugin: lines, stores, loads, calls and variables, each call into the runtime carrying names and type descriptions, selected by globs (-ztrace-only, -ztrace-mem), before the optimizer by default. src/instr/rt.zig is the runtime (libztrace-rt.a), which also answers clang's own coverage and -finstrument-functions hooks; src/instr/types.zig the grammar of the type descriptions and its parser. ztrace cc adds all of it to a compiler command. test-llvm compiles fib, two sorts, a linked list and a BFS through ztrace cc and asserts on their recordings; bench-llvm measures what each selection costs. Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'src/cli')
-rw-r--r--src/cli/cc.zig116
-rw-r--r--src/cli/main.zig2
2 files changed, 118 insertions, 0 deletions
diff --git a/src/cli/cc.zig b/src/cli/cc.zig
new file mode 100644
index 0000000..1d08b51
--- /dev/null
+++ b/src/cli/cc.zig
@@ -0,0 +1,116 @@
+//! ztrace cc: a compiler command with the instrumentation added, so a
+//! program compiled from source records itself under `ztrace run`.
+const std = @import("std");
+const util = @import("util.zig");
+const fail = util.fail;
+
+pub const usage =
+ \\usage: ztrace cc [--instr LIST] [--only GLOBS] [--mem GLOBS] [--late] [--plugin SO] [--rt A] -- CLANG ARGS
+ \\
+ \\Runs CLANG (clang, clang++) with ARGS and -g, the pass plugin and its
+ \\options, and when the command links, the runtime:
+ \\
+ \\ ztrace cc -- clang sort.c -o sort && ztrace run -- ./sort
+ \\
+ \\ --instr LIST comma separated, default lines,calls,vars,stores
+ \\ lines `line` at each source line reached
+ \\ stores `mem_write`, with the bytes, after each store to a
+ \\ variable or through a pointer; a memset or
+ \\ memcpy is one, of its first 64 KiB at most
+ \\ loads `mem_read` after each load
+ \\ calls `call` at function entry, `ret` with the value at exit
+ \\ vars `variable` for each named local and global:
+ \\ address, size, name, type description
+ \\ from stock clang, no plugin and no names:
+ \\ edges `edge` (-fsanitize-coverage=trace-pc-guard)
+ \\ cmps `cmp`, and `edge`: clang compares only along with edges
+ \\ (-fsanitize-coverage=trace-pc-guard,trace-cmp)
+ \\ cyg `call`, `ret` (-finstrument-functions)
+ \\ --only GLOBS comma separated; the plugin instruments only the functions
+ \\ and globals whose name, source path or source file name
+ \\ matches one: 'sort*,*/vdbe.c'
+ \\ --mem GLOBS of those, the functions whose stores and loads are recorded
+ \\ (default: all of them). Stores are most of a recording:
+ \\ in a large program, name where memory matters.
+ \\ --late instrument after optimization: the stores and lines of the
+ \\ code that runs, not of the source
+ \\ --plugin SO the pass (default: ../lib/ztrace-pass.so from this program)
+ \\ --rt A the runtime (default: ../lib/libztrace-rt.a)
+ \\
+;
+
+pub fn run(init: std.process.Init, args: []const [:0]const u8) !void {
+ const arena = init.arena.allocator();
+ var instr: []const u8 = "lines,calls,vars,stores";
+ var only: ?[]const u8 = null;
+ var mem: ?[]const u8 = null;
+ var late = false;
+ var plugin: ?[]const u8 = null;
+ var rt: ?[]const u8 = null;
+ var i: usize = 0;
+ while (i < args.len) : (i += 1) {
+ const arg = args[i];
+ if (std.mem.eql(u8, arg, "--")) {
+ i += 1;
+ break;
+ } else if (std.mem.eql(u8, arg, "--late")) {
+ late = true;
+ } else if (i + 1 < args.len and std.mem.eql(u8, arg, "--instr")) {
+ i += 1;
+ instr = args[i];
+ } else if (i + 1 < args.len and std.mem.eql(u8, arg, "--only")) {
+ i += 1;
+ only = args[i];
+ } else if (i + 1 < args.len and std.mem.eql(u8, arg, "--mem")) {
+ i += 1;
+ mem = args[i];
+ } else if (i + 1 < args.len and std.mem.eql(u8, arg, "--plugin")) {
+ i += 1;
+ plugin = args[i];
+ } else if (i + 1 < args.len and std.mem.eql(u8, arg, "--rt")) {
+ i += 1;
+ rt = args[i];
+ } else fail(usage, .{});
+ }
+ if (i >= args.len) fail(usage, .{});
+ const lib = try std.fs.path.join(arena, &.{ try std.process.executableDirPathAlloc(init.io, arena), "..", "lib" });
+
+ var argv: std.ArrayList([]const u8) = .empty;
+ for (args[i..]) |arg| try argv.append(arena, arg);
+ // What a command that only links does not use is no warning.
+ try argv.appendSlice(arena, &.{ "--start-no-unused-arguments", "-g" });
+ // The plugin's own words, which it checks; the rest are clang's flags.
+ var pass: std.ArrayList(u8) = .empty;
+ var words = std.mem.tokenizeScalar(u8, instr, ',');
+ while (words.next()) |word| {
+ if (std.mem.eql(u8, word, "edges")) {
+ try argv.append(arena, "-fsanitize-coverage=trace-pc-guard");
+ } else if (std.mem.eql(u8, word, "cmps")) {
+ try argv.append(arena, "-fsanitize-coverage=trace-pc-guard,trace-cmp");
+ } else if (std.mem.eql(u8, word, "cyg")) {
+ try argv.append(arena, "-finstrument-functions");
+ } else try pass.print(arena, "{s}{s}", .{ if (pass.items.len > 0) "," else "", word });
+ }
+ if (pass.items.len > 0) {
+ const so = plugin orelse try std.fs.path.join(arena, &.{ lib, "ztrace-pass.so" });
+ // -load as well: the plugin's options must exist when -mllvm is read,
+ // which is before -fpass-plugin loads it.
+ try argv.appendSlice(arena, &.{ try std.fmt.allocPrint(arena, "-fpass-plugin={s}", .{so}), "-Xclang", "-load", "-Xclang", so });
+ try argv.appendSlice(arena, &.{ "-mllvm", try std.fmt.allocPrint(arena, "-ztrace-instr={s}", .{pass.items}) });
+ if (only) |globs| try argv.appendSlice(arena, &.{ "-mllvm", try std.fmt.allocPrint(arena, "-ztrace-only={s}", .{globs}) });
+ if (mem) |globs| try argv.appendSlice(arena, &.{ "-mllvm", try std.fmt.allocPrint(arena, "-ztrace-mem={s}", .{globs}) });
+ if (late) try argv.appendSlice(arena, &.{ "-mllvm", "-ztrace-late" });
+ }
+ try argv.append(arena, "--end-no-unused-arguments");
+ // The command links unless it says where to stop. The whole archive: with
+ // -fsanitize-coverage clang links weak callbacks of its own first, and
+ // only a runtime already in the link replaces them. -x none: after an
+ // -x c the archive would be read as source.
+ const links = for (args[i..]) |arg| {
+ if (std.mem.eql(u8, arg, "-c") or std.mem.eql(u8, arg, "-S") or std.mem.eql(u8, arg, "-E") or std.mem.eql(u8, arg, "-fsyntax-only")) break false;
+ } else true;
+ if (links) try argv.appendSlice(arena, &.{ "-x", "none", "-Wl,--whole-archive", rt orelse try std.fs.path.join(arena, &.{ lib, "libztrace-rt.a" }), "-Wl,--no-whole-archive" });
+
+ const err = std.process.replace(init.io, .{ .argv = argv.items });
+ fail("{s}: {t}\n", .{ argv.items[0], err });
+}
diff --git a/src/cli/main.zig b/src/cli/main.zig
index 72b894a..1ac019f 100644
--- a/src/cli/main.zig
+++ b/src/cli/main.zig
@@ -9,6 +9,7 @@ const commands = .{
.run = @import("run.zig"),
.dump = @import("dump.zig"),
.show = @import("show.zig"),
+ .cc = @import("cc.zig"),
};
const usage =
@@ -19,6 +20,7 @@ const usage =
\\ run record a program that carries a ring producer (agent, instrumentation)
\\ dump print a recording's events
\\ show print a recording's summary, or the program's state at a moment
+ \\ cc compile a program with instrumentation that records it
\\
\\`ztrace COMMAND --help` for each.
\\