Setting up development environment

From Whole Brain Catalog

Jump to: navigation, search

Our developers have been using Eclipse to build the Whole Brain Catalog. Eclipse is also an open source community, whose projects are focused on building an open development platform. Below we have provided instructions in how to view and add the the Whole Brain Catalog code within Eclipse.

Contents

[edit] Getting Started

You will need:

  • Java 1.6
  • Eclipse (Ganymede version Recommended)

At the end of this process you will have:

  • Installed Eclipse
  • Installed Subclipse
  • Connected to Maven
  • Loaded the source code into Eclipse

In order to ensure a proper installation, make sure that yo go through all the steps of the instructions.

[edit] Downloading Java and Eclipse

Ensure you have JDK 1.6 installed in your computer

  • If you aren't sure if you have a Java JDK, download. Note that the JDK is the java development kit, whereas the JRE is the java runtime environment. The JDK contains the JRE, but you can download just the JRE without the JDK (so be careful to avoid this).
  • To install the JDK, all you need to do is run the downloaded JDK file. The installation process should be fairly straightforward, if you encounter issues during the installation visit the Java 6 Documentation website for details.
  • The JDK software is installed on your computer, for example, at [For Windows Systems] C:\Program Files\Java\jdk1.6.0_14 or [For Unix Systems] /usr/jdk/jdk1.6.0_14. You can move the JDK software to another location if desired.

Step 1B. Ensure you have Eclipse installed in your computer

  • Get Eclipse. If you have no preferences choose Eclipse IDE for Java EE Developers.
  • To install Eclipse, all you do is unpack the zip file download in the desired directory. When you unzip the file, it creates a subdirectory called "eclipse", with multiple subdirectories under that. So, for example, in Windows you could unpack the zip file in the root directory (e.g., C:\) and Eclipse would be installed in C:\eclipse. Note that installing Eclipse does not change the Windows registry. If you encounter any problems during the installation of eclipse, visit the Eclipse Installation website for more details.

[edit] Setting up the Eclipse Environment

  • First you will need to go to the folder where eclipse exists and edit the "eclipse.ini" file. At the beginning of the file you add the following: 
-vm
C:\Program Files\Java\jdk1.6.0_20\bin

Your path for the jdk may be different. Double check this. One you way you can find out which java version you have is by going to the folder where you have Java install and checking for a folder that starts with "jdk".

  • Get Subclipse (SVN Plugin for Eclipse)
    • Go to the menu Help->Software updates...
    • From this window, choose the tab labeled "available software".
    • Click "Add Site..." and type the following. Once you have done so click through all of the subsequent opportunities to accept and say OK to install the software. 
 Name: Subclipse 1.2.x (Eclipse 3.2+)
 URL:  http://subclipse.tigris.org/update_1.2.x
    • Check the boxes for "Maven integration" and "Maven Optional Components"
      • If you run into a problem installing these bits, your eclipse may be missing a necessary library. For me, the problem was with a library called "Zest". I found it here and installed it. Then I had to install the maven integration again.
  • Go to Window->preferences, and look under Maven->installations. There you will see the path that Eclipse expects to find a file called "settings.xml". Unfortunately, eclipse does not create this for you, so we'll have to.
    • Click on the blue underlined text that says "User Settings". This will open up the eclipse xml editor that will let you create the settings.xml
      • If this does not work: You must manually create the file at the specified path. You can do this by opening notepad and saving it as "settings.xml" You should save it in C:\Documents and Settings\yourusername\.m2\settings.xml Follow the rest of the instructions below.
    • After clicking from the "Design" tab at the bottom of the eclipse xml editor to the "Source" tab, cut and paste the text in this link: new settings.xml:

