276 Star 309 Fork 291

Huawei LiteOS / LiteOS_Components

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
BSD-3-Clause

组件开发指南

组件定义

组件是Huawei LiteOS系统的组成部分,属于Huawei LiteOS应用。从系统层面看,除内核、构建脚本、辅助工具、系统函数库外,其余组成Huawei LiteOS系统功能的软件包均可称为组件。本文档将详细介绍组件的构成、规范及组件开发流程,帮助组件开发人员进行组件开发。

Huawei LiteOS的组件分为在线组件和离线组件,在线组件的组件源码不在Huawei LiteOS代码仓中,使用时需要从网上下载,而离线组件的源码则存放在Huawei LiteOS代码仓中。离线组件一般都是基础组件,如网络、文件系统等。

组件构成

下面以在线组件curl为例,对Huawei LiteOS的组件构成及组件管理进行详细说明。

目录结构

新增一个组件涉及新建及修改的文件或目录如下所示。其中components下的curl和demos下的curl及它们包含的文件为新增目录和文件,其余文件为各组件或demos的共有文件,新增组件时一般也需要修改。

.
└── Huawei_LiteOS
    ├── components
    │   ├── components.mk            // 调用第一层子目录中的.mk文件,并导出所有组件对外开放的头文件
    │   ├── download.sh              // 在线组件的下载脚本
    │   ├── Kconfig
    │   ├── Makefile
    │   ├── online_components        // 在线组件的下载信息
    │   └── utility
    │       ├── 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
    │       │   ├── curl_demo.c
    │       │   ├── curl_demo.h
    │       │   ├── curl.mk
    │       │   ├── Kconfig
    │       │   ├── Makefile
    │       │   └── README_CN.md
    │       ├── Kconfig
    │       ├── Makefile
    │       └── utility.mk
    └── targets
        ├── bsp
        │   └── common
        │       └── demo_entry.c  // 各个demo的调用入口
        └── bsp.mk                // 链接各组件及demo编译生成的库文件

须知:

  1. 新增组件或demo,都需要新建其自身的KconfigMakefile.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
  • 参数一:组件源码名(一般命名为:源码名-版本号)。

须知: 该名字即相当于对源码的重命名,和直接在网页上点击下载得到的名字不一定相同。如,此处直接访问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
  https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.tar.gz
  • 使用git克隆,如:
git clone -b curl-7.54.1 https://github.com/curl/curl.git`
  • 如使用上述方式无法获取源码,可自行编写shell脚本完成源码下载,并返回下载结果(成功/失败)。参数四填写调用该脚本的方法即可。

download.sh

下载在线组件源码和补丁文件,进行sha256sum校验,校验成功后,将补丁文件打入源码。

components/utility/curl

curl目录是curl组件的源码及其相关文件所在目录。新增组件时,请根据组件功能在components目录相应位置下新建组件目录(分为语言类组件language、媒体类组件media、工具类组件utility、安全组件security等。而curl属于工具类组件,故其位于utility目录下)。

命名规范:一般和组件源码同名(不可简写,如libpng不可写为png)或参考业界通用命名。

components/utility/curl/curl-7.54.1

组件源码,目录名需要和online_components文件中的参数一保持一致。对于在线组件由download.sh从网上下载获得,所以不需要将组件源码上传到Huawei LiteOS代码仓,只有离线组件的源码需要上传。

src.sha256

文件内容为组件源码的sha256校验码。为确保组件的正常使用,需要保证从网上下载的源码与开发组件时使用的源码是同一份,LiteOS通过对下载的源码进行sha256校验来保证是同一份源码。所以,开发组件时需要计算生成源文件的sha256校验码,并将其复制到src.sha256文件。curl组件的src.sha256的文件内容如下:

7eec2c7f863c17d8586e94255cd0c2934822f1ae3cb40283a892b46e44f93bdf  curl-7.54.1.zip

生成sha256校验码的方法可参考如下命令:

  • 如果下载的源码包是压缩包:

    sha256sum 参数一.zip > src.sha256  # sha256sum curl-7.54.1.zip > src.sha256
  • 如果源码包不是压缩包:

    find 参数一 -type f -print0 | xargs -0 sha256sum > src.sha256 # find curl-7.54.1 -type f -print0 | xargs -0 sha256sum > src.sha256

