From patchwork Sat Jun 9 09:46:47 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Yann E. MORIN" X-Patchwork-Id: 927116 Return-Path: X-Original-To: incoming-buildroot@patchwork.ozlabs.org Delivered-To: patchwork-incoming-buildroot@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=busybox.net (client-ip=140.211.166.136; helo=silver.osuosl.org; envelope-from=buildroot-bounces@busybox.net; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=free.fr Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="ijinHqjQ"; dkim-atps=neutral Received: from silver.osuosl.org (smtp3.osuosl.org [140.211.166.136]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 412vZH0pWqz9s47 for ; Sat, 9 Jun 2018 19:47:01 +1000 (AEST) Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id 0EF7E2EBA6; Sat, 9 Jun 2018 09:46:58 +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 L1w9DlC3DAk2; Sat, 9 Jun 2018 09:46:56 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by silver.osuosl.org (Postfix) with ESMTP id 560EF2E7E3; Sat, 9 Jun 2018 09:46:56 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from silver.osuosl.org (smtp3.osuosl.org [140.211.166.136]) by ash.osuosl.org (Postfix) with ESMTP id 1E8A41C273C for ; Sat, 9 Jun 2018 09:46:55 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id 1BCC12E7E3 for ; Sat, 9 Jun 2018 09:46:55 +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 oMZol1NiGV51 for ; Sat, 9 Jun 2018 09:46:53 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wm0-f65.google.com (mail-wm0-f65.google.com [74.125.82.65]) by silver.osuosl.org (Postfix) with ESMTPS id 5B8322E2C4 for ; Sat, 9 Jun 2018 09:46:53 +0000 (UTC) Received: by mail-wm0-f65.google.com with SMTP id n5-v6so7814210wmc.5 for ; Sat, 09 Jun 2018 02:46:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id; bh=z1NeLoKJIyscZ6/PXNrBsLHzhCpHbgHIEhQChvvArbE=; b=ijinHqjQda7DCkIRGNxAxl9sOVcRxOJjKWZ1bpYqtbqCQT0/IUOKuc/SMMOS9Ia1/V sXEJAmkWz3E4l8oGzsWEK37rQfXLmNRt+sA4gZIAGPpESBdvS1RS9ewmzMDOHsReojEo GZaOdwychee+xzDK95joQ8B8lHk5/OHxUrpJlBC1WyoM0I5OmUUkqC8D6ZMYyM8nMp7C F+p+gWJnOEWLeJQ2HsAaB4ukKkF263HOAzfdMvMz3Dl676+eXnfwitOLY7tJHoJvxzn1 e0BG9hamUuzrkIlDQRMVWpISwiqP2XEHkJrH+P19MlVuN3FF0lqBHl9qgGbCuOMEwbnT 7tuA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id; bh=z1NeLoKJIyscZ6/PXNrBsLHzhCpHbgHIEhQChvvArbE=; b=bjmfnYiCGAnN6k492Y+UFzL+LxHitrcpov2Cft5eB7qdI6p1Xb2rX+w9/uhltZ2rlo Og8OnvGVhXrs5hCEc8uO2U+gZbmcvkwyq2Z9w0cpDcySW2l5TzbEE7M/bzHESUkR9hu0 AZPdJgzopvGWqdJhosrp7AZjjvvb/cu7ov09BOCpZOWLQnCWTKRnyQtGtEdzGt439seN zABdXjRfil/hHYXYOfolIo1GVlJbuf2+6pdTNoMQs1uB3SonLDMAgAFFRqZv5mgzRRjW J3v8x1bt2CpeFVsYV6yODXf5rZzkiOQta8jrP3dX6Q0CgDomzFg/v40Qvq02fvr3TWm7 nERg== X-Gm-Message-State: APt69E1fNyAZXSiZrGdZJ6A61nu4IjqFcjWdaEpahQQ1920AH2fDpyR9 ssFNvKn2WNgRMKcNY0VFBnHB9w== X-Google-Smtp-Source: ADUXVKIdpgu+Jkxwg/cJGMh862xFCHnA05IGqEtLnM0F/VxFT2+mnKFeEy4UxFfrwsCuxoHShtWsEA== X-Received: by 2002:a1c:7ce:: with SMTP id 197-v6mr3534110wmh.134.1528537611592; Sat, 09 Jun 2018 02:46:51 -0700 (PDT) Received: from scaer.bzh.lan (2a01cb088610730055df554501746183.ipv6.abo.wanadoo.fr. [2a01:cb08:8610:7300:55df:5545:174:6183]) by smtp.gmail.com with ESMTPSA id o9-v6sm15098189wrn.73.2018.06.09.02.46.50 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 09 Jun 2018 02:46:50 -0700 (PDT) From: "Yann E. MORIN" To: buildroot@buildroot.org Date: Sat, 9 Jun 2018 11:46:47 +0200 Message-Id: <20180609094647.21460-1-yann.morin.1998@free.fr> X-Mailer: git-send-email 2.14.1 Subject: [Buildroot] [PATCH] docs/manual: document filesystems X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.24 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Thomas De Schampheleire , "Yann E. MORIN" , Thomas Petazzoni MIME-Version: 1.0 Errors-To: buildroot-bounces@busybox.net Sender: "buildroot" We do expect that users be able to implement new filesystems and submit them, or have local, custom and private filesystems in their br2-external trees. So, add documentation for filesystems, based on the format we have for packages. Reported-by: Carlos Santos Signed-off-by: "Yann E. MORIN" Cc: Thomas De Schampheleire Cc: Carlos Santos Cc: Thomas Petazzoni --- Changes v1 -> v2: - credit Carlos for prompting this addition to the manual. :-) - fix the name of the _CMD macro (no trailing 'S') --- docs/manual/adding-filesystems.txt | 119 ++++++++++++++++++++++++++++++++++ docs/manual/adding-packages-hooks.txt | 7 +- docs/manual/adding-packages.txt | 2 + 3 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 docs/manual/adding-filesystems.txt diff --git a/docs/manual/adding-filesystems.txt b/docs/manual/adding-filesystems.txt new file mode 100644 index 0000000000..4731526c0f --- /dev/null +++ b/docs/manual/adding-filesystems.txt @@ -0,0 +1,119 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +=== Infrastructure for filesystems + +As for packages, Buildroot provides an infrastructure to build +filesystems. + +The filesystem infrastructure follows a carefully-crafted sequence: + +1. Assemble an intermediate, internal tarball from the +target/+ + directory: + * create users and groups, + * set the correct rights on files, + * create device nodes, + * create the intermediate tarball; +2. Then for each filesystem: + * extract the intermediate tarball to a filesystem-specific + +$(TARGET_DIR)+, + * execute the filesystem pre-gen hooks (see below), + * optionally, touch everything to a specific date, for reproducibility, + * execute the filesystem commands, + * execute the filesystem post-gen hooks (see below), + * remove the filesystem-specific +$(TARGET_DIR)+; +3. Remove the intermediate tarball. + +[[filesystem-tutorial]] +==== +filesystem+ tutorial + +Let's look at an example filesytem. First and foremost, like for a +package, create a directory named from your filesystem, e.g. +foo+. + +Then, create a +Config.in+ file describing the menuconfig entries +for the filesystem. Be sure to have that +Config.in+ included from ++fs/Config.in+ (or from the +Config.in+ of your *br2-external* tree). +For example: + +---- +01: config BR2_TARGET_ROOTFS_FOO +02: bool "foo root filesystem" +03: help +04: Build a foo root filesystem. +05: +06: if BR2_TARGET_ROOTFS_FOO +07: +08: config BR2_TARGET_ROOTFS_FOO_FORMAT_BAR +09: bool "bar format" +10: help +11: Enable the bar format. +12: +13: endif +---- + +Then, in the same directory, create a +foo.mk+ file describing how +to actually assemble the filesystem image from the content of ++$(TARGET_DIR)+. Be sure that this +.mk+ file is included in the +Makefile code (automatic for built-in filesystems, not for filesystems +in a *br2-external* tree.) For example: + +---- +01: ################################################################################ +02: # +03: # foo filesystem +04: # +05: ################################################################################ +06: +07: ROOTFS_FOO_DEPENDENCIES = host-foo-utils +08: +09: ifeq ($(BR2_TARGET_ROOTFS_FOO_FORMAT_BAR),y) +10: ROOTFS_FOO_OPTS = --format=bar +11: else +12: ROOTFS_FOO_OPTS = --format=foo +13: endif +14: +15: define ROOTFS_FOO_CMD +16: $(HOST_DIR)/bin/mkfs.foo \ +17: --root-dir=$(TARGET_DIR) \ +18: --option-foo --option-bar \ +19: $(ROOTFS_FOO_OPTS) \ +20: --output-file=$(@) +21: endef +22: +23: $(eval $(rootfs)) +---- + +On line 7, we specify the dependencies on packages needed to build the +filesystem. Usually, those dependencies are one or more host-packages +that provide the filesystem generator. + +On lines 9 to 13, we define a conditional set of options, depending on +the user's choice. + +On lines 15 to 21, we define the actual command that will generate the +filesystem image. + +Finally, on line 23, we invoke the +rootfs+ macro that generates all the +Makefile rules that actually allow the filesystem to be built. + +[[filesystem-reference]] +==== +filesystem+ reference + +If one compares a package with a filesystem, one may notice that the +variables for a filesystem start with the prefix +ROOTFS_+, when the +variables for packages have no prefix. + +There is a single macro that a filesystem may set: + +* +ROOTFS_FOO_CMD+ contains the commands to execute to actually + generate the filesystem iamge from the content of the +$(TARGET_DIR)+ + directory. + +Additionally, like for packages, there are a set of hooks; see +xref:hooks[] for details. + +And here is a list of variables that may be used (but may *not* be set): + +* +$(TARGET_DIR)+ is the directory containing the +target/+ directory. + +* +$(@)+ is the filename where to store the filesystem image into. diff --git a/docs/manual/adding-packages-hooks.txt b/docs/manual/adding-packages-hooks.txt index 0ce79f8907..34d5801169 100644 --- a/docs/manual/adding-packages-hooks.txt +++ b/docs/manual/adding-packages-hooks.txt @@ -11,7 +11,7 @@ Most hooks aren't really useful for generic packages, since the +.mk+ file already has full control over the actions performed in each step of the package construction. -The following hook points are available: +The following hook points are available for packages: * +LIBFOO_PRE_DOWNLOAD_HOOKS+ * +LIBFOO_POST_DOWNLOAD_HOOKS+ @@ -46,6 +46,11 @@ The following hook points are available: * +LIBFOO_PRE_LEGAL_INFO_HOOKS+ * +LIBFOO_POST_LEGAL_INFO_HOOKS+ +The following hook points are available for filesystems: + +* +ROOTFS_FOO_PRE_GEN_HOOKS+ +* +ROOTFS_FOO_POST_GEN_HOOKS+ + These variables are 'lists' of variable names containing actions to be performed at this hook point. This allows several hooks to be registered at a given hook point. Here is an example: diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt index 4a4a17e879..83c93f3dde 100644 --- a/docs/manual/adding-packages.txt +++ b/docs/manual/adding-packages.txt @@ -47,6 +47,8 @@ include::adding-packages-asciidoc.txt[] include::adding-packages-linux-kernel-spec-infra.txt[] +include::adding-filesystems.txt[] + include::adding-packages-hooks.txt[] include::adding-packages-gettext.txt[]