CMake libraries in KasperskyOS Community Edition

This section contains a description of the libraries that are provided in KasperskyOS Community Edition for automatically building a KasperskyOS-based solution.

platform library

The platform library contains the following commands:

• initialize_platform() is the command for initializing the platform library.

  The initialize_platform() command can be called with the FORCE_STATIC parameter, which enables forced static linking of executable files:

  • By default, if the toolchain in the KasperskyOS SDK supports dynamic linking, the initialize_platform() command causes the -rdynamic flag to be used automatically for building all executable files defined via CMake add_executable() commands.
  • When calling initialize_platform (FORCE_STATIC) in the CMakeLists.txt root file, the toolchain supporting dynamic linking performs static linking of executable files.

  The initialize_platform() command can be called with the NO_NEW_VERSION_CHECK parameter, which disables the check for SDK updates and transmission of the SDK version to the Kaspersky server.

  To disable the check for SDK updates and transmission of SDK version data to the Kaspersky server, use the following call during the solution build: initialize_platform(NO_NEW_VERSION_CHECK). For more details about the data provision policy, see Data provision.

• project_static_executable_header_default() is the command for enabling forced static linking of executable files defined via subsequent CMake add_executable() commands in one CMakeLists.txt file. The toolchain that supports dynamic linking performs static linking of these executable files.
• platform_target_force_static() is the command for enabling forced static linking of an executable file defined via the CMake add_executable() command. The toolchain that supports dynamic linking performs static linking of this executable file. For example, if the CMake commands add_executable(client "src/client.c") and platform_target_force_static(client) are called, static linking is performed for the client program.
• project_header_default() is the command for setting compile flags.

  Command parameters are defined in pairs consisting of a compile flag and its value: "FLAG_1:VALUE_1" "FLAG_2:VALUE_2" ... "FLAG_N:VALUE_N". The CMake platform library converts these pairs into compiler parameters.

When using the initialize_platform(FORCE_STATIC), project_static_executable_header_default() and platform_target_force_static() commands, you may encounter linking errors if the static variants of the required libraries are missing (for example, if they were not built or are not included in the KasperskyOS SDK). Even if the static variants of the required libraries are available, these errors may still occur because the build system searches for the dynamic variants of required libraries by default instead of the expected static variants when using the initialize_platform(FORCE_STATIC), project_static_executable_header_default() and platform_target_force_static() commands. To avoid errors, first make sure that the static variants are available. Then configure the build system to search for static libraries (although this capability may not be available for some libraries), or explicitly define linking with static libraries.

Examples of configuring the build system to search for static libraries:

Example that explicitly defines linking with a static library:

For more details about using dynamic libraries, see Using dynamic libraries.

These commands are used in CMakeLists.txt files for the Einit program and application software.

nk library

This section contains a description of the commands and macros of the CMake library for working with the NK compiler.

generate_edl_file()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/nk2.cmake.

This command generates an EDL file containing a description of the process class.

Parameters:

• NAME – name of the EDL file being created. Required parameter.
• PREFIX – parameter in which you need to specify the name of the process class, excluding the name of the EDL file. For example, if the name of the process class for which the EDL file is being created is defined as kl.core.NameServer, the PREFIX parameter must pass the value kl.core.
• EDL_COMPONENTS – name of the component and its instance that will be included in the EDL file. For example: EDL_COMPONENTS "env: kl.Env". To include multiple components, you need to use multiple EDL_COMPONENTS parameters.
• SECURITY – qualified name of the security interface method that will be included in the EDL file.
• OUTPUT_DIR – directory in which the EDL file will be created. The default directory is ${CMAKE_CURRENT_BINARY_DIR}.

As a result of this command, the EDL_FILE variable is exported and contains the path to the generated EDL file.

Example call:

For an example of using this command, see the article titled CMakeLists.txt files for building application software.

nk_build_idl_files()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/nk2.cmake.

This command creates a CMake target for generating .idl.h files for one or more defined IDL files using the NK compiler.

Parameters:

• NAME – name of the CMake target for building .idl.h files. If a target has not yet been created, it will be created by using add_library() with the specified name. Required parameter.
• NOINSTALL – if this option is specified, files will only be generated in the working directory and will not be installed in global directories: ${CMAKE_BINARY_DIR}/_headers_ ${CMAKE_BINARY_DIR}/_headers_/${PROJECT_NAME}.
• NK_MODULE – parameter in which you need to specify the package name, excluding the name of the IDL file. For example, if the package name in the IDL description is defined as kl.core.NameServer, the kl.core value must be passed in the NK_MODULE parameter.
• WORKING_DIRECTORY – working directory for calling the NK compiler, which is ${CMAKE_CURRENT_BINARY_DIR} by default.
• DEPENDS – additional build targets on which the IDL file depends.

  To add multiple targets, you need to use multiple DEPENDS parameters.

• IDL – path to the IDL file for which the idl.h file is being generated. Required parameter.

  To add multiple IDL files, you need to use multiple IDL parameters.

  If one IDL file imports another IDL file, idl.h files need to be generated in the order necessary for compliance with dependencies (with the most deeply nested first).

• NK_FLAGS – additional flags for the NK compiler.

Example call:

For an example of using this command, see the article titled CMakeLists.txt files for building application software.

nk_build_cdl_files()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/nk2.cmake.

This command creates a CMake target for generating .cdl.h files for one or more defined CDL files using the NK compiler.

Parameters:

• NAME – name of the CMake target for building .cdl.h files. If a target has not yet been created, it will be created by using add_library() with the specified name. Required parameter.
• NOINSTALL – if this option is specified, files will only be generated in the working directory and are not installed in global directories: ${CMAKE_BINARY_DIR}/_headers_ ${CMAKE_BINARY_DIR}/_headers_/${PROJECT_NAME}.
• IDL_TARGET – target when building .idl.h files for IDL files containing descriptions of endpoints provided by components described in CDL files.
• NK_MODULE – parameter in which you need to specify the component name, excluding the name of the CDL file. For example, if the component name in the CDL description is defined as kl.core.NameServer, the kl.core value must be passed in the NK_MODULE parameter.
• WORKING_DIRECTORY – working directory for calling the NK compiler, which is ${CMAKE_CURRENT_BINARY_DIR} by default.
• DEPENDS – additional build targets on which the CDL file depends.

  To add multiple targets, you need to use multiple DEPENDS parameters.

• CDL – path to the CDL file for which the .cdl.h file is being generated. Required parameter.

  To add multiple CDL files, you need to use multiple CDL parameters.

• NK_FLAGS – additional flags for the NK compiler.

Example call:

For an example of using this command, see the article titled CMakeLists.txt files for building application software.

nk_build_edl_files()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/nk2.cmake.

This command creates a CMake target for generating an .edl.h file for one defined EDL file using the NK compiler.

Parameters:

• NAME – name of the CMake target for building an .edl.h file. If a target has not yet been created, it will be created by using add_library() with the specified name. Required parameter.
• NOINSTALL – if this option is specified, files will only be generated in the working directory and are not installed in global directories: ${CMAKE_BINARY_DIR}/_headers_ ${CMAKE_BINARY_DIR}/_headers_/${PROJECT_NAME}.
• CDL_TARGET – target when building .cdl.h files for CDL files containing descriptions of components of the EDL file for which the build is being performed.
• IDL_TARGET – target when building .idl.h files for IDL files containing descriptions of interfaces of the EDL file for which the build is being performed.
• NK_MODULE – parameter in which you need to specify the name of the process class, excluding the name of the EDL file. For example, if the process class name in the EDL description is defined as kl.core.NameServer, the kl.core value must be passed in the NK_MODULE parameter.
• WORKING_DIRECTORY – working directory for calling the NK compiler, which is ${CMAKE_CURRENT_BINARY_DIR} by default.
• DEPENDS – additional build targets on which the EDL file depends.

  To add multiple targets, you need to use multiple DEPENDS parameters.

• EDL – path to the EDL file for which the edl.h file is being generated. Required parameter.
• NK_FLAGS – additional flags for the NK compiler.

Example calls:

For an example of using this command, see the article titled CMakeLists.txt files for building application software.

Generating transport code for development in C++

The CMake commands add_nk_idl(), add_nk_cdl() and add_nk_edl() are used to generate transport proxy objects and stubs using the nkppmeta compiler when building a solution.

