por Tiago Silva

Este documento mostra como configurar o LaTeX no VS Code no Windows e organizar um projeto a partir do template IEEE, com figuras, bibliografia e arquivos de compilação separados.

As ferramentas utilizadas são:

  • MiKTeX: distribuição LaTeX que fornece e gerencia os componentes necessários para a produção em LaTeX, incluindo mecanismos de compilação, pacotes, fontes e ferramentas auxiliares. Entre esses componentes estão:

    • pdfLaTeX e XeLaTeX: mecanismos de compilação que processam o código-fonte .tex e geram o documento final, normalmente em PDF.

    • BibTeX e Biber: ferramentas responsáveis pelo processamento das referências bibliográficas.

    • latexmk: ferramenta que coordena e automatiza o processo de compilação, executando os mecanismos de compilação e as ferramentas auxiliares quando necessário.

  • Strawberry Perl: distribuição do interpretador Perl para Windows. É necessária para executar o latexmk, que é escrito em Perl.

  • VS Code + extensão LaTeX Workshop: integra o VS Code às ferramentas LaTeX fornecidas pelo MiKTeX, permitindo executar a compilação e acompanhar seus resultados diretamente pela interface do editor.

Instalar os três programas é necessário, mas não garante sozinho que tudo funcione. O MiKTeX precisa concluir sua configuração inicial, latexmk e perl precisam estar no PATH, e o VS Code deve ser iniciado depois dessas alterações.

1. Entenda o papel de cada componente

A extensão LaTeX Workshop não inclui uma distribuição LaTeX e, portanto, não compila o documento por conta própria. Ela executa uma recipe de compilação, que define quais ferramentas serão chamadas e em que sequência.

Uma recipe pode, por exemplo, chamar o latexmk. Nesse caso, o latexmk executa o mecanismo de compilação, como pdfLaTeX ou XeLaTeX, chama ferramentas auxiliares, como BibTeX ou Biber, quando necessário, e realiza novas compilações até que referências cruzadas, citações, sumário e outros elementos dependentes de compilações anteriores estejam atualizados.

Os mecanismos de compilação mais comuns são pdfLaTeX e XeLaTeX. Ambos processam o arquivo .tex e podem gerar diretamente um documento PDF. A principal diferença prática está no tratamento de fontes e Unicode:

  pdfLaTeX XeLaTeX
Fontes utiliza principalmente fontes do ecossistema TeX pode utilizar diretamente fontes instaladas no sistema
Unicode aceita entrada UTF-8, mas possui limitações relacionadas ao modelo tradicional de fontes e codificações do TeX possui suporte nativo a Unicode e fontes OpenType/TrueType
Comando com latexmk latexmk -pdf latexmk -xelatex

O código-fonte do documento pode permanecer essencialmente o mesmo, mas a escolha do mecanismo depende das fontes, dos pacotes e dos requisitos do projeto.

No MiKTeX, o latexmk é um script escrito em Perl. Como o MiKTeX não fornece um interpretador Perl, é necessário instalar separadamente um ambiente Perl, como o Strawberry Perl, para executá-lo no Windows.

O fluxo esperado é:

VS Code / LaTeX Workshop
          |
          v
       latexmk -- Perl
          |
          +--> pdfLaTeX ou XeLaTeX
          +--> BibTeX ou Biber, quando necessário
          +--> novas execuções do compilador selecionado
          |
          v
         PDF

