How to make an extension

From ENIGMA
Jump to navigation Jump to search

Apparently, lots of people have been asking how to make extensions, so here's a tutorial.

Before you start, you'll want to make sure you're familiar with C++ and eYAML, and make sure that you have any prerequisites that your extension will need, and are familiar with their API.

For example, for a Lua extension, I had to get lua and its C++ binding. (make and make install http://www.lua.org/ftp/ and then apt-get install'd lua5.1 and libluabind-dev from the Ubuntu repositories. Dunno if it was all necessary, but it worked in the end).

Getting started

Navigate to enigma-dev-trunk/ENIGMAsystem/SHELL/Universal_System/Extensions/. This is currently where all extensions are housed - each extension has its own folder.

An extension folder will contain some key files, like About.ey, include.h, implement.h, Makefile, and a .cpp file containing your code, a .svg file for your extension's icon (for when the user selects or deselects your extension), and a .png prerendered version of the icon (since the extension selection system is written in Java, which doesn't currently support .svg). See Extensions for more information on these files.

It may be easier to copy over another extension folder and replace the files than to create them from scratch. In my case, I duplicated the DataStructures folder and renamed it Lua.

Then, I changed the About.ey.

%E-YAML
---

Name: Lua
Identifier: Lua
Description: Adds a Lua interpreter like a boss.
Build-date: 09/28/2011
Icon: datastructures.png

Depends: None
Dependencies: None
Implement: extension_lua

Note that Identifier should have no spaces. Name can though. Build-date probably doesn't matter. Implement seems to be in the form of extension_(lowercase Identifier). Depends documents any other ENIGMA systems that this extension may depend on, in normal About.ey format.

Now, I opened include.h. From looking at other extensions, this is where any #includes (For example, lua.h) of external libraries belongs.(After deleting Poly's code), I #included lua.h, lualib.h and luaxlib.h within an 'extern "C"', which isn't required unless the .h's are for C, not C++.

Lua requires you to link lua and dl with your project. To do that, go back into your About.ey and add in a Links: line. After that, I put -llua -ldl.

Now, for the fun part. In include.h, I added in all the functions I wanted after the extern

lua_State elua_start()
void elua_stop(lua_State state)
void elua_execute_file(lua_State state, int fileid)
void elua_execute_string(lua_State state, string execstr)

Then, I renamed data_structures.cpp to lua.cpp and modified the makefiles too.

I left implement the way it was, and moved onto lua.cpp

In there, I wrote the actual functions. For those interested, it looked like this:

#include <include.h>



typedef signed short sample_t;



lua_State elua_start() {
 lua_State *L = lua_open();
 luaL_openlibs(L);
}
void elua_stop(lua_State state) {
 lua_close(state);
}
void elua_execute_file(lua_State state, string filedir) {
 luaL_dofile(state,filedir);
}
void elua_execute_string(lua_State state, string execstr) {
 luaL_dostring(state,execstr);
}

Then, I tested it out.