ghdl/ext

GHDL 及补充工具 Docker 镜像文档

一、镜像概述和主要用途

本镜像为即用型 Docker 镜像，集成了 https://github.com/ghdl/ghdl%EF%BC%88VHDL 编译器/模拟器）及其补充工具（包括 https://github.com/ghdl/ghdl-language-server%E3%80%81GtkWave%E3%80%81https://vunit.github.io/ 等）。旨在提供一个标准化、开箱即用的 VHDL 开发与验证环境，避免用户手动安装和配置各类工具依赖，确保开发环境一致性。

二、核心功能和特性

2.1 集成工具

• GHDL：开源 VHDL 编译器、模拟器和综合器，支持 VHDL 93/02/08 标准，提供从代码分析到仿真执行的全流程支持。
• ghdl-language-server：基于 GHDL 的语言服务器协议（LSP）实现，支持代码补全、跳转定义、语法检查等 IDE 集成功能。
• GtkWave：波形文件查看器，支持 VCD、GHW 等格式，用于分析仿真波形结果。
• VUnit：开源 VHDL 单元测试框架，支持自动化测试用例管理、结果报告生成，提升代码可靠性。
• 其他补充工具：根据镜像版本可能包含 Make、Git 等辅助开发工具（详见 https://github.com/ghdl/docker/tree/master/dockerfiles%EF%BC%89%E3%80%82

三、使用场景和适用范围

• VHDL 项目开发：快速搭建本地或 CI 环境，进行代码编写、编译与调试。
• 仿真验证：通过 GHDL 编译 VHDL 代码并执行仿真，结合 GtkWave 分析波形。
• 单元测试：使用 VUnit 编写测试用例，自动化验证模块功能。
• IDE 集成：通过 ghdl-language-server 与 VS Code、Vim 等 IDE 集成，获得现代开发体验。
• CI/CD 流程：在持续集成/部署中使用，确保跨平台环境一致性。
• 教学与演示：快速部署标准化环境，降低新手入门门槛。

四、使用方法和配置说明

4.1 获取镜像

镜像可从 https://github.com/ghdl/docker 获取（需根据具体版本标签拉取，以下示例默认使用 latest 标签）：

bash
docker pull ghdl/ghdl:latest  # 假设官方镜像路径，实际请参考仓库文档

4.2 基本使用（docker run）

4.2.1 启动交互式终端

挂载本地项目目录至容器内工作目录（如 /work），启动交互式 shell：

bash
docker run -it --rm \
  -v $(pwd):/work  # 挂载当前目录到容器内 /work
  -w /work         # 设置工作目录为 /work
  ghdl/ghdl:latest \
  bash             # 启动 bash 终端

• -it：交互式终端模式，支持命令输入。
• --rm：容器退出后自动删除，避免残留。
• -v $(pwd):/work：将本地当前目录（项目代码）挂载到容器内 /work，实现文件共享。

4.2.2 常用命令示例

在容器终端中执行以下命令，完成典型开发流程：

1. 编译 VHDL 代码（以 design.vhd 为例）：

   bash
   ghdl -a design.vhd  # 分析（编译）VHDL 文件
   ghdl -e top_entity  #  elaborate（链接）顶层实体，生成可执行仿真文件
   

2. 执行仿真并生成波形：

   bash
   ghdl -r top_entity --wave=wave.ghw  # 运行仿真，输出 GHW 格式波形文件
   

3. 使用 GtkWave 查看波形（需宿主机支持 X11 转发，或挂载波形文件到宿主机后本地查看）：

   bash
   gtkwave wave.ghw  # 在容器内直接打开波形查看器（需配置 X11 转发）
   

4. 运行 VUnit 测试（假设项目中已集成 VUnit）：

   bash
   vunit run --output-path=test_results  # 执行测试用例，输出结果到 test_results 目录
   

4.3 Docker Compose 配置示例

创建 docker-compose.yml 文件，定义服务配置：

yaml
version: '3.8'

services:
  ghdl-env:
    image: ghdl/ghdl:latest
    volumes:
      - ./project:/work  # 挂载宿主机项目目录（./project）到容器 /work
      - ./wavefiles:/wave  # 可选：单独挂载波形文件目录
    working_dir: /work
    tty: true  # 启用终端交互
    stdin_open: true  # 保持标准输入打开
    # 如需支持 GtkWave 图形界面，添加 X11 转发配置（适用于 Linux 宿主机）：
    environment:
      - DISPLAY=${DISPLAY}
    volumes_from:
      - /tmp/.X11-unix:/tmp/.X11-unix

启动服务：

bash
docker-compose up -d  # 后台启动服务
docker-compose exec ghdl-env bash  # 进入容器终端

4.4 配置说明

4.4.1 环境变量

当前镜像未定义特殊环境变量，工具配置（如 GHDL 后端选择、VUnit 路径等）需通过工具自身配置文件或命令行参数实现。

4.4.2 数据持久化

通过 -v 挂载宿主机目录（如项目代码、波形文件、测试结果）实现数据持久化，避免容器销毁后数据丢失。

4.4.3 IDE 集成

若需通过 IDE（如 VS Code）使用 ghdl-language-server，可在容器内启动语言服务器，并配置 IDE 连接至容器内 LSP 端口（需映射端口 -p 2087:2087，具体端口参考工具文档）。

五、注意事项

• GtkWave 图形界面：在非 Linux 宿主机（如 Windows/macOS）上使用时，需额外配置图形转发工具（如 Xming、VcXsrv）。
• 镜像版本：不同版本镜像可能集成工具版本不同，建议通过 https://github.com/ghdl/docker/tree/master/dockerfiles 确认具体工具版本。
• 性能优化：大规模项目仿真建议挂载本地目录时使用 :delegated 或 :cached 选项（适用于 Docker Desktop）提升文件 I/O 性能。