From patchwork Sat Dec 30 10:02:02 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Angelo Compagnucci X-Patchwork-Id: 854080 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=amarulasolutions-com.20150623.gappssmtp.com header.i=@amarulasolutions-com.20150623.gappssmtp.com header.b="zsvPXFVu"; 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 3z7zXM3L7gz9t32 for ; Sat, 30 Dec 2017 21:02:27 +1100 (AEDT) Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id C6B042ED7A; Sat, 30 Dec 2017 10:02:24 +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 Ozs1r4ifuRoS; Sat, 30 Dec 2017 10:02:23 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by silver.osuosl.org (Postfix) with ESMTP id 001A82E97C; Sat, 30 Dec 2017 10:02:22 +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 245451C0B30 for ; Sat, 30 Dec 2017 10:02:18 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by hemlock.osuosl.org (Postfix) with ESMTP id 21CF7874F2 for ; Sat, 30 Dec 2017 10:02:18 +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 SHLyrvUtAk4x for ; Sat, 30 Dec 2017 10:02:17 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wr0-f171.google.com (mail-wr0-f171.google.com [209.85.128.171]) by hemlock.osuosl.org (Postfix) with ESMTPS id 94F2786CDD for ; Sat, 30 Dec 2017 10:02:16 +0000 (UTC) Received: by mail-wr0-f171.google.com with SMTP id o15so11112069wrf.12 for ; Sat, 30 Dec 2017 02:02:16 -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=F+Okb6/JrNL4IYojyHFdfRV1XfkHqyn3EjA+0V3KENs=; b=zsvPXFVunqsQzPdvZaOakbzMGgfV8IKmfr14AbSL971tP9ScNraPNtW06Sm1vs6BZ9 n1XRjjoozDSQVWuQqyIPKXcrRmIxi/AKWSbCv0g0+Om3DS2oH1jTcxARs4/3jsLQGvzF j1vY/j6BHo3ccKNwj9D5Ge0GhfQ8Hx7Hi2fr1azzHUlUKNYaTXzDtz/4B8zSIYjD0xll ixYq1h6fPjvmGhb+8U6Kt6iwdGaVAyhH2oMcfQr2SQ6TYrrcMne2AxqK2f6stg4ieuHJ qvfs203CSkzUSGDUmB7jb/oPj/pMSffnphW93XSuYo7DsBfW9r5LxojSG6hFyB9QruKb HEmQ== 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=F+Okb6/JrNL4IYojyHFdfRV1XfkHqyn3EjA+0V3KENs=; b=pDRiAOFNrIaQCS0UwEutVqJMwAOmZ5j5ptzcDW/W+JGpmTOlOSinr7xXWAnQQlF0vd CDIBmjRfR9F88n5vE/rNRI7GyT7p1ePS+eCuyNrZ1OlSxc2ffPlSHgTrsL6zea3CCLCb Ip5bN6EiHcL0AIxSGftvect5W5Xp5ljFquFDboBwK2fnlcvgk2desu//O8Oy3gIj4KY5 Oq/sSFzMn99Vk7A06MAkGr7inM6hrlW6GHTqH8cLVQP/s4haLdtxuIF61MrF2ExLvsAA na5Y/d8vovnf+DYPYHYFnKPk/pnkovKkkrWlw73EIUpZ1o7LHGbpmmZoSbHRYvJpT9AR e0OA== X-Gm-Message-State: AKGB3mLK/RLvH9APBWgnhh3Bx6dyVtOExjCcDFklqnxd8F4UQlfe0uph pe9J02GNroVkY+55jvhfnFuwGsareDU= X-Google-Smtp-Source: ACJfBouUXOzg3tT6sUbekExt0C4iICnTpvjxGNth2Q3TZGrl+bvkK+RKFxN/if75i2cB4qVrl1wSKg== X-Received: by 10.223.161.208 with SMTP id v16mr34170003wrv.103.1514628134745; Sat, 30 Dec 2017 02:02:14 -0800 (PST) Received: from localhost.localdomain ([89.202.204.147]) by smtp.gmail.com with ESMTPSA id n65sm66180723wrb.17.2017.12.30.02.02.13 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sat, 30 Dec 2017 02:02:13 -0800 (PST) From: Angelo Compagnucci To: buildroot@buildroot.org Date: Sat, 30 Dec 2017 11:02:02 +0100 Message-Id: <1514628127-15938-3-git-send-email-angelo@amarulasolutions.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1514628127-15938-1-git-send-email-angelo@amarulasolutions.com> References: <1514628127-15938-1-git-send-email-angelo@amarulasolutions.com> Subject: [Buildroot] [PATCH v2 2/7] 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 --- Changes: v1 -> v2: Adding documentation for go TAGS docs/manual/adding-packages-golang.txt | 116 +++++++++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 118 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..5d6de3a --- /dev/null +++ b/docs/manual/adding-packages-golang.txt @@ -0,0 +1,116 @@ +// -*- 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. + +* If you need to customize the building tags you can use GOO_FOO_GO_TAGS + +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 e542124..56991ab 100644 --- a/docs/manual/adding-packages.txt +++ b/docs/manual/adding-packages.txt @@ -36,6 +36,8 @@ include::adding-packages-waf.txt[] include::adding-packages-meson.txt[] +include::adding-packages-golang.txt[] + include::adding-packages-kernel-module.txt[] include::adding-packages-asciidoc.txt[]