Skip to content

Latest commit

 

History

History
160 lines (120 loc) · 5.72 KB

README.md

File metadata and controls

160 lines (120 loc) · 5.72 KB
Raw

C module template for Tarantool 1.6+

Use this template to create and publish a Tarantool module written in C.

Note: If you write a Tarantool module in pure Lua only, see the luakit branch of this repository.

Table of contents

Kit content

  • ./README.md - this file
  • ./ckit/init.lua - the Lua module itself, loaded with require('ckit')
  • ./ckit/lib.c - C module
  • ./test/ckit.test.lua - tests for the module
  • ./ckit-scm-1.rockspec - a specification for the tarantool/rocks repository
  • ./rpm/ - files to build an RPM package
  • ./debian/ - files to build a DEB package
  • ./CMakeLists.txt, ./FindTarantool.cmake - CMake scripts (only needed for C modules)

Prerequisites

Tarantool 1.6.5+ with header files (tarantool, tarantool-dev and libmsgpuck-dev packages)

Usage

  1. Clone this repository and switch to the ckit branch.

    git clone https://github.com/tarantool/modulekit.git
git fetch origin
git checkout -b ckit origin/ckit

  2. Rename all files to use your favorite name.

    For example, mymodule:

    grep -R ckit .
mv ckit/ mymodule/
mv test/ckit.test.lua test/mymodule.test.lua
...

  3. Implement your code in ./mymodule/.

    You will have one or more C modules, which export their functions for API calls. Also, you may have Lua modules, which in their turn may re-export the C modules' functions for API calls.

    As an example, see the following modules from the ckit package:

    • ckit/lib.c - a C module. Here we have one internal function (ckit_func()) and export another function (luaopen_ckit_lib()) which uses ckit_func().
    • ckit/init.lua - a Lua module. Here we load the C module with require('ckit.lib') and then re-export it as cfunc function for API calls. Also, we have a Lua function (func()) that uses the exported C function from ckit.lib, and we export this Lua function as func function.

    As a result, after we publish the ckit package in step 7, Tarantool users will be able to load the package and call two functions:

    • the C function luaopen_ckit_lib() - with require('ckit.lib').func(args) or require('ckit').cfunc(args), and
    • the Lua function func() - with require('ckit').func(args).

  4. Add tests to ./test/mymodule.test.lua:

    prove -v ./test/ckit.test.lua or ./test/ckit.test.lua

  5. Update copyright and README files.

  6. Push all files except rpm/, debian/ and mymodule-scm-1.rockspec.

  7. Update and check the rockspec.

    A .rockspec file wraps a module into a package. This is what you can publish. If you are new to Lua rocks, see general information on rockspec format and creation.

    Your rockspec must comply with these requirements and allow to build and install your package locally:

    luarocks install --local mymodule-scm-1.rockspec

    See an annotated rockspec example in ckit-scm-1.rockspec.

  8. Push your rockspec and make a pull request to the tarantool/rocks repository.

    The Tarantool team will review the request and decide on including your package in Tarantool rocks list and official Tarantool images for Docker.

  9. [Optional] Check DEB packaging and push debian/ to GitHub.

    dpkg-buildpackage -D -b -us -uc
ls -l ../*.deb

  10. [Optional] Check RPM packaging and push rpm/ to GitHub.

    tar cvzf ~/rpmbuild/SOURCES/tarantool-mymodule-1.0.0.tar.gz
rpmbuild -b rpm/tarantool-mymodule.spec

Enjoy! Thank you for contributing to Tarantool.

Examples

See also