From 362af615cd20dc7b4b0dd6fdcd7f2315a57de9a4 Mon Sep 17 00:00:00 2001 From: Arnout Vandecappelle Date: Fri, 12 Jul 2024 20:23:24 +0200 Subject: [PATCH] docs/manual: normalize delimiters of listing blocks Although the asciidoc toolchain accepts any number of ~ to delimit a listing block (i.e. a code block), it is actually specified to be exactly four, i.e. ~~~~. Currently, a mix of diffrent numbers of ~ are being used - sometimes even a different number at the beginning and at the end of the block. Normalize this to always use exactly four ~ for the delimiter. Signed-off-by: Arnout Vandecappelle (cherry picked from commit 447fa1fca425e629cc65cd0a8261a4c09ddf67d2) Signed-off-by: Peter Korsgaard --- docs/manual/adding-board-support.adoc | 4 +- docs/manual/adding-packages-autotools.adoc | 4 +- docs/manual/adding-packages-cargo.adoc | 8 +- docs/manual/adding-packages-cmake.adoc | 4 +- docs/manual/adding-packages-directory.adoc | 60 ++++++------- docs/manual/adding-packages-generic.adoc | 28 +++---- docs/manual/adding-packages-golang.adoc | 4 +- docs/manual/adding-packages-hooks.adoc | 4 +- docs/manual/adding-packages-kconfig.adoc | 4 +- ...ding-packages-linux-kernel-spec-infra.adoc | 16 ++-- docs/manual/adding-packages-luarocks.adoc | 4 +- docs/manual/adding-packages-meson.adoc | 4 +- docs/manual/adding-packages-perl.adoc | 4 +- docs/manual/adding-packages-python.adoc | 24 +++--- docs/manual/adding-packages-qmake.adoc | 4 +- docs/manual/adding-packages-rebar.adoc | 4 +- docs/manual/adding-packages-tips.adoc | 12 +-- docs/manual/adding-packages-virtual.adoc | 24 +++--- docs/manual/adding-packages-waf.adoc | 4 +- docs/manual/beyond-buildroot.adoc | 16 ++-- docs/manual/ccache-support.adoc | 4 +- docs/manual/common-usage.adoc | 64 +++++++------- docs/manual/configure.adoc | 4 +- docs/manual/contribute.adoc | 84 +++++++++---------- .../manual/customize-directory-structure.adoc | 12 +-- docs/manual/customize-outside-br.adoc | 24 +++--- docs/manual/customize-packages.adoc | 8 +- docs/manual/download-location.adoc | 4 +- docs/manual/faq-troubleshooting.adoc | 4 +- docs/manual/getting.adoc | 8 +- docs/manual/legal-notice.adoc | 4 +- docs/manual/make-tips.adoc | 24 +++--- docs/manual/package-make-target.adoc | 4 +- docs/manual/patch-policy.adoc | 16 ++-- docs/manual/quickstart.adoc | 20 ++--- docs/manual/rebuilding-packages.adoc | 4 +- docs/manual/using-buildroot-debugger.adoc | 12 +-- docs/manual/using-buildroot-development.adoc | 24 +++--- docs/manual/writing-rules.adoc | 36 ++++---- 39 files changed, 298 insertions(+), 298 deletions(-) diff --git a/docs/manual/adding-board-support.adoc b/docs/manual/adding-board-support.adoc index ef6dbd3c2b..9501262086 100644 --- a/docs/manual/adding-board-support.adoc +++ b/docs/manual/adding-board-support.adoc @@ -51,10 +51,10 @@ Before submitting patches for new boards it is recommended to test it by building it using latest gitlab-CI docker container. To do this use +utils/docker-run+ script and inside it issue these commands: --------------------- +---- $ make _defconfig $ make --------------------- +---- By default, Buildroot developers use the official image hosted on the https://gitlab.com/buildroot.org/buildroot/container_registry/2395076[gitlab.com diff --git a/docs/manual/adding-packages-autotools.adoc b/docs/manual/adding-packages-autotools.adoc index c2b90f31eb..a45d1652b5 100644 --- a/docs/manual/adding-packages-autotools.adoc +++ b/docs/manual/adding-packages-autotools.adoc @@ -10,7 +10,7 @@ First, let's see how to write a +.mk+ file for an autotools-based package, with an example : ------------------------- +---- 01: ################################################################################ 02: # 03: # libfoo @@ -26,7 +26,7 @@ package, with an example : 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf 14: 15: $(eval $(autotools-package)) ------------------------- +---- On line 7, we declare the version of the package. diff --git a/docs/manual/adding-packages-cargo.adoc b/docs/manual/adding-packages-cargo.adoc index a2a15ed996..1d476589f8 100644 --- a/docs/manual/adding-packages-cargo.adoc +++ b/docs/manual/adding-packages-cargo.adoc @@ -14,7 +14,7 @@ called "crates". The +Config.in+ file of Cargo-based package 'foo' should contain: ---------------------------- +---- 01: config BR2_PACKAGE_FOO 02: bool "foo" 03: depends on BR2_PACKAGE_HOST_RUSTC_TARGET_ARCH_SUPPORTS @@ -23,11 +23,11 @@ The +Config.in+ file of Cargo-based package 'foo' should contain: 06: This is a comment that explains what foo is. 07: 08: http://foosoftware.org/foo/ ---------------------------- +---- And the +.mk+ file for this package should contain: ------------------------------- +---- 01: ################################################################################ 02: # 03: # foo @@ -41,7 +41,7 @@ And the +.mk+ file for this package should contain: 11: FOO_LICENSE_FILES = COPYING 12: 13: $(eval $(cargo-package)) --------------------------------- +---- The Makefile starts with the definition of the standard variables for package declaration (lines 7 to 11). diff --git a/docs/manual/adding-packages-cmake.adoc b/docs/manual/adding-packages-cmake.adoc index e375e17d74..845f54ad4b 100644 --- a/docs/manual/adding-packages-cmake.adoc +++ b/docs/manual/adding-packages-cmake.adoc @@ -10,7 +10,7 @@ First, let's see how to write a +.mk+ file for a CMake-based package, with an example : ------------------------- +---- 01: ################################################################################ 02: # 03: # libfoo @@ -26,7 +26,7 @@ with an example : 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf 14: 15: $(eval $(cmake-package)) ------------------------- +---- On line 7, we declare the version of the package. diff --git a/docs/manual/adding-packages-directory.adoc b/docs/manual/adding-packages-directory.adoc index 0b7221aae0..2039c2c7cc 100644 --- a/docs/manual/adding-packages-directory.adoc +++ b/docs/manual/adding-packages-directory.adoc @@ -24,7 +24,7 @@ file will contain the option descriptions related to our +libfoo+ software that will be used and displayed in the configuration tool. It should basically contain: ---------------------------- +---- config BR2_PACKAGE_LIBFOO bool "libfoo" help @@ -32,7 +32,7 @@ config BR2_PACKAGE_LIBFOO should be wrapped. http://foosoftware.org/libfoo/ ---------------------------- +---- The +bool+ line, +help+ line and other metadata information about the configuration option must be indented with one tab. The help text @@ -64,9 +64,9 @@ put your package in one of the existing categories). The files included there are 'sorted alphabetically' per category and are 'NOT' supposed to contain anything but the 'bare' name of the package. --------------------------- +---- source "package/libfoo/Config.in" --------------------------- +---- ==== +Config.in.host+ file @@ -83,14 +83,14 @@ options here: the configuration menu. In this case, create a +Config.in.host+ file for that host package: + ---------------------------- +---- config BR2_PACKAGE_HOST_FOO bool "host foo" help This is a comment that explains what foo for the host is. http://foosoftware.org/foo/ ---------------------------- +---- + The same coding style and options as for the +Config.in+ file are valid. + @@ -98,9 +98,9 @@ Finally you have to add your new +libfoo/Config.in.host+ to +package/Config.in.host+. The files included there are 'sorted alphabetically' and are 'NOT' supposed to contain anything but the 'bare' name of the package. + --------------------------- +---- source "package/foo/Config.in.host" --------------------------- +---- + The host package will then be available from the +Host utilities+ menu. @@ -136,7 +136,7 @@ is not met. An example illustrates both the usage of +select+ and +depends on+. --------------------------- +---- config BR2_PACKAGE_RRDTOOL bool "rrdtool" depends on BR2_USE_WCHAR @@ -152,7 +152,7 @@ config BR2_PACKAGE_RRDTOOL comment "rrdtool needs a toolchain w/ wchar" depends on !BR2_USE_WCHAR --------------------------- +---- Note that these two dependency types are only transitive with the @@ -160,7 +160,7 @@ dependencies of the same kind. This means, in the following example: --------------------------- +---- config BR2_PACKAGE_A bool "Package A" @@ -179,7 +179,7 @@ config BR2_PACKAGE_D config BR2_PACKAGE_E bool "Package E" select BR2_PACKAGE_D --------------------------- +---- * Selecting +Package C+ will be visible if +Package B+ has been selected, which in turn is only visible if +Package A+ has been @@ -193,7 +193,7 @@ config BR2_PACKAGE_E the dependency of +Package B+ on +Package A+. Therefore, in such a situation, the transitive dependency has to be added explicitly: --------------------------- +---- config BR2_PACKAGE_D bool "Package D" depends on BR2_PACKAGE_A @@ -203,7 +203,7 @@ config BR2_PACKAGE_E bool "Package E" depends on BR2_PACKAGE_A select BR2_PACKAGE_D --------------------------- +---- Overall, for package library dependencies, +select+ should be preferred. @@ -247,21 +247,21 @@ comment and other config options. The general format of a dependency +comment+ for package foo is: --------------------------- +---- foo needs a toolchain w/ featA, featB, featC --------------------------- +---- for example: --------------------------- +---- mpd needs a toolchain w/ C++, threads, wchar --------------------------- +---- or --------------------------- +---- crda needs a toolchain w/ threads --------------------------- +---- Note that this text is kept brief on purpose, so that it will fit on a 80-character terminal. @@ -358,32 +358,32 @@ typically kernel modules or firmware. A comment should be added in the Config.in file to express this dependency, similar to dependencies on toolchain options. The general format is: --------------------------- +---- foo needs a Linux kernel to be built --------------------------- +---- If there is a dependency on both toolchain options and the Linux kernel, use this format: --------------------------- +---- foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built --------------------------- +---- ==== Dependencies on udev /dev management If a package needs udev /dev management, it should depend on symbol +BR2_PACKAGE_HAS_UDEV+, and the following comment should be added: --------------------------- +---- foo needs udev /dev management --------------------------- +---- If there is a dependency on both toolchain options and udev /dev management, use this format: --------------------------- +---- foo needs udev /dev management and a toolchain w/ featA, featB, featC --------------------------- +---- ==== Dependencies on features provided by virtual packages @@ -578,7 +578,7 @@ not start before +S40network+. The scripts are started in alphabetical order, so +S01syslogd+ starts before +S01watchdogd+, and +S02sysctl+ start thereafter. ------------------------------- +---- 01: #!/bin/sh 02: 03: DAEMON="syslogd" @@ -634,7 +634,7 @@ start thereafter. 53: echo "Usage: $0 {start|stop|restart|reload}" 54: exit 1 55: esac ------------------------------- +---- *Note:* programs that support reloading their configuration in some fashion (+SIGHUP+) should provide a +reload()+ function similar to diff --git a/docs/manual/adding-packages-generic.adoc b/docs/manual/adding-packages-generic.adoc index 9d365a10ca..89fc700452 100644 --- a/docs/manual/adding-packages-generic.adoc +++ b/docs/manual/adding-packages-generic.adoc @@ -12,7 +12,7 @@ system is based on hand-written Makefiles or shell scripts. ==== +generic-package+ tutorial ------------------------------- +---- 01: ################################################################################ 02: # 03: # libfoo @@ -56,7 +56,7 @@ system is based on hand-written Makefiles or shell scripts. 41: endef 42: 43: $(eval $(generic-package)) --------------------------------- +---- The Makefile begins on line 7 to 11 with metadata information: the version of the package (+LIBFOO_VERSION+), the name of the @@ -103,9 +103,9 @@ Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'. So its fixup would be: --------------------------------- +---- DIVINE_CONFIG_SCRIPTS = divine-config --------------------------------- +---- ================================ .Config script: 'imagemagick' package: @@ -115,11 +115,11 @@ Package imagemagick installs the following scripts: So it's fixup would be: --------------------------------- +---- IMAGEMAGICK_CONFIG_SCRIPTS = \ Magick-config Magick++-config \ MagickCore-config MagickWand-config Wand-config --------------------------------- +---- ================================ On line 14, we specify the list of dependencies this package relies @@ -166,10 +166,10 @@ for the host. It is possible to call both of them in a single +.mk+ file: once to create the rules to generate a target package and once to create the rules to generate a host package: ----------------------- +---- $(eval $(generic-package)) $(eval $(host-generic-package)) ----------------------- +---- This might be useful if the compilation of the target package requires some tools to be installed on the host. If the package name is @@ -504,12 +504,12 @@ not and can not work as people would expect it should: Buildroot package. A Makefile comment must always precede the addition of a CVE to this variable. Example: + ----------------------- +---- # 0001-fix-cve-2020-12345.patch LIBFOO_IGNORE_CVES += CVE-2020-12345 # only when built with libbaz, which Buildroot doesn't support LIBFOO_IGNORE_CVES += CVE-2020-54321 ----------------------- +---- * [[cpe-id]] +LIBFOO_CPE_ID_*+ variables is a set of variables that allows the package to define its https://nvd.nist.gov/products/cpe[CPE @@ -551,9 +551,9 @@ corresponding target package. The recommended way to define these variables is to use the following syntax: ----------------------- +---- LIBFOO_VERSION = 2.32 ----------------------- +---- Now, the variables that define what should be performed at the different steps of the build process. @@ -633,13 +633,13 @@ different steps of the build process. The preferred way to define these variables is: ----------------------- +---- define LIBFOO_CONFIGURE_CMDS action 1 action 2 action 3 endef ----------------------- +---- In the action definitions, you can use the following variables: diff --git a/docs/manual/adding-packages-golang.adoc b/docs/manual/adding-packages-golang.adoc index 00b8bea285..3ddbe57afe 100644 --- a/docs/manual/adding-packages-golang.adoc +++ b/docs/manual/adding-packages-golang.adoc @@ -13,7 +13,7 @@ build system and use bundled dependencies. First, let's see how to write a +.mk+ file for a go package, with an example : ------------------------- +---- 01: ################################################################################ 02: # 03: # foo @@ -26,7 +26,7 @@ with an example : 10: FOO_LICENSE_FILES = LICENSE 11: 12: $(eval $(golang-package)) ------------------------- +---- On line 7, we declare the version of the package. diff --git a/docs/manual/adding-packages-hooks.adoc b/docs/manual/adding-packages-hooks.adoc index 741b71ca29..7aa7aa232d 100644 --- a/docs/manual/adding-packages-hooks.adoc +++ b/docs/manual/adding-packages-hooks.adoc @@ -52,14 +52,14 @@ 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: ----------------------- +---- define LIBFOO_POST_PATCH_FIXUP action1 action2 endef LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP ----------------------- +---- [[hooks-rsync]] ==== Using the +POST_RSYNC+ hook diff --git a/docs/manual/adding-packages-kconfig.adoc b/docs/manual/adding-packages-kconfig.adoc index f2c40ed7a2..ee52cbd737 100644 --- a/docs/manual/adding-packages-kconfig.adoc +++ b/docs/manual/adding-packages-kconfig.adoc @@ -30,11 +30,11 @@ In order to use the +kconfig-package+ infrastructure for a Buildroot package, the minimally required lines in the +.mk+ file, in addition to the variables required by the +generic-package+ infrastructure, are: ------------------------------- +---- FOO_KCONFIG_FILE = reference-to-source-configuration-file $(eval $(kconfig-package)) ------------------------------- +---- This snippet creates the following make targets: diff --git a/docs/manual/adding-packages-linux-kernel-spec-infra.adoc b/docs/manual/adding-packages-linux-kernel-spec-infra.adoc index b948e208da..3b3daebf55 100644 --- a/docs/manual/adding-packages-linux-kernel-spec-infra.adoc +++ b/docs/manual/adding-packages-linux-kernel-spec-infra.adoc @@ -22,7 +22,7 @@ Let's look at an example of a Linux tool. For a new Linux tool named descriptions related to each kernel tool that will be used and displayed in the configuration tool. It would basically look like: ------------------------------- +---- 01: config BR2_PACKAGE_LINUX_TOOLS_FOO 02: bool "foo" 03: select BR2_PACKAGE_LINUX_TOOLS @@ -30,7 +30,7 @@ displayed in the configuration tool. It would basically look like: 05: This is a comment that explains what foo kernel tool is. 06: 07: http://foosoftware.org/foo/ ------------------------------- +---- The name of the option starts with the prefix +BR2_PACKAGE_LINUX_TOOLS_+, followed by the uppercase name of the tool (like is done for packages). @@ -43,7 +43,7 @@ the `Target packages` main menu. Then for each linux tool, add a new +.mk.in+ file named +package/linux-tools/linux-tool-foo.mk.in+. It would basically look like: ------------------------------- +---- 01: ################################################################################ 02: # 03: # foo @@ -69,7 +69,7 @@ Then for each linux tool, add a new +.mk.in+ file named 23: DESTDIR=$(TARGET_DIR) \ 24: foo_install 25: endef --------------------------------- +---- On line 7, we register the Linux tool +foo+ to the list of available Linux tools. @@ -115,19 +115,19 @@ the existing +linux/Config.ext.in+. This file contains the option descriptions related to each kernel extension that will be used and displayed in the configuration tool. It would basically look like: ------------------------------- +---- 01: config BR2_LINUX_KERNEL_EXT_FOO 02: bool "foo" 03: help 04: This is a comment that explains what foo kernel extension is. 05: 06: http://foosoftware.org/foo/ ------------------------------- +---- Then for each linux extension, add a new +.mk+ file named +linux/linux-ext-foo.mk+. It should basically contain: ------------------------------- +---- 01: ################################################################################ 02: # 03: # foo @@ -139,7 +139,7 @@ Then for each linux extension, add a new +.mk+ file named 09: define FOO_PREPARE_KERNEL 10: $(FOO_DIR)/prepare-kernel-tree.sh --linux-dir=$(@D) 11: endef --------------------------------- +---- On line 7, we add the Linux extension +foo+ to the list of available Linux extensions. diff --git a/docs/manual/adding-packages-luarocks.adoc b/docs/manual/adding-packages-luarocks.adoc index 9ced6c5504..e9d4717568 100644 --- a/docs/manual/adding-packages-luarocks.adoc +++ b/docs/manual/adding-packages-luarocks.adoc @@ -10,7 +10,7 @@ First, let's see how to write a +.mk+ file for a LuaRocks-based package, with an example : ------------------------- +---- 01: ################################################################################ 02: # 03: # lua-foo @@ -27,7 +27,7 @@ with an example : 14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING 15: 16: $(eval $(luarocks-package)) ------------------------- +---- On line 7, we declare the version of the package (the same as in the rockspec, which is the concatenation of the upstream version and the rockspec revision, diff --git a/docs/manual/adding-packages-meson.adoc b/docs/manual/adding-packages-meson.adoc index 8c0f84709f..16135b1297 100644 --- a/docs/manual/adding-packages-meson.adoc +++ b/docs/manual/adding-packages-meson.adoc @@ -14,7 +14,7 @@ build operations. Let's see how to write a +.mk+ file for a Meson-based package, with an example: ------------------------------- +---- 01: ################################################################################ 02: # 03: # foo @@ -38,7 +38,7 @@ Let's see how to write a +.mk+ file for a Meson-based package, with an example: 21: endif 22: 23: $(eval $(meson-package)) --------------------------------- +---- The Makefile starts with the definition of the standard variables for package declaration (lines 7 to 11). diff --git a/docs/manual/adding-packages-perl.adoc b/docs/manual/adding-packages-perl.adoc index 7c60a1a4a7..405931770c 100644 --- a/docs/manual/adding-packages-perl.adoc +++ b/docs/manual/adding-packages-perl.adoc @@ -10,7 +10,7 @@ First, let's see how to write a +.mk+ file for a Perl/CPAN package, with an example : ------------------------- +---- 01: ################################################################################ 02: # 03: # perl-foo-bar @@ -26,7 +26,7 @@ with an example : 13: PERL_FOO_BAR_DISTNAME = Foo-Bar 14: 15: $(eval $(perl-package)) ------------------------- +---- On line 7, we declare the version of the package. diff --git a/docs/manual/adding-packages-python.adoc b/docs/manual/adding-packages-python.adoc index 7cb3635792..f33770f95c 100644 --- a/docs/manual/adding-packages-python.adoc +++ b/docs/manual/adding-packages-python.adoc @@ -15,7 +15,7 @@ system, generally recognizable by the usage of a +setup.py+ script or First, let's see how to write a +.mk+ file for a Python package, with an example : ------------------------- +---- 01: ################################################################################ 02: # 03: # python-foo @@ -32,7 +32,7 @@ with an example : 14: PYTHON_FOO_SETUP_TYPE = setuptools 15: 16: $(eval $(python-package)) ------------------------- +---- On line 7, we declare the version of the package. @@ -170,9 +170,9 @@ your host. When at the root of your buildroot directory just do : ------------------------ +---- utils/scanpypi foo bar -o package ------------------------ +---- This will generate packages +python-foo+ and +python-bar+ in the package folder if they exist on https://pypi.python.org. @@ -190,18 +190,18 @@ need to manually add the package to the +package/Config.in+ file. If your Buildroot package is not in the official Buildroot tree but in a br2-external tree, use the -o flag as follows: ------------------------ +---- utils/scanpypi foo bar -o other_package_dir ------------------------ +---- This will generate packages +python-foo+ and +python-bar+ in the +other_package_directory+ instead of +package+. Option +-h+ will list the available options: ------------------------ +---- utils/scanpypi -h ------------------------ +---- [[python-package-cffi-backend]] @@ -219,17 +219,17 @@ Such a package should: compiled C library wrapper on the target. This is achieved by adding +select BR2_PACKAGE_PYTHON_CFFI+ to the package +Config.in+. ------------------------- +---- config BR2_PACKAGE_PYTHON_FOO bool "python-foo" select BR2_PACKAGE_PYTHON_CFFI # runtime ------------------------- +---- * add +host-python-cffi+ as a build-time dependency in order to cross-compile the C wrapper. This is achieved by adding +host-python-cffi+ to the +PYTHON_FOO_DEPENDENCIES+ variable. ------------------------- +---- ################################################################################ # # python-foo @@ -241,4 +241,4 @@ cross-compile the C wrapper. This is achieved by adding PYTHON_FOO_DEPENDENCIES = host-python-cffi $(eval $(python-package)) ------------------------- +---- diff --git a/docs/manual/adding-packages-qmake.adoc b/docs/manual/adding-packages-qmake.adoc index 0205f6ca29..e09da166b9 100644 --- a/docs/manual/adding-packages-qmake.adoc +++ b/docs/manual/adding-packages-qmake.adoc @@ -10,7 +10,7 @@ First, let's see how to write a +.mk+ file for a QMake-based package, with an example : ------------------------- +---- 01: ################################################################################ 02: # 03: # libfoo @@ -24,7 +24,7 @@ an example : 11: LIBFOO_DEPENDENCIES = bar 12: 13: $(eval $(qmake-package)) ------------------------- +---- On line 7, we declare the version of the package. diff --git a/docs/manual/adding-packages-rebar.adoc b/docs/manual/adding-packages-rebar.adoc index c2a5b0d0e9..d2ed67c474 100644 --- a/docs/manual/adding-packages-rebar.adoc +++ b/docs/manual/adding-packages-rebar.adoc @@ -10,7 +10,7 @@ First, let's see how to write a +.mk+ file for a rebar-based package, with an example : ------------------------------- +---- 01: ################################################################################ 02: # 03: # erlang-foobar @@ -23,7 +23,7 @@ with an example : 10: ERLANG_FOOBAR_DEPENDENCIES = host-libaaa libbbb 11: 12: $(eval $(rebar-package)) --------------------------------- +---- On line 7, we declare the version of the package. diff --git a/docs/manual/adding-packages-tips.adoc b/docs/manual/adding-packages-tips.adoc index d8c2eceb10..b04b42b51f 100644 --- a/docs/manual/adding-packages-tips.adoc +++ b/docs/manual/adding-packages-tips.adoc @@ -172,11 +172,11 @@ However, it is possible to download tarballs directly from the repository on GitHub. As GitHub is known to have changed download mechanisms in the past, the 'github' helper function should be used as shown below. ------------------------- +---- # Use a tag or a full commit ID FOO_VERSION = 1.0 FOO_SITE = $(call github,,,v$(FOO_VERSION)) ------------------------- +---- .Notes - The FOO_VERSION can either be a tag or a commit ID. @@ -220,22 +220,22 @@ to download from Gitlab repositories. It can be used to download auto-generated tarballs produced by Gitlab, either for specific tags or commits: ------------------------- +---- # Use a tag or a full commit ID FOO_VERSION = 1.0 FOO_SITE = $(call gitlab,,,v$(FOO_VERSION)) ------------------------- +---- By default, it will use a +.tar.gz+ tarball, but Gitlab also provides +.tar.bz2+ tarballs, so by adding a +_SOURCE+ variable, this +.tar.bz2+ tarball can be used: ------------------------- +---- # Use a tag or a full commit ID FOO_VERSION = 1.0 FOO_SITE = $(call gitlab,,,v$(FOO_VERSION)) FOO_SOURCE = foo-$(FOO_VERSION).tar.bz2 ------------------------- +---- If there is a specific tarball uploaded by the upstream developers in +https://gitlab.com//releases/+, do not use this macro, but diff --git a/docs/manual/adding-packages-virtual.adoc b/docs/manual/adding-packages-virtual.adoc index 722e6e3771..297e189186 100644 --- a/docs/manual/adding-packages-virtual.adoc +++ b/docs/manual/adding-packages-virtual.adoc @@ -26,14 +26,14 @@ First, let's create the virtual package. 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 @@ -43,7 +43,7 @@ providers. The +.mk+ for the virtual package should just evaluate the +virtual-package+ macro: ---------------------------- +---- 01: ################################################################################ 02: # 03: # something-virtual @@ -51,7 +51,7 @@ The +.mk+ for the virtual package should just evaluate the +virtual-package+ mac 05: ################################################################################ 06: 07: $(eval $(virtual-package)) ---------------------------- +---- The ability to have target and host packages is also available, with the +host-virtual-package+ macro. @@ -64,7 +64,7 @@ modifications. 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 @@ -77,7 +77,7 @@ functionalities of 'something-virtual', should contain: 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 @@ -89,9 +89,9 @@ The +.mk+ file should also declare an additional variable +SOME_PROVIDER_PROVIDES+ to contain the names of all the virtual packages it is an implementation of: ---------------------------- +---- 01: SOME_PROVIDER_PROVIDES = something-virtual ---------------------------- +---- Of course, do not forget to add the proper build and runtime dependencies for this package! @@ -101,14 +101,14 @@ this package! When adding a package that requires a certain +FEATURE+ provided by a virtual package, you have to use +depends on BR2_PACKAGE_HAS_FEATURE+, like so: ---------------------------- +---- config BR2_PACKAGE_HAS_FEATURE bool config BR2_PACKAGE_FOO bool "foo" depends on BR2_PACKAGE_HAS_FEATURE ---------------------------- +---- ==== Notes on depending on a specific provider @@ -118,7 +118,7 @@ provider. Let's take an example with two providers for a +FEATURE+: ---------------------------- +---- config BR2_PACKAGE_HAS_FEATURE bool @@ -129,7 +129,7 @@ config BR2_PACKAGE_FOO config BR2_PACKAGE_BAR bool "bar" select BR2_PACKAGE_HAS_FEATURE ---------------------------- +---- And you are adding a package that needs +FEATURE+ as provided by +foo+, but not as provided by +bar+. diff --git a/docs/manual/adding-packages-waf.adoc b/docs/manual/adding-packages-waf.adoc index 7622c55a7b..5902917214 100644 --- a/docs/manual/adding-packages-waf.adoc +++ b/docs/manual/adding-packages-waf.adoc @@ -10,7 +10,7 @@ First, let's see how to write a +.mk+ file for a Waf-based package, with an example : ------------------------- +---- 01: ################################################################################ 02: # 03: # libfoo @@ -24,7 +24,7 @@ an example : 11: LIBFOO_DEPENDENCIES = bar 12: 13: $(eval $(waf-package)) ------------------------- +---- On line 7, we declare the version of the package. diff --git a/docs/manual/beyond-buildroot.adoc b/docs/manual/beyond-buildroot.adoc index eefea1fecf..871b591a02 100644 --- a/docs/manual/beyond-buildroot.adoc +++ b/docs/manual/beyond-buildroot.adoc @@ -13,9 +13,9 @@ images_ menu. After a complete build, just run the following commands to setup the NFS-root directory: -------------------- +---- sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir -------------------- +---- Remember to add this path to +/etc/exports+. @@ -34,21 +34,21 @@ as a live CD and live USB (through the _Build hybrid image_ option). You can test your live CD image using QEMU: -------------------- +---- qemu-system-i386 -cdrom output/images/rootfs.iso9660 -------------------- +---- Or use it as a hard-drive image if it is a hybrid ISO: -------------------- +---- qemu-system-i386 -hda output/images/rootfs.iso9660 -------------------- +---- It can be easily flashed to a USB drive with +dd+: -------------------- +---- dd if=output/images/rootfs.iso9660 of=/dev/sdb -------------------- +---- === Chroot diff --git a/docs/manual/ccache-support.adoc b/docs/manual/ccache-support.adoc index ab4f10be23..86cb4a150d 100644 --- a/docs/manual/ccache-support.adoc +++ b/docs/manual/ccache-support.adoc @@ -28,13 +28,13 @@ misses, etc.) by running +make ccache-stats+. The make target +ccache-options+ and the +CCACHE_OPTIONS+ variable provide more generic access to the ccache. For example ------------------ +---- # set cache limit size make CCACHE_OPTIONS="--max-size=5G" ccache-options # zero statistics counters make CCACHE_OPTIONS="--zero-stats" ccache-options ------------------ +---- +ccache+ makes a hash of the source files and of the compiler options. If a compiler option is different, the cached object file will not be diff --git a/docs/manual/common-usage.adoc b/docs/manual/common-usage.adoc index e0ab1a9f66..43caa3a9bc 100644 --- a/docs/manual/common-usage.adoc +++ b/docs/manual/common-usage.adoc @@ -13,9 +13,9 @@ If you intend to do an offline build and just want to download all sources that you previously selected in the configurator ('menuconfig', 'nconfig', 'xconfig' or 'gconfig'), then issue: --------------------- +---- $ make source --------------------- +---- You can now disconnect or copy the content of your +dl+ directory to the build-host. @@ -29,15 +29,15 @@ Buildroot also supports building out of tree with a syntax similar to the Linux kernel. To use it, add +O=+ to the make command line: --------------------- +---- $ make O=/tmp/build menuconfig --------------------- +---- Or: --------------------- +---- $ cd /tmp/build; make O=$PWD -C path/to/buildroot menuconfig --------------------- +---- All the output files will be located under +/tmp/build+. If the +O+ path does not exist, Buildroot will create it. @@ -56,9 +56,9 @@ For ease of use, Buildroot generates a Makefile wrapper in the output directory - so after the first run, you no longer need to pass +O=<...>+ and +-C <...>+, simply run (in the output directory): --------------------- +---- $ make --------------------- +---- [[env-vars]] @@ -108,16 +108,16 @@ to +make+ or set in the environment: An example that uses config files located in the toplevel directory and in your $HOME: --------------------- +---- $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config --------------------- +---- If you want to use a compiler other than the default +gcc+ or +g+++ for building helper-binaries on your host, then do --------------------- +---- $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD --------------------- +---- === Dealing efficiently with filesystem images @@ -166,9 +166,9 @@ packages in the current configuration, together with their dependencies, licenses and other metadata. This JSON blurb is produced by using the +show-info+ make target: ------------------------- +---- make show-info ------------------------- +---- Buildroot can also produce details about packages as HTML and JSON output using the +pkg-stats+ make target. Amongst other things, these @@ -176,9 +176,9 @@ details include whether known CVEs (security vulnerabilities) affect the packages in your current configuration. It also shows if there is a newer upstream version for those packages. ------------------------- +---- make pkg-stats ------------------------- +---- === Graphing the dependencies between packages @@ -198,9 +198,9 @@ graphs. To generate a dependency graph of the full system you have compiled, simply run: ------------------------- +---- make graph-depends ------------------------- +---- You will find the generated graph in +output/graphs/graph-depends.pdf+. @@ -209,9 +209,9 @@ If your system is quite large, the dependency graph may be too complex and difficult to read. It is therefore possible to generate the dependency graph just for a given package: ------------------------- +---- make -graph-depends ------------------------- +---- You will find the generated graph in +output/graph/-graph-depends.pdf+. @@ -227,9 +227,9 @@ can switch to other output formats, such as PNG, PostScript or SVG. All formats supported by the +-T+ option of the +dot+ tool are supported. --------------------------------- +---- BR2_GRAPH_OUT=svg make graph-depends --------------------------------- +---- The +graph-depends+ behaviour can be controlled by setting options in the +BR2_GRAPH_DEPS_OPTS+ environment variable. The accepted options are: @@ -253,9 +253,9 @@ The +graph-depends+ behaviour can be controlled by setting options in the root package (+R+), the target packages (+T+) and the host packages (+H+). Defaults to: +lightblue,grey,gainsboro+ --------------------------------- +---- BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colors=red,green,blue' make graph-depends --------------------------------- +---- === Graphing the build duration @@ -269,9 +269,9 @@ step of each package, and allows to generate graphs from this data. To generate the build time graph after a build, run: ----------------- +---- make graph-build ----------------- +---- This will generate a set of files in +output/graphs+ : @@ -299,9 +299,9 @@ By default, the output format for the graph is PDF, but a different format can be selected using the +BR2_GRAPH_OUT+ environment variable. The only other format supported is PNG: ----------------- +---- BR2_GRAPH_OUT=png make graph-build ----------------- +---- [[graph-size]] === Graphing the filesystem size contribution of packages @@ -315,9 +315,9 @@ the different packages. To generate these data after a build, run: ----------------- +---- make graph-size ----------------- +---- This will generate: @@ -366,9 +366,9 @@ Buildroot release, use the +size-stats-compare+ script. It takes two +file-size-stats.csv+ files (produced by +make graph-size+) as input. Refer to the help text of this script for more details: ----------------- +---- utils/size-stats-compare -h ----------------- +---- [[top-level-parallel-build]] === Top-level parallel build diff --git a/docs/manual/configure.adoc b/docs/manual/configure.adoc index 60860d2c71..d27cdf3eb9 100644 --- a/docs/manual/configure.adoc +++ b/docs/manual/configure.adoc @@ -252,9 +252,9 @@ Then, we can trigger the build, and also ask Buildroot to generate a SDK. This will conveniently generate for us a tarball which contains our toolchain: ------ +---- make sdk ------ +---- This produces the SDK tarball in +$(O)/images+, with a name similar to +arm-buildroot-linux-uclibcgnueabi_sdk-buildroot.tar.gz+. Save this diff --git a/docs/manual/contribute.adoc b/docs/manual/contribute.adoc index 6ff6c15314..1801a53d2f 100644 --- a/docs/manual/contribute.adoc +++ b/docs/manual/contribute.adoc @@ -72,9 +72,9 @@ basically two things that can be done: can be removed. In the commit message of a patch fixing an autobuild failure, add a reference to the build result directory, as follows: ---------------------- +---- Fixes: http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069 ---------------------- +---- === Reviewing and testing patches @@ -153,10 +153,10 @@ When browsing patches in the patchwork management interface, an +mbox+ link is provided at the top of the page. Copy this link address and run the following commands: ---------------------- +---- $ git checkout -b $ wget -O - | git am ---------------------- +---- Another option for applying patches is to create a bundle. A bundle is a set of patches that you can group together using the patchwork @@ -306,24 +306,24 @@ Starting from the changes committed in your local git view, _rebase_ your development branch on top of the upstream tree before generating a patch set. To do so, run: ---------------------- +---- $ git fetch --all --tags $ git rebase origin/master ---------------------- +---- Now check the coding style for the changes you committed: ---------------------- +---- $ utils/docker-run make check-package ---------------------- +---- Now, you are ready to generate then submit your patch set. To generate it, run: ---------------------- +---- $ git format-patch -M -n -s -o outgoing origin/master ---------------------- +---- This will generate patch files in the +outgoing+ subdirectory, automatically adding the +Signed-off-by+ line. @@ -336,37 +336,37 @@ sent, called +get-developers+ (see xref:DEVELOPERS[] for more information). This tool reads your patches and outputs the appropriate +git send-email+ command to use: ---------------------- +---- $ ./utils/get-developers outgoing/* ---------------------- +---- Use the output of +get-developers+ to send your patches: ---------------------- +---- $ git send-email --to buildroot@buildroot.org --cc bob --cc alice outgoing/* ---------------------- +---- Alternatively, +get-developers -e+ can be used directly with the +--cc-cmd+ argument to +git send-email+ to automatically CC the affected developers: ---------------------- +---- $ git send-email --to buildroot@buildroot.org \ --cc-cmd './utils/get-developers -e' origin/master ---------------------- +---- +git+ can be configured to automatically do this out of the box with: ---------------------- +---- $ git config sendemail.to buildroot@buildroot.org $ git config sendemail.ccCmd "$(pwd)/utils/get-developers -e" ---------------------- +---- And then just do: ---------------------- +---- $ git send-email origin/master ---------------------- +---- Note that +git+ should be configured to use your mail account. To configure +git+, see +man git-send-email+ or https://git-send-email.io/. @@ -427,10 +427,10 @@ should be based off the maintenance branch, and the patch subject prefix must include the maintenance branch name (for example "[PATCH 2020.02.x]"). This can be done with the +git format-patch+ flag +--subject-prefix+: ---------------------- +---- $ git format-patch --subject-prefix "PATCH 2020.02.x" \ -M -s -o outgoing origin/2020.02.x ---------------------- +---- Then send the patches with +git send-email+, as described above. @@ -458,7 +458,7 @@ be preserved forever in the +git+ history of the project. Hereafter the recommended layout: ---------------- +---- Patch title: short explanation, max 72 chars A paragraph that explains the problem, and how it manifests itself. If @@ -481,7 +481,7 @@ Changes v2 -> v3: Changes v1 -> v2: - alpha bravo (suggested by John) - charly delta ---------------- +---- Any patch revision should include the version number. The version number is simply composed of the letter +v+ followed by an +integer+ greater or @@ -490,17 +490,17 @@ equal to two (i.e. "PATCH v2", "PATCH v3" ...). This can be easily handled with +git format-patch+ by using the option +--subject-prefix+: ---------------------- +---- $ git format-patch --subject-prefix "PATCH v4" \ -M -s -o outgoing origin/master ---------------------- +---- Since git version 1.8.1, you can also use +-v + (where is the version number): ---------------------- +---- $ git format-patch -v4 -M -s -o outgoing origin/master ---------------------- +---- When you provide a new version of a patch, please mark the old one as superseded in @@ -579,7 +579,7 @@ cases can be listed by executing +support/testing/run-tests -l+. These tests can all be run individually during test development from the console. Both one at a time and selectively as a group of a subset of tests. ---------------------- +---- $ support/testing/run-tests -l List of tests test_run (tests.utils.test_check_package.TestCheckPackage) @@ -606,11 +606,11 @@ test_run (tests.init.test_busybox.TestInitSystemBusyboxRwNet) ... ok Ran 157 tests in 0.021s OK ---------------------- +---- * Then, to run one test case: ---------------------- +---- $ support/testing/run-tests -d dl -o output_folder -k tests.init.test_busybox.TestInitSystemBusyboxRw 15:03:26 TestInitSystemBusyboxRw Starting 15:03:28 TestInitSystemBusyboxRw Building @@ -620,7 +620,7 @@ $ support/testing/run-tests -d dl -o output_folder -k tests.init.test_busybox.Te Ran 1 test in 301.140s OK ---------------------- +---- The standard output indicates if the test is successful or not. By default, the output folder for the test is deleted automatically @@ -674,12 +674,12 @@ be the maintainer of that test case. When a test case runs, the +output_folder+ will contain the following: ---------------------- +---- $ ls output_folder/ TestInitSystemBusyboxRw/ TestInitSystemBusyboxRw-build.log TestInitSystemBusyboxRw-run.log ---------------------- +---- +TestInitSystemBusyboxRw/+ is the Buildroot output directory, and it is preserved only if the +-k+ option is passed. @@ -721,28 +721,28 @@ arbitrary string you choose. * To trigger all run-test test case jobs, push a branch that ends with +-runtime-tests+: ---------------------- +---- $ git push gitlab HEAD:-runtime-tests ---------------------- +---- * To trigger one or several test case jobs, push a branch that ends with the complete test case name (+tests.init.test_busybox.TestInitSystemBusyboxRo+) or with the name of a category of tests (+tests.init.test_busybox+): ---------------------- +---- $ git push gitlab HEAD:- ---------------------- +---- Example to run one test: ---------------------- +---- $ git push gitlab HEAD:foo-tests.init.test_busybox.TestInitSystemBusyboxRo ---------------------- +---- Examples to run several tests part of the same group: ---------------------- +---- $ git push gitlab HEAD:foo-tests.init.test_busybox $ git push gitlab HEAD:foo-tests.init ---------------------- +---- diff --git a/docs/manual/customize-directory-structure.adoc b/docs/manual/customize-directory-structure.adoc index 1249421da2..e0eecb5641 100644 --- a/docs/manual/customize-directory-structure.adoc +++ b/docs/manual/customize-directory-structure.adoc @@ -16,7 +16,7 @@ this structure itself: either inside the Buildroot tree, or outside of it using a br2-external tree. Both options are valid, the choice is up to you. ------ +---- +-- board/ | +-- / | +-- / @@ -51,7 +51,7 @@ to you. +-- Config.in (if using a br2-external tree) +-- external.mk (if using a br2-external tree) +-- external.desc (if using a br2-external tree) ------- +---- Details on the files shown above are given further in this chapter. @@ -79,7 +79,7 @@ more than two layers. An example directory structure for where a user has two customization layers 'common' and 'fooboard' is: ------ +---- +-- board/ +-- / +-- common/ @@ -98,14 +98,14 @@ layers 'common' and 'fooboard' is: | +-- ... +-- patches/ +-- ... ------ +---- For example, if the user has the +BR2_GLOBAL_PATCH_DIR+ configuration option set as: ------ +---- BR2_GLOBAL_PATCH_DIR="board//common/patches board//fooboard/patches" ------ +---- then first the patches from the 'common' layer would be applied, followed by the patches from the 'fooboard' layer. diff --git a/docs/manual/customize-outside-br.adoc b/docs/manual/customize-outside-br.adoc index 348f2b089c..5e653f1603 100644 --- a/docs/manual/customize-outside-br.adoc +++ b/docs/manual/customize-outside-br.adoc @@ -40,23 +40,23 @@ xref:br2-external-converting[] for help on doing so. Some examples: ------ +---- buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig ------ +---- From now on, definitions from the +/path/to/foo+ br2-external tree will be used: ------ +---- buildroot/ $ make buildroot/ $ make legal-info ------ +---- We can switch to another br2-external tree at any time: ------ +---- buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig ------ +---- We can also use multiple br2-external trees: @@ -66,9 +66,9 @@ buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/where/we/have/bar menuconfig Or disable the usage of any br2-external tree: ------ +---- buildroot/ $ make BR2_EXTERNAL= xconfig ------ +---- ==== Layout of a br2-external tree @@ -152,16 +152,16 @@ makefile logic. The main usage of this is to store package recipes. The recommended way to do this is to write a +Config.in+ file that looks like: ------- +---- source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in" source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in" ------- +---- Then, have an +external.mk+ file that looks like: ------- +---- include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk)) ------- +---- And then in +$(BR2_EXTERNAL_BAR_42_PATH)/package/package1+ and +$(BR2_EXTERNAL_BAR_42_PATH)/package/package2+ create normal diff --git a/docs/manual/customize-packages.adoc b/docs/manual/customize-packages.adoc index b57280ea10..af2fd13deb 100644 --- a/docs/manual/customize-packages.adoc +++ b/docs/manual/customize-packages.adoc @@ -34,19 +34,19 @@ includes these additional +.mk+ files. Therefore, create a file +package//.mk+ with following contents (assuming you have only one extra directory level below +package//+): ------ +---- include $(sort $(wildcard package//*/*.mk)) ------ +---- For the +Config.in+ files, create a file +package//Config.in+ that includes the +Config.in+ files of all your packages. An exhaustive list has to be provided since wildcards are not supported in the source command of kconfig. For example: ------ +---- source "package//package1/Config.in" source "package//package2/Config.in" ------ +---- Include this new file +package//Config.in+ from +package/Config.in+, preferably in a company-specific menu to make diff --git a/docs/manual/download-location.adoc b/docs/manual/download-location.adoc index d485df94f5..b2c527ad05 100644 --- a/docs/manual/download-location.adoc +++ b/docs/manual/download-location.adoc @@ -18,9 +18,9 @@ shared download location. This can be achieved by pointing the set, then the value of +BR2_DL_DIR+ in the Buildroot configuration is overridden. The following line should be added to +<~/.bashrc>+. ------------------ +---- export BR2_DL_DIR= ------------------ +---- The download location can also be set in the +.config+ file, with the +BR2_DL_DIR+ option. Unlike most options in the .config file, this value diff --git a/docs/manual/faq-troubleshooting.adoc b/docs/manual/faq-troubleshooting.adoc index a61276d4c5..5f132f99f6 100644 --- a/docs/manual/faq-troubleshooting.adoc +++ b/docs/manual/faq-troubleshooting.adoc @@ -10,12 +10,12 @@ If the boot process seems to hang after the following messages (messages not necessarily exactly similar, depending on the list of packages selected): ------------------------- +---- Freeing init memory: 3972K Initializing random number generator... done. Starting network... Starting dropbear sshd: generating rsa key... generating dsa key... OK ------------------------- +---- then it means that your system is running, but didn't start a shell on the serial console. In order to have the system start a shell on your diff --git a/docs/manual/getting.adoc b/docs/manual/getting.adoc index 549938a223..51c97d5793 100644 --- a/docs/manual/getting.adoc +++ b/docs/manual/getting.adoc @@ -18,17 +18,17 @@ get started. If you want to setup an isolated buildroot environment on Linux or Mac Os X, paste this line onto your terminal: --------------------- +---- curl -O https://buildroot.org/downloads/Vagrantfile; vagrant up --------------------- +---- If you are on Windows, paste this into your powershell: --------------------- +---- (new-object System.Net.WebClient).DownloadFile( "https://buildroot.org/downloads/Vagrantfile","Vagrantfile"); vagrant up --------------------- +---- If you want to follow development, you can use the daily snapshots or make a clone of the Git repository. Refer to the diff --git a/docs/manual/legal-notice.adoc b/docs/manual/legal-notice.adoc index 179aa6b179..495c5ffe9c 100644 --- a/docs/manual/legal-notice.adoc +++ b/docs/manual/legal-notice.adoc @@ -24,9 +24,9 @@ To make this easier for you, Buildroot can collect for you some material you will probably need. To produce this material, after you have configured Buildroot with +make menuconfig+, +make xconfig+ or +make gconfig+, run: --------------------- +---- make legal-info --------------------- +---- Buildroot will collect legally-relevant material in your output directory, under the +legal-info/+ subdirectory. diff --git a/docs/manual/make-tips.adoc b/docs/manual/make-tips.adoc index df3b888c25..4ccb460525 100644 --- a/docs/manual/make-tips.adoc +++ b/docs/manual/make-tips.adoc @@ -8,21 +8,21 @@ This is a collection of tips that help you make the most of Buildroot. .Display all commands executed by make: --------------------- +---- $ make V=1 --------------------- +---- .Display the list of boards with a defconfig: --------------------- +---- $ make list-defconfigs --------------------- +---- .Display all available targets: --------------------- +---- $ make help --------------------- +---- Not all targets are always available, some settings in the +.config+ file may hide some targets: @@ -46,19 +46,19 @@ configuration options are changed. To delete all build products (including build directories, host, staging and target trees, the images and the toolchain): --------------------- +---- $ make clean --------------------- +---- .Generating the manual: The present manual sources are located in the 'docs/manual' directory. To generate the manual: ---------------------------------- +---- $ make manual-clean $ make manual ---------------------------------- +---- The manual outputs will be generated in 'output/docs/manual'. @@ -70,9 +70,9 @@ The manual outputs will be generated in 'output/docs/manual'. To delete all build products as well as the configuration: --------------------- +---- $ make distclean --------------------- +---- .Notes If +ccache+ is enabled, running +make clean+ or +distclean+ does diff --git a/docs/manual/package-make-target.adoc b/docs/manual/package-make-target.adoc index 795c7d46de..90a7910e23 100644 --- a/docs/manual/package-make-target.adoc +++ b/docs/manual/package-make-target.adoc @@ -12,9 +12,9 @@ For packages relying on the Buildroot infrastructure, there are numerous special make targets that can be called independently like this: ------------- +---- make - ------------- +---- The package build targets are (in the order they are executed): diff --git a/docs/manual/patch-policy.adoc b/docs/manual/patch-policy.adoc index dc35132ecf..a4bc5f391a 100644 --- a/docs/manual/patch-policy.adoc +++ b/docs/manual/patch-policy.adoc @@ -122,7 +122,7 @@ removed, but do update the rest of the patch comment when appropriate. At the end, the patch should look like: ---------------- +---- configure.ac: add C++ support test Signed-off-by: John Doe @@ -142,7 +142,7 @@ AC_PROG_MAKE_SET + AC_LANG_POP([C++])]) + +AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"]) ---------------- +---- === Additional patch documentation @@ -152,17 +152,17 @@ applicable, via the +Upstream+ trailer. When backporting an upstream patch that has been accepted into mainline, it is preferred that the URL to the commit is referenced: ---------------- +---- Upstream: ---------------- +---- If a new issue is identified in Buildroot and upstream is generally affected by the issue (it's not a Buildroot specific issue), users should submit the patch upstream and provide a link to that submission when possible: ---------------- +---- Upstream: ---------------- +---- Patches that have been submitted but were denied upstream should note that and include comments about why the patch is being used despite the upstream status. @@ -172,9 +172,9 @@ about any changes to the patch that may have been necessary. If a patch does not apply upstream then this should be noted with a comment: ---------------- +---- Upstream: N/A ---------------- +---- Adding this documentation helps streamline the patch review process during package version updates. \ No newline at end of file diff --git a/docs/manual/quickstart.adoc b/docs/manual/quickstart.adoc index 80569e85f4..605031037f 100644 --- a/docs/manual/quickstart.adoc +++ b/docs/manual/quickstart.adoc @@ -15,27 +15,27 @@ http://www.busybox.net/[BusyBox]. From the buildroot directory, run --------------------- +---- $ make menuconfig --------------------- +---- for the original curses-based configurator, or --------------------- +---- $ make nconfig --------------------- +---- for the new curses-based configurator, or --------------------- +---- $ make xconfig --------------------- +---- for the Qt-based configurator, or --------------------- +---- $ make gconfig --------------------- +---- for the GTK-based configurator. @@ -56,9 +56,9 @@ read by the top-level Makefile. To start the build process, simply run: --------------------- +---- $ make --------------------- +---- By default, Buildroot does not support top-level parallel build, so running +make -jN+ is not necessary. There is however experimental diff --git a/docs/manual/rebuilding-packages.adoc b/docs/manual/rebuilding-packages.adoc index 06d3855148..0658a93b30 100644 --- a/docs/manual/rebuilding-packages.adoc +++ b/docs/manual/rebuilding-packages.adoc @@ -86,9 +86,9 @@ necessary, and you will save more and more time. For reference, a full rebuild is achieved by running: ---------------- +---- $ make clean all ---------------- +---- [[rebuild-pkg]] === Understanding how to rebuild packages diff --git a/docs/manual/using-buildroot-debugger.adoc b/docs/manual/using-buildroot-debugger.adoc index 9a8a7dfbaf..c208e86bbd 100644 --- a/docs/manual/using-buildroot-debugger.adoc +++ b/docs/manual/using-buildroot-debugger.adoc @@ -24,9 +24,9 @@ To achieve this: Now, to start debugging a program called +foo+, you should run on the target: ----------------------------- +---- gdbserver :2345 foo ----------------------------- +---- This will cause +gdbserver+ to listen on TCP port 2345 for a connection from the cross gdb. @@ -34,9 +34,9 @@ from the cross gdb. Then, on the host, you should start the cross gdb using the following command line: ----------------------------- +---- /output/host/bin/-gdb -ix /output/staging/usr/share/buildroot/gdbinit foo ----------------------------- +---- Of course, +foo+ must be available in the current directory, built with debugging symbols. Typically you start this command from the @@ -48,6 +48,6 @@ cross gdb where to find the libraries of the target. Finally, to connect to the target from the cross gdb: ----------------------------- +---- (gdb) target remote :2345 ----------------------------- +---- diff --git a/docs/manual/using-buildroot-development.adoc b/docs/manual/using-buildroot-development.adoc index da6dd822fb..72628e0a6f 100644 --- a/docs/manual/using-buildroot-development.adoc +++ b/docs/manual/using-buildroot-development.adoc @@ -47,17 +47,17 @@ option. In this _override_ file, Buildroot expects to find lines of the form: ------------------- +---- _OVERRIDE_SRCDIR = /path/to/pkg1/sources _OVERRIDE_SRCDIR = /path/to/pkg2/sources ------------------- +---- For example: ------------------- +---- LINUX_OVERRIDE_SRCDIR = /home/bob/linux/ BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/ ------------------- +---- When Buildroot finds that for a given package, an +_OVERRIDE_SRCDIR+ has been defined, it will no longer attempt to @@ -79,17 +79,17 @@ process of just this package. In the example of the +linux+ package above, the developer can then make a source code change in +/home/bob/linux+ and then run: ------------------------ +---- make linux-rebuild all ------------------------ +---- and in a matter of seconds gets the updated Linux kernel image in +output/images+. Similarly, a change can be made to the BusyBox source code in +/home/bob/busybox+, and after: ------------------------ +---- make busybox-rebuild all ------------------------ +---- the root filesystem image in +output/images+ contains the updated BusyBox. @@ -102,13 +102,13 @@ from the source tree. For example, when working on the +webkitgtk+ package, the following will exclude the tests and in-tree builds from a local WebKit source tree: ------------------- +---- WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \ --exclude JSTests --exclude ManualTests --exclude PerformanceTests \ --exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \ --exclude WebKit.xcworkspace --exclude Websites --exclude Examples ------------------- +---- By default, Buildroot skips syncing of VCS artifacts (e.g., the *.git* and *.svn* directories). Some packages prefer to have these VCS directories @@ -116,6 +116,6 @@ available during build, for example for automatically determining a precise commit reference for version information. To undo this built-in filtering at a cost of a slower speed, add these directories back: ------------------- +---- LINUX_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = --include .git ------------------- +---- diff --git a/docs/manual/writing-rules.adoc b/docs/manual/writing-rules.adoc index 13b7fd5bea..03e4f2c61c 100644 --- a/docs/manual/writing-rules.adoc +++ b/docs/manual/writing-rules.adoc @@ -23,7 +23,7 @@ Buildroot. An entry has the following pattern: ---------------------- +---- config BR2_PACKAGE_LIBFOO bool "libfoo" depends on BR2_PACKAGE_LIBBAZ @@ -33,7 +33,7 @@ config BR2_PACKAGE_LIBFOO should be wrapped. http://foosoftware.org/libfoo/ ---------------------- +---- * The +bool+, +depends on+, +select+ and +help+ lines are indented with one tab. @@ -57,31 +57,31 @@ http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[]. preferably in lowercase, enclosed between separators made of 80 hashes. A blank line is mandatory after the header: + ---------------------- +---- ################################################################################ # # libfoo # ################################################################################ ---------------------- +---- + * Assignment: use +=+ preceded and followed by one space: + ---------------------- +---- LIBFOO_VERSION = 1.0 LIBFOO_CONF_OPTS += --without-python-support ---------------------- +---- + Do not align the +=+ signs. * Indentation: use tab only: + ---------------------- +---- define LIBFOO_REMOVE_DOC $(RM) -r $(TARGET_DIR)/usr/share/libfoo/doc \ $(TARGET_DIR)/usr/share/man/man3/libfoo* endef ---------------------- +---- + Note that commands inside a +define+ block should always start with a tab, so _make_ recognizes them as commands. @@ -92,21 +92,21 @@ so _make_ recognizes them as commands. + YES: + ---------------------- +---- ifeq ($(BR2_PACKAGE_PYTHON3),y) LIBFOO_CONF_OPTS += --with-python-support LIBFOO_DEPENDENCIES += python3 else LIBFOO_CONF_OPTS += --without-python-support endif ---------------------- +---- + NO: + ---------------------- +---- LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON3),,out)-python-support LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON3),python3,) ---------------------- +---- ** Keep configure options and dependencies close together. @@ -115,18 +115,18 @@ LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON3),python3,) + YES: + ---------------------- +---- ifneq ($(BR2_LIBFOO_INSTALL_DATA),y) define LIBFOO_REMOVE_DATA $(RM) -r $(TARGET_DIR)/usr/share/libfoo/data endef LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA endif ---------------------- +---- + NO: + ---------------------- +---- define LIBFOO_REMOVE_DATA $(RM) -r $(TARGET_DIR)/usr/share/libfoo/data endef @@ -134,7 +134,7 @@ endef ifneq ($(BR2_LIBFOO_INSTALL_DATA),y) LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA endif ---------------------- +---- [[writing-genimage-cfg]] @@ -145,7 +145,7 @@ uses to create final .img file. An example follows: ---------------------- +---- image efi-part.vfat { vfat { file EFI { @@ -174,7 +174,7 @@ image sdimage.img { size = 512M } } ---------------------- +---- * Every +section+(i.e. hdimage, vfat etc.), +partition+ must be indented with one tab.