Contents
  • Create a Flutter module
  • Embed the Flutter module in your existing application
    • Option B - Embed frameworks in Xcode

Flutter can be incrementally added into your existing iOSapplication as embedded frameworks.

Xcode is a complete developer toolset for creating apps for Mac, iPhone, iPad, Apple Watch, and Apple TV. Xcode brings user interface design, coding, testing, debugging, and submitting to the App Store all into a unified workflow. Downloading and updating Xcode. The current release of Xcode is available as a free download from the Mac. Mar 19, 2021 Adversaries have previously resorted to tainted Xcode executables (aka XCodeGhost) to inject malicious code into iOS apps compiled with the infected Xcode without the developers' knowledge, and subsequently use the infected apps to collect information from the devices once they are downloaded and installed from the App Store.

For examples, see the iOS directories in the add_to_app code samples.

System requirements

Your development environment must meet themacOS system requirements for Flutterwith Xcode installed.Flutter supports iOS 8.0 and later.Additionally, you will need CocoaPodsversion 1.10 or later.

Create a Flutter module

To embed Flutter into your existing application,first create a Flutter module.

From the command line, run:

A Flutter module project is created at some/path/my_flutter/.From that directory, you can run the same fluttercommands you would in any other Flutter project,like flutter run --debug or flutter build ios.You can also run the module inAndroid Studio/IntelliJ or VS Code withthe Flutter and Dart plugins. This project contains asingle-view example version of your module before it’sembedded in your existing application,which is useful for incrementallytesting the Flutter-only parts of your code.

Module organization

The my_flutter module directory structure is similar to anormal Flutter application:

Add your Dart code to the lib/ directory.

Add Flutter dependencies to my_flutter/pubspec.yaml,including Flutter packages and plugins.

The .ios/ hidden subfolder contains an Xcode workspace whereyou can run a standalone version of your module.It is a wrapper project to bootstrap your Flutter code,and contains helper scripts to facilitate building frameworks orembedding the module into your existing application with CocoaPods.

Note: Add custom iOS code to your own existing application’s project or to a plugin, not to the module’s .ios/ directory. Changes made in your module’s .ios/ directory do not appear in your existing iOS project using the module, and may be overwritten by Flutter.

Do not source control the .ios/ directory since it’s autogenerated. Before building the module on a new machine, run flutter pub get in the my_flutter directory first to regenerate the .ios/ directory before building iOS project using the Flutter module.

Embed the Flutter module in your existing application

There are two ways to embed Flutter in your existing application.

  1. Use the CocoaPods dependency manager and installed Flutter SDK.(Recommended.)
  2. Create frameworks for the Flutter engine, your compiled Dart code,and all Flutter plugins. Manually embed the frameworks,and update your existing application’s build settings in Xcode.

Note: Your app does not run on a simulator in Release mode because Flutter does not yet support outputting x86/x86_64 ahead-of-time (AOT) binaries for your Dart code. You can run in Debug mode on a simulator or a real device, and Release on a real device.

To run your app on a simulator follow the instructions in the bottom of section embed the frameworks.

Using Flutter increases your app size.

Option A - Embed with CocoaPods and the Flutter SDK

This method requires every developer working on yourproject to have a locally installed version of the Flutter SDK.Simply build your application in Xcode to automaticallyrun the script to embed your Dart and plugin code.This allows rapid iteration with the most up-to-dateversion of your Flutter module without running additionalcommands outside of Xcode.

The following example assumes that your existingapplication and the Flutter module are in siblingdirectories. If you have a different directory structure,you may need to adjust the relative paths.

If your existing application (MyApp) doesn’talready have a Podfile, follow theCocoaPods getting started guideto add a Podfile to your project.

  1. Add the following lines to your Podfile:

  2. For each Podfile target that needs toembed Flutter, call install_all_flutter_pods(flutter_application_path).

  3. Run pod install.

    Note: When you change the Flutter plugin dependencies in my_flutter/pubspec.yaml, run flutter pub get in your Flutter module directory to refresh the list of plugins read by the podhelper.rb script. Then, run pod install again from your application at some/path/MyApp.

Xcode App Installation Failed The Argument Is Invalid

The podhelper.rb script embeds your plugins,Flutter.framework, and App.framework into your project.

Your app’s Debug and Release build configurations embedthe Debug or Release build modes of Flutter, respectively.Add a Profile build configurationto your app to test in profile mode.

Tip:Flutter.framework is the bundle for the Flutter engine, and App.framework is the compiled Dart code for this project.

Open MyApp.xcworkspace in Xcode.You can now build the project using ⌘B.

Option B - Embed frameworks in Xcode

Alternatively, you can generate the necessary frameworksand embed them in your application by manually editingyour existing Xcode project. You may do this if members of yourteam can’t locally install Flutter SDK and CocoaPods,or if you don’t want to use CocoaPodsas a dependency manager in your existing applications.You must run flutter build ios-frameworkevery time you make code changes in your Flutter module.

