From patchwork Wed Oct 25 09:26:46 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Angelo Compagnucci X-Patchwork-Id: 830153 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=busybox.net (client-ip=140.211.166.136; helo=silver.osuosl.org; envelope-from=buildroot-bounces@busybox.net; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="XlY/UW9g"; dkim-atps=neutral Received: from silver.osuosl.org (smtp3.osuosl.org [140.211.166.136]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3yMPt45yDPz9sRV for ; Wed, 25 Oct 2017 20:27:08 +1100 (AEDT) Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id 722DF3083B; Wed, 25 Oct 2017 09:27:06 +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 e8Q1RMz7pOC4; Wed, 25 Oct 2017 09:27:04 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by silver.osuosl.org (Postfix) with ESMTP id 7D3E030832; Wed, 25 Oct 2017 09:27:04 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from hemlock.osuosl.org (smtp2.osuosl.org [140.211.166.133]) by ash.osuosl.org (Postfix) with ESMTP id EC5571C0621 for ; Wed, 25 Oct 2017 09:26:58 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by hemlock.osuosl.org (Postfix) with ESMTP id E5336899DF for ; Wed, 25 Oct 2017 09:26:58 +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 pEXIytAQvkaH for ; Wed, 25 Oct 2017 09:26:58 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wr0-f196.google.com (mail-wr0-f196.google.com [209.85.128.196]) by hemlock.osuosl.org (Postfix) with ESMTPS id 2664388A10 for ; Wed, 25 Oct 2017 09:26:58 +0000 (UTC) Received: by mail-wr0-f196.google.com with SMTP id k62so23278355wrc.9 for ; Wed, 25 Oct 2017 02:26:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=XFuMj3d7/yxpLL8+h5a69IMeF5frt0uQiNW+NyB/6nU=; b=XlY/UW9gs2UOTd+38hmQyd8YdR7dm66y30E2+j3vxNiEOxQkd8YxKDgMF04JEMIXe2 hC5SMuuT/PErn4ManTKKteVCcs0Kktd/0IgQd9dNvQByTWZG853OlFoSj6U4KAgBVcYb 3btgAFQTTwk0o+dxLEIhkq8DN9JXqPbuoj7NQR1CxJZ2tlHdjkHP1F7yNgiM6NS8etz6 z5TXcZuP843MFhbVM7eu59yOjl98b4i/Jt+cGC93cNz0QXHjC8Ie9E3Tw24NFFwDUZob 8qq9Yc3PSA8uXcmyApFx9PXYkW1LCU1RQyabfUfIrUGFO7gIOhdWzdiolVr3jndtzGcE Y3Ww== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=XFuMj3d7/yxpLL8+h5a69IMeF5frt0uQiNW+NyB/6nU=; b=ttIfRrK748SgIxMIU9shfwIaI7AjqyfYZTHyN/gXOndGCJ+TTRGpTC9S8xP4BC+GKl /+41eRc/dV4VedRP9TwTiePC4f3ZWQZq1146WJqVFzUyHKvV+jS50aYmD3T7XgWoQ/9N mNDpc6VMmZQc9xs953B15GsZD085yppBJ3sa4RVlidt5/eJ6b1eFmq4r8+WizJwFSLgx 60bxTS5yJrG9ZAHP+o60vrd5stk2JYJAYgshcZ5+W9kMowLtdm81BGbsf5RaoVnSps3Q 3DOLLOwWd4t20WKstSB7gPd61wf4ELp6QDTilkVr5vwrnp+3D8T8G2OmJ1qmLEgJ0Vzy JVvg== X-Gm-Message-State: AMCzsaVlrJ895a6FBc9uoRAb0uqgghw7Y+biAVtJ91b/9tMo2VidREq3 wjNPfu4tm03uB/0R41chHmmq7/Qq X-Google-Smtp-Source: ABhQp+Q5Us6askMNV/4H4PMLPhbUHBmB74o5K7VxSOZPJn2/1C65kpePANmZiQIk0EeK5xtZW3loYg== X-Received: by 10.223.154.74 with SMTP id z68mr1500123wrb.36.1508923615909; Wed, 25 Oct 2017 02:26:55 -0700 (PDT) Received: from localhost.localdomain ([89.202.204.147]) by smtp.gmail.com with ESMTPSA id q7sm2009311wrg.97.2017.10.25.02.26.54 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 25 Oct 2017 02:26:55 -0700 (PDT) From: Angelo Compagnucci To: buildroot@buildroot.org Date: Wed, 25 Oct 2017 11:26:46 +0200 Message-Id: <1508923609-2022-2-git-send-email-angelo.compagnucci@gmail.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1508923609-2022-1-git-send-email-angelo.compagnucci@gmail.com> References: <1508923609-2022-1-git-send-email-angelo.compagnucci@gmail.com> Cc: christian@paral.in Subject: [Buildroot] [RFC v5 2/5] docs/manual: adding documentation for the golang 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" This patch adds the documentation for the golang infrastructure. Signed-off-by: Angelo Compagnucci --- docs/manual/adding-packages-golang.txt | 114 +++++++++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 116 insertions(+) create mode 100644 docs/manual/adding-packages-golang.txt diff --git a/docs/manual/adding-packages-golang.txt b/docs/manual/adding-packages-golang.txt new file mode 100644 index 0000000..3761cac --- /dev/null +++ b/docs/manual/adding-packages-golang.txt @@ -0,0 +1,114 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +=== Infrastructure for Go packages + +This infrastructure applies to Go packages that use the standard +build system and use bundled dependencies. + +[[golang-package-tutorial]] + +==== +golang-package+ tutorial + +First, let's see how to write a +.mk+ file for a go package, +with an example : + +------------------------ +01: ################################################################################ +02: # +03: # go-foo +04: # +05: ################################################################################ +06: +07: GO_FOO_VERSION = 1.0 +08: GO_FOO_SOURCE = go-foo-$(GO_FOO_VERSION).tar.xz +09: GO_FOO_SITE = http://www.foosoftware.org/download +10: GO_FOO_LICENSE = BSD-3-Clause +11: GO_FOO_LICENSE_FILES = LICENSE +12: +13: $(eval $(golang-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 and 11, we give licensing details about the package (its +license on line 10, and the file containing the license text on line +11). + +Finally, on line 13, we invoke the +golang-package+ macro that +generates all the Makefile rules that actually allow the package to be +built. + +[[golang-package-reference]] + +==== +golang-package+ reference + +As a policy packages can freely choose their name (existing example in +Buildroot is +flannel+). + +In their +Config.in+ file, they should depend on ++BR2_PACKAGE_HOST_GO_ARCH_SUPPORTS+ and ++BR2_PACKAGE_HOST_GO_CGO_LINKING_SUPPORTS+ cause host-go will compile when Buildroot will add the +dependency automatically. + +The main macro of the Go package infrastructure is ++golang-package+. It is similar to the +generic-package+ macro. + +Just like the generic infrastructure, the Go infrastructure works +by defining a number of variables before calling the +golang-package+. + +All the package metadata information variables that exist in the +xref:generic-package-reference[generic package infrastructure] also +exist in the Go infrastructure: +GO_FOO_VERSION+, ++GO_FOO_SOURCE+, +GO_FOO_PATCH+, +GO_FOO_SITE+, ++GO_FOO_SUBDIR+, +GO_FOO_DEPENDENCIES+, +GO_FOO_LICENSE+, ++GO_FOO_LICENSE_FILES+, +GO_FOO_INSTALL_STAGING+, etc. + +Note that: + + * It is not necessary to add +go+ or +host-go+ in the + +GO_FOO_DEPENDENCIES+ variable of a package, since these basic + dependencies are automatically added as needed by the Go + package infrastructure. + +A few additional variables, specific to the Go infrastructure, can +optionally be defined, depending on the package's needs. Many of them +are only useful in very specific cases, typical packages will +therefore only use a few of them, or none. + +* If your package need a custom GOPATH to be compiled in, you can use the + +GO_FOO_GOPATH+. + +* +GO_FOO_GO_SRC_PATH+ is the path where your source will be compiled + relatively to the GOPATH. + The golang package infrastructure tries to guess the correct + sub folder to compile in but if guessing is not correct for you or your + package behaves differently, you can use this variable to + redefine the path. + +* +GOO_FOO_GO_LDFLAGS+ and +GO_FOO_GO_TAGS+ can be used to pass + respectively the LDFLAGS or the TAGS to the build command. + +GOO_FOO_GO_LDFLAGS+ and +GO_FOO_GO_TAGS+ will be combined into + the proper command line options to be passed to the compiler. + +* If you need to customize the install location for you binaries, you + can use +GOO_FOO_BINDIR+ to know where the binaries are. + +With the Go infrastructure, all the steps required to build and +install the packages are already defined, and they generally work well +for most Go-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 Go + infrastructure is used, if the package +.mk+ file defines its own + +GO_FOO_BUILD_CMDS+ variable, it will be used instead of the + default Go 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 d577ff0..be7468b 100644 --- a/docs/manual/adding-packages.txt +++ b/docs/manual/adding-packages.txt @@ -34,6 +34,8 @@ include::adding-packages-rebar.txt[] include::adding-packages-waf.txt[] +include::adding-packages-golang.txt[] + include::adding-packages-kernel-module.txt[] include::adding-packages-asciidoc.txt[]