Create documentation for the Kotlin Metadata JVM library #4675

daniCsorbaJB · 2025-01-23T14:28:21Z

This PR is created to add new documentation for the Kotlin Metadata JVM library.
Related issue: KT-66421

sandwwraith · 2025-01-28T13:54:05Z

docs/topics/metadata-jvm.md

@@ -0,0 +1,399 @@
+[//]: # (title: Kotlin Metadata JVM library)
+
+The [`kotlinx-metadata-jvm`](https://github.com/JetBrains/kotlin/tree/master/libraries/kotlinx-metadata/jvm) library provides tools to read, modify, and generate metadata from Kotlin classes compiled for the JVM.


Here and further: the library is called kotlin-metadata-jvm, without X

Updated to kotlin-metadata-jvm everywhere

sandwwraith · 2025-01-28T13:55:48Z

docs/topics/metadata-jvm.md

+
+The [`kotlinx-metadata-jvm`](https://github.com/JetBrains/kotlin/tree/master/libraries/kotlinx-metadata/jvm) library provides tools to read, modify, and generate metadata from Kotlin classes compiled for the JVM.
+This metadata, stored in the [`@Metadata`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-metadata/) annotation within `.class` files,
+is used by libraries and tools to inspect Kotlin-specific constructs such as properties, functions,


I would emphasise here that it is also used by Kotlin-reflect, and this is why it is important to keep it consistent with what is written in the class file.

sounds like a good idea I like it:

How about modifying it like:
This metadata, stored in the @Metadata annotation within .class files,
is used by libraries and tools, such as kotlin-reflect, to inspect Kotlin-specific constructs such as properties, functions,
and classes at runtime.

The kotlin-reflect library relies on metadata to retrieve Kotlin-specific class details at runtime.
Any inconsistencies between the metadata and the actual .class file may lead to incorrect behavior when using reflection.

{style="note"}

sandwwraith · 2025-01-28T13:56:17Z

docs/topics/metadata-jvm.md

+This metadata, stored in the [`@Metadata`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-metadata/) annotation within `.class` files,
+is used by libraries and tools to inspect Kotlin-specific constructs such as properties, functions,
+and classes at runtime.
+You can also use this library to adjust attributes for binary compatibility validation or to generate and embed metadata into `.class` files.


Binary compatibility validator does not 'adjust' attributes, it simply reads modifiers. What did you mean here?

nice catch thank you, I originally had something about ASM here but without it doesn't work. 😟

How about:
You can also use the Kotlin Metadata JVM library to read and analyze metadata for binary compatibility checks or to generate and embed metadata into .class files.

sandwwraith · 2025-01-28T14:25:16Z

docs/topics/metadata-jvm.md

+
+## Add the library to your project
+
+To include the Kotlin Metadata JVM library in your project, add the appropriate dependency configuration based on your build tool.


I'd also would mention explicitly that it has the same version as kotlin-stdlib and Kotlin compiler.

Good idea, added this line:

The Kotlin Metadata JVM library follows the same versioning as the Kotlin compiler and standard library. Ensure that the version you use matches your project's Kotlin version.

sandwwraith · 2025-01-28T14:29:39Z

docs/topics/metadata-jvm.md

+
+```kotlin
+// Imports the necessary library
+import kotlin.Metadata


kotlin.Metadata is located in the standard library, so I'm not sure if 'Imports the necessary library' line is relevant here.

good point - tested it without and it works - removed this import from everywhere

sandwwraith · 2025-01-28T16:26:10Z

docs/topics/metadata-jvm.md

+## Modify metadata
+
+You can use the `kotlinx-metadata-jvm` library to modify Kotlin class metadata, allowing you to adjust visibility attributes,
+remove specific declarations, or prepare metadata for binary compatibility checks.


prepare metadata for binary compatibility checks — also seems not related, see my explanation about BCV

sandwwraith · 2025-01-28T16:29:57Z

docs/topics/metadata-jvm.md

+
+You can use the `kotlinx-metadata-jvm` library to modify Kotlin class metadata, allowing you to adjust visibility attributes,
+remove specific declarations, or prepare metadata for binary compatibility checks.
+


I would also emphasize that modifying metadata is essential if you modify the bytecode in certain ways.
Given that you already have the example of removing private functions, you can write something like this:

"The main goal of modifying metadata is that it should be consistent with existing bytecode. For example, if you are writing a tool like ProGuard, which shrinks the code and may delete some declarations, you have to delete the same declarations from the metadata as well. Let us imagine that we have a JVM tool that deletes private methods from .class files. For that tool to work with Kotlin, it would also have to delete private methods from metadata, which can be done the following way:"

Great suggestion, thank you! 💯

I restructured the section a little

sandwwraith · 2025-01-28T16:34:54Z

docs/topics/metadata-jvm.md

+        e.printStackTrace()
+    }
+}
+```


You can also mention that for readStrict/write pair there is a convenient transform shortcut: https://kotlinlang.org/api/kotlinx-metadata-jvm/kotlin-metadata-jvm/kotlin.metadata.jvm/-kotlin-class-metadata/-companion/transform.html

Nice one - thank you! - I added it as a tip

You can use the transform() function instead of separately calling readStrict() and write() separately.
This function parses metadata, applies transformations via a lambda, and writes the modified metadata automatically.

{style="tip"}

sandwwraith · 2025-01-28T16:54:04Z

docs/topics/metadata-jvm.md

+These functions allow you to extract detailed information about classes or files, while addressing different compatibility requirements:
+
+* `readLenient()`: Use this function to read metadata, including metadata generated by newer Kotlin compiler versions. However, it doesn't support modifying or writing metadata.
+* `readStrict()`: Use this function when you need to modify and write metadata. The `readStrict()` function only works with metadata generated by Kotlin compiler versions fully supported by your project.


I'd also add a link somewhere to the 'Detailed explanation' section of the README in case someone would like to know more about future versions handling

I added it to the note below 👍

sandwwraith · 2025-01-28T16:54:36Z

docs/topics/metadata-jvm.md

+
+## What's next
+
+* [See the API reference for the Kotlin Metadata JVM library](https://kotlinlang.org/api/kotlinx-metadata-jvm/).


Maybe mention 'Module metadata' section of the readme here? It seems lost for now.

added it like so - what do you think:

What's next

See the API reference for the Kotlin Metadata JVM library.

Check out the Kotlin Metadata JVM GitHub repostiory.

Learn about module metadata and working with .kotlin_module files.

feat: creating documentation for the kotlin metadata jvm library

0a38f69

daniCsorbaJB requested a review from a team as a code owner January 23, 2025 14:28

daniCsorbaJB added 2 commits January 23, 2025 15:56

removing unnecessary character

4435ebb

updating code example

b38c419

daniCsorbaJB requested a review from sandwwraith January 24, 2025 14:11

sandwwraith requested changes Jan 28, 2025

View reviewed changes

implementing review comments

88ce853

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create documentation for the Kotlin Metadata JVM library #4675

Create documentation for the Kotlin Metadata JVM library #4675

daniCsorbaJB commented Jan 23, 2025

sandwwraith Jan 28, 2025

daniCsorbaJB Jan 29, 2025

sandwwraith Jan 28, 2025

daniCsorbaJB Jan 29, 2025

sandwwraith Jan 28, 2025

daniCsorbaJB Jan 29, 2025

sandwwraith Jan 28, 2025

daniCsorbaJB Jan 30, 2025

sandwwraith Jan 28, 2025

daniCsorbaJB Jan 30, 2025

sandwwraith Jan 28, 2025

sandwwraith Jan 28, 2025

daniCsorbaJB Jan 30, 2025

sandwwraith Jan 28, 2025

daniCsorbaJB Jan 30, 2025

daniCsorbaJB Jan 31, 2025

sandwwraith Jan 28, 2025

daniCsorbaJB Jan 30, 2025

sandwwraith Jan 28, 2025

daniCsorbaJB Jan 31, 2025

		@@ -0,0 +1,399 @@
		[//]: # (title: Kotlin Metadata JVM library)

		The [`kotlinx-metadata-jvm`](https://github.com/JetBrains/kotlin/tree/master/libraries/kotlinx-metadata/jvm) library provides tools to read, modify, and generate metadata from Kotlin classes compiled for the JVM.


		## Add the library to your project

		To include the Kotlin Metadata JVM library in your project, add the appropriate dependency configuration based on your build tool.


		You can use the `kotlinx-metadata-jvm` library to modify Kotlin class metadata, allowing you to adjust visibility attributes,
		remove specific declarations, or prepare metadata for binary compatibility checks.


		## What's next

		* [See the API reference for the Kotlin Metadata JVM library](https://kotlinlang.org/api/kotlinx-metadata-jvm/).

Create documentation for the Kotlin Metadata JVM library #4675

Are you sure you want to change the base?

Create documentation for the Kotlin Metadata JVM library #4675

Conversation

daniCsorbaJB commented Jan 23, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

What's next