须知: 如果需要在Windows中执行以上命令,可以安装Git工具,使用Git自带的终端即可执行。注意需提前设置Git为禁止换行符转换,参考命令git config --global core.autocrlf input

注意:

  • 校验码文件采用统一命名src.sha256,文件名不可修改。
  • 开发组件时,请使用online_components文件中的参数四的方式下载源码文件。

origin.patch

源码的补丁文件,该文件采用统一命名origin.patch,不可修改。在Huawei LiteOS上开发组件,建议尽量避免对开源源码的直接修改,如无法避免(例如:不修改源码无法编译成功,或源码无法直接运行在Huawei LiteOS上,则需要适配),则应该将修改内容生成为补丁文件origin.patch。在后续使用中,采取打补丁的方式修改源码。打补丁时采用patch -p1的方式,生成补丁文件时请注意。

origin.patch补丁文件的生成可参考如下方式:

  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        // 源码补丁文件
  1. 执行如下命令
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

源码补丁文件origin.patch的校验码文件,该文件采用统一命名patch.sha256,不可修改。其作用是保证下载的补丁文件正确,文件格式与src.patch的要求一致。

Kconfig

components/utility/curl/Kconfig

组件配置文件,通过该文件将组件纳入到LiteOS的菜单项界面中管理,编写时可参考已有组件的Kconfig文件进行修改,Kconfig的基本语法可自行搜索或参考官方文档《kconfig-language.txt》

components/utility/curl/Kconfig的文件内容及说明如下:

config LOSCFG_COMPONENTS_CURL           # 配置项:一般固定为"LOSCFG_COMPONENTS_目录名"
    bool "Enable Curl"                  # bool: 配置项类型; Enable Curl: 配置项提示
    select LOSCFG_COMPONENTS_NET_LWIP   # 依赖关系:如依赖其他组件,请指明依赖关系
    select LOSCFG_COMPONENTS_FS_FATFS
    default n                           # 组件默认是否使能:一般默认不使能
    help
      Answer y to enable curl.          # 帮助信息:该配置项的说明
  • 如果组件下还包含其他多个组件,可灵活命名配置项,如LOSCFG_COMPONENTS_目录名_XXX,但不宜过程。
  • 配置项提示是menuconfig菜单项中的显示信息,可理解为配置项的别名,各单词首字母需大写,其余小写(专有名词除外)。
  • 帮助信息的首字母大写,其余小写(专有名词除外),同时要有结束符.
  • 缩进请使用空格,不得使用tab健。

上级目录中的Kconfig

新增组件时,除了需要在本级组件目录下新建本组件的Kconfig文件,还需要修改上级目录下的Kconfig文件。该文件用于调用下一级子目录中的Kconfig,可参考该文件中的其他组件进行修改。components/utility/Kconfig文件内容如下,其包含了utility目录下所有组件的Kconfig文件。

menu "Utility"                                      # 菜单项

source "components/utility/bidireference/Kconfig"
source "components/utility/curl/Kconfig"            # 本次新增的内容
source "components/utility/freetype/Kconfig"
source "components/utility/iconv/Kconfig"
source "components/utility/iniparser/Kconfig"
source "components/utility/json-c/Kconfig"
source "components/utility/libxml2/Kconfig"

endmenu

.mk文件

.mk用于导出组件的对外头文件,供其他组件或模块调用本组件中的API。为避免头文件关系混乱,Huawei LiteOS使用.mk文件管理和限制组件对外头文件,并通过各目录下的.mk文件将组件的对外接口层层导出。最终所有组件的头文件通过components.mk对外提供。

新增组件时一般涉及的.mk文件为:

  • 在新增组件目录下新建本组件的.mk文件,可参考已有组件的.mk文件。
  • 修改上级目录下的.mk文件,可参考该文件中的其他组件进行修改。

curl.mkutility.mk

