diff options
Diffstat (limited to 'en/setup/initializing.html')
| -rw-r--r-- | en/setup/initializing.html | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/en/setup/initializing.html b/en/setup/initializing.html new file mode 100644 index 00000000..662862be --- /dev/null +++ b/en/setup/initializing.html @@ -0,0 +1,460 @@ +<html devsite> + <head> + <title>Establishing a Build Environment</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p>This section describes how to set up your local work environment to build +the Android source files. You will need to use Linux or Mac OS. Building under +Windows is not currently supported.</p> +<p>For an overview of the entire code-review and code-update process, see <a +href="life-of-a-patch.html">Life of a Patch</a>.</p> +<p class="note"><strong>Note:</strong> All commands in this site are preceded +by a dollar sign ($) to differentiate them from output or entries within files. +You may use the <em>Click to copy</em> feature at the top right of each command +box to copy all lines without the dollar signs or triple-click each line to +copy it individually without the dollar sign.</p> +<h2 id="choosing-a-branch">Choosing a Branch</h2> +<p>Some of the requirements for your build environment are determined by which +version of the source code you plan to compile. See +<a href="build-numbers.html">Build Numbers</a> for a full listing of branches you may +choose from. You may also choose to download and build the latest source code +(called <code>master</code>), in which case you will simply omit the branch specification +when you initialize the repository.</p> +<p>Once you have selected a branch, follow the appropriate instructions below to +set up your build environment.</p> +<h2 id="setting-up-a-linux-build-environment">Setting up a Linux build environment</h2> +<p>These instructions apply to all branches, including <code>master</code>.</p> +<p>The Android build is routinely tested in house on recent versions of +Ubuntu LTS (14.04), but most distributions should have the required +build tools available. Reports of successes or failures on other +distributions are welcome.</p> +<p>For Gingerbread (2.3.x) and newer versions, including the <code>master</code> +branch, a 64-bit environment is required. Older versions can be +compiled on 32-bit systems.</p> +<p class="note"><strong>Note:</strong> See the <a +href="requirements.html">Requirements</a> for the complete list of hardware and +software requirements. Then follow the detailed instructions for Ubuntu and Mac +OS below.</p> + +<h3 id="installing-the-jdk">Installing the JDK</h3> +<p>The <code>master</code> branch of Android in the <a +href="https://android.googlesource.com/">Android Open Source Project (AOSP)</a> +comes with a prebuilt version of OpenJDK in +<code>platform/prebuilts/jdk/jdk8</code>. So no additional installation is +required.</p> + +<p>Older versions of Android require a separate installation of the JDK. On +Ubuntu, use <a href="http://openjdk.java.net/install/">OpenJDK</a>. See <a +href="requirements.html#jdk">JDK Requirements</a> for precise versions and the +sections below for instructions.</p> + +<h4 id="for-ubuntu-15-04">For Ubuntu >= 15.04</h4> +<p>Run the following:</p> +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal">sudo apt-get update</code> +<code class="devsite-terminal">sudo apt-get install openjdk-8-jdk</code> +</pre> + +<h4 id="for-ubuntu-14-04">For Ubuntu LTS 14.04</h4> +<p>There are no available supported OpenJDK 8 packages for Ubuntu 14.04. The +<strong>Ubuntu 15.04 OpenJDK 8</strong> packages have been used successfully +with Ubuntu 14.04. <em>Newer package versions (e.g. those for 15.10, 16.04) were +found not to work on 14.04 using the instructions below.</em></p> +<ol> +<li> +<p>Download the <code>.deb</code> packages for 64-bit architecture from +<a href="http://archive.ubuntu.com/ubuntu/pool/universe/o/openjdk-8/">archive.ubuntu.com</a>:</p> +<ul> +<li><a +href="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> +with SHA256 <code>0f5aba8db39088283b51e00054813063173a4d8809f70033976f83e214ab56c0</code></li> +<li><a +href="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> +with SHA256 <code>9ef76c4562d39432b69baf6c18f199707c5c56a5b4566847df908b7d74e15849</code></li> +<li><a +href="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> +with SHA256 <code>6e47215cf6205aa829e6a0a64985075bd29d1f428a4006a80c9db371c2fc3c4c</code></li> +</ul> +</li> +<li> +<p>Optionally, confirm the checksums of the downloaded files against the SHA256 +string listed with each package above.</p> +<p>For example, with the <code>sha256sum</code> tool:</p> +<pre class="devsite-terminal devsite-click-to-copy"> +sha256sum {downloaded.deb file} +</pre> +</li> +<li> +<p>Install the packages:</p> +<pre class="devsite-terminal devsite-click-to-copy"> +sudo apt-get update +</pre> +<p>Run <code>dpkg</code> for each of the .deb files you downloaded. It may produce errors due to +missing dependencies:</p> +<pre class="devsite-terminal devsite-click-to-copy"> +sudo dpkg -i {downloaded.deb file} +</pre> +<p>To fix missing dependencies:</p> +<pre class="devsite-terminal devsite-click-to-copy"> +sudo apt-get -f install +</pre> +</li> +</ol> + +<h4 id="default-java-version">Update the default Java version - optional</h4> + +<p>Optionally, for the Ubuntu versions above update the default Java version by +running:</p> +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal">sudo update-alternatives --config java</code> +<code class="devsite-terminal">sudo update-alternatives --config javac</code> +</pre> + +<p>If, during a build, you encounter version errors for Java, set its +path as described in the <a href="building.html#wrong-java-version">Wrong +Java Version</a> section.</p> + +<h3 id="installing-required-packages-ubuntu-1404">Installing required packages (Ubuntu 14.04)</h3> + +<p>You will need a 64-bit version of Ubuntu. Ubuntu 14.04 is recommended.</p> + +<pre class="devsite-terminal devsite-click-to-copy"> +sudo 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 +</pre> + +<p class="note"><strong>Note:</strong> To use SELinux tools for policy +analysis, also install the <code>python-networkx</code> package.</p> + +<p class="note"><strong>Note:</strong> If you are using LDAP and want +to run ART host tests, also install the <code>libnss-sss:i386</code> +package.</p> + +<h3 id="installing-required-packages-ubuntu-1204">Installing required packages +(Ubuntu 12.04)</h3> + +<p>You may use Ubuntu 12.04 to build older versions of Android. Version 12.04 +is not supported on master or recent releases.</p> + +<pre class="devsite-click-to-copy"> +<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> +<code class="devsite-terminal">sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so</code> +</pre> + +<h3 id="installing-required-packages-ubuntu-1004-1110">Installing required +packages (Ubuntu 10.04 -- 11.10)</h3> +<p>Building on Ubuntu 10.04-11.10 is no longer supported, but may be useful for +building older releases of AOSP.</p> + +<pre class="devsite-terminal devsite-click-to-copy"> +sudo 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 +</pre> + +<p>On Ubuntu 10.10:</p> + +<pre class="devsite-terminal devsite-click-to-copy"> +sudo ln -s /usr/lib32/mesa/libGL.so.1 /usr/lib32/mesa/libGL.so +</pre> + +<p>On Ubuntu 11.10:</p> + +<pre class="devsite-terminal devsite-click-to-copy"> +sudo apt-get install libx11-dev:i386 +</pre> + +<h3 id="configuring-usb-access">Configuring USB Access</h3> + +<p>Install a community-maintained default set of <code>udev</code> rules for +all Android devices by following the instructions to <a +href="https://developer.android.com/studio/run/device.html#setting-up" +class="external">Set up a device for development</a>. + +<h3 id="using-a-separate-output-directory">Using a separate output directory</h3> + +<p>By default, the output of each build is stored in the <code>out/</code> +subdirectory of the matching source tree.</p> + +<p>On some machines with multiple storage devices, builds are +faster when storing the source files and the output on +separate volumes. For additional performance, the output +can be stored on a filesystem optimized for speed instead +of crash robustness, since all files can be re-generated +in case of filesystem corruption.</p> + +<p>To set this up, export the <code>OUT_DIR_COMMON_BASE</code> variable +to point to the location where your output directories +will be stored.</p> + +<pre class="devsite-terminal devsite-click-to-copy"> +export OUT_DIR_COMMON_BASE=<path-to-your-out-directory> +</pre> + +<p>The output directory for each separate source tree will be +named after the directory holding the source tree.</p> + +<p>For instance, if you have source trees as <code>/source/master1</code> +and <code>/source/master2</code> and <code>OUT_DIR_COMMON_BASE</code> is set to +<code>/output</code>, the output directories will be <code>/output/master1</code> +and <code>/output/master2</code>.</p> + +<p>It's important in that case to not have multiple source +trees stored in directories that have the same name, +as those would end up sharing an output directory, with +unpredictable results.</p> + +<p>This is only supported on Jelly Bean (4.1) and newer, +including the <code>master</code> branch.</p> + +<h2 id="setting-up-a-mac-os-x-build-environment">Setting up a Mac OS build +environment</h2> + +<p>In a default installation, Mac OS runs on a case-preserving but +case-insensitive filesystem. This type of filesystem is not supported by git +and will cause some git commands (such as <code>git status</code>) to behave +abnormally. Because of this, we recommend that you always work with the AOSP +source files on a case-sensitive filesystem. This can be done fairly easily +using a disk image, discussed below.</p> + +<p>Once the proper filesystem is available, building the <code>master</code> +branch in a modern Mac OS environment is very straightforward. Earlier +branches require some additional tools and SDKs.</p> + +<h3 id="creating-a-case-sensitive-disk-image">Creating a case-sensitive disk image</h3> + +<p>You can create a case-sensitive filesystem within your existing Mac OS environment +using a disk image. To create the image, launch Disk +Utility and select "New Image". A size of 25GB is the minimum to +complete the build; larger numbers are more future-proof. Using sparse images +saves space while allowing to grow later as the need arises. Be sure to select +"case sensitive, journaled" as the volume format.</p> + +<p>You can also create it from a shell with the following command:</p> +<pre class="devsite-click-to-copy"> +<span class="no-select"># </span>hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/android.dmg +</pre> + +<p>This will create a <code>.dmg</code> (or possibly a +<code>.dmg.sparseimage</code>) file which, once mounted, acts as a drive with +the required formatting for Android development.</p> + +<p>If you need a larger volume later, you can also resize the sparse image with +the following command:</p> + +<pre class="devsite-click-to-copy"> +<span class="no-select"># </span>hdiutil resize -size <new-size-you-want>g ~/android.dmg.sparseimage +</pre> + +<p>For a disk image named <code>android.dmg</code> stored in your home +directory, you can add helper functions to your <code>~/.bash_profile</code>:</p> + +<ul> +<li> +To mount the image when you execute <code>mountAndroid</code>: + +<pre class="devsite-click-to-copy"> +# mount the android file image +mountAndroid() { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; } +</pre> + +<p class="note"><strong>Note:</strong> If your system created a +<code>.dmg.sparseimage</code> file, replace <code>~/android.dmg</code> with +<code>~/android.dmg.sparseimage</code>.</p> +</li> + +<li> +<p>To unmount it when you execute <code>umountAndroid</code>:</p> +<pre class="devsite-click-to-copy"> +# unmount the android file image +umountAndroid() { hdiutil detach /Volumes/android; } +</pre> +</li> +</ul> + +<p>Once you've mounted the <code>android</code> volume, you'll do all your work +there. You can eject it (unmount it) just like you would with an external +drive.</p> + +<h3 id="installing-the-mac-jdk">Installing the JDK</h3> + +<p>See <a href="requirements.html">Requirements</a> for the version of Java to +use when developing various versions of Android.</p> + +<h4 id="installing-required-packages">Installing required packages</h4> + +<ol> +<li> +<p>Install Xcode command line tools with: +<pre class="devsite-terminal devsite-click-to-copy"> +xcode-select --install +</pre> + +<p>For older versions of Mac OS (10.8 or earlier), you need to install Xcode from +<a href="http://developer.apple.com/">the Apple developer site</a>. +If you are not already registered as an Apple developer, you will have to +create an Apple ID in order to download.</p> +</li> + +<li> +<p>Install MacPorts from <a +href="http://www.macports.org/install.php">macports.org</a>.</p> + +<p class="note"><strong>Note:</strong> Make sure that +<code>/opt/local/bin</code> appears in your path <strong>before</strong> +<code>/usr/bin</code>. If not, please add the following to your +<code>~/.bash_profile</code> file:</p> + +<pre class="devsite-click-to-copy"> +export PATH=/opt/local/bin:$PATH +</pre> + +<p class="note"><strong>Note:</strong> If you do not have a +<code>.bash_profile</code> file in your home directory, create one.</p> +</li> + +<li> +<p>Get make, git, and GPG packages from MacPorts:</p> + +<pre class="devsite-terminal devsite-click-to-copy"> +POSIXLY_CORRECT=1 sudo port install gmake libsdl git gnupg +</pre> + +<p>If using Mac OS X v10.4, also install bison:</p> +<pre class="devsite-terminal devsite-click-to-copy"> +POSIXLY_CORRECT=1 sudo port install bison +</pre> +</li> +</ol> + +<h4 id="reverting-from-make-382">Reverting from make 3.82</h4> + +<p>In Android 4.0.x (Ice Cream Sandwich) and earlier, a bug exists in gmake 3.82 +that prevents android from building. You can install version 3.81 using +MacPorts with these steps:</p> + +<ol> +<li> +<p>Edit <code>/opt/local/etc/macports/sources.conf</code> and add a line that says:</p> +<pre class="devsite-click-to-copy"> +file:///Users/Shared/dports +</pre> + +<p>above the rsync line. Then create this directory:</p> +<pre class="devsite-terminal devsite-click-to-copy"> +mkdir /Users/Shared/dports +</pre> +</li> + +<li> +<p>In the new <code>dports</code> directory, run:</p> +<pre class="devsite-terminal devsite-click-to-copy"> +svn co --revision 50980 http://svn.macports.org/repository/macports/trunk/dports/devel/gmake/ devel/gmake/ +</pre> +</li> + +<li> +<p>Create a port index for your new local repository:</p> + +<pre class="devsite-terminal devsite-click-to-copy"> +portindex /Users/Shared/dports +</pre> +</li> + +<li> +<p>Install the old version of gmake with:</p> +<pre class="devsite-terminal devsite-click-to-copy"> +sudo port install gmake @3.81 +</pre> +</li> +</ol> + +<h4 id="setting-a-file-descriptor-limit">Setting a file descriptor limit</h4> + +<p>On Mac OS, the default limit on the number of simultaneous file descriptors +open is too low and a highly parallel build process may exceed this limit.</p> + +<p>To increase the cap, add the following lines to your <code>~/.bash_profile</code>: </p> +<pre class="devsite-click-to-copy"> +# set the number of open files to be 1024 +ulimit -S -n 1024 +</pre> + +<h2 id="optimizing-a-build-environment">Optimizing a build environment (optional)</h2> + +<h3 id="setting-up-ccache">Setting up ccache</h3> + +<p>You can optionally tell the build to use the ccache compilation tool, which +is a compiler cache for C and C++ that can help make builds faster. It +is especially useful for build servers and other high-volume production +environments. Ccache acts as a compiler cache that can be used to speed up rebuilds. +This works very well if you use <code>make clean</code> often, or if you frequently +switch between different build products.</p> + +<p class="note"><strong>Note:</strong> If you're instead conducting incremental +builds (such as an individual developer rather than a build server), ccache may +slow your builds down by making you pay for cache misses.</p> + +<p>To use ccache, issue these commands in the root of the source tree:</p> + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal">export USE_CCACHE=1</code> +<code class="devsite-terminal">export CCACHE_DIR=/<path_of_your_choice>/.ccache</code> +<code class="devsite-terminal">prebuilts/misc/linux-x86/ccache/ccache -M 50G</code> +</pre> + +<p>The suggested cache size is 50-100G.</p> + +<p>Put the following in your <code>.bashrc</code> (or equivalent):</p> + +<pre class="devsite-click-to-copy"> +export USE_CCACHE=1 +</pre> + +<p>By default the cache will be stored in <code>~/.ccache</code>. +If your home directory is on NFS or some other non-local filesystem, +you will want to specify the directory in your <code>.bashrc</code> file too.</p> + +<p>On Mac OS, you should replace <code>linux-x86</code> with <code>darwin-x86</code>:</p> + +<pre class="devsite-click-to-copy"> +prebuilts/misc/darwin-x86/ccache/ccache -M 50G +</pre> + +<p>When building Ice Cream Sandwich (4.0.x) or older, ccache is in +a different location:</p> + +<pre class="devsite-click-to-copy"> +prebuilt/linux-x86/ccache/ccache -M 50G +</pre> + +<p>This setting is stored in the CCACHE_DIR and is persistent.</p> + +<p>On Linux, you can watch ccache being used by doing the following:</p> + +<pre class="devsite-terminal devsite-click-to-copy"> +watch -n1 -d prebuilts/misc/linux-x86/ccache/ccache -s +</pre> + +<h2 id="next-download-the-source">Next: Download the source</h2> + +<p>Your build environment is good to go! Proceed to <a +href="downloading.html">downloading the source</a>.</p> + + </body> +</html> |