Builds - MCU & FPGA https://mcu.tec.br Microcontroladores & FPGA Thu, 25 Dec 2025 13:18:15 +0000 pt-BR hourly 1 https://wordpress.org/?v=7.0 https://mcu.tec.br/wp-content/uploads/2025/02/Robo-para-o-site-MCU.tec_.br-512x512-1-150x150.png Builds - MCU & FPGA https://mcu.tec.br 32 32 Introdução ao CMake em Projetos STM32 Gerados pelo CubeMX https://mcu.tec.br/linguagem/builds/introducao-ao-cmake-em-projetos-stm32-gerados-pelo-cubemx/?utm_source=rss&utm_medium=rss&utm_campaign=introducao-ao-cmake-em-projetos-stm32-gerados-pelo-cubemx Thu, 25 Dec 2025 13:16:31 +0000 https://mcu.tec.br/?p=1069 Aprenda a usar o CMake de forma profissional em projetos STM32 gerados pelo CubeMX. Este guia completo e didático explica a história do CMake, os problemas que ele resolve, e como aplicá-lo corretamente em sistemas embarcados bare-metal. O artigo aborda em profundidade diretivas como project, add_executable, add_library, target_sources, target_include_directories, target_compile_definitions, target_link_libraries, uso consciente de file(GLOB), integração de BLOBs binários, criação de bibliotecas estáticas reutilizáveis, configuração de perfis de build, uso de CMakePresets.json e separação correta de toolchains via arquivos .cmake. Inclui um exemplo ideal e comentado de CMakeLists.txt para STM32, além de um arquivo de toolchain arm-none-eabi-gcc.cmake, mostrando como gerar .elf, .bin e .hex fora de IDEs proprietárias. Conteúdo técnico, prático e focado em boas práticas de engenharia de firmware.

The post Introdução ao CMake em Projetos STM32 Gerados pelo CubeMX first appeared on MCU & FPGA.

]]> A história do CMake e o problema que ele veio resolver

O CMake surge no início dos anos 2000, criado por Bill Hoffman no contexto do Kitware, com um objetivo muito claro: resolver o problema da portabilidade e da complexidade crescente dos sistemas de build. Até então, projetos em C e C++ dependiam fortemente de Makefiles escritos manualmente, profundamente acoplados ao sistema operacional, ao compilador e até mesmo à estrutura de diretórios da máquina do desenvolvedor. Em projetos pequenos isso era administrável, mas à medida que o software crescia — especialmente em ambientes multiplataforma — o custo de manutenção dos Makefiles se tornava proibitivo.

O problema se agravava em projetos embarcados. Cada microcontrolador exige um conjunto específico de flags de compilação, scripts de linkedição, opções de ABI (Application Binary Interface), suporte a assembly, bibliotecas de runtime reduzidas (newlib-nano, nosys, etc.) e, frequentemente, múltiplos perfis de build (Debug, Release, Profiling). Manter tudo isso sincronizado manualmente em Makefiles diferentes era uma fonte constante de erros sutis, builds não reproduzíveis e dependência excessiva do conhecimento tácito do desenvolvedor.

O CMake nasce justamente como uma ferramenta de meta-build. Ele não compila código diretamente. Em vez disso, descreve o projeto em um nível mais alto, declarativo, e gera os arquivos de build adequados para o ambiente alvo: Makefiles, Ninja, projetos para IDEs como Eclipse, Visual Studio ou Xcode. Essa abordagem separa claramente o que o projeto é de como ele será construído em cada plataforma.

No contexto de sistemas embarcados, essa separação é fundamental. O mesmo projeto pode ser compilado com GCC bare-metal (arm-none-eabi-gcc), Clang, ou até toolchains customizadas fornecidas por fabricantes. O CMake permite encapsular essas diferenças em arquivos de toolchain, mantendo o CMakeLists.txt do projeto limpo, legível e focado na arquitetura do software, e não nos detalhes do compilador.

Por que o CMake se encaixa tão bem com projetos STM32

Projetos STM32 gerados pelo CubeMX possuem uma característica importante: eles não são apenas aplicações, mas sim sistemas completos, compostos por código C, assembly, bibliotecas HAL, CMSIS, drivers específicos do microcontrolador, além de um script de linkedição altamente acoplado ao layout de memória do chip. O CubeMX tradicionalmente gera projetos voltados para IDEs específicas (STM32CubeIDE, Keil, IAR), mas isso cria um forte lock-in da ferramenta.

Ao adotar o CMake como sistema de build, o projeto STM32 passa a ser agnóstico de IDE. Ele pode ser compilado via linha de comando, integrado a pipelines de CI/CD, analisado por ferramentas como clangd, clang-tidy e cppcheck, ou aberto em qualquer editor moderno. Além disso, o CMake facilita a modularização do projeto, permitindo separar claramente o código gerado pelo CubeMX do código de aplicação, das bibliotecas externas e das bibliotecas internas reutilizáveis.

Outro ponto crucial é que o CMake trabalha com o conceito de targets. Em vez de pensar apenas em arquivos .c e .o, o desenvolvedor passa a modelar o sistema em termos de executáveis, bibliotecas estáticas, bibliotecas de interface e dependências explícitas entre elas. Isso se encaixa perfeitamente no mundo embarcado moderno, onde reutilização, isolamento de responsabilidades e controle fino de símbolos e includes são essenciais para manter projetos grandes sustentáveis ao longo do tempo.

CMake como fundação para arquiteturas escaláveis em firmware

Quando usamos CMake corretamente em um projeto STM32, deixamos de ter apenas um “script de build” e passamos a ter uma descrição formal da arquitetura do firmware. Bibliotecas como drivers, middlewares, stacks de comunicação ou camadas de abstração de hardware podem ser modeladas como bibliotecas estáticas independentes. Cada uma define seus próprios includes, defines e flags de compilação, que são propagados automaticamente para quem as consome.

Isso elimina uma classe inteira de problemas comuns em projetos embarcados: defines globais espalhados, includes duplicados, dependências implícitas e flags de compilação inconsistentes entre módulos. Além disso, o CMake facilita a criação de perfis de build (Debug, Release, Coverage, Profiling), algo essencial quando se trabalha com análise temporal, WCET, uso de heap, watermark de pilha e instrumentação de RTOS.

Em resumo, o CMake não é apenas uma alternativa ao Makefile tradicional. Ele é uma camada de engenharia de software aplicada ao processo de build, especialmente poderosa quando combinada com projetos STM32 gerados pelo CubeMX.

Estrutura básica de um projeto CMake para STM32 gerado pelo CubeMX

Ao abrir um projeto STM32 baseado em CMake, a primeira impressão costuma ser de estranhamento para quem vem de Makefiles tradicionais ou do ecossistema fechado de IDEs como o STM32CubeIDE. Isso acontece porque o CMake não descreve comandos de compilação de forma direta, mas sim relações estruturais entre os elementos do projeto. Antes de entender cada diretiva isoladamente, é fundamental compreender a estrutura conceitual que sustenta um projeto CMake bem organizado para firmware.

Em projetos STM32 modernos, especialmente aqueles que nascem a partir do CubeMX, o ponto de entrada é sempre um arquivo chamado CMakeLists.txt localizado na raiz do projeto. Esse arquivo funciona como o manifesto do firmware: ele declara qual é o projeto, quais linguagens são usadas, quais bibliotecas fazem parte do sistema, quais arquivos devem ser compilados e como tudo isso se conecta para gerar o binário final, geralmente um arquivo .elf.

Uma característica importante é que esse CMakeLists.txt de nível superior não deve conter tudo. Em projetos bem estruturados, ele atua como um orquestrador, delegando responsabilidades para outros CMakeLists.txt menores espalhados pela árvore do projeto. É exatamente isso que vemos em projetos gerados ou adaptados a partir do CubeMX, onde o código automático fica isolado em uma subpasta, normalmente algo como cmake/stm32cubemx, enquanto o código da aplicação permanece sob controle direto do desenvolvedor.

Essa separação é essencial. O código gerado pelo CubeMX pode ser regenerado a qualquer momento, enquanto o código da aplicação e a lógica de build precisam permanecer estáveis. O CMake favorece esse modelo ao permitir a inclusão explícita de subdiretórios, tornando claro o limite entre código gerado e código autoral.

A diretiva cmake_minimum_required: controle de compatibilidade e previsibilidade

Toda configuração CMake começa com a diretiva cmake_minimum_required. Embora muitos desenvolvedores a encarem como uma formalidade, ela desempenha um papel crítico em projetos embarcados. Essa diretiva define a versão mínima do CMake necessária para interpretar corretamente o script, garantindo que comportamentos antigos, obsoletos ou inconsistentes não sejam utilizados de forma implícita.

Em firmware, previsibilidade é tudo. Diferenças sutis no comportamento do sistema de build podem resultar em flags omitidas, bibliotecas ligadas em ordem incorreta ou até mesmo em binários que funcionam em Debug, mas falham em Release. Ao exigir explicitamente uma versão mínima, o projeto estabelece uma linha de base clara para todos os desenvolvedores e para sistemas de integração contínua.

Na prática, projetos STM32 modernos costumam exigir versões relativamente recentes do CMake, pois funcionalidades como FetchContent, presets (CMakePresets.json) e melhor suporte a toolchains cruzadas evoluíram bastante nas últimas versões. Definir essa versão logo no início do arquivo evita erros difíceis de rastrear mais adiante e deixa claro que o projeto não foi pensado para ambientes legados.

Além disso, essa diretiva influencia o modo como o CMake interpreta várias outras instruções. Sem ela, o CMake entra em um modo de compatibilidade que pode alterar silenciosamente o comportamento de comandos fundamentais. Em sistemas embarcados, onde cada byte e cada flag importam, esse tipo de ambiguidade é simplesmente inaceitável.

A diretiva project(): identidade formal do firmware

