Google Git
Sign in
android / platform / docs / source.android.com / ab0c83d9892fcee2bea15ef91167996378b3ba79 / . / en / source / initializing.html
blob: 430bb4b011c294d0b84797637f82b6a3d5c85bbd [file] [log] [blame]
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]1<html devsite>
2 <head>
3 <title>Establishing a Build Environment</title>
4 <meta name="project_path" value="/_project.yaml" />
5 <meta name="book_path" value="/_book.yaml" />
6 </head>
7 <body>
8 <!--
9 Copyright 2017 The Android Open Source Project
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]10
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]11 Licensed under the Apache License, Version 2.0 (the "License");
12 you may not use this file except in compliance with the License.
13 You may obtain a copy of the License at
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]14
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]15 http://www.apache.org/licenses/LICENSE-2.0
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]16
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]17 Unless required by applicable law or agreed to in writing, software
18 distributed under the License is distributed on an "AS IS" BASIS,
19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20 See the License for the specific language governing permissions and
21 limitations under the License.
22 -->
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]23
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]24<p>This section describes how to set up your local work environment to build
25the Android source files. You will need to use Linux or Mac OS. Building under
26Windows is not currently supported.</p>
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]27<p>For an overview of the entire code-review and code-update process, see <a
28href="life-of-a-patch.html">Life of a Patch</a>.</p>
Android Partner Docscb2b2fc2017-06-23 13:18:39 -0700[diff] [blame]29<p class="note"><strong>Note:</strong> All commands in this site are preceded
30by a dollar sign ($) to differentiate them from output or entries within files.
31You may use the <em>Click to copy</em> feature at the top right of each command
32box to copy all lines without the dollar signs or triple-click each line to
33copy it individually without the dollar sign.</p>
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]34<h2 id="choosing-a-branch">Choosing a Branch</h2>
Robert Ly40e3b6d2013-04-17 18:12:10 -0700[diff] [blame]35<p>Some of the requirements for your build environment are determined by which
36version of the source code you plan to compile. See
37<a href="build-numbers.html">Build Numbers</a> for a full listing of branches you may
38choose from. You may also choose to download and build the latest source code
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]39(called <code>master</code>), in which case you will simply omit the branch specification
Robert Ly40e3b6d2013-04-17 18:12:10 -0700[diff] [blame]40when you initialize the repository.</p>
41<p>Once you have selected a branch, follow the appropriate instructions below to
42set up your build environment.</p>
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]43<h2 id="setting-up-a-linux-build-environment">Setting up a Linux build environment</h2>
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]44<p>These instructions apply to all branches, including <code>master</code>.</p>
Robert Ly40e3b6d2013-04-17 18:12:10 -0700[diff] [blame]45<p>The Android build is routinely tested in house on recent versions of
Clay Murphyd95a71f2015-02-24 11:06:04 -0800[diff] [blame]46Ubuntu LTS (14.04), but most distributions should have the required
Robert Ly40e3b6d2013-04-17 18:12:10 -0700[diff] [blame]47build tools available. Reports of successes or failures on other
48distributions are welcome.</p>
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]49<p>For Gingerbread (2.3.x) and newer versions, including the <code>master</code>
Robert Ly40e3b6d2013-04-17 18:12:10 -0700[diff] [blame]50branch, a 64-bit environment is required. Older versions can be
51compiled on 32-bit systems.</p>
Clay Murphya5864b52015-07-30 11:44:49 -0700[diff] [blame]52<p class="note"><strong>Note:</strong> See the <a
53href="requirements.html">Requirements</a> for the complete list of hardware and
54software requirements. Then follow the detailed instructions for Ubuntu and Mac
55OS below.</p>
Conley Owens6c2621e2013-10-08 09:45:30 -0700[diff] [blame]56
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]57<h3 id="installing-the-jdk">Installing the JDK</h3>
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]58<p>The <code>master</code> branch of Android in the <a
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]59href="https://android.googlesource.com/">Android Open Source Project (AOSP)</a>
Clay Murphy403683d2016-04-27 10:41:11 -0700[diff] [blame]60requires Java 8. On Ubuntu, use <a
61href="http://openjdk.java.net/install/">OpenJDK</a>.</p>
62<p>See <a href="requirements.html#jdk">JDK Requirements</a> for older
63versions.</p>
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]64
Stefan Stanacar8420aad2016-02-04 13:08:36 +0200[diff] [blame]65<h4 id="for-ubuntu-15-04">For Ubuntu &gt;= 15.04</h4>
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]66<p>Run the following:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]67<pre class="devsite-click-to-copy">
68<code class="devsite-terminal">sudo apt-get update</code>
69<code class="devsite-terminal">sudo apt-get install openjdk-8-jdk</code>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]70</pre>
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]71
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]72<h4 id="for-ubuntu-14-04">For Ubuntu LTS 14.04</h4>
73<p>There are no available supported OpenJDK 8 packages for Ubuntu 14.04. The
74<strong>Ubuntu 15.04 OpenJDK 8</strong> packages have been used successfully
75with Ubuntu 14.04. <em>Newer package versions (e.g. those for 15.10, 16.04) were
76found not to work on 14.04 using the instructions below.</em></p>
77<ol>
78<li>
Clay Murphy91f5ddd2016-04-26 09:08:00 -0700[diff] [blame]79<p>Download the <code>.deb</code> packages for 64-bit architecture from
80<a href="http://archive.ubuntu.com/ubuntu/pool/universe/o/openjdk-8/">archive.ubuntu.com</a>:</p>
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]81<ul>
Clay Murphy91f5ddd2016-04-26 09:08:00 -0700[diff] [blame]82<li><a
83href="http://archive.ubuntu.com/ubuntu/pool/universe/o/openjdk-8/openjdk-8-jre-headless_8u45-b14-1_amd64.deb">openjdk-8-jre-headless_8u45-b14-1_amd64.deb</a>
84with SHA256 <code>0f5aba8db39088283b51e00054813063173a4d8809f70033976f83e214ab56c0</code></li>
85<li><a
86href="http://archive.ubuntu.com/ubuntu/pool/universe/o/openjdk-8/openjdk-8-jre_8u45-b14-1_amd64.deb">openjdk-8-jre_8u45-b14-1_amd64.deb</a>
87with SHA256 <code>9ef76c4562d39432b69baf6c18f199707c5c56a5b4566847df908b7d74e15849</code></li>
88<li><a
89href="http://archive.ubuntu.com/ubuntu/pool/universe/o/openjdk-8/openjdk-8-jdk_8u45-b14-1_amd64.deb">openjdk-8-jdk_8u45-b14-1_amd64.deb</a>
90with SHA256 <code>6e47215cf6205aa829e6a0a64985075bd29d1f428a4006a80c9db371c2fc3c4c</code></li>
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]91</ul>
92</li>
93<li>
Clay Murphy91f5ddd2016-04-26 09:08:00 -0700[diff] [blame]94<p>Optionally, confirm the checksums of the downloaded files against the SHA256
95string listed with each package above.</p>
96<p>For example, with the <code>sha256sum</code> tool:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]97<pre class="devsite-terminal devsite-click-to-copy">
98sha256sum {downloaded.deb file}
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]99</pre>
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]100</li>
101<li>
102<p>Install the packages:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]103<pre class="devsite-terminal devsite-click-to-copy">
104sudo apt-get update
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]105</pre>
Clay Murphy91f5ddd2016-04-26 09:08:00 -0700[diff] [blame]106<p>Run <code>dpkg</code> for each of the .deb files you downloaded. It may produce errors due to
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]107missing dependencies:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]108<pre class="devsite-terminal devsite-click-to-copy">
109sudo dpkg -i {downloaded.deb file}
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]110</pre>
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]111<p>To fix missing dependencies:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]112<pre class="devsite-terminal devsite-click-to-copy">
113sudo apt-get -f install
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]114</pre>
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]115</li>
116</ol>
117
118<h4 id="default-java-version">Update the default Java version - optional</h4>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]119
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]120<p>Optionally, for the Ubuntu versions above update the default Java version by
121running:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]122<pre class="devsite-click-to-copy">
123<code class="devsite-terminal">sudo update-alternatives --config java</code>
124<code class="devsite-terminal">sudo update-alternatives --config javac</code>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]125</pre>
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]126
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]127<p>If, during a build, you encounter version errors for Java, set its
Clay Murphya5864b52015-07-30 11:44:49 -0700[diff] [blame]128path as described in the <a href="building.html#wrong-java-version">Wrong
Clay Murphy019d9142014-05-06 14:22:54 -0700[diff] [blame]129Java Version</a> section.</p>
130
Clay Murphyd95a71f2015-02-24 11:06:04 -0800[diff] [blame]131<h3 id="installing-required-packages-ubuntu-1404">Installing required packages (Ubuntu 14.04)</h3>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]132
Clay Murphyd95a71f2015-02-24 11:06:04 -0800[diff] [blame]133<p>You will need a 64-bit version of Ubuntu. Ubuntu 14.04 is recommended.</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]134
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]135<pre class="devsite-terminal devsite-click-to-copy">
136sudo apt-get install git-core gnupg flex bison gperf build-essential 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
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]137</pre>
Clay Murphy95ffe512015-11-05 10:12:27 -0800[diff] [blame]138
139<p class="note"><strong>Note:</strong> To use SELinux tools for policy
140analysis, also install the <code>python-networkx</code> package.</p>
Clay Murphyd95a71f2015-02-24 11:06:04 -0800[diff] [blame]141
Roland Levillain245a9b82016-07-25 11:50:39 +0100[diff] [blame]142<p class="note"><strong>Note:</strong> If you are using LDAP and want
143to run ART host tests, also install the <code>libnss-sss:i386</code>
144package.</p>
145
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]146<h3 id="installing-required-packages-ubuntu-1204">Installing required packages
147(Ubuntu 12.04)</h3>
148
149<p>You may use Ubuntu 12.04 to build older versions of Android. Version 12.04
150is not supported on master or recent releases.</p>
151
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]152<pre class="devsite-click-to-copy">
153<code class="devsite-terminal">sudo apt-get install git gnupg flex bison gperf build-essential zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown libxml2-utils xsltproc zlib1g-dev:i386</code>
154<code class="devsite-terminal">sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so</code>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]155</pre>
Conley Owens6c2621e2013-10-08 09:45:30 -0700[diff] [blame]156
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]157<h3 id="installing-required-packages-ubuntu-1004-1110">Installing required
158packages (Ubuntu 10.04 -- 11.10)</h3>
159<p>Building on Ubuntu 10.04-11.10 is no longer supported, but may be useful for
160building older releases of AOSP.</p>
161
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]162<pre class="devsite-terminal devsite-click-to-copy">
163sudo apt-get install git gnupg flex bison gperf build-essential zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown libxml2-utils xsltproc
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]164</pre>
165
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]166<p>On Ubuntu 10.10:</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]167
Android Partner Docsab0c83d2017-08-07 16:52:38 -0700[diff] [blame^]168<pre class="devsite-terminal devsite-click-to-copy">
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]169sudo ln -s /usr/lib32/mesa/libGL.so.1 /usr/lib32/mesa/libGL.so
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]170</pre>
171
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]172<p>On Ubuntu 11.10:</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]173
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]174<pre class="devsite-terminal devsite-click-to-copy">
175sudo apt-get install libx11-dev:i386
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]176</pre>
177
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]178<h3 id="configuring-usb-access">Configuring USB Access</h3>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]179
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]180<p>Under GNU/Linux systems (and specifically under Ubuntu systems),
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]181regular users can't directly access USB devices by default. The
182system needs to be configured to allow such access.</p>
Clay Murphy739b22e2015-08-25 12:15:13 -0700[diff] [blame]183<p>The recommended approach is to create a file at
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]184<code>/etc/udev/rules.d/51-android.rules</code> (as the root user).</p>
Clay Murphy739b22e2015-08-25 12:15:13 -0700[diff] [blame]185
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]186<p>To do this, run the following command to download the <a
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]187href="51-android.txt">51-android.txt</a> file attached to this site, modify
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]188it to include your username, and place it in the correct location:</p>
Clay Murphy739b22e2015-08-25 12:15:13 -0700[diff] [blame]189
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]190<pre class="devsite-terminal devsite-click-to-copy">
191wget -S -O - http://source.android.com/source/51-android.txt | sed "s/&lt;username&gt;/$USER/" | sudo tee >/dev/null /etc/udev/rules.d/51-android.rules; sudo udevadm control --reload-rules
Clay Murphy739b22e2015-08-25 12:15:13 -0700[diff] [blame]192</pre>
193
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]194<p>Those new rules take effect the next time a device is plugged in.
195It might therefore be necessary to unplug the device and plug it
196back into the computer.</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]197
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]198<h3 id="using-a-separate-output-directory">Using a separate output directory</h3>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]199
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]200<p>By default, the output of each build is stored in the <code>out/</code>
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]201subdirectory of the matching source tree.</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]202
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]203<p>On some machines with multiple storage devices, builds are
204faster when storing the source files and the output on
205separate volumes. For additional performance, the output
206can be stored on a filesystem optimized for speed instead
207of crash robustness, since all files can be re-generated
208in case of filesystem corruption.</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]209
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]210<p>To set this up, export the <code>OUT_DIR_COMMON_BASE</code> variable
211to point to the location where your output directories
212will be stored.</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]213
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]214<pre class="devsite-terminal devsite-click-to-copy">
215export OUT_DIR_COMMON_BASE=&lt;path-to-your-out-directory&gt;
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]216</pre>
217
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]218<p>The output directory for each separate source tree will be
219named after the directory holding the source tree.</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]220
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]221<p>For instance, if you have source trees as <code>/source/master1</code>
222and <code>/source/master2</code> and <code>OUT_DIR_COMMON_BASE</code> is set to
223<code>/output</code>, the output directories will be <code>/output/master1</code>
224and <code>/output/master2</code>.</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]225
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]226<p>It's important in that case to not have multiple source
227trees stored in directories that have the same name,
228as those would end up sharing an output directory, with
229unpredictable results.</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]230
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]231<p>This is only supported on Jelly Bean (4.1) and newer,
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]232including the <code>master</code> branch.</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]233
234<h2 id="setting-up-a-mac-os-x-build-environment">Setting up a Mac OS build
235environment</h2>
236
237<p>In a default installation, Mac OS runs on a case-preserving but
238case-insensitive filesystem. This type of filesystem is not supported by git
239and will cause some git commands (such as <code>git status</code>) to behave
240abnormally. Because of this, we recommend that you always work with the AOSP
241source files on a case-sensitive filesystem. This can be done fairly easily
242using a disk image, discussed below.</p>
243
244<p>Once the proper filesystem is available, building the <code>master</code>
245branch in a modern Mac OS environment is very straightforward. Earlier
246branches require some additional tools and SDKs.</p>
247
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]248<h3 id="creating-a-case-sensitive-disk-image">Creating a case-sensitive disk image</h3>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]249
Clay Murphy2de21e82014-12-15 16:42:47 -0800[diff] [blame]250<p>You can create a case-sensitive filesystem within your existing Mac OS environment
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]251using a disk image. To create the image, launch Disk
252Utility and select "New Image". A size of 25GB is the minimum to
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]253complete the build; larger numbers are more future-proof. Using sparse images
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]254saves space while allowing to grow later as the need arises. Be sure to select
255"case sensitive, journaled" as the volume format.</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]256
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]257<p>You can also create it from a shell with the following command:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]258<pre class="devsite-click-to-copy">
259<span class="no-select"># </span>hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/android.dmg
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]260</pre>
261
262<p>This will create a <code>.dmg</code> (or possibly a
263<code>.dmg.sparseimage</code>) file which, once mounted, acts as a drive with
264the required formatting for Android development.</p>
265
266<p>If you need a larger volume later, you can also resize the sparse image with
267the following command:</p>
268
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]269<pre class="devsite-click-to-copy">
270<span class="no-select"># </span>hdiutil resize -size &lt;new-size-you-want&gt;g ~/android.dmg.sparseimage
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]271</pre>
272
273<p>For a disk image named <code>android.dmg</code> stored in your home
274directory, you can add helper functions to your <code>~/.bash_profile</code>:</p>
275
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]276<ul>
277<li>
Android Partner Docsab0c83d2017-08-07 16:52:38 -0700[diff] [blame^]278To mount the image when you execute <code>mountAndroid</code>:
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]279
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]280<pre class="devsite-click-to-copy">
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]281# mount the android file image
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]282function mountAndroid { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; }
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]283</pre>
284
285<p class="note"><strong>Note:</strong> If your system created a
286<code>.dmg.sparseimage</code> file, replace <code>~/android.dmg</code> with
287<code>~/android.dmg.sparseimage</code>.</p>
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]288</li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]289
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]290<li>
291<p>To unmount it when you execute <code>umountAndroid</code>:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]292<pre class="devsite-click-to-copy">
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]293# unmount the android file image
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]294function umountAndroid() { hdiutil detach /Volumes/android; }
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]295</pre>
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]296</li>
297</ul>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]298
299<p>Once you've mounted the <code>android</code> volume, you'll do all your work
300there. You can eject it (unmount it) just like you would with an external
301drive.</p>
Clay Murphy82779c22014-12-09 10:46:19 -0800[diff] [blame]302
303<h3 id="installing-the-mac-jdk">Installing the JDK</h3>
Neil Fuller6534d772016-01-18 12:38:30 -0800[diff] [blame]304
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]305<p>See <a href="requirements.html">Requirements</a> for the version of Java to
306use when developing various versions of Android.</p>
Clay Murphy82779c22014-12-09 10:46:19 -0800[diff] [blame]307
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]308<h4 id="installing-required-packages">Installing required packages</h4>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]309
310<ol>
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]311<li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]312<p>Install Xcode command line tools with:
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]313<pre class="devsite-terminal devsite-click-to-copy">
314xcode-select --install
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]315</pre>
316
317<p>For older versions of Mac OS (10.8 or earlier), you need to install Xcode from
318<a href="http://developer.apple.com/">the Apple developer site</a>.
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]319If you are not already registered as an Apple developer, you will have to
320create an Apple ID in order to download.</p>
321</li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]322
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]323<li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]324<p>Install MacPorts from <a
325href="http://www.macports.org/install.php">macports.org</a>.</p>
326
327<p class="note"><strong>Note:</strong> Make sure that
328<code>/opt/local/bin</code> appears in your path <strong>before</strong>
329<code>/usr/bin</code>. If not, please add the following to your
330<code>~/.bash_profile</code> file:</p>
331
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]332<pre class="devsite-click-to-copy">
333export PATH=/opt/local/bin:$PATH
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700[diff] [blame]334</pre>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]335
Clay Murphy3d70b982016-05-11 15:58:28 -0700[diff] [blame]336<p class="note"><strong>Note:</strong> If you do not have a
337<code>.bash_profile</code> file in your home directory, create one.</p>
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]338</li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]339
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]340<li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]341<p>Get make, git, and GPG packages from MacPorts:</p>
342
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]343<pre class="devsite-terminal devsite-click-to-copy">
344POSIXLY_CORRECT=1 sudo port install gmake libsdl git gnupg
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]345</pre>
346
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]347<p>If using Mac OS X v10.4, also install bison:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]348<pre class="devsite-terminal devsite-click-to-copy">
349POSIXLY_CORRECT=1 sudo port install bison
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]350</pre>
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]351</li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]352</ol>
Clay Murphyd110a482016-03-10 11:56:40 -0800[diff] [blame]353
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]354<h4 id="reverting-from-make-382">Reverting from make 3.82</h4>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]355
Clay Murphyd110a482016-03-10 11:56:40 -0800[diff] [blame]356<p>In Android 4.0.x (Ice Cream Sandwich) and earlier, a bug exists in gmake 3.82
357that prevents android from building. You can install version 3.81 using
358MacPorts with these steps:</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]359
360<ol>
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]361<li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]362<p>Edit <code>/opt/local/etc/macports/sources.conf</code> and add a line that says:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]363<pre class="devsite-click-to-copy">
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]364file:///Users/Shared/dports
365</pre>
366
367<p>above the rsync line. Then create this directory:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]368<pre class="devsite-terminal devsite-click-to-copy">
369mkdir /Users/Shared/dports
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]370</pre>
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]371</li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]372
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]373<li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]374<p>In the new <code>dports</code> directory, run:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]375<pre class="devsite-terminal devsite-click-to-copy">
376svn co --revision 50980 http://svn.macports.org/repository/macports/trunk/dports/devel/gmake/ devel/gmake/
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]377</pre>
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]378</li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]379
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]380<li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]381<p>Create a port index for your new local repository:</p>
382
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]383<pre class="devsite-terminal devsite-click-to-copy">
384portindex /Users/Shared/dports
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]385</pre>
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]386</li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]387
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]388<li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]389<p>Install the old version of gmake with:</p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]390<pre class="devsite-terminal devsite-click-to-copy">
391sudo port install gmake @3.81
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]392</pre>
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]393</li>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]394</ol>
Clay Murphyd110a482016-03-10 11:56:40 -0800[diff] [blame]395
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]396<h4 id="setting-a-file-descriptor-limit">Setting a file descriptor limit</h4>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]397
Clay Murphy3d70b982016-05-11 15:58:28 -0700[diff] [blame]398<p>On Mac OS, the default limit on the number of simultaneous file descriptors
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]399open is too low and a highly parallel build process may exceed this limit.</p>
400
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]401<p>To increase the cap, add the following lines to your <code>~/.bash_profile</code>: </p>
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]402<pre class="devsite-click-to-copy">
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]403# set the number of open files to be 1024
Robert Ly35f2fda2013-01-29 16:27:05 -0800[diff] [blame]404ulimit -S -n 1024
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]405</pre>
406
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]407<h2 id="optimizing-a-build-environment">Optimizing a build environment (optional)</h2>
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]408
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]409<h3 id="setting-up-ccache">Setting up ccache</h3>
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]410
Clay Murphy3d70b982016-05-11 15:58:28 -0700[diff] [blame]411<p>You can optionally tell the build to use the ccache compilation tool, which
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]412is a compiler cache for C and C++ that can help make builds faster. It
Clay Murphy3d70b982016-05-11 15:58:28 -0700[diff] [blame]413is especially useful for build servers and other high-volume production
414environments. Ccache acts as a compiler cache that can be used to speed up rebuilds.
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]415This works very well if you use <code>make clean</code> often, or if you frequently
416switch between different build products.</p>
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]417
Clay Murphy3d70b982016-05-11 15:58:28 -0700[diff] [blame]418<p class="note"><strong>Note:</strong> If you're instead conducting incremental
419builds (such as an individual developer rather than a build server), ccache may
420slow your builds down by making you pay for cache misses.</p>
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]421
422<p>To use ccache, issue these commands in the root of the source tree:</p>
423
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]424<pre class="devsite-click-to-copy">
425<code class="devsite-terminal">export USE_CCACHE=1</code>
426<code class="devsite-terminal">export CCACHE_DIR=/&lt;path_of_your_choice&gt;/.ccache</code>
427<code class="devsite-terminal">prebuilts/misc/linux-x86/ccache/ccache -M 50G</code>
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]428</pre>
429
430<p>The suggested cache size is 50-100G.</p>
431
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]432<p>Put the following in your <code>.bashrc</code> (or equivalent):</p>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]433
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]434<pre class="devsite-click-to-copy">
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]435export USE_CCACHE=1
436</pre>
437
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]438<p>By default the cache will be stored in <code>~/.ccache</code>.
439If your home directory is on NFS or some other non-local filesystem,
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]440you will want to specify the directory in your <code>.bashrc</code> file too.</p>
441
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]442<p>On Mac OS, you should replace <code>linux-x86</code> with <code>darwin-x86</code>:</p>
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]443
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]444<pre class="devsite-click-to-copy">
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]445prebuilts/misc/darwin-x86/ccache/ccache -M 50G
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]446</pre>
447
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]448<p>When building Ice Cream Sandwich (4.0.x) or older, ccache is in
449a different location:</p>
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]450
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]451<pre class="devsite-click-to-copy">
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]452prebuilt/linux-x86/ccache/ccache -M 50G
453</pre>
454
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]455<p>This setting is stored in the CCACHE_DIR and is persistent.</p>
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]456
457<p>On Linux, you can watch ccache being used by doing the following:</p>
458
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]459<pre class="devsite-terminal devsite-click-to-copy">
460watch -n1 -d prebuilts/misc/linux-x86/ccache/ccache -s
Clay Murphy62807b02016-06-17 18:01:28 -0700[diff] [blame]461</pre>
462
Clay Murphy6d00f3b2014-03-26 17:39:24 -0700[diff] [blame]463<h2 id="next-download-the-source">Next: Download the source</h2>
Clay Murphy07b876a2016-11-02 15:27:30 -0700[diff] [blame]464
465<p>Your build environment is good to go! Proceed to <a
466href="downloading.html">downloading the source</a>.</p>
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]467
468 </body>
469</html>