Update stardoc for bzlmod (#776)

.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
 

.github/workflows/tests.yml

@@ -149,8 +149,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Preflight Env
-        # TODO: stardoc doesn't currently support bzlmod: https://github.com/bazelbuild/stardoc/issues/117
-        run: .github/workflows/preflight_env.sh --no-bzlmod
+        run: .github/workflows/preflight_env.sh
         # Note: we need to pass the absolute to the Bazel run
       - name: buildifier
         run: |

MODULE.bazel

@@ -50,9 +50,15 @@ bazel_dep(
 )
 bazel_dep(
     name = "bazel_skylib",
-    version = "1.4.1",
+    version = "1.4.2",
     dev_dependency = True,
 )
+bazel_dep(
+    name = "stardoc",
+    version = "0.6.2",
+    dev_dependency = True,
+    repo_name = "io_bazel_stardoc",
+)
 
 # Load non-bzlmod dependencies from rules_ios
 non_module_deps = use_extension("//rules:module_extensions.bzl", "non_module_deps")

WORKSPACE

@@ -47,22 +47,28 @@ load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
 
 bazel_skylib_workspace()
 
-load(
-    "@bazel_tools//tools/build_defs/repo:git.bzl",
-    "git_repository",
-)
-
-git_repository(
-    name = "io_bazel_stardoc",
-    commit = "6f274e903009158504a9d9130d7f7d5f3e9421ed",
-    remote = "https://github.com/bazelbuild/stardoc.git",
-    shallow_since = "1667581897 -0400",
-)
+# Load stardoc and it's deps
 
 load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
 
 stardoc_repositories()
 
+load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
+
+rules_jvm_external_deps()
+
+load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
+
+rules_jvm_external_setup()
+
+load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps")
+
+stardoc_external_deps()
+
+load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install")
+
+stardoc_pinned_maven_install()
+
 # Download prebuilt binaries buildifier
 load("@buildifier_prebuilt//:deps.bzl", "buildifier_prebuilt_deps")
 

WORKSPACE.bzlmod

@@ -4,24 +4,3 @@
 # This file will generally be kept empty in favor of using MODULE.bazel fully.
 
 workspace(name = "build_bazel_rules_ios")
-
-# TODO: stardoc doesn't currently support bzlmod: https://github.com/bazelbuild/stardoc/issues/117
-# Once that closes we should depend on it via the WORKSPACE file.
-# In the meantime, this is a workaround to at least allow building.
-# Note however that updating docs with bzlmod will not work until the above is resolved.
-# Until then use: --noenable_bzlmod
-load(
-    "@bazel_tools//tools/build_defs/repo:git.bzl",
-    "git_repository",
-)
-
-git_repository(
-    name = "io_bazel_stardoc",
-    commit = "6f274e903009158504a9d9130d7f7d5f3e9421ed",
-    remote = "https://github.com/bazelbuild/stardoc.git",
-    shallow_since = "1667581897 -0400",
-)
-
-load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
-
-stardoc_repositories()

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,49 @@
 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 corresponding `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 +59,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%%.*}_doc.md # replace generated extension with '_doc.md'
+    dest="$${BUILD_WORKSPACE_DIRECTORY}/docs/$${dest_name}"
     cp "$$1" "$$dest"
     chmod +w "$$dest"
 }' >> $(OUTS)

docs/app_clip_doc.md

@@ -11,7 +11,7 @@ ios_app_clip(<a href="#ios_app_clip-name">name</a>, <a href="#ios_app_clip-famil
              <a href="#ios_app_clip-xcconfig_by_build_setting">xcconfig_by_build_setting</a>, <a href="#ios_app_clip-kwargs">kwargs</a>)
 </pre>
 
-    Builds and packages an iOS App Clip.
+Builds and packages an iOS App Clip.
 
 The docs for app_clip are at rules_apple
 https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_app_clip
@@ -23,11 +23,11 @@ https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_app_c
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
 | <a id="ios_app_clip-name"></a>name |  The name of the iOS app clip.   |  none |
-| <a id="ios_app_clip-families"></a>families |  A list of iOS device families the target supports.   |  <code>["iphone", "ipad"]</code> |
-| <a id="ios_app_clip-infoplists"></a>infoplists |  A list of Info.plist files to be merged into the app clip.   |  <code>[]</code> |
-| <a id="ios_app_clip-infoplists_by_build_setting"></a>infoplists_by_build_setting |  A dictionary of infoplists grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'infoplists' is set as default.   |  <code>{}</code> |
-| <a id="ios_app_clip-xcconfig"></a>xcconfig |  A dictionary of xcconfigs to be applied to the app clip by default.   |  <code>{}</code> |
-| <a id="ios_app_clip-xcconfig_by_build_setting"></a>xcconfig_by_build_setting |  A dictionary of xcconfigs grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'xcconfig' is set as default.   |  <code>{}</code> |
+| <a id="ios_app_clip-families"></a>families |  A list of iOS device families the target supports.   |  `["iphone", "ipad"]` |
+| <a id="ios_app_clip-infoplists"></a>infoplists |  A list of Info.plist files to be merged into the app clip.   |  `[]` |
+| <a id="ios_app_clip-infoplists_by_build_setting"></a>infoplists_by_build_setting |  A dictionary of infoplists grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'infoplists' is set as default.   |  `{}` |
+| <a id="ios_app_clip-xcconfig"></a>xcconfig |  A dictionary of xcconfigs to be applied to the app clip by default.   |  `{}` |
+| <a id="ios_app_clip-xcconfig_by_build_setting"></a>xcconfig_by_build_setting |  A dictionary of xcconfigs grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'xcconfig' is set as default.   |  `{}` |
 | <a id="ios_app_clip-kwargs"></a>kwargs |  Arguments passed to the ios_app_clip rule as appropriate.   |  none |
 
 

docs/app_doc.md

@@ -11,20 +11,20 @@ ios_application(<a href="#ios_application-name">name</a>, <a href="#ios_applicat
                 <a href="#ios_application-xcconfig_by_build_setting">xcconfig_by_build_setting</a>, <a href="#ios_application-kwargs">kwargs</a>)
 </pre>
 
-    Builds and packages an iOS application.
+Builds and packages an iOS application.
 
 **PARAMETERS**
 
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
 | <a id="ios_application-name"></a>name |  The name of the iOS application.   |  none |
-| <a id="ios_application-families"></a>families |  A list of iOS device families the target supports.   |  <code>["iphone", "ipad"]</code> |
-| <a id="ios_application-apple_library"></a>apple_library |  The macro used to package sources into a library.   |  <code>&lt;function apple_library&gt;</code> |
-| <a id="ios_application-infoplists"></a>infoplists |  A list of Info.plist files to be merged into the iOS app.   |  <code>[]</code> |
-| <a id="ios_application-infoplists_by_build_setting"></a>infoplists_by_build_setting |  A dictionary of infoplists grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'infoplists' is set as default.   |  <code>{}</code> |
-| <a id="ios_application-xcconfig"></a>xcconfig |  A dictionary of xcconfigs to be applied to the iOS app by default.   |  <code>{}</code> |
-| <a id="ios_application-xcconfig_by_build_setting"></a>xcconfig_by_build_setting |  A dictionary of xcconfigs grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'xcconfig' is set as default.   |  <code>{}</code> |
+| <a id="ios_application-families"></a>families |  A list of iOS device families the target supports.   |  `["iphone", "ipad"]` |
+| <a id="ios_application-apple_library"></a>apple_library |  The macro used to package sources into a library.   |  `<function apple_library>` |
+| <a id="ios_application-infoplists"></a>infoplists |  A list of Info.plist files to be merged into the iOS app.   |  `[]` |
+| <a id="ios_application-infoplists_by_build_setting"></a>infoplists_by_build_setting |  A dictionary of infoplists grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'infoplists' is set as default.   |  `{}` |
+| <a id="ios_application-xcconfig"></a>xcconfig |  A dictionary of xcconfigs to be applied to the iOS app by default.   |  `{}` |
+| <a id="ios_application-xcconfig_by_build_setting"></a>xcconfig_by_build_setting |  A dictionary of xcconfigs grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'xcconfig' is set as default.   |  `{}` |
 | <a id="ios_application-kwargs"></a>kwargs |  Arguments passed to the apple_library and ios_application rules as appropriate.   |  none |
 
 

docs/extension_doc.md

@@ -11,7 +11,7 @@ ios_extension(<a href="#ios_extension-name">name</a>, <a href="#ios_extension-fa
               <a href="#ios_extension-xcconfig_by_build_setting">xcconfig_by_build_setting</a>, <a href="#ios_extension-kwargs">kwargs</a>)
 </pre>
 
-    Builds and packages an iOS extension.
+Builds and packages an iOS extension.
 
 The docs for ios_extension are at rules_apple
 https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_extension
@@ -25,11 +25,11 @@ Perhaps we can just remove this wrapper longer term.
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
 | <a id="ios_extension-name"></a>name |  The name of the iOS extension.   |  none |
-| <a id="ios_extension-families"></a>families |  A list of iOS device families the target supports.   |  <code>["iphone", "ipad"]</code> |
-| <a id="ios_extension-infoplists"></a>infoplists |  A list of Info.plist files to be merged into the extension.   |  <code>[]</code> |
-| <a id="ios_extension-infoplists_by_build_setting"></a>infoplists_by_build_setting |  A dictionary of infoplists grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'infoplists' is set as default.   |  <code>{}</code> |
-| <a id="ios_extension-xcconfig"></a>xcconfig |  A dictionary of xcconfigs to be applied to the extension by default.   |  <code>{}</code> |
-| <a id="ios_extension-xcconfig_by_build_setting"></a>xcconfig_by_build_setting |  A dictionary of xcconfigs grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'xcconfig' is set as default.   |  <code>{}</code> |
+| <a id="ios_extension-families"></a>families |  A list of iOS device families the target supports.   |  `["iphone", "ipad"]` |
+| <a id="ios_extension-infoplists"></a>infoplists |  A list of Info.plist files to be merged into the extension.   |  `[]` |
+| <a id="ios_extension-infoplists_by_build_setting"></a>infoplists_by_build_setting |  A dictionary of infoplists grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'infoplists' is set as default.   |  `{}` |
+| <a id="ios_extension-xcconfig"></a>xcconfig |  A dictionary of xcconfigs to be applied to the extension by default.   |  `{}` |
+| <a id="ios_extension-xcconfig_by_build_setting"></a>xcconfig_by_build_setting |  A dictionary of xcconfigs grouped by bazel build setting.<br><br>Each value is applied if the respective bazel build setting is resolved during the analysis phase.<br><br>If '//conditions:default' is not set the value in 'xcconfig' is set as default.   |  `{}` |
 | <a id="ios_extension-kwargs"></a>kwargs |  Arguments passed to the ios_extension rule as appropriate.   |  none |
 
 

docs/features_doc.md

@@ -0,0 +1,16 @@
+<!-- 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,46 @@
+<!-- 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 |  `[]`  |
+| <a id="force_load_direct_deps-should_force_load"></a>should_force_load |  Allows parametrically enabling the functionality in this rule.   | Boolean | optional |  `True`  |
+
+