add_nk_idl()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/nk2.cmake.

This command creates a CMake target for generating a *.idl.cpp.h header file for a defined IDL file using the nkppmeta compiler. The command also creates a library containing the transport code for the defined interface. To link to this library, use the bind_nk_targets() command.

The generated header files contain a C++ representation for the interface and data types described in the IDL file, and the methods required for use of proxy objects and stubs.

Parameters:

• NAME – name of the CMake target. Required parameter.
• IDL_FILE – path to the IDL file. Required parameter.
• NK_MODULE – parameter in which you need to specify the package name, excluding the name of the IDL file. For example, if the package name in the IDL description is defined as kl.core.NameServer, the kl.core value must be passed in the NK_MODULE parameter.
• LANG – parameter in which you need to specify the CXX value.

Example call:

add_nk_cdl()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/nk2.cmake.

This command creates a CMake target for generating a *.cdl.cpp.h file for a defined CDL file using the nkppmeta compiler. The command also creates a library containing the transport code for the defined component. To link to this library, use the bind_nk_targets() command.

The *.cdl.cpp.h file contains the tree of embedded components and endpoints provided by the component described in the CDL file.

Parameters:

• NAME – name of the CMake target. Required parameter.
• CDL_FILE – path to the CDL file. Required parameter.
• NK_MODULE – parameter in which you need to specify the component name, excluding the name of the CDL file. For example, if the component name in the CDL description is defined as kl.core.NameServer, the kl.core value must be passed in the NK_MODULE parameter.
• LANG – parameter in which you need to specify the CXX value.

Example call:

add_nk_edl()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/nk2.cmake.

This command creates a CMake target for generating a *.edl.cpp.h file for a defined EDL file using the nkppmeta compiler. The command also creates a library containing the transport code for the server or client program. To link to this library, use the bind_nk_targets() command.

The *.edl.cpp.h file contains the tree of embedded components and endpoints provided by the process class described in the EDL file.

Parameters:

• NAME – name of the CMake target. Required parameter.
• EDL_FILE – path to the EDL file. Required parameter.
• NK_MODULE – parameter in which you need to specify the name of the process class, excluding the name of the EDL file. For example, if the process class name in the EDL description is defined as kl.core.NameServer, the kl.core value must be passed in the NK_MODULE parameter.
• LANG – parameter in which you need to specify the CXX value.

Example call:

image library

This section contains a description of the commands and macros of the CMake library named image that is included in KasperskyOS Community Edition and contains solution image build scripts.

build_kos_qemu_image()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/image.cmake.

The command creates a CMake target for building a solution image for QEMU.

Parameters:

• NAME – name of the CMake target for building a solution image. Required parameter.
• PERFCNT_KERNEL – use the kernel with performance counters if it is available in KasperskyOS Community Edition.
• EINIT_ENTITY – name of the executable file that will be used to start the Einit program.
• EXTRA_XDL_DIR – additional directories to include when building the Einit program.
• CONNECTIONS_CFG – path to the init.yaml file or init.yaml.in template.
• SECURITY_PSL – path to the security.psl file or security.psl.in template.
• KLOG_ENTITY – target for building the Klog system program, which is responsible for the security audit. If the target is not specified, the audit is not performed.
• QEMU_FLAGS – additional flags for running QEMU.
• IMAGE_BINARY_DIR_BIN – directory for the final image and other artifacts. It matches CMAKE_CURRENT_BINARY_DIR by default.
• NO_AUTO_BLOB_CONTAINER – solution image will not include the BlobContainer program that is required for working with dynamic libraries in shared memory. For more details, refer to Including the BlobContainer system program in a KasperskyOS-based solution.
• PACK_DEPS, PACK_DEPS_COPY_ONLY, PACK_DEPS_LIBS_PATH, and PACK_DEPS_COPY_TARGET – parameters that define the method used to add dynamic libraries to the solution image.
• GINGER_ENABLE – enable (GINGER_ENABLE TRUE) or disable (GINGER_ENABLE FALSE) the Ginger template engine.
• GINGER_DEFINITIONS – set of variables used when expanding Ginger PSL templates. For example, GINGER_DEFINITIONS "foo=bar baz=quux USE_DYNLD" sets the foo variable to bar, sets the baz variable to quux, and sets the USE_DYNLD variable to TRUE. The USE_DYNLD variable is set to TRUE because variables used when expanding Ginger PSL templates are set to TRUE by default.
• GINGER_DUMP_DIR – path to the directory where PSL files received from Ginger PSL templates will be stored. These PSL files are needed only to verify what was obtained as a result of expanding Ginger PSL templates, and are not used to generate source code of the Kaspersky Security Module. (When source code of the security module is generated, Ginger PSL templates are expanded in memory irrespective of whether or not the GINGER_DUMP_DIR parameter is being used.) The names of PSL files are generated based on the absolute paths to Ginger PSL templates. For example, the PSL file named foo!bar!baz.psl corresponds to the Ginger PSL template located at the path /foo/bar/baz.psl.
• IMAGE_FILES – executable files of applications and system programs (except the Einit program) and any other files to be added to the ROMFS image.

  To add multiple applications or files, you can use multiple IMAGE_FILES parameters.

