BuildingInEclipse
Building XWiki in Eclipse
This document contains instructions on how to configure Eclipse for building and developing XWiki. It should be noted that these are generic instructions, some components / sub-projects of XWiki might require specific configurations on Eclipse that may not be covered in this document.
Table of contents
Installing Eclipse
- Download the latest version of Eclipse from the Eclipse Download Site and launch it using a 1.5 JDK.
- Optionally you might want to install the Web Tools Project (WTP) feature if you want to deploy XWiki to a support server without having to leave the Eclipse IDE, See The WTP homepage for details and Installing and Using the Eclipse Web Tools for help.
Obtaining XWiki source
The source for XWiki is available via a subversion repository. You should get familiar with the Repository Structure before continuing any further. Once you have done that, you may use either of the following methods to obtain XWiki source.
Using Subclipse
Subclipse is a plug-in for Eclipse which lets you checkout svn repositories right within the IDE itself. Once installed you may checkout [https://svn.xwiki.org/svnroot/xwiki/platform/trunks], which will checkout the trunks of all XWiki artifacts, i.e. xwiki-platform, xwiki-products, xwiki-extensions, etc. Alternatively, you may checkout a specific artifact. i.e. [https://svn.xwiki.org/svnroot/xwiki/xwiki-platform/core/trunk]
Manually from a console
- Install a subversion client (most linux distributions automatically install one of these).
- Use svn from the command line, eg. [svn co https://svn.xwiki.org/svnroot/xwiki/platform/trunks] to get the latest source.
Building With M2Eclipse (Easy)
This is the most easiest way to build XWiki from sources while remaining inside the IDE.
- We'll start by installing M2Eclipse which is a plug-in for Eclipse. If you are not familiar with installing Eclipse plug-ins via update sites, you may refer to this HOWTO and get it done.
- Make it certain that your M2Eclipse installation is configured properly, select [Window->Preferences] and on the left column of the Preferences window, select Maven. Now on the right column, check whether your local maven repository and settings.xml file have been identified by M2Eclipse. If not, fill them in.
- Now we're going to import the XWiki source (checked out above) into your Eclipse workspace. Select [File->Import] and there under the General category, select Maven Projects and click Next.
- On the next screen, point Root Directory to whatever XWiki module you wish to work on. If you point the Root Directory to top-level trunks folder, you will end up with a gazillion of Eclipse projects. Therefor only select the module you wish to work on, and keep in mind that maven will take care of dependencies.
- Finally, click Finish to dismiss the import wizard and let the workspace adjust itself (This will take some time depending on the number of projects to be imported).
- Now you can execute maven goals simply by right-clicking on the project and then [Run As->]. Observe the output from maven now appearing on the Console viewer of Eclipse.
- That's it! Happy Hacking ... ;)
Building Manually (Hard)
This approach has been left obsolete with the arrival of M2Eclipse.
Generate Project Files.
- Make sure you have installed Maven correctly. Refer to Installing Maven for further details.
- Open up a console, navigate into the directory where sources for the module you wish to work on resides. Ex. [trunks/xwiki-platform-core]
- Then run "mvn eclipse:eclipse". This will create necessary Eclipse project files (can be more than one project).
Setup A Workspace.
- Create a new Eclipse workspace (optional)
- Within Eclipse, define a class path variable M2_REPO so that it points to your local maven repository. This can be accomplished from [Window->Preferences] and then under [Java->Build Path->Classpath Variables].
- Now import the eclipse projects created above into your workspace. For this, select [File->Import->Existing Projects into Workspace] and there from the Import dialog, point project root to the directory where you executed 'mvn eclipse:eclipse'. If everything goes ok, you should see the relevant project(s) getting listed on the Projects list-box. Now click Finish and allow the workspace to adjust itself.
Configure External Tools.
Now we'll configure Eclipse so that you can execute maven goals from within the Eclipse IDE itself. For this, we're going to use External Tools support of Eclipse, simply follow the instructions given bellow.
- First we need to let eclipse know where maven executable is located. For this we'll define a string variable pointing to your maven executable. Select [Window->Preferences] and there under [Run/Debug->String Substitution] introduce a new variable named maven_exec and set it's value to the location of your maven executable (Ex. /home/user/software/apache-maven-2.1-SNAPSHOT/bin/mvn).
- Select [Run->External Tools->Open External Tools Dialog]. From the left column of External Tools Dialog, select [Program->(Right Click)->New]. This will create an empty configuration.
- Name the configuration as maven_install, point Location to ${maven_exec} (use the Variables button nearby), point Working Directory to ${project_loc} and set the arguments to install.
- Now we have created an external runner which will execute the command 'mvn install' (lot of work, isn't it?).
- One more step remains, we need to allocate enough memory to maven while executing 'mvn install'. In the Environment tab of above configuration, add an environment variable named MAVEN_OPTS and set it's value to -Xmx512m. Now apply the configuration and close the External Tools Window.
- Select [Run->External Tools->Organize Favorites] and add the configuration just created into your favorites (for easy access).
- Finally select one of your XWiki projects and then execute the external runner created above. You can accomplish this by pointing to [Run->External Tools->maven_install] or you can access external tools directly from the Eclipse toolbar. If everything goes ok, you will see the output from maven now appearing on the Eclipse Console viewer.
- Now you may create as many external runners as you would like to (Ex maven_install, maven_deploy etc.).
[Optional] Import the WAR as a web project
If you want to use the Web Tools Project capabilities to deploy to a defined server, set breakpoints to debug code etc. then you can import the WAR file as a web project in eclipse. This is useful if you want to deploy directly into a web server such as WAS Community Edition Server with leaving the Eclipse IDE. It can also be a lot easier to debug.
- Install the Eclipse Web Tools Platform (WTP).
- From the Eclipse menu select File > Import...
- Choose Web > WAR file and press Next
- Fill in the WAR file field with the xwiki.war you just built
- Change the Web project to 'xwiki' (this is default used for the context root)
- Choose a target runtime; if this select is empty you will need to create a new one with your favorite web server. Instructions on the Eclipse website can guide you through this.
- Hit Finish to import the WAR file as a separate project
- To deploy and run xwiki, right click the new project and choose Run As > Run on Server.
[Optional] Use the Jetty Launcher plugin
Run the ant target 'standalone'. This will create a directory 'xwikionjetty' under 'release'. From the command line you can run start_xwiki.sh or start_xwiki.bat (after you make it executable), or you can use the Jetty Launcher plugin to make it run from within Eclipse.
Alternatively, you can add an ant task to execute the the start_xwiki.{sh,bat} script.
Building XEclipse
Building XEclipse from source is a straight forward task:
- First you need to check out the source with following command,
- Within the Eclipse IDE, select [File->Import->Existing Projects into Workspace].
- In the import projects dialog, point [root] directory to [xeclipse/plugins/org.xwiki.eclipse].
- If everything goes ok, you will see [org.xwiki.eclipse] get listed in the [Projects] list-box, click Finish.
- After the project finishes loading, you may right click on it (Package Explorer) and select [Run As->Eclipse Application].
- This will launch a new instance of Eclipse IDE with XEclipse loaded as a plugin.
- In this new instance of Eclipse, select [File->New->Other]. You should see XWiki get listed in the wizards list.
- That's it, happy hacking! :)