# Compilación

Compila proyectos de LaTeX, Typst y Markdown, elige las opciones de compilación de cada motor, lee los registros y controla la descarga de paquetes sin conexión.

Un proyecto de LaTeX nuevo empieza con el motor de compilación predeterminado de **Ajustes → Motores → LaTeX**. De fábrica es **Tectonic**, un motor basado en XeTeX que viene con Oleafly. También puedes usar `latexmk` cuando un proyecto necesite una cadena de herramientas de TeX tradicional, para un proyecto o como motor predeterminado. Los proyectos de Typst se compilan con el Typst incluido u otra versión que el proyecto fije, y los proyectos de Markdown pasan por Pandoc y Tectonic. El compilador de LaTeX y la versión de Typst pertenecen al proyecto, así que cambiar uno no afecta a los demás.

## Iniciar una compilación

![Usa Recompilar en la barra de herramientas del proyecto; la flecha que hay a su lado abre las opciones de compilación.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1265,0,330,48)

- ⌘↵ (Ctrl+Enter), desde cualquier sitio.
- El botón **Compilar** en la parte superior derecha de la barra de herramientas. Pasa a decir **Recompilar** cuando el proyecto ya tiene un resultado.
- **Recompilar** en la paleta de comandos ⌘K.
- Abrir un proyecto en una vista que muestra el panel del PDF lo compila una vez automáticamente, para que llegues a una vista previa actualizada.
- `oleafly build` en un terminal o en un script. Consulta [Herramienta de línea de comandos](/docs/cli/).

Compilar siempre guarda primero el archivo activo, así que el PDF coincide con lo que ves. Si estás en la vista solo con el editor, compilar muestra la vista dividida para que puedas ver el resultado.

## Opciones de compilación

La flecha junto a **Recompilar** abre las opciones de compilación. El menú muestra solo las opciones que hacen algo para el motor del proyecto.

| Grupo | LaTeX con Tectonic | LaTeX con `latexmk` | Typst | Markdown |
|---|---|---|---|---|
| **Compilación automática** | Sí | Sí | Sí | Sí |
| **Modo de compilación** (Normal o Rápida) | Sí | No | No | No |
| **Revisión de sintaxis** | Sí | Sí | No | No |
| **Compilador (este proyecto)** | Sí | Sí | No | No |
| **Versión de Typst**, **Tipografías**, **Compilación**, **Variante** | No | No | Sí | No |
| **Tratamiento de los errores de compilación** | Sí | Sí | No | No |

**Detener la compilación** y **Recompilar desde cero** están al final del menú para todos los motores. El grupo **Variante** aparece cuando un proyecto de Typst tiene variantes de compilación.

