KasperskyOS Community Edition 1.2
Русский

Содержание

Использование CMake из состава KasperskyOS Community Edition

Для автоматизации процесса подготовки образа решения нужно настроить систему сборки CMake. За основу можно взять параметры системы сборки, используемые в примерах из состава KasperskyOS Community Edition.

В файлах CMakeLists.txt используется стандартный синтаксис CMake, а также команды и макросы из библиотек, поставляемых в KasperskyOS Community Edition.

Рекомендованная структура директорий проекта

При создании решения на базе KasperskyOS рекомендуется использовать следующую структуру директорий в проекте:

  • В корне проекта создать корневой файл CMakeLists.txt, содержащий общие инструкции сборки для всего решения.
  • Исходный код каждой из разрабатываемых программ следует разместить в отдельной директории, в поддиректории src.
  • Создать файлы CMakeLists.txt для сборки каждой прикладной программы в соответствующих директориях.
  • Для генерации исходного кода программы Einit следует создать отдельную директорию einit, содержащую поддиректорию src, в которую следует поместить шаблоны init.yaml.in и security.psl.in.

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

  • Создать файл CMakeLists.txt для сборки программы Einit в директории einit.
  • Файлы EDL-, CDL- и IDL-описаний следует разместить в директории resources в корне проекта.

Пример структуры директорий проекта

example$ tree . ├── CMakeLists.txt ├── hello │ ├── CMakeLists.txt │ ├── src │ │ ├── hello.c ├── einit │ ├── CMakeLists.txt │ ├── src │ │ ├── init.yaml.in │ │ ├── security.psl.in ├── resources │ ├── Hello.idl │ ├── Hello.cdl │ ├── Hello.edl

Сборка образа решения

Чтобы выполнить сборку образа решения, нужно использовать утилиту cmake (исполняемый файл toolchain/bin/cmake из состава KasperskyOS Community Edition).

Пример скрипта сборки:

build.sh

#!/bin/bash # Скрипт для запуска в корне проекта. # Сведения о параметрах запуска утилиты cmake можно # получить shell-командой cmake --help, а также из # официальной документации по CMake. TARGET="aarch64-kos" SDK_PREFIX="/opt/KasperskyOS-SDK" # Инициализация системы сборки cmake \ -G "Unix Makefiles" \ -D CMAKE_BUILD_TYPE:STRING=Release \ -D CMAKE_TOOLCHAIN_FILE=$SDK_PREFIX/toolchain/share/toolchain-$TARGET.cmake \ -S . \ -B build # Сборка # Чтобы собрать образ решения для QEMU, нужно указать цель, заданную в # параметре NAME CMake-команды build_kos_qemu_image() в файле CMakeLists.txt # для сборки программы Einit. # Чтобы собрать образ решения для аппаратной платформы, нужно указать цель, # заданную в параметре NAME CMake-команды build_kos_hw_image() в файле # CMakeLists.txt для сборки программы Einit. # Чтобы собрать образ решения для QEMU и запустить QEMU с этим образом, нужно # указать цель sim. cmake --build build --target sim

В этом разделе

Корневой файл CMakeLists.txt

Файлы CMakeLists.txt для сборки прикладных программ

Файл CMakeLists.txt для сборки программы Einit

Шаблон init.yaml.in

Шаблон security.psl.in
В начало
[Topic cmake_using_sdk_cmake]

Корневой файл CMakeLists.txt

Корневой файл CMakeLists.txt содержит общие инструкции сборки для всего решения.

