user LoadingModules

Loading, Creating Additional Modules

---

Users can create additional modules, and following a few milk-specific conventions, link their functions to the milk CLI. Additional modules can be added to the existing build process or compiled separately and then loaded at runtime.

---

1. Overview

milk is organized in modules, each compiled as a shared object and loaded at runtime. Modules can be grouped in plugins.

1.1. Loading source code and compiling

While milk comes with its own set of modules, and others can be added at runtime. Modules that conform to milk specifications can be downloaded and added by following these steps:

# INDIVIDUAL MODULES
# execute these commands from the source root directory (for example ~./milk/)
# move to source subdir, where module directories are located
cd ./src
# Download a new module
git clone https://github.com/milk-org/NewModuleName

# or

# PLUGINS
cd ./plugins
# Download a new plugin (group of modules)
git clone https://github.com/milk-org/pluginName


# move to build directory
cd ../_build

# Compile
# any module within ./src will be compiled
cmake ..

# compile and install
sudo make install

Note that cmake will look for modules in both ./src and ./plugins, so there is no need to explicitely tell the compilation script that new module(s) have been added.

1.2. A simple example

milk includes an example module, which is not compiled or linked by default, to demonstrate how to write and add modules.

The example module is in directory 'src/milk_module_example' :

cd src/milk_module_example
ls
	CMakeLists.txt
	create_example_image.c
	create_example_image.h
	milk_module_example.c
	milk_module_example.h
	... additional .c and .h files

Check the source code (well documented) to see how modules are written. To compile :

cd _build
cmake ..
make
sudo make install

Lets run it :

# start milk
milk

# load module. Note that _s are removed from name
# milk> mload milkmoduleexample
# Alternatively, load module as "mex" (short for module example)
milk > mloadas milkmoduleexample mex

# check we have it
milk > m?

# run the test function, which creates an image
# note you can tab complete after typying "mex." to list functions
milk > mex.func1 im1 1.2

# check the image is in memory
milk > listim

2. Loading Modules

2.1. Automatic loading from ./milklib/ directory

Any shared object in the local ./milklib/ subdirectory of source code will be loaded upon startup.

Exzmple customization based on milklib content:

mkdir milklib
cd milklib
ln -s /usr/local/milk/lib/libmilkmoduleexample.so libmilkmoduleexample.so
cd ..

# Will load example module
milk

2.2. Loading module from within CLI with soload

Pre-compiled modules can be linked with the soload command within the CLI:

milk > soload <fullsoname>

The fullsoname is the shared object file name, path relative to current directory. For example "../mylib/myodule.so".

Provided that the module follows milk conventions, linking the module will add the corresponding functions to the CLI. This can be checked by probing the module functions:

milk > m?                # lists linked modules
milk > m? <ModuleName>   # lists CLI commands in the module

2.3. Linking module from within CLI with mload

By default, modules shared objects are installed in /usr/local/milk/lib, and are named libmilk<ModuleName>.so. With these assumptions satisfied, modules can be linked from within the CLI with the mload command:

milk > mload milk<ModuleName>

Alternatively, a short name can be specified

milk > mloadas <ModuleName> <shortname>

Module functions are called from the command line interface prompt:

milk > <shortname>.<functionname> <arguments...>

2.4. Using environment variable CLI_ADD_LIBS to link shared objects

Upon startup, milk will read the CLI_ADD_LIBS environment variable to link shared objects. For example:

CLI_ADD_LIBS="/usr/local/milk/lib/libMyFirstModule.so /usr/local/milk/lib/libMySecondModule.so" milk

will link modules MyFirstModule and MySecondModule.

@note Shared object names can be separated by space, semicolumn, or comma.

---

3. Writing Modules

3.1. Principles

Modules that are always loaded upon startup are explicitely listed in CLImain.c. Additional modules may be loaded using the C dlopen() command. The library should include a function initlib_<modulename> to be executed when the module is loaded. This function should register functions to the command line interface, as done for all other modules that are part of the distribution.

3.2. Adding new module to github

We assume here that you have created a module and you would like to push it to the main github package org (we assume here milk-org).

# First, create the repo in github, then run the following commands:
cd ./MyModuleName/
git init
git add .
git commit -m "First commit"
git remote add origin https://github.com/milk-org/MyModuleName

# Create repo on github, then ...
git push --set-upstream origin main
# Now we create dev branch
git checkout -b dev
git push --set-upstream origin dev

---