hoertech/docker-buildenv

MHA/openMHA Docker构建环境镜像文档

1. 镜像概述和主要用途

该Docker镜像为MHA（Multichannel Hearing Aid）和openMHA（开源多通道助听器软件框架）提供标准化的构建环境。旨在简化MHA和openMHA的源码编译、开发调试及测试流程，解决不同主机环境下依赖配置不一致、编译工具链差异导致的构建问题。通过容器化方案，确保开发、测试和部署环境的一致性，降低环境配置成本。

2. 核心功能和特性

2.1 环境标准化

• 基于Debian/Ubuntu稳定版基础镜像，预配置编译工具链（gcc, g++, cmake, make）及构建依赖（pkg-config, libtool）。
• 集成MHA/openMHA编译必需的音频处理库：ALSA（音频接口）、FFTW3（快速傅里叶变换）、libsndfile（音频文件I/O）、PortAudio（跨平台音频流）等。

2.2 灵活的版本支持

• 支持指定MHA和openMHA版本编译（通过环境变量控制），兼容官方发布的稳定版及开发版源码。
• 提供Debug/Release双模式构建支持，满足开发调试与生产部署需求。

2.3 轻量与可扩展

• 镜像体积优化，仅包含必要依赖，基础镜像大小<500MB。
• 支持用户自定义构建参数（如安装路径、编译选项），通过环境变量或挂载配置文件扩展功能。

2.4 跨平台一致性

• 消除主机系统差异（Windows/macOS/Linux），确保同一套源码在不同环境下构建结果一致，适配CI/CD流程集成。

3. 使用场景和适用范围

3.1 目标用户

• 音频信号处理算法开发者
• 助听器/听力辅助设备研发人员
• 声学工程或听力学领域学术研究人员
• 需要快速搭建MHA/openMHA开发环境的教学人员

3.2 典型使用场景

• 本地开发环境搭建：开发者无需手动配置依赖，通过容器快速启动编译环境，专注代码开发。
• CI/CD流程集成：作为自动化流水线的构建节点，实现MHA/openMHA源码的自动编译、单元测试及打包。
• 跨平台开发验证：在不同操作系统主机上，通过容器确保编译结果一致性，避免平台相关bug。
• 教学与演示：快速复现MHA/openMHA的编译过程，降低教学环境准备复杂度。

4. 使用方法和配置说明

4.1 镜像获取

4.1.1 从Docker Hub拉取（推荐）

bash
docker pull docker.xuanyuan.run/mha/openmha-build-env:latest

注：替换latest为具体版本标签（如ubuntu22.04）以指定基础系统版本。

4.1.2 本地构建镜像

若需自定义基础系统或依赖版本，可通过源码构建：

bash
# 克隆镜像构建脚本仓库（假设存在）
git clone https://github.com/example/mha-build-env.git
cd mha-build-env
# 构建镜像，指定基础系统版本
docker build --build-arg BASE_IMAGE=ubuntu:22.04 -t mha/openmha-build-env:ubuntu22.04 .

4.2 容器运行与编译流程

4.2.1 基本使用（交互式编译）

通过挂载本地MHA/openMHA源码目录，在容器内执行编译：

bash
# 假设本地源码路径为 /home/user/mha-src
docker run -it --rm \
  -v /home/user/mha-src:/app/src  # 挂载本地源码到容器内/app/src
  -e MHA_VERSION=1.24.0          # 指定MHA版本（可选，默认latest）
  -e BUILD_TYPE=Debug            # 构建类型（Debug/Release，默认Release）
  mha/openmha-build-env:latest   # 镜像名称
  /bin/bash                      # 启动交互式终端

进入容器后，执行编译命令：

bash
# 进入挂载的源码目录
cd /app/src
# 创建构建目录
mkdir -p build && cd build
# 生成Makefile（使用容器内预配置的cmake）
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local  # 安装路径默认/usr/local
# 执行编译
make -j$(nproc)  # 多线程编译
# 安装（可选）
make install

4.2.2 非交互式自动化编译

通过命令行直接执行编译流程，适用于脚本或CI环境：

bash
docker run --rm \
  -v /home/user/mha-src:/app/src \
  -v /home/user/mha-output:/app/output  # 挂载输出目录（存放编译产物）
  -e OPENMHA_VERSION=4.16.0 \
  -e INSTALL_PREFIX=/app/output \      # 指定安装路径到挂载的输出目录
  mha/openmha-build-env:latest \
  sh -c "cd /app/src && mkdir build && cd build && cmake .. -DCMAKE_INSTALL_PREFIX=\$INSTALL_PREFIX && make -j$(nproc) && make install"

4.3 配置参数说明

4.3.1 环境变量

4.4 Docker Compose配置示例

对于复杂场景（如持久化构建缓存、多步骤构建），可使用docker-compose.yml：

yaml
version: '3'
services:
  mha-build:
    image: docker.xuanyuan.run/mha/openmha-build-env:latest
    volumes:
      - ./mha-src:/app/src          # 本地源码目录
      - ./build-cache:/app/cache    # 持久化CMake缓存
      - ./output:/app/output        # 编译产物输出
    environment:
      - MHA_VERSION=1.24.0
      - BUILD_TYPE=Release
      - INSTALL_PREFIX=/app/output
    command: >
      sh -c "cd /app/src && 
             mkdir -p build && 
             cd build && 
             cmake .. -DCMAKE_INSTALL_PREFIX=\$INSTALL_PREFIX -DCMAKE_CACHEFILE_DIR=/app/cache && 
             make -j$(nproc) && 
             make install"

启动命令：docker-compose up

5. 注意事项

• 确保本地源码目录权限正确（容器内用户需有读写权限，可通过-u $(id -u):$(id -g)指定用户ID）。
• 不同MHA/openMHA版本可能依赖不同库版本，建议通过MHA_VERSION/OPENMHA_VERSION明确指定版本，避免兼容性问题。
• 如需使用音频输入输出设备（如测试MHA实时音频处理），需添加--device /dev/snd参数挂载音频设备（仅Linux主机支持）。