[google_maps_flutter] Add examples for different iOS versions (#3757)

Improves the way we specify and test the `GoogleMaps` SDK dependency on iOS. Currently as discussed in flutter/flutter#86820, we are allowing any version of the SDK, and CocoaPods will choose the best version that's compatible with the minimum iOS deployment version of the plugin client's app. However, clients are also subject to future breakage, since any new major SDK version could have compile-time incompatibility with the plugin's wrapping code. We also have no ability to test anything in CI that's newer than the SDK that supports our oldest supported version (currently that's iOS 11, and thus 5.x).

This makes two changes:
- Replaces the single example with N examples, each with a different minimum iOS version, corresponding to each point where the Google Maps SDK has bumped its minimum iOS requirement. Currently (as documented in the new README file)
  - The oldest example has all of the current testing.
  - The newest example has just XCTests (not integration or XCUITests).
  - Intervening examples have no tests.
- Instead of the completely unpinned version, we allow anything up to the next major version (which should be the first one with breaking API changes).

This gives us build coverage of each of the (latest at CI runtime) resolve points that clients can have. We retain the flexibility of allowing clients to get the best version that meets their app's constraints, except that we will need to explicitly test and enable new major versions, so that they won't randomly break clients.

Fixes flutter/flutter#86820

packages/google_maps_flutter/google_maps_flutter_ios/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.2.2
+
+* Sets an upper bound on the `GoogleMaps` SDK version that can be used, to
+  avoid future breakage.
+
 ## 2.2.1
 
 * Clarifies explanation of endorsement in README.

packages/google_maps_flutter/google_maps_flutter_ios/example/README.md

@@ -1,9 +1,46 @@
-# Platform Implementation Test App
+# Platform Implementation Test Apps
 
-This is a test app for manual testing and automated integration testing
-of this platform implementation. It is not intended to demonstrate actual use of
-this package, since the intent is that plugin clients use the app-facing
-package.
+These are test apps for manual testing and automated integration testing
+of this platform implementation. They are not intended to demonstrate actual
+use of this package, since the intent is that plugin clients use the
+app-facing package.
 
-Unless you are making changes to this implementation package, this example is
-very unlikely to be relevant.
+Unless you are making changes to this implementation package, these examples
+are very unlikely to be relevant.
+
+## Structure
+
+This package contains multiple exmaples, which are used to test different
+versions of the Google Maps iOS SDK. Because the plugin's dependency
+is loosely pinned, CocoaPods will pick the newest version that supports the
+minimum targetted OS version of the application using the plugin. In
+order to ensure that the plugin continues to compile against all
+SDK versions that could resolve, there are multiple largely identical
+examples, each with a different minimum target iOS version.
+
+In order to avoid wasting CI resources, tests are mostly not duplicated.
+The test structure is:
+* The oldest version has all of the usual tests (Dart integration,
+  XCTest, XCUITest).
+* The newest version has only XCTests (the cheapest tests), which
+  can be used to unit tests any code paths that are specific to
+  new SDKs (e.g., behind target OS `#if` checks).
+
+This setup is based on the assumption (based on experience so far) that
+the changes in the SDK are unlikely to break functionality at runtime,
+but that we will want to have unit test coverage of new-SDK-only code.
+New test types can be added to any example if needs change.
+
+## Updating Examples
+
+* When a new major of the SDK comes out that raises the minimum
+  iOS deployment version, a new example with that minimum target
+  should be added to ensure that the plugin compiles with that
+  version of the SDK, and the range in the plugin's `podspec` file
+  should be bumped to the next major version.
+* When the minimum supported version of Flutter (on `stable`)
+  reaches the point where the oldest example is for an SDK
+  that can no longer be resolved to, that example should be
+  removed, and all of its testing (Dart integration tests,
+  native unit tests, native UI tests) should be folded into
+  the next-oldest version.

packages/google_maps_flutter/google_maps_flutter_ios/example/ios11/README.md

@@ -0,0 +1,13 @@
+# Platform Implementation Test App
+
+This is a test app for manual testing and automated integration testing
+of this platform implementation. It is not intended to demonstrate actual use of
+this package, since the intent is that plugin clients use the app-facing
+package.
+
+Unless you are making changes to this implementation package, this example is
+very unlikely to be relevant.
+
+## Versions
+
+This example requires iOS 11, so will select a 5.x GoogleMaps SDK version.

packages/google_maps_flutter/google_maps_flutter_ios/example/integration_test/google_maps_test.dart → packages/google_maps_flutter/google_maps_flutter_ios/example/ios11/integration_test/google_maps_test.dart

@@ -8,9 +8,9 @@ import 'dart:ui' as ui;
 
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
-import 'package:google_maps_flutter_example/example_google_map.dart';
 import 'package:google_maps_flutter_platform_interface/google_maps_flutter_platform_interface.dart';
 import 'package:integration_test/integration_test.dart';
+import 'package:maps_example_dart/example_google_map.dart';
 
 const LatLng _kInitialMapCenter = LatLng(0, 0);
 const double _kInitialZoomLevel = 5;

packages/google_maps_flutter/google_maps_flutter_ios/example/ios11/lib/main.dart

@@ -0,0 +1,43 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:maps_example_dart/animate_camera.dart';
+import 'package:maps_example_dart/lite_mode.dart';
+import 'package:maps_example_dart/map_click.dart';
+import 'package:maps_example_dart/map_coordinates.dart';
+import 'package:maps_example_dart/map_ui.dart';
+import 'package:maps_example_dart/maps_demo.dart';
+import 'package:maps_example_dart/marker_icons.dart';
+import 'package:maps_example_dart/move_camera.dart';
+import 'package:maps_example_dart/padding.dart';
+import 'package:maps_example_dart/page.dart';
+import 'package:maps_example_dart/place_circle.dart';
+import 'package:maps_example_dart/place_marker.dart';
+import 'package:maps_example_dart/place_polygon.dart';
+import 'package:maps_example_dart/place_polyline.dart';
+import 'package:maps_example_dart/scrolling_map.dart';
+import 'package:maps_example_dart/snapshot.dart';
+import 'package:maps_example_dart/tile_overlay.dart';
+
+void main() {
+  runApp(const MaterialApp(
+      home: MapsDemo(<GoogleMapExampleAppPage>[
+    MapUiPage(),
+    MapCoordinatesPage(),
+    MapClickPage(),
+    AnimateCameraPage(),
+    MoveCameraPage(),
+    PlaceMarkerPage(),
+    MarkerIconsPage(),
+    ScrollingMapPage(),
+    PlacePolylinePage(),
+    PlacePolygonPage(),
+    PlaceCirclePage(),
+    PaddingPage(),
+    SnapshotPage(),
+    LiteModePage(),
+    TileOverlayPage(),
+  ])));
+}

packages/google_maps_flutter/google_maps_flutter_ios/example/pubspec.yaml → packages/google_maps_flutter/google_maps_flutter_ios/example/ios11/pubspec.yaml

@@ -17,8 +17,10 @@ dependencies:
     # See https://dart.dev/tools/pub/dependencies#version-constraints
     # The example app is bundled with the plugin so we use a path dependency on
     # the parent directory to use the current plugin's version.
-    path: ../
+    path: ../../
   google_maps_flutter_platform_interface: ^2.2.1
+  maps_example_dart:
+    path: ../shared/maps_example_dart/
 
 dev_dependencies:
   flutter_driver:

packages/google_maps_flutter/google_maps_flutter_ios/example/ios12/README.md

@@ -0,0 +1,13 @@
+# Platform Implementation Test App
+
+This is a test app for manual testing and automated integration testing
+of this platform implementation. It is not intended to demonstrate actual use of
+this package, since the intent is that plugin clients use the app-facing
+package.
+
+Unless you are making changes to this implementation package, this example is
+very unlikely to be relevant.
+
+## Versions
+
+This example requires iOS 12, so will select a 6.x GoogleMaps SDK version.

packages/google_maps_flutter/google_maps_flutter_ios/example/ios12/assets/night_mode.json

@@ -0,0 +1,162 @@
+[
+  {
+    "elementType": "geometry",
+    "stylers": [
+      {
+        "color": "#242f3e"
+      }
+    ]
+  },
+  {
+    "elementType": "labels.text.fill",
+    "stylers": [
+      {
+        "color": "#746855"
+      }
+    ]
+  },
+  {
+    "elementType": "labels.text.stroke",
+    "stylers": [
+      {
+        "color": "#242f3e"
+      }
+    ]
+  },
+  {
+    "featureType": "administrative.locality",
+    "elementType": "labels.text.fill",
+    "stylers": [
+      {
+        "color": "#d59563"
+      }
+    ]
+  },
+  {
+    "featureType": "poi",
+    "elementType": "labels.text.fill",
+    "stylers": [
+      {
+        "color": "#d59563"
+      }
+    ]
+  },
+  {
+    "featureType": "poi.park",
+    "elementType": "geometry",
+    "stylers": [
+      {
+        "color": "#263c3f"
+      }
+    ]
+  },
+  {
+    "featureType": "poi.park",
+    "elementType": "labels.text.fill",
+    "stylers": [
+      {
+        "color": "#6b9a76"
+      }
+    ]
+  },
+  {
+    "featureType": "road",
+    "elementType": "geometry",
+    "stylers": [
+      {
+        "color": "#38414e"
+      }
+    ]
+  },
+  {
+    "featureType": "road",
+    "elementType": "geometry.stroke",
+    "stylers": [
+      {
+        "color": "#212a37"
+      }
+    ]
+  },
+  {
+    "featureType": "road",
+    "elementType": "labels.text.fill",
+    "stylers": [
+      {
+        "color": "#9ca5b3"
+      }
+    ]
+  },
+  {
+    "featureType": "road.highway",
+    "elementType": "geometry",
+    "stylers": [
+      {
+        "color": "#746855"
+      }
+    ]
+  },
+  {
+    "featureType": "road.highway",
+    "elementType": "geometry.stroke",
+    "stylers": [
+      {
+        "color": "#1f2835"
+      }
+    ]
+  },
+  {
+    "featureType": "road.highway",
+    "elementType": "labels.text.fill",
+    "stylers": [
+      {
+        "color": "#f3d19c"
+      }
+    ]
+  },
+  {
+    "featureType": "transit",
+    "elementType": "geometry",
+    "stylers": [
+      {
+        "color": "#2f3948"
+      }
+    ]
+  },
+  {
+    "featureType": "transit.station",
+    "elementType": "labels.text.fill",
+    "stylers": [
+      {
+        "color": "#d59563"
+      }
+    ]
+  },
+  {
+    "featureType": "water",
+    "elementType": "geometry",
+    "stylers": [
+      {
+        "color": "#17263c"
+      }
+    ]
+  },
+  {
+    "featureType": "water",
+    "elementType": "labels.text.fill",
+    "stylers": [
+      {
+        "color": "#515c6d"
+      }
+    ]
+  },
+  {
+    "featureType": "water",
+    "elementType": "labels.text.stroke",
+    "stylers": [
+      {
+        "color": "#17263c"
+      }
+    ]
+  }
+]
+

packages/google_maps_flutter/google_maps_flutter_ios/example/ios12/ios/Flutter/AppFrameworkInfo.plist

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleExecutable</key>
+  <string>App</string>
+  <key>CFBundleIdentifier</key>
+  <string>io.flutter.flutter.app</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>App</string>
+  <key>CFBundlePackageType</key>
+  <string>FMWK</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0</string>
+  <key>CFBundleSignature</key>
+  <string>????</string>
+  <key>CFBundleVersion</key>
+  <string>1.0</string>
+  <key>UIRequiredDeviceCapabilities</key>
+  <array>
+    <string>arm64</string>
+  </array>
+  <key>MinimumOSVersion</key>
+  <string>12.0</string>
+</dict>
+</plist>

packages/google_maps_flutter/google_maps_flutter_ios/example/ios12/ios/Flutter/Debug.xcconfig

@@ -0,0 +1,2 @@
+#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig"
+#include "Generated.xcconfig"

packages/google_maps_flutter/google_maps_flutter_ios/example/ios12/ios/Flutter/Release.xcconfig

@@ -0,0 +1,2 @@
+#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.release.xcconfig"
+#include "Generated.xcconfig"

packages/google_maps_flutter/google_maps_flutter_ios/example/ios12/ios/Podfile

@@ -0,0 +1,41 @@
+# Uncomment this line to define a global platform for your project
+platform :ios, '12.0'
+
+# CocoaPods analytics sends network stats synchronously affecting flutter build latency.
+ENV['COCOAPODS_DISABLE_STATS'] = 'true'
+
+project 'Runner', {
+  'Debug' => :debug,
+  'Profile' => :release,
+  'Release' => :release,
+}
+
+def flutter_root
+  generated_xcode_build_settings_path = File.expand_path(File.join('..', 'Flutter', 'Generated.xcconfig'), __FILE__)
+  unless File.exist?(generated_xcode_build_settings_path)
+    raise "#{generated_xcode_build_settings_path} must exist. If you're running pod install manually, make sure flutter pub get is executed first"
+  end
+
+  File.foreach(generated_xcode_build_settings_path) do |line|
+    matches = line.match(/FLUTTER_ROOT\=(.*)/)
+    return matches[1].strip if matches
+  end
+  raise "FLUTTER_ROOT not found in #{generated_xcode_build_settings_path}. Try deleting Generated.xcconfig, then run flutter pub get"
+end
+
+require File.expand_path(File.join('packages', 'flutter_tools', 'bin', 'podhelper'), flutter_root)
+
+flutter_ios_podfile_setup
+
+target 'Runner' do
+  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
+end
+
+post_install do |installer|
+  installer.pods_project.targets.each do |target|
+    flutter_additional_ios_build_settings(target)
+    target.build_configurations.each do |build_configuration|
+      build_configuration.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64 i386'
+    end
+  end
+end