Harbour Runtime Binary (HRB)

Technical reference for compiled Harbour modules and dynamic loading

Status Initial research version
Technology / Format Harbour · HRB (p-code)
Primary Source Harbour Core
Objective Compilation, loading & lifecycle

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:

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)
Environment Dependency

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.

Host Application Main Executable Harbour VM Symbol Table / Stack HRB Loader hb_hrbLoad() HRB Module .hrb / .hbr File p-code Execution VM Runtime
Loading and integration flow of p-code within the Harbour Virtual Machine.

2.1. Harbour Virtual Machine

The VM is the component responsible for executing p-code instructions. Its operation involves:

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.

Harbour — Syntax and basic usage
// 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).

Harbour
xResult := hb_hrbRun( "plugin.hrb" )

3.3. hb_hrbDo()

Executes code from a module that was previously loaded via hb_hrbLoad().

Harbour
pHRB := hb_hrbLoad( "plugin.hrb" )

IF pHRB != NIL
   hb_hrbDo( pHRB )
ENDIF

3.4. hb_hrbUnload()

Frees previously loaded HRB code from memory:

Harbour
hb_hrbUnload( pHRB )
Delicate Operation

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:

Pending Verification

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:

  1. Class registration in the VM's global class table.
  2. Method resolution and inheritance with host classes.
  3. Object instantiation from the host for classes defined inside an HRB.
  4. Cross-references to classes defined in other HRB modules.
  5. Unloading modules that contain active registered classes.
  6. State of method references or existing instances after unloading a module.
Instance Warning

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:

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:

hb_hrbLoad() Load into VM Fetch Symbols GetFunList/Sym Execute hb_hrbDo / Eval Release Refs Objects / Blocks hb_hrbUnload() Safe Unload
Architecture Recommendation: Plugin Manager

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.

10 HRB vs. Workspace Providers

Workspace uses files with the .hbr extension located in:

Workspace Providers Directory
E:\WorkSpacein\Plugins\Providers

Currently identified provider files:

bcc.hbr fpc.hbr gcc.hbr hbmk2.hbr msvc.hbr pelles.hbr

Although the .hbr extension differs from the standard .hrb extension of Harbour Runtime Binary, inspecting these files reveals compiled Harbour module structures. Therefore:

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:

Test 1: Loadinghb_hrbLoad
  • Compile a test HRB file.
  • Load it using hb_hrbLoad().
  • Verify the returned handle and log any errors.
Test 2: Executionhb_hrbDo
  • Execute the module's entry function.
  • Verify parameter reception.
  • Check return values.
Test 3: CommunicationData Types
  • Test String, Number, and Logical exchange.
  • Test complex structures: Array, Hash, and Object.
Test 4: SymbolsIntrospection
  • Enumerate functions via hb_hrbGetFunList().
  • Lookup symbols via hb_hrbGetFunSym().
  • Invoke specific functions dynamically.
Test 5: StatePersistence
  • Modify internal STATIC variables.
  • Invoke functions repeatedly.
  • Observe state persistence across calls.
Test 6: Unloadinghb_hrbUnload
  • Release all active module references.
  • Call hb_hrbUnload().
  • Verify clean memory release.
Test 7: BindingBIND_*
  • 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.