# Compilação

Compile projetos LaTeX, Typst e Markdown, escolha opções de compilação por motor, leia os logs e controle o download de pacotes para uso offline.

Um novo projeto LaTeX começa no motor de compilação padrão definido em **Configurações → Motores → LaTeX**. Por padrão, ele é o **Tectonic**, um motor baseado no XeTeX que acompanha o Oleafly. Você também pode usar o `latexmk` quando um projeto precisa de uma cadeia de ferramentas TeX tradicional, em um único projeto ou como padrão. Projetos Typst compilam com o Typst embutido ou com outra versão fixada pelo projeto, e projetos Markdown passam pelo Pandoc e pelo Tectonic. O compilador LaTeX e a versão do Typst pertencem ao projeto, então alterar um projeto não afeta os outros.

## Iniciar uma compilação

![Use Compilar de novo na barra de ferramentas do projeto; a seta ao lado abre as opções de compilação.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1265,0,330,48)

- ⌘↵ (Ctrl+Enter), em qualquer lugar.
- O botão **Compilar** no canto superior direito da barra de ferramentas. Ele vira **Compilar de novo** depois que o projeto tem um resultado.
- **Compilar de novo** na paleta de comandos ⌘K.
- Abrir um projeto em uma visualização que mostra o painel do PDF compila uma vez automaticamente, para você chegar a uma prévia nova.
- `oleafly build` em um terminal ou em um script. Veja [Ferramenta de linha de comando](/docs/cli/).

Compilar sempre salva antes o arquivo ativo, para que o PDF corresponda ao que você vê. Se você estiver na visualização só de editor, compilar revela a visualização dividida para você acompanhar o resultado.

## Opções de compilação

A seta ao lado de **Compilar de novo** abre as opções de compilação. O menu mostra apenas as opções que têm algum efeito para o motor do projeto.

| Grupo | LaTeX com Tectonic | LaTeX com `latexmk` | Typst | Markdown |
|---|---|---|---|---|
| **Compilação automática** | Sim | Sim | Sim | Sim |
| **Modo de compilação** (Normal ou Rápido) | Sim | Não | Não | Não |
| **Verificações de sintaxe** | Sim | Sim | Não | Não |
| **Compilador (deste projeto)** | Sim | Sim | Não | Não |
| **Versão do Typst**, **Fontes**, **Compilação**, **Variante** | Não | Não | Sim | Não |
| **Tratamento de erros de compilação** | Sim | Sim | Não | Não |

**Parar a compilação** e **Compilar do zero** ficam no fim do menu para todos os motores. O grupo **Variante** aparece quando um projeto Typst tem variantes de compilação.

