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: # luafoo
  17 04: #
  18 05: ################################################################################
  19 06:
  20 07: LUAFOO_VERSION = 1.0.2-1
  21 08: LUAFOO_DEPENDENCIES = foo
  22 09:
  23 10: LUAFOO_BUILD_OPTS += FOO_INCDIR=$(STAGING_DIR)/usr/include
  24 11: LUAFOO_BUILD_OPTS += FOO_LIBDIR=$(STAGING_DIR)/usr/lib
  25 12: LUAFOO_LICENSE = luaFoo license
  26 13: LUAFOO_LICENSE_FILES = COPYING
  27 14:
  28 15: $(eval $(luarocks-package))
  29 ------------------------
  30
  31 On line 7, we declare the version of the package (the same as in the rockspec,
  32 which is the concatenation of the upstream version and the rockspec revision,
  33 separated by a hyphen '-').
  34
  35 On line 8, we declare our dependencies against native libraries, so that they
  36 are built before the build process of our package starts.
  37
  38 On lines 10-11, we tell Buildroot to pass custom options to LuaRocks when it is
  39 building the package.
  40
  41 On lines 12-13, we specify the licensing terms for the package.
  42
  43 Finally, on line 15, we invoke the +luarocks-package+
  44 macro that generates all the Makefile rules that actually allows the
  45 package to be built.
  46
  47 [[luarocks-package-reference]]
  48
  49 ==== +luarocks-package+ reference
  50
  51 LuaRocks is a deployment and management system for Lua modules, and supports
  52 various +build.type+: +builtin+, +make+ and +cmake+. In the context of
  53 Buildroot, the +luarocks-package+ infrastructure only supports the +builtin+
  54 mode. LuaRocks packages that use the +make+ or +cmake+ build mechanisms
  55 should instead be packaged using the +generic-package+ and +cmake-package+
  56 infrastructures in Buildroot, respectively.
  57
  58 The main macro of the LuaRocks package infrastructure is +luarocks-package+:
  59 like +generic-package+ it works by defining a number of variables providing
  60 metadata information about the package, and then calling +luarocks-package+. It
  61 is worth mentioning that building LuaRocks packages for the host is not
  62 supported, so the macro +host-luarocks-package+ is not implemented.
  63
  64 Just like the generic infrastructure, the LuaRocks infrastructure works
  65 by defining a number of variables before calling the +luarocks-package+
  66 macro.
  67
  68 First, all the package metadata information variables that exist in
  69 the generic infrastructure also exist in the LuaRocks infrastructure:
  70 +LUAFOO_VERSION+, +LUAFOO_SOURCE+, +LUAFOO_SITE+,
  71 +LUAFOO_DEPENDENCIES+, +LUAFOO_LICENSE+, +LUAFOO_LICENSE_FILES+.
  72
  73 Two of them are populated by the LuaRocks infrastructure (for the
  74 +download+ step). If your package is not hosted on the LuaRocks mirror
  75 +$(BR2_LUAROCKS_MIRROR)+, you can override them:
  76
  77 * +LUAFOO_SITE+, which defaults to +$(BR2_LUAROCKS_MIRROR)+
  78
  79 * +LUAFOO_SOURCE+, which defaults to +luafoo-$(LUAFOO_VERSION).src.rock+
  80
  81 A few additional variables, specific to the LuaRocks infrastructure, are
  82 also defined. They can be overridden in specific cases.
  83
  84 * +LUAFOO_ROCKSPEC+, which defaults to +luafoo-$(LUAFOO_VERSION).rockspec+
  85
  86 * +LUAFOO_SUBDIR+, which defaults to
  87   +luafoo-$(LUAFOO_VERSION_WITHOUT_ROCKSPEC_REVISION)+
  88
  89 * +LUAFOO_BUILD_OPTS+ contains additional build options for the
  90   +luarocks build+ call.