How to create Slax modules the right way

Slax modules may be created any way you like, as long as you are the only one who use them. But if you wish to share your modules with other users, you have to follow several rules described in this document. The rules are designed to benefit the end user at the first place; so if you disobey them, your module will never be accepted for the official Slax repository.

Technical overview

Slax module is a compressed squashfs filesystem with .lzm extension. The module is created by a mksquashfs utility and may be extracted (unpacked) using unsquashfs. Both these tools must be patched (modified) to support LZMA compression algorithm. These utilities are already included in Slax.

Every Slax module contains all files and directories with full path. For example, a module with bash (the binary and some man pages) would look like this:

/bin/
/bin/bash
/usr/
/usr/man/
/usr/man/man1/
/usr/man/man1/bash.1

The rules

1) All the directories in your module have to be accessible for a regular user. Reset all directory permissions to 755 (drwxr-xr-x), unless there is a sensible reason to use different permissions for a particular directory.

find ./ -type d | xargs chmod -v 755;

2) Keep the size of your module small. Uncompress all archives which may be safely left uncompressed (for example man pages, because LZMA will compress them far better), delete all files which are not needed to run the software (for example unneeded documentation, unused sounds, png/jpg images, unneeded translations from /usr/share/locale) and strip all unneeded symbols from binaries.

find ./usr/man/ -type l -name "*.gz" | xargs -r gunzip -f
find ./usr/man/ ! -type l -name "*.gz" | xargs -r gunzip
find . | xargs file | grep ELF | cut -f 1 -d : | xargs strip --strip-unneeded

3) If you compiled the module from source codes, provide the build script, which is used to create the module. The build script must handle the whole module creation. Any manual work (copying / deleting files, etc) aside the build script is not allowed. The script serves as a documentation how to create your module; moreover it makes it easy to take over your module in the case you stop updating it. Copy the build script to your module to:

/usr/src/slaxbuilds/your_module_name.slaxbuild

4) When you compile the software, make sure to use correct cflags and parameters. The following is recommended in order to use i486 instructions (which provides the best backward compatibility), but tune the performance of the code as if the target architecture was i686. In Slax, you can run 'configure-for-slax' as a shortcut. It does the same:

CFLAGS="-O3 -march=i486 -mtune=i686" ./configure --prefix=/usr --build=i486-Slackware-linux

5) Never include any existing files from Slax in your module, even if you modified them. In other words, your module should never 'overwrite' any existing file in Slax, unless you have a sensible reason to do so. It can make your module incompatible with newer Slax versions and it can cause problems with modules from other users. If you really have to overwrite a file in Slax, (for example in order to append a new path to /etc/ld.so.conf), write a startup script instead, which will modify (update) the particular file, instead of overwriting it by your module.

Example startup script to delete one line from ld.so.conf and add a new one at the end:

#!/bin/bash
sed -i -r '\;/usr/local/lib;d' /etc/ld.so.conf
echo '/opt/kde/lib' >> /etc/ld.so.conf

/etc/init.d
/etc/rc.d/rc.S
/etc/rc.d/rc.M
/etc/rc.d/rc.K
/etc/rc.d/rc.local
/lib/modules/2.6.x/modules.dep
/lib/modules/2.6.x/modules.alias
/etc/ld.so.conf
/etc/ld.so.cache
/etc/passwd
/etc/group
/etc/shadow

6) If you need to execute something during module activation, or system startup or shutdown, use the sysvinit-style directories. The best practice is to make an universal script in /etc/rc.d/init.d/ directory, which will understand the 'start' and 'stop' arguments. All the scripts in that directory will be started with 'start' argument during module activation, and with 'stop' argument during the deactivation. Optionally, you may place symbolic links starting with uppercase S (to start) and uppercase K (to kill) in the sysvinit directories corresponding to your desired runlevel, for example /etc/rc.d/rc3.d/. Every time a runlevel is changed, Slax executes all scripts starting with K from the previous runlevel directory (to kill), and all scripts starting with S from the current runlevel directory.

In the following example, Slax will execute 'apache.sh start' in runlevel 3 (which means during system startup) and it will execute 'apache.sh stop' in runlevel 0 or 6 (that means, when Slax is going to shutdown or reboot).

# Sample universal script: /etc/rc.d/init.d/apache.sh

#!/bin/bash
if [ "$1" = "start" ]; then
   echo "start apache @ startup"
   ... start apache here ...
fi
if [ "$1" = "stop" ]; then
   echo "stop all apache @ shutdown"
   ... stop apache processes here ...
fi

# When your universal script is created, add the following symbolic links:

ln -s ../init.d/apache.sh /etc/rc.d/rc3.d/S-apache
ln -s ../init.d/apache.sh /etc/rc.d/rc0.d/K-apache
ln -s ../init.d/apache.sh /etc/rc.d/rc6.d/K-apache

7) If your software can be started in GUI (for example in KDE, XFCE, etc.), you must include an icon and add a menu entry file to your module, so the user can start the application easily by finding it in his menu. To add a menu entry, simply create two files:

/usr/share/applications/your-application.desktop
/usr/share/pixmaps/your-applications-icon.png

[Desktop Entry]
Encoding=UTF-8
Exec=firefox %u
Icon=/usr/share/pixmaps/firefox.png
Type=Application
Categories=Application;Network;
Name=Firefox
Name[cs]=Firefox
GenericName=Web Browser
GenericName[cs]=Webovy prohlizec
MimeType=text/html
X-KDE-StartupNotify=true

8) When the software in your module is started, it should run straight away without any unnecessary dialogs, tips of the day or licence agreements. Keep in mind that if the user included your module on a readonly CD, he has no way to remember the settings (to disable tips, agree licences, and so on), so the module shouldn't bother him every startup.

9) Dependencies of your module must be as sparse as possible. That means, the less other modules are required by your module, the better, but also remember to keep the size of your module as small as possible. For example, If your module can run safely without python, then make sure to delete all python scripts from your module, instead of includin python in it.

If your module requires some libraries, which are practically useful only for your module, then include the libraries directly in your module and do not upload them separately. As an example, XFCE requires a lot of xfcelib* libraries, while those are practically unneeded by anything else. So, include them in XFCE module.

On the other hand, if your module needs some libraries or programs, which can be useful for other modules as well, never include it in your module, but upload it separately. For example, python binaries should be always uploaded separately and never included in any module.

Upload your modules

When your module follows the rules, you can share it with others. The official module repository should be as helpful as possible for the end users; for that reason, it is very important that every module has a nice icon, a screenshot which represents how the software looks like if you run it in fresh Slax (using the default KDE style and window decoration), and it's necessary to provide a meaningful description, which helps people understand more about the module.

Some libraries or programs do not show any user interface, in that cases the screenshot is not needed. But a nice, truecolor icon must be provided. Modules without icon are rarely accepted. If you think that it's not possible to find an icon for your module, then think again. It doesn't need to be unique for your module, but the user should be able to distinguish between a Text editor and an Email client just by a quick look at the icons.

The title should not contain any unneeded dashes and underscores, simply put there the software name, followed by version number. The following is correct: vim 7.1. The following is not correct: vim_7.1-112-i486-15

Description must be long enough in order to make the category overview look nice, but should contain only useful information for the user. It is meant to describe the module for someone who has absolutely no idea what is inside and what is it useful for. No bogus texts, no links, no grammar or spelling mistakes, no exclamation marks and no changelogs. Recommended length is 40 words or more.