Unix/GNU Windows

   
By Alexis Wilke
Started in Dec. 2006
   Home       Documentation       Download       Bugs   

Current
wpkg
Version:
0.5



Change Log
  

Building a package with wpkg is done with the --build option. Though, you can still create the different files by hand, it is recommended and prefered that you use the --build command line option from now on.

Creating a package a la Debian

To create a package as you would do with dpkg under Debian, you need to create:

  • A WPKG (or DEBIAN) folder where you put the different control files;
  • A set of directories and files to be installed on the target machines.

The WPKG directory must include a control file. This has to be a valid control file as defined in this documentation.

WARNING: The control file is rewritten by wpkg in order to remove the comments, empty lines and other wpkg acceptable artifacts. It is strongly recommanded that you keep a copy of the control file in a different place. wpkg creates a backup (control.bak) but there is no guarantee that it will work properly. The backup is never included in the output.

The other files that are usually put in the WPKG directory are as follow:

  • preinst — script executed before the installation begins
  • postinst — script executed after the installation begins
  • prerm — script executed before the removal begins
  • postrm — script executed after the removal begins

The md5sums file is automatically created and thus you do not need to include it. wpkg will silently overwrite it if it exists. wpkg never deletes this file.

At the same level as the WPKG directory, create other directories with the files you want to install. These directories form a structure similar to the structure used on the target machine. For instance, under MinGW, we install the runtime DLLs and executable under the directory named bin or mingw/bin. This is done by creating a bin or mingw/bin directory along the WPKG directory and putting the necessary dynamic libraries and executables in it.

Examples:
  WPKG/control
  WPKG/postinst
  bin/wpkg.exe
  bin/dirsize.exe
  share/wpkg-0.5/doc/index.html
  etc.

Once all of these directories and files are ready, use the following command to build your .deb package:

	wpkg --build <path> [<output.deb>]

The <path> points to the directory including the WPKG directory (i.e. the parent directory.) If an <output.deb> path and filename are specified, it is used. Otherwise the name is built from the name, version and architecture of the package (i.e. wpkg_0.5_win32-i386.deb). Notice that the package is created in the current directory. Using the <output.deb> extension let's you place the output in a different directory.

Creating packages from a .info file

Most of the time, when you create a project, you will endup with multiple packages. For instance, you probably want to create one runtime package (.exe and .dll), one documentation package (.html, .info, etc.), one library package (.h and .a), one source package (.c, .pas, .ada, etc.).

Because it is tedious to create one control file for each package with the correct description, version, and other common fields, plus create each package one by one making sure you install the right files in each one (and never install the same file twice), wpkg offers a way to create one control file and one directory tree which in general will help you reduce the number of errors dramatically. This special control file is the info file.

First, wpkg checks that all the files in each package do not overlap. This tells you that they will be installed only once and that you can install all the packages without having to force wpkg to do so.

Second, you create that single control file called the .info file. In general, you name it after your project and append the .info extension (i.e. wpkg.info). This control file includes definitions to let wpkg know how to build all the different packages for your project.

Please read the description of the .info file format for detailed information about it. In brief, it looks like a control file with extra fields. Especially, the Sub-Packages field is used to indicate the name of all the sub-packages to create from this .info file.

Third, you create a WPKG (or DEBIAN) sub-directory in each sub-package directory if you need to include special scripts such as the preinst, prerm, postinst and postrm scripts. If no special scripts or data is necessary, you do not need to create the WPKG directory, wpkg will create it for you.

Now you are ready to run wpkg to build your packages:

	wpkg --build <info file> <root tree>

Using the --build command with a plain file as the first parameter tells wpkg that it is used with a .info file. The second parameter (which is mandatory in this case) is the path to the root tree including all the sub-packages data and control files. It is also possible to indicate the root tree path in the .info file using the ROOT_TREE variable.

Creating a package by hand

Note that wpkg now supports the --build command line option that is the prefered method to create packages. Please, try to use it instead of creating packages by hand.

The sample coming with wpkg includes a script called build-script which shows each step of the process. There is the script:

 1:  #!/bin/sh
 2:  
 3:  tar cjf data.tar.bz2 usr
 4:  md5sum -b >md5sums `find usr -type f`
 5:  tar czf control.tar.gz control md5sums preinst postinst prerm postrm
 6:  echo 2.0 >debian-binary
 7:  rm -f sample.deb
 8:  ar cqS sample.deb debian-binary control.tar.gz data.tar.bz2

A .deb package includes at least three files: the debian-binary version specification, the control file and the data file.

