From patchwork Sun May 13 10:38:19 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Samuel Martin X-Patchwork-Id: 158822 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from fraxinus.osuosl.org (fraxinus.osuosl.org [140.211.166.137]) by ozlabs.org (Postfix) with ESMTP id E3DDEB7002 for ; Sun, 13 May 2012 20:41:34 +1000 (EST) Received: from localhost (localhost [127.0.0.1]) by fraxinus.osuosl.org (Postfix) with ESMTP id B6E5E10154E; Sun, 13 May 2012 10:41:33 +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 m2OuhjI75tTw; Sun, 13 May 2012 10:41:30 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by fraxinus.osuosl.org (Postfix) with ESMTP id 9EFB110155E; Sun, 13 May 2012 10:40:37 +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 393278F75B for ; Sun, 13 May 2012 10:39:56 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id 1541181C2D for ; Sun, 13 May 2012 10:39:55 +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 RRAOJ5mvNqCW for ; Sun, 13 May 2012 10:39:40 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wi0-f181.google.com (mail-wi0-f181.google.com [209.85.212.181]) by whitealder.osuosl.org (Postfix) with ESMTPS id C52498AAB0 for ; Sun, 13 May 2012 10:39:37 +0000 (UTC) Received: by mail-wi0-f181.google.com with SMTP id hn14so2709974wib.10 for ; Sun, 13 May 2012 03:39:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:date:message-id:x-mailer:in-reply-to:references; bh=kOE4dIFzmXo73Vzah4oVgB82xNUx6hBMcRwfg4auIw8=; b=BB136sGa95LrMspKWX8wH18kWX7JKsJjvsa32UzRStm+1nDm2yYhPNXOzZZFow8SFV MII3ZENuLnD5yOsowU9PKZg4CwUdtThanIbPBAgtOpEGjzljJTSGSG+nWmohVrbzfoXx JNuksZdMHQogGhVIg0ooRJNf6NbYOmMwQqqJs+pdJNIoJ2Fw2rYHAkZSxr44X3KycwSK Uapxi89IfzvdlDso16CwjjGWKzXp9Fn3lPvgeDVq+5v3eWIShB/eBhwTcXGw5nA5DOOY IHsRlPRzN0+0eguSXrXcos9Z9HU6DIOH8sOIJdGTvu/Iwqz+G06qJ6Y39lbRi2KtUZz4 k5Yg== Received: by 10.180.81.36 with SMTP id w4mr3065738wix.16.1336905577335; Sun, 13 May 2012 03:39:37 -0700 (PDT) Received: from localhost.localdomain (ivr94-4-82-229-165-48.fbx.proxad.net. [82.229.165.48]) by mx.google.com with ESMTPS id r2sm41271946wif.7.2012.05.13.03.39.35 (version=SSLv3 cipher=OTHER); Sun, 13 May 2012 03:39:36 -0700 (PDT) From: Samuel Martin To: buildroot@busybox.net Date: Sun, 13 May 2012 12:38:19 +0200 Message-Id: <1336905501-9757-10-git-send-email-s.martin49@gmail.com> X-Mailer: git-send-email 1.7.10.2 In-Reply-To: <1336905501-9757-1-git-send-email-s.martin49@gmail.com> References: <4FAEEFA8.2070005@mind.be> <1336905501-9757-1-git-send-email-s.martin49@gmail.com> Subject: [Buildroot] [PATCH v2 09/11] manual: add writing-rules.txt 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: Samuel MARTIN Signed-off-by: Samuel Martin create mode 100644 docs/manual/writing-rules.txt diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt index 1428f37..e36eafc 100644 --- a/docs/manual/adding-packages-directory.txt +++ b/docs/manual/adding-packages-directory.txt @@ -145,6 +145,9 @@ is also enabled, but not necessarily built before your package. To do so, the dependency also needs to be expressed in the +.mk+ file of the package. +Further formating details: see xref:writing-rules-config-in[the +writing rules]. + The +.mk+ file ^^^^^^^^^^^^^^ @@ -185,3 +188,5 @@ different way, using different infrastructures: many of them in the tree, we keep them documented in a xref:handwritten-tutorial[tutorial]. +Further formating details: see xref:writing-rules-mk[the writing +rules]. diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt index 69f3632..14589c2 100644 --- a/docs/manual/developer-guide.txt +++ b/docs/manual/developer-guide.txt @@ -1,6 +1,8 @@ Developer Guidelines ==================== +include::writing-rules.txt[] + include::adding-packages.txt[] include::board-support.txt[] diff --git a/docs/manual/writing-rules.txt b/docs/manual/writing-rules.txt new file mode 100644 index 0000000..b18f30b --- /dev/null +++ b/docs/manual/writing-rules.txt @@ -0,0 +1,119 @@ +Writing rules +------------- + +Overall, those writing rules are here to help you adding new files in +Buildroot or refactoring existing ones. In these cases, should be followed. + +If you slightly modify some existing file, the important thing is +keeping th consistency of the whole file, so you can: +* either follow the potentially deprecated rules used all over this +file +* or entirely rework it in order to make it comply with those rules. + +[[writing-rules-config-in]] + ++Config.in+ file +~~~~~~~~~~~~~~~~ + ++Config.in+ files contain entry for almost anything configurable in +buildroot. + +Entry has the following pattern: + +--------------------- +config BR2_PACKAGE_LIBFOO + bool "libfoo" + depends on BR2_PACKAGE_LIBBAZ + select BR2_PACKAGE_LIBBAR + help + This is a comment that explains what libfoo is. + + http://foosoftware.org/libfoo/ +--------------------- + +* The +bool+, +depends on+, +select+ and +help+ lines are indented + with one tab. + +* The help text itself should be indented with one tab and two + spaces. + + +[[writing-rules-mk]] + +The +.mk+ file +~~~~~~~~~~~~~~ + +* Affectation: use +=+ preceeded and followed by one space: ++ +--------------------- +LIBFOO_VERSION = 1.0 +LIBFOO_CONF_OPT += --without-python-support +--------------------- + +* Indentation: use tab only: ++ +--------------------- +define LIBFOO_REMOVE_DOC +$(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \ + $(TARGET_DIR)/usr/share/man/man3/libfoo* +endef +--------------------- + +* Optional dependency: + +** Prefer multi-line syntax. ++ +YES: ++ +--------------------- +ifeq ($(BR2_PACKAGE_PYTHON),y) +LIBFOO_CONF_OPT += --with-python-support +LIBFOO_DEPENDENCIES += python +else +LIBFOO_CONF_OPT += --without-python-support +endif +--------------------- ++ +NO: ++ +--------------------- +LIBFOO_CONF_OPT += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support +LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,) +--------------------- + +** Keep configure options and dependencies close together. + +* Optional hook: Keep hook function definition close hooks variable + affection nested in the +if+ block: ++ +YES: ++ +--------------------- +ifneq ($(BR2_LIBFOO_INSTALL_DATA),y) +define LIBFOO_REMOVE_DATA + $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data +endef +LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA +endif +--------------------- ++ +NO: ++ +--------------------- +define LIBFOO_REMOVE_DATA + $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data +endef + +ifneq ($(BR2_LIBFOO_INSTALL_DATA),y) +LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA +endif +--------------------- + +The documentation +~~~~~~~~~~~~~~~~~ + +The documentation uses the +http://www.methods.co.nz/asciidoc/[asciidoc] format. + +Further details about the http://www.methods.co.nz/asciidoc/[asciidoc] +syntax: refer to http://www.methods.co.nz/asciidoc/userguide.html[].