update: recommendations on ios dependencies and minor changes (#4699)

Author: danil-pavlov

docs/topics/multiplatform/multiplatform-direct-integration.md

@@ -29,8 +29,9 @@ In general, the script:
 ## How to set up
 
 If you're currently using the CocoaPods plugin to connect your Kotlin framework, migrate first.
+If your project doesn't have CocoaPods dependencies, [skip this step](#connect-the-framework-to-your-project).
 
-### Migrate from CocoaPods plugin to direct integration {initial-collapse-state="collapsed" collapsible="true"}
+### Migrate from the CocoaPods plugin
 
 To migrate from the CocoaPods plugin:
 
@@ -76,7 +77,7 @@ To connect the Kotlin framework generated from the multiplatform project to your
 
    ![User Script Sandboxing](disable-sandboxing-in-xcode-project-settings.png){width=700}
 
-   > This may require restarting your Gradle daemon, if you built the iOS project without disabling sandboxing first.
+   > This may require restarting your Gradle daemon if you built the iOS project without disabling sandboxing first.
    > Stop the Gradle daemon process that might have been sandboxed:
    > ```shell
    > ./gradlew --stop

docs/topics/multiplatform/multiplatform-ios-dependencies.md

@@ -7,103 +7,43 @@ You can also reuse other libraries and frameworks from the iOS ecosystem in your
 interoperability with Objective-C dependencies and Swift dependencies if their APIs are exported to Objective-C with
 the `@objc` attribute. Pure Swift dependencies are not yet supported.
 
-Integration with the CocoaPods dependency manager is also supported with the same limitation – you cannot use pure Swift
-pods.
+To handle iOS dependencies in Kotlin Multiplatform projects, you can manage them with the [cinterop tool](#with-cinterop)
+or use the [CocoaPods dependency manager](#with-cocoapods) (pure Swift pods are not supported).
 
-We recommend [using CocoaPods](#with-cocoapods) to handle iOS dependencies in Kotlin Multiplatform projects.
-[Manage dependencies manually](#without-cocoapods) only if you want to tune the interop process specifically or if you
-have some other strong reason to do so.
+### With cinterop
 
-### With CocoaPods
-
-1. Perform [initial CocoaPods integration setup](native-cocoapods.md#set-up-an-environment-to-work-with-cocoapods).
-2. Add a dependency on a Pod library from the CocoaPods repository that you want to use by including the `pod()`
-   function call in `build.gradle(.kts)`  of your project.
-
-    <tabs group="build-script">
-    <tab title="Kotlin" group-key="kotlin">
-
-    ```kotlin
-    kotlin {
-        cocoapods {
-            version = "2.0"
-            //..
-            pod("SDWebImage") {
-                version = "5.20.0"
-            }
-        }
-    }
-    ```
-
-    </tab>
-    <tab title="Groovy" group-key="groovy">
-
-    ```groovy
-    kotlin {
-        cocoapods {
-            version = '2.0'
-            //..
-            pod('SDWebImage') {
-                version = '5.20.0'
-            }
-        }
-    }
-    ```
-
-    </tab>
-    </tabs>
-
-   You can add the following dependencies on a Pod library:
-    * [From the CocoaPods repository](native-cocoapods-libraries.md#from-the-cocoapods-repository)
-    * [On a locally stored library](native-cocoapods-libraries.md#on-a-locally-stored-library)
-    * [From a custom Git repository](native-cocoapods-libraries.md#from-a-custom-git-repository)
-    * [From a custom Podspec repository](native-cocoapods-libraries.md#from-a-custom-podspec-repository)
-    * [With custom cinterop options](native-cocoapods-libraries.md#with-custom-cinterop-options)
-
-3. Run **Reload All Gradle Projects** in IntelliJ IDEA (or **Sync Project with Gradle Files** in Android Studio)
-   to re-import the project.
-
-To use the dependency in your Kotlin code, import the package `cocoapods.<library-name>`. For the example above, it's:
-
-```kotlin
-import cocoapods.SDWebImage.*
-```
-
-### Without CocoaPods
-
-If you don't want to use CocoaPods, you can use the cinterop tool to create Kotlin bindings for Objective-C or Swift
+You can use the cinterop tool to create Kotlin bindings for Objective-C or Swift
 declarations. This will allow you to call them from the Kotlin code.
 
-The steps differ a bit for [libraries](#add-a-library-without-cocoapods)
-and [frameworks](#add-a-framework-without-cocoapods), but the idea remains the same.
+The steps differ a bit for [libraries](#add-a-library) and [frameworks](#add-a-framework),
+but the general workflow looks like this:
 
 1. Download your dependency.
 2. Build it to get its binaries.
-3. Create a special `.def` file that describes this dependency to cinterop.
+3. Create a special `.def` [definition file](native-definition-file.md) that describes this dependency to cinterop.
 4. Adjust your build script to generate bindings during the build.
 
-#### Add a library without CocoaPods
+#### Add a library
 
 1. Download the library source code and place it somewhere where you can reference it from your project.
-
 2. Build a library (library authors usually provide a guide on how to do this) and get a path to the binaries.
-
 3. In your project, create a `.def` file, for example `DateTools.def`.
-
 4. Add a first string to this file: `language = Objective-C`. If you want to use a pure C dependency, omit the language
    property.
-
 5. Provide values for two mandatory properties:
+
     * `headers` describes which headers will be processed by cinterop.
     * `package` sets the name of the package these declarations should be put into.
 
    For example:
+
     ```none
     headers = DateTools.h
     package = DateTools
     ```
 
 6. Add information about interoperability with this library to the build script:
+
     * Pass the path to the `.def` file. This path can be omitted if your `.def` file has the same name as cinterop and
       is placed in the `src/nativeInterop/cinterop/` directory.
     * Tell cinterop where to look for header files using the `includeDirs` option.
@@ -173,18 +113,15 @@ property in the `.def` file. For the example above, this will be:
 import DateTools.*
 ```
 
-#### Add a framework without CocoaPods
+#### Add a framework
 
 1. Download the framework source code and place it somewhere that you can reference it from your project.
-
 2. Build the framework (framework authors usually provide a guide on how to do this) and get a path to the binaries.
-
 3. In your project, create a `.def` file, for example `MyFramework.def`.
-
 4. Add the first string to this file: `language = Objective-C`. If you want to use a pure C dependency, omit the
    language property.
-
 5. Provide values for these two mandatory properties:
+
     * `modules` – the name of the framework that should be processed by the cinterop.
     * `package` – the name of the package these declarations should be put into.
 
@@ -196,6 +133,7 @@ import DateTools.*
     ```
 
 6. Add information about interoperability with the framework to the build script:
+
     * Pass the path to the .def file. This path can be omitted if your `.def` file has the same name as the cinterop and
       is placed in the `src/nativeInterop/cinterop/` directory.
     * Pass the framework name to the compiler and linker using the `-framework` option. Pass the path to the framework
@@ -266,10 +204,66 @@ import MyFramework.*
 Learn more about [Objective-C and Swift interop](native-objc-interop.md) and
 [configuring cinterop from Gradle](multiplatform-dsl-reference.md#cinterops).
 
+### With CocoaPods
+
+1. Perform [initial CocoaPods integration setup](native-cocoapods.md#set-up-an-environment-to-work-with-cocoapods).
+2. Add a dependency on a Pod library from the CocoaPods repository that you want to use by including the `pod()`
+   function call in `build.gradle(.kts)` of your project.
+
+    <tabs group="build-script">
+    <tab title="Kotlin" group-key="kotlin">
+
+    ```kotlin
+    kotlin {
+        cocoapods {
+            version = "2.0"
+            //..
+            pod("SDWebImage") {
+                version = "5.20.0"
+            }
+        }
+    }
+    ```
+
+    </tab>
+    <tab title="Groovy" group-key="groovy">
+
+    ```groovy
+    kotlin {
+        cocoapods {
+            version = '2.0'
+            //..
+            pod('SDWebImage') {
+                version = '5.20.0'
+            }
+        }
+    }
+    ```
+
+    </tab>
+    </tabs>
+
+   You can add the following dependencies on a Pod library:
+
+   * [From the CocoaPods repository](native-cocoapods-libraries.md#from-the-cocoapods-repository)
+   * [On a locally stored library](native-cocoapods-libraries.md#on-a-locally-stored-library)
+   * [From a custom Git repository](native-cocoapods-libraries.md#from-a-custom-git-repository)
+   * [From a custom Podspec repository](native-cocoapods-libraries.md#from-a-custom-podspec-repository)
+   * [With custom cinterop options](native-cocoapods-libraries.md#with-custom-cinterop-options)
+
+3. Run **Reload All Gradle Projects** in IntelliJ IDEA (or **Sync Project with Gradle Files** in Android Studio)
+   to re-import the project.
+
+To use the dependency in your Kotlin code, import the package `cocoapods.<library-name>`. For the example above, it's:
+
+```kotlin
+import cocoapods.SDWebImage.*
+```
+
 ## What's next?
 
 Check out other resources on adding dependencies in multiplatform projects and learn more about:
 
-* [Connecting platform-specific libraries](multiplatform-share-on-platforms.md#connect-platform-specific-libraries)
+* [Connecting platform libraries](native-platform-libs.md)
 * [Adding dependencies on multiplatform libraries or other multiplatform projects](multiplatform-add-dependencies.md)
 * [Adding Android dependencies](multiplatform-android-dependencies.md)

docs/topics/multiplatform/multiplatform-spm-local-integration.md

@@ -43,7 +43,7 @@ The tutorial assumes that your project is using [direct integration](multiplatfo
 approach with the `embedAndSignAppleFrameworkForXcode` task in the project's build phase. If you're connecting a Kotlin
 framework through CocoaPods plugin or through Swift package with `binaryTarget`, migrate first.
 
-### Migrate from SPM binaryTarget integration to local direct integration {initial-collapse-state="collapsed" collapsible="true"}
+### Migrate from SPM binaryTarget integration {initial-collapse-state="collapsed" collapsible="true"}
 
 To migrate from the SPM integration with `binaryTarget`:
 
@@ -52,7 +52,7 @@ To migrate from the SPM integration with `binaryTarget`:
 2. In every `Package.swift` file, remove both dependencies to the package with a Kotlin framework inside and target
    dependencies to the products.
 
-### Migrate from CocoaPods plugin to direct integration {initial-collapse-state="collapsed" collapsible="true"}
+### Migrate from the CocoaPods plugin {initial-collapse-state="collapsed" collapsible="true"}
 
 > If you have dependencies on other Pods in the `cocoapods {}` block, you have to resort to the CocoaPods integration approach.
 > Currently, it's impossible to both have dependencies on Pods and on the Kotlin framework in a multimodal SPM project. 
@@ -81,7 +81,7 @@ To migrate from the CocoaPods plugin:
 To be able to use Kotlin code in a local Swift package, connect the Kotlin framework generated from the multiplatform
 project to your Xcode project:
 
-1. In Xcode, go to **Product** | **Scheme** | **Edit scheme** or click the schemes icon in the top bar and select **Edit scheme**:
+1. In Xcode, go to **Product** | **Scheme** | **Edit scheme** or click the scheme icon in the top bar and select **Edit scheme**:
 
    ![Edit scheme](xcode-edit-schemes.png){width=700}
 
@@ -103,7 +103,9 @@ project to your Xcode project:
 
    ![Filled run script action](xcode-filled-run-script-action.png){width=700}
 
-5. You can now import the shared module into your local Swift package and use Kotlin code. For example, define the following function:
+5. You can now import the shared module into your local Swift package and use Kotlin code.
+
+   In Xcode, navigate to your local Swift package and define a function with a module import, for example:
 
    ```Swift
    import Shared

docs/topics/multiplatform/native-spm.md

@@ -112,8 +112,6 @@ To set up the publishing of an XCFramework:
    
    `swift package compute-checksum Shared.xcframework.zip`
 
-<anchor name="upload"/>
-
 2. Upload the ZIP file to the file storage of your choice. The file should be accessible
    by a direct link. For example, here's how you can do it using releases in GitHub:
    
@@ -295,8 +293,9 @@ For example, you have a `network` and a `database` module, which you combine in
     ./gradlew :together:assembleTogetherReleaseXCFramework
     ```
 
-5. Follow steps 4–7 from [the previous section](#upload) for `together.xcframework`: archive, calculate the checksum,
-   upload the archived XCFramework, create and push a `Package.swift` file.
+5. Follow the steps from the [previous section](#prepare-the-xcframework-and-the-swift-package-manifest) to prepare
+   `together.xcframework`: archive it, calculate the checksum, upload the archived XCFramework to the file storage,
+   create and push a `Package.swift` file.
 
 Now, you can import the dependency into an Xcode project. After adding the `import together` directive,
 you should have classes from both the `network` and `database` modules available for import in Swift code.