Skip to content

Commit

Permalink
Document the verify goal of the bnd-resolver-maven-plugin
Browse files Browse the repository at this point in the history 
This commit updates the documentation for the bnd-resolver-maven-plugin to describe the verify goal. It also removes a configuration property and small quantity of dead code from the VerifierMojo which is not necessary for verification.

Signed-off-by: Tim Ward <[email protected]>
  • Loading branch information
@timothyjward
timothyjward committed Jan 24, 2024
1 parent 24634d9 commit 0ffe4c5
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 42 deletions.
45 changes: 38 additions & 7 deletions maven-plugins/bnd-resolver-maven-plugin/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# bnd-resolver-maven-plugin

The `bnd-resolver-maven-plugin` is a bnd based plugin to resolve bundles from bndrun files.
The `bnd-resolver-maven-plugin` is a bnd based plugin to resolve and validate bundles in bndrun files.

## What does the `bnd-resolver-maven-plugin` do?

Point the plugin to one or more bndrun files in the same project. It will resolve the -runbundles value.
Point the plugin to one or more bndrun files in the same project. It can `resolve` or `verify` the -runbundles value for that bndrun file.

```
<plugin>
Expand All @@ -27,6 +27,19 @@ Point the plugin to one or more bndrun files in the same project. It will resolv
</plugin>
```

### What's the difference between "resolve" and "verify"

A `resolve` operation uses the `-runrequires` from your bndrun file to *generate* the content of the `-runbundles`. This is usually saved back to the bnrun file so that you can use it with another plugin such as `bnd-testing-maven-plugin` or `bnd-export-maven-plugin`. The `resolve` goal is normally executed directly from the command line, or bound to a profile, so that a developer can regenerate the list of bundles after making changes to the code.

The `verify` goal is fundamentally different from `resolve` as it will never create a list of `-runbundles` for you - it only works with bndrun files that are already resolved. A `verify` operation *checks* the `-runbundles` from your bndrun file to make sure that they:

1. Are a valid resolution
2. Satisfy the `-runrequires` requirements

The `verify` goal is normally bound to a lifecycle phase and executed as part of the build. This may only be enabled in CI, for example by using a profile, or it may be run as part of every build. A failure from the `verify` goal indicates that the bndrun needs to be updated, either by hand, or by using the `resolve` goal.

### Using bundles from the file system

Here's an example setting the `bundles` used for resolution.

