Add Maven/Gradle usage examples to kotlinx-metadata-jvm ReadMe

This commit is contained in:
Alexander Udalov
2018-06-01 14:43:40 +02:00
parent adb129d244
commit 5478dabb38
+39
View File
@@ -2,6 +2,45 @@
This library provides an API to read and modify metadata of binary files generated by the Kotlin/JVM compiler, namely `.class` and `.kotlin_module` files.
## Usage
To use this library in your project, add the kotlinx repository at https://kotlin.bintray.com/kotlinx, and a dependency on `org.jetbrains.kotlinx:kotlinx-metadata-jvm:$kotlinx_metadata_version` (where `kotlinx_metadata_version` is the version of the library).
Example usage in Maven:
```
<project>
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-metadata-jvm</artifactId>
<version>${kotlinx_metadata_version}</version>
</dependency>
</dependencies>
<repositories>
<repository>
<id>bintray-kotlin-kotlinx</id>
<name>bintray</name>
<url>https://kotlin.bintray.com/kotlinx</url>
</repository>
</repositories>
...
</project>
```
Example usage in Gradle:
```
repositories {
mavenCentral()
maven { url "https://kotlin.bintray.com/kotlinx/" }
}
dependencies {
compile "org.jetbrains.kotlinx:kotlinx-metadata-jvm:$kotlinx_metadata_version"
}
```
## Overview
The entry point for reading the Kotlin metadata of a `.class` file is [`KotlinClassMetadata.read`](src/kotlinx/metadata/jvm/KotlinClassMetadata.kt). The data it takes is encapsulated in [`KotlinClassHeader`](src/kotlinx/metadata/jvm/KotlinClassHeader.kt) which is basically what is written in the [`kotlin.Metadata`](../../stdlib/jvm/runtime/kotlin/Metadata.kt) annotation on the class file generated by the Kotlin compiler. Construct `KotlinClassHeader` by reading the values from `kotlin.Metadata` reflectively or from some other resource, and then use `KotlinClassMetadata.read` to obtain the correct instance of the class metadata. (Note that loading values of `kotlin.Metadata` reflectively is only possible *from Java sources* until Kotlin 1.3, because this annotation is internal in the standard library, see [KT-23602](https://youtrack.jetbrains.com/issue/KT-23602).)