• <path to files> – free parameters like IMAGE_FILES.

Example call:

For an example of using this command, see the article titled CMakeLists.txt files for building the Einit program.

build_kos_hw_image()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/image.cmake.

The command creates a CMake target for building a solution image for the hardware platform.

Parameters:

• NAME – name of the CMake target for building a solution image. Required parameter.
• PERFCNT_KERNEL – use the kernel with performance counters if it is available in KasperskyOS Community Edition.
• EINIT_ENTITY – name of the executable file that will be used to start the Einit program.
• EXTRA_XDL_DIR – additional directories to include when building the Einit program.
• CONNECTIONS_CFG – path to the init.yaml file or init.yaml.in template.
• SECURITY_PSL – path to the security.psl file or security.psl.in template.
• KLOG_ENTITY – target for building the Klog system program, which is responsible for the security audit. If the target is not specified, the audit is not performed.
• IMAGE_BINARY_DIR_BIN – directory for the final image and other artifacts. The default directory is CMAKE_CURRENT_BINARY_DIR.
• NO_AUTO_BLOB_CONTAINER – solution image will not include the BlobContainer program that is required for working with dynamic libraries in shared memory. For more details, refer to Including the BlobContainer system program in a KasperskyOS-based solution.
• PACK_DEPS, PACK_DEPS_COPY_ONLY, PACK_DEPS_LIBS_PATH, and PACK_DEPS_COPY_TARGET – parameters that define the method used to add dynamic libraries to the solution image.
• GINGER_ENABLE – enable (GINGER_ENABLE TRUE) or disable (GINGER_ENABLE FALSE) the Ginger template engine.
• GINGER_DEFINITIONS – set of variables used when expanding Ginger PSL templates. For example, GINGER_DEFINITIONS "foo=bar baz=quux USE_DYNLD" sets the foo variable to bar, sets the baz variable to quux, and sets the USE_DYNLD variable to TRUE. The USE_DYNLD variable is set to TRUE because variables used when expanding Ginger PSL templates are set to TRUE by default.
• GINGER_DUMP_DIR – path to the directory where PSL files received from Ginger PSL templates will be stored. These PSL files are needed only to verify what was obtained as a result of expanding Ginger PSL templates, and are not used to generate source code of the Kaspersky Security Module. (When source code of the security module is generated, Ginger PSL templates are expanded in memory irrespective of whether or not the GINGER_DUMP_DIR parameter is being used.) The names of PSL files are generated based on the absolute paths to Ginger PSL templates. For example, the PSL file named foo!bar!baz.psl corresponds to the Ginger PSL template located at the path /foo/bar/baz.psl.
• IMAGE_FILES – executable files of applications and system programs (except the Einit program) and any other files to be added to the ROMFS image.

  To add multiple applications or files, you can use multiple IMAGE_FILES parameters.

• <path to files> – free parameters like IMAGE_FILES.

Example call:

For an example of using this command, see the article titled CMakeLists.txt files for building the Einit program.

build_sd_image library

The build_sd_image library is included in the KasperskyOS SDK and contains the build_sd_image() command. This command is declared in the file named /opt/KasperskyOS-Community-Edition-<version>/common/build-sd-image.cmake.

