1*4882a593Smuzhiyun// -*- mode:doc; -*- 2*4882a593Smuzhiyun// vim: set syntax=asciidoc: 3*4882a593Smuzhiyun 4*4882a593Smuzhiyun=== Infrastructure for LuaRocks-based packages 5*4882a593Smuzhiyun 6*4882a593Smuzhiyun[[luarocks-package-tutorial]] 7*4882a593Smuzhiyun 8*4882a593Smuzhiyun==== +luarocks-package+ tutorial 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunFirst, let's see how to write a +.mk+ file for a LuaRocks-based package, 11*4882a593Smuzhiyunwith an example : 12*4882a593Smuzhiyun 13*4882a593Smuzhiyun------------------------ 14*4882a593Smuzhiyun01: ################################################################################ 15*4882a593Smuzhiyun02: # 16*4882a593Smuzhiyun03: # lua-foo 17*4882a593Smuzhiyun04: # 18*4882a593Smuzhiyun05: ################################################################################ 19*4882a593Smuzhiyun06: 20*4882a593Smuzhiyun07: LUA_FOO_VERSION = 1.0.2-1 21*4882a593Smuzhiyun08: LUA_FOO_NAME_UPSTREAM = foo 22*4882a593Smuzhiyun09: LUA_FOO_DEPENDENCIES = bar 23*4882a593Smuzhiyun10: 24*4882a593Smuzhiyun11: LUA_FOO_BUILD_OPTS += BAR_INCDIR=$(STAGING_DIR)/usr/include 25*4882a593Smuzhiyun12: LUA_FOO_BUILD_OPTS += BAR_LIBDIR=$(STAGING_DIR)/usr/lib 26*4882a593Smuzhiyun13: LUA_FOO_LICENSE = luaFoo license 27*4882a593Smuzhiyun14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING 28*4882a593Smuzhiyun15: 29*4882a593Smuzhiyun16: $(eval $(luarocks-package)) 30*4882a593Smuzhiyun------------------------ 31*4882a593Smuzhiyun 32*4882a593SmuzhiyunOn line 7, we declare the version of the package (the same as in the rockspec, 33*4882a593Smuzhiyunwhich is the concatenation of the upstream version and the rockspec revision, 34*4882a593Smuzhiyunseparated by a hyphen '-'). 35*4882a593Smuzhiyun 36*4882a593SmuzhiyunOn line 8, we declare that the package is called "foo" on LuaRocks. In 37*4882a593SmuzhiyunBuildroot, we give Lua-related packages a name that starts with "lua", so the 38*4882a593SmuzhiyunBuildroot name is different from the upstream name. +LUA_FOO_NAME_UPSTREAM+ 39*4882a593Smuzhiyunmakes the link between the two names. 40*4882a593Smuzhiyun 41*4882a593SmuzhiyunOn line 9, we declare our dependencies against native libraries, so that they 42*4882a593Smuzhiyunare built before the build process of our package starts. 43*4882a593Smuzhiyun 44*4882a593SmuzhiyunOn lines 11-12, we tell Buildroot to pass custom options to LuaRocks when it is 45*4882a593Smuzhiyunbuilding the package. 46*4882a593Smuzhiyun 47*4882a593SmuzhiyunOn lines 13-14, we specify the licensing terms for the package. 48*4882a593Smuzhiyun 49*4882a593SmuzhiyunFinally, on line 16, we invoke the +luarocks-package+ 50*4882a593Smuzhiyunmacro that generates all the Makefile rules that actually allows the 51*4882a593Smuzhiyunpackage to be built. 52*4882a593Smuzhiyun 53*4882a593SmuzhiyunMost of these details can be retrieved from the +rock+ and +rockspec+. 54*4882a593SmuzhiyunSo, this file and the Config.in file can be generated by running the 55*4882a593Smuzhiyuncommand +luarocks buildroot foo lua-foo+ in the Buildroot 56*4882a593Smuzhiyundirectory. This command runs a specific Buildroot addon of +luarocks+ 57*4882a593Smuzhiyunthat will automatically generate a Buildroot package. The result must 58*4882a593Smuzhiyunstill be manually inspected and possibly modified. 59*4882a593Smuzhiyun 60*4882a593Smuzhiyun* The +package/Config.in+ file has to be updated manually to include the 61*4882a593Smuzhiyun generated Config.in files. 62*4882a593Smuzhiyun 63*4882a593Smuzhiyun[[luarocks-package-reference]] 64*4882a593Smuzhiyun 65*4882a593Smuzhiyun==== +luarocks-package+ reference 66*4882a593Smuzhiyun 67*4882a593SmuzhiyunLuaRocks is a deployment and management system for Lua modules, and supports 68*4882a593Smuzhiyunvarious +build.type+: +builtin+, +make+ and +cmake+. In the context of 69*4882a593SmuzhiyunBuildroot, the +luarocks-package+ infrastructure only supports the +builtin+ 70*4882a593Smuzhiyunmode. LuaRocks packages that use the +make+ or +cmake+ build mechanisms 71*4882a593Smuzhiyunshould instead be packaged using the +generic-package+ and +cmake-package+ 72*4882a593Smuzhiyuninfrastructures in Buildroot, respectively. 73*4882a593Smuzhiyun 74*4882a593SmuzhiyunThe main macro of the LuaRocks package infrastructure is +luarocks-package+: 75*4882a593Smuzhiyunlike +generic-package+ it works by defining a number of variables providing 76*4882a593Smuzhiyunmetadata information about the package, and then calling +luarocks-package+. 77*4882a593Smuzhiyun 78*4882a593SmuzhiyunJust like the generic infrastructure, the LuaRocks infrastructure works 79*4882a593Smuzhiyunby defining a number of variables before calling the +luarocks-package+ 80*4882a593Smuzhiyunmacro. 81*4882a593Smuzhiyun 82*4882a593SmuzhiyunFirst, all the package metadata information variables that exist in 83*4882a593Smuzhiyunthe generic infrastructure also exist in the LuaRocks infrastructure: 84*4882a593Smuzhiyun+LUA_FOO_VERSION+, +LUA_FOO_SOURCE+, +LUA_FOO_SITE+, 85*4882a593Smuzhiyun+LUA_FOO_DEPENDENCIES+, +LUA_FOO_LICENSE+, +LUA_FOO_LICENSE_FILES+. 86*4882a593Smuzhiyun 87*4882a593SmuzhiyunTwo of them are populated by the LuaRocks infrastructure (for the 88*4882a593Smuzhiyun+download+ step). If your package is not hosted on the LuaRocks mirror 89*4882a593Smuzhiyun+$(BR2_LUAROCKS_MIRROR)+, you can override them: 90*4882a593Smuzhiyun 91*4882a593Smuzhiyun* +LUA_FOO_SITE+, which defaults to +$(BR2_LUAROCKS_MIRROR)+ 92*4882a593Smuzhiyun 93*4882a593Smuzhiyun* +LUA_FOO_SOURCE+, which defaults to 94*4882a593Smuzhiyun +$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).src.rock+ 95*4882a593Smuzhiyun 96*4882a593SmuzhiyunA few additional variables, specific to the LuaRocks infrastructure, are 97*4882a593Smuzhiyunalso defined. They can be overridden in specific cases. 98*4882a593Smuzhiyun 99*4882a593Smuzhiyun* +LUA_FOO_NAME_UPSTREAM+, which defaults to +lua-foo+, i.e. the Buildroot 100*4882a593Smuzhiyun package name 101*4882a593Smuzhiyun 102*4882a593Smuzhiyun* +LUA_FOO_ROCKSPEC+, which defaults to 103*4882a593Smuzhiyun +$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).rockspec+ 104*4882a593Smuzhiyun 105*4882a593Smuzhiyun* +LUA_FOO_SUBDIR+, which defaults to 106*4882a593Smuzhiyun +$(LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION_WITHOUT_ROCKSPEC_REVISION)+ 107*4882a593Smuzhiyun 108*4882a593Smuzhiyun* +LUA_FOO_BUILD_OPTS+ contains additional build options for the 109*4882a593Smuzhiyun +luarocks build+ call. 110