Update iOS add-to-app project setup instructions by jmagman · Pull Request #3317 · flutter/website

jmagman · 2019-11-28T01:30:21Z

jmagman · 2019-11-28T01:30:43Z

I need to figure out how to deploy this to see how it looks.

xster · 2019-11-28T03:43:41Z

+You can also run in [Android Studio/IntelliJ][] or [VS Code][] with the Flutter and Dart plugins.
+This will run a single-view example version of your module without being
+embedded in your existing application. This can be useful for testing
+quick, incremental changes with hot reload.


this makes it sound like you can't hot reload if you embedded into your existing app

xster · 2019-11-28T03:43:51Z

+in any other Flutter project, like `flutter run --debug` or `flutter build ios`.
+You can also run in [Android Studio/IntelliJ][] or [VS Code][] with the Flutter and Dart plugins.
+This will run a single-view example version of your module without being
+embedded in your existing application. This can be useful for testing


testing flutter only parts

xster · 2019-11-28T03:44:38Z

+
+There is a `.ios/` hidden subfolder which contains a Xcode workspace where you can 
+run a stand-alone version of your module. It also contains helper scripts to embed
+the module into your existing application with [CocoaPods][].


or build frameworks from

xster · 2019-11-28T03:46:41Z

+{{site.alert.note}}
+Custom iOS code should be added to your existing application or a plugin, not
+the module in `.ios/`. Changes made in `.ios/` will not be embedded in your existing application.
+The directory can be regenerated by running `flutter clean` in the `my_flutter` directory.


Doesn't everything get overwritten too each time flutter packages get is run too? flutter/flutter#28135

That too flutter/flutter#42956.

xster · 2019-11-28T03:51:02Z

+CocoaPods as a vendored framework. This has to match up with the release type
+(debug/profile/release) as well as the architecture for your app (arm*, 
+x86_64, etc.).
+- `App.framework` (your Flutter application binary) is being embedded into your


The Flutter framework is in there too

Can you use "*" to indicate a bulleted list, rather than minus? (I know this was there before...)

Also, I am not sure what the point of this section is. It seems like it's there to just tell the user what's going on, but you've deleted the introductory sentence explaining that it's there just to let you know what's going on. Can you add that back (or something similar)?

I don't know if it's useful, the contents are almost untouched from what was there before. I'm happy to remove the entire section if you don't think it's useful. I removed the intro because I didn't want to imply anything would go wrong following these steps.

xster · 2019-11-28T03:51:30Z

-with the Dart code that's actually in the folder.  It also uses your Xcode build configuration (Debug, Profile, Release) to embed the matching
-release type of `Flutter.framework` and `App.framework`.
+- `Flutter.framework` (the Engine library) is being embedded into your application by
+CocoaPods as a vendored framework. This has to match up with the release type


This has to match sounds like you're telling the user to do something, but not what or how

Also, can you make this sentence more active? ->
"CocoaPods embeds the engine library (Flutter.framework) into your app as a vendored framework.

xster · 2019-11-28T03:52:27Z

+If you are using the above [Embed with CocoaPods and Flutter tools](#embed-with-CocoaPods-and-Flutter-tools)
+method, you can skip these instructions.
+
+Let's assume you want to generate the frameworks to `some/path/MyApp/Flutter/`.


Had to double take to realize that this is a future path you want to put things into

sfshaza2 · 2019-12-02T06:42:40Z

 ---

-TODO(jmagman): add the pre-built framework alternative and review.
+Flutter can be embedded into your existing iOS application in a piecemeal fashion as


I'd probably delete "in a piecemeal fashion", which might confuse some. Also, I'd change "as frameworks or libraries" to "as a framework or library." But, I have to ask, does it really make sense to add a "Flutter framework" to an iOS app? Finally, I'd change the passive voice to active. So:

"You can embed a Flutter library into your existing iOS application."

does it really make sense to add a "Flutter framework" to an iOS app

Yup, that's the feature! The user has an existing Flutter-free iOS app, and they want to add Flutter bits to it without migrating to Flutter wholesale or starting over as a Flutter app. These bits are generated as "libraries" or "frameworks" (Apple's wording, not ours) and then embedded into the existing iOS app.

