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