[edit] Downloading Whole Brain Catalog Source Code

  • Use Eclipse to download Whole Brain Catalog source code:
    1. Window->Show View->Other...
    2. Choose SVN->SVN Repository
    3. Right click within the SVN Repository View that comes up and click New->Repository Location...
    4. Follow this link to go to a web browser and log into your Google account.
    5. You should have ended up at the Google Code repository source page
    6. If you are one of the following users (@gmail.com) you have an account that is activated for submitting back to the project. If you are not on this list you can request access on the developer's forum.
      • stephen.larson
      • sarah.maynard1
      • caprea
      • piperfloyd
      • testpilot0
      • davlit0917
      • asceticmonk
      • imostafavi
    7. Back in Eclipse, for the URL, IF YOU ARE A REGISTERED USER, put: https://wholebrain.googlecode.com/svn/ If asked about a digital certificate, Accept Permanently. IF YOU ARE NOT A REGISTERED USER, put: http://wholebrain.googlecode.com/svn/ (note that one URL uses https and the other usese http).
    8. You will be asked for login information. Use the Google account username and the password at this link
    9. You should now have an item listed in the SVN Repository view in Eclipse. Drill down into the tree view to wbc->trunk.
    10. Right click on wbc/trunk and choose Checkout...
      1. You will be prompted to check out the project. Choose "Check out as a project configured using the New Project Wizard".
      2. In the "New Project" window that pops up, select Java->Java Project and hit Next
      3. Do NOT install the code into a path with spaces (like Documents and Settings in Windows). It will cause problems compiling. You can check this by looking at the greyed out "Directory" text box in the "Contents" group just under the Project name at the top of the window. If any of the directories in the path contains a space, you'll need to cancel this Window, open File->Switch Workspace...->Other... and pick a workspace at a location without a space in the file name. Once you have done that, come back and redo this step.
      4. In the next window, pick a project name you like (for example, "wbc")
      5. Click "Finish" and hit OK to any windows that popup
  • Right-click on the project, and from the Maven submenu, click "enable dependency management"
    • After you do this, you will notice a progress counter in the lower left hand corner of eclipse. Maven will be downloading a LOT of stuff at this point. Go grab a bite to eat or a coffee and wait for this progress counter to finish and disappear.
  • From the same Maven submenu, select "enable nested modules"
    • Somewhere around this point you may notice an operation in the lower right hand corner like "Changing nature (0%)" that continues for a long time. Be patient for this process as it is probably Maven downloading a bunch of subsequent dependencies it needs to function.
  • Right click on the project and look at Build path...->Java Build Path->Libraries tab. Click on the arrow to open up the JRE system library. Make sure this is pointing to a jdk 1.5 that is loaded on your machine. If it isn't, then press the Add Library... button and install a new JRE System library that does point to 1.5. On windows, its usually under C:\Program Files\Java. If you can't find a 1.5 JDK, you'll need to download it.
  • Create a new run configuration
    • Under "Maven", create a new run configuration. Name it "clean install". Make the workspace the root under your new project. In the box called "goals" type "clean install". Run this.
      • Again, Maven will be downloading a lot of stuff to make this work. This will take a LONG time. Be patient, take a break, and check in on it later.

[edit] Running the Server

A WBC server can be

  • Run locally within Eclipse
  • Deployed on a remote dedicated server

For the local option, follow the instructions below.

For the deployed option, see http://wiki.wholebraincatalog.org/wiki/How_to_Deploy_a_WBC_Server

Running the server for the first time requires some preparation followed by:

  1. Populating the database with sample data for the first time
  2. Starting the server

After this is done once, then each subsequent time, only the last step is required.

[edit] Download the WBC Server Source Code

