IgH EtherCAT 从入门到精通：第 2 章 环境搭建与编译安装

第 2 章 环境搭建与编译安装

导读摘要：本章将带你从零开始搭建 IgH EtherCAT Master 的开发环境。我们会逐步讲解硬件与软件的前置要求、源码获取方式、configure 配置选项的含义、内核模块与用户空间库的编译流程、安装部署与 udev 规则配置，以及常见编译错误的排查方法。完成本章后，你将拥有一个可运行的 EtherCAT 主站环境。

2.1 硬件与软件环境要求

硬件要求

IgH EtherCAT Master 对硬件的核心要求是一块受支持的以太网卡（NIC）。主站通过专用的网卡驱动直接控制以太网硬件，绕过 Linux 网络协议栈以获得确定性的通信时序。

项目内置了多款 Intel 和 Realtek 系列网卡的 EtherCAT 化驱动（Native Driver），包括：

如果你手头没有上述专用驱动支持的网卡，可以使用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 系统上，可以一键安装依赖：

sudoapt-getinstallbuild-essential autoconf automake libtool pkg-config\linux-headers-$(uname-r)

在 CentOS/RHEL 系统上：

sudoyuminstallgcc gcc-c++ autoconf automake libtool pkgconfig\kernel-devel-$(uname-r)

2.2 获取源码（Git 克隆与版本选择）

IgH EtherCAT Master 的官方源码托管在 GitLab 上。我们推荐使用 Git 克隆的方式获取源码，这样便于后续跟踪更新和切换版本。

# 克隆官方仓库gitclone https://gitlab.com/etherlab.org/ethercat.gitcdethercat# 查看所有可用的版本标签gittag-l# 切换到稳定分支（推荐用于生产环境）gitcheckout stable-1.5# 或者切换到特定的版本标签gitcheckout v1.6.8

如果你需要使用 Doxygen 文档功能，还需要初始化子模块：

gitsubmodule update--init

建议：生产环境推荐使用stable-1.5分支或正式的版本标签。master分支包含最新的开发代码，可能存在不稳定因素。

2.3 bootstrap 与 configure 配置选项详解

bootstrap 脚本

从 Git 仓库克隆的源码不包含configure脚本，需要先运行bootstrap来生成。这个脚本的核心逻辑非常简洁：

#!/bin/bashset-eset-xtouchChangeLogmkdir-pm4 autoreconf-i

它做了三件事：创建空的 ChangeLog 文件、确保m4宏目录存在、然后调用autoreconf -i生成完整的 Autotools 构建系统（包括configure脚本和Makefile.in文件）。

# 运行 bootstrap（仅从 Git 仓库获取源码时需要）./bootstrap

configure 核心选项

configure脚本提供了丰富的配置选项。我们按功能分类梳理最常用的选项：

基础路径选项：

功能开关选项：

实时框架选项（可选）：

典型配置示例

下面是一个适合入门学习的最小配置：

./configure--sysconfdir=/etc --enable-generic

下面是一个用于生产环境的配置示例，使用 Intel I210 网卡并启用冗余：

./configure\--sysconfdir=/etc\--enable-generic\--enable-igb\--with-devices=2\--enable-cycles\--enable-hrtimer\--enable-sii-assign

2.4 编译内核模块与用户空间库

配置完成后，整个编译流程可以用下面的流程图概括：

┌─────────────┐ ┌──────────────┐ ┌───────────────────┐ │ bootstrap │────>│ configure │────>│ make all │ │ (生成构建系统) │ │ (检测环境配置) │ │ (编译用户空间组件) │ └─────────────┘ └──────────────┘ └────────┬──────────┘ │ v ┌───────────────────┐ │ make modules │ │ (编译内核模块) │ └────────┬──────────┘ │ v ┌───────────────────┐ │ make modules_install│ │ make install │ │ (安装到系统) │ └───────────────────┘

编译用户空间组件

make all命令会编译以下组件（取决于你的 configure 配置）：

