---
title: "build.zig Not Found — Como Resolver em Zig"
url: "https://ziglang.com.br/erros/build.zig-not-found-como-resolver-em-zig/"
markdown_url: "https://ziglang.com.br/erros/build.zig-not-found-como-resolver-em-zig.MD"
description: "Entenda o erro 'build.zig not found' em Zig, que ocorre quando o comando zig build não encontra o arquivo de configuração do projeto. Veja como resolver."
date: "2026-02-21"
author: "Zig Brasil"
---

# build.zig Not Found — Como Resolver em Zig

Entenda o erro 'build.zig not found' em Zig, que ocorre quando o comando zig build não encontra o arquivo de configuração do projeto. Veja como resolver.


# 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

```bash
# 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

```bash
# 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

```bash
$ 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`:

```bash
# 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

```bash
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

```bash
$ 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

```bash
$ 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:

```zig
// 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

```zig
// 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:

```bash
# 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

```bash
# 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

```bash
# 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`:

```zig
// 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:

```bash
# 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](/erros/erro-dependency-fetch-failed/) — Falha ao baixar dependências
- [Linker error](/erros/erro-linker-error/) — Erro de linker
- [Target not supported](/erros/erro-target-not-supported/) — Alvo de compilação não suportado

## Links Úteis

- [Documentação oficial do Zig — Build System](https://ziglang.org/documentation/master/#Zig-Build-System)
- [Receitas de configuração de projeto](/receitas/)
- [Tutorial de introdução ao Zig](/tutoriais/)