Documentation home / Native C Module Development
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.
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 1On this page
- How native modules work
- Download and prepare the SDK
- ABI and module contract
- Write your first C module
- Native API reference
- Values, collections and ownership
- Calling GSVE functions from C
- Compile the shared library
- Load and use the module
- Verify and troubleshoot
- Package and distribute a module
- 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.
Download SDK
Get module_api.h and the matching greenServeFE runtime from the SDK archive.
Write C source
Implement C functions using GSValue and the GSNativeAPI table.
Build a .so
Compile with GCC, -fPIC and -shared.
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
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:
- Export a function with the exact name
greenServeFE_module_init. - Use the initializer signature
GSValue greenServeFE_module_init(const GSNativeAPI *api). - Check that
apiis not null and thatapi->abi_versionequalsGSFE_MODULE_ABI_VERSION. - Return a GSVE object whose properties are the functions or values you want to expose.
- Create callable exports with
api->native(your_c_function)and attach them to the returned object. - Compile the library as a position-independent shared object.
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:
static const GSNativeAPI *apistores the runtime API table pointer for the callbacks in this simple module pattern.api->cstringconverts a GSVE string value to a C string pointer for reading. Check for a null pointer before using it.api->number_valuereads a numeric value after checking its type.api->string,api->numberandapi->nullconstruct GSVE values.- After inserting a newly created native function into the exports object, the example releases its temporary reference with
api->release. - Validate argument count and types in every exported function. Return
api->null()for invalid input in this example; a module may define a more specific error-reporting convention if its host integration provides one.
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 member | Purpose |
|---|---|
abi_version | ABI 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. |
context | Opaque 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:
| Type | Meaning |
|---|---|
V_NULL | Null value. |
V_NUMBER | Double-precision number. |
V_BOOL | Boolean value. |
V_STRING | String value. |
V_ARRAY | Array collection. |
V_OBJECT | Object collection. |
V_FUNCTION | GSVE-defined function. |
V_NATIVE | Native C function. |
V_ITER | Iterator 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);
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
| Symptom | What to check |
|---|---|
module_api.h not found | Confirm 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 found | Run nm -D --defined-only your_module.so and confirm that greenServeFE_module_init is exported with the exact spelling. |
| Module cannot be located | Confirm the .so filename matches the import name and that GREENSERVE_MODULE_PATH points to its containing directory. |
| Shared-library dependency cannot be loaded | Inspect dependencies with ldd your_module.so and provide the required libraries through the system's normal library search configuration. |
| ABI mismatch | Build against the module_api.h from the intended SDK and check api->abi_version against GSFE_MODULE_ABI_VERSION. |
| Unexpected null or incorrect result | Check argument count, each argument's GSValue.type, conversion calls, return values and ownership handling. |
| Runtime works but a dependency is missing on another machine | Document 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
- Download the versioned SDK release and use its public header.
- Compile with warnings enabled and fail the build when compilation fails.
- Verify that
greenServeFE_module_initis present in the dynamic symbol table. - Run a GSVE integration program using the SDK runtime and the module search path.
- Test normal inputs, invalid inputs and relevant boundary conditions.
- Package the source, header, binary, test program and README.
- Test the archive itself before publishing it.
- Publish a versioned release and document its ABI and platform compatibility.
12. Security and compatibility
- Platform compatibility: a Linux x86_64
.sois not a Windows DLL or macOS dynamic library. Build and test separately for each supported platform and architecture. - ABI compatibility: compile against the SDK header matching the runtime ABI you target. Do not assume that a binary built for one ABI version will work with another.
- Memory safety: validate pointers, lengths, argument counts and value types. Avoid buffer overflows and use bounded C operations.
- Dependencies: declare external library requirements and test on a clean environment that resembles the target deployment system.
- Concurrency: design shared module state carefully if callbacks may be invoked from different execution contexts. Do not assume thread-safety guarantees that are not documented by the runtime.
- Failure handling: check optional function pointers before use, check callback status values, and return valid GSVE values from native callbacks.
