Wasm32-emscripten builds fail linking because of pthread dependency

floooh · November 6, 2025, 4:09pm

My sokol-zig CI has started failing for the Emscripten builds (where the Zig code is compiled with wasm32-emscripten because the pthread_kill() symbol is missing in the link step.

Does that ring a bell? Did the Zig stdlib accidentially get a general pthread dependency on wasm32-emscripten targets very recently? (which would suck because shared-memory multithreading in browsers is better to be avoided because SharedArrayBuffer is behind a COOP/COEP gate).

…I’ll also investigate on my side, more details to follow

PS: my CI is a few days behind because of the broken package download on Windows - and now I removed Windows from the build matrix and I’m running into the wasm32-emscripten problem.

castholm · November 6, 2025, 6:55pm

A quick search for pthread_kill in the repo suggests that these are the culprits:

github.com/ziglang/zig

lib/std/Io/Threaded.zig

b2895f356


      
              /// Whether this task bumps minimum number of threads in the pool.
              is_concurrent: bool,
          
              const Start = *const fn (*Closure) void;
          
              fn requestCancel(closure: *Closure) void {
                  switch (@atomicRmw(CancelId, &closure.cancel_tid, .Xchg, .canceling, .acq_rel)) {
                      .none, .canceling => {},
                      else => |tid| {
                          if (std.Thread.use_pthreads) {
                              const rc = std.c.pthread_kill(tid.toThreadId(), .IO);
                              if (is_debug) assert(rc == 0);
                          } else if (native_os == .linux) {
                              _ = std.os.linux.tgkill(std.os.linux.getpid(), @bitCast(tid.toThreadId()), .IO);
                          }
                      },
                  }
              }
          };
          
          pub const InitError = std.Thread.CpuCountError || Allocator.Error;

github.com/ziglang/zig

lib/std/Thread.zig

b2895f356


      
          const testing = std.testing;
          
          pub const Futex = @import("Thread/Futex.zig");
          pub const Mutex = @import("Thread/Mutex.zig");
          pub const Semaphore = @import("Thread/Semaphore.zig");
          pub const Condition = @import("Thread/Condition.zig");
          pub const RwLock = @import("Thread/RwLock.zig");
          pub const Pool = @import("Thread/Pool.zig");
          pub const WaitGroup = @import("Thread/WaitGroup.zig");
          
          pub const use_pthreads = native_os != .windows and native_os != .wasi and builtin.link_libc;
          
          /// A thread-safe logical boolean value which can be `set` and `unset`.
          ///
          /// It can also block threads until the value is set with cancelation via timed
          /// waits. Statically initializable; four bytes on all targets.
          pub const ResetEvent = enum(u32) {
              unset = 0,
              waiting = 1,
              is_set = 2,

I think the use_pthreads definition is too broad, but have you tried building with -fsingle_threaded (module.single_threaded = true in the build system)?

floooh · November 7, 2025, 8:03am

Hmm, slapping a .single_threaded = true on all my createModule() calls didn’t fix the issue, I’ll also need to investigate why that call even makes it into the build because most of the sokol-zig examples don’t even use the Zig stdlib.

PS: FWIW it works in release-fast and release-safe mode, only debug mode seems to include the pthread_kill() call.

castholm · November 7, 2025, 9:00am

I think it’s getting pulled in via std.debug.writeStackTrace():

github.com/ziglang/zig

lib/std/debug.zig

4b593a6c2


      
          /// Write a previously captured stack trace to `writer`, annotated with source locations.
          pub fn writeStackTrace(st: *const StackTrace, writer: *Writer, tty_config: tty.Config) Writer.Error!void {
              if (!std.options.allow_stack_tracing) {
                  tty_config.setColor(writer, .dim) catch {};
                  try writer.print("Cannot print stack trace: stack tracing is disabled\n", .{});
                  tty_config.setColor(writer, .reset) catch {};
                  return;
              }
              // We use an independent Io implementation here in case there was a problem
              // with the application's Io implementation itself.
              var threaded: Io.Threaded = .init_single_threaded;
              const io = threaded.ioBasic();
          
              // Fetch `st.index` straight away. Aside from avoiding redundant loads, this prevents issues if
              // `st` is `@errorReturnTrace()` and errors are encountered while writing the stack trace.
              const n_frames = st.index;
              if (n_frames == 0) return writer.writeAll("(empty stack trace)\n");
              const di_gpa = getDebugInfoAllocator();
              const di = getSelfDebugInfo() catch |err| switch (err) {
                  error.UnsupportedTarget => {
                      tty_config.setColor(writer, .dim) catch {};

Which is called by the std.start startup code that calls your main function, if your main function returns an error union:

github.com/ziglang/zig

lib/std/start.zig

4b593a6c2


      
                  => {
                      _ = std.posix.write(std.posix.STDERR_FILENO, "error: failed with error\n") catch {};
                      return 1;
                  },
                  else => {},
              }
              std.log.err("{s}", .{@errorName(err)});
              switch (native_os) {
                  .freestanding, .other => {},
                  else => if (@errorReturnTrace()) |trace| {
                      std.debug.dumpStackTrace(trace);
                  },
              }
              return 1;
          };
          
          return switch (@TypeOf(result)) {
              void => 0,
              u8 => result,
              else => @compileError(bad_main_ret),
          };

You might be able to work around in a few different ways, for example by declaring a non-error void/u8 main function, building with error return traces disabled, building with debug info stripped, or declaring pub const std_options: std.Options = .{ .allow_stack_tracing = false };. (But clearly it would be even better if you open an issue explaining that std.Io has regressed Emscripten.)

floooh · November 7, 2025, 9:07am

I’ll do that!

floooh · November 7, 2025, 4:25pm

Ok wrote a ticket here: wasm32-emscripten started to depend on clib thread func · Issue #25856 · ziglang/zig · GitHub

Sze · November 7, 2025, 4:41pm

I agree with the issue, however regarding:

for instance any WASM blob that’s hosted on Github pages cannot use threading

I think you could use what @tobyjaffey is using here Framebuffer and Audio WASM demos, coi-serviceworker:

However, this is worked around by using coi-serviceworker which reloads the page on startup.

But it seems you can’t avoid the reload on github pages.

floooh · November 7, 2025, 4:44pm

Yeah I know this service-worker “hack”, but I’ve also been hearing that this doesn’t work reliably.