[FE training-materials-updates] Thirdparty lab improvements

[Michael Opdenacker]

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

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

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

commit f3cf8c98796b6e6368c1b437482f01e612a8b8fb
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Thu Dec 4 09:17:03 2014 +0100

    Thirdparty lab improvements
    
    - Not finished yet
    
    Signed-off-by: Michael Opdenacker <michael.opdenacker at free-electrons.com>


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

f3cf8c98796b6e6368c1b437482f01e612a8b8fb
 labs/sysdev-thirdparty/sysdev-thirdparty.tex | 144 ++++++++++++---------------
 1 file changed, 66 insertions(+), 78 deletions(-)

diff --git a/labs/sysdev-thirdparty/sysdev-thirdparty.tex b/labs/sysdev-thirdparty/sysdev-thirdparty.tex
index ff0a323..902e0fb 100644
--- a/labs/sysdev-thirdparty/sysdev-thirdparty.tex
+++ b/labs/sysdev-thirdparty/sysdev-thirdparty.tex
@@ -10,7 +10,7 @@ playback application using these libraries.
 We'll see that manually re-using existing libraries is quite tedious,
 so that more automated procedures are necessary to make it
 easier. However, learning how to perform these operations manually
-will significantly help you when you'll face issues with more
+will significantly help you when you face issues with more
 automated tools.
 
 \section{Audio support in the Kernel}
@@ -19,24 +19,26 @@ Recompile your kernel with audio support. The options we want are:
 \code{CONFIG_SOUND}, \code{CONFIG_SND}, \code{CONFIG_SND_USB} and
 \code{CONFIG_SND_USB_AUDIO}.
 
-Boot your board with this new kernel.
+Update your kernel in NAND flash and make sure that your board
+still boots with this new kernel.
 
 \section{Figuring out library dependencies}
 
-We're going to integrate the \code{alsa-utils} and \code{ogg123}. As
-most software components, they in turn depend on other libraries, and
-these dependencies are different depending on the configuration chosen
-for them. In our case, the dependency chain for the \code{alsa-utils}
-is quite simple, it only depends on the \code{alsa-lib} library.
+We're going to integrate the \code{alsa-utils} and \code{ogg123}
+executables. As most software components, they in turn depend
+on other libraries, and these dependencies are different depending
+on the configuration chosen for them. In our case, the dependency
+chain for \code{alsa-utils} is quite simple, it only depends on
+the \code{alsa-lib} library.
 
 The dependencies are a bit more complex for \code{ogg123}. It is part
-of the \code{vorbis-tools}, that depend on \code{libao} and
-\code{libvorbis}. \code{libao} in turn depend on \code{alsa-lib}, and
+of \code{vorbis-tools}, that depend on \code{libao} and
+\code{libvorbis}. \code{libao} in turn depends on \code{alsa-lib}, and
 \code{libvorbis} on \code{libogg}.
 
-\code{libao}, the \code{alsa-utils} and the \code{alsa-lib} are here
+\code{libao}, \code{alsa-utils} and \code{alsa-lib} are here
 to abstract the use of \code{ALSA}, one of the Audio Subsystems
-supported in Linux. The \code{vorbis-tools}, \code{libvorbis} and
+supported in Linux. \code{vorbis-tools}, \code{libvorbis} and
 \code{libogg} are used to handle the audio files encoded using the Ogg
 codec, which is quite common.
 
@@ -55,16 +57,16 @@ several ways, that can be combined:
 \begin{itemize}
 \item Read the library documentation, which often mentions the
   dependencies;
