Emu.
Embeddable Utility Language
v1.0

Library SDK

by Aaron Kimball


This is the help/information file detailing the creation of expansion libraries for the Emu language (for use via the UseModule function).

This requires a copy of Emu, version 1.0 or higher. Installation instructions are available at the Emu homepage.

You are writing a shared object (.so) file. Thus, when compiling with gcc, always use the -shared flag. Also, your library must link against libemusdk.so (the last parameter to gcc should be -lemusdk.

Your library will contain all of the functions you wish to make available to the user, any support functions, and also a function named RegisterLibrary(). This function must be of the form: int RegisterLibrary(LPLIBRARYHANDLES hnds). RegisterLibrary() is used as a sort of "main()" for the library; it is called immediately upon loading. The function should do two things:

  1. It should pass hnds to the InitLibrary() function in the SDK library. This function will set up the pointers required to call back to the emu executable. Thus, this call should be the first one in RegisterLibrary(). InitLibrary() is prototyped as: int InitLibrary(LPLIBRARYHANDLES hnds). It returns 0 on success and 1 on failure. The pointer to the LIBRARYHANDLES structure that was passed to RegisterLibrary should be passed on without modification to InitLibrary. Should this function return 1, RegisterLibrary() should return 1 immediately as well.
  2. RegisterLibrary() must also register all user-accessable functions with Emu via the create_intrinsic_function() function. This is prototyped as: int create_intrinsic_function(char *user_name,int (*C_function_name)(char *, FILE *, FILE *, LPSAFELISTITEM, long *). (Thus, you pass it the name you want the script to access it as, in quotes, followed by the name of the handling C function.)

Language function definitions can be abbreviated using the LangFunc() macro. Simply define all your language functions as LangFunc(funcname). The parameters passed to the function are:

Other Emu functions available for use:

Emu is packaged with an example module. The modtest module (in the libemumodtest/ directory off of the source tree) demonstrates the proper way to build a module. The use of the module in an Emu script is demonstrated in test #17 (17.emu) in the bin/tests/ directory.


This document was written by Aaron Kimball (kimballa@concentric.net).
© Copyright 2001 Aaron Kimball.
Part of the Emu Language - http://emulang.sourceforge.net/.