Eclipse Tips and Customization

Eclipse with the Android plugin is a powerful IDE with many features, not all of which are found in the most obvious places or are well documented. At least in the Linux version under newest releases of operating systems, it also has the occasional bug that you have to work around. We collect here some tips and customizations that may be useful.

General

• When you first start Eclipse and try to develop an Android project you will be asked to indicate where the Android SDK is. Select Window > Preferences > Android and fill in the SDK Location field by using the Browse button to navigate to the directory in which the SDK was installed. The following figure
  
  
  
  illustrates for an installation on a Linux system. Then click OK. Eclipse should then remember where the Android SDK is for subsequent projects.



• If you modify Java or XML files external to Eclipse on a particular machine (e.g., replacing the files with files that you have modified on another machine) the file system will often be out of synch in Eclipse. Remedy that by selecting the project and selecting File > Refresh (or F5), or right-click on the project and select Refresh from the popup menu. Then do a clean build by selecting Project > Clean, selecting the project, and clicking OK.


• Likewise, if you add new files manually to directories they may not show up in the Eclipse project tree unless you right-click on the directory and select Refresh. To be certain, you should probably force a clean build after the files show up, as described above.


• If you are debugging on an emulator or device and have already run the program, for some changes (for example, modified drawable resources) Eclipse may not recognize that something has changed and you will get a message that the old activity has been brought to the foreground rather than the new activity started. In that case you can force Eclipse to execute the new modified version by forcing a clean build (Project > Clean) before launching the app.


• If you get the error: "Android requires .class compatibility set to 5.0. Please fix project properties", one way to proceed is to right-click on the project and select Android Tools > Fix Project Properties. But this may then generate a problem with @Override because under Java 5 @Override can only be used to override a method in a base class, but with 6 @Override can also be used if your method implements a method in a base interface. Then you may get error messages that @Override is not allowed at places where it would be under Java 6. To fix this: Select project, then Project > Properties > Java Compiler, check the Enable project specific settings box, then set the Java Compliance Level to 1.6 (further discussion).


• When import of new Android packages is required Eclipse can identify the needed packages one by one, but you can globally import all missing packages by hitting ctrl-shift-O. (However, at least in the Linux versions, Eclipse sometimes fails to realize that you need to import a particular Android package and you have to realize it and type it in by hand.)


• Applications must be digitally signed. For development within Eclipse, Android takes care of this under the hood by generating a "debug" signing certificate in a keystore called debug.keystore. The Eclipse plug-in uses this certificate to sign each application build, but the debug certificate is valid for only a certain period (currently 1 year). Thus, after some date you may suddenly get an error message along the lines of

  
      Error generating final archive: Debug certificate expired on 1/18/11 2:32 PM!
  
  

  and none of your projects will build. The problem may be even less obvious than this, since you may just get a red x on a project when you try to execute it (even though it compiles with no errors), with an error message "Your project contains errors ..." and no further information in the main display. This is typical of errors that occur in things like the build path, rather than in individual files of the project. In that case, you can get further information by opening the Problems window using Window > Show View > Problems and expanding any error messages in that window. The overall solution to the problem is to close Eclipse, remove the debug.keystore file, and then restart Eclipse, which will force it to generate a new and now valid debug certificate.
  
  
  

  The location of debug.keystore is installation-dependent. It can be found from Eclipse by selecting Window > Preferences > Android > Build, which should give a window with a field displaying the path to debug.keystore. On my Linux system, for example, it is at /home/guidry/.android/debug.keystore.

  
  
  Note that if the debug certificate changes, things that depend on it may have to be regenerated. For example, if you have mapping applications that use the Google Maps API, you will have to use the new debug certificate to generate a new mapping API key (see The Maps API Key).




Since expiration of the debug certificate often generates misdirection with its symptoms, and it occurs on just a long enough timescale to make it easy to forget the lesson you learned a year ago, it is easy even for an experienced programmer to waste time searching for why her system no longer works. Thus, you may find it useful to look at the date of the current debug.keystore file on your system and put an entry in your calendar with a alarm that repeats yearly a day or two before that date.

Editors

• To toggle line numbers on and off in code display, right-click on the leftmost part of the code display field and select or unselect Show Line Numbers.


• To comment a block of text in a Java file, select the text with the mouse and choose Source > Add Block Comment (shift+ctrl+/). To un-comment a commented block, select it with the mouse and choose Source > Remove Block Comment (shift+ctrl+\)