Em **Compilador (deste projeto)**, **Tectonic** é embutido. **Automático** executa o TeX do seu sistema por meio do `latexmk` e escolhe o compilador a partir do código-fonte. **pdfLaTeX**, **XeLaTeX** e **LuaLaTeX** fixam esse compilador e também passam pelo `latexmk`, e **upLaTeX** e **pLaTeX** compilam documentos em japonês. Toda escolha, exceto o Tectonic, precisa de uma distribuição TeX. Se este computador não tem nenhuma, o Oleafly oferece instalar o TinyTeX quando você escolhe uma delas. Veja [Quando nenhum TeX está instalado](/docs/latex-engines/#when-no-tex-is-installed). Os grupos do Typst são abordados em [Projetos Typst](/docs/typst/).

## Compilação automática

Defina **Compilação automática** como **Ligada** nas opções de compilação, ou execute **Ativar a compilação automática** na paleta ⌘K. Ela vem desligada por padrão, vale para todos os projetos, e os mesmos controles a desligam de novo.

Em um projeto LaTeX ou Markdown, o Oleafly recompila cerca de 2,5 segundos depois que você para de digitar. Só edições reais a disparam. Trocar de aba ou abrir arquivos não dispara.

Em um projeto Typst, a Compilação automática é a prévia em tempo real. O Oleafly mantém um processo Typst rodando, o arquivo aberto se salva sozinho um momento depois que você para de digitar, e o PDF é atualizado na mesma posição de rolagem. Veja [Prévia em tempo real com a Compilação automática](/docs/typst/#live-preview-with-auto-compile).

Compilações nunca se acumulam. Se você editar durante uma compilação automática, o Oleafly a interrompe e recomeça com o seu texto mais recente, para o PDF alcançar o estado atual mais depressa. Ele deixa uma compilação terminar quando você ou um agente a iniciou, quando ela está baixando pacotes, quando está quase no fim, ou quando ela mesma é um reinício. Nesses casos, exatamente uma compilação seguinte entra na fila, e o PDF final ainda reflete as suas edições mais recentes.

## Acompanhar o progresso

Uma barra de progresso fina percorre o topo da prévia durante a compilação, e antes de o primeiro PDF existir o painel mostra uma estimativa em porcentagem. Quando uma compilação termina, a barra de ferramentas mostra um **chip de status** com o tempo de compilação e um ícone de severidade:

- Marca de seleção verde: compilou com sucesso.
- Triângulo âmbar: compilou com avisos. Você ainda recebe o PDF.
- X vermelho: compilou com erros.

A prévia muda para o PDF automaticamente em caso de sucesso. Só uma falha real (nenhum PDF produzido) leva você à visualização de Logs.

![Uma compilação com falha sinalizada no editor e no log, e depois corrigida e compilada de novo.](https://cdn.oleafly.com/images/gifs/desktop/compile-errors.gif?v=2)

## Ler os logs

![Os Logs e a duração da última compilação ficam à esquerda da barra de ferramentas da prévia.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1146,44,239,42)

O botão **Logs** à esquerda da barra de ferramentas da prévia alterna entre o PDF e o log de compilação, com um contador de erros (vermelho) ou avisos (âmbar):

- Uma **lista de diagnósticos** analisada no topo: cada erro ou aviso com o seu tipo e, quando conhecido, a referência de linha `l.42`. Os caracteres que as fontes não conseguiram exibir ficam agrupados em **Caracteres ausentes**.
- O log completo do compilador abaixo, colorido: erros em vermelho negrito, referências de linha destacadas, aninhamento de arquivos recuado.
- Um botão **Copiar o log** captura tudo para um relatório de bug ou uma postagem em fórum. ⌘A seguido de ⌘C no log também copia tudo.
- **Limpar**, ao lado de **Copiar o log**, oculta o log e os erros dele até a próxima compilação. Os arquivos de build ficam, e a próxima compilação grava um log novo.

Logs longos abrem de imediato, mesmo com 100.000 linhas, e rolam sem áreas em branco.

Os erros de compilação também viram sublinhados ondulados no editor por meio do [pipeline de lint](/docs/editor/#the-built-in-latex-linter), e o [assistente de IA](/docs/ai-chat/) pode ler esse mesmo log com a ferramenta `get_log` quando você pede para corrigir os erros.

Os erros do Typst são marcados no editor no trecho exato que o Typst informa, com a linha do código-fonte e as próprias dicas do Typst. Erros comuns também vêm com uma explicação simples do que deu errado.

## Pacotes e compilação offline

O Tectonic baixa um pacote LaTeX na primeira vez que um documento precisa dele e depois o guarda em cache. A primeira compilação em um computador também busca de uma vez um lote de pacotes de uso comum. Essa primeira compilação pode ser mais lenta e precisa de conexão de rede. As compilações seguintes usam o cache. Se o espelho de pacotes do Oleafly falhar, a compilação recorre à fonte de upstream e o log avisa isso.

O **Modo offline** nas Configurações, no painel Geral, ou na paleta de comandos transforma isso em garantia para o Tectonic. O compilador roda com `--only-cached` e nunca baixa um pacote. Um documento que precise de um pacote fora do cache falha com uma mensagem que cita o arquivo quando possível, e **Desligar e compilar** desliga o Modo offline e compila de novo.

O Modo offline também vale para o Typst. O Typst não consegue baixar um pacote enquanto ele estiver ligado, então todo pacote `@preview` já precisa estar no cache ou dentro da pasta `typst-packages` do projeto. Veja [Pacotes do Typst Universe](/docs/typst/#packages-from-typst-universe). Projetos Markdown ignoram o Modo offline, e o log avisa isso.

O `latexmk` usa a distribuição TeX já instalada na sua máquina. O Oleafly verifica primeiro as distribuições do sistema, incluindo MacTeX, TeX Live, MiKTeX e TinyTeX, e **Configurações → Motores → LaTeX** marca como **Em uso** a que ele usa para compilar. Se nenhuma estiver disponível, o aplicativo pode instalar e gerenciar a própria cópia do TinyTeX. O MiKTeX também precisa do Perl para rodar o `latexmk`; veja [MiKTeX e Perl](/docs/latex-engines/#miktex-and-perl). Como um processo do TeX do sistema pode ler arquivos acessíveis à sua conta de usuário, use o `latexmk` apenas com projetos confiáveis.

Quando uma compilação com `latexmk` não encontra um `.sty`, `.cls`, um estilo de bibliografia, um arquivo de fonte, um arquivo de idioma do babel, uma biblioteca TikZ ou outro arquivo TeX, o Oleafly pode oferecer **Localizar e instalar** na mensagem de erro. O nome do arquivo e o nome do pacote costumam ser diferentes: `tikz.sty`, por exemplo, pertence ao pacote `pgf` do TeX Live. O Oleafly descobre o dono, instala-o com o `tlmgr`, atualiza a lista de pacotes e recompila. No Debian, no Ubuntu e no Fedora, o TeX Live pertence ao gerenciador de pacotes do sistema, então o Oleafly mostra o comando `apt` ou `dnf` no lugar. Use a lista **Pacotes** em **Configurações → Motores → LaTeX** quando preferir buscar primeiro ou gerenciar pacotes manualmente.

## Limites e válvulas de segurança

- Uma compilação por vez em cada projeto, em uma fila só da mais recente: pedidos novos substituem os antigos, então trocar de projeto no meio de uma compilação nunca exibe o PDF errado, e uma tempestade de compilações nunca se forma enquanto você digita.
- Uma compilação substituída ou expirada é de fato cancelada: o Oleafly encerra toda a árvore de processos do compilador, em todas as plataformas, em vez de deixá-la rodando em segundo plano.
- Uma compilação que passa de 5 minutos é interrompida em vez de ficar girando para sempre. Enquanto o Tectonic ainda está baixando pacotes, cada download empurra o limite para a frente, até 30 minutos no total. O Markdown para PDF tem 15 minutos, e o Quarto e o Calepin têm uma hora.
- Os resultados carregam uma identidade ligada ao pedido, então um PDF antigo de um término fora de ordem é recusado em vez de exibido.

## Falhas comuns, correções rápidas

- **"Pacote ausente" no Modo offline**: escolha **Desligar e compilar** na mensagem, ou desligue o Modo offline por uma compilação para baixar o pacote e guardá-lo no cache, depois ligue-o de novo.
- **"Este compilador precisa de uma distribuição TeX que funcione"**: o pdfLaTeX e os outros compiladores `latexmk` precisam de TeX neste computador, então escolher um sem ele abre este diálogo. Escolha **Baixar e usar o TinyTeX**, ou **Voltar para o Tectonic** para retornar ao motor embutido. Se uma compilação já falhou por esse motivo, a prévia oferece **Baixar e usar o TinyTeX** e **Usar Tectonic**. Veja [Quando nenhum TeX está instalado](/docs/latex-engines/#when-no-tex-is-installed).
- **"o latexmk precisa do Perl"** no MiKTeX: instale o Strawberry Perl, ou instale o TinyTeX, que traz o próprio. Veja [MiKTeX e Perl](/docs/latex-engines/#miktex-and-perl).
- **Um arquivo ausente em uma compilação com `latexmk`**: use **Localizar e instalar**. Se a busca falhar, procure o nome do arquivo ou do pacote na lista **Pacotes** em **Configurações → Motores → LaTeX**. No Debian, no Ubuntu ou no Fedora, instale-o com `apt` ou `dnf`. Pacotes do MiKTeX são gerenciados no MiKTeX Console.
- **O upLaTeX ou o pLaTeX não está instalado**: escolha **Instalar suporte a japonês (cerca de 450 MB)** quando for oferecido, ou execute o comando que a mensagem cita. Veja [Documentos em japonês](/docs/latex-engines/#japanese-documents-uplatex-and-platex).
- **Falta texto no PDF**, muitas vezes coreano, chinês ou japonês: a fonte não tem glifos para esses caracteres, e o TeX os deixa de fora sem falhar. O Oleafly avisa e o log traz uma configuração para colar. Veja [Caracteres ausentes no PDF](/docs/latex-engines/#characters-missing-from-the-pdf), ou [Caracteres que aparecem como caixas](/docs/typst/#characters-that-show-as-boxes) para o Typst.
- **Falta um índice, glossário ou lista de nomenclatura no PDF**: o Tectonic não consegue executar o `makeindex`. Mude o projeto para o `latexmk`, ou monte glossários com `\makenoidxglossaries`, que não precisa de ferramenta externa. No `latexmk`, listas feitas com `xindy` ou `\newglossary` não são geradas.
- **A compilação estourou o tempo**: compile de novo. Se pacotes ainda estavam sendo baixados, o download continua de onde parou. Para rascunhos longos no Tectonic, defina **Modo de compilação** como **Rápido**.
- **Uma figura EPS, um driver `pdftex` forçado ou um arquivo de pacote ausente no Tectonic**: o diálogo de motores abre. Se ele não abrir, ou você o fechou, escolha **Escolher motor**. [Quando o Tectonic não basta](/docs/latex-engines/#when-tectonic-isnt-enough) diz onde ele fica em cada visualização. Escolha a opção marcada como **Recomendado**: o seu LaTeX do sistema, quando o Oleafly encontra uma distribuição TeX que funciona, ou **Baixar e usar o TinyTeX**, quando não encontra. Para um pacote ausente, o Oleafly pode seguir para o instalador depois da troca.
- **`minted`, PythonTeX ou `\write18` bloqueado**: se você confia em todos os arquivos do projeto, escolha **Permitir comandos externos** na faixa acima do editor. Veja [Permitir comandos externos](/docs/latex-engines/#allow-external-commands).
- **Um download de pacote falhou no Tectonic**: verifique a conexão e escolha **Compilar de novo** na mensagem. O Oleafly já tentou a fonte de upstream depois do espelho, o download continua de onde parou e, se o computador estava offline, a compilação roda de novo sozinha quando a conexão voltar.
- **"O Typst 0.13.1 não está instalado"**: o projeto fixa uma versão do Typst que este computador não tem. Escolha **Baixar Typst 0.13.1** na prévia, ou **Usar Typst** seguido da sua versão padrão para soltar a fixação. Veja [Quando uma versão fixada está ausente](/docs/typst/#when-a-pinned-version-is-missing).
- **Avisos de citação ou referência indefinida**: a [Pré-verificação](/docs/preflight/#six-independent-checks) localiza cada um, com o arquivo e a linha.
- **Um erro que você não consegue interpretar**: pergunte à IA. "Corrija os erros de LaTeX" dispara um ciclo de compilação, leitura do log, edição dirigida e recompilação, usando a sua [política de aprovação](/docs/ai-chat/) selecionada.

## Outros motores de documento

A escolha do compilador LaTeX é separada do motor de documento do projeto:

- **Projetos Typst** compilam com o Typst 0.15.1 embutido ou com a versão fixada pelo projeto. Veja [Projetos Typst](/docs/typst/).
- **Projetos Markdown** geram o PDF por meio de um Pandoc gerenciado, com o Tectonic como motor de PDF.
- **Projetos Quarto** renderizam arquivos `.qmd` e `.Rmd` com o Quarto, em um PDF ou uma página web. Veja [Quarto](/docs/engines/#quarto).
- **Projetos Calepin** executam o código de um documento Typst com o Calepin e depois geram o PDF com o Typst embutido. Veja [Calepin](/docs/engines/#calepin). Nenhum dos dois motores executa o código de um projeto até você [permitir](/docs/engines/#allow-code-in-a-project).
- **PDFs etiquetados e acessíveis** usam LuaLaTeX por meio de uma instalação TeX do sistema ou do TinyTeX gerenciado pelo Oleafly. Veja [Motores LaTeX e pacotes](/docs/latex-engines/). O Typst 0.14 e versões posteriores etiquetam todo PDF sem passos extras.

O motor é uma escolha por projeto, feita na criação do projeto, e a interface se adapta a ela: ações que um motor não consegue suportar ficam ocultas em vez de deixadas para falhar. Para levar um projeto LaTeX ao Typst, [converta-o em um novo projeto Typst](/docs/typst/#convert-a-latex-project-to-typst).

## Guarde o código-fonte por trás de uma compilação bem-sucedida

Ative os [pontos de verificação](/docs/checkpoints/) para salvar o código-fonte usado pelas compilações bem-sucedidas. Você pode comparar e restaurar uma compilação anterior sem mudar o seu fluxo manual de trabalho com o Git.

Para manter o próprio PDF compilado na pasta do projeto, ative [Sincronizar PDF ao compilar](/docs/pdf-preview/#sync-pdf-on-compiles) no menu de salvar da prévia.
