Skip to content

gradle-plugin.md

Latest commit

 

History

History
133 lines (76 loc) · 5.19 KB

gradle-plugin.md

File metadata and controls

133 lines (76 loc) · 5.19 KB

(gradle-plugin-page)=

Using the Nextflow Gradle plugin

Nextflow provides a new plugin create command that simplifies the creation of Nextflow plugins. This command leverages the nf-plugin-template project, which uses the Nextflow Gradle plugin to streamline plugin development.

The Nextflow Gradle plugin configures default dependencies needed for Nextflow integration and defines Gradle tasks for building, testing, and publishing Nextflow plugins. The Gradle plugin is versioned and published to the Gradle Plugin Portal, allowing developers to manage it like any other dependency. As the plugin ecosystem evolves, the Gradle plugin will enable easier maintenance and adoption of improvements. This page introduces Nextflow Gradle plugin and how to use it.

(gradle-plugin-create)=

Creating a plugin

:::{versionadded} 25.04.0 :::

The best way to create a plugin with the Nextflow Gradle plugin is to use the nextflow plugin create sub-command and create a plugin project based on the Nextflow plugin template. See {ref}dev-plugins-template for more information about the Nextflow plugin template.

To create Nextflow plugins with the Gradle plugin:

  1. Run nextflow plugin create.

  2. Follow the prompts to add your plugin name, plugin provider, and project path.

    :::{note} Your plugin provider is usually your organization. This must match the provider specified when claiming your plugin. :::

  3. Develop your plugin extension points. See {ref}dev-plugins-extension-points for more information.

  4. Develop your tests. See {ref}gradle-plugin-test for more information.

  5. In the plugin root directory, run make assemble.

Installing a plugin

Plugins can be installed locally without being published.

To install plugins locally:

  1. In the plugin root directory, run make install.

    :::{note} Running make install will add your plugin to your $HOME/.nextflow/plugins directory. :::

  2. Run your pipeline:

    nextflow run main.nf -plugins <PLUGIN_NAME>@<VERSION>

    Replace <PLUGIN_NAME>@<VERSION> with your plugin name and version.

    :::{note} Plugins can also be configured via Nextflow configuration files. See {ref}using-plugins-page for more information. :::

(gradle-plugin-test)=

Testing a plugin

Testing your Nextflow plugin requires unit tests and end-to-end tests.

Unit tests

Unit tests are small, focused tests designed to verify the behavior of individual plugin components.

To run unit tests:

  1. Develop your unit tests. See MyObserverTest.groovy in the plugin template for an example unit test.

  2. In the plugin root directory, run make test.

End-to-end tests

End-to-end tests are comprehensive tests that verify the behavior of an entire plugin as it would be used in Nextflow pipelines.

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 for an example end-to-end test.

(gradle-plugin-publish)=

Publishing a plugin

The Nextflow Gradle plugin allows you to publish plugins to the Nextflow plugin registry from the command line.

(gradle-plugin-readme)=

README.md requirement

When publishing to the registry, your project must include a README.md file in the plugin project root directory. This file will be used as the plugin description in the registry.

Required sections:

  1. Summary - Explain what the plugin does
  2. Get Started - Setup and configuration instructions
  3. Examples - Code examples with code blocks
  4. License - Specify the plugin's license (e.g., Apache 2.0, MIT, GPL)

Optional sections:

  • What's new - Recent changes or new features
  • Breaking changes - Incompatible changes users should be aware of

Requirements:

  • Content must be meaningful (no placeholder text like TODO, TBD, Lorem ipsum)
  • Content must be in English

Publishing steps

To publish plugins to the Nextflow plugin registry:

  1. {ref}Claim your plugin <plugin-registry-claim> in the registry.

    :::{note} You can claim a plugin even if it doesn't exist in the registry yet. :::

  2. Create a file named $HOME/.gradle/gradle.properties, where $HOME is your home directory.

  3. Add your API key to the file:

    npr.apiKey=<API_KEY>

    Replace <API_KEY> with your plugin registry API key. See {ref}plugin-registry-access-token for more information.

  4. Run make release.

Additional resources

For additional Nextflow Gradle plugin configuration options, see the Nextflow Gradle plugin repository.
⚡