Корневой файл CMakeLists.txt должен содержать следующие команды:

  • cmake_minimum_required (VERSION 3.25) – указание минимальной поддерживаемой версии CMake.

    Для сборки решения на базе KasperskyOS требуется CMake версии не ниже 3.25.

    Требуемая версия CMake поставляется в составе KasperskyOS Community Edition и используется по умолчанию.

  • include (platform) – подключение CMake-библиотеки platform.
  • initialize_platform() – инициализация библиотеки platform.
  • project_header_default("STANDARD_GNU_11:YES" "STRICT_WARNINGS:NO") – установка флагов компилятора и компоновщика.
  • [Опционально] Подключение и настройка пакетов для поставляемых системных программ и драйверов, которые необходимо включить в решение:
    • Подключение пакета выполняется с помощью команды find_package().
    • После подключения пакета необходимо добавить директории, связанные с этим пакетом, в список директорий поиска с помощью команды include_directories().
    • Для некоторых пакетов также требуется установить значения свойств с помощью команды set_target_properties().

    CMake-описания системных программ и драйверов, поставляемых в составе KasperskyOS Community Edition, а также их экспортируемых переменных и свойств находятся в соответствующих файлах /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/lib/cmake/<имя программы>/<имя программы>-config.cmake

  • Сборка инициализирующей программы Einit должна быть выполнена с помощью команды add_subdirectory(einit).
  • Все прикладные программы, сборку которых необходимо выполнить, должны быть добавлены с помощью команды add_subdirectory(<имя директории программы>).

Пример корневого файла CMakeLists.txt

CMakeLists.txt

cmake_minimum_required(VERSION 3.12) project (example) # Инициализация библиотеки CMake для KasperskyOS SDK. include (platform) initialize_platform () project_header_default ("STANDARD_GNU_11:YES" "STRICT_WARNINGS:NO") # Подключение пакета, импортирующего компоненты для работы с виртуальной файловой системой. # Компоненты импортируются из папки: /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/lib/cmake/vfs/vfs-config.cmake find_package (vfs REQUIRED COMPONENTS ENTITY CLIENT_LIB) include_directories (${vfs_INCLUDE}) # Подключение пакета, импортирующего компоненты для сборки программы аудита и # подключения к ней. find_package (klog REQUIRED) include_directories (${klog_INCLUDE}) # Сборка инициализирующей программы Einit add_subdirectory (einit) # Сборка прикладной программы hello add_subdirectory (hello)
В начало
[Topic cmake_lists_root]

Файлы CMakeLists.txt для сборки прикладных программ

Файл CMakeLists.txt для сборки прикладной программы должен содержать следующие команды:

  • include (platform/nk) – подключение библиотеки CMake для работы с компилятором NK.
  • project_header_default ("STANDARD_GNU_11:YES" "STRICT_WARNINGS:NO") – установка флагов компилятора и компоновщика.
  • EDL-описание класса процессов для программы можно сгенерировать, используя команду generate_edl_file().
  • Если программа предоставляет службы, используя механизм IPC, необходимо сгенерировать транспортный код:
    1. idl.h-файлы генерируются командой nk_build_idl_files()
    2. cdl.h-файлы генерируются командой nk_build_cdl_files()
    3. edl.h-файлы генерируются командой nk_build_edl_files()
  • add_executable (<имя программы> "<путь к файлу исходного кода программы>") – добавление цели для сборки программы.
  • add_dependencies (<имя программы> <имя цели сборки edl.h файла>) – добавление зависимости сборки программы от генерации edl.h-файла.
  • target_link_libraries (<имя программы> <список библиотек>) – определяет библиотеки, с которыми необходимо скомпоновать программу при сборке.

    Например, если программа использует файловый или сетевой ввод/вывод, то она должна быть скомпонована с транспортной библиотекой ${vfs_CLIENT_LIB}.

    CMake-описания системных программ и драйверов, поставляемых в составе KasperskyOS Community Edition, а также их экспортированных переменных и свойств находятся в соответствующих файлах /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/lib/cmake/<имя программы>/<имя программы>-config.cmake

  • Для автоматического добавления описаний IPC-каналов в файл init.yaml при сборке решения необходимо определить свойство EXTRA_CONNECTIONS и присвоить ему значение с описаниями нужных IPC-каналов.

    Обратите внимание на отступы в начале строк в свойстве EXTRA_CONNECTIONS. Эти отступы необходимы для корректной подстановки значений в файл init.yaml и должны соответствовать требованиям к его синтаксису.

    Пример создания IPC-канала между процессами Client и Server:

    set_target_properties (Client PROPERTIES EXTRA_CONNECTIONS " - target: Server id: server_connection")

    В результате, при сборке решения, описание этого IPC-канала будет автоматически добавлено в файл init.yaml на этапе обработки макросов шаблона init.yaml.in.

  • Для автоматического добавления списка аргументов функции main() и словаря переменных окружения в файл init.yaml при сборке решения, необходимо определить свойства EXTRA_ARGS и EXTRA_ENV и присвоить им соответствующие значения.

    Обратите внимание на отступы в начале строк в свойствах EXTRA_ARGS и EXTRA_ENV. Эти отступы необходимы для корректной подстановки значений в файл init.yaml и должны соответствовать требованиям к его синтаксису.

    Пример передачи программе Client аргумента "-v" функции main() и переменной окружения VAR1 со значением VALUE1:

    set_target_properties (Client PROPERTIES EXTRA_ARGS " - \"-v\"" EXTRA_ENV " VAR1: VALUE1")

    В результате, при сборке решения, описание аргумента функции main()и значение переменной окружения будут автоматически добавлены в файл init.yaml на этапе обработки макросов шаблона init.yaml.in.

