openEuler/SBC-sig
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: how to build images in README

Browse Source
This commit is contained in:
Yafen 2025-09-02 17:11:14 +08:00
parent 943b02a62b
commit ddd415986e
5 changed files with 212 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
README.en.md
View File

@ -16,6 +16,8 @@ This repository is the main repository of the openEuler SBC (Single-Board Comput
- [How to build image](#how-to-build-image)
- [Prepare the environment](#prepare-the-environment)
- [Run the scripts to build image](#run-the-scripts-to-build-image)
- [Build on host](#build-on-host)
- [Build in a Docker container](#build-in-a-docker-container)
<!-- /TOC -->
@ -306,3 +308,95 @@ For other architecture hardware, you can use [QEMU](https://www.qemu.org/) to bu
You can use the unified build scripts [build.sh](./scripts/build.sh) or [build-image-docker.sh](./scripts/build-image-docker.sh) to build images for Raspberry Pi, Rockchip, and other development boards, either directly on the host machine or by launching a Docker container. For details, please refer to the documentation below:
- [Build Raspberry Pi images](./documents/RaspberryPi.md#构建镜像)
- [Build images for Rochchip and other SoCs](./documents/Rockchip.md#镜像构建)
#### Build on host
Run the following command to build images on the host machine:
`sudo bash build.sh --board BOARD_CONFIG -n NAME -k KERNEL_URL -b KERNEL_BRANCH -c KERNEL_DEFCONFIG -r REPO_INFO -s SPEC --cores N`
After building the image, you can find the image in `build/YYYY-MM-DD` of the directory in which the script resides as shown in the script output.
**NOTE: You can directly execute "sudo bash build.sh" to build an openEuler 20.03 LTS image for Firefly-RK3399 with the script's default parameters.**
**Parameter Descriptions**
1. --board BOARD_CONFIG
The board configuration files are located in the [boards](scripts/boards) directory. See the example file [sample.conf](scripts/boards/sample.conf). The default is `firefly-rk3399`.
Configuration parameters included:
- platform=PLATFORM
The Hardware platform used by the board. Currently supported platforms are: broadcom, rockchip, phytium. Default is `rockchip`.
- device-tree=DTB_NAME
The device name in the kernel device tree (slightly different from the board name). Corresponds to the `DTB_NAME.dts` file under [kernel/arch/arm64/boot/dts/rockchip](https://gitee.com/openeuler/kernel/tree/master/arch/arm64/boot/dts/rockchip). Default is `rk3399-firefly`.
- ubootconfig=UBOOT_DEFCONFIG
The defconfig file name for the development board. Corresponds to the `UBOOT_DEFCONFIG` file under [u-boot/configs](https://github.com/u-boot/u-boot/tree/master/configs). Default is `firefly-rk3399_defconfig`. To use a precompiled u-boot (e.g., on RK3588), set this to empty: ubootconfig=.
2. -n, --name IMAGE_NAME
The image name to be built. For example, `openEuler-20.03-LTS-Firefly-RK3399-aarch64-alpha1` or `openEuler-24.03-LTS-raspi-aarch64-alpha1`.
3. -k, --kernel KERNEL_URL
The URL of kernel source repository, which defaults to `https://gitee.com/openeuler/raspberrypi-kernel.git`. You can set the parameter as `git@gitee.com:openeuler/raspberrypi-kernel.git` or `git@gitee.com:openeuler/kernel.git` according to the requirement.
4. -b, --branch KERNEL_BRANCH
The branch name of kernel source repository, which defaults to openEuler-20.03-LTS.
5. -c, --config KERNEL_DEFCONFIG
The filename/path of configuration for compiling kernel, which defaults to `openeuler-raspi_defconfig`. If this parameter is the filename of configuration, please make sure the configuration file in `arch/arm64/configs` of the kernel source.
6. -r, --repo REPO_INFO
The URL/path of target repo file, or the list of repositories' baseurls. Note that, the baseurls should be separated by space and enclosed in double quotes.
Examples are as follows:
- The URL of target repo file: `https://gitee.com/src-openeuler/openEuler-repos/raw/openEuler-20.03-LTS/generic.repo`.
- The path of target repo file:
`./openEuler-20.03-LTS.repo`：for building openEuler 20.03 LTS image, refer to <https://gitee.com/src-openeuler/openEuler-repos/blob/openEuler-20.03-LTS/generic.repo> for details.
- List of repo's baseurls: `http://repo.openeuler.org/openEuler-20.03-LTS/OS/aarch64/ http://repo.openeuler.org/openEuler-20.03-LTS/EPOL/aarch64/`.
7. -s, --spec SPEC
Specify the image version:
- `headless`, image without desktop environments.
- `xfce`, image with Xfce desktop environment and related software including CJK fonts and IME.
- `ukui`, image with UKUI desktop environment and fundamental software including CJK fonts and IME.
- `dde`, image with DDE desktop environment and fundamental software including CJK fonts and IME.
- `gnome`，image with GNOME desktop environment and fundamental software including CJK fonts and IME.
- `devstation`，image with GNOME desktop environment and fundamental software including CJK fonts, IME, development tools and IDEs.
- The file path of rpmlist, the file contains a list of the software to be installed in the image, refer to [rpmlist](./scripts/configs/rpmlist) for details.
The default is `headless`.
8. --cores N
The number of parallel compilations, according to the actual number of CPU of the host running the script. The default is the number of processing units available.
9. -h, --help
Displays help information.
#### Build in a Docker container
Run the following command to build an image in a Docker container:
`sudo bash build-image-docker.sh -d DOCKER_FILE --board BOARD_CONFIG -n NAME -k KERNEL_URL -b KERNEL_BRANCH -c KERNEL_DEFCONFIG -r REPO_INFO -s SPEC --cores N`
After building the image, you can find the image in `build/YYYY-MM-DD` of the directory in which the script resides.
Caution, before running the script, you need to install Docker. The script will automatically import the Docker image into the local system according to the script's parameter: DOCKER_FILE.
In addition to the parameter DOCKER_FILE, the other parameters are the same as the corresponding parameters in [Build on host](#build-on-host):
1. -d, --docker DOCKER_FILE
The URL/path of the Docker image, which defaults to `https://repo.openeuler.org/openEuler-20.03-LTS-SP1/docker_img/aarch64/openEuler-docker.aarch64.tar.xz`. With the default parameter, the script will automatically download the Docker image of openEuler 20.03 LTS SP1 and import it into the local system.

99
README.md
View File

@ -16,6 +16,8 @@
- [镜像构建](#镜像构建)
- [准备环境](#准备环境)
- [构建镜像](#构建镜像)
- [宿主机上构建镜像](#宿主机上构建镜像)
- [Docker 容器内构建镜像](#docker-容器内构建镜像)
<!-- /TOC -->
## To Do List
@ -302,6 +304,101 @@ SIG 组基本信息位于 [sig-SBC](https://gitee.com/openeuler/community/tree/m
其他架构可以使用 [QEMU](https://www.qemu.org/) 模拟器搭建 AArch64 运行环境。
### 构建镜像
镜像构建使用统一入口 [build.sh](./scripts/build.sh) 或 [build-image-docker.sh](./scripts/build-image-docker.sh) 在宿主机或者启动 Docker 容器构建树莓派或瑞芯微等开发板镜像。具体参考以下文档：
镜像构建使用统一入口 [build.sh](./scripts/build.sh) 或 [build-image-docker.sh](./scripts/build-image-docker.sh) 在宿主机或者启动 Docker 容器构建树莓派或瑞芯微等开发板镜像。
具体参考以下文档：
- [树莓派镜像构建](./documents/RaspberryPi.md#构建镜像)
- [瑞芯微等开发板镜像构建](./documents/Rockchip.md#镜像构建)
#### 宿主机上构建镜像
构建镜像需执行命令：
`sudo bash build.sh --board BOARD_CONFIG -n NAME -k KERNEL_URL -b KERNEL_BRANCH -c KERNEL_DEFCONFIG -r REPO_INFO -s SPEC --cores N`
脚本运行结束后，会提示镜像的存储位置，镜像默认保存在脚本运行所在目录的 build/YYYY-MM-DD/ 下。
**说明: 基于 build.sh 提供的默认参数，执行 sudo bash build.sh 可构建 Firefly-RK3399 的 openEuler-20.03-LTS 镜像。**
**参数意义**
1. --board BOARD_CONFIG
适用的开发板的版型配置文件在 [boards](scripts/boards) 文件夹中，示例文件 [sample.conf](scripts/boards/sample.conf)，默认为 `firefly-rk3399`。
其包括的配置参数意义如下：
- platform=PLATFORM
开发板所使用的平台，目前支持的平台有：broadcom、rockchip、phytium，默认为 `rockchip`。
- device-tree=DTB_NAME
内核设备树中的设备名称，和开发板名称有一点区别，对应 [kernel/arch/arm64/boot/dts/rockchip](https://gitee.com/openeuler/kernel/tree/master/arch/arm64/boot/dts/rockchip) 下的 `DTB_NAME.dts` 文件，默认为 `rk3399-firefly`。
- ubootconfig=UBOOT_DEFCONFIG
开发板对应的 defconfig 的文件名称，对应 [u-boot/configs](https://github.com/u-boot/u-boot/tree/master/configs) 下 `UBOOT_DEFCONFIG` 文件，默认为 `firefly-rk3399_defconfig`；如需在 RK3588 开发板上使用预编译的 u-boot，可以将此项设置为空：`ubootconfig=`。
2. -n, --name IMAGE_NAME
构建的镜像名称，例如：`openEuler-20.03-LTS-Firefly-RK3399-aarch64-alpha1` 或 `openEuler-24.03-LTS-raspi-aarch64-alpha1`。
3. -k, --kernel KERNEL_URL
内核源码仓库的项目地址，默认为 `https://gitee.com/openeuler/rockchip-kernel.git`。可根据需要设置为 `git@gitee.com:openeuler/rockchip-kernel.git` 或 `git@gitee.com:openeuler/kernel.git`。
4. -b, --branch KERNEL_BRANCH
内核源码的对应分支，默认为 openEuler-20.03-LTS。
5. -c, --config KERNEL_DEFCONFIG
内核编译使用的配置文件名称或路径，默认为 `openeuler_rockchip_defconfig`。如果该参数为配置文件名称，请确保该文件在内核源码的目录 `arch/arm64/configs` 下。
6. -r, --repo REPO_INFO
软件源 repo 文件的 URL 或者路径，也可以是软件源中资源库的 baseurl 列表。注意，如果该参数为资源库的 baseurl 列表，该参数需要使用双引号，各个 baseurl 之间以空格隔开。
下面分别举例：
- 软件源 repo 文件的 URL，如 `https://gitee.com/src-openeuler/openEuler-repos/raw/openEuler-20.03-LTS/generic.repo`。
- 软件源的 repo 文件路径：
`./openEuler-20.03-LTS.repo`：生成 openEuler 20.03 LTS 版本的镜像，该文件内容参考 <https://gitee.com/src-openeuler/openEuler-repos/blob/openEuler-20.03-LTS/generic.repo>。
- 资源库的 baseurl 列表，如 `http://repo.openeuler.org/openEuler-20.03-LTS/OS/aarch64/ http://repo.openeuler.org/openEuler-20.03-LTS/EPOL/aarch64/`。
7. -s, --spec SPEC
构建的镜像版本：
- `headless`，无图形界面版的镜像。
- `xfce`，带 Xfce 桌面以及中文字体、输入法等全部配套软件。
- `ukui`，带 UKUI 桌面以及中文字体、输入法等全部配套软件。
- `dde`，带 DDE 桌面以及中文字体、输入法等全部配套软件。
- `gnome`，带 GNOME 桌面以及中文字体、输入法等全部配套软件。
- `devstation`，带 GNOME 桌面、中文字体、输入法、大量开发工具和 IDE 等配套软件。
- rpmlist 文件路径，其中包含镜像中要安装的软件列表，内容参考 [rpmlist](../scripts/configs/rockchip//rpmlist)。
默认使用 `headless` 选项。
8. --cores N
并行编译的数量，根据运行脚本的宿主机 CPU 实际数目设定，默认为可用的 CPU 总数。
9. -h, --help
显示帮助信息。
#### Docker 容器内构建镜像
构建镜像需执行命令：
`sudo bash build-image-docker.sh -d DOCKER_FILE --board BOARD_CONFIG -n NAME -k KERNEL_URL -b KERNEL_BRANCH -c KERNEL_DEFCONFIG -r REPO_INFO -s SPEC --cores N`
脚本运行结束后，会提示镜像的存储位置，镜像默认保存在脚本运行所在目录的 `build/YYYY-MM-DD/` 下。
注意！！！运行该脚本前，需安装 Docker 运行环境。该脚本会自动将 `-d DOCKER_FILE` 参数对应的 Docker 镜像导入本机系统中。
除参数 `-d DOCKER_FILE` 外，其余参数与 [宿主机上构建镜像](#宿主机上构建镜像) 中 [build.sh](scripts/build.sh) 对应参数一致：
1. -d, --docker DOCKER_FILE
Docker 镜像的 URL 或者路径， 默认为 `https://repo.openeuler.org/openEuler-20.03-LTS-SP1/docker_img/aarch64/openEuler-docker.aarch64.tar.xz`。使用该默认参数时，脚本会自动下载 openEuler 20.03 LTS SP1 的 Docker 镜像，并导入本机系统中。

28
documents/RaspberryPi.md
View File

@ -13,7 +13,7 @@
- [构建镜像](#构建镜像)
- [无需编译内核构建镜像](#无需编译内核构建镜像)
- [使用自定义内核构建镜像](#使用自定义内核构建镜像)
- [Docker 容器内构建](#docker-容器内构建)
- [Docker 容器内构建镜像](#docker-容器内构建镜像)
<!-- /TOC -->
@ -87,7 +87,7 @@
各个参数意义：
1. --board BOARD_CONFIG
1. --board BOARD_CONFIG
适用的开发板的版型配置文件在 [boards](../scripts/boards) 文件夹中，示例文件 [sample.conf](../scripts/boards/sample.conf)。构建树莓派镜像需要设置为 `raspberrypi`，对应文件 [raspberrypi.conf](../scripts/boards/raspberrypi.conf)。
@ -105,24 +105,19 @@
开发板对应的 defconfig 的文件名称，对应 [u-boot/configs](https://github.com/u-boot/u-boot/tree/master/configs) 下 `UBOOT_DEFCONFIG` 文件，默认为 `firefly-rk3399_defconfig`。构建树莓派镜像无需这部分内容，默认为空：`ubootconfig=`。
2. -n, --name IMAGE_NAME
2. -n, --name IMAGE_NAME
构建的镜像名称，例如：`openEuler-24.03-LTS-raspi-aarch64-alpha1`。
3. -k, --kernel KERNEL_URL
3. -k, --kernel KERNEL_URL
内核源码仓库的项目地址，如 `https://gitee.com/openeuler/raspberrypi-kernel.git`。可根据需要设置为 `git@gitee.com:openeuler/raspberrypi-kernel.git` 或 `git@gitee.com:openeuler/kernel.git`。
内核源码仓库的项目地址，如 `https://gitee.com/openeuler/raspberrypi-kernel.git`。可根据需要设置为 `git@gitee.com:openeuler/raspberrypi-kernel.git` 或 `git@gitee.com:openeuler/kernel.git`。
注意，如果本参数为空，则不会编译内核源码，默认使用软件源中的内核包。
注意，如果本参数为空，则不会编译内核源码，默认使用软件源中的内核包。
4. -b, --branch KERNEL_BRANCH
4. -b, --branch KERNEL_BRANCH
内核源码的对应分支，例如：OLK-6.6。根据 -k 参数有以下选择：
- -k https://gitee.com/openeuler/rockchip-kernel.git
- openEuler-20.03-LTS
- -k https://gitee.com/openeuler/kernel.git
- openEuler-21.09
内核源码的对应分支，例如：OLK-6.6。详细信息可参考 [使用自定义内核构建镜像](#使用自定义内核构建镜像) 章节。
5. -c, --config KERNEL_DEFCONFIG
@ -130,14 +125,15 @@
注意，如果 `--branch` 参数为 `OLK-6.6` 且本参数 `--config` 为空，则默认编译出同时支持树莓派 5 和树莓派 4B 的内核映像。
6. -r, --repo REPO_INFO
6. -r, --repo REPO_INFO
软件源 repo 文件的 URL 或者路径，也可以是软件源中资源库的 baseurl 列表。注意，如果该参数为资源库的 baseurl 列表，该参数需要使用双引号，各个 baseurl 之间以空格隔开。
下面分别举例：
- 软件源 repo 文件的 URL，如 `https://gitee.com/src-openeuler/openEuler-repos/raw/openEuler-20.03-LTS-SP1/generic.repo`
- 软件源的 repo 文件路径：
- `./openEuler-20.03-LTS-SP1.repo`：生成 openEuler 20.03 LTS SP1 版本的镜像，该文件内容参考 <https://gitee.com/src-openeuler/openEuler-repos/blob/openEuler-20.03-LTS-SP1/generic.repo>。
`./openEuler-20.03-LTS-SP1.repo`：生成 openEuler 20.03 LTS SP1 版本的镜像，该文件内容参考 <https://gitee.com/src-openeuler/openEuler-repos/blob/openEuler-20.03-LTS-SP1/generic.repo>。
- 资源库的 baseurl 列表，如 `"http://repo.openeuler.org/openEuler-20.03-LTS-SP1/OS/aarch64/ http://repo.openeuler.org/openEuler-20.03-LTS-SP1/EPOL/aarch64/"`。
7. -s, --spec SPEC
@ -226,7 +222,7 @@
> - openEuler 25.03：需要选择 [openEuler-RaspberryPi 内核](https://gitee.com/openeuler/raspberrypi-kernel) 的 [openEuler-25.03](https://gitee.com/openeuler/raspberrypi-kernel/tree/openEuler-25.03/) 分支，即将参数 `-k/--kernel` 设置为 `git@gitee.com:openeuler/raspberrypi-kernel.git`，`-b/--branch` 设置为 `openEuler-25.03`，`-c/--config` 设置为空 `""`。
>6. 根据需要设置 -s/--spec，其具体意义见该参数的介绍部分。
#### Docker 容器内构建
#### Docker 容器内构建镜像
构建镜像需执行命令：

14
documents/Rockchip.md
View File

@ -91,7 +91,7 @@
各个参数意义：
1. --board BOARD_CONFIG
1. --board BOARD_CONFIG
适用的开发板的版型配置文件在 [boards](../scripts/boards) 文件夹中，示例文件 [sample.conf](../scripts/boards/sample.conf)，默认为 `firefly-rk3399`。
@ -109,15 +109,15 @@
开发板对应的 defconfig 的文件名称，对应 [u-boot/configs](https://github.com/u-boot/u-boot/tree/master/configs) 下 `UBOOT_DEFCONFIG` 文件，默认为 `firefly-rk3399_defconfig`；如需在 RK3588 开发板上使用预编译的 u-boot，可以将此项设置为空：`ubootconfig=`。
2. -n, --name IMAGE_NAME
2. -n, --name IMAGE_NAME
构建的镜像名称，例如：`openEuler-20.03-LTS-Firefly-RK3399-aarch64-alpha1` 或 `openEuler-21.09-Firefly-RK3399-aarch64-alpha1`。
3. -k, --kernel KERNEL_URL
3. -k, --kernel KERNEL_URL
内核源码仓库的项目地址，默认为 `https://gitee.com/openeuler/rockchip-kernel.git`。可根据需要设置为 `git@gitee.com:openeuler/rockchip-kernel.git` 或 `git@gitee.com:openeuler/kernel.git`。
内核源码仓库的项目地址，默认为 `https://gitee.com/openeuler/rockchip-kernel.git`。可根据需要设置为 `git@gitee.com:openeuler/rockchip-kernel.git` 或 `git@gitee.com:openeuler/kernel.git`。
4. -b, --branch KERNEL_BRANCH
4. -b, --branch KERNEL_BRANCH
内核源码的对应分支，默认为 openEuler-20.03-LTS。根据 -k 参数有以下选择：
@ -130,7 +130,7 @@
内核编译使用的配置文件名称或路径，默认为 `openeuler_rockchip_defconfig`。如果该参数为配置文件名称，请确保该文件在内核源码的目录 arch/arm64/configs 下。
6. -r, --repo REPO_INFO
6. -r, --repo REPO_INFO
软件源 repo 文件的 URL 或者路径，也可以是软件源中资源库的 baseurl 列表。注意，如果该参数为资源库的 baseurl 列表，该参数需要使用双引号，各个 baseurl 之间以空格隔开。
下面分别举例：
@ -261,7 +261,7 @@
#### 使用脚本构建镜像需执行命令：
`sudo bash build-image-docker.sh --board BOARD_CONFIG -d DOCKER_FILE -n IMAGE_NAME -k KERNEL_URL -b KERNEL_BRANCH -c KERNEL_DEFCONFIG -r REPO --cores N`
`sudo bash build-image-docker.sh -d DOCKER_FILE --board BOARD_CONFIG -n NAME -k KERNEL_URL -b KERNEL_BRANCH -c KERNEL_DEFCONFIG -r REPO_INFO -s SPEC --cores N`
脚本运行结束后，镜像默认保存在脚本运行所在目录的 `build/YYYY-MM-DD` 下。

2
scripts/gen_image.sh
View File

@ -328,7 +328,7 @@ default_param
parseargs "$@" || help $?
if [ "x${board}" == "xraspberrypi" ]; then
config_dir=${cur_dir}/configs-raspberrypi
config_dir=${cur_dir}/configs/raspberrypi
fi
if [ ! -d ${workdir} ]; then