Merge pull request #451 from zapta/develop

Assorted apio changes

.gitignore

@@ -9,6 +9,7 @@
 *.swp
 *~
 .coverage
+.coverage.*
 .tox/
 .cache/
 .pytest_cache/
@@ -30,6 +31,8 @@ hardware.vlt
 hardware.bit
 hardware.config
 hardware.pnr
+hardware.dot
+hardware.svg
 *.out
 *.vcd
 .DS_Store

.vscode/launch.json

@@ -83,7 +83,8 @@
             "request": "launch",
             "program": "${workspaceFolder}/apio_run.py",
             "args": [
-                "examples"
+                "examples",
+                "--list"
             ],
             "console": "integratedTerminal",
             "justMyCode": false,
@@ -95,7 +96,8 @@
             "request": "launch",
             "program": "${workspaceFolder}/apio_run.py",
             "args": [
-                "graph"
+                "graph",
+                "--svg"
             ],
             "console": "integratedTerminal",
             "justMyCode": false,
@@ -144,6 +146,20 @@
             "justMyCode": false,
             "cwd": "${workspaceFolder}/test-examples/Alhambra-II/02-jumping-LED"
         },
+        {
+            "name": "Apio packages",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/apio_run.py",
+            "args": [
+                "packages",
+                "--install",
+                "--force"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": false,
+            "cwd": "${workspaceFolder}/test-examples/Alhambra-II/02-jumping-LED"
+        },
         {
             "name": "Apio raw",
             "type": "debugpy",
@@ -268,26 +284,14 @@
             "cwd": "${workspaceFolder}/test-examples/Alhambra-II/02-jumping-LED"
         },
         {
-            "name": "Scon (direct)",
+            "name": "Attach remote",
             "type": "debugpy",
-            "request": "launch",
-            "program": "${workspaceFolder}/scons_run.py",
-            "args": [
-                "-Q",  
-                "build", 
-                "fpga_model=iCE40-HX4K-TQ144",  
-                "fpga_arch=ice40",  
-                "fpga_size=4k",  
-                "fpga_type=hx",  
-                "fpga_pack=tq144", 
-                "top_module=main",
-                "-f",
-                "${workspaceFolder}/apio/scons/ice40/SConstruct",
-                "force_colors=True"
-            ],
-            "console": "integratedTerminal",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5678
+            },
             "justMyCode": false,
-            "cwd": "${workspaceFolder}/test-examples/Alhambra-II/02-jumping-LED"
         },
     ]
 }

DEVELOPER.md

@@ -33,9 +33,16 @@ python apio_run.py build --project_dir ~/projects/fpga/repo/hdl
 The ``apio`` repository contains at its root the file ``.vscode/launch.json`` with debug
 target for most of the ``apio`` commands. Make sure to open the roo folder of the repository for VSC to recognize the targets file. To select the debug target, click on the debug icon on the left sidebar and this will display above a pull down menu with the available debug target and a start icon.
 
+[NOTE] This method doesn't not work for debugging the SConstruct scripts since they are run as subprocesses of the apio process. For debugging SConstruct scripts see the next section.
+
 The debug target can be viewed here https://github.com/FPGAwars/apio/blob/develop/.vscode/launch.json
 
 
+## Debugging SConstruct scripts (subprocesses) with Visual Studio Code.
+
+To debug the scons scripts, which are run as apio subprocesses, we use a different method or remote debugging. Enable the ``wait_for_remote_debugger(env)`` call in the SConstruct script, run apio from the command line, and once it reports that it waits for a debugger, run the VCS ``Attach remote`` debug target to connect to the SConstruct process.
+
+
 ## Using the dev repository for apio commands.
 
 You can tell pip to youse your apio dev repository for apio commands instead of the standard apio release. This allows quick edit/test cycles where you the modify code in your apio dev repository and  immediately test it by running ``apio`` commands in the console..

apio/__main__.py

