docs/manual: add documentation for the pkg-rebar infrastructure

// -*- mode:doc; -*-

// vim: set syntax=asciidoc:

=== Infrastructure for rebar-based packages

[[rebar-package-tutorial]]

==== +rebar-package+ tutorial

First, let's see how to write a +.mk+ file for a rebar-based package,

with an example :

------------------------------

01: ################################################################################

02: #

03: # erlang-foobar

04: #

05: ################################################################################

06:

07: ERLANG_FOOBAR_VERSION = 1.0

08: ERLANG_FOOBAR_SOURCE = erlang-foobar-$(ERLANG_FOOBAR_VERSION).tar.xz

09: ERLANG_FOOBAR_SITE = http://www.foosoftware.org/download

10: ERLANG_FOOBAR_DEPENDENCIES = host-libaaa libbbb

11:

12: $(eval $(rebar-package))

--------------------------------

On line 7, we declare the version of the package.

On line 8 and 9, we declare the name of the tarball (xz-ed tarball

recommended) and the location of the tarball on the Web. Buildroot

will automatically download the tarball from this location.

On line 10, we declare our dependencies, so that they are built

before the build process of our package starts.

Finally, on line 12, we invoke the +rebar-package+ macro that

generates all the Makefile rules that actually allows the package to

be built.

[[rebar-package-reference]]

==== +rebar-package+ reference

The main macro of the +rebar+ package infrastructure is

+rebar-package+. It is similar to the +generic-package+ macro. The

ability to have host packages is also available, with the

+host-rebar-package+ macro.

Just like the generic infrastructure, the +rebar+ infrastructure works

by defining a number of variables before calling the +rebar-package+

macro.

First, all the package metadata information variables that exist in

the generic infrastructure also exist in the +rebar+ infrastructure:

+ERLANG_FOOBAR_VERSION+, +ERLANG_FOOBAR_SOURCE+,

+ERLANG_FOOBAR_PATCH+, +ERLANG_FOOBAR_SITE+,

+ERLANG_FOOBAR_SUBDIR+, +ERLANG_FOOBAR_DEPENDENCIES+,

+ERLANG_FOOBAR_INSTALL_STAGING+, +ERLANG_FOOBAR_INSTALL_TARGET+,

+ERLANG_FOOBAR_LICENSE+ and +ERLANG_FOOBAR_LICENSE_FILES+.

A few additional variables, specific to the +rebar+ infrastructure,

can also be defined. Many of them are only useful in very specific

cases, typical packages will therefore only use a few of them.

* +ERLANG_FOOBAR_USE_AUTOCONF+, to specify that the package uses

  _autoconf_ at the configuration step.  When a package sets this

  variable to +YES+, the +autotools+ infrastructure is used.

+

.Note

You can also use some of the variables from the +autotools+

  infrastructure: +ERLANG_FOOBAR_CONF_ENV+, +ERLANG_FOOBAR_CONF_OPTS+,

  +ERLANG_FOOBAR_AUTORECONF+, +ERLANG_FOOBAR_AUTORECONF_ENV+ and

  +ERLANG_FOOBAR_AUTORECONF_OPTS+.

* +ERLANG_FOOBAR_USE_BUNDLED_REBAR+, to specify that the package has

  a bundled version of _rebar_ *and* that it shall be used. Valid

  values are +YES+ or +NO+ (the default).

+

.Note

If the package bundles a _rebar_ utility, but can use the generic

  one that Buildroot provides, just say +NO+ (i.e., do not specify

  this variable). Only set if it is mandatory to use the _rebar_

  utility bundled in this package.

* +ERLANG_FOOBAR_REBAR_ENV+, to specify additional environment

  variables to pass to the _rebar_ utility.

With the rebar infrastructure, all the steps required to build

and install the packages are already defined, and they generally work

well for most rebar-based packages. However, when required, it is

still possible to customize what is done in any particular step:

* By adding a post-operation hook (after extract, patch, configure,

  build or install). See xref:hooks[] for details.

* By overriding one of the steps. For example, even if the rebar

  infrastructure is used, if the package +.mk+ file defines its

  own +ERLANG_FOOBAR_BUILD_CMDS+ variable, it will be used instead

  of the default rebar one. However, using this method should be

  restricted to very specific cases. Do not use it in the general

  case.

include::adding-packages-kconfig.txt[]

include::adding-packages-rebar.txt[]

include::adding-packages-asciidoc.txt[]

include::adding-packages-hooks.txt[]