|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +### Build System |
| 12 | +- **Primary build tool**: Gradle with wrapper (`./gradlew`) |
| 13 | +- **Quick commands via Makefile**: |
| 14 | + - `make compile` - Compile sources and export classpath |
| 15 | + - `make assemble` - Build info, compile, and assemble |
| 16 | + - `make test` - Run all tests |
| 17 | + - `make check` - Run verification tasks |
| 18 | + - `make clean` - Clean build artifacts |
| 19 | + |
| 20 | +### Testing |
| 21 | +- **Unit tests**: `make test` or `./gradlew test` |
| 22 | + - Uses Spock Framework (Groovy-based testing) |
| 23 | + - JaCoCo integration for code coverage |
| 24 | +- **Specific test class**: `./gradlew test --tests "SomeTestClass"` |
| 25 | +- **Specific module**: `make test module=nextflow` |
| 26 | +- **Smoke tests**: `make smoke` or `NXF_SMOKE=1 ./gradlew test` |
| 27 | +- **Integration tests**: Run from `tests/` directory using test runner scripts |
| 28 | +- **Cloud validation tests**: Located in `validation/` directory (requires credentials) |
| 29 | + |
| 30 | +### Development Workflow |
| 31 | +- **Development launcher**: `./launch.sh run script.nf` (uses development build) |
| 32 | +- **Dependency analysis**: `make deps` or `make deps config=runtime` |
| 33 | +- **Install locally**: `make install` (installs to Maven local) |
| 34 | + |
| 35 | +## Architecture |
| 36 | + |
| 37 | +### Core Modules (`modules/`) |
| 38 | +- **nextflow**: Main application module with core workflow engine, CLI, AST transformations, executors |
| 39 | +- **nf-commons**: Shared utilities, plugin system infrastructure, extension methods |
| 40 | +- **nf-httpfs**: HTTP filesystem support and custom providers |
| 41 | +- **nf-lang**: Language parsing, ANTLR grammars, AST implementation |
| 42 | +- **nf-lineage**: Data lineage tracking and workflow execution history |
| 43 | + |
| 44 | +### Plugin System (`plugins/`) |
| 45 | +- **Cloud providers**: nf-amazon (AWS), nf-azure (Azure), nf-google (GCP) |
| 46 | +- **Execution platforms**: nf-k8s (Kubernetes) |
| 47 | +- **Services**: nf-tower (Seqera Platform), nf-wave (container management) |
| 48 | +- **Other**: nf-console (interactive interface), nf-cloudcache (cloud caching) |
| 49 | + |
| 50 | +### Key Technologies |
| 51 | +- **Language**: Groovy 4.0.28 (Java-compatible, targeting Java 17) |
| 52 | +- **Concurrency**: GPars 1.2.1 (Actor model, parallel/concurrent programming) |
| 53 | +- **Build**: Gradle with Java 21 toolchain |
| 54 | +- **Parsing**: ANTLR for Nextflow DSL |
| 55 | +- **Serialization**: Kryo |
| 56 | +- **Database**: LevelDB for local caching |
| 57 | +- **Version Control**: JGit integration |
| 58 | + |
| 59 | +### Testing Structure |
| 60 | +- **Unit tests**: Each module has `src/test/groovy/` with Spock Framework tests |
| 61 | +- **Integration tests**: `tests/` directory with .nf workflows and expected outputs |
| 62 | +- **Legacy tests**: `tests-v1/` for DSL v1 compatibility |
| 63 | +- **Validation tests**: `validation/` directory for cloud provider end-to-end testing |
| 64 | +- **Documentation tests**: `docs/snippets/` for verifying documentation examples |
| 65 | + |
| 66 | +## Development Notes |
| 67 | + |
| 68 | +### Code Standards |
| 69 | +- All code must include Apache 2.0 license headers |
| 70 | +- Contributions require Developer Certificate of Origin (DCO) sign-off |
| 71 | +- Use existing code patterns and conventions from similar modules |
| 72 | +- Follow Groovy idioms and leverage the Nextflow DSL patterns |
| 73 | + |
| 74 | +### Common Development Tasks |
| 75 | +- **Local development**: Use `make compile` to build and `./launch.sh` to test changes |
| 76 | +- **Adding features**: First check modules like `nextflow` for core features or create plugins for specialized functionality |
| 77 | +- **Plugin development**: Follow existing plugin patterns in `plugins/` directory |
| 78 | +- **Testing changes**: Always run `make test` before committing |
| 79 | +- **Cloud testing**: Use validation scripts in `validation/` directory with appropriate credentials |
| 80 | + |
| 81 | +### Build Configuration |
| 82 | +- Java toolchain uses version 21 for development, targets Java 17 compatibility |
| 83 | +- Uses shadow plugin for creating fat JARs |
| 84 | +- Maven publication to S3-based Seqera repositories |
| 85 | +- Multi-module project with shared dependencies managed in root build.gradle |
| 86 | + |
| 87 | +### Git conventions |
| 88 | + |
| 89 | +- 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) |
| 90 | + |
| 91 | +## Important Files |
| 92 | +- `VERSION`: Contains current version number |
| 93 | +- `nextflow`: Launch wrapper script (updated by build process) |
| 94 | +- `.launch.classpath`: Development classpath (generated by `make compile`) |
| 95 | +- `build.gradle`: Root build configuration with multi-module setup |
| 96 | +- `settings.gradle`: Gradle project structure definition |
0 commit comments