greenServeFE logogreenServeFELanguage, VM and Native Module Reference

Documentation home / Native C Module Development

Developer guide · Native API · ABI 1

Build Native C Modules for greenServeFE

The greenServeFE Native API lets developers extend the language runtime with their own C code. Write a C source file, expose functions as GSVE values, compile it into a Linux shared library (.so), and import that module from a .gsve program. You do not need to modify or rebuild the greenServeFE language runtime to create an independent native module.

SDK release: greenServeFE-module-SDK-v1.0.0

Linux x86_64 SDK archive containing the public native API header and the greenServeFE runtime used to compile and integration-test native modules.

View SDK release · Download Linux x86_64 SDK (.tar.gz) · Reference build workflow

C11Linux x86_64.so shared modulesNative ABI 1

On this page

  1. How native modules work
  2. Download and prepare the SDK
  3. ABI and module contract
  4. Write your first C module
  5. Native API reference
  6. Values, collections and ownership
  7. Calling GSVE functions from C
  8. Compile the shared library
  9. Load and use the module
  10. Verify and troubleshoot
  11. Package and distribute a module
  12. Security and compatibility

1. How native modules work

A native module is a C shared library that follows the greenServeFE Native Module ABI. The runtime loads the library when a GSVE program imports its module name. The library must export one well-known initializer, greenServeFE_module_init. That initializer receives a pointer to the runtime's GSNativeAPI function table and returns a GSVE object containing the functions and values that the language should expose.

01 · Prepare

Download SDK

Get module_api.h and the matching greenServeFE runtime from the SDK archive.

02 · Develop

Write C source

Implement C functions using GSValue and the GSNativeAPI table.

03 · Compile

Build a .so

Compile with GCC, -fPIC and -shared.

04 · Integrate

Import in GSVE

Put the shared library on the module path and call its exported functions.

The resulting relationship is:

your_module.c  +  module_api.h
          │
          ▼
      GCC compiler
          │
          ▼
    your_module.so
          │
          ▼
GREENSERVE_MODULE_PATH
          │
          ▼
import your_module;
          │
          ▼
your_module.exported_function()

2. Download and prepare the SDK

The supported reference workflow downloads the versioned SDK archive directly from the greenServeFE release. It installs ordinary Linux build tools, extracts the archive, locates the public header named module_api.h and the executable greenServeFE, and copies both into a predictable working location.

Install build dependencies

sudo apt-get update
sudo apt-get install -y build-essential binutils curl tar zip

Download and extract greenServeFE-module-SDK-v1.0.0

set -eu

SDK_URL="https://github.com/dominexmacedon-docs/greenServeFE-/releases/download/greenServeFE-module-SDK-v1.0.0/greenServeFE-native-api-linux-x86_64.tar.gz"
SDK_ARCHIVE="$PWD/greenServeFE-native-api-linux-x86_64.tar.gz"
SDK_DIR="$PWD/greenServeFE-native-api"

curl --fail --location --retry 3 --retry-delay 2 "$SDK_URL" -o "$SDK_ARCHIVE"
mkdir -p "$SDK_DIR"
tar -xzf "$SDK_ARCHIVE" -C "$SDK_DIR"

HEADER="$(find "$SDK_DIR" -type f -name module_api.h -print -quit)"
RUNTIME="$(find "$SDK_DIR" -type f -name greenServeFE -perm -u+x -print -quit)"

if [ -z "$HEADER" ]; then
  echo "module_api.h was not found in the SDK." >&2
  find "$SDK_DIR" -maxdepth 4 -type f -print >&2
  exit 1
fi

if [ -z "$RUNTIME" ]; then
  echo "The greenServeFE runtime was not found in the SDK." >&2
  find "$SDK_DIR" -maxdepth 4 -type f -print >&2
  exit 1
fi

mkdir -p sdk
install -m 0644 "$HEADER" sdk/module_api.h
install -m 0755 "$RUNTIME" sdk/greenServeFE
sdk/greenServeFE --version
The archive is versioned. Build against the header and runtime supplied by the same SDK release so the module is compiled against the intended ABI contract.

3. ABI and module contract

The public C interface is declared in module_api.h. The current ABI version is GSFE_MODULE_ABI_VERSION, whose value is 1u. The initializer symbol is GSFE_MODULE_INIT_SYMBOL, defined as "greenServeFE_module_init".

#define GSFE_MODULE_ABI_VERSION 1u
#define GSFE_MODULE_INIT_SYMBOL "greenServeFE_module_init"

typedef GSValue (*GSModuleInit)(const GSNativeAPI *api);

GSValue greenServeFE_module_init(const GSNativeAPI *api);

Your shared library must satisfy these requirements:

The native callback type is GSValue (*GSNativeFn)(GSValue *args, size_t count). Each native function receives its arguments as an array of GSValue values and the number of arguments supplied, then returns a GSValue.

