[FE training-materials-updates] kernel sources lab: only use git

[Michael Opdenacker]

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

On branch  : kernel-ng
Link       : http://git.free-electrons.com/training-materials/commit/?id=29ac9efe8243899ced404a52a433651858317326

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

commit 29ac9efe8243899ced404a52a433651858317326
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Wed Sep 18 22:45:53 2013 +0200

    kernel sources lab: only use git
    
    Signed-off-by: Michael Opdenacker <michael.opdenacker at free-electrons.com>


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

29ac9efe8243899ced404a52a433651858317326
 labs/kernel-sources/kernel-sources.tex |   89 ++++++++++++++++++--------------
 1 file changed, 49 insertions(+), 40 deletions(-)

diff --git a/labs/kernel-sources/kernel-sources.tex b/labs/kernel-sources/kernel-sources.tex
index d4df67f..5f47eec 100644
--- a/labs/kernel-sources/kernel-sources.tex
+++ b/labs/kernel-sources/kernel-sources.tex
@@ -5,35 +5,66 @@ After this lab, you will be able to:
 
 \begin{itemize}
 
+\item Get your own copy of the mainline Linux kernel source tree
 \item Explore the sources in search for files, function headers or
   other kinds of information...
-
 \item Browse the kernel sources with tools like \code{cscope} and LXR.
-
 \end{itemize}
 
 \section{Setup}
 
 Go to the \code{$HOME/felabs/linux/modules} directory.
 
-Download and extract the Linux 3.5 kernel sources
-from \url{http://kernel.org}.
+First, install required software packages:
+
+\begin{verbatim}
+sudo apt-get install git gitk git-email
+\end{verbatim}
+
+\section{Cloning the mainline Linux tree}
+
+To begin working with the Linux kernel sources, we need to clone its
+reference git tree, the one managed by Linus Torvalds.
 
-\section{Apply patches}
+The trouble is you have to download about 1.5 GB of data!
 
-Install the \code{patch} command, either through the graphical package
-manager, or using the following command line:
+If you are running this command from home, or if you have very fast
+access to the Internet at work (and if you are not 256 participants in the
+training room), you can do it directly by connecting to
+\url{http://git.kernel.org}:
 
+{\small
 \begin{verbatim}
-sudo apt-get install patch
+git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+\end{verbatim}
+}
+
+or if the network port for \code{git} is blocked by the corporate
+firewall, you can use the \code{http} protocol as a less efficient
+fallback:
+
+{\small
+\begin{verbatim}
+git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 
 \end{verbatim}
+}
+
+If Internet access is not fast enough and if multiple people have to
+share it, your instructor will give you a USB flash drive with a
+\code{tar.xz} archive of a recently cloned Linux source tree.
 
-Now, download the two Linux patches corresponding to versions 3.6 and
-3.6.x (if such a version exists).
+You will just have to extract this archive in the current directory,
+and then pull the most recent changes over the network:
+
+\begin{verbatim}
+tar Jxf linux-git.tar.xz
+cd linux
+git pull
+\end{verbatim}
 
-Apply these patches, check the \code{Makefile} file to double check
-that you have the right version, and rename the source directory to
-reflect the version change.
+Of course, if you directly ran \code{git clone}, you won't have run 
+\code{git pull} today. You may run \code{git pull} every morning though,
+or at least every time you need an update of the upstream source tree.
 
 \section{Get familiar with the sources}
 
@@ -47,6 +78,11 @@ exploring the kernel sources.
 \item Find the declaration of the \code{platform_device_register()} function.
 \end{enumerate}
 
+Tip: if you need the \code{grep} command, we advise you to use \code{git
+grep}. This command is similar, but much faster, doing the search only
+on the files managed by git (ignoring git internal files and generated
+files). 
+
 \section{Use a kernel source indexing tool}
 
 Now that you know how to do things in a manual way, let's use more
@@ -60,30 +96,3 @@ If you don't have Internet access, you can use \code{cscope} instead.
 As in the previous section, use this tool to find where
 the \code{platform_device_register()} is declared, implemented and
 even used.
-
-\section{Accessing kernel sources with git}
-
-Later this week, we will also see another way of accessing kernel
-sources, with the {\em git} source control management tool used by kernel
-developers.
-
-To save time with the git lab on the last day, let's advance us by
-cloning the Linus Torvalds' git tree.
-
-First, install required software packages:
-
-\begin{verbatim}
-sudo apt-get install git gitk git-email
-\end{verbatim}
-
-Then, go to the \code{$HOME/felabs/linux/git directory}, and run
-the below command:
-
-\small
-\begin{verbatim}
-git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-\end{verbatim}
-\normalsize
-
-Now, just let this command run, from 30 minutes to several hours
-according to your workstation and network speed.