@@ -38,6 +38,7 @@
     "Setup commands": [
         "create",
         "modify",
+        "packages",
         "drivers",
         "install",
         "uninstall",

apio/cmd_util.py

@@ -26,7 +26,7 @@ def fatal_usage_error(ctx: click.Context, msg: str) -> None:
     msg: A single line short error message.
     """
     # Mimiking the usage error message from click/exceptions.py.
-    # E.g. "Try 'apio install -h' for help."
+    # E.g. "Try 'apio packages -h' for help."
     click.secho(ctx.get_usage())
     click.secho(
         f"Try '{ctx.command_path} {ctx.help_option_names[0]}' for help."
@@ -116,7 +116,7 @@ def _specified_params(ctx: click.Context, param_ids: List[str]) -> List[str]:
     return result
 
 
-def check_exclusive_params(ctx: click.Context, param_ids: List[str]) -> None:
+def check_at_most_one_param(ctx: click.Context, param_ids: List[str]) -> None:
     """Checks that at most one of given params were specified in
     the command line. If more than one param was specified, exits the
     program with a message and error status.
@@ -135,7 +135,28 @@ def check_exclusive_params(ctx: click.Context, param_ids: List[str]) -> None:
         fatal_usage_error(ctx, f"{aliases_str} are mutually exclusive.")
 
 
-def check_required_params(ctx: click.Context, param_ids: List[str]) -> None:
+def check_exactly_one_param(ctx: click.Context, param_ids: List[str]) -> None:
+    """Checks that at exactly one of given params is specified in
+    the command line. If more or less than one params is specified, exits the
+    program with a message and error status.
+
+    Params are click options and arguments that are passed to a command.
+    Param ids are the names of variables that are used to pass options and
+    argument values to the command. A safe way to construct param_ids
+    is nameof(param_var1, param_var2, ...)
+    """
+    # The the subset of ids of params that where used in the command.
+    specified_param_ids = _specified_params(ctx, param_ids)
+    # If more 2 or more print an error and exit.
+    if len(specified_param_ids) != 1:
+        canonical_aliases = _params_ids_to_aliases(ctx, param_ids)
+        aliases_str = ", ".join(canonical_aliases)
+        fatal_usage_error(
+            ctx, f"Exactly one of of {aliases_str} must be specified."
+        )
+
+
+def check_at_least_one_param(ctx: click.Context, param_ids: List[str]) -> None:
     """Checks that at least one of given params is specified in
     the command line. If none of the params is specified, exits the
     program with a message and error status.

apio/commands/boards.py

@@ -45,8 +45,8 @@
   apio boards -f | grep gowin  # Filter FPGA results.
 
 [Advanced] Boards with wide availability can be added by contacting the
-apio team. A custom one-of board can be added to your project by
-placing a boards.json file next to apio.ini.
+apio team. Custom one-of boards can be added to your project by
+placing an alternative boards.json file in your apio project directory.
 """
 
 
@@ -72,10 +72,11 @@ def cli(
     """
 
     # Make sure these params are exclusive.
-    cmd_util.check_exclusive_params(ctx, nameof(list_, fpgas))
+    cmd_util.check_at_most_one_param(ctx, nameof(list_, fpgas))
 
-    # -- Access to the apio resources
-    resources = Resources(project_dir=project_dir)
+    # -- Access to the apio resources. We need project scope since the project
+    # -- may override the list of boards.
+    resources = Resources(project_dir=project_dir, project_scope=True)
 
     # -- Option 1: List boards
     if list_:

apio/commands/build.py

@@ -13,6 +13,7 @@
 from apio.managers.scons import SCons
 from apio import cmd_util
 from apio.commands import options
+from apio.resources import Resources
 
 
 # ---------------------------
@@ -27,8 +28,12 @@
 
 \b
 Examples:
-  apio build
-  apio build -v
+  apio build       # Build
+  apio build -v    # Build with verbose info
+
+The build command builds all the .v files (e.g. my_module.v) in the project
+directory except for those whose name ends with _tb (e.g. my_module_tb.v) to
+indicate that they are testbenches.
 """
 
 
@@ -75,7 +80,8 @@ def cli(
     # https://www.scons.org/documentation.html
 
     # -- Create the scons object
-    scons = SCons(project_dir)
+    resources = Resources(project_dir=project_dir, project_scope=True)
+    scons = SCons(resources)
 
     # R0801: Similar lines in 2 files
     # pylint: disable=R0801

apio/commands/clean.py

@@ -13,6 +13,7 @@
 from apio.managers.scons import SCons
 from apio import cmd_util
 from apio.commands import options
+from apio.resources import Resources
 
 
 # ---------------------------
@@ -56,7 +57,8 @@ def cli(
     """
 
     # -- Create the scons object
-    scons = SCons(project_dir)
+    resources = Resources(project_dir=project_dir, project_scope=True)
+    scons = SCons(resources)
 
     # -- Build the project with the given parameters
     exit_code = scons.clean({"board": board, "verbose": {"all": verbose}})

apio/commands/create.py

@@ -14,6 +14,7 @@
 from apio import util
 from apio import cmd_util
 from apio.commands import options
+from apio.resources import Resources
 
 
 # ---------------------------
@@ -74,10 +75,15 @@ def cli(
     if not top_module:
         top_module = DEFAULT_TOP_MODULE
 
+    # -- Load resources. We use project scope in case the project dir
+    # -- already has a custom boards.json file so we validate 'board'
+    # -- against that board list.
+    resources = Resources(project_dir=project_dir, project_scope=True)
+
     project_dir = util.get_project_dir(project_dir)
 
     # Create the apio.ini file
-    ok = Project.create_ini(project_dir, board, top_module, sayyes)
+    ok = Project.create_ini(resources, board, top_module, sayyes)
 
     exit_code = 0 if ok else 1
     ctx.exit(exit_code)

apio/commands/drivers.py

@@ -12,6 +12,7 @@
 from click.core import Context
 from apio.managers.drivers import Drivers
 from apio import cmd_util
+from apio.resources import Resources
 
 # ---------------------------
 # -- COMMAND SPECIFIC OPTIONS
@@ -91,12 +92,13 @@ def cli(
     """Implements the drivers command."""
 
     # Make sure these params are exclusive.
-    cmd_util.check_exclusive_params(
+    cmd_util.check_at_most_one_param(
         ctx, nameof(ftdi_enable, ftdi_disable, serial_enable, serial_disable)
     )
 
     # -- Access to the Drivers
-    drivers = Drivers()
+    resources = Resources(project_scope=False)
+    drivers = Drivers(resources)
 
     # -- FTDI enable option
     if ftdi_enable: