##### Search XDoclet

## 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.

- Microsoft Windows machines: a good CVS client is TortoiseCVS (screenshot). When prompted for a password (anonymous user), simply press the Enter key.
- UNIX/Linux machines: you can get CVS from https://www.cvshome.org/downloads.html.

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:

- The jakarta-site tags
- The jakarta-site tags examples

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)