Package directive

PACKAGE_MANAGEMENT.md

@@ -0,0 +1,219 @@
+# Unified Package Management System
+
+This document describes the new unified package management system in Nextflow, introduced as a preview feature behind the `nextflow.preview.package` flag.
+
+## Overview
+
+The unified package management system provides a consistent interface for managing packages across different package managers (conda, pixi, mamba, etc.) through a single `package` directive.
+
+## Enabling the Feature
+
+Add this to your `nextflow.config`:
+
+```groovy
+nextflow.preview.package = true
+```
+
+## Basic Usage
+
+### Single Package
+
+```groovy
+process example {
+    package "samtools=1.17", provider: "conda"
+
+    script:
+    """
+    samtools --version
+    """
+}
+```
+
+### Multiple Packages
+
+```groovy
+process example {
+    package ["samtools=1.17", "bcftools=1.18"], provider: "conda"
+
+    script:
+    """
+    samtools --version
+    bcftools --version
+    """
+}
+```
+
+### Using Default Provider
+
+Configure a default provider in your config:
+
+```groovy
+packages {
+    provider = 'conda'
+}
+```
+
+Then use:
+
+```groovy
+process example {
+    package "samtools=1.17"  // uses default provider
+
+    script:
+    """
+    samtools --version
+    """
+}
+```
+
+### Advanced Configuration
+
+```groovy
+process example {
+    package {
+        provider = "conda"
+        packages = ["samtools=1.17", "bcftools=1.18"]
+        channels = ["conda-forge", "bioconda"]
+        options = [
+            createTimeout: "30 min"
+        ]
+    }
+
+    script:
+    """
+    samtools --version
+    bcftools --version
+    """
+}
+```
+
+### Environment Files
+
+```groovy
+process example {
+    package {
+        provider = "conda"
+        environment = file("environment.yml")
+    }
+
+    script:
+    """
+    python script.py
+    """
+}
+```
+
+## Supported Providers
+
+- `conda` - Anaconda/Miniconda package manager
+- `pixi` - Fast conda alternative with lockfiles
+- `mamba` - Fast conda alternative
+- `micromamba` - Minimal conda implementation
+
+## Configuration
+
+### Global Configuration
+
+```groovy
+// nextflow.config
+nextflow.preview.package = true
+
+packages {
+    provider = 'conda'  // default provider
+}
+
+// Provider-specific configurations
+conda {
+    channels = ['conda-forge', 'bioconda']
+    createTimeout = '20 min'
+}
+
+pixi {
+    cacheDir = '/tmp/pixi-cache'
+}
+```
+
+## Wave Integration
+
+The unified package system integrates with Wave for containerization:
+
+```groovy
+process example {
+    package "samtools=1.17", provider: "conda"
+
+    script:
+    """
+    samtools --version
+    """
+}
+```
+
+Wave will automatically create a container with the specified packages.
+
+## Backward Compatibility
+
+Old `conda` and `pixi` directives continue to work but show deprecation warnings when the preview feature is enabled:
+
+```groovy
+process oldStyle {
+    conda 'samtools=1.17'  // Shows deprecation warning
+
+    script:
+    """
+    samtools --version
+    """
+}
+```
+
+## Migration Guide
+
+### From conda directive
+
+**Before:**
+```groovy
+process example {
+    conda 'samtools=1.17 bcftools=1.18'
+    script: "samtools --version"
+}
+```
+
+**After:**
+```groovy
+process example {
+    package ["samtools=1.17", "bcftools=1.18"], provider: "conda"
+    script: "samtools --version"
+}
+```
+
+### From pixi directive
+
+**Before:**
+```groovy
+process example {
+    pixi 'samtools bcftools'
+    script: "samtools --version"
+}
+```
+
+**After:**
+```groovy
+process example {
+    package ["samtools", "bcftools"], provider: "pixi"
+    script: "samtools --version"
+}
+```
+
+## Plugin Architecture
+
+The system is extensible through plugins. Package managers are implemented as plugins that extend the `PackageProviderExtension` interface:
+
+- `nf-conda` - Conda support
+- `nf-pixi` - Pixi support
+
+Custom package managers can be added by implementing the `PackageProvider` interface and registering as a plugin.
+
+## Examples
+
+See the test files for complete examples:
+- `tests/package-test.nf` - Basic usage examples
+- `tests/integration-test.nf` - Integration and backward compatibility tests

docs/conda.md

@@ -35,6 +35,10 @@ The Conda environment feature is not supported by executors that use remote obje
 
 The use of Conda recipes specified using the {ref}`process-conda` directive needs to be enabled explicitly in the pipeline configuration file (i.e. `nextflow.config`):
 
+:::{note}
+Nextflow also provides a unified {ref}`package-page` system that supports conda and other package managers through a single interface. This newer system is enabled with the `preview.package` feature flag and provides a more consistent experience across different package managers.
+:::
+
 ```groovy
 conda.enabled = true
 ```
@@ -191,6 +195,49 @@ process hello {
 
 It is also possible to use [mamba](https://github.com/mamba-org/mamba) to speed up the creation of conda environments. For more information on how to enable this feature please refer to {ref}`Conda <config-conda>`.
 
+## Migration to Unified Package Management
+
+The unified {ref}`package-page` system provides a modern alternative to the conda directive. When the `preview.package` feature is enabled, you can use the new syntax:
+
+### Before (conda directive):
+```nextflow
+process example {
+    conda 'samtools=1.15 bcftools=1.15'
+
+    script:
+    """
+    samtools --version
+    bcftools --version
+    """
+}
+```
+
+### After (package directive):
+```nextflow
+process example {
+    package 'samtools=1.15 bcftools=1.15', provider: 'conda'
+
+    script:
+    """
+    samtools --version
+    bcftools --version
+    """
+}
+```
+
+To enable the unified package system:
+
+```groovy
+// nextflow.config
+nextflow.preview.package = true
+```
+
+The unified system provides:
+- Consistent interface across different package managers
+- Plugin-based architecture for extensibility
+- Better integration with containerization platforms
+- Support for multiple package managers (conda, pixi, etc.)
+
 ## Best practices
 
 When a `conda` directive is used in any `process` definition within the workflow script, Conda tool is required for the workflow execution.