# 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. Flujo de ejecución con la caché de compilados: firma, búsqueda en la caché, ejecución compilada o interpretada y compilación ## 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).