InstallingEnvironment - shiraji/androidannotations GitHub Wiki

Introduction

Developing an annotation processor 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

Getting the sources

  • Fork the repository
  • Clone the repository to your computer:
git clone [email protected]:YOUR_USERNAME/androidannotations.git

Importing into IntelliJ

  • First make sure the project builds on the command line. Open a terminal in the AndroidAnnotations folder inside the repository, then execute mvn install.
  • Go to File > Open > browse folder the AndroidAnnotations/pom.xml file in the repository and double-click it.
  • Unfortunately, due to an IntelliJ bug, you have to adjust the AndroidManifest.xml and res folder paths manually. Go to File > Project structure > Facets. For each facet, in the Structure tab, change the manifest to point to src/main/AndroidManifest.xml inside the module, and the resources directory to point to src/main/res inside the module. In the Maven tab, uncheck the Manifest and Resources directory checkboxes, so IntelliJ will not undo your settings when you reimport the project.

Running the compile-time tests

Compile-tests can be found under the src/test/java folder of the processor modules. These tests can verify the validation, and also check whether the generated compiles, and contains the expected strings. But does not run the generated code.

  • To run these tests, simply open a test class, and in the left side of the editor, click the test marker. You can also debug them in this way, the debugger will hit the breakpoints you put in the processor code.
  • Alternatively, you can right click a package, or the processor module itself in the Project explorer, then select Run tests in or Debug tests in.

Running the functional tests

These tests can be found in the test modules (xx-test) under the src/test/java folder. These tests verify that the generated code compiles, and also run it then assert the expected runtime behavior.

  • To run these tests, right click the folder / file in the project explorer -> Run and select the second option (window icon with two arrows). It is not possible to run JUnit tests from the editor unfortunately, due to a bug.
  • Alternatively, you can right click a package, folder or the test module itself in the Project explorer, then select Run tests in or Debug tests in.

Debugging processing in the test projects

It is little bit trickier to debug the code generation of the xx-test modules, because you have to attach the debugger to the compiler itself.

  • Go to File > Settings > Build, Execution, Deployment > Compiler. In the Shared build process VM options field, enter -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005, then click OK.
  • Go to Run > Edit configurations. Add a new Remote configuration with the green plus button.
  • Go to an annotated class in a test module, change it. Then click Build > Make module. The compilation will wait for you to attach the debugger.
  • Run the previously created remote configuration. Now you are debugging the processing, and which will stop at breakpoints.

Note: You may have to run the remote configuration several times, as the compiler will wait when building the other dependent modules. We did not found a way to modify the compiler settings only for the test module, please share it, if you do.

Note: Do not forget to remove the flags in Shared build process VM options if you do not want to debug, because the build will always pause if you hit Make (due to suspend=y).

Adjusting IntelliJ settings for our code style

We require strict rules for coding styles, and this is enforced in the command line build. However it is much more convenient to setup the code formatter instead of fixing it manually after broken builds.

  • Install the Checkstyle IDEA and Eclipse Code Formatter plugins into IntelliJ.
    • File > Settings > Plugins > Browse repositories.
    • Search for these plugins, select them and install them with the green Install button.
    • Restart IntelliJ.
  • You can adjust the formatter settings to meet with the conventions which AndroidAnnotations uses.
    • Go to File > Settings > Other settings > Eclipse Code Formatter.
    • Check Use the Eclipse code formatter, and browse for the Eclipse Java Formatter config file, select AndroidAnnotations/eclipse-formatter.xml.
    • Under the imports section, check From file and browse for AndroidAnnotations/eclipse.importorder.
    • We disallow star imports, so you have to disable them:
      • go to Editor > Code style > Java > Imports.
      • In the Class count to use import with '*' and Names count to use import with '*' boxes, enter 100000.
      • Click OK.
  • You can setup the Checkstyle plugin, so the coding style is verified right inside the IDE editor.
    • Go to File > Settings > Other settings > Checkstyle.
    • Check the Scan test classes box.
    • Hit the green plus button.
    • In the opening window, enter AA in the Description and in the File field, browse for the AndroidAnnotations/checkstyle-checks.xml file inside the repository, click Next.
    • In the next window, under the value field, enter the full path of the AndroidAnnotations/checkstyle-suppressions.xml file, and click Next.
    • Check the Active checkbox next to your newly added configuration, and click OK to close the settings window.