Howto create an add-on package for FREESCO 03x

FIXME 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. 8-)

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/
1) this is the hardest goal to obtain
2) study other packages how they've done it
 
freesco/howtos/how_to_create_an_add-on_package.txt (33496 views) · Last modified: 2005/09/14 00:49 (external edit)
 
Recent changes RSS feed Creative Commons License Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki