From patchwork Sun Nov 11 13:14:51 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Samuel Martin X-Patchwork-Id: 198273 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from silver.osuosl.org (silver.osuosl.org [140.211.166.136]) by ozlabs.org (Postfix) with ESMTP id C63022C0089 for ; Mon, 12 Nov 2012 00:17:22 +1100 (EST) Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id 195F831076; Sun, 11 Nov 2012 13:17:21 +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 e7PHDVeCm1gb; Sun, 11 Nov 2012 13:17:14 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by silver.osuosl.org (Postfix) with ESMTP id 73DEA31474; Sun, 11 Nov 2012 13:16:23 +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 657548F753 for ; Sun, 11 Nov 2012 13:15:45 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id 38B678C2E3 for ; Sun, 11 Nov 2012 13:15:41 +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 jFb2q69JQr93 for ; Sun, 11 Nov 2012 13:15:39 +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 404F98C2D7 for ; Sun, 11 Nov 2012 13:15:39 +0000 (UTC) Received: by mail-we0-f171.google.com with SMTP id s43so3028443wey.16 for ; Sun, 11 Nov 2012 05:15:39 -0800 (PST) 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=AZoHQqwL5Ypc6EqW6kpvPhM9faDYQfbjjuWsPcyGgmI=; b=jXFfu6zD0uyaeiZTIXWRHllZdwIsIVIvdxTslCK7rBVPnCB4Q9whj79wV1bAarwdmf AkxJAmG4Plr21LxU9CYd/ZlkqjNWW+kwk0txyDdUT6lbLxU2+Ea1x0gvvUr5jXRT0jLU Uq+EDHaublzP1U8KZz9FewW8F99yAHkzvcrcy6TzPl1k3lByly5hF7QDeeU90ZjBxhn9 zdvGzCE8LjCOyqdua3DBpgWR9kWTfl6pC5xtdXNg+HEqYvLDHhdHyGVILHvePbXwSdiA a5Og7qoPfmvsD5L1iT7wOoZmKlQbKm/YRmviLLowMq07Poa6oHavnveMKUv0jjpY4j/x /j/g== Received: by 10.216.209.224 with SMTP id s74mr7372053weo.63.1352639738945; Sun, 11 Nov 2012 05:15:38 -0800 (PST) Received: from localhost.localdomain (ivr94-4-82-229-165-48.fbx.proxad.net. [82.229.165.48]) by mx.google.com with ESMTPS id hv4sm10262550wib.0.2012.11.11.05.15.37 (version=SSLv3 cipher=OTHER); Sun, 11 Nov 2012 05:15:38 -0800 (PST) From: Samuel Martin To: buildroot@busybox.net Date: Sun, 11 Nov 2012 14:14:51 +0100 Message-Id: <1352639701-27829-14-git-send-email-s.martin49@gmail.com> X-Mailer: git-send-email 1.8.0 In-Reply-To: <1352639701-27829-1-git-send-email-s.martin49@gmail.com> References: <1352639701-27829-1-git-send-email-s.martin49@gmail.com> Subject: [Buildroot] [PATCH 13/23] 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 Signed-off-by: Samuel Martin create mode 100644 docs/manual/writing-rules.txt diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt index 37f703d..b254b0f 100644 --- a/docs/manual/developer-guide.txt +++ b/docs/manual/developer-guide.txt @@ -3,6 +3,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..e0a5a2a --- /dev/null +++ b/docs/manual/writing-rules.txt @@ -0,0 +1,125 @@ +// -*- mode:doc; -*- + +Writing rules +------------- + +Overall, those writing rules are here to help you add new files in +Buildroot or refactor existing ones. + +If you slightly modify some existing file, the important thing is +keeping the 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 entries for almost anything configurable in +Buildroot. + +An 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. + +The configuration system used in Buildroot, so the content of the ++Config.in+ files, is regular _Kconfig_. Further details about +_Kconfig_: refer to +http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[]. + +[[writing-rules-mk]] + +The +.mk+ file +~~~~~~~~~~~~~~ + +* Assignment: use +=+ preceded 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 hooks: keep hook definition and assignment together in one + 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[].