From b65d9ad5a1bd2dad5d4afa50fd3f5eb2ec54a39c Mon Sep 17 00:00:00 2001
From: Logan Shire <logan.shire@gmail.com>
Date: Thu, 4 Jul 2024 04:07:07 -0400
Subject: [PATCH] Create faq.md (#1279)

---
 doc/faq.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 doc/faq.md

diff --git a/doc/faq.md b/doc/faq.md
new file mode 100644
index 000000000..50f31fd7d
--- /dev/null
+++ b/doc/faq.md
@@ -0,0 +1,39 @@
+# Frequently Asked Questions
+
+## How can I build a `swift_library` directly for iOS?
+
+By default, `swift_library` will compile code for your host machine (e.g. macOS).
+As a result, you may see compiler errors if you attempt to build a `swift_library`
+which imports iOS system frameworks, such as UIKit or SwiftUI:
+
+```
+error: no such module 'UIKit'
+```
+
+In order to build a `swift_library` for iOS, you have two main options:
+
+1. (Preferred) Build the `swift_library` transitively via an `ios_*` target.
+
+The `ios_*` rules (e.g. `ios_application`, `ios_framework`, `ios_unit_test`, `ios_build_test`, etc.) 
+from **rules_apple** apply a "transition" to their transitive dependencies which
+applies a number of configurations that enable them to build for the target platform.
+
+The benefit to using these rules is that you can share a analysis and build cache with your main application,
+making building targets with a lot of dependencies much faster.
+
+2. Build the `swift_library` directly with a config.
+
+You can alternately create a config to build for the desired platform in your `.bazelrc` file:
+
+```
+build:ios_simulator --platforms=@build_bazel_apple_support//platforms:ios_sim_arm64
+```
+
+And apply it when building:
+
+```
+bazel build //path/to/your/library --config=ios_simulator
+```
+
+The drawback to this approach is that the configs will likely differ between your application
+and swift library, resulting in the caches not being shared.