Google is committed to advancing racial equity for Black communities. See how.

Android Developer Codelab

You can help develop the most widely installed operating system in the history of Earth. Yes, you are here to embark upon the journey of becoming an Android platform engineer.

Although the path is challenging, we the Android team strive to simplify your journey every release. And we make improvements every day via direct work in the Android Open Source Project (AOSP).

So sit back, fire up a terminal, and let's make history.

Goals

The mission of this codelab is twofold:

  1. This codelab will give you a small taste of what the developer workflow is like for Android engineers working on the platform (operating system).
  2. This codelab is a forcing function for you to provide feedback around Android's tools, documentation and the developer workflow when starting from scratch.

Prerequisites

Here is the complete list of requirements for this codelab, derived from those for general platform (AOSP) development.

To take this codelab, you will need to set up:

Environment

Typically, users build and develop on the workstation directly. Because you may be working in various terminals, and many of the commands used are terminal-specific, you will need to re-run them in each terminal session. Specifically, these include the source build/envsetup.sh, and lunch commands.

Set up workstation

  1. Install the necessary packages on the workstation.
  2. While still in a terminal, install Repo and gain credentials to all Git repositories.

Initialize and sync the code

  1. Navigate into your home directory:

    cd ~
    
  2. Create a local working subdirectory within it:

    mkdir aosp
    
  3. Navigate into the directory:

    cd aosp
    
  4. Initialize the AOSP repository source code master branch (the default):

    repo init -u https://android.googlesource.com/platform/manifest
    
  5. Enter or accept your Git credentials (name, email address).

  6. Sync the source code:

    repo sync -j16
    

Initial syncs can take an hour or more. See the downloading instructions for related details while you wait.

Each repo checkout is represented by a manifest file. You may have more than one repo checkout at a time so long as they exist in distinct directories. But note each checkout and build amounts to roughly 300GB and growing, so limit yourself to two or augment your system with a secondary drive.

Tip: To free up space, delete a branch directory and start anew from directory creation:

rm -rf aosp2

Build the code

To build Android, you must select a target device type to build with the lunch command. Targets are device permutations, such as a specific model or form factor.

The device target included below, aosp_cf_x86_phone-userdebug, enables you to build the Cuttlefish virtual Android device for testing without a physical device.

To instead build and update a physical device, choose another target and follow the instructions for flashing devices.

  1. Set up your environment for building Android devices by running the following command from the root of your source code checkout:

    source build/envsetup.sh
    
  2. Pass the build target to the lunch command, like so:

    lunch aosp_cf_x86_phone-userdebug
    
  3. Build the code from anywhere in your checkout with:

    m
    

Expect the first build to take hours. Subsequent builds take significantly less time.

Create Acloud instance

Acloud is a command line tool in AOSP that assists users in creating virtual Android devices, in this case Cuttlefish.

If you are in the same terminal session used to build the code, proceed. Otherwise, re-run the envsetup.sh script and same lunch command used there first. Then:

  1. Create an Acloud local instance with:

    acloud create --local-image --local-instance
    
  2. Accept updates to required packages.

  3. If prompted, restart your workstation for all changes to take effect.

  4. Select the Cuttlefish device.

You should be greeted with a VNC session containing an Android device!

You can interact with the virtual device on your workstation using your mouse and keyboard. You may also follow the activity within the logs while you use your device with the Android Debug Bridge (adb) logcat command:

adb logcat

Make a change

Update the source code following this example changelist.

  1. From the root of your checkout (aosp/ directory), navigate to the frameworks/native Git project:

    cd frameworks/native
    
  2. Start a temporary project with:

    repo start <some-name> .
    
  3. Edit SurfaceFlinger.cpp to include the updates from the changelist at the following location:

    aosp/frameworks/native/services/surfaceflinger/SurfaceFlinger.cpp
    
  4. Build the code:

    m
    
  5. Update the build on the device:

    adb root
    adb remount
    adb sync
    adb reboot
    acloud reconnect
    

You should see a color change on the device.

Test your code

During this portion of the codelab we will run through an example test that is in the source tree and is already failing. In order to run the test locally we will use Atest to test the code.

To use the test:

  1. Run:

    atest DevCodelabTest
    
  2. The test will fail; now let's fix it! Find the source code of the failing test:

    atest --info android.test.example.devcodelab.DevCodelabTest#testHelloWorld
    
  3. Then look within:

    platform_testing/tests/example/devcodelab
    
  4. For the file to edit, take the name of the test and replace the . with /, like so:

    android.test.example.devcodelab.DevCodelabTest
    

    Becomes:

    src/android/test/example/devcodelab/DevCodelabTest.java
    
  5. Thus edit:

    platform_testing/tests/example/devcodelab/src/android/test/example/devcodelab/DevCodelabTest.java
    

    To replace:

    Assert.assertTrue(false)
    

    With:

    Assert.assertTrue(true)
    
  6. Run the test again to verify you fixed the test:

    atest DevCodelabTest
    

Upload your code for review

Repo simplifies use of Git by bundling commands such as git clone to work across numerous Git repositories (or projects) at once.

See Source Control Tools for overviews of Git and Repo with links to full documentation on working with Android source code. See the AOSP repository for the full list of Git projects and the individual projects (paths) for branches associated with each project.

You will be using the Gerrit web-based code review system for projects in Git.

  1. Assuming you made your changes in the frameworks/native project, run these commands to upload them:

    cd frameworks/native
    repo start codelab .
    git add .
    git commit
    
  2. For your commit message enter:

    Android codelab change
    Test: manual atest
    
  3. Upload your change:

    repo upload
    

If you are successful, you will see a message resembling:

Upload project frameworks/native/ to remote branch master:
  branch codelab ( 1 commit, Wed Aug 7 09:32:33 2019 -0700):
         ff46b36d android codelab change
to https://android-review.googlesource.com/ (y/N)? y
remote: Processing changes: refs: 1, new: 1, done
remote:
remote: SUCCESS
remote:
remote:   https://android-review.googlesource.com/c/platform/frameworks/native/+/1098432 android codelab change [NEW]
remote:
To https://android-review.googlesource.com/platform/frameworks/native
 * [new branch]          codelab -> refs/for/master

View your change in Gerrit

Go to the link printed in the terminal resembling:

https://android-review.googlesource.com/c/platform/frameworks/native/+/1098432

This completes the starter codelab for Android platform development. See Submitting Patches for next steps and the rest of this site for full details on developing Android.

Revert your change

Normally, post testing and review/approval, you would submit your change in Gerrit and merge it into the repository.

Instead, for the purposes of the codelab, revert your changelist by clicking Abandon in Gerrit.

Then abandon the associated temporary branch in the frameworks/native project directory (or its subs):

repo abandon codelab .

Remember also to revert the changes to the test file. Since we did not repo start, git commit, and repo upload the change, we can merely reset the file itself, like so (assuming you are in the aosp/platform_testing directory):

git reset HEAD tests/example/devcodelab/src/android/test/example/devcodelab/DevCodelabTest.java
git checkout .

At this point, you are done! Nice work!

Get help

If you encounter errors during this codelab, please report them using the Site feedback link on the bottom of any page. Send questions to the android-building group.