Logo após definir a versão mínima do CMake, encontramos a diretiva project(). Essa é uma das instruções mais importantes de todo o sistema de build, pois é nela que o firmware passa a existir formalmente como um projeto CMake. Ao declarar o projeto, você não está apenas dando um nome simbólico ao binário final, mas também inicializando internamente todo o modelo de build que o CMake utilizará.

Em projetos STM32, o nome do projeto geralmente coincide com o nome do arquivo final .elf, e frequentemente reflete o hardware alvo ou a função principal do firmware. Isso não é apenas uma convenção estética. O nome do projeto passa a ser utilizado implicitamente em diversas outras diretivas, como na criação do executável, na geração de mensagens de log e na organização dos artefatos de build.

Além do nome, a diretiva project() também declara as linguagens utilizadas. Em firmware STM32, isso quase sempre inclui C e Assembly. Ao fazer isso explicitamente, o CMake passa a configurar corretamente compiladores, regras de build e extensões de arquivos para cada linguagem, algo fundamental quando se trabalha com arquivos .s ou .S de startup e rotinas de baixo nível.

Outro ponto relevante é que a chamada a project() marca o momento em que variáveis globais do CMake passam a estar disponíveis de forma consistente. Por isso, boas práticas recomendam que a maior parte das configurações estruturais do projeto aconteça após essa diretiva, garantindo que o ambiente esteja completamente inicializado.

Definição do padrão da linguagem e controle do compilador

Em sistemas embarcados, definir explicitamente o padrão da linguagem não é um detalhe estético, mas um requisito técnico. O comportamento do compilador, a disponibilidade de recursos da linguagem e até a geração de código variam significativamente entre diferentes padrões do C. O CMake resolve essa questão de forma clara e declarativa por meio de variáveis específicas que descrevem qual versão da linguagem o projeto exige, e não apenas qual compilador será usado.

A variável CMAKE_C_STANDARD estabelece o padrão mínimo do C que o projeto aceita. Em projetos STM32 gerados pelo CubeMX, é comum adotar o C11, pois ele oferece um bom equilíbrio entre modernidade e compatibilidade com toolchains bare-metal. Ao definir esse valor, o CMake garante que o compilador seja invocado com as flags corretas para ativar esse padrão, independentemente de qual GCC esteja instalado no sistema.

Complementando isso, CMAKE_C_STANDARD_REQUIRED força o compilador a respeitar exatamente o padrão definido. Sem essa diretiva, o compilador pode silenciosamente aceitar um padrão diferente, mais antigo ou mais permissivo, o que abre espaço para comportamentos inesperados. Em firmware, onde cada compilação precisa ser reprodutível, esse tipo de ambiguidade não é aceitável.

Já a variável CMAKE_C_EXTENSIONS controla se extensões específicas do compilador — como as extensões GNU — podem ser utilizadas. Em projetos STM32, muitas bibliotecas, incluindo partes do HAL e até do CMSIS, dependem de extensões do GCC. Por isso, permitir essas extensões costuma ser uma decisão consciente, e não um efeito colateral. O CMake torna essa decisão explícita, documentando a dependência do projeto em recursos fora do padrão estrito da linguagem.

Esse conjunto de definições cria um contrato claro entre o firmware e o compilador, algo essencial quando o mesmo projeto pode ser compilado em máquinas diferentes, por pessoas diferentes ou em pipelines automatizados.

Tipos de build: Debug, Release e além

Uma das maiores vantagens do CMake em relação a Makefiles artesanais é o tratamento nativo de tipos de build. Em firmware, isso vai muito além de simplesmente ativar ou desativar otimizações. Um build Debug normalmente inclui símbolos de depuração, otimizações mínimas e, muitas vezes, instrumentação adicional para análise de tempo, uso de memória e comportamento do RTOS. Já um build Release prioriza desempenho, tamanho do binário e previsibilidade temporal.

A variável CMAKE_BUILD_TYPE é o mecanismo básico pelo qual o CMake seleciona esse comportamento. Ao definir um valor padrão quando essa variável não está presente, o projeto garante que o build não ocorra em um estado indefinido. Isso é especialmente importante em ambientes embarcados, onde rodar um binário “meio Debug, meio Release” pode gerar resultados enganosos durante testes de campo.

Mais importante do que a existência de Debug e Release é o fato de que o CMake permite estender esse conceito. É comum em projetos STM32 mais maduros existirem perfis adicionais, como builds para análise de WCET, builds com logs detalhados, builds para testes de estresse ou builds voltados exclusivamente para validação de consumo de energia. O sistema de build deixa de ser apenas um meio de gerar um .elf e passa a ser uma ferramenta estratégica de engenharia.

Essa flexibilidade se torna ainda mais poderosa quando combinada com arquivos como CMakePresets.json, que permitem descrever esses perfis de forma padronizada e reutilizável, eliminando a necessidade de longas linhas de comando e reduzindo drasticamente erros humanos.

Ativação explícita das linguagens C e Assembly

Em firmware STM32, o uso de Assembly não é opcional. Arquivos de startup, rotinas de inicialização da pilha, vetores de interrupção e, em alguns casos, otimizações críticas de desempenho exigem suporte explícito a código Assembly. O CMake trata isso de forma direta por meio da diretiva enable_language.

Ao habilitar C e ASM de forma explícita, o projeto informa ao CMake que esses dois tipos de código fazem parte da arquitetura do firmware. Isso permite que o sistema de build configure corretamente as regras de compilação, extensões reconhecidas e até flags específicas para cada linguagem. Ignorar essa etapa pode levar a erros difíceis de diagnosticar, especialmente quando arquivos .s ou .S são tratados incorretamente como texto ou ignorados durante o build.

Outro ponto relevante é que, ao declarar explicitamente as linguagens, o projeto se torna mais claro para ferramentas externas. Editores, analisadores estáticos e sistemas de indexação conseguem entender melhor a natureza do código, o que melhora significativamente a experiência de desenvolvimento em projetos de médio e grande porte.

Criação do firmware com add_executable(): o nascimento do binário .elf

Em projetos embarcados, o executável gerado pelo CMake não é apenas um programa no sentido tradicional, mas sim a imagem completa do firmware, contendo código, dados, vetores de interrupção, tabelas de inicialização e referências explícitas ao layout de memória definido no script de linkedição. No CMake, esse artefato nasce por meio da diretiva add_executable().

Ao chamar add_executable, o projeto declara formalmente a existência de um alvo executável. No contexto STM32, esse alvo representa o firmware que será gravado na flash do microcontrolador. Diferente de ambientes desktop, o executável não será “executado” pelo sistema operacional, mas sim carregado por um programador ou bootloader. Ainda assim, para o CMake, ele é tratado como um executável completo, com regras claras de compilação e linkedição.

Uma característica interessante é que, em projetos bem estruturados, o add_executable normalmente aparece sem listar arquivos fonte diretamente. Isso não é um erro, mas sim uma decisão arquitetural. O alvo é criado vazio e, ao longo do CMakeLists.txt, vai recebendo fontes, includes, defines e bibliotecas por meio de outras diretivas mais específicas. Esse modelo favorece a modularização e evita grandes listas monolíticas de arquivos difíceis de manter.

Essa abordagem se encaixa muito bem com projetos CubeMX, onde o código gerado automaticamente pode ser adicionado ao executável a partir de um subdiretório específico, mantendo o arquivo principal limpo e legível. O executável passa a ser o ponto de convergência de vários módulos independentes, refletindo com clareza a arquitetura do firmware.

Criação de bibliotecas estáticas com add_library()

Se o add_executable representa o firmware final, add_library representa os blocos de construção que compõem esse firmware. Em projetos STM32 profissionais, bibliotecas estáticas são fundamentais para organizar o código, promover reutilização e limitar o acoplamento entre módulos.

Ao criar uma biblioteca estática no CMake, você está definindo um conjunto coeso de funcionalidades que pode ser compilado de forma independente e depois ligado ao firmware principal. Isso é extremamente comum para drivers, camadas de abstração, middlewares e até para o próprio HAL, quando se deseja maior controle sobre o processo de build.

No CMake, bibliotecas estáticas permitem encapsular não apenas arquivos fonte, mas também includes, defines e opções de compilação específicas daquele módulo. Isso significa que um driver pode expor suas dependências de forma explícita, e o executável que o utiliza herda essas informações automaticamente. Esse modelo elimina a necessidade de repetir configurações globais e reduz drasticamente erros de integração.

Em projetos derivados do CubeMX, é comum transformar partes do código gerado em bibliotecas internas, isolando, por exemplo, a inicialização do hardware da lógica da aplicação. O CMake torna esse processo natural, incentivando uma arquitetura mais limpa e sustentável ao longo do tempo.

O papel central de target_sources()

Uma vez criados os alvos — executáveis ou bibliotecas — surge a necessidade de associar arquivos fonte a eles. É aqui que entra a diretiva target_sources. Em vez de listar arquivos diretamente na criação do alvo, o CMake permite adicioná-los de forma incremental e contextualizada.

Essa abordagem é especialmente poderosa em firmware STM32, pois diferentes módulos podem contribuir com arquivos para o mesmo alvo sem que isso gere dependências implícitas ou confusão estrutural. O código gerado pelo CubeMX, por exemplo, pode ser adicionado a partir de um subdiretório específico, enquanto o código da aplicação é adicionado em outro ponto do projeto.

Além disso, target_sources ajuda a documentar a origem dos arquivos. Ao ler o CMakeLists.txt, fica claro quais fontes pertencem a qual módulo e como elas se integram ao firmware final. Isso facilita manutenção, revisão de código e onboarding de novos desenvolvedores.

Outro benefício importante é que essa diretiva respeita o escopo do alvo. Um arquivo fonte adicionado a uma biblioteca não “vaza” automaticamente para outros alvos, o que reforça o isolamento entre módulos e previne dependências acidentais.

