configurator/DESIGN.md

Version: 1 Status: DRAFT

Status

While this tutorial will explain you how to start coding your own module, it won't be prepared for packaging...

TODO : Add a 'build' script example that make the whole thing ready for packaging.

Main design

Coding your own CLI module

1. Create a directory where you'll put the CLI module code and cd into it.
   Example :

mkdir -p ~/Documents/my_armbian_module
cd ~/Documents/my_armbian_module

2. Create a file named DESC and write a short description for this module.

echo "Best module ever" > DESC

3. Add a module file and ensure it is executable.
   This file will be the one executed by the configurator when running your module.

echo '#!/bin/bash' > module
echo "echo 'I told you, best module ever \!'" >> module
chmod +x module

4. Create the directory /usr/share/armbian/configurator/modules/${module_name}/cli
   Example, if your module is named 'my_module' :

module_name=my_module
sudo mkdir -p "/usr/share/armbian/configurator/modules/${module_name}"

5. Link the DESC file to /usr/share/armbian/configurator/modules/${module_name}/DESC

module_name=my_module
sudo ln -s "${PWD}/DESC" "/usr/share/armbian/configurator/modules/${module_name}/DESC"

6. Link the directory itself to /usr/share/armbian/configurator/modules/${module_name}/cli

module_name=my_module
sudo ln -s "${PWD}" "/usr/share/armbian/configurator/modules/${module_name}/cli"

Now, the module is recognized by the configurator.

Launch the configurator without arguments to see your module in the list.
Launch the configurator with the name of your module to launch it :

module_name=my_module
configurator ${module_name}

I told you, best module ever !

Adding a GUI (X11/Wayland) to your module

1. Create a directory where you'll put the GUI executable of your module.
2. Make sure your GUI executable name is named module
3. Link it to /usr/share/armbian/configurator/modules/${module_name}/gui

You're done

Adding a translation to the short description

To add a translation for a module description, add a DESC.{locale} file to /usr/share/armbian/configurator/modules/${module_name}/

Precise locales are sampled before global ones, however avoid using precise locales names when you can.

Example

Let's say you want to add a French translation for a module description.

French locales start with fr.
French locale for people living in France specifically is : fr_FR.
French locale for people living in Canada specifically is : fr_CA.

So, if you want to add a french translation, add either a DESC.fr or DESC.fr_FR file.

If you add both DESC.fr_FR and DESC.fr, the system will use :

• DESC.fr_FR for people using the fr_FR locale.
• DESC.fr for people using fr_CA locale.

If you only add DESC.fr, the system will use :

• DESC.fr for people using the fr_FR locale.
• DESC.fr for people using fr_CA locale.

if you only add DESC.fr_FR, the system will use :

• DESC.fr_FR for people using the fr_FR locale.
• DESC (default english version) for people using the fr_CA locale.

Prepare for packaging

In order to prepare the module for packaging, see PACKAGING.md.