Merge pull request #445 from zapta/develop

Assorted apio changes

.gitignore

@@ -27,10 +27,11 @@ test-colorlight-v61.ice
 hardware.json
 hardware.out
 hardware.vlt
-*.out
-*.vcd
 hardware.bit
 hardware.config
+hardware.pnr
+*.out
+*.vcd
 .DS_Store
 abc.history
 temp-*

.vscode/launch.json

@@ -157,6 +157,18 @@
             "justMyCode": false,
             "cwd": "${workspaceFolder}/test-examples/Alhambra-II/02-jumping-LED"
         },
+        {
+            "name": "Apio report",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/apio_run.py",
+            "args": [
+                "report",
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": false,
+            "cwd": "${workspaceFolder}/test-examples/Alhambra-II/02-jumping-LED"
+        },
         {
             "name": "Apio system",
             "type": "debugpy",

apio/__main__.py

@@ -17,6 +17,40 @@
 import click
 from apio import util
 
+# -- Maps group title to command names. Controls how the 'apio -h' help
+# -- information is printed. Should include all commands and without
+# -- duplicates.
+COMMAND_GROUPS = {
+    "Build commands": [
+        "build",
+        "upload",
+        "clean",
+    ],
+    "Verification commands": [
+        "verify",
+        "lint",
+        "sim",
+        "test",
+        "time",
+        "report",
+        "graph",
+    ],
+    "Setup commands": [
+        "create",
+        "modify",
+        "drivers",
+        "install",
+        "uninstall",
+    ],
+    "Utility commands": [
+        "boards",
+        "examples",
+        "raw",
+        "system",
+        "upgrade",
+    ],
+}
+
 
 def select_commands_help(
     command_lines: List[str], command_names: List[str]
@@ -70,55 +104,30 @@ def reformat_apio_help(original_help: str) -> str:
     index += 1  # Skip the Commands: line.
     command_lines = help_lines[index:]
 
-    # -- Select project commands by the order they are listed here.
-    project_help = select_commands_help(
-        command_lines,
-        [
-            "build",
-            "clean",
-            "verify",
-            "sim",
-            "test",
-            "lint",
-            "upload",
-            "time",
-            "graph",
-        ],
-    )
-    # -- Select setup commands by the order they are listed here.
-    setup_help = select_commands_help(
-        command_lines,
-        ["create", "modify", "drivers", "install", "uninstall"],
-    )
-
-    # -- Select utility commands  by the order they are listed here.
-    utility_help = select_commands_help(
-        command_lines,
-        ["boards", "examples", "raw", "system", "upgrade"],
-    )
-
-    # -- Sanity check, in case we mispelled or ommited a command name.
-    num_selected = len(project_help) + len(setup_help) + len(utility_help)
-    assert len(command_lines) == num_selected
-
     # -- Header
     result = []
     result.extend(header_lines)
 
-    # -- Project commands:
-    result.append("Project commands:")
-    result.extend(project_help)
-    result.append("")
-
-    # -- Setup commands:
-    result.append("Setup commands:")
-    result.extend(setup_help)
-    result.append("")
-
-    # -- Print utility commands:
-    result.append("Utility commands:")
-    result.extend(utility_help)
-    result.append("")
+    # -- Print the help of the command groups while verifying that there
+    # -- are no missing or duplicate commands.
+    reported_commands = set()
+    for group_title, command_names in COMMAND_GROUPS.items():
+        # -- Assert no duplicates inter and intra groups.
+        assert len(command_names) == len(set(command_names))
+        assert reported_commands.isdisjoint(command_names)
+        reported_commands.update(command_names)
+        # -- Select the help lines of the commands in this group.
+        group_help = select_commands_help(command_lines, command_names)
+        # -- Append the group title and command lines.
+        result.append(f"{group_title}:")
+        result.extend(group_help)
+        result.append("")
+
+    # -- If this assertion fails, for a missing command in the groups
+    # -- definitions.
+    assert len(command_lines) == len(
+        reported_commands
+    ), f"{command_lines=}, {len(reported_commands)=}"
 
     return "\n".join(result)
 

apio/commands/build.py

@@ -47,10 +47,10 @@
 @options.verbose_pnr_option
 @options.top_module_option_gen(deprecated=True)
 @options.board_option_gen(deprecated=True)
-@options.fpga_option
-@options.size_option
-@options.type_option
-@options.pack_option
+@options.fpga_option_gen(deprecated=True)
+@options.size_option_gen(deprecated=True)
+@options.type_option_gen(deprecated=True)
+@options.pack_option_gen(deprecated=True)
 def cli(
     ctx: Context,
     # Options

apio/commands/clean.py

@@ -35,7 +35,7 @@
 
 @click.command(
     "clean",
-    short_help="Clean the apio generated files.",
+    short_help="Delete the apio generated files.",
     help=HELP,
     cls=cmd_util.ApioCommand,
 )

apio/commands/graph.py

@@ -8,6 +8,7 @@
 """Implementation of 'apio graph' command"""
 
 from pathlib import Path
+import shutil
 import click
 from click.core import Context
 from apio.managers.scons import SCons
@@ -38,6 +39,14 @@
 to the desired format using the dot command.
 """
 
+DOT_HELP = """
+The 'dot' command is part of the 'graphviz' suite. Please install
+it per the instructions at https://graphviz.org/download and run
+this command again. If you think that the 'dot' command is available
+on the system path, you can try supressing this error message by
+adding the --force flag to the apio graph command.
+"""
+
 
 @click.command(
     "graph",
@@ -48,16 +57,38 @@
 @click.pass_context
 @options.project_dir_option
 @options.top_module_option_gen(help="Set the name of the top module to graph.")
+@options.force_option_gen(help="Force execution despite no 'dot' command.")
 @options.verbose_option
 def cli(
     ctx: Context,
     # Options
     project_dir: Path,
+    force: bool,
     verbose: bool,
     top_module: str,
 ):
     """Implements the apio graph command."""
 
+    # -- This program requires a user install graphviz 'dot' available on
+    # -- the path. Verify it.
+    dot_path = shutil.which("dot")
+    if not dot_path:
+        if force:
+            # -- Just print a warning and continue.
+            click.secho(
+                "Warning: Skipping the check for the 'dot' command.",
+                fg="yellow",
+            )
+        else:
+            # -- Print an error message and abort.
+            click.secho()
+            click.secho(
+                "Error: The 'dot' command was not found on the system path.",
+                fg="red",
+            )
+            click.secho(DOT_HELP, fg="yellow")
+            ctx.exit(1)
+
     # -- Crete the scons object
     scons = SCons(project_dir)
 

apio/commands/install.py

@@ -19,19 +19,26 @@
 
 
 def install_packages(
-    packages: list, platform: str, resources: Resources, force: bool
+    packages: list,
+    platform: str,
+    resources: Resources,
+    force: bool,
+    verbose: bool,
 ):
     """Install the apio packages passed as a list
     * INPUTS:
       - packages: List of packages (Ex. ['examples', 'oss-cad-suite'])
       - platform: Specific platform (Advanced, just for developers)
       - force: Force package installation
+      - verbose: Show detailed output.
     """
     # -- Install packages, one by one...
     for package in packages:
 
         # -- The instalation is performed by the Installer object
-        modifiers = Installer.Modifiers(force=force, checkversion=True)
+        modifiers = Installer.Modifiers(
+            force=force, checkversion=True, verbose=verbose
+        )
         installer = Installer(package, platform, resources, modifiers)
 
         # -- Install the package!
@@ -71,6 +78,7 @@ def install_packages(
 @options.force_option_gen(help="Force the packages installation.")
 @options.project_dir_option
 @options.platform_option
+@options.verbose_option
 def cli(
     ctx: Context,
     # Arguments
@@ -81,6 +89,7 @@ def cli(
     force: bool,
     platform: str,
     project_dir: Path,
+    verbose: bool,
 ):
     """Implements the install command which allows to
     manage the installation of apio packages.
@@ -94,13 +103,15 @@ def cli(
 
     # -- Install the given apio packages
     if packages:
-        install_packages(packages, platform, resources, force)
+        install_packages(packages, platform, resources, force, verbose)
         ctx.exit(0)
 
     # -- Install all the available packages (if any)
     if all_:
         # -- Install all the available packages for this platform!
-        install_packages(resources.packages, platform, resources, force)
+        install_packages(
+            resources.packages, platform, resources, force, verbose
+        )
         ctx.exit(0)
 
     # -- List all the packages (installed or not)