Refactor "Interpolation of Values"

ivankravets · ivankravets · commit 2f0abf6aba38 · 2021-10-24T18:15:42.000+03:00
diff --git a/envvars.rst b/envvars.rst
@@ -177,7 +177,7 @@ Examples:
 
 .. warning::
 
-    Consider using :ref:`projectconf_dynamic_vars` instead of ``PLATFORMIO_BUILD_FLAGS``
+    Consider using :ref:`projectconf_interpolation` instead of ``PLATFORMIO_BUILD_FLAGS``
     environment variable if additional build flags contain preprocessor directive with
     special characters (``$``, ``&``, ``~``, etc) in its value.
 
diff --git a/platforms/atmelavr_extra.rst b/platforms/atmelavr_extra.rst
@@ -44,7 +44,7 @@ Configuration for the programmers:
         upload_flags =
             -C
             ; use "tool-avrdude-megaavr" for the atmelmegaavr platform
-            $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
+            ${platformio.packages_dir}/tool-avrdude/avrdude.conf
             -p
             $BOARD_MCU
             -P
@@ -67,7 +67,7 @@ Configuration for the programmers:
         upload_flags =
             -C
             ; use "tool-avrdude-megaavr" for the atmelmegaavr platform
-            $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
+            ${platformio.packages_dir}/tool-avrdude/avrdude.conf
             -p
             $BOARD_MCU
             -P
@@ -92,7 +92,7 @@ Configuration for the programmers:
         upload_flags =
             -C
             ; use "tool-avrdude-megaavr" for the atmelmegaavr platform
-            $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
+            ${platformio.packages_dir}/tool-avrdude/avrdude.conf
             -p
             $BOARD_MCU
             -c
@@ -112,7 +112,7 @@ Configuration for the programmers:
         upload_flags =
             -C
             ; use "tool-avrdude-megaavr" for the atmelmegaavr platform
-            $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
+            ${platformio.packages_dir}/tool-avrdude/avrdude.conf
             -p
             $BOARD_MCU
             -P
@@ -135,7 +135,7 @@ Configuration for the programmers:
         upload_flags =
             -C
             ; use "tool-avrdude-megaavr" for the atmelmegaavr platform
-            $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
+            ${platformio.packages_dir}/tool-avrdude/avrdude.conf
             -p
             $BOARD_MCU
             -P
@@ -155,7 +155,7 @@ Configuration for the programmers:
         upload_flags =
             -C
             ; use "tool-avrdude-megaavr" for the atmelmegaavr platform
-            $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
+            ${platformio.packages_dir}/tool-avrdude/avrdude.conf
             -p
             $BOARD_MCU
             -c
@@ -176,7 +176,7 @@ Configuration for the programmers:
         upload_flags =
             -C
             ; use "tool-avrdude-megaavr" for the atmelmegaavr platform
-            $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
+            ${platformio.packages_dir}/tool-avrdude/avrdude.conf
             -p
             $BOARD_MCU
             -P
diff --git a/projectconf/index.rst b/projectconf/index.rst
@@ -40,8 +40,8 @@ sections and their allowed contents:
 
     section_platformio
     section_env
+    interpolation
     build_configurations
-    dynamic_variables
     examples
 
 **Example**
@@ -53,9 +53,8 @@ For more examples, see :ref:`projectconf_examples`.
     [platformio]
     default_envs = nodemcuv2
 
-    ; You MUST inject these options into [env:] section
-    ; using ${common_env_data.***} (see below)
-    [common_env_data]
+    ; Set/override default options for each "[env:***]"
+    [env]
     build_flags =
         -D VERSION=1.2.3
         -D DEBUG=1
@@ -74,14 +73,14 @@ For more examples, see :ref:`projectconf_examples`.
 
     ; Build options
     build_flags =
-        ${common_env_data.build_flags}
+        ${env.build_flags}
         -DSSID_NAME=HELLO
         -DSSID_PASWORD=WORLD
 
     ; Library options
     lib_deps =
-        ${common_env_data.lib_deps_builtin}
-        ${common_env_data.lib_deps_external}
+        ${env.lib_deps_builtin}
+        ${env.lib_deps_external}
         https://github.com/me-no-dev/ESPAsyncTCP.git
         PubSubClient@2.6
         OneWire
@@ -100,17 +99,13 @@ For more examples, see :ref:`projectconf_examples`.
     framework = arduino
     board = bluepill_f103c8
 
-    ; Build options
-    build_flags = ${common_env_data.build_flags}
-
     ; Library options
-    lib_deps =
-        ${common_env_data.lib_deps_external}
+    lib_deps = ${env.lib_deps_external}
 
     ; Debug options
     debug_tool = custom
     debug_server =
-        JLinkGDBServer
+        ${platformio.packages_dir}/tool-jlink/JLinkGDBServer
         -singlerun
         -if
         SWD
diff --git a/projectconf/interpolation.rst b/projectconf/interpolation.rst
@@ -9,24 +9,43 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 
-.. _projectconf_dynamic_vars:
+.. _projectconf_interpolation:
 
-Dynamic variables
------------------
+Interpolation of Values
+-----------------------
 
-Dynamic variables (interpolations) are useful when you have a custom
-configuration data between build environments. For examples, extra
-:ref:`projectconf_build_flags` or project dependencies :ref:`projectconf_lib_deps`.
+On top of the core functionality, PlatformIO supports interpolation. It enables values
+to contain format strings which refer to other values from foreign sections.
 
-Each variable should have a next format: ``${<section>.<option>}``, where
+Interpolation has the next syntax – ``${<section>.<option>}``, where
 ``<section>`` is a value from ``[<section>]`` group, and ``<option>`` is a
 first item from pair ``<option> = value``.
 
