Current development on JAMWiki is primarily focused on maintenance rather than new features due to a lack of developer availability. If you are interested in working on JAMWiki please join the jamwiki-devel mailing list.

Building from Source

ktip.png Please contribute to the JAMWiki project by helping to improve this article. Add to or expand some of the existing information, fix an error, or share your own knowledge to improve this subject! Don't worry about making mistakes - there will always be someone who can correct any errors later.

These instructions describe how to build a JAMWiki WAR file directly from the Subversion source repository. Building JAMWiki requires Maven 3.x to build. The Subversion repository is accessible at http://jamwiki.svn.sourceforge.net/svnroot/jamwiki/ and can also be browsed online.

Contents

Building from source (command line)[edit]

Prerequisites[edit]

Before attempting the build from Source be sure that the following are all available:

Getting the Source[edit]

The JAMWiki source is available from the Subversion source repository on Sourceforge.net. To check out the code, first install Subversion and either checkout the trunk branch using a graphical Subversion client (such as TortoiseSVN) or directly from the command line using the command:

svn co https://jamwiki.svn.sourceforge.net/svnroot/jamwiki/wiki/trunk jamwiki

This command will copy the current development code (the "trunk") into a local directory named jamwiki.

Building from Source[edit]

ktip.png The Subversion repository code should always build without errors. If you encounter build errors please verify that you have followed the instructions below and have a working Maven setup; if there is an error in the instructions below please help by correcting it. If the problems persist and you are unable to find a solution please file a bug report with the error reported during the build process and your environment information (OS, JDK version, any other relevant information).

Building requires Maven. From either trunk or the appropriate branch (the jamwiki/wiki/trunk or jamwiki/wiki/branches/branch-name directory) run the following command:

mvn package

If the above command fails due to unit test failures you can build without running unit tests using:

mvn package -DskipTests=true

Maven will download all dependencies, compile all files, and build a WAR file named jamwiki-war/target/jamwiki-x.x.x.war. Consult your web application server's documentation for instructions on how to install this file.

If any Java heap size errors are encountered while running this command the heap size can be increased by setting the MAVEN_OPTS environment variable. For example:

MAVEN_OPTS=-Xmx256m

Additional options[edit]

To build all project reports the full project must first be built, then the sub-project libraries must be installed into the local repository. From the top of the source directory (the jamwiki/wiki/trunk or jamwiki/wiki/branches/branch-name directory) run the following commands:

mvn package
mvn install

Full site reports can now be run from the top of the source directory (the jamwiki/wiki/trunk or jamwiki/wiki/branches/branch-name directory) using the command:

mvn site

To remove all Maven artifacts, leaving only source files, run the command:

mvn clean

To skip JUnit tests when running any Maven command add the property -Dmaven.test.skip. For example:

mvn -Dmaven.test.skip package

To enable Maven debugging you can use Maven and its Jetty plugin. More information about that on Debugging with the Maven Jetty Plugin inside Eclipse

For further Information about Maven see Tech:Maven.

General information[edit]

Source Repository Layout[edit]

The Subversion layout is set up as follows:

  • trunk is where development for the next major release occurs. Most new branches should be created off of trunk.
  • branches are used for individual developer code and for maintenance of stable releases. Bug fixes for the stable release occurs on branches/1.1.x (or whatever the release name is). The stable branch is regularly merged back to trunk. New developers should create their own development branch. The branch name isn't important, but most people use either their Sourceforge ID or their JAMWiki login (example: branches/wrh2).
  • tags are used for releases to record the code that was used for a release version. Tags should never be modified.

As of JAMWiki 1.1 trunk, branches, and tags within the source code repository are organized as follows:


-pom.xml // main Maven project description file
-jamwiki-core // core packages including the parser
  |-src
  |  |-main
  |  |   |-java //java source code
  |  |   |-jflex // jflex lexer files used for generating parser code
  |  |-site
  |  |-test 
  |  |   |-java // test cases
  |  |   |-resources // test properties files and data files
-jamwiki-web // servlets and other non-core packages
  |-src
  |  |-main
  |  |   |-java //java source code
  |  |-site
  |  |-test 
  |  |   |-java //test cases
-jamwiki-war // JSP files and other code needed for the final WAR package
  |-src
  |  |-main
  |  |   |-resources // properties files and values needed in WEB-INF/classes
  |  |   |-webapp // root of war file
  |  |        |-WEB-INF
  |  |             |-jsp
-addons // extensions to the standard JAMWiki installation
  |-bliki-parser // an alternative JAMWiki parser interface
  |  |-src
  |  |   |-main
  |  |   |-site
  |-jamwiki-jflex-parser-tags // extension tags for the default JAMWiki JFlex parser
  |  |-src
  |  |   |-main
  |  |   |-site
  |  |   |-test

Working in your favorite IDE[edit]

ktip.png Please help keep these build instructions up-to-date by updating the steps below with any additional details or corrections.

Getting started with Eclipse (first approach)[edit]

I've copied my setup for Eclipse to this page: Building from source/Eclipse. Maybe someone else find it useful. --Axel Kramer 08-Jul-2008 10:21 PDT

Prerequisite[edit]

Setup[edit]

Install Subclipse and the Maven Eclipse plugins. See the URLs above for full instructions.

  1. In Eclipse go to Help → Software Updates → Find and Install.
  2. Choose "Search for new features to install"
  3. The required plugin URLs are:


Once installed, select the "SVN Repository" Eclipse perspective and add https://jamwiki.svn.sourceforge.net/svnroot/jamwiki/ as a repository. You should now be able to right click on this repository and select the "Check out as a Maven project" option.

Usage[edit]

In the package explorer view do a right mouse click on the pom.xml file and select the menu Run As -> Maven build....
In the appearing dialog box select the Select... button in the Main tab and choose the package goal:

m2eclipselaumch001.png

I needed to run this twice and increase the default java heap for eclipse to -Xmx1024m, because in the first run I get an OutOfMemoryError exception:

[INFO] Compiling 2 source files to C:\IDE\workspace\jamwiki_svn\javadiff\target\classes
org.apache.maven.plugin.CompilationFailureException: Compilation failure
Failure executing javac, but could not parse the error:

The system is out of resources.
Consult the following stack trace for details.
java.lang.OutOfMemoryError: Java heap space
	at java.util.zip.ZipEntry.initFields(Native Method)
	at java.util.zip.ZipEntry.<init>(ZipEntry.java:96)
	at java.util.zip.ZipFile$2.nextElement(ZipFile.java:329)
	at java.util.zip.ZipFile$2.nextElement(ZipFile.java:299)
	at com.sun.tools.javac.util.DefaultFileManager$ZipArchive.<init>(DefaultFileManager.java:405)
	at com.sun.tools.javac.util.DefaultFileManager$SymbolArchive.<init>(DefaultFileManager.java:460)
	at com.sun.tools.javac.util.DefaultFileManager.openArchive(DefaultFileManager.java:544)
...

...

Alternatively[edit]

 mvn eclipse:eclipse

Then start Eclipse, go to File > Import > General > Exiting projects into workspace, select folder in which you checked out the source.

Getting started with anything Netbeans[edit]

Since Netbeans 6.7, Maven support is bundled with the default installation of Netbeans. You can just open the project in Netbeans.