【2023-07-13】【教程】定制你的 OpenWrt 系统

Levi_Marvin

请务必从基础知识开始看，会帮你减少编译过程中的许多问题的。
由于帖子字数限制，每一节内容分楼层发布。如果后期发现错误/表达不妥的地方会尽量及时修正。
最后更新：2023/07/13，所有内容发布完毕，未显示即为待审核。

本教程分为二个部分：编译教程与问题解决 和 特殊设备问题解决。
编译教程与问题解决：序号 一 至 四。特殊设备问题解决：序号 五 至 后。（OpenWrt 的一些功能实现会在基础知识的最后面）

一、基础知识
/*********************/
本节名词解释：
SDK —— 英文 Software Development Kit 的缩写，翻译：“软件开发套件”。
ImageBuilder —— 翻译：映像构建器。
Github —— 国际著名的开源代码托管平台，国内可能无法直接访问。
/*********************/

对于教程中任何出现方括号（“【】”）的内容，请将其（包括方括号）替换为方括号内文本表示的实际内容。
如：请将“【Linux内核版本】”替换为“5.10.4”


1. OpenWrt 的源码、SDK、ImageBuilder
如果你想定制 OpenWrt，最好的方法是直接从 OpenWrt 放在 Github 上的源码开始修改和编译。
如果你想定制/编译 opkg 的软件包（*.ipk）或定制 OpenWrt，最好的方法是直接从 OpenWrt 官方和各大镜像（如清华Tuna镜像源）上的 SDK 开始修改和编译。
如果你想简单打包 OpenWrt（给 OpenWrt 封装第三方 opkg），最好的方法是直接从 OpenWrt 官方和各大镜像（如清华Tuna镜像源）上的 ImageBuilder 开始修改和编译。

复杂度和可定制度从上往下递减。
总的来说，OpenWrt 的源码、SDK、ImageBuilder是面向不同人、不同需求所准备的。
OpenWrt 的源码也可以编译生成 SDK 和 ImageBuilder。

2. Patch 文件（补丁文件）
位置：补丁文件通常位于源码目录 “target/linux/【架构】/patches-【Linux 内核版本】/” 目录下，这个目录的名字不是固定的（请勿直接复制粘贴）。
名称：“000-XXXXXX.patch”，开头的数字（如：“000”）表示这个补丁文件的序号，也对补丁文件的应用顺序做了定义。短横线（“-”）后的英文字符串为对这个补丁文件的说明。
例如：

1. 322-mt7621-fix-cpu-clk-add-clkdev.patch

复制代码

需要注意：补丁文件开头的数字不能与现有补丁文件开头的数字重复！补丁文件的说明可以自定义。

语法：
①. 头

“头”用来表示需要修补的文件，以 +++ 和 --- 两行开头，另一个“头”的开始结束，用来表示旧文件和新文件。
例如：

1. --- a/arch/mips/ralink/mt7621.c
   
2. +++ b/arch/mips/ralink/mt7621.c

复制代码

“头”后面的块均用来修补“头”中指定的文件。

②. 块

“块”用来表示需要修补的内容，以 @@ 开头，另一个“块”的开头或另一个“头”的开头结束。
例如：

1. @@ -105,11 +110,94 @@ static struct rt2880_pmx_group mt7621_pi

复制代码

“块”的开头第一行可以称为“‘块’的起始行”，“块”的起始行中，两个“@@”（不是两个“@”）中间的内容指定这一块的内容应该修补原文件的哪里、多少行，修改的内容是什么。
在这个示例中，这一块表示：从原文件的第 105 行开始，删除 11 行，从第 110 行开始，添加 94 行。
逗号前的数字前面的符号用于表示增加行（“+”）还是删除行（“-”），不写符号则表示仅引用（用来“定位”）。
要修改的内容从“块”的起始行已经开始了，第二个“@@”后面写的内容即为要改为的内容的第一行。


******************** OpenWrt 的一些功能实现 ********************
（欢迎大家补充）
1. 更改默认的 IP 地址：
OpenWrt 默认的 IP 地址是在“192.168.1.1”，但对于需要多个子网或多台路由器来说这可能不是很好。
使用命令：

