Deprecate --process-execution-cleanup-local-dirs in favor of `--pro…

…cess-execution-local-cleanup` (#11785)

This is shorter and more consistent with our other related options, like `--process-execution-local-cache` and `--process-execution-local-parallelism`.

[ci skip-rust]
[ci skip-build-wheels]

src/python/pants/engine/internals/scheduler.py

@@ -189,12 +189,12 @@ def __init__(
             lease_time_millis=LOCAL_STORE_LEASE_TIME_SECS * 1000,
         )
         exec_stategy_opts = PyExecutionStrategyOptions(
-            local_parallelism=execution_options.process_execution_local_parallelism,
-            remote_parallelism=execution_options.process_execution_remote_parallelism,
-            cleanup_local_dirs=execution_options.process_execution_cleanup_local_dirs,
             local_cache=execution_options.process_execution_local_cache,
             remote_cache_read=execution_options.remote_cache_read,
             remote_cache_write=execution_options.remote_cache_write,
+            local_cleanup=execution_options.process_execution_local_cleanup,
+            local_parallelism=execution_options.process_execution_local_parallelism,
+            remote_parallelism=execution_options.process_execution_remote_parallelism,
         )
 
         self._py_scheduler = native_engine.scheduler_create(

src/python/pants/option/global_options.py

@@ -125,14 +125,14 @@ class ExecutionOptions:
     remote_cache_read: bool
     remote_cache_write: bool
 
-    remote_instance_name: Optional[str]
-    remote_ca_certs_path: Optional[str]
+    remote_instance_name: str | None
+    remote_ca_certs_path: str | None
 
     process_execution_local_cache: bool
+    process_execution_local_cleanup: bool
     process_execution_local_parallelism: int
     process_execution_remote_parallelism: int
-    process_execution_cache_namespace: Optional[str]
-    process_execution_cleanup_local_dirs: bool
+    process_execution_cache_namespace: str | None
 
     remote_store_address: str | None
     remote_store_headers: dict[str, str]
@@ -255,7 +255,14 @@ def from_options(
             ),
             process_execution_local_parallelism=bootstrap_options.process_execution_local_parallelism,
             process_execution_remote_parallelism=bootstrap_options.process_execution_remote_parallelism,
-            process_execution_cleanup_local_dirs=bootstrap_options.process_execution_cleanup_local_dirs,
+            process_execution_local_cleanup=resolve_conflicting_options(
+                old_option="process_execution_cleanup_local_dirs",
+                new_option="process_execution_local_cleanup",
+                old_scope=GLOBAL_SCOPE,
+                new_scope=GLOBAL_SCOPE,
+                old_container=bootstrap_options,
+                new_container=bootstrap_options,
+            ),
             process_execution_cache_namespace=bootstrap_options.process_execution_cache_namespace,
             # Remote store setup.
             remote_store_address=remote_store_address,
@@ -324,7 +331,7 @@ def from_options(cls, options: OptionValueContainer) -> LocalStoreOptions:
     process_execution_local_parallelism=_CPU_COUNT,
     process_execution_remote_parallelism=128,
     process_execution_cache_namespace=None,
-    process_execution_cleanup_local_dirs=True,
+    process_execution_local_cleanup=True,
     process_execution_local_cache=True,
     # Remote store setup.
     remote_store_address=None,
@@ -836,7 +843,10 @@ def register_bootstrap_options(cls, register):
             type=bool,
             default=DEFAULT_EXECUTION_OPTIONS.process_execution_local_cache,
             advanced=True,
-            help="Whether to keep process executions in a local cache persisted to disk.",
+            help=(
+                "Whether to cache process executions in a local cache persisted to disk at "
+                "`--local-store-dir`."
+            ),
         )
         register(
             "--process-execution-use-local-cache",
@@ -849,13 +859,29 @@ def register_bootstrap_options(cls, register):
                 "Use the shorter `--process-execution-local-cache`, which behaves the same."
             ),
         )
+        register(
+            "--process-execution-local-cleanup",
+            type=bool,
+            default=DEFAULT_EXECUTION_OPTIONS.process_execution_local_cleanup,
+            advanced=True,
+            help=(
+                "If false, Pants will not clean up local directories used as chroots for running "
+                "processes. Pants will log their location so that you can inspect the chroot, and "
+                "run the `__run.sh` script to recreate the process using the same argv and "
+                "environment variables used by Pants. This option is useful for debugging."
+            ),
+        )
         register(
             "--process-execution-cleanup-local-dirs",
             type=bool,
-            default=True,
+            default=DEFAULT_EXECUTION_OPTIONS.process_execution_local_cleanup,
             advanced=True,
             help="Whether or not to cleanup directories used for local process execution "
             "(primarily useful for e.g. debugging).",
+            removal_version="2.5.0.dev0",
+            removal_hint=(
+                "Use the shorter `--process-execution-local-cleanup`, which behaves the same."
+            ),
         )
 
         register(

src/rust/engine/src/context.rs

@@ -87,7 +87,7 @@ pub struct RemotingOptions {
 pub struct ExecutionStrategyOptions {
   pub local_parallelism: usize,
   pub remote_parallelism: usize,
-  pub cleanup_local_dirs: bool,
+  pub local_cleanup: bool,
   pub local_cache: bool,
   pub remote_cache_read: bool,
   pub remote_cache_write: bool,
@@ -173,7 +173,7 @@ impl Core {
         executor.clone(),
         local_execution_root_dir.to_path_buf(),
         NamedCaches::new(named_caches_dir.to_path_buf()),
-        exec_strategy_opts.cleanup_local_dirs,
+        exec_strategy_opts.local_cleanup,
       )),
       exec_strategy_opts.local_parallelism,
     ));

src/rust/engine/src/externs/interface.rs

@@ -525,7 +525,7 @@ py_class!(class PyExecutionStrategyOptions |py| {
     _cls,
     local_parallelism: u64,
     remote_parallelism: u64,
-    cleanup_local_dirs: bool,
+    local_cleanup: bool,
     local_cache: bool,
     remote_cache_read: bool,
     remote_cache_write: bool
@@ -534,7 +534,7 @@ py_class!(class PyExecutionStrategyOptions |py| {
       ExecutionStrategyOptions {
         local_parallelism: local_parallelism as usize,
         remote_parallelism: remote_parallelism as usize,
-        cleanup_local_dirs,
+        local_cleanup,
         local_cache,
         remote_cache_read,
         remote_cache_write,