Pular para o conteúdo
Oleaflyv0.4.12

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.

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.

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.

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:

    \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.

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.

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.

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.

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.
  • 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.

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.

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.

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.

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, 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 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.

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:

% 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.

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.

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

Seção intitulada “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.

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.

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.

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.

  • 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.

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.

Visualização da imagem

Não foi possível carregar as respostas da IA

Tente de novo ou pesquise na documentação.