Skip to content

Commit 60632f2

Browse files
bentshermanbentsherman
committed
cleanup
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
1 parent a71ffcc commit 60632f2

File tree

13 files changed

+378
-408
lines changed

13 files changed

+378
-408
lines changed

‎docs/gradle-plugin.md

Lines changed: 0 additions & 85 deletions
This file was deleted.

‎docs/guides/gradle-plugin.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
(gradle-plugin-page)=
2+
3+
# Using the Nextflow Gradle plugin
4+
5+
The [Nextflow Gradle plugin](https://github.com/nextflow-io/nextflow-plugin-gradle) simplifies plugin development by configuring default dependencies needed for Nextflow integration and defining Gradle tasks for building, testing, and publishing Nextflow plugins.
6+
7+
:::{note}
8+
The Nextflow Gradle plugin and plugin registry are currently available as a private beta. See the {ref}`migration guide <plugin-registry-page>` for more information.
9+
:::
10+
11+
(gradle-plugin-create)=
12+
13+
## Creating a plugin
14+
15+
:::{versionadded} 25.04.0
16+
:::
17+
18+
The easiest way to get started with the Nextflow Gradle plugin is to use the `nextflow plugin create` sub-command, which creates a plugin project based on the [Nextflow plugin template](https://github.com/nextflow-io/nf-plugin-template/), which in turn uses the Gradle plugin.
19+
20+
To create a Nextflow plugin with the Gradle plugin, run `nextflow plugin create` on the command line. It will prompt you for your plugin name, organization name, and project path.
21+
22+
See {ref}`dev-plugins-template` for more information about the Nextflow plugin template. See {ref}`dev-plugins-extension-points` for more information about using plugin extension points.
23+
24+
## Building a plugin
25+
26+
To build a plugin, run `make assemble`.
27+
28+
Plugins can also be installed locally without being published. To install a plugin locally:
29+
30+
1. In the plugin root directory, run `make install`.
31+
32+
:::{note}
33+
Running `make install` will add your plugin to your `$HOME/.nextflow/plugins` directory.
34+
:::
35+
36+
2. Run your pipeline:
37+
38+
```bash
39+
nextflow run main.nf -plugins <PLUGIN_NAME>@<VERSION>
40+
```
41+
42+
:::{note}
43+
Plugins can also be configured via nextflow configuration files. See {ref}`using-plugins-page` for more information.
44+
:::
45+
46+
(gradle-plugin-test)=
47+
48+
## Testing a plugin
49+
50+
<h3>Unit tests</h3>
51+
52+
Unit tests are small, focused tests designed to verify the behavior of individual plugin components.
53+
54+
To run unit tests:
55+
56+
1. Develop your unit tests. See [MyObserverTest.groovy](https://github.com/nextflow-io/nf-plugin-template/blob/main/src/test/groovy/acme/plugin/MyObserverTest.groovy) in the [plugin template](https://github.com/nextflow-io/nf-plugin-template) for an example unit test.
57+
58+
2. In the plugin root directory, run `make test`.
59+
60+
<h3>End-to-end tests</h3>
61+
62+
End-to-end tests are comprehensive tests that verify the behavior of an entire plugin as it would be used in a Nextflow pipeline. End-to-end tests should be tailored to the needs of your plugin, but generally take the form of a small Nextflow pipeline. See the `validation` directory in the [plugin template](https://github.com/nextflow-io/nf-plugin-template) for an example end-to-end test.
63+
64+
(gradle-plugin-publish)=
65+
66+
## Publishing a plugin
67+
68+
The Nextflow Gradle plugin allows you to publish your plugin to the Nextflow plugin registry from the command line.
69+
70+
To publish your plugin:
71+
72+
1. Create a file named `$HOME/.gradle/gradle.properties`, where `$HOME` is your home directory.
73+
74+
2. Add the following properties:
75+
76+
```
77+
pluginRegistry.accessToken=<REGISTRY_ACCESS_TOKEN>
78+
```
79+
80+
Replace `<REGISTRY_ACCESS_TOKEN>` with your plugin registry access token.
81+
82+
3. Run `make release`.

‎docs/guides/plugin-registry.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
(plugin-registry-page)=
2+
3+
# Migrating to the Nextflow plugin registry
4+
5+
The Nextflow plugin ecosystem is evolving to support a more robust and user-friendly experience by simplifying the development, publishing, and discovery of Nextflow plugins. This page introduces the Nextflow plugin registry, the Nextflow Gradle plugin, and how to migrate to them.
6+
7+
:::{note}
8+
The Nextflow plugin registry and Gradle plugin are currently available as a private beta. Plugin developers are encouraged to contact [info@nextflow.io](mailto:info@nextflow.io) for more information about accessing the registry.
9+
:::
10+
11+
## Overview
12+
13+
### Nextflow plugin registry
14+
15+
The Nextflow plugin registry is a central repository for Nextflow plugins. It hosts an index of plugin metadata that supports plugin discovery, accessibility, and version tracking. Nextflow 25.04 and later can use the plugin registry as a drop-in replacement for the [legacy plugin index](https://github.com/nextflow-io/plugins) hosted on GitHub.
16+
17+
### Nextflow Gradle plugin
18+
19+
The [Nextflow Gradle plugin](https://github.com/nextflow-io/nextflow-plugin-gradle) simplifies the development of Nextflow plugins. It provides default configuration required for Nextflow integration, as well as custom Gradle tasks for building, testing, and publishing plugins.
20+
21+
The Gradle plugin is versioned and published to the [Gradle Plugin Portal](https://plugins.gradle.org/), allowing developers to manage it like any other dependency. As the plugin ecosystem evolves, the Gradle plugin will enable easier maintenance and adoption of ongoing improvements to the Nextflow plugin framework.
22+
23+
## Timeline
24+
25+
The [legacy plugin index](https://github.com/nextflow-io/plugins) will be deprecated in favor of the Nextflow plugin registry.
26+
27+
:::{note}
28+
The following timeline is tentative and subject to modification.
29+
:::
30+
31+
<h3>Nextflow 25.04</h3>
32+
33+
The Nextflow plugin registry is available as a private beta. Nextflow 25.04 can use the Nextflow plugin registry as an opt-in feature. The Nextflow plugin registry will be automatically kept up-to-date with the [legacy plugin index](https://github.com/nextflow-io/plugins).
34+
35+
During this time, plugin developers are encouraged to experiment with the Gradle plugin and plugin registry.
36+
37+
<h3>Nextflow 25.10</h3>
38+
39+
The Nextflow plugin registry will be generally available. Nextflow 25.10 will use the plugin registry by default. The legacy plugin index will be **closed to new pull requests**.
40+
41+
Developers will be required to publish to the Nextflow plugin registry. To ensure continued support for older versions of Nextflow, the legacy plugin index will be automatically kept up-to-date with the Nextflow plugin registry.
42+
43+
<h3>Nextflow 26.04</h3>
44+
45+
Nextflow 26.04 will only be able to use the Nextflow plugin registry.
46+
47+
At some point in the future, the legacy plugin index will be **frozen** -- it will no longer receives updates from the Nextflow plugin registry. To ensure continued support for older versions of Nextflow, the legacy plugin index will remain available indefinitely.
48+
49+
## Impact on plugin users
50+
51+
No immediate actions are required for plugin users. The plugin configuration has not changed.
52+
53+
## Impact on plugin developers
54+
55+
Plugin developers will need to update their plugin to publish to the Nextflow plugin registry instead of the legacy plugin index. The easiest way to do this is to migrate to the Nextflow Gradle plugin, which simplifies the development process and supports publishing to the plugin registry from the command line.
56+
57+
### Migrating to the Nextflow Gradle plugin
58+
59+
To migrate an existing Nextflow plugin:
60+
61+
1. Remove the following files and folders:
62+
- `buildSrc/`
63+
- `launch.sh`
64+
- `plugins/build.gradle`
65+
66+
2. If your plugin has a `plugins` directory, move the `src` directory to the project root.
67+
68+
:::{note}
69+
Plugin sources should be in `src/main/groovy` or `src/main/java`.
70+
:::
71+
72+
3. Replace the contents of `settings.gradle` with the following:
73+
74+
```groovy
75+
rootProject.name = '<PLUGIN_NAME>'
76+
```
77+
78+
Replace `PLUGIN_NAME` with your plugin name.
79+
80+
4. In the project root, create a new `build.gradle` file with the following configuration:
81+
82+
```groovy
83+
// Plugins
84+
plugins {
85+
id 'io.nextflow.nextflow-plugin' version '0.0.1-alpha4'
86+
}
87+
88+
// Dependencies (optional)
89+
dependencies {
90+
<DEPENDENCY>
91+
}
92+
93+
// Plugin version
94+
version = '<PLUGIN_VERSION>'
95+
96+
nextflowPlugin {
97+
// Minimum Nextflow version
98+
nextflowVersion = '<MINIMUM_NEXTFLOW_VERSION>'
99+
100+
// Plugin metadata
101+
provider = '<PROVIDER>'
102+
className = '<CLASS_NAME>'
103+
extensionPoints = [
104+
'<EXTENSION_POINT>'
105+
]
106+
107+
publishing {
108+
registry {
109+
authToken = project.findProperty('pluginRegistry.accessToken')
110+
}
111+
}
112+
}
113+
```
114+
115+
Replace the following:
116+
117+
- `DEPENDENCY`: (Optional) Your plugins dependency libraries—for example, `commons-io:commons-io:2.18.0`.
118+
- `PLUGIN_VERSION:` Your plugin version—for example, `0.5.0`.
119+
- `MINIMUM_NEXTFLOW_VERSION`: The minimum Nextflow version required to run your plugin—for example, `25.04.0`.
120+
- `PROVIDER`: Your name or organization—for example, `acme`.
121+
- `CLASS_NAME`: Your plugin class name—for example, `acme.plugin.MyPlugin`.
122+
- `EXTENSION_POINT`: Your extension point identifiers that the plugin will implement or expose—for example, `acme.plugin.MyFactory`.
123+
124+
5. Replace the contents of `Makefile` with the following:
125+
126+
```Makefile
127+
# Build the plugin
128+
assemble:
129+
./gradlew assemble
130+
131+
clean:
132+
rm -rf .nextflow*
133+
rm -rf work
134+
rm -rf build
135+
./gradlew clean
136+
137+
# Run plugin unit tests
138+
test:
139+
./gradlew test
140+
141+
# Install the plugin into local nextflow plugins dir
142+
install:
143+
./gradlew install
144+
145+
# Publish the plugin
146+
release:
147+
./gradlew releasePlugin
148+
```
149+
150+
6. Update `README.md` with information about the structure of your plugin.
151+
152+
7. In the plugin root directory, run `make assemble`.
153+
154+
Alternatively, use the `nextflow plugin create` command to re-create your plugin with the plugin template and add your existing plugin code. See {ref}`dev-plugins-template` for more information about the plugin template.
155+
156+
### Publishing to the Nextflow plugin registry
157+
158+
The Nextflow Gradle plugin supports publishing plugins from the command line. See {ref}`gradle-plugin-publish` for more information.
159+
160+
Once you migrate to the Gradle plugin, you will no longer be able to publish to the legacy plugin index. See the [transition timeline](#timeline) for more information.

‎docs/index.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,6 @@ developer/packages
163163
plugins/plugins
164164
plugins/using-plugins
165165
plugins/developing-plugins
166-
plugins/example-nf-hello
167166
```
168167

169168
```{toctree}
@@ -183,7 +182,7 @@ tutorials/flux
183182
:maxdepth: 1
184183
185184
guides/aws-java-sdk-v2
185+
guides/gradle-plugin
186+
guides/plugin-registry
186187
guides/updating-spot-retries
187-
gradle-plugin
188-
migrating-gradle-plugin
189188
```

0 commit comments

Comments
 (0)