commit 55fd56489acfc6c34ff64b720773dc0316cb59db
author Fredrik Medley <fredrik.medley@gmail.com> Fri Apr 29 05:56:36 2022 -0700
committer Copybara-Service <copybara-worker@google.com> Fri Apr 29 05:59:16 2022 -0700
tree 6f20bc4d595010aacd60581071744e1525f43c68
parent 3e35c74c0a38d682e59e32caaf9e94e595870070

Improve help description for --experimental_execution_log_file

Explain that `--experimental_execution_log_file` is unordered where as `--execution_log_binary_file` and `--execution_log_json_file` are ordered, which might be CPU and memory intensive.

Closes #14411.

PiperOrigin-RevId: 445396988

src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java

diff --git a/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java b/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
index 4a0cbfc..b9c0b7c 100644
--- a/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
@@ -417,7 +417,13 @@
       documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
       effectTags = {OptionEffectTag.UNKNOWN},
       converter = OptionsUtils.PathFragmentConverter.class,
-      help = "Log the executed spawns into this file as delimited Spawn protos.")
+      help =
+          "Log the executed spawns into this file as delimited Spawn protos, according to "
+              + "src/main/protobuf/spawn.proto. This file is written in order of the execution "
+              + "of the Spawns. Related flags:"
+              + " --execution_log_binary_file (ordered binary protobuf format),"
+              + " --execution_log_json_file (ordered text json format),"
+              + " --subcommands (for displaying subcommands in terminal output).")
   public PathFragment executionLogFile;
 
   @Option(
@@ -428,9 +434,13 @@
       effectTags = {OptionEffectTag.UNKNOWN},
       converter = OptionsUtils.PathFragmentConverter.class,
       help =
-          "Log the executed spawns into this file as delimited Spawn protos. Related flags:"
-              + " --execution_log_json_file (text json format), --subcommands (for displaying"
-              + " subcommands in terminal output).")
+          "Log the executed spawns into this file as delimited Spawn protos, according to"
+              + " src/main/protobuf/spawn.proto. The log is first written unordered and is then,"
+              + " at the end of the invocation, sorted in a stable order (can be CPU and memory"
+              + " intensive). Related flags:"
+              + " --execution_log_json_file (ordered text json format),"
+              + " --experimental_execution_log_file (unordered binary protobuf format),"
+              + " --subcommands (for displaying subcommands in terminal output).")
   public PathFragment executionLogBinaryFile;
 
   @Option(
@@ -442,7 +452,11 @@
       converter = OptionsUtils.PathFragmentConverter.class,
       help =
           "Log the executed spawns into this file as json representation of the delimited Spawn"
-              + " protos. Related flags: --execution_log_binary_file (binary protobuf format),"
+              + " protos, according to src/main/protobuf/spawn.proto. The log is first written"
+              + " unordered and is then, at the end of the invocation, sorted in a stable order"
+              + " (can be CPU and memory intensive). Related flags:"
+              + " Related flags: --execution_log_binary_file (ordered binary protobuf format),"
+              + " --experimental_execution_log_file (unordered binary protobuf format),"
               + " --subcommands (for displaying subcommands in terminal output).")
   public PathFragment executionLogJsonFile;