mirror of
https://github.com/KRTirtho/spotube.git
synced 2026-08-05 19:59:51 +00:00
110 lines
3.7 KiB
Markdown
110 lines
3.7 KiB
Markdown
# Gradle Build Logic Best Practices
|
|
|
|
**IMPORTANT**: This document provides a high-level snapshot of common best practices. However, Gradle is a rapidly evolving tool. **You MUST use the `gradle_docs` tool to retrieve the most up-to-date and comprehensive best practices
|
|
directly from the official documentation.**
|
|
|
|
## 1. Authoritative Research Workflow
|
|
|
|
Before implementing significant build logic, always perform a search for the latest recommendations using scoped queries and project context.
|
|
|
|
### Example: Getting an Index of Best Practices
|
|
|
|
To find the authoritative index of best practices within the User Guide, first explore the `userguide/` directory to identify the correct files.
|
|
|
|
Tool: `gradle_docs`
|
|
|
|
```json
|
|
{
|
|
"path": "userguide/",
|
|
"projectRoot": "/absolute/path/to/project"
|
|
}
|
|
```
|
|
|
|
**Reasoning**: This call lists the contents of the `userguide` directory. Look for files starting with `best_practices` (e.g., `best_practices.md`, `best_practices_dependency_management.md`). Once identified, read the main index:
|
|
|
|
Tool: `gradle_docs`
|
|
|
|
```json
|
|
{
|
|
"path": "userguide/best_practices.md",
|
|
"projectRoot": "/absolute/path/to/project"
|
|
}
|
|
```
|
|
|
|
### Example: Searching for Best Practices
|
|
|
|
Tool: `gradle_docs`
|
|
|
|
```json
|
|
{
|
|
"query": "tag:best-practices dependency management",
|
|
"projectRoot": "/absolute/path/to/project"
|
|
}
|
|
```
|
|
|
|
**Reasoning**: Using the authoritative `best-practices` tag ensures the returned content is filtered for high-signal architectural recommendations.
|
|
|
|
### Example: Searching for Specific Guidance
|
|
|
|
Tool: `gradle_docs`
|
|
|
|
```json
|
|
{
|
|
"query": "tag:userguide performance best practices",
|
|
"projectRoot": "/absolute/path/to/project"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Engine-Level Discovery (The "Source of Truth")
|
|
|
|
To understand the core architectural principles behind best practices, you can explore Gradle's own source documentation.
|
|
|
|
### Example: Listing Core Concepts and Documentation
|
|
|
|
Use `gradle_docs` with `path="."` to explore the root documentation tree.
|
|
|
|
Tool: `gradle_docs`
|
|
|
|
```json
|
|
{
|
|
"path": ".",
|
|
"projectRoot": "/absolute/path/to/project"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. High-Level Snapshot (Current Guidelines)
|
|
|
|
The following sections summarize established idiomatic patterns. Use these as a starting point, but verify against the official docs.
|
|
|
|
### Kotlin DSL Idiomatic Patterns
|
|
|
|
- **Use Type-Safe Accessors**: Prefer `tasks.test { ... }` or `tasks.named<Test>("test") { ... }` over `tasks.getByName("test")`.
|
|
- **Prefer `register` over `create` (Lazy APIs)**: Use `tasks.register<MyTask>("myTask")` to avoid eager task configuration.
|
|
- **Use Lazy Properties**: Employ the `Property<T>` and `Provider<T>` APIs for late binding and better configuration cache compatibility.
|
|
|
|
### Performance & Configuration Cache
|
|
|
|
- **Enable Configuration Cache**: Ensure build logic avoids accessing the `Project` object inside task actions.
|
|
- **Use Specific Annotations**: Properly label task properties with `@Input`, `@OutputFiles`, `@Internal`, etc.
|
|
- **Minimize Logic in Build Scripts**: Move complex logic into convention plugins or `buildSrc`.
|
|
|
|
### Dependency Management
|
|
|
|
- **Use Version Catalogs**: Centralize dependencies in `gradle/libs.versions.toml`.
|
|
- **Avoid `allprojects` and `subprojects`**: These blocks create tight coupling; use convention plugins and apply them selectively instead.
|
|
|
|
### Project Integrity
|
|
|
|
- **Reproducible Builds**: Use fixed versions and commit the Gradle wrapper.
|
|
- **Surgical Updates**: Only update what is necessary and verify with `check`.
|
|
|
|
## Resources (Official Source of Truth)
|
|
|
|
- [Official Gradle Best Practices](https://docs.gradle.org/current/userguide/best_practices.html)
|
|
- [Gradle Performance Guide](https://docs.gradle.org/current/userguide/performance.html)
|
|
- [Kotlin DSL Primer](https://docs.gradle.org/current/userguide/kotlin_dsl.html)
|