How to build iOS .app binaries for Flutter apps (#2956)

* How to build iOS .app binaries for Flutter apps * Typo fix * Add information how to create .app when using Workflow Editor * Update content/partials/app-preview-builds.md Co-authored-by: helinanever <[email protected]> * Update content/partials/app-preview-builds.md Co-authored-by: helinanever <[email protected]> * Update content/partials/app-preview-builds.md Co-authored-by: helinanever <[email protected]> * Update content/partials/app-preview-builds.md Co-authored-by: helinanever <[email protected]> --------- Co-authored-by: helinanever <[email protected]>
codemagic-ci-cd · Feb 4, 2025 · 845c56a · 845c56a
1 parent 2926c84
commit 845c56a
Showing 1 changed file with 84 additions and 0 deletions.
diff --git a/content/partials/app-preview-builds.md b/content/partials/app-preview-builds.md
@@ -7,6 +7,90 @@ Codemagic allows you to preview your `.app` artifact on an iOS simulator and int
 Note that this feature is available for **teams** on request. Please [contact us](https://codemagic.io/contact/) for more information.
 {{</notebox>}}
 
+## Using Workflow Editor to create iOS .app binaries for testing
+
+In the 'Build' section of the Workflow Editor, set the 'Mode' to debug. In the 'Build arguments' field, add `--simulator` next to the iOS '--debug' section.
+
+## Creating iOS .app binaries for testing with codemagic.yaml
+
+To create a `.app` to run on the iOS simulator, consult the **codemagic.yaml** samples below.
+
+You should make sure that the following values in the `-destination` string correspond with the macOS instance you are using:
+
+- `name` corresponds with one of the devices available on the macOS instance being used.
+- `OS` matches the iOS runtime available on the macOS instance being used.
+
+You can find the macOS specifications that list the available iOS devices and runtimes [here](https://docs.codemagic.io/specs-macos/xcode-16-2/#:~:text=Software%20and%20hardware-,macOS%20machines,-Xcode%2016.2.x).
+
+{{< tabpane >}}
+{{< tab header="Flutter" >}}
+{{<markdown>}}
+Sample **codemagic.yaml** for building an iOS `.app` binary for Flutter projects.
+
+{{< highlight yaml "style=paraiso-dark">}}
+workflows:
+  flutter-ios-simulator:
+    name: Flutter iOS Simulator
+    environment:
+      flutter: 3.27.3
+      xcode: 16.2
+    scripts:
+      - name: install dependencies
+        script: flutter pub get
+      - name: Build unsigned .app
+        script: |  
+          xcodebuild -workspace "ios/Runner.xcworkspace" \
+            -scheme "Runner" \
+            -sdk iphonesimulator \
+            -destination 'platform=iOS Simulator,name=iPhone 16,OS=18.2' \
+            -configuration Debug \
+            CODE_SIGN_IDENTITY="" \
+            CODE_SIGNING_REQUIRED=NO \
+            CODE_SIGNING_ALLOWED=NO \
+            -derivedDataPath ios/output
+    artifacts:
+      - ios/output/Build/Products/Debug-iphonesimulator/Runner.app
+{{< /highlight >}}
+
+{{</markdown>}}
+{{< /tab >}}
+
+
+{{< tab header="Flutter (Flavors)" >}}
+{{<markdown>}}
+
+If you are using Flutter flavors and want to preview a specific flavor, make sure that you set the correct value for your flavor's `-scheme` and set the entry point for your flavor using `FLUTTER_TARGET`. 
+
+{{< highlight yaml "style=paraiso-dark">}}
+workflows:
+  flutter-flavor-ios-simulator:
+    name: Flutter Flavor iOS Simulator
+    environment:
+      flutter: 3.27.3
+      xcode: 16.2
+      cocoapods: default
+    scripts:
+      - name: install dependencies
+        script: flutter pub get
+      - name: Build unsigned .app
+        script: |  
+          xcodebuild -workspace "ios/Runner.xcworkspace" \
+            -scheme "Runner-dev" \ 
+            -sdk iphonesimulator \
+            -destination 'platform=iOS Simulator,name=iPhone 16,OS=18.2' \
+            -configuration Debug \
+            CODE_SIGN_IDENTITY="" \
+            CODE_SIGNING_REQUIRED=NO \
+            CODE_SIGNING_ALLOWED=NO \
+            FLUTTER_TARGET=lib/main_dev.dart \
+            -derivedDataPath ios/output
+    artifacts:
+      - ios/output/Build/Products/Debug-iphonesimulator/Runner.app
+{{< /highlight >}}
+{{</markdown>}}
+{{< /tab >}}
+{{< /tabpane >}}
+
 ## Running preview builds
 
 You can preview any `.app` artifact built in Codemagic that targets the `iPhoneSimulator`. For such artifacts, there is a **Quick Launch** button available next to the artifact name on the build overview page.