pw_emu: Add user APIs and the command line interface

Add the user APIs, the command line interface, as well as related tests and documentation. Change-Id: I8990acc938dc918331508fc18fb1b2863d9adeed Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/173611 Presubmit-Verified: CQ Bot Account <[email protected]> Commit-Queue: Octavian Purdila <[email protected]> Reviewed-by: Armando Montanez <[email protected]>
google · Oct 13, 2023 · 842b244 · 842b244
1 parent dd397f9
commit 842b244
Show file tree

Hide file tree

Showing 11 changed files with 1,227 additions and 0 deletions.
diff --git a/pigweed.json b/pigweed.json
@@ -23,6 +23,10 @@
           "module": "pw_system.console",
           "function": "main"
         },
+        "emu": {
+          "module": "pw_emu.__main__",
+          "function": "main"
+        },
         "format": {
           "module": "pw_presubmit.format_code",
           "function": "main"

diff --git a/pw_cli/py/pw_cli/pw_command_plugins.py b/pw_cli/py/pw_cli/pw_command_plugins.py
@@ -31,6 +31,7 @@ def _register_builtin_plugins(registry: plugins.Registry) -> None:
     # Register these by name to avoid circular dependencies.
     registry.register_by_name('bloat', 'pw_bloat.__main__', 'main')
     registry.register_by_name('doctor', 'pw_doctor.doctor', 'main')
+    registry.register_by_name('emu', 'pw_emu.__main__', 'main')
     registry.register_by_name('format', 'pw_presubmit.format_code', 'main')
     registry.register_by_name('keep-sorted', 'pw_presubmit.keep_sorted', 'main')
     registry.register_by_name('logdemo', 'pw_cli.log', 'main')

diff --git a/pw_emu/api.rst b/pw_emu/api.rst
@@ -7,6 +7,9 @@ API reference
    :name: pw_emu
    :tagline: Emulators frontend
 
+.. automodule:: pw_emu.frontend
+   :members:
+
 .. automodule:: pw_emu.core
    :noindex:
    :members:

diff --git a/pw_emu/cli.rst b/pw_emu/cli.rst
@@ -6,3 +6,11 @@ CLI reference
 .. pigweed-module-subpage::
    :name: pw_emu
    :tagline: Pigweed emulator frontend
+
+.. argparse::
+   :module: pw_emu.__main__
+   :func: get_parser
+   :prog: pw emu
+   :nodefaultconst:
+   :nodescription:
+   :noepilog:
diff --git a/pw_emu/design.rst b/pw_emu/design.rst
@@ -19,6 +19,8 @@ how to access the emulator channels (e.g. socket ports, pty paths)
 .. mermaid::
 
    graph TD;
+       TemporaryEmulator & pw_emu_cli[pw emu cli] <--> Emulator
+       Emulator <--> Launcher & Connector
        Launcher  <--> Handles
        Connector <--> Handles
        Launcher <--> Config
@@ -28,6 +30,8 @@ how to access the emulator channels (e.g. socket ports, pty paths)
 
 The implementation uses the following classes:
 
+* :py:class:`pw_emu.frontend.Emulator`: the user visible API
+
 * :py:class:`pw_emu.core.Launcher`: an abstract class that starts an
   emulator instance for a given configuration and target
 

diff --git a/pw_emu/py/BUILD.gn b/pw_emu/py/BUILD.gn
@@ -24,13 +24,17 @@ pw_python_package("py") {
   ]
   sources = [
     "pw_emu/__init__.py",
+    "pw_emu/__main__.py",
     "pw_emu/core.py",
+    "pw_emu/frontend.py",
     "pw_emu/pigweed_emulators.py",
   ]
   tests = [
     "tests/__init__.py",
+    "tests/cli_test.py",
     "tests/common.py",
     "tests/core_test.py",
+    "tests/frontend_test.py",
   ]
   pylintrc = "$dir_pigweed/.pylintrc"
   mypy_ini = "$dir_pigweed/.mypy.ini"