4. Write your first C module

Create a file named hello_native.c. This example exports a version function, a greeting function and an addition function. It follows the same initializer and value-management pattern used by the published test-g example.

#include "module_api.h"

#include <stdio.h>

static const GSNativeAPI *api;

static GSValue hello_version(GSValue *args, size_t count) {
    (void)args;
    (void)count;
    return api->string("1.0.0");
}

static GSValue hello_greet(GSValue *args, size_t count) {
    const char *name = count > 0 ? api->cstring(args[0]) : NULL;
    if (!name || !*name) name = "greenServeFE developer";

    char message[512];
    int written = snprintf(message, sizeof(message), "Hello, %s!", name);
    if (written < 0 || (size_t)written >= sizeof(message)) {
        return api->null();
    }
    return api->string(message);
}

static GSValue hello_add(GSValue *args, size_t count) {
    if (count < 2) return api->null();

    double total = 0.0;
    for (size_t i = 0; i < count; ++i) {
        if (args[i].type != V_NUMBER) return api->null();
        total += api->number_value(args[i]);
    }
    return api->number(total);
}

GSValue greenServeFE_module_init(const GSNativeAPI *native_api) {
    if (!native_api ||
        native_api->abi_version != GSFE_MODULE_ABI_VERSION ||
        !native_api->object ||
        !native_api->native ||
        !native_api->object_set ||
        !native_api->release) {
        return native_api && native_api->null
            ? native_api->null()
            : (GSValue){0};
    }

    api = native_api;
    GSValue exports = api->object();

    GSValue fn = api->native(hello_version);
    api->object_set(&exports, "version", fn);
    api->release(fn);

    fn = api->native(hello_greet);
    api->object_set(&exports, "greet", fn);
    api->release(fn);

    fn = api->native(hello_add);
    api->object_set(&exports, "add", fn);
    api->release(fn);

    return exports;
}

Important details:

5. Native API reference

GSNativeAPI is a function table supplied by the runtime. Use these function pointers instead of linking your module directly to private runtime implementation functions.

API memberPurpose
abi_versionABI version supplied by the runtime. Compare it with GSFE_MODULE_ABI_VERSION.
null()Create a null GSVE value.
number(double)Create a numeric value.
boolean(int)Create a boolean value.
string(const char *)Create a GSVE string from a C string.
object()Create an object value for module exports or structured data.
array()Create an array value.
native(GSNativeFn)Wrap a C callback as a callable GSVE native function.
copy(GSValue)Create a copied GSVE value using the runtime's value-copy operation.
retain(GSValue)Retain a value when your code needs to keep an owned reference.
release(GSValue)Release a reference owned by your native code when it is no longer needed.
array_push(GSValue *, GSValue)Append a value to an array.
array_count(GSValue)Return the number of elements in an array.
array_get(GSValue, size_t)Read an array element by index.
array_set(GSValue *, size_t, GSValue)Set an existing array element; returns an integer status.
object_count(GSValue)Return the number of properties in an object.
object_key(GSValue, size_t)Read the key at an object property index.
object_set(GSValue *, const char *, GSValue)Set an object property.
object_get(GSValue, const char *)Read an object property by key.
cstring(GSValue)Access the C-string representation of a GSVE string.
truthy(GSValue)Evaluate a GSVE value using the runtime's truthiness rules.
number_value(GSValue)Read the numeric payload of a GSVE value.
print(FILE *, GSValue)Print a GSVE value to the supplied C stream.
contextOpaque runtime context passed back to the callback bridge.
call(void *, GSValue, GSValue *, size_t, GSValue *)Callback bridge entry point for invoking a GSVE callable value from native code.

6. Values, collections and ownership

Native functions exchange values using GSValue. The public value definition includes a type field and a typed payload. The type constants available in the SDK include:

TypeMeaning
V_NULLNull value.
V_NUMBERDouble-precision number.
V_BOOLBoolean value.
V_STRINGString value.
V_ARRAYArray collection.
V_OBJECTObject collection.
V_FUNCTIONGSVE-defined function.
V_NATIVENative C function.
V_ITERIterator value.

Read arguments safely

static GSValue inspect_value(GSValue *args, size_t count) {
    if (count == 0) return api->null();

    if (args[0].type == V_NUMBER) {
        double n = api->number_value(args[0]);
        return api->number(n * 2.0);
    }

    if (args[0].type == V_STRING) {
        const char *s = api->cstring(args[0]);
        if (s) return api->string(s);
    }

    return api->null();
}

Create and populate an array

GSValue values = api->array();

GSValue first = api->number(10);
api->array_push(&values, first);
api->release(first);

GSValue second = api->number(20);
api->array_push(&values, second);
api->release(second);

size_t length = api->array_count(values);
GSValue item = api->array_get(values, 0);

/* Release values your code owns when finished. */
api->release(item);
api->release(values);

Create and read an object

