开源Linux社区Armbian开发指南

1. 什么是armbian

Armbian是一个基于Debian或Ubuntu的开源操作系统，专门针对嵌入式ARM平台进行优化和定制。Armbian可以运行在多种不同的嵌入式设备上，例如树莓派、ArmSoM、香蕉派等等。Armbian针对不同的嵌入式平台，提供了相应的硬件支持，可以让用户轻松地在这些平台上搭建自己的嵌入式系统。

armbian立项于2014年底，于2016年开始进入频繁更新，每年千万行代码的爆发式成长，截止目前为止，官网已经支持185个不同的硬件设备的适配。

2. 为什么要使用armbian

Armbian提供了丰富的软件库和组件，包括Linux内核、文件系统、应用程序等，用户可以根据自己的需要进行选择和安装。Armbian还提供了一套完整的开发工具链，方便用户进行开发和调试工作。

总的来说，Armbian是一款功能强大、灵活性高、易于定制的嵌入式操作系统，适用于各种不同的嵌入式设备和应用场景。

3. 如何使用armbian

3.1 基本要求

• x86_64 或 aarch64 计算机，至少具有 2GB 内存和 ~35GB 磁盘空间，用于虚拟机、WSL2、容器或裸机安装
• Ubuntu Jammy 22.04.x amd64 或 aarch64 用于本机构建或任何支持 Docker 的 amd64 / aarch64 Linux 用于容器化。官方支持的编译环境仅限 Ubuntu Jammy 22.04.x amd64 ！
• 超级用户权限（配置的 sudo 或 root 访问权限）。
• 确保您的所有系统组件都是最新的。例如，过时的 Docker 二进制文件可能会导致问题。
• 很多资源包下载都需要外网，中国的用户需要一个翻墙工具

3.2 开始构建

$ apt-get -y install git
$ git clone --depth=1 --branch=main https://github.com/armbian/build
$ cd build
$ ./compile.sh

命令执行后会进行以下三个操作，具体的操作解释，后续我会写文章详细解释

• 交互式图形界面。
• 通过安装必要的依赖项和源来准备工作区。
• 它指导整个过程并创建内核包或即用型 SD 卡映像。

4. 项目结构

├── cache                                Work / cache directory
│   ├── aptcache                         Packages
│   ├── ccache                           C/C++ compiler
│   ├── docker                           Docker last pull
│   ├── git-bare                         Minimal Git
│   ├── git-bundles                      Full Git
│   ├── initrd                           Ram disk
│   ├── memoize                          Git status
│   ├── patch                            Kernel drivers patch
│   ├── pip                              Python
│   ├── rootfs                           Compressed userspaces
│   ├── sources                          Kernel, u-boot and other sources
│   ├── tools                            Additional tools like ORAS
│   └── utility
├── config                               Packages repository configurations
│   ├── targets.conf                     Board build target configuration
│   ├── boards                           Board configurations
│   ├── bootenv                          Initial boot loaders environments per family
│   ├── bootscripts                      Initial Boot loaders scripts per family
│   ├── cli                              CLI packages configurations per distribution
│   ├── desktop                          Desktop packages configurations per distribution
│   ├── distributions                    Distributions settings
│   ├── kernel                           Kernel build configurations per family
│   ├── sources                          Kernel and u-boot sources locations and scripts
│   ├── templates                        User configuration templates which populate userpatches
│   └── torrents                         External compiler and rootfs cache torrents
├── extensions                           Extend build system with specific functionality
├── lib                                  Main build framework libraries
│   ├── functions
│   │   ├── artifacts
│   │   ├── bsp
│   │   ├── cli
│   │   ├── compilation
│   │   ├── configuration
│   │   ├── general
│   │   ├── host
│   │   ├── image
│   │   ├── logging
│   │   ├── main
│   │   └── rootfs
│   └── tools
├── output                               Build artifact
│   └── deb                              Deb packages
│   └── images                           Bootable images - RAW or compressed
│   └── debug                            Patch and build logs
│   └── config                           Kernel configuration export location
│   └── patch                            Created patches location
├── packages                             Support scripts, binary blobs, packages
│   ├── blobs                            Wallpapers, various configs, closed source bootloaders
│   ├── bsp-cli                          Automatically added to armbian-bsp-cli package
│   ├── bsp-desktop                      Automatically added to armbian-bsp-desktopo package
│   ├── bsp                              Scripts and configs overlay for rootfs
│   └── extras-buildpkgs                 Optional compilation and packaging engine
├── patch                                Collection of patches
│   ├── atf                              ARM trusted firmware
│   ├── kernel                           Linux kernel patches
|   |   └── family-branch                Per kernel family and branch
│   ├── misc                             Linux kernel packaging patches
│   └── u-boot                           Universal boot loader patches
|       ├── u-boot-board                 For specific board
|       └── u-boot-family                For entire kernel family
├── tools                                Tools for dealing with kernel patches and configs
└── userpatches                          User: configuration patching area
    ├── lib.config                       User: framework common config/override file
    ├── config-default.conf              User: default user config file
    ├── customize-image.sh               User: script will execute just before closing the image
    ├── atf                              User: ARM trusted firmware
    ├── kernel                           User: Linux kernel per kernel family
    ├── misc                             User: various
    └── u-boot                           User: universal boot loader patches
 CONTRIBUTING.md // We would love to have you join the Armbian 

