[FE training-materials-updates] buildroot-analysis: new lab

[Thomas Petazzoni]

Repository : git://git.free-electrons.com/training-materials.git

On branch  : master
Link       : http://git.free-electrons.com/training-materials/commit/?id=9d8bbc5f4dd306a4153117c8ecbee94cb5bbba51

>---------------------------------------------------------------

commit 9d8bbc5f4dd306a4153117c8ecbee94cb5bbba51
Author: Thomas Petazzoni <thomas.petazzoni at free-electrons.com>
Date:   Tue Apr 28 10:22:54 2015 +0200

    buildroot-analysis: new lab
    
    Signed-off-by: Thomas Petazzoni <thomas.petazzoni at free-electrons.com>


>---------------------------------------------------------------

9d8bbc5f4dd306a4153117c8ecbee94cb5bbba51
 .../buildroot-advanced-packages.tex                |   9 ++
 labs/buildroot-analysis/buildroot-analysis.tex     | 161 ++++++++++++++++++++-
 2 files changed, 168 insertions(+), 2 deletions(-)

diff --git a/labs/buildroot-advanced-packages/buildroot-advanced-packages.tex b/labs/buildroot-advanced-packages/buildroot-advanced-packages.tex
index 77bf591..7602059 100644
--- a/labs/buildroot-advanced-packages/buildroot-advanced-packages.tex
+++ b/labs/buildroot-advanced-packages/buildroot-advanced-packages.tex
@@ -207,3 +207,12 @@ And run \code{bar} again, and see what difference it makes.
 
 Congratulations, you've finished package the most useless application
 in the world!
+
+\section{Preparing for the next lab}
+
+In preparation for the next lab, we need to do a clean full rebuild,
+so simply issue:
+
+\begin{verbatim}
+make clean all 2>&1 | tee build.log
+\end{verbatim}
diff --git a/labs/buildroot-analysis/buildroot-analysis.tex b/labs/buildroot-analysis/buildroot-analysis.tex
index 1e16f39..c579394 100644
--- a/labs/buildroot-analysis/buildroot-analysis.tex
+++ b/labs/buildroot-analysis/buildroot-analysis.tex
@@ -1,4 +1,161 @@
 \subchapter
