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.
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.
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 code base.
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
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:
Create a local working subdirectory within it:
Navigate into the directory:
Initialize the AOSP repository source code master 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. See the downloading instructions for related details while you wait.
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 free-up space, delete a branch directory and start anew from directory creation, as shown here:
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 included below,
aosp_cf_x86_64_phone-userdebug, enables 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:
Pass the build target to the lunch command, like this:
Build the code from anywhere in your checkout with:
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're in the same terminal session used to build the code,
proceed. Otherwise, rerun the
envsetup.sh script and the same
you used there first. Then
Create an Acloud local instance with:
acloud create --local-image --local-instance
Accept updates to required packages.
If prompted, restart your workstation, for all changes to take effect.
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 can also follow the activity within the logs while you use
your device by employing the Android Debug Bridge (adb)
Make a change
Update the source code following this example changelist.
From the root of your checkout (
aosp/directory), navigate to the
Start a temporary project with this command:
repo start <some-name> .
SurfaceFlinger.cppto include the updates from the changelist at the following location:
Add the following beneath the line of code you just included:
Build the code:
Update the build on the device:
adb root adb remount adb sync adb reboot acloud reconnect
Verify that you see a color change on the device.
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:
The test will fail. To fix it, find the source code of the failing test:
atest --info android.test.example.devcodelab.DevCodelabTest#testHelloWorld
Then look here
To get the file to edit, take the name of the test in
android.test.example.devcodelab.DevCodelabTestand replace the
/, to get this result:
Run the test again to verify you fixed the issue:
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/nativeproject, 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:
If you're successful, you see a message resembling this:
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 that resembles this one:
This completes the starter codelab for Android platform development. See Submitting Patches for next steps, and see the rest of this site for full details on developing Android.
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
directory (or its subdirectories):
repo abandon codelab .
Remember also to revert the changes you made to the test file. Since you didn't
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!