# Motores e pacotes LaTeX

Escolha o Tectonic ou um compilador latexmk, use uma distribuição TeX existente ou instale o TinyTeX gerenciado do Oleafly.

O Oleafly vem com o Tectonic e também pode compilar por meio do `latexmk`. O menu de compilador do projeto controla os builds do dia a dia. **Configurações → Motores** mostra as distribuições TeX e os pacotes disponíveis no seu computador.

## Tectonic: o motor do dia a dia

O **Tectonic** é o motor de compilação padrão até você escolher outro em **Motor de compilação padrão**, em **Configurações → Motores → LaTeX**. Ele não precisa de instalação separada, busca pacotes conforme a necessidade e os guarda em cache para uso offline. É uma boa escolha para a maioria dos projetos e continua disponível mesmo quando nenhuma distribuição TeX do sistema está instalada. Veja [Definir um padrão para projetos novos](/docs/engines/#set-a-default-for-new-projects).

Para **PDFs marcados**, use o fluxo de trabalho LuaLaTeX. As marcações descrevem a estrutura do documento para tecnologias assistivas. Inspecione o resultado com a Pré-verificação depois de compilar.

### Fontes no motor embutido

O Tectonic é baseado no XeTeX, que lê arquivos de fonte diretamente. O Oleafly ajusta algumas coisas para que documentos escritos para o pdfLaTeX mantenham as fontes e o texto:

- Times, Helvetica, Courier, Palatino, Bookman, New Century Schoolbook e Avant Garde usam as versões TeX Gyre delas, em vez de recorrer ao Latin Modern.
- `\usepackage[T1]{fontenc}` estraga acentos e símbolos digitados neste motor, então o Oleafly mantém o documento em texto Unicode. Se uma fonte usada pelo documento só existe em T1, o documento fica em T1 e a compilação avisa que caracteres como ß, §, «, aspas curvas e € podem sair errados ou sumir. O aviso traz uma versão da linha que carrega o T1 só no pdfLaTeX:

  ```latex
  \usepackage{iftex}
  \ifPDFTeX
    \usepackage[T1]{fontenc}
  \fi
  ```

- Um documento que define `\pdfoutput=1`, como o arXiv pede, compila como está.
- Um documento `ctex` que não define `fontset` recebe as fontes Fandol, para ficar igual em todos os computadores. Acrescente `fontset=mac` às opções da classe para usar as fontes do próprio Mac.
- As fontes que vêm com o motor embutido são encontradas pelo nome do arquivo. `\setmainfont{UnBatang}` falha, e o erro diz para escrever `UnBatang.ttf`.

O Modo offline pula os ajustes de fonte e de codificação, então uma compilação offline de um documento assim pode sair diferente de uma online.

## latexmk e o TeX do sistema

Escolha pdfLaTeX, XeLaTeX, LuaLaTeX, upLaTeX ou pLaTeX no menu de compilador de um projeto quando ele depende de um fluxo de trabalho tradicional de TeX Live ou MiKTeX. O Oleafly executa esses compiladores por meio do `latexmk`. O **Automático** lê o arquivo principal e escolhe um: uma linha `% !TeX program = xelatex` no topo vence, depois as classes japonesas, depois os pacotes que precisam do XeLaTeX ou do LuaLaTeX, como `fontspec`, `ctex`, `xeCJK` ou `luatexko`. Se o arquivo principal não resolver, o Automático também confere um `latexmkrc` no projeto e os arquivos que o preâmbulo carrega. Todo o resto usa o pdfLaTeX. Se um pacote precisar de um compilador diferente do que o Automático escolheu, a compilação oferece a troca, por exemplo com **Usar XeLaTeX**.

Há duas formas de prover essa cadeia de ferramentas:

1. **Usar uma instalação existente.** O Oleafly detecta MacTeX, TeX Live, MiKTeX e TinyTeX no seu sistema. Ele procura no mesmo `PATH` que o seu terminal usa e, no Windows, também nas configurações `Path` do sistema e do usuário, então um TeX que você instalou à mão é encontrado mesmo quando o aplicativo foi aberto pelo Dock ou pelo menu Iniciar. Uma instalação do sistema tem prioridade sobre a cópia gerenciada do Oleafly somente quando o diretório de binários dela contém `latexmk`, pdfLaTeX, XeLaTeX, LuaLaTeX, `kpsewhich` e Biber. Uma instalação parcial não passa na frente de um TinyTeX gerenciado funcionando sem que você saiba.
2. **Instalar o TinyTeX gerenciado.** O download tem cerca de 250 MB e não precisa de acesso de administrador. Veja [Instalar e atualizar o TinyTeX](#install-and-update-tinytex).

**Gerenciar as distribuições TeX**, em **Configurações → Motores → LaTeX**, lista todas as distribuições que o Oleafly encontrou. **Em uso** marca aquela com que o `latexmk` compila, e um selo **latexmk** marca cada uma que pode compilar. Escolha **Usar nas compilações** em outra linha para passar a usá-la. A linha que você escolheu passa então a mostrar **Automático**, que deixa o Oleafly escolher de novo: primeiro um TeX completo do sistema, depois o TinyTeX.

Se o TeX está instalado em uma pasta onde o Oleafly não procura, clique em **Escolher uma pasta do TeX** e selecione a pasta que contém o `latexmk`, ou a pasta do ano do TeX Live que fica acima dela, como `texlive/2026`. O Oleafly encontra o `latexmk` lá dentro e compila com essa instalação, que a lista marca como **Em uso**. **Automático** desfaz a escolha. Se a pasta não tem `latexmk`, a mensagem diz qual pasta selecionar no lugar.

O `latexmk` não é um sandbox do sistema de arquivos. Mesmo com comandos de shell bloqueados, o TeX pode ler arquivos disponíveis para a sua conta. O Oleafly também desativa os arquivos `.latexmkrc` do projeto, do usuário e do sistema porque eles são Perl executável. Use o TeX do sistema apenas em projetos em que você confia. Um projeto importado usa o TeX do sistema só quando você o escolhe, seja como motor de compilação padrão, seja pelo menu de compilador do projeto. Uma pasta que você abre no próprio lugar fica no Tectonic até você confiar nela.

### Quando nenhum TeX está instalado

Escolher pdfLaTeX, XeLaTeX, LuaLaTeX, upLaTeX, pLaTeX ou Automático em um computador sem uma distribuição TeX que funcione abre um diálogo chamado **Este compilador precisa de uma distribuição TeX que funcione**. Ele mostra três opções, nesta ordem:

- **Baixar o TinyTeX**, marcada como **Recomendado**. **Baixar e usar o TinyTeX** instala o TinyTeX e compila o projeto com ele.
- **Usar o LaTeX do meu sistema (latexmk)**, que diz que nenhuma distribuição TeX foi encontrada, ou por que a deste computador não consegue compilar. Ela não tem botão.
- **Continuar usando o Tectonic**. **Voltar para o Tectonic** devolve o projeto ao motor embutido.

Se você compilar primeiro, a prévia oferece a mesma saída: **Baixar e usar o TinyTeX**, **Usar Tectonic** e **Abrir as configurações do motor**. Uma compilação que você inicia enquanto o TinyTeX ainda está sendo baixado espera e começa sozinha quando a instalação termina.

A mesma oferta aparece quando há uma distribuição TeX, mas sem `latexmk`. Quando falta à distribuição o `latexmk`, o compilador escolhido ou o Biber, a mensagem também diz o que instalar, se o Oleafly conhece a distribuição, como `sudo tlmgr install latexmk` no MacTeX ou `sudo apt install latexmk` no Ubuntu.

Em um projeto compartilhado, o botão diz **Usar Tectonic para todos**, porque o compilador fica salvo no projeto e muda para todos os colaboradores. Instalar o TinyTeX muda só o seu computador.

### Instalar e atualizar o TinyTeX

Abra **Configurações → Motores → LaTeX** e escolha **Baixar o TinyTeX (~250 MB)** em **Gerenciar as distribuições TeX**, ou use a oferta no diálogo de compilação. O TinyTeX é um TeX Live compacto que não precisa de direitos de administrador. Modelos de periódico podem acrescentar pacotes depois, chegando a cerca de 1 GB no total, e o Oleafly confere se há cerca de 2 GB de espaço livre em disco antes de começar. O TinyTeX é instalado em `~/.oleafly/tinytex`.

- **Cancelar** interrompe o download e guarda o que já chegou. O botão passa então a dizer **Retomar o download** com a quantidade já feita. Fechar o Oleafly durante a instalação a pausa do mesmo jeito, e ela continua na próxima vez que você abrir o aplicativo.
- O download vem primeiro do espelho do Oleafly e depois do GitHub. Se uma origem falha ou fica um minuto sem enviar dados, o Oleafly passa para a próxima e continua de onde parou. **Configurações → Downloads → Origens** muda de onde vêm os downloads. Veja [Aba Origens](/docs/settings/downloads/#sources-tab).
- Quando o TinyTeX gerenciado é mais antigo que a versão que esta versão do Oleafly espera, a linha dele mostra **Atualizar**. **Remover** o exclui.

Se outra distribuição já está **Em uso**, instalar o TinyTeX não troca para ele. Escolha **Usar nas compilações** na linha do TinyTeX quando quiser que ele compile.

No Linux, o TinyTeX roda com o Perl do sistema. O Oleafly confere se há Perl antes de baixar qualquer coisa. Se faltar o Perl ou um dos módulos padrão dele, a mensagem traz o comando para instalá-lo: `sudo apt install perl`, `sudo dnf install perl` ou `sudo pacman -S perl`.

No Windows, o TeX Live não roda a partir de uma pasta cujo nome tem letras acentuadas ou não latinas. Se a sua pasta de usuário tem um nome assim, o Oleafly coloca o TinyTeX em uma pasta dentro de ProgramData. Se o antivírus mantém um arquivo aberto enquanto o TinyTeX é movido para o lugar, o Oleafly tenta de novo, e se ainda assim não conseguir terminar, espere um momento e repita a instalação.

### MiKTeX e Perl

O `latexmk` do MiKTeX é um script Perl, e o MiKTeX não inclui o Perl. Sem o Perl, as Configurações marcam o MiKTeX com **o latexmk precisa do Perl**, e o Oleafly compila com o TinyTeX no lugar quando ele está instalado. Sem mais nada para usar, a compilação para e dá três caminhos: instalar o TinyTeX em **Configurações → Motores → LaTeX**, que traz o próprio Perl, instalar o Strawberry Perl, ou voltar o projeto para o Tectonic.

O MiKTeX gerencia os pacotes dele no MiKTeX Console, então a lista **Pacotes** e o **Localizar e instalar** não valem para ele. O MiKTeX também não converte figuras EPS durante a compilação, então converta-as para PDF antes ou use o TinyTeX.

### Documentos em japonês: upLaTeX e pLaTeX

Escolha **upLaTeX** ou **pLaTeX** em **Compilador (deste projeto)** para um documento em japonês, ou deixe o compilador em **Automático**. O Automático escolhe o pLaTeX para `jsarticle`, `jsbook` e `jsreport` (o upLaTeX quando a classe tem a opção `uplatex`), o upLaTeX para as classes `uj` e `jlreq`, e o LuaLaTeX para `ltjsarticle` e outros documentos LuaTeX-ja.

Os dois compiladores precisam do suporte a japonês do TeX Live. Quando ele falta no TinyTeX gerenciado, ou em um TeX Live em que o Oleafly pode gravar, a compilação que falhou oferece **Instalar suporte a japonês (cerca de 450 MB)**. Isso o instala e compila de novo. Em outras instalações, a mensagem cita o comando para a sua distribuição, como `sudo apt install texlive-lang-japanese`.

## Quando o Tectonic não é suficiente

Alguns documentos precisam de coisas que o motor Tectonic embutido não faz, como figuras EPS ou um driver `pdftex` forçado. Quando a primeira compilação depois de abrir um projeto, ou uma compilação que você inicia, esbarra em uma dessas, o diálogo de motor abre sozinho. Quando a Compilação automática ou um agente inicia a compilação, o diálogo continua fechado e **Escolher motor** aparece no lugar. Escolha-o para abrir o diálogo. O botão fica até a próxima compilação, então ele também reabre o diálogo depois de você fechá-lo. Onde encontrá-lo depende da visualização:

- Depois de uma compilação que falhou, ele fica à direita da barra de ferramentas da prévia enquanto **Logs** está aberto. A prévia muda para **Logs** sozinha quando a compilação não gerou PDF. Se um PDF ainda está aparecendo, escolha **Logs** para ver o botão.
- Em uma prévia vazia, ele fica ao lado de **Compilar de novo**.
- Na visualização só com o editor, quando o PDF está em uma janela própria, ou depois de uma compilação bem-sucedida, ele fica à esquerda de **Compilar de novo**.

O diálogo se chama **Esta compilação precisa de mais do que o motor embutido** e lista os problemas que encontrou. A opção marcada como **Recomendado** vem primeiro:

- **Baixar o TinyTeX** aparece quando nenhuma distribuição TeX que funcione está instalada. O botão dela, **Baixar e usar o TinyTeX**, instala o TinyTeX, passa o projeto para o `latexmk` e compila de novo.
- **Usar o LaTeX do meu sistema (latexmk)** tem **Usar o LaTeX do sistema**, que passa o projeto para o `latexmk` na distribuição TeX que o Oleafly encontrou. Se o documento precisa de pdfLaTeX, a opção diz **Usar o pdfLaTeX no LaTeX do meu sistema (latexmk)** e o botão dela diz **Mudar para pdfLaTeX e compilar de novo**. Sem nenhum TeX instalado, essa opção não tem botão.
- **Continuar usando o Tectonic** tem **Continuar com o Tectonic**, que deixa o projeto no motor embutido. Quando uma troca resolveria os problemas que o diálogo lista, essa opção diz que eles não vão desaparecer.

Depois que você continua com o Tectonic, os mesmos problemas deixam de abrir o diálogo ou de mostrar **Escolher motor** neste projeto, neste computador. Para trocar depois, escolha um compilador em **Compilador (deste projeto)**.

Se o projeto também precisa executar comandos externos, trocar para o LaTeX do sistema ou para o TinyTeX os permite também, e o diálogo avisa isso antes de você clicar. O compilador que você escolhe fica gravado no projeto, então os colaboradores têm a mesma configuração.

## Permitir comandos externos

Pacotes como `minted` e PythonTeX, e documentos que usam `\write18`, executam outros programas enquanto compilam. O Oleafly bloqueia isso por padrão. Quando uma compilação é bloqueada, ou o log mostra que o projeto precisa desses comandos, um banner acima do editor oferece **Permitir comandos externos**.

O motor integrado mantém esse bloqueio também. O Tectonic inicia fora da pasta do projeto, e o Biber que acompanha o Oleafly trata as configurações de bibliografia de um documento como texto simples e ignora o `biber.conf` durante uma compilação.

Permita comandos externos apenas em um projeto cujos arquivos você confia, porque o LaTeX pode então executar qualquer programa com as suas permissões. A permissão funciona só com o LaTeX do sistema e fica neste computador. Ela nunca é gravada no `project.json` nem entra em commits do Git, então um coautor precisa permitir isso no próprio computador. Em um [projeto compartilhado](/docs/collaboration/), o Oleafly avisa antes de ativá-la, porque qualquer pessoa que pode editar o projeto poderia então executar programas no seu computador quando você compila. Trocar o projeto de volta para o Tectonic ou excluí-lo remove a permissão. Em uma pasta aberta no próprio lugar, confie na pasta primeiro. Confiar em uma pasta não permite comandos externos por si só.

Com um motor presente, o botão **Compilar com marcação e conferir** do painel de [Pré-verificação](/docs/preflight/) pode produzir um PDF marcado com LuaLaTeX e auditá-lo de imediato, em uma etapa só. Prefere a sua própria cadeia de ferramentas? A opção **Preparar para exportação acessível** da Pré-verificação reescreve o seu código-fonte para marcação e você o compila com qualquer LuaLaTeX do TeX Live 2026, ou de um TeX Live atualizado desde novembro de 2025, fora do aplicativo.

## Caracteres ausentes no PDF

O TeX deixa de fora qualquer caractere para o qual a fonte não tem glifo, e a compilação ainda assim termina com sucesso. Um parágrafo em coreano, chinês ou japonês pode sair em branco, sem erro. O Oleafly lê o log depois de cada compilação, então, quando faltam caracteres, você recebe um aviso uma vez por projeto, o log os lista em **Caracteres ausentes**, e o aviso cita alguns deles.

No motor embutido e no XeLaTeX, o aviso também traz uma configuração para cada escrita que encontrou, com fontes que vêm com o motor embutido. Cole a que você precisa no preâmbulo:

```latex
% Korean
\usepackage[space]{xeCJK}
\setCJKmainfont[AutoFakeBold]{UnBatang.ttf}

% Simplified Chinese
\usepackage{xeCJK}
\setCJKmainfont[AutoFakeBold]{gbsn00lp.ttf}

% Traditional Chinese
\usepackage{xeCJK}
\setCJKmainfont[AutoFakeBold]{bsmi00lp.ttf}

% Japanese
\usepackage{xeCJK}
\setCJKmainfont{ipaexm.ttf}[BoldFont=ipaexg.ttf]
```

A opção `space` mantém os espaços entre as palavras em coreano, que o `xeCJK` puro descarta.

O `CJKutf8` e o pacote `CJK` só funcionam no pdfLaTeX. Um projeto que os carrega no motor embutido compila sem o texto em chinês, japonês ou coreano, então o aviso oferece **Escolher motor**, que abre a troca para o pdfLaTeX. Você também pode remover o pacote e o ambiente `CJK` dele e usar uma das configurações acima.

Um documento `ctex` em um Mac que usa as fontes do próprio Mac pode fazer o macOS perguntar se deve baixar uma fonte, e a compilação espera a sua resposta. Responda ao diálogo e compile de novo, ou acrescente `fontset=fandol` às opções do `\documentclass`.

Outros caracteres ausentes, como um símbolo ou uma letra de outra escrita, precisam de uma fonte que os tenha. Troque por uma no preâmbulo. Para projetos Typst, veja [Caracteres que aparecem como caixas](/docs/typst/#characters-that-show-as-boxes).

## O gerenciador de pacotes

Abaixo do status do motor fica uma lista filtrável de **Pacotes** para o lado do LuaLaTeX, movida pelo `tlmgr`:

- Comece pela lista de pacotes sugeridos, ou digite pelo menos dois caracteres e escolha **Buscar no TeX Live** para consultar o catálogo completo.
- Busque pelo nome de um pacote ou por um arquivo que ele contém. O Oleafly mostra o pacote do TeX Live ao qual o arquivo pertence quando os nomes são diferentes.
- **Adicionar** ou **Remover** um pacote com um clique. As linhas de pacotes instalados mostram se o pacote está na árvore do sistema, na sua árvore pessoal ou nas duas.
- Confira o selo de marcação antes de uma exportação acessível: **marcação: atenção** sinaliza pacotes que podem reduzir a qualidade das marcações, e **quebra a marcação** sinaliza conflitos conhecidos.

Este gerenciador de pacotes vale para as distribuições TeX Live e TinyTeX usadas pelo `latexmk`. O Tectonic gerencia o próprio cache de pacotes. Para o MiKTeX, use o MiKTeX Console.

### Recuperar de um arquivo ausente

Um pacote nem sempre tem o nome do arquivo mencionado em um log de compilação. Por exemplo, o `tikz.sty` é instalado pelo pacote `pgf`. Instalar um pacote adivinhado chamado `tikz` falharia.

Quando uma compilação do `latexmk` relata um arquivo ausente, use **Localizar e instalar** na mensagem. Isso cobre pacotes, classes, estilos de bibliografia, arquivos de fonte, arquivos de idioma do babel e bibliotecas TikZ. O Oleafly pergunta ao TeX Live a qual pacote o arquivo pertence, instala esse pacote e compila de novo. Se nenhum pacote do TeX Live tem o arquivo, ele provavelmente veio com o modelo da sua universidade ou da editora, então acrescente-o ao projeto a partir do modelo original. Se vários pacotes o têm, a mensagem os lista para você escolher o que o seu modelo precisa. Se o catálogo não puder ser alcançado, ou se a instalação não resolver a compilação, a mensagem diz qual dos dois ocorreu.

Se você tentar alterar uma instalação do sistema sem permissão, o Oleafly pode instalar na sua árvore pessoal de TeX, e prepara essa árvore antes quando ela ainda não existe. A linha do pacote mostra onde ele parou. Remover o pacote proprietário também remove os outros arquivos que ele fornece, então leia a nota **Faz parte de** antes de removê-lo.

### Manter o tlmgr e versões antigas do TeX Live funcionando

O `tlmgr`, o gerenciador de pacotes do TeX Live, pode ficar atrás do repositório online do TeX Live e então se recusa a instalar qualquer coisa até se atualizar. No TinyTeX que o Oleafly gerencia, o Oleafly atualiza o `tlmgr` e repete a instalação. Em um TeX Live ou TinyTeX que você instalou por conta própria, a mensagem manda você executar `tlmgr update --self`.

Quando o repositório passa para um novo ano do TeX Live, uma instalação mais antiga não consegue instalar a partir dele. O Oleafly então instala a partir do arquivo final da sua versão. Se o arquivo também não tem o pacote, a mensagem pede que você atualize o TeX Live, ou use **Atualizar** no TinyTeX gerenciado, nas Configurações.

### Escolha de onde vêm os pacotes

O `tlmgr` instala pacotes a partir de um repositório do TeX Live. O TinyTeX que o Oleafly gerencia usa o espelho CTAN mais próximo, a menos que você escolha um repositório específico, como o espelho CTAN da sua universidade, em **Repositório de pacotes TeX**, em **Configurações → Downloads → Origens**. Um TeX Live que você instalou por conta própria mantém o próprio repositório, a menos que você digite um endereço ali. O Oleafly passa o endereço ao `tlmgr` a cada execução e nunca muda a configuração salva dele.

Uma busca de pacote que precisa alcançar o repositório pode demorar em uma conexão lenta. O Oleafly espera até 10 minutos e, se desiste, a mensagem nomeia o repositório que ele estava esperando. Veja [Aba Origens](/docs/settings/downloads/#sources-tab).

### TeX Live de uma distribuição Linux

No Debian, no Ubuntu e no Fedora, o TeX Live vem do gerenciador de pacotes do sistema, então o Oleafly não acrescenta pacotes a ele. A lista **Pacotes** manda usar `apt` ou `dnf`, e um arquivo ausente recebe um aviso com uma dica no lugar de **Localizar e instalar**:

- No Debian e no Ubuntu, encontre o pacote com `apt-file search` e o nome do arquivo, ou instale tudo com `sudo apt install texlive-full`.
- No Fedora, o aviso traz um comando `sudo dnf install 'tex(file.sty)'` para o arquivo ausente.

Quando o TeX da distribuição está incompleto, o aviso também oferece **Baixar o TinyTeX (~250 MB)**, cujos pacotes o Oleafly consegue gerenciar. No Debian e no Ubuntu, se você montou uma árvore pessoal com `tlmgr init-usertree`, o Oleafly instala os pacotes nessa árvore.

## Adicionar um pacote pelo editor

Escolha **Pacotes LaTeX**, o ícone de pacote na barra de ferramentas do editor LaTeX, para buscar no CTAN sem sair do documento. Cada resultado mostra se o documento já o carrega (**No documento**). Em um projeto `latexmk`, ele também mostra se a sua distribuição TeX o tem (**Instalado**), e **Instalar** acrescenta um que falta com o `tlmgr`. Com o TeX Live de uma distribuição Linux, o diálogo manda instalar os pacotes com `apt` ou `dnf`.

**Adicionar ao preâmbulo** escreve a linha `\usepackage` no preâmbulo. **Opções** deixa você adicionar opções de pacote antes, e **Copiar linha** copia a linha no lugar. Um projeto Tectonic não tem nada para instalar: o Tectonic baixa um pacote na primeira vez que o documento o usa.

## Qual motor compilou o meu PDF?

- **Compilador (deste projeto)**, no menu de compilação, a seta ao lado de **Compilar de novo**, mostra o compilador salvo para o projeto atual.
- Builds do Tectonic usam o motor embutido.
- Builds de pdfLaTeX, XeLaTeX, LuaLaTeX, upLaTeX e pLaTeX usam o `latexmk` e a distribuição TeX marcada como **Em uso** nas Configurações.
- A exportação marcada da Pré-verificação usa o LuaLaTeX e grava no local de build normal.

## Modelos e pacotes

Os modelos declaram os pacotes de que precisam, e o Tectonic os obtém na primeira compilação. Modelos com fontes sob demanda tratam delas separadamente. Veja [Modelos](/docs/templates/#on-demand-fonts-the-setup-badge).
