superrtl 0.2.0__tar.gz

superrtl-0.2.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# EDA Tools (installed by superrtl setup)
+.superrtl/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Temporary files
+*.tmp
+*.bak

superrtl-0.2.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- GitHub Actions CI/CD pipeline
+- PyPI publishing workflow
+
+## [0.2.0] - 2026-06-13
+
+### Added
+- **Automatic EDA tool installation**: `superrtl setup` command downloads OSS CAD Suite
+- **Docker support**: Complete Dockerfile with all EDA tools pre-installed
+- **Runtime environment management**: Automatic PATH configuration for local tools
+- **New CLI commands**: `setup`, `uninstall`, `check-tools`
+- **Cross-platform support**: Windows, Linux, macOS
+- **Comprehensive test suite**: 110 tests with 83% coverage
+
+### Changed
+- Migrated from bare subprocess calls to `run_command` wrapper
+- Updated MCP Server to use correct `@app.list_tools()` decorator API
+- Improved error handling in all tool wrappers
+- Updated testbench generator to handle modules without clock/reset
+
+### Fixed
+- Windows DLL dependency issues with iverilog
+- Unicode encoding issues in Windows console
+- Import order and unused import warnings
+- Resources path resolution for skills and templates
+
+## [0.1.0] - 2026-06-11
+
+### Added
+- Initial release
+- MCP Server with 6 tools
+- CLI with 8 commands
+- Verilog compilation (Icarus Verilog)
+- Verilog simulation (Icarus Verilog + vvp)
+- Lint checking (Verilator)
+- Synthesis checking (Yosys)
+- Testbench generation
+- VCD waveform analysis
+- Skills and templates resources
+
+[Unreleased]: https://github.com/RTL-Agent/SuperRTL/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/RTL-Agent/SuperRTL/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/RTL-Agent/SuperRTL/releases/tag/v0.1.0

superrtl-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RTL-Agent Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

superrtl-0.2.0/PKG-INFO

@@ -0,0 +1,360 @@
+Metadata-Version: 2.4
+Name: superrtl
+Version: 0.2.0
+Summary: Verilog EDA 工具的 MCP/CLI 客户端 - 一键安装，开箱即用
+Project-URL: Homepage, https://github.com/RTL-Agent/SuperRTL
+Project-URL: Repository, https://github.com/RTL-Agent/SuperRTL
+Project-URL: Documentation, https://github.com/RTL-Agent/SuperRTL#readme
+Project-URL: Issues, https://github.com/RTL-Agent/SuperRTL/issues
+Project-URL: Changelog, https://github.com/RTL-Agent/SuperRTL/blob/main/CHANGELOG.md
+Author-email: RTL-Agent Team <team@rtl-agent.dev>
+License: MIT
+License-File: LICENSE
+Keywords: eda,fpga,icarus,mcp,rtl,verilator,verilog,yosys
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SuperRTL
+
+> Verilog EDA 工具的 MCP/CLI 客户端
+
+---
+
+## 概述
+
+**SuperRTL** 将 Verilog EDA 工具链封装为标准 MCP 接口，支持：
+
+- **MCP Server 模式**：被 Claude Desktop、Cursor、Hermes Agent 等调用
+- **CLI 命令行模式**：独立使用，无需 MCP Host
+- **自动安装工具**：首次运行时自动下载 EDA 工具，无需手动配置
+
+---
+
+## 核心功能
+
+### MCP Tools
+
+| Tool | 命令 | 功能 | 依赖 |
+|------|------|------|------|
+| `compile_verilog` | `superrtl compile` | 编译 Verilog 代码 | Icarus Verilog |
+| `simulate_verilog` | `superrtl simulate` | 运行仿真 | Icarus Verilog |
+| `lint_verilog` | `superrtl lint` | Lint 检查 | Verilator |
+| `synthesize_verilog` | `superrtl synthesize` | 综合检查 | Yosys |
+| `generate_testbench` | `superrtl testbench` | 生成测试平台 | 内置 |
+| `analyze_waveform` | `superrtl waveform` | 分析波形 | 内置 |
+
+### MCP Resources
+
+| Resource | 功能 |
+|----------|------|
+| `skills://{name}` | 获取设计模式文档 |
+| `templates://{name}` | 获取代码模板 |
+
+---
+
+## 快速开始
+
+### 安装 SuperRTL
+
+```bash
+# 从源码安装
+cd SuperRTL
+pip install -e .
+
+# 或从 PyPI (发布后)
+pip install superrtl
+```
+
+### 安装 EDA 工具
+
+**方式一：自动安装（推荐）**
+
+```bash
+# 自动下载并安装 EDA 工具
+superrtl setup
+```
+
+这会自动下载 [OSS CAD Suite](https://github.com/YosysHQ/oss-cad-suite-build) 并安装到项目目录 `.superrtl/`。
+
+**方式二：手动安装**
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install iverilog yosys verilator
+
+# macOS
+brew install icarus-verilog yosys verilator
+
+# Windows (Scoop)
+scoop install iverilog yosys verilator
+```
+
+### 验证安装
+
+```bash
+# 检查工具状态
+superrtl check-tools
+```
+
+输出示例：
+```
+EDA 工具状态
+
+  + iverilog: Icarus Verilog (编译仿真)
+  + vvp: Icarus Verilog (仿真器)
+  + yosys: Yosys (综合检查)
+  + verilator: Verilator (Lint)
+
+所有工具已安装
+```
+
+### 使用 CLI
+
+```bash
+# 编译
+superrtl compile design.v
+
+# 仿真
+superrtl simulate design.v testbench.v
+
+# Lint
+superrtl lint design.v
+
+# 综合
+superrtl synthesize design.v --top counter
+
+# 生成 Testbench
+superrtl testbench design.v
+
+# 分析波形
+superrtl waveform simulation.vcd
+```
+
+### 使用 MCP Server
+
+```bash
+# 启动 MCP Server
+superrtl mcp
+
+# 指定传输方式
+superrtl mcp --transport sse --port 8080
+```
+
+### 配置 MCP Host
+
+**Claude Desktop** (`~/.claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "superrtl": {
+      "command": "superrtl",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "superrtl": {
+      "command": "superrtl",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Docker 支持
+
+### 构建镜像
+
+```bash
+# 构建 Docker 镜像
+docker build -t superrtl .
+```
+
+### 使用 Docker
+
+```bash
+# 启动 MCP Server
+docker run -it superrtl
+
+# 挂载目录使用 CLI
+docker run -v $(pwd):/workspace -it superrtl compile /workspace/design.v
+
+# 交互式使用
+docker run -it -v $(pwd):/workspace superrtl bash
+```
+
+---
+
+## CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `superrtl setup` | 安装 EDA 工具 |
+| `superrtl check-tools` | 检查工具状态 |
+| `superrtl compile <file>` | 编译 Verilog 代码 |
+| `superrtl simulate <design> <testbench>` | 运行仿真 |
+| `superrtl lint <file>` | Lint 检查 |
+| `superrtl synthesize <file>` | 综合检查 |
+| `superrtl testbench <file>` | 生成 Testbench |
+| `superrtl waveform <file>` | 分析波形 |
+| `superrtl mcp` | 启动 MCP Server |
+| `superrtl uninstall` | 卸载 EDA 工具 |
+
+---
+
+## 技术栈
+
+| 组件 | 选型 | 版本 |
+|------|------|------|
+| 语言 | Python | 3.10+ |
+| MCP 协议 | mcp | >=1.0.0 |
+| CLI 框架 | click | >=8.0.0 |
+| 终端美化 | rich | >=13.0.0 |
+| EDA 工具 | OSS CAD Suite | 2026.06 |
+
+---
+
+## 项目结构
+
+```
+SuperRTL/
+├── src/superrtl/
+│   ├── __init__.py
+│   ├── server.py              # MCP Server 主入口
+│   ├── cli.py                 # CLI 入口
+│   ├── setup.py               # EDA 工具安装管理
+│   ├── runtime.py             # 运行时环境管理
+│   │
+│   ├── tools/                 # MCP Tools
+│   │   ├── compile.py
+│   │   ├── simulate.py
+│   │   ├── lint.py
+│   │   ├── synthesize.py
+│   │   ├── testbench.py
+│   │   └── waveform.py
+│   │
+│   ├── resources/             # MCP Resources
+│   │   ├── skills.py
+│   │   └── templates.py
+│   │
+│   └── utils/
+│       ├── __init__.py        # run_command
+│       └── verilog.py
+│
+├── shared/                    # 共享资源
+│   ├── skills/                # 设计模式文档
+│   └── templates/             # 代码模板
+│
+├── .superrtl/                 # EDA 工具安装目录（自动生成）
+│   └── oss-cad-suite/
+│       ├── bin/
+│       └── lib/
+│
+├── Dockerfile                 # Docker 镜像
+├── tests/
+├── examples/
+└── pyproject.toml
+```
+
+---
+
+## 工作原理
+
+### 自动安装
+
+1. 运行 `superrtl setup`
+2. 检测操作系统和架构
+3. 从 GitHub 下载对应的 OSS CAD Suite
+4. 解压到 `.superrtl/oss-cad-suite/`
+5. 运行时自动添加到 PATH
+
+### 运行时
+
+1. 工具调用时自动检测本地安装
+2. 优先使用 `.superrtl/oss-cad-suite/bin/` 中的工具
+3. 回退到系统 PATH
+4. 自动处理 Windows DLL 依赖问题
+
+---
+
+## 示例
+
+### CLI 示例
+
+```bash
+# 编译并仿真
+$ superrtl compile counter.v
+[OK] 编译成功: counter
+   耗时: 0.058s
+
+$ superrtl simulate counter.v counter_tb.v
+[OK] 仿真通过
+   耗时: 0.456s
+   输出: PASS
+```
+
+### MCP 调用示例
+
+```json
+// tools/call
+{
+  "name": "compile_verilog",
+  "arguments": {
+    "code": "module counter(...); ...",
+    "top_module": "counter"
+  }
+}
+
+// 返回
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"success\": true, \"message\": \"编译成功\"}"
+    }
+  ]
+}
+```
+
+---
+
+## 许可证
+
+MIT License
+
+---
+
+## 致谢
+
+- [Icarus Verilog](https://github.com/steveicarus/iverilog)
+- [Yosys](https://github.com/YosysHQ/yosys)
+- [Verilator](https://github.com/verilator/verilator)
+- [OSS CAD Suite](https://github.com/YosysHQ/oss-cad-suite-build)

superrtl-0.2.0/docs/INSTALL.md

@@ -0,0 +1,239 @@
+# SuperRTL 安装指南
+
+---
+
+## 一、系统要求
+
+| 项目 | 要求 |
+|------|------|
+| Python | 3.10+ |
+| 操作系统 | Windows / macOS / Linux |
+
+---
+
+## 二、安装 SuperRTL
+
+### 从源码安装
+
+```bash
+cd SuperRTL
+pip install -e .
+```
+
+### 验证安装
+
+```bash
+superrtl --version
+```
+
+---
+
+## 三、安装 EDA 工具
+
+### Windows (使用 Scoop)
+
+[Scoop](https://scoop.sh/) 是 Windows 下的包管理器，推荐使用。
+
+#### 1. 安装 Scoop
+
+```powershell
+# 打开 PowerShell，执行：
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
+```
+
+#### 2. 添加 Bucket
+
+```powershell
+# 添加主 bucket
+scoop bucket add main
+
+# 添加 extras bucket (包含更多工具)
+scoop bucket add extras
+```
+
+#### 3. 安装 Verilog 工具
+
+```powershell
+# 安装 Icarus Verilog (编译仿真)
+scoop install main/iverilog
+
+# 安装 Yosys (综合检查)
+scoop install main/yosys
+
+# 安装 Verilator (Lint)
+scoop install main/verilator
+```
+
+#### 4. 验证安装
+
+```powershell
+# 检查版本
+iverilog -V
+yosys -V
+verilator --version
+```
+
+#### 5. 常见问题
+
+**问题：scoop 找不到包**
+
+```powershell
+# 更新 scoop
+scoop update
+
+# 搜索包
+scoop search iverilog
+scoop search yosys
+scoop search verilator
+```
+
+**问题：iverilog 安装后命令不可用**
+
+```powershell
+# 检查 PATH
+echo $env:PATH
+
+# 手动添加 PATH
+scoop prefix iverilog
+# 将输出的路径添加到 PATH
+```
+
+**问题：yosys 安装失败**
+
+```powershell
+# 尝试从 extras 安装
+scoop install extras/yosys
+
+# 或者从 GitHub 下载
+# https://github.com/YosysHQ/yosys/releases
+```
+
+---
+
+### macOS (使用 Homebrew)
+
+```bash
+# 安装 Homebrew (如果没有)
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# 安装工具
+brew install icarus-verilog
+brew install yosys
+brew install verilator
+
+# 验证
+iverilog -V
+yosys -V
+verilator --version
+```
+
+---
+
+### Linux (Ubuntu/Debian)
+
+```bash
+# 更新包列表
+sudo apt-get update
+
+# 安装工具
+sudo apt-get install -y iverilog
+sudo apt-get install -y yosys
+sudo apt-get install -y verilator
+
+# 验证
+iverilog -V
+yosys -V
+verilator --version
+```
+
+---
+
+## 四、安装 MCP Host (可选)
+
+### Claude Desktop
+
+1. 下载: https://claude.ai/download
+2. 配置 MCP Server:
+
+编辑 `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "superrtl": {
+      "command": "superrtl",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+1. 下载: https://cursor.sh/
+2. 配置 MCP Server:
+
+创建 `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "superrtl": {
+      "command": "superrtl",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 五、验证完整安装
+
+```bash
+# 1. 检查 SuperRTL
+superrtl --version
+
+# 2. 检查 EDA 工具
+superrtl check-tools
+
+# 3. 测试编译
+echo 'module test(input clk, output reg [3:0] cnt); always @(posedge clk) cnt <= cnt + 1; endmodule' > test.v
+superrtl compile test.v
+
+# 4. 启动 MCP Server
+superrtl mcp
+```
+
+---
+
+## 六、卸载
+
+### 卸载 SuperRTL
+
+```bash
+pip uninstall superrtl
+```
+
+### 卸载 EDA 工具 (Windows Scoop)
+
+```powershell
+scoop uninstall iverilog
+scoop uninstall yosys
+scoop uninstall verilator
+```
+
+### 卸载 EDA 工具 (macOS)
+
+```bash
+brew uninstall icarus-verilog
+brew uninstall yosys
+brew uninstall verilator
+```
+
+### 卸载 EDA 工具 (Linux)
+
+```bash
+sudo apt-get remove iverilog yosys verilator
+```