Includes e headers: controle preciso com target_include_directories()

Em projetos STM32 tradicionais, especialmente aqueles criados diretamente dentro de IDEs, é muito comum encontrar listas globais de includes, aplicadas indiscriminadamente a todo o projeto. Esse modelo funciona no início, mas rapidamente se torna frágil: headers passam a depender implicitamente de outros headers, conflitos de nomes surgem e o acoplamento entre módulos cresce silenciosamente.

O CMake resolve esse problema ao introduzir um modelo baseado em escopo, e a diretiva target_include_directories() é o coração dessa abordagem. Em vez de dizer “estes diretórios fazem parte do projeto”, você passa a dizer “estes diretórios fazem parte deste alvo”. Essa diferença conceitual muda completamente a forma como o firmware é organizado.

Quando um diretório de include é associado a um alvo específico — seja um executável ou uma biblioteca — apenas aquele alvo e seus consumidores diretos terão acesso a esses headers. Isso permite que cada módulo exponha exatamente o que precisa ser exposto, nada mais. Em firmware STM32, isso é essencial para separar, por exemplo, drivers de hardware, código de aplicação e camadas de abstração.

Outro aspecto importante é o nível de visibilidade: PRIVATE, PUBLIC e INTERFACE. Um include marcado como PRIVATE só é usado internamente pelo alvo. PUBLIC é usado pelo alvo e também propagado para quem o linkar. INTERFACE não é usado pelo próprio alvo, mas apenas pelos consumidores. Essa distinção é extremamente poderosa para firmware, pois permite criar bibliotecas que funcionam como contratos bem definidos entre módulos.

Ao adotar esse modelo, o projeto deixa de depender de “includes mágicos” e passa a ter uma estrutura previsível, rastreável e muito mais fácil de manter ao longo dos anos.

Definições de compilação e macros com target_compile_definitions()

Macros de compilação são inevitáveis em sistemas embarcados. Defines como STM32F4xx, USE_HAL_DRIVER, opções de debug, flags de instrumentação ou seleção de periféricos fazem parte do dia a dia. O problema surge quando essas macros são definidas globalmente, sem controle de escopo.

A diretiva target_compile_definitions() resolve exatamente isso. Assim como acontece com includes, as definições passam a pertencer a um alvo específico. Isso significa que um driver pode declarar suas próprias macros, um middleware pode exigir determinadas configurações, e o executável final herda apenas aquilo que faz sentido para ele.

Em projetos STM32 baseados em CubeMX, isso é particularmente relevante porque o código gerado assume a existência de certos defines. Ao propagar essas definições corretamente para bibliotecas externas ou módulos internos, o CMake garante que todo o código seja compilado sob o mesmo contexto, evitando erros sutis e difíceis de diagnosticar.

Outro ponto importante é que essas macros passam a ser documentadas implicitamente pelo sistema de build. Ao inspecionar o CMakeLists.txt, fica claro quais símbolos existem, por que existem e onde são utilizados. Isso é um ganho enorme em projetos de longa duração ou com múltiplos desenvolvedores.

Organização modular com add_subdirectory()

Uma das maiores forças do CMake em projetos STM32 é a possibilidade de fragmentar o sistema de build em múltiplos arquivos pequenos e coesos. A diretiva add_subdirectory() é o mecanismo que permite isso.

Ao adicionar um subdiretório, o CMake passa a processar o CMakeLists.txt contido naquele diretório como parte do projeto principal. Isso é exatamente o que permite isolar o código gerado pelo CubeMX em uma pasta dedicada, mantendo o arquivo principal enxuto e focado na arquitetura do firmware.

Esse modelo também favorece a criação de bibliotecas internas bem definidas. Cada módulo pode ter seu próprio CMakeLists.txt, declarando fontes, includes, defines e dependências de forma local. O projeto principal apenas conecta esses módulos, sem precisar conhecer seus detalhes internos.

Em firmware STM32 mais complexos, essa organização é o que torna viável a manutenção ao longo do tempo. O build deixa de ser um arquivo monolítico e passa a refletir a estrutura real do software.

Linkedição em firmware STM32 com target_link_libraries()

Diferente de aplicações desktop, a linkedição em sistemas embarcados não é apenas uma etapa final automática do build. Ela define o que realmente entra no firmware, como o código é organizado na memória e até quais partes do código serão eliminadas pelo linker. No CMake, o controle desse processo é feito principalmente por meio da diretiva target_link_libraries().

Ao usar target_link_libraries, você declara explicitamente que um alvo depende de outro. No caso de um firmware STM32, isso normalmente significa ligar o executável principal a bibliotecas estáticas que representam o HAL, CMSIS, drivers, middlewares ou módulos internos do projeto. O ponto central é que o CMake transforma essa declaração em ordem correta de linkedição, algo extremamente sensível em ambientes bare-metal.

Em sistemas embarcados, a ordem das bibliotecas importa. Diferente de ambientes com linker dinâmico, o linker bare-metal resolve símbolos em uma única passagem ou em grupos explícitos. O CMake entende essa necessidade e organiza a linha de link automaticamente com base nas dependências declaradas entre os targets. Isso elimina a prática perigosa de “testar ordens até funcionar”.

Outro aspecto importante é que, ao linkar bibliotecas como targets CMake — e não como arquivos .a soltos — o sistema de build passa a conhecer não apenas o binário da biblioteca, mas também seus includes, defines e opções de compilação. Isso cria um encadeamento coerente de dependências, reduzindo drasticamente inconsistências entre módulos.

Bibliotecas estáticas, descarte de código e otimizações agressivas

Em firmware STM32, quase sempre se trabalha com linkedição com garbage collection de seções (--gc-sections). Isso significa que qualquer função ou dado não referenciado será eliminado do binário final. Esse comportamento é desejável para reduzir tamanho, mas exige disciplina arquitetural.

Quando uma biblioteca estática é linkada ao firmware, apenas as partes efetivamente utilizadas entram no .elf. Porém, se a ordem de link estiver errada ou se símbolos forem referenciados apenas indiretamente (por exemplo, via ponteiros de função), o linker pode descartar código essencial. O uso correto de target_link_libraries ajuda a minimizar esse risco, pois o CMake mantém a relação explícita entre quem fornece e quem consome símbolos.

Além disso, o uso de bibliotecas bem definidas permite aplicar opções de compilação diferentes para cada módulo. Drivers críticos podem ser compilados com otimizações específicas, enquanto código de diagnóstico pode ser compilado de forma mais conservadora. O CMake torna esse tipo de ajuste local e controlável, algo praticamente inviável com Makefiles globais.

Diretórios de bibliotecas e o papel de target_link_directories()

Embora o uso de target_link_directories() exista, em projetos STM32 bem estruturados ele deve ser usado com cautela. Essa diretiva adiciona caminhos de busca para bibliotecas durante a linkedição, mas não cria dependências explícitas entre targets. Por isso, ela é considerada uma solução de menor nível.

Em firmware moderno com CMake, a prática recomendada é quase sempre trabalhar com targets reais, criados via add_library(), e ligá-los diretamente ao executável. Isso torna o build mais robusto, mais legível e menos dependente de detalhes implícitos do ambiente.

Ainda assim, existem cenários legítimos para target_link_directories, como a integração com bibliotecas pré-compiladas fornecidas por fabricantes ou com blobs binários. Nesses casos, o CMake permite isolar esse comportamento em pontos bem definidos do projeto, evitando que ele se espalhe de forma descontrolada.

O script de linkedição e sua relação com o CMake

Em projetos STM32, o script de linkedição (.ld) é tão importante quanto o código-fonte. Ele define o mapa de memória do microcontrolador, separa flash, RAM, stack, heap e regiões especiais. O CMake não substitui esse script, mas orquestra seu uso.

Ao configurar corretamente as flags de linkedição no CMake, o script .ld passa a fazer parte formal do processo de build. Isso significa que diferentes perfis de build podem usar scripts diferentes, algo extremamente útil para cenários como bootloaders, aplicações dual-bank ou firmware com atualização segura.

Mais uma vez, o CMake atua como um integrador arquitetural, garantindo que compilador, linker e layout de memória trabalhem de forma coerente.

Coleções de arquivos e BLOBs com file(GLOB …)

O CMake oferece a diretiva file(GLOB …) como uma forma de criar automaticamente listas de arquivos a partir de padrões, algo semelhante ao uso de curingas no shell. Em projetos embarcados, essa funcionalidade costuma gerar debates acalorados, pois envolve um equilíbrio delicado entre conveniência e previsibilidade.

Quando usamos file(GLOB), o CMake percorre um diretório e coleta todos os arquivos que correspondem a um determinado padrão, como todos os .c ou .h. Isso permite reduzir listas extensas e repetitivas de arquivos, especialmente em módulos com grande quantidade de fontes homogêneas, como drivers ou middlewares.

Em projetos STM32 derivados do CubeMX, esse mecanismo pode ser útil para lidar com conjuntos de arquivos que seguem uma estrutura estável, como diretórios de drivers ou bibliotecas externas que não sofrem alterações frequentes. Nesses casos, o GLOB atua como uma forma de declaração implícita de intenção: todo arquivo daquele tipo naquele diretório faz parte do módulo.

No entanto, existe um ponto crítico: o CMake não reavalia automaticamente os GLOBs quando novos arquivos são adicionados. Isso significa que, se um desenvolvedor cria um novo arquivo .c, ele pode não ser incluído no build até que o CMake seja reconfigurado. Em firmware, onde builds automatizados e reprodutibilidade são essenciais, esse comportamento precisa ser compreendido e controlado.

Por isso, a recomendação prática é clara: usar file(GLOB) apenas em diretórios cujo conteúdo é considerado estável, ou em bibliotecas externas que não fazem parte do ciclo de desenvolvimento diário. Para o código principal da aplicação, listas explícitas de arquivos continuam sendo a opção mais segura e transparente.

