aboutsummaryrefslogtreecommitdiff
path: root/docs/manual
diff options
context:
space:
mode:
authorGravatar Yann E. MORIN <yann.morin.1998@free.fr>2015-01-12 10:32:07 +0100
committerGravatar Thomas Petazzoni <thomas.petazzoni@free-electrons.com>2015-02-03 10:23:03 +0100
commit0fe05ff3e16113f2c558ba1f8a7bc2836842a08e (patch)
tree05bd472c7773ca32ee87683724bcf8c30d1fbb02 /docs/manual
parent781b49465896e2f6b338de331b9f7be5045f5eeb (diff)
downloadbuildroot-0fe05ff3e16113f2c558ba1f8a7bc2836842a08e.tar.gz
buildroot-0fe05ff3e16113f2c558ba1f8a7bc2836842a08e.tar.bz2
docs/manual: add documentation for the pkg-rebar infrastructure
Signed-off-by: Johan Oudinet <johan.oudinet@gmail.com> [yann.morin.1998@free.fr: split the doc into its own patch] Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Diffstat (limited to 'docs/manual')
-rw-r--r--docs/manual/adding-packages-rebar.txt102
-rw-r--r--docs/manual/adding-packages.txt2
2 files changed, 104 insertions, 0 deletions
diff --git a/docs/manual/adding-packages-rebar.txt b/docs/manual/adding-packages-rebar.txt
new file mode 100644
index 0000000000..be9ede0113
--- /dev/null
+++ b/docs/manual/adding-packages-rebar.txt
@@ -0,0 +1,102 @@
+// -*- 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.
diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
index feb0d13185..b8674f867c 100644
--- a/docs/manual/adding-packages.txt
+++ b/docs/manual/adding-packages.txt
@@ -27,6 +27,8 @@ include::adding-packages-virtual.txt[]
include::adding-packages-kconfig.txt[]
+include::adding-packages-rebar.txt[]
+
include::adding-packages-asciidoc.txt[]
include::adding-packages-hooks.txt[]