From af8b772560301f89de251dc494b3c5669451c5df Mon Sep 17 00:00:00 2001 From: ccalvarin Date: Wed, 6 Jun 2018 11:54:00 -0700 Subject: [PATCH] Mark --batch as deprecated in the documentation. RELNOTES: None. PiperOrigin-RevId: 199503117 --- site/docs/user-manual.html | 61 ++++++++----------- .../runtime/BlazeServerStartupOptions.java | 4 +- 2 files changed, 29 insertions(+), 36 deletions(-) diff --git a/site/docs/user-manual.html b/site/docs/user-manual.html index 8ae8b6c24a9360..40182e0554f6cf 100644 --- a/site/docs/user-manual.html +++ b/site/docs/user-manual.html @@ -83,7 +83,7 @@

Client/server implementation

workspace because their output bases will differ (different userids). If the client cannot find a running server instance, it starts a new one. The server process will stop after a period of inactivity (3 hours, - by default). + by default, which can be modified using the startup option --max_idle_secs).

For the most part, the fact that there is a server running is @@ -112,12 +112,6 @@

Client/server implementation

java.) Bazel servers can be stopped using the shutdown command.

-

- You can also run Bazel in batch mode using the --batch - startup flag. This will immediately shut down the process after the - command (build, test, etc.) has finished and not keep a server process - around. -

When running bazel, the client first checks that the @@ -134,7 +128,7 @@

Bazel accepts many options. Typically, some of these are varied - frequently (e.g. --subcommands) while others stay the + frequently (for example, --subcommands) while others stay the same across several builds (e.g. --package_path). To avoid having to specify these unchanged options for every build (and other commands) Bazel allows you to specify options in a configuration file. @@ -287,7 +281,7 @@

Example
   # Bob's Bazel option defaults
 
-  startup --batch --host_jvm_args=-XX:-UseParallelGC
+  startup --host_jvm_args=-XX:-UseParallelGC
   import /home/bobs_project/bazelrc
   build --show_timestamps --keep_going --jobs 600
   build --color=yes
@@ -2574,7 +2568,7 @@ 
Significant options

 

 
 
 

@@ -3576,7 +3570,7 @@ 
--host_jvm_args=string
 

   That this does not affect any JVMs used by
-  subprocesses of Bazel: applications, tests, tools, etc.  To pass
+  subprocesses of Bazel: applications, tests, tools, and so on.  To pass
   JVM options to executable Java programs, whether run by bazel
   run or on the command-line, you should use
   the --jvm_flags argument which
@@ -3598,24 +3592,32 @@ 
--host_jvm_debug

 

 
 
--batch

+
+

+  WARNING: --batch is deprecated. For build isolation, we recommend
+  using the command option  --nokeep_state_after_build, which guarantees
+  that no incremental in-memory state is kept between builds. In order to restart the
+  Bazel server and JVM after a build, please explicitly do so using the “shutdown” command.
+

+
 

-  This switch will cause bazel to be run in batch mode, instead of the
-  standard client/server mode described above.
-  Doing so provides more predictable semantics with respect to signal handling,
-  job control, and environment variable inheritance, and is necessary for running
-  bazel in a chroot jail.
+  Batch mode causes Bazel to not use the standard client/server mode described
+  above, instead running a bazel java process for a
+  single command, which has been used for more predictable semantics with respect
+  to signal handling, job control, and environment variable inheritance, and is
+  necessary for running bazel in a chroot jail.
 

 
 

   Batch mode retains proper queueing semantics within the same output_base.
   That is, simultaneous invocations will be processed in order, without overlap.
-  If a batch mode bazel is run on a client with a running server, it first
+  If a batch mode Bazel is run on a client with a running server, it first
   kills the server before processing the command.
 

 
 

-  Bazel will run slower in batch mode, compared to client/server mode.
-  Among other things, the build file cache is memory-resident, so it is not
+  Bazel will run slower in batch mode, or with the alternatives described above.
+  This is because, among other things, the build file cache is memory-resident, so it is not
   preserved between sequential batch invocations.
   Therefore, using batch mode often makes more sense in cases where performance
   is less critical, such as continuous builds.
@@ -3757,25 +3759,14 @@ 
Choosing the output base

   have to wait for those commands to complete before it can continue.
 

 
-
Server or no server?

+
Notes about Server Mode

 
 

   By default, Bazel uses a long-running server process as an optimization; this
-  behavior can be disabled using the --batch option.  There's no hard and
-  fast rule about whether or not your script should use a server, but
-  in general, the trade-off is between performance and reliability.
-  The server mode makes a sequence of builds, especially incremental
-  builds, faster, but its behavior is more complex and more likely to
-  fail.  We recommend in most cases that you use batch mode unless
-  the performance advantage is critical.
-

-

-  If you do use the server, don't forget to call shutdown
-  when you're finished with it, or, specify
-  --max_idle_secs=5 so that idle servers shut themselves
-  down promptly.
+  href='#client/server'>server process as an optimization. When running Bazel
+  in a script, don't forget to call shutdown when you're finished
+  with the server, or, specify --max_idle_secs=5 so
+  that idle servers shut themselves down promptly.
 

 
 
What exit code will I get?

diff --git a/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java b/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
index 1ec6e13d887d34..a79eb773b3bfc4 100644
--- a/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
@@ -210,9 +210,11 @@ public String getTypeDescription() {
       OptionEffectTag.LOSES_INCREMENTAL_STATE,
       OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION
     },
+    metadataTags = {OptionMetadataTag.DEPRECATED},
     help =
         "If set, Blaze will be run as just a client process without a server, instead of in "
-            + "the standard client/server mode."
+            + "the standard client/server mode. This is deprecated and will be removed, please "
+            + "prefer shutting down the server explicitly if you wish to avoid lingering servers."
   )
   public boolean batch;