CMake: Add some documentation about archival builds for iOS

docs/CMake API.md

@@ -119,6 +119,30 @@ provisioning profiles, which is achieved by passing the `-allowProvisioningUpdat
 
     cmake --build build-ios --target <targetName> -- -allowProvisioningUpdates
 
+#### Archiving for iOS
+
+CMake's out-of-the-box archiving behaviour doesn't always work as expected, especially for targets
+that depend on static libraries (such as targets added with `juce_add_binary_data`). Xcode may
+generate these libraries into a 'DerivedData' directory, but then omit this directory from the
+library search paths later in the build.
+
+If the "Product -> Archive" action isn't working, the following steps may help correct the issue:
+
+- On your static library, explicitly set the `ARCHIVE_OUTPUT_DIRECTORY` property.
+  ```
+  set_target_properties(my_static_lib_target PROPERTIES ARCHIVE_OUTPUT_DIRECTORY "./")
+  ```
+- Now, the Archive build should complete without linker errors, but the archived product may still
+  be hidden in the Organizer window. To fix this issue, set the following properties on the target
+  representing the actual iOS app. If your target was added with `juce_add_gui_app`, pass the same
+  target name. Otherwise, if your target was added with `juce_add_plugin` you may need to append
+  `_Standalone` to the target name, to specify the standalone plugin target.
+  ```
+  set_target_properties(my_ios_app_target PROPERTIES
+      XCODE_ATTRIBUTE_INSTALL_PATH "$(LOCAL_APPS_DIR)"
+      XCODE_ATTRIBUTE_SKIP_INSTALL "NO")
+  ```
+
 ### Building universal binaries for macOS
 
 Building universal binaries that will run on both arm64 and x86_64 can be achieved by