Plugin Packaging

There are as set of files that must exist within the repository of a plugin that are used to create the package for that plugin on the various supported platforms. The following documents what those files are and what they should contain.

Common files

  • Description - It should contain a brief description of the plugin and will be used as the description for the package that is created. Also make sure description of plugin must be in a single line as of now we do not have support multi lines yet.

  • Package - This is the main file where we define set of variables.

    • plugin_name - Name of the Plugin.

    • plugin_type - Type of the Plugin.

    • plugin_install_dirname - Installed Directory name.

    • plugin_package_name (Optional) - Name of the Package. If it is not given then the package name should be same as plugin name.

    • requirements - Runtime Architecture specific packages list and should have comma separated values without any space.

    Note

    For C-based plugins if a plugin requires some additional libraries to install with then set additional_libs variable inside Package file. And the value must be with following contract:

    additional_libs=”DIRECTORY_NAME:FILE_NAME” - in case of single additional_libs=”DIRECTORY_NAME:FILE_NAME1,DIRECTORY_NAME:FILE_NAME2” - in case of multiple use comma separated with both directory & file name

  • service_notification.version - It is only required if the plugin is a notification rule or notification delivery plugin. It contains the minimum version of the notification service which the plugin requires.

C based Plugins

  • VERSION - It contains the version number of the plugin and is used by the build process to include the version number within the code and also within the name of the package file created.

  • foglamp.version - It contains the minimum version number of FogLAMP required by the plugin.

  • requirements.sh (Optional) - It is used to install any additional libraries or other artifacts that are need to build the plugin. It takes the form of a shell script. This script, if it exists, will be run as a part of the process of building the plugin before the cmake command is issued in the build process.

  • extras_install.sh (Optional) - It is a shell script that is added to the package to allow for extra commands to be executed as part of the package installation. Not all plugins will require this file to be present and it can be omitted if there are no extra steps required on the installation.

Examples of filename along with content

  1. VERSION

$ cat VERSION
1.9.2

  1. foglamp.version

$ cat foglamp.version
foglamp_version>=1.9

  1. requirements.sh

$ cat requirements.sh
#!/usr/bin/env bash
which apt >/dev/null 2>&1
if [ $? -eq 0 ]; then
    sudo apt install -y libmodbus-dev
else
    which yum >/dev/null 2>&1
    if [ $? -eq 0 ]; then
        sudo yum -y install epel-release libmodbus libmodbus-devel
    fi
fi

  1. Description

$ cat Description
FogLAMP modbus plugin. Supports modbus RTU and modbus TCP.

  1. Package

$ cat Package
# A set of variables that define how we package this repository
#
plugin_name=modbus
plugin_type=south
plugin_install_dirname=ModbusC
plugin_package_name=foglamp-south-modbus
additional_libs="usr/local/lib:/usr/local/lib/libsmod.so*"

# Now build up the runtime requirements list. This has 3 components
#   1. Generic packages we depend on in all architectures and package managers
#   2. Architecture specific packages we depend on
#   3. Package manager specific packages we depend on
requirements="foglamp"

case "$arch" in
    x84_64)
        ;;
    armv7l)
        ;;
    aarch64)
        ;;
esac
case "$package_manager" in
    deb)
        requirements="${requirements},libmodbus-dev"
        ;;
esac

Note

If your package is not supported for a specific platform then you must exit with exitcode 1.

  1. service_notification.version

$ cat service_notification.version
service_notification_version>=1.9.2

Common Additional Libraries Package

Below are the packages which created a part of the process of building FogLAMP that are commonly used in plugins.

  • foglamp-mqtt which is a packaged version of the libpaho-mqtt library.

  • foglamp-gcp which is a packaged version of the libjwt and libjansson libraries.

  • foglamp-iec which is a packaged version of the IEC 60870 and IEC 61850 libraries.

  • foglamp-s2opcua which is a packaged version of libexpat and libs2opc libraries.

If your plugin depends on any of these libraries they should be added to the requirements variable in the Package file rather than adding them as additional_libs since the version of these is managed by the FogLAMP build and packaging process. Below is the example

requirements="foglamp,foglamp-s2opcua"

Python based Plugins

  • VERSION.{PLUGIN_TYPE}.{PLUGIN_NAME} - It contains the packaged version of the plugin and also the minimum foglamp version that the plugin requires.

  • install_notes.txt (Optional) - It is a simple text file that can be included if there are specific instructions required to be given during the installation of the plugin. These notes will be displayed at the end of the installation process for the package.

  • extras_install.sh (Optional) - It is a shell script that is added to the package to allow for extra commands to be executed as part of the package installation. Not all plugins will require this file to be present and it can be omitted if there are no extra steps required on the installation.

  • requirements-{PLUGIN_NAME}.txt (Optional) - It is a simple text file that can be included if there are pip dependencies required to be given during the installation of the plugin. Also make sure file should be placed inside python directory.

Examples of filename along with content

  1. Description

$ cat Description
FogLAMP South Sinusoid plugin

  1. Package

$ cat Package
# A set of variables that define how we package this repository
#
plugin_name=sinusoid
plugin_type=south
plugin_install_dirname=sinusoid

# Now build up the runtime requirements list. This has 3 components
#   1. Generic packages we depend on in all architectures and package managers
#   2. Architecture specific packages we depend on
#   3. Package manager specific packages we depend on
requirements="foglamp"

case "$arch" in
    x86_64)
        ;;
    armv7l)
        ;;
    aarch64)
        ;;
esac
case "$package_manager" in
    deb)
        ;;
esac

Note

If your package is not supported for a specific platform then you must exit with exitcode 1.

  1. VERSION.{PLUGIN_TYPE}.{PLUGIN_NAME}

$ cat VERSION.south.sinusoid
foglamp_south_sinusoid_version=1.9.2
foglamp_version>=1.9

  1. install_notes.txt

$ cat install_notes.txt
It is required to reboot the RPi, please do the following steps:
1) sudo reboot

  1. extras_install.sh

#!/usr/bin/env bash

os_name=$(grep -o '^NAME=.*' /etc/os-release | cut -f2 -d\" | sed 's/"//g')
os_version=$(grep -o '^VERSION_ID=.*' /etc/os-release | cut -f2 -d\" | sed 's/"//g')
echo "Platform is ${os_name}, Version: ${os_version}"
arch=`arch`
ID=$(cat /etc/os-release | grep -w ID | cut -f2 -d"=")
if [ ${ID} != "mendel" ]; then
case $os_name in
  *"Ubuntu"*)
    if [ ${arch} = "aarch64" ]; then
      python3 -m pip install --upgrade pip
    fi
    ;;

  esac
fi

  1. requirements-{PLUGIN_NAME}.txt

$ cat python/requirements-modbustcp.txt
pymodbus3==1.0.0

Building A Package

Firstly you need to clone the repository foglamp-pkg. Now do the following steps

$ cd plugins
$ ./make_deb -b <BRANCH_NAME> <REPOSITORY_NAME>

if everything goes well with above command then you can find your package inside archive directory.

$ ls archive