Пример файла CMakeLists.txt для сборки простой прикладной программы

CMakeLists.txt

project (hello) # Инструментарий для работы с компилятором NK. include (platform/nk) # Установка флагов компиляции. project_header_default ("STANDARD_GNU_11:YES" "STRICT_WARNINGS:NO") # Задаем имя проекта, в который входит программа. set (LOCAL_MODULE_NAME "example") # Задаем имя программы. set (ENTITY_NAME "Hello") # Обратите внимание на содержание шаблонов init.yaml.in и security.psl.in # В них имена программ задаются как ${LOCAL_MODULE_NAME}.${ENTITY_NAME} # Задаем цели, которые будут использованы для создания генерируемых файлов программы. set (ENTITY_IDL_TARGET ${ENTITY_NAME}_idl) set (ENTITY_CDL_TARGET ${ENTITY_NAME}_cdl) set (ENTITY_EDL_TARGET ${ENTITY_NAME}_edl) # Задаем имя цели, которая будет использована для построения программы. set (APP_TARGET ${ENTITY_NAME}_app) # Добавляем цель сборки idl.h-файла. nk_build_idl_files (${ENTITY_IDL_TARGET} NK_MODULE ${LOCAL_MODULE_NAME} IDL "resources/Hello.idl" ) # Добавляем цель сборки cdl.h-файла. nk_build_cdl_files (${ENTITY_CDL_TARGET} IDL_TARGET ${ENTITY_IDL_TARGET} NK_MODULE ${LOCAL_MODULE_NAME} CDL "resources/Hello.cdl") # Добавляем цель сборки EDL-файла. Переменная EDL_FILE экспортируется # и содержит путь до сгенерированного EDL-файла. generate_edl_file ( ${ENTITY_NAME} PREFIX ${LOCAL_MODULE_NAME} ) # Добавляем цель сборки edl.h-файла. nk_build_edl_files (${ENTITY_EDL_TARGET} NK_MODULE ${LOCAL_MODULE_NAME} EDL ${EDL_FILE} ) # Определяем цель для сборки программы. add_executable (${APP_TARGET} "src/hello.c") # Имя программы в init.yaml и security.psl и имя исполняемого файла должны совпадать set_target_properties (${APP_TARGET} PROPERTIES OUTPUT_NAME ${ENTITY_NAME}) # Библиотеки, с которыми программа компонуется при сборке target_link_libraries ( ${APP_TARGET} PUBLIC ${vfs_CLIENT_LIB} # Программа использует файловый ввод/вывод # и должна быть подключена как клиент к VFS )
В начало
[Topic cmake_lists_applied]

