Changes between Initial Version and Version 1 of Android/Building


Ignore:
Timestamp:
10/22/2017 05:28:45 AM (2 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Android/Building

    v1 v1  
     1[[PageOutline]]
     2
     3= Gateworks Ventana Android Board Support Package =
     4
     5Gateworks supports the following Android versions:
     6 * Android 5.1.1 (Aka 'Lollipop')
     7 * Android 4.4 (Aka '!KitKat')
     8 * Android 4.3 (Aka 'Jelly Bean-MR2')
     9
     10For a feature list please see [wiki:Android Gateworks Android]
     11
     12[=#variants]
     13= Android Build Variants =
     14The Android build system supports different build variants. The two that we build and support are:
     15 * eng - used for development and hacking
     16  - installs modules tagged with 'eng', 'debug', 'user', and/or 'development'
     17  - installs non-APK modules that have no tags specified
     18  - installs APKs according to the product definition files, in addition to tagged APKs
     19  - default.prop disables security and allows debugging:
     20{{{#!bash
     21ro.secure=0
     22ro.debuggable=1
     23}}}
     24  - {{{adb}}} runs as user 'root' is enabled by default (this allows commands such as {{{adb remount}}} and {{{adb push}}})
     25 * user - intended for final release
     26  - installs modules tagged with 'user'
     27  - installs non-APK modules that have no tags specified
     28  - installs APKs according to the product definition files; tags are ignored for APK modules.
     29  - default.prop disables security and allows debugging:
     30{{{#!bash
     31ro.secure=1
     32ro.debuggable=0
     33}}}
     34  - {{{adb}}} runs as user 'shell' and is disabled by default ({{{adb}}} running as non-root dis-allows commands such as {{{adb remount}}} and {{{adb push}}} but allows {{{adb install}}}
     35
     36
     37[=#prebuilt]
     38= Gateworks Precompiled Android Binary =
     39Gateworks provides pre-built Android images that you can evaluate without building the source if needed. You have the following options:
     40 * purchase a pre-installed USB stick from the [http://shop.gateworks.com/index.php?route=product/product&path=70_82&product_id=133 Gateworks Online Shop]
     41 * download UBI image if you have a board with 2GB of NAND flash and want to boot Android from flash
     42 * download tarball and image a removable block storage device (mSATA / USB / uSD)
     43
     44Latest images:
     45 * Android 4.4 (!KitKat):
     46  * Built on 2016-02-10 from Gateworks Android BSP:
     47   * Source: https://github.com/Gateworks/imx_android/tree/gateworks_kk4.4.3_2.0.0-ga
     48   * [wiki:Android Android Wiki]
     49   * Based on Freescale kk4.4.3_2.0.0-ga source
     50  * ubi images ('''requires 2GB NAND'''):
     51   * [http://marketing.gateworks.com/acton/formfd/2923/0007:d-0059 gateworks-kk4.4.3_2.0.0-ga-user-20160210.ubi] (sha256sum:1575480f030afa1cad42fe7cb719a1318367092abe9c523a2e8bf13397c8b4a9)
     52   * [http://marketing.gateworks.com/acton/formfd/2923/0007:d-005a gateworks-kk4.4.3_2.0.0-ga-eng-20160210.ubi] (sha256sum:ed0b090bf446049e9442e9bbe342e1750bae581bcf3a82d3d595a2212dd90e18)
     53  * tarballs (for imaging onto removable block storage devices):
     54   * [http://marketing.gateworks.com/acton/formfd/2923/0007:d-005b gateworks-kk4.4.3_2.0.0-ga-user-20160210.tar.gz] (sha256sum:933392c9217fefe0c0fc1a8c9f408f61f197aefc1e10210278ae3005fac5a86c)
     55   * [http://marketing.gateworks.com/acton/formfd/2923/0007:d-005c gateworks-kk4.4.3_2.0.0-ga-eng-20160210.tar.gz] (sha256sum:f95428b42e8c40c420b00d63d1dc2b40c46b1950f47f0db996929561dd14308b)
     56
     57See [#variants above] for differences on the {{{eng}}} vs {{{user}}} build variant
     58
     59Once you have installed the pre-built image using one of the methods below please see [wiki:Android#BootingAndroid here] for important instructions on booting Android
     60
     61
     62== Install on 2GB NAND Flash via ubi file ==
     63To install Android in flash for boards with 2GB of NAND from a downloaded ubi image:
     64 1. Download Binary ubi (see above for options)
     65 2. Place ubi on tftp server or removable storage
     66 3. Boot target and break into the bootloader
     67 4. Update NAND flash with image.ubi served from a tftp server (modify the ip addrs below for your network):
     68{{{#!bash
     69setenv ipaddr 192.168.1.1
     70setenv serverip 192.168.1.254
     71tftp ${loadaddr} android.ubi && nand erase.part rootfs && nand write ${loadaddr} rootfs ${filesize}
     72}}}
     73  * For more examples of loading images into uboot from network/mmc/usb see [wiki:linux/ubi#WorkingwithUBIinu-bootBootloader here]
     74
     75
     76== Install on a 2GB+ removable block storage device (USB/SATA/MMC) ==
     77The partitioning scheme Gateworks uses for Android on block storage is the following:
     78||= Partition =||= Size =||= Name     =||= Filesystem =||= Description =||
     79|| N/A         || 1MB    ||  -         || -            || SPL, bootloader, env ||
     80|| /dev/sdc1   || 20MB   || BOOT       || ext4         || Android boot partition (bootscript, kernel, dtbs, ramdisk) ||
     81|| /dev/sdc2   || 20MB   || RECOVERY   || ext4         || Android's recovery partition ||
     82|| /dev/sdc3   || -      || extended   || -            || extended partition ||
     83|| /dev/sdc4   || -      || DATA       || ext4         || userdata ||
     84|| /dev/sdc5   || 512MB  || SYSTEM     || ext4         || Android's /system partition (ROM) ||
     85|| /dev/sdc6   || 50MB   || CACHE      || ext4         || cache ||
     86|| /dev/sdc7   || 10MB   || VENDOR     || ext4         || vendor ||
     87|| /dev/sdc8   || 10MB   || MISC       || ext4         || misc  ||
     88
     89
     90To install on a 2GB+ removable block storage device (USB/SATA/MMC) from a downloaded tarball you first need to know the Linux device name of the storage device (use the Disks tool, or look at {{{/var/log/messages}}} for this info). Assuming {{{/dev/sdc}}} you can:
     91 1. Download Binary tarball (see above for options)
     92 2. extract the binary (example using gateworks-kk4.4.3_2.0.0-ga-user-20150327.tar.gz)
     93{{{#!bash
     94tar xvf gateworks-kk4.4.3_2.0.0-ga-user-20150327.tar.gz
     95}}}
     96 3. cd into the directory with the build artifacts and run the mksdcard.sh script:
     97{{{#!bash
     98cd kk4.4.3_2.0.0-ga_user
     99sudo ./mksdcard.sh /dev/sdc
     100}}}
     101
     102Note that the partition layout above requires 8 partitions which are typically not supported with built-in SDIO host controllers (which is what you are using if your microSD shows up as /dev/mmcblk*). We recommend using a USB based microSD card reader/writer which can be found from office supply stored for under $5.
     103
     104
     105[=#building]
     106= Building Android for Ventana from source =
     107
     108== Pre-requisites ==
     109
     110[=#dev-host]
     111=== Build Host ===
     112Per the Android documentation [https://source.android.com/source/building.html here] you should have a build host with the following:
     113 * Linux or Mac
     114 * 64bit environment
     115 * 100GB (for a single build, 150GB or more for multiple builds, and more if you use ccache)
     116 * Python 2.6 - 2.7
     117 * GNU Make 2.81 - 3.82
     118 * JDK 6 (for Gingerbread through !KitKat)
     119 * Git 1.7 or newer
     120
     121Gateworks uses Ubuntu 14.04/13.10 64bit build hosts although other configurations may work.
     122
     123A virtual machine is possible to use and Gateworks has verified that our latest BSP builds with the popular [http://nathanpfry.com/builduntu-virtual-machine-android-rom-compiling/ BuilduntuVM] based on Xubuntu with the following changes (based on BuildubuntuVM v1.5):
     124 * Download from [http://nathanpfry.com/builduntu-virtual-machine-android-rom-compiling/ BuilduntuVM page]
     125 * change Networking mode to bridged instead of NAT - !VirtualBox NAT can be unreliable with the heavy traffic a repo sync does.
     126 * adjust the memory allocated to the VM to a level appropriate for your host (defaults to 4GB, we've tested with 2GB)
     127 * install make v3.81 (make v4.0 on BuilduntuVM needs to be downgraded for Android !KitKat builds):
     128{{{#!bash
     129wget -o make.tar.gz http://ftp.gnu.org/gnu/make/make-3.81.tar.gz
     130tar -xvzf make-3.81.tar.gz
     131cd make-3.81
     132./configure
     133sudo make install
     134hash -r
     135}}}
     136 * install Oracle Java6 (openjdk7 on BuilduntuVM needs to be downgraded for Android !KitKat builds):
     137{{{#!bash
     138sudo apt-get install oracle-java6-installer
     139}}}
     140 * install a couple other packages our BSP requires:
     141{{{#!bash
     142sudo apt-get install u-boot-tools uuid-dev liblzo2-dev
     143}}}
     144
     145
     146References:
     147 * https://source.android.com/source/building.html
     148 * https://source.android.com/source/initializing.html
     149
     150
     151[=#network]
     152=== Network Connection and Disk Space ===
     153The initial {{{repo sync}}} of Android transfers approximately 15GB of data from the Internet. This can take several hours depending on your bandwidth.
     154
     155While the source-code accounts for approximately 15GB of data, you will need an additional 25GB or so (40GB total) for a build.
     156
     157
     158[=#jdk]
     159=== JDK ===
     160Different versions of Android require different versions of a Java Development Kit (JDK). Note that multiple versions of Java can easily co-exist on an OS by using either a {{{JAVA_HOME}}} env variable pointing to the root of a JDK, or by using {{{Linux alternatives}}}. To avoid switching back and forth, Gateworks recommends setting a {{{JAVA_HOME}}} env variable.
     161
     162JDK Requirements:
     163 * Android Lollipop - OpenJDK 7:
     164  - Ubuntu >= 14.04:
     165{{{#!bash
     166sudo apt-get update
     167sudo apt-get install openjdk-7-jdk
     168export JAVA_HOME=/usr/lib/jvm/java-7-openjdk-amd64
     169}}}
     170 * Android Gingerbread through Kitkat: Oracle JDK 6:
     171  - Ubuntu 14.04/13.10:
     172{{{#!bash
     173# add the PPA with updated builds of Java 6JDK compatible with 13.10
     174sudo add-apt-repository ppa:webupd8team/java # hit enter when prompted
     175# install the package
     176sudo apt-get update && sudo apt-get install oracle-java6-installer # read and accept the license agreement
     177# verify the correct version is installed
     178java -version
     179 java version "1.6.0_45"
     180 Java(TM) SE Runtime Environment (build 1.6.0_45-b06)
     181 Java HotSpot(TM) 64-Bit Server VM (build 20.45-b01, mixed mode)
     182export JAVA_HOME=/usr/lib/jvm/java-6-oracle
     183}}}
     184
     185Note that you can have multiple JDK's installed at the same time and use 'update-alternatives' to configure which version of ''java'' and ''javac'' is used.
     186
     187References:
     188 * https://source.android.com/source/initializing.html#installing-the-jdk
     189
     190
     191[=#required-packages]
     192=== Packages ===
     193Ubuntu 14.04 (Note that most of these instructions were found [http://forum.xda-developers.com/showthread.php?t=2639611&page=1 here]):
     194{{{#!bash
     195sudo apt-get purge icedtea-\* icedtea6-\*
     196sudo apt-get install git gnupg ccache lzop flex bison gperf build-essential zip curl \
     197  zlib1g-dev zlib1g-dev:i386 libc6-dev lib32bz2-1.0 lib32ncurses5-dev x11proto-core-dev \
     198  libx11-dev:i386 libreadline6-dev:i386 lib32z1-dev libgl1-mesa-glx:i386 libgl1-mesa-dev \
     199  g++-multilib mingw32 tofrodos python-markdown libxml2-utils xsltproc libreadline6-dev \
     200  lib32readline-gplv2-dev libncurses5-dev bzip2 libbz2-dev libbz2-1.0 libghc-bzlib-dev \
     201  lib32bz2-dev squashfs-tools pngcrush schedtool dpkg-dev
     202sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so
     203sudo apt-get install u-boot-tools uuid-dev liblzo2-dev librsvg2-dev intltool mtd-utils pv
     204cpan App::cpanminus # type 'yes' to let it automatically choose settings for you
     205cpan Switch
     206}}}
     207
     208Ubuntu 13.10:
     209{{{#!bash
     210sudo apt-get install git-core lzop ccache gnupg flex bison gperf build-essential \
     211  zip curl zlib1g-dev zlib1g-dev:i386 libc6-dev lib32ncurses5 lib32z1 lib32bz2-1.0 \
     212  lib32ncurses5-dev x11proto-core-dev libx11-dev:i386 libreadline6-dev:i386 lib32z-dev \
     213  libgl1-mesa-glx:i386 libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown \
     214  libxml2-utils xsltproc readline-common libreadline6-dev libreadline6 lib32readline-gplv2-dev \
     215  libncurses5-dev lib32readline5 lib32readline6 libreadline-dev libreadline6-dev:i386 \
     216  libreadline6:i386 bzip2 libbz2-dev libbz2-1.0 libghc-bzlib-dev lib32bz2-dev \
     217  libsdl1.2-dev libesd0-dev squashfs-tools pngcrush schedtool libwxgtk2.8-dev \
     218  python gcc g++ cpp gcc-4.8 g++-4.8
     219sudo apt-get install u-boot-tools uuid-dev liblzo2-dev librsvg2-dev intltool mtd-utils pv
     220sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so
     221}}}
     222
     223Ubuntu 12.04:
     224{{{#!bash
     225sudo apt-get install git gnupg flex bison gperf build-essential \
     226  zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \
     227  libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \
     228  libgl1-mesa-dev g++-multilib mingw32 tofrodos \
     229  python-markdown libxml2-utils xsltproc zlib1g-dev:i386
     230sudo apt-get install u-boot-tools uuid-dev liblzo2-dev librsvg2-dev intltool mtd-utils pv
     231sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so
     232}}}
     233
     234
     235References:
     236 * https://source.android.com/source/initializing.html#setting-up-a-linux-build-environment
     237
     238
     239[=#source]
     240== Obtaining Source ==
     241Android AOSP (Android Open Source Project) source is spread across 300+ git repositories. The [https://source.android.com/source/developing.html 'repo' tool] is used as a front-end to git to manage working with all of these repos. A manifest file describes all the repos used, where they can be found, what branch to checkout, and where to check it out to in the resulting directory tree. A {{{repo sync}}} command is what fetches or updates all these repos and an initial sync will pull down approximately 15GB of data from the Internet.
     242
     243Of the roughly 334 various project trees that create Android, Freescale adds 13 new projects (for Freescale specific features/subsystems) and modifies 28 projects from upstream Android sources (to add support for Freescale features).
     244
     245
     246=== Access Control ===
     247Freescale has several projects and patches required for Android on the IMX6 CPU, some of which require a End User License Agreement (EULA). They distribute these as a tarball of patches which is difficult to work with, especially as Gateworks and our end users also apply patches on top of these to add functionality.
     248
     249Gateworks puts the projects that are not Open Source in a bitbucket account with access control. If you need to build and develop Android source for Ventana, you will need to contact support@gateworks.com requesting access to the gateworks-android bitbucket team. You will need to sign our EULA and provide an ssh public key ({{{~/.ssh/id_rsa.pub}}}) for each user and workstation you need access from. To learn how to generate an SSH key on your linux host see [https://confluence.atlassian.com/pages/viewpage.action?pageId=270827678 here]. You will want to create a key without a passphrase as the whole point of this key is to automate connection to the repo's without requiring entering a passphrase (if you are prompted for a passphrase each time you contact a repo the {{{repo}}} tool will get in the way of entering in the passphrase)
     250
     251Once you have confirmation from support@gateworks.com that we have added access for your ssh key(s) you need to do the following on your development host to add the bitbucket RSA key fingerprint to your development host so that you are not prompted for it during a {{{repo sync}}}:
     252{{{
     253#!bash
     254ssh-keyscan -H git.bitbucket.org >> ~/.ssh/known_hosts
     255}}}
     256
     257
     258[=#fetch]
     259=== Fetching Source ===
     260Once you have access to the private repositories (see [wiki:Android/Building#AccessControl above]) you can use the following steps to create a build directory for Android.
     261
     262Branches:
     263 * gateworks_l5.1.1_2.1.0-ga - Android Lollipop 5.1 (Latest Gateworks Android release)
     264 * gateworks_kk4.4.3_2.0.0-ga - Android !KitKat 4.4.3
     265 * gateworks_jb4.3_1.1.0-ga - Android Jelly Bean 4.3
     266
     2671. Create a directory for your Android build:
     268{{{#!bash
     269mkdir gateworks-android
     270cd gateworks-android
     271}}}
     272
     2732. Get {{{repo}}} tool. This tool uses xml manifests to pull down multiple repos:
     274{{{#!bash
     275curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ./repo
     276chmod a+x ./repo
     277}}}
     278
     2793. Initialize android source repo (this pulls down the manifest of projects that make up the Gateworks Ventana Android BSP):
     280{{{#!bash
     281./repo init -u https://github.com/Gateworks/imx_android.git -b gateworks_l5.1.1_2.1.0-ga
     282}}}
     283 * use any of the above branches if you wish to use an older release
     284 * repeat this with a different branch name any time you wish to change to a new branch without pulling down all the repo's again in their entirety
     285
     2864. (optional) pin the repo versions to the latest version which was known to have been successfully built by the Gateworks nightly build server:
     287{{{#!bash
     288wget http://dev.gateworks.com/android/lp-5.1.1/snapshot.xml # fetch the pinned manifest from the last successful nightly build
     289mv snapshot.xml .repo/manifest.xml # copy over the generic un-pinned manifest
     290}}}
     291 * the repo init command will fetch a repo 'manifest' which refers to various source repositories and branches but will fetch the latest changes from those branches. The Gateworks nightly build server posts the manifest pinned to the specific revision used in the build on completion of a successful build. You can also use a snapshot from a previously released pre-built binary by using the other snapshot files in ​http://dev.gateworks.com/android
     292
     2935. Sync repo - this fetches the repos from the Internet (may take a while to download sources resulting in about 15GB more):
     294{{{#!bash
     295./repo sync -c -j8
     296}}}
     297 * the {{{-c}}} parameter tells repo to only fetch the current branch specified in the project manifest and can help speed up fetching as well as reduce disk space needed
     298 * the {{{-j}}} parameter tells repo to use multiple processes (8 in this case) and can help speed up fetching
     299
     300Troubleshooting:
     301 * first, try {{{repo sync}}} again. Often temporary network congestion or outages may be the culprit.
     302  * Sometimes, a source destination may have change from the first {{{repo sync}}} you may have preformed. In this case, try {{{repo sync --force-sync}}} to force a sync to a new package location.
     303 * Bitbucket access issues:
     304  * if you see several '''Permission denied (publickey)''' errors then you have not been granted access to the Freescale proprietary repositories (see above)
     305  * if you see several '''The authenticity of host 'git.butbucket.org (131.103.20.168)' can't be established.''' messages then you have forgotten to add the bitbucket RSA key fingerprint to your development host (see above). Type 'yes' and hit return to add it permanently.
     306 * !VirtualBox VM issues:
     307  * when using a !VirtualBox VM the process hangs or fails with a variety of symptoms such as HTTP 500 errors. The default network behavior of !VirtualBox is to use NAT (Network Address Translation) to connect the guest system to the network and the heavy network activity of a repo sync triggers some corner cases in the NAT code. As a workaround configure !VirtualBox to use bridged network instead of NAT.
     308 * For various other network troubleshooting issues please see the official Android source download documentation [https://source.android.com/source/downloading.html here] and their known issues [https://source.android.com/source/known-issues.html#source-sync here]. Various issues that can be common are discussed there with workarounds:
     309  * behind a proxy or firewall - set HTTP_PROXY and HTTPS_PROXY and use a single thread ({{{repo sync -j1}}})
     310  * download failures (typically hangs or 406 errors) - disable tcp window scaling and/or use a single thread:
     311{{{#!bash
     312sudo sysctl -w net.ipv4.tcp_window_scaling=0
     313repo sync -j1
     314}}}
     315  * IP bandwidth exceeded (common if you try to {{{repo sync}}} a full tree more than once per day, or have multiple people/systems doing it behind a NAT firewall) - use authentication by [https://android.googlesource.com/new-password obtaining a password] and adding an '/a' path to the beginning of the URL to android.googlesource.com directory
     316
     317References:
     318 * https://source.android.com/source/developing.html
     319 * https://source.android.com/source/downloading.html
     320 * https://source.android.com/source/known-issues.html
     321 * https://udinic.wordpress.com/2014/05/24/aosp-part-1-get-the-code-using-the-manifest-and-repo/
     322
     323
     324[=#repo]
     325=== Keeping up to date and/or pinning source with repo ===
     326When building projects that use multiple source repositories any repository may change and thus make your working directory out of date. Because Android uses hundreds of projects with their own repositories this can make it difficult to keep in sync - this is where the {{{repo}}} tool comes in handy.
     327
     328The {{{repo sync}}} command will update all repositories with upstream changes:
     329{{{#!bash
     330repo sync --quiet
     331}}}
     332
     333You can override the default Manifest by using a '''local manifest''' if you want to keep in sync with the upstream manifest yet make some minor change like pin a specific project or add a couple of projects. Reasons for doing this could be:
     334 * adding new projects
     335 * pinning certain projects
     336 * removing certain projects
     337
     338To use a local manifest create {{{.repo/local_manifest.xml}}} and it will be merged with {{{.repo/manifest.xml}}} by the repo tool whenever the manifest is used. You can use the '''remove-project''' directive to remove a project that you don't want and even add it back with your own choices if you want something different. For example:
     339{{{#!xml
     340<?xml version="1.0" encoding="UTF-8"?>
     341<manifest>
     342   <remove-project path="hardware/qcom/display" name="CyanogenMod/android_hardware_qcom_display" />
     343   <project path="hardware/qcom/display" name="WinSuk/android_hardware_qcom_display" />
     344</manifest>
     345}}}
     346
     347The {{{repo manifest}}} command will create a snapshot of your current project's manifest allowing you to create a pinned version that can be used later to create a working directory with the various projects at the exact same state as your current working directory:
     348{{{#!bash
     349repo manifest -o snapshot.xml -r
     350}}}
     351
     352This snapshot can then be copied over .repo/manifest.xml in a different build directory to pin the repository sources.
     353
     354The Gateworks nightly build server creates a manifest snapshot like this and uploads the latest successful build to ​http://dev.gateworks/com/yocto so that it can be used to re-create a successful nightly build.
     355
     356References:
     357 * [https://source.android.com/source/using-repo.html Official docs on using repo]
     358 * [http://xda-university.com/as-a-developer/repo-tips-tricks xda-university repo tips and tricks]
     359 * [http://wiki.cyanogenmod.org/w/Doc:_Using_manifests Cyanogenmod docs on using manifests]
     360 * [https://gerrit.googlesource.com/git-repo/+/master/docs/manifest-format.txt repo Manifest Format: the official, technical documentation for repo manifests]
     361
     362
     363[=#build]
     364== Building ==
     3651. Configure Android build system for 'ventana' product and desired variant (See [#variants above] for differences on the {{{eng}}} vs {{{user}}} build variant)
     366{{{#!bash
     367export JAVA_HOME=/usr/lib/jvm/java-7-openjdk-amd64
     368source build/envsetup.sh
     369lunch ventana-eng
     370}}}
     371 * An 'eng' build (ventana-eng) has certain debug options enabled and lowers security (makes things nice if your going to play around)
     372 * A 'user' build (ventana-user) is more locked down and intended for a production/shipping environment
     373 * This process is sometimes referred to as 'activating the shell' and must be done for each new shell (ie each time you login or open a new terminal). If this seems strange to you or if you are new to Linux build systems, you should probably only use a single shell to avoid confusion.
     374
     3752. Build (takes up an additional ~25GB and takes several hours)
     376{{{#!bash
     377make 2>&1 | tee build.log
     378}}}
     379
     380When complete the various build artifacts will be in {{{out/target/product/ventana/}}}
     381
     3823. Put artifacts onto a storage device to boot. See next section using the 'mksdcard.sh' script. The following build artifacts are in {{{out/target/product/ventana/}}} grouped by the partition they belong in:
     383 * BOOT:
     384  * uImage - kernel image
     385  * boot/boot/uramdisk.img - initial ramdisk containing init system
     386  * boot/boot/6x_bootscript-ventana - u-boot bootscript (sets up android kernel cmdline)
     387  * boot/boot/uImage - kernel image
     388  * boot/boot/*.dtb - kernel device tree binary blobs
     389 * RECOVER:
     390  * ramdisk-recovery.img - initial ramdisk containing init system
     391 * SYSTEM:
     392  * system.img - filesystem image of /system directory (Android ROM)
     393 * USER:
     394  * userdata.img - user data
     395
     396Note that the Android partition layout we use requires 8 partitions which are typically not supported with built-in SDIO host controllers based on standard kernel configurations (which is what you are using if your microSD shows up as /dev/mmcblk*). We recommend using a USB based microSD card reader/writer which can be found from office supply stored for under $5.
     397
     398
     399[=#create-tarball]
     400=== Creating a tarball of the built artifacts ===
     401
     402If you would like to create an archive of the build artifacts including everything needed to image Android onto a removable block storage device as well as the NAND uib, the following will do so:
     403{{{#!bash
     404tar -cvjf l5.1.1_2.1.0-ga.tar.bz2 \
     405  --transform "s,^device/gateworks/ventana/,l5.1.1_2.1.0-ga/," \
     406  --transform "s,^out/target/product/ventana/,l5.1.1_2.1.0-ga/," \
     407  device/gateworks/ventana/mksdcard.sh \
     408  out/target/product/ventana/boot \
     409  out/target/product/ventana/uramdisk-recovery.img \
     410  out/target/product/ventana/userdata.img \
     411  out/target/product/ventana/system.img \
     412  out/target/product/ventana/android.ubi
     413}}}
     414
     415Untaring the above archive would show:
     416{{{#!bash
     417tar xvf ../l5.1.1_2.1.0-ga.tar.bz2
     418l5.1.1_2.1.0-ga/mksdcard.sh
     419l5.1.1_2.1.0-ga/boot/
     420l5.1.1_2.1.0-ga/boot/boot/
     421l5.1.1_2.1.0-ga/boot/boot/imx6dl-gw54xx.dtb
     422l5.1.1_2.1.0-ga/boot/boot/imx6dl-gw53xx.dtb
     423l5.1.1_2.1.0-ga/boot/boot/imx6dl-gw52xx.dtb
     424l5.1.1_2.1.0-ga/boot/boot/imx6dl-gw51xx.dtb
     425l5.1.1_2.1.0-ga/boot/boot/imx6dl-gw551x.dtb
     426l5.1.1_2.1.0-ga/boot/boot/imx6dl-gw552x.dtb
     427l5.1.1_2.1.0-ga/boot/boot/imx6q-gw54xx.dtb
     428l5.1.1_2.1.0-ga/boot/boot/imx6q-gw53xx.dtb
     429l5.1.1_2.1.0-ga/boot/boot/imx6q-gw52xx.dtb
     430l5.1.1_2.1.0-ga/boot/boot/imx6q-gw51xx.dtb
     431l5.1.1_2.1.0-ga/boot/boot/imx6q-gw551x.dtb
     432l5.1.1_2.1.0-ga/boot/boot/imx6q-gw552x.dtb
     433l5.1.1_2.1.0-ga/boot/boot/uImage
     434l5.1.1_2.1.0-ga/boot/boot/6x_bootscript-ventana
     435l5.1.1_2.1.0-ga/boot/boot/uramdisk.img
     436l5.1.1_2.1.0-ga/uramdisk-recovery.img
     437l5.1.1_2.1.0-ga/userdata.img
     438l5.1.1_2.1.0-ga/system.img
     439l5.1.1_2.1.0-ga/android.ubi
     440}}}
     441
     442
     443[=#rebuild]
     444== Updating and Re-building ==
     445From time to time you may want to refresh your sources with upstream changes from Gateworks and elsewhere. The Gateworks Android BSP manifest file fetched from the {{{repo init}}} command controls what projects get fetched and where they go. The {{{repo sync}}} command with both update the manifest (in case projects have been added, removed, or changed) and updates all the individual git repos it references.
     446{{{#!bash
     447./repo sync --quiet
     448}}}
     449 * The quiet flag reduces most of the output allowing you to easily progress
     450 * This only pulls down 'changes' that have been made
     451 * As this alters source-code, do not do this while a build is running
     452
     453Now you can repeat the steps above to rebuild. You do not need to do a {{{make clean}}}.
     454
     455
     456[=#install]
     457== Flashing Android to NAND Flash ==
     458If you have a board with 2GB NAND Flash, you can use the {{{nand_update}}} uboot script to flash the Android ubi file from a tftp server.
     459
     460First you must copy the ubi from your build directory to your tftp server root directory:
     461{{{#!bash
     462cp out/target/product/ventana/android.ubi /tftpboot
     463}}}
     464
     465The nand_update script will tftp the file file represented by the {{{image_rootfs}}} env variable from the server represented by the {{{serverip}}} env variable and flash it to the rootfs partition:
     466{{{#!bash
     467setenv image_rootfs android.ubi
     468run nand_update
     469reset
     470}}}
     471
     472
     473== Creating a bootable removable storage device ==
     474You can create a bootable removable storage device (micro-SD / USB stick / mSATA disk) with the mksdcard.sh script (located in {{{device/gateworks/ventana/mksdcard.sh}}} of the source directory). Assuming the removable device is in {{{/dev/sdc}}} on your linux host '''(this is an assumption here - please verify on your system with something like the 'Disks' tool on Ubuntu)''':
     475{{{#!bash
     476sudo device/gateworks/ventana/mksdcard.sh /dev/sdc
     477}}}
     478 * Note that sanity checks are done to ensure the device specified appears to be removable by checking its size. If you get an 'invalid disk' error because of this and want to force the script you can execute it as:
     479{{{#!bash
     480sudo device/gateworks/ventana/mksdcard.sh /dev/sdc ventana --force
     481}}}
     482 * If using an archive of build artifacts you will find the mksdcard.sh script in the root directory and can run it from there
     483
     484Notes:
     485 * you must have a device of 2GB or larger
     486
     487Booting:
     488 * Please see [wiki:Android/Booting here] for important instructions on booting Android from removable media