blob: 56df7137794052375b8e0dd06f217755cf8bc268 [file] [log] [blame]
Dan Morrilla9788cd2009-11-15 11:49:30 -08001page.title=Using Eclipse
Dan Morrill3cd199f2009-11-06 14:04:16 -08002doc.type=source
3@jd:body
Dan Morrill55de6812009-11-15 15:46:36 -08004<div>
5<p>This document will help you set up the Eclipse IDE for Android platform development.</p>
6<p><i>Note: if you are looking for information on how to use
7Eclipse to develop applications that run on Android, this is not the right
8page for you. You probably would find <a
9href="http://developer.android.com/sdk/eclipse-adt.html">the Eclipse page on
10developer.android.com</a> more useful.</i></p>
Dan Morrill3cd199f2009-11-06 14:04:16 -080011<h2><a>Enter eclipse</a>
12</h2>
13<h4>
14Basic setup
15</h4>
16<p>First, it's important to make sure the regular Android development system is set up.
17</p>
Dan Morrilla9788cd2009-11-15 11:49:30 -080018<pre>cd /path/to/android/root <br>make # and wait a while, if you haven't done this <br></pre>
Dan Morrill3cd199f2009-11-06 14:04:16 -080019<p><b>Important</b>
20: You will still be using "make" to build the files you will actually run (in the emulator or on a device). You will be using Eclipse to edit files and verify that they compile, but when you want to run something you will need to make sure files are saved in Eclipse and run "make" in a shell. The Eclipse build is just for error checking.
21</p>
22<p>Eclipse needs a list of directories to search for Java files. This is called the "Java Build Path" and can be set with the .classpath file. We have a sample version to start you off.
23</p>
Dan Morrilla9788cd2009-11-15 11:49:30 -080024<pre>cd /path/to/android/root <br>cp development/ide/eclipse/.classpath .<br>chmod u+w .classpath # Make the copy writable <br></pre>
Dan Morrill3cd199f2009-11-06 14:04:16 -080025<p>Now edit that copy of .classpath, if necessary.
26</p>
27<h5>
28Increase Eclipse's Memory Settings
29</h5>
30<p>The Android project is large enough that Eclipse's Java VM sometimes runs out of memory while compiling it. Avoid this problem by editing the the eclipse.ini file. On Apple OSX the eclipse.ini file is located at /Applications/eclipse/Eclipse.app/Contents/MacOS/eclipse.ini
31</p>
32<p>Memory-related defaults (as of Eclipse 3.4)
33</p>
34
Dan Morrilla9788cd2009-11-15 11:49:30 -080035<pre>-Xms40m <br>-Xmx256m <br>-XX:MaxPermSize=256m <br></pre>
Dan Morrill3cd199f2009-11-06 14:04:16 -080036<p>Recommended settings for Android development
37</p>
Dan Morrilla9788cd2009-11-15 11:49:30 -080038<pre>-Xms128m <br>-Xmx512m <br>-XX:MaxPermSize=256m <br></pre>
Dan Morrill3cd199f2009-11-06 14:04:16 -080039<p>These settings set Eclipse's minimum Java heap size to 128MB, set the maximum Java heap size to 512MB, and keep the maximum permanent generation size at the default of 256MB.
40</p>
41<p>Now start Eclipse:
42</p>
Dan Morrilla9788cd2009-11-15 11:49:30 -080043<pre>eclipse # or you can click some clicky thing instead, if you prefer <br></pre>
Dan Morrill3cd199f2009-11-06 14:04:16 -080044<p>Now create a project for Android development:
45</p>
46<ol><li>If Eclipse asks you for a workspace location, choose the default.
47</li>
48<li>If you have a "Welcome" screen, close it to reveal the Java perspective.
49</li>
50<li>File New Java Project
51</li>
52<li>Pick a project name, "android" or anything you like.
53</li>
54<li>Select "Create project from existing source", enter the path to your Android root directory, and click Finish.
55</li>
56<li>Wait while it sets up the project. (You'll see a subtle progress meter in the lower right corner.)
57</li>
58</ol>
59<p>Once the project workspace is created, Eclipse should start building. In theory, it should build with no errors and you should be set to go. If necessary, uncheck and re-check Project Build Automatically to force a rebuild.
60</p>
61<p><i><b>Note:</b>
62</i>
63Eclipse sometimes likes to add an "import android.R" statement at the top of your files that use resources, especially when you ask eclipse to sort or otherwise manage imports. This will cause your make to break. Look out for these erroneous import statements and delete them.
64</p>
65<h4>
66When you sync
67</h4>
68<p>Every time you repo sync, or otherwise change files outside of Eclipse (especially the .classpath), you need to refresh Eclipse's view of things:
69</p>
70<ol><li>Window Show View Navigator
71</li>
72<li>In the "Navigator", right-click on the project ("android-java" or whatever you named it)
73</li>
74<li>Click Refresh in the context menu
75</li>
76</ol>
77<h4>
78Adding apps to the build path
79</h4>
80<p>The default .classpath includes the source to the core system and a sample set of apps, but might not include the particular app you may want to work on. To add an app, you must add the app's source directory. To do this inside Eclipse:
81</p>
82<ol><li>Project Properties
83</li>
84<li>Select "Java Build Path" from the left-hand menu.
85</li>
86<li>Choose the "Source" tab.
87</li>
88<li>Click "Add Folder...".
89</li>
90<li>Add your app's "src" directory.
91</li>
92<li>Click OK.
93</li>
94</ol>
95<p>When you're done, the "source folder" path in the list should look like android/packages/apps/<i>YourAppName</i>
96/src. Depending on which app(s) you include, you may also need to include othersrc/main/java directories under android/dalvik/libcore. Do this if you find you cannot build with the default set.
97</p>
98<h4>
99Eclipse setup to work on developer tools
100</h4>
101<p>To work on Java developer tools, the principle is the same, except you specify /path/to/tool when using the option "Create project from existing source."
102</p>
103<p>Once the project is created, you need to set up the Java Build Path:
104</p>
105<ol><li>Select the project you just created.
106</li>
107<li>Project Properties
108</li>
109<li>Select "Java Build Path" from the left-hand menu.
110</li>
111<li>Choose the "Source" tab.
112</li>
Dan Morrilla9788cd2009-11-15 11:49:30 -0800113<li>Expand the single <i>toolname</i>
Dan Morrill3cd199f2009-11-06 14:04:16 -0800114/src entry.
115</li>
116<li>Double click the "Excluded: (none)" item.
117</li>
118<li>Add to the excluded (bottom) list: "MakeFile" and "resources/".
119</li>
120<li>Close the dialog.
121</li>
Dan Morrilla9788cd2009-11-15 11:49:30 -0800122<li>Back in the "Source" tab, click "Add Folder...", and add <i>toolname</i>
Dan Morrill3cd199f2009-11-06 14:04:16 -0800123/src/resources.
124</li>
125<li>Click OK.
126</li>
127</ol>
128<h4>
Dan Morrilla9788cd2009-11-15 11:49:30 -0800129Eclipse setup to work on DDMS <br></h4>
Dan Morrill3cd199f2009-11-06 14:04:16 -0800130<p>For DDMS, you will need to make a project for
131</p>
132<ol><li>development/tools/ddms/libs/ddmlib
133</li>
134<li>development/tools/ddms/libs/ddmuilib
135</li>
136<li>development/tools/ddms/app
137</li>
138</ol>
139<p>Each project will need to reference the ones before it ("ddmuilib" references "ddmlib", and "app" references both of those). To do this:
140</p>
141<ol><li>Make sure you have all 3 projects defined.
142</li>
143<li>Right click on a project, "Build Path" "Configure Build Path..."
144</li>
145<li>Choose the "Project" tab.
146</li>
147<li>Click "Add..." and check the required projects.
148</li>
149</ol>
150<h2><a>Eclipse formatting</a>
151</h2>
Tom O'Neill1180ce92010-01-11 09:01:05 -0800152<p>You can import files in development/ide/eclipse to make Eclipse
153follow the Android style rules. Select
154"Window &rsaquo; Preferences &rsaquo; Java &rsaquo; Code Style".
155Use "Formatter &rsaquo; Import" to import android-formatting.xml
156and "Organize Imports &rsaquo; Import" to import android.importorder.
Dan Morrill3cd199f2009-11-06 14:04:16 -0800157</p>
158<h2><a>Debugging the emulator with Eclipse</a>
159</h2>
160<p>You can also use eclipse to debug the emulator and step through code. First, start the emulator running:
161</p>
Dan Morrilla9788cd2009-11-15 11:49:30 -0800162<pre>cd /path/to/android/root <br>. build/envsetup.sh <br>lunch 1 # to build the emulator <br>make # if you didn't already do this <br>emulator # you should see a GUI picture of a phone <br></pre>
Dan Morrill3cd199f2009-11-06 14:04:16 -0800163<p>In another shell, start DDMS (the Dalvik debug manager):
164</p>
Dan Morrilla9788cd2009-11-15 11:49:30 -0800165<pre>cd /path/to/android/root <br>ddms # you should get a splufty debugging console <br></pre>
Dan Morrill3cd199f2009-11-06 14:04:16 -0800166<p>Now, in eclipse, you can attach to the emulator:
167</p>
168<ol><li>Run Open Debug Dialog...
169</li>
170<li>Right-click "Remote Java Application", select "New".
171</li>
172<li>Pick a name, "android-debug" or anything you like.
173</li>
174<li>Set the "Project" to your project ("android-java" or whatever).
175</li>
176<li>Keep the "Host" set to "localhost", but change "Port" to 8700.
177</li>
178<li>Click the "Debug" button and you should be all set.
179</li>
180</ol>
181<p>Note that port 8700 is attached to whatever process is currently selected in the DDMS console, so you need to sure that DDMS has selected the process you want to debug.
182</p>
183<p>You may need to open the Debug perspective (next to the "Java" perspective icon in the upper-right, click the small "Open Perspective" icon and select "Debug"). Once you do, you should see a list of threads; if you select one and break it (by clicking the "pause" icon), it should show the stack trace, source file, and line where execution is at. Breakpoints and whatnot should all work.
184</p>
185<h2><a>Bonus material</a>
186</h2>
187<p>Replace Ctrl with the Apple key on Mac.
188</p>
189
Dan Morrilla9788cd2009-11-15 11:49:30 -0800190<pre>Ctrl-Shift-o = Organize imports <br>Ctrl-Shift-t = load class by name <br>Ctrl-Shift-r = load non-class resource by name <br>Ctrl-1 = quick fix <br>Ctrl-e = Recently viewed files <br>Ctrl-space = auto complete <br>Shift-Alt-r = refactor:rename <br>Shift-Alt-v = refactor:move <br></pre>
Dan Morrill3cd199f2009-11-06 14:04:16 -0800191
192<h2><a>Useful Plugins</a>
193</h2>
194<p>Eclipse has a plugin architecture that enables third parties to extend the IDE. Here are some plugins that make Eclipse easier to use for writing Android software:
195</p>
196
197<ul><li><a href="http://andrei.gmxhome.de/anyedit/">AnyEdit</a>
198- automatically fix whitespace issues when saving files. Can convert tabs to spaces, strip blanks at end-of-line, and ensure the last line of the file has an end-of-line character.
199</li>
200</ul>
201<h2><a>"Eclipse is not working correctly, what should I do?"</a>
202</h2>
203<p>Make sure:
204</p>
205<ul><li>You followed the instructions on this page precisely.
206</li>
207<li>Your Problems view doesn't show any errors.
208</li>
209<li>Your application respects the package/directory structure.
210</li>
211</ul>
212<p>If you're still having problems, please contact one of the Android mailing lists or IRC channels.
213</p>
214</div>