Skip to content

MindConnect Library – 针对 Linux 的入门指南

先决条件

  • 需要 CMake 3.5.2 或更高版本构建 MindConnect Library。
  • 需要 OpenSSL 1.0.x 和 libcurl。
    注意:已经使用 OpenSSL 1.0.2q 和 LibCurl 7.64.1 测试 MCL。
    请确保对 libcurl 进行配置,以便将 OpenSSL 用作 TLS v1.2 实现。
    为了在您的实现中使用 OpenSSL,必须支持并配置以下任一密码以进行 SSL 握手:

    AES128-SHA256
    AES256-SHA256
    AES128-GCM-SHA256
    AES256-GCM-SHA384
    ECDHE-RSA-AES128-SHA256
    ECDHE-RSA-AES256-SHA384
    ECDHE-RSA-AES128-GCM-SHA256
    ECDHE-RSA-AES256-GCM-SHA384
    

    启用主机和对等验证来验证 MindSphere 证书的正确性。

  • 要构建单元和集成测试可执行文件,请确保 ruby 已经安装且对 CMake 可用。

准备和构建

以下步骤描述了每个构建过程,并向您展示如何在客户端应用中导入和使用 MCL。

创建构建目录

创建一个工作目录 {MCL_build_dir},CMake 将在目录中生成所需文件,例如 ~/MCL_build_linux 或者 C:\\Temp\\MCL_build_windows,并且切换到新目录:

mkdir {MCL_build_dir}
cd {MCL_build_dir}

以下所有构建步骤均在此工作目录中执行。MindConnect Library 的源文件将不受任何此类操作的影响。构建的文件位于:

{MCL_build_dir}\build\{build_type}\

使用 CMake 准备构建文件夹

MCL_build_dir 内部构建 MindConnect Library。占位符 {MCL_project_dir} 指定包含 CMakeLists.txt 源代码目录的位置。

cmake {MCL_project_dir}

在创建构建文件时,CMake 会在环境中寻找合适的编译器和链接器。在 Visual Studio 工具链的 Windows 系统下进行构建,您需要运行 vcvarsall.bat(位于 VS 安装路径中)来设置所有环境变量。

选择 CMake 生成器(可选)

根据为进行开发而使用的 IDE,您可以使用 CMake 为 MCL 创建项目并生成文件。根据您的环境使用 CMake 帮助文档,查看可用的生成器列表。

cmake --help

您将看到以下输出:

The following generators are available on this platform:
  Visual Studio 14 2015 [arch]  = Generates Visual Studio 2015 project files. Optional [arch] can be "Win64" or "ARM".
  ...
  Unix Makefiles                = Generates standard UNIX makefiles.
  ...
  Eclipse CDT4 - Unix Makefiles = Generates Eclipse CDT 4.0 project files with Unix Makefiles.

列出的每个生成器都可用于在 MCL_build_dir 构建目录中创建项目和生成文件。

如需使用上述任一生成器,请将 cmake 调用更改为:

cmake -G "name of the generator" {MCL_project_dir}

以下示例中的 CMake 调用均使用了上面列出的生成器:

cmake -G "Unix Makefiles" {MCL_project_dir}
cmake -G "Visual Studio 14 2015 Win64" {MCL_project_dir}
cmake -G "Eclipse CDT4 - Unix Makefiles" {MCL_project_dir}

如果您为 Visual Studio 或 Eclipse 选择了生成器,CMake 还会生成可由相应 IDE 打开的项目文件(如 VS 解决方案)。

如需获得特定构建类型的输出,请使用 CMAKE_BUILD_TYPE 参数。例如:

cmake -G "Eclipse CDT4 - Unix Makefiles" -DCMAKE_BUILD_TYPE={Debug|Release|..} {MCL_project_dir}

为构建过程指定 MCL 选项

您还可以启用或禁用其它选项以修改 MCL 的构建方式。每个选项将通过用以下命令提供给 CMake:

cmake -D{MCL_OPTION}[={selection}] {MCL_project_dir}

[={selection}] 为可选项。如果 MCL_OPTION 的值为空,可以省略此项。

