Add xcschemes.autogeneration_config (#3027)

Resolves #3013 

The proposal is to introduce a `xcschemes.autogeneration_config` macro
to allow consumers to configure scheme auto-generation. I'm addressing
my particular use case of wanting to exclude certain schemes based on
patterns in their names but I'm open to discuss other
configurations/exclusion patterns folks might want to add here.

In order to test this note how running (from `examples/integration`)
`bazel run //:xcodeproj-incremental-bazel-sim_arm64` generates a project
that **does not** contain the undesired schemes `UndesiredScheme_Swift`
and `UnwantedScheme_Swift` even though the respective targets do exist.

---------

Signed-off-by: Thiago Cruz <thiago@squareup.com>
Co-authored-by: Brentley Jones <github@brentleyjones.com>

Author: thiagohmcruz

docs/bazel.md

@@ -62,10 +62,10 @@ xcodeproj(<a href="#xcodeproj-name">name</a>, <a href="#xcodeproj-adjust_schemes
           <a href="#xcodeproj-build_mode">build_mode</a>, <a href="#xcodeproj-config">config</a>, <a href="#xcodeproj-default_xcode_configuration">default_xcode_configuration</a>, <a href="#xcodeproj-extra_files">extra_files</a>,
           <a href="#xcodeproj-fail_for_invalid_extra_files_targets">fail_for_invalid_extra_files_targets</a>, <a href="#xcodeproj-focused_targets">focused_targets</a>, <a href="#xcodeproj-generation_mode">generation_mode</a>, <a href="#xcodeproj-install_directory">install_directory</a>,
           <a href="#xcodeproj-ios_device_cpus">ios_device_cpus</a>, <a href="#xcodeproj-ios_simulator_cpus">ios_simulator_cpus</a>, <a href="#xcodeproj-minimum_xcode_version">minimum_xcode_version</a>, <a href="#xcodeproj-post_build">post_build</a>, <a href="#xcodeproj-pre_build">pre_build</a>,
-          <a href="#xcodeproj-project_name">project_name</a>, <a href="#xcodeproj-project_options">project_options</a>, <a href="#xcodeproj-scheme_autogeneration_mode">scheme_autogeneration_mode</a>, <a href="#xcodeproj-schemes">schemes</a>, <a href="#xcodeproj-target_name_mode">target_name_mode</a>,
-          <a href="#xcodeproj-top_level_targets">top_level_targets</a>, <a href="#xcodeproj-tvos_device_cpus">tvos_device_cpus</a>, <a href="#xcodeproj-tvos_simulator_cpus">tvos_simulator_cpus</a>, <a href="#xcodeproj-unfocused_targets">unfocused_targets</a>,
-          <a href="#xcodeproj-visionos_device_cpus">visionos_device_cpus</a>, <a href="#xcodeproj-visionos_simulator_cpus">visionos_simulator_cpus</a>, <a href="#xcodeproj-watchos_device_cpus">watchos_device_cpus</a>, <a href="#xcodeproj-watchos_simulator_cpus">watchos_simulator_cpus</a>,
-          <a href="#xcodeproj-xcode_configurations">xcode_configurations</a>, <a href="#xcodeproj-xcschemes">xcschemes</a>, <a href="#xcodeproj-kwargs">kwargs</a>)
+          <a href="#xcodeproj-project_name">project_name</a>, <a href="#xcodeproj-project_options">project_options</a>, <a href="#xcodeproj-scheme_autogeneration_mode">scheme_autogeneration_mode</a>, <a href="#xcodeproj-scheme_autogeneration_config">scheme_autogeneration_config</a>,
+          <a href="#xcodeproj-schemes">schemes</a>, <a href="#xcodeproj-target_name_mode">target_name_mode</a>, <a href="#xcodeproj-top_level_targets">top_level_targets</a>, <a href="#xcodeproj-tvos_device_cpus">tvos_device_cpus</a>, <a href="#xcodeproj-tvos_simulator_cpus">tvos_simulator_cpus</a>,
+          <a href="#xcodeproj-unfocused_targets">unfocused_targets</a>, <a href="#xcodeproj-visionos_device_cpus">visionos_device_cpus</a>, <a href="#xcodeproj-visionos_simulator_cpus">visionos_simulator_cpus</a>, <a href="#xcodeproj-watchos_device_cpus">watchos_device_cpus</a>,
+          <a href="#xcodeproj-watchos_simulator_cpus">watchos_simulator_cpus</a>, <a href="#xcodeproj-xcode_configurations">xcode_configurations</a>, <a href="#xcodeproj-xcschemes">xcschemes</a>, <a href="#xcodeproj-kwargs">kwargs</a>)
 </pre>
 
 Creates an `.xcodeproj` file in the workspace when run.
