Developing OpenCms with Eclipse

Revision as of 09:06, 22 October 2010

Development Configuration

The OpenCms core provides the main OpenCms functionality. You can install the OpenCms core source code in your Eclipse in order to analyze it and learn how OpenCms works internally. It should not be necessary to modify anything in the OpenCms core for your project. We strongly recommend staying with the unmodified public core distribution. Creating a modified OpenCms core version will only lead to a dead end for your project since you will not be able to install important updates without incorporating your changes to the standard core. In the first subchapter is described how to checkout OpenCms Core project. How to configure OpenCms Core project in Eclipse is described in the second subchapter. In the third subchapter it is described how to check OpenCms Core code. How to build OpenCms Core project with Ant is described in the fourth subchapter.

Check Out the Project

OpenCms Core is accessible for free. The code is in a CVS repository. Following it is described how to checkout this code to your local computer.

Please Note: You can checkout all stable OpenCms Core Versions which were ever published. That means you can checkout the last stable version and also special numbered public OpenCms Core Versions, for example 7_0_5. In order for Eclipse to know which Branches or CVS Tags exists, you need to configure a file that has these information available. We usually use the Ant build file build.xml from the OpenCms core project to get this information. To check out the project from the CVS repository, you should create a new project, using the "New Project" wizard of Eclipse. For this go to the "File > New > Project..." menu option of Eclipse, and select the "CVS > Projects from CVS" option.

After clicking the ‘next’ button, a dialog for entering the repository information is displayed, enter the following information:

• Host: cvs.opencms.org
• Repository Path: /usr/local/cvs
• User: anon
• Password: anon
• Connection Type: pserver
• Use Default Port: true (leave it checked, as default)
• Save Password: check it if you do not want to enter the CVS password anytime Eclipse needs to connect to the server.

Click the "Next" button, to select the module name. Set it to opencms

Then, click the "Next" button, and select to "Checkout as a project configured using the New Project Wizard".

Click the "Next" button, to select the version to check out. Click the "Refresh Tags" button to get a list of possibilities, the most used is HEAD which is the last stable version. In choice "Branches" you can get another last version, for example dev_7_0_5 is OpenCms Version 7.0.5. When no branch versions are listed you have to select file build.xml in mask opened with button "Configure Tags".

Click the "Finish" button and the "New Project" wizard appears again. Now select "Java Project". Click the "Next" button and the "Create new Java Project" dialog is shown. Here enter the following information:

• Project Name: OpenCms
• Contents: Create a new project in the workplace
• Project Layout: Create a separate source and output folders. Click on "Configure Default...", and configure the "Source and output folder" checking folders, leaving the defaults: src for the Source folder and bin for the output Folder.

Link "Configure default" in section "Project layout" should have the following settings.

Click the "Finish" button. Now the source code should be downloaded from the CVS repository. This can take some minutes, depending on your Internet connection.

Configuring the OpenCms Project

After importing code from OpenCms Core you have to configure project to be able to compile it in Eclipse and to build OpenCms Core with your personal enhancements. You have to configure project classpath and project source folder. How to configure project classpath is described in the first subchapter. In the second subchapter the project source folder is described.

Configuring the Project’s Classpath

After the checkout, Eclipse will try to immediately compile the project, and you will have several errors, this is because you have to add the needed external libraries to the classpath. For this, go to the "Project > Properties" menu option of Eclipse, opening the "Project Properties" dialog. Select the "Java Build Path" option on the left, and the "Libraries" tab on the right, there click the "Add Jars..." button and add all jars in folders:

• OpenCms/lib/compile/
• OpenCms/lib/runtime/
• OpenCms/modules/org.opencms.frontend.templateone.form/resources/system/modules/org.opencms.frontend.templateone.form/lib/
• OpenCms/webapp/setup/database/oracle/
• OpenCms/modules/org.opencms.frontend.layoutpage/resources/system/modules/org.opencms.frontend.layoutpage/lib/freemarker-2.3.6.jar
• OpenCms/webapp/setup/database/ and sub folder with jar-archive to belonging DB-driver

Now click the "Ok" button, and Eclipse should automatically build the project again. So, every compile error should disappear.

Configuring the Project’s Source Folders

In addition to the default src folder OpenCms has 4 source folders:

• OpenCms/src: Here you find the OpenCms core classes (all classes found in opencms.jar)
• OpenCms/src-components: Here you find the source code for some libraries used by OpenCms, like the Upload Applet, or the Ant extensions.
• OpenCms/src-modules: Here is the source code of all modules located.
• OpenCms/src-setup: Setup source code.
• OpenCms/test: Here are the JUnit test cases located.

To set up these source folders, open the properties dialog for the project, select the "Java Build Path" on the left side, and then the "Source" tab on the right side.

Do not forget to set two exclusion filters to the OpenCms/test source folder:

• data/**
• org/opencms/util/ant/

Therefore you have to select in source OpenCms/test "Excluded" and press the "Edit" button. Then you have to put in the two exclusion filters separately.

Building OpenCms with Ant

To build OpenCms Core you should use Ant. Using Ant allows changing Java classes and automatically building jar files, without manual copying these jar files into running OpenCms installation. That means, if you change Java classes and build OpenCms in Eclipse you have nothing to do else, because Eclipse builds a jar file and this file is automatically updated for the OpenCms installation, too. If you do not use Ant you have more complexity to do, to bring your enhancements into your running OpenCms installation. In the first subchapter is described how to configure Ant. In the second subchapter is described how to use Ant to build OpenCms Core project.

Configuring Ant

To be able to compile the project, you will need to configure Ant. For this, go to the "Window > Preferences..." menu option of Eclipse, select the ‘Ant > Runtime’ node on the left and the "Classpath" tab on the right, and add the following jar files to the "Global Entries":

• OpenCms/lib/compile/ant-contrib-1.0b1.jar
• OpenCms/lib/compile/ant-opencms-1.1.jar
• OpenCms/lib/runtime/commons-beanutils-1.8.0.jar
• OpenCms/lib/runtime/commons-collections-3.2.jar
• OpenCms/lib/runtime/commons-digester-1.8.jar
• OpenCms/lib/runtime/commons-logging-1.1.1.jar