A Build System with wpkg

Introduction

The --build command allows a project manager to generate source packages that in turn can be used to generate binary packages for one's project.

Then, the --build command (again), from that source package, can compile the project and save the result in binary packages.

To achieve the feat, the packager makes uses of a few files in your project. Some of the files are mandatory (ChangeLog), others are optional although some are recommended (LICENSE, copyright, README.txt, etc.)

The control file is not required because all the necessary information to create the control file come from the ChangeLog and the other files. However, if you want to include a certain number of specialized fields, a control.info file becomes necessary.

Standalone Build

At first, you probably want to test that your package can indeed be built using wpkg.

The first step is to create the source package:

cd .../root/directory/of/your/project
wpkg --build

The --build by itself creates a source package of the package you are in. Note that if your package includes sub-packages (i.e. like wpkg includes the zlib package) then you probably want to make sure that all the files listed below exist either in the default location or in the root directory of your project1.

Once the source package was successfully created, it is time to try building the binary packages. This is very simple as well:

wpkg --root <path to a target> --build <package name>-src_<version>.deb

The .deb will have been created in the root directory of you project. Note that it is possible to place it somewhere else with --output-dir or --output-repository-dir. The --root option in that last command is required because the source package is going to be installed in the target before getting built. The system uses a rollback mechanism, so once the source package is dealt with, it automatically gets removed along with all the dependencies that got installed at the same time.

Once this last command works, you are done in terms of getting packages to build for this project.

IMPORTANT NOTE

At this point a source package can really only support one distribution. More than one would not work with the build process to binary packages as the --root option would require a different target for each distribution involved.

Updating a Source Package in your Repository

I suggest that you first try the build process as shown in the Standalone Build chapter. Once that works, you certainly want to include your project source package in your repository. This is the same command as before with the addition of the --output-repository-dir to indicate where your repository is:

wpkg --build --output-repository-dir .../my/repository

Note that the build command automatically creates all the required directories and saves the file where it is expected to go in the repository. Say for example that the Component field is set to main/tools/developers, then the source package ends up under:

.../my/repository/sources/main/tools

The path segment sources is automatically used as a replacement for the Distribution path and only the first two segments of the Component path are used.

Building Source Packages in a Repository

When you save your source packages (.deb files with the source code of your project) in your repository (see Updating a Source Package in Your Repository above) then you make it available to the repository build process via the following command:

wpkg --root <path to a target> --build .../my/repository

Note that we do not specify the sources directory, only the root of the repository. Also we need a --root option since the process is going to install source packages on that target before compiling them.

Assuming everything works according to plan, the <path to target> target will be returned as it was before you started the build (except for the database which keeps information about all installations.) This is the case whether or not the target succeeds its build process.

In this last process, the wpkg tool is 100% in charge of getting everything compiled, linked, installed for packaging, and packaged. Assuming everything works as expected, the result is the generation of binary packages of all the packages that are considered out of date, in the order as defined by the different package dependencies.

Note that if your target system has packages already installed, and those packages are in conflict with some of the packages that need to be compiled, then an error will occur at the time the system attempts to install those packages and the process will end. At this point you should make use of pretty much empty targets to increase the changes for this process to work.

IMPORTANT NOTE

It is important to note that at this point the system is not actually capable of handling more than one Distribution. The fact is that the target has to be using the correct distribution information, has had only packages from the same distribution installed in it, to work as expected. At this point this is not yet implemented. It is not unlikely that the system will be converted to automatically generate a target while doing the work on building source packages from a full repository.

Verification Steps

When creating a source package or a binary package, a large set of verifications check the input data. If anything is wrong, then an error is emitted and in the very end the package does not get saved.

What gets verified varies depending on how the package is being created. Since there are many different manners to create a package, these steps are not listed here. Note that for a source package you can list the verification steps with the following --help command line:

wpkg --help build-validations [--verbose]

Where --verbose is optional although that will give you a lot more details about the build steps.

Expected and Mandatory Files

The build process that creates a source package searches for a set of files in your source project. For the process to succeed some of these files must exist because these files are used and will be required to create the binary packages.

The filenames having a path that are listed in the table below are all relative from the root of the project. Files without a path may appear anywhere.

Fields Used from the ChangeLog File

The following table shows you the fields found in the ChangeLog file that are used to fill out fields in your control file.

Note that the source package accepts a list of distributions in its Distribution field. When building such a package, it gets built once per distribution found in its source package field.

• 1. In version 0.9.0, only files in the root directory are checked anyway, except for the few checked under wpkg/... and debian/...