docs: Document that copy() uses the toolchain's copy tool

The copy() target type does not have a built-in copy command; the actual
command is provided by the "copy" tool defined by the toolchain, and GN
errors out if no such tool exists. This is how Chromium customizes
copying (e.g. hard-linking for speed), but it was not documented
anywhere, so it was easy to assume copy() had a fixed built-in
implementation.

Add a "How the copy is performed" section to `gn help copy` explaining
the mechanism and showing how to override the tool, and cross-reference
it from the "copy" tool description in `gn help tool`. Regenerate
reference.md.

Change-Id: I0fbd42c540411b4e15b0385f6753b6679ee23483
Reviewed-on: https://gn-review.googlesource.com/c/gn/+/23760
Reviewed-by: Takuto Ikuta <tikuta@google.com>
Reviewed-by: Matt Stark <msta@google.com>
Commit-Queue: Philipp Wollermann <philwo@chromium.org>

docs/reference.md

diff --git a/docs/reference.md b/docs/reference.md
index 4194378..4fbc5d9 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -1869,6 +1869,24 @@
   the copy target.
 ```
 
+#### **How the copy is performed**
+
+```
+  The actual command used to copy each file is not built in to the "copy"
+  target type. It is provided by the "copy" tool defined by the toolchain used
+  to build the target (see "gn help tool"). If the toolchain does not define a
+  "copy" tool, GN will error out.
+
+  This means projects can customize how files are copied -- for example to hard
+  link instead of byte-copying for speed -- by overriding the toolchain's
+  "copy" tool:
+
+    tool("copy") {
+      command = "cp -af --reflink=auto {{source}} {{output}}"
+      description = "COPY {{source}} {{output}}"
+    }
+```
+
 #### **Variables**
 
 ```
@@ -4439,8 +4457,10 @@
   substitutions.
 
   The copy tool allows the common compiler/linker substitutions, plus
-  {{source}} which is the source of the copy. The stamp tool allows only the
-  common tool substitutions.
+  {{source}} which is the source of the copy. It defines the command run by
+  "copy" targets (see "gn help copy"), so overriding it lets a toolchain
+  customize how those targets copy files. The stamp tool allows only the common
+  tool substitutions.
 
   The copy_bundle_data and compile_xcassets tools only allows the common tool
   substitutions. Both tools are required to create iOS/macOS bundles and need

src/gn/function_toolchain.cc

diff --git a/src/gn/function_toolchain.cc b/src/gn/function_toolchain.cc
index 3fdddae..70f6863 100644
--- a/src/gn/function_toolchain.cc
+++ b/src/gn/function_toolchain.cc
@@ -801,8 +801,10 @@
   substitutions.
 
   The copy tool allows the common compiler/linker substitutions, plus
-  {{source}} which is the source of the copy. The stamp tool allows only the
-  common tool substitutions.
+  {{source}} which is the source of the copy. It defines the command run by
+  "copy" targets (see "gn help copy"), so overriding it lets a toolchain
+  customize how those targets copy files. The stamp tool allows only the common
+  tool substitutions.
 
   The copy_bundle_data and compile_xcassets tools only allows the common tool
   substitutions. Both tools are required to create iOS/macOS bundles and need

src/gn/functions_target.cc

diff --git a/src/gn/functions_target.cc b/src/gn/functions_target.cc
index e50fc9b..c5e3e2e 100644
--- a/src/gn/functions_target.cc
+++ b/src/gn/functions_target.cc
@@ -555,6 +555,22 @@
   generates the file to copy must be reachable from the deps or public_deps of
   the copy target.
 
+How the copy is performed
+
+  The actual command used to copy each file is not built in to the "copy"
+  target type. It is provided by the "copy" tool defined by the toolchain used
+  to build the target (see "gn help tool"). If the toolchain does not define a
+  "copy" tool, GN will error out.
+
+  This means projects can customize how files are copied -- for example to hard
+  link instead of byte-copying for speed -- by overriding the toolchain's
+  "copy" tool:
+
+    tool("copy") {
+      command = "cp -af --reflink=auto {{source}} {{output}}"
+      description = "COPY {{source}} {{output}}"
+    }
+
 Variables
 
 )" DEPENDENT_CONFIG_VARS DEPS_VARS GENERAL_TARGET_VARS