wpkg --install | -i

Table of Contents

• Introduction
• Validation
• Upgrading
• Reinstalling
• Downgrading
• Additional Options
• Pre-configuration
• Scripts
• Unpacking
• Configuring
• Remote Repository Installation
• Remote Files
• Directed Acyclic Graph
• Debugging

Introduction

The --install command allows a system administrator to install packages on a target system. Before installing anything, the command runs a battery of validations to make sure that the target system as it stands and the set of packages to be installed are fully compatible. If so the installation, which consists of unpacking the contents of the package and then configuring the package, happens one package at a time.

Validation

The list of validations is defined in the windows package details section. There are the important points to remember to get a successful validation:

• All dependencies of the newly installed packages must be satified
• None of the already installed packages and the new packages must be in any kind of conflict with each others
• None of the files of the new packages overwrite a file that already exists on the target1
• The target system must have enough free disk space for the installation to proceed
• The installation can proceed only if the target system is considered stable
• The architecture of the target and the packages to be installed match
• The version of the running packager is equal or larger than the version of the packager used to create the target system
• All the files in the package to be installed do not end up in the wpkg database area as indicated by the --admindir option
• All the user defined field validations are all satisfied

Upgrading

To upgrade a package that was installed earlier one uses --install again with the new version of the package. When an upgrade happens, the system runs the removal process on the previously installed package (prerm and postrm scripts, which means the old package gets deconfigured) and the installation process on the newly installed version (preinst and postinst which means the new packages gets configured.) Also the unpack process deletes files that were installed by the older version and that do not exist anymore in the new version of the package.

Upgrading is not similar to removing the existing package and installing the new package because it can happen even when the package being upgraded is depended upon: if package A depends on package B, you could not remove B without also removing A; with an upgrade capability you can upgrade B in place and thus you do not have to touch A in the process. Although note that the validation process may prevent the update of B if incompatible with the existing version of A.

Reinstalling

You can also re-install a package that was already installed. This is a way to repair some of the issues of the existing installation (i.e. some files were modified and their md5sum do not match the original.) When running tools, it may happen that some existing packages appear on the wpkg command line. If you want to avoid re-installing packages with such runs, use the --skip-same-version option.

Downgrading

Downgrading is very similar to Upgrading only that the version of the package decreases in the installation process.

Because the installation and removal scripts are generally not tested for downgrading a package, the system prevents downgrading by default. The --force-downgrade option must be used to allow downgrading.

Contrary to the Debian packager (dpkg), the windows packager (wpkg) validates the resulting installation of a downgrade. If it breaks some rules (invalid dependencies, conflicts, etc.) then wpkg fails the validation process before proceeding with the downgrade.

Additional Options

In many cases the administrator makes use of the --root option to define the target system root directory (and thus database directory.)

Many of the validation tests can be bypassed with the use of the --force-... options. For example, the --force-depends is used to install a package with missing dependencies.

When installing a package from a repository without knowing the list of dependencies one can use the --repository option. This allows wpkg to look for any missing packages and implicitly install them.

Pre-configuration

If some of the dependencies are defined in the Pre-Depends list of packages and those dependencies were unpacked but not yet configured, then they need to be configured before the process can continue. This happens before anything in link with the new packages happens (i.e. running scripts, unpacking, configuring.)

Scripts

Before unpacking anything, the installation process runs the preinst script with "install" as the parameter. If a previous version was installed and just removed (opposed to being purged) then the version of that old version is also specified on the command line:

preinst install [old-version]

More details can be found in the script section about the entire process in case the installation of a package is an upgrade, a downgrade, and what happens when errors occur.

Unpacking

While unpacking, wpkg makes a backup of the existing files before overwriting them. This happens whether you are upgrading or just replacing files that exist in your target system. If the unpack process fails before all the files get unpacked, then it attempts to restore all the files that were being replaced. This process tries to make it as safe as possible for the target system so as to keep it in a stable state. In case an error occurs, the system gives a list of the backup files so it may be possible to manual restore the target to a valid state.

Configuration files are extracted with a special extension added: <config-name>.wpkg-new. If a file with the same name already exists, it gets overwritten without asking for anything. It is expected that this special extension be reserved to the packager.

On failure, additional scripts (cancelation scripts) are run on the target system.

On success, the system proceeds with the configuration step of that package. If the configuration succeeds then the next package gets unpacked and configured.

Configuring

The configuration consists of two steps: renaming of the configuration file(s) and running the postinst script.

The configuration system handles the following configuration filenames:

• <config-name> -- the user supplied configuration filename (i.e. wpkg.conf)
• <config-name>.wpkg-new -- the name of a newly --unpack-ed configuration filename
• <config-name>.wpkg-old -- the name of an unmodified configuration file that was replaced by a newer version
• <config-name>.wpkg-user -- a configuration file that was saved by the --deconfigure command

