跳到內容

第一個運行模組

文件對應版本v0.2.0/main 穩定版

先讓一個 Module 跑起來:啟動時印出 hello started,正常關閉時印出 hello stopped。選擇下方的程式語言,兩種版本的 Shell 操作相同。

先準備建置指南中的工具,再取得範例:

終端機視窗
git clone --branch main https://github.com/JayTDawgzone1994/open-vinc-examples.git
cd open-vinc-examples
git submodule update --init framework/open-vinc
git -C framework/open-vinc submodule update --init --recursive
npm ci --prefix framework/open-vinc/src/vinc/ui/web

Windows 請使用 MSVC x64 開發環境。模組原始碼是 first-module/hello.cpp。

後續 PowerShell 與建置命令都在 open-vinc-examples repository 根目錄執行。

first-module/hello.cpp
#include <vinc/vinc.hpp>
#include <cstdint>
#include <iostream>
#include <string>
#include <vector>
class HelloModule final
: public vinc::BaseModule<vinc::RunMode::FrameworkLoop> {
public:
HelloModule() : BaseModule("hello") {
// 設定 Shell 指令使用的實例名稱。
}
vinc::Result<void> on_start(const std::vector<std::string>&) override {
// 啟動 hook:實例名稱核准後,由框架呼叫。
// 在這裡初始化模組;回傳 {} 代表初始化成功。
std::cout << "hello started" << std::endl;
return {};
}
vinc::Result<std::int32_t> module_interface(std::vector<std::string>) override {
// 指令 hook:Shell 將指令送到這個實例時,由框架呼叫。
// 回傳 0 表示成功,回傳 1 表示指令執行失敗。
// 第一個範例尚未提供應用程式指令。
return 1;
}
vinc::Result<void> on_stop() override {
// 停止 hook:正常關閉時由框架呼叫,在這裡清理模組資源。
std::cout << "hello stopped" << std::endl;
return {};
}
};
// 登記 Shell 用來建立此模組的種類名稱。
REGISTER_MODULE(HelloModule, "helloModule")

first-module/hello.cpp · e165aed · 中文註解

HelloModule 繼承 BaseModule。建構子提出實例名稱 hello,最後的 REGISTER_MODULE 登記種類 helloModule。

生命週期函式以 return {} 表示成功。這個範例還沒有應用指令,所以 module_interface() 回傳 1。

框架在 Module 可以開始初始化時呼叫 on_start()。函式結束後,Module 仍會繼續運行。正常關閉時,再由 on_stop() 清理資源。

FrameworkLoop 讓框架負責等待指令與停止要求,不需要自己寫無限迴圈。

CMake 專案負責加入框架並建置 Module:

first-module/CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(open_vinc_first_module LANGUAGES C CXX)
if(MSVC)
add_compile_options("$<$<COMPILE_LANGUAGE:CXX>:/utf-8>")
endif()
set(VINC_NAME "first-module-example" CACHE STRING "Central instance identity")
set(VINC_BUILD_APPS OFF CACHE BOOL "Build the framework's demonstration app")
set(BUILD_TESTING OFF CACHE BOOL "Build the framework's internal tests")
add_subdirectory(../framework/open-vinc/src open-vinc)
add_module(hello_module
MODULE_TYPE_NAME helloModule
SOURCES hello.cpp
)
vinc_add_app(Vinc INSTANCE_NAME "${VINC_NAME}" VINC_BUILD_CONFIG vinc.conf)
# 固定教學使用的執行檔路徑,Tcl 也會部署到相同位置。
set_target_properties(Vinc PROPERTIES
RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}"
RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}"
)
include(tests/CMakeLists.txt)

first-module/CMakeLists.txt · e165aed · 中文註解

add_module() 建置 hello.cpp 並登記 helloModule。其中的 MODULE_TYPE_NAME 要與 REGISTER_MODULE 的字串相同。

vinc_add_app() 建立中央 App。first-module/vinc.conf 選擇要放進這個 App 的模組:

first-module/vinc.conf
CONFIG_VINC_MODULE_helloModule=y

first-module/vinc.conf · e165aed

在 repository 根目錄建置:

終端機視窗
cmake -S first-module -B build/first-module-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build/first-module-debug

在 PowerShell 開啟 Vinc Shell:

終端機視窗
.\build\first-module-debug\Vinc.exe

看到 VINC ready 後,在 Vinc Shell 輸入:

helloModule

等待 hello started 和 Started hello。實際輸出可能帶有來源前綴,兩行的顯示順序也可能不同。

接著輸入 help,在運行中的模組列表找到 hello。

名稱 用途
helloModule ModuleType:輸入它來建立模組
hello 實例名稱:用來識別已運行的模組

這個範例使用固定實例名稱。再次輸入 helloModule 會嘗試建立另一個 hello,原本的還在運行時就會被拒絕。

exit

看到 hello stopped 後,Vinc 會等待 Module 程序退出,再回到 PowerShell。

接著前往第一個跨程序訊息,讓兩個 Module 傳遞計數訊息。