adding-packages-rebar.txt 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. === Infrastructure for rebar-based packages
  4. [[rebar-package-tutorial]]
  5. ==== +rebar-package+ tutorial
  6. First, let's see how to write a +.mk+ file for a rebar-based package,
  7. with an example :
  8. ------------------------------
  9. 01: ################################################################################
  10. 02: #
  11. 03: # erlang-foobar
  12. 04: #
  13. 05: ################################################################################
  14. 06:
  15. 07: ERLANG_FOOBAR_VERSION = 1.0
  16. 08: ERLANG_FOOBAR_SOURCE = erlang-foobar-$(ERLANG_FOOBAR_VERSION).tar.xz
  17. 09: ERLANG_FOOBAR_SITE = http://www.foosoftware.org/download
  18. 10: ERLANG_FOOBAR_DEPENDENCIES = host-libaaa libbbb
  19. 11:
  20. 12: $(eval $(rebar-package))
  21. --------------------------------
  22. On line 7, we declare the version of the package.
  23. On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  24. recommended) and the location of the tarball on the Web. Buildroot
  25. will automatically download the tarball from this location.
  26. On line 10, we declare our dependencies, so that they are built
  27. before the build process of our package starts.
  28. Finally, on line 12, we invoke the +rebar-package+ macro that
  29. generates all the Makefile rules that actually allows the package to
  30. be built.
  31. [[rebar-package-reference]]
  32. ==== +rebar-package+ reference
  33. The main macro of the +rebar+ package infrastructure is
  34. +rebar-package+. It is similar to the +generic-package+ macro. The
  35. ability to have host packages is also available, with the
  36. +host-rebar-package+ macro.
  37. Just like the generic infrastructure, the +rebar+ infrastructure works
  38. by defining a number of variables before calling the +rebar-package+
  39. macro.
  40. First, all the package metadata information variables that exist in
  41. the generic infrastructure also exist in the +rebar+ infrastructure:
  42. +ERLANG_FOOBAR_VERSION+, +ERLANG_FOOBAR_SOURCE+,
  43. +ERLANG_FOOBAR_PATCH+, +ERLANG_FOOBAR_SITE+,
  44. +ERLANG_FOOBAR_SUBDIR+, +ERLANG_FOOBAR_DEPENDENCIES+,
  45. +ERLANG_FOOBAR_INSTALL_STAGING+, +ERLANG_FOOBAR_INSTALL_TARGET+,
  46. +ERLANG_FOOBAR_LICENSE+ and +ERLANG_FOOBAR_LICENSE_FILES+.
  47. A few additional variables, specific to the +rebar+ infrastructure,
  48. can also be defined. Many of them are only useful in very specific
  49. cases, typical packages will therefore only use a few of them.
  50. * +ERLANG_FOOBAR_USE_AUTOCONF+, to specify that the package uses
  51. _autoconf_ at the configuration step. When a package sets this
  52. variable to +YES+, the +autotools+ infrastructure is used.
  53. +
  54. .Note
  55. You can also use some of the variables from the +autotools+
  56. infrastructure: +ERLANG_FOOBAR_CONF_ENV+, +ERLANG_FOOBAR_CONF_OPTS+,
  57. +ERLANG_FOOBAR_AUTORECONF+, +ERLANG_FOOBAR_AUTORECONF_ENV+ and
  58. +ERLANG_FOOBAR_AUTORECONF_OPTS+.
  59. * +ERLANG_FOOBAR_USE_BUNDLED_REBAR+, to specify that the package has
  60. a bundled version of _rebar_ *and* that it shall be used. Valid
  61. values are +YES+ or +NO+ (the default).
  62. +
  63. .Note
  64. If the package bundles a _rebar_ utility, but can use the generic
  65. one that Buildroot provides, just say +NO+ (i.e., do not specify
  66. this variable). Only set if it is mandatory to use the _rebar_
  67. utility bundled in this package.
  68. * +ERLANG_FOOBAR_REBAR_ENV+, to specify additional environment
  69. variables to pass to the _rebar_ utility.
  70. * +ERLANG_FOOBAR_KEEP_DEPENDENCIES+, to keep the dependencies
  71. described in the rebar.config file. Valid values are +YES+ or +NO+
  72. (the default). Unless this variable is set to +YES+, the _rebar_
  73. infrastructure removes such dependencies in a post-patch hook to
  74. ensure rebar does not download nor compile them.
  75. With the rebar infrastructure, all the steps required to build
  76. and install the packages are already defined, and they generally work
  77. well for most rebar-based packages. However, when required, it is
  78. still possible to customize what is done in any particular step:
  79. * By adding a post-operation hook (after extract, patch, configure,
  80. build or install). See xref:hooks[] for details.
  81. * By overriding one of the steps. For example, even if the rebar
  82. infrastructure is used, if the package +.mk+ file defines its
  83. own +ERLANG_FOOBAR_BUILD_CMDS+ variable, it will be used instead
  84. of the default rebar one. However, using this method should be
  85. restricted to very specific cases. Do not use it in the general
  86. case.