list2pkg User Manual

You need a UNIX-like system for list2pkg to work. I have tested it on GNU/Linux, but other systems should work as well. You will also need root access on that system, since otherwise some ownership information might not be correctly preserved.

First, extract the list2pkg tarball and cd to it.

    $ tar -xf <Your .tar.gz file>
    $ cd <filename without .tar.gz>
  

If you have downloaded a release tarball, you should skip this step, since the html and man documentation has already been compiled for you. Otherwise, you can build the documentation by doing the following.

    $ ./helpers/build-doc.sh .
  

Installing list2pkg is very simple: you just have to invoke the install.sh script. First, you must choose where you want list2pkg installed. There are several variables you can give to the installation script to change that.

For example, to install list2pkg in a /usr prefix and the configuration file in /etc, you can do

    $ sudo PREFIX=/usr SYSCONFDIR=/etc ./install.sh
  

list2pkg takes two arguments: a list of the files that will belong to the package, and the package file we will create. List2pkg can also read a file list from standard input.

The format of a list is very simple: each line must contains the path to a file. This path can either be absolute (recommended) or relative to the directory from which list2pkg is invoked.

For this first example, we are going to use the list of files in filelist, which contains files in src. Feel free to look around.

    $ cat filelist
    $ ls -lR src
  

Note an important detail: if directories are given in the file list, they will not be copied recursively. This means that if the file /home is in your list, the package will not contain all files from all home directories, but only an empty /home directory.

list2pkg does not create the slackware package directly using the files that are given in the list. Instead, it copies those files to a temporary directory, do some adjustments there, and then call makepkg, which is Slackware's standard tool for package creation. This temporary directory is called the package tree directory by list2pkg .

If the user does not specify one, list2pkg creates a temporary directory in e.g /var/tmp, do its stuff and then remove the directory. If a package tree directory is given on the command line, the package structure is created inside instead, and it is not deleted at the end of the process.

Since you want to have a clue what is going on, we are going to use our own package tree directory.

    $ mkdir treedir
  

Following Slackware package's convention, the file name must have several information in it: the program's name, the version, the machine it was compiled for, and the creator's name along with the build version. Each of these fields must be separated by a dash. After this, the file extension, .tgz must follow. For more information on Slackware package naming, see The Perfect Package

As an example, we will use test-0.1-noarch-2usr.tgz as a package name.

It's now time to run the package-creating command

    $ sudo list2pkg --treedir=treedir --verbose filelist \
    test-0.1-noarch-2usr.tgz
  

The command should finish without errors, and a test-0.1-noarch-2usr.tgz file should have been created. Note that you need root privilege, because otherwise some owner and groups information might not be saved correctly. You can check that all files in the file list have been packed correctly (there are subtleties related to symlinks that are explained in the section called “Tricky cases”)

    $ tar --list --verbose -f test-0.1-noarch-2usr.tgz
    $ ls -lR treedir
  

Notice that an install/ directory with the necessary files has been created automatically. A minimalist install/slack-desc file was created, along with a doinst.sh script. This file deserves special attention. You should see some special commands between the #BEGIN: AUTO_LIST2PKG and #END: AUTO_LIST2PKG comments. Here is what mine looks like.

    #BEGIN: AUTO_LIST2PKG
    groupadd john || (if test $? -ne 9; then exit 1; fi)
    useradd john || (if test $? -ne 9; then exit 1; fi)
    chown -v john home/john || exit 1
    chgrp -v john home/john || exit 1
    chmod -v 755 home/john || exit 1
    chown -v john home/john/rep || exit 1
    chgrp -v john home/john/rep || exit 1
    chmod -v 775 home/john/rep || exit 1
    chown -v john home/john/rep/list2pkg || exit 1
    chgrp -v john home/john/rep/list2pkg || exit 1
    chmod -v 775 home/john/rep/list2pkg || exit 1
    chown -v john home/john/rep/list2pkg/testing || exit 1
    chgrp -v john home/john/rep/list2pkg/testing || exit 1
    chmod -v 775 home/john/rep/list2pkg/testing || exit 1
    chown -v john home/john/rep/list2pkg/testing/src || exit 1
    chgrp -v john home/john/rep/list2pkg/testing/src || exit 1
    chmod -v 775 home/john/rep/list2pkg/testing/src || exit 1
    chown -v john home/john/rep/list2pkg/testing/src/dir2 || exit 1
    chgrp -v john home/john/rep/list2pkg/testing/src/dir2 || exit 1
    chmod -v 775 home/john/rep/list2pkg/testing/src/dir2 || exit 1
    chown -v john home/john/rep/list2pkg/testing/src/dir1 || exit 1
    chgrp -v john home/john/rep/list2pkg/testing/src/dir1 || exit 1
    chmod -v 775 home/john/rep/list2pkg/testing/src/dir1 || exit 1
    chown -v john home/john/rep/list2pkg/testing/src/dir3 || exit 1
    chgrp -v john home/john/rep/list2pkg/testing/src/dir3 || exit 1
    chmod -v 775 home/john/rep/list2pkg/testing/src/dir3 || exit 1
    chown -v john home/john/rep/list2pkg/testing/src/dir3/dir4 || exit 1
    chgrp -v john home/john/rep/list2pkg/testing/src/dir3/dir4 || exit 1
    chmod -v 775 home/john/rep/list2pkg/testing/src/dir3/dir4 || exit 1
    #END: AUTO_LIST2PKG
  

