docs/manual/adding-packages-luarocks.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 === Infrastructure for LuaRocks-based packages
   5
   6 [[luarocks-package-tutorial]]
   7
   8 ==== +luarocks-package+ tutorial
   9
  10 First, let's see how to write a +.mk+ file for a LuaRocks-based package,
  11 with an example :
  12
  13 ------------------------
  14 01: ################################################################################
  15 02: #
  16 03: # lua-foo
  17 04: #
  18 05: ################################################################################
  19 06:
  20 07: LUA_FOO_VERSION = 1.0.2-1
  21 08: LUA_FOO_NAME_UPSTREAM = foo
  22 09: LUA_FOO_DEPENDENCIES = bar
  23 10:
  24 11: LUA_FOO_BUILD_OPTS += BAR_INCDIR=$(STAGING_DIR)/usr/include
  25 12: LUA_FOO_BUILD_OPTS += BAR_LIBDIR=$(STAGING_DIR)/usr/lib
  26 13: LUA_FOO_LICENSE = luaFoo license
  27 14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING
  28 15:
  29 16: $(eval $(luarocks-package))
  30 ------------------------
  31
  32 On line 7, we declare the version of the package (the same as in the rockspec,
  33 which is the concatenation of the upstream version and the rockspec revision,
  34 separated by a hyphen '-').
  35
  36 On line 8, we declare that the package is called "foo" on LuaRocks. In
  37 Buildroot, we give Lua-related packages a name that starts with "lua", so the
  38 Buildroot name is different from the upstream name. +LUA_FOO_NAME_UPSTREAM+
  39 makes the link between the two names.
  40
  41 On line 9, we declare our dependencies against native libraries, so that they
  42 are built before the build process of our package starts.
  43
  44 On lines 11-12, we tell Buildroot to pass custom options to LuaRocks when it is
  45 building the package.
  46
  47 On lines 13-14, we specify the licensing terms for the package.
  48
  49 Finally, on line 16, we invoke the +luarocks-package+
  50 macro that generates all the Makefile rules that actually allows the
  51 package to be built.
  52
  53 [[luarocks-package-reference]]
  54
  55 ==== +luarocks-package+ reference
  56
  57 LuaRocks is a deployment and management system for Lua modules, and supports
  58 various +build.type+: +builtin+, +make+ and +cmake+. In the context of
  59 Buildroot, the +luarocks-package+ infrastructure only supports the +builtin+
  60 mode. LuaRocks packages that use the +make+ or +cmake+ build mechanisms
  61 should instead be packaged using the +generic-package+ and +cmake-package+
  62 infrastructures in Buildroot, respectively.
  63
  64 The main macro of the LuaRocks package infrastructure is +luarocks-package+:
  65 like +generic-package+ it works by defining a number of variables providing
  66 metadata information about the package, and then calling +luarocks-package+. It
  67 is worth mentioning that building LuaRocks packages for the host is not
  68 supported, so the macro +host-luarocks-package+ is not implemented.
  69
  70 Just like the generic infrastructure, the LuaRocks infrastructure works
  71 by defining a number of variables before calling the +luarocks-package+
  72 macro.
  73
  74 First, all the package metadata information variables that exist in
  75 the generic infrastructure also exist in the LuaRocks infrastructure:
  76 +LUA_FOO_VERSION+, +LUA_FOO_SOURCE+, +LUA_FOO_SITE+,
  77 +LUA_FOO_DEPENDENCIES+, +LUA_FOO_LICENSE+, +LUA_FOO_LICENSE_FILES+.
  78
  79 Two of them are populated by the LuaRocks infrastructure (for the
  80 +download+ step). If your package is not hosted on the LuaRocks mirror
  81 +$(BR2_LUAROCKS_MIRROR)+, you can override them:
  82
  83 * +LUA_FOO_SITE+, which defaults to +$(BR2_LUAROCKS_MIRROR)+
  84
  85 * +LUA_FOO_SOURCE+, which defaults to
  86   +$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).src.rock+
  87
  88 A few additional variables, specific to the LuaRocks infrastructure, are
  89 also defined. They can be overridden in specific cases.
  90
  91 * +LUA_FOO_NAME_UPSTREAM+, which defaults to +lua-foo+, i.e. the Buildroot
  92   package name
  93
  94 * +LUA_FOO_ROCKSPEC+, which defaults to
  95   +$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).rockspec+
  96
  97 * +LUA_FOO_SUBDIR+, which defaults to
  98   +$(LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION_WITHOUT_ROCKSPEC_REVISION)+
  99
 100 * +LUA_FOO_BUILD_OPTS+ contains additional build options for the
 101   +luarocks build+ call.