diff --git a/docs/add-dependencies.md b/docs/add-dependencies.md index 12de49d14..47ca6217b 100644 --- a/docs/add-dependencies.md +++ b/docs/add-dependencies.md @@ -118,9 +118,45 @@ refreshVersions will handle it. Below are some ways to deal with the dependency notations that are not built-in. -### Using gradle buildSrcLibs (WIP) +### Using buildSrcLibs -Yet another approach to managing dependencies is to use the **Gradle buildSrc** module, and to automatically generate a file `Libs.kt` that contains all the dependencies applied to your build: +The Gradle task `buildSrcLibs` can be used to automatically generate a `Libs.kt` file in the [buildSrc](https://docs.gradle.org/current/userguide/organizing_gradle_projects.html#sec:build_sources), that will contain all the dependency notations curently used in your build. + +To use it, you need to enable it: + +=== "settings.gradle.kts" + ```kotlin + plugins { + // See https://jmfayard.github.io/refreshVersions + id("de.fayard.refreshVersions") version "{{version.refreshVersions}}" + } + + refreshVersions { + enableBuildSrcLibs() // <-- Add this + } + ``` +=== "settings.gradle" + ```groovy + plugins { + // See https://jmfayard.github.io/refreshVersions + id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}' + } + + refreshVersions { + enableBuildSrcLibs() // <-- Add this + } + ``` + +Then you can use the command `./gradlew buildSrcLibs` to generate accessors for your dependencies + +```bash +$ ./gradlew buildSrcLibs +> Task :buildSrcLibs + new file: buildSrc/build.gradle.kts + new file: buildSrc/src/main/kotlin/Libs.kt +``` + +The generated file will look like this: === "buildSrc/src/main/kotlin/Libs.kt" ```kotlin @@ -136,9 +172,9 @@ object Libs { } ``` -Because this file used the placeholder version `_`, it is compatible with gradle refreshVersions! +Because this file uses the version placeholder (`_`), it is compatible with refreshVersions! -**This feature is not done yet. If you think we should prioritize it, please vote for [this issue]({{link.issues}}/235) with a 👍 and subscribe to it.** +Read more: [gradle buildSrcVersions]({{link.site}}/gradle-buildsrcversions). ### Using Package Search from JetBrains @@ -154,6 +190,30 @@ Can you use it with refreshVersions? Sure, just use the version placeholder (`_`). +### Using Gradle 7+ Versions Catalogs + +Gradle 7 comes with its own feature for centralizing dependencies: [Versions Catalogs](https://docs.gradle.org/7.0-rc-1/userguide/platforms.html#sub:central-declaration-of-dependencies). + +With Versions Catalog, you have a file like `gradle/libs.versions.toml` where you can centralize all your dependencies and benefit from typesafe accessors in your `build.gradle[.kts]` file. + +Since the feature is incubating, you need to enable it explicitly in the project's `settings.gradle[.kts]` file: +> `enableFeaturePreview("VERSION_CATALOGS")` + +Does that work well with refreshVersions? Yes, as long as you use the version placeholder (`_`). + +=== "gradle/libs.versions.toml" +``` +[libraries] +accompanist-coil = "com.google.accompanist:accompanist-coil:_" +accompanist-flowlayout = "com.google.accompanist:accompanist-flowlayout:_" +accompanist-insets = "com.google.accompanist:accompanist-insets:_" +... +``` + +In this configuration, the versions catalog centralizes the dependency notations, while refreshVersions takes care of setting and updating the versions. + +We have ideas to integrate Versions Catalogs deeper into refreshVersions, see [this issue](https://github.com/jmfayard/refreshVersions/issues/333). + ### Using the libraries.gradle pattern An older approach to centralize dependencies is to have a `libraries.gradle` file: diff --git a/docs/gradle-buildsrcversions.md b/docs/gradle-buildsrcversions.md index ff1eda4e0..82efcd4dc 100644 --- a/docs/gradle-buildsrcversions.md +++ b/docs/gradle-buildsrcversions.md @@ -39,7 +39,6 @@ What it did was to auto-generate the `buildSrc/.../{Libs,Versions}.kt` files abo ```bash $ ./gradlew buildSrcVersions -> Task :dependencyUpdates > Task :buildSrcVersions new file: buildSrc/build.gradle.kts new file: buildSrc/.gitignore diff --git a/docs/gradle-tips.md b/docs/gradle-tips.md new file mode 100644 index 000000000..d60ca6985 --- /dev/null +++ b/docs/gradle-tips.md @@ -0,0 +1,98 @@ +# Gradle tips and tricks + +More information to make your build great again! + +## Switch to the Kotlin DSL + +Groovy was there first in Gradle, but consider switching to Kotlin if you have not done so already. The cryptic error +messages will go away, and the IDE support is far superior. Hello auto-complete! + +**How Kotlin makes +editing your Gradle build less frustrating** + +## Consider using the Gradle build scan + +Given the range of information it gives you about your build, it's a no-brainer to use the build scan if you are working +an open-source project or have a Gradle Enterprise account. For a company project, understands the trade off of having +this information potentially shared by someone outside. + +It has to be configured in `settings.gradle[.kts]` + +```kotlin +// https://dev.to/jmfayard/the-one-gradle-trick-that-supersedes-all-the-others-5bpg +plugins { + id("com.gradle.enterprise").version(VERSION) +} + +gradleEnterprise { + buildScan { + // Accept the license agreement for com.gradle.build-scan plugin + termsOfServiceUrl = "https://gradle.com/terms-of-service" + termsOfServiceAgree = "yes" + publishOnFailure() + } +} +``` + +Find VERSION at https://plugins.gradle.org/plugin/com.gradle.enterprise + +[**Build scan - the one Gradle trick that supersedes all the others**](https://dev.to/jmfayard/the-one-gradle-trick-that-supersedes-all-the-others-5bpg) + +## Configure Gradle with gradle.properties + +You need to put some magic property with some magic value in gradle.properties, but which one? + +[**Configure Gradle with Gradle Properties**](https://dev.to/jmfayard/configuring-gradle-with-gradle-properties-211k) + +## Set-up GitHub Actions with Gradle + +A simple workflow to get you up and running with continuous integration. + +- copy-paste `.github/worrkflows/runOnGitHub.yml` +- create a Gradle task called `runOnGitHub` +- create a pull request, and you are good to go! + +[**How do I set up GitHub Actions for my Gradle or Android project?**](https://dev.to/jmfayard/how-do-i-setup-github-actions-for-my-gradle-or-android-project-3eal) + +More complex workflows can be found in the +repositories [refreshVersions](https://github.com/jmfayard/refreshVersions/tree/main/.github/workflows) +and [Splitties](https://github.com/LouisCAD/Splitties/tree/main/.github/workflows) + +## Gradle Settings + +A Gradle project has [a Settings file](https://docs.gradle.org/current/userguide/build_lifecycle.html#sec:settings_file) +called `settings.gradle` or `settings.gradle.kts` where you must respect a certain order (otherwise, the build breaks). + +The order is: + +1. imports, if any. +2. The `pluginManagement` block, if any. +3. The `buildscript` block, if any. (We will use it) +4. The `plugins` block, if any settings plugins are applied. +5. Logic for Gradle settings (any other code). + +See the example snippet below: + +```kotlin +import com.example.something // Imports at the top, as usual. + +pluginManagement {} // Optional + +buildscript { + // We will setup refreshVersions here, see below. +} + +plugins { // Optional + id("de.fayard.refreshVersions") version "0.10.0" + // other plugins like the Gradle Entreprise plugin go here +} + +refreshVersions { // Optional configuration + +} + +// Then you can have other code after the blocks above, + +rootProject.name = "My Project" // Optional, defaults to parent dir's name. +include(":app") // If the project has modules/subprojects to declare. +``` diff --git a/docs/setup.md b/docs/setup.md index 3794e6e47..c042cbda5 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -51,14 +51,26 @@ If you use the **buildSrc** module and have dependencies declared in the `buildS === "buildSrc/settings.gradle.kts" ```kotlin + pluginManagement { + plugins { + id("de.fayard.refreshVersions") version "{{version.refreshVersions}}" + } + } + plugins { - id("de.fayard.refreshVersions") version "{{version.refreshVersions}}" + id("de.fayard.refreshVersions") } ``` === "buildSrc/settings.gradle" ```groovy + pluginManagement { + plugins { + id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}' + } + } + plugins { - id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}' + id 'de.fayard.refreshVersions' } ``` @@ -69,11 +81,17 @@ If you use the **buildSrc** module and have dependencies declared in the `buildS A workaround is to configure the plugin in the `buildSrc` module (create the directory if it doesn't exist yet): === "buildSrc/settings.gradle" -```groovy -plugins { - id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}' -} -``` + ```groovy + pluginManagement { + plugins { + id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}' + } + } + + plugins { + id 'de.fayard.refreshVersions' + } + ``` ### If you have a composite/included build @@ -82,9 +100,35 @@ Sharing used versions with included builds is not supported at the moment. If you need/want this feature, please vote with a 👍 on [this issue]({{link.issues}}/205), subscribe to it, and tell us about your use case, to help us prioritize. -### If you want to use a development version +### If you want to use a snapshot version + +=== "settings.gradle.kts" + ```kotlin + pluginManagement { + repositories { + gradlePluginPortal() + maven("https://s01.oss.sonatype.org/content/repositories/snapshots") + } + } + plugins { + // See https://jmfayard.github.io/refreshVersions + id("de.fayard.refreshVersions") version "{{version.snapshot}}" + } + ``` +=== "settings.gradle" + ```groovy + pluginManagement { + repositories { + gradlePluginPortal() + maven { url 'https://s01.oss.sonatype.org/content/repositories/snapshots' } + } + } + plugins { + // See https://jmfayard.github.io/refreshVersions + id 'de.fayard.refreshVersions' version '{{version.snapshot}}' + } + ``` -Follow [issue 340: Continuous Deployment]({{link.issues}}/340) ## Configure the plugin @@ -96,74 +140,9 @@ If you are curious about what are the available options, you can use auto-comple - ## Earlier versions - - ### If you are upgrading from the buildSrcVersions plugin Before refreshVersions, [there was the plugin buildSrcVersions](https://dev.to/jmfayard/better-dependency-management-in-android-studio-3-5-with-gradle-buildsrcversions-34e9). diff --git a/mkdocs.yml b/mkdocs.yml index 6de22611d..fc5c9aa4a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -22,6 +22,7 @@ extra: version: gradle: 6.9 refreshVersions: '0.10.0' + snapshot: '0.10.1-SNAPSHOT' keyboard_shortcuts: find_actions: ctrl/cmd + shift + A @@ -74,6 +75,7 @@ nav: - 'Dev environment': contributing/submitting-prs/dev-env.md - 'Development process': contributing/submitting-prs/dev-process.md - 'Dependency notations': contributing/submitting-prs/dependency-notations-updates.md + - 'Bonus: Gradle tips and tricks': gradle-tips.md plugins: - search