Anatomia do repositório (raiz) e o que você deve editar para “virar seu projeto”
Antes de tocar no app/, vale entender a raiz do example-application, porque é ali que ficam os “pinos de ancoragem” do workspace: o manifesto (west.yml), a integração como módulo Zephyr (pasta zephyr/), e os pontos de entrada do CMake/Kconfig para que seus drivers/bindings/bibliotecas out-of-tree possam ser descobertos e linkados corretamente. O próprio README deixa explícito que o objetivo do repo é servir como referência de estrutura e lista os blocos que ele demonstra (workspace app, módulos, topologia T2, boards, bindings, drivers, CI, runner, west extension, docs). (GitHub)
west.yml (o “manifest” do seu workspace)
No Zephyr, um workspace T2 (star topology) é quando a sua aplicação é o repositório-manifesto: ela contém west.yml e, dentro dele, declara “quais repositórios eu preciso para buildar” (incluindo zephyr e módulos). A documentação descreve exatamente isso e diz que esse formato é útil quando você está focado em uma aplicação principal. (Documentação Zephyr)
O arquivo west.yml é um manifest file do west: define remotes, projects, defaults e self (o repositório atual). Essa estrutura é detalhada na documentação oficial do west. (Documentação Zephyr)
O que você edita aqui ao adaptar para um projeto novo:
- Trocar as URLs de repositórios adicionais (se você tiver libs próprias, drivers próprios, middleware, etc.).
- Fixar versões/revisões (tag, branch ou SHA) para reprodutibilidade. O README do
example-applicationmenciona que ele é versionado junto com o Zephyr (tags alinhadas) e que owest.ymlaponta para a tag correspondente do Zephyr quando o repo está em uma versão específica. (GitHub) self:: você quase nunca remove; ele define a aplicação “central” do workspace e onde ela vive na árvore. (Documentação Zephyr)
Na prática, pense no west.yml como o “package-lock.json do firmware”: ele congela de onde vêm as dependências do seu RTOS e dos seus módulos.
.west/ (não fica no Git, mas é o “cérebro operacional” do workspace)
Quando você faz west init + west update (como o README manda), o west cria .west/ no diretório do workspace, e passa a controlar as revisões “declaradas pelo manifesto”. A documentação descreve inclusive o branch manifest-rev que o west gerencia para manter rastreável o que foi sincronizado da última vez. (Documentação Zephyr)
Isso explica por que “clonar solto” fora de workspace frequentemente dá erro: west build espera que você esteja em um workspace válido.
zephyr/ (pasta do repo) + “ser um módulo”
Você viu no tree que existe uma pasta zephyr/ dentro do example-application. (GitHub)
Essa pasta, nesse tipo de template, costuma conter arquivos como module.yml (ou equivalente) que dizem ao build system: “este repositório é um módulo Zephyr; você pode procurar Kconfig/CMake/headers aqui e incorporar quando apropriado”. A documentação oficial define módulos como repositórios que contêm zephyr/module.yml, permitindo que o build system “puxe” e integre o código do módulo. (Documentação Zephyr)
Por que isso importa no seu projeto novo?
Porque é o que viabiliza você manter drivers, libs e bindings fora da árvore oficial do Zephyr e ainda assim fazer com que o build os enxergue de forma “Zephyr-native”.
CMakeLists.txt (na raiz)
O Zephyr é application-centric: quem inicia o build é a aplicação, e ela controla a configuração e compilação do próprio Zephyr para produzir um binário único. (Documentação Zephyr)
Então, o CMakeLists.txt na raiz normalmente faz duas coisas:
- “encaixa” o repositório no fluxo do CMake do Zephyr (quando o repo é módulo, ele pode exportar alvos, incluir diretórios, hooks, etc.).
- prepara o terreno para subpastas como
lib/,drivers/, e integrações extras.
O que você costuma mudar ao adaptar:
- Nome de projeto/identidade (quando houver).
- Inclusão/remoção de subdiretórios do seu produto (por exemplo, se você vai ter
middleware/ouplatform/além dedrivers/). - Ajustes de exportação (headers públicos,
INTERFACElibs) se você quiser que outras aplicações consumam seu módulo.
Kconfig (na raiz)
O Kconfig é o “catálogo de opções” que aparecem no menuconfig/guiconfig e são ativadas via prj.conf. Mesmo quando você só quer um “primeiro projeto simples”, entender isso cedo evita gambiarra depois: você cria símbolos do tipo CONFIG_MY_FEATURE=y e deixa o build ligar/desligar componentes sem mexer em código. (Na próxima seção, quando entrarmos no app/prj.conf, isso fica bem concreto.)
Pastas raiz (o mapa do que existe e por que existe)
Pelo tree do repo você tem, na raiz: .github/ (CI), boards/ (boards custom), dts/bindings/ (bindings), drivers/ (drivers out-of-tree), include/app/ (headers públicos da app/módulo), lib/ (bibliotecas), scripts/, tests/, doc/, além de app/ (a aplicação em si). (GitHub)
O README também indica que o build típico é feito apontando para app (west build -b $BOARD app) e que existe um exemplo de uso de EXTRA_CONF_FILE=debug.conf, além de west flash e west twister para testes. (GitHub)
