第一個運行模組
先讓一個 Module 跑起來:啟動時印出 hello started,正常關閉時印出 hello stopped。選擇下方的程式語言,兩種版本的 Shell 操作相同。
1. 準備專案
Section titled “1. 準備專案”先準備建置指南中的工具,再取得範例:
git clone --branch main https://github.com/JayTDawgzone1994/open-vinc-examples.gitcd open-vinc-examplesgit submodule update --init framework/open-vincgit -C framework/open-vinc submodule update --init --recursivenpm ci --prefix framework/open-vinc/src/vinc/ui/webWindows 請使用 MSVC x64 開發環境。模組原始碼是 first-module/hello.cpp。
先完成準備 Python 範例,沿用該專案和環境。
模組原始碼是 python/modules/helloModule/helloModule.py。
後續 PowerShell 與建置命令都在 open-vinc-examples repository 根目錄執行。
2. 撰寫模組
Section titled “2. 撰寫模組”#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。
import vinc
class Module(vinc.BaseModule, mode=vinc.RunMode.FrameworkLoop): def on_name(self, args): # 命名 hook:回傳 Shell 用來識別此模組的實例名稱。 # 發布與訂閱請稍後在 on_start 裡建立。 return "hello"
def on_start(self, args): # 啟動 hook:實例名稱核准後,由框架呼叫。 # 在這裡初始化模組;回傳 None 代表初始化成功。 print("hello started")
def on_stop(self): # 停止 hook:正常關閉時由框架呼叫,在這裡清理模組資源。 print("hello stopped")python/modules/helloModule/helloModule.py · e165aed · 中文註解
匯出名為 Module 的類別,繼承 vinc.BaseModule。on_name() 回傳實例名稱 hello。
生命週期函式成功時回傳 None;執行到函式結尾,就會自動回傳 None。
框架在 Module 可以開始初始化時呼叫 on_start()。函式結束後,Module 仍會繼續運行。正常關閉時,再由 on_stop() 清理資源。
FrameworkLoop 讓框架負責等待指令與停止要求,不需要自己寫無限迴圈。
3. 準備可執行的模組
Section titled “3. 準備可執行的模組”CMake 專案負責加入框架並建置 Module:
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 的模組:
CONFIG_VINC_MODULE_helloModule=yfirst-module/vinc.conf · e165aed
在 repository 根目錄建置:
cmake -S first-module -B build/first-module-debug -G Ninja -DCMAKE_BUILD_TYPE=Debugcmake --build build/first-module-debug準備頁的 SDK 建置已經把模組複製到:
build/python/data/module/helloModule/helloModule.py目錄和檔名都使用種類名稱 helloModule。中央啟動時會掃描這個目錄。
修改 python/modules/ 裡的原始碼後,執行以下命令複製更新:
cmake --build build/python4. 從 Shell 啟動
Section titled “4. 從 Shell 啟動”在 PowerShell 開啟 Vinc Shell:
.\build\first-module-debug\Vinc.exe.\build\python\Vinc.exe --python .\.venv\Scripts\python.exe看到 VINC ready 後,在 Vinc Shell 輸入:
helloModule等待 hello started 和 Started hello。實際輸出可能帶有來源前綴,兩行的顯示順序也可能不同。
接著輸入 help,在運行中的模組列表找到 hello。
| 名稱 | 用途 |
|---|---|
helloModule |
ModuleType:輸入它來建立模組 |
hello |
實例名稱:用來識別已運行的模組 |
這個範例使用固定實例名稱。再次輸入 helloModule 會嘗試建立另一個 hello,原本的還在運行時就會被拒絕。
5. 正常關閉
Section titled “5. 正常關閉”exit看到 hello stopped 後,Vinc 會等待 Module 程序退出,再回到 PowerShell。
接著前往第一個跨程序訊息,讓兩個 Module 傳遞計數訊息。