edubart / nelua-decl

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:

• SDL2
  • sdl2.nelua (Platform window/input/graphics/audio manipulation)
  • sdl2_image.nelua (Read/write images)
  • sdl2_mixer.nelua (Audio mixer)
  • sdl2_ttf.nelua (Read TTF font files)
• GLFW
  • glfw.nelua (OpenGL/Vullkan framework)
• minilua (Lua)
  • lua.nelua (Lua scripting language)
• miniminiz (MiniZ)
  • miniminiz.nelua (Lossless, high performance data compression library)
• minicoro
  • minicoro.nelua (Coroutine library)
• miniaudio
  • miniaudio.nelua (Low level audio API)
  • miniaudio_engine.nelua (High level audio API)
• minifs
  • minifs.nelua (File system library)
• miniphysfs (PhysFS)
  • miniphysfs.nelua (Archive filesystem)
• STB
  • stb_image.nelua (Read images)
  • stb_image_write.nelua (Write images)
  • stb_image_resize.nelua (Resize images)
  • stb_truetype.nelua (Read TTF font files)
  • stb_vorbis.nelua (Read OGG sound files)
• Sokol
  • sokol_app.nelua (Platform window manipulation)
  • sokol_args.nelua (Platform command line arguments parser)
  • sokol_audio.nelua (Platform low level audio)
  • sokol_gfx.nelua (Platform graphics API)
  • sokol_glue.nelua
  • sokol_time.nelua (Platform time utilities)
  • sokol_nuklear.nelua (Sokol backend for Nuklear)
  • sokol_gl.nelua (Sokol 3D painter)
  • sokol_gp.nelua (Sokol 2D painter)
• Blend2D
  • blend2d.nelua (2D vector graphics engine)
• Chipmunk
  • chipmunk.nelua (2D physics library)
• Raylib
  • raylib.nelua (Simple library for creating games)
• libuv
  • uv.nelua (Asynchronous I/O)
• enet
  • enet.nelua (Reliable UDP networking library)
• znet
  • znet.nelua (Simple TCP/UDP networking library)
• curl
  • curl.nelua (Utility for HTTP request and URL data transfer)
• mongoose
  • mongoose.nelua (Embedded web server and multi-protocol networking library)
• dmon
  • dmon.nelua (Watch file changes in a directory)
• c89thread and c89atomic
  • c89thread.nelua (Threading library)
  • c89atomic.nelua (Atomics library)
• subprocess
  • subprocess.nelua (Process launching library)
• mjson
  • mjson.nelua (Lightweight JSON parser/emitter library)
• cJSON
  • cJSON.nelua (Easy JSON parser/emitter library)
• sqlite3
  • sqlite3.nelua (SQLite3 database)
• nuklear
  • nuklear.nelua (Immediate UI library)
• mbedtls
  • nuklear.nelua (Cryptographic library)
• MIR
  • mir.nelua (A lightweight JIT compiler and C11 JIT compiler/interpreter based on MIR)
• Lexbor
  • lexbor.nelua (HTML/CSS/DOM parser/engine)
• tree-sitter
  • tree-sitter.nelua (A parser generator tool and an incremental parsing library)
• microui
  • microui.nelua (A tiny, portable, immediate-mode UI library)
• msf_gif
  • msf_gif.nelua (A single-header animated GIF exporter) Plus the following platform specific libraries:
• dl
  • dl.nelua (Unix dynamic library loader)
• pthread
  • pthread.nelua (POSIX threads)
• POSIX
  • unistd.nelua (Essential POSIX functions)
  • dirent.nelua (Directory control options)
  • errno.nelua (Error handling)
  • fcntl.nelua (File control options)
  • signal.nelua (Signal handling)
  • termios.nelua (Manipulate terminal I/O)
  • time.nelua (Date and time)
  • sys/stat.nelua (File attributes)
  • And some other POSIX APIs, check the directory
• Linux
  • inotify.nelua (Linux filesystem watcher)
  • epoll.nelua (Linux I/O event notification facility)
  • iouring.nelua (Linux newest IO interface)
• Windows
  • windows.nelua (Windows APIs)
• Emscripten
  • emscripten.nelua (Emscripten APIs)
• X11
  • x11.nelua (X11 Window APIs)
• WAMR
  • wamr.nelua (WASM Micro Runtime APIs)

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.