For Packagers: Packaging Standards - Package Descriptions

[JohnB316]

From time to time it is good to be reminded of some of the items that make a good package. This post will cover the package description.

1) The package description - this is extremely important. One-liners are not really sufficient. A good Slack/VL package should have a description like this one:

Code:

seamonkey: SeaMonkey (an open-source web browser suite)
seamonkey:
seamonkey: The SeaMonkey browser suite.  SeaMonkey features a state-of-the-art
seamonkey: web browser and powerful email client, as well as a WYSIWYG web page
seamonkey: composer, a calendar and a feature-rich IRC chat client. For web
seamonkey: developers, mozilla.org's DOM inspector and JavaScript debugger tools
seamonkey: are included as well.
seamonkey:
seamonkey: Visit the SeaMonkey project at this URL:
seamonkey:   http://www.mozilla.org/projects/seamonkey/
seamonkey:

The key points to note about a good description are:

1) The package description is limited to 11 lines maximum. This is a Slackware standard that we need to keep for compatibility with the packaging tools.

2) The first line of the description gives the package name as well as a basic description of what the package is. This first line is very important, because it shows up in slapt-get and gslapt when the repository packages list is parsed. It is also important, because it tells the person who may want to install it the type of package it is.

3) The second line of the description is blank. This is a Slackware package standard that we need to enforce for compatibility with the standard packaging tools.

4) The last nine lines of the description give more information about the package. Typically you will see these lines when a package is being installed, whether by slapt-get, gslapt or the installpkg/upgradepkg commands. They should give additional information about the package.

How to Create a Package Description

If you are using checkinstall to create your packages, you will need to create a text file with the descrption before you call checkinstall to package things. The text file needs to be called description-pak, and it needs to be at the top level of your source build tree. Using the Seamonkey example above, here is how it would look as a description-pak file:

Code:

SeaMonkey (an open-source web browser suite)

The SeaMonkey browser suite.  SeaMonkey features a state-of-the-art
web browser and powerful email client, as well as a WYSIWYG web page
composer, a calendar and a feature-rich IRC chat client. For web
developers, mozilla.org's DOM inspector and JavaScript debugger tools
are included as well.

Visit the SeaMonkey project at this URL:
  http://www.mozilla.org/projects/seamonkey/

The description-pak file doesn't need the extra "seamonkey:" at the beginning of each line, as it will be added when checkinstall does its thing. However, you will need to put returns at the end of each line to make sure that lines are no longer than around 60 characters.

If you are packaging by hand or via SlackBuild scripts that don't invoke checkinstall, the description file needs to be called slack-desc. It goes into the install directory at the top of the package tree. The linuxpackages.net site has a very handy slack-desc creator that will do a lot of the dirty work for you. You can find it at http://www.linuxpackages.net/slackcreator.php.

Finally, there's the old stand-by slack-desc template, again for those of you who package things either by hand or via SlackBuild scripts that don't invoke checkinstall. Again, using the Seamonkey example, here it is as a template (because it was "borrowed" from Papa Slack):

Code:

# HOW TO EDIT THIS FILE:
# The "handy ruler" below makes it easier to edit a package description.  Line
# up the first '|' above the ':' following the base package name, and the '|'
# on the right side marks the last column you can put a character in.  You must
# make exactly 11 lines for the formatting to be correct.  It's also
# customary to leave one space after the ':'.

         |-----handy-ruler------------------------------------------------------|
seamonkey: SeaMonkey (an open-source web browser suite)
seamonkey:
seamonkey: The SeaMonkey browser suite.  SeaMonkey features a state-of-the-art
seamonkey: web browser and powerful email client, as well as a WYSIWYG web page
seamonkey: composer, a calendar and a feature-rich IRC chat client. For web
seamonkey: developers, mozilla.org's DOM inspector and JavaScript debugger tools
seamonkey: are included as well.
seamonkey:
seamonkey: Visit the SeaMonkey project at this URL:
seamonkey:   http://www.mozilla.org/projects/seamonkey/
seamonkey:

I hope this is helpful. Feel free to ask any questions you may have. Also take a look at the packaging documentation at linuxpackages.net, as it is very good. Finally, if you use checkinstall, please take the time to read its documentation so that it is used correctly.

Cheers,
John

[Kocil]

Just copy paste from my postings ...

The "template" we have been using since VL SOHO 5.0 looks like this:

Code:

pkgname: pkgname (pkg short-description about 40 chars max)
pkgname:
pkgname: pkg long desciption, about 60 chars per line, about 10 lines max.
pkgname:
pkgname: Website: http://www.thepackage.org
pkgname: License: GNU GPL
pkgname: Author: the hacker

------------------------------------------
BUILDDATE:  Tue Oct 31 07:28:06 WIT 2006                                       
HOST     :  Linux 2.6.18_s i686                                                 
DISTRO   :  Slackware 11.0.0                                                   
CFLAGS   : -O2 -mtune=i686 -march=i586                                         
CONFIGURE: --prefix=/usr/X11R6   

The first section, marked by "pkgname:" in the beginning of each line, contains the main info:

pkgname : should be correct as is
short-description : these will be taken by pkgtools, VL installer, slaptget in the list
long-description : will be shown by gslapt and pkgtools in the detailed view
website: THIS IS A MUST as a minimun requirement to comply with GNU GPL,
      since VL does not release source code
license: put the appropriate one. Usually GNU GPL but might be BSD, APL, or even propriatery.
author: respect the work of others please.


The second section, after the --------------------- line, is the compilation info.
These are also required to comply with GPL (especially the CONFIGURE:).
This info should be inserted automatically by checkinstall and vectelopment system,
but only if properly setup and used.

[JohnB316]

As far as the slack-desc template given above, it's a good one. In fact, when I write my build scripts, I add a section to them to generate the additional build information similar to that in the template above. When space is available, I also put in the home page for the program. However, putting the web site with the original source in the slack-desc file by itself does not relieve VL of its obligation ito provide the source code for any GPL software we package for distribution. The GPL is clear that we MUST include the entire text of the license in any packages of GPL'd software we distribute. It's also clear that we must make source available. The situation with Mepis illustrated this very plainly - see http://www.mepis.org/node/10725.

That's why we now have a source tree in the veclinux-5.8 and veclinux-current branches. And that's also why packagers are required to upload source code tarballs, as well as any buildscripts they used to build packages, including patches, slack-desc files, etc., much as Papa Slack does in its source tree.  I am not a lawyer, but I believe it's the right thing to include source code in our repository for any GPL programs we distribute, regardless of whether sources are available from Papa Slack, etc.

FWIW,
John

[M0E-lnx]

Just to clear things up (for me at least ).... I understand the slack-desk or description-pack file (whichever one is used) should contain 11 lines max...

Does that mean slapt-get/gslapt can only displayt 11 lines even if the file contains more than that?...
If that's true, then that means that everything in the section under the dotted like in the above example wouldn't show up during installation anyway (ie, the config options and all that good stuff).... with that said, should that information be included within the first 11 lines of the file, or is it ok if they don't show up, so long as they're in the file?

[JohnB316]

Just to clear things up (for me at least ).... I understand the slack-desk or description-pack file (whichever one is used) should contain 11 lines max...

Does that mean slapt-get/gslapt can only displayt 11 lines even if the file contains more than that?...
If that's true, then that means that everything in the section under the dotted like in the above example wouldn't show up during installation anyway (ie, the config options and all that good stuff).... with that said, should that information be included within the first 11 lines of the file, or is it ok if they don't show up, so long as they're in the file?

Slapt-get/gslapt/installpkg/upgradepkg will only show the actual package description. They won't show the "handy ruler" from Papa Slack's template, nor will they show build information.

It's better for the build information to be appended to the end of the slack-desc file. ;-)

HTH,
John

[The Headacher]

It's better for the build information to be appended to the end of the slack-desc file.

It seemed like a good idea, but I found a reason to disagree now .

Eventhough the package will include the info, it will be 'lost' after installing. It doesn't show up anywhere AFAIK. Today I had to download a package that was already installed on my box just to explode it and look at the configure options I should use in slack-desc. Can we not include a "VL-packaging" file or something like that? You know, a simple textfile you can include in doc-pak (if you're using checkinstall that is) ?

Or, could the makeinfo-slapt script be modified to include this info in either the .meta file or the .txt file ( if it was in the slack-desc in the first place of course).

[edit]
As far as I know, there isn't a way to add lines that won't be shown to slack-desc when using checkinstall, so you'd need to explodepkg every package you make to add some lines nobody will ever see..... and then repackage it. Please correct me if I'm wrong.
[/edit]