En **Compilador (este proyecto)**, **Tectonic** viene incluido. **Automático** ejecuta el TeX de tu sistema mediante `latexmk` y elige el compilador a partir del código fuente. **pdfLaTeX**, **XeLaTeX** y **LuaLaTeX** fijan ese compilador y también se ejecutan mediante `latexmk`, y **upLaTeX** y **pLaTeX** compilan documentos en japonés. Todas las opciones salvo Tectonic necesitan una distribución de TeX. Si este equipo no tiene ninguna, Oleafly ofrece instalar TinyTeX cuando eliges una. Consulta [Cuando no hay TeX instalado](/docs/latex-engines/#when-no-tex-is-installed). Los grupos de Typst se explican en [Proyectos de Typst](/docs/typst/).

## Compilación automática

Pon **Compilación automática** en **Activada** en las opciones de compilación, o ejecuta **Activar la compilación automática** desde la paleta ⌘K. Está desactivada por defecto, se aplica a todos los proyectos y los mismos controles la vuelven a desactivar.

En un proyecto de LaTeX o Markdown, Oleafly recompila unos 2,5 segundos después de que dejes de escribir. Solo la activan ediciones reales. Cambiar de pestaña o abrir archivos no.

En un proyecto de Typst, la compilación automática es la vista previa en vivo. Oleafly mantiene un proceso de Typst en marcha, el archivo abierto se guarda solo un momento después de que dejes de escribir y el PDF se actualiza en la misma posición de desplazamiento. Consulta [Vista previa en vivo con la compilación automática](/docs/typst/#live-preview-with-auto-compile).

Las compilaciones nunca se acumulan. Si editas mientras se ejecuta una compilación automática, Oleafly la detiene y empieza de nuevo con tu texto más reciente, de modo que el PDF se pone al día antes. Deja terminar una compilación cuando la iniciaste tú o un agente, cuando está descargando paquetes, cuando está casi terminada o cuando ya es un reinicio. En esos casos se pone en cola exactamente una compilación de seguimiento, así que el PDF final sigue reflejando tus últimas ediciones.

## Seguir el progreso

Una barra de progreso fina recorre la parte superior de la vista previa durante una compilación, y antes de que exista el primer PDF el panel muestra una estimación en porcentaje. Cuando termina una compilación, la barra de herramientas muestra un **indicador de estado** con el tiempo de compilación y un icono de gravedad:

- Marca verde: compilado correctamente.
- Triángulo ámbar: compilado con advertencias. Sigues obteniendo el PDF.
- Cruz roja: compilado con errores.

La vista previa pasa al PDF automáticamente si todo va bien. Solo un fallo real (sin PDF generado) te lleva a la vista de Registros.

![Una compilación fallida marcada en el editor y en el registro, y luego corregida y compilada de nuevo.](https://cdn.oleafly.com/images/gifs/desktop/compile-errors.gif?v=2)

## Leer los registros

![Los registros y la duración de la última compilación están a la izquierda de la barra de herramientas de la vista previa.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1146,44,239,42)

El botón **Registros** a la izquierda de la barra de herramientas de la vista previa alterna entre el PDF y el registro de compilación, con una insignia que cuenta los errores (rojo) o las advertencias (ámbar):

- Una **lista de diagnósticos** analizada arriba: cada error o advertencia con su tipo y, cuando se conoce, la referencia de línea `l.42`. Los caracteres que las tipografías no pudieron mostrar se agrupan en **Caracteres que faltan**.
- El registro completo del compilador, sin procesar, debajo y con colores: los errores en rojo y negrita, las referencias de línea resaltadas y el anidamiento de archivos con sangría.
- Un botón **Copiar el registro** se lleva todo para un informe de error o una publicación en un foro. ⌘A seguido de ⌘C en el registro también copia todo.
- **Borrar**, junto a **Copiar el registro**, oculta el registro y sus errores hasta la próxima compilación. Tus archivos de compilación se conservan, y la siguiente compilación escribe un registro nuevo.

Los registros largos se abren enseguida, incluso los de 100 000 líneas, y se desplazan sin zonas en blanco.

Los errores de compilación también se convierten en subrayados ondulados en el editor mediante el [flujo del linter](/docs/editor/#the-built-in-latex-linter), y el [asistente de IA](/docs/ai-chat/) puede leer este mismo registro con su herramienta `get_log` cuando le pides que corrija los errores.

Los errores de Typst se marcan en el editor en el tramo exacto que indica Typst, con la línea de código y las propias sugerencias de Typst. Los errores habituales también vienen con una explicación sencilla de lo que salió mal.

## Paquetes y compilación sin conexión

Tectonic descarga un paquete de LaTeX la primera vez que un documento lo necesita y luego lo guarda en caché localmente. La primera compilación en un equipo también descarga de una vez un lote de paquetes de uso habitual. Esa primera compilación puede ser más lenta y necesita conexión de red. Las compilaciones posteriores usan la caché. Si falla el mirror de paquetes de Oleafly, la compilación recurre al origen y el registro lo indica.

El **Modo sin conexión** en Ajustes, General, o en la paleta de comandos convierte esto en una garantía para Tectonic. El compilador se ejecuta con `--only-cached` y nunca descarga un paquete. Un documento que necesita un paquete que no está en la caché falla con un mensaje que nombra el archivo cuando puede, y **Desactivar y compilar** desactiva el modo sin conexión y vuelve a compilar.

El modo sin conexión también cubre Typst. Typst no puede descargar un paquete mientras está activado, así que todos los paquetes `@preview` deben estar ya en la caché o incluidos en la carpeta `typst-packages` del proyecto. Consulta [Paquetes de Typst Universe](/docs/typst/#packages-from-typst-universe). Los proyectos de Markdown ignoran el modo sin conexión, y el registro lo indica.

`latexmk` usa la distribución de TeX ya instalada en tu máquina. Oleafly comprueba primero las distribuciones del sistema, incluidas MacTeX, TeX Live, MiKTeX y TinyTeX, y **Ajustes → Motores → LaTeX** marca con **En uso** la que usa para compilar. Si no hay ninguna disponible, la aplicación puede instalar y gestionar su propia copia de TinyTeX. MiKTeX también necesita Perl para ejecutar `latexmk`; consulta [MiKTeX y Perl](/docs/latex-engines/#miktex-and-perl). Como un proceso de TeX del sistema puede leer los archivos accesibles a tu cuenta de usuario, usa `latexmk` solo con proyectos en los que confíes.

Cuando una compilación con `latexmk` no encuentra un archivo `.sty`, `.cls`, un estilo de bibliografía, un archivo de tipografía, un archivo de idioma de babel, una biblioteca de TikZ u otro archivo de TeX, Oleafly puede ofrecer **Buscar e instalar** en el mensaje de error. El nombre del archivo y el del paquete suelen ser distintos: `tikz.sty`, por ejemplo, pertenece al paquete de TeX Live `pgf`. Oleafly averigua a qué paquete pertenece, lo instala con `tlmgr`, actualiza la lista de paquetes y recompila. En Debian, Ubuntu y Fedora, TeX Live pertenece al gestor de paquetes del sistema, así que Oleafly te da el comando de `apt` o `dnf`. Usa la lista **Paquetes** de **Ajustes → Motores → LaTeX** cuando prefieras buscar primero o gestionar los paquetes a mano.

## Límites y válvulas de seguridad

- Se ejecuta una compilación a la vez por proyecto, en una cola que conserva solo la última: las solicitudes más nuevas reemplazan a las obsoletas, de modo que cambiar de proyecto en mitad de una compilación nunca muestra el PDF equivocado, y mientras escribes nunca se forma una tormenta de compilaciones.
- Una compilación reemplazada o que agota su tiempo se cancela de verdad: Oleafly termina todo el árbol de procesos del compilador, en todas las plataformas, en vez de dejarlo ejecutándose en segundo plano.
- Una compilación que dura más de 5 minutos se detiene en lugar de dejar que dé vueltas para siempre. Mientras Tectonic sigue descargando paquetes, cada descarga adelanta el límite, hasta 30 minutos en total. Markdown a PDF tiene 15 minutos, y Quarto y Calepin tienen una hora.
- Los resultados llevan una identidad ligada a la solicitud, así que un PDF obsoleto que termina fuera de orden se rechaza en lugar de mostrarse.

## Fallos habituales y soluciones rápidas

- **“Missing package” en modo sin conexión**: elige **Desactivar y compilar** en el mensaje, o desactiva el modo sin conexión durante una compilación para descargarlo y guardarlo en caché, y luego vuelve a activarlo.
- **“Este compilador necesita una distribución de TeX que funcione”**: pdfLaTeX y los demás compiladores de `latexmk` necesitan TeX en este equipo, así que elegir uno sin tenerlo abre este diálogo. Elige **Descargar y usar TinyTeX**, o **Volver a Tectonic** para regresar al motor incluido. Si una compilación ya falló por este motivo, la vista previa ofrece **Descargar y usar TinyTeX** y **Usar Tectonic**. Consulta [Cuando no hay TeX instalado](/docs/latex-engines/#when-no-tex-is-installed).
- **“latexmk necesita Perl”** en MiKTeX: instala Strawberry Perl, o instala TinyTeX, que trae el suyo. Consulta [MiKTeX y Perl](/docs/latex-engines/#miktex-and-perl).
- **Falta un archivo en una compilación con `latexmk`**: usa **Buscar e instalar**. Si la búsqueda falla, busca el nombre del archivo o del paquete en la lista **Paquetes** de **Ajustes → Motores → LaTeX**. En Debian, Ubuntu o Fedora, instálalo con `apt` o `dnf`. Los paquetes de MiKTeX se gestionan en MiKTeX Console.
- **upLaTeX o pLaTeX no está instalado**: elige **Instalar el soporte para japonés (unos 450 MB)** cuando se ofrezca, o ejecuta el comando que indica el mensaje. Consulta [Documentos en japonés](/docs/latex-engines/#japanese-documents-uplatex-and-platex).
- **Falta texto en el PDF**, a menudo coreano, chino o japonés: la tipografía no tiene glifos para esos caracteres, y TeX los omite sin que falle la compilación. Oleafly te avisa y el registro incluye una configuración para pegar. Consulta [Caracteres que faltan en el PDF](/docs/latex-engines/#characters-missing-from-the-pdf), o [Caracteres que se ven como cuadros](/docs/typst/#characters-that-show-as-boxes) para Typst.
- **Falta un índice, un glosario o una nomenclatura en el PDF**: Tectonic no puede ejecutar `makeindex`. Cambia el proyecto a `latexmk`, o crea los glosarios con `\makenoidxglossaries`, que no necesita ninguna herramienta externa. Con `latexmk`, las listas hechas con `xindy` o `\newglossary` no se generan.
- **La compilación se quedó sin tiempo**: compila otra vez. Si aún se estaban descargando paquetes, la descarga continúa donde se quedó. Para borradores largos con Tectonic, pon **Modo de compilación** en **Rápida**.
- **Una figura EPS, un controlador `pdftex` forzado o un archivo que falta en el bundle de Tectonic**: se abre el diálogo del motor. Si no se abre, o lo cerraste, elige **Elegir motor**. [Cuando Tectonic no basta](/docs/latex-engines/#when-tectonic-isnt-enough) explica dónde está en cada vista. Elige la opción marcada como **Recomendado**: el LaTeX de tu sistema cuando Oleafly encuentra una distribución de TeX que funciona, o **Descargar y usar TinyTeX** cuando no la encuentra. Si falta un paquete, Oleafly puede continuar con su instalador después del cambio.
- **`minted`, PythonTeX o `\write18` está bloqueado**: si confías en todos los archivos del proyecto, elige **Permitir comandos externos** en el aviso que hay sobre el editor. Consulta [Permitir comandos externos](/docs/latex-engines/#allow-external-commands).
- **Falló la descarga de un paquete en Tectonic**: revisa la conexión y elige **Compilar otra vez** en el mensaje. Oleafly ya probó el origen después de su mirror, la descarga continúa donde se quedó y, si el equipo estaba sin conexión, la compilación se repite sola cuando vuelve la conexión.
- **“Typst 0.13.1 no está instalado”**: el proyecto fija una versión de Typst que este ordenador no tiene. Elige **Descargar Typst 0.13.1** en la vista previa, o **Usar Typst** seguido de tu versión predeterminada para quitar la fijación. Consulta [Cuando falta una versión fijada](/docs/typst/#when-a-pinned-version-is-missing).
- **Advertencias de citas o referencias sin definir**: [Preflight](/docs/preflight/#six-independent-checks) localiza cada una, con el archivo y la línea.
- **Un error que no entiendes**: pregunta a la IA. “Corrige los errores de LaTeX” desencadena un ciclo de compilar, leer el registro, hacer una edición puntual y recompilar, con la [política de aprobación](/docs/ai-chat/) que hayas elegido.

## Otros motores de documentos

La elección del compilador de LaTeX es independiente del motor de documentos del proyecto:

- Los **proyectos de Typst** se compilan con el Typst 0.15.1 incluido o con la versión que fija el proyecto. Consulta [Proyectos de Typst](/docs/typst/).
- Los **proyectos de Markdown** generan el PDF mediante un Pandoc gestionado con Tectonic como motor de PDF.
- Los **proyectos de Quarto** generan archivos `.qmd` y `.Rmd` con Quarto, como PDF o como página web. Consulta [Quarto](/docs/engines/#quarto).
- Los **proyectos de Calepin** ejecutan el código de un documento de Typst con Calepin y luego generan el PDF con el Typst incluido. Consulta [Calepin](/docs/engines/#calepin). Ninguno de los dos motores ejecuta el código de un proyecto hasta que lo [permites](/docs/engines/#allow-code-in-a-project).
- Los **PDF accesibles con etiquetas** usan LuaLaTeX mediante una instalación de TeX del sistema o el TinyTeX gestionado por Oleafly. Consulta [Motores y paquetes de LaTeX](/docs/latex-engines/). Typst 0.14 y posteriores etiquetan todos los PDF sin pasos adicionales.

El motor es una elección por proyecto que se hace al crearlo, y la interfaz se adapta a él: las acciones que un motor no puede admitir se ocultan en lugar de dejarlas fallar. Para pasar un proyecto de LaTeX a Typst, [conviértelo en un proyecto nuevo de Typst](/docs/typst/#convert-a-latex-project-to-typst).

## Conservar el código de una compilación correcta

Activa los [puntos de control](/docs/checkpoints/) para guardar el código usado en las compilaciones correctas. Puedes comparar y restaurar una compilación anterior sin cambiar tu flujo de trabajo manual con Git.

Para conservar el propio PDF compilado en la carpeta del proyecto, activa [Sincronizar PDF al compilar](/docs/pdf-preview/#sync-pdf-on-compiles) en el menú de guardado de la vista previa.
