kumquat-buildroot/docs/manual/adding-packages-rebar.adoc
Francois Perrad 32cec3be97 docs/manual: rename *.txt as *.adoc
by using this standard extension `adoc`,
these files are rendered on gitlab & github

Signed-off-by: Francois Perrad <francois.perrad@gadz.org>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2023-09-30 10:25:22 +02:00

109 lines
4.2 KiB
Plaintext

// -*- 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.
* +ERLANG_FOOBAR_KEEP_DEPENDENCIES+, to keep the dependencies
described in the rebar.config file. Valid values are +YES+ or +NO+
(the default). Unless this variable is set to +YES+, the _rebar_
infrastructure removes such dependencies in a post-patch hook to
ensure rebar does not download nor compile them.
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.