From e7e0c4aca885fe1bc52a6683fe336c6c473b19e1 Mon Sep 17 00:00:00 2001 From: Lyb9 <1576988680@qq.com> Date: Fri, 13 Aug 2021 14:55:27 +0800 Subject: [PATCH] update online component development guide --- README.md | 100 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 70 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 295f439..2172b33 100644 --- a/README.md +++ b/README.md @@ -19,23 +19,24 @@ . └── Huawei_LiteOS ├── components - │   ├── components.mk // 调用第一层子目录中的.mk文件，并导出所有组件对外开放的头文件 - │   ├── download.sh // 在线组件的下载脚本 + │   ├── components.mk // 调用第一层子目录中的.mk文件，并导出所有组件对外开放的头文件 + │   ├── download.sh // 在线组件的下载脚本 │   ├── Kconfig │   ├── Makefile - │   ├── online_components // 在线组件的下载信息 + │   ├── online_components // 在线组件的下载信息 │   └── utility - │   ├── curl // 组件目录 - │   │   ├── curl-7.54.1 // 组件源码 - │   │   ├── curl.mk // 组件对外头文件的管理文件 - │   │   ├── Kconfig // 组件配置文件 - │   │   ├── Makefile // 组件编译文件 - │   │   ├── origin.patch // 组件源码的补丁文件 - │   │   ├── patch.sha256 // 补丁文件的sha256校验码 - │   │   └── src.sha256 // 组件源码的sha256校验码 - │   ├── Kconfig // 调用第一层子目录中的Kconfig - │   ├── Makefile // 调用第一层子目录中的Makefile - │   └── utility.mk // 调用第一层子目录中的.mk文件，并导出其中的组件对外开放的头文件 + │   ├── curl // 组件目录 + │   │   ├── curl-7.54.1 // 组件源码（提交代码时需删除） + │   │   ├── curl-7.54.1.zip // 组件源码压缩包（提交代码时需删除） + │   │   ├── curl.mk // 组件对外头文件的管理文件 + │   │   ├── Kconfig // 组件配置文件 + │   │   ├── Makefile // 组件编译文件 + │   │   ├── origin.patch // 组件源码的补丁文件 + │   │   ├── patch.sha256 // 补丁文件的sha256校验码 + │   │   └── src.sha256 // 组件源码的sha256校验码 + │   ├── Kconfig // 调用第一层子目录中的Kconfig + │   ├── Makefile // 调用第一层子目录中的Makefile + │   └── utility.mk // 调用第一层子目录中的.mk文件，导出其中的组件对外开放的头文件 ├── demos │   └── utility │   ├── curl @@ -52,25 +53,44 @@ ├── bsp │   └── common │   └── demo_entry.c // 各个demo的调用入口 - └── targets.mk // 链接各组件及demo编译生成的库文件 + └── bsp.mk // 链接各组件及demo编译生成的库文件 ``` -**须知：** 新增组件或demo，都需要新建其自身的`Kconfig`、`Makefile`、`.mk`文件，本文档以新增组件为主题，新增demo的方法和新增组件类似，本文档不再赘述。 - +**须知：** +1. 新增组件或demo，都需要新建其自身的`Kconfig`、`Makefile`、`.mk`文件，本文档以新增组件为主题，新增demo的方法和新增组件类似，本文档不再赘述。 +2. curl-7.54.1、curl-7.54.1.zip 提交时需删除，无须提交到LiteOS仓库。 +3. origin.patch、patch.sha256、src.sha256 是开发过程中生成的文件，需提交到LiteOS_Components仓库。 ### online_components 在线组件的源码需要从网上下载，下载信息记录在`online_components`文件中。该文件具有特定格式，保存了各在线组件的相关信息（或称参数），如下所示，每个组件各有四个参数，各参数之间使用`&#&`分开。 -`curl-7.54.1 &#& components/utility/curl &#& LOSCFG_COMPONENTS_CURL=y &#& https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.zip` +``` +curl-7.54.1 &#& components/utility/curl &#& LOSCFG_COMPONENTS_CURL=y &#& https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.zip +``` + * 参数一：组件源码名（一般命名为：`源码名-版本号`）。 + +**须知：** 该名字即相当于对源码的重命名，和直接在网页上点击下载得到的名字不一定相同。如，此处直接访问`https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.zip`下载得到的文件名为`curl-curl-7_54_1.zip`，解压该文件得到的文件为`curl-curl-7_54_1`。但download.sh在执行下载时，会根据参数一及参数四将下载的文件命名为`curl-7.54.1.zip`（命名方式：`参数一 + 参数四中的下载类型`），解压该文件得到的文件为`curl-7.54.1`，即`参数一`；因此开发人员在开发过程中，对源码进行的一切操作，必须以`参数一`写的名字为准，如果下载的源码名与你参数一写的不一致，请根据上述说明，重命名之后再进行后续开发。 + * 参数二：组件所在路径（将组件源码下载到该目录下）。 + * 参数三：组件使能的标志（用于判断是否下载组件源码，该标志就是组件`Kconfig`文件中的配置项）。 -* 参数四：组件源码的下载地址或获取组件源码的命令（因后面涉及源码校验，推荐优先下载源码压缩包，校验起来更加方便快捷）。 + +* 参数四：组件源码的下载地址或获取组件源码的命令（因后面涉及源码校验，推荐优先下载源码压缩包，校验时更加方便快捷）。 **须知：** 在线组件目前支持如下几种下载方式： -* 下载压缩包：目前仅支持`.zip`/`.tar.gz`类型的压缩包，如：https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.zip。 -* 使用git克隆：如：`git clone -b curl-7.54.1 https://github.com/curl/curl.git`。 -* 如无法使用以上方式获取源码，可自行编写shell脚本完成源码下载，并返回下载结果（成功/失败）。参数四填写调用该脚本的方法即可。 +* 下载压缩包：目前仅支持`.zip`、`.tar.gz`类型的压缩包，如： +```txt + https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.zip + https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.tar.gz +``` + +* 使用git克隆，如： +```txt +git clone -b curl-7.54.1 https://github.com/curl/curl.git` +``` + +* 如使用上述方式无法获取源码，可自行编写shell脚本完成源码下载，并返回下载结果（成功/失败）。参数四填写调用该脚本的方法即可。 ### download.sh @@ -94,7 +114,7 @@ 文件内容为组件源码的`sha256`校验码。为确保组件的正常使用，需要保证从网上下载的源码与开发组件时使用的源码是同一份，`LiteOS`通过对下载的源码进行`sha256`校验来保证是同一份源码。所以，开发组件时需要计算生成源文件的`sha256`校验码，并将其复制到`src.sha256`文件。`curl`组件的`src.sha256`的文件内容如下： -``` +```txt 7eec2c7f863c17d8586e94255cd0c2934822f1ae3cb40283a892b46e44f93bdf curl-7.54.1.zip ``` @@ -119,10 +139,28 @@ ### origin.patch -源码的补丁文件，该文件采用统一命名`origin.patch`，不可修改。在`Huawei LiteOS`上开发组件，建议尽量避免对开源源码的直接修改，如无法避免（例如：不修改源码无法编译成功，或源码无法直接运行在`Huawei LiteOS`上，则需要适配），则应该将修改内容生成为补丁文件`origin.patch`。在后续使用中，采取打补丁的方式修改源码。 +源码的补丁文件，该文件采用统一命名`origin.patch`，不可修改。在`Huawei LiteOS`上开发组件，建议尽量避免对开源源码的直接修改，如无法避免（例如：不修改源码无法编译成功，或源码无法直接运行在`Huawei LiteOS`上，则需要适配），则应该将修改内容生成为补丁文件`origin.patch`。在后续使用中，采取打补丁的方式修改源码。打补丁时采用`patch -p1`的方式，生成补丁文件时请注意。 + +`origin.patch`补丁文件的生成可参考如下方式： -补丁文件需上传到`LiteOS_Components`仓库中，使用时由`download.sh`从该仓库中下载获得。`download.sh`脚本会采用`patch -p1`的方式打补丁，所以应该将修改后的源码文件放在另一个源码目录中，对原源码目录和修改后的源码目录制作补丁。 +1. 新建a、b目录，将没有被修改的组件源码拷贝到a目录下，将修改过后的组件源码拷贝到b目录下，目录结构如下： +``` +. +└── curl // 组件目录 + ├── a + │   └── curl-7.54.1 // 没有被修改的组件源码 + ├── b + │   └── curl-7.54.1 // 修改过后的组件源码 + ├── curl-7.54.1 + ├── curl-7.54.1.zip // 组件源码压缩包 + └── origin.patch // 源码补丁文件 +``` +2. 执行如下命令 + +```shell +diff -Nur a/curl-7.54.1 b/curl-7.54.1 > orinig.patch +``` **注意：** 请确保`origin.patch`文件在本地校验前已经是`unix`格式，因为该文件上传到`LiteOS_Components`仓库时会自动转换为`unix`格式，如果本地校验时不是`unix`格式，会导致该在线组件执行`download.sh`失败。 ### patch.sha256 @@ -185,7 +223,9 @@ CURL_VERSION=curl-7.54.1 # 组件版本 COMPONENTS_CURL_INCLUDE := \ -I $(LITEOSTOPDIR)/components/utility/curl/$(CURL_VERSION)/include \ -I $(LITEOSTOPDIR)/components/utility/curl/$(CURL_VERSION)/src +``` +```makefile ##################### utility.mk的内容如下 ####################### ifeq ($(LOSCFG_COMPONENTS_CURL), y) # 只有组件已使能，才执行以下操作 include $(LITEOSTOPDIR)/components/utility/curl/curl.mk # 调用子目录下其他组件的.mk文件 @@ -241,7 +281,7 @@ include $(MODULE) ``` 下面对几个重要参数进行说明（部分参数不是每个`Makefile`都必须的，请根据实际需求选择写/不写）： * include $(LITEOSTOPDIR)/config.mk：引入`Huawei LiteOS`系统的宏定义，所有`Makefile`都需要引用该文件。 -* MODULE_NAME：模块名，编译生成的静态链接库的名称就是模块名，例如这里模块名为`curl`，那么生成的静态链接库就是libcurl.a。在`targets.mk`文件中需要增加新组件的库文件的链接，请参考`targets.mk`文件中已有组件的链接进行修改。 +* MODULE_NAME：模块名，编译生成的静态链接库的名称就是模块名，例如这里模块名为`curl`，那么生成的静态链接库就是libcurl.a。在`bsp.mk`文件中需要增加新组件的库文件的链接，请参考`bsp.mk`文件中已有组件的链接进行修改。 **注意：** 如果组件名本身是以`lib`开头的，模块名中不需要体现`lib`，如`libpng`应写为`MODULE_NAME := png`，而不应写为`MODULE_NAME := libpng`，避免生成的静态库文件名为`liblibpng.a`。 @@ -276,9 +316,9 @@ include $(MODULE) 原则上每个组件都应提供一个参考`demo`，demo必须自研，禁止直接拷贝网络上的代码。每个`demo`只允许提供一个对外接口，统一在`demo_entry.c`文件中进行调用。 -### targets.mk +### bsp.mk -`Huawei LiteOS`采用组件化编译框架，每个组件或`demo`编译完成后会在`out`目录下生成相应的静态库文件。因`Windows`平台无法自动链接静态库文件，因此需要在`targets.mk`文件中进行手动链接。如新增链接`curl`组件和`demo`的静态库文件： +`Huawei LiteOS`采用组件化编译框架，每个组件或`demo`编译完成后会在`out`目录下生成相应的静态库文件。因`Windows`平台无法自动链接静态库文件，因此需要在`bsp.mk`文件中进行手动链接。如新增链接`curl`组件和`demo`的静态库文件： ```makefile ifneq ($(OS), Linux) ifeq ($(LOSCFG_COMPONENTS_CURL), y) @@ -308,7 +348,7 @@ VOID DemoEntry(VOID) #endif } ``` -**注意：** ，必须以`#include`头文件的方式调用函数，禁止使用`extern`的方式。 +**注意：** 必须以`#include`头文件的方式调用函数，禁止使用`extern`的方式。 ## 在线组件下载流程 @@ -317,7 +357,7 @@ VOID DemoEntry(VOID) 下载LiteOS代码仓。在`Huawei LiteOS`源码根目录下执行`make menuconfig`命令后会自动调用`download.sh`脚本，该脚本读取`online_components`文件的内容以获取组件下载信息，判断组件是否被使能，如果组件已经使能，继续判断组件源码是否存在，如不存在则下载组件源码、`origin.patch`、`src.sha256`和`patch.sha256`。通过`.sha256`文件判断下载的组件源码及`origin.patch`文件是否正确，正确则打入patch，完成在线组件的下载流程。 -**注意：** 如果想要重新下载组件源码和补丁，需要在本地删除已有源码和补丁。同时，在脚本运行过程中，如果被外部信号强制中断，如`ctrl z`、`ctrl c`等，会导致下载流程失败，请及时清理此次下载中残留文件。 +**注意：** 如果想要重新下载组件源码和补丁，需要在本地删除已有源码和补丁文件。同时，在脚本运行过程中，如果被外部信号强制中断，如`ctrl z`、`ctrl c`等，可能会导致下载流程失败，请及时清理此次下载中残留文件。 ### Windows平台 -- Gitee