This procedure is similar to that described above for the general WBC (Client) Source, so this download (or check out) is described in less detail.

  • Use the same repository referenced above (http://wholebrain.googlecode.com/svn/)
  • Right click on wbc-server/trunk and choose Checkout...
    • You will be prompted to check out the project. Choose "Check out as a project configured using the New Project Wizard".
    • In the "New Project" window that pops up, select Java->Java Project and hit Next
    • Do NOT install the code into a path with spaces (like Documents and Settings in Windows). It will cause problems compiling. You can check this by looking at the greyed out "Directory" text box in the "Contents" group just under the Project name at the top of the window. If any of the directories in the path contains a space, you'll need to cancel this Window, open File->Switch Workspace...->Other... and pick a workspace at a location without a space in the file name. Once you have done that, come back and redo this step.
    • In the next window, pick a project name you like (for example, "wbc-server")
    • Click "Finish" and hit OK to any windows that popup
  • Right-click on the project, and from the Maven submenu, click "Enable dependency management"
    • After you do this, you will notice a progress counter in the lower left hand corner of eclipse. Maven will be downloading a LOT of stuff at this point. Go grab a bite to eat or a coffee and wait for this progress counter to finish and disappear.
    • Somewhere around this point you may notice an operation in the lower right hand corner like "Changing nature (0%)" that continues for a long time. Be patient for this process as it is probably Maven downloading a bunch of subsequent dependencies it needs to function.
  • Right click on the project and look at Build path...->Java Build Path->Libraries tab. Click on the arrow to open up the JRE system library. Make sure this is pointing to a jdk 1.5 that is loaded on your machine. If it isn't, then press the Add Library... button and install a new JRE System library that does point to 1.5. On windows, its usually under C:\Program Files\Java. If you can't find a 1.5 JDK, you'll need to download it.
  • Create a new run configuration
    • Under "Maven", create a new run configuration. Name it "clean install". Make the workspace the root under your new project. In the box called "goals" type "clean install". Run this.
    • Again, Maven may be downloading a lot of stuff to make this work. This may take a some time. Be patient, take a break, and check in on it later.

[edit] Prepare Resource Files

Selected resources files in src/main/resources need to be checked and possibly modified for using this local server option.

[edit] hibernate.properties

The hibernate.properties file determines the database that the WBC server uses. We want to reference a local in-process HSQL database.

  • Make sure the hibernate.properties contains the line "hibernate.connection.url = jdbc:hsqldb:file:db/wbcdb".
    • If id does not, copy the entire contents of hibernateHsqlInProcess.properties (Ctrl-A, Ctrl-C) and paste this content into hibernate.properties overwriting its full content (Ctrl-A, Ctrl-V).

[edit] log4j.properties

The log4j.properties file controls the WBC server logging behavior. We want logging to the console.

  • Make sure the log4j.rootCategory property near the top of the file is set for INFO, CONSOLE
    • For example, log4j.rootCategory=INFO, CONSOLE

[edit] Eclipse run configurations

[edit] 1. Populating the Database

  • In the Eclipse Package view, select wbc-server
  • On the Eclipse menu, select Run > Run Configurations... to open the Run Configurations dialog box
  • In the left panel select Java Application
  • In the Run Configurations dialog, click the "New launch configuration" button
  • In the right panel enter name "wbc populate db"
  • On the Main tab
    • Browse and select the "wbc-server" Project
    • For Main class, use Search to locate the desired class [unique for each Run Configuration]
  • On the Arguments tab
    • Set Program arguments: org.wholebrainproject.wbc.server.util.PopulateDatabaseFromXML
    • Set VM arguments: -Xmx1000M
    • The Working directory should be ${workspace_loc:wbc-server} by either Default or Other
  • Click Apply to save the Run Configuration
  • Use this Run Configuration and click Run to populate the database
    • A Confirm Destruction dialog box should show affected database as HSQL, on localhost - in process, named wbcdb; click OK or Cancel
    • Currently this takes about 3 minutes
    • You can't start the server until this step has completed with a message "Database has been populated."

[edit] 2. Starting the WBC Server

  • In the Eclipse Package view, select wbc-server
  • On the Eclipse menu, select Run > Run Configurations... to open the Run Configurations dialog box
  • In the left panel select Java Application
  • In the Run Configurations dialog, click the "New launch configuration" button
  • In the right panel enter name "wbc server start"
  • On the Main tab
    • Browse and select the "wbc-server" Project
    • For Main class, use Search to locate the desired class: org.wholebrainproject.wbc.server.Server
  • On the Arguments tab
    • Set VM arguments: -Xmx1000M
    • The Working directory should be ${workspace_loc:wbc-server} by either Default or Other
  • Click Apply to save the Run Configuration
  • Use this Run Configuration and click Run to start the WBC server
    • You will see logging messages on the console
    • Confirm that it is running on your localhost by navigating your browser to http://localhost:8182/tangibles/slides and confirm that output comes out. If so, you should be ready to move on to running the client!

NOTE: The HSQL database is "in process"--it is part of the WBC server. If you run a Maven clean, it will delete the database.

[edit] Running the Client

  • Make sure you have the Maven Natives Plugin for Eclipse installed and working correctly:
  • Create a new run configuration for the class org.wholebrainproject.wbc.app.WholeBrainCatalog.
  • There are extended options for running a program in eclipse under Run->Run... Go to arguments and under VM arguments, type the following: -Xmx768m or -Xmx1024m or such.

[edit] Tips

  • Eclipse may complain to you about access restrictions to rt.jar unless you do the following. You can change compiler settings to not fail on those restrictions in workspace settings in Window -> Preferences -> Java -> Compiler -> Errors/Warnings -> Deprecated and restricted API -> Forbidden reference (access rules). Set from "error" to "warning".
  • Linux: Some installations of Eclipse (3.2+) may work better if you install two JDKs. Use JDK 1.5 to launch eclipse itself as shown below: 
 eclipse -vm (path_to _RE)/bin/java
 eclipse -vm /usr/lib/jvm/java-1.5.0-sun/bin/java (on linux)
  • this solves the problem of Eclipse crashing randomly, such as in dialog boxes. This does not solve errors in regards to compiling or running the WholeBrainCatalog3DClient

[edit] Links

Some update sites which may be of use for an empty version of Eclipse

Retrieved from "http://wiki.wholebraincatalog.org/wiki/Setting_up_development_environment"
Personal tools