README.md
1# Robolectric build-android.sh tutorial
2
3**Note:** Based on [Android documentation](https://source.android.com/source/downloading.html).
4
5This tutorial will allow you to run the `build-android.sh` script in the Robolectric repository, resulting in the corresponding Android version's android-all jar.
6
7## 1. Installing Repo
8Repo is a tool that makes it easier to work with Git in the context of Android. For more information about Repo, see the Developing section.
9
10To install Repo make sure you have a bin/ directory in your home directory and that it is included in your path:
11```
12$ mkdir ~/bin
13$ PATH=~/bin:$PATH
14```
15
16Download the Repo tool and ensure that it is executable:
17```
18$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
19$ chmod a+x ~/bin/repo
20```
21
22## 2. Initializing a Repo client
23After installing Repo, set up your client to access the Android source repository:
24
25Create an empty directory to hold your working files. If you're using MacOS, this has to be on a case-sensitive filesystem. Give it any name you like:
26```
27$ mkdir <WORKING_DIRECTORY>
28$ cd <WORKING_DIRECTORY>
29```
30
31Configure git with your real name and email address. To use the Gerrit code-review tool, you will need an email address that is connected with a [registered Google account](https://myaccount.google.com/?pli=1). Make sure this is a live address at which you can receive messages. The name that you provide here will show up in attributions for your code submissions.
32```
33$ git config --global user.name "Your Name"
34$ git config --global user.email "you@example.com"
35```
36
37## 3. Grab dependencies
38On Ubuntu run
39```
40$ sudo apt-get install git-core gnupg gnupg-agent flex bison gperf build-essential \
41zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 \
42lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z-dev ccache \
43libgl1-mesa-dev libxml2-utils xsltproc unzip libswitch-perl
44```
45
46## 4. Run sync-android.sh to sync and build source
47Now use repo to sync the android source, and then build.
48
49```
50./sync-android.sh <root source location> <android version> <# parallel jobs>
51```
52
53The currently supported Android versions are:
54
55* `4.1.2_r1` - Jelly Bean API 16
56* `4.2.2_r1.2` - Jelly Bean MR1 API 17
57* `4.3_r2` - Jelly Bean MR2 API 18
58* `4.4_r1` - Kit Kat API 19
59* `5.0.2_r3` - Lollipop API 21
60* `5.1.1_r9` - Lollipop MR1 API 22
61* `6.0.1_r3` - Marshmallow API 23
62* `7.0.0_r1` - Nougat API 24
63* `7.1.0_r7` - Nougat MR1 API 25
64* `8.0.0_r4` - Oreo API 26
65
66Beware it can take upwards of 100 GB of space to sync and build.
67
68For more infomation see [Downloading and Building](https://source.android.com/source/requirements)
69
70Choose a <# parallel jobs> value roughly equal to # of free cores on your machine. YMMV.
71
72
73## 7. Run build-android.sh
74
75Signing Artifacts:
76The end of the script will prompt you to sign the new artifacts using GPG. See [Performing a Release](https://github.com/robolectric/robolectric-gradle-plugin/wiki/Performing-a-Release) for instructions on obtaining a GPG key pair.
77
78(Optional) You will be prompted a total of 4 times (once for each artifact). To make this easier, run this command beforehand:
79```
80$ gpg-agent --daemon
81```
82
83Finally, in your Robolectric directory run:
84```
85$ export SIGNING_PASSWORD=<Passphrase for GPG signing key>
86$ build-android.sh <Path to AOSP source directory> <android version> <robolectric sub-version>
87```
88
89For Robolectric version `6.0.1_r3-robolectric-0`, android version would be `6.0.1_r3` and robolectric sub-version `0`.
90