• To bookmark lines for easy reference
  
  
  1. Add a bookmark by right-clicking on the line number and selecting Add Bookmark (or from the menu Edit > Add Bookmark). In the window that pops up, give the bookmark a name and click OK. To remove a bookmark, right-click on the bookmarked line and choose Remove Bookmark (a bookmark can also be removed using the bookmark window, as described below).
  
  
  2. Now a blue mark appears to the left of the line number indicating the bookmark (see line 55 in the following figure).
     
     
     To navigate among bookmarks, Select Window > Show View > Other. then choose General > Bookmarks to open the bookmarks window (see the above figure). Click on the iconize command (short horizontal line on the bottom right in the above figure) to iconize the bookmarks menu at the bottom right. Now it can be recalled just by clicking on the bookmarks icon at the lower right.
  
  
  3. Double click on a bookmark in the bookmark window to go to a bookmark. You can also delete a bookmark by right-clicking on the bookmark in the bookmark window and selecting Delete (this deletes the bookmark, not the line), and the bookmark window has various options like sorting that can be accessed through a menu displayed by clicking the down triangle at the upper right of the bookmark window (see the above figure).
  
  


• To change the Java editor font, select Window > Preferences and then in the resulting window select General > Appearance > Colors and Fonts, and then in the resulting window select Java and under it Java Editor Text Font. Then click Edit and select the desired font and size. Then click OK and OK. XML files are displayed in a separate editor. To change its font follow the same steps as above, except for the last part of the path choose Colors and Fonts > Basic > Text Fonts.


• To override a method in a Java class: Right click on the Eclipse window for the file, then choose Source > Override/Implement methods, then choose the method from the popup and where you want it inserted.


• Eclipse has fairly sophisticated global renaming capability. To globally rename a variable, select it with the mouse and then choose Refactor > Rename from the menu (shortcut ctrl-alt-R). Then type the new name in the highlighted field and hit Enter on the keyboard. This will generally work even when the variable in question is defined across multiple files within the project. For example, renaming a class will rename it in all files, and also change the name of the file holding the class definition if required (since in Java the file must have the same name as the primary class that it contains). To rename a file, right-click on it in the left Eclipse panel, select Refactor > Rename, give the new name and check the Update references box in the resulting window, and click Finish. The corresponding references in XML files (including AndroidManifest.xml) will generally not be updated by this refactoring so those typically have to be edited by hand to bring them into agreement with changes in the Java files.


• It is often useful to display two files side-by-side in the Eclipse editor. With two files open in the editor (two tabs at the top), grab the tab of the rightmost file and drag it to the right until the cursor changes to a right-arrow and an outline of the new position shows, and release. (You will probably want to expand Eclipse to the full screen and close any other panels displayed horizontally to give sufficient room to edit two files side-by-side.) To change back, grab the tab of the right file and drag to the left until the cursor changes to a stacked folders image and release. You can also open a file (the same file, or a different one) in a separate window by clicking Window > New and then opening the file in the new window. This permits you to have an editor open on two different files, or on different parts of the same file, for example. If you are viewing two files side-by-side and open additional files, each will open as a tab in the file view that has focus when the new file is opened. You can repeat the above dragging procedure to open three or more files side-by-side, if you have enough screen real estate to make that useful.

Version Control

If you use version control software like SVN (and you should use version control if you do anything extensive), there may be some special issues associated with the internal file management of Eclipse in its build cycle.

Subversion

If you use SVN for version control it can be a little tricky. To get SVN to work correctly you should implement the following steps in the order given.

• To prevent Eclipse from copying the .svn directory from the source directories to the bin directory as part of its build, you should add .svn as a filtered resource: Select the project and go to Project> Properties > Java Compiler > Building, check the Enable project specific settings box if necessary, open Output folder, and add .svn to the list of Filtered resources (Note: entries in the list are separated by commas). Click OK. Further discussion: 1, 2, 3, 4.


• Physically remove the bin and gen directories from the project before adding the project to the SVN repository and committing it, and don't archive the .metadata directory of the Android workspace.
  
  

  The contents of the bin and gen directories are generated entirely by Eclipse and it will create these directories if they are missing. You may get an error message that the (machine-generated) R.java file is missing from the gen directory in the first build after deleting bin and gen, but it should go away if you build the project again (Project > Clean). In rare instances you may have to build the project twice to get the errors associated with missing machine-generated R. files to go away.

  
  


• Once the new project is committed to version control, use the SVN propedit command (svn propedit svn:ignore .) to permanently remove the bin and gen directories from version control and commit this change. DO NOT UNDER ANY CIRCUMSTANCE COMMIT THE bin DIRECTORY TO THE REPOSITORY.

Use of the Subclipse plugin has also been recommended to manage these issues, but I have not tried it.

CVS

I have not tried CVS with Eclipse but there is a CVS plugin for Eclipse.