tarantool / tarantool/tarantool

Introduce unified Lua ffi.cdef builder

Open
#4,202 18 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

feature lua
Dominant language
Lua
Stars
3.7k
Forks
419
Avg merge
1d 23h
Merged PRs (30d)
88

Description

Lua ffi is quite fast and simple mechanism allowing to call C functions directly, without using Lua C API. It is usually faster, sometimes much faster. But ffi requires to define all the C methods again in a Lua file in ffi.cdef function. It is as bad as any other code duplication - when the original API is changed, a one could forget to update Lua files and ffi.cdef arguments. It is especially painful, when ffi C definition is really big.

Interestingly, we have exactly the same issue with module.h file - it is in fact a set of copy-pasted code blocks from some header files. But it is copy-pasted automatically. CMake calls a special routine walking over specified header files and extracting code inside /** \cond public */ and /** \endcond public */ tags.

Goal of this ticket is to introduce a similar mechanism to generate ffi C definitions. API RFC:

Option 1

File box_example.h
/* \cond ffi */

int
box_example1(void);

int
box_example2(void);

int
box_example3(void);

/* \endcond ffi */
File box_example.lua
ffi = require('ffi')
ffi.cdef_file('box_example.h')

Option 2

This option allows to collect C definitions by name, from multiple files.

File box_example.h
/* \cond lua box_example */

int
box_example1(void);

int
box_example2(void);

int
box_example3(void);

/* \endcond lua box_example */
File box_another_example.h
/* \cond lua box_example */

int
box_another_example4(void);

int
box_another_example5(void);

/* \endcond lua box_example */
File box_example.lua
ffi = require('ffi')
ffi.cdef_tag('box_example')

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read module.h and trace the CMake routine that extracts declarations between public tags. Compare that generation path with the two proposed ffi.cdef_file and ffi.cdef_tag APIs, then define how tagged declarations from one or multiple headers should become Lua FFI definitions. Done means the generated definitions stay synchronized with the marked C declarations.

Written by the indexing model from the issue text.

Assessment

Tech stack
c, cmake, lua
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.