(yes, my username is john). This script actually tries to recreate the owners and groups of the package's file, in case they do not exist on the target system. If you don't like this, you can use the list2pkg.conf file. See the section called “Users and groups handling” for more information.

As mentioned previously, the last step of list2pkg's creation of a package is to call makepkg . The --linkadd, --prepend and --chown options will be passed to it as is.

The install/ directory contains special files the slackware package management tools use to know how to install the package. The only file that must exist is the slack-desc file which gives a plain text description of the package. The slack-desc file which list2pkg creates is not especially good in that respect, so you might want to add your own slack-desc. To do that, you can use the --slack-desc option.

Another important file is the doinst.sh script, which gets executed after an installation. You can give your own custom doinst.sh script using the --doinst option. List2pkg will then append its own commands to it.

There are other files which can be in install/ that list2pkg does not support. Among them are files like slack-required or slack-conflicts. You can specify a directory with other files to copy to install using the --install-files option.

Once the package tree has been created, you might want to change a few details. For example, you might want to move all files in /usr/local to /usr in order to create a more “standard-compliant” package. List2pkg cannot do that directly, but it lets you run any script you want once the package tree directory has been created. The script will be invoked with the tree's path as first argument. The option to use is --changetree .

List2pkg handles file owners and groups in a peculiar way. For each of the package's file, it will check if its owner or group is “special”. A special owner or group name is not standard and matters enough for it to be re-created explicitly on any system the package is installed on.

If, for example you are creating a package for the cron daemon, you will want the cron user to be created on the target system, since some of the package's file will likely be set user id. On the other hand, the user root is generally not special, since it exists on virtually all UNIX-like systems.

Note that by default, all files in the package will have root as owner and group, meaning that files with non-special owners or groups will lose them and be installed with root owner and group on the target system. You can use the --no-root-ownership to prevent list2pkg from resetting the owner and group of every file to root.

By default, all user and group names are special except “root” . Any user or group beginning with “urpkg-” or “urpkgrp-” is also considered non-special, for reasons that will become obvious to you if you use urpkg . If you don't you shouldn't have any user or group name formatted that way.

According to TPP, the package's file name should be formatted in a very strict way. It should be made of several fields, including the program name, version number and architecture, all separated by dashes. List2pkg does not directly enforce this rule, because makepkg should output a warning if the name is not standard.

A good Slackware packages has its files in LSB standard locations. For example, no files should be in /usr/local because this is reserved for files that do not come from a package.

List2pkg does not do anything to enforce this for the moment. However, the script which can be given using the --changetree option can do it. Maybe in the future there will be standard scripts that list2pkg will run by default, and which will take care of fixing install locations inside the package tree. If you wrote a script you think could be included as a default script, please send it to me (see Chapter 4, Contributing to list2pkg).

Similarly, you can also write scripts to strip executable or gzip manpages.

I have tried hard to make list2pkg keep all permissions of all files and directories given in the file list. This way if the permissions are correctly set on your system, then those in the package should also be correct. If you think permissions are mishandled in some way by list2pkg, it's worth reporting the bug to me.

list2pkg automatically creates a standard slack-desc file. However, it is unable to put useful content in it, so you might want to create your own and add it using the --slack-desc option.

list2pkg tries to preserve a directory's permission and ownership. However, as previously mentioned, it will not copy its content if it is not explicitly given in the file list. For example, if the file list contains only /home, the package will only have an empty /home directory in it.

A symbolic link can be in the file list in two ways: it can be explicitly given, i.e as if it were a regular file, or it can be implicitly given, i.e as if it was part of the file's path.

For example, if /lib/libc.so.6 is a symbolic link to libc-2.7.so , and /lib/libc.so.6 is given on the file list, then it is considered an explicit symlink. However, if /usr/share/man is a symlink to /usr/man, and one file which is in the file list is /usr/share/man/man1/ld.1 , then it is considered an implicit symlink.

Explicit symlinks are copied as is to the package tree directory. Regardless of whether they are absolute or relative symlinks, they should be recreated on the target system.

On the other hand, path involving implicit symlinks are not created as they are given on the file list. Instead, all symbolic links are first resolved before the file's copy. Therefore, if we take our /usr/share/man/man1/ld.1 example, it will be created as /usr/man/man1/ld.1 in the package.