Файл CMakeLists.txt для сборки программы Einit

Файл CMakeLists.txt для сборки инициализирующей программы Einit должен содержать следующие команды:

  • include (platform/image) – подключение библиотеки CMake, содержащей скрипты сборки образа решения.
  • project_header_default ("STANDARD_GNU_11:YES" "STRICT_WARNINGS:NO") – установка флагов компилятора и компоновщика.
  • Настройка пакетов системных программ и драйверов, которые необходимо включить в решение.
    • Подключение пакета выполняется с помощью команды find_package ().
    • Для некоторых пакетов также требуется установить значения свойств с помощью команды set_target_properties ().

    CMake-описания системных программ и драйверов, поставляемых в составе KasperskyOS Community Edition, а также их экспортированных переменных и свойств находятся в соответствующих файлах /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/lib/cmake/<имя программы>/<имя программы>-config.cmake

  • Для автоматического добавления описаний IPC-каналов между процессами системных программ в файл init.yaml при сборке решения необходимо добавить эти каналы в свойство EXTRA_CONNECTIONS для соответствующих программ.

    Обратите внимание на отступы в начале строк в свойстве EXTRA_CONNECTIONS. Эти отступы необходимы для корректной подстановки значений в файл init.yaml и должны соответствовать требованиям к его синтаксису.

    Например, программа VFS по умолчанию не имеет канала для соединения с программой Env. Чтобы описание такого канала автоматически добавилось в файл init.yaml при сборке решения, необходимо добавить следующий вызов в файл CMakeLists.txt для сборки программы Einit:

    set_target_properties (${vfs_ENTITY} PROPERTIES EXTRA_CONNECTIONS " - target: env.Env id: {var: ENV_SERVICE_NAME, include: env/env.h}"

    В результате, при сборке решения, описание этого IPC-канала будет автоматически добавлено в файл init.yaml на этапе обработки макросов шаблона init.yaml.in.

  • Для автоматического добавления списка аргументов функции main() и словаря переменных окружения в файл init.yaml при сборке решения, необходимо определить свойства EXTRA_ARGS и EXTRA_ENV и присвоить им соответствующие значения.

    Обратите внимание на отступы в начале строк в свойствах EXTRA_ARGS и EXTRA_ENV. Эти отступы необходимы для корректной подстановки значений в файл init.yaml и должны соответствовать требованиям к его синтаксису.

Пример передачи программе VfsEntity аргумента "-f fstab" функции main() и переменной окружения ROOTFS со значением ramdisk0,0 / ext2 0:

set_target_properties (${vfs_ENTITY} PROPERTIES EXTRA_ARGS " - \"-f\" - \"fstab\"" EXTRA_ENV " ROOTFS: ramdisk0,0 / ext2 0")

В результате, при сборке решения, описание аргумента функции main() и значение переменной окружения будут автоматически добавлены в файл init.yaml на этапе обработки макросов шаблона init.yaml.in.

  • set(ENTITIES <полный список программ, входящих в решение>) – определение переменной ENTITIES со списком исполняемых файлов всех программ, входящих в решение.
  • Одна или обе команды для сборки образа решения:
    • build_kos_hw_image() – создает цель сборки образа решения для аппаратной платформы.
    • build_kos_qemu_image() – создает цель сборки образа решения для QEMU.

Пример файла CMakeLists.txt для сборки программы Einit

CMakeLitsts.txt

project (einit) # Подключение библиотеки, содержащей скрипты сборки образа решения. include (platform/image) # Установка флагов компиляции. project_header_default ("STANDARD_GNU_11:YES" "STRICT_WARNINGS:NO") # Настройка программы VFS. # По умолчанию программе VFS не сопоставляется программа, реализующая блочное устройство. # Если необходимо использовать блочное устройство, например ata из компонента ata, # необходимо задать это устройство в переменной ${blkdev_ENTITY}_REPLACEMENT # Больше информации об экспортированных переменных и свойств программы VFS # см. в /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/lib/cmake/vfs/vfs-config.cmake # find_package(ata) # set_target_properties (${vfs_ENTITY} PROPERTIES ${blkdev_ENTITY}_REPLACEMENT ${ata_ENTITY}) # В простейшем случае не нужно взаимодействовать с диском, # поэтому мы устанавливаем значение переменной ${blkdev_ENTITY}_REPLACEMENT равным пустой строке set_target_properties (${vfs_ENTITY} PROPERTIES ${blkdev_ENTITY}_REPLACEMENT "") # Определение переменной ENTITIES со списком исполняемых файлов программ # Важно включить все программы, входящие в проект, кроме программы Einit. # Обратите внимание на то, что имя исполняемого файла программы должно # совпадать с названием цели, указанной в add_executable() в CMakeLists.txt для сборки этой программы. set(ENTITIES ${vfs_ENTITY} Hello_app ) # Создание цели сборки с именем kos-image, которая является образом решения для аппаратной платформы. build_kos_hw_image (kos-image EINIT_ENTITY EinitHw CONNECTIONS_CFG "src/init.yaml.in" # шаблон файла init.yaml SECURITY_PSL "src/security.psl.in" # шаблон файла security.psl IMAGE_FILES ${ENTITIES} ) # Создание цели сборки с именем kos-qemu-image, которая является образом решения для QEMU. build_kos_qemu_image (kos-qemu-image EINIT_ENTITY EinitQemu CONNECTIONS_CFG "src/init.yaml.in" SECURITY_PSL "src/security.psl.in" IMAGE_FILES ${ENTITIES} )
В начало
[Topic cmake_lists_einit]

Шаблон init.yaml.in

Шаблон init.yaml.in используется для автоматической генерации части файла init.yaml перед сборкой программы Einit средствами CMake.

Использование шаблона init.yaml.in позволяет не добавлять описания системных программ и IPC-каналов для соединения с ними в файл init.yaml вручную.

Шаблон init.yaml.in должен содержать следующие данные:

  • Корневой ключ entities.
  • Список всех прикладных программ, входящих в решение.
  • Для прикладных программ, использующих механизм IPC, необходимо указать список IPC-каналов, соединяющих эту программу с другими программами.

    IPC-каналы, соединяющие эту программу с другими прикладными программами указываются вручную или в файле CMakeLists.txt этой программы с помощью свойства EXTRA_CONNECTIONS.

    Для указания списка IPC-каналов, соединяющих эту программу с системными программами, входящими в состав KasperskyOS Community Edition, используются следующие макросы:

    • @INIT_<имя программы>_ENTITY_CONNECTIONS@ – при сборке заменяется на список IPC-каналов со всеми системными программами, с которыми скомпонована прикладная программа. Поля target и id заполняются в соответствии с файлами connect.yaml из состава KasperskyOS Community Edition, расположенными в /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/<имя системной программы>).

      Этот макрос нужно использовать, если прикладная программа не имеет соединений с другими прикладными программами и соединяется только с системными программами. Этот макрос добавляет корневой ключ connections.

    • @INIT_<имя программы>_ENTITY_CONNECTIONS+@ – при сборке добавляет список IPC-каналов со всеми системными программами, с которыми скомпонована прикладная программа, к списку IPC-каналов, заданному вручную. Этот макрос не добавляет корневой ключ connections.

      Этот макрос нужно использовать, если прикладная программа имеет соединения с другими прикладными программами, которые были указаны в шаблоне init.yaml.in вручную.

  • Макросы @INIT_<имя программы>_ENTITY_CONNECTIONS@ и @INIT_<имя программы>_ENTITY_CONNECTIONS+@ также добавляют список соединений для каждой программы, заданный в свойстве EXTRA_CONNECTIONS при сборке этой программы.
  • Если необходимо передать программе аргументы функции main(), заданные в свойстве EXTRA_ARGS при сборке этой программы, то необходимо использовать следующие макросы:
    • @INIT_<имя программы>_ENTITY_ARGS@ – при сборке заменяется на список аргументов функции main(), заданный в свойстве EXTRA_ARGS. Этот макрос добавляет корневой ключ args.
    • @INIT_<имя программы>_ENTITY_ARGS+@ – при сборке добавляет список аргументов функции main(), заданный в свойстве EXTRA_ARGS, к списку аргументов заданному вручную. Этот макрос не добавляет корневой ключ args.
  • Если необходимо передать программе значения переменных окружения, заданные в свойстве EXTRA_ENV при сборке этой программы, то необходимо использовать следующие макросы:
    • @INIT_<имя программы>_ENTITY_ENV@ – при сборке заменяется на словарь переменных окружения и их значений, заданный в свойстве EXTRA_ENV. Этот макрос добавляет корневой ключ env.
    • @INIT_<имя программы>_ENTITY_ENV+@ – при сборке добавляет словарь переменных окружения и их значений, заданный в свойстве EXTRA_ENV, к переменным заданным вручную. Этот макрос не добавляет корневой ключ env.
  • Макрос @INIT_EXTERNAL_ENTITIES@, который при сборке заменяется на список системных программ, с которыми скомпонована прикладная программа, и их IPC-каналов, аргументов функции main() и значений переменных окружения.

