Компоненты разработки Huawei LiteOS

Компоненты — это составные части системы Huawei LiteOS, которые относятся к её приложениям. С точки зрения системного уровня, компоненты — это все пакеты программного обеспечения, кроме ядра, скриптов сборки, вспомогательных инструментов и системной библиотеки функций. В этом документе подробно описаны структура компонентов, их стандарты и процесс разработки, чтобы помочь разработчикам компонентов в их работе.

В системе Huawei LiteOS компоненты делятся на онлайн-компоненты и офлайн-компоненты. Исходный код онлайн-компонентов не хранится в репозитории кода Huawei LiteOS. Его необходимо загрузить из сети при использовании. Исходные коды офлайн-компонентов хранятся в репозитории кода Huawei LiteOS. Базовые компоненты, такие как сетевые и файловые системы, обычно являются офлайн-компонентами.

Далее на примере онлайн-компонента curl для Huawei LiteOS подробно описываются структура компонентов и управление ими.

Каталог и структура файлов

Создание нового компонента включает создание или изменение файлов и каталогов. Каталог components содержит файл Kconfig, Makefile и каталог online_components. Онлайн-компоненты хранят информацию о загрузке. Каталог utility содержит компонент curl и демонстрационные файлы curl. Файлы и каталоги, содержащиеся в каталогах components и utility, являются новыми каталогами и файлами. Остальные файлы являются общими для всех компонентов или демонстрационных версий, и они также должны быть изменены при создании нового компонента.

.
└── Huawei_LiteOS
    ├── components
    │   ├── components.mk            // Вызов первого слоя подкаталога .mk файла и экспорт всех общедоступных заголовочных файлов компонентов
    │   ├── download.sh              // Скрипт загрузки онлайн-компонентов
    │   ├── Kconfig
    │   ├── Makefile
    │   └── online_components        // Информация о загрузке онлайн-компонентов
    │       ├── curl                 // Онлайн-компонент curl
    │       │   ├── curl-7.54.1      // Исходный код компонента (удалить при отправке кода)
    │       │   ├── curl-7.54.1.zip  // Zip-архив исходного кода компонента (удалить при отправке кода)
    │       │   ├── curl.mk          // Файл управления общедоступными заголовочными файлами компонентов
    │       │   ├── Kconfig          // Конфигурационный файл компонента
    │       │   ├── Makefile         // Компиляционный файл компонента
    │       │   ├── origin.patch     // Исправления исходного кода
    │       │   ├── patch.sha256     // Контрольная сумма SHA-256 файла исправлений
    │       │   └── src.sha256       // Контрольная сумма SHA-256 исходного кода
    │       └── 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  // Вызовы входа для каждой демонстрации
        └── bsp.mk                // Связывание каждого компонента и демонстрационной версии с библиотекой скомпилированных файлов

Следует отметить:

1. При создании новых компонентов или демонстраций необходимо создать собственные файлы Kconfig, Makefile и .mk. Этот документ фокусируется на создании компонентов, а создание демонстраций аналогично созданию компонентов. Этот документ не будет повторяться.
2. Файлы curl-7.54.1 и curl-7.54.1.zip следует удалить перед отправкой.
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, то есть именем, указанным в первом параметре. Поэтому разработчики должны использовать имя, указанное в первом параметре, при разработке. Если имя скачанного файла отличается от указанного в первом параметре, рекомендуется переименовать файл в соответствии со спецификациями, прежде чем продолжить разработку.

Второй параметр — путь к компоненту (исходный код загружается в этот каталог).