1. uci set network.lan.ipaddr='【你要修改为的IP地址】' && uci commit network

复制代码

然后重新启动路由器即可。

二、准备工作
/*********************/
本节名词解释：
Linux —— 类 Unix 的开源操作系统（常同于通称基于其的系统）。
Windows —— 由微软开发的闭源操作系统的名称。
Ubuntu —— 一个 Linux 系统的名称。
Fedora —— 一个 Linux 系统的名称。
WSL —— 英文 Windows Subsystem for Linux 的缩写，翻译：“适用于 Windows 的 Linux 子系统”。
VMware —— 集成了虚拟机环境的软件的名称。
/*********************/

1. 本人的编译环境：
   
2. CPU：Intel Core i5-10400
   
3. GPU：NVIDIA GeForce GTX650 (Patched for UEFI)
   
4. RAM：DDR4 16GB 2733MHz
   
5. 硬盘（系统）：SSD 120GB
   
6. 网络：中国联通 300Mbps GPON
   
7. 
   
8. 主系统：Windows 11 22H2 PREVIEW
   
9. 子系统：Ubuntu 20.04 LTS
   
10. 子系统环境：
    
11.   > 环境变量（PATH）：/home/levi/openwrt/staging_dir/host/bin:/home/levi/openwrt/staging_dir/toolchain-mipsel_24kc_gcc-11.2.0_musl/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    
12. 编译目标：OpenWrt 22.03 (git branch)
    
13.   > MediaTek Ralink MIPS
    
14.   > MT7621 based boards
    
15.   > Xiaomi Mi Router 3G

复制代码

1. 安装依赖，我推荐使用 Ubuntu 系统进行编译不论是虚拟机（WSL/VMware/其他）还是实体机。我尝试使用 Fedora 35（WSL）进行编译的时候尽管已经安装好各种依赖，但总有一些玄学问题。最后编译成功是在 Ubuntu 20.04 LTS（WSL）系统上。
Ubuntu 推荐执行这个命令（两条都要执行）：
（来自 OpenWrt 官网）

1. sudo apt update
   
2. sudo apt install build-essential ccache ecj fastjar file g++ gawk \
   
3. gettext git java-propose-classpath libelf-dev libncurses5-dev \
   
4. libncursesw5-dev libssl-dev python python2.7-dev python3 unzip wget \
   
5. python3-distutils python3-setuptools python3-dev rsync subversion \
   
6. swig time xsltproc zlib1g-dev

复制代码

2. 编译前准备
①. 用户：确认当前用户不是“root”用户。
②. 环境变量：
对于 WSL 官方推荐使用这个环境变量（因为 WSL 子系统的 $PATH 会包含部分 Windows 目录，而这些目录带有空格，可能导致编译失败）：

1. PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

复制代码

并且推荐在这个环境变量的基础上添加 OpenWrt 编译工具链的变量（OpenWrt 编译工具链在编译之前不存在，但是开始编译后会自动生成，因此可以在编译前添加好环境变量）：

1. PATH=~/【OpenWrt源码目录】/staging_dir/host/bin:~/[PATH TO OPENWRT]/staging_dir/toolchain-mipsel_24kc_gcc-【GCC版本】_musl/bin:$PATH

复制代码

③. 网络环境：
确保可以正常访问 OpenWrt 源码的 Github 仓库。
确保可以正常访问部分软件包源码的下载仓库/地址。
④. 源码：
首先下载 OpenWrt 的源码（克隆仓库到本地）：
git clone https://github.com/openwrt/openwrt.git
执行命令修改目录权限，防止权限问题造成编译失败：

1. chmod -R 777 OpenWrt
   
2. chmod -R +x OpenWrt

复制代码

进入源码目录，首先要做的事情是切换分支到你想要的 OpenWrt 版本，如果没有你想要的版本，请从别处下载你想要的版本的 OpenWrt 源码，如果你想要最新的版本，可以不切换分支，直接使用 master 分支的代码（但这样做可能导致你的固件包含许多 BUG）。
例如：强制 切换到 OpenWrt 22.03 版本的分支。

