!!! HOW-TO Contribute Packages For Vector Linux
This how-to shows how you can use vecteloper kit to construct
a "source tarball", compiling, and then contributing it for Vector Linux package.
----
!! REQUIREMENTS
Assume that the lead developer has build the VL-5.0rc1.
You want to contribute the packages for VL-5.0rc2, and soon.
You need to:
# Install the VL-5.0rc1 (or VL-Dynamite-5.0).
# Install the vecteloper package (This is not a standard package, so it may not be in the official distro).
# It is recomended that you work from console with midnight commander.
----
!! QUICK HOW-TO
Suppose that you want to contribute a GTK based package named gxyz-1.0.
Firstly of course, go to their homepage and download the source tarball
(either gxyz-1.0.tar.gz or gxyz-1.0.tar.bz2). If possible,
choose tar.bz2 since it has better compression. Then ... let's do it.
!1. Find the correct tarball tree.
After installing the vecteloper package, go to /home/vectelopment directory.
You will find these directories:
* doc : some documentations
* RELEASE : output directory that is supposed to be put online on the FTP site.
* pkg : output directory for putting the built packages. This is a symlink to RELEASE/packages
* tgz : input directory for putting prebuilt packages
* tar : input directory for putting the tarball (source code)
* src : temporary directory for extracting and compiling the tarball
* tmp : temporary directory for anything else
You should go to tar directory, since that is where you put the tarball.
It is organized as described here PackageOrganisation.
So, you will find directory structure like these:
* cli : console based packages
* x11 : x11 based packages
* x11/sdl : sdl based packages (games)
* x11/gtk : gtk based packages
* x11/gtk2 : gtk2 based packages
* x11/qt : qt based packages
* x11/qt/kde : kde based packages
Since your package is a gtk based, go to /x11/gtk directory.
You will find these directories:
* BASE : base libraries, like glib, atk, pango, gtk. Only lead developer does these.
* CORE : essential and customisation packages like icewm, dfm, rox-filer.
These packages are the ones that make this distro a Vector Linux !
* DEV : development like vdkbuilder, anjunta (gnome), kdevelopt (kde).
* EDU : edutainment like galculator, geg, bibblestudy.
* ENT : entertainment like gtkboard, gtans.
* GR : graphics like the Gimp, dia, sketch.
* MM : multimedia like xmms, gxine, mplayer, alsaplayer.
* NET : network and internet like firefox, dillo, gftp, xchat, sylphed.
* OFT : office like Open Office, gnumeric, abiword.
* SET : setting (usually for the WM) like icecc, fluxconf, menueditor, gamix.
* SYS : system and its configurator like samba, cups.
* UTIL : utilities like emelfm, xcdroast, sane.
So, select a category that is the best for your contributed package.
Let's assume you select the util directory.
!2. Make a new tarball directory
Go to the category directory (x11/gtk/UTIL), then create a new directory for your package
(we call this a tarball directory). The name should match your package, in this case
x11/gtk/UTIL/gxyz.
!3. Put the source tarball
Copy the gxyz-1.0.tar.bz2 into that tarball directory.
If your package follow standard GNU automake convention, this is all you have to do.
!4. Compile it
Just go to the /home/vectelopment directory, call
./bc tar/x11/gtk/gxyc
Thats it !
Find out the result on RELEASE/packages/x11/gtk/UTIL directory.
!5. Upload your contribution
You need to upload these to the VL FTP site.
* The tarball directory tar/x11/gtk/UTIL/gxyz (all under it)
* The compiled packages (optional) under pkg/gtk/util. There should be 3 files
including the gxyz-1.0-i586-vl?.tgz, gxyz-1.0-i586-vl?.txt, and gxyz-1.0-i586-vl?.tgz.md5.
Why contribute the tarball ? Because
# The GNU GPL requires us to publish the source that is used to build our distro. Without that, actually we violates the license.
# The lead developer can easily recompile the tarballs. For example, if he want a i686 based distro instead of i586.
So ... that's it. I hope it is easy enough and thank you very much for your contribution.
----
!! ADVANCED HOW-TO
Ok, this is to make your package perfect. To customize the package, you may add various
files beside the tarball itself, under the tarball directory (e.g. x11/gtk/UTIL/gxyz).
!1. The description-pak
There are three files that will be included into the package named
description-pak, install-pak and dependency-pak. Lets talk about the description-pak first.
The description-pak should contains brief information for the package.
This is the standard example:
gxyz (A GTK based xyz utility)
The gxy is a program that do bla bla bla.
Homepage: www.gxyz.org
License : GNU GPL
Author: the-hacker
Author: the-hacker2
First line must be the package name followed by short description (about 5 words)
inside the bracket. Slackware's pkgtool and Vector's vecpkg use this line to display
the short description.
The second paragraph is a longer explanations. It must be no more than 50 characters wide.
The number of rows is relaxed, but better keep it no more than 8.
The last three lines are obvious. Please complete that lines to regard the authors.
To make the descrition, I usually use mc to browse through the tarball (*.tar.bz2 or *.tar.gz),
copy the README and AUTHORS file to the tarball_dir, then edit it.
!2. The install-pak
The file install-pak will be included into the package as an installation script
(/install/doinstall). For example, if the package gxyz needs to make a configuration
you may add
# This file is called after the package is extracted
# It has a predefined variabel called PREFIX
# example, add prefix to PATH
PROFILE=etc/profile.d/gxyz.sh
echo '#!/bin/sh' > $PROFILE
echo 'if ! which gxyz &> /dev/null; then' > $PROFILE
echo ' export PREFIX="$PREFIX:'$PREFIX'"' > $PROFILE
echo 'fi' > $PROFILE
Normally, you don't need to create this file.
The vectelopment system automatically make one to adds symlinks creation,
and call ldconfig if there is any shared object file.
If that all the package needs, don't bother to add them by your self.
!3. The dependency-pak
This is a new feature to allow dependency information.
The good news is, vectelopment can generate auto dependency based on
shared library tracking system. So you may skip to make this file at all.
However, vectelopment cannot track inter application dependency.
For example, there is no way to track that firefox needs xpdf,
since it is called through application level (not through shared object).
Thus, for the firefox you have to make file dependency-pak like this
# dependency for firefox with plugins
mozplugger
xpdf
xmms
mplayer
!4. The settings.sh
Now, we are going to talk about the configuration files
that affect the compilation of the package. There are three files named
settings.sh, compile.sh and install.sh. Before we begin,
here is a brief explanation about compilation process.
From a tarball, the standard compilation is like these
tar -xjf gxyz-1.0.tar.bz2 ## extract tarball
cd gxyz-1.0 ## go to the source directory
./configure --options ## set tarball configuration
make ## compile it
checkinstall ## make the tgz package and install it
The vecteloper kit does this for you automatically,
without any more settings for most of the tarballs.
However, some anomaly tarballs need special treatments.
The settings.sh file is for changing the package configuration and properties.
The possible settings are:
#!/bin/sh
PREFIX=/usr/local # override default prefix (/usr)
CONFIGURE="..." # options for ./configure (--prefix=$PREFIX)
PNAME=gxyz2 # package name (the tarbal directory name)
PVERSION=1.0 # package version (determined from the tarball)
PARCH=noarch # package architecture (i586)
PRELEASE=1 # package release (vl5)
!4. The compile.sh
This file is for overriding the default configuration and compile steps
(./configure then make). For example, if your tarball does not need to be configured,
simply make this compile.sh
#!/bin/sh
make
Another example, some tarballs do not use ./configure, but need prefix for proper compilation like this.
#!/bin/sh
make prefix=$PREFIX
I'm sorry, but I cannot tell you the exact guide.
Mostly, you have to read the tarball's Makefile to find out the correct compile.sh.
!5. The install.sh
Actually, vldistro making the distro by installing the compiled tarball
into a temporary directory. This can be achieved by using the command:
make install DESTDIR=/the_temp_dir
Unfortunatelly, that method works for the GNU automake complian tarball only.
Some tarballs do not have DESTDIR capability.
So ... you have to read the Makefile, then create the install.sh.
Here are some examples:
#!/bin/sh
# install.sh that silently know DESTDIR
make install
#!/bin/sh
# install.sh that understand prefix but not DESTDIR
make install prefix=${DESTDIR}${PREFIX}
From my experience, about 20% tarballs need custom compile.sh or install.sh.
!6. The /custom directory
This directory is for putting some files that will be included into the package,
starting from root (/) directory. Usually, for files that go to /etc, /bin, or /sbin.
Just put the as is, for example, under x11/gtk/UTIL/gxyz you can have:
custom/etc/profile.d/gxyz.sh
custom/etc/gxyz.ini
!7. The /custom-prefix directory.
This is the same as /custom directory, but the files will go under the $PREFIX of the package.
For example, if gxyz has prefix=/usr/X11R6, then you may put this file
custom-prefix/share/gxyz/gxyz.ini
It will be installed as /usr/X11R6/share/gxyz/gxyz.ini.
It is possible to make a package that contains only the /custom and /custom-prefix directories, without the tarball.
For this, you must make settings.sh
#!/bin/sh
PNAME=mycustom # package name (determined from the tarbal directory)
PVERSION=1.0 # package version (MUST !)
PARCH=noarch # package architecture (i586)
Packages like vasm, icewm-custom, fluxbox-custom are done this way.
----
!! COMPILING MULTIPLE PACKAGES
If you have many packages, better make a compilation script.
The files you should take a look are config.core, config.pack and v5-pack1.
!1. Edit compilation configuration
Now go back to /home/vectelopment directory, edit the config.pack file.
Change this
INSTALL_PKG="yes"
That will make your newly created package to be installed.
If "no", it will be compiled to the pkg directory, but not installed.
!2. Make compilation script
Create a new script called v5-pack2 (copy it from v5-pack1).
The content is
#!/bin/sh
. config.vl ## include distro (VL) settings
. config.pack ## include the package settings
## call scripts to install the package
## ig <...>
ig x11/gtk/UTIL gxyz another_package
!3. Compiling and testing
Call
./v5-pack2