支持操作以下选项:

选项 描述
MCL_STATICLIB 如果设置为 ON,MCL 将构建为静态库。
如果设置为 OFF(默认),MCL 将构建为动态库。
MCL_USE_LIBCURL 如果设置为 ON(默认),则使用 libcurl 构建 MCL。
如果设置为 OFF,则不使用 libcurl 构建 MCL。此时,用户必须提供实现 HTTPS 客户端的模块。用户必须确保 libcurl 在路径环境中可用。
MCL_USE_OPENSSL 如果设置为 ON(默认),则使用 OpenSSL 构建 MCL。
如果设置为 OFF,则不使用 OpenSSL 构建 MCL。此时,用户必须提供可实现 MCL 安全层(SHA256、MD5 计算等)的模块。确保 OpenSSL 1.0.2q 在路径中可用。
MCL_TESTING 如果设置为 ON(默认)且 Ruby 存在于路径中,则使用测试构建 MCL。
如果设置为 OFF,则不使用测试构建 MCL。
MCL_CREATE_DOXYGEN 如果设置为 ON(默认)且 Doxygen 存在于路径中,则使用 mcl_doc 目标构建 MCL。
如果设置为 OFF,则不使用 mcl_doc 目标构建 MCL。
MCL_LOG_UTIL_LEVEL 此选项的值用于设置编译的日志级别。
取值范围(从最低到最高级别):
MCL_LOG_UTIL_LEVEL_VERBOSE
MCL_LOG_UTIL_LEVEL_DEBUG
MCL_LOG_UTIL_LEVEL_INFO
MCL_LOG_UTIL_LEVEL_WARN
MCL_LOG_UTIL_LEVEL_ERROR
MCL_LOG_UTIL_LEVEL_FATAL
MCL_LOG_UTIL_LEVEL_NONE

使用 CMake 调用 Cross Build(可选)

CMake 还可以为不同的目标系统交叉构建 MindConnect Library。构建系统必须支持所需的工具链,并且必须提供工具链设置文件。使用工具链设置进行构建的 CMake 调用如下所示:

cmake -DCMAKE_TOOLCHAIN_FILE=../Toolchain-i586-poky-linux.cmake {MCL_project_dir}

必须在路径中提供任何所需的系统根文件夹,以便 CMake 能够找到目标系统的任何包含项。以下示例显示了用于在 Debian OS 上使用 Intel 工具链为 IoT2040 设备构建 MCL 的 Toolchain-i586-poky-linux.cmake

SET(CMAKE_SYSTEM_NAME Linux)
SET(CMAKE_SYSROOT ~/iss-iot-linux/devkit-x86/sysroots/i586-poky-linux)

SET(CMAKE_C_COMPILER i586-poky-linux-gcc)

SET(tools ~/iss-iot-linux/devkit-x86/sysroots/x86_64-pokysdk-linux/usr/bin/i586-poky-linux)
SET(CMAKE_FIND_ROOT_PATH ${tools})

SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
SET(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

为嵌入式设备构建 MCL 的示例如下:

SET(CMAKE_SYSTEM_NAME Generic)
INCLUDE(CMakeForceCompiler)
CMAKE_FORCE_C_COMPILER(arm-none-eabi-gcc GNU)
CMAKE_FORCE_CXX_COMPILER(arm-none-eabi-g++ GNU)
SET(CMAKE_C_FLAGS "-Wall -ffunction-sections -fdata-sections -fno-builtin-memcpy -gdwarf-2 -mthumb-interwork -mcpu=arm926ej-s -O0 -g3 -c -MMD -MP")
SET(CMAKE_EXE_LINKER_FLAGS "-nostdlib -nostartfiles -Wl,--gc-sections -Wl,--wrap=malloc -Wl,--wrap=calloc -Wl,--wrap=realloc -Wl,--wrap=free -Wl,--wrap=_malloc_r -Wl,--wrap=_calloc_r -Wl,--wrap=_realloc_r -Wl,--wrap=_free_r -Wl,--defsym -Wl,PAGE_SIZE=0 -Wl,--start-group -lgcc -lc -lm -lstdc++ -Wl,--end-group")

使用 CMake 调用构建

设置文件夹结构后即可构建 MCL 项目。例如,如果 make 命令位于工具链中,您可以直接在构建文件夹中调用该命令,而对于其它工具链设置,您需要调用以下命令(构建所有目标):

cmake --build .

您只能从下表列出的目标中选择其中一种:

目标 描述
mc 用于构建 MCL
mcl_doc 用于构建 MCL 项目的 Doxygen 文档
package 用于生成 MCL 发布软件包
test_{module_name} 用于为 MCL 的给定模块构建单元测试可执行文档

使用以下命令结构只能构建一个目标:

cmake --build . --target {target_name}

创建 Doxygen 文档

通过 Doxygen 构建 MCL 文档。该项目包含一个 Doxygen 配置文件,可以根据您的需要进行调整。您可以调用 CMake 目标来构建文档,如下所示:

cmake --build . --target mcl_doc

生成发布软件包

使用 CPack 生成 MCL 的发布软件包。在 CMake 文件中配置 CPack。通过调用 CMake 目标可生成发布软件包 MCL-{mcl_version}-{target_system}.zip,如下所示:

cmake --build . --target package

执行单元和集成测试

如果使用包含的测试构建所有目标,则可以使用以下命令运行测试:

ctest .

有关使用正则表达式运行或排除特定测试的信息,请参见 CTest (ctest --help) 帮助文档。

构建过程将所有输出存储于 {MCL_build_dir}/build/{Debug|Release|... 子文件夹中。

为 Linux 构建和运行自定义代理

执行下列步骤,使用 MCL 为 Linux 重新构建和运行自定义代理。

创建目录结构

  1. 创建 /usr/customAgentExample 目录。该目录是整个过程的父目录。
  2. 创建 /usr/customAgentExample/build 目录。该目录是构建输出的父目录。
  3. 为 openssl 构建输出创建/usr/customAgentExample/build/openssl 目录。
  4. 为 curl 构建输出创建 /usr/customAgentExample/build/curl 目录。
  5. 为 mcl 构建输出创建 /usr/customAgentExample/build/mcl 目录。
  6. 为代理构建输出创建 /usr/customAgentExample/build/agent 目录。
  7. 将 MCL 源代码 .../MCL_Core 复制到/usr/customAgentExample

说明

如果需要,使用以下命令更改目录模式:

sudo chmod 755 {directory_path}

构建 OpenSSL

下载 OpenSSL 包 openssl-1.0.2q.tar.gz。将 openssl-1.0.2q.tar.gz 解压到 /usr/customAgentExample。输入以下命令:

cd /usr/customAgentExample/{downloaded_openssl_dir}
./config --openssldir=/usr/customAgentExample/build/openssl shared -fPIC
sudo make install

构建 Libcurl

下载 curl-7.64.1.zip。将 curl-7.64.1.zip 解压到 /usr/customAgentExample。输入以下命令:

cd /usr/customAgentExample/{downloaded_curl_dir}
LDFLAGS="-Wl,-R/usr/customAgentExample/build/openssl/lib" ./configure --enable-http --with-ssl=/usr/customAgentExample/build/openssl --prefix=/usr/customAgentExample/build/curl --without-libssh2 --disable-ftp --disable-tftp --disable-file --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-pop3 --disable-imap --disable-smb --disable-scp --disable-sftp --disable-smtp --disable-gopher --disable-manual
sudo make install

构建 MCL

使用以下内容创建 bash 文件 /usr/customAgentExample/build_mcl:

#!/bin/bash
OPENSSL_DIR="/usr/customAgentExample/build/openssl"
CURL_DIR="/usr/customAgentExample/build/curl"
MCL_SOURCE_DIR="/usr/customAgentExample/MCL_Core"
MCL_BUILD_DIR="/usr/customAgentExample/build/mcl"
if [ -d ${MCL_BUILD_DIR} ]; then
 sudo rm -rf ${MCL_BUILD_DIR}
fi
sudo mkdir ${MCL_BUILD_DIR}
sudo chmod 777 ${MCL_BUILD_DIR}
cd ${MCL_BUILD_DIR}
cmake -DCMAKE_PREFIX_PATH="${OPENSSL_DIR};${CURL_DIR}" -DCMAKE_BUILD_TYPE=Release -DMCL_STATICLIB=OFF -DMCL_USE_LIBCURL=ON -DMCL_USE_OPENSSL=ON -DMCL_CREATE_DOXYGEN=OFF -DMCL_TESTING=OFF -DMCL_LOG_UTIL_LEVEL=MCL_LOG_UTIL_LEVEL_NONE ${MCL_SOURCE_DIR}
cmake --build . --target mc

使用以下命令构建 MCL:

sudo ./build_mcl

确保使用以下命令链接了正确的库:

ldd /usr/customAgentExample/build/mcl/build/Release/libmc.so

构建自定义代理应用

  1. 为代理应用创建 /usr/customAgentExample/agent 目录。
  2. 使用以下内容在 /usr/customAgentExample/agent 中创建 CMakeLists.txt 文件:

    CMAKE_MINIMUM_REQUIRED(VERSION 3.5 FATAL_ERROR)
    PROJECT(CustomAgentApplication LANGUAGES C)
    SET(CMAKE_C_STANDARD 99)
    SET(CMAKE_C_STANDARD_REQUIRED ON)
    FILE(GLOB SOURCES *.c)
    LIST(APPEND AGENT_SOURCES ${SOURCES})
    SET(MCL "/usr/customAgentExample/build/mcl/build/Release/libmc.so" CACHE INTERNAL "MCL" FORCE)
    SET(MCL_INCLUDE_DIRECTORIES "/usr/customAgentExample/build/mcl/include/" CACHE INTERNAL "MCL_INCLUDE_DIRECTORIES" FORCE)
    SET(AGENT_OUTPUT_DIR ${CMAKE_BINARY_DIR}/build)
    SET(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${AGENT_OUTPUT_DIR})
    SET(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${AGENT_OUTPUT_DIR})
    SET(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${AGENT_OUTPUT_DIR})
    ADD_EXECUTABLE(${PROJECT_NAME} ${AGENT_SOURCES})
    TARGET_INCLUDE_DIRECTORIES(${PROJECT_NAME} PUBLIC ${MCL_INCLUDE_DIRECTORIES})
    TARGET_LINK_LIBRARIES(${PROJECT_NAME} ${MCL})
    
  3. 确保提供的 MCL 消息头位于 /usr/customAgentExample/build/mcl/include/mcl 中。

  4. /usr/customAgentExample/agent 中为自定义代理应用编写源代码,然后运行以下命令:
cd /usr/customAgentExample/build/agent
cmake /usr/customAgentExample/agent
cmake --build . --clean-first
./build/CustomAgentApplication

使用自定义实现替换 MCL 模块

下表列出了 MCL 项目的模块,可用自定义实现进行替换:

模块 描述
memory.h 实现与内存相关的功能。如果没有特别说明,将从标准库中选用 alloccallocreallocfree。您可以使用自定义实现替换此模块,该自定义实现可为目标设备和构建环境进行内存管理。
random.h 如果没有特别说明,MCL 将使用标准库中的随机生成器。您可以使用自定义实现替换此模块。
security.h 此模块提供了几种实现计算的功能,如 SHA256、MD5、RSA 密钥生成。如果没有特别说明,这些计算将由 OpenSSL 的加密库执行。替换此模块来提供您自己的硬件特定实现。
http_client.h MCL 使用此模块向 MindSphere 发送 HTTP 请求。如果没有特别说明,将使用 libcurl 来实现通信。您可以使用自定义实现替换此模块。您的实现必须满足与 TLS v1.2 相同的安全要求。MindSphere 证书必须在 SSL 握手过程中由您的实现进行验证。

要替换模块,请保留原始 *.h 文件,并用相同的名称替换其实现文件 *.c


Last update: March 22, 2023