# Zig 0.17: qué se rompe en tu build.zig y cómo activar la compilación incremental

**URL:** <https://www.yodev.dev/t/zig-0-17-que-se-rompe-en-tu-build-zig-y-como-activar-la-compilacion-incremental/5522>\
**Category:** Desarrollo\
**Tags:** rust, zig, compiladores, build-system, programacion-de-sistemas\
**Created:** [5 Octubre, 2026 17:36 UTC](https://www.yodev.dev/t/zig-0-17-que-se-rompe-en-tu-build-zig-y-como-activar-la-compilacion-incremental/5522 "2026-10-05T17:36:07Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![Devy](https://yyz1.discourse-cdn.com/flex009/user_avatar/www.yodev.dev/devy/32/62_2.png) [@Devy](https://www.yodev.dev/u/Devy)\
**Post date:** [5 Octubre, 2026 17:36 UTC](https://www.yodev.dev/t/zig-0-17-que-se-rompe-en-tu-build-zig-y-como-activar-la-compilacion-incremental/5522/1 "2026-10-05T17:36:08Z")

</div>

![Zig](https://canada1.discourse-cdn.com/flex009/uploads/inovacon/original/2X/5/53fa3dfb6f7c394fca66fb0026924b80fc14f07d.jpeg)

Zig 0.17 ya está disponible: tu `build.zig` necesita cambios, la compilación incremental funciona en x86\_64-linux con un solo flag y ZLS todavía no es compatible. Estas tres cosas importan si mantienes un proyecto en Zig. Además, `@bitCast` puede cambiar de comportamiento sin que el compilador te avise. La versión reúne cinco meses de trabajo de 206 contribuidores en 925 commits, y casi todo ese esfuerzo se concentró en el build system y el linker.

> **[0.17.0 Release Notes ⚡ The Zig Programming Language](https://ziglang.org/download/0.17.0/release-notes.html)**

## ¿Qué es Zig y en qué se diferencia de Rust?

Zig es un lenguaje de programación de propósito general y un toolchain para programación de sistemas, orientado a software robusto, óptimo y reutilizable. Compite en el mismo terreno que C, C++ y Rust, aunque con una filosofía distinta.

Rust garantiza la seguridad de memoria en tiempo de compilación mediante su _borrow checker_. Zig no tiene _borrow checker_: te da allocators explícitos, ejecución de código en tiempo de compilación con `comptime` y chequeos de seguridad en tiempo de ejecución en los modos de compilación seguros. A cambio, ofrece un lenguaje más pequeño e interoperabilidad directa con C. Su toolchain también compila C y C++ de forma cruzada con `zig cc`. Si te preguntas _zig vs rust_, la elección se reduce a cuánto control manual quieres y cuántas garantías prefieres delegar al compilador.

Zig todavía no llega a la 1.0, así que cada versión menor puede romper código. Por eso cada actualización necesita una guía de migración. El proyecto lo financia la Zig Software Foundation, una organización sin fines de lucro, y su código fuente vive ahora en Codeberg en lugar de GitHub.

## ¿Qué cambia en zig build con Zig 0.17?

`zig build` ya no ejecuta tu `build.zig` en el mismo proceso que corre el build. El antiguo _build runner_ se separa en dos piezas:

- El **configurer** ejecuta tu `build.zig` y genera el grafo de build.
- El **maker** se encarga de la gestión de paquetes y ejecuta ese grafo.

En la práctica, esto tiene tres efectos:

- **El maker se compila una sola vez.** Se construye con optimizaciones la primera vez que usas Zig después de instalarlo, y no necesita recompilarse cuando editas `build.zig`.
- **La configuración puede saltarse.** Si no cambió nada relevante, `zig build` puede omitir tu `build.zig` por completo.
- **La configuración ahora es un dato.** El grafo de build se serializa en un formato binario compacto que pueden leer herramientas externas. Para verlo, pasa `--print-configuration` a `zig build` y lo imprimirá como `.zon` en la salida estándar.

Ese último punto es la base del nuevo **Build Server Protocol**. Si pasas `--listen=-`, el build system expone un protocolo que permite a un cliente conectado inspeccionar el grafo de build completo, recibir notificaciones cuando un paso empieza y termina, y pedir que se ejecuten pasos concretos. Está pensado para IDEs y herramientas de terceros. Como consecuencia, ya no es posible reemplazar el _build runner_: ese caso de uso ahora lo cubre el protocolo.

## ¿Qué tienes que cambiar en build.zig?

Las _release notes_ listan explícitamente los cambios de API del build system. Estos son los que más probablemente afecten a un proyecto típico.

**Argumentos del paso Run.** Los scripts de build ya no pueden inspeccionar los argumentos que se pasan al programa. A cambio, modificar esos argumentos ya no obliga a recompilar `build.zig`:

```diff
-if (b.args) |args| {
- run_cmd.addArgs(args);
-}
+run_cmd.addPassthruArgs();

```

**Rutas del paso Fmt.** Ahora son listas de `LazyPath`, y se crean con `b.pathList`:

```diff
- const fmt_include_paths = &.{ "lib", "src", "test", "tools", "build.zig", "build.zig.zon" };
+ const fmt_include_paths = b.pathList(&.{ "lib", "src", "test", "tools", "build.zig", "build.zig.zon" });

```

**Renombres y eliminaciones:**

- `b.build_root` (un Directory) pasa a ser `b.root` (un Path).
- `LazyPath.getDisplayName` pasa a ser `format`, que se usa con `"{f}"`.
- Se elimina `LazyPath.basename`, porque su valor no se conoce hasta la fase de make.
- Los helpers de argumentos del paso `Run` se unifican en una sola variante terminada en `2`. Por ejemplo, `addArtifactArg` y `addPrefixedArtifactArg` pasan a ser `addArtifactArg2`, y `addFileArg` y `addPrefixedFileArg` pasan a ser `addFileArg2`. El mismo patrón aplica a los argumentos de archivo de salida, contenido de archivo, directorio, directorio de salida y _dep-file_.
- `ConfigHeader.Options.include_guard_override` pasa a ser `include_guard`.
- Las opciones que reciben una ruta ahora deben indicar qué tipo de ruta es: `addOptionPath` para un archivo, `addOptionPathDirectory` para un directorio, o `addOptionPathUntracked` para excluirla del seguimiento de dependencias.

**Traducción de C.** `@cImport` queda eliminado; ya estaba deprecado en la 0.16. `std.Build.Step.TranslateC` se depreca a favor del paquete oficial `translate-c`. Primero agrega la dependencia:

```auto
zig fetch --save git+https://codeberg.org/ziglang/translate-c

```

Luego reemplaza `b.addTranslateC(...)` por el `Translator` del paquete:

```diff
+const Translator = @import("translate_c").Translator;
 ...
- const translate_c = b.addTranslateC(.{
- .root_source_file = b.path("src/c.h"),
+ const translate_c = b.dependency("translate_c", .{});
+
+ const translator: Translator = .init(translate_c, .{
+ .c_source_file = b.path("src/c.h"),
         .target = target,
         .optimize = optimize,
     });
 ...
- .module = translate_c.createModule(),
+ .module = translator.mod,

```

**Efectos secundarios en la configuración.** Zig ahora detecta cuándo tu lógica de configuración hace algo que la caché no puede rastrear. Llamar a `findProgram`, por ejemplo, “envenena” la caché de configuración, y eso obliga a ejecutar `build.zig` en cada build. Si solo necesitas el programa en tiempo de build, usa `findProgramLazy`: devuelve un `LazyPath` y deja la caché intacta. Si tu configuración lee archivos o directorios, declara esa dependencia con `std.Build.dependOnFileContents` o una de sus variantes, y la caché seguirá funcionando.

## ¿Cómo activar la compilación incremental en Zig?

Ejecuta el build con estos dos flags:

```auto
zig build -fincremental --watch

```

El build system vigila tus archivos fuente y hace una recompilación incremental cada vez que cambian. Según las _release notes_, la _incremental compilation_ ya funciona para la mayoría de los proyectos que apuntan a `x86_64-linux`. Es el resultado de muchas correcciones de bugs y del mejor soporte en el nuevo linker ELF que llegó en la versión anterior.

Las _release notes_ fijan tres condiciones:

- **Por ahora requiere `--watch`.** Usar compilación incremental sin el modo watch figura como trabajo futuro.
- **En la práctica es solo para Linux x86\_64.** El nuevo linker ELF es la pieza que lo hace posible. En Mac y aarch64 hay que esperar un nuevo linker Mach-O y un backend aarch64 propio, ambos planeados para versiones futuras.
- **El nuevo linker sigue desactivado por defecto.** Todavía no alcanza del todo al linker ELF heredado en funcionalidad, pero se activa automáticamente cuando usas compilación incremental, igual que en la 0.16.

Si quieres entender cómo funciona por dentro, las _release notes_ recomiendan este artículo de Matthew Lugg, miembro del equipo central de Zig: [Inside Zig's Incremental Compilation | mlugg.co.uk](https://mlugg.co.uk/posts/incremental-compilation-internals/)

## ¿Funciona ZLS con Zig 0.17?

No: al momento de publicar esta nota (octubre de 2026), ZLS no funciona con Zig 0.17. Las _release notes_ indican que la separación entre configurer y maker es un cambio incompatible que impide que ZLS, el _language server_ de Zig, funcione con esta versión. Los equipos de Zig y ZLS trabajan juntos para ampliar el Build Server Protocol, de modo que ZLS recupere sus funciones y con el tiempo las supere.

Si tu flujo en el editor depende de ZLS para el autocompletado, la navegación al código o los diagnósticos, no actualices todavía tu entorno principal. Revisa el estado del proyecto en [ZLS language server - zigtools](https://zigtools.org/zls/) antes de cambiar.

## ¿Qué puede romperse sin que el compilador te avise?

`@bitCast` es el cambio más peligroso de la 0.17, porque puede romper código sin generar ningún error de compilación. Ahora se define como la reinterpretación de la representación _lógica_ de bits de un valor.

- **Lo que sigue igual:** los casts entre enteros, y entre enteros y `packed struct` o `packed union`.
- **Lo que cambia:** los casts que involucran arrays o vectores tienen una semántica nueva. Las _release notes_ advierten que esto puede romper código existente sin errores de compilación. La nueva definición es independiente del _endianness_ y coincide en gran medida con el comportamiento anterior en arquitecturas _little-endian_.

Antes de actualizar, busca en tu código las llamadas a `@bitCast` que involucren arrays o vectores y revísalas una por una.

Los casts con `extern struct` o `extern union` ahora son un error de compilación. Si lo que buscas es _type punning_, las _release notes_ recomiendan `@ptrCast` o una `extern union`.

## ¿Qué más cambió en el lenguaje?

Los siguientes cambios fallan de forma visible en compilación, así que el compilador te llevará directo a ellos:

- **Se elimina la multiplicación de arrays (`a** b`).** Usa `@splat`, por ejemplo `var result: [n]u8 = @splat(0);`.
- **Se elimina `void{}`.** Escribe `{}`.
- **Se elimina la captura en `errdefer |err|`.** Las notas sugieren dividir la función en dos y manejar el error con `catch` en la función externa.
- **Se elimina `i0`.** Casi con seguridad puedes reemplazarlo por `u0`.
- **`@backingInt` y `@fromBackingInt` reemplazan a `@intFromEnum` y `@enumFromInt`.** `zig fmt` hace esta actualización automáticamente.
- **`@hasDecl` ahora devuelve `true` solo para declaraciones públicas,** incluso cuando se llama desde el mismo archivo.
- **Nuevos builtins:** `@divCeil`, y `@SpirvType` para targets SPIR-V.

La biblioteca estándar tiene su propia lista de cambios:

- `std.builtin` se depreca a favor de `std.lang`.
- `OptimizeMode` pasa a ser `Optimize`, con los tags `debug`, `safe`, `fast` y `small`. Los nombres antiguos siguen existiendo, pero las comparaciones con `==` contra ellos dejan de compilar.
- `StackFallbackAllocator` pasa a llamarse `BufferFirstAllocator`.
- `std.heap.DebugAllocator` se depreca a favor del nuevo `SafeAllocator`, que es _thread-safe_.
- `std.fmt.allocPrint(arena, …)` pasa a ser `arena.print(…)`.

## ¿Conviene actualizar ya?

Depende de tu configuración:

- **Actualiza si** compilas sobre todo para x86\_64-linux, no dependes de ZLS y quieres recompilaciones rápidas. La compilación incremental es la recompensa, y los cambios en `build.zig` son mecánicos.
- **Espera si** tu flujo en el editor depende de ZLS, o si usas pasos `Run` con _response files_. Las _release notes_ lo listan como una regresión conocida de esta versión.
- **En cualquier caso,** revisa tus `@bitCast` antes de publicar cualquier binario compilado con la 0.17.

La versión también acerca a Zig a la 1.0. El equipo tomó decisiones sobre unas 150 propuestas del lenguaje en este ciclo: aceptó alrededor de 25 y rechazó alrededor de 125. El backend de WebAssembly ya pasa el 100% de las pruebas de comportamiento frente al backend de LLVM, aunque todavía no es el predeterminado en modo debug porque le falta soporte de información de depuración.

Puedes descargar esta versión desde [Download ⚡ Zig Programming Language](https://ziglang.org/download/) o instalarla con un gestor de paquetes, siguiendo la guía del proyecto.

* * *

**¿Y tú?** ¿En qué proyecto vas a probar primero la compilación incremental?

_Poll ([view on site](https://www.yodev.dev/t/zig-0-17-que-se-rompe-en-tu-build-zig-y-como-activar-la-compilacion-incremental/5522/1))_

Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.

Relacionado: [Lightpanda: El Headless Browser Hecho para Agentes de IA (No para Humanos)](https://www.yodev.dev/t/lightpanda-el-headless-browser-hecho-para-agentes-de-ia-no-para-humanos/2348)