diff --git a/modello-ant-task/README.md b/modello-ant-task/README.md new file mode 100644 index 000000000..de289eddd --- /dev/null +++ b/modello-ant-task/README.md @@ -0,0 +1,188 @@ +# Modello Ant Task + +The `modello-ant-task` is an Apache Ant task that integrates [Codehaus Modello](https://codehaus-plexus.github.io/modello/) into Ant build workflows. It allows you to generate Java classes, XML serializers/deserializers, XML Schemas (XSD), documentation, and other outputs from Modello model description (`.mdo`) files. + +--- + +## Installation & Definition + +To use the task in your Ant build file, define it using either the individual task definition or the preferred standard `antlib` resource. + +### Option 1: Using Antlib (Recommended) + +```xml + +``` + +### Option 2: Using Taskdef + +```xml + +``` + +*Note: `modello.classpath` must contain the `modello-ant-task` JAR, `modello-core`, and any runtime Modello generator plugins you wish to use.* + +--- + +## Task Reference + +The `` task supports several attributes and nested elements to configure code generation. + +### Attributes + +| Attribute | Type | Description | Required | Default | +|:-------------------------------|:----------|:--------------------------------------------------------------------------------------|:--------:|:---------:| +| **`version`** | `String` | The model version to generate (e.g., `1.0.0`). | **Yes** | — | +| **`outputDirectory`** | `File` | The directory where the generated files will be written. | **Yes** | — | +| **`javaSource`** | `String` | Target Java version for generated source code. | No | `8` | +| **`encoding`** | `String` | Character encoding for generated files. | No | `"utf-8"` | +| **`packageWithVersion`** | `boolean` | Whether to append the version to the package name (`"true"` / `"false"`). | No | `false` | +| **`packagedVersions`** | `String` | Comma-separated list of versions to generate backward compatibility for. | No | — | +| **`domAsXpp3`** | `boolean` | Whether to generate DOM content as Xpp3Dom (`"true"`) or W3C DOM Element (`"false"`). | No | `true` | +| **`licenseFile`** | `File` | Path to file containing license header text to prepend to generated files. | No | — | +| **`licenseText`** | `String` | License header text to prepend to generated files. | No | — | +| **`extendedClassnameSuffix`** | `String` | Suffix for extended class names (e.g., `Ex`). | No | — | +| **`xsdFileName`** | `String` | Custom output file name for generated XSD schema (`xsd` goal). | No | — | +| **`enforceMandatoryElements`** | `boolean` | Whether to enforce mandatory elements in XSD (`"true"` / `"false"`). | No | `false` | +| **`jsonSchemaFileName`** | `String` | Custom output file name for generated JSON Schema (`jsonschema` goal). | No | — | +| **`firstVersion`** | `String` | Earliest version to document when generating documentation (`xdoc` goal). | No | — | +| **`xdocFileName`** | `String` | Custom output file name for generated XDoc documentation (`xdoc` goal). | No | — | +| **`velocityBasedir`** | `File` | Base directory of template files (required only for Velocity-based goals). | No | — | + +### Nested Elements + +#### `` + +Specifies the Modello model description file to read. At least one `` element is required. +* **`file`** (`File`, Required): Path to the `.mdo` model file. + +```xml + +``` + +#### `` + +Specifies the Modello generator target to run. At least one `` element is required. +* **`name`** (`String`, Required): The generator plugin name (e.g., `java`, `xdoc`, `xsd`, `xpp3-reader`, `xpp3-writer`, `velocity`). + +```xml + +``` + +#### `` + +Specifies an additional model version to package. Can be specified multiple times. +* **`name`** (`String`, Required): The version string (e.g., `1.0.0`). + +```xml + + +``` + +#### `` + +Specifies license header content to prepend to generated sources. +* **`file`** (`File`, Optional): File containing license header text. +* **`text`** (`String`, Optional): Direct license text string (can also be passed as nested text). + +```xml + +``` + +#### `` + +Specifies an irregular plural mapping used during field naming generation. +* **`name`** (`String`, Required): The plural form (e.g., `aliases`). +* **`value`** (`String`, Required): The singular form (e.g., `alias`). + +```xml + +``` + +#### `