1 <!-- 2 Copyright 2010 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 --> 16 17 # Using Eclipse # 18 19 This document will help you set up the Eclipse IDE for Android platform development. 20 21 *Note: if you are looking for information on how to use 22 Eclipse to develop applications that run on Android, this is not the right 23 page for you. You probably would find [the Eclipse page on 24 developer.android.com](http://developer.android.com/sdk/eclipse-adt.html) more useful.* 25 26 ## Basic setup ## 27 28 First, it's important to make sure the regular Android development system is set up. 29 30 cd /path/to/android/root 31 make 32 33 **Important**: 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. 34 35 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. 36 37 cd /path/to/android/root 38 cp development/ide/eclipse/.classpath . 39 chmod u+w .classpath 40 41 Now edit that copy of `.classpath`, if necessary. 42 43 ### Increase Eclipse's Memory Settings ### 44 45 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 46 47 /Applications/eclipse/Eclipse.app/Contents/MacOS/eclipse.ini 48 49 Memory-related defaults (as of Eclipse 3.4): 50 51 -Xms40m 52 -Xmx256m 53 -XX:MaxPermSize=256m 54 55 Recommended settings for Android development: 56 57 -Xms128m 58 -Xmx512m 59 -XX:MaxPermSize=256m 60 61 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. 62 63 Now start Eclipse: 64 65 eclipse 66 67 Now create a project for Android development: 68 69 1. If Eclipse asks you for a workspace location, choose the default. 70 71 2. If you have a "Welcome" screen, close it to reveal the Java perspective. 72 73 3. File > New > Java Project 74 75 4. Pick a project name, "android" or anything you like. 76 77 5. Select "Create project from existing source", enter the path to your Android root directory, and click Finish. 78 79 6. Wait while it sets up the project. (You'll see a subtle progress meter in the lower right corner.) 80 81 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. 82 83 *Note:* Eclipse 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. 84 85 ### When You Sync ### 86 87 Every time you repo sync, or otherwise change files outside of Eclipse (especially the .classpath), you need to refresh Eclipse's view of things: 88 89 1. Window > Show View > Navigator 90 91 1. In the Navigator, right-click on the project name 92 93 1. Click Refresh in the context menu 94 95 ### Adding Apps to the Build Path ### 96 97 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: 98 99 1. Project > Properties 100 101 1. Select "Java Build Path" from the left-hand menu. 102 103 1. Choose the "Source" tab. 104 105 1. Click "Add Folder..." 106 107 1. Add your app's `src` directory. 108 109 1. Click OK. 110 111 When you're done, the "source folder" path in the list should look like 112 113 android/packages/apps/YOURAPP/src 114 115 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. 116 117 ## Eclipse formatting ## 118 119 You can import files in `development/ide/eclipse` to make Eclipse 120 follow the Android style rules. 121 122 1. Select Window > Preferences > Java > Code Style. 123 124 1. Use Formatter > Import to import `android-formatting.xml`. 125 126 1. Organize Imports > Import to import `android.importorder`. 127 128 ## Debugging the emulator with Eclipse ## 129 130 You can also use eclipse to debug the emulator and step through code. First, start the emulator running: 131 132 cd /path/to/android/root 133 . build/envsetup.sh 134 lunch 1 135 make 136 emulator 137 138 If the emulator is running, you should see a picture of a phone. 139 140 In another shell, start DDMS (the Dalvik debug manager): 141 142 cd /path/to/android/root 143 ddms 144 145 You should see a splufty debugging console. 146 147 Now, in eclipse, you can attach to the emulator: 148 149 1. Run > Open Debug Dialog... 150 151 1. Right-click "Remote Java Application", select "New". 152 153 1. Pick a name, i.e. "android-debug" or anything you like. 154 155 1. Set the "Project" to your project name. 156 157 1. Keep the Host set to "localhost", but change Port to 8700. 158 159 1. Click the "Debug" button and you should be all set. 160 161 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. 162 163 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. 164 165 ## Bonus material ## 166 167 Replace Ctrl with the Apple key on Mac. 168 169 shortcut | function 170 -------------|----------------- 171 Ctrl-Shift-o | Organize imports 172 Ctrl-Shift-t | load class by name 173 Ctrl-Shift-r | load non-class resource by name 174 Ctrl-1 | quick fix 175 Ctrl-e | Recently viewed files 176 Ctrl-space | auto complete 177 Shift-Alt-r | refactor:rename 178 Shift-Alt-v | refactor:move 179 180 ## Eclipse is not working correctly, what should I do? ## 181 182 Make sure: 183 184 - You followed the instructions on this page precisely. 185 186 - Your Problems view doesn't show any errors. 187 188 - Your application respects the package/directory structure. 189 190 If you're still having problems, please contact one of the Android mailing lists or IRC channels. 191 192
