Setting up Yanel in the Eclipse IDE

This document will get you started using Eclipse to develop/debug your Yanel project. To keep things simple and reliable it is recommend to checkout Yanel from git and build Yanel initially outside of Eclipse.

Depending on what you will be working on, you might need to import several projects into Eclipse. Basically there are 3 types of projects: Yanel itself, realms/websites and resources/controllers. Please note that importing Yanel into Eclipse as a project will not automatically import Yanel's resource types, they have to be imported separately, and one by one, as described below.

Importing Yanel

1. Checkout and build Yanel, if you have not yet done so.
2. Build an Eclipse project using the specific target "eclipse":
   

   cd {path/to/yanel/root}
   ./build.sh eclipse

3. In Eclipse, select File -> Import, to open the Import dialog.
4. Select General -> Existing Projects into Workspace, then click on Next.
5. Check "Select root directory", click on Browse, and select the Yanel root directory (i.e. where build.sh is located)
6. Make sure the Yanel project is selected (should be the only one), "Copy projects into workspace" is not selected, and click on Finish.

The project "yanel" should now be visible in the Package Explorer view in Eclipse's Java perspective.

Importing a (third party) realm/website

If you want to work on a realm that has a separate directory from the Yanel source, follow the following steps to import it as a project into Eclipse:

1. Make sure Yanel is installed properly and add the realm to Yanel.
2. Build an Eclipse project using the specific "eclipse" target with the realm's build file:
   

   cd {path/to/yanel/root}
   ./build.sh -f src/test/build.xml install-jar
   ./build.sh -f {path/to/realm/root}/build.xml eclipse
   

3. In Eclipse, select File -> Import, to open the Import dialog.
4. Select General -> Existing Projects into Workspace, then click on Next.
5. Check "Select root directory", click on Browse, and select the realm's root directory (i.e. where build.xml is located)
6. Make sure the realm project is selected (should be the only one), "Copy projects into workspace" is not selected, and click on Finish.

The realm should now be visible as a project in the Package Explorer view in Eclipse's Java perspective.

Importing resource types

If you want to work on a specific resource type that is either a resource type of Yanel, or one belonging to another realm, follow these steps to import it as a project into Eclipse:

1. Follow points #1-2 above if you have not already done so.
2. If the resource type you are importing belongs to an external realm, follow point #3 above in case you have not already done so. If the resource type you are importing belongs to Yanel, build an Eclipse project using the specific "eclipse" target with the resource's build file:
   

   cd {path/to/yanel/root}
   ./build.sh -f {path/to/yanel/root}/src/.../{resource-directory}/build.xml eclipse

3. In Eclipse, select File -> Import, to open the Import dialog.
4. Select General -> Existing Projects into Workspace, then click on Next.
5. Check "Select root directory", click on Browse, and select either a directory containing all the resource-types of your realm (they may be imported all at once), or the directory of the Yanel resource that you want to import ({path/to/yanel/root}/src/.../{resource-directory}, in this case you have to import them one by one).
6. Select the resources that you want to import as projects, make sure "Copy projects into workspace" is not selected, and click on Finish.

The resources should now be visible as projects in the Package Explorer view in Eclipse's Java perspective.

Debugging

To start debugging with Eclipse, start Tomcat in debug mode:

{path/to/yanel/root}/local/apache-tomcat-7.0.25/bin/catalina.sh jpda start

Alternatively, you can (theoretically) also use the Eclipse Tomcat Launcher or other Tomcat plugins. If you succeed in this, please document it here, or send a description to the Yanel developers mailing list.

Notes

Windows users, please configure your line endings as LF by setting Preferences -> General -> Workspace -> New text file line delimiter to "Unix".

 

---

 

TODO: Document how to create a debug configuration andhow to debug across multiple resource-types, which may still be tricky.