E-xyza · ityonemo · Oct 27, 2025 · Aug 22, 2025 · Aug 23, 2025 · Aug 24, 2025
diff --git a/.envrc b/.envrc
diff --git a/.github/workflows/freebsd.yml b/.github/workflows/freebsd.yml
@@ -13,7 +13,7 @@ jobs:
       name: Setup Erlang
       with:
         otp-version: '27.3'
-        elixir-version: '1.18.3'
+        elixir-version: '1.17.3'
 
     - uses: actions/cache@v3
       id: deps-cache
@@ -33,7 +33,7 @@ jobs:
     - name: get zig
       run: |
         if [ ! -d zig ]; then
-          git clone -b 0.14.1 https://github.com/ziglang/zig.git
+          git clone -b 0.15.1 https://github.com/ziglang/zig.git
         fi 
 
     - name: Test in FreeBSD
@@ -43,9 +43,9 @@ jobs:
         mem: 8192
         usesh: true
         prepare: |
-          pkg install -y erlang-runtime27
-          pkg install -y elixir-devel
-          pkg install -y llvm19
+          pkg install -y erlang-runtime28
+          pkg install -y elixir
+          pkg install -y llvm20
           pkg install -y ca_root_nss
 
           pkg install -y cmake zstd libxml2 lzma ninja
@@ -57,7 +57,7 @@ jobs:
           mkdir -p build
 
           cd build
-          cmake .. -G Ninja -DZIG_STATIC_LLVM=ON -DCMAKE_PREFIX_PATH="/usr/local/llvm19;/usr/local;/usr/local/lib" -DCMAKE_EXE_LINKER_FLAGS="-L/usr/local/lib" -DCMAKE_BUILD_TYPE=ReleaseSafe
+          cmake .. -G Ninja -DZIG_STATIC_LLVM=ON -DCMAKE_PREFIX_PATH="/usr/local/llvm20;/usr/local;/usr/local/lib" -DCMAKE_EXE_LINKER_FLAGS="-L/usr/local/lib" -DCMAKE_BUILD_TYPE=ReleaseSafe
 
           ninja -C .
 

diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
@@ -9,16 +9,16 @@ jobs:
     strategy:
       matrix:
         pair:
-          - otp-version: '27.3'
-            elixir-version: '1.18.3'
+          - otp-version: '28.1'
+            elixir-version: '1.19.1'
+          - otp-version: '28.1'
+            elixir-version: '1.18.4'
           - otp-version: '27.3'
             elixir-version: '1.17.3'
           - otp-version: '26.2'
             elixir-version: '1.16.3'
           - otp-version: '25.3'
             elixir-version: '1.15.8'
-          - otp-version: '24.3'
-            elixir-version: '1.14.5'
     steps:
     - uses: actions/checkout@v4
     - uses: erlef/setup-beam@v1
@@ -49,7 +49,7 @@ jobs:
 
     - name: Get Zig version
       id: zig-version
-      run: echo "version=$(mix eval 'IO.puts(Zig.version())')" >> $GITHUB_OUTPUT
+      run: echo "version=$(mix run --no-compile --no-start -e 'IO.puts(Zig.version())')" >> $GITHUB_OUTPUT
 
     - uses: actions/cache@v3
       id: zig-cache

diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml
@@ -43,7 +43,7 @@ jobs:
 
       - name: Get Zig version
         id: zig-version
-        run: mix eval "IO.puts(Zig.version())"
+        run: mix run --no-compile --no-start -e "IO.puts(Zig.version())"
 
       - uses: actions/cache@v3
         id: zig-cache

diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml
@@ -5,6 +5,8 @@ on: push
 jobs:
   test:
     runs-on: windows-latest
+    env:
+        ImageOS: win22 
 
     steps:
       - name: Checkout repository
@@ -13,8 +15,8 @@ jobs:
       - name: Setup Elixir
         uses: erlef/setup-beam@v1
         with:
-          elixir-version: '1.18.3'  # adjust as needed
-          otp-version: '27.3'       # adjust as needed
+          elixir-version: '1.18.4'  # adjust as needed
+          otp-version: '28.1'       # adjust as needed
 
       - uses: actions/cache@v3
         id: deps-cache
@@ -38,7 +40,7 @@ jobs:
         id: zig-version
         shell: bash
         run: | 
-          VERSION=$(mix eval "IO.puts(Zig.version())" | tail -n 1)
+          VERSION=$(mix run --no-compile --no-start -e "IO.puts(Zig.version())" | tail -n 1)
           echo "zig_version=$VERSION" >> $GITHUB_OUTPUT
 
       - uses: actions/cache@v3
@@ -53,4 +55,4 @@ jobs:
       - name: Run Tests
         env:
           RUNNING_CI: "TRUE"
-        run: mix test --exclude no_ci --exclude on_upgrade --exclude skip_windows
+        run: mix test --exclude no_ci --exclude on_upgrade --trace
diff --git a/.gitignore b/.gitignore
@@ -53,5 +53,12 @@ zigler-*.tar
 # other compiled files
 *.a
 
