\subchapter{First compilation}{Get used to the build mechanism}

During this lab, you will:
\begin{itemize}
  \item Configure which system to build Android for
  \item Compile your first Android root filesystem
\end{itemize}

\section{Setup}

Stay in the Android source directory.

\section{Set up ccache}

To be able to use \code{ccache} properly, we need to apply a commit
present in the AOSP master that will bump the version of ccache to a
more recent and much more adapted version of \code{ccache}.

We will first need to create a new branch where we will store the
commit doing such a change. To do that, we will obviously use
\code{repo}, and especially the \code{start} sub-command, on the
\code{prebuilts/misc} repository. We can call that branch
\code{ccache} for example.

Now, go in the \code{prebuilts/misc} directory, and use the command
\code{git cherry-pick 81012983}. This will apply the given commit in
our current branch, and since we have created a new branch,
\code{repo} will carry our commits, even if we do \code{repo sync}.

\section{Build environment}

Now that \code{repo sync} is over, we will compile an Android system
for the emulator. This will include building the emulator itself.

First, run \code{source build/envsetup.sh}.

This file contains many useful shell functions and aliases, such as
\code{croot} to go to the root directory of the Android source code or
\code{lunch}, to select the build options.

Check your \code{PATH} environment variable:

\begin{verbatim}
echo $PATH
\end{verbatim}

You will see that \code{build/envsetup.sh} hasn't modified your
\code{PATH}.  This will be done during the build job.

The target product for the emulator is {\it full}, and we want to
have an engineering build. To do this, run \code{lunch aosp_arm-eng}

Now, to tell Android to use \code{ccache} whenever possible, we need
to set a few environment variable.

\begin{verbatim}
export USE_CCACHE=1
export CCACHE_DIR=/opt/ccache
\end{verbatim}
or, depending on your setup,
\begin{verbatim}
export CCACHE_DIR=$HOME/android-labs/ccache
\end{verbatim}

And that's it!

\section{Compile the root filesystem}

The build system will use the proper setup to build this
target. Before running \code{make}, first check the number of CPU
cores in your workstation, as seen by the operating system
(hyperthreading could make your OS see 4 cores instead of 2, for
example).

\begin{verbatim}
cat /proc/cpuinfo
\end{verbatim}

You can use \code{make -j} (\code{j} stands for {\it jobs} to instruct
\code{make} to run multiple compile jobs in parallel, taking advantage
of the multiple CPU cores, and making sure that I/Os and CPU cores are
always at 100\%. This will significantly reduce build time.

For example, if Linux sees 4 cores, you will get good performance by
specifying the double number of parallel jobs:

\begin{verbatim}
make -j 8
\end{verbatim}

While this command runs, make sure you are actually using ccache
properly: in another terminal, set the \code{CCACHE_DIR} environment
variable like we did, and use the command

\begin{verbatim}
watch -n1 -d prebuilts/misc/linux-x86/ccache/ccache -s
\end{verbatim}

After a few minutes, you should see the number of cache hits
increasing, while the number of cache misses remain very low. If
that's not the case, call your instructor.

Go grab (several cups of) coffee!

\paragraph{Known issue}
In rare circumstances, some builds can fail when \code{make} is run
with multiple jobs in parallel. If this happens, you can run
\code{make} with no option after the failure, and this is likely to
make the issue disappear.

\section{Test your Android build}

Now, look at the \code{PATH} environment variable again.

You can see that it contains:
\begin{itemize}
\item
  \code{$HOME/android-labs/source/out/host/linux-x86/bin/}.
  That's where new utilities have just been compiled.
\item Prebuilt executables, in particular the ARM cross-compiling
  toolchain, which was already present in the repositories fetched by
  \code{repo}.
\end{itemize}

Look at the contents of the \code{out/target/product/generic} folder.
That's where the system images have been built.

Run the \code{emulator} command. It will run the emulator with these
generated images.  Wait a few minutes for the emulator to load the
system, and then check the build number in the \code{Settings}
application in Android.

\paragraph{Note}
The \code{PATH} settings automatically added by the build process will
be lost if you close your terminal. We will see how to restore this
environment in the next lab.
