From patchwork Mon Jan 12 09:32:07 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Johan Oudinet X-Patchwork-Id: 427613 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from silver.osuosl.org (silver.osuosl.org [140.211.166.136]) by ozlabs.org (Postfix) with ESMTP id EE38C140192 for ; Mon, 12 Jan 2015 20:33:29 +1100 (AEDT) Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id 36F26309D5; Mon, 12 Jan 2015 09:33:29 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from silver.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 9lBcUZABI-jK; Mon, 12 Jan 2015 09:33:26 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by silver.osuosl.org (Postfix) with ESMTP id 8E507313E5; Mon, 12 Jan 2015 09:33:26 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from hemlock.osuosl.org (hemlock.osuosl.org [140.211.166.133]) by ash.osuosl.org (Postfix) with ESMTP id AE9091C22EC for ; Mon, 12 Jan 2015 09:33:25 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by hemlock.osuosl.org (Postfix) with ESMTP id A940D8AE40 for ; Mon, 12 Jan 2015 09:33:25 +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 g4i-MDLjRRB1 for ; Mon, 12 Jan 2015 09:33:25 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wg0-f42.google.com (mail-wg0-f42.google.com [74.125.82.42]) by hemlock.osuosl.org (Postfix) with ESMTPS id E379D8A461 for ; Mon, 12 Jan 2015 09:33:24 +0000 (UTC) Received: by mail-wg0-f42.google.com with SMTP id k14so18144712wgh.1 for ; Mon, 12 Jan 2015 01:33:23 -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=AAJe5n6Rbinkj1zYmehojSbK/zX8kSu6E/YrRjZNKyc=; b=yfuLS+ZML2Nd90p3GHIf+IBDVH27vZOB7hXLmAML8MQn1+5SHO1Fg/h1kC26W8v0TT BMZQeGWnTAwUFW1LP77yMHfAWAvECSxxJUPyfuakj6cY0Cu1xODgRFQDRvNgADriI1db mBdP0sfHP/hO9lXmJgeAJLKcWNFR+O5E76Lld8V9X3Qd3ZM/RtQ1ls0Wt/3sZt6XxYZ2 hHxFFCl9t3D1zVZZZxXJ2WoCymR2l+WsGyE8h+MCAYuV2izTQ8+CDj4b28DdbslEvRoX 95cYCb0nEk6ljUSd6TuR2LUOpvEKg74UHUPrFVfuO5hQdyomDsN4A9LviUuniKHlSOA/ Gsig== X-Received: by 10.181.27.199 with SMTP id ji7mr28711461wid.76.1421055203463; Mon, 12 Jan 2015 01:33:23 -0800 (PST) Received: from localhost.localdomain ([193.51.194.209]) by mx.google.com with ESMTPSA id fm10sm9431343wib.7.2015.01.12.01.33.22 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 12 Jan 2015 01:33:22 -0800 (PST) From: Johan Oudinet To: buildroot@buildroot.org Date: Mon, 12 Jan 2015 10:32:07 +0100 Message-Id: <1421055140-5092-4-git-send-email-johan.oudinet@gmail.com> X-Mailer: git-send-email 2.1.0 In-Reply-To: <1421055140-5092-1-git-send-email-johan.oudinet@gmail.com> References: <1421055140-5092-1-git-send-email-johan.oudinet@gmail.com> Cc: "Yann E. MORIN" Subject: [Buildroot] [PATCH v6 03/16] 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" --- Changes v4 -> v5: (Thomas) - drop unused variables - drop implementation details - properly document the autotools case - add missing licensing variables - some rewording about everywhere (YEM) Signed-off-by: Johan Oudinet --- docs/manual/adding-packages-rebar.txt | 102 ++++++++++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 104 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..be9ede0 --- /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 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[]