第 2 章 环境搭建与编译安装
导读摘要：本章将带你从零开始搭建 IgH EtherCAT Master 的开发环境。我们会逐步讲解硬件与软件的前置要求、源码获取方式、configure 配置选项的含义、内核模块与用户空间库的编译流程、安装部署与 udev 规则配置，以及常见编译错误的排查方法。完成本章后，你将拥有一个可运行的 EtherCAT 主站环境。
2.1 硬件与软件环境要求
硬件要求
IgH EtherCAT Master 对硬件的核心要求是一块受支持的以太网卡（NIC）。主站通过专用的网卡驱动直接控制以太网硬件，绕过 Linux 网络协议栈以获得确定性的通信时序。
项目内置了多款 Intel 和 Realtek 系列网卡的 EtherCAT 化驱动（Native Driver），包括：
| 驱动名称 | 适用硬件 | configure 选项 |
|---|---|---|
| generic | 通用以太网卡（任意 NIC） | --enable-generic（默认开启） |
| e1000 | Intel 82540/82545 等千兆网卡 | --enable-e1000 |
| e1000e | Intel I217/I218/I219 等 PCIe 千兆网卡 | --enable-e1000e |
| igb | Intel I350/I210 等服务器级千兆网卡 | --enable-igb |
| igc | Intel I225/I226 2.5G 网卡 | --enable-igc |
| r8169 | Realtek RTL8111/RTL8168 千兆网卡 | --enable-r8169 |
| genet | 树莓派 4（Raspberry Pi 4）板载网卡 | --enable-genet |
| 8139too | Realtek RTL8139 百兆网卡 | --enable-8139too |
如果你手头没有上述专用驱动支持的网卡，可以使用 generic 驱动。它适配任何 Linux 以太网卡，但性能和实时性不如 Native Driver。对于入门学习和功能验证来说，generic 驱动完全够用。
提示 ：完整的受支持硬件列表可参阅 EtherLab 官方文档。
软件要求
编译 IgH EtherCAT Master 1.6.8 版本需要以下软件环境：
- 操作系统：Linux，内核版本 2.6 或更新
- 已配置的内核源码 ：编译内核模块时需要当前运行内核的源码目录（含
.config文件） - Autotools 工具链 ：
autoconf（>= 2.59）、automake、libtool - pkg-config：版本 >= 0.27
- GCC 编译器 ：支持 C 和 C++ 编译（
gcc、g++） - 内核头文件 ：通常通过
linux-headers-$(uname -r)包安装
在 Debian/Ubuntu 系统上，可以一键安装依赖：
bash
sudo apt-get install build-essential autoconf automake libtool pkg-config \
linux-headers-$(uname -r)在 CentOS/RHEL 系统上：
bash
sudo yum install gcc gcc-c++ autoconf automake libtool pkgconfig \
kernel-devel-$(uname -r)2.2 获取源码（Git 克隆与版本选择）
IgH EtherCAT Master 的官方源码托管在 GitLab 上。我们推荐使用 Git 克隆的方式获取源码，这样便于后续跟踪更新和切换版本。
bash
# 克隆官方仓库
git clone https://gitlab.com/etherlab.org/ethercat.git
cd ethercat
# 查看所有可用的版本标签
git tag -l
# 切换到稳定分支（推荐用于生产环境）
git checkout stable-1.5
# 或者切换到特定的版本标签
git checkout v1.6.8如果你需要使用 Doxygen 文档功能，还需要初始化子模块：
bash
git submodule update --init建议 ：生产环境推荐使用
stable-1.5分支或正式的版本标签。master分支包含最新的开发代码，可能存在不稳定因素。
2.3 bootstrap 与 configure 配置选项详解
bootstrap 脚本
从 Git 仓库克隆的源码不包含 configure 脚本，需要先运行 bootstrap 来生成。这个脚本的核心逻辑非常简洁：
bash
#!/bin/bash
set -e
set -x
touch ChangeLog
mkdir -p m4
autoreconf -i它做了三件事：创建空的 ChangeLog 文件、确保 m4 宏目录存在、然后调用 autoreconf -i 生成完整的 Autotools 构建系统（包括 configure 脚本和 Makefile.in 文件）。
bash
# 运行 bootstrap（仅从 Git 仓库获取源码时需要）
./bootstrapconfigure 核心选项
configure 脚本提供了丰富的配置选项。我们按功能分类梳理最常用的选项：
基础路径选项：
| 选项 | 说明 | 默认值 |
|---|---|---|
--prefix=<DIR> |
安装前缀路径 | /usr/local |
--sysconfdir=<DIR> |
配置文件目录 | ${prefix}/etc |
--with-linux-dir=<DIR> |
Linux 内核源码路径 | 自动检测当前内核 |
--with-module-dir=<DIR> |
内核模块安装子目录 | ethercat |
功能开关选项：
| 选项 | 说明 | 默认值 |
|---|---|---|
--enable-kernel |
构建内核模块 | yes |
--enable-tool |
构建命令行工具 ethercat |
yes |
--enable-userlib |
构建用户空间库 libethercat |
yes |
--enable-eoe |
启用 EoE（Ethernet over EtherCAT）支持 | yes |
--enable-cycles |
使用 CPU 时间戳计数器（TSC） | no |
--enable-hrtimer |
使用高精度定时器（High-Resolution Timer）调度 | no |
--enable-rtdm |
启用 RTDM（Real-Time Driver Model）接口 | no |
--enable-debug-if |
创建调试网络接口 | no |
--enable-tty |
构建 TTY 驱动模块 ec_tty |
no |
--enable-sii-assign |
将 SII（Slave Information Interface）分配给 PDI | yes |
--enable-wildcards |
启用 Vendor ID / Product Code 通配符 | no |
实时框架选项（可选）：
| 选项 | 说明 |
|---|---|
--with-rtai-dir=<DIR> |
RTAI 安装路径，启用 RTAI 支持 |
--with-xenomai-dir=<DIR> |
Xenomai 安装路径，启用 Xenomai 支持 |
--with-devices=<N> |
每个主站的以太网设备数量，大于 1 时启用冗余（Redundancy），默认 1 |
典型配置示例
下面是一个适合入门学习的最小配置：
bash
./configure --sysconfdir=/etc --enable-generic下面是一个用于生产环境的配置示例，使用 Intel I210 网卡并启用冗余：
bash
./configure \
--sysconfdir=/etc \
--enable-generic \
--enable-igb \
--with-devices=2 \
--enable-cycles \
--enable-hrtimer \
--enable-sii-assign2.4 编译内核模块与用户空间库
配置完成后，整个编译流程可以用下面的流程图概括：
┌─────────────┐ ┌──────────────┐ ┌───────────────────┐
│ bootstrap │────>│ configure │────>│ make all │
│ (生成构建系统) │ │ (检测环境配置) │ │ (编译用户空间组件) │
└─────────────┘ └──────────────┘ └────────┬──────────┘
│
v
┌───────────────────┐
│ make modules │
│ (编译内核模块) │
└────────┬──────────┘
│
v
┌───────────────────┐
│ make modules_install│
│ make install │
│ (安装到系统) │
└───────────────────┘编译用户空间组件
make all 命令会编译以下组件（取决于你的 configure 配置）：
- 命令行工具
ethercat：用于主站管理和从站诊断 - 用户空间库
libethercat：应用程序通过此库与内核主站通信 - init 脚本和 systemd 服务文件：用于系统服务管理
bash
make all编译内核模块
make modules 命令会编译内核空间的模块：
- ec_master.ko：EtherCAT 主站核心模块
- ec_generic.ko ：通用以太网驱动模块（如果启用了
--enable-generic） - ec_<driver>.ko ：各 Native Driver 模块（如
ec_e1000e.ko、ec_igb.ko等）
bash
make modules编译完成后，你可以在 master/ 目录下找到 ec_master.ko，在 devices/ 目录下找到各驱动模块。
注意 ：
make all和make modules是两个独立的构建目标。all只编译用户空间组件，modules编译内核模块。两者都需要执行。
如果你的机器有多个 CPU 核心，可以使用 -j 参数并行编译以加快速度：
bash
make -j$(nproc) all modules2.5 安装部署与 udev 规则配置
安装
编译完成后，以 root 权限执行安装命令：
bash
sudo make modules_install install
sudo depmodmake modules_install 将内核模块安装到 /lib/modules/$(uname -r)/ethercat/ 目录（可通过 --with-module-dir 修改子目录名）。make install 安装用户空间的库、头文件、命令行工具和服务脚本。depmod 更新内核模块依赖关系。
配置文件
安装后，你需要编辑配置文件来指定主站使用的网卡 MAC 地址和驱动类型：
bash
# systemd 发行版
sudo vi /etc/ethercat.conf
# init.d 发行版
sudo vi /etc/sysconfig/ethercat配置文件中最关键的两个参数：
MASTER0_DEVICE：EtherCAT 主站使用的网卡 MAC 地址DEVICE_MODULES：使用的驱动模块名称（如generic、igb等）
udev 规则配置
IgH EtherCAT Master 通过字符设备（Character Device）与用户空间通信。udev 会在主站启动时自动创建 /dev/EtherCAT0 等设备节点。默认情况下，设备权限为 0660（仅 root 用户和 root 组可读写）。
如果希望普通用户也能读取设备信息（例如使用 ethercat 命令行工具），需要创建 udev 规则：
bash
# 允许普通用户读取 EtherCAT 设备
echo 'KERNEL=="EtherCAT[0-9]*", MODE="0664"' | \
sudo tee /etc/udev/rules.d/99-EtherCAT.rules如果你需要更精细的权限控制，可以创建专用用户组：
bash
sudo groupadd ethercat
sudo usermod -aG ethercat $USER
echo 'KERNEL=="EtherCAT[0-9]*", MODE="0660", GROUP="ethercat"' | \
sudo tee /etc/udev/rules.d/99-EtherCAT.rules启动主站服务
一切就绪后，启动 EtherCAT 主站：
bash
# systemd 发行版
sudo systemctl start ethercat
sudo systemctl enable ethercat # 设置开机自启
# init.d 发行版
sudo /etc/init.d/ethercat start验证主站是否正常运行：
bash
# 查看主站状态
ethercat master
# 扫描总线上的从站
ethercat slaves2.6 常见编译错误排查
错误 1：找不到内核源码
configure: error: Failed to find Linux sources. Use --with-linux-dir!原因 ：系统未安装当前内核的头文件/源码，或 /lib/modules/$(uname -r)/build 链接缺失。
解决方法：
bash
# Debian/Ubuntu
sudo apt-get install linux-headers-$(uname -r)
# CentOS/RHEL
sudo yum install kernel-devel-$(uname -r)
# 或者手动指定内核源码路径
./configure --with-linux-dir=/path/to/kernel/sources ...错误 2：内核源码未配置
configure: error: No configured Linux kernel sources in /lib/modules/.../build原因 ：内核源码目录下缺少 .config 文件，说明内核源码尚未配置。
解决方法 ：确保安装了正确版本的内核头文件包，或进入内核源码目录执行 make oldconfig。
错误 3：autoconf/automake 版本不满足
bootstrap: autoreconf: command not found原因：系统缺少 Autotools 工具链。
解决方法：
bash
sudo apt-get install autoconf automake libtool # Debian/Ubuntu
sudo yum install autoconf automake libtool # CentOS/RHEL错误 4：pkg-config 版本过低或缺失
m4_fatal: pkgconf or pkg-config not found or too old原因 ：pkg-config 未安装或版本低于 0.27。
解决方法：
bash
sudo apt-get install pkg-config # Debian/Ubuntu
sudo yum install pkgconfig # CentOS/RHEL错误 5：驱动内核版本不匹配
configure: error: kernel X.Y.Z not available for e1000e driver!原因：你启用了某个 Native Driver，但项目中没有适配你当前内核版本的驱动源码。
解决方法 ：查看 devices/ 目录下该驱动支持的内核版本列表，或使用 --with-<driver>-kernel=<X.Y.Z> 指定一个可用的版本。如果确实没有匹配的版本，改用 generic 驱动是最简单的替代方案。
错误 6：模块编译时 GPL 符号错误
ERROR: modpost: GPL-incompatible module ... uses GPL-only symbol ...原因：内核版本与驱动代码之间存在兼容性问题。
解决方法：确认你的内核版本在项目支持范围内，必要时更换到项目已适配的内核版本。
小结
本章我们完成了 IgH EtherCAT Master 从零到运行的完整搭建过程：
- 环境准备：安装了编译工具链和内核头文件
- 源码获取：通过 Git 克隆并选择了合适的版本
- 配置：使用 bootstrap 和 configure 定制了构建选项
- 编译：分别构建了用户空间组件和内核模块
- 安装与部署：安装到系统并配置了 udev 规则和服务
如果你在编译过程中遇到问题，请优先检查内核头文件是否匹配、Autotools 版本是否满足要求。大多数编译问题都源于环境依赖不完整。
下一章预告
在第 3 章中，我们将深入分析 IgH EtherCAT Master 的内核模块架构。你将了解 ec_master.ko 的内部结构、主站状态机的工作原理、以及内核模块与用户空间之间的通信机制。这些知识将帮助你理解主站的核心运行逻辑，为后续的应用开发打下坚实基础。