2. Instale o MiKTeX

  1. Baixe o Basic MiKTeX Installer em https://miktex.org/download.
  2. Execute o instalador.
  3. Quando perguntado, prefira a instalação privada, somente para o usuário atual. Ela normalmente evita conflitos de permissões.
  4. Mantenha o diretório sugerido pelo instalador.
  5. Selecione papel A4.

  6. Em instalação automática de pacotes ausentes, selecione:

    • Always, opção mais prática para iniciantes; ou
    • Ask me first, se quiser aprovar cada pacote.

    Não selecione Never em uma instalação básica, pois muitos documentos dependem de pacotes que serão obtidos apenas na primeira compilação.

  7. Aguarde o instalador chegar à tela final. Não interrompa o processo quando os arquivos parecerem já ter sido copiados.
  8. Abra MiKTeX Console pelo menu Iniciar, ainda antes de abrir o VS Code.

  9. Em Updates:

    1. clique em Check for Updates;
    2. se houver atualizações, clique em Update now;
    3. repita a consulta até não haver atualizações pendentes.

  10. Em Settings > General, confirme:

    • papel A4;
    • instalação de pacotes ausentes como Always ou Ask me.

Se uma instalação anterior foi interrompida, use também Tasks > Refresh file name database. Essa tarefa normalmente não é necessária em uma instalação nova concluída corretamente, mas recompõe o índice de arquivos do MiKTeX.

3. Instale o Strawberry Perl

  1. Acesse https://strawberryperl.com/releases.html.
  2. Execute o instalador e mantenha o diretório padrão. Normalmente ele será semelhante a C:\Strawberry.
  3. Conclua a instalação.

O instalador normalmente inclui no PATH diretórios como:

C:\Strawberry\perl\bin
C:\Strawberry\perl\site\bin
C:\Strawberry\c\bin

4. Valide o ambiente antes de abrir o VS Code

Abra uma nova janela do PowerShell. Não reutilize um terminal que já estava aberto durante as instalações.

Execute:

$programas = 'pdflatex', 'xelatex', 'bibtex', 'latexmk', 'perl'

foreach ($programa in $programas) {
    $comando = Get-Command $programa -ErrorAction SilentlyContinue
    if ($null -eq $comando) {
        Write-Host "[FALHOU] $programa não foi encontrado" -ForegroundColor Red
    }
    else {
        Write-Host "[OK] $programa -> $($comando.Source)" -ForegroundColor Green
    }
}

Os cinco itens precisam aparecer como [OK]. Depois verifique se os programas realmente iniciam:

pdflatex --version
xelatex --version
bibtex --version
latexmk -v
perl --version

Na primeira execução de latexmk -v, o MiKTeX pode instalar o pacote correspondente. Aguarde a conclusão.

Por fim, consulte o estado do MiKTeX:

initexmf --report | Select-String 'SetupDate|PathOkay|UserInstall'

O resultado saudável contém:

SetupDate: uma data, e não "not yet"
PathOkay: yes
UserInstall: diretório real da instalação

Somente prossiga quando esses testes funcionarem.

5. Corrija o PATH, se algum comando não for encontrado

O PATH deve conter os diretórios dos executáveis, não os nomes dos arquivos .exe.

Instalações privadas do MiKTeX costumam usar:

C:\Users\SEU_USUARIO\AppData\Local\Programs\MiKTeX\miktex\bin\x64

Instalações compartilhadas podem usar:

C:\Program Files\MiKTeX\miktex\bin\x64

O Strawberry Perl normalmente usa:

C:\Strawberry\perl\bin
C:\Strawberry\perl\site\bin
C:\Strawberry\c\bin

Para corrigir no Windows:

  1. pesquise por Editar as variáveis de ambiente da sua conta;
  2. selecione a variável Path do usuário;
  3. clique em Editar e depois em Novo;
  4. adicione somente os diretórios que existirem no computador;
  5. não apague as entradas que já estavam no Path;
  6. confirme todas as janelas;
  7. feche e reabra PowerShell e VS Code.

Se o MiKTeX estiver no caminho privado padrão, também é possível solicitar que ele próprio registre seu diretório:

& "$env:LOCALAPPDATA\Programs\MiKTeX\miktex\bin\x64\initexmf.exe" --modify-path

Depois disso, abra outro PowerShell e repita todos os testes da seção anterior.

Para verificar se existem instalações concorrentes, execute:

where.exe pdflatex
where.exe xelatex
where.exe latexmk
where.exe perl

