Toolkit architecture and extension¶
UCM Toolkit gives prechecks, metric inspection and native performance tests one command entry point. Tools have different dependencies: the CLI dispatches commands, while each Adapter owns its parameters, resource paths and execution. Toolkit is a separate Python package; see installation and usage.
How one command runs¶
For ucm-toolkit run dev-sandbox copy ...:
cli.main()initializes built-in registration and recognizesrun.commands/run.pyresolves the tool name or alias and passes remaining arguments to its Adapter.DevSandboxToolresolves the copy binary frombuild_dirandsubcommandsand forwards native arguments.runner.pylaunches the subprocess and returns its exit code. The CLI turnsToolkitErrorinto a readable error and exit status.
The top-level CLI does not interpret copy cases or device settings. In dev-sandbox friendly mode, its Adapter maps --model-type, --iodirect and --sdma to an existing Ascend copy case and forwards remaining arguments.
Module responsibilities¶
| Module | Responsibility |
|---|---|
cli.py and commands/ |
Parse the top-level action, select a tool and return its result |
registry.py |
Own tool objects/aliases, define ToolAdapter and resolve repository-relative paths |
tools/<tool>/ |
Own tool parameters, dependency checks, build, execution and cleanup |
runner.py |
Check commands, run subprocesses and propagate failures |
errors.py |
Define readable CLI errors and exit codes |
list shows top-level tools and doctor checks their environments. Only buildable tools enter build, currently dev-sandbox. Internal subcommands are exposed through the tool's own help.
Build directories and runtime resources¶
DevSandboxTool reads CMake/C++ sources from the installed package and runs configure and build. Outputs default to a user cache directory isolated by installation and Toolkit version. An explicit --build-dir is resolved against the working directory and saved as an absolute path only after a successful build.
run, doctor, and clean share that user state without editing Adapter source files. clean --dry-run displays the target; cleanup verifies that it is a CMake build of this dev-sandbox.
Add a tool¶
- Implement
ToolAdapterundertools/with a unique name, aliases and description. Keep tool-specific paths and rules in that module. - Implement
run(tool_args)anddoctor(). For compilation, declarebuildable=Trueand implement build arguments andbuild(). Clean only actual generated outputs. - Import and register an instance in
init_builtin_tools(). Registry rejects duplicate names and aliases. - Call the runner with argument lists. Keep tool semantics in the Adapter rather than coupling top-level CLI branches to one tool.
- Update the user guide and verify list, help, doctor and run exit codes, plus build/cleanup when applicable.
See tools/nic_monitor/ for script execution and tools/dev_sandbox/adapter.py for native builds. A tool need not support every lifecycle action; use existing errors for unsupported operations.
Maintenance and verification¶
Focus unit checks on dispatch, argument forwarding and errors. Native builds and bandwidth measurements require the corresponding hardware and runtime; successful CLI dispatch is separate evidence. See precheck for thresholds and results and dev sandbox for native development.