Android developer codelab

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

Although the path is challenging, the Android team strives to simplify your journey, every release. And the team makes improvements every day through 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:

To give you a small taste of what the developer workflow is like for Android engineers working on the platform (the operating system).
Encourage you to provide feedback around Android's tools, documentation, and the developer workflow.

Prerequisites

The list of requirements for this codelab are derived from those for general platform (AOSP) development. To take this codelab, set up the following:

Physical Linux workstation meeting all public requirements.
Repo and the Git configuration required to edit the Android codebase.

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 rerun them in each terminal session. Specifically, these include the source build/envsetup.sh and lunch commands.

Set up workstation

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

Initialize and sync the code

Navigate into your home directory:
```
cd ~
```
Create a local working subdirectory within it:
```
mkdir aosp
```
Navigate into the directory:
```
cd aosp
```
Initialize the AOSP repository source code main branch (the default):
```
repo init -u https://android.googlesource.com/platform/manifest
```
Enter or accept your Git credentials (name, email address).
Sync the source code:
```
repo sync -j8
```

Initial syncs can take an hour or more.

Each repo checkout is represented by a manifest file. It's permissable to have more than 1 repo checkout at a time, so long as they exist in distinct directories. But note that each checkout and build amounts to roughly 300 GB usage (and growing), so either limit yourself to 2 repo checkouts, or augment your system with a secondary drive.

TIP: To increase free space, delete a branch directory and start anew from directory creation, like this: rm -rf aosp2.

Build the code

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

The device target aosp_cf_x86_64_phone-userdebug allows you to build the Cuttlefish virtual Android device for testing without a physical device.

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

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
```
Pass the build target to the lunch command, like this:
```
lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
```
Build the code from anywhere in your checkout with:
```
m
```

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

Launch Cuttlefish

Cuttlefish is the Android emulator used to test your builds.

If you've never installed Cuttlefish, you must install the necessary Cuttlefish dependencies. In a terminal window, run the following commands to download, build, and install the host Debian packages:

sudo apt install -y git devscripts equivs config-package-dev debhelper-compat golang curl
git clone https://github.com/google/android-cuttlefish
cd android-cuttlefish
for dir in base frontend; do
pushd $dir
# Install build dependencies
sudo mk-build-deps -i
dpkg-buildpackage -uc -us
popd
done
sudo dpkg -i ./cuttlefish-base_*_*64.deb || sudo apt-get install -f
sudo dpkg -i ./cuttlefish-user_*_*64.deb || sudo apt-get install -f
sudo usermod -aG kvm,cvdnetwork,render $USER
sudo reboot

The reboot triggers installing additional kernel modules and applies udev rules.

Launch Cuttlefish:
```
launch_cvd --daemon
```
Connect to the Cuttlefish device by navigating to https://localhost:8443 in your web browser. You are greeted with a video stream of the Android-powered device you just built.

Make a change

Update the source code following this example changelist.

From the root of your checkout (aosp/ directory), navigate to the frameworks/native Git project:
```
cd frameworks/native
```
Start a temporary project with this command:
```
repo start <some-name> .
```
Edit SurfaceFlinger.cpp to include the updates from the changelist at the following location:
```
aosp/frameworks/native/services/surfaceflinger/SurfaceFlinger.cpp
```

Find this line:

void SurfaceFlinger::updateColorMatrixLocked() {

Add these two lines at the start of updateColorMatrixLocked():

mClientColorMatrix = mat4(vec4{1.0f, 0.0f, 0.0f, 0.0f}, vec4{0.0f, -1.0f, 0.0f, 0.0f},
                          vec4{0.0f, 0.0f, -1.0f, 0.0f}, vec4{0.0f, 1.0f, 1.0f, 1.0f});

Build the code:
```
m
```

Update the build on the device:

adb root
adb remount
adb sync
adb reboot

Verify that you see a color change on your selected device similar to what shows in Figure 1.

Example of a successful color change

Figure 1. Screen appearance after successful color change

Test your code

This portion of the codelab utilizes an example test that's in the source tree and is failing. This employs Atest for running the test locally and testing the code.

To use the test, follow these instructions:

Run:
```
atest DevCodelabTest
```

The test will fail. Examine the stack trace of the failing test:

STACKTRACE:
java.lang.AssertionError
 at org.junit.Assert.fail(Assert.java:87)
 at org.junit.Assert.assertTrue(Assert.java:42)
 at org.junit.Assert.assertTrue(Assert.java:53)
 at android.test.example.devcodelab.DevCodelabTest.testHelloWorld(DevCodelabTest.java:29)

Then look here

platform_testing/tests/example/devcodelab

To get the file to edit, take the name of the test in android.test.example.devcodelab.DevCodelabTest and replace the . with /, to get this result:
```
src/android/test/example/devcodelab/DevCodelabTest.java
```

Then edit

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

to replace

Assert.assertTrue(false)

with

Assert.assertTrue(true)

Run the test again to verify you fixed the issue:
```
atest DevCodelabTest
```

Upload your code for review

Repo simplifies Git usage 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.

For code review of your projects in Git, you'll use the Gerrit web-based code review system.

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
```
For your commit message, enter the following:
```
Android codelab change
Test: manual atest
```
Upload your change:
```
repo upload
```

If you're successful, you see a message resembling this one:

Upload project frameworks/native/ to remote branch main:
  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/main

View your change in Gerrit

Go to the link, printed in the terminal, that resembles this one:

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 for full details on developing Android, see the rest of this site.

Revert your change

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

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

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

repo abandon codelab .

Remember also to revert the changes you made to the test file. Since you didn't repo start, git commit, and repo upload the change, you can reset the file itself. Assuming you're in the aosp/platform_testing directory, use the following to reset the file:

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

At this point, you're done! Nice work!

Get help

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