InstallingEnvironment

Introduction

Developing an AnnotationProcessor is not something very common, but hopefully we went through many different bugs and solved them. We now have a quite stable and clean dev environment, so you should be able to contribute to AndroidAnnotations by following these simple steps.

Installing the environment

• Install Git
• Install Maven >= 3.1
• Install Eclipse Luna
• Install the latest version of the Android SDK and the Android Eclipse Plugin (ADT)
• Install the latest version of the m2e, m2e-apt and m2e-android and PDE plugins:
  • Start Eclipse, then select Help > Install New Software.
  • Click Add, in the top-right corner.
  • In the Add Repository dialog that appears, enter "m2e-android" for the Name and the following URL for the Location: http://rgladwell.github.io/m2e-android/updates
  • In the Available Software dialog, select the checkbox next to Android for Maven Eclipse and click Next.
  • In the next window, you'll see a list of the tools to be downloaded. Click Next.
  • Read and accept the license agreements, then click Finish. If you get a security warning saying that the authenticity or validity of the software can't be established, click OK.
  • Install Maven Integration for Eclipse JDT APT from http://download.jboss.org/jbosstools/updates/m2e-extensions/m2e-apt with the same method.
  • Install PDE: work with All Available Sites and install General Purpose Tools -> Eclipse Plug-in Development Environment.
  • When the installation completes, restart Eclipse.

Getting the sources

• Fork the repository
• Clone the repository to your computer:

git clone git@github.com:YOUR_USERNAME/androidannotations.git

Importing in Eclipse

• Go to File > Import > General > Existing Projects into Workspace, click Browse, select the eclipse-dependencies folder and click Open. Click Finish.

• Go to File > Import > Maven > Existing Maven Projects, click Browse, select the AndroidAnnotations folder and click Open then uncheck the last two to keep only /pom.xml and androidannotations/pom.xml checked. Click Finish.

• In the androidannotations project, right click on src/main/eclipse and select Build Path > Use as source folder.

• Right click on the androidannotations project, select Build Path > Add Libraries.... Select Plug-in Dependencies, select org.eclipse.core.runtime_XXX.jar and click Finish.

Running the dev Eclipse instance

• Go to Run > Run Configurations... and double click on Eclipse Application. Go to the Arguments tab and add -XX:MaxPermSize=256m in VM arguments. Then click Run.

Note: I encountered a problem with running Eclipse on a 32bits JVM with a 64bits Mac, which was simply solved by adding -D32 to the VM arguments of the run configuration.

• This new eclipse is launched on a new workspace.

Note: you can use a free jrebel license (free for OSS projects) and use it for automatic class reloading. You just need to add ${jrebel_args} to the VM arguments, and enable jrebel. You may also start this new Eclipse instance in Debug, put breakpoints in AndroidAnnotations code and benefit from hot code swapping.

Importing the test project

• Go to File > Import > Maven > Existing Maven Projects, click Browse, select the AndroidAnnotations/functional-test-1-5 folder and click Open and then Finish.

• Right-click the project, choose Properties, go to Maven > Annotation Processing

• Check Enable project specific settings

• Select Automatically configure JDT APT

• If you get weird errors about some Android or JDK classes not being found and see unable to get system library for the project on eclipse ide when looking at the build path, check this out.

• The generated classes may not be there yet, so do a Project > Clean... to let AndroidAnnotations generate them.

• A bit of dark magic: if you still have compilation errors on a project, claiming that the generated classes are missing, open the project Properties > Java compiler > Annotation Processing and change the name of the Generated source directory. Click Apply, then change it back to target/generated-sources/annotations and apply again. You should be good to go, if not, then let us know ;-) .

Running the functional tests

• Right click on functional-test-1-5 and select Run As > JUnit Test. Check Use configuration specific settings, select Eclipse JUnit Launcher and click OK.

• If the test fails to start due to no test cases, go to Run configurations -> JUnit -> functional-test-1-5. Select Run all test in the selected project and browse the project by after clicking the Search button. In the Test runner configuration, choose JUnit 4, then Apply.

• The test may take a bit of time to run, because Robolectric has to load tons of classes.

Notes:

To start the tests, just run the previously created Run Configuration

To see your changes in the code, you have to restart the 2nd eclipse. We didn't find any better solution, but tell us if you do!