From patchwork Wed Dec 6 10:56:54 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Angelo Compagnucci X-Patchwork-Id: 845120 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.137; helo=fraxinus.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=amarulasolutions-com.20150623.gappssmtp.com header.i=@amarulasolutions-com.20150623.gappssmtp.com header.b="vooDip/M"; dkim-atps=neutral Received: from fraxinus.osuosl.org (smtp4.osuosl.org [140.211.166.137]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3ysFtb5YHyz9sBd for ; Wed, 6 Dec 2017 21:57:11 +1100 (AEDT) Received: from localhost (localhost [127.0.0.1]) by fraxinus.osuosl.org (Postfix) with ESMTP id BBF1A8803F; Wed, 6 Dec 2017 10:57:09 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from fraxinus.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id dP2BJeo0dXUH; Wed, 6 Dec 2017 10:57:08 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by fraxinus.osuosl.org (Postfix) with ESMTP id C9AD788055; Wed, 6 Dec 2017 10:57:08 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from fraxinus.osuosl.org (smtp4.osuosl.org [140.211.166.137]) by ash.osuosl.org (Postfix) with ESMTP id CA4431C041E for ; Wed, 6 Dec 2017 10:57:07 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by fraxinus.osuosl.org (Postfix) with ESMTP id C78208803F for ; Wed, 6 Dec 2017 10:57:07 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from fraxinus.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id edg06VcYkLFO for ; Wed, 6 Dec 2017 10:57:06 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wr0-f178.google.com (mail-wr0-f178.google.com [209.85.128.178]) by fraxinus.osuosl.org (Postfix) with ESMTPS id 2761987FE8 for ; Wed, 6 Dec 2017 10:57:06 +0000 (UTC) Received: by mail-wr0-f178.google.com with SMTP id o2so3423719wro.5 for ; Wed, 06 Dec 2017 02:57:06 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amarulasolutions-com.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=EBgkggFgEdo2n78txgnrq//LUMibkLdb89vTvLqjKY8=; b=vooDip/MvIOkFhpY4vm/wShdN+j5k+vAbesgIsjY2xr3euNE2zhFQ8HUdjUl6r14jk zPaD96bsXkaTpQbUEirfg+6IRCN5qHNo4/SRJ2gkPXGTqkkeX88Dk8e7ixE37CWE3PRz XZfeuVbqY4zDHDmKvXPqlSaIsvpPFlvCCoLOn9JnwVBWQcHioNyhe3jrRDvLnwh4/Nh+ 0g6cLkP76iqmn2z+rpfpQmYIJfu1bOQEPuzbTiGe9U+8mDjgLuRhk5SmK7odYefy2uKk bdCsDyw3fjEqOTMIH0yZ+7iMNy1Uhw88V/n1jTVGzKCi875oMfobQvRpOEylX0S3Uy3R gkDw== 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=EBgkggFgEdo2n78txgnrq//LUMibkLdb89vTvLqjKY8=; b=KqIt1oKzt8uD4LPPtwj8LI6twxFSE5d9D4aIG9vF9FKMFpjHOlah1aA/BJac+hYLvp 0fgd8eyJyv3cUyCUqgleJzzXDCOw6W+PjUIhS5Dm7nsvJg4VBM1nUAASac85QFHPSsm9 ezzQUDM8IqZPH4cybZfm7QOZMUBNQwKzD0hwY9AIVTKajBPx6Qe/XnkB6OLNxrUxeYZV CSxT4SLeXihfqtY68fFPL1UQiOfZUpXHqyr853XgvC/w5w+2tMXAe7pN9PZre7dj/K0Y +1AJkOYbeZ5xcXTGDMQWHKJFkbT3Y7uvNRjzbl+iQ37uALHD7xwfeHOh7BMCJD/uFOt/ kmIA== X-Gm-Message-State: AJaThX5ixDQkV/o6uKTHPvRLjiWPhjFOrdDKtKVK72fN5noIzzgJFMRb MbvmhrxujVz7TjgzCRoyZ0WyeTiDvAI= X-Google-Smtp-Source: AGs4zMYMMVDAHsglRb1Zva6reYgVO46YRwK4UIRp5rNX1w3svqpo4YU/xdaRGKyuZagkqLIDcwJzWw== X-Received: by 10.223.195.113 with SMTP id e46mr18642025wrg.149.1512557824270; Wed, 06 Dec 2017 02:57:04 -0800 (PST) Received: from localhost.localdomain ([89.202.204.147]) by smtp.gmail.com with ESMTPSA id 31sm2433971wrm.59.2017.12.06.02.57.03 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 06 Dec 2017 02:57:03 -0800 (PST) From: Angelo Compagnucci To: buildroot@buildroot.org Date: Wed, 6 Dec 2017 11:56:54 +0100 Message-Id: <1512557817-431-3-git-send-email-angelo@amarulasolutions.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1512557817-431-1-git-send-email-angelo@amarulasolutions.com> References: <1512557817-431-1-git-send-email-angelo@amarulasolutions.com> Subject: [Buildroot] [PATCH 2/5] docs/manual: adding documentation for the golang infrastructure X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.24 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Angelo Compagnucci MIME-Version: 1.0 Errors-To: buildroot-bounces@busybox.net Sender: "buildroot" From: Angelo Compagnucci 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[]