Jump to: navigation, search

Build Instructions

Revision as of 04:04, 23 March 2016 by AdminTeam (talk | contribs) (Swap and RAM clarifications)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Console OS > Wiki > Source Code > Build Instructions

To build Console OS with Android, we recommend matching our build environment. Today we rely on building Console OS via Ubuntu 15.10 with a 64-bit x86 processor. Building with a 32-bit version of Ubuntu is unlikely to work.

More RAM is better - at least 4GB should be used, and 8GB is strongly recommended. If building with multiple cores, you should plan on at least 8GB of RAM. We recommend at least a 10GB swap file. For faster build times, we also encourage you to use an solid-state drive - building Android with a traditional hard disk has become very slow.

You probably can build Console OS with most popular Linux distributions, but we only test the build guide with the configuration described above. Building Console OS on OS X is planned and possible, but not supported at this time.

Note: This guide is designed to be omni-platform for Android. It should properly build Console OS with Android, Android-IA, Android-x86.org, and AOSP trunk for both Lollipop (5.0 & 5.1) as well as Marshmallow (6.0). If it doesn't, please let us know.

Generally, build steps below in italics are commands you should enter into a terminal or shell, or raw text you should add to a file when appropriate.

Configuring Build Environment

Installing Packages

  • For starters, run Ubuntu Software Update until it reports no updates available.
  • Then, run the following commands to add support for multi-arch building, and add additional required build components:
    • sudo dpkg --add-architecture i386
    • sudo apt-get update
    • sudo apt-get install git-core gnupg flex bison gperf build-essential bison zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z-dev ccache libgl1-mesa-dev libxml2-utils xsltproc unzip gperf libxml2-utils dos2unix zlib1g:i386 ccache dosfstools python-dev python-pip libyaml-dev
  • Restart the computer.
  • Run the following command to enable some python build steps.
    • sudo pip install prettytable Mako pyaml dateutils --upgrade

Enabling CCache

  • We recommend enabling ccache - It is not required, but will speed up incremental builds significantly.
  • Create a file ~/.bashrc (or edit it, if it already exists).
    • Edit the file and add the following:
      • export USE_CCACHE=1
    • If you are using a single disk drive, you don't need to define the ccache directory - however if you have multiple drives, moving the ccache to another drive may be beneficial. For example, if your OS install drive is a HDD, and your build drive is a SSD, you will probably want to move your ccache folder from your home drive, to the SSD.
    • To do so, edit the .bashrc file to add the following:
      • export CCACHE_DIR=(insert path here)
      • Also, be sure to create a directory at that location. If you do not, the build will fail. CCache will only make the default directory ~/.ccache automatically.
  • Note: CCache is required for Android-IA kernel builds. As such we have listed it in the required packages, in the first portion of the build guide.
    • If you are not building Android-IA or Intel kernels, and do not wish to use ccache, you can remove ccache from the first portion of the build guide.

Installing OpenJDK

Android versions prior to Lollipop were built using the Sun/Oracle JDK. However, Google switched to OpenJDK for Lollipop, which is easier to install and set up.

Start by installing OpenJDK 7. We do not support JDK 8+ though some have noted stable building with it. Also OpenJDK 6 is not supported for versions prior to Lollipop, either. We recommend doing this separately than the rest of the installs.

  • sudo apt-get install openjdk-7-jdk
  • We recommend you restart the computer again, this avoids some situations where java defaults may not have set.
  • Once rebooted, check your java versions to make sure java & javac have accepted the OpenJDK installation.
    • java -version
    • javac -version
    • Make sure java reports 1.7 and confirms OpenJDK, and that javac reports version 1.7.
  • Note: If you have previously installed Sun/Oracle JDKs, or another OpenJDK generation, you may need to manually update the defaults. Android will only build properly if the versions in the above test are properly set. See other guides for how to do this.

Configuring GCC

By default, Ubuntu should use GCC for compiling C/C++ code. However, in some cases, Clang or another compiler may be the default.

This will cause building Console OS to fail. To resolve this, we need to configure GCC as the default from the terminal/shell:

  • sudo -l
  • sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-5 100
  • Edit your ~/bash.rc file and add the following:
    • export CXX=/usr/bin/gcc-5
  • Restart your computer
  • Finally run update-alternatives --query gcc
    • Confirm GCC is now the default compiler

Thanks to community member Robert Crawford for adding this step.

Configuring Repo & Git

