build.zig Not Found — Como Resolver em Zig
O Que Este Erro Significa
O erro build.zig not found ocorre quando você executa zig build em um diretório que não contém um arquivo build.zig. Este arquivo é o sistema de build declarativo do Zig — equivalente ao Makefile, CMakeLists.txt ou package.json — e deve estar na raiz do projeto. Sem ele, o comando zig build não sabe como compilar o projeto.
A mensagem de erro:
error: no build.zig file found in . or any parent directories
Ou:
error: FileNotFound: build.zig
Causas Comuns
1. Executar zig build no Diretório Errado
# Você está em /home/user, mas o projeto está em /home/user/meu-projeto
$ zig build
# ERRO: build.zig not found — não está na raiz do projeto
2. Projeto Não Inicializado
# Diretório criado manualmente sem zig init
$ mkdir meu-projeto
$ cd meu-projeto
$ zig build
# ERRO: build.zig não existe
3. Arquivo com Nome Errado
$ ls
Build.zig # Maiúscula — Zig espera minúscula
main.zig
4. Usar zig build ao Invés de zig build-exe
Para compilar um único arquivo sem projeto, o comando correto é zig build-exe:
# Arquivo solto, sem projeto
$ ls
main.zig
$ zig build # ERRO: precisa de build.zig
$ zig build-exe main.zig # CORRETO para arquivo único
5. Subdiretório do Projeto
meu-projeto/
build.zig
src/
main.zig # Você está aqui
$ cd src
$ zig build # ERRO: build.zig está no diretório pai
Como Corrigir
Solucao 1: Inicializar um Projeto Zig
$ mkdir meu-projeto
$ cd meu-projeto
$ zig init
# Cria build.zig, build.zig.zon e src/main.zig automaticamente
$ zig build
# Sucesso!
Solucao 2: Navegar para a Raiz do Projeto
$ cd /caminho/para/meu-projeto # Onde está o build.zig
$ zig build
Solucao 3: Criar build.zig Manualmente
Para um projeto simples com executável:
// build.zig
const std = @import("std");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
const exe = b.addExecutable(.{
.name = "meu-projeto",
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
});
b.installArtifact(exe);
const run_cmd = b.addRunArtifact(exe);
run_cmd.step.dependOn(b.getInstallStep());
const run_step = b.step("run", "Executar o programa");
run_step.dependOn(&run_cmd.step);
}
Solucao 4: Criar build.zig para Biblioteca
// build.zig
const std = @import("std");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
const lib = b.addStaticLibrary(.{
.name = "minha-lib",
.root_source_file = b.path("src/lib.zig"),
.target = target,
.optimize = optimize,
});
b.installArtifact(lib);
// Testes
const tests = b.addTest(.{
.root_source_file = b.path("src/lib.zig"),
.target = target,
.optimize = optimize,
});
const run_tests = b.addRunArtifact(tests);
const test_step = b.step("test", "Executar testes");
test_step.dependOn(&run_tests.step);
}
Solucao 5: Compilar Arquivo Único sem build.zig
Se você não precisa de um projeto completo:
# Compilar executável
$ zig build-exe main.zig
# Compilar e executar
$ zig run main.zig
# Executar testes
$ zig test test_main.zig
Solucao 6: Especificar Caminho do build.zig
# Indicar onde o build.zig está
$ zig build --build-file /caminho/para/build.zig
Estrutura de Projeto Recomendada
meu-projeto/
build.zig # Configuração de build (obrigatório para zig build)
build.zig.zon # Manifesto de dependências
src/
main.zig # Ponto de entrada do executável
lib.zig # Ponto de entrada da biblioteca
modulo.zig # Módulos adicionais
tests/
test_modulo.zig # Testes
Verificar se o Projeto Está Configurado
# Listar os passos de build disponíveis
$ zig build --help
# Se funcionar, mostrará opções como:
# install (default)
# run
# test
Criar build.zig.zon (Manifesto)
Para projetos modernos com dependências, também é necessário o build.zig.zon:
// build.zig.zon
.{
.name = "meu-projeto",
.version = "0.1.0",
.dependencies = .{},
.paths = .{
"build.zig",
"build.zig.zon",
"src",
},
}
Migração de Projeto Sem Build System
Se você tem um projeto com apenas arquivos .zig soltos:
# 1. Inicializar o projeto
$ zig init
# 2. Mover seu código para src/
$ mv *.zig src/
# 3. Ajustar build.zig se necessário
# 4. Testar
$ zig build
$ zig build run
Erros Relacionados
- Dependency fetch failed — Falha ao baixar dependências
- Linker error — Erro de linker
- Target not supported — Alvo de compilação não suportado