From 3093eb55ac4a7054f51f06ea2786b5f9c9ec73f6 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 11 Nov 2026 14:43:13 -0300 Subject: canim: a minimap in each pane; source wherever it can be had, libc's included From the user. Each pane with more than it shows carries a strip of its whole column at its right edge, the pane's window outlined and what happens off it marked there; the corner minimap is gone and the dive folds each column of the map into its pane's strip. The source panel follows the pc into any file the build has: glibc's own, from the distro's debuginfod by an optional step that caches them by build id (zig build sources; nothing else touches the network), and musl's, from Zig's lib directory. The syscalls scene shows open64.c on the way down, and a new scene follows the same call through a Zig-built musl. A graph's counts and inks are as of the moment shown. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa --- anim/tools/chart.py | 41 ++++++++----- anim/tools/sources.zig | 164 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 189 insertions(+), 16 deletions(-) create mode 100644 anim/tools/sources.zig (limited to 'anim/tools') diff --git a/anim/tools/chart.py b/anim/tools/chart.py index 7cc0925..290c59e 100644 --- a/anim/tools/chart.py +++ b/anim/tools/chart.py @@ -39,27 +39,36 @@ def split(drawing, view, source, disasm, slots, backtrace=0): out["backtrace"] = (976, right + ph(17) + 12 + ph(slots) + 12, 880, ph(backtrace)) return out -# The words that are not panels (motion.WORDS): the clock (its count, ranged right at 1648, -# changes in a frame by design), the caption (its 1400 from the margin), and the minimap at -# the caption band's right end, secondary action. The caption's box starts under the clock's count -# and the run's step counter (912 to 934). -words = {"clock": (0, 888, 1656, 46), "caption": (0, 940, 1464, 140), "minimap": (1664, 912, 192, 108)} +# The words that are not panels (motion.WORDS): the clock (its count, ranged right at 1856, +# changes in a frame by design) and the caption (its 1400 from the margin). The caption's box +# starts under the clock's count and the run's step counter (912 to 934). +words = {"clock": (0, 888, 1920, 46), "caption": (0, 940, 1464, 140)} none, beside, subject = split(0, 0, 14, 17, 8, 4), split(152, 152, 8, 17, 8), split(296, 200, 10, 9, 6) # The `blocks` lens: the graph over the program column, the source alone under it; the disassembly # (its view) over the state column, seven rows, the registers and six words under it. blocks = {**subject, "view": (976, 48, 880, ph(7)), "source": (64, 356, 880, ph(20))} del blocks["disasm"] +# Each pane's minimap a region of its own (motion.strips), secondary action: the source's, the +# disassembly's, the stack's, and the view's where it is a dump (not the calls lens's backtrace, +# not the syscalls lens's log). +def strips(panes, view): + out = motion.strips(panes) + if not view and "view strip" in out: + del out["view strip"] + out["view"] = panes["view"] + return out motion.REGIONS.update({ - "fib": {**subject, **words}, - "sort": {**blocks, **words}, + "fib": {**strips(subject, False), **words}, + "sort": {**strips(blocks, True), **words}, # The band is the calls so far; the disassembly a descent. - "syscalls": {**beside, **words}, - "heap": {**subject, **words}, - "list": {**subject, **words}, - # The band's drawing is the backtrace, then the kernel's side. - "sqlite": {**subject, **words}, - "zoom": {**none, **words}, - "gallery": {**beside, **words}, + "syscalls": {**strips(beside, False), **words}, + "musl": {**strips(beside, False), **words}, + "heap": {**strips(subject, True), **words}, + "list": {**strips(subject, True), **words}, + # The band's drawing is the backtrace, then the kernel's side; its view a dump. + "sqlite": {**strips(subject, True), **words}, + "zoom": {**strips(none, False), **words}, + "gallery": {**strips(beside, True), **words}, }) # `cut`: the gallery is the catalogue's pages, cut from one to the next (scenes/gallery.zig: 3, 6, 9.6, 13, 16, # 19.8, 21 and 24 s), not a scene: a page's first frame changes everything at once by design. @@ -92,8 +101,8 @@ def shown(text): text = re.sub(r"\\(.)", r"\1", text.replace("\\n", "")) return len(text.replace("`", "")) -# A scene that opens on the map dives (scenes/list.zig: at 2.5 s, 150 f): the falling map passes under the -# caption, which does not change. Its frames are no caption's arrival or leaving. +# A scene that opens on the map dives (scenes/list.zig: at 2.5 s, 150 f): the map's columns go into their +# strips over the caption, which does not change. Its frames are no caption's arrival or leaving. DIVES = {"list": (150, 300)} _lint = motion.lint diff --git a/anim/tools/sources.zig b/anim/tools/sources.zig new file mode 100644 index 0000000..8c8026e --- /dev/null +++ b/anim/tools/sources.zig @@ -0,0 +1,164 @@ +//! The sources a recording's lines name, other than the program's own, for +//! the source panel to follow the pc into (`Recording.sources`): +//! +//! sources embed TRACE OWN ZIG OUT every build, no network +//! sources fetch TRACE... `zig build sources` +//! +//! `embed` copies those it can read into OUT, a file each, and writes +//! OUT/sources.zig (`list`: each path, as the debug info names it, and its +//! text) for the scene to embed: Zig's musl from the lib directory of ZIG +//! (`zig env`: a static musl build's lines name it there), the rest +//! from the debuginfod client's cache by the build id of the module the pc +//! was in: //source/ (the cache: `$DEBUGINFOD_CACHE_PATH`, +//! else `$XDG_CACHE_HOME/debuginfod_client`, else `~/.cache/debuginfod_client`). What is in neither is left out: the +//! panel then waits a frame up, as it did before there were sources. +//! `fetch` asks the debuginfod server (the first of `$DEBUGINFOD_URLS`, +//! else of `/etc/debuginfod/*.urls`) for those the cache lacks, of +//! the modules whose names came from a separate debug file (a +//! distribution's library: never the program's own): `URL/buildid//source`, with curl, which sends nothing but its defaults. +//! The only step that uses the network. +const std = @import("std"); +const zt = @import("ztrace"); + +/// A file a moment's line names; the build id (hex) of the module the pc +/// was in, and whether that module's names came from a separate debug file. +const Named = struct { path: []const u8, id: []const u8, separate: bool }; + +/// Each file the recording's lines name, but the program's own (`own`, its bare name). +fn named(a: std.mem.Allocator, io: std.Io, trace_path: []const u8, own: []const u8) ![]Named { + var trace = try zt.Trace.open(a, io, trace_path); + defer trace.close(); + var out: std.ArrayList(Named) = .empty; + var tid: u32 = 0; + for (0..trace.len) |i| { + const m = try trace.moment(i); + if (tid == 0) { + const threads = try m.threads(a); + if (threads.len == 0) continue; + tid = threads[0]; + } + const line = (try m.line(tid)) orelse continue; + if (line.line == 0) continue; + const path = trace.strings.get(line.file) orelse continue; + if (std.mem.eql(u8, std.fs.path.basename(path), own)) continue; + if (for (out.items) |n| { + if (std.mem.eql(u8, n.path, path)) break true; + } else false) continue; + const regs = (try m.regs(tid)) orelse continue; + var module: []const u8 = ""; + var buf: [4096]u8 = undefined; + _ = try m.mapping(regs.rip, &module, &buf); + const mod = zt.telescope.module(m, module); + try out.append(a, .{ + .path = try a.dupe(u8, path), + .id = if (mod) |it| try std.fmt.allocPrint(a, "{x}", .{it.build_id}) else "", + .separate = if (mod) |it| it.debug == .separate else false, + }); + } + return out.items; +} + +/// Where a file of musl's is in Zig's lib directory, by its path from `libc/musl/`. +fn musl(a: std.mem.Allocator, path: []const u8, zig_lib: []const u8) !?[]const u8 { + const k = std.mem.indexOf(u8, path, "/libc/musl/") orelse return null; + return try std.fs.path.join(a, &.{ zig_lib, path[k + 1 ..] }); +} + +/// Where the cache keeps a module's source file: `//source/`. +fn cached(a: std.mem.Allocator, cache: []const u8, n: Named) ![]const u8 { + return std.fs.path.join(a, &.{ cache, n.id, "source", n.path }); +} + +/// Zig's lib directory, as `zig env` says it. +fn zigLib(a: std.mem.Allocator, io: std.Io, zig: []const u8) ![]const u8 { + const env = try std.process.run(a, io, .{ .argv = &.{ zig, "env" } }); + const key = ".lib_dir = \""; + const at = (std.mem.indexOf(u8, env.stdout, key) orelse return error.NoLibDir) + key.len; + return env.stdout[at .. std.mem.indexOfScalarPos(u8, env.stdout, at, '"') orelse return error.NoLibDir]; +} + +fn embed(a: std.mem.Allocator, io: std.Io, trace: []const u8, own: []const u8, zig: []const u8, cache: []const u8, out_dir: []const u8) !void { + const cwd = std.Io.Dir.cwd(); + const zig_lib = try zigLib(a, io, zig); + var dir = try cwd.createDirPathOpen(io, out_dir, .{}); + defer dir.close(io); + var list: std.ArrayList(u8) = .empty; + try list.appendSlice(a, "//! Generated by tools/sources.zig: the files the recording's lines name that the build found.\npub const list = [_][2][]const u8{\n"); + var k: usize = 0; + for (try named(a, io, trace, own)) |n| { + const from = (try musl(a, n.path, zig_lib)) orelse if (n.id.len > 0) try cached(a, cache, n) else continue; + const text = cwd.readFileAlloc(io, from, a, .limited(1 << 22)) catch continue; + // A path a Zig string literal holds as it is: nothing to escape. + if (std.mem.indexOfAny(u8, n.path, "\"\\\n") != null) continue; + const name = try std.fmt.allocPrint(a, "{d}", .{k}); + try dir.writeFile(io, .{ .sub_path = name, .data = text }); + try list.print(a, " .{{ \"{s}\", @embedFile(\"{s}\") }},\n", .{ n.path, name }); + k += 1; + } + try list.appendSlice(a, "};\n"); + try dir.writeFile(io, .{ .sub_path = "sources.zig", .data = list.items }); +} + +fn fetch(a: std.mem.Allocator, io: std.Io, url: []const u8, cache: []const u8, traces: []const []const u8) !void { + const cwd = std.Io.Dir.cwd(); + const base = std.mem.trimEnd(u8, url, "/"); + for (traces) |trace| for (try named(a, io, trace, "")) |n| { + if (!n.separate or n.id.len == 0 or !std.fs.path.isAbsolute(n.path)) continue; + const to = try cached(a, cache, n); + if (cwd.access(io, to, .{})) |_| continue else |_| {} + const part = try std.fmt.allocPrint(a, "{s}.part", .{to}); + const from = try std.fmt.allocPrint(a, "{s}/buildid/{s}/source{s}", .{ base, n.id, n.path }); + const got = try std.process.run(a, io, .{ .argv = &.{ "curl", "-fsS", "--create-dirs", "-o", part, from } }); + if (got.term == .exited and got.term.exited == 0) { + try cwd.rename(part, cwd, to, io); + std.debug.print("sources: {s} {s}\n", .{ n.id, n.path }); + } else { + cwd.deleteFile(io, part) catch {}; + std.debug.print("sources: not served: {s} {s}: {s}", .{ n.id, n.path, got.stderr }); + } + }; +} + +/// The debuginfod client's cache, as elfutils and Zig's std find it. +fn cacheDir(a: std.mem.Allocator, env: *const std.process.Environ.Map) ![]const u8 { + if (env.get("DEBUGINFOD_CACHE_PATH")) |p| return p; + if (env.get("XDG_CACHE_HOME")) |x| return std.fs.path.join(a, &.{ x, "debuginfod_client" }); + return std.fs.path.join(a, &.{ env.get("HOME") orelse "/", ".cache", "debuginfod_client" }); +} + +/// The debuginfod server: the first of `$DEBUGINFOD_URLS`, else of `/etc/debuginfod/*.urls`. +fn server(a: std.mem.Allocator, io: std.Io, env: *const std.process.Environ.Map) ?[]const u8 { + const first = struct { + fn of(text: []const u8) ?[]const u8 { + var words = std.mem.tokenizeAny(u8, text, " \t\n"); + return words.next(); + } + }.of; + if (env.get("DEBUGINFOD_URLS")) |urls| if (first(urls)) |url| return url; + var dir = std.Io.Dir.openDirAbsolute(io, "/etc/debuginfod", .{ .iterate = true }) catch return null; + defer dir.close(io); + var it = dir.iterate(); + while (it.next(io) catch null) |entry| { + if (!std.mem.endsWith(u8, entry.name, ".urls")) continue; + const text = dir.readFileAlloc(io, entry.name, a, .limited(1 << 16)) catch continue; + if (first(text)) |url| return url; + } + return null; +} + +pub fn main(init: std.process.Init) !void { + const a = init.arena.allocator(); + const args = try init.minimal.args.toSlice(a); + const cache = try cacheDir(a, init.environ_map); + if (args.len >= 6 and std.mem.eql(u8, args[1], "embed")) return embed(a, init.io, args[2], args[3], args[4], cache, args[5]); + if (args.len >= 2 and std.mem.eql(u8, args[1], "fetch")) { + const url = server(a, init.io, init.environ_map) orelse { + std.debug.print("sources: no debuginfod server: set DEBUGINFOD_URLS or /etc/debuginfod/*.urls\n", .{}); + return error.NoServer; + }; + return fetch(a, init.io, url, cache, args[2..]); + } + std.debug.print("usage: sources embed TRACE OWN ZIG OUT | sources fetch TRACE...\n", .{}); + return error.Usage; +} -- cgit v1.3