Пример шаблона init.yaml.in

init.yaml.in

entities: - name: ping.Client connections: # Программа "Client" может обращаться к "Server". - target: ping.Server id: server_connection @INIT_Client_ENTITY_CONNECTIONS+@ @INIT_Client_ENTITY_ARGS@ @INIT_Client_ENTITY_ENV@ - name: ping.Server @INIT_Server_ENTITY_CONNECTIONS@ @INIT_EXTERNAL_ENTITIES@

При сборке программы Einit из этого шаблона будет сгенерирован следующий файл init.yaml:

init.yaml

entities: - name: ping.Client connections: # Программа "Client" может обращаться к "Server" - target: ping.Server id: server_connection - target: kl.VfsEntity id: {var: _VFS_CONNECTION_ID, include: vfs/defs.h} args: - "-v" env: VAR1: VALUE1 - name: ping.Server connections: - target: kl.VfsEntity id: {var: _VFS_CONNECTION_ID, include: vfs/defs.h} - name: kl.VfsEntity path: VFS args: - "-f" - "fstab" env: ROOTFS: ramdisk0,0 / ext2
В начало
[Topic cmake_yaml_templates]

Шаблон security.psl.in

Шаблон security.psl.in используется для автоматической генерации части файла security.psl перед сборкой программы Einit средствами CMake.

Файл security.psl содержит часть описания политики безопасности решения.

Использование шаблона security.psl.in позволяет не добавлять EDL-описания системных программ в файл security.psl вручную.

Шаблон security.psl.in должен содержать описание политики безопасности решения, созданное вручную, включая следующие декларации:

  • установка глобальных параметров политики безопасности решения;
  • включение PSL-файлов в описание политики безопасности решения;
  • включение EDL-файлов прикладных программ в описание политики безопасности решения;
  • создание объектов моделей безопасности;
  • привязка методов моделей безопасности к событиям безопасности;
  • создание профилей аудита безопасности.

Для автоматического включения системных программ, необходимо использовать макрос @INIT_EXTERNAL_ENTITIES@.

Пример шаблона security.psl.in

security.psl.in

execute: kl.core.Execute use nk.base._ use EDL Einit use EDL kl.core.Core use EDL Client use EDL Server @INIT_EXTERNAL_ENTITIES@ /* Запуск программ разрешен */ execute { grant () } /* Отправка и получение запросов, ответов и ошибок разрешены. */ request { grant () } response { grant () } error { grant () } /* Обращения по интерфейсу безопасности игнорируются. */ security { grant () }
В начало
[Topic cmake_psl_templates]