BLOBs binários: quando o código não é tudo

Em projetos STM32 reais, nem tudo é código-fonte. É comum lidar com BLOBs binários, como tabelas de fontes, imagens, firmware de coprocesso, certificados, ou até microcódigos proprietários fornecidos por terceiros. Integrar esses artefatos ao firmware exige cuidado, e o CMake oferece ferramentas adequadas para isso.

Uma abordagem comum é tratar esses BLOBs como arquivos de entrada do processo de build, convertendo-os em objetos ou seções específicas que serão linkadas ao firmware. O CMake permite gerenciar esses arquivos como fontes do alvo, mesmo que não sejam compilados no sentido tradicional.

O ponto central aqui é que o CMake não faz distinção conceitual entre “código” e “dados”. Ele trabalha com artefatos que participam do processo de geração do binário final. Isso torna possível incorporar recursos binários ao firmware de forma controlada, documentada e reproduzível.

Quando combinado com scripts de conversão e regras customizadas, o CMake se torna uma ferramenta poderosa para integrar dados externos ao firmware STM32, sem recorrer a soluções ad hoc ou etapas manuais frágeis.

Perfis de build e CMakePresets.json

À medida que projetos STM32 crescem, o simples uso de CMAKE_BUILD_TYPE passa a não ser suficiente. Diferentes desenvolvedores, máquinas e pipelines precisam gerar builds consistentes sem depender de longas linhas de comando. É aqui que entram os presets do CMake.

O arquivo CMakePresets.json permite definir perfis de configuração e build de forma declarativa. Em vez de memorizar comandos, o desenvolvedor escolhe um preset, e o CMake aplica automaticamente gerador, diretórios de build, toolchain e variáveis de cache. Isso reduz drasticamente erros humanos e melhora a experiência de uso.

Em projetos STM32, presets são especialmente úteis para encapsular diferentes toolchains, placas-alvo ou modos de operação. Um mesmo projeto pode gerar firmware para múltiplas variantes de hardware sem que isso se torne um pesadelo de manutenção.

Além disso, presets se integram muito bem com editores modernos e ferramentas de automação, tornando o fluxo de desenvolvimento mais profissional e previsível.

Toolchains cruzadas no CMake: separando o “como compilar” do “que compilar”

Em sistemas embarcados, o compilador não roda no mesmo ambiente do software gerado. Compilamos no host (Linux, Windows ou macOS) para executar em um microcontrolador ARM Cortex-M. Esse modelo exige uma toolchain cruzada, normalmente baseada no arm-none-eabi-gcc. O CMake trata essa realidade de forma elegante ao separar completamente o conceito de projeto do conceito de toolchain.

No CMake, a toolchain não deve ser definida dentro do CMakeLists.txt principal. Em vez disso, ela é descrita em um arquivo .cmake dedicado, passado ao CMake no momento da configuração. Essa decisão arquitetural é extremamente importante, pois evita que o projeto fique acoplado a um compilador específico ou a caminhos absolutos do sistema.

Um arquivo de toolchain define coisas como:

  • qual compilador C e ASM será usado
  • qual linker será invocado
  • quais ferramentas auxiliares (objcopy, size, objdump) fazem parte do fluxo
  • quais flags são obrigatórias para aquela arquitetura

No contexto STM32, esse arquivo encapsula todo o conhecimento sobre a plataforma Cortex-M, deixando o restante do projeto livre para se concentrar na arquitetura do firmware, e não em detalhes do compilador.

Arquivos de toolchain para STM32 e CubeIDE

Quando usamos o GCC fornecido pelo STM32CubeIDE, a toolchain já existe, mas normalmente está escondida dentro da IDE. Ao trabalhar com CMake, precisamos tornar isso explícito. É exatamente para isso que surgem arquivos como cubeide-gcc.cmake.

Esse tipo de arquivo informa ao CMake onde encontrar o compilador arm-none-eabi-gcc, qual prefixo usar, como tratar o assembler e quais ferramentas adicionais fazem parte do toolchain. Além disso, ele define que o sistema alvo não é um sistema operacional tradicional, mas sim um ambiente bare-metal.

Essa distinção é crucial. Ao informar ao CMake que o sistema alvo não possui libc padrão, filesystem ou runtime POSIX, evitamos que ele tente realizar testes de compilação ou linkedição incompatíveis com microcontroladores. O build passa a ser previsível e alinhado com a realidade do hardware.

Outro benefício direto é que o mesmo projeto pode ser compilado com toolchains diferentes apenas trocando o arquivo de toolchain, sem tocar em uma única linha do CMakeLists.txt principal. Isso é extremamente valioso em ambientes profissionais, onde certificações, auditorias ou requisitos de longo prazo exigem controle fino sobre a ferramenta de compilação.

Integração da toolchain com presets e automação

Quando combinamos arquivos de toolchain com CMakePresets.json, o fluxo de build se torna ainda mais robusto. O preset passa a declarar explicitamente qual toolchain deve ser usada, qual gerador será adotado e onde os artefatos de build serão gerados.

Isso elimina a dependência de documentação informal do tipo “compile assim no seu computador” e transforma o processo de build em algo reproduzível por definição. Qualquer desenvolvedor, ou mesmo um sistema de integração contínua, consegue gerar exatamente o mesmo firmware a partir do mesmo código-fonte.

Em projetos STM32 maiores, é comum ter presets separados para diferentes placas, diferentes microcontroladores ou diferentes perfis de memória. O CMake lida com isso de forma natural, sem duplicação de código e sem gambiarras.

Arquivos de apoio: includes, perfis e configuração externa

À medida que o projeto cresce, surge a necessidade de arquivos auxiliares para organizar o build. Em vez de concentrar tudo no CMakeLists.txt principal, o CMake incentiva a criação de arquivos .cmake especializados: um para toolchain, outro para configuração de RTOS, outro para opções de análise, outro para perfis de instrumentação.

Essa abordagem se encaixa perfeitamente com firmware STM32 moderno, onde diferentes builds podem habilitar logs, medições de tempo, análise de stack ou até funcionalidades experimentais. Cada uma dessas variações pode ser descrita de forma limpa e modular, sem poluir a lógica central do projeto.

O resultado final é um sistema de build que deixa de ser um obstáculo e passa a ser um ativo técnico do projeto.

Fluxo completo de build: do CubeMX ao firmware final

Uma vez compreendidos os conceitos fundamentais do CMake, o fluxo de trabalho em um projeto STM32 torna-se claro, previsível e altamente profissional. O ponto de partida continua sendo o STM32CubeMX, responsável por gerar o código de inicialização, HAL, CMSIS e o script de linkedição. A diferença é que, em vez de amarrar o projeto a uma IDE específica, o CubeMX passa a ser apenas um gerador de código, e não o dono do processo de build.

Após gerar ou atualizar o código, o projeto é estruturado de forma que esse conteúdo fique isolado em um subdiretório, normalmente tratado como um módulo independente. O CMakeLists.txt principal atua como o orquestrador, conectando esse código gerado à aplicação, às bibliotecas internas e às dependências externas. Essa separação garante que futuras regenerações do CubeMX não quebrem a arquitetura do projeto.

A etapa seguinte é a configuração do build. Aqui, o CMake lê o CMakeLists.txt, o arquivo de toolchain e, quando presentes, os presets. Esse momento não gera binários; ele apenas constrói o modelo interno do projeto. É nesse ponto que erros de configuração, caminhos incorretos ou inconsistências arquiteturais aparecem — e é exatamente onde eles devem aparecer.

Com a configuração concluída, o processo de compilação e linkedição passa a ser mecânico. O CMake invoca o compilador correto, aplica as flags definidas, executa o linker com o script apropriado e gera o arquivo .elf, que representa o firmware completo. A partir dele, ferramentas auxiliares convertem o binário para .bin ou .hex, prontos para gravação no microcontrolador.

Esse fluxo é repetível, automatizável e independente de IDE, o que representa um salto de maturidade em relação a projetos embarcados tradicionais.

Geração de bibliotecas estáticas reutilizáveis

Um dos maiores ganhos ao adotar CMake em projetos STM32 é a facilidade de criar e reutilizar bibliotecas estáticas. Drivers, middlewares, camadas de abstração e até subsistemas inteiros podem ser encapsulados em bibliotecas independentes, com seus próprios includes, defines e opções de compilação.

Essas bibliotecas deixam de ser “copiadas e coladas” entre projetos e passam a ser componentes versionáveis, facilmente integrados por meio de add_subdirectory() ou mecanismos como FetchContent. O CMake garante que cada biblioteca seja compilada no contexto correto e ligada de forma consistente ao firmware final.

Esse modelo é essencial para quem mantém múltiplos projetos STM32 ou deseja construir uma base técnica sólida ao longo do tempo. O build passa a refletir a arquitetura do software, e não apenas uma sequência de comandos.

Erros comuns e armadilhas em STM32 + CMake

Apesar de poderoso, o CMake não perdoa descuidos conceituais. Um erro frequente é tratar o CMakeLists.txt como um Makefile disfarçado, concentrando tudo em um único arquivo, com variáveis globais e pouca modularização. Isso anula grande parte dos benefícios do sistema.

Outro problema recorrente é misturar configurações de toolchain com lógica do projeto. Sempre que o CMakeLists.txt começa a conter caminhos absolutos para compiladores ou flags específicas de uma máquina, o projeto perde portabilidade imediatamente. A separação entre toolchain e projeto é inegociável em ambientes profissionais.

O uso indiscriminado de file(GLOB) também merece atenção. Embora conveniente, ele pode comprometer a reprodutibilidade do build se usado sem critério. Em firmware, previsibilidade sempre deve pesar mais do que comodidade.

Por fim, a falta de entendimento sobre escopos — PRIVATE, PUBLIC e INTERFACE — costuma gerar projetos frágeis, cheios de dependências implícitas. O CMake oferece as ferramentas para evitar isso, mas cabe ao engenheiro usá-las corretamente.