1. git checkout openwrt-22.03 --force

复制代码

切换分支完毕后，修改“feeds.conf.default”文件，添加你想要的 feeds 源后，保存。
使用命令更新并安装 feeds：

1. ./script/feeds update -a
   
2. ./script/feeds install -a

复制代码

三、 开始编译
1. 配置 OpenWrt 都有哪些特性，哪些功能，哪些软件包例如：固件是为什么架构的什么芯片的什么型号的设备定制的
比如我的就是：固件是为 MediaTek MIPS 架构的 MT7621 的芯片的小米路由3G设备定制的。
使用命令：

1. make menuconfig

复制代码

随后你的终端会变成一个使用键盘操作的 GUI 界面，如果终端太小则无法进行配置！
根据每一个选项的字面意思（不懂英文的自行翻译）来进行配置。
大多数的功能和配置都会占用硬盘空间，因此如果添加过多的功能和软件包则会造成固件大小和实际安装后的大小过大！

2. 根据你上一步的配置，下载编译需要的源码（包括软件包）
这步操作将减少编译时因下载错误造成的编译失败并且节省编译时间
使用命令：

1. make download -j【CPU线程数】 V=s

复制代码

请根据自己电脑的CPU来设置，例如本人的这条命令为：

1. make download -j12 V=s

复制代码

由于网络环境影响，有时会下载失败或卡住，这时可以通过“Ctrl + C”快捷键终止操作，执行下面的命令后再次执行上面的命令下载。小技巧：有时候无法通过 “curl” 工具下载特定文件或者自动下载的文件地址不正确/失效导致一直下载失败，这时可以直接利用搜索引擎搜索需要下载的文件名下载到电脑后放到 “dl” 目录下，并且执行下面的命令后继续执行上面的命令直到完全正常（无报错）。

1. rm -rf tmp/

复制代码

推荐多执行几次，确保所需软件包的源码下载正确、完整。

3. 开始编译
官方推荐使用单线程（make -j1 V=s）编译，这样会让错误显示在最底部（不同线程执行命令的顺序不同，因此错误信息返回的时间也不同，有可能导致错误信息被其他线程的正确信息推到终端后面）
开始前的建议：检查 “dl/” 目录下，下载的源文件，通常小于 1M 的是下载错误的，建议重新下载。（例如：php 8.1.3 为 11.7M，Linux 显示为 12M）
我个人推荐：
使用全线程编译，当遇到错误终止后再次多线程编译（可能解决玄学问题，但我没遇到），同一问题没有消失查看错误：有明显报错信息的，根据报错信息解决，没有的，换单线程编译查看错误（make -j1 V=sc）。
目前我遇到的错误：
1. 自己修改修补文件后语法错误；报错自动中止后修正语法错误继续多线程编译。
2. 同一个文件，但两个软件包均提供了；报错自动中止后重新配置 OpenWrt，冲突的软件包二选一（OpenWrt 自带的软件包优先保留（为了兼容性））。

使用命令：

1. make -j12 V=s

复制代码

根据我的电脑配置，最后编译成功实际花费时间（取决于功能和软件包的数量）：

因为使用的是 WSL，存在性能损耗，因此实际编译速度应该更快一点。


四、编译时的错误与解决这里仅说明我遇到的问题，我没遇到的也不知道，也不能乱说。

1. 内核编译错误
这种错误通常是 Linux 内核文件在编译时发生错误，这时需要检查是否修改过修补文件。
如果修改过，则进行检查，检查修补文件的语法是否有问题，更改的内容的语法是否有问题（比如是否缺少符号，“头”指定的新的行数是否与“块”中写入的相等）
例如：
原来修补文件的“头”是：

1. @@ -10,11 +12,<b>15</b> @@ static struct example

复制代码

意思为从第十行删去11行，从第十二行添加15行。如果增加/删除了修补文件“块”中的任何一行，则上方代码中加粗的数字应当对应增加/减少行数。

2. 软件包编译错误
这种错误通常是：
①. 选中的软件包中的部分文件相互冲突。
②. 玄学问题。

