{"id":20492616,"url":"https://github.com/redmadrobot/gradle-version-catalogs","last_synced_at":"2025-04-05T18:06:32.776Z","repository":{"id":40628873,"uuid":"431836858","full_name":"RedMadRobot/gradle-version-catalogs","owner":"RedMadRobot","description":"Version catalogs used in red_mad_robot Android team","archived":false,"fork":false,"pushed_at":"2025-03-26T22:41:49.000Z","size":1035,"stargazers_count":112,"open_issues_count":20,"forks_count":13,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-29T09:42:02.108Z","etag":null,"topics":["androidx","gradle-version-catalog","version-catalog"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RedMadRobot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG-2022.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-25T12:26:53.000Z","updated_at":"2025-03-25T23:55:35.000Z","dependencies_parsed_at":"2024-03-07T16:44:20.263Z","dependency_job_id":"f17c28b6-0b4a-45d6-8bf1-fafb91f7f1d3","html_url":"https://github.com/RedMadRobot/gradle-version-catalogs","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RedMadRobot%2Fgradle-version-catalogs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RedMadRobot%2Fgradle-version-catalogs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RedMadRobot%2Fgradle-version-catalogs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RedMadRobot%2Fgradle-version-catalogs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RedMadRobot","download_url":"https://codeload.github.com/RedMadRobot/gradle-version-catalogs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378140,"owners_count":20929296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["androidx","gradle-version-catalog","version-catalog"],"created_at":"2024-11-15T17:29:50.224Z","updated_at":"2025-04-05T18:06:32.759Z","avatar_url":"https://github.com/RedMadRobot.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# red_mad_robot Version Catalogs\n[![Version](https://img.shields.io/maven-central/v/com.redmadrobot.versions/versions-redmadrobot?style=flat-square)][mavenCentral]\n\n[Shared catalogs](https://docs.gradle.org/current/userguide/platforms.html#sec:sharing-catalogs) used in red_mad_robot android team.\nGradle 7.4+ is required.\n\n---\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Catalogs](#catalogs)\n  - [Motivation](#motivation)\n- [Usage](#usage)\n  - [Where can I find the version of a dependency?](#where-can-i-find-the-version-of-a-dependency)\n  - [How can I change a dependency version?](#how-can-i-change-a-dependency-version)\n  - [How can I add a dependency to the catalog?](#how-can-i-add-a-dependency-to-the-catalog)\n  - [How can I make a bundle of dependencies?](#how-can-i-make-a-bundle-of-dependencies)\n- [Catalogs Principles](#catalogs-principles)\n  - [Update Policy](#update-policy)\n  - [Naming and Structure](#naming-and-structure)\n- [Troubleshooting](#troubleshooting)\n  - [Unable to apply the plugin because the extension is already registered](#unable-to-apply-the-plugin-because-the-extension-is-already-registered)\n  - [Unable to apply a plugin from the version catalog due to a version conflict to the classpath](#unable-to-apply-a-plugin-from-the-version-catalog-due-to-a-version-conflict-to-the-classpath)\n  - [DSL_SCOPE_VIOLATION can't be called in this context by implicit receiver](#dsl_scope_violation-cant-be-called-in-this-context-by-implicit-receiver)\n  - [Invalid TOML catalog definition](#invalid-toml-catalog-definition)\n- [Additional resources](#additional-resources)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Catalogs\n\nThere are two groups of catalogs.\nThe first group is **catalogs containing libraries from the same group**.\nThey are not specific to red_mad_robot, so feel free to use them.\n\n- [redmadrobot][versions-redmadrobot] - contains [red_mad_robot libraries](https://github.com/RedMadRobot)\n- [androidx][versions-androidx] - contains [AndroidX libraries](https://developer.android.com/jetpack/androidx/versions)\n\nThe second group is **internal catalogs**.\nUse them only if you are red_mad_robot team member.\n\n- [stack][versions-stack] - contains libraries according to tech stack used in red_mad_robot android team\n\n### Motivation\n\nWhy to prefer version catalogs over the declaring dependencies via `buildSrc`?\n\n- If you have multiple projects\n  - **and** you want to share the same set of dependencies (considered as your tech stack) between multiple projects.\n    It also allows you to start new projects quickly.\n  - **and** you want to reduce effort on dependencies updating, and update them in one place.\n    So, you have to ensure all dependencies are compatible to each other only once.\n- If you want to share dependencies between project and `buildSrc` or [composite builds][docs-composite-builds].\n- If you don't want to trigger recompilation of all build scripts when the only thing you did was change a dependency version.\n- If you want to [create bundles](#how-can-i-make-a-bundle-of-dependencies) for dependencies frequently used together.\n\n\u003e [!TIP]\n\u003e\n\u003e If you use the catalogs from this repository, you can look at the [changelog] containing links to release notes for each updated dependency.\n\u003e Updates requiring your attention are marked with :warning:.\n\nBefore switching to version catalogs, take into account the following drawbacks:\n\n- Version catalogs are not quite popular yet, so you need to guide your team on how to use and modify catalogs.\n  [\"Usage\"](#usage) section of this guide is a good starting point.\n- If you use external version catalogs, it may be harder to update catalogs if you skip several updates.\n  There is a cumulative effect.\n  The more updated dependencies require the more effort on update to honor all breaking changes.\n  Although this problem exists even if you don't use version catalogs, it is simpler to handle when you update dependencies one-by-one without catalog.\n- If version catalogs are shared between multiple projects, they should be continuously maintained to keep them up-to-date and to not block consumers from updating dependencies (see [\"Catalogs Principles\"](#catalogs-principles)).\n\n## Usage\n\n\u003e [!NOTE]\n\u003e\n\u003e Read more about version catalogs sharing in the [official documentation][docs-importing].\n\nTo add published catalogs to your project, declare it in `settings.gradle.kts`:\n\n```kotlin\ndependencyResolutionManagement {\n    repositories {\n        mavenCentral()\n    }\n\n    versionCatalogs {\n        val version = \"2025.03.10\"\n        create(\"rmr\") {\n            from(\"com.redmadrobot.versions:versions-redmadrobot:$version\")\n        }\n        create(\"androidx\") {\n            from(\"com.redmadrobot.versions:versions-androidx:$version\")\n        }\n        create(\"stack\") {\n            from(\"com.redmadrobot.versions:versions-stack:$version\")\n        }\n    }\n}\n```\n\n\u003e [!WARNING]\n\u003e\n\u003e Be careful with version catalogs naming.\\\n\u003e Make sure selected name doesn't conflict with any of Gradle plugins' extensions, otherwise your project will not sync.\n\u003e For example, if you have [gradle-infrastructure](https://github.com/RedMadRobot/gradle-infrastructure) plugin, you cannot create version catalog named `redmadrobot` because gradle-infrastructure contains an extension named `redmadrobot`.\n\u003e Moreover you should not name the published version catalog as `libs` if you want to be able to use the local version catalog, or you must rename the local version catalog.\n\nGradle generates accessors for dependencies according to the declared catalogs after the project sync:\n\n```kotlin\nplugins {\n    alias(rmr.plugins.application)\n    alias(androidx.plugins.navigation.safeargs.kotlin)\n}\n\ndependencies {\n    implementation(androidx.core)\n    implementation(androidx.fragment)\n\n    implementation(rmr.ktx.fragment)\n\n    implementation(stack.dagger)\n}\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e Here are listed only most common catalogs use cases.\n\u003e If you want to know more about version catalogs usage, please read the [official documentation][docs].\n\n### Where can I find the version of a dependency?\n\nVersions of dependencies declared in version catalogs are known only on dependency resolution step.\nSo, the best way to know what version of dependency is used in your project is to use Gradle dependencies report:\n\n```shell\n# To show all dependencies in releaseRuntimeClasspath configuration\n./gradlew -q :app:dependencies --configuration releaseRuntimeClasspath\n# or to show information about specific dependency\n./gradlew -q :app:dependencyInsight --configuration releaseRuntimeClasspath --dependency com.google.dagger:dagger\n```\n\nAnother way is to look at catalogs sources and find the version there.\nYou can find link to the catalogs sources in section [Catalogs](#catalogs).\nIf you go this way, make sure you've selected repository revision corresponding to the version used in your project.\n\n### How can I change a dependency version?\n\nEach dependency [has a corresponding version alias](#versions).\nYou can change the value associated with the version alias and replace it with the needed value.\nHere is an example of how you can change the Kotlin version.\nNote that you should also change all versions based on the changed version.\n\n```kotlin\n// settings.gradle.kts\ndependencyResolutionManagement {\n  //...\n\n  versionCatalogs {\n    create(\"stack\") {\n      from(\"com.redmadrobot.versions:versions-stack:[...]\")\n\n      version(\"kotlin\", \"1.9.22\")\n      version(\"ksp\", \"1.9.22-1.0.17\")\n    }\n\n    create(\"androidx\") {\n      from(\"com.redmadrobot.versions:versions-androidx:[...]\")\n\n      version(\"compose-compiler\", \"1.5.8\")\n    }\n  }\n}\n```\n\n### How can I add a dependency to the catalog?\n\nIf you want to share the added dependency with all projects using the catalogs, fell free to [file an issue][issue].\nIn the case you need the dependence only in your project, you can add it locally to the catalog.\nIt is encouraged to [follow catalog structure](#naming-and-structure).\n\n```kotlin\n// settings.gradle.kts\ndependencyResolutionManagement {\n  versionCatalogs {\n    create(\"androidx\") {\n      from(\"com.redmadrobot.versions:versions-androidx:[...]\")\n\n      library(\"games-activity\", \"androidx.games:games-activity:2.0.2\")\n      library(\"games-controller\", \"androidx.games:games-controller:2.0.1\")\n    }\n  }\n}\n```\n\n### How can I make a bundle of dependencies?\n\nSimilarly to the [dependencies](#how-can-i-add-a-dependency-to-the-catalog), you can add bundles to the catalogs.\nCatalogs doesn't contain any bundles by default, so feel free to add your own.\n\n```kotlin\n// settings.gradle.kts\ndependencyResolutionManagement {\n  versionCatalogs {\n    create(\"androidx\") {\n      from(\"com.redmadrobot.versions:versions-androidx:[...]\")\n\n      bundle(\"compose\", listOf(\"compose-animation\", \"compose-material3\", \"compose-foundation\", \"compose-ui\"))\n    }\n  }\n}\n```\n\n## Catalogs Principles\n\nThe catalogs published here must be:\n\n- **Foolproof**: catalogs shouldn't contain invalid dependencies.\n  Dependencies published in the same version of catalog must be compatible with each other.\n  Dependencies should have predictable aliases\n- **Up-to-date**: dependencies must be updated within one month since release.\n  It must be possible to change dependencies' versions without modifying the catalog's source code\n- **Transparent**: catalogs mustn't hide important changes in dependencies from developers.\n  Everyone who wants to update catalogs in a project should see what dependencies were changed and what important changes these updates include\n\n### Update Policy\n\nTo not block projects using these catalogs from updating to the latest versions, the catalogs should be updated regularly, every two weeks.\nUsually, this period of time is enough to gather libraries compatible with each other.\n\nGenerally, catalogs should include only stable versions of libraries, with some exclusions:\n\n- It is allowed to use RC version of a dependency if it contains a fix for a major issue or brings compatibility with other dependencies\n- It is allowed to use RC, beta, alpha, etc. if the dependency has no stable version yet.\n\nRelease notes should contain all the information needed for an update to the new version of catalogs:\n\n- List of added, changed, or removed dependencies\n- Link to the changelog for each dependency\n- Links to additional information about the update if it is helpful (e.g., what's new article, migration guide, etc.)\n- Updates containing changes requiring the developer's attention should be marked with :warning: sign\n\n\u003e **Symbols Used in Catalogs Release Notes:** \\\n\u003e :sparkle: - Added dependency \\\n\u003e :arrow_up: - Updated dependency \\\n\u003e :x: - Removed dependency \\\n\u003e :memo: - Dependency or version name changed \\\n\u003e :warning: - Attention required. Update may contain breaking changes or behaviour changes.\n\n### Naming and Structure\n\n#### Libraries\n\nGenerally, alias of each library must follow Maven coordinates to make it simple to guess the alias without looking at the catalog's source code.\n\nTo make accessors' hierarchy shorter, large groups of dependencies (for example, androidx) should be moved to the own catalog.\nThe name of the catalog should be equal to common part of group.\n\n\u003e **Example:**\\\n\u003e `com.redmadrobot:flipper` → `redmadrobot` (catalog) + `flipper` (alias) = `redmadrobot.flipper` (accessor)\n\nIn catalogs containing libraries from different groups (like [stack catalog][versions-stack] or local project catalog) it is allowed to omit library group fully or partially if the library name is pretty unique to be used without group.\n\n\u003e **Examples:**\n\u003e\n\u003e - :white_check_mark: `com.jakewharton.timber:timber` → `timber`\n\u003e - :white_check_mark: `com.google.dagger:dagger` → `dagger`\n\u003e - :white_check_mark: `com.airbnb.android:lottie` → `lottie`\n\u003e - :x: `org.jetbrains.kotlinx:kotlinx-serialization-core`  `serializtion-core`\n\u003e - :x: `javax.inject:javax.inject` → `inject`\n\nA module name might be dropped if it duplicates group name, so in the case library name included both in group and in module name, it should be included only once to the alias.\nIt is allowed to use `camelCase` when module name contains more than one word, but hierarchical structure doesn't make sense for this alias.\n\n\u003e **Examples:**\n\u003e\n\u003e - :white_check_mark: `com.google.devtools.ksp:symbol-processing` → `ksp` (KSP abbreviation already includes \"symbol processing\")\n\u003e - :white_check_mark: `io.gitlab.arturbosch.detekt:detekt-gradle-plugin` → `detekt-gradlePlugin`\n\u003e - :white_check_mark: `io.reactivex.rxjava3:rxjava` → `rxjava3` (alias `rxjava` is also acceptable in the case the catalog doesn't contain `rxjava2`)\n\u003e - :white_check_mark: `androidx.coordinatorlayout:coordinatorlayout` → `coordinatorlayout`\n\u003e - :x: `androidx.coordinatorlayout:coordinatorlayout` → `coordinatorLayout`\n\u003e - :x: `androidx.coordinatorlayout:coordinatorlayout` → `coordinator-layout`\n\nThere are a few cases when it is not possible or not recommended to follow library Maven coordinates:\n\n1. If the library name or group contains words reserved by Gradle (e.g., `extensions`):\n   \u003e **Example:**\n   \u003e\n   \u003e - :x: `com.redmadrobot.extensions:core-ktx` → `extensions-coreKtx` (`extensions` is reserved for Gradle extensions)\n   \u003e - :white_check_mark: `com.redmadrobot.extensions:core-ktx` → `ktx-core`\n2. If the library's hierarchy makes autocompletion useless:\n   \u003e :x: **Bad hierarchy**\n   \u003e\n   \u003e - `org.jetbrains.dokka:dokka-gradle-plugin` → `dokka-gradlePlugin`\n   \u003e - `org.jetbrains.dokka:javadoc-plugin` → `dokka-javadocPlugin`\n   \u003e - `org.jetbrains.dokka:android-documentation-plugin` → `dokka-androidDocumentationPlugin`\n\n   \u003e :white_check_mark: **Good hierarchy**\n   \u003e\n   \u003e - `org.jetbrains.dokka:dokka-gradle-plugin` → `dokka-gradlePlugin` (this one stays the same to separate gradle plugin from dokka plugins)\n   \u003e - `org.jetbrains.dokka:javadoc-plugin` → `dokka-plugin-javadoc`\n   \u003e - `org.jetbrains.dokka:android-documentation-plugin` → `dokka-plugin-androidDocumentation`\n   \u003e\n   \u003e After this change we can list all available dokka plugins using autocompletion.\n\n#### Versions\n\nEach library must have a version alias to make it possible to override the version from a project.\nA version alias should be the same as the corresponding library alias.\nIf more than one library uses the same version alias, its name should be equal to the main dependency's alias.\n\n#### Plugins\n\nPlugin alias should follow the plugin ID.\nPlugin artifact should also be declared in `[libraries]` section to make it possible to use it from buildSrc or composite builds.\n\n## Troubleshooting\n\n\u003e [!NOTE]\n\u003e\n\u003e You can find Troubleshooting guide in the [official documentation][docs-problems].\n\n### Unable to apply the plugin because the extension is already registered\n\n```\nCaused by: java.lang.IllegalArgumentException: Cannot add extension with name, as there is an extension already registered with that name\n```\n\nProbably, you named a version catalog as one of the Gradle plugin extensions.\nPlease, read the warning in [Usage](#usage) section.\n\n### Unable to apply a plugin from the version catalog due to a version conflict to the classpath\n\n```\nCaused by: org.gradle.plugin.management.internal.InvalidPluginRequestException: Plugin request for plugin already on the classpath must not include a version\n```\n\nThis exception can occur if the plugin has already been applied in the root **build.gradle**, or has a notation in the **buildscripts** section, or has a notation in the **plugins** section of the **settings.gradle** file.\nYou can leave the plugin notation only in the modules you need, because `alias` applies the plugin version from the version catalog file.\nIf this is not possible, you can use the `id` extension instead of `alias` and get only **pluginId** from the accessor.\n\n```kotlin\nplugins {\n  id(rmr.plugins.detekt.get().pluginId)\n}\n```\n\n### DSL_SCOPE_VIOLATION can't be called in this context by implicit receiver\n\nThis is an [issue](https://github.com/gradle/gradle/issues/22797) in Gradle, and it was fixed in Gradle 8.1.\nIn case you use older Gradle version, you can suppress it with `@Suppress(\"DSL_SCOPE_VIOLATION\")`.\n\n### Invalid TOML catalog definition\n\nCheck your Gradle wrapper version. The current catalog based on Gradle 7.2.\n\n## Additional resources\n\nFor more information about version catalogs, consult the following resources.\n\n- [Docs: Sharing dependency versions between projects][docs]\n- [Docs: Troubleshooting version catalog problems][docs-problems]\n- [Cédric Champeau's blog](https://melix.github.io/blog/tags/catalog.html) - articles about version catalogs from engineer working at Gradle who worked on version catalogs\n\n[versions-redmadrobot]: versions-redmadrobot/libs.versions.toml\n[versions-androidx]: versions-androidx/libs.versions.toml\n[versions-stack]: versions-stack/libs.versions.toml\n[changelog]: CHANGELOG.md\n[issue]: https://github.com/RedMadRobot/gradle-version-catalogs/issues/new\n\n[docs]: https://docs.gradle.org/current/userguide/platforms.html\n[docs-importing]: https://docs.gradle.org/current/userguide/platforms.html#sec:importing-published-catalog\n[docs-problems]: https://docs.gradle.org/current/userguide/version_catalog_problems.html\n[docs-composite-builds]: https://docs.gradle.org/current/userguide/composite_builds.html\n[mavenCentral]: https://search.maven.org/search?q=com.redmadrobot.versions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredmadrobot%2Fgradle-version-catalogs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredmadrobot%2Fgradle-version-catalogs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredmadrobot%2Fgradle-version-catalogs/lists"}