adding-packages-luarocks.txt 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. === Infrastructure for LuaRocks-based packages
  4. [[luarocks-package-tutorial]]
  5. ==== +luarocks-package+ tutorial
  6. First, let's see how to write a +.mk+ file for a LuaRocks-based package,
  7. with an example :
  8. ------------------------
  9. 01: ################################################################################
  10. 02: #
  11. 03: # lua-foo
  12. 04: #
  13. 05: ################################################################################
  14. 06:
  15. 07: LUA_FOO_VERSION = 1.0.2-1
  16. 08: LUA_FOO_NAME_UPSTREAM = foo
  17. 09: LUA_FOO_DEPENDENCIES = bar
  18. 10:
  19. 11: LUA_FOO_BUILD_OPTS += BAR_INCDIR=$(STAGING_DIR)/usr/include
  20. 12: LUA_FOO_BUILD_OPTS += BAR_LIBDIR=$(STAGING_DIR)/usr/lib
  21. 13: LUA_FOO_LICENSE = luaFoo license
  22. 14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING
  23. 15:
  24. 16: $(eval $(luarocks-package))
  25. ------------------------
  26. On line 7, we declare the version of the package (the same as in the rockspec,
  27. which is the concatenation of the upstream version and the rockspec revision,
  28. separated by a hyphen '-').
  29. On line 8, we declare that the package is called "foo" on LuaRocks. In
  30. Buildroot, we give Lua-related packages a name that starts with "lua", so the
  31. Buildroot name is different from the upstream name. +LUA_FOO_NAME_UPSTREAM+
  32. makes the link between the two names.
  33. On line 9, we declare our dependencies against native libraries, so that they
  34. are built before the build process of our package starts.
  35. On lines 11-12, we tell Buildroot to pass custom options to LuaRocks when it is
  36. building the package.
  37. On lines 13-14, we specify the licensing terms for the package.
  38. Finally, on line 16, we invoke the +luarocks-package+
  39. macro that generates all the Makefile rules that actually allows the
  40. package to be built.
  41. Most of these details can be retrieved from the +rock+ and +rockspec+.
  42. So, this file and the Config.in file can be generated by running the
  43. command +luarocks buildroot foo lua-foo+ in the Buildroot
  44. directory. This command runs a specific Buildroot addon of +luarocks+
  45. that will automatically generate a Buildroot package. The result must
  46. still be manually inspected and possibly modified.
  47. * The +package/Config.in+ file has to be updated manually to include the
  48. generated Config.in files.
  49. [[luarocks-package-reference]]
  50. ==== +luarocks-package+ reference
  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. The main macro of the LuaRocks package infrastructure is +luarocks-package+:
  58. like +generic-package+ it works by defining a number of variables providing
  59. metadata information about the package, and then calling +luarocks-package+.
  60. Just like the generic infrastructure, the LuaRocks infrastructure works
  61. by defining a number of variables before calling the +luarocks-package+
  62. macro.
  63. First, all the package metadata information variables that exist in
  64. the generic infrastructure also exist in the LuaRocks infrastructure:
  65. +LUA_FOO_VERSION+, +LUA_FOO_SOURCE+, +LUA_FOO_SITE+,
  66. +LUA_FOO_DEPENDENCIES+, +LUA_FOO_LICENSE+, +LUA_FOO_LICENSE_FILES+.
  67. Two of them are populated by the LuaRocks infrastructure (for the
  68. +download+ step). If your package is not hosted on the LuaRocks mirror
  69. +$(BR2_LUAROCKS_MIRROR)+, you can override them:
  70. * +LUA_FOO_SITE+, which defaults to +$(BR2_LUAROCKS_MIRROR)+
  71. * +LUA_FOO_SOURCE+, which defaults to
  72. +$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).src.rock+
  73. A few additional variables, specific to the LuaRocks infrastructure, are
  74. also defined. They can be overridden in specific cases.
  75. * +LUA_FOO_NAME_UPSTREAM+, which defaults to +lua-foo+, i.e. the Buildroot
  76. package name
  77. * +LUA_FOO_ROCKSPEC+, which defaults to
  78. +$(lowercase LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).rockspec+
  79. * +LUA_FOO_SUBDIR+, which defaults to
  80. +$(LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION_WITHOUT_ROCKSPEC_REVISION)+
  81. * +LUA_FOO_BUILD_OPTS+ contains additional build options for the
  82. +luarocks build+ call.