-{Use licensing, dependency and build time graphing features}
-{Objectives:}
+{Use build time and dependency graphing, licensing report features}
+{Objectives:
+  \begin{itemize}
+  \item Use build time graphing capabilities
+  \item Use dependency graphing capabilities
+  \item Use licensing report generation, and add licensing
+    informations to your own packages
+  \end{itemize}
+}
+
+\section{Build time graphing}
+
+When your embedded Linux system grows, its build time will also grow,
+so it is often interesting to understand where the build time is
+spent.
+
+Since we have just do a fresh clean rebuild at the end of the previous
+lab, we can analyze the build time. The raw data has been generated by
+Buildroot in \code{output/build/build-time.log}, which contains for
+each step of each package the start time and end time (in seconds
+since Epoch).
+
+Now, let's get a better visualization of this raw data:
+
+\begin{verbatim}
+make graph-build
+\end{verbatim}
+
+Note: you may need to install \code{python-matplotlib} on your machine.
+
+The graphs are generated in \code{output/graphs}:
+
+\begin{itemize}
+\item \code{build.hist-build.pdf}, build time of each package, by
+  build order
+\item \code{build.hist-duration.pdf}, build time of each package, by
+  build duration
+\item \code{build.hist-name.pdf}, build time of each package, by
+  package name
+\item \code{build.pie-packages.pdf}, build time of each package, in
+  proportion of the total build time
+\item \code{build.pie-steps.pdf}, build time of each step
+\end{itemize}
+
+Explore those graphs, see which packages and steps are taking the
+biggest amount of time.
+
+Note that when you don't do a clean rebuild, the \code{build-time.log}
+file gets appended and appended with all the successful builds, making
+the resulting graphs unexploitable. So remember to always do a clean
+full rebuild before looking at the build time graphs.
+
+\section{Dependency graphing}
+
+Another useful tool to analyze the build is graphing dependencies
+between packages. The dependency graph is generated for your current
+configuration: depending on the Buildroot configuration, a given
+package may have different dependencies.
+
+To generate the full dependency graph, do:
+
+\begin{verbatim}
+make graph-depends
+\end{verbatim}
+
+The graph is also generated in \code{output/graphs}, under the name
+\code{graph-depends.pdf}. On the graph, identify the \code{bar} and
+\code{ninvaders} packages you have created, and look at their
+dependencies to see if they match your expectations.
+
+Now, let's draw a graph for a much bigger system. To do this, create a
+completely separate Buildroot output directory:
+
+\begin{verbatim}
+mkdir $HOME/felabs/buildroot-output-test-graph/
+cd $HOME/felabs/buildroot-output-test-graph/
+\end{verbatim}
+
+We're going to create a Buildroot configuration, so create a file
+named \code{.config} and put the following contents:
+
+\begin{verbatim}
+BR2_TOOLCHAIN_BUILDROOT_LARGEFILE=y
+BR2_TOOLCHAIN_BUILDROOT_INET_IPV6=y
+BR2_TOOLCHAIN_BUILDROOT_INET_RPC=y
+BR2_TOOLCHAIN_BUILDROOT_WCHAR=y
+BR2_TOOLCHAIN_BUILDROOT_CXX=y
+BR2_PACKAGE_XORG7=y
+BR2_PACKAGE_XSERVER_XORG_SERVER=y
+BR2_PACKAGE_LIBGTK2=y
+BR2_PACKAGE_WEBKIT=y
+\end{verbatim}
+
+It represents a configuration that builds an internal toolchain, with
+a X.org graphic server, the Gtk2 library, and the Webkit Web rendering
+engine. We're not going to build this configuration, as it would take
+quite a bit of time, but we will generate the dependency graph for it.
+
+First, let's run \code{make menuconfig} to expand this minimal
+configuration into a full configuration:
+
+\begin{verbatim}
+make -C $HOME/felabs/buildroot/ O=$(pwd) menuconfig
+\end{verbatim}
+
+Feel free to explore the configuration at this stage. Now, let's
+generate the dependency graph:
+
+\begin{verbatim}
+make graph-depends
+\end{verbatim}
+
+Look at \code{graphs/graph-depends.pdf} and how complex it is. Now,
+let's look at the dependencies of one specific package, let's say
+\code{libgtk2}:
+
+\begin{verbatim}
+make libgtk2-graph-depends
+\end{verbatim}
+
+Now, open the graph generated at
+\code{graphs/libgtk2-graph-depends.pdf}. As you can see, it is a lot
+more readable.
+
+Such dependencies graphs are very useful to understand why a package
+is being built, and help identifying what you could do to reduce the
+number of packages part of the build.
+
+\section{Licensing report}
+
+Go back to our original build directory, in
+\code{$HOME/felabs/buildroot/}.
+
+As explained during the lectures, Buildroot has a built-in mechanism
+to generate a licensing report, describing all the components part of
+the generated embedded Linux system, and their corresponding licenses.
+
+Let's generate this report for our system:
+
+\begin{verbatim}
+make legal-info
+\end{verbatim}
+
+In the output, you can see some interesting messages:
+
+\begin{verbatim}
+WARNING: bar: cannot save license (BAR_LICENSE_FILES not defined)
+WARNING: libfoo: cannot save license (LIBFOO_LICENSE_FILES not defined)
+WARNING: ninvaders: cannot save license (NINVADERS_LICENSE_FILES not defined)
+\end{verbatim}
+
+So, now update your \code{ninvaders}, \code{libfoo} and \code{bar}
+packages to include the license informations. Run again \code{make
+  legal-info}.
+
+Now, explore \code{output/legal-info}, look at the \code{.csv} files,
+the \code{.txt} files, and the various directories. Buildroot has
+gathered for you most of what is needed to help with licensing
+compliance.