1# BOM Migration — Gradle Programmatic Version Catalog (`settings.gradle`)
2 
3Some projects define version catalogs programmatically in `settings.gradle` / `settings.gradle.kts` instead of using a TOML file. OpenRewrite does not support this either ([openrewrite/rewrite#4852](https://github.com/openrewrite/rewrite/issues/4852)). Handle manually.
4 
5## Step 0 — Detect programmatic catalog usage
6 
7Look for a `dependencyResolutionManagement` block in `settings.gradle` or `settings.gradle.kts`:
8 
9```groovy
10// settings.gradle (Groovy DSL)
11dependencyResolutionManagement {
12    versionCatalogs {
13        libs {
14            version("azureSdk", "1.41.4")
15            version("azureStorage", "8.6.6")
16            library("azure", "com.microsoft.azure", "azure").versionRef("azureSdk")
17            library("azure-storage", "com.microsoft.azure", "azure-storage").versionRef("azureStorage")
18        }
19    }
20}
21```
22 
23```kotlin
24// settings.gradle.kts (Kotlin DSL)
25dependencyResolutionManagement {
26    versionCatalogs {
27        create("libs") {
28            version("azureSdk", "1.41.4")
29            version("azureStorage", "8.6.6")
30            library("azure", "com.microsoft.azure", "azure").versionRef("azureSdk")
31            library("azure-storage", "com.microsoft.azure", "azure-storage").versionRef("azureStorage")
32        }
33    }
34}
35```
36 
37The `library()` call can also use the two-arg `module` form (the same syntax applies to Kotlin DSL):
38```groovy
39library("azure", "com.microsoft.azure:azure").versionRef("azureSdk")
40library("azure-inline", "com.microsoft.azure:azure").version("1.41.4")
41```
42 
43If the project has this pattern and contains Azure dependency entries, use this section. The same `libs.<alias>` accessor syntax is used in `build.gradle` as with TOML catalogs.
44 
45## Step 1 — Add or upgrade the BOM
46 
47Add a version and library entry for the BOM inside the `versionCatalogs` block:
48 
49```groovy
50// Groovy DSL
51dependencyResolutionManagement {
52    versionCatalogs {
53        libs {
54            version("azureSdkBom", "{bom_version}")
55            library("azure-sdk-bom", "com.azure", "azure-sdk-bom").versionRef("azureSdkBom")
56        }
57    }
58}
59```
60 
61```kotlin
62// Kotlin DSL
63dependencyResolutionManagement {
64    versionCatalogs {
65        create("libs") {
66            version("azureSdkBom", "{bom_version}")
67            library("azure-sdk-bom", "com.azure", "azure-sdk-bom").versionRef("azureSdkBom")
68        }
69    }
70}
71```
72 
73If a BOM entry already exists, update the version string.
74 
75Add the platform dependency (if not already present).
76 
77Groovy DSL (`build.gradle`):
78```groovy
79dependencies {
80    implementation enforcedPlatform(libs.azure.sdk.bom)
81}
82```
83 
84Kotlin DSL (`build.gradle.kts`):
85```kotlin
86dependencies {
87    implementation(enforcedPlatform(libs.azure.sdk.bom))
88}
89```
90 
91## Step 2 — Remove explicit versions from BOM-managed Azure libraries
92 
93For each modern Azure library (`com.azure.*`) managed by the BOM, change its catalog entry to remove the version. Use the `withoutVersion()` call:
94 
95The snippets below show Groovy DSL (`settings.gradle`); the same code applies to Kotlin DSL (`settings.gradle.kts`).
96 
97Before:
98```groovy
99library("azure-identity", "com.azure", "azure-identity").versionRef("azureIdentity")
100```
101 
102After:
103```groovy
104library("azure-identity", "com.azure", "azure-identity").withoutVersion()
105```
106 
107For the two-arg module form (the same syntax applies to Kotlin DSL):
108```groovy
109// Before
110library("azure-identity", "com.azure:azure-identity").versionRef("azureIdentity")
111// After
112library("azure-identity", "com.azure:azure-identity").withoutVersion()
113```
114 
115Then remove any orphaned `version(...)` calls that are no longer referenced.
116 
117## Step 3 — Replace legacy Azure library entries with modern equivalents
118 
119For each legacy `com.microsoft.azure.*` library call:
1201. Replace the group and artifact with the modern `com.azure.*` equivalent.
1212. Change `.versionRef(...)` or `.version(...)` to `.withoutVersion()` if the new artifact is managed by the BOM.
1223. Remove orphaned `version(...)` calls.
1234. If you rename the alias (first argument), update **all** references in `build.gradle` / `build.gradle.kts` and any `bundle(...)` calls.
124 
125The snippets below show Groovy DSL (`settings.gradle`); the same code applies to Kotlin DSL (`settings.gradle.kts`).
126 
127Before:
128```groovy
129version("azureSdk", "1.41.4")
130version("azureStorage", "8.6.6")
131library("azure", "com.microsoft.azure", "azure").versionRef("azureSdk")
132library("azure-storage", "com.microsoft.azure", "azure-storage").versionRef("azureStorage")
133```
134 
135After:
136```groovy
137library("azure-resourcemanager", "com.azure.resourcemanager", "azure-resourcemanager").withoutVersion()
138library("azure-storage-blob", "com.azure", "azure-storage-blob").withoutVersion()
139```
140 
141Then update `build.gradle` (Groovy DSL):
142```groovy
143// Before
144implementation libs.azure
145implementation libs.azure.storage
146 
147// After
148implementation libs.azure.resourcemanager
149implementation libs.azure.storage.blob
150```
151 
152Or `build.gradle.kts` (Kotlin DSL):
153```kotlin
154// Before
155implementation(libs.azure)
156implementation(libs.azure.storage)
157 
158// After
159implementation(libs.azure.resourcemanager)
160implementation(libs.azure.storage.blob)
161```
162 
163## Step 4 — Handle bundles
164 
165If `bundle(...)` calls reference any renamed or removed aliases, update them:
166 
167Groovy DSL (`settings.gradle`):
168```groovy
169// Before
170bundle("azureLibs", ["azure", "azure-storage"])
171// After
172bundle("azureLibs", ["azure-resourcemanager", "azure-storage-blob", "azure-identity"])
173```
174 
175Kotlin DSL (`settings.gradle.kts`):
176```kotlin
177// Before
178bundle("azureLibs", listOf("azure", "azure-storage"))
179// After
180bundle("azureLibs", listOf("azure-resourcemanager", "azure-storage-blob", "azure-identity"))
181```
182 
183## Expected settings.gradle after migration
184 
185Groovy DSL (`settings.gradle`):
186```groovy
187dependencyResolutionManagement {
188    versionCatalogs {
189        libs {
190            version("azureSdkBom", "{bom_version}")
191            library("azure-sdk-bom", "com.azure", "azure-sdk-bom").versionRef("azureSdkBom")
192            library("azure-identity", "com.azure", "azure-identity").withoutVersion()
193            library("azure-resourcemanager", "com.azure.resourcemanager", "azure-resourcemanager").withoutVersion()
194        }
195    }
196}
197```
198 
199Kotlin DSL (`settings.gradle.kts`):
200```kotlin
201dependencyResolutionManagement {
202    versionCatalogs {
203        create("libs") {
204            version("azureSdkBom", "{bom_version}")
205            library("azure-sdk-bom", "com.azure", "azure-sdk-bom").versionRef("azureSdkBom")
206            library("azure-identity", "com.azure", "azure-identity").withoutVersion()
207            library("azure-resourcemanager", "com.azure.resourcemanager", "azure-resourcemanager").withoutVersion()
208        }
209    }
210}
211```
212 
213