update: libcurl tutorial (#4783)

Author: danil-pavlov

docs/images/native/cinterop/native-output.png

@@ -1,7 +1,7 @@
-[//]: # (title: Create an app using C Interop and libcurl – tutorial)
+[//]: # (title: Create an app using C interop and libcurl – tutorial)
 
 This tutorial demonstrates how to use IntelliJ IDEA to create a command-line application. You'll learn how to create
-a simple HTTP client that can run natively on specified platforms using Kotlin/Native and the `libcurl` library.
+a simple HTTP client that can run natively on specified platforms using Kotlin/Native and the libcurl library.
 
 The output will be an executable command-line app that you can run on macOS and Linux and make simple HTTP GET requests.
 
@@ -13,15 +13,19 @@ Kotlin/Native can use the [Gradle](https://gradle.org) build system through the
 
 ## Before you start
 
-1. Download and install the latest version of [IntelliJ IDEA](https://www.jetbrains.com/idea/) with the latest [Kotlin plugin](releases.md).
+1. Download and install the latest version of [IntelliJ IDEA](https://www.jetbrains.com/idea/).
 2. Clone the [project template](https://github.com/Kotlin/kmp-native-wizard)
-   by selecting **File** | **New** | **Project from Version Control** in IntelliJ IDEA.
+   by selecting **File** | **New** | **Project from Version Control** in IntelliJ IDEA and using this URL:
+
+   ```none
+   https://github.com/Kotlin/kmp-native-wizard
+   ```  
 
 3. Explore the project structure:
 
    ![Native application project structure](native-project-structure.png){width=700}
 
-   The template includes a project with the files and folders you need to get you started. It's important to understand
+   The template includes a project with the files and folders you need to get started. It's important to understand
    that an application written in Kotlin/Native can target different platforms if the code does not have platform-specific
    requirements. Your code is placed in the `nativeMain` directory with a corresponding `nativeTest`. For this tutorial,
    keep the folder structure as is.
@@ -54,7 +58,7 @@ Kotlin/Native can use the [Gradle](https://gradle.org) build system through the
 
     ```
 
-   * Targets are defined using `macosX64`, `macosArm64`, `linuxX64`, `linuxArm64`, and `mingwX64` for macOS, Linux,
+   * Targets are defined using `macosArm64`, `macosX64`, `linuxArm64`, `linuxX64`, and `mingwX64` for macOS, Linux,
      and Windows. See the complete list of [supported platforms](native-target-support.md).
    * The entry itself defines a series of properties to indicate how the binary is generated and the entry
      point of the applications. These can be left as default values.
@@ -73,15 +77,17 @@ for pretty much anything you may need. Kotlin/Native is already shipped with a s
 which provide some additional common functionality to the standard library.
 
 An ideal scenario for interop is to call C functions as if you are calling Kotlin functions, following the same
-signature and conventions. This is when the `cinterop` tool comes in handy. It takes a C library and generates the
+signature and conventions. This is when the cinterop tool comes in handy. It takes a C library and generates the
 corresponding Kotlin bindings, so that the library can be used as if it were Kotlin code.
 
-To generate these bindings, create a library definition `.def` file that contains some information about the necessary
-headers. In this app, you'll need the `libcurl` library to make some HTTP calls. To create a definition file:
+To generate these bindings, each library needs a definition file, usually with the same name as the library.
+This is a property file that describes exactly how the library should be consumed.
+
+In this app, you'll need the libcurl library to make some HTTP calls. To create its definition file:
 
 1. Select the `src` folder and create a new directory with **File | New | Directory**.
-2. Name new directory **nativeInterop/cinterop**. This is the default convention for header file locations, though it can
-   be overridden in the `build.gradle.kts` file if you use a different location.
+2. Name the new directory **nativeInterop/cinterop**. This is the default convention for header file locations,
+   though it can be overridden in the `build.gradle.kts` file if you use a different location.
 3. Select this new subfolder and create a new `libcurl.def` file with **File | New | File**.
 4. Update your file with the following code:
 
@@ -94,28 +100,26 @@ headers. In this app, you'll need the `libcurl` library to make some HTTP calls.
     linkerOpts.linux = -L/usr/lib/x86_64-linux-gnu -lcurl
     ```
 
-   * `headers` is the list of header files to generate Kotlin stubs. You can add multiple files to this entry,
-     separating each with a `\` on a new line. In this case, it's only `curl.h`. The referenced files need to be available
-     on the system path (in this case, it's `/usr/include/curl`).
+   * `headers` is the list of header files to generate Kotlin stubs for. You can add multiple files to this entry,
+     separating each with a space. In this case, it's only `curl.h`. The referenced files need to be available
+     on the specified path (in this case, it's `/usr/include/curl`).
    * `headerFilter` shows what exactly is included. In C, all the headers are also included when one file references
      another one with the `#include` directive. Sometimes it's not necessary, and you can add this parameter
-     [using glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)) to fine-tune things.
+     [using glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)) to make adjustments.
 
-     `headerFilter` is an optional argument and is mostly used when the library is installed as a system library. You don't
-     want to fetch external dependencies (such as system `stdint.h` header) into the interop library. It may be important to
-     optimize the library size and fix potential conflicts between the system and the provided Kotlin/Native compilation
-     environment.
+     You can use `headerFilter` if you don't want to fetch external dependencies (such as system `stdint.h` header) into
+     the interop library. Also, it may be useful for library size optimization and fixing potential conflicts between the
+     system and the provided Kotlin/Native compilation environment.
 
-   * The next lines are about providing linker and compiler options, which can vary depending on different target platforms.
-     In this case, they are macOS (the `.osx` suffix) and Linux (the `.linux` suffix). Parameters without a suffix are also
-     possible (for example, `linkerOpts=`) and applied to all platforms.
+   * If the behavior for a certain platform needs to be modified, you can use a format like `compilerOpts.osx` or `compilerOpts.linux`
+     to provide platform-specific values to the options. In this case, they are macOS (the `.osx` suffix) and Linux (the `.linux` suffix).
+     Parameters without a suffix are also possible (for example, `linkerOpts=`) and applied to all platforms.
 
-The convention is that each library gets its definition file, usually with the same name as the library. For more
-information on all the options available to `cinterop`, see [the Interop section](native-c-interop.md).
+   For the full list of available options, see [Definition file](native-definition-file.md#properties).
 
 > You need to have the `curl` library binaries on your system to make the sample work. On macOS and Linux, they are usually
-> included. On Windows, you can build it from [sources](https://curl.haxx.se/download.html) (you'll need Visual Studio or
-> Windows SDK Commandline tools). For more details, see the [related blog post](https://jonnyzzz.com/blog/2018/10/29/kn-libcurl-windows/).
+> included. On Windows, you can build it from [sources](https://curl.se/download.html) (you'll need Microsoft Visual Studio or
+> Windows SDK command-line tools). For more details, see the [related blog post](https://jonnyzzz.com/blog/2018/10/29/kn-libcurl-windows/).
 > Alternatively, you may want to consider a [MinGW/MSYS2](https://www.msys2.org/) `curl` binary.
 >
 {style="note"}
@@ -127,11 +131,11 @@ entry to the `build.gradle.kts` file:
 
 ```kotlin
 nativeTarget.apply {
-    compilations.getByName("main") {    // NL
-        cinterops {                     // NL
-            val libcurl by creating     // NL
-        }                               // NL
-    }                                   // NL
+    compilations.getByName("main") {
+        cinterops {
+            val libcurl by creating
+        }
+    }
     binaries {
         executable {
             entryPoint = "main"
@@ -140,24 +144,24 @@ nativeTarget.apply {
 }
 ```
 
-The new lines are marked with `// NL`. First, `cinterops` is added, and then an entry for each `def` file. By default,
-the name of the file is used. You can override this with additional parameters:
+First, `cinterops` is added, and then an entry for a definition file. By default, the name of the file is used.
+You can override this with additional parameters:
 
 ```kotlin
-val libcurl by creating {
-    definitionFile.set(project.file("src/nativeInterop/cinterop/libcurl.def"))
-    packageName("com.jetbrains.handson.http")
-    compilerOpts("-I/path")
-    includeDirs.allHeaders("path")
+cinterops {
+    val libcurl by creating {
+        definitionFile.set(project.file("src/nativeInterop/cinterop/libcurl.def"))
+        packageName("com.jetbrains.handson.http")
+        compilerOpts("-I/path")
+        includeDirs.allHeaders("path")
+    }
 }
 ```
 
-See the [Interoperability with C](native-c-interop.md) section for more details on the available options.
-
 ## Write the application code
 
-Now you have the library and the corresponding Kotlin stubs and can use them from your application. For this tutorial,
-convert the [simple.c](https://curl.haxx.se/libcurl/c/simple.html) example to Kotlin.
+Now that you have the library and the corresponding Kotlin stubs, you can use them from your application.
+For this tutorial, convert the [simple.c](https://curl.se/libcurl/c/simple.html) example to Kotlin.
 
 In the `src/nativeMain/kotlin/` folder, update your `Main.kt` file with the following code:
 
@@ -181,31 +185,37 @@ fun main(args: Array<String>) {
 ```
 
 As you can see, explicit variable declarations are eliminated in the Kotlin version, but everything else is pretty much
-the same as the C version. All the calls you'd expect in the `libcurl` library are available in the Kotlin equivalent.
+the same as the C version. All the calls you'd expect in the libcurl library are available in the Kotlin equivalent.
 
 > This is a line-by-line literal translation. You could also write this in a more Kotlin idiomatic way.
 >
+{type="tip"}
 
 ## Compile and run the application
 
-1. Compile the application. To do that, call `runDebugExecutableNative` in the list of run Gradle tasks or use the following
+1. Compile the application. To do that, run the `runDebugExecutableNative` Gradle task from the task list or use the following
    command in the terminal:
+ 
+   ```bash
+   ./gradlew runDebugExecutableNative
+   ```
 
-    ```bash
-    ./gradlew runDebugExecutableNative
-    ```
-   In this case, the `cinterop` generated part is implicitly included in the build.
+   In this case, the part generated by the cinterop tool is implicitly included in the build.
 
-2. If there are no errors during compilation, click the green **Run** icon in the gutter beside the `main()` method or
-   use the **Alt+Enter** shortcut to invoke the launch menu in IntelliJ IDEA.
+2. If there are no errors during compilation, click the green **Run** icon in the gutter next to the `main()` function or
+   use the <shortcut>Shift + Cmd + R</shortcut>/<shortcut>Shift + F10</shortcut> shortcut.
 
-   IntelliJ IDEA opens the **Run** tab and shows the output — the contents of `https://example.com`:
+   IntelliJ IDEA opens the **Run** tab and shows the output — the contents of [example.com](https://example.com/):
 
    ![Application output with HTML-code](native-output.png){width=700}
 
 You can see the actual output because the call `curl_easy_perform` prints the result to the standard output. You could
 hide this using `curl_easy_setopt`.
 
-> You can get the full code [here](https://github.com/Kotlin/kotlin-hands-on-intro-kotlin-native).
+> You can get the full project code in our [GitHub repository](https://github.com/Kotlin/kotlin-hands-on-intro-kotlin-native).
 >
 {style="note"}
+
+## What's next
+
+Learn more about [Kotlin's interoperability with C](native-c-interop.md).