Merge from bittboy/buildroot@26c91a9

docs/manual/common-usage.txt

@@ -88,7 +88,7 @@ to +make+ or set in the environment:
   Buildroot stores the cached files when using ccache.
   +
 * +BR2_DL_DIR+ to override the directory in which
-  Buildroot stores/retrieves downloaded files
+  Buildroot stores/retrieves downloaded files.
   +
   Note that the Buildroot download directory can also be set from the
   configuration interface, so through the Buildroot +.config+ file. See
@@ -102,6 +102,8 @@ to +make+ or set in the environment:
   xref:graph-depends[] for the accepted options
 * +BR2_GRAPH_DOT_OPTS+ is passed verbatim as options to the +dot+ utility to
   draw the dependency graph.
+* +BR2_GRAPH_SIZE_OPTS+ to pass extra options to the size graph; see
+  xref:graph-size[] for the acepted options
 
 An example that uses config files located in the toplevel directory and
 in your $HOME:
@@ -278,6 +280,7 @@ only other format supported is PNG:
 BR2_GRAPH_OUT=png make graph-build
 ----------------
 
+[[graph-size]]
 === Graphing the filesystem size contribution of packages
 
 When your target system grows, it is sometimes useful to understand
@@ -314,6 +317,21 @@ Just like for the duration graph, a +BR2_GRAPH_OUT+ environment variable
 is supported to adjust the output file format. See xref:graph-depends[]
 for details about this environment variable.
 
+Additionally, one may set the environment variable +BR2_GRAPH_SIZE_OPTS+
+to further control the generated graph. Accepted options are:
+
+* `--size-limit X`, `-l X`, will group all packages which individual
+  contribution is below `X` percent, to a single entry labelled _Others_
+  in the graph. By default, `X=0.01`, which means packages each
+  contributing less than 1% are grouped under _Others_. Accepted values
+  are in the range `[0.0..1.0]`.
+
+* `--iec`, `--binary`, `--si`, `--decimal`, to use IEC (binary, powers
+  of 1024) or SI (decimal, powers of 1000; the default) prefixes.
+
+* `--biggest-first`, to sort packages in decreasing size order, rather
+  than in increasing size order.
+
 .Note
 The collected filesystem size data is only meaningful after a complete
 clean rebuild. Be sure to run +make clean all+ before using +make
@@ -329,6 +347,53 @@ Refer to the help text of this script for more details:
 utils/size-stats-compare -h
 ----------------
 
+[[top-level-parallel-build]]
+=== Top-level parallel build
+
+.Note
+This section deals with a very experimental feature, which is known to
+break even in some non-unusual situations. Use at your own risk.
+
+Buildroot has always been capable of using parallel build on a per
+package basis: each package is built by Buildroot using +make -jN+ (or
+the equivalent invocation for non-make-based build systems). The level
+of parallelism is by default number of CPUs + 1, but it can be
+adjusted using the +BR2_JLEVEL+ configuration option.
+
+Until 2020.02, Buildroot was however building packages in a serial
+fashion: each package was built one after the other, without
+parallelization of the build between packages. As of 2020.02,
+Buildroot has experimental support for *top-level parallel build*,
+which allows some signicant build time savings by building packages
+that have no dependency relationship in parallel. This feature is
+however marked as experimental and is known not to work in some cases.
+
+In order to use top-level parallel build, one must:
+
+. Enable the option +BR2_PER_PACKAGE_DIRECTORIES+ in the Buildroot
+configuration
+
+. Use +make -jN+ when starting the Buildroot build
+
+Internally, the +BR2_PER_PACKAGE_DIRECTORIES+ will enable a mechanism
+called *per-package directories*, which will have the following
+effects:
+
+* Instead of a global _target_ directory and a global _host_ directory
+  common to all packages, per-package _target_ and _host_ directories
+  will be used, in +$(O)/per-package/<pkg>/target/+ and
+  +$(O)/per-package/<pkg>/host/+ respectively. Those folders will be
+  populated from the corresponding folders of the package dependencies
+  at the beginning of +<pkg>+ build. The compiler and all other tools
+  will therefore only be able to see and access files installed by
+  dependencies explicitly listed by +<pkg>+.
+
+* At the end of the build, the global _target_ and _host_ directories
+  will be populated, located in +$(O)/target+ and +$(O)/host+
+  respectively. This means that during the build, those folders will
+  be empty and it's only at the very end of the build that they will
+  be populated.
+
 include::eclipse-integration.txt[]
 
 include::advanced.txt[]