# oebuild

**Repository Path**: digitzh/oebuild

## Basic Information

- **Project Name**: oebuild
- **Description**: oebuild is a meta tool for openEuler Embedded
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 38
- **Created**: 2023-08-31
- **Last Updated**: 2023-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### 总体介绍

oebuild是openEuler Embedded孵化的一个开源项目，是为了辅助开发openEuler Embedded项目而衍生的辅助开发工具，可促进openEuler Embedded项目健康运行。目前oebuild实现了主体框架，业务只涵盖了构建，将来会涉及到CI/CD、本地测试、云构建等等。oebuild的使用不仅限于命令行窗口，还会搭载上层IDE来使用。

虽然yocto实现了构建的灵活性，但是应用的定制与实现所需学习成本与环境成本较高。oebuild则可摆脱此类开发羁绊、解放双手，只需几个指令，即可获得所需应用镜像，无需下载代码或准备编译环境。如果所需应用不是特有定制的，甚至不要求学习如何修改bb文件，一切都可以交给oebuild来做，而oebuild需要的，仅仅是一个网络而已。对，就这么简单！！！

### 如何编译一个标准镜像

下面将介绍如何使用oebuild编译基于openEuler Embedded项目标准的aarch64 qemu应用。

#### 安装python3和pip

oebuild由python语言编写而成，通过pip命令完成安装，python3与pip的安装指令视操作系统而定，以ubuntu系统为例，通过如下命令安装：

```
apt-get install python3 python3-pip
```

如果是CentOS，则通过如下命令安装：

```
yum install python3 python3-pip
```

如果是SUSE，则通过如下命令安装：

```
zepper install python3 python3-pip
```

> 注1：由于版本或名称可能会有所不同，因此请根据实际环境来安装python3和pip，例如有些系统会默认python即python3，有些系统则需要使用python-is-python3包来安装。
>
> 注2：如果本机系统没有pip包，可以通过离线方式预先下载pip包，再通过python安装。通过如下命令来完成pip的安装：

```
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py   # 下载安装脚本
python get-pip.py	# python is python3
```

#### 安装oebuild

安装完pip后可以通过以下命令来完成oebuild的安装：

```
pip install oebuild
```

或者点击[该地址](https://gitee.com/alichinese/oebuild-bin)进入oebuild二进制仓，在该仓下有最新的二进制包，运行以下命令来完成oebuild的安装。

```
pip install <oebuild.wheel>
```
> 注：目前实测pip install oebuild安装方式不稳定，Ubuntu系统可用二进制包方式完成oebuild安装，其他系统正在测试中。——2023.8.31

oebuild会依赖一些第三方库辅助运行，因此也会直接安装相关的第三方库，如果安装过程报第三方库安装请求失败等错误，再次重新运行安装oebuild的命令即可。

> 注：如果以root用户安装oebuild，则安装后可以直接运行，如果以普通用户安装，注意需将普通用户执行路径添加到环境变量中。可以参考以下方式来完成添加：

1. 以普通用户身份打开.bashrc：

```
    cd ~ && vim .bashrc
```

2. 在文件末尾查看是否将命令执行路径添加到环境变量中，该路径一般为`/home/<user>/.local/bin`，如果没有，则将以下语句添加到文件末尾：

```
    export PATH=/home/<user>/.local/bin:$PATH
```

- 在以上命令行中，`<user>`表示当前用户名，可以通过指令`whoami`来确定。

3. 在添加完成后保存退出。vim的保存退出方法：先按`Esc`，再键入`:wq`，按回车键即可。

4. 退出后还需要执行以下命令刷新环境变量：

```
    source ~/.bashrc
```

此时即可使用oebuild工具了，可尝试执行`oebuild -h`，若能显示oebuild的帮助信息则表示已完成安装。

#### 初始化oebuild目录

运行如下命令以初始化oebuild目录：

```
oebuild init <directory>
```

其中`<directory>`需要替换为要初始化的目录名称。

由于oebuild整体依赖docker环境而运行，因此如果本地没有安装docker应用，则需按照oebuild给出的提示进行操作，即可完成docker环境的配置。

> 也可按以下方式安装docker：
>
> 1. 根据本机系统类型输入指令安装docker，以ubuntu为例：
>
>```
>    sudo apt install docker docker.io -y
>```
>
>2. 添加docker用户组：
>
>```
>    sudo groupadd docker
>```
>
>3. 将本用户添加到docker组内：
>
>```
>    sudo usermod -a -G docker $(whoami)
>```
>
>4. 重新启动docker：
>
>```
>    sudo systemctl daemon-reload && sudo systemctl restart docker
>```
>
>5. 修改docker.sock读写权限：
>
>```
>    sudo chmod o+rw /var/run/docker.sock
>```
>
>其他操作系统下的配置可参考上述指令进行。

#### 更新oebuild运行环境

运行如下命令以完成初期环境的准备工作：

```
oebuild update
```

更新工作主要有两点：  
1. pull相关的运行容器镜像；  
2. 从gitee下载yocto-meta-openeuler仓代码。
   - 如果本地没有openeuler相关容器，则这一步执行会比较漫长，请耐心等待。

#### 创建编译配置文件

运行如下命令以产生编译配置文件：

```
oebuild generate
```

默认配置文件对应的镜像是aarch64标准镜像。

#### 执行构建操作

执行如下命令以进入镜像构建程序：

```
oebuild bitbake openeuler-image
```

耐心等待20~50分钟（视主机性能而定），即可得到标准的openEuler Embedded aarch64架构的镜像。

### 命令介绍

#### oebuild init

目录初始化指令，主要用于初始化oebuild项目目录。运行该指令需要提供要初始化的目录名参数：

```
oebuild init [directory] [-u yocto_remote_url] [-b branch]
```

各参数说明如下：

directory: 要初始化的目录名称。
>注意：已经初始化的目录内无法再次执行初始化操作。

yocto_remote_url：yocto-meta-openeuler的remote远程链接。

branch：yocto-meta-openeuler的分支。

> 注意：oebuild在执行构建任务时是依赖已经适配oebuild的yocto-meta-openeuler的仓的。

例如，初始化demo目录只需要执行如下命令：

```
oebuild init demo
```

init命令执行后主要执行两个任务：一是创建src源码目录。创建.oebuild目录，拷贝config配置文件到.oebuild。二是如果设置了-u或-b参数，则对config文件进行相应的修改。

初始化目录后demo的目录结构如下：

```
.oebuild
	config
src
```

src：该目录用于存放跟编译相关的源码

.oebuild：目录用于存放全局性配置文件。在oebuild执行初始化后，可以看到一个config配置文件，该配置文件将在搭建编译基础环境时应用到。

#### oebuild update

基础环境更新指令。在执行初始化目录指令后、执行构建环节之前，必须先执行该命令。命令及各参数说明如下：

```
oebuild update [-t docker_tag] [-l list] [-i ignore] [-e enable]
```

-t: 指更新哪个tag的容器。

-l: 表示列出可选资源列表，目前只有docker这一项。

-i: 表示在更新时忽略哪一项，可选的有docker与meta，docker代表容器镜像，meta代表yocto-meta-openeuler仓。

-e: 表示在更新时使能哪一项，可选范围与解释同上。

执行更新操作如下命令：

```
oebuild update
```

oebuild执行构建有两个必要的前提，一是构建需要的容器，二是主构建仓（yocto-meta-openeuler），所以更新命令主要以这两部分展开。

另外，如果我们有自己的oebuild适配仓，可以在`config`配置文件中修改（该文件在`<workspace>/.oebuild`目录下）。如果已经先执行过更新操作，则再次执行`oebuild update`会将原有的`yocto-meta-openeuler`做备份，在工作空间根目录下创建yocto-bak备份目录，然后将备份后的`yocto-meta-openeuler`移动到该目录。更改基础仓在config中的如下字段修改：

```
basic_repo:
  yocto_meta_openeuler:
    path: yocto-meta-openeuler
    remote_url: https://gitee.com/openeuler/yocto-meta-openeuler.git
    branch: master
```

basic_repo与yocto-meta-openeuler是两个key键，不可更改。remote_url与branch可以更改成自己已经适配的`yocto-meta-openeuler`仓的参数。

注：如果我们不输入任何参数，即直接执行`oebuild update`，则默认更新容器镜像和基础仓。

#### oebuild generate

创建配置文件指令，该命令用于产生配置文件。命令及参数说明如下：

```
oebuild generate [-p platform] [-f features] [-t toolchain_dir] [-d build_directory] [-l list]
```

-p：cpu类型参数，全称platform，生成配置文件所需的一个参数，默认为aarch64-std。

-f：特性参数，全称feature，生成配置文件所需的一个参数，没有默认值。

-t：外部编译链参数，全称toolchain_dir，生成配置文件所需的一个参数，没有默认值，当用户不需要系统提供的交叉编译链而选择自己的交叉编译链时，可以选择该参数。

-d：初始化的编译目录，如果不设置该参数，则初始化的编译目录和-p参数保持一致。

-l: list参数，有两个可选范围，platform和feature，platform则会列出支持的platform列表，feature则会列出支持的feature列表。

oebuild在构建时依赖`compile.yaml`配置文件来完成构建操作。创建配置文件指令属于构建指令内容，该操作将会检查`yocto-meta-openeuler`是否适配了oebuild，检查是否适配的规则为“是否在`yocto-meta-openeuler`根目录创建了`.oebuild`隐藏目录”。  
参数`-p`会解析.oebuild/platform下相应的平台配置文件，`-f`会解析.oebuild/feature下相应的配置文件，该参数可以多值传入，例如：

```
oebuild generate -p aarch64-std -f systemd -f openeuler-qt
```

则生成的构建配置文件会涵盖systemd和openeuler-qt两者的特性。

最终会在编译目录下（在执行完`oebuild generate`后按提示给出的路径即为编译目录）生成构建配置文件`compile.yaml`,关于该配置文件的详细介绍请参考配置文件介绍中的`compile.yaml`。在下一步的构建流程会解析该配置文件，在此之前，用户可以根据自身特定场景环境来修改配置文件，因为按该`oebuild generate`指令生成的配置文件仅算作一个参考模板，目的是给用户一个最基本的模板参考用，减少用户学习的成本，使用户能够快速上手。

#### oebuild bitbake

构建指令，该指令会解析`compile.yaml`(通过`oebuild generate`指令生成)，然后完成构建环境的初始化工作。该命令参数如下：

-h：帮助命令，通过执行

```
oebuild bitbake -h
```

来获取帮助。

一般来说，启动后的容器挂在的目录映射关系如下：

```
<workspace>/src:/usr1/openeuler/src
<workspace>/build/:/usr1/openeuler/build
```

如果在`compile.yaml`中有`toolchain_dir`参数，即有用户自定义外部工具链，则会增加一个挂载目录，如下：

```
<toolchain_dir>：/usr1/openeuler/native_gcc
```

#### oebuild upgrade

在线升级指令，该指令会请求远程oebuild版本信息，通过和本地oebuild版本对比来判断是否进行升级。

由于oebuild二进制包存放在gitee仓库中，因此oebuild在升级时会先克隆最新的二进制仓到用户根目录，并以一个随机文件名命名，然后执行`sudo pip install <oebuild*.whl>`来完成升级。期间会要求用户输入root密码，在完成升级后会自动删除oebuild二进制包。

### 配置文件介绍

oebuild在生成后有多个配置文件，每个配置文件的作用域不同，下面将介绍各配置文件存放位置以及内容：

#### config

oebuild在外围环境的配置文件。该配置文件存放在oebuild项目根目录下的.oebuild目录中，结构如下：

```
docker:
  repo_url: swr.cn-north-4.myhuaweicloud.com/openeuler-embedded/openeuler-container
  tag_map:
    openEuler-22.09: '22.09'
    openEuler-22.03-lts-sp1: 22.03-lts-sp1
    master: latest
basic_repo:
  yocto_meta_openeuler:
    path: yocto-meta-openeuler
    remote_url: https://gitee.com/openeuler/yocto-meta-openeuler.git
    branch: master
```

**docker**: 表示构建容器相关信息，在该字段下面所列的容器镜像，在执行`oebuild update`后会下载相应的容器。

​	repo_url: 表示openEuler Embedded的docker远程仓地址。

​	tag_map: 表示每个openEuler Embedded版本对应的docker构建容器tag。

**basic_repo**:表示基础的repo仓。顾名思义，表示在构建之前是作为底座的角色存在的，在执行`oebuild update`时会解析config配置文件，然后下载相应的构建代码仓。

​	yocto-meta-openeuler: 目前oebuild唯一的基础仓。

- path： 该仓下载的路径名称。

- remote_url: 该仓的远程地址。

- branch: 该仓的分支。

#### .env

 编译目录配置文件结构如下：

```
container:
	remote: xxxxxxxxxxxx
	branch: xxxxxxxxxxxx
	short_id: xxxxxxxxxx
	volumns:
	- /xxxxxxxxxxx
	- /xxxxxxxxxxx
```
各参数含义如下：

container: 容器相关配置信息

​	remote: `yocto-meta-openeuler`远程url

​	branch: `yocto-meta-openeuler`分支信息

​	short_id: 容器ID

​	volumns: 容器挂载的目录映射

oebuild在执行构建过程中，会解析`.env`配置文件，通过对比环境中的其他参数确定是重新创建一个新的容器还是启用旧容器。比对的内容包括remote、branch和volumns，只有这三个参数与要构建的对应参数一致，才会继续拉起旧容器，否则就会创建一个新的容器。另外oebuild也会检查设置的short_id对用的容器是否存在，不存在也会创建一个新的容器。在创建新的容器后，新的配置信息会重新写入到`.env`中。

#### compile.yaml

构建配置文件，其结构如下：

```
platform: aarch64-std
machine: qemu-aarch64
toolchain_type: EXTERNAL_TOOLCHAIN_aarch64
sdk_dir:
toolchain_dir:
repos:
  yocto-poky:
    url: https://gitee.com/openeuler/yocto-poky.git
    path: yocto-poky
    refspec: openEuler-22.09

  yocto-meta-openembedded:
    url: https://gitee.com/openeuler/yocto-meta-openembedded.git
    path: yocto-meta-openembedded
    refspec: dev_hardknott

  yocto-meta-ros:
    url: https://gitee.com/openeuler/yocto-meta-ros.git
    path: yocto-meta-ros
    refspec: dev_hardknott
local_conf: |
- xxx
- xxx
layers: 
- xxx
- xxxx
```
各参数含义如下：

platform：cpu架构

machine：机器类型

toolchain_type: 编译链类型

sdk_dir: 保留字段

toolchain_dir：自定义外部编译链路径
> 如果在`oebuild generate`设置了该参数`-t`，则会在`compile.yaml`存在该字段。

repos: 在初始化构建环境时需要用到的仓

​	url: 仓的远程地址

​	path: 仓在本地的地址

​	refspec: 仓的版本分支

local_conf: local.conf替换内容，该值在oebuild执行完oe_init后将替换`build/conf/local.conf`中匹配到的内容。

layers: meta层，该值在oebuild执行完oe_init后将通过调用`bitbake-layers add-layer`来添加meta层。

### 开发者帮助

oebuild项目欢迎广大爱好开发者参与贡献oebuild的发展。为了使开发者更快更好地参与到oebuild的开发工作中来，我们专门写了如下指导：

#### oebuild目录介绍

打开oebuild仓可以看到，oebuild一级目录有如下内容：

```
docs
src
.gitignore
MANIFEST.in
README.md
setup.py
```

docs：文档目录，该目录用于存放关于oebuild的介绍性信息。

src：核心源码目录，存放oebuild的核心源码。关于参与开发oebuild的详细流程，后续将会详细介绍。

.gitignore：git提交忽略的文件，在该文件中设置的内容在git提交时自动忽略。

MANIFEST.in：该文件为pip在打包时包含额外文件的配置文件，在该文件中的内容将在执行python打包时按规则进行包含。

README.md：简要介绍性文件。

setup.py：python打包入口文件 ，最终要打包wheel包通过该文件来完成。

#### 如何使用setup.py进行调试或打包

在我们完成相关的开发性工作并进行调试时，将通过setup.py内的相关设置来完成该工作。

打开setup.py文件，可以看到如下内容：

```
# Copyright 2018 Open Source Foundries Limited.
# Copyright (c) 2020, Nordic Semiconductor ASA
#
# SPDX-License-Identifier: Apache-2.0

import os

import setuptools

SCRIPT_DIR = os.path.dirname(os.path.realpath(__file__))
os.chdir(SCRIPT_DIR)

with open('README.md', 'r') as f:
    long_description = f.read()

with open('src/oebuild/version.py', 'r') as f:
    __version__ = None
    exec(f.read())
    assert __version__ is not None

version = os.environ.get('OEBUILD_VERSION', __version__)

setuptools.setup(
    name='oebuild',
    version=version,
    author='alichinese',
    author_email='',
    description='',
    long_description=long_description,
    # http://docutils.sourceforge.net/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data
    long_description_content_type="text/x-rst",
    url='',
    packages=setuptools.find_packages(where='src'),
    package_dir={'': 'src'},
    include_package_data=True,
    classifiers=[
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: Apache Software License',
        'Operating System :: POSIX :: Linux',
    ],
    install_requires=[
        'setuptools',
        'packaging',
        'PyYaml',
        'docker',
        'GitPython',
        'colorama',
        'ruamel.yaml'
    ],
    python_requires='>=3.8',
    entry_points={'console_scripts': ('oebuild = oebuild.app.main:main',)},
)

```

可以看到引入的模块有`setuptools`，这个是打包的核心模块。关于其他的介绍我们暂且不管，因为对于开发者来说几乎没改动，这里我们着重介绍`install_requires`。该设置从字面意思理解就是依赖的必要安装，也就是oebuild运行要依赖的第三方库，如果后续oebuild开发过程中有一些其他库的依赖，则需要在这里添加。

在进入oebuild目录后，我们可以执行以下命令进入调试状态：

```
pip install -e .
```

> 注：以上命令的运行如果以普通用户运行，需要先确认是否已将本地执行路径添加到环境变量`PATH`中，如果以root用户运行则不需要考虑，可以直接运行oebuild相关指令。

这样在后续开发与调试过程中，我们可以随时改代码随时生效。

#### src源码介绍

正在完善中...