The @native module is just a single class @native, which allows for interfacing with native code in a shared object (.so) or dynamically linked library (.dll).

Methods

Construct a native instance.

Parameters

• library — the path or name of the native library (should be a .so or .dll)

Return

• a native instance
• null if the library was not found

Declare a native function.

Parameters

• signature — a string containing the signature of the function, see notes for details

Return

• an Axiom function that wraps the specified native function
• null if the function was not found

Notes

The signature must be in the format: 'type name(type, type, ...)'

Where the first type is the return type, and subsequent types are the argument types. Possible types and their conversions are:

• void → null (return type only)
• char ↔ string of length 1 (for arguments, boolean and number will also work)
• uchar ↔ string of length 1 (for arguments, boolean and number will also work)
• bool ↔ boolean (for arguments, number will also work)
• short ↔ number (for arguments, boolean will also work)
• ushort ↔ number (for arguments, boolean will also work)
• int ↔ number (for arguments, boolean will also work)
• uint ↔ number (for arguments, boolean will also work)
• float ↔ number
• double ↔ number
• void* ↔ number (opaque, offsets will not work)
• char* ↔ string
• float* ← matrix (argument type only)
• int* ← image (argument type only)

Any type that is not one of the above is treated as void* if it ends with "*" and int otherwise, with a warning. Argument naming and extra whitespace is allowed in the signature, but other C-like syntax is not allowed: comments, semicolons, qualifiers (like "const"), etc.

Up to 9 arguments are supported. When the function is called, each argument is automatically converted to the specified native type, and the native return value is automatically converted back to the corresponding Axiom type.

The name is used to search for the function within the library's exports. To examine all exports of a library, you can do the following:

• Windows
  dumpbin.exe /exports [.dll]
• MacOS
  nm [mach .so]
• Linux
  objdump -T [elf .so]

Example

if os.platform()=='windows'
	some_library = native('some_library.dll')
else
	some_library = native('some_library.so')

narf = some_library.declare('int narf(int,char,char*)')

print narf(3,'c','axiom is great!')

## some_library.c ##
##
/*
windows compile:
cl /LD some_library.c

linux/mac compile:
gcc some_library.c -shared -fPIC -o some_library.so
*/

#include 

//on windows, you need to explicitly export each function individually
//(on linux/mac, all functions are exported by default)
#ifdef _WIN32
#define EXPORT comment(linker, "/EXPORT:"__FUNCTION__"="__FUNCDNAME__)
#endif

int narf(int i, char c, const char* s){
	#pragma EXPORT
	printf("i = %d, c = %c, s = %s\n",i,c,s);
	return 99;
}
##

##
output:
i = 3, c = c, s = axiom is great!
99
##