Skip to content

C binding generator for Nelua using GCC Lua plugin.

Notifications You must be signed in to change notification settings

edubart/nelua-decl

Repository files navigation

C binding generator for Nelua using GCC Lua plugin.

This tool assists creating C bindings for any C library for Nelua in a few steps, also enables the possibility to customize each library bindings via Lua scripts. Requires GCC to run.

Note: You need GCC plugin mechanism to use this (only available in Linux systems).

Bindings example

The following cross-platform libraries bindings are ready and generated as example:

How to generate bindings

Make sure you are using Lua 5.3+, GCC 9+ and have GCC plugin installed.

First clone and compile the gcc-lua plugin and compile it:

git clone --recurse-submodules https://github.com/edubart/nelua-decl.git
make -C gcc-lua

Some libraries such as SDL2, GLFW must be installed on your system.

To generate bindings for a library simply do make generate in its folder. For example, the following will generate libs/sdl2/sdl2.nelua and then run a test to check if it's working:

cd libs/sdl2
make generate
make test

Some single header libraries you must be downloaded with make download, for example:

cd libs/minilua
make download
make generate
make test

How to generate bindings for a new library

Suppose you want generate bindings for mylib, create a new folder mylib in libs/, then you must create the following files:

  • mylib.c - A C file including all C headers that have the functions we want to bind.
  • mylib.lua - A lua file with binding generator rules.
  • Makefile - A Makefile script to assist generating the bindings.

For a quick start, see the Makefile, .lua and .c files of the current bundled libraries as an example.

How it works

The bindings are generated using the following command:

gcc -S libs/lua/lua.c \
    -fplugin=./gcc-lua/gcc/gcclua.so \
    -fplugin-arg-gcclua-script=libs/lua/lua.lua \
    > libs/lua/lua.nelua

Command explanation:

  • -S libs/lua/lua.c tells GCC to compile only the assembly instructions for the file, this is sufficient for parsing.
  • -fplugin=./gcc-lua/gcc/gcclua.so tells GCC to load the gcc-lua plugin before compiling.
  • -fplugin-arg-gcclua-script=libs/lua/lua.lua is the lua script loaded with configurations to generate the bindings.
  • libs/lua/lua.nelua is the output file.

Caveats

Some limitations:

  • C bit fields are not supported.
  • C unnamed fields are not supported.
  • C math complex type is not supported.
  • C macros are hidden and requires some manual work to expose them.
  • Currently GCC plugin does not work on Windows, thus you have to generate bindings from a Linux machine.

Usually to create bindings for a new library requires little manual work for C libraries that are binding friendly to other languages. A binding friendly C libraries have the following characteristics:

  • No use of platform dependent function declarations, constants and structs in its API.
  • Constants are declared as enums instead of macros.
  • Functions are declared as C functions and not macros.
  • It doesn't use unnamed fields.
  • It doesn't use bit fields.

About

C binding generator for Nelua using GCC Lua plugin.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages