Skip to content

Commit 1e9a7a6

Browse files
README: add TOML version catalog example, add supported platforms, tools
Using KTS and a TOML version catalog is the new default for Android projects, so make it the primary example.
1 parent f2fc048 commit 1e9a7a6

File tree

1 file changed

+93
-17
lines changed

1 file changed

+93
-17
lines changed

README.md

Lines changed: 93 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -83,12 +83,10 @@ box.put(person) // Update
8383
box.remove(person) // Delete
8484
```
8585

86-
Continue with the ➡️ **[Getting Started guide](https://docs.objectbox.io/getting-started)**.
87-
8886
## Table of Contents
8987

9088
- [Key Features](#key-features)
91-
- [Getting started](#getting-started)
89+
- [Getting Started](#getting-started)
9290
- [Gradle setup](#gradle-setup)
9391
- [Maven setup](#maven-setup)
9492
- [Why use ObjectBox?](#why-use-objectbox-for-java-data-management)
@@ -105,31 +103,74 @@ Continue with the ➡️ **[Getting Started guide](https://docs.objectbox.io/get
105103
🔗 **[Built-in Object Relations](https://docs.objectbox.io/relations):** built-in support for object relations, allowing you to easily establish and manage relationships between objects.\
106104
👌 **Ease of use:** concise API that eliminates the need for complex SQL queries, saving you time and effort during development.
107105

108-
## Getting started
106+
## Getting Started
107+
108+
> [!NOTE]
109+
> Prefer to look at example code? Check out [our examples repository](https://github.com/objectbox/objectbox-examples).
110+
111+
You can add the ObjectBox Java SDK to your project using:
112+
113+
- a [Gradle setup](#gradle-setup)
114+
- a [Maven setup](#maven-setup)
115+
116+
ObjectBox tools and dependencies are available on [the Maven Central repository](https://central.sonatype.com/namespace/io.objectbox).
117+
118+
The database libraries available for the ObjectBox Java SDK support:
119+
120+
- JVM 8 or newer
121+
- Linux (x64, arm64, armv7)
122+
- macOS (x64, arm64)
123+
- Windows (x64)
124+
- Android 5.0 (API level 21) or newer
125+
126+
The APIs and tools of the ObjectBox Java SDK support:
127+
128+
- Java 8 or newer
129+
- Kotlin 1.7 or newer
130+
- Android Gradle Plugin 8.0 or newer
109131

110132
### Gradle setup
111133

112-
For Gradle projects, add the ObjectBox Gradle plugin to your root Gradle script:
134+
For Gradle projects, add the ObjectBox Gradle plugin to your root Gradle script.
135+
136+
When using a TOML version catalog and plugins syntax (for alternatives see below):
137+
138+
```toml
139+
# gradle/libs.versions.toml
140+
[versions]
141+
objectbox = "5.1.0"
142+
143+
[plugins]
144+
objectbox = { id = "io.objectbox", version.ref = "objectbox" }
145+
```
113146

114147
```kotlin
115148
// build.gradle.kts
116-
buildscript {
117-
val objectboxVersion by extra("5.1.0")
118-
repositories {
119-
mavenCentral()
120-
}
121-
dependencies {
122-
classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
149+
plugins {
150+
alias(libs.plugins.objectbox) apply false
151+
}
152+
```
153+
154+
```kotlin
155+
// settings.gradle.kts
156+
pluginManagement {
157+
resolutionStrategy {
158+
eachPlugin {
159+
if (requested.id.id == "io.objectbox") {
160+
useModule("io.objectbox:objectbox-gradle-plugin:${requested.version}")
161+
}
162+
}
123163
}
124164
}
125165
```
126166

167+
Alternatives:
168+
127169
<details><summary>Using plugins syntax</summary>
128170

129171
```kotlin
130172
// build.gradle.kts
131173
plugins {
132-
id("com.android.application") version "8.0.2" apply false // When used in an Android project
133174
id("io.objectbox") version "5.1.0" apply false
134175
}
135176
```
@@ -149,7 +190,24 @@ pluginManagement {
149190

150191
</details>
151192

152-
<details><summary>Using Groovy syntax</summary>
193+
<details><summary>Using buildscript syntax (KTS)</summary>
194+
195+
```kotlin
196+
// build.gradle.kts
197+
buildscript {
198+
val objectboxVersion by extra("5.1.0")
199+
repositories {
200+
mavenCentral()
201+
}
202+
dependencies {
203+
classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
204+
}
205+
}
206+
```
207+
208+
</details>
209+
210+
<details><summary>Using buildscript syntax (Groovy)</summary>
153211

154212
```groovy
155213
// build.gradle
@@ -166,19 +224,33 @@ buildscript {
166224

167225
</details>
168226

169-
And in the Gradle script of your subproject apply the plugin:
227+
Then, in the Gradle script of your subproject apply the plugin:
228+
229+
```kotlin
230+
// app/build.gradle.kts
231+
plugins {
232+
alias(libs.plugins.android.application) // When used in an Android project
233+
alias(libs.plugins.kotlin.android) // When used in an Android project
234+
alias(libs.plugins.kotlin.kapt) // When used in an Android or Kotlin project
235+
alias(libs.plugins.objectbox) // Add after other plugins
236+
}
237+
```
238+
239+
<details><summary>Alternative: when not using a version catalog, using the plugin id</summary>
170240

171241
```kotlin
172242
// app/build.gradle.kts
173243
plugins {
174244
id("com.android.application") // When used in an Android project
175245
kotlin("android") // When used in an Android project
176-
kotlin("kapt")
246+
kotlin("kapt") // When used in an Android or Kotlin project
177247
id("io.objectbox") // Add after other plugins
178248
}
179249
```
180250

181-
Then sync the Gradle project with your IDE.
251+
</details>
252+
253+
Finally, sync the Gradle project with your IDE (for ex. using "Sync Project with Gradle Files" in Android Studio).
182254

183255
Your project can now use ObjectBox, continue by [defining entity classes](https://docs.objectbox.io/getting-started#define-entity-classes).
184256

@@ -188,6 +260,10 @@ This is currently only supported for JVM projects.
188260

189261
To set up a Maven project, see the [README of the Java Maven example project](https://github.com/objectbox/objectbox-examples/blob/main/java-main-maven/README.md).
190262

263+
## Frequently Asked Questions and Troubleshooting
264+
265+
If you encounter any problems, check out the [FAQ](https://docs.objectbox.io/faq) and [Troubleshooting](https://docs.objectbox.io/troubleshooting) pages.
266+
191267
## Why use ObjectBox for Java data management?
192268

193269
ObjectBox is a NoSQL Java database designed for local data storage on resource-restricted devices, prioritizing

0 commit comments

Comments
 (0)