# LL-Dominus Harbour

Este directorio contiene la infraestructura oficial para desarrollar y probar codigo Harbour dentro de LL-Dominus.

## Objetivo

- El Engine definitivo de LL-Dominus sera Harbour.
- El Engine PHP actual es la referencia funcional durante la migracion.
- No se debe portar todo el Engine de una vez.
- Las traducciones PHP -> Harbour se hacen clase por clase.
- En esta fase se trabaja principalmente con PRG y pruebas ejecutables. No implementar aun DLL, LIB, .so ni .a completas.

## Antes de traducir una clase

1. Leer el codigo PHP real de la clase.
2. Identificar responsabilidad, entradas, salidas y errores relevantes.
3. Localizar dependencias directas.
4. Localizar pruebas o usos reales.
5. Revisar si primero hay que limpiar responsabilidades en PHP.
6. No inventar APIs, clases, metodos, variables, tablas, funciones ni librerias.

Una clase no se considera portada hasta que:

- la implementacion Harbour compila;
- existe prueba Harbour equivalente o prueba de comportamiento suficiente;
- la prueba se ejecuta correctamente;
- las salidas relevantes coinciden con PHP;
- las diferencias inevitables PHP/Harbour estan documentadas;
- no se han anadido funciones nuevas salvo adaptaciones tecnicas justificadas.

## Portabilidad

- El nucleo Harbour debe ser portable entre Windows y Linux.
- No acoplar el nucleo a GUI, WinAPI, HTML, PDF, impresion, rutas absolutas ni estado global evitable.
- Las particularidades de Windows deben quedar en herramientas o adaptadores.
- El IR es el contrato de salida del Engine. Los renderers no deben entrar en el nucleo.
- Usar funciones multiplataforma de Harbour para valores dependientes del sistema:
  - `hb_ps()` para construir rutas reales de filesystem.
  - `hb_eol()` para saltos de linea de texto.
  - No concatenar `\` ni `/` para rutas reales; `/` solo puede usarse como separador logico de plantilla, URL, MIME o data URI.
  - Si una diferencia de plataforma no tiene equivalente claro, preguntar antes de codificar una solucion parcial.

## Compilacion oficial

Usar siempre los BAT de este directorio:

```bat
tools\harbour\build_prg.bat tools\harbour\tests\smoke_env.prg
tools\harbour\build_and_run_prg.bat tools\harbour\tests\smoke_env.prg
tools\harbour\clean_prg.bat tools\harbour\tests\smoke_env.prg
```

Para varios PRG:

```bat
tools\harbour\build_and_run_prg.bat tools\harbour\tests\smoke_multi_main.prg tools\harbour\tests\smoke_multi_helper.prg
```

## Reglas de trabajo

- Despues de cada cambio significativo en Harbour, compilar.
- Cuando exista prueba ejecutable, ejecutarla.
- Leer la salida real de `hbmk2`; corregir basandose en errores reales.
- No ocultar fallos de compilacion o limpieza.
- No crear sistemas alternativos permanentes de build sin causa demostrada.
- Evitar nombres de fichero PRG con espacios. Se verifico que `hbmk2/gcc` falla enlazando objetos o salidas con espacios en el nombre. Los directorios con espacios se soportan mediante los BAT actuales.