对于第①种问题，我们需要查看错误日志，找到对应提示的文件。
例如提示（大概意思）：“软件包：XXX 无法创建文件 ABC，因为 YYY 也提供了这个文件”。
这个时候需要重新配置 OpenWrt，在冲突的软件包二选一。

对于第②种问题，可能是下载的软件包源码文件有问题或莫名其妙出现这种情况（我用 Fedora 35 编译的时候会有莫名其妙的问题，但使用 Ubuntu 则一次性编译成功）。
最好的方法是再次执行编译，大多时候这种问题就会消失，但如果还不消失，则需要执行下面的命令（每个命令我会用“#”符号在末尾注释）。

1. rm -rf tmp/    #清空make download的缓存（临时文件）
   
2. rm -rf dl/【提示编译失败的软件包的名字】<TAB>    # 删除无法编译的软件包源码，<TAB>表示按键盘的“TAB键”
   
3. make download -j【CPU线程数】 V=s    # 重新下载缺少的软件包源码
   
4. make -j1 V=sc   # <b>单线程</b>编译，显示全部错误日志

复制代码

随后观察是否仍有错误，如果问题消失则可以按需求使用“Ctrl + C”终止后再次多线程编译。

欢迎补充相关的编译问题。

请不要胡乱输入以及粘贴、复制等方式灌水

请尊重作者、并共同维护网站的正常阅读，否则账户将会被限制发帖、回帖，并且积分可能会被清零，站内短信以及阅读权限等都会受到影响，谢谢。 具体限制方式：https://www.right.com.cn/forum/thread-8307840-1-1.html

Levi_Marvin

二、准备工作
/*********************/
本节名词解释：
Linux —— 类 Unix 的开源操作系统（常同于通称基于其的系统）。
Windows —— 由微软开发的闭源操作系统的名称。
Ubuntu —— 一个 Linux 系统的名称。
Fedora —— 一个 Linux 系统的名称。
WSL —— 英文 Windows Subsystem for Linux 的缩写，翻译：“适用于 Windows 的 Linux 子系统”。
VMware —— 集成了虚拟机环境的软件的名称。
/*********************/

1. 本人的编译环境：
   
2. CPU：Intel Core i5-10400
   
3. GPU：NVIDIA GeForce GTX650 (Patched for UEFI)
   
4. RAM：DDR4 16GB 2733MHz
   
5. 硬盘（系统）：SSD 120GB
   
6. 网络：中国联通 300Mbps GPON
   
7. 
   
8. 主系统：Windows 11 22H2 PREVIEW
   
9. 子系统：Ubuntu 20.04 LTS
   
10. 子系统环境：
    
11.   > 环境变量（PATH）：/home/levi/openwrt/staging_dir/host/bin:/home/levi/openwrt/staging_dir/toolchain-mipsel_24kc_gcc-11.2.0_musl/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    
12. 编译目标：OpenWrt 22.03 (git branch)
    
13.   > MediaTek Ralink MIPS
    
14.   > MT7621 based boards
    
15.   > Xiaomi Mi Router 3G

复制代码

1. 安装依赖，我推荐使用 Ubuntu 系统进行编译不论是虚拟机（WSL/VMware/其他）还是实体机。我尝试使用 Fedora 35（WSL）进行编译的时候尽管已经安装好各种依赖，但总有一些玄学问题。最后编译成功是在 Ubuntu 20.04 LTS（WSL）系统上。
Ubuntu 推荐执行这个命令（两条都要执行）：
（来自 OpenWrt 官网）

1. sudo apt update
   
2. sudo apt install build-essential ccache ecj fastjar file g++ gawk \
   
3. gettext git java-propose-classpath libelf-dev libncurses5-dev \
   
4. libncursesw5-dev libssl-dev python python2.7-dev python3 unzip wget \
   
5. python3-distutils python3-setuptools python3-dev rsync subversion \
   
6. swig time xsltproc zlib1g-dev

复制代码

2. 编译前准备
①. 用户：确认当前用户不是“root”用户。
②. 环境变量：
对于 WSL 官方推荐使用这个环境变量（因为 WSL 子系统的 $PATH 会包含部分 Windows 目录，而这些目录带有空格，可能导致编译失败）：

1. PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

复制代码

并且推荐在这个环境变量的基础上添加 OpenWrt 编译工具链的变量（OpenWrt 编译工具链在编译之前不存在，但是开始编译后会自动生成，因此可以在编译前添加好环境变量）：

1. PATH=~/【OpenWrt源码目录】/staging_dir/host/bin:~/[PATH TO OPENWRT]/staging_dir/toolchain-mipsel_24kc_gcc-【GCC版本】_musl/bin:$PATH

复制代码

③. 网络环境：
确保可以正常访问 OpenWrt 源码的 Github 仓库。
确保可以正常访问部分软件包源码的下载仓库/地址。
④. 源码：
首先下载 OpenWrt 的源码（克隆仓库到本地）：
git clone https://github.com/openwrt/openwrt.git
执行命令修改目录权限，防止权限问题造成编译失败：

1. chmod -R 777 OpenWrt
   
2. chmod -R +x OpenWrt

复制代码

进入源码目录，首先要做的事情是切换分支到你想要的 OpenWrt 版本，如果没有你想要的版本，请从别处下载你想要的版本的 OpenWrt 源码，如果你想要最新的版本，可以不切换分支，直接使用 master 分支的代码（但这样做可能导致你的固件包含许多 BUG）。
例如：强制 切换到 OpenWrt 22.03 版本的分支。

1. git checkout openwrt-22.03 --force

复制代码

切换分支完毕后，修改“feeds.conf.default”文件，添加你想要的 feeds 源后，保存。
使用命令更新并安装 feeds：

1. ./scripts/feeds update -a
   
2. ./scripts/feeds install -a

复制代码

Levi_Marvin

三、 开始编译
1. 配置 OpenWrt 都有哪些特性，哪些功能，哪些软件包例如：固件是为什么架构的什么芯片的什么型号的设备定制的
比如我的就是：固件是为 MediaTek MIPS 架构的 MT7621 的芯片的小米路由3G设备定制的。
使用命令：

1. make menuconfig

复制代码

随后你的终端会变成一个使用键盘操作的 GUI 界面，如果终端太小则无法进行配置！
根据每一个选项的字面意思（不懂英文的自行翻译）来进行配置。
大多数的功能和配置都会占用硬盘空间，因此如果添加过多的功能和软件包则会造成固件大小和实际安装后的大小过大！

2. 根据你上一步的配置，下载编译需要的源码（包括软件包）
这步操作将减少编译时因下载错误造成的编译失败并且节省编译时间
使用命令：

1. make download -j【CPU线程数】 V=s

复制代码

请根据自己电脑的CPU来设置，例如本人的这条命令为：

1. make download -j12 V=s

复制代码

由于网络环境影响，有时会下载失败或卡住，这时可以通过“Ctrl + C”快捷键终止操作，执行下面的命令后再次执行上面的命令下载。小技巧：有时候无法通过 “curl” 工具下载特定文件或者自动下载的文件地址不正确/失效导致一直下载失败，这时可以直接利用搜索引擎搜索需要下载的文件名下载到电脑后放到 “dl” 目录下，并且执行下面的命令后继续执行上面的命令直到完全正常（无报错）。

1. rm -rf tmp/

复制代码

推荐多执行几次，确保所需软件包的源码下载正确、完整。

3. 开始编译
官方推荐使用单线程（make -j1 V=s）编译，这样会让错误显示在最底部（不同线程执行命令的顺序不同，因此错误信息返回的时间也不同，有可能导致错误信息被其他线程的正确信息推到终端后面）
开始前的建议：检查 “dl/” 目录下，下载的源文件，通常小于 1M 的是下载错误的，建议重新下载。（例如：php 8.1.3 为 11.7M，Linux 显示为 12M）
我个人推荐：
使用全线程编译，当遇到错误终止后再次多线程编译（可能解决玄学问题，但我没遇到），同一问题没有消失查看错误：有明显报错信息的，根据报错信息解决，没有的，换单线程编译查看错误（make -j1 V=sc）。
目前我遇到的错误：
1. 自己修改修补文件后语法错误；报错自动中止后修正语法错误继续多线程编译。
2. 同一个文件，但两个软件包均提供了；报错自动中止后重新配置 OpenWrt，冲突的软件包二选一（OpenWrt 自带的软件包优先保留（为了兼容性））。

