1 files changed, 110 insertions, 5 deletions
diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
index 127060dc35..a16b887fb6 100644
--- a/docs/manual/common-usage.txt
+++ b/docs/manual/common-usage.txt
@@ -40,7 +40,13 @@ Or:
  $ cd /tmp/build; make O=$PWD -C path/to/buildroot
 --------------------
 
-All the output files will be located under +/tmp/build+.
+All the output files will be located under +/tmp/build+. If the +O+
+path does not exist, Buildroot will create it.
+
+*Note:* the +O+ path can be either an absolute or a relative path, but if it's
+passed as a relative path, it is important to note that it is interpreted
+relative to the main Buildroot source directory, *not* the current working
+directory.
 
 When using out-of-tree builds, the Buildroot +.config+ and temporary
 files are also stored in the output directory. This means that you can
@@ -48,8 +54,8 @@ safely run multiple builds in parallel using the same source tree as
 long as they use unique output directories.
 
 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):
+directory - so after the first run, you no longer need to pass +O=<...>+
+and +-C <...>+, simply run (in the output directory):
 
 --------------------
  $ make <target>
@@ -86,9 +92,9 @@ to +make+ or set in the environment:
   Note that the Buildroot download directory can also be set from the
   configuration interface, so through the Buildroot +.config+ file; this
   is the recommended way of setting it.
-* +GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in
+* +BR2_GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in
   build-time graphs
-* +GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the
+* +BR2_GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the
   default), or +png+.
 
 An example that uses config files located in the toplevel directory and
@@ -143,3 +149,102 @@ of an ext2 filesystem may be corrupted; or, if you have sparse files in
 your filesystem, those parts may not be all-zeroes when read back). You
 should only use sparse files when handling files on the build machine, not
 when transferring them to an actual device that will be used on the target.
+
+Graphing the dependencies between packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[graph-depends]]
+
+One of Buildroot's jobs is to know the dependencies between packages,
+and make sure they are built in the right order. These dependencies
+can sometimes be quite complicated, and for a given system, it is
+often not easy to understand why such or such package was brought into
+the build by Buildroot.
+
+In order to help understanding the dependencies, and therefore better
+understand what is the role of the different components in your
+embedded Linux system, Buildroot is capable of generating dependency
+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+.
+
+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 <pkg>-graph-depends
+------------------------
+
+You will find the generated graph in
++output/graph/<pkg>-graph-depends.pdf+.
+
+Note that the dependency graphs are generated using the +dot+ tool
+from the _Graphviz_ project, which you must have installed on your
+system to use this feature. In most distributions, it is available as
+the +graphviz+ package.
+
+By default, the dependency graphs are generated in the PDF
+format. However, by passing the +BR2_GRAPH_OUT+ environment variable, you
+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
+--------------------------------
+
+Graphing the build duration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[graph-duration]]
+
+When the build of a system takes a long time, it is sometimes useful
+to be able to understand which packages are the longest to build, to
+see if anything can be done to speed up the build. In order to help
+such build time analysis, Buildroot collects the build time of each
+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+ :
+
+* +build.hist-build.pdf+, a histogram of the build time for each
+  package, ordered in the build order.
+
+* +build.hist-duration.pdf+, a histogram of the build time for each
+  package, ordered by duration (longest first)
+
+* +build.hist-name.pdf+, a histogram of the build time for each
+  package, order by package name.
+
+* +build.pie-packages.pdf+, a pie chart of the build time per package
+
+* +build.pie-steps.pdf+, a pie chart of the global time spent in each
+  step of the packages build process.
+
+This +graph-build+ target requires the Python Matplotlib and Numpy
+libraries to be installed (+python-matplotlib+ and +python-numpy+ on
+most distributions), and also the +argparse+ module if you're using a
+Python version older than 2.7 (+python-argparse+ on most
+distributions).
+
+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
+----------------