Repo is the tool created by Google to manage the numerous Git repositories that make up the Android Open Source Project. Even if you do not plan to contribute code upstream, you need to configure both tools properly, in order to maintain the code base.


  • The only required Git configuration is defining a username and email address. If you are concerned about privacy, just use placeholders. Note that any code you push will reflect these names, unless changed later.
    • git config --global user.name “(Insert Name here)”
    • git config --global user.email “(Insert valid email address here)”
    • Note the double quotation marks around both name and email fields. This allows for apostrophes in names to be used.


  • First we need to download and install Repo from Google. Repo is an advanced script that usually should automatically update itself. We recommend following Google's steps to deploy repo in your home folder, as described in these commands:
  • Next we need to properly add the path to your .bashrc file, so that invoking repo can be done without manually typing in the location each time the command is needed.
    • To do this, open your .bashrc file in a text editor, and add the following:
      • export PATH=$PATH:~/bin
  • Note that due to file permissions, Repo may not be able to update itself automatically. It will still check for new versions and notify you when it is run - with instructions on how to manually update.

Downloading Source Code

Now that you have configured your build environment, it's time to download the source code.

  • Start with creating a new directory to download the source code into, for example:
    • mkdir ~/console-os-github
    • cd ~/console-os-github
  • Next run repo using the target operating system. For Console OS Lollipop, you would enter the following:
    • repo init -u https://github.com/iConsole/Console-OS -b consoleos-lollipop
      • The -b command triggers designation of the target branch. If one is not designated, most distributions will work with the master branch, which usually is the latest development build. It may or may not be stable, but most Android distributions maintain buildability even with the master tree.
    • To change between branches in the future, simply run repo init again, with the new branch in the -b command.
  • Next run repo sync to trigger a pulldown of the code:
    • repo sync -j4
      • The -j4 command triggers four concurrent sessions. This is useful to maximize bandwidth, but may cause issues. If you experience repo errors, continue to re-run the command, but remove the -j4 part.

After this completes, you may want to verify that the download was successful later. You can run repo sync again to pull down the latest code, but this may also remove any changes you've made to the code.

  • To verify a repo without modifying the downloaded branch, run the following command: "nothing to commit (working directory clean)"
    • repo status
  • You will either see a list of differences, or the following message:

Optimizing CCache After Source Download

After downloading the Android distribution, we need to increase the CCache from its default (1GB) to something larger. Generally, Google recommends between 50GB and 100GB for your CCache. Make sure you have significantly more free disk space than what you define your CCache, as building will also use dozens of gigabytes of space.

  • Run the following command to increase your CCache
    • cd ~/console-os-github (replace this path with wherever you initiated your repo and synced it)
    • prebuilts/misc/linux-x86/ccache/ccache -M 100G

Obviously, if you are not using CCache, this will not do anything. If you are using ccache, this step is extremely important. You also should remember to re-run this when doing a clean resync. Forgetting to do this step routinely happens to the best of us... we're considering making it the default in Console OS in the future.

Running A Build

Now you should be all set to build Console OS, or another Android distribution.

  • Start by opening the directory you ran repo sync on
    • cd ~/console-os-github
  • Next run the following command to configure the build environment
    • source build/envsetup.sh
  • You next need to select a target device to build, run the following command:
    • lunch
  • A list of devices will appear. On Console OS, we respect the -eng -userdebug -user build options.
    • -eng means an engineering build. This has additional log settings and is often rooted for easier debugging.
    • -userdebug is more often reserved for betas and seed builds to external testers. It often parallels -eng but may not always be rooted. It may also have less logging.
    • -user is reserved for release builds. It should not be rooted, unless specifically modified for a purpose-build edition.
    • Select the device target and build options that best suit your needs. Enter the number next to the build, and hit enter.
  • You are now set to run the build. Run the following command:
    • make efi_img -jN
      • Replace N with the number of logical cores you have on your system. If builds fail, you may want to reduce this to -j1 as your machine may have run out of memory. Unfortunately, due to the many build tools AOSP uses, it does not always clearly state to the builder, that the machine ran out of memory.
      • For example, an Intel i5-4790K processor has four cores, and four additional hyperthreading (logical) cores. If you have sufficient memory, you would want to use -j8 for that processor. Do not exceed the total number of cores and hypertreads that your processor supports... it will greatly slow the build process.

The make command has numerous options, depending on the Android rendition. For example, Android-IA uses options like flashfiles to designate an update image. Console OS today is a fork of Android-x86.org and inherits the iso_img (BIOS) and efi_img (UEFI) build targets. Today, we only support efi_img on Console OS.

When the build finishes, you should find build files in the ~/console-os-github/out/target/ directory - using the example directories above.

Congratulations, if successful, you have just set up your build environment, and completed your first build of Console OS with Android!

Usually, you will have a .img file that you can flash. Graphically, you can use Ubuntu's Disks app to restore this disk image to a flash drive. Connect a flash drive, and select it in the Disks app. Then, proceed to pressing the wheel button in the top-right corner of the app. Finally, select Restore Disk Image. Navigate to the path of the .img file, and select it. Note that all contents on the flash drive you have connected, will be erased.