adding scope attributes for starlark flags (#546)

Working towards docs.google.com/document/d/1wIMpW1DsA0CEOs0bo9-maWbNEz4eAAyoIH59lJlZt_o/edit?tab=t.0#heading=h.epjv6353d2y8

docs/common_settings_doc.md

@@ -13,7 +13,7 @@ https://bazel.build/extending/config#user-defined-build-settings
 ## bool_flag
 
 <pre>
-bool_flag(<a href="#bool_flag-name">name</a>)
+bool_flag(<a href="#bool_flag-name">name</a>, <a href="#bool_flag-scope">scope</a>)
 </pre>
 
 A bool-typed build setting that can be set on the command line
@@ -24,6 +24,7 @@ A bool-typed build setting that can be set on the command line
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="bool_flag-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="bool_flag-scope"></a>scope |  The scope indicates where a flag can propagate to   | String | optional |  `"universal"`  |
 
 
 <a id="bool_setting"></a>
@@ -31,7 +32,7 @@ A bool-typed build setting that can be set on the command line
 ## bool_setting
 
 <pre>
-bool_setting(<a href="#bool_setting-name">name</a>)
+bool_setting(<a href="#bool_setting-name">name</a>, <a href="#bool_setting-scope">scope</a>)
 </pre>
 
 A bool-typed build setting that cannot be set on the command line
@@ -42,6 +43,7 @@ A bool-typed build setting that cannot be set on the command line
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="bool_setting-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="bool_setting-scope"></a>scope |  The scope indicates where a flag can propagate to   | String | optional |  `"universal"`  |
 
 
 <a id="int_flag"></a>
@@ -49,7 +51,7 @@ A bool-typed build setting that cannot be set on the command line
 ## int_flag
 
 <pre>
-int_flag(<a href="#int_flag-name">name</a>, <a href="#int_flag-make_variable">make_variable</a>)
+int_flag(<a href="#int_flag-name">name</a>, <a href="#int_flag-make_variable">make_variable</a>, <a href="#int_flag-scope">scope</a>)
 </pre>
 
 An int-typed build setting that can be set on the command line
@@ -61,6 +63,7 @@ An int-typed build setting that can be set on the command line
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="int_flag-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
 | <a id="int_flag-make_variable"></a>make_variable |  If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute.   | String | optional |  `""`  |
+| <a id="int_flag-scope"></a>scope |  The scope indicates where a flag can propagate to   | String | optional |  `"universal"`  |
 
 
 <a id="int_setting"></a>
@@ -68,7 +71,7 @@ An int-typed build setting that can be set on the command line
 ## int_setting
 
 <pre>
-int_setting(<a href="#int_setting-name">name</a>, <a href="#int_setting-make_variable">make_variable</a>)
+int_setting(<a href="#int_setting-name">name</a>, <a href="#int_setting-make_variable">make_variable</a>, <a href="#int_setting-scope">scope</a>)
 </pre>
 
 An int-typed build setting that cannot be set on the command line
@@ -80,6 +83,7 @@ An int-typed build setting that cannot be set on the command line
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="int_setting-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
 | <a id="int_setting-make_variable"></a>make_variable |  If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute.   | String | optional |  `""`  |
+| <a id="int_setting-scope"></a>scope |  The scope indicates where a flag can propagate to   | String | optional |  `"universal"`  |
 
 
 <a id="string_flag"></a>
@@ -87,7 +91,7 @@ An int-typed build setting that cannot be set on the command line
 ## string_flag
 
 <pre>
-string_flag(<a href="#string_flag-name">name</a>, <a href="#string_flag-make_variable">make_variable</a>, <a href="#string_flag-values">values</a>)
+string_flag(<a href="#string_flag-name">name</a>, <a href="#string_flag-make_variable">make_variable</a>, <a href="#string_flag-scope">scope</a>, <a href="#string_flag-values">values</a>)
 </pre>
 
 A string-typed build setting that can be set on the command line
@@ -99,6 +103,7 @@ A string-typed build setting that can be set on the command line
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="string_flag-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
 | <a id="string_flag-make_variable"></a>make_variable |  If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute.   | String | optional |  `""`  |
+| <a id="string_flag-scope"></a>scope |  The scope indicates where a flag can propagate to   | String | optional |  `"universal"`  |
 | <a id="string_flag-values"></a>values |  The list of allowed values for this setting. An error is raised if any other value is given.   | List of strings | optional |  `[]`  |
 
 
@@ -107,7 +112,7 @@ A string-typed build setting that can be set on the command line
 ## string_list_flag
 
 <pre>
-string_list_flag(<a href="#string_list_flag-name">name</a>)
+string_list_flag(<a href="#string_list_flag-name">name</a>, <a href="#string_list_flag-scope">scope</a>)
 </pre>
 
 A string list-typed build setting that can be set on the command line
@@ -118,6 +123,7 @@ A string list-typed build setting that can be set on the command line
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="string_list_flag-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="string_list_flag-scope"></a>scope |  The scope indicates where a flag can propagate to   | String | optional |  `"universal"`  |
 
 
 <a id="string_list_setting"></a>
@@ -125,7 +131,7 @@ A string list-typed build setting that can be set on the command line
 ## string_list_setting
 
 <pre>
-string_list_setting(<a href="#string_list_setting-name">name</a>)
+string_list_setting(<a href="#string_list_setting-name">name</a>, <a href="#string_list_setting-scope">scope</a>)
 </pre>
 
 A string list-typed build setting that cannot be set on the command line
@@ -136,6 +142,7 @@ A string list-typed build setting that cannot be set on the command line
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="string_list_setting-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="string_list_setting-scope"></a>scope |  The scope indicates where a flag can propagate to   | String | optional |  `"universal"`  |
 
 
 <a id="string_setting"></a>

rules/common_settings.bzl

@@ -66,6 +66,10 @@ int_flag = rule(
     build_setting = config.int(flag = True),
     attrs = {
         "make_variable": _MAKE_VARIABLE_ATTR,
+        "scope": attr.string(
+            doc = "The scope indicates where a flag can propagate to",
+            default = "universal",
+        ),
     },
     doc = "An int-typed build setting that can be set on the command line",
 )
@@ -75,6 +79,10 @@ int_setting = rule(
     build_setting = config.int(),
     attrs = {
         "make_variable": _MAKE_VARIABLE_ATTR,
+        "scope": attr.string(
+            doc = "The scope indicates where a flag can propagate to",
+            default = "universal",
+        ),
     },
     doc = "An int-typed build setting that cannot be set on the command line",
 )
@@ -82,24 +90,48 @@ int_setting = rule(
 bool_flag = rule(
     implementation = _impl,
     build_setting = config.bool(flag = True),
+    attrs = {
+        "scope": attr.string(
+            doc = "The scope indicates where a flag can propagate to",
+            default = "universal",
+        ),
+    },
     doc = "A bool-typed build setting that can be set on the command line",
 )
 
 bool_setting = rule(
     implementation = _impl,
     build_setting = config.bool(),
+    attrs = {
+        "scope": attr.string(
+            doc = "The scope indicates where a flag can propagate to",
+            default = "universal",
+        ),
+    },
     doc = "A bool-typed build setting that cannot be set on the command line",
 )
 
 string_list_flag = rule(
     implementation = _impl,
     build_setting = config.string_list(flag = True),
+    attrs = {
+        "scope": attr.string(
+            doc = "The scope indicates where a flag can propagate to",
+            default = "universal",
+        ),
+    },
     doc = "A string list-typed build setting that can be set on the command line",
 )
 
 string_list_setting = rule(
     implementation = _impl,
     build_setting = config.string_list(),
+    attrs = {
+        "scope": attr.string(
+            doc = "The scope indicates where a flag can propagate to",
+            default = "universal",
+        ),
+    },
     doc = "A string list-typed build setting that cannot be set on the command line",
 )
 
@@ -128,6 +160,10 @@ string_flag = rule(
             doc = "The list of allowed values for this setting. An error is raised if any other value is given.",
         ),
         "make_variable": _MAKE_VARIABLE_ATTR,
+        "scope": attr.string(
+            doc = "The scope indicates where a flag can propagate to",
+            default = "universal",
+        ),
     },
     doc = "A string-typed build setting that can be set on the command line",
 )