Articles

Compiling a module from source

Compiling a module from source code

You should be aware that there are many different forms of source code and not all source code follows the conventions stated here. This tutorial gives a general idea about how to compile a module from source code for a majority of sources (as at 2010) and is by no means a comprehensive study of compiling from source code. You should first know the basics of modules and understand how they are created.

When you download source code it will generally come in the form of a filename.tar.gz or a filename.tar.bz2 compressed file. For the following example the source package has the name ImageMagick-6.5.2-5.tar.gz. It was download to a folder in the home directory called Downloads. Here is a list of the basic commands needed in order to make a quick and dirty module for your own use only. If you plan on making an official module that will be uploaded to the Porteus repository please follow the rules and guidelines below.  These are the general rules provided by the creator of Slax, Tomas M, and will be largely adopted for use in Porteus.

Quick and easy compiling for personal use:

Generally after you unpack a source file there is a text file inside called INSTALL or README. These usually contain the information needed to build the package.

Set the package variable

# PKG=ImageMagick-6.5.2.5
# TMP=/tmp/$PKG

Make a temp working directory

# mkdir  $TMP

Change directory to source file

# cd ~/Downloads

Unpack the tarball:

# tar zxvf ImageMagick-6.5.2-5.tar.gz
# tar xvjf  ImageMagick-6.5.2-5.tar.bz2

Enter into the source directory

# cd ImageMag*

Start the configure process

# ./configure --prefix=/usr

If you get an error message saying there is no configure file then you may need to install a package called autoconf and run it. The next step is to check that the Makefile contains the  variable DESTDIR. This is required in order to make a module. If it does not exist then you may get away with using the --prefix= switch in the configure process.

# grep "DESTDIR" Makefile

If you get no output from this then reconfigure using:

# ./configure --prefix=$TMP

Now start the make process

# make

Now create the package. The || means if the first command fails jump to the second.

# make install-strip DESTDIR=$TMP || make install DESTDIR=$TMP

Strip the binaries

# pushd $TMP
# find . | xargs file | grep "executable" | grep ELF | cut -f 1 -d : | xargs strip --strip-unneeded 2> /dev/null
# find . | xargs file | grep "shared object" | grep ELF | cut -f 1 -d : | xargs strip --strip-unneeded 2> /dev/null

If the package requires a menu entry you should now find a suitable icon image and place it in /tmp/ImageMagick-6.5.2.5/usr/share/applications

# mkdir -p $TMP/usr/share/pixmaps
# cp /path/to/imagemagik.ico $TMP/usr/share/pixmaps

Create the menu entry and desktop file now

# mkdir $TMP/usr/share/applications
# cat >> $TMP/usr/share/applications/imageMagick.desktop << EOF
[Desktop Entry]
Type=Application
Encoding=UTF-8
Name=ImageMagick
Icon=imagemagick.ico
Terminal=false
Categories=Graphics
EOF

Pop back out of the source directory and create module

# popd
# dir2xzm $TMP $PKG.xzm

If you compiled with the DESTDIR=$TMP switch then you will need to check that inside your $TMP directory you the normal filesystem folders such as /usr /bin. If not then adjust your dir2xzm command so that the base folder contains the correct folders. It may be something like: dir2xzm $TMP/$TMP /tmp/mymodule.xzm

That should be all you need to create your module. Remove your tmp directory and you are done. Please remember that this module should only be used for your own personal use. It may not run smoothly on someone else's system.

Module creation rules

Every Porteus module contains all files and directories with full path needed for the package to function. 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

Since Porteus is designed to be a lightweight portable system the size of your module should be as small as possible. 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.

If you compiled the module from source codes and you used a script then 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 as to 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/porteusbuilds/your_module_name.porteusbuild

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.

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

Never include any existing files from Porteus in your module, even if you modified them. In other words, your module should never 'overwrite' any existing file in Porteus, unless you have a sensible reason to do so. It can make your module incompatible with newer Porteus versions and it can cause problems with modules from other users. If you really have to overwrite a file in Porteus, (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

Here is a sample list of few files which should never be included in your module:

/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