-You can inject system environment variable using ``sysenv`` as a ``section``.
-For example, ``${sysenv.HOME}``.
+.. list-table::
+    :header-rows:  1
 
-* Variable can be applied only for the option's value
-* Multiple variables are allowed
+    * - Syntax
+      - Meaning
+
+    * - ``${sysenv.<name>}``
+      - Embed system environment variable by a name. For example,
+        ``${sysenv.HOME}`` refers to user home directory on Unix machine
+
+    * - ``${platformio.<option>}``
+      - Embed value from :ref:`projectconf_section_platformio`. For example,
+        ``${platformio.packages_dir}`` refers to a path of :ref:`projectconf_pio_packages_dir`
+
+    * - ``${env.<option>}``
+      - Embed default value from :ref:`projectconf_section_env`. For example,
+        ``${env.debug_build_flags}`` refers to the default debugging flags.
+
+    * - ``${<section>.<option>}``
+      - Embed value from another section. For example, ``${extra.lib_deps}`` embeds
+        library dependencies declared in the section named ``extra``.
+
+* Interpolation can span multiple levels
+* Interpolation can be applied only for the option's value
+* Multiple interpolations are allowed
 * The :ref:`projectconf_section_platformio` and :ref:`projectconf_section_env`
   sections are reserved and could not be used as a custom section. Some good
   section names might be ``extra`` or ``custom``.
@@ -37,7 +56,7 @@ For example, ``${sysenv.HOME}``.
     :ref:`projectconf_section_env` or :ref:`projectconf_env_extends` option which
     allows extending of other sections.
 
-Example:
+**Example:**
 
 .. code-block:: ini
 
diff --git a/projectconf/section_env_advanced.rst b/projectconf/section_env_advanced.rst
@@ -26,7 +26,7 @@ in :ref:`projectconf`. Multiple items are allowed, split them with ``,`` or
 with a new line.
 
 If you need to extend only a few options from some section, please take a look at
-:ref:`projectconf_dynamic_vars`.
+:ref:`projectconf_interpolation`.
 
 Example:
 
diff --git a/projectconf/section_env_build.rst b/projectconf/section_env_build.rst
@@ -160,7 +160,7 @@ You can inject the built-in variables into your build flags, such as:
 * ``$PROJECT_BUILD_DIR``, project build directory per all environments
 * ``$BUILD_DIR``, build directory per current environment
 
-See the `full list of PlatformIO variables <https://github.com/platformio/platformio-core/blob/develop/platformio/builder/main.py#L99:L120>`_.
+See the `full list of PlatformIO variables <https://github.com/platformio/platformio-core/blob/develop/platformio/builder/main.py>`_.
 
 Please use target ``envdump`` for the :option:`pio run --target`
 command to see ALL variable values for a build environment.
diff --git a/projectconf/section_env_debug.rst b/projectconf/section_env_debug.rst
@@ -237,7 +237,7 @@ with a debugging server that is compatible with "on-board" debugging tool
 * First line is an executable path of debugging server
 * 2-nd and the next lines are arguments for executable file
 
-**Example:**
+**Examples:**
 
 .. code-block:: ini
 
@@ -251,6 +251,15 @@ with a debugging server that is compatible with "on-board" debugging tool
       ...
       argN
 
+    [env:debug_openocd]
+    platform = ...
+    board = ...
+    debug_tool = custom
+    debug_server =
+        ${platformio.packages_dir}/tool-openocd/openocd
+        -f
+        ${platformio.packages_dir}/tool-openocd/scripts/board/stm32f103zet6_warship.cfg
+
 .. _projectconf_debug_port:
 
 ``debug_port``
diff --git a/projectconf/section_env_library.rst b/projectconf/section_env_library.rst
@@ -34,7 +34,7 @@ Specify project dependencies that should be installed automatically to
 :ref:`projectconf_pio_libdeps_dir` before environment processing.
 
 If you have multiple build environments that depend on the same libraries,
-you can use :ref:`projectconf_dynamic_vars` to use common configuration.
+you can use :ref:`projectconf_interpolation` to use common configuration.
 
 **Valid forms**
 
diff --git a/projectconf/section_env_upload.rst b/projectconf/section_env_upload.rst
@@ -173,7 +173,7 @@ Default upload commands are declared in ``build/main.py`` script file of
     ``some-flash-bin-tool $UPLOADERFLAGS $SOURCE``, where
     ``$SOURCE`` will be replaced by a real program/firmware binary.
 
-    ``$PROJECT_PACKAGES_DIR`` build variable points to :ref:`projectconf_pio_packages_dir`.
+    ``${platformio.packages_dir}`` template points to :ref:`projectconf_pio_packages_dir`.
 
     .. code-block:: ini
 
@@ -184,7 +184,7 @@ Default upload commands are declared in ``build/main.py`` script file of
         upload_protocol = custom
         upload_flags =
             -C
-            $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
+            ${platformio.packages_dir}/tool-avrdude/avrdude.conf
             -p
             atmega328p
             -P
@@ -206,7 +206,7 @@ Default upload commands are declared in ``build/main.py`` script file of
         upload_protocol = custom
         upload_flags =
             -C
-            $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
+            ${platformio.packages_dir}/tool-avrdude/avrdude.conf
             -p
             atmega328p
             -Pusb
@@ -223,4 +223,4 @@ Default upload commands are declared in ``build/main.py`` script file of
         framework = stm32cube
         board = bluepill_f103c6
         upload_protocol = custom
-        upload_command = $PROJECT_PACKAGES_DIR/tool-stlink/st-flash write $SOURCE 0x8000000
+        upload_command = ${platformio.packages_dir}/tool-stlink/st-flash write $SOURCE 0x8000000
diff --git a/redirects.txt b/redirects.txt
