fix the toolchains registration and document the algorithm

Author: aignas

python/uv/private/toolchains_hub.bzl

@@ -30,7 +30,8 @@ def toolchains_hub(
 
     Args:
         name: Unused.
-        names: The names for toolchain targets.
+        names: The names for toolchain targets. The later occurring items take
+            precedence over the previous items if they match the target platform.
         implementations: The name to label mapping.
         target_compatible_with: The name to target_compatible_with list mapping.
         target_settings: The name to target_settings list mapping.
@@ -50,7 +51,11 @@ def toolchains_hub(
     prefix_len = len(str(len(names)))
     prefix = "0" * (prefix_len - 1)
 
-    for i, name in sorted(enumerate(names), key = lambda x: -x[0]):
+    # reverse the names list so that the later items override earlier toolchain
+    # registrations.
+    names = [n for _, n in sorted(enumerate(names), key = lambda x: -x[0])]
+
+    for i, name in enumerate(names):
         # prefix with a prefix and then truncate the string.
         number_prefix = "{}{}".format(prefix, i)[-prefix_len:]
 

tests/uv/uv_toolchains/BUILD.bazel

@@ -5,10 +5,10 @@ toolchains_hub(
         "bar": "//tests/uv/uv:fake_bar",
         "foo": "//tests/uv/uv:fake_foof",
     },
-    # We expect bar to not be effective here
+    # We expect foo to take precedence over bar
     names = [
-        "foo",
         "bar",
+        "foo",
     ],
     target_compatible_with = {
         "bar": [