-\item Read the help message of the configure script (by running
+\item Read the help message of the \code{configure script} (by running
   \code{./configure --help}).
-\item By running the configure script, compiling and looking at the
-  errors.
+\item By running the \code{configure} script, compiling and looking
+  at the errors.
 \end{itemize}
 
 To configure, compile and install all the components of our system,
 we're going to start from the bottom of the tree with {\em alsa-lib},
-then continue with the {\em alsa-utils}, \emph{libao}, {\em libogg},
-and \emph{libvorbis}, to finally compile the \emph{vorbis-tools}.
+then continue with {\em alsa-utils}, \emph{libao}, {\em libogg},
+and \emph{libvorbis}, to finally compile \emph{vorbis-tools}.
 
 \section{Preparation}
 
@@ -75,7 +77,7 @@ For our cross-compilation work, we will need two separate spaces:
   documentation and other files needed for the compilation. This
   \emph{staging} space can be quite big, but will not be used on our
   target, only for compiling libraries or applications;
-\item A \emph{target} space, in which we will copy only the required
+\item A \emph{target} space, in which we will only copy the required
   files from the \emph{staging} space: binaries and libraries, after
   stripping, configuration files needed at runtime, etc. This target
   space will take a lot less space than the \emph{staging} space, and
@@ -96,20 +98,16 @@ initialization scripts. We will re-use the system built in the {\em A
 directory:
 
 \begin{verbatim}
-sudo cp -a $HOME/embedded-linux-labs/tinysystem/nfsroot/* target/
+cp -a $HOME/embedded-linux-labs/tinysystem/nfsroot/* target/
 \end{verbatim}
 
-The copy must be done as \code{root}, because the root filesystem of
-the {\em A tiny embedded system} lab contains a few device nodes.
-
 \section{Testing}
 
 Make sure the \code{target/} directory is exported by your NFS server
 to your board by modifying \code{/etc/exports} and restarting your NFS
 server.
 
-Make sure your board boots as it used to and that you can get a
-prompt.
+Make your board boot from this new directory through NFS.
 
 \section{alsa-lib}
 
@@ -118,12 +116,12 @@ the ALSA subsystem. It is available at
 \url{http://alsa-project.org}. Download version 1.0.28, and extract it
 in \code{$HOME/embedded-linux-labs/thirdparty/}.
 
-By looking at the \code{configure} script, we see that this configure
-script has been generated by \code{autoconf} (the header contain a
+By looking at the \code{configure} script, we see that it has
+been generated by \code{autoconf} (the header contains a
 sentence like {\em Generated by GNU Autoconf 2.62}). Most of the time,
 \code{autoconf} comes with \code{automake}, that generates Makefiles
-from Makefile.am files. So the alsa-lib uses a rather common build
-system. Let's try to configure and build alsa-lib:
+from \code{Makefile.am} files. So alsa-lib uses a rather common build
+system. Let's try to configure and build it:
 
 \begin{verbatim}
 ./configure
@@ -141,7 +139,7 @@ CC=arm-linux-gcc ./configure
 \end{verbatim}
 
 Of course, the \code{arm-linux-gcc} cross-compiler must be in your
-PATH prior to running the configure script. The CC environment
+\code{PATH} prior to running the configure script. The \code{CC} environment
 variable is the classical name for specifying the compiler to
 use.
 
@@ -156,22 +154,22 @@ See `config.log' for more details
 \end{verbatim}
 \normalsize
 
-If you look at the \code{config.log} file, you can see that the configure
-script compiles a binary with the cross-compiler and then tries to run
-it on the development workstation. This is a rather usual thing to do
-for a configure script, and that's why it tests so early that it's
-actually doable, and bails out if not.
+If you look at the \code{config.log} file, you can see that the
+\code{configure} script compiles a binary with the cross-compiler
+and then tries to run it on the development workstation. This is a
+rather usual thing to do for a \code{configure} script, and that's
+why it tests so early that it's actually doable, and bails out if not.
 
 Obviously, it cannot work in our case, and the scripts exits. The job
-of the configure script is to test the configuration of the system. To
+of the \code{configure} script is to test the configuration of the system. To
 do so, it tries to compile and run a few sample applications to test
 if this library is available, if this compiler option is supported,
 etc. But in our case, running the test examples is definitely not
 possible.
 
-We need to tell the configure script that we are cross-compiling, and
+We need to tell the \code{configure} script that we are cross-compiling, and
 this can be done using the \code{--build} and \code{--host} options,
-as described in the help of the configure script:
+as described in the help of the \code{configure} script:
 
 \begin{verbatim}
 System types:
@@ -195,15 +193,15 @@ So, let's override the value of the \code{--host} option:
 CC=arm-linux-gcc ./configure --host=arm-linux
 \end{verbatim}
 
-The configure script should end properly now, and create a
+The \code{configure} script should end properly now, and create a
 Makefile. Run the \code{make} command, and you should see that at some
-point it is failing because of a missing python header.
+point it is failing because of a missing Python header.
 
-You can get rid of this error by disabling the python support in the
-configure script by using the \code{--disable-python} option. Start
+You can get rid of this error by disabling Python support in the
+\code{configure} script by using the \code{--disable-python} option. Start
 make again, and this time you should have the compilation ending fine.
 
-Look at the result of compiling in src/.libs: a set of object files
+Look at the result of compiling in \code{src/.libs}: a set of object files
 and a set of \code{libasound.so*} files.
 
 The \code{libasound.so*} files are a dynamic version of the
@@ -217,7 +215,7 @@ arm-linux-gcc -shared conf.o confmisc.o input.o output.o \
               -Wl,-soname -Wl,libasound.so.2 -o libasound.so.2.0.0
 \end{verbatim}
 
-And creates the symbolic link \code{libasound.so} and
+And creates the symbolic links \code{libasound.so} and
 \code{libasound.so.2}.
 
 \begin{verbatim}
@@ -260,7 +258,7 @@ libasound 2.0.0, and fixed in the next alsa-lib release, which will
 now provide libasound 2.0.1.
 
 You can just recompile the library, install it on your target system,
-change the link \code{libasound.so.2} so that it points to
+change the \code{libasound.so.2} link so that it points to
 \code{libasound.so.2.0.1} and restart your applications. And it will
 work, because your applications don't look specifically for
 \code{libasound.so.2.0.0} but for the {\em SONAME}
@@ -270,13 +268,13 @@ However, it also means that as a library developer, if you break the
 ABI of the library, you must change the {\em SONAME}: change from
 \code{libasound.so.2} to \code{libasound.so.3}.
 
-Finally, the last step is to tell the configure script where the
-library is going to be installed. Most configure scripts consider that
+Finally, the last step is to tell the \code{configure} script where the
+library is going to be installed. Most \code{configure} scripts consider that
 the installation prefix is \code{/usr/local/} (so that the library is
 installed in \code{/usr/local/lib}, the headers in
 \code{/usr/local/include}, etc.). But in our system, we simply want
 the libraries to be installed in the \code{/usr} prefix, so let's tell
-the configure script about this:
+the \code{configure} script about this:
 
 \begin{verbatim}
 CC=arm-linux-gcc ./configure --host=arm-linux --disable-python --prefix=/usr
@@ -320,7 +318,7 @@ Now look at what has been installed by alsa-lib:
 \begin{itemize}
 \item Some configuration files in \code{/usr/share/alsa}
 \item The headers in \code{/usr/include}
-\item The shared library and its libtool file in \code{/usr/lib}
+\item The shared library and its libtool (\code{.la}) file in \code{/usr/lib}
 \item A pkgconfig file in \code{/usr/lib/pkgconfig}. We'll come back
   to these later
 \end{itemize}
@@ -352,7 +350,7 @@ with version 1.0.28.
 
 Once uncompressed, we quickly discover that the alsa-utils build
 system is based on the {\em autotools}, so we will work once again
-with a regular configure script.
+with a regular \code{configure} script.
 
 As we've seen previously, we will have to provide the prefix and host
 options and the CC variable:
@@ -361,16 +359,16 @@ options and the CC variable:
 CC=arm-linux-gcc ./configure --host=arm-linux --prefix=/usr
 \end{verbatim}
 
-Now, we should quiclky get an error in the execution of the configure
-script:
+Now, we should quiclky get an error in the execution of the
+\code{configure} script:
 
 \begin{verbatim}
 checking for libasound headers version >= 1.0.27... not present.
 configure: error: Sufficiently new version of libasound not found.
 \end{verbatim}
 
-Again, we can check in config.log what the configure script is trying
-to do:
+Again, we can check in \code{config.log} what the \code{configure}
+script is trying to do:
 
 \footnotesize
 \begin{verbatim}
@@ -380,11 +378,11 @@ conftest.c:15:28: fatal error: alsa/asoundlib.h: No such file or directory
 \end{verbatim}
 \normalsize
 
-Of course, since {\em alsa-utils} uses the {\em alsa-lib}, it includes
+Of course, since {\em alsa-utils} uses {\em alsa-lib}, it includes
 its header file! So we need to tell the C compiler where the headers
 can be found: there are not in the default directory
 \code{/usr/include/}, but in the \code{/usr/include} directory of our
-{\em staging} space. The help text of the configure script says:
+{\em staging} space. The help text of the \code{configure} script says:
 
 \begin{verbatim}
   CPPFLAGS              C/C++/Objective C preprocessor flags,
@@ -407,16 +405,16 @@ checking for snd_ctl_open in -lasound... no
 configure: error: No linkable libasound was found.
 \end{verbatim}
 
-The configure script tries to compile an application against {\em
+The \code{configure} script tries to compile an application against {\em
   libasound} (as can be seen from the \code{-lasound} option): {\em
-  alsa-utils} uses the {\em alsa-lib}, so the \code{configure} script
+  alsa-utils} uses {\em alsa-lib}, so the \code{configure} script
 wants to make sure this library is already installed. Unfortunately,
-the \code{ld} linker doesn't find this library. So, let's tell the
+the \code{ld} linker doesn't find it. So, let's tell the
 linker where to look for libraries using the \code{-L} option followed
 by the directory where our libraries are (in
 \code{staging/usr/lib}). This \code{-L} option can be passed to the
 linker by using the \code{LDFLAGS} at configure time, as told by the
-help text of the configure script:
+help text of the \code{configure} script:
 
 \begin{verbatim}
   LDFLAGS       linker flags, e.g. -L<lib dir> if you have
@@ -429,16 +427,6 @@ Let's use this \code{LDFLAGS} variable:
 LDFLAGS=-L$HOME/embedded-linux-labs/thirdparty/staging/usr/lib \
 CPPFLAGS=-I$HOME/embedded-linux-labs/thirdparty/staging/usr/include \
 CC=arm-linux-gcc \
-./configure --host=arm-linux
-\end{verbatim}
-
-Let's also specify the prefix, so that the library is compiled to be
-installed in \code{/usr} and not \code{/usr/local}:
-
-\begin{verbatim}
-LDFLAGS=-L$HOME/embedded-linux-labs/thirdparty/staging/usr/lib \
-CPPFLAGS=-I$HOME/embedded-linux-labs/thirdparty/staging/usr/include \
-CC=arm-linux-gcc \
 ./configure --host=arm-linux --prefix=/usr
 \end{verbatim}
 
@@ -618,7 +606,7 @@ Done with libogg!
 Once again, the libvorbis build system is a nice example of what can
 be done with a good usage of the autotools. Cross-compiling libvorbis
 is very easy, and almost identical to what we've seen with the
-alsa-utils. First, the configure step:
+alsa-utils. First, the \code{configure} step:
 
 \begin{verbatim}
 CC=arm-linux-gcc \
@@ -732,7 +720,7 @@ configuration options:
   optionally be used by the vorbis tools
 \end{itemize}
 
-So, let's begin with our usual configure line:
+So, let's begin with our usual \code{configure} line:
 
 \begin{verbatim}
 LDFLAGS=-L$HOME/embedded-linux-labs/thirdparty/staging/usr/lib \
@@ -759,7 +747,7 @@ checking for AO... no
 configure: WARNING: libao too old; >= 1.0.0 required
 \end{verbatim}
 
-Ok, now at the end of the configure, we get:
+Ok, now at the end of the \code{configure}, we get:
 
 If you look into the \code{config.log} file now, you should find
 something like:
@@ -773,11 +761,11 @@ to the PKG_CONFIG_PATH environment variable
 No package 'ao' found
 \end{verbatim}
 
-In this case, the configure script uses the {\em pkg-config} system to
+In this case, the \code{configure} script uses the {\em pkg-config} system to
 get the configuration parameters to link the library against libao. By
 default, {\em pkg-config} looks in \code{/usr/lib/pkgconfig/} for
 \code{.pc} files, and because the \code{libao-dev} package is probably
-not installed in your system the configure script will not find the
+not installed in your system the \code{configure} script will not find the
 libao we just compiled.
 
 It would have been worse if we had the package installed, because it
@@ -827,14 +815,14 @@ CC=arm-linux-gcc \
 \end{verbatim}
 \normalsize
 
-Now, the configure script should end properly, we can now start the
+Now, the \code{configure} script should end properly, we can now start the
 compilation:
 \begin{verbatim}
 make
 \end{verbatim}
 
 It should fail rather quickly, complaining that the curl headers are
-missing. This is because the configure script, in curl's case, didn't
+missing. This is because the \code{configure} script, in curl's case, didn't
 actually test whether it was available or not, but just assumed it was.
 
 It may also fail with the following cryptic message:
@@ -865,7 +853,7 @@ Again, this is not what we want because it contains includes for the
 host, not the target. It is coming from the autodetected value for
 \code{CURL_CFLAGS}.
 
-Add the \code{--without-curl} option to the configure invocation,
+Add the \code{--without-curl} option to the \code{configure} invocation,
 restart the compilation.
 
 The compilation may then fail with an error related to libm. While
@@ -873,7 +861,7 @@ the code uses the function from this library, the generated Makefile
 doesn't give the right command line argument in order to link against
 the libm.
 
-If you look at the configure help, you can see
+If you look at the \code{configure} help, you can see
 \begin{verbatim}
 LIBS        libraries to pass to the linker, e.g. -l<library>
 \end{verbatim}
@@ -881,7 +869,7 @@ LIBS        libraries to pass to the linker, e.g. -l<library>
 And this is exactly what we are supposed to use to add new linker
 flags.
 
-Add this to the configure command line to get
+Add this to the \code{configure} command line to get
 \begin{verbatim}
 LDFLAGS=-L$HOME/embedded-linux-labs/thirdparty/staging/usr/lib \
 CPPFLAGS=-I$HOME/embedded-linux-labs/thirdparty/staging/usr/include \