Tutorial Zephyr OS: Como Criar o Primeiro Projeto com example-application, DeviceTree e West

Uma forma segura de “renomear para seu projeto” sem quebrar nada

Você consegue adaptar sem reestruturar de cara:

1. Renomeie a pasta example-application/ para o nome do seu produto só depois que você já tiver validado um build com west build -b <BOARD> app.
2. Ajuste o west.yml apenas para trocar nome/URLs/revisions dos seus módulos extras (se existirem).
3. Deixe boards/, drivers/, dts/bindings/, lib/ por enquanto como estão; primeiro faça o “hello world” rodar no seu target.

A pasta app/: onde nasce o seu firmware (arquivos essenciais + como adaptar com mudanças mínimas)

No example-application, o comando de build aponta explicitamente para a pasta app (west build -b $BOARD app). Ou seja: o “seu projeto” (a aplicação) está dentro de app/, enquanto a raiz do repositório concentra estrutura de módulo, testes, drivers, bindings e CI. (GitHub)
Essa separação é proposital: ela te permite evoluir a aplicação sem bagunçar o “pacote” de componentes out-of-tree (drivers/bindings/libs) do repositório.

3.1 O que normalmente existe dentro de app/ (e por quê)

Mesmo sem abrir cada arquivo linha-a-linha (o GitHub às vezes bloqueia listagens), a estrutura padrão recomendada pela documentação do Zephyr para uma aplicação é:

• app/CMakeLists.txt — ponto de entrada do build via CMake
• app/prj.conf — configuração Kconfig do projeto (o que vira CONFIG_*)
• app/src/main.c — seu código (ou, mais tarde, vários .c/.cpp)
• app/boards/ — ajustes específicos por board (overlays .overlay e/ou fragmentos .conf)

A própria documentação de “Application Development” descreve exatamente esse esqueleto: fonte em src/, CMakeLists.txt na raiz da app e target_sources(app …) apontando os seus arquivos. (Documentação Zephyr)

A frase que guia tudo aqui é: o build do Zephyr é application-centric — o build começa pela aplicação e ela controla a configuração e o build do Zephyr também, gerando um binário único. (Documentação Zephyr)

app/CMakeLists.txt: o “roteador” do build

O CMakeLists.txt da aplicação costuma fazer três coisas, sempre nessa ordem mental:

1. Define uma versão mínima do CMake (por compatibilidade com o ecossistema).
2. Faz find_package(Zephyr) (ou find_package(Zephyr REQUIRED ...)) para “plugar” o build system do Zephyr. A documentação do Zephyr CMake Package diz que, ao desenvolver uma aplicação, você basicamente precisa disso no início do CMakeLists.txt. (Documentação Zephyr)
3. Declara o projeto e lista as fontes com target_sources(app PRIVATE ...) (ou com bibliotecas e alvos auxiliares).

Um exemplo canônico (bem próximo do que o Zephyr recomenda como ponto de partida) é: (Documentação Zephyr)

cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr)
project(meu_primeiro_projeto)

target_sources(app PRIVATE src/main.c)

cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr)
project(meu_primeiro_projeto)

target_sources(app PRIVATE src/main.c)

Como adaptar para o seu novo projeto (mudanças mínimas e seguras):

• Troque apenas o nome do project(...) para refletir seu produto (isso é mais “identidade” do que funcionalidade).
• Se você for dividir o código em módulos, vá adicionando fontes aos poucos:
  • target_sources(app PRIVATE src/main.c src/foo.c src/bar.c)
• Se você tiver um componente que você quer compilar como biblioteca, você pode criar uma zephyr_library() no seu lib/ (fora do app/) — mas isso é “fase 2”; no primeiro projeto, mantenha simples.

app/prj.conf: o painel de liga/desliga do firmware

O prj.conf é onde você habilita/desabilita recursos via Kconfig, sem “sujar” o código com #ifdef desnecessário. Pense assim: o seu .c deveria expressar comportamento; o prj.conf deveria expressar “quais peças existem”.

Exemplo típico de “primeiro projeto” (console + logs):

CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y
CONFIG_PRINTK=y
CONFIG_LOG=y
CONFIG_LOG_DEFAULT_LEVEL=3

E o example-application já mostra no README um mecanismo importante para crescer sem virar bagunça: configurações extras por fragmento, usando -DEXTRA_CONF_FILE=debug.conf no build. (GitHub)
Isso é ouro na prática, porque separa “config de debug” da config normal. Você mantém prj.conf limpo e cria, por exemplo, debug.conf com logs mais verbosos e asserts ligados, ativando só quando precisar.