# Organização de um projeto
Um projeto é uma pasta no disco governada por um arquivo {file}`.spf` (*SAPHO Project File*). Tudo o que a AURORA sabe sobre o projeto está nele: quais arquivos participam, qual é o Top Level, qual é o Testbench Top e quais processadores existem.
## A pasta
Um projeto que já tem um processador e alguns fontes Verilog fica assim:
```text
MeuProjeto/
├── MeuProjeto.spf o arquivo do projeto
├── contador.v fonte Verilog importado
├── tb_contador.v testbench importado
├── media_movel/ um processador SAPHO: o que você escreve
│ ├── media_movel.cmm o programa (ou media_movel.cpp)
│ ├── input_0.txt estímulo da porta de entrada 0
│ └── media_movel/ a pasta de saída: tudo o que o YANC gera
│ ├── media_movel.asm
│ ├── media_movel.v
│ ├── media_movel_inst.mif
│ ├── media_movel_data.mif
│ ├── media_movel_tb.v
│ └── output_0.txt o que a simulação do processador escreveu
├── testbench/ estado de ondas por testbench
├── .aurora/ registros da AURORA (histórico de execuções)
└── Backup/ zips gerados pelo botão de backup
```
O projeto nasce só com o {file}`.spf`. A pasta de um processador aparece quando você o cria no Hub, só com o fonte dentro; a pasta de saída, com o mesmo nome do processador, o YANC cria na primeira compilação. As demais aparecem conforme o uso.
Cada processador tem, então, duas pastas:
- {file}`media_movel/` guarda o que **você escreve**: o fonte, os arquivos que inicializam vetores e os {file}`input_N.txt` (e os {file}`cade_k.txt`, se o processador usar links; veja {doc}`../sapho/linguagem`);
- {file}`media_movel/media_movel/` guarda o que **o YANC gera**: o assembly, o Verilog, as memórias, o testbench, as tabelas da forma de onda e as saídas da simulação. Não escreva nada lá dentro: a próxima compilação sobrescreve.
O nome do processador é o nome do arquivo fonte, e vira o nome do módulo Verilog. Por isso ele só aceita letras sem acento, dígitos e `_`, não pode começar com dígito nem com `__`, e não pode ser uma palavra reservada do Verilog (`wire`, `module`, `begin`...). A AURORA confere isso ao criar e ao renomear. Para renomear um processador, use a opção da árvore ou do Hub: ela troca a pasta, o fonte e a pasta de saída juntos.
## Projetos de versões antigas
Antes do YANC 7.1, cada processador tinha três subpastas, {file}`Software/`, {file}`Hardware/` e {file}`Simulation/`, e o nome do módulo vinha da diretiva `#PRNAME`. O compilador novo não aceita mais nenhuma das duas coisas. Ao abrir um projeto assim, a AURORA pergunta, uma vez, se pode convertê-lo:
- o que você escreveu (o fonte, os arquivos de vetor, os {file}`input_N.txt`, um {file}`.v` seu que estivesse em {file}`Hardware/`) vai para a pasta do processador;
- o que o YANC tinha gerado vai para a pasta de saída;
- nada é apagado e nada é sobrescrito: se o destino já existe, o arquivo fica onde estava e aparece no relatório;
- a linha `#PRNAME` sai do fonte, e o {file}`.spf` passa a apontar para os lugares novos.
No fim, um relatório lista o que foi movido e o que ficou. Se o `#PRNAME` antigo dava ao módulo um nome diferente do nome da pasta, o relatório oferece renomear o processador para esse nome, para o seu top-level continuar achando o módulo. O mesmo vale para um nome que não serve mais (com hífen ou acento). Quem responder {guilabel}`Agora não` pode converter depois, abrindo o projeto de novo; até lá ele não compila.
```{list-table}
:widths: 50 50
:align: center
* - **A pergunta**
```{image} ../_static/assets/screenshots/aurora-conversao-pergunta.png
:alt: Dialogo Projeto na estrutura de pastas antiga, com os botoes Agora nao e Converter.
:width: 100%
```
- **O relatório**
```{image} ../_static/assets/screenshots/aurora-conversao-relatorio.png
:alt: Dialogo Projeto convertido, com a lista dos arquivos movidos e a linha do nome retirada do fonte.
:width: 100%
```
```
## Projetos de exemplo
Quem prefere partir de algo pronto tem o botão {guilabel}`Projetos de exemplo...` na tela de boas-vindas: ele pergunta só onde salvar e cria **cinco projetos completos**, cada um com o seu {file}`.spf` e o testbench já registrado, todos dentro de uma pasta {file}`exemplos-sapho`. Os cinco entram na lista de recentes, do mais simples para o mais completo:
1. **Contador em Verilog** — Verilog puro, sem processador; o caminho mais curto para ver a AURORA elaborar e simular.
2. **Média móvel** — o processador do {doc}`tutorial <../sapho/tutorial-filtro>`, em aritmética inteira.
3. **Trigonometria** — ponto flutuante: seno, cosseno e arco-tangente.
4. **Notação de Dirac** — a álgebra linear escrita como na física, uma operação por linha.
5. **Cruzamento por zero** — duas entradas, cinco saídas, filtros IIR e o endereçamento de porta.
Os fontes viajam dentro do aplicativo, então o botão funciona sem internet. Instalar de novo na mesma pasta não sobrescreve nada: o que já existe é respeitado. A Aurora Intelligence conhece os cinco e também sabe criá-los, a pedido, pelo chat.
Em desenho, o caminho de um arquivo até o hardware:
```{mermaid}
flowchart TB
subgraph P["MeuProjeto/"]
SPF["MeuProjeto.spf
quem é top level, quem é testbench"]
V["contador.v, tb_contador.v
Verilog escrito à mão"]
subgraph PROC["media_movel/ (um processador)"]
direction LR
SW["media_movel/
você escreve
.cmm, input_N.txt"]
OUT["media_movel/media_movel/
YANC gera
.asm, .v, .mif, testbench, saídas"]
SW -->|compilar e simular| OUT
end
end
SPF -.governa.- PROC
SPF -.governa.- V
```
:::{warning}
**Escolha bem o caminho da pasta.** As ferramentas de linha de comando que rodam por baixo (compiladores, Icarus, Verilator, Yosys) recebem esse caminho como argumento, e várias delas engasgam com acentos, espaços duplos, cedilha, `#`, `&`, `%` ou parênteses. O sintoma é ruim de diagnosticar: um erro estranho de arquivo não encontrado, vindo de uma etapa que não tem nada a ver com o seu código.
Use letras sem acento, números, hífen e sublinhado. `C:\Projetos\meu_filtro` está bom; `C:\Meus Projetos (2026)\Simulação #1` não. Vale para o nome do projeto e para toda a árvore de pastas acima dele, inclusive o nome de usuário do Windows. O compilador e os simuladores já aceitam acento no caminho; o espaço continua sendo o que mais atrapalha, porque o Verilator não aceita espaço no caminho do projeto. O nome do processador tem regra mais estrita, descrita acima.
:::
## O arquivo .spf
É um JSON legível. Guarda o nome e o caminho base do projeto, a lista de processadores com suas configurações de simulação, as listas de fontes sintetizáveis e de testbenches, e os dois ponteiros centrais: `topLevelFile` e `testbenchFile`. Caminhos dentro do projeto são gravados relativos, então o projeto pode ser movido ou copiado de máquina para máquina sem quebrar.
:::{tip}
O {file}`.spf` abre no editor como JSON com realce. Ler o seu é uma boa forma de entender o que a AURORA registra. Editar à mão raramente é necessário; a interface cuida dele.
:::
:::{warning}
Os parâmetros de arquitetura do processador (largura de bits, mantissa, portas) não ficam no {file}`.spf`. Eles vivem nas diretivas no topo do arquivo {file}`.cmm` (ou nos `#pragma yanc` do {file}`.cpp`), que é a fonte da verdade: editar uma diretiva muda o processador na próxima compilação. No {file}`.spf` ficam apenas as preferências de simulação de cada processador (clock, número de ciclos).
:::
(sintetizavel-ou-testbench-quem-decide-e-o-conteudo)=
## Sintetizável ou testbench: quem decide é você
Todo arquivo Verilog do projeto tem um papel, guardado no {file}`.spf`: **sintetizável** (entra na elaboração e no PRISM), **testbench**, ou **sem papel**. Um arquivo novo ou importado entra sem papel, com um ponto de interrogação no ícone, e fica fora de toda compilação até você escolher, pelo botão direito do mouse. Antes de compilar, o terminal lista os arquivos que ficaram de fora por não ter papel. Arquivos `.py` entram como testbenches cocotb, e o que o YANC gera já nasce com o papel certo: o {file}`.v` é sintetizável e o {file}`_tb.v` é testbench. Nada muda de papel sozinho.
Além do papel, há o papel de raiz, que também é seu:
```{figure} ../_static/assets/screenshots/aurora-arvore-menu-contexto.png
:alt: Menu de contexto de um arquivo Verilog ainda sem papel, com as opcoes Marcar como sintese e Marcar como testbench.
:width: 45%
:align: center
O menu de contexto de um {file}`.v` ainda sem papel, na visão Arquivos: as duas escolhas de papel.
```
Top Level
: O módulo raiz do circuito sintetizável. Define de onde a elaboração parte e o que o PRISM desenha. Marque pelo menu de contexto do arquivo na visão Arquivos: {guilabel}`Definir como Top Level`.
Testbench Top
: O arquivo que comanda a simulação, {file}`.v` ou {file}`.py`. Define o que roda quando você clica em {guilabel}`Analisar Verilog`. Marque por {guilabel}`Definir como testbench atual`, no menu de um arquivo que já é testbench.
```{list-table}
:widths: 50 50
:align: center
* - **Top Level**
```{image} ../_static/assets/screenshots/aurora-top-level.png
:alt: Menu de contexto do media_movel.v gerado, com a opcao Definir como Top Level.
:width: 100%
```
- **Testbench Top**
```{image} ../_static/assets/screenshots/aurora-top-testbench.png
:alt: Menu de contexto do media_movel_tb.v gerado, com a opcao Definir como testbench atual.
:width: 100%
```
```
Os dois papéis são exclusivos: marcar um arquivo desmarca o anterior. A barra de status mostra os dois o tempo todo.
## Importar e criar arquivos
Arraste arquivos {file}`.v`, {file}`.sv`, {file}`.vh` ou {file}`.py` de fora para a árvore, ou use o menu de contexto da área vazia: {guilabel}`Novo arquivo`, {guilabel}`Novo testbench cocotb (.py)`, {guilabel}`Novo .gitignore`. Na visão Pastas, o menu de contexto oferece o conjunto completo de operações de disco, com lixeira e desfazer.
## Backup
O botão de backup no cabeçalho da árvore gera {file}`Backup/_.zip` com tudo, exceto os backups anteriores. É a forma rápida de congelar um estado antes de uma mudança grande. Para histórico de verdade, o painel de controle de versão está em {doc}`apoio`.
Pronto para trabalhar. A Parte II começa criando um projeto Verilog do zero: {doc}`../verilog/tutorial-contador`.