From ddd415986ed148785e076137dce0a93230721035 Mon Sep 17 00:00:00 2001 From: Yafen Date: Tue, 2 Sep 2025 17:11:14 +0800 Subject: [PATCH] docs: how to build images in README --- README.en.md | 94 ++++++++++++++++++++++++++++++++++++++ README.md | 99 +++++++++++++++++++++++++++++++++++++++- documents/RaspberryPi.md | 28 +++++------- documents/Rockchip.md | 14 +++--- scripts/gen_image.sh | 2 +- 5 files changed, 212 insertions(+), 25 deletions(-) diff --git a/README.en.md b/README.en.md index ead9bc6..4600025 100644 --- 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) @@ -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 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. \ No newline at end of file diff --git a/README.md b/README.md index f46a1ac..c1d9530 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ - [镜像构建](#镜像构建) - [准备环境](#准备环境) - [构建镜像](#构建镜像) + - [宿主机上构建镜像](#宿主机上构建镜像) + - [Docker 容器内构建镜像](#docker-容器内构建镜像) ## 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 版本的镜像，该文件内容参考 。 + + - 资源库的 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 镜像，并导入本机系统中。 \ No newline at end of file diff --git a/documents/RaspberryPi.md b/documents/RaspberryPi.md index fe378de..9724b2f 100644 --- a/documents/RaspberryPi.md +++ b/documents/RaspberryPi.md @@ -13,7 +13,7 @@ - [构建镜像](#构建镜像) - [无需编译内核构建镜像](#无需编译内核构建镜像) - [使用自定义内核构建镜像](#使用自定义内核构建镜像) - - [Docker 容器内构建](#docker-容器内构建) + - [Docker 容器内构建镜像](#docker-容器内构建镜像) @@ -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 版本的镜像，该文件内容参考 。 + + `./openEuler-20.03-LTS-SP1.repo`：生成 openEuler 20.03 LTS SP1 版本的镜像，该文件内容参考 。 - 资源库的 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 容器内构建镜像 构建镜像需执行命令： diff --git a/documents/Rockchip.md b/documents/Rockchip.md index d647f6a..912e900 100644 --- 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` 下。 diff --git a/scripts/gen_image.sh b/scripts/gen_image.sh index 3e0d3ef..41f58df 100755 --- 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