Incremental Project Synchronisation for PIO Plus // Resolve #825

docs/envvars.rst

@@ -103,6 +103,10 @@ Allows to override :ref:`projectconf` option :ref:`projectconf_pio_test_dir`.
 
 Allows to override :ref:`projectconf` option :ref:`projectconf_pio_boards_dir`.
 
+.. envvar:: PLATFORMIO_REMOTE_AGENT_DIR
+
+Allows to override :option:`platformio remote agent start --working-dir`.
+
 Building
 --------
 

docs/plus/unit-testing.rst

@@ -48,7 +48,7 @@ test on a host machine (desktop).
 .. note::
     PlatformIO does not install any toolchains automatically for
     :ref:`platform_native` and requires ``GCC`` toolchain to be installed
-    on your local machine.
+    on your host machine.
     Please open Terminal and check that ``gcc`` command is installed.
 
 Embedded

docs/userguide/remote/cmd_agent.rst

@@ -101,6 +101,12 @@ Share your agent/devices with other PlatformIO developers who have
 The valid value for ``--share`` option is E-Mail address that was used for
 :ref:`cmd_account_register` command.
 
+.. option::
+    -d, --working-dir
+
+A working directory where :ref:`cmd_remote_agent` stores projects data for
+incremental synchronization and embedded programs for PIO Process Supervisor.
+
 ------------
 
 platformio remote agent reload

docs/userguide/remote/cmd_run.rst

@@ -33,13 +33,13 @@ Description
 -----------
 
 Process remotely environments which are defined in :ref:`projectconf` file.
-By default, :ref:`pio_remote` builds project on the local machine and deploy
-final firmware Over-The-Air (OTA) to remote device.
+By default, :ref:`pio_remote` builds project on a host machine and deploy
+final firmware Over-The-Air (OTA) to remote device (embedded board).
 
-If you need to build project on remote machine, please use
-:option:`platformio remote run --build-remotely` option. In this case,
-:ref:`pio_remote` will automatically deploy your project to remote machine,
-install required toolchains, frameworks, SDKs, etc and build/upload firmware.
+If you need to process project on remote machine, please use
+:option:`platformio remote run --force-remote` option. In this case,
+:ref:`pio_remote` will automatically synchronize your project with remote machine,
+install required toolchains, frameworks, SDKs, etc., and process project.
 
 
 Options
@@ -101,15 +101,15 @@ Disable auto-clean of :ref:`projectconf_pio_envs_dir` when :ref:`projectconf`
 or :ref:`projectconf_pio_src_dir` (project structure) have been modified.
 
 .. option::
-    -r, --build-remotely
+    -r, --force-remote
 
-By default, :ref:`pio_remote` builds project on the local machine and deploy
-final firmware Over-The-Air (OTA) to remote device.
+By default, :ref:`pio_remote` builds project on a host machine and deploy
+final firmware Over-The-Air (OTA) to remote device (embedded board).
 
-If you need to build project on remote machine, please use
-:option:`platformio remote run --build-remotely` option. In this case,
-:ref:`pio_remote` will automatically deploy your project to remote machine,
-install required toolchains, frameworks, SDKs, etc and build/upload firmware.
+If you need to process project on remote machine, please use
+:option:`platformio remote run --force-remote` option. In this case,
+:ref:`pio_remote` will automatically synchronize your project with remote machine,
+install required toolchains, frameworks, SDKs, etc., and process project.
 
 Example
 -------

docs/userguide/remote/cmd_test.rst

@@ -99,15 +99,15 @@ Specify the path to project directory. By default, ``--project-dir`` is equal
 to current working directory (``CWD``).
 
 .. option::
-    -r, --build-remotely
+    -r, --force-remote
 
-By default, :ref:`pio_remote` builds project on the local machine and deploy
-final testing firmware Over-The-Air (OTA) to remote device.
+By default, :ref:`pio_remote` processes project on a host machine and deploy
+final testing firmware Over-The-Air (OTA) to remote device (embedded board).
 
-If you need to build project on remote machine, please use
-:option:`platformio remote test --build-remotely` option. In this case,
-:ref:`pio_remote` will automatically deploy your project to remote machine,
-install required toolchains, frameworks, SDKs, etc and process tests.
+If you need to process project on remote machine, please use
+:option:`platformio remote test --force-remote` option. In this case,
+:ref:`pio_remote` will automatically synchronize your project with remote machine,
+install required toolchains, frameworks, SDKs, etc., and process project.
 
 
 .. option::

platformio/commands/remote.py

@@ -42,6 +42,15 @@ def remote_agent():
 @remote_agent.command("start", short_help="Start agent")
 @click.option("-n", "--name")
 @click.option("-s", "--share", multiple=True, metavar="E-MAIL")
+@click.option(
+    "-d",
+    "--working-dir",
+    envvar="PLATFORMIO_REMOTE_AGENT_DIR",
+    type=click.Path(
+        file_okay=False,
+        dir_okay=True,
+        writable=True,
+        resolve_path=True))
 def remote_agent_start(**kwargs):
     pioplus_call(sys.argv[1:])
 
@@ -82,7 +91,7 @@ def remote_update(only_check):
         writable=True,
         resolve_path=True))
 @click.option("--disable-auto-clean", is_flag=True)
-@click.option("-r", "--build-remotely", is_flag=True)
+@click.option("-r", "--force-remote", is_flag=True)
 @click.option("-s", "--silent", is_flag=True)
 @click.option("-v", "--verbose", is_flag=True)
 def remote_run(**kwargs):
@@ -104,7 +113,7 @@ def remote_run(**kwargs):
         dir_okay=True,
         writable=True,
         resolve_path=True))
-@click.option("-r", "--build-remotely", is_flag=True)
+@click.option("-r", "--force-remote", is_flag=True)
 @click.option("--without-building", is_flag=True)
 @click.option("--without-uploading", is_flag=True)
 @click.option("--verbose", "-v", is_flag=True)