diff --git a/README.md b/README.md index bef30db7..e557f3cc 100644 --- a/README.md +++ b/README.md @@ -64,8 +64,26 @@ then run the generator ```sh # dart dart pub run build_runner build + +# for watch mode (recommended during development) +dart pub run build_runner watch +``` + +#### Lean Builder Support (Experimental) + +Retrofit now has experimental support for [lean_builder](https://pub.dev/packages/lean_builder), a faster build system for Dart. While lean_builder support is still under development, the infrastructure has been added for future use. + +**Important**: lean_builder is an **optional** dependency and is NOT required to use retrofit_generator. It's only needed if you want to try the experimental lean_builder support. + +To prepare for lean_builder support, add it to your `dev_dependencies`: + +```yaml +dev_dependencies: + lean_builder: ^0.1.2 # Optional - only if you want to use lean_builder ``` +**Note:** For now, please continue using `build_runner` as shown above. Full lean_builder integration will be available in a future release once lean_builder reaches stability. + ### Use it ```dart diff --git a/example/LEAN_BUILDER.md b/example/LEAN_BUILDER.md new file mode 100644 index 00000000..9c5d9f48 --- /dev/null +++ b/example/LEAN_BUILDER.md @@ -0,0 +1,106 @@ +# Lean Builder Support (Experimental) + +This document provides information about using lean_builder with retrofit_generator. + +## Status + +⚠️ **Experimental** - Lean Builder support is currently under development and not yet recommended for production use. + +## What is Lean Builder? + +[Lean Builder](https://pub.dev/packages/lean_builder) is a streamlined Dart build system that offers: +- Fast incremental builds (often under 1 second) +- Parallel processing for maximum efficiency +- Watch mode with hot reload support +- Simple, declarative builder configuration + +## Current Implementation + +The infrastructure for lean_builder support has been added to retrofit_generator, but the full implementation is pending until: +1. Lean Builder reaches a stable release (currently at v0.1.2) +2. The retrofit_generator codebase is fully adapted to lean_builder's API + +## Using build_runner (Recommended) + +For now, please continue using build_runner for code generation: + +```bash +# One-time build +dart pub run build_runner build + +# Watch mode (recommended during development) +dart pub run build_runner watch --delete-conflicting-outputs +``` + +## Future Usage (When Available) + +Once lean_builder support is fully implemented, you'll be able to use: + +```bash +# One-time build +dart run lean_builder build + +# Watch mode with hot reload +dart run lean_builder watch --dev +``` + +## Configuration + +### pubspec.yaml + +**Important**: lean_builder is an **optional** dependency. It is NOT included in retrofit_generator by default. + +When lean_builder support is ready, your `pubspec.yaml` will include: + +```yaml +dependencies: + retrofit: ^4.6.0 + dio: ^5.0.0 + json_annotation: ^4.9.0 + retrofit_generator: ^10.0.0 # For use in codegen folder + +dev_dependencies: + lean_builder: ^0.1.2 # Optional - only if you want to use lean_builder + json_serializable: ^6.10.0 +``` + +Note: retrofit_generator does not depend on lean_builder, so you won't be forced to install it unless you explicitly want to use lean_builder support. + +### build.yaml (Optional) + +You can keep your existing `build.yaml` configuration. Lean Builder will respect these settings when support is fully implemented: + +```yaml +targets: + $default: + builders: + retrofit_generator: + options: + auto_cast_response: true +``` + +## Migration Path + +When lean_builder support becomes stable: + +1. **No code changes required** - Your @RestApi annotations and API definitions remain the same +2. **Update dependencies** - Add lean_builder to dev_dependencies +3. **Switch build command** - Use `dart run lean_builder build` instead of `build_runner` +4. **Enjoy faster builds** - Experience significantly faster incremental builds + +## Contributing + +If you're interested in helping complete the lean_builder integration, please: +1. Check the [retrofit.dart GitHub repository](https://github.com/trevorwang/retrofit.dart) +2. Review the [lean_builder documentation](https://pub.dev/packages/lean_builder) +3. Submit a pull request or open an issue with your ideas + +## Support + +For questions or issues: +- **retrofit.dart**: https://github.com/trevorwang/retrofit.dart/issues +- **lean_builder**: https://github.com/Milad-Akarie/lean_builder/issues + +## Timeline + +Follow the retrofit.dart repository for updates on when lean_builder support will be fully available. The maintainers are monitoring lean_builder's development and will complete the integration when appropriate. diff --git a/generator/CHANGELOG.md b/generator/CHANGELOG.md index 0eb95ed7..02adf6c0 100644 --- a/generator/CHANGELOG.md +++ b/generator/CHANGELOG.md @@ -1,3 +1,11 @@ +## 10.0.8 (Unreleased) + +- Add experimental lean_builder support infrastructure +- Add `lib/lean_builder.dart` entry point for lean_builder users +- Add comprehensive documentation for lean_builder support +- Note: lean_builder is now an **optional** dependency - it's not required unless you want to use lean_builder +- Note: Full lean_builder implementation is pending until lean_builder reaches stability + ## 10.0.6 - Update `protobuf` to 5.0.0 diff --git a/generator/analysis_options.yaml b/generator/analysis_options.yaml index 01174176..82d058c0 100644 --- a/generator/analysis_options.yaml +++ b/generator/analysis_options.yaml @@ -1,3 +1,9 @@ include: package:lints/recommended.yaml formatter: page_width: 80 +analyzer: + exclude: + # Exclude lean_builder support files as lean_builder is an optional dependency + # These files are only used when users explicitly add lean_builder to their project + - lib/lean_builder.dart + - lib/src/lean_generator.dart diff --git a/generator/lib/lean_builder.dart b/generator/lib/lean_builder.dart new file mode 100644 index 00000000..8ddcb490 --- /dev/null +++ b/generator/lib/lean_builder.dart @@ -0,0 +1,66 @@ +/// Lean Builder entry point for Retrofit code generator. +/// +/// **⚠️ Experimental Feature ⚠️** +/// +/// This file provides experimental lean_builder support for retrofit_generator. +/// Lean Builder support is currently under development and not yet recommended +/// for production use. +/// +/// ## Important: Optional Dependency +/// +/// This library is **NOT** included in retrofit_generator's dependencies. +/// To use lean_builder support, you must add it to your own project: +/// +/// ```yaml +/// dependencies: +/// retrofit_generator: +/// +/// dev_dependencies: +/// lean_builder: ^0.1.2 +/// ``` +/// +/// Then, in your codegen folder (or where you define generators), import: +/// ```dart +/// import 'package:retrofit_generator/lean_builder.dart'; +/// ``` +/// +/// ## Current Status +/// +/// While the infrastructure for lean_builder support has been added, the +/// retrofit_generator package is currently optimized for build_runner. Full +/// lean_builder integration is planned for future releases once lean_builder +/// reaches a stable version. +/// +/// ## Usage (Experimental) +/// +/// 1. Add both packages to your pubspec.yaml: +/// ```yaml +/// dependencies: +/// retrofit_generator: +/// +/// dev_dependencies: +/// lean_builder: ^0.1.2 +/// ``` +/// +/// 2. For now, please continue using build_runner: +/// ```bash +/// dart pub run build_runner build +/// # or for watch mode: +/// dart pub run build_runner watch +/// ``` +/// +/// ## Future Plans +/// +/// Once lean_builder reaches stability and this integration is complete, you'll +/// be able to use: +/// ```bash +/// dart run lean_builder build +/// # or for watch mode with hot reload: +/// dart run lean_builder watch --dev +/// ``` +/// +/// For updates on lean_builder support, visit: +/// https://github.com/trevorwang/retrofit.dart +library; + +export 'package:retrofit_generator/src/lean_generator.dart'; diff --git a/generator/lib/src/lean_generator.dart b/generator/lib/src/lean_generator.dart new file mode 100644 index 00000000..b9999a78 --- /dev/null +++ b/generator/lib/src/lean_generator.dart @@ -0,0 +1,46 @@ +import 'dart:async'; + +import 'package:lean_builder/builder.dart'; +import 'package:lean_builder/element.dart'; +import 'package:retrofit/retrofit.dart' as retrofit; + +/// Lean Builder generator for Retrofit. +/// +/// This generator provides lean_builder support for retrofit_generator, +/// allowing faster incremental builds with lean_builder. +/// +/// Note: This is an experimental feature. For production use, we recommend +/// using the traditional build_runner approach until lean_builder support +/// is fully stable. +/// +/// This generator is automatically discovered by lean_builder through the +/// @LeanGenerator.shared() annotation, which marks it as a shared part builder +/// (similar to build_runner's shared part builders). +@LeanGenerator.shared() +class RetrofitLeanGenerator extends GeneratorForAnnotatedClass { + RetrofitLeanGenerator(); + + @override + FutureOr generateForClass( + BuildStep buildStep, + ClassElement classElement, + ElementAnnotation annotation, + ) async { + // The retrofit generator is currently optimized for build_runner/source_gen. + // Full lean_builder support requires adapting the codebase to use lean_builder's + // analyzer abstractions instead of source_gen's API. + // + // For now, this serves as a placeholder for future lean_builder support. + // Users should continue using build_runner for code generation: + // dart pub run build_runner build + + throw UnsupportedError( + 'Lean Builder support for retrofit_generator is not yet fully implemented.\n' + 'The retrofit_generator package currently works with build_runner.\n\n' + 'To generate code, please use:\n' + ' dart pub run build_runner build\n\n' + 'For more information, see: https://github.com/trevorwang/retrofit.dart\n\n' + 'Lean Builder support is planned for a future release once lean_builder reaches stable.', + ); + } +}