I'd probably delete "in a piecemeal fashion", which might confuse some

Sounds good, though I copied this from https://github.com/flutter/website/blob/staging-add-to-app-do-not-delete-until-2020/src/docs/development/add-to-app/index.md

sfshaza2 · 2019-12-02T06:43:34Z

+## Create a Flutter module

-To integrate a Flutter module into your app, use the following steps:
+In order to embed Flutter into your existing application, first create a Flutter module.


Delete "in order". -> "To embed Flutter..."

sfshaza2 · 2019-12-02T06:45:12Z

-In order to embed Flutter as a library, use the Flutter module template.
-Executing `flutter create -t module xxx` produces a Flutter project with a
-CocoaPods pod designed for consumption by your existing host app.
+In that directory you can run the same `flutter` commands you would


Which directory is "that directory"? Do you mean the top of the project? It's not clear to me.

some/path/my_flutter/ from the previous sentence. I'll combine.

sfshaza2 · 2019-12-02T06:46:14Z

+In that directory you can run the same `flutter` commands you would
+in any other Flutter project, like `flutter run --debug` or `flutter build ios`.
+You can also run in [Android Studio/IntelliJ][] or [VS Code][] with the Flutter and Dart plugins.
+This will run a single-view example version of your module without being


Avoid future tense. "This will run..." -> "This runs..."

sfshaza2 · 2019-12-02T06:48:45Z

-CocoaPods pod designed for consumption by your existing host app.
+In that directory you can run the same `flutter` commands you would
+in any other Flutter project, like `flutter run --debug` or `flutter build ios`.
+You can also run in [Android Studio/IntelliJ][] or [VS Code][] with the Flutter and Dart plugins.


So, are they running the iOS app from AS/IntelliJ, VS Code?

The only way to run normal iOS apps is from Xcode, but you can run the Flutter module part from any Flutter IDEs.

sfshaza2 · 2019-12-02T07:08:09Z

+(debug/profile/release) as well as the architecture for your app (arm*, 
+x86_64, etc.).
+- `App.framework` (your Flutter application binary) is being embedded into your
+application by CocoaPods as a vendored framework.


Ditto (make the sentence more active): ->
Cocoapods embeds your Flutter application binary (App.framework) into your app as a vendored framework.

sfshaza2 · 2019-12-02T07:10:18Z

+x86_64, etc.).
+- `App.framework` (your Flutter application binary) is being embedded into your
+application by CocoaPods as a vendored framework.
+- Flutter plugins with iOS platform code are added as CocoaPod pods.


