From patchwork Sun Oct 2 09:09:58 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Yann E. MORIN" X-Patchwork-Id: 677486 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from whitealder.osuosl.org (smtp1.osuosl.org [140.211.166.138]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3smzv81FmKz9ryv for ; Sun, 2 Oct 2016 20:11:32 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b=U1CZTCtC; dkim-atps=neutral Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id 6910C91B78; Sun, 2 Oct 2016 09:11:30 +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 JwrR-5ioxPRh; Sun, 2 Oct 2016 09:11:23 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by whitealder.osuosl.org (Postfix) with ESMTP id A21C292183; Sun, 2 Oct 2016 09:10:37 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from whitealder.osuosl.org (smtp1.osuosl.org [140.211.166.138]) by ash.osuosl.org (Postfix) with ESMTP id 95D741C1E7D for ; Sun, 2 Oct 2016 09:10:21 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id 8DE759214C for ; Sun, 2 Oct 2016 09:10:21 +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 PBB1Nvbc-C0a for ; Sun, 2 Oct 2016 09:10:16 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wm0-f67.google.com (mail-wm0-f67.google.com [74.125.82.67]) by whitealder.osuosl.org (Postfix) with ESMTPS id 5B3AE9213B for ; Sun, 2 Oct 2016 09:10:14 +0000 (UTC) Received: by mail-wm0-f67.google.com with SMTP id b201so4732624wmb.1 for ; Sun, 02 Oct 2016 02:10:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references; bh=V12VfmjMRHUFigcnoA8Z2oIMZVg3QdUhzFHme8yJzR0=; b=U1CZTCtCvpeet83aOwwANNRRVwsgI/1P7grR1n7iUhQvlmr49/BDCAenH7PQFNMn4k i0wT6OpmwkBtLYNOyDSRaY4vqwGF2jKSnP5g1L+IRsYH4D8+PvDz4yXhHVLUeLidyLOG nZTGfPC2WOOfZANdIWU446FjjLCuKOhZBpqeGzMcz9dVjIAHDaCLvjXlo58PfT2KFkX4 tkIroVaRzKwt7m5Isq+jJVcuir8vyU0Kp66VzMWl7+8i5qrBjUpsP32h2MjMGFc3LUf4 NhzuiG4VitORggBMMpPgi4aonGKJxoIE3XDK/hzTK2haQs/9X/fcFZyu3BBcchNaaBcG HDyA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references; bh=V12VfmjMRHUFigcnoA8Z2oIMZVg3QdUhzFHme8yJzR0=; b=dW6OyWEgAVe3XlhskT7gPbcknL9gbOnvWZDswRTtKngcLN4q0f4e4tS89dHKWAEdqU A0S6g4DM5u07UrjqdIiibGg+mpfDq/l4UbkQH5CdWnfCWwrjjRlDmnDQGHxU+rx+p+/0 bOoTlYJCYleUBXHILQUt623QXXr/Nz7SnpcP4XJg/1SmfKwzbvdqBPA7at6qXVNh8b74 tgX0FLSrTMD4x7V2toiGL3R61/z2nn7d2j7OEFBq//DF4WPIVVuyz6K3q6Kkw9P7wrMr WYei8HZ3KvZw2WkGcuIQPc9sN80CzKlKdz2lV6ddUdf+OErmMSOpRBK4cukKYuQP0qf6 lOVg== X-Gm-Message-State: AA6/9RkyX/Gtcunu63RndlK6wPCSKiXbmAsmR3ZAn9lpZXnBohCRC+u3fIZALuANM7li8g== X-Received: by 10.28.20.12 with SMTP id 12mr5477983wmu.78.1475399412752; Sun, 02 Oct 2016 02:10:12 -0700 (PDT) Received: from gourin.bzh.lan (ns304657.ip-46-105-103.eu. [46.105.103.66]) by smtp.gmail.com with ESMTPSA id l206sm13020518wmf.15.2016.10.02.02.10.11 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sun, 02 Oct 2016 02:10:12 -0700 (PDT) From: "Yann E. MORIN" To: buildroot@buildroot.org Date: Sun, 2 Oct 2016 11:09:58 +0200 Message-Id: X-Mailer: git-send-email 2.7.4 In-Reply-To: References: Cc: Thomas Petazzoni , Romain Naour , "Yann E. MORIN" Subject: [Buildroot] [PATCH 09/10] docs/manual: document multi br2-external 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" Signed-off-by: "Yann E. MORIN" Cc: Thomas Petazzoni Cc: Arnout Vandecappelle Cc: Samuel Martin Cc: Romain Naour Cc: Julien CORJON --- docs/manual/br2-external-converting.txt | 9 ++++-- docs/manual/customize-outside-br.txt | 49 ++++++++++++++++++++++++--------- 2 files changed, 42 insertions(+), 16 deletions(-) diff --git a/docs/manual/br2-external-converting.txt b/docs/manual/br2-external-converting.txt index b207601..9c7a168 100644 --- a/docs/manual/br2-external-converting.txt +++ b/docs/manual/br2-external-converting.txt @@ -4,9 +4,12 @@ [[br2-external-converting]] == Converting old br2-external trees -Buildroot 2016.11 introduced a backward-incompatible change in the way -br2-external trees are handled. A minor change has to be made: adding -a name to your br2-external tree, see xref:outside-br-custom[]. +Before Buildroot 2016.11, it was possible to use only one br2-external +tree at once. With Buildroot 2016.11 came the possibility to use more +than one simultaneously (for details, see xref:outside-br-custom[]). + +This however means that older br2-external trees are not usable as-is. +A minor change has to be made: adding a name to your br2-external tree. This can be done very easily in just a few steps: diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt index 3ad0bc0..09977e0 100644 --- a/docs/manual/customize-outside-br.txt +++ b/docs/manual/customize-outside-br.txt @@ -19,10 +19,10 @@ place project-specific customizations in two locations: the br2-external mechanism and what to provide in a br2-external tree. -One can tell Buildroot to use a br2-external tree by setting the -+BR2_EXTERNAL+ make variable set to the path of the br2-external tree -to use. It can be passed to any Buildroot +make+ invocation. It is -automatically saved in the hidden +.br-external.mk+ file in the output +One can tell Buildroot to use one or more br2-external trees by setting +the +BR2_EXTERNAL+ make variable set to the path(s) of the br2-external +tree(s) to use. It can be passed to any Buildroot +make+ invocation. It +is automatically saved in the hidden +.br-external.mk+ file in the output directory. Thanks to this, there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It can however be changed at any time by passing a new value, and can be removed by passing an empty value. @@ -41,10 +41,10 @@ xref:br2-external-converting[] for help on doing so. Some examples: ----- -buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig +buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig ----- -From now on, definitions from the +/path/to/foobar+ br2-external tree +From now on, definitions from the +/path/to/foo+ br2-external tree will be used: ----- @@ -55,9 +55,15 @@ buildroot/ $ make legal-info We can switch to another br2-external tree at any time: ----- -buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig +buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig ----- +We can also use multiple br2-external trees: + +---- +buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/where/we/have/bar menuconfig +---- + Or disable the usage of any br2-external tree: ----- @@ -73,13 +79,23 @@ A br2-external tree must contain at least those three files: the keyword 'name:', followed by one or more spaces, followed by the name. + -Buildroot sets +BR2_EXTERNAL_$(NAME)_PATH+ to the absolute path of the +Buildroot sets +BR2_EXTERNAL_$(NAME)_PATH+ to the absolute path of each br2-external tree, so that you can use it to refer to your br2-external tree. This variable is available both in Kconfig, so you can use it to source your Kconfig files (see below) and in the Makefile, so that you can use it to include other Makefiles (see below) or refer to other files (like data files) from your br2-external tree. + +.Note: +Since it is possible to use multiple br2-external trees at once, this + name is used by Buildroot to generate variables for each of those trees. + That name is used to identify your br2-external tree, so try to come up + with a name that really describes your br2-external tree, in order for + it to be relatively unique, so that it does not clash with another name + from another br2-external tree, especially if you are planning on + somehow sharing your br2-external tree with third parties or using + br2-external trees from third parties. ++ Example of an +external.desc+ file that declares the name +FOO+: + ---- @@ -119,9 +135,10 @@ BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_FOO)/board/ * One can store package recipes (i.e. +Config.in+ and +.mk+), or even custom configuration options and make logic. Buildroot - automatically includes +Config.in+ to make it appear in the top-level - configuration menu, and includes +external.mk+ with the rest of the - makefile logic. + automatically includes the +Config.in+ from each br2-external tree to + make it appear in the top-level configuration menu, and includes the + +external.mk+ from each br2-external tree with the rest of the makefile + logic. + The main usage of this is to store package recipes. The recommended way to do this is to write a +Config.in+ file that looks like: @@ -146,5 +163,11 @@ And then in +$(BR2_EXTERNAL_FOO_42_PATH)/package/package1+ and * One can store Buildroot defconfigs in the +configs+ subdirectory of the br2-external tree. Buildroot will automatically show them in the output of +make list-defconfigs+ and allow them to be loaded with the - normal +make _defconfig+ command. They will be visible under the - +User-provided configs+' label in the 'make list-defconfigs' output. + normal +make _defconfig+ command. They will be visible in the + 'make list-defconfigs' output, below an +External configs+ label that + contains the name of the br2-extermnal tree they are defined in. ++ +.Note: +If a defconfig file is present in more than one br2-external tree, then + the first one is used. It is not possible to override a defconfig + bundled in Buildroot.