Running DITA builds in Eclipse

You must be using the full package distribution of DITA Toolkit 1.3.1 (or later) to use this procedure.

This topic describes how to incorporate an existing set of DITA Open Toolkit source and Ant build files into an Eclipse project so that the DITA source files can be edited and the DITA Toolkit Ant builds can be run within Eclipse. Eclipse provides various XML editors and also supports execution of Ant build scripts.

  1. Create a new Eclipse general project. Begin by selecting File > New > Project > General project . Then select Next and give the project a name. In our example we call it DITAEclipse2.
  2. Import the DITA source and build files into your Eclipse project. To add the existing DITA source and build files to the new project, right-click on the project in the Package Explorer and select Import > File System > Next , and use the Import Dialog to locate and select the files and directories to be added to the project.
  3. Make any needed modifications to the Ant build script. After you have imported the Ant build script used to process your DITA files, check to make sure that the basedir and other properties in the build script are correct for the location of the files in your Eclipse project.
  4. Create a project folder to reference the Toolkit lib directory. In order to run your Ant build script under Eclipse, you need to add the appropriate Toolkit .jar files to the classpath used by Eclipse when it runs the Ant script. Right-click on the project and select New > Folder > Advanced and check the "link to folder in the file system" box. Then select Browse and select the lib directory in the Toolkit. This directory contains all the necessary .jar files required for the Toolkit processing. Now right-click your project Ant build script and select Run As > 2 Ant Build... . This will open the Modify attributes and launch dialog. Select the Classpath tab and use the dialog to add the jar files in the project lib folder and the lib folder itself to the CLASSPATH for the script. The result should look something like this:

    classpath dialog

  5. Now select Apply > Run to run your DITA build. The build output (and any error messages) will appear in the console window at the bottom of the Eclipse window.