[Cassandra Wiki] Update of "RunningCassandraInEclipse" by DavidAllsopp

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cassandra Wiki" for change notification.

The "RunningCassandraInEclipse" page has been changed by DavidAllsopp:
http://wiki.apache.org/cassandra/RunningCassandraInEclipse?action=diff&rev1=26&rev2=27

  Eclipse is open source. Download Eclipse from http://www.eclipse.org/downloads/. There is no need for the Enterprise Edition (EE) version of Eclipse. Hence
  "Eclipse IDE for Java Developers" is good enough. 
  
- Cassandra is using Git and Subversion for version control. In this tutorial we will checkout Cassandra from Subversion. To be able to do this we need a Subversion plugin for Eclipse (there is no native svn (or git) support in Eclipse). Feel free to use your favorite Eclipse Subversion plugin. Though, this tutorial will use the Subclipse (http://subclipse.tigris.org/) Ecplise Subversion plugin. 
+ Cassandra is using Git and Subversion for version control. In this tutorial we will checkout Cassandra from Subversion. 
  
- = Setup Cassandra =
+ The previous version of this guide used the Subclipse (http://subclipse.tigris.org/) Eclipse Subversion plugin. However, over time, the instructions became out-of-date and confusing - if you are currently using Subclipse or Subversive successfully with Cassandra then please add a new section below!
  
- Preconditions: JDK6, Ant (http://ant.apache.org/), Eclipse + Subversion plugin 
+ For the moment, we will a command-line Subversion client.
  
+ = Checkout and setup Cassandra =
- Start Eclipse and open perspective "SVN Repository Exploring" (Window -> Open Perspective -> Other... -> SVN Repository Exploring)
- (If you dont have perspective "SVN Repository Exploring" you need to install an Eclipse Subversion plugin, eg. Subclipse or Subversive)
  
- {{attachment:WindowOpenPerspectiveOther-1.png}}
+ Preconditions: JDK6, Ant (http://ant.apache.org/), Eclipse, SVN client.
  
+ From the console, checkout the code using SVN. Here we assume you are checking out the latest trunk, but browse http://svn.apache.org/repos/asf/cassandra/ for all available versions...
- Right mouse click in the "SVN Repositories" view, choose New -> Repository Location...
- Enter https://svn.apache.org/repos/asf/cassandra/ as the Url and the press "Finished". Expand the directory and right mouse click on 'trunk' and choose 'checkout'.
  
- {{attachment:SVNCheckout-3.png}}
+ {{{
+ svn checkout http://svn.apache.org/repos/asf/cassandra/ cassandra-trunk
  
+ cd cassandra-trunk
  
- Make sure that the first radio button "Check out as a project configured using the New Project wizard" is selected and press "Finish".
+ ant build
  
- {{attachment:CheckoutFromSVN-4.png}}
+ ant generate-eclipse-files
  
- Select "Java" -> "Java Project"
+ }}}
  
- {{attachment:NewProject-5.png}}
+ The `ant build` step may take some time as various libraries are downloaded. This step will do a whole lot of good things, eg. generate the CLI grammar with ANTLR, generate Thrift RPC code...
  
- Pick an appropriate project name (hint cassandra). Press "Finish" without do any changes. If the IDE asks you to open the "Java Perspective" I recommend you you to do so. Also if the "Confirm Overwrite" dialog appears just accept.
+ '''It is important  that you generate the Eclipse files with Ant before trying to set up the Eclipse project'''. In the previous version of this tutorial, we executed the Ant tasks after importing the code into Eclipse, which tends to confuse Eclipse mightily, leaving you stuck with about 2000 compiler errors that you can't get rid of.
  
- {{attachment:NewJavaProject-6.png}}
+ = Setup Eclipse =
  
- After the following steps your project workspace should look something like this:
+  *Start Eclipse.
  
- {{attachment:InitialEclipseProjectWorkspace-7.png}}
+  *Click the `File->New->Java Project` menu
  
- As you might have noticed (currently) Eclipse is mad and we need to perform some additional steps (generate CLI (Command Line Interface) grammar, avro, thrift and add some third party dependencies to the Eclipse build path (java classpath)) to fix this.
+  *Enter "cassandra-trunk" as the project name (assuming you checked the code out into the folder cassandra-trunk as shown above.  If your project name doesn't match the top-level folder name you may get problems).
  
+  *Untick "Use default location" and browse to the top-level folder you just checked out (cassandra-trunk).
- Right click on the build.xml (in your project root) -> "Run As" -> "Ant Build".
- This will do a whole lot of good things, eg. generate the CLI grammar with ANTLR, generate avro and thrift code.
  
- '''UPDATE''' New for Cassandra 0.7.1: Right click on the build.xml again (in your project root) -> "Run As" -> "Ant Build..." and this time select "generate-eclipse-files". This will automatically build most of the jars in the right places. All that is left to do is to is the very next step in which you add all of the jars in the lib/ folder to the Build Path and all the dissociations should dissappear. If so, skip to the "Run Cassandra" section.
+  *Click "Next"
  
+  *Verify that the Default Output Folder is `cassandra-trunk/build/classes/main`. Eclipse normally defaults to `bin` which we DO NOT want for Cassandra.
- Next thing you want to do is to add all the needed third party libraries to the build path. 
- Expand the lib/ folder and find a bunch of jar files. Shift select all of them and right mouse click and choose "Build Path" -> "Add to Build Path".   
- This will force Eclipse do update the entire workspace, so please be patient. Some of the errors should also have disappeared by now (not all though).
  
+  *Click "Finish"
- '''UPDATE''' There are several more jars required on the build path which will be available after successful completion of the Ant build described above. To add these jars, expand the build/lib/jars directory (if it is not there you may need to right-click the project directory and select "Refresh") add the following using the same method above: 
-  * hadoop-core-0.20.2-320.jar 
-  * hadoop-streaming-0.20.2.320.jar 
-  * jna-3.2.7.jar 
  
- '''UPDATE UPDATE!''' as of 0.8.1, at least, all the jarfiles are added to the build path by generate-eclipse-files (although there may be a slight bug - see https://issues.apache.org/jira/browse/CASSANDRA-2854). The generated code in the next step is also added automatically. At the time of writing this didn't seem to work if checking out trunk, but worked for the 0.8.1 branch.
+ (The Eclipse console will show a few lines of output as the build process runs).
  
- {{attachment:AddToBuildPath-9.png}}
+ That's it.  There should be no errors shown in the Problems view or the Package Explorer.
  
+ '''TODO: in fact, I don't think the Problems view is working at all, since it doesn't shown any warnings, and doesn't show errors if you provoke one by mis-editing and saving a source file.'''
- The final step is to add the generated Java code to the Eclipse build path. Expand and select interface/thrift/gen-java, right click -> "Build Path" -> "Use as Source Folder". Do the same for interface/avro/gen-java and src/gen-java.
- 
- '''UPDATE''' Currently the source directories interface/avro/gen-java and src/gen-java have some naming conflicts. Unless you plan to do work on the Avro API (you probably do not), leave off interface/avro/gen-java from the build path. 
- 
- {{attachment:AddThriftToBuildPath-10.png}}
- 
- If Eclipse still complains about compile errors it is because 'src' (and not 'src/java') is added as source folder. To fix this I recommend to remove 'src' from build path and add 'src/java' to the build path (just like you did for the thrift and avro generated code).
- 
- Now, if you are lucky, your Eclipse workspace should look something like this:
- 
- {{attachment:FixSrcJavaSourceFolder-11.png}}
  
  = Common Errors =
  
@@ -92, +76 @@

  
  (See https://bugs.eclipse.org/bugs/show_bug.cgi?id=302296 for recent history of the efforts to get Eclipse up to this version of Ant!)
  
+ === Variable references non-existent resource ===
+ 
+ If you get the following (probably when refreshing the project after first setting it up):
+ 
+ {{{
+ Errors occurred during the build.
+ Errors running builder 'Integrated External Tool Builder' on project 'Cassandra-trunk'.
+ Variable references non-existent resource : ${workspace_loc:/cassandra-trunk/build.xml}
+ Variable references non-existent resource : ${workspace_loc:/cassandra-trunk/build.xml}
+ }}}
+ 
+ This probably means that the project name you chose in Eclipse doesn't match the top-level directory (must match exactly, including capitalisation). Go to `Project->Properties->Builders`, select `Cassandra-Ant-Builder`, `Edit`, and fix the `Build File` and `Base Directory` to match the name in Eclipse (the easiest way is just to browse to the right file/folder).
+ 
+ === Other compile errors ===
+ 
+ If Eclipse still complains about compile errors it may be because 'src' (and not 'src/java') is added as source folder. To fix this I recommend to remove 'src' from build path and add 'src/java' to the build path.
+ 
+ 
  = Unit Tests =
  
  ''Question - can JUnit tests be run through Eclipse, or should they only be run using the Ant build target?''
  
  Note that some of the unit tests use Java `assert` as well as JUnit assertEquals() etc, so they need to be run with assertions enabled in the JVM (using `-ea`). If you just run them directly in Eclipse/JUnit without assertions enabled, you may get false test passes.
+ 
  
  = Run Cassandra =