Harbour Runtime Binary (HRB)
Referencia técnica de módulos Harbour compilados y carga dinámica
01 Introducción
Harbour dispone de un mecanismo para compilar código fuente Harbour en módulos binarios que pueden cargarse durante la ejecución de una aplicación. Estos módulos se conocen como HRB (Harbour Runtime Binary).
Un módulo HRB contiene p-code Harbour y la información necesaria para que la máquina virtual de Harbour pueda interpretar y ejecutar ese código. La característica fundamental es que permite incorporar funcionalidades a una aplicación sin tener que compilar y enlazar nuevamente todo el ejecutable principal.
Casos de uso principales:
- Sistemas de plugins y extensiones dinámicas.
- Módulos funcionales independientes y componentes cargables bajo demanda.
- Aplicaciones extensibles sin recompilación del binario anfitrión.
- Sistemas de ejecución de código Harbour compilado externamente.
1.1. HRB no es una DLL
Es importante distinguir técnicamente ambos mecanismos de extensión:
| Módulo HRB | Biblioteca DLL Nativa |
|---|---|
| Contiene p-code Harbour | Contiene código máquina nativo |
| Se ejecuta mediante la VM Harbour | Se ejecuta directamente mediante el Sistema Operativo |
| Utiliza el runtime Harbour | Utiliza ABI y convenciones de llamada nativas |
| Puede utilizar símbolos Harbour directamente | Expone funciones nativas exportadas |
Se carga mediante la API HRB (hb_hrbLoad) |
Se carga mediante mecanismos del SO (LoadLibrary) |
Un HRB no es un ejecutable independiente: necesita obligatoriamente un entorno Harbour (VM) compatible activo para poder cargarse y ejecutarse.
02 Arquitectura general
La aplicación principal conserva su entorno de ejecución intacto, mientras que el módulo HRB incorpora código p-code adicional que se integra dinámicamente con la máquina virtual.
2.1. Máquina virtual Harbour
La VM es el componente encargado de ejecutar las instrucciones p-code. Su funcionamiento involucra:
- Pila de ejecución y administración de niveles de ejecución.
- Tabla de símbolos global y resolución dinámica.
- Variables públicas y estáticas.
- Administración de memoria y recolector de basura (GC).
- Subsistema de objetos, funciones y procedimientos.
El documento oficial doc/vm.txt describe en detalle estos subsistemas: github.com/harbour/core/blob/master/doc/vm.txt.
03 API de administración HRB
Harbour proporciona un conjunto de funciones integradas en su espacio de nombres público para administrar módulos HRB:
| Función | Responsabilidad principal |
|---|---|
hb_hrbLoad() |
Carga un módulo HRB en memoria y devuelve su handle/referencia. |
hb_hrbRun() |
Carga y ejecuta un módulo de forma directa sin gestión manual del ciclo. |
hb_hrbDo() |
Ejecuta código de un módulo previamente cargado con hb_hrbLoad(). |
hb_hrbUnload() |
Libera y descarga un módulo HRB de la memoria. |
hb_hrbGetFunList() |
Obtiene la lista de funciones exportadas/contenidas en el módulo. |
hb_hrbGetFunSym() |
Busca y devuelve el símbolo correspondiente a una función específica. |
hb_hrbSignature() |
Obtiene la firma identificadora del formato binario HRB. |
3.1. hb_hrbLoad()
Permite cargar un archivo HRB en memoria y devuelve una referencia utilizable para ejecuciones posteriores. Admite opciones de vinculación y parámetros destinados al procedimiento de inicialización del módulo.
// Esquema general documentado
pHRB := hb_hrbLoad( [nOptions], cHrbFileName, [xParameters...] )
// Ejemplo básico
pHRB := hb_hrbLoad( "plugin.hrb" )
Nota: Los parámetros exactos y constantes de opciones deben verificarse contra hbhrb.ch de la versión Harbour utilizada.
3.2. hb_hrbRun()
Ejecuta un módulo HRB directamente. Es útil cuando se desea correr un script compilado sin administrar explícitamente su ciclo de carga y descarga. La ejecución ocurre dentro del mismo entorno Harbour que realiza la llamada (no es IPC).
xResult := hb_hrbRun( "plugin.hrb" )
3.3. hb_hrbDo()
Permite ejecutar código de un módulo que ya fue cargado previamente mediante hb_hrbLoad().
pHRB := hb_hrbLoad( "plugin.hrb" )
IF pHRB != NIL
hb_hrbDo( pHRB )
ENDIF
3.4. hb_hrbUnload()
Libera el código HRB previamente cargado en memoria:
hb_hrbUnload( pHRB )
Antes de descargar un módulo deben liberarse todas las referencias activas (objetos, codeblocks, punteros a símbolos) que dependan de su código.
3.5. hb_hrbGetFunList()
Permite obtener información sobre las funciones presentes en un módulo HRB cargado. Resulta fundamental para implementar mecanismos de introspección y descubrimiento automático de funcionalidades en sistemas de plugins.
3.6. hb_hrbGetFunSym()
Busca un símbolo correspondiente a una función dentro de un módulo HRB. Si el símbolo existe, puede utilizarse para invocar la función mediante los mecanismos de evaluación de símbolos de Harbour (como hb_ExecFromArray() o Eval()).
3.7. hb_hrbSignature()
Devuelve la firma identificadora del formato binario HRB. Es útil para validar compatibilidad de versión del formato, pero no debe confundirse con una firma criptográfica de integridad o autenticidad.
04 Opciones de vinculación
La carga de módulos HRB admite diferentes modos de vinculación definidos mediante constantes HB_HRB_BIND_* en el archivo de cabecera include/hbhrb.ch.
Estas opciones determinan cómo se resuelven y enlazan los símbolos entre el módulo cargado y la tabla de símbolos de la aplicación anfitriona:
- Significado y alcance de cada constante
HB_HRB_BIND_*. - Resolución de símbolos externos solicitados por el HRB.
- Comportamiento ante símbolos ya existentes en el host (sobrescritura, aislamiento o error).
- Tratamiento de símbolos no encontrados o duplicados entre múltiples módulos.
No establecer valores numéricos fijos ni asumir el comportamiento de cada modalidad sin inspeccionar el archivo include/hbhrb.ch correspondiente a la versión exacta de Harbour compilada en el entorno.
05 Comunicación entre aplicación y módulo
A diferencia de procesos externos, HRB no utiliza IPC, sockets ni pipes para comunicarse con su aplicación anfitriona: ambos ejecutan código dentro de la misma Máquina Virtual Harbour.
La comunicación puede realizarse de forma nativa mediante parámetros de funciones, valores de retorno, símbolos públicos, objetos, arrays, hashes y codeblocks.
| Mecanismo | Tipos de datos soportados | Observaciones |
|---|---|---|
| Parámetros de entrada | Strings, números, fechas, lógicos, arrays, hashes, objetos | Pueden pasarse tanto en la inicialización (hb_hrbLoad) como en llamadas posteriores. Historial documentado en doc/oldnews.txt. |
| Valores de retorno | String, Número, Fecha, Logical, Array, Hash, Objeto, NIL |
Se recomienda validar la compatibilidad concreta de objetos complejos mediante pruebas ejecutables. |
06 Funciones, símbolos y clases
Los módulos HRB interactúan directamente con el sistema de símbolos de Harbour, permitiendo que la aplicación anfitriona localice funciones y ejecute código del módulo.
Respecto a la Programación Orientada a Objetos, deben investigarse y validarse los siguientes puntos críticos cuando se definen clases dentro de módulos dinámicos:
- Registro de clases en la tabla global de clases de la VM.
- Resolución de métodos e herencia con clases del anfitrión.
- Instanciación de objetos desde el host hacia clases definidas en el HRB.
- Referencias cruzadas a clases definidas en otros módulos HRB.
- Descarga de módulos que contienen clases registradas activas.
- Estado de referencias a métodos u objetos existentes tras descargar el módulo.
No debe asumirse que invocar hb_hrbUnload() elimina o invalida de forma segura todos los objetos que fueron instanciados a partir de clases definidas en ese módulo.
07 Variables y estado
Un módulo HRB mantiene su propio estado de ejecución. Es necesario distinguir el alcance de cada tipo de variable:
- Locales: Aisladas al marco de ejecución de cada función.
- Estáticas (
STATIC): Persisten dentro del módulo HRB mientras permanezca cargado en memoria. - Públicas / Privadas / Globales: Interactúan con el entorno de variables de la VM según las reglas de vinculación activas.
- Estado de objetos: Almacenado en las variables de instancia (
DATA) de cada objeto creado.
Debe estudiarse particularmente qué ocurre cuando un mismo módulo HRB se carga múltiples veces o cuando conviven varios módulos que declaran símbolos con nombres coincidentes.
08 Ciclo de vida de un módulo
Un ciclo de vida controlado para un plugin HRB sigue esta secuencia estricta:
Implementar un gestor centralizado que controle: módulos cargados, identificadores únicos, funciones registradas, objetos instanciados, dependencias, contador de referencias activas y estados de inicialización/descarga. Nunca descargar un módulo mientras existan referencias activas dependientes de él.
09 Seguridad
HRB no debe considerarse un formato seguro ni aislado (sandbox) por el simple hecho de ser binario. Un módulo HRB contiene p-code ejecutable con los mismos privilegios y permisos del sistema operativo que la aplicación anfitriona.
- No cargar módulos de origen desconocido o no verificado.
- Controlar estrictamente los permisos de escritura en los directorios de plugins.
- Verificar integridad mediante hashes criptográficos (ej. SHA-256) o firmas digitales externas cuando corresponda.
- Recordar que
hb_hrbSignature()solo identifica el encabezado del formato, no valida autenticidad.
10 Diferencia entre HRB y proveedores de Workspace
Workspace utiliza archivos con extensión .hbr ubicados en el directorio:
E:\WorkSpacein\Plugins\Providers
Archivos identificados actualmente:
Aunque la extensión .hbr difiere de la extensión convencional .hrb de Harbour Runtime Binary, la inspección de estos archivos revela estructuras de módulos Harbour compilados. Por lo tanto:
- HRB: Tecnología y formato binario estándar de Harbour.
- HBR: Convención de extensión adoptada por Workspace para identificar sus plugins de proveedores de compilación.
La relación exacta entre esta extensión y el cargador utilizado debe verificarse en el código fuente de Workspace.
11 Fuentes oficiales y referencias
| Recurso | Ubicación / Enlace | Propósito |
|---|---|---|
| Harbour Core | github.com/harbour/core | Repositorio principal del proyecto |
| Máquina Virtual | doc/vm.txt | Arquitectura y subsistemas de la VM |
| Funciones HRB | include/harbour.hbx | Declaraciones de símbolos públicos HRB |
| Opciones HRB | include/hbhrb.ch |
Constantes de vinculación HB_HRB_BIND_* |
| Historial | doc/oldnews.txt | Evolución de la API y soporte de parámetros no string |
12 Plan de verificación experimental
Para validar cada comportamiento en la versión exacta de Harbour utilizada, se propone construir una aplicación anfitriona mínima y ejecutar la siguiente batería de pruebas:
- Generar un archivo HRB de prueba.
- Cargar con
hb_hrbLoad(). - Comprobar handle devuelto y registrar errores.
- Ejecutar función principal del módulo.
- Verificar recepción de parámetros.
- Comprobar valor de retorno.
- Probar intercambio de String, Número y Logical.
- Probar estructuras complejas: Array, Hash y Objeto.
- Enumerar funciones con
hb_hrbGetFunList(). - Buscar símbolos con
hb_hrbGetFunSym(). - Invocar funciones específicas dinámicamente.
- Modificar variables
STATICinternas. - Invocar funciones repetidamente.
- Observar persistencia entre llamadas.
- Liberar referencias activas del módulo.
- Ejecutar
hb_hrbUnload(). - Verificar liberación limpia en memoria.
- Probar distintas banderas
HB_HRB_BIND_*. - Observar resolución y colisión de símbolos.
13 Conclusión
HRB proporciona a Harbour un mecanismo de extensibilidad dinámica potente y ligero basado en p-code compilado, permitiendo incorporar funcionalidades en tiempo de ejecución sin depender de DLLs nativas ni recompilar el ejecutable principal.
Para implementarlo de forma robusta en producción es indispensable dominar la estructura del módulo, las reglas de vinculación de símbolos, el intercambio de datos y, especialmente, el ciclo de vida y control de referencias previo a la descarga.