####################### curl.mk的内容如下 ########################
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
##################### utility.mk的内容如下 #######################
ifeq ($(LOSCFG_COMPONENTS_CURL), y)                       # 只有组件已使能,才执行以下操作
include $(LITEOSTOPDIR)/components/utility/curl/curl.mk   # 调用子目录下其他组件的.mk文件
COMPONENTS_UTILITY_INCLUDE += $(COMPONENTS_CURL_INCLUDE)  # 导出该组件对外开放的头文件
endif

文件规范及说明:

  • CURL_VERSION:组件版本宏定义,一般命名为源码名_VERSION
  • COMPONENTS_CURL_INCLUDE:头文件宏定义,一般命名为COMPONENTS_源码名_INCLUDE
  • 一般在组件的上级目录.mk文件中,调用具体组件的.mk文件时必须有条件限制,只有组件被使能的情况下才允许调用组件的.mk文件。
  • 如需缩进,统一缩进四个空格,注意不得使用tab健。

Makefile

components/utility/curl/Makefile

组件化编译文件,通过该文件将组件加入到Huawei LiteOS的组件化编译框架中。新增组件时需要在组件目录下新建该文件以实现组件编译,可参考已有组件的Makefile文件。components/utility/curl/Makefile文件内容如下:

include $(LITEOSTOPDIR)/config.mk
include $(LITEOSTOPDIR)/components/net/lwip/lwip.mk
include $(LITEOSTOPDIR)/components/utility/curl/curl.mk

MODULE_NAME := $(notdir $(CURDIR))      # $(notdir $(CURDIR)) 等价于 curl

LOCAL_SRCS_y :=
LOCAL_DIRS_y :=

LOCAL_DIRS_y += $(CURL_VERSION)/lib
LOCAL_DIRS_y += $(CURL_VERSION)/lib/vauth
LOCAL_DIRS_y += $(CURL_VERSION)/lib/vtls
LOCAL_DIRS_y += $(CURL_VERSION)/src

LOCAL_INCLUDE := $(LWIP_INCLUDE)
LOCAL_INCLUDE += \
    -I $(LITEOSTOPDIR)/components/utility/curl/$(CURL_VERSION)/lib \
    -I $(LITEOSTOPDIR)/components/utility/curl/$(CURL_VERSION)/include \
    -I $(LITEOSTOPDIR)/components/utility/curl/$(CURL_VERSION)/src

