Harbour Runtime Binary (HRB)
Technical reference for compiled Harbour modules and dynamic loading
01 Introduction
Harbour provides a mechanism for compiling Harbour source code into binary modules that can be loaded during an application's runtime. These modules are known as HRB (Harbour Runtime Binary).
An HRB module contains Harbour p-code along with the metadata required for the Harbour Virtual Machine to interpret and execute that code. Its core advantage is allowing new functionality to be added to an application without recompiling and relinking the main executable.
Primary use cases:
- Plugin systems and dynamic extensions.
- Independent functional modules and on-demand loadable components.
- Extensible applications without recompiling the host binary.
- Execution systems for externally compiled Harbour code.
1.1. HRB is not a DLL
It is essential to distinguish technically between these two extension mechanisms:
| HRB Module | Native DLL Library |
|---|---|
| Contains Harbour p-code | Contains native machine code |
| Executed by the Harbour VM | Executed directly by the Operating System |
| Uses the Harbour runtime | Uses native ABI and calling conventions |
| Can directly access Harbour symbols | Exposes exported native functions |
Loaded via the HRB API (hb_hrbLoad) |
Loaded via OS mechanisms (LoadLibrary) |
An HRB is not a standalone executable: it strictly requires an active, compatible Harbour environment (VM) in order to be loaded and executed.
02 General Architecture
The host application preserves its runtime environment intact, while the HRB module injects additional p-code that integrates dynamically with the virtual machine.
2.1. Harbour Virtual Machine
The VM is the component responsible for executing p-code instructions. Its operation involves:
- Execution stack and execution level management.
- Global symbol table and dynamic symbol resolution.
- Public and static variables.
- Memory management and Garbage Collector (GC).
- Object subsystem, functions, and procedures.
The official document doc/vm.txt describes these subsystems in detail: github.com/harbour/core/blob/master/doc/vm.txt.
03 HRB Management API
Harbour provides a set of built-in functions within its public namespace to manage HRB modules:
| Function | Primary Responsibility |
|---|---|
hb_hrbLoad() |
Loads an HRB module into memory and returns its handle/reference. |
hb_hrbRun() |
Loads and executes a module directly without manual lifecycle management. |
hb_hrbDo() |
Executes code from a module previously loaded with hb_hrbLoad(). |
hb_hrbUnload() |
Frees and unloads an HRB module from memory. |
hb_hrbGetFunList() |
Retrieves the list of functions contained/exported in the module. |
hb_hrbGetFunSym() |
Searches for and returns the symbol corresponding to a specific function. |
hb_hrbSignature() |
Returns the identifying signature of the HRB binary format. |
3.1. hb_hrbLoad()
Loads an HRB file into memory and returns a handle usable for subsequent executions. It accepts binding options and parameters intended for the module's initialization procedure.
// Documented general signature
pHRB := hb_hrbLoad( [nOptions], cHrbFileName, [xParameters...] )
// Basic example
pHRB := hb_hrbLoad( "plugin.hrb" )
Note: Exact parameter signatures and option constants must be verified against hbhrb.ch for the specific Harbour version in use.
3.2. hb_hrbRun()
Executes an HRB module directly. Useful when running compiled scripts without explicitly managing their load/unload cycle. Execution takes place inside the same Harbour environment making the call (not IPC).
xResult := hb_hrbRun( "plugin.hrb" )
3.3. hb_hrbDo()
Executes code from a module that was previously loaded via hb_hrbLoad().
pHRB := hb_hrbLoad( "plugin.hrb" )
IF pHRB != NIL
hb_hrbDo( pHRB )
ENDIF
3.4. hb_hrbUnload()
Frees previously loaded HRB code from memory:
hb_hrbUnload( pHRB )
Before unloading a module, all active references (objects, codeblocks, symbol pointers) that depend on its code must be released.
3.5. hb_hrbGetFunList()
Retrieves information about the functions present inside a loaded HRB module. Essential for implementing introspection and automatic feature discovery in plugin architectures.
3.6. hb_hrbGetFunSym()
Searches for a symbol corresponding to a function inside an HRB module. If found, it can be used to invoke the function through Harbour's symbol evaluation mechanisms (such as hb_ExecFromArray() or Eval()).
3.7. hb_hrbSignature()
Returns the identifying header signature of the HRB binary format. Useful for validating binary format compatibility, though it must not be mistaken for a cryptographic integrity or authenticity signature.
04 Binding Options
Loading HRB modules supports different binding modes defined via HB_HRB_BIND_* constants in the header file include/hbhrb.ch.
These options control how symbols are resolved and linked between the loaded module and the host application's symbol table:
- Meaning and scope of each
HB_HRB_BIND_*constant. - Resolution of external symbols requested by the HRB module.
- Behavior when symbols already exist in the host (overwriting, isolation, or error).
- Handling of unresolved or duplicate symbols across multiple loaded modules.
Do not hardcode numeric values or assume the exact behavior of each binding mode without inspecting include/hbhrb.ch from the exact Harbour version compiled in your environment.
05 Application & Module Communication
Unlike external processes, HRB does not rely on IPC, sockets, or pipes to communicate with its host application: both execute code within the same Harbour Virtual Machine.
Communication is performed natively using function parameters, return values, public symbols, objects, arrays, hashes, and codeblocks.
| Mechanism | Supported Data Types | Notes |
|---|---|---|
| Input Parameters | Strings, numbers, dates, logicals, arrays, hashes, objects | Can be passed both during initialization (hb_hrbLoad) and in subsequent calls. Evolution documented in doc/oldnews.txt. |
| Return Values | String, Number, Date, Logical, Array, Hash, Object, NIL |
Concrete compatibility for complex objects should be validated with executable tests. |
06 Functions, Symbols & Classes
HRB modules interact directly with Harbour's symbol system, enabling the host application to locate functions and execute module code.
Regarding Object-Oriented Programming, the following critical areas must be investigated and validated when defining classes inside dynamic modules:
- Class registration in the VM's global class table.
- Method resolution and inheritance with host classes.
- Object instantiation from the host for classes defined inside an HRB.
- Cross-references to classes defined in other HRB modules.
- Unloading modules that contain active registered classes.
- State of method references or existing instances after unloading a module.
Do not assume that calling hb_hrbUnload() safely destroys or invalidates all object instances created from classes defined within that module.
07 Variables & State
An HRB module maintains its own execution state. It is important to distinguish the scope of each variable class:
- Locals: Scoped strictly to each function's execution frame.
- Statics (
STATIC): Persist within the HRB module for as long as it remains loaded in memory. - Public / Private / Global: Interact with the VM variable environment according to active binding rules.
- Object State: Stored in the instance variables (
DATA) of each instantiated object.
Special attention should be given to what happens when the same HRB module is loaded multiple times or when multiple modules declare colliding symbol names.
08 Module Lifecycle
A controlled lifecycle for an HRB plugin follows this strict sequence:
Implement a centralized manager tracking loaded modules, unique module IDs, registered functions, instantiated objects, dependencies, active reference counts, and initialization/unloading states. Never unload a module while active references still depend on it.
09 Security
HRB must not be considered a secure or sandboxed format merely because it is binary. An HRB module contains executable p-code that runs with the exact same operating system privileges and permissions as the host application.
- Never load modules from untrusted or unverified sources.
- Strictly control write permissions on plugin directories.
- Verify file integrity using cryptographic hashes (e.g., SHA-256) or external digital signatures where appropriate.
- Remember that
hb_hrbSignature()only identifies the format header—it does not verify authenticity.
10 HRB vs. Workspace Providers
Workspace uses files with the .hbr extension located in:
E:\WorkSpacein\Plugins\Providers
Currently identified provider files:
Although the .hbr extension differs from the standard .hrb extension of Harbour Runtime Binary, inspecting these files reveals compiled Harbour module structures. Therefore:
- HRB: Standard Harbour binary technology and format.
- HBR: File extension convention adopted by Workspace for its compiler provider plugins.
The exact relationship between this extension and the loader used by Workspace should be verified in the application's source code.
11 Official Sources & References
| Resource | Location / Link | Purpose |
|---|---|---|
| Harbour Core | github.com/harbour/core | Main project repository |
| Virtual Machine | doc/vm.txt | VM architecture and subsystems |
| HRB Functions | include/harbour.hbx | Public HRB symbol declarations |
| HRB Options | include/hbhrb.ch |
HB_HRB_BIND_* binding constants |
| Change History | doc/oldnews.txt | API evolution and non-string parameter support |
12 Experimental Verification Plan
To validate each behavior against the exact Harbour build in use, build a minimal host application and run the following test suite:
- Compile a test HRB file.
- Load it using
hb_hrbLoad(). - Verify the returned handle and log any errors.
- Execute the module's entry function.
- Verify parameter reception.
- Check return values.
- Test String, Number, and Logical exchange.
- Test complex structures: Array, Hash, and Object.
- Enumerate functions via
hb_hrbGetFunList(). - Lookup symbols via
hb_hrbGetFunSym(). - Invoke specific functions dynamically.
- Modify internal
STATICvariables. - Invoke functions repeatedly.
- Observe state persistence across calls.
- Release all active module references.
- Call
hb_hrbUnload(). - Verify clean memory release.
- Test different
HB_HRB_BIND_*flags. - Observe symbol resolution and collision handling.
13 Conclusion
HRB equips Harbour with a lightweight, powerful dynamic extensibility mechanism based on compiled p-code, enabling runtime feature loading without relying on native DLLs or rebuilding the host executable.
To deploy it reliably in production, developers must master module structure, symbol binding rules, data exchange, and—above all—lifecycle and reference management prior to unloading.