# Compilación de programas DKL
Devkron 2.0 LTS puede **compilar** sus programas DKL a código máquina sin cambiar una sola línea del programa. El programa compilado da exactamente el mismo resultado que el interpretado, pero los ciclos, la recursión y las funciones que se llaman muchas veces corren de 2 a 5 veces más rápido.
Devkron 1.x no compilaba: todo se interpretaba. En 2.0 la compilación es **opcional** y está **apagada por omisión**. Esta página explica cómo funciona, cuándo conviene encenderla, cómo usarla en consola y en el servidor FastCGI, y cómo saber qué se compiló.
## En resumen
| Dónde | Cómo se compila | Qué hay que hacer |
|---|---|---|
| Consola (`dkl`) | en primer plano, antes de ejecutar | agregar `-compile` una vez; las siguientes ejecuciones usan lo compilado |
| Servidor FastCGI | en segundo plano, sin detener las peticiones | poner `"native_compile": true` en `fastcgi.json` y reiniciar |
| Las dos | lo compilado se guarda en la **caché de compilados**, firmado con una llave propia de la instalación | nada: la caché y la llave se crean solas |
No hay que marcar el código, ni generar un archivo aparte, ni distribuir otra cosa que los `.dkl`, `.dk` y `.dkh` de siempre. Si algo no se puede compilar, se interpreta en silencio.
## Cómo funciona
1. Devkron analiza el programa y todos sus `#include`, como siempre.
2. Calcula una **firma** (SHA-256) con el contenido del programa y de sus includes, la versión del motor y las opciones que afectan al código.
3. Busca en la caché de compilados una entrada con esa firma y con la marca de integridad de su llave.
- Si la encuentra, la carga y **ejecuta lo compilado**.
- Si no, **interpreta** el programa. Además, compila en primer plano si usted pidió `-compile` en consola, o lo encola en segundo plano en FastCGI con `native_compile`.
4. Lo que se compila son las **funciones** y los **ciclos**. Un modelo de costo decide qué partes vale la pena: lo que corre una sola vez fuera de una función no se compila, porque compilarlo cuesta más de lo que ahorra.
## Cuándo conviene encenderla
Mídalo en su aplicación antes de dejarla encendida. Como referencia, en aplicaciones reales:
| Tipo de programa | Ganancia | Costo |
|---|---|---|
| Cálculo intensivo: ciclos largos, recursión, funciones DKL llamadas miles de veces, poca base de datos | **2 a 5 veces** más rápido en estado estable | más memoria |
| Aplicación web real con base de datos (en FastCGI, de 1 a 200 clientes) | 3 a 10 % más peticiones por segundo | ~35 % más memoria; la primera visita de cada programa es más lenta mientras compila |
| Aplicación con MySQL y un solo usuario | nada medible | 35 a 40 % más memoria |
En las aplicaciones con base de datos, el tiempo se va en las consultas y en la salida, no en el DKL. Ahí la caché del árbol analizado y el intérprete de 2.0 ya hacen casi todo el trabajo (vea [Rendimiento](/es/devkron/2.0/migracion/rendimiento.md)).
**Regla práctica:**
- **Encienda la compilación** para reportes y procesos por lotes con cálculo pesado, y para servicios que hacen mucha lógica en DKL entre consultas, siempre que el servidor tenga memoria de sobra.
- **Déjela apagada** en sitios web y sistemas de gestión donde casi todo es consultar la base de datos y pintar la página.
## En consola: `-compile`
Sin `-compile`, `dkl` **nunca compila**. Pero si en la caché ya existe un compilado vigente del mismo programa, lo usa. Con `-compile`, primero compila, guarda en la caché y luego ejecuta lo compilado.
Ejemplo, `fib.dkl`:
```dkl
#include "dkli.dkh"
#!
program "fibonacci"
{
function fib(n)
{
if n < 2 { return n }
return fib(n - 1) + fib(n - 2)
}
r = fib(27)
do print("fib(27) = " + str(r))
}
```
```bash
dkl /home/usuario/fib.dkl -hide-log # interpretado
dkl /home/usuario/fib.dkl -hide-log -compile # compila, guarda y ejecuta
dkl /home/usuario/fib.dkl -hide-log # usa lo compilado de la caché
```
Las tres ejecuciones imprimen lo mismo:
```text
fib(27) = 196418
```
Tiempos medidos de proceso completo, incluido el arranque de `dkl`, en una VM de 2 núcleos con Linux:
| Ejecución | Tiempo |
|---|---:|
| interpretada | 0.76 s |
| con `-compile` (incluye compilar) | 0.45 s |
| siguientes, desde la caché | 0.29 s |
**Para tareas programadas** (`cron`, Programador de tareas):
1. Ejecute la tarea una vez con `-compile`, con **el mismo usuario** con el que va a correr. La caché y la llave son por usuario.
2. Deje en `cron` la línea sin `-compile`: usará lo compilado mientras el programa no cambie.
3. Si cambia el programa, la siguiente ejecución se interpreta hasta que vuelva a correr con `-compile`. También puede dejar `-compile` siempre: cuando la caché está vigente no recompila.
```bash
# crontab del usuario devkron: el reporte de las 2:00 usa lo compilado
0 2 * * * /opt/devkron/dkl /srv/tareas/reporte-nocturno.dkl -hide-log -compile >> /var/log/devkron/reporte.log 2>&1
```
## En el servidor FastCGI: `native_compile`
Agregue la llave en `fastcgi.json` y reinicie el servicio:
```json
{
"native_compile": true,
"native_cache_dir": "/var/cache/devkron/native"
}
```
Entonces el servidor:
1. **Interpreta** la primera petición de un programa sin compilado vigente y encola la compilación en un hilo de baja prioridad. Mientras compila, las peticiones siguen interpretadas: nadie espera.
2. Al terminar, guarda el compilado en disco y las **peticiones siguientes** lo usan.
3. **Cambios en caliente.** Si edita el `.dk` o cualquiera de sus `#include`, la siguiente petición se interpreta con el código nuevo y se recompila en segundo plano. Nunca se sirve una versión compilada vieja.
4. **Al reiniciar** el servicio, lo compilado se lee de la caché en disco, sin recompilar.
Las DLL que carga `_import_library` funcionan igual en código compilado. Reemplazar una DLL ya cargada **sigue requiriendo reiniciar** FastCGI, como en 1.x.
Con muchos programas compilados, tres topes acotan la memoria. `0` quiere decir sin tope:
| Llave de `fastcgi.json` | Omisión | Qué hace |
|---|---|---|
| `native_max_contexts` | 512 | programas compilados cargados a la vez; al pasarlo se descarga el de uso más antiguo (se vuelve a leer de disco sin recompilar) |
| `native_max_assembly_kb` | 4096 | tamaño de código por programa; lo que no cabe se interpreta |
| `native_max_program_mb` | 64 | si la huella de un programa compilado pasa este tope, ese programa se interpreta hasta que cambie su código; se avisa en el journal con `##nativo corte: …` |
Todas las llaves de `fastcgi.json` están en [Servidor FastCGI](/es/devkron/2.0/instalacion/fastcgi.md).
## Cuándo se recompila
La firma de cada compilado incluye:
- el contenido del programa y de **todos** sus `#include`, también los anidados;
- las búsquedas de archivos que hizo al resolverlos;
- la versión exacta del motor;
- las opciones que cambian el código;
- el directorio de trabajo y las rutas de `#path`.
| Qué pasó | ¿Se recompila? |
|---|---|
| editó el programa o un include | sí |
| creó un archivo que cambia cómo se resuelve un `#include` | sí |
| actualizó Devkron, aunque sea un parche | sí, todo |
| ejecutó desde otro directorio de trabajo | sí |
| `touch` a un archivo sin cambiar su contenido | no |
| el programa tiene un `#include` por URL | nunca se compila |
En consola, un programa editado se **interpreta** hasta la siguiente ejecución con `-compile`. Con `DEVKRON_NATIVE_STATS=1` lo verá como `fallos=1 compilaciones=0`.
## Qué no se compila
Estas partes se quedan en el intérprete, en silencio y con el mismo resultado. El resto del programa sí puede estar compilado:
- `point`, `go`, `that`, `expose`, `text`, `namespace`, `alias`;
- `store`/`unstore` (`>>`/`<<`), las flechas `->`/`<-` y los bloques `$$`;
- `let` con plantilla, imprimibles con marcas en el nombre o en una llave, y elementos ocultos;
- el código que se analiza al ejecutar: `eval`, `runcode`, `runscript` e `include` en ejecución;
- lo que corre una sola vez fuera de una función y sin ciclos;
- funciones que el programa no nombra desde el código alcanzable.
Si un programa que se compila no acelera, lo más probable es que su tiempo esté en estas partes o en la base de datos.
## La caché de compilados y su llave
| | Ubicación (gana la primera que aplique) |
|---|---|
| **Caché** | `-native-cache-dir:ruta` (consola o `devkron_args`) o `"native_cache_dir"` en `fastcgi.json` › `DEVKRON_NATIVE_CACHE_DIR` › `/native-cache` si se puede escribir › `~/.cache/devkron/native-cache` (Linux), `%LOCALAPPDATA%\Devkron\native-cache` (Windows) |
| **Llave** | `DEVKRON_NATIVE_KEY_FILE` › `"native_key_file"` en `fastcgi.json` › `~/.config/devkron/native.key` (Linux), `%LOCALAPPDATA%\Devkron\native.key` (Windows) |
- Cada entrada (`.dkn`, una por programa) va firmada con **HMAC-SHA256** y la llave de la instalación. Devkron nunca carga un compilado que no produjo esa misma llave. Eso protege contra entradas copiadas de otra máquina, respaldos, corrupción o alguien con permiso de escritura en la carpeta.
- **No copie la caché entre servidores:** en otro servidor se rechaza y se recompila. Cada servidor genera la suya.
- La llave (32 bytes aleatorios) se crea sola en el primer uso, **por usuario del sistema**, con permisos `0600` en una carpeta `0700`.
- En Linux, Devkron **rechaza** una llave con permisos para el grupo u otros. Entonces no usa la caché y todo se interpreta. Con `DEVKRON_NATIVE_STATS=1` lo verá en `sin_llave`.
- **Nunca** ponga la llave ni la caché dentro de la raíz web (`web/`).
- La caché se limpia sola, a lo más una vez por hora. Borra:
- entradas cuyo fuente cambió o se borró;
- entradas de otros motores con más de 7 días;
- entradas sin uso en 30 días;
- si pasa de 512 MB o 20 000 entradas, las más viejas.
- Puede borrar la carpeta completa cuando quiera: solo se pierde lo compilado.
- Un error de la caché (solo lectura, disco lleno, archivo dañado) nunca llega al programa: se interpreta.
- Si el servicio FastCGI y las tareas de consola corren con usuarios distintos, cada uno tiene su llave y su caché y no comparten compilados. No es un error.
Permisos recomendados para el servicio: [Servicio en Linux (systemd)](/es/devkron/2.0/instalacion/servicio-linux.md) y [Servicio en Windows](/es/devkron/2.0/instalacion/servicio-windows.md).
## Cómo saber qué se compiló
`DEVKRON_NATIVE_NOTES=1` explica, unidad por unidad, qué se compiló, qué se quedó en el intérprete y por qué:
```bash
DEVKRON_NATIVE_NOTES=1 dkl /home/usuario/fib.dkl -hide-log -compile
```
```text
##native compiladas=1 omitidas=0
##native función fib (fib.dkl:9): costo ganancia=27 lento=0 caliente -> consola:sí servidor:sí
fib(27) = 196418
```
`DEVKRON_NATIVE_STATS=1` imprime contadores en stderr al salir. La primera ejecución con `-compile`:
```text
##nativo aciertos=0 fallos=1 compilaciones=1 enlaces=1 … escrituras=1 rechazados=0 … sin_llave=0 … errores=0 …
```
La siguiente, sin `-compile`, ya lee la caché:
```text
##nativo aciertos=1 fallos=0 compilaciones=0 enlaces=1 …
```
| Contador | Significa |
|---|---|
| `aciertos` | compilados vigentes leídos de la caché |
| `fallos` | programas sin compilado vigente (se interpretaron) |
| `compilaciones` | programas que se compilaron en esta ejecución |
| `rechazados` | entradas con firma o formato inválido (se borran) |
| `sin_llave` | la llave falta o se rechazó (también imprime el motivo) |
| `cortes` | programas que pasaron `native_max_program_mb` y se interpretan |
| `errores` | errores del compilador o de la caché (el programa se interpretó) |
## Interruptores
- `"native_compile"` en `fastcgi.json`: `true` enciende la compilación en FastCGI y `false` la apaga (apagada por omisión).
- `-compile` en `dkl` o `devkron_args`: compila en primer plano antes de ejecutar.
- `DEVKRON_NATIVE=0`: apaga la compilación por completo; gana siempre (interruptor de emergencia).
- `DEVKRON_COMPILE_ALL=1`: validación: compila todo lo compilable en primer plano y lo enlaza todo, también en FastCGI.
- `DEVKRON_NATIVE_STRICT=1`: un error del compilador detiene la ejecución (para pruebas).
- `DEVKRON_NATIVE_STATS=1`: contadores en stderr al salir.
- `DEVKRON_NATIVE_NOTES=1`: notas del compilador en stderr al salir.
- `-native-cache-dir:ruta`: carpeta de la caché en consola; en `fastcgi.json` es `"native_cache_dir"` y en el entorno `DEVKRON_NATIVE_CACHE_DIR`.
- `DEVKRON_NATIVE_KEY_FILE`: archivo de la llave; en `fastcgi.json` es `"native_key_file"`.
## Problemas frecuentes
| Síntoma | Causa | Solución |
|---|---|---|
| `aciertos=0` en cada ejecución aunque ya compiló | corre con otro usuario o desde otro directorio de trabajo, o el programa cambió | compile con el mismo usuario y directorio con que corre la tarea |
| `sin_llave=1` y nada se compila | la llave o su carpeta tienen permisos para el grupo u otros | `chmod 700` a la carpeta y `chmod 600` a `native.key`, o bórrela para que se cree de nuevo |
| el servidor usa más memoria con la compilación encendida | es lo esperado (~35 %) | baje `native_max_contexts` o apague `native_compile` si no gana velocidad |
| la primera visita de una página es más lenta tras un cambio | se interpreta mientras compila en segundo plano | normal; las siguientes usan lo compilado |
| un resultado distinto con y sin compilar | defecto del motor | compare con `DEVKRON_NATIVE=0` y repórtelo con el programa mínimo que lo reproduzca |
## Compilar no es cifrar
La compilación acelera, pero **no protege el código**: los `.dkl` siguen siendo necesarios en el servidor y la caché es solo una copia de trabajo. Para distribuir programas sin que se lea el fuente, use el cifrado de fuentes de [Ejecutar programas de consola](/es/devkron/2.0/instalacion/consola.md).
## Vea también
- [Rendimiento](/es/devkron/2.0/migracion/rendimiento.md): todo lo que hace más rápido a 2.0, cifras y diagnóstico.
- [Ejecutar programas de consola](/es/devkron/2.0/instalacion/consola.md): todas las opciones de `dkl`.
- [Servidor FastCGI](/es/devkron/2.0/instalacion/fastcgi.md): todas las llaves de `fastcgi.json`.
- [Variables de entorno](/es/devkron/2.0/instalacion/variables-de-entorno.md).