Setting up development environment: Helios

From Whole Brain Catalog

Jump to: navigation, search

Our developers have been using Eclipse to build the Whole Brain Catalog. Eclipse is 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 to the Whole Brain Catalog code within Eclipse.

Note: These instructions are for the Indigo version of Eclipse. Individuals have had mixed luck with Indigo, but for 64-bit Windows it seems to be the best option. To see the instructions for the tried and true versions of Eclipse (Ganymede and Galileo), see Setting up development environment.

At the end of this process you will have:

  • Installed JDK (7)
  • Installed Eclipse (Indigo)
  • Installed Subclipse
  • Installed Maven
  • Loaded the WBC source code into Eclipse
  • Properly setup the development environment to run WBC

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


[edit] Downloading and Installing Java and Eclipse

[edit] Install JDK 7

  1. Download JDK. 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).
  2. 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 7 Documentation website for details. Make sure to install the public JRE for the JDK.
  3. On 64-bit Windows download and install both the 32-bit and 64-bit versions of the JDK.
  4. The JDK software is installed at [For Windows Systems] C:\Program Files\Java\jdk1.7.0_## or [For Unix Systems] /usr/jdk/jdk1.7.0_##. You can move the JDK software to another location if desired.
    • On 64-bit Windows, the 32-bit version is installed at C:\Program Files (x86)\Java\jdk1.7.0_##

[edit] Install Eclipse Indigo

  1. Download Eclipse. Eclipse IDE for Java EE Developers is recommended. If you are using a 64-bit OS make sure to download the 64-bit version.
  2. 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. If you encounter any problems during the installation of eclipse, visit the Eclipse Installation website for more details.

[edit] Setting up the Eclipse Environment

  1. Go to the folder where eclipse exists and edit the "eclipse.ini" file. Notepad will not work since it uses UNIX line endings (WordPad and many others do just fine). At the beginning of the file add the following:
    C:\Program Files\Java\jdk1.7.0_02\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".
  2. You probably want to increase the memory Eclipse is allowed to use. The last line in "eclipse.ini" says something like "-Xmx512m". You can change this to "-Xmx1024m" for 1 GB of memory allowed for Eclipse.
  3. Start Eclipse. You will be asked to set a workspace. Make sure the workspace you select has no spaces in it.

[edit] Install Subclipse (SVN Plugin)

  1. In Eclipse, go to Help -> Install New Software...
  2. Click "Add..." and enter "Subclipse 1.8.x Update Site" for the name and "" as the location.
  3. Click "Select All"
  4. Click "Next", "Next", agree to the terms, and "Finish". More dialog boxes may show up (e.g. asking you to approve certificates), click the choice that lets you keep on installing. When done installing, click "Restart Now".

[edit] Install Maven Integration (Dependency Management Plugin)

  1. In Eclipse, go to Help -> Install New Software...
  2. Click "Add..." and enter "Maven 0.10.2" for the name and "" as the location.
    • Note: Maven 0.10.2 is the last version to support certain features used by WBC, do not install a newer version than this! Also, any version before 0.10.0 will not support Indigo.
  3. Check the box for "Maven Integration for Eclipse"
  4. Click "Next", "Next", agree to the terms, and "Finish". More dialog boxes may show up (e.g. asking you to approve certificates), click the choice that lets you keep on installing. When done installing, click "Restart Now".
    • If you run into a problem installing this your Eclipse may be missing a necessary library. One example is the library called "Zest". It can be found here. You will then have to install Maven Integration again.
  5. Go to Window -> Preferences...
  6. Choose Maven
  7. Check "Support multiple Maven modules mapped to a single Eclipse workspace project" and click "Apply"
  8. Choose Maven -> User Settings
  9. On this page it tells you where it expects to find the settings file (e.g. C:\Users\yourusername\.m2\settings.xml on Windows Vista and 7). That settings file does not exist yet. Open Notepad, copy and paste the settings.xml text, and save to where it expects to find the settings (make sure to NOT save as .txt but as All Files with .xml).
  10. In Eclipse, with the Maven User Settings still open, click "Browse..." and select the settings.xml file. It should no longer say the file doesn't exist and give you an option to open it.
  11. Click "Ok"

