Do Comando Único ao Projeto Real — Construindo com CMake

Fechamos a Fase 7 e abrimos a Fase 8, dedicada ao que transforma código que funciona em software profissional: ferramentas, qualidade e boas práticas. Começamos pelo alicerce de todo projeto C++ real — o sistema de build. Até aqui, cada exemplo foi um arquivo único compilado com uma linha de g++. Isso serviu ao aprendizado, mas está a anos-luz de um projeto de verdade, que tem dezenas de arquivos-fonte, cabeçalhos, dependências externas e configurações diferentes para depuração e produção. Compilar tudo isso à mão, lembrando a ordem e as flags, é insustentável. O CMake é a ferramenta padrão da indústria para descrever como um projeto C++ deve ser construído, de forma portável entre compiladores e sistemas operacionais. Hoje você sai do "um arquivo, uma linha" e dá o primeiro passo no mundo real da construção de software.

O problema que o CMake resolve

Imagine um projeto com um main.cpp, um calculadora.cpp (implementação) e um calculadora.h (interface). Compilá-lo à mão exigiria conhecer todos os arquivos, a ordem, as flags de padrão e otimização, e repetir isso a cada mudança. Multiplique por dezenas de arquivos e você tem um pesadelo de manutenção. Pior: a linha de comando que funciona no seu Linux com g++ não é a mesma no macOS com clang++ ou no Windows com MSVC. O CMake resolve os dois problemas: você descreve o projeto uma vez, de forma abstrata, e o CMake gera os comandos de build corretos para o ambiente de cada um.

O coração de um projeto CMake é um arquivo chamado CMakeLists.txt. Aqui está o mínimo para o projeto de três arquivos acima:

# CMakeLists.txt — descrição do projeto

# Versão mínima do CMake exigida. 3.16+ é seguro para recursos modernos.
cmake_minimum_required(VERSION 3.16)

# Nome do projeto e linguagem.
project(Calculadora LANGUAGES CXX)

# Exige C++20 e proíbe extensões não-padrão do compilador.
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Cria um executável chamado 'calc' a partir destes arquivos-fonte.
# (Cabeçalhos .h não entram aqui; são incluídos pelos .cpp.)
add_executable(calc main.cpp calculadora.cpp)

Este arquivo descreve o projeto: sua versão mínima de CMake, seu nome, o padrão da linguagem (nosso C++20 de sempre), e que há um executável calc feito de dois .cpp. Nenhuma flag de compilador crua, nenhum caminho absoluto — tudo abstrato e portável.

O ciclo de build: configurar e compilar

Com o CMakeLists.txt pronto, construir o projeto tem duas etapas. Primeiro você configura (o CMake lê a descrição e gera os arquivos de build para seu ambiente), depois você compila. A prática recomendada é fazer isso numa pasta separada (build/), para não misturar os arquivos gerados com o código-fonte:

# A partir da raiz do projeto:
cmake -S . -B build          # configura: lê CMakeLists.txt, gera build/ 
cmake --build build          # compila: constrói o executável dentro de build/
./build/calc                 # executa o programa gerado

O -S . diz "o código-fonte está aqui"; o -B build diz "gere os arquivos de build na pasta build". Depois, cmake --build build compila. Essa separação (o out-of-source build) mantém o repositório limpo — a pasta build/ pode ser apagada e regenerada a qualquer momento, e nunca vai para o controle de versão. É um hábito profissional que vale adotar desde já.

Bibliotecas: organizando código em módulos

Projetos reais separam código reutilizável em bibliotecas, não jogam tudo no executável. O CMake torna isso natural: você cria uma biblioteca com add_library e a liga ao executável com target_link_libraries. Suponha que a calculadora vire uma biblioteca reutilizável:

cmake_minimum_required(VERSION 3.16)
project(Calculadora LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Cria uma biblioteca 'mathlib' com a lógica da calculadora.
add_library(mathlib calculadora.cpp)

# Diz onde estão os cabeçalhos da biblioteca (para quem a usar poder incluí-los).
target_include_directories(mathlib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})

# O executável 'calc' usa a biblioteca.
add_executable(calc main.cpp)
target_link_libraries(calc PRIVATE mathlib)   # liga a biblioteca ao executável