The command creates a CMake target for building an SD card image for running a solution on the hardware platform.

Parameters:

• IMAGE_NAME – name of the CMake target for building an SD card image for running the solution on the hardware platform. Required parameter.
• KOS_IMAGE_TARGET – name of the CMake target for building a solution image for the hardware platform that will be added to the SD card image.
• KOS_COPY_PATH – path to the directory where the solution image for the hardware platform will be copied before it is added to the SD card image.
• IMAGE_FS – path to the root directory of the file system that will be used for the SD card image. Default value: ${CMAKE_BINARY_DIR}/hdd.
• OUTPUT_IMAGE_NAME – name of the SD card image.
• DISK_SIZE – size of the created SD card image in megabytes. Default value: 1024 MB.
• PARTITION_CMD – set of parameters that will be used to create and configure partitions in the SD card image. Separate the parameters with a space.

Example call:

kpa library

This section contains a description of commands of the CMake library kpa, which is intended for building KPA packages.

add_kpa_package()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/kpa.cmake.

The command creates a CMake target for building the KPA package. When building this target, the build process automatically creates the KPA package manifest and the KPA package, which includes all components that were added to this target using the CMake command add_kpa_component().

Parameters:

• KPA_TARGET_NAME – name of the CMake target. Required parameter.
• MANIFEST_V – version of the KPA package manifest. Required parameter. It must be set to 2.
• VERSION – version of the KPA package. The default value is PROJECT_VERSION.
• ID – ID of the KPA package. The default value is KPA_TARGET_NAME.
• DEVELOPER_ID – identifier of the developer. The default value is "unspecified".
• DONT_VERIFY—if this parameter is defined, verification of the presence of all KPA package components specified in its manifest and the absence of unspecified components, and calculation of the checksums of KPA package components and their comparison with those specified in the KPA package manifest will not be performed.

Properties of the created CMake target:

• KPA_OUTPUT_DIR – directory in which the KPA package will be put.
• KPA_OUTPUT_NAME – name of the KPA file without the file extension. The default value is ${DEVELOPER_ID}.${ID}.

Example call:

add_kpa_component()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/cmake/Modules/platform/kpa.cmake.

The command adds the component to the specified CMake target for building the KPA package. This command can be called multiple times for the same KPA package build target. A KPA package build target is created by the add_kpa_package() command.

Parameters:

• PACKAGE_NAME – name of the CMake target for building the KPA package. Required parameter.
• MODE – type of component. Required parameter. The following values are possible:
  • LIBRARY – the component is a dynamic library. You must specify the full path to the file or the name of the CMake target. It is put into the directory /<package_name>/lib when the KPA package is installed.
  • FILES – the component is a file. You must specify the full path to the file. When a KPA package is installed, it is put into the /<package_name>/res directory.
  • DIRECTORY – the component is a directory containing files. You must specify the full path to the directory. When a KPA package is installed, it is put into the /<package_name>/res directory.
  • RUN_CONFIGURATION – the component is a program run configuration. You must specify the following parameters:
    • ID – startup configuration ID that is unique within the KPA package. Required parameter.
    • NAME – startup configuration name. Required parameter.
    • TYPE – type of run configuration: "gui" – process with a graphical user interface or "service" – endpoint process. Required parameter.
    • PATH – full path to the executable file of the component after KPA package installation relative to the /<package_name> directory.
    • EIID – security class of the program. Required parameter.
    • PRIMARY – indicates whether the startup configuration is the primary one during program startup.
    • AUTORUN – indicates whether this configuration is started automatically.
    • ARGS – list of command-line arguments in the form of a string array for starting the program.
    • ENV – list of environment variables for starting the program.
  • RESOURCE – used for adding arbitrary data to the KPA package. You must specify the following parameters:
    • Full path to the file or directory containing the data. Required parameter.
    • In the TYPE parameter, specify the data type: "res", "bin", "lib" or "manifestLocale". Required parameter. For more details, refer to List of "components" objects.
    • (Optional) In the DIRECTORY_PATH parameter, specify the path to the directory where the data will be put after KPA package installation; the specified path should be relative to the /<package_name>/res directory.

Example calls: