Out-of-source builds — a pasta de build deve ser separada

1. Out-of-source build: ideia e sentido

Se você é novo em programação, é fácil pensar assim: “Eu tenho main.cpp e CMakeLists.txt. Cliquei em Run — então em algum lugar vai aparecer o programa. Qual a diferença de onde?” E é aí que começa a mágica do mundo real: a compilação é um processo que produz muitos arquivos intermediários, e esses arquivos também precisam ser guardados em algum lugar — caso contrário o projeto vira uma bagunça.

Out-of-source build é a abordagem em que você nunca gera arquivos de build na pasta com os fontes. Os fontes ficam limpos: src/, include/, CMakeLists.txt e por aí vai. Tudo o que o sistema de build cria (arquivos temporários, objetos, caches, arquivos de projeto para IDEs/generadores) vai para uma pasta separada — normalmente build/ ou várias pastas como build-debug/, build-release/.

Para facilitar a memorização:

Os fontes são o texto que você escreve. A pasta de build é a “cozinha” onde esse texto vira um executável.
Na cozinha inevitavelmente haverá bagunça (farinha, facas, louça), mas isso não é motivo para guardar tudo no quarto.

2. O que vive na pasta de build e por que isso não deve ficar junto com o código

Se você só compilou projetos em Web‑IDE, pode não ter visto as “entradas” do processo de build. Uma IDE local e o CMake são bem mais honestos: eles não escondem que a compilação é um universo inteiro de artefatos. E esse universo cresce muito rápido.

Numa pasta de build típica você encontra arquivos objeto (resultado da compilação de .cpp), arquivos do sistema de build (por exemplo, para Ninja ou Make), diretórios temporários do CMake, vários arquivos de configuração de serviço, caches de configuração e resultados da “detecção do ambiente” (qual compilador, quais paths, quais bibliotecas foram encontradas). Mesmo que você não tenha pedido, o sistema precisa disso para que a segunda execução da build seja mais rápida e para não repetir as mesmas perguntas sempre.

Existe até um fato curioso do mundo “muito sério do C++”: mesmo no processo de preparação de rascunhos do padrão C++ as pessoas agradecem separadamente quem melhorou o processo de build e a infraestrutura — isso mostra o quão importante e não trivial isso é.

No nosso mini‑projeto didático (vamos chamá‑lo de Tasker — uma utilidade de console simples que por enquanto só imprime uma saudação) os fontes podem estar assim:

tasker/
  CMakeLists.txt
  src/
    main.cpp
  include/
    tasker_version.hpp

E a pasta de build fica mais ou menos assim:

tasker/
  build/
    CMakeCache.txt
    CMakeFiles/
    build.ninja (ou Makefile)
    tasker (arquivo executável)
    ...

A ideia principal: tudo o que aparece em build/ não é código-fonte. É ou um resultado intermediário, ou a “memória” do sistema de build. Se você mantém isso junto dos fontes, só atrapalha: fica mais difícil se orientar, mais difícil limpar o projeto, mais difícil explicar a estrutura para outra pessoa e mais difícil manter várias configurações.

3. Por que in-source build — quase sempre — é má ideia

Iniciantes frequentemente fazem assim: criam a pasta do projeto, abrem o terminal na raiz, executam o CMake “do jeito que der” e, de repente, ao lado do CMakeLists.txt aparecem CMakeCache.txt, CMakeFiles/ e dezenas de outros arquivos. Isso é justamente o que chamamos de in-source build.

O problema não é que “isso é proibido” (tecnicamente funciona), mas que isso cria problemas práticos bem desagradáveis. Fica difícil distinguir “meu código” do “lixo de build”. Ao refatorar, mover arquivos, escrever instruções para a equipe ou abrir o projeto depois de um ano, a sua mente perde tempo limpando em vez de trabalhar.

Outro incômodo é conflito de nomes e caminhos. O sistema de build pode gerar arquivos com nomes que coincidem com os seus. Ou você pode acidentalmente adicionar ao repositório coisas que não deveriam entrar (por exemplo, caches e artefatos). No fim, no GitHub você não tem um projeto, mas uma camada arqueológica de “vestígios de build”.

