一分钟带你了解Huawei LiteOS之组件开发指南

举报
Lionlace 发表于 2021/09/03 15:10:01 2021/09/03
【摘要】 今天为大家带来开发者效率提升利器:组件 本文将基于Huawei LiteOS系统,从组件定义开始带你走进组件开发指南。


在开发工作过程中,面对庞大的代码量,你是否因担心出现牵一发而动全身的情况而不知从何下手?

今天为大家带来开发者效率提升利器:组件

本文将基于Huawei LiteOS系统,从组件定义开始带你走进组件开发指南。


组件定义

组件是Huawei LiteOS系统的组成部分,属于Huawei LiteOS应用。从系统层面看,除内核、构建脚本、辅助工具、系统函数库外,其余组成Huawei LiteOS系统功能的软件包均可称为组件。本文档将详细介绍组件的构成、规范及组件开发流程,帮助组件开发人员进行组件开发。Huawei LiteOS的组件分为在线组件和离线组件。在线组件的组件源码不在Huawei LiteOS代码仓中,使用时需要从网上下载;而离线组件的源码则存放在Huawei LiteOS代码仓中。离线组件一般都是基础组件,如网络、文件系统等。


组件构成

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

目录结构

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

须知:

新增组件或demo,都需要新建其自身的KconfigMakefile、.mk文件,本文档以新增组件为主题,新增demo的方法和新增组件类似,本文档不再赘述。

curl-7.54.1、curl-7.54.1.zip 提交时需删除,无须提交到LiteOS仓库。

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)或参考业界通用命名。


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文件中的参数四的方式下载源码文件。


src.sha256

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

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

新建a、b目录,将没有被修改的组件源码拷贝到a目录下,将修改过后的组件源码拷贝到b目录下,目录结构如下:

执行如下命令

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.mk与utility.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.patch、src.sha256和patch.sha256,通过.sha256文件判断下载的组件源码及origin.patch文件是否正确。正确则打入patch,完成在线组件的下载流程。

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

Windows平台

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


测试组件

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


提交代码

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

在线组件不需要提交组件源码。

origin.patch、src.sha256和patch.sha256提交到LiteOS_Components仓库下的对应目录(目录结构需与开发时的目录结构保持一致。例如curl的这些文件,应置于该仓库的components/utility/curl目录下)。对于离线组件,不需要src.sha256文件。

其余文件提交到LiteOS仓库。


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

https://gitee.com/LiteOS/LiteOS/blob/master/doc/LiteOS_Contribute_Guide.md



结语

未来我们还会持续新增更多组件、开发板、架构、特性等。

感谢您的阅读,有任何问题、建议,都可以留言给我们,让我们一起进步:

https://gitee.com/LiteOS/LiteOS/issues

为了更容易找到“LiteOS”代码仓,建议访问https://gitee.com/LiteOS/LiteOS,关注“ Watch”、点赞“Star”、并“Fork”到自己账号下,如下图。

-end-

【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。