docs: how to build images in README

2025-09-02 17:11:14 +08:00 · 2025-09-02 17:11:14 +08:00 · ddd415986e
commit ddd415986e
parent 943b02a62b
5 changed files with 212 additions and 25 deletions
--- a/README.en.md
+++ b/README.en.md
@ -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.
--- a/README.md
+++ b/README.md
@ -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 镜像，并导入本机系统中。
--- a/documents/RaspberryPi.md
+++ b/documents/RaspberryPi.md
@ -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 容器内构建镜像

 构建镜像需执行命令：

--- a/documents/Rockchip.md
+++ b/documents/Rockchip.md
@ -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` 下。

--- a/scripts/gen_image.sh
+++ b/scripts/gen_image.sh
@ -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