Your first running module
Start with one Module that prints hello started on startup and hello stopped during normal shutdown. Choose your programming language below; the Shell operations are the same.
1. Prepare the project
Section titled “1. Prepare the project”Prepare the tools in the build guide, then get the example:
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/webUse the MSVC x64 developer environment on Windows. The module source is first-module/hello.cpp.
Complete Prepare the Python examples first. Reuse that project and environment.
The module source is python/modules/helloModule/helloModule.py.
Run all PowerShell and build commands below from the open-vinc-examples repository root.
2. Write the module
Section titled “2. Write the module”#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") { // Set the instance name used by Shell commands. }
vinc::Result<void> on_start(const std::vector<std::string>&) override { // Startup hook: the framework calls this after the instance name is approved. // Set up this module here; returning {} means initialization succeeded. std::cout << "hello started" << std::endl; return {}; }
vinc::Result<std::int32_t> module_interface(std::vector<std::string>) override { // Command hook: called when Shell addresses this instance. // Return 0 for success or 1 to report a command error. // This first example does not provide application commands. return 1; }
vinc::Result<void> on_stop() override { // Shutdown hook: called during normal shutdown to clean up this module. std::cout << "hello stopped" << std::endl; return {}; }};
// Register the type name Shell uses to create this module.REGISTER_MODULE(HelloModule, "helloModule")first-module/hello.cpp · e165aed
HelloModule inherits BaseModule. The constructor proposes the instance name hello, and REGISTER_MODULE registers the type helloModule.
The lifecycle hooks return {} for success. This example provides no application commands, so module_interface() returns 1.
import vinc
class Module(vinc.BaseModule, mode=vinc.RunMode.FrameworkLoop): def on_name(self, args): # Naming hook: return the instance name used to address this module in Shell. # Create publishers and subscriptions later, in on_start. return "hello"
def on_start(self, args): # Startup hook: the framework calls this after the instance name is approved. # Set up this module here; returning None means initialization succeeded. print("hello started")
def on_stop(self): # Shutdown hook: called during normal shutdown to clean up this module. print("hello stopped")python/modules/helloModule/helloModule.py · e165aed
Export a class named Module that inherits vinc.BaseModule. on_name() returns the instance name hello.
Lifecycle hooks return None on success; reaching the end of a function does that automatically.
The framework calls on_start() when the module is ready to initialize. Returning from it leaves the Module running. On normal shutdown, on_stop() handles cleanup.
FrameworkLoop lets the framework wait for commands and stop requests. You do not need to write an infinite loop.
3. Prepare the runnable module
Section titled “3. Prepare the runnable module”The CMake project adds the framework and builds the 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)
# Keep the tutorial's executable path stable. Tcl deployment follows this target.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() builds hello.cpp and registers helloModule. Its MODULE_TYPE_NAME must match the string in REGISTER_MODULE.
vinc_add_app() creates the central App. first-module/vinc.conf selects the module included in it:
CONFIG_VINC_MODULE_helloModule=yfirst-module/vinc.conf · e165aed
Build from the repository root:
cmake -S first-module -B build/first-module-debug -G Ninja -DCMAKE_BUILD_TYPE=Debugcmake --build build/first-module-debugThe SDK build from the preparation page already copies the module to:
build/python/data/module/helloModule/helloModule.pyThe directory and filename both use the type name helloModule. Vinc scans this directory when the central application starts.
After editing the source under python/modules/, copy the update with:
cmake --build build/python4. Start from Shell
Section titled “4. Start from Shell”Open Vinc Shell from PowerShell:
.\build\first-module-debug\Vinc.exe.\build\python\Vinc.exe --python .\.venv\Scripts\python.exeOnce you see VINC ready, enter this in Vinc Shell:
helloModuleWait for hello started and Started hello. Output may include source prefixes, and these lines may appear in either order.
Then enter help to find hello in the running module list.
| Name | Use |
|---|---|
helloModule |
ModuleType: enter it to create a module |
hello |
Instance name: identifies the running module |
This example uses a fixed instance name. Entering helloModule again tries to create another hello, which is rejected while the first is running.
5. Shut down cleanly
Section titled “5. Shut down cleanly”exitLook for hello stopped. Vinc waits for the Module process to exit, then returns to PowerShell.
Continue with Your first cross-process message to send a counter between two modules.