+# local development files
+.envrc
+
 /test/code
-/test/corner_cases/staging
+/test/corner_cases/staging
+
+# precompilation test module
+/precompiled/bin
+/precompiled/lib
diff --git a/README.md b/README.md
@@ -25,7 +25,7 @@ by adding `zigler` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:zigler, "~> 0.14.1", runtime: false}
+    {:zigler, "~> 0.15.1", runtime: false}
   ]
 end
 ```
@@ -36,7 +36,7 @@ end
 
 TBD.
 
-`~/.cache/zigler/zig-linux-<arch>-0.14.1`
+`~/.cache/zigler/zig-linux-<arch>-0.15.1`
 
 ### Main Installation
 

diff --git a/VERSIONS.md b/VERSIONS.md
@@ -164,8 +164,26 @@ Thanks to Dave Cottlehuber @dch for testing.
 
 - no changes.
 
-## Upcoming
-- `precompiled` mode that will let you obtain packages with precompiled assets.
+## 0.15.2
 
-## Possible
+- Breaking changes:
+  - rename "packages" option to "extra_modules"
+  - unification of path scheme ("./" is project-rooted)
+  - renamed `release_mode` to `optimize`.  Also note the new optimize policy defaults
+    to `ReleaseSafe` in non-dev, non-test modes and defaults to `Debug` in test and dev.
+- Policy changes:
+  - error return traces by default in ReleaseSafe builds
+- Temporary Regressions:
+  - Error return traces are disabled in MacOS (due to https://github.com/ziglang/zig/issues/25433)
+  - on_upgrade tests are failing in elixir 1.19.x; may or may not reflect a real problem.
+- Outstanding issues:
+  - c_ulonglong doesn't work on windows; c_long doesn't work on other platforms.
+- Features:
+  - add "dependency" option for zig dependencies
+  - `precompiled` option that will let you use precompiled library assets.  NOTE: this feature is highly
+    experimental and functions might need to be compiled for different erts versions.  This will likely 
+    be changed in the future.
+  - adds `beam.get_list_cell`
+
+## Possible Future Changes
 - `struct` which lets you declare a struct inside your zig code as the module's struct
diff --git a/guides/01-nifs.md b/guides/01-nifs.md
@@ -132,7 +132,7 @@ For more on marshalling collection datatypes, see [`collections`](collections.ht
 
 You may also manually marshal types into and out of the beam by using the
 [`beam.term`](beam.html#term) datatype. To do so, you must first import the [`beam`](beam.html)
-package. The `beam.term` type is an opaque, wrapped datatype that ensures safe manipulation of terms
+module. The `beam.term` type is an opaque, wrapped datatype that ensures safe manipulation of terms
 as a token in your zig code.
 
 ```elixir
@@ -216,6 +216,16 @@ test "erroring" do
 end
 ```
 
+> ### Error Return Trace Availability {: .info}
+>
+> errorReturnTrace is enabled by default in Debug and ReleaseSafe builds, and disabled in ReleaseFast
+> and ReleaseSmall builds. This differs from the zig default. 
+>
+> Note that the erlang compiler has a --no-debug-info parameter that might be set; if this flag is
+> set, then errorReturnTrace will be disabled in ReleaseSafe builds.
+>
+> To override this policy, set the `:error_tracing` option.
+
 ### A few notes on the above code.
 
 - to marshal a value out of a `beam.term` and into a zig static type, use [`beam.get`](beam.html#get).

diff --git a/guides/03-allocators.md b/guides/03-allocators.md
@@ -106,8 +106,11 @@ higher alignment than the maximum alignment for builtin types.
 
 ```elixir
 ~Z"""
+const std = @import("std");
+
 pub fn allocate_large_aligned(count: usize) !usize {
-    const page = try beam.allocator.allocWithOptions(u8, count, 4096, null);
+    const alignment = comptime std.mem.Alignment.fromByteUnits(4096);
+    const page = try beam.allocator.alignedAlloc(u8, alignment, count);
     defer beam.allocator.free(page);
 
     return @intFromPtr(page.ptr);
@@ -151,7 +154,7 @@ pub fn noleak() !bool {
 }
 """
 
-@tag [erroring: true, skip_windows: true]
+@tag :erroring
 test "leak checks with debug allocator" do
   require Logger
   Logger.warning("====== the following leak message is expected: =========== START")
@@ -166,14 +169,12 @@ end
 ## Building composable allocators backed by zig's beam allocator
 
 Because zigler's beam allocators conform to zig's allocator interface, you may use use any
