DITA-OT Dependency Checker Plugin

A plugin for DITA Open Toolkit that provides enhanced dependency management for DITA-OT plugins.

Features

• Check for dependencies defined in various sources with a clear precedence.
• Support for <?depends-on ...?> processing instructions within a plugin's plugin.xml for self-contained dependency declarations.
• Support for a global dependency-config.xml file for site-wide or overriding dependency rules.
• Differentiate between required and preferred dependencies.
• Version checking for dependencies with flexible version requirements (>=, >, <=, <, =).
• Check for:
  • Other plugins
  • Installed executable software
  • Java versions
  • Java JAR files
• Generate HTML and XML dependency reports.
• Warning logs for missing dependencies.

Installation

1. Build the plugin using Maven: mvn clean package. This creates the plugin ZIP in the target/ directory (e.g., dep-checker-1.0.0-plugin.zip).
2. Install the plugin into your DITA-OT instance using the DITA-OT integrator tool:

   dita --install /path/to/your/target/dep-checker-1.0.0-plugin.zip

   Alternatively, you can copy the plugin contents to the plugins directory of your DITA-OT installation and run the integrator.

Configuration

Dependencies are determined based on the following sources, in order of precedence (highest to lowest):

1. Global Configuration for a Specific Plugin: Rules in the main dependency-config.xml (located at the project root dependency-config.xml during development, or in com.android606.dep-checker/config/ after installation) that target a specific plugin (e.g., <plugin id="some.other.plugin">...</plugin>).
2. Plugin's Own Declarations in plugin.xml:
   • Standard <require> elements.
   • <?depends-on ...?> processing instructions. These are effectively evaluated together for the plugin being checked if no overriding global configuration for that specific plugin is found.

Additionally, Universal Global Dependencies (defined with <plugin id="*">...</plugin>) from the main dependency-config.xml are applied to EVERY plugin being checked, in addition to its specific dependencies.

Plugin Definition (plugin.xml)

Your plugin.xml is the primary place for self-contained dependency declarations.

Standard <require> Elements:

DITA-OT's standard mechanism for plugin dependencies.

<plugin id="your.plugin.id" version="1.0.0">
  <require plugin="org.dita.base" importance="required" version=">=3.0.0"/>
  <require plugin="org.dita.pdf2" importance="optional" version="<4.0.0"/>
  <!-- ... -->
</plugin>

<?depends-on ...?> Processing Instructions:

For more detailed or varied dependency types (software, JARs, specific Java versions, or more nuanced plugin checks), use processing instructions directly under the root <plugin> element.

<?xml version="1.0" encoding="UTF-8"?>
<plugin id="your.plugin.id" version="1.0.0">
  <require plugin="org.dita.base"/>
  
  <?depends-on id="com.example.another-plugin" type="PLUGIN" version="^1.2.0" required="true" message="Needs this for cool feature X." ?>
  <?depends-on id="ghostscript" type="SOFTWARE" version=">=9.50" required="false" message="Ghostscript is preferred for enhanced PDF processing." ?>
  <?depends-on id="my-custom-library" type="JAR" required="true" message="Core library for this plugin." ?>
  <?depends-on id="java" type="JAVA_VERSION" version=">=11" message="Requires Java 11 or newer." ?>
  
  <!-- Other plugin elements like features, templates, etc. -->
</plugin>

Attributes for <?depends-on ...?>:

• id: The identifier of the dependency (plugin ID, software name, JAR name, or "java"). (Required)
• type: The type of dependency: PLUGIN, JAR, SOFTWARE, JAVA_VERSION. (Defaults to PLUGIN if omitted)
• version: The version requirement string (see "Version Requirements" below). (Optional)
• required: true or false. (Defaults to true if omitted)
• message: A descriptive message explaining the dependency or the consequence of it being missing. (Optional; a default message is generated if omitted)

Global Dependency Configuration (dependency-config.xml)

This file is located at the project root (dependency-config.xml) during development. When the plugin is packaged, it is placed into the config/ subdirectory (e.g., DITA-OT/plugins/com.android606.dep-checker/config/dependency-config.xml). It's used for site-wide rules or to override/supplement definitions from individual plugin.xml files.

Example Structure:

