View source for UDOO compile Android 4.2.2 from sources

This wiki describes the necessary steps to start and use the pre-compiled Android software support package for UDOO Board. Moreover, a description of how to rebuild the bootloader, kernel and Android file system is provided.
The procedure described in this wiki refers to UDOO Board Dual and Quad version.

= System Requirements =
Android system for UDOO board is provided as precompiled images or as source code to be customized and rebuilt.
Running the full procedure described in this wiki, rebuilding the Android system from source files, it is necessary to have an host PC (or Virtual Machine) running Ubuntu Linux 10.04 64bit with at least 40 GB of free disk space, configured [[#Set up the work environment|here]]. The host PC should also include:
* an SD/µSD card reader;    
* a microUSB cable to connect UDOO to host and access debug serial    
* an host pc with internet connection

== Terminology ==
The set of scripts and images necessary to run Android on a board is generically called a Distro.

= Set up the work environment =
Given an host PC (or Virtual Machine) running Ubuntu Linux 10.04 64bit with at least 40 GB of free disk space, it is required to install all the necessary packages for a standard Android build, as reported on the Android website at http://source.android.com/source/initializing.html.

We suggest to use a Virtual Machine environment to create a close and dedicated workspace. It reduce risks of procedure and libraries mismatching or to corrupt other working enviroments present on the host machine.

== Install and configure a Virtual Machine with Ubuntu 10.04 64bit ==
We suggest to use VMware ® Player™ for this operation. We provide a step by step installation procedure.

'''Mac users have to use Virtual Box player. Unfortunately we didn’t test procedure on this system.'''

# Download the player from VMware ® Player™ website: You can find the last version at this url: http://www.vmware.com/products/player/ and choose the right version for your OS. 
# Install the VM on your system 
# Download Ubuntu Desktop 10.04 installation disk image. We suggest to use a 64 bit 10.04 Ubuntu distro to run this procedure. You can find the download links at http://old-releases.ubuntu.com/releases/lucid/
# Create a new VM running Ubuntu 10.04
## Click on VMware Player icon.
## Choose Create a New Virtual Machine from menu on the right
## Choose Installer disk image file (iso) and choose the uclick on ubuntu iso image from your download location. Then press Next button.
## Then you have to choose your name, the username and the password. Fill these fields and click on next button.
## Choose the VM name: UDOO-dev-10.04 and click next.
## Set hard-disk size at least 40 GB. Unfortunately compile Android OS take a big amount of disk space. Select split virtual disk into multiple files option.
# Set VM performance clicking on customize hardware button.     
## Memory Options (''Caution: choose the size of memory size depending the amount of free memory on the host computer. If you assign a larger amount of memory to VM can let host OS swapping or pagining. This kill your computer performance!''):
##*	1 GB minimum (low performance, lot of swapping during the compilation)
##*	2.5 GB recomended (memory swapping especially during java compilations)
##*	4 GB+ perfect (no memory swapping during build operations)
## CPUs: We suggest to assign to VM all the available CPUs of your host machine especially for the first compilation that take a lot of time. After that you can reduce the number of CPUs as you prefer. It is possible that 4 is the maximum of available CPUS for the VM.
# Click on finish button and Ubuntu installation will start.
# After installation finish, you should login from console and launch the GUI running this command:

 startx 

= Configure Ubuntu 10.04 =

Android website reports the following list of packages that must be installed in the host PC (and all their dependencies):
 HOST$ sudo apt-get update
 HOST$ sudo apt-get install git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown libxml2-utils xsltproc uboot-mkimage uuid uuid-dev liblz-dev liblzo2-2 liblzo2-dev dialog sun-java6-jdk 

'''Note:''' sun-java6-jdk package isn’t still available on official repositories. Given the Android compilation process needs the Oracle Java version 6 we suggest two methods to install it.

== Instal Java Oracle 6 from aptitude ==

 HOST$ sudo apt-get install software-properties-common
 HOST$ sudo add-apt-repository ppa:webupd8team/java
 HOST$ sudo apt-get update
 HOST$ sudo apt-get install oracle-java6-installer

== Instal Java Oracle 6 from official site ==

Download binary installation package from oracle download page (remember JDK 6 update 35 for 64 bit linux version) http://download.oracle.com/

Change permissions to downloaded file
 HOST$ sudo chmod 755 jdk-6u35-linux-x64.bin

Create destination folder
 HOST$ sudo mkdir /usr/bin/jvm/

Copy the installer into destination folder
 HOST$ cp jdk-6u35-linux-x64.bin /usr/bin/jvm/
 HOST$ cd /usr/bin/jvm/

Launch the installer
 HOST$ ./jdk-6u35-linux-x64.bin

It will create a folder in current path called jdk1.6.0_35

Update the java alternatives:
 HOST$ sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/jdk1.6.0_35/bin/java" 1
 HOST$ sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/lib/jvm/jdk1.6.0_35/bin/javac" 1
 HOST$ sudo update-alternatives --install "/usr/bin/javaws" "javaws" "/usr/lib/jvm/jdk1.6.0_35/bin/javaws" 1
 HOST$ sudo update-alternatives --install "/usr/bin/jar" "jar" "/usr/lib/jvm/jdk1.6.0_35/bin/jar" 1
 HOST$ sudo update-alternatives --install "/usr/bin/javadoc" "javadoc" "/usr/lib/jvm/jdk1.6.0_35/bin/javadoc" 1

After each following commands you need to choose the java version previously installed: jdk1.6.0_35.

 HOST$ sudo update-alternatives --config java
 HOST$ sudo update-alternatives --config javac
 HOST$ sudo update-alternatives --config javaws

Now it's possible to remove the installer
 HOST$ rm jdk-6u35-linux-x64.bin

= Serial communication =
While not exactly necessary, serial communication with UDOO is strongly recommended as the first debug method. In order to use the serial debug port on UDOO, after connecting the board and host PC ports, it is necessary to install and setup an application for serial communication, such as minicom, cutecom or gtkterm (to mention only the most famous). There is no specific requirement on the application to use, here we only consider minicom, but settings for the others are equivalent.

Install minicom
 HOST$ sudo apt-get install minicom

Launch minicom in setup mode (and with Linewrap ON, not necessary but useful)
 HOST$ sudo minicom -sw

Select “Serial port setup” and check the following parameters
* Serial Device, option A (usually, /dev/ttyS0 or /dev/ttyUSB0 in case an USB  adapter is used)
* Communications parameters, option E (must be 115200 8N1)
* No flow control, neither hardware nor software, options F and G

Save the settings as default.

Exit closes setup and opens minicom, instead “Exit from minicom” completely closes minicom, and you have to run it again without setup options
 HOST$ sudo minicom -w

= Run Android=
Right now the Android OS can boot only from a Micro SD. Here we consider only to boot UDOO from the external SD present on board.
In order to install and run a Distro on UDOO, it is sufficient to prepare an SD with the Android system images, connect it to the board and power up the board. 

== Notes on the prebuilt images ==
In order to simplify packages distribution and use, the bootloader prebuilt images are compiled for only a set of the possible configurations, allowing anyway to boot any platform.
In particular, we provide:
* prebuilt images for UDOO Dual and 1 GB of DDR    
* prebuilt images for UDOO QUad and 1 GB of DDR

== Boot Android from SD ==
When the script ends, insert the SD in the Carrier5, and power it up. The Android system boots.
You can see the Android bootscreen on a connected HDMI monitor within 20 seconds, while messages on the serial debug port start to be sent almost immediately.
First of all, messages from the bootloader can be seen. Among the rest, characteristics of the
board are shown: CPU type, boot device and memory size. Please check the correctness of these informations.
The kernel is automatically launched after 3 seconds of countdown. The first time Android System boots, it must configure the storage, preparing folders for data and applications. As a consequence, every time the SD is prepared with the procedure described in this section, the first boot takes around 1 minute, while subsequent boots are much faster.
At the end of the boot procedure, you can interact with the system either with mouse and keyboard and the HDMI display, or with a root console automatically opened in serial.

The serial debug port is used for two different reasons:
The bootloader and kernel send debug messages via serial port, so that the user can monitor the low level system state; a root console is opened on the seriaI port, allowing bootloader configuration and system control.

The number of messages sent via serial port can be very high. For this reason, it is quite useful to increase scrolling capabilities of the terminal, possibly setting them to a very high or even unlimited.

= Build Android =
For a better tune-up of the system, it is possible to build the Android system images from scratch, rather than use the precompiled images.

Create a folder and get the source code, download tar file containing sources from http://www.udoo.org/downloads/

 HOST# cd [udoo-android-dev]
 HOST# tar –xzvpf UDOO_Android-4.2.2_Sources_1.0.tar.gz

It take up to an hour to download files from git. [udoo-android-dev] contain Androids sources and a series of scripts that helps in configuring the environment, building the system and preparing a new set of images to be run on UDOO Board (following again the procedure described in [[#Run Android|Run Android section]]).

In order to build the whole system, it is necessary to
# configure the environment        
# build the bootloader (u-boot)        
# build kernel and Android system

Each step is considered separately.

== Configure the environment ==
Prior to build the system, it is necessary to configure the Android environment for the specific build. In particular, the following commands have to be launched:

 HOST$ export ARCH=arm
 HOST$ export CROSS_COMPILE=$PWD/prebuilts/gcc/linux-x86/arm/arm-eabi-4.6-bin/arm-eabi-
 HOST$ export PATH=$PWD/bootable/bootloader/u-boot-imx/tools:$PATH
 HOST$ . build/envsetup.sh

Finally, it is necessary to choose which target to build. The command below shows a list of possible targets

 HOST$ lunch

For each possible target, the first part of the name indicates the board you are building for, while the second part selects the build type, as described at http://source.android.com/source/building-running.html.

In particular, valid options to build for UDOO board are:

* udoo-user: build for production, with limited access
* udoo-eng: build for development, with root access and additional debugging tools 

The target selection can alternatively be done directly at command line, calling for example

 HOST$ lunch udoo-eng

Once all these steps are done, several environment variables are set. Among the rest, it is worth noting the environment variable OUT, automatically set to [udoo-android-dev]/out/target/product/udoo, that is the folder where Android system is actually built, and where object files, folders and system images are created. From now on, this folder is called [OUT].
For everyday development, a command list is provided that automatically launches all the commands above:

 HOST$ . setup udoo-eng

or alternatively

 HOST$ . setup udoo-user

== Build u-boot ==
Move to the folder where bootloader sources are located, with command

 HOST$ cd [udoo-android-dev]/bootable/bootloader/uboot-imx

The sources can be compiled for different boards, modules and OS. A script is provided to guide u boot compilation, and help in configuring the bootloader for the specific Module and system characteristics. It is sufficient to launch the following command to run the script for configuration:

 HOST$ ./compile.sh -c

In a graphical menu is possible to choose some compilation options:
The following settings are allowed:
* '''DDR Size''': 1 options are given GB with bus size 64 (4 banks, each of 256 MB)
* '''Board Type''': Udoo must be chosen.    
* '''CPU Type''': refers to i.MX6 specific CPU, values are Quad and Dual.    
* '''OS Type''': Linux or Android, Android must be selected.    
* '''Environment device''': where the u-boot environment is stored. SD/MMC must be selected.    
* '''Extra  option''': at the moment, in this submenu it is only possible to force clean before compile.    
* '''Compiler options''': here the compiler path can be chosen (this is useful for Linux only, leave this as it is), and part of the u-boot version string can be customized.

Once all settings are checked, select Exit, and the following screen select OK to just save the settings or Yes, with Compile to save and directly compile the bootloader. If you saved the settings, you can also rebuild u-boot with the command.

 HOST$ ./compile.sh

This operation usually takes less than a minute (but depends on the host PC). In the end, the bootloader image u-boot.bin is placed in the same directory and is ready to be used to boot the UDOO Board.

== Build Android system image ==

The easiest but most time-consuming step in building Android is to build the Android system image. In general, after configuring the environment as in [[#Configure the environment |configuration section]], it is sufficient to launch the following command to build the whole system image, including the kernel:

 HOST$ make

The duration of the whole system build is strongly dependent on the host PC you are working on, but this can take up to several hours, and builds more than 20GB of compiled code (this is the size of the [udoo-android-dev]/out/ folder when the operation is completed).
Enabling parallel compilation can speed up the process. In general, the idea is to let the compiler to launch several compiling jobs in parallel, where the number of jobs depends on the specific PC you are working on.

 HOST$ make -jN

where N is the maximum number of parallel jobs allowed. For a better explanation of this point (included the value to assign to N), please see http://source.android.com/source/building-running.html, in [[#Build the Code|Build the Code section]].

Several files and folders are created in [OUT]. Among the rest we underline:

* ''root/'' and ''ramdisk.img'': root file system and generated image    
* ''recovery/'' and ''ramdisk-recovery.img'': root file system used in recovery mode, and generated image    
* ''system/'' and ''system.img'': Android system including binaries and libraries, and generated image    
* ''data/'' and ''userdata.img'': Android data area and generated image    
* ''kernel'' and ''uImage'': kernel images    
* ''boot.img'': kernel and initial root ramdisk, generated from kernel and ramdisk.img
* ''recovery.img'': kernel and initial root ramdisk used in recovery mode, generated from kernel and ramdisk-recovery.img

Together with the bootloader image created [[#Build u-boot|previously]], the images are sufficient to boot UDOO board with the default kernel configuration, as described [[#Use the new Android system images|here]]. Instead if it is necessary to customize the kernel, the procedure is described in [[#Build Kernel|kernel section]].

== Build Kernel ==
The kernel is built together with the rest of the [[#Build Android system image|Android system]]. However, it is also possible to modify the configuration and rebuild it separately.
As for the bootloader, the kernel can be configured and customized for a very wide range of boards and peripherals. Linux kernel customization is a very complex task, an in-depth description is out of the scope of this document. Here we consider only the default configuration to run linux kernel on UDOO board.
It is possible to configure (or restore) the kernel to the default configuration for the Module calling the command

 HOST$ make -C kernel_imx UDOO_android_defconfig

If you wish to check the configuration or customize it, use

 HOST$ make -C kernel_imx menuconfig

The command opens a graphical configuration tool equivalent to the one for u-boot. Any saved change is stored in the same folder as an hidden file called .config, which then is the actual configuration file used to compile the kernel.
Once the configuration is ready, the kernel is compiled with command

 HOST$ make bootimage

This operation can take up to 30 minutes to complete, and performs several actions:
* builds the kernel, creating the images uImage  and zImage in [udoo-android-dev]/kernel_imx/arch/arm/boot    
* copies the kernel images in [OUT] (zImage is renamed to kernel)    
* updates root/ and ramdisk.img    
* updates boot.img from ramdisk.img and kernel

When it is done, the new boot.img is present in [OUT], ready to be used to boot the Module.
    

== Use the new Android system images ==
Once the new Android system images are rebuilt based on the previous Sections, it is necessary to prepare an µSD with the new images and boot UDOO board. A script is provided to help in this step. In a way similar to what is described in [[#Run Android|Run Android section]], the script partitions and formats the SD, and then copies the new Android images on the SD, reading them directly from [OUT] (and [udoo-android-dev]/bootable/bootloader/uboot-imx for the bootloader). It is sufficient to follow the next steps.

Connect the SD card to your host PC, and use the command dmesg to find the device name; we suppose it is /dev/sdc    
Launch the script to prepare the SD

 HOST# sudo -E sh /make_sd.sh /dev/sdc

When this is done, the SD containing the new images is ready to boot UDOO as described in[[#Boot Android from SD|dedicated section]].

== Prepare a Distro ==
It is sometimes useful to prepare a new Distro to be stored. To do this, once the new images are built following the procedures described in the previous Sections, it is sufficient to call the command

 HOST$ ./prepare_distro.sh [distro_name]

Called without arguments, the script creates a new folder UDOO_Android_4.2_Distro, containing the freshly built Android system images, and the scripts to use them. An archive UDOO_Android_4.2_Distro.tar.gz is also prepared for distribution. The optional parameter [distro_name] can be used to customize the folder and archive name.
Once the archive is ready, its use is described in [[#Run Android|Run Android section]].

[[Category:UDOO]]