-composable allocator in the standard library or any composable allocator from an imported zig
-package, passing any one of the beam allocators into place. 
+composable allocator in the standard library or any composable allocator from an imported module,
+passing any one of the beam allocators into place. 
 
 ```elixir
 ~Z"""
 pub fn with_arena() !beam.term {
-    const std = @import("std");
-
     var arena = std.heap.ArenaAllocator.init(beam.allocator);
     defer arena.deinit();
 

diff --git a/guides/04-nif_options.md b/guides/04-nif_options.md
@@ -147,7 +147,7 @@ defmodule LeakCheckTest do
   }
   """
 
-  @tag [erroring: true, skip_windows: true]
+  @tag :erroring
   test "leak check" do
     require Logger
     Logger.warning("====== the following leak message is expected: =========== START")
@@ -177,7 +177,7 @@ defmodule LeakCheckAllTest do
   }
   """
 
-  @tag [erroring: true, skip_windows: true]
+  @tag :erroring
   test "leak check" do
     require Logger
     Logger.warning("====== the following leak message is expected: =========== START")

diff --git a/guides/06-c_integration.md b/guides/06-c_integration.md
@@ -55,11 +55,11 @@ This example shows you how to link in a system library (which can be `.a`, `.so`
 `.dll`). Zig will resolve the extension based on the operating system native rules. To use the
 functions in the library, there must also be an associated `.h` file with `extern` functions.
 
-If you wish to package a `.so` file with the project, you have two options:
+If you wish to distribute a `.so` file with the project, you have two options:
 
-1. package the file in the `priv` directory and use `{:priv, "path/to/lib.so"}`. Note that in this
+1. distribute the file in the `priv` directory and use `{:priv, "path/to/lib.so"}`. Note that in this
   case, you must provide `lib` prefix and `.so` or `.dylib` or `.dll` extensions, if applicable.
-1. package the file using an absolute or relative path (relative the code file location). use
+1. distribute the file using an absolute or relative path (relative the code file location). use
   `"path/to/lib.so"`. You must provide `lib` and `.so` or `.dylib` or `.dll` extension.
 
 In this example we'll use the `cblas_dasum` function, which takes a length, an pointer to

diff --git a/guides/08-module_options.md b/guides/08-module_options.md
@@ -69,15 +69,15 @@ defmodule Attribute do
 end
 ```
 
-## adding packages
+## adding modules
 
-It's possible to add zig files as packages using the `packages` keyword option. The name of the
-package is the key, and the value is a tuple of the path to the zig file that acts as the package
-and a list of dependencies for the package. 
+It's possible to add zig files as modules using the `extra_modules` keyword option. The name of the
+module is the key, and the value is a tuple of the path to the zig file that acts as the module
+and a list of transitive module dependencies. 
 
 ### Example extra.zig
 
-```zig
+````zig
 pub const value = 47;
 ```
 
@@ -86,7 +86,7 @@ defmodule PackageFile do
   use ExUnit.Case, async: true
   use Zig, 
     otp_app: :zigler,
-    packages: [extra: {"test/_support/package/extra.zig", [:beam]}]
+    extra_modules: [extra: {"./test/_support/module/extra.zig", [:beam]}]
 
   ~Z"""
   const extra = @import("extra");
@@ -96,7 +96,7 @@ defmodule PackageFile do
   }
   """
 
-  test "package file" do
+  test "module file" do
     assert 47 = extra_value()
   end
 end
@@ -105,18 +105,16 @@ end
 ## Release Mode
 
 Zig has several release modes, and you can specify which release mode to build your program under
-using the `release_mode` option. Importantly, it is possible to set a release mode that depends on
-mix environment.
+using the `optimize` option.  This option defaults to `:debug` if you are in `:dev` or `:test`
+and `:safe` otherwise (or if the `Mix` module is not available).  You may also specify `:env` which
+reades the `ZIGLER_RELEASE_MODE` environment variable, or `{:env, default}` which lets you specify
+a different default mode if `ZIGLER_RELEASE_MODE` is not set.
 
 ```elixir
 defmodule ReleaseMode do
   use ExUnit.Case, async: true
-  mode = case MyApp.env() do
-    :prod -> :safe
-    _ -> :debug
-  end
 
-  use Zig, otp_app: :zigler, release_mode: mode
+  use Zig, otp_app: :zigler, optimize: :fast
 
   ~Z"""
   const beam = @import("beam");
@@ -126,7 +124,40 @@ defmodule ReleaseMode do
   """
 
   test "release mode" do
-    assert :Debug == get_mode()
+    assert :ReleaseFast == get_mode()
+  end
+end
+```
+
+## Error Traces
+
+By default, zigler will provide error traces in Debug and ReleaseSafe modes.  You may
+override this in ReleaseSafe by supplying the `error_tracing` option
+
+```elixir
+defmodule ErrorTraces do
+  use ExUnit.Case, async: true
+
+  use Zig, otp_app: :zigler, error_tracing: false, optimize: :safe
+
+  ~Z"""
+  pub fn add_one(x: u32) !u32 {
+      if (x == 42) return error.BadNumber;
+      return x + 1;
+  }
+  """
+
+  test "error traces can be overridden" do
+    assert 48 == add_one(47)
+
+    stacktrace = try do
+      add_one(42)
+    rescue
+      _ ->
+        __STACKTRACE__
+    end
+
+    assert [{__MODULE__, :add_one, 1, _} | _] = stacktrace
   end
 end