The debian-binary file is used as a mark meaning that this file is a debian package (wpkg does not test the file extension, only this debian-binary file.) The content of the file is only one line of text with the version of the package (notice that this is not the version of what's inside the package!) followed by a new-line character. At this time, we support any version 2 (more precisly, we expect 2.0, 2.1, 2.2, etc.)

Creating the debian-binary file is very easy [line 6]:

 6:  echo 2.0 >debian-binary

The content of the .deb is described in the control file. The control file is a tarball composed of at least two files. wpkg supports tarballs being compressed using gzip or bzip2—however, dpkg does not support bzip2 compression of the control file. The corresponding extension must be used or the .deb will not be considered valid by wpkg or dpkg. The two files required are: control and md5sums. Without these two files, the .deb cannot be used for anything. The control file is a list of fields used to describe the package, especially its name, version and the architecture on which is can be installed (see the wpkg control file for more information.) The md5sums is a list of all the files in the data file with their md5sum. This can be used to make sure that each file is correct when being installed and later to check that installed files have not been modified (especially before being removed, though in version 0.5 the md5sums are ignored.)

The control file can also include scripts to be executed as the package is being installed (preinst and postinst) or removed (prerm and postrm.) All these scripts are also executed when a package is being up- or down-graded (not supported in version 0.1). These scripts are simple shell scripts expected to run with /bin/sh.exe (your PATH needs to be properly setup since wpkg will only use sh.exe as the command and not the full path.)

The creation of the control file is done with the following few steps.

  1. Create the md5sums file. This is archived using the md5sums tool. You need to have access to the tree of files being packaged. Use the find command to find all the files which need to appear in the md5sums. Notice that we do not include directories in the md5sums list. [line 4]
  2.  4:  md5sum -b >md5sums `find usr -type f`
    
  3. Second you need to create the control file, and if necessary, the preinst, postinst, prerm and postrm scripts. This is not part of the sample script since it is expected to be a one time human effort that cannot be automated.
  4. Note, however, that this process can be simplified with the use of default scripts that you concatenate to generate the final script.

  5. Finally, you create the control tarball with tar and compress the tarball. (note: if you write a script to run under MSYS, consider using two lines to create the tar file and one to compress it since the z and j options do not always work correctly under MSYS, especially older versions; also that way you can specify the compression level)
  6.  5:  tar czf control.tar.gz control md5sums preinst postinst prerm postrm
    
    or
     5:  tar cf control.tar control md5sums preinst postinst prerm postrm
     5:  gzip -9f control.tar
    

Finally, the data file is the tarball of all the files to be installed (and removed). The tarball can be compressed with gzip or bzip2 and must have the corresponding extension to work properly. The files saved in this tarball represent your binaries, configuration files, locale text files, manual pages, themes, etc. This is usually what you get when you type the following commands to build your software:

	#!/bin/sh
	# if any error, stop script
	set -e
	configure --prefix=/mingw
	make
	make prefix=`pwd`/BUILD install-strip
	cd BUILD
	# generate data tarball for wpkg
	tar czf ../data.tar.gz *

These files are put in a tarball with their full path but usually without the starting / (it is valid to use "./"). Under the MSYS/gnuwin32 system, most user files are expected to be installed under /mingw. However, wpkg root path is /. If the package has files to be installed under /usr, they will instead be placed under /mingw (which is somewhat contrary to what MSYS does since MSYS considers /usr to be equivalent to /.). So for instance, if you create a package with a file in: /usr/bin/my-app.exe, it will be installed as: /mingw/bin/my-app.exe.

Rational: We expect win32 packages to use the proper path, but since it will be possible to install debian packages which are not architecture specific, it is important to include this conversion.

In our sample script, line 3 presents the creation of the tarball compressed with bzip2 and specifically packaging the usr directory.

 3:  tar cjf data.tar.bz2 usr

Now we have all the elements necessary for the .deb file so we can create it. To create the .deb file you need the ar tool (archive tool used under Unix to create static libraries.) Because this archiver will usually extend an existing file, you must make sure to delete the file if it exists before to recreate it. The file is created using the cqS options (c—create, q—quick, S—no symbol table) followed by the name of the output .deb, and then the debian-binary file which must be the first file added to the archive. The other files can appear in any order though it is usual to put the control file before anything else.

 7:  rm -f sample.deb
 8:  ar cqS sample.deb debian-binary control.tar.gz data.tar.bz2

You can use the following command to verify that you got the right files in your package.

	ar tv <package>.deb

It is possible to include extension files in a package. wpkg (like dpkg) ignores files added in the ar archive when their name start with an underscore (_). For instance, you could include a blog speaking about changes you made in your package but that you do not really want to have installed, yet you still want people to be able to access that file... then name it _blog and add it to the ar command line. Users can extract such files using the --extract or --vextract command line flags.

	ar cqS sample.deb debian-binary control.tar.gz data.tar.bz2 _blog

Known Bugs

The --build option makes use of a temporary directory to temporarily save the control.tar.gz, data.tar.gz and debian-binary files in a sub-directory. wpkg needs to be able to create that sub-directory or it will fail building the packages. If you have problems with the default temporary folder, try the --tempdir option to specify a directory you have access to and is readable and writable by you (i.e. $HOME/tmp).

Note that the sub-directory is named wpkg-<process id> which should be unique.