Agora mathlib é um módulo independente que o executável calc consome. Essa estrutura — separar lógica reutilizável em bibliotecas e ligá-las aos executáveis — é como projetos C++ reais se organizam. O PUBLIC/PRIVATE controla a propagação das propriedades (quem usa mathlib herda seus diretórios de include, por serem PUBLIC; a ligação de calc a mathlib é PRIVATE, um detalhe interno de calc). Não se prenda a esses modificadores agora; o essencial é a ideia de compor um projeto a partir de bibliotecas e executáveis ligados entre si.

A honestidade sobre o CMake

Prometo transparência, e o CMake merece uma nota franca. Ele é a ferramenta padrão da indústria — onipresente, portável, poderoso — mas tem fama merecida de ter uma sintaxe peculiar e uma curva de aprendizado íngreme; sua própria linguagem de script é idiossincrática e sua documentação histórica confundiu gerações de programadores. A boa notícia é que o "CMake moderno" (a partir da versão 3.x, com a abordagem baseada em targets que usamos acima) é muito mais limpo que o estilo antigo que você encontrará em projetos legados e tutoriais desatualizados. Meu conselho: aprenda o estilo moderno baseado em target_* (como fizemos), ignore os exemplos antigos cheios de variáveis globais, e não tente dominar tudo de uma vez — o subconjunto que vimos hoje já constrói projetos reais. À medida que precisar de mais (dependências externas, testes, instalação), você amplia. O CMake é uma ferramenta que se aprende ao longo da carreira, não numa tarde.

Compilar à mão deixa de funcionar bem antes do que se imagina: basta uma dúzia de arquivos, uma biblioteca externa e a necessidade de compilar no computador de outra pessoa. O CMake descreve o projeto em vez dos comandos, e gera o build concreto de cada ambiente. Duas coisas valem guardar desde o começo: configurar e construir são etapas distintas, e a pasta build/ separada mantém os artefatos fora do que está versionado.

Fontes e leituras recomendadas

• cmake.org/cmake/help/latest: a documentação oficial do CMake; comece pelos tutoriais da própria página, que usam o estilo moderno.
• Craig Scott, Professional CMake: A Practical Guide: o livro de referência sobre CMake moderno, escrito por um mantenedor do projeto.
• "An Introduction to Modern CMake" (cliutils.gitlab.io/modern-cmake): um guia online gratuito e excelente sobre o estilo baseado em targets que adotamos.
• cmake.org/cmake/help/latest/command/add_library.html e add_executable.html: as referências dos comandos centrais desta aula.
• Bjarne Stroustrup, A Tour of C++ (3ª ed.), apêndices sobre organização de projetos: contexto sobre como estruturar código C++ em módulos.

Exercícios

Exercício 1

Crie um projeto com três arquivos: main.cpp (que usa uma função saudacao()), saudacao.cpp (a implementação) e saudacao.h (a declaração). Escreva o CMakeLists.txt que produz um executável a partir deles.

// saudacao.h
#pragma once
#include <string>
std::string saudacao(const std::string& nome);

// saudacao.cpp
#include "saudacao.h"
std::string saudacao(const std::string& nome) {
    return "Olá, " + nome + "!";
}

// main.cpp
#include <iostream>
#include "saudacao.h"
int main() {
    std::cout << saudacao("Mundo") << '\n';
    return 0;
}

# CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(Saudacao LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_executable(app main.cpp saudacao.cpp)

Exercício 2

Explique o que cada uma das duas etapas — cmake -S . -B build e cmake --build build — faz. Por que é boa prática usar uma pasta build/ separada?

Exercício 3

Modifique o projeto do exercício 1 para que a saudacao seja uma biblioteca (add_library) ligada ao executável (target_link_libraries). Explique a vantagem de separar código em bibliotecas.

cmake_minimum_required(VERSION 3.16)
project(Saudacao LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_library(saudacao_lib saudacao.cpp)
target_include_directories(saudacao_lib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})

add_executable(app main.cpp)
target_link_libraries(app PRIVATE saudacao_lib)

Exercício 4

Explique por que os arquivos de cabeçalho (.h) geralmente não são listados em add_executable/add_library, enquanto os .cpp são. O que o target_include_directories faz nesse contexto?

Exercício 5

Discuta por que compilar um projeto grande "à mão" com g++ se torna insustentável, e liste três problemas concretos que o CMake resolve. Dê um exemplo de como o mesmo CMakeLists.txt funciona em ambientes diferentes.