From patchwork Sat Apr 5 15:21:44 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Yann E. MORIN" X-Patchwork-Id: 337173 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from hemlock.osuosl.org (hemlock.osuosl.org [140.211.166.133]) by ozlabs.org (Postfix) with ESMTP id 5DC501400FB for ; Sun, 6 Apr 2014 02:22:19 +1100 (EST) Received: from localhost (localhost [127.0.0.1]) by hemlock.osuosl.org (Postfix) with ESMTP id 286378ACD3; Sat, 5 Apr 2014 15:22:16 +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 QBk2KogdVCcT; Sat, 5 Apr 2014 15:22:15 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by hemlock.osuosl.org (Postfix) with ESMTP id 974AC88219; Sat, 5 Apr 2014 15:22:14 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from whitealder.osuosl.org (whitealder.osuosl.org [140.211.166.138]) by ash.osuosl.org (Postfix) with ESMTP id 070941BF97E for ; Sat, 5 Apr 2014 15:22:13 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id 030368ACE8 for ; Sat, 5 Apr 2014 15:22:13 +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 RoPzcwJcQnFV for ; Sat, 5 Apr 2014 15:22:12 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wi0-f178.google.com (mail-wi0-f178.google.com [209.85.212.178]) by whitealder.osuosl.org (Postfix) with ESMTPS id 4657A8A96B for ; Sat, 5 Apr 2014 15:22:12 +0000 (UTC) Received: by mail-wi0-f178.google.com with SMTP id bs8so2784363wib.11 for ; Sat, 05 Apr 2014 08:22:10 -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=11PNIZMo8iCirMLrN+USO6hq3hoNY6feV3CGiVgqH/o=; b=jZOoytWeOE6ztWvO+aXm9rMx6KmhGycXIQ7HFz2cNyxn0P3u9tgVxCbV1hccN7Urqk nn75iuXwLMI47FQYRpYcjiF+NoSHwngtmw/tbRDqrJJj+kHqJzjXj+SE6EbYnXaKT17Z Ma6IhVwtMC3wYtvfVupv80qepFfXZARToBKljnph++ZHQtrDjQRNd/SorhPwh9GqTyeG lug04es0k9K1oQDRMPTdwdWRBE0NIx/ELaZ+jROh75ClfjxsYnuaFXytkAF4PC7T2e7s 0KxwBX4sX0w0CizrI3ZczC0gcT+LjbkjdmCnEWsb2z3kCyVoSuDWdGHuqL5U0aG9dc8E Y4Cg== X-Received: by 10.180.211.208 with SMTP id ne16mr12624095wic.21.1396711330860; Sat, 05 Apr 2014 08:22:10 -0700 (PDT) Received: from gourin.bzh.lan (ks3095497.kimsufi.com. [94.23.60.27]) by mx.google.com with ESMTPSA id t10sm11403796wiw.19.2014.04.05.08.22.09 for (version=TLSv1.1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Sat, 05 Apr 2014 08:22:10 -0700 (PDT) From: "Yann E. MORIN" To: buildroot@buildroot.org Date: Sat, 5 Apr 2014 17:21:44 +0200 Message-Id: <58a86e3a25f01b55ca428c13d83680ca0fb00cb1.1396711074.git.yann.morin.1998@free.fr> X-Mailer: git-send-email 1.8.3.2 In-Reply-To: References: Cc: "Yann E. MORIN" Subject: [Buildroot] [PATCH 07/21] manual: add virtual package tutorial X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.14 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-bounces@busybox.net From: "eric.le.bihan.dev@free.fr" The manual now features a new section with instructions about how to add a virtual package. Signed-off-by: Eric Le Bihan [yann.morin.1998@free.fr: move down statement about provider's .mk] Signed-off-by: "Yann E. MORIN" Reviewed-by: Samuel Martin Acked-by: Arnout Vandecappelle (Essensium/Mind) --- docs/manual/adding-packages-virtual.txt | 99 +++++++++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 101 insertions(+) create mode 100644 docs/manual/adding-packages-virtual.txt diff --git a/docs/manual/adding-packages-virtual.txt b/docs/manual/adding-packages-virtual.txt new file mode 100644 index 0000000..76f5794 --- /dev/null +++ b/docs/manual/adding-packages-virtual.txt @@ -0,0 +1,99 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +[[virtual-package-tutorial]] + +Virtual package tutorial +~~~~~~~~~~~~~~~~~~~~~~~~ + +In Buildroot, a virtual package is a package whose functionalities are +provided by one or more packages, referred to as 'providers'. The virtual +package management is an extensible mechanism allowing the user to choose +the provider used in the rootfs. + +For example, 'OpenGL ES' is an API for 2D and 3D graphics on embedded systems. +The implementation of this API is different for the 'Allwinner Tech Sunxi' and +the 'Texas Instruments OMAP35xx' plaftorms. So +libgles+ will be a virtual +package and +sunxi-mali+ and +ti-gfx+ will be the providers. + +In the following example, we will explain how to add a new virtual package +('something-virtual') and a provider for it ('some-provider'). + +First, let's create the virtual package. + +Virtual package's +Config.in+ file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The +Config.in+ file of virtual package 'something-virtual' should contain: + +--------------------------- +01: config BR2_PACKAGE_HAS_SOMETHING_VIRTUAL +02: bool +03: +04: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL +05: depends on BR2_PACKAGE_HAS_SOMETHING_VIRTUAL +06: string +--------------------------- + +In this file, we declare two options, +BR2_PACKAGE_HAS_SOMETHING_VIRTUAL+ and ++BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL+, whose values will be used by the +providers. + +Virtual package's +*.mk+ file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Makefile +package/something-virtual/something-virtual.mk+ should contain: + +--------------------------- +01: ################################################################################ +02: # +03: # something-virtual +04: # +05: ################################################################################ +06: +07: SOMETHING_VIRTUAL_SOURCE = +08: SOMETHING_VIRTUAL_DEPENDENCIES = $(call qstrip,$(BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL)) +09: +10: ifeq ($(BR2_PACKAGE_HAS_SOMETHING_VIRTUAL),y) +11: ifeq ($(SOMETHING_VIRTUAL_DEPENDENCIES),) +12: $(error No something-virtual implementation selected. Configuration error.) +13: endif +14: endif +15: +16: $(eval $(generic-package)) +--------------------------- + +The Makefile is quite small as it will only check if a provider for the +virtual package has been selected. + +Provider's +Config.in+ file +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When adding a package as a provider, only the +Config.in+ file requires some +modifications. The +*.mk+ file should follow the Buildroot infrastructure with +no change at all. + +The +Config.in+ file of the package 'some-provider', which provides the +functionalities of 'something-virtual', should contain: + +--------------------------- +01: config BR2_PACKAGE_SOME_PROVIDER +02: bool "some-provider" +03: select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL +04: help +05: This is a comment that explains what some-provider is. +06: +07: http://foosoftware.org/some-provider/ +08: +09: if BR2_PACKAGE_SOME_PROVIDER +10: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL +11: default "some-provider" +12: endif +--------------------------- + +On line 3, we select +BR2_PACKAGE_HAS_SOMETHING_VIRTUAL+, and on line 11, we +set the value of +BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL+ to the name of the +provider, but only if it is selected. + +Of course, do not forget to add the proper build and runtime dependencies for +this package! diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt index 745e33a..dbba930 100644 --- a/docs/manual/adding-packages.txt +++ b/docs/manual/adding-packages.txt @@ -24,6 +24,8 @@ include::adding-packages-luarocks.txt[] include::adding-packages-perl.txt[] +include::adding-packages-virtual.txt[] + include::adding-packages-hooks.txt[] include::adding-packages-gettext.txt[]