Is this accurate? (I'm trying to make it more active): ->
CocoaPods adds the Flutter plugins with iOS platform code.

sfshaza2 · 2019-12-02T07:12:29Z

+- A build script is added to the Podfile targets that call `install_all_flutter_pods`
+to ensure that the binaries you build stay up to date with the Dart code in
+the Flutter module.  It also uses your Xcode build configuration (Debug, Profile, Release)
+to embed the matching build mode type of `Flutter.framework` and `App.framework`.


Accurate?
The framework adds a build script to each Podfile target that calls install_all_flutter_pods.
This ensures that the binary stays up to date with the Dart code in the Flutter module.

sfshaza2 · 2019-12-02T07:14:48Z

+You should now be able to build the project using `⌘B`.
+
+### Under the hood
+- The frameworks are added to the target's Link Binary with Libraries and Embed Frameworks


So much passive voice! And non-asterisk bullets. It would be nice if all items in this list used active voice, as well.

I removed the "Under the hood" sections.

xster

LGTM. Thanks!

xster · 2019-12-03T18:46:19Z

+### Embed frameworks in Xcode
+
+Alternatively, you can generate the necessary frameworks and embed them in your application
+by manually editing your existing Xcode project.


Add a sentence for why you might want to do this

sfshaza2

I'd like to get this into the hands of my editor, so LGTM.

xster · 2019-12-04T01:27:45Z

+
+### Embed with CocoaPods and the Flutter SDK
+
+This method requires every developer working on your project to have a locally installed


Add some pros and cons. e.g. you can just click run in xcode and not have to build 2 things when you're rapidly iterating.

xster · 2019-12-04T01:28:58Z

 of plugins read by the `podhelper.rb` script. Then run `pod install` again from
-`some/path/MyApp`.
+in your application at`some/path/MyApp`.
+{{site.alert.end}}


Do you have to do this if you flutter upgrade or flutter channel too?

I don't think upgrade or channel would alter anything in .flutter-plugins, but I can add it if you know something I don't.

I'm just guessing. Wouldn't this change the engine framework which gets copied over to your .ios folder if you ran flutter packages get? Don't know if you need a subsequent pod install to make things match.

The right version of the Flutter.framework should get copied the next time they run their app via the xcode_backend script.

xster · 2019-12-04T01:30:23Z

+Alternatively, you can generate the necessary frameworks and embed them in your application
+by manually editing your existing Xcode project. You may choose to do this if members of your
+team cannot locally install Flutter SDK and CocoaPods, or if you do not wish to use CocoaPods
+as a dependency manager in your existing applications.


Mention that the downside is that you have to run flutter build ios-framework each time you change things in Flutter

xster · 2019-12-04T01:31:24Z

+the flags `--xcframework --no-universal`.
+{{site.alert.end}}
+
+Open your existing project in Xcode and drag the frameworks from `some/path/MyApp/Flutter/Release/` in Finder


Say that this is just one arbitrary way of integrating we're using as an example. You don't have to do this and you can integrate in whichever way you prefer.

xster · 2019-12-04T03:04:50Z

-following to integrate with your `my_flutter` app:
+If your existing application (`MyApp`) does not already have a Podfile,  follow the
+[CocoaPods getting started guide][] to add a `Podfile` to your project.



Actually I suspect a non-trivial amount of people might fall into the i-opened-the-xcodeproj-file-instead-of-the-xcworkspace-file and will run into an error. Perhaps spell that out as well.

I mentioned it. Fortunately pod on its own has a better log about using xcworkspace than flutter does, so hopefully they see it.

jmagman requested review from sfshaza2 and xster November 28, 2019 01:30

jmagman self-assigned this Nov 28, 2019

googlebot added the cla: yes Contributor has signed the Contributor License Agreement label Nov 28, 2019

xster reviewed Nov 28, 2019

View reviewed changes

sfshaza2 reviewed Dec 2, 2019

View reviewed changes

jmagman added 3 commits December 2, 2019 13:29

Update iOS add-to-app project setup instructions

1aa37af

Remove extra header

c5fe656

Review edits

3c73cbf

xster reviewed Dec 3, 2019

View reviewed changes

Add system requirements, code-excerpt

d013766

sfshaza2 approved these changes Dec 3, 2019

View reviewed changes

xster reviewed Dec 4, 2019

View reviewed changes

jmagman added 2 commits December 4, 2019 12:30

Review edits

8c406c8

Call out xcworkspace

37b078e

jmagman merged commit cc9280b into flutter:staging-add-to-app-do-not-delete-until-2020 Dec 5, 2019

jmagman deleted the ios-setup branch December 5, 2019 02:06


		### Embed with CocoaPods and the Flutter SDK

		This method requires every developer working on your project to have a locally installed

Uh oh!

Conversation

jmagman commented Nov 28, 2019

Uh oh!

jmagman commented Nov 28, 2019

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xster left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!