E o mais irritante: in-source build torna o “reset rápido do estado” muito inconveniente. Quando a compilação quebra por um estado estranho, a forma mais confiável é apagar a pasta de build e recriá‑la. Mas se você compilou na raiz do projeto, “apagar a pasta de build” significa “apagar metade dos arquivos na raiz e rezar para não apagar os fontes”.

4. Modelo “fontes separados, build separado”

Neste ponto é importante não se afogar em termos nem transformar a ideia simples numa “religião CMake”. Basta adotar um hábito prático: mantenha na raiz do projeto apenas o que você edita manualmente, e tudo que é gerado — leve para fora.

Para o nosso Tasker isso significa: consideramos a pasta tasker/ uma “zona limpa”. Ali ficam src/, include/, CMakeLists.txt. Ponto. Já a pasta build/ é a “zona suja”, onde o CMake e o compilador podem fazer o que quiserem, e nós não os censuramos por isso.

Visualmente, a out-of-source build é conveniente de pensar como duas “faixas” paralelas:

(fontes) tasker/                 (artefatos) tasker/build/
  CMakeLists.txt                      CMakeCache.txt
  src/main.cpp                        CMakeFiles/...
  include/tasker_version.hpp          tasker (exe)

Se você gosta de diagramas (eu gosto — diagramas não discutem), dá para desenhar assim:

flowchart LR
    A[Fontes: src/, include/, CMakeLists.txt] --> B[Configure: CMake]
    B --> C[Diretório de build: build/]
    C --> D[Compilação: .o/.obj]
    D --> E[Linkagem]
    E --> F[Arquivo executável]

O sentido do diagrama é simples: o configure “vincula” seu projeto a uma pasta de build específica, e daí toda a compilação vive lá. Os fontes permanecem imutáveis.

5. Prática no Tasker: raiz limpa e várias pastas de build

Mini‑demonstração: fontes do Tasker e raiz limpa

Agora não vamos tentar escrever uma “super‑aplicação”. Nosso objetivo é que o projeto seja real o bastante para que a compilação gere artefatos, mas simples o suficiente para que você não tenha medo de abrir qualquer arquivo.

Que tal o src/main.cpp ficar assim:

#include <iostream>
#include "tasker_version.hpp"

int main() {
    std::cout << "Tasker v" << TASKER_VERSION << '\n'; // Tasker v0.1
}

E o cabeçalho include/tasker_version.hpp assim:

#pragma once

#define TASKER_VERSION "0.1"

Sim, isso “quase não faz nada”. E isso é ótimo: aqui treinamos não algoritmos, mas a organização do build.

Agora o ponto principal: seja qual for a forma como você compilar esse projeto (IDE, Ninja, Make), se você fizer out-of-source, pretende que depois da compilação a raiz do projeto continue igualmente arrumada:

tasker/
  CMakeLists.txt
  src/
  include/
  build/     (e é aqui que começa a “cozinha interna”)

Você compra conveniência: sempre pode abrir tasker/ e não ver milhares de arquivos que você mesmo não criou.

Por que ter várias pastas de build, mesmo que o projeto seja pequeno

Quando você adota o hábito “build separado”, logo surge outro hábito útil: cenários diferentes de build — pastas de build diferentes. Mesmo que por enquanto você tenha uma ideia vaga do que distingue Debug de Release, a ideia de que “duas builds diferentes não devem pisar uma na outra” é prática.

Imagine que você quer compilar o projeto com um compilador agora e com outro depois. Ou em uma IDE e depois em outra. Ou com flags diferentes. Tentar reconfigurar a mesma pasta de build várias vezes normalmente faz com que ela guarde vestígios de configurações antigas, e você não tem certeza do que está realmente ativado.

Se você usa pastas separadas, tem clareza pelo sistema de arquivos:

tasker/
  build-debug/
  build-release/

Até um iniciante que não sabe nada sobre otimizações entende: “São duas builds diferentes”. E se a build release quebra, você não mexe na debug. Isso evita muitos problemas aleatórios.

6. Higiene da pasta de build: estado, exclusão e nomes

A pasta de build é um estado, e é normal apagá‑la

Há uma barreira psicológica: iniciantes têm medo de apagar arquivos porque “e se eu apagar algo importante”. E isso faz sentido: na pasta dos fontes é perigoso apagar sem pensar.

