Merge pull request #858 from zapta/main

Added support for macros within apio.ini values.

Author: zapta

apio/managers/project.py

@@ -20,6 +20,7 @@
 from apio.utils import util
 from apio.common.apio_console import cout, cerror, cwarning
 from apio.common.apio_styles import INFO, SUCCESS, EMPH2
+from apio.common.common_util import PROJECT_BUILD_PATH
 
 
 DEFAULT_TOP_MODULE = "main"
@@ -343,11 +344,10 @@ def _determine_default_env_name(
         return env_name
 
     @staticmethod
-    def _unescape_value(s: str) -> str:
-        """Unescape # and ; in values. This allows to add these two
-        chars in values."""
-        s = s.replace("\\#", "#")
-        s = s.replace("\\;", ";")
+    def _expand_value(s: str, macros: Dict[str, str]) -> str:
+        """Expand macros by replacing macros keys with macro values."""
+        for k, v in macros.items():
+            s = s.replace(k, v)
         return s
 
     @staticmethod
@@ -361,6 +361,18 @@ def _parse_env_options(
         and list options are returned as list of strings.
         """
 
+        # -- Key/Value dict for macro expansion.
+        macros = {
+            # -- The ';' char.  (de-conflicted from ; comment)
+            "{semicolon}": ";",
+            # -- The '#' char.  (de-conflicted from # comment)
+            "{hash}": "#",
+            # -- The env name.
+            "{env-name}": env_name,
+            # -- The relative path to env build directory (linux / style)
+            "{env-build}": (PROJECT_BUILD_PATH / env_name).as_posix(),
+        }
+
         # -- Select the env section by name.
         env_section = env_sections[env_name]
 
@@ -372,11 +384,11 @@ def _parse_env_options(
         # -- Add common options that are not in env section
         for name, val in common_section.items():
             if name not in env_section:
-                result[name] = Project._unescape_value(val)
+                result[name] = Project._expand_value(val, macros)
 
         # -- Add all the options from the env section.
         for name, val in env_section.items():
-            result[name] = Project._unescape_value(val)
+            result[name] = Project._expand_value(val, macros)
 
         # -- check that all the required options exist.
         for option_spec in ENV_OPTIONS_SPEC.values():

docs/project-file.md

@@ -38,10 +38,23 @@ At runtime, apio select the env to use based using the following rules in decrea
 2. The value of the `default-env` option in the `[apio]` section, if exists.
 3. The first env that is listed in `apio.ini`.
 
+
 When apio determines the env to use, it collects its options
 from the `[common]` and the [env:name] section, with options in the `[env:name]` section
 having higher priority, and executes the command with the resolved set options.
 
+## Value macros
+
+When processing env values, apio replaces the following macros with their
+respective values.
+
+| MACRO_NAME    | VALUE                                                            |
+| :------------ | :--------------------------------------------------------------- |
+| `{semicolon}` | The character `;`                                                |
+| `{hash}`      | The character `#`                                                |
+| `{env-name}`  | The env name, e.g. `my-env`.                                     |
+| `{env-build}` | The posix path of the env build directory, e.g. `_build/my-env`. |
+
 ---
 
 ## The \[apio] section
@@ -92,11 +105,11 @@ board ID must be from that file.
 
 The optional `constraint-file` option allows to specify the constraint file
 (aka pinout file) and to use different constraint file for different envs. Its
-value is a relative path to a constraint file under the project's root. 
+value is a relative path to a constraint file under the project's root.
 The constraint file extension must be the one expected by the
 FPGA architecture, for example `.lpf` for ICE40 architecture.
 
-If `constraint-file` is not specified and the project directory tree 
+If `constraint-file` is not specified and the project directory tree
 contains exactly one file with the expected extension, that files is used
 automatically as the constraint file, otherwise Apio exists with an error
 message.
@@ -233,6 +246,7 @@ verilator command that that is invoked by the `apio lint`. For a list of
 verilator's command line options type `apio raw -- verilator --help`.
 
 Example:
+
 ```
 [env:default]
 verilator-extra-options =
@@ -255,8 +269,8 @@ yosys-extra-options =
     -verbose
 ```
 
-In the example below, the command `write_verilog` is added to the Yosys 
-build command to generate all file `_build/default/hardware-synth.v` with
+In the example below, the command `write_verilog` is added to the Yosys
+build command to generate all file `_build/default/yosys-synth.v` with
 a flattened representation of the synthesized design. This is helpful when
 diagnosing Yosys related synthesis issues.
 
@@ -265,5 +279,6 @@ diagnosing Yosys related synthesis issues.
 board = alhambra-ii
 top-module = leds
 yosys-extra-options =
-  \; write_verilog _build/my-env/hardware-synth.v
+  {semicolon} write_verilog {env-build}/yosys-synth.v
 ``
+```

tests/unit_tests/managers/test_project.py

@@ -155,17 +155,17 @@ def test_list_options(apio_runner: ApioRunner, capsys: LogCaptureFixture):
     ]
 
 
-def test_escaping(apio_runner: ApioRunner, capsys: LogCaptureFixture):
-    """Tests escaping of comment markers in values.."""
+def test_macro_expansion(apio_runner: ApioRunner, capsys: LogCaptureFixture):
+    """Tests the expansion of macros within values."""
 
     project, _ = load_apio_ini(
         apio_ini={
             "[env:default]": {
                 "board": "alhambra-ii",
                 "top-module": "my_top_module",
-                "constraint-file": " \\; value ",
-                "yosys-extra-options": "  k1=\\;v1  k2=v2; \n ; "
-                "Comment \n k3=v3\\# \n\n",
+                "constraint-file": " {semicolon} value ",
+                "yosys-extra-options": "  k1={env-build}/v1  k2=v2; \n ; "
+                "Comment \n k3=v3{hash} {env-name}\n\n",
             }
         },
         env_arg=None,
@@ -176,8 +176,8 @@ def test_escaping(apio_runner: ApioRunner, capsys: LogCaptureFixture):
     assert project.get_str_option("constraint-file") == "; value"
 
     assert project.get_list_option("yosys-extra-options") == [
-        "k1=;v1  k2=v2;",
-        "k3=v3#",
+        "k1=_build/default/v1  k2=v2;",
+        "k3=v3# default",
     ]