From patchwork Tue Dec 9 14:34:09 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Johan Oudinet X-Patchwork-Id: 419087 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from hemlock.osuosl.org (hemlock.osuosl.org [140.211.166.133]) by ozlabs.org (Postfix) with ESMTP id A0B641400D5 for ; Wed, 10 Dec 2014 01:35:30 +1100 (AEDT) Received: from localhost (localhost [127.0.0.1]) by hemlock.osuosl.org (Postfix) with ESMTP id 0940195E91; Tue, 9 Dec 2014 14:35:23 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from hemlock.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id KpmJDf7fd5SF; Tue, 9 Dec 2014 14:35:22 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by hemlock.osuosl.org (Postfix) with ESMTP id BC6D995F1C; Tue, 9 Dec 2014 14:35:21 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from whitealder.osuosl.org (whitealder.osuosl.org [140.211.166.138]) by ash.osuosl.org (Postfix) with ESMTP id 5ED5C1C2826 for ; Tue, 9 Dec 2014 14:35:16 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id 5A88491A21 for ; Tue, 9 Dec 2014 14:35:16 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from whitealder.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id qmXDD90kr7MK for ; Tue, 9 Dec 2014 14:35:13 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wi0-f169.google.com (mail-wi0-f169.google.com [209.85.212.169]) by whitealder.osuosl.org (Postfix) with ESMTPS id 70E3B909A4 for ; Tue, 9 Dec 2014 14:35:13 +0000 (UTC) Received: by mail-wi0-f169.google.com with SMTP id r20so10323845wiv.4 for ; Tue, 09 Dec 2014 06:35:12 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=Qo2QgXnytF26p03TcKvTV3I3k0RzizGftNVr9W0hqRc=; b=puDdNnzcwhPGgwrgPPPQjlPjIiZU6An7jqRsUqR4i4iVHK7WYvyia8jzw6Hb9bPZxc phmAeL+igQHGU1my+iXIkRnJAQaeVnZPBNtp1OqL1SWzcACatZ4IheerGgWvIv7fwMYY Chi9QDszvs4VOAzsm93BrWl9RfEctkMEd4UDhovzEgmMfCs11oJSUeLuGmOYorPfoz+t Ki1vctw9iZvpiWkhNaWXxlxedR4ns/31XKhN9VlVu//Qo0Q/F5CkYi2i77kyQkikAjIo njeXM82QH5t7ZhbJUGm4VoQ35VMbjaHXWpjrLaZfXTpekNdkhdpY+6PKfDj21PaMFW7V NaPA== X-Received: by 10.180.8.70 with SMTP id p6mr33537283wia.72.1418135711960; Tue, 09 Dec 2014 06:35:11 -0800 (PST) Received: from localhost.localdomain ([193.51.194.209]) by mx.google.com with ESMTPSA id d16sm2480265wib.4.2014.12.09.06.35.10 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 09 Dec 2014 06:35:11 -0800 (PST) From: Johan Oudinet To: buildroot@buildroot.org Date: Tue, 9 Dec 2014 15:34:09 +0100 Message-Id: <1418135662-773-5-git-send-email-johan.oudinet@gmail.com> X-Mailer: git-send-email 2.1.0 In-Reply-To: <1418135662-773-1-git-send-email-johan.oudinet@gmail.com> References: <1418135662-773-1-git-send-email-johan.oudinet@gmail.com> Cc: "Yann E. MORIN" Subject: [Buildroot] [PATCH v4 04/17] docs/manual: add documentation for the pkg-rebar infrastructure X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: buildroot-bounces@busybox.net Sender: "buildroot" From: "Yann E. MORIN" Signed-off-by: Johan Oudinet [yann.morin.1998@free.fr: split the doc into its own patch] Signed-off-by: "Yann E. MORIN" Signed-off-by: Johan Oudinet --- docs/manual/adding-packages-rebar.txt | 157 ++++++++++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 159 insertions(+) create mode 100644 docs/manual/adding-packages-rebar.txt diff --git a/docs/manual/adding-packages-rebar.txt b/docs/manual/adding-packages-rebar.txt new file mode 100644 index 0000000..c132a4a --- /dev/null +++ b/docs/manual/adding-packages-rebar.txt @@ -0,0 +1,157 @@ +// -*- 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.gz +09: ERLANG_FOOBAR_SITE = http://www.foosoftware.org/download +10: ERLANG_FOOBAR_INSTALL_STAGING = YES +11: ERLANG_FOOBAR_CONF_OPTS = --enable-bar +12: ERLANG_FOOBAR_DEPENDENCIES = host-libaaa libbbb +13: +14: $(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 tell Buildroot to install the package to the staging +directory. The staging directory, located in +output/staging/+ +is the directory where all the packages are installed, including their +development files, etc. By default, packages are not installed to the +staging directory, since usually, only libraries need to be installed in +the staging directory: their development files are needed to compile +other libraries or applications depending on them. + +On line 11, we tell Buildroot to pass a custom configure option, that +will be passed to the +./configure+ script before configuring +and building the package. + +On line 12, we declare our dependencies, so that they are built +before the build process of our package starts. + +Finally, on line line 14, 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 target and 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+. + +Note that the rebar infrastructure does not expect a configure script, +but does call such a script when it exists. When a package uses both +the Autotools and rebar, it should use the rebar infrastructure. In +this case however, the build commands do not call make, but only ++rebar compile+; this avoids triggering the download of dependencies +(as most Makefile's do when combined with rebar). Also, note that the +install commands never call +make install+. Instead, they install +Erlang's application directories (ebin, priv, etc.) into a proper +location. If this is not what you want, add custom hooks or override +rebar commands (see below). + +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_CONF_ENV+, to specify additional environment + variables to pass to the configure script. By default, empty. + +* +ERLANG_FOOBAR_CONF_OPTS+, to specify additional configure options + to pass to the configure script. By default, empty. + +* +ERLANG_FOOBAR_AUTORECONF+, tells whether the package should be + autoreconfigured or not (i.e. if the configure script and + Makefile.in files should be re-generated by re-running autoconf, + automake, libtool, etc.). Valid values are +YES+ and +NO+. By + default, the value is +NO+ + +* +ERLANG_FOOBAR_AUTORECONF_ENV+, to specify additional environment + variables to pass to the 'autoreconf' program if + +ERLANG_FOOBAR_AUTORECONF=YES+. These are passed in the environment + of the 'autoreconf' command. By default, empty. + +* +ERLANG_FOOBAR_AUTORECONF_OPTS+ to specify additional options passed + to the 'autoreconf' program if +ERLANG_FOOBAR_AUTORECONF=YES+. By + default, empty. + +* +ERLANG_FOOBAR_REBAR_ENV+, to specify additional environment + variables to pass to rebar. By default, the value sets a minimal + PATH that only includes +HOST_DIR/bin+, +HOST_DIR/usr/bin+, and + +/bin+. + +* +ERLANG_FOOBAR_REBAR_FLAGS+, to specify rebar flags. By default, the + value is +deps_dir=ERLANG_FOOBAR_REBAR_DEPS_DIR+. + +* +ERLANG_FOOBAR_REBAR_DEPS_DIR+, to specify where to look for the + package's dependencies. By default, the value is + +output/build/erlang-rebar-deps/target+, or + +output/build/erlang-rebar-deps/host+ for host packages. Note that + if the package installs to staging as well, the rebar infrastructure + then creates a symbolic link in this directory to + +ERLANG_FOOBAR_ERLANG_LIBDIR+ so other packages may use it as + a dependency. + +* +ERLANG_FOOBAR_ERLANG_LIBDIR+, to specify where to install the + Erlang application. By default, the value is + +/usr/lib/erlang/lib/ERLANG_FOOBAR_ERLANG_APP-ERLANG_FOOBAR_VERSION+. + +* +ERLANG_FOOBAR_ERLANG_APP+, to specify the name of the Erlang + application to be installed. This modifies where the application is + installed (e.g., +/usr/lib/erlang/lib/ERLANG_FOOBAR_ERLANG_APP-ERLANG_FOOBAR_VERSION+) + and the name of the symbolic link in +ERLANG_FOOBAR_REBAR_DEPS_DIR+, + if any (e.g., +output/build/erlang-rebar-deps/target/ERLANG_FOOBAR_ERLANG_APP+. + By default, the value is the lowercase package name stripped from + any +erlang-+ prefix, and with dashes converted to underscores. + +* +ERLANG_FOOBAR_ENV+, to specify additional environment variables to + pass both to the configure script and rebar. By default, sets CC, + CFLAGS, LDFLAGS, ERL_COMPILER_OPTIONS, and ERL_EI_LIBDIR. + +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_CONFIGURE_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 feb0d13..b8674f8 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[]