For each configuration file, assuming that the file is called <config-name>, the process runs the following steps:

  1. Check whether a file named <config-name>.wpkg-user exists

    1.1 If not, go to step 2

    1.2 Check whether the file <config-name> exists

      1.2.1 If it exists, then check whether the file md5sum is the same as the md5sum of the original configuration file

        1.2.1.1 If not equal, then the process stops

        1.2.1.2 If equal, then the <config-name> file is renamed <config-name>.wpkg-old

    1.3 Rename the file <config-name>.wpkg-user as <config-name> (i.e. restore the configuration saved by the --deconfigure command.)

    1.4 Continue to step 2

  2. Check whether a file named <config-name>.wpkg-new exists

    2.1 If not, we are done, then process stops

    2.2 Check whether the file <config-name> exists

      2.2.1 If it exists, then check whether the file md5sum is the same as the md5sum of the original configuration file

        2.2.1.1 If not equal, then the process stops

        2.2.1.2 If equal, then the <config-name> file is renamed <config-name>.wpkg-old

    2.3 Rename the file <config-name>.wpkg-new as <config-name>

As you may notice, if both, a <config-name>.wpkg-user and a <config-name>.wpkg-new exist then we first restore with the <config-name>.wpkg-user and then we apply the algorithm just as if the <config-name>.wpkg-user did not exist at all. This is important because if you (a) do a --deconfigure, followed by (b) an --install to upgrade the package to a newer version, then you would want the <config-name>.wpkg-user version to be replaced by the newer configuration file available in the package assuming that you made no changes to that configuration file.

Also. even if the old configuration file was not modified it gets renamed as <config-name>.wpkg-old so you still get a chance to compare it with the newly installed configuration file. However, any <config-name>.wpkg-old file that exists before the process begins is likely to get deleted.

Finally, the configuration process runs the postinst script with "configure" and the package version as parameters. If that script fails an error is generated but no cancelation procedure is engaged.

postinst configure 1.2.3

Under MS-Windows it is not unlikely that the installation process happens in a graphical interface. For this reason, any post installation script should not attempt to interactively request the user to enter data or answer questions using a shell as there may not be a shell available. Instead, it is expected to open a dialog window2.

Remote Repository Installation

When installing from a remote repository that you installed using the --add-sources and updated with the --update command, you can install packages by specifying their name only, without any path, version, architecture, or extension:

wpkg --install package-name (this part does not work yet, you must use the full URI and dependencies are not automatically found from the sources.list repositories)

So in this case, package-name is just the name that appears in the Package field of your control file.

Remote Files

wpkg supports several protocols and the input package filenames can be fully qualified URIs. For example, you could get a file named boost_1.2.3_win32.deb from a webserver using the following:

http://www.example.com/software/repository/boost_1.2.3_win32.deb

This filename references the server www.example.com and uses the path /software/repository/boost_1.2.3_win32.deb on that remote server. This loads the specified package file from the example.com server and installs it in your target environment.

If you are using a WebServer that does not run on port 80 or 443 (in case of HTTPS) then you may specify the port after the domain name, separating both with a colon (:):

http://www.example.com:777/software/repository/wpkg_0.7.3_win32.deb

Similarly, you can use NetBIOS paths to connect and load files from other network drives. We accept two syntaxes for NetBIOS. The standard MS-Windows syntax (requires backslashes) and the URI syntax:

\\server\share\software\repository\boost_1.2.3_win32.deb
smb://server/share/software/repository/boost_1.2.3_win32.deb

The second syntax allows for you to enter a login and password (albeit not really safe, it can be useful when scripting installations.)

smb://username:password@server/share/software/repository/boost_1.2.3_win32.deb

You can also use smbs for a secure connection, which translate into the addition of @SSL at the end of the server name as in:

\\server@SSL\share\software\repository\boost_1.2.3_win32.deb

The --interactive option can be used to get the application to ask for the username and password instead of specifying them within the URI. It is generally more secure (i.e. does not show up in a ps -ef or equivalent,) but not very friendly when running a background process. For NetBIOS, you can also connect using IExplorer and then use wpkg.

Directed Acyclic Graph

Package dependencies are expected to represent a directed cyclic graph. By default, cyclic graphs are not allowed and this documentation often mentioned the fact that package graphs are acyclic.

In order to allow cyclic graph installations, you need to use --force-depends and even that may still fail installation of cyclic dependencies.

Debugging

When attempting to install a package with a full repository, failures can be difficult to understand. By default wpkg attempts to install the latest version of all the packages necessary for an installation. In that process, wpkg tries to create a valid installation graph. When multiple graphs are possible, it keeps the best one defined as the graph that uses newer packages. When no such graph is found or when multiple graphs are found and more than one look like the best graph, the process fails with an error. However, it does not directly give you information about the tests it attempted to resolve the installation graph.

For more information, you can request wpkg to generate a set of DOT files3. These are representations of the successful and failed installation graphs. This can give you information such as what package(s) are in conflict or which package has an incompatible version. By default wpkg does not create the DOT files. To turn that option on, use the --debug option with flag 04. Then you can convert the .dot files with the dot tool as in:

dot -Tpng -ograph.png install-graph-1.dot

Graph 0 (zero) represents the entire graph as is. It is generally not as useful to debug things unless you have missing dependencies.

• 1. Note that you can upgrade a package in which case the newer version is allowed to replace files from the older version of that package.
• 2. We are considering creating a resource like scheme that one can use cross platform to handle this problem.
• 3. DOT files can also be created with the deb2graph program.