• 命令行工具ethercat：用于主站管理和从站诊断
• 用户空间库libethercat：应用程序通过此库与内核主站通信
• init 脚本和 systemd 服务文件：用于系统服务管理

makeall

编译内核模块

make modules命令会编译内核空间的模块：

• ec_master.ko：EtherCAT 主站核心模块
• ec_generic.ko：通用以太网驱动模块（如果启用了--enable-generic）
• ec_<driver>.ko：各 Native Driver 模块（如ec_e1000e.ko、ec_igb.ko等）

makemodules

编译完成后，你可以在master/目录下找到ec_master.ko，在devices/目录下找到各驱动模块。

注意：make all和make modules是两个独立的构建目标。all只编译用户空间组件，modules编译内核模块。两者都需要执行。

如果你的机器有多个 CPU 核心，可以使用-j参数并行编译以加快速度：

make-j$(nproc)all modules

2.5 安装部署与 udev 规则配置

安装

编译完成后，以 root 权限执行安装命令：

sudomakemodules_installinstallsudodepmod

make modules_install将内核模块安装到/lib/modules/$(uname -r)/ethercat/目录（可通过--with-module-dir修改子目录名）。make install安装用户空间的库、头文件、命令行工具和服务脚本。depmod更新内核模块依赖关系。

配置文件

安装后，你需要编辑配置文件来指定主站使用的网卡 MAC 地址和驱动类型：

# systemd 发行版sudovi/etc/ethercat.conf# init.d 发行版sudovi/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 规则：

# 允许普通用户读取 EtherCAT 设备echo'KERNEL=="EtherCAT[0-9]*", MODE="0664"'|\sudotee/etc/udev/rules.d/99-EtherCAT.rules

如果你需要更精细的权限控制，可以创建专用用户组：

sudogroupaddethercatsudousermod-aGethercat$USERecho'KERNEL=="EtherCAT[0-9]*", MODE="0660", GROUP="ethercat"'|\sudotee/etc/udev/rules.d/99-EtherCAT.rules

启动主站服务

一切就绪后，启动 EtherCAT 主站：

# systemd 发行版sudosystemctl start ethercatsudosystemctlenableethercat# 设置开机自启# init.d 发行版sudo/etc/init.d/ethercat start

验证主站是否正常运行：

# 查看主站状态ethercat master# 扫描总线上的从站ethercat slaves

2.6 常见编译错误排查

错误 1：找不到内核源码

configure: error: Failed to find Linux sources. Use --with-linux-dir!

原因：系统未安装当前内核的头文件/源码，或/lib/modules/$(uname -r)/build链接缺失。

解决方法：

# Debian/Ubuntusudoapt-getinstalllinux-headers-$(uname-r)# CentOS/RHELsudoyuminstallkernel-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 工具链。

解决方法：

sudoapt-getinstallautoconf automake libtool# Debian/Ubuntusudoyuminstallautoconf automake libtool# CentOS/RHEL

错误 4：pkg-config 版本过低或缺失

m4_fatal: pkgconf or pkg-config not found or too old

原因：pkg-config未安装或版本低于 0.27。

解决方法：

sudoapt-getinstallpkg-config# Debian/Ubuntusudoyuminstallpkgconfig# 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 从零到运行的完整搭建过程：

1. 环境准备：安装了编译工具链和内核头文件
2. 源码获取：通过 Git 克隆并选择了合适的版本
3. 配置：使用 bootstrap 和 configure 定制了构建选项
4. 编译：分别构建了用户空间组件和内核模块
5. 安装与部署：安装到系统并配置了 udev 规则和服务

如果你在编译过程中遇到问题，请优先检查内核头文件是否匹配、Autotools 版本是否满足要求。大多数编译问题都源于环境依赖不完整。

下一章预告

在第 3 章中，我们将深入分析 IgH EtherCAT Master 的内核模块架构。你将了解ec_master.ko的内部结构、主站状态机的工作原理、以及内核模块与用户空间之间的通信机制。这些知识将帮助你理解主站的核心运行逻辑，为后续的应用开发打下坚实基础。