DOCSEARCHbyAlgolia
Submit Docs

refreshVersions Documentation

repository·main·Indexed 23 days ago

https://github.com/splitties/refreshversions

A Gradle plugin designed to automate the management and updating of dependency versions. It features built-in dependency notations for Kotlin Multiplatform, Kotlin/JVM, and Android ecosystems, a migration tool (refreshVersionsMigrate), and support for versions.properties and Gradle Version Catalogs. The plugin allows for type-safe dependency accessors via buildSrcLibs and provides the versionFor() function for retrieving versions within Gradle scripts.

Tokens
25.9K
Snippets
30
Records
88
Agent score
81%

What's inside refreshVersions

  2. Correct order for Gradle Settings files

    main

    When configuring settings.gradle or settings.gradle.kts, you must follow a specific order to prevent build failures. The required sequence is:

    1. Imports: Any import statements.
    2. pluginManagement: The pluginManagement { ... } block (optional).
    3. buildscript: The buildscript { ... } block (used for setting up refreshVersions).
    4. plugins: The plugins { ... } block for applying settings plugins.
    5. Logic: General Gradle settings and project declarations (e.g., rootProject.name, include()).
    import com.example.something // Imports at the top, as usual.

pluginManagement {} // Optional

buildscript {
    // We will setup refreshVersions here, see below.
}

plugins {
    id("de.fayard.refreshVersions") version "0.10.0"
    // other plugins like the Gradle Entreprise plugin go end here
}

refreshVersions {
    // Optional configuration
}

// Then you can have other code after the blocks above,

rootProject.name = "My Project"
include(":app")

  3. Use refreshVersions with non-built-in dependency notations

    main

    refreshVersions can manage versions for any dependency notation as long as you use the version placeholder (_) instead of a hardcoded version number. This applies to:

    • JetBrains Package Search: Use the _ placeholder when adding dependencies via the plugin.
    • Gradle Versions Catalogs: In your gradle/libs.versions.toml file, use the _ placeholder for version values to keep them managed in versions.properties.
    • libraries.gradle pattern: In custom Groovy maps used for dependency centralization, replace version numbers with _.
    // libraries.gradle
ext.libraries = [
    spring_core: "org.springframework:spring-core:_",
    junit: "junit:junit:_"
]

  4. What are Built-in Dependency Notations

    main

    Built-in Dependency Notations are pre-defined maven coordinates for popular libraries provided by refreshVersions. Instead of manually typing full maven coordinates (e.g., com.google.android.play:billing:x.x.x), you can use a discoverable notation like Android.billingClient.

    How they work:

    1. You use the notation in your Gradle build files.
    2. After the first Gradle sync, the notation is automatically configured in your versions.properties file with the latest available version.
    3. This drastically reduces the time required to add popular libraries to your project.

    Each notation is internally represented as a Triple(KotlinName, MavenCoordinate, VersionKey).

  5. How refreshVersions manages dependencies

    main

    refreshVersions centralizes dependency versions in a versions.properties file (Java Properties format) instead of using Groovy or Kotlin code. This makes the version file machine-readable and easy to manipulate with tooling.

    The Opt-in Mechanism

    To allow refreshVersions to manage a dependency, you must use an underscore _ as a placeholder for the version in your build.gradle[.kts] files. This tells the plugin that the version is not hardcoded but is instead managed via the versions.properties file.

    Version Key Mapping

    By default, the plugin maps dependency notations to version keys. You can use a system of rules to group multiple artifacts under a single version key to keep your configuration DRY (Don't Repeat Yourself).

    Dependency notationVersion key example
    org.gradle:gradle-hello-world-plugin:_version.org.gradle..gradle-hello-world-plugin
    com.squareup.retrofit2:retrofit:_version.retrofit
    com.squareup.retrofit2:retrofit-adapter-xxx:_version.retrofit
    plugin with id com.squareup.sqldelightplugin.com.squareup.sqldelight

  6. Enable auto-completion for Groovy DSL users

    main

    If you use Groovy DSL (build.gradle files instead of .kts), dependency notation auto-completion will not work by default.

    Workaround: Configure the plugin in a buildSrc module to enable auto-completion support.

    // buildSrc/settings.gradle
pluginManagement {
    repositories {
        gradlePluginPortal()
    }
    plugins {
        id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}'
    }
}

plugins {
    id 'de.fayard.refreshVersions'
}

  7. Migrate Google Play Core to partitioned libraries

    main

    The Google Play Core library has been partitioned/split into multiple per-feature libraries. Instead of using the monolithic com.google.android.play:core or com.google.android.play:core-ktx, you must migrate to the specific Play Library required for your feature.

    Consult the official migration guide before updating: https://developer.android.com/guide/playcore#playcore-migration.

  8. Upgrade from buildSrcVersions to refreshVersions

    main

    If you are migrating from the buildSrcVersions plugin, follow these steps to avoid conflicts:

    1. Remove all buildSrcVersions configuration and the plugin declaration from your top-level build.gradle[.kts] file.
    2. Enable buildSrcLibs in your settings.gradle[.kts] or settings.gradle file using the refreshVersions block.
    // settings.gradle.kts
plugins {
    id("de.fayard.refreshVersions") version "{{version.refreshVersions}}"
}

refreshVersions {
    enableBuildSrcLibs() // <-- Add this
}

  10. Configure Gradle Build Scans

    main

    To gain detailed insights into your build process, you can use Gradle Build Scans. This requires configuring the com.gradle.enterprise plugin in your settings.gradle[.kts] file. If you are using the free version for open-source projects, you must explicitly accept the terms of service in the configuration block.

    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()
    }
}

  11. Update dependencies using refreshVersions

    main

    To update the dependencies managed by refreshVersions, follow these three steps:

    1. Run the Gradle task: Execute the refreshVersions task on your root project to look up available updates.
      ./gradlew refreshVersions
    2. Apply updates in versions.properties: Open the versions.properties file. Available updates will appear as comments next to your current versions. To upgrade, replace the existing version string with the version suggested in the comment. If you choose not to upgrade, you can leave the comments as a reminder of technical debt.
    3. Sync Gradle: After editing versions.properties, you must sync your project so the IDE recognizes the changes.
      • IntelliJ IDEA: Run "Reload all Gradle projects" or click the refresh arrows in the Gradle tool window.
      • Android Studio: Run "Sync Project with Gradle Files" or click the elephant + arrow icon in the toolbar.
    ./gradlew refreshVersions

  12. Add the refreshVersions plugin to a standard project

    main

    To add refreshVersions to a standard Gradle project, add the plugin to your settings.gradle.kts (Kotlin DSL) or settings.gradle (Groovy DSL) file.

    // settings.gradle.kts
plugins {
    id("de.fayard.refreshVersions") version "{{version.refreshVersions}}"
}