接下来会详细拆解开发步骤，本文讲带大家熟悉如何编译出自己想要的板级固件，armbian开发指北（三）会更加详细的带大家深入代码。

1. 编译

进入项目目录执行：

$ ./compile.sh

执行脚本后会提示

[] Docker is installed, but not usable [ can't use Docker; check your Docker config / groups / etc ]
[] Problem detected [ Docker installed but not usable ]
[] Exiting in 10 seconds [ Press  to abort,  to ignore and continue ]
Counting down: 9... 8... 

armbian支持 docker环境编译，执行脚本后提示我们目前是docker环境是没有搭建好的，我们暂时不使用docker，按enter键即可

后提示输入权限密码 [sudo] password for jackson:

2. 选择是否更改kernel config

此时可看到两个选择

• Do not change the kernel configuration
• Show a kernel configuration menu before comilation

1. 选项为不更改kernel配置
2. 选项为在编译前可自行更改kernel配置

我们暂且先选择 Do not change the kernel configuration 不去更改内核配置，按enter键。

3. 选择目标

大家下载下来的 armbian/build 应该是没有armsom-w3 和 armsom-p2pro, 是我们这边开发使用暂时没有合并提交到armbian官方仓库,后续会提交。

除此以上承列的板子都是目前官方支持的，我们可以选择自己需要编译的板子固件 ,细心的朋友可能会注意到底部除了 ok，Cancel，还有一个 show CSC/WIP/EOS/TVB 选项

CSC/WIP/EOS/TVB 解释：
CSC: 社区支持的配置，社区贡献的支持。Armbian 开发团队没有官方支持
WIP：正在进行中，基本功能可以测试，但尚未准备好投入生产。
EOS：生命周期结束，支持结束。
TVB：TV 电视盒子版本

我这边选择 armsom-w3 ：Rockchip RK3588 SoC octa core 8-32GB SoC 2.5GBe PoE eMMC USB3 NvME

4. 选择要使用什么kernel版本

如上我们可以看到Legacy版本，edge版本，midstream版本，collabora版本

Legacy版本：旧的kernel版本，大概率是各个芯片厂家官方支持的kernel
edge版本：最新主线的kernel
midstream版本：介于主线mainline 和 rk官网legacy版本之间。
collabora版本：Collabora's rk3588, where the action is these days

对于后面两个版本是开发者自己客制化的版本，可以自定义任何版本，armbian在这方面做的非常弹性。

选择自己想要编译的kernel版本，这边选legacy

5. 选择目标操作系统

如上我们可以看到

• bookworm Debian12 Bookworm
• bullseys Debian11 Bullseye
• jammy Ubuntu jammy 22.04 LTS

其实就是各种os版本，系统之间的差别可自行上网了解，选择你喜欢的，这边选择bullseye

6. 选择目标系统类型（是否带桌面系统）

Image with console interface (server版本) Image with desktop environment 桌面版本

开发验证阶段可用server版本编译的更快一些，需要验证显示接口建议用desktop版本

6.1 选择目标系统带桌面版本

假如选择desktop版本将会进入

cinnamon Cinnamon desktopp environment:

Cinnamon 是一款 Linux 桌面，提供先进的创新功能和传统的用户体验。
桌面布局类似于 Gnome 2，其底层技术源自 Gnome Shell。Cinnamon 提供易于使用且舒适的桌面体验，让用户有宾至如归的感觉。

gnome Gnome desktop enviroment:

GNOME是一套纯粹自由的计算机软件，运行在操作系统上，提供图形桌面环境。
桌面环境具有简洁、自定义性高、多任务支持、丰富的应用程序和开放性等特点，适合那些注重用户体验、个性化和开放性的用户。

i3-wm I3-wm desktop enviroment

平铺式桌面实在是太棒了！也许你习惯了KDE、Gnome、Xfce、Cinammon这些主流桌面后可以尝试一下

xfce Xfce desktop enviroment

Xfce 是一个以速度、性能和资源效率为重点的轻量级桌面环境。它在不牺牲功能的情况下，提供了一个干净直观的用户界面。它采用了经过时间验证的、传统的图标和菜单驱动的用户界面，对提高生产力非常有效。此外，Xfce 还允许用户根据自己的偏好进行个性化设置。

我们偏好采用 gnome desktop，纯属个人喜好。

之后会要求选择我们需要安装的软件，根据自己喜好选择，可多选。

6.2 选择目标系统server版本

Standard image with console interface：标准server版本

Minimal image with console interface：最小server版本

两者具体的差别，暂未深入

7. 总结

至此已经选择完所有配置开始编译，编译过程中大家可注意到

Repeat Build Options (early) [./compile.sh build BOARD=armsom-w3 BRANCH=legacy BUILD_DESKTOP=yes BUILD_MINIMAL=no DESKTOP_APPGROUPS_SELECTED='3dsupport browsers chat desktop_tools editors internet multimedia office programming remote_desktop' DESKTOP_ENVIRONMENT=gnome DESKTOP_ENVIRONMENT_CONFIG_NAME=config_base KERNEL_CONFIGURE=no RELEASE=bullseye ]

其中./compile.sh 后面的参数便是我们所有的选择，后续开发如果不想用图形页面选择，可直接输入以上命令

假设我们现在需要把Banana Pi 与armsom团队开发的Banana Pi BPI-W3(armsom-w3)

1. board.config 板级配置

$ armsom/armbian/build/config/boards

改目录下存放目前armbian支持的board，首先我们要建立自己的config armsom-w3.config, show code no bb

# Rockchip RK3588 SoC octa core 8-32GB SoC 2.5GBe PoE eMMC USB3 NvME 
// 这行是我们执行编译脚本后，选择哪个boader后面的描述，可自行更改
BOARD_NAME="ArmSoM W3" 
// 板子名称
BOARDFAMILY="rockchip-rk3588" 
// rockchip-rk3588 文件在config/sources/families/rockchip-rk3588.conf，里面有详细的板子kernel，uboot下载链接，各种配置
BOARD_MAINTAINER="armsom-team"
// 板子的维护者名称
BOOTCONFIG="rock-5b-rk3588_defconfig"
// uboot的config
KERNEL_TARGET="legacy,edge,midstream,collabora"
// kernel支持哪些版本
KERNEL_TEST_TARGET="legacy" # in case different then kernel target
FULL_DESKTOP="yes"
BOOT_LOGO="desktop"
BOOT_FDT_FILE="rockchip/rk3588-rock-5b.dtb"
BOOT_SCENARIO="spl-blobs"
BOOT_SUPPORT_SPI="yes"
BOOT_SPI_RKSPI_LOADER="yes"
IMAGE_PARTITION_TABLE="gpt"
SKIP_BOOTSPLASH="yes" # Skip boot splash patch, conflicts with CONFIG_VT=yes
BOOTFS_TYPE="ext4"
 
function post_family_tweaks__rock5b_naming_audios() {
	display_alert "$BOARD" "Renaming rock5b audios" "info"
 
	mkdir -p $SDCARD/etc/udev/rules.d/
	echo 'SUBSYSTEM=="sound", ENV{ID_PATH}=="platform-hdmi0-sound", ENV{SOUND_DESCRIPTION}="HDMI0 Audio"' > $SDCARD/etc/udev/rules.d/90-naming-audios.rules
	echo 'SUBSYSTEM=="sound", ENV{ID_PATH}=="platform-hdmi1-sound", ENV{SOUND_DESCRIPTION}="HDMI1 Audio"' >> $SDCARD/etc/udev/rules.d/90-naming-audios.rules
	echo 'SUBSYSTEM=="sound", ENV{ID_PATH}=="platform-hdmiin-sound", ENV{SOUND_DESCRIPTION}="HDMI-In Audio"' >> $SDCARD/etc/udev/rules.d/90-naming-audios.rules
	echo 'SUBSYSTEM=="sound", ENV{ID_PATH}=="platform-dp0-sound", ENV{SOUND_DESCRIPTION}="DP0 Audio"' >> $SDCARD/etc/udev/rules.d/90-naming-audios.rules
	echo 'SUBSYSTEM=="sound", ENV{ID_PATH}=="platform-es8316-sound", ENV{SOUND_DESCRIPTION}="ES8316 Audio"' >> $SDCARD/etc/udev/rules.d/90-naming-audios.rules
	return 0
}

以上boards配置均可在config/boards/README.md文件查看详细解释

lib/functions/artifacts/artifacts-obtain.sh 去掉413行的else，确保每次都会拉kernel uboot到 cache目录，方便开发 artifact_exists_in_remote_cache=no

查看单独编译kernel命令，output里面的log，

把sd卡固件烧录到emmc nand-sata-install