REBOL 3 Concepts: Extensions: Embedded Extensions

Explains how to embed extensions into a REBOL executable (using the host-kit).

Basics

This feature allows you to extend REBOL by embedding your own native and mezzanine code and data within a REBOL executable program. Embedding an extension makes it possible to use the extension and its native command functions without requiring a separate DLL library to accompany your executable program.

Not always necessary

If your embedded module consists entirely of REBOL code (no native commands), it's not required that you embed it in the way described here. Instead, you can add it to the host bundled source code which initialized in the host in the line:

RL_Do_Binary(Reb_Init_Code, REB_INIT_SIZE, 0, 0);

More on this is described in the host-kit documentation.

Steps

If you already know how to make an extension (from prior pages), embedding it is trivial.

The steps are:

Create a new extension as described in previous sections. It is only necessary to create the RX_Call function. The RX_Init and RX_Quit functions are not required.
Add one or more extensions by calling the RL_Extend function. This can be done directly in host-main.c or via a function called from that module.

This function is defined as:

RL_API void *RL_Extend(REBYTE *source, RXICAL call);

It accepts as arguments the UTF-8/ASCII source code for a module, along with a pointer to its command dispatcher function.

These values are added to the system/catalog/boot-exts block. Later in the boot process, the boot-exts block is processed to import each of its embedded modules.

Future Features

In the future, it may be possible to provide embedded extensions that do not automatically import on boot. Such extensions would be added to the module list, but would not be otherwise initialized. Later, a program could call import with the module name to initialize access to it.

Example

We define an extension module:

char *ext =
    "REBOL [\n"
        "Title: {Hosted extension}\n"
        "Name: hosted\n"
        "Type: module\n"
        "Exports: [add-mul]\n"
    "]\n"
    "add-mul: command [{Add and multiply integers.} a b c]\n"
;

and a simple call dispatcher function:

RXIEXT int RX_Call(int cmd, RXIFRM *frm, REBCEC *ctx) {
    RXA_INT64(frm, 1) =
        (RXA_INT64(frm, 1) + RXA_INT64(frm, 2)) *
        RXA_INT64(frm, 3);
    return RXR_VALUE;
}

We then call the RL_Extend function to add it during boot. This is done in the host-main.c code before (or after, it's your choice) the bundled source code init call:

RL_Extend(hext, &RX_Call);

// Initialize host bundled source code:
RL_Do_Binary(Reb_Init_Code, REB_INIT_SIZE, 0, 0);

After REBOL boots, we can call the add-mul command that was provided:

print add-mul 1 2 3
9

Note that multiple embedded extensions can be added in the same way.

Editor note: how to use the make-ext tool for creating it. Also, mention the host-ext-test.c example.

REBOL 3 Concepts: Extensions: Embedded Extensions

Contents

Basics

Steps

Example