Se houver mais de um resultado para pdflatex, xelatex ou latexmk, o primeiro caminho é o programa que será usado. Ajuste a ordem do Path para manter uma única distribuição LaTeX como principal.

6. Instale o VS Code e o LaTeX Workshop

  1. Instale ou atualize o VS Code por https://code.visualstudio.com/download.
  2. Abra o VS Code após validar o PATH.
  3. Abra a tela de extensões com Ctrl+Shift+X.
  4. Procure por LaTeX Workshop.
  5. Confirme que o identificador é James-Yu.latex-workshop e instale a extensão oficial: https://marketplace.visualstudio.com/items?itemName=james-yu.latex-workshop.

Não é necessário criar uma receita personalizada se os testes do PowerShell funcionaram. O LaTeX Workshop já inclui receitas baseadas em latexmk para pdfLaTeX e XeLaTeX.

7. Teste pdfLaTeX e XeLaTeX no VS Code

Crie uma pasta vazia e abra a pasta no VS Code por File > Open Folder. Os exemplos a seguir são independentes: use apenas o compilador adequado ao seu projeto.

7.1. Exemplo mínimo com pdfLaTeX

Crie main.tex:

% !LW recipe = latexmk
\documentclass[a4paper,12pt]{article}

\usepackage[T1]{fontenc}
\usepackage[brazilian]{babel}

\begin{document}

Documento compilado com pdfLaTeX.

\end{document}

Teste pelo terminal integrado:

latexmk -pdf -interaction=nonstopmode -file-line-error main.tex

7.2. Exemplo mínimo com XeLaTeX

Substitua o conteúdo de main.tex por:

% !LW recipe = latexmk (xelatex)
\documentclass[a4paper,12pt]{article}

\usepackage{fontspec}
\setmainfont{Times New Roman}
\usepackage[brazilian]{babel}

\begin{document}

Documento compilado com XeLaTeX e uma fonte instalada no Windows.

\end{document}

Teste pelo terminal integrado:

latexmk -xelatex -interaction=nonstopmode -file-line-error main.tex

Se a fonte indicada em \setmainfont não estiver instalada, escolha outra fonte disponível no Windows. Não use fontspec com pdfLaTeX.

7.3. Informe o compilador ao LaTeX Workshop

As primeiras linhas dos exemplos selecionam receitas que já acompanham o LaTeX Workshop:

% !LW recipe = latexmk

seleciona pdfLaTeX, enquanto:

% !LW recipe = latexmk (xelatex)

seleciona XeLaTeX.

Com main.tex ativo, pressione Ctrl+Alt+B ou execute LaTeX Workshop: Build LaTeX project. A extensão lê a receita indicada no arquivo e chama o latexmk com o compilador correspondente.

Também é possível escolher manualmente:

  1. execute LaTeX Workshop: Build with recipe na paleta de comandos;
  2. escolha latexmk para pdfLaTeX ou latexmk (xelatex) para XeLaTeX.

A escolha manual vale para aquela compilação. A indicação % !LW recipe continua no arquivo e torna a escolha reproduzível para outros usuários.

O comando LaTeX Workshop: View LaTeX PDF não escolhe o compilador. Ele apenas abre o PDF produzido pelo último Build, procurando-o no diretório de saída configurado.

Na primeira compilação, permita que o MiKTeX instale os pacotes ausentes e aguarde. As compilações seguintes serão muito mais rápidas.

7.4. Teste bibliografia com qualquer um dos compiladores

Para verificar também o BibTeX, acrescente ao documento, antes de \end{document}, uma citação e a bibliografia:

Segundo \cite{knuth1984}, a composição tipográfica pode ser automatizada.

\bibliographystyle{plain}
\bibliography{references}

Crie references.bib na mesma pasta:

@book{knuth1984,
  author    = {Donald E. Knuth},
  title     = {The TeXbook},
  publisher = {Addison-Wesley},
  year      = {1984}
}

Execute novamente o comando latexmk correspondente. Ele deve chamar o compilador selecionado, o BibTeX e as recompilações necessárias, terminando com uma mensagem semelhante a All targets are up-to-date.

