Download/Installation

Requirements

XDoclet will run on any platform where there is a suitable Java 2 runtime environment. You have to make sure tools.jar from JDK's lib directory is on your classpath, and that you are using Jakarta Ant 1.5 or higher (XDoclet does not support previous versions).

XDoclet has been used successfully on many platforms, including Linux, UNIX, Windows 9x, NT, 2000 and XP, MacOSX.

Starting from XDoclet 2, JDK 1.4 is required to run (and build) XDoclet. However, the generated sources are still compilable on JDK 1.3 environments.

Downloading XDoclet

The latest stable version of XDoclet is available from the SourceForge download page.

The available distribution archives are:

  • xdoclet-lib-1.2, includes all needed libraries
  • xdoclet-bin-1.2, includes the documentation, all needed libraries and samples
  • xdoclet-src-1.2, includes scripts and sources needed to build XDoclet (see below)

Installing XDoclet

Depending on the XDoclet distribution archive you downloaded, it consists of the following directory layout:

  • docs - user documentation, point your browser to index.html in this directory
  • lib - libraries needed to run XDoclet (jar files)
  • samples - simple examples demonstrating XDoclet (execute ant in this directory)

Xdoclet JARs for Maven

The Xdoclet web site has a repository set up, at http://xdoclet.sourceforge.net/repository. The individual jars and the maven plugin can be found at this location. Maven users can add the above location to their the maven.repo.remote property.

Getting XDoclet from CVS

If you need access to the latest source code, and like living on the bleeding edge (don't complain we didn't warn you), you need understanding of CVS and a CVS client.

Follow the instructions explained here to configure your client.

Getting XDoclet from CVS from Behind a Firewall

If you are behind a firewall, or you do not want to install a CVS client, a daily CVS dump is available at http://xdoclet.sourceforge.net/xdoclet-cvs.zip.

If you need to checkout or update from behind a firewall, you can use CVSGrab (reads the repository via the XDoclet ViewCVS web interface).

Building XDoclet from Sources

Follow these steps carefully:

  • install Jakarta Ant 1.5 or higher
  • go to the xdoclet directory (CVS checkout or expanded source download)
  • execute ant (optionally append the target)
A target is a set of tasks you want to be executed. When starting Ant, you can select which target(s) you want to have executed. When no target is given, the project's default (dist) is used. The available build targets are:
  • core - build the core
  • modules - build the core and the modules
  • docs - build the core, modules and generate the documentation
  • samples - build the core, modules and samples
  • dist - build everything and package it into archives (this is the default target)
  • clean - revert back to the source distribution
  • patch - makes one patch file containing all local changes

To change the compiler, modify the build.properties file, and change the build.compiler property to your preferred value. To build using Jikes, change the default modern value to jikes and make sure Jikes is on your path.

Please note that the MISSING RESOURCE errors displayed when building the xdoclet module are NOT bugs.

Generating the XDoclet Documentation

XDoclet uses Maven and XDoclet (yes, we do eat our own dog food!) to generate the documentation.

The documentation consists out of the following parts:

  • xdocs (Maven handles these)
    • User Documentation
    • Ant Task Reference (build-docs.xml, ant-docs target, using AntdocSubTask)
    • Tag Reference (modules-common.ent, docs target, using xslt (xdocs/stylesheets/xtags2xdoc.xslt) to convert xtags.xml into xdocs)
  • JavaDoc (build-docs.xml, api target)
  • Template Language Reference (build-docs.xml, document target, using DocumentDocletTask)
  • Todo List (build-docs.xml, todo target, using DocumentDocletTask)
Most of the documentation (xdocs) is in Anakia format. More information along with samples, can be found at: To generate the documentation, follow these steps carefully:
  1. install Jakarta Ant 1.5 or higher
  2. install Maven 1.0 RC2 or higher
  3. get XDoclet from CVS
  4. go to the xdoclet directory
  5. to build the documentation, execute
    • ant (this builds XDoclet and the documentation)
    • OR ant -f build-docs.xml (this will only build the documentation, but you need to build XDoclet first)