Skip to content

Commit

Permalink
Fix README
Browse files Browse the repository at this point in the history
  • Loading branch information
@baloo42
baloo42 committed May 15, 2024
1 parent 4141076 commit 2139478
Showing 1 changed file with 19 additions and 21 deletions.
40 changes: 19 additions & 21 deletions crd-generator/maven-plugin/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,10 @@ Maven plugin for the CRD-Generator: Generate CRDs from Java model during Maven b

### Scan project for Custom Resource classes

By default, the `target/` directory will be scanned for Custom Resource classes and the resulting CRDs will be emitted
below `target/META-INF/fabric8/`:
By default, the `target/classes` (`${project.build.outputDirectory}`) directory will be scanned for Custom Resource classes and the resulting CRDs will be emitted
below `target/classes/META-INF/fabric8/` (`${project.build.outputDirectory}/META-INF/fabric8/`):

```xml

<plugin>
<groupId>io.fabric8</groupId>
<artifactId>crd-generator-maven-plugin</artifactId>
Expand All @@ -30,7 +29,6 @@ The involved Custom Resource classes can also be configured explicitly. In this
provided classes are used.

```xml

<plugin>
<groupId>io.fabric8</groupId>
<artifactId>crd-generator-maven-plugin</artifactId>
Expand All @@ -56,7 +54,6 @@ If CRDs for a Java model of an external project or another module should be gene
be specified and added to the classpath.

```xml

<dependencies>
<dependency>
<groupId>io.fabric8.crd-generator.maven.example</groupId>
Expand Down Expand Up @@ -104,7 +101,6 @@ The Custom Resource classes which should be used by the CRD Generator can be fil
Either by including or excluding:

```xml

<dependencies>
<dependency>
<groupId>io.fabric8.crd-generator.maven.example</groupId>
Expand Down Expand Up @@ -141,22 +137,22 @@ Either by including or excluding:

### More Configuration Parameters

| Parameter | Description |
|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `outputDirectory` | The output directory where the CRDs are emitted.<br>Default: `${project.build.outputDirectory}/META-INF/fabric8/` |
| `forceIndex` | If `true`, a Jandex index will be created even if the directory or JAR file contains an existing index.<br>Default: `false` |
| `forceScan` | If `true`, directories and JAR files are scanned even if Custom Resource classes are given.<br>Default: `false` |
| `implicitPreserveUnknownFields` | If `true`, `x-kubernetes-preserve-unknown-fields: true` will be added to objects which contain an any-setter or any-getter.<br>Default: `false` |
| `parallel` | If `true`, the CRDs will be generated in parallel.<br>Default: `true` |
| `skip` | If `true`, execution will be skipped.<br>Default: `false` |
| Parameter | Description |
|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `outputDirectory` | The output directory where the CRDs are emitted.<br>Default: `${project.build.outputDirectory}/META-INF/fabric8/` |
| `forceIndex` | If `true`, a Jandex index will be created even if the directory or JAR file contains an existing index. See [Using existing indices](#using-existing-indices) for details.<br>Default: `false` |
| `forceScan` | If `true`, directories and JAR files are scanned even if Custom Resource classes are given.<br>Default: `false` |
| `implicitPreserveUnknownFields` | If `true`, `x-kubernetes-preserve-unknown-fields: true` will be added to objects which contain an any-setter or any-getter.<br>Default: `false` |
| `parallel` | If `true`, the CRDs will be generated in parallel.<br>Default: `true` |
| `skip` | If `true`, execution will be skipped.<br>Default: `false` |

## Jandex

The CRD-Generator Maven plugin uses [jandex](https://github.com/smallrye/jandex) under the hood to
find Custom Resource classes.

With jandex, metadata of compiled Java classes can be collected in an index and this index can be used to
search for classes which implement an interface and/or are annotated by annotations.
Jandex allows to collect and aggregate metadata of compiled Java classes into an index, which can be used afterward to
search for classes which implement an interface, extend a class and/or are annotated by annotations.

The CRD-Generator Maven plugin creates the necessary index automatically and searches for
Custom Resource classes in this index by using the following criteria:
Expand All @@ -165,16 +161,18 @@ Custom Resource classes in this index by using the following criteria:
- The class must be annotated by `@Group` and `@Version`

> [!NOTE]
> The abstract class `CustomResource` implements `HasMetadata`. As such a class which implements `CustomResource` will be found, too.
> The abstract class `CustomResource` implements `HasMetadata`.
> As such a class which extends `CustomResource` will be found, too.
> [!IMPORTANT]
> If your Custom Resource classes extend an own abstract class or own interface, so that `HasMetadata` is only implemented
> indirect, then ensure that this intermediate class is included in the scan scope.
> If your Custom Resource class extends an own abstract class or own interface, so that `HasMetadata` is only
> implemented indirect, then ensure that this intermediate class is included in the scan / index.
### Reusing existing indices
### Using existing indices

If the project or the dependency to scan already contains a serialized Jandex index,
this pre-existing index will be used instead of generating an own index and will result in a small performance gain.
This behaviour can be overridden by setting `forceIndex` to `true`.

To always create an own index, set `forceIndex` to `true`.


0 comments on commit 2139478

Please sign in to comment.