8. Configuração opcional para colocar a saída em build

Depois de confirmar que a configuração padrão funciona, crie .vscode/settings.json dentro do projeto se quiser separar PDF e arquivos auxiliares:

{
  "latex-workshop.latex.outDir": "%DIR%/build",
  "latex-workshop.latex.auxDir": "%OUTDIR%"
}

Essa configuração é portátil e pode ser compartilhada no repositório, pois não contém nomes de usuário nem caminhos específicos do computador.

O settings.json configura apenas o LaTeX Workshop. Ao compilar pelo terminal, acrescente -outdir=build aos comandos anteriores para gerar a saída na mesma pasta. Por exemplo:

latexmk -pdf -interaction=nonstopmode -file-line-error -outdir=build main.tex

9. Receita de emergência para um PATH que não pode ser alterado

Use esta solução apenas em computadores corporativos ou ambientes nos quais não seja possível corrigir o PATH global. Substitua SEU_USUARIO e confirme que todos os diretórios existem:

{
  "latex-workshop.latex.recipe.default": "first",
  "latex-workshop.latex.recipes": [
    {
      "name": "latexmk",
      "tools": ["latexmk-pdf-miktex"]
    },
    {
      "name": "latexmk (xelatex)",
      "tools": ["latexmk-xe-miktex"]
    }
  ],
  "latex-workshop.latex.tools": [
    {
      "name": "latexmk-pdf-miktex",
      "command": "C:/Users/SEU_USUARIO/AppData/Local/Programs/MiKTeX/miktex/bin/x64/latexmk.exe",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-pdf",
        "-outdir=%OUTDIR%",
        "-auxdir=%AUXDIR%",
        "%DOC%"
      ],
      "env": {
        "Path": "C:/Users/SEU_USUARIO/AppData/Local/Programs/MiKTeX/miktex/bin/x64;C:/Strawberry/perl/bin;C:/Strawberry/perl/site/bin;C:/Strawberry/c/bin;C:/Windows/System32;C:/Windows"
      }
    },
    {
      "name": "latexmk-xe-miktex",
      "command": "C:/Users/SEU_USUARIO/AppData/Local/Programs/MiKTeX/miktex/bin/x64/latexmk.exe",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-xelatex",
        "-outdir=%OUTDIR%",
        "-auxdir=%AUXDIR%",
        "%DOC%"
      ],
      "env": {
        "Path": "C:/Users/SEU_USUARIO/AppData/Local/Programs/MiKTeX/miktex/bin/x64;C:/Strawberry/perl/bin;C:/Strawberry/perl/site/bin;C:/Strawberry/c/bin;C:/Windows/System32;C:/Windows"
      }
    }
  ]
}

No Windows, use Path nessa configuração. Não escreva %PATH%, $PATH ou ${env:PATH} esperando que sejam expandidos dentro da propriedade env: o LaTeX Workshop não expande essas variáveis ali.

Essas receitas contêm caminhos específicos da máquina. Portanto, prefira colocá-las nas configurações locais do usuário ou não versionar o arquivo.

10. Entenda as extensões dos arquivos LaTeX

Arquivo Função Como usar
.tex Código-fonte do documento: texto, comandos, equações e chamadas de figuras. Edite o arquivo principal, como main.tex.
.cls Classe que define a estrutura e a apresentação do documento. \documentclass[conference]{IEEEtran} carrega IEEEtran.cls.
.sty Pacote que acrescenta recursos ao LaTeX. \usepackage{graphicx} carrega graphicx.sty, geralmente instalado pelo MiKTeX.
.bib Base de referências com autores, títulos, anos e outros campos. Cadastre suas fontes em referencias.bib.
.bst Estilo usado pelo BibTeX para formatar e ordenar a bibliografia. \bibliographystyle{IEEEtran} seleciona IEEEtran.bst.