LOCAL_SRCS_y += $(foreach dir, $(LOCAL_DIRS_y), $(wildcard $(dir)/*.c))
LOCAL_SRCS   = $(LOCAL_SRCS_y)

LOCAL_EXT_FLAG := -Wno-error -Wno-implicit-function-declaration -Wno-unused-variable

CURL_DEFS = \
    -D HAVE_CONFIG_H \
    -D BUILDING_LIBCURL

LOCAL_FLAGS := $(LOCAL_INCLUDE) $(CURL_DEFS) $(LOCAL_EXT_FLAG)

include $(MODULE)

下面对几个重要参数进行说明(部分参数不是每个Makefile都必须的,请根据实际需求选择写/不写):

  • include $(LITEOSTOPDIR)/config.mk:引入Huawei LiteOS系统的宏定义,所有Makefile都需要引用该文件。

  • MODULE_NAME:模块名,编译生成的静态链接库的名称就是模块名,例如这里模块名为curl,那么生成的静态链接库就是libcurl.a。在bsp.mk文件中需要增加新组件的库文件的链接,请参考bsp.mk文件中已有组件的链接进行修改。

    注意: 如果组件名本身是以lib开头的,模块名中不需要体现lib,如libpng应写为MODULE_NAME := png,而不应写为MODULE_NAME := libpng,避免生成的静态库文件名为liblibpng.a

  • LOCAL_INCLUDE:编译需要用到的头文件集合。

  • LOCAL_SRCS:本模块需要参与编译的所有除头文件以外的源文件。

  • LOCAL_EXT_FLAG:本模块的编译参数集合(非必须)。

  • CURL_DEFS:本模块编译需要用到的宏定义集合(非必须)。

  • 如需缩进,统一缩进四个空格,注意不得使用tab健。

上级目录中的Makefile

该文件用于调用下一级子目录中的Makefile,components/utility/Makefile文件内容如下:

include $(LITEOSTOPDIR)/config.mk

MODULE_$(LOSCFG_COMPONENTS_BIDIREFERENCE) += bidireference
MODULE_$(LOSCFG_COMPONENTS_CURL) += curl                    # 本次新增的内容
MODULE_$(LOSCFG_COMPONENTS_FREETYPE) += freetype
MODULE_$(LOSCFG_COMPONENTS_ICONV) += iconv
MODULE_$(LOSCFG_COMPONENTS_INIPARSER) += iniparser
MODULE_$(LOSCFG_COMPONENTS_JSON_C) += json-c
MODULE_$(LOSCFG_COMPONENTS_LIBXML2) += libxml2

include $(MODULE)

LOSCFG_COMPONENTS_CURL是组件Kconfig文件中的配置项,MODULE_$(LOSCFG_COMPONENTS_CURL)表示只有使能了组件后,才编译curl组件。

组件demo

原则上每个组件都应提供一个参考demo,demo必须自研,禁止直接拷贝网络上的代码。每个demo只允许提供一个对外接口,统一在demo_entry.c文件中进行调用。

bsp.mk

Huawei LiteOS采用组件化编译框架,每个组件或demo编译完成后会在out目录下生成相应的静态库文件。因Windows平台无法自动链接静态库文件,因此需要在bsp.mk文件中进行手动链接。如新增链接curl组件和demo的静态库文件:

ifneq ($(OS), Linux)
    ifeq ($(LOSCFG_COMPONENTS_CURL), y)
        LITEOS_BASELIB += -lcurl        # curl是组件的模块名
    endif

    ifeq ($(LOSCFG_DEMOS_CURL), y)
        LITEOS_BASELIB += -lcurl_demo   # curl_demo是组件demo的模块名
    endif
endif

demo_entry.c

所有demo的入口,demo完成后,统一在该文件的DemoEntry函数中调用。

#ifdef LOSCFG_DEMOS_CURL
#include "curl_demo.h"
#endif

VOID DemoEntry(VOID)
{
#ifdef LOSCFG_DEMOS_CURL
    CurlDemoTask();
#endif
}

注意: 必须以#include头文件的方式调用函数,禁止使用extern的方式。

在线组件下载流程

Linux平台

下载LiteOS代码仓。在Huawei LiteOS源码根目录下执行make menuconfig命令后会自动调用download.sh脚本,该脚本读取online_components文件的内容以获取组件下载信息,判断组件是否被使能,如果组件已经使能,继续判断组件源码是否存在,如不存在则下载组件源码、origin.patchsrc.sha256patch.sha256。通过.sha256文件判断下载的组件源码及origin.patch文件是否正确,正确则打入patch,完成在线组件的下载流程。

注意: 如果想要重新下载组件源码和补丁,需要在本地删除已有源码和补丁文件。同时,在脚本运行过程中,如果被外部信号强制中断,如ctrl zctrl c等,可能会导致下载流程失败,请及时清理此次下载中残留文件。

Windows平台

HUAWEI LiteOS Studio开发工具中,完成工程配置——>组件配置后,会自动调用download.sh文件,其余逻辑和Linux平台一致。

测试组件

完成组件开发的全部工作后,需要对组件进行测试,确保在线组件下载流程执行通过。

提交代码

组件测试通过后,即可将代码提交到Huawei LiteOS的各代码仓,代码提交的要求如下:

  1. 在线组件不需要提交组件源码。
  2. origin.patchsrc.sha256patch.sha256提交到LiteOS_Components仓库下的对应目录(目录结构需与开发时的目录结构保持一致,例如curl的这些文件,应置于该仓库的components/utility/curl目录下)。对于离线组件,不需要src.sha256文件。
  3. 其余文件提交到LiteOS仓库。

须知: 代码提交流程请参考LiteOS 代码&文档贡献指南

BSD 3-Clause License Copyright (c) 2021, hy All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

简介

Huawei LiteOS组件仓库,主要存放组件的补丁及相关的sha256校验文件。 展开 收起
BSD-3-Clause
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
1
https://gitee.com/LiteOS/LiteOS_Components.git
git@gitee.com:LiteOS/LiteOS_Components.git
LiteOS
LiteOS_Components
LiteOS_Components
master

搜索帮助

14c37bed 8189591 565d56ea 8189591