= Dyne Modules - pluggable software collections =

Dyne modules are simple .dyne files that you can drop into the dyne/modules directory and will be activated at the next boot: they can provide the user with new software, without any installation hassle.

Users can easily keep their modules across different machines, always finding back the software they need. Modules can also be used thru different dyne versions: just update the core dock and then drop in your good old modules.

We are still keeping things simple here, in the dyne tradition: just drop a file in a directory and that's it ;)

Now let's see how it works to build a module...
Create a new .dyne module

First of all make sure you dock your system on a harddisk, then create an SDK with a simple command:
{{{
[d:b] ~ # dynesdk mksdk
}}}
Have a look also to the DyneSdk documentation for more informations about these two simple steps.

Creating an SDK needs to be done only once, then your dock will be ready for development.

Now you will have an SDK directory in your harddisk. To see where that is, just type
{{{
[d:b] ~ # echo $DYNE_SYS_MNT/SDK
}}}
into an XTERM, you'll get printed out the full path to the SDK directory.

Next step is to create the module directory in the SDK, so let's choose our module name first: we are going to create the spaghetti module, with the commands
{{{
[d:b] ~ # mkdir -p $DYNE_SYS_MNT/SDK/modules/spaghetti
[d:b] ~ # mkdir $DYNE_SYS_MNT/SDK/modules/spaghetti/bin
[d:b] ~ # mkdir $DYNE_SYS_MNT/SDK/modules/spaghetti/lib
[d:b] ~ # touch $DYNE_SYS_MNT/SDK/modules/spaghetti/VERSION
}}}
basically we are just creating the bin and lib directories and a VERSION file inside the module, you can do that with any filebrowser or midnight commander if you like: c'mon, make yourself comfortable ;)

The last thing to do is to activate our spaghetti module, mounting it on /opt/spaghetti since all modules are activated in the /opt prefix. To do that we use again a DyneSdk command
{{{
[d:b] ~ # dynesdk mount
[d:b] ~ # source /boot/dynenv.modules
}}}
That's it! our new module is mounted in /opt and we have our PATHs configured accordingly.

You need to use dynesdk mount once after every boot, before starting development on your module.

Now you can compile the spaghetti software you like with ./configure --prefix=/opt/spaghetti, or editing the PREFIX in the Makefile in some cases - and don't forget the sauce! :)

To make it easier, when software is compiles with the usual ./configure && make && make install, you can use the dynemodconf command (followed by the module name) instead of calling ./configure directly: that will set the prefix and more environment correctly
{{{
[d:b] ~ # dynemodconf spaghetti --with-basilico
}}}
is a convenient configure line for the module in /opt/spaghetti

Once you are done with cook... ahem, compiling, then you can squash everything into a compressed .dyne module with
{{{
[d:b] ~ # dynesdk squash
}}}
and that's it! your new module will be found in $DYNE_SYS_MNT/dyne/SDK/cdrom/dyne/modules/spaghetti-1.0.dyne and ready to be included in the next CD ISO that you can pack with dynesdk mkiso.


== Filling VERSION information ==

Before releasing your module into the public, is a good idea to fill up some information about your creation so that people can contact you and visit software homepages. That's what the VERSION file is for, and it's format is very simple:
{{{
name            Spaghetti
desc            spaghetti pizza mandolino e presidente scemo
version         1.0
url             http://tuttifrutti.org/spaghetti
packager        The Crazy Cook http://tuttifrutti.org/~crazycook
}}}
Just use your favorite text editor to fill in these fields, leave a space or a tab between the field name and value and that's it.
Add entries to the menu

You can add entries and submenus for the user to start up your software. To do so create an applist file inside your module's etc directory, like for example /opt/spaghetti/etc/applist.

The applist file will list application binaries, descriptions and ways to start them up thru flags. Here it follows a description of the format, basically a | separated list:
{{{
# format:
# name | description | command | flags | web url | author

# flags:
# runonce | multi = if there should be only one instance running, or not
# terminal        = if it should run in a terminal
# manual          = if it's a manual entry
# root | user     = if it must be run as root or as user

# submenus can start and end with
# Begin | MySubmenu
# End | MySubmenu
}}}
for example:
{{{
Begin | SPAGHETTI

AglioeOlio | aglio olio e peperoncino | pasta --agliolio | | http://tuttifrutti.org | The Crazy Cook
Puttanesca | olive capperi e alici | pasta --puttan | | http://tuttifrutti.org | The Crazy Cook
Pesto | pesto alla genovese | pasta --pesto | | http://tuttifrutti.org | The Crazy Cook

End | SPAGHETTI
}}}

You can also have submenus, just use Begin and End once again inside. For a complete example see the system application list in /lib/dyne/dyne.applist.
Declaring global environment variables

In case your module needs to set environment variables (like custom paths and general settings for applications) you can simply declare them in a env file inside the etc directory. That file can contain declarations of environment variables, one per line, which will be exported in the running system, for example in our spaghetti module /opt/spaghetti/etc/env will look like:

{{{
KITCHEN_PATH=/opt/spaghetti/lib/kitchen
GLOBAL_TASTE=spicy
COOK_PROFILE=big_nose
}}}

== Including your own user settings ==

/!\ this feature is subject to security restrictions, so the user will be warned about your module and it will be possible to reject it

You can include your own home settings inside a module, so that they will override the default dyne:II user settings. This is useful when you want to change the window manager default configuration (with a new desktop image for example) or deliver pre-configured applications (with a .config file in home).

To do this you simply have to create a skel directory inside your module: all files that are included in it will be automatically copied into all users home directories and setted up to be adopted for users that are created in future.

== Including your own kernel modules ==

/!\ this feature is subject to security restrictions, so the user will be warned about your module and it will be possible to reject it

In your modules you can include any kernel module correctly compiled for the dyne:II kernel.

To do this you have to create a kernel directory inside your module: all kernel modules contained will be searched and loaded if found by the loadmod command, to be used instead of the standard modprobe.

In case the module is not naturally requested by your hardware configuration (not listed by the pcimodules command), you build your own detection or force loading of your module inside a module startup script (see below).
Running startup scripts for your own module
WARNING 	this feature is subject to security restrictions, so the user will be warned about your module and it will be possible to reject it

You can prepare a script inside your module to be executed every time your module is activated.

To do this you have to create a etc directory inside your module: all executable files included in the rc.* wildcard will be launched at startup, with the first $1 argument being the name of the module itself.

== In brief… ==

Here is resumed the file structure contained in modules:
VERSION 	required file 	contains information about the module and its sources
bin 	optional directory 	contains all binaries, automatically included in $PATH
lib 	optional directory 	contains all libraries, automatically included in $LD_LIBRARY_PATH
etc 	optional directory, security warn 	contains rc.* startup scripts executed at activation
skel 	optional directory, security warn 	contains all settings to be added to /home/user and /etc/skel
kernel 	optional directory, security warn 	contains kernel modules that can be loaded by loadmod