// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

=== Infrastructure for LuaRocks-based packages

[[luarocks-package-tutorial]]

==== +luarocks-package+ tutorial

First, let's see how to write a +.mk+ file for a LuaRocks-based package,
with an example :

------------------------
01: ################################################################################
02: #
03: # lua-foo
04: #
05: ################################################################################
06:
07: LUA_FOO_VERSION = 1.0.2-1
08: LUA_FOO_NAME_UPSTREAM = foo
09: LUA_FOO_DEPENDENCIES = bar
10:
11: LUA_FOO_BUILD_OPTS += BAR_INCDIR=$(STAGING_DIR)/usr/include
12: LUA_FOO_BUILD_OPTS += BAR_LIBDIR=$(STAGING_DIR)/usr/lib
13: LUA_FOO_LICENSE = luaFoo license
14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING
15:
16: $(eval $(luarocks-package))
------------------------

On line 7, we declare the version of the package (the same as in the rockspec,
which is the concatenation of the upstream version and the rockspec revision,
separated by a hyphen '-').

On line 8, we declare that the package is called "foo" on LuaRocks. In
Buildroot, we give Lua-related packages a name that starts with "lua", so the
Buildroot name is different from the upstream name. +LUA_FOO_NAME_UPSTREAM+
makes the link between the two names.

On line 9, we declare our dependencies against native libraries, so that they
are built before the build process of our package starts.

On lines 11-12, we tell Buildroot to pass custom options to LuaRocks when it is
building the package.

On lines 13-14, we specify the licensing terms for the package.

Finally, on line 16, we invoke the +luarocks-package+
macro that generates all the Makefile rules that actually allows the
package to be built.

Most of these details can be retrieved from the +rock+ and +rockspec+.
So, this file and the Config.in file can be generated by running the
command +luarocks buildroot foo lua-foo+ in the Buildroot
directory. This command runs a specific Buildroot addon of +luarocks+
that will automatically generate a Buildroot package. The result must
still be manually inspected and possibly modified.

* The +package/Config.in+ file has to be updated manually to include the
  generated Config.in files.

[[luarocks-package-reference]]

==== +luarocks-package+ reference

LuaRocks is a deployment and management system for Lua modules, and supports
various +build.type+: +builtin+, +make+ and +cmake+. In the context of
Buildroot, the +luarocks-package+ infrastructure only supports the +builtin+
mode. LuaRocks packages that use the +make+ or +cmake+ build mechanisms
should instead be packaged using the +generic-package+ and +cmake-package+
infrastructures in Buildroot, respectively.

The main macro of the LuaRocks package infrastructure is +luarocks-package+:
like +generic-package+ it works by defining a number of variables providing
metadata information about the package, and then calling +luarocks-package+. It
is worth mentioning that building LuaRocks packages for the host is not
supported, so the macro +host-luarocks-package+ is not implemented.

Just like the generic infrastructure, the LuaRocks infrastructure works
by defining a number of variables before calling the +luarocks-package+
macro.

First, all the package metadata information variables that exist in
the generic infrastructure also exist in the LuaRocks infrastructure:
+LUA_FOO_VERSION+, +LUA_FOO_SOURCE+, +LUA_FOO_SITE+,
+LUA_FOO_DEPENDENCIES+, +LUA_FOO_LICENSE+, +LUA_FOO_LICENSE_FILES+.

Two of them are populated by the LuaRocks infrastructure (for the
+download+ step). If your package is not hosted on the LuaRocks mirror
+$(BR2_LUAROCKS_MIRROR)+, you can override them:

* +LUA_FOO_SITE+, which defaults to +$(BR2_LUAROCKS_MIRROR)+

* +LUA_FOO_SOURCE+, which defaults to
  +$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).src.rock+

A few additional variables, specific to the LuaRocks infrastructure, are
also defined. They can be overridden in specific cases.

* +LUA_FOO_NAME_UPSTREAM+, which defaults to +lua-foo+, i.e. the Buildroot
  package name

* +LUA_FOO_ROCKSPEC+, which defaults to
  +$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).rockspec+

* +LUA_FOO_SUBDIR+, which defaults to
  +$(LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION_WITHOUT_ROCKSPEC_REVISION)+

* +LUA_FOO_BUILD_OPTS+ contains additional build options for the
  +luarocks build+ call.