Update doc targets to work with latest version of stardoc

.bazelrc

@@ -2,10 +2,6 @@
 # TODO: While supporting Bazel 5 we need to keep experimental flag vs using "--enable_bzlmod"
 common --experimental_enable_bzlmod
 
-# We can't create a bzl_library for rules-swift because of its visibility,
-# so circumvent by not using the sandbox
-build --strategy=Stardoc=standalone
-
 # Spawn strategy required for some tests
 build --spawn_strategy=standalone
 

MODULE.bazel

@@ -55,9 +55,9 @@ bazel_dep(
 )
 bazel_dep(
     name = "stardoc",
-    version = "0.6.2",
-    repo_name = "io_bazel_stardoc",
+    version = "0.5.6",
     dev_dependency = True,
+    repo_name = "io_bazel_stardoc",
 )
 
 # Load non-bzlmod dependencies from rules_ios

data/BUILD.bazel

@@ -1,6 +1,17 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
 package(default_visibility = ["//rules/library:__pkg__"])
 
 exports_files(
     ["xcspecs.bzl"],
     visibility = ["//docs:__pkg__"],
 )
+
+bzl_library(
+    name = "xcspecs",
+    srcs = [
+        "xcspec_evals.bzl",
+        "xcspecs.bzl",
+    ],
+    visibility = ["//visibility:public"],
+)

docs/BUILD.bazel

@@ -1,50 +1,48 @@
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
-load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
 package(default_visibility = ["//visibility:private"])
 
