Rename the root cell

This commit renames the `root` cell to facilitate embedding it as a dependency to Rust projects.
While the Buck2 repository does not have an official public API, depending on it is the most
reasonable way of writing custom test runners, which is important for OSS users until TestInfo V2
lands.

`root` is a common name for root cells, it is generic and it is the default when running `buck2
init`, making it a bad name that is not descriptive and likely to conflict with downstream cells.

As described in the added docs, this commit is not an ideal solution, since it requires
configuration hacks:
- The root `.buckconfig` must point to Buck2's shim directory.
- Buck2's `.buckconfig` must be edited to remove cells that are already defined in the root.

.buckconfig

@@ -1,6 +1,6 @@
 [repositories]
-root = .
 prelude = prelude
+buck2 = .
 shim = shim
 
 [repository_aliases]
@@ -14,4 +14,4 @@ buck = shim
 bazel_skylib = shim
 
 [parser]
-target_platform_detector_spec = target:root//...->prelude//platforms:default target:shim//...->prelude//platforms:default
+target_platform_detector_spec = target:buck2//...->prelude//platforms:default target:shim//...->prelude//platforms:default

docs/users/advanced/buck2_library.md

@@ -0,0 +1,32 @@
+---
+id: buck2_library
+title: Consuming code from the `buck2` repository
+---
+
+It is possible to depend on targets from the Buck2 repository, which you
+might need to do to write a custom test runner (at least until [TestInfo
+V2](../../rfcs/drafts/test-info-v2.md) lands). Note that there are no
+API stability guarantees at the moment.
+
+The Buck2 Rust code is available in the `buck2` cell and is useable as
+is after adding the following to your `.buckconfig`'s (assuming that the
+`buck2` project is available at `path/to/buck2`):
+
+```
+[cells]
+buck2 = path/to/buck2
+shim = path/to/buck2/shim
+
+[cell_aliases]
+config = prelude
+ovr_config = prelude
+fbcode = shim
+fbsource = shim
+fbcode_macros = shim
+buck = shim
+bazel_skylib = shim
+```
+
+Note that due to how cells work in Buck2, the `buck2` cell cannot bring
+its own dependencies, so you must remove conflicting cell aliases from
+`path/to/buck2/.buckconfig`.

examples/visual_studio/toolchains/BUCK

@@ -1,8 +1,8 @@
+load("@buck2//buck2_utils/platforms:defs.bzl", "is_remote_enabled")
 load("@prelude//toolchains:cxx.bzl", "cxx_tools_info_toolchain")
 load("@prelude//toolchains:python.bzl", "system_python_bootstrap_toolchain")
 load("@prelude//toolchains/cxx/clang:tools.bzl", "path_clang_tools")
 load("@prelude//toolchains/msvc:tools.bzl", "find_msvc_tools")
-load("@root//buck2_utils/platforms:defs.bzl", "is_remote_enabled")
 
 oncall("build_infra")
 
@@ -43,13 +43,13 @@ cxx_tools_info_toolchain(
             "/permissive-",
             "/TC",
         ] + select({
-            "root//buck2_utils/configuration:debug": [
+            "buck2//buck2_utils/configuration:debug": [
                 "/Od",
                 "/D_DEBUG",
                 "/RTC1",
                 "/MDd",
             ],
-            "root//buck2_utils/configuration:release": [
+            "buck2//buck2_utils/configuration:release": [
                 "/O2",
                 "/Oi",
                 "/GL",
@@ -86,13 +86,13 @@ cxx_tools_info_toolchain(
             "/permissive-",
             "/TP",
         ] + select({
-            "root//buck2_utils/configuration:debug": [
+            "buck2//buck2_utils/configuration:debug": [
                 "/Od",
                 "/D_DEBUG",
                 "/RTC1",
                 "/MDd",
             ],
-            "root//buck2_utils/configuration:release": [
+            "buck2//buck2_utils/configuration:release": [
                 "/O2",
                 "/Oi",
                 "/GL",
@@ -117,9 +117,9 @@ cxx_tools_info_toolchain(
             "/DEBUG",
             "/INCREMENTAL:NO",
         ] + select({
-            "root//buck2_utils/configuration:debug": [],
+            "buck2//buck2_utils/configuration:debug": [],
             #Converted /LTCG:incremental to /LTCG because I'm guessing incremental actions won't work well with Buck2
-            "root//buck2_utils/configuration:release": [
+            "buck2//buck2_utils/configuration:release": [
                 "/OPT:REF",
                 "/OPT:ICF",
                 "/LTCG",

shim/build_defs/native_rules.bzl

@@ -18,7 +18,7 @@ def buck_filegroup(visibility = ["PUBLIC"], **kwargs):
 
 def alias(actual, visibility = ["PUBLIC"], **kwargs):
     if actual.startswith("//buck2/"):
-        actual = "root//" + actual.removeprefix("//buck2/")
+        actual = "buck2//" + actual.removeprefix("//buck2/")
     native.alias(actual = actual, visibility = visibility, **kwargs)
 
 def buck_sh_binary(visibility = ["PUBLIC"], **kwargs):

shim/shims.bzl

@@ -416,9 +416,9 @@ def _fix_dep(x: str) -> [
     elif x.startswith("//buck2/facebook/"):
         return None
     elif x.startswith("//buck2/"):
-        return "root//" + x.removeprefix("//buck2/")
+        return "buck2//" + x.removeprefix("//buck2/")
     elif x.startswith("fbcode//common/ocaml/interop/"):
-        return "root//" + x.removeprefix("fbcode//common/ocaml/interop/")
+        return "buck2//" + x.removeprefix("fbcode//common/ocaml/interop/")
     elif x.startswith("fbcode//third-party-buck/platform010/build/supercaml"):
         return "shim//third-party/ocaml" + x.removeprefix("fbcode//third-party-buck/platform010/build/supercaml")
     elif x.startswith("fbcode//third-party-buck/platform010/build"):
@@ -430,12 +430,12 @@ def _fix_dep(x: str) -> [
     elif x.startswith("//folly"):
         oss_depends_on_folly = read_config("oss_depends_on", "folly", False)
         if oss_depends_on_folly:
-            return "root//folly/" + x.removeprefix("//")
-        return "root//" + x.removeprefix("//")
-    elif x.startswith("root//folly"):
+            return "buck2//folly/" + x.removeprefix("//")
+        return "buck2//" + x.removeprefix("//")
+    elif x.startswith("buck2//folly"):
         return x
     elif x.startswith("//fizz"):
-        return "root//" + x.removeprefix("//")
+        return "buck2//" + x.removeprefix("//")
     elif x.startswith("shim//"):
         return x
     else:
@@ -445,7 +445,7 @@ def _fix_dep(x: str) -> [
 def _fix_dep_in_string(x: str) -> str:
     """Replace internal labels in string values such as env-vars."""
     return (x
-        .replace("//buck2/", "root//"))
+        .replace("//buck2/", "buck2//"))
 
 # Do a nasty conversion of e.g. ("supercaml", None, "ocaml-dev") to
 # 'fbcode//third-party-buck/platform010/build/supercaml:ocaml-dev'