```
Expand All @@ -43,13 +56,22 @@ Here's an example setting the `bundles` used for resolution.

## Executing the resolve operation

Since the resolve operation is not associated with any maven build phase, it must in invoked manually.
Since the resolve operation is not associated with any maven build phase, it must be invoked manually, or bound to a lifecycle phase in configuration.

Here's an example invocation:
```
mvn bnd-resolver:resolve
```

## Executing the verify operation

Since the verify operation is not associated with any maven build phase, it must be invoked manually, or bound to a lifecycle phase in configuration.

Here's an example invocation:
```
mvn bnd-resolver:verify
```

## Bndrun Details Inferred from Maven

The `-runee` and `-runrequires` values can be inferred from the maven project as follows:
Expand All @@ -61,18 +83,27 @@ The `-runee` and `-runrequires` values can be inferred from the maven project as

An *implicit repository* containing the project artifact and project dependencies (as defined through the configuration of `bundles`, `scopes`, `useMavenDependencies` and `includeDependencyManagement`) is created and added when this plugin is executed.

## Configuration Properties
## Common Configuration Properties

The following configuration properties are common to both the `resolve` and `verify` goals

| Configuration Property | Description |
|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `bndruns` | Can contain `bndrun` child elements specifying a bndrun file to resolve. These are relative to the `${project.basedir}` directory. You can also specify `include` and `exclude` child elements using Ant-style globs to specify bndrun files in the `bndrunDir` directory. _Defaults to `<include>*.bndrun</include>`._ |
| `bndrunDir` | This directory will be used when locating bndrun files using `include` and `exclude`. _Defaults to `${project.basedir}`_. |
| `outputBndrunDir` | The bndrun files will be written to the specified directory. If the specified directory is the same as `bndrunDir`, then any changes to a bndrun files will cause the bndrun file to be overwritten. _Defaults to `${project.basedir}`_. |
| `failOnChanges` | Whether to fail the build if any change in the resolved `-runbundles` is discovered. _Defaults to `true`._ |
| `writeOnChanges` | Whether to write the resolved run bundles back to the `-runbundles` property of the `bndrun` file. _Defaults to `true`._ |
| `bundles` | A collection of files to include in the *implicit repository*. Can contain `bundle` child elements specifying the path to a bundle. These can be absolute paths. You can also specify `include` and `exclude` child elements using Ant-style globs to specify bundles. These are relative to the `${project.basedir}` directory. _Defaults to dependencies in the scopes specified by the `scopes` property, plus the current artifact (if any and `useMavenDependencies` is `true`)._ |
| `useMavenDependencies` | If `true`, adds the project dependencies subject to `scopes` to the collection of files to include in the *implicit repository*. _Defaults to `true`._ |
| `reportOptional` | If `true`, resolution failure reports will include optional requirements. _Defaults to `true`._ |
| `scopes` | Specify from which scopes to collect dependencies. _Defaults to `compile, runtime`._ Override with property `bnd.resolve.scopes`. |
| `includeDependencyManagement` | Include `<dependencyManagement>` subject to `scopes` when collecting files to include in the *implicit repository*. _Defaults to `false`._ Override with property `bnd.resolve.include.dependency.management`. |
| `skip` | Skip the project. _Defaults to `false`._ Override with property `bnd.resolve.skip`. |

### Additional Configuration Properties for the resolve goal

The following properties apply only to the `resolve` goal

| Configuration Property | Description |
|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `outputBndrunDir` | The bndrun files will be written to the specified directory. If the specified directory is the same as `bndrunDir`, then any changes to a bndrun files will cause the bndrun file to be overwritten. _Defaults to `${project.basedir}`_. |
| `failOnChanges` | Whether to fail the build if any change in the resolved `-runbundles` is discovered. _Defaults to `true`._ |
| `writeOnChanges` | Whether to write the resolved run bundles back to the `-runbundles` property of the `bndrun` file. _Defaults to `true`._ |
35 changes: 0 additions & 35 deletions ...bnd-resolver-maven-plugin/src/main/java/aQute/bnd/maven/resolver/plugin/VerifierMojo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,9 @@
import static java.util.stream.Collectors.toList;

import java.io.File;
import java.io.Writer;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.Objects;
import java.util.Set;
import java.util.stream.Collectors;

Expand All @@ -25,8 +23,6 @@
import aQute.bnd.osgi.resource.ResourceUtils;
import aQute.bnd.unmodifiable.Sets;
import aQute.bnd.version.VersionRange;
import aQute.lib.io.IO;
import aQute.lib.utf8properties.UTF8Properties;
import biz.aQute.resolve.ResolutionCallback;
import biz.aQute.resolve.ResolveProcess;
import biz.aQute.resolve.RunResolution;
Expand Down Expand Up @@ -99,14 +95,6 @@ public class VerifierMojo extends AbstractMojo {
@Parameter(defaultValue = "${project.basedir}")
private File bndrunDir;

/**
* The bndrun files will be written to this directory. If the
* specified directory is the same as {@link #bndrunDir}, then
* any changes to a bndrun file will cause the bndrun file to be overwritten.
*/
@Parameter(defaultValue = "${project.basedir}")
private File outputBndrunDir;

@Component
private RepositorySystem system;

Expand Down Expand Up @@ -146,16 +134,6 @@ public void execute() throws MojoExecutionException, MojoFailureException {

for (File runFile : bndrunFiles) {
logger.info("Verifying {}:", runFile);
if (!Objects.equals(outputBndrunDir, bndrunDir)) {
IO.mkdirs(outputBndrunDir);
File outputRunFile = new File(outputBndrunDir, runFile.getName());
try (Writer writer = IO.writer(outputRunFile)) {
UTF8Properties props = new UTF8Properties();
props.setProperty(Constants.INCLUDE, String.format("\"~%s\"", escape(IO.absolutePath(runFile))));
props.store(writer, null);
}
runFile = outputRunFile;
}
errors += container.execute(runFile, "resolve", targetDir, operation);
}
} catch (Exception e) {
Expand Down Expand Up @@ -271,17 +249,4 @@ public void processCandidates(Requirement requirement, Set<Capability> wired, Li
}
}
}

private String escape(String input) {
final int length = input.length();
StringBuilder sb = new StringBuilder(length);
for (int i = 0; i < length;i++) {
char c = input.charAt(i);
if (c == '"') {
sb.append('\\');
}
sb.append(c);
}
return sb.length() == length ? input : sb.toString();
}
}

0 comments on commit 0ffe4c5

Please sign in to comment.