Mas a pasta de build é diferente. Ela foi pensada justamente para que, a qualquer momento, você possa dizer: “A build está estranha. Quero voltar a um estado limpo”, apagar o diretório de build e recriá‑lo.

Por que isso funciona? Porque a pasta de build é uma derivação dos fontes e das configurações. Se os fontes estiverem no lugar, você sempre conseguirá gerar a pasta de build novamente. É como a pasta bin/ ou out/ em outras linguagens: é valiosa como resultado, não como artefato único.

Na prática isso vira uma regra simples de pensamento:

Se você não entende por que a build “está se comportando de forma estranha” e suspeita que o problema seja o estado acumulado,
recriar a pasta de build frequentemente é mais rápido do que tentar consertar manualmente.

Importante: isso não é um “hack”, é uma ferramenta de trabalho legítima. Sistemas de build são complexos. Eles têm caches. Às vezes ajudam, às vezes atrapalham. E out-of-source dá o botão “resetar todo o estado” sem risco de apagar os fontes.

Onde colocar a pasta de build e como nomeá‑la

Ao fazer out-of-source build, a pergunta prática é: “Ok, a pasta é separada — onde ela deve ficar?” Em projetos didáticos é mais simples manter a pasta de build logo ao lado dos fontes, na raiz do projeto: assim é fácil achar e fácil apagar.

Nomes comuns são build/, cmake-build-debug/ (algumas IDEs criam esse padrão automaticamente), build-debug/, build-release/. O importante não é o nome, e sim que seja óbvio e consistente. Ao abrir o projeto depois de um mês, você deve entender na hora: “Ah, aqui estão os fontes, ali estão os diretórios de build”.

Outro ponto prático: a pasta de build normalmente não deve entrar no repositório. Não é só por “costume” — artefatos de build dependem da sua máquina, do compilador, do sistema operacional e das configurações. Duas pessoas que compilam o mesmo projeto geram arquivos diferentes na pasta de build — e isso é esperado. Se você comitar esses arquivos, o repositório vira um campo de batalha.

7. Erros comuns ao usar out-of-source build

Agora vem uma seção que economiza mais tempo que muitos “bons conselhos”. A maioria dos problemas com CMake entre iniciantes não é sobre flags complexas nem “magia do linker”, mas sobre confusão básica de onde você está compilando e qual pasta contém o estado atual da build.

Erro nº 1: compilar no diretório raiz e depois estranhar “de onde vieram esses arquivos”.
Quando você roda a configuração na pasta dos fontes, o CMake cria arquivos de serviço ali. Depois você procura main.cpp e encontra CMakeCache.txt e CMakeFiles/ ao lado. A solução é simples: combine com você mesmo que a raiz do projeto é uma zona limpa e que a build não grava lá.

Erro nº 2: tratar a pasta de build como parte dos fontes e ter medo de apagá‑la.
Se você vê a pasta de build como “coisa frágil, não mexer”, perde a ferramenta mais útil: o reset do estado. Com out-of-source você tem a opção segura de apagar o diretório de build por completo quando algo der errado e reconstruir do zero.

Erro nº 3: usar uma única pasta de build para “tudo” e reaproveitá‑la sempre.
Hoje você compilou com certas configurações, amanhã com outras, depois a IDE mudou o gerador — e a pasta de build acaba guardando vestígios de tudo. Os sintomas são misteriosos: “Mudei um arquivo e não teve efeito” ou “funciona para mim, não para o colega”. É muito melhor isolar cenários de build em pastas separadas.

Erro nº 4: tentar limpar a pasta de build manualmente e parcialmente.
Às vezes você quer remover “aquele arquivo estranho” e torcer para que tudo volte a funcionar. É como tentar consertar uma geladeira sacudindo a porta: às vezes ajuda, mas você não sabe por quê. Se o estado da build está corrompido, o jeito honesto é apagar a pasta inteira. Out-of-source torna isso seguro.

Erro nº 5: acidentalmente adicionar a pasta de build ao repositório e depois lutar com diffs.
Mesmo sozinho, um repositório com artefatos de build vira barulhento: gigabytes de lixo, mudanças inexplicáveis, conflitos. Num projeto normal, diretórios de build são considerados reconstruíveis e mantidos fora do repositório. Quando você aceita essa ideia, o Git e sua sanidade agradecem.