GSValue record = api->object();
GSValue name = api->string("Ada");
GSValue score = api->number(100);

api->object_set(&record, "name", name);
api->object_set(&record, "score", score);

api->release(name);
api->release(score);

GSValue stored_name = api->object_get(record, "name");
const char *name_text = api->cstring(stored_name);

/* Use name_text while the corresponding value remains valid. */
api->release(stored_name);
api->release(record);
Ownership is part of the ABI. Follow the ownership behavior defined by the SDK header and runtime. The established module pattern releases temporary values after inserting them into a container. Do not keep borrowed pointers from cstring beyond the lifetime of the value that backs them. Retain values you need to keep, and release references your module owns. Avoid releasing a borrowed argument merely because you have finished reading it.

7. Calling GSVE functions from C

The API table includes context and call for the native-to-GSVE callback bridge. This allows a native extension to invoke a GSVE callable value supplied to it, rather than limiting communication to values flowing from GSVE into C.

void *context;
int (*call)(
    void *context,
    GSValue callable,
    GSValue *args,
    size_t count,
    GSValue *result
);

The callback bridge receives the runtime context, the callable GSVE value, an argument array and its length, and an output location for the returned value. Check that api->call is available before using it, pass the supplied api->context, and check the returned status before consuming the output value. Follow the value ownership rules for the returned result.

Use the callback bridge when your native module needs to call a GSVE function passed into a native API, such as a user-provided callback. Keep the original GSVE callable value valid for the duration required by the call.

8. Compile the shared library

Compile the C file with GCC using the SDK header. The important flags are -std=c11 for the C language standard, -fPIC for position-independent code and -shared to produce a shared library.

mkdir -p build

gcc -std=c11 -O2 -Wall -Wextra -Wpedantic -fPIC -shared \
  -Isdk \
  -o build/hello_native.so \
  hello_native.c

Check that the expected initializer is exported:

nm -D --defined-only build/hello_native.so | grep greenServeFE_module_init
file build/hello_native.so

The output file name determines the import name. For example, hello_native.so is imported as hello_native in GSVE. Use a simple module filename that matches the identifier used by your import statement.

9. Load and use the module

Create a GSVE test file named hello_native.gsve:

import hello_native;

print(hello_native.version());
print(hello_native.greet("Ada"));
print(hello_native.add(10, 20, 30));

Set the module search path to the directory containing the shared library, then execute the program with the SDK runtime:

export GREENSERVE_MODULE_PATH="$PWD/build"
export LD_LIBRARY_PATH="$PWD/build:${LD_LIBRARY_PATH:-}"
sdk/greenServeFE hello_native.gsve

GREENSERVE_MODULE_PATH tells greenServeFE where to find native modules. LD_LIBRARY_PATH helps the operating system's dynamic loader find shared-library dependencies when your module has any. The module search path and the operating-system library search path serve different purposes.

10. Verify and troubleshoot

SymptomWhat to check
module_api.h not foundConfirm that the SDK archive was extracted and that the compiler include path points to the directory containing the header, for example -Isdk.
Initializer symbol not foundRun nm -D --defined-only your_module.so and confirm that greenServeFE_module_init is exported with the exact spelling.
Module cannot be locatedConfirm the .so filename matches the import name and that GREENSERVE_MODULE_PATH points to its containing directory.
Shared-library dependency cannot be loadedInspect dependencies with ldd your_module.so and provide the required libraries through the system's normal library search configuration.
ABI mismatchBuild against the module_api.h from the intended SDK and check api->abi_version against GSFE_MODULE_ABI_VERSION.
Unexpected null or incorrect resultCheck argument count, each argument's GSValue.type, conversion calls, return values and ownership handling.
Runtime works but a dependency is missing on another machineDocument and package the dependency or use an available system library. A native module is not automatically a self-contained executable.

A minimal integration test should verify the exported symbol, load the module with the target runtime, call every exported function with valid inputs, and test invalid argument counts and types. The published test-g example source demonstrates several exports, while its GitHub Actions workflow automates SDK download, compilation, symbol verification, runtime integration testing and ZIP packaging.

11. Package and distribute a module

A distributable native module should include enough material for users and maintainers to understand, verify and rebuild it. A practical Linux x86_64 package layout is:

hello-native-linux-x86_64/
├── hello_native.c
├── module_api.h
├── hello_native.so
├── hello_native.gsve
└── README.md

Include the module's source, the public header used for the build, the compiled shared library, a small GSVE integration test and instructions describing the runtime and ABI requirements. State the target operating system and CPU architecture clearly. If the module depends on other shared libraries, list those dependencies and their required versions.

Reproducible build and release checklist

12. Security and compatibility

Native modules execute native code. They are trusted extensions, not sandboxed GSVE scripts. A loaded module can exercise the operating-system permissions of the process. Only load native modules from sources you trust, and review C code and external dependencies before deployment.