wpkg quick cheat sheet

The basics of wpkg are very easy to use. There are a few things to know about to get started with wpkg:


(1) Building a package

There are two methods to build a package, the normal Debian method that uses a WPKG/control file and the MacPorts method that uses a control.info file and generates multiple packages all at once.

Sample4 uses the normal Debian scheme:

wpkg --build test/sample4

Sample5 uses the MacPorts scheme:

wpkg --build test/sample5/control.info sample5

Note: The build capability does not use the database directory.


(2) Checking, Installing, Removing a package

Before you can handle any of those commands you want to create a database directory. By default, the database is created under /var/lib/wpkg (even under MS-Windows where the current drive will be used.) You may change the directory using the --root, --admindir, and --instdir on the command line, but unfortunately, in that case you have to do it all the time!1

So to quickly test under Linux, you probably want to create the directory /var/lib/wpkg and change the owner to yourself:

sudo mkdir -p /var/lib/wpkg
sudo chown alexis:alexis /var/lib/wpkg

Then the wpkg tool will save those information in that directory and you don't have to use sudo every time (this is if you are TESTING wpkg, if you are seriously using wpkg, you probably do not want to change that directory ownership, it should be root:root by default and use wpkg with sudo, just like you would dpkg.)

With that directory in place, all the CONTENTS flags will work, these use a sub-folder named tmp.

Now to get the installation and removal to also work, use the wpkg command to initialize the database:

wpkg --create-admindir sample.admindir

Please edit the sample.admindir to your liking (at time of writing it is compatible with sample4 but not sample5--you need to change the architecture and it is an exclusive choice.) At this time, running this command multiple times does NOT generate an error and does NOT replace the file. To change the administration director information, delete the core directory that appeared in the /var/lib/wpkg directory.

Now you can use the --install and --remove command line options! The install expects the name of the .deb file (and an optional --repository):

wpkg --install sample4_1.2.3_win32.deb

The remove command, however, makes use of the name of the package as found in the Package field. This means without the version, architecture and .deb extension:

wpkg --remove sample4

You can find the list of installed packages with the --list command line option.

Again, you can test using the --root, --admindir, and --instdir instead and place all that data in directories where you have permission instead of using the default wpkg directories. Note however that you will have to use the --root, --admindir, and --instdir each time you run wpkg2.


Packages are expected to be created for a specific distribution which name is indicated in their control file with the Distribution field. That same field is also defined in the sample.admindir. The Distribution field have to match for the installation to happen3. You may turn off the feature completely by removing the field from your version of sample.admindir (or edit the /var/lib//wpkg/core/control file and delete the Distribution: ... line from there.) This feature is used to protect software companies that have to run in a 100% controlled environment and thus which do not want to mix different distribution of software.


(3) Installing a package built by someone else?

Problems installing a package that was built by someone else? You are probably getting an error telling you that you should be an Administrator or root to do the installation. As long as you are installing an environment in your own world (under your home directory tree) then you can use the --force-file-info flag to permit the installation to proceed even though the chown command fails.

Note that this flag is not safe for a system wide installation as it may give other people access to files that should never be tempered with.

(4) Manageing and using a repository of packages

wpkg is capable of handling repositories of packages. A repository directory is a directory filled with .deb files that you built with the --build command line option. It can include sub-directories so as to have a directory structure.


wpkg --create-index <path>
wpkg --add-sources <source>
wpkg --update
wpkg --upgrade

For a repository to be recongized by wpkg, the packages must be listed in an index file (index.tar.gz). The index file is created with the --create-index command line of wpkg. There are several ways to create the index, note that the packager knows what to add and what to skip, so you can use * and it will work as expected. This is important because the --recursive would not otherwise work.

cd /path/to/repository
wpkg --create-index .

Once your repository is ready (has an index) you can add it to your target as a source. Sources are added using the --add-sources command line option. A source is simply a path to the repository, although it requires two directory levels minimum, so you may have to move your repository files one or two levels down if defined in the wrong place. The quick format of a sources.list line is:

type URI distribution component1 component2 ...

In case of wpkg, the type must be "wpkg" (later we will also support "wpkg-src".)

The URI is a path using the URI notation. For example, a filename starts with file:// and then the full path. Although backslashes (\) will work, it is suggested you only use forward slashes (/) in your source URIs. The distribution and components are sub-directory names that get appended to the URI. For example, to you could use a source on an HTTP server such as http://wpkg.m2osw.com/, with a distribution named m2osw and the first component main. The result is a full URI of http://wpkg.m2osw.com/m2osw/main. This means the index is searched in that directory. This source would be added with the following command:

wpkg --add-sources 'wpkg http://wpkg.m2osw.com/ m2osw main'

Once you added all your sources, you are ready to update the indexexs which means downloading the remote indexes to your local installation target (in the administration directory, under the core internal package.) This is done with the --update command line option:

wpkg --update

This command is fairly silent by default. Use the --verbose and --debug command line options to increase verbosity. To see the results at a later time, you may use the --update-info command line. This gives you information such as whether the transfer of the index file worked, when it ran, etc.

Now that you have the indexes on your local target, you can upgrade the packages that are installed. This is done with the --upgrade command line option:

wpkg --upgrade

If you want to know what will be upgraded, you may first run --upgrade-status. Also, it a goo idea to remember running --update before --upgrade.


  • 1. We are planning to support environment variables, configuration files, and plain and bold automatic discovery in a future release.
  • 2. A later version will be smart enough to find out information about your installation, but not the current version.
  • 3. Although not recommended, you may use the --force-any-distribution to force the installation of foreign distributions in your target system.