使用命令：

1. make -j12 V=s

复制代码

根据我的电脑配置，最后编译成功实际花费时间（取决于功能和软件包的数量）：

因为使用的是 WSL，存在性能损耗，因此实际编译速度应该更快一点。

Levi_Marvin

四、编译时的错误与解决这里仅说明我遇到的问题，我没遇到的也不知道，也不能乱说。

1. 内核编译错误
这种错误通常是 Linux 内核文件在编译时发生错误，这时需要检查是否修改过修补文件。
如果修改过，则进行检查，检查修补文件的语法是否有问题，更改的内容的语法是否有问题（比如是否缺少符号，“头”指定的新的行数是否与“块”中写入的相等）
例如：
原来修补文件的“头”是：

1. @@ -10,11 +12,<b>15</b> @@ static struct example

复制代码

意思为从第十行删去11行，从第十二行添加15行。如果增加/删除了修补文件“块”中的任何一行，则上方代码中加粗的数字应当对应增加/减少行数。

2. 软件包编译错误
这种错误通常是：
①. 选中的软件包中的部分文件相互冲突。
②. 玄学问题。

对于第①种问题，我们需要查看错误日志，找到对应提示的文件。
例如提示（大概意思）：“软件包：XXX 无法创建文件 ABC，因为 YYY 也提供了这个文件”。
这个时候需要重新配置 OpenWrt，在冲突的软件包二选一。

对于第②种问题，可能是下载的软件包源码文件有问题或莫名其妙出现这种情况（我用 Fedora 35 编译的时候会有莫名其妙的问题，但使用 Ubuntu 则一次性编译成功）。
最好的方法是再次执行编译，大多时候这种问题就会消失，但如果还不消失，则需要执行下面的命令（每个命令我会用“#”符号在末尾注释）。

1. rm -rf tmp/    #清空make download的缓存（临时文件）
   
2. rm -rf dl/【提示编译失败的软件包的名字】<TAB>    # 删除无法编译的软件包源码，<TAB>表示按键盘的“TAB键”
   
3. make download -j【CPU线程数】 V=s    # 重新下载缺少的软件包源码
   
4. make -j1 V=sc   # <b>单线程</b>编译，显示全部错误日志

复制代码

随后观察是否仍有错误，如果问题消失则可以按需求使用“Ctrl + C”终止后再次多线程编译。

欢迎补充相关的编译问题。

渣渣小白

私人定制什么啊

Hanchenl

火钳刘明，插个眼

dust2k

火钳刘明！！！

RTX10086

插眼   

Levi_Marvin

渣渣小白 发表于 2022-3-25 18:54
私人定制什么啊

不好意思，没理解你的意思

司徒哥

火钳刘明，插个眼

xpmg

哇，大工程，谢谢楼主分享

rxjhhuai

思考一下，难吗。。。要不要在虚拟机里弄。

antpliot

期待更新，多加些实际操作的图片

Levi_Marvin

antpliot 发表于 2022-3-26 10:25
期待更新，多加些实际操作的图片

不知道为啥直接从剪切板粘贴图像以后会显示非常大的帖子大小，我会抽空上传补充图片。

Levi_Marvin

rxjhhuai 发表于 2022-3-26 10:24
思考一下，难吗。。。要不要在虚拟机里弄。

我就是使用的虚拟机进行的编译。
使用的是基于 WSL （Windows Subsystem for Linux）的 Ubuntu 20.04 LTS
推荐使用 Ubuntu，因为我在使用基于 WSL 的 Fedora Remix（Fedora 35）系统的时候会有一些问题。
如果有条件还是在实体机安装 Ubuntu 比较好，虽然 WSL 虚拟机是与实体机共享 CPU、RAM 等资源，但因为多了一层 IO 会有性能损耗。