From patchwork Tue Mar 20 23:09:59 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Samuel Martin X-Patchwork-Id: 147864 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 9BF41B6ED0 for ; Wed, 21 Mar 2012 10:12:22 +1100 (EST) Received: from localhost (localhost [127.0.0.1]) by fraxinus.osuosl.org (Postfix) with ESMTP id ACE3A100E5B; Tue, 20 Mar 2012 23:12:21 +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 WAl2aBBikWkg; Tue, 20 Mar 2012 23:12:14 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by fraxinus.osuosl.org (Postfix) with ESMTP id C84C9101125; Tue, 20 Mar 2012 23:11:11 +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 546078F75B for ; Tue, 20 Mar 2012 23:11:03 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id 479758D0AB for ; Tue, 20 Mar 2012 23:11:03 +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 vy-S0h9HfFYA for ; Tue, 20 Mar 2012 23:11:01 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-we0-f171.google.com (mail-we0-f171.google.com [74.125.82.171]) by whitealder.osuosl.org (Postfix) with ESMTPS id 890CE8D071 for ; Tue, 20 Mar 2012 23:11:01 +0000 (UTC) Received: by mail-we0-f171.google.com with SMTP id m1so946014wer.16 for ; Tue, 20 Mar 2012 16:11:01 -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=m8V1USDvKnlhHARJhRf1xp3i+swkanO9RV9xZgb1Fo8=; b=gvN8vFbZ2redGeK07QroIg/Vj3fhr6Vq4vyG6PG+kT04Dfu47swZkSNv1U/P6MdREF hGc/J6CJpIE3r7HNCglYO9+Cth6EjYkm5j+h8NRCeXzFcfelnmRy4QmUGr5AoEMnjIWc Jk1LND5xSxgycOiH5Oj9GV+zYdvF6M63oubq57E7p9awoATlx5cnAydI178XcXrkKHgt hjlR7pQ1VU1pav02hOqbM12j5dOttW304CUz8wYUdXvnCkrjUiz7YOtPUdkKmtJIKuHY aTa0N1H2w0qM+lzI5Umwg5tj8i3ucWgBTpZ2AV7qvtA9wGgVrmG9SwATZoz+X+p7glHQ RODA== Received: by 10.180.107.162 with SMTP id hd2mr32730798wib.8.1332285061200; Tue, 20 Mar 2012 16:11:01 -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 fz9sm37727837wib.3.2012.03.20.16.10.59 (version=SSLv3 cipher=OTHER); Tue, 20 Mar 2012 16:11:00 -0700 (PDT) From: Samuel MARTIN To: buildroot@busybox.net Date: Wed, 21 Mar 2012 00:09:59 +0100 Message-Id: <1332285001-12881-10-git-send-email-s.martin49@gmail.com> X-Mailer: git-send-email 1.7.9.4 In-Reply-To: <1332285001-12881-1-git-send-email-s.martin49@gmail.com> References: <1332285001-12881-1-git-send-email-s.martin49@gmail.com> Subject: [Buildroot] [PATCH 09/11] manual: update 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 Signed-off-by: Samuel MARTIN --- docs/manual/adding-packages-directory.txt | 5 ++ docs/manual/writing-rules.txt | 108 +++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) 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/writing-rules.txt b/docs/manual/writing-rules.txt index 284cee2..b18f30b 100644 --- a/docs/manual/writing-rules.txt +++ b/docs/manual/writing-rules.txt @@ -1,11 +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[].