[JohnB316]

---snip---
Or, could the makeinfo-slapt script be modified to include this info in either the .meta file or the .txt file ( if it was in the slack-desc in the first place of course).

[edit]
As far as I know, there isn't a way to add lines that won't be shown to slack-desc when using checkinstall, so you'd need to explodepkg every package you make to add some lines nobody will ever see..... and then repackage it. Please correct me if I'm wrong.
[/edit]

The makeinfo-slapt script in the VL 5.8 repository already does this by generating a .meta file for a package. The .meta file includes the package description as well as the dependencies, assuming a slack-required file was found in the package. Here is the .meta file for the minicom package in the VL 5.8 extra repository:

Code:

PACKAGE NAME:  minicom-2.2-i586-1vl58.tlz
PACKAGE LOCATION:  ./base-apps
PACKAGE SIZE (compressed):  198 K
PACKAGE SIZE (uncompressed):  910 K
PACKAGE MD5: e9cb7a2b540d115eab7dc9f3208735de  ./base-apps/minicom-2.2-i586-1vl58.tlz
PACKAGE REQUIRED:  ncurses >= 5.5,bash >= 3.1.017
PACKAGE CONFLICTS: 
PACKAGE SUGGESTS: 
PACKAGE DESCRIPTION:
minicom: Minicom (TTY mode communications package ala Telix)
minicom:
minicom: Minicom is a communications program that resembles the MSDOS Telix
minicom: somewhat. It has a dialing directory, color, full ANSI and VT100
minicom: emulation, an (external) scripting language and more.
minicom:
minicom: Author:     Miquel van Smoorenburg <miquels@cistron.nl>   (1991-1996)
minicom: Maintainer: Adam Lackorzynski <adam@os.inf.tu-dresden.de> (since 2003)
minicom: http://alioth.debian.org/projects/minicom/
minicom: GNU GENERAL PUBLIC LICENSE, Version 2, June 1991
minicom:

The makeinfo-slack script in the VL 5.8 repository will extract build information from a slack-desc file if it's already there and put it into a .txt file. Here is the example for minicom:

Code:

BUILDDATE: Mon Dic 11 08:10:00 EST 2006
HOST:      Linux 2.6.18.5 i686
DISTRO:    Vector Linux 5.8-RC2   11-04-2006

I think the script needs to be tweaked to read the rest of the information that's needed, like the arguments passed to the configure script. Better yet, we probably should do what the slacky.it packagers do. They package their slackbuild scripts, their slack-desc files and their slack-required, slack-conflicts and slack-suggests files into /usr/doc/package-version. Thoughts on this?

Cheers,
John

[The Headacher]

They package their slackbuild scripts, their slack-desc files and their slack-required, slack-conflicts and slack-suggests files into /usr/doc/package-version. Thoughts on this?

That would basically mean I could put my used options etc in the doc-pak directory. Anything in there goes into /usr/doc/package-version by default.

Until checkinstall can do what you proposed I'd like to just add some file called VL-packaging or something like that to doc-pak in which I write I used checkinstall + used configure options or something, since the rest will be created by checkinstall.

