feat: platform libraries update (#4694)

Author: danil-pavlov

docs/topics/compiler-reference.md

@@ -341,7 +341,7 @@ Include the native bitcode library.
 
 ### -no-default-libs
 
-Disable linking user code with the [default platform libraries](native-platform-libs.md) distributed with the compiler.
+Disable linking user code with the prebuilt [platform libraries](native-platform-libs.md) distributed with the compiler.
 
 ### -nomain
 

docs/topics/multiplatform/multiplatform-share-on-platforms.md

@@ -62,8 +62,8 @@ it and call `runBlocking` from a source set that is shared between the JVM and n
 
 ## Connect platform-specific libraries
 
-To share more native code without being limited by platform-specific dependencies, connect [platform-specific libraries](native-platform-libs.md).
-Libraries shipped with Kotlin/Native (like Foundation, UIKit, and POSIX) are available in shared source sets by default.
+To share more native code without being limited by platform-specific dependencies, use [platform libraries](native-platform-libs.md),
+like Foundation, UIKit, and POSIX. These libraries are shipped with Kotlin/Native and available in shared source sets by default.
 
 In addition, if you use the [Kotlin CocoaPods Gradle](native-cocoapods.md) plugin in your projects,
 you can work with third-party native libraries consumed with the [`cinterop` mechanism](native-c-interop.md).

docs/topics/native/native-definition-file.md

@@ -258,7 +258,7 @@ Note that the generated bindings are generally platform-specific, so if you are
 the bindings need to be regenerated.
 
 * For host libraries that are not included in the sysroot search paths, headers may be needed.
-* For a typical Unix library with a configuration script, the `compilerOpts` will likely contain the output of a
+* For a typical UNIX library with a configuration script, the `compilerOpts` will likely contain the output of a
   configuration script with the `--cflags` option (maybe without exact paths).
 * The output of a configuration script with `--libs` can be passed to the `linkerOpts` property.
 

docs/topics/native/native-overview.md

@@ -47,7 +47,7 @@ static or dynamic [C libraries](native-c-interop.md),
 Swift/Objective-C [frameworks](native-objc-interop.md),
 graphical engines, and anything else directly from Kotlin/Native.
 
-Kotlin/Native [libraries](native-platform-libs.md) help share Kotlin
+Kotlin/Native [platform libraries](native-platform-libs.md) help share Kotlin
 code between projects.
 POSIX, gzip, OpenGL, Metal, Foundation, and many other popular libraries and Apple frameworks
 are pre-imported and included as Kotlin/Native libraries in the compiler package.

docs/topics/native/native-platform-libs.md

@@ -1,46 +1,88 @@
 [//]: # (title: Platform libraries)
 
-To provide access to user's native operating system services,
-Kotlin/Native distribution includes a set of prebuilt libraries specific to
-each target. We call them **Platform Libraries**.
+To provide access to native services of operating systems, the Kotlin/Native distribution includes a set of prebuilt
+libraries specific to each target. These are called _platform libraries_.
 
-### POSIX bindings
+The packages from platform libraries are available by default. You don't need to specify additional link options to use
+them. The Kotlin/Native compiler automatically detects which platform libraries are accessed and links the necessary ones.
 
-For all Unix- or Windows-based targets (including Android and
-iOS targets) we provide the POSIX platform lib. It contains bindings
-to platform's implementation of the [POSIX standard](https://en.wikipedia.org/wiki/POSIX).
+However, platform libraries in the compiler distribution are merely wrappers and bindings to the native libraries. That
+means you need to install native libraries themselves (`.so`, `.a`, `.dylib`, `.dll`, and so on) on your local machine.
 
-To use the library, just import it: 
+## POSIX bindings
+
+Kotlin provides the POSIX platform library for all UNIX- and Windows-based targets, including Android and iOS.
+These platform libraries contain bindings to the platform's implementation, which follows the [POSIX standard](https://en.wikipedia.org/wiki/POSIX).
+
+To use the library, import it into your project:
 
 ```kotlin
 import platform.posix.*
 ```
 
-The only target for which it is not available is [WebAssembly](https://en.wikipedia.org/wiki/WebAssembly).
+> The `platform.posix` contents differ across platforms because of variations in POSIX implementations.
+>
+{style="note"}
+
+You can explore the contents of the `posix.def` file for each supported platform here:
+
+* [iOS](https://github.com/JetBrains/kotlin/tree/master/kotlin-native/platformLibs/src/platform/ios/posix.def)
+* [macOS](https://github.com/JetBrains/kotlin/tree/master/kotlin-native/platformLibs/src/platform/osx/posix.def)
+* [tvOS](https://github.com/JetBrains/kotlin/tree/master/kotlin-native/platformLibs/src/platform/tvos/posix.def)
+* [watchOS](https://github.com/JetBrains/kotlin/tree/master/kotlin-native/platformLibs/src/platform/watchos/posix.def)
+* [Linux](https://github.com/JetBrains/kotlin/tree/master/kotlin-native/platformLibs/src/platform/linux/posix.def)
+* [Windows (MinGW)](https://github.com/JetBrains/kotlin/tree/master/kotlin-native/platformLibs/src/platform/mingw/posix.def)
+* [Android](https://github.com/JetBrains/kotlin/tree/master/kotlin-native/platformLibs/src/platform/android/posix.def)
+
+The POSIX platform library is not available for the [WebAssembly](wasm-overview.md) target.
+
+## Popular native libraries
+
+Kotlin/Native provides bindings for various popular native libraries that are commonly used on different platforms,
+such as OpenGL, zlib, and Foundation.
+
+On Apple platforms, the `objc` library is included to enable [interoperability with Objective-C](native-objc-interop.md)
+APIs.
+
+You can explore the native libraries available for Kotlin/Native targets in your compiler distribution,
+depending on your setup:
+
+* If you [installed a standalone Kotlin/Native compiler](native-get-started.md#download-and-install-the-compiler):
+
+  1. Go to the unpacked archive with the compiler distribution, for example, `kotlin-native-prebuilt-macos-aarch64-2.1.0`.
+  2. Navigate to the `klib/platform` directory.
+  3. Choose the folder with the corresponding target.
+
+* If you use the Kotlin plugin in your IDE (bundled with IntelliJ IDEA and Android Studio):
+
+  1. In your command line tool, run the following to navigate to the `.konan` folder:
+
+     <tabs>
+     <tab title="macOS and Linux">
 
-Note that the content of `platform.posix` is NOT identical on
-different platforms, in the same way as different POSIX implementations
-are a little different.
+     ```none
+     ~/.konan/
+     ```
 
-### Popular native libraries
+     </tab>
+     <tab title="Windows">
 
-There are many more platform libraries available for host and
-cross-compilation targets.  Kotlin/Native distribution provides access to
-OpenGL, zlib and other popular native libraries on
-applicable platforms.
+     ```none
+     %\USERPROFILE%\.konan
+     ```
 
-On Apple platforms, `objc` library is provided for interoperability with [Objective-C](https://en.wikipedia.org/wiki/Objective-C).
+     </tab>
+     </tabs>
 
-Inspect the contents of `dist/klib/platform/$target` of the distribution for the details.
+  2. Open the Kotlin/Native compiler distribution, for example, `kotlin-native-prebuilt-macos-aarch64-2.1.0`.
+  3. Navigate to the `klib/platform` directory.
+  4. Choose the folder with the corresponding target.
 
-## Availability by default
+> If you'd like to explore the definition file for each supported platform library: in the compiler distribution folder,
+> navigate to the `konan/platformDef` directory and choose the necessary target.
+> 
+{style="tip"}
 
-The packages from platform libraries are available by default. No
-special link flags need to be specified to use them. Kotlin/Native
-compiler automatically detects which of the platform libraries have
-been accessed and automatically links the needed libraries.
+## What's next
 
-On the other hand, the platform libs in the distribution are merely
-just wrappers and bindings to the native libraries.  That means the
-native libraries themselves (`.so`, `.a`, `.dylib`, `.dll` etc)
-should be installed on the machine.
+[Learn more about interoperability with Swift/Objective-C](native-objc-interop.md)