Третий параметр — флаг включения компонента (используется для определения, следует ли загружать исходный код; этот флаг является конфигурационным элементом в файле 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`

• Если вышеуказанные методы не работают, можно написать собственный сценарий оболочки для загрузки исходного кода и вернуть результат загрузки (успех/неудача). Можно указать метод вызова сценария оболочки в четвёртом параметре.

download.sh

Скачивает исходный код и исправления для онлайн-компонентов и выполняет проверку SHA-256. После успешной проверки исправления добавляются в исходный код.

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

Файл содержит контрольную сумму SHA-256 исходного кода компонента. Чтобы гарантировать нормальное использование компонента, необходимо убедиться, что исходный код, загруженный из сети, совпадает с исходным кодом, используемым при разработке компонента. LiteOS проверяет загруженный исходный код с помощью контрольной суммы SHA-256, чтобы убедиться в его подлинности. Поэтому при разработке компонентов необходимо вычислить контрольную сумму SHA-256 исходных файлов и скопировать её в файл src.sha256. Содержимое файла src.sha256 компонента curl выглядит следующим образом: 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

Примечание:

• Файл с контрольной суммой называется src.sha256, имя файла нельзя изменять.
• При разработке компонентов рекомендуется использовать параметры из online_components для загрузки исходного кода.

origin.patch

Файл с исправлениями исходного кода, который называется origin.patch и не может быть изменён. При разработке на Huawei LiteOS рекомендуется избегать прямого изменения открытого исходного кода. В случае необходимости внесения изменений следует создать файл origin.patch.

Создание файла 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        // Файл с исправлениями

2. Выполните следующую команду:

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-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. Все слова начинаются с заглавной буквы, остальные — со строчной (кроме собственных имён).
• В помощи используется заглавная буква в начале каждого слова, кроме собственных имён, и ставится точка в конце.
• Отступ делается пробелами, табуляция не используется.

Kconfig в родительских каталогах

При добавлении нового компонента необходимо создать файл Kconfig для этого компонента в его собственном каталоге, а также внести изменения в файл Kconfig родительского каталога. Этот файл используется для вызова файлов Kconfig дочерних каталогов. Содержимое файла components/utility/Kconfig включает все файлы Kconfig компонентов в каталоге utility.

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 используются для экспорта внешних заголовков компонентов, которые могут использоваться другими компонентами или модулями. Чтобы избежать путаницы в заголовках, 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: макрос, определяющий версию компонента, обычно называемый source_code_name_VERSION.
• COMPONENTS_CURL_INCLUDE: макрос для определения заголовков, обычно именуемый COMPONENTS_source_code_name_INCLUDE. Обычно в каталоге верхнего уровня компонента .mk файл, при вызове конкретного файла .mk компонента должны быть условия ограничения, только если компонент включён, можно вызывать файл .mk компонента.

Если требуется отступ, используйте четыре пробела, обратите внимание, что табуляция не должна использоваться.

Makefile

components/utility/curl/Makefile

Файл компиляции компонентов, используется для добавления компонента в структуру компиляции компонентов Huawei LiteOS. При добавлении нового компонента необходимо создать этот файл в каталоге компонента, чтобы реализовать компиляцию компонента. Содержимое файла 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 следует записать как png, а не как libpng, чтобы избежать создания имени статической библиотеки liblibpng.a.

• LOCAL_INCLUDE: набор заголовков, необходимых для компиляции.
• LOCAL_SRCS: все исходные файлы, кроме файлов заголовков, которые должны участвовать в компиляции этого модуля.
• LOCAL_EXT_FLAG: набор параметров компиляции для этого модуля (не обязательно).
• CURL_DEFS: набор макроопределений, необходимых для компиляции этого модуля (необязательно).
• Если требуется отступ, используйте четыре пробела, обратите внимание, что табуляция не должна использоваться.

Файл Makefile в родительском каталоге

Этот файл используется для вызова файла Makefile следующего уровня подкаталога. Содержимое файла 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) указывает, что компонент скомпилирован только после включения компонента.

Компонентный демо

В принципе, каждый компонент должен предоставлять демонстрационный пример, который должен быть разработан самостоятельно и не может напрямую копировать код из сети. Каждый демонстрационный пример может предоставить только один внешний интерфейс, который вызывается единообразно в файле demo_entry.c.

bsp.mk

Huawei LiteOS использует структуру компиляции компонентов, и после завершения компиляции каждого компонента или демонстрационного примера соответствующий файл статической библиотеки будет создан в каталоге out. Поскольку Windows не может автоматически связывать файлы статических библиотек, необходимо выполнить ручное связывание в файле bsp.mk. Например, добавьте ссылки на файлы статических библиотек curl и демонстрационных примеров:

ifneq ($(OS), Linux)
    ifeq ($(LOSCFG_COMPONENTS_CURL), y)
        LITEOS_BASELIB += -lcurl        # curl — это имя модуля компонента
    endif

    ifeq ($(LOSCFG_DEMOS_CURL), y)
        LITEOS_BASELIB += -lcurl_demo   # curl_demo — это имя демонстрационного модуля
    endif
endif

demo_entry.c

Вход всех демонстрационных примеров, после завершения демонстрационного примера, единообразно вызывается в функции DemoEntry в этом файле.

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

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

Примечание: Вызов функции должен осуществляться способом #include заголовочный файл, а не способом extern.

Процесс загрузки онлайн-компонентов

Платформа Linux

Скачайте исходный код Huawei LiteOS. После выполнения команды make menuconfig в корне исходного кода Huawei LiteOS автоматически вызывается сценарий download.sh, который считывает содержимое файла online_components для получения информации о загрузке компонентов, определяет, включен ли компонент, и, если он уже включен, продолжает определять, существует ли исходный код компонента, если нет, загружает исходный код компонента, origin.patch, src.sha256 и patch.sha256. С помощью файлов .sha256 определите, правильно ли загружены исходный код компонента и файл origin.patch. Если они верны, выполните исправление, завершите процесс загрузки онлайн-компонента.

Примечание: Если вы хотите повторно загрузить исходный код и патч, вам необходимо удалить существующие исходные коды и патчи в вашей локальной среде. Кроме того, во время выполнения сценария, если внешнее прерывание сигнала, такое как ctrl z, ctrl c и т. д., принудительно останавливает выполнение сценария, это может привести к сбою процесса загрузки, поэтому рекомендуется своевременно очистить файлы, оставшиеся от этой загрузки.

Платформа Windows

После завершения настройки проекта в инструменте разработки HUAWEI LiteOS Studio автоматически вызывается файл download.sh. Остальная логика такая же, как и на платформе Linux.

Тестирование компонентов

Завершив всю работу по разработке компонентов, необходимо протестировать компоненты, чтобы убедиться, что процесс загрузки онлайн-компонентов выполнен успешно.

Отправка кода

После успешного тестирования компонентов код можно отправить в различные репозитории исходного кода Huawei LiteOS. Требования к отправке кода следующие:

1. Онлайн-компоненты не требуют отправки исходного кода.