Os arquivos .cls e .bst se complementam: um define o documento; o outro, a bibliografia. Manter os arquivos fornecidos pelo template junto de main.tex facilita compartilhar o projeto. Os demais pacotes continuam sendo fornecidos pela distribuição LaTeX.

Durante a compilação, também aparecem arquivos que você normalmente não edita:

Extensão Conteúdo
.aux Informações de referências cruzadas e citações usadas nas próximas etapas.
.bbl Bibliografia formatada pelo BibTeX, que será incorporada ao documento.
.blg Registro do processamento da bibliografia.
.log Registro da compilação LaTeX, incluindo erros e avisos.
.fls e .fdb_latexmk Arquivos lidos/gerados e informações usadas pelo latexmk para decidir o que recompilar.
.synctex.gz Dados de sincronização entre o código-fonte e a posição correspondente no PDF.
.toc, .lof e .lot Dados do sumário e das listas de figuras e tabelas, quando utilizados.

Esses arquivos podem ser regenerados a partir das fontes. Em uma submissão, confira as instruções do evento: alguns fluxos também solicitam o .bbl.

11. Exemplo de organização com o template IEEE

O IEEE Author Center disponibiliza modelos para conferências. O arquivo IEEEtran.cls vem do template LaTeX, e IEEEtran.bst, do pacote de bibliografia (neste exemplo, IEEEtranBST2.zip). Coloque ambos na mesma pasta de main.tex.

Uma organização possível da estrutura de arquivos seria, por exemplo:

artigo/
├── main.tex
├── IEEEtran.cls
├── IEEEtran.bst
├── referencias.bib
├── .gitignore
├── .vscode/
│   └── settings.json
├── figures/
│   └── fig1.png
└── build/

Ao mover fig1.png para figures/, atualize a chamada no template para que o LaTeX encontre a imagem:

\includegraphics{figures/fig1.png}

Troque as referências manuais por BibTeX

O template usado aqui contém um ambiente thebibliography, com entradas \bibitem. Para adotar um arquivo .bib, migre os dados dessas referências e substitua todo o ambiente pelas duas linhas abaixo, antes de \end{document}:

\bibliographystyle{IEEEtran}
\bibliography{referencias}

Não acrescente outra seção \section*{References} para a lista: a bibliografia já gera o título. Remova também o texto de instrução do template ao escrever seu artigo.

Este é um exemplo mínimo de referencias.bib, usando uma das fontes presentes no template:

@book{young1989,
  author    = {M. Young},
  title     = {The Technical Writer's Handbook},
  address   = {Mill Valley, CA},
  publisher = {University Science},
  year      = {1989}
}

No texto, cite a chave da entrada:

A escrita técnica exige atenção à apresentação das informações \cite{young1989}.

Um main.tex mínimo para testar essa base é:

% !LW recipe = latexmk
\documentclass[conference]{IEEEtran}
\usepackage[T1]{fontenc}
\usepackage{cite}
\usepackage{graphicx}
\usepackage{url}

\begin{document}

\title{Exemplo de artigo}
\author{\IEEEauthorblockN{Nome do autor}
\IEEEauthorblockA{Instituição}}
\maketitle

\begin{abstract}
Exemplo mínimo para testar a organização do projeto e a bibliografia.
\end{abstract}

\section{Introdução}
A escrita técnica exige atenção à apresentação das informações \cite{young1989}.

\bibliographystyle{IEEEtran}
\bibliography{referencias}
\end{document}

Esse exemplo testa a estrutura; para redigir o artigo, use o template completo e as instruções da publicação. Substitua as referências ilustrativas pelas fontes efetivamente utilizadas.

Se suas entradas usarem as abreviações definidas em IEEEabrv.bib, copie também esse arquivo para a raiz e troque a chamada por \bibliography{IEEEabrv,referencias}. Sem essas abreviações, basta \bibliography{referencias}.

Este fluxo usa BibTeX com um estilo .bst. Projetos com biblatex e Biber usam outra configuração; não misture os dois fluxos neste exemplo.