Articles

[HOWTO] Understanding Module Creation and Manipulation: Two Case Studies

To view or contibute to the discussion about this tutorial, visit this thread on our forum.

If you're like me, then you learn and understand concepts better as you use and apply them, rather than simply reading about them. In this tutorial, we'll get our hands dirty with some real examples of Porteus modules, by creating them, extracting them, editing them, and generally messing around with them. Much of this will be with command line tools, which offer the best way to really get "under the hood", but you can just as easily perform many of these steps from the GUI, using the right-click menus in your file manager. Please read the doc on our main site, "What are Porteus Modules" before proceeding.

Note: this tutorial was written for the 32-bit edition of Porteus (V1.0). If you are using the 64-bit edition, the same commands apply, but you should use 64-bit packages, or the modules won't work. Pick any package you like, but if it requires dependencies, your program won't run in our first example.

Conventions: As you read through this document, perform any actions inside codeblocks in a console. For example:

cd ~/Downloads

means you should enter the text, exactly as it appears, in your console. Do not execute text that is preceded by a # sign, these are comments to help describe the commands you are being asked to perform.

Case Number 1:

The first thing we're going to do is download a program that does not require any dependencies, and convert it into a module, then extract it to a folder, tinker with the files, and then convert that folder back to a module.

Ok, we're going to start off with obtaining a slackware package (rpms or debs would also suffice and can be converted to Porteus modules with deb2xzm or rpm2xzm, but since Porteus is slackware based, let's start with a slackware package):

Navigate your browser to:

http://pkgs.org/slackware-13.37/slacky-i486/aterm-1.0.1-i486-6sl.txz.html

scroll down on that page a bit, and you'll see a list of files and directories:

/install/
/install/slack-desc
/install/slack-required
/usr/
/usr/bin/
/usr/bin/aterm
/usr/doc/
/usr/doc/aterm-1.0.1/
/usr/doc/aterm-1.0.1/ChangeLog
/usr/doc/aterm-1.0.1/INSTALL
/usr/doc/aterm-1.0.1/README.configure
/usr/doc/aterm-1.0.1/aterm.SlackBuild
/usr/doc/aterm-1.0.1/slack-desc
/usr/man/
/usr/man/man1/
/usr/man/man1/aterm.1.gz

These are all of the files that are contained in the aterm slackware package (slackware packages have the .txz file extension). All of these files will be incorporated into our module in the same directory structure, with the exception of the files in /install/. The files in /install/ are used by the install or conversion scripts to create symlinks and other files that are not contained in the slackware package, but should be included in our module.

Now, scroll back up and click on "select mirror", then "binary package" to download this file to your Desktop. I'm logged in as root (you should log in as root as well, or use su for the command line apps), and I've saved it to: /root/Downloads/aterm-1.0.1-i486-6sl.txz

Open up a terminal. The first thing we're going to do is set up a clean workspace, to keep from cluttering up our system:

mkdir -p ~/temp/modwork/
#creates nested folders inside our home directory (i.e., /root/ or /home/guest/)

Now, let's move our slack package to our workspace and convert it into a module:

mv ~/Downloads/ ~/temp/modwork/
cd ~/temp/modwork/
txz2xzm aterm-1.0.1-i486-6sl.txz aterm-1.0.1-i486-6sl.xzm

Use tab autocompletion for the package name (i.e., enter mv ~/Downloads/aterm, then press TAB and the rest of the filename will autocomplete), and the module name can be anything you want, but it's easier to keep your modules oganized if you use a specific name that includes the version number.

Now, you have an .xzm file next to your .txz file in ~/temp/modwork/. This module is ready to use, as it has no dependencies. You can't activate a module from within your live filesystem --if you try to activate it, the system will relocate it to /mnt/live/memory/modules and then activate it (and it will disappear from your 'modwork' directory). Let's copy this to some place permanent instead:

cp aterm-1.0.1-i486-6sl.xzm /mnt/sdXN/porteus/optional
#where sdXN is the device and partition on which porteus is installed

Now, let's activate that module:

activate /mnt/sdXN/porteus/optional/aterm-1.0.1-i486-6sl.xzm

And start it up:

aterm

Now, you have another console program installed in Porteus, which can be activated by double clicking the module in /mnt/sdXN/porteus/optional, or you can move it to /mnt/sdXN/porteus/modules, and it will be automatically loaded into your system every time you boot up.

Let's say you wanted to see which files are inside your module. This can be accomplished in a few ways:

First, using 'lsxzm':

lsxzm aterm-1.0.1-i486-6sl.xzm
#this will list all of the files in the module

Also, you can use 'mloop':

mloop aterm-1.0.1-i486-6sl.xzm

this will mount the module on a loop, and the files will be available inside the /mnt/loop/ directory. You can then copy some or all of them to another location to edit them and compress them into a new module if you choose.

Finally, if the module is active, you can view the files in read-only format at /mnt/live/memory/images/aterm-1.0.1-i486-6sl.xzm/

Poke around using one of these methods, and you will see that the module contains the same files as the slackware package that we used to create the module (with the exception of the files in the packages /install directory, and the addition of symlinks, etc., created by the scripts in /install).

Now, perhaps you want to add or modify a file inside the module. You would need to extract the module, add or modify the file, and then compress it again:

cd ~/temp/modwork/
#we're going back to the module in our clean workspace to mess around with it
#because if we extract a module on a FAT or NTFS file system
#i.e. your /porteus/optional folder, if your drive is FAT or NTFS,
#all of the symlinks and file permissions will be lost.
mkdir aterm
xzm2dir aterm-1.0.1-i486-6sl.xzm aterm
#this extracts the xzm module to the 'aterm' directory you just created
mkdir -p aterm/usr/share/applications
cp /usr/share/applications/psinfo.desktop aterm/usr/share/applications/aterm.desktop
mcedit aterm/usr/share/applications/aterm.desktop
#copy an existing a desktop entry file and then add your text to create a menu entry for aterm
#change the Exec= line to Exec=aterm which is the file that will be executed
#change the name to aterm and change the description
dir2xzm aterm aterm-1.0.1-i486-modified.xzm
#compresses the files inside the aterm directory into a new module
# Now after activation you should have a menu entry for aterm which you can click on

By now, you should understand the basics of how to create convert, mount, extract and modify a module. If not, keep working with it. You can create a module out of any directory, so you can just create a handful of files inside a directory and start making modules, extracting them, etc.

Case No. 2

To learn a few more useful tools, let's take a look at a package that depends on another package which is not included with Porteus by default, and look at how that module can be constructed and manipulated:

This time, we're going to use slackyd, a command line package manager to obtain the slackware packages.

First, update slackyd:

slackyd -u

Now, we'll download the package without installing it (using the -g switch):

slackyd -g xpdf

Press y to download the package.

Now, let's go to where slackyd stores downloaded packages: /var/slackyd

cd /var/slackyd
#now, move the file to your workspace
mv xpdf-3.02pl6-i486-4.txz ~/temp/modwork/

We want to find out what dependencies this package has, so we're going to change directories again, install xpdf and then use slackyd to find the dependencies:

cd ~/temp/modwork/
installpkg xpdf-3.02pl6-i486-4.txz
#installs the package to the live filesystem; this install will not survive reboot unless you are
#saving your changes with the changes=cheatcode.
slackyd -d

The -d switch searches your existing system for missing dependencies. This will take a while, and will return required packages that are needed for xpdf, as well as any other packages. This is a portion of the output from that command:

Found 4 missing dependencies:
libruby.so.1.8 required by:
--> Package: kdebindings-3.5.12-i486-1 (/usr/bin/qtrubyinit)
--> Package: kdebindings-3.5.12-i486-1 (/usr/bin/krubyinit)
--> Package: koffice-3.5.12-i486-1 (/usr/lib/kde3/krossruby.so)
libnotify.so.1 required by:
--> Package: mozilla-firefox-4.0.1-i486-1 (/usr/lib/firefox-4.0.1/components/libmozgnome.so)
libQtCore.so.4 required by:
--> Package: wpa_supplicant-0.7.3-i486-3 (/usr/bin/wpa_gui)
libXm.so.2 required by:
--> Package: xpdf-3.02pl6-i486-4 (/usr/bin/xpdf)

You can see that libXm.so.2 is required by xpdf, and all of the other libraries are required by other programs in Porteus. Slackyd will prompt you to download packages for all of the missing dependencies it finds, so press Y to download lesstif (of which libXm is a part), but say N to decline downloading all of the others.

Now, we'll move lesstif to our workspace, install it and check again for missing dependencies:

mv /var/slackyd/lesstif-0.95.2-i486-1.txz ~/temp/modwork/
cd ~/temp/modwork/
#just in case you left it!
installpkg lesstif-0.95.2-i486-1.txz
slackyd -d

This time through, neither xpdf nor lesstif have any required dependencies, so we should have everything we need.

Since both packages are installed in our live system, let's check if xpdf works:

xpdf

And, indeed, it should.

If you're saving your changes, you should probably remove xpdf and lesstif in order to keep things tidy:

removepkg xpdf-3.02pl6-i486-4
removepkg lesstif-0.95.2-i486-1

Note that installpkg and removepkg are slackware tools for installing and removing slackware txz packages.

Now, you could use txz2xzm to convert each of these packages into a module, and then use Porteus-Module-Tools to merge those modules together. However, it's easier to install both packages to a fakeroot directory, and then turn that directory into a module:

#we're still in ~/temp/modwork/, cd here if you've left
mkdir xpdf
installpkg -root ~/temp/modwork/xpdf *.txz
#the -root switch specifies the fake root directory for the install, and *.txz applies the command to any file in the current directory that ends in .txz
#now, let's check to see if both packages are installed:
cd xpdf/var/log/packages
#note that you should NOT use a leading / before xpdf
ls
#you can see that both the xpdf and lesstif packages are installed here
cat * | less
#to see all of the files that came with the packages

Now, let's turn this into a module:

cd ~/temp/modwork/
dir2xzm xpdf xpdf-3.02pl6-i486+deps.xzm
#copy it to your /porteus/optional folder
cp xpdf-3.02pl6-i486+deps.xzm /mnt/sdXN/porteus/optional/

Now, you have a module with two slackware packages inside it, and whenever you activate it, everything you need for xpdf to run will be injected into the live filesystem.