Lua module template for Tarantool 1.6+

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

Note: If you write a Tarantool module in C, see the ckit branch of this repository.

Table of contents

• Kit content
• Prerequisites
• Examples
• See also

Kit content

• ./README.md - this file
• ./luakit/init.lua - the Lua module itself, loaded with require('luakit')
• ./luakit-scm-1.rockspec - a specification for the tarantool/rocks repository
• ./test/luakit.test.lua - tests for the module
• ./rpm/ - files to build an RPM package
• ./debian/ - files to build a DEB package

Prerequisites

Tarantool 1.6.8+ with header files (tarantool and tarantool-dev packages)

Usage

1. Clone this repository.

   git clone https://github.com/tarantool/modulekit.git

   The default branch is luakit, which is what you need for a module in pure Lua.

2. Rename all files to use your favorite name.

   For example, mymodule:

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

3. Implement your code in ./mymodule/.

   You will have one or more Lua modules that export their functions for API calls.

   As an example, see the Lua module luakit/init.lua from the luakit package. Here we have one internal function (test()), and we export it as test for API calls.

   As a result, after we publish the luakit package in step 7, Tarantool users will be able to load the package and call the function test() with require('luakit').test(arg).

   Note: The basics of creating a Lua module for Tarantool are explained in the Tarantool manual.

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

   prove -v ./test/luakit.test.lua or ./test/luakit.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 luakit-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

• Lua module example
• One more Lua module example

See also

• Tarantool/Lua API Reference
• Modulekit for Tarantool modules in C