Skip to content

CLAUDE.md

Latest commit

 

History

History
99 lines (80 loc) · 4.71 KB

CLAUDE.md

File metadata and controls

99 lines (80 loc) · 4.71 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Nextflow is a scientific workflow management system built primarily in Groovy and Java. It enables the creation of scalable, portable, and reproducible computational pipelines using a dataflow programming model. The project follows a modular architecture with a plugin-based system for cloud providers and specialized features.

Development Commands

Build System

  • Primary build tool: Gradle with wrapper (./gradlew)
  • Quick commands via Makefile:
    • make compile - Compile sources and export classpath
    • make assemble - Build info, compile, and assemble
    • make test - Run all tests
    • make check - Run verification tasks
    • make clean - Clean build artifacts

Testing

  • Unit tests: make test or ./gradlew test
    • Uses Spock Framework (Groovy-based testing)
    • JaCoCo integration for code coverage
  • Specific test class: ./gradlew test --tests "SomeTestClass"
  • Specific module: make test module=nextflow
  • Smoke tests: make smoke or NXF_SMOKE=1 ./gradlew test (skips long-running tests, network-dependent tests, and cloud provider integration tests)
  • Integration tests: Run from tests/ directory using test runner scripts
  • Cloud validation tests: Located in validation/ directory (requires credentials)

Development Workflow

  • Development launcher: ./launch.sh run script.nf (uses development build)
  • Dependency analysis: make deps or make deps config=runtime
  • Install locally: make install (installs to Maven local)

Architecture

Core Modules (modules/)

  • nextflow: Main application module with core workflow engine, CLI, AST transformations, executors
  • nf-commons: Shared utilities, plugin system infrastructure, extension methods
  • nf-httpfs: HTTP filesystem support and custom providers
  • nf-lang: Language parsing, ANTLR grammars, AST implementation
  • nf-lineage: Data lineage tracking and workflow execution history

Plugin System (plugins/)

  • Cloud providers: nf-amazon (AWS), nf-azure (Azure), nf-google (GCP)
  • Execution platforms: nf-k8s (Kubernetes)
  • Services: nf-tower (Seqera Platform), nf-wave (container management)
  • Other: nf-console (interactive interface), nf-cloudcache (cloud caching)

Key Technologies

  • Language: Groovy 4.0.28 (Java-compatible, targeting Java 17)
  • Concurrency: GPars 1.2.1 (Actor model, parallel/concurrent programming)
  • Build: Gradle with Java 21 toolchain
  • Parsing: ANTLR for Nextflow DSL
  • Serialization: Kryo
  • Database: LevelDB for local caching
  • Version Control: JGit integration

Testing Structure

  • Unit tests: Each module has src/test/groovy/ with Spock Framework tests
  • Integration tests: tests/ directory with .nf workflows and expected outputs
  • Legacy tests: tests-v1/ for DSL v1 compatibility
  • Validation tests: validation/ directory for cloud provider end-to-end testing
  • Documentation tests: docs/snippets/ for verifying documentation examples

Development Notes

Code Standards

  • All code must include Apache 2.0 license headers
  • Contributions require Developer Certificate of Origin (DCO) sign-off
  • Use existing code patterns and conventions from similar modules
  • Follow Groovy idioms and leverage the Nextflow DSL patterns

Common Development Tasks

  • Local development: Use make compile to build and ./launch.sh to test changes
  • Adding features: First check modules like nextflow for core features or create plugins for specialized functionality
  • Plugin development: Follow existing plugin patterns in plugins/ directory
  • Testing changes: Always run make test before committing
  • Cloud testing: Use validation scripts in validation/ directory with appropriate credentials

Build Configuration

  • Java toolchain uses version 21 for development, targets Java 17 compatibility
  • Uses shadow plugin for creating fat JARs
  • Maven publication to S3-based Seqera repositories
  • Multi-module project with shared dependencies managed in root build.gradle

Git conventions

  • Commit should be signed by adding a Signed-off-by line to the commit message as shown below, or by using the -s option (see CONTRIBUTING.md for details)

Important Files

  • VERSION: Define the current version number
  • nextflow: Launch wrapper script (updated by build process)
  • .launch.classpath: Development classpath (generated by make compile)
  • build.gradle: Root build configuration with multi-module setup
  • settings.gradle: Gradle project structure definition
  • plugins/*/VERSION: Define the version of the corresponding plugin sub-project.