Exemplo ideal de CMakeLists.txt para STM32 (CubeMX) + arquivo .cmake de toolchain

Abaixo vai um exemplo de referência (um “padrão ouro” pragmático) para projetos STM32 gerados pelo CubeMX. Ele aplica todas as diretivas que discutimos e deixa claro, por comentários, por que cada parte existe. Em seguida, incluo um arquivo .cmake de toolchain para arm-none-eabi-gcc (modelo compatível com GCC do CubeIDE ou GNU Arm Embedded).

Observação importante: este exemplo assume uma árvore típica:

  • Core/ e Drivers/ vindos do CubeMX
  • startup/ com startup assembly
  • linker/ com o .ld
  • app/ para seu código autoral
  • cmake/ para toolchain e helpers

CMakeLists.txt (raiz do projeto)

# ============================================================
#  CMakeLists.txt - Projeto STM32 (CubeMX) com arquitetura limpa
# ============================================================

# 1) Garante previsibilidade de comportamento do CMake.
cmake_minimum_required(VERSION 3.22)

# 2) Declara formalmente o projeto e as linguagens.
#    Em STM32 quase sempre é C + ASM (startup).
project(stm32_firmware
  VERSION 1.0.0
  LANGUAGES C ASM
)

# 3) Controle do padrão de linguagem (contrato explícito com o compilador).
set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
# Em STM32, frequentemente extensões GNU são úteis (HAL/CMSIS às vezes dependem).
set(CMAKE_C_EXTENSIONS ON)

# 4) Define um build type padrão quando o gerador é single-config (Makefiles/Ninja).
#    Em multi-config (ex.: Visual Studio), isso é ignorado.
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
  set(CMAKE_BUILD_TYPE Debug CACHE STRING "Build type" FORCE)
endif()

# 5) Diretórios principais do projeto
set(APP_DIR       ${CMAKE_SOURCE_DIR}/app)
set(CORE_DIR      ${CMAKE_SOURCE_DIR}/Core)
set(DRIVERS_DIR   ${CMAKE_SOURCE_DIR}/Drivers)
set(STARTUP_DIR   ${CMAKE_SOURCE_DIR}/startup)
set(LINKER_DIR    ${CMAKE_SOURCE_DIR}/linker)

# 6) Script de linker (ajuste para o .ld do seu MCU)
set(LINKER_SCRIPT ${LINKER_DIR}/STM32xxxx_FLASH.ld)

