feat: add the ability to declare safe tools in a cross-build environment. (#2317)

* Add the ability to declare safe tools in a cross-build environment.

* Add an xfail if cmake isn't available on the test machine.

* Placate linter regarding positional args.

* Rework test to provide more robust confirmation of safe tools.

* Remove a test skip condition that is no longer needed.

Co-authored-by: Joe Rickerby <joerick@mac.com>

* Rename the setting to xbuild-tools.

* Add docs to clarify that xbuild-tools is transitive.

* Raise a warning if xbuild-tools isn't defined.

* Correct a bad copy-paste in the schema generator.

* .. and now fix the indentation.

* Move sentinel handling earlier into the parsing process.

* Remove serialization from tests that won't start a test suite.

---------

Co-authored-by: Joe Rickerby <joerick@mac.com>

unit_test/options_test.py

@@ -618,3 +618,31 @@ def test_get_build_frontend_extra_flags_warning(
     )
     assert args == ["-Ca", "-Cb", "-1"]
     mock_warning.assert_called_once()
+
+
+@pytest.mark.parametrize(
+    ("definition", "expected"),
+    [
+        ("", None),
+        ("xbuild-tools = []", []),
+        ('xbuild-tools = ["cmake", "rustc"]', ["cmake", "rustc"]),
+    ],
+)
+def test_xbuild_tools_handling(tmp_path: Path, definition: str, expected: list[str] | None) -> None:
+    args = CommandLineArguments.defaults()
+    args.package_dir = tmp_path
+
+    pyproject_toml: Path = tmp_path / "pyproject.toml"
+    pyproject_toml.write_text(
+        textwrap.dedent(
+            f"""\
+            [tool.cibuildwheel]
+            {definition}
+            """
+        )
+    )
+
+    options = Options(platform="ios", command_line_arguments=args, env={})
+
+    local = options.build_options("cp313-ios_13_0_arm64_iphoneos")
+    assert local.xbuild_tools == expected

unit_test/options_toml_test.py

@@ -17,6 +17,7 @@ PYPROJECT_1 = """
 [tool.cibuildwheel]
 build = "cp39*"
 environment = {THING = "OTHER", FOO="BAR"}
+xbuild-tools = ["first"]
 
 test-command = "pyproject"
 test-requires = "something"
@@ -89,6 +90,7 @@ def test_envvar_override(tmp_path, platform):
         env={
             "CIBW_BUILD": "cp38*",
             "CIBW_MANYLINUX_X86_64_IMAGE": "manylinux_2_24",
+            "CIBW_XBUILD_TOOLS": "cmake rustc",
             "CIBW_TEST_COMMAND": "mytest",
             "CIBW_TEST_REQUIRES": "docs",
             "CIBW_TEST_GROUPS": "mgroup two",
@@ -104,6 +106,10 @@ def test_envvar_override(tmp_path, platform):
     assert options_reader.get("manylinux-x86_64-image") == "manylinux_2_24"
     assert options_reader.get("manylinux-i686-image") == "manylinux2014"
 
+    assert (
+        options_reader.get("xbuild-tools", option_format=ListFormat(" ", quote=shlex.quote))
+        == "cmake rustc"
+    )
     assert (
         options_reader.get("test-sources", option_format=ListFormat(" ", quote=shlex.quote))
         == 'first "second third"'
@@ -269,6 +275,7 @@ manylinux-x86_64-image = ""
         env={
             "CIBW_MANYLINUX_I686_IMAGE": "",
             "CIBW_MANYLINUX_AARCH64_IMAGE": "manylinux1",
+            "CIBW_XBUILD_TOOLS": "",
         },
     )
 
@@ -280,6 +287,10 @@ manylinux-x86_64-image = ""
     assert options_reader.get("manylinux-i686-image", ignore_empty=True) == "manylinux1"
     assert options_reader.get("manylinux-aarch64-image", ignore_empty=True) == "manylinux1"
 
+    assert (
+        options_reader.get("xbuild-tools", option_format=ListFormat(" ", quote=shlex.quote)) == ""
+    )
+
 
 @pytest.mark.parametrize("ignore_empty", [True, False], ids=["ignore_empty", "no_ignore_empty"])
 def test_resolve_cascade(ignore_empty):