[edit]
I just realized checkinstall isn't some script created by a VL hacker, but a 3d party program that happens to work great for us. I suppose
checkinstall will not do aforementioned actions ever unless the authors are asked to incorporate these functions.
[/edit[

I was thinking something like this:

Code:

This package was created by checkinstall 1.6.0 on {date }

Packaged for and on VL 5.8 Standard 'gold'.

the following command was used to configure the sources:
./configure --prefix=/usr

Packaged by:
Jacco "The Headacher" Kramer  (Email@adress_here)

Is that alright by you?

[edit 2]
I could also add that info to the description-pak file and be done with it. It will be world visible, but at least the info is there and nothing really needs to be changed and we won't need to explodepkg or write scripts or whatever.

[JohnB316]

Here is the code I use to get build information into the slack-desc file via traditional SlackBuild scripts after I copy the slack-desc from my source directory into the package tree:

Code:

#
# append build information to the end of the slack-desc file
#
cat >> $PKG/install/slack-desc << EOF

#----------------------------------------

BUILDDATE: `date`
PACKAGER:  $VL_PACKAGER
HOST:      `uname -srm`
DISTRO:    `cat /etc/vector-version`
CFLAGS:    $SLKCFLAGS
CONFIGURE: `awk "/\.\/configure\ /" $TMP/$NAME-$VERSION/config.log`

EOF

This works for 99% of packages that write the configuration output to config.log. Here is the slack-desc file for a package of amaroK that was recently built for the repo:

Code:

amarok: amaroK (the audio player for KDE)
amarok:
amarok: amaroK provides a simple drag and drop interface,
amarok: that really makes playlist handling easy.
amarok:
amarok: HOME PAGE: http://amarok.kde.org
amarok: LICENSE:   GNU GPL
amarok:
amarok:
amarok:
amarok:
#----------------------------------------

BUILDDATE: Fri Jan 12 01:11:36 EST 2007
PACKAGER:  JohnB316
HOST:      Linux 2.6.18.5 i686
DISTRO:    Vector Linux 5.8 Standard   12-16-2006
CFLAGS:    -O2 -march=i586 -mtune=i686
CONFIGURE:   $ ./configure --prefix=/opt/kde --program-prefix= --program-suffix= --disable-mysql --disable-postgresql --without-included-sqlite --without-nmm --without-helix i486-slackware-linux

Since checkinstall is a bash script (a rather complex one at that), it should be possible to add a patch to it so that it generates this type of information.

HTH and FWIW,
John

[Joe1962]

Since checkinstall is a bash script (a rather complex one at that), it should be possible to add a patch to it so that it generates this type of information.

Didn't you already patch it once back in SOHO 5.1? I remember it did that automagically.

[The Headacher]

I'd hate having to learn making Slackbuilds just to add some lines nobody ever reads ( I have to admit I forgot adding them to some of my packages), and even if they wanted to read them they'd still have to explode the package.

Is it alright if I just add the info needed to the description-pak so I can keep packaging with checkinstall?

[JohnB316]

Headacher,

It's possible to do that. You might want to take the code I posted and put it into a shell script to be run before checkinstall does its thing. You'll need to adjust some things to fit your building style, but here goes:

Code:

#!/bin/sh

export VL_PACKAGER="The Headacher"

#
# append build information to the end of the description-pak file
# Run this script BEFORE running checkinstall and after make is done.
#
cat >> description-pak << EOF

#----------------------------------------

BUILDDATE: `date`
PACKAGER:  $VL_PACKAGER
HOST:      `uname -srm`
DISTRO:    `cat /etc/vector-version`
CFLAGS:    $CFLAGS
CONFIGURE: `awk "/\.\/configure\ /" config.log`

EOF

The way this script is set up, it assumes that you are calling it from the top of the build tree, which is where the config.log is 99% of the time.

HTH,
John

P.S.: The advantage to automating the generation of this kind of detail stuff is tremendous. ;-)

[Joe1962]

I'd hate having to learn making Slackbuilds just to add some lines nobody ever reads...

Believe me, it's very important for your fellow packagers (even if some of them don't know that yet). I've been needed this info lately from several packages and it wasn't there... . If you have trouble building a package that somebody else built an earlier version of, or you need to rebuild one to add a config switch or extra functionality (new dep), then you'll get my point. It's also needed when checking if a package was built with the proper switches to replace an older one without breaking other packages or future app builds. This last is specially valid for lib updates.

[easuter]

Headacher,

It's possible to do that. You might want to take the code I posted and put it into a shell script to be run before checkinstall does its thing. You'll need to adjust some things to fit your building style, but here goes:

Code:

#!/bin/sh

export VL_PACKAGER="The Headacher"

#
# append build information to the end of the description-pak file
# Run this script BEFORE running checkinstall and after make is done.
#
cat >> description-pak << EOF

#----------------------------------------

BUILDDATE: `date`
PACKAGER:  $VL_PACKAGER
HOST:      `uname -srm`
DISTRO:    `cat /etc/vector-version`
CFLAGS:    $CFLAGS
CONFIGURE: `awk "/\.\/configure\ /" config.log`

EOF

The way this script is set up, it assumes that you are calling it from the top of the build tree, which is where the config.log is 99% of the time.

HTH,
John

P.S.: The advantage to automating the generation of this kind of detail stuff is tremendous. ;-)

Won't appending that to description-pak make the description longer than 11 lines?
On slack-desc its ok I guess, since it only reads the "name: " lines for the description.

[Joe1962]

The 11 line limit refers only to the description itself, that is the part that has the package name on the left side.