Add discussion bullet points to README

README.md

@@ -2,38 +2,111 @@
 
 ![master](https://github.com/bazel-ios/rules_ios/workflows/CI-master/badge.svg)
 
-These rules provide some macros and rules that make it easier to build iOS
-application with Bazel. The heavy lifting of compiling, and packaging is
-still done by the existing
- [`objc_library` rule](https://bazel.build/reference/be/objective-c#objc_library)
-in Bazel, and by the
-[`swift_library` rule](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_library)
-available from [rules_swift](https://github.com/bazelbuild/rules_swift).
-
-The goal of rules_ios has always been to allow seamlessly transitioning a set of targets from being built
-in Xcode to being built in bazel, with minimal-to-no code changes.
-In that vein, it acts as glue between the underlying rules (rules_apple and rules_swift and the native objc rules),
-applying defaults that mirror what Xcode does. 
-Additionally, rules_ios comes built-in with extension points that act as a quasi-toolchain,
-allowing users to customize things such as generated modulemaps.
+`rules_ios` is [community developed Bazel rules](https://bazel-ios.github.io/)
+that enable you to do iOS development with Bazel end to end.
 
-Bazel version required by current rules is [here](https://github.com/bazel-ios/rules_ios/blob/master/.bazelversion)
+It seamlessly Bazel builds iOS applications originally written under Xcode with
+minimal-to-no code changes. It often re-uses ideas and code from `rules_swift`
+and `rules_apple` and it isn't tied to untested or unused features. It generates
+Xcode projects that _just work_ and makes using Apple Silicon with Bazel a
+breeze.
 
-**Xcode 12** and above supported, to find the last `SHA` with support for older versions see the list of git tags.
+_Learn more at [bazel-ios.github.io](https://bazel-ios.github.io/)_
 
-## Reference documentation
+### iOS Applications
 
-[Click here](https://github.com/bazel-ios/rules_ios/tree/master/docs)
-for the documentation.
+_it supports all the primitives like apps, extensions, and widgets_
+
+```python
+load("@build_bazel_rules_ios//rules:app.bzl", "ios_application")
+
+ios_application(
+    name = "iOS-App",
+    srcs = glob(["*.swift"]),
+    bundle_id = "com.example.ios-app",
+    minimum_os_version = "12.0",
+    visibility = ["//visibility:public"],
+)
+```
+
+### Xcode project generation
+
+_Bazel optimized Xcode project generation that's tested and works end to end with open source remote execution and caching_
+
+```python
+load("@build_bazel_rules_ios//rules:xcodeproj.bzl", "xcodeproj")
+
+xcodeproj(
+    name = "MyXcode",
+    bazel_path = "bazelisk",
+    deps = [ ":iOS-App"] 
+)
+```
+
+_projects are optimized to build with Bazel and optionally fallback to building with Xcode_
+
+
+### Frameworks
+
+_static frameworks with Xcode semantics - easily port existing apps to Bazel_
+
+```python
+# Builds a static framework
+apple_framework(
+    name = "Static",
+    srcs = glob(["static/*.swift"]),
+    bundle_id = "com.example.b",
+    data = ["Static.txt"],
+    infoplists = ["Info.plist"],
+    platforms = {"ios": "12.0"},
+    deps = ["//tests/ios/frameworks/dynamic/c"],
+)
+```
+
+### Dynamic iOS frameworks
+
+_rules_ios builds frameworks as static or dynamic - just flip
+`link_dynamic`_
+
+```python
+apple_framework(
+    name = "Dynamic",
+    srcs = glob(["dynamic/*.swift"]),
+    bundle_id = "com.example.a",
+    infoplists = ["Info.plist"],
+    link_dynamic = True,
+    platforms = {"ios": "12.0"},
+    deps = [":Static"],
+)
+```
 
-## Quick setup
+### Testing - UI / Unit
 
-Add the following lines to your `WORKSPACE` file. Note that since `rules_swift`
-and `rules_apple` [no longer create
-releases](https://github.com/bazelbuild/rules_swift/pull/335), the versions are
-hardcoded to commit sha's that are known to work. You can see the particular
-commit sha's in
-[`repositories.bzl`](https://github.com/bazel-ios/rules_ios/tree/master/rules/repositories.bzl).
+_easily test iOS applications with Bazel - ui and unit testing rules_
+
+```python
+load("//rules:test.bzl", "ios_unit_test")
+
+ios_unit_test(
+    name = "Unhosted",
+    srcs = ["some.swift"],
+    minimum_os_version = "11.0",
+    deps = [":Dynamic"]
+)
+```
+
+### Apple Silicon ready
+
+- Automatically run legacy deps on Apple Silicon - it _just works_ by running [arm64-to-sim](https://github.com/bogo/arm64-to-sim) and more.
+- Testing mechanisms to easily test in ephemeral VMs
+
+## WORKSPACE setup
+
+Add the following lines to your `WORKSPACE` file.
+
+_It pulls a vetted sha of `rules_apple` and `rules_swift` - you can find the
+versions in
+[`repositories.bzl`](https://github.com/bazel-ios/rules_ios/tree/master/rules/repositories.bzl)._
 
 ```python
 load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
@@ -80,30 +153,21 @@ load(
 protobuf_deps()
 ```
 
-## Examples
+_See the [tests](https://github.com/bazel-ios/rules_ios/tree/master/tests)
+directory for tested use cases.
 
-Minimal example:
+## Special notes about debugging xcode projects
+Debugging does not work in sandbox mode, due to issue [#108](https://github.com/bazel-ios/rules_ios/issues/108). The workaround for now is to disable sandboxing in the .bazelrc file.
 
-```python
-load("@build_bazel_rules_ios//rules:app.bzl", "ios_application")
+## 
 
-ios_application(
-    name = "iOS-App",
-    srcs = glob(["*.m"]),
-    bundle_id = "com.example.ios-app",
-    entitlements = "ios.entitlements",
-    families = [
-        "iphone",
-        "ipad",
-    ],
-    launch_storyboard = "LaunchScreen.storyboard",
-    minimum_os_version = "12.0",
-    visibility = ["//visibility:public"],
-)
-```
 
-See the [tests](https://github.com/bazel-ios/rules_ios/tree/master/tests)
-directory for sample applications.
+Bazel version required by current rules is [here](https://github.com/bazel-ios/rules_ios/blob/master/.bazelversion)
+
+**Xcode 12** and above supported, to find the last `SHA` with support for older versions see the list of git tags.
+
+## Reference documentation
+
+[Click here](https://github.com/bazel-ios/rules_ios/tree/master/docs)
+for the documentation.
 
-## Special notes about debugging xcode projects
-Debugging does not work in sandbox mode, due to issue [#108](https://github.com/bazel-ios/rules_ios/issues/108). The workaround for now is to disable sandboxing in the .bazelrc file.