[edit] Downloading the Whole Brain Catalog Source Code

  1. In Eclipse, go to Window -> Show View -> Other...
  2. Choose SVN -> SVN Repositories
  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. Back in Eclipse, for the URL (note that one URL uses https and the other uses http):
  7. Click "Finish". If asked about a digital certificate click "Accept Permanently".
  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:
    1. For the standard client: wbc -> trunk
    2. For the web client: wbc-view-web2 -> trunk
  10. Right click on trunk and choose Checkout...
    1. Choose "Check out as a project configured using the New Project Wizard". "Check out HEAD revision" should be checked. Click "Finish".
    2. In the "New Project" window that pops up, select Java -> Java Project and click "Next".
    3. Pick a name for the project (e.g. "wbc")
    4. Make sure the path has no spaces (in the grayed out Location: box). If it does, you need to rename the project or switch workspaces (click "Cancel", open File -> Switch Workspace -> Other..., enter a new workspace path without a space, click "Ok" and restart Eclipse. Then you can redo the checkout).
    5. Click "Finish", check "Remember my decision", click "Yes" and then "Ok"
    6. Restart Eclipse

[edit] Building the Whole Brain Catalog Source Code

  1. Maven has to be setup and download the dependencies. Each of these 3 steps takes a while. A progress bar will be shown in the lower left or lower right, sometimes accompanied by text similar to "Updating Index", "Changing nature" or "Building workspace". Do each of these separately, and after each one restart Eclipse.
    1. Right-click on the project and choose Maven -> Enable Dependency Management
    2. Right-click on the project and choose Maven -> Enable Nested Modules
    3. Right-click on the project and choose Maven -> Update Project Configuration
  2. Optional: If you want to build using JDK 1.5 for WBC instead of 1.7 you can do the following. I have been doing fine with Java 1.7 though.
    1. Install the JDK 1.5 (32-bit, 64-bit, or both, it's your choice)
    2. Right-click on the project and choose Build path -> Configure Build Path...
    3. Choose the "Libraries" tab.
    4. Select the "JRE System Library [JavaSE-1.7]" option and click "Edit..."
    5. Choose "Alternate JRE" and select jdk1.5.0_##. If there is no jdk 1.5 option:
      1. Click "Installed JREs..."
      2. Click "Search..."
      3. Select the Java folder (usually either "C:\Program Files\Java" or "C:\Program Files (x86)\Java on Windows") and click "Ok".
      4. All of the installed JREs and JDKs from that folder should now be listed (you will have to repeat if you installed 32 and 64 bit). Click "Ok". Now you can select jdk1.5.0_##
    6. Click "Ok"
  3. Choose Run -> Run Configurations...
  4. Double click "Maven Build"
  5. Name it "clean install" and enter "clean install" for Goals as well.
  6. Click "Browse Workspace..." and select the root of your project and click "Ok".
  7. Click "Run"
    • 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.
    • If this fails (which it does more often than not...), try to following:
      • Right-click on the project and choose Maven -> Update Project Configuration, Update Snapshots, Update Dependencies then restart Eclipse and try again
      • Right-click on the project and choose Maven -> Disable Dependency Management, restart Eclipse, then re-Enable it, restart Eclipse and try again
      • Disable dependency management (like above), close Eclipse, delete the "repository" folder within the ".m2" folder in your user directory (it is where you saved the settings.xml file), open Eclipse, and repeat all the building steps from the beginning.
  8. Restart Eclipse. From now on Maven will AUTOBUILD and you do not need to run clean install.

[edit] Running the Server

Running the server has not yet been tested with Indigo, however you may try to follow the guides for the generic Eclipse installation at Setting up development environment

[edit] Running the Client

[edit] Maven Natives Issue

In the previous versions of Eclipse (that supported Maven Integration v0.9.8 or earlier) you could install a plugin called Maven Natives which would correct the path to automatically include native libraries required by WBC. However it doesn't work at all with the versions that we can use.

Good news is that there is a workaround for the lack of Maven Natives support. Whenever you create a new Run / Debug Configuration:

  1. Go to the "Arguments" tab of the configuration
  2. Set the working directory to /wbc/target/natives

[edit] Running

During the first run Maven will have to download more things. Be patient.

Running the standard client:

  1. Create a new run/debug configuration for the class
  2. On the configuration page, go to the "Arguments" tab and set the VM arguments to -Xmx768m or -Xmx1024m to increase the available memory

Running the web client:

  1. Create a new Maven run/debug configuration with the name "run", goal "jetty:run", and workspace as the workspace root.
  2. Open a browser and go to "http://localhost:8080/wbc".
  3. Whenever the code changes you must run "clean install" first.

[edit] Tips

There are a few tips on the Setting up development environment page.

Personal tools