-_RULES = [
+# Targets to document.
+# Must have a coressponding `bzl_library` target in `//rules:BUILD.bazel`.
+_DOC_SRCS = [
     "app_clip",
     "app",
-    "apple_patched",
     "extension",
+    "features",
+    "force_load_direct_deps",
     "framework",
     "hmap",
+    "import_middleman",
     "library",
     "plists",
     "precompiled_apple_resource_bundle",
+    "providers",
     "substitute_build_settings",
     "test",
     "transition_support",
+    "vfs_overlay.doc",
+    "xcconfig.doc",
 ]
 
-bzl_library(
-    name = "data",
-    srcs = [
-        "//data:xcspecs.bzl",
-    ],
-    tags = ["manual"],
-    visibility = ["//visibility:private"],
-)
+# Create stardoc targets for each documentation target defined
 
 [
     stardoc(
-        name = "%s-docs" % name,
-        out = "%s_doc.md" % name,
-        input = "//rules:%s.bzl" % name,
-        tags = ["manual"],
-        visibility = ["//:__pkg__"],
-        deps = [
-            ":data",
-            "@build_bazel_rules_apple//apple",
+        name = file + "_doc",
+        out = file + ".gen.md",
+        input = "//rules:%s.bzl" % file,
+        tags = [
+            "no-cache",
+            "no-sandbox",  # https://github.com/bazelbuild/stardoc/issues/112
         ],
+        deps = ["//rules:" + file],
     )
-    for name in _RULES
+    for file in _DOC_SRCS
 ]
 
 filegroup(
     name = "_all_docs",
-    srcs = ["%s-docs" % name for name in _RULES],
+    srcs = ["%s.gen.md" % name for name in _DOC_SRCS],
     tags = ["manual"],
 )
 
@@ -60,7 +58,9 @@ genrule(
 echo "#!/bin/bash" > $(OUTS)
 echo "set -eu" > $(OUTS)
 echo 'function copy() {
-    dest="$${BUILD_WORKSPACE_DIRECTORY}/docs/$$(basename $$1)"
+    src_name=$$(basename "$$1")
+    dest_name=$${src_name%.gen.md}_doc.md # replace '.gen.md' with '_doc.md'
+    dest="$${BUILD_WORKSPACE_DIRECTORY}/docs/$${dest_name}"
     cp "$$1" "$$dest"
     chmod +w "$$dest"
 }' >> $(OUTS)
@@ -71,3 +71,42 @@ done
     executable = 1,
     tags = ["manual"],
 )
+
+# _RULES = [
+#     "app_clip",
+#     "app",
+#     "apple_patched",
+#     "extension",
+#     "framework",
+#     "hmap",
+#     "library",
+#     "plists",
+#     "precompiled_apple_resource_bundle",
+#     "substitute_build_settings",
+#     "test",
+#     "transition_support",
+# ]
+
+# bzl_library(
+#     name = "data",
+#     srcs = [
+#         "//data:xcspecs.bzl",
+#     ],
+#     tags = ["manual"],
+#     visibility = ["//visibility:private"],
+# )
+
+# [
+#     stardoc(
+#         name = "%s-docs" % name,
+#         out = "%s_doc.md" % name,
+#         input = "//rules:%s.bzl" % name,
+#         tags = ["manual"],
+#         visibility = ["//:__pkg__"],
+#         deps = [
+#             ":data",
+#             "@build_bazel_rules_apple//apple",
+#         ],
+#     )
+#     for name in _RULES
+# ]

docs/features_doc.md

@@ -0,0 +1,18 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+Defines features specific to rules_ios
+
+- `apple.virtualize_frameworks`
+  - Virtualize means that swift,clang read from llvm's in-memory file system
+
+- `xcode.compile_with_xcode`
+  - Some of the rules need to work sligntly differently under pure Xcode mode
+
+- `apple.arm64_simulator_use_device_deps`
+  - Use the ARM deps for the simulator - see rules/import_middleman.bzl
+
+- `swift.swift_disable_import_underlying_module`
+  - When set disable passing the `-import-underlying-module` copt to `swift_library` targets
+
+

docs/force_load_direct_deps_doc.md

@@ -0,0 +1,49 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+
+<a id="force_load_direct_deps"></a>
+
+## force_load_direct_deps
+
+<pre>
+force_load_direct_deps(<a href="#force_load_direct_deps-name">name</a>, <a href="#force_load_direct_deps-deps">deps</a>, <a href="#force_load_direct_deps-should_force_load">should_force_load</a>)
+</pre>
+
+
+A rule to link with `-force_load` for direct`deps`
+
+ld has different behavior when loading members of a static library VS objects
+as far as visibility. Under `-dynamic`
+- linked _swift object files_ can have public visibility
+- symbols from _swift static libraries_ are omitted unless used, and not
+visible otherwise
+
+By using `-force_load`, we can load static libraries in the attributes of an
+application's direct depenencies. These args need go at the _front_ of the
+linker invocation otherwise these arguments don't work with lds logic.
+
+Why not put it into `rules_apple`? Ideally it could be, and perhaps consider a
+PR to there .The underlying java rule, `AppleBinary.linkMultiArchBinary`
+places `extraLinkopts` at the end of the linker invocation. At the time of
+writing these args need to go into the current rule context where
+`AppleBinary.linkMultiArchBinary` is called.
+
+One use case of this is that iOS developers want to load above mentioned
+symbols from applications. Another alternate could be to create an aspect,
+that actually generates a different application and linker invocation instead
+of force loading symbols. This could be more complicated from an integration
+perspective so it isn't used.
+
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="force_load_direct_deps-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="force_load_direct_deps-deps"></a>deps |  -   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
+| <a id="force_load_direct_deps-should_force_load"></a>should_force_load |  Allows parametrically enabling the functionality in this rule.   | Boolean | optional | <code>True</code> |
+
+

docs/import_middleman_doc.md

@@ -0,0 +1,78 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+
+<a id="import_middleman"></a>
+
+## import_middleman
+
+<pre>
+import_middleman(<a href="#import_middleman-name">name</a>, <a href="#import_middleman-deps">deps</a>, <a href="#import_middleman-test_deps">test_deps</a>, <a href="#import_middleman-update_in_place">update_in_place</a>)
+</pre>
+
+
+This rule adds the ability to update the Mach-o header on imported
+libraries and frameworks to get arm64 binaires running on Apple silicon
+simulator. For rules_ios, it's added in `app.bzl` and `test.bzl`
+
+Why bother doing this? Well some apps have many dependencies which could take
+along time on vendors or other parties to update. Because the M1 chip has the
+same ISA as ARM64, most binaries will run transparently. Most iOS developers
+code is high level enough and isn't specifc to a device or simulator. There are
+many caveats and eceptions but getting it running is better than nothing. ( e.g.
+`TARGET_OS_SIMULATOR` )
+
+This solves the problem at the build system level with the power of bazel. The
+idea is pretty straight forward:
+1. collect all imported paths
+2. update the macho headers with Apples vtool and arm64-to-sim
+3. update the linker invocation to use the new libs
+
+Now it updates all of the inputs automatically - the action can be taught to do
+all of this conditionally if necessary.
+
+Note: The action happens in a rule for a few reasons.  This has an interesting
+propery: you get a single path for framework lookups at linktime. Perhaps this
+can be updated to work without the other behavior
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="import_middleman-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="import_middleman-deps"></a>deps |  -   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
+| <a id="import_middleman-test_deps"></a>test_deps |  -   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
+| <a id="import_middleman-update_in_place"></a>update_in_place |  -   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//tools/m1_utils:update_in_place</code> |
+
+
+<a id="find_imports"></a>
+
+## find_imports
+
+<pre>
+find_imports(<a href="#find_imports-name">name</a>)
+</pre>
+
+
+Internal aspect for the `import_middleman` see below for a description.
+
+
+**ASPECT ATTRIBUTES**
+
+
+| Name | Type |
+| :------------- | :------------- |
+| transitve_deps| String |
+| deps| String |
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="find_imports-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |   |
+
+

docs/providers_doc.md

@@ -0,0 +1,47 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+
+<a id="AvoidDepsInfo"></a>
+
+## AvoidDepsInfo
+
+<pre>
+AvoidDepsInfo(<a href="#AvoidDepsInfo-libraries">libraries</a>, <a href="#AvoidDepsInfo-link_dynamic">link_dynamic</a>)
+</pre>
+
+
+
+**FIELDS**
+
+
+| Name  | Description |
+| :------------- | :------------- |
+| <a id="AvoidDepsInfo-libraries"></a>libraries |  Libraries to avoid    |
+| <a id="AvoidDepsInfo-link_dynamic"></a>link_dynamic |  Weather or not if this dep is dynamic    |
+
+
+<a id="FrameworkInfo"></a>
+
+## FrameworkInfo
+
+<pre>
+FrameworkInfo(<a href="#FrameworkInfo-vfsoverlay_infos">vfsoverlay_infos</a>, <a href="#FrameworkInfo-binary">binary</a>, <a href="#FrameworkInfo-headers">headers</a>, <a href="#FrameworkInfo-private_headers">private_headers</a>, <a href="#FrameworkInfo-modulemap">modulemap</a>, <a href="#FrameworkInfo-swiftmodule">swiftmodule</a>, <a href="#FrameworkInfo-swiftdoc">swiftdoc</a>)
+</pre>
+
+
+
+**FIELDS**
+
+
+| Name  | Description |
+| :------------- | :------------- |
+| <a id="FrameworkInfo-vfsoverlay_infos"></a>vfsoverlay_infos |  Merged VFS overlay infos, present when virtual frameworks enabled    |
+| <a id="FrameworkInfo-binary"></a>binary |  The binary of the framework    |
+| <a id="FrameworkInfo-headers"></a>headers |  Headers of the framework's public interface    |
+| <a id="FrameworkInfo-private_headers"></a>private_headers |  Private headers of the framework    |
+| <a id="FrameworkInfo-modulemap"></a>modulemap |  The module map of the framework    |
+| <a id="FrameworkInfo-swiftmodule"></a>swiftmodule |  The swiftmodule    |
+| <a id="FrameworkInfo-swiftdoc"></a>swiftdoc |  The Swift doc    |
+
+