# ------------------------------------------------------------
#  BLOBS / Coleções de arquivos (file(GLOB))
#  Use com critério: recomendado para diretórios estáveis (ex.: Drivers).
#  Para app/ prefira listas explícitas (reprodutibilidade).
# ------------------------------------------------------------
file(GLOB HAL_SOURCES
  ${DRIVERS_DIR}/STM32*/Src/*.c
  ${DRIVERS_DIR}/CMSIS/Device/ST/*/Source/Templates/*.c
)

# Exemplo de “BLOB”: um binário que você quer embutir no firmware
# (pode ser fonte, lookup table, certificado, etc.)
set(BLOB_BIN ${CMAKE_SOURCE_DIR}/assets/blob.bin)

# ------------------------------------------------------------
#  7) Biblioteca estática para HAL/CMSIS (reutilizável)
# ------------------------------------------------------------
add_library(stm32_hal STATIC)

# Adiciona fontes do HAL/CMSIS (coleção via GLOB; diretório estável)
target_sources(stm32_hal PRIVATE
  ${HAL_SOURCES}
  # Se você tem system_stm32xxxx.c gerado pelo CubeMX, inclua aqui.
  ${CORE_DIR}/Src/system_stm32xxxx.c
)

# Includes do HAL/CMSIS
target_include_directories(stm32_hal PUBLIC
  ${CORE_DIR}/Inc
  ${DRIVERS_DIR}/CMSIS/Include
  ${DRIVERS_DIR}/CMSIS/Device/ST/STM32xxxx/Include
  ${DRIVERS_DIR}/STM32xxxx_HAL_Driver/Inc
)

# Defines exigidos pelo CubeMX/HAL (escopo bem definido)
target_compile_definitions(stm32_hal PUBLIC
  USE_HAL_DRIVER
  STM32xxxx
)

# Flags específicas por target (ex.: warnings do HAL)
# (Você pode ajustar e mover para um helper .cmake se quiser.)
target_compile_options(stm32_hal PRIVATE
  -Wall -Wextra
)

# ------------------------------------------------------------
#  8) Biblioteca estática para sua camada de aplicação (opcional, mas ideal)
# ------------------------------------------------------------
add_library(app_lib STATIC)

# Para o código autoral, prefira listar explicitamente as fontes:
target_sources(app_lib PRIVATE
  ${APP_DIR}/src/app_main.c
  ${APP_DIR}/src/app_tasks.c
  ${APP_DIR}/src/app_drivers.c
)

target_include_directories(app_lib PUBLIC
  ${APP_DIR}/include
)

target_compile_definitions(app_lib PUBLIC
  APP_VERSION=\"${PROJECT_VERSION}\"
)

# Dependência explícita: app usa HAL
target_link_libraries(app_lib PUBLIC stm32_hal)

# ------------------------------------------------------------
#  9) Firmware final (ELF)
# ------------------------------------------------------------
add_executable(${PROJECT_NAME}.elf)

# Startup (ASM) e fontes CubeMX “Core”
target_sources(${PROJECT_NAME}.elf PRIVATE
  ${STARTUP_DIR}/startup_stm32xxxx.s
  ${CORE_DIR}/Src/main.c
  ${CORE_DIR}/Src/stm32xxxx_it.c
  ${CORE_DIR}/Src/stm32xxxx_hal_msp.c
  ${CORE_DIR}/Src/syscalls.c
  ${CORE_DIR}/Src/sysmem.c
)

# Inclui o BLOB no build (como dependência para empacotar/gerar header, se necessário)
# Aqui mostramos como gerar um .o a partir de .bin (técnica comum).
# Isso requer objcopy da toolchain.
set(BLOB_OBJ ${CMAKE_BINARY_DIR}/blob.o)

add_custom_command(
  OUTPUT ${BLOB_OBJ}
  COMMAND ${CMAKE_OBJCOPY} -I binary -O elf32-littlearm -B arm ${BLOB_BIN} ${BLOB_OBJ}
  DEPENDS ${BLOB_BIN}
  COMMENT "Convertendo BLOB binário em objeto linkável: blob.o"
)

# Adiciona o blob.o ao firmware
target_sources(${PROJECT_NAME}.elf PRIVATE ${BLOB_OBJ})

# Includes do firmware (o executável também pode precisar de headers específicos)
target_include_directories(${PROJECT_NAME}.elf PRIVATE
  ${CORE_DIR}/Inc
  ${APP_DIR}/include
)

# Defines do firmware (ex.: debug, features)
target_compile_definitions(${PROJECT_NAME}.elf PRIVATE
  # Exemplo: liga logs em Debug
  $<$<CONFIG:Debug>:APP_LOG_ENABLE=1>
)

# Linka bibliotecas internas (ordem e dependências ficam claras)
target_link_libraries(${PROJECT_NAME}.elf PRIVATE
  app_lib
  stm32_hal
)

# 10) Flags de link: script .ld, map, gc-sections
target_link_options(${PROJECT_NAME}.elf PRIVATE
  -T${LINKER_SCRIPT}
  -Wl,-Map=${PROJECT_NAME}.map
  -Wl,--gc-sections
  -Wl,--print-memory-usage
)

# (Opcional) Se você precisa apontar diretórios extras de bibliotecas pré-compiladas:
# Use com cautela. Prefira targets CMake quando possível.
# target_link_directories(${PROJECT_NAME}.elf PRIVATE ${CMAKE_SOURCE_DIR}/third_party/lib)

# ------------------------------------------------------------
#  11) Geração de .bin e .hex a partir do .elf
# ------------------------------------------------------------
add_custom_command(TARGET ${PROJECT_NAME}.elf POST_BUILD
  COMMAND ${CMAKE_OBJCOPY} -O ihex   $<TARGET_FILE:${PROJECT_NAME}.elf> ${PROJECT_NAME}.hex
  COMMAND ${CMAKE_OBJCOPY} -O binary $<TARGET_FILE:${PROJECT_NAME}.elf> ${PROJECT_NAME}.bin
  COMMAND ${CMAKE_SIZE} $<TARGET_FILE:${PROJECT_NAME}.elf>
  COMMENT "Gerando artefatos: .hex, .bin e exibindo size"
)

Arquivo de toolchain: cmake/toolchains/arm-none-eabi-gcc.cmake

# ============================================================
#  arm-none-eabi-gcc.cmake - Toolchain STM32 (GCC bare-metal)
#  Use com: cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=...
# ============================================================

# Diz ao CMake que estamos compilando para um sistema "genérico" (bare-metal).
set(CMAKE_SYSTEM_NAME Generic)
set(CMAKE_SYSTEM_PROCESSOR arm)

# Evita que o CMake tente rodar executáveis gerados (não rodam no host).
set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)

# Prefixo padrão da toolchain GNU Arm Embedded / CubeIDE
set(TOOLCHAIN_PREFIX arm-none-eabi)

# Permite sobrescrever via ambiente, útil em CI:
# export ARM_GCC_PATH=/caminho/para/bin
if(DEFINED ENV{ARM_GCC_PATH})
  set(ARM_GCC_BIN "$ENV{ARM_GCC_PATH}")
else()
  set(ARM_GCC_BIN "") # usa PATH
endif()

# Compiladores
set(CMAKE_C_COMPILER   ${ARM_GCC_BIN}${TOOLCHAIN_PREFIX}-gcc)
set(CMAKE_ASM_COMPILER ${ARM_GCC_BIN}${TOOLCHAIN_PREFIX}-gcc)

# Ferramentas auxiliares (usadas para .bin/.hex e size)
set(CMAKE_OBJCOPY ${ARM_GCC_BIN}${TOOLCHAIN_PREFIX}-objcopy CACHE FILEPATH "")
set(CMAKE_SIZE    ${ARM_GCC_BIN}${TOOLCHAIN_PREFIX}-size    CACHE FILEPATH "")

# Flags de arquitetura (AJUSTE conforme seu MCU: cortex-m4/m7/m33 etc.)
set(ARCH_FLAGS "-mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard")

# Flags comuns
set(COMMON_FLAGS
  "${ARCH_FLAGS} -ffunction-sections -fdata-sections -fno-common"
)

# Debug vs Release pode ser refinado no projeto ou via presets
set(CMAKE_C_FLAGS_INIT "${COMMON_FLAGS}")
set(CMAKE_ASM_FLAGS_INIT "${COMMON_FLAGS}")

# Flags típicas de link em bare-metal (você complementa no target_link_options)
set(CMAKE_EXE_LINKER_FLAGS_INIT
  "${ARCH_FLAGS} -Wl,--gc-sections"
)

# (Opcional) Se você usa newlib-nano e nosys
# set(CMAKE_EXE_LINKER_FLAGS_INIT
#   "${CMAKE_EXE_LINKER_FLAGS_INIT} -specs=nano.specs -specs=nosys.specs"
# )

CMake como ferramenta de engenharia, não apenas de build

Adotar CMake em projetos STM32 não é apenas uma escolha técnica; é uma decisão de engenharia de software. Ele transforma o processo de build em algo declarativo, previsível e alinhado com boas práticas modernas, aproximando o desenvolvimento embarcado do rigor encontrado em sistemas de maior escala.

Quando bem utilizado, o CMake deixa de ser um obstáculo e passa a ser um mapa formal da arquitetura do firmware. Ele documenta dependências, explicita decisões técnicas e reduz drasticamente o custo de manutenção ao longo do tempo.

Para projetos STM32 gerados pelo CubeMX, essa combinação representa o melhor dos dois mundos: a produtividade do gerador de código da ST e a flexibilidade de um sistema de build profissional, independente de IDEs proprietárias.

The post Introdução ao CMake em Projetos STM32 Gerados pelo CubeMX first appeared on MCU & FPGA.

]]> 1069 Como Estruturar um Projeto Profissional com CMake para o RP2040: Guia Didático Passo a Passo https://mcu.tec.br/linguagem/builds/como-estruturar-um-projeto-profissional-com-cmake-para-o-rp2040-guia-didatico-passo-a-passo/?utm_source=rss&utm_medium=rss&utm_campaign=como-estruturar-um-projeto-profissional-com-cmake-para-o-rp2040-guia-didatico-passo-a-passo Fri, 01 Aug 2025 01:06:42 +0000 https://mcu.tec.br/?p=635 Aprenda a estruturar corretamente um projeto para o microcontrolador RP2040 utilizando CMake. Este guia didático passo a passo explica cada linha do CMakeLists.txt, desde variáveis de ambiente até a geração do firmware .uf2, com foco em boas práticas e clareza para iniciantes.

The post Como Estruturar um Projeto Profissional com CMake para o RP2040: Guia Didático Passo a Passo first appeared on MCU & FPGA.

]]> No universo do desenvolvimento embarcado, a jornada do iniciante pode parecer repleta de barreiras invisíveis. Uma das mais frequentes – e subestimadas – está na estruturação correta do projeto, especialmente quando se trata de plataformas modernas como o RP2040, o microcontrolador da Raspberry Pi Foundation. Antes mesmo de escrever a primeira linha de código C, é essencial compreender como preparar o ambiente de compilação, como organizar os arquivos e como garantir que tudo esteja pronto para transformar ideias em firmware funcional.

Neste contexto, o sistema de build CMake se torna uma ferramenta central. Apesar de sua aparência intimidadora para quem está começando, o CMake é uma ponte poderosa entre o código-fonte e o binário que rodará no seu dispositivo. Ele permite organizar dependências, configurar variáveis, compilar múltiplos arquivos e até mesmo lidar com diferentes toolchains de forma automatizada. E quando combinamos o CMake com o ecossistema do RP2040, especialmente com o Pico SDK, temos um ambiente robusto, escalável e flexível — desde projetos educacionais até aplicações industriais.

Por isso, este artigo tem como objetivo guiar o leitor iniciante passo a passo pela análise de um projeto real baseado no RP2040, explicando detalhadamente cada trecho do arquivo CMakeLists.txt e os scripts auxiliares que compõem a infraestrutura de build. Vamos abordar o papel de cada linha, o porquê das decisões adotadas, e quais boas práticas estão sendo aplicadas — além de sugerir melhorias e comparações com abordagens de outras plataformas.

Este não é apenas um guia técnico: é também um convite à compreensão. Ao final desta leitura, você não apenas será capaz de compilar um projeto com confiança, mas também entenderá por que cada etapa é importante. Assim, poderá adaptar seus projetos futuros com segurança e domínio técnico, explorando todo o potencial do RP2040.

Prepare seu editor de texto e acompanhe cada seção com atenção — pois cada linha que vamos explorar é um pequeno degrau em direção à maestria no desenvolvimento embarcado moderno.

Para este artigo foi usado os seguintes arquivos CMakeLists.txt:

1. Configuração Inicial do CMake: Definindo Versão e Padrões do Projeto

Logo no início do arquivo CMakeLists.txt, temos um trecho essencial para garantir a compatibilidade e padronização do ambiente de compilação. Veja abaixo:

cmake_minimum_required(VERSION 3.13)

set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

Explicação Didática

  1. cmake_minimum_required(VERSION 3.13)
    Esta linha define a versão mínima do CMake exigida para processar corretamente este projeto. O valor 3.13 é uma escolha segura para projetos com RP2040, pois é compatível com as versões mais estáveis do SDK da Raspberry Pi e da extensão para VSCode. Se o desenvolvedor tentar compilar o projeto com uma versão mais antiga do CMake, ele receberá uma mensagem de erro clara, evitando comportamento indefinido ou suporte incompleto a recursos.
  2. set(CMAKE_C_STANDARD 11)
    Define que o código C será compilado segundo o padrão C11, uma versão estável e moderna da linguagem C, que inclui melhorias importantes como atomics, static assertions e melhor suporte a multithreading.
  3. set(CMAKE_CXX_STANDARD 17)
    Determina que, caso o projeto inclua arquivos em C++, eles devem seguir o padrão C++17. Este padrão oferece recursos como structured bindings, if constexpr, e std::optional, que podem ser úteis em aplicações mais complexas.
  4. set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
    Esta opção gera o arquivo compile_commands.json, que descreve os comandos de compilação de cada fonte no projeto. Ele é extremamente útil para ferramentas externas como servidores de linguagem (LSPs), linters e analisadores estáticos, como o clangd.

Análise Crítica

  • A escolha de C11 e C++17 é apropriada: garante modernidade sem sacrificar a compatibilidade com a maioria dos toolchains usados no mundo embarcado.
  • A inclusão de CMAKE_EXPORT_COMPILE_COMMANDS mostra preocupação com a qualidade do desenvolvimento, pois favorece a integração com IDEs modernas e ferramentas de verificação de código.
  • Poderia ser interessante tornar os padrões configuráveis via variável de cache (CACHE STRING), permitindo ao usuário customizar sem alterar diretamente o CMakeLists.txt.

Observações Didáticas

  • 🔰 Para iniciantes: Pense nesta seção como o “acordo inicial” entre você e o compilador. Aqui você diz: “vamos trabalhar com a linguagem C moderna, C++ moderno e quero um ambiente que me ajude a detectar erros logo no começo”.
  • 🛠 Boas práticas: Sempre explicite o padrão da linguagem em projetos embarcados. Evita surpresas e garante consistência entre diferentes ambientes de build.
  • 🧠 Dica extra: O compile_commands.json pode ser usado por ferramentas como o clang-tidy ou cppcheck para inspeções profundas do seu código.

2. Configuração da Extensão VSCode e Inclusão do SDK

Após definir os padrões iniciais de compilação, o projeto introduz uma etapa importante para integração com o ambiente de desenvolvimento e o SDK do RP2040. Veja o trecho a seguir:

# == DO NOT EDIT THE FOLLOWING LINES for the Raspberry Pi Pico VS Code Extension to work ==
if(WIN32)
    set(USERHOME $ENV{USERPROFILE})
else()
    set(USERHOME $ENV{HOME})
endif()
set(sdkVersion 2.1.1)
set(toolchainVersion 14_2_Rel1)
set(picotoolVersion 2.1.1)
set(picoVscode ${USERHOME}/.pico-sdk/cmake/pico-vscode.cmake)
if (EXISTS ${picoVscode})
    include(${picoVscode})
endif()
# ====================================================================================

Explicação Didática

  1. Bloco condicional if(WIN32)…
    Aqui é verificado se o sistema operacional é Windows (WIN32). Se for, define a variável USERHOME como o caminho da variável de ambiente USERPROFILE. Caso contrário (Linux/macOS), usa HOME.
    Isso garante portabilidade do projeto entre sistemas operacionais, o que é essencial para ambientes colaborativos e didáticos.
  2. set(sdkVersion ...), toolchainVersion ..., picotoolVersion ...)
    Essas linhas servem como metadados informativos que descrevem as versões usadas no ambiente de desenvolvimento. Embora não sejam diretamente utilizadas pelo CMake nesta etapa, são úteis para documentação, scripts externos ou para controle de consistência do ambiente de build.
  3. set(picoVscode ...) e include(...)
    Essa etapa tenta localizar o arquivo pico-vscode.cmake, que é utilizado pela extensão oficial da Raspberry Pi no VSCode para configurar corretamente o ambiente.
    Se o arquivo existir, ele é incluído, permitindo que recursos como auto-complete, debug remoto, e templates automáticos funcionem adequadamente.

Análise Crítica

  • O uso de EXISTS para checar a presença do arquivo evita erros e torna o projeto mais robusto.
  • Esta seção é essencial para ambientes com suporte a IDEs modernas, mas pode ser omitida com segurança se o projeto for construído apenas via terminal.
  • A presença dos comentários DO NOT EDIT é uma prática comum para marcar blocos sensíveis que são exigidos por ferramentas externas.

Observações Didáticas

  • 🧰 Para iniciantes: Essa parte pode parecer obscura à primeira vista, mas pense nela como a “ponte” entre o CMake e o seu editor (VSCode). Se ela estiver funcionando, você terá suporte a atalhos, intellisense e debug facilitado.
  • 🌍 Dica de compatibilidade: Quando você compartilha seu projeto com colegas usando Windows e você usa Linux (ou vice-versa), esse bloco ajuda a manter tudo funcionando sem dor de cabeça.
  • 📦 Importante saber: Se o arquivo pico-vscode.cmake não estiver instalado, o build ainda funcionará — mas você perderá integração com o VSCode.

3. Parametrização por Ambiente: Importando o env.cmake

Este bloco mostra como carregar configurações externas e definir valores padrão para variáveis críticas de conexão, como Wi-Fi e MQTT. Veja o trecho abaixo:

if(EXISTS "${CMAKE_SOURCE_DIR}/env.cmake")
    include("${CMAKE_SOURCE_DIR}/env.cmake")
    message(STATUS "Arquivo env.cmake carregado com sucesso.")
else()
    message(FATAL_ERROR "Arquivo env.cmake não encontrado!")
endif()

Explicação Didática

  1. if(EXISTS "${CMAKE_SOURCE_DIR}/env.cmake")
    Verifica se o arquivo env.cmake existe no diretório raiz do projeto. Essa verificação é crucial para não interromper o processo de configuração se o arquivo estiver ausente ou mal posicionado.
  2. include(...)
    Se o arquivo existir, ele é carregado e suas variáveis passam a ser conhecidas no escopo do CMake. Isso permite separar a configuração sensível ou personalizada (como senhas e tópicos MQTT) do corpo principal do projeto.
  3. message(STATUS "...") e message(FATAL_ERROR "...")
    Usadas para informar claramente ao usuário o sucesso ou falha dessa etapa. Um erro fatal é gerado se o env.cmake estiver ausente, forçando o desenvolvedor a corrigi-lo antes de prosseguir — uma forma de evitar builds incompletos ou configurações erradas.

A seguir, são aplicadas validações adicionais:

if(NOT DEFINED ENV{WIFI_SSID})
    message(WARNING "Variável WIFI_SSID não definida no .env.")
    set(ENV{WIFI_SSID} "ArvoreDosSaberes")
endif()
# ... outros blocos semelhantes para WIFI_PASSWORD, MQTT_BROKER, etc.

Explicação Didática

Cada bloco verifica se uma variável de ambiente essencial está definida (ENV{VARIAVEL}). Se não estiver, ele:

  • Emite um aviso não fatal, alertando o usuário;
  • Define um valor padrão razoável para que o build continue.

Ao final, todas as variáveis são capturadas explicitamente para o escopo interno do CMake:

set(WIFI_SSID "$ENV{WIFI_SSID}")
set(WIFI_PASSWORD "$ENV{WIFI_PASSWORD}")
set(MQTT_BROKER "$ENV{MQTT_BROKER}")
set(MQTT_BASE_TOPIC "$ENV{MQTT_BASE_TOPIC}")
set(MQTT_RACK_NUMBER "$ENV{MQTT_RACK_NUMBER}")

Análise Crítica

  • O uso do env.cmake permite separar configuração de ambiente do código — uma excelente prática que segue os princípios da engenharia de software moderna.
  • Fornecer valores padrão facilita testes e uso didático, mas o ideal seria mover os valores sensíveis (como senhas) para fora do controle de versão (usando, por exemplo, .gitignore).
  • Poderia haver uma variável global ou opção no CMake para desativar temporariamente os erros fatais, facilitando builds rápidos durante o desenvolvimento.

Observações Didáticas

  • 🧪 Analogia simples: Pense no env.cmake como um “cartão de visita” que você entrega ao projeto, dizendo quem você é (SSID, senha, broker). Assim, ele sabe com quem falar e como se comportar.
  • 📁 Organização é tudo: Ao manter essas variáveis fora do CMakeLists.txt, você pode trocar de rede ou broker sem reconfigurar o projeto inteiro — basta editar ou substituir o env.cmake.
  • 🚫 Cuidado comum: Não deixar o env.cmake com credenciais sensíveis visíveis em repositórios públicos. Para isso, use .gitignore.

4. Inicialização do SDK e Definição do Executável

Com todas as variáveis e configurações preparadas, o próximo passo é estruturar o projeto de forma que o SDK da Raspberry Pi Pico possa ser utilizado corretamente, e o firmware final seja construído como um executável nomeado. O trecho em destaque é o seguinte:

# Pull in Raspberry Pi Pico SDK (must be before project)
include(pico_sdk_import.cmake)

project(firmware_client_mqtt C CXX ASM)

# Initialise the Raspberry Pi Pico SDK
pico_sdk_init()

Explicação Didática

  1. include(pico_sdk_import.cmake)
    Este comando inclui o script pico_sdk_import.cmake, normalmente localizado na raiz do SDK da Raspberry Pi. Ele é responsável por carregar as bibliotecas, drivers e configurações internas que fazem parte do Pico SDK.
    É essencial que esta linha venha antes do comando project(...), pois o SDK precisa estar carregado para que o CMake reconheça suas funções auxiliares como pico_sdk_init() ou pico_enable_stdio_usb().
  2. project(firmware_client_mqtt C CXX ASM)
    Define oficialmente o nome do projeto, bem como os tipos de código que ele conterá:
    • C: código C (linguagem base do projeto);
    • CXX: suporte a C++, mesmo que opcional;
    • ASM: suporte à linguagem Assembly, caso você deseje manipular diretamente registradores ou realizar otimizações de baixo nível.
  3. pico_sdk_init()
    Esta função é uma macro do Pico SDK que realiza a configuração padrão do ambiente, ativando funcionalidades como drivers de hardware (hardware_gpio, hardware_adc, etc.), bibliotecas utilitárias e integração com o sistema de build.

Em seguida, o projeto define o binário principal:

add_executable(firmware_client_mqtt
    firmware_client_mqtt.c
)

E depois configura nome e versão para fins de organização:

pico_set_program_name(firmware_client_mqtt "firmware_client_mqtt")
pico_set_program_version(firmware_client_mqtt "0.1")

Explicação Didática

  1. add_executable(...)
    Esta linha define o arquivo principal a ser compilado, neste caso, firmware_client_mqtt.c. O nome dado ao executável será usado como base para gerar o binário .uf2 (formato de firmware usado pelo RP2040).
    Também é possível incluir múltiplos arquivos .c, .cpp ou .s (Assembly) se o projeto for modularizado.
  2. pico_set_program_name e pico_set_program_version
    Estes comandos definem metadados do projeto, como nome e versão, que podem ser usados por ferramentas de depuração ou sistemas de versionamento. Embora opcionais, são úteis em ambientes colaborativos ou industriais.

Análise Crítica

  • Esta seção está tecnicamente correta e bem estruturada, seguindo as recomendações do Pico SDK.
  • O uso explícito de C, CXX e ASM torna o projeto mais versátil e pronto para escalar em complexidade.
  • O nome do projeto (firmware_client_mqtt) é repetido em vários pontos. Poderia ser definido via uma variável (set(PROJECT_NAME firmware_client_mqtt)) para facilitar manutenção futura.

Observações Didáticas

  • 🚀 Analogia prática: Essa parte é como “ligar a tomada” do seu projeto. Você diz ao sistema: “meu projeto se chama X, usa essas linguagens, e quero usar as bibliotecas do SDK da Raspberry Pi”.
  • 📦 Dica extra: Ao compilar, o CMake vai gerar automaticamente arquivos .elf, .bin e .uf2, prontos para serem gravados na flash do RP2040.
  • 🗃 Boas práticas: Sempre modularize seu código desde o começo. Mesmo que só tenha um arquivo .c, mantenha espaço para crescer (ex: src/, include/).

5. Ativando Entradas/Saídas e Ligando Bibliotecas Essenciais

Depois de declarar o executável e configurar seu nome e versão, o projeto define como o firmware irá se comunicar com o mundo externo — por portas seriais ou USB — e quais bibliotecas devem ser incluídas na hora da linkagem. Veja o trecho:

pico_enable_stdio_uart(firmware_client_mqtt 0)
pico_enable_stdio_usb(firmware_client_mqtt 1)

Explicação Didática

  1. pico_enable_stdio_uart(<target> <boolean>)
    Define se a UART (porta serial física) será usada como saída padrão (stdout) do programa. No exemplo acima, o valor 0 desativa a UART. Isso pode ser útil se o projeto não utilizar os pinos GPIO dedicados à UART, ou se estiver usando USB para comunicação com o PC.
  2. pico_enable_stdio_usb(<target> <boolean>)
    Ativa a comunicação serial via USB virtual (CDC). Com 1, o firmware pode imprimir mensagens no terminal conectado via cabo USB — muito útil para debug com ferramentas como minicom, PuTTY, Thonny ou o console do VSCode.

Em seguida, são declaradas as bibliotecas necessárias à aplicação:

target_link_libraries(firmware_client_mqtt
    pico_stdlib
    pico_cyw43_arch_lwip_threadsafe_background
    pico_lwip_mqtt
)

Explicação Didática

  1. target_link_libraries(...)
    Essa linha especifica quais bibliotecas serão ligadas (linkadas) ao firmware durante a compilação.
    • pico_stdlib: a biblioteca padrão do SDK, que fornece funções básicas como printf, controle de pinos, delays, etc.
    • pico_cyw43_arch_lwip_threadsafe_background: fornece acesso ao chip Wi-Fi CYW43 (usado no RP2040 W) em modo cooperativo com a pilha TCP/IP lwIP.
    • pico_lwip_mqtt: adiciona suporte ao protocolo MQTT com base na biblioteca lwIP, permitindo que o firmware se comunique com brokers MQTT como o Mosquitto, HiveMQ, etc.

Análise Crítica

  • Desativar UART e ativar apenas USB (como neste projeto) é uma escolha moderna e prática, já que a maioria dos computadores não possui porta serial física.
  • O uso de pico_lwip_mqtt demonstra um foco em conectividade IoT. Esta biblioteca ainda é pouco documentada fora dos exemplos oficiais, então usar os exemplos do SDK como base é uma boa prática.
  • Poderia ser interessante encapsular as bibliotecas adicionais em uma função auxiliar (add_custom_dependencies()), principalmente em projetos maiores.

Observações Didáticas

  • 🔌 Para iniciantes: Pense na UART e na USB como “canais de conversa” entre o RP2040 e o mundo externo. Você pode escolher usar um, ambos, ou nenhum.
  • 🧰 Boas práticas: Se for usar UART, lembre-se de configurar os pinos no firmware (gpio_set_function(...)). Se usar USB, não esqueça que a comunicação começa após a USB ser enumerada pelo host — o que leva alguns milissegundos após reset.
  • 🌐 Importante saber: A biblioteca pico_cyw43_arch_lwip_threadsafe_background executa tarefas de rede em segundo plano, sem precisar de um RTOS. Ideal para projetos simples mas que precisam de conectividade Wi-Fi confiável.

6. Inclusão de Diretórios e Definição de Macros de Conexão

Com a estrutura principal pronta e as bibliotecas já ligadas, o projeto agora configura o acesso aos diretórios de cabeçalhos e exporta as variáveis de ambiente para uso direto no código C:

target_include_directories(firmware_client_mqtt PRIVATE ${CMAKE_CURRENT_LIST_DIR})

Explicação Didática

  1. target_include_directories(...)
    Especifica para o compilador onde ele deve procurar os arquivos .h durante a compilação.
    • firmware_client_mqtt: é o alvo (o executável).
    • PRIVATE: significa que esses diretórios são usados apenas internamente para este alvo (e não propagados a outras dependências).
    • ${CMAKE_CURRENT_LIST_DIR}: refere-se ao diretório atual onde está o CMakeLists.txt. Isso permite que o main.c e outros arquivos no mesmo diretório acessem os headers locais diretamente.

Agora, as variáveis de ambiente definidas anteriormente são “injetadas” no código-fonte como macros com #define, utilizando o comando:

target_compile_definitions(firmware_client_mqtt PRIVATE 
    WIFI_SSID=\"${WIFI_SSID}\" 
    WIFI_PASSWORD=\"${WIFI_PASSWORD}\" 
    MQTT_BROKER=\"${MQTT_BROKER}\" 
    MQTT_BASE_TOPIC=\"${MQTT_BASE_TOPIC}\"
    MQTT_RACK_NUMBER=\"${MQTT_RACK_NUMBER}\"
)

Explicação Didática

  1. target_compile_definitions(...)
    Insere macros de pré-processador no projeto. Na prática, é como se o CMake escrevesse automaticamente estas linhas no seu código: #define WIFI_SSID "ArvoreDosSaberes" #define WIFI_PASSWORD "Arduino2022" #define MQTT_BROKER "mqtt.rapport.tec.br" #define MQTT_BASE_TOPIC "rack_inteligente" #define MQTT_RACK_NUMBER "3" Isso permite que o código-fonte seja genérico e portátil, pegando os dados do ambiente e não de strings fixas.

Análise Crítica

  • O uso de target_compile_definitions é altamente recomendável, pois centraliza a configuração no CMake em vez de espalhar definições pelo código-fonte.
  • A sintaxe de escape com \"...\" garante que as strings sejam corretamente interpretadas como literais no código C. Uma falha comum de iniciantes é esquecer essas aspas.
  • Em projetos maiores, pode-se usar arquivos .h autogerados a partir do CMake para organizar essas definições (ex: config.h.in com configure_file()).

Observações Didáticas

  • 🧠 Para iniciantes: Pense que você está mandando um bilhete do CMake para o seu código C. Esse bilhete diz: “ei, aqui está o nome da sua rede Wi-Fi e os dados do MQTT”.
  • ⚠ Erros comuns: Se você esquecer de escapar as aspas (\"), o compilador vai entender errado a definição e gerar erros como “expected identifier”.
  • 🛡 Boas práticas: Nunca inclua senhas reais ou dados sensíveis diretamente no main.c. Use sempre esse método de parametrização, ou proteja via arquivos ignorados no Git.

7. Geração dos Arquivos de Saída: pico_add_extra_outputs

No final do arquivo, encontramos a seguinte linha:

pico_add_extra_outputs(firmware_client_mqtt)

Explicação Didática

Este comando é uma macro fornecida pelo Pico SDK que automatiza a criação de diferentes formatos de saída do firmware. A partir do executável gerado (firmware_client_mqtt.elf), ela cuida de produzir também:

  • firmware_client_mqtt.bin: imagem binária “crua”, usada em alguns programadores.
  • firmware_client_mqtt.uf2: formato específico do RP2040, utilizado para arrastar e soltar o firmware diretamente na unidade USB visível quando o RP2040 está em modo de bootloader.
  • Arquivos .map, .hex, .dis ou .lst também podem ser gerados, dependendo das opções do CMake.

Tudo isso acontece de forma automática, dispensando a escrita manual de comandos extras.

Análise Crítica

  • O uso de pico_add_extra_outputs é obrigatório em projetos com RP2040 se você quiser gerar arquivos .uf2, que são os mais práticos para upload via USB.
  • Essa macro também facilita o debug, já que o .elf gerado pode ser carregado diretamente por ferramentas como GDB, OpenOCD ou o depurador do VSCode.
  • Poderia ser complementada com scripts de pós-build para, por exemplo, copiar o .uf2 para um diretório específico ou ativar gravação automática via picotool.

Observações Didáticas

  • 🧾 Para iniciantes: Essa etapa é como pedir ao compilador: “não me dê só o resultado final, me dê também outras versões do programa — uma para o bootloader, outra para depurar, outra para backup”.
  • 💾 Boas práticas: Após cada build, confira a pasta build/ — os arquivos .uf2, .elf e .bin estarão lá. O .uf2 é o que você deve arrastar e soltar no RP2040 quando ele estiver em modo boot (pressionando o botão BOOTSEL).
  • 🚦 Dica de produtividade: Se você estiver usando VSCode com a extensão oficial, essa macro garante que o botão “Build” funcione corretamente e gere o .uf2 automaticamente.

✅ Finalização da Análise Técnica

Com essa última linha, fechamos a análise completa e detalhada do arquivo CMakeLists.txt. Todas as etapas — desde configuração básica, carregamento do SDK, definição do executável, inclusão de bibliotecas, parâmetros de ambiente até a geração dos arquivos finais — foram explicadas com clareza e espírito didático.

Perfeito! Vamos então à conclusão geral do artigo, amarrando todo o conteúdo de forma coesa e didática.

Conclusão

Ao longo deste artigo, percorremos — linha por linha — a estrutura de um CMakeLists.txt real utilizado em um projeto baseado no microcontrolador RP2040, com foco em conectividade Wi-Fi e MQTT. O objetivo foi mais do que explicar comandos: buscamos desenvolver no leitor a compreensão do porquê de cada configuração, tornando-o capaz de analisar, adaptar e evoluir seus próprios projetos.

Iniciamos com a definição dos padrões de compilação e seguimos pela configuração do ambiente de desenvolvimento, mostrando como tornar o projeto compatível com ferramentas modernas como o VSCode. Depois, vimos como separar parâmetros de configuração em arquivos auxiliares (env.cmake) e como capturar variáveis de ambiente de forma segura e elegante. Em seguida, exploramos a inicialização do SDK, a declaração do executável, a ativação dos canais de comunicação via USB e UART, a ligação com bibliotecas críticas como pico_lwip_mqtt, e, por fim, a geração dos arquivos .uf2 e .elf prontos para gravação.

Além do conteúdo técnico, discutimos boas práticas como:

  • Separar configuração do código-fonte com env.cmake;
  • Utilizar target_compile_definitions para injetar parâmetros no pré-processador;
  • Escapar corretamente strings definidas no CMake;
  • Manter o projeto modular e escalável com target_include_directories e target_link_libraries;
  • Evitar hardcoding de dados sensíveis e trabalhar com variáveis de ambiente.

Esse conhecimento é fundamental para qualquer desenvolvedor embarcado que deseje usar o RP2040 de forma profissional e segura. A compreensão profunda da infraestrutura de build é o que separa um programador iniciante de um desenvolvedor capaz de integrar sistemas complexos, automatizar tarefas, e resolver problemas de forma elegante.

Próximos Passos

Se você chegou até aqui, parabéns! Seu próximo passo pode ser:

  • Explorar o conteúdo do arquivo env.cmake em detalhes;
  • Modularizar seu projeto criando subdiretórios como src/ e include/;
  • Automatizar tarefas de pós-build, como upload via picotool;
  • Adicionar testes unitários usando CMocka ou Unity em conjunto com CMake;
  • Criar templates de projetos reutilizáveis com base nessa estrutura.

Indicações de Leitura Complementar

The post Como Estruturar um Projeto Profissional com CMake para o RP2040: Guia Didático Passo a Passo first appeared on MCU & FPGA.

]]> 635