Developing OpenCms with Eclipse

Latest revision as of 10:41, 21 February 2012

Developing OpenCms with Eclipse

This entry is made for OpenCms users who want to enhance OpenCms for their own requirements. The target is to enhance the OpenCms core and/or build new OpenCms modules. For that you have to setup the complete OpenCms development environment and you have to know how to build new OpenCms installation. Eclipse is the OpenCms development environment. In the first subchapter is described how to checkout the OpenCms core, and how to build an OpenCms installation in Eclipse. The second subchapter will describe how to create and build own OpenCms modules.

OpenCms Core

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

The complete OpenCms source code is accessible at the web-based hosting service Github. Github is based on the popular distributed revision control system (DRCS) Git. In case you do not know what Github is, check out the Github website for further information.

You will always find the latest source code version of OpenCms in our Github repository. You can check out this source code and compile OpenCms for yourself as described on the Core Build page.

Please note that Github may contain new code that has not fully been tested yet and thus might cause problems. In case you want to use OpenCms in a production environment, we recommend that you use the latest binary release, available in the Download area.

Git/EGit client configuration

The easiest way to access the OpenCms source code is to clone the OpenCms repository at Github to your local hard drive.

EGit

If you use Eclipse as IDE, there is a plugin called EGit available from http://download.eclipse.org/egit/updates. Use the Eclipse Update manager to install this plugin.

After installation open the Git Repository Explorer Perspective and click the button "Clone a Git Repository...".

Parameters:

Host: github.com

Repository Path: /alkacon/opencms-core

Protocol: git

EGit requires Eclipse Version 3.5 or later.

Git

Alternatively you can install Git following the instructions at help.github.com >Beginner>"Set up Git".

Use this command to clone the OpenCms Repository to your local system

git clone git://github.com/alkacon/opencms-core

A Git reference is available at gitref.org.

Please note: If you intend to build OpenCms from the sources, you will need the required libraries (*.jar files). These are included in the OpenCms source distribution. Please consult the Core build page for full instructions how to build OpenCms from source.

Github web interface

You can also browse the OpenCms repository at Github and download individual source code files from github.com/alkacon/opencms-core.

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

Then select the "Properties" tab and add the following "Global properties" by clicking the "Add property..." button:

• tomcat.home: Indicates the servlet container location
• app.name: indicates the context name of the OpenCms instance to update (see next section)
• opencms.output: indicates where to store compilation files

After that select build.xml in the Eclipse Explorer View with mouse, press right mouse key and choose "Run As" and "External Tool Configuration". In the tab "Target" you can select the following often needed options:

• OpenCms > bindist: Use this target to get a distribution zip file with all modules. The zip file is stored at ${opencms.output}/zip/opencms_${opencms.version}.zip
• OpenCms > clean: Use this target to purge the output folder, do not use the "OpenCms Common Modules > clean" target that only cleans the output files of the selected modules.
• OpenCms > tomcat.update: Updates a previous installed OpenCms instance. It copies a new compiled opencms.jar in the ${tomcat.home}/${app.name}/WEBINF/ lib (or ${jboss.home}/${app.name}.war/WEB-INF/lib) folder.
• OpenCms Common Modules > war: This target generates a new war file with the selected modules. You can find the generated file under ${opencms.output}/build/opencms.war

Compiling OpenCms with Ant

To execute a build target select the Ant build menu and select the build.xml to build. Make sure, that console in Eclipse is opened. You can open that with "Window" > "Show View" > "Console".

OpenCms Modules

We do not advise to make changes in OpenCms Core. One reason is that your private OpenCms Core enhancements are overwritten with an OpenCms Core Update. But we want to say again that good OpenCms Core enhancements are always welcome, but not every external developed OpenCms Core enhancement can become a part from public OpenCms Core. That’s why we advise to create own modules for your OpenCms needs. In the first subchapter is described how to create own OpenCms modules. In the second subchapter is described how to compile these modules to use them in the OpenCms Installation.

Create OpenCms Modules

Analogue to other OpenCms Modules is to create a new package in OpenCms/src-modules/ folder. Here new Java classes have to come in. To create such new package in Eclipse you have to select the OpenCms/src-modules/ directory and in the menu "File" > "New" > "Package". Other new module resources like JSP pages are directly created in OpenCms. After OpenCms Module export, these resources have to become imported into Eclipse into the OpenCms/modules/<new package>/resources/ directory. To import these resources into Eclipse create with any file explorer in Eclipse workspace directory OpenCms/modules/<new package>/resources/ directory and copy system directory and manifest.xml from exported OpenCms Module into here.

Building OpenCms Modules with Ant

To build OpenCms Modules you have to use Ant. Using Ant allows changing Java classes and building jar files automatically, without manually copying these jar files into running OpenCms installation. Administration resources like JSP pages are controlled with module manifest.xml file. Manifest file only changes when OpenCms resources for module are new created. Only with Ant the jar file belongs to module and if a jar file is new built in Eclipse, it automatically is updated in module and therefore directly in OpenCms. In the first subchapter is described how to configure Ant. How to use Ant to build OpenCms Modules is described in the second subchapter.

Configure Ant to compile OpenCms Modules

To be able to compile the project, you will need to configure Ant additional to the configuration for OpenCms Core. 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 select the "Properties" tab and add following "Global properties" by clicking the "Add property..." button:

• modules.selection.mode: This optional property controls how to select the modules to build/update, the following values are possible:

 + interactive: interactive GUI based module selection, this is the default.
 + selection: module selection based on modules.common.selection property
 + all: module selection based on modules.common.all property defined in the file: all-modules.properties

• modules.common.selection: set this property to a comma separated list of module names if you set the modules.selection.mode to selection. After that select src-modules/build.xml in the Eclipse Explorer View with mouse, press right mouse key and choose "Run As" and "External Tool Configuration". In the tab "Target" you can select the following often needed options:

• OpenCms > bindist: Use this target to get a distribution zip file with all modules. The zip file is stored at ${opencms.output}/zip/opencms_${opencms.version}.zip
• OpenCms > clean: Use this target to purge the output folder, do not use the "OpenCms Common Modules > clean" target which only cleans the output files of the selected modules.
• OpenCms > tomcat.update: Updates a previous installed OpenCms instance. It copies a new compiled opencms.jar in the ${tomcat.home}/${app.name}/WEBINF/ lib (or ${jboss.home}/${app.name}.war/WEB-INF/lib) folder.

Additionally you have to enhance OpenCms/modules/all-modules.properties. Here are listed all OpenCms modules. You have to write a comma and a backslash after the last module name entry. Then you have to write your module name in a new line.

Compiling OpenCms Modules with Ant

To execute a build target select the Ant build menu and select the build.xml to build. Make sure, that console in Eclipse is opened. You can open that with "Window" > "Show View" > "Console".

During building modules in Eclipse appears a window where you can select modules to build new. If you press button “None” and you select your module, only your new module will become created.