@@ -117,6 +117,7 @@ xcodeproj(
 | <a id="xcodeproj-project_name"></a>project_name |  Optional. The name to use for the `.xcodeproj` file.<br><br>If not specified, the value of the `name` argument is used.   |  `None` |
 | <a id="xcodeproj-project_options"></a>project_options |  Optional. A value returned by `project_options`.   |  `None` |
 | <a id="xcodeproj-scheme_autogeneration_mode"></a>scheme_autogeneration_mode |  Optional. Specifies how Xcode schemes are automatically generated:<br><br><ul> <li>   `auto`: If no custom schemes are specified, via `schemes`, an   Xcode scheme will be created for every buildable target. If custom   schemes are provided, no autogenerated schemes will be created. </li> <li>   `none`: No schemes are automatically generated. </li> <li>   `all`: A scheme is generated for every buildable target even if   custom schemes are provided. </li> </ul>   |  `"auto"` |
+| <a id="xcodeproj-scheme_autogeneration_config"></a>scheme_autogeneration_config |  Optional. A value returned by [`xcschemes.autogeneration_config`](#xcschemes.autogeneration_config).<br><br>Allows further configuration of `scheme_autogeneration_mode`.   |  `{}` |
 | <a id="xcodeproj-schemes"></a>schemes |  Optional. A `list` of values returned by `xcode_schemes.scheme`.<br><br>This and the `scheme_autogeneration_mode` argument together customize how schemes for targets are generated, when using `generation_mode = "legacy"`.<br><br>Target labels listed in the schemes need to be from the transitive dependencies of the targets specified in the `top_level_targets` argument.   |  `[]` |
 | <a id="xcodeproj-target_name_mode"></a>target_name_mode |  Optional. Specifies how Xcode targets names are represented:<br><br><ul> <li>   `auto`: Use the product name if it is available and there is no collision.    Otherwise select the target name from the label.    And if there is a collision, use the full label. </li> <li>   `label`: Always use full label for Xcode targets names. </li> </ul>   |  `"auto"` |
 | <a id="xcodeproj-top_level_targets"></a>top_level_targets |  A `list` of a list of top-level targets.<br><br>Each target can be specified as either a `Label` (or label-like `string`), a value returned by `top_level_target`, or a value returned by `top_level_targets`.   |  none |
@@ -236,6 +237,28 @@ Defines a command-line argument.
 | <a id="xcschemes.arg-literal_string"></a>literal_string |  Whether `value` should be interpreted as a literal string.<br><br>If `True`, any spaces will be escaped. This means that `value` will be passed to the launch target as a single string. If `False`, any spaces will not be escaped. This is useful to group multiple arguments under a single checkbox in Xcode.   |  `True` |
 
 
+<a id="xcschemes.autogeneration_config"></a>
+
+## xcschemes.autogeneration_config
+
+<pre>
+xcschemes.autogeneration_config(<a href="#xcschemes.autogeneration_config-scheme_name_exclude_patterns">scheme_name_exclude_patterns</a>)
+</pre>
+
+Creates a value for the [`scheme_autogeneration_config`](xcodeproj-scheme_autogeneration_config) attribute of `xcodeproj`.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="xcschemes.autogeneration_config-scheme_name_exclude_patterns"></a>scheme_name_exclude_patterns |  A `list` of regex patterns used to skip creating matching autogenerated schemes.<br><br>Example:<br><br><pre><code class="language-starlark">xcodeproj(&#10;    ...&#10;    scheme_name_exclude_patterns = xcschemes.autogeneration_config(&#10;        scheme_name_exclude_patterns = [&#10;            ".*somePattern.*",&#10;            "^AnotherPattern.*",&#10;        ],&#10;    )&#10;)</code></pre>   |  `None` |
+
+**RETURNS**
+
+An opaque value for the [`scheme_autogeneration_config`](xcodeproj-scheme_autogeneration_config) attribute of `xcodeproj`.
+
+
 <a id="xcschemes.diagnostics"></a>
 
 ## xcschemes.diagnostics

examples/integration/BUILD

@@ -10,6 +10,7 @@ load(
     "FAIL_FOR_INVALID_EXTRA_FILES_TARGETS",
     "PRE_BUILD",
     "PROJECT_OPTIONS",
+    "SCHEME_AUTOGENERATION_CONFIG",
     "SCHEME_AUTOGENERATION_MODE",
     "UNFOCUSED_TARGETS",
     "XCODEPROJ_TARGETS",
@@ -68,6 +69,7 @@ string_flag(
         pre_build = PRE_BUILD,
         project_name = "Integration",
         project_options = PROJECT_OPTIONS,
+        scheme_autogeneration_config = SCHEME_AUTOGENERATION_CONFIG,
         scheme_autogeneration_mode = SCHEME_AUTOGENERATION_MODE,
         schemes = get_xcode_schemes(),
         tags = ["manual"],

examples/integration/Lib/UndesiredSchemes/BUILD

@@ -0,0 +1,18 @@
+"""Targets meant to match scheme auto-generation exclude patterns"""
+
+load(
+    "@build_bazel_rules_swift//swift:swift.bzl",
+    "swift_library",
+)
+
+swift_library(
+    name = "UndesiredScheme_Swift",
+    srcs = ["UndesiredScheme.swift"],
+    visibility = ["//iOSApp/Source:__pkg__"],
+)
+
+swift_library(
+    name = "UnwantedScheme_Swift",
+    srcs = ["UnwantedScheme.swift"],
+    visibility = ["//iOSApp/Source:__pkg__"],
+)

examples/integration/Lib/UndesiredSchemes/UndesiredScheme.swift

@@ -142,6 +142,8 @@ swift_library(
     tags = ["manual"],
     visibility = ["//iOSApp/Test:__subpackages__"],
     deps = [
+        "//Lib/UndesiredSchemes:UndesiredScheme_Swift",
+        "//Lib/UndesiredSchemes:UnwantedScheme_Swift",
         "//UI",
         "//iOSApp/Source/CoreUtilsMixed/MixedAnswer",
         "//iOSApp/Source/CoreUtilsObjC",