If you’re using the previousEmbed with CocoaPods and Flutter tools method,you can skip these instructions.

The following example assumes that you want to generate theframeworks to some/path/MyApp/Flutter/.

Warning: Always use Flutter.xcframework and App.xcframework from the same directory. Mixing .xcframework imports from different directories (such as Profile/Flutter.xcframework with Debug/App.xcframework) causes runtime crashes.

Embed and link the generated frameworks into your existingapplication in Xcode. There are multiple ways to dothis—use the method that is best for your project.

Link on the frameworks

For example, you can drag the frameworks fromsome/path/MyApp/Flutter/Release/ in Finderinto your target’s BuildSettings > Build Phases > Link Binary With Libraries.

In the target’s build settings, add $(PROJECT_DIR)/Flutter/Release/to the Framework Search Paths (FRAMEWORK_SEARCH_PATHS).

Embed the frameworks

The generated dynamic frameworks must be embeddedinto your app to be loaded at runtime.

Important: Plugins might produce static or dynamic frameworks. Static frameworks should be linked on, but never embedded. If you embed a static framework into your application, your application is not publishable to the App Store and fails with a Found an unexpected Mach-O header code archive error.

For example, you can drag the framework(except for FlutterPluginRegistrant and any otherstatic frameworks) from your application’s Frameworks groupinto your target’s Build Settings > Build Phases >Embed Frameworks.Then, select Embed & Sign from the drop-down list.

You should now be able to build the project in Xcode using ⌘B.

Tip: To embed the Debug version of the Flutter frameworks in your Debug build configuration and the Release version in your Release configuration, in your MyApp.xcodeproj/project.pbxproj, try replacing path = Flutter/Release/example.xcframework; with path = 'Flutter/$(CONFIGURATION)/example.xcframework'; for all added frameworks. (Note the added '.)

You must also add $(PROJECT_DIR)/Flutter/$(CONFIGURATION) to the Framework Search Paths (FRAMEWORK_SEARCH_PATHS) build setting.

Option C - Embed application and plugin frameworks in Xcode and Flutter framework with CocoaPods

Alternatively, instead of distributing the large Flutter.xcframeworkto other developers, machines, or continuous integration systems,you can instead generate Flutter as CocoaPods podspec by addingthe flag --cocoapods. This produces a Flutter.podspecinstead of an engine Flutter.xcframework.The App.xcframework and plugin frameworks are generatedas described in Option B.

Host apps using CocoaPods can add Flutter to their Podfile:

Embed and link the generated App.xcframework,FlutterPluginRegistrant.xcframework,and any plugin frameworks into your existing applicationas described in Option B.

Local Network Privacy Permissions

On iOS 14 and higher, enable the Dart multicast DNSservice in the Debug version of your appto add debugging functionalities such as hot-reload andDevTools via flutter attach.

Warning: This service must not be enabled in the Release version of your app, or you may experience App Store rejections.

One way to do this is to maintain a separate copy of your app’s Info.plist perbuild configuration. The following instructions assumethe default Debug and Release.Adjust the names as needed depending on your app’s build configurations.

  1. Rename your app’s Info.plist to Info-Debug.plist.Make a copy of it called Info-Release.plist and add it to your Xcode project.

  2. In Info-Debug.plistonly add the key NSBonjourServicesand set the value to an array with the string _dartobservatory._tcp.Note Xcode will display this as “Bonjour services”.

    Optionally, add the key NSLocalNetworkUsageDescription set to yourdesired customized permission dialog text.

  3. In your target’s build settings, change the Info.plist File(INFOPLIST_FILE) setting path from path/to/Info.plist to path/to/Info-$(CONFIGURATION).plist.

    This will resolve to the path Info-Debug.plist in Debug andInfo-Release.plist in Release.

    Alternatively, you can explicitly set the Debug path to Info-Debug.plistand the Release path to Info-Release.plist.

  4. If the Info-Release.plist copy is in your target’s Build Settings > Build Phases > Copy BundleResources build phase, remove it.

    The first Flutter screen loaded by your Debug app will now promptfor local network permission. The permission can also be allowed by enablingSettings > Privacy > Local Network > Your App.

App

Apple Silicon (arm64 Macs)

Flutter does not yet support arm64 iOS simulators. To run your host app on an Apple SiliconMac, exclude arm64 from the simulator architectures.

In your host app target, find the Excluded Architectures (EXCLUDED_ARCHS) build setting.Click the right arrow disclosure indicator icon to expand the available build configurations.Hover over Debug and click the plus icon. Change Any SDK to Any iOS Simulator SDK.Add arm64 to the build settings value.

When done correctly, Xcode will add 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' = arm64; to your project.pbxproj file.

Xcode Install App On Apple Watch

Repeat for any iOS unit test targets.

Development

Xcode App Install Mac

You can now add a Flutter screen to your existing application.