Howto create an add-on package for FREESCO 03x
This article is work in progress…
To begin with, it's impossible to write a howto for add-on packages that covers all bases. In this acticle I will describe the making of a 03x package by going through the steps of an actual package I've made recently. Some packages are relatively easy to make, others are more of a “challenge”. I do most of my work from the command line, but you're welcome to use f.i. the Midnight Commander add-on package if you want.
— dingetje 2005/05/31 11:15
Introduction
This howto will use my recently made htp package as a basis. This is a fairly simple package, that contains both a client (htpdate) and a server (htpd).
Requirements
- Lightnings 'package' script, available at your local FREESCOSOft mirror.
- Shell access on a linux box. Your own FREESCO will do nicely
- The compiled binaries, libs, configs files, etc. In short the ready to package software 1)
- fairly good knowledge of linux shell scripting 2)
- half a brain
Step 1
I make all my packages in a seperate directory on the hard disk, so I can later always locate the correct package and make modifications if needed. The name of the directory will be the same as the final package, following the package name rules as described in the new http://3rd-party.freescosoft.com/ 3rd party site setup by Howler. The general rule for a 3rd party add-on package name is:
<packagename>-<version#>-<author>
or:
<packagename>_<version#>_<author>
Where version# is the version of the software your packaging, not the version of your package. The author name can be your real name, but in the FREESCO community this is usally the handle/nickname you're using on the FREESCO forums.
I'm packaging a port of the HTP software in this example, based on the 0.4.4 version, so now I know what my directory/package name should become:
[Linux] mkdir htp_0.4.4_dingetje [Linux] cd htp_0.4.4_dingetje/
Step 2
Now run Lightnings package script for the first time, giving it the name of the package you're about to make:
[Linux] package htp_0.4.4_dingetje
Extra text is helpfull inside of the ./pkg/rc/rc_htp
as well as inside of the ./htp_0.4.4_dingetje install script for helping
with understanding what each variable is used for and any
other options that are availible.
Do you want the extra text (y/n) ?y
The files and directories have been generated you can now edit them.
Packager version 2.3 made by Lightning 12/7/2003
Have fun
Lightning
The package script now has created the complete directory structure, as well as a startup script and installation script. Because this is a tutorial I've enabled the extra text, but when you get more experienced, you can answer 'n' to keep the scripts smaller.
Let's have a look what the script has done:
[Linux] ls -la drwxr-xr-x 3 root root 4096 Dec 30 22:06 . drwxr-xr-x 54 root root 4096 Dec 30 22:05 .. drwxr-xr-x 11 root root 4096 Dec 30 22:05 pkg -rw-r--r-- 1 root root 4274 Dec 30 22:06 htp_0.4.4_dingetje
This file htp_0.4.4_dingetje is the package installation script. We'll get to that script later on in this tutorial.
Step 3
As you may have guessed, the pkg directory must be used to hold the files you're going to package. Let's have a look what's in that directory:
[Linux] cd pkg [Linux] ls -la drwxr-xr-x 11 root root 4096 Dec 30 22:05 . drwxr-xr-x 3 root root 4096 Dec 30 22:06 .. drwxr-xr-x 2 root root 4096 Dec 30 22:05 bin drwxr-xr-x 2 root root 4096 Dec 30 22:05 etc drwxr-xr-x 2 root root 4096 Dec 30 22:05 home drwxr-xr-x 2 root root 4096 Dec 30 22:05 lib drwxr-xr-x 2 root root 4096 Dec 30 22:05 man drwxr-xr-x 2 root root 4096 Dec 30 22:06 rc drwxr-xr-x 2 root root 4096 Dec 30 22:05 sbin drwxr-xr-x 5 root root 4096 Dec 30 22:05 usr drwxr-xr-x 2 root root 4096 Dec 30 22:05 addons
“What's all this?” you may ask, I will attempt to explain:
| dir name | Comments |
|---|---|
| bin | Everything in this directory will get installed on the target system in the /pkg/bin directory and as such will be in the search PATH of the target system. It must be used to add (user) commands to the target system. My utils_1.0 package f.i. installs almost completely in this directory. |
| etc | Most servers require some form of config file that must end up in /etc directory. |
| home | This directory can be used to install stuff for user's home directories |
| lib | Most add-on packages require additional library files. These loadable library files (.so extension) must be placed in this directory. An exception is the libc.so.5 file, because this library is always in use on the target system. A special technique is required for upgrading the libc.so.5 file on the target system. I will discuss that later. |
| man | FREESCO lacks a true man page system, so do NOT place man formatted files in this directory, but rather readable ASCII text files with the package documentation. As a minimum add a few lines of text explaining what the package is for and maybe an internet URL where the original software can be found. |
| rc | This directory contains the startup/shutdown/firewall script of your package. Not all packages require such a script. A skeleton startup script is already made, but needs editing. |
| sbin | This directory is intended for secure binaries, typically only needed for the root account or so called daemon binaries. |
| usr | This directory is intended for add-on software in the /usr path. |
| addons | In this directory you can place addons for the web control panel. |
I've uploaded the complete package from my development work station (a zipslack 3.9 linux) to a directory of my FREESCO FTP server:
[Linux] cd bin [Linux] ls /mnt/ftp/htp-0.4.4/ MD5SUMS Makefile.in PLATFORMS README aclocal.m4 config.guess htpd.8 config.h.in config.sub configure configure.in getopt.c getopt.h gettimeofday.c gettimeofday.h htp.c htp.h htp.spec htpdate.8 htpd.8.in htpd.c htpd.conf htpd.conf.5 htpd.conf.5.in htpd.init.in htpdate.8.in htpdate.c install-sh VERSION settimeofday.c settimeofday.h win32.h config.log config.status Makefile htpd.init config.h htpdate htpd libconfig.so
Step 4
So lets start by placing the package files in the correct locations.
[Linux] cd bin [Linux] cp /mnt/ftp/htp-0.4.4/htpdate .
The htpdate is a user command to request the time via HTP protocol, so it's placed in the pkg/bin directory.
The htpd is the HTP time deamon that will sync the FREESCO clock via HTP protocol, so this is placed in the pkg/sbin directory.
Now I determine what libraries are required for this binary, by using the ldd (list library dependency) command:
[Linux] ldd htpd
libconfig.so => not found
libc.so.5 => /lib/libc.so.5 (0x40009000)
As you can see the libconfig.so lib is missing, so lets add that from the compiled package:
[Linux] cd ../lib [Linux] cp /mnt/ftp/htp-0.4.4/libconfig.so .
Since this is a loadable library file (.so extension) this lib file is placed in the pkg/lib directory.
[Linux] cd ../etc [Linux] cp /mnt/ftp/htp-0.4.4/htpd.conf .
The HTP daemon uses a config file htpd.conf which is expected in the /etc directory. By placing this sample file in the pkg/etc directory, the file will end up on the target system in the /etc directory (in ramdisk) via a symlink. Other than in 027 packages where the package author needs to take care of creating these symlinks, the package system of FREESCO 03x does this all automagically.
[Linux] cd ../man [Linux] edit htp.txt
This is the 'man' file of this package, so I use the editor and copy/paste some information about the package into a file called htp.txt.
Next I use the find command to list what's in my pkg directory:
[Linux] cd .. [Linux] find . ./addons ./bin/htpdate ./bin ./etc/htpd.conf ./etc ./home ./lib/libconfig.so ./lib ./man/htp.txt ./man ./rc/rc_htp ./rc ./sbin/htpd ./sbin ./usr/lib ./usr/local ./usr/share ./usr
Cool, looks like all the required files are in the right location. 
Step 5
Let's remove stuff we're not going to need in this package:
[Linux] rm -fr addons [Linux] rm -fr usr [Linux] rm -fr home [Linux] ls -la drwxr-xr-x 8 root root 4096 Dec 31 02:00 . drwxr-xr-x 3 root root 4096 Dec 30 22:06 .. drwxr-xr-x 2 root root 4096 Dec 31 00:41 bin drwxr-xr-x 2 root root 4096 Dec 31 00:41 etc drwxr-xr-x 2 root root 4096 Dec 31 00:41 lib drwxr-xr-x 2 root root 4096 Dec 31 00:43 man drwxr-xr-x 2 root root 4096 Dec 30 22:06 rc drwxr-xr-x 2 root root 4096 Dec 31 00:41 sbin
Step 6
Now lets look at the package startup/shutdown/firewall script:
[Linux] cd rc
[Linux] cat rc_htp
#!/bin/sh
#
# Template for htp version 0.4.4
#. /etc/system.cfg # Uncomment this only if it is needed.
. /etc/colors # Most packages don't need to read the system
# configuration.
fn2() { ps | sed -n '/ htp/P';
}
# check if program is actually running.
# Usually a <TAB> is required because otherwise this command will
# find it's self and always think your program is running.
# This will usually work where htp is the name of the program.
# But not always. Other parameters may be needed as well.
fn1() { # some internal function if needed.
# Usually this can be removed.
}
stp() {
[ "`fn2`" ] || return # if not running return
echo -n "Stopping htp... "
# killall service
= # This just prints done regardless. Which killall has no exit code.
}
str() {
[ "`fn2`" ] && return # if already running return
echo -n "Starting htp... "
# start service
= $? # test the exit code of the program
# Note: Not all programs will respond correctly to the $?
# if this happens just use =
}
edthlp() { cat <<~
Now you can edit the configuration file(s) for$CY htp$CW
After you are finished editing the configuration scripts.
Exit and save with$CG <ALT>+<X>$CW or$CG <F10>$CW and then$CG <y>
<ENTER>$CW to continue.
~
}
case "$1" in
firewall) # If you need any firewall settings, just changhe the
# PortNumber to the actual port and include the udp as well
# if needed.
# ipfwadm -I -a deny -P tcp -W $INET -D 0/0 PortNumber -o
# ipfwadm -I -a deny -P udp -W $INET -D 0/0 PortNumber -o
;;
boot) # do boot time hardware init. Not recommended for most programs
;;
setup) # This is called from setup or directly from a command line.
# It should automaticly edit all of the configuration files
# for you program.
#
# edthlp
# read t
# edit /etc/htp.cfg
# sync; sync
;;
start) str;;
stop) stp;;
restart)stp;str;;
newip) # called when system gets new IP/DNS address.
;;
status) if [ "`fn2`" ]
then echo "Running htp"; fn2
else echo No running htp
fi;;
esac
As you can see Lightning's package script has already created a skeleton script that only needs a bit of editing to get it right for this package.
[Linux] edit rc_htp <click>...<click>......<clickerty-click>....<coffee>...<mad keyboard click sounds>
The end result looks like this:
[Linux] cat rc_htp
#!/bin/sh
#
# Template for htp version 0.4.4
#. /etc/system.cfg # Uncomment this only if it is needed.
. /etc/colors # Most packages don't need to read the system
# configuration.
fn2() { ps | sed -n '/ htpd/P';
}
# check if program is actually running.
# Usually a <TAB> is required because otherwise this command will
# find it's self and always think your program is running.
# This will usually work where htp is the name of the program.
# But not always. Other parameters may be needed as well.
fn1() { # some internal function if needed.
# Usually this can be removed.
}
stp() {
[ "`fn2`" ] || return # if not running return
echo -n "Stopping htpd... "
killall htpd
= # This just prints done regardless. Which killall has no exit code.
}
str() {
[ "`fn2`" ] && return # if already running return
echo -n "Starting htpd... "
htpd
= $? # test the exit code of the program
# Note: Not all programs will respond correctly to the $?
# if this happens just use =
}
edthlp() { cat <<~
Now you can edit the configuration file(s) for$CY htpd$CW
After you are finished editing the configuration scripts.
Exit and save with$CG <ALT>+<X>$CW or$CG <F10>$CW and then$CG <y>
<ENTER>$CW to continue.
~
}
case "$1" in
firewall) # If you need any firewall settings, just changhe the
# PortNumber to the actual port and include the udp as well
# if needed.
# ipfwadm -I -a deny -P tcp -W $INET -D 0/0 PortNumber -o
# ipfwadm -I -a deny -P udp -W $INET -D 0/0 PortNumber -o
;;
boot) # do boot time hardware init. Not recommended for most programs
;;
setup) # This is called from setup or directly from a command line.
# It should automaticly edit all of the configuration files
# for you program.
#
edthlp
read t
edit /etc/htpd.conf
sync; sync
;;
start) str;;
stop) stp;;
restart)stp;str;;
newip) # called when system gets new IP/DNS address.
;;
status) if [ "`fn2`" ]
then echo "Running htpd"; fn2
else echo No running htpd
fi;;
esac
Lets zoom in a bit on some of these modifications:
fn2() { ps | sed -n '/ htpd/P';
}
This function is called to verify the htpd process is up and running. Because the generated code accidently checked for htp (because of the package name I've picked) instead of htpd, this needed correction.
killall htpd
This line is added in the stp() function to kill all htpd processes.
This next line is added in the str() function to start the htpd process. Because here also fn2() is called to check that the process isn't already running, I don't have to worry about the daemon getting started twice.
htpd
In the setup section I've removed the comments and changed the location of the actual config file, like so:
edthlp
read t
edit /etc/htpd.conf
sync; sync
Step 7
Almost done! Move up two directories, so I'm back in the directory where the new package installation script resides:
[Linux] cd ../..
[Linux] ls
pkg htp_0.4.4_dingetje
<code>
Now I run Lightning's //**package**// script again with the name of my package as 1st argument:
<code>
[Linux] package htp_0.4.4_dingetje
Unpacked size = 50
Packed size = 18
Version number [0.3.0 0.3.x]
Do you want to automaticly generate the uninstall section (y/n) ?y
************* The uninstall has been generated *******************
This uninstall is just a best guess and HAS to be reviewed.
******************************************************************
You need to review and probably edit install script - htp_0.4.4_dingetje
and put in the uninstall, postinstall, and preinstall sections.
Packager version 2.3 made by Lightning 12/7/2003
Step 8
The next step is to verify the installation script is correct, so I look through it in the editor:
[Linux] edit htp_0.4.4_dingetje
Because this is a fairly simple package, all I do is change the INFO text to a more appropriate message.
Step 9
Finally I move the BETA package to my web server and start with the tedious task of testing, testing, testing.
[Linux] ls -la drwxr-xr-x 3 root root 4096 Dec 31 02:03 . drwxr-xr-x 54 root root 4096 Dec 30 22:05 .. drwxr-xr-x 8 root root 4096 Dec 31 02:00 pkg -rw-r--r-- 1 root root 5028 Dec 31 02:06 htp_0.4.4_dingetje -rw-r--r-- 1 root root 19204 Dec 31 02:03 htp_0.4.4_dingetje.tgz [Linux] [Linux] cp htp* /www/beta/0.3.x/