<dependency-config>
  <!-- Rules for a specific plugin (e.g., org.dita.pdf2), will override its plugin.xml declarations -->
  <plugin id="org.dita.pdf2">
    <depend id="org.apache.fop" type="JAR" version=">=2.3" required="true" 
            message="Apache FOP 2.3 or higher is strictly required for PDF generation by site policy." />
  </plugin>
  
  <!-- Universal global rules, applied to ALL plugins -->
  <plugin id="*">
    <depend id="java" type="JAVA_VERSION" version=">=1.8" required="true" 
            message="Site policy: Java 8 or higher is required for all DITA-OT processing." />
  </plugin>
</dependency-config>

The <depend> elements within this file have the same attributes as the <?depends-on ...?> processing instructions.

Version Requirements

The plugin supports the following version requirement formats in the version attribute:

• 3.0.0 - Exact version match.
• =3.0.0 - Explicit exact version match.
• >=3.0.0 - Version 3.0.0 or higher.
• >3.0.0 - Version higher than 3.0.0.
• <=3.0.0 - Version 3.0.0 or lower.
• <3.0.0 - Version lower than 3.0.0.
• >=3.0.0,<4.0.0 - Version 3.0.0 or higher, AND lower than 4.0.0 (range). (Note: use < for < in XML attributes if using dependency-config.xml. Processing instructions can use < directly).

Usage

The dependency checker is integrated into DITA-OT's preprocessing pipeline. When DITA-OT builds documents, the checker will automatically analyze installed plugins based on the configured rules.

If dependencies are not met:

• Warnings will be logged to the console.
• The build may fail if a required dependency is missing and the checker is configured to failOnError="true" (default behavior of the Ant task may vary).
• An HTML and XML report will be generated.

Ant Task (check-dependencies)

The plugin provides an Ant task that can be called directly, though it's primarily designed to be invoked by DITA-OT.

Parameters for the Ant task:

• pluginDir: Path to the DITA-OT plugins directory. (Required)
• configFile: Path to the global dependency-config.xml file (e.g., plugins/com.android606.dep-checker/config/dependency-config.xml in an installed DITA-OT, or simply dependency-config.xml if running tests from the project root where the Ant task can find it). (Optional)
• reportDir: Directory where the HTML and XML reports will be generated. (Required)
• failOnError: Whether to fail the Ant build if required dependencies are missing. (true or false, defaults to false if not set, but DITA-OT's invocation might set this).
• logLevel: Logging verbosity (error, warn, info, verbose, debug. Defaults to info).

Example Ant task usage in a build script:

<taskdef name="check-dependencies"
         classname="com.android606.dita.dependencychecker.CheckDependenciesTask"
         classpath="path/to/dep-checker.jar"/>

<target name="run-dependency-check">
  <check-dependencies pluginDir="${dita.ot.dir}/plugins"
                      configFile="dependency-config.xml"
                      reportDir="${output.dir}/dependency-reports"
                      failOnError="true"
                      logLevel="verbose"/>
</target>

Report

An HTML report of dependency issues is generated (e.g., in out/dependency-reports/dependency-report.html). This report includes:

• Summary of scanned plugins and issues found.
• Details for each issue:
  • The plugin that has the unmet dependency.
  • The missing dependency's ID, type, and required version.
  • Whether the dependency was required or optional.
  • The original message associated with the dependency rule.

An XML report (dependencies.xml) is also generated in the same directory, suitable for automated parsing.

Development & Testing

Build

The project uses Maven. To build the plugin JAR and the distributable plugin ZIP:

mvn clean package

The JAR will be in target/dep-checker-1.0.0.jar (and copied to lib/dependency-checker.jar). The plugin ZIP will be in target/dep-checker-1.0.0-plugin.zip.

Integration Tests

The project includes an Ant build script (integration_test_build.xml) for running integration tests. These tests will:

1. Download a specific version of DITA-OT (if not already cached in test/dita-ot-downloads/).
2. Build the com.android606.dep-checker plugin using Maven (invokes mvn clean package).
3. Install the main plugin and dummy test plugins into the downloaded DITA-OT instance. Dummy plugins use <?depends-on ...?> PIs to test the new mechanism.
4. Run a DITA build on a sample project to trigger the dependency checker.
5. Verify that the dependency reports are generated and check for expected outcomes.

To run the integration tests:

ant -f integration_test_build.xml

The main test output will be in the test-output/ directory, and the DITA-OT test instance will be in dita-ot-test-instance/.

About

This plugin is designed to be cross-platform and works with Ant and Java.