Skip to content

Your first running module

Documented releasev0.2.0/Stable main branch

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.

Prepare the tools in the build guide, then get the example:

Terminal window
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

Use the MSVC x64 developer environment on Windows. The module source is first-module/hello.cpp.

Run all PowerShell and build commands below from the open-vinc-examples repository root.

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") {
// 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.

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.

The CMake project adds the framework and builds the 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)
# 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:

first-module/vinc.conf
CONFIG_VINC_MODULE_helloModule=y

first-module/vinc.conf · e165aed

Build from the repository root:

Terminal window
cmake -S first-module -B build/first-module-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build/first-module-debug

Open Vinc Shell from PowerShell:

Terminal window
.\build\first-module-debug\Vinc.exe

Once you see VINC ready, enter this in Vinc Shell:

helloModule

Wait 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.

exit

Look 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.